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