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