"Fossies" - the Fresh Open Source Software Archive 
Member "ntp-4.2.8p15/ntpd/ntp.conf.5mdoc" (23 Jun 2020, 104160 Bytes) of package /linux/misc/ntp-4.2.8p15.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
See also the latest
Fossies "Diffs" side-by-side code changes report for "ntp.conf.5mdoc":
4.2.8p14_vs_4.2.8p15.
1 .Dd June 23 2020
2 .Dt NTP_CONF 5mdoc File Formats
3 .Os
4 .\" EDIT THIS FILE WITH CAUTION (ntp.mdoc)
5 .\"
6 .\" It has been AutoGen-ed June 23, 2020 at 02:20:27 AM by AutoGen 5.18.5
7 .\" From the definitions ntp.conf.def
8 .\" and the template file agmdoc-cmd.tpl
9 .Sh NAME
10 .Nm ntp.conf
11 .Nd Network Time Protocol (NTP) daemon configuration file format
12 .Sh SYNOPSIS
13 .Nm
14 .Op Fl \-option\-name
15 .Op Fl \-option\-name Ar value
16 .Pp
17 All arguments must be options.
18 .Pp
19 .Sh DESCRIPTION
20 The
21 .Nm
22 configuration file is read at initial startup by the
23 .Xr ntpd 1ntpdmdoc
24 daemon in order to specify the synchronization sources,
25 modes and other related information.
26 Usually, it is installed in the
27 .Pa /etc
28 directory,
29 but could be installed elsewhere
30 (see the daemon's
31 .Fl c
32 command line option).
33 .Pp
34 The file format is similar to other
35 .Ux
36 configuration files.
37 Comments begin with a
38 .Ql #
39 character and extend to the end of the line;
40 blank lines are ignored.
41 Configuration commands consist of an initial keyword
42 followed by a list of arguments,
43 some of which may be optional, separated by whitespace.
44 Commands may not be continued over multiple lines.
45 Arguments may be host names,
46 host addresses written in numeric, dotted\-quad form,
47 integers, floating point numbers (when specifying times in seconds)
48 and text strings.
49 .Pp
50 The rest of this page describes the configuration and control options.
51 The
52 .Qq Notes on Configuring NTP and Setting up an NTP Subnet
53 page
54 (available as part of the HTML documentation
55 provided in
56 .Pa /usr/share/doc/ntp )
57 contains an extended discussion of these options.
58 In addition to the discussion of general
59 .Sx Configuration Options ,
60 there are sections describing the following supported functionality
61 and the options used to control it:
62 .Bl -bullet -offset indent
63 .It
64 .Sx Authentication Support
65 .It
66 .Sx Monitoring Support
67 .It
68 .Sx Access Control Support
69 .It
70 .Sx Automatic NTP Configuration Options
71 .It
72 .Sx Reference Clock Support
73 .It
74 .Sx Miscellaneous Options
75 .El
76 .Pp
77 Following these is a section describing
78 .Sx Miscellaneous Options .
79 While there is a rich set of options available,
80 the only required option is one or more
81 .Ic pool ,
82 .Ic server ,
83 .Ic peer ,
84 .Ic broadcast
85 or
86 .Ic manycastclient
87 commands.
88 .Sh Configuration Support
89 Following is a description of the configuration commands in
90 NTPv4.
91 These commands have the same basic functions as in NTPv3 and
92 in some cases new functions and new arguments.
93 There are two
94 classes of commands, configuration commands that configure a
95 persistent association with a remote server or peer or reference
96 clock, and auxiliary commands that specify environmental variables
97 that control various related operations.
98 .Ss Configuration Commands
99 The various modes are determined by the command keyword and the
100 type of the required IP address.
101 Addresses are classed by type as
102 (s) a remote server or peer (IPv4 class A, B and C), (b) the
103 broadcast address of a local interface, (m) a multicast address (IPv4
104 class D), or (r) a reference clock address (127.127.x.x).
105 Note that
106 only those options applicable to each command are listed below.
107 Use
108 of options not listed may not be caught as an error, but may result
109 in some weird and even destructive behavior.
110 .Pp
111 If the Basic Socket Interface Extensions for IPv6 (RFC\-2553)
112 is detected, support for the IPv6 address family is generated
113 in addition to the default support of the IPv4 address family.
114 In a few cases, including the
115 .Cm reslist
116 billboard generated
117 by
118 .Xr ntpq 1ntpqmdoc
119 or
120 .Xr ntpdc 1ntpdcmdoc ,
121 IPv6 addresses are automatically generated.
122 IPv6 addresses can be identified by the presence of colons
123 .Dq \&:
124 in the address field.
125 IPv6 addresses can be used almost everywhere where
126 IPv4 addresses can be used,
127 with the exception of reference clock addresses,
128 which are always IPv4.
129 .Pp
130 Note that in contexts where a host name is expected, a
131 .Fl 4
132 qualifier preceding
133 the host name forces DNS resolution to the IPv4 namespace,
134 while a
135 .Fl 6
136 qualifier forces DNS resolution to the IPv6 namespace.
137 See IPv6 references for the
138 equivalent classes for that address family.
139 .Bl -tag -width indent
140 .It Xo Ic pool Ar address
141 .Op Cm burst
142 .Op Cm iburst
143 .Op Cm version Ar version
144 .Op Cm prefer
145 .Op Cm minpoll Ar minpoll
146 .Op Cm maxpoll Ar maxpoll
147 .Op Cm xmtnonce
148 .Xc
149 .It Xo Ic server Ar address
150 .Op Cm key Ar key \&| Cm autokey
151 .Op Cm burst
152 .Op Cm iburst
153 .Op Cm version Ar version
154 .Op Cm prefer
155 .Op Cm minpoll Ar minpoll
156 .Op Cm maxpoll Ar maxpoll
157 .Op Cm true
158 .Op Cm xmtnonce
159 .Xc
160 .It Xo Ic peer Ar address
161 .Op Cm key Ar key \&| Cm autokey
162 .Op Cm version Ar version
163 .Op Cm prefer
164 .Op Cm minpoll Ar minpoll
165 .Op Cm maxpoll Ar maxpoll
166 .Op Cm true
167 .Op Cm xleave
168 .Xc
169 .It Xo Ic broadcast Ar address
170 .Op Cm key Ar key \&| Cm autokey
171 .Op Cm version Ar version
172 .Op Cm prefer
173 .Op Cm minpoll Ar minpoll
174 .Op Cm ttl Ar ttl
175 .Op Cm xleave
176 .Xc
177 .It Xo Ic manycastclient Ar address
178 .Op Cm key Ar key \&| Cm autokey
179 .Op Cm version Ar version
180 .Op Cm prefer
181 .Op Cm minpoll Ar minpoll
182 .Op Cm maxpoll Ar maxpoll
183 .Op Cm ttl Ar ttl
184 .Xc
185 .El
186 .Pp
187 These five commands specify the time server name or address to
188 be used and the mode in which to operate.
189 The
190 .Ar address
191 can be
192 either a DNS name or an IP address in dotted\-quad notation.
193 Additional information on association behavior can be found in the
194 .Qq Association Management
195 page
196 (available as part of the HTML documentation
197 provided in
198 .Pa /usr/share/doc/ntp ) .
199 .Bl -tag -width indent
200 .It Ic pool
201 For type s addresses, this command mobilizes a persistent
202 client mode association with a number of remote servers.
203 In this mode the local clock can synchronized to the
204 remote server, but the remote server can never be synchronized to
205 the local clock.
206 .It Ic server
207 For type s and r addresses, this command mobilizes a persistent
208 client mode association with the specified remote server or local
209 radio clock.
210 In this mode the local clock can synchronized to the
211 remote server, but the remote server can never be synchronized to
212 the local clock.
213 This command should
214 .Em not
215 be used for type
216 b or m addresses.
217 .It Ic peer
218 For type s addresses (only), this command mobilizes a
219 persistent symmetric\-active mode association with the specified
220 remote peer.
221 In this mode the local clock can be synchronized to
222 the remote peer or the remote peer can be synchronized to the local
223 clock.
224 This is useful in a network of servers where, depending on
225 various failure scenarios, either the local or remote peer may be
226 the better source of time.
227 This command should NOT be used for type
228 b, m or r addresses.
229 .It Ic broadcast
230 For type b and m addresses (only), this
231 command mobilizes a persistent broadcast mode association.
232 Multiple
233 commands can be used to specify multiple local broadcast interfaces
234 (subnets) and/or multiple multicast groups.
235 Note that local
236 broadcast messages go only to the interface associated with the
237 subnet specified, but multicast messages go to all interfaces.
238 In broadcast mode the local server sends periodic broadcast
239 messages to a client population at the
240 .Ar address
241 specified, which is usually the broadcast address on (one of) the
242 local network(s) or a multicast address assigned to NTP.
243 The IANA
244 has assigned the multicast group address IPv4 224.0.1.1 and
245 IPv6 ff05::101 (site local) exclusively to
246 NTP, but other nonconflicting addresses can be used to contain the
247 messages within administrative boundaries.
248 Ordinarily, this
249 specification applies only to the local server operating as a
250 sender; for operation as a broadcast client, see the
251 .Ic broadcastclient
252 or
253 .Ic multicastclient
254 commands
255 below.
256 .It Ic manycastclient
257 For type m addresses (only), this command mobilizes a
258 manycast client mode association for the multicast address
259 specified.
260 In this case a specific address must be supplied which
261 matches the address used on the
262 .Ic manycastserver
263 command for
264 the designated manycast servers.
265 The NTP multicast address
266 224.0.1.1 assigned by the IANA should NOT be used, unless specific
267 means are taken to avoid spraying large areas of the Internet with
268 these messages and causing a possibly massive implosion of replies
269 at the sender.
270 The
271 .Ic manycastserver
272 command specifies that the local server
273 is to operate in client mode with the remote servers that are
274 discovered as the result of broadcast/multicast messages.
275 The
276 client broadcasts a request message to the group address associated
277 with the specified
278 .Ar address
279 and specifically enabled
280 servers respond to these messages.
281 The client selects the servers
282 providing the best time and continues as with the
283 .Ic server
284 command.
285 The remaining servers are discarded as if never
286 heard.
287 .El
288 .Pp
289 Options:
290 .Bl -tag -width indent
291 .It Cm autokey
292 All packets sent to and received from the server or peer are to
293 include authentication fields encrypted using the autokey scheme
294 described in
295 .Sx Authentication Options .
296 .It Cm burst
297 when the server is reachable, send a burst of eight packets
298 instead of the usual one.
299 The packet spacing is normally 2 s;
300 however, the spacing between the first and second packets
301 can be changed with the
302 .Ic calldelay
303 command to allow
304 additional time for a modem or ISDN call to complete.
305 This is designed to improve timekeeping quality
306 with the
307 .Ic server
308 command and s addresses.
309 .It Cm iburst
310 When the server is unreachable, send a burst of eight packets
311 instead of the usual one.
312 The packet spacing is normally 2 s;
313 however, the spacing between the first two packets can be
314 changed with the
315 .Ic calldelay
316 command to allow
317 additional time for a modem or ISDN call to complete.
318 This is designed to speed the initial synchronization
319 acquisition with the
320 .Ic server
321 command and s addresses and when
322 .Xr ntpd 1ntpdmdoc
323 is started with the
324 .Fl q
325 option.
326 .It Cm key Ar key
327 All packets sent to and received from the server or peer are to
328 include authentication fields encrypted using the specified
329 .Ar key
330 identifier with values from 1 to 65535, inclusive.
331 The
332 default is to include no encryption field.
333 .It Cm minpoll Ar minpoll
334 .It Cm maxpoll Ar maxpoll
335 These options specify the minimum and maximum poll intervals
336 for NTP messages, as a power of 2 in seconds
337 The maximum poll
338 interval defaults to 10 (1,024 s), but can be increased by the
339 .Cm maxpoll
340 option to an upper limit of 17 (36.4 h).
341 The
342 minimum poll interval defaults to 6 (64 s), but can be decreased by
343 the
344 .Cm minpoll
345 option to a lower limit of 4 (16 s).
346 .It Cm noselect
347 Marks the server as unused, except for display purposes.
348 The server is discarded by the selection algroithm.
349 .It Cm preempt
350 Says the association can be preempted.
351 .It Cm prefer
352 Marks the server as preferred.
353 All other things being equal,
354 this host will be chosen for synchronization among a set of
355 correctly operating hosts.
356 See the
357 .Qq Mitigation Rules and the prefer Keyword
358 page
359 (available as part of the HTML documentation
360 provided in
361 .Pa /usr/share/doc/ntp )
362 for further information.
363 .It Cm true
364 Marks the server as a truechimer,
365 forcing the association to always survive the selection and clustering algorithms.
366 This option should almost certainly
367 .Em only
368 be used while testing an association.
369 .It Cm ttl Ar ttl
370 This option is used only with broadcast server and manycast
371 client modes.
372 It specifies the time\-to\-live
373 .Ar ttl
374 to
375 use on broadcast server and multicast server and the maximum
376 .Ar ttl
377 for the expanding ring search with manycast
378 client packets.
379 Selection of the proper value, which defaults to
380 127, is something of a black art and should be coordinated with the
381 network administrator.
382 .It Cm version Ar version
383 Specifies the version number to be used for outgoing NTP
384 packets.
385 Versions 1\-4 are the choices, with version 4 the
386 default.
387 .It Cm xleave
388 Valid in
389 .Cm peer
390 and
391 .Cm broadcast
392 modes only, this flag enables interleave mode.
393 .It Cm xmtnonce
394 Valid only for
395 .Cm server
396 and
397 .Cm pool
398 modes, this flag puts a random number in the packet's transmit timestamp.
399 .El
400 .Ss Auxiliary Commands
401 .Bl -tag -width indent
402 .It Ic broadcastclient
403 This command enables reception of broadcast server messages to
404 any local interface (type b) address.
405 Upon receiving a message for
406 the first time, the broadcast client measures the nominal server
407 propagation delay using a brief client/server exchange with the
408 server, then enters the broadcast client mode, in which it
409 synchronizes to succeeding broadcast messages.
410 Note that, in order
411 to avoid accidental or malicious disruption in this mode, both the
412 server and client should operate using symmetric\-key or public\-key
413 authentication as described in
414 .Sx Authentication Options .
415 .It Ic manycastserver Ar address ...
416 This command enables reception of manycast client messages to
417 the multicast group address(es) (type m) specified.
418 At least one
419 address is required, but the NTP multicast address 224.0.1.1
420 assigned by the IANA should NOT be used, unless specific means are
421 taken to limit the span of the reply and avoid a possibly massive
422 implosion at the original sender.
423 Note that, in order to avoid
424 accidental or malicious disruption in this mode, both the server
425 and client should operate using symmetric\-key or public\-key
426 authentication as described in
427 .Sx Authentication Options .
428 .It Ic multicastclient Ar address ...
429 This command enables reception of multicast server messages to
430 the multicast group address(es) (type m) specified.
431 Upon receiving
432 a message for the first time, the multicast client measures the
433 nominal server propagation delay using a brief client/server
434 exchange with the server, then enters the broadcast client mode, in
435 which it synchronizes to succeeding multicast messages.
436 Note that,
437 in order to avoid accidental or malicious disruption in this mode,
438 both the server and client should operate using symmetric\-key or
439 public\-key authentication as described in
440 .Sx Authentication Options .
441 .It Ic mdnstries Ar number
442 If we are participating in mDNS,
443 after we have synched for the first time
444 we attempt to register with the mDNS system.
445 If that registration attempt fails,
446 we try again at one minute intervals for up to
447 .Ic mdnstries
448 times.
449 After all,
450 .Ic ntpd
451 may be starting before mDNS.
452 The default value for
453 .Ic mdnstries
454 is 5.
455 .El
456 .Sh Authentication Support
457 Authentication support allows the NTP client to verify that the
458 server is in fact known and trusted and not an intruder intending
459 accidentally or on purpose to masquerade as that server.
460 The NTPv3
461 specification RFC\-1305 defines a scheme which provides
462 cryptographic authentication of received NTP packets.
463 Originally,
464 this was done using the Data Encryption Standard (DES) algorithm
465 operating in Cipher Block Chaining (CBC) mode, commonly called
466 DES\-CBC.
467 Subsequently, this was replaced by the RSA Message Digest
468 5 (MD5) algorithm using a private key, commonly called keyed\-MD5.
469 Either algorithm computes a message digest, or one\-way hash, which
470 can be used to verify the server has the correct private key and
471 key identifier.
472 .Pp
473 NTPv4 retains the NTPv3 scheme, properly described as symmetric key
474 cryptography and, in addition, provides a new Autokey scheme
475 based on public key cryptography.
476 Public key cryptography is generally considered more secure
477 than symmetric key cryptography, since the security is based
478 on a private value which is generated by each server and
479 never revealed.
480 With Autokey all key distribution and
481 management functions involve only public values, which
482 considerably simplifies key distribution and storage.
483 Public key management is based on X.509 certificates,
484 which can be provided by commercial services or
485 produced by utility programs in the OpenSSL software library
486 or the NTPv4 distribution.
487 .Pp
488 While the algorithms for symmetric key cryptography are
489 included in the NTPv4 distribution, public key cryptography
490 requires the OpenSSL software library to be installed
491 before building the NTP distribution.
492 Directions for doing that
493 are on the Building and Installing the Distribution page.
494 .Pp
495 Authentication is configured separately for each association
496 using the
497 .Cm key
498 or
499 .Cm autokey
500 subcommand on the
501 .Ic peer ,
502 .Ic server ,
503 .Ic broadcast
504 and
505 .Ic manycastclient
506 configuration commands as described in
507 .Sx Configuration Options
508 page.
509 The authentication
510 options described below specify the locations of the key files,
511 if other than default, which symmetric keys are trusted
512 and the interval between various operations, if other than default.
513 .Pp
514 Authentication is always enabled,
515 although ineffective if not configured as
516 described below.
517 If a NTP packet arrives
518 including a message authentication
519 code (MAC), it is accepted only if it
520 passes all cryptographic checks.
521 The
522 checks require correct key ID, key value
523 and message digest.
524 If the packet has
525 been modified in any way or replayed
526 by an intruder, it will fail one or more
527 of these checks and be discarded.
528 Furthermore, the Autokey scheme requires a
529 preliminary protocol exchange to obtain
530 the server certificate, verify its
531 credentials and initialize the protocol
532 .Pp
533 The
534 .Cm auth
535 flag controls whether new associations or
536 remote configuration commands require cryptographic authentication.
537 This flag can be set or reset by the
538 .Ic enable
539 and
540 .Ic disable
541 commands and also by remote
542 configuration commands sent by a
543 .Xr ntpdc 1ntpdcmdoc
544 program running on
545 another machine.
546 If this flag is enabled, which is the default
547 case, new broadcast client and symmetric passive associations and
548 remote configuration commands must be cryptographically
549 authenticated using either symmetric key or public key cryptography.
550 If this
551 flag is disabled, these operations are effective
552 even if not cryptographic
553 authenticated.
554 It should be understood
555 that operating with the
556 .Ic auth
557 flag disabled invites a significant vulnerability
558 where a rogue hacker can
559 masquerade as a falseticker and seriously
560 disrupt system timekeeping.
561 It is
562 important to note that this flag has no purpose
563 other than to allow or disallow
564 a new association in response to new broadcast
565 and symmetric active messages
566 and remote configuration commands and, in particular,
567 the flag has no effect on
568 the authentication process itself.
569 .Pp
570 An attractive alternative where multicast support is available
571 is manycast mode, in which clients periodically troll
572 for servers as described in the
573 .Sx Automatic NTP Configuration Options
574 page.
575 Either symmetric key or public key
576 cryptographic authentication can be used in this mode.
577 The principle advantage
578 of manycast mode is that potential servers need not be
579 configured in advance,
580 since the client finds them during regular operation,
581 and the configuration
582 files for all clients can be identical.
583 .Pp
584 The security model and protocol schemes for
585 both symmetric key and public key
586 cryptography are summarized below;
587 further details are in the briefings, papers
588 and reports at the NTP project page linked from
589 .Li http://www.ntp.org/ .
590 .Ss Symmetric\-Key Cryptography
591 The original RFC\-1305 specification allows any one of possibly
592 65,535 keys, each distinguished by a 32\-bit key identifier, to
593 authenticate an association.
594 The servers and clients involved must
595 agree on the key and key identifier to
596 authenticate NTP packets.
597 Keys and
598 related information are specified in a key
599 file, usually called
600 .Pa ntp.keys ,
601 which must be distributed and stored using
602 secure means beyond the scope of the NTP protocol itself.
603 Besides the keys used
604 for ordinary NTP associations,
605 additional keys can be used as passwords for the
606 .Xr ntpq 1ntpqmdoc
607 and
608 .Xr ntpdc 1ntpdcmdoc
609 utility programs.
610 .Pp
611 When
612 .Xr ntpd 1ntpdmdoc
613 is first started, it reads the key file specified in the
614 .Ic keys
615 configuration command and installs the keys
616 in the key cache.
617 However,
618 individual keys must be activated with the
619 .Ic trusted
620 command before use.
621 This
622 allows, for instance, the installation of possibly
623 several batches of keys and
624 then activating or deactivating each batch
625 remotely using
626 .Xr ntpdc 1ntpdcmdoc .
627 This also provides a revocation capability that can be used
628 if a key becomes compromised.
629 The
630 .Ic requestkey
631 command selects the key used as the password for the
632 .Xr ntpdc 1ntpdcmdoc
633 utility, while the
634 .Ic controlkey
635 command selects the key used as the password for the
636 .Xr ntpq 1ntpqmdoc
637 utility.
638 .Ss Public Key Cryptography
639 NTPv4 supports the original NTPv3 symmetric key scheme
640 described in RFC\-1305 and in addition the Autokey protocol,
641 which is based on public key cryptography.
642 The Autokey Version 2 protocol described on the Autokey Protocol
643 page verifies packet integrity using MD5 message digests
644 and verifies the source with digital signatures and any of several
645 digest/signature schemes.
646 Optional identity schemes described on the Identity Schemes
647 page and based on cryptographic challenge/response algorithms
648 are also available.
649 Using all of these schemes provides strong security against
650 replay with or without modification, spoofing, masquerade
651 and most forms of clogging attacks.
652 .\" .Pp
653 .\" The cryptographic means necessary for all Autokey operations
654 .\" is provided by the OpenSSL software library.
655 .\" This library is available from http://www.openssl.org/
656 .\" and can be installed using the procedures outlined
657 .\" in the Building and Installing the Distribution page.
658 .\" Once installed,
659 .\" the configure and build
660 .\" process automatically detects the library and links
661 .\" the library routines required.
662 .Pp
663 The Autokey protocol has several modes of operation
664 corresponding to the various NTP modes supported.
665 Most modes use a special cookie which can be
666 computed independently by the client and server,
667 but encrypted in transmission.
668 All modes use in addition a variant of the S\-KEY scheme,
669 in which a pseudo\-random key list is generated and used
670 in reverse order.
671 These schemes are described along with an executive summary,
672 current status, briefing slides and reading list on the
673 .Sx Autonomous Authentication
674 page.
675 .Pp
676 The specific cryptographic environment used by Autokey servers
677 and clients is determined by a set of files
678 and soft links generated by the
679 .Xr ntp\-keygen 1ntpkeygenmdoc
680 program.
681 This includes a required host key file,
682 required certificate file and optional sign key file,
683 leapsecond file and identity scheme files.
684 The
685 digest/signature scheme is specified in the X.509 certificate
686 along with the matching sign key.
687 There are several schemes
688 available in the OpenSSL software library, each identified
689 by a specific string such as
690 .Cm md5WithRSAEncryption ,
691 which stands for the MD5 message digest with RSA
692 encryption scheme.
693 The current NTP distribution supports
694 all the schemes in the OpenSSL library, including
695 those based on RSA and DSA digital signatures.
696 .Pp
697 NTP secure groups can be used to define cryptographic compartments
698 and security hierarchies.
699 It is important that every host
700 in the group be able to construct a certificate trail to one
701 or more trusted hosts in the same group.
702 Each group
703 host runs the Autokey protocol to obtain the certificates
704 for all hosts along the trail to one or more trusted hosts.
705 This requires the configuration file in all hosts to be
706 engineered so that, even under anticipated failure conditions,
707 the NTP subnet will form such that every group host can find
708 a trail to at least one trusted host.
709 .Ss Naming and Addressing
710 It is important to note that Autokey does not use DNS to
711 resolve addresses, since DNS can't be completely trusted
712 until the name servers have synchronized clocks.
713 The cryptographic name used by Autokey to bind the host identity
714 credentials and cryptographic values must be independent
715 of interface, network and any other naming convention.
716 The name appears in the host certificate in either or both
717 the subject and issuer fields, so protection against
718 DNS compromise is essential.
719 .Pp
720 By convention, the name of an Autokey host is the name returned
721 by the Unix
722 .Xr gethostname 2
723 system call or equivalent in other systems.
724 By the system design
725 model, there are no provisions to allow alternate names or aliases.
726 However, this is not to say that DNS aliases, different names
727 for each interface, etc., are constrained in any way.
728 .Pp
729 It is also important to note that Autokey verifies authenticity
730 using the host name, network address and public keys,
731 all of which are bound together by the protocol specifically
732 to deflect masquerade attacks.
733 For this reason Autokey
734 includes the source and destination IP addresses in message digest
735 computations and so the same addresses must be available
736 at both the server and client.
737 For this reason operation
738 with network address translation schemes is not possible.
739 This reflects the intended robust security model where government
740 and corporate NTP servers are operated outside firewall perimeters.
741 .Ss Operation
742 A specific combination of authentication scheme (none,
743 symmetric key, public key) and identity scheme is called
744 a cryptotype, although not all combinations are compatible.
745 There may be management configurations where the clients,
746 servers and peers may not all support the same cryptotypes.
747 A secure NTPv4 subnet can be configured in many ways while
748 keeping in mind the principles explained above and
749 in this section.
750 Note however that some cryptotype
751 combinations may successfully interoperate with each other,
752 but may not represent good security practice.
753 .Pp
754 The cryptotype of an association is determined at the time
755 of mobilization, either at configuration time or some time
756 later when a message of appropriate cryptotype arrives.
757 When mobilized by a
758 .Ic server
759 or
760 .Ic peer
761 configuration command and no
762 .Ic key
763 or
764 .Ic autokey
765 subcommands are present, the association is not
766 authenticated; if the
767 .Ic key
768 subcommand is present, the association is authenticated
769 using the symmetric key ID specified; if the
770 .Ic autokey
771 subcommand is present, the association is authenticated
772 using Autokey.
773 .Pp
774 When multiple identity schemes are supported in the Autokey
775 protocol, the first message exchange determines which one is used.
776 The client request message contains bits corresponding
777 to which schemes it has available.
778 The server response message
779 contains bits corresponding to which schemes it has available.
780 Both server and client match the received bits with their own
781 and select a common scheme.
782 .Pp
783 Following the principle that time is a public value,
784 a server responds to any client packet that matches
785 its cryptotype capabilities.
786 Thus, a server receiving
787 an unauthenticated packet will respond with an unauthenticated
788 packet, while the same server receiving a packet of a cryptotype
789 it supports will respond with packets of that cryptotype.
790 However, unconfigured broadcast or manycast client
791 associations or symmetric passive associations will not be
792 mobilized unless the server supports a cryptotype compatible
793 with the first packet received.
794 By default, unauthenticated associations will not be mobilized
795 unless overridden in a decidedly dangerous way.
796 .Pp
797 Some examples may help to reduce confusion.
798 Client Alice has no specific cryptotype selected.
799 Server Bob has both a symmetric key file and minimal Autokey files.
800 Alice's unauthenticated messages arrive at Bob, who replies with
801 unauthenticated messages.
802 Cathy has a copy of Bob's symmetric
803 key file and has selected key ID 4 in messages to Bob.
804 Bob verifies the message with his key ID 4.
805 If it's the
806 same key and the message is verified, Bob sends Cathy a reply
807 authenticated with that key.
808 If verification fails,
809 Bob sends Cathy a thing called a crypto\-NAK, which tells her
810 something broke.
811 She can see the evidence using the
812 .Xr ntpq 1ntpqmdoc
813 program.
814 .Pp
815 Denise has rolled her own host key and certificate.
816 She also uses one of the identity schemes as Bob.
817 She sends the first Autokey message to Bob and they
818 both dance the protocol authentication and identity steps.
819 If all comes out okay, Denise and Bob continue as described above.
820 .Pp
821 It should be clear from the above that Bob can support
822 all the girls at the same time, as long as he has compatible
823 authentication and identity credentials.
824 Now, Bob can act just like the girls in his own choice of servers;
825 he can run multiple configured associations with multiple different
826 servers (or the same server, although that might not be useful).
827 But, wise security policy might preclude some cryptotype
828 combinations; for instance, running an identity scheme
829 with one server and no authentication with another might not be wise.
830 .Ss Key Management
831 The cryptographic values used by the Autokey protocol are
832 incorporated as a set of files generated by the
833 .Xr ntp\-keygen 1ntpkeygenmdoc
834 utility program, including symmetric key, host key and
835 public certificate files, as well as sign key, identity parameters
836 and leapseconds files.
837 Alternatively, host and sign keys and
838 certificate files can be generated by the OpenSSL utilities
839 and certificates can be imported from public certificate
840 authorities.
841 Note that symmetric keys are necessary for the
842 .Xr ntpq 1ntpqmdoc
843 and
844 .Xr ntpdc 1ntpdcmdoc
845 utility programs.
846 The remaining files are necessary only for the
847 Autokey protocol.
848 .Pp
849 Certificates imported from OpenSSL or public certificate
850 authorities have certian limitations.
851 The certificate should be in ASN.1 syntax, X.509 Version 3
852 format and encoded in PEM, which is the same format
853 used by OpenSSL.
854 The overall length of the certificate encoded
855 in ASN.1 must not exceed 1024 bytes.
856 The subject distinguished
857 name field (CN) is the fully qualified name of the host
858 on which it is used; the remaining subject fields are ignored.
859 The certificate extension fields must not contain either
860 a subject key identifier or a issuer key identifier field;
861 however, an extended key usage field for a trusted host must
862 contain the value
863 .Cm trustRoot ; .
864 Other extension fields are ignored.
865 .Ss Authentication Commands
866 .Bl -tag -width indent
867 .It Ic autokey Op Ar logsec
868 Specifies the interval between regenerations of the session key
869 list used with the Autokey protocol.
870 Note that the size of the key
871 list for each association depends on this interval and the current
872 poll interval.
873 The default value is 12 (4096 s or about 1.1 hours).
874 For poll intervals above the specified interval, a session key list
875 with a single entry will be regenerated for every message
876 sent.
877 .It Ic controlkey Ar key
878 Specifies the key identifier to use with the
879 .Xr ntpq 1ntpqmdoc
880 utility, which uses the standard
881 protocol defined in RFC\-1305.
882 The
883 .Ar key
884 argument is
885 the key identifier for a trusted key, where the value can be in the
886 range 1 to 65,535, inclusive.
887 .It Xo Ic crypto
888 .Op Cm cert Ar file
889 .Op Cm leap Ar file
890 .Op Cm randfile Ar file
891 .Op Cm host Ar file
892 .Op Cm sign Ar file
893 .Op Cm gq Ar file
894 .Op Cm gqpar Ar file
895 .Op Cm iffpar Ar file
896 .Op Cm mvpar Ar file
897 .Op Cm pw Ar password
898 .Xc
899 This command requires the OpenSSL library.
900 It activates public key
901 cryptography, selects the message digest and signature
902 encryption scheme and loads the required private and public
903 values described above.
904 If one or more files are left unspecified,
905 the default names are used as described above.
906 Unless the complete path and name of the file are specified, the
907 location of a file is relative to the keys directory specified
908 in the
909 .Ic keysdir
910 command or default
911 .Pa /usr/local/etc .
912 Following are the subcommands:
913 .Bl -tag -width indent
914 .It Cm cert Ar file
915 Specifies the location of the required host public certificate file.
916 This overrides the link
917 .Pa ntpkey_cert_ Ns Ar hostname
918 in the keys directory.
919 .It Cm gqpar Ar file
920 Specifies the location of the optional GQ parameters file.
921 This
922 overrides the link
923 .Pa ntpkey_gq_ Ns Ar hostname
924 in the keys directory.
925 .It Cm host Ar file
926 Specifies the location of the required host key file.
927 This overrides
928 the link
929 .Pa ntpkey_key_ Ns Ar hostname
930 in the keys directory.
931 .It Cm iffpar Ar file
932 Specifies the location of the optional IFF parameters file.
933 This overrides the link
934 .Pa ntpkey_iff_ Ns Ar hostname
935 in the keys directory.
936 .It Cm leap Ar file
937 Specifies the location of the optional leapsecond file.
938 This overrides the link
939 .Pa ntpkey_leap
940 in the keys directory.
941 .It Cm mvpar Ar file
942 Specifies the location of the optional MV parameters file.
943 This overrides the link
944 .Pa ntpkey_mv_ Ns Ar hostname
945 in the keys directory.
946 .It Cm pw Ar password
947 Specifies the password to decrypt files containing private keys and
948 identity parameters.
949 This is required only if these files have been
950 encrypted.
951 .It Cm randfile Ar file
952 Specifies the location of the random seed file used by the OpenSSL
953 library.
954 The defaults are described in the main text above.
955 .It Cm sign Ar file
956 Specifies the location of the optional sign key file.
957 This overrides
958 the link
959 .Pa ntpkey_sign_ Ns Ar hostname
960 in the keys directory.
961 If this file is
962 not found, the host key is also the sign key.
963 .El
964 .It Ic keys Ar keyfile
965 Specifies the complete path and location of the MD5 key file
966 containing the keys and key identifiers used by
967 .Xr ntpd 1ntpdmdoc ,
968 .Xr ntpq 1ntpqmdoc
969 and
970 .Xr ntpdc 1ntpdcmdoc
971 when operating with symmetric key cryptography.
972 This is the same operation as the
973 .Fl k
974 command line option.
975 .It Ic keysdir Ar path
976 This command specifies the default directory path for
977 cryptographic keys, parameters and certificates.
978 The default is
979 .Pa /usr/local/etc/ .
980 .It Ic requestkey Ar key
981 Specifies the key identifier to use with the
982 .Xr ntpdc 1ntpdcmdoc
983 utility program, which uses a
984 proprietary protocol specific to this implementation of
985 .Xr ntpd 1ntpdmdoc .
986 The
987 .Ar key
988 argument is a key identifier
989 for the trusted key, where the value can be in the range 1 to
990 65,535, inclusive.
991 .It Ic revoke Ar logsec
992 Specifies the interval between re\-randomization of certain
993 cryptographic values used by the Autokey scheme, as a power of 2 in
994 seconds.
995 These values need to be updated frequently in order to
996 deflect brute\-force attacks on the algorithms of the scheme;
997 however, updating some values is a relatively expensive operation.
998 The default interval is 16 (65,536 s or about 18 hours).
999 For poll
1000 intervals above the specified interval, the values will be updated
1001 for every message sent.
1002 .It Ic trustedkey Ar key ...
1003 Specifies the key identifiers which are trusted for the
1004 purposes of authenticating peers with symmetric key cryptography,
1005 as well as keys used by the
1006 .Xr ntpq 1ntpqmdoc
1007 and
1008 .Xr ntpdc 1ntpdcmdoc
1009 programs.
1010 The authentication procedures require that both the local
1011 and remote servers share the same key and key identifier for this
1012 purpose, although different keys can be used with different
1013 servers.
1014 The
1015 .Ar key
1016 arguments are 32\-bit unsigned
1017 integers with values from 1 to 65,535.
1018 .El
1019 .Ss Error Codes
1020 The following error codes are reported via the NTP control
1021 and monitoring protocol trap mechanism.
1022 .Bl -tag -width indent
1023 .It 101
1024 .Pq bad field format or length
1025 The packet has invalid version, length or format.
1026 .It 102
1027 .Pq bad timestamp
1028 The packet timestamp is the same or older than the most recent received.
1029 This could be due to a replay or a server clock time step.
1030 .It 103
1031 .Pq bad filestamp
1032 The packet filestamp is the same or older than the most recent received.
1033 This could be due to a replay or a key file generation error.
1034 .It 104
1035 .Pq bad or missing public key
1036 The public key is missing, has incorrect format or is an unsupported type.
1037 .It 105
1038 .Pq unsupported digest type
1039 The server requires an unsupported digest/signature scheme.
1040 .It 106
1041 .Pq mismatched digest types
1042 Not used.
1043 .It 107
1044 .Pq bad signature length
1045 The signature length does not match the current public key.
1046 .It 108
1047 .Pq signature not verified
1048 The message fails the signature check.
1049 It could be bogus or signed by a
1050 different private key.
1051 .It 109
1052 .Pq certificate not verified
1053 The certificate is invalid or signed with the wrong key.
1054 .It 110
1055 .Pq certificate not verified
1056 The certificate is not yet valid or has expired or the signature could not
1057 be verified.
1058 .It 111
1059 .Pq bad or missing cookie
1060 The cookie is missing, corrupted or bogus.
1061 .It 112
1062 .Pq bad or missing leapseconds table
1063 The leapseconds table is missing, corrupted or bogus.
1064 .It 113
1065 .Pq bad or missing certificate
1066 The certificate is missing, corrupted or bogus.
1067 .It 114
1068 .Pq bad or missing identity
1069 The identity key is missing, corrupt or bogus.
1070 .El
1071 .Sh Monitoring Support
1072 .Xr ntpd 1ntpdmdoc
1073 includes a comprehensive monitoring facility suitable
1074 for continuous, long term recording of server and client
1075 timekeeping performance.
1076 See the
1077 .Ic statistics
1078 command below
1079 for a listing and example of each type of statistics currently
1080 supported.
1081 Statistic files are managed using file generation sets
1082 and scripts in the
1083 .Pa ./scripts
1084 directory of the source code distribution.
1085 Using
1086 these facilities and
1087 .Ux
1088 .Xr cron 8
1089 jobs, the data can be
1090 automatically summarized and archived for retrospective analysis.
1091 .Ss Monitoring Commands
1092 .Bl -tag -width indent
1093 .It Ic statistics Ar name ...
1094 Enables writing of statistics records.
1095 Currently, eight kinds of
1096 .Ar name
1097 statistics are supported.
1098 .Bl -tag -width indent
1099 .It Cm clockstats
1100 Enables recording of clock driver statistics information.
1101 Each update
1102 received from a clock driver appends a line of the following form to
1103 the file generation set named
1104 .Cm clockstats :
1105 .Bd -literal
1106 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1107 .Ed
1108 .Pp
1109 The first two fields show the date (Modified Julian Day) and time
1110 (seconds and fraction past UTC midnight).
1111 The next field shows the
1112 clock address in dotted\-quad notation.
1113 The final field shows the last
1114 timecode received from the clock in decoded ASCII format, where
1115 meaningful.
1116 In some clock drivers a good deal of additional information
1117 can be gathered and displayed as well.
1118 See information specific to each
1119 clock for further details.
1120 .It Cm cryptostats
1121 This option requires the OpenSSL cryptographic software library.
1122 It
1123 enables recording of cryptographic public key protocol information.
1124 Each message received by the protocol module appends a line of the
1125 following form to the file generation set named
1126 .Cm cryptostats :
1127 .Bd -literal
1128 49213 525.624 127.127.4.1 message
1129 .Ed
1130 .Pp
1131 The first two fields show the date (Modified Julian Day) and time
1132 (seconds and fraction past UTC midnight).
1133 The next field shows the peer
1134 address in dotted\-quad notation, The final message field includes the
1135 message type and certain ancillary information.
1136 See the
1137 .Sx Authentication Options
1138 section for further information.
1139 .It Cm loopstats
1140 Enables recording of loop filter statistics information.
1141 Each
1142 update of the local clock outputs a line of the following form to
1143 the file generation set named
1144 .Cm loopstats :
1145 .Bd -literal
1146 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806
1147 .Ed
1148 .Pp
1149 The first two fields show the date (Modified Julian Day) and
1150 time (seconds and fraction past UTC midnight).
1151 The next five fields
1152 show time offset (seconds), frequency offset (parts per million \-
1153 PPM), RMS jitter (seconds), Allan deviation (PPM) and clock
1154 discipline time constant.
1155 .It Cm peerstats
1156 Enables recording of peer statistics information.
1157 This includes
1158 statistics records of all peers of a NTP server and of special
1159 signals, where present and configured.
1160 Each valid update appends a
1161 line of the following form to the current element of a file
1162 generation set named
1163 .Cm peerstats :
1164 .Bd -literal
1165 48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674
1166 .Ed
1167 .Pp
1168 The first two fields show the date (Modified Julian Day) and
1169 time (seconds and fraction past UTC midnight).
1170 The next two fields
1171 show the peer address in dotted\-quad notation and status,
1172 respectively.
1173 The status field is encoded in hex in the format
1174 described in Appendix A of the NTP specification RFC 1305.
1175 The final four fields show the offset,
1176 delay, dispersion and RMS jitter, all in seconds.
1177 .It Cm rawstats
1178 Enables recording of raw\-timestamp statistics information.
1179 This
1180 includes statistics records of all peers of a NTP server and of
1181 special signals, where present and configured.
1182 Each NTP message
1183 received from a peer or clock driver appends a line of the
1184 following form to the file generation set named
1185 .Cm rawstats :
1186 .Bd -literal
1187 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000
1188 .Ed
1189 .Pp
1190 The first two fields show the date (Modified Julian Day) and
1191 time (seconds and fraction past UTC midnight).
1192 The next two fields
1193 show the remote peer or clock address followed by the local address
1194 in dotted\-quad notation.
1195 The final four fields show the originate,
1196 receive, transmit and final NTP timestamps in order.
1197 The timestamp
1198 values are as received and before processing by the various data
1199 smoothing and mitigation algorithms.
1200 .It Cm sysstats
1201 Enables recording of ntpd statistics counters on a periodic basis.
1202 Each
1203 hour a line of the following form is appended to the file generation
1204 set named
1205 .Cm sysstats :
1206 .Bd -literal
1207 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147
1208 .Ed
1209 .Pp
1210 The first two fields show the date (Modified Julian Day) and time
1211 (seconds and fraction past UTC midnight).
1212 The remaining ten fields show
1213 the statistics counter values accumulated since the last generated
1214 line.
1215 .Bl -tag -width indent
1216 .It Time since restart Cm 36000
1217 Time in hours since the system was last rebooted.
1218 .It Packets received Cm 81965
1219 Total number of packets received.
1220 .It Packets processed Cm 0
1221 Number of packets received in response to previous packets sent
1222 .It Current version Cm 9546
1223 Number of packets matching the current NTP version.
1224 .It Previous version Cm 56
1225 Number of packets matching the previous NTP version.
1226 .It Bad version Cm 71793
1227 Number of packets matching neither NTP version.
1228 .It Access denied Cm 512
1229 Number of packets denied access for any reason.
1230 .It Bad length or format Cm 540
1231 Number of packets with invalid length, format or port number.
1232 .It Bad authentication Cm 10
1233 Number of packets not verified as authentic.
1234 .It Rate exceeded Cm 147
1235 Number of packets discarded due to rate limitation.
1236 .El
1237 .It Cm statsdir Ar directory_path
1238 Indicates the full path of a directory where statistics files
1239 should be created (see below).
1240 This keyword allows
1241 the (otherwise constant)
1242 .Cm filegen
1243 filename prefix to be modified for file generation sets, which
1244 is useful for handling statistics logs.
1245 .It Cm filegen Ar name Xo
1246 .Op Cm file Ar filename
1247 .Op Cm type Ar typename
1248 .Op Cm link | nolink
1249 .Op Cm enable | disable
1250 .Xc
1251 Configures setting of generation file set name.
1252 Generation
1253 file sets provide a means for handling files that are
1254 continuously growing during the lifetime of a server.
1255 Server statistics are a typical example for such files.
1256 Generation file sets provide access to a set of files used
1257 to store the actual data.
1258 At any time at most one element
1259 of the set is being written to.
1260 The type given specifies
1261 when and how data will be directed to a new element of the set.
1262 This way, information stored in elements of a file set
1263 that are currently unused are available for administrational
1264 operations without the risk of disturbing the operation of ntpd.
1265 (Most important: they can be removed to free space for new data
1266 produced.)
1267 .Pp
1268 Note that this command can be sent from the
1269 .Xr ntpdc 1ntpdcmdoc
1270 program running at a remote location.
1271 .Bl -tag -width indent
1272 .It Cm name
1273 This is the type of the statistics records, as shown in the
1274 .Cm statistics
1275 command.
1276 .It Cm file Ar filename
1277 This is the file name for the statistics records.
1278 Filenames of set
1279 members are built from three concatenated elements
1280 .Ar Cm prefix ,
1281 .Ar Cm filename
1282 and
1283 .Ar Cm suffix :
1284 .Bl -tag -width indent
1285 .It Cm prefix
1286 This is a constant filename path.
1287 It is not subject to
1288 modifications via the
1289 .Ar filegen
1290 option.
1291 It is defined by the
1292 server, usually specified as a compile\-time constant.
1293 It may,
1294 however, be configurable for individual file generation sets
1295 via other commands.
1296 For example, the prefix used with
1297 .Ar loopstats
1298 and
1299 .Ar peerstats
1300 generation can be configured using the
1301 .Ar statsdir
1302 option explained above.
1303 .It Cm filename
1304 This string is directly concatenated to the prefix mentioned
1305 above (no intervening
1306 .Ql / ) .
1307 This can be modified using
1308 the file argument to the
1309 .Ar filegen
1310 statement.
1311 No
1312 .Pa ..
1313 elements are
1314 allowed in this component to prevent filenames referring to
1315 parts outside the filesystem hierarchy denoted by
1316 .Ar prefix .
1317 .It Cm suffix
1318 This part is reflects individual elements of a file set.
1319 It is
1320 generated according to the type of a file set.
1321 .El
1322 .It Cm type Ar typename
1323 A file generation set is characterized by its type.
1324 The following
1325 types are supported:
1326 .Bl -tag -width indent
1327 .It Cm none
1328 The file set is actually a single plain file.
1329 .It Cm pid
1330 One element of file set is used per incarnation of a ntpd
1331 server.
1332 This type does not perform any changes to file set
1333 members during runtime, however it provides an easy way of
1334 separating files belonging to different
1335 .Xr ntpd 1ntpdmdoc
1336 server incarnations.
1337 The set member filename is built by appending a
1338 .Ql \&.
1339 to concatenated
1340 .Ar prefix
1341 and
1342 .Ar filename
1343 strings, and
1344 appending the decimal representation of the process ID of the
1345 .Xr ntpd 1ntpdmdoc
1346 server process.
1347 .It Cm day
1348 One file generation set element is created per day.
1349 A day is
1350 defined as the period between 00:00 and 24:00 UTC.
1351 The file set
1352 member suffix consists of a
1353 .Ql \&.
1354 and a day specification in
1355 the form
1356 .Cm YYYYMMdd .
1357 .Cm YYYY
1358 is a 4\-digit year number (e.g., 1992).
1359 .Cm MM
1360 is a two digit month number.
1361 .Cm dd
1362 is a two digit day number.
1363 Thus, all information written at 10 December 1992 would end up
1364 in a file named
1365 .Ar prefix
1366 .Ar filename Ns .19921210 .
1367 .It Cm week
1368 Any file set member contains data related to a certain week of
1369 a year.
1370 The term week is defined by computing day\-of\-year
1371 modulo 7.
1372 Elements of such a file generation set are
1373 distinguished by appending the following suffix to the file set
1374 filename base: A dot, a 4\-digit year number, the letter
1375 .Cm W ,
1376 and a 2\-digit week number.
1377 For example, information from January,
1378 10th 1992 would end up in a file with suffix
1379 .No . Ns Ar 1992W1 .
1380 .It Cm month
1381 One generation file set element is generated per month.
1382 The
1383 file name suffix consists of a dot, a 4\-digit year number, and
1384 a 2\-digit month.
1385 .It Cm year
1386 One generation file element is generated per year.
1387 The filename
1388 suffix consists of a dot and a 4 digit year number.
1389 .It Cm age
1390 This type of file generation sets changes to a new element of
1391 the file set every 24 hours of server operation.
1392 The filename
1393 suffix consists of a dot, the letter
1394 .Cm a ,
1395 and an 8\-digit number.
1396 This number is taken to be the number of seconds the server is
1397 running at the start of the corresponding 24\-hour period.
1398 Information is only written to a file generation by specifying
1399 .Cm enable ;
1400 output is prevented by specifying
1401 .Cm disable .
1402 .El
1403 .It Cm link | nolink
1404 It is convenient to be able to access the current element of a file
1405 generation set by a fixed name.
1406 This feature is enabled by
1407 specifying
1408 .Cm link
1409 and disabled using
1410 .Cm nolink .
1411 If link is specified, a
1412 hard link from the current file set element to a file without
1413 suffix is created.
1414 When there is already a file with this name and
1415 the number of links of this file is one, it is renamed appending a
1416 dot, the letter
1417 .Cm C ,
1418 and the pid of the
1419 .Xr ntpd 1ntpdmdoc
1420 server process.
1421 When the
1422 number of links is greater than one, the file is unlinked.
1423 This
1424 allows the current file to be accessed by a constant name.
1425 .It Cm enable \&| Cm disable
1426 Enables or disables the recording function.
1427 .El
1428 .El
1429 .El
1430 .Sh Access Control Support
1431 The
1432 .Xr ntpd 1ntpdmdoc
1433 daemon implements a general purpose address/mask based restriction
1434 list.
1435 The list contains address/match entries sorted first
1436 by increasing address values and and then by increasing mask values.
1437 A match occurs when the bitwise AND of the mask and the packet
1438 source address is equal to the bitwise AND of the mask and
1439 address in the list.
1440 The list is searched in order with the
1441 last match found defining the restriction flags associated
1442 with the entry.
1443 Additional information and examples can be found in the
1444 .Qq Notes on Configuring NTP and Setting up a NTP Subnet
1445 page
1446 (available as part of the HTML documentation
1447 provided in
1448 .Pa /usr/share/doc/ntp ) .
1449 .Pp
1450 The restriction facility was implemented in conformance
1451 with the access policies for the original NSFnet backbone
1452 time servers.
1453 Later the facility was expanded to deflect
1454 cryptographic and clogging attacks.
1455 While this facility may
1456 be useful for keeping unwanted or broken or malicious clients
1457 from congesting innocent servers, it should not be considered
1458 an alternative to the NTP authentication facilities.
1459 Source address based restrictions are easily circumvented
1460 by a determined cracker.
1461 .Pp
1462 Clients can be denied service because they are explicitly
1463 included in the restrict list created by the
1464 .Ic restrict
1465 command
1466 or implicitly as the result of cryptographic or rate limit
1467 violations.
1468 Cryptographic violations include certificate
1469 or identity verification failure; rate limit violations generally
1470 result from defective NTP implementations that send packets
1471 at abusive rates.
1472 Some violations cause denied service
1473 only for the offending packet, others cause denied service
1474 for a timed period and others cause the denied service for
1475 an indefinite period.
1476 When a client or network is denied access
1477 for an indefinite period, the only way at present to remove
1478 the restrictions is by restarting the server.
1479 .Ss The Kiss\-of\-Death Packet
1480 Ordinarily, packets denied service are simply dropped with no
1481 further action except incrementing statistics counters.
1482 Sometimes a
1483 more proactive response is needed, such as a server message that
1484 explicitly requests the client to stop sending and leave a message
1485 for the system operator.
1486 A special packet format has been created
1487 for this purpose called the "kiss\-of\-death" (KoD) packet.
1488 KoD packets have the leap bits set unsynchronized and stratum set
1489 to zero and the reference identifier field set to a four\-byte
1490 ASCII code.
1491 If the
1492 .Cm noserve
1493 or
1494 .Cm notrust
1495 flag of the matching restrict list entry is set,
1496 the code is "DENY"; if the
1497 .Cm limited
1498 flag is set and the rate limit
1499 is exceeded, the code is "RATE".
1500 Finally, if a cryptographic violation occurs, the code is "CRYP".
1501 .Pp
1502 A client receiving a KoD performs a set of sanity checks to
1503 minimize security exposure, then updates the stratum and
1504 reference identifier peer variables, sets the access
1505 denied (TEST4) bit in the peer flash variable and sends
1506 a message to the log.
1507 As long as the TEST4 bit is set,
1508 the client will send no further packets to the server.
1509 The only way at present to recover from this condition is
1510 to restart the protocol at both the client and server.
1511 This
1512 happens automatically at the client when the association times out.
1513 It will happen at the server only if the server operator cooperates.
1514 .Ss Access Control Commands
1515 .Bl -tag -width indent
1516 .It Xo Ic discard
1517 .Op Cm average Ar avg
1518 .Op Cm minimum Ar min
1519 .Op Cm monitor Ar prob
1520 .Xc
1521 Set the parameters of the
1522 .Cm limited
1523 facility which protects the server from
1524 client abuse.
1525 The
1526 .Cm average
1527 subcommand specifies the minimum average packet
1528 spacing, while the
1529 .Cm minimum
1530 subcommand specifies the minimum packet spacing.
1531 Packets that violate these minima are discarded
1532 and a kiss\-o'\-death packet returned if enabled.
1533 The default
1534 minimum average and minimum are 5 and 2, respectively.
1535 The
1536 .Ic monitor
1537 subcommand specifies the probability of discard
1538 for packets that overflow the rate\-control window.
1539 .It Xo Ic restrict address
1540 .Op Cm mask Ar mask
1541 .Op Cm ippeerlimit Ar int
1542 .Op Ar flag ...
1543 .Xc
1544 The
1545 .Ar address
1546 argument expressed in
1547 dotted\-quad form is the address of a host or network.
1548 Alternatively, the
1549 .Ar address
1550 argument can be a valid host DNS name.
1551 The
1552 .Ar mask
1553 argument expressed in dotted\-quad form defaults to
1554 .Cm 255.255.255.255 ,
1555 meaning that the
1556 .Ar address
1557 is treated as the address of an individual host.
1558 A default entry (address
1559 .Cm 0.0.0.0 ,
1560 mask
1561 .Cm 0.0.0.0 )
1562 is always included and is always the first entry in the list.
1563 Note that text string
1564 .Cm default ,
1565 with no mask option, may
1566 be used to indicate the default entry.
1567 The
1568 .Cm ippeerlimit
1569 directive limits the number of peer requests for each IP to
1570 .Ar int ,
1571 where a value of \-1 means "unlimited", the current default.
1572 A value of 0 means "none".
1573 There would usually be at most 1 peering request per IP,
1574 but if the remote peering requests are behind a proxy
1575 there could well be more than 1 per IP.
1576 In the current implementation,
1577 .Cm flag
1578 always
1579 restricts access, i.e., an entry with no flags indicates that free
1580 access to the server is to be given.
1581 The flags are not orthogonal,
1582 in that more restrictive flags will often make less restrictive
1583 ones redundant.
1584 The flags can generally be classed into two
1585 categories, those which restrict time service and those which
1586 restrict informational queries and attempts to do run\-time
1587 reconfiguration of the server.
1588 One or more of the following flags
1589 may be specified:
1590 .Bl -tag -width indent
1591 .It Cm ignore
1592 Deny packets of all kinds, including
1593 .Xr ntpq 1ntpqmdoc
1594 and
1595 .Xr ntpdc 1ntpdcmdoc
1596 queries.
1597 .It Cm kod
1598 If this flag is set when an access violation occurs, a kiss\-o'\-death
1599 (KoD) packet is sent.
1600 KoD packets are rate limited to no more than one
1601 per second.
1602 If another KoD packet occurs within one second after the
1603 last one, the packet is dropped.
1604 .It Cm limited
1605 Deny service if the packet spacing violates the lower limits specified
1606 in the
1607 .Ic discard
1608 command.
1609 A history of clients is kept using the
1610 monitoring capability of
1611 .Xr ntpd 1ntpdmdoc .
1612 Thus, monitoring is always active as
1613 long as there is a restriction entry with the
1614 .Cm limited
1615 flag.
1616 .It Cm lowpriotrap
1617 Declare traps set by matching hosts to be low priority.
1618 The
1619 number of traps a server can maintain is limited (the current limit
1620 is 3).
1621 Traps are usually assigned on a first come, first served
1622 basis, with later trap requestors being denied service.
1623 This flag
1624 modifies the assignment algorithm by allowing low priority traps to
1625 be overridden by later requests for normal priority traps.
1626 .It Cm noepeer
1627 Deny ephemeral peer requests,
1628 even if they come from an authenticated source.
1629 Note that the ability to use a symmetric key for authentication may be restricted to
1630 one or more IPs or subnets via the third field of the
1631 .Pa ntp.keys
1632 file.
1633 This restriction is not enabled by default,
1634 to maintain backward compatability.
1635 Expect
1636 .Cm noepeer
1637 to become the default in ntp\-4.4.
1638 .It Cm nomodify
1639 Deny
1640 .Xr ntpq 1ntpqmdoc
1641 and
1642 .Xr ntpdc 1ntpdcmdoc
1643 queries which attempt to modify the state of the
1644 server (i.e., run time reconfiguration).
1645 Queries which return
1646 information are permitted.
1647 .It Cm noquery
1648 Deny
1649 .Xr ntpq 1ntpqmdoc
1650 and
1651 .Xr ntpdc 1ntpdcmdoc
1652 queries.
1653 Time service is not affected.
1654 .It Cm nopeer
1655 Deny unauthenticated packets which would result in mobilizing a new association.
1656 This includes
1657 broadcast and symmetric active packets
1658 when a configured association does not exist.
1659 It also includes
1660 .Cm pool
1661 associations, so if you want to use servers from a
1662 .Cm pool
1663 directive and also want to use
1664 .Cm nopeer
1665 by default, you'll want a
1666 .Cm "restrict source ..."
1667 line as well that does
1668 .Em not
1669 include the
1670 .Cm nopeer
1671 directive.
1672 .It Cm noserve
1673 Deny all packets except
1674 .Xr ntpq 1ntpqmdoc
1675 and
1676 .Xr ntpdc 1ntpdcmdoc
1677 queries.
1678 .It Cm notrap
1679 Decline to provide mode 6 control message trap service to matching
1680 hosts.
1681 The trap service is a subsystem of the
1682 .Xr ntpq 1ntpqmdoc
1683 control message
1684 protocol which is intended for use by remote event logging programs.
1685 .It Cm notrust
1686 Deny service unless the packet is cryptographically authenticated.
1687 .It Cm ntpport
1688 This is actually a match algorithm modifier, rather than a
1689 restriction flag.
1690 Its presence causes the restriction entry to be
1691 matched only if the source port in the packet is the standard NTP
1692 UDP port (123).
1693 Both
1694 .Cm ntpport
1695 and
1696 .Cm non\-ntpport
1697 may
1698 be specified.
1699 The
1700 .Cm ntpport
1701 is considered more specific and
1702 is sorted later in the list.
1703 .It Ic "serverresponse fuzz"
1704 When reponding to server requests,
1705 fuzz the low order bits of the
1706 .Cm reftime .
1707 .It Cm version
1708 Deny packets that do not match the current NTP version.
1709 .El
1710 .Pp
1711 Default restriction list entries with the flags ignore, interface,
1712 ntpport, for each of the local host's interface addresses are
1713 inserted into the table at startup to prevent the server
1714 from attempting to synchronize to its own time.
1715 A default entry is also always present, though if it is
1716 otherwise unconfigured; no flags are associated
1717 with the default entry (i.e., everything besides your own
1718 NTP server is unrestricted).
1719 .El
1720 .Sh Automatic NTP Configuration Options
1721 .Ss Manycasting
1722 Manycasting is a automatic discovery and configuration paradigm
1723 new to NTPv4.
1724 It is intended as a means for a multicast client
1725 to troll the nearby network neighborhood to find cooperating
1726 manycast servers, validate them using cryptographic means
1727 and evaluate their time values with respect to other servers
1728 that might be lurking in the vicinity.
1729 The intended result is that each manycast client mobilizes
1730 client associations with some number of the "best"
1731 of the nearby manycast servers, yet automatically reconfigures
1732 to sustain this number of servers should one or another fail.
1733 .Pp
1734 Note that the manycasting paradigm does not coincide
1735 with the anycast paradigm described in RFC\-1546,
1736 which is designed to find a single server from a clique
1737 of servers providing the same service.
1738 The manycast paradigm is designed to find a plurality
1739 of redundant servers satisfying defined optimality criteria.
1740 .Pp
1741 Manycasting can be used with either symmetric key
1742 or public key cryptography.
1743 The public key infrastructure (PKI)
1744 offers the best protection against compromised keys
1745 and is generally considered stronger, at least with relatively
1746 large key sizes.
1747 It is implemented using the Autokey protocol and
1748 the OpenSSL cryptographic library available from
1749 .Li http://www.openssl.org/ .
1750 The library can also be used with other NTPv4 modes
1751 as well and is highly recommended, especially for broadcast modes.
1752 .Pp
1753 A persistent manycast client association is configured
1754 using the
1755 .Ic manycastclient
1756 command, which is similar to the
1757 .Ic server
1758 command but with a multicast (IPv4 class
1759 .Cm D
1760 or IPv6 prefix
1761 .Cm FF )
1762 group address.
1763 The IANA has designated IPv4 address 224.1.1.1
1764 and IPv6 address FF05::101 (site local) for NTP.
1765 When more servers are needed, it broadcasts manycast
1766 client messages to this address at the minimum feasible rate
1767 and minimum feasible time\-to\-live (TTL) hops, depending
1768 on how many servers have already been found.
1769 There can be as many manycast client associations
1770 as different group address, each one serving as a template
1771 for a future ephemeral unicast client/server association.
1772 .Pp
1773 Manycast servers configured with the
1774 .Ic manycastserver
1775 command listen on the specified group address for manycast
1776 client messages.
1777 Note the distinction between manycast client,
1778 which actively broadcasts messages, and manycast server,
1779 which passively responds to them.
1780 If a manycast server is
1781 in scope of the current TTL and is itself synchronized
1782 to a valid source and operating at a stratum level equal
1783 to or lower than the manycast client, it replies to the
1784 manycast client message with an ordinary unicast server message.
1785 .Pp
1786 The manycast client receiving this message mobilizes
1787 an ephemeral client/server association according to the
1788 matching manycast client template, but only if cryptographically
1789 authenticated and the server stratum is less than or equal
1790 to the client stratum.
1791 Authentication is explicitly required
1792 and either symmetric key or public key (Autokey) can be used.
1793 Then, the client polls the server at its unicast address
1794 in burst mode in order to reliably set the host clock
1795 and validate the source.
1796 This normally results
1797 in a volley of eight client/server at 2\-s intervals
1798 during which both the synchronization and cryptographic
1799 protocols run concurrently.
1800 Following the volley,
1801 the client runs the NTP intersection and clustering
1802 algorithms, which act to discard all but the "best"
1803 associations according to stratum and synchronization
1804 distance.
1805 The surviving associations then continue
1806 in ordinary client/server mode.
1807 .Pp
1808 The manycast client polling strategy is designed to reduce
1809 as much as possible the volume of manycast client messages
1810 and the effects of implosion due to near\-simultaneous
1811 arrival of manycast server messages.
1812 The strategy is determined by the
1813 .Ic manycastclient ,
1814 .Ic tos
1815 and
1816 .Ic ttl
1817 configuration commands.
1818 The manycast poll interval is
1819 normally eight times the system poll interval,
1820 which starts out at the
1821 .Cm minpoll
1822 value specified in the
1823 .Ic manycastclient ,
1824 command and, under normal circumstances, increments to the
1825 .Cm maxpolll
1826 value specified in this command.
1827 Initially, the TTL is
1828 set at the minimum hops specified by the
1829 .Ic ttl
1830 command.
1831 At each retransmission the TTL is increased until reaching
1832 the maximum hops specified by this command or a sufficient
1833 number client associations have been found.
1834 Further retransmissions use the same TTL.
1835 .Pp
1836 The quality and reliability of the suite of associations
1837 discovered by the manycast client is determined by the NTP
1838 mitigation algorithms and the
1839 .Cm minclock
1840 and
1841 .Cm minsane
1842 values specified in the
1843 .Ic tos
1844 configuration command.
1845 At least
1846 .Cm minsane
1847 candidate servers must be available and the mitigation
1848 algorithms produce at least
1849 .Cm minclock
1850 survivors in order to synchronize the clock.
1851 Byzantine agreement principles require at least four
1852 candidates in order to correctly discard a single falseticker.
1853 For legacy purposes,
1854 .Cm minsane
1855 defaults to 1 and
1856 .Cm minclock
1857 defaults to 3.
1858 For manycast service
1859 .Cm minsane
1860 should be explicitly set to 4, assuming at least that
1861 number of servers are available.
1862 .Pp
1863 If at least
1864 .Cm minclock
1865 servers are found, the manycast poll interval is immediately
1866 set to eight times
1867 .Cm maxpoll .
1868 If less than
1869 .Cm minclock
1870 servers are found when the TTL has reached the maximum hops,
1871 the manycast poll interval is doubled.
1872 For each transmission
1873 after that, the poll interval is doubled again until
1874 reaching the maximum of eight times
1875 .Cm maxpoll .
1876 Further transmissions use the same poll interval and
1877 TTL values.
1878 Note that while all this is going on,
1879 each client/server association found is operating normally
1880 it the system poll interval.
1881 .Pp
1882 Administratively scoped multicast boundaries are normally
1883 specified by the network router configuration and,
1884 in the case of IPv6, the link/site scope prefix.
1885 By default, the increment for TTL hops is 32 starting
1886 from 31; however, the
1887 .Ic ttl
1888 configuration command can be
1889 used to modify the values to match the scope rules.
1890 .Pp
1891 It is often useful to narrow the range of acceptable
1892 servers which can be found by manycast client associations.
1893 Because manycast servers respond only when the client
1894 stratum is equal to or greater than the server stratum,
1895 primary (stratum 1) servers fill find only primary servers
1896 in TTL range, which is probably the most common objective.
1897 However, unless configured otherwise, all manycast clients
1898 in TTL range will eventually find all primary servers
1899 in TTL range, which is probably not the most common
1900 objective in large networks.
1901 The
1902 .Ic tos
1903 command can be used to modify this behavior.
1904 Servers with stratum below
1905 .Cm floor
1906 or above
1907 .Cm ceiling
1908 specified in the
1909 .Ic tos
1910 command are strongly discouraged during the selection
1911 process; however, these servers may be temporally
1912 accepted if the number of servers within TTL range is
1913 less than
1914 .Cm minclock .
1915 .Pp
1916 The above actions occur for each manycast client message,
1917 which repeats at the designated poll interval.
1918 However, once the ephemeral client association is mobilized,
1919 subsequent manycast server replies are discarded,
1920 since that would result in a duplicate association.
1921 If during a poll interval the number of client associations
1922 falls below
1923 .Cm minclock ,
1924 all manycast client prototype associations are reset
1925 to the initial poll interval and TTL hops and operation
1926 resumes from the beginning.
1927 It is important to avoid
1928 frequent manycast client messages, since each one requires
1929 all manycast servers in TTL range to respond.
1930 The result could well be an implosion, either minor or major,
1931 depending on the number of servers in range.
1932 The recommended value for
1933 .Cm maxpoll
1934 is 12 (4,096 s).
1935 .Pp
1936 It is possible and frequently useful to configure a host
1937 as both manycast client and manycast server.
1938 A number of hosts configured this way and sharing a common
1939 group address will automatically organize themselves
1940 in an optimum configuration based on stratum and
1941 synchronization distance.
1942 For example, consider an NTP
1943 subnet of two primary servers and a hundred or more
1944 dependent clients.
1945 With two exceptions, all servers
1946 and clients have identical configuration files including both
1947 .Ic multicastclient
1948 and
1949 .Ic multicastserver
1950 commands using, for instance, multicast group address
1951 239.1.1.1.
1952 The only exception is that each primary server
1953 configuration file must include commands for the primary
1954 reference source such as a GPS receiver.
1955 .Pp
1956 The remaining configuration files for all secondary
1957 servers and clients have the same contents, except for the
1958 .Ic tos
1959 command, which is specific for each stratum level.
1960 For stratum 1 and stratum 2 servers, that command is
1961 not necessary.
1962 For stratum 3 and above servers the
1963 .Cm floor
1964 value is set to the intended stratum number.
1965 Thus, all stratum 3 configuration files are identical,
1966 all stratum 4 files are identical and so forth.
1967 .Pp
1968 Once operations have stabilized in this scenario,
1969 the primary servers will find the primary reference source
1970 and each other, since they both operate at the same
1971 stratum (1), but not with any secondary server or client,
1972 since these operate at a higher stratum.
1973 The secondary
1974 servers will find the servers at the same stratum level.
1975 If one of the primary servers loses its GPS receiver,
1976 it will continue to operate as a client and other clients
1977 will time out the corresponding association and
1978 re\-associate accordingly.
1979 .Pp
1980 Some administrators prefer to avoid running
1981 .Xr ntpd 1ntpdmdoc
1982 continuously and run either
1983 .Xr sntp 1sntpmdoc
1984 or
1985 .Xr ntpd 1ntpdmdoc
1986 .Fl q
1987 as a cron job.
1988 In either case the servers must be
1989 configured in advance and the program fails if none are
1990 available when the cron job runs.
1991 A really slick
1992 application of manycast is with
1993 .Xr ntpd 1ntpdmdoc
1994 .Fl q .
1995 The program wakes up, scans the local landscape looking
1996 for the usual suspects, selects the best from among
1997 the rascals, sets the clock and then departs.
1998 Servers do not have to be configured in advance and
1999 all clients throughout the network can have the same
2000 configuration file.
2001 .Ss Manycast Interactions with Autokey
2002 Each time a manycast client sends a client mode packet
2003 to a multicast group address, all manycast servers
2004 in scope generate a reply including the host name
2005 and status word.
2006 The manycast clients then run
2007 the Autokey protocol, which collects and verifies
2008 all certificates involved.
2009 Following the burst interval
2010 all but three survivors are cast off,
2011 but the certificates remain in the local cache.
2012 It often happens that several complete signing trails
2013 from the client to the primary servers are collected in this way.
2014 .Pp
2015 About once an hour or less often if the poll interval
2016 exceeds this, the client regenerates the Autokey key list.
2017 This is in general transparent in client/server mode.
2018 However, about once per day the server private value
2019 used to generate cookies is refreshed along with all
2020 manycast client associations.
2021 In this case all
2022 cryptographic values including certificates is refreshed.
2023 If a new certificate has been generated since
2024 the last refresh epoch, it will automatically revoke
2025 all prior certificates that happen to be in the
2026 certificate cache.
2027 At the same time, the manycast
2028 scheme starts all over from the beginning and
2029 the expanding ring shrinks to the minimum and increments
2030 from there while collecting all servers in scope.
2031 .Ss Broadcast Options
2032 .Bl -tag -width indent
2033 .It Xo Ic tos
2034 .Oo
2035 .Cm bcpollbstep Ar gate
2036 .Oc
2037 .Xc
2038 This command provides a way to delay,
2039 by the specified number of broadcast poll intervals,
2040 believing backward time steps from a broadcast server.
2041 Broadcast time networks are expected to be trusted.
2042 In the event a broadcast server's time is stepped backwards,
2043 there is clear benefit to having the clients notice this change
2044 as soon as possible.
2045 Attacks such as replay attacks can happen, however,
2046 and even though there are a number of protections built in to
2047 broadcast mode, attempts to perform a replay attack are possible.
2048 This value defaults to 0, but can be changed
2049 to any number of poll intervals between 0 and 4.
2050 .El
2051 .Ss Manycast Options
2052 .Bl -tag -width indent
2053 .It Xo Ic tos
2054 .Oo
2055 .Cm ceiling Ar ceiling |
2056 .Cm cohort { 0 | 1 } |
2057 .Cm floor Ar floor |
2058 .Cm minclock Ar minclock |
2059 .Cm minsane Ar minsane
2060 .Oc
2061 .Xc
2062 This command affects the clock selection and clustering
2063 algorithms.
2064 It can be used to select the quality and
2065 quantity of peers used to synchronize the system clock
2066 and is most useful in manycast mode.
2067 The variables operate
2068 as follows:
2069 .Bl -tag -width indent
2070 .It Cm ceiling Ar ceiling
2071 Peers with strata above
2072 .Cm ceiling
2073 will be discarded if there are at least
2074 .Cm minclock
2075 peers remaining.
2076 This value defaults to 15, but can be changed
2077 to any number from 1 to 15.
2078 .It Cm cohort Bro 0 | 1 Brc
2079 This is a binary flag which enables (0) or disables (1)
2080 manycast server replies to manycast clients with the same
2081 stratum level.
2082 This is useful to reduce implosions where
2083 large numbers of clients with the same stratum level
2084 are present.
2085 The default is to enable these replies.
2086 .It Cm floor Ar floor
2087 Peers with strata below
2088 .Cm floor
2089 will be discarded if there are at least
2090 .Cm minclock
2091 peers remaining.
2092 This value defaults to 1, but can be changed
2093 to any number from 1 to 15.
2094 .It Cm minclock Ar minclock
2095 The clustering algorithm repeatedly casts out outlier
2096 associations until no more than
2097 .Cm minclock
2098 associations remain.
2099 This value defaults to 3,
2100 but can be changed to any number from 1 to the number of
2101 configured sources.
2102 .It Cm minsane Ar minsane
2103 This is the minimum number of candidates available
2104 to the clock selection algorithm in order to produce
2105 one or more truechimers for the clustering algorithm.
2106 If fewer than this number are available, the clock is
2107 undisciplined and allowed to run free.
2108 The default is 1
2109 for legacy purposes.
2110 However, according to principles of
2111 Byzantine agreement,
2112 .Cm minsane
2113 should be at least 4 in order to detect and discard
2114 a single falseticker.
2115 .El
2116 .It Cm ttl Ar hop ...
2117 This command specifies a list of TTL values in increasing
2118 order, up to 8 values can be specified.
2119 In manycast mode these values are used in turn
2120 in an expanding\-ring search.
2121 The default is eight
2122 multiples of 32 starting at 31.
2123 .El
2124 .Sh Reference Clock Support
2125 The NTP Version 4 daemon supports some three dozen different radio,
2126 satellite and modem reference clocks plus a special pseudo\-clock
2127 used for backup or when no other clock source is available.
2128 Detailed descriptions of individual device drivers and options can
2129 be found in the
2130 .Qq Reference Clock Drivers
2131 page
2132 (available as part of the HTML documentation
2133 provided in
2134 .Pa /usr/share/doc/ntp ) .
2135 Additional information can be found in the pages linked
2136 there, including the
2137 .Qq Debugging Hints for Reference Clock Drivers
2138 and
2139 .Qq How To Write a Reference Clock Driver
2140 pages
2141 (available as part of the HTML documentation
2142 provided in
2143 .Pa /usr/share/doc/ntp ) .
2144 In addition, support for a PPS
2145 signal is available as described in the
2146 .Qq Pulse\-per\-second (PPS) Signal Interfacing
2147 page
2148 (available as part of the HTML documentation
2149 provided in
2150 .Pa /usr/share/doc/ntp ) .
2151 Many
2152 drivers support special line discipline/streams modules which can
2153 significantly improve the accuracy using the driver.
2154 These are
2155 described in the
2156 .Qq Line Disciplines and Streams Drivers
2157 page
2158 (available as part of the HTML documentation
2159 provided in
2160 .Pa /usr/share/doc/ntp ) .
2161 .Pp
2162 A reference clock will generally (though not always) be a radio
2163 timecode receiver which is synchronized to a source of standard
2164 time such as the services offered by the NRC in Canada and NIST and
2165 USNO in the US.
2166 The interface between the computer and the timecode
2167 receiver is device dependent, but is usually a serial port.
2168 A
2169 device driver specific to each reference clock must be selected and
2170 compiled in the distribution; however, most common radio, satellite
2171 and modem clocks are included by default.
2172 Note that an attempt to
2173 configure a reference clock when the driver has not been compiled
2174 or the hardware port has not been appropriately configured results
2175 in a scalding remark to the system log file, but is otherwise non
2176 hazardous.
2177 .Pp
2178 For the purposes of configuration,
2179 .Xr ntpd 1ntpdmdoc
2180 treats
2181 reference clocks in a manner analogous to normal NTP peers as much
2182 as possible.
2183 Reference clocks are identified by a syntactically
2184 correct but invalid IP address, in order to distinguish them from
2185 normal NTP peers.
2186 Reference clock addresses are of the form
2187 .Sm off
2188 .Li 127.127. Ar t . Ar u ,
2189 .Sm on
2190 where
2191 .Ar t
2192 is an integer
2193 denoting the clock type and
2194 .Ar u
2195 indicates the unit
2196 number in the range 0\-3.
2197 While it may seem overkill, it is in fact
2198 sometimes useful to configure multiple reference clocks of the same
2199 type, in which case the unit numbers must be unique.
2200 .Pp
2201 The
2202 .Ic server
2203 command is used to configure a reference
2204 clock, where the
2205 .Ar address
2206 argument in that command
2207 is the clock address.
2208 The
2209 .Cm key ,
2210 .Cm version
2211 and
2212 .Cm ttl
2213 options are not used for reference clock support.
2214 The
2215 .Cm mode
2216 option is added for reference clock support, as
2217 described below.
2218 The
2219 .Cm prefer
2220 option can be useful to
2221 persuade the server to cherish a reference clock with somewhat more
2222 enthusiasm than other reference clocks or peers.
2223 Further
2224 information on this option can be found in the
2225 .Qq Mitigation Rules and the prefer Keyword
2226 (available as part of the HTML documentation
2227 provided in
2228 .Pa /usr/share/doc/ntp )
2229 page.
2230 The
2231 .Cm minpoll
2232 and
2233 .Cm maxpoll
2234 options have
2235 meaning only for selected clock drivers.
2236 See the individual clock
2237 driver document pages for additional information.
2238 .Pp
2239 The
2240 .Ic fudge
2241 command is used to provide additional
2242 information for individual clock drivers and normally follows
2243 immediately after the
2244 .Ic server
2245 command.
2246 The
2247 .Ar address
2248 argument specifies the clock address.
2249 The
2250 .Cm refid
2251 and
2252 .Cm stratum
2253 options can be used to
2254 override the defaults for the device.
2255 There are two optional
2256 device\-dependent time offsets and four flags that can be included
2257 in the
2258 .Ic fudge
2259 command as well.
2260 .Pp
2261 The stratum number of a reference clock is by default zero.
2262 Since the
2263 .Xr ntpd 1ntpdmdoc
2264 daemon adds one to the stratum of each
2265 peer, a primary server ordinarily displays an external stratum of
2266 one.
2267 In order to provide engineered backups, it is often useful to
2268 specify the reference clock stratum as greater than zero.
2269 The
2270 .Cm stratum
2271 option is used for this purpose.
2272 Also, in cases
2273 involving both a reference clock and a pulse\-per\-second (PPS)
2274 discipline signal, it is useful to specify the reference clock
2275 identifier as other than the default, depending on the driver.
2276 The
2277 .Cm refid
2278 option is used for this purpose.
2279 Except where noted,
2280 these options apply to all clock drivers.
2281 .Ss Reference Clock Commands
2282 .Bl -tag -width indent
2283 .It Xo Ic server
2284 .Sm off
2285 .Li 127.127. Ar t . Ar u
2286 .Sm on
2287 .Op Cm prefer
2288 .Op Cm mode Ar int
2289 .Op Cm minpoll Ar int
2290 .Op Cm maxpoll Ar int
2291 .Xc
2292 This command can be used to configure reference clocks in
2293 special ways.
2294 The options are interpreted as follows:
2295 .Bl -tag -width indent
2296 .It Cm prefer
2297 Marks the reference clock as preferred.
2298 All other things being
2299 equal, this host will be chosen for synchronization among a set of
2300 correctly operating hosts.
2301 See the
2302 .Qq Mitigation Rules and the prefer Keyword
2303 page
2304 (available as part of the HTML documentation
2305 provided in
2306 .Pa /usr/share/doc/ntp )
2307 for further information.
2308 .It Cm mode Ar int
2309 Specifies a mode number which is interpreted in a
2310 device\-specific fashion.
2311 For instance, it selects a dialing
2312 protocol in the ACTS driver and a device subtype in the
2313 parse
2314 drivers.
2315 .It Cm minpoll Ar int
2316 .It Cm maxpoll Ar int
2317 These options specify the minimum and maximum polling interval
2318 for reference clock messages, as a power of 2 in seconds
2319 For
2320 most directly connected reference clocks, both
2321 .Cm minpoll
2322 and
2323 .Cm maxpoll
2324 default to 6 (64 s).
2325 For modem reference clocks,
2326 .Cm minpoll
2327 defaults to 10 (17.1 m) and
2328 .Cm maxpoll
2329 defaults to 14 (4.5 h).
2330 The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
2331 .El
2332 .It Xo Ic fudge
2333 .Sm off
2334 .Li 127.127. Ar t . Ar u
2335 .Sm on
2336 .Op Cm time1 Ar sec
2337 .Op Cm time2 Ar sec
2338 .Op Cm stratum Ar int
2339 .Op Cm refid Ar string
2340 .Op Cm mode Ar int
2341 .Op Cm flag1 Cm 0 \&| Cm 1
2342 .Op Cm flag2 Cm 0 \&| Cm 1
2343 .Op Cm flag3 Cm 0 \&| Cm 1
2344 .Op Cm flag4 Cm 0 \&| Cm 1
2345 .Xc
2346 This command can be used to configure reference clocks in
2347 special ways.
2348 It must immediately follow the
2349 .Ic server
2350 command which configures the driver.
2351 Note that the same capability
2352 is possible at run time using the
2353 .Xr ntpdc 1ntpdcmdoc
2354 program.
2355 The options are interpreted as
2356 follows:
2357 .Bl -tag -width indent
2358 .It Cm time1 Ar sec
2359 Specifies a constant to be added to the time offset produced by
2360 the driver, a fixed\-point decimal number in seconds.
2361 This is used
2362 as a calibration constant to adjust the nominal time offset of a
2363 particular clock to agree with an external standard, such as a
2364 precision PPS signal.
2365 It also provides a way to correct a
2366 systematic error or bias due to serial port or operating system
2367 latencies, different cable lengths or receiver internal delay.
2368 The
2369 specified offset is in addition to the propagation delay provided
2370 by other means, such as internal DIPswitches.
2371 Where a calibration
2372 for an individual system and driver is available, an approximate
2373 correction is noted in the driver documentation pages.
2374 Note: in order to facilitate calibration when more than one
2375 radio clock or PPS signal is supported, a special calibration
2376 feature is available.
2377 It takes the form of an argument to the
2378 .Ic enable
2379 command described in
2380 .Sx Miscellaneous Options
2381 page and operates as described in the
2382 .Qq Reference Clock Drivers
2383 page
2384 (available as part of the HTML documentation
2385 provided in
2386 .Pa /usr/share/doc/ntp ) .
2387 .It Cm time2 Ar secs
2388 Specifies a fixed\-point decimal number in seconds, which is
2389 interpreted in a driver\-dependent way.
2390 See the descriptions of
2391 specific drivers in the
2392 .Qq Reference Clock Drivers
2393 page
2394 (available as part of the HTML documentation
2395 provided in
2396 .Pa /usr/share/doc/ntp ).
2397 .It Cm stratum Ar int
2398 Specifies the stratum number assigned to the driver, an integer
2399 between 0 and 15.
2400 This number overrides the default stratum number
2401 ordinarily assigned by the driver itself, usually zero.
2402 .It Cm refid Ar string
2403 Specifies an ASCII string of from one to four characters which
2404 defines the reference identifier used by the driver.
2405 This string
2406 overrides the default identifier ordinarily assigned by the driver
2407 itself.
2408 .It Cm mode Ar int
2409 Specifies a mode number which is interpreted in a
2410 device\-specific fashion.
2411 For instance, it selects a dialing
2412 protocol in the ACTS driver and a device subtype in the
2413 parse
2414 drivers.
2415 .It Cm flag1 Cm 0 \&| Cm 1
2416 .It Cm flag2 Cm 0 \&| Cm 1
2417 .It Cm flag3 Cm 0 \&| Cm 1
2418 .It Cm flag4 Cm 0 \&| Cm 1
2419 These four flags are used for customizing the clock driver.
2420 The
2421 interpretation of these values, and whether they are used at all,
2422 is a function of the particular clock driver.
2423 However, by
2424 convention
2425 .Cm flag4
2426 is used to enable recording monitoring
2427 data to the
2428 .Cm clockstats
2429 file configured with the
2430 .Ic filegen
2431 command.
2432 Further information on the
2433 .Ic filegen
2434 command can be found in
2435 .Sx Monitoring Options .
2436 .El
2437 .El
2438 .Sh Miscellaneous Options
2439 .Bl -tag -width indent
2440 .It Ic broadcastdelay Ar seconds
2441 The broadcast and multicast modes require a special calibration
2442 to determine the network delay between the local and remote
2443 servers.
2444 Ordinarily, this is done automatically by the initial
2445 protocol exchanges between the client and server.
2446 In some cases,
2447 the calibration procedure may fail due to network or server access
2448 controls, for example.
2449 This command specifies the default delay to
2450 be used under these circumstances.
2451 Typically (for Ethernet), a
2452 number between 0.003 and 0.007 seconds is appropriate.
2453 The default
2454 when this command is not used is 0.004 seconds.
2455 .It Ic calldelay Ar delay
2456 This option controls the delay in seconds between the first and second
2457 packets sent in burst or iburst mode to allow additional time for a modem
2458 or ISDN call to complete.
2459 .It Ic driftfile Ar driftfile
2460 This command specifies the complete path and name of the file used to
2461 record the frequency of the local clock oscillator.
2462 This is the same
2463 operation as the
2464 .Fl f
2465 command line option.
2466 If the file exists, it is read at
2467 startup in order to set the initial frequency and then updated once per
2468 hour with the current frequency computed by the daemon.
2469 If the file name is
2470 specified, but the file itself does not exist, the starts with an initial
2471 frequency of zero and creates the file when writing it for the first time.
2472 If this command is not given, the daemon will always start with an initial
2473 frequency of zero.
2474 .Pp
2475 The file format consists of a single line containing a single
2476 floating point number, which records the frequency offset measured
2477 in parts\-per\-million (PPM).
2478 The file is updated by first writing
2479 the current drift value into a temporary file and then renaming
2480 this file to replace the old version.
2481 This implies that
2482 .Xr ntpd 1ntpdmdoc
2483 must have write permission for the directory the
2484 drift file is located in, and that file system links, symbolic or
2485 otherwise, should be avoided.
2486 .It Ic dscp Ar value
2487 This option specifies the Differentiated Services Control Point (DSCP) value,
2488 a 6\-bit code.
2489 The default value is 46, signifying Expedited Forwarding.
2490 .It Xo Ic enable
2491 .Oo
2492 .Cm auth | Cm bclient |
2493 .Cm calibrate | Cm kernel |
2494 .Cm mode7 | Cm monitor |
2495 .Cm ntp | Cm stats |
2496 .Cm peer_clear_digest_early |
2497 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2498 .Oc
2499 .Xc
2500 .It Xo Ic disable
2501 .Oo
2502 .Cm auth | Cm bclient |
2503 .Cm calibrate | Cm kernel |
2504 .Cm mode7 | Cm monitor |
2505 .Cm ntp | Cm stats |
2506 .Cm peer_clear_digest_early |
2507 .Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early
2508 .Oc
2509 .Xc
2510 Provides a way to enable or disable various server options.
2511 Flags not mentioned are unaffected.
2512 Note that all of these flags
2513 can be controlled remotely using the
2514 .Xr ntpdc 1ntpdcmdoc
2515 utility program.
2516 .Bl -tag -width indent
2517 .It Cm auth
2518 Enables the server to synchronize with unconfigured peers only if the
2519 peer has been correctly authenticated using either public key or
2520 private key cryptography.
2521 The default for this flag is
2522 .Ic enable .
2523 .It Cm bclient
2524 Enables the server to listen for a message from a broadcast or
2525 multicast server, as in the
2526 .Ic multicastclient
2527 command with default
2528 address.
2529 The default for this flag is
2530 .Ic disable .
2531 .It Cm calibrate
2532 Enables the calibrate feature for reference clocks.
2533 The default for
2534 this flag is
2535 .Ic disable .
2536 .It Cm kernel
2537 Enables the kernel time discipline, if available.
2538 The default for this
2539 flag is
2540 .Ic enable
2541 if support is available, otherwise
2542 .Ic disable .
2543 .It Cm mode7
2544 Enables processing of NTP mode 7 implementation\-specific requests
2545 which are used by the deprecated
2546 .Xr ntpdc 1ntpdcmdoc
2547 program.
2548 The default for this flag is disable.
2549 This flag is excluded from runtime configuration using
2550 .Xr ntpq 1ntpqmdoc .
2551 The
2552 .Xr ntpq 1ntpqmdoc
2553 program provides the same capabilities as
2554 .Xr ntpdc 1ntpdcmdoc
2555 using standard mode 6 requests.
2556 .It Cm monitor
2557 Enables the monitoring facility.
2558 See the
2559 .Xr ntpdc 1ntpdcmdoc
2560 program
2561 and the
2562 .Ic monlist
2563 command or further information.
2564 The
2565 default for this flag is
2566 .Ic enable .
2567 .It Cm ntp
2568 Enables time and frequency discipline.
2569 In effect, this switch opens and
2570 closes the feedback loop, which is useful for testing.
2571 The default for
2572 this flag is
2573 .Ic enable .
2574 .It Cm peer_clear_digest_early
2575 By default, if
2576 .Xr ntpd 1ntpdmdoc
2577 is using autokey and it
2578 receives a crypto\-NAK packet that
2579 passes the duplicate packet and origin timestamp checks
2580 the peer variables are immediately cleared.
2581 While this is generally a feature
2582 as it allows for quick recovery if a server key has changed,
2583 a properly forged and appropriately delivered crypto\-NAK packet
2584 can be used in a DoS attack.
2585 If you have active noticable problems with this type of DoS attack
2586 then you should consider
2587 disabling this option.
2588 You can check your
2589 .Cm peerstats
2590 file for evidence of any of these attacks.
2591 The
2592 default for this flag is
2593 .Ic enable .
2594 .It Cm stats
2595 Enables the statistics facility.
2596 See the
2597 .Sx Monitoring Options
2598 section for further information.
2599 The default for this flag is
2600 .Ic disable .
2601 .It Cm unpeer_crypto_early
2602 By default, if
2603 .Xr ntpd 1ntpdmdoc
2604 receives an autokey packet that fails TEST9,
2605 a crypto failure,
2606 the association is immediately cleared.
2607 This is almost certainly a feature,
2608 but if, in spite of the current recommendation of not using autokey,
2609 you are
2610 .B still
2611 using autokey
2612 .B and
2613 you are seeing this sort of DoS attack
2614 disabling this flag will delay
2615 tearing down the association until the reachability counter
2616 becomes zero.
2617 You can check your
2618 .Cm peerstats
2619 file for evidence of any of these attacks.
2620 The
2621 default for this flag is
2622 .Ic enable .
2623 .It Cm unpeer_crypto_nak_early
2624 By default, if
2625 .Xr ntpd 1ntpdmdoc
2626 receives a crypto\-NAK packet that
2627 passes the duplicate packet and origin timestamp checks
2628 the association is immediately cleared.
2629 While this is generally a feature
2630 as it allows for quick recovery if a server key has changed,
2631 a properly forged and appropriately delivered crypto\-NAK packet
2632 can be used in a DoS attack.
2633 If you have active noticable problems with this type of DoS attack
2634 then you should consider
2635 disabling this option.
2636 You can check your
2637 .Cm peerstats
2638 file for evidence of any of these attacks.
2639 The
2640 default for this flag is
2641 .Ic enable .
2642 .It Cm unpeer_digest_early
2643 By default, if
2644 .Xr ntpd 1ntpdmdoc
2645 receives what should be an authenticated packet
2646 that passes other packet sanity checks but
2647 contains an invalid digest
2648 the association is immediately cleared.
2649 While this is generally a feature
2650 as it allows for quick recovery,
2651 if this type of packet is carefully forged and sent
2652 during an appropriate window it can be used for a DoS attack.
2653 If you have active noticable problems with this type of DoS attack
2654 then you should consider
2655 disabling this option.
2656 You can check your
2657 .Cm peerstats
2658 file for evidence of any of these attacks.
2659 The
2660 default for this flag is
2661 .Ic enable .
2662 .El
2663 .It Ic includefile Ar includefile
2664 This command allows additional configuration commands
2665 to be included from a separate file.
2666 Include files may
2667 be nested to a depth of five; upon reaching the end of any
2668 include file, command processing resumes in the previous
2669 configuration file.
2670 This option is useful for sites that run
2671 .Xr ntpd 1ntpdmdoc
2672 on multiple hosts, with (mostly) common options (e.g., a
2673 restriction list).
2674 .It Xo Ic interface
2675 .Oo
2676 .Cm listen | Cm ignore | Cm drop
2677 .Oc
2678 .Oo
2679 .Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard
2680 .Ar name | Ar address
2681 .Oo Cm / Ar prefixlen
2682 .Oc
2683 .Oc
2684 .Xc
2685 The
2686 .Cm interface
2687 directive controls which network addresses
2688 .Xr ntpd 1ntpdmdoc
2689 opens, and whether input is dropped without processing.
2690 The first parameter determines the action for addresses
2691 which match the second parameter.
2692 The second parameter specifies a class of addresses,
2693 or a specific interface name,
2694 or an address.
2695 In the address case,
2696 .Ar prefixlen
2697 determines how many bits must match for this rule to apply.
2698 .Cm ignore
2699 prevents opening matching addresses,
2700 .Cm drop
2701 causes
2702 .Xr ntpd 1ntpdmdoc
2703 to open the address and drop all received packets without examination.
2704 Multiple
2705 .Cm interface
2706 directives can be used.
2707 The last rule which matches a particular address determines the action for it.
2708 .Cm interface
2709 directives are disabled if any
2710 .Fl I ,
2711 .Fl \-interface ,
2712 .Fl L ,
2713 or
2714 .Fl \-novirtualips
2715 command\-line options are specified in the configuration file,
2716 all available network addresses are opened.
2717 The
2718 .Cm nic
2719 directive is an alias for
2720 .Cm interface .
2721 .It Ic leapfile Ar leapfile
2722 This command loads the IERS leapseconds file and initializes the
2723 leapsecond values for the next leapsecond event, leapfile expiration
2724 time, and TAI offset.
2725 The file can be obtained directly from the IERS at
2726 .Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list
2727 or
2728 .Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list .
2729 The
2730 .Cm leapfile
2731 is scanned when
2732 .Xr ntpd 1ntpdmdoc
2733 processes the
2734 .Cm leapfile directive or when
2735 .Cm ntpd detects that the
2736 .Ar leapfile
2737 has changed.
2738 .Cm ntpd
2739 checks once a day to see if the
2740 .Ar leapfile
2741 has changed.
2742 The
2743 .Xr update\-leap 1update_leapmdoc
2744 script can be run to see if the
2745 .Ar leapfile
2746 should be updated.
2747 .It Ic leapsmearinterval Ar seconds
2748 This EXPERIMENTAL option is only available if
2749 .Xr ntpd 1ntpdmdoc
2750 was built with the
2751 .Cm \-\-enable\-leap\-smear
2752 option to the
2753 .Cm configure
2754 script.
2755 It specifies the interval over which a leap second correction will be applied.
2756 Recommended values for this option are between
2757 7200 (2 hours) and 86400 (24 hours).
2758 .Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS!
2759 See http://bugs.ntp.org/2855 for more information.
2760 .It Ic logconfig Ar configkeyword
2761 This command controls the amount and type of output written to
2762 the system
2763 .Xr syslog 3
2764 facility or the alternate
2765 .Ic logfile
2766 log file.
2767 By default, all output is turned on.
2768 All
2769 .Ar configkeyword
2770 keywords can be prefixed with
2771 .Ql = ,
2772 .Ql +
2773 and
2774 .Ql \- ,
2775 where
2776 .Ql =
2777 sets the
2778 .Xr syslog 3
2779 priority mask,
2780 .Ql +
2781 adds and
2782 .Ql \-
2783 removes
2784 messages.
2785 .Xr syslog 3
2786 messages can be controlled in four
2787 classes
2788 .Po
2789 .Cm clock ,
2790 .Cm peer ,
2791 .Cm sys
2792 and
2793 .Cm sync
2794 .Pc .
2795 Within these classes four types of messages can be
2796 controlled: informational messages
2797 .Po
2798 .Cm info
2799 .Pc ,
2800 event messages
2801 .Po
2802 .Cm events
2803 .Pc ,
2804 statistics messages
2805 .Po
2806 .Cm statistics
2807 .Pc
2808 and
2809 status messages
2810 .Po
2811 .Cm status
2812 .Pc .
2813 .Pp
2814 Configuration keywords are formed by concatenating the message class with
2815 the event class.
2816 The
2817 .Cm all
2818 prefix can be used instead of a message class.
2819 A
2820 message class may also be followed by the
2821 .Cm all
2822 keyword to enable/disable all
2823 messages of the respective message class.
2824 Thus, a minimal log configuration
2825 could look like this:
2826 .Bd -literal
2827 logconfig =syncstatus +sysevents
2828 .Ed
2829 .Pp
2830 This would just list the synchronizations state of
2831 .Xr ntpd 1ntpdmdoc
2832 and the major system events.
2833 For a simple reference server, the
2834 following minimum message configuration could be useful:
2835 .Bd -literal
2836 logconfig =syncall +clockall
2837 .Ed
2838 .Pp
2839 This configuration will list all clock information and
2840 synchronization information.
2841 All other events and messages about
2842 peers, system events and so on is suppressed.
2843 .It Ic logfile Ar logfile
2844 This command specifies the location of an alternate log file to
2845 be used instead of the default system
2846 .Xr syslog 3
2847 facility.
2848 This is the same operation as the
2849 .Fl l
2850 command line option.
2851 .It Xo Ic mru
2852 .Oo
2853 .Cm maxdepth Ar count | Cm maxmem Ar kilobytes |
2854 .Cm mindepth Ar count | Cm maxage Ar seconds |
2855 .Cm initialloc Ar count | Cm initmem Ar kilobytes |
2856 .Cm incalloc Ar count | Cm incmem Ar kilobytes
2857 .Oc
2858 .Xc
2859 Controls size limite of the monitoring facility's Most Recently Used
2860 (MRU) list
2861 of client addresses, which is also used by the
2862 rate control facility.
2863 .Bl -tag -width indent
2864 .It Ic maxdepth Ar count
2865 .It Ic maxmem Ar kilobytes
2866 Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes.
2867 The acutal limit will be up to
2868 .Cm incalloc
2869 entries or
2870 .Cm incmem
2871 kilobytes larger.
2872 As with all of the
2873 .Cm mru
2874 options offered in units of entries or kilobytes, if both
2875 .Cm maxdepth
2876 and
2877 .Cm maxmem are used, the last one used controls.
2878 The default is 1024 kilobytes.
2879 .It Cm mindepth Ar count
2880 Lower limit on the MRU list size.
2881 When the MRU list has fewer than
2882 .Cm mindepth
2883 entries, existing entries are never removed to make room for newer ones,
2884 regardless of their age.
2885 The default is 600 entries.
2886 .It Cm maxage Ar seconds
2887 Once the MRU list has
2888 .Cm mindepth
2889 entries and an additional client is to ba added to the list,
2890 if the oldest entry was updated more than
2891 .Cm maxage
2892 seconds ago, that entry is removed and its storage is reused.
2893 If the oldest entry was updated more recently the MRU list is grown,
2894 subject to
2895 .Cm maxdepth / moxmem .
2896 The default is 64 seconds.
2897 .It Cm initalloc Ar count
2898 .It Cm initmem Ar kilobytes
2899 Initial memory allocation at the time the monitoringfacility is first enabled,
2900 in terms of the number of entries or kilobytes.
2901 The default is 4 kilobytes.
2902 .It Cm incalloc Ar count
2903 .It Cm incmem Ar kilobytes
2904 Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
2905 The default is 4 kilobytes.
2906 .El
2907 .It Ic nonvolatile Ar threshold
2908 Specify the
2909 .Ar threshold
2910 delta in seconds before an hourly change to the
2911 .Cm driftfile
2912 (frequency file) will be written, with a default value of 1e\-7 (0.1 PPM).
2913 The frequency file is inspected each hour.
2914 If the difference between the current frequency and the last value written
2915 exceeds the threshold, the file is written and the
2916 .Cm threshold
2917 becomes the new threshold value.
2918 If the threshold is not exceeeded, it is reduced by half.
2919 This is intended to reduce the number of file writes
2920 for embedded systems with nonvolatile memory.
2921 .It Ic phone Ar dial ...
2922 This command is used in conjunction with
2923 the ACTS modem driver (type 18)
2924 or the JJY driver (type 40, mode 100 \- 180).
2925 For the ACTS modem driver (type 18), the arguments consist of
2926 a maximum of 10 telephone numbers used to dial USNO, NIST, or European
2927 time service.
2928 For the JJY driver (type 40 mode 100 \- 180), the argument is
2929 one telephone number used to dial the telephone JJY service.
2930 The Hayes command ATDT is normally prepended to the number.
2931 The number can contain other modem control codes as well.
2932 .It Xo Cm pollskewlist
2933 .Oo
2934 .Ar poll
2935 .Ar value | value
2936 .Oc
2937 .Ar ...
2938 .Oo
2939 .Cm default
2940 .Ar value | value
2941 .Oc
2942 .Xc
2943 Enable skewing of our poll requests to our servers.
2944 .Ar poll
2945 is a number between 3 and 17 inclusive, identifying a specific poll interval.
2946 A poll interval is 2^n seconds in duration,
2947 so a poll value of 3 corresponds to 8 seconds
2948 and
2949 a poll interval of 17 corresponds to
2950 131,072 seconds, or about a day and a half.
2951 The next two numbers must be between 0 and one\-half of the poll interval,
2952 inclusive.
2953 The first number specifies how early the poll may start,
2954 while
2955 the second number specifies how late the poll may be delayed.
2956 With no arguments, internally specified default values are chosen.
2957 .It Xo Ic reset
2958 .Oo
2959 .Ic allpeers
2960 .Oc
2961 .Oo
2962 .Ic auth
2963 .Oc
2964 .Oo
2965 .Ic ctl
2966 .Oc
2967 .Oo
2968 .Ic io
2969 .Oc
2970 .Oo
2971 .Ic mem
2972 .Oc
2973 .Oo
2974 .Ic sys
2975 .Oc
2976 .Oo
2977 .Ic timer
2978 .Oc
2979 .Xc
2980 Reset one or more groups of counters maintained by
2981 .Cm ntpd
2982 and exposed by
2983 .Cm ntpq
2984 and
2985 .Cm ntpdc .
2986 .It Xo Ic rlimit
2987 .Oo
2988 .Cm memlock Ar Nmegabytes |
2989 .Cm stacksize Ar N4kPages
2990 .Cm filenum Ar Nfiledescriptors
2991 .Oc
2992 .Xc
2993 .Bl -tag -width indent
2994 .It Cm memlock Ar Nmegabytes
2995 Specify the number of megabytes of memory that should be
2996 allocated and locked.
2997 Probably only available under Linux, this option may be useful
2998 when dropping root (the
2999 .Fl i
3000 option).
3001 The default is 32 megabytes on non\-Linux machines, and \-1 under Linux.
3002 -1 means "do not lock the process into memory".
3003 0 means "lock whatever memory the process wants into memory".
3004 .It Cm stacksize Ar N4kPages
3005 Specifies the maximum size of the process stack on systems with the
3006 .Fn mlockall
3007 function.
3008 Defaults to 50 4k pages (200 4k pages in OpenBSD).
3009 .It Cm filenum Ar Nfiledescriptors
3010 Specifies the maximum number of file descriptors ntpd may have open at once.
3011 Defaults to the system default.
3012 .El
3013 .It Ic saveconfigdir Ar directory_path
3014 Specify the directory in which to write configuration snapshots
3015 requested with
3016 .Cm ntpq 's
3017 .Cm saveconfig
3018 command.
3019 If
3020 .Cm saveconfigdir
3021 does not appear in the configuration file,
3022 .Cm saveconfig
3023 requests are rejected by
3024 .Cm ntpd .
3025 .It Ic saveconfig Ar filename
3026 Write the current configuration, including any runtime
3027 modifications given with
3028 .Cm :config
3029 or
3030 .Cm config\-from\-file
3031 to the
3032 .Cm ntpd
3033 host's
3034 .Ar filename
3035 in the
3036 .Cm saveconfigdir .
3037 This command will be rejected unless the
3038 .Cm saveconfigdir
3039 directive appears in
3040 .Cm ntpd 's
3041 configuration file.
3042 .Ar filename
3043 can use
3044 .Xr strftime 3
3045 format directives to substitute the current date and time,
3046 for example,
3047 .Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf .
3048 The filename used is stored in the system variable
3049 .Cm savedconfig .
3050 Authentication is required.
3051 .It Ic setvar Ar variable Op Cm default
3052 This command adds an additional system variable.
3053 These
3054 variables can be used to distribute additional information such as
3055 the access policy.
3056 If the variable of the form
3057 .Sm off
3058 .Va name = Ar value
3059 .Sm on
3060 is followed by the
3061 .Cm default
3062 keyword, the
3063 variable will be listed as part of the default system variables
3064 .Po
3065 .Xr ntpq 1ntpqmdoc
3066 .Ic rv
3067 command
3068 .Pc ) .
3069 These additional variables serve
3070 informational purposes only.
3071 They are not related to the protocol
3072 other that they can be listed.
3073 The known protocol variables will
3074 always override any variables defined via the
3075 .Ic setvar
3076 mechanism.
3077 There are three special variables that contain the names
3078 of all variable of the same group.
3079 The
3080 .Va sys_var_list
3081 holds
3082 the names of all system variables.
3083 The
3084 .Va peer_var_list
3085 holds
3086 the names of all peer variables and the
3087 .Va clock_var_list
3088 holds the names of the reference clock variables.
3089 .It Cm sysinfo
3090 Display operational summary.
3091 .It Cm sysstats
3092 Show statistics counters maintained in the protocol module.
3093 .It Xo Ic tinker
3094 .Oo
3095 .Cm allan Ar allan |
3096 .Cm dispersion Ar dispersion |
3097 .Cm freq Ar freq |
3098 .Cm huffpuff Ar huffpuff |
3099 .Cm panic Ar panic |
3100 .Cm step Ar step |
3101 .Cm stepback Ar stepback |
3102 .Cm stepfwd Ar stepfwd |
3103 .Cm stepout Ar stepout
3104 .Oc
3105 .Xc
3106 This command can be used to alter several system variables in
3107 very exceptional circumstances.
3108 It should occur in the
3109 configuration file before any other configuration options.
3110 The
3111 default values of these variables have been carefully optimized for
3112 a wide range of network speeds and reliability expectations.
3113 In
3114 general, they interact in intricate ways that are hard to predict
3115 and some combinations can result in some very nasty behavior.
3116 Very
3117 rarely is it necessary to change the default values; but, some
3118 folks cannot resist twisting the knobs anyway and this command is
3119 for them.
3120 Emphasis added: twisters are on their own and can expect
3121 no help from the support group.
3122 .Pp
3123 The variables operate as follows:
3124 .Bl -tag -width indent
3125 .It Cm allan Ar allan
3126 The argument becomes the new value for the minimum Allan
3127 intercept, which is a parameter of the PLL/FLL clock discipline
3128 algorithm.
3129 The value in log2 seconds defaults to 7 (1024 s), which is also the lower
3130 limit.
3131 .It Cm dispersion Ar dispersion
3132 The argument becomes the new value for the dispersion increase rate,
3133 normally .000015 s/s.
3134 .It Cm freq Ar freq
3135 The argument becomes the initial value of the frequency offset in
3136 parts\-per\-million.
3137 This overrides the value in the frequency file, if
3138 present, and avoids the initial training state if it is not.
3139 .It Cm huffpuff Ar huffpuff
3140 The argument becomes the new value for the experimental
3141 huff\-n'\-puff filter span, which determines the most recent interval
3142 the algorithm will search for a minimum delay.
3143 The lower limit is
3144 900 s (15 m), but a more reasonable value is 7200 (2 hours).
3145 There
3146 is no default, since the filter is not enabled unless this command
3147 is given.
3148 .It Cm panic Ar panic
3149 The argument is the panic threshold, normally 1000 s.
3150 If set to zero,
3151 the panic sanity check is disabled and a clock offset of any value will
3152 be accepted.
3153 .It Cm step Ar step
3154 The argument is the step threshold, which by default is 0.128 s.
3155 It can
3156 be set to any positive number in seconds.
3157 If set to zero, step
3158 adjustments will never occur.
3159 Note: The kernel time discipline is
3160 disabled if the step threshold is set to zero or greater than the
3161 default.
3162 .It Cm stepback Ar stepback
3163 The argument is the step threshold for the backward direction,
3164 which by default is 0.128 s.
3165 It can
3166 be set to any positive number in seconds.
3167 If both the forward and backward step thresholds are set to zero, step
3168 adjustments will never occur.
3169 Note: The kernel time discipline is
3170 disabled if
3171 each direction of step threshold are either
3172 set to zero or greater than .5 second.
3173 .It Cm stepfwd Ar stepfwd
3174 As for stepback, but for the forward direction.
3175 .It Cm stepout Ar stepout
3176 The argument is the stepout timeout, which by default is 900 s.
3177 It can
3178 be set to any positive number in seconds.
3179 If set to zero, the stepout
3180 pulses will not be suppressed.
3181 .El
3182 .It Cm writevar Ar assocID\ name = value [,...]
3183 Write (create or update) the specified variables.
3184 If the
3185 .Cm assocID
3186 is zero, the variablea re from the
3187 system variables
3188 name space, otherwise they are from the
3189 peer variables
3190 name space.
3191 The
3192 .Cm assocID
3193 is required, as the same name can occur in both name spaces.
3194 .It Xo Ic trap Ar host_address
3195 .Op Cm port Ar port_number
3196 .Op Cm interface Ar interface_address
3197 .Xc
3198 This command configures a trap receiver at the given host
3199 address and port number for sending messages with the specified
3200 local interface address.
3201 If the port number is unspecified, a value
3202 of 18447 is used.
3203 If the interface address is not specified, the
3204 message is sent with a source address of the local interface the
3205 message is sent through.
3206 Note that on a multihomed host the
3207 interface used may vary from time to time with routing changes.
3208 .It Cm ttl Ar hop ...
3209 This command specifies a list of TTL values in increasing order.
3210 Up to 8 values can be specified.
3211 In
3212 .Cm manycast
3213 mode these values are used in\-turn in an expanding\-ring search.
3214 The default is eight multiples of 32 starting at 31.
3215 .Pp
3216 The trap receiver will generally log event messages and other
3217 information from the server in a log file.
3218 While such monitor
3219 programs may also request their own trap dynamically, configuring a
3220 trap receiver will ensure that no messages are lost when the server
3221 is started.
3222 .It Cm hop Ar ...
3223 This command specifies a list of TTL values in increasing order, up to 8
3224 values can be specified.
3225 In manycast mode these values are used in turn in
3226 an expanding\-ring search.
3227 The default is eight multiples of 32 starting at
3228 31.
3229 .El
3230 .Sh "OPTIONS"
3231 .Bl -tag
3232 .It Fl \-help
3233 Display usage information and exit.
3234 .It Fl \-more\-help
3235 Pass the extended usage information through a pager.
3236 .It Fl \-version Op Brq Ar v|c|n
3237 Output version of program and exit. The default mode is `v', a simple
3238 version. The `c' mode will print copyright information and `n' will
3239 print the full copyright notice.
3240 .El
3241 .Sh "OPTION PRESETS"
3242 Any option that is not marked as \fInot presettable\fP may be preset
3243 by loading values from environment variables named:
3244 .nf
3245 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP
3246 .fi
3247 .ad
3248 .Sh "ENVIRONMENT"
3249 See \fBOPTION PRESETS\fP for configuration environment variables.
3250 .Sh FILES
3251 .Bl -tag -width /etc/ntp.drift -compact
3252 .It Pa /etc/ntp.conf
3253 the default name of the configuration file
3254 .It Pa ntp.keys
3255 private MD5 keys
3256 .It Pa ntpkey
3257 RSA private key
3258 .It Pa ntpkey_ Ns Ar host
3259 RSA public key
3260 .It Pa ntp_dh
3261 Diffie\-Hellman agreement parameters
3262 .El
3263 .Sh "EXIT STATUS"
3264 One of the following exit values will be returned:
3265 .Bl -tag
3266 .It 0 " (EXIT_SUCCESS)"
3267 Successful program execution.
3268 .It 1 " (EXIT_FAILURE)"
3269 The operation failed or the command syntax was not valid.
3270 .It 70 " (EX_SOFTWARE)"
3271 libopts had an internal operational error. Please report
3272 it to autogen\-users@lists.sourceforge.net. Thank you.
3273 .El
3274 .Sh "SEE ALSO"
3275 .Xr ntpd 1ntpdmdoc ,
3276 .Xr ntpdc 1ntpdcmdoc ,
3277 .Xr ntpq 1ntpqmdoc
3278 .Pp
3279 In addition to the manual pages provided,
3280 comprehensive documentation is available on the world wide web
3281 at
3282 .Li http://www.ntp.org/ .
3283 A snapshot of this documentation is available in HTML format in
3284 .Pa /usr/share/doc/ntp .
3285 .Rs
3286 .%A David L. Mills
3287 .%T Network Time Protocol (Version 4)
3288 .%O RFC5905
3289 .Re
3290 .Sh "AUTHORS"
3291 The University of Delaware and Network Time Foundation
3292 .Sh "COPYRIGHT"
3293 Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved.
3294 This program is released under the terms of the NTP license, <http://ntp.org/license>.
3295 .Sh BUGS
3296 The syntax checking is not picky; some combinations of
3297 ridiculous and even hilarious options and modes may not be
3298 detected.
3299 .Pp
3300 The
3301 .Pa ntpkey_ Ns Ar host
3302 files are really digital
3303 certificates.
3304 These should be obtained via secure directory
3305 services when they become universally available.
3306 .Pp
3307 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
3308 .Sh NOTES
3309 This document was derived from FreeBSD.
3310 .Pp
3311 This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP
3312 option definitions.