1ntpd(8) System Manager's Manual ntpd(8)
2
6 ntpd - Network Time Protocol (NTP) daemon
7
10 ntpd [ -46aAbdDgLmnNqx ] [ -c conffile ] [ -f driftfile ] [ -i jaildir
11 ] [ -I iface ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -P prior‐
12 ity ] [ -r broadcastdelay ] [ -s statsdir ] [ -t key ] [ -u
13 user[:group] ] [ -U interface_update_interval ] [ -v variable ] [ -V
14 variable ]
15
18 The ntpd program is an operating system daemon that synchronises the
19 system clock with remote NTP time servers or local reference clocks. It
20 is a complete implementation of the Network Time Protocol (NTP) version
21 4, but also retains compatibility with version 3, as defined by
22 RFC-1305, and version 1 and 2, as defined by RFC-1059 and RFC-1119,
23 respectively. The program can operate in any of several modes, as
24 described on the Association Management page, and with both symmetric
25 key and public key cryptography, as described on the Authentication
26 Options page.
27 The ntpd program ordinarily requires a configuration file as desccribe
29 on the Configuration Commands and Options collection above. However a
30 client can discover remote servers and configure them automatically.
31 This makes it possible to deploy a fleet of workstations without speci‐
32 fying configuration details specific to the local environment. Further
33 details are on the Automatic Server Discovery page.
34 Once the NTP software distribution has been compiled and installed and
36 the configuration file constructed, the next step is to verify correct
37 operation and fix any bugs that may result. Usually, the command line
38 that starts the daemon is included in the system startup file, so it is
39 executed only at system boot time; however, the daemon can be stopped
40 and restarted from root at any time. Once started, the daemon will
41 begin sending and receiving messages, as specified in the configuration
42 file.
43
46 The ntpd program operates by exchanging messages with one or more
47 servers at designated intervals ranging from about one minute to about
48 17 minutes. When started, the program requires several exchanges while
49 the algorithms accumulate and groom the data before setting the clock.
50 The initial delay to set the clock can be reduced using options on the
51 Server Options page.
52 Most compters today incorporate a time-of-year (TOY) chip to maintain
54 the time during periods when the power is off. When the machine is
55 booted, the chip is used to initialize the operating system time. In
56 case there is no TOY chip or the TOY time is more than 1000 s from the
57 server time, ntpd assumes something must be terribly wrong and exits
58 with a panic message to the system operator. With the -g option the
59 clock will be initially set to the server time regardless of the chip
60 time. However, once the clock has been set, an error greater than 1000
61 s will cause ntpd to exit anyway.
62 Under ordinary conditions, ntpd slews the clock so that the time is
64 effectively continuous and never runs backwards. If due to extreme net‐
65 work congestion an error spike exceeds the step threshold, by default
66 128 ms, the spike is discarded. However, if the error persists for more
67 than the stepout threshold, by default 900 s, the system clock is
68 stepped to the correct value. In practice the need for a step has is
69 extremely rare and almost always the result of a hardware failure. With
70 the -x option the step threshold is increased to 600 s. Other options
71 are available using the tinker command on the Miscellaneous Options
72 page.
73 The issues should be carefully considered before using these options.
75 The maximum slew rate possible is limited to 500 parts-per-million
76 (PPM) by the Unix kernel. As a result, the clock can take 2000 s for
77 each second the clock is outside the acceptable range. During this
78 interval the clock will not be consistent with any other network clock
79 and the system cannot be used for distributed applications that require
80 correctly synchronized network time.
81 The frequency file, usually called ntp.drift, contains the latest esti‐
83 mate of clock frequency. If this file does not exist when ntpd is
84 started, it enters a special mode designed to measure the particular
85 frequency directly. The measurement takes 15 minutes, after which the
86 frequency is set and ntpd resumes normal mode where the time and fre‐
87 quency are continuously adjusted. The frequency file is updated at
88 intervals of an hour or more depending on the measured clock stability.
89
92 The ntpd program normally operates continuously while adjusting the
93 time and frequency, but in some cases it may not be practical to run it
94 continuously. With the -q option ntpd operates as in continous mode,
95 but exits just after setting the clock for the first time with the con‐
96 figured servers. Most applications will probably want to specify the
97 iburst option with the server command. With this option a volley of
98 messages is exchanged to groom the data and set the clock in about 10
99 s. If nothing is heard after a few minutes, the daemon times out and
100 exits.
101
104 NTP uses an intricate heuristic algorithm to automatically control the
105 poll interval for maximum accuracy consistent with minimum network
106 overhead. The algorithm measures the incidental offset and jitter to
107 determine the best poll interval. When ntpd starts, the interval is the
108 default minimum 64 s. Under normal conditions when the clock discipline
109 has stabilized, the interval increases in steps to the default maximum
110 1024 s. In addition, should a server become unreachable after some
111 time, the interval increases in steps to the maximum in order to reduce
112 network overhead.
113 The default poll interval range is suitable for most conditions, but
115 can be changed using options on the Server Options and Miscellaneous
116 Options pages. However, when using maximum intervals much larger than
117 the default, the residual clock frequency error must be small enough
118 for the discipline loop to capture and correct. The capture range is
119 500 PPM with a 64-s interval decreasing by a factor of two for each
120 interval doubling. At a 36-hr interval, for example, the capture range
121 is only 0.24 PPM.
122
125 In scenarios where a considerable amount of data are to be downloaded
126 or uploaded over telephone modems, timekeeping quality can be seriously
127 degraded. This occurs because the differential delays on the two direc‐
128 tions of transmission can be quite large. In many cases the apparent
129 time errors are so large as to exceed the step threshold and a step
130 correction can occur during and after the data transfer.
131 The huff-n'-puff filter is designed to correct the apparent time offset
133 in these cases. It depends on knowledge of the propagation delay when
134 no other traffic is present, such as during other than work hours. The
135 filter remembers the minimum delay over the most recent interval mea‐
136 sured usually in hours. Under conditions of severe delay, the filter
137 corrects the apparent offset using the sign of the offset and the dif‐
138 ference between the apparent delay and minimum delay. The name of the
139 filter reflects the negative (huff) and positive (puff) correction,
140 which depends on the sign of the offset. The filter is activated by the
141 tinker huffpuff command, as described in the Miscellaneous Options
142 page.
143
146 As provided by international agreement, an extra second is sometimes
147 inserted in Coordinated Universal Time (UTC) at the end of a selected
148 month, usually June or December. The National Institutes of Standards
149 and Technology (NIST) provides an historic leapseconds file at
150 time.nist.gov for retrieval via FTP. When this file, usually called
151 ntp-leapseconds.list, is copied and installed in a directory. The leap‐
152 file configuration command specifies the path to this file. At startup,
153 ntpd reads it and initializes three leapsecond values: the NTP seconds
154 at the next leap event, the offset of UTC relative to International
155 Atomic Time (TAI) after the leap and the NTP seconds when the leapsec‐
156 onds file expires and should be retrieved again.
157 If a host does not have the leapsecond values, they can be obtained
159 over the net using the Autokey security protocol. Ordinarily, the
160 leapseconds file is installed on the primary servers and the values
161 flow from them via secondary servers to the clients. When multiple
162 servers are involved, the values with the latest expiration time are
163 used.
164 If the latest leap is in the past, nothing further is done other than
166 to install the TAI offset. If the leap is in the future less than 28
167 days, the leap warning bits are set. If in the future less than 23
168 hours, the kernel is armed to insert one second at the end of the cur‐
169 rent day. If the kernel is enabled, the leap is done automatically at
170 that time; otherwise, the clock is effectively stopped for one second
171 at the leap. Additional details are in the The NTP Timescale and Leap
172 Seconds white paper
173 If none of the above provisions are available, dsependent servers and
175 clients tally the leap warning bits of surviving servers and reference
176 clocks. When a majority of the survivors show warning, a leap is pro‐
177 grammed at the end of the current month. During the month and day of
178 insertion, they operate as above. In this way the leap is is propagated
179 at all dependent servers and clients.
180
183 A new experimental feature called interleaved modes can be used in NTP
184 symmetric or broadcast modes. It is designed to improve accuracy by
185 avoiding kernel latency and queueing delay, as described on the NTP
186 Interleaved Modes page. It is activated by the xleave option with the
187 peer or broadcast configuration commands. The NTP protocol automati‐
188 cally reconfigures in normal or interleaved mode as required. Ordinary
189 broadcast clients can use the same servers as interleaved clients at
190 the same time. Further details are in the white paper NTP Interleaved
191 On-Wire Protocol and the briefing Interleaved Synchronization Protocols
192 for LANs and Space Data Links.
193 If ntpd, is configured with NetInfo support, it will attempt to read
195 its configuration from the NetInfo service if the default ntp.conf file
196 cannot be read and no file is specified by the -c option.
197 In contexts where a host name is expected, a -4 qualifier preceding the
199 host name forces DNS resolution to the IPv4 namespace, while a -6 qual‐
200 ifier forces DNS resolution to the IPv6 namespace.
201 Various internal ntpd variables can be displayed and configuration
203 options altered while the ntpd is running using the ntpq and ntpdc
204 utility programs.
205 When ntpd starts it looks at the value of umask, and if zero ntpd will
207 set the umask to 022.
208 Unless the -n, -d or -D option is used, ntpd changes the current work‐
210 ing directory to the root directory, so any options or commands speci‐
211 fying paths need to use an absolute path or a path relative to the
212 root.
213
216 -4 Force DNS resolution of host names to the IPv4 namespace.
217 -6 Force DNS resolution of host names to the IPv6 namespace.
219 -a Require cryptographic authentication for broadcast client, mul‐
221 ticast client and symmetric passive associations. This is the
222 same operation as the enable auth command and is the default.
223 -A Do not require cryptographic authentication for broadcast
225 client, multicast client and symmetric passive associations.
226 This is the same operation as the disable auth command and
227 almost never a good idea.
228 -b Enable the client to synchronize to broadcast servers.
230 -c conffile
232 Specify the name and path of the configuration file, default
233 /etc/ntp.conf.
234 -d Specify debugging mode. This option may occur more than once,
236 with each occurrence indicating greater detail of display.
237 -D level
239 Specify debugging level directly.
240 -f driftfile
242 Specify the name and path of the frequency file. This is the
243 same operation as the driftfile driftfile command.
244 -g Normally, ntpd exits with a message to the system log if the
246 offset exceeds the panic threshold, which is 1000 s by default.
247 This option allows the time to be set to any value without
248 restriction; however, this can happen only once. If the thresh‐
249 old is exceeded after that, ntpd will exit with a message to
250 the system log. This option can be used with the -q and -x
251 options. See the tinker command for other options.
252 -i jaildir
254 Chroot the server to the directory jaildir. This option also
255 implies that the server attempts to drop root privileges at
256 startup (otherwise, chroot gives very little additional secu‐
257 rity), and it is only available if the OS supports to run the
258 server without full root privileges. You may need to also spec‐
259 ify a -u option.
260 -I [address | interface name]
262 Open the network address given, or all the addresses associated
263 with the given interface name. This option may appear multiple
264 times. This option also implies not opening other addresses,
265 except wildcard and localhost. This option is deprecated.
266 Please consider using the configuration file interface command,
267 which is more versatile.
268 -k keyfile
270 Specify the name and path of the symmetric key file. This is
271 the same operation as the keys keyfile command.
272 -l logfile
274 Specify the name and path of the log file. The default is the
275 system log file. This is the same operation as the logfile log‐
276 file command.
277 -L Do not listen to virtual interfaces, defined as those with
279 names containing a colon. This option is deprecated. Please
280 consider using the configuration file interface command, which
281 is more versatile.
282 -M Raise scheduler precision to its maximum (1 msec) using timeBe‐
284 ginPeriod. (Windows only)
285 -m Lock memory.
287 -n Don't fork.
289 -N To the extent permitted by the operating system, run the ntpd
291 at the highest priority.
292 -p pidfile
294 Specify the name and path of the file used to record the ntpd
295 process ID. This is the same operation as the pidfile pidfile
296 command.
297 -P priority
299 To the extent permitted by the operating system, run the ntpd
300 at the specified priority.
301 -q Exit the ntpd just after the first time the clock is set. This
303 behavior mimics that of the ntpdate program, which is to be
304 retired. The -g and -x options can be used with this option.
305 Note: The kernel time discipline is disabled with this option.
306 -r broadcastdelay
308 Specify the default propagation delay from the broadcast/multi‐
309 cast server to this client. This is necessary only if the delay
310 cannot be computed automatically by the protocol.
311 -s statsdir
313 Specify the directory path for files created by the statistics
314 facility. This is the same operation as the statsdir statsdir
315 command.
316 -t key Add a key number to the trusted key list. This option can occur
318 more than once. This is the same operation as the trustedkey
319 key command.
320 -u user[:group]
322 Specify a user, and optionally a group, to switch to. This
323 option is only available if the OS supports running the server
324 without full root privileges. Currently, this option is sup‐
325 ported under NetBSD (configure with --enable-clockctl) and
326 Linux (configure with --enable-linuxcaps).
327 -U interface update interval
329 Number of seconds to wait between interface list scans to pick
330 up new and delete network interface. Set to 0 to disable
331 dynamic interface list updating. The default is to scan every 5
332 minutes.
333 -v variable
335 -V variable
337 Add a system variable listed by default.
338 -x Normally, the time is slewed if the offset is less than the
340 step threshold, which is 128 ms by default, and stepped if
341 above the threshold. This option sets the threshold to 600 s,
342 which is well within the accuracy window to set the clock manu‐
343 ally. Note: Since the slew rate of typical Unix kernels is lim‐
344 ited to 0.5 ms/s, each second of adjustment requires an amorti‐
345 zation interval of 2000 s. Thus, an adjustment as much as 600 s
346 will take almost 14 days to complete. This option can be used
347 with the -g and -q options. See the tinker command for other
348 options. Note: The kernel time discipline is disabled with this
349 option.
350 --pccfreq frequency
352 Substitute processor cycle counter for QueryPerformanceCounter
353 unconditionally using the given frequency (in Hz). --pccfreq
354 can be used on systems which do not use the PCC to implement
355 QueryPerformanceCounter and have a fixed PCC frequency. The
356 frequency specified must be accurate within 0.5 percent.
357 --usepcc is equivalent on many systems and should be tried
358 first, as it does not require determining the frequency of the
359 processor cycle counter. For x86-compatible processors, the PCC
360 is also referred to as RDTSC, which is the assembly-language
361 instruction to retrieve the current value. (Windows only)
362 --usepcc
364 Substitute processor cycle counter for QueryPerformanceCounter
365 if they appear equivalent. This option should be used only if
366 the PCC frequency is fixed. Power-saving functionality on many
367 laptops varies the PCC frequency. (Windows only)
368
371 Ordinarily, ntpd reads the ntp.conf configuration file at startup in
372 order to determine the synchronization sources and operating modes. It
373 is also possible to specify a working, although limited, configuration
374 entirely on the command line, obviating the need for a configuration
375 file. This may be particularly useful when the local host is to be con‐
376 figured as a broadcast client, with servers determined by listening to
377 broadcasts at run time.
378 Usually, the configuration file is installed as/etc/ntp.conf, but could
380 be installed elsewhere (see the -c conffile command line option). The
381 file format is similar to other Unix configuration files - comments
382 begin with a # character and extend to the end of the line; blank lines
383 are ignored.
384 Configuration commands consist of an initial command keyword followed
386 by a list of option keywords separated by whitespace. Commands may not
387 be continued over multiple lines. Options may be host names, host
388 addresses written in numeric, dotted-quad form, integers, floating
389 point numbers (when specifying times in seconds) and text strings.
390 Optional arguments are delimited by [ ] in the options pages, while
391 alternatives are separated by |. The notation [ ... ] means an
392 optional, indefinite repetition of the last item before the [ ... ].
393
396 ┌─────────────────────┬──────────────────────┬──────────┬──────────────┐
397 │File │ Default │ Option │ Command │
398 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
399 │configuration file │ /etc/ntp.conf │ -c │ none │
400 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
401 │frequency file │ none │ -f │ driftfile │
402 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
403 │leapseconds file │ none │ │ leapfile │
404 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
405 │process ID file │ none │ -p │ pidfile │
406 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
407 │log file │ system log │ -l │ logfile │
408 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
409 │include file │ none │ none │ includefile │
410 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
411 │statistics path │ /var/log/ntpstats/ │ -s │ statsdir │
412 ├─────────────────────┼──────────────────────┼──────────┼──────────────┤
413 │keys path │ /etc/ntp/crypto │ none │ keysdir │
414 └─────────────────────┴──────────────────────┴──────────┴──────────────┘
415
417 A non-zero exit code indicates an error. Any error messages are logged
418 to the system log by default.
419 The exit code is 0 only when ntpd is terminated by a signal, or when
421 the -q option is used and ntpd successfully sets the system clock.
422
425 ntp.conf(5), ntpq(8), ntpdc(8)
426 HTML documentation in ntp-doc package.
428 This file was automatically generated from HTML source.
430 ntpd(8)