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