NETDATE(8L)NETDATE(8L)NAMEnetdate - set date and time by ARPA Internet RFC 868
SYNOPSISnetdate [ -v ] [ -l limit ] [ protocol ] hostname...
DESCRIPTION
Netdate takes a list of names of Internet hosts as arguments, selects
the one which supplies the best time, and sets the system time accord‐
ingly. 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 difference 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/init.d/boot.local, so
that the time will be set properly on system startup. It is also use‐
ful 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 moderate 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 circum‐
stances, 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 some‐
thing. 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 neighbor), 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 independently from dcn-gate, one
hopes. It is very likely that the time will be set to that one of
those three very accurate 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 sec‐
onds 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/log/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).
DIAGNOSTICS4th Berkeley Distribution 85/08/21 NETDATE(8L)