contrib/ntp/ntpd/ntp.conf.html

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