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.8p11 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>[ippeerlimit </code><kbd>int</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. 1493The 1494<code>ippeerlimit</code> 1495directive limits the number of peer requests for each IP to 1496<kbd>int</kbd>, 1497where a value of -1 means "unlimited", the current default. 1498A value of 0 means "none". 1499There would usually be at most 1 peering request per IP, 1500but if the remote peering requests are behind a proxy 1501there could well be more than 1 per IP. 1502In the current implementation, 1503<code>flag</code> 1504always 1505restricts access, i.e., an entry with no flags indicates that free 1506access to the server is to be given. 1507The flags are not orthogonal, 1508in that more restrictive flags will often make less restrictive 1509ones redundant. 1510The flags can generally be classed into two 1511categories, those which restrict time service and those which 1512restrict informational queries and attempts to do run-time 1513reconfiguration of the server. 1514One or more of the following flags 1515may be specified: 1516 <dl> 1517<dt><code>ignore</code><dd>Deny packets of all kinds, including 1518<code>ntpq(1ntpqmdoc)</code> 1519and 1520<code>ntpdc(1ntpdcmdoc)</code> 1521queries. 1522<br><dt><code>kod</code><dd>If this flag is set when an access violation occurs, a kiss-o'-death 1523(KoD) packet is sent. 1524KoD packets are rate limited to no more than one 1525per second. 1526If another KoD packet occurs within one second after the 1527last one, the packet is dropped. 1528<br><dt><code>limited</code><dd>Deny service if the packet spacing violates the lower limits specified 1529in the 1530<code>discard</code> 1531command. 1532A history of clients is kept using the 1533monitoring capability of 1534<code>ntpd(1ntpdmdoc)</code>. 1535Thus, monitoring is always active as 1536long as there is a restriction entry with the 1537<code>limited</code> 1538flag. 1539<br><dt><code>lowpriotrap</code><dd>Declare traps set by matching hosts to be low priority. 1540The 1541number of traps a server can maintain is limited (the current limit 1542is 3). 1543Traps are usually assigned on a first come, first served 1544basis, with later trap requestors being denied service. 1545This flag 1546modifies the assignment algorithm by allowing low priority traps to 1547be overridden by later requests for normal priority traps. 1548<br><dt><code>noepeer</code><dd>Deny ephemeral peer requests, 1549even if they come from an authenticated source. 1550Note that the ability to use a symmetric key for authentication may be restricted to 1551one or more IPs or subnets via the third field of the 1552<span class="file">ntp.keys</span> 1553file. 1554This restriction is not enabled by default, 1555to maintain backward compatability. 1556Expect 1557<code>noepeer</code> 1558to become the default in ntp-4.4. 1559<br><dt><code>nomodify</code><dd>Deny 1560<code>ntpq(1ntpqmdoc)</code> 1561and 1562<code>ntpdc(1ntpdcmdoc)</code> 1563queries which attempt to modify the state of the 1564server (i.e., run time reconfiguration). 1565Queries which return 1566information are permitted. 1567<br><dt><code>noquery</code><dd>Deny 1568<code>ntpq(1ntpqmdoc)</code> 1569and 1570<code>ntpdc(1ntpdcmdoc)</code> 1571queries. 1572Time service is not affected. 1573<br><dt><code>nopeer</code><dd>Deny unauthenticated packets which would result in mobilizing a new association. 1574This includes 1575broadcast and symmetric active packets 1576when a configured association does not exist. 1577It also includes 1578<code>pool</code> 1579associations, so if you want to use servers from a 1580<code>pool</code> 1581directive and also want to use 1582<code>nopeer</code> 1583by default, you'll want a 1584<code>restrict source ...</code> 1585line as well that does 1586<em>not</em> 1587include the 1588<code>nopeer</code> 1589directive. 1590<br><dt><code>noserve</code><dd>Deny all packets except 1591<code>ntpq(1ntpqmdoc)</code> 1592and 1593<code>ntpdc(1ntpdcmdoc)</code> 1594queries. 1595<br><dt><code>notrap</code><dd>Decline to provide mode 6 control message trap service to matching 1596hosts. 1597The trap service is a subsystem of the 1598<code>ntpq(1ntpqmdoc)</code> 1599control message 1600protocol which is intended for use by remote event logging programs. 1601<br><dt><code>notrust</code><dd>Deny service unless the packet is cryptographically authenticated. 1602<br><dt><code>ntpport</code><dd>This is actually a match algorithm modifier, rather than a 1603restriction flag. 1604Its presence causes the restriction entry to be 1605matched only if the source port in the packet is the standard NTP 1606UDP port (123). 1607Both 1608<code>ntpport</code> 1609and 1610<code>non-ntpport</code> 1611may 1612be specified. 1613The 1614<code>ntpport</code> 1615is considered more specific and 1616is sorted later in the list. 1617<br><dt><code>version</code><dd>Deny packets that do not match the current NTP version. 1618</dl> 1619 1620 <p>Default restriction list entries with the flags ignore, interface, 1621ntpport, for each of the local host's interface addresses are 1622inserted into the table at startup to prevent the server 1623from attempting to synchronize to its own time. 1624A default entry is also always present, though if it is 1625otherwise unconfigured; no flags are associated 1626with the default entry (i.e., everything besides your own 1627NTP server is unrestricted). 1628</dl> 1629<div class="node"> 1630<p><hr> 1631<a name="Automatic-NTP-Configuration-Options"></a> 1632<br> 1633</div> 1634 1635<h4 class="subsection">Automatic NTP Configuration Options</h4> 1636 1637<h5 class="subsubsection">Manycasting</h5> 1638 1639<p>Manycasting is a automatic discovery and configuration paradigm 1640new to NTPv4. 1641It is intended as a means for a multicast client 1642to troll the nearby network neighborhood to find cooperating 1643manycast servers, validate them using cryptographic means 1644and evaluate their time values with respect to other servers 1645that might be lurking in the vicinity. 1646The intended result is that each manycast client mobilizes 1647client associations with some number of the "best" 1648of the nearby manycast servers, yet automatically reconfigures 1649to sustain this number of servers should one or another fail. 1650 1651 <p>Note that the manycasting paradigm does not coincide 1652with the anycast paradigm described in RFC-1546, 1653which is designed to find a single server from a clique 1654of servers providing the same service. 1655The manycast paradigm is designed to find a plurality 1656of redundant servers satisfying defined optimality criteria. 1657 1658 <p>Manycasting can be used with either symmetric key 1659or public key cryptography. 1660The public key infrastructure (PKI) 1661offers the best protection against compromised keys 1662and is generally considered stronger, at least with relatively 1663large key sizes. 1664It is implemented using the Autokey protocol and 1665the OpenSSL cryptographic library available from 1666<code>http://www.openssl.org/</code>. 1667The library can also be used with other NTPv4 modes 1668as well and is highly recommended, especially for broadcast modes. 1669 1670 <p>A persistent manycast client association is configured 1671using the 1672<code>manycastclient</code> 1673command, which is similar to the 1674<code>server</code> 1675command but with a multicast (IPv4 class 1676<code>D</code> 1677or IPv6 prefix 1678<code>FF</code>) 1679group address. 1680The IANA has designated IPv4 address 224.1.1.1 1681and IPv6 address FF05::101 (site local) for NTP. 1682When more servers are needed, it broadcasts manycast 1683client messages to this address at the minimum feasible rate 1684and minimum feasible time-to-live (TTL) hops, depending 1685on how many servers have already been found. 1686There can be as many manycast client associations 1687as different group address, each one serving as a template 1688for a future ephemeral unicast client/server association. 1689 1690 <p>Manycast servers configured with the 1691<code>manycastserver</code> 1692command listen on the specified group address for manycast 1693client messages. 1694Note the distinction between manycast client, 1695which actively broadcasts messages, and manycast server, 1696which passively responds to them. 1697If a manycast server is 1698in scope of the current TTL and is itself synchronized 1699to a valid source and operating at a stratum level equal 1700to or lower than the manycast client, it replies to the 1701manycast client message with an ordinary unicast server message. 1702 1703 <p>The manycast client receiving this message mobilizes 1704an ephemeral client/server association according to the 1705matching manycast client template, but only if cryptographically 1706authenticated and the server stratum is less than or equal 1707to the client stratum. 1708Authentication is explicitly required 1709and either symmetric key or public key (Autokey) can be used. 1710Then, the client polls the server at its unicast address 1711in burst mode in order to reliably set the host clock 1712and validate the source. 1713This normally results 1714in a volley of eight client/server at 2-s intervals 1715during which both the synchronization and cryptographic 1716protocols run concurrently. 1717Following the volley, 1718the client runs the NTP intersection and clustering 1719algorithms, which act to discard all but the "best" 1720associations according to stratum and synchronization 1721distance. 1722The surviving associations then continue 1723in ordinary client/server mode. 1724 1725 <p>The manycast client polling strategy is designed to reduce 1726as much as possible the volume of manycast client messages 1727and the effects of implosion due to near-simultaneous 1728arrival of manycast server messages. 1729The strategy is determined by the 1730<code>manycastclient</code>, 1731<code>tos</code> 1732and 1733<code>ttl</code> 1734configuration commands. 1735The manycast poll interval is 1736normally eight times the system poll interval, 1737which starts out at the 1738<code>minpoll</code> 1739value specified in the 1740<code>manycastclient</code>, 1741command and, under normal circumstances, increments to the 1742<code>maxpolll</code> 1743value specified in this command. 1744Initially, the TTL is 1745set at the minimum hops specified by the 1746<code>ttl</code> 1747command. 1748At each retransmission the TTL is increased until reaching 1749the maximum hops specified by this command or a sufficient 1750number client associations have been found. 1751Further retransmissions use the same TTL. 1752 1753 <p>The quality and reliability of the suite of associations 1754discovered by the manycast client is determined by the NTP 1755mitigation algorithms and the 1756<code>minclock</code> 1757and 1758<code>minsane</code> 1759values specified in the 1760<code>tos</code> 1761configuration command. 1762At least 1763<code>minsane</code> 1764candidate servers must be available and the mitigation 1765algorithms produce at least 1766<code>minclock</code> 1767survivors in order to synchronize the clock. 1768Byzantine agreement principles require at least four 1769candidates in order to correctly discard a single falseticker. 1770For legacy purposes, 1771<code>minsane</code> 1772defaults to 1 and 1773<code>minclock</code> 1774defaults to 3. 1775For manycast service 1776<code>minsane</code> 1777should be explicitly set to 4, assuming at least that 1778number of servers are available. 1779 1780 <p>If at least 1781<code>minclock</code> 1782servers are found, the manycast poll interval is immediately 1783set to eight times 1784<code>maxpoll</code>. 1785If less than 1786<code>minclock</code> 1787servers are found when the TTL has reached the maximum hops, 1788the manycast poll interval is doubled. 1789For each transmission 1790after that, the poll interval is doubled again until 1791reaching the maximum of eight times 1792<code>maxpoll</code>. 1793Further transmissions use the same poll interval and 1794TTL values. 1795Note that while all this is going on, 1796each client/server association found is operating normally 1797it the system poll interval. 1798 1799 <p>Administratively scoped multicast boundaries are normally 1800specified by the network router configuration and, 1801in the case of IPv6, the link/site scope prefix. 1802By default, the increment for TTL hops is 32 starting 1803from 31; however, the 1804<code>ttl</code> 1805configuration command can be 1806used to modify the values to match the scope rules. 1807 1808 <p>It is often useful to narrow the range of acceptable 1809servers which can be found by manycast client associations. 1810Because manycast servers respond only when the client 1811stratum is equal to or greater than the server stratum, 1812primary (stratum 1) servers fill find only primary servers 1813in TTL range, which is probably the most common objective. 1814However, unless configured otherwise, all manycast clients 1815in TTL range will eventually find all primary servers 1816in TTL range, which is probably not the most common 1817objective in large networks. 1818The 1819<code>tos</code> 1820command can be used to modify this behavior. 1821Servers with stratum below 1822<code>floor</code> 1823or above 1824<code>ceiling</code> 1825specified in the 1826<code>tos</code> 1827command are strongly discouraged during the selection 1828process; however, these servers may be temporally 1829accepted if the number of servers within TTL range is 1830less than 1831<code>minclock</code>. 1832 1833 <p>The above actions occur for each manycast client message, 1834which repeats at the designated poll interval. 1835However, once the ephemeral client association is mobilized, 1836subsequent manycast server replies are discarded, 1837since that would result in a duplicate association. 1838If during a poll interval the number of client associations 1839falls below 1840<code>minclock</code>, 1841all manycast client prototype associations are reset 1842to the initial poll interval and TTL hops and operation 1843resumes from the beginning. 1844It is important to avoid 1845frequent manycast client messages, since each one requires 1846all manycast servers in TTL range to respond. 1847The result could well be an implosion, either minor or major, 1848depending on the number of servers in range. 1849The recommended value for 1850<code>maxpoll</code> 1851is 12 (4,096 s). 1852 1853 <p>It is possible and frequently useful to configure a host 1854as both manycast client and manycast server. 1855A number of hosts configured this way and sharing a common 1856group address will automatically organize themselves 1857in an optimum configuration based on stratum and 1858synchronization distance. 1859For example, consider an NTP 1860subnet of two primary servers and a hundred or more 1861dependent clients. 1862With two exceptions, all servers 1863and clients have identical configuration files including both 1864<code>multicastclient</code> 1865and 1866<code>multicastserver</code> 1867commands using, for instance, multicast group address 1868239.1.1.1. 1869The only exception is that each primary server 1870configuration file must include commands for the primary 1871reference source such as a GPS receiver. 1872 1873 <p>The remaining configuration files for all secondary 1874servers and clients have the same contents, except for the 1875<code>tos</code> 1876command, which is specific for each stratum level. 1877For stratum 1 and stratum 2 servers, that command is 1878not necessary. 1879For stratum 3 and above servers the 1880<code>floor</code> 1881value is set to the intended stratum number. 1882Thus, all stratum 3 configuration files are identical, 1883all stratum 4 files are identical and so forth. 1884 1885 <p>Once operations have stabilized in this scenario, 1886the primary servers will find the primary reference source 1887and each other, since they both operate at the same 1888stratum (1), but not with any secondary server or client, 1889since these operate at a higher stratum. 1890The secondary 1891servers will find the servers at the same stratum level. 1892If one of the primary servers loses its GPS receiver, 1893it will continue to operate as a client and other clients 1894will time out the corresponding association and 1895re-associate accordingly. 1896 1897 <p>Some administrators prefer to avoid running 1898<code>ntpd(1ntpdmdoc)</code> 1899continuously and run either 1900<code>sntp(1sntpmdoc)</code> 1901or 1902<code>ntpd(1ntpdmdoc)</code> 1903<code>-q</code> 1904as a cron job. 1905In either case the servers must be 1906configured in advance and the program fails if none are 1907available when the cron job runs. 1908A really slick 1909application of manycast is with 1910<code>ntpd(1ntpdmdoc)</code> 1911<code>-q</code>. 1912The program wakes up, scans the local landscape looking 1913for the usual suspects, selects the best from among 1914the rascals, sets the clock and then departs. 1915Servers do not have to be configured in advance and 1916all clients throughout the network can have the same 1917configuration file. 1918 1919<h5 class="subsubsection">Manycast Interactions with Autokey</h5> 1920 1921<p>Each time a manycast client sends a client mode packet 1922to a multicast group address, all manycast servers 1923in scope generate a reply including the host name 1924and status word. 1925The manycast clients then run 1926the Autokey protocol, which collects and verifies 1927all certificates involved. 1928Following the burst interval 1929all but three survivors are cast off, 1930but the certificates remain in the local cache. 1931It often happens that several complete signing trails 1932from the client to the primary servers are collected in this way. 1933 1934 <p>About once an hour or less often if the poll interval 1935exceeds this, the client regenerates the Autokey key list. 1936This is in general transparent in client/server mode. 1937However, about once per day the server private value 1938used to generate cookies is refreshed along with all 1939manycast client associations. 1940In this case all 1941cryptographic values including certificates is refreshed. 1942If a new certificate has been generated since 1943the last refresh epoch, it will automatically revoke 1944all prior certificates that happen to be in the 1945certificate cache. 1946At the same time, the manycast 1947scheme starts all over from the beginning and 1948the expanding ring shrinks to the minimum and increments 1949from there while collecting all servers in scope. 1950 1951<h5 class="subsubsection">Broadcast Options</h5> 1952 1953 <dl> 1954<dt><code>tos</code> <code>[bcpollbstep </code><kbd>gate</kbd><code>]</code><dd>This command provides a way to delay, 1955by the specified number of broadcast poll intervals, 1956believing backward time steps from a broadcast server. 1957Broadcast time networks are expected to be trusted. 1958In the event a broadcast server's time is stepped backwards, 1959there is clear benefit to having the clients notice this change 1960as soon as possible. 1961Attacks such as replay attacks can happen, however, 1962and even though there are a number of protections built in to 1963broadcast mode, attempts to perform a replay attack are possible. 1964This value defaults to 0, but can be changed 1965to any number of poll intervals between 0 and 4. 1966</dl> 1967 1968<h5 class="subsubsection">Manycast Options</h5> 1969 1970 <dl> 1971<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 1972algorithms. 1973It can be used to select the quality and 1974quantity of peers used to synchronize the system clock 1975and is most useful in manycast mode. 1976The variables operate 1977as follows: 1978 <dl> 1979<dt><code>ceiling</code> <kbd>ceiling</kbd><dd>Peers with strata above 1980<code>ceiling</code> 1981will be discarded if there are at least 1982<code>minclock</code> 1983peers remaining. 1984This value defaults to 15, but can be changed 1985to any number from 1 to 15. 1986<br><dt><code>cohort</code> <code>{0 | 1}</code><dd>This is a binary flag which enables (0) or disables (1) 1987manycast server replies to manycast clients with the same 1988stratum level. 1989This is useful to reduce implosions where 1990large numbers of clients with the same stratum level 1991are present. 1992The default is to enable these replies. 1993<br><dt><code>floor</code> <kbd>floor</kbd><dd>Peers with strata below 1994<code>floor</code> 1995will be discarded if there are at least 1996<code>minclock</code> 1997peers remaining. 1998This value defaults to 1, but can be changed 1999to any number from 1 to 15. 2000<br><dt><code>minclock</code> <kbd>minclock</kbd><dd>The clustering algorithm repeatedly casts out outlier 2001associations until no more than 2002<code>minclock</code> 2003associations remain. 2004This value defaults to 3, 2005but can be changed to any number from 1 to the number of 2006configured sources. 2007<br><dt><code>minsane</code> <kbd>minsane</kbd><dd>This is the minimum number of candidates available 2008to the clock selection algorithm in order to produce 2009one or more truechimers for the clustering algorithm. 2010If fewer than this number are available, the clock is 2011undisciplined and allowed to run free. 2012The default is 1 2013for legacy purposes. 2014However, according to principles of 2015Byzantine agreement, 2016<code>minsane</code> 2017should be at least 4 in order to detect and discard 2018a single falseticker. 2019</dl> 2020 <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing 2021order, up to 8 values can be specified. 2022In manycast mode these values are used in turn 2023in an expanding-ring search. 2024The default is eight 2025multiples of 32 starting at 31. 2026</dl> 2027<div class="node"> 2028<p><hr> 2029<a name="Reference-Clock-Support"></a> 2030<br> 2031</div> 2032 2033<h4 class="subsection">Reference Clock Support</h4> 2034 2035<p>The NTP Version 4 daemon supports some three dozen different radio, 2036satellite and modem reference clocks plus a special pseudo-clock 2037used for backup or when no other clock source is available. 2038Detailed descriptions of individual device drivers and options can 2039be found in the 2040"Reference Clock Drivers" 2041page 2042(available as part of the HTML documentation 2043provided in 2044<span class="file">/usr/share/doc/ntp</span>). 2045Additional information can be found in the pages linked 2046there, including the 2047"Debugging Hints for Reference Clock Drivers" 2048and 2049"How To Write a Reference Clock Driver" 2050pages 2051(available as part of the HTML documentation 2052provided in 2053<span class="file">/usr/share/doc/ntp</span>). 2054In addition, support for a PPS 2055signal is available as described in the 2056"Pulse-per-second (PPS) Signal Interfacing" 2057page 2058(available as part of the HTML documentation 2059provided in 2060<span class="file">/usr/share/doc/ntp</span>). 2061Many 2062drivers support special line discipline/streams modules which can 2063significantly improve the accuracy using the driver. 2064These are 2065described in the 2066"Line Disciplines and Streams Drivers" 2067page 2068(available as part of the HTML documentation 2069provided in 2070<span class="file">/usr/share/doc/ntp</span>). 2071 2072 <p>A reference clock will generally (though not always) be a radio 2073timecode receiver which is synchronized to a source of standard 2074time such as the services offered by the NRC in Canada and NIST and 2075USNO in the US. 2076The interface between the computer and the timecode 2077receiver is device dependent, but is usually a serial port. 2078A 2079device driver specific to each reference clock must be selected and 2080compiled in the distribution; however, most common radio, satellite 2081and modem clocks are included by default. 2082Note that an attempt to 2083configure a reference clock when the driver has not been compiled 2084or the hardware port has not been appropriately configured results 2085in a scalding remark to the system log file, but is otherwise non 2086hazardous. 2087 2088 <p>For the purposes of configuration, 2089<code>ntpd(1ntpdmdoc)</code> 2090treats 2091reference clocks in a manner analogous to normal NTP peers as much 2092as possible. 2093Reference clocks are identified by a syntactically 2094correct but invalid IP address, in order to distinguish them from 2095normal NTP peers. 2096Reference clock addresses are of the form 2097<code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd>, 2098where 2099<kbd>t</kbd> 2100is an integer 2101denoting the clock type and 2102<kbd>u</kbd> 2103indicates the unit 2104number in the range 0-3. 2105While it may seem overkill, it is in fact 2106sometimes useful to configure multiple reference clocks of the same 2107type, in which case the unit numbers must be unique. 2108 2109 <p>The 2110<code>server</code> 2111command is used to configure a reference 2112clock, where the 2113<kbd>address</kbd> 2114argument in that command 2115is the clock address. 2116The 2117<code>key</code>, 2118<code>version</code> 2119and 2120<code>ttl</code> 2121options are not used for reference clock support. 2122The 2123<code>mode</code> 2124option is added for reference clock support, as 2125described below. 2126The 2127<code>prefer</code> 2128option can be useful to 2129persuade the server to cherish a reference clock with somewhat more 2130enthusiasm than other reference clocks or peers. 2131Further 2132information on this option can be found in the 2133"Mitigation Rules and the prefer Keyword" 2134(available as part of the HTML documentation 2135provided in 2136<span class="file">/usr/share/doc/ntp</span>) 2137page. 2138The 2139<code>minpoll</code> 2140and 2141<code>maxpoll</code> 2142options have 2143meaning only for selected clock drivers. 2144See the individual clock 2145driver document pages for additional information. 2146 2147 <p>The 2148<code>fudge</code> 2149command is used to provide additional 2150information for individual clock drivers and normally follows 2151immediately after the 2152<code>server</code> 2153command. 2154The 2155<kbd>address</kbd> 2156argument specifies the clock address. 2157The 2158<code>refid</code> 2159and 2160<code>stratum</code> 2161options can be used to 2162override the defaults for the device. 2163There are two optional 2164device-dependent time offsets and four flags that can be included 2165in the 2166<code>fudge</code> 2167command as well. 2168 2169 <p>The stratum number of a reference clock is by default zero. 2170Since the 2171<code>ntpd(1ntpdmdoc)</code> 2172daemon adds one to the stratum of each 2173peer, a primary server ordinarily displays an external stratum of 2174one. 2175In order to provide engineered backups, it is often useful to 2176specify the reference clock stratum as greater than zero. 2177The 2178<code>stratum</code> 2179option is used for this purpose. 2180Also, in cases 2181involving both a reference clock and a pulse-per-second (PPS) 2182discipline signal, it is useful to specify the reference clock 2183identifier as other than the default, depending on the driver. 2184The 2185<code>refid</code> 2186option is used for this purpose. 2187Except where noted, 2188these options apply to all clock drivers. 2189 2190<h5 class="subsubsection">Reference Clock Commands</h5> 2191 2192 <dl> 2193<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 2194special ways. 2195The options are interpreted as follows: 2196 <dl> 2197<dt><code>prefer</code><dd>Marks the reference clock as preferred. 2198All other things being 2199equal, this host will be chosen for synchronization among a set of 2200correctly operating hosts. 2201See the 2202"Mitigation Rules and the prefer Keyword" 2203page 2204(available as part of the HTML documentation 2205provided in 2206<span class="file">/usr/share/doc/ntp</span>) 2207for further information. 2208<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 2209device-specific fashion. 2210For instance, it selects a dialing 2211protocol in the ACTS driver and a device subtype in the 2212parse 2213drivers. 2214<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 2215for reference clock messages, as a power of 2 in seconds 2216For 2217most directly connected reference clocks, both 2218<code>minpoll</code> 2219and 2220<code>maxpoll</code> 2221default to 6 (64 s). 2222For modem reference clocks, 2223<code>minpoll</code> 2224defaults to 10 (17.1 m) and 2225<code>maxpoll</code> 2226defaults to 14 (4.5 h). 2227The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2228</dl> 2229 <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 2230special ways. 2231It must immediately follow the 2232<code>server</code> 2233command which configures the driver. 2234Note that the same capability 2235is possible at run time using the 2236<code>ntpdc(1ntpdcmdoc)</code> 2237program. 2238The options are interpreted as 2239follows: 2240 <dl> 2241<dt><code>time1</code> <kbd>sec</kbd><dd>Specifies a constant to be added to the time offset produced by 2242the driver, a fixed-point decimal number in seconds. 2243This is used 2244as a calibration constant to adjust the nominal time offset of a 2245particular clock to agree with an external standard, such as a 2246precision PPS signal. 2247It also provides a way to correct a 2248systematic error or bias due to serial port or operating system 2249latencies, different cable lengths or receiver internal delay. 2250The 2251specified offset is in addition to the propagation delay provided 2252by other means, such as internal DIPswitches. 2253Where a calibration 2254for an individual system and driver is available, an approximate 2255correction is noted in the driver documentation pages. 2256Note: in order to facilitate calibration when more than one 2257radio clock or PPS signal is supported, a special calibration 2258feature is available. 2259It takes the form of an argument to the 2260<code>enable</code> 2261command described in 2262<a href="#Miscellaneous-Options">Miscellaneous Options</a> 2263page and operates as described in the 2264"Reference Clock Drivers" 2265page 2266(available as part of the HTML documentation 2267provided in 2268<span class="file">/usr/share/doc/ntp</span>). 2269<br><dt><code>time2</code> <kbd>secs</kbd><dd>Specifies a fixed-point decimal number in seconds, which is 2270interpreted in a driver-dependent way. 2271See the descriptions of 2272specific drivers in the 2273"Reference Clock Drivers" 2274page 2275(available as part of the HTML documentation 2276provided in 2277<span class="file">/usr/share/doc/ntp</span> <span class="file">).</span> 2278<br><dt><code>stratum</code> <kbd>int</kbd><dd>Specifies the stratum number assigned to the driver, an integer 2279between 0 and 15. 2280This number overrides the default stratum number 2281ordinarily assigned by the driver itself, usually zero. 2282<br><dt><code>refid</code> <kbd>string</kbd><dd>Specifies an ASCII string of from one to four characters which 2283defines the reference identifier used by the driver. 2284This string 2285overrides the default identifier ordinarily assigned by the driver 2286itself. 2287<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 2288device-specific fashion. 2289For instance, it selects a dialing 2290protocol in the ACTS driver and a device subtype in the 2291parse 2292drivers. 2293<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. 2294The 2295interpretation of these values, and whether they are used at all, 2296is a function of the particular clock driver. 2297However, by 2298convention 2299<code>flag4</code> 2300is used to enable recording monitoring 2301data to the 2302<code>clockstats</code> 2303file configured with the 2304<code>filegen</code> 2305command. 2306Further information on the 2307<code>filegen</code> 2308command can be found in 2309<a href="#Monitoring-Options">Monitoring Options</a>. 2310</dl> 2311 </dl> 2312<div class="node"> 2313<p><hr> 2314<a name="Miscellaneous-Options"></a> 2315<br> 2316</div> 2317 2318<h4 class="subsection">Miscellaneous Options</h4> 2319 2320 <dl> 2321<dt><code>broadcastdelay</code> <kbd>seconds</kbd><dd>The broadcast and multicast modes require a special calibration 2322to determine the network delay between the local and remote 2323servers. 2324Ordinarily, this is done automatically by the initial 2325protocol exchanges between the client and server. 2326In some cases, 2327the calibration procedure may fail due to network or server access 2328controls, for example. 2329This command specifies the default delay to 2330be used under these circumstances. 2331Typically (for Ethernet), a 2332number between 0.003 and 0.007 seconds is appropriate. 2333The default 2334when this command is not used is 0.004 seconds. 2335<br><dt><code>calldelay</code> <kbd>delay</kbd><dd>This option controls the delay in seconds between the first and second 2336packets sent in burst or iburst mode to allow additional time for a modem 2337or ISDN call to complete. 2338<br><dt><code>driftfile</code> <kbd>driftfile</kbd><dd>This command specifies the complete path and name of the file used to 2339record the frequency of the local clock oscillator. 2340This is the same 2341operation as the 2342<code>-f</code> 2343command line option. 2344If the file exists, it is read at 2345startup in order to set the initial frequency and then updated once per 2346hour with the current frequency computed by the daemon. 2347If the file name is 2348specified, but the file itself does not exist, the starts with an initial 2349frequency of zero and creates the file when writing it for the first time. 2350If this command is not given, the daemon will always start with an initial 2351frequency of zero. 2352 2353 <p>The file format consists of a single line containing a single 2354floating point number, which records the frequency offset measured 2355in parts-per-million (PPM). 2356The file is updated by first writing 2357the current drift value into a temporary file and then renaming 2358this file to replace the old version. 2359This implies that 2360<code>ntpd(1ntpdmdoc)</code> 2361must have write permission for the directory the 2362drift file is located in, and that file system links, symbolic or 2363otherwise, should be avoided. 2364<br><dt><code>dscp</code> <kbd>value</kbd><dd>This option specifies the Differentiated Services Control Point (DSCP) value, 2365a 6-bit code. 2366The default value is 46, signifying Expedited Forwarding. 2367<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. 2368Flags not mentioned are unaffected. 2369Note that all of these flags 2370can be controlled remotely using the 2371<code>ntpdc(1ntpdcmdoc)</code> 2372utility program. 2373 <dl> 2374<dt><code>auth</code><dd>Enables the server to synchronize with unconfigured peers only if the 2375peer has been correctly authenticated using either public key or 2376private key cryptography. 2377The default for this flag is 2378<code>enable</code>. 2379<br><dt><code>bclient</code><dd>Enables the server to listen for a message from a broadcast or 2380multicast server, as in the 2381<code>multicastclient</code> 2382command with default 2383address. 2384The default for this flag is 2385<code>disable</code>. 2386<br><dt><code>calibrate</code><dd>Enables the calibrate feature for reference clocks. 2387The default for 2388this flag is 2389<code>disable</code>. 2390<br><dt><code>kernel</code><dd>Enables the kernel time discipline, if available. 2391The default for this 2392flag is 2393<code>enable</code> 2394if support is available, otherwise 2395<code>disable</code>. 2396<br><dt><code>mode7</code><dd>Enables processing of NTP mode 7 implementation-specific requests 2397which are used by the deprecated 2398<code>ntpdc(1ntpdcmdoc)</code> 2399program. 2400The default for this flag is disable. 2401This flag is excluded from runtime configuration using 2402<code>ntpq(1ntpqmdoc)</code>. 2403The 2404<code>ntpq(1ntpqmdoc)</code> 2405program provides the same capabilities as 2406<code>ntpdc(1ntpdcmdoc)</code> 2407using standard mode 6 requests. 2408<br><dt><code>monitor</code><dd>Enables the monitoring facility. 2409See the 2410<code>ntpdc(1ntpdcmdoc)</code> 2411program 2412and the 2413<code>monlist</code> 2414command or further information. 2415The 2416default for this flag is 2417<code>enable</code>. 2418<br><dt><code>ntp</code><dd>Enables time and frequency discipline. 2419In effect, this switch opens and 2420closes the feedback loop, which is useful for testing. 2421The default for 2422this flag is 2423<code>enable</code>. 2424<br><dt><code>peer_clear_digest_early</code><dd>By default, if 2425<code>ntpd(1ntpdmdoc)</code> 2426is using autokey and it 2427receives a crypto-NAK packet that 2428passes the duplicate packet and origin timestamp checks 2429the peer variables are immediately cleared. 2430While this is generally a feature 2431as it allows for quick recovery if a server key has changed, 2432a properly forged and appropriately delivered crypto-NAK packet 2433can be used in a DoS attack. 2434If you have active noticable problems with this type of DoS attack 2435then you should consider 2436disabling this option. 2437You can check your 2438<code>peerstats</code> 2439file for evidence of any of these attacks. 2440The 2441default for this flag is 2442<code>enable</code>. 2443<br><dt><code>stats</code><dd>Enables the statistics facility. 2444See the 2445<a href="#Monitoring-Options">Monitoring Options</a> 2446section for further information. 2447The default for this flag is 2448<code>disable</code>. 2449<br><dt><code>unpeer_crypto_early</code><dd>By default, if 2450<code>ntpd(1ntpdmdoc)</code> 2451receives an autokey packet that fails TEST9, 2452a crypto failure, 2453the association is immediately cleared. 2454This is almost certainly a feature, 2455but if, in spite of the current recommendation of not using autokey, 2456you are 2457.B still 2458using autokey 2459.B and 2460you are seeing this sort of DoS attack 2461disabling this flag will delay 2462tearing down the association until the reachability counter 2463becomes zero. 2464You can check your 2465<code>peerstats</code> 2466file for evidence of any of these attacks. 2467The 2468default for this flag is 2469<code>enable</code>. 2470<br><dt><code>unpeer_crypto_nak_early</code><dd>By default, if 2471<code>ntpd(1ntpdmdoc)</code> 2472receives a crypto-NAK packet that 2473passes the duplicate packet and origin timestamp checks 2474the association is immediately cleared. 2475While this is generally a feature 2476as it allows for quick recovery if a server key has changed, 2477a properly forged and appropriately delivered crypto-NAK packet 2478can be used in a DoS attack. 2479If you have active noticable problems with this type of DoS attack 2480then you should consider 2481disabling this option. 2482You can check your 2483<code>peerstats</code> 2484file for evidence of any of these attacks. 2485The 2486default for this flag is 2487<code>enable</code>. 2488<br><dt><code>unpeer_digest_early</code><dd>By default, if 2489<code>ntpd(1ntpdmdoc)</code> 2490receives what should be an authenticated packet 2491that passes other packet sanity checks but 2492contains an invalid digest 2493the association is immediately cleared. 2494While this is generally a feature 2495as it allows for quick recovery, 2496if this type of packet is carefully forged and sent 2497during an appropriate window it can be used for a DoS attack. 2498If you have active noticable problems with this type of DoS attack 2499then you should consider 2500disabling this option. 2501You can check your 2502<code>peerstats</code> 2503file for evidence of any of these attacks. 2504The 2505default for this flag is 2506<code>enable</code>. 2507</dl> 2508 <br><dt><code>includefile</code> <kbd>includefile</kbd><dd>This command allows additional configuration commands 2509to be included from a separate file. 2510Include files may 2511be nested to a depth of five; upon reaching the end of any 2512include file, command processing resumes in the previous 2513configuration file. 2514This option is useful for sites that run 2515<code>ntpd(1ntpdmdoc)</code> 2516on multiple hosts, with (mostly) common options (e.g., a 2517restriction list). 2518<br><dt><code>interface</code> <code>[listen | ignore | drop]</code> <code>[all | ipv4 | ipv6 | wildcard </code><kbd>name</kbd><code> | </code><kbd>address</kbd><code> [/ </code><kbd>prefixlen</kbd><code>]]</code><dd>The 2519<code>interface</code> 2520directive controls which network addresses 2521<code>ntpd(1ntpdmdoc)</code> 2522opens, and whether input is dropped without processing. 2523The first parameter determines the action for addresses 2524which match the second parameter. 2525The second parameter specifies a class of addresses, 2526or a specific interface name, 2527or an address. 2528In the address case, 2529<kbd>prefixlen</kbd> 2530determines how many bits must match for this rule to apply. 2531<code>ignore</code> 2532prevents opening matching addresses, 2533<code>drop</code> 2534causes 2535<code>ntpd(1ntpdmdoc)</code> 2536to open the address and drop all received packets without examination. 2537Multiple 2538<code>interface</code> 2539directives can be used. 2540The last rule which matches a particular address determines the action for it. 2541<code>interface</code> 2542directives are disabled if any 2543<code>-I</code>, 2544<code>--interface</code>, 2545<code>-L</code>, 2546or 2547<code>--novirtualips</code> 2548command-line options are specified in the configuration file, 2549all available network addresses are opened. 2550The 2551<code>nic</code> 2552directive is an alias for 2553<code>interface</code>. 2554<br><dt><code>leapfile</code> <kbd>leapfile</kbd><dd>This command loads the IERS leapseconds file and initializes the 2555leapsecond values for the next leapsecond event, leapfile expiration 2556time, and TAI offset. 2557The file can be obtained directly from the IERS at 2558<code>https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</code> 2559or 2560<code>ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</code>. 2561The 2562<code>leapfile</code> 2563is scanned when 2564<code>ntpd(1ntpdmdoc)</code> 2565processes the 2566<code>leapfile</code> <code>directive</code> <code>or</code> <code>when</code> 2567<code>ntpd</code> <code>detects</code> <code>that</code> <code>the</code> 2568<kbd>leapfile</kbd> 2569has changed. 2570<code>ntpd</code> 2571checks once a day to see if the 2572<kbd>leapfile</kbd> 2573has changed. 2574The 2575<code>update-leap(1update_leapmdoc)</code> 2576script can be run to see if the 2577<kbd>leapfile</kbd> 2578should be updated. 2579<br><dt><code>leapsmearinterval</code> <kbd>seconds</kbd><dd>This EXPERIMENTAL option is only available if 2580<code>ntpd(1ntpdmdoc)</code> 2581was built with the 2582<code>--enable-leap-smear</code> 2583option to the 2584<code>configure</code> 2585script. 2586It specifies the interval over which a leap second correction will be applied. 2587Recommended values for this option are between 25887200 (2 hours) and 86400 (24 hours). 2589.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2590See http://bugs.ntp.org/2855 for more information. 2591<br><dt><code>logconfig</code> <kbd>configkeyword</kbd><dd>This command controls the amount and type of output written to 2592the system 2593<code>syslog(3)</code> 2594facility or the alternate 2595<code>logfile</code> 2596log file. 2597By default, all output is turned on. 2598All 2599<kbd>configkeyword</kbd> 2600keywords can be prefixed with 2601=, 2602+ 2603and 2604-, 2605where 2606= 2607sets the 2608<code>syslog(3)</code> 2609priority mask, 2610+ 2611adds and 2612- 2613removes 2614messages. 2615<code>syslog(3)</code> 2616messages can be controlled in four 2617classes 2618(<code>clock</code>, <code>peer</code>, <code>sys</code> and <code>sync</code>). 2619Within these classes four types of messages can be 2620controlled: informational messages 2621(<code>info</code>), 2622event messages 2623(<code>events</code>), 2624statistics messages 2625(<code>statistics</code>) 2626and 2627status messages 2628(<code>status</code>). 2629 2630 <p>Configuration keywords are formed by concatenating the message class with 2631the event class. 2632The 2633<code>all</code> 2634prefix can be used instead of a message class. 2635A 2636message class may also be followed by the 2637<code>all</code> 2638keyword to enable/disable all 2639messages of the respective message class. 2640Thus, a minimal log configuration 2641could look like this: 2642<pre class="verbatim"> 2643 logconfig =syncstatus +sysevents 2644</pre> 2645 2646 <p>This would just list the synchronizations state of 2647<code>ntpd(1ntpdmdoc)</code> 2648and the major system events. 2649For a simple reference server, the 2650following minimum message configuration could be useful: 2651<pre class="verbatim"> 2652 logconfig =syncall +clockall 2653</pre> 2654 2655 <p>This configuration will list all clock information and 2656synchronization information. 2657All other events and messages about 2658peers, system events and so on is suppressed. 2659<br><dt><code>logfile</code> <kbd>logfile</kbd><dd>This command specifies the location of an alternate log file to 2660be used instead of the default system 2661<code>syslog(3)</code> 2662facility. 2663This is the same operation as the 2664<code>-l</code> 2665command line option. 2666<br><dt><code>mru</code> <code>[maxdepth </code><kbd>count</kbd><code> | maxmem </code><kbd>kilobytes</kbd><code> | mindepth </code><kbd>count</kbd><code> | maxage </code><kbd>seconds</kbd><code> | initialloc </code><kbd>count</kbd><code> | initmem </code><kbd>kilobytes</kbd><code> | incalloc </code><kbd>count</kbd><code> | incmem </code><kbd>kilobytes</kbd><code>]</code><dd>Controls size limite of the monitoring facility's Most Recently Used 2667(MRU) list 2668of client addresses, which is also used by the 2669rate control facility. 2670 <dl> 2671<dt><code>maxdepth</code> <kbd>count</kbd><br><dt><code>maxmem</code> <kbd>kilobytes</kbd><dd>Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. 2672The acutal limit will be up to 2673<code>incalloc</code> 2674entries or 2675<code>incmem</code> 2676kilobytes larger. 2677As with all of the 2678<code>mru</code> 2679options offered in units of entries or kilobytes, if both 2680<code>maxdepth</code> 2681and 2682<code>maxmem</code> <code>are</code> <code>used,</code> <code>the</code> <code>last</code> <code>one</code> <code>used</code> <code>controls.</code> 2683The default is 1024 kilobytes. 2684<br><dt><code>mindepth</code> <kbd>count</kbd><dd>Lower limit on the MRU list size. 2685When the MRU list has fewer than 2686<code>mindepth</code> 2687entries, existing entries are never removed to make room for newer ones, 2688regardless of their age. 2689The default is 600 entries. 2690<br><dt><code>maxage</code> <kbd>seconds</kbd><dd>Once the MRU list has 2691<code>mindepth</code> 2692entries and an additional client is to ba added to the list, 2693if the oldest entry was updated more than 2694<code>maxage</code> 2695seconds ago, that entry is removed and its storage is reused. 2696If the oldest entry was updated more recently the MRU list is grown, 2697subject to 2698<code>maxdepth</code> <code>/</code> <code>moxmem</code>. 2699The default is 64 seconds. 2700<br><dt><code>initalloc</code> <kbd>count</kbd><br><dt><code>initmem</code> <kbd>kilobytes</kbd><dd>Initial memory allocation at the time the monitoringfacility is first enabled, 2701in terms of the number of entries or kilobytes. 2702The default is 4 kilobytes. 2703<br><dt><code>incalloc</code> <kbd>count</kbd><br><dt><code>incmem</code> <kbd>kilobytes</kbd><dd>Size of additional memory allocations when growing the MRU list, in entries or kilobytes. 2704The default is 4 kilobytes. 2705</dl> 2706 <br><dt><code>nonvolatile</code> <kbd>threshold</kbd><dd>Specify the 2707<kbd>threshold</kbd> 2708delta in seconds before an hourly change to the 2709<code>driftfile</code> 2710(frequency file) will be written, with a default value of 1e-7 (0.1 PPM). 2711The frequency file is inspected each hour. 2712If the difference between the current frequency and the last value written 2713exceeds the threshold, the file is written and the 2714<code>threshold</code> 2715becomes the new threshold value. 2716If the threshold is not exceeeded, it is reduced by half. 2717This is intended to reduce the number of file writes 2718for embedded systems with nonvolatile memory. 2719<br><dt><code>phone</code> <kbd>dial</kbd> <kbd>...</kbd><dd>This command is used in conjunction with 2720the ACTS modem driver (type 18) 2721or the JJY driver (type 40, mode 100 - 180). 2722For the ACTS modem driver (type 18), the arguments consist of 2723a maximum of 10 telephone numbers used to dial USNO, NIST, or European 2724time service. 2725For the JJY driver (type 40 mode 100 - 180), the argument is 2726one telephone number used to dial the telephone JJY service. 2727The Hayes command ATDT is normally prepended to the number. 2728The number can contain other modem control codes as well. 2729<br><dt><code>reset</code> <code>[allpeers]</code> <code>[auth]</code> <code>[ctl]</code> <code>[io]</code> <code>[mem]</code> <code>[sys]</code> <code>[timer]</code><dd>Reset one or more groups of counters maintained by 2730<code>ntpd</code> 2731and exposed by 2732<code>ntpq</code> 2733and 2734<code>ntpdc</code>. 2735<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> 2736 <dl> 2737<dt><code>memlock</code> <kbd>Nmegabytes</kbd><dd>Specify the number of megabytes of memory that should be 2738allocated and locked. 2739Probably only available under Linux, this option may be useful 2740when dropping root (the 2741<code>-i</code> 2742option). 2743The default is 32 megabytes on non-Linux machines, and -1 under Linux. 2744-1 means "do not lock the process into memory". 27450 means "lock whatever memory the process wants into memory". 2746<br><dt><code>stacksize</code> <kbd>N4kPages</kbd><dd>Specifies the maximum size of the process stack on systems with the 2747<code>mlockall()</code> 2748function. 2749Defaults to 50 4k pages (200 4k pages in OpenBSD). 2750<br><dt><code>filenum</code> <kbd>Nfiledescriptors</kbd><dd>Specifies the maximum number of file descriptors ntpd may have open at once. 2751Defaults to the system default. 2752</dl> 2753 <br><dt><code>saveconfigdir</code> <kbd>directory_path</kbd><dd>Specify the directory in which to write configuration snapshots 2754requested with 2755.Cm ntpq 's 2756<code>saveconfig</code> 2757command. 2758If 2759<code>saveconfigdir</code> 2760does not appear in the configuration file, 2761<code>saveconfig</code> 2762requests are rejected by 2763<code>ntpd</code>. 2764<br><dt><code>saveconfig</code> <kbd>filename</kbd><dd>Write the current configuration, including any runtime 2765modifications given with 2766<code>:config</code> 2767or 2768<code>config-from-file</code> 2769to the 2770<code>ntpd</code> 2771host's 2772<kbd>filename</kbd> 2773in the 2774<code>saveconfigdir</code>. 2775This command will be rejected unless the 2776<code>saveconfigdir</code> 2777directive appears in 2778.Cm ntpd 's 2779configuration file. 2780<kbd>filename</kbd> 2781can use 2782<code>strftime(3)</code> 2783format directives to substitute the current date and time, 2784for example, 2785<code>saveconfig\ ntp-%Y%m%d-%H%M%S.conf</code>. 2786The filename used is stored in the system variable 2787<code>savedconfig</code>. 2788Authentication is required. 2789<br><dt><code>setvar</code> <kbd>variable</kbd> <code>[default]</code><dd>This command adds an additional system variable. 2790These 2791variables can be used to distribute additional information such as 2792the access policy. 2793If the variable of the form 2794<code>name</code><code>=</code><kbd>value</kbd> 2795is followed by the 2796<code>default</code> 2797keyword, the 2798variable will be listed as part of the default system variables 2799(<code>rv</code> command)). 2800These additional variables serve 2801informational purposes only. 2802They are not related to the protocol 2803other that they can be listed. 2804The known protocol variables will 2805always override any variables defined via the 2806<code>setvar</code> 2807mechanism. 2808There are three special variables that contain the names 2809of all variable of the same group. 2810The 2811<code>sys_var_list</code> 2812holds 2813the names of all system variables. 2814The 2815<code>peer_var_list</code> 2816holds 2817the names of all peer variables and the 2818<code>clock_var_list</code> 2819holds the names of the reference clock variables. 2820<br><dt><code>sysinfo</code><dd>Display operational summary. 2821<br><dt><code>sysstats</code><dd>Show statistics counters maintained in the protocol module. 2822<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 2823very exceptional circumstances. 2824It should occur in the 2825configuration file before any other configuration options. 2826The 2827default values of these variables have been carefully optimized for 2828a wide range of network speeds and reliability expectations. 2829In 2830general, they interact in intricate ways that are hard to predict 2831and some combinations can result in some very nasty behavior. 2832Very 2833rarely is it necessary to change the default values; but, some 2834folks cannot resist twisting the knobs anyway and this command is 2835for them. 2836Emphasis added: twisters are on their own and can expect 2837no help from the support group. 2838 2839 <p>The variables operate as follows: 2840 <dl> 2841<dt><code>allan</code> <kbd>allan</kbd><dd>The argument becomes the new value for the minimum Allan 2842intercept, which is a parameter of the PLL/FLL clock discipline 2843algorithm. 2844The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2845limit. 2846<br><dt><code>dispersion</code> <kbd>dispersion</kbd><dd>The argument becomes the new value for the dispersion increase rate, 2847normally .000015 s/s. 2848<br><dt><code>freq</code> <kbd>freq</kbd><dd>The argument becomes the initial value of the frequency offset in 2849parts-per-million. 2850This overrides the value in the frequency file, if 2851present, and avoids the initial training state if it is not. 2852<br><dt><code>huffpuff</code> <kbd>huffpuff</kbd><dd>The argument becomes the new value for the experimental 2853huff-n'-puff filter span, which determines the most recent interval 2854the algorithm will search for a minimum delay. 2855The lower limit is 2856900 s (15 m), but a more reasonable value is 7200 (2 hours). 2857There 2858is no default, since the filter is not enabled unless this command 2859is given. 2860<br><dt><code>panic</code> <kbd>panic</kbd><dd>The argument is the panic threshold, normally 1000 s. 2861If set to zero, 2862the panic sanity check is disabled and a clock offset of any value will 2863be accepted. 2864<br><dt><code>step</code> <kbd>step</kbd><dd>The argument is the step threshold, which by default is 0.128 s. 2865It can 2866be set to any positive number in seconds. 2867If set to zero, step 2868adjustments will never occur. 2869Note: The kernel time discipline is 2870disabled if the step threshold is set to zero or greater than the 2871default. 2872<br><dt><code>stepback</code> <kbd>stepback</kbd><dd>The argument is the step threshold for the backward direction, 2873which by default is 0.128 s. 2874It can 2875be set to any positive number in seconds. 2876If both the forward and backward step thresholds are set to zero, step 2877adjustments will never occur. 2878Note: The kernel time discipline is 2879disabled if 2880each direction of step threshold are either 2881set to zero or greater than .5 second. 2882<br><dt><code>stepfwd</code> <kbd>stepfwd</kbd><dd>As for stepback, but for the forward direction. 2883<br><dt><code>stepout</code> <kbd>stepout</kbd><dd>The argument is the stepout timeout, which by default is 900 s. 2884It can 2885be set to any positive number in seconds. 2886If set to zero, the stepout 2887pulses will not be suppressed. 2888</dl> 2889 <br><dt><code>writevar</code> <kbd>assocID\ name</kbd> <kbd>=</kbd> <kbd>value</kbd> <kbd>[,...]</kbd><dd>Write (create or update) the specified variables. 2890If the 2891<code>assocID</code> 2892is zero, the variablea re from the 2893system variables 2894name space, otherwise they are from the 2895peer variables 2896name space. 2897The 2898<code>assocID</code> 2899is required, as the same name can occur in both name spaces. 2900<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 2901address and port number for sending messages with the specified 2902local interface address. 2903If the port number is unspecified, a value 2904of 18447 is used. 2905If the interface address is not specified, the 2906message is sent with a source address of the local interface the 2907message is sent through. 2908Note that on a multihomed host the 2909interface used may vary from time to time with routing changes. 2910<br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order. 2911Up to 8 values can be specified. 2912In 2913<code>manycast</code> 2914mode these values are used in-turn in an expanding-ring search. 2915The default is eight multiples of 32 starting at 31. 2916 2917 <p>The trap receiver will generally log event messages and other 2918information from the server in a log file. 2919While such monitor 2920programs may also request their own trap dynamically, configuring a 2921trap receiver will ensure that no messages are lost when the server 2922is started. 2923<br><dt><code>hop</code> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order, up to 8 2924values can be specified. 2925In manycast mode these values are used in turn in 2926an expanding-ring search. 2927The default is eight multiples of 32 starting at 292831. 2929</dl> 2930 2931 <p>This section was generated by <strong>AutoGen</strong>, 2932using the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program. 2933This software is released under the NTP license, <http://ntp.org/license>. 2934 2935<ul class="menu"> 2936<li><a accesskey="1" href="#ntp_002econf-Files">ntp.conf Files</a>: Files 2937<li><a accesskey="2" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also 2938<li><a accesskey="3" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs 2939<li><a accesskey="4" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes 2940</ul> 2941 2942<div class="node"> 2943<p><hr> 2944<a name="ntp_002econf-Files"></a> 2945<br> 2946</div> 2947 2948<h4 class="subsection">ntp.conf Files</h4> 2949 2950 <dl> 2951<dt><span class="file">/etc/ntp.conf</span><dd>the default name of the configuration file 2952<br><dt><span class="file">ntp.keys</span><dd>private MD5 keys 2953<br><dt><span class="file">ntpkey</span><dd>RSA private key 2954<br><dt><span class="file">ntpkey_</span><kbd>host</kbd><dd>RSA public key 2955<br><dt><span class="file">ntp_dh</span><dd>Diffie-Hellman agreement parameters 2956</dl> 2957<div class="node"> 2958<p><hr> 2959<a name="ntp_002econf-See-Also"></a> 2960<br> 2961</div> 2962 2963<h4 class="subsection">ntp.conf See Also</h4> 2964 2965<p><code>ntpd(1ntpdmdoc)</code>, 2966<code>ntpdc(1ntpdcmdoc)</code>, 2967<code>ntpq(1ntpqmdoc)</code> 2968 2969 <p>In addition to the manual pages provided, 2970comprehensive documentation is available on the world wide web 2971at 2972<code>http://www.ntp.org/</code>. 2973A snapshot of this documentation is available in HTML format in 2974<span class="file">/usr/share/doc/ntp</span>. 2975<br> 2976 2977 <p><br> 2978David L. Mills, <em>Network Time Protocol (Version 4)</em>, RFC5905 2979<div class="node"> 2980<p><hr> 2981<a name="ntp_002econf-Bugs"></a> 2982<br> 2983</div> 2984 2985<h4 class="subsection">ntp.conf Bugs</h4> 2986 2987<p>The syntax checking is not picky; some combinations of 2988ridiculous and even hilarious options and modes may not be 2989detected. 2990 2991 <p>The 2992<span class="file">ntpkey_</span><kbd>host</kbd> 2993files are really digital 2994certificates. 2995These should be obtained via secure directory 2996services when they become universally available. 2997<div class="node"> 2998<p><hr> 2999<a name="ntp_002econf-Notes"></a> 3000<br> 3001</div> 3002 3003<h4 class="subsection">ntp.conf Notes</h4> 3004 3005<p>This document was derived from FreeBSD. 3006 3007</body></html> 3008 3009