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