"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
   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 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 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
  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 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 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 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 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 ,
 1555 meaning that the
 1556 .Ar address
 1557 is treated as the address of an individual host.
 1558 A default entry (address
 1559 .Cm ,
 1560 mask
 1561 .Cm )
 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
 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
 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).
 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
 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
 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.