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