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