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.8p8 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">Manycast Options</h5> 1930 1931 <dl> 1932<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 1933algorithms. 1934It can be used to select the quality and 1935quantity of peers used to synchronize the system clock 1936and is most useful in manycast mode. 1937The variables operate 1938as follows: 1939 <dl> 1940<dt><code>ceiling</code> <kbd>ceiling</kbd><dd>Peers with strata above 1941<code>ceiling</code> 1942will be discarded if there are at least 1943<code>minclock</code> 1944peers remaining. 1945This value defaults to 15, but can be changed 1946to any number from 1 to 15. 1947<br><dt><code>cohort</code> <code>{0 | 1}</code><dd>This is a binary flag which enables (0) or disables (1) 1948manycast server replies to manycast clients with the same 1949stratum level. 1950This is useful to reduce implosions where 1951large numbers of clients with the same stratum level 1952are present. 1953The default is to enable these replies. 1954<br><dt><code>floor</code> <kbd>floor</kbd><dd>Peers with strata below 1955<code>floor</code> 1956will be discarded if there are at least 1957<code>minclock</code> 1958peers remaining. 1959This value defaults to 1, but can be changed 1960to any number from 1 to 15. 1961<br><dt><code>minclock</code> <kbd>minclock</kbd><dd>The clustering algorithm repeatedly casts out outlier 1962associations until no more than 1963<code>minclock</code> 1964associations remain. 1965This value defaults to 3, 1966but can be changed to any number from 1 to the number of 1967configured sources. 1968<br><dt><code>minsane</code> <kbd>minsane</kbd><dd>This is the minimum number of candidates available 1969to the clock selection algorithm in order to produce 1970one or more truechimers for the clustering algorithm. 1971If fewer than this number are available, the clock is 1972undisciplined and allowed to run free. 1973The default is 1 1974for legacy purposes. 1975However, according to principles of 1976Byzantine agreement, 1977<code>minsane</code> 1978should be at least 4 in order to detect and discard 1979a single falseticker. 1980</dl> 1981 <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing 1982order, up to 8 values can be specified. 1983In manycast mode these values are used in turn 1984in an expanding-ring search. 1985The default is eight 1986multiples of 32 starting at 31. 1987</dl> 1988<div class="node"> 1989<p><hr> 1990<a name="Reference-Clock-Support"></a> 1991<br> 1992</div> 1993 1994<h4 class="subsection">Reference Clock Support</h4> 1995 1996<p>The NTP Version 4 daemon supports some three dozen different radio, 1997satellite and modem reference clocks plus a special pseudo-clock 1998used for backup or when no other clock source is available. 1999Detailed descriptions of individual device drivers and options can 2000be found in the 2001"Reference Clock Drivers" 2002page 2003(available as part of the HTML documentation 2004provided in 2005<span class="file">/usr/share/doc/ntp</span>). 2006Additional information can be found in the pages linked 2007there, including the 2008"Debugging Hints for Reference Clock Drivers" 2009and 2010"How To Write a Reference Clock Driver" 2011pages 2012(available as part of the HTML documentation 2013provided in 2014<span class="file">/usr/share/doc/ntp</span>). 2015In addition, support for a PPS 2016signal is available as described in the 2017"Pulse-per-second (PPS) Signal Interfacing" 2018page 2019(available as part of the HTML documentation 2020provided in 2021<span class="file">/usr/share/doc/ntp</span>). 2022Many 2023drivers support special line discipline/streams modules which can 2024significantly improve the accuracy using the driver. 2025These are 2026described in the 2027"Line Disciplines and Streams Drivers" 2028page 2029(available as part of the HTML documentation 2030provided in 2031<span class="file">/usr/share/doc/ntp</span>). 2032 2033 <p>A reference clock will generally (though not always) be a radio 2034timecode receiver which is synchronized to a source of standard 2035time such as the services offered by the NRC in Canada and NIST and 2036USNO in the US. 2037The interface between the computer and the timecode 2038receiver is device dependent, but is usually a serial port. 2039A 2040device driver specific to each reference clock must be selected and 2041compiled in the distribution; however, most common radio, satellite 2042and modem clocks are included by default. 2043Note that an attempt to 2044configure a reference clock when the driver has not been compiled 2045or the hardware port has not been appropriately configured results 2046in a scalding remark to the system log file, but is otherwise non 2047hazardous. 2048 2049 <p>For the purposes of configuration, 2050<code>ntpd(1ntpdmdoc)</code> 2051treats 2052reference clocks in a manner analogous to normal NTP peers as much 2053as possible. 2054Reference clocks are identified by a syntactically 2055correct but invalid IP address, in order to distinguish them from 2056normal NTP peers. 2057Reference clock addresses are of the form 2058<code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd>, 2059where 2060<kbd>t</kbd> 2061is an integer 2062denoting the clock type and 2063<kbd>u</kbd> 2064indicates the unit 2065number in the range 0-3. 2066While it may seem overkill, it is in fact 2067sometimes useful to configure multiple reference clocks of the same 2068type, in which case the unit numbers must be unique. 2069 2070 <p>The 2071<code>server</code> 2072command is used to configure a reference 2073clock, where the 2074<kbd>address</kbd> 2075argument in that command 2076is the clock address. 2077The 2078<code>key</code>, 2079<code>version</code> 2080and 2081<code>ttl</code> 2082options are not used for reference clock support. 2083The 2084<code>mode</code> 2085option is added for reference clock support, as 2086described below. 2087The 2088<code>prefer</code> 2089option can be useful to 2090persuade the server to cherish a reference clock with somewhat more 2091enthusiasm than other reference clocks or peers. 2092Further 2093information on this option can be found in the 2094"Mitigation Rules and the prefer Keyword" 2095(available as part of the HTML documentation 2096provided in 2097<span class="file">/usr/share/doc/ntp</span>) 2098page. 2099The 2100<code>minpoll</code> 2101and 2102<code>maxpoll</code> 2103options have 2104meaning only for selected clock drivers. 2105See the individual clock 2106driver document pages for additional information. 2107 2108 <p>The 2109<code>fudge</code> 2110command is used to provide additional 2111information for individual clock drivers and normally follows 2112immediately after the 2113<code>server</code> 2114command. 2115The 2116<kbd>address</kbd> 2117argument specifies the clock address. 2118The 2119<code>refid</code> 2120and 2121<code>stratum</code> 2122options can be used to 2123override the defaults for the device. 2124There are two optional 2125device-dependent time offsets and four flags that can be included 2126in the 2127<code>fudge</code> 2128command as well. 2129 2130 <p>The stratum number of a reference clock is by default zero. 2131Since the 2132<code>ntpd(1ntpdmdoc)</code> 2133daemon adds one to the stratum of each 2134peer, a primary server ordinarily displays an external stratum of 2135one. 2136In order to provide engineered backups, it is often useful to 2137specify the reference clock stratum as greater than zero. 2138The 2139<code>stratum</code> 2140option is used for this purpose. 2141Also, in cases 2142involving both a reference clock and a pulse-per-second (PPS) 2143discipline signal, it is useful to specify the reference clock 2144identifier as other than the default, depending on the driver. 2145The 2146<code>refid</code> 2147option is used for this purpose. 2148Except where noted, 2149these options apply to all clock drivers. 2150 2151<h5 class="subsubsection">Reference Clock Commands</h5> 2152 2153 <dl> 2154<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 2155special ways. 2156The options are interpreted as follows: 2157 <dl> 2158<dt><code>prefer</code><dd>Marks the reference clock as preferred. 2159All other things being 2160equal, this host will be chosen for synchronization among a set of 2161correctly operating hosts. 2162See the 2163"Mitigation Rules and the prefer Keyword" 2164page 2165(available as part of the HTML documentation 2166provided in 2167<span class="file">/usr/share/doc/ntp</span>) 2168for further information. 2169<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 2170device-specific fashion. 2171For instance, it selects a dialing 2172protocol in the ACTS driver and a device subtype in the 2173parse 2174drivers. 2175<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 2176for reference clock messages, as a power of 2 in seconds 2177For 2178most directly connected reference clocks, both 2179<code>minpoll</code> 2180and 2181<code>maxpoll</code> 2182default to 6 (64 s). 2183For modem reference clocks, 2184<code>minpoll</code> 2185defaults to 10 (17.1 m) and 2186<code>maxpoll</code> 2187defaults to 14 (4.5 h). 2188The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2189</dl> 2190 <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 2191special ways. 2192It must immediately follow the 2193<code>server</code> 2194command which configures the driver. 2195Note that the same capability 2196is possible at run time using the 2197<code>ntpdc(1ntpdcmdoc)</code> 2198program. 2199The options are interpreted as 2200follows: 2201 <dl> 2202<dt><code>time1</code> <kbd>sec</kbd><dd>Specifies a constant to be added to the time offset produced by 2203the driver, a fixed-point decimal number in seconds. 2204This is used 2205as a calibration constant to adjust the nominal time offset of a 2206particular clock to agree with an external standard, such as a 2207precision PPS signal. 2208It also provides a way to correct a 2209systematic error or bias due to serial port or operating system 2210latencies, different cable lengths or receiver internal delay. 2211The 2212specified offset is in addition to the propagation delay provided 2213by other means, such as internal DIPswitches. 2214Where a calibration 2215for an individual system and driver is available, an approximate 2216correction is noted in the driver documentation pages. 2217Note: in order to facilitate calibration when more than one 2218radio clock or PPS signal is supported, a special calibration 2219feature is available. 2220It takes the form of an argument to the 2221<code>enable</code> 2222command described in 2223<a href="#Miscellaneous-Options">Miscellaneous Options</a> 2224page and operates as described in the 2225"Reference Clock Drivers" 2226page 2227(available as part of the HTML documentation 2228provided in 2229<span class="file">/usr/share/doc/ntp</span>). 2230<br><dt><code>time2</code> <kbd>secs</kbd><dd>Specifies a fixed-point decimal number in seconds, which is 2231interpreted in a driver-dependent way. 2232See the descriptions of 2233specific drivers in the 2234"Reference Clock Drivers" 2235page 2236(available as part of the HTML documentation 2237provided in 2238<span class="file">/usr/share/doc/ntp</span>). 2239<br><dt><code>stratum</code> <kbd>int</kbd><dd>Specifies the stratum number assigned to the driver, an integer 2240between 0 and 15. 2241This number overrides the default stratum number 2242ordinarily assigned by the driver itself, usually zero. 2243<br><dt><code>refid</code> <kbd>string</kbd><dd>Specifies an ASCII string of from one to four characters which 2244defines the reference identifier used by the driver. 2245This string 2246overrides the default identifier ordinarily assigned by the driver 2247itself. 2248<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 2249device-specific fashion. 2250For instance, it selects a dialing 2251protocol in the ACTS driver and a device subtype in the 2252parse 2253drivers. 2254<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. 2255The 2256interpretation of these values, and whether they are used at all, 2257is a function of the particular clock driver. 2258However, by 2259convention 2260<code>flag4</code> 2261is used to enable recording monitoring 2262data to the 2263<code>clockstats</code> 2264file configured with the 2265<code>filegen</code> 2266command. 2267Further information on the 2268<code>filegen</code> 2269command can be found in 2270<a href="#Monitoring-Options">Monitoring Options</a>. 2271</dl> 2272 </dl> 2273<div class="node"> 2274<p><hr> 2275<a name="Miscellaneous-Options"></a> 2276<br> 2277</div> 2278 2279<h4 class="subsection">Miscellaneous Options</h4> 2280 2281 <dl> 2282<dt><code>broadcastdelay</code> <kbd>seconds</kbd><dd>The broadcast and multicast modes require a special calibration 2283to determine the network delay between the local and remote 2284servers. 2285Ordinarily, this is done automatically by the initial 2286protocol exchanges between the client and server. 2287In some cases, 2288the calibration procedure may fail due to network or server access 2289controls, for example. 2290This command specifies the default delay to 2291be used under these circumstances. 2292Typically (for Ethernet), a 2293number between 0.003 and 0.007 seconds is appropriate. 2294The default 2295when this command is not used is 0.004 seconds. 2296<br><dt><code>calldelay</code> <kbd>delay</kbd><dd>This option controls the delay in seconds between the first and second 2297packets sent in burst or iburst mode to allow additional time for a modem 2298or ISDN call to complete. 2299<br><dt><code>driftfile</code> <kbd>driftfile</kbd><dd>This command specifies the complete path and name of the file used to 2300record the frequency of the local clock oscillator. 2301This is the same 2302operation as the 2303<code>-f</code> 2304command line option. 2305If the file exists, it is read at 2306startup in order to set the initial frequency and then updated once per 2307hour with the current frequency computed by the daemon. 2308If the file name is 2309specified, but the file itself does not exist, the starts with an initial 2310frequency of zero and creates the file when writing it for the first time. 2311If this command is not given, the daemon will always start with an initial 2312frequency of zero. 2313 2314 <p>The file format consists of a single line containing a single 2315floating point number, which records the frequency offset measured 2316in parts-per-million (PPM). 2317The file is updated by first writing 2318the current drift value into a temporary file and then renaming 2319this file to replace the old version. 2320This implies that 2321<code>ntpd(1ntpdmdoc)</code> 2322must have write permission for the directory the 2323drift file is located in, and that file system links, symbolic or 2324otherwise, should be avoided. 2325<br><dt><code>dscp</code> <kbd>value</kbd><dd>This option specifies the Differentiated Services Control Point (DSCP) value, 2326a 6-bit code. 2327The default value is 46, signifying Expedited Forwarding. 2328<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. 2329Flags not mentioned are unaffected. 2330Note that all of these flags 2331can be controlled remotely using the 2332<code>ntpdc(1ntpdcmdoc)</code> 2333utility program. 2334 <dl> 2335<dt><code>auth</code><dd>Enables the server to synchronize with unconfigured peers only if the 2336peer has been correctly authenticated using either public key or 2337private key cryptography. 2338The default for this flag is 2339<code>enable</code>. 2340<br><dt><code>bclient</code><dd>Enables the server to listen for a message from a broadcast or 2341multicast server, as in the 2342<code>multicastclient</code> 2343command with default 2344address. 2345The default for this flag is 2346<code>disable</code>. 2347<br><dt><code>calibrate</code><dd>Enables the calibrate feature for reference clocks. 2348The default for 2349this flag is 2350<code>disable</code>. 2351<br><dt><code>kernel</code><dd>Enables the kernel time discipline, if available. 2352The default for this 2353flag is 2354<code>enable</code> 2355if support is available, otherwise 2356<code>disable</code>. 2357<br><dt><code>mode7</code><dd>Enables processing of NTP mode 7 implementation-specific requests 2358which are used by the deprecated 2359<code>ntpdc(1ntpdcmdoc)</code> 2360program. 2361The default for this flag is disable. 2362This flag is excluded from runtime configuration using 2363<code>ntpq(1ntpqmdoc)</code>. 2364The 2365<code>ntpq(1ntpqmdoc)</code> 2366program provides the same capabilities as 2367<code>ntpdc(1ntpdcmdoc)</code> 2368using standard mode 6 requests. 2369<br><dt><code>monitor</code><dd>Enables the monitoring facility. 2370See the 2371<code>ntpdc(1ntpdcmdoc)</code> 2372program 2373and the 2374<code>monlist</code> 2375command or further information. 2376The 2377default for this flag is 2378<code>enable</code>. 2379<br><dt><code>ntp</code><dd>Enables time and frequency discipline. 2380In effect, this switch opens and 2381closes the feedback loop, which is useful for testing. 2382The default for 2383this flag is 2384<code>enable</code>. 2385<br><dt><code>peer_clear_digest_early</code><dd>By default, if 2386<code>ntpd(1ntpdmdoc)</code> 2387is using autokey and it 2388receives a crypto-NAK packet that 2389passes the duplicate packet and origin timestamp checks 2390the peer variables are immediately cleared. 2391While this is generally a feature 2392as it allows for quick recovery if a server key has changed, 2393a properly forged and appropriately delivered crypto-NAK packet 2394can be used in a DoS attack. 2395If you have active noticable problems with this type of DoS attack 2396then you should consider 2397disabling this option. 2398You can check your 2399<code>peerstats</code> 2400file for evidence of any of these attacks. 2401The 2402default for this flag is 2403<code>enable</code>. 2404<br><dt><code>stats</code><dd>Enables the statistics facility. 2405See the 2406<a href="#Monitoring-Options">Monitoring Options</a> 2407section for further information. 2408The default for this flag is 2409<code>disable</code>. 2410<br><dt><code>unpeer_crypto_early</code><dd>By default, if 2411<code>ntpd(1ntpdmdoc)</code> 2412receives an autokey packet that fails TEST9, 2413a crypto failure, 2414the association is immediately cleared. 2415This is almost certainly a feature, 2416but if, in spite of the current recommendation of not using autokey, 2417you are 2418.B still 2419using autokey 2420.B and 2421you are seeing this sort of DoS attack 2422disabling this flag will delay 2423tearing down the association until the reachability counter 2424becomes zero. 2425You can check your 2426<code>peerstats</code> 2427file for evidence of any of these attacks. 2428The 2429default for this flag is 2430<code>enable</code>. 2431<br><dt><code>unpeer_crypto_nak_early</code><dd>By default, if 2432<code>ntpd(1ntpdmdoc)</code> 2433receives a crypto-NAK packet that 2434passes the duplicate packet and origin timestamp checks 2435the association is immediately cleared. 2436While this is generally a feature 2437as it allows for quick recovery if a server key has changed, 2438a properly forged and appropriately delivered crypto-NAK packet 2439can be used in a DoS attack. 2440If you have active noticable problems with this type of DoS attack 2441then you should consider 2442disabling this option. 2443You can check your 2444<code>peerstats</code> 2445file for evidence of any of these attacks. 2446The 2447default for this flag is 2448<code>enable</code>. 2449<br><dt><code>unpeer_digest_early</code><dd>By default, if 2450<code>ntpd(1ntpdmdoc)</code> 2451receives what should be an authenticated packet 2452that passes other packet sanity checks but 2453contains an invalid digest 2454the association is immediately cleared. 2455While this is generally a feature 2456as it allows for quick recovery, 2457if this type of packet is carefully forged and sent 2458during an appropriate window it can be used for a DoS attack. 2459If you have active noticable problems with this type of DoS attack 2460then you should consider 2461disabling this option. 2462You can check your 2463<code>peerstats</code> 2464file for evidence of any of these attacks. 2465The 2466default for this flag is 2467<code>enable</code>. 2468</dl> 2469 <br><dt><code>includefile</code> <kbd>includefile</kbd><dd>This command allows additional configuration commands 2470to be included from a separate file. 2471Include files may 2472be nested to a depth of five; upon reaching the end of any 2473include file, command processing resumes in the previous 2474configuration file. 2475This option is useful for sites that run 2476<code>ntpd(1ntpdmdoc)</code> 2477on multiple hosts, with (mostly) common options (e.g., a 2478restriction list). 2479<br><dt><code>leapsmearinterval</code> <kbd>seconds</kbd><dd>This EXPERIMENTAL option is only available if 2480<code>ntpd(1ntpdmdoc)</code> 2481was built with the 2482<code>--enable-leap-smear</code> 2483option to the 2484<code>configure</code> 2485script. 2486It specifies the interval over which a leap second correction will be applied. 2487Recommended values for this option are between 24887200 (2 hours) and 86400 (24 hours). 2489.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2490See http://bugs.ntp.org/2855 for more information. 2491<br><dt><code>logconfig</code> <kbd>configkeyword</kbd><dd>This command controls the amount and type of output written to 2492the system 2493<code>syslog(3)</code> 2494facility or the alternate 2495<code>logfile</code> 2496log file. 2497By default, all output is turned on. 2498All 2499<kbd>configkeyword</kbd> 2500keywords can be prefixed with 2501=, 2502+ 2503and 2504-, 2505where 2506= 2507sets the 2508<code>syslog(3)</code> 2509priority mask, 2510+ 2511adds and 2512- 2513removes 2514messages. 2515<code>syslog(3)</code> 2516messages can be controlled in four 2517classes 2518(<code>clock</code>, <code>peer</code>, <code>sys</code> and <code>sync</code>). 2519Within these classes four types of messages can be 2520controlled: informational messages 2521(<code>info</code>), 2522event messages 2523(<code>events</code>), 2524statistics messages 2525(<code>statistics</code>) 2526and 2527status messages 2528(<code>status</code>). 2529 2530 <p>Configuration keywords are formed by concatenating the message class with 2531the event class. 2532The 2533<code>all</code> 2534prefix can be used instead of a message class. 2535A 2536message class may also be followed by the 2537<code>all</code> 2538keyword to enable/disable all 2539messages of the respective message class. 2540Thus, a minimal log configuration 2541could look like this: 2542<pre class="verbatim"> 2543 logconfig =syncstatus +sysevents 2544</pre> 2545 2546 <p>This would just list the synchronizations state of 2547<code>ntpd(1ntpdmdoc)</code> 2548and the major system events. 2549For a simple reference server, the 2550following minimum message configuration could be useful: 2551<pre class="verbatim"> 2552 logconfig =syncall +clockall 2553</pre> 2554 2555 <p>This configuration will list all clock information and 2556synchronization information. 2557All other events and messages about 2558peers, system events and so on is suppressed. 2559<br><dt><code>logfile</code> <kbd>logfile</kbd><dd>This command specifies the location of an alternate log file to 2560be used instead of the default system 2561<code>syslog(3)</code> 2562facility. 2563This is the same operation as the 2564<code>-l</code> 2565command line option. 2566<br><dt><code>setvar</code> <kbd>variable</kbd> <code>[default]</code><dd>This command adds an additional system variable. 2567These 2568variables can be used to distribute additional information such as 2569the access policy. 2570If the variable of the form 2571<code>name</code><code>=</code><kbd>value</kbd> 2572is followed by the 2573<code>default</code> 2574keyword, the 2575variable will be listed as part of the default system variables 2576(<code>rv</code> command)). 2577These additional variables serve 2578informational purposes only. 2579They are not related to the protocol 2580other that they can be listed. 2581The known protocol variables will 2582always override any variables defined via the 2583<code>setvar</code> 2584mechanism. 2585There are three special variables that contain the names 2586of all variable of the same group. 2587The 2588<code>sys_var_list</code> 2589holds 2590the names of all system variables. 2591The 2592<code>peer_var_list</code> 2593holds 2594the names of all peer variables and the 2595<code>clock_var_list</code> 2596holds the names of the reference clock variables. 2597<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 2598very exceptional circumstances. 2599It should occur in the 2600configuration file before any other configuration options. 2601The 2602default values of these variables have been carefully optimized for 2603a wide range of network speeds and reliability expectations. 2604In 2605general, they interact in intricate ways that are hard to predict 2606and some combinations can result in some very nasty behavior. 2607Very 2608rarely is it necessary to change the default values; but, some 2609folks cannot resist twisting the knobs anyway and this command is 2610for them. 2611Emphasis added: twisters are on their own and can expect 2612no help from the support group. 2613 2614 <p>The variables operate as follows: 2615 <dl> 2616<dt><code>allan</code> <kbd>allan</kbd><dd>The argument becomes the new value for the minimum Allan 2617intercept, which is a parameter of the PLL/FLL clock discipline 2618algorithm. 2619The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2620limit. 2621<br><dt><code>dispersion</code> <kbd>dispersion</kbd><dd>The argument becomes the new value for the dispersion increase rate, 2622normally .000015 s/s. 2623<br><dt><code>freq</code> <kbd>freq</kbd><dd>The argument becomes the initial value of the frequency offset in 2624parts-per-million. 2625This overrides the value in the frequency file, if 2626present, and avoids the initial training state if it is not. 2627<br><dt><code>huffpuff</code> <kbd>huffpuff</kbd><dd>The argument becomes the new value for the experimental 2628huff-n'-puff filter span, which determines the most recent interval 2629the algorithm will search for a minimum delay. 2630The lower limit is 2631900 s (15 m), but a more reasonable value is 7200 (2 hours). 2632There 2633is no default, since the filter is not enabled unless this command 2634is given. 2635<br><dt><code>panic</code> <kbd>panic</kbd><dd>The argument is the panic threshold, normally 1000 s. 2636If set to zero, 2637the panic sanity check is disabled and a clock offset of any value will 2638be accepted. 2639<br><dt><code>step</code> <kbd>step</kbd><dd>The argument is the step threshold, which by default is 0.128 s. 2640It can 2641be set to any positive number in seconds. 2642If set to zero, step 2643adjustments will never occur. 2644Note: The kernel time discipline is 2645disabled if the step threshold is set to zero or greater than the 2646default. 2647<br><dt><code>stepback</code> <kbd>stepback</kbd><dd>The argument is the step threshold for the backward direction, 2648which by default is 0.128 s. 2649It can 2650be set to any positive number in seconds. 2651If both the forward and backward step thresholds are set to zero, step 2652adjustments will never occur. 2653Note: The kernel time discipline is 2654disabled if 2655each direction of step threshold are either 2656set to zero or greater than .5 second. 2657<br><dt><code>stepfwd</code> <kbd>stepfwd</kbd><dd>As for stepback, but for the forward direction. 2658<br><dt><code>stepout</code> <kbd>stepout</kbd><dd>The argument is the stepout timeout, which by default is 900 s. 2659It can 2660be set to any positive number in seconds. 2661If set to zero, the stepout 2662pulses will not be suppressed. 2663</dl> 2664 <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> 2665 <dl> 2666<dt><code>memlock</code> <kbd>Nmegabytes</kbd><dd>Specify the number of megabytes of memory that should be 2667allocated and locked. 2668Probably only available under Linux, this option may be useful 2669when dropping root (the 2670<code>-i</code> 2671option). 2672The default is 32 megabytes on non-Linux machines, and -1 under Linux. 2673-1 means "do not lock the process into memory". 26740 means "lock whatever memory the process wants into memory". 2675<br><dt><code>stacksize</code> <kbd>N4kPages</kbd><dd>Specifies the maximum size of the process stack on systems with the 2676<code>mlockall()</code> 2677function. 2678Defaults to 50 4k pages (200 4k pages in OpenBSD). 2679<br><dt><code>filenum</code> <kbd>Nfiledescriptors</kbd><dd>Specifies the maximum number of file descriptors ntpd may have open at once. 2680Defaults to the system default. 2681</dl> 2682 <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 2683address and port number for sending messages with the specified 2684local interface address. 2685If the port number is unspecified, a value 2686of 18447 is used. 2687If the interface address is not specified, the 2688message is sent with a source address of the local interface the 2689message is sent through. 2690Note that on a multihomed host the 2691interface used may vary from time to time with routing changes. 2692 2693 <p>The trap receiver will generally log event messages and other 2694information from the server in a log file. 2695While such monitor 2696programs may also request their own trap dynamically, configuring a 2697trap receiver will ensure that no messages are lost when the server 2698is started. 2699<br><dt><code>hop</code> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order, up to 8 2700values can be specified. 2701In manycast mode these values are used in turn in 2702an expanding-ring search. 2703The default is eight multiples of 32 starting at 270431. 2705</dl> 2706 2707 <p>This section was generated by <strong>AutoGen</strong>, 2708using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program. 2709This software is released under the NTP license, <http://ntp.org/license>. 2710 2711<ul class="menu"> 2712<li><a accesskey="1" href="#ntp_002econf-Files">ntp.conf Files</a>: Files 2713<li><a accesskey="2" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also 2714<li><a accesskey="3" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs 2715<li><a accesskey="4" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes 2716</ul> 2717 2718<div class="node"> 2719<p><hr> 2720<a name="ntp_002econf-Files"></a> 2721<br> 2722</div> 2723 2724<h4 class="subsection">ntp.conf Files</h4> 2725 2726 <dl> 2727<dt><span class="file">/etc/ntp.conf</span><dd>the default name of the configuration file 2728<br><dt><span class="file">ntp.keys</span><dd>private MD5 keys 2729<br><dt><span class="file">ntpkey</span><dd>RSA private key 2730<br><dt><span class="file">ntpkey_</span><kbd>host</kbd><dd>RSA public key 2731<br><dt><span class="file">ntp_dh</span><dd>Diffie-Hellman agreement parameters 2732</dl> 2733<div class="node"> 2734<p><hr> 2735<a name="ntp_002econf-See-Also"></a> 2736<br> 2737</div> 2738 2739<h4 class="subsection">ntp.conf See Also</h4> 2740 2741<p><code>ntpd(1ntpdmdoc)</code>, 2742<code>ntpdc(1ntpdcmdoc)</code>, 2743<code>ntpq(1ntpqmdoc)</code> 2744 2745 <p>In addition to the manual pages provided, 2746comprehensive documentation is available on the world wide web 2747at 2748<code>http://www.ntp.org/</code>. 2749A snapshot of this documentation is available in HTML format in 2750<span class="file">/usr/share/doc/ntp</span>. 2751<br> 2752 2753 <p><br> 2754David L. Mills, <em>Network Time Protocol (Version 4)</em>, RFC5905 2755<div class="node"> 2756<p><hr> 2757<a name="ntp_002econf-Bugs"></a> 2758<br> 2759</div> 2760 2761<h4 class="subsection">ntp.conf Bugs</h4> 2762 2763<p>The syntax checking is not picky; some combinations of 2764ridiculous and even hilarious options and modes may not be 2765detected. 2766 2767 <p>The 2768<span class="file">ntpkey_</span><kbd>host</kbd> 2769files are really digital 2770certificates. 2771These should be obtained via secure directory 2772services when they become universally available. 2773<div class="node"> 2774<p><hr> 2775<a name="ntp_002econf-Notes"></a> 2776<br> 2777</div> 2778 2779<h4 class="subsection">ntp.conf Notes</h4> 2780 2781<p>This document was derived from FreeBSD. 2782 2783</body></html> 2784 2785