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