2 .Dt NTP_CONF 5 File Formats
4 .\" EDIT THIS FILE WITH CAUTION (ntp.mdoc)
8 .\" It has been AutoGen-ed February 27, 2018 at 05:14:42 PM by AutoGen 5.18.5
9 .\" From the definitions ntp.conf.def
10 .\" and the template file agmdoc-cmd.tpl
13 .Nd Network Time Protocol (NTP) daemon configuration file format
17 .Op Fl \-option\-name Ar value
19 All arguments must be options.
24 configuration file is read at initial startup by the
26 daemon in order to specify the synchronization sources,
27 modes and other related information.
28 Usually, it is installed in the
31 but could be installed elsewhere
36 The file format is similar to other
41 character and extend to the end of the line;
42 blank lines are ignored.
43 Configuration commands consist of an initial keyword
44 followed by a list of arguments,
45 some of which may be optional, separated by whitespace.
46 Commands may not be continued over multiple lines.
47 Arguments may be host names,
48 host addresses written in numeric, dotted\-quad form,
49 integers, floating point numbers (when specifying times in seconds)
52 The rest of this page describes the configuration and control options.
54 .Qq Notes on Configuring NTP and Setting up an NTP Subnet
56 (available as part of the HTML documentation
58 .Pa /usr/share/doc/ntp )
59 contains an extended discussion of these options.
60 In addition to the discussion of general
61 .Sx Configuration Options ,
62 there are sections describing the following supported functionality
63 and the options used to control it:
64 .Bl -bullet -offset indent
66 .Sx Authentication Support
68 .Sx Monitoring Support
70 .Sx Access Control Support
72 .Sx Automatic NTP Configuration Options
74 .Sx Reference Clock Support
76 .Sx Miscellaneous Options
79 Following these is a section describing
80 .Sx Miscellaneous Options .
81 While there is a rich set of options available,
82 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
123 IPv6 addresses are automatically generated.
124 IPv6 addresses can be identified by the presence of colons
126 in the address field.
127 IPv6 addresses can be used almost everywhere where
128 IPv4 addresses can be used,
129 with the exception of reference clock addresses,
130 which are always IPv4.
132 Note that in contexts where a host name is expected, a
135 the host name forces DNS resolution to the IPv4 namespace,
138 qualifier forces DNS resolution to the IPv6 namespace.
139 See IPv6 references for the
140 equivalent classes for that address family.
141 .Bl -tag -width indent
142 .It Xo Ic pool Ar address
145 .Op Cm version Ar version
147 .Op Cm minpoll Ar minpoll
148 .Op Cm maxpoll Ar maxpoll
150 .It Xo Ic server Ar address
151 .Op Cm key Ar key \&| Cm autokey
154 .Op Cm version Ar version
156 .Op Cm minpoll Ar minpoll
157 .Op Cm maxpoll Ar maxpoll
160 .It Xo Ic peer Ar address
161 .Op Cm key Ar key \&| Cm autokey
162 .Op Cm version Ar version
164 .Op Cm minpoll Ar minpoll
165 .Op Cm maxpoll Ar maxpoll
169 .It Xo Ic broadcast Ar address
170 .Op Cm key Ar key \&| Cm autokey
171 .Op Cm version Ar version
173 .Op Cm minpoll Ar minpoll
177 .It Xo Ic manycastclient Ar address
178 .Op Cm key Ar key \&| Cm autokey
179 .Op Cm version Ar version
181 .Op Cm minpoll Ar minpoll
182 .Op Cm maxpoll Ar maxpoll
187 These five commands specify the time server name or address to
188 be used and the mode in which to operate.
192 either a DNS name or an IP address in dotted\-quad notation.
193 Additional information on association behavior can be found in the
194 .Qq Association Management
196 (available as part of the HTML documentation
198 .Pa /usr/share/doc/ntp ) .
199 .Bl -tag -width indent
201 For type s addresses, this command mobilizes a persistent
202 client mode association with a number of remote servers.
203 In this mode the local clock can synchronized to the
204 remote server, but the remote server can never be synchronized to
207 For type s and r addresses, this command mobilizes a persistent
208 client mode association with the specified remote server or local
210 In this mode the local clock can synchronized to the
211 remote server, but the remote server can never be synchronized to
218 For type s addresses (only), this command mobilizes a
219 persistent symmetric\-active mode association with the specified
221 In this mode the local clock can be synchronized to
222 the remote peer or the remote peer can be synchronized to the local
224 This is useful in a network of servers where, depending on
225 various failure scenarios, either the local or remote peer may be
226 the better source of time.
227 This command should NOT be used for type
230 For type b and m addresses (only), this
231 command mobilizes a persistent broadcast mode association.
233 commands can be used to specify multiple local broadcast interfaces
234 (subnets) and/or multiple multicast groups.
236 broadcast messages go only to the interface associated with the
237 subnet specified, but multicast messages go to all interfaces.
238 In broadcast mode the local server sends periodic broadcast
239 messages to a client population at the
241 specified, which is usually the broadcast address on (one of) the
242 local network(s) or a multicast address assigned to NTP.
244 has assigned the multicast group address IPv4 224.0.1.1 and
245 IPv6 ff05::101 (site local) exclusively to
246 NTP, but other nonconflicting addresses can be used to contain the
247 messages within administrative boundaries.
249 specification applies only to the local server operating as a
250 sender; for operation as a broadcast client, see the
256 .It Ic manycastclient
257 For type m addresses (only), this command mobilizes a
258 manycast client mode association for the multicast address
260 In this case a specific address must be supplied which
261 matches the address used on the
264 the designated manycast servers.
265 The NTP multicast address
266 224.0.1.1 assigned by the IANA should NOT be used, unless specific
267 means are taken to avoid spraying large areas of the Internet with
268 these messages and causing a possibly massive implosion of replies
272 command specifies that the local server
273 is to operate in client mode with the remote servers that are
274 discovered as the result of broadcast/multicast messages.
276 client broadcasts a request message to the group address associated
279 and specifically enabled
280 servers respond to these messages.
281 The client selects the servers
282 providing the best time and continues as with the
285 The remaining servers are discarded as if never
290 .Bl -tag -width indent
292 All packets sent to and received from the server or peer are to
293 include authentication fields encrypted using the autokey scheme
295 .Sx Authentication Options .
297 when the server is reachable, send a burst of eight packets
298 instead of the usual one.
299 The packet spacing is normally 2 s;
300 however, the spacing between the first and second packets
301 can be changed with the
304 additional time for a modem or ISDN call to complete.
305 This is designed to improve timekeeping quality
308 command and s addresses.
310 When the server is unreachable, send a burst of eight packets
311 instead of the usual one.
312 The packet spacing is normally 2 s;
313 however, the spacing between the first two packets can be
317 additional time for a modem or ISDN call to complete.
318 This is designed to speed the initial synchronization
321 command and s addresses and when
327 All packets sent to and received from the server or peer are to
328 include authentication fields encrypted using the specified
330 identifier with values from 1 to 65534, inclusive.
332 default is to include no encryption field.
333 .It Cm minpoll Ar minpoll
334 .It Cm maxpoll Ar maxpoll
335 These options specify the minimum and maximum poll intervals
336 for NTP messages, as a power of 2 in seconds
338 interval defaults to 10 (1,024 s), but can be increased by the
340 option to an upper limit of 17 (36.4 h).
342 minimum poll interval defaults to 6 (64 s), but can be decreased by
345 option to a lower limit of 4 (16 s).
347 Marks the server as unused, except for display purposes.
348 The server is discarded by the selection algroithm.
350 Says the association can be preempted.
352 Marks the server as a truechimer.
353 Use this option only for testing.
355 Marks the server as preferred.
356 All other things being equal,
357 this host will be chosen for synchronization among a set of
358 correctly operating hosts.
360 .Qq Mitigation Rules and the prefer Keyword
362 (available as part of the HTML documentation
364 .Pa /usr/share/doc/ntp )
365 for further information.
367 Forces the association to always survive the selection and clustering algorithms.
368 This option should almost certainly
370 be used while testing an association.
372 This option is used only with broadcast server and manycast
374 It specifies the time\-to\-live
377 use on broadcast server and multicast server and the maximum
379 for the expanding ring search with manycast
381 Selection of the proper value, which defaults to
382 127, is something of a black art and should be coordinated with the
383 network administrator.
384 .It Cm version Ar version
385 Specifies the version number to be used for outgoing NTP
387 Versions 1\-4 are the choices, with version 4 the
394 modes only, this flag enables interleave mode.
396 .Ss Auxiliary Commands
397 .Bl -tag -width indent
398 .It Ic broadcastclient
399 This command enables reception of broadcast server messages to
400 any local interface (type b) address.
401 Upon receiving a message for
402 the first time, the broadcast client measures the nominal server
403 propagation delay using a brief client/server exchange with the
404 server, then enters the broadcast client mode, in which it
405 synchronizes to succeeding broadcast messages.
407 to avoid accidental or malicious disruption in this mode, both the
408 server and client should operate using symmetric\-key or public\-key
409 authentication as described in
410 .Sx Authentication Options .
411 .It Ic manycastserver Ar address ...
412 This command enables reception of manycast client messages to
413 the multicast group address(es) (type m) specified.
415 address is required, but the NTP multicast address 224.0.1.1
416 assigned by the IANA should NOT be used, unless specific means are
417 taken to limit the span of the reply and avoid a possibly massive
418 implosion at the original sender.
419 Note that, in order to avoid
420 accidental or malicious disruption in this mode, both the server
421 and client should operate using symmetric\-key or public\-key
422 authentication as described in
423 .Sx Authentication Options .
424 .It Ic multicastclient Ar address ...
425 This command enables reception of multicast server messages to
426 the multicast group address(es) (type m) specified.
428 a message for the first time, the multicast client measures the
429 nominal server propagation delay using a brief client/server
430 exchange with the server, then enters the broadcast client mode, in
431 which it synchronizes to succeeding multicast messages.
433 in order to avoid accidental or malicious disruption in this mode,
434 both the server and client should operate using symmetric\-key or
435 public\-key authentication as described in
436 .Sx Authentication Options .
437 .It Ic mdnstries Ar number
438 If we are participating in mDNS,
439 after we have synched for the first time
440 we attempt to register with the mDNS system.
441 If that registration attempt fails,
442 we try again at one minute intervals for up to
447 may be starting before mDNS.
448 The default value for
452 .Sh Authentication Support
453 Authentication support allows the NTP client to verify that the
454 server is in fact known and trusted and not an intruder intending
455 accidentally or on purpose to masquerade as that server.
457 specification RFC\-1305 defines a scheme which provides
458 cryptographic authentication of received NTP packets.
460 this was done using the Data Encryption Standard (DES) algorithm
461 operating in Cipher Block Chaining (CBC) mode, commonly called
463 Subsequently, this was replaced by the RSA Message Digest
464 5 (MD5) algorithm using a private key, commonly called keyed\-MD5.
465 Either algorithm computes a message digest, or one\-way hash, which
466 can be used to verify the server has the correct private key and
469 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
470 cryptography and, in addition, provides a new Autokey scheme
471 based on public key cryptography.
472 Public key cryptography is generally considered more secure
473 than symmetric key cryptography, since the security is based
474 on a private value which is generated by each server and
476 With Autokey all key distribution and
477 management functions involve only public values, which
478 considerably simplifies key distribution and storage.
479 Public key management is based on X.509 certificates,
480 which can be provided by commercial services or
481 produced by utility programs in the OpenSSL software library
482 or the NTPv4 distribution.
484 While the algorithms for symmetric key cryptography are
485 included in the NTPv4 distribution, public key cryptography
486 requires the OpenSSL software library to be installed
487 before building the NTP distribution.
488 Directions for doing that
489 are on the Building and Installing the Distribution page.
491 Authentication is configured separately for each association
502 configuration commands as described in
503 .Sx Configuration Options
506 options described below specify the locations of the key files,
507 if other than default, which symmetric keys are trusted
508 and the interval between various operations, if other than default.
510 Authentication is always enabled,
511 although ineffective if not configured as
513 If a NTP packet arrives
514 including a message authentication
515 code (MAC), it is accepted only if it
516 passes all cryptographic checks.
518 checks require correct key ID, key value
521 been modified in any way or replayed
522 by an intruder, it will fail one or more
523 of these checks and be discarded.
524 Furthermore, the Autokey scheme requires a
525 preliminary protocol exchange to obtain
526 the server certificate, verify its
527 credentials and initialize the protocol
531 flag controls whether new associations or
532 remote configuration commands require cryptographic authentication.
533 This flag can be set or reset by the
537 commands and also by remote
538 configuration commands sent by a
542 If this flag is enabled, which is the default
543 case, new broadcast client and symmetric passive associations and
544 remote configuration commands must be cryptographically
545 authenticated using either symmetric key or public key cryptography.
547 flag is disabled, these operations are effective
548 even if not cryptographic
550 It should be understood
551 that operating with the
553 flag disabled invites a significant vulnerability
554 where a rogue hacker can
555 masquerade as a falseticker and seriously
556 disrupt system timekeeping.
558 important to note that this flag has no purpose
559 other than to allow or disallow
560 a new association in response to new broadcast
561 and symmetric active messages
562 and remote configuration commands and, in particular,
563 the flag has no effect on
564 the authentication process itself.
566 An attractive alternative where multicast support is available
567 is manycast mode, in which clients periodically troll
568 for servers as described in the
569 .Sx Automatic NTP Configuration Options
571 Either symmetric key or public key
572 cryptographic authentication can be used in this mode.
573 The principle advantage
574 of manycast mode is that potential servers need not be
575 configured in advance,
576 since the client finds them during regular operation,
577 and the configuration
578 files for all clients can be identical.
580 The security model and protocol schemes for
581 both symmetric key and public key
582 cryptography are summarized below;
583 further details are in the briefings, papers
584 and reports at the NTP project page linked from
585 .Li http://www.ntp.org/ .
586 .Ss Symmetric\-Key Cryptography
587 The original RFC\-1305 specification allows any one of possibly
588 65,534 keys, each distinguished by a 32\-bit key identifier, to
589 authenticate an association.
590 The servers and clients involved must
591 agree on the key and key identifier to
592 authenticate NTP packets.
594 related information are specified in a key
597 which must be distributed and stored using
598 secure means beyond the scope of the NTP protocol itself.
599 Besides the keys used
600 for ordinary NTP associations,
601 additional keys can be used as passwords for the
609 is first started, it reads the key file specified in the
611 configuration command and installs the keys
614 individual keys must be activated with the
618 allows, for instance, the installation of possibly
619 several batches of keys and
620 then activating or deactivating each batch
623 This also provides a revocation capability that can be used
624 if a key becomes compromised.
627 command selects the key used as the password for the
631 command selects the key used as the password for the
634 .Ss Public Key Cryptography
635 NTPv4 supports the original NTPv3 symmetric key scheme
636 described in RFC\-1305 and in addition the Autokey protocol,
637 which is based on public key cryptography.
638 The Autokey Version 2 protocol described on the Autokey Protocol
639 page verifies packet integrity using MD5 message digests
640 and verifies the source with digital signatures and any of several
641 digest/signature schemes.
642 Optional identity schemes described on the Identity Schemes
643 page and based on cryptographic challenge/response algorithms
645 Using all of these schemes provides strong security against
646 replay with or without modification, spoofing, masquerade
647 and most forms of clogging attacks.
649 .\" The cryptographic means necessary for all Autokey operations
650 .\" is provided by the OpenSSL software library.
651 .\" This library is available from http://www.openssl.org/
652 .\" and can be installed using the procedures outlined
653 .\" in the Building and Installing the Distribution page.
655 .\" the configure and build
656 .\" process automatically detects the library and links
657 .\" the library routines required.
659 The Autokey protocol has several modes of operation
660 corresponding to the various NTP modes supported.
661 Most modes use a special cookie which can be
662 computed independently by the client and server,
663 but encrypted in transmission.
664 All modes use in addition a variant of the S\-KEY scheme,
665 in which a pseudo\-random key list is generated and used
667 These schemes are described along with an executive summary,
668 current status, briefing slides and reading list on the
669 .Sx Autonomous Authentication
672 The specific cryptographic environment used by Autokey servers
673 and clients is determined by a set of files
674 and soft links generated by the
675 .Xr ntp\-keygen 1ntpkeygenmdoc
677 This includes a required host key file,
678 required certificate file and optional sign key file,
679 leapsecond file and identity scheme files.
681 digest/signature scheme is specified in the X.509 certificate
682 along with the matching sign key.
683 There are several schemes
684 available in the OpenSSL software library, each identified
685 by a specific string such as
686 .Cm md5WithRSAEncryption ,
687 which stands for the MD5 message digest with RSA
689 The current NTP distribution supports
690 all the schemes in the OpenSSL library, including
691 those based on RSA and DSA digital signatures.
693 NTP secure groups can be used to define cryptographic compartments
694 and security hierarchies.
695 It is important that every host
696 in the group be able to construct a certificate trail to one
697 or more trusted hosts in the same group.
699 host runs the Autokey protocol to obtain the certificates
700 for all hosts along the trail to one or more trusted hosts.
701 This requires the configuration file in all hosts to be
702 engineered so that, even under anticipated failure conditions,
703 the NTP subnet will form such that every group host can find
704 a trail to at least one trusted host.
705 .Ss Naming and Addressing
706 It is important to note that Autokey does not use DNS to
707 resolve addresses, since DNS can't be completely trusted
708 until the name servers have synchronized clocks.
709 The cryptographic name used by Autokey to bind the host identity
710 credentials and cryptographic values must be independent
711 of interface, network and any other naming convention.
712 The name appears in the host certificate in either or both
713 the subject and issuer fields, so protection against
714 DNS compromise is essential.
716 By convention, the name of an Autokey host is the name returned
719 system call or equivalent in other systems.
721 model, there are no provisions to allow alternate names or aliases.
722 However, this is not to say that DNS aliases, different names
723 for each interface, etc., are constrained in any way.
725 It is also important to note that Autokey verifies authenticity
726 using the host name, network address and public keys,
727 all of which are bound together by the protocol specifically
728 to deflect masquerade attacks.
729 For this reason Autokey
730 includes the source and destination IP addresses in message digest
731 computations and so the same addresses must be available
732 at both the server and client.
733 For this reason operation
734 with network address translation schemes is not possible.
735 This reflects the intended robust security model where government
736 and corporate NTP servers are operated outside firewall perimeters.
738 A specific combination of authentication scheme (none,
739 symmetric key, public key) and identity scheme is called
740 a cryptotype, although not all combinations are compatible.
741 There may be management configurations where the clients,
742 servers and peers may not all support the same cryptotypes.
743 A secure NTPv4 subnet can be configured in many ways while
744 keeping in mind the principles explained above and
746 Note however that some cryptotype
747 combinations may successfully interoperate with each other,
748 but may not represent good security practice.
750 The cryptotype of an association is determined at the time
751 of mobilization, either at configuration time or some time
752 later when a message of appropriate cryptotype arrives.
757 configuration command and no
761 subcommands are present, the association is not
762 authenticated; if the
764 subcommand is present, the association is authenticated
765 using the symmetric key ID specified; if the
767 subcommand is present, the association is authenticated
770 When multiple identity schemes are supported in the Autokey
771 protocol, the first message exchange determines which one is used.
772 The client request message contains bits corresponding
773 to which schemes it has available.
774 The server response message
775 contains bits corresponding to which schemes it has available.
776 Both server and client match the received bits with their own
777 and select a common scheme.
779 Following the principle that time is a public value,
780 a server responds to any client packet that matches
781 its cryptotype capabilities.
782 Thus, a server receiving
783 an unauthenticated packet will respond with an unauthenticated
784 packet, while the same server receiving a packet of a cryptotype
785 it supports will respond with packets of that cryptotype.
786 However, unconfigured broadcast or manycast client
787 associations or symmetric passive associations will not be
788 mobilized unless the server supports a cryptotype compatible
789 with the first packet received.
790 By default, unauthenticated associations will not be mobilized
791 unless overridden in a decidedly dangerous way.
793 Some examples may help to reduce confusion.
794 Client Alice has no specific cryptotype selected.
795 Server Bob has both a symmetric key file and minimal Autokey files.
796 Alice's unauthenticated messages arrive at Bob, who replies with
797 unauthenticated messages.
798 Cathy has a copy of Bob's symmetric
799 key file and has selected key ID 4 in messages to Bob.
800 Bob verifies the message with his key ID 4.
802 same key and the message is verified, Bob sends Cathy a reply
803 authenticated with that key.
804 If verification fails,
805 Bob sends Cathy a thing called a crypto\-NAK, which tells her
807 She can see the evidence using the
811 Denise has rolled her own host key and certificate.
812 She also uses one of the identity schemes as Bob.
813 She sends the first Autokey message to Bob and they
814 both dance the protocol authentication and identity steps.
815 If all comes out okay, Denise and Bob continue as described above.
817 It should be clear from the above that Bob can support
818 all the girls at the same time, as long as he has compatible
819 authentication and identity credentials.
820 Now, Bob can act just like the girls in his own choice of servers;
821 he can run multiple configured associations with multiple different
822 servers (or the same server, although that might not be useful).
823 But, wise security policy might preclude some cryptotype
824 combinations; for instance, running an identity scheme
825 with one server and no authentication with another might not be wise.
827 The cryptographic values used by the Autokey protocol are
828 incorporated as a set of files generated by the
829 .Xr ntp\-keygen 1ntpkeygenmdoc
830 utility program, including symmetric key, host key and
831 public certificate files, as well as sign key, identity parameters
832 and leapseconds files.
833 Alternatively, host and sign keys and
834 certificate files can be generated by the OpenSSL utilities
835 and certificates can be imported from public certificate
837 Note that symmetric keys are necessary for the
842 The remaining files are necessary only for the
845 Certificates imported from OpenSSL or public certificate
846 authorities have certian limitations.
847 The certificate should be in ASN.1 syntax, X.509 Version 3
848 format and encoded in PEM, which is the same format
850 The overall length of the certificate encoded
851 in ASN.1 must not exceed 1024 bytes.
852 The subject distinguished
853 name field (CN) is the fully qualified name of the host
854 on which it is used; the remaining subject fields are ignored.
855 The certificate extension fields must not contain either
856 a subject key identifier or a issuer key identifier field;
857 however, an extended key usage field for a trusted host must
860 Other extension fields are ignored.
861 .Ss Authentication Commands
862 .Bl -tag -width indent
863 .It Ic autokey Op Ar logsec
864 Specifies the interval between regenerations of the session key
865 list used with the Autokey protocol.
866 Note that the size of the key
867 list for each association depends on this interval and the current
869 The default value is 12 (4096 s or about 1.1 hours).
870 For poll intervals above the specified interval, a session key list
871 with a single entry will be regenerated for every message
873 .It Ic controlkey Ar key
874 Specifies the key identifier to use with the
876 utility, which uses the standard
877 protocol defined in RFC\-1305.
881 the key identifier for a trusted key, where the value can be in the
882 range 1 to 65,534, inclusive.
886 .Op Cm randfile Ar file
891 .Op Cm iffpar Ar file
893 .Op Cm pw Ar password
895 This command requires the OpenSSL library.
896 It activates public key
897 cryptography, selects the message digest and signature
898 encryption scheme and loads the required private and public
899 values described above.
900 If one or more files are left unspecified,
901 the default names are used as described above.
902 Unless the complete path and name of the file are specified, the
903 location of a file is relative to the keys directory specified
908 Following are the subcommands:
909 .Bl -tag -width indent
911 Specifies the location of the required host public certificate file.
912 This overrides the link
913 .Pa ntpkey_cert_ Ns Ar hostname
914 in the keys directory.
916 Specifies the location of the optional GQ parameters file.
919 .Pa ntpkey_gq_ Ns Ar hostname
920 in the keys directory.
922 Specifies the location of the required host key file.
925 .Pa ntpkey_key_ Ns Ar hostname
926 in the keys directory.
927 .It Cm iffpar Ar file
928 Specifies the location of the optional IFF parameters file.
929 This overrides the link
930 .Pa ntpkey_iff_ Ns Ar hostname
931 in the keys directory.
933 Specifies the location of the optional leapsecond file.
934 This overrides the link
936 in the keys directory.
938 Specifies the location of the optional MV parameters file.
939 This overrides the link
940 .Pa ntpkey_mv_ Ns Ar hostname
941 in the keys directory.
942 .It Cm pw Ar password
943 Specifies the password to decrypt files containing private keys and
945 This is required only if these files have been
947 .It Cm randfile Ar file
948 Specifies the location of the random seed file used by the OpenSSL
950 The defaults are described in the main text above.
952 Specifies the location of the optional sign key file.
955 .Pa ntpkey_sign_ Ns Ar hostname
956 in the keys directory.
958 not found, the host key is also the sign key.
960 .It Ic keys Ar keyfile
961 Specifies the complete path and location of the MD5 key file
962 containing the keys and key identifiers used by
967 when operating with symmetric key cryptography.
968 This is the same operation as the
971 .It Ic keysdir Ar path
972 This command specifies the default directory path for
973 cryptographic keys, parameters and certificates.
975 .Pa /usr/local/etc/ .
976 .It Ic requestkey Ar key
977 Specifies the key identifier to use with the
979 utility program, which uses a
980 proprietary protocol specific to this implementation of
984 argument is a key identifier
985 for the trusted key, where the value can be in the range 1 to
987 .It Ic revoke Ar logsec
988 Specifies the interval between re\-randomization of certain
989 cryptographic values used by the Autokey scheme, as a power of 2 in
991 These values need to be updated frequently in order to
992 deflect brute\-force attacks on the algorithms of the scheme;
993 however, updating some values is a relatively expensive operation.
994 The default interval is 16 (65,536 s or about 18 hours).
996 intervals above the specified interval, the values will be updated
997 for every message sent.
998 .It Ic trustedkey Ar key ...
999 Specifies the key identifiers which are trusted for the
1000 purposes of authenticating peers with symmetric key cryptography,
1001 as well as keys used by the
1006 The authentication procedures require that both the local
1007 and remote servers share the same key and key identifier for this
1008 purpose, although different keys can be used with different
1012 arguments are 32\-bit unsigned
1013 integers with values from 1 to 65,534.
1016 The following error codes are reported via the NTP control
1017 and monitoring protocol trap mechanism.
1018 .Bl -tag -width indent
1020 .Pq bad field format or length
1021 The packet has invalid version, length or format.
1024 The packet timestamp is the same or older than the most recent received.
1025 This could be due to a replay or a server clock time step.
1028 The packet filestamp is the same or older than the most recent received.
1029 This could be due to a replay or a key file generation error.
1031 .Pq bad or missing public key
1032 The public key is missing, has incorrect format or is an unsupported type.
1034 .Pq unsupported digest type
1035 The server requires an unsupported digest/signature scheme.
1037 .Pq mismatched digest types
1040 .Pq bad signature length
1041 The signature length does not match the current public key.
1043 .Pq signature not verified
1044 The message fails the signature check.
1045 It could be bogus or signed by a
1046 different private key.
1048 .Pq certificate not verified
1049 The certificate is invalid or signed with the wrong key.
1051 .Pq certificate not verified
1052 The certificate is not yet valid or has expired or the signature could not
1055 .Pq bad or missing cookie
1056 The cookie is missing, corrupted or bogus.
1058 .Pq bad or missing leapseconds table
1059 The leapseconds table is missing, corrupted or bogus.
1061 .Pq bad or missing certificate
1062 The certificate is missing, corrupted or bogus.
1064 .Pq bad or missing identity
1065 The identity key is missing, corrupt or bogus.
1067 .Sh Monitoring Support
1069 includes a comprehensive monitoring facility suitable
1070 for continuous, long term recording of server and client
1071 timekeeping performance.
1075 for a listing and example of each type of statistics currently
1077 Statistic files are managed using file generation sets
1080 directory of the source code distribution.
1082 these facilities and
1085 jobs, the data can be
1086 automatically summarized and archived for retrospective analysis.
1087 .Ss Monitoring Commands
1088 .Bl -tag -width indent
1089 .It Ic statistics Ar name ...
1090 Enables writing of statistics records.
1091 Currently, eight kinds of
1093 statistics are supported.
1094 .Bl -tag -width indent
1096 Enables recording of clock driver statistics information.
1098 received from a clock driver appends a line of the following form to
1099 the file generation set named
1102 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1105 The first two fields show the date (Modified Julian Day) and time
1106 (seconds and fraction past UTC midnight).
1107 The next field shows the
1108 clock address in dotted\-quad notation.
1109 The final field shows the last
1110 timecode received from the clock in decoded ASCII format, where
1112 In some clock drivers a good deal of additional information
1113 can be gathered and displayed as well.
1114 See information specific to each
1115 clock for further details.
1117 This option requires the OpenSSL cryptographic software library.
1119 enables recording of cryptographic public key protocol information.
1120 Each message received by the protocol module appends a line of the
1121 following form to the file generation set named
1124 49213 525.624 127.127.4.1 message
1127 The first two fields show the date (Modified Julian Day) and time
1128 (seconds and fraction past UTC midnight).
1129 The next field shows the peer
1130 address in dotted\-quad notation, The final message field includes the
1131 message type and certain ancillary information.
1133 .Sx Authentication Options
1134 section for further information.
1136 Enables recording of loop filter statistics information.
1138 update of the local clock outputs a line of the following form to
1139 the file generation set named
1142 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1145 The first two fields show the date (Modified Julian Day) and
1146 time (seconds and fraction past UTC midnight).
1147 The next five fields
1148 show time offset (seconds), frequency offset (parts per million \-
1149 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1150 discipline time constant.
1152 Enables recording of peer statistics information.
1154 statistics records of all peers of a NTP server and of special
1155 signals, where present and configured.
1156 Each valid update appends a
1157 line of the following form to the current element of a file
1158 generation set named
1161 48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674
1164 The first two fields show the date (Modified Julian Day) and
1165 time (seconds and fraction past UTC midnight).
1167 show the peer address in dotted\-quad notation and status,
1169 The status field is encoded in hex in the format
1170 described in Appendix A of the NTP specification RFC 1305.
1171 The final four fields show the offset,
1172 delay, dispersion and RMS jitter, all in seconds.
1174 Enables recording of raw\-timestamp statistics information.
1176 includes statistics records of all peers of a NTP server and of
1177 special signals, where present and configured.
1179 received from a peer or clock driver appends a line of the
1180 following form to the file generation set named
1183 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1186 The first two fields show the date (Modified Julian Day) and
1187 time (seconds and fraction past UTC midnight).
1189 show the remote peer or clock address followed by the local address
1190 in dotted\-quad notation.
1191 The final four fields show the originate,
1192 receive, transmit and final NTP timestamps in order.
1194 values are as received and before processing by the various data
1195 smoothing and mitigation algorithms.
1197 Enables recording of ntpd statistics counters on a periodic basis.
1199 hour a line of the following form is appended to the file generation
1203 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1206 The first two fields show the date (Modified Julian Day) and time
1207 (seconds and fraction past UTC midnight).
1208 The remaining ten fields show
1209 the statistics counter values accumulated since the last generated
1211 .Bl -tag -width indent
1212 .It Time since restart Cm 36000
1213 Time in hours since the system was last rebooted.
1214 .It Packets received Cm 81965
1215 Total number of packets received.
1216 .It Packets processed Cm 0
1217 Number of packets received in response to previous packets sent
1218 .It Current version Cm 9546
1219 Number of packets matching the current NTP version.
1220 .It Previous version Cm 56
1221 Number of packets matching the previous NTP version.
1222 .It Bad version Cm 71793
1223 Number of packets matching neither NTP version.
1224 .It Access denied Cm 512
1225 Number of packets denied access for any reason.
1226 .It Bad length or format Cm 540
1227 Number of packets with invalid length, format or port number.
1228 .It Bad authentication Cm 10
1229 Number of packets not verified as authentic.
1230 .It Rate exceeded Cm 147
1231 Number of packets discarded due to rate limitation.
1233 .It Cm statsdir Ar directory_path
1234 Indicates the full path of a directory where statistics files
1235 should be created (see below).
1237 the (otherwise constant)
1239 filename prefix to be modified for file generation sets, which
1240 is useful for handling statistics logs.
1241 .It Cm filegen Ar name Xo
1242 .Op Cm file Ar filename
1243 .Op Cm type Ar typename
1244 .Op Cm link | nolink
1245 .Op Cm enable | disable
1247 Configures setting of generation file set name.
1249 file sets provide a means for handling files that are
1250 continuously growing during the lifetime of a server.
1251 Server statistics are a typical example for such files.
1252 Generation file sets provide access to a set of files used
1253 to store the actual data.
1254 At any time at most one element
1255 of the set is being written to.
1256 The type given specifies
1257 when and how data will be directed to a new element of the set.
1258 This way, information stored in elements of a file set
1259 that are currently unused are available for administrational
1260 operations without the risk of disturbing the operation of ntpd.
1261 (Most important: they can be removed to free space for new data
1264 Note that this command can be sent from the
1266 program running at a remote location.
1267 .Bl -tag -width indent
1269 This is the type of the statistics records, as shown in the
1272 .It Cm file Ar filename
1273 This is the file name for the statistics records.
1275 members are built from three concatenated elements
1280 .Bl -tag -width indent
1282 This is a constant filename path.
1283 It is not subject to
1284 modifications via the
1287 It is defined by the
1288 server, usually specified as a compile\-time constant.
1290 however, be configurable for individual file generation sets
1292 For example, the prefix used with
1296 generation can be configured using the
1298 option explained above.
1300 This string is directly concatenated to the prefix mentioned
1301 above (no intervening
1303 This can be modified using
1304 the file argument to the
1310 allowed in this component to prevent filenames referring to
1311 parts outside the filesystem hierarchy denoted by
1314 This part is reflects individual elements of a file set.
1316 generated according to the type of a file set.
1318 .It Cm type Ar typename
1319 A file generation set is characterized by its type.
1321 types are supported:
1322 .Bl -tag -width indent
1324 The file set is actually a single plain file.
1326 One element of file set is used per incarnation of a ntpd
1328 This type does not perform any changes to file set
1329 members during runtime, however it provides an easy way of
1330 separating files belonging to different
1332 server incarnations.
1333 The set member filename is built by appending a
1340 appending the decimal representation of the process ID of the
1344 One file generation set element is created per day.
1346 defined as the period between 00:00 and 24:00 UTC.
1348 member suffix consists of a
1350 and a day specification in
1354 is a 4\-digit year number (e.g., 1992).
1356 is a two digit month number.
1358 is a two digit day number.
1359 Thus, all information written at 10 December 1992 would end up
1362 .Ar filename Ns .19921210 .
1364 Any file set member contains data related to a certain week of
1366 The term week is defined by computing day\-of\-year
1368 Elements of such a file generation set are
1369 distinguished by appending the following suffix to the file set
1370 filename base: A dot, a 4\-digit year number, the letter
1372 and a 2\-digit week number.
1373 For example, information from January,
1374 10th 1992 would end up in a file with suffix
1375 .No . Ns Ar 1992W1 .
1377 One generation file set element is generated per month.
1379 file name suffix consists of a dot, a 4\-digit year number, and
1382 One generation file element is generated per year.
1384 suffix consists of a dot and a 4 digit year number.
1386 This type of file generation sets changes to a new element of
1387 the file set every 24 hours of server operation.
1389 suffix consists of a dot, the letter
1391 and an 8\-digit number.
1392 This number is taken to be the number of seconds the server is
1393 running at the start of the corresponding 24\-hour period.
1394 Information is only written to a file generation by specifying
1396 output is prevented by specifying
1399 .It Cm link | nolink
1400 It is convenient to be able to access the current element of a file
1401 generation set by a fixed name.
1402 This feature is enabled by
1407 If link is specified, a
1408 hard link from the current file set element to a file without
1410 When there is already a file with this name and
1411 the number of links of this file is one, it is renamed appending a
1418 number of links is greater than one, the file is unlinked.
1420 allows the current file to be accessed by a constant name.
1421 .It Cm enable \&| Cm disable
1422 Enables or disables the recording function.
1426 .Sh Access Control Support
1429 daemon implements a general purpose address/mask based restriction
1431 The list contains address/match entries sorted first
1432 by increasing address values and and then by increasing mask values.
1433 A match occurs when the bitwise AND of the mask and the packet
1434 source address is equal to the bitwise AND of the mask and
1435 address in the list.
1436 The list is searched in order with the
1437 last match found defining the restriction flags associated
1439 Additional information and examples can be found in the
1440 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
1442 (available as part of the HTML documentation
1444 .Pa /usr/share/doc/ntp ) .
1446 The restriction facility was implemented in conformance
1447 with the access policies for the original NSFnet backbone
1449 Later the facility was expanded to deflect
1450 cryptographic and clogging attacks.
1451 While this facility may
1452 be useful for keeping unwanted or broken or malicious clients
1453 from congesting innocent servers, it should not be considered
1454 an alternative to the NTP authentication facilities.
1455 Source address based restrictions are easily circumvented
1456 by a determined cracker.
1458 Clients can be denied service because they are explicitly
1459 included in the restrict list created by the
1462 or implicitly as the result of cryptographic or rate limit
1464 Cryptographic violations include certificate
1465 or identity verification failure; rate limit violations generally
1466 result from defective NTP implementations that send packets
1468 Some violations cause denied service
1469 only for the offending packet, others cause denied service
1470 for a timed period and others cause the denied service for
1471 an indefinite period.
1472 When a client or network is denied access
1473 for an indefinite period, the only way at present to remove
1474 the restrictions is by restarting the server.
1475 .Ss The Kiss\-of\-Death Packet
1476 Ordinarily, packets denied service are simply dropped with no
1477 further action except incrementing statistics counters.
1479 more proactive response is needed, such as a server message that
1480 explicitly requests the client to stop sending and leave a message
1481 for the system operator.
1482 A special packet format has been created
1483 for this purpose called the "kiss\-of\-death" (KoD) packet.
1484 KoD packets have the leap bits set unsynchronized and stratum set
1485 to zero and the reference identifier field set to a four\-byte
1491 flag of the matching restrict list entry is set,
1492 the code is "DENY"; if the
1494 flag is set and the rate limit
1495 is exceeded, the code is "RATE".
1496 Finally, if a cryptographic violation occurs, the code is "CRYP".
1498 A client receiving a KoD performs a set of sanity checks to
1499 minimize security exposure, then updates the stratum and
1500 reference identifier peer variables, sets the access
1501 denied (TEST4) bit in the peer flash variable and sends
1502 a message to the log.
1503 As long as the TEST4 bit is set,
1504 the client will send no further packets to the server.
1505 The only way at present to recover from this condition is
1506 to restart the protocol at both the client and server.
1508 happens automatically at the client when the association times out.
1509 It will happen at the server only if the server operator cooperates.
1510 .Ss Access Control Commands
1511 .Bl -tag -width indent
1513 .Op Cm average Ar avg
1514 .Op Cm minimum Ar min
1515 .Op Cm monitor Ar prob
1517 Set the parameters of the
1519 facility which protects the server from
1523 subcommand specifies the minimum average packet
1526 subcommand specifies the minimum packet spacing.
1527 Packets that violate these minima are discarded
1528 and a kiss\-o'\-death packet returned if enabled.
1530 minimum average and minimum are 5 and 2, respectively.
1533 subcommand specifies the probability of discard
1534 for packets that overflow the rate\-control window.
1535 .It Xo Ic restrict address
1537 .Op Cm ippeerlimit Ar int
1542 argument expressed in
1543 dotted\-quad form is the address of a host or network.
1546 argument can be a valid host DNS name.
1549 argument expressed in dotted\-quad form defaults to
1550 .Cm 255.255.255.255 ,
1553 is treated as the address of an individual host.
1554 A default entry (address
1558 is always included and is always the first entry in the list.
1559 Note that text string
1561 with no mask option, may
1562 be used to indicate the default entry.
1565 directive limits the number of peer requests for each IP to
1567 where a value of \-1 means "unlimited", the current default.
1568 A value of 0 means "none".
1569 There would usually be at most 1 peering request per IP,
1570 but if the remote peering requests are behind a proxy
1571 there could well be more than 1 per IP.
1572 In the current implementation,
1575 restricts access, i.e., an entry with no flags indicates that free
1576 access to the server is to be given.
1577 The flags are not orthogonal,
1578 in that more restrictive flags will often make less restrictive
1580 The flags can generally be classed into two
1581 categories, those which restrict time service and those which
1582 restrict informational queries and attempts to do run\-time
1583 reconfiguration of the server.
1584 One or more of the following flags
1586 .Bl -tag -width indent
1588 Deny packets of all kinds, including
1594 If this flag is set when an access violation occurs, a kiss\-o'\-death
1595 (KoD) packet is sent.
1596 KoD packets are rate limited to no more than one
1598 If another KoD packet occurs within one second after the
1599 last one, the packet is dropped.
1601 Deny service if the packet spacing violates the lower limits specified
1605 A history of clients is kept using the
1606 monitoring capability of
1608 Thus, monitoring is always active as
1609 long as there is a restriction entry with the
1613 Declare traps set by matching hosts to be low priority.
1615 number of traps a server can maintain is limited (the current limit
1617 Traps are usually assigned on a first come, first served
1618 basis, with later trap requestors being denied service.
1620 modifies the assignment algorithm by allowing low priority traps to
1621 be overridden by later requests for normal priority traps.
1623 Deny ephemeral peer requests,
1624 even if they come from an authenticated source.
1625 Note that the ability to use a symmetric key for authentication may be restricted to
1626 one or more IPs or subnets via the third field of the
1629 This restriction is not enabled by default,
1630 to maintain backward compatability.
1633 to become the default in ntp\-4.4.
1639 queries which attempt to modify the state of the
1640 server (i.e., run time reconfiguration).
1641 Queries which return
1642 information are permitted.
1649 Time service is not affected.
1651 Deny unauthenticated packets which would result in mobilizing a new association.
1653 broadcast and symmetric active packets
1654 when a configured association does not exist.
1657 associations, so if you want to use servers from a
1659 directive and also want to use
1661 by default, you'll want a
1662 .Cm "restrict source ..."
1663 line as well that does
1669 Deny all packets except
1675 Decline to provide mode 6 control message trap service to matching
1677 The trap service is a subsystem of the
1680 protocol which is intended for use by remote event logging programs.
1682 Deny service unless the packet is cryptographically authenticated.
1684 This is actually a match algorithm modifier, rather than a
1686 Its presence causes the restriction entry to be
1687 matched only if the source port in the packet is the standard NTP
1697 is considered more specific and
1698 is sorted later in the list.
1700 Deny packets that do not match the current NTP version.
1703 Default restriction list entries with the flags ignore, interface,
1704 ntpport, for each of the local host's interface addresses are
1705 inserted into the table at startup to prevent the server
1706 from attempting to synchronize to its own time.
1707 A default entry is also always present, though if it is
1708 otherwise unconfigured; no flags are associated
1709 with the default entry (i.e., everything besides your own
1710 NTP server is unrestricted).
1712 .Sh Automatic NTP Configuration Options
1714 Manycasting is a automatic discovery and configuration paradigm
1716 It is intended as a means for a multicast client
1717 to troll the nearby network neighborhood to find cooperating
1718 manycast servers, validate them using cryptographic means
1719 and evaluate their time values with respect to other servers
1720 that might be lurking in the vicinity.
1721 The intended result is that each manycast client mobilizes
1722 client associations with some number of the "best"
1723 of the nearby manycast servers, yet automatically reconfigures
1724 to sustain this number of servers should one or another fail.
1726 Note that the manycasting paradigm does not coincide
1727 with the anycast paradigm described in RFC\-1546,
1728 which is designed to find a single server from a clique
1729 of servers providing the same service.
1730 The manycast paradigm is designed to find a plurality
1731 of redundant servers satisfying defined optimality criteria.
1733 Manycasting can be used with either symmetric key
1734 or public key cryptography.
1735 The public key infrastructure (PKI)
1736 offers the best protection against compromised keys
1737 and is generally considered stronger, at least with relatively
1739 It is implemented using the Autokey protocol and
1740 the OpenSSL cryptographic library available from
1741 .Li http://www.openssl.org/ .
1742 The library can also be used with other NTPv4 modes
1743 as well and is highly recommended, especially for broadcast modes.
1745 A persistent manycast client association is configured
1748 command, which is similar to the
1750 command but with a multicast (IPv4 class
1755 The IANA has designated IPv4 address 224.1.1.1
1756 and IPv6 address FF05::101 (site local) for NTP.
1757 When more servers are needed, it broadcasts manycast
1758 client messages to this address at the minimum feasible rate
1759 and minimum feasible time\-to\-live (TTL) hops, depending
1760 on how many servers have already been found.
1761 There can be as many manycast client associations
1762 as different group address, each one serving as a template
1763 for a future ephemeral unicast client/server association.
1765 Manycast servers configured with the
1767 command listen on the specified group address for manycast
1769 Note the distinction between manycast client,
1770 which actively broadcasts messages, and manycast server,
1771 which passively responds to them.
1772 If a manycast server is
1773 in scope of the current TTL and is itself synchronized
1774 to a valid source and operating at a stratum level equal
1775 to or lower than the manycast client, it replies to the
1776 manycast client message with an ordinary unicast server message.
1778 The manycast client receiving this message mobilizes
1779 an ephemeral client/server association according to the
1780 matching manycast client template, but only if cryptographically
1781 authenticated and the server stratum is less than or equal
1782 to the client stratum.
1783 Authentication is explicitly required
1784 and either symmetric key or public key (Autokey) can be used.
1785 Then, the client polls the server at its unicast address
1786 in burst mode in order to reliably set the host clock
1787 and validate the source.
1788 This normally results
1789 in a volley of eight client/server at 2\-s intervals
1790 during which both the synchronization and cryptographic
1791 protocols run concurrently.
1792 Following the volley,
1793 the client runs the NTP intersection and clustering
1794 algorithms, which act to discard all but the "best"
1795 associations according to stratum and synchronization
1797 The surviving associations then continue
1798 in ordinary client/server mode.
1800 The manycast client polling strategy is designed to reduce
1801 as much as possible the volume of manycast client messages
1802 and the effects of implosion due to near\-simultaneous
1803 arrival of manycast server messages.
1804 The strategy is determined by the
1805 .Ic manycastclient ,
1809 configuration commands.
1810 The manycast poll interval is
1811 normally eight times the system poll interval,
1812 which starts out at the
1814 value specified in the
1815 .Ic manycastclient ,
1816 command and, under normal circumstances, increments to the
1818 value specified in this command.
1819 Initially, the TTL is
1820 set at the minimum hops specified by the
1823 At each retransmission the TTL is increased until reaching
1824 the maximum hops specified by this command or a sufficient
1825 number client associations have been found.
1826 Further retransmissions use the same TTL.
1828 The quality and reliability of the suite of associations
1829 discovered by the manycast client is determined by the NTP
1830 mitigation algorithms and the
1834 values specified in the
1836 configuration command.
1839 candidate servers must be available and the mitigation
1840 algorithms produce at least
1842 survivors in order to synchronize the clock.
1843 Byzantine agreement principles require at least four
1844 candidates in order to correctly discard a single falseticker.
1845 For legacy purposes,
1850 For manycast service
1852 should be explicitly set to 4, assuming at least that
1853 number of servers are available.
1857 servers are found, the manycast poll interval is immediately
1862 servers are found when the TTL has reached the maximum hops,
1863 the manycast poll interval is doubled.
1864 For each transmission
1865 after that, the poll interval is doubled again until
1866 reaching the maximum of eight times
1868 Further transmissions use the same poll interval and
1870 Note that while all this is going on,
1871 each client/server association found is operating normally
1872 it the system poll interval.
1874 Administratively scoped multicast boundaries are normally
1875 specified by the network router configuration and,
1876 in the case of IPv6, the link/site scope prefix.
1877 By default, the increment for TTL hops is 32 starting
1878 from 31; however, the
1880 configuration command can be
1881 used to modify the values to match the scope rules.
1883 It is often useful to narrow the range of acceptable
1884 servers which can be found by manycast client associations.
1885 Because manycast servers respond only when the client
1886 stratum is equal to or greater than the server stratum,
1887 primary (stratum 1) servers fill find only primary servers
1888 in TTL range, which is probably the most common objective.
1889 However, unless configured otherwise, all manycast clients
1890 in TTL range will eventually find all primary servers
1891 in TTL range, which is probably not the most common
1892 objective in large networks.
1895 command can be used to modify this behavior.
1896 Servers with stratum below
1902 command are strongly discouraged during the selection
1903 process; however, these servers may be temporally
1904 accepted if the number of servers within TTL range is
1908 The above actions occur for each manycast client message,
1909 which repeats at the designated poll interval.
1910 However, once the ephemeral client association is mobilized,
1911 subsequent manycast server replies are discarded,
1912 since that would result in a duplicate association.
1913 If during a poll interval the number of client associations
1916 all manycast client prototype associations are reset
1917 to the initial poll interval and TTL hops and operation
1918 resumes from the beginning.
1919 It is important to avoid
1920 frequent manycast client messages, since each one requires
1921 all manycast servers in TTL range to respond.
1922 The result could well be an implosion, either minor or major,
1923 depending on the number of servers in range.
1924 The recommended value for
1928 It is possible and frequently useful to configure a host
1929 as both manycast client and manycast server.
1930 A number of hosts configured this way and sharing a common
1931 group address will automatically organize themselves
1932 in an optimum configuration based on stratum and
1933 synchronization distance.
1934 For example, consider an NTP
1935 subnet of two primary servers and a hundred or more
1937 With two exceptions, all servers
1938 and clients have identical configuration files including both
1942 commands using, for instance, multicast group address
1944 The only exception is that each primary server
1945 configuration file must include commands for the primary
1946 reference source such as a GPS receiver.
1948 The remaining configuration files for all secondary
1949 servers and clients have the same contents, except for the
1951 command, which is specific for each stratum level.
1952 For stratum 1 and stratum 2 servers, that command is
1954 For stratum 3 and above servers the
1956 value is set to the intended stratum number.
1957 Thus, all stratum 3 configuration files are identical,
1958 all stratum 4 files are identical and so forth.
1960 Once operations have stabilized in this scenario,
1961 the primary servers will find the primary reference source
1962 and each other, since they both operate at the same
1963 stratum (1), but not with any secondary server or client,
1964 since these operate at a higher stratum.
1966 servers will find the servers at the same stratum level.
1967 If one of the primary servers loses its GPS receiver,
1968 it will continue to operate as a client and other clients
1969 will time out the corresponding association and
1970 re\-associate accordingly.
1972 Some administrators prefer to avoid running
1974 continuously and run either
1980 In either case the servers must be
1981 configured in advance and the program fails if none are
1982 available when the cron job runs.
1984 application of manycast is with
1987 The program wakes up, scans the local landscape looking
1988 for the usual suspects, selects the best from among
1989 the rascals, sets the clock and then departs.
1990 Servers do not have to be configured in advance and
1991 all clients throughout the network can have the same
1993 .Ss Manycast Interactions with Autokey
1994 Each time a manycast client sends a client mode packet
1995 to a multicast group address, all manycast servers
1996 in scope generate a reply including the host name
1998 The manycast clients then run
1999 the Autokey protocol, which collects and verifies
2000 all certificates involved.
2001 Following the burst interval
2002 all but three survivors are cast off,
2003 but the certificates remain in the local cache.
2004 It often happens that several complete signing trails
2005 from the client to the primary servers are collected in this way.
2007 About once an hour or less often if the poll interval
2008 exceeds this, the client regenerates the Autokey key list.
2009 This is in general transparent in client/server mode.
2010 However, about once per day the server private value
2011 used to generate cookies is refreshed along with all
2012 manycast client associations.
2014 cryptographic values including certificates is refreshed.
2015 If a new certificate has been generated since
2016 the last refresh epoch, it will automatically revoke
2017 all prior certificates that happen to be in the
2019 At the same time, the manycast
2020 scheme starts all over from the beginning and
2021 the expanding ring shrinks to the minimum and increments
2022 from there while collecting all servers in scope.
2023 .Ss Broadcast Options
2024 .Bl -tag -width indent
2027 .Cm bcpollbstep Ar gate
2030 This command provides a way to delay,
2031 by the specified number of broadcast poll intervals,
2032 believing backward time steps from a broadcast server.
2033 Broadcast time networks are expected to be trusted.
2034 In the event a broadcast server's time is stepped backwards,
2035 there is clear benefit to having the clients notice this change
2036 as soon as possible.
2037 Attacks such as replay attacks can happen, however,
2038 and even though there are a number of protections built in to
2039 broadcast mode, attempts to perform a replay attack are possible.
2040 This value defaults to 0, but can be changed
2041 to any number of poll intervals between 0 and 4.
2043 .Ss Manycast Options
2044 .Bl -tag -width indent
2047 .Cm ceiling Ar ceiling |
2048 .Cm cohort { 0 | 1 } |
2049 .Cm floor Ar floor |
2050 .Cm minclock Ar minclock |
2051 .Cm minsane Ar minsane
2054 This command affects the clock selection and clustering
2056 It can be used to select the quality and
2057 quantity of peers used to synchronize the system clock
2058 and is most useful in manycast mode.
2059 The variables operate
2061 .Bl -tag -width indent
2062 .It Cm ceiling Ar ceiling
2063 Peers with strata above
2065 will be discarded if there are at least
2068 This value defaults to 15, but can be changed
2069 to any number from 1 to 15.
2070 .It Cm cohort Bro 0 | 1 Brc
2071 This is a binary flag which enables (0) or disables (1)
2072 manycast server replies to manycast clients with the same
2074 This is useful to reduce implosions where
2075 large numbers of clients with the same stratum level
2077 The default is to enable these replies.
2078 .It Cm floor Ar floor
2079 Peers with strata below
2081 will be discarded if there are at least
2084 This value defaults to 1, but can be changed
2085 to any number from 1 to 15.
2086 .It Cm minclock Ar minclock
2087 The clustering algorithm repeatedly casts out outlier
2088 associations until no more than
2090 associations remain.
2091 This value defaults to 3,
2092 but can be changed to any number from 1 to the number of
2094 .It Cm minsane Ar minsane
2095 This is the minimum number of candidates available
2096 to the clock selection algorithm in order to produce
2097 one or more truechimers for the clustering algorithm.
2098 If fewer than this number are available, the clock is
2099 undisciplined and allowed to run free.
2101 for legacy purposes.
2102 However, according to principles of
2103 Byzantine agreement,
2105 should be at least 4 in order to detect and discard
2106 a single falseticker.
2108 .It Cm ttl Ar hop ...
2109 This command specifies a list of TTL values in increasing
2110 order, up to 8 values can be specified.
2111 In manycast mode these values are used in turn
2112 in an expanding\-ring search.
2113 The default is eight
2114 multiples of 32 starting at 31.
2116 .Sh Reference Clock Support
2117 The NTP Version 4 daemon supports some three dozen different radio,
2118 satellite and modem reference clocks plus a special pseudo\-clock
2119 used for backup or when no other clock source is available.
2120 Detailed descriptions of individual device drivers and options can
2122 .Qq Reference Clock Drivers
2124 (available as part of the HTML documentation
2126 .Pa /usr/share/doc/ntp ) .
2127 Additional information can be found in the pages linked
2128 there, including the
2129 .Qq Debugging Hints for Reference Clock Drivers
2131 .Qq How To Write a Reference Clock Driver
2133 (available as part of the HTML documentation
2135 .Pa /usr/share/doc/ntp ) .
2136 In addition, support for a PPS
2137 signal is available as described in the
2138 .Qq Pulse\-per\-second (PPS) Signal Interfacing
2140 (available as part of the HTML documentation
2142 .Pa /usr/share/doc/ntp ) .
2144 drivers support special line discipline/streams modules which can
2145 significantly improve the accuracy using the driver.
2148 .Qq Line Disciplines and Streams Drivers
2150 (available as part of the HTML documentation
2152 .Pa /usr/share/doc/ntp ) .
2154 A reference clock will generally (though not always) be a radio
2155 timecode receiver which is synchronized to a source of standard
2156 time such as the services offered by the NRC in Canada and NIST and
2158 The interface between the computer and the timecode
2159 receiver is device dependent, but is usually a serial port.
2161 device driver specific to each reference clock must be selected and
2162 compiled in the distribution; however, most common radio, satellite
2163 and modem clocks are included by default.
2164 Note that an attempt to
2165 configure a reference clock when the driver has not been compiled
2166 or the hardware port has not been appropriately configured results
2167 in a scalding remark to the system log file, but is otherwise non
2170 For the purposes of configuration,
2173 reference clocks in a manner analogous to normal NTP peers as much
2175 Reference clocks are identified by a syntactically
2176 correct but invalid IP address, in order to distinguish them from
2178 Reference clock addresses are of the form
2180 .Li 127.127. Ar t . Ar u ,
2185 denoting the clock type and
2188 number in the range 0\-3.
2189 While it may seem overkill, it is in fact
2190 sometimes useful to configure multiple reference clocks of the same
2191 type, in which case the unit numbers must be unique.
2195 command is used to configure a reference
2198 argument in that command
2199 is the clock address.
2205 options are not used for reference clock support.
2208 option is added for reference clock support, as
2212 option can be useful to
2213 persuade the server to cherish a reference clock with somewhat more
2214 enthusiasm than other reference clocks or peers.
2216 information on this option can be found in the
2217 .Qq Mitigation Rules and the prefer Keyword
2218 (available as part of the HTML documentation
2220 .Pa /usr/share/doc/ntp )
2227 meaning only for selected clock drivers.
2228 See the individual clock
2229 driver document pages for additional information.
2233 command is used to provide additional
2234 information for individual clock drivers and normally follows
2235 immediately after the
2240 argument specifies the clock address.
2245 options can be used to
2246 override the defaults for the device.
2247 There are two optional
2248 device\-dependent time offsets and four flags that can be included
2253 The stratum number of a reference clock is by default zero.
2256 daemon adds one to the stratum of each
2257 peer, a primary server ordinarily displays an external stratum of
2259 In order to provide engineered backups, it is often useful to
2260 specify the reference clock stratum as greater than zero.
2263 option is used for this purpose.
2265 involving both a reference clock and a pulse\-per\-second (PPS)
2266 discipline signal, it is useful to specify the reference clock
2267 identifier as other than the default, depending on the driver.
2270 option is used for this purpose.
2272 these options apply to all clock drivers.
2273 .Ss Reference Clock Commands
2274 .Bl -tag -width indent
2277 .Li 127.127. Ar t . Ar u
2281 .Op Cm minpoll Ar int
2282 .Op Cm maxpoll Ar int
2284 This command can be used to configure reference clocks in
2286 The options are interpreted as follows:
2287 .Bl -tag -width indent
2289 Marks the reference clock as preferred.
2290 All other things being
2291 equal, this host will be chosen for synchronization among a set of
2292 correctly operating hosts.
2294 .Qq Mitigation Rules and the prefer Keyword
2296 (available as part of the HTML documentation
2298 .Pa /usr/share/doc/ntp )
2299 for further information.
2301 Specifies a mode number which is interpreted in a
2302 device\-specific fashion.
2303 For instance, it selects a dialing
2304 protocol in the ACTS driver and a device subtype in the
2307 .It Cm minpoll Ar int
2308 .It Cm maxpoll Ar int
2309 These options specify the minimum and maximum polling interval
2310 for reference clock messages, as a power of 2 in seconds
2312 most directly connected reference clocks, both
2316 default to 6 (64 s).
2317 For modem reference clocks,
2319 defaults to 10 (17.1 m) and
2321 defaults to 14 (4.5 h).
2322 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2326 .Li 127.127. Ar t . Ar u
2330 .Op Cm stratum Ar int
2331 .Op Cm refid Ar string
2333 .Op Cm flag1 Cm 0 \&| Cm 1
2334 .Op Cm flag2 Cm 0 \&| Cm 1
2335 .Op Cm flag3 Cm 0 \&| Cm 1
2336 .Op Cm flag4 Cm 0 \&| Cm 1
2338 This command can be used to configure reference clocks in
2340 It must immediately follow the
2342 command which configures the driver.
2343 Note that the same capability
2344 is possible at run time using the
2347 The options are interpreted as
2349 .Bl -tag -width indent
2351 Specifies a constant to be added to the time offset produced by
2352 the driver, a fixed\-point decimal number in seconds.
2354 as a calibration constant to adjust the nominal time offset of a
2355 particular clock to agree with an external standard, such as a
2356 precision PPS signal.
2357 It also provides a way to correct a
2358 systematic error or bias due to serial port or operating system
2359 latencies, different cable lengths or receiver internal delay.
2361 specified offset is in addition to the propagation delay provided
2362 by other means, such as internal DIPswitches.
2364 for an individual system and driver is available, an approximate
2365 correction is noted in the driver documentation pages.
2366 Note: in order to facilitate calibration when more than one
2367 radio clock or PPS signal is supported, a special calibration
2368 feature is available.
2369 It takes the form of an argument to the
2371 command described in
2372 .Sx Miscellaneous Options
2373 page and operates as described in the
2374 .Qq Reference Clock Drivers
2376 (available as part of the HTML documentation
2378 .Pa /usr/share/doc/ntp ) .
2379 .It Cm time2 Ar secs
2380 Specifies a fixed\-point decimal number in seconds, which is
2381 interpreted in a driver\-dependent way.
2382 See the descriptions of
2383 specific drivers in the
2384 .Qq Reference Clock Drivers
2386 (available as part of the HTML documentation
2388 .Pa /usr/share/doc/ntp ).
2389 .It Cm stratum Ar int
2390 Specifies the stratum number assigned to the driver, an integer
2392 This number overrides the default stratum number
2393 ordinarily assigned by the driver itself, usually zero.
2394 .It Cm refid Ar string
2395 Specifies an ASCII string of from one to four characters which
2396 defines the reference identifier used by the driver.
2398 overrides the default identifier ordinarily assigned by the driver
2401 Specifies a mode number which is interpreted in a
2402 device\-specific fashion.
2403 For instance, it selects a dialing
2404 protocol in the ACTS driver and a device subtype in the
2407 .It Cm flag1 Cm 0 \&| Cm 1
2408 .It Cm flag2 Cm 0 \&| Cm 1
2409 .It Cm flag3 Cm 0 \&| Cm 1
2410 .It Cm flag4 Cm 0 \&| Cm 1
2411 These four flags are used for customizing the clock driver.
2413 interpretation of these values, and whether they are used at all,
2414 is a function of the particular clock driver.
2418 is used to enable recording monitoring
2421 file configured with the
2424 Further information on the
2426 command can be found in
2427 .Sx Monitoring Options .
2430 .Sh Miscellaneous Options
2431 .Bl -tag -width indent
2432 .It Ic broadcastdelay Ar seconds
2433 The broadcast and multicast modes require a special calibration
2434 to determine the network delay between the local and remote
2436 Ordinarily, this is done automatically by the initial
2437 protocol exchanges between the client and server.
2439 the calibration procedure may fail due to network or server access
2440 controls, for example.
2441 This command specifies the default delay to
2442 be used under these circumstances.
2443 Typically (for Ethernet), a
2444 number between 0.003 and 0.007 seconds is appropriate.
2446 when this command is not used is 0.004 seconds.
2447 .It Ic calldelay Ar delay
2448 This option controls the delay in seconds between the first and second
2449 packets sent in burst or iburst mode to allow additional time for a modem
2450 or ISDN call to complete.
2451 .It Ic driftfile Ar driftfile
2452 This command specifies the complete path and name of the file used to
2453 record the frequency of the local clock oscillator.
2457 command line option.
2458 If the file exists, it is read at
2459 startup in order to set the initial frequency and then updated once per
2460 hour with the current frequency computed by the daemon.
2462 specified, but the file itself does not exist, the starts with an initial
2463 frequency of zero and creates the file when writing it for the first time.
2464 If this command is not given, the daemon will always start with an initial
2467 The file format consists of a single line containing a single
2468 floating point number, which records the frequency offset measured
2469 in parts\-per\-million (PPM).
2470 The file is updated by first writing
2471 the current drift value into a temporary file and then renaming
2472 this file to replace the old version.
2475 must have write permission for the directory the
2476 drift file is located in, and that file system links, symbolic or
2477 otherwise, should be avoided.
2478 .It Ic dscp Ar value
2479 This option specifies the Differentiated Services Control Point (DSCP) value,
2481 The default value is 46, signifying Expedited Forwarding.
2484 .Cm auth | Cm bclient |
2485 .Cm calibrate | Cm kernel |
2486 .Cm mode7 | Cm monitor |
2487 .Cm ntp | Cm stats |
2488 .Cm peer_clear_digest_early |
2489 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2494 .Cm auth | Cm bclient |
2495 .Cm calibrate | Cm kernel |
2496 .Cm mode7 | Cm monitor |
2497 .Cm ntp | Cm stats |
2498 .Cm peer_clear_digest_early |
2499 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2502 Provides a way to enable or disable various server options.
2503 Flags not mentioned are unaffected.
2504 Note that all of these flags
2505 can be controlled remotely using the
2508 .Bl -tag -width indent
2510 Enables the server to synchronize with unconfigured peers only if the
2511 peer has been correctly authenticated using either public key or
2512 private key cryptography.
2513 The default for this flag is
2516 Enables the server to listen for a message from a broadcast or
2517 multicast server, as in the
2519 command with default
2521 The default for this flag is
2524 Enables the calibrate feature for reference clocks.
2529 Enables the kernel time discipline, if available.
2530 The default for this
2533 if support is available, otherwise
2536 Enables processing of NTP mode 7 implementation\-specific requests
2537 which are used by the deprecated
2540 The default for this flag is disable.
2541 This flag is excluded from runtime configuration using
2545 program provides the same capabilities as
2547 using standard mode 6 requests.
2549 Enables the monitoring facility.
2555 command or further information.
2557 default for this flag is
2560 Enables time and frequency discipline.
2561 In effect, this switch opens and
2562 closes the feedback loop, which is useful for testing.
2566 .It Cm peer_clear_digest_early
2569 is using autokey and it
2570 receives a crypto\-NAK packet that
2571 passes the duplicate packet and origin timestamp checks
2572 the peer variables are immediately cleared.
2573 While this is generally a feature
2574 as it allows for quick recovery if a server key has changed,
2575 a properly forged and appropriately delivered crypto\-NAK packet
2576 can be used in a DoS attack.
2577 If you have active noticable problems with this type of DoS attack
2578 then you should consider
2579 disabling this option.
2582 file for evidence of any of these attacks.
2584 default for this flag is
2587 Enables the statistics facility.
2589 .Sx Monitoring Options
2590 section for further information.
2591 The default for this flag is
2593 .It Cm unpeer_crypto_early
2596 receives an autokey packet that fails TEST9,
2598 the association is immediately cleared.
2599 This is almost certainly a feature,
2600 but if, in spite of the current recommendation of not using autokey,
2605 you are seeing this sort of DoS attack
2606 disabling this flag will delay
2607 tearing down the association until the reachability counter
2611 file for evidence of any of these attacks.
2613 default for this flag is
2615 .It Cm unpeer_crypto_nak_early
2618 receives a crypto\-NAK packet that
2619 passes the duplicate packet and origin timestamp checks
2620 the association is immediately cleared.
2621 While this is generally a feature
2622 as it allows for quick recovery if a server key has changed,
2623 a properly forged and appropriately delivered crypto\-NAK packet
2624 can be used in a DoS attack.
2625 If you have active noticable problems with this type of DoS attack
2626 then you should consider
2627 disabling this option.
2630 file for evidence of any of these attacks.
2632 default for this flag is
2634 .It Cm unpeer_digest_early
2637 receives what should be an authenticated packet
2638 that passes other packet sanity checks but
2639 contains an invalid digest
2640 the association is immediately cleared.
2641 While this is generally a feature
2642 as it allows for quick recovery,
2643 if this type of packet is carefully forged and sent
2644 during an appropriate window it can be used for a DoS attack.
2645 If you have active noticable problems with this type of DoS attack
2646 then you should consider
2647 disabling this option.
2650 file for evidence of any of these attacks.
2652 default for this flag is
2655 .It Ic includefile Ar includefile
2656 This command allows additional configuration commands
2657 to be included from a separate file.
2659 be nested to a depth of five; upon reaching the end of any
2660 include file, command processing resumes in the previous
2662 This option is useful for sites that run
2664 on multiple hosts, with (mostly) common options (e.g., a
2668 .Cm listen | Cm ignore | Cm drop
2671 .Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard
2672 .Ar name | Ar address
2673 .Oo Cm / Ar prefixlen
2679 directive controls which network addresses
2681 opens, and whether input is dropped without processing.
2682 The first parameter determines the action for addresses
2683 which match the second parameter.
2684 The second parameter specifies a class of addresses,
2685 or a specific interface name,
2687 In the address case,
2689 determines how many bits must match for this rule to apply.
2691 prevents opening matching addresses,
2695 to open the address and drop all received packets without examination.
2698 directives can be used.
2699 The last rule which matches a particular address determines the action for it.
2701 directives are disabled if any
2707 command\-line options are specified in the configuration file,
2708 all available network addresses are opened.
2711 directive is an alias for
2713 .It Ic leapfile Ar leapfile
2714 This command loads the IERS leapseconds file and initializes the
2715 leapsecond values for the next leapsecond event, leapfile expiration
2716 time, and TAI offset.
2717 The file can be obtained directly from the IERS at
2718 .Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list
2720 .Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list .
2726 .Cm leapfile directive or when
2727 .Cm ntpd detects that the
2731 checks once a day to see if the
2735 .Xr update\-leap 1update_leapmdoc
2736 script can be run to see if the
2739 .It Ic leapsmearinterval Ar seconds
2740 This EXPERIMENTAL option is only available if
2743 .Cm \-\-enable\-leap\-smear
2747 It specifies the interval over which a leap second correction will be applied.
2748 Recommended values for this option are between
2749 7200 (2 hours) and 86400 (24 hours).
2750 .Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS!
2751 See http://bugs.ntp.org/2855 for more information.
2752 .It Ic logconfig Ar configkeyword
2753 This command controls the amount and type of output written to
2756 facility or the alternate
2759 By default, all output is turned on.
2762 keywords can be prefixed with
2778 messages can be controlled in four
2787 Within these classes four types of messages can be
2788 controlled: informational messages
2806 Configuration keywords are formed by concatenating the message class with
2810 prefix can be used instead of a message class.
2812 message class may also be followed by the
2814 keyword to enable/disable all
2815 messages of the respective message class.
2816 Thus, a minimal log configuration
2817 could look like this:
2819 logconfig =syncstatus +sysevents
2822 This would just list the synchronizations state of
2824 and the major system events.
2825 For a simple reference server, the
2826 following minimum message configuration could be useful:
2828 logconfig =syncall +clockall
2831 This configuration will list all clock information and
2832 synchronization information.
2833 All other events and messages about
2834 peers, system events and so on is suppressed.
2835 .It Ic logfile Ar logfile
2836 This command specifies the location of an alternate log file to
2837 be used instead of the default system
2840 This is the same operation as the
2842 command line option.
2845 .Cm maxdepth Ar count | Cm maxmem Ar kilobytes |
2846 .Cm mindepth Ar count | Cm maxage Ar seconds |
2847 .Cm initialloc Ar count | Cm initmem Ar kilobytes |
2848 .Cm incalloc Ar count | Cm incmem Ar kilobytes
2851 Controls size limite of the monitoring facility's Most Recently Used
2853 of client addresses, which is also used by the
2854 rate control facility.
2855 .Bl -tag -width indent
2856 .It Ic maxdepth Ar count
2857 .It Ic maxmem Ar kilobytes
2858 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2859 The acutal limit will be up to
2866 options offered in units of entries or kilobytes, if both
2869 .Cm maxmem are used, the last one used controls.
2870 The default is 1024 kilobytes.
2871 .It Cm mindepth Ar count
2872 Lower limit on the MRU list size.
2873 When the MRU list has fewer than
2875 entries, existing entries are never removed to make room for newer ones,
2876 regardless of their age.
2877 The default is 600 entries.
2878 .It Cm maxage Ar seconds
2879 Once the MRU list has
2881 entries and an additional client is to ba added to the list,
2882 if the oldest entry was updated more than
2884 seconds ago, that entry is removed and its storage is reused.
2885 If the oldest entry was updated more recently the MRU list is grown,
2887 .Cm maxdepth / moxmem .
2888 The default is 64 seconds.
2889 .It Cm initalloc Ar count
2890 .It Cm initmem Ar kilobytes
2891 Initial memory allocation at the time the monitoringfacility is first enabled,
2892 in terms of the number of entries or kilobytes.
2893 The default is 4 kilobytes.
2894 .It Cm incalloc Ar count
2895 .It Cm incmem Ar kilobytes
2896 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2897 The default is 4 kilobytes.
2899 .It Ic nonvolatile Ar threshold
2902 delta in seconds before an hourly change to the
2904 (frequency file) will be written, with a default value of 1e\-7 (0.1 PPM).
2905 The frequency file is inspected each hour.
2906 If the difference between the current frequency and the last value written
2907 exceeds the threshold, the file is written and the
2909 becomes the new threshold value.
2910 If the threshold is not exceeeded, it is reduced by half.
2911 This is intended to reduce the number of file writes
2912 for embedded systems with nonvolatile memory.
2913 .It Ic phone Ar dial ...
2914 This command is used in conjunction with
2915 the ACTS modem driver (type 18)
2916 or the JJY driver (type 40, mode 100 \- 180).
2917 For the ACTS modem driver (type 18), the arguments consist of
2918 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2920 For the JJY driver (type 40 mode 100 \- 180), the argument is
2921 one telephone number used to dial the telephone JJY service.
2922 The Hayes command ATDT is normally prepended to the number.
2923 The number can contain other modem control codes as well.
2947 Reset one or more groups of counters maintained by
2955 .Cm memlock Ar Nmegabytes |
2956 .Cm stacksize Ar N4kPages
2957 .Cm filenum Ar Nfiledescriptors
2960 .Bl -tag -width indent
2961 .It Cm memlock Ar Nmegabytes
2962 Specify the number of megabytes of memory that should be
2963 allocated and locked.
2964 Probably only available under Linux, this option may be useful
2965 when dropping root (the
2968 The default is 32 megabytes on non\-Linux machines, and \-1 under Linux.
2969 -1 means "do not lock the process into memory".
2970 0 means "lock whatever memory the process wants into memory".
2971 .It Cm stacksize Ar N4kPages
2972 Specifies the maximum size of the process stack on systems with the
2975 Defaults to 50 4k pages (200 4k pages in OpenBSD).
2976 .It Cm filenum Ar Nfiledescriptors
2977 Specifies the maximum number of file descriptors ntpd may have open at once.
2978 Defaults to the system default.
2980 .It Ic saveconfigdir Ar directory_path
2981 Specify the directory in which to write configuration snapshots
2988 does not appear in the configuration file,
2990 requests are rejected by
2992 .It Ic saveconfig Ar filename
2993 Write the current configuration, including any runtime
2994 modifications given with
2997 .Cm config\-from\-file
3004 This command will be rejected unless the
3006 directive appears in
3012 format directives to substitute the current date and time,
3014 .Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf .
3015 The filename used is stored in the system variable
3017 Authentication is required.
3018 .It Ic setvar Ar variable Op Cm default
3019 This command adds an additional system variable.
3021 variables can be used to distribute additional information such as
3023 If the variable of the form
3030 variable will be listed as part of the default system variables
3036 These additional variables serve
3037 informational purposes only.
3038 They are not related to the protocol
3039 other that they can be listed.
3040 The known protocol variables will
3041 always override any variables defined via the
3044 There are three special variables that contain the names
3045 of all variable of the same group.
3049 the names of all system variables.
3053 the names of all peer variables and the
3055 holds the names of the reference clock variables.
3057 Display operational summary.
3059 Show statistics counters maintained in the protocol module.
3062 .Cm allan Ar allan |
3063 .Cm dispersion Ar dispersion |
3065 .Cm huffpuff Ar huffpuff |
3066 .Cm panic Ar panic |
3068 .Cm stepback Ar stepback |
3069 .Cm stepfwd Ar stepfwd |
3070 .Cm stepout Ar stepout
3073 This command can be used to alter several system variables in
3074 very exceptional circumstances.
3075 It should occur in the
3076 configuration file before any other configuration options.
3078 default values of these variables have been carefully optimized for
3079 a wide range of network speeds and reliability expectations.
3081 general, they interact in intricate ways that are hard to predict
3082 and some combinations can result in some very nasty behavior.
3084 rarely is it necessary to change the default values; but, some
3085 folks cannot resist twisting the knobs anyway and this command is
3087 Emphasis added: twisters are on their own and can expect
3088 no help from the support group.
3090 The variables operate as follows:
3091 .Bl -tag -width indent
3092 .It Cm allan Ar allan
3093 The argument becomes the new value for the minimum Allan
3094 intercept, which is a parameter of the PLL/FLL clock discipline
3096 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
3098 .It Cm dispersion Ar dispersion
3099 The argument becomes the new value for the dispersion increase rate,
3100 normally .000015 s/s.
3102 The argument becomes the initial value of the frequency offset in
3103 parts\-per\-million.
3104 This overrides the value in the frequency file, if
3105 present, and avoids the initial training state if it is not.
3106 .It Cm huffpuff Ar huffpuff
3107 The argument becomes the new value for the experimental
3108 huff\-n'\-puff filter span, which determines the most recent interval
3109 the algorithm will search for a minimum delay.
3111 900 s (15 m), but a more reasonable value is 7200 (2 hours).
3113 is no default, since the filter is not enabled unless this command
3115 .It Cm panic Ar panic
3116 The argument is the panic threshold, normally 1000 s.
3118 the panic sanity check is disabled and a clock offset of any value will
3121 The argument is the step threshold, which by default is 0.128 s.
3123 be set to any positive number in seconds.
3124 If set to zero, step
3125 adjustments will never occur.
3126 Note: The kernel time discipline is
3127 disabled if the step threshold is set to zero or greater than the
3129 .It Cm stepback Ar stepback
3130 The argument is the step threshold for the backward direction,
3131 which by default is 0.128 s.
3133 be set to any positive number in seconds.
3134 If both the forward and backward step thresholds are set to zero, step
3135 adjustments will never occur.
3136 Note: The kernel time discipline is
3138 each direction of step threshold are either
3139 set to zero or greater than .5 second.
3140 .It Cm stepfwd Ar stepfwd
3141 As for stepback, but for the forward direction.
3142 .It Cm stepout Ar stepout
3143 The argument is the stepout timeout, which by default is 900 s.
3145 be set to any positive number in seconds.
3146 If set to zero, the stepout
3147 pulses will not be suppressed.
3149 .It Cm writevar Ar assocID\ name = value [,...]
3150 Write (create or update) the specified variables.
3153 is zero, the variablea re from the
3155 name space, otherwise they are from the
3160 is required, as the same name can occur in both name spaces.
3161 .It Xo Ic trap Ar host_address
3162 .Op Cm port Ar port_number
3163 .Op Cm interface Ar interface_address
3165 This command configures a trap receiver at the given host
3166 address and port number for sending messages with the specified
3167 local interface address.
3168 If the port number is unspecified, a value
3170 If the interface address is not specified, the
3171 message is sent with a source address of the local interface the
3172 message is sent through.
3173 Note that on a multihomed host the
3174 interface used may vary from time to time with routing changes.
3175 .It Cm ttl Ar hop ...
3176 This command specifies a list of TTL values in increasing order.
3177 Up to 8 values can be specified.
3180 mode these values are used in\-turn in an expanding\-ring search.
3181 The default is eight multiples of 32 starting at 31.
3183 The trap receiver will generally log event messages and other
3184 information from the server in a log file.
3186 programs may also request their own trap dynamically, configuring a
3187 trap receiver will ensure that no messages are lost when the server
3190 This command specifies a list of TTL values in increasing order, up to 8
3191 values can be specified.
3192 In manycast mode these values are used in turn in
3193 an expanding\-ring search.
3194 The default is eight multiples of 32 starting at
3200 Display usage information and exit.
3202 Pass the extended usage information through a pager.
3203 .It Fl \-version Op Brq Ar v|c|n
3204 Output version of program and exit. The default mode is `v', a simple
3205 version. The `c' mode will print copyright information and `n' will
3206 print the full copyright notice.
3208 .Sh "OPTION PRESETS"
3209 Any option that is not marked as \fInot presettable\fP may be preset
3210 by loading values from environment variables named:
3212 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP
3216 See \fBOPTION PRESETS\fP for configuration environment variables.
3218 .Bl -tag -width /etc/ntp.drift -compact
3219 .It Pa /etc/ntp.conf
3220 the default name of the configuration file
3225 .It Pa ntpkey_ Ns Ar host
3228 Diffie\-Hellman agreement parameters
3231 One of the following exit values will be returned:
3233 .It 0 " (EXIT_SUCCESS)"
3234 Successful program execution.
3235 .It 1 " (EXIT_FAILURE)"
3236 The operation failed or the command syntax was not valid.
3237 .It 70 " (EX_SOFTWARE)"
3238 libopts had an internal operational error. Please report
3239 it to autogen\-users@lists.sourceforge.net. Thank you.
3246 In addition to the manual pages provided,
3247 comprehensive documentation is available on the world wide web
3249 .Li http://www.ntp.org/ .
3250 A snapshot of this documentation is available in HTML format in
3251 .Pa /usr/share/doc/ntp .
3254 .%T Network Time Protocol (Version 4)
3258 The University of Delaware and Network Time Foundation
3260 Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
3261 This program is released under the terms of the NTP license, <http://ntp.org/license>.
3263 The syntax checking is not picky; some combinations of
3264 ridiculous and even hilarious options and modes may not be
3268 .Pa ntpkey_ Ns Ar host
3269 files are really digital
3271 These should be obtained via secure directory
3272 services when they become universally available.
3274 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
3276 This document was derived from FreeBSD.
3278 This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP