2 .Dt NTP_CONF 5mdoc File Formats
4 .\" EDIT THIS FILE WITH CAUTION (ntp.mdoc)
6 .\" It has been AutoGen-ed February 27, 2018 at 05:14:42 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 1ntpdcmdoc ,
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
148 .It Xo Ic server Ar address
149 .Op Cm key Ar key \&| Cm autokey
152 .Op Cm version Ar version
154 .Op Cm minpoll Ar minpoll
155 .Op Cm maxpoll Ar maxpoll
158 .It Xo Ic peer Ar address
159 .Op Cm key Ar key \&| Cm autokey
160 .Op Cm version Ar version
162 .Op Cm minpoll Ar minpoll
163 .Op Cm maxpoll Ar maxpoll
167 .It Xo Ic broadcast Ar address
168 .Op Cm key Ar key \&| Cm autokey
169 .Op Cm version Ar version
171 .Op Cm minpoll Ar minpoll
175 .It Xo Ic manycastclient Ar address
176 .Op Cm key Ar key \&| Cm autokey
177 .Op Cm version Ar version
179 .Op Cm minpoll Ar minpoll
180 .Op Cm maxpoll Ar maxpoll
185 These five commands specify the time server name or address to
186 be used and the mode in which to operate.
190 either a DNS name or an IP address in dotted\-quad notation.
191 Additional information on association behavior can be found in the
192 .Qq Association Management
194 (available as part of the HTML documentation
196 .Pa /usr/share/doc/ntp ) .
197 .Bl -tag -width indent
199 For type s addresses, this command mobilizes a persistent
200 client mode association with a number of remote servers.
201 In this mode the local clock can synchronized to the
202 remote server, but the remote server can never be synchronized to
205 For type s and r addresses, this command mobilizes a persistent
206 client mode association with the specified remote server or local
208 In this mode the local clock can synchronized to the
209 remote server, but the remote server can never be synchronized to
216 For type s addresses (only), this command mobilizes a
217 persistent symmetric\-active mode association with the specified
219 In this mode the local clock can be synchronized to
220 the remote peer or the remote peer can be synchronized to the local
222 This is useful in a network of servers where, depending on
223 various failure scenarios, either the local or remote peer may be
224 the better source of time.
225 This command should NOT be used for type
228 For type b and m addresses (only), this
229 command mobilizes a persistent broadcast mode association.
231 commands can be used to specify multiple local broadcast interfaces
232 (subnets) and/or multiple multicast groups.
234 broadcast messages go only to the interface associated with the
235 subnet specified, but multicast messages go to all interfaces.
236 In broadcast mode the local server sends periodic broadcast
237 messages to a client population at the
239 specified, which is usually the broadcast address on (one of) the
240 local network(s) or a multicast address assigned to NTP.
242 has assigned the multicast group address IPv4 224.0.1.1 and
243 IPv6 ff05::101 (site local) exclusively to
244 NTP, but other nonconflicting addresses can be used to contain the
245 messages within administrative boundaries.
247 specification applies only to the local server operating as a
248 sender; for operation as a broadcast client, see the
254 .It Ic manycastclient
255 For type m addresses (only), this command mobilizes a
256 manycast client mode association for the multicast address
258 In this case a specific address must be supplied which
259 matches the address used on the
262 the designated manycast servers.
263 The NTP multicast address
264 224.0.1.1 assigned by the IANA should NOT be used, unless specific
265 means are taken to avoid spraying large areas of the Internet with
266 these messages and causing a possibly massive implosion of replies
270 command specifies that the local server
271 is to operate in client mode with the remote servers that are
272 discovered as the result of broadcast/multicast messages.
274 client broadcasts a request message to the group address associated
277 and specifically enabled
278 servers respond to these messages.
279 The client selects the servers
280 providing the best time and continues as with the
283 The remaining servers are discarded as if never
288 .Bl -tag -width indent
290 All packets sent to and received from the server or peer are to
291 include authentication fields encrypted using the autokey scheme
293 .Sx Authentication Options .
295 when the server is reachable, send a burst of eight packets
296 instead of the usual one.
297 The packet spacing is normally 2 s;
298 however, the spacing between the first and second packets
299 can be changed with the
302 additional time for a modem or ISDN call to complete.
303 This is designed to improve timekeeping quality
306 command and s addresses.
308 When the server is unreachable, send a burst of eight packets
309 instead of the usual one.
310 The packet spacing is normally 2 s;
311 however, the spacing between the first two packets can be
315 additional time for a modem or ISDN call to complete.
316 This is designed to speed the initial synchronization
319 command and s addresses and when
325 All packets sent to and received from the server or peer are to
326 include authentication fields encrypted using the specified
328 identifier with values from 1 to 65534, inclusive.
330 default is to include no encryption field.
331 .It Cm minpoll Ar minpoll
332 .It Cm maxpoll Ar maxpoll
333 These options specify the minimum and maximum poll intervals
334 for NTP messages, as a power of 2 in seconds
336 interval defaults to 10 (1,024 s), but can be increased by the
338 option to an upper limit of 17 (36.4 h).
340 minimum poll interval defaults to 6 (64 s), but can be decreased by
343 option to a lower limit of 4 (16 s).
345 Marks the server as unused, except for display purposes.
346 The server is discarded by the selection algroithm.
348 Says the association can be preempted.
350 Marks the server as a truechimer.
351 Use this option only for testing.
353 Marks the server as preferred.
354 All other things being equal,
355 this host will be chosen for synchronization among a set of
356 correctly operating hosts.
358 .Qq Mitigation Rules and the prefer Keyword
360 (available as part of the HTML documentation
362 .Pa /usr/share/doc/ntp )
363 for further information.
365 Forces 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.
394 .Ss Auxiliary Commands
395 .Bl -tag -width indent
396 .It Ic broadcastclient
397 This command enables reception of broadcast server messages to
398 any local interface (type b) address.
399 Upon receiving a message for
400 the first time, the broadcast client measures the nominal server
401 propagation delay using a brief client/server exchange with the
402 server, then enters the broadcast client mode, in which it
403 synchronizes to succeeding broadcast messages.
405 to avoid accidental or malicious disruption in this mode, both the
406 server and client should operate using symmetric\-key or public\-key
407 authentication as described in
408 .Sx Authentication Options .
409 .It Ic manycastserver Ar address ...
410 This command enables reception of manycast client messages to
411 the multicast group address(es) (type m) specified.
413 address is required, but the NTP multicast address 224.0.1.1
414 assigned by the IANA should NOT be used, unless specific means are
415 taken to limit the span of the reply and avoid a possibly massive
416 implosion at the original sender.
417 Note that, in order to avoid
418 accidental or malicious disruption in this mode, both the server
419 and client should operate using symmetric\-key or public\-key
420 authentication as described in
421 .Sx Authentication Options .
422 .It Ic multicastclient Ar address ...
423 This command enables reception of multicast server messages to
424 the multicast group address(es) (type m) specified.
426 a message for the first time, the multicast client measures the
427 nominal server propagation delay using a brief client/server
428 exchange with the server, then enters the broadcast client mode, in
429 which it synchronizes to succeeding multicast messages.
431 in order to avoid accidental or malicious disruption in this mode,
432 both the server and client should operate using symmetric\-key or
433 public\-key authentication as described in
434 .Sx Authentication Options .
435 .It Ic mdnstries Ar number
436 If we are participating in mDNS,
437 after we have synched for the first time
438 we attempt to register with the mDNS system.
439 If that registration attempt fails,
440 we try again at one minute intervals for up to
445 may be starting before mDNS.
446 The default value for
450 .Sh Authentication Support
451 Authentication support allows the NTP client to verify that the
452 server is in fact known and trusted and not an intruder intending
453 accidentally or on purpose to masquerade as that server.
455 specification RFC\-1305 defines a scheme which provides
456 cryptographic authentication of received NTP packets.
458 this was done using the Data Encryption Standard (DES) algorithm
459 operating in Cipher Block Chaining (CBC) mode, commonly called
461 Subsequently, this was replaced by the RSA Message Digest
462 5 (MD5) algorithm using a private key, commonly called keyed\-MD5.
463 Either algorithm computes a message digest, or one\-way hash, which
464 can be used to verify the server has the correct private key and
467 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
468 cryptography and, in addition, provides a new Autokey scheme
469 based on public key cryptography.
470 Public key cryptography is generally considered more secure
471 than symmetric key cryptography, since the security is based
472 on a private value which is generated by each server and
474 With Autokey all key distribution and
475 management functions involve only public values, which
476 considerably simplifies key distribution and storage.
477 Public key management is based on X.509 certificates,
478 which can be provided by commercial services or
479 produced by utility programs in the OpenSSL software library
480 or the NTPv4 distribution.
482 While the algorithms for symmetric key cryptography are
483 included in the NTPv4 distribution, public key cryptography
484 requires the OpenSSL software library to be installed
485 before building the NTP distribution.
486 Directions for doing that
487 are on the Building and Installing the Distribution page.
489 Authentication is configured separately for each association
500 configuration commands as described in
501 .Sx Configuration Options
504 options described below specify the locations of the key files,
505 if other than default, which symmetric keys are trusted
506 and the interval between various operations, if other than default.
508 Authentication is always enabled,
509 although ineffective if not configured as
511 If a NTP packet arrives
512 including a message authentication
513 code (MAC), it is accepted only if it
514 passes all cryptographic checks.
516 checks require correct key ID, key value
519 been modified in any way or replayed
520 by an intruder, it will fail one or more
521 of these checks and be discarded.
522 Furthermore, the Autokey scheme requires a
523 preliminary protocol exchange to obtain
524 the server certificate, verify its
525 credentials and initialize the protocol
529 flag controls whether new associations or
530 remote configuration commands require cryptographic authentication.
531 This flag can be set or reset by the
535 commands and also by remote
536 configuration commands sent by a
540 If this flag is enabled, which is the default
541 case, new broadcast client and symmetric passive associations and
542 remote configuration commands must be cryptographically
543 authenticated using either symmetric key or public key cryptography.
545 flag is disabled, these operations are effective
546 even if not cryptographic
548 It should be understood
549 that operating with the
551 flag disabled invites a significant vulnerability
552 where a rogue hacker can
553 masquerade as a falseticker and seriously
554 disrupt system timekeeping.
556 important to note that this flag has no purpose
557 other than to allow or disallow
558 a new association in response to new broadcast
559 and symmetric active messages
560 and remote configuration commands and, in particular,
561 the flag has no effect on
562 the authentication process itself.
564 An attractive alternative where multicast support is available
565 is manycast mode, in which clients periodically troll
566 for servers as described in the
567 .Sx Automatic NTP Configuration Options
569 Either symmetric key or public key
570 cryptographic authentication can be used in this mode.
571 The principle advantage
572 of manycast mode is that potential servers need not be
573 configured in advance,
574 since the client finds them during regular operation,
575 and the configuration
576 files for all clients can be identical.
578 The security model and protocol schemes for
579 both symmetric key and public key
580 cryptography are summarized below;
581 further details are in the briefings, papers
582 and reports at the NTP project page linked from
583 .Li http://www.ntp.org/ .
584 .Ss Symmetric\-Key Cryptography
585 The original RFC\-1305 specification allows any one of possibly
586 65,534 keys, each distinguished by a 32\-bit key identifier, to
587 authenticate an association.
588 The servers and clients involved must
589 agree on the key and key identifier to
590 authenticate NTP packets.
592 related information are specified in a key
595 which must be distributed and stored using
596 secure means beyond the scope of the NTP protocol itself.
597 Besides the keys used
598 for ordinary NTP associations,
599 additional keys can be used as passwords for the
607 is first started, it reads the key file specified in the
609 configuration command and installs the keys
612 individual keys must be activated with the
616 allows, for instance, the installation of possibly
617 several batches of keys and
618 then activating or deactivating each batch
620 .Xr ntpdc 1ntpdcmdoc .
621 This also provides a revocation capability that can be used
622 if a key becomes compromised.
625 command selects the key used as the password for the
629 command selects the key used as the password for the
632 .Ss Public Key Cryptography
633 NTPv4 supports the original NTPv3 symmetric key scheme
634 described in RFC\-1305 and in addition the Autokey protocol,
635 which is based on public key cryptography.
636 The Autokey Version 2 protocol described on the Autokey Protocol
637 page verifies packet integrity using MD5 message digests
638 and verifies the source with digital signatures and any of several
639 digest/signature schemes.
640 Optional identity schemes described on the Identity Schemes
641 page and based on cryptographic challenge/response algorithms
643 Using all of these schemes provides strong security against
644 replay with or without modification, spoofing, masquerade
645 and most forms of clogging attacks.
647 .\" The cryptographic means necessary for all Autokey operations
648 .\" is provided by the OpenSSL software library.
649 .\" This library is available from http://www.openssl.org/
650 .\" and can be installed using the procedures outlined
651 .\" in the Building and Installing the Distribution page.
653 .\" the configure and build
654 .\" process automatically detects the library and links
655 .\" the library routines required.
657 The Autokey protocol has several modes of operation
658 corresponding to the various NTP modes supported.
659 Most modes use a special cookie which can be
660 computed independently by the client and server,
661 but encrypted in transmission.
662 All modes use in addition a variant of the S\-KEY scheme,
663 in which a pseudo\-random key list is generated and used
665 These schemes are described along with an executive summary,
666 current status, briefing slides and reading list on the
667 .Sx Autonomous Authentication
670 The specific cryptographic environment used by Autokey servers
671 and clients is determined by a set of files
672 and soft links generated by the
673 .Xr ntp\-keygen 1ntpkeygenmdoc
675 This includes a required host key file,
676 required certificate file and optional sign key file,
677 leapsecond file and identity scheme files.
679 digest/signature scheme is specified in the X.509 certificate
680 along with the matching sign key.
681 There are several schemes
682 available in the OpenSSL software library, each identified
683 by a specific string such as
684 .Cm md5WithRSAEncryption ,
685 which stands for the MD5 message digest with RSA
687 The current NTP distribution supports
688 all the schemes in the OpenSSL library, including
689 those based on RSA and DSA digital signatures.
691 NTP secure groups can be used to define cryptographic compartments
692 and security hierarchies.
693 It is important that every host
694 in the group be able to construct a certificate trail to one
695 or more trusted hosts in the same group.
697 host runs the Autokey protocol to obtain the certificates
698 for all hosts along the trail to one or more trusted hosts.
699 This requires the configuration file in all hosts to be
700 engineered so that, even under anticipated failure conditions,
701 the NTP subnet will form such that every group host can find
702 a trail to at least one trusted host.
703 .Ss Naming and Addressing
704 It is important to note that Autokey does not use DNS to
705 resolve addresses, since DNS can't be completely trusted
706 until the name servers have synchronized clocks.
707 The cryptographic name used by Autokey to bind the host identity
708 credentials and cryptographic values must be independent
709 of interface, network and any other naming convention.
710 The name appears in the host certificate in either or both
711 the subject and issuer fields, so protection against
712 DNS compromise is essential.
714 By convention, the name of an Autokey host is the name returned
717 system call or equivalent in other systems.
719 model, there are no provisions to allow alternate names or aliases.
720 However, this is not to say that DNS aliases, different names
721 for each interface, etc., are constrained in any way.
723 It is also important to note that Autokey verifies authenticity
724 using the host name, network address and public keys,
725 all of which are bound together by the protocol specifically
726 to deflect masquerade attacks.
727 For this reason Autokey
728 includes the source and destination IP addresses in message digest
729 computations and so the same addresses must be available
730 at both the server and client.
731 For this reason operation
732 with network address translation schemes is not possible.
733 This reflects the intended robust security model where government
734 and corporate NTP servers are operated outside firewall perimeters.
736 A specific combination of authentication scheme (none,
737 symmetric key, public key) and identity scheme is called
738 a cryptotype, although not all combinations are compatible.
739 There may be management configurations where the clients,
740 servers and peers may not all support the same cryptotypes.
741 A secure NTPv4 subnet can be configured in many ways while
742 keeping in mind the principles explained above and
744 Note however that some cryptotype
745 combinations may successfully interoperate with each other,
746 but may not represent good security practice.
748 The cryptotype of an association is determined at the time
749 of mobilization, either at configuration time or some time
750 later when a message of appropriate cryptotype arrives.
755 configuration command and no
759 subcommands are present, the association is not
760 authenticated; if the
762 subcommand is present, the association is authenticated
763 using the symmetric key ID specified; if the
765 subcommand is present, the association is authenticated
768 When multiple identity schemes are supported in the Autokey
769 protocol, the first message exchange determines which one is used.
770 The client request message contains bits corresponding
771 to which schemes it has available.
772 The server response message
773 contains bits corresponding to which schemes it has available.
774 Both server and client match the received bits with their own
775 and select a common scheme.
777 Following the principle that time is a public value,
778 a server responds to any client packet that matches
779 its cryptotype capabilities.
780 Thus, a server receiving
781 an unauthenticated packet will respond with an unauthenticated
782 packet, while the same server receiving a packet of a cryptotype
783 it supports will respond with packets of that cryptotype.
784 However, unconfigured broadcast or manycast client
785 associations or symmetric passive associations will not be
786 mobilized unless the server supports a cryptotype compatible
787 with the first packet received.
788 By default, unauthenticated associations will not be mobilized
789 unless overridden in a decidedly dangerous way.
791 Some examples may help to reduce confusion.
792 Client Alice has no specific cryptotype selected.
793 Server Bob has both a symmetric key file and minimal Autokey files.
794 Alice's unauthenticated messages arrive at Bob, who replies with
795 unauthenticated messages.
796 Cathy has a copy of Bob's symmetric
797 key file and has selected key ID 4 in messages to Bob.
798 Bob verifies the message with his key ID 4.
800 same key and the message is verified, Bob sends Cathy a reply
801 authenticated with that key.
802 If verification fails,
803 Bob sends Cathy a thing called a crypto\-NAK, which tells her
805 She can see the evidence using the
809 Denise has rolled her own host key and certificate.
810 She also uses one of the identity schemes as Bob.
811 She sends the first Autokey message to Bob and they
812 both dance the protocol authentication and identity steps.
813 If all comes out okay, Denise and Bob continue as described above.
815 It should be clear from the above that Bob can support
816 all the girls at the same time, as long as he has compatible
817 authentication and identity credentials.
818 Now, Bob can act just like the girls in his own choice of servers;
819 he can run multiple configured associations with multiple different
820 servers (or the same server, although that might not be useful).
821 But, wise security policy might preclude some cryptotype
822 combinations; for instance, running an identity scheme
823 with one server and no authentication with another might not be wise.
825 The cryptographic values used by the Autokey protocol are
826 incorporated as a set of files generated by the
827 .Xr ntp\-keygen 1ntpkeygenmdoc
828 utility program, including symmetric key, host key and
829 public certificate files, as well as sign key, identity parameters
830 and leapseconds files.
831 Alternatively, host and sign keys and
832 certificate files can be generated by the OpenSSL utilities
833 and certificates can be imported from public certificate
835 Note that symmetric keys are necessary for the
840 The remaining files are necessary only for the
843 Certificates imported from OpenSSL or public certificate
844 authorities have certian limitations.
845 The certificate should be in ASN.1 syntax, X.509 Version 3
846 format and encoded in PEM, which is the same format
848 The overall length of the certificate encoded
849 in ASN.1 must not exceed 1024 bytes.
850 The subject distinguished
851 name field (CN) is the fully qualified name of the host
852 on which it is used; the remaining subject fields are ignored.
853 The certificate extension fields must not contain either
854 a subject key identifier or a issuer key identifier field;
855 however, an extended key usage field for a trusted host must
858 Other extension fields are ignored.
859 .Ss Authentication Commands
860 .Bl -tag -width indent
861 .It Ic autokey Op Ar logsec
862 Specifies the interval between regenerations of the session key
863 list used with the Autokey protocol.
864 Note that the size of the key
865 list for each association depends on this interval and the current
867 The default value is 12 (4096 s or about 1.1 hours).
868 For poll intervals above the specified interval, a session key list
869 with a single entry will be regenerated for every message
871 .It Ic controlkey Ar key
872 Specifies the key identifier to use with the
874 utility, which uses the standard
875 protocol defined in RFC\-1305.
879 the key identifier for a trusted key, where the value can be in the
880 range 1 to 65,534, inclusive.
884 .Op Cm randfile Ar file
889 .Op Cm iffpar Ar file
891 .Op Cm pw Ar password
893 This command requires the OpenSSL library.
894 It activates public key
895 cryptography, selects the message digest and signature
896 encryption scheme and loads the required private and public
897 values described above.
898 If one or more files are left unspecified,
899 the default names are used as described above.
900 Unless the complete path and name of the file are specified, the
901 location of a file is relative to the keys directory specified
906 Following are the subcommands:
907 .Bl -tag -width indent
909 Specifies the location of the required host public certificate file.
910 This overrides the link
911 .Pa ntpkey_cert_ Ns Ar hostname
912 in the keys directory.
914 Specifies the location of the optional GQ parameters file.
917 .Pa ntpkey_gq_ Ns Ar hostname
918 in the keys directory.
920 Specifies the location of the required host key file.
923 .Pa ntpkey_key_ Ns Ar hostname
924 in the keys directory.
925 .It Cm iffpar Ar file
926 Specifies the location of the optional IFF parameters file.
927 This overrides the link
928 .Pa ntpkey_iff_ Ns Ar hostname
929 in the keys directory.
931 Specifies the location of the optional leapsecond file.
932 This overrides the link
934 in the keys directory.
936 Specifies the location of the optional MV parameters file.
937 This overrides the link
938 .Pa ntpkey_mv_ Ns Ar hostname
939 in the keys directory.
940 .It Cm pw Ar password
941 Specifies the password to decrypt files containing private keys and
943 This is required only if these files have been
945 .It Cm randfile Ar file
946 Specifies the location of the random seed file used by the OpenSSL
948 The defaults are described in the main text above.
950 Specifies the location of the optional sign key file.
953 .Pa ntpkey_sign_ Ns Ar hostname
954 in the keys directory.
956 not found, the host key is also the sign key.
958 .It Ic keys Ar keyfile
959 Specifies the complete path and location of the MD5 key file
960 containing the keys and key identifiers used by
965 when operating with symmetric key cryptography.
966 This is the same operation as the
969 .It Ic keysdir Ar path
970 This command specifies the default directory path for
971 cryptographic keys, parameters and certificates.
973 .Pa /usr/local/etc/ .
974 .It Ic requestkey Ar key
975 Specifies the key identifier to use with the
977 utility program, which uses a
978 proprietary protocol specific to this implementation of
982 argument is a key identifier
983 for the trusted key, where the value can be in the range 1 to
985 .It Ic revoke Ar logsec
986 Specifies the interval between re\-randomization of certain
987 cryptographic values used by the Autokey scheme, as a power of 2 in
989 These values need to be updated frequently in order to
990 deflect brute\-force attacks on the algorithms of the scheme;
991 however, updating some values is a relatively expensive operation.
992 The default interval is 16 (65,536 s or about 18 hours).
994 intervals above the specified interval, the values will be updated
995 for every message sent.
996 .It Ic trustedkey Ar key ...
997 Specifies the key identifiers which are trusted for the
998 purposes of authenticating peers with symmetric key cryptography,
999 as well as keys used by the
1002 .Xr ntpdc 1ntpdcmdoc
1004 The authentication procedures require that both the local
1005 and remote servers share the same key and key identifier for this
1006 purpose, although different keys can be used with different
1010 arguments are 32\-bit unsigned
1011 integers with values from 1 to 65,534.
1014 The following error codes are reported via the NTP control
1015 and monitoring protocol trap mechanism.
1016 .Bl -tag -width indent
1018 .Pq bad field format or length
1019 The packet has invalid version, length or format.
1022 The packet timestamp is the same or older than the most recent received.
1023 This could be due to a replay or a server clock time step.
1026 The packet filestamp is the same or older than the most recent received.
1027 This could be due to a replay or a key file generation error.
1029 .Pq bad or missing public key
1030 The public key is missing, has incorrect format or is an unsupported type.
1032 .Pq unsupported digest type
1033 The server requires an unsupported digest/signature scheme.
1035 .Pq mismatched digest types
1038 .Pq bad signature length
1039 The signature length does not match the current public key.
1041 .Pq signature not verified
1042 The message fails the signature check.
1043 It could be bogus or signed by a
1044 different private key.
1046 .Pq certificate not verified
1047 The certificate is invalid or signed with the wrong key.
1049 .Pq certificate not verified
1050 The certificate is not yet valid or has expired or the signature could not
1053 .Pq bad or missing cookie
1054 The cookie is missing, corrupted or bogus.
1056 .Pq bad or missing leapseconds table
1057 The leapseconds table is missing, corrupted or bogus.
1059 .Pq bad or missing certificate
1060 The certificate is missing, corrupted or bogus.
1062 .Pq bad or missing identity
1063 The identity key is missing, corrupt or bogus.
1065 .Sh Monitoring Support
1067 includes a comprehensive monitoring facility suitable
1068 for continuous, long term recording of server and client
1069 timekeeping performance.
1073 for a listing and example of each type of statistics currently
1075 Statistic files are managed using file generation sets
1078 directory of the source code distribution.
1080 these facilities and
1083 jobs, the data can be
1084 automatically summarized and archived for retrospective analysis.
1085 .Ss Monitoring Commands
1086 .Bl -tag -width indent
1087 .It Ic statistics Ar name ...
1088 Enables writing of statistics records.
1089 Currently, eight kinds of
1091 statistics are supported.
1092 .Bl -tag -width indent
1094 Enables recording of clock driver statistics information.
1096 received from a clock driver appends a line of the following form to
1097 the file generation set named
1100 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1103 The first two fields show the date (Modified Julian Day) and time
1104 (seconds and fraction past UTC midnight).
1105 The next field shows the
1106 clock address in dotted\-quad notation.
1107 The final field shows the last
1108 timecode received from the clock in decoded ASCII format, where
1110 In some clock drivers a good deal of additional information
1111 can be gathered and displayed as well.
1112 See information specific to each
1113 clock for further details.
1115 This option requires the OpenSSL cryptographic software library.
1117 enables recording of cryptographic public key protocol information.
1118 Each message received by the protocol module appends a line of the
1119 following form to the file generation set named
1122 49213 525.624 127.127.4.1 message
1125 The first two fields show the date (Modified Julian Day) and time
1126 (seconds and fraction past UTC midnight).
1127 The next field shows the peer
1128 address in dotted\-quad notation, The final message field includes the
1129 message type and certain ancillary information.
1131 .Sx Authentication Options
1132 section for further information.
1134 Enables recording of loop filter statistics information.
1136 update of the local clock outputs a line of the following form to
1137 the file generation set named
1140 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1143 The first two fields show the date (Modified Julian Day) and
1144 time (seconds and fraction past UTC midnight).
1145 The next five fields
1146 show time offset (seconds), frequency offset (parts per million \-
1147 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1148 discipline time constant.
1150 Enables recording of peer statistics information.
1152 statistics records of all peers of a NTP server and of special
1153 signals, where present and configured.
1154 Each valid update appends a
1155 line of the following form to the current element of a file
1156 generation set named
1159 48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674
1162 The first two fields show the date (Modified Julian Day) and
1163 time (seconds and fraction past UTC midnight).
1165 show the peer address in dotted\-quad notation and status,
1167 The status field is encoded in hex in the format
1168 described in Appendix A of the NTP specification RFC 1305.
1169 The final four fields show the offset,
1170 delay, dispersion and RMS jitter, all in seconds.
1172 Enables recording of raw\-timestamp statistics information.
1174 includes statistics records of all peers of a NTP server and of
1175 special signals, where present and configured.
1177 received from a peer or clock driver appends a line of the
1178 following form to the file generation set named
1181 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1184 The first two fields show the date (Modified Julian Day) and
1185 time (seconds and fraction past UTC midnight).
1187 show the remote peer or clock address followed by the local address
1188 in dotted\-quad notation.
1189 The final four fields show the originate,
1190 receive, transmit and final NTP timestamps in order.
1192 values are as received and before processing by the various data
1193 smoothing and mitigation algorithms.
1195 Enables recording of ntpd statistics counters on a periodic basis.
1197 hour a line of the following form is appended to the file generation
1201 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1204 The first two fields show the date (Modified Julian Day) and time
1205 (seconds and fraction past UTC midnight).
1206 The remaining ten fields show
1207 the statistics counter values accumulated since the last generated
1209 .Bl -tag -width indent
1210 .It Time since restart Cm 36000
1211 Time in hours since the system was last rebooted.
1212 .It Packets received Cm 81965
1213 Total number of packets received.
1214 .It Packets processed Cm 0
1215 Number of packets received in response to previous packets sent
1216 .It Current version Cm 9546
1217 Number of packets matching the current NTP version.
1218 .It Previous version Cm 56
1219 Number of packets matching the previous NTP version.
1220 .It Bad version Cm 71793
1221 Number of packets matching neither NTP version.
1222 .It Access denied Cm 512
1223 Number of packets denied access for any reason.
1224 .It Bad length or format Cm 540
1225 Number of packets with invalid length, format or port number.
1226 .It Bad authentication Cm 10
1227 Number of packets not verified as authentic.
1228 .It Rate exceeded Cm 147
1229 Number of packets discarded due to rate limitation.
1231 .It Cm statsdir Ar directory_path
1232 Indicates the full path of a directory where statistics files
1233 should be created (see below).
1235 the (otherwise constant)
1237 filename prefix to be modified for file generation sets, which
1238 is useful for handling statistics logs.
1239 .It Cm filegen Ar name Xo
1240 .Op Cm file Ar filename
1241 .Op Cm type Ar typename
1242 .Op Cm link | nolink
1243 .Op Cm enable | disable
1245 Configures setting of generation file set name.
1247 file sets provide a means for handling files that are
1248 continuously growing during the lifetime of a server.
1249 Server statistics are a typical example for such files.
1250 Generation file sets provide access to a set of files used
1251 to store the actual data.
1252 At any time at most one element
1253 of the set is being written to.
1254 The type given specifies
1255 when and how data will be directed to a new element of the set.
1256 This way, information stored in elements of a file set
1257 that are currently unused are available for administrational
1258 operations without the risk of disturbing the operation of ntpd.
1259 (Most important: they can be removed to free space for new data
1262 Note that this command can be sent from the
1263 .Xr ntpdc 1ntpdcmdoc
1264 program running at a remote location.
1265 .Bl -tag -width indent
1267 This is the type of the statistics records, as shown in the
1270 .It Cm file Ar filename
1271 This is the file name for the statistics records.
1273 members are built from three concatenated elements
1278 .Bl -tag -width indent
1280 This is a constant filename path.
1281 It is not subject to
1282 modifications via the
1285 It is defined by the
1286 server, usually specified as a compile\-time constant.
1288 however, be configurable for individual file generation sets
1290 For example, the prefix used with
1294 generation can be configured using the
1296 option explained above.
1298 This string is directly concatenated to the prefix mentioned
1299 above (no intervening
1301 This can be modified using
1302 the file argument to the
1308 allowed in this component to prevent filenames referring to
1309 parts outside the filesystem hierarchy denoted by
1312 This part is reflects individual elements of a file set.
1314 generated according to the type of a file set.
1316 .It Cm type Ar typename
1317 A file generation set is characterized by its type.
1319 types are supported:
1320 .Bl -tag -width indent
1322 The file set is actually a single plain file.
1324 One element of file set is used per incarnation of a ntpd
1326 This type does not perform any changes to file set
1327 members during runtime, however it provides an easy way of
1328 separating files belonging to different
1330 server incarnations.
1331 The set member filename is built by appending a
1338 appending the decimal representation of the process ID of the
1342 One file generation set element is created per day.
1344 defined as the period between 00:00 and 24:00 UTC.
1346 member suffix consists of a
1348 and a day specification in
1352 is a 4\-digit year number (e.g., 1992).
1354 is a two digit month number.
1356 is a two digit day number.
1357 Thus, all information written at 10 December 1992 would end up
1360 .Ar filename Ns .19921210 .
1362 Any file set member contains data related to a certain week of
1364 The term week is defined by computing day\-of\-year
1366 Elements of such a file generation set are
1367 distinguished by appending the following suffix to the file set
1368 filename base: A dot, a 4\-digit year number, the letter
1370 and a 2\-digit week number.
1371 For example, information from January,
1372 10th 1992 would end up in a file with suffix
1373 .No . Ns Ar 1992W1 .
1375 One generation file set element is generated per month.
1377 file name suffix consists of a dot, a 4\-digit year number, and
1380 One generation file element is generated per year.
1382 suffix consists of a dot and a 4 digit year number.
1384 This type of file generation sets changes to a new element of
1385 the file set every 24 hours of server operation.
1387 suffix consists of a dot, the letter
1389 and an 8\-digit number.
1390 This number is taken to be the number of seconds the server is
1391 running at the start of the corresponding 24\-hour period.
1392 Information is only written to a file generation by specifying
1394 output is prevented by specifying
1397 .It Cm link | nolink
1398 It is convenient to be able to access the current element of a file
1399 generation set by a fixed name.
1400 This feature is enabled by
1405 If link is specified, a
1406 hard link from the current file set element to a file without
1408 When there is already a file with this name and
1409 the number of links of this file is one, it is renamed appending a
1416 number of links is greater than one, the file is unlinked.
1418 allows the current file to be accessed by a constant name.
1419 .It Cm enable \&| Cm disable
1420 Enables or disables the recording function.
1424 .Sh Access Control Support
1427 daemon implements a general purpose address/mask based restriction
1429 The list contains address/match entries sorted first
1430 by increasing address values and and then by increasing mask values.
1431 A match occurs when the bitwise AND of the mask and the packet
1432 source address is equal to the bitwise AND of the mask and
1433 address in the list.
1434 The list is searched in order with the
1435 last match found defining the restriction flags associated
1437 Additional information and examples can be found in the
1438 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
1440 (available as part of the HTML documentation
1442 .Pa /usr/share/doc/ntp ) .
1444 The restriction facility was implemented in conformance
1445 with the access policies for the original NSFnet backbone
1447 Later the facility was expanded to deflect
1448 cryptographic and clogging attacks.
1449 While this facility may
1450 be useful for keeping unwanted or broken or malicious clients
1451 from congesting innocent servers, it should not be considered
1452 an alternative to the NTP authentication facilities.
1453 Source address based restrictions are easily circumvented
1454 by a determined cracker.
1456 Clients can be denied service because they are explicitly
1457 included in the restrict list created by the
1460 or implicitly as the result of cryptographic or rate limit
1462 Cryptographic violations include certificate
1463 or identity verification failure; rate limit violations generally
1464 result from defective NTP implementations that send packets
1466 Some violations cause denied service
1467 only for the offending packet, others cause denied service
1468 for a timed period and others cause the denied service for
1469 an indefinite period.
1470 When a client or network is denied access
1471 for an indefinite period, the only way at present to remove
1472 the restrictions is by restarting the server.
1473 .Ss The Kiss\-of\-Death Packet
1474 Ordinarily, packets denied service are simply dropped with no
1475 further action except incrementing statistics counters.
1477 more proactive response is needed, such as a server message that
1478 explicitly requests the client to stop sending and leave a message
1479 for the system operator.
1480 A special packet format has been created
1481 for this purpose called the "kiss\-of\-death" (KoD) packet.
1482 KoD packets have the leap bits set unsynchronized and stratum set
1483 to zero and the reference identifier field set to a four\-byte
1489 flag of the matching restrict list entry is set,
1490 the code is "DENY"; if the
1492 flag is set and the rate limit
1493 is exceeded, the code is "RATE".
1494 Finally, if a cryptographic violation occurs, the code is "CRYP".
1496 A client receiving a KoD performs a set of sanity checks to
1497 minimize security exposure, then updates the stratum and
1498 reference identifier peer variables, sets the access
1499 denied (TEST4) bit in the peer flash variable and sends
1500 a message to the log.
1501 As long as the TEST4 bit is set,
1502 the client will send no further packets to the server.
1503 The only way at present to recover from this condition is
1504 to restart the protocol at both the client and server.
1506 happens automatically at the client when the association times out.
1507 It will happen at the server only if the server operator cooperates.
1508 .Ss Access Control Commands
1509 .Bl -tag -width indent
1511 .Op Cm average Ar avg
1512 .Op Cm minimum Ar min
1513 .Op Cm monitor Ar prob
1515 Set the parameters of the
1517 facility which protects the server from
1521 subcommand specifies the minimum average packet
1524 subcommand specifies the minimum packet spacing.
1525 Packets that violate these minima are discarded
1526 and a kiss\-o'\-death packet returned if enabled.
1528 minimum average and minimum are 5 and 2, respectively.
1531 subcommand specifies the probability of discard
1532 for packets that overflow the rate\-control window.
1533 .It Xo Ic restrict address
1535 .Op Cm ippeerlimit Ar int
1540 argument expressed in
1541 dotted\-quad form is the address of a host or network.
1544 argument can be a valid host DNS name.
1547 argument expressed in dotted\-quad form defaults to
1548 .Cm 255.255.255.255 ,
1551 is treated as the address of an individual host.
1552 A default entry (address
1556 is always included and is always the first entry in the list.
1557 Note that text string
1559 with no mask option, may
1560 be used to indicate the default entry.
1563 directive limits the number of peer requests for each IP to
1565 where a value of \-1 means "unlimited", the current default.
1566 A value of 0 means "none".
1567 There would usually be at most 1 peering request per IP,
1568 but if the remote peering requests are behind a proxy
1569 there could well be more than 1 per IP.
1570 In the current implementation,
1573 restricts access, i.e., an entry with no flags indicates that free
1574 access to the server is to be given.
1575 The flags are not orthogonal,
1576 in that more restrictive flags will often make less restrictive
1578 The flags can generally be classed into two
1579 categories, those which restrict time service and those which
1580 restrict informational queries and attempts to do run\-time
1581 reconfiguration of the server.
1582 One or more of the following flags
1584 .Bl -tag -width indent
1586 Deny packets of all kinds, including
1589 .Xr ntpdc 1ntpdcmdoc
1592 If this flag is set when an access violation occurs, a kiss\-o'\-death
1593 (KoD) packet is sent.
1594 KoD packets are rate limited to no more than one
1596 If another KoD packet occurs within one second after the
1597 last one, the packet is dropped.
1599 Deny service if the packet spacing violates the lower limits specified
1603 A history of clients is kept using the
1604 monitoring capability of
1605 .Xr ntpd 1ntpdmdoc .
1606 Thus, monitoring is always active as
1607 long as there is a restriction entry with the
1611 Declare traps set by matching hosts to be low priority.
1613 number of traps a server can maintain is limited (the current limit
1615 Traps are usually assigned on a first come, first served
1616 basis, with later trap requestors being denied service.
1618 modifies the assignment algorithm by allowing low priority traps to
1619 be overridden by later requests for normal priority traps.
1621 Deny ephemeral peer requests,
1622 even if they come from an authenticated source.
1623 Note that the ability to use a symmetric key for authentication may be restricted to
1624 one or more IPs or subnets via the third field of the
1627 This restriction is not enabled by default,
1628 to maintain backward compatability.
1631 to become the default in ntp\-4.4.
1636 .Xr ntpdc 1ntpdcmdoc
1637 queries which attempt to modify the state of the
1638 server (i.e., run time reconfiguration).
1639 Queries which return
1640 information are permitted.
1645 .Xr ntpdc 1ntpdcmdoc
1647 Time service is not affected.
1649 Deny unauthenticated packets which would result in mobilizing a new association.
1651 broadcast and symmetric active packets
1652 when a configured association does not exist.
1655 associations, so if you want to use servers from a
1657 directive and also want to use
1659 by default, you'll want a
1660 .Cm "restrict source ..."
1661 line as well that does
1667 Deny all packets except
1670 .Xr ntpdc 1ntpdcmdoc
1673 Decline to provide mode 6 control message trap service to matching
1675 The trap service is a subsystem of the
1678 protocol which is intended for use by remote event logging programs.
1680 Deny service unless the packet is cryptographically authenticated.
1682 This is actually a match algorithm modifier, rather than a
1684 Its presence causes the restriction entry to be
1685 matched only if the source port in the packet is the standard NTP
1695 is considered more specific and
1696 is sorted later in the list.
1698 Deny packets that do not match the current NTP version.
1701 Default restriction list entries with the flags ignore, interface,
1702 ntpport, for each of the local host's interface addresses are
1703 inserted into the table at startup to prevent the server
1704 from attempting to synchronize to its own time.
1705 A default entry is also always present, though if it is
1706 otherwise unconfigured; no flags are associated
1707 with the default entry (i.e., everything besides your own
1708 NTP server is unrestricted).
1710 .Sh Automatic NTP Configuration Options
1712 Manycasting is a automatic discovery and configuration paradigm
1714 It is intended as a means for a multicast client
1715 to troll the nearby network neighborhood to find cooperating
1716 manycast servers, validate them using cryptographic means
1717 and evaluate their time values with respect to other servers
1718 that might be lurking in the vicinity.
1719 The intended result is that each manycast client mobilizes
1720 client associations with some number of the "best"
1721 of the nearby manycast servers, yet automatically reconfigures
1722 to sustain this number of servers should one or another fail.
1724 Note that the manycasting paradigm does not coincide
1725 with the anycast paradigm described in RFC\-1546,
1726 which is designed to find a single server from a clique
1727 of servers providing the same service.
1728 The manycast paradigm is designed to find a plurality
1729 of redundant servers satisfying defined optimality criteria.
1731 Manycasting can be used with either symmetric key
1732 or public key cryptography.
1733 The public key infrastructure (PKI)
1734 offers the best protection against compromised keys
1735 and is generally considered stronger, at least with relatively
1737 It is implemented using the Autokey protocol and
1738 the OpenSSL cryptographic library available from
1739 .Li http://www.openssl.org/ .
1740 The library can also be used with other NTPv4 modes
1741 as well and is highly recommended, especially for broadcast modes.
1743 A persistent manycast client association is configured
1746 command, which is similar to the
1748 command but with a multicast (IPv4 class
1753 The IANA has designated IPv4 address 224.1.1.1
1754 and IPv6 address FF05::101 (site local) for NTP.
1755 When more servers are needed, it broadcasts manycast
1756 client messages to this address at the minimum feasible rate
1757 and minimum feasible time\-to\-live (TTL) hops, depending
1758 on how many servers have already been found.
1759 There can be as many manycast client associations
1760 as different group address, each one serving as a template
1761 for a future ephemeral unicast client/server association.
1763 Manycast servers configured with the
1765 command listen on the specified group address for manycast
1767 Note the distinction between manycast client,
1768 which actively broadcasts messages, and manycast server,
1769 which passively responds to them.
1770 If a manycast server is
1771 in scope of the current TTL and is itself synchronized
1772 to a valid source and operating at a stratum level equal
1773 to or lower than the manycast client, it replies to the
1774 manycast client message with an ordinary unicast server message.
1776 The manycast client receiving this message mobilizes
1777 an ephemeral client/server association according to the
1778 matching manycast client template, but only if cryptographically
1779 authenticated and the server stratum is less than or equal
1780 to the client stratum.
1781 Authentication is explicitly required
1782 and either symmetric key or public key (Autokey) can be used.
1783 Then, the client polls the server at its unicast address
1784 in burst mode in order to reliably set the host clock
1785 and validate the source.
1786 This normally results
1787 in a volley of eight client/server at 2\-s intervals
1788 during which both the synchronization and cryptographic
1789 protocols run concurrently.
1790 Following the volley,
1791 the client runs the NTP intersection and clustering
1792 algorithms, which act to discard all but the "best"
1793 associations according to stratum and synchronization
1795 The surviving associations then continue
1796 in ordinary client/server mode.
1798 The manycast client polling strategy is designed to reduce
1799 as much as possible the volume of manycast client messages
1800 and the effects of implosion due to near\-simultaneous
1801 arrival of manycast server messages.
1802 The strategy is determined by the
1803 .Ic manycastclient ,
1807 configuration commands.
1808 The manycast poll interval is
1809 normally eight times the system poll interval,
1810 which starts out at the
1812 value specified in the
1813 .Ic manycastclient ,
1814 command and, under normal circumstances, increments to the
1816 value specified in this command.
1817 Initially, the TTL is
1818 set at the minimum hops specified by the
1821 At each retransmission the TTL is increased until reaching
1822 the maximum hops specified by this command or a sufficient
1823 number client associations have been found.
1824 Further retransmissions use the same TTL.
1826 The quality and reliability of the suite of associations
1827 discovered by the manycast client is determined by the NTP
1828 mitigation algorithms and the
1832 values specified in the
1834 configuration command.
1837 candidate servers must be available and the mitigation
1838 algorithms produce at least
1840 survivors in order to synchronize the clock.
1841 Byzantine agreement principles require at least four
1842 candidates in order to correctly discard a single falseticker.
1843 For legacy purposes,
1848 For manycast service
1850 should be explicitly set to 4, assuming at least that
1851 number of servers are available.
1855 servers are found, the manycast poll interval is immediately
1860 servers are found when the TTL has reached the maximum hops,
1861 the manycast poll interval is doubled.
1862 For each transmission
1863 after that, the poll interval is doubled again until
1864 reaching the maximum of eight times
1866 Further transmissions use the same poll interval and
1868 Note that while all this is going on,
1869 each client/server association found is operating normally
1870 it the system poll interval.
1872 Administratively scoped multicast boundaries are normally
1873 specified by the network router configuration and,
1874 in the case of IPv6, the link/site scope prefix.
1875 By default, the increment for TTL hops is 32 starting
1876 from 31; however, the
1878 configuration command can be
1879 used to modify the values to match the scope rules.
1881 It is often useful to narrow the range of acceptable
1882 servers which can be found by manycast client associations.
1883 Because manycast servers respond only when the client
1884 stratum is equal to or greater than the server stratum,
1885 primary (stratum 1) servers fill find only primary servers
1886 in TTL range, which is probably the most common objective.
1887 However, unless configured otherwise, all manycast clients
1888 in TTL range will eventually find all primary servers
1889 in TTL range, which is probably not the most common
1890 objective in large networks.
1893 command can be used to modify this behavior.
1894 Servers with stratum below
1900 command are strongly discouraged during the selection
1901 process; however, these servers may be temporally
1902 accepted if the number of servers within TTL range is
1906 The above actions occur for each manycast client message,
1907 which repeats at the designated poll interval.
1908 However, once the ephemeral client association is mobilized,
1909 subsequent manycast server replies are discarded,
1910 since that would result in a duplicate association.
1911 If during a poll interval the number of client associations
1914 all manycast client prototype associations are reset
1915 to the initial poll interval and TTL hops and operation
1916 resumes from the beginning.
1917 It is important to avoid
1918 frequent manycast client messages, since each one requires
1919 all manycast servers in TTL range to respond.
1920 The result could well be an implosion, either minor or major,
1921 depending on the number of servers in range.
1922 The recommended value for
1926 It is possible and frequently useful to configure a host
1927 as both manycast client and manycast server.
1928 A number of hosts configured this way and sharing a common
1929 group address will automatically organize themselves
1930 in an optimum configuration based on stratum and
1931 synchronization distance.
1932 For example, consider an NTP
1933 subnet of two primary servers and a hundred or more
1935 With two exceptions, all servers
1936 and clients have identical configuration files including both
1940 commands using, for instance, multicast group address
1942 The only exception is that each primary server
1943 configuration file must include commands for the primary
1944 reference source such as a GPS receiver.
1946 The remaining configuration files for all secondary
1947 servers and clients have the same contents, except for the
1949 command, which is specific for each stratum level.
1950 For stratum 1 and stratum 2 servers, that command is
1952 For stratum 3 and above servers the
1954 value is set to the intended stratum number.
1955 Thus, all stratum 3 configuration files are identical,
1956 all stratum 4 files are identical and so forth.
1958 Once operations have stabilized in this scenario,
1959 the primary servers will find the primary reference source
1960 and each other, since they both operate at the same
1961 stratum (1), but not with any secondary server or client,
1962 since these operate at a higher stratum.
1964 servers will find the servers at the same stratum level.
1965 If one of the primary servers loses its GPS receiver,
1966 it will continue to operate as a client and other clients
1967 will time out the corresponding association and
1968 re\-associate accordingly.
1970 Some administrators prefer to avoid running
1972 continuously and run either
1978 In either case the servers must be
1979 configured in advance and the program fails if none are
1980 available when the cron job runs.
1982 application of manycast is with
1985 The program wakes up, scans the local landscape looking
1986 for the usual suspects, selects the best from among
1987 the rascals, sets the clock and then departs.
1988 Servers do not have to be configured in advance and
1989 all clients throughout the network can have the same
1991 .Ss Manycast Interactions with Autokey
1992 Each time a manycast client sends a client mode packet
1993 to a multicast group address, all manycast servers
1994 in scope generate a reply including the host name
1996 The manycast clients then run
1997 the Autokey protocol, which collects and verifies
1998 all certificates involved.
1999 Following the burst interval
2000 all but three survivors are cast off,
2001 but the certificates remain in the local cache.
2002 It often happens that several complete signing trails
2003 from the client to the primary servers are collected in this way.
2005 About once an hour or less often if the poll interval
2006 exceeds this, the client regenerates the Autokey key list.
2007 This is in general transparent in client/server mode.
2008 However, about once per day the server private value
2009 used to generate cookies is refreshed along with all
2010 manycast client associations.
2012 cryptographic values including certificates is refreshed.
2013 If a new certificate has been generated since
2014 the last refresh epoch, it will automatically revoke
2015 all prior certificates that happen to be in the
2017 At the same time, the manycast
2018 scheme starts all over from the beginning and
2019 the expanding ring shrinks to the minimum and increments
2020 from there while collecting all servers in scope.
2021 .Ss Broadcast Options
2022 .Bl -tag -width indent
2025 .Cm bcpollbstep Ar gate
2028 This command provides a way to delay,
2029 by the specified number of broadcast poll intervals,
2030 believing backward time steps from a broadcast server.
2031 Broadcast time networks are expected to be trusted.
2032 In the event a broadcast server's time is stepped backwards,
2033 there is clear benefit to having the clients notice this change
2034 as soon as possible.
2035 Attacks such as replay attacks can happen, however,
2036 and even though there are a number of protections built in to
2037 broadcast mode, attempts to perform a replay attack are possible.
2038 This value defaults to 0, but can be changed
2039 to any number of poll intervals between 0 and 4.
2041 .Ss Manycast Options
2042 .Bl -tag -width indent
2045 .Cm ceiling Ar ceiling |
2046 .Cm cohort { 0 | 1 } |
2047 .Cm floor Ar floor |
2048 .Cm minclock Ar minclock |
2049 .Cm minsane Ar minsane
2052 This command affects the clock selection and clustering
2054 It can be used to select the quality and
2055 quantity of peers used to synchronize the system clock
2056 and is most useful in manycast mode.
2057 The variables operate
2059 .Bl -tag -width indent
2060 .It Cm ceiling Ar ceiling
2061 Peers with strata above
2063 will be discarded if there are at least
2066 This value defaults to 15, but can be changed
2067 to any number from 1 to 15.
2068 .It Cm cohort Bro 0 | 1 Brc
2069 This is a binary flag which enables (0) or disables (1)
2070 manycast server replies to manycast clients with the same
2072 This is useful to reduce implosions where
2073 large numbers of clients with the same stratum level
2075 The default is to enable these replies.
2076 .It Cm floor Ar floor
2077 Peers with strata below
2079 will be discarded if there are at least
2082 This value defaults to 1, but can be changed
2083 to any number from 1 to 15.
2084 .It Cm minclock Ar minclock
2085 The clustering algorithm repeatedly casts out outlier
2086 associations until no more than
2088 associations remain.
2089 This value defaults to 3,
2090 but can be changed to any number from 1 to the number of
2092 .It Cm minsane Ar minsane
2093 This is the minimum number of candidates available
2094 to the clock selection algorithm in order to produce
2095 one or more truechimers for the clustering algorithm.
2096 If fewer than this number are available, the clock is
2097 undisciplined and allowed to run free.
2099 for legacy purposes.
2100 However, according to principles of
2101 Byzantine agreement,
2103 should be at least 4 in order to detect and discard
2104 a single falseticker.
2106 .It Cm ttl Ar hop ...
2107 This command specifies a list of TTL values in increasing
2108 order, up to 8 values can be specified.
2109 In manycast mode these values are used in turn
2110 in an expanding\-ring search.
2111 The default is eight
2112 multiples of 32 starting at 31.
2114 .Sh Reference Clock Support
2115 The NTP Version 4 daemon supports some three dozen different radio,
2116 satellite and modem reference clocks plus a special pseudo\-clock
2117 used for backup or when no other clock source is available.
2118 Detailed descriptions of individual device drivers and options can
2120 .Qq Reference Clock Drivers
2122 (available as part of the HTML documentation
2124 .Pa /usr/share/doc/ntp ) .
2125 Additional information can be found in the pages linked
2126 there, including the
2127 .Qq Debugging Hints for Reference Clock Drivers
2129 .Qq How To Write a Reference Clock Driver
2131 (available as part of the HTML documentation
2133 .Pa /usr/share/doc/ntp ) .
2134 In addition, support for a PPS
2135 signal is available as described in the
2136 .Qq Pulse\-per\-second (PPS) Signal Interfacing
2138 (available as part of the HTML documentation
2140 .Pa /usr/share/doc/ntp ) .
2142 drivers support special line discipline/streams modules which can
2143 significantly improve the accuracy using the driver.
2146 .Qq Line Disciplines and Streams Drivers
2148 (available as part of the HTML documentation
2150 .Pa /usr/share/doc/ntp ) .
2152 A reference clock will generally (though not always) be a radio
2153 timecode receiver which is synchronized to a source of standard
2154 time such as the services offered by the NRC in Canada and NIST and
2156 The interface between the computer and the timecode
2157 receiver is device dependent, but is usually a serial port.
2159 device driver specific to each reference clock must be selected and
2160 compiled in the distribution; however, most common radio, satellite
2161 and modem clocks are included by default.
2162 Note that an attempt to
2163 configure a reference clock when the driver has not been compiled
2164 or the hardware port has not been appropriately configured results
2165 in a scalding remark to the system log file, but is otherwise non
2168 For the purposes of configuration,
2171 reference clocks in a manner analogous to normal NTP peers as much
2173 Reference clocks are identified by a syntactically
2174 correct but invalid IP address, in order to distinguish them from
2176 Reference clock addresses are of the form
2178 .Li 127.127. Ar t . Ar u ,
2183 denoting the clock type and
2186 number in the range 0\-3.
2187 While it may seem overkill, it is in fact
2188 sometimes useful to configure multiple reference clocks of the same
2189 type, in which case the unit numbers must be unique.
2193 command is used to configure a reference
2196 argument in that command
2197 is the clock address.
2203 options are not used for reference clock support.
2206 option is added for reference clock support, as
2210 option can be useful to
2211 persuade the server to cherish a reference clock with somewhat more
2212 enthusiasm than other reference clocks or peers.
2214 information on this option can be found in the
2215 .Qq Mitigation Rules and the prefer Keyword
2216 (available as part of the HTML documentation
2218 .Pa /usr/share/doc/ntp )
2225 meaning only for selected clock drivers.
2226 See the individual clock
2227 driver document pages for additional information.
2231 command is used to provide additional
2232 information for individual clock drivers and normally follows
2233 immediately after the
2238 argument specifies the clock address.
2243 options can be used to
2244 override the defaults for the device.
2245 There are two optional
2246 device\-dependent time offsets and four flags that can be included
2251 The stratum number of a reference clock is by default zero.
2254 daemon adds one to the stratum of each
2255 peer, a primary server ordinarily displays an external stratum of
2257 In order to provide engineered backups, it is often useful to
2258 specify the reference clock stratum as greater than zero.
2261 option is used for this purpose.
2263 involving both a reference clock and a pulse\-per\-second (PPS)
2264 discipline signal, it is useful to specify the reference clock
2265 identifier as other than the default, depending on the driver.
2268 option is used for this purpose.
2270 these options apply to all clock drivers.
2271 .Ss Reference Clock Commands
2272 .Bl -tag -width indent
2275 .Li 127.127. Ar t . Ar u
2279 .Op Cm minpoll Ar int
2280 .Op Cm maxpoll Ar int
2282 This command can be used to configure reference clocks in
2284 The options are interpreted as follows:
2285 .Bl -tag -width indent
2287 Marks the reference clock as preferred.
2288 All other things being
2289 equal, this host will be chosen for synchronization among a set of
2290 correctly operating hosts.
2292 .Qq Mitigation Rules and the prefer Keyword
2294 (available as part of the HTML documentation
2296 .Pa /usr/share/doc/ntp )
2297 for further information.
2299 Specifies a mode number which is interpreted in a
2300 device\-specific fashion.
2301 For instance, it selects a dialing
2302 protocol in the ACTS driver and a device subtype in the
2305 .It Cm minpoll Ar int
2306 .It Cm maxpoll Ar int
2307 These options specify the minimum and maximum polling interval
2308 for reference clock messages, as a power of 2 in seconds
2310 most directly connected reference clocks, both
2314 default to 6 (64 s).
2315 For modem reference clocks,
2317 defaults to 10 (17.1 m) and
2319 defaults to 14 (4.5 h).
2320 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2324 .Li 127.127. Ar t . Ar u
2328 .Op Cm stratum Ar int
2329 .Op Cm refid Ar string
2331 .Op Cm flag1 Cm 0 \&| Cm 1
2332 .Op Cm flag2 Cm 0 \&| Cm 1
2333 .Op Cm flag3 Cm 0 \&| Cm 1
2334 .Op Cm flag4 Cm 0 \&| Cm 1
2336 This command can be used to configure reference clocks in
2338 It must immediately follow the
2340 command which configures the driver.
2341 Note that the same capability
2342 is possible at run time using the
2343 .Xr ntpdc 1ntpdcmdoc
2345 The options are interpreted as
2347 .Bl -tag -width indent
2349 Specifies a constant to be added to the time offset produced by
2350 the driver, a fixed\-point decimal number in seconds.
2352 as a calibration constant to adjust the nominal time offset of a
2353 particular clock to agree with an external standard, such as a
2354 precision PPS signal.
2355 It also provides a way to correct a
2356 systematic error or bias due to serial port or operating system
2357 latencies, different cable lengths or receiver internal delay.
2359 specified offset is in addition to the propagation delay provided
2360 by other means, such as internal DIPswitches.
2362 for an individual system and driver is available, an approximate
2363 correction is noted in the driver documentation pages.
2364 Note: in order to facilitate calibration when more than one
2365 radio clock or PPS signal is supported, a special calibration
2366 feature is available.
2367 It takes the form of an argument to the
2369 command described in
2370 .Sx Miscellaneous Options
2371 page and operates as described in the
2372 .Qq Reference Clock Drivers
2374 (available as part of the HTML documentation
2376 .Pa /usr/share/doc/ntp ) .
2377 .It Cm time2 Ar secs
2378 Specifies a fixed\-point decimal number in seconds, which is
2379 interpreted in a driver\-dependent way.
2380 See the descriptions of
2381 specific drivers in the
2382 .Qq Reference Clock Drivers
2384 (available as part of the HTML documentation
2386 .Pa /usr/share/doc/ntp ).
2387 .It Cm stratum Ar int
2388 Specifies the stratum number assigned to the driver, an integer
2390 This number overrides the default stratum number
2391 ordinarily assigned by the driver itself, usually zero.
2392 .It Cm refid Ar string
2393 Specifies an ASCII string of from one to four characters which
2394 defines the reference identifier used by the driver.
2396 overrides the default identifier ordinarily assigned by the driver
2399 Specifies a mode number which is interpreted in a
2400 device\-specific fashion.
2401 For instance, it selects a dialing
2402 protocol in the ACTS driver and a device subtype in the
2405 .It Cm flag1 Cm 0 \&| Cm 1
2406 .It Cm flag2 Cm 0 \&| Cm 1
2407 .It Cm flag3 Cm 0 \&| Cm 1
2408 .It Cm flag4 Cm 0 \&| Cm 1
2409 These four flags are used for customizing the clock driver.
2411 interpretation of these values, and whether they are used at all,
2412 is a function of the particular clock driver.
2416 is used to enable recording monitoring
2419 file configured with the
2422 Further information on the
2424 command can be found in
2425 .Sx Monitoring Options .
2428 .Sh Miscellaneous Options
2429 .Bl -tag -width indent
2430 .It Ic broadcastdelay Ar seconds
2431 The broadcast and multicast modes require a special calibration
2432 to determine the network delay between the local and remote
2434 Ordinarily, this is done automatically by the initial
2435 protocol exchanges between the client and server.
2437 the calibration procedure may fail due to network or server access
2438 controls, for example.
2439 This command specifies the default delay to
2440 be used under these circumstances.
2441 Typically (for Ethernet), a
2442 number between 0.003 and 0.007 seconds is appropriate.
2444 when this command is not used is 0.004 seconds.
2445 .It Ic calldelay Ar delay
2446 This option controls the delay in seconds between the first and second
2447 packets sent in burst or iburst mode to allow additional time for a modem
2448 or ISDN call to complete.
2449 .It Ic driftfile Ar driftfile
2450 This command specifies the complete path and name of the file used to
2451 record the frequency of the local clock oscillator.
2455 command line option.
2456 If the file exists, it is read at
2457 startup in order to set the initial frequency and then updated once per
2458 hour with the current frequency computed by the daemon.
2460 specified, but the file itself does not exist, the starts with an initial
2461 frequency of zero and creates the file when writing it for the first time.
2462 If this command is not given, the daemon will always start with an initial
2465 The file format consists of a single line containing a single
2466 floating point number, which records the frequency offset measured
2467 in parts\-per\-million (PPM).
2468 The file is updated by first writing
2469 the current drift value into a temporary file and then renaming
2470 this file to replace the old version.
2473 must have write permission for the directory the
2474 drift file is located in, and that file system links, symbolic or
2475 otherwise, should be avoided.
2476 .It Ic dscp Ar value
2477 This option specifies the Differentiated Services Control Point (DSCP) value,
2479 The default value is 46, signifying Expedited Forwarding.
2482 .Cm auth | Cm bclient |
2483 .Cm calibrate | Cm kernel |
2484 .Cm mode7 | Cm monitor |
2485 .Cm ntp | Cm stats |
2486 .Cm peer_clear_digest_early |
2487 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
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
2500 Provides a way to enable or disable various server options.
2501 Flags not mentioned are unaffected.
2502 Note that all of these flags
2503 can be controlled remotely using the
2504 .Xr ntpdc 1ntpdcmdoc
2506 .Bl -tag -width indent
2508 Enables the server to synchronize with unconfigured peers only if the
2509 peer has been correctly authenticated using either public key or
2510 private key cryptography.
2511 The default for this flag is
2514 Enables the server to listen for a message from a broadcast or
2515 multicast server, as in the
2517 command with default
2519 The default for this flag is
2522 Enables the calibrate feature for reference clocks.
2527 Enables the kernel time discipline, if available.
2528 The default for this
2531 if support is available, otherwise
2534 Enables processing of NTP mode 7 implementation\-specific requests
2535 which are used by the deprecated
2536 .Xr ntpdc 1ntpdcmdoc
2538 The default for this flag is disable.
2539 This flag is excluded from runtime configuration using
2540 .Xr ntpq 1ntpqmdoc .
2543 program provides the same capabilities as
2544 .Xr ntpdc 1ntpdcmdoc
2545 using standard mode 6 requests.
2547 Enables the monitoring facility.
2549 .Xr ntpdc 1ntpdcmdoc
2553 command or further information.
2555 default for this flag is
2558 Enables time and frequency discipline.
2559 In effect, this switch opens and
2560 closes the feedback loop, which is useful for testing.
2564 .It Cm peer_clear_digest_early
2567 is using autokey and it
2568 receives a crypto\-NAK packet that
2569 passes the duplicate packet and origin timestamp checks
2570 the peer variables are immediately cleared.
2571 While this is generally a feature
2572 as it allows for quick recovery if a server key has changed,
2573 a properly forged and appropriately delivered crypto\-NAK packet
2574 can be used in a DoS attack.
2575 If you have active noticable problems with this type of DoS attack
2576 then you should consider
2577 disabling this option.
2580 file for evidence of any of these attacks.
2582 default for this flag is
2585 Enables the statistics facility.
2587 .Sx Monitoring Options
2588 section for further information.
2589 The default for this flag is
2591 .It Cm unpeer_crypto_early
2594 receives an autokey packet that fails TEST9,
2596 the association is immediately cleared.
2597 This is almost certainly a feature,
2598 but if, in spite of the current recommendation of not using autokey,
2603 you are seeing this sort of DoS attack
2604 disabling this flag will delay
2605 tearing down the association until the reachability counter
2609 file for evidence of any of these attacks.
2611 default for this flag is
2613 .It Cm unpeer_crypto_nak_early
2616 receives a crypto\-NAK packet that
2617 passes the duplicate packet and origin timestamp checks
2618 the association is immediately cleared.
2619 While this is generally a feature
2620 as it allows for quick recovery if a server key has changed,
2621 a properly forged and appropriately delivered crypto\-NAK packet
2622 can be used in a DoS attack.
2623 If you have active noticable problems with this type of DoS attack
2624 then you should consider
2625 disabling this option.
2628 file for evidence of any of these attacks.
2630 default for this flag is
2632 .It Cm unpeer_digest_early
2635 receives what should be an authenticated packet
2636 that passes other packet sanity checks but
2637 contains an invalid digest
2638 the association is immediately cleared.
2639 While this is generally a feature
2640 as it allows for quick recovery,
2641 if this type of packet is carefully forged and sent
2642 during an appropriate window it can be used for a DoS attack.
2643 If you have active noticable problems with this type of DoS attack
2644 then you should consider
2645 disabling this option.
2648 file for evidence of any of these attacks.
2650 default for this flag is
2653 .It Ic includefile Ar includefile
2654 This command allows additional configuration commands
2655 to be included from a separate file.
2657 be nested to a depth of five; upon reaching the end of any
2658 include file, command processing resumes in the previous
2660 This option is useful for sites that run
2662 on multiple hosts, with (mostly) common options (e.g., a
2666 .Cm listen | Cm ignore | Cm drop
2669 .Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard
2670 .Ar name | Ar address
2671 .Oo Cm / Ar prefixlen
2677 directive controls which network addresses
2679 opens, and whether input is dropped without processing.
2680 The first parameter determines the action for addresses
2681 which match the second parameter.
2682 The second parameter specifies a class of addresses,
2683 or a specific interface name,
2685 In the address case,
2687 determines how many bits must match for this rule to apply.
2689 prevents opening matching addresses,
2693 to open the address and drop all received packets without examination.
2696 directives can be used.
2697 The last rule which matches a particular address determines the action for it.
2699 directives are disabled if any
2705 command\-line options are specified in the configuration file,
2706 all available network addresses are opened.
2709 directive is an alias for
2711 .It Ic leapfile Ar leapfile
2712 This command loads the IERS leapseconds file and initializes the
2713 leapsecond values for the next leapsecond event, leapfile expiration
2714 time, and TAI offset.
2715 The file can be obtained directly from the IERS at
2716 .Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list
2718 .Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list .
2724 .Cm leapfile directive or when
2725 .Cm ntpd detects that the
2729 checks once a day to see if the
2733 .Xr update\-leap 1update_leapmdoc
2734 script can be run to see if the
2737 .It Ic leapsmearinterval Ar seconds
2738 This EXPERIMENTAL option is only available if
2741 .Cm \-\-enable\-leap\-smear
2745 It specifies the interval over which a leap second correction will be applied.
2746 Recommended values for this option are between
2747 7200 (2 hours) and 86400 (24 hours).
2748 .Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS!
2749 See http://bugs.ntp.org/2855 for more information.
2750 .It Ic logconfig Ar configkeyword
2751 This command controls the amount and type of output written to
2754 facility or the alternate
2757 By default, all output is turned on.
2760 keywords can be prefixed with
2776 messages can be controlled in four
2785 Within these classes four types of messages can be
2786 controlled: informational messages
2804 Configuration keywords are formed by concatenating the message class with
2808 prefix can be used instead of a message class.
2810 message class may also be followed by the
2812 keyword to enable/disable all
2813 messages of the respective message class.
2814 Thus, a minimal log configuration
2815 could look like this:
2817 logconfig =syncstatus +sysevents
2820 This would just list the synchronizations state of
2822 and the major system events.
2823 For a simple reference server, the
2824 following minimum message configuration could be useful:
2826 logconfig =syncall +clockall
2829 This configuration will list all clock information and
2830 synchronization information.
2831 All other events and messages about
2832 peers, system events and so on is suppressed.
2833 .It Ic logfile Ar logfile
2834 This command specifies the location of an alternate log file to
2835 be used instead of the default system
2838 This is the same operation as the
2840 command line option.
2843 .Cm maxdepth Ar count | Cm maxmem Ar kilobytes |
2844 .Cm mindepth Ar count | Cm maxage Ar seconds |
2845 .Cm initialloc Ar count | Cm initmem Ar kilobytes |
2846 .Cm incalloc Ar count | Cm incmem Ar kilobytes
2849 Controls size limite of the monitoring facility's Most Recently Used
2851 of client addresses, which is also used by the
2852 rate control facility.
2853 .Bl -tag -width indent
2854 .It Ic maxdepth Ar count
2855 .It Ic maxmem Ar kilobytes
2856 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2857 The acutal limit will be up to
2864 options offered in units of entries or kilobytes, if both
2867 .Cm maxmem are used, the last one used controls.
2868 The default is 1024 kilobytes.
2869 .It Cm mindepth Ar count
2870 Lower limit on the MRU list size.
2871 When the MRU list has fewer than
2873 entries, existing entries are never removed to make room for newer ones,
2874 regardless of their age.
2875 The default is 600 entries.
2876 .It Cm maxage Ar seconds
2877 Once the MRU list has
2879 entries and an additional client is to ba added to the list,
2880 if the oldest entry was updated more than
2882 seconds ago, that entry is removed and its storage is reused.
2883 If the oldest entry was updated more recently the MRU list is grown,
2885 .Cm maxdepth / moxmem .
2886 The default is 64 seconds.
2887 .It Cm initalloc Ar count
2888 .It Cm initmem Ar kilobytes
2889 Initial memory allocation at the time the monitoringfacility is first enabled,
2890 in terms of the number of entries or kilobytes.
2891 The default is 4 kilobytes.
2892 .It Cm incalloc Ar count
2893 .It Cm incmem Ar kilobytes
2894 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2895 The default is 4 kilobytes.
2897 .It Ic nonvolatile Ar threshold
2900 delta in seconds before an hourly change to the
2902 (frequency file) will be written, with a default value of 1e\-7 (0.1 PPM).
2903 The frequency file is inspected each hour.
2904 If the difference between the current frequency and the last value written
2905 exceeds the threshold, the file is written and the
2907 becomes the new threshold value.
2908 If the threshold is not exceeeded, it is reduced by half.
2909 This is intended to reduce the number of file writes
2910 for embedded systems with nonvolatile memory.
2911 .It Ic phone Ar dial ...
2912 This command is used in conjunction with
2913 the ACTS modem driver (type 18)
2914 or the JJY driver (type 40, mode 100 \- 180).
2915 For the ACTS modem driver (type 18), the arguments consist of
2916 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2918 For the JJY driver (type 40 mode 100 \- 180), the argument is
2919 one telephone number used to dial the telephone JJY service.
2920 The Hayes command ATDT is normally prepended to the number.
2921 The number can contain other modem control codes as well.
2945 Reset one or more groups of counters maintained by
2953 .Cm memlock Ar Nmegabytes |
2954 .Cm stacksize Ar N4kPages
2955 .Cm filenum Ar Nfiledescriptors
2958 .Bl -tag -width indent
2959 .It Cm memlock Ar Nmegabytes
2960 Specify the number of megabytes of memory that should be
2961 allocated and locked.
2962 Probably only available under Linux, this option may be useful
2963 when dropping root (the
2966 The default is 32 megabytes on non\-Linux machines, and \-1 under Linux.
2967 -1 means "do not lock the process into memory".
2968 0 means "lock whatever memory the process wants into memory".
2969 .It Cm stacksize Ar N4kPages
2970 Specifies the maximum size of the process stack on systems with the
2973 Defaults to 50 4k pages (200 4k pages in OpenBSD).
2974 .It Cm filenum Ar Nfiledescriptors
2975 Specifies the maximum number of file descriptors ntpd may have open at once.
2976 Defaults to the system default.
2978 .It Ic saveconfigdir Ar directory_path
2979 Specify the directory in which to write configuration snapshots
2986 does not appear in the configuration file,
2988 requests are rejected by
2990 .It Ic saveconfig Ar filename
2991 Write the current configuration, including any runtime
2992 modifications given with
2995 .Cm config\-from\-file
3002 This command will be rejected unless the
3004 directive appears in
3010 format directives to substitute the current date and time,
3012 .Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf .
3013 The filename used is stored in the system variable
3015 Authentication is required.
3016 .It Ic setvar Ar variable Op Cm default
3017 This command adds an additional system variable.
3019 variables can be used to distribute additional information such as
3021 If the variable of the form
3028 variable will be listed as part of the default system variables
3034 These additional variables serve
3035 informational purposes only.
3036 They are not related to the protocol
3037 other that they can be listed.
3038 The known protocol variables will
3039 always override any variables defined via the
3042 There are three special variables that contain the names
3043 of all variable of the same group.
3047 the names of all system variables.
3051 the names of all peer variables and the
3053 holds the names of the reference clock variables.
3055 Display operational summary.
3057 Show statistics counters maintained in the protocol module.
3060 .Cm allan Ar allan |
3061 .Cm dispersion Ar dispersion |
3063 .Cm huffpuff Ar huffpuff |
3064 .Cm panic Ar panic |
3066 .Cm stepback Ar stepback |
3067 .Cm stepfwd Ar stepfwd |
3068 .Cm stepout Ar stepout
3071 This command can be used to alter several system variables in
3072 very exceptional circumstances.
3073 It should occur in the
3074 configuration file before any other configuration options.
3076 default values of these variables have been carefully optimized for
3077 a wide range of network speeds and reliability expectations.
3079 general, they interact in intricate ways that are hard to predict
3080 and some combinations can result in some very nasty behavior.
3082 rarely is it necessary to change the default values; but, some
3083 folks cannot resist twisting the knobs anyway and this command is
3085 Emphasis added: twisters are on their own and can expect
3086 no help from the support group.
3088 The variables operate as follows:
3089 .Bl -tag -width indent
3090 .It Cm allan Ar allan
3091 The argument becomes the new value for the minimum Allan
3092 intercept, which is a parameter of the PLL/FLL clock discipline
3094 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
3096 .It Cm dispersion Ar dispersion
3097 The argument becomes the new value for the dispersion increase rate,
3098 normally .000015 s/s.
3100 The argument becomes the initial value of the frequency offset in
3101 parts\-per\-million.
3102 This overrides the value in the frequency file, if
3103 present, and avoids the initial training state if it is not.
3104 .It Cm huffpuff Ar huffpuff
3105 The argument becomes the new value for the experimental
3106 huff\-n'\-puff filter span, which determines the most recent interval
3107 the algorithm will search for a minimum delay.
3109 900 s (15 m), but a more reasonable value is 7200 (2 hours).
3111 is no default, since the filter is not enabled unless this command
3113 .It Cm panic Ar panic
3114 The argument is the panic threshold, normally 1000 s.
3116 the panic sanity check is disabled and a clock offset of any value will
3119 The argument is the step threshold, which by default is 0.128 s.
3121 be set to any positive number in seconds.
3122 If set to zero, step
3123 adjustments will never occur.
3124 Note: The kernel time discipline is
3125 disabled if the step threshold is set to zero or greater than the
3127 .It Cm stepback Ar stepback
3128 The argument is the step threshold for the backward direction,
3129 which by default is 0.128 s.
3131 be set to any positive number in seconds.
3132 If both the forward and backward step thresholds are set to zero, step
3133 adjustments will never occur.
3134 Note: The kernel time discipline is
3136 each direction of step threshold are either
3137 set to zero or greater than .5 second.
3138 .It Cm stepfwd Ar stepfwd
3139 As for stepback, but for the forward direction.
3140 .It Cm stepout Ar stepout
3141 The argument is the stepout timeout, which by default is 900 s.
3143 be set to any positive number in seconds.
3144 If set to zero, the stepout
3145 pulses will not be suppressed.
3147 .It Cm writevar Ar assocID\ name = value [,...]
3148 Write (create or update) the specified variables.
3151 is zero, the variablea re from the
3153 name space, otherwise they are from the
3158 is required, as the same name can occur in both name spaces.
3159 .It Xo Ic trap Ar host_address
3160 .Op Cm port Ar port_number
3161 .Op Cm interface Ar interface_address
3163 This command configures a trap receiver at the given host
3164 address and port number for sending messages with the specified
3165 local interface address.
3166 If the port number is unspecified, a value
3168 If the interface address is not specified, the
3169 message is sent with a source address of the local interface the
3170 message is sent through.
3171 Note that on a multihomed host the
3172 interface used may vary from time to time with routing changes.
3173 .It Cm ttl Ar hop ...
3174 This command specifies a list of TTL values in increasing order.
3175 Up to 8 values can be specified.
3178 mode these values are used in\-turn in an expanding\-ring search.
3179 The default is eight multiples of 32 starting at 31.
3181 The trap receiver will generally log event messages and other
3182 information from the server in a log file.
3184 programs may also request their own trap dynamically, configuring a
3185 trap receiver will ensure that no messages are lost when the server
3188 This command specifies a list of TTL values in increasing order, up to 8
3189 values can be specified.
3190 In manycast mode these values are used in turn in
3191 an expanding\-ring search.
3192 The default is eight multiples of 32 starting at
3198 Display usage information and exit.
3200 Pass the extended usage information through a pager.
3201 .It Fl \-version Op Brq Ar v|c|n
3202 Output version of program and exit. The default mode is `v', a simple
3203 version. The `c' mode will print copyright information and `n' will
3204 print the full copyright notice.
3206 .Sh "OPTION PRESETS"
3207 Any option that is not marked as \fInot presettable\fP may be preset
3208 by loading values from environment variables named:
3210 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP
3214 See \fBOPTION PRESETS\fP for configuration environment variables.
3216 .Bl -tag -width /etc/ntp.drift -compact
3217 .It Pa /etc/ntp.conf
3218 the default name of the configuration file
3223 .It Pa ntpkey_ Ns Ar host
3226 Diffie\-Hellman agreement parameters
3229 One of the following exit values will be returned:
3231 .It 0 " (EXIT_SUCCESS)"
3232 Successful program execution.
3233 .It 1 " (EXIT_FAILURE)"
3234 The operation failed or the command syntax was not valid.
3235 .It 70 " (EX_SOFTWARE)"
3236 libopts had an internal operational error. Please report
3237 it to autogen\-users@lists.sourceforge.net. Thank you.
3240 .Xr ntpd 1ntpdmdoc ,
3241 .Xr ntpdc 1ntpdcmdoc ,
3244 In addition to the manual pages provided,
3245 comprehensive documentation is available on the world wide web
3247 .Li http://www.ntp.org/ .
3248 A snapshot of this documentation is available in HTML format in
3249 .Pa /usr/share/doc/ntp .
3252 .%T Network Time Protocol (Version 4)
3256 The University of Delaware and Network Time Foundation
3258 Copyright (C) 1992\-2017 The University of Delaware and Network Time Foundation all rights reserved.
3259 This program is released under the terms of the NTP license, <http://ntp.org/license>.
3261 The syntax checking is not picky; some combinations of
3262 ridiculous and even hilarious options and modes may not be
3266 .Pa ntpkey_ Ns Ar host
3267 files are really digital
3269 These should be obtained via secure directory
3270 services when they become universally available.
3272 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
3274 This document was derived from FreeBSD.
3276 This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP