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