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