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