NetBSD/usr.sbin/sntp/sntp.1

.\" $NetBSD: sntp.1,v 1.3 2003/12/09 11:15:18 drochner Exp $
.TH SNTP 1
.SH NAME
sntp \- a SNTP utility (command and daemon)
.SH SYNOPSIS
.B sntp
[
.B \-h
|
.B \-\-help
|
.B \-?
] [
.B \-v
|
.B \-V
|
.B \-W
] [
.B \-B
[
.I period
] |
.B \-S
|
.B \-q
[
.BI \-f " savefile"
] | [ {
.B \-r
|
.B \-a
} [
.BI \-P " prompt"
] [
.BI \-l " lockfile"
] ] [
.BI \-e " minerr"
] [
.BI \-E " maxerr"
] [
.BI \-c " count"
] [
.BI \-d " delay"
|
.B \-x
[
.I separation
] ] [
.BI \-f " savefile"
] ] [
.I address(es)
] ]
.SH DESCRIPTION
.PP
.I sntp
can be used as a SNTP client to query a NTP or SNTP server and either display
the time or set the local system's time (given suitable privilege).  It can be
run as an interactive command, in a
.I cron
job or as a daemon.  It can be run as a daemon to provide a SNTP server for
other clients.  NTP is the Network Time Protocol (RFC 1305) and SNTP is the
Simple Network Time Protocol (RFC 2030, which supersedes RFC 1769).
.SS Options
.PP
.I sntp
recognizes the following options:
.TP
.B \-h
displays the syntax error message.  If there are no other arguments, it then
stops; otherwise it then does what was requested.
.B \-\-help
and
.B \-?
are synonyms.
.TP
.B \-v
indicates that diagnostic messages for non-fatal errors and a limited amount of
tracing should be written to standard error.  Fatal ones always produce a
diagnostic.  This option should be set when there is a suspected problem with
the server, network or the source.
.TP
.B \-V
requests more and less comprehensible output, mainly for investigating problems
with apparently inconsistent timestamps.  This option should be set when the
program fails with a message indicating that is the trouble.
.TP
.B \-W
requests very verbose debugging output, and will interfere with the timing
when writing to the terminal (because of line buffered output from C).  Note
that the times produced by this are the corrections needed, and not the error
in the local clock.  This option should be set only when debugging the source.
.TP
.BI \-B " period"
indicates that it should behave as a server, broadcasting time packets at
intervals of
.I period
minutes (sic).  Acceptable values of
.I period
are from 1 to 1440 (a day), and the default (i.e. if
.B \-B
is specified but
.I period
is omitted) is 60.  Naturally, this will work only if the user has enough
privilege.
.TP
.B \-S
indicates that it should behave as a server, responding to time requests from
clients.  Naturally, this will work only if the user has enough privilege.
.TP
.B \-q
indicates that it should query a daemon save file being maintained by it.
This needs no privilege and will change neither the save file nor the clock.
.PP
The default is that it should behave as a client, and the following options
are then relevant:
.TP
.B \-r
indicates that the system clock should be reset by
.IR settimeofday .
Naturally, this will work only if the user has enough privilege.
.TP
.B \-a
indicates that the system clock should be reset by
.IR adjtime .
Naturally, this will work only if the user has enough privilege.
.PP
The default is to write the estimated correct local date and time (i.e. not
UTC) to the standard output in a format like
.BR "'1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs'" ,
where the
.B "'+ 4.567 +/- 0.089 secs'"
indicates the estimated error in the time on the local system.  In daemon mode,
it will add drift information in a format like
.BR "' + 1.3 +/- 0.1 ppm'" ,
and display this at roughly
.I separation
intervals (see under the
.B \-x
option for details).
.TP
.BI \-l " lockfile"
sets the name of the lock file to ensure that there is only
one copy of
.I sntp
running at once.  The default is installation-dependent, but will usually be
.IR /var/run/sntp.pid .
.TP
.BI \-e " minerr"
sets the maximum ignorable variation between the clocks to
.IR minerr .
Acceptable values are from 0.001 to 1, and the default is 0.1 if a NTP host is
is specified and 0.5 otherwise.
.TP
.BI \-E " maxerr"
sets the maximum value of various delays that are deemed acceptable to
.IR maxerr .
Acceptable values are from 1 to 60, and the default is 5.  It should sometimes
be increased if there are problems with the network, NTP server or system
clock, but take care.
.TP
.BI \-P  " prompt"
sets the maximum clock change that will be made automatically to
.IR maxerr .
Acceptable values are from 1 to 3600 or
.IR no ,
and the default is 30.  If the program is being run interactively in ordinary
client mode, and the system clock is to be changed, larger corrections will
prompt the user for confirmation.  Specifying
.I no
will disable this and the correction will be made regardless.
.TP
.BI \-c " count"
sets the maximum number of NTP packets required to
.IR count .
Acceptable values are from 1 to 25 if a NTP host is specified and from 5 to 25
otherwise, and the default is 5.  If the maximum isn't enough, the system needs
a better consistency algorithm than this program uses.
.TP
.BI \-d " delay"
sets a rough limit on the total running time to
.I delay
seconds.  Acceptable values are from 1 to 3600, and the default is 15 if a NTP
host is specified and 300 otherwise.
.TP
.BI \-x " separation"
causes the program to run as a daemon (i.e. forever), and to estimate and
correct for the clock drift.
.I separation
sets the minimum time between calls to the server in minutes if a NTP host is
specified, and between broadcast packets if not.  Acceptable values are from 1
to 1440 (a day), and the default (if
.B \-x
is specified but
.I separation
is omitted) is 300.
.TP
.BI \-f " savefile"
may be used with the
.B \-x
option to store a record of previous packets, which speeds up recalculating
the drift after
.I sntp
has to be restarted (e.g. because of network or server outages).  In order to
restart the data,
.I sntp
must be restarted reasonably soon after it died (within a few times the value of
.IR separation ) ,
with the same value of the
.B \-c
option, the same value of
.IR separation ,
in the same mode (i.e. broadcast or client), though the NTP servers need not
be the same for client mode, and with compatible values of other settings.
Note that the file will be created with the default ownerships and permissions,
using standard C facilities.  The default is installation-dependent, but will
usually be
.IR /var/db/sntp.state .
.PP
.B address(es)
are the DNS names or IP numbers of hosts to use for the challenge and response
protocol; if no names are given, the program waits for broadcasts.  Polling a
server is vastly more reliable than listening to broadcasts.  Note that a
single component numeric address is not allowed, to avoid ambiguities.  If
more than one name is give, they will be used in a round-robin fashion.
.PP
Constraints:
.IP
.B minerr
must be less than
.B maxerr
which must be less than
.B delay
(or, if a NTP host is not specified
.BR delay / count "),"
and
.B count
must be less than half of
.BR delay .
.IP
In update mode,
.B maxerr
must be less than
.BR prompt .
.IP
In daemon mode (i.e. when
.B \-x
is specified),
.B minerr
must be less than
.B maxerr
which must be less than
.B separation
(note that this is in minutes, not seconds, but the numeric value is compared).
.PP
Note that none of the above values are closely linked to the limits described
in the NTP protocol (RFC 1305).
.SH USAGE
The simplest use of this program is as an unprivileged command to check the
current time and error in the local clock.  For example:
.IP
.B sntp ntpserver.somewhere
.PP
It can be run as a unprivileged background process to check on the clock drift
as well as the current error; this will probably fail if the local clock is
reset while it is running.  For example:
.IP
.B sntp -x ntpserver.somewhere > output 2>\*[Am]1 \*[Am]
.PP
With suitable privilege, it can be run as a command or in a
.I cron
job to reset the local clock from a reliable server, like the
.I ntpdate
and
.I rdate
commands.  For example:
.IP
.B sntp -a ntpserver.somewhere
.PP
It can also be run as a daemon to keep the local clock in step.  For example:
.IP
.B sntp -a -x ntpserver.somewhere > output 2>\*[Am]1 \*[Am]
.PP
More information on how to use this utility is given in the
.I README
file in the distribution.  In particular, this
.I man
page does not describe how to set it up as a server, which needs special care
to avoid propagating misinformation.
.SH RETURN VALUE
When used as a client in non-daemon mode, the program returns a zero exit
status for success, and a non-zero one otherwise. When used as a daemon
(either client or server), it does not return except after a serious error.
.SH BUGS
The program implements the SNTP protocol, and does not provide all NTP
facilities.  In particular, it contains no checks against any form of spoofing.
If this is a serious concern, some network security mechanism (like a firewall
or even just
.IR tcpwrappers )
should be installed.
.PP
There are some errors, ambiguities and inconsistencies in the RFCs, and this
code may not interwork with all other NTP implementations.  Any unreasonable
restrictions should be reported as bugs to whoever is responsible.  It may
be difficult to find out who that is.
.PP
The program will stop as soon as it feels that things have got out of control.
In client daemon mode, it will usually fail during an extended period of
network or server inaccessibility or excessively slow performance, or when the
local clock is reset by another process.  It will then need restarting
manually.  Experienced system administrators can write a shell script, a
.I cron
job or put it in
.IR inittab ,
to do this automatically.
.PP
The error cannot be estimated reliably with broadcast packets or for the drift
in daemon mode (even with client-server packets), and the guess made by the
program may be wrong (possibly even very wrong).  If this is a problem, then
setting the
.B \-c
option to a larger value may help.  Or it may not.
.SH AUTHOR
.I sntp
was developed as "msntp" by N.M. Maclaren of the University of Cambridge Computing
Service.