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