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