1 /* -*- Mode: Text -*- */
3 autogen definitions options;
8 prog-title = "NTP daemon program";
9 argument = "[ <server1> ... <serverN> ]";
11 #include ntpdbase-opts.def
13 /* explain: Additional information whenever the usage routine is invoked */
14 explain = <<- _END_EXPLAIN
18 ds-type = 'DESCRIPTION';
20 ds-text = <<- _END_PROG_MDOC_DESCRIP
23 utility is an operating system daemon which sets
24 and maintains the system time of day in synchronism with Internet
25 standard time servers.
26 It is a complete implementation of the
27 Network Time Protocol (NTP) version 4, as defined by RFC-5905,
28 but also retains compatibility with
29 version 3, as defined by RFC-1305, and versions 1
30 and 2, as defined by RFC-1059 and RFC-1119, respectively.
34 utility does most computations in 64-bit floating point
35 arithmetic and does relatively clumsy 64-bit fixed point operations
36 only when necessary to preserve the ultimate precision, about 232
38 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.
46 configuration file at startup time in order to determine the
47 synchronization sources and operating modes.
48 It is also possible to
49 specify a working, although limited, configuration entirely on the
50 command line, obviating the need for a configuration file.
52 be particularly useful when the local host is to be configured as a
53 broadcast/multicast client, with all peers being determined by
54 listening to broadcasts at run time.
56 If NetInfo support is built into
60 will attempt to read its configuration from the
61 NetInfo if the default
63 file cannot be read and no file is
70 variables can be displayed and
71 configuration options altered while the
82 starts it looks at the value of
89 _END_PROG_MDOC_DESCRIP;
95 ds-text = <<- _END_MDOC_USAGE
96 .Ss "How NTP Operates"
99 utility operates by exchanging messages with
100 one or more configured servers over a range of designated poll intervals.
102 started, whether for the first or subsequent times, the program
103 requires several exchanges from the majority of these servers so
104 the signal processing and mitigation algorithms can accumulate and
105 groom the data and set the clock.
106 In order to protect the network
107 from bursts, the initial poll interval for each server is delayed
108 an interval randomized over a few seconds.
109 At the default initial poll
110 interval of 64s, several minutes can elapse before the clock is
112 This initial delay to set the clock
113 can be safely and dramatically reduced using the
118 command, as described in
121 Most operating systems and hardware of today incorporate a
122 time-of-year (TOY) chip to maintain the time during periods when
124 When the machine is booted, the chip is used to
125 initialize the operating system time.
126 After the machine has
127 synchronized to a NTP server, the operating system corrects the
128 chip from time to time.
129 In the default case, if
131 detects that the time on the host
132 is more than 1000s from the server time,
134 assumes something must be terribly wrong and the only
135 reliable action is for the operator to intervene and set the clock
137 (Reasons for this include there is no TOY chip,
138 or its battery is dead, or that the TOY chip is just of poor quality.)
141 to exit with a panic message to
145 option overrides this check and the
146 clock will be set to the server time regardless of the chip time
147 (up to 68 years in the past or future \(em
148 this is a limitation of the NTPv4 protocol).
149 However, and to protect against broken hardware, such as when the
150 CMOS battery fails or the clock counter becomes defective, once the
151 clock has been set an error greater than 1000s will cause
155 Under ordinary conditions,
158 small steps so that the timescale is effectively continuous and
159 without discontinuities.
160 Under conditions of extreme network
161 congestion, the roundtrip delay jitter can exceed three seconds and
162 the synchronization distance, which is equal to one-half the
163 roundtrip delay plus error budget terms, can become very large.
166 algorithms discard sample offsets exceeding 128 ms,
167 unless the interval during which no sample offset is less than 128
169 The first sample after that, no matter what the
170 offset, steps the clock to the indicated time.
172 reduces the false alarm rate where the clock is stepped in error to
173 a vanishingly low incidence.
175 As the result of this behavior, once the clock has been set it
176 very rarely strays more than 128 ms even under extreme cases of
177 network path congestion and jitter.
178 Sometimes, in particular when
180 is first started without a valid drift file
181 on a system with a large intrinsic drift
182 the error might grow to exceed 128 ms,
183 which would cause the clock to be set backwards
184 if the local clock time is more than 128 s
185 in the future relative to the server.
186 In some applications, this behavior may be unacceptable.
187 There are several solutions, however.
190 option is included on the command line, the clock will
191 never be stepped and only slew corrections will be used.
192 But this choice comes with a cost that
193 should be carefully explored before deciding to use
197 The maximum slew rate possible is limited
198 to 500 parts-per-million (PPM) as a consequence of the correctness
199 principles on which the NTP protocol and algorithm design are
201 As a result, the local clock can take a long time to
202 converge to an acceptable offset, about 2,000 s for each second the
203 clock is outside the acceptable range.
204 During this interval the
205 local clock will not be consistent with any other network clock and
206 the system cannot be used for distributed applications that require
207 correctly synchronized network time.
209 In spite of the above precautions, sometimes when large
210 frequency errors are present the resulting time offsets stray
211 outside the 128-ms range and an eventual step or slew time
212 correction is required.
213 If following such a correction the
214 frequency error is so large that the first sample is outside the
217 enters the same state as when the
220 The intent of this behavior
221 is to quickly correct the frequency and restore operation to the
222 normal tracking mode.
223 In the most extreme cases
226 comes to mind), there may be occasional
227 step/slew corrections and subsequent frequency corrections.
229 helps in these cases to use the
232 configuring the server, but
234 when you have permission to do so from the owner of the target host.
237 in the past many startup scripts would run
238 .Xr ntpdate 1ntpdatemdoc
241 to get the system clock close to correct before starting
243 but this was never more than a mediocre hack and is no longer needed.
244 If you are following the instructions in
245 .Sx "Starting NTP (Best Current Practice)"
246 and you still need to set the system time before starting
248 please open a bug report and document what is going on,
249 and then look at using
251 if you really need to set the clock before starting
254 There is a way to start
256 that often addresses all of the problems mentioned above.
257 .Ss "Starting NTP (Best Current Practice)"
264 If you can also keep a good
268 will effectively "warm-start" and your system's clock will
269 be stable in under 11 seconds' time.
271 As soon as possible in the startup sequence, start
279 start the rest of your "normal" processes.
282 as much time as possible to get the system's clock synchronized and stable.
285 if you have processes like
289 monotonically-increasing time,
291 .Xr ntp-wait 1ntp-waitmdoc
292 as late as possible in the boot sequence
297 .Xr ntp-wait 1ntp-waitmdoc
299 it is as safe as it will ever be to start any process that require
301 .Ss "Frequency Discipline"
304 behavior at startup depends on whether the
305 frequency file, usually
309 contains the latest estimate of clock frequency error.
312 is started and the file does not exist, the
314 enters a special mode designed to quickly adapt to
315 the particular system clock oscillator time and frequency error.
316 This takes approximately 15 minutes, after which the time and
317 frequency are set to nominal values and the
320 normal mode, where the time and frequency are continuously tracked
321 relative to the server.
322 After one hour the frequency file is
323 created and the current frequency offset written to it.
326 is started and the file does exist, the
328 frequency is initialized from the file and enters normal mode
330 After that the current frequency offset is written to
331 the file at hourly intervals.
332 .Ss "Operating Modes"
335 utility can operate in any of several modes, including
336 symmetric active/passive, client/server broadcast/multicast and
337 manycast, as described in the
338 .Qq Association Management
340 (available as part of the HTML documentation
342 .Pa /usr/share/doc/ntp ) .
343 It normally operates continuously while
344 monitoring for small changes in frequency and trimming the clock
345 for the ultimate precision.
346 However, it can operate in a one-time
347 mode where the time is set from an external server and frequency is
348 set from a previously recorded frequency file.
350 broadcast/multicast or manycast client can discover remote servers,
351 compute server-client propagation delay correction factors and
352 configure itself automatically.
353 This makes it possible to deploy a
354 fleet of workstations without specifying configuration details
355 specific to the local environment.
359 runs in continuous mode where each of
360 possibly several external servers is polled at intervals determined
361 by an intricate state machine.
362 The state machine measures the
363 incidental roundtrip delay jitter and oscillator frequency wander
364 and determines the best poll interval using a heuristic algorithm.
365 Ordinarily, and in most operating environments, the state machine
366 will start with 64s intervals and eventually increase in steps to
368 A small amount of random variation is introduced in order to
369 avoid bunching at the servers.
370 In addition, should a server become
371 unreachable for some time, the poll interval is increased in steps
372 to 1024s in order to reduce network overhead.
374 In some cases it may not be practical for
377 A common workaround has been to run the
378 .Xr ntpdate 1ntpdatemdoc
385 However, these programs do not have the crafted signal
386 processing, error checking or mitigation algorithms of
390 option is intended for this purpose.
391 Setting this option will cause
394 setting the clock for the first time.
395 The procedure for initially
396 setting the clock is the same as in continuous mode; most
397 applications will probably want to specify the
401 configuration command.
403 keyword a volley of messages are exchanged to groom the data and
404 the clock is set in about 10 s.
405 If nothing is heard after a
406 couple of minutes, the daemon times out and exits.
408 period of mourning, the
409 .Xr ntpdate 1ntpdatemdoc
413 When kernel support is available to discipline the clock
414 frequency, which is the case for stock Solaris, Tru64, Linux and
416 a useful feature is available to discipline the clock
420 is run in continuous mode with
421 selected servers in order to measure and record the intrinsic clock
422 frequency offset in the frequency file.
423 It may take some hours for
424 the frequency and offset to settle down.
428 stopped and run in one-time mode as required.
430 frequency is read from the file and initializes the kernel
432 .Ss "Poll Interval Control"
433 This version of NTP includes an intricate state machine to
434 reduce the network load while maintaining a quality of
435 synchronization consistent with the observed jitter and wander.
436 There are a number of ways to tailor the operation in order enhance
437 accuracy by reducing the interval or to reduce network overhead by
439 However, the user is advised to carefully consider
440 the consequences of changing the poll adjustment range from the
441 default minimum of 64 s to the default maximum of 1,024 s.
443 default minimum can be changed with the
446 command to a value not less than 16 s.
447 This value is used for all
448 configured associations, unless overridden by the
450 option on the configuration command.
451 Note that most device drivers
452 will not operate properly if the poll interval is less than 64 s
453 and that the broadcast server and manycast client associations will
454 also use the default, unless overridden.
456 In some cases involving dial up or toll services, it may be
457 useful to increase the minimum interval to a few tens of minutes
458 and maximum interval to a day or so.
459 Under normal operation
460 conditions, once the clock discipline loop has stabilized the
461 interval will be increased in steps from the minimum to the
463 However, this assumes the intrinsic clock frequency error
464 is small enough for the discipline loop correct it.
466 range of the loop is 500 PPM at an interval of 64s decreasing by a
467 factor of two for each doubling of interval.
468 At a minimum of 1,024
469 s, for example, the capture range is only 31 PPM.
471 error is greater than this, the drift file
474 have to be specially tailored to reduce the residual error below
476 Once this is done, the drift file is automatically
477 updated once per hour and is available to initialize the frequency
478 on subsequent daemon restarts.
479 .Ss "The huff-n'-puff Filter"
480 In scenarios where a considerable amount of data are to be
481 downloaded or uploaded over telephone modems, timekeeping quality
482 can be seriously degraded.
483 This occurs because the differential
484 delays on the two directions of transmission can be quite large.
486 many cases the apparent time errors are so large as to exceed the
487 step threshold and a step correction can occur during and after the
488 data transfer is in progress.
490 The huff-n'-puff filter is designed to correct the apparent time
491 offset in these cases.
492 It depends on knowledge of the propagation
493 delay when no other traffic is present.
494 In common scenarios this
495 occurs during other than work hours.
496 The filter maintains a shift
497 register that remembers the minimum delay over the most recent
498 interval measured usually in hours.
499 Under conditions of severe
500 delay, the filter corrects the apparent offset using the sign of
501 the offset and the difference between the apparent delay and
503 The name of the filter reflects the negative (huff)
504 and positive (puff) correction, which depends on the sign of the
507 The filter is activated by the
511 keyword, as described in
519 ds-text = <<- _END_MDOC_FILES
520 .Bl -tag -width /etc/ntp.drift -compact
522 the default name of the configuration file
523 .It Pa /etc/ntp.drift
524 the default name of the drift file
526 the default name of the key file
532 ds-type = 'SEE ALSO';
534 ds-text = <<- _END_MDOC_SEE_ALSO
536 .Xr ntpdate 1ntpdatemdoc ,
537 .Xr ntpdc 1ntpdcmdoc ,
541 In addition to the manual pages provided,
542 comprehensive documentation is available on the world wide web
544 .Li http://www.ntp.org/ .
545 A snapshot of this documentation is available in HTML format in
546 .Pa /usr/share/doc/ntp .
549 .%T Network Time Protocol (Version 1)
554 .%T Network Time Protocol (Version 2)
559 .%T Network Time Protocol (Version 3)
567 .%T Network Time Protocol Version 4: Protocol and Algorithms Specification
573 .%T Network Time Protocol Version 4: Autokey Specification
580 .%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)
586 .%T Network Time Protocol (NTP) Server Option for DHCPv6
595 ds-text = <<- _END_MDOC_BUGS
598 utility has gotten rather fat.
599 While not huge, it has gotten
600 larger than might be desirable for an elevated-priority
602 running on a workstation, particularly since many of
603 the fancy features which consume the space were designed more with
604 a busy primary server, rather than a high stratum workstation in
612 ds-text = <<- _END_MDOC_NOTES
613 Portions of this document came from FreeBSD.