contrib/ntp/html/ntpd.htm

   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>ntpd - Network Time Protocol (NTP) daemon</title>
   6 </head>
   7 <body>
   8 <h3><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</h3>
   9
  10 <img align="left" src="pic/alice47.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>The mushroom knows all the command line options.<br clear=
  15 "left">
  16 </p>
  17
  18 <hr>
  19 <h4>Synopsis</h4>
  20
  21 <tt>ntpd [ -aAbdgLmNPqx ] [ -c <i>conffile</i> ] [ -f <i>
  22 driftfile</i> ] [ -g ] [ -k <i>keyfile</i> ] [ -l <i>logfile</i> ]
  23 [ -N high ] [ -p <i>pidfile</i> ] [ -r <i>broadcastdelay</i> ] [ -s
  24 <i>statsdir</i> ] [ -t <i>key</i> ] [ -v <i>variable</i> ] [ -V <i>
  25 variable</i> ] [ -x ]</tt>
  26
  27 <h4>Description</h4>
  28
  29 The <tt>ntpd</tt> program is an operating system daemon which sets
  30 and maintains the system time of day in synchronism with Internet
  31 standard time servers. It is a complete implementation of the
  32 Network Time Protocol (NTP) version 4, but also retains
  33 compatibility with version 3, as defined by RFC-1305, and version 1
  34 and 2, as defined by RFC-1059 and RFC-1119, respectively. <tt>
  35 ntpd</tt> does most computations in 64-bit floating point
  36 arithmetic and does relatively clumsy 64-bit fixed point operations
  37 only when necessary to preserve the ultimate precision, about 232
  38 picoseconds. While the ultimate precision, is not achievable with
  39 ordinary workstations and networks of today, it may be required
  40 with future gigahertz CPU clocks and gigabit LANs.
  41
  42 <h4>How NTP Operates</h4>
  43
  44 <p>The <tt>ntpd</tt> program operates by exchanging messages with
  45 one or more configured servers at designated poll intervals. When
  46 started, whether for the first or subsequent times, the program
  47 requires several exahanges from the majority of these servers so
  48 the signal processing and mitigation algorithms can accumulate and
  49 groom the data and set the clock. In order to protect the network
  50 from bursts, the initial poll interval for each server is delayed
  51 an interval randomized over 0-16s. At the default initial poll
  52 interval of 64s, several minutes can elapse before the clock is
  53 set. The initial delay to set the clock can be reduced using the
  54 <tt>iburst</tt> keyword with the <tt>server</tt> configuration
  55 command, as described on the <a href="confopt.htm">Configuration
  56 Options</a> page.</p>
  57
  58 <p>Most operating systems and hardware of today incorporate a
  59 time-of-year (TOY) chip to maintain the time during periods when
  60 the power is off. When the machine is booted, the chip is used to
  61 initialize the operating system time. After the machine has
  62 synchronized to a NTP server, the operating system corrects the
  63 chip from time to time. In case there is no TOY chip or for some
  64 reason its time is more than 1000s from the server time, <tt>
  65 ntpd</tt> assumes something must be terribly wrong and the only
  66 reliable action is for the operator to intervene and set the clock
  67 by hand. This causes <tt>ntpd</tt> to exit with a panic message to
  68 the system log. The <tt>-g</tt> option overrides this check and the
  69 clock will be set to the server time regardless of the chip time.
  70 However, and to protect against broken hardware, such as when the
  71 CMOS battery fails or the clock counter becomes defective, once the
  72 clock has been set, an error greater than 1000s will cause <tt>
  73 ntpd</tt> to exit anyway.</p>
  74
  75 <p>Under ordinariy conditions, <tt>ntpd</tt> adjusts the clock in
  76 small steps so that the timescale is effectively continuous and
  77 without discontinuities. Under conditions of extreme network
  78 congestion, the roundtrip delay jitter can exceed three seconds and
  79 the synchronization distance, which is equal to one-half the
  80 roundtrip delay plus error budget terms, can become very large. The
  81 <tt>ntpd</tt> algorithms discard sample offsets exceeding 128 ms,
  82 unless the interval during which no sample offset is less than 128
  83 ms exceeds 900s. The first sample after that, no matter what the
  84 offset, steps the clock to the indicated time. In practice this
  85 reduces the false alarm rate where the clock is stepped in error to
  86 a vanishingly low incidence.</p>
  87
  88 <p>As the result of this behavior, once the clock has been set, it
  89 very rarely strays more than 128 ms, even under extreme cases of
  90 network path congestion and jitter. Sometimes, in particular when
  91 <tt>ntpd</tt> is first started, the error might exceed 128 ms. This
  92 may on occasion cause the clock to be set backwards if the local
  93 clock time is more than 128 s in the future relative to the server.
  94 In some applications, this behavior may be unacceptable. If the
  95 <tt>-x</tt> option is included on the command line, the clock will
  96 never be stepped and only slew corrections will be used.</p>
  97
  98 <p>The issues should be carefully explored before deciding to use
  99 the <tt>-x</tt> option. The maximum slew rate possible is limited
 100 to 500 parts-per-million (PPM) as a consequence of the correctness
 101 principles on which the NTP protocol and algorithm design are
 102 based. As a result, the local clock can take a long time to
 103 converge to an acceptable offset, about 2,000 s for each second the
 104 clock is outside the acceptable range. During this interval the
 105 local clock will not be consistent with any other network clock and
 106 the system cannot be used for distributed applications that require
 107 correctly synchronized network time.</p>
 108
 109 <p>In spite of the above precautions, sometimes when large
 110 frequency errors are present the resulting time offsets stray
 111 outside the 128-ms range and an eventual step or slew time
 112 correction is required. If following such a correction the
 113 frequency error is so large that the first sample is outside the
 114 acceptable range, <tt>ntpd</tt> enters the same state as when the
 115 <tt>ntp.drift</tt> file is not present. The intent of this behavior
 116 is to quickly correct the frequency and restore operation to the
 117 normal tracking mode. In the most extreme cases
 118 (<tt>time.ien.it</tt> comes to mind), there may be occasional
 119 step/slew corrections and subsequent frequency corrections. It
 120 helps in these cases to use the <tt>burst</tt> keyword when
 121 configuring the server.</p>
 122
 123 <h4>Frequency Discipline</h4>
 124
 125 <p>The <tt>ntpd</tt> behavior at startup depends on whether the
 126 frequency file, usually <tt>ntp.drift</tt>, exists. This file
 127 contains the latest estimate of clock frequency error. When the
 128 <tt>ntpd</tt> is started and the file does not exist, the <tt>
 129 ntpd</tt> enters a special mode designed to quickly adapt to the
 130 particular system clock oscillator time and frequency error. This
 131 takes approximately 15 minutes, after which the time and frequency
 132 are set to nominal values and the <tt>ntpd</tt> enters normal mode,
 133 where the time and frequency are continuously tracked relative to
 134 the server. After one hour the frequency file is created and the
 135 current frequency offset written to it. When the <tt>ntpd</tt> is
 136 started and the file does exist, the <tt>ntpd</tt> frequency is
 137 initialized from the file and enters normal mode immediately. After
 138 that the current frequency offset is written to the file at hourly
 139 intervals.</p>
 140
 141 <h4>Operating Modes</h4>
 142
 143 <p><tt>ntpd</tt> can operate in any of several modes, including
 144 symmetric active/passive, client/server broadcast/multicast and
 145 manycast, as described in the <a href="assoc.htm">Association
 146 Management</a> page. It normally operates continuously while
 147 monitoring for small changes in frequency and trimming the clock
 148 for the ultimate precision. However, it can operate in a one-time
 149 mode where the time is set from an external server and frequency is
 150 set from a previously recorded frequency file. A
 151 broadcast/multicast or manycast client can discover remote servers,
 152 compute server-client propagation delay correction factors and
 153 configure itself automatically. This makes it possible to deploy a
 154 fleet of workstations without specifying configuration details
 155 specific to the local environment.</p>
 156
 157 <p>By default, <tt>ntpd</tt> runs in continuous mode where each of
 158 possibly several external servers is polled at intervals determined
 159 by an intricate state machine. The state machine measures the
 160 incidental roundtrip delay jitter and oscillator frequency wander
 161 and determines the best poll interval using a heuristic algorithm.
 162 Ordinarily, and in most operating environments, the state machine
 163 will start with 64s intervals and eventually increase in steps to
 164 1024s. A small amount of random variation is introduced in order to
 165 avoid bunching at the servers. In addition, should a server become
 166 unreachable for some time, the poll interval is increased in steps
 167 to 1024s in order to reduce network overhead.</p>
 168
 169 <p>In some cases it may not be practical for <tt>ntpd</tt> to run
 170 continuously. A common workaround has been to run the <tt>
 171 ntpdate</tt> program from a <tt>cron</tt> job at designated times.
 172 However, this program does not have the crafted signal processing,
 173 error checking and mitigation algorithms of <tt>ntpd</tt>. The <tt>
 174 -q</tt> option is intended for this purpose. Setting this option
 175 will cause <tt>ntpd</tt> to exit just after setting the clock for
 176 the first time. The procedure for initially setting the clock is
 177 the same as in continuous mode; most applications will probably
 178 want to specify the <tt>iburst</tt> keyword with the <tt>
 179 server</tt> configuration command. With this keyword a volley of
 180 messages are exchanged to groom the data and the clock is set in
 181 about a minute. If nothing is heard after a couple of minutes, the
 182 daemon times out and exits. After a suitable period of mourning,
 183 the <tt>ntpdate</tt> program may be retired.</p>
 184
 185 <p>When kernel support is available to discipline the clock
 186 frequency, which is the case for stock Solaris, Tru64, Linux and
 187 FreeBSD, a useful feature is available to discipline the clock
 188 frequency. First, <tt>ntpd</tt> is run in continuous mode with
 189 selected servers in order to measure and record the intrinsic clock
 190 frequency offset in the frequency file. It may take some hours for
 191 the frequency and offset to settle down. Then the <tt>ntpd</tt> is
 192 stopped and run in one-time mode as required. At each startup, the
 193 frequency is read from the file and initializes the kernel
 194 frequency.</p>
 195
 196 <h4>Poll Interval Control</h4>
 197
 198 <p>This version of NTP includes an intricate state machine to
 199 reduce the network load while maintaining a quality of
 200 synchronization consistent with the observed jitter and wander.
 201 There are a number of ways to tailor the operation in order enhance
 202 accuracy by reducing the interval or to reduce network overhead by
 203 increasing it. However, the user is advised to carefully consider
 204 the consequenses of changing the poll adjustment range from the
 205 default minimum of 64 s to the default maximum of 1,024 s. The
 206 default minimum can be changed with the <tt>tinker minpoll</tt>
 207 command to a value not less than 16 s. This value is used for all
 208 configured associations, unless overriden by the <tt>minpoll</tt>
 209 option on the configuration command. Note that most device drivers
 210 will not operate properly if the poll interval is less than 64 s
 211 and that the broadcast server and manycast client associations will
 212 also use the default, unless overriden.</p>
 213
 214 <p>In some cases involving dial up or toll services, it may be
 215 useful to increase the minimum interval to a few tens of minutes
 216 and maximum interval to a day or so. Under normal operation
 217 conditions, once the clock discipline loop has stabilized the
 218 interval will be increased in steps from the minumum to the
 219 maximum. However, this assumes the intrinsic clock frequency error
 220 is small enough for the discipline loop correct it. The capture
 221 range of the loop is 500 PPM at an interval of 64s decreasing by a
 222 factor of two for each doubling of interval. At a minimum of 1,024
 223 s, for example, the capture range is only 31 PPM. If the intrinsic
 224 error is greater than this, the drift file <tt>ntp.drift</tt> will
 225 have to be specially tailored to reduce the residual error below
 226 this limit. Once this is done, the drift file is automatically
 227 updated once per hour and is available to initialize the frequency
 228 on subsequent daemon restarts.</p>
 229
 230 <h4>The huff-n'-puff filter</h4>
 231
 232 <p>In scenarios where a considerable amount of data are to be
 233 downloaded or uploaded over telephone modems, timekeeping quality
 234 can be seriously degraded. This occurs because the differential
 235 delays on the two directions of transmission can be quite large. In
 236 many cases the apparent time errors are so large as to exceed the
 237 step threshold and a step correction can occur during and after the
 238 data transfer is in progress.</p>
 239
 240 <p>The huff-n'-puff filter is designed to correct the apparent time
 241 offset in these cases. It depends on knowledge of the propagation
 242 delay when no other traffic is present. In common scenarios this
 243 occurs during other than work hours. The filter maintains a shift
 244 register that remembers the minimum delay over the most recent
 245 interval measured usually in hours. Under conditions of severe
 246 delay, the filter corrects the apparent offset using the sign of
 247 the offset and the difference between the apparent delay and
 248 minimum delay. The name of the filter reflects the negative (huff)
 249 and positive (puff) correction, which depends on the sign of the
 250 offset.</p>
 251
 252 <p>The filter is activated by the <tt>tinker</tt> command and <tt>
 253 huffpuff</tt> keyword, as described in the <a href="miscopt.htm">
 254 Miscellaneous Options</a> page.</p>
 255
 256 <h4>Notes</h4>
 257
 258 <p>If NetInfo support is built into <tt>ntpd</tt>, then <tt>
 259 ntpd</tt> will attempt to read its configuration from the NetInfo
 260 if the default ntp.conf file cannot be read and no file is
 261 specified by the <tt>-c</tt> option.</p>
 262
 263 <p>Various internal <tt>ntpd</tt> variables can be displayed and
 264 configuration options altered while the <tt>ntpd</tt> is running
 265 using the <tt><a href="ntpq.htm">ntpq</a></tt> and <tt><a href=
 266 "ntpdc.htm">ntpdc</a></tt> utility programs.</p>
 267
 268 <p>When <tt>ntpd</tt> starts it looks at the value of <tt>
 269 umask</tt>, and if zero <tt>ntpd</tt> will set the <tt>umask</tt>
 270 to <tt>022</tt>.</p>
 271
 272 <h4>Command Line Options</h4>
 273
 274 <dl>
 275 <dt><tt>-a</tt></dt>
 276
 277 <dd>Enable authentication mode (default).</dd>
 278
 279 <dt><tt>-A</tt></dt>
 280
 281 <dd>Disable authentication mode.</dd>
 282
 283 <dt><tt>-b</tt></dt>
 284
 285 <dd>Synchronize using NTP broadcast messages.</dd>
 286
 287 <dt><tt>-c <i>conffile</i></tt></dt>
 288
 289 <dd>Specify the name and path of the configuration file. (Disable
 290 netinfo?)</dd>
 291
 292 <dt><tt>-d</tt></dt>
 293
 294 <dd>Specify debugging mode. This flag may occur multiple times,
 295 with each occurrence indicating greater detail of display.</dd>
 296
 297 <dt><tt>-D <i>level</i></tt></dt>
 298
 299 <dd>Specify debugging level directly.</dd>
 300
 301 <dt><tt>-f <i>driftfile</i></tt></dt>
 302
 303 <dd>Specify the name and path of the drift file.</dd>
 304
 305 <dt><tt>-g</tt></dt>
 306
 307 <dd>Normally, <tt>ntpd</tt> exits if the offset exceeds the sanity
 308 limit, which is 1000 s by default. If the sanity limit is set to
 309 zero, no sanity checking is performed and any offset is acceptable.
 310 This option overrides the limit and allows the time to be set to
 311 any value without restriction; however, this can happen only once.
 312 After that, <tt>ntpd</tt> will exit if the limit is exceeded. This
 313 option can be used with the <tt>-q</tt> option.</dd>
 314
 315 <dt><tt>-k <i>keyfile</i></tt></dt>
 316
 317 <dd>Specify the name and path of the file containing the NTP
 318 authentication keys.</dd>
 319
 320 <dt><tt>-l <i>logfile</i></tt></dt>
 321
 322 <dd>Specify the name and path of the log file. The default is the
 323 system log facility.</dd>
 324
 325 <dt><tt>-L</tt></dt>
 326
 327 <dd>Listen to virtual IPs.</dd>
 328
 329 <dt><tt>-m</tt></dt>
 330
 331 <dd>Synchronize using NTP multicast messages on the IP multicast
 332 group address 224.0.1.1 (requires multicast kernel).</dd>
 333
 334 <dt><tt>-n</tt></dt>
 335
 336 <dd>Don't fork.</dd>
 337
 338 <dt><tt>-N <i>priority</i></tt></dt>
 339
 340 <dd>To the extent permitted by the operating system, run the <tt>
 341 ntpd</tt> at a high priority.</dd>
 342
 343 <dt><tt>-p <i>pidfile</i></tt></dt>
 344
 345 <dd>Specify the name and path to record the <tt>ntpd</tt>'s process
 346 ID.</dd>
 347
 348 <dt><tt>-P</tt></dt>
 349
 350 <dd>Override the priority limit set by the operating system. Not
 351 recommended for sissies.</dd>
 352
 353 <dt><tt>-q</tt></dt>
 354
 355 <dd>Exit the <tt>ntpd</tt> just after the first time the clock is
 356 set. This behavior mimics that of the <tt>ntpdate</tt> program,
 357 which is to be retired. The <tt>-g</tt> and <tt>-x</tt> options can
 358 be used with this option.</dd>
 359
 360 <dt><tt>-r <i>broadcastdelay</i></tt></dt>
 361
 362 <dd>Specify the default propagation delay from the
 363 broadcast/multicast server and this computer. This is necessary
 364 only if the delay cannot be computed automatically by the
 365 protocol.</dd>
 366
 367 <dt><tt>-s <i>statsdir</i></tt></dt>
 368
 369 <dd>Specify the directory path for files created by the statistics
 370 facility.</dd>
 371
 372 <dt><tt>-t <i>key</i></tt></dt>
 373
 374 <dd>Add a key number to the trusted key list.</dd>
 375
 376 <dt><tt>-v <i>variable</i></tt></dt>
 377
 378 <dt><tt>-V <i>variable</i></tt></dt>
 379
 380 <dd>Add a system variable listed by default.</dd>
 381
 382 <dt><tt>-x</tt></dt>
 383
 384 <dd>Normally, the time is slewed if the offset is less than the
 385 step threshold, which is 128 ms by default, and stepped if above
 386 the threshold. This option forces the time to be slewed in all
 387 cases. If the step threshold is set to zero, all offsets are
 388 stepped, regardless of value and regardless of the <tt>-x</tt>
 389 option. In general, this is not a good idea, as it bypasses the
 390 clock state machine which is designed to cope with large time and
 391 frequency errors Note: Since the slew rate is limited to 0.5 ms/s,
 392 each second of adjustment requires an amortization interval of 2000
 393 s. Thus, an adjustment of many seconds can take hours or days to
 394 amortize. This option can be used with the <tt>-q</tt> option.</dd>
 395 </dl>
 396
 397 <h4>The Configuration File</h4>
 398
 399 <p>Ordinarily, <tt>ntpd</tt> reads the <tt>ntp.conf</tt>
 400 configuration file at startup time in order to determine the
 401 synchronization sources and operating modes. It is also possible to
 402 specify a working, although limited, configuration entirely on the
 403 command line, obviating the need for a configuration file. This may
 404 be particularly useful when the local host is to be configured as a
 405 broadcast/multicast client, with all peers being determined by
 406 listening to broadcasts at run time.</p>
 407
 408 <p>Usually, the configuration file is installed in the <tt>
 409 /etc</tt> directory, but could be installed elsewhere (see the <tt>
 410 -c <i>conffile</i></tt> command line option). The file format is
 411 similar to other Unix configuration files - comments begin with a
 412 <tt>#</tt> character and extend to the end of the line; blank lines
 413 are ignored.</p>
 414
 415 <p>Configuration commands consist of an initial keyword followed by
 416 a list of arguments, some of which may be optional, separated by
 417 whitespace. Commands may not be continued over multiple lines.
 418 Arguments may be host names, host addresses written in numeric,
 419 dotted-quad form, integers, floating point numbers (when specifying
 420 times in seconds) and text strings. Optional arguments are
 421 delimited by <tt>[ ]</tt> in the following descriptions, while
 422 alternatives are separated by <tt>|</tt>. The notation <tt>[ ...
 423 ]</tt> means an optional, indefinite repetition of the last item
 424 before the <tt>[ ... ]</tt>.</p>
 425
 426 <p><a href="confopt.htm">Configuration Options</a><br>
 427 <a href="authopt.htm">Authentication Options</a><br>
 428 <a href="monopt.htm">Monitoring Options</a><br>
 429 <a href="accopt.htm">Access Control Options</a><br>
 430 <a href="clockopt.htm">Reference Clock Options</a><br>
 431 <a href="miscopt.htm">Miscellaneous Options</a></p>
 432
 433 <h4>Files</h4>
 434
 435 <tt>/etc/ntp.conf</tt> - the default name of the configuration file
 436 <br>
 437 <tt>/etc/ntp.drift</tt> - the default name of the drift file <br>
 438 <tt>/etc/ntp.keys</tt> - the default name of the key file
 439
 440 <h4>Bugs</h4>
 441
 442 <tt>ntpd</tt> has gotten rather fat. While not huge, it has gotten
 443 larger than might be desirable for an elevated-priority <tt>
 444 ntpd</tt> running on a workstation, particularly since many of the
 445 fancy features which consume the space were designed more with a
 446 busy primary server, rather than a high stratum workstation in
 447 mind.
 448
 449 <hr>
 450 <a href="index.htm"><img align="left" src="pic/home.gif" alt=
 451 "gif"></a>
 452
 453 <address><a href="mailto:mills@udel.edu">David L. Mills
 454 &lt;mills@udel.edu&gt;</a></address>
 455 </body>
 456 </html>
 457