1.Dd June 23 2020 2.Dt NTP_CONF 5mdoc File Formats 3.Os 4.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) 5.\" 6.\" It has been AutoGen-ed June 23, 2020 at 02:20:27 AM by AutoGen 5.18.5 7.\" From the definitions ntp.conf.def 8.\" and the template file agmdoc-cmd.tpl 9.Sh NAME 10.Nm ntp.conf 11.Nd Network Time Protocol (NTP) daemon configuration file format 12.Sh SYNOPSIS 13.Nm 14.Op Fl \-option\-name 15.Op Fl \-option\-name Ar value 16.Pp 17All arguments must be options. 18.Pp 19.Sh DESCRIPTION 20The 21.Nm 22configuration file is read at initial startup by the 23.Xr ntpd 1ntpdmdoc 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 1ntpqmdoc 119or 120.Xr ntpdc 1ntpdcmdoc , 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 1ntpdmdoc 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 1ntpdcmdoc 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 1ntpqmdoc 607and 608.Xr ntpdc 1ntpdcmdoc 609utility programs. 610.Pp 611When 612.Xr ntpd 1ntpdmdoc 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 1ntpdcmdoc . 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 1ntpdcmdoc 633utility, while the 634.Ic controlkey 635command selects the key used as the password for the 636.Xr ntpq 1ntpqmdoc 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 1ntpqmdoc 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 1ntpqmdoc 843and 844.Xr ntpdc 1ntpdcmdoc 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 1ntpqmdoc 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 1ntpdmdoc , 968.Xr ntpq 1ntpqmdoc 969and 970.Xr ntpdc 1ntpdcmdoc 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 1ntpdcmdoc 983utility program, which uses a 984proprietary protocol specific to this implementation of 985.Xr ntpd 1ntpdmdoc . 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 1ntpqmdoc 1007and 1008.Xr ntpdc 1ntpdcmdoc 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 1ntpdmdoc 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 1ntpdcmdoc 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 1ntpdmdoc 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 1ntpdmdoc 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 1ntpdmdoc 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 1ntpdmdoc 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, while the 1529.Cm minimum 1530subcommand specifies the minimum packet spacing. 1531Packets that violate these minima are discarded 1532and a kiss\-o'\-death packet returned if enabled. 1533The default 1534minimum average and minimum are 5 and 2, respectively. 1535The 1536.Ic monitor 1537subcommand specifies the probability of discard 1538for packets that overflow the rate\-control window. 1539.It Xo Ic restrict address 1540.Op Cm mask Ar mask 1541.Op Cm ippeerlimit Ar int 1542.Op Ar flag ... 1543.Xc 1544The 1545.Ar address 1546argument expressed in 1547dotted\-quad form is the address of a host or network. 1548Alternatively, the 1549.Ar address 1550argument can be a valid host DNS name. 1551The 1552.Ar mask 1553argument expressed in dotted\-quad form defaults to 1554.Cm 255.255.255.255 , 1555meaning that the 1556.Ar address 1557is treated as the address of an individual host. 1558A default entry (address 1559.Cm 0.0.0.0 , 1560mask 1561.Cm 0.0.0.0 ) 1562is always included and is always the first entry in the list. 1563Note that text string 1564.Cm default , 1565with no mask option, may 1566be used to indicate the default entry. 1567The 1568.Cm ippeerlimit 1569directive limits the number of peer requests for each IP to 1570.Ar int , 1571where a value of \-1 means "unlimited", the current default. 1572A value of 0 means "none". 1573There would usually be at most 1 peering request per IP, 1574but if the remote peering requests are behind a proxy 1575there could well be more than 1 per IP. 1576In the current implementation, 1577.Cm flag 1578always 1579restricts access, i.e., an entry with no flags indicates that free 1580access to the server is to be given. 1581The flags are not orthogonal, 1582in that more restrictive flags will often make less restrictive 1583ones redundant. 1584The flags can generally be classed into two 1585categories, those which restrict time service and those which 1586restrict informational queries and attempts to do run\-time 1587reconfiguration of the server. 1588One or more of the following flags 1589may be specified: 1590.Bl -tag -width indent 1591.It Cm ignore 1592Deny packets of all kinds, including 1593.Xr ntpq 1ntpqmdoc 1594and 1595.Xr ntpdc 1ntpdcmdoc 1596queries. 1597.It Cm kod 1598If this flag is set when an access violation occurs, a kiss\-o'\-death 1599(KoD) packet is sent. 1600KoD packets are rate limited to no more than one 1601per second. 1602If another KoD packet occurs within one second after the 1603last one, the packet is dropped. 1604.It Cm limited 1605Deny service if the packet spacing violates the lower limits specified 1606in the 1607.Ic discard 1608command. 1609A history of clients is kept using the 1610monitoring capability of 1611.Xr ntpd 1ntpdmdoc . 1612Thus, monitoring is always active as 1613long as there is a restriction entry with the 1614.Cm limited 1615flag. 1616.It Cm lowpriotrap 1617Declare traps set by matching hosts to be low priority. 1618The 1619number of traps a server can maintain is limited (the current limit 1620is 3). 1621Traps are usually assigned on a first come, first served 1622basis, with later trap requestors being denied service. 1623This flag 1624modifies the assignment algorithm by allowing low priority traps to 1625be overridden by later requests for normal priority traps. 1626.It Cm noepeer 1627Deny ephemeral peer requests, 1628even if they come from an authenticated source. 1629Note that the ability to use a symmetric key for authentication may be restricted to 1630one or more IPs or subnets via the third field of the 1631.Pa ntp.keys 1632file. 1633This restriction is not enabled by default, 1634to maintain backward compatability. 1635Expect 1636.Cm noepeer 1637to become the default in ntp\-4.4. 1638.It Cm nomodify 1639Deny 1640.Xr ntpq 1ntpqmdoc 1641and 1642.Xr ntpdc 1ntpdcmdoc 1643queries which attempt to modify the state of the 1644server (i.e., run time reconfiguration). 1645Queries which return 1646information are permitted. 1647.It Cm noquery 1648Deny 1649.Xr ntpq 1ntpqmdoc 1650and 1651.Xr ntpdc 1ntpdcmdoc 1652queries. 1653Time service is not affected. 1654.It Cm nopeer 1655Deny unauthenticated packets which would result in mobilizing a new association. 1656This includes 1657broadcast and symmetric active packets 1658when a configured association does not exist. 1659It also includes 1660.Cm pool 1661associations, so if you want to use servers from a 1662.Cm pool 1663directive and also want to use 1664.Cm nopeer 1665by default, you'll want a 1666.Cm "restrict source ..." 1667line as well that does 1668.Em not 1669include the 1670.Cm nopeer 1671directive. 1672.It Cm noserve 1673Deny all packets except 1674.Xr ntpq 1ntpqmdoc 1675and 1676.Xr ntpdc 1ntpdcmdoc 1677queries. 1678.It Cm notrap 1679Decline to provide mode 6 control message trap service to matching 1680hosts. 1681The trap service is a subsystem of the 1682.Xr ntpq 1ntpqmdoc 1683control message 1684protocol which is intended for use by remote event logging programs. 1685.It Cm notrust 1686Deny service unless the packet is cryptographically authenticated. 1687.It Cm ntpport 1688This is actually a match algorithm modifier, rather than a 1689restriction flag. 1690Its presence causes the restriction entry to be 1691matched only if the source port in the packet is the standard NTP 1692UDP port (123). 1693Both 1694.Cm ntpport 1695and 1696.Cm non\-ntpport 1697may 1698be specified. 1699The 1700.Cm ntpport 1701is considered more specific and 1702is sorted later in the list. 1703.It Ic "serverresponse fuzz" 1704When reponding to server requests, 1705fuzz the low order bits of the 1706.Cm reftime . 1707.It Cm version 1708Deny packets that do not match the current NTP version. 1709.El 1710.Pp 1711Default restriction list entries with the flags ignore, interface, 1712ntpport, for each of the local host's interface addresses are 1713inserted into the table at startup to prevent the server 1714from attempting to synchronize to its own time. 1715A default entry is also always present, though if it is 1716otherwise unconfigured; no flags are associated 1717with the default entry (i.e., everything besides your own 1718NTP server is unrestricted). 1719.El 1720.Sh Automatic NTP Configuration Options 1721.Ss Manycasting 1722Manycasting is a automatic discovery and configuration paradigm 1723new to NTPv4. 1724It is intended as a means for a multicast client 1725to troll the nearby network neighborhood to find cooperating 1726manycast servers, validate them using cryptographic means 1727and evaluate their time values with respect to other servers 1728that might be lurking in the vicinity. 1729The intended result is that each manycast client mobilizes 1730client associations with some number of the "best" 1731of the nearby manycast servers, yet automatically reconfigures 1732to sustain this number of servers should one or another fail. 1733.Pp 1734Note that the manycasting paradigm does not coincide 1735with the anycast paradigm described in RFC\-1546, 1736which is designed to find a single server from a clique 1737of servers providing the same service. 1738The manycast paradigm is designed to find a plurality 1739of redundant servers satisfying defined optimality criteria. 1740.Pp 1741Manycasting can be used with either symmetric key 1742or public key cryptography. 1743The public key infrastructure (PKI) 1744offers the best protection against compromised keys 1745and is generally considered stronger, at least with relatively 1746large key sizes. 1747It is implemented using the Autokey protocol and 1748the OpenSSL cryptographic library available from 1749.Li http://www.openssl.org/ . 1750The library can also be used with other NTPv4 modes 1751as well and is highly recommended, especially for broadcast modes. 1752.Pp 1753A persistent manycast client association is configured 1754using the 1755.Ic manycastclient 1756command, which is similar to the 1757.Ic server 1758command but with a multicast (IPv4 class 1759.Cm D 1760or IPv6 prefix 1761.Cm FF ) 1762group address. 1763The IANA has designated IPv4 address 224.1.1.1 1764and IPv6 address FF05::101 (site local) for NTP. 1765When more servers are needed, it broadcasts manycast 1766client messages to this address at the minimum feasible rate 1767and minimum feasible time\-to\-live (TTL) hops, depending 1768on how many servers have already been found. 1769There can be as many manycast client associations 1770as different group address, each one serving as a template 1771for a future ephemeral unicast client/server association. 1772.Pp 1773Manycast servers configured with the 1774.Ic manycastserver 1775command listen on the specified group address for manycast 1776client messages. 1777Note the distinction between manycast client, 1778which actively broadcasts messages, and manycast server, 1779which passively responds to them. 1780If a manycast server is 1781in scope of the current TTL and is itself synchronized 1782to a valid source and operating at a stratum level equal 1783to or lower than the manycast client, it replies to the 1784manycast client message with an ordinary unicast server message. 1785.Pp 1786The manycast client receiving this message mobilizes 1787an ephemeral client/server association according to the 1788matching manycast client template, but only if cryptographically 1789authenticated and the server stratum is less than or equal 1790to the client stratum. 1791Authentication is explicitly required 1792and either symmetric key or public key (Autokey) can be used. 1793Then, the client polls the server at its unicast address 1794in burst mode in order to reliably set the host clock 1795and validate the source. 1796This normally results 1797in a volley of eight client/server at 2\-s intervals 1798during which both the synchronization and cryptographic 1799protocols run concurrently. 1800Following the volley, 1801the client runs the NTP intersection and clustering 1802algorithms, which act to discard all but the "best" 1803associations according to stratum and synchronization 1804distance. 1805The surviving associations then continue 1806in ordinary client/server mode. 1807.Pp 1808The manycast client polling strategy is designed to reduce 1809as much as possible the volume of manycast client messages 1810and the effects of implosion due to near\-simultaneous 1811arrival of manycast server messages. 1812The strategy is determined by the 1813.Ic manycastclient , 1814.Ic tos 1815and 1816.Ic ttl 1817configuration commands. 1818The manycast poll interval is 1819normally eight times the system poll interval, 1820which starts out at the 1821.Cm minpoll 1822value specified in the 1823.Ic manycastclient , 1824command and, under normal circumstances, increments to the 1825.Cm maxpolll 1826value specified in this command. 1827Initially, the TTL is 1828set at the minimum hops specified by the 1829.Ic ttl 1830command. 1831At each retransmission the TTL is increased until reaching 1832the maximum hops specified by this command or a sufficient 1833number client associations have been found. 1834Further retransmissions use the same TTL. 1835.Pp 1836The quality and reliability of the suite of associations 1837discovered by the manycast client is determined by the NTP 1838mitigation algorithms and the 1839.Cm minclock 1840and 1841.Cm minsane 1842values specified in the 1843.Ic tos 1844configuration command. 1845At least 1846.Cm minsane 1847candidate servers must be available and the mitigation 1848algorithms produce at least 1849.Cm minclock 1850survivors in order to synchronize the clock. 1851Byzantine agreement principles require at least four 1852candidates in order to correctly discard a single falseticker. 1853For legacy purposes, 1854.Cm minsane 1855defaults to 1 and 1856.Cm minclock 1857defaults to 3. 1858For manycast service 1859.Cm minsane 1860should be explicitly set to 4, assuming at least that 1861number of servers are available. 1862.Pp 1863If at least 1864.Cm minclock 1865servers are found, the manycast poll interval is immediately 1866set to eight times 1867.Cm maxpoll . 1868If less than 1869.Cm minclock 1870servers are found when the TTL has reached the maximum hops, 1871the manycast poll interval is doubled. 1872For each transmission 1873after that, the poll interval is doubled again until 1874reaching the maximum of eight times 1875.Cm maxpoll . 1876Further transmissions use the same poll interval and 1877TTL values. 1878Note that while all this is going on, 1879each client/server association found is operating normally 1880it the system poll interval. 1881.Pp 1882Administratively scoped multicast boundaries are normally 1883specified by the network router configuration and, 1884in the case of IPv6, the link/site scope prefix. 1885By default, the increment for TTL hops is 32 starting 1886from 31; however, the 1887.Ic ttl 1888configuration command can be 1889used to modify the values to match the scope rules. 1890.Pp 1891It is often useful to narrow the range of acceptable 1892servers which can be found by manycast client associations. 1893Because manycast servers respond only when the client 1894stratum is equal to or greater than the server stratum, 1895primary (stratum 1) servers fill find only primary servers 1896in TTL range, which is probably the most common objective. 1897However, unless configured otherwise, all manycast clients 1898in TTL range will eventually find all primary servers 1899in TTL range, which is probably not the most common 1900objective in large networks. 1901The 1902.Ic tos 1903command can be used to modify this behavior. 1904Servers with stratum below 1905.Cm floor 1906or above 1907.Cm ceiling 1908specified in the 1909.Ic tos 1910command are strongly discouraged during the selection 1911process; however, these servers may be temporally 1912accepted if the number of servers within TTL range is 1913less than 1914.Cm minclock . 1915.Pp 1916The above actions occur for each manycast client message, 1917which repeats at the designated poll interval. 1918However, once the ephemeral client association is mobilized, 1919subsequent manycast server replies are discarded, 1920since that would result in a duplicate association. 1921If during a poll interval the number of client associations 1922falls below 1923.Cm minclock , 1924all manycast client prototype associations are reset 1925to the initial poll interval and TTL hops and operation 1926resumes from the beginning. 1927It is important to avoid 1928frequent manycast client messages, since each one requires 1929all manycast servers in TTL range to respond. 1930The result could well be an implosion, either minor or major, 1931depending on the number of servers in range. 1932The recommended value for 1933.Cm maxpoll 1934is 12 (4,096 s). 1935.Pp 1936It is possible and frequently useful to configure a host 1937as both manycast client and manycast server. 1938A number of hosts configured this way and sharing a common 1939group address will automatically organize themselves 1940in an optimum configuration based on stratum and 1941synchronization distance. 1942For example, consider an NTP 1943subnet of two primary servers and a hundred or more 1944dependent clients. 1945With two exceptions, all servers 1946and clients have identical configuration files including both 1947.Ic multicastclient 1948and 1949.Ic multicastserver 1950commands using, for instance, multicast group address 1951239.1.1.1. 1952The only exception is that each primary server 1953configuration file must include commands for the primary 1954reference source such as a GPS receiver. 1955.Pp 1956The remaining configuration files for all secondary 1957servers and clients have the same contents, except for the 1958.Ic tos 1959command, which is specific for each stratum level. 1960For stratum 1 and stratum 2 servers, that command is 1961not necessary. 1962For stratum 3 and above servers the 1963.Cm floor 1964value is set to the intended stratum number. 1965Thus, all stratum 3 configuration files are identical, 1966all stratum 4 files are identical and so forth. 1967.Pp 1968Once operations have stabilized in this scenario, 1969the primary servers will find the primary reference source 1970and each other, since they both operate at the same 1971stratum (1), but not with any secondary server or client, 1972since these operate at a higher stratum. 1973The secondary 1974servers will find the servers at the same stratum level. 1975If one of the primary servers loses its GPS receiver, 1976it will continue to operate as a client and other clients 1977will time out the corresponding association and 1978re\-associate accordingly. 1979.Pp 1980Some administrators prefer to avoid running 1981.Xr ntpd 1ntpdmdoc 1982continuously and run either 1983.Xr sntp 1sntpmdoc 1984or 1985.Xr ntpd 1ntpdmdoc 1986.Fl q 1987as a cron job. 1988In either case the servers must be 1989configured in advance and the program fails if none are 1990available when the cron job runs. 1991A really slick 1992application of manycast is with 1993.Xr ntpd 1ntpdmdoc 1994.Fl q . 1995The program wakes up, scans the local landscape looking 1996for the usual suspects, selects the best from among 1997the rascals, sets the clock and then departs. 1998Servers do not have to be configured in advance and 1999all clients throughout the network can have the same 2000configuration file. 2001.Ss Manycast Interactions with Autokey 2002Each time a manycast client sends a client mode packet 2003to a multicast group address, all manycast servers 2004in scope generate a reply including the host name 2005and status word. 2006The manycast clients then run 2007the Autokey protocol, which collects and verifies 2008all certificates involved. 2009Following the burst interval 2010all but three survivors are cast off, 2011but the certificates remain in the local cache. 2012It often happens that several complete signing trails 2013from the client to the primary servers are collected in this way. 2014.Pp 2015About once an hour or less often if the poll interval 2016exceeds this, the client regenerates the Autokey key list. 2017This is in general transparent in client/server mode. 2018However, about once per day the server private value 2019used to generate cookies is refreshed along with all 2020manycast client associations. 2021In this case all 2022cryptographic values including certificates is refreshed. 2023If a new certificate has been generated since 2024the last refresh epoch, it will automatically revoke 2025all prior certificates that happen to be in the 2026certificate cache. 2027At the same time, the manycast 2028scheme starts all over from the beginning and 2029the expanding ring shrinks to the minimum and increments 2030from there while collecting all servers in scope. 2031.Ss Broadcast Options 2032.Bl -tag -width indent 2033.It Xo Ic tos 2034.Oo 2035.Cm bcpollbstep Ar gate 2036.Oc 2037.Xc 2038This command provides a way to delay, 2039by the specified number of broadcast poll intervals, 2040believing backward time steps from a broadcast server. 2041Broadcast time networks are expected to be trusted. 2042In the event a broadcast server's time is stepped backwards, 2043there is clear benefit to having the clients notice this change 2044as soon as possible. 2045Attacks such as replay attacks can happen, however, 2046and even though there are a number of protections built in to 2047broadcast mode, attempts to perform a replay attack are possible. 2048This value defaults to 0, but can be changed 2049to any number of poll intervals between 0 and 4. 2050.El 2051.Ss Manycast Options 2052.Bl -tag -width indent 2053.It Xo Ic tos 2054.Oo 2055.Cm ceiling Ar ceiling | 2056.Cm cohort { 0 | 1 } | 2057.Cm floor Ar floor | 2058.Cm minclock Ar minclock | 2059.Cm minsane Ar minsane 2060.Oc 2061.Xc 2062This command affects the clock selection and clustering 2063algorithms. 2064It can be used to select the quality and 2065quantity of peers used to synchronize the system clock 2066and is most useful in manycast mode. 2067The variables operate 2068as follows: 2069.Bl -tag -width indent 2070.It Cm ceiling Ar ceiling 2071Peers with strata above 2072.Cm ceiling 2073will be discarded if there are at least 2074.Cm minclock 2075peers remaining. 2076This value defaults to 15, but can be changed 2077to any number from 1 to 15. 2078.It Cm cohort Bro 0 | 1 Brc 2079This is a binary flag which enables (0) or disables (1) 2080manycast server replies to manycast clients with the same 2081stratum level. 2082This is useful to reduce implosions where 2083large numbers of clients with the same stratum level 2084are present. 2085The default is to enable these replies. 2086.It Cm floor Ar floor 2087Peers with strata below 2088.Cm floor 2089will be discarded if there are at least 2090.Cm minclock 2091peers remaining. 2092This value defaults to 1, but can be changed 2093to any number from 1 to 15. 2094.It Cm minclock Ar minclock 2095The clustering algorithm repeatedly casts out outlier 2096associations until no more than 2097.Cm minclock 2098associations remain. 2099This value defaults to 3, 2100but can be changed to any number from 1 to the number of 2101configured sources. 2102.It Cm minsane Ar minsane 2103This is the minimum number of candidates available 2104to the clock selection algorithm in order to produce 2105one or more truechimers for the clustering algorithm. 2106If fewer than this number are available, the clock is 2107undisciplined and allowed to run free. 2108The default is 1 2109for legacy purposes. 2110However, according to principles of 2111Byzantine agreement, 2112.Cm minsane 2113should be at least 4 in order to detect and discard 2114a single falseticker. 2115.El 2116.It Cm ttl Ar hop ... 2117This command specifies a list of TTL values in increasing 2118order, up to 8 values can be specified. 2119In manycast mode these values are used in turn 2120in an expanding\-ring search. 2121The default is eight 2122multiples of 32 starting at 31. 2123.El 2124.Sh Reference Clock Support 2125The NTP Version 4 daemon supports some three dozen different radio, 2126satellite and modem reference clocks plus a special pseudo\-clock 2127used for backup or when no other clock source is available. 2128Detailed descriptions of individual device drivers and options can 2129be found in the 2130.Qq Reference Clock Drivers 2131page 2132(available as part of the HTML documentation 2133provided in 2134.Pa /usr/share/doc/ntp ) . 2135Additional information can be found in the pages linked 2136there, including the 2137.Qq Debugging Hints for Reference Clock Drivers 2138and 2139.Qq How To Write a Reference Clock Driver 2140pages 2141(available as part of the HTML documentation 2142provided in 2143.Pa /usr/share/doc/ntp ) . 2144In addition, support for a PPS 2145signal is available as described in the 2146.Qq Pulse\-per\-second (PPS) Signal Interfacing 2147page 2148(available as part of the HTML documentation 2149provided in 2150.Pa /usr/share/doc/ntp ) . 2151Many 2152drivers support special line discipline/streams modules which can 2153significantly improve the accuracy using the driver. 2154These are 2155described in the 2156.Qq Line Disciplines and Streams Drivers 2157page 2158(available as part of the HTML documentation 2159provided in 2160.Pa /usr/share/doc/ntp ) . 2161.Pp 2162A reference clock will generally (though not always) be a radio 2163timecode receiver which is synchronized to a source of standard 2164time such as the services offered by the NRC in Canada and NIST and 2165USNO in the US. 2166The interface between the computer and the timecode 2167receiver is device dependent, but is usually a serial port. 2168A 2169device driver specific to each reference clock must be selected and 2170compiled in the distribution; however, most common radio, satellite 2171and modem clocks are included by default. 2172Note that an attempt to 2173configure a reference clock when the driver has not been compiled 2174or the hardware port has not been appropriately configured results 2175in a scalding remark to the system log file, but is otherwise non 2176hazardous. 2177.Pp 2178For the purposes of configuration, 2179.Xr ntpd 1ntpdmdoc 2180treats 2181reference clocks in a manner analogous to normal NTP peers as much 2182as possible. 2183Reference clocks are identified by a syntactically 2184correct but invalid IP address, in order to distinguish them from 2185normal NTP peers. 2186Reference clock addresses are of the form 2187.Sm off 2188.Li 127.127. Ar t . Ar u , 2189.Sm on 2190where 2191.Ar t 2192is an integer 2193denoting the clock type and 2194.Ar u 2195indicates the unit 2196number in the range 0\-3. 2197While it may seem overkill, it is in fact 2198sometimes useful to configure multiple reference clocks of the same 2199type, in which case the unit numbers must be unique. 2200.Pp 2201The 2202.Ic server 2203command is used to configure a reference 2204clock, where the 2205.Ar address 2206argument in that command 2207is the clock address. 2208The 2209.Cm key , 2210.Cm version 2211and 2212.Cm ttl 2213options are not used for reference clock support. 2214The 2215.Cm mode 2216option is added for reference clock support, as 2217described below. 2218The 2219.Cm prefer 2220option can be useful to 2221persuade the server to cherish a reference clock with somewhat more 2222enthusiasm than other reference clocks or peers. 2223Further 2224information on this option can be found in the 2225.Qq Mitigation Rules and the prefer Keyword 2226(available as part of the HTML documentation 2227provided in 2228.Pa /usr/share/doc/ntp ) 2229page. 2230The 2231.Cm minpoll 2232and 2233.Cm maxpoll 2234options have 2235meaning only for selected clock drivers. 2236See the individual clock 2237driver document pages for additional information. 2238.Pp 2239The 2240.Ic fudge 2241command is used to provide additional 2242information for individual clock drivers and normally follows 2243immediately after the 2244.Ic server 2245command. 2246The 2247.Ar address 2248argument specifies the clock address. 2249The 2250.Cm refid 2251and 2252.Cm stratum 2253options can be used to 2254override the defaults for the device. 2255There are two optional 2256device\-dependent time offsets and four flags that can be included 2257in the 2258.Ic fudge 2259command as well. 2260.Pp 2261The stratum number of a reference clock is by default zero. 2262Since the 2263.Xr ntpd 1ntpdmdoc 2264daemon adds one to the stratum of each 2265peer, a primary server ordinarily displays an external stratum of 2266one. 2267In order to provide engineered backups, it is often useful to 2268specify the reference clock stratum as greater than zero. 2269The 2270.Cm stratum 2271option is used for this purpose. 2272Also, in cases 2273involving both a reference clock and a pulse\-per\-second (PPS) 2274discipline signal, it is useful to specify the reference clock 2275identifier as other than the default, depending on the driver. 2276The 2277.Cm refid 2278option is used for this purpose. 2279Except where noted, 2280these options apply to all clock drivers. 2281.Ss Reference Clock Commands 2282.Bl -tag -width indent 2283.It Xo Ic server 2284.Sm off 2285.Li 127.127. Ar t . Ar u 2286.Sm on 2287.Op Cm prefer 2288.Op Cm mode Ar int 2289.Op Cm minpoll Ar int 2290.Op Cm maxpoll Ar int 2291.Xc 2292This command can be used to configure reference clocks in 2293special ways. 2294The options are interpreted as follows: 2295.Bl -tag -width indent 2296.It Cm prefer 2297Marks the reference clock as preferred. 2298All other things being 2299equal, this host will be chosen for synchronization among a set of 2300correctly operating hosts. 2301See the 2302.Qq Mitigation Rules and the prefer Keyword 2303page 2304(available as part of the HTML documentation 2305provided in 2306.Pa /usr/share/doc/ntp ) 2307for further information. 2308.It Cm mode Ar int 2309Specifies a mode number which is interpreted in a 2310device\-specific fashion. 2311For instance, it selects a dialing 2312protocol in the ACTS driver and a device subtype in the 2313parse 2314drivers. 2315.It Cm minpoll Ar int 2316.It Cm maxpoll Ar int 2317These options specify the minimum and maximum polling interval 2318for reference clock messages, as a power of 2 in seconds 2319For 2320most directly connected reference clocks, both 2321.Cm minpoll 2322and 2323.Cm maxpoll 2324default to 6 (64 s). 2325For modem reference clocks, 2326.Cm minpoll 2327defaults to 10 (17.1 m) and 2328.Cm maxpoll 2329defaults to 14 (4.5 h). 2330The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2331.El 2332.It Xo Ic fudge 2333.Sm off 2334.Li 127.127. Ar t . Ar u 2335.Sm on 2336.Op Cm time1 Ar sec 2337.Op Cm time2 Ar sec 2338.Op Cm stratum Ar int 2339.Op Cm refid Ar string 2340.Op Cm mode Ar int 2341.Op Cm flag1 Cm 0 \&| Cm 1 2342.Op Cm flag2 Cm 0 \&| Cm 1 2343.Op Cm flag3 Cm 0 \&| Cm 1 2344.Op Cm flag4 Cm 0 \&| Cm 1 2345.Xc 2346This command can be used to configure reference clocks in 2347special ways. 2348It must immediately follow the 2349.Ic server 2350command which configures the driver. 2351Note that the same capability 2352is possible at run time using the 2353.Xr ntpdc 1ntpdcmdoc 2354program. 2355The options are interpreted as 2356follows: 2357.Bl -tag -width indent 2358.It Cm time1 Ar sec 2359Specifies a constant to be added to the time offset produced by 2360the driver, a fixed\-point decimal number in seconds. 2361This is used 2362as a calibration constant to adjust the nominal time offset of a 2363particular clock to agree with an external standard, such as a 2364precision PPS signal. 2365It also provides a way to correct a 2366systematic error or bias due to serial port or operating system 2367latencies, different cable lengths or receiver internal delay. 2368The 2369specified offset is in addition to the propagation delay provided 2370by other means, such as internal DIPswitches. 2371Where a calibration 2372for an individual system and driver is available, an approximate 2373correction is noted in the driver documentation pages. 2374Note: in order to facilitate calibration when more than one 2375radio clock or PPS signal is supported, a special calibration 2376feature is available. 2377It takes the form of an argument to the 2378.Ic enable 2379command described in 2380.Sx Miscellaneous Options 2381page and operates as described in the 2382.Qq Reference Clock Drivers 2383page 2384(available as part of the HTML documentation 2385provided in 2386.Pa /usr/share/doc/ntp ) . 2387.It Cm time2 Ar secs 2388Specifies a fixed\-point decimal number in seconds, which is 2389interpreted in a driver\-dependent way. 2390See the descriptions of 2391specific drivers 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 stratum Ar int 2398Specifies the stratum number assigned to the driver, an integer 2399between 0 and 15. 2400This number overrides the default stratum number 2401ordinarily assigned by the driver itself, usually zero. 2402.It Cm refid Ar string 2403Specifies an ASCII string of from one to four characters which 2404defines the reference identifier used by the driver. 2405This string 2406overrides the default identifier ordinarily assigned by the driver 2407itself. 2408.It Cm mode Ar int 2409Specifies a mode number which is interpreted in a 2410device\-specific fashion. 2411For instance, it selects a dialing 2412protocol in the ACTS driver and a device subtype in the 2413parse 2414drivers. 2415.It Cm flag1 Cm 0 \&| Cm 1 2416.It Cm flag2 Cm 0 \&| Cm 1 2417.It Cm flag3 Cm 0 \&| Cm 1 2418.It Cm flag4 Cm 0 \&| Cm 1 2419These four flags are used for customizing the clock driver. 2420The 2421interpretation of these values, and whether they are used at all, 2422is a function of the particular clock driver. 2423However, by 2424convention 2425.Cm flag4 2426is used to enable recording monitoring 2427data to the 2428.Cm clockstats 2429file configured with the 2430.Ic filegen 2431command. 2432Further information on the 2433.Ic filegen 2434command can be found in 2435.Sx Monitoring Options . 2436.El 2437.El 2438.Sh Miscellaneous Options 2439.Bl -tag -width indent 2440.It Ic broadcastdelay Ar seconds 2441The broadcast and multicast modes require a special calibration 2442to determine the network delay between the local and remote 2443servers. 2444Ordinarily, this is done automatically by the initial 2445protocol exchanges between the client and server. 2446In some cases, 2447the calibration procedure may fail due to network or server access 2448controls, for example. 2449This command specifies the default delay to 2450be used under these circumstances. 2451Typically (for Ethernet), a 2452number between 0.003 and 0.007 seconds is appropriate. 2453The default 2454when this command is not used is 0.004 seconds. 2455.It Ic calldelay Ar delay 2456This option controls the delay in seconds between the first and second 2457packets sent in burst or iburst mode to allow additional time for a modem 2458or ISDN call to complete. 2459.It Ic driftfile Ar driftfile 2460This command specifies the complete path and name of the file used to 2461record the frequency of the local clock oscillator. 2462This is the same 2463operation as the 2464.Fl f 2465command line option. 2466If the file exists, it is read at 2467startup in order to set the initial frequency and then updated once per 2468hour with the current frequency computed by the daemon. 2469If the file name is 2470specified, but the file itself does not exist, the starts with an initial 2471frequency of zero and creates the file when writing it for the first time. 2472If this command is not given, the daemon will always start with an initial 2473frequency of zero. 2474.Pp 2475The file format consists of a single line containing a single 2476floating point number, which records the frequency offset measured 2477in parts\-per\-million (PPM). 2478The file is updated by first writing 2479the current drift value into a temporary file and then renaming 2480this file to replace the old version. 2481This implies that 2482.Xr ntpd 1ntpdmdoc 2483must have write permission for the directory the 2484drift file is located in, and that file system links, symbolic or 2485otherwise, should be avoided. 2486.It Ic dscp Ar value 2487This option specifies the Differentiated Services Control Point (DSCP) value, 2488a 6\-bit code. 2489The default value is 46, signifying Expedited Forwarding. 2490.It Xo Ic enable 2491.Oo 2492.Cm auth | Cm bclient | 2493.Cm calibrate | Cm kernel | 2494.Cm mode7 | Cm monitor | 2495.Cm ntp | Cm stats | 2496.Cm peer_clear_digest_early | 2497.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early 2498.Oc 2499.Xc 2500.It Xo Ic disable 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 2510Provides a way to enable or disable various server options. 2511Flags not mentioned are unaffected. 2512Note that all of these flags 2513can be controlled remotely using the 2514.Xr ntpdc 1ntpdcmdoc 2515utility program. 2516.Bl -tag -width indent 2517.It Cm auth 2518Enables the server to synchronize with unconfigured peers only if the 2519peer has been correctly authenticated using either public key or 2520private key cryptography. 2521The default for this flag is 2522.Ic enable . 2523.It Cm bclient 2524Enables the server to listen for a message from a broadcast or 2525multicast server, as in the 2526.Ic multicastclient 2527command with default 2528address. 2529The default for this flag is 2530.Ic disable . 2531.It Cm calibrate 2532Enables the calibrate feature for reference clocks. 2533The default for 2534this flag is 2535.Ic disable . 2536.It Cm kernel 2537Enables the kernel time discipline, if available. 2538The default for this 2539flag is 2540.Ic enable 2541if support is available, otherwise 2542.Ic disable . 2543.It Cm mode7 2544Enables processing of NTP mode 7 implementation\-specific requests 2545which are used by the deprecated 2546.Xr ntpdc 1ntpdcmdoc 2547program. 2548The default for this flag is disable. 2549This flag is excluded from runtime configuration using 2550.Xr ntpq 1ntpqmdoc . 2551The 2552.Xr ntpq 1ntpqmdoc 2553program provides the same capabilities as 2554.Xr ntpdc 1ntpdcmdoc 2555using standard mode 6 requests. 2556.It Cm monitor 2557Enables the monitoring facility. 2558See the 2559.Xr ntpdc 1ntpdcmdoc 2560program 2561and the 2562.Ic monlist 2563command or further information. 2564The 2565default for this flag is 2566.Ic enable . 2567.It Cm ntp 2568Enables time and frequency discipline. 2569In effect, this switch opens and 2570closes the feedback loop, which is useful for testing. 2571The default for 2572this flag is 2573.Ic enable . 2574.It Cm peer_clear_digest_early 2575By default, if 2576.Xr ntpd 1ntpdmdoc 2577is using autokey and it 2578receives a crypto\-NAK packet that 2579passes the duplicate packet and origin timestamp checks 2580the peer variables are immediately cleared. 2581While this is generally a feature 2582as it allows for quick recovery if a server key has changed, 2583a properly forged and appropriately delivered crypto\-NAK packet 2584can be used in a DoS attack. 2585If you have active noticable problems with this type of DoS attack 2586then you should consider 2587disabling this option. 2588You can check your 2589.Cm peerstats 2590file for evidence of any of these attacks. 2591The 2592default for this flag is 2593.Ic enable . 2594.It Cm stats 2595Enables the statistics facility. 2596See the 2597.Sx Monitoring Options 2598section for further information. 2599The default for this flag is 2600.Ic disable . 2601.It Cm unpeer_crypto_early 2602By default, if 2603.Xr ntpd 1ntpdmdoc 2604receives an autokey packet that fails TEST9, 2605a crypto failure, 2606the association is immediately cleared. 2607This is almost certainly a feature, 2608but if, in spite of the current recommendation of not using autokey, 2609you are 2610.B still 2611using autokey 2612.B and 2613you are seeing this sort of DoS attack 2614disabling this flag will delay 2615tearing down the association until the reachability counter 2616becomes zero. 2617You can check your 2618.Cm peerstats 2619file for evidence of any of these attacks. 2620The 2621default for this flag is 2622.Ic enable . 2623.It Cm unpeer_crypto_nak_early 2624By default, if 2625.Xr ntpd 1ntpdmdoc 2626receives a crypto\-NAK packet that 2627passes the duplicate packet and origin timestamp checks 2628the association is immediately cleared. 2629While this is generally a feature 2630as it allows for quick recovery if a server key has changed, 2631a properly forged and appropriately delivered crypto\-NAK packet 2632can be used in a DoS attack. 2633If you have active noticable problems with this type of DoS attack 2634then you should consider 2635disabling this option. 2636You can check your 2637.Cm peerstats 2638file for evidence of any of these attacks. 2639The 2640default for this flag is 2641.Ic enable . 2642.It Cm unpeer_digest_early 2643By default, if 2644.Xr ntpd 1ntpdmdoc 2645receives what should be an authenticated packet 2646that passes other packet sanity checks but 2647contains an invalid digest 2648the association is immediately cleared. 2649While this is generally a feature 2650as it allows for quick recovery, 2651if this type of packet is carefully forged and sent 2652during an appropriate window it can be used for a DoS attack. 2653If you have active noticable problems with this type of DoS attack 2654then you should consider 2655disabling this option. 2656You can check your 2657.Cm peerstats 2658file for evidence of any of these attacks. 2659The 2660default for this flag is 2661.Ic enable . 2662.El 2663.It Ic includefile Ar includefile 2664This command allows additional configuration commands 2665to be included from a separate file. 2666Include files may 2667be nested to a depth of five; upon reaching the end of any 2668include file, command processing resumes in the previous 2669configuration file. 2670This option is useful for sites that run 2671.Xr ntpd 1ntpdmdoc 2672on multiple hosts, with (mostly) common options (e.g., a 2673restriction list). 2674.It Xo Ic interface 2675.Oo 2676.Cm listen | Cm ignore | Cm drop 2677.Oc 2678.Oo 2679.Cm all | Cm ipv4 | Cm ipv6 | Cm wildcard 2680.Ar name | Ar address 2681.Oo Cm / Ar prefixlen 2682.Oc 2683.Oc 2684.Xc 2685The 2686.Cm interface 2687directive controls which network addresses 2688.Xr ntpd 1ntpdmdoc 2689opens, and whether input is dropped without processing. 2690The first parameter determines the action for addresses 2691which match the second parameter. 2692The second parameter specifies a class of addresses, 2693or a specific interface name, 2694or an address. 2695In the address case, 2696.Ar prefixlen 2697determines how many bits must match for this rule to apply. 2698.Cm ignore 2699prevents opening matching addresses, 2700.Cm drop 2701causes 2702.Xr ntpd 1ntpdmdoc 2703to open the address and drop all received packets without examination. 2704Multiple 2705.Cm interface 2706directives can be used. 2707The last rule which matches a particular address determines the action for it. 2708.Cm interface 2709directives are disabled if any 2710.Fl I , 2711.Fl \-interface , 2712.Fl L , 2713or 2714.Fl \-novirtualips 2715command\-line options are specified in the configuration file, 2716all available network addresses are opened. 2717The 2718.Cm nic 2719directive is an alias for 2720.Cm interface . 2721.It Ic leapfile Ar leapfile 2722This command loads the IERS leapseconds file and initializes the 2723leapsecond values for the next leapsecond event, leapfile expiration 2724time, and TAI offset. 2725The file can be obtained directly from the IERS at 2726.Li https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list 2727or 2728.Li ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap\-seconds.list . 2729The 2730.Cm leapfile 2731is scanned when 2732.Xr ntpd 1ntpdmdoc 2733processes the 2734.Cm leapfile directive or when 2735.Cm ntpd detects that the 2736.Ar leapfile 2737has changed. 2738.Cm ntpd 2739checks once a day to see if the 2740.Ar leapfile 2741has changed. 2742The 2743.Xr update\-leap 1update_leapmdoc 2744script can be run to see if the 2745.Ar leapfile 2746should be updated. 2747.It Ic leapsmearinterval Ar seconds 2748This EXPERIMENTAL option is only available if 2749.Xr ntpd 1ntpdmdoc 2750was built with the 2751.Cm \-\-enable\-leap\-smear 2752option to the 2753.Cm configure 2754script. 2755It specifies the interval over which a leap second correction will be applied. 2756Recommended values for this option are between 27577200 (2 hours) and 86400 (24 hours). 2758.Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS! 2759See http://bugs.ntp.org/2855 for more information. 2760.It Ic logconfig Ar configkeyword 2761This command controls the amount and type of output written to 2762the system 2763.Xr syslog 3 2764facility or the alternate 2765.Ic logfile 2766log file. 2767By default, all output is turned on. 2768All 2769.Ar configkeyword 2770keywords can be prefixed with 2771.Ql = , 2772.Ql + 2773and 2774.Ql \- , 2775where 2776.Ql = 2777sets the 2778.Xr syslog 3 2779priority mask, 2780.Ql + 2781adds and 2782.Ql \- 2783removes 2784messages. 2785.Xr syslog 3 2786messages can be controlled in four 2787classes 2788.Po 2789.Cm clock , 2790.Cm peer , 2791.Cm sys 2792and 2793.Cm sync 2794.Pc . 2795Within these classes four types of messages can be 2796controlled: informational messages 2797.Po 2798.Cm info 2799.Pc , 2800event messages 2801.Po 2802.Cm events 2803.Pc , 2804statistics messages 2805.Po 2806.Cm statistics 2807.Pc 2808and 2809status messages 2810.Po 2811.Cm status 2812.Pc . 2813.Pp 2814Configuration keywords are formed by concatenating the message class with 2815the event class. 2816The 2817.Cm all 2818prefix can be used instead of a message class. 2819A 2820message class may also be followed by the 2821.Cm all 2822keyword to enable/disable all 2823messages of the respective message class. 2824Thus, a minimal log configuration 2825could look like this: 2826.Bd -literal 2827logconfig =syncstatus +sysevents 2828.Ed 2829.Pp 2830This would just list the synchronizations state of 2831.Xr ntpd 1ntpdmdoc 2832and the major system events. 2833For a simple reference server, the 2834following minimum message configuration could be useful: 2835.Bd -literal 2836logconfig =syncall +clockall 2837.Ed 2838.Pp 2839This configuration will list all clock information and 2840synchronization information. 2841All other events and messages about 2842peers, system events and so on is suppressed. 2843.It Ic logfile Ar logfile 2844This command specifies the location of an alternate log file to 2845be used instead of the default system 2846.Xr syslog 3 2847facility. 2848This is the same operation as the 2849.Fl l 2850command line option. 2851.It Xo Ic mru 2852.Oo 2853.Cm maxdepth Ar count | Cm maxmem Ar kilobytes | 2854.Cm mindepth Ar count | Cm maxage Ar seconds | 2855.Cm initialloc Ar count | Cm initmem Ar kilobytes | 2856.Cm incalloc Ar count | Cm incmem Ar kilobytes 2857.Oc 2858.Xc 2859Controls size limite of the monitoring facility's Most Recently Used 2860(MRU) list 2861of client addresses, which is also used by the 2862rate control facility. 2863.Bl -tag -width indent 2864.It Ic maxdepth Ar count 2865.It Ic maxmem Ar kilobytes 2866Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. 2867The acutal limit will be up to 2868.Cm incalloc 2869entries or 2870.Cm incmem 2871kilobytes larger. 2872As with all of the 2873.Cm mru 2874options offered in units of entries or kilobytes, if both 2875.Cm maxdepth 2876and 2877.Cm maxmem are used, the last one used controls. 2878The default is 1024 kilobytes. 2879.It Cm mindepth Ar count 2880Lower limit on the MRU list size. 2881When the MRU list has fewer than 2882.Cm mindepth 2883entries, existing entries are never removed to make room for newer ones, 2884regardless of their age. 2885The default is 600 entries. 2886.It Cm maxage Ar seconds 2887Once the MRU list has 2888.Cm mindepth 2889entries and an additional client is to ba added to the list, 2890if the oldest entry was updated more than 2891.Cm maxage 2892seconds ago, that entry is removed and its storage is reused. 2893If the oldest entry was updated more recently the MRU list is grown, 2894subject to 2895.Cm maxdepth / moxmem . 2896The default is 64 seconds. 2897.It Cm initalloc Ar count 2898.It Cm initmem Ar kilobytes 2899Initial memory allocation at the time the monitoringfacility is first enabled, 2900in terms of the number of entries or kilobytes. 2901The default is 4 kilobytes. 2902.It Cm incalloc Ar count 2903.It Cm incmem Ar kilobytes 2904Size of additional memory allocations when growing the MRU list, in entries or kilobytes. 2905The default is 4 kilobytes. 2906.El 2907.It Ic nonvolatile Ar threshold 2908Specify the 2909.Ar threshold 2910delta in seconds before an hourly change to the 2911.Cm driftfile 2912(frequency file) will be written, with a default value of 1e\-7 (0.1 PPM). 2913The frequency file is inspected each hour. 2914If the difference between the current frequency and the last value written 2915exceeds the threshold, the file is written and the 2916.Cm threshold 2917becomes the new threshold value. 2918If the threshold is not exceeeded, it is reduced by half. 2919This is intended to reduce the number of file writes 2920for embedded systems with nonvolatile memory. 2921.It Ic phone Ar dial ... 2922This command is used in conjunction with 2923the ACTS modem driver (type 18) 2924or the JJY driver (type 40, mode 100 \- 180). 2925For the ACTS modem driver (type 18), the arguments consist of 2926a maximum of 10 telephone numbers used to dial USNO, NIST, or European 2927time service. 2928For the JJY driver (type 40 mode 100 \- 180), the argument is 2929one telephone number used to dial the telephone JJY service. 2930The Hayes command ATDT is normally prepended to the number. 2931The number can contain other modem control codes as well. 2932.It Xo Cm pollskewlist 2933.Oo 2934.Ar poll 2935.Ar value | value 2936.Oc 2937.Ar ... 2938.Oo 2939.Cm default 2940.Ar value | value 2941.Oc 2942.Xc 2943Enable skewing of our poll requests to our servers. 2944.Ar poll 2945is a number between 3 and 17 inclusive, identifying a specific poll interval. 2946A poll interval is 2^n seconds in duration, 2947so a poll value of 3 corresponds to 8 seconds 2948and 2949a poll interval of 17 corresponds to 2950131,072 seconds, or about a day and a half. 2951The next two numbers must be between 0 and one\-half of the poll interval, 2952inclusive. 2953The first number specifies how early the poll may start, 2954while 2955the second number specifies how late the poll may be delayed. 2956With no arguments, internally specified default values are chosen. 2957.It Xo Ic reset 2958.Oo 2959.Ic allpeers 2960.Oc 2961.Oo 2962.Ic auth 2963.Oc 2964.Oo 2965.Ic ctl 2966.Oc 2967.Oo 2968.Ic io 2969.Oc 2970.Oo 2971.Ic mem 2972.Oc 2973.Oo 2974.Ic sys 2975.Oc 2976.Oo 2977.Ic timer 2978.Oc 2979.Xc 2980Reset one or more groups of counters maintained by 2981.Cm ntpd 2982and exposed by 2983.Cm ntpq 2984and 2985.Cm ntpdc . 2986.It Xo Ic rlimit 2987.Oo 2988.Cm memlock Ar Nmegabytes | 2989.Cm stacksize Ar N4kPages 2990.Cm filenum Ar Nfiledescriptors 2991.Oc 2992.Xc 2993.Bl -tag -width indent 2994.It Cm memlock Ar Nmegabytes 2995Specify the number of megabytes of memory that should be 2996allocated and locked. 2997Probably only available under Linux, this option may be useful 2998when dropping root (the 2999.Fl i 3000option). 3001The default is 32 megabytes on non\-Linux machines, and \-1 under Linux. 3002-1 means "do not lock the process into memory". 30030 means "lock whatever memory the process wants into memory". 3004.It Cm stacksize Ar N4kPages 3005Specifies the maximum size of the process stack on systems with the 3006.Fn mlockall 3007function. 3008Defaults to 50 4k pages (200 4k pages in OpenBSD). 3009.It Cm filenum Ar Nfiledescriptors 3010Specifies the maximum number of file descriptors ntpd may have open at once. 3011Defaults to the system default. 3012.El 3013.It Ic saveconfigdir Ar directory_path 3014Specify the directory in which to write configuration snapshots 3015requested with 3016.Cm ntpq 's 3017.Cm saveconfig 3018command. 3019If 3020.Cm saveconfigdir 3021does not appear in the configuration file, 3022.Cm saveconfig 3023requests are rejected by 3024.Cm ntpd . 3025.It Ic saveconfig Ar filename 3026Write the current configuration, including any runtime 3027modifications given with 3028.Cm :config 3029or 3030.Cm config\-from\-file 3031to the 3032.Cm ntpd 3033host's 3034.Ar filename 3035in the 3036.Cm saveconfigdir . 3037This command will be rejected unless the 3038.Cm saveconfigdir 3039directive appears in 3040.Cm ntpd 's 3041configuration file. 3042.Ar filename 3043can use 3044.Xr strftime 3 3045format directives to substitute the current date and time, 3046for example, 3047.Cm saveconfig\ ntp\-%Y%m%d\-%H%M%S.conf . 3048The filename used is stored in the system variable 3049.Cm savedconfig . 3050Authentication is required. 3051.It Ic setvar Ar variable Op Cm default 3052This command adds an additional system variable. 3053These 3054variables can be used to distribute additional information such as 3055the access policy. 3056If the variable of the form 3057.Sm off 3058.Va name = Ar value 3059.Sm on 3060is followed by the 3061.Cm default 3062keyword, the 3063variable will be listed as part of the default system variables 3064.Po 3065.Xr ntpq 1ntpqmdoc 3066.Ic rv 3067command 3068.Pc ) . 3069These additional variables serve 3070informational purposes only. 3071They are not related to the protocol 3072other that they can be listed. 3073The known protocol variables will 3074always override any variables defined via the 3075.Ic setvar 3076mechanism. 3077There are three special variables that contain the names 3078of all variable of the same group. 3079The 3080.Va sys_var_list 3081holds 3082the names of all system variables. 3083The 3084.Va peer_var_list 3085holds 3086the names of all peer variables and the 3087.Va clock_var_list 3088holds the names of the reference clock variables. 3089.It Cm sysinfo 3090Display operational summary. 3091.It Cm sysstats 3092Show statistics counters maintained in the protocol module. 3093.It Xo Ic tinker 3094.Oo 3095.Cm allan Ar allan | 3096.Cm dispersion Ar dispersion | 3097.Cm freq Ar freq | 3098.Cm huffpuff Ar huffpuff | 3099.Cm panic Ar panic | 3100.Cm step Ar step | 3101.Cm stepback Ar stepback | 3102.Cm stepfwd Ar stepfwd | 3103.Cm stepout Ar stepout 3104.Oc 3105.Xc 3106This command can be used to alter several system variables in 3107very exceptional circumstances. 3108It should occur in the 3109configuration file before any other configuration options. 3110The 3111default values of these variables have been carefully optimized for 3112a wide range of network speeds and reliability expectations. 3113In 3114general, they interact in intricate ways that are hard to predict 3115and some combinations can result in some very nasty behavior. 3116Very 3117rarely is it necessary to change the default values; but, some 3118folks cannot resist twisting the knobs anyway and this command is 3119for them. 3120Emphasis added: twisters are on their own and can expect 3121no help from the support group. 3122.Pp 3123The variables operate as follows: 3124.Bl -tag -width indent 3125.It Cm allan Ar allan 3126The argument becomes the new value for the minimum Allan 3127intercept, which is a parameter of the PLL/FLL clock discipline 3128algorithm. 3129The value in log2 seconds defaults to 7 (1024 s), which is also the lower 3130limit. 3131.It Cm dispersion Ar dispersion 3132The argument becomes the new value for the dispersion increase rate, 3133normally .000015 s/s. 3134.It Cm freq Ar freq 3135The argument becomes the initial value of the frequency offset in 3136parts\-per\-million. 3137This overrides the value in the frequency file, if 3138present, and avoids the initial training state if it is not. 3139.It Cm huffpuff Ar huffpuff 3140The argument becomes the new value for the experimental 3141huff\-n'\-puff filter span, which determines the most recent interval 3142the algorithm will search for a minimum delay. 3143The lower limit is 3144900 s (15 m), but a more reasonable value is 7200 (2 hours). 3145There 3146is no default, since the filter is not enabled unless this command 3147is given. 3148.It Cm panic Ar panic 3149The argument is the panic threshold, normally 1000 s. 3150If set to zero, 3151the panic sanity check is disabled and a clock offset of any value will 3152be accepted. 3153.It Cm step Ar step 3154The argument is the step threshold, which by default is 0.128 s. 3155It can 3156be set to any positive number in seconds. 3157If set to zero, step 3158adjustments will never occur. 3159Note: The kernel time discipline is 3160disabled if the step threshold is set to zero or greater than the 3161default. 3162.It Cm stepback Ar stepback 3163The argument is the step threshold for the backward direction, 3164which by default is 0.128 s. 3165It can 3166be set to any positive number in seconds. 3167If both the forward and backward step thresholds are set to zero, step 3168adjustments will never occur. 3169Note: The kernel time discipline is 3170disabled if 3171each direction of step threshold are either 3172set to zero or greater than .5 second. 3173.It Cm stepfwd Ar stepfwd 3174As for stepback, but for the forward direction. 3175.It Cm stepout Ar stepout 3176The argument is the stepout timeout, which by default is 900 s. 3177It can 3178be set to any positive number in seconds. 3179If set to zero, the stepout 3180pulses will not be suppressed. 3181.El 3182.It Cm writevar Ar assocID\ name = value [,...] 3183Write (create or update) the specified variables. 3184If the 3185.Cm assocID 3186is zero, the variablea re from the 3187system variables 3188name space, otherwise they are from the 3189peer variables 3190name space. 3191The 3192.Cm assocID 3193is required, as the same name can occur in both name spaces. 3194.It Xo Ic trap Ar host_address 3195.Op Cm port Ar port_number 3196.Op Cm interface Ar interface_address 3197.Xc 3198This command configures a trap receiver at the given host 3199address and port number for sending messages with the specified 3200local interface address. 3201If the port number is unspecified, a value 3202of 18447 is used. 3203If the interface address is not specified, the 3204message is sent with a source address of the local interface the 3205message is sent through. 3206Note that on a multihomed host the 3207interface used may vary from time to time with routing changes. 3208.It Cm ttl Ar hop ... 3209This command specifies a list of TTL values in increasing order. 3210Up to 8 values can be specified. 3211In 3212.Cm manycast 3213mode these values are used in\-turn in an expanding\-ring search. 3214The default is eight multiples of 32 starting at 31. 3215.Pp 3216The trap receiver will generally log event messages and other 3217information from the server in a log file. 3218While such monitor 3219programs may also request their own trap dynamically, configuring a 3220trap receiver will ensure that no messages are lost when the server 3221is started. 3222.It Cm hop Ar ... 3223This command specifies a list of TTL values in increasing order, up to 8 3224values can be specified. 3225In manycast mode these values are used in turn in 3226an expanding\-ring search. 3227The default is eight multiples of 32 starting at 322831. 3229.El 3230.Sh "OPTIONS" 3231.Bl -tag 3232.It Fl \-help 3233Display usage information and exit. 3234.It Fl \-more\-help 3235Pass the extended usage information through a pager. 3236.It Fl \-version Op Brq Ar v|c|n 3237Output version of program and exit. The default mode is `v', a simple 3238version. The `c' mode will print copyright information and `n' will 3239print the full copyright notice. 3240.El 3241.Sh "OPTION PRESETS" 3242Any option that is not marked as \fInot presettable\fP may be preset 3243by loading values from environment variables named: 3244.nf 3245 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP 3246.fi 3247.ad 3248.Sh "ENVIRONMENT" 3249See \fBOPTION PRESETS\fP for configuration environment variables. 3250.Sh FILES 3251.Bl -tag -width /etc/ntp.drift -compact 3252.It Pa /etc/ntp.conf 3253the default name of the configuration file 3254.It Pa ntp.keys 3255private MD5 keys 3256.It Pa ntpkey 3257RSA private key 3258.It Pa ntpkey_ Ns Ar host 3259RSA public key 3260.It Pa ntp_dh 3261Diffie\-Hellman agreement parameters 3262.El 3263.Sh "EXIT STATUS" 3264One of the following exit values will be returned: 3265.Bl -tag 3266.It 0 " (EXIT_SUCCESS)" 3267Successful program execution. 3268.It 1 " (EXIT_FAILURE)" 3269The operation failed or the command syntax was not valid. 3270.It 70 " (EX_SOFTWARE)" 3271libopts had an internal operational error. Please report 3272it to autogen\-users@lists.sourceforge.net. Thank you. 3273.El 3274.Sh "SEE ALSO" 3275.Xr ntpd 1ntpdmdoc , 3276.Xr ntpdc 1ntpdcmdoc , 3277.Xr ntpq 1ntpqmdoc 3278.Pp 3279In addition to the manual pages provided, 3280comprehensive documentation is available on the world wide web 3281at 3282.Li http://www.ntp.org/ . 3283A snapshot of this documentation is available in HTML format in 3284.Pa /usr/share/doc/ntp . 3285.Rs 3286.%A David L. Mills 3287.%T Network Time Protocol (Version 4) 3288.%O RFC5905 3289.Re 3290.Sh "AUTHORS" 3291The University of Delaware and Network Time Foundation 3292.Sh "COPYRIGHT" 3293Copyright (C) 1992\-2020 The University of Delaware and Network Time Foundation all rights reserved. 3294This program is released under the terms of the NTP license, <http://ntp.org/license>. 3295.Sh BUGS 3296The syntax checking is not picky; some combinations of 3297ridiculous and even hilarious options and modes may not be 3298detected. 3299.Pp 3300The 3301.Pa ntpkey_ Ns Ar host 3302files are really digital 3303certificates. 3304These should be obtained via secure directory 3305services when they become universally available. 3306.Pp 3307Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 3308.Sh NOTES 3309This document was derived from FreeBSD. 3310.Pp 3311This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP 3312option definitions. 3313