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