NTPDATE(8)

NAME
ntpdate - set the date and time via NTP

SYNOPSIS
ntpdate [ -bds ] [ -o version ] [ -a key# ] [ -e authdelay ] [ -k keyfile ] [ -p samples ] [ -t timeout ] server ...

DESCRIPTION
Ntpdate sets the local date and time by polling the Network Time Protocol server(s) on the host(s) given as arguments to determine the correct time. It must be run as root on the local host. A number of samples are obtained from each of the servers specified and the standard NTP clock filter and selection algorithms are applied to select the best of these. Typically, ntpdate can be inserted in the /etc/rc.local startup up script to set the time of day at boot time and/or can be run from time-to-time via cron(8). Note that ntpdate's reliability and precision will improve dramatically with greater numbers of servers. While a single server may be used, better performance and greater resistance to insanity on the part of any one server will be obtained by providing at least three or four servers, if not more.

Time adjustments are made by ntpdate in one of two ways. If ntpdate determines your clock is off by more than 0.5 seconds it will simply step the time by calling settimeofday(2). If the error is less than 0.5 seconds, however, it will by default slew the clock's time via a call to adjtime(2) with the offset. The latter technique is less disruptive and more accurate when the offset is small, and works quite well when ntpdate is run by cron (8) every hour or two. The adjustment made in the latter case is actually 50% larger than the measured offset since this will tend to keep a badly drifting clock more accurate (at some expense to stability, though this tradeoff is usually advantageous). At boot time, however, it is usually better to always step the time. This can be forced in all cases by specifying the -b switch on the command line. The -s switch tells ntpdate to log its actions via the syslog(3) facility rather than to the standard output, a useful option when running the program from cron(8).

The -d flag may be used to determine what ntpdate will do without it actually doing it. Information useful for general debugging will also be printed. By default ntpdate claims to be an NTP version 3 implementation in its outgoing packets. As some older software will decline to respond to version 3 queries, the -o version switch can be used to force the program to poll as a version 2 or 1 implementation instead.

The number of samples ntpdate acquires from each server can be set to between 1 and 8 inclusive using the -p switch. The default is 4. The time it will spend waiting for a response can be set using the -t switch, and will be rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN.

Ntpdate will authenticate its transactions if need be. The -a switch specifies that all packets should be authenticated using the key number indicated. The -k switch allows the name of the file from which the keys may be read to be modified from the default of /etc/ntp.keys. This file should be in the format described in xntpd(8). The -e option allows the specification of an authentication processing delay, in seconds (see xntpd(8) for details). This number is usually small enough to be negligible for ntpdate's purposes, though specifying a value may improve timekeeping on very slow CPU's.

Ntpdate will decline to set the date if an NTP server daemon (e.g. xntpd(8)) is running on the same host. When running ntpdate on a regular basis from cron(8) as an alternative to running a daemon, doing so once every hour or two will result in precise enough timekeeping to avoid stepping the clock.

FILES
/etc/ntp.keys  contains the encryption keys used by ntpdate.

SEE ALSO
xntpd(8)

HISTORY
Written by Dennis Ferguson at the University of Toronto

BUGS
The technique used for improving accuracy by compensating for clock oscillator errors sucks, but doing better would require the program to save state from previous runs.