13 .TH ntp.conf 5 "21 Nov 2016" "4.2.8p9" "File Formats"
15 .\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-Q_ai3f/ag-2_aa2f)
17 .\" It has been AutoGen-ed November 21, 2016 at 08:01:41 AM by AutoGen 5.18.5
18 .\" From the definitions ntp.conf.def
19 .\" and the template file agman-cmd.tpl
21 \f\*[B-Font]ntp.conf\fP
22 \- Network Time Protocol (NTP) daemon configuration file format
24 \f\*[B-Font]ntp.conf\fP
25 [\f\*[B-Font]\-\-option-name\f[]]
26 [\f\*[B-Font]\-\-option-name\f[] \f\*[I-Font]value\f[]]
30 All arguments must be options.
36 \f\*[B-Font]ntp.conf\fP
37 configuration file is read at initial startup by the
38 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
39 daemon in order to specify the synchronization sources,
40 modes and other related information.
41 Usually, it is installed in the
44 but could be installed elsewhere
51 The file format is similar to other
56 character and extend to the end of the line;
57 blank lines are ignored.
58 Configuration commands consist of an initial keyword
59 followed by a list of arguments,
60 some of which may be optional, separated by whitespace.
61 Commands may not be continued over multiple lines.
62 Arguments may be host names,
63 host addresses written in numeric, dotted-quad form,
64 integers, floating point numbers (when specifying times in seconds)
69 The rest of this page describes the configuration and control options.
71 "Notes on Configuring NTP and Setting up an NTP Subnet"
73 (available as part of the HTML documentation
75 \fI/usr/share/doc/ntp\f[])
76 contains an extended discussion of these options.
77 In addition to the discussion of general
78 \fIConfiguration\f[] \fIOptions\f[],
79 there are sections describing the following supported functionality
80 and the options used to control it:
82 \fIAuthentication\f[] \fISupport\f[]
84 \fIMonitoring\f[] \fISupport\f[]
86 \fIAccess\f[] \fIControl\f[] \fISupport\f[]
88 \fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[]
90 \fIReference\f[] \fIClock\f[] \fISupport\f[]
92 \fIMiscellaneous\f[] \fIOptions\f[]
97 Following these is a section describing
98 \fIMiscellaneous\f[] \fIOptions\f[].
99 While there is a rich set of options available,
100 the only required option is one or more
101 \f\*[B-Font]pool\f[],
102 \f\*[B-Font]server\f[],
103 \f\*[B-Font]peer\f[],
104 \f\*[B-Font]broadcast\f[]
106 \f\*[B-Font]manycastclient\f[]
108 .SH Configuration Support
109 Following is a description of the configuration commands in
111 These commands have the same basic functions as in NTPv3 and
112 in some cases new functions and new arguments.
114 classes of commands, configuration commands that configure a
115 persistent association with a remote server or peer or reference
116 clock, and auxiliary commands that specify environmental variables
117 that control various related operations.
118 .SS Configuration Commands
119 The various modes are determined by the command keyword and the
120 type of the required IP address.
121 Addresses are classed by type as
122 (s) a remote server or peer (IPv4 class A, B and C), (b) the
123 broadcast address of a local interface, (m) a multicast address (IPv4
124 class D), or (r) a reference clock address (127.127.x.x).
126 only those options applicable to each command are listed below.
128 of options not listed may not be caught as an error, but may result
129 in some weird and even destructive behavior.
133 If the Basic Socket Interface Extensions for IPv6 (RFC-2553)
134 is detected, support for the IPv6 address family is generated
135 in addition to the default support of the IPv4 address family.
136 In a few cases, including the
137 \f\*[B-Font]reslist\f[]
140 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
142 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[],
143 IPv6 addresses are automatically generated.
144 IPv6 addresses can be identified by the presence of colons
146 in the address field.
147 IPv6 addresses can be used almost everywhere where
148 IPv4 addresses can be used,
149 with the exception of reference clock addresses,
150 which are always IPv4.
154 Note that in contexts where a host name is expected, a
157 the host name forces DNS resolution to the IPv4 namespace,
160 qualifier forces DNS resolution to the IPv6 namespace.
161 See IPv6 references for the
162 equivalent classes for that address family.
164 .NOP \f\*[B-Font]pool\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]burst\f[]] [\f\*[B-Font]iburst\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]]
166 .NOP \f\*[B-Font]server\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]burst\f[]] [\f\*[B-Font]iburst\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]true\f[]]
168 .NOP \f\*[B-Font]peer\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]true\f[]] [\f\*[B-Font]xleave\f[]]
170 .NOP \f\*[B-Font]broadcast\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[]] [\f\*[B-Font]xleave\f[]]
172 .NOP \f\*[B-Font]manycastclient\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[]]
177 These five commands specify the time server name or address to
178 be used and the mode in which to operate.
180 \f\*[I-Font]address\f[]
182 either a DNS name or an IP address in dotted-quad notation.
183 Additional information on association behavior can be found in the
184 "Association Management"
186 (available as part of the HTML documentation
188 \fI/usr/share/doc/ntp\f[]).
190 .NOP \f\*[B-Font]pool\f[]
191 For type s addresses, this command mobilizes a persistent
192 client mode association with a number of remote servers.
193 In this mode the local clock can synchronized to the
194 remote server, but the remote server can never be synchronized to
197 .NOP \f\*[B-Font]server\f[]
198 For type s and r addresses, this command mobilizes a persistent
199 client mode association with the specified remote server or local
201 In this mode the local clock can synchronized to the
202 remote server, but the remote server can never be synchronized to
209 .NOP \f\*[B-Font]peer\f[]
210 For type s addresses (only), this command mobilizes a
211 persistent symmetric-active mode association with the specified
213 In this mode the local clock can be synchronized to
214 the remote peer or the remote peer can be synchronized to the local
216 This is useful in a network of servers where, depending on
217 various failure scenarios, either the local or remote peer may be
218 the better source of time.
219 This command should NOT be used for type
222 .NOP \f\*[B-Font]broadcast\f[]
223 For type b and m addresses (only), this
224 command mobilizes a persistent broadcast mode association.
226 commands can be used to specify multiple local broadcast interfaces
227 (subnets) and/or multiple multicast groups.
229 broadcast messages go only to the interface associated with the
230 subnet specified, but multicast messages go to all interfaces.
231 In broadcast mode the local server sends periodic broadcast
232 messages to a client population at the
233 \f\*[I-Font]address\f[]
234 specified, which is usually the broadcast address on (one of) the
235 local network(s) or a multicast address assigned to NTP.
237 has assigned the multicast group address IPv4 224.0.1.1 and
238 IPv6 ff05::101 (site local) exclusively to
239 NTP, but other nonconflicting addresses can be used to contain the
240 messages within administrative boundaries.
242 specification applies only to the local server operating as a
243 sender; for operation as a broadcast client, see the
244 \f\*[B-Font]broadcastclient\f[]
246 \f\*[B-Font]multicastclient\f[]
250 .NOP \f\*[B-Font]manycastclient\f[]
251 For type m addresses (only), this command mobilizes a
252 manycast client mode association for the multicast address
254 In this case a specific address must be supplied which
255 matches the address used on the
256 \f\*[B-Font]manycastserver\f[]
258 the designated manycast servers.
259 The NTP multicast address
260 224.0.1.1 assigned by the IANA should NOT be used, unless specific
261 means are taken to avoid spraying large areas of the Internet with
262 these messages and causing a possibly massive implosion of replies
265 \f\*[B-Font]manycastserver\f[]
266 command specifies that the local server
267 is to operate in client mode with the remote servers that are
268 discovered as the result of broadcast/multicast messages.
270 client broadcasts a request message to the group address associated
272 \f\*[I-Font]address\f[]
273 and specifically enabled
274 servers respond to these messages.
275 The client selects the servers
276 providing the best time and continues as with the
277 \f\*[B-Font]server\f[]
279 The remaining servers are discarded as if never
287 .NOP \f\*[B-Font]autokey\f[]
288 All packets sent to and received from the server or peer are to
289 include authentication fields encrypted using the autokey scheme
291 \fIAuthentication\f[] \fIOptions\f[].
293 .NOP \f\*[B-Font]burst\f[]
294 when the server is reachable, send a burst of eight packets
295 instead of the usual one.
296 The packet spacing is normally 2 s;
297 however, the spacing between the first and second packets
298 can be changed with the
299 \f\*[B-Font]calldelay\f[]
301 additional time for a modem or ISDN call to complete.
302 This is designed to improve timekeeping quality
304 \f\*[B-Font]server\f[]
305 command and s addresses.
307 .NOP \f\*[B-Font]iburst\f[]
308 When the server is unreachable, send a burst of eight packets
309 instead of the usual one.
310 The packet spacing is normally 2 s;
311 however, the spacing between the first two packets can be
313 \f\*[B-Font]calldelay\f[]
315 additional time for a modem or ISDN call to complete.
316 This is designed to speed the initial synchronization
318 \f\*[B-Font]server\f[]
319 command and s addresses and when
320 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
325 .NOP \f\*[B-Font]key\f[] \f\*[I-Font]key\f[]
326 All packets sent to and received from the server or peer are to
327 include authentication fields encrypted using the specified
329 identifier with values from 1 to 65534, inclusive.
331 default is to include no encryption field.
333 .NOP \f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]
335 .NOP \f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]
336 These options specify the minimum and maximum poll intervals
337 for NTP messages, as a power of 2 in seconds
339 interval defaults to 10 (1,024 s), but can be increased by the
340 \f\*[B-Font]maxpoll\f[]
341 option to an upper limit of 17 (36.4 h).
343 minimum poll interval defaults to 6 (64 s), but can be decreased by
345 \f\*[B-Font]minpoll\f[]
346 option to a lower limit of 4 (16 s).
348 .NOP \f\*[B-Font]noselect\f[]
349 Marks the server as unused, except for display purposes.
350 The server is discarded by the selection algroithm.
352 .NOP \f\*[B-Font]preempt\f[]
353 Says the association can be preempted.
355 .NOP \f\*[B-Font]true\f[]
356 Marks the server as a truechimer.
357 Use this option only for testing.
359 .NOP \f\*[B-Font]prefer\f[]
360 Marks the server as preferred.
361 All other things being equal,
362 this host will be chosen for synchronization among a set of
363 correctly operating hosts.
365 "Mitigation Rules and the prefer Keyword"
367 (available as part of the HTML documentation
369 \fI/usr/share/doc/ntp\f[])
370 for further information.
372 .NOP \f\*[B-Font]true\f[]
373 Forces the association to always survive the selection and clustering algorithms.
374 This option should almost certainly
376 be used while testing an association.
378 .NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[]
379 This option is used only with broadcast server and manycast
381 It specifies the time-to-live
384 use on broadcast server and multicast server and the maximum
386 for the expanding ring search with manycast
388 Selection of the proper value, which defaults to
389 127, is something of a black art and should be coordinated with the
390 network administrator.
392 .NOP \f\*[B-Font]version\f[] \f\*[I-Font]version\f[]
393 Specifies the version number to be used for outgoing NTP
395 Versions 1-4 are the choices, with version 4 the
398 .NOP \f\*[B-Font]xleave\f[]
402 \f\*[B-Font]broadcast\f[]
403 modes only, this flag enables interleave mode.
405 .SS Auxiliary Commands
407 .NOP \f\*[B-Font]broadcastclient\f[]
408 This command enables reception of broadcast server messages to
409 any local interface (type b) address.
410 Upon receiving a message for
411 the first time, the broadcast client measures the nominal server
412 propagation delay using a brief client/server exchange with the
413 server, then enters the broadcast client mode, in which it
414 synchronizes to succeeding broadcast messages.
416 to avoid accidental or malicious disruption in this mode, both the
417 server and client should operate using symmetric-key or public-key
418 authentication as described in
419 \fIAuthentication\f[] \fIOptions\f[].
421 .NOP \f\*[B-Font]manycastserver\f[] \f\*[I-Font]address\f[] \f\*[I-Font]...\f[]
422 This command enables reception of manycast client messages to
423 the multicast group address(es) (type m) specified.
425 address is required, but the NTP multicast address 224.0.1.1
426 assigned by the IANA should NOT be used, unless specific means are
427 taken to limit the span of the reply and avoid a possibly massive
428 implosion at the original sender.
429 Note that, in order to avoid
430 accidental or malicious disruption in this mode, both the server
431 and client should operate using symmetric-key or public-key
432 authentication as described in
433 \fIAuthentication\f[] \fIOptions\f[].
435 .NOP \f\*[B-Font]multicastclient\f[] \f\*[I-Font]address\f[] \f\*[I-Font]...\f[]
436 This command enables reception of multicast server messages to
437 the multicast group address(es) (type m) specified.
439 a message for the first time, the multicast client measures the
440 nominal server propagation delay using a brief client/server
441 exchange with the server, then enters the broadcast client mode, in
442 which it synchronizes to succeeding multicast messages.
444 in order to avoid accidental or malicious disruption in this mode,
445 both the server and client should operate using symmetric-key or
446 public-key authentication as described in
447 \fIAuthentication\f[] \fIOptions\f[].
449 .NOP \f\*[B-Font]mdnstries\f[] \f\*[I-Font]number\f[]
450 If we are participating in mDNS,
451 after we have synched for the first time
452 we attempt to register with the mDNS system.
453 If that registration attempt fails,
454 we try again at one minute intervals for up to
455 \f\*[B-Font]mdnstries\f[]
459 may be starting before mDNS.
460 The default value for
461 \f\*[B-Font]mdnstries\f[]
464 .SH Authentication Support
465 Authentication support allows the NTP client to verify that the
466 server is in fact known and trusted and not an intruder intending
467 accidentally or on purpose to masquerade as that server.
469 specification RFC-1305 defines a scheme which provides
470 cryptographic authentication of received NTP packets.
472 this was done using the Data Encryption Standard (DES) algorithm
473 operating in Cipher Block Chaining (CBC) mode, commonly called
475 Subsequently, this was replaced by the RSA Message Digest
476 5 (MD5) algorithm using a private key, commonly called keyed-MD5.
477 Either algorithm computes a message digest, or one-way hash, which
478 can be used to verify the server has the correct private key and
483 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
484 cryptography and, in addition, provides a new Autokey scheme
485 based on public key cryptography.
486 Public key cryptography is generally considered more secure
487 than symmetric key cryptography, since the security is based
488 on a private value which is generated by each server and
490 With Autokey all key distribution and
491 management functions involve only public values, which
492 considerably simplifies key distribution and storage.
493 Public key management is based on X.509 certificates,
494 which can be provided by commercial services or
495 produced by utility programs in the OpenSSL software library
496 or the NTPv4 distribution.
500 While the algorithms for symmetric key cryptography are
501 included in the NTPv4 distribution, public key cryptography
502 requires the OpenSSL software library to be installed
503 before building the NTP distribution.
504 Directions for doing that
505 are on the Building and Installing the Distribution page.
509 Authentication is configured separately for each association
513 \f\*[B-Font]autokey\f[]
515 \f\*[B-Font]peer\f[],
516 \f\*[B-Font]server\f[],
517 \f\*[B-Font]broadcast\f[]
519 \f\*[B-Font]manycastclient\f[]
520 configuration commands as described in
521 \fIConfiguration\f[] \fIOptions\f[]
524 options described below specify the locations of the key files,
525 if other than default, which symmetric keys are trusted
526 and the interval between various operations, if other than default.
530 Authentication is always enabled,
531 although ineffective if not configured as
533 If a NTP packet arrives
534 including a message authentication
535 code (MAC), it is accepted only if it
536 passes all cryptographic checks.
538 checks require correct key ID, key value
541 been modified in any way or replayed
542 by an intruder, it will fail one or more
543 of these checks and be discarded.
544 Furthermore, the Autokey scheme requires a
545 preliminary protocol exchange to obtain
546 the server certificate, verify its
547 credentials and initialize the protocol
553 flag controls whether new associations or
554 remote configuration commands require cryptographic authentication.
555 This flag can be set or reset by the
556 \f\*[B-Font]enable\f[]
558 \f\*[B-Font]disable\f[]
559 commands and also by remote
560 configuration commands sent by a
561 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
564 If this flag is enabled, which is the default
565 case, new broadcast client and symmetric passive associations and
566 remote configuration commands must be cryptographically
567 authenticated using either symmetric key or public key cryptography.
569 flag is disabled, these operations are effective
570 even if not cryptographic
572 It should be understood
573 that operating with the
575 flag disabled invites a significant vulnerability
576 where a rogue hacker can
577 masquerade as a falseticker and seriously
578 disrupt system timekeeping.
580 important to note that this flag has no purpose
581 other than to allow or disallow
582 a new association in response to new broadcast
583 and symmetric active messages
584 and remote configuration commands and, in particular,
585 the flag has no effect on
586 the authentication process itself.
590 An attractive alternative where multicast support is available
591 is manycast mode, in which clients periodically troll
592 for servers as described in the
593 \fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[]
595 Either symmetric key or public key
596 cryptographic authentication can be used in this mode.
597 The principle advantage
598 of manycast mode is that potential servers need not be
599 configured in advance,
600 since the client finds them during regular operation,
601 and the configuration
602 files for all clients can be identical.
606 The security model and protocol schemes for
607 both symmetric key and public key
608 cryptography are summarized below;
609 further details are in the briefings, papers
610 and reports at the NTP project page linked from
611 \f[C]http://www.ntp.org/\f[].
612 .SS Symmetric-Key Cryptography
613 The original RFC-1305 specification allows any one of possibly
614 65,534 keys, each distinguished by a 32-bit key identifier, to
615 authenticate an association.
616 The servers and clients involved must
617 agree on the key and key identifier to
618 authenticate NTP packets.
620 related information are specified in a key
623 which must be distributed and stored using
624 secure means beyond the scope of the NTP protocol itself.
625 Besides the keys used
626 for ordinary NTP associations,
627 additional keys can be used as passwords for the
628 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
630 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
636 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
637 is first started, it reads the key file specified in the
639 configuration command and installs the keys
642 individual keys must be activated with the
643 \f\*[B-Font]trusted\f[]
646 allows, for instance, the installation of possibly
647 several batches of keys and
648 then activating or deactivating each batch
650 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[].
651 This also provides a revocation capability that can be used
652 if a key becomes compromised.
654 \f\*[B-Font]requestkey\f[]
655 command selects the key used as the password for the
656 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
658 \f\*[B-Font]controlkey\f[]
659 command selects the key used as the password for the
660 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
662 .SS Public Key Cryptography
663 NTPv4 supports the original NTPv3 symmetric key scheme
664 described in RFC-1305 and in addition the Autokey protocol,
665 which is based on public key cryptography.
666 The Autokey Version 2 protocol described on the Autokey Protocol
667 page verifies packet integrity using MD5 message digests
668 and verifies the source with digital signatures and any of several
669 digest/signature schemes.
670 Optional identity schemes described on the Identity Schemes
671 page and based on cryptographic challenge/response algorithms
673 Using all of these schemes provides strong security against
674 replay with or without modification, spoofing, masquerade
675 and most forms of clogging attacks.
677 .\" The cryptographic means necessary for all Autokey operations
678 .\" is provided by the OpenSSL software library.
679 .\" This library is available from http://www.openssl.org/
680 .\" and can be installed using the procedures outlined
681 .\" in the Building and Installing the Distribution page.
683 .\" the configure and build
684 .\" process automatically detects the library and links
685 .\" the library routines required.
689 The Autokey protocol has several modes of operation
690 corresponding to the various NTP modes supported.
691 Most modes use a special cookie which can be
692 computed independently by the client and server,
693 but encrypted in transmission.
694 All modes use in addition a variant of the S-KEY scheme,
695 in which a pseudo-random key list is generated and used
697 These schemes are described along with an executive summary,
698 current status, briefing slides and reading list on the
699 \fIAutonomous\f[] \fIAuthentication\f[]
704 The specific cryptographic environment used by Autokey servers
705 and clients is determined by a set of files
706 and soft links generated by the
707 \fCntp-keygen\f[]\fR(1ntpkeygenmdoc)\f[]
709 This includes a required host key file,
710 required certificate file and optional sign key file,
711 leapsecond file and identity scheme files.
713 digest/signature scheme is specified in the X.509 certificate
714 along with the matching sign key.
715 There are several schemes
716 available in the OpenSSL software library, each identified
717 by a specific string such as
718 \f\*[B-Font]md5WithRSAEncryption\f[],
719 which stands for the MD5 message digest with RSA
721 The current NTP distribution supports
722 all the schemes in the OpenSSL library, including
723 those based on RSA and DSA digital signatures.
727 NTP secure groups can be used to define cryptographic compartments
728 and security hierarchies.
729 It is important that every host
730 in the group be able to construct a certificate trail to one
731 or more trusted hosts in the same group.
733 host runs the Autokey protocol to obtain the certificates
734 for all hosts along the trail to one or more trusted hosts.
735 This requires the configuration file in all hosts to be
736 engineered so that, even under anticipated failure conditions,
737 the NTP subnet will form such that every group host can find
738 a trail to at least one trusted host.
739 .SS Naming and Addressing
740 It is important to note that Autokey does not use DNS to
741 resolve addresses, since DNS can't be completely trusted
742 until the name servers have synchronized clocks.
743 The cryptographic name used by Autokey to bind the host identity
744 credentials and cryptographic values must be independent
745 of interface, network and any other naming convention.
746 The name appears in the host certificate in either or both
747 the subject and issuer fields, so protection against
748 DNS compromise is essential.
752 By convention, the name of an Autokey host is the name returned
754 \fCgethostname\f[]\fR(2)\f[]
755 system call or equivalent in other systems.
757 model, there are no provisions to allow alternate names or aliases.
758 However, this is not to say that DNS aliases, different names
759 for each interface, etc., are constrained in any way.
763 It is also important to note that Autokey verifies authenticity
764 using the host name, network address and public keys,
765 all of which are bound together by the protocol specifically
766 to deflect masquerade attacks.
767 For this reason Autokey
768 includes the source and destination IP addresses in message digest
769 computations and so the same addresses must be available
770 at both the server and client.
771 For this reason operation
772 with network address translation schemes is not possible.
773 This reflects the intended robust security model where government
774 and corporate NTP servers are operated outside firewall perimeters.
776 A specific combination of authentication scheme (none,
777 symmetric key, public key) and identity scheme is called
778 a cryptotype, although not all combinations are compatible.
779 There may be management configurations where the clients,
780 servers and peers may not all support the same cryptotypes.
781 A secure NTPv4 subnet can be configured in many ways while
782 keeping in mind the principles explained above and
784 Note however that some cryptotype
785 combinations may successfully interoperate with each other,
786 but may not represent good security practice.
790 The cryptotype of an association is determined at the time
791 of mobilization, either at configuration time or some time
792 later when a message of appropriate cryptotype arrives.
794 \f\*[B-Font]server\f[]
797 configuration command and no
800 \f\*[B-Font]autokey\f[]
801 subcommands are present, the association is not
802 authenticated; if the
804 subcommand is present, the association is authenticated
805 using the symmetric key ID specified; if the
806 \f\*[B-Font]autokey\f[]
807 subcommand is present, the association is authenticated
812 When multiple identity schemes are supported in the Autokey
813 protocol, the first message exchange determines which one is used.
814 The client request message contains bits corresponding
815 to which schemes it has available.
816 The server response message
817 contains bits corresponding to which schemes it has available.
818 Both server and client match the received bits with their own
819 and select a common scheme.
823 Following the principle that time is a public value,
824 a server responds to any client packet that matches
825 its cryptotype capabilities.
826 Thus, a server receiving
827 an unauthenticated packet will respond with an unauthenticated
828 packet, while the same server receiving a packet of a cryptotype
829 it supports will respond with packets of that cryptotype.
830 However, unconfigured broadcast or manycast client
831 associations or symmetric passive associations will not be
832 mobilized unless the server supports a cryptotype compatible
833 with the first packet received.
834 By default, unauthenticated associations will not be mobilized
835 unless overridden in a decidedly dangerous way.
839 Some examples may help to reduce confusion.
840 Client Alice has no specific cryptotype selected.
841 Server Bob has both a symmetric key file and minimal Autokey files.
842 Alice's unauthenticated messages arrive at Bob, who replies with
843 unauthenticated messages.
844 Cathy has a copy of Bob's symmetric
845 key file and has selected key ID 4 in messages to Bob.
846 Bob verifies the message with his key ID 4.
848 same key and the message is verified, Bob sends Cathy a reply
849 authenticated with that key.
850 If verification fails,
851 Bob sends Cathy a thing called a crypto-NAK, which tells her
853 She can see the evidence using the
854 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
859 Denise has rolled her own host key and certificate.
860 She also uses one of the identity schemes as Bob.
861 She sends the first Autokey message to Bob and they
862 both dance the protocol authentication and identity steps.
863 If all comes out okay, Denise and Bob continue as described above.
867 It should be clear from the above that Bob can support
868 all the girls at the same time, as long as he has compatible
869 authentication and identity credentials.
870 Now, Bob can act just like the girls in his own choice of servers;
871 he can run multiple configured associations with multiple different
872 servers (or the same server, although that might not be useful).
873 But, wise security policy might preclude some cryptotype
874 combinations; for instance, running an identity scheme
875 with one server and no authentication with another might not be wise.
877 The cryptographic values used by the Autokey protocol are
878 incorporated as a set of files generated by the
879 \fCntp-keygen\f[]\fR(1ntpkeygenmdoc)\f[]
880 utility program, including symmetric key, host key and
881 public certificate files, as well as sign key, identity parameters
882 and leapseconds files.
883 Alternatively, host and sign keys and
884 certificate files can be generated by the OpenSSL utilities
885 and certificates can be imported from public certificate
887 Note that symmetric keys are necessary for the
888 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
890 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
892 The remaining files are necessary only for the
897 Certificates imported from OpenSSL or public certificate
898 authorities have certian limitations.
899 The certificate should be in ASN.1 syntax, X.509 Version 3
900 format and encoded in PEM, which is the same format
902 The overall length of the certificate encoded
903 in ASN.1 must not exceed 1024 bytes.
904 The subject distinguished
905 name field (CN) is the fully qualified name of the host
906 on which it is used; the remaining subject fields are ignored.
907 The certificate extension fields must not contain either
908 a subject key identifier or a issuer key identifier field;
909 however, an extended key usage field for a trusted host must
911 \f\*[B-Font]trustRoot\f[];.
912 Other extension fields are ignored.
913 .SS Authentication Commands
915 .NOP \f\*[B-Font]autokey\f[] [\f\*[I-Font]logsec\f[]]
916 Specifies the interval between regenerations of the session key
917 list used with the Autokey protocol.
918 Note that the size of the key
919 list for each association depends on this interval and the current
921 The default value is 12 (4096 s or about 1.1 hours).
922 For poll intervals above the specified interval, a session key list
923 with a single entry will be regenerated for every message
926 .NOP \f\*[B-Font]controlkey\f[] \f\*[I-Font]key\f[]
927 Specifies the key identifier to use with the
928 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
929 utility, which uses the standard
930 protocol defined in RFC-1305.
934 the key identifier for a trusted key, where the value can be in the
935 range 1 to 65,534, inclusive.
937 .NOP \f\*[B-Font]crypto\f[] [\f\*[B-Font]cert\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]leap\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]randfile\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]host\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]sign\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]gq\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]gqpar\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]iffpar\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]mvpar\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]pw\f[] \f\*[I-Font]password\f[]]
938 This command requires the OpenSSL library.
939 It activates public key
940 cryptography, selects the message digest and signature
941 encryption scheme and loads the required private and public
942 values described above.
943 If one or more files are left unspecified,
944 the default names are used as described above.
945 Unless the complete path and name of the file are specified, the
946 location of a file is relative to the keys directory specified
948 \f\*[B-Font]keysdir\f[]
950 \fI/usr/local/etc\f[].
951 Following are the subcommands:
954 .NOP \f\*[B-Font]cert\f[] \f\*[I-Font]file\f[]
955 Specifies the location of the required host public certificate file.
956 This overrides the link
957 \fIntpkey_cert_\f[]\f\*[I-Font]hostname\f[]
958 in the keys directory.
960 .NOP \f\*[B-Font]gqpar\f[] \f\*[I-Font]file\f[]
961 Specifies the location of the optional GQ parameters file.
964 \fIntpkey_gq_\f[]\f\*[I-Font]hostname\f[]
965 in the keys directory.
967 .NOP \f\*[B-Font]host\f[] \f\*[I-Font]file\f[]
968 Specifies the location of the required host key file.
971 \fIntpkey_key_\f[]\f\*[I-Font]hostname\f[]
972 in the keys directory.
974 .NOP \f\*[B-Font]iffpar\f[] \f\*[I-Font]file\f[]
975 Specifies the location of the optional IFF parameters file.
976 This overrides the link
977 \fIntpkey_iff_\f[]\f\*[I-Font]hostname\f[]
978 in the keys directory.
980 .NOP \f\*[B-Font]leap\f[] \f\*[I-Font]file\f[]
981 Specifies the location of the optional leapsecond file.
982 This overrides the link
984 in the keys directory.
986 .NOP \f\*[B-Font]mvpar\f[] \f\*[I-Font]file\f[]
987 Specifies the location of the optional MV parameters file.
988 This overrides the link
989 \fIntpkey_mv_\f[]\f\*[I-Font]hostname\f[]
990 in the keys directory.
992 .NOP \f\*[B-Font]pw\f[] \f\*[I-Font]password\f[]
993 Specifies the password to decrypt files containing private keys and
995 This is required only if these files have been
998 .NOP \f\*[B-Font]randfile\f[] \f\*[I-Font]file\f[]
999 Specifies the location of the random seed file used by the OpenSSL
1001 The defaults are described in the main text above.
1003 .NOP \f\*[B-Font]sign\f[] \f\*[I-Font]file\f[]
1004 Specifies the location of the optional sign key file.
1007 \fIntpkey_sign_\f[]\f\*[I-Font]hostname\f[]
1008 in the keys directory.
1010 not found, the host key is also the sign key.
1013 .NOP \f\*[B-Font]keys\f[] \f\*[I-Font]keyfile\f[]
1014 Specifies the complete path and location of the MD5 key file
1015 containing the keys and key identifiers used by
1016 \fCntpd\f[]\fR(@NTPD_MS@)\f[],
1017 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1019 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1020 when operating with symmetric key cryptography.
1021 This is the same operation as the
1023 command line option.
1025 .NOP \f\*[B-Font]keysdir\f[] \f\*[I-Font]path\f[]
1026 This command specifies the default directory path for
1027 cryptographic keys, parameters and certificates.
1029 \fI/usr/local/etc/\f[].
1031 .NOP \f\*[B-Font]requestkey\f[] \f\*[I-Font]key\f[]
1032 Specifies the key identifier to use with the
1033 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1034 utility program, which uses a
1035 proprietary protocol specific to this implementation of
1036 \fCntpd\f[]\fR(@NTPD_MS@)\f[].
1039 argument is a key identifier
1040 for the trusted key, where the value can be in the range 1 to
1043 .NOP \f\*[B-Font]revoke\f[] \f\*[I-Font]logsec\f[]
1044 Specifies the interval between re-randomization of certain
1045 cryptographic values used by the Autokey scheme, as a power of 2 in
1047 These values need to be updated frequently in order to
1048 deflect brute-force attacks on the algorithms of the scheme;
1049 however, updating some values is a relatively expensive operation.
1050 The default interval is 16 (65,536 s or about 18 hours).
1052 intervals above the specified interval, the values will be updated
1053 for every message sent.
1055 .NOP \f\*[B-Font]trustedkey\f[] \f\*[I-Font]key\f[] \f\*[I-Font]...\f[]
1056 Specifies the key identifiers which are trusted for the
1057 purposes of authenticating peers with symmetric key cryptography,
1058 as well as keys used by the
1059 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1061 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1063 The authentication procedures require that both the local
1064 and remote servers share the same key and key identifier for this
1065 purpose, although different keys can be used with different
1069 arguments are 32-bit unsigned
1070 integers with values from 1 to 65,534.
1073 The following error codes are reported via the NTP control
1074 and monitoring protocol trap mechanism.
1077 (bad field format or length)
1078 The packet has invalid version, length or format.
1082 The packet timestamp is the same or older than the most recent received.
1083 This could be due to a replay or a server clock time step.
1087 The packet filestamp is the same or older than the most recent received.
1088 This could be due to a replay or a key file generation error.
1091 (bad or missing public key)
1092 The public key is missing, has incorrect format or is an unsupported type.
1095 (unsupported digest type)
1096 The server requires an unsupported digest/signature scheme.
1099 (mismatched digest types)
1103 (bad signature length)
1104 The signature length does not match the current public key.
1107 (signature not verified)
1108 The message fails the signature check.
1109 It could be bogus or signed by a
1110 different private key.
1113 (certificate not verified)
1114 The certificate is invalid or signed with the wrong key.
1117 (certificate not verified)
1118 The certificate is not yet valid or has expired or the signature could not
1122 (bad or missing cookie)
1123 The cookie is missing, corrupted or bogus.
1126 (bad or missing leapseconds table)
1127 The leapseconds table is missing, corrupted or bogus.
1130 (bad or missing certificate)
1131 The certificate is missing, corrupted or bogus.
1134 (bad or missing identity)
1135 The identity key is missing, corrupt or bogus.
1137 .SH Monitoring Support
1138 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
1139 includes a comprehensive monitoring facility suitable
1140 for continuous, long term recording of server and client
1141 timekeeping performance.
1143 \f\*[B-Font]statistics\f[]
1145 for a listing and example of each type of statistics currently
1147 Statistic files are managed using file generation sets
1150 directory of the source code distribution.
1152 these facilities and
1154 \fCcron\f[]\fR(8)\f[]
1155 jobs, the data can be
1156 automatically summarized and archived for retrospective analysis.
1157 .SS Monitoring Commands
1159 .NOP \f\*[B-Font]statistics\f[] \f\*[I-Font]name\f[] \f\*[I-Font]...\f[]
1160 Enables writing of statistics records.
1161 Currently, eight kinds of
1162 \f\*[I-Font]name\f[]
1163 statistics are supported.
1166 .NOP \f\*[B-Font]clockstats\f[]
1167 Enables recording of clock driver statistics information.
1169 received from a clock driver appends a line of the following form to
1170 the file generation set named
1171 \f\*[B-Font]clockstats\f[]:
1175 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1181 The first two fields show the date (Modified Julian Day) and time
1182 (seconds and fraction past UTC midnight).
1183 The next field shows the
1184 clock address in dotted-quad notation.
1185 The final field shows the last
1186 timecode received from the clock in decoded ASCII format, where
1188 In some clock drivers a good deal of additional information
1189 can be gathered and displayed as well.
1190 See information specific to each
1191 clock for further details.
1193 .NOP \f\*[B-Font]cryptostats\f[]
1194 This option requires the OpenSSL cryptographic software library.
1196 enables recording of cryptographic public key protocol information.
1197 Each message received by the protocol module appends a line of the
1198 following form to the file generation set named
1199 \f\*[B-Font]cryptostats\f[]:
1203 49213 525.624 127.127.4.1 message
1209 The first two fields show the date (Modified Julian Day) and time
1210 (seconds and fraction past UTC midnight).
1211 The next field shows the peer
1212 address in dotted-quad notation, The final message field includes the
1213 message type and certain ancillary information.
1215 \fIAuthentication\f[] \fIOptions\f[]
1216 section for further information.
1218 .NOP \f\*[B-Font]loopstats\f[]
1219 Enables recording of loop filter statistics information.
1221 update of the local clock outputs a line of the following form to
1222 the file generation set named
1223 \f\*[B-Font]loopstats\f[]:
1227 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1233 The first two fields show the date (Modified Julian Day) and
1234 time (seconds and fraction past UTC midnight).
1235 The next five fields
1236 show time offset (seconds), frequency offset (parts per million \-
1237 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1238 discipline time constant.
1240 .NOP \f\*[B-Font]peerstats\f[]
1241 Enables recording of peer statistics information.
1243 statistics records of all peers of a NTP server and of special
1244 signals, where present and configured.
1245 Each valid update appends a
1246 line of the following form to the current element of a file
1247 generation set named
1248 \f\*[B-Font]peerstats\f[]:
1252 48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674
1258 The first two fields show the date (Modified Julian Day) and
1259 time (seconds and fraction past UTC midnight).
1261 show the peer address in dotted-quad notation and status,
1263 The status field is encoded in hex in the format
1264 described in Appendix A of the NTP specification RFC 1305.
1265 The final four fields show the offset,
1266 delay, dispersion and RMS jitter, all in seconds.
1268 .NOP \f\*[B-Font]rawstats\f[]
1269 Enables recording of raw-timestamp statistics information.
1271 includes statistics records of all peers of a NTP server and of
1272 special signals, where present and configured.
1274 received from a peer or clock driver appends a line of the
1275 following form to the file generation set named
1276 \f\*[B-Font]rawstats\f[]:
1280 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1286 The first two fields show the date (Modified Julian Day) and
1287 time (seconds and fraction past UTC midnight).
1289 show the remote peer or clock address followed by the local address
1290 in dotted-quad notation.
1291 The final four fields show the originate,
1292 receive, transmit and final NTP timestamps in order.
1294 values are as received and before processing by the various data
1295 smoothing and mitigation algorithms.
1297 .NOP \f\*[B-Font]sysstats\f[]
1298 Enables recording of ntpd statistics counters on a periodic basis.
1300 hour a line of the following form is appended to the file generation
1302 \f\*[B-Font]sysstats\f[]:
1306 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1312 The first two fields show the date (Modified Julian Day) and time
1313 (seconds and fraction past UTC midnight).
1314 The remaining ten fields show
1315 the statistics counter values accumulated since the last generated
1319 .NOP Time since restart \f\*[B-Font]36000\f[]
1320 Time in hours since the system was last rebooted.
1322 .NOP Packets received \f\*[B-Font]81965\f[]
1323 Total number of packets received.
1325 .NOP Packets processed \f\*[B-Font]0\f[]
1326 Number of packets received in response to previous packets sent
1328 .NOP Current version \f\*[B-Font]9546\f[]
1329 Number of packets matching the current NTP version.
1331 .NOP Previous version \f\*[B-Font]56\f[]
1332 Number of packets matching the previous NTP version.
1334 .NOP Bad version \f\*[B-Font]71793\f[]
1335 Number of packets matching neither NTP version.
1337 .NOP Access denied \f\*[B-Font]512\f[]
1338 Number of packets denied access for any reason.
1340 .NOP Bad length or format \f\*[B-Font]540\f[]
1341 Number of packets with invalid length, format or port number.
1343 .NOP Bad authentication \f\*[B-Font]10\f[]
1344 Number of packets not verified as authentic.
1346 .NOP Rate exceeded \f\*[B-Font]147\f[]
1347 Number of packets discarded due to rate limitation.
1350 .NOP \f\*[B-Font]statsdir\f[] \f\*[I-Font]directory_path\f[]
1351 Indicates the full path of a directory where statistics files
1352 should be created (see below).
1354 the (otherwise constant)
1355 \f\*[B-Font]filegen\f[]
1356 filename prefix to be modified for file generation sets, which
1357 is useful for handling statistics logs.
1359 .NOP \f\*[B-Font]filegen\f[] \f\*[I-Font]name\f[] [\f\*[B-Font]file\f[] \f\*[I-Font]filename\f[]] [\f\*[B-Font]type\f[] \f\*[I-Font]typename\f[]] [\f\*[B-Font]link\f[] | \f\*[B-Font]nolink\f[]] [\f\*[B-Font]enable\f[] | \f\*[B-Font]disable\f[]]
1360 Configures setting of generation file set name.
1362 file sets provide a means for handling files that are
1363 continuously growing during the lifetime of a server.
1364 Server statistics are a typical example for such files.
1365 Generation file sets provide access to a set of files used
1366 to store the actual data.
1367 At any time at most one element
1368 of the set is being written to.
1369 The type given specifies
1370 when and how data will be directed to a new element of the set.
1371 This way, information stored in elements of a file set
1372 that are currently unused are available for administrational
1373 operations without the risk of disturbing the operation of ntpd.
1374 (Most important: they can be removed to free space for new data
1379 Note that this command can be sent from the
1380 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1381 program running at a remote location.
1384 .NOP \f\*[B-Font]name\f[]
1385 This is the type of the statistics records, as shown in the
1386 \f\*[B-Font]statistics\f[]
1389 .NOP \f\*[B-Font]file\f[] \f\*[I-Font]filename\f[]
1390 This is the file name for the statistics records.
1392 members are built from three concatenated elements
1393 \f\*[B-Font]prefix\f[],
1394 \f\*[B-Font]filename\f[]
1396 \f\*[B-Font]suffix\f[]:
1399 .NOP \f\*[B-Font]prefix\f[]
1400 This is a constant filename path.
1401 It is not subject to
1402 modifications via the
1403 \f\*[I-Font]filegen\f[]
1405 It is defined by the
1406 server, usually specified as a compile-time constant.
1408 however, be configurable for individual file generation sets
1410 For example, the prefix used with
1411 \f\*[I-Font]loopstats\f[]
1413 \f\*[I-Font]peerstats\f[]
1414 generation can be configured using the
1415 \f\*[I-Font]statsdir\f[]
1416 option explained above.
1418 .NOP \f\*[B-Font]filename\f[]
1419 This string is directly concatenated to the prefix mentioned
1420 above (no intervening
1422 This can be modified using
1423 the file argument to the
1424 \f\*[I-Font]filegen\f[]
1429 allowed in this component to prevent filenames referring to
1430 parts outside the filesystem hierarchy denoted by
1431 \f\*[I-Font]prefix\f[].
1433 .NOP \f\*[B-Font]suffix\f[]
1434 This part is reflects individual elements of a file set.
1436 generated according to the type of a file set.
1439 .NOP \f\*[B-Font]type\f[] \f\*[I-Font]typename\f[]
1440 A file generation set is characterized by its type.
1442 types are supported:
1445 .NOP \f\*[B-Font]none\f[]
1446 The file set is actually a single plain file.
1448 .NOP \f\*[B-Font]pid\f[]
1449 One element of file set is used per incarnation of a ntpd
1451 This type does not perform any changes to file set
1452 members during runtime, however it provides an easy way of
1453 separating files belonging to different
1454 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
1455 server incarnations.
1456 The set member filename is built by appending a
1459 \f\*[I-Font]prefix\f[]
1461 \f\*[I-Font]filename\f[]
1463 appending the decimal representation of the process ID of the
1464 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
1467 .NOP \f\*[B-Font]day\f[]
1468 One file generation set element is created per day.
1470 defined as the period between 00:00 and 24:00 UTC.
1472 member suffix consists of a
1474 and a day specification in
1476 \f\*[B-Font]YYYYMMdd\f[].
1477 \f\*[B-Font]YYYY\f[]
1478 is a 4-digit year number (e.g., 1992).
1480 is a two digit month number.
1482 is a two digit day number.
1483 Thus, all information written at 10 December 1992 would end up
1485 \f\*[I-Font]prefix\f[]
1486 \f\*[I-Font]filename\f[].19921210.
1488 .NOP \f\*[B-Font]week\f[]
1489 Any file set member contains data related to a certain week of
1491 The term week is defined by computing day-of-year
1493 Elements of such a file generation set are
1494 distinguished by appending the following suffix to the file set
1495 filename base: A dot, a 4-digit year number, the letter
1497 and a 2-digit week number.
1498 For example, information from January,
1499 10th 1992 would end up in a file with suffix
1500 .NOP. \f\*[I-Font]1992W1\f[].
1502 .NOP \f\*[B-Font]month\f[]
1503 One generation file set element is generated per month.
1505 file name suffix consists of a dot, a 4-digit year number, and
1508 .NOP \f\*[B-Font]year\f[]
1509 One generation file element is generated per year.
1511 suffix consists of a dot and a 4 digit year number.
1513 .NOP \f\*[B-Font]age\f[]
1514 This type of file generation sets changes to a new element of
1515 the file set every 24 hours of server operation.
1517 suffix consists of a dot, the letter
1519 and an 8-digit number.
1520 This number is taken to be the number of seconds the server is
1521 running at the start of the corresponding 24-hour period.
1522 Information is only written to a file generation by specifying
1523 \f\*[B-Font]enable\f[];
1524 output is prevented by specifying
1525 \f\*[B-Font]disable\f[].
1528 .NOP \f\*[B-Font]link\f[] | \f\*[B-Font]nolink\f[]
1529 It is convenient to be able to access the current element of a file
1530 generation set by a fixed name.
1531 This feature is enabled by
1533 \f\*[B-Font]link\f[]
1535 \f\*[B-Font]nolink\f[].
1536 If link is specified, a
1537 hard link from the current file set element to a file without
1539 When there is already a file with this name and
1540 the number of links of this file is one, it is renamed appending a
1544 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
1547 number of links is greater than one, the file is unlinked.
1549 allows the current file to be accessed by a constant name.
1551 .NOP \f\*[B-Font]enable\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]disable\f[]
1552 Enables or disables the recording function.
1556 .SH Access Control Support
1558 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
1559 daemon implements a general purpose address/mask based restriction
1561 The list contains address/match entries sorted first
1562 by increasing address values and and then by increasing mask values.
1563 A match occurs when the bitwise AND of the mask and the packet
1564 source address is equal to the bitwise AND of the mask and
1565 address in the list.
1566 The list is searched in order with the
1567 last match found defining the restriction flags associated
1569 Additional information and examples can be found in the
1570 "Notes on Configuring NTP and Setting up a NTP Subnet"
1572 (available as part of the HTML documentation
1574 \fI/usr/share/doc/ntp\f[]).
1578 The restriction facility was implemented in conformance
1579 with the access policies for the original NSFnet backbone
1581 Later the facility was expanded to deflect
1582 cryptographic and clogging attacks.
1583 While this facility may
1584 be useful for keeping unwanted or broken or malicious clients
1585 from congesting innocent servers, it should not be considered
1586 an alternative to the NTP authentication facilities.
1587 Source address based restrictions are easily circumvented
1588 by a determined cracker.
1592 Clients can be denied service because they are explicitly
1593 included in the restrict list created by the
1594 \f\*[B-Font]restrict\f[]
1596 or implicitly as the result of cryptographic or rate limit
1598 Cryptographic violations include certificate
1599 or identity verification failure; rate limit violations generally
1600 result from defective NTP implementations that send packets
1602 Some violations cause denied service
1603 only for the offending packet, others cause denied service
1604 for a timed period and others cause the denied service for
1605 an indefinite period.
1606 When a client or network is denied access
1607 for an indefinite period, the only way at present to remove
1608 the restrictions is by restarting the server.
1609 .SS The Kiss-of-Death Packet
1610 Ordinarily, packets denied service are simply dropped with no
1611 further action except incrementing statistics counters.
1613 more proactive response is needed, such as a server message that
1614 explicitly requests the client to stop sending and leave a message
1615 for the system operator.
1616 A special packet format has been created
1617 for this purpose called the "kiss-of-death" (KoD) packet.
1618 KoD packets have the leap bits set unsynchronized and stratum set
1619 to zero and the reference identifier field set to a four-byte
1622 \f\*[B-Font]noserve\f[]
1624 \f\*[B-Font]notrust\f[]
1625 flag of the matching restrict list entry is set,
1626 the code is "DENY"; if the
1627 \f\*[B-Font]limited\f[]
1628 flag is set and the rate limit
1629 is exceeded, the code is "RATE".
1630 Finally, if a cryptographic violation occurs, the code is "CRYP".
1634 A client receiving a KoD performs a set of sanity checks to
1635 minimize security exposure, then updates the stratum and
1636 reference identifier peer variables, sets the access
1637 denied (TEST4) bit in the peer flash variable and sends
1638 a message to the log.
1639 As long as the TEST4 bit is set,
1640 the client will send no further packets to the server.
1641 The only way at present to recover from this condition is
1642 to restart the protocol at both the client and server.
1644 happens automatically at the client when the association times out.
1645 It will happen at the server only if the server operator cooperates.
1646 .SS Access Control Commands
1648 .NOP \f\*[B-Font]discard\f[] [\f\*[B-Font]average\f[] \f\*[I-Font]avg\f[]] [\f\*[B-Font]minimum\f[] \f\*[I-Font]min\f[]] [\f\*[B-Font]monitor\f[] \f\*[I-Font]prob\f[]]
1649 Set the parameters of the
1650 \f\*[B-Font]limited\f[]
1651 facility which protects the server from
1654 \f\*[B-Font]average\f[]
1655 subcommand specifies the minimum average packet
1657 \f\*[B-Font]minimum\f[]
1658 subcommand specifies the minimum packet spacing.
1659 Packets that violate these minima are discarded
1660 and a kiss-o'-death packet returned if enabled.
1662 minimum average and minimum are 5 and 2, respectively.
1664 \f\*[B-Font]monitor\f[]
1665 subcommand specifies the probability of discard
1666 for packets that overflow the rate-control window.
1668 .NOP \f\*[B-Font]restrict\f[] \f\*[B-Font]address\f[] [\f\*[B-Font]mask\f[] \f\*[I-Font]mask\f[]] [\f\*[I-Font]flag\f[] \f\*[I-Font]...\f[]]
1670 \f\*[I-Font]address\f[]
1671 argument expressed in
1672 dotted-quad form is the address of a host or network.
1674 \f\*[I-Font]address\f[]
1675 argument can be a valid host DNS name.
1677 \f\*[I-Font]mask\f[]
1678 argument expressed in dotted-quad form defaults to
1679 \f\*[B-Font]255.255.255.255\f[],
1681 \f\*[I-Font]address\f[]
1682 is treated as the address of an individual host.
1683 A default entry (address
1684 \f\*[B-Font]0.0.0.0\f[],
1686 \f\*[B-Font]0.0.0.0\f[])
1687 is always included and is always the first entry in the list.
1688 Note that text string
1689 \f\*[B-Font]default\f[],
1690 with no mask option, may
1691 be used to indicate the default entry.
1692 In the current implementation,
1693 \f\*[B-Font]flag\f[]
1695 restricts access, i.e., an entry with no flags indicates that free
1696 access to the server is to be given.
1697 The flags are not orthogonal,
1698 in that more restrictive flags will often make less restrictive
1700 The flags can generally be classed into two
1701 categories, those which restrict time service and those which
1702 restrict informational queries and attempts to do run-time
1703 reconfiguration of the server.
1704 One or more of the following flags
1708 .NOP \f\*[B-Font]ignore\f[]
1709 Deny packets of all kinds, including
1710 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1712 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1715 .NOP \f\*[B-Font]kod\f[]
1716 If this flag is set when an access violation occurs, a kiss-o'-death
1717 (KoD) packet is sent.
1718 KoD packets are rate limited to no more than one
1720 If another KoD packet occurs within one second after the
1721 last one, the packet is dropped.
1723 .NOP \f\*[B-Font]limited\f[]
1724 Deny service if the packet spacing violates the lower limits specified
1726 \f\*[B-Font]discard\f[]
1728 A history of clients is kept using the
1729 monitoring capability of
1730 \fCntpd\f[]\fR(@NTPD_MS@)\f[].
1731 Thus, monitoring is always active as
1732 long as there is a restriction entry with the
1733 \f\*[B-Font]limited\f[]
1736 .NOP \f\*[B-Font]lowpriotrap\f[]
1737 Declare traps set by matching hosts to be low priority.
1739 number of traps a server can maintain is limited (the current limit
1741 Traps are usually assigned on a first come, first served
1742 basis, with later trap requestors being denied service.
1744 modifies the assignment algorithm by allowing low priority traps to
1745 be overridden by later requests for normal priority traps.
1747 .NOP \f\*[B-Font]nomodify\f[]
1749 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1751 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1752 queries which attempt to modify the state of the
1753 server (i.e., run time reconfiguration).
1754 Queries which return
1755 information are permitted.
1757 .NOP \f\*[B-Font]noquery\f[]
1759 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1761 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1763 Time service is not affected.
1765 .NOP \f\*[B-Font]nopeer\f[]
1766 Deny packets which would result in mobilizing a new association.
1768 includes broadcast and symmetric active packets when a configured
1769 association does not exist.
1771 \f\*[B-Font]pool\f[]
1772 associations, so if you want to use servers from a
1773 \f\*[B-Font]pool\f[]
1774 directive and also want to use
1775 \f\*[B-Font]nopeer\f[]
1776 by default, you'll want a
1777 \f\*[B-Font]restrict source ...\f[] \f\*[B-Font]line\f[] \f\*[B-Font]as\f[] \f\*[B-Font]well\f[] \f\*[B-Font]that\f[] \f\*[B-Font]does\f[]
1781 \f\*[B-Font]nopeer\f[]
1784 .NOP \f\*[B-Font]noserve\f[]
1785 Deny all packets except
1786 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1788 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
1791 .NOP \f\*[B-Font]notrap\f[]
1792 Decline to provide mode 6 control message trap service to matching
1794 The trap service is a subsystem of the
1795 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
1797 protocol which is intended for use by remote event logging programs.
1799 .NOP \f\*[B-Font]notrust\f[]
1800 Deny service unless the packet is cryptographically authenticated.
1802 .NOP \f\*[B-Font]ntpport\f[]
1803 This is actually a match algorithm modifier, rather than a
1805 Its presence causes the restriction entry to be
1806 matched only if the source port in the packet is the standard NTP
1809 \f\*[B-Font]ntpport\f[]
1811 \f\*[B-Font]non-ntpport\f[]
1815 \f\*[B-Font]ntpport\f[]
1816 is considered more specific and
1817 is sorted later in the list.
1819 .NOP \f\*[B-Font]version\f[]
1820 Deny packets that do not match the current NTP version.
1825 Default restriction list entries with the flags ignore, interface,
1826 ntpport, for each of the local host's interface addresses are
1827 inserted into the table at startup to prevent the server
1828 from attempting to synchronize to its own time.
1829 A default entry is also always present, though if it is
1830 otherwise unconfigured; no flags are associated
1831 with the default entry (i.e., everything besides your own
1832 NTP server is unrestricted).
1834 .SH Automatic NTP Configuration Options
1836 Manycasting is a automatic discovery and configuration paradigm
1838 It is intended as a means for a multicast client
1839 to troll the nearby network neighborhood to find cooperating
1840 manycast servers, validate them using cryptographic means
1841 and evaluate their time values with respect to other servers
1842 that might be lurking in the vicinity.
1843 The intended result is that each manycast client mobilizes
1844 client associations with some number of the "best"
1845 of the nearby manycast servers, yet automatically reconfigures
1846 to sustain this number of servers should one or another fail.
1850 Note that the manycasting paradigm does not coincide
1851 with the anycast paradigm described in RFC-1546,
1852 which is designed to find a single server from a clique
1853 of servers providing the same service.
1854 The manycast paradigm is designed to find a plurality
1855 of redundant servers satisfying defined optimality criteria.
1859 Manycasting can be used with either symmetric key
1860 or public key cryptography.
1861 The public key infrastructure (PKI)
1862 offers the best protection against compromised keys
1863 and is generally considered stronger, at least with relatively
1865 It is implemented using the Autokey protocol and
1866 the OpenSSL cryptographic library available from
1867 \f[C]http://www.openssl.org/\f[].
1868 The library can also be used with other NTPv4 modes
1869 as well and is highly recommended, especially for broadcast modes.
1873 A persistent manycast client association is configured
1875 \f\*[B-Font]manycastclient\f[]
1876 command, which is similar to the
1877 \f\*[B-Font]server\f[]
1878 command but with a multicast (IPv4 class
1883 The IANA has designated IPv4 address 224.1.1.1
1884 and IPv6 address FF05::101 (site local) for NTP.
1885 When more servers are needed, it broadcasts manycast
1886 client messages to this address at the minimum feasible rate
1887 and minimum feasible time-to-live (TTL) hops, depending
1888 on how many servers have already been found.
1889 There can be as many manycast client associations
1890 as different group address, each one serving as a template
1891 for a future ephemeral unicast client/server association.
1895 Manycast servers configured with the
1896 \f\*[B-Font]manycastserver\f[]
1897 command listen on the specified group address for manycast
1899 Note the distinction between manycast client,
1900 which actively broadcasts messages, and manycast server,
1901 which passively responds to them.
1902 If a manycast server is
1903 in scope of the current TTL and is itself synchronized
1904 to a valid source and operating at a stratum level equal
1905 to or lower than the manycast client, it replies to the
1906 manycast client message with an ordinary unicast server message.
1910 The manycast client receiving this message mobilizes
1911 an ephemeral client/server association according to the
1912 matching manycast client template, but only if cryptographically
1913 authenticated and the server stratum is less than or equal
1914 to the client stratum.
1915 Authentication is explicitly required
1916 and either symmetric key or public key (Autokey) can be used.
1917 Then, the client polls the server at its unicast address
1918 in burst mode in order to reliably set the host clock
1919 and validate the source.
1920 This normally results
1921 in a volley of eight client/server at 2-s intervals
1922 during which both the synchronization and cryptographic
1923 protocols run concurrently.
1924 Following the volley,
1925 the client runs the NTP intersection and clustering
1926 algorithms, which act to discard all but the "best"
1927 associations according to stratum and synchronization
1929 The surviving associations then continue
1930 in ordinary client/server mode.
1934 The manycast client polling strategy is designed to reduce
1935 as much as possible the volume of manycast client messages
1936 and the effects of implosion due to near-simultaneous
1937 arrival of manycast server messages.
1938 The strategy is determined by the
1939 \f\*[B-Font]manycastclient\f[],
1943 configuration commands.
1944 The manycast poll interval is
1945 normally eight times the system poll interval,
1946 which starts out at the
1947 \f\*[B-Font]minpoll\f[]
1948 value specified in the
1949 \f\*[B-Font]manycastclient\f[],
1950 command and, under normal circumstances, increments to the
1951 \f\*[B-Font]maxpolll\f[]
1952 value specified in this command.
1953 Initially, the TTL is
1954 set at the minimum hops specified by the
1957 At each retransmission the TTL is increased until reaching
1958 the maximum hops specified by this command or a sufficient
1959 number client associations have been found.
1960 Further retransmissions use the same TTL.
1964 The quality and reliability of the suite of associations
1965 discovered by the manycast client is determined by the NTP
1966 mitigation algorithms and the
1967 \f\*[B-Font]minclock\f[]
1969 \f\*[B-Font]minsane\f[]
1970 values specified in the
1972 configuration command.
1974 \f\*[B-Font]minsane\f[]
1975 candidate servers must be available and the mitigation
1976 algorithms produce at least
1977 \f\*[B-Font]minclock\f[]
1978 survivors in order to synchronize the clock.
1979 Byzantine agreement principles require at least four
1980 candidates in order to correctly discard a single falseticker.
1981 For legacy purposes,
1982 \f\*[B-Font]minsane\f[]
1984 \f\*[B-Font]minclock\f[]
1986 For manycast service
1987 \f\*[B-Font]minsane\f[]
1988 should be explicitly set to 4, assuming at least that
1989 number of servers are available.
1994 \f\*[B-Font]minclock\f[]
1995 servers are found, the manycast poll interval is immediately
1997 \f\*[B-Font]maxpoll\f[].
1999 \f\*[B-Font]minclock\f[]
2000 servers are found when the TTL has reached the maximum hops,
2001 the manycast poll interval is doubled.
2002 For each transmission
2003 after that, the poll interval is doubled again until
2004 reaching the maximum of eight times
2005 \f\*[B-Font]maxpoll\f[].
2006 Further transmissions use the same poll interval and
2008 Note that while all this is going on,
2009 each client/server association found is operating normally
2010 it the system poll interval.
2014 Administratively scoped multicast boundaries are normally
2015 specified by the network router configuration and,
2016 in the case of IPv6, the link/site scope prefix.
2017 By default, the increment for TTL hops is 32 starting
2018 from 31; however, the
2020 configuration command can be
2021 used to modify the values to match the scope rules.
2025 It is often useful to narrow the range of acceptable
2026 servers which can be found by manycast client associations.
2027 Because manycast servers respond only when the client
2028 stratum is equal to or greater than the server stratum,
2029 primary (stratum 1) servers fill find only primary servers
2030 in TTL range, which is probably the most common objective.
2031 However, unless configured otherwise, all manycast clients
2032 in TTL range will eventually find all primary servers
2033 in TTL range, which is probably not the most common
2034 objective in large networks.
2037 command can be used to modify this behavior.
2038 Servers with stratum below
2039 \f\*[B-Font]floor\f[]
2041 \f\*[B-Font]ceiling\f[]
2044 command are strongly discouraged during the selection
2045 process; however, these servers may be temporally
2046 accepted if the number of servers within TTL range is
2048 \f\*[B-Font]minclock\f[].
2052 The above actions occur for each manycast client message,
2053 which repeats at the designated poll interval.
2054 However, once the ephemeral client association is mobilized,
2055 subsequent manycast server replies are discarded,
2056 since that would result in a duplicate association.
2057 If during a poll interval the number of client associations
2059 \f\*[B-Font]minclock\f[],
2060 all manycast client prototype associations are reset
2061 to the initial poll interval and TTL hops and operation
2062 resumes from the beginning.
2063 It is important to avoid
2064 frequent manycast client messages, since each one requires
2065 all manycast servers in TTL range to respond.
2066 The result could well be an implosion, either minor or major,
2067 depending on the number of servers in range.
2068 The recommended value for
2069 \f\*[B-Font]maxpoll\f[]
2074 It is possible and frequently useful to configure a host
2075 as both manycast client and manycast server.
2076 A number of hosts configured this way and sharing a common
2077 group address will automatically organize themselves
2078 in an optimum configuration based on stratum and
2079 synchronization distance.
2080 For example, consider an NTP
2081 subnet of two primary servers and a hundred or more
2083 With two exceptions, all servers
2084 and clients have identical configuration files including both
2085 \f\*[B-Font]multicastclient\f[]
2087 \f\*[B-Font]multicastserver\f[]
2088 commands using, for instance, multicast group address
2090 The only exception is that each primary server
2091 configuration file must include commands for the primary
2092 reference source such as a GPS receiver.
2096 The remaining configuration files for all secondary
2097 servers and clients have the same contents, except for the
2099 command, which is specific for each stratum level.
2100 For stratum 1 and stratum 2 servers, that command is
2102 For stratum 3 and above servers the
2103 \f\*[B-Font]floor\f[]
2104 value is set to the intended stratum number.
2105 Thus, all stratum 3 configuration files are identical,
2106 all stratum 4 files are identical and so forth.
2110 Once operations have stabilized in this scenario,
2111 the primary servers will find the primary reference source
2112 and each other, since they both operate at the same
2113 stratum (1), but not with any secondary server or client,
2114 since these operate at a higher stratum.
2116 servers will find the servers at the same stratum level.
2117 If one of the primary servers loses its GPS receiver,
2118 it will continue to operate as a client and other clients
2119 will time out the corresponding association and
2120 re-associate accordingly.
2124 Some administrators prefer to avoid running
2125 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2126 continuously and run either
2127 \fCsntp\f[]\fR(@SNTP_MS@)\f[]
2129 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2132 In either case the servers must be
2133 configured in advance and the program fails if none are
2134 available when the cron job runs.
2136 application of manycast is with
2137 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2138 \f\*[B-Font]\-q\f[].
2139 The program wakes up, scans the local landscape looking
2140 for the usual suspects, selects the best from among
2141 the rascals, sets the clock and then departs.
2142 Servers do not have to be configured in advance and
2143 all clients throughout the network can have the same
2145 .SS Manycast Interactions with Autokey
2146 Each time a manycast client sends a client mode packet
2147 to a multicast group address, all manycast servers
2148 in scope generate a reply including the host name
2150 The manycast clients then run
2151 the Autokey protocol, which collects and verifies
2152 all certificates involved.
2153 Following the burst interval
2154 all but three survivors are cast off,
2155 but the certificates remain in the local cache.
2156 It often happens that several complete signing trails
2157 from the client to the primary servers are collected in this way.
2161 About once an hour or less often if the poll interval
2162 exceeds this, the client regenerates the Autokey key list.
2163 This is in general transparent in client/server mode.
2164 However, about once per day the server private value
2165 used to generate cookies is refreshed along with all
2166 manycast client associations.
2168 cryptographic values including certificates is refreshed.
2169 If a new certificate has been generated since
2170 the last refresh epoch, it will automatically revoke
2171 all prior certificates that happen to be in the
2173 At the same time, the manycast
2174 scheme starts all over from the beginning and
2175 the expanding ring shrinks to the minimum and increments
2176 from there while collecting all servers in scope.
2177 .SS Broadcast Options
2179 .NOP \f\*[B-Font]tos\f[] [\f\*[B-Font]bcpollbstep\f[] \f\*[I-Font]gate\f[]]
2180 This command provides a way to delay,
2181 by the specified number of broadcast poll intervals,
2182 believing backward time steps from a broadcast server.
2183 Broadcast time networks are expected to be trusted.
2184 In the event a broadcast server's time is stepped backwards,
2185 there is clear benefit to having the clients notice this change
2186 as soon as possible.
2187 Attacks such as replay attacks can happen, however,
2188 and even though there are a number of protections built in to
2189 broadcast mode, attempts to perform a replay attack are possible.
2190 This value defaults to 0, but can be changed
2191 to any number of poll intervals between 0 and 4.
2192 .SS Manycast Options
2195 .NOP \f\*[B-Font]tos\f[] [\f\*[B-Font]ceiling\f[] \f\*[I-Font]ceiling\f[] | \f\*[B-Font]cohort\f[] { \f\*[B-Font]0\f[] | \f\*[B-Font]1\f[] } | \f\*[B-Font]floor\f[] \f\*[I-Font]floor\f[] | \f\*[B-Font]minclock\f[] \f\*[I-Font]minclock\f[] | \f\*[B-Font]minsane\f[] \f\*[I-Font]minsane\f[]]
2196 This command affects the clock selection and clustering
2198 It can be used to select the quality and
2199 quantity of peers used to synchronize the system clock
2200 and is most useful in manycast mode.
2201 The variables operate
2205 .NOP \f\*[B-Font]ceiling\f[] \f\*[I-Font]ceiling\f[]
2206 Peers with strata above
2207 \f\*[B-Font]ceiling\f[]
2208 will be discarded if there are at least
2209 \f\*[B-Font]minclock\f[]
2211 This value defaults to 15, but can be changed
2212 to any number from 1 to 15.
2214 .NOP \f\*[B-Font]cohort\f[] {0 | 1 }
2215 This is a binary flag which enables (0) or disables (1)
2216 manycast server replies to manycast clients with the same
2218 This is useful to reduce implosions where
2219 large numbers of clients with the same stratum level
2221 The default is to enable these replies.
2223 .NOP \f\*[B-Font]floor\f[] \f\*[I-Font]floor\f[]
2224 Peers with strata below
2225 \f\*[B-Font]floor\f[]
2226 will be discarded if there are at least
2227 \f\*[B-Font]minclock\f[]
2229 This value defaults to 1, but can be changed
2230 to any number from 1 to 15.
2232 .NOP \f\*[B-Font]minclock\f[] \f\*[I-Font]minclock\f[]
2233 The clustering algorithm repeatedly casts out outlier
2234 associations until no more than
2235 \f\*[B-Font]minclock\f[]
2236 associations remain.
2237 This value defaults to 3,
2238 but can be changed to any number from 1 to the number of
2241 .NOP \f\*[B-Font]minsane\f[] \f\*[I-Font]minsane\f[]
2242 This is the minimum number of candidates available
2243 to the clock selection algorithm in order to produce
2244 one or more truechimers for the clustering algorithm.
2245 If fewer than this number are available, the clock is
2246 undisciplined and allowed to run free.
2248 for legacy purposes.
2249 However, according to principles of
2250 Byzantine agreement,
2251 \f\*[B-Font]minsane\f[]
2252 should be at least 4 in order to detect and discard
2253 a single falseticker.
2256 .NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]hop\f[] \f\*[I-Font]...\f[]
2257 This command specifies a list of TTL values in increasing
2258 order, up to 8 values can be specified.
2259 In manycast mode these values are used in turn
2260 in an expanding-ring search.
2261 The default is eight
2262 multiples of 32 starting at 31.
2264 .SH Reference Clock Support
2265 The NTP Version 4 daemon supports some three dozen different radio,
2266 satellite and modem reference clocks plus a special pseudo-clock
2267 used for backup or when no other clock source is available.
2268 Detailed descriptions of individual device drivers and options can
2270 "Reference Clock Drivers"
2272 (available as part of the HTML documentation
2274 \fI/usr/share/doc/ntp\f[]).
2275 Additional information can be found in the pages linked
2276 there, including the
2277 "Debugging Hints for Reference Clock Drivers"
2279 "How To Write a Reference Clock Driver"
2281 (available as part of the HTML documentation
2283 \fI/usr/share/doc/ntp\f[]).
2284 In addition, support for a PPS
2285 signal is available as described in the
2286 "Pulse-per-second (PPS) Signal Interfacing"
2288 (available as part of the HTML documentation
2290 \fI/usr/share/doc/ntp\f[]).
2292 drivers support special line discipline/streams modules which can
2293 significantly improve the accuracy using the driver.
2296 "Line Disciplines and Streams Drivers"
2298 (available as part of the HTML documentation
2300 \fI/usr/share/doc/ntp\f[]).
2304 A reference clock will generally (though not always) be a radio
2305 timecode receiver which is synchronized to a source of standard
2306 time such as the services offered by the NRC in Canada and NIST and
2308 The interface between the computer and the timecode
2309 receiver is device dependent, but is usually a serial port.
2311 device driver specific to each reference clock must be selected and
2312 compiled in the distribution; however, most common radio, satellite
2313 and modem clocks are included by default.
2314 Note that an attempt to
2315 configure a reference clock when the driver has not been compiled
2316 or the hardware port has not been appropriately configured results
2317 in a scalding remark to the system log file, but is otherwise non
2322 For the purposes of configuration,
2323 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2325 reference clocks in a manner analogous to normal NTP peers as much
2327 Reference clocks are identified by a syntactically
2328 correct but invalid IP address, in order to distinguish them from
2330 Reference clock addresses are of the form
2331 \f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[],
2335 denoting the clock type and
2338 number in the range 0-3.
2339 While it may seem overkill, it is in fact
2340 sometimes useful to configure multiple reference clocks of the same
2341 type, in which case the unit numbers must be unique.
2346 \f\*[B-Font]server\f[]
2347 command is used to configure a reference
2349 \f\*[I-Font]address\f[]
2350 argument in that command
2351 is the clock address.
2353 \f\*[B-Font]key\f[],
2354 \f\*[B-Font]version\f[]
2357 options are not used for reference clock support.
2359 \f\*[B-Font]mode\f[]
2360 option is added for reference clock support, as
2363 \f\*[B-Font]prefer\f[]
2364 option can be useful to
2365 persuade the server to cherish a reference clock with somewhat more
2366 enthusiasm than other reference clocks or peers.
2368 information on this option can be found in the
2369 "Mitigation Rules and the prefer Keyword"
2370 (available as part of the HTML documentation
2372 \fI/usr/share/doc/ntp\f[])
2375 \f\*[B-Font]minpoll\f[]
2377 \f\*[B-Font]maxpoll\f[]
2379 meaning only for selected clock drivers.
2380 See the individual clock
2381 driver document pages for additional information.
2386 \f\*[B-Font]fudge\f[]
2387 command is used to provide additional
2388 information for individual clock drivers and normally follows
2389 immediately after the
2390 \f\*[B-Font]server\f[]
2393 \f\*[I-Font]address\f[]
2394 argument specifies the clock address.
2396 \f\*[B-Font]refid\f[]
2398 \f\*[B-Font]stratum\f[]
2399 options can be used to
2400 override the defaults for the device.
2401 There are two optional
2402 device-dependent time offsets and four flags that can be included
2404 \f\*[B-Font]fudge\f[]
2409 The stratum number of a reference clock is by default zero.
2411 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2412 daemon adds one to the stratum of each
2413 peer, a primary server ordinarily displays an external stratum of
2415 In order to provide engineered backups, it is often useful to
2416 specify the reference clock stratum as greater than zero.
2418 \f\*[B-Font]stratum\f[]
2419 option is used for this purpose.
2421 involving both a reference clock and a pulse-per-second (PPS)
2422 discipline signal, it is useful to specify the reference clock
2423 identifier as other than the default, depending on the driver.
2425 \f\*[B-Font]refid\f[]
2426 option is used for this purpose.
2428 these options apply to all clock drivers.
2429 .SS Reference Clock Commands
2432 .NOP \f\*[B-Font]server\f[] \f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]mode\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]int\f[]]
2433 This command can be used to configure reference clocks in
2435 The options are interpreted as follows:
2438 .NOP \f\*[B-Font]prefer\f[]
2439 Marks the reference clock as preferred.
2440 All other things being
2441 equal, this host will be chosen for synchronization among a set of
2442 correctly operating hosts.
2444 "Mitigation Rules and the prefer Keyword"
2446 (available as part of the HTML documentation
2448 \fI/usr/share/doc/ntp\f[])
2449 for further information.
2451 .NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[]
2452 Specifies a mode number which is interpreted in a
2453 device-specific fashion.
2454 For instance, it selects a dialing
2455 protocol in the ACTS driver and a device subtype in the
2459 .NOP \f\*[B-Font]minpoll\f[] \f\*[I-Font]int\f[]
2461 .NOP \f\*[B-Font]maxpoll\f[] \f\*[I-Font]int\f[]
2462 These options specify the minimum and maximum polling interval
2463 for reference clock messages, as a power of 2 in seconds
2465 most directly connected reference clocks, both
2466 \f\*[B-Font]minpoll\f[]
2468 \f\*[B-Font]maxpoll\f[]
2469 default to 6 (64 s).
2470 For modem reference clocks,
2471 \f\*[B-Font]minpoll\f[]
2472 defaults to 10 (17.1 m) and
2473 \f\*[B-Font]maxpoll\f[]
2474 defaults to 14 (4.5 h).
2475 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2478 .NOP \f\*[B-Font]fudge\f[] \f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[] [\f\*[B-Font]time1\f[] \f\*[I-Font]sec\f[]] [\f\*[B-Font]time2\f[] \f\*[I-Font]sec\f[]] [\f\*[B-Font]stratum\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]refid\f[] \f\*[I-Font]string\f[]] [\f\*[B-Font]mode\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]flag1\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] [\f\*[B-Font]flag2\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] [\f\*[B-Font]flag3\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] [\f\*[B-Font]flag4\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]]
2479 This command can be used to configure reference clocks in
2481 It must immediately follow the
2482 \f\*[B-Font]server\f[]
2483 command which configures the driver.
2484 Note that the same capability
2485 is possible at run time using the
2486 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
2488 The options are interpreted as
2492 .NOP \f\*[B-Font]time1\f[] \f\*[I-Font]sec\f[]
2493 Specifies a constant to be added to the time offset produced by
2494 the driver, a fixed-point decimal number in seconds.
2496 as a calibration constant to adjust the nominal time offset of a
2497 particular clock to agree with an external standard, such as a
2498 precision PPS signal.
2499 It also provides a way to correct a
2500 systematic error or bias due to serial port or operating system
2501 latencies, different cable lengths or receiver internal delay.
2503 specified offset is in addition to the propagation delay provided
2504 by other means, such as internal DIPswitches.
2506 for an individual system and driver is available, an approximate
2507 correction is noted in the driver documentation pages.
2508 Note: in order to facilitate calibration when more than one
2509 radio clock or PPS signal is supported, a special calibration
2510 feature is available.
2511 It takes the form of an argument to the
2512 \f\*[B-Font]enable\f[]
2513 command described in
2514 \fIMiscellaneous\f[] \fIOptions\f[]
2515 page and operates as described in the
2516 "Reference Clock Drivers"
2518 (available as part of the HTML documentation
2520 \fI/usr/share/doc/ntp\f[]).
2522 .NOP \f\*[B-Font]time2\f[] \f\*[I-Font]secs\f[]
2523 Specifies a fixed-point decimal number in seconds, which is
2524 interpreted in a driver-dependent way.
2525 See the descriptions of
2526 specific drivers in the
2527 "Reference Clock Drivers"
2529 (available as part of the HTML documentation
2531 \fI/usr/share/doc/ntp\f[]).
2533 .NOP \f\*[B-Font]stratum\f[] \f\*[I-Font]int\f[]
2534 Specifies the stratum number assigned to the driver, an integer
2536 This number overrides the default stratum number
2537 ordinarily assigned by the driver itself, usually zero.
2539 .NOP \f\*[B-Font]refid\f[] \f\*[I-Font]string\f[]
2540 Specifies an ASCII string of from one to four characters which
2541 defines the reference identifier used by the driver.
2543 overrides the default identifier ordinarily assigned by the driver
2546 .NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[]
2547 Specifies a mode number which is interpreted in a
2548 device-specific fashion.
2549 For instance, it selects a dialing
2550 protocol in the ACTS driver and a device subtype in the
2554 .NOP \f\*[B-Font]flag1\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]
2556 .NOP \f\*[B-Font]flag2\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]
2558 .NOP \f\*[B-Font]flag3\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]
2560 .NOP \f\*[B-Font]flag4\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]
2561 These four flags are used for customizing the clock driver.
2563 interpretation of these values, and whether they are used at all,
2564 is a function of the particular clock driver.
2567 \f\*[B-Font]flag4\f[]
2568 is used to enable recording monitoring
2570 \f\*[B-Font]clockstats\f[]
2571 file configured with the
2572 \f\*[B-Font]filegen\f[]
2574 Further information on the
2575 \f\*[B-Font]filegen\f[]
2576 command can be found in
2577 \fIMonitoring\f[] \fIOptions\f[].
2580 .SH Miscellaneous Options
2583 .NOP \f\*[B-Font]broadcastdelay\f[] \f\*[I-Font]seconds\f[]
2584 The broadcast and multicast modes require a special calibration
2585 to determine the network delay between the local and remote
2587 Ordinarily, this is done automatically by the initial
2588 protocol exchanges between the client and server.
2590 the calibration procedure may fail due to network or server access
2591 controls, for example.
2592 This command specifies the default delay to
2593 be used under these circumstances.
2594 Typically (for Ethernet), a
2595 number between 0.003 and 0.007 seconds is appropriate.
2597 when this command is not used is 0.004 seconds.
2599 .NOP \f\*[B-Font]calldelay\f[] \f\*[I-Font]delay\f[]
2600 This option controls the delay in seconds between the first and second
2601 packets sent in burst or iburst mode to allow additional time for a modem
2602 or ISDN call to complete.
2604 .NOP \f\*[B-Font]driftfile\f[] \f\*[I-Font]driftfile\f[]
2605 This command specifies the complete path and name of the file used to
2606 record the frequency of the local clock oscillator.
2610 command line option.
2611 If the file exists, it is read at
2612 startup in order to set the initial frequency and then updated once per
2613 hour with the current frequency computed by the daemon.
2615 specified, but the file itself does not exist, the starts with an initial
2616 frequency of zero and creates the file when writing it for the first time.
2617 If this command is not given, the daemon will always start with an initial
2622 The file format consists of a single line containing a single
2623 floating point number, which records the frequency offset measured
2624 in parts-per-million (PPM).
2625 The file is updated by first writing
2626 the current drift value into a temporary file and then renaming
2627 this file to replace the old version.
2629 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2630 must have write permission for the directory the
2631 drift file is located in, and that file system links, symbolic or
2632 otherwise, should be avoided.
2634 .NOP \f\*[B-Font]dscp\f[] \f\*[I-Font]value\f[]
2635 This option specifies the Differentiated Services Control Point (DSCP) value,
2637 The default value is 46, signifying Expedited Forwarding.
2639 .NOP \f\*[B-Font]enable\f[] [\f\*[B-Font]auth\f[] | \f\*[B-Font]bclient\f[] | \f\*[B-Font]calibrate\f[] | \f\*[B-Font]kernel\f[] | \f\*[B-Font]mode7\f[] | \f\*[B-Font]monitor\f[] | \f\*[B-Font]ntp\f[] | \f\*[B-Font]stats\f[] | \f\*[B-Font]peer_clear_digest_early\f[] | \f\*[B-Font]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]]
2641 .NOP \f\*[B-Font]disable\f[] [\f\*[B-Font]auth\f[] | \f\*[B-Font]bclient\f[] | \f\*[B-Font]calibrate\f[] | \f\*[B-Font]kernel\f[] | \f\*[B-Font]mode7\f[] | \f\*[B-Font]monitor\f[] | \f\*[B-Font]ntp\f[] | \f\*[B-Font]stats\f[] | \f\*[B-Font]peer_clear_digest_early\f[] | \f\*[B-Font]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]]
2642 Provides a way to enable or disable various server options.
2643 Flags not mentioned are unaffected.
2644 Note that all of these flags
2645 can be controlled remotely using the
2646 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
2650 .NOP \f\*[B-Font]auth\f[]
2651 Enables the server to synchronize with unconfigured peers only if the
2652 peer has been correctly authenticated using either public key or
2653 private key cryptography.
2654 The default for this flag is
2655 \f\*[B-Font]enable\f[].
2657 .NOP \f\*[B-Font]bclient\f[]
2658 Enables the server to listen for a message from a broadcast or
2659 multicast server, as in the
2660 \f\*[B-Font]multicastclient\f[]
2661 command with default
2663 The default for this flag is
2664 \f\*[B-Font]disable\f[].
2666 .NOP \f\*[B-Font]calibrate\f[]
2667 Enables the calibrate feature for reference clocks.
2670 \f\*[B-Font]disable\f[].
2672 .NOP \f\*[B-Font]kernel\f[]
2673 Enables the kernel time discipline, if available.
2674 The default for this
2676 \f\*[B-Font]enable\f[]
2677 if support is available, otherwise
2678 \f\*[B-Font]disable\f[].
2680 .NOP \f\*[B-Font]mode7\f[]
2681 Enables processing of NTP mode 7 implementation-specific requests
2682 which are used by the deprecated
2683 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
2685 The default for this flag is disable.
2686 This flag is excluded from runtime configuration using
2687 \fCntpq\f[]\fR(@NTPQ_MS@)\f[].
2689 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
2690 program provides the same capabilities as
2691 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
2692 using standard mode 6 requests.
2694 .NOP \f\*[B-Font]monitor\f[]
2695 Enables the monitoring facility.
2697 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[]
2700 \f\*[B-Font]monlist\f[]
2701 command or further information.
2703 default for this flag is
2704 \f\*[B-Font]enable\f[].
2706 .NOP \f\*[B-Font]ntp\f[]
2707 Enables time and frequency discipline.
2708 In effect, this switch opens and
2709 closes the feedback loop, which is useful for testing.
2712 \f\*[B-Font]enable\f[].
2714 .NOP \f\*[B-Font]peer_clear_digest_early\f[]
2716 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2717 is using autokey and it
2718 receives a crypto-NAK packet that
2719 passes the duplicate packet and origin timestamp checks
2720 the peer variables are immediately cleared.
2721 While this is generally a feature
2722 as it allows for quick recovery if a server key has changed,
2723 a properly forged and appropriately delivered crypto-NAK packet
2724 can be used in a DoS attack.
2725 If you have active noticable problems with this type of DoS attack
2726 then you should consider
2727 disabling this option.
2729 \f\*[B-Font]peerstats\f[]
2730 file for evidence of any of these attacks.
2732 default for this flag is
2733 \f\*[B-Font]enable\f[].
2735 .NOP \f\*[B-Font]stats\f[]
2736 Enables the statistics facility.
2738 \fIMonitoring\f[] \fIOptions\f[]
2739 section for further information.
2740 The default for this flag is
2741 \f\*[B-Font]disable\f[].
2743 .NOP \f\*[B-Font]unpeer_crypto_early\f[]
2745 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2746 receives an autokey packet that fails TEST9,
2748 the association is immediately cleared.
2749 This is almost certainly a feature,
2750 but if, in spite of the current recommendation of not using autokey,
2755 you are seeing this sort of DoS attack
2756 disabling this flag will delay
2757 tearing down the association until the reachability counter
2760 \f\*[B-Font]peerstats\f[]
2761 file for evidence of any of these attacks.
2763 default for this flag is
2764 \f\*[B-Font]enable\f[].
2766 .NOP \f\*[B-Font]unpeer_crypto_nak_early\f[]
2768 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2769 receives a crypto-NAK packet that
2770 passes the duplicate packet and origin timestamp checks
2771 the association is immediately cleared.
2772 While this is generally a feature
2773 as it allows for quick recovery if a server key has changed,
2774 a properly forged and appropriately delivered crypto-NAK packet
2775 can be used in a DoS attack.
2776 If you have active noticable problems with this type of DoS attack
2777 then you should consider
2778 disabling this option.
2780 \f\*[B-Font]peerstats\f[]
2781 file for evidence of any of these attacks.
2783 default for this flag is
2784 \f\*[B-Font]enable\f[].
2786 .NOP \f\*[B-Font]unpeer_digest_early\f[]
2788 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2789 receives what should be an authenticated packet
2790 that passes other packet sanity checks but
2791 contains an invalid digest
2792 the association is immediately cleared.
2793 While this is generally a feature
2794 as it allows for quick recovery,
2795 if this type of packet is carefully forged and sent
2796 during an appropriate window it can be used for a DoS attack.
2797 If you have active noticable problems with this type of DoS attack
2798 then you should consider
2799 disabling this option.
2801 \f\*[B-Font]peerstats\f[]
2802 file for evidence of any of these attacks.
2804 default for this flag is
2805 \f\*[B-Font]enable\f[].
2808 .NOP \f\*[B-Font]includefile\f[] \f\*[I-Font]includefile\f[]
2809 This command allows additional configuration commands
2810 to be included from a separate file.
2812 be nested to a depth of five; upon reaching the end of any
2813 include file, command processing resumes in the previous
2815 This option is useful for sites that run
2816 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2817 on multiple hosts, with (mostly) common options (e.g., a
2820 .NOP \f\*[B-Font]leapsmearinterval\f[] \f\*[I-Font]seconds\f[]
2821 This EXPERIMENTAL option is only available if
2822 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2824 \f\*[B-Font]\--enable-leap-smear\f[]
2826 \f\*[B-Font]configure\f[]
2828 It specifies the interval over which a leap second correction will be applied.
2829 Recommended values for this option are between
2830 7200 (2 hours) and 86400 (24 hours).
2831 .Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!
2832 See http://bugs.ntp.org/2855 for more information.
2834 .NOP \f\*[B-Font]logconfig\f[] \f\*[I-Font]configkeyword\f[]
2835 This command controls the amount and type of output written to
2837 \fCsyslog\f[]\fR(3)\f[]
2838 facility or the alternate
2839 \f\*[B-Font]logfile\f[]
2841 By default, all output is turned on.
2843 \f\*[I-Font]configkeyword\f[]
2844 keywords can be prefixed with
2852 \fCsyslog\f[]\fR(3)\f[]
2859 \fCsyslog\f[]\fR(3)\f[]
2860 messages can be controlled in four
2862 (\f\*[B-Font]clock\f[], \f\*[B-Font]peer\f[], \f\*[B-Font]sys\f[] and \f\*[B-Font]sync\f[]).
2863 Within these classes four types of messages can be
2864 controlled: informational messages
2865 (\f\*[B-Font]info\f[]),
2867 (\f\*[B-Font]events\f[]),
2869 (\f\*[B-Font]statistics\f[])
2872 (\f\*[B-Font]status\f[]).
2876 Configuration keywords are formed by concatenating the message class with
2880 prefix can be used instead of a message class.
2882 message class may also be followed by the
2884 keyword to enable/disable all
2885 messages of the respective message class.
2886 Thus, a minimal log configuration
2887 could look like this:
2891 logconfig =syncstatus +sysevents
2897 This would just list the synchronizations state of
2898 \fCntpd\f[]\fR(@NTPD_MS@)\f[]
2899 and the major system events.
2900 For a simple reference server, the
2901 following minimum message configuration could be useful:
2905 logconfig =syncall +clockall
2911 This configuration will list all clock information and
2912 synchronization information.
2913 All other events and messages about
2914 peers, system events and so on is suppressed.
2916 .NOP \f\*[B-Font]logfile\f[] \f\*[I-Font]logfile\f[]
2917 This command specifies the location of an alternate log file to
2918 be used instead of the default system
2919 \fCsyslog\f[]\fR(3)\f[]
2921 This is the same operation as the
2923 command line option.
2925 .NOP \f\*[B-Font]setvar\f[] \f\*[I-Font]variable\f[] [\f\*[B-Font]default\f[]]
2926 This command adds an additional system variable.
2928 variables can be used to distribute additional information such as
2930 If the variable of the form
2931 \fIname\f[]\fI=\f[]\f\*[I-Font]value\f[]
2933 \f\*[B-Font]default\f[]
2935 variable will be listed as part of the default system variables
2936 (\fCntpq\f[]\fR(@NTPQ_MS@)\f[] \f\*[B-Font]rv\f[] command)).
2937 These additional variables serve
2938 informational purposes only.
2939 They are not related to the protocol
2940 other that they can be listed.
2941 The known protocol variables will
2942 always override any variables defined via the
2943 \f\*[B-Font]setvar\f[]
2945 There are three special variables that contain the names
2946 of all variable of the same group.
2950 the names of all system variables.
2952 \fIpeer_var_list\f[]
2954 the names of all peer variables and the
2955 \fIclock_var_list\f[]
2956 holds the names of the reference clock variables.
2958 .NOP \f\*[B-Font]tinker\f[] [\f\*[B-Font]allan\f[] \f\*[I-Font]allan\f[] | \f\*[B-Font]dispersion\f[] \f\*[I-Font]dispersion\f[] | \f\*[B-Font]freq\f[] \f\*[I-Font]freq\f[] | \f\*[B-Font]huffpuff\f[] \f\*[I-Font]huffpuff\f[] | \f\*[B-Font]panic\f[] \f\*[I-Font]panic\f[] | \f\*[B-Font]step\f[] \f\*[I-Font]step\f[] | \f\*[B-Font]stepback\f[] \f\*[I-Font]stepback\f[] | \f\*[B-Font]stepfwd\f[] \f\*[I-Font]stepfwd\f[] | \f\*[B-Font]stepout\f[] \f\*[I-Font]stepout\f[]]
2959 This command can be used to alter several system variables in
2960 very exceptional circumstances.
2961 It should occur in the
2962 configuration file before any other configuration options.
2964 default values of these variables have been carefully optimized for
2965 a wide range of network speeds and reliability expectations.
2967 general, they interact in intricate ways that are hard to predict
2968 and some combinations can result in some very nasty behavior.
2970 rarely is it necessary to change the default values; but, some
2971 folks cannot resist twisting the knobs anyway and this command is
2973 Emphasis added: twisters are on their own and can expect
2974 no help from the support group.
2978 The variables operate as follows:
2981 .NOP \f\*[B-Font]allan\f[] \f\*[I-Font]allan\f[]
2982 The argument becomes the new value for the minimum Allan
2983 intercept, which is a parameter of the PLL/FLL clock discipline
2985 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
2988 .NOP \f\*[B-Font]dispersion\f[] \f\*[I-Font]dispersion\f[]
2989 The argument becomes the new value for the dispersion increase rate,
2990 normally .000015 s/s.
2992 .NOP \f\*[B-Font]freq\f[] \f\*[I-Font]freq\f[]
2993 The argument becomes the initial value of the frequency offset in
2995 This overrides the value in the frequency file, if
2996 present, and avoids the initial training state if it is not.
2998 .NOP \f\*[B-Font]huffpuff\f[] \f\*[I-Font]huffpuff\f[]
2999 The argument becomes the new value for the experimental
3000 huff-n'-puff filter span, which determines the most recent interval
3001 the algorithm will search for a minimum delay.
3003 900 s (15 m), but a more reasonable value is 7200 (2 hours).
3005 is no default, since the filter is not enabled unless this command
3008 .NOP \f\*[B-Font]panic\f[] \f\*[I-Font]panic\f[]
3009 The argument is the panic threshold, normally 1000 s.
3011 the panic sanity check is disabled and a clock offset of any value will
3014 .NOP \f\*[B-Font]step\f[] \f\*[I-Font]step\f[]
3015 The argument is the step threshold, which by default is 0.128 s.
3017 be set to any positive number in seconds.
3018 If set to zero, step
3019 adjustments will never occur.
3020 Note: The kernel time discipline is
3021 disabled if the step threshold is set to zero or greater than the
3024 .NOP \f\*[B-Font]stepback\f[] \f\*[I-Font]stepback\f[]
3025 The argument is the step threshold for the backward direction,
3026 which by default is 0.128 s.
3028 be set to any positive number in seconds.
3029 If both the forward and backward step thresholds are set to zero, step
3030 adjustments will never occur.
3031 Note: The kernel time discipline is
3033 each direction of step threshold are either
3034 set to zero or greater than .5 second.
3036 .NOP \f\*[B-Font]stepfwd\f[] \f\*[I-Font]stepfwd\f[]
3037 As for stepback, but for the forward direction.
3039 .NOP \f\*[B-Font]stepout\f[] \f\*[I-Font]stepout\f[]
3040 The argument is the stepout timeout, which by default is 900 s.
3042 be set to any positive number in seconds.
3043 If set to zero, the stepout
3044 pulses will not be suppressed.
3047 .NOP \f\*[B-Font]rlimit\f[] [\f\*[B-Font]memlock\f[] \f\*[I-Font]Nmegabytes\f[] | \f\*[B-Font]stacksize\f[] \f\*[I-Font]N4kPages\f[] \f\*[B-Font]filenum\f[] \f\*[I-Font]Nfiledescriptors\f[]]
3050 .NOP \f\*[B-Font]memlock\f[] \f\*[I-Font]Nmegabytes\f[]
3051 Specify the number of megabytes of memory that should be
3052 allocated and locked.
3053 Probably only available under Linux, this option may be useful
3054 when dropping root (the
3057 The default is 32 megabytes on non-Linux machines, and \-1 under Linux.
3058 -1 means "do not lock the process into memory".
3059 0 means "lock whatever memory the process wants into memory".
3061 .NOP \f\*[B-Font]stacksize\f[] \f\*[I-Font]N4kPages\f[]
3062 Specifies the maximum size of the process stack on systems with the
3063 \fBmlockall\f[]\fR()\f[]
3065 Defaults to 50 4k pages (200 4k pages in OpenBSD).
3067 .NOP \f\*[B-Font]filenum\f[] \f\*[I-Font]Nfiledescriptors\f[]
3068 Specifies the maximum number of file descriptors ntpd may have open at once.
3069 Defaults to the system default.
3072 .NOP \f\*[B-Font]trap\f[] \f\*[I-Font]host_address\f[] [\f\*[B-Font]port\f[] \f\*[I-Font]port_number\f[]] [\f\*[B-Font]interface\f[] \f\*[I-Font]interface_address\f[]]
3073 This command configures a trap receiver at the given host
3074 address and port number for sending messages with the specified
3075 local interface address.
3076 If the port number is unspecified, a value
3078 If the interface address is not specified, the
3079 message is sent with a source address of the local interface the
3080 message is sent through.
3081 Note that on a multihomed host the
3082 interface used may vary from time to time with routing changes.
3086 The trap receiver will generally log event messages and other
3087 information from the server in a log file.
3089 programs may also request their own trap dynamically, configuring a
3090 trap receiver will ensure that no messages are lost when the server
3093 .NOP \f\*[B-Font]hop\f[] \f\*[I-Font]...\f[]
3094 This command specifies a list of TTL values in increasing order, up to 8
3095 values can be specified.
3096 In manycast mode these values are used in turn in
3097 an expanding-ring search.
3098 The default is eight multiples of 32 starting at
3104 .NOP \f\*[B-Font]\-\-help\f[]
3105 Display usage information and exit.
3107 .NOP \f\*[B-Font]\-\-more-help\f[]
3108 Pass the extended usage information through a pager.
3110 .NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}]
3111 Output version of program and exit. The default mode is `v', a simple
3112 version. The `c' mode will print copyright information and `n' will
3113 print the full copyright notice.
3115 .SH "OPTION PRESETS"
3116 Any option that is not marked as \fInot presettable\fP may be preset
3117 by loading values from environment variables named:
3119 \fBNTP_CONF_<option-name>\fP or \fBNTP_CONF\fP
3123 See \fBOPTION PRESETS\fP for configuration environment variables.
3127 .NOP \fI/etc/ntp.conf\f[]
3128 the default name of the configuration file
3132 .NOP \fIntp.keys\f[]
3142 .NOP \fIntpkey_\f[]\f\*[I-Font]host\f[]
3148 Diffie-Hellman agreement parameters
3151 One of the following exit values will be returned:
3154 .NOP 0 " (EXIT_SUCCESS)"
3155 Successful program execution.
3157 .NOP 1 " (EXIT_FAILURE)"
3158 The operation failed or the command syntax was not valid.
3160 .NOP 70 " (EX_SOFTWARE)"
3161 libopts had an internal operational error. Please report
3162 it to autogen-users@lists.sourceforge.net. Thank you.
3165 \fCntpd\f[]\fR(@NTPD_MS@)\f[],
3166 \fCntpdc\f[]\fR(@NTPDC_MS@)\f[],
3167 \fCntpq\f[]\fR(@NTPQ_MS@)\f[]
3171 In addition to the manual pages provided,
3172 comprehensive documentation is available on the world wide web
3174 \f[C]http://www.ntp.org/\f[].
3175 A snapshot of this documentation is available in HTML format in
3176 \fI/usr/share/doc/ntp\f[].
3178 \fINetwork Time Protocol (Version 4)\fR,
3183 The University of Delaware and Network Time Foundation
3185 Copyright (C) 1992-2016 The University of Delaware and Network Time Foundation all rights reserved.
3186 This program is released under the terms of the NTP license, <http://ntp.org/license>.
3188 The syntax checking is not picky; some combinations of
3189 ridiculous and even hilarious options and modes may not be
3195 \fIntpkey_\f[]\f\*[I-Font]host\f[]
3196 files are really digital
3198 These should be obtained via secure directory
3199 services when they become universally available.
3203 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
3205 This document was derived from FreeBSD.
3209 This manual page was \fIAutoGen\fP-erated from the \fBntp.conf\fP