1 /* -*- Mode: Text -*- */
3 autogen definitions options;
7 // We want the synopsis to be "/etc/ntp.conf" but we need the prog-name
8 // to be ntp.conf - the latter is also how autogen produces the output
10 prog-name = "ntp.conf";
11 file-path = "/etc/ntp.conf";
12 prog-title = "Network Time Protocol (NTP) daemon configuration file format";
14 /* explain: Additional information whenever the usage routine is invoked */
15 explain = <<- _END_EXPLAIN
19 ds-type = 'DESCRIPTION';
21 ds-text = <<- _END_PROG_MDOC_DESCRIP
24 configuration file is read at initial startup by the
26 daemon in order to specify the synchronization sources,
27 modes and other related information.
28 Usually, it is installed in the
31 but could be installed elsewhere
36 The file format is similar to other
41 character and extend to the end of the line;
42 blank lines are ignored.
43 Configuration commands consist of an initial keyword
44 followed by a list of arguments,
45 some of which may be optional, separated by whitespace.
46 Commands may not be continued over multiple lines.
47 Arguments may be host names,
48 host addresses written in numeric, dotted-quad form,
49 integers, floating point numbers (when specifying times in seconds)
52 The rest of this page describes the configuration and control options.
54 .Qq Notes on Configuring NTP and Setting up an NTP Subnet
56 (available as part of the HTML documentation
58 .Pa /usr/share/doc/ntp )
59 contains an extended discussion of these options.
60 In addition to the discussion of general
61 .Sx Configuration Options ,
62 there are sections describing the following supported functionality
63 and the options used to control it:
64 .Bl -bullet -offset indent
66 .Sx Authentication Support
68 .Sx Monitoring Support
70 .Sx Access Control Support
72 .Sx Automatic NTP Configuration Options
74 .Sx Reference Clock Support
76 .Sx Miscellaneous Options
79 Following these is a section describing
80 .Sx Miscellaneous Options .
81 While there is a rich set of options available,
82 the only required option is one or more
90 .Sh Configuration Support
91 Following is a description of the configuration commands in
93 These commands have the same basic functions as in NTPv3 and
94 in some cases new functions and new arguments.
96 classes of commands, configuration commands that configure a
97 persistent association with a remote server or peer or reference
98 clock, and auxiliary commands that specify environmental variables
99 that control various related operations.
100 .Ss Configuration Commands
101 The various modes are determined by the command keyword and the
102 type of the required IP address.
103 Addresses are classed by type as
104 (s) a remote server or peer (IPv4 class A, B and C), (b) the
105 broadcast address of a local interface, (m) a multicast address (IPv4
106 class D), or (r) a reference clock address (127.127.x.x).
108 only those options applicable to each command are listed below.
110 of options not listed may not be caught as an error, but may result
111 in some weird and even destructive behavior.
113 If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
114 is detected, support for the IPv6 address family is generated
115 in addition to the default support of the IPv4 address family.
116 In a few cases, including the
122 .Xr ntpdc 1ntpdcmdoc ,
123 IPv6 addresses are automatically generated.
124 IPv6 addresses can be identified by the presence of colons
126 in the address field.
127 IPv6 addresses can be used almost everywhere where
128 IPv4 addresses can be used,
129 with the exception of reference clock addresses,
130 which are always IPv4.
132 Note that in contexts where a host name is expected, a
135 the host name forces DNS resolution to the IPv4 namespace,
138 qualifier forces DNS resolution to the IPv6 namespace.
139 See IPv6 references for the
140 equivalent classes for that address family.
141 .Bl -tag -width indent
142 .It Xo Ic pool Ar address
145 .Op Cm version Ar version
147 .Op Cm minpoll Ar minpoll
148 .Op Cm maxpoll Ar maxpoll
151 .It Xo Ic server Ar address
152 .Op Cm key Ar key \&| Cm autokey
155 .Op Cm version Ar version
157 .Op Cm minpoll Ar minpoll
158 .Op Cm maxpoll Ar maxpoll
162 .It Xo Ic peer Ar address
163 .Op Cm key Ar key \&| Cm autokey
164 .Op Cm version Ar version
166 .Op Cm minpoll Ar minpoll
167 .Op Cm maxpoll Ar maxpoll
171 .It Xo Ic broadcast Ar address
172 .Op Cm key Ar key \&| Cm autokey
173 .Op Cm version Ar version
175 .Op Cm minpoll Ar minpoll
179 .It Xo Ic manycastclient Ar address
180 .Op Cm key Ar key \&| Cm autokey
181 .Op Cm version Ar version
183 .Op Cm minpoll Ar minpoll
184 .Op Cm maxpoll Ar maxpoll
189 These five commands specify the time server name or address to
190 be used and the mode in which to operate.
194 either a DNS name or an IP address in dotted-quad notation.
195 Additional information on association behavior can be found in the
196 .Qq Association Management
198 (available as part of the HTML documentation
200 .Pa /usr/share/doc/ntp ) .
201 .Bl -tag -width indent
203 For type s addresses, this command mobilizes a persistent
204 client mode association with a number of remote servers.
205 In this mode the local clock can synchronized to the
206 remote server, but the remote server can never be synchronized to
209 For type s and r addresses, this command mobilizes a persistent
210 client mode association with the specified remote server or local
212 In this mode the local clock can synchronized to the
213 remote server, but the remote server can never be synchronized to
220 For type s addresses (only), this command mobilizes a
221 persistent symmetric-active mode association with the specified
223 In this mode the local clock can be synchronized to
224 the remote peer or the remote peer can be synchronized to the local
226 This is useful in a network of servers where, depending on
227 various failure scenarios, either the local or remote peer may be
228 the better source of time.
229 This command should NOT be used for type
232 For type b and m addresses (only), this
233 command mobilizes a persistent broadcast mode association.
235 commands can be used to specify multiple local broadcast interfaces
236 (subnets) and/or multiple multicast groups.
238 broadcast messages go only to the interface associated with the
239 subnet specified, but multicast messages go to all interfaces.
240 In broadcast mode the local server sends periodic broadcast
241 messages to a client population at the
243 specified, which is usually the broadcast address on (one of) the
244 local network(s) or a multicast address assigned to NTP.
246 has assigned the multicast group address IPv4 224.0.1.1 and
247 IPv6 ff05::101 (site local) exclusively to
248 NTP, but other nonconflicting addresses can be used to contain the
249 messages within administrative boundaries.
251 specification applies only to the local server operating as a
252 sender; for operation as a broadcast client, see the
258 .It Ic manycastclient
259 For type m addresses (only), this command mobilizes a
260 manycast client mode association for the multicast address
262 In this case a specific address must be supplied which
263 matches the address used on the
266 the designated manycast servers.
267 The NTP multicast address
268 224.0.1.1 assigned by the IANA should NOT be used, unless specific
269 means are taken to avoid spraying large areas of the Internet with
270 these messages and causing a possibly massive implosion of replies
274 command specifies that the local server
275 is to operate in client mode with the remote servers that are
276 discovered as the result of broadcast/multicast messages.
278 client broadcasts a request message to the group address associated
281 and specifically enabled
282 servers respond to these messages.
283 The client selects the servers
284 providing the best time and continues as with the
287 The remaining servers are discarded as if never
292 .Bl -tag -width indent
294 All packets sent to and received from the server or peer are to
295 include authentication fields encrypted using the autokey scheme
297 .Sx Authentication Options .
299 when the server is reachable, send a burst of eight packets
300 instead of the usual one.
301 The packet spacing is normally 2 s;
302 however, the spacing between the first and second packets
303 can be changed with the
306 additional time for a modem or ISDN call to complete.
307 This is designed to improve timekeeping quality
310 command and s addresses.
312 When the server is unreachable, send a burst of eight packets
313 instead of the usual one.
314 The packet spacing is normally 2 s;
315 however, the spacing between the first two packets can be
319 additional time for a modem or ISDN call to complete.
320 This is designed to speed the initial synchronization
323 command and s addresses and when
329 All packets sent to and received from the server or peer are to
330 include authentication fields encrypted using the specified
332 identifier with values from 1 to 65535, inclusive.
334 default is to include no encryption field.
335 .It Cm minpoll Ar minpoll
336 .It Cm maxpoll Ar maxpoll
337 These options specify the minimum and maximum poll intervals
338 for NTP messages, as a power of 2 in seconds
340 interval defaults to 10 (1,024 s), but can be increased by the
342 option to an upper limit of 17 (36.4 h).
344 minimum poll interval defaults to 6 (64 s), but can be decreased by
347 option to a lower limit of 4 (16 s).
349 Marks the server as unused, except for display purposes.
350 The server is discarded by the selection algroithm.
352 Says the association can be preempted.
354 Marks the server as preferred.
355 All other things being equal,
356 this host will be chosen for synchronization among a set of
357 correctly operating hosts.
359 .Qq Mitigation Rules and the prefer Keyword
361 (available as part of the HTML documentation
363 .Pa /usr/share/doc/ntp )
364 for further information.
366 Marks the server as a truechimer,
367 forcing the association to always survive the selection and clustering algorithms.
368 This option should almost certainly
370 be used while testing an association.
372 This option is used only with broadcast server and manycast
374 It specifies the time-to-live
377 use on broadcast server and multicast server and the maximum
379 for the expanding ring search with manycast
381 Selection of the proper value, which defaults to
382 127, is something of a black art and should be coordinated with the
383 network administrator.
384 .It Cm version Ar version
385 Specifies the version number to be used for outgoing NTP
387 Versions 1-4 are the choices, with version 4 the
394 modes only, this flag enables interleave mode.
400 modes, this flag puts a random number in the packet's transmit timestamp.
403 .Ss Auxiliary Commands
404 .Bl -tag -width indent
405 .It Ic broadcastclient
406 This command enables reception of broadcast server messages to
407 any local interface (type b) address.
408 Upon receiving a message for
409 the first time, the broadcast client measures the nominal server
410 propagation delay using a brief client/server exchange with the
411 server, then enters the broadcast client mode, in which it
412 synchronizes to succeeding broadcast messages.
414 to avoid accidental or malicious disruption in this mode, both the
415 server and client should operate using symmetric-key or public-key
416 authentication as described in
417 .Sx Authentication Options .
418 .It Ic manycastserver Ar address ...
419 This command enables reception of manycast client messages to
420 the multicast group address(es) (type m) specified.
422 address is required, but the NTP multicast address 224.0.1.1
423 assigned by the IANA should NOT be used, unless specific means are
424 taken to limit the span of the reply and avoid a possibly massive
425 implosion at the original sender.
426 Note that, in order to avoid
427 accidental or malicious disruption in this mode, both the server
428 and client should operate using symmetric-key or public-key
429 authentication as described in
430 .Sx Authentication Options .
431 .It Ic multicastclient Ar address ...
432 This command enables reception of multicast server messages to
433 the multicast group address(es) (type m) specified.
435 a message for the first time, the multicast client measures the
436 nominal server propagation delay using a brief client/server
437 exchange with the server, then enters the broadcast client mode, in
438 which it synchronizes to succeeding multicast messages.
440 in order to avoid accidental or malicious disruption in this mode,
441 both the server and client should operate using symmetric-key or
442 public-key authentication as described in
443 .Sx Authentication Options .
444 .It Ic mdnstries Ar number
445 If we are participating in mDNS,
446 after we have synched for the first time
447 we attempt to register with the mDNS system.
448 If that registration attempt fails,
449 we try again at one minute intervals for up to
454 may be starting before mDNS.
455 The default value for
459 .Sh Authentication Support
460 Authentication support allows the NTP client to verify that the
461 server is in fact known and trusted and not an intruder intending
462 accidentally or on purpose to masquerade as that server.
464 specification RFC-1305 defines a scheme which provides
465 cryptographic authentication of received NTP packets.
467 this was done using the Data Encryption Standard (DES) algorithm
468 operating in Cipher Block Chaining (CBC) mode, commonly called
470 Subsequently, this was replaced by the RSA Message Digest
471 5 (MD5) algorithm using a private key, commonly called keyed-MD5.
472 Either algorithm computes a message digest, or one-way hash, which
473 can be used to verify the server has the correct private key and
476 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
477 cryptography and, in addition, provides a new Autokey scheme
478 based on public key cryptography.
479 Public key cryptography is generally considered more secure
480 than symmetric key cryptography, since the security is based
481 on a private value which is generated by each server and
483 With Autokey all key distribution and
484 management functions involve only public values, which
485 considerably simplifies key distribution and storage.
486 Public key management is based on X.509 certificates,
487 which can be provided by commercial services or
488 produced by utility programs in the OpenSSL software library
489 or the NTPv4 distribution.
491 While the algorithms for symmetric key cryptography are
492 included in the NTPv4 distribution, public key cryptography
493 requires the OpenSSL software library to be installed
494 before building the NTP distribution.
495 Directions for doing that
496 are on the Building and Installing the Distribution page.
498 Authentication is configured separately for each association
509 configuration commands as described in
510 .Sx Configuration Options
513 options described below specify the locations of the key files,
514 if other than default, which symmetric keys are trusted
515 and the interval between various operations, if other than default.
517 Authentication is always enabled,
518 although ineffective if not configured as
520 If a NTP packet arrives
521 including a message authentication
522 code (MAC), it is accepted only if it
523 passes all cryptographic checks.
525 checks require correct key ID, key value
528 been modified in any way or replayed
529 by an intruder, it will fail one or more
530 of these checks and be discarded.
531 Furthermore, the Autokey scheme requires a
532 preliminary protocol exchange to obtain
533 the server certificate, verify its
534 credentials and initialize the protocol
538 flag controls whether new associations or
539 remote configuration commands require cryptographic authentication.
540 This flag can be set or reset by the
544 commands and also by remote
545 configuration commands sent by a
549 If this flag is enabled, which is the default
550 case, new broadcast client and symmetric passive associations and
551 remote configuration commands must be cryptographically
552 authenticated using either symmetric key or public key cryptography.
554 flag is disabled, these operations are effective
555 even if not cryptographic
557 It should be understood
558 that operating with the
560 flag disabled invites a significant vulnerability
561 where a rogue hacker can
562 masquerade as a falseticker and seriously
563 disrupt system timekeeping.
565 important to note that this flag has no purpose
566 other than to allow or disallow
567 a new association in response to new broadcast
568 and symmetric active messages
569 and remote configuration commands and, in particular,
570 the flag has no effect on
571 the authentication process itself.
573 An attractive alternative where multicast support is available
574 is manycast mode, in which clients periodically troll
575 for servers as described in the
576 .Sx Automatic NTP Configuration Options
578 Either symmetric key or public key
579 cryptographic authentication can be used in this mode.
580 The principle advantage
581 of manycast mode is that potential servers need not be
582 configured in advance,
583 since the client finds them during regular operation,
584 and the configuration
585 files for all clients can be identical.
587 The security model and protocol schemes for
588 both symmetric key and public key
589 cryptography are summarized below;
590 further details are in the briefings, papers
591 and reports at the NTP project page linked from
592 .Li http://www.ntp.org/ .
593 .Ss Symmetric-Key Cryptography
594 The original RFC-1305 specification allows any one of possibly
595 65,535 keys, each distinguished by a 32-bit key identifier, to
596 authenticate an association.
597 The servers and clients involved must
598 agree on the key and key identifier to
599 authenticate NTP packets.
601 related information are specified in a key
604 which must be distributed and stored using
605 secure means beyond the scope of the NTP protocol itself.
606 Besides the keys used
607 for ordinary NTP associations,
608 additional keys can be used as passwords for the
616 is first started, it reads the key file specified in the
618 configuration command and installs the keys
621 individual keys must be activated with the
625 allows, for instance, the installation of possibly
626 several batches of keys and
627 then activating or deactivating each batch
629 .Xr ntpdc 1ntpdcmdoc .
630 This also provides a revocation capability that can be used
631 if a key becomes compromised.
634 command selects the key used as the password for the
638 command selects the key used as the password for the
641 .Ss Public Key Cryptography
642 NTPv4 supports the original NTPv3 symmetric key scheme
643 described in RFC-1305 and in addition the Autokey protocol,
644 which is based on public key cryptography.
645 The Autokey Version 2 protocol described on the Autokey Protocol
646 page verifies packet integrity using MD5 message digests
647 and verifies the source with digital signatures and any of several
648 digest/signature schemes.
649 Optional identity schemes described on the Identity Schemes
650 page and based on cryptographic challenge/response algorithms
652 Using all of these schemes provides strong security against
653 replay with or without modification, spoofing, masquerade
654 and most forms of clogging attacks.
656 .\" The cryptographic means necessary for all Autokey operations
657 .\" is provided by the OpenSSL software library.
658 .\" This library is available from http://www.openssl.org/
659 .\" and can be installed using the procedures outlined
660 .\" in the Building and Installing the Distribution page.
662 .\" the configure and build
663 .\" process automatically detects the library and links
664 .\" the library routines required.
666 The Autokey protocol has several modes of operation
667 corresponding to the various NTP modes supported.
668 Most modes use a special cookie which can be
669 computed independently by the client and server,
670 but encrypted in transmission.
671 All modes use in addition a variant of the S-KEY scheme,
672 in which a pseudo-random key list is generated and used
674 These schemes are described along with an executive summary,
675 current status, briefing slides and reading list on the
676 .Sx Autonomous Authentication
679 The specific cryptographic environment used by Autokey servers
680 and clients is determined by a set of files
681 and soft links generated by the
682 .Xr ntp-keygen 1ntpkeygenmdoc
684 This includes a required host key file,
685 required certificate file and optional sign key file,
686 leapsecond file and identity scheme files.
688 digest/signature scheme is specified in the X.509 certificate
689 along with the matching sign key.
690 There are several schemes
691 available in the OpenSSL software library, each identified
692 by a specific string such as
693 .Cm md5WithRSAEncryption ,
694 which stands for the MD5 message digest with RSA
696 The current NTP distribution supports
697 all the schemes in the OpenSSL library, including
698 those based on RSA and DSA digital signatures.
700 NTP secure groups can be used to define cryptographic compartments
701 and security hierarchies.
702 It is important that every host
703 in the group be able to construct a certificate trail to one
704 or more trusted hosts in the same group.
706 host runs the Autokey protocol to obtain the certificates
707 for all hosts along the trail to one or more trusted hosts.
708 This requires the configuration file in all hosts to be
709 engineered so that, even under anticipated failure conditions,
710 the NTP subnet will form such that every group host can find
711 a trail to at least one trusted host.
712 .Ss Naming and Addressing
713 It is important to note that Autokey does not use DNS to
714 resolve addresses, since DNS can't be completely trusted
715 until the name servers have synchronized clocks.
716 The cryptographic name used by Autokey to bind the host identity
717 credentials and cryptographic values must be independent
718 of interface, network and any other naming convention.
719 The name appears in the host certificate in either or both
720 the subject and issuer fields, so protection against
721 DNS compromise is essential.
723 By convention, the name of an Autokey host is the name returned
726 system call or equivalent in other systems.
728 model, there are no provisions to allow alternate names or aliases.
729 However, this is not to say that DNS aliases, different names
730 for each interface, etc., are constrained in any way.
732 It is also important to note that Autokey verifies authenticity
733 using the host name, network address and public keys,
734 all of which are bound together by the protocol specifically
735 to deflect masquerade attacks.
736 For this reason Autokey
737 includes the source and destination IP addresses in message digest
738 computations and so the same addresses must be available
739 at both the server and client.
740 For this reason operation
741 with network address translation schemes is not possible.
742 This reflects the intended robust security model where government
743 and corporate NTP servers are operated outside firewall perimeters.
745 A specific combination of authentication scheme (none,
746 symmetric key, public key) and identity scheme is called
747 a cryptotype, although not all combinations are compatible.
748 There may be management configurations where the clients,
749 servers and peers may not all support the same cryptotypes.
750 A secure NTPv4 subnet can be configured in many ways while
751 keeping in mind the principles explained above and
753 Note however that some cryptotype
754 combinations may successfully interoperate with each other,
755 but may not represent good security practice.
757 The cryptotype of an association is determined at the time
758 of mobilization, either at configuration time or some time
759 later when a message of appropriate cryptotype arrives.
764 configuration command and no
768 subcommands are present, the association is not
769 authenticated; if the
771 subcommand is present, the association is authenticated
772 using the symmetric key ID specified; if the
774 subcommand is present, the association is authenticated
777 When multiple identity schemes are supported in the Autokey
778 protocol, the first message exchange determines which one is used.
779 The client request message contains bits corresponding
780 to which schemes it has available.
781 The server response message
782 contains bits corresponding to which schemes it has available.
783 Both server and client match the received bits with their own
784 and select a common scheme.
786 Following the principle that time is a public value,
787 a server responds to any client packet that matches
788 its cryptotype capabilities.
789 Thus, a server receiving
790 an unauthenticated packet will respond with an unauthenticated
791 packet, while the same server receiving a packet of a cryptotype
792 it supports will respond with packets of that cryptotype.
793 However, unconfigured broadcast or manycast client
794 associations or symmetric passive associations will not be
795 mobilized unless the server supports a cryptotype compatible
796 with the first packet received.
797 By default, unauthenticated associations will not be mobilized
798 unless overridden in a decidedly dangerous way.
800 Some examples may help to reduce confusion.
801 Client Alice has no specific cryptotype selected.
802 Server Bob has both a symmetric key file and minimal Autokey files.
803 Alice's unauthenticated messages arrive at Bob, who replies with
804 unauthenticated messages.
805 Cathy has a copy of Bob's symmetric
806 key file and has selected key ID 4 in messages to Bob.
807 Bob verifies the message with his key ID 4.
809 same key and the message is verified, Bob sends Cathy a reply
810 authenticated with that key.
811 If verification fails,
812 Bob sends Cathy a thing called a crypto-NAK, which tells her
814 She can see the evidence using the
818 Denise has rolled her own host key and certificate.
819 She also uses one of the identity schemes as Bob.
820 She sends the first Autokey message to Bob and they
821 both dance the protocol authentication and identity steps.
822 If all comes out okay, Denise and Bob continue as described above.
824 It should be clear from the above that Bob can support
825 all the girls at the same time, as long as he has compatible
826 authentication and identity credentials.
827 Now, Bob can act just like the girls in his own choice of servers;
828 he can run multiple configured associations with multiple different
829 servers (or the same server, although that might not be useful).
830 But, wise security policy might preclude some cryptotype
831 combinations; for instance, running an identity scheme
832 with one server and no authentication with another might not be wise.
834 The cryptographic values used by the Autokey protocol are
835 incorporated as a set of files generated by the
836 .Xr ntp-keygen 1ntpkeygenmdoc
837 utility program, including symmetric key, host key and
838 public certificate files, as well as sign key, identity parameters
839 and leapseconds files.
840 Alternatively, host and sign keys and
841 certificate files can be generated by the OpenSSL utilities
842 and certificates can be imported from public certificate
844 Note that symmetric keys are necessary for the
849 The remaining files are necessary only for the
852 Certificates imported from OpenSSL or public certificate
853 authorities have certian limitations.
854 The certificate should be in ASN.1 syntax, X.509 Version 3
855 format and encoded in PEM, which is the same format
857 The overall length of the certificate encoded
858 in ASN.1 must not exceed 1024 bytes.
859 The subject distinguished
860 name field (CN) is the fully qualified name of the host
861 on which it is used; the remaining subject fields are ignored.
862 The certificate extension fields must not contain either
863 a subject key identifier or a issuer key identifier field;
864 however, an extended key usage field for a trusted host must
867 Other extension fields are ignored.
868 .Ss Authentication Commands
869 .Bl -tag -width indent
870 .It Ic autokey Op Ar logsec
871 Specifies the interval between regenerations of the session key
872 list used with the Autokey protocol.
873 Note that the size of the key
874 list for each association depends on this interval and the current
876 The default value is 12 (4096 s or about 1.1 hours).
877 For poll intervals above the specified interval, a session key list
878 with a single entry will be regenerated for every message
880 .It Ic controlkey Ar key
881 Specifies the key identifier to use with the
883 utility, which uses the standard
884 protocol defined in RFC-1305.
888 the key identifier for a trusted key, where the value can be in the
889 range 1 to 65,535, inclusive.
893 .Op Cm randfile Ar file
898 .Op Cm iffpar Ar file
900 .Op Cm pw Ar password
902 This command requires the OpenSSL library.
903 It activates public key
904 cryptography, selects the message digest and signature
905 encryption scheme and loads the required private and public
906 values described above.
907 If one or more files are left unspecified,
908 the default names are used as described above.
909 Unless the complete path and name of the file are specified, the
910 location of a file is relative to the keys directory specified
915 Following are the subcommands:
916 .Bl -tag -width indent
918 Specifies the location of the required host public certificate file.
919 This overrides the link
920 .Pa ntpkey_cert_ Ns Ar hostname
921 in the keys directory.
923 Specifies the location of the optional GQ parameters file.
926 .Pa ntpkey_gq_ Ns Ar hostname
927 in the keys directory.
929 Specifies the location of the required host key file.
932 .Pa ntpkey_key_ Ns Ar hostname
933 in the keys directory.
934 .It Cm iffpar Ar file
935 Specifies the location of the optional IFF parameters file.
936 This overrides the link
937 .Pa ntpkey_iff_ Ns Ar hostname
938 in the keys directory.
940 Specifies the location of the optional leapsecond file.
941 This overrides the link
943 in the keys directory.
945 Specifies the location of the optional MV parameters file.
946 This overrides the link
947 .Pa ntpkey_mv_ Ns Ar hostname
948 in the keys directory.
949 .It Cm pw Ar password
950 Specifies the password to decrypt files containing private keys and
952 This is required only if these files have been
954 .It Cm randfile Ar file
955 Specifies the location of the random seed file used by the OpenSSL
957 The defaults are described in the main text above.
959 Specifies the location of the optional sign key file.
962 .Pa ntpkey_sign_ Ns Ar hostname
963 in the keys directory.
965 not found, the host key is also the sign key.
967 .It Ic keys Ar keyfile
968 Specifies the complete path and location of the MD5 key file
969 containing the keys and key identifiers used by
974 when operating with symmetric key cryptography.
975 This is the same operation as the
978 .It Ic keysdir Ar path
979 This command specifies the default directory path for
980 cryptographic keys, parameters and certificates.
982 .Pa /usr/local/etc/ .
983 .It Ic requestkey Ar key
984 Specifies the key identifier to use with the
986 utility program, which uses a
987 proprietary protocol specific to this implementation of
991 argument is a key identifier
992 for the trusted key, where the value can be in the range 1 to
994 .It Ic revoke Ar logsec
995 Specifies the interval between re-randomization of certain
996 cryptographic values used by the Autokey scheme, as a power of 2 in
998 These values need to be updated frequently in order to
999 deflect brute-force attacks on the algorithms of the scheme;
1000 however, updating some values is a relatively expensive operation.
1001 The default interval is 16 (65,536 s or about 18 hours).
1003 intervals above the specified interval, the values will be updated
1004 for every message sent.
1005 .It Ic trustedkey Ar key ...
1006 Specifies the key identifiers which are trusted for the
1007 purposes of authenticating peers with symmetric key cryptography,
1008 as well as keys used by the
1011 .Xr ntpdc 1ntpdcmdoc
1013 The authentication procedures require that both the local
1014 and remote servers share the same key and key identifier for this
1015 purpose, although different keys can be used with different
1019 arguments are 32-bit unsigned
1020 integers with values from 1 to 65,535.
1023 The following error codes are reported via the NTP control
1024 and monitoring protocol trap mechanism.
1025 .Bl -tag -width indent
1027 .Pq bad field format or length
1028 The packet has invalid version, length or format.
1031 The packet timestamp is the same or older than the most recent received.
1032 This could be due to a replay or a server clock time step.
1035 The packet filestamp is the same or older than the most recent received.
1036 This could be due to a replay or a key file generation error.
1038 .Pq bad or missing public key
1039 The public key is missing, has incorrect format or is an unsupported type.
1041 .Pq unsupported digest type
1042 The server requires an unsupported digest/signature scheme.
1044 .Pq mismatched digest types
1047 .Pq bad signature length
1048 The signature length does not match the current public key.
1050 .Pq signature not verified
1051 The message fails the signature check.
1052 It could be bogus or signed by a
1053 different private key.
1055 .Pq certificate not verified
1056 The certificate is invalid or signed with the wrong key.
1058 .Pq certificate not verified
1059 The certificate is not yet valid or has expired or the signature could not
1062 .Pq bad or missing cookie
1063 The cookie is missing, corrupted or bogus.
1065 .Pq bad or missing leapseconds table
1066 The leapseconds table is missing, corrupted or bogus.
1068 .Pq bad or missing certificate
1069 The certificate is missing, corrupted or bogus.
1071 .Pq bad or missing identity
1072 The identity key is missing, corrupt or bogus.
1074 .Sh Monitoring Support
1076 includes a comprehensive monitoring facility suitable
1077 for continuous, long term recording of server and client
1078 timekeeping performance.
1082 for a listing and example of each type of statistics currently
1084 Statistic files are managed using file generation sets
1087 directory of the source code distribution.
1089 these facilities and
1092 jobs, the data can be
1093 automatically summarized and archived for retrospective analysis.
1094 .Ss Monitoring Commands
1095 .Bl -tag -width indent
1096 .It Ic statistics Ar name ...
1097 Enables writing of statistics records.
1098 Currently, eight kinds of
1100 statistics are supported.
1101 .Bl -tag -width indent
1103 Enables recording of clock driver statistics information.
1105 received from a clock driver appends a line of the following form to
1106 the file generation set named
1109 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1112 The first two fields show the date (Modified Julian Day) and time
1113 (seconds and fraction past UTC midnight).
1114 The next field shows the
1115 clock address in dotted-quad notation.
1116 The final field shows the last
1117 timecode received from the clock in decoded ASCII format, where
1119 In some clock drivers a good deal of additional information
1120 can be gathered and displayed as well.
1121 See information specific to each
1122 clock for further details.
1124 This option requires the OpenSSL cryptographic software library.
1126 enables recording of cryptographic public key protocol information.
1127 Each message received by the protocol module appends a line of the
1128 following form to the file generation set named
1131 49213 525.624 127.127.4.1 message
1134 The first two fields show the date (Modified Julian Day) and time
1135 (seconds and fraction past UTC midnight).
1136 The next field shows the peer
1137 address in dotted-quad notation, The final message field includes the
1138 message type and certain ancillary information.
1140 .Sx Authentication Options
1141 section for further information.
1143 Enables recording of loop filter statistics information.
1145 update of the local clock outputs a line of the following form to
1146 the file generation set named
1149 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1152 The first two fields show the date (Modified Julian Day) and
1153 time (seconds and fraction past UTC midnight).
1154 The next five fields
1155 show time offset (seconds), frequency offset (parts per million -
1156 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1157 discipline time constant.
1159 Enables recording of peer statistics information.
1161 statistics records of all peers of a NTP server and of special
1162 signals, where present and configured.
1163 Each valid update appends a
1164 line of the following form to the current element of a file
1165 generation set named
1168 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
1171 The first two fields show the date (Modified Julian Day) and
1172 time (seconds and fraction past UTC midnight).
1174 show the peer address in dotted-quad notation and status,
1176 The status field is encoded in hex in the format
1177 described in Appendix A of the NTP specification RFC 1305.
1178 The final four fields show the offset,
1179 delay, dispersion and RMS jitter, all in seconds.
1181 Enables recording of raw-timestamp statistics information.
1183 includes statistics records of all peers of a NTP server and of
1184 special signals, where present and configured.
1186 received from a peer or clock driver appends a line of the
1187 following form to the file generation set named
1190 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1193 The first two fields show the date (Modified Julian Day) and
1194 time (seconds and fraction past UTC midnight).
1196 show the remote peer or clock address followed by the local address
1197 in dotted-quad notation.
1198 The final four fields show the originate,
1199 receive, transmit and final NTP timestamps in order.
1201 values are as received and before processing by the various data
1202 smoothing and mitigation algorithms.
1204 Enables recording of ntpd statistics counters on a periodic basis.
1206 hour a line of the following form is appended to the file generation
1210 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1213 The first two fields show the date (Modified Julian Day) and time
1214 (seconds and fraction past UTC midnight).
1215 The remaining ten fields show
1216 the statistics counter values accumulated since the last generated
1218 .Bl -tag -width indent
1219 .It Time since restart Cm 36000
1220 Time in hours since the system was last rebooted.
1221 .It Packets received Cm 81965
1222 Total number of packets received.
1223 .It Packets processed Cm 0
1224 Number of packets received in response to previous packets sent
1225 .It Current version Cm 9546
1226 Number of packets matching the current NTP version.
1227 .It Previous version Cm 56
1228 Number of packets matching the previous NTP version.
1229 .It Bad version Cm 71793
1230 Number of packets matching neither NTP version.
1231 .It Access denied Cm 512
1232 Number of packets denied access for any reason.
1233 .It Bad length or format Cm 540
1234 Number of packets with invalid length, format or port number.
1235 .It Bad authentication Cm 10
1236 Number of packets not verified as authentic.
1237 .It Rate exceeded Cm 147
1238 Number of packets discarded due to rate limitation.
1240 .It Cm statsdir Ar directory_path
1241 Indicates the full path of a directory where statistics files
1242 should be created (see below).
1244 the (otherwise constant)
1246 filename prefix to be modified for file generation sets, which
1247 is useful for handling statistics logs.
1248 .It Cm filegen Ar name Xo
1249 .Op Cm file Ar filename
1250 .Op Cm type Ar typename
1251 .Op Cm link | nolink
1252 .Op Cm enable | disable
1254 Configures setting of generation file set name.
1256 file sets provide a means for handling files that are
1257 continuously growing during the lifetime of a server.
1258 Server statistics are a typical example for such files.
1259 Generation file sets provide access to a set of files used
1260 to store the actual data.
1261 At any time at most one element
1262 of the set is being written to.
1263 The type given specifies
1264 when and how data will be directed to a new element of the set.
1265 This way, information stored in elements of a file set
1266 that are currently unused are available for administrational
1267 operations without the risk of disturbing the operation of ntpd.
1268 (Most important: they can be removed to free space for new data
1271 Note that this command can be sent from the
1272 .Xr ntpdc 1ntpdcmdoc
1273 program running at a remote location.
1274 .Bl -tag -width indent
1276 This is the type of the statistics records, as shown in the
1279 .It Cm file Ar filename
1280 This is the file name for the statistics records.
1282 members are built from three concatenated elements
1287 .Bl -tag -width indent
1289 This is a constant filename path.
1290 It is not subject to
1291 modifications via the
1294 It is defined by the
1295 server, usually specified as a compile-time constant.
1297 however, be configurable for individual file generation sets
1299 For example, the prefix used with
1303 generation can be configured using the
1305 option explained above.
1307 This string is directly concatenated to the prefix mentioned
1308 above (no intervening
1310 This can be modified using
1311 the file argument to the
1317 allowed in this component to prevent filenames referring to
1318 parts outside the filesystem hierarchy denoted by
1321 This part is reflects individual elements of a file set.
1323 generated according to the type of a file set.
1325 .It Cm type Ar typename
1326 A file generation set is characterized by its type.
1328 types are supported:
1329 .Bl -tag -width indent
1331 The file set is actually a single plain file.
1333 One element of file set is used per incarnation of a ntpd
1335 This type does not perform any changes to file set
1336 members during runtime, however it provides an easy way of
1337 separating files belonging to different
1339 server incarnations.
1340 The set member filename is built by appending a
1347 appending the decimal representation of the process ID of the
1351 One file generation set element is created per day.
1353 defined as the period between 00:00 and 24:00 UTC.
1355 member suffix consists of a
1357 and a day specification in
1361 is a 4-digit year number (e.g., 1992).
1363 is a two digit month number.
1365 is a two digit day number.
1366 Thus, all information written at 10 December 1992 would end up
1369 .Ar filename Ns .19921210 .
1371 Any file set member contains data related to a certain week of
1373 The term week is defined by computing day-of-year
1375 Elements of such a file generation set are
1376 distinguished by appending the following suffix to the file set
1377 filename base: A dot, a 4-digit year number, the letter
1379 and a 2-digit week number.
1380 For example, information from January,
1381 10th 1992 would end up in a file with suffix
1382 .No . Ns Ar 1992W1 .
1384 One generation file set element is generated per month.
1386 file name suffix consists of a dot, a 4-digit year number, and
1389 One generation file element is generated per year.
1391 suffix consists of a dot and a 4 digit year number.
1393 This type of file generation sets changes to a new element of
1394 the file set every 24 hours of server operation.
1396 suffix consists of a dot, the letter
1398 and an 8-digit number.
1399 This number is taken to be the number of seconds the server is
1400 running at the start of the corresponding 24-hour period.
1401 Information is only written to a file generation by specifying
1403 output is prevented by specifying
1406 .It Cm link | nolink
1407 It is convenient to be able to access the current element of a file
1408 generation set by a fixed name.
1409 This feature is enabled by
1414 If link is specified, a
1415 hard link from the current file set element to a file without
1417 When there is already a file with this name and
1418 the number of links of this file is one, it is renamed appending a
1425 number of links is greater than one, the file is unlinked.
1427 allows the current file to be accessed by a constant name.
1428 .It Cm enable \&| Cm disable
1429 Enables or disables the recording function.
1433 .Sh Access Control Support
1436 daemon implements a general purpose address/mask based restriction
1438 The list contains address/match entries sorted first
1439 by increasing address values and and then by increasing mask values.
1440 A match occurs when the bitwise AND of the mask and the packet
1441 source address is equal to the bitwise AND of the mask and
1442 address in the list.
1443 The list is searched in order with the
1444 last match found defining the restriction flags associated
1446 Additional information and examples can be found in the
1447 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
1449 (available as part of the HTML documentation
1451 .Pa /usr/share/doc/ntp ) .
1453 The restriction facility was implemented in conformance
1454 with the access policies for the original NSFnet backbone
1456 Later the facility was expanded to deflect
1457 cryptographic and clogging attacks.
1458 While this facility may
1459 be useful for keeping unwanted or broken or malicious clients
1460 from congesting innocent servers, it should not be considered
1461 an alternative to the NTP authentication facilities.
1462 Source address based restrictions are easily circumvented
1463 by a determined cracker.
1465 Clients can be denied service because they are explicitly
1466 included in the restrict list created by the
1469 or implicitly as the result of cryptographic or rate limit
1471 Cryptographic violations include certificate
1472 or identity verification failure; rate limit violations generally
1473 result from defective NTP implementations that send packets
1475 Some violations cause denied service
1476 only for the offending packet, others cause denied service
1477 for a timed period and others cause the denied service for
1478 an indefinite period.
1479 When a client or network is denied access
1480 for an indefinite period, the only way at present to remove
1481 the restrictions is by restarting the server.
1482 .Ss The Kiss-of-Death Packet
1483 Ordinarily, packets denied service are simply dropped with no
1484 further action except incrementing statistics counters.
1486 more proactive response is needed, such as a server message that
1487 explicitly requests the client to stop sending and leave a message
1488 for the system operator.
1489 A special packet format has been created
1490 for this purpose called the "kiss-of-death" (KoD) packet.
1491 KoD packets have the leap bits set unsynchronized and stratum set
1492 to zero and the reference identifier field set to a four-byte
1498 flag of the matching restrict list entry is set,
1499 the code is "DENY"; if the
1501 flag is set and the rate limit
1502 is exceeded, the code is "RATE".
1503 Finally, if a cryptographic violation occurs, the code is "CRYP".
1505 A client receiving a KoD performs a set of sanity checks to
1506 minimize security exposure, then updates the stratum and
1507 reference identifier peer variables, sets the access
1508 denied (TEST4) bit in the peer flash variable and sends
1509 a message to the log.
1510 As long as the TEST4 bit is set,
1511 the client will send no further packets to the server.
1512 The only way at present to recover from this condition is
1513 to restart the protocol at both the client and server.
1515 happens automatically at the client when the association times out.
1516 It will happen at the server only if the server operator cooperates.
1517 .Ss Access Control Commands
1518 .Bl -tag -width indent
1520 .Op Cm average Ar avg
1521 .Op Cm minimum Ar min
1522 .Op Cm monitor Ar prob
1524 Set the parameters of the
1526 facility which protects the server from
1530 subcommand specifies the minimum average packet
1533 subcommand specifies the minimum packet spacing.
1534 Packets that violate these minima are discarded
1535 and a kiss-o'-death packet returned if enabled.
1537 minimum average and minimum are 5 and 2, respectively.
1540 subcommand specifies the probability of discard
1541 for packets that overflow the rate-control window.
1542 .It Xo Ic restrict address
1544 .Op Cm ippeerlimit Ar int
1549 argument expressed in
1550 dotted-quad form is the address of a host or network.
1553 argument can be a valid host DNS name.
1556 argument expressed in dotted-quad form defaults to
1557 .Cm 255.255.255.255 ,
1560 is treated as the address of an individual host.
1561 A default entry (address
1565 is always included and is always the first entry in the list.
1566 Note that text string
1568 with no mask option, may
1569 be used to indicate the default entry.
1572 directive limits the number of peer requests for each IP to
1574 where a value of -1 means "unlimited", the current default.
1575 A value of 0 means "none".
1576 There would usually be at most 1 peering request per IP,
1577 but if the remote peering requests are behind a proxy
1578 there could well be more than 1 per IP.
1579 In the current implementation,
1582 restricts access, i.e., an entry with no flags indicates that free
1583 access to the server is to be given.
1584 The flags are not orthogonal,
1585 in that more restrictive flags will often make less restrictive
1587 The flags can generally be classed into two
1588 categories, those which restrict time service and those which
1589 restrict informational queries and attempts to do run-time
1590 reconfiguration of the server.
1591 One or more of the following flags
1593 .Bl -tag -width indent
1595 Deny packets of all kinds, including
1598 .Xr ntpdc 1ntpdcmdoc
1601 If this flag is set when an access violation occurs, a kiss-o'-death
1602 (KoD) packet is sent.
1603 KoD packets are rate limited to no more than one
1605 If another KoD packet occurs within one second after the
1606 last one, the packet is dropped.
1608 Deny service if the packet spacing violates the lower limits specified
1612 A history of clients is kept using the
1613 monitoring capability of
1614 .Xr ntpd 1ntpdmdoc .
1615 Thus, monitoring is always active as
1616 long as there is a restriction entry with the
1620 Declare traps set by matching hosts to be low priority.
1622 number of traps a server can maintain is limited (the current limit
1624 Traps are usually assigned on a first come, first served
1625 basis, with later trap requestors being denied service.
1627 modifies the assignment algorithm by allowing low priority traps to
1628 be overridden by later requests for normal priority traps.
1630 Deny ephemeral peer requests,
1631 even if they come from an authenticated source.
1632 Note that the ability to use a symmetric key for authentication may be restricted to
1633 one or more IPs or subnets via the third field of the
1636 This restriction is not enabled by default,
1637 to maintain backward compatability.
1640 to become the default in ntp-4.4.
1645 .Xr ntpdc 1ntpdcmdoc
1646 queries which attempt to modify the state of the
1647 server (i.e., run time reconfiguration).
1648 Queries which return
1649 information are permitted.
1654 .Xr ntpdc 1ntpdcmdoc
1656 Time service is not affected.
1658 Deny unauthenticated packets which would result in mobilizing a new association.
1660 broadcast and symmetric active packets
1661 when a configured association does not exist.
1664 associations, so if you want to use servers from a
1666 directive and also want to use
1668 by default, you'll want a
1669 .Cm "restrict source ..."
1670 line as well that does
1676 Deny all packets except
1679 .Xr ntpdc 1ntpdcmdoc
1682 Decline to provide mode 6 control message trap service to matching
1684 The trap service is a subsystem of the
1687 protocol which is intended for use by remote event logging programs.
1689 Deny service unless the packet is cryptographically authenticated.
1691 This is actually a match algorithm modifier, rather than a
1693 Its presence causes the restriction entry to be
1694 matched only if the source port in the packet is the standard NTP
1704 is considered more specific and
1705 is sorted later in the list.
1706 .It Ic "serverresponse fuzz"
1707 When reponding to server requests,
1708 fuzz the low order bits of the
1711 Deny packets that do not match the current NTP version.
1714 Default restriction list entries with the flags ignore, interface,
1715 ntpport, for each of the local host's interface addresses are
1716 inserted into the table at startup to prevent the server
1717 from attempting to synchronize to its own time.
1718 A default entry is also always present, though if it is
1719 otherwise unconfigured; no flags are associated
1720 with the default entry (i.e., everything besides your own
1721 NTP server is unrestricted).
1723 .Sh Automatic NTP Configuration Options
1725 Manycasting is a automatic discovery and configuration paradigm
1727 It is intended as a means for a multicast client
1728 to troll the nearby network neighborhood to find cooperating
1729 manycast servers, validate them using cryptographic means
1730 and evaluate their time values with respect to other servers
1731 that might be lurking in the vicinity.
1732 The intended result is that each manycast client mobilizes
1733 client associations with some number of the "best"
1734 of the nearby manycast servers, yet automatically reconfigures
1735 to sustain this number of servers should one or another fail.
1737 Note that the manycasting paradigm does not coincide
1738 with the anycast paradigm described in RFC-1546,
1739 which is designed to find a single server from a clique
1740 of servers providing the same service.
1741 The manycast paradigm is designed to find a plurality
1742 of redundant servers satisfying defined optimality criteria.
1744 Manycasting can be used with either symmetric key
1745 or public key cryptography.
1746 The public key infrastructure (PKI)
1747 offers the best protection against compromised keys
1748 and is generally considered stronger, at least with relatively
1750 It is implemented using the Autokey protocol and
1751 the OpenSSL cryptographic library available from
1752 .Li http://www.openssl.org/ .
1753 The library can also be used with other NTPv4 modes
1754 as well and is highly recommended, especially for broadcast modes.
1756 A persistent manycast client association is configured
1759 command, which is similar to the
1761 command but with a multicast (IPv4 class
1766 The IANA has designated IPv4 address 224.1.1.1
1767 and IPv6 address FF05::101 (site local) for NTP.
1768 When more servers are needed, it broadcasts manycast
1769 client messages to this address at the minimum feasible rate
1770 and minimum feasible time-to-live (TTL) hops, depending
1771 on how many servers have already been found.
1772 There can be as many manycast client associations
1773 as different group address, each one serving as a template
1774 for a future ephemeral unicast client/server association.
1776 Manycast servers configured with the
1778 command listen on the specified group address for manycast
1780 Note the distinction between manycast client,
1781 which actively broadcasts messages, and manycast server,
1782 which passively responds to them.
1783 If a manycast server is
1784 in scope of the current TTL and is itself synchronized
1785 to a valid source and operating at a stratum level equal
1786 to or lower than the manycast client, it replies to the
1787 manycast client message with an ordinary unicast server message.
1789 The manycast client receiving this message mobilizes
1790 an ephemeral client/server association according to the
1791 matching manycast client template, but only if cryptographically
1792 authenticated and the server stratum is less than or equal
1793 to the client stratum.
1794 Authentication is explicitly required
1795 and either symmetric key or public key (Autokey) can be used.
1796 Then, the client polls the server at its unicast address
1797 in burst mode in order to reliably set the host clock
1798 and validate the source.
1799 This normally results
1800 in a volley of eight client/server at 2-s intervals
1801 during which both the synchronization and cryptographic
1802 protocols run concurrently.
1803 Following the volley,
1804 the client runs the NTP intersection and clustering
1805 algorithms, which act to discard all but the "best"
1806 associations according to stratum and synchronization
1808 The surviving associations then continue
1809 in ordinary client/server mode.
1811 The manycast client polling strategy is designed to reduce
1812 as much as possible the volume of manycast client messages
1813 and the effects of implosion due to near-simultaneous
1814 arrival of manycast server messages.
1815 The strategy is determined by the
1816 .Ic manycastclient ,
1820 configuration commands.
1821 The manycast poll interval is
1822 normally eight times the system poll interval,
1823 which starts out at the
1825 value specified in the
1826 .Ic manycastclient ,
1827 command and, under normal circumstances, increments to the
1829 value specified in this command.
1830 Initially, the TTL is
1831 set at the minimum hops specified by the
1834 At each retransmission the TTL is increased until reaching
1835 the maximum hops specified by this command or a sufficient
1836 number client associations have been found.
1837 Further retransmissions use the same TTL.
1839 The quality and reliability of the suite of associations
1840 discovered by the manycast client is determined by the NTP
1841 mitigation algorithms and the
1845 values specified in the
1847 configuration command.
1850 candidate servers must be available and the mitigation
1851 algorithms produce at least
1853 survivors in order to synchronize the clock.
1854 Byzantine agreement principles require at least four
1855 candidates in order to correctly discard a single falseticker.
1856 For legacy purposes,
1861 For manycast service
1863 should be explicitly set to 4, assuming at least that
1864 number of servers are available.
1868 servers are found, the manycast poll interval is immediately
1873 servers are found when the TTL has reached the maximum hops,
1874 the manycast poll interval is doubled.
1875 For each transmission
1876 after that, the poll interval is doubled again until
1877 reaching the maximum of eight times
1879 Further transmissions use the same poll interval and
1881 Note that while all this is going on,
1882 each client/server association found is operating normally
1883 it the system poll interval.
1885 Administratively scoped multicast boundaries are normally
1886 specified by the network router configuration and,
1887 in the case of IPv6, the link/site scope prefix.
1888 By default, the increment for TTL hops is 32 starting
1889 from 31; however, the
1891 configuration command can be
1892 used to modify the values to match the scope rules.
1894 It is often useful to narrow the range of acceptable
1895 servers which can be found by manycast client associations.
1896 Because manycast servers respond only when the client
1897 stratum is equal to or greater than the server stratum,
1898 primary (stratum 1) servers fill find only primary servers
1899 in TTL range, which is probably the most common objective.
1900 However, unless configured otherwise, all manycast clients
1901 in TTL range will eventually find all primary servers
1902 in TTL range, which is probably not the most common
1903 objective in large networks.
1906 command can be used to modify this behavior.
1907 Servers with stratum below
1913 command are strongly discouraged during the selection
1914 process; however, these servers may be temporally
1915 accepted if the number of servers within TTL range is
1919 The above actions occur for each manycast client message,
1920 which repeats at the designated poll interval.
1921 However, once the ephemeral client association is mobilized,
1922 subsequent manycast server replies are discarded,
1923 since that would result in a duplicate association.
1924 If during a poll interval the number of client associations
1927 all manycast client prototype associations are reset
1928 to the initial poll interval and TTL hops and operation
1929 resumes from the beginning.
1930 It is important to avoid
1931 frequent manycast client messages, since each one requires
1932 all manycast servers in TTL range to respond.
1933 The result could well be an implosion, either minor or major,
1934 depending on the number of servers in range.
1935 The recommended value for
1939 It is possible and frequently useful to configure a host
1940 as both manycast client and manycast server.
1941 A number of hosts configured this way and sharing a common
1942 group address will automatically organize themselves
1943 in an optimum configuration based on stratum and
1944 synchronization distance.
1945 For example, consider an NTP
1946 subnet of two primary servers and a hundred or more
1948 With two exceptions, all servers
1949 and clients have identical configuration files including both
1953 commands using, for instance, multicast group address
1955 The only exception is that each primary server
1956 configuration file must include commands for the primary
1957 reference source such as a GPS receiver.
1959 The remaining configuration files for all secondary
1960 servers and clients have the same contents, except for the
1962 command, which is specific for each stratum level.
1963 For stratum 1 and stratum 2 servers, that command is
1965 For stratum 3 and above servers the
1967 value is set to the intended stratum number.
1968 Thus, all stratum 3 configuration files are identical,
1969 all stratum 4 files are identical and so forth.
1971 Once operations have stabilized in this scenario,
1972 the primary servers will find the primary reference source
1973 and each other, since they both operate at the same
1974 stratum (1), but not with any secondary server or client,
1975 since these operate at a higher stratum.
1977 servers will find the servers at the same stratum level.
1978 If one of the primary servers loses its GPS receiver,
1979 it will continue to operate as a client and other clients
1980 will time out the corresponding association and
1981 re-associate accordingly.
1983 Some administrators prefer to avoid running
1985 continuously and run either
1991 In either case the servers must be
1992 configured in advance and the program fails if none are
1993 available when the cron job runs.
1995 application of manycast is with
1998 The program wakes up, scans the local landscape looking
1999 for the usual suspects, selects the best from among
2000 the rascals, sets the clock and then departs.
2001 Servers do not have to be configured in advance and
2002 all clients throughout the network can have the same
2004 .Ss Manycast Interactions with Autokey
2005 Each time a manycast client sends a client mode packet
2006 to a multicast group address, all manycast servers
2007 in scope generate a reply including the host name
2009 The manycast clients then run
2010 the Autokey protocol, which collects and verifies
2011 all certificates involved.
2012 Following the burst interval
2013 all but three survivors are cast off,
2014 but the certificates remain in the local cache.
2015 It often happens that several complete signing trails
2016 from the client to the primary servers are collected in this way.
2018 About once an hour or less often if the poll interval
2019 exceeds this, the client regenerates the Autokey key list.
2020 This is in general transparent in client/server mode.
2021 However, about once per day the server private value
2022 used to generate cookies is refreshed along with all
2023 manycast client associations.
2025 cryptographic values including certificates is refreshed.
2026 If a new certificate has been generated since
2027 the last refresh epoch, it will automatically revoke
2028 all prior certificates that happen to be in the
2030 At the same time, the manycast
2031 scheme starts all over from the beginning and
2032 the expanding ring shrinks to the minimum and increments
2033 from there while collecting all servers in scope.
2034 .Ss Broadcast Options
2035 .Bl -tag -width indent
2038 .Cm bcpollbstep Ar gate
2041 This command provides a way to delay,
2042 by the specified number of broadcast poll intervals,
2043 believing backward time steps from a broadcast server.
2044 Broadcast time networks are expected to be trusted.
2045 In the event a broadcast server's time is stepped backwards,
2046 there is clear benefit to having the clients notice this change
2047 as soon as possible.
2048 Attacks such as replay attacks can happen, however,
2049 and even though there are a number of protections built in to
2050 broadcast mode, attempts to perform a replay attack are possible.
2051 This value defaults to 0, but can be changed
2052 to any number of poll intervals between 0 and 4.
2054 .Ss Manycast Options
2055 .Bl -tag -width indent
2058 .Cm ceiling Ar ceiling |
2059 .Cm cohort { 0 | 1 } |
2060 .Cm floor Ar floor |
2061 .Cm minclock Ar minclock |
2062 .Cm minsane Ar minsane
2065 This command affects the clock selection and clustering
2067 It can be used to select the quality and
2068 quantity of peers used to synchronize the system clock
2069 and is most useful in manycast mode.
2070 The variables operate
2072 .Bl -tag -width indent
2073 .It Cm ceiling Ar ceiling
2074 Peers with strata above
2076 will be discarded if there are at least
2079 This value defaults to 15, but can be changed
2080 to any number from 1 to 15.
2081 .It Cm cohort Bro 0 | 1 Brc
2082 This is a binary flag which enables (0) or disables (1)
2083 manycast server replies to manycast clients with the same
2085 This is useful to reduce implosions where
2086 large numbers of clients with the same stratum level
2088 The default is to enable these replies.
2089 .It Cm floor Ar floor
2090 Peers with strata below
2092 will be discarded if there are at least
2095 This value defaults to 1, but can be changed
2096 to any number from 1 to 15.
2097 .It Cm minclock Ar minclock
2098 The clustering algorithm repeatedly casts out outlier
2099 associations until no more than
2101 associations remain.
2102 This value defaults to 3,
2103 but can be changed to any number from 1 to the number of
2105 .It Cm minsane Ar minsane
2106 This is the minimum number of candidates available
2107 to the clock selection algorithm in order to produce
2108 one or more truechimers for the clustering algorithm.
2109 If fewer than this number are available, the clock is
2110 undisciplined and allowed to run free.
2112 for legacy purposes.
2113 However, according to principles of
2114 Byzantine agreement,
2116 should be at least 4 in order to detect and discard
2117 a single falseticker.
2119 .It Cm ttl Ar hop ...
2120 This command specifies a list of TTL values in increasing
2121 order, up to 8 values can be specified.
2122 In manycast mode these values are used in turn
2123 in an expanding-ring search.
2124 The default is eight
2125 multiples of 32 starting at 31.
2127 .Sh Reference Clock Support
2128 The NTP Version 4 daemon supports some three dozen different radio,
2129 satellite and modem reference clocks plus a special pseudo-clock
2130 used for backup or when no other clock source is available.
2131 Detailed descriptions of individual device drivers and options can
2133 .Qq Reference Clock Drivers
2135 (available as part of the HTML documentation
2137 .Pa /usr/share/doc/ntp ) .
2138 Additional information can be found in the pages linked
2139 there, including the
2140 .Qq Debugging Hints for Reference Clock Drivers
2142 .Qq How To Write a Reference Clock Driver
2144 (available as part of the HTML documentation
2146 .Pa /usr/share/doc/ntp ) .
2147 In addition, support for a PPS
2148 signal is available as described in the
2149 .Qq Pulse-per-second (PPS) Signal Interfacing
2151 (available as part of the HTML documentation
2153 .Pa /usr/share/doc/ntp ) .
2155 drivers support special line discipline/streams modules which can
2156 significantly improve the accuracy using the driver.
2159 .Qq Line Disciplines and Streams Drivers
2161 (available as part of the HTML documentation
2163 .Pa /usr/share/doc/ntp ) .
2165 A reference clock will generally (though not always) be a radio
2166 timecode receiver which is synchronized to a source of standard
2167 time such as the services offered by the NRC in Canada and NIST and
2169 The interface between the computer and the timecode
2170 receiver is device dependent, but is usually a serial port.
2172 device driver specific to each reference clock must be selected and
2173 compiled in the distribution; however, most common radio, satellite
2174 and modem clocks are included by default.
2175 Note that an attempt to
2176 configure a reference clock when the driver has not been compiled
2177 or the hardware port has not been appropriately configured results
2178 in a scalding remark to the system log file, but is otherwise non
2181 For the purposes of configuration,
2184 reference clocks in a manner analogous to normal NTP peers as much
2186 Reference clocks are identified by a syntactically
2187 correct but invalid IP address, in order to distinguish them from
2189 Reference clock addresses are of the form
2191 .Li 127.127. Ar t . Ar u ,
2196 denoting the clock type and
2199 number in the range 0-3.
2200 While it may seem overkill, it is in fact
2201 sometimes useful to configure multiple reference clocks of the same
2202 type, in which case the unit numbers must be unique.
2206 command is used to configure a reference
2209 argument in that command
2210 is the clock address.
2216 options are not used for reference clock support.
2219 option is added for reference clock support, as
2223 option can be useful to
2224 persuade the server to cherish a reference clock with somewhat more
2225 enthusiasm than other reference clocks or peers.
2227 information on this option can be found in the
2228 .Qq Mitigation Rules and the prefer Keyword
2229 (available as part of the HTML documentation
2231 .Pa /usr/share/doc/ntp )
2238 meaning only for selected clock drivers.
2239 See the individual clock
2240 driver document pages for additional information.
2244 command is used to provide additional
2245 information for individual clock drivers and normally follows
2246 immediately after the
2251 argument specifies the clock address.
2256 options can be used to
2257 override the defaults for the device.
2258 There are two optional
2259 device-dependent time offsets and four flags that can be included
2264 The stratum number of a reference clock is by default zero.
2267 daemon adds one to the stratum of each
2268 peer, a primary server ordinarily displays an external stratum of
2270 In order to provide engineered backups, it is often useful to
2271 specify the reference clock stratum as greater than zero.
2274 option is used for this purpose.
2276 involving both a reference clock and a pulse-per-second (PPS)
2277 discipline signal, it is useful to specify the reference clock
2278 identifier as other than the default, depending on the driver.
2281 option is used for this purpose.
2283 these options apply to all clock drivers.
2284 .Ss Reference Clock Commands
2285 .Bl -tag -width indent
2288 .Li 127.127. Ar t . Ar u
2292 .Op Cm minpoll Ar int
2293 .Op Cm maxpoll Ar int
2295 This command can be used to configure reference clocks in
2297 The options are interpreted as follows:
2298 .Bl -tag -width indent
2300 Marks the reference clock as preferred.
2301 All other things being
2302 equal, this host will be chosen for synchronization among a set of
2303 correctly operating hosts.
2305 .Qq Mitigation Rules and the prefer Keyword
2307 (available as part of the HTML documentation
2309 .Pa /usr/share/doc/ntp )
2310 for further information.
2312 Specifies a mode number which is interpreted in a
2313 device-specific fashion.
2314 For instance, it selects a dialing
2315 protocol in the ACTS driver and a device subtype in the
2318 .It Cm minpoll Ar int
2319 .It Cm maxpoll Ar int
2320 These options specify the minimum and maximum polling interval
2321 for reference clock messages, as a power of 2 in seconds
2323 most directly connected reference clocks, both
2327 default to 6 (64 s).
2328 For modem reference clocks,
2330 defaults to 10 (17.1 m) and
2332 defaults to 14 (4.5 h).
2333 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2337 .Li 127.127. Ar t . Ar u
2341 .Op Cm stratum Ar int
2342 .Op Cm refid Ar string
2344 .Op Cm flag1 Cm 0 \&| Cm 1
2345 .Op Cm flag2 Cm 0 \&| Cm 1
2346 .Op Cm flag3 Cm 0 \&| Cm 1
2347 .Op Cm flag4 Cm 0 \&| Cm 1
2349 This command can be used to configure reference clocks in
2351 It must immediately follow the
2353 command which configures the driver.
2354 Note that the same capability
2355 is possible at run time using the
2356 .Xr ntpdc 1ntpdcmdoc
2358 The options are interpreted as
2360 .Bl -tag -width indent
2362 Specifies a constant to be added to the time offset produced by
2363 the driver, a fixed-point decimal number in seconds.
2365 as a calibration constant to adjust the nominal time offset of a
2366 particular clock to agree with an external standard, such as a
2367 precision PPS signal.
2368 It also provides a way to correct a
2369 systematic error or bias due to serial port or operating system
2370 latencies, different cable lengths or receiver internal delay.
2372 specified offset is in addition to the propagation delay provided
2373 by other means, such as internal DIPswitches.
2375 for an individual system and driver is available, an approximate
2376 correction is noted in the driver documentation pages.
2377 Note: in order to facilitate calibration when more than one
2378 radio clock or PPS signal is supported, a special calibration
2379 feature is available.
2380 It takes the form of an argument to the
2382 command described in
2383 .Sx Miscellaneous Options
2384 page and operates as described in the
2385 .Qq Reference Clock Drivers
2387 (available as part of the HTML documentation
2389 .Pa /usr/share/doc/ntp ) .
2390 .It Cm time2 Ar secs
2391 Specifies a fixed-point decimal number in seconds, which is
2392 interpreted in a driver-dependent way.
2393 See the descriptions of
2394 specific drivers in the
2395 .Qq Reference Clock Drivers
2397 (available as part of the HTML documentation
2399 .Pa /usr/share/doc/ntp ).
2400 .It Cm stratum Ar int
2401 Specifies the stratum number assigned to the driver, an integer
2403 This number overrides the default stratum number
2404 ordinarily assigned by the driver itself, usually zero.
2405 .It Cm refid Ar string
2406 Specifies an ASCII string of from one to four characters which
2407 defines the reference identifier used by the driver.
2409 overrides the default identifier ordinarily assigned by the driver
2412 Specifies a mode number which is interpreted in a
2413 device-specific fashion.
2414 For instance, it selects a dialing
2415 protocol in the ACTS driver and a device subtype in the
2418 .It Cm flag1 Cm 0 \&| Cm 1
2419 .It Cm flag2 Cm 0 \&| Cm 1
2420 .It Cm flag3 Cm 0 \&| Cm 1
2421 .It Cm flag4 Cm 0 \&| Cm 1
2422 These four flags are used for customizing the clock driver.
2424 interpretation of these values, and whether they are used at all,
2425 is a function of the particular clock driver.
2429 is used to enable recording monitoring
2432 file configured with the
2435 Further information on the
2437 command can be found in
2438 .Sx Monitoring Options .
2441 .Sh Miscellaneous Options
2442 .Bl -tag -width indent
2443 .It Ic broadcastdelay Ar seconds
2444 The broadcast and multicast modes require a special calibration
2445 to determine the network delay between the local and remote
2447 Ordinarily, this is done automatically by the initial
2448 protocol exchanges between the client and server.
2450 the calibration procedure may fail due to network or server access
2451 controls, for example.
2452 This command specifies the default delay to
2453 be used under these circumstances.
2454 Typically (for Ethernet), a
2455 number between 0.003 and 0.007 seconds is appropriate.
2457 when this command is not used is 0.004 seconds.
2458 .It Ic calldelay Ar delay
2459 This option controls the delay in seconds between the first and second
2460 packets sent in burst or iburst mode to allow additional time for a modem
2461 or ISDN call to complete.
2462 .It Ic driftfile Ar driftfile
2463 This command specifies the complete path and name of the file used to
2464 record the frequency of the local clock oscillator.
2468 command line option.
2469 If the file exists, it is read at
2470 startup in order to set the initial frequency and then updated once per
2471 hour with the current frequency computed by the daemon.
2473 specified, but the file itself does not exist, the starts with an initial
2474 frequency of zero and creates the file when writing it for the first time.
2475 If this command is not given, the daemon will always start with an initial
2478 The file format consists of a single line containing a single
2479 floating point number, which records the frequency offset measured
2480 in parts-per-million (PPM).
2481 The file is updated by first writing
2482 the current drift value into a temporary file and then renaming
2483 this file to replace the old version.
2486 must have write permission for the directory the
2487 drift file is located in, and that file system links, symbolic or
2488 otherwise, should be avoided.
2489 .It Ic dscp Ar value
2490 This option specifies the Differentiated Services Control Point (DSCP) value,
2492 The default value is 46, signifying Expedited Forwarding.
2495 .Cm auth | Cm bclient |
2496 .Cm calibrate | Cm kernel |
2497 .Cm mode7 | Cm monitor |
2498 .Cm ntp | Cm stats |
2499 .Cm peer_clear_digest_early |
2500 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2505 .Cm auth | Cm bclient |
2506 .Cm calibrate | Cm kernel |
2507 .Cm mode7 | Cm monitor |
2508 .Cm ntp | Cm stats |
2509 .Cm peer_clear_digest_early |
2510 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2513 Provides a way to enable or disable various server options.
2514 Flags not mentioned are unaffected.
2515 Note that all of these flags
2516 can be controlled remotely using the
2517 .Xr ntpdc 1ntpdcmdoc
2519 .Bl -tag -width indent
2521 Enables the server to synchronize with unconfigured peers only if the
2522 peer has been correctly authenticated using either public key or
2523 private key cryptography.
2524 The default for this flag is
2527 Enables the server to listen for a message from a broadcast or
2528 multicast server, as in the
2530 command with default
2532 The default for this flag is
2535 Enables the calibrate feature for reference clocks.
2540 Enables the kernel time discipline, if available.
2541 The default for this
2544 if support is available, otherwise
2547 Enables processing of NTP mode 7 implementation-specific requests
2548 which are used by the deprecated
2549 .Xr ntpdc 1ntpdcmdoc
2551 The default for this flag is disable.
2552 This flag is excluded from runtime configuration using
2553 .Xr ntpq 1ntpqmdoc .
2556 program provides the same capabilities as
2557 .Xr ntpdc 1ntpdcmdoc
2558 using standard mode 6 requests.
2560 Enables the monitoring facility.
2562 .Xr ntpdc 1ntpdcmdoc
2566 command or further information.
2568 default for this flag is
2571 Enables time and frequency discipline.
2572 In effect, this switch opens and
2573 closes the feedback loop, which is useful for testing.
2577 .It Cm peer_clear_digest_early
2580 is using autokey and it
2581 receives a crypto-NAK packet that
2582 passes the duplicate packet and origin timestamp checks
2583 the peer variables are immediately cleared.
2584 While this is generally a feature
2585 as it allows for quick recovery if a server key has changed,
2586 a properly forged and appropriately delivered crypto-NAK packet
2587 can be used in a DoS attack.
2588 If you have active noticable problems with this type of DoS attack
2589 then you should consider
2590 disabling this option.
2593 file for evidence of any of these attacks.
2595 default for this flag is
2598 Enables the statistics facility.
2600 .Sx Monitoring Options
2601 section for further information.
2602 The default for this flag is
2604 .It Cm unpeer_crypto_early
2607 receives an autokey packet that fails TEST9,
2609 the association is immediately cleared.
2610 This is almost certainly a feature,
2611 but if, in spite of the current recommendation of not using autokey,
2616 you are seeing this sort of DoS attack
2617 disabling this flag will delay
2618 tearing down the association until the reachability counter
2622 file for evidence of any of these attacks.
2624 default for this flag is
2626 .It Cm unpeer_crypto_nak_early
2629 receives a crypto-NAK packet that
2630 passes the duplicate packet and origin timestamp checks
2631 the association is immediately cleared.
2632 While this is generally a feature
2633 as it allows for quick recovery if a server key has changed,
2634 a properly forged and appropriately delivered crypto-NAK packet
2635 can be used in a DoS attack.
2636 If you have active noticable problems with this type of DoS attack
2637 then you should consider
2638 disabling this option.
2641 file for evidence of any of these attacks.
2643 default for this flag is
2645 .It Cm unpeer_digest_early
2648 receives what should be an authenticated packet
2649 that passes other packet sanity checks but
2650 contains an invalid digest
2651 the association is immediately cleared.
2652 While this is generally a feature
2653 as it allows for quick recovery,
2654 if this type of packet is carefully forged and sent
2655 during an appropriate window it can be used for a DoS attack.
2656 If you have active noticable problems with this type of DoS attack
2657 then you should consider
2658 disabling this option.
2661 file for evidence of any of these attacks.
2663 default for this flag is
2666 .It Ic includefile Ar includefile
2667 This command allows additional configuration commands
2668 to be included from a separate file.
2670 be nested to a depth of five; upon reaching the end of any
2671 include file, command processing resumes in the previous
2673 This option is useful for sites that run
2675 on multiple hosts, with (mostly) common options (e.g., a
2679 .Cm listen | Cm ignore | Cm drop
2682 .Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard
2683 .Ar name | Ar address
2684 .Oo Cm / Ar prefixlen
2690 directive controls which network addresses
2692 opens, and whether input is dropped without processing.
2693 The first parameter determines the action for addresses
2694 which match the second parameter.
2695 The second parameter specifies a class of addresses,
2696 or a specific interface name,
2698 In the address case,
2700 determines how many bits must match for this rule to apply.
2702 prevents opening matching addresses,
2706 to open the address and drop all received packets without examination.
2709 directives can be used.
2710 The last rule which matches a particular address determines the action for it.
2712 directives are disabled if any
2718 command-line options are specified in the configuration file,
2719 all available network addresses are opened.
2722 directive is an alias for
2724 .It Ic leapfile Ar leapfile
2725 This command loads the IERS leapseconds file and initializes the
2726 leapsecond values for the next leapsecond event, leapfile expiration
2727 time, and TAI offset.
2728 The file can be obtained directly from the IERS at
2729 .Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list
2731 .Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list .
2737 .Cm leapfile directive or when
2738 .Cm ntpd detects that the
2742 checks once a day to see if the
2746 .Xr update-leap 1update_leapmdoc
2747 script can be run to see if the
2750 .It Ic leapsmearinterval Ar seconds
2751 This EXPERIMENTAL option is only available if
2754 .Cm --enable-leap-smear
2758 It specifies the interval over which a leap second correction will be applied.
2759 Recommended values for this option are between
2760 7200 (2 hours) and 86400 (24 hours).
2761 .Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!
2762 See http://bugs.ntp.org/2855 for more information.
2763 .It Ic logconfig Ar configkeyword
2764 This command controls the amount and type of output written to
2767 facility or the alternate
2770 By default, all output is turned on.
2773 keywords can be prefixed with
2789 messages can be controlled in four
2798 Within these classes four types of messages can be
2799 controlled: informational messages
2817 Configuration keywords are formed by concatenating the message class with
2821 prefix can be used instead of a message class.
2823 message class may also be followed by the
2825 keyword to enable/disable all
2826 messages of the respective message class.
2827 Thus, a minimal log configuration
2828 could look like this:
2830 logconfig =syncstatus +sysevents
2833 This would just list the synchronizations state of
2835 and the major system events.
2836 For a simple reference server, the
2837 following minimum message configuration could be useful:
2839 logconfig =syncall +clockall
2842 This configuration will list all clock information and
2843 synchronization information.
2844 All other events and messages about
2845 peers, system events and so on is suppressed.
2846 .It Ic logfile Ar logfile
2847 This command specifies the location of an alternate log file to
2848 be used instead of the default system
2851 This is the same operation as the
2853 command line option.
2856 .Cm maxdepth Ar count | Cm maxmem Ar kilobytes |
2857 .Cm mindepth Ar count | Cm maxage Ar seconds |
2858 .Cm initialloc Ar count | Cm initmem Ar kilobytes |
2859 .Cm incalloc Ar count | Cm incmem Ar kilobytes
2862 Controls size limite of the monitoring facility's Most Recently Used
2864 of client addresses, which is also used by the
2865 rate control facility.
2866 .Bl -tag -width indent
2867 .It Ic maxdepth Ar count
2868 .It Ic maxmem Ar kilobytes
2869 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2870 The acutal limit will be up to
2877 options offered in units of entries or kilobytes, if both
2880 .Cm maxmem are used, the last one used controls.
2881 The default is 1024 kilobytes.
2882 .It Cm mindepth Ar count
2883 Lower limit on the MRU list size.
2884 When the MRU list has fewer than
2886 entries, existing entries are never removed to make room for newer ones,
2887 regardless of their age.
2888 The default is 600 entries.
2889 .It Cm maxage Ar seconds
2890 Once the MRU list has
2892 entries and an additional client is to ba added to the list,
2893 if the oldest entry was updated more than
2895 seconds ago, that entry is removed and its storage is reused.
2896 If the oldest entry was updated more recently the MRU list is grown,
2898 .Cm maxdepth / moxmem .
2899 The default is 64 seconds.
2900 .It Cm initalloc Ar count
2901 .It Cm initmem Ar kilobytes
2902 Initial memory allocation at the time the monitoringfacility is first enabled,
2903 in terms of the number of entries or kilobytes.
2904 The default is 4 kilobytes.
2905 .It Cm incalloc Ar count
2906 .It Cm incmem Ar kilobytes
2907 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2908 The default is 4 kilobytes.
2910 .It Ic nonvolatile Ar threshold
2913 delta in seconds before an hourly change to the
2915 (frequency file) will be written, with a default value of 1e-7 (0.1 PPM).
2916 The frequency file is inspected each hour.
2917 If the difference between the current frequency and the last value written
2918 exceeds the threshold, the file is written and the
2920 becomes the new threshold value.
2921 If the threshold is not exceeeded, it is reduced by half.
2922 This is intended to reduce the number of file writes
2923 for embedded systems with nonvolatile memory.
2924 .It Ic phone Ar dial ...
2925 This command is used in conjunction with
2926 the ACTS modem driver (type 18)
2927 or the JJY driver (type 40, mode 100 - 180).
2928 For the ACTS modem driver (type 18), the arguments consist of
2929 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2931 For the JJY driver (type 40 mode 100 - 180), the argument is
2932 one telephone number used to dial the telephone JJY service.
2933 The Hayes command ATDT is normally prepended to the number.
2934 The number can contain other modem control codes as well.
2935 .It Xo Cm pollskewlist
2946 Enable skewing of our poll requests to our servers.
2948 is a number between 3 and 17 inclusive, identifying a specific poll interval.
2949 A poll interval is 2^n seconds in duration,
2950 so a poll value of 3 corresponds to 8 seconds
2952 a poll interval of 17 corresponds to
2953 131,072 seconds, or about a day and a half.
2954 The next two numbers must be between 0 and one-half of the poll interval,
2956 The first number specifies how early the poll may start,
2958 the second number specifies how late the poll may be delayed.
2959 With no arguments, internally specified default values are chosen.
2983 Reset one or more groups of counters maintained by
2991 .Cm memlock Ar Nmegabytes |
2992 .Cm stacksize Ar N4kPages
2993 .Cm filenum Ar Nfiledescriptors
2996 .Bl -tag -width indent
2997 .It Cm memlock Ar Nmegabytes
2998 Specify the number of megabytes of memory that should be
2999 allocated and locked.
3000 Probably only available under Linux, this option may be useful
3001 when dropping root (the
3004 The default is 32 megabytes on non-Linux machines, and -1 under Linux.
3005 -1 means "do not lock the process into memory".
3006 0 means "lock whatever memory the process wants into memory".
3007 .It Cm stacksize Ar N4kPages
3008 Specifies the maximum size of the process stack on systems with the
3011 Defaults to 50 4k pages (200 4k pages in OpenBSD).
3012 .It Cm filenum Ar Nfiledescriptors
3013 Specifies the maximum number of file descriptors ntpd may have open at once.
3014 Defaults to the system default.
3016 .It Ic saveconfigdir Ar directory_path
3017 Specify the directory in which to write configuration snapshots
3024 does not appear in the configuration file,
3026 requests are rejected by
3028 .It Ic saveconfig Ar filename
3029 Write the current configuration, including any runtime
3030 modifications given with
3033 .Cm config-from-file
3040 This command will be rejected unless the
3042 directive appears in
3048 format directives to substitute the current date and time,
3050 .Cm saveconfig\ ntp-%Y%m%d-%H%M%S.conf .
3051 The filename used is stored in the system variable
3053 Authentication is required.
3054 .It Ic setvar Ar variable Op Cm default
3055 This command adds an additional system variable.
3057 variables can be used to distribute additional information such as
3059 If the variable of the form
3066 variable will be listed as part of the default system variables
3072 These additional variables serve
3073 informational purposes only.
3074 They are not related to the protocol
3075 other that they can be listed.
3076 The known protocol variables will
3077 always override any variables defined via the
3080 There are three special variables that contain the names
3081 of all variable of the same group.
3085 the names of all system variables.
3089 the names of all peer variables and the
3091 holds the names of the reference clock variables.
3093 Display operational summary.
3095 Show statistics counters maintained in the protocol module.
3098 .Cm allan Ar allan |
3099 .Cm dispersion Ar dispersion |
3101 .Cm huffpuff Ar huffpuff |
3102 .Cm panic Ar panic |
3104 .Cm stepback Ar stepback |
3105 .Cm stepfwd Ar stepfwd |
3106 .Cm stepout Ar stepout
3109 This command can be used to alter several system variables in
3110 very exceptional circumstances.
3111 It should occur in the
3112 configuration file before any other configuration options.
3114 default values of these variables have been carefully optimized for
3115 a wide range of network speeds and reliability expectations.
3117 general, they interact in intricate ways that are hard to predict
3118 and some combinations can result in some very nasty behavior.
3120 rarely is it necessary to change the default values; but, some
3121 folks cannot resist twisting the knobs anyway and this command is
3123 Emphasis added: twisters are on their own and can expect
3124 no help from the support group.
3126 The variables operate as follows:
3127 .Bl -tag -width indent
3128 .It Cm allan Ar allan
3129 The argument becomes the new value for the minimum Allan
3130 intercept, which is a parameter of the PLL/FLL clock discipline
3132 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
3134 .It Cm dispersion Ar dispersion
3135 The argument becomes the new value for the dispersion increase rate,
3136 normally .000015 s/s.
3138 The argument becomes the initial value of the frequency offset in
3140 This overrides the value in the frequency file, if
3141 present, and avoids the initial training state if it is not.
3142 .It Cm huffpuff Ar huffpuff
3143 The argument becomes the new value for the experimental
3144 huff-n'-puff filter span, which determines the most recent interval
3145 the algorithm will search for a minimum delay.
3147 900 s (15 m), but a more reasonable value is 7200 (2 hours).
3149 is no default, since the filter is not enabled unless this command
3151 .It Cm panic Ar panic
3152 The argument is the panic threshold, normally 1000 s.
3154 the panic sanity check is disabled and a clock offset of any value will
3157 The argument is the step threshold, which by default is 0.128 s.
3159 be set to any positive number in seconds.
3160 If set to zero, step
3161 adjustments will never occur.
3162 Note: The kernel time discipline is
3163 disabled if the step threshold is set to zero or greater than the
3165 .It Cm stepback Ar stepback
3166 The argument is the step threshold for the backward direction,
3167 which by default is 0.128 s.
3169 be set to any positive number in seconds.
3170 If both the forward and backward step thresholds are set to zero, step
3171 adjustments will never occur.
3172 Note: The kernel time discipline is
3174 each direction of step threshold are either
3175 set to zero or greater than .5 second.
3176 .It Cm stepfwd Ar stepfwd
3177 As for stepback, but for the forward direction.
3178 .It Cm stepout Ar stepout
3179 The argument is the stepout timeout, which by default is 900 s.
3181 be set to any positive number in seconds.
3182 If set to zero, the stepout
3183 pulses will not be suppressed.
3185 .It Cm writevar Ar assocID\ name = value [,...]
3186 Write (create or update) the specified variables.
3189 is zero, the variablea re from the
3191 name space, otherwise they are from the
3196 is required, as the same name can occur in both name spaces.
3197 .It Xo Ic trap Ar host_address
3198 .Op Cm port Ar port_number
3199 .Op Cm interface Ar interface_address
3201 This command configures a trap receiver at the given host
3202 address and port number for sending messages with the specified
3203 local interface address.
3204 If the port number is unspecified, a value
3206 If the interface address is not specified, the
3207 message is sent with a source address of the local interface the
3208 message is sent through.
3209 Note that on a multihomed host the
3210 interface used may vary from time to time with routing changes.
3211 .It Cm ttl Ar hop ...
3212 This command specifies a list of TTL values in increasing order.
3213 Up to 8 values can be specified.
3216 mode these values are used in-turn in an expanding-ring search.
3217 The default is eight multiples of 32 starting at 31.
3219 The trap receiver will generally log event messages and other
3220 information from the server in a log file.
3222 programs may also request their own trap dynamically, configuring a
3223 trap receiver will ensure that no messages are lost when the server
3226 This command specifies a list of TTL values in increasing order, up to 8
3227 values can be specified.
3228 In manycast mode these values are used in turn in
3229 an expanding-ring search.
3230 The default is eight multiples of 32 starting at
3233 _END_PROG_MDOC_DESCRIP;
3239 ds-text = <<- _END_MDOC_FILES
3240 .Bl -tag -width /etc/ntp.drift -compact
3241 .It Pa /etc/ntp.conf
3242 the default name of the configuration file
3247 .It Pa ntpkey_ Ns Ar host
3250 Diffie-Hellman agreement parameters
3256 ds-type = 'SEE ALSO';
3258 ds-text = <<- _END_MDOC_SEE_ALSO
3259 .Xr ntpd 1ntpdmdoc ,
3260 .Xr ntpdc 1ntpdcmdoc ,
3263 In addition to the manual pages provided,
3264 comprehensive documentation is available on the world wide web
3266 .Li http://www.ntp.org/ .
3267 A snapshot of this documentation is available in HTML format in
3268 .Pa /usr/share/doc/ntp .
3271 .%T Network Time Protocol (Version 4)
3280 ds-text = <<- _END_MDOC_BUGS
3281 The syntax checking is not picky; some combinations of
3282 ridiculous and even hilarious options and modes may not be
3286 .Pa ntpkey_ Ns Ar host
3287 files are really digital
3289 These should be obtained via secure directory
3290 services when they become universally available.
3297 ds-text = <<- _END_MDOC_NOTES
3298 This document was derived from FreeBSD.