3 <title>NTP Configuration File User's Manual</title>
4 <meta http-equiv="Content-Type" content="text/html">
5 <meta name="description" content="NTP Configuration File User's Manual">
6 <meta name="generator" content="makeinfo 4.7">
7 <link title="Top" rel="top" href="#Top">
8 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
9 <meta http-equiv="Content-Style-Type" content="text/css">
10 <style type="text/css"><!--
11 pre.display { font-family:inherit }
12 pre.format { font-family:inherit }
13 pre.smalldisplay { font-family:inherit; font-size:smaller }
14 pre.smallformat { font-family:inherit; font-size:smaller }
15 pre.smallexample { font-size:smaller }
16 pre.smalllisp { font-size:smaller }
17 span.sc { font-variant:small-caps }
18 span.roman { font-family: serif; font-weight: normal; }
22 <h1 class="settitle">NTP Configuration File User's Manual</h1>
25 <a name="Top"></a>Next: <a rel="next" accesskey="n" href="#ntp_002econf-Description">ntp.conf Description</a>,
26 Previous: <a rel="previous" accesskey="p" href="#dir">(dir)</a>,
27 Up: <a rel="up" accesskey="u" href="#dir">(dir)</a>
31 <h2 class="unnumbered">NTP's Configuration File User Manual</h2>
33 <p>This document describes the configuration file for the NTP Project's
34 <code>ntpd</code> program.
36 <p>This document applies to version 4.2.8p12 of <code>ntp.conf</code>.
38 <div class="shortcontents">
39 <h2>Short Contents</h2>
41 <a href="#Top">NTP's Configuration File User Manual</a>
46 <li><a accesskey="1" href="#ntp_002econf-Description">ntp.conf Description</a>
47 <li><a accesskey="2" href="#ntp_002econf-Notes">ntp.conf Notes</a>
52 <a name="ntp_002econf-Description"></a>Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>,
53 Up: <a rel="up" accesskey="u" href="#Top">Top</a>
57 <!-- node-name, next, previous, up -->
58 <h3 class="section">Description</h3>
60 <p>The behavior of <code>ntpd</code> can be changed by a configuration file,
61 by default <code>ntp.conf</code>.
65 <a name="ntp_002econf-Notes"></a>
69 <h3 class="section">Notes about ntp.conf</h3>
71 <p><a name="index-ntp_002econf-1"></a><a name="index-Network-Time-Protocol-_0028NTP_0029-daemon-configuration-file-format-2"></a>
75 configuration file is read at initial startup by the
76 <code>ntpd(1ntpdmdoc)</code>
77 daemon in order to specify the synchronization sources,
78 modes and other related information.
79 Usually, it is installed in the
80 <span class="file">/etc</span>
82 but could be installed elsewhere
87 <p>The file format is similar to other
88 <span class="sc">unix</span>
92 character and extend to the end of the line;
93 blank lines are ignored.
94 Configuration commands consist of an initial keyword
95 followed by a list of arguments,
96 some of which may be optional, separated by whitespace.
97 Commands may not be continued over multiple lines.
98 Arguments may be host names,
99 host addresses written in numeric, dotted-quad form,
100 integers, floating point numbers (when specifying times in seconds)
103 <p>The rest of this page describes the configuration and control options.
105 "Notes on Configuring NTP and Setting up an NTP Subnet"
107 (available as part of the HTML documentation
109 <span class="file">/usr/share/doc/ntp</span>)
110 contains an extended discussion of these options.
111 In addition to the discussion of general
112 <a href="#Configuration-Options">Configuration Options</a>,
113 there are sections describing the following supported functionality
114 and the options used to control it:
116 <li><a href="#Authentication-Support">Authentication Support</a>
117 <li><a href="#Monitoring-Support">Monitoring Support</a>
118 <li><a href="#Access-Control-Support">Access Control Support</a>
119 <li><a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a>
120 <li><a href="#Reference-Clock-Support">Reference Clock Support</a>
121 <li><a href="#Miscellaneous-Options">Miscellaneous Options</a>
124 <p>Following these is a section describing
125 <a href="#Miscellaneous-Options">Miscellaneous Options</a>.
126 While there is a rich set of options available,
127 the only required option is one or more
131 <code>broadcast</code>
133 <code>manycastclient</code>
137 <a name="Configuration-Support"></a>
141 <h4 class="subsection">Configuration Support</h4>
143 <p>Following is a description of the configuration commands in
145 These commands have the same basic functions as in NTPv3 and
146 in some cases new functions and new arguments.
148 classes of commands, configuration commands that configure a
149 persistent association with a remote server or peer or reference
150 clock, and auxiliary commands that specify environmental variables
151 that control various related operations.
153 <h5 class="subsubsection">Configuration Commands</h5>
155 <p>The various modes are determined by the command keyword and the
156 type of the required IP address.
157 Addresses are classed by type as
158 (s) a remote server or peer (IPv4 class A, B and C), (b) the
159 broadcast address of a local interface, (m) a multicast address (IPv4
160 class D), or (r) a reference clock address (127.127.x.x).
162 only those options applicable to each command are listed below.
164 of options not listed may not be caught as an error, but may result
165 in some weird and even destructive behavior.
167 <p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
168 is detected, support for the IPv6 address family is generated
169 in addition to the default support of the IPv4 address family.
170 In a few cases, including the
174 <code>ntpq(1ntpqmdoc)</code>
176 <code>ntpdc(1ntpdcmdoc)</code>,
177 IPv6 addresses are automatically generated.
178 IPv6 addresses can be identified by the presence of colons
180 in the address field.
181 IPv6 addresses can be used almost everywhere where
182 IPv4 addresses can be used,
183 with the exception of reference clock addresses,
184 which are always IPv4.
186 <p>Note that in contexts where a host name is expected, a
189 the host name forces DNS resolution to the IPv4 namespace,
192 qualifier forces DNS resolution to the IPv6 namespace.
193 See IPv6 references for the
194 equivalent classes for that address family.
196 <dt><code>pool</code> <kbd>address</kbd> <code>[burst]</code> <code>[iburst]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code><br><dt><code>server</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[burst]</code> <code>[iburst]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[true]</code><br><dt><code>peer</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[true]</code> <code>[xleave]</code><br><dt><code>broadcast</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[ttl </code><kbd>ttl</kbd><code>]</code> <code>[xleave]</code><br><dt><code>manycastclient</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[ttl </code><kbd>ttl</kbd><code>]</code><dd></dl>
198 <p>These five commands specify the time server name or address to
199 be used and the mode in which to operate.
203 either a DNS name or an IP address in dotted-quad notation.
204 Additional information on association behavior can be found in the
205 "Association Management"
207 (available as part of the HTML documentation
209 <span class="file">/usr/share/doc/ntp</span>).
211 <dt><code>pool</code><dd>For type s addresses, this command mobilizes a persistent
212 client mode association with a number of remote servers.
213 In this mode the local clock can synchronized to the
214 remote server, but the remote server can never be synchronized to
216 <br><dt><code>server</code><dd>For type s and r addresses, this command mobilizes a persistent
217 client mode association with the specified remote server or local
219 In this mode the local clock can synchronized to the
220 remote server, but the remote server can never be synchronized to
226 <br><dt><code>peer</code><dd>For type s addresses (only), this command mobilizes a
227 persistent symmetric-active mode association with the specified
229 In this mode the local clock can be synchronized to
230 the remote peer or the remote peer can be synchronized to the local
232 This is useful in a network of servers where, depending on
233 various failure scenarios, either the local or remote peer may be
234 the better source of time.
235 This command should NOT be used for type
237 <br><dt><code>broadcast</code><dd>For type b and m addresses (only), this
238 command mobilizes a persistent broadcast mode association.
240 commands can be used to specify multiple local broadcast interfaces
241 (subnets) and/or multiple multicast groups.
243 broadcast messages go only to the interface associated with the
244 subnet specified, but multicast messages go to all interfaces.
245 In broadcast mode the local server sends periodic broadcast
246 messages to a client population at the
248 specified, which is usually the broadcast address on (one of) the
249 local network(s) or a multicast address assigned to NTP.
251 has assigned the multicast group address IPv4 224.0.1.1 and
252 IPv6 ff05::101 (site local) exclusively to
253 NTP, but other nonconflicting addresses can be used to contain the
254 messages within administrative boundaries.
256 specification applies only to the local server operating as a
257 sender; for operation as a broadcast client, see the
258 <code>broadcastclient</code>
260 <code>multicastclient</code>
263 <br><dt><code>manycastclient</code><dd>For type m addresses (only), this command mobilizes a
264 manycast client mode association for the multicast address
266 In this case a specific address must be supplied which
267 matches the address used on the
268 <code>manycastserver</code>
270 the designated manycast servers.
271 The NTP multicast address
272 224.0.1.1 assigned by the IANA should NOT be used, unless specific
273 means are taken to avoid spraying large areas of the Internet with
274 these messages and causing a possibly massive implosion of replies
277 <code>manycastserver</code>
278 command specifies that the local server
279 is to operate in client mode with the remote servers that are
280 discovered as the result of broadcast/multicast messages.
282 client broadcasts a request message to the group address associated
285 and specifically enabled
286 servers respond to these messages.
287 The client selects the servers
288 providing the best time and continues as with the
291 The remaining servers are discarded as if never
297 <dt><code>autokey</code><dd>All packets sent to and received from the server or peer are to
298 include authentication fields encrypted using the autokey scheme
300 <a href="#Authentication-Options">Authentication Options</a>.
301 <br><dt><code>burst</code><dd>when the server is reachable, send a burst of eight packets
302 instead of the usual one.
303 The packet spacing is normally 2 s;
304 however, the spacing between the first and second packets
305 can be changed with the
306 <code>calldelay</code>
308 additional time for a modem or ISDN call to complete.
309 This is designed to improve timekeeping quality
312 command and s addresses.
313 <br><dt><code>iburst</code><dd>When the server is unreachable, send a burst of eight packets
314 instead of the usual one.
315 The packet spacing is normally 2 s;
316 however, the spacing between the first two packets can be
318 <code>calldelay</code>
320 additional time for a modem or ISDN call to complete.
321 This is designed to speed the initial synchronization
324 command and s addresses and when
325 <code>ntpd(1ntpdmdoc)</code>
329 <br><dt><code>key</code> <kbd>key</kbd><dd>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 <br><dt><code>minpoll</code> <kbd>minpoll</kbd><br><dt><code>maxpoll</code> <kbd>maxpoll</kbd><dd>These options specify the minimum and maximum poll intervals
336 for NTP messages, as a power of 2 in seconds
338 interval defaults to 10 (1,024 s), but can be increased by the
340 option to an upper limit of 17 (36.4 h).
342 minimum poll interval defaults to 6 (64 s), but can be decreased by
345 option to a lower limit of 4 (16 s).
346 <br><dt><code>noselect</code><dd>Marks the server as unused, except for display purposes.
347 The server is discarded by the selection algroithm.
348 <br><dt><code>preempt</code><dd>Says the association can be preempted.
349 <br><dt><code>true</code><dd>Marks the server as a truechimer.
350 Use this option only for testing.
351 <br><dt><code>prefer</code><dd>Marks the server as preferred.
352 All other things being equal,
353 this host will be chosen for synchronization among a set of
354 correctly operating hosts.
356 "Mitigation Rules and the prefer Keyword"
358 (available as part of the HTML documentation
360 <span class="file">/usr/share/doc/ntp</span>)
361 for further information.
362 <br><dt><code>true</code><dd>Forces the association to always survive the selection and clustering algorithms.
363 This option should almost certainly
365 be used while testing an association.
366 <br><dt><code>ttl</code> <kbd>ttl</kbd><dd>This option is used only with broadcast server and manycast
368 It specifies the time-to-live
371 use on broadcast server and multicast server and the maximum
373 for the expanding ring search with manycast
375 Selection of the proper value, which defaults to
376 127, is something of a black art and should be coordinated with the
377 network administrator.
378 <br><dt><code>version</code> <kbd>version</kbd><dd>Specifies the version number to be used for outgoing NTP
380 Versions 1-4 are the choices, with version 4 the
382 <br><dt><code>xleave</code><dd>Valid in
385 <code>broadcast</code>
386 modes only, this flag enables interleave mode.
389 <h5 class="subsubsection">Auxiliary Commands</h5>
392 <dt><code>broadcastclient</code><dd>This command enables reception of broadcast server messages to
393 any local interface (type b) address.
394 Upon receiving a message for
395 the first time, the broadcast client measures the nominal server
396 propagation delay using a brief client/server exchange with the
397 server, then enters the broadcast client mode, in which it
398 synchronizes to succeeding broadcast messages.
400 to avoid accidental or malicious disruption in this mode, both the
401 server and client should operate using symmetric-key or public-key
402 authentication as described in
403 <a href="#Authentication-Options">Authentication Options</a>.
404 <br><dt><code>manycastserver</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of manycast client messages to
405 the multicast group address(es) (type m) specified.
407 address is required, but the NTP multicast address 224.0.1.1
408 assigned by the IANA should NOT be used, unless specific means are
409 taken to limit the span of the reply and avoid a possibly massive
410 implosion at the original sender.
411 Note that, in order to avoid
412 accidental or malicious disruption in this mode, both the server
413 and client should operate using symmetric-key or public-key
414 authentication as described in
415 <a href="#Authentication-Options">Authentication Options</a>.
416 <br><dt><code>multicastclient</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of multicast server messages to
417 the multicast group address(es) (type m) specified.
419 a message for the first time, the multicast client measures the
420 nominal server propagation delay using a brief client/server
421 exchange with the server, then enters the broadcast client mode, in
422 which it synchronizes to succeeding multicast messages.
424 in order to avoid accidental or malicious disruption in this mode,
425 both the server and client should operate using symmetric-key or
426 public-key authentication as described in
427 <a href="#Authentication-Options">Authentication Options</a>.
428 <br><dt><code>mdnstries</code> <kbd>number</kbd><dd>If we are participating in mDNS,
429 after we have synched for the first time
430 we attempt to register with the mDNS system.
431 If that registration attempt fails,
432 we try again at one minute intervals for up to
433 <code>mdnstries</code>
437 may be starting before mDNS.
438 The default value for
439 <code>mdnstries</code>
444 <a name="Authentication-Support"></a>
448 <h4 class="subsection">Authentication Support</h4>
450 <p>Authentication support allows the NTP client to verify that the
451 server is in fact known and trusted and not an intruder intending
452 accidentally or on purpose to masquerade as that server.
454 specification RFC-1305 defines a scheme which provides
455 cryptographic authentication of received NTP packets.
457 this was done using the Data Encryption Standard (DES) algorithm
458 operating in Cipher Block Chaining (CBC) mode, commonly called
460 Subsequently, this was replaced by the RSA Message Digest
461 5 (MD5) algorithm using a private key, commonly called keyed-MD5.
462 Either algorithm computes a message digest, or one-way hash, which
463 can be used to verify the server has the correct private key and
466 <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key
467 cryptography and, in addition, provides a new Autokey scheme
468 based on public key cryptography.
469 Public key cryptography is generally considered more secure
470 than symmetric key cryptography, since the security is based
471 on a private value which is generated by each server and
473 With Autokey all key distribution and
474 management functions involve only public values, which
475 considerably simplifies key distribution and storage.
476 Public key management is based on X.509 certificates,
477 which can be provided by commercial services or
478 produced by utility programs in the OpenSSL software library
479 or the NTPv4 distribution.
481 <p>While the algorithms for symmetric key cryptography are
482 included in the NTPv4 distribution, public key cryptography
483 requires the OpenSSL software library to be installed
484 before building the NTP distribution.
485 Directions for doing that
486 are on the Building and Installing the Distribution page.
488 <p>Authentication is configured separately for each association
496 <code>broadcast</code>
498 <code>manycastclient</code>
499 configuration commands as described in
500 <a href="#Configuration-Options">Configuration Options</a>
503 options described below specify the locations of the key files,
504 if other than default, which symmetric keys are trusted
505 and the interval between various operations, if other than default.
507 <p>Authentication is always enabled,
508 although ineffective if not configured as
510 If a NTP packet arrives
511 including a message authentication
512 code (MAC), it is accepted only if it
513 passes all cryptographic checks.
515 checks require correct key ID, key value
518 been modified in any way or replayed
519 by an intruder, it will fail one or more
520 of these checks and be discarded.
521 Furthermore, the Autokey scheme requires a
522 preliminary protocol exchange to obtain
523 the server certificate, verify its
524 credentials and initialize the protocol
528 flag controls whether new associations or
529 remote configuration commands require cryptographic authentication.
530 This flag can be set or reset by the
534 commands and also by remote
535 configuration commands sent by a
536 <code>ntpdc(1ntpdcmdoc)</code>
539 If this flag is enabled, which is the default
540 case, new broadcast client and symmetric passive associations and
541 remote configuration commands must be cryptographically
542 authenticated using either symmetric key or public key cryptography.
544 flag is disabled, these operations are effective
545 even if not cryptographic
547 It should be understood
548 that operating with the
550 flag disabled invites a significant vulnerability
551 where a rogue hacker can
552 masquerade as a falseticker and seriously
553 disrupt system timekeeping.
555 important to note that this flag has no purpose
556 other than to allow or disallow
557 a new association in response to new broadcast
558 and symmetric active messages
559 and remote configuration commands and, in particular,
560 the flag has no effect on
561 the authentication process itself.
563 <p>An attractive alternative where multicast support is available
564 is manycast mode, in which clients periodically troll
565 for servers as described in the
566 <a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a>
568 Either symmetric key or public key
569 cryptographic authentication can be used in this mode.
570 The principle advantage
571 of manycast mode is that potential servers need not be
572 configured in advance,
573 since the client finds them during regular operation,
574 and the configuration
575 files for all clients can be identical.
577 <p>The security model and protocol schemes for
578 both symmetric key and public key
579 cryptography are summarized below;
580 further details are in the briefings, papers
581 and reports at the NTP project page linked from
582 <code>http://www.ntp.org/</code>.
584 <h5 class="subsubsection">Symmetric-Key Cryptography</h5>
586 <p>The original RFC-1305 specification allows any one of possibly
587 65,535 keys, each distinguished by a 32-bit key identifier, to
588 authenticate an association.
589 The servers and clients involved must
590 agree on the key and key identifier to
591 authenticate NTP packets.
593 related information are specified in a key
595 <span class="file">ntp.keys</span>,
596 which must be distributed and stored using
597 secure means beyond the scope of the NTP protocol itself.
598 Besides the keys used
599 for ordinary NTP associations,
600 additional keys can be used as passwords for the
601 <code>ntpq(1ntpqmdoc)</code>
603 <code>ntpdc(1ntpdcmdoc)</code>
607 <code>ntpd(1ntpdmdoc)</code>
608 is first started, it reads the key file specified in the
610 configuration command and installs the keys
613 individual keys must be activated with the
617 allows, for instance, the installation of possibly
618 several batches of keys and
619 then activating or deactivating each batch
621 <code>ntpdc(1ntpdcmdoc)</code>.
622 This also provides a revocation capability that can be used
623 if a key becomes compromised.
625 <code>requestkey</code>
626 command selects the key used as the password for the
627 <code>ntpdc(1ntpdcmdoc)</code>
629 <code>controlkey</code>
630 command selects the key used as the password for the
631 <code>ntpq(1ntpqmdoc)</code>
634 <h5 class="subsubsection">Public Key Cryptography</h5>
636 <p>NTPv4 supports the original NTPv3 symmetric key scheme
637 described in RFC-1305 and in addition the Autokey protocol,
638 which is based on public key cryptography.
639 The Autokey Version 2 protocol described on the Autokey Protocol
640 page verifies packet integrity using MD5 message digests
641 and verifies the source with digital signatures and any of several
642 digest/signature schemes.
643 Optional identity schemes described on the Identity Schemes
644 page and based on cryptographic challenge/response algorithms
646 Using all of these schemes provides strong security against
647 replay with or without modification, spoofing, masquerade
648 and most forms of clogging attacks.
650 <p>The Autokey protocol has several modes of operation
651 corresponding to the various NTP modes supported.
652 Most modes use a special cookie which can be
653 computed independently by the client and server,
654 but encrypted in transmission.
655 All modes use in addition a variant of the S-KEY scheme,
656 in which a pseudo-random key list is generated and used
658 These schemes are described along with an executive summary,
659 current status, briefing slides and reading list on the
660 <a href="#Autonomous-Authentication">Autonomous Authentication</a>
663 <p>The specific cryptographic environment used by Autokey servers
664 and clients is determined by a set of files
665 and soft links generated by the
666 <code>ntp-keygen(1ntpkeygenmdoc)</code>
668 This includes a required host key file,
669 required certificate file and optional sign key file,
670 leapsecond file and identity scheme files.
672 digest/signature scheme is specified in the X.509 certificate
673 along with the matching sign key.
674 There are several schemes
675 available in the OpenSSL software library, each identified
676 by a specific string such as
677 <code>md5WithRSAEncryption</code>,
678 which stands for the MD5 message digest with RSA
680 The current NTP distribution supports
681 all the schemes in the OpenSSL library, including
682 those based on RSA and DSA digital signatures.
684 <p>NTP secure groups can be used to define cryptographic compartments
685 and security hierarchies.
686 It is important that every host
687 in the group be able to construct a certificate trail to one
688 or more trusted hosts in the same group.
690 host runs the Autokey protocol to obtain the certificates
691 for all hosts along the trail to one or more trusted hosts.
692 This requires the configuration file in all hosts to be
693 engineered so that, even under anticipated failure conditions,
694 the NTP subnet will form such that every group host can find
695 a trail to at least one trusted host.
697 <h5 class="subsubsection">Naming and Addressing</h5>
699 <p>It is important to note that Autokey does not use DNS to
700 resolve addresses, since DNS can't be completely trusted
701 until the name servers have synchronized clocks.
702 The cryptographic name used by Autokey to bind the host identity
703 credentials and cryptographic values must be independent
704 of interface, network and any other naming convention.
705 The name appears in the host certificate in either or both
706 the subject and issuer fields, so protection against
707 DNS compromise is essential.
709 <p>By convention, the name of an Autokey host is the name returned
711 <code>gethostname(2)</code>
712 system call or equivalent in other systems.
714 model, there are no provisions to allow alternate names or aliases.
715 However, this is not to say that DNS aliases, different names
716 for each interface, etc., are constrained in any way.
718 <p>It is also important to note that Autokey verifies authenticity
719 using the host name, network address and public keys,
720 all of which are bound together by the protocol specifically
721 to deflect masquerade attacks.
722 For this reason Autokey
723 includes the source and destination IP addresses in message digest
724 computations and so the same addresses must be available
725 at both the server and client.
726 For this reason operation
727 with network address translation schemes is not possible.
728 This reflects the intended robust security model where government
729 and corporate NTP servers are operated outside firewall perimeters.
731 <h5 class="subsubsection">Operation</h5>
733 <p>A specific combination of authentication scheme (none,
734 symmetric key, public key) and identity scheme is called
735 a cryptotype, although not all combinations are compatible.
736 There may be management configurations where the clients,
737 servers and peers may not all support the same cryptotypes.
738 A secure NTPv4 subnet can be configured in many ways while
739 keeping in mind the principles explained above and
741 Note however that some cryptotype
742 combinations may successfully interoperate with each other,
743 but may not represent good security practice.
745 <p>The cryptotype of an association is determined at the time
746 of mobilization, either at configuration time or some time
747 later when a message of appropriate cryptotype arrives.
752 configuration command and no
756 subcommands are present, the association is not
757 authenticated; if the
759 subcommand is present, the association is authenticated
760 using the symmetric key ID specified; if the
762 subcommand is present, the association is authenticated
765 <p>When multiple identity schemes are supported in the Autokey
766 protocol, the first message exchange determines which one is used.
767 The client request message contains bits corresponding
768 to which schemes it has available.
769 The server response message
770 contains bits corresponding to which schemes it has available.
771 Both server and client match the received bits with their own
772 and select a common scheme.
774 <p>Following the principle that time is a public value,
775 a server responds to any client packet that matches
776 its cryptotype capabilities.
777 Thus, a server receiving
778 an unauthenticated packet will respond with an unauthenticated
779 packet, while the same server receiving a packet of a cryptotype
780 it supports will respond with packets of that cryptotype.
781 However, unconfigured broadcast or manycast client
782 associations or symmetric passive associations will not be
783 mobilized unless the server supports a cryptotype compatible
784 with the first packet received.
785 By default, unauthenticated associations will not be mobilized
786 unless overridden in a decidedly dangerous way.
788 <p>Some examples may help to reduce confusion.
789 Client Alice has no specific cryptotype selected.
790 Server Bob has both a symmetric key file and minimal Autokey files.
791 Alice's unauthenticated messages arrive at Bob, who replies with
792 unauthenticated messages.
793 Cathy has a copy of Bob's symmetric
794 key file and has selected key ID 4 in messages to Bob.
795 Bob verifies the message with his key ID 4.
797 same key and the message is verified, Bob sends Cathy a reply
798 authenticated with that key.
799 If verification fails,
800 Bob sends Cathy a thing called a crypto-NAK, which tells her
802 She can see the evidence using the
803 <code>ntpq(1ntpqmdoc)</code>
806 <p>Denise has rolled her own host key and certificate.
807 She also uses one of the identity schemes as Bob.
808 She sends the first Autokey message to Bob and they
809 both dance the protocol authentication and identity steps.
810 If all comes out okay, Denise and Bob continue as described above.
812 <p>It should be clear from the above that Bob can support
813 all the girls at the same time, as long as he has compatible
814 authentication and identity credentials.
815 Now, Bob can act just like the girls in his own choice of servers;
816 he can run multiple configured associations with multiple different
817 servers (or the same server, although that might not be useful).
818 But, wise security policy might preclude some cryptotype
819 combinations; for instance, running an identity scheme
820 with one server and no authentication with another might not be wise.
822 <h5 class="subsubsection">Key Management</h5>
824 <p>The cryptographic values used by the Autokey protocol are
825 incorporated as a set of files generated by the
826 <code>ntp-keygen(1ntpkeygenmdoc)</code>
827 utility program, including symmetric key, host key and
828 public certificate files, as well as sign key, identity parameters
829 and leapseconds files.
830 Alternatively, host and sign keys and
831 certificate files can be generated by the OpenSSL utilities
832 and certificates can be imported from public certificate
834 Note that symmetric keys are necessary for the
835 <code>ntpq(1ntpqmdoc)</code>
837 <code>ntpdc(1ntpdcmdoc)</code>
839 The remaining files are necessary only for the
842 <p>Certificates imported from OpenSSL or public certificate
843 authorities have certian limitations.
844 The certificate should be in ASN.1 syntax, X.509 Version 3
845 format and encoded in PEM, which is the same format
847 The overall length of the certificate encoded
848 in ASN.1 must not exceed 1024 bytes.
849 The subject distinguished
850 name field (CN) is the fully qualified name of the host
851 on which it is used; the remaining subject fields are ignored.
852 The certificate extension fields must not contain either
853 a subject key identifier or a issuer key identifier field;
854 however, an extended key usage field for a trusted host must
856 <code>trustRoot</code>;.
857 Other extension fields are ignored.
859 <h5 class="subsubsection">Authentication Commands</h5>
862 <dt><code>autokey</code> <code>[</code><kbd>logsec</kbd><code>]</code><dd>Specifies the interval between regenerations of the session key
863 list used with the Autokey protocol.
864 Note that the size of the key
865 list for each association depends on this interval and the current
867 The default value is 12 (4096 s or about 1.1 hours).
868 For poll intervals above the specified interval, a session key list
869 with a single entry will be regenerated for every message
871 <br><dt><code>controlkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the
872 <code>ntpq(1ntpqmdoc)</code>
873 utility, which uses the standard
874 protocol defined in RFC-1305.
878 the key identifier for a trusted key, where the value can be in the
879 range 1 to 65,535, inclusive.
880 <br><dt><code>crypto</code> <code>[cert </code><kbd>file</kbd><code>]</code> <code>[leap </code><kbd>file</kbd><code>]</code> <code>[randfile </code><kbd>file</kbd><code>]</code> <code>[host </code><kbd>file</kbd><code>]</code> <code>[sign </code><kbd>file</kbd><code>]</code> <code>[gq </code><kbd>file</kbd><code>]</code> <code>[gqpar </code><kbd>file</kbd><code>]</code> <code>[iffpar </code><kbd>file</kbd><code>]</code> <code>[mvpar </code><kbd>file</kbd><code>]</code> <code>[pw </code><kbd>password</kbd><code>]</code><dd>This command requires the OpenSSL library.
881 It activates public key
882 cryptography, selects the message digest and signature
883 encryption scheme and loads the required private and public
884 values described above.
885 If one or more files are left unspecified,
886 the default names are used as described above.
887 Unless the complete path and name of the file are specified, the
888 location of a file is relative to the keys directory specified
892 <span class="file">/usr/local/etc</span>.
893 Following are the subcommands:
895 <dt><code>cert</code> <kbd>file</kbd><dd>Specifies the location of the required host public certificate file.
896 This overrides the link
897 <span class="file">ntpkey_cert_</span><kbd>hostname</kbd>
898 in the keys directory.
899 <br><dt><code>gqpar</code> <kbd>file</kbd><dd>Specifies the location of the optional GQ parameters file.
902 <span class="file">ntpkey_gq_</span><kbd>hostname</kbd>
903 in the keys directory.
904 <br><dt><code>host</code> <kbd>file</kbd><dd>Specifies the location of the required host key file.
907 <span class="file">ntpkey_key_</span><kbd>hostname</kbd>
908 in the keys directory.
909 <br><dt><code>iffpar</code> <kbd>file</kbd><dd>Specifies the location of the optional IFF parameters file.
910 This overrides the link
911 <span class="file">ntpkey_iff_</span><kbd>hostname</kbd>
912 in the keys directory.
913 <br><dt><code>leap</code> <kbd>file</kbd><dd>Specifies the location of the optional leapsecond file.
914 This overrides the link
915 <span class="file">ntpkey_leap</span>
916 in the keys directory.
917 <br><dt><code>mvpar</code> <kbd>file</kbd><dd>Specifies the location of the optional MV parameters file.
918 This overrides the link
919 <span class="file">ntpkey_mv_</span><kbd>hostname</kbd>
920 in the keys directory.
921 <br><dt><code>pw</code> <kbd>password</kbd><dd>Specifies the password to decrypt files containing private keys and
923 This is required only if these files have been
925 <br><dt><code>randfile</code> <kbd>file</kbd><dd>Specifies the location of the random seed file used by the OpenSSL
927 The defaults are described in the main text above.
928 <br><dt><code>sign</code> <kbd>file</kbd><dd>Specifies the location of the optional sign key file.
931 <span class="file">ntpkey_sign_</span><kbd>hostname</kbd>
932 in the keys directory.
934 not found, the host key is also the sign key.
936 <br><dt><code>keys</code> <kbd>keyfile</kbd><dd>Specifies the complete path and location of the MD5 key file
937 containing the keys and key identifiers used by
938 <code>ntpd(1ntpdmdoc)</code>,
939 <code>ntpq(1ntpqmdoc)</code>
941 <code>ntpdc(1ntpdcmdoc)</code>
942 when operating with symmetric key cryptography.
943 This is the same operation as the
946 <br><dt><code>keysdir</code> <kbd>path</kbd><dd>This command specifies the default directory path for
947 cryptographic keys, parameters and certificates.
949 <span class="file">/usr/local/etc/</span>.
950 <br><dt><code>requestkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the
951 <code>ntpdc(1ntpdcmdoc)</code>
952 utility program, which uses a
953 proprietary protocol specific to this implementation of
954 <code>ntpd(1ntpdmdoc)</code>.
957 argument is a key identifier
958 for the trusted key, where the value can be in the range 1 to
960 <br><dt><code>revoke</code> <kbd>logsec</kbd><dd>Specifies the interval between re-randomization of certain
961 cryptographic values used by the Autokey scheme, as a power of 2 in
963 These values need to be updated frequently in order to
964 deflect brute-force attacks on the algorithms of the scheme;
965 however, updating some values is a relatively expensive operation.
966 The default interval is 16 (65,536 s or about 18 hours).
968 intervals above the specified interval, the values will be updated
969 for every message sent.
970 <br><dt><code>trustedkey</code> <kbd>key</kbd> <kbd>...</kbd><dd>Specifies the key identifiers which are trusted for the
971 purposes of authenticating peers with symmetric key cryptography,
972 as well as keys used by the
973 <code>ntpq(1ntpqmdoc)</code>
975 <code>ntpdc(1ntpdcmdoc)</code>
977 The authentication procedures require that both the local
978 and remote servers share the same key and key identifier for this
979 purpose, although different keys can be used with different
983 arguments are 32-bit unsigned
984 integers with values from 1 to 65,535.
987 <h5 class="subsubsection">Error Codes</h5>
989 <p>The following error codes are reported via the NTP control
990 and monitoring protocol trap mechanism.
992 <dt>101<dd>(bad field format or length)
993 The packet has invalid version, length or format.
994 <br><dt>102<dd>(bad timestamp)
995 The packet timestamp is the same or older than the most recent received.
996 This could be due to a replay or a server clock time step.
997 <br><dt>103<dd>(bad filestamp)
998 The packet filestamp is the same or older than the most recent received.
999 This could be due to a replay or a key file generation error.
1000 <br><dt>104<dd>(bad or missing public key)
1001 The public key is missing, has incorrect format or is an unsupported type.
1002 <br><dt>105<dd>(unsupported digest type)
1003 The server requires an unsupported digest/signature scheme.
1004 <br><dt>106<dd>(mismatched digest types)
1006 <br><dt>107<dd>(bad signature length)
1007 The signature length does not match the current public key.
1008 <br><dt>108<dd>(signature not verified)
1009 The message fails the signature check.
1010 It could be bogus or signed by a
1011 different private key.
1012 <br><dt>109<dd>(certificate not verified)
1013 The certificate is invalid or signed with the wrong key.
1014 <br><dt>110<dd>(certificate not verified)
1015 The certificate is not yet valid or has expired or the signature could not
1017 <br><dt>111<dd>(bad or missing cookie)
1018 The cookie is missing, corrupted or bogus.
1019 <br><dt>112<dd>(bad or missing leapseconds table)
1020 The leapseconds table is missing, corrupted or bogus.
1021 <br><dt>113<dd>(bad or missing certificate)
1022 The certificate is missing, corrupted or bogus.
1023 <br><dt>114<dd>(bad or missing identity)
1024 The identity key is missing, corrupt or bogus.
1028 <a name="Monitoring-Support"></a>
1032 <h4 class="subsection">Monitoring Support</h4>
1034 <p><code>ntpd(1ntpdmdoc)</code>
1035 includes a comprehensive monitoring facility suitable
1036 for continuous, long term recording of server and client
1037 timekeeping performance.
1039 <code>statistics</code>
1041 for a listing and example of each type of statistics currently
1043 Statistic files are managed using file generation sets
1045 <span class="file">./scripts</span>
1046 directory of the source code distribution.
1048 these facilities and
1049 <span class="sc">unix</span>
1050 <code>cron(8)</code>
1051 jobs, the data can be
1052 automatically summarized and archived for retrospective analysis.
1054 <h5 class="subsubsection">Monitoring Commands</h5>
1057 <dt><code>statistics</code> <kbd>name</kbd> <kbd>...</kbd><dd>Enables writing of statistics records.
1058 Currently, eight kinds of
1060 statistics are supported.
1062 <dt><code>clockstats</code><dd>Enables recording of clock driver statistics information.
1064 received from a clock driver appends a line of the following form to
1065 the file generation set named
1066 <code>clockstats</code>:
1067 <pre class="verbatim">
1068 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1071 <p>The first two fields show the date (Modified Julian Day) and time
1072 (seconds and fraction past UTC midnight).
1073 The next field shows the
1074 clock address in dotted-quad notation.
1075 The final field shows the last
1076 timecode received from the clock in decoded ASCII format, where
1078 In some clock drivers a good deal of additional information
1079 can be gathered and displayed as well.
1080 See information specific to each
1081 clock for further details.
1082 <br><dt><code>cryptostats</code><dd>This option requires the OpenSSL cryptographic software library.
1084 enables recording of cryptographic public key protocol information.
1085 Each message received by the protocol module appends a line of the
1086 following form to the file generation set named
1087 <code>cryptostats</code>:
1088 <pre class="verbatim">
1089 49213 525.624 127.127.4.1 message
1092 <p>The first two fields show the date (Modified Julian Day) and time
1093 (seconds and fraction past UTC midnight).
1094 The next field shows the peer
1095 address in dotted-quad notation, The final message field includes the
1096 message type and certain ancillary information.
1098 <a href="#Authentication-Options">Authentication Options</a>
1099 section for further information.
1100 <br><dt><code>loopstats</code><dd>Enables recording of loop filter statistics information.
1102 update of the local clock outputs a line of the following form to
1103 the file generation set named
1104 <code>loopstats</code>:
1105 <pre class="verbatim">
1106 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1109 <p>The first two fields show the date (Modified Julian Day) and
1110 time (seconds and fraction past UTC midnight).
1111 The next five fields
1112 show time offset (seconds), frequency offset (parts per million -
1113 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1114 discipline time constant.
1115 <br><dt><code>peerstats</code><dd>Enables recording of peer statistics information.
1117 statistics records of all peers of a NTP server and of special
1118 signals, where present and configured.
1119 Each valid update appends a
1120 line of the following form to the current element of a file
1121 generation set named
1122 <code>peerstats</code>:
1123 <pre class="verbatim">
1124 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674
1127 <p>The first two fields show the date (Modified Julian Day) and
1128 time (seconds and fraction past UTC midnight).
1130 show the peer address in dotted-quad notation and status,
1132 The status field is encoded in hex in the format
1133 described in Appendix A of the NTP specification RFC 1305.
1134 The final four fields show the offset,
1135 delay, dispersion and RMS jitter, all in seconds.
1136 <br><dt><code>rawstats</code><dd>Enables recording of raw-timestamp statistics information.
1138 includes statistics records of all peers of a NTP server and of
1139 special signals, where present and configured.
1141 received from a peer or clock driver appends a line of the
1142 following form to the file generation set named
1143 <code>rawstats</code>:
1144 <pre class="verbatim">
1145 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1148 <p>The first two fields show the date (Modified Julian Day) and
1149 time (seconds and fraction past UTC midnight).
1151 show the remote peer or clock address followed by the local address
1152 in dotted-quad notation.
1153 The final four fields show the originate,
1154 receive, transmit and final NTP timestamps in order.
1156 values are as received and before processing by the various data
1157 smoothing and mitigation algorithms.
1158 <br><dt><code>sysstats</code><dd>Enables recording of ntpd statistics counters on a periodic basis.
1160 hour a line of the following form is appended to the file generation
1162 <code>sysstats</code>:
1163 <pre class="verbatim">
1164 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1167 <p>The first two fields show the date (Modified Julian Day) and time
1168 (seconds and fraction past UTC midnight).
1169 The remaining ten fields show
1170 the statistics counter values accumulated since the last generated
1173 <dt>Time since restart <code>36000</code><dd>Time in hours since the system was last rebooted.
1174 <br><dt>Packets received <code>81965</code><dd>Total number of packets received.
1175 <br><dt>Packets processed <code>0</code><dd>Number of packets received in response to previous packets sent
1176 <br><dt>Current version <code>9546</code><dd>Number of packets matching the current NTP version.
1177 <br><dt>Previous version <code>56</code><dd>Number of packets matching the previous NTP version.
1178 <br><dt>Bad version <code>71793</code><dd>Number of packets matching neither NTP version.
1179 <br><dt>Access denied <code>512</code><dd>Number of packets denied access for any reason.
1180 <br><dt>Bad length or format <code>540</code><dd>Number of packets with invalid length, format or port number.
1181 <br><dt>Bad authentication <code>10</code><dd>Number of packets not verified as authentic.
1182 <br><dt>Rate exceeded <code>147</code><dd>Number of packets discarded due to rate limitation.
1184 <br><dt><code>statsdir</code> <kbd>directory_path</kbd><dd>Indicates the full path of a directory where statistics files
1185 should be created (see below).
1187 the (otherwise constant)
1188 <code>filegen</code>
1189 filename prefix to be modified for file generation sets, which
1190 is useful for handling statistics logs.
1191 <br><dt><code>filegen</code> <kbd>name</kbd> <code>[file </code><kbd>filename</kbd><code>]</code> <code>[type </code><kbd>typename</kbd><code>]</code> <code>[link | nolink]</code> <code>[enable | disable]</code><dd>Configures setting of generation file set name.
1193 file sets provide a means for handling files that are
1194 continuously growing during the lifetime of a server.
1195 Server statistics are a typical example for such files.
1196 Generation file sets provide access to a set of files used
1197 to store the actual data.
1198 At any time at most one element
1199 of the set is being written to.
1200 The type given specifies
1201 when and how data will be directed to a new element of the set.
1202 This way, information stored in elements of a file set
1203 that are currently unused are available for administrational
1204 operations without the risk of disturbing the operation of ntpd.
1205 (Most important: they can be removed to free space for new data
1208 <p>Note that this command can be sent from the
1209 <code>ntpdc(1ntpdcmdoc)</code>
1210 program running at a remote location.
1212 <dt><code>name</code><dd>This is the type of the statistics records, as shown in the
1213 <code>statistics</code>
1215 <br><dt><code>file</code> <kbd>filename</kbd><dd>This is the file name for the statistics records.
1217 members are built from three concatenated elements
1218 <code>prefix</code>,
1219 <code>filename</code>
1221 <code>suffix</code>:
1223 <dt><code>prefix</code><dd>This is a constant filename path.
1224 It is not subject to
1225 modifications via the
1228 It is defined by the
1229 server, usually specified as a compile-time constant.
1231 however, be configurable for individual file generation sets
1233 For example, the prefix used with
1234 <kbd>loopstats</kbd>
1236 <kbd>peerstats</kbd>
1237 generation can be configured using the
1239 option explained above.
1240 <br><dt><code>filename</code><dd>This string is directly concatenated to the prefix mentioned
1241 above (no intervening
1243 This can be modified using
1244 the file argument to the
1248 <span class="file">..</span>
1250 allowed in this component to prevent filenames referring to
1251 parts outside the filesystem hierarchy denoted by
1253 <br><dt><code>suffix</code><dd>This part is reflects individual elements of a file set.
1255 generated according to the type of a file set.
1257 <br><dt><code>type</code> <kbd>typename</kbd><dd>A file generation set is characterized by its type.
1259 types are supported:
1261 <dt><code>none</code><dd>The file set is actually a single plain file.
1262 <br><dt><code>pid</code><dd>One element of file set is used per incarnation of a ntpd
1264 This type does not perform any changes to file set
1265 members during runtime, however it provides an easy way of
1266 separating files belonging to different
1267 <code>ntpd(1ntpdmdoc)</code>
1268 server incarnations.
1269 The set member filename is built by appending a
1276 appending the decimal representation of the process ID of the
1277 <code>ntpd(1ntpdmdoc)</code>
1279 <br><dt><code>day</code><dd>One file generation set element is created per day.
1281 defined as the period between 00:00 and 24:00 UTC.
1283 member suffix consists of a
1285 and a day specification in
1287 <code>YYYYMMdd</code>.
1289 is a 4-digit year number (e.g., 1992).
1291 is a two digit month number.
1293 is a two digit day number.
1294 Thus, all information written at 10 December 1992 would end up
1297 <kbd>filename</kbd>.19921210.
1298 <br><dt><code>week</code><dd>Any file set member contains data related to a certain week of
1300 The term week is defined by computing day-of-year
1302 Elements of such a file generation set are
1303 distinguished by appending the following suffix to the file set
1304 filename base: A dot, a 4-digit year number, the letter
1306 and a 2-digit week number.
1307 For example, information from January,
1308 10th 1992 would end up in a file with suffix
1309 .No . Ns Ar 1992W1 .
1310 <br><dt><code>month</code><dd>One generation file set element is generated per month.
1312 file name suffix consists of a dot, a 4-digit year number, and
1314 <br><dt><code>year</code><dd>One generation file element is generated per year.
1316 suffix consists of a dot and a 4 digit year number.
1317 <br><dt><code>age</code><dd>This type of file generation sets changes to a new element of
1318 the file set every 24 hours of server operation.
1320 suffix consists of a dot, the letter
1322 and an 8-digit number.
1323 This number is taken to be the number of seconds the server is
1324 running at the start of the corresponding 24-hour period.
1325 Information is only written to a file generation by specifying
1326 <code>enable</code>;
1327 output is prevented by specifying
1328 <code>disable</code>.
1330 <br><dt><code>link</code> | <code>nolink</code><dd>It is convenient to be able to access the current element of a file
1331 generation set by a fixed name.
1332 This feature is enabled by
1336 <code>nolink</code>.
1337 If link is specified, a
1338 hard link from the current file set element to a file without
1340 When there is already a file with this name and
1341 the number of links of this file is one, it is renamed appending a
1345 <code>ntpd(1ntpdmdoc)</code>
1348 number of links is greater than one, the file is unlinked.
1350 allows the current file to be accessed by a constant name.
1351 <br><dt><code>enable</code> <code>|</code> <code>disable</code><dd>Enables or disables the recording function.
1357 <a name="Access-Control-Support"></a>
1361 <h4 class="subsection">Access Control Support</h4>
1364 <code>ntpd(1ntpdmdoc)</code>
1365 daemon implements a general purpose address/mask based restriction
1367 The list contains address/match entries sorted first
1368 by increasing address values and and then by increasing mask values.
1369 A match occurs when the bitwise AND of the mask and the packet
1370 source address is equal to the bitwise AND of the mask and
1371 address in the list.
1372 The list is searched in order with the
1373 last match found defining the restriction flags associated
1375 Additional information and examples can be found in the
1376 "Notes on Configuring NTP and Setting up a NTP Subnet"
1378 (available as part of the HTML documentation
1380 <span class="file">/usr/share/doc/ntp</span>).
1382 <p>The restriction facility was implemented in conformance
1383 with the access policies for the original NSFnet backbone
1385 Later the facility was expanded to deflect
1386 cryptographic and clogging attacks.
1387 While this facility may
1388 be useful for keeping unwanted or broken or malicious clients
1389 from congesting innocent servers, it should not be considered
1390 an alternative to the NTP authentication facilities.
1391 Source address based restrictions are easily circumvented
1392 by a determined cracker.
1394 <p>Clients can be denied service because they are explicitly
1395 included in the restrict list created by the
1396 <code>restrict</code>
1398 or implicitly as the result of cryptographic or rate limit
1400 Cryptographic violations include certificate
1401 or identity verification failure; rate limit violations generally
1402 result from defective NTP implementations that send packets
1404 Some violations cause denied service
1405 only for the offending packet, others cause denied service
1406 for a timed period and others cause the denied service for
1407 an indefinite period.
1408 When a client or network is denied access
1409 for an indefinite period, the only way at present to remove
1410 the restrictions is by restarting the server.
1412 <h5 class="subsubsection">The Kiss-of-Death Packet</h5>
1414 <p>Ordinarily, packets denied service are simply dropped with no
1415 further action except incrementing statistics counters.
1417 more proactive response is needed, such as a server message that
1418 explicitly requests the client to stop sending and leave a message
1419 for the system operator.
1420 A special packet format has been created
1421 for this purpose called the "kiss-of-death" (KoD) packet.
1422 KoD packets have the leap bits set unsynchronized and stratum set
1423 to zero and the reference identifier field set to a four-byte
1426 <code>noserve</code>
1428 <code>notrust</code>
1429 flag of the matching restrict list entry is set,
1430 the code is "DENY"; if the
1431 <code>limited</code>
1432 flag is set and the rate limit
1433 is exceeded, the code is "RATE".
1434 Finally, if a cryptographic violation occurs, the code is "CRYP".
1436 <p>A client receiving a KoD performs a set of sanity checks to
1437 minimize security exposure, then updates the stratum and
1438 reference identifier peer variables, sets the access
1439 denied (TEST4) bit in the peer flash variable and sends
1440 a message to the log.
1441 As long as the TEST4 bit is set,
1442 the client will send no further packets to the server.
1443 The only way at present to recover from this condition is
1444 to restart the protocol at both the client and server.
1446 happens automatically at the client when the association times out.
1447 It will happen at the server only if the server operator cooperates.
1449 <h5 class="subsubsection">Access Control Commands</h5>
1452 <dt><code>discard</code> <code>[average </code><kbd>avg</kbd><code>]</code> <code>[minimum </code><kbd>min</kbd><code>]</code> <code>[monitor </code><kbd>prob</kbd><code>]</code><dd>Set the parameters of the
1453 <code>limited</code>
1454 facility which protects the server from
1457 <code>average</code>
1458 subcommand specifies the minimum average packet
1460 <code>minimum</code>
1461 subcommand specifies the minimum packet spacing.
1462 Packets that violate these minima are discarded
1463 and a kiss-o'-death packet returned if enabled.
1465 minimum average and minimum are 5 and 2, respectively.
1467 <code>monitor</code>
1468 subcommand specifies the probability of discard
1469 for packets that overflow the rate-control window.
1470 <br><dt><code>restrict</code> <code>address</code> <code>[mask </code><kbd>mask</kbd><code>]</code> <code>[ippeerlimit </code><kbd>int</kbd><code>]</code> <code>[</code><kbd>flag</kbd> <kbd>...</kbd><code>]</code><dd>The
1472 argument expressed in
1473 dotted-quad form is the address of a host or network.
1476 argument can be a valid host DNS name.
1479 argument expressed in dotted-quad form defaults to
1480 <code>255.255.255.255</code>,
1483 is treated as the address of an individual host.
1484 A default entry (address
1485 <code>0.0.0.0</code>,
1487 <code>0.0.0.0</code>)
1488 is always included and is always the first entry in the list.
1489 Note that text string
1490 <code>default</code>,
1491 with no mask option, may
1492 be used to indicate the default entry.
1494 <code>ippeerlimit</code>
1495 directive limits the number of peer requests for each IP to
1497 where a value of -1 means "unlimited", the current default.
1498 A value of 0 means "none".
1499 There would usually be at most 1 peering request per IP,
1500 but if the remote peering requests are behind a proxy
1501 there could well be more than 1 per IP.
1502 In the current implementation,
1505 restricts access, i.e., an entry with no flags indicates that free
1506 access to the server is to be given.
1507 The flags are not orthogonal,
1508 in that more restrictive flags will often make less restrictive
1510 The flags can generally be classed into two
1511 categories, those which restrict time service and those which
1512 restrict informational queries and attempts to do run-time
1513 reconfiguration of the server.
1514 One or more of the following flags
1517 <dt><code>ignore</code><dd>Deny packets of all kinds, including
1518 <code>ntpq(1ntpqmdoc)</code>
1520 <code>ntpdc(1ntpdcmdoc)</code>
1522 <br><dt><code>kod</code><dd>If this flag is set when an access violation occurs, a kiss-o'-death
1523 (KoD) packet is sent.
1524 KoD packets are rate limited to no more than one
1526 If another KoD packet occurs within one second after the
1527 last one, the packet is dropped.
1528 <br><dt><code>limited</code><dd>Deny service if the packet spacing violates the lower limits specified
1530 <code>discard</code>
1532 A history of clients is kept using the
1533 monitoring capability of
1534 <code>ntpd(1ntpdmdoc)</code>.
1535 Thus, monitoring is always active as
1536 long as there is a restriction entry with the
1537 <code>limited</code>
1539 <br><dt><code>lowpriotrap</code><dd>Declare traps set by matching hosts to be low priority.
1541 number of traps a server can maintain is limited (the current limit
1543 Traps are usually assigned on a first come, first served
1544 basis, with later trap requestors being denied service.
1546 modifies the assignment algorithm by allowing low priority traps to
1547 be overridden by later requests for normal priority traps.
1548 <br><dt><code>noepeer</code><dd>Deny ephemeral peer requests,
1549 even if they come from an authenticated source.
1550 Note that the ability to use a symmetric key for authentication may be restricted to
1551 one or more IPs or subnets via the third field of the
1552 <span class="file">ntp.keys</span>
1554 This restriction is not enabled by default,
1555 to maintain backward compatability.
1557 <code>noepeer</code>
1558 to become the default in ntp-4.4.
1559 <br><dt><code>nomodify</code><dd>Deny
1560 <code>ntpq(1ntpqmdoc)</code>
1562 <code>ntpdc(1ntpdcmdoc)</code>
1563 queries which attempt to modify the state of the
1564 server (i.e., run time reconfiguration).
1565 Queries which return
1566 information are permitted.
1567 <br><dt><code>noquery</code><dd>Deny
1568 <code>ntpq(1ntpqmdoc)</code>
1570 <code>ntpdc(1ntpdcmdoc)</code>
1572 Time service is not affected.
1573 <br><dt><code>nopeer</code><dd>Deny unauthenticated packets which would result in mobilizing a new association.
1575 broadcast and symmetric active packets
1576 when a configured association does not exist.
1579 associations, so if you want to use servers from a
1581 directive and also want to use
1583 by default, you'll want a
1584 <code>restrict source ...</code>
1585 line as well that does
1590 <br><dt><code>noserve</code><dd>Deny all packets except
1591 <code>ntpq(1ntpqmdoc)</code>
1593 <code>ntpdc(1ntpdcmdoc)</code>
1595 <br><dt><code>notrap</code><dd>Decline to provide mode 6 control message trap service to matching
1597 The trap service is a subsystem of the
1598 <code>ntpq(1ntpqmdoc)</code>
1600 protocol which is intended for use by remote event logging programs.
1601 <br><dt><code>notrust</code><dd>Deny service unless the packet is cryptographically authenticated.
1602 <br><dt><code>ntpport</code><dd>This is actually a match algorithm modifier, rather than a
1604 Its presence causes the restriction entry to be
1605 matched only if the source port in the packet is the standard NTP
1608 <code>ntpport</code>
1610 <code>non-ntpport</code>
1614 <code>ntpport</code>
1615 is considered more specific and
1616 is sorted later in the list.
1617 <br><dt><code>version</code><dd>Deny packets that do not match the current NTP version.
1620 <p>Default restriction list entries with the flags ignore, interface,
1621 ntpport, for each of the local host's interface addresses are
1622 inserted into the table at startup to prevent the server
1623 from attempting to synchronize to its own time.
1624 A default entry is also always present, though if it is
1625 otherwise unconfigured; no flags are associated
1626 with the default entry (i.e., everything besides your own
1627 NTP server is unrestricted).
1631 <a name="Automatic-NTP-Configuration-Options"></a>
1635 <h4 class="subsection">Automatic NTP Configuration Options</h4>
1637 <h5 class="subsubsection">Manycasting</h5>
1639 <p>Manycasting is a automatic discovery and configuration paradigm
1641 It is intended as a means for a multicast client
1642 to troll the nearby network neighborhood to find cooperating
1643 manycast servers, validate them using cryptographic means
1644 and evaluate their time values with respect to other servers
1645 that might be lurking in the vicinity.
1646 The intended result is that each manycast client mobilizes
1647 client associations with some number of the "best"
1648 of the nearby manycast servers, yet automatically reconfigures
1649 to sustain this number of servers should one or another fail.
1651 <p>Note that the manycasting paradigm does not coincide
1652 with the anycast paradigm described in RFC-1546,
1653 which is designed to find a single server from a clique
1654 of servers providing the same service.
1655 The manycast paradigm is designed to find a plurality
1656 of redundant servers satisfying defined optimality criteria.
1658 <p>Manycasting can be used with either symmetric key
1659 or public key cryptography.
1660 The public key infrastructure (PKI)
1661 offers the best protection against compromised keys
1662 and is generally considered stronger, at least with relatively
1664 It is implemented using the Autokey protocol and
1665 the OpenSSL cryptographic library available from
1666 <code>http://www.openssl.org/</code>.
1667 The library can also be used with other NTPv4 modes
1668 as well and is highly recommended, especially for broadcast modes.
1670 <p>A persistent manycast client association is configured
1672 <code>manycastclient</code>
1673 command, which is similar to the
1675 command but with a multicast (IPv4 class
1680 The IANA has designated IPv4 address 224.1.1.1
1681 and IPv6 address FF05::101 (site local) for NTP.
1682 When more servers are needed, it broadcasts manycast
1683 client messages to this address at the minimum feasible rate
1684 and minimum feasible time-to-live (TTL) hops, depending
1685 on how many servers have already been found.
1686 There can be as many manycast client associations
1687 as different group address, each one serving as a template
1688 for a future ephemeral unicast client/server association.
1690 <p>Manycast servers configured with the
1691 <code>manycastserver</code>
1692 command listen on the specified group address for manycast
1694 Note the distinction between manycast client,
1695 which actively broadcasts messages, and manycast server,
1696 which passively responds to them.
1697 If a manycast server is
1698 in scope of the current TTL and is itself synchronized
1699 to a valid source and operating at a stratum level equal
1700 to or lower than the manycast client, it replies to the
1701 manycast client message with an ordinary unicast server message.
1703 <p>The manycast client receiving this message mobilizes
1704 an ephemeral client/server association according to the
1705 matching manycast client template, but only if cryptographically
1706 authenticated and the server stratum is less than or equal
1707 to the client stratum.
1708 Authentication is explicitly required
1709 and either symmetric key or public key (Autokey) can be used.
1710 Then, the client polls the server at its unicast address
1711 in burst mode in order to reliably set the host clock
1712 and validate the source.
1713 This normally results
1714 in a volley of eight client/server at 2-s intervals
1715 during which both the synchronization and cryptographic
1716 protocols run concurrently.
1717 Following the volley,
1718 the client runs the NTP intersection and clustering
1719 algorithms, which act to discard all but the "best"
1720 associations according to stratum and synchronization
1722 The surviving associations then continue
1723 in ordinary client/server mode.
1725 <p>The manycast client polling strategy is designed to reduce
1726 as much as possible the volume of manycast client messages
1727 and the effects of implosion due to near-simultaneous
1728 arrival of manycast server messages.
1729 The strategy is determined by the
1730 <code>manycastclient</code>,
1734 configuration commands.
1735 The manycast poll interval is
1736 normally eight times the system poll interval,
1737 which starts out at the
1738 <code>minpoll</code>
1739 value specified in the
1740 <code>manycastclient</code>,
1741 command and, under normal circumstances, increments to the
1742 <code>maxpolll</code>
1743 value specified in this command.
1744 Initially, the TTL is
1745 set at the minimum hops specified by the
1748 At each retransmission the TTL is increased until reaching
1749 the maximum hops specified by this command or a sufficient
1750 number client associations have been found.
1751 Further retransmissions use the same TTL.
1753 <p>The quality and reliability of the suite of associations
1754 discovered by the manycast client is determined by the NTP
1755 mitigation algorithms and the
1756 <code>minclock</code>
1758 <code>minsane</code>
1759 values specified in the
1761 configuration command.
1763 <code>minsane</code>
1764 candidate servers must be available and the mitigation
1765 algorithms produce at least
1766 <code>minclock</code>
1767 survivors in order to synchronize the clock.
1768 Byzantine agreement principles require at least four
1769 candidates in order to correctly discard a single falseticker.
1770 For legacy purposes,
1771 <code>minsane</code>
1773 <code>minclock</code>
1775 For manycast service
1776 <code>minsane</code>
1777 should be explicitly set to 4, assuming at least that
1778 number of servers are available.
1781 <code>minclock</code>
1782 servers are found, the manycast poll interval is immediately
1784 <code>maxpoll</code>.
1786 <code>minclock</code>
1787 servers are found when the TTL has reached the maximum hops,
1788 the manycast poll interval is doubled.
1789 For each transmission
1790 after that, the poll interval is doubled again until
1791 reaching the maximum of eight times
1792 <code>maxpoll</code>.
1793 Further transmissions use the same poll interval and
1795 Note that while all this is going on,
1796 each client/server association found is operating normally
1797 it the system poll interval.
1799 <p>Administratively scoped multicast boundaries are normally
1800 specified by the network router configuration and,
1801 in the case of IPv6, the link/site scope prefix.
1802 By default, the increment for TTL hops is 32 starting
1803 from 31; however, the
1805 configuration command can be
1806 used to modify the values to match the scope rules.
1808 <p>It is often useful to narrow the range of acceptable
1809 servers which can be found by manycast client associations.
1810 Because manycast servers respond only when the client
1811 stratum is equal to or greater than the server stratum,
1812 primary (stratum 1) servers fill find only primary servers
1813 in TTL range, which is probably the most common objective.
1814 However, unless configured otherwise, all manycast clients
1815 in TTL range will eventually find all primary servers
1816 in TTL range, which is probably not the most common
1817 objective in large networks.
1820 command can be used to modify this behavior.
1821 Servers with stratum below
1824 <code>ceiling</code>
1827 command are strongly discouraged during the selection
1828 process; however, these servers may be temporally
1829 accepted if the number of servers within TTL range is
1831 <code>minclock</code>.
1833 <p>The above actions occur for each manycast client message,
1834 which repeats at the designated poll interval.
1835 However, once the ephemeral client association is mobilized,
1836 subsequent manycast server replies are discarded,
1837 since that would result in a duplicate association.
1838 If during a poll interval the number of client associations
1840 <code>minclock</code>,
1841 all manycast client prototype associations are reset
1842 to the initial poll interval and TTL hops and operation
1843 resumes from the beginning.
1844 It is important to avoid
1845 frequent manycast client messages, since each one requires
1846 all manycast servers in TTL range to respond.
1847 The result could well be an implosion, either minor or major,
1848 depending on the number of servers in range.
1849 The recommended value for
1850 <code>maxpoll</code>
1853 <p>It is possible and frequently useful to configure a host
1854 as both manycast client and manycast server.
1855 A number of hosts configured this way and sharing a common
1856 group address will automatically organize themselves
1857 in an optimum configuration based on stratum and
1858 synchronization distance.
1859 For example, consider an NTP
1860 subnet of two primary servers and a hundred or more
1862 With two exceptions, all servers
1863 and clients have identical configuration files including both
1864 <code>multicastclient</code>
1866 <code>multicastserver</code>
1867 commands using, for instance, multicast group address
1869 The only exception is that each primary server
1870 configuration file must include commands for the primary
1871 reference source such as a GPS receiver.
1873 <p>The remaining configuration files for all secondary
1874 servers and clients have the same contents, except for the
1876 command, which is specific for each stratum level.
1877 For stratum 1 and stratum 2 servers, that command is
1879 For stratum 3 and above servers the
1881 value is set to the intended stratum number.
1882 Thus, all stratum 3 configuration files are identical,
1883 all stratum 4 files are identical and so forth.
1885 <p>Once operations have stabilized in this scenario,
1886 the primary servers will find the primary reference source
1887 and each other, since they both operate at the same
1888 stratum (1), but not with any secondary server or client,
1889 since these operate at a higher stratum.
1891 servers will find the servers at the same stratum level.
1892 If one of the primary servers loses its GPS receiver,
1893 it will continue to operate as a client and other clients
1894 will time out the corresponding association and
1895 re-associate accordingly.
1897 <p>Some administrators prefer to avoid running
1898 <code>ntpd(1ntpdmdoc)</code>
1899 continuously and run either
1900 <code>sntp(1sntpmdoc)</code>
1902 <code>ntpd(1ntpdmdoc)</code>
1905 In either case the servers must be
1906 configured in advance and the program fails if none are
1907 available when the cron job runs.
1909 application of manycast is with
1910 <code>ntpd(1ntpdmdoc)</code>
1912 The program wakes up, scans the local landscape looking
1913 for the usual suspects, selects the best from among
1914 the rascals, sets the clock and then departs.
1915 Servers do not have to be configured in advance and
1916 all clients throughout the network can have the same
1919 <h5 class="subsubsection">Manycast Interactions with Autokey</h5>
1921 <p>Each time a manycast client sends a client mode packet
1922 to a multicast group address, all manycast servers
1923 in scope generate a reply including the host name
1925 The manycast clients then run
1926 the Autokey protocol, which collects and verifies
1927 all certificates involved.
1928 Following the burst interval
1929 all but three survivors are cast off,
1930 but the certificates remain in the local cache.
1931 It often happens that several complete signing trails
1932 from the client to the primary servers are collected in this way.
1934 <p>About once an hour or less often if the poll interval
1935 exceeds this, the client regenerates the Autokey key list.
1936 This is in general transparent in client/server mode.
1937 However, about once per day the server private value
1938 used to generate cookies is refreshed along with all
1939 manycast client associations.
1941 cryptographic values including certificates is refreshed.
1942 If a new certificate has been generated since
1943 the last refresh epoch, it will automatically revoke
1944 all prior certificates that happen to be in the
1946 At the same time, the manycast
1947 scheme starts all over from the beginning and
1948 the expanding ring shrinks to the minimum and increments
1949 from there while collecting all servers in scope.
1951 <h5 class="subsubsection">Broadcast Options</h5>
1954 <dt><code>tos</code> <code>[bcpollbstep </code><kbd>gate</kbd><code>]</code><dd>This command provides a way to delay,
1955 by the specified number of broadcast poll intervals,
1956 believing backward time steps from a broadcast server.
1957 Broadcast time networks are expected to be trusted.
1958 In the event a broadcast server's time is stepped backwards,
1959 there is clear benefit to having the clients notice this change
1960 as soon as possible.
1961 Attacks such as replay attacks can happen, however,
1962 and even though there are a number of protections built in to
1963 broadcast mode, attempts to perform a replay attack are possible.
1964 This value defaults to 0, but can be changed
1965 to any number of poll intervals between 0 and 4.
1968 <h5 class="subsubsection">Manycast Options</h5>
1971 <dt><code>tos</code> <code>[ceiling </code><kbd>ceiling</kbd><code> | cohort { 0 | 1 } | floor </code><kbd>floor</kbd><code> | minclock </code><kbd>minclock</kbd><code> | minsane </code><kbd>minsane</kbd><code>]</code><dd>This command affects the clock selection and clustering
1973 It can be used to select the quality and
1974 quantity of peers used to synchronize the system clock
1975 and is most useful in manycast mode.
1976 The variables operate
1979 <dt><code>ceiling</code> <kbd>ceiling</kbd><dd>Peers with strata above
1980 <code>ceiling</code>
1981 will be discarded if there are at least
1982 <code>minclock</code>
1984 This value defaults to 15, but can be changed
1985 to any number from 1 to 15.
1986 <br><dt><code>cohort</code> <code>{0 | 1}</code><dd>This is a binary flag which enables (0) or disables (1)
1987 manycast server replies to manycast clients with the same
1989 This is useful to reduce implosions where
1990 large numbers of clients with the same stratum level
1992 The default is to enable these replies.
1993 <br><dt><code>floor</code> <kbd>floor</kbd><dd>Peers with strata below
1995 will be discarded if there are at least
1996 <code>minclock</code>
1998 This value defaults to 1, but can be changed
1999 to any number from 1 to 15.
2000 <br><dt><code>minclock</code> <kbd>minclock</kbd><dd>The clustering algorithm repeatedly casts out outlier
2001 associations until no more than
2002 <code>minclock</code>
2003 associations remain.
2004 This value defaults to 3,
2005 but can be changed to any number from 1 to the number of
2007 <br><dt><code>minsane</code> <kbd>minsane</kbd><dd>This is the minimum number of candidates available
2008 to the clock selection algorithm in order to produce
2009 one or more truechimers for the clustering algorithm.
2010 If fewer than this number are available, the clock is
2011 undisciplined and allowed to run free.
2013 for legacy purposes.
2014 However, according to principles of
2015 Byzantine agreement,
2016 <code>minsane</code>
2017 should be at least 4 in order to detect and discard
2018 a single falseticker.
2020 <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing
2021 order, up to 8 values can be specified.
2022 In manycast mode these values are used in turn
2023 in an expanding-ring search.
2024 The default is eight
2025 multiples of 32 starting at 31.
2029 <a name="Reference-Clock-Support"></a>
2033 <h4 class="subsection">Reference Clock Support</h4>
2035 <p>The NTP Version 4 daemon supports some three dozen different radio,
2036 satellite and modem reference clocks plus a special pseudo-clock
2037 used for backup or when no other clock source is available.
2038 Detailed descriptions of individual device drivers and options can
2040 "Reference Clock Drivers"
2042 (available as part of the HTML documentation
2044 <span class="file">/usr/share/doc/ntp</span>).
2045 Additional information can be found in the pages linked
2046 there, including the
2047 "Debugging Hints for Reference Clock Drivers"
2049 "How To Write a Reference Clock Driver"
2051 (available as part of the HTML documentation
2053 <span class="file">/usr/share/doc/ntp</span>).
2054 In addition, support for a PPS
2055 signal is available as described in the
2056 "Pulse-per-second (PPS) Signal Interfacing"
2058 (available as part of the HTML documentation
2060 <span class="file">/usr/share/doc/ntp</span>).
2062 drivers support special line discipline/streams modules which can
2063 significantly improve the accuracy using the driver.
2066 "Line Disciplines and Streams Drivers"
2068 (available as part of the HTML documentation
2070 <span class="file">/usr/share/doc/ntp</span>).
2072 <p>A reference clock will generally (though not always) be a radio
2073 timecode receiver which is synchronized to a source of standard
2074 time such as the services offered by the NRC in Canada and NIST and
2076 The interface between the computer and the timecode
2077 receiver is device dependent, but is usually a serial port.
2079 device driver specific to each reference clock must be selected and
2080 compiled in the distribution; however, most common radio, satellite
2081 and modem clocks are included by default.
2082 Note that an attempt to
2083 configure a reference clock when the driver has not been compiled
2084 or the hardware port has not been appropriately configured results
2085 in a scalding remark to the system log file, but is otherwise non
2088 <p>For the purposes of configuration,
2089 <code>ntpd(1ntpdmdoc)</code>
2091 reference clocks in a manner analogous to normal NTP peers as much
2093 Reference clocks are identified by a syntactically
2094 correct but invalid IP address, in order to distinguish them from
2096 Reference clock addresses are of the form
2097 <code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd>,
2101 denoting the clock type and
2104 number in the range 0-3.
2105 While it may seem overkill, it is in fact
2106 sometimes useful to configure multiple reference clocks of the same
2107 type, in which case the unit numbers must be unique.
2111 command is used to configure a reference
2114 argument in that command
2115 is the clock address.
2118 <code>version</code>
2121 options are not used for reference clock support.
2124 option is added for reference clock support, as
2128 option can be useful to
2129 persuade the server to cherish a reference clock with somewhat more
2130 enthusiasm than other reference clocks or peers.
2132 information on this option can be found in the
2133 "Mitigation Rules and the prefer Keyword"
2134 (available as part of the HTML documentation
2136 <span class="file">/usr/share/doc/ntp</span>)
2139 <code>minpoll</code>
2141 <code>maxpoll</code>
2143 meaning only for selected clock drivers.
2144 See the individual clock
2145 driver document pages for additional information.
2149 command is used to provide additional
2150 information for individual clock drivers and normally follows
2151 immediately after the
2156 argument specifies the clock address.
2160 <code>stratum</code>
2161 options can be used to
2162 override the defaults for the device.
2163 There are two optional
2164 device-dependent time offsets and four flags that can be included
2169 <p>The stratum number of a reference clock is by default zero.
2171 <code>ntpd(1ntpdmdoc)</code>
2172 daemon adds one to the stratum of each
2173 peer, a primary server ordinarily displays an external stratum of
2175 In order to provide engineered backups, it is often useful to
2176 specify the reference clock stratum as greater than zero.
2178 <code>stratum</code>
2179 option is used for this purpose.
2181 involving both a reference clock and a pulse-per-second (PPS)
2182 discipline signal, it is useful to specify the reference clock
2183 identifier as other than the default, depending on the driver.
2186 option is used for this purpose.
2188 these options apply to all clock drivers.
2190 <h5 class="subsubsection">Reference Clock Commands</h5>
2193 <dt><code>server</code> <code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd> <code>[prefer]</code> <code>[mode </code><kbd>int</kbd><code>]</code> <code>[minpoll </code><kbd>int</kbd><code>]</code> <code>[maxpoll </code><kbd>int</kbd><code>]</code><dd>This command can be used to configure reference clocks in
2195 The options are interpreted as follows:
2197 <dt><code>prefer</code><dd>Marks the reference clock as preferred.
2198 All other things being
2199 equal, this host will be chosen for synchronization among a set of
2200 correctly operating hosts.
2202 "Mitigation Rules and the prefer Keyword"
2204 (available as part of the HTML documentation
2206 <span class="file">/usr/share/doc/ntp</span>)
2207 for further information.
2208 <br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a
2209 device-specific fashion.
2210 For instance, it selects a dialing
2211 protocol in the ACTS driver and a device subtype in the
2214 <br><dt><code>minpoll</code> <kbd>int</kbd><br><dt><code>maxpoll</code> <kbd>int</kbd><dd>These options specify the minimum and maximum polling interval
2215 for reference clock messages, as a power of 2 in seconds
2217 most directly connected reference clocks, both
2218 <code>minpoll</code>
2220 <code>maxpoll</code>
2221 default to 6 (64 s).
2222 For modem reference clocks,
2223 <code>minpoll</code>
2224 defaults to 10 (17.1 m) and
2225 <code>maxpoll</code>
2226 defaults to 14 (4.5 h).
2227 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2229 <br><dt><code>fudge</code> <code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd> <code>[time1 </code><kbd>sec</kbd><code>]</code> <code>[time2 </code><kbd>sec</kbd><code>]</code> <code>[stratum </code><kbd>int</kbd><code>]</code> <code>[refid </code><kbd>string</kbd><code>]</code> <code>[mode </code><kbd>int</kbd><code>]</code> <code>[flag1 0 | 1]</code> <code>[flag2 0 | 1]</code> <code>[flag3 0 | 1]</code> <code>[flag4 0 | 1]</code><dd>This command can be used to configure reference clocks in
2231 It must immediately follow the
2233 command which configures the driver.
2234 Note that the same capability
2235 is possible at run time using the
2236 <code>ntpdc(1ntpdcmdoc)</code>
2238 The options are interpreted as
2241 <dt><code>time1</code> <kbd>sec</kbd><dd>Specifies a constant to be added to the time offset produced by
2242 the driver, a fixed-point decimal number in seconds.
2244 as a calibration constant to adjust the nominal time offset of a
2245 particular clock to agree with an external standard, such as a
2246 precision PPS signal.
2247 It also provides a way to correct a
2248 systematic error or bias due to serial port or operating system
2249 latencies, different cable lengths or receiver internal delay.
2251 specified offset is in addition to the propagation delay provided
2252 by other means, such as internal DIPswitches.
2254 for an individual system and driver is available, an approximate
2255 correction is noted in the driver documentation pages.
2256 Note: in order to facilitate calibration when more than one
2257 radio clock or PPS signal is supported, a special calibration
2258 feature is available.
2259 It takes the form of an argument to the
2261 command described in
2262 <a href="#Miscellaneous-Options">Miscellaneous Options</a>
2263 page and operates as described in the
2264 "Reference Clock Drivers"
2266 (available as part of the HTML documentation
2268 <span class="file">/usr/share/doc/ntp</span>).
2269 <br><dt><code>time2</code> <kbd>secs</kbd><dd>Specifies a fixed-point decimal number in seconds, which is
2270 interpreted in a driver-dependent way.
2271 See the descriptions of
2272 specific drivers in the
2273 "Reference Clock Drivers"
2275 (available as part of the HTML documentation
2277 <span class="file">/usr/share/doc/ntp</span> <span class="file">).</span>
2278 <br><dt><code>stratum</code> <kbd>int</kbd><dd>Specifies the stratum number assigned to the driver, an integer
2280 This number overrides the default stratum number
2281 ordinarily assigned by the driver itself, usually zero.
2282 <br><dt><code>refid</code> <kbd>string</kbd><dd>Specifies an ASCII string of from one to four characters which
2283 defines the reference identifier used by the driver.
2285 overrides the default identifier ordinarily assigned by the driver
2287 <br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a
2288 device-specific fashion.
2289 For instance, it selects a dialing
2290 protocol in the ACTS driver and a device subtype in the
2293 <br><dt><code>flag1</code> <code>0</code> <code>|</code> <code>1</code><br><dt><code>flag2</code> <code>0</code> <code>|</code> <code>1</code><br><dt><code>flag3</code> <code>0</code> <code>|</code> <code>1</code><br><dt><code>flag4</code> <code>0</code> <code>|</code> <code>1</code><dd>These four flags are used for customizing the clock driver.
2295 interpretation of these values, and whether they are used at all,
2296 is a function of the particular clock driver.
2300 is used to enable recording monitoring
2302 <code>clockstats</code>
2303 file configured with the
2304 <code>filegen</code>
2306 Further information on the
2307 <code>filegen</code>
2308 command can be found in
2309 <a href="#Monitoring-Options">Monitoring Options</a>.
2314 <a name="Miscellaneous-Options"></a>
2318 <h4 class="subsection">Miscellaneous Options</h4>
2321 <dt><code>broadcastdelay</code> <kbd>seconds</kbd><dd>The broadcast and multicast modes require a special calibration
2322 to determine the network delay between the local and remote
2324 Ordinarily, this is done automatically by the initial
2325 protocol exchanges between the client and server.
2327 the calibration procedure may fail due to network or server access
2328 controls, for example.
2329 This command specifies the default delay to
2330 be used under these circumstances.
2331 Typically (for Ethernet), a
2332 number between 0.003 and 0.007 seconds is appropriate.
2334 when this command is not used is 0.004 seconds.
2335 <br><dt><code>calldelay</code> <kbd>delay</kbd><dd>This option controls the delay in seconds between the first and second
2336 packets sent in burst or iburst mode to allow additional time for a modem
2337 or ISDN call to complete.
2338 <br><dt><code>driftfile</code> <kbd>driftfile</kbd><dd>This command specifies the complete path and name of the file used to
2339 record the frequency of the local clock oscillator.
2343 command line option.
2344 If the file exists, it is read at
2345 startup in order to set the initial frequency and then updated once per
2346 hour with the current frequency computed by the daemon.
2348 specified, but the file itself does not exist, the starts with an initial
2349 frequency of zero and creates the file when writing it for the first time.
2350 If this command is not given, the daemon will always start with an initial
2353 <p>The file format consists of a single line containing a single
2354 floating point number, which records the frequency offset measured
2355 in parts-per-million (PPM).
2356 The file is updated by first writing
2357 the current drift value into a temporary file and then renaming
2358 this file to replace the old version.
2360 <code>ntpd(1ntpdmdoc)</code>
2361 must have write permission for the directory the
2362 drift file is located in, and that file system links, symbolic or
2363 otherwise, should be avoided.
2364 <br><dt><code>dscp</code> <kbd>value</kbd><dd>This option specifies the Differentiated Services Control Point (DSCP) value,
2366 The default value is 46, signifying Expedited Forwarding.
2367 <br><dt><code>enable</code> <code>[auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats | peer_clear_digest_early | unpeer_crypto_early | unpeer_crypto_nak_early | unpeer_digest_early]</code><br><dt><code>disable</code> <code>[auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats | peer_clear_digest_early | unpeer_crypto_early | unpeer_crypto_nak_early | unpeer_digest_early]</code><dd>Provides a way to enable or disable various server options.
2368 Flags not mentioned are unaffected.
2369 Note that all of these flags
2370 can be controlled remotely using the
2371 <code>ntpdc(1ntpdcmdoc)</code>
2374 <dt><code>auth</code><dd>Enables the server to synchronize with unconfigured peers only if the
2375 peer has been correctly authenticated using either public key or
2376 private key cryptography.
2377 The default for this flag is
2378 <code>enable</code>.
2379 <br><dt><code>bclient</code><dd>Enables the server to listen for a message from a broadcast or
2380 multicast server, as in the
2381 <code>multicastclient</code>
2382 command with default
2384 The default for this flag is
2385 <code>disable</code>.
2386 <br><dt><code>calibrate</code><dd>Enables the calibrate feature for reference clocks.
2389 <code>disable</code>.
2390 <br><dt><code>kernel</code><dd>Enables the kernel time discipline, if available.
2391 The default for this
2394 if support is available, otherwise
2395 <code>disable</code>.
2396 <br><dt><code>mode7</code><dd>Enables processing of NTP mode 7 implementation-specific requests
2397 which are used by the deprecated
2398 <code>ntpdc(1ntpdcmdoc)</code>
2400 The default for this flag is disable.
2401 This flag is excluded from runtime configuration using
2402 <code>ntpq(1ntpqmdoc)</code>.
2404 <code>ntpq(1ntpqmdoc)</code>
2405 program provides the same capabilities as
2406 <code>ntpdc(1ntpdcmdoc)</code>
2407 using standard mode 6 requests.
2408 <br><dt><code>monitor</code><dd>Enables the monitoring facility.
2410 <code>ntpdc(1ntpdcmdoc)</code>
2413 <code>monlist</code>
2414 command or further information.
2416 default for this flag is
2417 <code>enable</code>.
2418 <br><dt><code>ntp</code><dd>Enables time and frequency discipline.
2419 In effect, this switch opens and
2420 closes the feedback loop, which is useful for testing.
2423 <code>enable</code>.
2424 <br><dt><code>peer_clear_digest_early</code><dd>By default, if
2425 <code>ntpd(1ntpdmdoc)</code>
2426 is using autokey and it
2427 receives a crypto-NAK packet that
2428 passes the duplicate packet and origin timestamp checks
2429 the peer variables are immediately cleared.
2430 While this is generally a feature
2431 as it allows for quick recovery if a server key has changed,
2432 a properly forged and appropriately delivered crypto-NAK packet
2433 can be used in a DoS attack.
2434 If you have active noticable problems with this type of DoS attack
2435 then you should consider
2436 disabling this option.
2438 <code>peerstats</code>
2439 file for evidence of any of these attacks.
2441 default for this flag is
2442 <code>enable</code>.
2443 <br><dt><code>stats</code><dd>Enables the statistics facility.
2445 <a href="#Monitoring-Options">Monitoring Options</a>
2446 section for further information.
2447 The default for this flag is
2448 <code>disable</code>.
2449 <br><dt><code>unpeer_crypto_early</code><dd>By default, if
2450 <code>ntpd(1ntpdmdoc)</code>
2451 receives an autokey packet that fails TEST9,
2453 the association is immediately cleared.
2454 This is almost certainly a feature,
2455 but if, in spite of the current recommendation of not using autokey,
2460 you are seeing this sort of DoS attack
2461 disabling this flag will delay
2462 tearing down the association until the reachability counter
2465 <code>peerstats</code>
2466 file for evidence of any of these attacks.
2468 default for this flag is
2469 <code>enable</code>.
2470 <br><dt><code>unpeer_crypto_nak_early</code><dd>By default, if
2471 <code>ntpd(1ntpdmdoc)</code>
2472 receives a crypto-NAK packet that
2473 passes the duplicate packet and origin timestamp checks
2474 the association is immediately cleared.
2475 While this is generally a feature
2476 as it allows for quick recovery if a server key has changed,
2477 a properly forged and appropriately delivered crypto-NAK packet
2478 can be used in a DoS attack.
2479 If you have active noticable problems with this type of DoS attack
2480 then you should consider
2481 disabling this option.
2483 <code>peerstats</code>
2484 file for evidence of any of these attacks.
2486 default for this flag is
2487 <code>enable</code>.
2488 <br><dt><code>unpeer_digest_early</code><dd>By default, if
2489 <code>ntpd(1ntpdmdoc)</code>
2490 receives what should be an authenticated packet
2491 that passes other packet sanity checks but
2492 contains an invalid digest
2493 the association is immediately cleared.
2494 While this is generally a feature
2495 as it allows for quick recovery,
2496 if this type of packet is carefully forged and sent
2497 during an appropriate window it can be used for a DoS attack.
2498 If you have active noticable problems with this type of DoS attack
2499 then you should consider
2500 disabling this option.
2502 <code>peerstats</code>
2503 file for evidence of any of these attacks.
2505 default for this flag is
2506 <code>enable</code>.
2508 <br><dt><code>includefile</code> <kbd>includefile</kbd><dd>This command allows additional configuration commands
2509 to be included from a separate file.
2511 be nested to a depth of five; upon reaching the end of any
2512 include file, command processing resumes in the previous
2514 This option is useful for sites that run
2515 <code>ntpd(1ntpdmdoc)</code>
2516 on multiple hosts, with (mostly) common options (e.g., a
2518 <br><dt><code>interface</code> <code>[listen | ignore | drop]</code> <code>[all | ipv4 | ipv6 | wildcard </code><kbd>name</kbd><code> | </code><kbd>address</kbd><code> [/ </code><kbd>prefixlen</kbd><code>]]</code><dd>The
2519 <code>interface</code>
2520 directive controls which network addresses
2521 <code>ntpd(1ntpdmdoc)</code>
2522 opens, and whether input is dropped without processing.
2523 The first parameter determines the action for addresses
2524 which match the second parameter.
2525 The second parameter specifies a class of addresses,
2526 or a specific interface name,
2528 In the address case,
2529 <kbd>prefixlen</kbd>
2530 determines how many bits must match for this rule to apply.
2532 prevents opening matching addresses,
2535 <code>ntpd(1ntpdmdoc)</code>
2536 to open the address and drop all received packets without examination.
2538 <code>interface</code>
2539 directives can be used.
2540 The last rule which matches a particular address determines the action for it.
2541 <code>interface</code>
2542 directives are disabled if any
2544 <code>--interface</code>,
2547 <code>--novirtualips</code>
2548 command-line options are specified in the configuration file,
2549 all available network addresses are opened.
2552 directive is an alias for
2553 <code>interface</code>.
2554 <br><dt><code>leapfile</code> <kbd>leapfile</kbd><dd>This command loads the IERS leapseconds file and initializes the
2555 leapsecond values for the next leapsecond event, leapfile expiration
2556 time, and TAI offset.
2557 The file can be obtained directly from the IERS at
2558 <code>https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</code>
2560 <code>ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</code>.
2562 <code>leapfile</code>
2564 <code>ntpd(1ntpdmdoc)</code>
2566 <code>leapfile</code> <code>directive</code> <code>or</code> <code>when</code>
2567 <code>ntpd</code> <code>detects</code> <code>that</code> <code>the</code>
2571 checks once a day to see if the
2575 <code>update-leap(1update_leapmdoc)</code>
2576 script can be run to see if the
2579 <br><dt><code>leapsmearinterval</code> <kbd>seconds</kbd><dd>This EXPERIMENTAL option is only available if
2580 <code>ntpd(1ntpdmdoc)</code>
2582 <code>--enable-leap-smear</code>
2584 <code>configure</code>
2586 It specifies the interval over which a leap second correction will be applied.
2587 Recommended values for this option are between
2588 7200 (2 hours) and 86400 (24 hours).
2589 .Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!
2590 See http://bugs.ntp.org/2855 for more information.
2591 <br><dt><code>logconfig</code> <kbd>configkeyword</kbd><dd>This command controls the amount and type of output written to
2593 <code>syslog(3)</code>
2594 facility or the alternate
2595 <code>logfile</code>
2597 By default, all output is turned on.
2599 <kbd>configkeyword</kbd>
2600 keywords can be prefixed with
2608 <code>syslog(3)</code>
2615 <code>syslog(3)</code>
2616 messages can be controlled in four
2618 (<code>clock</code>, <code>peer</code>, <code>sys</code> and <code>sync</code>).
2619 Within these classes four types of messages can be
2620 controlled: informational messages
2621 (<code>info</code>),
2623 (<code>events</code>),
2625 (<code>statistics</code>)
2628 (<code>status</code>).
2630 <p>Configuration keywords are formed by concatenating the message class with
2634 prefix can be used instead of a message class.
2636 message class may also be followed by the
2638 keyword to enable/disable all
2639 messages of the respective message class.
2640 Thus, a minimal log configuration
2641 could look like this:
2642 <pre class="verbatim">
2643 logconfig =syncstatus +sysevents
2646 <p>This would just list the synchronizations state of
2647 <code>ntpd(1ntpdmdoc)</code>
2648 and the major system events.
2649 For a simple reference server, the
2650 following minimum message configuration could be useful:
2651 <pre class="verbatim">
2652 logconfig =syncall +clockall
2655 <p>This configuration will list all clock information and
2656 synchronization information.
2657 All other events and messages about
2658 peers, system events and so on is suppressed.
2659 <br><dt><code>logfile</code> <kbd>logfile</kbd><dd>This command specifies the location of an alternate log file to
2660 be used instead of the default system
2661 <code>syslog(3)</code>
2663 This is the same operation as the
2665 command line option.
2666 <br><dt><code>mru</code> <code>[maxdepth </code><kbd>count</kbd><code> | maxmem </code><kbd>kilobytes</kbd><code> | mindepth </code><kbd>count</kbd><code> | maxage </code><kbd>seconds</kbd><code> | initialloc </code><kbd>count</kbd><code> | initmem </code><kbd>kilobytes</kbd><code> | incalloc </code><kbd>count</kbd><code> | incmem </code><kbd>kilobytes</kbd><code>]</code><dd>Controls size limite of the monitoring facility's Most Recently Used
2668 of client addresses, which is also used by the
2669 rate control facility.
2671 <dt><code>maxdepth</code> <kbd>count</kbd><br><dt><code>maxmem</code> <kbd>kilobytes</kbd><dd>Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2672 The acutal limit will be up to
2673 <code>incalloc</code>
2679 options offered in units of entries or kilobytes, if both
2680 <code>maxdepth</code>
2682 <code>maxmem</code> <code>are</code> <code>used,</code> <code>the</code> <code>last</code> <code>one</code> <code>used</code> <code>controls.</code>
2683 The default is 1024 kilobytes.
2684 <br><dt><code>mindepth</code> <kbd>count</kbd><dd>Lower limit on the MRU list size.
2685 When the MRU list has fewer than
2686 <code>mindepth</code>
2687 entries, existing entries are never removed to make room for newer ones,
2688 regardless of their age.
2689 The default is 600 entries.
2690 <br><dt><code>maxage</code> <kbd>seconds</kbd><dd>Once the MRU list has
2691 <code>mindepth</code>
2692 entries and an additional client is to ba added to the list,
2693 if the oldest entry was updated more than
2695 seconds ago, that entry is removed and its storage is reused.
2696 If the oldest entry was updated more recently the MRU list is grown,
2698 <code>maxdepth</code> <code>/</code> <code>moxmem</code>.
2699 The default is 64 seconds.
2700 <br><dt><code>initalloc</code> <kbd>count</kbd><br><dt><code>initmem</code> <kbd>kilobytes</kbd><dd>Initial memory allocation at the time the monitoringfacility is first enabled,
2701 in terms of the number of entries or kilobytes.
2702 The default is 4 kilobytes.
2703 <br><dt><code>incalloc</code> <kbd>count</kbd><br><dt><code>incmem</code> <kbd>kilobytes</kbd><dd>Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2704 The default is 4 kilobytes.
2706 <br><dt><code>nonvolatile</code> <kbd>threshold</kbd><dd>Specify the
2707 <kbd>threshold</kbd>
2708 delta in seconds before an hourly change to the
2709 <code>driftfile</code>
2710 (frequency file) will be written, with a default value of 1e-7 (0.1 PPM).
2711 The frequency file is inspected each hour.
2712 If the difference between the current frequency and the last value written
2713 exceeds the threshold, the file is written and the
2714 <code>threshold</code>
2715 becomes the new threshold value.
2716 If the threshold is not exceeeded, it is reduced by half.
2717 This is intended to reduce the number of file writes
2718 for embedded systems with nonvolatile memory.
2719 <br><dt><code>phone</code> <kbd>dial</kbd> <kbd>...</kbd><dd>This command is used in conjunction with
2720 the ACTS modem driver (type 18)
2721 or the JJY driver (type 40, mode 100 - 180).
2722 For the ACTS modem driver (type 18), the arguments consist of
2723 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2725 For the JJY driver (type 40 mode 100 - 180), the argument is
2726 one telephone number used to dial the telephone JJY service.
2727 The Hayes command ATDT is normally prepended to the number.
2728 The number can contain other modem control codes as well.
2729 <br><dt><code>reset</code> <code>[allpeers]</code> <code>[auth]</code> <code>[ctl]</code> <code>[io]</code> <code>[mem]</code> <code>[sys]</code> <code>[timer]</code><dd>Reset one or more groups of counters maintained by
2735 <br><dt><code>rlimit</code> <code>[memlock </code><kbd>Nmegabytes</kbd><code> | stacksize </code><kbd>N4kPages</kbd><code> filenum </code><kbd>Nfiledescriptors</kbd><code>]</code><dd>
2737 <dt><code>memlock</code> <kbd>Nmegabytes</kbd><dd>Specify the number of megabytes of memory that should be
2738 allocated and locked.
2739 Probably only available under Linux, this option may be useful
2740 when dropping root (the
2743 The default is 32 megabytes on non-Linux machines, and -1 under Linux.
2744 -1 means "do not lock the process into memory".
2745 0 means "lock whatever memory the process wants into memory".
2746 <br><dt><code>stacksize</code> <kbd>N4kPages</kbd><dd>Specifies the maximum size of the process stack on systems with the
2747 <code>mlockall()</code>
2749 Defaults to 50 4k pages (200 4k pages in OpenBSD).
2750 <br><dt><code>filenum</code> <kbd>Nfiledescriptors</kbd><dd>Specifies the maximum number of file descriptors ntpd may have open at once.
2751 Defaults to the system default.
2753 <br><dt><code>saveconfigdir</code> <kbd>directory_path</kbd><dd>Specify the directory in which to write configuration snapshots
2756 <code>saveconfig</code>
2759 <code>saveconfigdir</code>
2760 does not appear in the configuration file,
2761 <code>saveconfig</code>
2762 requests are rejected by
2764 <br><dt><code>saveconfig</code> <kbd>filename</kbd><dd>Write the current configuration, including any runtime
2765 modifications given with
2766 <code>:config</code>
2768 <code>config-from-file</code>
2774 <code>saveconfigdir</code>.
2775 This command will be rejected unless the
2776 <code>saveconfigdir</code>
2777 directive appears in
2782 <code>strftime(3)</code>
2783 format directives to substitute the current date and time,
2785 <code>saveconfig\ ntp-%Y%m%d-%H%M%S.conf</code>.
2786 The filename used is stored in the system variable
2787 <code>savedconfig</code>.
2788 Authentication is required.
2789 <br><dt><code>setvar</code> <kbd>variable</kbd> <code>[default]</code><dd>This command adds an additional system variable.
2791 variables can be used to distribute additional information such as
2793 If the variable of the form
2794 <code>name</code><code>=</code><kbd>value</kbd>
2796 <code>default</code>
2798 variable will be listed as part of the default system variables
2799 (<code>rv</code> command)).
2800 These additional variables serve
2801 informational purposes only.
2802 They are not related to the protocol
2803 other that they can be listed.
2804 The known protocol variables will
2805 always override any variables defined via the
2808 There are three special variables that contain the names
2809 of all variable of the same group.
2811 <code>sys_var_list</code>
2813 the names of all system variables.
2815 <code>peer_var_list</code>
2817 the names of all peer variables and the
2818 <code>clock_var_list</code>
2819 holds the names of the reference clock variables.
2820 <br><dt><code>sysinfo</code><dd>Display operational summary.
2821 <br><dt><code>sysstats</code><dd>Show statistics counters maintained in the protocol module.
2822 <br><dt><code>tinker</code> <code>[allan </code><kbd>allan</kbd><code> | dispersion </code><kbd>dispersion</kbd><code> | freq </code><kbd>freq</kbd><code> | huffpuff </code><kbd>huffpuff</kbd><code> | panic </code><kbd>panic</kbd><code> | step </code><kbd>step</kbd><code> | stepback </code><kbd>stepback</kbd><code> | stepfwd </code><kbd>stepfwd</kbd><code> | stepout </code><kbd>stepout</kbd><code>]</code><dd>This command can be used to alter several system variables in
2823 very exceptional circumstances.
2824 It should occur in the
2825 configuration file before any other configuration options.
2827 default values of these variables have been carefully optimized for
2828 a wide range of network speeds and reliability expectations.
2830 general, they interact in intricate ways that are hard to predict
2831 and some combinations can result in some very nasty behavior.
2833 rarely is it necessary to change the default values; but, some
2834 folks cannot resist twisting the knobs anyway and this command is
2836 Emphasis added: twisters are on their own and can expect
2837 no help from the support group.
2839 <p>The variables operate as follows:
2841 <dt><code>allan</code> <kbd>allan</kbd><dd>The argument becomes the new value for the minimum Allan
2842 intercept, which is a parameter of the PLL/FLL clock discipline
2844 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
2846 <br><dt><code>dispersion</code> <kbd>dispersion</kbd><dd>The argument becomes the new value for the dispersion increase rate,
2847 normally .000015 s/s.
2848 <br><dt><code>freq</code> <kbd>freq</kbd><dd>The argument becomes the initial value of the frequency offset in
2850 This overrides the value in the frequency file, if
2851 present, and avoids the initial training state if it is not.
2852 <br><dt><code>huffpuff</code> <kbd>huffpuff</kbd><dd>The argument becomes the new value for the experimental
2853 huff-n'-puff filter span, which determines the most recent interval
2854 the algorithm will search for a minimum delay.
2856 900 s (15 m), but a more reasonable value is 7200 (2 hours).
2858 is no default, since the filter is not enabled unless this command
2860 <br><dt><code>panic</code> <kbd>panic</kbd><dd>The argument is the panic threshold, normally 1000 s.
2862 the panic sanity check is disabled and a clock offset of any value will
2864 <br><dt><code>step</code> <kbd>step</kbd><dd>The argument is the step threshold, which by default is 0.128 s.
2866 be set to any positive number in seconds.
2867 If set to zero, step
2868 adjustments will never occur.
2869 Note: The kernel time discipline is
2870 disabled if the step threshold is set to zero or greater than the
2872 <br><dt><code>stepback</code> <kbd>stepback</kbd><dd>The argument is the step threshold for the backward direction,
2873 which by default is 0.128 s.
2875 be set to any positive number in seconds.
2876 If both the forward and backward step thresholds are set to zero, step
2877 adjustments will never occur.
2878 Note: The kernel time discipline is
2880 each direction of step threshold are either
2881 set to zero or greater than .5 second.
2882 <br><dt><code>stepfwd</code> <kbd>stepfwd</kbd><dd>As for stepback, but for the forward direction.
2883 <br><dt><code>stepout</code> <kbd>stepout</kbd><dd>The argument is the stepout timeout, which by default is 900 s.
2885 be set to any positive number in seconds.
2886 If set to zero, the stepout
2887 pulses will not be suppressed.
2889 <br><dt><code>writevar</code> <kbd>assocID\ name</kbd> <kbd>=</kbd> <kbd>value</kbd> <kbd>[,...]</kbd><dd>Write (create or update) the specified variables.
2891 <code>assocID</code>
2892 is zero, the variablea re from the
2894 name space, otherwise they are from the
2898 <code>assocID</code>
2899 is required, as the same name can occur in both name spaces.
2900 <br><dt><code>trap</code> <kbd>host_address</kbd> <code>[port </code><kbd>port_number</kbd><code>]</code> <code>[interface </code><kbd>interface_address</kbd><code>]</code><dd>This command configures a trap receiver at the given host
2901 address and port number for sending messages with the specified
2902 local interface address.
2903 If the port number is unspecified, a value
2905 If the interface address is not specified, the
2906 message is sent with a source address of the local interface the
2907 message is sent through.
2908 Note that on a multihomed host the
2909 interface used may vary from time to time with routing changes.
2910 <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order.
2911 Up to 8 values can be specified.
2913 <code>manycast</code>
2914 mode these values are used in-turn in an expanding-ring search.
2915 The default is eight multiples of 32 starting at 31.
2917 <p>The trap receiver will generally log event messages and other
2918 information from the server in a log file.
2920 programs may also request their own trap dynamically, configuring a
2921 trap receiver will ensure that no messages are lost when the server
2923 <br><dt><code>hop</code> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order, up to 8
2924 values can be specified.
2925 In manycast mode these values are used in turn in
2926 an expanding-ring search.
2927 The default is eight multiples of 32 starting at
2931 <p>This section was generated by <strong>AutoGen</strong>,
2932 using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program.
2933 This software is released under the NTP license, <http://ntp.org/license>.
2936 <li><a accesskey="1" href="#ntp_002econf-Files">ntp.conf Files</a>: Files
2937 <li><a accesskey="2" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also
2938 <li><a accesskey="3" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs
2939 <li><a accesskey="4" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes
2944 <a name="ntp_002econf-Files"></a>
2948 <h4 class="subsection">ntp.conf Files</h4>
2951 <dt><span class="file">/etc/ntp.conf</span><dd>the default name of the configuration file
2952 <br><dt><span class="file">ntp.keys</span><dd>private MD5 keys
2953 <br><dt><span class="file">ntpkey</span><dd>RSA private key
2954 <br><dt><span class="file">ntpkey_</span><kbd>host</kbd><dd>RSA public key
2955 <br><dt><span class="file">ntp_dh</span><dd>Diffie-Hellman agreement parameters
2959 <a name="ntp_002econf-See-Also"></a>
2963 <h4 class="subsection">ntp.conf See Also</h4>
2965 <p><code>ntpd(1ntpdmdoc)</code>,
2966 <code>ntpdc(1ntpdcmdoc)</code>,
2967 <code>ntpq(1ntpqmdoc)</code>
2969 <p>In addition to the manual pages provided,
2970 comprehensive documentation is available on the world wide web
2972 <code>http://www.ntp.org/</code>.
2973 A snapshot of this documentation is available in HTML format in
2974 <span class="file">/usr/share/doc/ntp</span>.
2978 David L. Mills, <em>Network Time Protocol (Version 4)</em>, RFC5905
2981 <a name="ntp_002econf-Bugs"></a>
2985 <h4 class="subsection">ntp.conf Bugs</h4>
2987 <p>The syntax checking is not picky; some combinations of
2988 ridiculous and even hilarious options and modes may not be
2992 <span class="file">ntpkey_</span><kbd>host</kbd>
2993 files are really digital
2995 These should be obtained via secure directory
2996 services when they become universally available.
2999 <a name="ntp_002econf-Notes"></a>
3003 <h4 class="subsection">ntp.conf Notes</h4>
3005 <p>This document was derived from FreeBSD.