1NTPD(8)                             NTPsec                             NTPD(8)
2
3
4

NAME

6       ntpd - Network Time Protocol service daemon
7

SYNOPSIS

9       ntpd
10           [-46agGhLmnNqx] [assert] [-c conffile] [-f driftfile]
11           [-i jaildir] [-k keyfile] [-l logfile] [-p pidfile]
12           [-P priority] [-s statsdir]  [-t  key]
13           [-u user[:'group']] [-U interface_update_interval]
14           [-v variable] [-V variable] [server...]
15

DESCRIPTION

17       The ntpd utility is an operating system daemon which sets and maintains
18       the system time of day in synchronism with Internet standard time
19       servers. It is a complete implementation of the Network Time Protocol
20       (NTP) version 4, as defined by RFC 5905, but also retains compatibility
21       with version 3, as defined by RFC 1305, and versions 1 and 2, as
22       defined by RFC 1059 and RFC 1119, respectively.
23
24       The ntpd utility can synchronize time to a theoretical precision of
25       about 232 picoseconds. In practice, this limit is unattainable due to
26       quantum limits on the clock speed of ballistic-electron logic.
27
28       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.
33
34       The ntpd program normally operates continuously while adjusting the
35       system time and frequency, but in some cases this might not be
36       practical. With the -q option ntpd operates as in continuous mode, but
37       exits just after setting the clock for the first time. Most
38       applications will probably want to specify the iburst option with the
39       server command. With this option, a volley of messages is exchanged to
40       groom the data and set the clock in about ten seconds. With -q, if
41       nothing is heard after a few minutes, the daemon times out and exits
42       without setting the clock.
43
44       Various internal ntpd variables can be displayed and configuration
45       options altered while the ntpd is running using the ntpq(1) utility
46       program. The state of ntpd can be continuously monitored using
47       ntpmon(1).
48
49       When ntpd starts it looks at the value of umask(2), and if zero ntpd
50       will set the umask(2) to 022.
51

OPTIONS

53       -4, --ipv4
54           Force IPv4 DNS name resolution. This option must not appear in
55           combination with any of the following options: ipv6.
56
57           Force DNS resolution of following host names on the command line to
58           the IPv4 namespace.
59
60       -6, --ipv6
61           Force IPv6 DNS name resolution. This option must not appear in
62           combination with any of the following options: ipv4.
63
64           Force DNS resolution of following host names on the command line to
65           the IPv6 namespace.
66
67       -a, --assert
68           REQUIRE(false) to test assert handler.
69
70       -c string, --configfile=string
71           configuration file name.
72
73           The name and path of the configuration file, /etc/ntp.conf by
74           default.
75
76       -d, --debug-level
77           Increase debug verbosity level. This option may appear an unlimited
78           number of times.
79
80       -D number, --set-debug-level=number
81           Set the debug verbosity level. This option may appear an unlimited
82           number of times. This option takes an integer number as its
83           argument.
84
85       -f string, --driftfile=string
86           frequency drift file name.
87
88           The name and path of the frequency file, e.g. /etc/ntp.drift. This
89           is the same operation as the driftfile configuration specification
90           in the /etc/ntp.conf file.
91
92       -g, --panicgate
93           Allow the first adjustment to be big. This option may appear an
94           unlimited number of times.
95
96           Normally, ntpd exits with a message to the system log if the offset
97           exceeds the panic threshold, which is 1000 s by default. This
98           option allows the time to be set to any value without restriction;
99           however, this can happen only once. If the threshold is exceeded
100           after that, ntpd will exit with a message to the system log. This
101           option can be used with the -q and -x options. See the tinker
102           configuration file directive for other options.
103
104       -G
105           Step any initial offset correction.
106
107           Normally, ntpd steps the time if the time offset exceeds the step
108           threshold, which is 128 ms by default, and otherwise slews the
109           time. This option forces the initial offset correction to be
110           stepped, so the highest time accuracy can be achieved quickly.
111           However, this may also cause the time to be stepped back so this
112           option must not be used if applications requiring monotonic time
113           are running. See the tinker configuration file directive for other
114           options.
115
116       -h, --help
117           Print a usage message summarizing options and exit.
118
119       -i string, --jaildir=string
120           Jail directory.
121
122           Chroot the server to the directory jaildir This option also implies
123           that the server attempts to drop root privileges at startup. You
124           may need to also specify a -u option. This option is only available
125           if the OS supports adjusting the clock without full root
126           privileges. This option is supported under Linux, NetBSD, and
127           Solaris.
128
129       -I iface, --interface=iface
130           Listen on an interface name or address. This option may appear an
131           unlimited number of times.
132
133           Open the network address given, or all the addresses associated
134           with the given interface name. This option may appear multiple
135           times. This option also implies not opening other addresses, except
136           wildcard and localhost. This option is deprecated. Please consider
137           using the configuration file interface command, which is more
138           versatile.
139
140       -k string, --keyfile=string
141           the path to symmetric keys.
142
143           Specify the name and path of the symmetric key file. /etc/ntp.keys
144           is a common location. This is the same operation as the keys
145           configuration file directive.
146
147       -l string, --logfile=string
148           the path to the log file.
149
150           Specify the name and path of the log file. The default is the
151           system log file. This is the same operation as the logfile
152           configuration file directive. See ntp.conf(5) for more info.
153
154       -L, --novirtualips
155           Do not listen to virtual interfaces.
156
157           Do not listen to virtual interfaces, defined as those with names
158           containing a colon. This option is deprecated. Please consider
159           using the configuration file interface command, which is more
160           versatile.
161
162       -m, --mdns
163           Register with mDNS as an NTP server.
164
165           Registers as an NTP server with the local mDNS server which allows
166           the server to be discovered via mDNS client lookup.
167
168       -n, --nofork
169           Do not fork. This option must not appear in combination with any of
170           the following options: wait-sync.
171
172       -N, --nice
173           Run at high priority.
174
175           To the extent permitted by the operating system, run ntpd at the
176           highest priority.
177
178       -p string, --pidfile=string
179           the path to the PID file.
180
181           Specify the name and path of the file used to record ntpd's process
182           ID. This is the same operation as the pidfile configuration file
183           directive.
184
185       -P number, --priority=number
186           Process priority. This option takes an integer number as its
187           argument.
188
189           To the extent permitted by the operating system, run ntpd at the
190           specified pthread_setschedparam(SCHED_FIFO) priority.
191
192       -q, --quit
193           Set the time and quit. This option must not appear in combination
194           with wait-sync.
195
196           ntpd will not daemonize and will exit after the clock is first
197           synchronized. This behavior mimics that of the old ntpdate program,
198           which has been replaced with a shell script. The -g and -x options
199           can be used with this option. Note: The kernel time discipline is
200           disabled with this option.
201
202       -s string, --statsdir=string
203           Statistics file location.
204
205           Specify the directory path for files created by the statistics
206           facility. This is the same operation as the statsdir configuration
207           file directive.
208
209       -t tkey, --trustedkey=tkey
210           Trusted key number. This option may appear an unlimited number of
211           times.
212
213           Add the specified key number to the trusted key list.
214
215       -u string, --user=string
216           Run as userid (or userid:groupid).
217
218           Specify a user, and optionally a group, to switch to. The user and
219           group may be specified by name or numeric id. If no group is
220           specified, then the default group for userid is used. This option
221           is only available if the OS supports adjusting the clock without
222           full root privileges. This option is supported under Linux, NetBSD,
223           Solaris and other OS.
224
225       -U number, --updateinterval=number
226           interval in seconds between scans for new or dropped interfaces.
227           This option takes an integer number as its argument.
228
229           Give the time in seconds between two scans for new or dropped
230           interfaces. For systems with routing socket support, the scans will
231           be performed shortly after the interface change has been detected
232           by the system. Use 0 to disable scanning. 60 seconds is the minimum
233           time between scans.
234
235       -w number, --wait-sync=number
236           Seconds to wait for first clock sync. This option must not appear
237           in combination with any of the following options: nofork, quit.
238           This option takes an integer number as its argument.
239
240           If greater than zero alters ntpd's behavior when forking to
241           daemonize. Instead of exiting with status 0 immediately after the
242           fork, the parent waits up to the specified number of seconds for
243           the child to first synchronize the clock. The exit status is zero
244           (success) if the clock was synchronized; otherwise, it is
245           ETIMEDOUT. This provides the option for a script starting ntpd to
246           easily wait for the first set of the clock before proceeding.
247
248       -x, --slew
249           Slew up to 600 seconds.
250
251           Normally, the time is slewed if the offset is less than the step
252           threshold, which is 128 ms by default, and stepped if above the
253           threshold. This option sets the threshold to 600 s, which is well
254           within the accuracy window to set the clock manually. Note: Since
255           the slew rate of typical Unix kernels is limited to 0.5 ms/s, each
256           second of adjustment requires an amortization interval of 2000 s.
257           Thus, an adjustment as much as 600 s will take almost 14 days to
258           complete. This option can be used with the -g and -q options. See
259           the tinker configuration file directive for other options. Note:
260           The kernel time discipline is disabled with this option.
261
262       -z nvar, --var=nvar
263           make ARG an ntp variable (RW). This option may appear an unlimited
264           number of times.
265
266       -Z nvar, --dvar=ndvar
267           make ARG an ntp variable (RW|DEF). This option may appear an
268           unlimited number of times.
269
270       -V, --version
271           Output version of program and exit.
272
273       Any arguments given after options are interpreted as server addresses
274       or hostnames, with the iburst option implied. Associations with these
275       are formed before any associations implied by the configuration file.
276

USAGE

278   How NTP Operates
279       The ntpd utility operates by exchanging messages with one or more
280       configured servers over a range of designated poll intervals. When
281       started, whether for the first or subsequent times, the program
282       requires several exchanges from the majority of these servers so the
283       signal processing and mitigation algorithms can accumulate and groom
284       the data and set the clock. In order to protect the network from
285       bursts, the initial poll interval for each server is delayed an
286       interval randomized over a few seconds. At the default initial poll
287       interval of 64s, several minutes can elapse before the clock is set.
288       This initial delay to set the clock can be safely and dramatically
289       reduced using the iburst keyword with the server configuration command,
290       as described in ntp.conf(5).
291
292       Most operating systems and hardware of today incorporate a time-of-year
293       (TOY) chip to maintain the time during periods when the power is off.
294       When the machine is booted, the chip is used to initialize the
295       operating system time. After the machine has synchronized to an NTP
296       server, the operating system corrects the chip from time to time. In
297       the default case, if ntpd detects that the time on the host is more
298       than 1000s from the server time, ntpd assumes something must be
299       terribly wrong, and the only reliable action is for the operator to
300       intervene and set the clock by hand. (Reasons for this include there is
301       no TOY chip, or its battery is dead, or that the TOY chip is just of
302       poor quality.) This causes ntpd to exit with a panic message to the
303       system log. The -g option overrides this check, and the clock will be
304       set to the server time regardless of the chip time (up to 68 years in
305       the past or future — this is a limitation of the NTPv4 protocol).
306       However, and to protect against broken hardware, such as when the CMOS
307       battery fails or the clock counter becomes defective, once the clock
308       has been set an error greater than 1000s will cause ntpd to exit
309       anyway.
310
311       Under ordinary conditions, ntpd adjusts the clock in small steps so
312       that the timescale is effectively continuous and without
313       discontinuities. Under conditions of extreme network congestion, the
314       roundtrip delay jitter can exceed three seconds and the synchronization
315       distance, which is equal to one-half the roundtrip delay plus error
316       budget terms, can become very large. The ntpd algorithms discard sample
317       offsets exceeding 128 ms, unless the interval during which no sample
318       offset is less than 128 ms exceeds 900s. The first sample after that,
319       no matter what the offset, steps the clock to the indicated time. In
320       practice, this reduces the false alarm rate where the clock is stepped
321       in error to a vanishingly low incidence.
322
323       As the result of this behavior, once the clock has been set it very
324       rarely strays more than 128 ms even under extreme cases of network path
325       congestion and jitter. Sometimes, in particular, when ntpd is first
326       started without a valid drift file on a system with a large intrinsic
327       drift the error might grow to exceed 128 ms, which would cause the
328       clock to be set backwards if the local clock time is more than 128 ms
329       in the future relative to the server. In some applications, this
330       behavior may be unacceptable. There are several solutions, however. If
331       the -x option is included on the command line, the clock will never be
332       stepped and only slew corrections will be used. But this choice comes
333       at a cost that should be carefully explored before deciding to use the
334       -x option. The maximum slew rate possible is limited to 500
335       parts-per-million (PPM) as a consequence of the correctness principles
336       on which the NTP protocol and algorithm design are based. As a result,
337       the local clock can take a long time to converge to an acceptable
338       offset, about 2,000 s for each second the clock is outside the
339       acceptable range. During this interval, the local clock will not be
340       consistent with any other network clock and the system cannot be used
341       for distributed applications that require correctly synchronized
342       network time.
343
344       In spite of the above precautions, sometimes when large frequency
345       errors are present the resulting time offsets stray outside the 128-ms
346       range and an eventual step or slew time correction is required. If
347       following such a correction the frequency error is so large that the
348       first sample is outside the acceptable range, ntpd enters the same
349       state as when the ntp.drift file is not present. The intent of this
350       behavior is to quickly correct the frequency and restore operation to
351       the normal tracking mode. In the most extreme cases, there may be
352       occasional step/slew corrections and subsequent frequency corrections.
353       It helps in these cases to use the burst keyword when configuring the
354       server, but ONLY when you have permission to do so from the owner of
355       the target host.
356
357       Finally, in the past, many startup scripts would run a separate utility
358       to get the system clock close to correct before starting ntpd(8), but
359       this was never more than a mediocre hack and is no longer needed. If
360       you are following the best current practice <#starting> and you still
361       need to set the system time before starting ntpd, please open a bug
362       report and document what is going on, and then look at using ntpdig(1).
363
364       There is a way to start ntpd(8) that often addresses all of the
365       problems mentioned above.
366
367   Starting NTP (Best Current Practice)
368       First, use the iburst option on your server and pool entries.
369
370       If you can also keep a good ntp.drift file then ntpd(8) will
371       effectively "warm-start" and your system’s clock will be stable in
372       under 11 seconds' time.
373
374       As soon as possible in the startup sequence, start ntpd(8) with at
375       least the -g and perhaps the -N options. Then, start the rest of your
376       "normal" processes. This will give ntpd(8) as much time as possible to
377       get the system’s clock synchronized and stable.
378
379       Finally, if you have processes like dovecot or database servers that
380       require monotonically-increasing time, run ntpwait(8) as late as
381       possible in the boot sequence (perhaps with the -v flag) and after
382       ntpwait(8) exits successfully it is as safe as it will ever be to start
383       any processes that require stable time.
384
385   Frequency Discipline
386       The ntpd behavior at startup depends on whether the frequency file,
387       usually ntp.drift, exists. This file contains the latest estimate of
388       clock frequency error. When the ntpd is started and the file does not
389       exist, the ntpd enters a special mode designed to quickly adapt to the
390       particular system clock oscillator time and frequency error. This takes
391       approximately 15 minutes, after which the time and frequency are set to
392       nominal values and the ntpd enters normal mode, where the time and
393       frequency are continuously tracked relative to the server. After one
394       hour the frequency file is created and the current frequency offset
395       written to it. When the ntpd is started and the file does exist, the
396       ntpd frequency is initialized from the file and enters normal mode
397       immediately. After that, the current frequency offset is written to the
398       file at hourly intervals.
399
400   Operating Modes
401       ntpd normally operates continuously while monitoring for small changes
402       in frequency and trimming the clock for the ultimate precision.
403       However, it can operate in a one-time mode where the time is set from
404       an external server and frequency is set from a previously recorded
405       frequency file.
406
407       By default, ntpd runs in continuous mode where each of possibly several
408       external servers is polled at intervals determined by an intricate
409       state machine. The state machine measures the incidental roundtrip
410       delay jitter and oscillator frequency wander and determines the best
411       poll interval using a heuristic algorithm. Ordinarily, and in most
412       operating environments, the state machine will start with 64s intervals
413       and eventually increase in steps to 1024s. A small amount of random
414       variation is introduced in order to avoid bunching at the servers. In
415       addition, should a server become unreachable for some time, the poll
416       interval is increased in steps to 1024s in order to reduce network
417       overhead.
418
419       In some cases, it may not be practical for ntpd to run continuously.
420       The -q option is provided to support running ntpd periodically from a
421       cron(8) job. Setting this option will cause ntpd to exit just after
422       setting the clock for the first time. The procedure for initially
423       setting the clock is the same as in continuous mode; most applications
424       will probably want to specify the iburst keyword with the server
425       configuration command. With this keyword, a volley of messages are
426       exchanged to groom the data and the clock is set in about 10 sec. If
427       nothing is heard after a couple of minutes, the daemon times out and
428       exits.
429
430       When kernel support is available to discipline the clock frequency,
431       which is the case for stock Solaris, Linux, and FreeBSD, a useful
432       feature is available to discipline the clock frequency. First, ntpd is
433       run in continuous mode with selected servers in order to measure and
434       record the intrinsic clock frequency offset in the frequency file. It
435       may take some hours for the frequency and offset to settle down. Then
436       the ntpd is stopped and run in one-time mode as required. At each
437       startup, the frequency is read from the file and initializes the kernel
438       frequency.
439
440   Poll Interval Control
441       This version of NTP includes an intricate state machine to reduce the
442       network load while maintaining a quality of synchronization consistent
443       with the observed jitter and wander. There are a number of ways to
444       tailor the operation in order enhance accuracy by reducing the interval
445       or to reduce network overhead by increasing it. However, the user is
446       advised to carefully consider the consequences of changing the poll
447       adjustment range from the default minimum of 64 s to the default
448       maximum of 1,024 s. The default minimum can be changed with the tinker
449       minpoll command to a value not less than 16 s. This value is used for
450       all configured associations, unless overridden by the minpoll option on
451       the configuration command. Note that most device drivers will not
452       operate properly if the poll interval is less than 64 s and that the
453       broadcast server and manycast client associations will also use the
454       default unless overridden.
455
456       In some cases involving dial up or toll services, it may be useful to
457       increase the minimum interval to a few tens of minutes and maximum
458       interval to a day or so. Under normal operation conditions, once the
459       clock discipline loop has stabilized the interval will be increased in
460       steps from the minimum to the maximum. However, this assumes the
461       intrinsic clock frequency error is small enough for the discipline loop
462       correct it. The capture range of the loop is 500 PPM at an interval of
463       64s decreasing by a factor of two for each doubling of the interval. At
464       a minimum of 1,024 s, for example, the capture range is only 31 PPM. If
465       the intrinsic error is greater than this, the drift file ntp.drift will
466       have to be specially tailored to reduce the residual error below this
467       limit. Once this is done, the drift file is automatically updated once
468       per hour and is available to initialize the frequency on subsequent
469       daemon restarts.
470
471   The huff-n'-puff Filter
472       In scenarios where a considerable amount of data are to be downloaded
473       or uploaded over telephone modems, timekeeping quality can be seriously
474       degraded. This occurs because the differential delays on the two
475       directions of transmission can be quite large. In many cases, the
476       apparent time errors are so large as to exceed the step threshold and a
477       step correction can occur during and after the data transfer is in
478       progress.
479
480       The huff-n'-puff filter is designed to correct the apparent time offset
481       in these cases. It depends on knowledge of the propagation delay when
482       no other traffic is present. In common scenarios, this occurs during
483       other than work hours. The filter maintains a shift register that
484       remembers the minimum delay over the most recent interval measured
485       usually in hours. Under conditions of severe delay, the filter corrects
486       the apparent offset using the sign of the offset and the difference
487       between the apparent delay and minimum delay. The name of the filter
488       reflects the negative (huff) and positive (puff) correction, which
489       depends on the sign of the offset.
490
491       The filter is activated by the tinker command and huffpuff keyword, as
492       described in ntp.conf(5).
493

FILES

495       ┌─────────────────┬───────────────────┬────────┬─────────────┐
496       │                 │                   │        │             │
497       │File             │ Default           │ Option │ Option      │
498       ├─────────────────┼───────────────────┼────────┼─────────────┤
499       │                 │                   │        │             │
500       │configuration    │ /etc/ntp.conf     │ -c     │ conffile    │
501       │file             │                   │        │             │
502       ├─────────────────┼───────────────────┼────────┼─────────────┤
503       │                 │                   │        │             │
504       │configuration    │ /etc/ntp.d        │ -c     │ conffile    │
505       │directory        │                   │        │             │
506       ├─────────────────┼───────────────────┼────────┼─────────────┤
507       │                 │                   │        │             │
508       │frequency file   │ none              │ -f     │ driftfile   │
509       ├─────────────────┼───────────────────┼────────┼─────────────┤
510       │                 │                   │        │             │
511       │leapseconds file │ none              │        │ leapfile    │
512       ├─────────────────┼───────────────────┼────────┼─────────────┤
513       │                 │                   │        │             │
514       │process ID file  │ none              │ -p     │ pidfile     │
515       ├─────────────────┼───────────────────┼────────┼─────────────┤
516       │                 │                   │        │             │
517       │log file         │ system log        │ -l     │ logfile     │
518       ├─────────────────┼───────────────────┼────────┼─────────────┤
519       │                 │                   │        │             │
520       │include file     │ none              │ none   │ includefile │
521       ├─────────────────┼───────────────────┼────────┼─────────────┤
522       │                 │                   │        │             │
523       │statistics path  │ /var/log/ntpstats │ -s     │ statsdir    │
524       ├─────────────────┼───────────────────┼────────┼─────────────┤
525       │                 │                   │        │             │
526       │keys file        │ none              │ -k     │ keys        │
527       └─────────────────┴───────────────────┴────────┴─────────────┘
528
529       Configuration files are parsed according to the following rules:
530
531        1. The plain config file (normally /etc/ntp.conf but the path can be
532           overridden by the -c option) is read first if it exists.
533
534        2. Then the configuration directory, if it exists, is scanned.
535           Normally this directory is /etc/ntp.d, but if the -c option is
536           specified the /etc will be specified by the directory name of the
537           -c argument.
538
539        3. Each file beneath the configuration directory with the extension
540           ".conf" is interpreted. Files are interpreted in ASCII sort order
541           of their pathnames. Files with other extensions or no extensions
542           are ignored.
543

SIGNALS

545       SIGQUIT, SIGINT, and SIGTERM will cause ntpd to clean up and exit.
546
547       SIGHUP checks various things that would otherwise require restarting
548       ntpd.
549
550       It will reopen the log file if it has changed and check for a new
551       leapseconds file if one was specified.
552
553       If the NTS server is enabled, it will reload the certificate file if it
554       has changed. (It doesn’t check for a new key file, but reloads it when
555       it reloads the certificate file.)
556
557       It will also retry any pending DNS or NTS lookups.
558
559       On most systems, you can send SIGHUP to ntpd with
560
561             # killall -HUP ntpd
562
563       If built with debugging enabled (waf configured with --enable-debug)
564       SIGUSR1 will increase the debug level by 1 and SIGUSR2 will decrease it
565       by 1. This may be helpful if you are running with -n, either just to
566       see the logging on your screen or with gdb.
567

BUGS

569       The -V option is not backward-compatible with its use (as the
570       equivalent of -Z) in older versions.
571

STANDARDS

573       RFC 1059
574           David L. Mills, Network Time Protocol (Version 1), RFC 1059
575
576       RFC 1119
577           David L. Mills, Network Time Protocol (Version 2), RFC 1119
578
579       RFC 1305
580           David L. Mills, Network Time Protocol (Version 3), RFC 1305
581
582       RFC 5905
583           David L. Mills and J. Martin, Ed. and J. Burbank and W. Kasch,
584           Network Time Protocol Version 4: Protocol and Algorithms
585           Specification, RFC 5905
586
587       RFC 5907
588           H&#x2e; Gerstung and C. Elliott and B. Haberman, Ed., Definitions
589           of Managed Objects for Network Time Protocol Version 4: (NTPv4),
590           RFC 5907
591
592       RFC 5908
593           R&#x2e; Gayraud and B. Lourdelet, Network Time Protocol (NTP)
594           Server Option for DHCPv6, RFC 5908
595

EXIT STATUS

597       One of the following exit values will be returned:
598
599       0 (EXIT_SUCCESS)
600           Successful program execution.
601
602       1 (EXIT_FAILURE)
603           Execution failed - examine system logfiles.
604

SEE ALSO

606       ntp.conf(5), ntpq(1), ntpdig(1).
607
608
609
610NTPsec                            2023-08-03                           NTPD(8)
Impressum