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