| 1 | ''' $Header |
| 2 | ''' |
| 3 | .de Sh |
| 4 | .br |
| 5 | .ne 5 |
| 6 | .PP |
| 7 | \fB\\$1\fR |
| 8 | .PP |
| 9 | .. |
| 10 | .de Sp |
| 11 | .if t .sp .5v |
| 12 | .if n .sp |
| 13 | .. |
| 14 | .de Ip |
| 15 | .br |
| 16 | .ie \\n.$>=3 .ne \\$3 |
| 17 | .el .ne 3 |
| 18 | .IP "\\$1" \\$2 |
| 19 | .. |
| 20 | ''' |
| 21 | ''' Set up \*(-- to give an unbreakable dash; |
| 22 | ''' string Tr holds user defined translation string. |
| 23 | ''' Greek uppercase omega is used as a dummy character. |
| 24 | ''' |
| 25 | .tr \(*W-|\(bv\*(Tr |
| 26 | .ie n \{\ |
| 27 | .ds -- \(*W- |
| 28 | .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| 29 | .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| 30 | .ds L" "" |
| 31 | .ds R" "" |
| 32 | .ds L' ' |
| 33 | .ds R' ' |
| 34 | 'br\} |
| 35 | .el\{\ |
| 36 | .ds -- \(em\| |
| 37 | .tr \*(Tr |
| 38 | .ds L" `` |
| 39 | .ds R" '' |
| 40 | .ds L' ` |
| 41 | .ds R' ' |
| 42 | 'br\} |
| 43 | .TH NTPDATE 8 LOCAL |
| 44 | .SH NAME |
| 45 | ntpdate - set the date and time via NTP |
| 46 | .SH SYNOPSIS |
| 47 | .B ntpdate |
| 48 | [ |
| 49 | .B -bdos |
| 50 | ] [ |
| 51 | .B -a |
| 52 | .I key# |
| 53 | ] [ |
| 54 | .B -e |
| 55 | .I authdelay |
| 56 | ] [ |
| 57 | .B -k |
| 58 | .I keyfile |
| 59 | ] [ |
| 60 | .B -p |
| 61 | .I samples |
| 62 | ] [ |
| 63 | .B -t |
| 64 | .I timeout |
| 65 | ] |
| 66 | server ... |
| 67 | .SH DESCRIPTION |
| 68 | .I Ntpdate |
| 69 | sets the local date and time by polling the Network Time Protocol |
| 70 | server(s) on the host(s) given as arguments to determine |
| 71 | the correct time. It must be run as root on the local host. A number |
| 72 | of samples are obtained from each of the servers specified and the |
| 73 | standard NTP clock filter and selection algorithms are applied to select |
| 74 | the best of these. Typically, |
| 75 | .I ntpdate |
| 76 | can be inserted in the |
| 77 | .I /etc/rc.local |
| 78 | startup up script to set the time of day at boot time and/or can be run |
| 79 | from time\-to\-time via |
| 80 | .IR cron (8). |
| 81 | Note that |
| 82 | .IR ntpdate 's |
| 83 | reliability and precision will improve dramatically with greater numbers |
| 84 | of servers. While a single server may be used, better performance and |
| 85 | greater resistance to insanity on the part of any one server |
| 86 | will be obtained by providing at least three or four servers, if not more. |
| 87 | .PP |
| 88 | Time adjustments are made by |
| 89 | .I ntpdate |
| 90 | in one of two ways. If |
| 91 | .I ntpdate |
| 92 | determines your clock is off by more than 0.5 seconds it will simply |
| 93 | step the time by calling |
| 94 | .IR settimeofday (2). |
| 95 | If the error is less than 0.5 seconds, however, it will by default slew |
| 96 | the clock's time via a call to |
| 97 | .IR adjtime (2) |
| 98 | with the offset. The latter technique is less disruptive and more |
| 99 | accurate when the offset is small, and works quite well when |
| 100 | .I ntpdate |
| 101 | is run by |
| 102 | .I cron (8) |
| 103 | every hour or two. The adjustment made in the latter |
| 104 | case is actually 50% larger than the measured offset since this will |
| 105 | tend to keep a badly drifting clock more accurate (at some expense to |
| 106 | stability, though this tradeoff is usually advantageous). At boot time, |
| 107 | however, it is usually better to always step the time. This can be forced |
| 108 | in all cases by specifying the |
| 109 | .B -b |
| 110 | switch on the command line. The |
| 111 | .B -s |
| 112 | switch tells |
| 113 | .I ntpdate |
| 114 | to log its actions via the |
| 115 | .IR syslog (3) |
| 116 | facility rather than to the standard output, a useful option when |
| 117 | running the program from |
| 118 | .IR cron (8). |
| 119 | .PP |
| 120 | The |
| 121 | .B -d |
| 122 | flag may be used to determine what |
| 123 | .I ntpdate |
| 124 | will do without it actually doing it. Information useful for general |
| 125 | debugging will also be printed. By default |
| 126 | .I ntpdate |
| 127 | claims to be an NTP version 2 implementation in its outgoing packets. As |
| 128 | some older software will decline to respond to version 2 queries, the |
| 129 | .B -o |
| 130 | switch can be used to force the program to poll as a version 1 implementation |
| 131 | instead. |
| 132 | .PP |
| 133 | The number of samples |
| 134 | .I ntpdate |
| 135 | acquires from each server can be set to between 1 and 8 inclusive |
| 136 | using the |
| 137 | .B -p |
| 138 | switch. The default is 4. The time it will spend waiting for a |
| 139 | response can be set using the |
| 140 | .B -t |
| 141 | switch, and will be rounded to a multiple of 0.2 seconds. The default |
| 142 | is 1 second, a value suitable for polling across a LAN. |
| 143 | .PP |
| 144 | .I Ntpdate |
| 145 | will authenticate its transactions if need be. The |
| 146 | .B -a |
| 147 | switch specifies that all packets should be authenticated using the |
| 148 | key number indicated. The |
| 149 | .B -k |
| 150 | switch allows the name of the file from which the keys may be read |
| 151 | to be modified from the default of |
| 152 | .I /etc/ntp.keys. |
| 153 | This file should be in the format described in |
| 154 | .IR xntpd (8). |
| 155 | The |
| 156 | .B -e |
| 157 | option allows the specification of an authentication processing delay, |
| 158 | in seconds (see |
| 159 | .IR xntpd (8) |
| 160 | for details). This number is usually small enough to be negligible for |
| 161 | .IR ntpdate 's |
| 162 | purposes, though specifying a value may improve timekeeping on very slow |
| 163 | CPU's. |
| 164 | .PP |
| 165 | .I Ntpdate |
| 166 | will decline to set the date if an NTP server daemon (e.g. |
| 167 | .IR xntpd (8)) |
| 168 | is running on the same host. When running |
| 169 | .I ntpdate |
| 170 | on a regular basis from |
| 171 | .IR cron (8) |
| 172 | as an alternative to running a daemon, doing so once every hour or two |
| 173 | will result in precise enough timekeeping to avoid stepping the clock. |
| 174 | .SH FILES |
| 175 | .nf |
| 176 | /etc/ntp.keys\0\0contains the encription keys used by \fIntpdate\fP. |
| 177 | .fi |
| 178 | .SH SEE ALSO |
| 179 | xntpd(8) |
| 180 | .SH HISTORY |
| 181 | Written by Dennis Ferguson at the University of Toronto |
| 182 | .SH BUGS |
| 183 | The technique used for improving accuracy by compensating for clock |
| 184 | oscillator errors sucks, but doing better would require the program |
| 185 | to save state from previous runs. |