netdate
Hurricane Electric Internet Services
NAME
netdate - set date and time by ARPA Internet RFC 868
SYNOPSIS
netdate [ -v ] [ -l limit ] [ protocol ] hostname...
DESCRIPTION
Netdate takes a list of names of Internet hosts as argu-
ments, selects the one which supplies the best time, and
sets the system time accordingly. The invoker must be the
super-user for the time to be set. Protocol names (either
udp or tcp) may be interspersed with the host names, and
determine the protocol which will be used to connect to
the hosts whose names follow, up to the next protocol name
or the end of the arguments. The default protocol is udp.
The ``best'' time is chosen by polling the named hosts
once each to find their times and taking their differences
from the local host's time. These differences are used to
find the largest group of hosts whose times agree with
each other within a certain limit. The first host in the
largest group is picked as the best host. (The assumption
is that the hosts which are usually most accurate will be
named first.) That host is polled again and the local
host's time is set to the result. The chosen host's time
is checked on this second poll to insure that its differ-
ence from the local host's time has not varied more than
the limit from its difference at the first poll.
The default limit is five seconds. It may be set with the
-l option. The -v option causes the groups to be shown.
The host name localhost is recognized as a synonym for the
name of the local host, no network connection is made for
it, and its time difference is always zero. If localhost
is chosen as having the best time, the system time will
not be set. Hosts which do not respond are not counted in
the groups. If the limit is set to zero, the time is set
to that of the first host to respond and no other checking
is done. Supplying only one host name argument also sets
the limit to zero.
While the RFC868 protocol only returns 32 bits of data,
containing the time in seconds, netdate will accept an
extra 32 bits, containing microseconds (expected to be
accurate to no more than milliseconds). Delays on long
haul networks may make this extra precision useless, but
it is useful on local area networks. The extra precision
is not used on the first poll of a host, but it is used on
the second poll of the chosen host, if that host supplies
it.
EXAMPLE
The most accurate hosts are named first in each example.
Some such call on netdate should be put at the end of
/etc/rc.d/rc.local, so that the time will be set properly
on system startup. It is also useful to have a shell
script, e.g., /sbin/timehosts, which contains a call on
netdate with arguments appropriate to the local system, so
that it is easy to set the time manually.
netdate -l 30 udp dcn-gate tcp neighbor
Dcn-gate is a hypothetical host which usually keeps time
accurate to within milliseconds of Coordinated Universal
Time, but may occasionally be eight hours off. Neighbor
is a neighbor of the local host which keeps time with mod-
erate accuracy. The time will be set to that of dcn-gate
if that and neighbor agree to within thirty seconds, else
it will not be set at all. This is almost good enough for
most circumstances, but won't do when the local host's
time is known to be wrong (e.g., after a long downtime or
a bad crash) and must be set to something. If one of the
hosts named is inaccurate or not responding, there is a
problem.
netdate -l 30 udp dcn-gate tcp neighbor neighbor2
Only two of the three hosts named must agree on the time.
The time will still be set (to that of the first neigh-
bor), even if dcn-gate is far off as long as the two
neighbors agree. This is probably good enough for most
cases. One can arbitrarily gerrymander the vote for more
insurance (and less clarity), as in the following example.
netdate udp dcn-gate dcn1 tcp bbn-unix localhost neighbor
Here dcn1 and bbn-unix are more hypothetical very accurate
timekeepers, at least one of which keeps time indepen-
dently from dcn-gate, one hopes. It is very likely that
the time will be set to that one of those three very accu-
rate hosts, as long as at least two of them agree, or at
least one of them agrees with the neighbor or the local
host's time. If all the foreign hosts disagree, the time
will not be set, since localhost will be chosen as best.
netdate -l 3 localhost localhost udp dcn-gate dcn1 tcp bbn-unix
This example gives localhost two votes and declares it to
usually have the most accurate time. All three foreign
hosts must agree within three seconds and also differ from
localhosts by more than three seconds for the time to be
set. Thus the time will be set only if it really needs to
be.
FILES
/etc/services for the time service port number
/etc/protocols for the protocol numbers
/var/adm/wtmp to record time-setting
SEE ALSO
ARPANET Request for Comments 868, gettimeofday(2),
date(1), WWV (USA): 2.5,5,10,15 MHz AM for Coordinated
Universal Time (UCT).
DIAGNOSTICS
Hurricane Electric Internet Services
Copyright (C) 1998
Hurricane Electric.
All Rights Reserved.