| 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> |
|---|
| 2 | <html> |
|---|
| 3 | <head> |
|---|
| 4 | <meta name="generator" content="HTML Tidy, see www.w3.org"> |
|---|
| 5 | <title>ntpdate - set the date and time via NTP</title> |
|---|
| 6 | </head> |
|---|
| 7 | <body> |
|---|
| 8 | <h3><tt>ntpdate</tt> - set the date and time via NTP</h3> |
|---|
| 9 | |
|---|
| 10 | <img align="left" src="pic/rabbit.gif" alt="gif"><a href= |
|---|
| 11 | "http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's |
|---|
| 12 | Adventures in Wonderland</i>, Lewis Carroll</a> |
|---|
| 13 | |
|---|
| 14 | <p>I told you it was eyeball and wristwatch.<br clear="left"> |
|---|
| 15 | </p> |
|---|
| 16 | |
|---|
| 17 | <hr> |
|---|
| 18 | <p>Disclaimer: The functionality of this program is now available |
|---|
| 19 | in the <tt>ntpd</tt> program. See the <tt>-q</tt> command line |
|---|
| 20 | option in the <a href="ntpd.htm"><tt>ntpd</tt> - Network Time |
|---|
| 21 | Protocol (NTP) daemon</a> page. After a suitable period of |
|---|
| 22 | mourning, the <tt>ntpdate</tt> program is to be retired from this |
|---|
| 23 | distribution</p> |
|---|
| 24 | |
|---|
| 25 | <h4>Synopsis</h4> |
|---|
| 26 | |
|---|
| 27 | <tt>ntpdate [ -bBdoqsuv ] [ -a <i>key</i> ] [ -e <i>authdelay</i> ] |
|---|
| 28 | [ -k <i>keyfile</i> ] [ -o <i>version</i> ] [ -p <i>samples</i> ] [ |
|---|
| 29 | -t <i>timeout</i> ] <i>server</i> [ ... ]</tt> |
|---|
| 30 | |
|---|
| 31 | <h4>Description</h4> |
|---|
| 32 | |
|---|
| 33 | <tt>ntpdate</tt> sets the local date and time by polling the |
|---|
| 34 | Network Time Protocol (NTP) server(s) given as the <i>server</i> |
|---|
| 35 | arguments to determine the correct time. It must be run as root on |
|---|
| 36 | the local host. A number of samples are obtained from each of the |
|---|
| 37 | servers specified and a subset of the NTP clock filter and |
|---|
| 38 | selection algorithms are applied to select the best of these. Note |
|---|
| 39 | that the accuracy and reliability of <tt>ntpdate</tt> depends on |
|---|
| 40 | the number of servers, the number of polls each time it is run and |
|---|
| 41 | the interval between runs. |
|---|
| 42 | |
|---|
| 43 | <p><tt>ntpdate</tt> can be run manually as necessary to set the |
|---|
| 44 | host clock, or it can be run from the host startup script to set |
|---|
| 45 | the clock at boot time. This is useful in some cases to set the |
|---|
| 46 | clock initially before starting the NTP daemon <tt>ntpd</tt>. It is |
|---|
| 47 | also possible to run <tt>ntpdate</tt> from a <tt>cron</tt> script. |
|---|
| 48 | However, it is important to note that <tt>ntpdate</tt> with |
|---|
| 49 | contrived <tt>cron</tt> scripts is no substitute for the NTP |
|---|
| 50 | daemon, which uses sophisticated algorithms to maximize accuracy |
|---|
| 51 | and reliability while minimizing resource use. Finally, since <tt> |
|---|
| 52 | ntpdate</tt> does not discipline the host clock frequency as does |
|---|
| 53 | <tt>ntpd</tt>, the accuracy using <tt>ntpdate</tt> is limited.</p> |
|---|
| 54 | |
|---|
| 55 | <p>Time adjustments are made by <tt>ntpdate</tt> in one of two |
|---|
| 56 | ways. If <tt>ntpdate</tt> determines the clock is in error more |
|---|
| 57 | than 0.5 second it will simply step the time by calling the system |
|---|
| 58 | <tt>settimeofday()</tt> routine. If the error is less than 0.5 |
|---|
| 59 | seconds, it will slew the time by calling the system <tt> |
|---|
| 60 | adjtime()</tt> routine. The latter technique is less disruptive and |
|---|
| 61 | more accurate when the error is small, and works quite well when |
|---|
| 62 | <tt>ntpdate</tt> is run by <tt>cron</tt> every hour or two.</p> |
|---|
| 63 | |
|---|
| 64 | <p><tt>ntpdate</tt> will decline to set the date if an NTP server |
|---|
| 65 | daemon (e.g., <tt>ntpd</tt>) is running on the same host. When |
|---|
| 66 | running <tt>ntpdate</tt> on a regular basis from <tt>cron</tt> as |
|---|
| 67 | an alternative to running a daemon, doing so once every hour or two |
|---|
| 68 | will result in precise enough timekeeping to avoid stepping the |
|---|
| 69 | clock.</p> |
|---|
| 70 | |
|---|
| 71 | <p>If NetInfo support is compiled into <tt>ntpdate</tt>, then the |
|---|
| 72 | <tt>server</tt> argument is optional if <tt>ntpdate</tt> can find a |
|---|
| 73 | time server in the NetInfo configuration for <tt>ntpd</tt>.</p> |
|---|
| 74 | |
|---|
| 75 | <h4>Command Line Options</h4> |
|---|
| 76 | |
|---|
| 77 | <dl> |
|---|
| 78 | <dt><tt>-a <i>key</i></tt></dt> |
|---|
| 79 | |
|---|
| 80 | <dd>Enable the authentication function and specify the key |
|---|
| 81 | identifier to be used for authentication as the argument <i> |
|---|
| 82 | key</i><tt>ntpdate</tt>. The keys and key identifiers must match in |
|---|
| 83 | both the client and server key files. The default is to disable the |
|---|
| 84 | authentication function.</dd> |
|---|
| 85 | |
|---|
| 86 | <dt><tt>-B</tt></dt> |
|---|
| 87 | |
|---|
| 88 | <dd>Force the time to always be slewed using the adjtime() system |
|---|
| 89 | call, even if the measured offset is greater than +-128 ms. The |
|---|
| 90 | default is to step the time using settimeofday() if the offset is |
|---|
| 91 | greater than +-128 ms. Note that, if the offset is much greater |
|---|
| 92 | than +-128 ms in this case, that it can take a long time (hours) to |
|---|
| 93 | slew the clock to the correct value. During this time. the host |
|---|
| 94 | should not be used to synchronize clients.</dd> |
|---|
| 95 | |
|---|
| 96 | <dt><tt>-b</tt></dt> |
|---|
| 97 | |
|---|
| 98 | <dd>Force the time to be stepped using the settimeofday() system |
|---|
| 99 | call, rather than slewed (default) using the adjtime() system call. |
|---|
| 100 | This option should be used when called from a startup file at boot |
|---|
| 101 | time.</dd> |
|---|
| 102 | |
|---|
| 103 | <dt><tt>-d</tt></dt> |
|---|
| 104 | |
|---|
| 105 | <dd>Enable the debugging mode, in which <tt>ntpdate</tt> will go |
|---|
| 106 | through all the steps, but not adjust the local clock. Information |
|---|
| 107 | useful for general debugging will also be printed.</dd> |
|---|
| 108 | |
|---|
| 109 | <dt><tt>-e <i>authdelay</i></tt></dt> |
|---|
| 110 | |
|---|
| 111 | <dd>Specify the processing delay to perform an authentication |
|---|
| 112 | function as the value <i>authdelay</i>, in seconds and fraction |
|---|
| 113 | (see <tt>ntpd</tt> for details). This number is usually small |
|---|
| 114 | enough to be negligible for most purposes, though specifying a |
|---|
| 115 | value may improve timekeeping on very slow CPU's.</dd> |
|---|
| 116 | |
|---|
| 117 | <dt><tt>-k <i>keyfile</i></tt></dt> |
|---|
| 118 | |
|---|
| 119 | <dd>Specify the path for the authentication key file as the string |
|---|
| 120 | <i>keyfile</i>. The default is <tt>/etc/ntp.keys</tt>. This file |
|---|
| 121 | should be in the format described in <tt>ntpd</tt>.</dd> |
|---|
| 122 | |
|---|
| 123 | <dt><tt>-o <i>version</i></tt></dt> |
|---|
| 124 | |
|---|
| 125 | <dd>Specify the NTP version for outgoint packets as the integer <i> |
|---|
| 126 | version</i>, which can be 1 or 2. The default is 3. This allows |
|---|
| 127 | <tt>ntpdate</tt> to be used with older NTP versions.</dd> |
|---|
| 128 | |
|---|
| 129 | <dt><tt>-p <i>samples</i></tt></dt> |
|---|
| 130 | |
|---|
| 131 | <dd>Specify the number of samples to be acquired from each server |
|---|
| 132 | as the integer <i>samples</i>, with values from 1 to 8 inclusive. |
|---|
| 133 | The default is 4.</dd> |
|---|
| 134 | |
|---|
| 135 | <dt><i><tt>-q</tt></i></dt> |
|---|
| 136 | |
|---|
| 137 | <dd>Query only - don't set the clock.</dd> |
|---|
| 138 | |
|---|
| 139 | <dt><tt>-s</tt></dt> |
|---|
| 140 | |
|---|
| 141 | <dd>Divert logging output from the standard output (default) to the |
|---|
| 142 | system <tt>syslog</tt> facility. This is designed primarily for |
|---|
| 143 | convenience of <tt>cron</tt> scripts.</dd> |
|---|
| 144 | |
|---|
| 145 | <dt><tt>-t <i>timeout</i></tt></dt> |
|---|
| 146 | |
|---|
| 147 | <dd>Specify the maximum time waiting for a server response as the |
|---|
| 148 | value <i>timeout</i>, in seconds and fraction. The value is is |
|---|
| 149 | rounded to a multiple of 0.2 seconds. The default is 1 second, a |
|---|
| 150 | value suitable for polling across a LAN.</dd> |
|---|
| 151 | |
|---|
| 152 | <dt><tt>-u</tt></dt> |
|---|
| 153 | |
|---|
| 154 | <dd>Direct <tt>ntpdate</tt> to use an unprivileged port or outgoing |
|---|
| 155 | packets. This is most useful when behind a firewall that blocks |
|---|
| 156 | incoming traffic to privileged ports, and you want to synchronise |
|---|
| 157 | with hosts beyond the firewall. Note that the <tt>-d</tt> option |
|---|
| 158 | always uses unprivileged ports.</dd> |
|---|
| 159 | |
|---|
| 160 | <dt><tt>-<i>v</i></tt></dt> |
|---|
| 161 | |
|---|
| 162 | <dd>Be verbose. This option will cause <tt>ntpdate</tt>'s version |
|---|
| 163 | identification string to be logged.</dd> |
|---|
| 164 | </dl> |
|---|
| 165 | |
|---|
| 166 | <h4>Files</h4> |
|---|
| 167 | |
|---|
| 168 | <tt>/etc/ntp.keys</tt> - encryption keys used by <tt>ntpdate</tt>. |
|---|
| 169 | |
|---|
| 170 | <h4>Bugs</h4> |
|---|
| 171 | |
|---|
| 172 | The slew adjustment is actually 50% larger than the measured |
|---|
| 173 | offset, since this (it is argued) will tend to keep a badly |
|---|
| 174 | drifting clock more accurate. This is probably not a good idea and |
|---|
| 175 | may cause a troubling hunt for some values of the kernel variables |
|---|
| 176 | <tt>tick</tt> and <tt>tickadj</tt>. |
|---|
| 177 | |
|---|
| 178 | <hr> |
|---|
| 179 | <a href="index.htm"><img align="left" src="pic/home.gif" alt= |
|---|
| 180 | "gif"></a> |
|---|
| 181 | |
|---|
| 182 | <address><a href="mailto:mills@udel.edu">David L. Mills |
|---|
| 183 | <mills@udel.edu></a></address> |
|---|
| 184 | </body> |
|---|
| 185 | </html> |
|---|
| 186 | |
|---|
