invoke-ntp.conf.texi revision 309007
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 November 21, 2016 at 08:01:55 AM by AutoGen 5.18.5 10# From the definitions ntp.conf.def 11# and the template file agtexi-file.tpl 12@end ignore 13 14 15 16The 17@code{ntp.conf} 18configuration file is read at initial startup by the 19@code{ntpd(1ntpdmdoc)} 20daemon in order to specify the synchronization sources, 21modes and other related information. 22Usually, it is installed in the 23@file{/etc} 24directory, 25but could be installed elsewhere 26(see the daemon's 27@code{-c} 28command line option). 29 30The file format is similar to other 31@sc{unix} 32configuration files. 33Comments begin with a 34@quoteleft{}#@quoteright{} 35character and extend to the end of the line; 36blank lines are ignored. 37Configuration commands consist of an initial keyword 38followed by a list of arguments, 39some of which may be optional, separated by whitespace. 40Commands may not be continued over multiple lines. 41Arguments may be host names, 42host addresses written in numeric, dotted-quad form, 43integers, floating point numbers (when specifying times in seconds) 44and text strings. 45 46The rest of this page describes the configuration and control options. 47The 48"Notes on Configuring NTP and Setting up an NTP Subnet" 49page 50(available as part of the HTML documentation 51provided in 52@file{/usr/share/doc/ntp}) 53contains an extended discussion of these options. 54In addition to the discussion of general 55@ref{Configuration Options}, 56there are sections describing the following supported functionality 57and the options used to control it: 58@itemize @bullet 59@item 60@ref{Authentication Support} 61@item 62@ref{Monitoring Support} 63@item 64@ref{Access Control Support} 65@item 66@ref{Automatic NTP Configuration Options} 67@item 68@ref{Reference Clock Support} 69@item 70@ref{Miscellaneous Options} 71@end itemize 72 73Following these is a section describing 74@ref{Miscellaneous Options}. 75While there is a rich set of options available, 76the only required option is one or more 77@code{pool}, 78@code{server}, 79@code{peer}, 80@code{broadcast} 81or 82@code{manycastclient} 83commands. 84@node Configuration Support 85@subsection Configuration Support 86Following is a description of the configuration commands in 87NTPv4. 88These commands have the same basic functions as in NTPv3 and 89in some cases new functions and new arguments. 90There are two 91classes of commands, configuration commands that configure a 92persistent association with a remote server or peer or reference 93clock, and auxiliary commands that specify environmental variables 94that control various related operations. 95@subsubsection Configuration Commands 96The various modes are determined by the command keyword and the 97type of the required IP address. 98Addresses are classed by type as 99(s) a remote server or peer (IPv4 class A, B and C), (b) the 100broadcast address of a local interface, (m) a multicast address (IPv4 101class D), or (r) a reference clock address (127.127.x.x). 102Note that 103only those options applicable to each command are listed below. 104Use 105of options not listed may not be caught as an error, but may result 106in some weird and even destructive behavior. 107 108If the Basic Socket Interface Extensions for IPv6 (RFC-2553) 109is detected, support for the IPv6 address family is generated 110in addition to the default support of the IPv4 address family. 111In a few cases, including the 112@code{reslist} 113billboard generated 114by 115@code{ntpq(1ntpqmdoc)} 116or 117@code{ntpdc(1ntpdcmdoc)}, 118IPv6 addresses are automatically generated. 119IPv6 addresses can be identified by the presence of colons 120@quotedblleft{}:@quotedblright{} 121in the address field. 122IPv6 addresses can be used almost everywhere where 123IPv4 addresses can be used, 124with the exception of reference clock addresses, 125which are always IPv4. 126 127Note that in contexts where a host name is expected, a 128@code{-4} 129qualifier preceding 130the host name forces DNS resolution to the IPv4 namespace, 131while a 132@code{-6} 133qualifier forces DNS resolution to the IPv6 namespace. 134See IPv6 references for the 135equivalent classes for that address family. 136@table @asis 137@item @code{pool} @kbd{address} @code{[@code{burst}]} @code{[@code{iburst}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} 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{[@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. 1489In the current implementation, 1490@code{flag} 1491always 1492restricts access, i.e., an entry with no flags indicates that free 1493access to the server is to be given. 1494The flags are not orthogonal, 1495in that more restrictive flags will often make less restrictive 1496ones redundant. 1497The flags can generally be classed into two 1498categories, those which restrict time service and those which 1499restrict informational queries and attempts to do run-time 1500reconfiguration of the server. 1501One or more of the following flags 1502may be specified: 1503@table @asis 1504@item @code{ignore} 1505Deny packets of all kinds, including 1506@code{ntpq(1ntpqmdoc)} 1507and 1508@code{ntpdc(1ntpdcmdoc)} 1509queries. 1510@item @code{kod} 1511If this flag is set when an access violation occurs, a kiss-o'-death 1512(KoD) packet is sent. 1513KoD packets are rate limited to no more than one 1514per second. 1515If another KoD packet occurs within one second after the 1516last one, the packet is dropped. 1517@item @code{limited} 1518Deny service if the packet spacing violates the lower limits specified 1519in the 1520@code{discard} 1521command. 1522A history of clients is kept using the 1523monitoring capability of 1524@code{ntpd(1ntpdmdoc)}. 1525Thus, monitoring is always active as 1526long as there is a restriction entry with the 1527@code{limited} 1528flag. 1529@item @code{lowpriotrap} 1530Declare traps set by matching hosts to be low priority. 1531The 1532number of traps a server can maintain is limited (the current limit 1533is 3). 1534Traps are usually assigned on a first come, first served 1535basis, with later trap requestors being denied service. 1536This flag 1537modifies the assignment algorithm by allowing low priority traps to 1538be overridden by later requests for normal priority traps. 1539@item @code{nomodify} 1540Deny 1541@code{ntpq(1ntpqmdoc)} 1542and 1543@code{ntpdc(1ntpdcmdoc)} 1544queries which attempt to modify the state of the 1545server (i.e., run time reconfiguration). 1546Queries which return 1547information are permitted. 1548@item @code{noquery} 1549Deny 1550@code{ntpq(1ntpqmdoc)} 1551and 1552@code{ntpdc(1ntpdcmdoc)} 1553queries. 1554Time service is not affected. 1555@item @code{nopeer} 1556Deny packets which would result in mobilizing a new association. 1557This 1558includes broadcast and symmetric active packets when a configured 1559association does not exist. 1560It also includes 1561@code{pool} 1562associations, so if you want to use servers from a 1563@code{pool} 1564directive and also want to use 1565@code{nopeer} 1566by default, you'll want a 1567@code{restrict source ...} @code{line} @code{as} @code{well} @code{that} @code{does} 1568@item not 1569include the 1570@code{nopeer} 1571directive. 1572@item @code{noserve} 1573Deny all packets except 1574@code{ntpq(1ntpqmdoc)} 1575and 1576@code{ntpdc(1ntpdcmdoc)} 1577queries. 1578@item @code{notrap} 1579Decline to provide mode 6 control message trap service to matching 1580hosts. 1581The trap service is a subsystem of the 1582@code{ntpq(1ntpqmdoc)} 1583control message 1584protocol which is intended for use by remote event logging programs. 1585@item @code{notrust} 1586Deny service unless the packet is cryptographically authenticated. 1587@item @code{ntpport} 1588This is actually a match algorithm modifier, rather than a 1589restriction flag. 1590Its presence causes the restriction entry to be 1591matched only if the source port in the packet is the standard NTP 1592UDP port (123). 1593Both 1594@code{ntpport} 1595and 1596@code{non-ntpport} 1597may 1598be specified. 1599The 1600@code{ntpport} 1601is considered more specific and 1602is sorted later in the list. 1603@item @code{version} 1604Deny packets that do not match the current NTP version. 1605@end table 1606 1607Default restriction list entries with the flags ignore, interface, 1608ntpport, for each of the local host's interface addresses are 1609inserted into the table at startup to prevent the server 1610from attempting to synchronize to its own time. 1611A default entry is also always present, though if it is 1612otherwise unconfigured; no flags are associated 1613with the default entry (i.e., everything besides your own 1614NTP server is unrestricted). 1615@end table 1616@node Automatic NTP Configuration Options 1617@subsection Automatic NTP Configuration Options 1618@subsubsection Manycasting 1619Manycasting is a automatic discovery and configuration paradigm 1620new to NTPv4. 1621It is intended as a means for a multicast client 1622to troll the nearby network neighborhood to find cooperating 1623manycast servers, validate them using cryptographic means 1624and evaluate their time values with respect to other servers 1625that might be lurking in the vicinity. 1626The intended result is that each manycast client mobilizes 1627client associations with some number of the "best" 1628of the nearby manycast servers, yet automatically reconfigures 1629to sustain this number of servers should one or another fail. 1630 1631Note that the manycasting paradigm does not coincide 1632with the anycast paradigm described in RFC-1546, 1633which is designed to find a single server from a clique 1634of servers providing the same service. 1635The manycast paradigm is designed to find a plurality 1636of redundant servers satisfying defined optimality criteria. 1637 1638Manycasting can be used with either symmetric key 1639or public key cryptography. 1640The public key infrastructure (PKI) 1641offers the best protection against compromised keys 1642and is generally considered stronger, at least with relatively 1643large key sizes. 1644It is implemented using the Autokey protocol and 1645the OpenSSL cryptographic library available from 1646@code{http://www.openssl.org/}. 1647The library can also be used with other NTPv4 modes 1648as well and is highly recommended, especially for broadcast modes. 1649 1650A persistent manycast client association is configured 1651using the 1652@code{manycastclient} 1653command, which is similar to the 1654@code{server} 1655command but with a multicast (IPv4 class 1656@code{D} 1657or IPv6 prefix 1658@code{FF}) 1659group address. 1660The IANA has designated IPv4 address 224.1.1.1 1661and IPv6 address FF05::101 (site local) for NTP. 1662When more servers are needed, it broadcasts manycast 1663client messages to this address at the minimum feasible rate 1664and minimum feasible time-to-live (TTL) hops, depending 1665on how many servers have already been found. 1666There can be as many manycast client associations 1667as different group address, each one serving as a template 1668for a future ephemeral unicast client/server association. 1669 1670Manycast servers configured with the 1671@code{manycastserver} 1672command listen on the specified group address for manycast 1673client messages. 1674Note the distinction between manycast client, 1675which actively broadcasts messages, and manycast server, 1676which passively responds to them. 1677If a manycast server is 1678in scope of the current TTL and is itself synchronized 1679to a valid source and operating at a stratum level equal 1680to or lower than the manycast client, it replies to the 1681manycast client message with an ordinary unicast server message. 1682 1683The manycast client receiving this message mobilizes 1684an ephemeral client/server association according to the 1685matching manycast client template, but only if cryptographically 1686authenticated and the server stratum is less than or equal 1687to the client stratum. 1688Authentication is explicitly required 1689and either symmetric key or public key (Autokey) can be used. 1690Then, the client polls the server at its unicast address 1691in burst mode in order to reliably set the host clock 1692and validate the source. 1693This normally results 1694in a volley of eight client/server at 2-s intervals 1695during which both the synchronization and cryptographic 1696protocols run concurrently. 1697Following the volley, 1698the client runs the NTP intersection and clustering 1699algorithms, which act to discard all but the "best" 1700associations according to stratum and synchronization 1701distance. 1702The surviving associations then continue 1703in ordinary client/server mode. 1704 1705The manycast client polling strategy is designed to reduce 1706as much as possible the volume of manycast client messages 1707and the effects of implosion due to near-simultaneous 1708arrival of manycast server messages. 1709The strategy is determined by the 1710@code{manycastclient}, 1711@code{tos} 1712and 1713@code{ttl} 1714configuration commands. 1715The manycast poll interval is 1716normally eight times the system poll interval, 1717which starts out at the 1718@code{minpoll} 1719value specified in the 1720@code{manycastclient}, 1721command and, under normal circumstances, increments to the 1722@code{maxpolll} 1723value specified in this command. 1724Initially, the TTL is 1725set at the minimum hops specified by the 1726@code{ttl} 1727command. 1728At each retransmission the TTL is increased until reaching 1729the maximum hops specified by this command or a sufficient 1730number client associations have been found. 1731Further retransmissions use the same TTL. 1732 1733The quality and reliability of the suite of associations 1734discovered by the manycast client is determined by the NTP 1735mitigation algorithms and the 1736@code{minclock} 1737and 1738@code{minsane} 1739values specified in the 1740@code{tos} 1741configuration command. 1742At least 1743@code{minsane} 1744candidate servers must be available and the mitigation 1745algorithms produce at least 1746@code{minclock} 1747survivors in order to synchronize the clock. 1748Byzantine agreement principles require at least four 1749candidates in order to correctly discard a single falseticker. 1750For legacy purposes, 1751@code{minsane} 1752defaults to 1 and 1753@code{minclock} 1754defaults to 3. 1755For manycast service 1756@code{minsane} 1757should be explicitly set to 4, assuming at least that 1758number of servers are available. 1759 1760If at least 1761@code{minclock} 1762servers are found, the manycast poll interval is immediately 1763set to eight times 1764@code{maxpoll}. 1765If less than 1766@code{minclock} 1767servers are found when the TTL has reached the maximum hops, 1768the manycast poll interval is doubled. 1769For each transmission 1770after that, the poll interval is doubled again until 1771reaching the maximum of eight times 1772@code{maxpoll}. 1773Further transmissions use the same poll interval and 1774TTL values. 1775Note that while all this is going on, 1776each client/server association found is operating normally 1777it the system poll interval. 1778 1779Administratively scoped multicast boundaries are normally 1780specified by the network router configuration and, 1781in the case of IPv6, the link/site scope prefix. 1782By default, the increment for TTL hops is 32 starting 1783from 31; however, the 1784@code{ttl} 1785configuration command can be 1786used to modify the values to match the scope rules. 1787 1788It is often useful to narrow the range of acceptable 1789servers which can be found by manycast client associations. 1790Because manycast servers respond only when the client 1791stratum is equal to or greater than the server stratum, 1792primary (stratum 1) servers fill find only primary servers 1793in TTL range, which is probably the most common objective. 1794However, unless configured otherwise, all manycast clients 1795in TTL range will eventually find all primary servers 1796in TTL range, which is probably not the most common 1797objective in large networks. 1798The 1799@code{tos} 1800command can be used to modify this behavior. 1801Servers with stratum below 1802@code{floor} 1803or above 1804@code{ceiling} 1805specified in the 1806@code{tos} 1807command are strongly discouraged during the selection 1808process; however, these servers may be temporally 1809accepted if the number of servers within TTL range is 1810less than 1811@code{minclock}. 1812 1813The above actions occur for each manycast client message, 1814which repeats at the designated poll interval. 1815However, once the ephemeral client association is mobilized, 1816subsequent manycast server replies are discarded, 1817since that would result in a duplicate association. 1818If during a poll interval the number of client associations 1819falls below 1820@code{minclock}, 1821all manycast client prototype associations are reset 1822to the initial poll interval and TTL hops and operation 1823resumes from the beginning. 1824It is important to avoid 1825frequent manycast client messages, since each one requires 1826all manycast servers in TTL range to respond. 1827The result could well be an implosion, either minor or major, 1828depending on the number of servers in range. 1829The recommended value for 1830@code{maxpoll} 1831is 12 (4,096 s). 1832 1833It is possible and frequently useful to configure a host 1834as both manycast client and manycast server. 1835A number of hosts configured this way and sharing a common 1836group address will automatically organize themselves 1837in an optimum configuration based on stratum and 1838synchronization distance. 1839For example, consider an NTP 1840subnet of two primary servers and a hundred or more 1841dependent clients. 1842With two exceptions, all servers 1843and clients have identical configuration files including both 1844@code{multicastclient} 1845and 1846@code{multicastserver} 1847commands using, for instance, multicast group address 1848239.1.1.1. 1849The only exception is that each primary server 1850configuration file must include commands for the primary 1851reference source such as a GPS receiver. 1852 1853The remaining configuration files for all secondary 1854servers and clients have the same contents, except for the 1855@code{tos} 1856command, which is specific for each stratum level. 1857For stratum 1 and stratum 2 servers, that command is 1858not necessary. 1859For stratum 3 and above servers the 1860@code{floor} 1861value is set to the intended stratum number. 1862Thus, all stratum 3 configuration files are identical, 1863all stratum 4 files are identical and so forth. 1864 1865Once operations have stabilized in this scenario, 1866the primary servers will find the primary reference source 1867and each other, since they both operate at the same 1868stratum (1), but not with any secondary server or client, 1869since these operate at a higher stratum. 1870The secondary 1871servers will find the servers at the same stratum level. 1872If one of the primary servers loses its GPS receiver, 1873it will continue to operate as a client and other clients 1874will time out the corresponding association and 1875re-associate accordingly. 1876 1877Some administrators prefer to avoid running 1878@code{ntpd(1ntpdmdoc)} 1879continuously and run either 1880@code{sntp(1sntpmdoc)} 1881or 1882@code{ntpd(1ntpdmdoc)} 1883@code{-q} 1884as a cron job. 1885In either case the servers must be 1886configured in advance and the program fails if none are 1887available when the cron job runs. 1888A really slick 1889application of manycast is with 1890@code{ntpd(1ntpdmdoc)} 1891@code{-q}. 1892The program wakes up, scans the local landscape looking 1893for the usual suspects, selects the best from among 1894the rascals, sets the clock and then departs. 1895Servers do not have to be configured in advance and 1896all clients throughout the network can have the same 1897configuration file. 1898@subsubsection Manycast Interactions with Autokey 1899Each time a manycast client sends a client mode packet 1900to a multicast group address, all manycast servers 1901in scope generate a reply including the host name 1902and status word. 1903The manycast clients then run 1904the Autokey protocol, which collects and verifies 1905all certificates involved. 1906Following the burst interval 1907all but three survivors are cast off, 1908but the certificates remain in the local cache. 1909It often happens that several complete signing trails 1910from the client to the primary servers are collected in this way. 1911 1912About once an hour or less often if the poll interval 1913exceeds this, the client regenerates the Autokey key list. 1914This is in general transparent in client/server mode. 1915However, about once per day the server private value 1916used to generate cookies is refreshed along with all 1917manycast client associations. 1918In this case all 1919cryptographic values including certificates is refreshed. 1920If a new certificate has been generated since 1921the last refresh epoch, it will automatically revoke 1922all prior certificates that happen to be in the 1923certificate cache. 1924At the same time, the manycast 1925scheme starts all over from the beginning and 1926the expanding ring shrinks to the minimum and increments 1927from there while collecting all servers in scope. 1928@subsubsection Broadcast Options 1929@table @asis 1930@item @code{tos} @code{[@code{bcpollbstep} @kbd{gate}]} 1931This command provides a way to delay, 1932by the specified number of broadcast poll intervals, 1933believing backward time steps from a broadcast server. 1934Broadcast time networks are expected to be trusted. 1935In the event a broadcast server's time is stepped backwards, 1936there is clear benefit to having the clients notice this change 1937as soon as possible. 1938Attacks such as replay attacks can happen, however, 1939and even though there are a number of protections built in to 1940broadcast mode, attempts to perform a replay attack are possible. 1941This value defaults to 0, but can be changed 1942to any number of poll intervals between 0 and 4. 1943@subsubsection Manycast Options 1944@table @asis 1945@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}]} 1946This command affects the clock selection and clustering 1947algorithms. 1948It can be used to select the quality and 1949quantity of peers used to synchronize the system clock 1950and is most useful in manycast mode. 1951The variables operate 1952as follows: 1953@table @asis 1954@item @code{ceiling} @kbd{ceiling} 1955Peers with strata above 1956@code{ceiling} 1957will be discarded if there are at least 1958@code{minclock} 1959peers remaining. 1960This value defaults to 15, but can be changed 1961to any number from 1 to 15. 1962@item @code{cohort} @code{@{0 | 1@}} 1963This is a binary flag which enables (0) or disables (1) 1964manycast server replies to manycast clients with the same 1965stratum level. 1966This is useful to reduce implosions where 1967large numbers of clients with the same stratum level 1968are present. 1969The default is to enable these replies. 1970@item @code{floor} @kbd{floor} 1971Peers with strata below 1972@code{floor} 1973will be discarded if there are at least 1974@code{minclock} 1975peers remaining. 1976This value defaults to 1, but can be changed 1977to any number from 1 to 15. 1978@item @code{minclock} @kbd{minclock} 1979The clustering algorithm repeatedly casts out outlier 1980associations until no more than 1981@code{minclock} 1982associations remain. 1983This value defaults to 3, 1984but can be changed to any number from 1 to the number of 1985configured sources. 1986@item @code{minsane} @kbd{minsane} 1987This is the minimum number of candidates available 1988to the clock selection algorithm in order to produce 1989one or more truechimers for the clustering algorithm. 1990If fewer than this number are available, the clock is 1991undisciplined and allowed to run free. 1992The default is 1 1993for legacy purposes. 1994However, according to principles of 1995Byzantine agreement, 1996@code{minsane} 1997should be at least 4 in order to detect and discard 1998a single falseticker. 1999@end table 2000@item @code{ttl} @kbd{hop} @kbd{...} 2001This command specifies a list of TTL values in increasing 2002order, up to 8 values can be specified. 2003In manycast mode these values are used in turn 2004in an expanding-ring search. 2005The default is eight 2006multiples of 32 starting at 31. 2007@end table 2008@node Reference Clock Support 2009@subsection Reference Clock Support 2010The NTP Version 4 daemon supports some three dozen different radio, 2011satellite and modem reference clocks plus a special pseudo-clock 2012used for backup or when no other clock source is available. 2013Detailed descriptions of individual device drivers and options can 2014be found in the 2015"Reference Clock Drivers" 2016page 2017(available as part of the HTML documentation 2018provided in 2019@file{/usr/share/doc/ntp}). 2020Additional information can be found in the pages linked 2021there, including the 2022"Debugging Hints for Reference Clock Drivers" 2023and 2024"How To Write a Reference Clock Driver" 2025pages 2026(available as part of the HTML documentation 2027provided in 2028@file{/usr/share/doc/ntp}). 2029In addition, support for a PPS 2030signal is available as described in the 2031"Pulse-per-second (PPS) Signal Interfacing" 2032page 2033(available as part of the HTML documentation 2034provided in 2035@file{/usr/share/doc/ntp}). 2036Many 2037drivers support special line discipline/streams modules which can 2038significantly improve the accuracy using the driver. 2039These are 2040described in the 2041"Line Disciplines and Streams Drivers" 2042page 2043(available as part of the HTML documentation 2044provided in 2045@file{/usr/share/doc/ntp}). 2046 2047A reference clock will generally (though not always) be a radio 2048timecode receiver which is synchronized to a source of standard 2049time such as the services offered by the NRC in Canada and NIST and 2050USNO in the US. 2051The interface between the computer and the timecode 2052receiver is device dependent, but is usually a serial port. 2053A 2054device driver specific to each reference clock must be selected and 2055compiled in the distribution; however, most common radio, satellite 2056and modem clocks are included by default. 2057Note that an attempt to 2058configure a reference clock when the driver has not been compiled 2059or the hardware port has not been appropriately configured results 2060in a scalding remark to the system log file, but is otherwise non 2061hazardous. 2062 2063For the purposes of configuration, 2064@code{ntpd(1ntpdmdoc)} 2065treats 2066reference clocks in a manner analogous to normal NTP peers as much 2067as possible. 2068Reference clocks are identified by a syntactically 2069correct but invalid IP address, in order to distinguish them from 2070normal NTP peers. 2071Reference clock addresses are of the form 2072@code{127.127.}@kbd{t}.@kbd{u}, 2073where 2074@kbd{t} 2075is an integer 2076denoting the clock type and 2077@kbd{u} 2078indicates the unit 2079number in the range 0-3. 2080While it may seem overkill, it is in fact 2081sometimes useful to configure multiple reference clocks of the same 2082type, in which case the unit numbers must be unique. 2083 2084The 2085@code{server} 2086command is used to configure a reference 2087clock, where the 2088@kbd{address} 2089argument in that command 2090is the clock address. 2091The 2092@code{key}, 2093@code{version} 2094and 2095@code{ttl} 2096options are not used for reference clock support. 2097The 2098@code{mode} 2099option is added for reference clock support, as 2100described below. 2101The 2102@code{prefer} 2103option can be useful to 2104persuade the server to cherish a reference clock with somewhat more 2105enthusiasm than other reference clocks or peers. 2106Further 2107information on this option can be found in the 2108"Mitigation Rules and the prefer Keyword" 2109(available as part of the HTML documentation 2110provided in 2111@file{/usr/share/doc/ntp}) 2112page. 2113The 2114@code{minpoll} 2115and 2116@code{maxpoll} 2117options have 2118meaning only for selected clock drivers. 2119See the individual clock 2120driver document pages for additional information. 2121 2122The 2123@code{fudge} 2124command is used to provide additional 2125information for individual clock drivers and normally follows 2126immediately after the 2127@code{server} 2128command. 2129The 2130@kbd{address} 2131argument specifies the clock address. 2132The 2133@code{refid} 2134and 2135@code{stratum} 2136options can be used to 2137override the defaults for the device. 2138There are two optional 2139device-dependent time offsets and four flags that can be included 2140in the 2141@code{fudge} 2142command as well. 2143 2144The stratum number of a reference clock is by default zero. 2145Since the 2146@code{ntpd(1ntpdmdoc)} 2147daemon adds one to the stratum of each 2148peer, a primary server ordinarily displays an external stratum of 2149one. 2150In order to provide engineered backups, it is often useful to 2151specify the reference clock stratum as greater than zero. 2152The 2153@code{stratum} 2154option is used for this purpose. 2155Also, in cases 2156involving both a reference clock and a pulse-per-second (PPS) 2157discipline signal, it is useful to specify the reference clock 2158identifier as other than the default, depending on the driver. 2159The 2160@code{refid} 2161option is used for this purpose. 2162Except where noted, 2163these options apply to all clock drivers. 2164@subsubsection Reference Clock Commands 2165@table @asis 2166@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}]} 2167This command can be used to configure reference clocks in 2168special ways. 2169The options are interpreted as follows: 2170@table @asis 2171@item @code{prefer} 2172Marks the reference clock as preferred. 2173All other things being 2174equal, this host will be chosen for synchronization among a set of 2175correctly operating hosts. 2176See the 2177"Mitigation Rules and the prefer Keyword" 2178page 2179(available as part of the HTML documentation 2180provided in 2181@file{/usr/share/doc/ntp}) 2182for further information. 2183@item @code{mode} @kbd{int} 2184Specifies a mode number which is interpreted in a 2185device-specific fashion. 2186For instance, it selects a dialing 2187protocol in the ACTS driver and a device subtype in the 2188parse 2189drivers. 2190@item @code{minpoll} @kbd{int} 2191@item @code{maxpoll} @kbd{int} 2192These options specify the minimum and maximum polling interval 2193for reference clock messages, as a power of 2 in seconds 2194For 2195most directly connected reference clocks, both 2196@code{minpoll} 2197and 2198@code{maxpoll} 2199default to 6 (64 s). 2200For modem reference clocks, 2201@code{minpoll} 2202defaults to 10 (17.1 m) and 2203@code{maxpoll} 2204defaults to 14 (4.5 h). 2205The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2206@end table 2207@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}]} 2208This command can be used to configure reference clocks in 2209special ways. 2210It must immediately follow the 2211@code{server} 2212command which configures the driver. 2213Note that the same capability 2214is possible at run time using the 2215@code{ntpdc(1ntpdcmdoc)} 2216program. 2217The options are interpreted as 2218follows: 2219@table @asis 2220@item @code{time1} @kbd{sec} 2221Specifies a constant to be added to the time offset produced by 2222the driver, a fixed-point decimal number in seconds. 2223This is used 2224as a calibration constant to adjust the nominal time offset of a 2225particular clock to agree with an external standard, such as a 2226precision PPS signal. 2227It also provides a way to correct a 2228systematic error or bias due to serial port or operating system 2229latencies, different cable lengths or receiver internal delay. 2230The 2231specified offset is in addition to the propagation delay provided 2232by other means, such as internal DIPswitches. 2233Where a calibration 2234for an individual system and driver is available, an approximate 2235correction is noted in the driver documentation pages. 2236Note: in order to facilitate calibration when more than one 2237radio clock or PPS signal is supported, a special calibration 2238feature is available. 2239It takes the form of an argument to the 2240@code{enable} 2241command described in 2242@ref{Miscellaneous Options} 2243page and operates as described in the 2244"Reference Clock Drivers" 2245page 2246(available as part of the HTML documentation 2247provided in 2248@file{/usr/share/doc/ntp}). 2249@item @code{time2} @kbd{secs} 2250Specifies a fixed-point decimal number in seconds, which is 2251interpreted in a driver-dependent way. 2252See the descriptions of 2253specific drivers in the 2254"Reference Clock Drivers" 2255page 2256(available as part of the HTML documentation 2257provided in 2258@file{/usr/share/doc/ntp}). 2259@item @code{stratum} @kbd{int} 2260Specifies the stratum number assigned to the driver, an integer 2261between 0 and 15. 2262This number overrides the default stratum number 2263ordinarily assigned by the driver itself, usually zero. 2264@item @code{refid} @kbd{string} 2265Specifies an ASCII string of from one to four characters which 2266defines the reference identifier used by the driver. 2267This string 2268overrides the default identifier ordinarily assigned by the driver 2269itself. 2270@item @code{mode} @kbd{int} 2271Specifies a mode number which is interpreted in a 2272device-specific fashion. 2273For instance, it selects a dialing 2274protocol in the ACTS driver and a device subtype in the 2275parse 2276drivers. 2277@item @code{flag1} @code{0} @code{|} @code{1} 2278@item @code{flag2} @code{0} @code{|} @code{1} 2279@item @code{flag3} @code{0} @code{|} @code{1} 2280@item @code{flag4} @code{0} @code{|} @code{1} 2281These four flags are used for customizing the clock driver. 2282The 2283interpretation of these values, and whether they are used at all, 2284is a function of the particular clock driver. 2285However, by 2286convention 2287@code{flag4} 2288is used to enable recording monitoring 2289data to the 2290@code{clockstats} 2291file configured with the 2292@code{filegen} 2293command. 2294Further information on the 2295@code{filegen} 2296command can be found in 2297@ref{Monitoring Options}. 2298@end table 2299@end table 2300@node Miscellaneous Options 2301@subsection Miscellaneous Options 2302@table @asis 2303@item @code{broadcastdelay} @kbd{seconds} 2304The broadcast and multicast modes require a special calibration 2305to determine the network delay between the local and remote 2306servers. 2307Ordinarily, this is done automatically by the initial 2308protocol exchanges between the client and server. 2309In some cases, 2310the calibration procedure may fail due to network or server access 2311controls, for example. 2312This command specifies the default delay to 2313be used under these circumstances. 2314Typically (for Ethernet), a 2315number between 0.003 and 0.007 seconds is appropriate. 2316The default 2317when this command is not used is 0.004 seconds. 2318@item @code{calldelay} @kbd{delay} 2319This option controls the delay in seconds between the first and second 2320packets sent in burst or iburst mode to allow additional time for a modem 2321or ISDN call to complete. 2322@item @code{driftfile} @kbd{driftfile} 2323This command specifies the complete path and name of the file used to 2324record the frequency of the local clock oscillator. 2325This is the same 2326operation as the 2327@code{-f} 2328command line option. 2329If the file exists, it is read at 2330startup in order to set the initial frequency and then updated once per 2331hour with the current frequency computed by the daemon. 2332If the file name is 2333specified, but the file itself does not exist, the starts with an initial 2334frequency of zero and creates the file when writing it for the first time. 2335If this command is not given, the daemon will always start with an initial 2336frequency of zero. 2337 2338The file format consists of a single line containing a single 2339floating point number, which records the frequency offset measured 2340in parts-per-million (PPM). 2341The file is updated by first writing 2342the current drift value into a temporary file and then renaming 2343this file to replace the old version. 2344This implies that 2345@code{ntpd(1ntpdmdoc)} 2346must have write permission for the directory the 2347drift file is located in, and that file system links, symbolic or 2348otherwise, should be avoided. 2349@item @code{dscp} @kbd{value} 2350This option specifies the Differentiated Services Control Point (DSCP) value, 2351a 6-bit code. 2352The default value is 46, signifying Expedited Forwarding. 2353@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}]} 2354@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}]} 2355Provides a way to enable or disable various server options. 2356Flags not mentioned are unaffected. 2357Note that all of these flags 2358can be controlled remotely using the 2359@code{ntpdc(1ntpdcmdoc)} 2360utility program. 2361@table @asis 2362@item @code{auth} 2363Enables the server to synchronize with unconfigured peers only if the 2364peer has been correctly authenticated using either public key or 2365private key cryptography. 2366The default for this flag is 2367@code{enable}. 2368@item @code{bclient} 2369Enables the server to listen for a message from a broadcast or 2370multicast server, as in the 2371@code{multicastclient} 2372command with default 2373address. 2374The default for this flag is 2375@code{disable}. 2376@item @code{calibrate} 2377Enables the calibrate feature for reference clocks. 2378The default for 2379this flag is 2380@code{disable}. 2381@item @code{kernel} 2382Enables the kernel time discipline, if available. 2383The default for this 2384flag is 2385@code{enable} 2386if support is available, otherwise 2387@code{disable}. 2388@item @code{mode7} 2389Enables processing of NTP mode 7 implementation-specific requests 2390which are used by the deprecated 2391@code{ntpdc(1ntpdcmdoc)} 2392program. 2393The default for this flag is disable. 2394This flag is excluded from runtime configuration using 2395@code{ntpq(1ntpqmdoc)}. 2396The 2397@code{ntpq(1ntpqmdoc)} 2398program provides the same capabilities as 2399@code{ntpdc(1ntpdcmdoc)} 2400using standard mode 6 requests. 2401@item @code{monitor} 2402Enables the monitoring facility. 2403See the 2404@code{ntpdc(1ntpdcmdoc)} 2405program 2406and the 2407@code{monlist} 2408command or further information. 2409The 2410default for this flag is 2411@code{enable}. 2412@item @code{ntp} 2413Enables time and frequency discipline. 2414In effect, this switch opens and 2415closes the feedback loop, which is useful for testing. 2416The default for 2417this flag is 2418@code{enable}. 2419@item @code{peer_clear_digest_early} 2420By default, if 2421@code{ntpd(1ntpdmdoc)} 2422is using autokey and it 2423receives a crypto-NAK packet that 2424passes the duplicate packet and origin timestamp checks 2425the peer variables are immediately cleared. 2426While this is generally a feature 2427as it allows for quick recovery if a server key has changed, 2428a properly forged and appropriately delivered crypto-NAK packet 2429can be used in a DoS attack. 2430If you have active noticable problems with this type of DoS attack 2431then you should consider 2432disabling this option. 2433You can check your 2434@code{peerstats} 2435file for evidence of any of these attacks. 2436The 2437default for this flag is 2438@code{enable}. 2439@item @code{stats} 2440Enables the statistics facility. 2441See the 2442@ref{Monitoring Options} 2443section for further information. 2444The default for this flag is 2445@code{disable}. 2446@item @code{unpeer_crypto_early} 2447By default, if 2448@code{ntpd(1ntpdmdoc)} 2449receives an autokey packet that fails TEST9, 2450a crypto failure, 2451the association is immediately cleared. 2452This is almost certainly a feature, 2453but if, in spite of the current recommendation of not using autokey, 2454you are 2455.B still 2456using autokey 2457.B and 2458you are seeing this sort of DoS attack 2459disabling this flag will delay 2460tearing down the association until the reachability counter 2461becomes zero. 2462You can check your 2463@code{peerstats} 2464file for evidence of any of these attacks. 2465The 2466default for this flag is 2467@code{enable}. 2468@item @code{unpeer_crypto_nak_early} 2469By default, if 2470@code{ntpd(1ntpdmdoc)} 2471receives a crypto-NAK packet that 2472passes the duplicate packet and origin timestamp checks 2473the association is immediately cleared. 2474While this is generally a feature 2475as it allows for quick recovery if a server key has changed, 2476a properly forged and appropriately delivered crypto-NAK packet 2477can be used in a DoS attack. 2478If you have active noticable problems with this type of DoS attack 2479then you should consider 2480disabling this option. 2481You can check your 2482@code{peerstats} 2483file for evidence of any of these attacks. 2484The 2485default for this flag is 2486@code{enable}. 2487@item @code{unpeer_digest_early} 2488By default, if 2489@code{ntpd(1ntpdmdoc)} 2490receives what should be an authenticated packet 2491that passes other packet sanity checks but 2492contains an invalid digest 2493the association is immediately cleared. 2494While this is generally a feature 2495as it allows for quick recovery, 2496if this type of packet is carefully forged and sent 2497during an appropriate window it can be used for a DoS attack. 2498If you have active noticable problems with this type of DoS attack 2499then you should consider 2500disabling this option. 2501You can check your 2502@code{peerstats} 2503file for evidence of any of these attacks. 2504The 2505default for this flag is 2506@code{enable}. 2507@end table 2508@item @code{includefile} @kbd{includefile} 2509This command allows additional configuration commands 2510to be included from a separate file. 2511Include files may 2512be nested to a depth of five; upon reaching the end of any 2513include file, command processing resumes in the previous 2514configuration file. 2515This option is useful for sites that run 2516@code{ntpd(1ntpdmdoc)} 2517on multiple hosts, with (mostly) common options (e.g., a 2518restriction list). 2519@item @code{leapsmearinterval} @kbd{seconds} 2520This EXPERIMENTAL option is only available if 2521@code{ntpd(1ntpdmdoc)} 2522was built with the 2523@code{--enable-leap-smear} 2524option to the 2525@code{configure} 2526script. 2527It specifies the interval over which a leap second correction will be applied. 2528Recommended values for this option are between 25297200 (2 hours) and 86400 (24 hours). 2530.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2531See http://bugs.ntp.org/2855 for more information. 2532@item @code{logconfig} @kbd{configkeyword} 2533This command controls the amount and type of output written to 2534the system 2535@code{syslog(3)} 2536facility or the alternate 2537@code{logfile} 2538log file. 2539By default, all output is turned on. 2540All 2541@kbd{configkeyword} 2542keywords can be prefixed with 2543@quoteleft{}=@quoteright{}, 2544@quoteleft{}+@quoteright{} 2545and 2546@quoteleft{}-@quoteright{}, 2547where 2548@quoteleft{}=@quoteright{} 2549sets the 2550@code{syslog(3)} 2551priority mask, 2552@quoteleft{}+@quoteright{} 2553adds and 2554@quoteleft{}-@quoteright{} 2555removes 2556messages. 2557@code{syslog(3)} 2558messages can be controlled in four 2559classes 2560(@code{clock}, @code{peer}, @code{sys} and @code{sync}). 2561Within these classes four types of messages can be 2562controlled: informational messages 2563(@code{info}), 2564event messages 2565(@code{events}), 2566statistics messages 2567(@code{statistics}) 2568and 2569status messages 2570(@code{status}). 2571 2572Configuration keywords are formed by concatenating the message class with 2573the event class. 2574The 2575@code{all} 2576prefix can be used instead of a message class. 2577A 2578message class may also be followed by the 2579@code{all} 2580keyword to enable/disable all 2581messages of the respective message class. 2582Thus, a minimal log configuration 2583could look like this: 2584@verbatim 2585logconfig =syncstatus +sysevents 2586@end verbatim 2587 2588This would just list the synchronizations state of 2589@code{ntpd(1ntpdmdoc)} 2590and the major system events. 2591For a simple reference server, the 2592following minimum message configuration could be useful: 2593@verbatim 2594logconfig =syncall +clockall 2595@end verbatim 2596 2597This configuration will list all clock information and 2598synchronization information. 2599All other events and messages about 2600peers, system events and so on is suppressed. 2601@item @code{logfile} @kbd{logfile} 2602This command specifies the location of an alternate log file to 2603be used instead of the default system 2604@code{syslog(3)} 2605facility. 2606This is the same operation as the 2607@code{-l} 2608command line option. 2609@item @code{setvar} @kbd{variable} @code{[@code{default}]} 2610This command adds an additional system variable. 2611These 2612variables can be used to distribute additional information such as 2613the access policy. 2614If the variable of the form 2615@code{name}@code{=}@kbd{value} 2616is followed by the 2617@code{default} 2618keyword, the 2619variable will be listed as part of the default system variables 2620(@code{rv} command)). 2621These additional variables serve 2622informational purposes only. 2623They are not related to the protocol 2624other that they can be listed. 2625The known protocol variables will 2626always override any variables defined via the 2627@code{setvar} 2628mechanism. 2629There are three special variables that contain the names 2630of all variable of the same group. 2631The 2632@code{sys_var_list} 2633holds 2634the names of all system variables. 2635The 2636@code{peer_var_list} 2637holds 2638the names of all peer variables and the 2639@code{clock_var_list} 2640holds the names of the reference clock variables. 2641@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}]} 2642This command can be used to alter several system variables in 2643very exceptional circumstances. 2644It should occur in the 2645configuration file before any other configuration options. 2646The 2647default values of these variables have been carefully optimized for 2648a wide range of network speeds and reliability expectations. 2649In 2650general, they interact in intricate ways that are hard to predict 2651and some combinations can result in some very nasty behavior. 2652Very 2653rarely is it necessary to change the default values; but, some 2654folks cannot resist twisting the knobs anyway and this command is 2655for them. 2656Emphasis added: twisters are on their own and can expect 2657no help from the support group. 2658 2659The variables operate as follows: 2660@table @asis 2661@item @code{allan} @kbd{allan} 2662The argument becomes the new value for the minimum Allan 2663intercept, which is a parameter of the PLL/FLL clock discipline 2664algorithm. 2665The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2666limit. 2667@item @code{dispersion} @kbd{dispersion} 2668The argument becomes the new value for the dispersion increase rate, 2669normally .000015 s/s. 2670@item @code{freq} @kbd{freq} 2671The argument becomes the initial value of the frequency offset in 2672parts-per-million. 2673This overrides the value in the frequency file, if 2674present, and avoids the initial training state if it is not. 2675@item @code{huffpuff} @kbd{huffpuff} 2676The argument becomes the new value for the experimental 2677huff-n'-puff filter span, which determines the most recent interval 2678the algorithm will search for a minimum delay. 2679The lower limit is 2680900 s (15 m), but a more reasonable value is 7200 (2 hours). 2681There 2682is no default, since the filter is not enabled unless this command 2683is given. 2684@item @code{panic} @kbd{panic} 2685The argument is the panic threshold, normally 1000 s. 2686If set to zero, 2687the panic sanity check is disabled and a clock offset of any value will 2688be accepted. 2689@item @code{step} @kbd{step} 2690The argument is the step threshold, which by default is 0.128 s. 2691It can 2692be set to any positive number in seconds. 2693If set to zero, step 2694adjustments will never occur. 2695Note: The kernel time discipline is 2696disabled if the step threshold is set to zero or greater than the 2697default. 2698@item @code{stepback} @kbd{stepback} 2699The argument is the step threshold for the backward direction, 2700which by default is 0.128 s. 2701It can 2702be set to any positive number in seconds. 2703If both the forward and backward step thresholds are set to zero, step 2704adjustments will never occur. 2705Note: The kernel time discipline is 2706disabled if 2707each direction of step threshold are either 2708set to zero or greater than .5 second. 2709@item @code{stepfwd} @kbd{stepfwd} 2710As for stepback, but for the forward direction. 2711@item @code{stepout} @kbd{stepout} 2712The argument is the stepout timeout, which by default is 900 s. 2713It can 2714be set to any positive number in seconds. 2715If set to zero, the stepout 2716pulses will not be suppressed. 2717@end table 2718@item @code{rlimit} @code{[@code{memlock} @kbd{Nmegabytes} | @code{stacksize} @kbd{N4kPages} @code{filenum} @kbd{Nfiledescriptors}]} 2719@table @asis 2720@item @code{memlock} @kbd{Nmegabytes} 2721Specify the number of megabytes of memory that should be 2722allocated and locked. 2723Probably only available under Linux, this option may be useful 2724when dropping root (the 2725@code{-i} 2726option). 2727The default is 32 megabytes on non-Linux machines, and -1 under Linux. 2728-1 means "do not lock the process into memory". 27290 means "lock whatever memory the process wants into memory". 2730@item @code{stacksize} @kbd{N4kPages} 2731Specifies the maximum size of the process stack on systems with the 2732@code{mlockall()} 2733function. 2734Defaults to 50 4k pages (200 4k pages in OpenBSD). 2735@item @code{filenum} @kbd{Nfiledescriptors} 2736Specifies the maximum number of file descriptors ntpd may have open at once. 2737Defaults to the system default. 2738@end table 2739@item @code{trap} @kbd{host_address} @code{[@code{port} @kbd{port_number}]} @code{[@code{interface} @kbd{interface_address}]} 2740This command configures a trap receiver at the given host 2741address and port number for sending messages with the specified 2742local interface address. 2743If the port number is unspecified, a value 2744of 18447 is used. 2745If the interface address is not specified, the 2746message is sent with a source address of the local interface the 2747message is sent through. 2748Note that on a multihomed host the 2749interface used may vary from time to time with routing changes. 2750 2751The trap receiver will generally log event messages and other 2752information from the server in a log file. 2753While such monitor 2754programs may also request their own trap dynamically, configuring a 2755trap receiver will ensure that no messages are lost when the server 2756is started. 2757@item @code{hop} @kbd{...} 2758This command specifies a list of TTL values in increasing order, up to 8 2759values can be specified. 2760In manycast mode these values are used in turn in 2761an expanding-ring search. 2762The default is eight multiples of 32 starting at 276331. 2764@end table 2765 2766This section was generated by @strong{AutoGen}, 2767using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program. 2768This software is released under the NTP license, <http://ntp.org/license>. 2769 2770@menu 2771* ntp.conf Files:: Files 2772* ntp.conf See Also:: See Also 2773* ntp.conf Bugs:: Bugs 2774* ntp.conf Notes:: Notes 2775@end menu 2776 2777@node ntp.conf Files 2778@subsection ntp.conf Files 2779@table @asis 2780@item @file{/etc/ntp.conf} 2781the default name of the configuration file 2782@item @file{ntp.keys} 2783private MD5 keys 2784@item @file{ntpkey} 2785RSA private key 2786@item @file{ntpkey_}@kbd{host} 2787RSA public key 2788@item @file{ntp_dh} 2789Diffie-Hellman agreement parameters 2790@end table 2791@node ntp.conf See Also 2792@subsection ntp.conf See Also 2793@code{ntpd(1ntpdmdoc)}, 2794@code{ntpdc(1ntpdcmdoc)}, 2795@code{ntpq(1ntpqmdoc)} 2796 2797In addition to the manual pages provided, 2798comprehensive documentation is available on the world wide web 2799at 2800@code{http://www.ntp.org/}. 2801A snapshot of this documentation is available in HTML format in 2802@file{/usr/share/doc/ntp}. 2803@* 2804 2805@* 2806David L. Mills, @emph{Network Time Protocol (Version 4)}, RFC5905 2807@node ntp.conf Bugs 2808@subsection ntp.conf Bugs 2809The syntax checking is not picky; some combinations of 2810ridiculous and even hilarious options and modes may not be 2811detected. 2812 2813The 2814@file{ntpkey_}@kbd{host} 2815files are really digital 2816certificates. 2817These should be obtained via secure directory 2818services when they become universally available. 2819@node ntp.conf Notes 2820@subsection ntp.conf Notes 2821This document was derived from FreeBSD. 2822