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