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