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