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