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 February 27, 2018 at 05:14:34 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}]}
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}]}
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 65534, 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 a truechimer.
310 Use this option only for testing.
312 Marks the server as preferred.
313 All other things being equal,
314 this host will be chosen for synchronization among a set of
315 correctly operating hosts.
317 "Mitigation Rules and the prefer Keyword"
319 (available as part of the HTML documentation
321 @file{/usr/share/doc/ntp})
322 for further information.
324 Forces the association to always survive the selection and clustering algorithms.
325 This option should almost certainly
327 be used while testing an association.
328 @item @code{ttl} @kbd{ttl}
329 This option is used only with broadcast server and manycast
331 It specifies the time-to-live
334 use on broadcast server and multicast server and the maximum
336 for the expanding ring search with manycast
338 Selection of the proper value, which defaults to
339 127, is something of a black art and should be coordinated with the
340 network administrator.
341 @item @code{version} @kbd{version}
342 Specifies the version number to be used for outgoing NTP
344 Versions 1-4 are the choices, with version 4 the
351 modes only, this flag enables interleave mode.
353 @subsubsection Auxiliary Commands
355 @item @code{broadcastclient}
356 This command enables reception of broadcast server messages to
357 any local interface (type b) address.
358 Upon receiving a message for
359 the first time, the broadcast client measures the nominal server
360 propagation delay using a brief client/server exchange with the
361 server, then enters the broadcast client mode, in which it
362 synchronizes to succeeding broadcast messages.
364 to avoid accidental or malicious disruption in this mode, both the
365 server and client should operate using symmetric-key or public-key
366 authentication as described in
367 @ref{Authentication Options}.
368 @item @code{manycastserver} @kbd{address} @kbd{...}
369 This command enables reception of manycast client messages to
370 the multicast group address(es) (type m) specified.
372 address is required, but the NTP multicast address 224.0.1.1
373 assigned by the IANA should NOT be used, unless specific means are
374 taken to limit the span of the reply and avoid a possibly massive
375 implosion at the original sender.
376 Note that, in order to avoid
377 accidental or malicious disruption in this mode, both the server
378 and client should operate using symmetric-key or public-key
379 authentication as described in
380 @ref{Authentication Options}.
381 @item @code{multicastclient} @kbd{address} @kbd{...}
382 This command enables reception of multicast server messages to
383 the multicast group address(es) (type m) specified.
385 a message for the first time, the multicast client measures the
386 nominal server propagation delay using a brief client/server
387 exchange with the server, then enters the broadcast client mode, in
388 which it synchronizes to succeeding multicast messages.
390 in order to avoid accidental or malicious disruption in this mode,
391 both the server and client should operate using symmetric-key or
392 public-key authentication as described in
393 @ref{Authentication Options}.
394 @item @code{mdnstries} @kbd{number}
395 If we are participating in mDNS,
396 after we have synched for the first time
397 we attempt to register with the mDNS system.
398 If that registration attempt fails,
399 we try again at one minute intervals for up to
404 may be starting before mDNS.
405 The default value for
409 @node Authentication Support
410 @subsection Authentication Support
411 Authentication support allows the NTP client to verify that the
412 server is in fact known and trusted and not an intruder intending
413 accidentally or on purpose to masquerade as that server.
415 specification RFC-1305 defines a scheme which provides
416 cryptographic authentication of received NTP packets.
418 this was done using the Data Encryption Standard (DES) algorithm
419 operating in Cipher Block Chaining (CBC) mode, commonly called
421 Subsequently, this was replaced by the RSA Message Digest
422 5 (MD5) algorithm using a private key, commonly called keyed-MD5.
423 Either algorithm computes a message digest, or one-way hash, which
424 can be used to verify the server has the correct private key and
427 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
428 cryptography and, in addition, provides a new Autokey scheme
429 based on public key cryptography.
430 Public key cryptography is generally considered more secure
431 than symmetric key cryptography, since the security is based
432 on a private value which is generated by each server and
434 With Autokey all key distribution and
435 management functions involve only public values, which
436 considerably simplifies key distribution and storage.
437 Public key management is based on X.509 certificates,
438 which can be provided by commercial services or
439 produced by utility programs in the OpenSSL software library
440 or the NTPv4 distribution.
442 While the algorithms for symmetric key cryptography are
443 included in the NTPv4 distribution, public key cryptography
444 requires the OpenSSL software library to be installed
445 before building the NTP distribution.
446 Directions for doing that
447 are on the Building and Installing the Distribution page.
449 Authentication is configured separately for each association
459 @code{manycastclient}
460 configuration commands as described in
461 @ref{Configuration Options}
464 options described below specify the locations of the key files,
465 if other than default, which symmetric keys are trusted
466 and the interval between various operations, if other than default.
468 Authentication is always enabled,
469 although ineffective if not configured as
471 If a NTP packet arrives
472 including a message authentication
473 code (MAC), it is accepted only if it
474 passes all cryptographic checks.
476 checks require correct key ID, key value
479 been modified in any way or replayed
480 by an intruder, it will fail one or more
481 of these checks and be discarded.
482 Furthermore, the Autokey scheme requires a
483 preliminary protocol exchange to obtain
484 the server certificate, verify its
485 credentials and initialize the protocol
489 flag controls whether new associations or
490 remote configuration commands require cryptographic authentication.
491 This flag can be set or reset by the
495 commands and also by remote
496 configuration commands sent by a
497 @code{ntpdc(1ntpdcmdoc)}
500 If this flag is enabled, which is the default
501 case, new broadcast client and symmetric passive associations and
502 remote configuration commands must be cryptographically
503 authenticated using either symmetric key or public key cryptography.
505 flag is disabled, these operations are effective
506 even if not cryptographic
508 It should be understood
509 that operating with the
511 flag disabled invites a significant vulnerability
512 where a rogue hacker can
513 masquerade as a falseticker and seriously
514 disrupt system timekeeping.
516 important to note that this flag has no purpose
517 other than to allow or disallow
518 a new association in response to new broadcast
519 and symmetric active messages
520 and remote configuration commands and, in particular,
521 the flag has no effect on
522 the authentication process itself.
524 An attractive alternative where multicast support is available
525 is manycast mode, in which clients periodically troll
526 for servers as described in the
527 @ref{Automatic NTP Configuration Options}
529 Either symmetric key or public key
530 cryptographic authentication can be used in this mode.
531 The principle advantage
532 of manycast mode is that potential servers need not be
533 configured in advance,
534 since the client finds them during regular operation,
535 and the configuration
536 files for all clients can be identical.
538 The security model and protocol schemes for
539 both symmetric key and public key
540 cryptography are summarized below;
541 further details are in the briefings, papers
542 and reports at the NTP project page linked from
543 @code{http://www.ntp.org/}.
544 @subsubsection Symmetric-Key Cryptography
545 The original RFC-1305 specification allows any one of possibly
546 65,534 keys, each distinguished by a 32-bit key identifier, to
547 authenticate an association.
548 The servers and clients involved must
549 agree on the key and key identifier to
550 authenticate NTP packets.
552 related information are specified in a key
555 which must be distributed and stored using
556 secure means beyond the scope of the NTP protocol itself.
557 Besides the keys used
558 for ordinary NTP associations,
559 additional keys can be used as passwords for the
560 @code{ntpq(1ntpqmdoc)}
562 @code{ntpdc(1ntpdcmdoc)}
566 @code{ntpd(1ntpdmdoc)}
567 is first started, it reads the key file specified in the
569 configuration command and installs the keys
572 individual keys must be activated with the
576 allows, for instance, the installation of possibly
577 several batches of keys and
578 then activating or deactivating each batch
580 @code{ntpdc(1ntpdcmdoc)}.
581 This also provides a revocation capability that can be used
582 if a key becomes compromised.
585 command selects the key used as the password for the
586 @code{ntpdc(1ntpdcmdoc)}
589 command selects the key used as the password for the
590 @code{ntpq(1ntpqmdoc)}
592 @subsubsection Public Key Cryptography
593 NTPv4 supports the original NTPv3 symmetric key scheme
594 described in RFC-1305 and in addition the Autokey protocol,
595 which is based on public key cryptography.
596 The Autokey Version 2 protocol described on the Autokey Protocol
597 page verifies packet integrity using MD5 message digests
598 and verifies the source with digital signatures and any of several
599 digest/signature schemes.
600 Optional identity schemes described on the Identity Schemes
601 page and based on cryptographic challenge/response algorithms
603 Using all of these schemes provides strong security against
604 replay with or without modification, spoofing, masquerade
605 and most forms of clogging attacks.
607 The Autokey protocol has several modes of operation
608 corresponding to the various NTP modes supported.
609 Most modes use a special cookie which can be
610 computed independently by the client and server,
611 but encrypted in transmission.
612 All modes use in addition a variant of the S-KEY scheme,
613 in which a pseudo-random key list is generated and used
615 These schemes are described along with an executive summary,
616 current status, briefing slides and reading list on the
617 @ref{Autonomous Authentication}
620 The specific cryptographic environment used by Autokey servers
621 and clients is determined by a set of files
622 and soft links generated by the
623 @code{ntp-keygen(1ntpkeygenmdoc)}
625 This includes a required host key file,
626 required certificate file and optional sign key file,
627 leapsecond file and identity scheme files.
629 digest/signature scheme is specified in the X.509 certificate
630 along with the matching sign key.
631 There are several schemes
632 available in the OpenSSL software library, each identified
633 by a specific string such as
634 @code{md5WithRSAEncryption},
635 which stands for the MD5 message digest with RSA
637 The current NTP distribution supports
638 all the schemes in the OpenSSL library, including
639 those based on RSA and DSA digital signatures.
641 NTP secure groups can be used to define cryptographic compartments
642 and security hierarchies.
643 It is important that every host
644 in the group be able to construct a certificate trail to one
645 or more trusted hosts in the same group.
647 host runs the Autokey protocol to obtain the certificates
648 for all hosts along the trail to one or more trusted hosts.
649 This requires the configuration file in all hosts to be
650 engineered so that, even under anticipated failure conditions,
651 the NTP subnet will form such that every group host can find
652 a trail to at least one trusted host.
653 @subsubsection Naming and Addressing
654 It is important to note that Autokey does not use DNS to
655 resolve addresses, since DNS can't be completely trusted
656 until the name servers have synchronized clocks.
657 The cryptographic name used by Autokey to bind the host identity
658 credentials and cryptographic values must be independent
659 of interface, network and any other naming convention.
660 The name appears in the host certificate in either or both
661 the subject and issuer fields, so protection against
662 DNS compromise is essential.
664 By convention, the name of an Autokey host is the name returned
666 @code{gethostname(2)}
667 system call or equivalent in other systems.
669 model, there are no provisions to allow alternate names or aliases.
670 However, this is not to say that DNS aliases, different names
671 for each interface, etc., are constrained in any way.
673 It is also important to note that Autokey verifies authenticity
674 using the host name, network address and public keys,
675 all of which are bound together by the protocol specifically
676 to deflect masquerade attacks.
677 For this reason Autokey
678 includes the source and destination IP addresses in message digest
679 computations and so the same addresses must be available
680 at both the server and client.
681 For this reason operation
682 with network address translation schemes is not possible.
683 This reflects the intended robust security model where government
684 and corporate NTP servers are operated outside firewall perimeters.
685 @subsubsection Operation
686 A specific combination of authentication scheme (none,
687 symmetric key, public key) and identity scheme is called
688 a cryptotype, although not all combinations are compatible.
689 There may be management configurations where the clients,
690 servers and peers may not all support the same cryptotypes.
691 A secure NTPv4 subnet can be configured in many ways while
692 keeping in mind the principles explained above and
694 Note however that some cryptotype
695 combinations may successfully interoperate with each other,
696 but may not represent good security practice.
698 The cryptotype of an association is determined at the time
699 of mobilization, either at configuration time or some time
700 later when a message of appropriate cryptotype arrives.
705 configuration command and no
709 subcommands are present, the association is not
710 authenticated; if the
712 subcommand is present, the association is authenticated
713 using the symmetric key ID specified; if the
715 subcommand is present, the association is authenticated
718 When multiple identity schemes are supported in the Autokey
719 protocol, the first message exchange determines which one is used.
720 The client request message contains bits corresponding
721 to which schemes it has available.
722 The server response message
723 contains bits corresponding to which schemes it has available.
724 Both server and client match the received bits with their own
725 and select a common scheme.
727 Following the principle that time is a public value,
728 a server responds to any client packet that matches
729 its cryptotype capabilities.
730 Thus, a server receiving
731 an unauthenticated packet will respond with an unauthenticated
732 packet, while the same server receiving a packet of a cryptotype
733 it supports will respond with packets of that cryptotype.
734 However, unconfigured broadcast or manycast client
735 associations or symmetric passive associations will not be
736 mobilized unless the server supports a cryptotype compatible
737 with the first packet received.
738 By default, unauthenticated associations will not be mobilized
739 unless overridden in a decidedly dangerous way.
741 Some examples may help to reduce confusion.
742 Client Alice has no specific cryptotype selected.
743 Server Bob has both a symmetric key file and minimal Autokey files.
744 Alice's unauthenticated messages arrive at Bob, who replies with
745 unauthenticated messages.
746 Cathy has a copy of Bob's symmetric
747 key file and has selected key ID 4 in messages to Bob.
748 Bob verifies the message with his key ID 4.
750 same key and the message is verified, Bob sends Cathy a reply
751 authenticated with that key.
752 If verification fails,
753 Bob sends Cathy a thing called a crypto-NAK, which tells her
755 She can see the evidence using the
756 @code{ntpq(1ntpqmdoc)}
759 Denise has rolled her own host key and certificate.
760 She also uses one of the identity schemes as Bob.
761 She sends the first Autokey message to Bob and they
762 both dance the protocol authentication and identity steps.
763 If all comes out okay, Denise and Bob continue as described above.
765 It should be clear from the above that Bob can support
766 all the girls at the same time, as long as he has compatible
767 authentication and identity credentials.
768 Now, Bob can act just like the girls in his own choice of servers;
769 he can run multiple configured associations with multiple different
770 servers (or the same server, although that might not be useful).
771 But, wise security policy might preclude some cryptotype
772 combinations; for instance, running an identity scheme
773 with one server and no authentication with another might not be wise.
774 @subsubsection Key Management
775 The cryptographic values used by the Autokey protocol are
776 incorporated as a set of files generated by the
777 @code{ntp-keygen(1ntpkeygenmdoc)}
778 utility program, including symmetric key, host key and
779 public certificate files, as well as sign key, identity parameters
780 and leapseconds files.
781 Alternatively, host and sign keys and
782 certificate files can be generated by the OpenSSL utilities
783 and certificates can be imported from public certificate
785 Note that symmetric keys are necessary for the
786 @code{ntpq(1ntpqmdoc)}
788 @code{ntpdc(1ntpdcmdoc)}
790 The remaining files are necessary only for the
793 Certificates imported from OpenSSL or public certificate
794 authorities have certian limitations.
795 The certificate should be in ASN.1 syntax, X.509 Version 3
796 format and encoded in PEM, which is the same format
798 The overall length of the certificate encoded
799 in ASN.1 must not exceed 1024 bytes.
800 The subject distinguished
801 name field (CN) is the fully qualified name of the host
802 on which it is used; the remaining subject fields are ignored.
803 The certificate extension fields must not contain either
804 a subject key identifier or a issuer key identifier field;
805 however, an extended key usage field for a trusted host must
808 Other extension fields are ignored.
809 @subsubsection Authentication Commands
811 @item @code{autokey} @code{[@kbd{logsec}]}
812 Specifies the interval between regenerations of the session key
813 list used with the Autokey protocol.
814 Note that the size of the key
815 list for each association depends on this interval and the current
817 The default value is 12 (4096 s or about 1.1 hours).
818 For poll intervals above the specified interval, a session key list
819 with a single entry will be regenerated for every message
821 @item @code{controlkey} @kbd{key}
822 Specifies the key identifier to use with the
823 @code{ntpq(1ntpqmdoc)}
824 utility, which uses the standard
825 protocol defined in RFC-1305.
829 the key identifier for a trusted key, where the value can be in the
830 range 1 to 65,534, inclusive.
831 @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}]}
832 This command requires the OpenSSL library.
833 It activates public key
834 cryptography, selects the message digest and signature
835 encryption scheme and loads the required private and public
836 values described above.
837 If one or more files are left unspecified,
838 the default names are used as described above.
839 Unless the complete path and name of the file are specified, the
840 location of a file is relative to the keys directory specified
844 @file{/usr/local/etc}.
845 Following are the subcommands:
847 @item @code{cert} @kbd{file}
848 Specifies the location of the required host public certificate file.
849 This overrides the link
850 @file{ntpkey_cert_}@kbd{hostname}
851 in the keys directory.
852 @item @code{gqpar} @kbd{file}
853 Specifies the location of the optional GQ parameters file.
856 @file{ntpkey_gq_}@kbd{hostname}
857 in the keys directory.
858 @item @code{host} @kbd{file}
859 Specifies the location of the required host key file.
862 @file{ntpkey_key_}@kbd{hostname}
863 in the keys directory.
864 @item @code{iffpar} @kbd{file}
865 Specifies the location of the optional IFF parameters file.
866 This overrides the link
867 @file{ntpkey_iff_}@kbd{hostname}
868 in the keys directory.
869 @item @code{leap} @kbd{file}
870 Specifies the location of the optional leapsecond file.
871 This overrides the link
873 in the keys directory.
874 @item @code{mvpar} @kbd{file}
875 Specifies the location of the optional MV parameters file.
876 This overrides the link
877 @file{ntpkey_mv_}@kbd{hostname}
878 in the keys directory.
879 @item @code{pw} @kbd{password}
880 Specifies the password to decrypt files containing private keys and
882 This is required only if these files have been
884 @item @code{randfile} @kbd{file}
885 Specifies the location of the random seed file used by the OpenSSL
887 The defaults are described in the main text above.
888 @item @code{sign} @kbd{file}
889 Specifies the location of the optional sign key file.
892 @file{ntpkey_sign_}@kbd{hostname}
893 in the keys directory.
895 not found, the host key is also the sign key.
897 @item @code{keys} @kbd{keyfile}
898 Specifies the complete path and location of the MD5 key file
899 containing the keys and key identifiers used by
900 @code{ntpd(1ntpdmdoc)},
901 @code{ntpq(1ntpqmdoc)}
903 @code{ntpdc(1ntpdcmdoc)}
904 when operating with symmetric key cryptography.
905 This is the same operation as the
908 @item @code{keysdir} @kbd{path}
909 This command specifies the default directory path for
910 cryptographic keys, parameters and certificates.
912 @file{/usr/local/etc/}.
913 @item @code{requestkey} @kbd{key}
914 Specifies the key identifier to use with the
915 @code{ntpdc(1ntpdcmdoc)}
916 utility program, which uses a
917 proprietary protocol specific to this implementation of
918 @code{ntpd(1ntpdmdoc)}.
921 argument is a key identifier
922 for the trusted key, where the value can be in the range 1 to
924 @item @code{revoke} @kbd{logsec}
925 Specifies the interval between re-randomization of certain
926 cryptographic values used by the Autokey scheme, as a power of 2 in
928 These values need to be updated frequently in order to
929 deflect brute-force attacks on the algorithms of the scheme;
930 however, updating some values is a relatively expensive operation.
931 The default interval is 16 (65,536 s or about 18 hours).
933 intervals above the specified interval, the values will be updated
934 for every message sent.
935 @item @code{trustedkey} @kbd{key} @kbd{...}
936 Specifies the key identifiers which are trusted for the
937 purposes of authenticating peers with symmetric key cryptography,
938 as well as keys used by the
939 @code{ntpq(1ntpqmdoc)}
941 @code{ntpdc(1ntpdcmdoc)}
943 The authentication procedures require that both the local
944 and remote servers share the same key and key identifier for this
945 purpose, although different keys can be used with different
949 arguments are 32-bit unsigned
950 integers with values from 1 to 65,534.
952 @subsubsection Error Codes
953 The following error codes are reported via the NTP control
954 and monitoring protocol trap mechanism.
957 (bad field format or length)
958 The packet has invalid version, length or format.
961 The packet timestamp is the same or older than the most recent received.
962 This could be due to a replay or a server clock time step.
965 The packet filestamp is the same or older than the most recent received.
966 This could be due to a replay or a key file generation error.
968 (bad or missing public key)
969 The public key is missing, has incorrect format or is an unsupported type.
971 (unsupported digest type)
972 The server requires an unsupported digest/signature scheme.
974 (mismatched digest types)
977 (bad signature length)
978 The signature length does not match the current public key.
980 (signature not verified)
981 The message fails the signature check.
982 It could be bogus or signed by a
983 different private key.
985 (certificate not verified)
986 The certificate is invalid or signed with the wrong key.
988 (certificate not verified)
989 The certificate is not yet valid or has expired or the signature could not
992 (bad or missing cookie)
993 The cookie is missing, corrupted or bogus.
995 (bad or missing leapseconds table)
996 The leapseconds table is missing, corrupted or bogus.
998 (bad or missing certificate)
999 The certificate is missing, corrupted or bogus.
1001 (bad or missing identity)
1002 The identity key is missing, corrupt or bogus.
1004 @node Monitoring Support
1005 @subsection Monitoring Support
1006 @code{ntpd(1ntpdmdoc)}
1007 includes a comprehensive monitoring facility suitable
1008 for continuous, long term recording of server and client
1009 timekeeping performance.
1013 for a listing and example of each type of statistics currently
1015 Statistic files are managed using file generation sets
1018 directory of the source code distribution.
1020 these facilities and
1023 jobs, the data can be
1024 automatically summarized and archived for retrospective analysis.
1025 @subsubsection Monitoring Commands
1027 @item @code{statistics} @kbd{name} @kbd{...}
1028 Enables writing of statistics records.
1029 Currently, eight kinds of
1031 statistics are supported.
1033 @item @code{clockstats}
1034 Enables recording of clock driver statistics information.
1036 received from a clock driver appends a line of the following form to
1037 the file generation set named
1040 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1043 The first two fields show the date (Modified Julian Day) and time
1044 (seconds and fraction past UTC midnight).
1045 The next field shows the
1046 clock address in dotted-quad notation.
1047 The final field shows the last
1048 timecode received from the clock in decoded ASCII format, where
1050 In some clock drivers a good deal of additional information
1051 can be gathered and displayed as well.
1052 See information specific to each
1053 clock for further details.
1054 @item @code{cryptostats}
1055 This option requires the OpenSSL cryptographic software library.
1057 enables recording of cryptographic public key protocol information.
1058 Each message received by the protocol module appends a line of the
1059 following form to the file generation set named
1062 49213 525.624 127.127.4.1 message
1065 The first two fields show the date (Modified Julian Day) and time
1066 (seconds and fraction past UTC midnight).
1067 The next field shows the peer
1068 address in dotted-quad notation, The final message field includes the
1069 message type and certain ancillary information.
1071 @ref{Authentication Options}
1072 section for further information.
1073 @item @code{loopstats}
1074 Enables recording of loop filter statistics information.
1076 update of the local clock outputs a line of the following form to
1077 the file generation set named
1080 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1083 The first two fields show the date (Modified Julian Day) and
1084 time (seconds and fraction past UTC midnight).
1085 The next five fields
1086 show time offset (seconds), frequency offset (parts per million -
1087 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1088 discipline time constant.
1089 @item @code{peerstats}
1090 Enables recording of peer statistics information.
1092 statistics records of all peers of a NTP server and of special
1093 signals, where present and configured.
1094 Each valid update appends a
1095 line of the following form to the current element of a file
1096 generation set named
1099 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
1102 The first two fields show the date (Modified Julian Day) and
1103 time (seconds and fraction past UTC midnight).
1105 show the peer address in dotted-quad notation and status,
1107 The status field is encoded in hex in the format
1108 described in Appendix A of the NTP specification RFC 1305.
1109 The final four fields show the offset,
1110 delay, dispersion and RMS jitter, all in seconds.
1111 @item @code{rawstats}
1112 Enables recording of raw-timestamp statistics information.
1114 includes statistics records of all peers of a NTP server and of
1115 special signals, where present and configured.
1117 received from a peer or clock driver appends a line of the
1118 following form to the file generation set named
1121 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1124 The first two fields show the date (Modified Julian Day) and
1125 time (seconds and fraction past UTC midnight).
1127 show the remote peer or clock address followed by the local address
1128 in dotted-quad notation.
1129 The final four fields show the originate,
1130 receive, transmit and final NTP timestamps in order.
1132 values are as received and before processing by the various data
1133 smoothing and mitigation algorithms.
1134 @item @code{sysstats}
1135 Enables recording of ntpd statistics counters on a periodic basis.
1137 hour a line of the following form is appended to the file generation
1141 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1144 The first two fields show the date (Modified Julian Day) and time
1145 (seconds and fraction past UTC midnight).
1146 The remaining ten fields show
1147 the statistics counter values accumulated since the last generated
1150 @item Time since restart @code{36000}
1151 Time in hours since the system was last rebooted.
1152 @item Packets received @code{81965}
1153 Total number of packets received.
1154 @item Packets processed @code{0}
1155 Number of packets received in response to previous packets sent
1156 @item Current version @code{9546}
1157 Number of packets matching the current NTP version.
1158 @item Previous version @code{56}
1159 Number of packets matching the previous NTP version.
1160 @item Bad version @code{71793}
1161 Number of packets matching neither NTP version.
1162 @item Access denied @code{512}
1163 Number of packets denied access for any reason.
1164 @item Bad length or format @code{540}
1165 Number of packets with invalid length, format or port number.
1166 @item Bad authentication @code{10}
1167 Number of packets not verified as authentic.
1168 @item Rate exceeded @code{147}
1169 Number of packets discarded due to rate limitation.
1171 @item @code{statsdir} @kbd{directory_path}
1172 Indicates the full path of a directory where statistics files
1173 should be created (see below).
1175 the (otherwise constant)
1177 filename prefix to be modified for file generation sets, which
1178 is useful for handling statistics logs.
1179 @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}]}
1180 Configures setting of generation file set name.
1182 file sets provide a means for handling files that are
1183 continuously growing during the lifetime of a server.
1184 Server statistics are a typical example for such files.
1185 Generation file sets provide access to a set of files used
1186 to store the actual data.
1187 At any time at most one element
1188 of the set is being written to.
1189 The type given specifies
1190 when and how data will be directed to a new element of the set.
1191 This way, information stored in elements of a file set
1192 that are currently unused are available for administrational
1193 operations without the risk of disturbing the operation of ntpd.
1194 (Most important: they can be removed to free space for new data
1197 Note that this command can be sent from the
1198 @code{ntpdc(1ntpdcmdoc)}
1199 program running at a remote location.
1202 This is the type of the statistics records, as shown in the
1205 @item @code{file} @kbd{filename}
1206 This is the file name for the statistics records.
1208 members are built from three concatenated elements
1215 This is a constant filename path.
1216 It is not subject to
1217 modifications via the
1220 It is defined by the
1221 server, usually specified as a compile-time constant.
1223 however, be configurable for individual file generation sets
1225 For example, the prefix used with
1229 generation can be configured using the
1231 option explained above.
1232 @item @code{filename}
1233 This string is directly concatenated to the prefix mentioned
1234 above (no intervening
1235 @quoteleft{}/@quoteright{}).
1236 This can be modified using
1237 the file argument to the
1243 allowed in this component to prevent filenames referring to
1244 parts outside the filesystem hierarchy denoted by
1247 This part is reflects individual elements of a file set.
1249 generated according to the type of a file set.
1251 @item @code{type} @kbd{typename}
1252 A file generation set is characterized by its type.
1254 types are supported:
1257 The file set is actually a single plain file.
1259 One element of file set is used per incarnation of a ntpd
1261 This type does not perform any changes to file set
1262 members during runtime, however it provides an easy way of
1263 separating files belonging to different
1264 @code{ntpd(1ntpdmdoc)}
1265 server incarnations.
1266 The set member filename is built by appending a
1267 @quoteleft{}.@quoteright{}
1273 appending the decimal representation of the process ID of the
1274 @code{ntpd(1ntpdmdoc)}
1277 One file generation set element is created per day.
1279 defined as the period between 00:00 and 24:00 UTC.
1281 member suffix consists of a
1282 @quoteleft{}.@quoteright{}
1283 and a day specification in
1287 is a 4-digit year number (e.g., 1992).
1289 is a two digit month number.
1291 is a two digit day number.
1292 Thus, all information written at 10 December 1992 would end up
1295 @kbd{filename}.19921210.
1297 Any file set member contains data related to a certain week of
1299 The term week is defined by computing day-of-year
1301 Elements of such a file generation set are
1302 distinguished by appending the following suffix to the file set
1303 filename base: A dot, a 4-digit year number, the letter
1305 and a 2-digit week number.
1306 For example, information from January,
1307 10th 1992 would end up in a file with suffix
1308 .No . Ns Ar 1992W1 .
1310 One generation file set element is generated per month.
1312 file name suffix consists of a dot, a 4-digit year number, and
1315 One generation file element is generated per year.
1317 suffix consists of a dot and a 4 digit year number.
1319 This type of file generation sets changes to a new element of
1320 the file set every 24 hours of server operation.
1322 suffix consists of a dot, the letter
1324 and an 8-digit number.
1325 This number is taken to be the number of seconds the server is
1326 running at the start of the corresponding 24-hour period.
1327 Information is only written to a file generation by specifying
1329 output is prevented by specifying
1332 @item @code{link} | @code{nolink}
1333 It is convenient to be able to access the current element of a file
1334 generation set by a fixed name.
1335 This feature is enabled by
1340 If link is specified, a
1341 hard link from the current file set element to a file without
1343 When there is already a file with this name and
1344 the number of links of this file is one, it is renamed appending a
1348 @code{ntpd(1ntpdmdoc)}
1351 number of links is greater than one, the file is unlinked.
1353 allows the current file to be accessed by a constant name.
1354 @item @code{enable} @code{|} @code{disable}
1355 Enables or disables the recording function.
1359 @node Access Control Support
1360 @subsection Access Control Support
1362 @code{ntpd(1ntpdmdoc)}
1363 daemon implements a general purpose address/mask based restriction
1365 The list contains address/match entries sorted first
1366 by increasing address values and and then by increasing mask values.
1367 A match occurs when the bitwise AND of the mask and the packet
1368 source address is equal to the bitwise AND of the mask and
1369 address in the list.
1370 The list is searched in order with the
1371 last match found defining the restriction flags associated
1373 Additional information and examples can be found in the
1374 "Notes on Configuring NTP and Setting up a NTP Subnet"
1376 (available as part of the HTML documentation
1378 @file{/usr/share/doc/ntp}).
1380 The restriction facility was implemented in conformance
1381 with the access policies for the original NSFnet backbone
1383 Later the facility was expanded to deflect
1384 cryptographic and clogging attacks.
1385 While this facility may
1386 be useful for keeping unwanted or broken or malicious clients
1387 from congesting innocent servers, it should not be considered
1388 an alternative to the NTP authentication facilities.
1389 Source address based restrictions are easily circumvented
1390 by a determined cracker.
1392 Clients can be denied service because they are explicitly
1393 included in the restrict list created by the
1396 or implicitly as the result of cryptographic or rate limit
1398 Cryptographic violations include certificate
1399 or identity verification failure; rate limit violations generally
1400 result from defective NTP implementations that send packets
1402 Some violations cause denied service
1403 only for the offending packet, others cause denied service
1404 for a timed period and others cause the denied service for
1405 an indefinite period.
1406 When a client or network is denied access
1407 for an indefinite period, the only way at present to remove
1408 the restrictions is by restarting the server.
1409 @subsubsection The Kiss-of-Death Packet
1410 Ordinarily, packets denied service are simply dropped with no
1411 further action except incrementing statistics counters.
1413 more proactive response is needed, such as a server message that
1414 explicitly requests the client to stop sending and leave a message
1415 for the system operator.
1416 A special packet format has been created
1417 for this purpose called the "kiss-of-death" (KoD) packet.
1418 KoD packets have the leap bits set unsynchronized and stratum set
1419 to zero and the reference identifier field set to a four-byte
1425 flag of the matching restrict list entry is set,
1426 the code is "DENY"; if the
1428 flag is set and the rate limit
1429 is exceeded, the code is "RATE".
1430 Finally, if a cryptographic violation occurs, the code is "CRYP".
1432 A client receiving a KoD performs a set of sanity checks to
1433 minimize security exposure, then updates the stratum and
1434 reference identifier peer variables, sets the access
1435 denied (TEST4) bit in the peer flash variable and sends
1436 a message to the log.
1437 As long as the TEST4 bit is set,
1438 the client will send no further packets to the server.
1439 The only way at present to recover from this condition is
1440 to restart the protocol at both the client and server.
1442 happens automatically at the client when the association times out.
1443 It will happen at the server only if the server operator cooperates.
1444 @subsubsection Access Control Commands
1446 @item @code{discard} @code{[@code{average} @kbd{avg}]} @code{[@code{minimum} @kbd{min}]} @code{[@code{monitor} @kbd{prob}]}
1447 Set the parameters of the
1449 facility which protects the server from
1453 subcommand specifies the minimum average packet
1456 subcommand specifies the minimum packet spacing.
1457 Packets that violate these minima are discarded
1458 and a kiss-o'-death packet returned if enabled.
1460 minimum average and minimum are 5 and 2, respectively.
1463 subcommand specifies the probability of discard
1464 for packets that overflow the rate-control window.
1465 @item @code{restrict} @code{address} @code{[@code{mask} @kbd{mask}]} @code{[@code{ippeerlimit} @kbd{int}]} @code{[@kbd{flag} @kbd{...}]}
1468 argument expressed in
1469 dotted-quad form is the address of a host or network.
1472 argument can be a valid host DNS name.
1475 argument expressed in dotted-quad form defaults to
1476 @code{255.255.255.255},
1479 is treated as the address of an individual host.
1480 A default entry (address
1484 is always included and is always the first entry in the list.
1485 Note that text string
1487 with no mask option, may
1488 be used to indicate the default entry.
1491 directive limits the number of peer requests for each IP to
1493 where a value of -1 means "unlimited", the current default.
1494 A value of 0 means "none".
1495 There would usually be at most 1 peering request per IP,
1496 but if the remote peering requests are behind a proxy
1497 there could well be more than 1 per IP.
1498 In the current implementation,
1501 restricts access, i.e., an entry with no flags indicates that free
1502 access to the server is to be given.
1503 The flags are not orthogonal,
1504 in that more restrictive flags will often make less restrictive
1506 The flags can generally be classed into two
1507 categories, those which restrict time service and those which
1508 restrict informational queries and attempts to do run-time
1509 reconfiguration of the server.
1510 One or more of the following flags
1514 Deny packets of all kinds, including
1515 @code{ntpq(1ntpqmdoc)}
1517 @code{ntpdc(1ntpdcmdoc)}
1520 If this flag is set when an access violation occurs, a kiss-o'-death
1521 (KoD) packet is sent.
1522 KoD packets are rate limited to no more than one
1524 If another KoD packet occurs within one second after the
1525 last one, the packet is dropped.
1526 @item @code{limited}
1527 Deny service if the packet spacing violates the lower limits specified
1531 A history of clients is kept using the
1532 monitoring capability of
1533 @code{ntpd(1ntpdmdoc)}.
1534 Thus, monitoring is always active as
1535 long as there is a restriction entry with the
1538 @item @code{lowpriotrap}
1539 Declare traps set by matching hosts to be low priority.
1541 number of traps a server can maintain is limited (the current limit
1543 Traps are usually assigned on a first come, first served
1544 basis, with later trap requestors being denied service.
1546 modifies the assignment algorithm by allowing low priority traps to
1547 be overridden by later requests for normal priority traps.
1548 @item @code{noepeer}
1549 Deny ephemeral peer requests,
1550 even if they come from an authenticated source.
1551 Note that the ability to use a symmetric key for authentication may be restricted to
1552 one or more IPs or subnets via the third field of the
1555 This restriction is not enabled by default,
1556 to maintain backward compatability.
1559 to become the default in ntp-4.4.
1560 @item @code{nomodify}
1562 @code{ntpq(1ntpqmdoc)}
1564 @code{ntpdc(1ntpdcmdoc)}
1565 queries which attempt to modify the state of the
1566 server (i.e., run time reconfiguration).
1567 Queries which return
1568 information are permitted.
1569 @item @code{noquery}
1571 @code{ntpq(1ntpqmdoc)}
1573 @code{ntpdc(1ntpdcmdoc)}
1575 Time service is not affected.
1577 Deny unauthenticated packets which would result in mobilizing a new association.
1579 broadcast and symmetric active packets
1580 when a configured association does not exist.
1583 associations, so if you want to use servers from a
1585 directive and also want to use
1587 by default, you'll want a
1588 @code{restrict source ...}
1589 line as well that does
1594 @item @code{noserve}
1595 Deny all packets except
1596 @code{ntpq(1ntpqmdoc)}
1598 @code{ntpdc(1ntpdcmdoc)}
1601 Decline to provide mode 6 control message trap service to matching
1603 The trap service is a subsystem of the
1604 @code{ntpq(1ntpqmdoc)}
1606 protocol which is intended for use by remote event logging programs.
1607 @item @code{notrust}
1608 Deny service unless the packet is cryptographically authenticated.
1609 @item @code{ntpport}
1610 This is actually a match algorithm modifier, rather than a
1612 Its presence causes the restriction entry to be
1613 matched only if the source port in the packet is the standard NTP
1623 is considered more specific and
1624 is sorted later in the list.
1625 @item @code{version}
1626 Deny packets that do not match the current NTP version.
1629 Default restriction list entries with the flags ignore, interface,
1630 ntpport, for each of the local host's interface addresses are
1631 inserted into the table at startup to prevent the server
1632 from attempting to synchronize to its own time.
1633 A default entry is also always present, though if it is
1634 otherwise unconfigured; no flags are associated
1635 with the default entry (i.e., everything besides your own
1636 NTP server is unrestricted).
1638 @node Automatic NTP Configuration Options
1639 @subsection Automatic NTP Configuration Options
1640 @subsubsection Manycasting
1641 Manycasting is a automatic discovery and configuration paradigm
1643 It is intended as a means for a multicast client
1644 to troll the nearby network neighborhood to find cooperating
1645 manycast servers, validate them using cryptographic means
1646 and evaluate their time values with respect to other servers
1647 that might be lurking in the vicinity.
1648 The intended result is that each manycast client mobilizes
1649 client associations with some number of the "best"
1650 of the nearby manycast servers, yet automatically reconfigures
1651 to sustain this number of servers should one or another fail.
1653 Note that the manycasting paradigm does not coincide
1654 with the anycast paradigm described in RFC-1546,
1655 which is designed to find a single server from a clique
1656 of servers providing the same service.
1657 The manycast paradigm is designed to find a plurality
1658 of redundant servers satisfying defined optimality criteria.
1660 Manycasting can be used with either symmetric key
1661 or public key cryptography.
1662 The public key infrastructure (PKI)
1663 offers the best protection against compromised keys
1664 and is generally considered stronger, at least with relatively
1666 It is implemented using the Autokey protocol and
1667 the OpenSSL cryptographic library available from
1668 @code{http://www.openssl.org/}.
1669 The library can also be used with other NTPv4 modes
1670 as well and is highly recommended, especially for broadcast modes.
1672 A persistent manycast client association is configured
1674 @code{manycastclient}
1675 command, which is similar to the
1677 command but with a multicast (IPv4 class
1682 The IANA has designated IPv4 address 224.1.1.1
1683 and IPv6 address FF05::101 (site local) for NTP.
1684 When more servers are needed, it broadcasts manycast
1685 client messages to this address at the minimum feasible rate
1686 and minimum feasible time-to-live (TTL) hops, depending
1687 on how many servers have already been found.
1688 There can be as many manycast client associations
1689 as different group address, each one serving as a template
1690 for a future ephemeral unicast client/server association.
1692 Manycast servers configured with the
1693 @code{manycastserver}
1694 command listen on the specified group address for manycast
1696 Note the distinction between manycast client,
1697 which actively broadcasts messages, and manycast server,
1698 which passively responds to them.
1699 If a manycast server is
1700 in scope of the current TTL and is itself synchronized
1701 to a valid source and operating at a stratum level equal
1702 to or lower than the manycast client, it replies to the
1703 manycast client message with an ordinary unicast server message.
1705 The manycast client receiving this message mobilizes
1706 an ephemeral client/server association according to the
1707 matching manycast client template, but only if cryptographically
1708 authenticated and the server stratum is less than or equal
1709 to the client stratum.
1710 Authentication is explicitly required
1711 and either symmetric key or public key (Autokey) can be used.
1712 Then, the client polls the server at its unicast address
1713 in burst mode in order to reliably set the host clock
1714 and validate the source.
1715 This normally results
1716 in a volley of eight client/server at 2-s intervals
1717 during which both the synchronization and cryptographic
1718 protocols run concurrently.
1719 Following the volley,
1720 the client runs the NTP intersection and clustering
1721 algorithms, which act to discard all but the "best"
1722 associations according to stratum and synchronization
1724 The surviving associations then continue
1725 in ordinary client/server mode.
1727 The manycast client polling strategy is designed to reduce
1728 as much as possible the volume of manycast client messages
1729 and the effects of implosion due to near-simultaneous
1730 arrival of manycast server messages.
1731 The strategy is determined by the
1732 @code{manycastclient},
1736 configuration commands.
1737 The manycast poll interval is
1738 normally eight times the system poll interval,
1739 which starts out at the
1741 value specified in the
1742 @code{manycastclient},
1743 command and, under normal circumstances, increments to the
1745 value specified in this command.
1746 Initially, the TTL is
1747 set at the minimum hops specified by the
1750 At each retransmission the TTL is increased until reaching
1751 the maximum hops specified by this command or a sufficient
1752 number client associations have been found.
1753 Further retransmissions use the same TTL.
1755 The quality and reliability of the suite of associations
1756 discovered by the manycast client is determined by the NTP
1757 mitigation algorithms and the
1761 values specified in the
1763 configuration command.
1766 candidate servers must be available and the mitigation
1767 algorithms produce at least
1769 survivors in order to synchronize the clock.
1770 Byzantine agreement principles require at least four
1771 candidates in order to correctly discard a single falseticker.
1772 For legacy purposes,
1777 For manycast service
1779 should be explicitly set to 4, assuming at least that
1780 number of servers are available.
1784 servers are found, the manycast poll interval is immediately
1789 servers are found when the TTL has reached the maximum hops,
1790 the manycast poll interval is doubled.
1791 For each transmission
1792 after that, the poll interval is doubled again until
1793 reaching the maximum of eight times
1795 Further transmissions use the same poll interval and
1797 Note that while all this is going on,
1798 each client/server association found is operating normally
1799 it the system poll interval.
1801 Administratively scoped multicast boundaries are normally
1802 specified by the network router configuration and,
1803 in the case of IPv6, the link/site scope prefix.
1804 By default, the increment for TTL hops is 32 starting
1805 from 31; however, the
1807 configuration command can be
1808 used to modify the values to match the scope rules.
1810 It is often useful to narrow the range of acceptable
1811 servers which can be found by manycast client associations.
1812 Because manycast servers respond only when the client
1813 stratum is equal to or greater than the server stratum,
1814 primary (stratum 1) servers fill find only primary servers
1815 in TTL range, which is probably the most common objective.
1816 However, unless configured otherwise, all manycast clients
1817 in TTL range will eventually find all primary servers
1818 in TTL range, which is probably not the most common
1819 objective in large networks.
1822 command can be used to modify this behavior.
1823 Servers with stratum below
1829 command are strongly discouraged during the selection
1830 process; however, these servers may be temporally
1831 accepted if the number of servers within TTL range is
1835 The above actions occur for each manycast client message,
1836 which repeats at the designated poll interval.
1837 However, once the ephemeral client association is mobilized,
1838 subsequent manycast server replies are discarded,
1839 since that would result in a duplicate association.
1840 If during a poll interval the number of client associations
1843 all manycast client prototype associations are reset
1844 to the initial poll interval and TTL hops and operation
1845 resumes from the beginning.
1846 It is important to avoid
1847 frequent manycast client messages, since each one requires
1848 all manycast servers in TTL range to respond.
1849 The result could well be an implosion, either minor or major,
1850 depending on the number of servers in range.
1851 The recommended value for
1855 It is possible and frequently useful to configure a host
1856 as both manycast client and manycast server.
1857 A number of hosts configured this way and sharing a common
1858 group address will automatically organize themselves
1859 in an optimum configuration based on stratum and
1860 synchronization distance.
1861 For example, consider an NTP
1862 subnet of two primary servers and a hundred or more
1864 With two exceptions, all servers
1865 and clients have identical configuration files including both
1866 @code{multicastclient}
1868 @code{multicastserver}
1869 commands using, for instance, multicast group address
1871 The only exception is that each primary server
1872 configuration file must include commands for the primary
1873 reference source such as a GPS receiver.
1875 The remaining configuration files for all secondary
1876 servers and clients have the same contents, except for the
1878 command, which is specific for each stratum level.
1879 For stratum 1 and stratum 2 servers, that command is
1881 For stratum 3 and above servers the
1883 value is set to the intended stratum number.
1884 Thus, all stratum 3 configuration files are identical,
1885 all stratum 4 files are identical and so forth.
1887 Once operations have stabilized in this scenario,
1888 the primary servers will find the primary reference source
1889 and each other, since they both operate at the same
1890 stratum (1), but not with any secondary server or client,
1891 since these operate at a higher stratum.
1893 servers will find the servers at the same stratum level.
1894 If one of the primary servers loses its GPS receiver,
1895 it will continue to operate as a client and other clients
1896 will time out the corresponding association and
1897 re-associate accordingly.
1899 Some administrators prefer to avoid running
1900 @code{ntpd(1ntpdmdoc)}
1901 continuously and run either
1902 @code{sntp(1sntpmdoc)}
1904 @code{ntpd(1ntpdmdoc)}
1907 In either case the servers must be
1908 configured in advance and the program fails if none are
1909 available when the cron job runs.
1911 application of manycast is with
1912 @code{ntpd(1ntpdmdoc)}
1914 The program wakes up, scans the local landscape looking
1915 for the usual suspects, selects the best from among
1916 the rascals, sets the clock and then departs.
1917 Servers do not have to be configured in advance and
1918 all clients throughout the network can have the same
1920 @subsubsection Manycast Interactions with Autokey
1921 Each time a manycast client sends a client mode packet
1922 to a multicast group address, all manycast servers
1923 in scope generate a reply including the host name
1925 The manycast clients then run
1926 the Autokey protocol, which collects and verifies
1927 all certificates involved.
1928 Following the burst interval
1929 all but three survivors are cast off,
1930 but the certificates remain in the local cache.
1931 It often happens that several complete signing trails
1932 from the client to the primary servers are collected in this way.
1934 About once an hour or less often if the poll interval
1935 exceeds this, the client regenerates the Autokey key list.
1936 This is in general transparent in client/server mode.
1937 However, about once per day the server private value
1938 used to generate cookies is refreshed along with all
1939 manycast client associations.
1941 cryptographic values including certificates is refreshed.
1942 If a new certificate has been generated since
1943 the last refresh epoch, it will automatically revoke
1944 all prior certificates that happen to be in the
1946 At the same time, the manycast
1947 scheme starts all over from the beginning and
1948 the expanding ring shrinks to the minimum and increments
1949 from there while collecting all servers in scope.
1950 @subsubsection Broadcast Options
1952 @item @code{tos} @code{[@code{bcpollbstep} @kbd{gate}]}
1953 This command provides a way to delay,
1954 by the specified number of broadcast poll intervals,
1955 believing backward time steps from a broadcast server.
1956 Broadcast time networks are expected to be trusted.
1957 In the event a broadcast server's time is stepped backwards,
1958 there is clear benefit to having the clients notice this change
1959 as soon as possible.
1960 Attacks such as replay attacks can happen, however,
1961 and even though there are a number of protections built in to
1962 broadcast mode, attempts to perform a replay attack are possible.
1963 This value defaults to 0, but can be changed
1964 to any number of poll intervals between 0 and 4.
1966 @subsubsection Manycast Options
1968 @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}]}
1969 This command affects the clock selection and clustering
1971 It can be used to select the quality and
1972 quantity of peers used to synchronize the system clock
1973 and is most useful in manycast mode.
1974 The variables operate
1977 @item @code{ceiling} @kbd{ceiling}
1978 Peers with strata above
1980 will be discarded if there are at least
1983 This value defaults to 15, but can be changed
1984 to any number from 1 to 15.
1985 @item @code{cohort} @code{@{0 | 1@}}
1986 This is a binary flag which enables (0) or disables (1)
1987 manycast server replies to manycast clients with the same
1989 This is useful to reduce implosions where
1990 large numbers of clients with the same stratum level
1992 The default is to enable these replies.
1993 @item @code{floor} @kbd{floor}
1994 Peers with strata below
1996 will be discarded if there are at least
1999 This value defaults to 1, but can be changed
2000 to any number from 1 to 15.
2001 @item @code{minclock} @kbd{minclock}
2002 The clustering algorithm repeatedly casts out outlier
2003 associations until no more than
2005 associations remain.
2006 This value defaults to 3,
2007 but can be changed to any number from 1 to the number of
2009 @item @code{minsane} @kbd{minsane}
2010 This is the minimum number of candidates available
2011 to the clock selection algorithm in order to produce
2012 one or more truechimers for the clustering algorithm.
2013 If fewer than this number are available, the clock is
2014 undisciplined and allowed to run free.
2016 for legacy purposes.
2017 However, according to principles of
2018 Byzantine agreement,
2020 should be at least 4 in order to detect and discard
2021 a single falseticker.
2023 @item @code{ttl} @kbd{hop} @kbd{...}
2024 This command specifies a list of TTL values in increasing
2025 order, up to 8 values can be specified.
2026 In manycast mode these values are used in turn
2027 in an expanding-ring search.
2028 The default is eight
2029 multiples of 32 starting at 31.
2031 @node Reference Clock Support
2032 @subsection Reference Clock Support
2033 The NTP Version 4 daemon supports some three dozen different radio,
2034 satellite and modem reference clocks plus a special pseudo-clock
2035 used for backup or when no other clock source is available.
2036 Detailed descriptions of individual device drivers and options can
2038 "Reference Clock Drivers"
2040 (available as part of the HTML documentation
2042 @file{/usr/share/doc/ntp}).
2043 Additional information can be found in the pages linked
2044 there, including the
2045 "Debugging Hints for Reference Clock Drivers"
2047 "How To Write a Reference Clock Driver"
2049 (available as part of the HTML documentation
2051 @file{/usr/share/doc/ntp}).
2052 In addition, support for a PPS
2053 signal is available as described in the
2054 "Pulse-per-second (PPS) Signal Interfacing"
2056 (available as part of the HTML documentation
2058 @file{/usr/share/doc/ntp}).
2060 drivers support special line discipline/streams modules which can
2061 significantly improve the accuracy using the driver.
2064 "Line Disciplines and Streams Drivers"
2066 (available as part of the HTML documentation
2068 @file{/usr/share/doc/ntp}).
2070 A reference clock will generally (though not always) be a radio
2071 timecode receiver which is synchronized to a source of standard
2072 time such as the services offered by the NRC in Canada and NIST and
2074 The interface between the computer and the timecode
2075 receiver is device dependent, but is usually a serial port.
2077 device driver specific to each reference clock must be selected and
2078 compiled in the distribution; however, most common radio, satellite
2079 and modem clocks are included by default.
2080 Note that an attempt to
2081 configure a reference clock when the driver has not been compiled
2082 or the hardware port has not been appropriately configured results
2083 in a scalding remark to the system log file, but is otherwise non
2086 For the purposes of configuration,
2087 @code{ntpd(1ntpdmdoc)}
2089 reference clocks in a manner analogous to normal NTP peers as much
2091 Reference clocks are identified by a syntactically
2092 correct but invalid IP address, in order to distinguish them from
2094 Reference clock addresses are of the form
2095 @code{127.127.}@kbd{t}.@kbd{u},
2099 denoting the clock type and
2102 number in the range 0-3.
2103 While it may seem overkill, it is in fact
2104 sometimes useful to configure multiple reference clocks of the same
2105 type, in which case the unit numbers must be unique.
2109 command is used to configure a reference
2112 argument in that command
2113 is the clock address.
2119 options are not used for reference clock support.
2122 option is added for reference clock support, as
2126 option can be useful to
2127 persuade the server to cherish a reference clock with somewhat more
2128 enthusiasm than other reference clocks or peers.
2130 information on this option can be found in the
2131 "Mitigation Rules and the prefer Keyword"
2132 (available as part of the HTML documentation
2134 @file{/usr/share/doc/ntp})
2141 meaning only for selected clock drivers.
2142 See the individual clock
2143 driver document pages for additional information.
2147 command is used to provide additional
2148 information for individual clock drivers and normally follows
2149 immediately after the
2154 argument specifies the clock address.
2159 options can be used to
2160 override the defaults for the device.
2161 There are two optional
2162 device-dependent time offsets and four flags that can be included
2167 The stratum number of a reference clock is by default zero.
2169 @code{ntpd(1ntpdmdoc)}
2170 daemon adds one to the stratum of each
2171 peer, a primary server ordinarily displays an external stratum of
2173 In order to provide engineered backups, it is often useful to
2174 specify the reference clock stratum as greater than zero.
2177 option is used for this purpose.
2179 involving both a reference clock and a pulse-per-second (PPS)
2180 discipline signal, it is useful to specify the reference clock
2181 identifier as other than the default, depending on the driver.
2184 option is used for this purpose.
2186 these options apply to all clock drivers.
2187 @subsubsection Reference Clock Commands
2189 @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}]}
2190 This command can be used to configure reference clocks in
2192 The options are interpreted as follows:
2195 Marks the reference clock as preferred.
2196 All other things being
2197 equal, this host will be chosen for synchronization among a set of
2198 correctly operating hosts.
2200 "Mitigation Rules and the prefer Keyword"
2202 (available as part of the HTML documentation
2204 @file{/usr/share/doc/ntp})
2205 for further information.
2206 @item @code{mode} @kbd{int}
2207 Specifies a mode number which is interpreted in a
2208 device-specific fashion.
2209 For instance, it selects a dialing
2210 protocol in the ACTS driver and a device subtype in the
2213 @item @code{minpoll} @kbd{int}
2214 @item @code{maxpoll} @kbd{int}
2215 These options specify the minimum and maximum polling interval
2216 for reference clock messages, as a power of 2 in seconds
2218 most directly connected reference clocks, both
2222 default to 6 (64 s).
2223 For modem reference clocks,
2225 defaults to 10 (17.1 m) and
2227 defaults to 14 (4.5 h).
2228 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2230 @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}]}
2231 This command can be used to configure reference clocks in
2233 It must immediately follow the
2235 command which configures the driver.
2236 Note that the same capability
2237 is possible at run time using the
2238 @code{ntpdc(1ntpdcmdoc)}
2240 The options are interpreted as
2243 @item @code{time1} @kbd{sec}
2244 Specifies a constant to be added to the time offset produced by
2245 the driver, a fixed-point decimal number in seconds.
2247 as a calibration constant to adjust the nominal time offset of a
2248 particular clock to agree with an external standard, such as a
2249 precision PPS signal.
2250 It also provides a way to correct a
2251 systematic error or bias due to serial port or operating system
2252 latencies, different cable lengths or receiver internal delay.
2254 specified offset is in addition to the propagation delay provided
2255 by other means, such as internal DIPswitches.
2257 for an individual system and driver is available, an approximate
2258 correction is noted in the driver documentation pages.
2259 Note: in order to facilitate calibration when more than one
2260 radio clock or PPS signal is supported, a special calibration
2261 feature is available.
2262 It takes the form of an argument to the
2264 command described in
2265 @ref{Miscellaneous Options}
2266 page and operates as described in the
2267 "Reference Clock Drivers"
2269 (available as part of the HTML documentation
2271 @file{/usr/share/doc/ntp}).
2272 @item @code{time2} @kbd{secs}
2273 Specifies a fixed-point decimal number in seconds, which is
2274 interpreted in a driver-dependent way.
2275 See the descriptions of
2276 specific drivers in the
2277 "Reference Clock Drivers"
2279 (available as part of the HTML documentation
2281 @file{/usr/share/doc/ntp} @file{).}
2282 @item @code{stratum} @kbd{int}
2283 Specifies the stratum number assigned to the driver, an integer
2285 This number overrides the default stratum number
2286 ordinarily assigned by the driver itself, usually zero.
2287 @item @code{refid} @kbd{string}
2288 Specifies an ASCII string of from one to four characters which
2289 defines the reference identifier used by the driver.
2291 overrides the default identifier ordinarily assigned by the driver
2293 @item @code{mode} @kbd{int}
2294 Specifies a mode number which is interpreted in a
2295 device-specific fashion.
2296 For instance, it selects a dialing
2297 protocol in the ACTS driver and a device subtype in the
2300 @item @code{flag1} @code{0} @code{|} @code{1}
2301 @item @code{flag2} @code{0} @code{|} @code{1}
2302 @item @code{flag3} @code{0} @code{|} @code{1}
2303 @item @code{flag4} @code{0} @code{|} @code{1}
2304 These four flags are used for customizing the clock driver.
2306 interpretation of these values, and whether they are used at all,
2307 is a function of the particular clock driver.
2311 is used to enable recording monitoring
2314 file configured with the
2317 Further information on the
2319 command can be found in
2320 @ref{Monitoring Options}.
2323 @node Miscellaneous Options
2324 @subsection Miscellaneous Options
2326 @item @code{broadcastdelay} @kbd{seconds}
2327 The broadcast and multicast modes require a special calibration
2328 to determine the network delay between the local and remote
2330 Ordinarily, this is done automatically by the initial
2331 protocol exchanges between the client and server.
2333 the calibration procedure may fail due to network or server access
2334 controls, for example.
2335 This command specifies the default delay to
2336 be used under these circumstances.
2337 Typically (for Ethernet), a
2338 number between 0.003 and 0.007 seconds is appropriate.
2340 when this command is not used is 0.004 seconds.
2341 @item @code{calldelay} @kbd{delay}
2342 This option controls the delay in seconds between the first and second
2343 packets sent in burst or iburst mode to allow additional time for a modem
2344 or ISDN call to complete.
2345 @item @code{driftfile} @kbd{driftfile}
2346 This command specifies the complete path and name of the file used to
2347 record the frequency of the local clock oscillator.
2351 command line option.
2352 If the file exists, it is read at
2353 startup in order to set the initial frequency and then updated once per
2354 hour with the current frequency computed by the daemon.
2356 specified, but the file itself does not exist, the starts with an initial
2357 frequency of zero and creates the file when writing it for the first time.
2358 If this command is not given, the daemon will always start with an initial
2361 The file format consists of a single line containing a single
2362 floating point number, which records the frequency offset measured
2363 in parts-per-million (PPM).
2364 The file is updated by first writing
2365 the current drift value into a temporary file and then renaming
2366 this file to replace the old version.
2368 @code{ntpd(1ntpdmdoc)}
2369 must have write permission for the directory the
2370 drift file is located in, and that file system links, symbolic or
2371 otherwise, should be avoided.
2372 @item @code{dscp} @kbd{value}
2373 This option specifies the Differentiated Services Control Point (DSCP) value,
2375 The default value is 46, signifying Expedited Forwarding.
2376 @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}]}
2377 @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}]}
2378 Provides a way to enable or disable various server options.
2379 Flags not mentioned are unaffected.
2380 Note that all of these flags
2381 can be controlled remotely using the
2382 @code{ntpdc(1ntpdcmdoc)}
2386 Enables the server to synchronize with unconfigured peers only if the
2387 peer has been correctly authenticated using either public key or
2388 private key cryptography.
2389 The default for this flag is
2391 @item @code{bclient}
2392 Enables the server to listen for a message from a broadcast or
2393 multicast server, as in the
2394 @code{multicastclient}
2395 command with default
2397 The default for this flag is
2399 @item @code{calibrate}
2400 Enables the calibrate feature for reference clocks.
2405 Enables the kernel time discipline, if available.
2406 The default for this
2409 if support is available, otherwise
2412 Enables processing of NTP mode 7 implementation-specific requests
2413 which are used by the deprecated
2414 @code{ntpdc(1ntpdcmdoc)}
2416 The default for this flag is disable.
2417 This flag is excluded from runtime configuration using
2418 @code{ntpq(1ntpqmdoc)}.
2420 @code{ntpq(1ntpqmdoc)}
2421 program provides the same capabilities as
2422 @code{ntpdc(1ntpdcmdoc)}
2423 using standard mode 6 requests.
2424 @item @code{monitor}
2425 Enables the monitoring facility.
2427 @code{ntpdc(1ntpdcmdoc)}
2431 command or further information.
2433 default for this flag is
2436 Enables time and frequency discipline.
2437 In effect, this switch opens and
2438 closes the feedback loop, which is useful for testing.
2442 @item @code{peer_clear_digest_early}
2444 @code{ntpd(1ntpdmdoc)}
2445 is using autokey and it
2446 receives a crypto-NAK packet that
2447 passes the duplicate packet and origin timestamp checks
2448 the peer variables are immediately cleared.
2449 While this is generally a feature
2450 as it allows for quick recovery if a server key has changed,
2451 a properly forged and appropriately delivered crypto-NAK packet
2452 can be used in a DoS attack.
2453 If you have active noticable problems with this type of DoS attack
2454 then you should consider
2455 disabling this option.
2458 file for evidence of any of these attacks.
2460 default for this flag is
2463 Enables the statistics facility.
2465 @ref{Monitoring Options}
2466 section for further information.
2467 The default for this flag is
2469 @item @code{unpeer_crypto_early}
2471 @code{ntpd(1ntpdmdoc)}
2472 receives an autokey packet that fails TEST9,
2474 the association is immediately cleared.
2475 This is almost certainly a feature,
2476 but if, in spite of the current recommendation of not using autokey,
2481 you are seeing this sort of DoS attack
2482 disabling this flag will delay
2483 tearing down the association until the reachability counter
2487 file for evidence of any of these attacks.
2489 default for this flag is
2491 @item @code{unpeer_crypto_nak_early}
2493 @code{ntpd(1ntpdmdoc)}
2494 receives a crypto-NAK packet that
2495 passes the duplicate packet and origin timestamp checks
2496 the association is immediately cleared.
2497 While this is generally a feature
2498 as it allows for quick recovery if a server key has changed,
2499 a properly forged and appropriately delivered crypto-NAK packet
2500 can be used in a DoS attack.
2501 If you have active noticable problems with this type of DoS attack
2502 then you should consider
2503 disabling this option.
2506 file for evidence of any of these attacks.
2508 default for this flag is
2510 @item @code{unpeer_digest_early}
2512 @code{ntpd(1ntpdmdoc)}
2513 receives what should be an authenticated packet
2514 that passes other packet sanity checks but
2515 contains an invalid digest
2516 the association is immediately cleared.
2517 While this is generally a feature
2518 as it allows for quick recovery,
2519 if this type of packet is carefully forged and sent
2520 during an appropriate window it can be used for a DoS attack.
2521 If you have active noticable problems with this type of DoS attack
2522 then you should consider
2523 disabling this option.
2526 file for evidence of any of these attacks.
2528 default for this flag is
2531 @item @code{includefile} @kbd{includefile}
2532 This command allows additional configuration commands
2533 to be included from a separate file.
2535 be nested to a depth of five; upon reaching the end of any
2536 include file, command processing resumes in the previous
2538 This option is useful for sites that run
2539 @code{ntpd(1ntpdmdoc)}
2540 on multiple hosts, with (mostly) common options (e.g., a
2542 @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}]}]}
2545 directive controls which network addresses
2546 @code{ntpd(1ntpdmdoc)}
2547 opens, and whether input is dropped without processing.
2548 The first parameter determines the action for addresses
2549 which match the second parameter.
2550 The second parameter specifies a class of addresses,
2551 or a specific interface name,
2553 In the address case,
2555 determines how many bits must match for this rule to apply.
2557 prevents opening matching addresses,
2560 @code{ntpd(1ntpdmdoc)}
2561 to open the address and drop all received packets without examination.
2564 directives can be used.
2565 The last rule which matches a particular address determines the action for it.
2567 directives are disabled if any
2572 @code{--novirtualips}
2573 command-line options are specified in the configuration file,
2574 all available network addresses are opened.
2577 directive is an alias for
2579 @item @code{leapfile} @kbd{leapfile}
2580 This command loads the IERS leapseconds file and initializes the
2581 leapsecond values for the next leapsecond event, leapfile expiration
2582 time, and TAI offset.
2583 The file can be obtained directly from the IERS at
2584 @code{https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list}
2586 @code{ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list}.
2590 @code{ntpd(1ntpdmdoc)}
2592 @code{leapfile} @code{directive} @code{or} @code{when}
2593 @code{ntpd} @code{detects} @code{that} @code{the}
2597 checks once a day to see if the
2601 @code{update-leap(1update_leapmdoc)}
2602 script can be run to see if the
2605 @item @code{leapsmearinterval} @kbd{seconds}
2606 This EXPERIMENTAL option is only available if
2607 @code{ntpd(1ntpdmdoc)}
2609 @code{--enable-leap-smear}
2613 It specifies the interval over which a leap second correction will be applied.
2614 Recommended values for this option are between
2615 7200 (2 hours) and 86400 (24 hours).
2616 .Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!
2617 See http://bugs.ntp.org/2855 for more information.
2618 @item @code{logconfig} @kbd{configkeyword}
2619 This command controls the amount and type of output written to
2622 facility or the alternate
2625 By default, all output is turned on.
2628 keywords can be prefixed with
2629 @quoteleft{}=@quoteright{},
2630 @quoteleft{}+@quoteright{}
2632 @quoteleft{}-@quoteright{},
2634 @quoteleft{}=@quoteright{}
2638 @quoteleft{}+@quoteright{}
2640 @quoteleft{}-@quoteright{}
2644 messages can be controlled in four
2646 (@code{clock}, @code{peer}, @code{sys} and @code{sync}).
2647 Within these classes four types of messages can be
2648 controlled: informational messages
2658 Configuration keywords are formed by concatenating the message class with
2662 prefix can be used instead of a message class.
2664 message class may also be followed by the
2666 keyword to enable/disable all
2667 messages of the respective message class.
2668 Thus, a minimal log configuration
2669 could look like this:
2671 logconfig =syncstatus +sysevents
2674 This would just list the synchronizations state of
2675 @code{ntpd(1ntpdmdoc)}
2676 and the major system events.
2677 For a simple reference server, the
2678 following minimum message configuration could be useful:
2680 logconfig =syncall +clockall
2683 This configuration will list all clock information and
2684 synchronization information.
2685 All other events and messages about
2686 peers, system events and so on is suppressed.
2687 @item @code{logfile} @kbd{logfile}
2688 This command specifies the location of an alternate log file to
2689 be used instead of the default system
2692 This is the same operation as the
2694 command line option.
2695 @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}]}
2696 Controls size limite of the monitoring facility's Most Recently Used
2698 of client addresses, which is also used by the
2699 rate control facility.
2701 @item @code{maxdepth} @kbd{count}
2702 @item @code{maxmem} @kbd{kilobytes}
2703 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2704 The acutal limit will be up to
2711 options offered in units of entries or kilobytes, if both
2714 @code{maxmem} @code{are} @code{used,} @code{the} @code{last} @code{one} @code{used} @code{controls.}
2715 The default is 1024 kilobytes.
2716 @item @code{mindepth} @kbd{count}
2717 Lower limit on the MRU list size.
2718 When the MRU list has fewer than
2720 entries, existing entries are never removed to make room for newer ones,
2721 regardless of their age.
2722 The default is 600 entries.
2723 @item @code{maxage} @kbd{seconds}
2724 Once the MRU list has
2726 entries and an additional client is to ba added to the list,
2727 if the oldest entry was updated more than
2729 seconds ago, that entry is removed and its storage is reused.
2730 If the oldest entry was updated more recently the MRU list is grown,
2732 @code{maxdepth} @code{/} @code{moxmem}.
2733 The default is 64 seconds.
2734 @item @code{initalloc} @kbd{count}
2735 @item @code{initmem} @kbd{kilobytes}
2736 Initial memory allocation at the time the monitoringfacility is first enabled,
2737 in terms of the number of entries or kilobytes.
2738 The default is 4 kilobytes.
2739 @item @code{incalloc} @kbd{count}
2740 @item @code{incmem} @kbd{kilobytes}
2741 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2742 The default is 4 kilobytes.
2744 @item @code{nonvolatile} @kbd{threshold}
2747 delta in seconds before an hourly change to the
2749 (frequency file) will be written, with a default value of 1e-7 (0.1 PPM).
2750 The frequency file is inspected each hour.
2751 If the difference between the current frequency and the last value written
2752 exceeds the threshold, the file is written and the
2754 becomes the new threshold value.
2755 If the threshold is not exceeeded, it is reduced by half.
2756 This is intended to reduce the number of file writes
2757 for embedded systems with nonvolatile memory.
2758 @item @code{phone} @kbd{dial} @kbd{...}
2759 This command is used in conjunction with
2760 the ACTS modem driver (type 18)
2761 or the JJY driver (type 40, mode 100 - 180).
2762 For the ACTS modem driver (type 18), the arguments consist of
2763 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2765 For the JJY driver (type 40 mode 100 - 180), the argument is
2766 one telephone number used to dial the telephone JJY service.
2767 The Hayes command ATDT is normally prepended to the number.
2768 The number can contain other modem control codes as well.
2769 @item @code{reset} @code{[@code{allpeers}]} @code{[@code{auth}]} @code{[@code{ctl}]} @code{[@code{io}]} @code{[@code{mem}]} @code{[@code{sys}]} @code{[@code{timer}]}
2770 Reset one or more groups of counters maintained by
2776 @item @code{rlimit} @code{[@code{memlock} @kbd{Nmegabytes} | @code{stacksize} @kbd{N4kPages} @code{filenum} @kbd{Nfiledescriptors}]}
2778 @item @code{memlock} @kbd{Nmegabytes}
2779 Specify the number of megabytes of memory that should be
2780 allocated and locked.
2781 Probably only available under Linux, this option may be useful
2782 when dropping root (the
2785 The default is 32 megabytes on non-Linux machines, and -1 under Linux.
2786 -1 means "do not lock the process into memory".
2787 0 means "lock whatever memory the process wants into memory".
2788 @item @code{stacksize} @kbd{N4kPages}
2789 Specifies the maximum size of the process stack on systems with the
2792 Defaults to 50 4k pages (200 4k pages in OpenBSD).
2793 @item @code{filenum} @kbd{Nfiledescriptors}
2794 Specifies the maximum number of file descriptors ntpd may have open at once.
2795 Defaults to the system default.
2797 @item @code{saveconfigdir} @kbd{directory_path}
2798 Specify the directory in which to write configuration snapshots
2804 @code{saveconfigdir}
2805 does not appear in the configuration file,
2807 requests are rejected by
2809 @item @code{saveconfig} @kbd{filename}
2810 Write the current configuration, including any runtime
2811 modifications given with
2814 @code{config-from-file}
2820 @code{saveconfigdir}.
2821 This command will be rejected unless the
2822 @code{saveconfigdir}
2823 directive appears in
2829 format directives to substitute the current date and time,
2831 @code{saveconfig\ ntp-%Y%m%d-%H%M%S.conf}.
2832 The filename used is stored in the system variable
2834 Authentication is required.
2835 @item @code{setvar} @kbd{variable} @code{[@code{default}]}
2836 This command adds an additional system variable.
2838 variables can be used to distribute additional information such as
2840 If the variable of the form
2841 @code{name}@code{=}@kbd{value}
2845 variable will be listed as part of the default system variables
2846 (@code{rv} command)).
2847 These additional variables serve
2848 informational purposes only.
2849 They are not related to the protocol
2850 other that they can be listed.
2851 The known protocol variables will
2852 always override any variables defined via the
2855 There are three special variables that contain the names
2856 of all variable of the same group.
2860 the names of all system variables.
2862 @code{peer_var_list}
2864 the names of all peer variables and the
2865 @code{clock_var_list}
2866 holds the names of the reference clock variables.
2867 @item @code{sysinfo}
2868 Display operational summary.
2869 @item @code{sysstats}
2870 Show statistics counters maintained in the protocol module.
2871 @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}]}
2872 This command can be used to alter several system variables in
2873 very exceptional circumstances.
2874 It should occur in the
2875 configuration file before any other configuration options.
2877 default values of these variables have been carefully optimized for
2878 a wide range of network speeds and reliability expectations.
2880 general, they interact in intricate ways that are hard to predict
2881 and some combinations can result in some very nasty behavior.
2883 rarely is it necessary to change the default values; but, some
2884 folks cannot resist twisting the knobs anyway and this command is
2886 Emphasis added: twisters are on their own and can expect
2887 no help from the support group.
2889 The variables operate as follows:
2891 @item @code{allan} @kbd{allan}
2892 The argument becomes the new value for the minimum Allan
2893 intercept, which is a parameter of the PLL/FLL clock discipline
2895 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
2897 @item @code{dispersion} @kbd{dispersion}
2898 The argument becomes the new value for the dispersion increase rate,
2899 normally .000015 s/s.
2900 @item @code{freq} @kbd{freq}
2901 The argument becomes the initial value of the frequency offset in
2903 This overrides the value in the frequency file, if
2904 present, and avoids the initial training state if it is not.
2905 @item @code{huffpuff} @kbd{huffpuff}
2906 The argument becomes the new value for the experimental
2907 huff-n'-puff filter span, which determines the most recent interval
2908 the algorithm will search for a minimum delay.
2910 900 s (15 m), but a more reasonable value is 7200 (2 hours).
2912 is no default, since the filter is not enabled unless this command
2914 @item @code{panic} @kbd{panic}
2915 The argument is the panic threshold, normally 1000 s.
2917 the panic sanity check is disabled and a clock offset of any value will
2919 @item @code{step} @kbd{step}
2920 The argument is the step threshold, which by default is 0.128 s.
2922 be set to any positive number in seconds.
2923 If set to zero, step
2924 adjustments will never occur.
2925 Note: The kernel time discipline is
2926 disabled if the step threshold is set to zero or greater than the
2928 @item @code{stepback} @kbd{stepback}
2929 The argument is the step threshold for the backward direction,
2930 which by default is 0.128 s.
2932 be set to any positive number in seconds.
2933 If both the forward and backward step thresholds are set to zero, step
2934 adjustments will never occur.
2935 Note: The kernel time discipline is
2937 each direction of step threshold are either
2938 set to zero or greater than .5 second.
2939 @item @code{stepfwd} @kbd{stepfwd}
2940 As for stepback, but for the forward direction.
2941 @item @code{stepout} @kbd{stepout}
2942 The argument is the stepout timeout, which by default is 900 s.
2944 be set to any positive number in seconds.
2945 If set to zero, the stepout
2946 pulses will not be suppressed.
2948 @item @code{writevar} @kbd{assocID\ name} @kbd{=} @kbd{value} @kbd{[,...]}
2949 Write (create or update) the specified variables.
2952 is zero, the variablea re from the
2954 name space, otherwise they are from the
2959 is required, as the same name can occur in both name spaces.
2960 @item @code{trap} @kbd{host_address} @code{[@code{port} @kbd{port_number}]} @code{[@code{interface} @kbd{interface_address}]}
2961 This command configures a trap receiver at the given host
2962 address and port number for sending messages with the specified
2963 local interface address.
2964 If the port number is unspecified, a value
2966 If the interface address is not specified, the
2967 message is sent with a source address of the local interface the
2968 message is sent through.
2969 Note that on a multihomed host the
2970 interface used may vary from time to time with routing changes.
2971 @item @code{ttl} @kbd{hop} @kbd{...}
2972 This command specifies a list of TTL values in increasing order.
2973 Up to 8 values can be specified.
2976 mode these values are used in-turn in an expanding-ring search.
2977 The default is eight multiples of 32 starting at 31.
2979 The trap receiver will generally log event messages and other
2980 information from the server in a log file.
2982 programs may also request their own trap dynamically, configuring a
2983 trap receiver will ensure that no messages are lost when the server
2985 @item @code{hop} @kbd{...}
2986 This command specifies a list of TTL values in increasing order, up to 8
2987 values can be specified.
2988 In manycast mode these values are used in turn in
2989 an expanding-ring search.
2990 The default is eight multiples of 32 starting at
2994 This section was generated by @strong{AutoGen},
2995 using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program.
2996 This software is released under the NTP license, <http://ntp.org/license>.
2999 * ntp.conf Files:: Files
3000 * ntp.conf See Also:: See Also
3001 * ntp.conf Bugs:: Bugs
3002 * ntp.conf Notes:: Notes
3005 @node ntp.conf Files
3006 @subsection ntp.conf Files
3008 @item @file{/etc/ntp.conf}
3009 the default name of the configuration file
3010 @item @file{ntp.keys}
3014 @item @file{ntpkey_}@kbd{host}
3017 Diffie-Hellman agreement parameters
3019 @node ntp.conf See Also
3020 @subsection ntp.conf See Also
3021 @code{ntpd(1ntpdmdoc)},
3022 @code{ntpdc(1ntpdcmdoc)},
3023 @code{ntpq(1ntpqmdoc)}
3025 In addition to the manual pages provided,
3026 comprehensive documentation is available on the world wide web
3028 @code{http://www.ntp.org/}.
3029 A snapshot of this documentation is available in HTML format in
3030 @file{/usr/share/doc/ntp}.
3034 David L. Mills, @emph{Network Time Protocol (Version 4)}, RFC5905
3036 @subsection ntp.conf Bugs
3037 The syntax checking is not picky; some combinations of
3038 ridiculous and even hilarious options and modes may not be
3042 @file{ntpkey_}@kbd{host}
3043 files are really digital
3045 These should be obtained via secure directory
3046 services when they become universally available.
3047 @node ntp.conf Notes
3048 @subsection ntp.conf Notes
3049 This document was derived from FreeBSD.