NAME
msntp - a SNTP utility (command and daemon)
SYNOPSIS
msntp [ -h | --help | -? ] [ -v | -V | -W ] [ -B [ period ] | -S | -q
[ -f savefile ] | [ { -r | -a } [ -P prompt ] [ -l lockfile ] ] [ -e
minerr ] [ -E maxerr ] [ -c count ] [ -d delay | -x [ separation ] ] [
-f savefile ] ] [ address(es) ] ]
DESCRIPTION
msntp 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 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).
Options
msntp recognizes the following options:
-h displays the syntax error message. If there are no other
arguments, it then stops; otherwise it then does what was
requested. --help and -? are synonyms.
-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.
-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.
-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.
-B period
indicates that it should behave as a server, broadcasting time
packets at intervals of period minutes (sic). Acceptable values
of period are from 1 to 1440 (a day), and the default (i.e. if
-B is specified but period is omitted) is 60. Naturally, this
will work only if the user has enough privilege.
-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.
-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.
The default is that it should behave as a client, and the following
options are then relevant:
-r indicates that the system clock should be reset by settimeofday.
Naturally, this will work only if the user has enough privilege.
-a indicates that the system clock should be reset by adjtime.
Naturally, this will work only if the user has enough privilege.
The default is to write the estimated correct local date and time (i.e.
not UTC) to the standard output in a format like ’1996 Oct 15
20:17:25.123 + 4.567 +/- 0.089 secs’, where the ’+ 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 ’ + 1.3
+/- 0.1 ppm’, and display this at roughly separation intervals (see
under the -x option for details).
-l lockfile
sets the name of the lock file to ensure that there is only one
copy of msntp running at once. The default is installation-
dependent, but will usually be /var/run/msntp.pid.
-e minerr
sets the maximum ignorable variation between the clocks to
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.
-E maxerr
sets the maximum value of various delays that are deemed
acceptable to 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.
-P prompt
sets the maximum clock change that will be made automatically to
maxerr. Acceptable values are from 1 to 3600 or 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 no will disable this and the correction will be made
regardless.
-c count
sets the maximum number of NTP packets required to 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.
-d delay
sets a rough limit on the total running time to delay seconds.
Acceptable values are from 1 to 3600, and the default is 15 if a
NTP host is specified and 300 otherwise.
-x separation
causes the program to run as a daemon (i.e. forever), and to
estimate and correct for the clock drift. 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 -x is specified but separation is omitted) is 300.
-f savefile
may be used with the -x option to store a record of previous
packets, which speeds up recalculating the drift after msntp has
to be restarted (e.g. because of network or server outages). In
order to restart the data, msntp must be restarted reasonably
soon after it died (within a few times the value of separation),
with the same value of the -c option, the same value of
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 /var/run/msntp.state.
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.
Constraints:
minerr must be less than maxerr which must be less than delay
(or, if a NTP host is not specified delay/count), and count must
be less than half of delay.
In update mode, maxerr must be less than prompt.
In daemon mode (i.e. when -x is specified), minerr must be less
than maxerr which must be less than separation (note that this
is in minutes, not seconds, but the numeric value is compared).
Note that none of the above values are closely linked to the limits
described in the NTP protocol (RFC 1305).
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:
msntp ntpserver.somewhere
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:
msntp -x ntpserver.somewhere > output 2>1
With suitable privilege, it can be run as a command or in a cron job to
reset the local clock from a reliable server, like the ntpdate and
rdate commands. For example:
msntp -a ntpserver.somewhere
It can also be run as a daemon to keep the local clock in step. For
example:
msntp -a -x ntpserver.somewhere > output 2>1
More information on how to use this utility is given in the README file
in the distribution. In particular, this man page does not describe
how to set it up as a server, which needs special care to avoid
propagating misinformation.
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.
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 tcpwrappers) should be
installed.
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.
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 cron job or put it in
inittab, to do this automatically.
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 -c option to a larger value may
help. Or it may not.
AUTHOR
msntp was developed by N.M. Maclaren of the University of Cambridge
Computing Service.