diff options
Diffstat (limited to 'usr.sbin/xntpd/doc/ntpdate.8')
| -rw-r--r-- | usr.sbin/xntpd/doc/ntpdate.8 | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/usr.sbin/xntpd/doc/ntpdate.8 b/usr.sbin/xntpd/doc/ntpdate.8 new file mode 100644 index 000000000000..05be737fd88c --- /dev/null +++ b/usr.sbin/xntpd/doc/ntpdate.8 @@ -0,0 +1,185 @@ +''' $Header +''' +.de Sh +.br +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp +.if t .sp .5v +.if n .sp +.. +.de Ip +.br +.ie \\n.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +''' +''' Set up \*(-- to give an unbreakable dash; +''' string Tr holds user defined translation string. +''' Bell System Logo is used as a dummy character. +''' +.tr \(bs-|\(bv\*(Tr +.ie n \{\ +.ds -- \(bs- +.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch +.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch +.ds L" "" +.ds R" "" +.ds L' ' +.ds R' ' +'br\} +.el\{\ +.ds -- \(em\| +.tr \*(Tr +.ds L" `` +.ds R" '' +.ds L' ` +.ds R' ' +'br\} +.TH NTPDATE 8 LOCAL +.SH NAME +ntpdate - set the date and time via NTP +.SH SYNOPSIS +.B ntpdate +[ +.B -bdos +] [ +.B -a +.I key# +] [ +.B -e +.I authdelay +] [ +.B -k +.I keyfile +] [ +.B -p +.I samples +] [ +.B -t +.I timeout +] +server ... +.SH DESCRIPTION +.I 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, +.I ntpdate +can be inserted in the +.I /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 +.IR cron (8). +Note that +.IR 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. +.PP +Time adjustments are made by +.I ntpdate +in one of two ways. If +.I ntpdate +determines your clock is off by more than 0.5 seconds it will simply +step the time by calling +.IR 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 +.IR adjtime (2) +with the offset. The latter technique is less disruptive and more +accurate when the offset is small, and works quite well when +.I ntpdate +is run by +.I 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 -b +switch on the command line. The +.B -s +switch tells +.I ntpdate +to log its actions via the +.IR syslog (3) +facility rather than to the standard output, a useful option when +running the program from +.IR cron (8). +.PP +The +.B -d +flag may be used to determine what +.I ntpdate +will do without it actually doing it. Information useful for general +debugging will also be printed. By default +.I ntpdate +claims to be an NTP version 2 implementation in its outgoing packets. As +some older software will decline to respond to version 2 queries, the +.B -o +switch can be used to force the program to poll as a version 1 implementation +instead. +.PP +The number of samples +.I ntpdate +acquires from each server can be set to between 1 and 8 inclusive +using the +.B -p +switch. The default is 4. The time it will spend waiting for a +response can be set using the +.B -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. +.PP +.I Ntpdate +will authenticate its transactions if need be. The +.B -a +switch specifies that all packets should be authenticated using the +key number indicated. The +.B -k +switch allows the name of the file from which the keys may be read +to be modified from the default of +.I /etc/ntp.keys. +This file should be in the format described in +.IR xntpd (8). +The +.B -e +option allows the specification of an authentication processing delay, +in seconds (see +.IR xntpd (8) +for details). This number is usually small enough to be negligible for +.IR ntpdate 's +purposes, though specifying a value may improve timekeeping on very slow +CPU's. +.PP +.I Ntpdate +will decline to set the date if an NTP server daemon (e.g. +.IR xntpd (8)) +is running on the same host. When running +.I ntpdate +on a regular basis from +.IR 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. +.SH FILES +.nf +/etc/ntp.keys\0\0contains the encription keys used by \fIntpdate\fP. +.fi +.SH SEE ALSO +xntpd(8) +.SH HISTORY +Written by Dennis Ferguson at the University of Toronto +.SH 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. |