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