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