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