9 .Nd Network Time Protocol (NTP) daemon configuration file
15 configuration file is read at initial startup by the
17 daemon in order to specify the synchronization sources,
18 modes and other related information.
19 Usually, it is installed in the
22 but could be installed elsewhere
29 script reads this file to get a list of NTP servers to use if the
35 man page for further info about this.
37 The file format is similar to other
42 character and extend to the end of the line;
43 blank lines are ignored.
44 Configuration commands consist of an initial keyword
45 followed by a list of arguments,
46 some of which may be optional, separated by whitespace.
47 Commands may not be continued over multiple lines.
48 Arguments may be host names,
49 host addresses written in numeric, dotted-quad form,
50 integers, floating point numbers (when specifying times in seconds)
53 The rest of this page describes the configuration and control options.
55 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
57 (available as part of the HTML documentation
59 .Pa /usr/share/doc/ntp )
60 contains an extended discussion of these options.
61 In addition to the discussion of general
62 .Sx Configuration Options ,
63 there are sections describing the following supported functionality
64 and the options used to control it:
65 .Bl -bullet -offset indent
67 .Sx Authentication Support
69 .Sx Monitoring Support
71 .Sx Access Control Support
73 .Sx Automatic NTP Configuration Options
75 .Sx Reference Clock Support
77 .Sx Miscellaneous Options
80 Following these is a section describing
81 .Sx Miscellaneous Options .
82 While there is a rich set of options available,
83 the only required option is one or more
90 .Sh Configuration Support
91 Following is a description of the configuration commands in
93 These commands have the same basic functions as in NTPv3 and
94 in some cases new functions and new arguments.
96 classes of commands, configuration commands that configure a
97 persistent association with a remote server or peer or reference
98 clock, and auxiliary commands that specify environmental variables
99 that control various related operations.
100 .Ss Configuration Commands
101 The various modes are determined by the command keyword and the
102 type of the required IP address.
103 Addresses are classed by type as
104 (s) a remote server or peer (IPv4 class A, B and C), (b) the
105 broadcast address of a local interface, (m) a multicast address (IPv4
106 class D), or (r) a reference clock address (127.127.x.x).
108 only those options applicable to each command are listed below.
110 of options not listed may not be caught as an error, but may result
111 in some weird and even destructive behavior.
113 If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
114 is detected, support for the IPv6 address family is generated
115 in addition to the default support of the IPv4 address family.
116 In a few cases, including the reslist billboard generated
117 by ntpdc, IPv6 addresses are automatically generated.
118 IPv6 addresses can be identified by the presence of colons
120 in the address field.
121 IPv6 addresses can be used almost everywhere where
122 IPv4 addresses can be used,
123 with the exception of reference clock addresses,
124 which are always IPv4.
126 Note that in contexts where a host name is expected, a
129 the host name forces DNS resolution to the IPv4 namespace,
132 qualifier forces DNS resolution to the IPv6 namespace.
133 See IPv6 references for the
134 equivalent classes for that address family.
135 .Bl -tag -width indent
136 .It Xo Ic server Ar address
137 .Op Cm key Ar key \&| Cm autokey
140 .Op Cm version Ar version
142 .Op Cm minpoll Ar minpoll
143 .Op Cm maxpoll Ar maxpoll
145 .It Xo Ic peer Ar address
146 .Op Cm key Ar key \&| Cm autokey
147 .Op Cm version Ar version
149 .Op Cm minpoll Ar minpoll
150 .Op Cm maxpoll Ar maxpoll
152 .It Xo Ic broadcast Ar address
153 .Op Cm key Ar key \&| Cm autokey
154 .Op Cm version Ar version
156 .Op Cm minpoll Ar minpoll
159 .It Xo Ic manycastclient Ar address
160 .Op Cm key Ar key \&| Cm autokey
161 .Op Cm version Ar version
163 .Op Cm minpoll Ar minpoll
164 .Op Cm maxpoll Ar maxpoll
169 These four commands specify the time server name or address to
170 be used and the mode in which to operate.
174 either a DNS name or an IP address in dotted-quad notation.
175 Additional information on association behavior can be found in the
176 .Qq Association Management
178 (available as part of the HTML documentation
180 .Pa /usr/share/doc/ntp ) .
181 .Bl -tag -width indent
183 For type s and r addresses, this command mobilizes a persistent
184 client mode association with the specified remote server or local
186 In this mode the local clock can synchronized to the
187 remote server, but the remote server can never be synchronized to
194 For type s addresses (only), this command mobilizes a
195 persistent symmetric-active mode association with the specified
197 In this mode the local clock can be synchronized to
198 the remote peer or the remote peer can be synchronized to the local
200 This is useful in a network of servers where, depending on
201 various failure scenarios, either the local or remote peer may be
202 the better source of time.
203 This command should NOT be used for type
206 For type b and m addresses (only), this
207 command mobilizes a persistent broadcast mode association.
209 commands can be used to specify multiple local broadcast interfaces
210 (subnets) and/or multiple multicast groups.
212 broadcast messages go only to the interface associated with the
213 subnet specified, but multicast messages go to all interfaces.
214 In broadcast mode the local server sends periodic broadcast
215 messages to a client population at the
217 specified, which is usually the broadcast address on (one of) the
218 local network(s) or a multicast address assigned to NTP.
220 has assigned the multicast group address IPv4 224.0.1.1 and
221 IPv6 ff05::101 (site local) exclusively to
222 NTP, but other nonconflicting addresses can be used to contain the
223 messages within administrative boundaries.
225 specification applies only to the local server operating as a
226 sender; for operation as a broadcast client, see the
232 .It Ic manycastclient
233 For type m addresses (only), this command mobilizes a
234 manycast client mode association for the multicast address
236 In this case a specific address must be supplied which
237 matches the address used on the
240 the designated manycast servers.
241 The NTP multicast address
242 224.0.1.1 assigned by the IANA should NOT be used, unless specific
243 means are taken to avoid spraying large areas of the Internet with
244 these messages and causing a possibly massive implosion of replies
248 command specifies that the local server
249 is to operate in client mode with the remote servers that are
250 discovered as the result of broadcast/multicast messages.
252 client broadcasts a request message to the group address associated
255 and specifically enabled
256 servers respond to these messages.
257 The client selects the servers
258 providing the best time and continues as with the
261 The remaining servers are discarded as if never
266 .Bl -tag -width indent
268 All packets sent to and received from the server or peer are to
269 include authentication fields encrypted using the autokey scheme
271 .Sx Authentication Commands .
273 when the server is reachable, send a burst of eight packets
274 instead of the usual one.
275 The packet spacing is normally 2 s;
276 however, the spacing between the first and second packets
277 can be changed with the calldelay command to allow
278 additional time for a modem or ISDN call to complete.
279 This is designed to improve timekeeping quality
282 command and s addresses.
284 When the server is unreachable, send a burst of eight packets
285 instead of the usual one.
286 The packet spacing is normally 2 s;
287 however, the spacing between the first two packets can be
288 changed with the calldelay command to allow
289 additional time for a modem or ISDN call to complete.
290 This is designed to speed the initial synchronization
293 command and s addresses and when
299 All packets sent to and received from the server or peer are to
300 include authentication fields encrypted using the specified
302 identifier with values from 1 to 65534, inclusive.
304 default is to include no encryption field.
305 .It Cm minpoll Ar minpoll
306 .It Cm maxpoll Ar maxpoll
307 These options specify the minimum and maximum poll intervals
308 for NTP messages, as a power of 2 in seconds.
310 interval defaults to 10 (1,024 s), but can be increased by the
312 option to an upper limit of 17 (36.4 h).
314 minimum poll interval defaults to 6 (64 s), but can be decreased by
317 option to a lower limit of 4 (16 s).
319 Marks the server as unused, except for display purposes.
320 The server is discarded by the selection algorithm.
322 Marks the server as preferred.
323 All other things being equal,
324 this host will be chosen for synchronization among a set of
325 correctly operating hosts.
327 .Qq Mitigation Rules and the prefer Keyword
329 (available as part of the HTML documentation
331 .Pa /usr/share/doc/ntp )
332 for further information.
334 This option is used only with broadcast server and manycast
336 It specifies the time-to-live
339 use on broadcast server and multicast server and the maximum
341 for the expanding ring search with manycast
343 Selection of the proper value, which defaults to
344 127, is something of a black art and should be coordinated with the
345 network administrator.
346 .It Cm version Ar version
347 Specifies the version number to be used for outgoing NTP
349 Versions 1-4 are the choices, with version 4 the
352 .Ss Auxiliary Commands
353 .Bl -tag -width indent
354 .It Ic broadcastclient
355 This command enables reception of broadcast server messages to
356 any local interface (type b) address.
357 Upon receiving a message for
358 the first time, the broadcast client measures the nominal server
359 propagation delay using a brief client/server exchange with the
360 server, then enters the broadcast client mode, in which it
361 synchronizes to succeeding broadcast messages.
363 to avoid accidental or malicious disruption in this mode, both the
364 server and client should operate using symmetric-key or public-key
365 authentication as described in
366 .Sx Authentication Commands .
367 .It Ic manycastserver Ar address ...
368 This command enables reception of manycast client messages to
369 the multicast group address(es) (type m) specified.
371 address is required, but the NTP multicast address 224.0.1.1
372 assigned by the IANA should NOT be used, unless specific means are
373 taken to limit the span of the reply and avoid a possibly massive
374 implosion at the original sender.
375 Note that, in order to avoid
376 accidental or malicious disruption in this mode, both the server
377 and client should operate using symmetric-key or public-key
378 authentication as described in
379 .Sx Authentication Commands .
380 .It Ic multicastclient Ar address ...
381 This command enables reception of multicast server messages to
382 the multicast group address(es) (type m) specified.
384 a message for the first time, the multicast client measures the
385 nominal server propagation delay using a brief client/server
386 exchange with the server, then enters the broadcast client mode, in
387 which it synchronizes to succeeding multicast messages.
389 in order to avoid accidental or malicious disruption in this mode,
390 both the server and client should operate using symmetric-key or
391 public-key authentication as described in
392 .Sx Authentication Commands .
394 .Sh Authentication Support
395 Authentication support allows the NTP client to verify that the
396 server is in fact known and trusted and not an intruder intending
397 accidentally or on purpose to masquerade as that server.
399 specification RFC-1305 defines a scheme which provides
400 cryptographic authentication of received NTP packets.
402 this was done using the Data Encryption Standard (DES) algorithm
403 operating in Cipher Block Chaining (CBC) mode, commonly called
405 Subsequently, this was replaced by the RSA Message Digest
406 5 (MD5) algorithm using a private key, commonly called keyed-MD5.
407 Either algorithm computes a message digest, or one-way hash, which
408 can be used to verify the server has the correct private key and
411 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
412 cryptography and, in addition, provides a new Autokey scheme
413 based on public key cryptography.
414 Public key cryptography is generally considered more secure
415 than symmetric key cryptography, since the security is based
416 on a private value which is generated by each server and
418 With Autokey all key distribution and
419 management functions involve only public values, which
420 considerably simplifies key distribution and storage.
421 Public key management is based on X.509 certificates,
422 which can be provided by commercial services or
423 produced by utility programs in the OpenSSL software library
424 or the NTPv4 distribution.
426 While the algorithms for symmetric key cryptography are
427 included in the NTPv4 distribution, public key cryptography
428 requires the OpenSSL software library to be installed
429 before building the NTP distribution.
430 Directions for doing that
431 are on the Building and Installing the Distribution page.
433 Authentication is configured separately for each association
444 configuration commands as described in
445 .Sx Configuration Options
448 options described below specify the locations of the key files,
449 if other than default, which symmetric keys are trusted
450 and the interval between various operations, if other than default.
452 Authentication is always enabled,
453 although ineffective if not configured as
455 If a NTP packet arrives
456 including a message authentication
457 code (MAC), it is accepted only if it
458 passes all cryptographic checks.
460 checks require correct key ID, key value
463 been modified in any way or replayed
464 by an intruder, it will fail one or more
465 of these checks and be discarded.
466 Furthermore, the Autokey scheme requires a
467 preliminary protocol exchange to obtain
468 the server certificate, verify its
469 credentials and initialize the protocol.
473 flag controls whether new associations or
474 remote configuration commands require cryptographic authentication.
475 This flag can be set or reset by the
479 commands and also by remote
480 configuration commands sent by a
484 If this flag is enabled, which is the default
485 case, new broadcast client and symmetric passive associations and
486 remote configuration commands must be cryptographically
487 authenticated using either symmetric key or public key cryptography.
489 flag is disabled, these operations are effective
490 even if not cryptographic
492 It should be understood
493 that operating with the
495 flag disabled invites a significant vulnerability
496 where a rogue hacker can
497 masquerade as a falseticker and seriously
498 disrupt system timekeeping.
500 important to note that this flag has no purpose
501 other than to allow or disallow
502 a new association in response to new broadcast
503 and symmetric active messages
504 and remote configuration commands and, in particular,
505 the flag has no effect on
506 the authentication process itself.
508 An attractive alternative where multicast support is available
509 is manycast mode, in which clients periodically troll
510 for servers as described in the
511 .Sx Automatic NTP Configuration Options
513 Either symmetric key or public key
514 cryptographic authentication can be used in this mode.
515 The principle advantage
516 of manycast mode is that potential servers need not be
517 configured in advance,
518 since the client finds them during regular operation,
519 and the configuration
520 files for all clients can be identical.
522 The security model and protocol schemes for
523 both symmetric key and public key
524 cryptography are summarized below;
525 further details are in the briefings, papers
526 and reports at the NTP project page linked from
527 .Li http://www.ntp.org/ .
528 .Ss Symmetric-Key Cryptography
529 The original RFC-1305 specification allows any one of possibly
530 65,534 keys, each distinguished by a 32-bit key identifier, to
531 authenticate an association.
532 The servers and clients involved must
533 agree on the key and key identifier to
534 authenticate NTP packets.
536 related information are specified in a key
539 which must be distributed and stored using
540 secure means beyond the scope of the NTP protocol itself.
541 Besides the keys used
542 for ordinary NTP associations,
543 additional keys can be used as passwords for the
551 is first started, it reads the key file specified in the
553 configuration command and installs the keys
556 individual keys must be activated with the
560 allows, for instance, the installation of possibly
561 several batches of keys and
562 then activating or deactivating each batch
565 This also provides a revocation capability that can be used
566 if a key becomes compromised.
569 command selects the key used as the password for the
573 command selects the key used as the password for the
576 .Ss Public Key Cryptography
577 NTPv4 supports the original NTPv3 symmetric key scheme
578 described in RFC-1305 and in addition the Autokey protocol,
579 which is based on public key cryptography.
580 The Autokey Version 2 protocol described on the Autokey Protocol
581 page verifies packet integrity using MD5 message digests
582 and verifies the source with digital signatures and any of several
583 digest/signature schemes.
584 Optional identity schemes described on the Identity Schemes
585 page and based on cryptographic challenge/response algorithms
587 Using all of these schemes provides strong security against
588 replay with or without modification, spoofing, masquerade
589 and most forms of clogging attacks.
591 .\" The cryptographic means necessary for all Autokey operations
592 .\" is provided by the OpenSSL software library.
593 .\" This library is available from http://www.openssl.org/
594 .\" and can be installed using the procedures outlined
595 .\" in the Building and Installing the Distribution page.
597 .\" the configure and build
598 .\" process automatically detects the library and links
599 .\" the library routines required.
601 The Autokey protocol has several modes of operation
602 corresponding to the various NTP modes supported.
603 Most modes use a special cookie which can be
604 computed independently by the client and server,
605 but encrypted in transmission.
606 All modes use in addition a variant of the S-KEY scheme,
607 in which a pseudo-random key list is generated and used
609 These schemes are described along with an executive summary,
610 current status, briefing slides and reading list on the
611 .Sx Autonomous Authentication
614 The specific cryptographic environment used by Autokey servers
615 and clients is determined by a set of files
616 and soft links generated by the
619 This includes a required host key file,
620 required certificate file and optional sign key file,
621 leapsecond file and identity scheme files.
623 digest/signature scheme is specified in the X.509 certificate
624 along with the matching sign key.
625 There are several schemes
626 available in the OpenSSL software library, each identified
627 by a specific string such as
628 .Cm md5WithRSAEncryption ,
629 which stands for the MD5 message digest with RSA
631 The current NTP distribution supports
632 all the schemes in the OpenSSL library, including
633 those based on RSA and DSA digital signatures.
635 NTP secure groups can be used to define cryptographic compartments
636 and security hierarchies.
637 It is important that every host
638 in the group be able to construct a certificate trail to one
639 or more trusted hosts in the same group.
641 host runs the Autokey protocol to obtain the certificates
642 for all hosts along the trail to one or more trusted hosts.
643 This requires the configuration file in all hosts to be
644 engineered so that, even under anticipated failure conditions,
645 the NTP subnet will form such that every group host can find
646 a trail to at least one trusted host.
647 .Ss Naming and Addressing
648 It is important to note that Autokey does not use DNS to
649 resolve addresses, since DNS can't be completely trusted
650 until the name servers have synchronized clocks.
651 The cryptographic name used by Autokey to bind the host identity
652 credentials and cryptographic values must be independent
653 of interface, network and any other naming convention.
654 The name appears in the host certificate in either or both
655 the subject and issuer fields, so protection against
656 DNS compromise is essential.
658 By convention, the name of an Autokey host is the name returned
661 system call or equivalent in other systems.
663 model, there are no provisions to allow alternate names or aliases.
664 However, this is not to say that DNS aliases, different names
665 for each interface, etc., are constrained in any way.
667 It is also important to note that Autokey verifies authenticity
668 using the host name, network address and public keys,
669 all of which are bound together by the protocol specifically
670 to deflect masquerade attacks.
671 For this reason Autokey
672 includes the source and destination IP addresses in message digest
673 computations and so the same addresses must be available
674 at both the server and client.
675 For this reason operation
676 with network address translation schemes is not possible.
677 This reflects the intended robust security model where government
678 and corporate NTP servers are operated outside firewall perimeters.
680 A specific combination of authentication scheme (none,
681 symmetric key, public key) and identity scheme is called
682 a cryptotype, although not all combinations are compatible.
683 There may be management configurations where the clients,
684 servers and peers may not all support the same cryptotypes.
685 A secure NTPv4 subnet can be configured in many ways while
686 keeping in mind the principles explained above and
688 Note however that some cryptotype
689 combinations may successfully interoperate with each other,
690 but may not represent good security practice.
692 The cryptotype of an association is determined at the time
693 of mobilization, either at configuration time or some time
694 later when a message of appropriate cryptotype arrives.
699 configuration command and no
703 subcommands are present, the association is not
704 authenticated; if the
706 subcommand is present, the association is authenticated
707 using the symmetric key ID specified; if the
709 subcommand is present, the association is authenticated
712 When multiple identity schemes are supported in the Autokey
713 protocol, the first message exchange determines which one is used.
714 The client request message contains bits corresponding
715 to which schemes it has available.
716 The server response message
717 contains bits corresponding to which schemes it has available.
718 Both server and client match the received bits with their own
719 and select a common scheme.
721 Following the principle that time is a public value,
722 a server responds to any client packet that matches
723 its cryptotype capabilities.
724 Thus, a server receiving
725 an unauthenticated packet will respond with an unauthenticated
726 packet, while the same server receiving a packet of a cryptotype
727 it supports will respond with packets of that cryptotype.
728 However, unconfigured broadcast or manycast client
729 associations or symmetric passive associations will not be
730 mobilized unless the server supports a cryptotype compatible
731 with the first packet received.
732 By default, unauthenticated associations will not be mobilized
733 unless overridden in a decidedly dangerous way.
735 Some examples may help to reduce confusion.
736 Client Alice has no specific cryptotype selected.
737 Server Bob has both a symmetric key file and minimal Autokey files.
738 Alice's unauthenticated messages arrive at Bob, who replies with
739 unauthenticated messages.
740 Cathy has a copy of Bob's symmetric
741 key file and has selected key ID 4 in messages to Bob.
742 Bob verifies the message with his key ID 4.
744 same key and the message is verified, Bob sends Cathy a reply
745 authenticated with that key.
746 If verification fails,
747 Bob sends Cathy a thing called a crypto-NAK, which tells her
749 She can see the evidence using the ntpq program.
751 Denise has rolled her own host key and certificate.
752 She also uses one of the identity schemes as Bob.
753 She sends the first Autokey message to Bob and they
754 both dance the protocol authentication and identity steps.
755 If all comes out okay, Denise and Bob continue as described above.
757 It should be clear from the above that Bob can support
758 all the girls at the same time, as long as he has compatible
759 authentication and identity credentials.
760 Now, Bob can act just like the girls in his own choice of servers;
761 he can run multiple configured associations with multiple different
762 servers (or the same server, although that might not be useful).
763 But, wise security policy might preclude some cryptotype
764 combinations; for instance, running an identity scheme
765 with one server and no authentication with another might not be wise.
767 The cryptographic values used by the Autokey protocol are
768 incorporated as a set of files generated by the
770 utility program, including symmetric key, host key and
771 public certificate files, as well as sign key, identity parameters
772 and leapseconds files.
773 Alternatively, host and sign keys and
774 certificate files can be generated by the OpenSSL utilities
775 and certificates can be imported from public certificate
777 Note that symmetric keys are necessary for the
782 The remaining files are necessary only for the
785 Certificates imported from OpenSSL or public certificate
786 authorities have certain limitations.
787 The certificate should be in ASN.1 syntax, X.509 Version 3
788 format and encoded in PEM, which is the same format
790 The overall length of the certificate encoded
791 in ASN.1 must not exceed 1024 bytes.
792 The subject distinguished
793 name field (CN) is the fully qualified name of the host
794 on which it is used; the remaining subject fields are ignored.
795 The certificate extension fields must not contain either
796 a subject key identifier or a issuer key identifier field;
797 however, an extended key usage field for a trusted host must
800 Other extension fields are ignored.
801 .Ss Authentication Commands
802 .Bl -tag -width indent
803 .It Ic autokey Op Ar logsec
804 Specifies the interval between regenerations of the session key
805 list used with the Autokey protocol.
806 Note that the size of the key
807 list for each association depends on this interval and the current
809 The default value is 12 (4096 s or about 1.1 hours).
810 For poll intervals above the specified interval, a session key list
811 with a single entry will be regenerated for every message
813 .It Ic controlkey Ar key
814 Specifies the key identifier to use with the
816 utility, which uses the standard
817 protocol defined in RFC-1305.
821 the key identifier for a trusted key, where the value can be in the
822 range 1 to 65,534, inclusive.
826 .Op Cm randfile Ar file
831 .Op Cm iffpar Ar file
833 .Op Cm pw Ar password
835 This command requires the OpenSSL library.
836 It activates public key
837 cryptography, selects the message digest and signature
838 encryption scheme and loads the required private and public
839 values described above.
840 If one or more files are left unspecified,
841 the default names are used as described above.
842 Unless the complete path and name of the file are specified, the
843 location of a file is relative to the keys directory specified
848 Following are the subcommands:
849 .Bl -tag -width indent
851 Specifies the location of the required host public certificate file.
852 This overrides the link
853 .Pa ntpkey_cert_ Ns Ar hostname
854 in the keys directory.
856 Specifies the location of the optional GQ parameters file.
859 .Pa ntpkey_gq_ Ns Ar hostname
860 in the keys directory.
862 Specifies the location of the required host key file.
865 .Pa ntpkey_key_ Ns Ar hostname
866 in the keys directory.
867 .It Cm iffpar Ar file
868 Specifies the location of the optional IFF parameters file.This
870 .Pa ntpkey_iff_ Ns Ar hostname
871 in the keys directory.
873 Specifies the location of the optional leapsecond file.
874 This overrides the link
876 in the keys directory.
878 Specifies the location of the optional MV parameters file.
881 .Pa ntpkey_mv_ Ns Ar hostname
882 in the keys directory.
883 .It Cm pw Ar password
884 Specifies the password to decrypt files containing private keys and
886 This is required only if these files have been
888 .It Cm randfile Ar file
889 Specifies the location of the random seed file used by the OpenSSL
891 The defaults are described in the main text above.
893 Specifies the location of the optional sign key file.
896 .Pa ntpkey_sign_ Ns Ar hostname
897 in the keys directory.
899 not found, the host key is also the sign key.
901 .It Ic keys Ar keyfile
902 Specifies the complete path and location of the MD5 key file
903 containing the keys and key identifiers used by
908 when operating with symmetric key cryptography.
909 This is the same operation as the
912 .It Ic keysdir Ar path
913 This command specifies the default directory path for
914 cryptographic keys, parameters and certificates.
916 .Pa /usr/local/etc/ .
917 .It Ic requestkey Ar key
918 Specifies the key identifier to use with the
920 utility program, which uses a
921 proprietary protocol specific to this implementation of
925 argument is a key identifier
926 for the trusted key, where the value can be in the range 1 to
928 .It Ic revoke Ar logsec
929 Specifies the interval between re-randomization of certain
930 cryptographic values used by the Autokey scheme, as a power of 2 in
932 These values need to be updated frequently in order to
933 deflect brute-force attacks on the algorithms of the scheme;
934 however, updating some values is a relatively expensive operation.
935 The default interval is 16 (65,536 s or about 18 hours).
937 intervals above the specified interval, the values will be updated
938 for every message sent.
939 .It Ic trustedkey Ar key ...
940 Specifies the key identifiers which are trusted for the
941 purposes of authenticating peers with symmetric key cryptography,
942 as well as keys used by the
947 The authentication procedures require that both the local
948 and remote servers share the same key and key identifier for this
949 purpose, although different keys can be used with different
953 arguments are 32-bit unsigned
954 integers with values from 1 to 65,534.
957 The following error codes are reported via the NTP control
958 and monitoring protocol trap mechanism.
959 .Bl -tag -width indent
961 .Pq bad field format or length
962 The packet has invalid version, length or format.
965 The packet timestamp is the same or older than the most recent received.
966 This could be due to a replay or a server clock time step.
969 The packet filestamp is the same or older than the most recent received.
970 This could be due to a replay or a key file generation error.
972 .Pq bad or missing public key
973 The public key is missing, has incorrect format or is an unsupported type.
975 .Pq unsupported digest type
976 The server requires an unsupported digest/signature scheme.
978 .Pq mismatched digest types
981 .Pq bad signature length
982 The signature length does not match the current public key.
984 .Pq signature not verified
985 The message fails the signature check.
986 It could be bogus or signed by a
987 different private key.
989 .Pq certificate not verified
990 The certificate is invalid or signed with the wrong key.
992 .Pq certificate not verified
993 The certificate is not yet valid or has expired or the signature could not
996 .Pq bad or missing cookie
997 The cookie is missing, corrupted or bogus.
999 .Pq bad or missing leapseconds table
1000 The leapseconds table is missing, corrupted or bogus.
1002 .Pq bad or missing certificate
1003 The certificate is missing, corrupted or bogus.
1005 .Pq bad or missing identity
1006 The identity key is missing, corrupt or bogus.
1008 .Sh Monitoring Support
1010 includes a comprehensive monitoring facility suitable
1011 for continuous, long term recording of server and client
1012 timekeeping performance.
1016 for a listing and example of each type of statistics currently
1018 Statistic files are managed using file generation sets
1021 directory of this distribution.
1023 these facilities and
1026 jobs, the data can be
1027 automatically summarized and archived for retrospective analysis.
1028 .Ss Monitoring Commands
1029 .Bl -tag -width indent
1030 .It Ic statistics Ar name ...
1031 Enables writing of statistics records.
1032 Currently, four kinds of
1034 statistics are supported.
1035 .Bl -tag -width indent
1037 Enables recording of clock driver statistics information.
1039 received from a clock driver appends a line of the following form to
1040 the file generation set named
1043 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1046 The first two fields show the date (Modified Julian Day) and time
1047 (seconds and fraction past UTC midnight).
1048 The next field shows the
1049 clock address in dotted-quad notation.
1050 The final field shows the last
1051 timecode received from the clock in decoded ASCII format, where
1053 In some clock drivers a good deal of additional information
1054 can be gathered and displayed as well.
1055 See information specific to each
1056 clock for further details.
1058 This option requires the OpenSSL cryptographic software library.
1060 enables recording of cryptographic public key protocol information.
1061 Each message received by the protocol module appends a line of the
1062 following form to the file generation set named
1065 49213 525.624 127.127.4.1 message
1068 The first two fields show the date (Modified Julian Day) and time
1069 (seconds and fraction past UTC midnight).
1070 The next field shows the peer
1071 address in dotted-quad notation.
1072 The final message field includes the
1073 message type and certain ancillary information.
1075 .Sx Authentication Commands
1076 section for further information.
1078 Enables recording of loop filter statistics information.
1080 update of the local clock outputs a line of the following form to
1081 the file generation set named
1084 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1087 The first two fields show the date (Modified Julian Day) and
1088 time (seconds and fraction past UTC midnight).
1089 The next five fields
1090 show time offset (seconds), frequency offset (parts per million -
1091 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1092 discipline time constant.
1094 Enables recording of peer statistics information.
1096 statistics records of all peers of a NTP server and of special
1097 signals, where present and configured.
1098 Each valid update appends a
1099 line of the following form to the current element of a file
1100 generation set named
1103 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
1106 The first two fields show the date (Modified Julian Day) and
1107 time (seconds and fraction past UTC midnight).
1109 show the peer address in dotted-quad notation and status,
1111 The status field is encoded in hex in the format
1112 described in Appendix A of the NTP specification RFC 1305.
1113 The final four fields show the offset,
1114 delay, dispersion and RMS jitter, all in seconds.
1116 Enables recording of raw-timestamp statistics information.
1118 includes statistics records of all peers of a NTP server and of
1119 special signals, where present and configured.
1121 received from a peer or clock driver appends a line of the
1122 following form to the file generation set named
1125 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1128 The first two fields show the date (Modified Julian Day) and
1129 time (seconds and fraction past UTC midnight).
1131 show the remote peer or clock address followed by the local address
1132 in dotted-quad notation.
1133 The final four fields show the originate,
1134 receive, transmit and final NTP timestamps in order.
1136 values are as received and before processing by the various data
1137 smoothing and mitigation algorithms.
1139 Enables recording of ntpd statistics counters on a periodic basis.
1141 hour a line of the following form is appended to the file generation
1145 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1148 The first two fields show the date (Modified Julian Day) and time
1149 (seconds and fraction past UTC midnight).
1150 The remaining ten fields show
1151 the statistics counter values accumulated since the last generated
1153 .Bl -tag -width indent
1154 .It Time since restart Cm 36000
1155 Time in hours since the system was last rebooted.
1156 .It Packets received Cm 81965
1157 Total number of packets received.
1158 .It Packets processed Cm 0
1159 Number of packets received in response to previous packets sent.
1160 .It Current version Cm 9546
1161 Number of packets matching the current NTP version.
1162 .It Previous version Cm 56
1163 Number of packets matching the previous NTP version.
1164 .It Bad version Cm 71793
1165 Number of packets matching neither NTP version.
1166 .It Access denied Cm 512
1167 Number of packets denied access for any reason.
1168 .It Bad length or format Cm 540
1169 Number of packets with invalid length, format or port number.
1170 .It Bad authentication Cm 10
1171 Number of packets not verified as authentic.
1172 .It Rate exceeded Cm 147
1173 Number of packets discarded due to rate limitation.
1175 .It Cm statsdir Ar directory_path
1176 Indicates the full path of a directory where statistics files
1177 should be created (see below).
1179 the (otherwise constant)
1181 filename prefix to be modified for file generation sets, which
1182 is useful for handling statistics logs.
1183 .It Cm filegen Ar name Xo
1184 .Op Cm file Ar filename
1185 .Op Cm type Ar typename
1186 .Op Cm link | nolink
1187 .Op Cm enable | disable
1189 Configures setting of generation file set name.
1191 file sets provide a means for handling files that are
1192 continuously growing during the lifetime of a server.
1193 Server statistics are a typical example for such files.
1194 Generation file sets provide access to a set of files used
1195 to store the actual data.
1196 At any time at most one element
1197 of the set is being written to.
1198 The type given specifies
1199 when and how data will be directed to a new element of the set.
1200 This way, information stored in elements of a file set
1201 that are currently unused are available for administrational
1202 operations without the risk of disturbing the operation of ntpd.
1203 (Most important: they can be removed to free space for new data
1206 Note that this command can be sent from the
1208 program running at a remote location.
1209 .Bl -tag -width indent
1211 This is the type of the statistics records, as shown in the
1214 .It Cm file Ar filename
1215 This is the file name for the statistics records.
1217 members are built from three concatenated elements
1222 .Bl -tag -width indent
1224 This is a constant filename path.
1225 It is not subject to
1226 modifications via the
1229 It is defined by the
1230 server, usually specified as a compile-time constant.
1232 however, be configurable for individual file generation sets
1234 For example, the prefix used with
1238 generation can be configured using the
1240 option explained above.
1242 This string is directly concatenated to the prefix mentioned
1243 above (no intervening
1245 This can be modified using
1246 the file argument to the
1252 allowed in this component to prevent filenames referring to
1253 parts outside the filesystem hierarchy denoted by
1256 This part is reflects individual elements of a file set.
1258 generated according to the type of a file set.
1260 .It Cm type Ar typename
1261 A file generation set is characterized by its type.
1263 types are supported:
1264 .Bl -tag -width indent
1266 The file set is actually a single plain file.
1268 One element of file set is used per incarnation of a ntpd
1270 This type does not perform any changes to file set
1271 members during runtime, however it provides an easy way of
1272 separating files belonging to different
1274 server incarnations.
1275 The set member filename is built by appending a
1282 appending the decimal representation of the process ID of the
1286 One file generation set element is created per day.
1288 defined as the period between 00:00 and 24:00 UTC.
1290 member suffix consists of a
1292 and a day specification in
1296 is a 4-digit year number (e.g., 1992).
1298 is a two digit month number.
1300 is a two digit day number.
1301 Thus, all information written at 10 December 1992 would end up
1304 .Ar filename Ns .19921210 .
1306 Any file set member contains data related to a certain week of
1308 The term week is defined by computing day-of-year
1310 Elements of such a file generation set are
1311 distinguished by appending the following suffix to the file set
1312 filename base: A dot, a 4-digit year number, the letter
1314 and a 2-digit week number.
1315 For example, information from January,
1316 10th 1992 would end up in a file with suffix
1317 .No . Ns Ar 1992W1 .
1319 One generation file set element is generated per month.
1321 file name suffix consists of a dot, a 4-digit year number, and
1324 One generation file element is generated per year.
1326 suffix consists of a dot and a 4 digit year number.
1328 This type of file generation sets changes to a new element of
1329 the file set every 24 hours of server operation.
1331 suffix consists of a dot, the letter
1333 and an 8-digit number.
1334 This number is taken to be the number of seconds the server is
1335 running at the start of the corresponding 24-hour period.
1336 Information is only written to a file generation by specifying
1338 output is prevented by specifying
1341 .It Cm link | nolink
1342 It is convenient to be able to access the current element of a file
1343 generation set by a fixed name.
1344 This feature is enabled by
1349 If link is specified, a
1350 hard link from the current file set element to a file without
1352 When there is already a file with this name and
1353 the number of links of this file is one, it is renamed appending a
1356 and the pid of the ntpd server process.
1358 number of links is greater than one, the file is unlinked.
1360 allows the current file to be accessed by a constant name.
1361 .It Cm enable \&| Cm disable
1362 Enables or disables the recording function.
1366 .Sh Access Control Support
1369 daemon implements a general purpose address/mask based restriction
1371 The list contains address/match entries sorted first
1372 by increasing address values and then by increasing mask values.
1373 A match occurs when the bitwise AND of the mask and the packet
1374 source address is equal to the bitwise AND of the mask and
1375 address in the list.
1376 The list is searched in order with the
1377 last match found defining the restriction flags associated
1379 Additional information and examples can be found in the
1380 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
1382 (available as part of the HTML documentation
1384 .Pa /usr/share/doc/ntp ) .
1386 The restriction facility was implemented in conformance
1387 with the access policies for the original NSFnet backbone
1389 Later the facility was expanded to deflect
1390 cryptographic and clogging attacks.
1391 While this facility may
1392 be useful for keeping unwanted or broken or malicious clients
1393 from congesting innocent servers, it should not be considered
1394 an alternative to the NTP authentication facilities.
1395 Source address based restrictions are easily circumvented
1396 by a determined cracker.
1398 Clients can be denied service because they are explicitly
1399 included in the restrict list created by the restrict command
1400 or implicitly as the result of cryptographic or rate limit
1402 Cryptographic violations include certificate
1403 or identity verification failure; rate limit violations generally
1404 result from defective NTP implementations that send packets
1406 Some violations cause denied service
1407 only for the offending packet, others cause denied service
1408 for a timed period and others cause the denied service for
1409 an indefinite period.
1410 When a client or network is denied access
1411 for an indefinite period, the only way at present to remove
1412 the restrictions is by restarting the server.
1413 .Ss The Kiss-of-Death Packet
1414 Ordinarily, packets denied service are simply dropped with no
1415 further action except incrementing statistics counters.
1417 more proactive response is needed, such as a server message that
1418 explicitly requests the client to stop sending and leave a message
1419 for the system operator.
1420 A special packet format has been created
1421 for this purpose called the "kiss-of-death" (KoD) packet.
1422 KoD packets have the leap bits set unsynchronized and stratum set
1423 to zero and the reference identifier field set to a four-byte
1429 flag of the matching restrict list entry is set,
1430 the code is "DENY"; if the
1432 flag is set and the rate limit
1433 is exceeded, the code is "RATE".
1434 Finally, if a cryptographic violation occurs, the code is "CRYP".
1436 A client receiving a KoD performs a set of sanity checks to
1437 minimize security exposure, then updates the stratum and
1438 reference identifier peer variables, sets the access
1439 denied (TEST4) bit in the peer flash variable and sends
1440 a message to the log.
1441 As long as the TEST4 bit is set,
1442 the client will send no further packets to the server.
1443 The only way at present to recover from this condition is
1444 to restart the protocol at both the client and server.
1446 happens automatically at the client when the association times out.
1447 It will happen at the server only if the server operator cooperates.
1448 .Ss Access Control Commands
1449 .Bl -tag -width indent
1451 .Op Cm average Ar avg
1452 .Op Cm minimum Ar min
1453 .Op Cm monitor Ar prob
1455 Set the parameters of the
1457 facility which protects the server from
1461 subcommand specifies the minimum average packet
1464 subcommand specifies the minimum packet spacing.
1465 Packets that violate these minimum are discarded
1466 and a kiss-o'-death packet returned if enabled.
1468 minimum average and minimum are 5 and 2, respectively.
1469 The monitor subcommand specifies the probability of discard
1470 for packets that overflow the rate-control window.
1471 .It Xo Ic restrict address
1477 argument expressed in
1478 dotted-quad form is the address of a host or network.
1481 argument can be a valid host DNS name.
1484 argument expressed in dotted-quad form defaults to
1485 .Cm 255.255.255.255 ,
1488 is treated as the address of an individual host.
1489 A default entry (address
1493 is always included and is always the first entry in the list.
1494 Note that text string
1496 with no mask option, may
1497 be used to indicate the default entry.
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
1512 .Bl -tag -width indent
1514 Deny packets of all kinds, including
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.
1527 Deny service if the packet spacing violates the lower limits specified
1528 in the discard command.
1529 A history of clients is kept using the
1530 monitoring capability of
1532 Thus, monitoring is always active as
1533 long as there is a restriction entry with the
1537 Declare traps set by matching hosts to be low priority.
1539 number of traps a server can maintain is limited (the current limit
1541 Traps are usually assigned on a first come, first served
1542 basis, with later trap requestors being denied service.
1544 modifies the assignment algorithm by allowing low priority traps to
1545 be overridden by later requests for normal priority traps.
1551 queries which attempt to modify the state of the
1552 server (i.e., run time reconfiguration).
1553 Queries which return
1554 information are permitted.
1561 Time service is not affected.
1563 Deny packets which would result in mobilizing a new association.
1565 includes broadcast and symmetric active packets when a configured
1566 association does not exist.
1568 Deny all packets except
1574 Decline to provide mode 6 control message trap service to matching
1576 The trap service is a subsystem of the ntpdq control message
1577 protocol which is intended for use by remote event logging programs.
1579 Deny service unless the packet is cryptographically authenticated.
1581 This is actually a match algorithm modifier, rather than a
1583 Its presence causes the restriction entry to be
1584 matched only if the source port in the packet is the standard NTP
1594 is considered more specific and
1595 is sorted later in the list.
1597 Deny packets that do not match the current NTP version.
1600 Default restriction list entries with the flags ignore, interface,
1601 ntpport, for each of the local host's interface addresses are
1602 inserted into the table at startup to prevent the server
1603 from attempting to synchronize to its own time.
1604 A default entry is also always present, though if it is
1605 otherwise unconfigured; no flags are associated
1606 with the default entry (i.e., everything besides your own
1607 NTP server is unrestricted).
1609 .Sh Automatic NTP Configuration Options
1611 Manycasting is a automatic discovery and configuration paradigm
1613 It is intended as a means for a multicast client
1614 to troll the nearby network neighborhood to find cooperating
1615 manycast servers, validate them using cryptographic means
1616 and evaluate their time values with respect to other servers
1617 that might be lurking in the vicinity.
1618 The intended result is that each manycast client mobilizes
1619 client associations with some number of the "best"
1620 of the nearby manycast servers, yet automatically reconfigures
1621 to sustain this number of servers should one or another fail.
1623 Note that the manycasting paradigm does not coincide
1624 with the anycast paradigm described in RFC-1546,
1625 which is designed to find a single server from a clique
1626 of servers providing the same service.
1627 The manycast paradigm is designed to find a plurality
1628 of redundant servers satisfying defined optimality criteria.
1630 Manycasting can be used with either symmetric key
1631 or public key cryptography.
1632 The public key infrastructure (PKI)
1633 offers the best protection against compromised keys
1634 and is generally considered stronger, at least with relatively
1636 It is implemented using the Autokey protocol and
1637 the OpenSSL cryptographic library available from
1638 .Li http://www.openssl.org/ .
1639 The library can also be used with other NTPv4 modes
1640 as well and is highly recommended, especially for broadcast modes.
1642 A persistent manycast client association is configured
1643 using the manycastclient command, which is similar to the
1644 server command but with a multicast (IPv4 class
1649 The IANA has designated IPv4 address 224.1.1.1
1650 and IPv6 address FF05::101 (site local) for NTP.
1651 When more servers are needed, it broadcasts manycast
1652 client messages to this address at the minimum feasible rate
1653 and minimum feasible time-to-live (TTL) hops, depending
1654 on how many servers have already been found.
1655 There can be as many manycast client associations
1656 as different group address, each one serving as a template
1657 for a future ephemeral unicast client/server association.
1659 Manycast servers configured with the
1661 command listen on the specified group address for manycast
1663 Note the distinction between manycast client,
1664 which actively broadcasts messages, and manycast server,
1665 which passively responds to them.
1666 If a manycast server is
1667 in scope of the current TTL and is itself synchronized
1668 to a valid source and operating at a stratum level equal
1669 to or lower than the manycast client, it replies to the
1670 manycast client message with an ordinary unicast server message.
1672 The manycast client receiving this message mobilizes
1673 an ephemeral client/server association according to the
1674 matching manycast client template, but only if cryptographically
1675 authenticated and the server stratum is less than or equal
1676 to the client stratum.
1677 Authentication is explicitly required
1678 and either symmetric key or public key (Autokey) can be used.
1679 Then, the client polls the server at its unicast address
1680 in burst mode in order to reliably set the host clock
1681 and validate the source.
1682 This normally results
1683 in a volley of eight client/server at 2-s intervals
1684 during which both the synchronization and cryptographic
1685 protocols run concurrently.
1686 Following the volley,
1687 the client runs the NTP intersection and clustering
1688 algorithms, which act to discard all but the "best"
1689 associations according to stratum and synchronization
1691 The surviving associations then continue
1692 in ordinary client/server mode.
1694 The manycast client polling strategy is designed to reduce
1695 as much as possible the volume of manycast client messages
1696 and the effects of implosion due to near-simultaneous
1697 arrival of manycast server messages.
1698 The strategy is determined by the
1699 .Ic manycastclient ,
1703 configuration commands.
1704 The manycast poll interval is
1705 normally eight times the system poll interval,
1706 which starts out at the
1708 value specified in the
1709 .Ic manycastclient ,
1710 command and, under normal circumstances, increments to the
1712 value specified in this command.
1713 Initially, the TTL is
1714 set at the minimum hops specified by the ttl command.
1715 At each retransmission the TTL is increased until reaching
1716 the maximum hops specified by this command or a sufficient
1717 number client associations have been found.
1718 Further retransmissions use the same TTL.
1720 The quality and reliability of the suite of associations
1721 discovered by the manycast client is determined by the NTP
1722 mitigation algorithms and the
1726 values specified in the
1728 configuration command.
1731 candidate servers must be available and the mitigation
1732 algorithms produce at least
1734 survivors in order to synchronize the clock.
1735 Byzantine agreement principles require at least four
1736 candidates in order to correctly discard a single falseticker.
1737 For legacy purposes,
1742 For manycast service
1744 should be explicitly set to 4, assuming at least that
1745 number of servers are available.
1749 servers are found, the manycast poll interval is immediately
1754 servers are found when the TTL has reached the maximum hops,
1755 the manycast poll interval is doubled.
1756 For each transmission
1757 after that, the poll interval is doubled again until
1758 reaching the maximum of eight times
1760 Further transmissions use the same poll interval and
1762 Note that while all this is going on,
1763 each client/server association found is operating normally
1764 it the system poll interval.
1766 Administratively scoped multicast boundaries are normally
1767 specified by the network router configuration and,
1768 in the case of IPv6, the link/site scope prefix.
1769 By default, the increment for TTL hops is 32 starting
1770 from 31; however, the
1772 configuration command can be
1773 used to modify the values to match the scope rules.
1775 It is often useful to narrow the range of acceptable
1776 servers which can be found by manycast client associations.
1777 Because manycast servers respond only when the client
1778 stratum is equal to or greater than the server stratum,
1779 primary (stratum 1) servers will find only primary servers
1780 in TTL range, which is probably the most common objective.
1781 However, unless configured otherwise, all manycast clients
1782 in TTL range will eventually find all primary servers
1783 in TTL range, which is probably not the most common
1784 objective in large networks.
1787 command can be used to modify this behavior.
1788 Servers with stratum below
1794 command are strongly discouraged during the selection
1795 process; however, these servers may be temporally
1796 accepted if the number of servers within TTL range is
1800 The above actions occur for each manycast client message,
1801 which repeats at the designated poll interval.
1802 However, once the ephemeral client association is mobilized,
1803 subsequent manycast server replies are discarded,
1804 since that would result in a duplicate association.
1805 If during a poll interval the number of client associations
1808 all manycast client prototype associations are reset
1809 to the initial poll interval and TTL hops and operation
1810 resumes from the beginning.
1811 It is important to avoid
1812 frequent manycast client messages, since each one requires
1813 all manycast servers in TTL range to respond.
1814 The result could well be an implosion, either minor or major,
1815 depending on the number of servers in range.
1816 The recommended value for
1820 It is possible and frequently useful to configure a host
1821 as both manycast client and manycast server.
1822 A number of hosts configured this way and sharing a common
1823 group address will automatically organize themselves
1824 in an optimum configuration based on stratum and
1825 synchronization distance.
1826 For example, consider an NTP
1827 subnet of two primary servers and a hundred or more
1829 With two exceptions, all servers
1830 and clients have identical configuration files including both
1834 commands using, for instance, multicast group address
1836 The only exception is that each primary server
1837 configuration file must include commands for the primary
1838 reference source such as a GPS receiver.
1840 The remaining configuration files for all secondary
1841 servers and clients have the same contents, except for the
1843 command, which is specific for each stratum level.
1844 For stratum 1 and stratum 2 servers, that command is
1846 For stratum 3 and above servers the
1848 value is set to the intended stratum number.
1849 Thus, all stratum 3 configuration files are identical,
1850 all stratum 4 files are identical and so forth.
1852 Once operations have stabilized in this scenario,
1853 the primary servers will find the primary reference source
1854 and each other, since they both operate at the same
1855 stratum (1), but not with any secondary server or client,
1856 since these operate at a higher stratum.
1858 servers will find the servers at the same stratum level.
1859 If one of the primary servers loses its GPS receiver,
1860 it will continue to operate as a client and other clients
1861 will time out the corresponding association and
1862 re-associate accordingly.
1864 Some administrators prefer to avoid running
1866 continuously and run either
1872 In either case the servers must be
1873 configured in advance and the program fails if none are
1874 available when the cron job runs.
1876 application of manycast is with
1879 The program wakes up, scans the local landscape looking
1880 for the usual suspects, selects the best from among
1881 the rascals, sets the clock and then departs.
1882 Servers do not have to be configured in advance and
1883 all clients throughout the network can have the same
1885 .Ss Manycast Interactions with Autokey
1886 Each time a manycast client sends a client mode packet
1887 to a multicast group address, all manycast servers
1888 in scope generate a reply including the host name
1890 The manycast clients then run
1891 the Autokey protocol, which collects and verifies
1892 all certificates involved.
1893 Following the burst interval
1894 all but three survivors are cast off,
1895 but the certificates remain in the local cache.
1896 It often happens that several complete signing trails
1897 from the client to the primary servers are collected in this way.
1899 About once an hour or less often if the poll interval
1900 exceeds this, the client regenerates the Autokey key list.
1901 This is in general transparent in client/server mode.
1902 However, about once per day the server private value
1903 used to generate cookies is refreshed along with all
1904 manycast client associations.
1906 cryptographic values including certificates is refreshed.
1907 If a new certificate has been generated since
1908 the last refresh epoch, it will automatically revoke
1909 all prior certificates that happen to be in the
1911 At the same time, the manycast
1912 scheme starts all over from the beginning and
1913 the expanding ring shrinks to the minimum and increments
1914 from there while collecting all servers in scope.
1915 .Ss Manycast Options
1916 .Bl -tag -width indent
1919 .Cm ceiling Ar ceiling |
1920 .Cm cohort { 0 | 1 } |
1921 .Cm floor Ar floor |
1922 .Cm minclock Ar minclock |
1923 .Cm minsane Ar minsane
1926 This command affects the clock selection and clustering
1928 It can be used to select the quality and
1929 quantity of peers used to synchronize the system clock
1930 and is most useful in manycast mode.
1931 The variables operate
1933 .Bl -tag -width indent
1934 .It Cm ceiling Ar ceiling
1935 Peers with strata above
1937 will be discarded if there are at least
1940 This value defaults to 15, but can be changed
1941 to any number from 1 to 15.
1942 .It Cm cohort Bro 0 | 1 Brc
1943 This is a binary flag which enables (0) or disables (1)
1944 manycast server replies to manycast clients with the same
1946 This is useful to reduce implosions where
1947 large numbers of clients with the same stratum level
1949 The default is to enable these replies.
1950 .It Cm floor Ar floor
1951 Peers with strata below
1953 will be discarded if there are at least
1956 This value defaults to 1, but can be changed
1957 to any number from 1 to 15.
1958 .It Cm minclock Ar minclock
1959 The clustering algorithm repeatedly casts out outerlayer
1960 associations until no more than
1962 associations remain.
1963 This value defaults to 3,
1964 but can be changed to any number from 1 to the number of
1966 .It Cm minsane Ar minsane
1967 This is the minimum number of candidates available
1968 to the clock selection algorithm in order to produce
1969 one or more true chimers for the clustering algorithm.
1970 If fewer than this number are available, the clock is
1971 undisciplined and allowed to run free.
1973 for legacy purposes.
1974 However, according to principles of
1975 Byzantine agreement,
1977 should be at least 4 in order to detect and discard
1978 a single falseticker.
1980 .It Cm ttl Ar hop ...
1981 This command specifies a list of TTL values in increasing
1982 order, up to 8 values can be specified.
1983 In manycast mode these values are used in turn
1984 in an expanding-ring search.
1985 The default is eight
1986 multiples of 32 starting at 31.
1988 .Sh Reference Clock Support
1989 The NTP Version 4 daemon supports some three dozen different radio,
1990 satellite and modem reference clocks plus a special pseudo-clock
1991 used for backup or when no other clock source is available.
1992 Detailed descriptions of individual device drivers and options can
1994 .Qq Reference Clock Drivers
1996 (available as part of the HTML documentation
1998 .Pa /usr/share/doc/ntp ) .
1999 Additional information can be found in the pages linked
2000 there, including the
2001 .Qq Debugging Hints for Reference Clock Drivers
2003 .Qq How To Write a Reference Clock Driver
2005 (available as part of the HTML documentation
2007 .Pa /usr/share/doc/ntp ) .
2008 In addition, support for a PPS
2009 signal is available as described in the
2010 .Qq Pulse-per-second (PPS) Signal Interfacing
2012 (available as part of the HTML documentation
2014 .Pa /usr/share/doc/ntp ) .
2016 drivers support special line discipline/streams modules which can
2017 significantly improve the accuracy using the driver.
2020 .Qq Line Disciplines and Streams Drivers
2022 (available as part of the HTML documentation
2024 .Pa /usr/share/doc/ntp ) .
2026 A reference clock will generally (though not always) be a radio
2027 timecode receiver which is synchronized to a source of standard
2028 time such as the services offered by the NRC in Canada and NIST and
2030 The interface between the computer and the timecode
2031 receiver is device dependent, but is usually a serial port.
2033 device driver specific to each reference clock must be selected and
2034 compiled in the distribution; however, most common radio, satellite
2035 and modem clocks are included by default.
2036 Note that an attempt to
2037 configure a reference clock when the driver has not been compiled
2038 or the hardware port has not been appropriately configured results
2039 in a scalding remark to the system log file, but is otherwise non
2042 For the purposes of configuration,
2045 reference clocks in a manner analogous to normal NTP peers as much
2047 Reference clocks are identified by a syntactically
2048 correct but invalid IP address, in order to distinguish them from
2050 Reference clock addresses are of the form
2052 .Li 127.127. Ar t . Ar u ,
2057 denoting the clock type and
2060 number in the range 0-3.
2061 While it may seem overkill, it is in fact
2062 sometimes useful to configure multiple reference clocks of the same
2063 type, in which case the unit numbers must be unique.
2067 command is used to configure a reference
2070 argument in that command
2071 is the clock address.
2077 options are not used for reference clock support.
2080 option is added for reference clock support, as
2084 option can be useful to
2085 persuade the server to cherish a reference clock with somewhat more
2086 enthusiasm than other reference clocks or peers.
2088 information on this option can be found in the
2089 .Qq Mitigation Rules and the prefer Keyword
2090 (available as part of the HTML documentation
2092 .Pa /usr/share/doc/ntp )
2099 meaning only for selected clock drivers.
2100 See the individual clock
2101 driver document pages for additional information.
2105 command is used to provide additional
2106 information for individual clock drivers and normally follows
2107 immediately after the
2112 argument specifies the clock address.
2117 options can be used to
2118 override the defaults for the device.
2119 There are two optional
2120 device-dependent time offsets and four flags that can be included
2125 The stratum number of a reference clock is by default zero.
2128 daemon adds one to the stratum of each
2129 peer, a primary server ordinarily displays an external stratum of
2131 In order to provide engineered backups, it is often useful to
2132 specify the reference clock stratum as greater than zero.
2135 option is used for this purpose.
2137 involving both a reference clock and a pulse-per-second (PPS)
2138 discipline signal, it is useful to specify the reference clock
2139 identifier as other than the default, depending on the driver.
2142 option is used for this purpose.
2144 these options apply to all clock drivers.
2145 .Ss Reference Clock Commands
2146 .Bl -tag -width indent
2149 .Li 127.127. Ar t . Ar u
2153 .Op Cm minpoll Ar int
2154 .Op Cm maxpoll Ar int
2156 This command can be used to configure reference clocks in
2158 The options are interpreted as follows:
2159 .Bl -tag -width indent
2161 Marks the reference clock as preferred.
2162 All other things being
2163 equal, this host will be chosen for synchronization among a set of
2164 correctly operating hosts.
2166 .Qq Mitigation Rules and the prefer Keyword
2168 (available as part of the HTML documentation
2170 .Pa /usr/share/doc/ntp )
2171 for further information.
2173 Specifies a mode number which is interpreted in a
2174 device-specific fashion.
2175 For instance, it selects a dialing
2176 protocol in the ACTS driver and a device subtype in the
2179 .It Cm minpoll Ar int
2180 .It Cm maxpoll Ar int
2181 These options specify the minimum and maximum polling interval
2182 for reference clock messages, as a power of 2 in seconds
2184 most directly connected reference clocks, both
2188 default to 6 (64 s).
2189 For modem reference clocks,
2191 defaults to 10 (17.1 m) and
2193 defaults to 14 (4.5 h).
2194 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2198 .Li 127.127. Ar t . Ar u
2202 .Op Cm stratum Ar int
2203 .Op Cm refid Ar string
2205 .Op Cm flag1 Cm 0 \&| Cm 1
2206 .Op Cm flag2 Cm 0 \&| Cm 1
2207 .Op Cm flag3 Cm 0 \&| Cm 1
2208 .Op Cm flag4 Cm 0 \&| Cm 1
2210 This command can be used to configure reference clocks in
2212 It must immediately follow the
2214 command which configures the driver.
2215 Note that the same capability
2216 is possible at run time using the
2219 The options are interpreted as
2221 .Bl -tag -width indent
2223 Specifies a constant to be added to the time offset produced by
2224 the driver, a fixed-point decimal number in seconds.
2226 as a calibration constant to adjust the nominal time offset of a
2227 particular clock to agree with an external standard, such as a
2228 precision PPS signal.
2229 It also provides a way to correct a
2230 systematic error or bias due to serial port or operating system
2231 latencies, different cable lengths or receiver internal delay.
2233 specified offset is in addition to the propagation delay provided
2234 by other means, such as internal DIPswitches.
2236 for an individual system and driver is available, an approximate
2237 correction is noted in the driver documentation pages.
2238 Note: in order to facilitate calibration when more than one
2239 radio clock or PPS signal is supported, a special calibration
2240 feature is available.
2241 It takes the form of an argument to the
2243 command described in
2244 .Sx Miscellaneous Options
2245 page and operates as described in the
2246 .Qq Reference Clock Drivers
2248 (available as part of the HTML documentation
2250 .Pa /usr/share/doc/ntp ) .
2251 .It Cm time2 Ar secs
2252 Specifies a fixed-point decimal number in seconds, which is
2253 interpreted in a driver-dependent way.
2254 See the descriptions of
2255 specific drivers in the
2256 .Qq Reference Clock Drivers
2258 (available as part of the HTML documentation
2260 .Pa /usr/share/doc/ntp ) .
2261 .It Cm stratum Ar int
2262 Specifies the stratum number assigned to the driver, an integer
2264 This number overrides the default stratum number
2265 ordinarily assigned by the driver itself, usually zero.
2266 .It Cm refid Ar string
2267 Specifies an ASCII string of from one to four characters which
2268 defines the reference identifier used by the driver.
2270 overrides the default identifier ordinarily assigned by the driver
2273 Specifies a mode number which is interpreted in a
2274 device-specific fashion.
2275 For instance, it selects a dialing
2276 protocol in the ACTS driver and a device subtype in the
2279 .It Cm flag1 Cm 0 \&| Cm 1
2280 .It Cm flag2 Cm 0 \&| Cm 1
2281 .It Cm flag3 Cm 0 \&| Cm 1
2282 .It Cm flag4 Cm 0 \&| Cm 1
2283 These four flags are used for customizing the clock driver.
2285 interpretation of these values, and whether they are used at all,
2286 is a function of the particular clock driver.
2290 is used to enable recording monitoring
2293 file configured with the
2296 Further information on the
2298 command can be found in
2299 .Sx Monitoring Options .
2302 .Sh Miscellaneous Options
2303 .Bl -tag -width indent
2304 .It Ic broadcastdelay Ar seconds
2305 The broadcast and multicast modes require a special calibration
2306 to determine the network delay between the local and remote
2308 Ordinarily, this is done automatically by the initial
2309 protocol exchanges between the client and server.
2311 the calibration procedure may fail due to network or server access
2312 controls, for example.
2313 This command specifies the default delay to
2314 be used under these circumstances.
2315 Typically (for Ethernet), a
2316 number between 0.003 and 0.007 seconds is appropriate.
2318 when this command is not used is 0.004 seconds.
2319 .It Ic calldelay Ar delay
2320 This option controls the delay in seconds between the first and second
2321 packets sent in burst or iburst mode to allow additional time for a modem
2322 or ISDN call to complete.
2323 .It Ic driftfile Ar driftfile
2324 This command specifies the complete path and name of the file used to
2325 record the frequency of the local clock oscillator.
2329 command line option.
2330 If the file exists, it is read at
2331 startup in order to set the initial frequency and then updated once per
2332 hour with the current frequency computed by the daemon.
2334 specified, but the file itself does not exist, the starts with an initial
2335 frequency of zero and creates the file when writing it for the first time.
2336 If this command is not given, the daemon will always start with an initial
2339 The file format consists of a single line containing a single
2340 floating point number, which records the frequency offset measured
2341 in parts-per-million (PPM).
2342 The file is updated by first writing
2343 the current drift value into a temporary file and then renaming
2344 this file to replace the old version.
2347 must have write permission for the directory the
2348 drift file is located in, and that file system links, symbolic or
2349 otherwise, should be avoided.
2352 .Cm auth | Cm bclient |
2353 .Cm calibrate | Cm kernel |
2354 .Cm monitor | Cm ntp |
2360 .Cm auth | Cm bclient |
2361 .Cm calibrate | Cm kernel |
2362 .Cm monitor | Cm ntp |
2366 Provides a way to enable or disable various server options.
2367 Flags not mentioned are unaffected.
2368 Note that all of these flags
2369 can be controlled remotely using the
2372 .Bl -tag -width indent
2374 Enables the server to synchronize with unconfigured peers only if the
2375 peer has been correctly authenticated using either public key or
2376 private key cryptography.
2377 The default for this flag is
2380 Enables the server to listen for a message from a broadcast or
2381 multicast server, as in the
2383 command with default
2385 The default for this flag is
2388 Enables the calibrate feature for reference clocks.
2393 Enables the kernel time discipline, if available.
2394 The default for this
2397 if support is available, otherwise
2400 Enables the monitoring facility.
2406 command or further information.
2408 default for this flag is
2411 Enables time and frequency discipline.
2412 In effect, this switch opens and
2413 closes the feedback loop, which is useful for testing.
2418 Enables the pulse-per-second (PPS) signal when frequency and time is
2419 disciplined by the precision time kernel modifications.
2421 .Qq A Kernel Model for Precision Timekeeping
2422 (available as part of the HTML documentation
2424 .Pa /usr/share/doc/ntp )
2425 page for further information.
2426 The default for this flag is
2429 Enables the statistics facility.
2431 .Sx Monitoring Options
2432 section for further information.
2433 The default for this flag is
2436 .It Ic includefile Ar includefile
2437 This command allows additional configuration commands
2438 to be included from a separate file.
2440 be nested to a depth of five; upon reaching the end of any
2441 include file, command processing resumes in the previous
2443 This option is useful for sites that run
2445 on multiple hosts, with (mostly) common options (e.g., a
2447 .It Ic logconfig Ar configkeyword
2448 This command controls the amount and type of output written to
2451 facility or the alternate
2454 By default, all output is turned on.
2457 keywords can be prefixed with
2473 messages can be controlled in four
2482 Within these classes four types of messages can be
2483 controlled: informational messages
2501 Configuration keywords are formed by concatenating the message class with
2505 prefix can be used instead of a message class.
2507 message class may also be followed by the
2509 keyword to enable/disable all
2510 messages of the respective message class.Thus, a minimal log configuration
2511 could look like this:
2513 logconfig =syncstatus +sysevents
2516 This would just list the synchronizations state of
2518 and the major system events.
2519 For a simple reference server, the
2520 following minimum message configuration could be useful:
2522 logconfig =syncall +clockall
2525 This configuration will list all clock information and
2526 synchronization information.
2527 All other events and messages about
2528 peers, system events and so on is suppressed.
2529 .It Ic logfile Ar logfile
2530 This command specifies the location of an alternate log file to
2531 be used instead of the default system
2534 This is the same operation as the -l command line option.
2535 .It Ic setvar Ar variable Op Cm default
2536 This command adds an additional system variable.
2538 variables can be used to distribute additional information such as
2540 If the variable of the form
2547 variable will be listed as part of the default system variables
2553 These additional variables serve
2554 informational purposes only.
2555 They are not related to the protocol
2556 other that they can be listed.
2557 The known protocol variables will
2558 always override any variables defined via the
2561 There are three special variables that contain the names
2562 of all variable of the same group.
2566 the names of all system variables.
2570 the names of all peer variables and the
2572 holds the names of the reference clock variables.
2575 .Cm allan Ar allan |
2576 .Cm dispersion Ar dispersion |
2578 .Cm huffpuff Ar huffpuff |
2579 .Cm panic Ar panic |
2581 .Cm stepout Ar stepout
2584 This command can be used to alter several system variables in
2585 very exceptional circumstances.
2586 It should occur in the
2587 configuration file before any other configuration options.
2589 default values of these variables have been carefully optimized for
2590 a wide range of network speeds and reliability expectations.
2592 general, they interact in intricate ways that are hard to predict
2593 and some combinations can result in some very nasty behavior.
2595 rarely is it necessary to change the default values; but, some
2596 folks cannot resist twisting the knobs anyway and this command is
2598 Emphasis added: twisters are on their own and can expect
2599 no help from the support group.
2601 The variables operate as follows:
2602 .Bl -tag -width indent
2603 .It Cm allan Ar allan
2604 The argument becomes the new value for the minimum Allan
2605 intercept, which is a parameter of the PLL/FLL clock discipline
2607 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
2609 .It Cm dispersion Ar dispersion
2610 The argument becomes the new value for the dispersion increase rate,
2611 normally .000015 s/s.
2613 The argument becomes the initial value of the frequency offset in
2615 This overrides the value in the frequency file, if
2616 present, and avoids the initial training state if it is not.
2617 .It Cm huffpuff Ar huffpuff
2618 The argument becomes the new value for the experimental
2619 huff-n'-puff filter span, which determines the most recent interval
2620 the algorithm will search for a minimum delay.
2622 900 s (15 m), but a more reasonable value is 7200 (2 hours).
2624 is no default, since the filter is not enabled unless this command
2626 .It Cm panic Ar panic
2627 The argument is the panic threshold, normally 1000 s.
2629 the panic sanity check is disabled and a clock offset of any value will
2632 The argument is the step threshold, which by default is 0.128 s.
2634 be set to any positive number in seconds.
2635 If set to zero, step
2636 adjustments will never occur.
2637 Note: The kernel time discipline is
2638 disabled if the step threshold is set to zero or greater than the
2640 .It Cm stepout Ar stepout
2641 The argument is the stepout timeout, which by default is 900 s.
2643 be set to any positive number in seconds.
2644 If set to zero, the stepout
2645 pulses will not be suppressed.
2647 .It Xo Ic trap Ar host_address
2648 .Op Cm port Ar port_number
2649 .Op Cm interface Ar interface_address
2651 This command configures a trap receiver at the given host
2652 address and port number for sending messages with the specified
2653 local interface address.
2654 If the port number is unspecified, a value
2656 If the interface address is not specified, the
2657 message is sent with a source address of the local interface the
2658 message is sent through.
2659 Note that on a multihomed host the
2660 interface used may vary from time to time with routing changes.
2662 The trap receiver will generally log event messages and other
2663 information from the server in a log file.
2665 programs may also request their own trap dynamically, configuring a
2666 trap receiver will ensure that no messages are lost when the server
2669 This command specifies a list of TTL values in increasing order, up to 8
2670 values can be specified.
2671 In manycast mode these values are used in turn in
2672 an expanding-ring search.
2673 The default is eight multiples of 32 starting at
2677 .Bl -tag -width /etc/ntp.drift -compact
2678 .It Pa /etc/ntp.conf
2679 the default name of the configuration file
2684 .It Pa ntpkey_ Ns Ar host
2687 Diffie-Hellman agreement parameters
2695 In addition to the manual pages provided,
2696 comprehensive documentation is available on the world wide web
2698 .Li http://www.ntp.org/ .
2699 A snapshot of this documentation is available in HTML format in
2700 .Pa /usr/share/doc/ntp .
2703 .%T Network Time Protocol (Version 3)
2707 The syntax checking is not picky; some combinations of
2708 ridiculous and even hilarious options and modes may not be
2712 .Pa ntpkey_ Ns Ar host
2713 files are really digital
2715 These should be obtained via secure directory
2716 services when they become universally available.