9 .Nd Network Time Protocol (NTP) daemon
18 .Op Fl r Ar broadcastdelay
26 utility is an operating system daemon which sets
27 and maintains the system time of day in synchronism with Internet
28 standard time servers.
29 It is a complete implementation of the
30 Network Time Protocol (NTP) version 4, but also retains
31 compatibility with version 3, as defined by RFC-1305, and version 1
32 and 2, as defined by RFC-1059 and RFC-1119, respectively.
36 utility does most computations in 64-bit floating point
37 arithmetic and does relatively clumsy 64-bit fixed point operations
38 only when necessary to preserve the ultimate precision, about 232
40 While the ultimate precision is not achievable with
41 ordinary workstations and networks of today, it may be required
42 with future gigahertz CPU clocks and gigabit LANs.
48 configuration file at startup time in order to determine the
49 synchronization sources and operating modes.
50 It is also possible to
51 specify a working, although limited, configuration entirely on the
52 command line, obviating the need for a configuration file.
54 be particularly useful when the local host is to be configured as a
55 broadcast/multicast client, with all peers being determined by
56 listening to broadcasts at run time.
58 If NetInfo support is built into
62 will attempt to read its configuration from the
63 NetInfo if the default
65 file cannot be read and no file is
72 variables can be displayed and
73 configuration options altered while the
84 starts it looks at the value of
92 The following options are available:
93 .Bl -tag -width indent
95 Require cryptographic authentication for broadcast client,
96 multicast client and symmetric passive associations.
99 Do not require cryptographic authentication for broadcast client,
100 multicast client and symmetric passive associations.
101 This is almost never a good idea.
103 Enable the client to synchronize to broadcast servers.
105 Specify the name and path of the configuration file, default
108 Specify debugging mode.
109 This option may occur more than once,
110 with each occurrence indicating greater detail of display.
113 with DEBUG in order to use this.
115 Specify debugging level directly.
116 .It Fl f Ar driftfile
117 Specify the name and path of the frequency file, default
119 This is the same operation as the
120 .Ic driftfile Ar driftfile
121 configuration command.
125 exits with a message to the system log if the offset exceeds
126 the panic threshold, which is 1000 s by default.
127 This option allows the time to be set to any value without restriction;
128 however, this can happen only once.
129 If the threshold is exceeded after that,
131 will exit with a message to the system log.
132 This option can be used with the
139 command for other options.
141 Specify the name and path of the symmetric key file, default
143 This is the same operation as the
145 configuration command.
147 Specify the name and path of the log file.
148 The default is the system log file.
149 This is the same operation as the
150 .Ic logfile Ar logfile
151 configuration command.
153 Do not listen to virtual IPs.
154 The default is to listen.
156 Enable the client to synchronize to multicast servers at the IPv4 multicast
157 group address 224.0.1.1.
161 To the extent permitted by the operating system, run the
163 at the highest priority.
165 Specify the name and path of the file used to record the
168 This is the same operation as the
169 .Ic pidfile Ar pidfile
170 configuration command.
172 To the extent permitted by the operating system, run the
174 at the specified priority.
178 just after the first time the clock is
180 This behavior mimics that of the
183 which is to be retired.
189 be used with this option.
190 Note: The kernel time discipline is disabled with this option.
191 .It Fl r Ar broadcastdelay
192 Specify the default propagation delay from the
193 broadcast/multicast server to this client.
195 only if the delay cannot be computed automatically by the
198 Specify the directory path for files created by the statistics
200 This is the same operation as the
201 .Ic statsdir Ar statsdir
202 configuration command.
204 Add a key number to the trusted key list.
205 This option can occur more than once.
208 Add a system variable listed by default.
210 Normally, the time is slewed if the offset is less than the
211 step threshold, which is 128 ms by default, and stepped if above
213 This option sets the threshold to 600 s,
214 which is well within the accuracy window to set the clock manually.
215 Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s,
216 each second of adjustment requires an amortization interval of 2000 s.
217 Thus, an adjustment as much as 600 s will take almost 14 days to complete.
218 This option can be used with the
225 command for other options.
226 Note: The kernel time discipline is disabled with this option.
228 .Ss "How NTP Operates"
231 utility operates by exchanging messages with
232 one or more configured servers at designated poll intervals.
234 started, whether for the first or subsequent times, the program
235 requires several exchanges from the majority of these servers so
236 the signal processing and mitigation algorithms can accumulate and
237 groom the data and set the clock.
238 In order to protect the network
239 from bursts, the initial poll interval for each server is delayed
240 an interval randomized over a few seconds.
241 At the default initial poll
242 interval of 64s, several minutes can elapse before the clock is
244 The initial delay to set the clock can be reduced using the
249 command, as described in
252 Most operating systems and hardware of today incorporate a
253 time-of-year (TOY) chip to maintain the time during periods when
255 When the machine is booted, the chip is used to
256 initialize the operating system time.
257 After the machine has
258 synchronized to a NTP server, the operating system corrects the
259 chip from time to time.
260 In case there is no TOY chip or for some
261 reason its time is more than 1000s from the server time,
263 assumes something must be terribly wrong and the only
264 reliable action is for the operator to intervene and set the clock
268 to exit with a panic message to
272 option overrides this check and the
273 clock will be set to the server time regardless of the chip time.
274 However, and to protect against broken hardware, such as when the
275 CMOS battery fails or the clock counter becomes defective, once the
276 clock has been set, an error greater than 1000s will cause
280 Under ordinary conditions,
283 small steps so that the timescale is effectively continuous and
284 without discontinuities.
285 Under conditions of extreme network
286 congestion, the roundtrip delay jitter can exceed three seconds and
287 the synchronization distance, which is equal to one-half the
288 roundtrip delay plus error budget terms, can become very large.
291 algorithms discard sample offsets exceeding 128 ms,
292 unless the interval during which no sample offset is less than 128
294 The first sample after that, no matter what the
295 offset, steps the clock to the indicated time.
297 reduces the false alarm rate where the clock is stepped in error to
298 a vanishingly low incidence.
300 As the result of this behavior, once the clock has been set, it
301 very rarely strays more than 128 ms, even under extreme cases of
302 network path congestion and jitter.
303 Sometimes, in particular when
305 is first started, the error might exceed 128 ms.
307 may on occasion cause the clock to be set backwards if the local
308 clock time is more than 128 s in the future relative to the server.
309 In some applications, this behavior may be unacceptable.
312 option is included on the command line, the clock will
313 never be stepped and only slew corrections will be used.
315 The issues should be carefully explored before deciding to use
319 The maximum slew rate possible is limited
320 to 500 parts-per-million (PPM) as a consequence of the correctness
321 principles on which the NTP protocol and algorithm design are
323 As a result, the local clock can take a long time to
324 converge to an acceptable offset, about 2,000 s for each second the
325 clock is outside the acceptable range.
326 During this interval the
327 local clock will not be consistent with any other network clock and
328 the system cannot be used for distributed applications that require
329 correctly synchronized network time.
331 In spite of the above precautions, sometimes when large
332 frequency errors are present the resulting time offsets stray
333 outside the 128-ms range and an eventual step or slew time
334 correction is required.
335 If following such a correction the
336 frequency error is so large that the first sample is outside the
339 enters the same state as when the
342 The intent of this behavior
343 is to quickly correct the frequency and restore operation to the
344 normal tracking mode.
345 In the most extreme cases
348 comes to mind), there may be occasional
349 step/slew corrections and subsequent frequency corrections.
351 helps in these cases to use the
354 configuring the server.
355 .Ss "Frequency Discipline"
358 behavior at startup depends on whether the
359 frequency file, usually
363 contains the latest estimate of clock frequency error.
366 is started and the file does not exist, the
368 enters a special mode designed to quickly adapt to
369 the particular system clock oscillator time and frequency error.
370 This takes approximately 15 minutes, after which the time and
371 frequency are set to nominal values and the
374 normal mode, where the time and frequency are continuously tracked
375 relative to the server.
376 After one hour the frequency file is
377 created and the current frequency offset written to it.
380 is started and the file does exist, the
382 frequency is initialized from the file and enters normal mode
384 After that the current frequency offset is written to
385 the file at hourly intervals.
386 .Ss "Operating Modes"
389 utility can operate in any of several modes, including
390 symmetric active/passive, client/server broadcast/multicast and
391 manycast, as described in the
392 .Qq Association Management
394 (available as part of the HTML documentation
396 .Pa /usr/share/doc/ntp ) .
397 It normally operates continuously while
398 monitoring for small changes in frequency and trimming the clock
399 for the ultimate precision.
400 However, it can operate in a one-time
401 mode where the time is set from an external server and frequency is
402 set from a previously recorded frequency file.
404 broadcast/multicast or manycast client can discover remote servers,
405 compute server-client propagation delay correction factors and
406 configure itself automatically.
407 This makes it possible to deploy a
408 fleet of workstations without specifying configuration details
409 specific to the local environment.
413 runs in continuous mode where each of
414 possibly several external servers is polled at intervals determined
415 by an intricate state machine.
416 The state machine measures the
417 incidental roundtrip delay jitter and oscillator frequency wander
418 and determines the best poll interval using a heuristic algorithm.
419 Ordinarily, and in most operating environments, the state machine
420 will start with 64s intervals and eventually increase in steps to
422 A small amount of random variation is introduced in order to
423 avoid bunching at the servers.
424 In addition, should a server become
425 unreachable for some time, the poll interval is increased in steps
426 to 1024s in order to reduce network overhead.
428 In some cases it may not be practical for
432 A common workaround has been to run the
438 However, this program does not have the crafted signal
439 processing, error checking and mitigation algorithms of
443 option is intended for this purpose.
444 Setting this option will cause
447 setting the clock for the first time.
448 The procedure for initially
449 setting the clock is the same as in continuous mode; most
450 applications will probably want to specify the
454 configuration command.
456 keyword a volley of messages are exchanged to groom the data and
457 the clock is set in about 10 s.
458 If nothing is heard after a
459 couple of minutes, the daemon times out and exits.
461 period of mourning, the
466 When kernel support is available to discipline the clock
467 frequency, which is the case for stock Solaris, Tru64, Linux and
469 a useful feature is available to discipline the clock
473 is run in continuous mode with
474 selected servers in order to measure and record the intrinsic clock
475 frequency offset in the frequency file.
476 It may take some hours for
477 the frequency and offset to settle down.
481 stopped and run in one-time mode as required.
483 frequency is read from the file and initializes the kernel
485 .Ss "Poll Interval Control"
486 This version of NTP includes an intricate state machine to
487 reduce the network load while maintaining a quality of
488 synchronization consistent with the observed jitter and wander.
489 There are a number of ways to tailor the operation in order enhance
490 accuracy by reducing the interval or to reduce network overhead by
492 However, the user is advised to carefully consider
493 the consequences of changing the poll adjustment range from the
494 default minimum of 64 s to the default maximum of 1,024 s.
496 default minimum can be changed with the
499 command to a value not less than 16 s.
500 This value is used for all
501 configured associations, unless overridden by the
503 option on the configuration command.
504 Note that most device drivers
505 will not operate properly if the poll interval is less than 64 s
506 and that the broadcast server and manycast client associations will
507 also use the default, unless overridden.
509 In some cases involving dial up or toll services, it may be
510 useful to increase the minimum interval to a few tens of minutes
511 and maximum interval to a day or so.
512 Under normal operation
513 conditions, once the clock discipline loop has stabilized the
514 interval will be increased in steps from the minimum to the
516 However, this assumes the intrinsic clock frequency error
517 is small enough for the discipline loop correct it.
519 range of the loop is 500 PPM at an interval of 64s decreasing by a
520 factor of two for each doubling of interval.
521 At a minimum of 1,024
522 s, for example, the capture range is only 31 PPM.
524 error is greater than this, the drift file
527 have to be specially tailored to reduce the residual error below
529 Once this is done, the drift file is automatically
530 updated once per hour and is available to initialize the frequency
531 on subsequent daemon restarts.
532 .Ss "The huff-n'-puff Filter"
533 In scenarios where a considerable amount of data are to be
534 downloaded or uploaded over telephone modems, timekeeping quality
535 can be seriously degraded.
536 This occurs because the differential
537 delays on the two directions of transmission can be quite large.
539 many cases the apparent time errors are so large as to exceed the
540 step threshold and a step correction can occur during and after the
541 data transfer is in progress.
543 The huff-n'-puff filter is designed to correct the apparent time
544 offset in these cases.
545 It depends on knowledge of the propagation
546 delay when no other traffic is present.
547 In common scenarios this
548 occurs during other than work hours.
549 The filter maintains a shift
550 register that remembers the minimum delay over the most recent
551 interval measured usually in hours.
552 Under conditions of severe
553 delay, the filter corrects the apparent offset using the sign of
554 the offset and the difference between the apparent delay and
556 The name of the filter reflects the negative (huff)
557 and positive (puff) correction, which depends on the sign of the
560 The filter is activated by the
564 keyword, as described in
567 .Bl -tag -width /etc/ntp.drift -compact
569 the default name of the configuration file
570 .It Pa /etc/ntp.drift
571 the default name of the drift file
573 the default name of the key file
581 In addition to the manual pages provided,
582 comprehensive documentation is available on the world wide web
584 .Li http://www.ntp.org/ .
585 A snapshot of this documentation is available in HTML format in
586 .Pa /usr/share/doc/ntp .
589 .%T Network Time Protocol (Version 1)
594 .%T Network Time Protocol (Version 2)
599 .%T Network Time Protocol (Version 3)
605 utility has gotten rather fat.
606 While not huge, it has gotten
607 larger than might be desirable for an elevated-priority
609 running on a workstation, particularly since many of
610 the fancy features which consume the space were designed more with
611 a busy primary server, rather than a high stratum workstation in