2 @section Notes about ntp.conf
4 @cindex Network Time Protocol (NTP) daemon configuration file format
7 # EDIT THIS FILE WITH CAUTION (invoke-ntp.conf.texi)
9 # It has been AutoGen-ed March 3, 2020 at 05:40:57 PM by AutoGen 5.18.5
10 # From the definitions ntp.conf.def
11 # and the template file agtexi-file.tpl
18 configuration file is read at initial startup by the
19 @code{ntpd(1ntpdmdoc)}
20 daemon in order to specify the synchronization sources,
21 modes and other related information.
22 Usually, it is installed in the
25 but could be installed elsewhere
30 The file format is similar to other
34 @quoteleft{}#@quoteright{}
35 character and extend to the end of the line;
36 blank lines are ignored.
37 Configuration commands consist of an initial keyword
38 followed by a list of arguments,
39 some of which may be optional, separated by whitespace.
40 Commands may not be continued over multiple lines.
41 Arguments may be host names,
42 host addresses written in numeric, dotted-quad form,
43 integers, floating point numbers (when specifying times in seconds)
46 The rest of this page describes the configuration and control options.
48 "Notes on Configuring NTP and Setting up an NTP Subnet"
50 (available as part of the HTML documentation
52 @file{/usr/share/doc/ntp})
53 contains an extended discussion of these options.
54 In addition to the discussion of general
55 @ref{Configuration Options},
56 there are sections describing the following supported functionality
57 and the options used to control it:
60 @ref{Authentication Support}
62 @ref{Monitoring Support}
64 @ref{Access Control Support}
66 @ref{Automatic NTP Configuration Options}
68 @ref{Reference Clock Support}
70 @ref{Miscellaneous Options}
73 Following these is a section describing
74 @ref{Miscellaneous Options}.
75 While there is a rich set of options available,
76 the only required option is one or more
84 @node Configuration Support
85 @subsection Configuration Support
86 Following is a description of the configuration commands in
88 These commands have the same basic functions as in NTPv3 and
89 in some cases new functions and new arguments.
91 classes of commands, configuration commands that configure a
92 persistent association with a remote server or peer or reference
93 clock, and auxiliary commands that specify environmental variables
94 that control various related operations.
95 @subsubsection Configuration Commands
96 The various modes are determined by the command keyword and the
97 type of the required IP address.
98 Addresses are classed by type as
99 (s) a remote server or peer (IPv4 class A, B and C), (b) the
100 broadcast address of a local interface, (m) a multicast address (IPv4
101 class D), or (r) a reference clock address (127.127.x.x).
103 only those options applicable to each command are listed below.
105 of options not listed may not be caught as an error, but may result
106 in some weird and even destructive behavior.
108 If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
109 is detected, support for the IPv6 address family is generated
110 in addition to the default support of the IPv4 address family.
111 In a few cases, including the
115 @code{ntpq(1ntpqmdoc)}
117 @code{ntpdc(1ntpdcmdoc)},
118 IPv6 addresses are automatically generated.
119 IPv6 addresses can be identified by the presence of colons
120 @quotedblleft{}:@quotedblright{}
121 in the address field.
122 IPv6 addresses can be used almost everywhere where
123 IPv4 addresses can be used,
124 with the exception of reference clock addresses,
125 which are always IPv4.
127 Note that in contexts where a host name is expected, a
130 the host name forces DNS resolution to the IPv4 namespace,
133 qualifier forces DNS resolution to the IPv6 namespace.
134 See IPv6 references for the
135 equivalent classes for that address family.
137 @item @code{pool} @kbd{address} @code{[@code{burst}]} @code{[@code{iburst}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} @code{[@code{xmtnonce}]}
138 @item @code{server} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{burst}]} @code{[@code{iburst}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} @code{[@code{true}]} @code{[@code{xmtnonce}]}
139 @item @code{peer} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} @code{[@code{true}]} @code{[@code{xleave}]}
140 @item @code{broadcast} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{ttl} @kbd{ttl}]} @code{[@code{xleave}]}
141 @item @code{manycastclient} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} @code{[@code{ttl} @kbd{ttl}]}
144 These five commands specify the time server name or address to
145 be used and the mode in which to operate.
149 either a DNS name or an IP address in dotted-quad notation.
150 Additional information on association behavior can be found in the
151 "Association Management"
153 (available as part of the HTML documentation
155 @file{/usr/share/doc/ntp}).
158 For type s addresses, this command mobilizes a persistent
159 client mode association with a number of remote servers.
160 In this mode the local clock can synchronized to the
161 remote server, but the remote server can never be synchronized to
164 For type s and r addresses, this command mobilizes a persistent
165 client mode association with the specified remote server or local
167 In this mode the local clock can synchronized to the
168 remote server, but the remote server can never be synchronized to
175 For type s addresses (only), this command mobilizes a
176 persistent symmetric-active mode association with the specified
178 In this mode the local clock can be synchronized to
179 the remote peer or the remote peer can be synchronized to the local
181 This is useful in a network of servers where, depending on
182 various failure scenarios, either the local or remote peer may be
183 the better source of time.
184 This command should NOT be used for type
186 @item @code{broadcast}
187 For type b and m addresses (only), this
188 command mobilizes a persistent broadcast mode association.
190 commands can be used to specify multiple local broadcast interfaces
191 (subnets) and/or multiple multicast groups.
193 broadcast messages go only to the interface associated with the
194 subnet specified, but multicast messages go to all interfaces.
195 In broadcast mode the local server sends periodic broadcast
196 messages to a client population at the
198 specified, which is usually the broadcast address on (one of) the
199 local network(s) or a multicast address assigned to NTP.
201 has assigned the multicast group address IPv4 224.0.1.1 and
202 IPv6 ff05::101 (site local) exclusively to
203 NTP, but other nonconflicting addresses can be used to contain the
204 messages within administrative boundaries.
206 specification applies only to the local server operating as a
207 sender; for operation as a broadcast client, see the
208 @code{broadcastclient}
210 @code{multicastclient}
213 @item @code{manycastclient}
214 For type m addresses (only), this command mobilizes a
215 manycast client mode association for the multicast address
217 In this case a specific address must be supplied which
218 matches the address used on the
219 @code{manycastserver}
221 the designated manycast servers.
222 The NTP multicast address
223 224.0.1.1 assigned by the IANA should NOT be used, unless specific
224 means are taken to avoid spraying large areas of the Internet with
225 these messages and causing a possibly massive implosion of replies
228 @code{manycastserver}
229 command specifies that the local server
230 is to operate in client mode with the remote servers that are
231 discovered as the result of broadcast/multicast messages.
233 client broadcasts a request message to the group address associated
236 and specifically enabled
237 servers respond to these messages.
238 The client selects the servers
239 providing the best time and continues as with the
242 The remaining servers are discarded as if never
249 All packets sent to and received from the server or peer are to
250 include authentication fields encrypted using the autokey scheme
252 @ref{Authentication Options}.
254 when the server is reachable, send a burst of eight packets
255 instead of the usual one.
256 The packet spacing is normally 2 s;
257 however, the spacing between the first and second packets
258 can be changed with the
261 additional time for a modem or ISDN call to complete.
262 This is designed to improve timekeeping quality
265 command and s addresses.
267 When the server is unreachable, send a burst of eight packets
268 instead of the usual one.
269 The packet spacing is normally 2 s;
270 however, the spacing between the first two packets can be
274 additional time for a modem or ISDN call to complete.
275 This is designed to speed the initial synchronization
278 command and s addresses and when
279 @code{ntpd(1ntpdmdoc)}
283 @item @code{key} @kbd{key}
284 All packets sent to and received from the server or peer are to
285 include authentication fields encrypted using the specified
287 identifier with values from 1 to 65535, inclusive.
289 default is to include no encryption field.
290 @item @code{minpoll} @kbd{minpoll}
291 @item @code{maxpoll} @kbd{maxpoll}
292 These options specify the minimum and maximum poll intervals
293 for NTP messages, as a power of 2 in seconds
295 interval defaults to 10 (1,024 s), but can be increased by the
297 option to an upper limit of 17 (36.4 h).
299 minimum poll interval defaults to 6 (64 s), but can be decreased by
302 option to a lower limit of 4 (16 s).
303 @item @code{noselect}
304 Marks the server as unused, except for display purposes.
305 The server is discarded by the selection algroithm.
307 Says the association can be preempted.
309 Marks the server as preferred.
310 All other things being equal,
311 this host will be chosen for synchronization among a set of
312 correctly operating hosts.
314 "Mitigation Rules and the prefer Keyword"
316 (available as part of the HTML documentation
318 @file{/usr/share/doc/ntp})
319 for further information.
321 Marks the server as a truechimer,
322 forcing the association to always survive the selection and clustering algorithms.
323 This option should almost certainly
325 be used while testing an association.
326 @item @code{ttl} @kbd{ttl}
327 This option is used only with broadcast server and manycast
329 It specifies the time-to-live
332 use on broadcast server and multicast server and the maximum
334 for the expanding ring search with manycast
336 Selection of the proper value, which defaults to
337 127, is something of a black art and should be coordinated with the
338 network administrator.
339 @item @code{version} @kbd{version}
340 Specifies the version number to be used for outgoing NTP
342 Versions 1-4 are the choices, with version 4 the
349 modes only, this flag enables interleave mode.
350 @item @code{xmtnonce}
355 modes, this flag puts a random number in the packet's transmit timestamp.
358 @subsubsection Auxiliary Commands
360 @item @code{broadcastclient}
361 This command enables reception of broadcast server messages to
362 any local interface (type b) address.
363 Upon receiving a message for
364 the first time, the broadcast client measures the nominal server
365 propagation delay using a brief client/server exchange with the
366 server, then enters the broadcast client mode, in which it
367 synchronizes to succeeding broadcast messages.
369 to avoid accidental or malicious disruption in this mode, both the
370 server and client should operate using symmetric-key or public-key
371 authentication as described in
372 @ref{Authentication Options}.
373 @item @code{manycastserver} @kbd{address} @kbd{...}
374 This command enables reception of manycast client messages to
375 the multicast group address(es) (type m) specified.
377 address is required, but the NTP multicast address 224.0.1.1
378 assigned by the IANA should NOT be used, unless specific means are
379 taken to limit the span of the reply and avoid a possibly massive
380 implosion at the original sender.
381 Note that, in order to avoid
382 accidental or malicious disruption in this mode, both the server
383 and client should operate using symmetric-key or public-key
384 authentication as described in
385 @ref{Authentication Options}.
386 @item @code{multicastclient} @kbd{address} @kbd{...}
387 This command enables reception of multicast server messages to
388 the multicast group address(es) (type m) specified.
390 a message for the first time, the multicast client measures the
391 nominal server propagation delay using a brief client/server
392 exchange with the server, then enters the broadcast client mode, in
393 which it synchronizes to succeeding multicast messages.
395 in order to avoid accidental or malicious disruption in this mode,
396 both the server and client should operate using symmetric-key or
397 public-key authentication as described in
398 @ref{Authentication Options}.
399 @item @code{mdnstries} @kbd{number}
400 If we are participating in mDNS,
401 after we have synched for the first time
402 we attempt to register with the mDNS system.
403 If that registration attempt fails,
404 we try again at one minute intervals for up to
409 may be starting before mDNS.
410 The default value for
414 @node Authentication Support
415 @subsection Authentication Support
416 Authentication support allows the NTP client to verify that the
417 server is in fact known and trusted and not an intruder intending
418 accidentally or on purpose to masquerade as that server.
420 specification RFC-1305 defines a scheme which provides
421 cryptographic authentication of received NTP packets.
423 this was done using the Data Encryption Standard (DES) algorithm
424 operating in Cipher Block Chaining (CBC) mode, commonly called
426 Subsequently, this was replaced by the RSA Message Digest
427 5 (MD5) algorithm using a private key, commonly called keyed-MD5.
428 Either algorithm computes a message digest, or one-way hash, which
429 can be used to verify the server has the correct private key and
432 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
433 cryptography and, in addition, provides a new Autokey scheme
434 based on public key cryptography.
435 Public key cryptography is generally considered more secure
436 than symmetric key cryptography, since the security is based
437 on a private value which is generated by each server and
439 With Autokey all key distribution and
440 management functions involve only public values, which
441 considerably simplifies key distribution and storage.
442 Public key management is based on X.509 certificates,
443 which can be provided by commercial services or
444 produced by utility programs in the OpenSSL software library
445 or the NTPv4 distribution.
447 While the algorithms for symmetric key cryptography are
448 included in the NTPv4 distribution, public key cryptography
449 requires the OpenSSL software library to be installed
450 before building the NTP distribution.
451 Directions for doing that
452 are on the Building and Installing the Distribution page.
454 Authentication is configured separately for each association
464 @code{manycastclient}
465 configuration commands as described in
466 @ref{Configuration Options}
469 options described below specify the locations of the key files,
470 if other than default, which symmetric keys are trusted
471 and the interval between various operations, if other than default.
473 Authentication is always enabled,
474 although ineffective if not configured as
476 If a NTP packet arrives
477 including a message authentication
478 code (MAC), it is accepted only if it
479 passes all cryptographic checks.
481 checks require correct key ID, key value
484 been modified in any way or replayed
485 by an intruder, it will fail one or more
486 of these checks and be discarded.
487 Furthermore, the Autokey scheme requires a
488 preliminary protocol exchange to obtain
489 the server certificate, verify its
490 credentials and initialize the protocol
494 flag controls whether new associations or
495 remote configuration commands require cryptographic authentication.
496 This flag can be set or reset by the
500 commands and also by remote
501 configuration commands sent by a
502 @code{ntpdc(1ntpdcmdoc)}
505 If this flag is enabled, which is the default
506 case, new broadcast client and symmetric passive associations and
507 remote configuration commands must be cryptographically
508 authenticated using either symmetric key or public key cryptography.
510 flag is disabled, these operations are effective
511 even if not cryptographic
513 It should be understood
514 that operating with the
516 flag disabled invites a significant vulnerability
517 where a rogue hacker can
518 masquerade as a falseticker and seriously
519 disrupt system timekeeping.
521 important to note that this flag has no purpose
522 other than to allow or disallow
523 a new association in response to new broadcast
524 and symmetric active messages
525 and remote configuration commands and, in particular,
526 the flag has no effect on
527 the authentication process itself.
529 An attractive alternative where multicast support is available
530 is manycast mode, in which clients periodically troll
531 for servers as described in the
532 @ref{Automatic NTP Configuration Options}
534 Either symmetric key or public key
535 cryptographic authentication can be used in this mode.
536 The principle advantage
537 of manycast mode is that potential servers need not be
538 configured in advance,
539 since the client finds them during regular operation,
540 and the configuration
541 files for all clients can be identical.
543 The security model and protocol schemes for
544 both symmetric key and public key
545 cryptography are summarized below;
546 further details are in the briefings, papers
547 and reports at the NTP project page linked from
548 @code{http://www.ntp.org/}.
549 @subsubsection Symmetric-Key Cryptography
550 The original RFC-1305 specification allows any one of possibly
551 65,535 keys, each distinguished by a 32-bit key identifier, to
552 authenticate an association.
553 The servers and clients involved must
554 agree on the key and key identifier to
555 authenticate NTP packets.
557 related information are specified in a key
560 which must be distributed and stored using
561 secure means beyond the scope of the NTP protocol itself.
562 Besides the keys used
563 for ordinary NTP associations,
564 additional keys can be used as passwords for the
565 @code{ntpq(1ntpqmdoc)}
567 @code{ntpdc(1ntpdcmdoc)}
571 @code{ntpd(1ntpdmdoc)}
572 is first started, it reads the key file specified in the
574 configuration command and installs the keys
577 individual keys must be activated with the
581 allows, for instance, the installation of possibly
582 several batches of keys and
583 then activating or deactivating each batch
585 @code{ntpdc(1ntpdcmdoc)}.
586 This also provides a revocation capability that can be used
587 if a key becomes compromised.
590 command selects the key used as the password for the
591 @code{ntpdc(1ntpdcmdoc)}
594 command selects the key used as the password for the
595 @code{ntpq(1ntpqmdoc)}
597 @subsubsection Public Key Cryptography
598 NTPv4 supports the original NTPv3 symmetric key scheme
599 described in RFC-1305 and in addition the Autokey protocol,
600 which is based on public key cryptography.
601 The Autokey Version 2 protocol described on the Autokey Protocol
602 page verifies packet integrity using MD5 message digests
603 and verifies the source with digital signatures and any of several
604 digest/signature schemes.
605 Optional identity schemes described on the Identity Schemes
606 page and based on cryptographic challenge/response algorithms
608 Using all of these schemes provides strong security against
609 replay with or without modification, spoofing, masquerade
610 and most forms of clogging attacks.
612 The Autokey protocol has several modes of operation
613 corresponding to the various NTP modes supported.
614 Most modes use a special cookie which can be
615 computed independently by the client and server,
616 but encrypted in transmission.
617 All modes use in addition a variant of the S-KEY scheme,
618 in which a pseudo-random key list is generated and used
620 These schemes are described along with an executive summary,
621 current status, briefing slides and reading list on the
622 @ref{Autonomous Authentication}
625 The specific cryptographic environment used by Autokey servers
626 and clients is determined by a set of files
627 and soft links generated by the
628 @code{ntp-keygen(1ntpkeygenmdoc)}
630 This includes a required host key file,
631 required certificate file and optional sign key file,
632 leapsecond file and identity scheme files.
634 digest/signature scheme is specified in the X.509 certificate
635 along with the matching sign key.
636 There are several schemes
637 available in the OpenSSL software library, each identified
638 by a specific string such as
639 @code{md5WithRSAEncryption},
640 which stands for the MD5 message digest with RSA
642 The current NTP distribution supports
643 all the schemes in the OpenSSL library, including
644 those based on RSA and DSA digital signatures.
646 NTP secure groups can be used to define cryptographic compartments
647 and security hierarchies.
648 It is important that every host
649 in the group be able to construct a certificate trail to one
650 or more trusted hosts in the same group.
652 host runs the Autokey protocol to obtain the certificates
653 for all hosts along the trail to one or more trusted hosts.
654 This requires the configuration file in all hosts to be
655 engineered so that, even under anticipated failure conditions,
656 the NTP subnet will form such that every group host can find
657 a trail to at least one trusted host.
658 @subsubsection Naming and Addressing
659 It is important to note that Autokey does not use DNS to
660 resolve addresses, since DNS can't be completely trusted
661 until the name servers have synchronized clocks.
662 The cryptographic name used by Autokey to bind the host identity
663 credentials and cryptographic values must be independent
664 of interface, network and any other naming convention.
665 The name appears in the host certificate in either or both
666 the subject and issuer fields, so protection against
667 DNS compromise is essential.
669 By convention, the name of an Autokey host is the name returned
671 @code{gethostname(2)}
672 system call or equivalent in other systems.
674 model, there are no provisions to allow alternate names or aliases.
675 However, this is not to say that DNS aliases, different names
676 for each interface, etc., are constrained in any way.
678 It is also important to note that Autokey verifies authenticity
679 using the host name, network address and public keys,
680 all of which are bound together by the protocol specifically
681 to deflect masquerade attacks.
682 For this reason Autokey
683 includes the source and destination IP addresses in message digest
684 computations and so the same addresses must be available
685 at both the server and client.
686 For this reason operation
687 with network address translation schemes is not possible.
688 This reflects the intended robust security model where government
689 and corporate NTP servers are operated outside firewall perimeters.
690 @subsubsection Operation
691 A specific combination of authentication scheme (none,
692 symmetric key, public key) and identity scheme is called
693 a cryptotype, although not all combinations are compatible.
694 There may be management configurations where the clients,
695 servers and peers may not all support the same cryptotypes.
696 A secure NTPv4 subnet can be configured in many ways while
697 keeping in mind the principles explained above and
699 Note however that some cryptotype
700 combinations may successfully interoperate with each other,
701 but may not represent good security practice.
703 The cryptotype of an association is determined at the time
704 of mobilization, either at configuration time or some time
705 later when a message of appropriate cryptotype arrives.
710 configuration command and no
714 subcommands are present, the association is not
715 authenticated; if the
717 subcommand is present, the association is authenticated
718 using the symmetric key ID specified; if the
720 subcommand is present, the association is authenticated
723 When multiple identity schemes are supported in the Autokey
724 protocol, the first message exchange determines which one is used.
725 The client request message contains bits corresponding
726 to which schemes it has available.
727 The server response message
728 contains bits corresponding to which schemes it has available.
729 Both server and client match the received bits with their own
730 and select a common scheme.
732 Following the principle that time is a public value,
733 a server responds to any client packet that matches
734 its cryptotype capabilities.
735 Thus, a server receiving
736 an unauthenticated packet will respond with an unauthenticated
737 packet, while the same server receiving a packet of a cryptotype
738 it supports will respond with packets of that cryptotype.
739 However, unconfigured broadcast or manycast client
740 associations or symmetric passive associations will not be
741 mobilized unless the server supports a cryptotype compatible
742 with the first packet received.
743 By default, unauthenticated associations will not be mobilized
744 unless overridden in a decidedly dangerous way.
746 Some examples may help to reduce confusion.
747 Client Alice has no specific cryptotype selected.
748 Server Bob has both a symmetric key file and minimal Autokey files.
749 Alice's unauthenticated messages arrive at Bob, who replies with
750 unauthenticated messages.
751 Cathy has a copy of Bob's symmetric
752 key file and has selected key ID 4 in messages to Bob.
753 Bob verifies the message with his key ID 4.
755 same key and the message is verified, Bob sends Cathy a reply
756 authenticated with that key.
757 If verification fails,
758 Bob sends Cathy a thing called a crypto-NAK, which tells her
760 She can see the evidence using the
761 @code{ntpq(1ntpqmdoc)}
764 Denise has rolled her own host key and certificate.
765 She also uses one of the identity schemes as Bob.
766 She sends the first Autokey message to Bob and they
767 both dance the protocol authentication and identity steps.
768 If all comes out okay, Denise and Bob continue as described above.
770 It should be clear from the above that Bob can support
771 all the girls at the same time, as long as he has compatible
772 authentication and identity credentials.
773 Now, Bob can act just like the girls in his own choice of servers;
774 he can run multiple configured associations with multiple different
775 servers (or the same server, although that might not be useful).
776 But, wise security policy might preclude some cryptotype
777 combinations; for instance, running an identity scheme
778 with one server and no authentication with another might not be wise.
779 @subsubsection Key Management
780 The cryptographic values used by the Autokey protocol are
781 incorporated as a set of files generated by the
782 @code{ntp-keygen(1ntpkeygenmdoc)}
783 utility program, including symmetric key, host key and
784 public certificate files, as well as sign key, identity parameters
785 and leapseconds files.
786 Alternatively, host and sign keys and
787 certificate files can be generated by the OpenSSL utilities
788 and certificates can be imported from public certificate
790 Note that symmetric keys are necessary for the
791 @code{ntpq(1ntpqmdoc)}
793 @code{ntpdc(1ntpdcmdoc)}
795 The remaining files are necessary only for the
798 Certificates imported from OpenSSL or public certificate
799 authorities have certian limitations.
800 The certificate should be in ASN.1 syntax, X.509 Version 3
801 format and encoded in PEM, which is the same format
803 The overall length of the certificate encoded
804 in ASN.1 must not exceed 1024 bytes.
805 The subject distinguished
806 name field (CN) is the fully qualified name of the host
807 on which it is used; the remaining subject fields are ignored.
808 The certificate extension fields must not contain either
809 a subject key identifier or a issuer key identifier field;
810 however, an extended key usage field for a trusted host must
813 Other extension fields are ignored.
814 @subsubsection Authentication Commands
816 @item @code{autokey} @code{[@kbd{logsec}]}
817 Specifies the interval between regenerations of the session key
818 list used with the Autokey protocol.
819 Note that the size of the key
820 list for each association depends on this interval and the current
822 The default value is 12 (4096 s or about 1.1 hours).
823 For poll intervals above the specified interval, a session key list
824 with a single entry will be regenerated for every message
826 @item @code{controlkey} @kbd{key}
827 Specifies the key identifier to use with the
828 @code{ntpq(1ntpqmdoc)}
829 utility, which uses the standard
830 protocol defined in RFC-1305.
834 the key identifier for a trusted key, where the value can be in the
835 range 1 to 65,535, inclusive.
836 @item @code{crypto} @code{[@code{cert} @kbd{file}]} @code{[@code{leap} @kbd{file}]} @code{[@code{randfile} @kbd{file}]} @code{[@code{host} @kbd{file}]} @code{[@code{sign} @kbd{file}]} @code{[@code{gq} @kbd{file}]} @code{[@code{gqpar} @kbd{file}]} @code{[@code{iffpar} @kbd{file}]} @code{[@code{mvpar} @kbd{file}]} @code{[@code{pw} @kbd{password}]}
837 This command requires the OpenSSL library.
838 It activates public key
839 cryptography, selects the message digest and signature
840 encryption scheme and loads the required private and public
841 values described above.
842 If one or more files are left unspecified,
843 the default names are used as described above.
844 Unless the complete path and name of the file are specified, the
845 location of a file is relative to the keys directory specified
849 @file{/usr/local/etc}.
850 Following are the subcommands:
852 @item @code{cert} @kbd{file}
853 Specifies the location of the required host public certificate file.
854 This overrides the link
855 @file{ntpkey_cert_}@kbd{hostname}
856 in the keys directory.
857 @item @code{gqpar} @kbd{file}
858 Specifies the location of the optional GQ parameters file.
861 @file{ntpkey_gq_}@kbd{hostname}
862 in the keys directory.
863 @item @code{host} @kbd{file}
864 Specifies the location of the required host key file.
867 @file{ntpkey_key_}@kbd{hostname}
868 in the keys directory.
869 @item @code{iffpar} @kbd{file}
870 Specifies the location of the optional IFF parameters file.
871 This overrides the link
872 @file{ntpkey_iff_}@kbd{hostname}
873 in the keys directory.
874 @item @code{leap} @kbd{file}
875 Specifies the location of the optional leapsecond file.
876 This overrides the link
878 in the keys directory.
879 @item @code{mvpar} @kbd{file}
880 Specifies the location of the optional MV parameters file.
881 This overrides the link
882 @file{ntpkey_mv_}@kbd{hostname}
883 in the keys directory.
884 @item @code{pw} @kbd{password}
885 Specifies the password to decrypt files containing private keys and
887 This is required only if these files have been
889 @item @code{randfile} @kbd{file}
890 Specifies the location of the random seed file used by the OpenSSL
892 The defaults are described in the main text above.
893 @item @code{sign} @kbd{file}
894 Specifies the location of the optional sign key file.
897 @file{ntpkey_sign_}@kbd{hostname}
898 in the keys directory.
900 not found, the host key is also the sign key.
902 @item @code{keys} @kbd{keyfile}
903 Specifies the complete path and location of the MD5 key file
904 containing the keys and key identifiers used by
905 @code{ntpd(1ntpdmdoc)},
906 @code{ntpq(1ntpqmdoc)}
908 @code{ntpdc(1ntpdcmdoc)}
909 when operating with symmetric key cryptography.
910 This is the same operation as the
913 @item @code{keysdir} @kbd{path}
914 This command specifies the default directory path for
915 cryptographic keys, parameters and certificates.
917 @file{/usr/local/etc/}.
918 @item @code{requestkey} @kbd{key}
919 Specifies the key identifier to use with the
920 @code{ntpdc(1ntpdcmdoc)}
921 utility program, which uses a
922 proprietary protocol specific to this implementation of
923 @code{ntpd(1ntpdmdoc)}.
926 argument is a key identifier
927 for the trusted key, where the value can be in the range 1 to
929 @item @code{revoke} @kbd{logsec}
930 Specifies the interval between re-randomization of certain
931 cryptographic values used by the Autokey scheme, as a power of 2 in
933 These values need to be updated frequently in order to
934 deflect brute-force attacks on the algorithms of the scheme;
935 however, updating some values is a relatively expensive operation.
936 The default interval is 16 (65,536 s or about 18 hours).
938 intervals above the specified interval, the values will be updated
939 for every message sent.
940 @item @code{trustedkey} @kbd{key} @kbd{...}
941 Specifies the key identifiers which are trusted for the
942 purposes of authenticating peers with symmetric key cryptography,
943 as well as keys used by the
944 @code{ntpq(1ntpqmdoc)}
946 @code{ntpdc(1ntpdcmdoc)}
948 The authentication procedures require that both the local
949 and remote servers share the same key and key identifier for this
950 purpose, although different keys can be used with different
954 arguments are 32-bit unsigned
955 integers with values from 1 to 65,535.
957 @subsubsection Error Codes
958 The following error codes are reported via the NTP control
959 and monitoring protocol trap mechanism.
962 (bad field format or length)
963 The packet has invalid version, length or format.
966 The packet timestamp is the same or older than the most recent received.
967 This could be due to a replay or a server clock time step.
970 The packet filestamp is the same or older than the most recent received.
971 This could be due to a replay or a key file generation error.
973 (bad or missing public key)
974 The public key is missing, has incorrect format or is an unsupported type.
976 (unsupported digest type)
977 The server requires an unsupported digest/signature scheme.
979 (mismatched digest types)
982 (bad signature length)
983 The signature length does not match the current public key.
985 (signature not verified)
986 The message fails the signature check.
987 It could be bogus or signed by a
988 different private key.
990 (certificate not verified)
991 The certificate is invalid or signed with the wrong key.
993 (certificate not verified)
994 The certificate is not yet valid or has expired or the signature could not
997 (bad or missing cookie)
998 The cookie is missing, corrupted or bogus.
1000 (bad or missing leapseconds table)
1001 The leapseconds table is missing, corrupted or bogus.
1003 (bad or missing certificate)
1004 The certificate is missing, corrupted or bogus.
1006 (bad or missing identity)
1007 The identity key is missing, corrupt or bogus.
1009 @node Monitoring Support
1010 @subsection Monitoring Support
1011 @code{ntpd(1ntpdmdoc)}
1012 includes a comprehensive monitoring facility suitable
1013 for continuous, long term recording of server and client
1014 timekeeping performance.
1018 for a listing and example of each type of statistics currently
1020 Statistic files are managed using file generation sets
1023 directory of the source code distribution.
1025 these facilities and
1028 jobs, the data can be
1029 automatically summarized and archived for retrospective analysis.
1030 @subsubsection Monitoring Commands
1032 @item @code{statistics} @kbd{name} @kbd{...}
1033 Enables writing of statistics records.
1034 Currently, eight kinds of
1036 statistics are supported.
1038 @item @code{clockstats}
1039 Enables recording of clock driver statistics information.
1041 received from a clock driver appends a line of the following form to
1042 the file generation set named
1045 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1048 The first two fields show the date (Modified Julian Day) and time
1049 (seconds and fraction past UTC midnight).
1050 The next field shows the
1051 clock address in dotted-quad notation.
1052 The final field shows the last
1053 timecode received from the clock in decoded ASCII format, where
1055 In some clock drivers a good deal of additional information
1056 can be gathered and displayed as well.
1057 See information specific to each
1058 clock for further details.
1059 @item @code{cryptostats}
1060 This option requires the OpenSSL cryptographic software library.
1062 enables recording of cryptographic public key protocol information.
1063 Each message received by the protocol module appends a line of the
1064 following form to the file generation set named
1067 49213 525.624 127.127.4.1 message
1070 The first two fields show the date (Modified Julian Day) and time
1071 (seconds and fraction past UTC midnight).
1072 The next field shows the peer
1073 address in dotted-quad notation, The final message field includes the
1074 message type and certain ancillary information.
1076 @ref{Authentication Options}
1077 section for further information.
1078 @item @code{loopstats}
1079 Enables recording of loop filter statistics information.
1081 update of the local clock outputs a line of the following form to
1082 the file generation set named
1085 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1088 The first two fields show the date (Modified Julian Day) and
1089 time (seconds and fraction past UTC midnight).
1090 The next five fields
1091 show time offset (seconds), frequency offset (parts per million -
1092 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1093 discipline time constant.
1094 @item @code{peerstats}
1095 Enables recording of peer statistics information.
1097 statistics records of all peers of a NTP server and of special
1098 signals, where present and configured.
1099 Each valid update appends a
1100 line of the following form to the current element of a file
1101 generation set named
1104 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
1107 The first two fields show the date (Modified Julian Day) and
1108 time (seconds and fraction past UTC midnight).
1110 show the peer address in dotted-quad notation and status,
1112 The status field is encoded in hex in the format
1113 described in Appendix A of the NTP specification RFC 1305.
1114 The final four fields show the offset,
1115 delay, dispersion and RMS jitter, all in seconds.
1116 @item @code{rawstats}
1117 Enables recording of raw-timestamp statistics information.
1119 includes statistics records of all peers of a NTP server and of
1120 special signals, where present and configured.
1122 received from a peer or clock driver appends a line of the
1123 following form to the file generation set named
1126 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1129 The first two fields show the date (Modified Julian Day) and
1130 time (seconds and fraction past UTC midnight).
1132 show the remote peer or clock address followed by the local address
1133 in dotted-quad notation.
1134 The final four fields show the originate,
1135 receive, transmit and final NTP timestamps in order.
1137 values are as received and before processing by the various data
1138 smoothing and mitigation algorithms.
1139 @item @code{sysstats}
1140 Enables recording of ntpd statistics counters on a periodic basis.
1142 hour a line of the following form is appended to the file generation
1146 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1149 The first two fields show the date (Modified Julian Day) and time
1150 (seconds and fraction past UTC midnight).
1151 The remaining ten fields show
1152 the statistics counter values accumulated since the last generated
1155 @item Time since restart @code{36000}
1156 Time in hours since the system was last rebooted.
1157 @item Packets received @code{81965}
1158 Total number of packets received.
1159 @item Packets processed @code{0}
1160 Number of packets received in response to previous packets sent
1161 @item Current version @code{9546}
1162 Number of packets matching the current NTP version.
1163 @item Previous version @code{56}
1164 Number of packets matching the previous NTP version.
1165 @item Bad version @code{71793}
1166 Number of packets matching neither NTP version.
1167 @item Access denied @code{512}
1168 Number of packets denied access for any reason.
1169 @item Bad length or format @code{540}
1170 Number of packets with invalid length, format or port number.
1171 @item Bad authentication @code{10}
1172 Number of packets not verified as authentic.
1173 @item Rate exceeded @code{147}
1174 Number of packets discarded due to rate limitation.
1176 @item @code{statsdir} @kbd{directory_path}
1177 Indicates the full path of a directory where statistics files
1178 should be created (see below).
1180 the (otherwise constant)
1182 filename prefix to be modified for file generation sets, which
1183 is useful for handling statistics logs.
1184 @item @code{filegen} @kbd{name} @code{[@code{file} @kbd{filename}]} @code{[@code{type} @kbd{typename}]} @code{[@code{link} | @code{nolink}]} @code{[@code{enable} | @code{disable}]}
1185 Configures setting of generation file set name.
1187 file sets provide a means for handling files that are
1188 continuously growing during the lifetime of a server.
1189 Server statistics are a typical example for such files.
1190 Generation file sets provide access to a set of files used
1191 to store the actual data.
1192 At any time at most one element
1193 of the set is being written to.
1194 The type given specifies
1195 when and how data will be directed to a new element of the set.
1196 This way, information stored in elements of a file set
1197 that are currently unused are available for administrational
1198 operations without the risk of disturbing the operation of ntpd.
1199 (Most important: they can be removed to free space for new data
1202 Note that this command can be sent from the
1203 @code{ntpdc(1ntpdcmdoc)}
1204 program running at a remote location.
1207 This is the type of the statistics records, as shown in the
1210 @item @code{file} @kbd{filename}
1211 This is the file name for the statistics records.
1213 members are built from three concatenated elements
1220 This is a constant filename path.
1221 It is not subject to
1222 modifications via the
1225 It is defined by the
1226 server, usually specified as a compile-time constant.
1228 however, be configurable for individual file generation sets
1230 For example, the prefix used with
1234 generation can be configured using the
1236 option explained above.
1237 @item @code{filename}
1238 This string is directly concatenated to the prefix mentioned
1239 above (no intervening
1240 @quoteleft{}/@quoteright{}).
1241 This can be modified using
1242 the file argument to the
1248 allowed in this component to prevent filenames referring to
1249 parts outside the filesystem hierarchy denoted by
1252 This part is reflects individual elements of a file set.
1254 generated according to the type of a file set.
1256 @item @code{type} @kbd{typename}
1257 A file generation set is characterized by its type.
1259 types are supported:
1262 The file set is actually a single plain file.
1264 One element of file set is used per incarnation of a ntpd
1266 This type does not perform any changes to file set
1267 members during runtime, however it provides an easy way of
1268 separating files belonging to different
1269 @code{ntpd(1ntpdmdoc)}
1270 server incarnations.
1271 The set member filename is built by appending a
1272 @quoteleft{}.@quoteright{}
1278 appending the decimal representation of the process ID of the
1279 @code{ntpd(1ntpdmdoc)}
1282 One file generation set element is created per day.
1284 defined as the period between 00:00 and 24:00 UTC.
1286 member suffix consists of a
1287 @quoteleft{}.@quoteright{}
1288 and a day specification in
1292 is a 4-digit year number (e.g., 1992).
1294 is a two digit month number.
1296 is a two digit day number.
1297 Thus, all information written at 10 December 1992 would end up
1300 @kbd{filename}.19921210.
1302 Any file set member contains data related to a certain week of
1304 The term week is defined by computing day-of-year
1306 Elements of such a file generation set are
1307 distinguished by appending the following suffix to the file set
1308 filename base: A dot, a 4-digit year number, the letter
1310 and a 2-digit week number.
1311 For example, information from January,
1312 10th 1992 would end up in a file with suffix
1313 .No . Ns Ar 1992W1 .
1315 One generation file set element is generated per month.
1317 file name suffix consists of a dot, a 4-digit year number, and
1320 One generation file element is generated per year.
1322 suffix consists of a dot and a 4 digit year number.
1324 This type of file generation sets changes to a new element of
1325 the file set every 24 hours of server operation.
1327 suffix consists of a dot, the letter
1329 and an 8-digit number.
1330 This number is taken to be the number of seconds the server is
1331 running at the start of the corresponding 24-hour period.
1332 Information is only written to a file generation by specifying
1334 output is prevented by specifying
1337 @item @code{link} | @code{nolink}
1338 It is convenient to be able to access the current element of a file
1339 generation set by a fixed name.
1340 This feature is enabled by
1345 If link is specified, a
1346 hard link from the current file set element to a file without
1348 When there is already a file with this name and
1349 the number of links of this file is one, it is renamed appending a
1353 @code{ntpd(1ntpdmdoc)}
1356 number of links is greater than one, the file is unlinked.
1358 allows the current file to be accessed by a constant name.
1359 @item @code{enable} @code{|} @code{disable}
1360 Enables or disables the recording function.
1364 @node Access Control Support
1365 @subsection Access Control Support
1367 @code{ntpd(1ntpdmdoc)}
1368 daemon implements a general purpose address/mask based restriction
1370 The list contains address/match entries sorted first
1371 by increasing address values and and then by increasing mask values.
1372 A match occurs when the bitwise AND of the mask and the packet
1373 source address is equal to the bitwise AND of the mask and
1374 address in the list.
1375 The list is searched in order with the
1376 last match found defining the restriction flags associated
1378 Additional information and examples can be found in the
1379 "Notes on Configuring NTP and Setting up a NTP Subnet"
1381 (available as part of the HTML documentation
1383 @file{/usr/share/doc/ntp}).
1385 The restriction facility was implemented in conformance
1386 with the access policies for the original NSFnet backbone
1388 Later the facility was expanded to deflect
1389 cryptographic and clogging attacks.
1390 While this facility may
1391 be useful for keeping unwanted or broken or malicious clients
1392 from congesting innocent servers, it should not be considered
1393 an alternative to the NTP authentication facilities.
1394 Source address based restrictions are easily circumvented
1395 by a determined cracker.
1397 Clients can be denied service because they are explicitly
1398 included in the restrict list created by the
1401 or implicitly as the result of cryptographic or rate limit
1403 Cryptographic violations include certificate
1404 or identity verification failure; rate limit violations generally
1405 result from defective NTP implementations that send packets
1407 Some violations cause denied service
1408 only for the offending packet, others cause denied service
1409 for a timed period and others cause the denied service for
1410 an indefinite period.
1411 When a client or network is denied access
1412 for an indefinite period, the only way at present to remove
1413 the restrictions is by restarting the server.
1414 @subsubsection The Kiss-of-Death Packet
1415 Ordinarily, packets denied service are simply dropped with no
1416 further action except incrementing statistics counters.
1418 more proactive response is needed, such as a server message that
1419 explicitly requests the client to stop sending and leave a message
1420 for the system operator.
1421 A special packet format has been created
1422 for this purpose called the "kiss-of-death" (KoD) packet.
1423 KoD packets have the leap bits set unsynchronized and stratum set
1424 to zero and the reference identifier field set to a four-byte
1430 flag of the matching restrict list entry is set,
1431 the code is "DENY"; if the
1433 flag is set and the rate limit
1434 is exceeded, the code is "RATE".
1435 Finally, if a cryptographic violation occurs, the code is "CRYP".
1437 A client receiving a KoD performs a set of sanity checks to
1438 minimize security exposure, then updates the stratum and
1439 reference identifier peer variables, sets the access
1440 denied (TEST4) bit in the peer flash variable and sends
1441 a message to the log.
1442 As long as the TEST4 bit is set,
1443 the client will send no further packets to the server.
1444 The only way at present to recover from this condition is
1445 to restart the protocol at both the client and server.
1447 happens automatically at the client when the association times out.
1448 It will happen at the server only if the server operator cooperates.
1449 @subsubsection Access Control Commands
1451 @item @code{discard} @code{[@code{average} @kbd{avg}]} @code{[@code{minimum} @kbd{min}]} @code{[@code{monitor} @kbd{prob}]}
1452 Set the parameters of the
1454 facility which protects the server from
1458 subcommand specifies the minimum average packet
1461 subcommand specifies the minimum packet spacing.
1462 Packets that violate these minima are discarded
1463 and a kiss-o'-death packet returned if enabled.
1465 minimum average and minimum are 5 and 2, respectively.
1468 subcommand specifies the probability of discard
1469 for packets that overflow the rate-control window.
1470 @item @code{restrict} @code{address} @code{[@code{mask} @kbd{mask}]} @code{[@code{ippeerlimit} @kbd{int}]} @code{[@kbd{flag} @kbd{...}]}
1473 argument expressed in
1474 dotted-quad form is the address of a host or network.
1477 argument can be a valid host DNS name.
1480 argument expressed in dotted-quad form defaults to
1481 @code{255.255.255.255},
1484 is treated as the address of an individual host.
1485 A default entry (address
1489 is always included and is always the first entry in the list.
1490 Note that text string
1492 with no mask option, may
1493 be used to indicate the default entry.
1496 directive limits the number of peer requests for each IP to
1498 where a value of -1 means "unlimited", the current default.
1499 A value of 0 means "none".
1500 There would usually be at most 1 peering request per IP,
1501 but if the remote peering requests are behind a proxy
1502 there could well be more than 1 per IP.
1503 In the current implementation,
1506 restricts access, i.e., an entry with no flags indicates that free
1507 access to the server is to be given.
1508 The flags are not orthogonal,
1509 in that more restrictive flags will often make less restrictive
1511 The flags can generally be classed into two
1512 categories, those which restrict time service and those which
1513 restrict informational queries and attempts to do run-time
1514 reconfiguration of the server.
1515 One or more of the following flags
1519 Deny packets of all kinds, including
1520 @code{ntpq(1ntpqmdoc)}
1522 @code{ntpdc(1ntpdcmdoc)}
1525 If this flag is set when an access violation occurs, a kiss-o'-death
1526 (KoD) packet is sent.
1527 KoD packets are rate limited to no more than one
1529 If another KoD packet occurs within one second after the
1530 last one, the packet is dropped.
1531 @item @code{limited}
1532 Deny service if the packet spacing violates the lower limits specified
1536 A history of clients is kept using the
1537 monitoring capability of
1538 @code{ntpd(1ntpdmdoc)}.
1539 Thus, monitoring is always active as
1540 long as there is a restriction entry with the
1543 @item @code{lowpriotrap}
1544 Declare traps set by matching hosts to be low priority.
1546 number of traps a server can maintain is limited (the current limit
1548 Traps are usually assigned on a first come, first served
1549 basis, with later trap requestors being denied service.
1551 modifies the assignment algorithm by allowing low priority traps to
1552 be overridden by later requests for normal priority traps.
1553 @item @code{noepeer}
1554 Deny ephemeral peer requests,
1555 even if they come from an authenticated source.
1556 Note that the ability to use a symmetric key for authentication may be restricted to
1557 one or more IPs or subnets via the third field of the
1560 This restriction is not enabled by default,
1561 to maintain backward compatability.
1564 to become the default in ntp-4.4.
1565 @item @code{nomodify}
1567 @code{ntpq(1ntpqmdoc)}
1569 @code{ntpdc(1ntpdcmdoc)}
1570 queries which attempt to modify the state of the
1571 server (i.e., run time reconfiguration).
1572 Queries which return
1573 information are permitted.
1574 @item @code{noquery}
1576 @code{ntpq(1ntpqmdoc)}
1578 @code{ntpdc(1ntpdcmdoc)}
1580 Time service is not affected.
1582 Deny unauthenticated packets which would result in mobilizing a new association.
1584 broadcast and symmetric active packets
1585 when a configured association does not exist.
1588 associations, so if you want to use servers from a
1590 directive and also want to use
1592 by default, you'll want a
1593 @code{restrict source ...}
1594 line as well that does
1599 @item @code{noserve}
1600 Deny all packets except
1601 @code{ntpq(1ntpqmdoc)}
1603 @code{ntpdc(1ntpdcmdoc)}
1606 Decline to provide mode 6 control message trap service to matching
1608 The trap service is a subsystem of the
1609 @code{ntpq(1ntpqmdoc)}
1611 protocol which is intended for use by remote event logging programs.
1612 @item @code{notrust}
1613 Deny service unless the packet is cryptographically authenticated.
1614 @item @code{ntpport}
1615 This is actually a match algorithm modifier, rather than a
1617 Its presence causes the restriction entry to be
1618 matched only if the source port in the packet is the standard NTP
1628 is considered more specific and
1629 is sorted later in the list.
1630 @item @code{serverresponse fuzz}
1631 When reponding to server requests,
1632 fuzz the low order bits of the
1634 @item @code{version}
1635 Deny packets that do not match the current NTP version.
1638 Default restriction list entries with the flags ignore, interface,
1639 ntpport, for each of the local host's interface addresses are
1640 inserted into the table at startup to prevent the server
1641 from attempting to synchronize to its own time.
1642 A default entry is also always present, though if it is
1643 otherwise unconfigured; no flags are associated
1644 with the default entry (i.e., everything besides your own
1645 NTP server is unrestricted).
1647 @node Automatic NTP Configuration Options
1648 @subsection Automatic NTP Configuration Options
1649 @subsubsection Manycasting
1650 Manycasting is a automatic discovery and configuration paradigm
1652 It is intended as a means for a multicast client
1653 to troll the nearby network neighborhood to find cooperating
1654 manycast servers, validate them using cryptographic means
1655 and evaluate their time values with respect to other servers
1656 that might be lurking in the vicinity.
1657 The intended result is that each manycast client mobilizes
1658 client associations with some number of the "best"
1659 of the nearby manycast servers, yet automatically reconfigures
1660 to sustain this number of servers should one or another fail.
1662 Note that the manycasting paradigm does not coincide
1663 with the anycast paradigm described in RFC-1546,
1664 which is designed to find a single server from a clique
1665 of servers providing the same service.
1666 The manycast paradigm is designed to find a plurality
1667 of redundant servers satisfying defined optimality criteria.
1669 Manycasting can be used with either symmetric key
1670 or public key cryptography.
1671 The public key infrastructure (PKI)
1672 offers the best protection against compromised keys
1673 and is generally considered stronger, at least with relatively
1675 It is implemented using the Autokey protocol and
1676 the OpenSSL cryptographic library available from
1677 @code{http://www.openssl.org/}.
1678 The library can also be used with other NTPv4 modes
1679 as well and is highly recommended, especially for broadcast modes.
1681 A persistent manycast client association is configured
1683 @code{manycastclient}
1684 command, which is similar to the
1686 command but with a multicast (IPv4 class
1691 The IANA has designated IPv4 address 224.1.1.1
1692 and IPv6 address FF05::101 (site local) for NTP.
1693 When more servers are needed, it broadcasts manycast
1694 client messages to this address at the minimum feasible rate
1695 and minimum feasible time-to-live (TTL) hops, depending
1696 on how many servers have already been found.
1697 There can be as many manycast client associations
1698 as different group address, each one serving as a template
1699 for a future ephemeral unicast client/server association.
1701 Manycast servers configured with the
1702 @code{manycastserver}
1703 command listen on the specified group address for manycast
1705 Note the distinction between manycast client,
1706 which actively broadcasts messages, and manycast server,
1707 which passively responds to them.
1708 If a manycast server is
1709 in scope of the current TTL and is itself synchronized
1710 to a valid source and operating at a stratum level equal
1711 to or lower than the manycast client, it replies to the
1712 manycast client message with an ordinary unicast server message.
1714 The manycast client receiving this message mobilizes
1715 an ephemeral client/server association according to the
1716 matching manycast client template, but only if cryptographically
1717 authenticated and the server stratum is less than or equal
1718 to the client stratum.
1719 Authentication is explicitly required
1720 and either symmetric key or public key (Autokey) can be used.
1721 Then, the client polls the server at its unicast address
1722 in burst mode in order to reliably set the host clock
1723 and validate the source.
1724 This normally results
1725 in a volley of eight client/server at 2-s intervals
1726 during which both the synchronization and cryptographic
1727 protocols run concurrently.
1728 Following the volley,
1729 the client runs the NTP intersection and clustering
1730 algorithms, which act to discard all but the "best"
1731 associations according to stratum and synchronization
1733 The surviving associations then continue
1734 in ordinary client/server mode.
1736 The manycast client polling strategy is designed to reduce
1737 as much as possible the volume of manycast client messages
1738 and the effects of implosion due to near-simultaneous
1739 arrival of manycast server messages.
1740 The strategy is determined by the
1741 @code{manycastclient},
1745 configuration commands.
1746 The manycast poll interval is
1747 normally eight times the system poll interval,
1748 which starts out at the
1750 value specified in the
1751 @code{manycastclient},
1752 command and, under normal circumstances, increments to the
1754 value specified in this command.
1755 Initially, the TTL is
1756 set at the minimum hops specified by the
1759 At each retransmission the TTL is increased until reaching
1760 the maximum hops specified by this command or a sufficient
1761 number client associations have been found.
1762 Further retransmissions use the same TTL.
1764 The quality and reliability of the suite of associations
1765 discovered by the manycast client is determined by the NTP
1766 mitigation algorithms and the
1770 values specified in the
1772 configuration command.
1775 candidate servers must be available and the mitigation
1776 algorithms produce at least
1778 survivors in order to synchronize the clock.
1779 Byzantine agreement principles require at least four
1780 candidates in order to correctly discard a single falseticker.
1781 For legacy purposes,
1786 For manycast service
1788 should be explicitly set to 4, assuming at least that
1789 number of servers are available.
1793 servers are found, the manycast poll interval is immediately
1798 servers are found when the TTL has reached the maximum hops,
1799 the manycast poll interval is doubled.
1800 For each transmission
1801 after that, the poll interval is doubled again until
1802 reaching the maximum of eight times
1804 Further transmissions use the same poll interval and
1806 Note that while all this is going on,
1807 each client/server association found is operating normally
1808 it the system poll interval.
1810 Administratively scoped multicast boundaries are normally
1811 specified by the network router configuration and,
1812 in the case of IPv6, the link/site scope prefix.
1813 By default, the increment for TTL hops is 32 starting
1814 from 31; however, the
1816 configuration command can be
1817 used to modify the values to match the scope rules.
1819 It is often useful to narrow the range of acceptable
1820 servers which can be found by manycast client associations.
1821 Because manycast servers respond only when the client
1822 stratum is equal to or greater than the server stratum,
1823 primary (stratum 1) servers fill find only primary servers
1824 in TTL range, which is probably the most common objective.
1825 However, unless configured otherwise, all manycast clients
1826 in TTL range will eventually find all primary servers
1827 in TTL range, which is probably not the most common
1828 objective in large networks.
1831 command can be used to modify this behavior.
1832 Servers with stratum below
1838 command are strongly discouraged during the selection
1839 process; however, these servers may be temporally
1840 accepted if the number of servers within TTL range is
1844 The above actions occur for each manycast client message,
1845 which repeats at the designated poll interval.
1846 However, once the ephemeral client association is mobilized,
1847 subsequent manycast server replies are discarded,
1848 since that would result in a duplicate association.
1849 If during a poll interval the number of client associations
1852 all manycast client prototype associations are reset
1853 to the initial poll interval and TTL hops and operation
1854 resumes from the beginning.
1855 It is important to avoid
1856 frequent manycast client messages, since each one requires
1857 all manycast servers in TTL range to respond.
1858 The result could well be an implosion, either minor or major,
1859 depending on the number of servers in range.
1860 The recommended value for
1864 It is possible and frequently useful to configure a host
1865 as both manycast client and manycast server.
1866 A number of hosts configured this way and sharing a common
1867 group address will automatically organize themselves
1868 in an optimum configuration based on stratum and
1869 synchronization distance.
1870 For example, consider an NTP
1871 subnet of two primary servers and a hundred or more
1873 With two exceptions, all servers
1874 and clients have identical configuration files including both
1875 @code{multicastclient}
1877 @code{multicastserver}
1878 commands using, for instance, multicast group address
1880 The only exception is that each primary server
1881 configuration file must include commands for the primary
1882 reference source such as a GPS receiver.
1884 The remaining configuration files for all secondary
1885 servers and clients have the same contents, except for the
1887 command, which is specific for each stratum level.
1888 For stratum 1 and stratum 2 servers, that command is
1890 For stratum 3 and above servers the
1892 value is set to the intended stratum number.
1893 Thus, all stratum 3 configuration files are identical,
1894 all stratum 4 files are identical and so forth.
1896 Once operations have stabilized in this scenario,
1897 the primary servers will find the primary reference source
1898 and each other, since they both operate at the same
1899 stratum (1), but not with any secondary server or client,
1900 since these operate at a higher stratum.
1902 servers will find the servers at the same stratum level.
1903 If one of the primary servers loses its GPS receiver,
1904 it will continue to operate as a client and other clients
1905 will time out the corresponding association and
1906 re-associate accordingly.
1908 Some administrators prefer to avoid running
1909 @code{ntpd(1ntpdmdoc)}
1910 continuously and run either
1911 @code{sntp(1sntpmdoc)}
1913 @code{ntpd(1ntpdmdoc)}
1916 In either case the servers must be
1917 configured in advance and the program fails if none are
1918 available when the cron job runs.
1920 application of manycast is with
1921 @code{ntpd(1ntpdmdoc)}
1923 The program wakes up, scans the local landscape looking
1924 for the usual suspects, selects the best from among
1925 the rascals, sets the clock and then departs.
1926 Servers do not have to be configured in advance and
1927 all clients throughout the network can have the same
1929 @subsubsection Manycast Interactions with Autokey
1930 Each time a manycast client sends a client mode packet
1931 to a multicast group address, all manycast servers
1932 in scope generate a reply including the host name
1934 The manycast clients then run
1935 the Autokey protocol, which collects and verifies
1936 all certificates involved.
1937 Following the burst interval
1938 all but three survivors are cast off,
1939 but the certificates remain in the local cache.
1940 It often happens that several complete signing trails
1941 from the client to the primary servers are collected in this way.
1943 About once an hour or less often if the poll interval
1944 exceeds this, the client regenerates the Autokey key list.
1945 This is in general transparent in client/server mode.
1946 However, about once per day the server private value
1947 used to generate cookies is refreshed along with all
1948 manycast client associations.
1950 cryptographic values including certificates is refreshed.
1951 If a new certificate has been generated since
1952 the last refresh epoch, it will automatically revoke
1953 all prior certificates that happen to be in the
1955 At the same time, the manycast
1956 scheme starts all over from the beginning and
1957 the expanding ring shrinks to the minimum and increments
1958 from there while collecting all servers in scope.
1959 @subsubsection Broadcast Options
1961 @item @code{tos} @code{[@code{bcpollbstep} @kbd{gate}]}
1962 This command provides a way to delay,
1963 by the specified number of broadcast poll intervals,
1964 believing backward time steps from a broadcast server.
1965 Broadcast time networks are expected to be trusted.
1966 In the event a broadcast server's time is stepped backwards,
1967 there is clear benefit to having the clients notice this change
1968 as soon as possible.
1969 Attacks such as replay attacks can happen, however,
1970 and even though there are a number of protections built in to
1971 broadcast mode, attempts to perform a replay attack are possible.
1972 This value defaults to 0, but can be changed
1973 to any number of poll intervals between 0 and 4.
1975 @subsubsection Manycast Options
1977 @item @code{tos} @code{[@code{ceiling} @kbd{ceiling} | @code{cohort} @code{@{} @code{0} | @code{1} @code{@}} | @code{floor} @kbd{floor} | @code{minclock} @kbd{minclock} | @code{minsane} @kbd{minsane}]}
1978 This command affects the clock selection and clustering
1980 It can be used to select the quality and
1981 quantity of peers used to synchronize the system clock
1982 and is most useful in manycast mode.
1983 The variables operate
1986 @item @code{ceiling} @kbd{ceiling}
1987 Peers with strata above
1989 will be discarded if there are at least
1992 This value defaults to 15, but can be changed
1993 to any number from 1 to 15.
1994 @item @code{cohort} @code{@{0 | 1@}}
1995 This is a binary flag which enables (0) or disables (1)
1996 manycast server replies to manycast clients with the same
1998 This is useful to reduce implosions where
1999 large numbers of clients with the same stratum level
2001 The default is to enable these replies.
2002 @item @code{floor} @kbd{floor}
2003 Peers with strata below
2005 will be discarded if there are at least
2008 This value defaults to 1, but can be changed
2009 to any number from 1 to 15.
2010 @item @code{minclock} @kbd{minclock}
2011 The clustering algorithm repeatedly casts out outlier
2012 associations until no more than
2014 associations remain.
2015 This value defaults to 3,
2016 but can be changed to any number from 1 to the number of
2018 @item @code{minsane} @kbd{minsane}
2019 This is the minimum number of candidates available
2020 to the clock selection algorithm in order to produce
2021 one or more truechimers for the clustering algorithm.
2022 If fewer than this number are available, the clock is
2023 undisciplined and allowed to run free.
2025 for legacy purposes.
2026 However, according to principles of
2027 Byzantine agreement,
2029 should be at least 4 in order to detect and discard
2030 a single falseticker.
2032 @item @code{ttl} @kbd{hop} @kbd{...}
2033 This command specifies a list of TTL values in increasing
2034 order, up to 8 values can be specified.
2035 In manycast mode these values are used in turn
2036 in an expanding-ring search.
2037 The default is eight
2038 multiples of 32 starting at 31.
2040 @node Reference Clock Support
2041 @subsection Reference Clock Support
2042 The NTP Version 4 daemon supports some three dozen different radio,
2043 satellite and modem reference clocks plus a special pseudo-clock
2044 used for backup or when no other clock source is available.
2045 Detailed descriptions of individual device drivers and options can
2047 "Reference Clock Drivers"
2049 (available as part of the HTML documentation
2051 @file{/usr/share/doc/ntp}).
2052 Additional information can be found in the pages linked
2053 there, including the
2054 "Debugging Hints for Reference Clock Drivers"
2056 "How To Write a Reference Clock Driver"
2058 (available as part of the HTML documentation
2060 @file{/usr/share/doc/ntp}).
2061 In addition, support for a PPS
2062 signal is available as described in the
2063 "Pulse-per-second (PPS) Signal Interfacing"
2065 (available as part of the HTML documentation
2067 @file{/usr/share/doc/ntp}).
2069 drivers support special line discipline/streams modules which can
2070 significantly improve the accuracy using the driver.
2073 "Line Disciplines and Streams Drivers"
2075 (available as part of the HTML documentation
2077 @file{/usr/share/doc/ntp}).
2079 A reference clock will generally (though not always) be a radio
2080 timecode receiver which is synchronized to a source of standard
2081 time such as the services offered by the NRC in Canada and NIST and
2083 The interface between the computer and the timecode
2084 receiver is device dependent, but is usually a serial port.
2086 device driver specific to each reference clock must be selected and
2087 compiled in the distribution; however, most common radio, satellite
2088 and modem clocks are included by default.
2089 Note that an attempt to
2090 configure a reference clock when the driver has not been compiled
2091 or the hardware port has not been appropriately configured results
2092 in a scalding remark to the system log file, but is otherwise non
2095 For the purposes of configuration,
2096 @code{ntpd(1ntpdmdoc)}
2098 reference clocks in a manner analogous to normal NTP peers as much
2100 Reference clocks are identified by a syntactically
2101 correct but invalid IP address, in order to distinguish them from
2103 Reference clock addresses are of the form
2104 @code{127.127.}@kbd{t}.@kbd{u},
2108 denoting the clock type and
2111 number in the range 0-3.
2112 While it may seem overkill, it is in fact
2113 sometimes useful to configure multiple reference clocks of the same
2114 type, in which case the unit numbers must be unique.
2118 command is used to configure a reference
2121 argument in that command
2122 is the clock address.
2128 options are not used for reference clock support.
2131 option is added for reference clock support, as
2135 option can be useful to
2136 persuade the server to cherish a reference clock with somewhat more
2137 enthusiasm than other reference clocks or peers.
2139 information on this option can be found in the
2140 "Mitigation Rules and the prefer Keyword"
2141 (available as part of the HTML documentation
2143 @file{/usr/share/doc/ntp})
2150 meaning only for selected clock drivers.
2151 See the individual clock
2152 driver document pages for additional information.
2156 command is used to provide additional
2157 information for individual clock drivers and normally follows
2158 immediately after the
2163 argument specifies the clock address.
2168 options can be used to
2169 override the defaults for the device.
2170 There are two optional
2171 device-dependent time offsets and four flags that can be included
2176 The stratum number of a reference clock is by default zero.
2178 @code{ntpd(1ntpdmdoc)}
2179 daemon adds one to the stratum of each
2180 peer, a primary server ordinarily displays an external stratum of
2182 In order to provide engineered backups, it is often useful to
2183 specify the reference clock stratum as greater than zero.
2186 option is used for this purpose.
2188 involving both a reference clock and a pulse-per-second (PPS)
2189 discipline signal, it is useful to specify the reference clock
2190 identifier as other than the default, depending on the driver.
2193 option is used for this purpose.
2195 these options apply to all clock drivers.
2196 @subsubsection Reference Clock Commands
2198 @item @code{server} @code{127.127.}@kbd{t}.@kbd{u} @code{[@code{prefer}]} @code{[@code{mode} @kbd{int}]} @code{[@code{minpoll} @kbd{int}]} @code{[@code{maxpoll} @kbd{int}]}
2199 This command can be used to configure reference clocks in
2201 The options are interpreted as follows:
2204 Marks the reference clock as preferred.
2205 All other things being
2206 equal, this host will be chosen for synchronization among a set of
2207 correctly operating hosts.
2209 "Mitigation Rules and the prefer Keyword"
2211 (available as part of the HTML documentation
2213 @file{/usr/share/doc/ntp})
2214 for further information.
2215 @item @code{mode} @kbd{int}
2216 Specifies a mode number which is interpreted in a
2217 device-specific fashion.
2218 For instance, it selects a dialing
2219 protocol in the ACTS driver and a device subtype in the
2222 @item @code{minpoll} @kbd{int}
2223 @item @code{maxpoll} @kbd{int}
2224 These options specify the minimum and maximum polling interval
2225 for reference clock messages, as a power of 2 in seconds
2227 most directly connected reference clocks, both
2231 default to 6 (64 s).
2232 For modem reference clocks,
2234 defaults to 10 (17.1 m) and
2236 defaults to 14 (4.5 h).
2237 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2239 @item @code{fudge} @code{127.127.}@kbd{t}.@kbd{u} @code{[@code{time1} @kbd{sec}]} @code{[@code{time2} @kbd{sec}]} @code{[@code{stratum} @kbd{int}]} @code{[@code{refid} @kbd{string}]} @code{[@code{mode} @kbd{int}]} @code{[@code{flag1} @code{0} @code{|} @code{1}]} @code{[@code{flag2} @code{0} @code{|} @code{1}]} @code{[@code{flag3} @code{0} @code{|} @code{1}]} @code{[@code{flag4} @code{0} @code{|} @code{1}]}
2240 This command can be used to configure reference clocks in
2242 It must immediately follow the
2244 command which configures the driver.
2245 Note that the same capability
2246 is possible at run time using the
2247 @code{ntpdc(1ntpdcmdoc)}
2249 The options are interpreted as
2252 @item @code{time1} @kbd{sec}
2253 Specifies a constant to be added to the time offset produced by
2254 the driver, a fixed-point decimal number in seconds.
2256 as a calibration constant to adjust the nominal time offset of a
2257 particular clock to agree with an external standard, such as a
2258 precision PPS signal.
2259 It also provides a way to correct a
2260 systematic error or bias due to serial port or operating system
2261 latencies, different cable lengths or receiver internal delay.
2263 specified offset is in addition to the propagation delay provided
2264 by other means, such as internal DIPswitches.
2266 for an individual system and driver is available, an approximate
2267 correction is noted in the driver documentation pages.
2268 Note: in order to facilitate calibration when more than one
2269 radio clock or PPS signal is supported, a special calibration
2270 feature is available.
2271 It takes the form of an argument to the
2273 command described in
2274 @ref{Miscellaneous Options}
2275 page and operates as described in the
2276 "Reference Clock Drivers"
2278 (available as part of the HTML documentation
2280 @file{/usr/share/doc/ntp}).
2281 @item @code{time2} @kbd{secs}
2282 Specifies a fixed-point decimal number in seconds, which is
2283 interpreted in a driver-dependent way.
2284 See the descriptions of
2285 specific drivers in the
2286 "Reference Clock Drivers"
2288 (available as part of the HTML documentation
2290 @file{/usr/share/doc/ntp} @file{).}
2291 @item @code{stratum} @kbd{int}
2292 Specifies the stratum number assigned to the driver, an integer
2294 This number overrides the default stratum number
2295 ordinarily assigned by the driver itself, usually zero.
2296 @item @code{refid} @kbd{string}
2297 Specifies an ASCII string of from one to four characters which
2298 defines the reference identifier used by the driver.
2300 overrides the default identifier ordinarily assigned by the driver
2302 @item @code{mode} @kbd{int}
2303 Specifies a mode number which is interpreted in a
2304 device-specific fashion.
2305 For instance, it selects a dialing
2306 protocol in the ACTS driver and a device subtype in the
2309 @item @code{flag1} @code{0} @code{|} @code{1}
2310 @item @code{flag2} @code{0} @code{|} @code{1}
2311 @item @code{flag3} @code{0} @code{|} @code{1}
2312 @item @code{flag4} @code{0} @code{|} @code{1}
2313 These four flags are used for customizing the clock driver.
2315 interpretation of these values, and whether they are used at all,
2316 is a function of the particular clock driver.
2320 is used to enable recording monitoring
2323 file configured with the
2326 Further information on the
2328 command can be found in
2329 @ref{Monitoring Options}.
2332 @node Miscellaneous Options
2333 @subsection Miscellaneous Options
2335 @item @code{broadcastdelay} @kbd{seconds}
2336 The broadcast and multicast modes require a special calibration
2337 to determine the network delay between the local and remote
2339 Ordinarily, this is done automatically by the initial
2340 protocol exchanges between the client and server.
2342 the calibration procedure may fail due to network or server access
2343 controls, for example.
2344 This command specifies the default delay to
2345 be used under these circumstances.
2346 Typically (for Ethernet), a
2347 number between 0.003 and 0.007 seconds is appropriate.
2349 when this command is not used is 0.004 seconds.
2350 @item @code{calldelay} @kbd{delay}
2351 This option controls the delay in seconds between the first and second
2352 packets sent in burst or iburst mode to allow additional time for a modem
2353 or ISDN call to complete.
2354 @item @code{driftfile} @kbd{driftfile}
2355 This command specifies the complete path and name of the file used to
2356 record the frequency of the local clock oscillator.
2360 command line option.
2361 If the file exists, it is read at
2362 startup in order to set the initial frequency and then updated once per
2363 hour with the current frequency computed by the daemon.
2365 specified, but the file itself does not exist, the starts with an initial
2366 frequency of zero and creates the file when writing it for the first time.
2367 If this command is not given, the daemon will always start with an initial
2370 The file format consists of a single line containing a single
2371 floating point number, which records the frequency offset measured
2372 in parts-per-million (PPM).
2373 The file is updated by first writing
2374 the current drift value into a temporary file and then renaming
2375 this file to replace the old version.
2377 @code{ntpd(1ntpdmdoc)}
2378 must have write permission for the directory the
2379 drift file is located in, and that file system links, symbolic or
2380 otherwise, should be avoided.
2381 @item @code{dscp} @kbd{value}
2382 This option specifies the Differentiated Services Control Point (DSCP) value,
2384 The default value is 46, signifying Expedited Forwarding.
2385 @item @code{enable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats} | @code{peer_clear_digest_early} | @code{unpeer_crypto_early} | @code{unpeer_crypto_nak_early} | @code{unpeer_digest_early}]}
2386 @item @code{disable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats} | @code{peer_clear_digest_early} | @code{unpeer_crypto_early} | @code{unpeer_crypto_nak_early} | @code{unpeer_digest_early}]}
2387 Provides a way to enable or disable various server options.
2388 Flags not mentioned are unaffected.
2389 Note that all of these flags
2390 can be controlled remotely using the
2391 @code{ntpdc(1ntpdcmdoc)}
2395 Enables the server to synchronize with unconfigured peers only if the
2396 peer has been correctly authenticated using either public key or
2397 private key cryptography.
2398 The default for this flag is
2400 @item @code{bclient}
2401 Enables the server to listen for a message from a broadcast or
2402 multicast server, as in the
2403 @code{multicastclient}
2404 command with default
2406 The default for this flag is
2408 @item @code{calibrate}
2409 Enables the calibrate feature for reference clocks.
2414 Enables the kernel time discipline, if available.
2415 The default for this
2418 if support is available, otherwise
2421 Enables processing of NTP mode 7 implementation-specific requests
2422 which are used by the deprecated
2423 @code{ntpdc(1ntpdcmdoc)}
2425 The default for this flag is disable.
2426 This flag is excluded from runtime configuration using
2427 @code{ntpq(1ntpqmdoc)}.
2429 @code{ntpq(1ntpqmdoc)}
2430 program provides the same capabilities as
2431 @code{ntpdc(1ntpdcmdoc)}
2432 using standard mode 6 requests.
2433 @item @code{monitor}
2434 Enables the monitoring facility.
2436 @code{ntpdc(1ntpdcmdoc)}
2440 command or further information.
2442 default for this flag is
2445 Enables time and frequency discipline.
2446 In effect, this switch opens and
2447 closes the feedback loop, which is useful for testing.
2451 @item @code{peer_clear_digest_early}
2453 @code{ntpd(1ntpdmdoc)}
2454 is using autokey and it
2455 receives a crypto-NAK packet that
2456 passes the duplicate packet and origin timestamp checks
2457 the peer variables are immediately cleared.
2458 While this is generally a feature
2459 as it allows for quick recovery if a server key has changed,
2460 a properly forged and appropriately delivered crypto-NAK packet
2461 can be used in a DoS attack.
2462 If you have active noticable problems with this type of DoS attack
2463 then you should consider
2464 disabling this option.
2467 file for evidence of any of these attacks.
2469 default for this flag is
2472 Enables the statistics facility.
2474 @ref{Monitoring Options}
2475 section for further information.
2476 The default for this flag is
2478 @item @code{unpeer_crypto_early}
2480 @code{ntpd(1ntpdmdoc)}
2481 receives an autokey packet that fails TEST9,
2483 the association is immediately cleared.
2484 This is almost certainly a feature,
2485 but if, in spite of the current recommendation of not using autokey,
2490 you are seeing this sort of DoS attack
2491 disabling this flag will delay
2492 tearing down the association until the reachability counter
2496 file for evidence of any of these attacks.
2498 default for this flag is
2500 @item @code{unpeer_crypto_nak_early}
2502 @code{ntpd(1ntpdmdoc)}
2503 receives a crypto-NAK packet that
2504 passes the duplicate packet and origin timestamp checks
2505 the association is immediately cleared.
2506 While this is generally a feature
2507 as it allows for quick recovery if a server key has changed,
2508 a properly forged and appropriately delivered crypto-NAK packet
2509 can be used in a DoS attack.
2510 If you have active noticable problems with this type of DoS attack
2511 then you should consider
2512 disabling this option.
2515 file for evidence of any of these attacks.
2517 default for this flag is
2519 @item @code{unpeer_digest_early}
2521 @code{ntpd(1ntpdmdoc)}
2522 receives what should be an authenticated packet
2523 that passes other packet sanity checks but
2524 contains an invalid digest
2525 the association is immediately cleared.
2526 While this is generally a feature
2527 as it allows for quick recovery,
2528 if this type of packet is carefully forged and sent
2529 during an appropriate window it can be used for a DoS attack.
2530 If you have active noticable problems with this type of DoS attack
2531 then you should consider
2532 disabling this option.
2535 file for evidence of any of these attacks.
2537 default for this flag is
2540 @item @code{includefile} @kbd{includefile}
2541 This command allows additional configuration commands
2542 to be included from a separate file.
2544 be nested to a depth of five; upon reaching the end of any
2545 include file, command processing resumes in the previous
2547 This option is useful for sites that run
2548 @code{ntpd(1ntpdmdoc)}
2549 on multiple hosts, with (mostly) common options (e.g., a
2551 @item @code{interface} @code{[@code{listen} | @code{ignore} | @code{drop}]} @code{[@code{all} | @code{ipv4} | @code{ipv6} | @code{wildcard} @kbd{name} | @kbd{address} @code{[@code{/} @kbd{prefixlen}]}]}
2554 directive controls which network addresses
2555 @code{ntpd(1ntpdmdoc)}
2556 opens, and whether input is dropped without processing.
2557 The first parameter determines the action for addresses
2558 which match the second parameter.
2559 The second parameter specifies a class of addresses,
2560 or a specific interface name,
2562 In the address case,
2564 determines how many bits must match for this rule to apply.
2566 prevents opening matching addresses,
2569 @code{ntpd(1ntpdmdoc)}
2570 to open the address and drop all received packets without examination.
2573 directives can be used.
2574 The last rule which matches a particular address determines the action for it.
2576 directives are disabled if any
2581 @code{--novirtualips}
2582 command-line options are specified in the configuration file,
2583 all available network addresses are opened.
2586 directive is an alias for
2588 @item @code{leapfile} @kbd{leapfile}
2589 This command loads the IERS leapseconds file and initializes the
2590 leapsecond values for the next leapsecond event, leapfile expiration
2591 time, and TAI offset.
2592 The file can be obtained directly from the IERS at
2593 @code{https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list}
2595 @code{ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list}.
2599 @code{ntpd(1ntpdmdoc)}
2601 @code{leapfile} @code{directive} @code{or} @code{when}
2602 @code{ntpd} @code{detects} @code{that} @code{the}
2606 checks once a day to see if the
2610 @code{update-leap(1update_leapmdoc)}
2611 script can be run to see if the
2614 @item @code{leapsmearinterval} @kbd{seconds}
2615 This EXPERIMENTAL option is only available if
2616 @code{ntpd(1ntpdmdoc)}
2618 @code{--enable-leap-smear}
2622 It specifies the interval over which a leap second correction will be applied.
2623 Recommended values for this option are between
2624 7200 (2 hours) and 86400 (24 hours).
2625 .Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!
2626 See http://bugs.ntp.org/2855 for more information.
2627 @item @code{logconfig} @kbd{configkeyword}
2628 This command controls the amount and type of output written to
2631 facility or the alternate
2634 By default, all output is turned on.
2637 keywords can be prefixed with
2638 @quoteleft{}=@quoteright{},
2639 @quoteleft{}+@quoteright{}
2641 @quoteleft{}-@quoteright{},
2643 @quoteleft{}=@quoteright{}
2647 @quoteleft{}+@quoteright{}
2649 @quoteleft{}-@quoteright{}
2653 messages can be controlled in four
2655 (@code{clock}, @code{peer}, @code{sys} and @code{sync}).
2656 Within these classes four types of messages can be
2657 controlled: informational messages
2667 Configuration keywords are formed by concatenating the message class with
2671 prefix can be used instead of a message class.
2673 message class may also be followed by the
2675 keyword to enable/disable all
2676 messages of the respective message class.
2677 Thus, a minimal log configuration
2678 could look like this:
2680 logconfig =syncstatus +sysevents
2683 This would just list the synchronizations state of
2684 @code{ntpd(1ntpdmdoc)}
2685 and the major system events.
2686 For a simple reference server, the
2687 following minimum message configuration could be useful:
2689 logconfig =syncall +clockall
2692 This configuration will list all clock information and
2693 synchronization information.
2694 All other events and messages about
2695 peers, system events and so on is suppressed.
2696 @item @code{logfile} @kbd{logfile}
2697 This command specifies the location of an alternate log file to
2698 be used instead of the default system
2701 This is the same operation as the
2703 command line option.
2704 @item @code{mru} @code{[@code{maxdepth} @kbd{count} | @code{maxmem} @kbd{kilobytes} | @code{mindepth} @kbd{count} | @code{maxage} @kbd{seconds} | @code{initialloc} @kbd{count} | @code{initmem} @kbd{kilobytes} | @code{incalloc} @kbd{count} | @code{incmem} @kbd{kilobytes}]}
2705 Controls size limite of the monitoring facility's Most Recently Used
2707 of client addresses, which is also used by the
2708 rate control facility.
2710 @item @code{maxdepth} @kbd{count}
2711 @item @code{maxmem} @kbd{kilobytes}
2712 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2713 The acutal limit will be up to
2720 options offered in units of entries or kilobytes, if both
2723 @code{maxmem} @code{are} @code{used,} @code{the} @code{last} @code{one} @code{used} @code{controls.}
2724 The default is 1024 kilobytes.
2725 @item @code{mindepth} @kbd{count}
2726 Lower limit on the MRU list size.
2727 When the MRU list has fewer than
2729 entries, existing entries are never removed to make room for newer ones,
2730 regardless of their age.
2731 The default is 600 entries.
2732 @item @code{maxage} @kbd{seconds}
2733 Once the MRU list has
2735 entries and an additional client is to ba added to the list,
2736 if the oldest entry was updated more than
2738 seconds ago, that entry is removed and its storage is reused.
2739 If the oldest entry was updated more recently the MRU list is grown,
2741 @code{maxdepth} @code{/} @code{moxmem}.
2742 The default is 64 seconds.
2743 @item @code{initalloc} @kbd{count}
2744 @item @code{initmem} @kbd{kilobytes}
2745 Initial memory allocation at the time the monitoringfacility is first enabled,
2746 in terms of the number of entries or kilobytes.
2747 The default is 4 kilobytes.
2748 @item @code{incalloc} @kbd{count}
2749 @item @code{incmem} @kbd{kilobytes}
2750 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2751 The default is 4 kilobytes.
2753 @item @code{nonvolatile} @kbd{threshold}
2756 delta in seconds before an hourly change to the
2758 (frequency file) will be written, with a default value of 1e-7 (0.1 PPM).
2759 The frequency file is inspected each hour.
2760 If the difference between the current frequency and the last value written
2761 exceeds the threshold, the file is written and the
2763 becomes the new threshold value.
2764 If the threshold is not exceeeded, it is reduced by half.
2765 This is intended to reduce the number of file writes
2766 for embedded systems with nonvolatile memory.
2767 @item @code{phone} @kbd{dial} @kbd{...}
2768 This command is used in conjunction with
2769 the ACTS modem driver (type 18)
2770 or the JJY driver (type 40, mode 100 - 180).
2771 For the ACTS modem driver (type 18), the arguments consist of
2772 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2774 For the JJY driver (type 40 mode 100 - 180), the argument is
2775 one telephone number used to dial the telephone JJY service.
2776 The Hayes command ATDT is normally prepended to the number.
2777 The number can contain other modem control codes as well.
2778 @item @code{pollskewlist} @code{[@kbd{poll} @kbd{value} | @kbd{value}]} @kbd{...} @code{[@code{default} @kbd{value} | @kbd{value}]}
2779 Enable skewing of our poll requests to our servers.
2781 is a number between 3 and 17 inclusive, identifying a specific poll interval.
2782 A poll interval is 2^n seconds in duration,
2783 so a poll value of 3 corresponds to 8 seconds
2785 a poll interval of 17 corresponds to
2786 131,072 seconds, or about a day and a half.
2787 The next two numbers must be between 0 and one-half of the poll interval,
2789 The first number specifies how early the poll may start,
2791 the second number specifies how late the poll may be delayed.
2792 With no arguments, internally specified default values are chosen.
2793 @item @code{reset} @code{[@code{allpeers}]} @code{[@code{auth}]} @code{[@code{ctl}]} @code{[@code{io}]} @code{[@code{mem}]} @code{[@code{sys}]} @code{[@code{timer}]}
2794 Reset one or more groups of counters maintained by
2800 @item @code{rlimit} @code{[@code{memlock} @kbd{Nmegabytes} | @code{stacksize} @kbd{N4kPages} @code{filenum} @kbd{Nfiledescriptors}]}
2802 @item @code{memlock} @kbd{Nmegabytes}
2803 Specify the number of megabytes of memory that should be
2804 allocated and locked.
2805 Probably only available under Linux, this option may be useful
2806 when dropping root (the
2809 The default is 32 megabytes on non-Linux machines, and -1 under Linux.
2810 -1 means "do not lock the process into memory".
2811 0 means "lock whatever memory the process wants into memory".
2812 @item @code{stacksize} @kbd{N4kPages}
2813 Specifies the maximum size of the process stack on systems with the
2816 Defaults to 50 4k pages (200 4k pages in OpenBSD).
2817 @item @code{filenum} @kbd{Nfiledescriptors}
2818 Specifies the maximum number of file descriptors ntpd may have open at once.
2819 Defaults to the system default.
2821 @item @code{saveconfigdir} @kbd{directory_path}
2822 Specify the directory in which to write configuration snapshots
2828 @code{saveconfigdir}
2829 does not appear in the configuration file,
2831 requests are rejected by
2833 @item @code{saveconfig} @kbd{filename}
2834 Write the current configuration, including any runtime
2835 modifications given with
2838 @code{config-from-file}
2844 @code{saveconfigdir}.
2845 This command will be rejected unless the
2846 @code{saveconfigdir}
2847 directive appears in
2853 format directives to substitute the current date and time,
2855 @code{saveconfig\ ntp-%Y%m%d-%H%M%S.conf}.
2856 The filename used is stored in the system variable
2858 Authentication is required.
2859 @item @code{setvar} @kbd{variable} @code{[@code{default}]}
2860 This command adds an additional system variable.
2862 variables can be used to distribute additional information such as
2864 If the variable of the form
2865 @code{name}@code{=}@kbd{value}
2869 variable will be listed as part of the default system variables
2870 (@code{rv} command)).
2871 These additional variables serve
2872 informational purposes only.
2873 They are not related to the protocol
2874 other that they can be listed.
2875 The known protocol variables will
2876 always override any variables defined via the
2879 There are three special variables that contain the names
2880 of all variable of the same group.
2884 the names of all system variables.
2886 @code{peer_var_list}
2888 the names of all peer variables and the
2889 @code{clock_var_list}
2890 holds the names of the reference clock variables.
2891 @item @code{sysinfo}
2892 Display operational summary.
2893 @item @code{sysstats}
2894 Show statistics counters maintained in the protocol module.
2895 @item @code{tinker} @code{[@code{allan} @kbd{allan} | @code{dispersion} @kbd{dispersion} | @code{freq} @kbd{freq} | @code{huffpuff} @kbd{huffpuff} | @code{panic} @kbd{panic} | @code{step} @kbd{step} | @code{stepback} @kbd{stepback} | @code{stepfwd} @kbd{stepfwd} | @code{stepout} @kbd{stepout}]}
2896 This command can be used to alter several system variables in
2897 very exceptional circumstances.
2898 It should occur in the
2899 configuration file before any other configuration options.
2901 default values of these variables have been carefully optimized for
2902 a wide range of network speeds and reliability expectations.
2904 general, they interact in intricate ways that are hard to predict
2905 and some combinations can result in some very nasty behavior.
2907 rarely is it necessary to change the default values; but, some
2908 folks cannot resist twisting the knobs anyway and this command is
2910 Emphasis added: twisters are on their own and can expect
2911 no help from the support group.
2913 The variables operate as follows:
2915 @item @code{allan} @kbd{allan}
2916 The argument becomes the new value for the minimum Allan
2917 intercept, which is a parameter of the PLL/FLL clock discipline
2919 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
2921 @item @code{dispersion} @kbd{dispersion}
2922 The argument becomes the new value for the dispersion increase rate,
2923 normally .000015 s/s.
2924 @item @code{freq} @kbd{freq}
2925 The argument becomes the initial value of the frequency offset in
2927 This overrides the value in the frequency file, if
2928 present, and avoids the initial training state if it is not.
2929 @item @code{huffpuff} @kbd{huffpuff}
2930 The argument becomes the new value for the experimental
2931 huff-n'-puff filter span, which determines the most recent interval
2932 the algorithm will search for a minimum delay.
2934 900 s (15 m), but a more reasonable value is 7200 (2 hours).
2936 is no default, since the filter is not enabled unless this command
2938 @item @code{panic} @kbd{panic}
2939 The argument is the panic threshold, normally 1000 s.
2941 the panic sanity check is disabled and a clock offset of any value will
2943 @item @code{step} @kbd{step}
2944 The argument is the step threshold, which by default is 0.128 s.
2946 be set to any positive number in seconds.
2947 If set to zero, step
2948 adjustments will never occur.
2949 Note: The kernel time discipline is
2950 disabled if the step threshold is set to zero or greater than the
2952 @item @code{stepback} @kbd{stepback}
2953 The argument is the step threshold for the backward direction,
2954 which by default is 0.128 s.
2956 be set to any positive number in seconds.
2957 If both the forward and backward step thresholds are set to zero, step
2958 adjustments will never occur.
2959 Note: The kernel time discipline is
2961 each direction of step threshold are either
2962 set to zero or greater than .5 second.
2963 @item @code{stepfwd} @kbd{stepfwd}
2964 As for stepback, but for the forward direction.
2965 @item @code{stepout} @kbd{stepout}
2966 The argument is the stepout timeout, which by default is 900 s.
2968 be set to any positive number in seconds.
2969 If set to zero, the stepout
2970 pulses will not be suppressed.
2972 @item @code{writevar} @kbd{assocID\ name} @kbd{=} @kbd{value} @kbd{[,...]}
2973 Write (create or update) the specified variables.
2976 is zero, the variablea re from the
2978 name space, otherwise they are from the
2983 is required, as the same name can occur in both name spaces.
2984 @item @code{trap} @kbd{host_address} @code{[@code{port} @kbd{port_number}]} @code{[@code{interface} @kbd{interface_address}]}
2985 This command configures a trap receiver at the given host
2986 address and port number for sending messages with the specified
2987 local interface address.
2988 If the port number is unspecified, a value
2990 If the interface address is not specified, the
2991 message is sent with a source address of the local interface the
2992 message is sent through.
2993 Note that on a multihomed host the
2994 interface used may vary from time to time with routing changes.
2995 @item @code{ttl} @kbd{hop} @kbd{...}
2996 This command specifies a list of TTL values in increasing order.
2997 Up to 8 values can be specified.
3000 mode these values are used in-turn in an expanding-ring search.
3001 The default is eight multiples of 32 starting at 31.
3003 The trap receiver will generally log event messages and other
3004 information from the server in a log file.
3006 programs may also request their own trap dynamically, configuring a
3007 trap receiver will ensure that no messages are lost when the server
3009 @item @code{hop} @kbd{...}
3010 This command specifies a list of TTL values in increasing order, up to 8
3011 values can be specified.
3012 In manycast mode these values are used in turn in
3013 an expanding-ring search.
3014 The default is eight multiples of 32 starting at
3018 This section was generated by @strong{AutoGen},
3019 using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program.
3020 This software is released under the NTP license, <http://ntp.org/license>.
3023 * ntp.conf Files:: Files
3024 * ntp.conf See Also:: See Also
3025 * ntp.conf Bugs:: Bugs
3026 * ntp.conf Notes:: Notes
3029 @node ntp.conf Files
3030 @subsection ntp.conf Files
3032 @item @file{/etc/ntp.conf}
3033 the default name of the configuration file
3034 @item @file{ntp.keys}
3038 @item @file{ntpkey_}@kbd{host}
3041 Diffie-Hellman agreement parameters
3043 @node ntp.conf See Also
3044 @subsection ntp.conf See Also
3045 @code{ntpd(1ntpdmdoc)},
3046 @code{ntpdc(1ntpdcmdoc)},
3047 @code{ntpq(1ntpqmdoc)}
3049 In addition to the manual pages provided,
3050 comprehensive documentation is available on the world wide web
3052 @code{http://www.ntp.org/}.
3053 A snapshot of this documentation is available in HTML format in
3054 @file{/usr/share/doc/ntp}.
3058 David L. Mills, @emph{Network Time Protocol (Version 4)}, RFC5905
3060 @subsection ntp.conf Bugs
3061 The syntax checking is not picky; some combinations of
3062 ridiculous and even hilarious options and modes may not be
3066 @file{ntpkey_}@kbd{host}
3067 files are really digital
3069 These should be obtained via secure directory
3070 services when they become universally available.
3071 @node ntp.conf Notes
3072 @subsection ntp.conf Notes
3073 This document was derived from FreeBSD.