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