1ntpd(8) User Commands ntpd(8)
2
6 ntpd - NTP daemon program
7
9 ntpd [-flags] [-flag [value]] [--option-name[[=| ]value]] [ <server1>
10 ... <serverN> ]
11
14 The ntpd utility is an operating system daemon which sets and maintains
15 the system time of day in synchronism with Internet standard time
16 servers. It is a complete implementation of the Network Time Protocol
17 (NTP) version 4, as defined by RFC-5905, but also retains compatibility
18 with version 3, as defined by RFC-1305, and versions 1 and 2, as
19 defined by RFC-1059 and RFC-1119, respectively.
20 The ntpd utility does most computations in 64-bit floating point arith‐
22 metic and does relatively clumsy 64-bit fixed point operations only
23 when necessary to preserve the ultimate precision, about 232 picosec‐
24 onds. While the ultimate precision is not achievable with ordinary
25 workstations and networks of today, it may be required with future
26 gigahertz CPU clocks and gigabit LANs.
27 Ordinarily, ntpd reads the ntp.conf(5) configuration file at startup
29 time in order to determine the synchronization sources and operating
30 modes. It is also possible to specify a working, although limited,
31 configuration entirely on the command line, obviating the need for a
32 configuration file. This may be particularly useful when the local
33 host is to be configured as a broadcast/multicast client, with all
34 peers being determined by listening to broadcasts at run time.
35 If NetInfo support is built into ntpd, then ntpd will attempt to read
37 its configuration from the NetInfo if the default ntp.conf(5) file can‐
38 not be read and no file is specified by the -c option.
39 Various internal ntpd variables can be displayed and configuration
41 options altered while the ntpd is running using the ntpq(8) and
42 ntpdc(8) utility programs.
43 When ntpd starts it looks at the value of umask(2), and if zero ntpd
45 will set the umask(2) to 022.
46
48 -4, --ipv4
49 Force IPv4 DNS name resolution. This option must not appear in
50 combination with any of the following options: ipv6.
51 Force DNS resolution of following host names on the command line
53 to the IPv4 namespace.
54 -6, --ipv6
56 Force IPv6 DNS name resolution. This option must not appear in
57 combination with any of the following options: ipv4.
58 Force DNS resolution of following host names on the command line
60 to the IPv6 namespace.
61 -a, --authreq
63 Require crypto authentication. This option must not appear in
64 combination with any of the following options: authnoreq.
65 Require cryptographic authentication for broadcast client, mul‐
67 ticast client and symmetric passive associations. This is the
68 default.
69 -A, --authnoreq
71 Do not require crypto authentication. This option must not
72 appear in combination with any of the following options:
73 authreq.
74 Do not require cryptographic authentication for broadcast
76 client, multicast client and symmetric passive associations.
77 This is almost never a good idea.
78 -b, --bcastsync
80 Allow us to sync to broadcast servers.
81 -c string, --configfile=string
84 configuration file name.
85 The name and path of the configuration file, /etc/ntp.conf by
87 default.
88 -d, --debug-level
90 Increase debug verbosity level. This option may appear an
91 unlimited number of times.
92 -D number, --set-debug-level=number
95 Set the debug verbosity level. This option may appear an unlim‐
96 ited number of times. This option takes an integer number as
97 its argument.
98 -f string, --driftfile=string
101 frequency drift file name.
102 The name and path of the frequency file, /etc/ntp.drift by
104 default. This is the same operation as the driftfile driftfile
105 configuration specification in the /etc/ntp.conf file.
106 -g, --panicgate
108 Allow the first adjustment to be Big. This option may appear an
109 unlimited number of times.
110 Normally, ntpd exits with a message to the system log if the
112 offset exceeds the panic threshold, which is 1000 s by default.
113 This option allows the time to be set to any value without
114 restriction; however, this can happen only once. If the thresh‐
115 old is exceeded after that, ntpd will exit with a message to the
116 system log. This option can be used with the -q and -x options.
117 See the tinker configuration file directive for other options.
118 -G, --force-step-once
120 Step any initial offset correction..
121 Normally, ntpd steps the time if the time offset exceeds the
123 step threshold, which is 128 ms by default, and otherwise slews
124 the time. This option forces the initial offset correction to
125 be stepped, so the highest time accuracy can be achieved
126 quickly. However, this may also cause the time to be stepped
127 back so this option must not be used if applications requiring
128 monotonic time are running. See the tinker configuration file
129 directive for other options.
130 -i string, --jaildir=string
132 Jail directory.
133 Chroot the server to the directory jaildir This option also
135 implies that the server attempts to drop root privileges at
136 startup. You may need to also specify a -u option. This option
137 is only available if the OS supports adjusting the clock without
138 full root privileges. This option is supported under NetBSD
139 (configure with --enable-clockctl) or Linux (configure with
140 --enable-linuxcaps) or Solaris (configure with --enable-solar‐
141 isprivs).
142 -I iface, --interface=iface
144 Listen on an interface name or address. This option may appear
145 an unlimited number of times.
146 Open the network address given, or all the addresses associated
148 with the given interface name. This option may appear multiple
149 times. This option also implies not opening other addresses,
150 except wildcard and localhost. This option is deprecated.
151 Please consider using the configuration file interface command,
152 which is more versatile.
153 -k string, --keyfile=string
155 path to symmetric keys.
156 Specify the name and path of the symmetric key file.
158 /etc/ntp.keys is the default. This is the same operation as the
159 keys keyfile configuration file directive.
160 -l string, --logfile=string
162 path to the log file.
163 Specify the name and path of the log file. The default is the
165 system log file. This is the same operation as the logfile log‐
166 file configuration file directive.
167 -L, --novirtualips
169 Do not listen to virtual interfaces.
170 Do not listen to virtual interfaces, defined as those with names
172 containing a colon. This option is deprecated. Please consider
173 using the configuration file interface command, which is more
174 versatile.
175 -M, --modifymmtimer
177 Modify Multimedia Timer (Windows only).
178 Set the Windows Multimedia Timer to highest resolution. This
180 ensures the resolution does not change while ntpd is running,
181 avoiding timekeeping glitches associated with changes.
182 -n, --nofork
184 Do not fork. This option must not appear in combination with
185 any of the following options: wait-sync.
186 -N, --nice
189 Run at high priority.
190 To the extent permitted by the operating system, run ntpd at the
192 highest priority.
193 -p string, --pidfile=string
195 path to the PID file.
196 Specify the name and path of the file used to record ntpd's
198 process ID. This is the same operation as the pidfile pidfile
199 configuration file directive.
200 -P number, --priority=number
202 Process priority. This option takes an integer number as its
203 argument.
204 To the extent permitted by the operating system, run ntpd at the
206 specified sched_setscheduler(SCHED_FIFO) priority.
207 -q, --quit
209 Set the time and quit. This option must not appear in combina‐
210 tion with any of the following options: saveconfigquit, wait-
211 sync.
212 ntpd will not daemonize and will exit after the clock is first
214 synchronized. This behavior mimics that of the ntpdate program,
215 which will soon be replaced with a shell script. The -g and -x
216 options can be used with this option. Note: The kernel time
217 discipline is disabled with this option.
218 -r string, --propagationdelay=string
220 Broadcast/propagation delay.
221 Specify the default propagation delay from the broadcast/multi‐
223 cast server to this client. This is necessary only if the delay
224 cannot be computed automatically by the protocol.
225 --saveconfigquit=string
227 Save parsed configuration and quit. This option must not appear
228 in combination with any of the following options: quit, wait-
229 sync.
230 Cause ntpd to parse its startup configuration file and save an
232 equivalent to the given filename and exit. This option was
233 designed for automated testing.
234 -s string, --statsdir=string
236 Statistics file location.
237 Specify the directory path for files created by the statistics
239 facility. This is the same operation as the statsdir statsdir
240 configuration file directive.
241 -t tkey, --trustedkey=tkey
243 Trusted key number. This option may appear an unlimited number
244 of times.
245 Add the specified key number to the trusted key list.
247 -u string, --user=string
249 Run as userid (or userid:groupid).
250 Specify a user, and optionally a group, to switch to. This
252 option is only available if the OS supports adjusting the clock
253 without full root privileges. This option is supported under
254 NetBSD (configure with --enable-clockctl) or Linux (configure
255 with --enable-linuxcaps) or Solaris (configure with --enable-
256 solarisprivs).
257 -U number, --updateinterval=number
259 interval in seconds between scans for new or dropped interfaces.
260 This option takes an integer number as its argument.
261 Give the time in seconds between two scans for new or dropped
263 interfaces. For systems with routing socket support the scans
264 will be performed shortly after the interface change has been
265 detected by the system. Use 0 to disable scanning. 60 seconds
266 is the minimum time between scans.
267 --var=nvar
269 make ARG an ntp variable (RW). This option may appear an unlim‐
270 ited number of times.
271 --dvar=ndvar
274 make ARG an ntp variable (RW|DEF). This option may appear an
275 unlimited number of times.
276 -w number, --wait-sync=number
279 Seconds to wait for first clock sync. This option must not
280 appear in combination with any of the following options: nofork,
281 quit, saveconfigquit. This option takes an integer number as
282 its argument.
283 If greater than zero, alters ntpd's behavior when forking to
285 daemonize. Instead of exiting with status 0 immediately after
286 the fork, the parent waits up to the specified number of seconds
287 for the child to first synchronize the clock. The exit status
288 is zero (success) if the clock was synchronized, otherwise it is
289 ETIMEDOUT. This provides the option for a script starting ntpd
290 to easily wait for the first set of the clock before proceeding.
291 -x, --slew
293 Slew up to 600 seconds.
294 Normally, the time is slewed if the offset is less than the step
296 threshold, which is 128 ms by default, and stepped if above the
297 threshold. This option sets the threshold to 600 s, which is
298 well within the accuracy window to set the clock manually.
299 Note: Since the slew rate of typical Unix kernels is limited to
300 0.5 ms/s, each second of adjustment requires an amortization
301 interval of 2000 s. Thus, an adjustment as much as 600 s will
302 take almost 14 days to complete. This option can be used with
303 the -g and -q options. See the tinker configuration file direc‐
304 tive for other options. Note: The kernel time discipline is
305 disabled with this option.
306 --usepcc
308 Use CPU cycle counter (Windows only).
309 Attempt to substitute the CPU counter for QueryPerformance‐
311 Counter. The CPU counter and QueryPerformanceCounter are com‐
312 pared, and if they have the same frequency, the CPU counter
313 (RDTSC on x86) is used directly, saving the overhead of a system
314 call.
315 --pccfreq=string
317 Force CPU cycle counter use (Windows only).
318 Force substitution the CPU counter for QueryPerformanceCounter.
320 The CPU counter (RDTSC on x86) is used unconditionally with the
321 given frequency (in Hz).
322 -m, --mdns
324 Register with mDNS as a NTP server.
325 Registers as an NTP server with the local mDNS server which
327 allows the server to be discovered via mDNS client lookup.
328 -?, --help
330 Display usage information and exit.
331 -!, --more-help
333 Pass the extended usage information through a pager.
334 --version [{v|c|n}]
336 Output version of program and exit. The default mode is `v', a
337 simple version. The `c' mode will print copyright information
338 and `n' will print the full copyright notice.
339
341 Any option that is not marked as not presettable may be preset by load‐
342 ing values from environment variables named:
343 NTPD_<option-name> or NTPD
344
346 How NTP Operates
347 The ntpd utility operates by exchanging messages with one or more con‐
348 figured servers over a range of designated poll intervals. When
349 started, whether for the first or subsequent times, the program
350 requires several exchanges from the majority of these servers so the
351 signal processing and mitigation algorithms can accumulate and groom
352 the data and set the clock. In order to protect the network from
353 bursts, the initial poll interval for each server is delayed an inter‐
354 val randomized over a few seconds. At the default initial poll inter‐
355 val of 64s, several minutes can elapse before the clock is set. This
356 initial delay to set the clock can be safely and dramatically reduced
357 using the iburst keyword with the server configuration command, as
358 described in ntp.conf(5).
359 Most operating systems and hardware of today incorporate a time-of-year
361 (TOY) chip to maintain the time during periods when the power is off.
362 When the machine is booted, the chip is used to initialize the operat‐
363 ing system time. After the machine has synchronized to a NTP server,
364 the operating system corrects the chip from time to time. In the
365 default case, if ntpd detects that the time on the host is more than
366 1000s from the server time, ntpd assumes something must be terribly
367 wrong and the only reliable action is for the operator to intervene and
368 set the clock by hand. (Reasons for this include there is no TOY chip,
369 or its battery is dead, or that the TOY chip is just of poor quality.)
370 This causes ntpd to exit with a panic message to the system log. The
371 -g option overrides this check and the clock will be set to the server
372 time regardless of the chip time (up to 68 years in the past or future
373 — this is a limitation of the NTPv4 protocol). However, and to protect
374 against broken hardware, such as when the CMOS battery fails or the
375 clock counter becomes defective, once the clock has been set an error
376 greater than 1000s will cause ntpd to exit anyway.
377 Under ordinary conditions, ntpd adjusts the clock in small steps so
379 that the timescale is effectively continuous and without discontinu‐
380 ities. Under conditions of extreme network congestion, the roundtrip
381 delay jitter can exceed three seconds and the synchronization distance,
382 which is equal to one-half the roundtrip delay plus error budget terms,
383 can become very large. The ntpd algorithms discard sample offsets
384 exceeding 128 ms, unless the interval during which no sample offset is
385 less than 128 ms exceeds 900s. The first sample after that, no matter
386 what the offset, steps the clock to the indicated time. In practice
387 this reduces the false alarm rate where the clock is stepped in error
388 to a vanishingly low incidence.
389 As the result of this behavior, once the clock has been set it very
391 rarely strays more than 128 ms even under extreme cases of network path
392 congestion and jitter. Sometimes, in particular when ntpd is first
393 started without a valid drift file on a system with a large intrinsic
394 drift the error might grow to exceed 128 ms, which would cause the
395 clock to be set backwards if the local clock time is more than 128 s in
396 the future relative to the server. In some applications, this behavior
397 may be unacceptable. There are several solutions, however. If the -x
398 option is included on the command line, the clock will never be stepped
399 and only slew corrections will be used. But this choice comes with a
400 cost that should be carefully explored before deciding to use the -x
401 option. The maximum slew rate possible is limited to 500 parts-per-
402 million (PPM) as a consequence of the correctness principles on which
403 the NTP protocol and algorithm design are based. As a result, the
404 local clock can take a long time to converge to an acceptable offset,
405 about 2,000 s for each second the clock is outside the acceptable
406 range. During this interval the local clock will not be consistent
407 with any other network clock and the system cannot be used for distrib‐
408 uted applications that require correctly synchronized network time.
409 In spite of the above precautions, sometimes when large frequency
411 errors are present the resulting time offsets stray outside the 128-ms
412 range and an eventual step or slew time correction is required. If
413 following such a correction the frequency error is so large that the
414 first sample is outside the acceptable range, ntpd enters the same
415 state as when the ntp.drift file is not present. The intent of this
416 behavior is to quickly correct the frequency and restore operation to
417 the normal tracking mode. In the most extreme cases (the host
418 time.ien.it comes to mind), there may be occasional step/slew correc‐
419 tions and subsequent frequency corrections. It helps in these cases to
420 use the burst keyword when configuring the server, but ONLY when you
421 have permission to do so from the owner of the target host.
422 Finally, in the past many startup scripts would run ntpdate(8) or
424 sntp(8) to get the system clock close to correct before starting
425 ntpd(8), but this was never more than a mediocre hack and is no longer
426 needed. If you are following the instructions in Starting NTP (Best
427 Current Practice) and you still need to set the system time before
428 starting ntpd, please open a bug report and document what is going on,
429 and then look at using sntp(8) if you really need to set the clock
430 before starting ntpd.
431 There is a way to start ntpd(8) that often addresses all of the prob‐
433 lems mentioned above.
434 Starting NTP (Best Current Practice)
436 First, use the iburst option on your server entries.
437 If you can also keep a good ntp.drift file then ntpd(8) will effec‐
439 tively "warm-start" and your system's clock will be stable in under 11
440 seconds' time.
441 As soon as possible in the startup sequence, start ntpd(8) with at
443 least the -g and perhaps the -N options. Then, start the rest of your
444 "normal" processes. This will give ntpd(8) as much time as possible to
445 get the system's clock synchronized and stable.
446 Finally, if you have processes like dovecot or database servers that
448 require monotonically-increasing time, run ntp-wait(8) as late as pos‐
449 sible in the boot sequence (perhaps with the -v flag) and after ntp-
450 wait(8) exits successfully it is as safe as it will ever be to start
451 any process that require stable time.
452 Frequency Discipline
454 The ntpd behavior at startup depends on whether the frequency file,
455 usually ntp.drift, exists. This file contains the latest estimate of
456 clock frequency error. When the ntpd is started and the file does not
457 exist, the ntpd enters a special mode designed to quickly adapt to the
458 particular system clock oscillator time and frequency error. This
459 takes approximately 15 minutes, after which the time and frequency are
460 set to nominal values and the ntpd enters normal mode, where the time
461 and frequency are continuously tracked relative to the server. After
462 one hour the frequency file is created and the current frequency offset
463 written to it. When the ntpd is started and the file does exist, the
464 ntpd frequency is initialized from the file and enters normal mode
465 immediately. After that the current frequency offset is written to the
466 file at hourly intervals.
467 Operating Modes
469 The ntpd utility can operate in any of several modes, including symmet‐
470 ric active/passive, client/server broadcast/multicast and manycast, as
471 described in the "Association Management" page (available as part of
472 the HTML documentation provided in /usr/share/doc/ntp). It normally
473 operates continuously while monitoring for small changes in frequency
474 and trimming the clock for the ultimate precision. However, it can
475 operate in a one-time mode where the time is set from an external
476 server and frequency is set from a previously recorded frequency file.
477 A broadcast/multicast or manycast client can discover remote servers,
478 compute server-client propagation delay correction factors and config‐
479 ure itself automatically. This makes it possible to deploy a fleet of
480 workstations without specifying configuration details specific to the
481 local environment.
482 By default, ntpd runs in continuous mode where each of possibly several
484 external servers is polled at intervals determined by an intricate
485 state machine. The state machine measures the incidental roundtrip
486 delay jitter and oscillator frequency wander and determines the best
487 poll interval using a heuristic algorithm. Ordinarily, and in most
488 operating environments, the state machine will start with 64s intervals
489 and eventually increase in steps to 1024s. A small amount of random
490 variation is introduced in order to avoid bunching at the servers. In
491 addition, should a server become unreachable for some time, the poll
492 interval is increased in steps to 1024s in order to reduce network
493 overhead.
494 In some cases it may not be practical for ntpd to run continuously. A
496 common workaround has been to run the ntpdate(8) or sntp(8) programs
497 from a cron(8) job at designated times. However, these programs do not
498 have the crafted signal processing, error checking or mitigation algo‐
499 rithms of ntpd. The -q option is intended for this purpose. Setting
500 this option will cause ntpd to exit just after setting the clock for
501 the first time. The procedure for initially setting the clock is the
502 same as in continuous mode; most applications will probably want to
503 specify the iburst keyword with the server configuration command. With
504 this keyword a volley of messages are exchanged to groom the data and
505 the clock is set in about 10 s. If nothing is heard after a couple of
506 minutes, the daemon times out and exits. After a suitable period of
507 mourning, the ntpdate(8) program will be retired.
508 When kernel support is available to discipline the clock frequency,
510 which is the case for stock Solaris, Tru64, Linux and FreeBSD, a useful
511 feature is available to discipline the clock frequency. First, ntpd is
512 run in continuous mode with selected servers in order to measure and
513 record the intrinsic clock frequency offset in the frequency file. It
514 may take some hours for the frequency and offset to settle down. Then
515 the ntpd is stopped and run in one-time mode as required. At each
516 startup, the frequency is read from the file and initializes the kernel
517 frequency.
518 Poll Interval Control
520 This version of NTP includes an intricate state machine to reduce the
521 network load while maintaining a quality of synchronization consistent
522 with the observed jitter and wander. There are a number of ways to
523 tailor the operation in order enhance accuracy by reducing the interval
524 or to reduce network overhead by increasing it. However, the user is
525 advised to carefully consider the consequences of changing the poll
526 adjustment range from the default minimum of 64 s to the default maxi‐
527 mum of 1,024 s. The default minimum can be changed with the tinker
528 minpoll command to a value not less than 16 s. This value is used for
529 all configured associations, unless overridden by the minpoll option on
530 the configuration command. Note that most device drivers will not
531 operate properly if the poll interval is less than 64 s and that the
532 broadcast server and manycast client associations will also use the
533 default, unless overridden.
534 In some cases involving dial up or toll services, it may be useful to
536 increase the minimum interval to a few tens of minutes and maximum
537 interval to a day or so. Under normal operation conditions, once the
538 clock discipline loop has stabilized the interval will be increased in
539 steps from the minimum to the maximum. However, this assumes the
540 intrinsic clock frequency error is small enough for the discipline loop
541 correct it. The capture range of the loop is 500 PPM at an interval of
542 64s decreasing by a factor of two for each doubling of interval. At a
543 minimum of 1,024 s, for example, the capture range is only 31 PPM. If
544 the intrinsic error is greater than this, the drift file ntp.drift will
545 have to be specially tailored to reduce the residual error below this
546 limit. Once this is done, the drift file is automatically updated once
547 per hour and is available to initialize the frequency on subsequent
548 daemon restarts.
549 The huff-n'-puff Filter
551 In scenarios where a considerable amount of data are to be downloaded
552 or uploaded over telephone modems, timekeeping quality can be seriously
553 degraded. This occurs because the differential delays on the two
554 directions of transmission can be quite large. In many cases the
555 apparent time errors are so large as to exceed the step threshold and a
556 step correction can occur during and after the data transfer is in
557 progress.
558 The huff-n'-puff filter is designed to correct the apparent time offset
560 in these cases. It depends on knowledge of the propagation delay when
561 no other traffic is present. In common scenarios this occurs during
562 other than work hours. The filter maintains a shift register that
563 remembers the minimum delay over the most recent interval measured usu‐
564 ally in hours. Under conditions of severe delay, the filter corrects
565 the apparent offset using the sign of the offset and the difference
566 between the apparent delay and minimum delay. The name of the filter
567 reflects the negative (huff) and positive (puff) correction, which
568 depends on the sign of the offset.
569 The filter is activated by the tinker command and huffpuff keyword, as
571 described in ntp.conf(5).
572
574 See OPTION PRESETS for configuration environment variables.
575
577 /etc/ntp.conf the default name of the configuration file
578 /etc/ntp.drift the default name of the drift file
579 /etc/ntp.keys the default name of the key file
580
582 One of the following exit values will be returned:
583 0 (EXIT_SUCCESS)
585 Successful program execution.
586 1 (EXIT_FAILURE)
588 The operation failed or the command syntax was not valid.
589 70 (EX_SOFTWARE)
591 libopts had an internal operational error. Please report it to
592 autogen-users@lists.sourceforge.net. Thank you.
593
595 ntp.conf(5), ntpdate(8), ntpdc(8), ntpq(8), sntp(8)
596 In addition to the manual pages provided, comprehensive documentation
598 is available on the world wide web at http://www.ntp.org/. A snapshot
599 of this documentation is available in HTML format in
600 /usr/share/doc/ntp. David L. Mills, Network Time Protocol (Version 1),
601 RFC1059
602 David L. Mills, Network Time Protocol (Version 2), RFC1119
604 David L. Mills, Network Time Protocol (Version 3), RFC1305
606 David L. Mills and J. Martin, Ed. and J. Burbank and W. Kasch, Network
608 Time Protocol Version 4: Protocol and Algorithms Specification, RFC5905
609 David L. Mills and B. Haberman, Ed., Network Time Protocol Version 4:
611 Autokey Specification, RFC5906
612 H. Gerstung and C. Elliott and B. Haberman, Ed., Definitions of Managed
614 Objects for Network Time Protocol Version 4: (NTPv4), RFC5907
615 R. Gayraud and B. Lourdelet, Network Time Protocol (NTP) Server Option
617 for DHCPv6, RFC5908
618
620 The University of Delaware and Network Time Foundation
621
623 Copyright (C) 1992-2020 The University of Delaware and Network Time
624 Foundation all rights reserved. This program is released under the
625 terms of the NTP license, <http://ntp.org/license>.
626
628 The ntpd utility has gotten rather fat. While not huge, it has gotten
629 larger than might be desirable for an elevated-priority ntpd running on
630 a workstation, particularly since many of the fancy features which con‐
631 sume the space were designed more with a busy primary server, rather
632 than a high stratum workstation in mind.
633 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
635
637 Portions of this document came from FreeBSD.
638 This manual page was AutoGen-erated from the ntpd option definitions.
6404.2.8p15 23 Jun 2020 ntpd(8)