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