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