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