2 .Dt NTPD @NTPD_MS@ User Commands
4 .\" EDIT THIS FILE WITH CAUTION (ntpd-opts.mdoc)
6 .\" It has been AutoGen-ed June 29, 2015 at 04:30:41 PM by AutoGen 5.18.5
7 .\" From the definitions ntpd-opts.def
8 .\" and the template file agmdoc-cmd.tpl
11 .Nd NTP daemon program
14 .\" Mixture of short (flag) options and long options
16 .Op Fl flag Op Ar value
17 .Op Fl \-option\-name Ns Oo Oo Ns "=| " Oc Ns Ar value Oc
18 [ <server1> ... <serverN> ]
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
92 Force IPv4 DNS name resolution.
93 This option must not appear in combination with any of the following options:
96 Force DNS resolution of following host names on the command line
97 to the IPv4 namespace.
99 Force IPv6 DNS name resolution.
100 This option must not appear in combination with any of the following options:
103 Force DNS resolution of following host names on the command line
104 to the IPv6 namespace.
105 .It Fl a , Fl \-authreq
106 Require crypto authentication.
107 This option must not appear in combination with any of the following options:
110 Require cryptographic authentication for broadcast client,
111 multicast client and symmetric passive associations.
113 .It Fl A , Fl \-authnoreq
114 Do not require crypto authentication.
115 This option must not appear in combination with any of the following options:
118 Do not require cryptographic authentication for broadcast client,
119 multicast client and symmetric passive associations.
120 This is almost never a good idea.
121 .It Fl b , Fl \-bcastsync
122 Allow us to sync to broadcast servers.
124 .It Fl c Ar string , Fl \-configfile Ns = Ns Ar string
125 configuration file name.
127 The name and path of the configuration file,
130 .It Fl d , Fl \-debug\-level
131 Increase debug verbosity level.
132 This option may appear an unlimited number of times.
134 .It Fl D Ar number , Fl \-set\-debug\-level Ns = Ns Ar number
135 Set the debug verbosity level.
136 This option may appear an unlimited number of times.
137 This option takes an integer number as its argument.
139 .It Fl f Ar string , Fl \-driftfile Ns = Ns Ar string
140 frequency drift file name.
142 The name and path of the frequency file,
145 This is the same operation as the
146 \fBdriftfile\fP \fIdriftfile\fP
147 configuration specification in the
150 .It Fl g , Fl \-panicgate
151 Allow the first adjustment to be Big.
152 This option may appear an unlimited number of times.
156 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,
158 will exit with a message to the system log. This option can be used with the
165 configuration file directive for other options.
166 .It Fl G , Fl \-force\-step\-once
167 Step any initial offset correction..
171 steps the time if the time offset exceeds the step threshold,
172 which is 128 ms by default, and otherwise slews the time.
173 This option forces the initial offset correction to be stepped,
174 so the highest time accuracy can be achieved quickly.
175 However, this may also cause the time to be stepped back
176 so this option must not be used if
177 applications requiring monotonic time are running.
178 See the \fBtinker\fP configuration file directive for other options.
179 .It Fl i Ar string , Fl \-jaildir Ns = Ns Ar string
182 Chroot the server to the directory
185 This option also implies that the server attempts to drop root privileges at startup.
186 You may need to also specify a
189 This option is only available if the OS supports adjusting the clock
190 without full root privileges.
191 This option is supported under NetBSD (configure with
192 \fB\-\-enable\-clockctl\fP) or Linux (configure with
193 \fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP).
194 .It Fl I Ar iface , Fl \-interface Ns = Ns Ar iface
195 Listen on an interface name or address.
196 This option may appear an unlimited number of times.
198 Open the network address given, or all the addresses associated with the
199 given interface name. This option may appear multiple times. This option
200 also implies not opening other addresses, except wildcard and localhost.
201 This option is deprecated. Please consider using the configuration file
202 \fBinterface\fP command, which is more versatile.
203 .It Fl k Ar string , Fl \-keyfile Ns = Ns Ar string
204 path to symmetric keys.
206 Specify the name and path of the symmetric key file.
209 This is the same operation as the
210 \fBkeys\fP \fIkeyfile\fP
211 configuration file directive.
212 .It Fl l Ar string , Fl \-logfile Ns = Ns Ar string
213 path to the log file.
215 Specify the name and path of the log file.
216 The default is the system log file.
217 This is the same operation as the
218 \fBlogfile\fP \fIlogfile\fP
219 configuration file directive.
220 .It Fl L , Fl \-novirtualips
221 Do not listen to virtual interfaces.
223 Do not listen to virtual interfaces, defined as those with
224 names containing a colon. This option is deprecated. Please
225 consider using the configuration file \fBinterface\fP command, which
227 .It Fl M , Fl \-modifymmtimer
228 Modify Multimedia Timer (Windows only).
230 Set the Windows Multimedia Timer to highest resolution. This
231 ensures the resolution does not change while ntpd is running,
232 avoiding timekeeping glitches associated with changes.
233 .It Fl n , Fl \-nofork
235 This option must not appear in combination with any of the following options:
239 Run at high priority.
241 To the extent permitted by the operating system, run
243 at the highest priority.
244 .It Fl p Ar string , Fl \-pidfile Ns = Ns Ar string
245 path to the PID file.
247 Specify the name and path of the file used to record
250 This is the same operation as the
251 \fBpidfile\fP \fIpidfile\fP
252 configuration file directive.
253 .It Fl P Ar number , Fl \-priority Ns = Ns Ar number
255 This option takes an integer number as its argument.
257 To the extent permitted by the operating system, run
260 \fBsched_setscheduler(SCHED_FIFO)\fP
263 Set the time and quit.
264 This option must not appear in combination with any of the following options:
265 saveconfigquit, wait\-sync.
268 will not daemonize and will exit after the clock is first
269 synchronized. This behavior mimics that of the
271 program, which will soon be replaced with a shell script.
276 options can be used with this option.
277 Note: The kernel time discipline is disabled with this option.
278 .It Fl r Ar string , Fl \-propagationdelay Ns = Ns Ar string
279 Broadcast/propagation delay.
281 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.
282 .It Fl \-saveconfigquit Ns = Ns Ar string
283 Save parsed configuration and quit.
284 This option must not appear in combination with any of the following options:
287 Cause \fBntpd\fP to parse its startup configuration file and save an
288 equivalent to the given filename and exit. This option was
289 designed for automated testing.
290 .It Fl s Ar string , Fl \-statsdir Ns = Ns Ar string
291 Statistics file location.
293 Specify the directory path for files created by the statistics facility.
294 This is the same operation as the
295 \fBstatsdir\fP \fIstatsdir\fP
296 configuration file directive.
297 .It Fl t Ar tkey , Fl \-trustedkey Ns = Ns Ar tkey
299 This option may appear an unlimited number of times.
301 Add the specified key number to the trusted key list.
302 .It Fl u Ar string , Fl \-user Ns = Ns Ar string
303 Run as userid (or userid:groupid).
305 Specify a user, and optionally a group, to switch to.
306 This option is only available if the OS supports adjusting the clock
307 without full root privileges.
308 This option is supported under NetBSD (configure with
309 \fB\-\-enable\-clockctl\fP) or Linux (configure with
310 \fB\-\-enable\-linuxcaps\fP) or Solaris (configure with \fB\-\-enable\-solarisprivs\fP).
311 .It Fl U Ar number , Fl \-updateinterval Ns = Ns Ar number
312 interval in seconds between scans for new or dropped interfaces.
313 This option takes an integer number as its argument.
315 Give the time in seconds between two scans for new or dropped interfaces.
316 For systems with routing socket support the scans will be performed shortly after the interface change
317 has been detected by the system.
318 Use 0 to disable scanning. 60 seconds is the minimum time between scans.
319 .It Fl \-var Ns = Ns Ar nvar
320 make ARG an ntp variable (RW).
321 This option may appear an unlimited number of times.
323 .It Fl \-dvar Ns = Ns Ar ndvar
324 make ARG an ntp variable (RW|DEF).
325 This option may appear an unlimited number of times.
327 .It Fl w Ar number , Fl \-wait\-sync Ns = Ns Ar number
328 Seconds to wait for first clock sync.
329 This option must not appear in combination with any of the following options:
330 nofork, quit, saveconfigquit.
331 This option takes an integer number as its argument.
333 If greater than zero, alters \fBntpd\fP's behavior when forking to
334 daemonize. Instead of exiting with status 0 immediately after
335 the fork, the parent waits up to the specified number of
336 seconds for the child to first synchronize the clock. The exit
337 status is zero (success) if the clock was synchronized,
338 otherwise it is \fBETIMEDOUT\fP.
339 This provides the option for a script starting \fBntpd\fP to easily
340 wait for the first set of the clock before proceeding.
342 Slew up to 600 seconds.
344 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.
345 This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually.
346 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.
347 Thus, an adjustment as much as 600 s will take almost 14 days to complete.
348 This option can be used with the
355 configuration file directive for other options.
356 Note: The kernel time discipline is disabled with this option.
358 Use CPU cycle counter (Windows only).
360 Attempt to substitute the CPU counter for \fBQueryPerformanceCounter\fP.
361 The CPU counter and \fBQueryPerformanceCounter\fP are compared, and if
362 they have the same frequency, the CPU counter (RDTSC on x86) is
363 used directly, saving the overhead of a system call.
364 .It Fl \-pccfreq Ns = Ns Ar string
365 Force CPU cycle counter use (Windows only).
367 Force substitution the CPU counter for \fBQueryPerformanceCounter\fP.
368 The CPU counter (RDTSC on x86) is used unconditionally with the
369 given frequency (in Hz).
371 Register with mDNS as a NTP server.
373 Registers as an NTP server with the local mDNS server which allows
374 the server to be discovered via mDNS client lookup.
375 .It Fl \&? , Fl \-help
376 Display usage information and exit.
377 .It Fl \&! , Fl \-more\-help
378 Pass the extended usage information through a pager.
379 .It Fl \-version Op Brq Ar v|c|n
380 Output version of program and exit. The default mode is `v', a simple
381 version. The `c' mode will print copyright information and `n' will
382 print the full copyright notice.
385 Any option that is not marked as \fInot presettable\fP may be preset
386 by loading values from environment variables named:
388 \fBNTPD_<option\-name>\fP or \fBNTPD\fP
392 .Ss "How NTP Operates"
395 utility operates by exchanging messages with
396 one or more configured servers over a range of designated poll intervals.
398 started, whether for the first or subsequent times, the program
399 requires several exchanges from the majority of these servers so
400 the signal processing and mitigation algorithms can accumulate and
401 groom the data and set the clock.
402 In order to protect the network
403 from bursts, the initial poll interval for each server is delayed
404 an interval randomized over a few seconds.
405 At the default initial poll
406 interval of 64s, several minutes can elapse before the clock is
408 This initial delay to set the clock
409 can be safely and dramatically reduced using the
414 command, as described in
417 Most operating systems and hardware of today incorporate a
418 time\-of\-year (TOY) chip to maintain the time during periods when
420 When the machine is booted, the chip is used to
421 initialize the operating system time.
422 After the machine has
423 synchronized to a NTP server, the operating system corrects the
424 chip from time to time.
425 In the default case, if
427 detects that the time on the host
428 is more than 1000s from the server time,
430 assumes something must be terribly wrong and the only
431 reliable action is for the operator to intervene and set the clock
433 (Reasons for this include there is no TOY chip,
434 or its battery is dead, or that the TOY chip is just of poor quality.)
437 to exit with a panic message to
441 option overrides this check and the
442 clock will be set to the server time regardless of the chip time
443 (up to 68 years in the past or future \(em
444 this is a limitation of the NTPv4 protocol).
445 However, and to protect against broken hardware, such as when the
446 CMOS battery fails or the clock counter becomes defective, once the
447 clock has been set an error greater than 1000s will cause
451 Under ordinary conditions,
454 small steps so that the timescale is effectively continuous and
455 without discontinuities.
456 Under conditions of extreme network
457 congestion, the roundtrip delay jitter can exceed three seconds and
458 the synchronization distance, which is equal to one\-half the
459 roundtrip delay plus error budget terms, can become very large.
462 algorithms discard sample offsets exceeding 128 ms,
463 unless the interval during which no sample offset is less than 128
465 The first sample after that, no matter what the
466 offset, steps the clock to the indicated time.
468 reduces the false alarm rate where the clock is stepped in error to
469 a vanishingly low incidence.
471 As the result of this behavior, once the clock has been set it
472 very rarely strays more than 128 ms even under extreme cases of
473 network path congestion and jitter.
474 Sometimes, in particular when
476 is first started without a valid drift file
477 on a system with a large intrinsic drift
478 the error might grow to exceed 128 ms,
479 which would cause the clock to be set backwards
480 if the local clock time is more than 128 s
481 in the future relative to the server.
482 In some applications, this behavior may be unacceptable.
483 There are several solutions, however.
486 option is included on the command line, the clock will
487 never be stepped and only slew corrections will be used.
488 But this choice comes with a cost that
489 should be carefully explored before deciding to use
493 The maximum slew rate possible is limited
494 to 500 parts\-per\-million (PPM) as a consequence of the correctness
495 principles on which the NTP protocol and algorithm design are
497 As a result, the local clock can take a long time to
498 converge to an acceptable offset, about 2,000 s for each second the
499 clock is outside the acceptable range.
500 During this interval the
501 local clock will not be consistent with any other network clock and
502 the system cannot be used for distributed applications that require
503 correctly synchronized network time.
505 In spite of the above precautions, sometimes when large
506 frequency errors are present the resulting time offsets stray
507 outside the 128\-ms range and an eventual step or slew time
508 correction is required.
509 If following such a correction the
510 frequency error is so large that the first sample is outside the
513 enters the same state as when the
516 The intent of this behavior
517 is to quickly correct the frequency and restore operation to the
518 normal tracking mode.
519 In the most extreme cases
522 comes to mind), there may be occasional
523 step/slew corrections and subsequent frequency corrections.
525 helps in these cases to use the
528 configuring the server, but
530 when you have permission to do so from the owner of the target host.
533 in the past many startup scripts would run
534 .Xr ntpdate @NTPDATE_MS@
535 to get the system clock close to correct before starting
537 but this was never more than a mediocre hack and is no longer needed.
538 If you are following the instructions in
539 .Sx "Starting NTP (Best Current Practice)"
540 and you still need to set the system time before starting
542 please open a bug report and document what is going on,
543 and then look at using
546 There is a way to start
548 that often addresses all of the problems mentioned above.
549 .Ss "Starting NTP (Best Current Practice)"
556 If you can also keep a good
560 will effectively "warm\-start" and your system's clock will
561 be stable in under 11 seconds' time.
563 As soon as possible in the startup sequence, start
571 start the rest of your "normal" processes.
574 as much time as possible to get the system's clock synchronized and stable.
577 if you have processes like
581 monotonically\-increasing time,
583 .Xr ntp\-wait 1ntp\-waitmdoc
584 as late as possible in the boot sequence
589 .Xr ntp\-wait 1ntp\-waitmdoc
591 it is as safe as it will ever be to start any process that require
593 .Ss "Frequency Discipline"
596 behavior at startup depends on whether the
597 frequency file, usually
601 contains the latest estimate of clock frequency error.
604 is started and the file does not exist, the
606 enters a special mode designed to quickly adapt to
607 the particular system clock oscillator time and frequency error.
608 This takes approximately 15 minutes, after which the time and
609 frequency are set to nominal values and the
612 normal mode, where the time and frequency are continuously tracked
613 relative to the server.
614 After one hour the frequency file is
615 created and the current frequency offset written to it.
618 is started and the file does exist, the
620 frequency is initialized from the file and enters normal mode
622 After that the current frequency offset is written to
623 the file at hourly intervals.
624 .Ss "Operating Modes"
627 utility can operate in any of several modes, including
628 symmetric active/passive, client/server broadcast/multicast and
629 manycast, as described in the
630 .Qq Association Management
632 (available as part of the HTML documentation
634 .Pa /usr/share/doc/ntp ) .
635 It normally operates continuously while
636 monitoring for small changes in frequency and trimming the clock
637 for the ultimate precision.
638 However, it can operate in a one\-time
639 mode where the time is set from an external server and frequency is
640 set from a previously recorded frequency file.
642 broadcast/multicast or manycast client can discover remote servers,
643 compute server\-client propagation delay correction factors and
644 configure itself automatically.
645 This makes it possible to deploy a
646 fleet of workstations without specifying configuration details
647 specific to the local environment.
651 runs in continuous mode where each of
652 possibly several external servers is polled at intervals determined
653 by an intricate state machine.
654 The state machine measures the
655 incidental roundtrip delay jitter and oscillator frequency wander
656 and determines the best poll interval using a heuristic algorithm.
657 Ordinarily, and in most operating environments, the state machine
658 will start with 64s intervals and eventually increase in steps to
660 A small amount of random variation is introduced in order to
661 avoid bunching at the servers.
662 In addition, should a server become
663 unreachable for some time, the poll interval is increased in steps
664 to 1024s in order to reduce network overhead.
666 In some cases it may not be practical for
669 A common workaround has been to run the
670 .Xr ntpdate @NTPDATE_MS@
677 However, these programs do not have the crafted signal
678 processing, error checking or mitigation algorithms of
682 option is intended for this purpose.
683 Setting this option will cause
686 setting the clock for the first time.
687 The procedure for initially
688 setting the clock is the same as in continuous mode; most
689 applications will probably want to specify the
693 configuration command.
695 keyword a volley of messages are exchanged to groom the data and
696 the clock is set in about 10 s.
697 If nothing is heard after a
698 couple of minutes, the daemon times out and exits.
700 period of mourning, the
701 .Xr ntpdate @NTPDATE_MS@
705 When kernel support is available to discipline the clock
706 frequency, which is the case for stock Solaris, Tru64, Linux and
708 a useful feature is available to discipline the clock
712 is run in continuous mode with
713 selected servers in order to measure and record the intrinsic clock
714 frequency offset in the frequency file.
715 It may take some hours for
716 the frequency and offset to settle down.
720 stopped and run in one\-time mode as required.
722 frequency is read from the file and initializes the kernel
724 .Ss "Poll Interval Control"
725 This version of NTP includes an intricate state machine to
726 reduce the network load while maintaining a quality of
727 synchronization consistent with the observed jitter and wander.
728 There are a number of ways to tailor the operation in order enhance
729 accuracy by reducing the interval or to reduce network overhead by
731 However, the user is advised to carefully consider
732 the consequences of changing the poll adjustment range from the
733 default minimum of 64 s to the default maximum of 1,024 s.
735 default minimum can be changed with the
738 command to a value not less than 16 s.
739 This value is used for all
740 configured associations, unless overridden by the
742 option on the configuration command.
743 Note that most device drivers
744 will not operate properly if the poll interval is less than 64 s
745 and that the broadcast server and manycast client associations will
746 also use the default, unless overridden.
748 In some cases involving dial up or toll services, it may be
749 useful to increase the minimum interval to a few tens of minutes
750 and maximum interval to a day or so.
751 Under normal operation
752 conditions, once the clock discipline loop has stabilized the
753 interval will be increased in steps from the minimum to the
755 However, this assumes the intrinsic clock frequency error
756 is small enough for the discipline loop correct it.
758 range of the loop is 500 PPM at an interval of 64s decreasing by a
759 factor of two for each doubling of interval.
760 At a minimum of 1,024
761 s, for example, the capture range is only 31 PPM.
763 error is greater than this, the drift file
766 have to be specially tailored to reduce the residual error below
768 Once this is done, the drift file is automatically
769 updated once per hour and is available to initialize the frequency
770 on subsequent daemon restarts.
771 .Ss "The huff\-n'\-puff Filter"
772 In scenarios where a considerable amount of data are to be
773 downloaded or uploaded over telephone modems, timekeeping quality
774 can be seriously degraded.
775 This occurs because the differential
776 delays on the two directions of transmission can be quite large.
778 many cases the apparent time errors are so large as to exceed the
779 step threshold and a step correction can occur during and after the
780 data transfer is in progress.
782 The huff\-n'\-puff filter is designed to correct the apparent time
783 offset in these cases.
784 It depends on knowledge of the propagation
785 delay when no other traffic is present.
786 In common scenarios this
787 occurs during other than work hours.
788 The filter maintains a shift
789 register that remembers the minimum delay over the most recent
790 interval measured usually in hours.
791 Under conditions of severe
792 delay, the filter corrects the apparent offset using the sign of
793 the offset and the difference between the apparent delay and
795 The name of the filter reflects the negative (huff)
796 and positive (puff) correction, which depends on the sign of the
799 The filter is activated by the
803 keyword, as described in
806 See \fBOPTION PRESETS\fP for configuration environment variables.
808 .Bl -tag -width /etc/ntp.drift -compact
810 the default name of the configuration file
811 .It Pa /etc/ntp.drift
812 the default name of the drift file
814 the default name of the key file
817 One of the following exit values will be returned:
819 .It 0 " (EXIT_SUCCESS)"
820 Successful program execution.
821 .It 1 " (EXIT_FAILURE)"
822 The operation failed or the command syntax was not valid.
823 .It 70 " (EX_SOFTWARE)"
824 libopts had an internal operational error. Please report
825 it to autogen\-users@lists.sourceforge.net. Thank you.
829 .Xr ntpdate @NTPDATE_MS@ ,
830 .Xr ntpdc @NTPDC_MS@ ,
834 In addition to the manual pages provided,
835 comprehensive documentation is available on the world wide web
837 .Li http://www.ntp.org/ .
838 A snapshot of this documentation is available in HTML format in
839 .Pa /usr/share/doc/ntp .
842 .%T Network Time Protocol (Version 1)
847 .%T Network Time Protocol (Version 2)
852 .%T Network Time Protocol (Version 3)
860 .%T Network Time Protocol Version 4: Protocol and Algorithms Specification
866 .%T Network Time Protocol Version 4: Autokey Specification
873 .%T Definitions of Managed Objects for Network Time Protocol Version 4: (NTPv4)
879 .%T Network Time Protocol (NTP) Server Option for DHCPv6
883 The University of Delaware and Network Time Foundation
885 Copyright (C) 1992\-2015 The University of Delaware and Network Time Foundation all rights reserved.
886 This program is released under the terms of the NTP license, <http://ntp.org/license>.
890 utility has gotten rather fat.
891 While not huge, it has gotten
892 larger than might be desirable for an elevated\-priority
894 running on a workstation, particularly since many of
895 the fancy features which consume the space were designed more with
896 a busy primary server, rather than a high stratum workstation in
899 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
901 Portions of this document came from FreeBSD.
903 This manual page was \fIAutoGen\fP\-erated from the \fBntpd\fP
projects / FreeBSD / releng / 10.2.git / blob