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