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