2 .Dt NTP_CONF 5 File Formats
4 .\" EDIT THIS FILE WITH CAUTION (ntp.mdoc)
6 .\" It has been AutoGen-ed March 3, 2020 at 05:40:53 PM by AutoGen 5.18.5
7 .\" From the definitions ntp.conf.def
8 .\" and the template file agmdoc-cmd.tpl
11 .Nd Network Time Protocol (NTP) daemon configuration file format
15 .Op Fl \-option\-name Ar value
17 All arguments must be options.
22 configuration file is read at initial startup by the
24 daemon in order to specify the synchronization sources,
25 modes and other related information.
26 Usually, it is installed in the
29 but could be installed elsewhere
34 The file format is similar to other
39 character and extend to the end of the line;
40 blank lines are ignored.
41 Configuration commands consist of an initial keyword
42 followed by a list of arguments,
43 some of which may be optional, separated by whitespace.
44 Commands may not be continued over multiple lines.
45 Arguments may be host names,
46 host addresses written in numeric, dotted\-quad form,
47 integers, floating point numbers (when specifying times in seconds)
50 The rest of this page describes the configuration and control options.
52 .Qq Notes on Configuring NTP and Setting up an NTP Subnet
54 (available as part of the HTML documentation
56 .Pa /usr/share/doc/ntp )
57 contains an extended discussion of these options.
58 In addition to the discussion of general
59 .Sx Configuration Options ,
60 there are sections describing the following supported functionality
61 and the options used to control it:
62 .Bl -bullet -offset indent
64 .Sx Authentication Support
66 .Sx Monitoring Support
68 .Sx Access Control Support
70 .Sx Automatic NTP Configuration Options
72 .Sx Reference Clock Support
74 .Sx Miscellaneous Options
77 Following these is a section describing
78 .Sx Miscellaneous Options .
79 While there is a rich set of options available,
80 the only required option is one or more
88 .Sh Configuration Support
89 Following is a description of the configuration commands in
91 These commands have the same basic functions as in NTPv3 and
92 in some cases new functions and new arguments.
94 classes of commands, configuration commands that configure a
95 persistent association with a remote server or peer or reference
96 clock, and auxiliary commands that specify environmental variables
97 that control various related operations.
98 .Ss Configuration Commands
99 The various modes are determined by the command keyword and the
100 type of the required IP address.
101 Addresses are classed by type as
102 (s) a remote server or peer (IPv4 class A, B and C), (b) the
103 broadcast address of a local interface, (m) a multicast address (IPv4
104 class D), or (r) a reference clock address (127.127.x.x).
106 only those options applicable to each command are listed below.
108 of options not listed may not be caught as an error, but may result
109 in some weird and even destructive behavior.
111 If the Basic Socket Interface Extensions for IPv6 (RFC\-2553)
112 is detected, support for the IPv6 address family is generated
113 in addition to the default support of the IPv4 address family.
114 In a few cases, including the
120 .Xr ntpdc @NTPDC_MS@ ,
121 IPv6 addresses are automatically generated.
122 IPv6 addresses can be identified by the presence of colons
124 in the address field.
125 IPv6 addresses can be used almost everywhere where
126 IPv4 addresses can be used,
127 with the exception of reference clock addresses,
128 which are always IPv4.
130 Note that in contexts where a host name is expected, a
133 the host name forces DNS resolution to the IPv4 namespace,
136 qualifier forces DNS resolution to the IPv6 namespace.
137 See IPv6 references for the
138 equivalent classes for that address family.
139 .Bl -tag -width indent
140 .It Xo Ic pool Ar address
143 .Op Cm version Ar version
145 .Op Cm minpoll Ar minpoll
146 .Op Cm maxpoll Ar maxpoll
149 .It Xo Ic server Ar address
150 .Op Cm key Ar key \&| Cm autokey
153 .Op Cm version Ar version
155 .Op Cm minpoll Ar minpoll
156 .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 65535, 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 preferred.
353 All other things being equal,
354 this host will be chosen for synchronization among a set of
355 correctly operating hosts.
357 .Qq Mitigation Rules and the prefer Keyword
359 (available as part of the HTML documentation
361 .Pa /usr/share/doc/ntp )
362 for further information.
364 Marks the server as a truechimer,
365 forcing the association to always survive the selection and clustering algorithms.
366 This option should almost certainly
368 be used while testing an association.
370 This option is used only with broadcast server and manycast
372 It specifies the time\-to\-live
375 use on broadcast server and multicast server and the maximum
377 for the expanding ring search with manycast
379 Selection of the proper value, which defaults to
380 127, is something of a black art and should be coordinated with the
381 network administrator.
382 .It Cm version Ar version
383 Specifies the version number to be used for outgoing NTP
385 Versions 1\-4 are the choices, with version 4 the
392 modes only, this flag enables interleave mode.
398 modes, this flag puts a random number in the packet's transmit timestamp.
400 .Ss Auxiliary Commands
401 .Bl -tag -width indent
402 .It Ic broadcastclient
403 This command enables reception of broadcast server messages to
404 any local interface (type b) address.
405 Upon receiving a message for
406 the first time, the broadcast client measures the nominal server
407 propagation delay using a brief client/server exchange with the
408 server, then enters the broadcast client mode, in which it
409 synchronizes to succeeding broadcast messages.
411 to avoid accidental or malicious disruption in this mode, both the
412 server and client should operate using symmetric\-key or public\-key
413 authentication as described in
414 .Sx Authentication Options .
415 .It Ic manycastserver Ar address ...
416 This command enables reception of manycast client messages to
417 the multicast group address(es) (type m) specified.
419 address is required, but the NTP multicast address 224.0.1.1
420 assigned by the IANA should NOT be used, unless specific means are
421 taken to limit the span of the reply and avoid a possibly massive
422 implosion at the original sender.
423 Note that, in order to avoid
424 accidental or malicious disruption in this mode, both the server
425 and client should operate using symmetric\-key or public\-key
426 authentication as described in
427 .Sx Authentication Options .
428 .It Ic multicastclient Ar address ...
429 This command enables reception of multicast server messages to
430 the multicast group address(es) (type m) specified.
432 a message for the first time, the multicast client measures the
433 nominal server propagation delay using a brief client/server
434 exchange with the server, then enters the broadcast client mode, in
435 which it synchronizes to succeeding multicast messages.
437 in order to avoid accidental or malicious disruption in this mode,
438 both the server and client should operate using symmetric\-key or
439 public\-key authentication as described in
440 .Sx Authentication Options .
441 .It Ic mdnstries Ar number
442 If we are participating in mDNS,
443 after we have synched for the first time
444 we attempt to register with the mDNS system.
445 If that registration attempt fails,
446 we try again at one minute intervals for up to
451 may be starting before mDNS.
452 The default value for
456 .Sh Authentication Support
457 Authentication support allows the NTP client to verify that the
458 server is in fact known and trusted and not an intruder intending
459 accidentally or on purpose to masquerade as that server.
461 specification RFC\-1305 defines a scheme which provides
462 cryptographic authentication of received NTP packets.
464 this was done using the Data Encryption Standard (DES) algorithm
465 operating in Cipher Block Chaining (CBC) mode, commonly called
467 Subsequently, this was replaced by the RSA Message Digest
468 5 (MD5) algorithm using a private key, commonly called keyed\-MD5.
469 Either algorithm computes a message digest, or one\-way hash, which
470 can be used to verify the server has the correct private key and
473 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
474 cryptography and, in addition, provides a new Autokey scheme
475 based on public key cryptography.
476 Public key cryptography is generally considered more secure
477 than symmetric key cryptography, since the security is based
478 on a private value which is generated by each server and
480 With Autokey all key distribution and
481 management functions involve only public values, which
482 considerably simplifies key distribution and storage.
483 Public key management is based on X.509 certificates,
484 which can be provided by commercial services or
485 produced by utility programs in the OpenSSL software library
486 or the NTPv4 distribution.
488 While the algorithms for symmetric key cryptography are
489 included in the NTPv4 distribution, public key cryptography
490 requires the OpenSSL software library to be installed
491 before building the NTP distribution.
492 Directions for doing that
493 are on the Building and Installing the Distribution page.
495 Authentication is configured separately for each association
506 configuration commands as described in
507 .Sx Configuration Options
510 options described below specify the locations of the key files,
511 if other than default, which symmetric keys are trusted
512 and the interval between various operations, if other than default.
514 Authentication is always enabled,
515 although ineffective if not configured as
517 If a NTP packet arrives
518 including a message authentication
519 code (MAC), it is accepted only if it
520 passes all cryptographic checks.
522 checks require correct key ID, key value
525 been modified in any way or replayed
526 by an intruder, it will fail one or more
527 of these checks and be discarded.
528 Furthermore, the Autokey scheme requires a
529 preliminary protocol exchange to obtain
530 the server certificate, verify its
531 credentials and initialize the protocol
535 flag controls whether new associations or
536 remote configuration commands require cryptographic authentication.
537 This flag can be set or reset by the
541 commands and also by remote
542 configuration commands sent by a
546 If this flag is enabled, which is the default
547 case, new broadcast client and symmetric passive associations and
548 remote configuration commands must be cryptographically
549 authenticated using either symmetric key or public key cryptography.
551 flag is disabled, these operations are effective
552 even if not cryptographic
554 It should be understood
555 that operating with the
557 flag disabled invites a significant vulnerability
558 where a rogue hacker can
559 masquerade as a falseticker and seriously
560 disrupt system timekeeping.
562 important to note that this flag has no purpose
563 other than to allow or disallow
564 a new association in response to new broadcast
565 and symmetric active messages
566 and remote configuration commands and, in particular,
567 the flag has no effect on
568 the authentication process itself.
570 An attractive alternative where multicast support is available
571 is manycast mode, in which clients periodically troll
572 for servers as described in the
573 .Sx Automatic NTP Configuration Options
575 Either symmetric key or public key
576 cryptographic authentication can be used in this mode.
577 The principle advantage
578 of manycast mode is that potential servers need not be
579 configured in advance,
580 since the client finds them during regular operation,
581 and the configuration
582 files for all clients can be identical.
584 The security model and protocol schemes for
585 both symmetric key and public key
586 cryptography are summarized below;
587 further details are in the briefings, papers
588 and reports at the NTP project page linked from
589 .Li http://www.ntp.org/ .
590 .Ss Symmetric\-Key Cryptography
591 The original RFC\-1305 specification allows any one of possibly
592 65,535 keys, each distinguished by a 32\-bit key identifier, to
593 authenticate an association.
594 The servers and clients involved must
595 agree on the key and key identifier to
596 authenticate NTP packets.
598 related information are specified in a key
601 which must be distributed and stored using
602 secure means beyond the scope of the NTP protocol itself.
603 Besides the keys used
604 for ordinary NTP associations,
605 additional keys can be used as passwords for the
613 is first started, it reads the key file specified in the
615 configuration command and installs the keys
618 individual keys must be activated with the
622 allows, for instance, the installation of possibly
623 several batches of keys and
624 then activating or deactivating each batch
626 .Xr ntpdc @NTPDC_MS@ .
627 This also provides a revocation capability that can be used
628 if a key becomes compromised.
631 command selects the key used as the password for the
635 command selects the key used as the password for the
638 .Ss Public Key Cryptography
639 NTPv4 supports the original NTPv3 symmetric key scheme
640 described in RFC\-1305 and in addition the Autokey protocol,
641 which is based on public key cryptography.
642 The Autokey Version 2 protocol described on the Autokey Protocol
643 page verifies packet integrity using MD5 message digests
644 and verifies the source with digital signatures and any of several
645 digest/signature schemes.
646 Optional identity schemes described on the Identity Schemes
647 page and based on cryptographic challenge/response algorithms
649 Using all of these schemes provides strong security against
650 replay with or without modification, spoofing, masquerade
651 and most forms of clogging attacks.
653 .\" The cryptographic means necessary for all Autokey operations
654 .\" is provided by the OpenSSL software library.
655 .\" This library is available from http://www.openssl.org/
656 .\" and can be installed using the procedures outlined
657 .\" in the Building and Installing the Distribution page.
659 .\" the configure and build
660 .\" process automatically detects the library and links
661 .\" the library routines required.
663 The Autokey protocol has several modes of operation
664 corresponding to the various NTP modes supported.
665 Most modes use a special cookie which can be
666 computed independently by the client and server,
667 but encrypted in transmission.
668 All modes use in addition a variant of the S\-KEY scheme,
669 in which a pseudo\-random key list is generated and used
671 These schemes are described along with an executive summary,
672 current status, briefing slides and reading list on the
673 .Sx Autonomous Authentication
676 The specific cryptographic environment used by Autokey servers
677 and clients is determined by a set of files
678 and soft links generated by the
679 .Xr ntp\-keygen 1ntpkeygenmdoc
681 This includes a required host key file,
682 required certificate file and optional sign key file,
683 leapsecond file and identity scheme files.
685 digest/signature scheme is specified in the X.509 certificate
686 along with the matching sign key.
687 There are several schemes
688 available in the OpenSSL software library, each identified
689 by a specific string such as
690 .Cm md5WithRSAEncryption ,
691 which stands for the MD5 message digest with RSA
693 The current NTP distribution supports
694 all the schemes in the OpenSSL library, including
695 those based on RSA and DSA digital signatures.
697 NTP secure groups can be used to define cryptographic compartments
698 and security hierarchies.
699 It is important that every host
700 in the group be able to construct a certificate trail to one
701 or more trusted hosts in the same group.
703 host runs the Autokey protocol to obtain the certificates
704 for all hosts along the trail to one or more trusted hosts.
705 This requires the configuration file in all hosts to be
706 engineered so that, even under anticipated failure conditions,
707 the NTP subnet will form such that every group host can find
708 a trail to at least one trusted host.
709 .Ss Naming and Addressing
710 It is important to note that Autokey does not use DNS to
711 resolve addresses, since DNS can't be completely trusted
712 until the name servers have synchronized clocks.
713 The cryptographic name used by Autokey to bind the host identity
714 credentials and cryptographic values must be independent
715 of interface, network and any other naming convention.
716 The name appears in the host certificate in either or both
717 the subject and issuer fields, so protection against
718 DNS compromise is essential.
720 By convention, the name of an Autokey host is the name returned
723 system call or equivalent in other systems.
725 model, there are no provisions to allow alternate names or aliases.
726 However, this is not to say that DNS aliases, different names
727 for each interface, etc., are constrained in any way.
729 It is also important to note that Autokey verifies authenticity
730 using the host name, network address and public keys,
731 all of which are bound together by the protocol specifically
732 to deflect masquerade attacks.
733 For this reason Autokey
734 includes the source and destination IP addresses in message digest
735 computations and so the same addresses must be available
736 at both the server and client.
737 For this reason operation
738 with network address translation schemes is not possible.
739 This reflects the intended robust security model where government
740 and corporate NTP servers are operated outside firewall perimeters.
742 A specific combination of authentication scheme (none,
743 symmetric key, public key) and identity scheme is called
744 a cryptotype, although not all combinations are compatible.
745 There may be management configurations where the clients,
746 servers and peers may not all support the same cryptotypes.
747 A secure NTPv4 subnet can be configured in many ways while
748 keeping in mind the principles explained above and
750 Note however that some cryptotype
751 combinations may successfully interoperate with each other,
752 but may not represent good security practice.
754 The cryptotype of an association is determined at the time
755 of mobilization, either at configuration time or some time
756 later when a message of appropriate cryptotype arrives.
761 configuration command and no
765 subcommands are present, the association is not
766 authenticated; if the
768 subcommand is present, the association is authenticated
769 using the symmetric key ID specified; if the
771 subcommand is present, the association is authenticated
774 When multiple identity schemes are supported in the Autokey
775 protocol, the first message exchange determines which one is used.
776 The client request message contains bits corresponding
777 to which schemes it has available.
778 The server response message
779 contains bits corresponding to which schemes it has available.
780 Both server and client match the received bits with their own
781 and select a common scheme.
783 Following the principle that time is a public value,
784 a server responds to any client packet that matches
785 its cryptotype capabilities.
786 Thus, a server receiving
787 an unauthenticated packet will respond with an unauthenticated
788 packet, while the same server receiving a packet of a cryptotype
789 it supports will respond with packets of that cryptotype.
790 However, unconfigured broadcast or manycast client
791 associations or symmetric passive associations will not be
792 mobilized unless the server supports a cryptotype compatible
793 with the first packet received.
794 By default, unauthenticated associations will not be mobilized
795 unless overridden in a decidedly dangerous way.
797 Some examples may help to reduce confusion.
798 Client Alice has no specific cryptotype selected.
799 Server Bob has both a symmetric key file and minimal Autokey files.
800 Alice's unauthenticated messages arrive at Bob, who replies with
801 unauthenticated messages.
802 Cathy has a copy of Bob's symmetric
803 key file and has selected key ID 4 in messages to Bob.
804 Bob verifies the message with his key ID 4.
806 same key and the message is verified, Bob sends Cathy a reply
807 authenticated with that key.
808 If verification fails,
809 Bob sends Cathy a thing called a crypto\-NAK, which tells her
811 She can see the evidence using the
815 Denise has rolled her own host key and certificate.
816 She also uses one of the identity schemes as Bob.
817 She sends the first Autokey message to Bob and they
818 both dance the protocol authentication and identity steps.
819 If all comes out okay, Denise and Bob continue as described above.
821 It should be clear from the above that Bob can support
822 all the girls at the same time, as long as he has compatible
823 authentication and identity credentials.
824 Now, Bob can act just like the girls in his own choice of servers;
825 he can run multiple configured associations with multiple different
826 servers (or the same server, although that might not be useful).
827 But, wise security policy might preclude some cryptotype
828 combinations; for instance, running an identity scheme
829 with one server and no authentication with another might not be wise.
831 The cryptographic values used by the Autokey protocol are
832 incorporated as a set of files generated by the
833 .Xr ntp\-keygen 1ntpkeygenmdoc
834 utility program, including symmetric key, host key and
835 public certificate files, as well as sign key, identity parameters
836 and leapseconds files.
837 Alternatively, host and sign keys and
838 certificate files can be generated by the OpenSSL utilities
839 and certificates can be imported from public certificate
841 Note that symmetric keys are necessary for the
846 The remaining files are necessary only for the
849 Certificates imported from OpenSSL or public certificate
850 authorities have certian limitations.
851 The certificate should be in ASN.1 syntax, X.509 Version 3
852 format and encoded in PEM, which is the same format
854 The overall length of the certificate encoded
855 in ASN.1 must not exceed 1024 bytes.
856 The subject distinguished
857 name field (CN) is the fully qualified name of the host
858 on which it is used; the remaining subject fields are ignored.
859 The certificate extension fields must not contain either
860 a subject key identifier or a issuer key identifier field;
861 however, an extended key usage field for a trusted host must
864 Other extension fields are ignored.
865 .Ss Authentication Commands
866 .Bl -tag -width indent
867 .It Ic autokey Op Ar logsec
868 Specifies the interval between regenerations of the session key
869 list used with the Autokey protocol.
870 Note that the size of the key
871 list for each association depends on this interval and the current
873 The default value is 12 (4096 s or about 1.1 hours).
874 For poll intervals above the specified interval, a session key list
875 with a single entry will be regenerated for every message
877 .It Ic controlkey Ar key
878 Specifies the key identifier to use with the
880 utility, which uses the standard
881 protocol defined in RFC\-1305.
885 the key identifier for a trusted key, where the value can be in the
886 range 1 to 65,535, inclusive.
890 .Op Cm randfile Ar file
895 .Op Cm iffpar Ar file
897 .Op Cm pw Ar password
899 This command requires the OpenSSL library.
900 It activates public key
901 cryptography, selects the message digest and signature
902 encryption scheme and loads the required private and public
903 values described above.
904 If one or more files are left unspecified,
905 the default names are used as described above.
906 Unless the complete path and name of the file are specified, the
907 location of a file is relative to the keys directory specified
912 Following are the subcommands:
913 .Bl -tag -width indent
915 Specifies the location of the required host public certificate file.
916 This overrides the link
917 .Pa ntpkey_cert_ Ns Ar hostname
918 in the keys directory.
920 Specifies the location of the optional GQ parameters file.
923 .Pa ntpkey_gq_ Ns Ar hostname
924 in the keys directory.
926 Specifies the location of the required host key file.
929 .Pa ntpkey_key_ Ns Ar hostname
930 in the keys directory.
931 .It Cm iffpar Ar file
932 Specifies the location of the optional IFF parameters file.
933 This overrides the link
934 .Pa ntpkey_iff_ Ns Ar hostname
935 in the keys directory.
937 Specifies the location of the optional leapsecond file.
938 This overrides the link
940 in the keys directory.
942 Specifies the location of the optional MV parameters file.
943 This overrides the link
944 .Pa ntpkey_mv_ Ns Ar hostname
945 in the keys directory.
946 .It Cm pw Ar password
947 Specifies the password to decrypt files containing private keys and
949 This is required only if these files have been
951 .It Cm randfile Ar file
952 Specifies the location of the random seed file used by the OpenSSL
954 The defaults are described in the main text above.
956 Specifies the location of the optional sign key file.
959 .Pa ntpkey_sign_ Ns Ar hostname
960 in the keys directory.
962 not found, the host key is also the sign key.
964 .It Ic keys Ar keyfile
965 Specifies the complete path and location of the MD5 key file
966 containing the keys and key identifiers used by
971 when operating with symmetric key cryptography.
972 This is the same operation as the
975 .It Ic keysdir Ar path
976 This command specifies the default directory path for
977 cryptographic keys, parameters and certificates.
979 .Pa /usr/local/etc/ .
980 .It Ic requestkey Ar key
981 Specifies the key identifier to use with the
983 utility program, which uses a
984 proprietary protocol specific to this implementation of
988 argument is a key identifier
989 for the trusted key, where the value can be in the range 1 to
991 .It Ic revoke Ar logsec
992 Specifies the interval between re\-randomization of certain
993 cryptographic values used by the Autokey scheme, as a power of 2 in
995 These values need to be updated frequently in order to
996 deflect brute\-force attacks on the algorithms of the scheme;
997 however, updating some values is a relatively expensive operation.
998 The default interval is 16 (65,536 s or about 18 hours).
1000 intervals above the specified interval, the values will be updated
1001 for every message sent.
1002 .It Ic trustedkey Ar key ...
1003 Specifies the key identifiers which are trusted for the
1004 purposes of authenticating peers with symmetric key cryptography,
1005 as well as keys used by the
1008 .Xr ntpdc @NTPDC_MS@
1010 The authentication procedures require that both the local
1011 and remote servers share the same key and key identifier for this
1012 purpose, although different keys can be used with different
1016 arguments are 32\-bit unsigned
1017 integers with values from 1 to 65,535.
1020 The following error codes are reported via the NTP control
1021 and monitoring protocol trap mechanism.
1022 .Bl -tag -width indent
1024 .Pq bad field format or length
1025 The packet has invalid version, length or format.
1028 The packet timestamp is the same or older than the most recent received.
1029 This could be due to a replay or a server clock time step.
1032 The packet filestamp is the same or older than the most recent received.
1033 This could be due to a replay or a key file generation error.
1035 .Pq bad or missing public key
1036 The public key is missing, has incorrect format or is an unsupported type.
1038 .Pq unsupported digest type
1039 The server requires an unsupported digest/signature scheme.
1041 .Pq mismatched digest types
1044 .Pq bad signature length
1045 The signature length does not match the current public key.
1047 .Pq signature not verified
1048 The message fails the signature check.
1049 It could be bogus or signed by a
1050 different private key.
1052 .Pq certificate not verified
1053 The certificate is invalid or signed with the wrong key.
1055 .Pq certificate not verified
1056 The certificate is not yet valid or has expired or the signature could not
1059 .Pq bad or missing cookie
1060 The cookie is missing, corrupted or bogus.
1062 .Pq bad or missing leapseconds table
1063 The leapseconds table is missing, corrupted or bogus.
1065 .Pq bad or missing certificate
1066 The certificate is missing, corrupted or bogus.
1068 .Pq bad or missing identity
1069 The identity key is missing, corrupt or bogus.
1071 .Sh Monitoring Support
1073 includes a comprehensive monitoring facility suitable
1074 for continuous, long term recording of server and client
1075 timekeeping performance.
1079 for a listing and example of each type of statistics currently
1081 Statistic files are managed using file generation sets
1084 directory of the source code distribution.
1086 these facilities and
1089 jobs, the data can be
1090 automatically summarized and archived for retrospective analysis.
1091 .Ss Monitoring Commands
1092 .Bl -tag -width indent
1093 .It Ic statistics Ar name ...
1094 Enables writing of statistics records.
1095 Currently, eight kinds of
1097 statistics are supported.
1098 .Bl -tag -width indent
1100 Enables recording of clock driver statistics information.
1102 received from a clock driver appends a line of the following form to
1103 the file generation set named
1106 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1109 The first two fields show the date (Modified Julian Day) and time
1110 (seconds and fraction past UTC midnight).
1111 The next field shows the
1112 clock address in dotted\-quad notation.
1113 The final field shows the last
1114 timecode received from the clock in decoded ASCII format, where
1116 In some clock drivers a good deal of additional information
1117 can be gathered and displayed as well.
1118 See information specific to each
1119 clock for further details.
1121 This option requires the OpenSSL cryptographic software library.
1123 enables recording of cryptographic public key protocol information.
1124 Each message received by the protocol module appends a line of the
1125 following form to the file generation set named
1128 49213 525.624 127.127.4.1 message
1131 The first two fields show the date (Modified Julian Day) and time
1132 (seconds and fraction past UTC midnight).
1133 The next field shows the peer
1134 address in dotted\-quad notation, The final message field includes the
1135 message type and certain ancillary information.
1137 .Sx Authentication Options
1138 section for further information.
1140 Enables recording of loop filter statistics information.
1142 update of the local clock outputs a line of the following form to
1143 the file generation set named
1146 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1149 The first two fields show the date (Modified Julian Day) and
1150 time (seconds and fraction past UTC midnight).
1151 The next five fields
1152 show time offset (seconds), frequency offset (parts per million \-
1153 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1154 discipline time constant.
1156 Enables recording of peer statistics information.
1158 statistics records of all peers of a NTP server and of special
1159 signals, where present and configured.
1160 Each valid update appends a
1161 line of the following form to the current element of a file
1162 generation set named
1165 48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674
1168 The first two fields show the date (Modified Julian Day) and
1169 time (seconds and fraction past UTC midnight).
1171 show the peer address in dotted\-quad notation and status,
1173 The status field is encoded in hex in the format
1174 described in Appendix A of the NTP specification RFC 1305.
1175 The final four fields show the offset,
1176 delay, dispersion and RMS jitter, all in seconds.
1178 Enables recording of raw\-timestamp statistics information.
1180 includes statistics records of all peers of a NTP server and of
1181 special signals, where present and configured.
1183 received from a peer or clock driver appends a line of the
1184 following form to the file generation set named
1187 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1190 The first two fields show the date (Modified Julian Day) and
1191 time (seconds and fraction past UTC midnight).
1193 show the remote peer or clock address followed by the local address
1194 in dotted\-quad notation.
1195 The final four fields show the originate,
1196 receive, transmit and final NTP timestamps in order.
1198 values are as received and before processing by the various data
1199 smoothing and mitigation algorithms.
1201 Enables recording of ntpd statistics counters on a periodic basis.
1203 hour a line of the following form is appended to the file generation
1207 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1210 The first two fields show the date (Modified Julian Day) and time
1211 (seconds and fraction past UTC midnight).
1212 The remaining ten fields show
1213 the statistics counter values accumulated since the last generated
1215 .Bl -tag -width indent
1216 .It Time since restart Cm 36000
1217 Time in hours since the system was last rebooted.
1218 .It Packets received Cm 81965
1219 Total number of packets received.
1220 .It Packets processed Cm 0
1221 Number of packets received in response to previous packets sent
1222 .It Current version Cm 9546
1223 Number of packets matching the current NTP version.
1224 .It Previous version Cm 56
1225 Number of packets matching the previous NTP version.
1226 .It Bad version Cm 71793
1227 Number of packets matching neither NTP version.
1228 .It Access denied Cm 512
1229 Number of packets denied access for any reason.
1230 .It Bad length or format Cm 540
1231 Number of packets with invalid length, format or port number.
1232 .It Bad authentication Cm 10
1233 Number of packets not verified as authentic.
1234 .It Rate exceeded Cm 147
1235 Number of packets discarded due to rate limitation.
1237 .It Cm statsdir Ar directory_path
1238 Indicates the full path of a directory where statistics files
1239 should be created (see below).
1241 the (otherwise constant)
1243 filename prefix to be modified for file generation sets, which
1244 is useful for handling statistics logs.
1245 .It Cm filegen Ar name Xo
1246 .Op Cm file Ar filename
1247 .Op Cm type Ar typename
1248 .Op Cm link | nolink
1249 .Op Cm enable | disable
1251 Configures setting of generation file set name.
1253 file sets provide a means for handling files that are
1254 continuously growing during the lifetime of a server.
1255 Server statistics are a typical example for such files.
1256 Generation file sets provide access to a set of files used
1257 to store the actual data.
1258 At any time at most one element
1259 of the set is being written to.
1260 The type given specifies
1261 when and how data will be directed to a new element of the set.
1262 This way, information stored in elements of a file set
1263 that are currently unused are available for administrational
1264 operations without the risk of disturbing the operation of ntpd.
1265 (Most important: they can be removed to free space for new data
1268 Note that this command can be sent from the
1269 .Xr ntpdc @NTPDC_MS@
1270 program running at a remote location.
1271 .Bl -tag -width indent
1273 This is the type of the statistics records, as shown in the
1276 .It Cm file Ar filename
1277 This is the file name for the statistics records.
1279 members are built from three concatenated elements
1284 .Bl -tag -width indent
1286 This is a constant filename path.
1287 It is not subject to
1288 modifications via the
1291 It is defined by the
1292 server, usually specified as a compile\-time constant.
1294 however, be configurable for individual file generation sets
1296 For example, the prefix used with
1300 generation can be configured using the
1302 option explained above.
1304 This string is directly concatenated to the prefix mentioned
1305 above (no intervening
1307 This can be modified using
1308 the file argument to the
1314 allowed in this component to prevent filenames referring to
1315 parts outside the filesystem hierarchy denoted by
1318 This part is reflects individual elements of a file set.
1320 generated according to the type of a file set.
1322 .It Cm type Ar typename
1323 A file generation set is characterized by its type.
1325 types are supported:
1326 .Bl -tag -width indent
1328 The file set is actually a single plain file.
1330 One element of file set is used per incarnation of a ntpd
1332 This type does not perform any changes to file set
1333 members during runtime, however it provides an easy way of
1334 separating files belonging to different
1336 server incarnations.
1337 The set member filename is built by appending a
1344 appending the decimal representation of the process ID of the
1348 One file generation set element is created per day.
1350 defined as the period between 00:00 and 24:00 UTC.
1352 member suffix consists of a
1354 and a day specification in
1358 is a 4\-digit year number (e.g., 1992).
1360 is a two digit month number.
1362 is a two digit day number.
1363 Thus, all information written at 10 December 1992 would end up
1366 .Ar filename Ns .19921210 .
1368 Any file set member contains data related to a certain week of
1370 The term week is defined by computing day\-of\-year
1372 Elements of such a file generation set are
1373 distinguished by appending the following suffix to the file set
1374 filename base: A dot, a 4\-digit year number, the letter
1376 and a 2\-digit week number.
1377 For example, information from January,
1378 10th 1992 would end up in a file with suffix
1379 .No . Ns Ar 1992W1 .
1381 One generation file set element is generated per month.
1383 file name suffix consists of a dot, a 4\-digit year number, and
1386 One generation file element is generated per year.
1388 suffix consists of a dot and a 4 digit year number.
1390 This type of file generation sets changes to a new element of
1391 the file set every 24 hours of server operation.
1393 suffix consists of a dot, the letter
1395 and an 8\-digit number.
1396 This number is taken to be the number of seconds the server is
1397 running at the start of the corresponding 24\-hour period.
1398 Information is only written to a file generation by specifying
1400 output is prevented by specifying
1403 .It Cm link | nolink
1404 It is convenient to be able to access the current element of a file
1405 generation set by a fixed name.
1406 This feature is enabled by
1411 If link is specified, a
1412 hard link from the current file set element to a file without
1414 When there is already a file with this name and
1415 the number of links of this file is one, it is renamed appending a
1422 number of links is greater than one, the file is unlinked.
1424 allows the current file to be accessed by a constant name.
1425 .It Cm enable \&| Cm disable
1426 Enables or disables the recording function.
1430 .Sh Access Control Support
1433 daemon implements a general purpose address/mask based restriction
1435 The list contains address/match entries sorted first
1436 by increasing address values and and then by increasing mask values.
1437 A match occurs when the bitwise AND of the mask and the packet
1438 source address is equal to the bitwise AND of the mask and
1439 address in the list.
1440 The list is searched in order with the
1441 last match found defining the restriction flags associated
1443 Additional information and examples can be found in the
1444 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
1446 (available as part of the HTML documentation
1448 .Pa /usr/share/doc/ntp ) .
1450 The restriction facility was implemented in conformance
1451 with the access policies for the original NSFnet backbone
1453 Later the facility was expanded to deflect
1454 cryptographic and clogging attacks.
1455 While this facility may
1456 be useful for keeping unwanted or broken or malicious clients
1457 from congesting innocent servers, it should not be considered
1458 an alternative to the NTP authentication facilities.
1459 Source address based restrictions are easily circumvented
1460 by a determined cracker.
1462 Clients can be denied service because they are explicitly
1463 included in the restrict list created by the
1466 or implicitly as the result of cryptographic or rate limit
1468 Cryptographic violations include certificate
1469 or identity verification failure; rate limit violations generally
1470 result from defective NTP implementations that send packets
1472 Some violations cause denied service
1473 only for the offending packet, others cause denied service
1474 for a timed period and others cause the denied service for
1475 an indefinite period.
1476 When a client or network is denied access
1477 for an indefinite period, the only way at present to remove
1478 the restrictions is by restarting the server.
1479 .Ss The Kiss\-of\-Death Packet
1480 Ordinarily, packets denied service are simply dropped with no
1481 further action except incrementing statistics counters.
1483 more proactive response is needed, such as a server message that
1484 explicitly requests the client to stop sending and leave a message
1485 for the system operator.
1486 A special packet format has been created
1487 for this purpose called the "kiss\-of\-death" (KoD) packet.
1488 KoD packets have the leap bits set unsynchronized and stratum set
1489 to zero and the reference identifier field set to a four\-byte
1495 flag of the matching restrict list entry is set,
1496 the code is "DENY"; if the
1498 flag is set and the rate limit
1499 is exceeded, the code is "RATE".
1500 Finally, if a cryptographic violation occurs, the code is "CRYP".
1502 A client receiving a KoD performs a set of sanity checks to
1503 minimize security exposure, then updates the stratum and
1504 reference identifier peer variables, sets the access
1505 denied (TEST4) bit in the peer flash variable and sends
1506 a message to the log.
1507 As long as the TEST4 bit is set,
1508 the client will send no further packets to the server.
1509 The only way at present to recover from this condition is
1510 to restart the protocol at both the client and server.
1512 happens automatically at the client when the association times out.
1513 It will happen at the server only if the server operator cooperates.
1514 .Ss Access Control Commands
1515 .Bl -tag -width indent
1517 .Op Cm average Ar avg
1518 .Op Cm minimum Ar min
1519 .Op Cm monitor Ar prob
1521 Set the parameters of the
1523 facility which protects the server from
1527 subcommand specifies the minimum average packet
1530 subcommand specifies the minimum packet spacing.
1531 Packets that violate these minima are discarded
1532 and a kiss\-o'\-death packet returned if enabled.
1534 minimum average and minimum are 5 and 2, respectively.
1537 subcommand specifies the probability of discard
1538 for packets that overflow the rate\-control window.
1539 .It Xo Ic restrict address
1541 .Op Cm ippeerlimit Ar int
1546 argument expressed in
1547 dotted\-quad form is the address of a host or network.
1550 argument can be a valid host DNS name.
1553 argument expressed in dotted\-quad form defaults to
1554 .Cm 255.255.255.255 ,
1557 is treated as the address of an individual host.
1558 A default entry (address
1562 is always included and is always the first entry in the list.
1563 Note that text string
1565 with no mask option, may
1566 be used to indicate the default entry.
1569 directive limits the number of peer requests for each IP to
1571 where a value of \-1 means "unlimited", the current default.
1572 A value of 0 means "none".
1573 There would usually be at most 1 peering request per IP,
1574 but if the remote peering requests are behind a proxy
1575 there could well be more than 1 per IP.
1576 In the current implementation,
1579 restricts access, i.e., an entry with no flags indicates that free
1580 access to the server is to be given.
1581 The flags are not orthogonal,
1582 in that more restrictive flags will often make less restrictive
1584 The flags can generally be classed into two
1585 categories, those which restrict time service and those which
1586 restrict informational queries and attempts to do run\-time
1587 reconfiguration of the server.
1588 One or more of the following flags
1590 .Bl -tag -width indent
1592 Deny packets of all kinds, including
1595 .Xr ntpdc @NTPDC_MS@
1598 If this flag is set when an access violation occurs, a kiss\-o'\-death
1599 (KoD) packet is sent.
1600 KoD packets are rate limited to no more than one
1602 If another KoD packet occurs within one second after the
1603 last one, the packet is dropped.
1605 Deny service if the packet spacing violates the lower limits specified
1609 A history of clients is kept using the
1610 monitoring capability of
1611 .Xr ntpd @NTPD_MS@ .
1612 Thus, monitoring is always active as
1613 long as there is a restriction entry with the
1617 Declare traps set by matching hosts to be low priority.
1619 number of traps a server can maintain is limited (the current limit
1621 Traps are usually assigned on a first come, first served
1622 basis, with later trap requestors being denied service.
1624 modifies the assignment algorithm by allowing low priority traps to
1625 be overridden by later requests for normal priority traps.
1627 Deny ephemeral peer requests,
1628 even if they come from an authenticated source.
1629 Note that the ability to use a symmetric key for authentication may be restricted to
1630 one or more IPs or subnets via the third field of the
1633 This restriction is not enabled by default,
1634 to maintain backward compatability.
1637 to become the default in ntp\-4.4.
1642 .Xr ntpdc @NTPDC_MS@
1643 queries which attempt to modify the state of the
1644 server (i.e., run time reconfiguration).
1645 Queries which return
1646 information are permitted.
1651 .Xr ntpdc @NTPDC_MS@
1653 Time service is not affected.
1655 Deny unauthenticated packets which would result in mobilizing a new association.
1657 broadcast and symmetric active packets
1658 when a configured association does not exist.
1661 associations, so if you want to use servers from a
1663 directive and also want to use
1665 by default, you'll want a
1666 .Cm "restrict source ..."
1667 line as well that does
1673 Deny all packets except
1676 .Xr ntpdc @NTPDC_MS@
1679 Decline to provide mode 6 control message trap service to matching
1681 The trap service is a subsystem of the
1684 protocol which is intended for use by remote event logging programs.
1686 Deny service unless the packet is cryptographically authenticated.
1688 This is actually a match algorithm modifier, rather than a
1690 Its presence causes the restriction entry to be
1691 matched only if the source port in the packet is the standard NTP
1701 is considered more specific and
1702 is sorted later in the list.
1703 .It Ic "serverresponse fuzz"
1704 When reponding to server requests,
1705 fuzz the low order bits of the
1708 Deny packets that do not match the current NTP version.
1711 Default restriction list entries with the flags ignore, interface,
1712 ntpport, for each of the local host's interface addresses are
1713 inserted into the table at startup to prevent the server
1714 from attempting to synchronize to its own time.
1715 A default entry is also always present, though if it is
1716 otherwise unconfigured; no flags are associated
1717 with the default entry (i.e., everything besides your own
1718 NTP server is unrestricted).
1720 .Sh Automatic NTP Configuration Options
1722 Manycasting is a automatic discovery and configuration paradigm
1724 It is intended as a means for a multicast client
1725 to troll the nearby network neighborhood to find cooperating
1726 manycast servers, validate them using cryptographic means
1727 and evaluate their time values with respect to other servers
1728 that might be lurking in the vicinity.
1729 The intended result is that each manycast client mobilizes
1730 client associations with some number of the "best"
1731 of the nearby manycast servers, yet automatically reconfigures
1732 to sustain this number of servers should one or another fail.
1734 Note that the manycasting paradigm does not coincide
1735 with the anycast paradigm described in RFC\-1546,
1736 which is designed to find a single server from a clique
1737 of servers providing the same service.
1738 The manycast paradigm is designed to find a plurality
1739 of redundant servers satisfying defined optimality criteria.
1741 Manycasting can be used with either symmetric key
1742 or public key cryptography.
1743 The public key infrastructure (PKI)
1744 offers the best protection against compromised keys
1745 and is generally considered stronger, at least with relatively
1747 It is implemented using the Autokey protocol and
1748 the OpenSSL cryptographic library available from
1749 .Li http://www.openssl.org/ .
1750 The library can also be used with other NTPv4 modes
1751 as well and is highly recommended, especially for broadcast modes.
1753 A persistent manycast client association is configured
1756 command, which is similar to the
1758 command but with a multicast (IPv4 class
1763 The IANA has designated IPv4 address 224.1.1.1
1764 and IPv6 address FF05::101 (site local) for NTP.
1765 When more servers are needed, it broadcasts manycast
1766 client messages to this address at the minimum feasible rate
1767 and minimum feasible time\-to\-live (TTL) hops, depending
1768 on how many servers have already been found.
1769 There can be as many manycast client associations
1770 as different group address, each one serving as a template
1771 for a future ephemeral unicast client/server association.
1773 Manycast servers configured with the
1775 command listen on the specified group address for manycast
1777 Note the distinction between manycast client,
1778 which actively broadcasts messages, and manycast server,
1779 which passively responds to them.
1780 If a manycast server is
1781 in scope of the current TTL and is itself synchronized
1782 to a valid source and operating at a stratum level equal
1783 to or lower than the manycast client, it replies to the
1784 manycast client message with an ordinary unicast server message.
1786 The manycast client receiving this message mobilizes
1787 an ephemeral client/server association according to the
1788 matching manycast client template, but only if cryptographically
1789 authenticated and the server stratum is less than or equal
1790 to the client stratum.
1791 Authentication is explicitly required
1792 and either symmetric key or public key (Autokey) can be used.
1793 Then, the client polls the server at its unicast address
1794 in burst mode in order to reliably set the host clock
1795 and validate the source.
1796 This normally results
1797 in a volley of eight client/server at 2\-s intervals
1798 during which both the synchronization and cryptographic
1799 protocols run concurrently.
1800 Following the volley,
1801 the client runs the NTP intersection and clustering
1802 algorithms, which act to discard all but the "best"
1803 associations according to stratum and synchronization
1805 The surviving associations then continue
1806 in ordinary client/server mode.
1808 The manycast client polling strategy is designed to reduce
1809 as much as possible the volume of manycast client messages
1810 and the effects of implosion due to near\-simultaneous
1811 arrival of manycast server messages.
1812 The strategy is determined by the
1813 .Ic manycastclient ,
1817 configuration commands.
1818 The manycast poll interval is
1819 normally eight times the system poll interval,
1820 which starts out at the
1822 value specified in the
1823 .Ic manycastclient ,
1824 command and, under normal circumstances, increments to the
1826 value specified in this command.
1827 Initially, the TTL is
1828 set at the minimum hops specified by the
1831 At each retransmission the TTL is increased until reaching
1832 the maximum hops specified by this command or a sufficient
1833 number client associations have been found.
1834 Further retransmissions use the same TTL.
1836 The quality and reliability of the suite of associations
1837 discovered by the manycast client is determined by the NTP
1838 mitigation algorithms and the
1842 values specified in the
1844 configuration command.
1847 candidate servers must be available and the mitigation
1848 algorithms produce at least
1850 survivors in order to synchronize the clock.
1851 Byzantine agreement principles require at least four
1852 candidates in order to correctly discard a single falseticker.
1853 For legacy purposes,
1858 For manycast service
1860 should be explicitly set to 4, assuming at least that
1861 number of servers are available.
1865 servers are found, the manycast poll interval is immediately
1870 servers are found when the TTL has reached the maximum hops,
1871 the manycast poll interval is doubled.
1872 For each transmission
1873 after that, the poll interval is doubled again until
1874 reaching the maximum of eight times
1876 Further transmissions use the same poll interval and
1878 Note that while all this is going on,
1879 each client/server association found is operating normally
1880 it the system poll interval.
1882 Administratively scoped multicast boundaries are normally
1883 specified by the network router configuration and,
1884 in the case of IPv6, the link/site scope prefix.
1885 By default, the increment for TTL hops is 32 starting
1886 from 31; however, the
1888 configuration command can be
1889 used to modify the values to match the scope rules.
1891 It is often useful to narrow the range of acceptable
1892 servers which can be found by manycast client associations.
1893 Because manycast servers respond only when the client
1894 stratum is equal to or greater than the server stratum,
1895 primary (stratum 1) servers fill find only primary servers
1896 in TTL range, which is probably the most common objective.
1897 However, unless configured otherwise, all manycast clients
1898 in TTL range will eventually find all primary servers
1899 in TTL range, which is probably not the most common
1900 objective in large networks.
1903 command can be used to modify this behavior.
1904 Servers with stratum below
1910 command are strongly discouraged during the selection
1911 process; however, these servers may be temporally
1912 accepted if the number of servers within TTL range is
1916 The above actions occur for each manycast client message,
1917 which repeats at the designated poll interval.
1918 However, once the ephemeral client association is mobilized,
1919 subsequent manycast server replies are discarded,
1920 since that would result in a duplicate association.
1921 If during a poll interval the number of client associations
1924 all manycast client prototype associations are reset
1925 to the initial poll interval and TTL hops and operation
1926 resumes from the beginning.
1927 It is important to avoid
1928 frequent manycast client messages, since each one requires
1929 all manycast servers in TTL range to respond.
1930 The result could well be an implosion, either minor or major,
1931 depending on the number of servers in range.
1932 The recommended value for
1936 It is possible and frequently useful to configure a host
1937 as both manycast client and manycast server.
1938 A number of hosts configured this way and sharing a common
1939 group address will automatically organize themselves
1940 in an optimum configuration based on stratum and
1941 synchronization distance.
1942 For example, consider an NTP
1943 subnet of two primary servers and a hundred or more
1945 With two exceptions, all servers
1946 and clients have identical configuration files including both
1950 commands using, for instance, multicast group address
1952 The only exception is that each primary server
1953 configuration file must include commands for the primary
1954 reference source such as a GPS receiver.
1956 The remaining configuration files for all secondary
1957 servers and clients have the same contents, except for the
1959 command, which is specific for each stratum level.
1960 For stratum 1 and stratum 2 servers, that command is
1962 For stratum 3 and above servers the
1964 value is set to the intended stratum number.
1965 Thus, all stratum 3 configuration files are identical,
1966 all stratum 4 files are identical and so forth.
1968 Once operations have stabilized in this scenario,
1969 the primary servers will find the primary reference source
1970 and each other, since they both operate at the same
1971 stratum (1), but not with any secondary server or client,
1972 since these operate at a higher stratum.
1974 servers will find the servers at the same stratum level.
1975 If one of the primary servers loses its GPS receiver,
1976 it will continue to operate as a client and other clients
1977 will time out the corresponding association and
1978 re\-associate accordingly.
1980 Some administrators prefer to avoid running
1982 continuously and run either
1988 In either case the servers must be
1989 configured in advance and the program fails if none are
1990 available when the cron job runs.
1992 application of manycast is with
1995 The program wakes up, scans the local landscape looking
1996 for the usual suspects, selects the best from among
1997 the rascals, sets the clock and then departs.
1998 Servers do not have to be configured in advance and
1999 all clients throughout the network can have the same
2001 .Ss Manycast Interactions with Autokey
2002 Each time a manycast client sends a client mode packet
2003 to a multicast group address, all manycast servers
2004 in scope generate a reply including the host name
2006 The manycast clients then run
2007 the Autokey protocol, which collects and verifies
2008 all certificates involved.
2009 Following the burst interval
2010 all but three survivors are cast off,
2011 but the certificates remain in the local cache.
2012 It often happens that several complete signing trails
2013 from the client to the primary servers are collected in this way.
2015 About once an hour or less often if the poll interval
2016 exceeds this, the client regenerates the Autokey key list.
2017 This is in general transparent in client/server mode.
2018 However, about once per day the server private value
2019 used to generate cookies is refreshed along with all
2020 manycast client associations.
2022 cryptographic values including certificates is refreshed.
2023 If a new certificate has been generated since
2024 the last refresh epoch, it will automatically revoke
2025 all prior certificates that happen to be in the
2027 At the same time, the manycast
2028 scheme starts all over from the beginning and
2029 the expanding ring shrinks to the minimum and increments
2030 from there while collecting all servers in scope.
2031 .Ss Broadcast Options
2032 .Bl -tag -width indent
2035 .Cm bcpollbstep Ar gate
2038 This command provides a way to delay,
2039 by the specified number of broadcast poll intervals,
2040 believing backward time steps from a broadcast server.
2041 Broadcast time networks are expected to be trusted.
2042 In the event a broadcast server's time is stepped backwards,
2043 there is clear benefit to having the clients notice this change
2044 as soon as possible.
2045 Attacks such as replay attacks can happen, however,
2046 and even though there are a number of protections built in to
2047 broadcast mode, attempts to perform a replay attack are possible.
2048 This value defaults to 0, but can be changed
2049 to any number of poll intervals between 0 and 4.
2051 .Ss Manycast Options
2052 .Bl -tag -width indent
2055 .Cm ceiling Ar ceiling |
2056 .Cm cohort { 0 | 1 } |
2057 .Cm floor Ar floor |
2058 .Cm minclock Ar minclock |
2059 .Cm minsane Ar minsane
2062 This command affects the clock selection and clustering
2064 It can be used to select the quality and
2065 quantity of peers used to synchronize the system clock
2066 and is most useful in manycast mode.
2067 The variables operate
2069 .Bl -tag -width indent
2070 .It Cm ceiling Ar ceiling
2071 Peers with strata above
2073 will be discarded if there are at least
2076 This value defaults to 15, but can be changed
2077 to any number from 1 to 15.
2078 .It Cm cohort Bro 0 | 1 Brc
2079 This is a binary flag which enables (0) or disables (1)
2080 manycast server replies to manycast clients with the same
2082 This is useful to reduce implosions where
2083 large numbers of clients with the same stratum level
2085 The default is to enable these replies.
2086 .It Cm floor Ar floor
2087 Peers with strata below
2089 will be discarded if there are at least
2092 This value defaults to 1, but can be changed
2093 to any number from 1 to 15.
2094 .It Cm minclock Ar minclock
2095 The clustering algorithm repeatedly casts out outlier
2096 associations until no more than
2098 associations remain.
2099 This value defaults to 3,
2100 but can be changed to any number from 1 to the number of
2102 .It Cm minsane Ar minsane
2103 This is the minimum number of candidates available
2104 to the clock selection algorithm in order to produce
2105 one or more truechimers for the clustering algorithm.
2106 If fewer than this number are available, the clock is
2107 undisciplined and allowed to run free.
2109 for legacy purposes.
2110 However, according to principles of
2111 Byzantine agreement,
2113 should be at least 4 in order to detect and discard
2114 a single falseticker.
2116 .It Cm ttl Ar hop ...
2117 This command specifies a list of TTL values in increasing
2118 order, up to 8 values can be specified.
2119 In manycast mode these values are used in turn
2120 in an expanding\-ring search.
2121 The default is eight
2122 multiples of 32 starting at 31.
2124 .Sh Reference Clock Support
2125 The NTP Version 4 daemon supports some three dozen different radio,
2126 satellite and modem reference clocks plus a special pseudo\-clock
2127 used for backup or when no other clock source is available.
2128 Detailed descriptions of individual device drivers and options can
2130 .Qq Reference Clock Drivers
2132 (available as part of the HTML documentation
2134 .Pa /usr/share/doc/ntp ) .
2135 Additional information can be found in the pages linked
2136 there, including the
2137 .Qq Debugging Hints for Reference Clock Drivers
2139 .Qq How To Write a Reference Clock Driver
2141 (available as part of the HTML documentation
2143 .Pa /usr/share/doc/ntp ) .
2144 In addition, support for a PPS
2145 signal is available as described in the
2146 .Qq Pulse\-per\-second (PPS) Signal Interfacing
2148 (available as part of the HTML documentation
2150 .Pa /usr/share/doc/ntp ) .
2152 drivers support special line discipline/streams modules which can
2153 significantly improve the accuracy using the driver.
2156 .Qq Line Disciplines and Streams Drivers
2158 (available as part of the HTML documentation
2160 .Pa /usr/share/doc/ntp ) .
2162 A reference clock will generally (though not always) be a radio
2163 timecode receiver which is synchronized to a source of standard
2164 time such as the services offered by the NRC in Canada and NIST and
2166 The interface between the computer and the timecode
2167 receiver is device dependent, but is usually a serial port.
2169 device driver specific to each reference clock must be selected and
2170 compiled in the distribution; however, most common radio, satellite
2171 and modem clocks are included by default.
2172 Note that an attempt to
2173 configure a reference clock when the driver has not been compiled
2174 or the hardware port has not been appropriately configured results
2175 in a scalding remark to the system log file, but is otherwise non
2178 For the purposes of configuration,
2181 reference clocks in a manner analogous to normal NTP peers as much
2183 Reference clocks are identified by a syntactically
2184 correct but invalid IP address, in order to distinguish them from
2186 Reference clock addresses are of the form
2188 .Li 127.127. Ar t . Ar u ,
2193 denoting the clock type and
2196 number in the range 0\-3.
2197 While it may seem overkill, it is in fact
2198 sometimes useful to configure multiple reference clocks of the same
2199 type, in which case the unit numbers must be unique.
2203 command is used to configure a reference
2206 argument in that command
2207 is the clock address.
2213 options are not used for reference clock support.
2216 option is added for reference clock support, as
2220 option can be useful to
2221 persuade the server to cherish a reference clock with somewhat more
2222 enthusiasm than other reference clocks or peers.
2224 information on this option can be found in the
2225 .Qq Mitigation Rules and the prefer Keyword
2226 (available as part of the HTML documentation
2228 .Pa /usr/share/doc/ntp )
2235 meaning only for selected clock drivers.
2236 See the individual clock
2237 driver document pages for additional information.
2241 command is used to provide additional
2242 information for individual clock drivers and normally follows
2243 immediately after the
2248 argument specifies the clock address.
2253 options can be used to
2254 override the defaults for the device.
2255 There are two optional
2256 device\-dependent time offsets and four flags that can be included
2261 The stratum number of a reference clock is by default zero.
2264 daemon adds one to the stratum of each
2265 peer, a primary server ordinarily displays an external stratum of
2267 In order to provide engineered backups, it is often useful to
2268 specify the reference clock stratum as greater than zero.
2271 option is used for this purpose.
2273 involving both a reference clock and a pulse\-per\-second (PPS)
2274 discipline signal, it is useful to specify the reference clock
2275 identifier as other than the default, depending on the driver.
2278 option is used for this purpose.
2280 these options apply to all clock drivers.
2281 .Ss Reference Clock Commands
2282 .Bl -tag -width indent
2285 .Li 127.127. Ar t . Ar u
2289 .Op Cm minpoll Ar int
2290 .Op Cm maxpoll Ar int
2292 This command can be used to configure reference clocks in
2294 The options are interpreted as follows:
2295 .Bl -tag -width indent
2297 Marks the reference clock as preferred.
2298 All other things being
2299 equal, this host will be chosen for synchronization among a set of
2300 correctly operating hosts.
2302 .Qq Mitigation Rules and the prefer Keyword
2304 (available as part of the HTML documentation
2306 .Pa /usr/share/doc/ntp )
2307 for further information.
2309 Specifies a mode number which is interpreted in a
2310 device\-specific fashion.
2311 For instance, it selects a dialing
2312 protocol in the ACTS driver and a device subtype in the
2315 .It Cm minpoll Ar int
2316 .It Cm maxpoll Ar int
2317 These options specify the minimum and maximum polling interval
2318 for reference clock messages, as a power of 2 in seconds
2320 most directly connected reference clocks, both
2324 default to 6 (64 s).
2325 For modem reference clocks,
2327 defaults to 10 (17.1 m) and
2329 defaults to 14 (4.5 h).
2330 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2334 .Li 127.127. Ar t . Ar u
2338 .Op Cm stratum Ar int
2339 .Op Cm refid Ar string
2341 .Op Cm flag1 Cm 0 \&| Cm 1
2342 .Op Cm flag2 Cm 0 \&| Cm 1
2343 .Op Cm flag3 Cm 0 \&| Cm 1
2344 .Op Cm flag4 Cm 0 \&| Cm 1
2346 This command can be used to configure reference clocks in
2348 It must immediately follow the
2350 command which configures the driver.
2351 Note that the same capability
2352 is possible at run time using the
2353 .Xr ntpdc @NTPDC_MS@
2355 The options are interpreted as
2357 .Bl -tag -width indent
2359 Specifies a constant to be added to the time offset produced by
2360 the driver, a fixed\-point decimal number in seconds.
2362 as a calibration constant to adjust the nominal time offset of a
2363 particular clock to agree with an external standard, such as a
2364 precision PPS signal.
2365 It also provides a way to correct a
2366 systematic error or bias due to serial port or operating system
2367 latencies, different cable lengths or receiver internal delay.
2369 specified offset is in addition to the propagation delay provided
2370 by other means, such as internal DIPswitches.
2372 for an individual system and driver is available, an approximate
2373 correction is noted in the driver documentation pages.
2374 Note: in order to facilitate calibration when more than one
2375 radio clock or PPS signal is supported, a special calibration
2376 feature is available.
2377 It takes the form of an argument to the
2379 command described in
2380 .Sx Miscellaneous Options
2381 page and operates as described in the
2382 .Qq Reference Clock Drivers
2384 (available as part of the HTML documentation
2386 .Pa /usr/share/doc/ntp ) .
2387 .It Cm time2 Ar secs
2388 Specifies a fixed\-point decimal number in seconds, which is
2389 interpreted in a driver\-dependent way.
2390 See the descriptions of
2391 specific drivers in the
2392 .Qq Reference Clock Drivers
2394 (available as part of the HTML documentation
2396 .Pa /usr/share/doc/ntp ).
2397 .It Cm stratum Ar int
2398 Specifies the stratum number assigned to the driver, an integer
2400 This number overrides the default stratum number
2401 ordinarily assigned by the driver itself, usually zero.
2402 .It Cm refid Ar string
2403 Specifies an ASCII string of from one to four characters which
2404 defines the reference identifier used by the driver.
2406 overrides the default identifier ordinarily assigned by the driver
2409 Specifies a mode number which is interpreted in a
2410 device\-specific fashion.
2411 For instance, it selects a dialing
2412 protocol in the ACTS driver and a device subtype in the
2415 .It Cm flag1 Cm 0 \&| Cm 1
2416 .It Cm flag2 Cm 0 \&| Cm 1
2417 .It Cm flag3 Cm 0 \&| Cm 1
2418 .It Cm flag4 Cm 0 \&| Cm 1
2419 These four flags are used for customizing the clock driver.
2421 interpretation of these values, and whether they are used at all,
2422 is a function of the particular clock driver.
2426 is used to enable recording monitoring
2429 file configured with the
2432 Further information on the
2434 command can be found in
2435 .Sx Monitoring Options .
2438 .Sh Miscellaneous Options
2439 .Bl -tag -width indent
2440 .It Ic broadcastdelay Ar seconds
2441 The broadcast and multicast modes require a special calibration
2442 to determine the network delay between the local and remote
2444 Ordinarily, this is done automatically by the initial
2445 protocol exchanges between the client and server.
2447 the calibration procedure may fail due to network or server access
2448 controls, for example.
2449 This command specifies the default delay to
2450 be used under these circumstances.
2451 Typically (for Ethernet), a
2452 number between 0.003 and 0.007 seconds is appropriate.
2454 when this command is not used is 0.004 seconds.
2455 .It Ic calldelay Ar delay
2456 This option controls the delay in seconds between the first and second
2457 packets sent in burst or iburst mode to allow additional time for a modem
2458 or ISDN call to complete.
2459 .It Ic driftfile Ar driftfile
2460 This command specifies the complete path and name of the file used to
2461 record the frequency of the local clock oscillator.
2465 command line option.
2466 If the file exists, it is read at
2467 startup in order to set the initial frequency and then updated once per
2468 hour with the current frequency computed by the daemon.
2470 specified, but the file itself does not exist, the starts with an initial
2471 frequency of zero and creates the file when writing it for the first time.
2472 If this command is not given, the daemon will always start with an initial
2475 The file format consists of a single line containing a single
2476 floating point number, which records the frequency offset measured
2477 in parts\-per\-million (PPM).
2478 The file is updated by first writing
2479 the current drift value into a temporary file and then renaming
2480 this file to replace the old version.
2483 must have write permission for the directory the
2484 drift file is located in, and that file system links, symbolic or
2485 otherwise, should be avoided.
2486 .It Ic dscp Ar value
2487 This option specifies the Differentiated Services Control Point (DSCP) value,
2489 The default value is 46, signifying Expedited Forwarding.
2492 .Cm auth | Cm bclient |
2493 .Cm calibrate | Cm kernel |
2494 .Cm mode7 | Cm monitor |
2495 .Cm ntp | Cm stats |
2496 .Cm peer_clear_digest_early |
2497 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2502 .Cm auth | Cm bclient |
2503 .Cm calibrate | Cm kernel |
2504 .Cm mode7 | Cm monitor |
2505 .Cm ntp | Cm stats |
2506 .Cm peer_clear_digest_early |
2507 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2510 Provides a way to enable or disable various server options.
2511 Flags not mentioned are unaffected.
2512 Note that all of these flags
2513 can be controlled remotely using the
2514 .Xr ntpdc @NTPDC_MS@
2516 .Bl -tag -width indent
2518 Enables the server to synchronize with unconfigured peers only if the
2519 peer has been correctly authenticated using either public key or
2520 private key cryptography.
2521 The default for this flag is
2524 Enables the server to listen for a message from a broadcast or
2525 multicast server, as in the
2527 command with default
2529 The default for this flag is
2532 Enables the calibrate feature for reference clocks.
2537 Enables the kernel time discipline, if available.
2538 The default for this
2541 if support is available, otherwise
2544 Enables processing of NTP mode 7 implementation\-specific requests
2545 which are used by the deprecated
2546 .Xr ntpdc @NTPDC_MS@
2548 The default for this flag is disable.
2549 This flag is excluded from runtime configuration using
2550 .Xr ntpq @NTPQ_MS@ .
2553 program provides the same capabilities as
2554 .Xr ntpdc @NTPDC_MS@
2555 using standard mode 6 requests.
2557 Enables the monitoring facility.
2559 .Xr ntpdc @NTPDC_MS@
2563 command or further information.
2565 default for this flag is
2568 Enables time and frequency discipline.
2569 In effect, this switch opens and
2570 closes the feedback loop, which is useful for testing.
2574 .It Cm peer_clear_digest_early
2577 is using autokey and it
2578 receives a crypto\-NAK packet that
2579 passes the duplicate packet and origin timestamp checks
2580 the peer variables are immediately cleared.
2581 While this is generally a feature
2582 as it allows for quick recovery if a server key has changed,
2583 a properly forged and appropriately delivered crypto\-NAK packet
2584 can be used in a DoS attack.
2585 If you have active noticable problems with this type of DoS attack
2586 then you should consider
2587 disabling this option.
2590 file for evidence of any of these attacks.
2592 default for this flag is
2595 Enables the statistics facility.
2597 .Sx Monitoring Options
2598 section for further information.
2599 The default for this flag is
2601 .It Cm unpeer_crypto_early
2604 receives an autokey packet that fails TEST9,
2606 the association is immediately cleared.
2607 This is almost certainly a feature,
2608 but if, in spite of the current recommendation of not using autokey,
2613 you are seeing this sort of DoS attack
2614 disabling this flag will delay
2615 tearing down the association until the reachability counter
2619 file for evidence of any of these attacks.
2621 default for this flag is
2623 .It Cm unpeer_crypto_nak_early
2626 receives a crypto\-NAK packet that
2627 passes the duplicate packet and origin timestamp checks
2628 the association is immediately cleared.
2629 While this is generally a feature
2630 as it allows for quick recovery if a server key has changed,
2631 a properly forged and appropriately delivered crypto\-NAK packet
2632 can be used in a DoS attack.
2633 If you have active noticable problems with this type of DoS attack
2634 then you should consider
2635 disabling this option.
2638 file for evidence of any of these attacks.
2640 default for this flag is
2642 .It Cm unpeer_digest_early
2645 receives what should be an authenticated packet
2646 that passes other packet sanity checks but
2647 contains an invalid digest
2648 the association is immediately cleared.
2649 While this is generally a feature
2650 as it allows for quick recovery,
2651 if this type of packet is carefully forged and sent
2652 during an appropriate window it can be used for a DoS attack.
2653 If you have active noticable problems with this type of DoS attack
2654 then you should consider
2655 disabling this option.
2658 file for evidence of any of these attacks.
2660 default for this flag is
2663 .It Ic includefile Ar includefile
2664 This command allows additional configuration commands
2665 to be included from a separate file.
2667 be nested to a depth of five; upon reaching the end of any
2668 include file, command processing resumes in the previous
2670 This option is useful for sites that run
2672 on multiple hosts, with (mostly) common options (e.g., a
2676 .Cm listen | Cm ignore | Cm drop
2679 .Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard
2680 .Ar name | Ar address
2681 .Oo Cm / Ar prefixlen
2687 directive controls which network addresses
2689 opens, and whether input is dropped without processing.
2690 The first parameter determines the action for addresses
2691 which match the second parameter.
2692 The second parameter specifies a class of addresses,
2693 or a specific interface name,
2695 In the address case,
2697 determines how many bits must match for this rule to apply.
2699 prevents opening matching addresses,
2703 to open the address and drop all received packets without examination.
2706 directives can be used.
2707 The last rule which matches a particular address determines the action for it.
2709 directives are disabled if any
2715 command\-line options are specified in the configuration file,
2716 all available network addresses are opened.
2719 directive is an alias for
2721 .It Ic leapfile Ar leapfile
2722 This command loads the IERS leapseconds file and initializes the
2723 leapsecond values for the next leapsecond event, leapfile expiration
2724 time, and TAI offset.
2725 The file can be obtained directly from the IERS at
2726 .Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list
2728 .Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list .
2734 .Cm leapfile directive or when
2735 .Cm ntpd detects that the
2739 checks once a day to see if the
2743 .Xr update\-leap 1update_leapmdoc
2744 script can be run to see if the
2747 .It Ic leapsmearinterval Ar seconds
2748 This EXPERIMENTAL option is only available if
2751 .Cm \-\-enable\-leap\-smear
2755 It specifies the interval over which a leap second correction will be applied.
2756 Recommended values for this option are between
2757 7200 (2 hours) and 86400 (24 hours).
2758 .Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS!
2759 See http://bugs.ntp.org/2855 for more information.
2760 .It Ic logconfig Ar configkeyword
2761 This command controls the amount and type of output written to
2764 facility or the alternate
2767 By default, all output is turned on.
2770 keywords can be prefixed with
2786 messages can be controlled in four
2795 Within these classes four types of messages can be
2796 controlled: informational messages
2814 Configuration keywords are formed by concatenating the message class with
2818 prefix can be used instead of a message class.
2820 message class may also be followed by the
2822 keyword to enable/disable all
2823 messages of the respective message class.
2824 Thus, a minimal log configuration
2825 could look like this:
2827 logconfig =syncstatus +sysevents
2830 This would just list the synchronizations state of
2832 and the major system events.
2833 For a simple reference server, the
2834 following minimum message configuration could be useful:
2836 logconfig =syncall +clockall
2839 This configuration will list all clock information and
2840 synchronization information.
2841 All other events and messages about
2842 peers, system events and so on is suppressed.
2843 .It Ic logfile Ar logfile
2844 This command specifies the location of an alternate log file to
2845 be used instead of the default system
2848 This is the same operation as the
2850 command line option.
2853 .Cm maxdepth Ar count | Cm maxmem Ar kilobytes |
2854 .Cm mindepth Ar count | Cm maxage Ar seconds |
2855 .Cm initialloc Ar count | Cm initmem Ar kilobytes |
2856 .Cm incalloc Ar count | Cm incmem Ar kilobytes
2859 Controls size limite of the monitoring facility's Most Recently Used
2861 of client addresses, which is also used by the
2862 rate control facility.
2863 .Bl -tag -width indent
2864 .It Ic maxdepth Ar count
2865 .It Ic maxmem Ar kilobytes
2866 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2867 The acutal limit will be up to
2874 options offered in units of entries or kilobytes, if both
2877 .Cm maxmem are used, the last one used controls.
2878 The default is 1024 kilobytes.
2879 .It Cm mindepth Ar count
2880 Lower limit on the MRU list size.
2881 When the MRU list has fewer than
2883 entries, existing entries are never removed to make room for newer ones,
2884 regardless of their age.
2885 The default is 600 entries.
2886 .It Cm maxage Ar seconds
2887 Once the MRU list has
2889 entries and an additional client is to ba added to the list,
2890 if the oldest entry was updated more than
2892 seconds ago, that entry is removed and its storage is reused.
2893 If the oldest entry was updated more recently the MRU list is grown,
2895 .Cm maxdepth / moxmem .
2896 The default is 64 seconds.
2897 .It Cm initalloc Ar count
2898 .It Cm initmem Ar kilobytes
2899 Initial memory allocation at the time the monitoringfacility is first enabled,
2900 in terms of the number of entries or kilobytes.
2901 The default is 4 kilobytes.
2902 .It Cm incalloc Ar count
2903 .It Cm incmem Ar kilobytes
2904 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2905 The default is 4 kilobytes.
2907 .It Ic nonvolatile Ar threshold
2910 delta in seconds before an hourly change to the
2912 (frequency file) will be written, with a default value of 1e\-7 (0.1 PPM).
2913 The frequency file is inspected each hour.
2914 If the difference between the current frequency and the last value written
2915 exceeds the threshold, the file is written and the
2917 becomes the new threshold value.
2918 If the threshold is not exceeeded, it is reduced by half.
2919 This is intended to reduce the number of file writes
2920 for embedded systems with nonvolatile memory.
2921 .It Ic phone Ar dial ...
2922 This command is used in conjunction with
2923 the ACTS modem driver (type 18)
2924 or the JJY driver (type 40, mode 100 \- 180).
2925 For the ACTS modem driver (type 18), the arguments consist of
2926 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2928 For the JJY driver (type 40 mode 100 \- 180), the argument is
2929 one telephone number used to dial the telephone JJY service.
2930 The Hayes command ATDT is normally prepended to the number.
2931 The number can contain other modem control codes as well.
2932 .It Xo Cm pollskewlist
2943 Enable skewing of our poll requests to our servers.
2945 is a number between 3 and 17 inclusive, identifying a specific poll interval.
2946 A poll interval is 2^n seconds in duration,
2947 so a poll value of 3 corresponds to 8 seconds
2949 a poll interval of 17 corresponds to
2950 131,072 seconds, or about a day and a half.
2951 The next two numbers must be between 0 and one\-half of the poll interval,
2953 The first number specifies how early the poll may start,
2955 the second number specifies how late the poll may be delayed.
2956 With no arguments, internally specified default values are chosen.
2980 Reset one or more groups of counters maintained by
2988 .Cm memlock Ar Nmegabytes |
2989 .Cm stacksize Ar N4kPages
2990 .Cm filenum Ar Nfiledescriptors
2993 .Bl -tag -width indent
2994 .It Cm memlock Ar Nmegabytes
2995 Specify the number of megabytes of memory that should be
2996 allocated and locked.
2997 Probably only available under Linux, this option may be useful
2998 when dropping root (the
3001 The default is 32 megabytes on non\-Linux machines, and \-1 under Linux.
3002 -1 means "do not lock the process into memory".
3003 0 means "lock whatever memory the process wants into memory".
3004 .It Cm stacksize Ar N4kPages
3005 Specifies the maximum size of the process stack on systems with the
3008 Defaults to 50 4k pages (200 4k pages in OpenBSD).
3009 .It Cm filenum Ar Nfiledescriptors
3010 Specifies the maximum number of file descriptors ntpd may have open at once.
3011 Defaults to the system default.
3013 .It Ic saveconfigdir Ar directory_path
3014 Specify the directory in which to write configuration snapshots
3021 does not appear in the configuration file,
3023 requests are rejected by
3025 .It Ic saveconfig Ar filename
3026 Write the current configuration, including any runtime
3027 modifications given with
3030 .Cm config\-from\-file
3037 This command will be rejected unless the
3039 directive appears in
3045 format directives to substitute the current date and time,
3047 .Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf .
3048 The filename used is stored in the system variable
3050 Authentication is required.
3051 .It Ic setvar Ar variable Op Cm default
3052 This command adds an additional system variable.
3054 variables can be used to distribute additional information such as
3056 If the variable of the form
3063 variable will be listed as part of the default system variables
3069 These additional variables serve
3070 informational purposes only.
3071 They are not related to the protocol
3072 other that they can be listed.
3073 The known protocol variables will
3074 always override any variables defined via the
3077 There are three special variables that contain the names
3078 of all variable of the same group.
3082 the names of all system variables.
3086 the names of all peer variables and the
3088 holds the names of the reference clock variables.
3090 Display operational summary.
3092 Show statistics counters maintained in the protocol module.
3095 .Cm allan Ar allan |
3096 .Cm dispersion Ar dispersion |
3098 .Cm huffpuff Ar huffpuff |
3099 .Cm panic Ar panic |
3101 .Cm stepback Ar stepback |
3102 .Cm stepfwd Ar stepfwd |
3103 .Cm stepout Ar stepout
3106 This command can be used to alter several system variables in
3107 very exceptional circumstances.
3108 It should occur in the
3109 configuration file before any other configuration options.
3111 default values of these variables have been carefully optimized for
3112 a wide range of network speeds and reliability expectations.
3114 general, they interact in intricate ways that are hard to predict
3115 and some combinations can result in some very nasty behavior.
3117 rarely is it necessary to change the default values; but, some
3118 folks cannot resist twisting the knobs anyway and this command is
3120 Emphasis added: twisters are on their own and can expect
3121 no help from the support group.
3123 The variables operate as follows:
3124 .Bl -tag -width indent
3125 .It Cm allan Ar allan
3126 The argument becomes the new value for the minimum Allan
3127 intercept, which is a parameter of the PLL/FLL clock discipline
3129 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
3131 .It Cm dispersion Ar dispersion
3132 The argument becomes the new value for the dispersion increase rate,
3133 normally .000015 s/s.
3135 The argument becomes the initial value of the frequency offset in
3136 parts\-per\-million.
3137 This overrides the value in the frequency file, if
3138 present, and avoids the initial training state if it is not.
3139 .It Cm huffpuff Ar huffpuff
3140 The argument becomes the new value for the experimental
3141 huff\-n'\-puff filter span, which determines the most recent interval
3142 the algorithm will search for a minimum delay.
3144 900 s (15 m), but a more reasonable value is 7200 (2 hours).
3146 is no default, since the filter is not enabled unless this command
3148 .It Cm panic Ar panic
3149 The argument is the panic threshold, normally 1000 s.
3151 the panic sanity check is disabled and a clock offset of any value will
3154 The argument is the step threshold, which by default is 0.128 s.
3156 be set to any positive number in seconds.
3157 If set to zero, step
3158 adjustments will never occur.
3159 Note: The kernel time discipline is
3160 disabled if the step threshold is set to zero or greater than the
3162 .It Cm stepback Ar stepback
3163 The argument is the step threshold for the backward direction,
3164 which by default is 0.128 s.
3166 be set to any positive number in seconds.
3167 If both the forward and backward step thresholds are set to zero, step
3168 adjustments will never occur.
3169 Note: The kernel time discipline is
3171 each direction of step threshold are either
3172 set to zero or greater than .5 second.
3173 .It Cm stepfwd Ar stepfwd
3174 As for stepback, but for the forward direction.
3175 .It Cm stepout Ar stepout
3176 The argument is the stepout timeout, which by default is 900 s.
3178 be set to any positive number in seconds.
3179 If set to zero, the stepout
3180 pulses will not be suppressed.
3182 .It Cm writevar Ar assocID\ name = value [,...]
3183 Write (create or update) the specified variables.
3186 is zero, the variablea re from the
3188 name space, otherwise they are from the
3193 is required, as the same name can occur in both name spaces.
3194 .It Xo Ic trap Ar host_address
3195 .Op Cm port Ar port_number
3196 .Op Cm interface Ar interface_address
3198 This command configures a trap receiver at the given host
3199 address and port number for sending messages with the specified
3200 local interface address.
3201 If the port number is unspecified, a value
3203 If the interface address is not specified, the
3204 message is sent with a source address of the local interface the
3205 message is sent through.
3206 Note that on a multihomed host the
3207 interface used may vary from time to time with routing changes.
3208 .It Cm ttl Ar hop ...
3209 This command specifies a list of TTL values in increasing order.
3210 Up to 8 values can be specified.
3213 mode these values are used in\-turn in an expanding\-ring search.
3214 The default is eight multiples of 32 starting at 31.
3216 The trap receiver will generally log event messages and other
3217 information from the server in a log file.
3219 programs may also request their own trap dynamically, configuring a
3220 trap receiver will ensure that no messages are lost when the server
3223 This command specifies a list of TTL values in increasing order, up to 8
3224 values can be specified.
3225 In manycast mode these values are used in turn in
3226 an expanding\-ring search.
3227 The default is eight multiples of 32 starting at
3233 Display usage information and exit.
3235 Pass the extended usage information through a pager.
3236 .It Fl \-version Op Brq Ar v|c|n
3237 Output version of program and exit. The default mode is `v', a simple
3238 version. The `c' mode will print copyright information and `n' will
3239 print the full copyright notice.
3241 .Sh "OPTION PRESETS"
3242 Any option that is not marked as \fInot presettable\fP may be preset
3243 by loading values from environment variables named:
3245 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP
3249 See \fBOPTION PRESETS\fP for configuration environment variables.
3251 .Bl -tag -width /etc/ntp.drift -compact
3252 .It Pa /etc/ntp.conf
3253 the default name of the configuration file
3258 .It Pa ntpkey_ Ns Ar host
3261 Diffie\-Hellman agreement parameters
3264 One of the following exit values will be returned:
3266 .It 0 " (EXIT_SUCCESS)"
3267 Successful program execution.
3268 .It 1 " (EXIT_FAILURE)"
3269 The operation failed or the command syntax was not valid.
3270 .It 70 " (EX_SOFTWARE)"
3271 libopts had an internal operational error. Please report
3272 it to autogen\-users@lists.sourceforge.net. Thank you.
3275 .Xr ntpd @NTPD_MS@ ,
3276 .Xr ntpdc @NTPDC_MS@ ,
3279 In addition to the manual pages provided,
3280 comprehensive documentation is available on the world wide web
3282 .Li http://www.ntp.org/ .
3283 A snapshot of this documentation is available in HTML format in
3284 .Pa /usr/share/doc/ntp .
3287 .%T Network Time Protocol (Version 4)
3291 The University of Delaware and Network Time Foundation
3293 Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved.
3294 This program is released under the terms of the NTP license, <http://ntp.org/license>.
3296 The syntax checking is not picky; some combinations of
3297 ridiculous and even hilarious options and modes may not be
3301 .Pa ntpkey_ Ns Ar host
3302 files are really digital
3304 These should be obtained via secure directory
3305 services when they become universally available.
3307 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
3309 This document was derived from FreeBSD.
3311 This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP