2 .\" $FreeBSD: src/usr.sbin/ntp/doc/ntpd.8,v 1.4.2.5 2003/03/11 22:31:29 trhodes Exp $
3 .\" $DragonFly: src/usr.sbin/ntp/doc/Attic/ntpd.8,v 1.2 2003/06/17 04:29:58 dillon Exp $
10 .Nd Network Time Protocol (NTP) daemon
21 .Op Fl r Ar broadcastdelay
29 utility is an operating system daemon which sets
30 and maintains the system time of day in synchronism with Internet
31 standard time servers.
32 It is a complete implementation of the
33 Network Time Protocol (NTP) version 4, but also retains
34 compatibility with version 3, as defined by RFC-1305, and version 1
35 and 2, as defined by RFC-1059 and RFC-1119, respectively.
39 utility does most computations in 64-bit floating point
40 arithmetic and does relatively clumsy 64-bit fixed point operations
41 only when necessary to preserve the ultimate precision, about 232
43 While the ultimate precision, is not achievable with
44 ordinary workstations and networks of today, it may be required
45 with future gigahertz CPU clocks and gigabit LANs.
51 configuration file at startup time in order to determine the
52 synchronization sources and operating modes.
53 It is also possible to
54 specify a working, although limited, configuration entirely on the
55 command line, obviating the need for a configuration file.
57 be particularly useful when the local host is to be configured as a
58 broadcast/multicast client, with all peers being determined by
59 listening to broadcasts at run time.
61 If NetInfo support is built into
65 will attempt to read its configuration from the
66 NetInfo if the default
68 file cannot be read and no file is
75 variables can be displayed and
76 configuration options altered while the
87 starts it looks at the value of
95 The following options are available:
96 .Bl -tag -width indent
98 Enable authentication mode (default).
100 Disable authentication mode.
102 Synchronize using NTP broadcast messages.
104 Specify the name and path of the configuration file.
108 Specify debugging mode.
109 This flag may occur multiple times,
110 with each occurrence indicating greater detail of display.
112 Specify debugging level directly.
113 .It Fl f Ar driftfile
114 Specify the name and path of the drift file.
118 exits if the offset exceeds the sanity
119 limit, which is 1000 s by default.
120 If the sanity limit is set to
121 zero, no sanity checking is performed and any offset is acceptable.
122 This option overrides the limit and allows the time to be set to
123 any value without restriction; however, this can happen only once.
126 will exit if the limit is exceeded.
128 option can be used with the
132 Specify the name and path of the file containing the NTP
135 Specify the name and path of the log file.
139 Listen to virtual IPs.
141 Synchronize using NTP multicast messages on the IP multicast
142 group address 224.0.1.1 (requires multicast kernel).
146 To the extent permitted by the operating system, run the
150 Specify the name and path to record the
155 Override the priority limit set by the operating system.
157 recommended for sissies.
161 just after the first time the clock is
163 This behavior mimics that of the
166 which is to be retired.
172 be used with this option.
173 .It Fl r Ar broadcastdelay
174 Specify the default propagation delay from the
175 broadcast/multicast server and this computer.
177 only if the delay cannot be computed automatically by the
180 Specify the directory path for files created by the statistics
183 Add a key number to the trusted key list.
186 Add a system variable listed by default.
188 Normally, the time is slewed if the offset is less than the
189 step threshold, which is 128 ms by default, and stepped if above
191 This option forces the time to be slewed in all
193 If the step threshold is set to zero, all offsets are
194 stepped, regardless of value and regardless of the
197 In general, this is not a good idea, as it bypasses the
198 clock state machine which is designed to cope with large time and
199 frequency errors Note: Since the slew rate is limited to 0.5 ms/s,
200 each second of adjustment requires an amortization interval of 2000
202 Thus, an adjustment of many seconds can take hours or days to
204 This option can be used with the
208 .Ss "How NTP Operates"
211 utility operates by exchanging messages with
212 one or more configured servers at designated poll intervals.
214 started, whether for the first or subsequent times, the program
215 requires several exchanges from the majority of these servers so
216 the signal processing and mitigation algorithms can accumulate and
217 groom the data and set the clock.
218 In order to protect the network
219 from bursts, the initial poll interval for each server is delayed
220 an interval randomized over 0-16s.
221 At the default initial poll
222 interval of 64s, several minutes can elapse before the clock is
224 The initial delay to set the clock can be reduced using the
229 command, as described in
232 Most operating systems and hardware of today incorporate a
233 time-of-year (TOY) chip to maintain the time during periods when
235 When the machine is booted, the chip is used to
236 initialize the operating system time.
237 After the machine has
238 synchronized to a NTP server, the operating system corrects the
239 chip from time to time.
240 In case there is no TOY chip or for some
241 reason its time is more than 1000s from the server time,
243 assumes something must be terribly wrong and the only
244 reliable action is for the operator to intervene and set the clock
248 to exit with a panic message to
252 option overrides this check and the
253 clock will be set to the server time regardless of the chip time.
254 However, and to protect against broken hardware, such as when the
255 CMOS battery fails or the clock counter becomes defective, once the
256 clock has been set, an error greater than 1000s will cause
260 Under ordinary conditions,
263 small steps so that the timescale is effectively continuous and
264 without discontinuities.
265 Under conditions of extreme network
266 congestion, the roundtrip delay jitter can exceed three seconds and
267 the synchronization distance, which is equal to one-half the
268 roundtrip delay plus error budget terms, can become very large.
271 algorithms discard sample offsets exceeding 128 ms,
272 unless the interval during which no sample offset is less than 128
274 The first sample after that, no matter what the
275 offset, steps the clock to the indicated time.
277 reduces the false alarm rate where the clock is stepped in error to
278 a vanishingly low incidence.
280 As the result of this behavior, once the clock has been set, it
281 very rarely strays more than 128 ms, even under extreme cases of
282 network path congestion and jitter.
283 Sometimes, in particular when
285 is first started, the error might exceed 128 ms.
287 may on occasion cause the clock to be set backwards if the local
288 clock time is more than 128 s in the future relative to the server.
289 In some applications, this behavior may be unacceptable.
292 option is included on the command line, the clock will
293 never be stepped and only slew corrections will be used.
295 The issues should be carefully explored before deciding to use
299 The maximum slew rate possible is limited
300 to 500 parts-per-million (PPM) as a consequence of the correctness
301 principles on which the NTP protocol and algorithm design are
303 As a result, the local clock can take a long time to
304 converge to an acceptable offset, about 2,000 s for each second the
305 clock is outside the acceptable range.
306 During this interval the
307 local clock will not be consistent with any other network clock and
308 the system cannot be used for distributed applications that require
309 correctly synchronized network time.
311 In spite of the above precautions, sometimes when large
312 frequency errors are present the resulting time offsets stray
313 outside the 128-ms range and an eventual step or slew time
314 correction is required.
315 If following such a correction the
316 frequency error is so large that the first sample is outside the
319 enters the same state as when the
322 The intent of this behavior
323 is to quickly correct the frequency and restore operation to the
324 normal tracking mode.
325 In the most extreme cases
326 (time.ien.it comes to mind), there may be occasional
327 step/slew corrections and subsequent frequency corrections.
329 helps in these cases to use the
332 configuring the server.
333 .Ss "Frequency Discipline"
336 behavior at startup depends on whether the
337 frequency file, usually
341 contains the latest estimate of clock frequency error.
344 is started and the file does not exist, the
346 enters a special mode designed to quickly adapt to
347 the particular system clock oscillator time and frequency error.
348 This takes approximately 15 minutes, after which the time and
349 frequency are set to nominal values and the
352 normal mode, where the time and frequency are continuously tracked
353 relative to the server.
354 After one hour the frequency file is
355 created and the current frequency offset written to it.
358 is started and the file does exist, the
360 frequency is initialized from the file and enters normal mode
362 After that the current frequency offset is written to
363 the file at hourly intervals.
364 .Ss "Operating Modes"
367 utility can operate in any of several modes, including
368 symmetric active/passive, client/server broadcast/multicast and
369 manycast, as described in the
370 .Qq Association Management
372 (available as part of the HTML documentation
374 .Pa /usr/share/doc/ntp ) .
375 It normally operates continuously while
376 monitoring for small changes in frequency and trimming the clock
377 for the ultimate precision.
378 However, it can operate in a one-time
379 mode where the time is set from an external server and frequency is
380 set from a previously recorded frequency file.
382 broadcast/multicast or manycast client can discover remote servers,
383 compute server-client propagation delay correction factors and
384 configure itself automatically.
385 This makes it possible to deploy a
386 fleet of workstations without specifying configuration details
387 specific to the local environment.
391 runs in continuous mode where each of
392 possibly several external servers is polled at intervals determined
393 by an intricate state machine.
394 The state machine measures the
395 incidental roundtrip delay jitter and oscillator frequency wander
396 and determines the best poll interval using a heuristic algorithm.
397 Ordinarily, and in most operating environments, the state machine
398 will start with 64s intervals and eventually increase in steps to
400 A small amount of random variation is introduced in order to
401 avoid bunching at the servers.
402 In addition, should a server become
403 unreachable for some time, the poll interval is increased in steps
404 to 1024s in order to reduce network overhead.
406 In some cases it may not be practical for
410 A common workaround has been to run the
416 However, this program does not have the crafted signal
417 processing, error checking and mitigation algorithms of
421 option is intended for this purpose.
422 Setting this option will cause
425 setting the clock for the first time.
426 The procedure for initially
427 setting the clock is the same as in continuous mode; most
428 applications will probably want to specify the
432 configuration command.
434 keyword a volley of messages are exchanged to groom the data and
435 the clock is set in about a minute.
436 If nothing is heard after a
437 couple of minutes, the daemon times out and exits.
439 period of mourning, the
444 When kernel support is available to discipline the clock
445 frequency, which is the case for stock Solaris, Tru64, Linux and
447 a useful feature is available to discipline the clock
451 is run in continuous mode with
452 selected servers in order to measure and record the intrinsic clock
453 frequency offset in the frequency file.
454 It may take some hours for
455 the frequency and offset to settle down.
459 stopped and run in one-time mode as required.
461 frequency is read from the file and initializes the kernel
463 .Ss "Poll Interval Control"
464 This version of NTP includes an intricate state machine to
465 reduce the network load while maintaining a quality of
466 synchronization consistent with the observed jitter and wander.
467 There are a number of ways to tailor the operation in order enhance
468 accuracy by reducing the interval or to reduce network overhead by
470 However, the user is advised to carefully consider
471 the consequences of changing the poll adjustment range from the
472 default minimum of 64 s to the default maximum of 1,024 s.
474 default minimum can be changed with the
477 command to a value not less than 16 s.
478 This value is used for all
479 configured associations, unless overridden by the
481 option on the configuration command.
482 Note that most device drivers
483 will not operate properly if the poll interval is less than 64 s
484 and that the broadcast server and manycast client associations will
485 also use the default, unless overridden.
487 In some cases involving dial up or toll services, it may be
488 useful to increase the minimum interval to a few tens of minutes
489 and maximum interval to a day or so.
490 Under normal operation
491 conditions, once the clock discipline loop has stabilized the
492 interval will be increased in steps from the minimum to the
494 However, this assumes the intrinsic clock frequency error
495 is small enough for the discipline loop correct it.
497 range of the loop is 500 PPM at an interval of 64s decreasing by a
498 factor of two for each doubling of interval.
499 At a minimum of 1,024
500 s, for example, the capture range is only 31 PPM.
502 error is greater than this, the drift file
505 have to be specially tailored to reduce the residual error below
507 Once this is done, the drift file is automatically
508 updated once per hour and is available to initialize the frequency
509 on subsequent daemon restarts.
510 .Ss "The huff-n'-puff filter"
511 In scenarios where a considerable amount of data are to be
512 downloaded or uploaded over telephone modems, timekeeping quality
513 can be seriously degraded.
514 This occurs because the differential
515 delays on the two directions of transmission can be quite large.
517 many cases the apparent time errors are so large as to exceed the
518 step threshold and a step correction can occur during and after the
519 data transfer is in progress.
521 The huff-n'-puff filter is designed to correct the apparent time
522 offset in these cases.
523 It depends on knowledge of the propagation
524 delay when no other traffic is present.
525 In common scenarios this
526 occurs during other than work hours.
527 The filter maintains a shift
528 register that remembers the minimum delay over the most recent
529 interval measured usually in hours.
530 Under conditions of severe
531 delay, the filter corrects the apparent offset using the sign of
532 the offset and the difference between the apparent delay and
534 The name of the filter reflects the negative (huff)
535 and positive (puff) correction, which depends on the sign of the
538 The filter is activated by the
539 .Ic tinker command and
541 keyword, as described in
544 .Bl -tag -width /etc/ntp.drift -compact
546 the default name of the configuration file
547 .It Pa /etc/ntp.drift
548 the default name of the drift file
550 the default name of the key file
558 In addition to the manual pages provided,
559 comprehensive documentation is available on the world wide web
561 .Li http://www.ntp.org/ .
562 A snapshot of this documentation is available in HTML format in
563 .Pa /usr/share/doc/ntp .
566 .%T Network Time Protocol (Version 1)
571 .%T Network Time Protocol (Version 2)
576 .%T Network Time Protocol (Version 3)
582 utility has gotten rather fat.
583 While not huge, it has gotten
584 larger than might be desirable for an elevated-priority
586 running on a workstation, particularly since many of
587 the fancy features which consume the space were designed more with
588 a busy primary server, rather than a high stratum workstation in