2 .Dt NTPD 8 User Commands
4 .\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc)
8 .\" It has been AutoGen-ed February 4, 2015 at 02:42:12 AM by AutoGen 5.18.5pre4
9 .\" From the definitions ntpd-opts.def
10 .\" and the template file agmdoc-cmd.tpl
13 .Nd NTP daemon program
16 .\" Mixture of short (flag) options and long options
18 .Op Fl flag Op Ar value
19 .Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
20 [ <server1> ... <serverN> ]
25 utility is an operating system daemon which sets
26 and maintains the system time of day in synchronism with Internet
27 standard time servers.
28 It is a complete implementation of the
29 Network Time Protocol (NTP) version 4, as defined by RFC\-5905,
30 but also retains compatibility with
31 version 3, as defined by RFC\-1305, and versions 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
94 Force IPv4 DNS name resolution.
95 This option must not appear in combination with any of the following options:
98 Force DNS resolution of following host names on the command line
99 to the IPv4 namespace.
101 Force IPv6 DNS name resolution.
102 This option must not appear in combination with any of the following options:
105 Force DNS resolution of following host names on the command line
106 to the IPv6 namespace.
107 .It Fl a , Fl \-authreq
108 Require crypto authentication.
109 This option must not appear in combination with any of the following options:
112 Require cryptographic authentication for broadcast client,
113 multicast client and symmetric passive associations.
115 .It Fl A , Fl \-authnoreq
116 Do not require crypto authentication.
117 This option must not appear in combination with any of the following options:
120 Do not require cryptographic authentication for broadcast client,
121 multicast client and symmetric passive associations.
122 This is almost never a good idea.
123 .It Fl b , Fl \-bcastsync
124 Allow us to sync to broadcast servers.
126 .It Fl c Ar string , Fl \-configfile Ns = Ns Ar string
127 configuration file name.
129 The name and path of the configuration file,
132 .It Fl d , Fl \-debug\-level
133 Increase debug verbosity level.
134 This option may appear an unlimited number of times.
136 .It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
137 Set the debug verbosity level.
138 This option may appear an unlimited number of times.
139 This option takes an integer number as its argument.
141 .It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string
142 frequency drift file name.
144 The name and path of the frequency file,
147 This is the same operation as the
148 \fBdriftfile\fP \fIdriftfile\fP
149 configuration specification in the
152 .It Fl g , Fl \-panicgate
153 Allow the first adjustment to be Big.
154 This option may appear an unlimited number of times.
158 exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that,
160 will exit with a message to the system log. This option can be used with the
167 configuration file directive for other options.
168 .It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string
171 Chroot the server to the directory
174 This option also implies that the server attempts to drop root privileges at startup.
175 You may need to also specify a
178 This option is only available if the OS supports adjusting the clock
179 without full root privileges.
180 This option is supported under NetBSD (configure with
181 \fB\-\-enable\-clockctl\fP) or Linux (configure with
182 \fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP).
183 .It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface
184 Listen on an interface name or address.
185 This option may appear an unlimited number of times.
187 Open the network address given, or all the addresses associated with the
188 given interface name. This option may appear multiple times. This option
189 also implies not opening other addresses, except wildcard and localhost.
190 This option is deprecated. Please consider using the configuration file
191 \fBinterface\fP command, which is more versatile.
192 .It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string
193 path to symmetric keys.
195 Specify the name and path of the symmetric key file.
198 This is the same operation as the
199 \fBkeys\fP \fIkeyfile\fP
200 configuration file directive.
201 .It Fl l Ar string , Fl \-logfile Ns = Ns Ar string
202 path to the log file.
204 Specify the name and path of the log file.
205 The default is the system log file.
206 This is the same operation as the
207 \fBlogfile\fP \fIlogfile\fP
208 configuration file directive.
209 .It Fl L , Fl \-novirtualips
210 Do not listen to virtual interfaces.
212 Do not listen to virtual interfaces, defined as those with
213 names containing a colon. This option is deprecated. Please
214 consider using the configuration file \fBinterface\fP command, which
216 .It Fl M , Fl \-modifymmtimer
217 Modify Multimedia Timer (Windows only).
219 Set the Windows Multimedia Timer to highest resolution. This
220 ensures the resolution does not change while ntpd is running,
221 avoiding timekeeping glitches associated with changes.
222 .It Fl n , Fl \-nofork
224 This option must not appear in combination with any of the following options:
228 Run at high priority.
230 To the extent permitted by the operating system, run
232 at the highest priority.
233 .It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string
234 path to the PID file.
236 Specify the name and path of the file used to record
239 This is the same operation as the
240 \fBpidfile\fP \fIpidfile\fP
241 configuration file directive.
242 .It Fl P Ar number , Fl \-priority Ns = Ns Ar number
244 This option takes an integer number as its argument.
246 To the extent permitted by the operating system, run
249 \fBsched_setscheduler(SCHED_FIFO)\fP
252 Set the time and quit.
253 This option must not appear in combination with any of the following options:
254 saveconfigquit, wait\-sync.
257 will not daemonize and will exit after the clock is first
258 synchronized. This behavior mimics that of the
260 program, which will soon be replaced with a shell script.
265 options can be used with this option.
266 Note: The kernel time discipline is disabled with this option.
267 .It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string
268 Broadcast/propagation delay.
270 Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol.
271 .It Fl \-saveconfigquit Ns = Ns Ar string
272 Save parsed configuration and quit.
273 This option must not appear in combination with any of the following options:
276 Cause \fBntpd\fP to parse its startup configuration file and save an
277 equivalent to the given filename and exit. This option was
278 designed for automated testing.
279 .It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string
280 Statistics file location.
282 Specify the directory path for files created by the statistics facility.
283 This is the same operation as the
284 \fBstatsdir\fP \fIstatsdir\fP
285 configuration file directive.
286 .It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey
288 This option may appear an unlimited number of times.
290 Add the specified key number to the trusted key list.
291 .It Fl u Ar string , Fl \-user Ns = Ns Ar string
292 Run as userid (or userid:groupid).
294 Specify a user, and optionally a group, to switch to.
295 This option is only available if the OS supports adjusting the clock
296 without full root privileges.
297 This option is supported under NetBSD (configure with
298 \fB\-\-enable\-clockctl\fP) or Linux (configure with
299 \fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP).
300 .It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number
301 interval in seconds between scans for new or dropped interfaces.
302 This option takes an integer number as its argument.
304 Give the time in seconds between two scans for new or dropped interfaces.
305 For systems with routing socket support the scans will be performed shortly after the interface change
306 has been detected by the system.
307 Use 0 to disable scanning. 60 seconds is the minimum time between scans.
308 .It Fl \-var Ns = Ns Ar nvar
309 make ARG an ntp variable (RW).
310 This option may appear an unlimited number of times.
312 .It Fl \-dvar Ns = Ns Ar ndvar
313 make ARG an ntp variable (RW|DEF).
314 This option may appear an unlimited number of times.
316 .It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number
317 Seconds to wait for first clock sync.
318 This option must not appear in combination with any of the following options:
319 nofork, quit, saveconfigquit.
320 This option takes an integer number as its argument.
322 If greater than zero, alters \fBntpd\fP's behavior when forking to
323 daemonize. Instead of exiting with status 0 immediately after
324 the fork, the parent waits up to the specified number of
325 seconds for the child to first synchronize the clock. The exit
326 status is zero (success) if the clock was synchronized,
327 otherwise it is \fBETIMEDOUT\fP.
328 This provides the option for a script starting \fBntpd\fP to easily
329 wait for the first set of the clock before proceeding.
331 Slew up to 600 seconds.
333 Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold.
334 This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually.
335 Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s.
336 Thus, an adjustment as much as 600 s will take almost 14 days to complete.
337 This option can be used with the
344 configuration file directive for other options.
345 Note: The kernel time discipline is disabled with this option.
347 Use CPU cycle counter (Windows only).
349 Attempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP.
350 The CPU counter and \fBQueryPerformanceCounter\fP are compared, and if
351 they have the same frequency, the CPU counter (RDTSC on x86) is
352 used directly, saving the overhead of a system call.
353 .It Fl \-pccfreq Ns = Ns Ar string
354 Force CPU cycle counter use (Windows only).
356 Force substitution the CPU counter for \fBQueryPerformanceCounter\fP.
357 The CPU counter (RDTSC on x86) is used unconditionally with the
358 given frequency (in Hz).
360 Register with mDNS as a NTP server.
362 Registers as an NTP server with the local mDNS server which allows
363 the server to be discovered via mDNS client lookup.
364 .It Fl \&? , Fl \-help
365 Display usage information and exit.
366 .It Fl \&! , Fl \-more\-help
367 Pass the extended usage information through a pager.
368 .It Fl \-version Op Brq Ar v|c|n
369 Output version of program and exit. The default mode is `v', a simple
370 version. The `c' mode will print copyright information and `n' will
371 print the full copyright notice.
374 Any option that is not marked as \fInot presettable\fP may be preset
375 by loading values from environment variables named:
377 \fBNTPD_<option\-name>\fP or \fBNTPD\fP
381 .Ss "How NTP Operates"
384 utility operates by exchanging messages with
385 one or more configured servers over a range of designated poll intervals.
387 started, whether for the first or subsequent times, the program
388 requires several exchanges from the majority of these servers so
389 the signal processing and mitigation algorithms can accumulate and
390 groom the data and set the clock.
391 In order to protect the network
392 from bursts, the initial poll interval for each server is delayed
393 an interval randomized over a few seconds.
394 At the default initial poll
395 interval of 64s, several minutes can elapse before the clock is
397 This initial delay to set the clock
398 can be safely and dramatically reduced using the
403 command, as described in
406 Most operating systems and hardware of today incorporate a
407 time\-of\-year (TOY) chip to maintain the time during periods when
409 When the machine is booted, the chip is used to
410 initialize the operating system time.
411 After the machine has
412 synchronized to a NTP server, the operating system corrects the
413 chip from time to time.
414 In the default case, if
416 detects that the time on the host
417 is more than 1000s from the server time,
419 assumes something must be terribly wrong and the only
420 reliable action is for the operator to intervene and set the clock
422 (Reasons for this include there is no TOY chip,
423 or its battery is dead, or that the TOY chip is just of poor quality.)
426 to exit with a panic message to
430 option overrides this check and the
431 clock will be set to the server time regardless of the chip time
432 (up to 68 years in the past or future \(em
433 this is a limitation of the NTPv4 protocol).
434 However, and to protect against broken hardware, such as when the
435 CMOS battery fails or the clock counter becomes defective, once the
436 clock has been set an error greater than 1000s will cause
440 Under ordinary conditions,
443 small steps so that the timescale is effectively continuous and
444 without discontinuities.
445 Under conditions of extreme network
446 congestion, the roundtrip delay jitter can exceed three seconds and
447 the synchronization distance, which is equal to one\-half the
448 roundtrip delay plus error budget terms, can become very large.
451 algorithms discard sample offsets exceeding 128 ms,
452 unless the interval during which no sample offset is less than 128
454 The first sample after that, no matter what the
455 offset, steps the clock to the indicated time.
457 reduces the false alarm rate where the clock is stepped in error to
458 a vanishingly low incidence.
460 As the result of this behavior, once the clock has been set it
461 very rarely strays more than 128 ms even under extreme cases of
462 network path congestion and jitter.
463 Sometimes, in particular when
465 is first started without a valid drift file
466 on a system with a large intrinsic drift
467 the error might grow to exceed 128 ms,
468 which would cause the clock to be set backwards
469 if the local clock time is more than 128 s
470 in the future relative to the server.
471 In some applications, this behavior may be unacceptable.
472 There are several solutions, however.
475 option is included on the command line, the clock will
476 never be stepped and only slew corrections will be used.
477 But this choice comes with a cost that
478 should be carefully explored before deciding to use
482 The maximum slew rate possible is limited
483 to 500 parts\-per\-million (PPM) as a consequence of the correctness
484 principles on which the NTP protocol and algorithm design are
486 As a result, the local clock can take a long time to
487 converge to an acceptable offset, about 2,000 s for each second the
488 clock is outside the acceptable range.
489 During this interval the
490 local clock will not be consistent with any other network clock and
491 the system cannot be used for distributed applications that require
492 correctly synchronized network time.
494 In spite of the above precautions, sometimes when large
495 frequency errors are present the resulting time offsets stray
496 outside the 128\-ms range and an eventual step or slew time
497 correction is required.
498 If following such a correction the
499 frequency error is so large that the first sample is outside the
502 enters the same state as when the
505 The intent of this behavior
506 is to quickly correct the frequency and restore operation to the
507 normal tracking mode.
508 In the most extreme cases
511 comes to mind), there may be occasional
512 step/slew corrections and subsequent frequency corrections.
514 helps in these cases to use the
517 configuring the server, but
519 when you have permission to do so from the owner of the target host.
522 in the past many startup scripts would run
524 to get the system clock close to correct before starting
526 but this was never more than a mediocre hack and is no longer needed.
527 If you are following the instructions in
528 .Sx "Starting NTP (Best Current Practice)"
529 and you still need to set the system time before starting
531 please open a bug report and document what is going on,
532 and then look at using
535 There is a way to start
537 that often addresses all of the problems mentioned above.
538 .Ss "Starting NTP (Best Current Practice)"
545 If you can also keep a good
549 will effectively "warm\-start" and your system's clock will
550 be stable in under 11 seconds' time.
552 As soon as possible in the startup sequence, start
560 start the rest of your "normal" processes.
563 as much time as possible to get the system's clock synchronized and stable.
566 if you have processes like
570 monotonically\-increasing time,
572 .Xr ntp\-wait 1ntp\-waitmdoc
573 as late as possible in the boot sequence
578 .Xr ntp\-wait 1ntp\-waitmdoc
580 it is as safe as it will ever be to start any process that require
582 .Ss "Frequency Discipline"
585 behavior at startup depends on whether the
586 frequency file, usually
590 contains the latest estimate of clock frequency error.
593 is started and the file does not exist, the
595 enters a special mode designed to quickly adapt to
596 the particular system clock oscillator time and frequency error.
597 This takes approximately 15 minutes, after which the time and
598 frequency are set to nominal values and the
601 normal mode, where the time and frequency are continuously tracked
602 relative to the server.
603 After one hour the frequency file is
604 created and the current frequency offset written to it.
607 is started and the file does exist, the
609 frequency is initialized from the file and enters normal mode
611 After that the current frequency offset is written to
612 the file at hourly intervals.
613 .Ss "Operating Modes"
616 utility can operate in any of several modes, including
617 symmetric active/passive, client/server broadcast/multicast and
618 manycast, as described in the
619 .Qq Association Management
621 (available as part of the HTML documentation
623 .Pa /usr/share/doc/ntp ) .
624 It normally operates continuously while
625 monitoring for small changes in frequency and trimming the clock
626 for the ultimate precision.
627 However, it can operate in a one\-time
628 mode where the time is set from an external server and frequency is
629 set from a previously recorded frequency file.
631 broadcast/multicast or manycast client can discover remote servers,
632 compute server\-client propagation delay correction factors and
633 configure itself automatically.
634 This makes it possible to deploy a
635 fleet of workstations without specifying configuration details
636 specific to the local environment.
640 runs in continuous mode where each of
641 possibly several external servers is polled at intervals determined
642 by an intricate state machine.
643 The state machine measures the
644 incidental roundtrip delay jitter and oscillator frequency wander
645 and determines the best poll interval using a heuristic algorithm.
646 Ordinarily, and in most operating environments, the state machine
647 will start with 64s intervals and eventually increase in steps to
649 A small amount of random variation is introduced in order to
650 avoid bunching at the servers.
651 In addition, should a server become
652 unreachable for some time, the poll interval is increased in steps
653 to 1024s in order to reduce network overhead.
655 In some cases it may not be practical for
658 A common workaround has been to run the
666 However, these programs do not have the crafted signal
667 processing, error checking or mitigation algorithms of
671 option is intended for this purpose.
672 Setting this option will cause
675 setting the clock for the first time.
676 The procedure for initially
677 setting the clock is the same as in continuous mode; most
678 applications will probably want to specify the
682 configuration command.
684 keyword a volley of messages are exchanged to groom the data and
685 the clock is set in about 10 s.
686 If nothing is heard after a
687 couple of minutes, the daemon times out and exits.
689 period of mourning, the
694 When kernel support is available to discipline the clock
695 frequency, which is the case for stock Solaris, Tru64, Linux and
697 a useful feature is available to discipline the clock
701 is run in continuous mode with
702 selected servers in order to measure and record the intrinsic clock
703 frequency offset in the frequency file.
704 It may take some hours for
705 the frequency and offset to settle down.
709 stopped and run in one\-time mode as required.
711 frequency is read from the file and initializes the kernel
713 .Ss "Poll Interval Control"
714 This version of NTP includes an intricate state machine to
715 reduce the network load while maintaining a quality of
716 synchronization consistent with the observed jitter and wander.
717 There are a number of ways to tailor the operation in order enhance
718 accuracy by reducing the interval or to reduce network overhead by
720 However, the user is advised to carefully consider
721 the consequences of changing the poll adjustment range from the
722 default minimum of 64 s to the default maximum of 1,024 s.
724 default minimum can be changed with the
727 command to a value not less than 16 s.
728 This value is used for all
729 configured associations, unless overridden by the
731 option on the configuration command.
732 Note that most device drivers
733 will not operate properly if the poll interval is less than 64 s
734 and that the broadcast server and manycast client associations will
735 also use the default, unless overridden.
737 In some cases involving dial up or toll services, it may be
738 useful to increase the minimum interval to a few tens of minutes
739 and maximum interval to a day or so.
740 Under normal operation
741 conditions, once the clock discipline loop has stabilized the
742 interval will be increased in steps from the minimum to the
744 However, this assumes the intrinsic clock frequency error
745 is small enough for the discipline loop correct it.
747 range of the loop is 500 PPM at an interval of 64s decreasing by a
748 factor of two for each doubling of interval.
749 At a minimum of 1,024
750 s, for example, the capture range is only 31 PPM.
752 error is greater than this, the drift file
755 have to be specially tailored to reduce the residual error below
757 Once this is done, the drift file is automatically
758 updated once per hour and is available to initialize the frequency
759 on subsequent daemon restarts.
760 .Ss "The huff\-n'\-puff Filter"
761 In scenarios where a considerable amount of data are to be
762 downloaded or uploaded over telephone modems, timekeeping quality
763 can be seriously degraded.
764 This occurs because the differential
765 delays on the two directions of transmission can be quite large.
767 many cases the apparent time errors are so large as to exceed the
768 step threshold and a step correction can occur during and after the
769 data transfer is in progress.
771 The huff\-n'\-puff filter is designed to correct the apparent time
772 offset in these cases.
773 It depends on knowledge of the propagation
774 delay when no other traffic is present.
775 In common scenarios this
776 occurs during other than work hours.
777 The filter maintains a shift
778 register that remembers the minimum delay over the most recent
779 interval measured usually in hours.
780 Under conditions of severe
781 delay, the filter corrects the apparent offset using the sign of
782 the offset and the difference between the apparent delay and
784 The name of the filter reflects the negative (huff)
785 and positive (puff) correction, which depends on the sign of the
788 The filter is activated by the
792 keyword, as described in
795 See \fBOPTION PRESETS\fP for configuration environment variables.
797 .Bl -tag -width /etc/ntp.drift -compact
799 the default name of the configuration file
800 .It Pa /etc/ntp.drift
801 the default name of the drift file
803 the default name of the key file
806 One of the following exit values will be returned:
808 .It 0 " (EXIT_SUCCESS)"
809 Successful program execution.
810 .It 1 " (EXIT_FAILURE)"
811 The operation failed or the command syntax was not valid.
812 .It 70 " (EX_SOFTWARE)"
813 libopts had an internal operational error. Please report
814 it to autogen\-users@lists.sourceforge.net. Thank you.
823 In addition to the manual pages provided,
824 comprehensive documentation is available on the world wide web
826 .Li http://www.ntp.org/ .
827 A snapshot of this documentation is available in HTML format in
828 .Pa /usr/share/doc/ntp .
831 .%T Network Time Protocol (Version 1)
836 .%T Network Time Protocol (Version 2)
841 .%T Network Time Protocol (Version 3)
849 .%T Network Time Protocol Version 4: Protocol and Algorithms Specification
855 .%T Network Time Protocol Version 4: Autokey Specification
862 .%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)
868 .%T Network Time Protocol (NTP) Server Option for DHCPv6
872 The University of Delaware and Network Time Foundation
874 Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved.
875 This program is released under the terms of the NTP license, <http://ntp.org/license>.
879 utility has gotten rather fat.
880 While not huge, it has gotten
881 larger than might be desirable for an elevated\-priority
883 running on a workstation, particularly since many of
884 the fancy features which consume the space were designed more with
885 a busy primary server, rather than a high stratum workstation in
888 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
890 Portions of this document came from FreeBSD.
892 This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP