1ntp.conf(5) File Formats ntp.conf(5)
2
6 ntp.conf - Network Time Protocol (NTP) daemon configuration file format
7
9 ntp.conf [--option-name] [--option-name value]
10 All arguments must be options.
12
15 The ntp.conf configuration file is read at initial startup by the
16 ntpd(8) daemon in order to specify the synchronization sources, modes
17 and other related information. Usually, it is installed in the /etc
18 directory, but could be installed elsewhere (see the daemon's -c com‐
19 mand line option).
20 The file format is similar to other UNIX configuration files. Comments
22 begin with a ‘#’ character and extend to the end of the line; blank
23 lines are ignored. Configuration commands consist of an initial key‐
24 word followed by a list of arguments, some of which may be optional,
25 separated by whitespace. Commands may not be continued over multiple
26 lines. Arguments may be host names, host addresses written in numeric,
27 dotted-quad form, integers, floating point numbers (when specifying
28 times in seconds) and text strings.
29 The rest of this page describes the configuration and control options.
31 The "Notes on Configuring NTP and Setting up an NTP Subnet" page
32 (available as part of the HTML documentation provided in
33 /usr/share/doc/ntp) contains an extended discussion of these options.
34 In addition to the discussion of general Configuration Options, there
35 are sections describing the following supported functionality and the
36 options used to control it:
37 · Authentication Support
39 · Monitoring Support
41 · Access Control Support
43 · Automatic NTP Configuration Options
45 · Reference Clock Support
47 · Miscellaneous Options
49 Following these is a section describing Miscellaneous Options. While
51 there is a rich set of options available, the only required option is
52 one or more pool, server, peer, broadcast or manycastclient commands.
53
55 Following is a description of the configuration commands in NTPv4.
56 These commands have the same basic functions as in NTPv3 and in some
57 cases new functions and new arguments. There are two classes of com‐
58 mands, configuration commands that configure a persistent association
59 with a remote server or peer or reference clock, and auxiliary commands
60 that specify environmental variables that control various related oper‐
61 ations.
62 Configuration Commands
64 The various modes are determined by the command keyword and the type of
65 the required IP address. Addresses are classed by type as (s) a remote
66 server or peer (IPv4 class A, B and C), (b) the broadcast address of a
67 local interface, (m) a multicast address (IPv4 class D), or (r) a ref‐
68 erence clock address (127.127.x.x). Note that only those options
69 applicable to each command are listed below. Use of options not listed
70 may not be caught as an error, but may result in some weird and even
71 destructive behavior.
72 If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is
74 detected, support for the IPv6 address family is generated in addition
75 to the default support of the IPv4 address family. In a few cases,
76 including the reslist billboard generated by ntpq(8) or ntpdc(8), IPv6
77 addresses are automatically generated. IPv6 addresses can be identi‐
78 fied by the presence of colons : in the address field. IPv6 addresses
79 can be used almost everywhere where IPv4 addresses can be used, with
80 the exception of reference clock addresses, which are always IPv4.
81 Note that in contexts where a host name is expected, a -4 qualifier
83 preceding the host name forces DNS resolution to the IPv4 namespace,
84 while a -6 qualifier forces DNS resolution to the IPv6 namespace. See
85 IPv6 references for the equivalent classes for that address family.
86 pool address [burst] [iburst] [version version] [prefer] [minpoll min‐
88 poll] [maxpoll maxpoll]
89 server address [key key | autokey] [burst] [iburst] [version version]
91 [prefer] [minpoll minpoll] [maxpoll maxpoll] [true]
92 peer address [key key | autokey] [version version] [prefer] [minpoll
94 minpoll] [maxpoll maxpoll] [true] [xleave]
95 broadcast address [key key | autokey] [version version] [prefer] [min‐
97 poll minpoll] [ttl ttl] [xleave]
98 manycastclient address [key key | autokey] [version version] [prefer]
100 [minpoll minpoll] [maxpoll maxpoll] [ttl ttl]
101 These five commands specify the time server name or address to be used
103 and the mode in which to operate. The address can be either a DNS name
104 or an IP address in dotted-quad notation. Additional information on
105 association behavior can be found in the "Association Management" page
106 (available as part of the HTML documentation provided in
107 /usr/share/doc/ntp).
108 pool For type s addresses, this command mobilizes a persistent client
110 mode association with a number of remote servers. In this mode
111 the local clock can synchronized to the remote server, but the
112 remote server can never be synchronized to the local clock.
113 server For type s and r addresses, this command mobilizes a persistent
115 client mode association with the specified remote server or
116 local radio clock. In this mode the local clock can synchro‐
117 nized to the remote server, but the remote server can never be
118 synchronized to the local clock. This command should not be
119 used for type b or m addresses.
120 peer For type s addresses (only), this command mobilizes a persistent
122 symmetric-active mode association with the specified remote
123 peer. In this mode the local clock can be synchronized to the
124 remote peer or the remote peer can be synchronized to the local
125 clock. This is useful in a network of servers where, depending
126 on various failure scenarios, either the local or remote peer
127 may be the better source of time. This command should NOT be
128 used for type b, m or r addresses.
129 broadcast
131 For type b and m addresses (only), this command mobilizes a per‐
132 sistent broadcast mode association. Multiple commands can be
133 used to specify multiple local broadcast interfaces (subnets)
134 and/or multiple multicast groups. Note that local broadcast
135 messages go only to the interface associated with the subnet
136 specified, but multicast messages go to all interfaces. In
137 broadcast mode the local server sends periodic broadcast mes‐
138 sages to a client population at the address specified, which is
139 usually the broadcast address on (one of) the local network(s)
140 or a multicast address assigned to NTP. The IANA has assigned
141 the multicast group address IPv4 224.0.1.1 and IPv6 ff05::101
142 (site local) exclusively to NTP, but other nonconflicting
143 addresses can be used to contain the messages within administra‐
144 tive boundaries. Ordinarily, this specification applies only to
145 the local server operating as a sender; for operation as a
146 broadcast client, see the broadcastclient or multicastclient
147 commands below.
148 manycastclient
150 For type m addresses (only), this command mobilizes a manycast
151 client mode association for the multicast address specified. In
152 this case a specific address must be supplied which matches the
153 address used on the manycastserver command for the designated
154 manycast servers. The NTP multicast address 224.0.1.1 assigned
155 by the IANA should NOT be used, unless specific means are taken
156 to avoid spraying large areas of the Internet with these mes‐
157 sages and causing a possibly massive implosion of replies at the
158 sender. The manycastserver command specifies that the local
159 server is to operate in client mode with the remote servers that
160 are discovered as the result of broadcast/multicast messages.
161 The client broadcasts a request message to the group address
162 associated with the specified address and specifically enabled
163 servers respond to these messages. The client selects the
164 servers providing the best time and continues as with the server
165 command. The remaining servers are discarded as if never heard.
166 Options:
168 autokey
170 All packets sent to and received from the server or peer are to
171 include authentication fields encrypted using the autokey scheme
172 described in Authentication Options.
173 burst when the server is reachable, send a burst of eight packets
175 instead of the usual one. The packet spacing is normally 2 s;
176 however, the spacing between the first and second packets can be
177 changed with the calldelay command to allow additional time for
178 a modem or ISDN call to complete. This is designed to improve
179 timekeeping quality with the server command and s addresses.
180 iburst When the server is unreachable, send a burst of eight packets
182 instead of the usual one. The packet spacing is normally 2 s;
183 however, the spacing between the first two packets can be
184 changed with the calldelay command to allow additional time for
185 a modem or ISDN call to complete. This is designed to speed the
186 initial synchronization acquisition with the server command and
187 s addresses and when ntpd(8) is started with the -q option.
188 key key
190 All packets sent to and received from the server or peer are to
191 include authentication fields encrypted using the specified key
192 identifier with values from 1 to 65535, inclusive. The default
193 is to include no encryption field.
194 minpoll minpoll
196 maxpoll maxpoll
198 These options specify the minimum and maximum poll intervals for
199 NTP messages, as a power of 2 in seconds The maximum poll inter‐
200 val defaults to 10 (1,024 s), but can be increased by the max‐
201 poll option to an upper limit of 17 (36.4 h). The minimum poll
202 interval defaults to 6 (64 s), but can be decreased by the min‐
203 poll option to a lower limit of 4 (16 s).
204 noselect
206 Marks the server as unused, except for display purposes. The
207 server is discarded by the selection algroithm.
208 preempt
210 Says the association can be preempted.
211 true Marks the server as a truechimer. Use this option only for
213 testing.
214 prefer Marks the server as preferred. All other things being equal,
216 this host will be chosen for synchronization among a set of cor‐
217 rectly operating hosts. See the "Mitigation Rules and the pre‐
218 fer Keyword" page (available as part of the HTML documentation
219 provided in /usr/share/doc/ntp) for further information.
220 true Forces the association to always survive the selection and clus‐
222 tering algorithms. This option should almost certainly only be
223 used while testing an association.
224 ttl ttl
226 This option is used only with broadcast server and manycast
227 client modes. It specifies the time-to-live ttl to use on
228 broadcast server and multicast server and the maximum ttl for
229 the expanding ring search with manycast client packets. Selec‐
230 tion of the proper value, which defaults to 127, is something of
231 a black art and should be coordinated with the network adminis‐
232 trator.
233 version version
235 Specifies the version number to be used for outgoing NTP pack‐
236 ets. Versions 1-4 are the choices, with version 4 the default.
237 xleave Valid in peer and broadcast modes only, this flag enables inter‐
239 leave mode.
240 Auxiliary Commands
242 broadcastclient
243 This command enables reception of broadcast server messages to
244 any local interface (type b) address. Upon receiving a message
245 for the first time, the broadcast client measures the nominal
246 server propagation delay using a brief client/server exchange
247 with the server, then enters the broadcast client mode, in which
248 it synchronizes to succeeding broadcast messages. Note that, in
249 order to avoid accidental or malicious disruption in this mode,
250 both the server and client should operate using symmetric-key or
251 public-key authentication as described in Authentication
252 Options.
253 manycastserver address ...
255 This command enables reception of manycast client messages to
256 the multicast group address(es) (type m) specified. At least
257 one address is required, but the NTP multicast address 224.0.1.1
258 assigned by the IANA should NOT be used, unless specific means
259 are taken to limit the span of the reply and avoid a possibly
260 massive implosion at the original sender. Note that, in order
261 to avoid accidental or malicious disruption in this mode, both
262 the server and client should operate using symmetric-key or pub‐
263 lic-key authentication as described in Authentication Options.
264 multicastclient address ...
266 This command enables reception of multicast server messages to
267 the multicast group address(es) (type m) specified. Upon
268 receiving a message for the first time, the multicast client
269 measures the nominal server propagation delay using a brief
270 client/server exchange with the server, then enters the broad‐
271 cast client mode, in which it synchronizes to succeeding multi‐
272 cast messages. Note that, in order to avoid accidental or mali‐
273 cious disruption in this mode, both the server and client should
274 operate using symmetric-key or public-key authentication as
275 described in Authentication Options.
276 mdnstries number
278 If we are participating in mDNS, after we have synched for the
279 first time we attempt to register with the mDNS system. If that
280 registration attempt fails, we try again at one minute intervals
281 for up to mdnstries times. After all, ntpd may be starting
282 before mDNS. The default value for mdnstries is 5.
283
285 Authentication support allows the NTP client to verify that the server
286 is in fact known and trusted and not an intruder intending accidentally
287 or on purpose to masquerade as that server. The NTPv3 specification
288 RFC-1305 defines a scheme which provides cryptographic authentication
289 of received NTP packets. Originally, this was done using the Data
290 Encryption Standard (DES) algorithm operating in Cipher Block Chaining
291 (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced
292 by the RSA Message Digest 5 (MD5) algorithm using a private key, com‐
293 monly called keyed-MD5. Either algorithm computes a message digest, or
294 one-way hash, which can be used to verify the server has the correct
295 private key and key identifier.
296 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
298 cryptography and, in addition, provides a new Autokey scheme based on
299 public key cryptography. Public key cryptography is generally consid‐
300 ered more secure than symmetric key cryptography, since the security is
301 based on a private value which is generated by each server and never
302 revealed. With Autokey all key distribution and management functions
303 involve only public values, which considerably simplifies key distribu‐
304 tion and storage. Public key management is based on X.509 certifi‐
305 cates, which can be provided by commercial services or produced by
306 utility programs in the OpenSSL software library or the NTPv4 distribu‐
307 tion.
308 While the algorithms for symmetric key cryptography are included in the
310 NTPv4 distribution, public key cryptography requires the OpenSSL soft‐
311 ware library to be installed before building the NTP distribution.
312 Directions for doing that are on the Building and Installing the Dis‐
313 tribution page.
314 Authentication is configured separately for each association using the
316 key or autokey subcommand on the peer, server, broadcast and manycast‐
317 client configuration commands as described in Configuration Options
318 page. The authentication options described below specify the locations
319 of the key files, if other than default, which symmetric keys are
320 trusted and the interval between various operations, if other than
321 default.
322 Authentication is always enabled, although ineffective if not config‐
324 ured as described below. If a NTP packet arrives including a message
325 authentication code (MAC), it is accepted only if it passes all crypto‐
326 graphic checks. The checks require correct key ID, key value and mes‐
327 sage digest. If the packet has been modified in any way or replayed by
328 an intruder, it will fail one or more of these checks and be discarded.
329 Furthermore, the Autokey scheme requires a preliminary protocol
330 exchange to obtain the server certificate, verify its credentials and
331 initialize the protocol
332 The auth flag controls whether new associations or remote configuration
334 commands require cryptographic authentication. This flag can be set or
335 reset by the enable and disable commands and also by remote configura‐
336 tion commands sent by a ntpdc(8) program running on another machine.
337 If this flag is enabled, which is the default case, new broadcast
338 client and symmetric passive associations and remote configuration com‐
339 mands must be cryptographically authenticated using either symmetric
340 key or public key cryptography. If this flag is disabled, these opera‐
341 tions are effective even if not cryptographic authenticated. It should
342 be understood that operating with the auth flag disabled invites a sig‐
343 nificant vulnerability where a rogue hacker can masquerade as a falset‐
344 icker and seriously disrupt system timekeeping. It is important to
345 note that this flag has no purpose other than to allow or disallow a
346 new association in response to new broadcast and symmetric active mes‐
347 sages and remote configuration commands and, in particular, the flag
348 has no effect on the authentication process itself.
349 An attractive alternative where multicast support is available is many‐
351 cast mode, in which clients periodically troll for servers as described
352 in the Automatic NTP Configuration Options page. Either symmetric key
353 or public key cryptographic authentication can be used in this mode.
354 The principle advantage of manycast mode is that potential servers need
355 not be configured in advance, since the client finds them during regu‐
356 lar operation, and the configuration files for all clients can be iden‐
357 tical.
358 The security model and protocol schemes for both symmetric key and pub‐
360 lic key cryptography are summarized below; further details are in the
361 briefings, papers and reports at the NTP project page linked from
362 http://www.ntp.org/.
363 Symmetric-Key Cryptography
365 The original RFC-1305 specification allows any one of possibly 65,535
366 keys, each distinguished by a 32-bit key identifier, to authenticate an
367 association. The servers and clients involved must agree on the key
368 and key identifier to authenticate NTP packets. Keys and related
369 information are specified in a key file, usually called ntp.keys, which
370 must be distributed and stored using secure means beyond the scope of
371 the NTP protocol itself. Besides the keys used for ordinary NTP asso‐
372 ciations, additional keys can be used as passwords for the ntpq(8) and
373 ntpdc(8) utility programs.
374 When ntpd(8) is first started, it reads the key file specified in the
376 keys configuration command and installs the keys in the key cache.
377 However, individual keys must be activated with the trusted command
378 before use. This allows, for instance, the installation of possibly
379 several batches of keys and then activating or deactivating each batch
380 remotely using ntpdc(8). This also provides a revocation capability
381 that can be used if a key becomes compromised. The requestkey command
382 selects the key used as the password for the ntpdc(8) utility, while
383 the controlkey command selects the key used as the password for the
384 ntpq(8) utility.
385 Public Key Cryptography
387 NTPv4 supports the original NTPv3 symmetric key scheme described in
388 RFC-1305 and in addition the Autokey protocol, which is based on public
389 key cryptography. The Autokey Version 2 protocol described on the
390 Autokey Protocol page verifies packet integrity using MD5 message
391 digests and verifies the source with digital signatures and any of sev‐
392 eral digest/signature schemes. Optional identity schemes described on
393 the Identity Schemes page and based on cryptographic challenge/response
394 algorithms are also available. Using all of these schemes provides
395 strong security against replay with or without modification, spoofing,
396 masquerade and most forms of clogging attacks.
397 The Autokey protocol has several modes of operation corresponding to
399 the various NTP modes supported. Most modes use a special cookie which
400 can be computed independently by the client and server, but encrypted
401 in transmission. All modes use in addition a variant of the S-KEY
402 scheme, in which a pseudo-random key list is generated and used in
403 reverse order. These schemes are described along with an executive
404 summary, current status, briefing slides and reading list on the Auton‐
405 omous Authentication page.
406 The specific cryptographic environment used by Autokey servers and
408 clients is determined by a set of files and soft links generated by the
409 ntp-keygen(1ntpkeygenmdoc) program. This includes a required host key
410 file, required certificate file and optional sign key file, leapsecond
411 file and identity scheme files. The digest/signature scheme is speci‐
412 fied in the X.509 certificate along with the matching sign key. There
413 are several schemes available in the OpenSSL software library, each
414 identified by a specific string such as md5WithRSAEncryption, which
415 stands for the MD5 message digest with RSA encryption scheme. The cur‐
416 rent NTP distribution supports all the schemes in the OpenSSL library,
417 including those based on RSA and DSA digital signatures.
418 NTP secure groups can be used to define cryptographic compartments and
420 security hierarchies. It is important that every host in the group be
421 able to construct a certificate trail to one or more trusted hosts in
422 the same group. Each group host runs the Autokey protocol to obtain
423 the certificates for all hosts along the trail to one or more trusted
424 hosts. This requires the configuration file in all hosts to be engi‐
425 neered so that, even under anticipated failure conditions, the NTP sub‐
426 net will form such that every group host can find a trail to at least
427 one trusted host.
428 Naming and Addressing
430 It is important to note that Autokey does not use DNS to resolve
431 addresses, since DNS can't be completely trusted until the name servers
432 have synchronized clocks. The cryptographic name used by Autokey to
433 bind the host identity credentials and cryptographic values must be
434 independent of interface, network and any other naming convention. The
435 name appears in the host certificate in either or both the subject and
436 issuer fields, so protection against DNS compromise is essential.
437 By convention, the name of an Autokey host is the name returned by the
439 Unix gethostname(2) system call or equivalent in other systems. By the
440 system design model, there are no provisions to allow alternate names
441 or aliases. However, this is not to say that DNS aliases, different
442 names for each interface, etc., are constrained in any way.
443 It is also important to note that Autokey verifies authenticity using
445 the host name, network address and public keys, all of which are bound
446 together by the protocol specifically to deflect masquerade attacks.
447 For this reason Autokey includes the source and destination IP
448 addresses in message digest computations and so the same addresses must
449 be available at both the server and client. For this reason operation
450 with network address translation schemes is not possible. This
451 reflects the intended robust security model where government and corpo‐
452 rate NTP servers are operated outside firewall perimeters.
453 Operation
455 A specific combination of authentication scheme (none, symmetric key,
456 public key) and identity scheme is called a cryptotype, although not
457 all combinations are compatible. There may be management configura‐
458 tions where the clients, servers and peers may not all support the same
459 cryptotypes. A secure NTPv4 subnet can be configured in many ways
460 while keeping in mind the principles explained above and in this sec‐
461 tion. Note however that some cryptotype combinations may successfully
462 interoperate with each other, but may not represent good security prac‐
463 tice.
464 The cryptotype of an association is determined at the time of mobiliza‐
466 tion, either at configuration time or some time later when a message of
467 appropriate cryptotype arrives. When mobilized by a server or peer
468 configuration command and no key or autokey subcommands are present,
469 the association is not authenticated; if the key subcommand is present,
470 the association is authenticated using the symmetric key ID specified;
471 if the autokey subcommand is present, the association is authenticated
472 using Autokey.
473 When multiple identity schemes are supported in the Autokey protocol,
475 the first message exchange determines which one is used. The client
476 request message contains bits corresponding to which schemes it has
477 available. The server response message contains bits corresponding to
478 which schemes it has available. Both server and client match the
479 received bits with their own and select a common scheme.
480 Following the principle that time is a public value, a server responds
482 to any client packet that matches its cryptotype capabilities. Thus, a
483 server receiving an unauthenticated packet will respond with an unau‐
484 thenticated packet, while the same server receiving a packet of a cryp‐
485 totype it supports will respond with packets of that cryptotype. How‐
486 ever, unconfigured broadcast or manycast client associations or symmet‐
487 ric passive associations will not be mobilized unless the server sup‐
488 ports a cryptotype compatible with the first packet received. By
489 default, unauthenticated associations will not be mobilized unless
490 overridden in a decidedly dangerous way.
491 Some examples may help to reduce confusion. Client Alice has no spe‐
493 cific cryptotype selected. Server Bob has both a symmetric key file
494 and minimal Autokey files. Alice's unauthenticated messages arrive at
495 Bob, who replies with unauthenticated messages. Cathy has a copy of
496 Bob's symmetric key file and has selected key ID 4 in messages to Bob.
497 Bob verifies the message with his key ID 4. If it's the same key and
498 the message is verified, Bob sends Cathy a reply authenticated with
499 that key. If verification fails, Bob sends Cathy a thing called a
500 crypto-NAK, which tells her something broke. She can see the evidence
501 using the ntpq(8) program.
502 Denise has rolled her own host key and certificate. She also uses one
504 of the identity schemes as Bob. She sends the first Autokey message to
505 Bob and they both dance the protocol authentication and identity steps.
506 If all comes out okay, Denise and Bob continue as described above.
507 It should be clear from the above that Bob can support all the girls at
509 the same time, as long as he has compatible authentication and identity
510 credentials. Now, Bob can act just like the girls in his own choice of
511 servers; he can run multiple configured associations with multiple dif‐
512 ferent servers (or the same server, although that might not be useful).
513 But, wise security policy might preclude some cryptotype combinations;
514 for instance, running an identity scheme with one server and no authen‐
515 tication with another might not be wise.
516 Key Management
518 The cryptographic values used by the Autokey protocol are incorporated
519 as a set of files generated by the ntp-keygen(1ntpkeygenmdoc) utility
520 program, including symmetric key, host key and public certificate
521 files, as well as sign key, identity parameters and leapseconds files.
522 Alternatively, host and sign keys and certificate files can be gener‐
523 ated by the OpenSSL utilities and certificates can be imported from
524 public certificate authorities. Note that symmetric keys are necessary
525 for the ntpq(8) and ntpdc(8) utility programs. The remaining files are
526 necessary only for the Autokey protocol.
527 Certificates imported from OpenSSL or public certificate authorities
529 have certian limitations. The certificate should be in ASN.1 syntax,
530 X.509 Version 3 format and encoded in PEM, which is the same format
531 used by OpenSSL. The overall length of the certificate encoded in
532 ASN.1 must not exceed 1024 bytes. The subject distinguished name field
533 (CN) is the fully qualified name of the host on which it is used; the
534 remaining subject fields are ignored. The certificate extension fields
535 must not contain either a subject key identifier or a issuer key iden‐
536 tifier field; however, an extended key usage field for a trusted host
537 must contain the value trustRoot;. Other extension fields are ignored.
538 Authentication Commands
540 autokey [logsec]
541 Specifies the interval between regenerations of the session key
542 list used with the Autokey protocol. Note that the size of the
543 key list for each association depends on this interval and the
544 current poll interval. The default value is 12 (4096 s or about
545 1.1 hours). For poll intervals above the specified interval, a
546 session key list with a single entry will be regenerated for
547 every message sent.
548 controlkey key
550 Specifies the key identifier to use with the ntpq(8) utility,
551 which uses the standard protocol defined in RFC-1305. The key
552 argument is the key identifier for a trusted key, where the
553 value can be in the range 1 to 65,535, inclusive.
554 crypto [cert file] [leap file] [randfile file] [host file] [sign file]
556 [gq file] [gqpar file] [iffpar file] [mvpar file] [pw password]
557 This command requires the OpenSSL library. It activates public
558 key cryptography, selects the message digest and signature
559 encryption scheme and loads the required private and public val‐
560 ues described above. If one or more files are left unspecified,
561 the default names are used as described above. Unless the com‐
562 plete path and name of the file are specified, the location of a
563 file is relative to the keys directory specified in the keysdir
564 command or default /usr/local/etc. Following are the subcom‐
565 mands:
566 cert file
568 Specifies the location of the required host public cer‐
569 tificate file. This overrides the link ntpkey_cert_host‐
570 name in the keys directory.
571 gqpar file
573 Specifies the location of the optional GQ parameters
574 file. This overrides the link ntpkey_gq_hostname in the
575 keys directory.
576 host file
578 Specifies the location of the required host key file.
579 This overrides the link ntpkey_key_hostname in the keys
580 directory.
581 iffpar file
583 Specifies the location of the optional IFF parameters
584 file. This overrides the link ntpkey_iff_hostname in the
585 keys directory.
586 leap file
588 Specifies the location of the optional leapsecond file.
589 This overrides the link ntpkey_leap in the keys direc‐
590 tory.
591 mvpar file
593 Specifies the location of the optional MV parameters
594 file. This overrides the link ntpkey_mv_hostname in the
595 keys directory.
596 pw password
598 Specifies the password to decrypt files containing pri‐
599 vate keys and identity parameters. This is required only
600 if these files have been encrypted.
601 randfile file
603 Specifies the location of the random seed file used by
604 the OpenSSL library. The defaults are described in the
605 main text above.
606 sign file
608 Specifies the location of the optional sign key file.
609 This overrides the link ntpkey_sign_hostname in the keys
610 directory. If this file is not found, the host key is
611 also the sign key.
612 keys keyfile
614 Specifies the complete path and location of the MD5 key file
615 containing the keys and key identifiers used by ntpd(8), ntpq(8)
616 and ntpdc(8) when operating with symmetric key cryptography.
617 This is the same operation as the -k command line option.
618 keysdir path
620 This command specifies the default directory path for crypto‐
621 graphic keys, parameters and certificates. The default is
622 /usr/local/etc/.
623 requestkey key
625 Specifies the key identifier to use with the ntpdc(8) utility
626 program, which uses a proprietary protocol specific to this
627 implementation of ntpd(8). The key argument is a key identifier
628 for the trusted key, where the value can be in the range 1 to
629 65,535, inclusive.
630 revoke logsec
632 Specifies the interval between re-randomization of certain cryp‐
633 tographic values used by the Autokey scheme, as a power of 2 in
634 seconds. These values need to be updated frequently in order to
635 deflect brute-force attacks on the algorithms of the scheme;
636 however, updating some values is a relatively expensive opera‐
637 tion. The default interval is 16 (65,536 s or about 18 hours).
638 For poll intervals above the specified interval, the values will
639 be updated for every message sent.
640 trustedkey key ...
642 Specifies the key identifiers which are trusted for the purposes
643 of authenticating peers with symmetric key cryptography, as well
644 as keys used by the ntpq(8) and ntpdc(8) programs. The authen‐
645 tication procedures require that both the local and remote
646 servers share the same key and key identifier for this purpose,
647 although different keys can be used with different servers. The
648 key arguments are 32-bit unsigned integers with values from 1 to
649 65,535.
650 Error Codes
652 The following error codes are reported via the NTP control and monitor‐
653 ing protocol trap mechanism.
654 101 (bad field format or length) The packet has invalid version,
656 length or format.
657 102 (bad timestamp) The packet timestamp is the same or older than
659 the most recent received. This could be due to a replay or a
660 server clock time step.
661 103 (bad filestamp) The packet filestamp is the same or older than
663 the most recent received. This could be due to a replay or a
664 key file generation error.
665 104 (bad or missing public key) The public key is missing, has
667 incorrect format or is an unsupported type.
668 105 (unsupported digest type) The server requires an unsupported
670 digest/signature scheme.
671 106 (mismatched digest types) Not used.
673 107 (bad signature length) The signature length does not match the
675 current public key.
676 108 (signature not verified) The message fails the signature check.
678 It could be bogus or signed by a different private key.
679 109 (certificate not verified) The certificate is invalid or signed
681 with the wrong key.
682 110 (certificate not verified) The certificate is not yet valid or
684 has expired or the signature could not be verified.
685 111 (bad or missing cookie) The cookie is missing, corrupted or
687 bogus.
688 112 (bad or missing leapseconds table) The leapseconds table is
690 missing, corrupted or bogus.
691 113 (bad or missing certificate) The certificate is missing, cor‐
693 rupted or bogus.
694 114 (bad or missing identity) The identity key is missing, corrupt
696 or bogus.
697
699 ntpd(8) includes a comprehensive monitoring facility suitable for con‐
700 tinuous, long term recording of server and client timekeeping perfor‐
701 mance. See the statistics command below for a listing and example of
702 each type of statistics currently supported. Statistic files are man‐
703 aged using file generation sets and scripts in the ./scripts directory
704 of the source code distribution. Using these facilities and UNIX
705 cron(8) jobs, the data can be automatically summarized and archived for
706 retrospective analysis.
707 Monitoring Commands
709 statistics name ...
710 Enables writing of statistics records. Currently, eight kinds
711 of name statistics are supported.
712 clockstats
714 Enables recording of clock driver statistics information.
715 Each update received from a clock driver appends a line
716 of the following form to the file generation set named
717 clockstats:
718 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
719 The first two fields show the date (Modified Julian Day)
721 and time (seconds and fraction past UTC midnight). The
722 next field shows the clock address in dotted-quad nota‐
723 tion. The final field shows the last timecode received
724 from the clock in decoded ASCII format, where meaningful.
725 In some clock drivers a good deal of additional informa‐
726 tion can be gathered and displayed as well. See informa‐
727 tion specific to each clock for further details.
728 cryptostats
730 This option requires the OpenSSL cryptographic software
731 library. It enables recording of cryptographic public
732 key protocol information. Each message received by the
733 protocol module appends a line of the following form to
734 the file generation set named cryptostats:
735 49213 525.624 127.127.4.1 message
736 The first two fields show the date (Modified Julian Day)
738 and time (seconds and fraction past UTC midnight). The
739 next field shows the peer address in dotted-quad nota‐
740 tion, The final message field includes the message type
741 and certain ancillary information. See the Authentica‐
742 tion Options section for further information.
743 loopstats
745 Enables recording of loop filter statistics information.
746 Each update of the local clock outputs a line of the fol‐
747 lowing form to the file generation set named loopstats:
748 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
749 The first two fields show the date (Modified Julian Day)
751 and time (seconds and fraction past UTC midnight). The
752 next five fields show time offset (seconds), frequency
753 offset (parts per million - PPM), RMS jitter (seconds),
754 Allan deviation (PPM) and clock discipline time constant.
755 peerstats
757 Enables recording of peer statistics information. This
758 includes statistics records of all peers of a NTP server
759 and of special signals, where present and configured.
760 Each valid update appends a line of the following form to
761 the current element of a file generation set named peer‐
762 stats:
763 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
764 The first two fields show the date (Modified Julian Day)
766 and time (seconds and fraction past UTC midnight). The
767 next two fields show the peer address in dotted-quad
768 notation and status, respectively. The status field is
769 encoded in hex in the format described in Appendix A of
770 the NTP specification RFC 1305. The final four fields
771 show the offset, delay, dispersion and RMS jitter, all in
772 seconds.
773 rawstats
775 Enables recording of raw-timestamp statistics informa‐
776 tion. This includes statistics records of all peers of a
777 NTP server and of special signals, where present and con‐
778 figured. Each NTP message received from a peer or clock
779 driver appends a line of the following form to the file
780 generation set named rawstats:
781 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
782 The first two fields show the date (Modified Julian Day)
784 and time (seconds and fraction past UTC midnight). The
785 next two fields show the remote peer or clock address
786 followed by the local address in dotted-quad notation.
787 The final four fields show the originate, receive, trans‐
788 mit and final NTP timestamps in order. The timestamp
789 values are as received and before processing by the vari‐
790 ous data smoothing and mitigation algorithms.
791 sysstats
793 Enables recording of ntpd statistics counters on a peri‐
794 odic basis. Each hour a line of the following form is
795 appended to the file generation set named sysstats:
796 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
797 The first two fields show the date (Modified Julian Day)
799 and time (seconds and fraction past UTC midnight). The
800 remaining ten fields show the statistics counter values
801 accumulated since the last generated line.
802 Time since restart 36000
804 Time in hours since the system was last rebooted.
805 Packets received 81965
807 Total number of packets received.
808 Packets processed 0
810 Number of packets received in response to previous
811 packets sent
812 Current version 9546
814 Number of packets matching the current NTP ver‐
815 sion.
816 Previous version 56
818 Number of packets matching the previous NTP ver‐
819 sion.
820 Bad version 71793
822 Number of packets matching neither NTP version.
823 Access denied 512
825 Number of packets denied access for any reason.
826 Bad length or format 540
828 Number of packets with invalid length, format or
829 port number.
830 Bad authentication 10
832 Number of packets not verified as authentic.
833 Rate exceeded 147
835 Number of packets discarded due to rate limita‐
836 tion.
837 statsdir directory_path
839 Indicates the full path of a directory where statistics
840 files should be created (see below). This keyword allows
841 the (otherwise constant) filegen filename prefix to be
842 modified for file generation sets, which is useful for
843 handling statistics logs.
844 filegen name [file filename] [type typename] [link | nolink]
846 [enable | disable]
847 Configures setting of generation file set name. Genera‐
848 tion file sets provide a means for handling files that
849 are continuously growing during the lifetime of a server.
850 Server statistics are a typical example for such files.
851 Generation file sets provide access to a set of files
852 used to store the actual data. At any time at most one
853 element of the set is being written to. The type given
854 specifies when and how data will be directed to a new
855 element of the set. This way, information stored in ele‐
856 ments of a file set that are currently unused are avail‐
857 able for administrational operations without the risk of
858 disturbing the operation of ntpd. (Most important: they
859 can be removed to free space for new data produced.)
860 Note that this command can be sent from the ntpdc(8) pro‐
862 gram running at a remote location.
863 name This is the type of the statistics records, as
865 shown in the statistics command.
866 file filename
868 This is the file name for the statistics records.
869 Filenames of set members are built from three con‐
870 catenated elements prefix, filename and suffix:
871 prefix This is a constant filename path. It is
873 not subject to modifications via the file‐
874 gen option. It is defined by the server,
875 usually specified as a compile-time con‐
876 stant. It may, however, be configurable
877 for individual file generation sets via
878 other commands. For example, the prefix
879 used with loopstats and peerstats genera‐
880 tion can be configured using the statsdir
881 option explained above.
882 filename
884 This string is directly concatenated to the
885 prefix mentioned above (no intervening
886 ‘/’). This can be modified using the file
887 argument to the filegen statement. No ..
888 elements are allowed in this component to
889 prevent filenames referring to parts out‐
890 side the filesystem hierarchy denoted by
891 prefix.
892 suffix This part is reflects individual elements
894 of a file set. It is generated according
895 to the type of a file set.
896 type typename
898 A file generation set is characterized by its
899 type. The following types are supported:
900 none The file set is actually a single plain
902 file.
903 pid One element of file set is used per incar‐
905 nation of a ntpd server. This type does
906 not perform any changes to file set members
907 during runtime, however it provides an easy
908 way of separating files belonging to dif‐
909 ferent ntpd(8) server incarnations. The
910 set member filename is built by appending a
911 ‘.’ to concatenated prefix and filename
912 strings, and appending the decimal repre‐
913 sentation of the process ID of the ntpd(8)
914 server process.
915 day One file generation set element is created
917 per day. A day is defined as the period
918 between 00:00 and 24:00 UTC. The file set
919 member suffix consists of a ‘.’ and a day
920 specification in the form YYYYMMdd. YYYY
921 is a 4-digit year number (e.g., 1992). MM
922 is a two digit month number. dd is a two
923 digit day number. Thus, all information
924 written at 10 December 1992 would end up in
925 a file named prefix filename.19921210.
926 week Any file set member contains data related
928 to a certain week of a year. The term week
929 is defined by computing day-of-year modulo
930 7. Elements of such a file generation set
931 are distinguished by appending the follow‐
932 ing suffix to the file set filename base: A
933 dot, a 4-digit year number, the letter W,
934 and a 2-digit week number. For example,
935 information from January, 10th 1992 would
936 end up in a file with suffix
937 month One generation file set element is gener‐
939 ated per month. The file name suffix con‐
940 sists of a dot, a 4-digit year number, and
941 a 2-digit month.
942 year One generation file element is generated
944 per year. The filename suffix consists of
945 a dot and a 4 digit year number.
946 age This type of file generation sets changes
948 to a new element of the file set every 24
949 hours of server operation. The filename
950 suffix consists of a dot, the letter a, and
951 an 8-digit number. This number is taken to
952 be the number of seconds the server is run‐
953 ning at the start of the corresponding
954 24-hour period. Information is only writ‐
955 ten to a file generation by specifying
956 enable; output is prevented by specifying
957 disable.
958 link | nolink
960 It is convenient to be able to access the current
961 element of a file generation set by a fixed name.
962 This feature is enabled by specifying link and
963 disabled using nolink. If link is specified, a
964 hard link from the current file set element to a
965 file without suffix is created. When there is
966 already a file with this name and the number of
967 links of this file is one, it is renamed appending
968 a dot, the letter C, and the pid of the ntpd(8)
969 server process. When the number of links is
970 greater than one, the file is unlinked. This
971 allows the current file to be accessed by a con‐
972 stant name.
973 enable | disable
975 Enables or disables the recording function.
976
978 The ntpd(8) daemon implements a general purpose address/mask based
979 restriction list. The list contains address/match entries sorted first
980 by increasing address values and and then by increasing mask values. A
981 match occurs when the bitwise AND of the mask and the packet source
982 address is equal to the bitwise AND of the mask and address in the
983 list. The list is searched in order with the last match found defining
984 the restriction flags associated with the entry. Additional informa‐
985 tion and examples can be found in the "Notes on Configuring NTP and
986 Setting up a NTP Subnet" page (available as part of the HTML documenta‐
987 tion provided in /usr/share/doc/ntp).
988 The restriction facility was implemented in conformance with the access
990 policies for the original NSFnet backbone time servers. Later the
991 facility was expanded to deflect cryptographic and clogging attacks.
992 While this facility may be useful for keeping unwanted or broken or
993 malicious clients from congesting innocent servers, it should not be
994 considered an alternative to the NTP authentication facilities. Source
995 address based restrictions are easily circumvented by a determined
996 cracker.
997 Clients can be denied service because they are explicitly included in
999 the restrict list created by the restrict command or implicitly as the
1000 result of cryptographic or rate limit violations. Cryptographic viola‐
1001 tions include certificate or identity verification failure; rate limit
1002 violations generally result from defective NTP implementations that
1003 send packets at abusive rates. Some violations cause denied service
1004 only for the offending packet, others cause denied service for a timed
1005 period and others cause the denied service for an indefinite period.
1006 When a client or network is denied access for an indefinite period, the
1007 only way at present to remove the restrictions is by restarting the
1008 server.
1009 The Kiss-of-Death Packet
1011 Ordinarily, packets denied service are simply dropped with no further
1012 action except incrementing statistics counters. Sometimes a more
1013 proactive response is needed, such as a server message that explicitly
1014 requests the client to stop sending and leave a message for the system
1015 operator. A special packet format has been created for this purpose
1016 called the "kiss-of-death" (KoD) packet. KoD packets have the leap
1017 bits set unsynchronized and stratum set to zero and the reference iden‐
1018 tifier field set to a four-byte ASCII code. If the noserve or notrust
1019 flag of the matching restrict list entry is set, the code is "DENY"; if
1020 the limited flag is set and the rate limit is exceeded, the code is
1021 "RATE". Finally, if a cryptographic violation occurs, the code is
1022 "CRYP".
1023 A client receiving a KoD performs a set of sanity checks to minimize
1025 security exposure, then updates the stratum and reference identifier
1026 peer variables, sets the access denied (TEST4) bit in the peer flash
1027 variable and sends a message to the log. As long as the TEST4 bit is
1028 set, the client will send no further packets to the server. The only
1029 way at present to recover from this condition is to restart the proto‐
1030 col at both the client and server. This happens automatically at the
1031 client when the association times out. It will happen at the server
1032 only if the server operator cooperates.
1033 Access Control Commands
1035 discard [average avg] [minimum min] [monitor prob]
1036 Set the parameters of the limited facility which protects the
1037 server from client abuse. The average subcommand specifies the
1038 minimum average packet spacing, while the minimum subcommand
1039 specifies the minimum packet spacing. Packets that violate
1040 these minima are discarded and a kiss-o'-death packet returned
1041 if enabled. The default minimum average and minimum are 5 and
1042 2, respectively. The monitor subcommand specifies the probabil‐
1043 ity of discard for packets that overflow the rate-control win‐
1044 dow.
1045 restrict address [mask mask] [ippeerlimit int] [flag ...]
1047 The address argument expressed in dotted-quad form is the
1048 address of a host or network. Alternatively, the address argu‐
1049 ment can be a valid host DNS name. The mask argument expressed
1050 in dotted-quad form defaults to 255.255.255.255, meaning that
1051 the address is treated as the address of an individual host. A
1052 default entry (address 0.0.0.0, mask 0.0.0.0) is always included
1053 and is always the first entry in the list. Note that text
1054 string default, with no mask option, may be used to indicate the
1055 default entry. The ippeerlimit directive limits the number of
1056 peer requests for each IP to int, where a value of -1 means
1057 "unlimited", the current default. A value of 0 means "none".
1058 There would usually be at most 1 peering request per IP, but if
1059 the remote peering requests are behind a proxy there could well
1060 be more than 1 per IP. In the current implementation, flag
1061 always restricts access, i.e., an entry with no flags indicates
1062 that free access to the server is to be given. The flags are
1063 not orthogonal, in that more restrictive flags will often make
1064 less restrictive ones redundant. The flags can generally be
1065 classed into two categories, those which restrict time service
1066 and those which restrict informational queries and attempts to
1067 do run-time reconfiguration of the server. One or more of the
1068 following flags may be specified:
1069 ignore Deny packets of all kinds, including ntpq(8) and ntpdc(8)
1071 queries.
1072 kod If this flag is set when an access violation occurs, a
1074 kiss-o'-death (KoD) packet is sent. KoD packets are rate
1075 limited to no more than one per second. If another KoD
1076 packet occurs within one second after the last one, the
1077 packet is dropped.
1078 limited
1080 Deny service if the packet spacing violates the lower
1081 limits specified in the discard command. A history of
1082 clients is kept using the monitoring capability of
1083 ntpd(8). Thus, monitoring is always active as long as
1084 there is a restriction entry with the limited flag.
1085 lowpriotrap
1087 Declare traps set by matching hosts to be low priority.
1088 The number of traps a server can maintain is limited (the
1089 current limit is 3). Traps are usually assigned on a
1090 first come, first served basis, with later trap
1091 requestors being denied service. This flag modifies the
1092 assignment algorithm by allowing low priority traps to be
1093 overridden by later requests for normal priority traps.
1094 noepeer
1096 Deny ephemeral peer requests, even if they come from an
1097 authenticated source. Note that the ability to use a
1098 symmetric key for authentication may be restricted to one
1099 or more IPs or subnets via the third field of the
1100 ntp.keys file. This restriction is not enabled by
1101 default, to maintain backward compatability. Expect
1102 noepeer to become the default in ntp-4.4.
1103 nomodify
1105 Deny ntpq(8) and ntpdc(8) queries which attempt to modify
1106 the state of the server (i.e., run time reconfiguration).
1107 Queries which return information are permitted.
1108 noquery
1110 Deny ntpq(8) and ntpdc(8) queries. Time service is not
1111 affected.
1112 nopeer Deny unauthenticated packets which would result in mobi‐
1114 lizing a new association. This includes broadcast and
1115 symmetric active packets when a configured association
1116 does not exist. It also includes pool associations, so
1117 if you want to use servers from a pool directive and also
1118 want to use nopeer by default, you'll want a restrict
1119 source ... line as well that does not include the nopeer
1120 directive.
1121 noserve
1123 Deny all packets except ntpq(8) and ntpdc(8) queries.
1124 notrap Decline to provide mode 6 control message trap service to
1126 matching hosts. The trap service is a subsystem of the
1127 ntpq(8) control message protocol which is intended for
1128 use by remote event logging programs.
1129 notrust
1131 Deny service unless the packet is cryptographically
1132 authenticated.
1133 ntpport
1135 This is actually a match algorithm modifier, rather than
1136 a restriction flag. Its presence causes the restriction
1137 entry to be matched only if the source port in the packet
1138 is the standard NTP UDP port (123). Both ntpport and
1139 non-ntpport may be specified. The ntpport is considered
1140 more specific and is sorted later in the list.
1141 version
1143 Deny packets that do not match the current NTP version.
1144 Default restriction list entries with the flags ignore, interface, ntp‐
1146 port, for each of the local host's interface addresses are inserted
1147 into the table at startup to prevent the server from attempting to syn‐
1148 chronize to its own time. A default entry is also always present,
1149 though if it is otherwise unconfigured; no flags are associated with
1150 the default entry (i.e., everything besides your own NTP server is
1151 unrestricted).
1152
1154 Manycasting
1155 Manycasting is a automatic discovery and configuration paradigm new to
1156 NTPv4. It is intended as a means for a multicast client to troll the
1157 nearby network neighborhood to find cooperating manycast servers, vali‐
1158 date them using cryptographic means and evaluate their time values with
1159 respect to other servers that might be lurking in the vicinity. The
1160 intended result is that each manycast client mobilizes client associa‐
1161 tions with some number of the "best" of the nearby manycast servers,
1162 yet automatically reconfigures to sustain this number of servers should
1163 one or another fail.
1164 Note that the manycasting paradigm does not coincide with the anycast
1166 paradigm described in RFC-1546, which is designed to find a single
1167 server from a clique of servers providing the same service. The many‐
1168 cast paradigm is designed to find a plurality of redundant servers sat‐
1169 isfying defined optimality criteria.
1170 Manycasting can be used with either symmetric key or public key cryp‐
1172 tography. The public key infrastructure (PKI) offers the best protec‐
1173 tion against compromised keys and is generally considered stronger, at
1174 least with relatively large key sizes. It is implemented using the
1175 Autokey protocol and the OpenSSL cryptographic library available from
1176 http://www.openssl.org/. The library can also be used with other NTPv4
1177 modes as well and is highly recommended, especially for broadcast
1178 modes.
1179 A persistent manycast client association is configured using the many‐
1181 castclient command, which is similar to the server command but with a
1182 multicast (IPv4 class D or IPv6 prefix FF) group address. The IANA has
1183 designated IPv4 address 224.1.1.1 and IPv6 address FF05::101 (site
1184 local) for NTP. When more servers are needed, it broadcasts manycast
1185 client messages to this address at the minimum feasible rate and mini‐
1186 mum feasible time-to-live (TTL) hops, depending on how many servers
1187 have already been found. There can be as many manycast client associa‐
1188 tions as different group address, each one serving as a template for a
1189 future ephemeral unicast client/server association.
1190 Manycast servers configured with the manycastserver command listen on
1192 the specified group address for manycast client messages. Note the
1193 distinction between manycast client, which actively broadcasts mes‐
1194 sages, and manycast server, which passively responds to them. If a
1195 manycast server is in scope of the current TTL and is itself synchro‐
1196 nized to a valid source and operating at a stratum level equal to or
1197 lower than the manycast client, it replies to the manycast client mes‐
1198 sage with an ordinary unicast server message.
1199 The manycast client receiving this message mobilizes an ephemeral
1201 client/server association according to the matching manycast client
1202 template, but only if cryptographically authenticated and the server
1203 stratum is less than or equal to the client stratum. Authentication is
1204 explicitly required and either symmetric key or public key (Autokey)
1205 can be used. Then, the client polls the server at its unicast address
1206 in burst mode in order to reliably set the host clock and validate the
1207 source. This normally results in a volley of eight client/server at
1208 2-s intervals during which both the synchronization and cryptographic
1209 protocols run concurrently. Following the volley, the client runs the
1210 NTP intersection and clustering algorithms, which act to discard all
1211 but the "best" associations according to stratum and synchronization
1212 distance. The surviving associations then continue in ordinary
1213 client/server mode.
1214 The manycast client polling strategy is designed to reduce as much as
1216 possible the volume of manycast client messages and the effects of
1217 implosion due to near-simultaneous arrival of manycast server messages.
1218 The strategy is determined by the manycastclient, tos and ttl configu‐
1219 ration commands. The manycast poll interval is normally eight times
1220 the system poll interval, which starts out at the minpoll value speci‐
1221 fied in the manycastclient, command and, under normal circumstances,
1222 increments to the maxpolll value specified in this command. Initially,
1223 the TTL is set at the minimum hops specified by the ttl command. At
1224 each retransmission the TTL is increased until reaching the maximum
1225 hops specified by this command or a sufficient number client associa‐
1226 tions have been found. Further retransmissions use the same TTL.
1227 The quality and reliability of the suite of associations discovered by
1229 the manycast client is determined by the NTP mitigation algorithms and
1230 the minclock and minsane values specified in the tos configuration com‐
1231 mand. At least minsane candidate servers must be available and the
1232 mitigation algorithms produce at least minclock survivors in order to
1233 synchronize the clock. Byzantine agreement principles require at least
1234 four candidates in order to correctly discard a single falseticker.
1235 For legacy purposes, minsane defaults to 1 and minclock defaults to 3.
1236 For manycast service minsane should be explicitly set to 4, assuming at
1237 least that number of servers are available.
1238 If at least minclock servers are found, the manycast poll interval is
1240 immediately set to eight times maxpoll. If less than minclock servers
1241 are found when the TTL has reached the maximum hops, the manycast poll
1242 interval is doubled. For each transmission after that, the poll inter‐
1243 val is doubled again until reaching the maximum of eight times maxpoll.
1244 Further transmissions use the same poll interval and TTL values. Note
1245 that while all this is going on, each client/server association found
1246 is operating normally it the system poll interval.
1247 Administratively scoped multicast boundaries are normally specified by
1249 the network router configuration and, in the case of IPv6, the
1250 link/site scope prefix. By default, the increment for TTL hops is 32
1251 starting from 31; however, the ttl configuration command can be used to
1252 modify the values to match the scope rules.
1253 It is often useful to narrow the range of acceptable servers which can
1255 be found by manycast client associations. Because manycast servers
1256 respond only when the client stratum is equal to or greater than the
1257 server stratum, primary (stratum 1) servers fill find only primary
1258 servers in TTL range, which is probably the most common objective.
1259 However, unless configured otherwise, all manycast clients in TTL range
1260 will eventually find all primary servers in TTL range, which is proba‐
1261 bly not the most common objective in large networks. The tos command
1262 can be used to modify this behavior. Servers with stratum below floor
1263 or above ceiling specified in the tos command are strongly discouraged
1264 during the selection process; however, these servers may be temporally
1265 accepted if the number of servers within TTL range is less than min‐
1266 clock.
1267 The above actions occur for each manycast client message, which repeats
1269 at the designated poll interval. However, once the ephemeral client
1270 association is mobilized, subsequent manycast server replies are dis‐
1271 carded, since that would result in a duplicate association. If during
1272 a poll interval the number of client associations falls below minclock,
1273 all manycast client prototype associations are reset to the initial
1274 poll interval and TTL hops and operation resumes from the beginning.
1275 It is important to avoid frequent manycast client messages, since each
1276 one requires all manycast servers in TTL range to respond. The result
1277 could well be an implosion, either minor or major, depending on the
1278 number of servers in range. The recommended value for maxpoll is 12
1279 (4,096 s).
1280 It is possible and frequently useful to configure a host as both many‐
1282 cast client and manycast server. A number of hosts configured this way
1283 and sharing a common group address will automatically organize them‐
1284 selves in an optimum configuration based on stratum and synchronization
1285 distance. For example, consider an NTP subnet of two primary servers
1286 and a hundred or more dependent clients. With two exceptions, all
1287 servers and clients have identical configuration files including both
1288 multicastclient and multicastserver commands using, for instance, mul‐
1289 ticast group address 239.1.1.1. The only exception is that each pri‐
1290 mary server configuration file must include commands for the primary
1291 reference source such as a GPS receiver.
1292 The remaining configuration files for all secondary servers and clients
1294 have the same contents, except for the tos command, which is specific
1295 for each stratum level. For stratum 1 and stratum 2 servers, that com‐
1296 mand is not necessary. For stratum 3 and above servers the floor value
1297 is set to the intended stratum number. Thus, all stratum 3 configura‐
1298 tion files are identical, all stratum 4 files are identical and so
1299 forth.
1300 Once operations have stabilized in this scenario, the primary servers
1302 will find the primary reference source and each other, since they both
1303 operate at the same stratum (1), but not with any secondary server or
1304 client, since these operate at a higher stratum. The secondary servers
1305 will find the servers at the same stratum level. If one of the primary
1306 servers loses its GPS receiver, it will continue to operate as a client
1307 and other clients will time out the corresponding association and re-
1308 associate accordingly.
1309 Some administrators prefer to avoid running ntpd(8) continuously and
1311 run either sntp(8) or ntpd(8) -q as a cron job. In either case the
1312 servers must be configured in advance and the program fails if none are
1313 available when the cron job runs. A really slick application of many‐
1314 cast is with ntpd(8) -q. The program wakes up, scans the local land‐
1315 scape looking for the usual suspects, selects the best from among the
1316 rascals, sets the clock and then departs. Servers do not have to be
1317 configured in advance and all clients throughout the network can have
1318 the same configuration file.
1319 Manycast Interactions with Autokey
1321 Each time a manycast client sends a client mode packet to a multicast
1322 group address, all manycast servers in scope generate a reply including
1323 the host name and status word. The manycast clients then run the
1324 Autokey protocol, which collects and verifies all certificates
1325 involved. Following the burst interval all but three survivors are
1326 cast off, but the certificates remain in the local cache. It often
1327 happens that several complete signing trails from the client to the
1328 primary servers are collected in this way.
1329 About once an hour or less often if the poll interval exceeds this, the
1331 client regenerates the Autokey key list. This is in general transpar‐
1332 ent in client/server mode. However, about once per day the server pri‐
1333 vate value used to generate cookies is refreshed along with all many‐
1334 cast client associations. In this case all cryptographic values
1335 including certificates is refreshed. If a new certificate has been
1336 generated since the last refresh epoch, it will automatically revoke
1337 all prior certificates that happen to be in the certificate cache. At
1338 the same time, the manycast scheme starts all over from the beginning
1339 and the expanding ring shrinks to the minimum and increments from there
1340 while collecting all servers in scope.
1341 Broadcast Options
1343 tos [bcpollbstep gate]
1344 This command provides a way to delay, by the specified number of
1345 broadcast poll intervals, believing backward time steps from a
1346 broadcast server. Broadcast time networks are expected to be
1347 trusted. In the event a broadcast server's time is stepped
1348 backwards, there is clear benefit to having the clients notice
1349 this change as soon as possible. Attacks such as replay attacks
1350 can happen, however, and even though there are a number of pro‐
1351 tections built in to broadcast mode, attempts to perform a
1352 replay attack are possible. This value defaults to 0, but can
1353 be changed to any number of poll intervals between 0 and 4.
1354 Manycast Options
1356 tos [ceiling ceiling | cohort { 0 | 1 } | floor floor | minclock min‐
1357 clock | minsane minsane]
1358 This command affects the clock selection and clustering algo‐
1359 rithms. It can be used to select the quality and quantity of
1360 peers used to synchronize the system clock and is most useful in
1361 manycast mode. The variables operate as follows:
1362 ceiling ceiling
1364 Peers with strata above ceiling will be discarded if
1365 there are at least minclock peers remaining. This value
1366 defaults to 15, but can be changed to any number from 1
1367 to 15.
1368 cohort {0 | 1 }
1370 This is a binary flag which enables (0) or disables (1)
1371 manycast server replies to manycast clients with the same
1372 stratum level. This is useful to reduce implosions where
1373 large numbers of clients with the same stratum level are
1374 present. The default is to enable these replies.
1375 floor floor
1377 Peers with strata below floor will be discarded if there
1378 are at least minclock peers remaining. This value
1379 defaults to 1, but can be changed to any number from 1 to
1380 15.
1381 minclock minclock
1383 The clustering algorithm repeatedly casts out outlier
1384 associations until no more than minclock associations
1385 remain. This value defaults to 3, but can be changed to
1386 any number from 1 to the number of configured sources.
1387 minsane minsane
1389 This is the minimum number of candidates available to the
1390 clock selection algorithm in order to produce one or more
1391 truechimers for the clustering algorithm. If fewer than
1392 this number are available, the clock is undisciplined and
1393 allowed to run free. The default is 1 for legacy pur‐
1394 poses. However, according to principles of Byzantine
1395 agreement, minsane should be at least 4 in order to
1396 detect and discard a single falseticker.
1397 ttl hop ...
1399 This command specifies a list of TTL values in increasing order,
1400 up to 8 values can be specified. In manycast mode these values
1401 are used in turn in an expanding-ring search. The default is
1402 eight multiples of 32 starting at 31.
1403
1405 The NTP Version 4 daemon supports some three dozen different radio,
1406 satellite and modem reference clocks plus a special pseudo-clock used
1407 for backup or when no other clock source is available. Detailed
1408 descriptions of individual device drivers and options can be found in
1409 the "Reference Clock Drivers" page (available as part of the HTML docu‐
1410 mentation provided in /usr/share/doc/ntp). Additional information can
1411 be found in the pages linked there, including the "Debugging Hints for
1412 Reference Clock Drivers" and "How To Write a Reference Clock Driver"
1413 pages (available as part of the HTML documentation provided in
1414 /usr/share/doc/ntp). In addition, support for a PPS signal is avail‐
1415 able as described in the "Pulse-per-second (PPS) Signal Interfacing"
1416 page (available as part of the HTML documentation provided in
1417 /usr/share/doc/ntp). Many drivers support special line disci‐
1418 pline/streams modules which can significantly improve the accuracy
1419 using the driver. These are described in the "Line Disciplines and
1420 Streams Drivers" page (available as part of the HTML documentation pro‐
1421 vided in /usr/share/doc/ntp).
1422 A reference clock will generally (though not always) be a radio time‐
1424 code receiver which is synchronized to a source of standard time such
1425 as the services offered by the NRC in Canada and NIST and USNO in the
1426 US. The interface between the computer and the timecode receiver is
1427 device dependent, but is usually a serial port. A device driver spe‐
1428 cific to each reference clock must be selected and compiled in the dis‐
1429 tribution; however, most common radio, satellite and modem clocks are
1430 included by default. Note that an attempt to configure a reference
1431 clock when the driver has not been compiled or the hardware port has
1432 not been appropriately configured results in a scalding remark to the
1433 system log file, but is otherwise non hazardous.
1434 For the purposes of configuration, ntpd(8) treats reference clocks in a
1436 manner analogous to normal NTP peers as much as possible. Reference
1437 clocks are identified by a syntactically correct but invalid IP
1438 address, in order to distinguish them from normal NTP peers. Reference
1439 clock addresses are of the form 127.127.t.u, where t is an integer
1440 denoting the clock type and u indicates the unit number in the range
1441 0-3. While it may seem overkill, it is in fact sometimes useful to
1442 configure multiple reference clocks of the same type, in which case the
1443 unit numbers must be unique.
1444 The server command is used to configure a reference clock, where the
1446 address argument in that command is the clock address. The key, ver‐
1447 sion and ttl options are not used for reference clock support. The
1448 mode option is added for reference clock support, as described below.
1449 The prefer option can be useful to persuade the server to cherish a
1450 reference clock with somewhat more enthusiasm than other reference
1451 clocks or peers. Further information on this option can be found in
1452 the "Mitigation Rules and the prefer Keyword" (available as part of the
1453 HTML documentation provided in /usr/share/doc/ntp) page. The minpoll
1454 and maxpoll options have meaning only for selected clock drivers. See
1455 the individual clock driver document pages for additional information.
1456 The fudge command is used to provide additional information for indi‐
1458 vidual clock drivers and normally follows immediately after the server
1459 command. The address argument specifies the clock address. The refid
1460 and stratum options can be used to override the defaults for the
1461 device. There are two optional device-dependent time offsets and four
1462 flags that can be included in the fudge command as well.
1463 The stratum number of a reference clock is by default zero. Since the
1465 ntpd(8) daemon adds one to the stratum of each peer, a primary server
1466 ordinarily displays an external stratum of one. In order to provide
1467 engineered backups, it is often useful to specify the reference clock
1468 stratum as greater than zero. The stratum option is used for this pur‐
1469 pose. Also, in cases involving both a reference clock and a pulse-per-
1470 second (PPS) discipline signal, it is useful to specify the reference
1471 clock identifier as other than the default, depending on the driver.
1472 The refid option is used for this purpose. Except where noted, these
1473 options apply to all clock drivers.
1474 Reference Clock Commands
1476 server 127.127.t.u [prefer] [mode int] [minpoll int] [maxpoll int]
1477 This command can be used to configure reference clocks in spe‐
1478 cial ways. The options are interpreted as follows:
1479 prefer Marks the reference clock as preferred. All other things
1481 being equal, this host will be chosen for synchronization
1482 among a set of correctly operating hosts. See the "Miti‐
1483 gation Rules and the prefer Keyword" page (available as
1484 part of the HTML documentation provided in
1485 /usr/share/doc/ntp) for further information.
1486 mode int
1488 Specifies a mode number which is interpreted in a device-
1489 specific fashion. For instance, it selects a dialing
1490 protocol in the ACTS driver and a device subtype in the
1491 parse drivers.
1492 minpoll int
1494 maxpoll int
1496 These options specify the minimum and maximum polling
1497 interval for reference clock messages, as a power of 2 in
1498 seconds For most directly connected reference clocks,
1499 both minpoll and maxpoll default to 6 (64 s). For modem
1500 reference clocks, minpoll defaults to 10 (17.1 m) and
1501 maxpoll defaults to 14 (4.5 h). The allowable range is 4
1502 (16 s) to 17 (36.4 h) inclusive.
1503 fudge 127.127.t.u [time1 sec] [time2 sec] [stratum int] [refid string]
1505 [mode int] [flag1 0 | 1] [flag2 0 | 1] [flag3 0 | 1] [flag4 0 | 1]
1506 This command can be used to configure reference clocks in spe‐
1507 cial ways. It must immediately follow the server command which
1508 configures the driver. Note that the same capability is possi‐
1509 ble at run time using the ntpdc(8) program. The options are
1510 interpreted as follows:
1511 time1 sec
1513 Specifies a constant to be added to the time offset pro‐
1514 duced by the driver, a fixed-point decimal number in sec‐
1515 onds. This is used as a calibration constant to adjust
1516 the nominal time offset of a particular clock to agree
1517 with an external standard, such as a precision PPS sig‐
1518 nal. It also provides a way to correct a systematic
1519 error or bias due to serial port or operating system
1520 latencies, different cable lengths or receiver internal
1521 delay. The specified offset is in addition to the propa‐
1522 gation delay provided by other means, such as internal
1523 DIPswitches. Where a calibration for an individual sys‐
1524 tem and driver is available, an approximate correction is
1525 noted in the driver documentation pages. Note: in order
1526 to facilitate calibration when more than one radio clock
1527 or PPS signal is supported, a special calibration feature
1528 is available. It takes the form of an argument to the
1529 enable command described in Miscellaneous Options page
1530 and operates as described in the "Reference Clock Driv‐
1531 ers" page (available as part of the HTML documentation
1532 provided in /usr/share/doc/ntp).
1533 time2 secs
1535 Specifies a fixed-point decimal number in seconds, which
1536 is interpreted in a driver-dependent way. See the
1537 descriptions of specific drivers in the "Reference Clock
1538 Drivers" page (available as part of the HTML documenta‐
1539 tion provided in /usr/share/doc/ntp ).
1540 stratum int
1542 Specifies the stratum number assigned to the driver, an
1543 integer between 0 and 15. This number overrides the
1544 default stratum number ordinarily assigned by the driver
1545 itself, usually zero.
1546 refid string
1548 Specifies an ASCII string of from one to four characters
1549 which defines the reference identifier used by the
1550 driver. This string overrides the default identifier
1551 ordinarily assigned by the driver itself.
1552 mode int
1554 Specifies a mode number which is interpreted in a device-
1555 specific fashion. For instance, it selects a dialing
1556 protocol in the ACTS driver and a device subtype in the
1557 parse drivers.
1558 flag1 0 | 1
1560 flag2 0 | 1
1562 flag3 0 | 1
1564 flag4 0 | 1
1566 These four flags are used for customizing the clock
1567 driver. The interpretation of these values, and whether
1568 they are used at all, is a function of the particular
1569 clock driver. However, by convention flag4 is used to
1570 enable recording monitoring data to the clockstats file
1571 configured with the filegen command. Further information
1572 on the filegen command can be found in Monitoring
1573 Options.
1574
1576 broadcastdelay seconds
1577 The broadcast and multicast modes require a special calibration
1578 to determine the network delay between the local and remote
1579 servers. Ordinarily, this is done automatically by the initial
1580 protocol exchanges between the client and server. In some
1581 cases, the calibration procedure may fail due to network or
1582 server access controls, for example. This command specifies the
1583 default delay to be used under these circumstances. Typically
1584 (for Ethernet), a number between 0.003 and 0.007 seconds is
1585 appropriate. The default when this command is not used is 0.004
1586 seconds.
1587 calldelay delay
1589 This option controls the delay in seconds between the first and
1590 second packets sent in burst or iburst mode to allow additional
1591 time for a modem or ISDN call to complete.
1592 driftfile driftfile
1594 This command specifies the complete path and name of the file
1595 used to record the frequency of the local clock oscillator.
1596 This is the same operation as the -f command line option. If
1597 the file exists, it is read at startup in order to set the ini‐
1598 tial frequency and then updated once per hour with the current
1599 frequency computed by the daemon. If the file name is speci‐
1600 fied, but the file itself does not exist, the starts with an
1601 initial frequency of zero and creates the file when writing it
1602 for the first time. If this command is not given, the daemon
1603 will always start with an initial frequency of zero.
1604 The file format consists of a single line containing a single
1606 floating point number, which records the frequency offset mea‐
1607 sured in parts-per-million (PPM). The file is updated by first
1608 writing the current drift value into a temporary file and then
1609 renaming this file to replace the old version. This implies
1610 that ntpd(8) must have write permission for the directory the
1611 drift file is located in, and that file system links, symbolic
1612 or otherwise, should be avoided.
1613 dscp value
1615 This option specifies the Differentiated Services Control Point
1616 (DSCP) value, a 6-bit code. The default value is 46, signifying
1617 Expedited Forwarding.
1618 enable [auth | bclient | calibrate | kernel | mode7 | monitor | ntp |
1620 stats | peer_clear_digest_early | unpeer_crypto_early |
1621 unpeer_crypto_nak_early | unpeer_digest_early]
1622 disable [auth | bclient | calibrate | kernel | mode7 | monitor | ntp |
1624 stats | peer_clear_digest_early | unpeer_crypto_early |
1625 unpeer_crypto_nak_early | unpeer_digest_early]
1626 Provides a way to enable or disable various server options.
1627 Flags not mentioned are unaffected. Note that all of these
1628 flags can be controlled remotely using the ntpdc(8) utility pro‐
1629 gram.
1630 auth Enables the server to synchronize with unconfigured peers
1632 only if the peer has been correctly authenticated using
1633 either public key or private key cryptography. The
1634 default for this flag is enable.
1635 bclient
1637 Enables the server to listen for a message from a broad‐
1638 cast or multicast server, as in the multicastclient com‐
1639 mand with default address. The default for this flag is
1640 disable.
1641 calibrate
1643 Enables the calibrate feature for reference clocks. The
1644 default for this flag is disable.
1645 kernel Enables the kernel time discipline, if available. The
1647 default for this flag is enable if support is available,
1648 otherwise disable.
1649 mode7 Enables processing of NTP mode 7 implementation-specific
1651 requests which are used by the deprecated ntpdc(8) pro‐
1652 gram. The default for this flag is disable. This flag
1653 is excluded from runtime configuration using ntpq(8).
1654 The ntpq(8) program provides the same capabilities as
1655 ntpdc(8) using standard mode 6 requests.
1656 monitor
1658 Enables the monitoring facility. See the ntpdc(8) pro‐
1659 gram and the monlist command or further information. The
1660 default for this flag is enable.
1661 ntp Enables time and frequency discipline. In effect, this
1663 switch opens and closes the feedback loop, which is use‐
1664 ful for testing. The default for this flag is enable.
1665 peer_clear_digest_early
1667 By default, if ntpd(8) is using autokey and it receives a
1668 crypto-NAK packet that passes the duplicate packet and
1669 origin timestamp checks the peer variables are immedi‐
1670 ately cleared. While this is generally a feature as it
1671 allows for quick recovery if a server key has changed, a
1672 properly forged and appropriately delivered crypto-NAK
1673 packet can be used in a DoS attack. If you have active
1674 noticable problems with this type of DoS attack then you
1675 should consider disabling this option. You can check
1676 your peerstats file for evidence of any of these attacks.
1677 The default for this flag is enable.
1678 stats Enables the statistics facility. See the Monitoring
1680 Options section for further information. The default for
1681 this flag is disable.
1682 unpeer_crypto_early
1684 By default, if ntpd(8) receives an autokey packet that
1685 fails TEST9, a crypto failure, the association is immedi‐
1686 ately cleared. This is almost certainly a feature, but
1687 if, in spite of the current recommendation of not using
1688 autokey, you are still using autokey and you are seeing
1689 this sort of DoS attack disabling this flag will delay
1690 tearing down the association until the reachability
1691 counter becomes zero. You can check your peerstats file
1692 for evidence of any of these attacks. The default for
1693 this flag is enable.
1694 unpeer_crypto_nak_early
1696 By default, if ntpd(8) receives a crypto-NAK packet that
1697 passes the duplicate packet and origin timestamp checks
1698 the association is immediately cleared. While this is
1699 generally a feature as it allows for quick recovery if a
1700 server key has changed, a properly forged and appropri‐
1701 ately delivered crypto-NAK packet can be used in a DoS
1702 attack. If you have active noticable problems with this
1703 type of DoS attack then you should consider disabling
1704 this option. You can check your peerstats file for evi‐
1705 dence of any of these attacks. The default for this flag
1706 is enable.
1707 unpeer_digest_early
1709 By default, if ntpd(8) receives what should be an authen‐
1710 ticated packet that passes other packet sanity checks but
1711 contains an invalid digest the association is immediately
1712 cleared. While this is generally a feature as it allows
1713 for quick recovery, if this type of packet is carefully
1714 forged and sent during an appropriate window it can be
1715 used for a DoS attack. If you have active noticable
1716 problems with this type of DoS attack then you should
1717 consider disabling this option. You can check your peer‐
1718 stats file for evidence of any of these attacks. The
1719 default for this flag is enable.
1720 includefile includefile
1722 This command allows additional configuration commands to be
1723 included from a separate file. Include files may be nested to a
1724 depth of five; upon reaching the end of any include file, com‐
1725 mand processing resumes in the previous configuration file.
1726 This option is useful for sites that run ntpd(8) on multiple
1727 hosts, with (mostly) common options (e.g., a restriction list).
1728 interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard name |
1730 address [/ prefixlen]]
1731 The interface directive controls which network addresses ntpd(8)
1732 opens, and whether input is dropped without processing. The
1733 first parameter determines the action for addresses which match
1734 the second parameter. The second parameter specifies a class of
1735 addresses, or a specific interface name, or an address. In the
1736 address case, prefixlen determines how many bits must match for
1737 this rule to apply. ignore prevents opening matching addresses,
1738 drop causes ntpd(8) to open the address and drop all received
1739 packets without examination. Multiple interface directives can
1740 be used. The last rule which matches a particular address
1741 determines the action for it. interface directives are disabled
1742 if any -I, --interface, -L, or --novirtualips command-line
1743 options are specified in the configuration file, all available
1744 network addresses are opened. The nic directive is an alias for
1745 interface.
1746 leapfile leapfile
1748 This command loads the IERS leapseconds file and initializes the
1749 leapsecond values for the next leapsecond event, leapfile expi‐
1750 ration time, and TAI offset. The file can be obtained directly
1751 from the IERS at https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-
1752 seconds.list or ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-
1753 seconds.list. The leapfile is scanned when ntpd(8) processes
1754 the leapfile directive or when ntpd detects that the leapfile
1755 has changed. ntpd checks once a day to see if the leapfile has
1756 changed. The update-leap(1update_leapmdoc) script can be run to
1757 see if the leapfile should be updated.
1758 leapsmearinterval seconds
1760 This EXPERIMENTAL option is only available if ntpd(8) was built
1761 with the --enable-leap-smear option to the configure script. It
1762 specifies the interval over which a leap second correction will
1763 be applied. Recommended values for this option are between 7200
1764 (2 hours) and 86400 (24 hours). See http://bugs.ntp.org/2855
1765 for more information.
1766 logconfig configkeyword
1768 This command controls the amount and type of output written to
1769 the system syslog(3) facility or the alternate logfile log file.
1770 By default, all output is turned on. All configkeyword keywords
1771 can be prefixed with ‘=’, ‘+’ and ‘-’, where ‘=’ sets the sys‐
1772 log(3) priority mask, ‘+’ adds and ‘-’ removes messages. sys‐
1773 log(3) messages can be controlled in four classes (clock, peer,
1774 sys and sync). Within these classes four types of messages can
1775 be controlled: informational messages (info), event messages
1776 (events), statistics messages (statistics) and status messages
1777 (status).
1778 Configuration keywords are formed by concatenating the message
1780 class with the event class. The all prefix can be used instead
1781 of a message class. A message class may also be followed by the
1782 all keyword to enable/disable all messages of the respective
1783 message class. Thus, a minimal log configuration could look
1784 like this:
1785 logconfig =syncstatus +sysevents
1786 This would just list the synchronizations state of ntpd(8) and
1788 the major system events. For a simple reference server, the
1789 following minimum message configuration could be useful:
1790 logconfig =syncall +clockall
1791 This configuration will list all clock information and synchro‐
1793 nization information. All other events and messages about
1794 peers, system events and so on is suppressed.
1795 logfile logfile
1797 This command specifies the location of an alternate log file to
1798 be used instead of the default system syslog(3) facility. This
1799 is the same operation as the -l command line option.
1800 mru [maxdepth count | maxmem kilobytes | mindepth count | maxage sec‐
1802 onds | initialloc count | initmem kilobytes | incalloc count | incmem
1803 kilobytes]
1804 Controls size limite of the monitoring facility's Most Recently
1805 Used (MRU) list of client addresses, which is also used by the
1806 rate control facility.
1807 maxdepth count
1809 maxmem kilobytes
1811 Equivalent upper limits on the size of the MRU list, in
1812 terms of entries or kilobytes. The acutal limit will be
1813 up to incalloc entries or incmem kilobytes larger. As
1814 with all of the mru options offered in units of entries
1815 or kilobytes, if both maxdepth and maxmem are used, the
1816 last one used controls. The default is 1024 kilobytes.
1817 mindepth count
1819 Lower limit on the MRU list size. When the MRU list has
1820 fewer than mindepth entries, existing entries are never
1821 removed to make room for newer ones, regardless of their
1822 age. The default is 600 entries.
1823 maxage seconds
1825 Once the MRU list has mindepth entries and an additional
1826 client is to ba added to the list, if the oldest entry
1827 was updated more than maxage seconds ago, that entry is
1828 removed and its storage is reused. If the oldest entry
1829 was updated more recently the MRU list is grown, subject
1830 to maxdepth / moxmem. The default is 64 seconds.
1831 initalloc count
1833 initmem kilobytes
1835 Initial memory allocation at the time the monitoringfa‐
1836 cility is first enabled, in terms of the number of
1837 entries or kilobytes. The default is 4 kilobytes.
1838 incalloc count
1840 incmem kilobytes
1842 Size of additional memory allocations when growing the
1843 MRU list, in entries or kilobytes. The default is 4
1844 kilobytes.
1845 nonvolatile threshold
1847 Specify the threshold delta in seconds before an hourly change
1848 to the driftfile (frequency file) will be written, with a
1849 default value of 1e-7 (0.1 PPM). The frequency file is
1850 inspected each hour. If the difference between the current fre‐
1851 quency and the last value written exceeds the threshold, the
1852 file is written and the threshold becomes the new threshold
1853 value. If the threshold is not exceeeded, it is reduced by
1854 half. This is intended to reduce the number of file writes for
1855 embedded systems with nonvolatile memory.
1856 phone dial ...
1858 This command is used in conjunction with the ACTS modem driver
1859 (type 18) or the JJY driver (type 40, mode 100 - 180). For the
1860 ACTS modem driver (type 18), the arguments consist of a maximum
1861 of 10 telephone numbers used to dial USNO, NIST, or European
1862 time service. For the JJY driver (type 40 mode 100 - 180), the
1863 argument is one telephone number used to dial the telephone JJY
1864 service. The Hayes command ATDT is normally prepended to the
1865 number. The number can contain other modem control codes as
1866 well.
1867 reset [allpeers] [auth] [ctl] [io] [mem] [sys] [timer]
1869 Reset one or more groups of counters maintained by ntpd and
1870 exposed by ntpq and ntpdc.
1871 rlimit [memlock Nmegabytes | stacksize N4kPages filenum Nfiledescrip‐
1873 tors]
1874 memlock Nmegabytes
1876 Specify the number of megabytes of memory that should be
1877 allocated and locked. Probably only available under
1878 Linux, this option may be useful when dropping root (the
1879 -i option). The default is 32 megabytes on non-Linux
1880 machines, and -1 under Linux. -1 means "do not lock the
1881 process into memory". 0 means "lock whatever memory the
1882 process wants into memory".
1883 stacksize N4kPages
1885 Specifies the maximum size of the process stack on sys‐
1886 tems with the mlockall() function. Defaults to 50 4k
1887 pages (200 4k pages in OpenBSD).
1888 filenum Nfiledescriptors
1890 Specifies the maximum number of file descriptors ntpd may
1891 have open at once. Defaults to the system default.
1892 saveconfigdir directory_path
1894 Specify the directory in which to write configuration snapshots
1895 requested with saveconfig command. If saveconfigdir does not
1896 appear in the configuration file, saveconfig requests are
1897 rejected by ntpd.
1898 saveconfig filename
1900 Write the current configuration, including any runtime modifica‐
1901 tions given with :config or config-from-file to the ntpd host's
1902 filename in the saveconfigdir. This command will be rejected
1903 unless the saveconfigdir directive appears in configuration
1904 file. filename can use strftime(3) format directives to substi‐
1905 tute the current date and time, for example, savecon‐
1906 fig ntp-%Y%m%d-%H%M%S.conf. The filename used is stored in the
1907 system variable savedconfig. Authentication is required.
1908 setvar variable [default]
1910 This command adds an additional system variable. These vari‐
1911 ables can be used to distribute additional information such as
1912 the access policy. If the variable of the form name=value is
1913 followed by the default keyword, the variable will be listed as
1914 part of the default system variables (ntpq(8) rv command)).
1915 These additional variables serve informational purposes only.
1916 They are not related to the protocol other that they can be
1917 listed. The known protocol variables will always override any
1918 variables defined via the setvar mechanism. There are three
1919 special variables that contain the names of all variable of the
1920 same group. The sys_var_list holds the names of all system
1921 variables. The peer_var_list holds the names of all peer vari‐
1922 ables and the clock_var_list holds the names of the reference
1923 clock variables.
1924 sysinfo
1926 Display operational summary.
1927 sysstats
1929 Show statistics counters maintained in the protocol module.
1930 tinker [allan allan | dispersion dispersion | freq freq | huffpuff
1932 huffpuff | panic panic | step step | stepback stepback | stepfwd
1933 stepfwd | stepout stepout]
1934 This command can be used to alter several system variables in
1935 very exceptional circumstances. It should occur in the configu‐
1936 ration file before any other configuration options. The default
1937 values of these variables have been carefully optimized for a
1938 wide range of network speeds and reliability expectations. In
1939 general, they interact in intricate ways that are hard to pre‐
1940 dict and some combinations can result in some very nasty behav‐
1941 ior. Very rarely is it necessary to change the default values;
1942 but, some folks cannot resist twisting the knobs anyway and this
1943 command is for them. Emphasis added: twisters are on their own
1944 and can expect no help from the support group.
1945 The variables operate as follows:
1947 allan allan
1949 The argument becomes the new value for the minimum Allan
1950 intercept, which is a parameter of the PLL/FLL clock dis‐
1951 cipline algorithm. The value in log2 seconds defaults to
1952 7 (1024 s), which is also the lower limit.
1953 dispersion dispersion
1955 The argument becomes the new value for the dispersion
1956 increase rate, normally .000015 s/s.
1957 freq freq
1959 The argument becomes the initial value of the frequency
1960 offset in parts-per-million. This overrides the value in
1961 the frequency file, if present, and avoids the initial
1962 training state if it is not.
1963 huffpuff huffpuff
1965 The argument becomes the new value for the experimental
1966 huff-n'-puff filter span, which determines the most
1967 recent interval the algorithm will search for a minimum
1968 delay. The lower limit is 900 s (15 m), but a more rea‐
1969 sonable value is 7200 (2 hours). There is no default,
1970 since the filter is not enabled unless this command is
1971 given.
1972 panic panic
1974 The argument is the panic threshold, normally 1000 s. If
1975 set to zero, the panic sanity check is disabled and a
1976 clock offset of any value will be accepted.
1977 step step
1979 The argument is the step threshold, which by default is
1980 0.128 s. It can be set to any positive number in sec‐
1981 onds. If set to zero, step adjustments will never occur.
1982 Note: The kernel time discipline is disabled if the step
1983 threshold is set to zero or greater than the default.
1984 stepback stepback
1986 The argument is the step threshold for the backward
1987 direction, which by default is 0.128 s. It can be set to
1988 any positive number in seconds. If both the forward and
1989 backward step thresholds are set to zero, step adjust‐
1990 ments will never occur. Note: The kernel time discipline
1991 is disabled if each direction of step threshold are
1992 either set to zero or greater than .5 second.
1993 stepfwd stepfwd
1995 As for stepback, but for the forward direction.
1996 stepout stepout
1998 The argument is the stepout timeout, which by default is
1999 900 s. It can be set to any positive number in seconds.
2000 If set to zero, the stepout pulses will not be sup‐
2001 pressed.
2002 writevar assocID name = value [,...]
2004 Write (create or update) the specified variables. If the asso‐
2005 cID is zero, the variablea re from the system variables name
2006 space, otherwise they are from the peer variables name space.
2007 The assocID is required, as the same name can occur in both name
2008 spaces.
2009 trap host_address [port port_number] [interface interface_address]
2011 This command configures a trap receiver at the given host
2012 address and port number for sending messages with the specified
2013 local interface address. If the port number is unspecified, a
2014 value of 18447 is used. If the interface address is not speci‐
2015 fied, the message is sent with a source address of the local
2016 interface the message is sent through. Note that on a multi‐
2017 homed host the interface used may vary from time to time with
2018 routing changes.
2019 ttl hop ...
2021 This command specifies a list of TTL values in increasing order.
2022 Up to 8 values can be specified. In manycast mode these values
2023 are used in-turn in an expanding-ring search. The default is
2024 eight multiples of 32 starting at 31.
2025 The trap receiver will generally log event messages and other
2027 information from the server in a log file. While such monitor
2028 programs may also request their own trap dynamically, configur‐
2029 ing a trap receiver will ensure that no messages are lost when
2030 the server is started.
2031 hop ...
2033 This command specifies a list of TTL values in increasing order,
2034 up to 8 values can be specified. In manycast mode these values
2035 are used in turn in an expanding-ring search. The default is
2036 eight multiples of 32 starting at 31.
2037
2039 --help Display usage information and exit.
2040 --more-help
2042 Pass the extended usage information through a pager.
2043 --version [{v|c|n}]
2045 Output version of program and exit. The default mode is `v', a
2046 simple version. The `c' mode will print copyright information
2047 and `n' will print the full copyright notice.
2048
2050 Any option that is not marked as not presettable may be preset by load‐
2051 ing values from environment variables named:
2052 NTP_CONF_<option-name> or NTP_CONF
2053
2055 See OPTION PRESETS for configuration environment variables.
2056
2058 /etc/ntp.conf the default name of the configuration file
2059 ntp.keys private MD5 keys
2060 ntpkey RSA private key
2061 ntpkey_host RSA public key
2062 ntp_dh Diffie-Hellman agreement parameters
2063
2065 One of the following exit values will be returned:
2066 0 (EXIT_SUCCESS)
2068 Successful program execution.
2069 1 (EXIT_FAILURE)
2071 The operation failed or the command syntax was not valid.
2072 70 (EX_SOFTWARE)
2074 libopts had an internal operational error. Please report it to
2075 autogen-users@lists.sourceforge.net. Thank you.
2076
2078 ntpd(8), ntpdc(8), ntpq(8)
2079 In addition to the manual pages provided, comprehensive documentation
2081 is available on the world wide web at http://www.ntp.org/. A snapshot
2082 of this documentation is available in HTML format in
2083 /usr/share/doc/ntp. David L. Mills, Network Time Protocol (Version 4),
2084 RFC5905
2085
2087 The University of Delaware and Network Time Foundation
2088
2090 Copyright (C) 1992-2017 The University of Delaware and Network Time
2091 Foundation all rights reserved. This program is released under the
2092 terms of the NTP license, <http://ntp.org/license>.
2093
2095 The syntax checking is not picky; some combinations of ridiculous and
2096 even hilarious options and modes may not be detected.
2097 The ntpkey_host files are really digital certificates. These should be
2099 obtained via secure directory services when they become universally
2100 available.
2101 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
2103
2105 This document was derived from FreeBSD.
2106 This manual page was AutoGen-erated from the ntp.conf option defini‐
2108 tions.
21094.2.8p13 20 Feb 2019 ntp.conf(5)