| netdate - set date and time by ARPA Internet RFC 868 |
| netdate [ -v ] [ -l limit ] [ protocol ] hostname... |
| Netdate takes a list of names of Internet hosts as arguments, 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 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. |
| 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. |
| 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 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. |
| 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. |
| 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. |
| 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. |
/etc/services for the time service port number /etc/protocols for the protocol numbers /var/log/wtmp to record time-setting |
| ARPANET Request for Comments 868, gettimeofday(2), date(1), WWV (USA): 2.5,5,10,15 MHz AM for Coordinated Universal Time (UCT). |