contrib/ntp/ntpd/ntp.conf.html

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