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, four 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. 1582.It Cm noserve 1583Deny all packets except 1584.Xr ntpq 1ntpqmdoc 1585and 1586.Xr ntpdc 1ntpdcmdoc 1587queries. 1588.It Cm notrap 1589Decline to provide mode 6 control message trap service to matching 1590hosts. 1591The trap service is a subsystem of the ntpdq control message 1592protocol which is intended for use by remote event logging programs. 1593.It Cm notrust 1594Deny service unless the packet is cryptographically authenticated. 1595.It Cm ntpport 1596This is actually a match algorithm modifier, rather than a 1597restriction flag. 1598Its presence causes the restriction entry to be 1599matched only if the source port in the packet is the standard NTP 1600UDP port (123). 1601Both 1602.Cm ntpport 1603and 1604.Cm non-ntpport 1605may 1606be specified. 1607The 1608.Cm ntpport 1609is considered more specific and 1610is sorted later in the list. 1611.It Cm version 1612Deny packets that do not match the current NTP version. 1613.El 1614.Pp 1615Default restriction list entries with the flags ignore, interface, 1616ntpport, for each of the local host's interface addresses are 1617inserted into the table at startup to prevent the server 1618from attempting to synchronize to its own time. 1619A default entry is also always present, though if it is 1620otherwise unconfigured; no flags are associated 1621with the default entry (i.e., everything besides your own 1622NTP server is unrestricted). 1623.El 1624.Sh Automatic NTP Configuration Options 1625.Ss Manycasting 1626Manycasting is a automatic discovery and configuration paradigm 1627new to NTPv4. 1628It is intended as a means for a multicast client 1629to troll the nearby network neighborhood to find cooperating 1630manycast servers, validate them using cryptographic means 1631and evaluate their time values with respect to other servers 1632that might be lurking in the vicinity. 1633The intended result is that each manycast client mobilizes 1634client associations with some number of the "best" 1635of the nearby manycast servers, yet automatically reconfigures 1636to sustain this number of servers should one or another fail. 1637.Pp 1638Note that the manycasting paradigm does not coincide 1639with the anycast paradigm described in RFC-1546, 1640which is designed to find a single server from a clique 1641of servers providing the same service. 1642The manycast paradigm is designed to find a plurality 1643of redundant servers satisfying defined optimality criteria. 1644.Pp 1645Manycasting can be used with either symmetric key 1646or public key cryptography. 1647The public key infrastructure (PKI) 1648offers the best protection against compromised keys 1649and is generally considered stronger, at least with relatively 1650large key sizes. 1651It is implemented using the Autokey protocol and 1652the OpenSSL cryptographic library available from 1653.Li http://www.openssl.org/ . 1654The library can also be used with other NTPv4 modes 1655as well and is highly recommended, especially for broadcast modes. 1656.Pp 1657A persistent manycast client association is configured 1658using the manycastclient command, which is similar to the 1659server command but with a multicast (IPv4 class 1660.Cm D 1661or IPv6 prefix 1662.Cm FF ) 1663group address. 1664The IANA has designated IPv4 address 224.1.1.1 1665and IPv6 address FF05::101 (site local) for NTP. 1666When more servers are needed, it broadcasts manycast 1667client messages to this address at the minimum feasible rate 1668and minimum feasible time-to-live (TTL) hops, depending 1669on how many servers have already been found. 1670There can be as many manycast client associations 1671as different group address, each one serving as a template 1672for a future ephemeral unicast client/server association. 1673.Pp 1674Manycast servers configured with the 1675.Ic manycastserver 1676command listen on the specified group address for manycast 1677client messages. 1678Note the distinction between manycast client, 1679which actively broadcasts messages, and manycast server, 1680which passively responds to them. 1681If a manycast server is 1682in scope of the current TTL and is itself synchronized 1683to a valid source and operating at a stratum level equal 1684to or lower than the manycast client, it replies to the 1685manycast client message with an ordinary unicast server message. 1686.Pp 1687The manycast client receiving this message mobilizes 1688an ephemeral client/server association according to the 1689matching manycast client template, but only if cryptographically 1690authenticated and the server stratum is less than or equal 1691to the client stratum. 1692Authentication is explicitly required 1693and either symmetric key or public key (Autokey) can be used. 1694Then, the client polls the server at its unicast address 1695in burst mode in order to reliably set the host clock 1696and validate the source. 1697This normally results 1698in a volley of eight client/server at 2-s intervals 1699during which both the synchronization and cryptographic 1700protocols run concurrently. 1701Following the volley, 1702the client runs the NTP intersection and clustering 1703algorithms, which act to discard all but the "best" 1704associations according to stratum and synchronization 1705distance. 1706The surviving associations then continue 1707in ordinary client/server mode. 1708.Pp 1709The manycast client polling strategy is designed to reduce 1710as much as possible the volume of manycast client messages 1711and the effects of implosion due to near-simultaneous 1712arrival of manycast server messages. 1713The strategy is determined by the 1714.Ic manycastclient , 1715.Ic tos 1716and 1717.Ic ttl 1718configuration commands. 1719The manycast poll interval is 1720normally eight times the system poll interval, 1721which starts out at the 1722.Cm minpoll 1723value specified in the 1724.Ic manycastclient , 1725command and, under normal circumstances, increments to the 1726.Cm maxpolll 1727value specified in this command. 1728Initially, the TTL is 1729set at the minimum hops specified by the ttl command. 1730At each retransmission the TTL is increased until reaching 1731the maximum hops specified by this command or a sufficient 1732number client associations have been found. 1733Further retransmissions use the same TTL. 1734.Pp 1735The quality and reliability of the suite of associations 1736discovered by the manycast client is determined by the NTP 1737mitigation algorithms and the 1738.Cm minclock 1739and 1740.Cm minsane 1741values specified in the 1742.Ic tos 1743configuration command. 1744At least 1745.Cm minsane 1746candidate servers must be available and the mitigation 1747algorithms produce at least 1748.Cm minclock 1749survivors in order to synchronize the clock. 1750Byzantine agreement principles require at least four 1751candidates in order to correctly discard a single falseticker. 1752For legacy purposes, 1753.Cm minsane 1754defaults to 1 and 1755.Cm minclock 1756defaults to 3. 1757For manycast service 1758.Cm minsane 1759should be explicitly set to 4, assuming at least that 1760number of servers are available. 1761.Pp 1762If at least 1763.Cm minclock 1764servers are found, the manycast poll interval is immediately 1765set to eight times 1766.Cm maxpoll . 1767If less than 1768.Cm minclock 1769servers are found when the TTL has reached the maximum hops, 1770the manycast poll interval is doubled. 1771For each transmission 1772after that, the poll interval is doubled again until 1773reaching the maximum of eight times 1774.Cm maxpoll . 1775Further transmissions use the same poll interval and 1776TTL values. 1777Note that while all this is going on, 1778each client/server association found is operating normally 1779it the system poll interval. 1780.Pp 1781Administratively scoped multicast boundaries are normally 1782specified by the network router configuration and, 1783in the case of IPv6, the link/site scope prefix. 1784By default, the increment for TTL hops is 32 starting 1785from 31; however, the 1786.Ic ttl 1787configuration command can be 1788used to modify the values to match the scope rules. 1789.Pp 1790It is often useful to narrow the range of acceptable 1791servers which can be found by manycast client associations. 1792Because manycast servers respond only when the client 1793stratum is equal to or greater than the server stratum, 1794primary (stratum 1) servers fill find only primary servers 1795in TTL range, which is probably the most common objective. 1796However, unless configured otherwise, all manycast clients 1797in TTL range will eventually find all primary servers 1798in TTL range, which is probably not the most common 1799objective in large networks. 1800The 1801.Ic tos 1802command can be used to modify this behavior. 1803Servers with stratum below 1804.Cm floor 1805or above 1806.Cm ceiling 1807specified in the 1808.Ic tos 1809command are strongly discouraged during the selection 1810process; however, these servers may be temporally 1811accepted if the number of servers within TTL range is 1812less than 1813.Cm minclock . 1814.Pp 1815The above actions occur for each manycast client message, 1816which repeats at the designated poll interval. 1817However, once the ephemeral client association is mobilized, 1818subsequent manycast server replies are discarded, 1819since that would result in a duplicate association. 1820If during a poll interval the number of client associations 1821falls below 1822.Cm minclock , 1823all manycast client prototype associations are reset 1824to the initial poll interval and TTL hops and operation 1825resumes from the beginning. 1826It is important to avoid 1827frequent manycast client messages, since each one requires 1828all manycast servers in TTL range to respond. 1829The result could well be an implosion, either minor or major, 1830depending on the number of servers in range. 1831The recommended value for 1832.Cm maxpoll 1833is 12 (4,096 s). 1834.Pp 1835It is possible and frequently useful to configure a host 1836as both manycast client and manycast server. 1837A number of hosts configured this way and sharing a common 1838group address will automatically organize themselves 1839in an optimum configuration based on stratum and 1840synchronization distance. 1841For example, consider an NTP 1842subnet of two primary servers and a hundred or more 1843dependent clients. 1844With two exceptions, all servers 1845and clients have identical configuration files including both 1846.Ic multicastclient 1847and 1848.Ic multicastserver 1849commands using, for instance, multicast group address 1850239.1.1.1. 1851The only exception is that each primary server 1852configuration file must include commands for the primary 1853reference source such as a GPS receiver. 1854.Pp 1855The remaining configuration files for all secondary 1856servers and clients have the same contents, except for the 1857.Ic tos 1858command, which is specific for each stratum level. 1859For stratum 1 and stratum 2 servers, that command is 1860not necessary. 1861For stratum 3 and above servers the 1862.Cm floor 1863value is set to the intended stratum number. 1864Thus, all stratum 3 configuration files are identical, 1865all stratum 4 files are identical and so forth. 1866.Pp 1867Once operations have stabilized in this scenario, 1868the primary servers will find the primary reference source 1869and each other, since they both operate at the same 1870stratum (1), but not with any secondary server or client, 1871since these operate at a higher stratum. 1872The secondary 1873servers will find the servers at the same stratum level. 1874If one of the primary servers loses its GPS receiver, 1875it will continue to operate as a client and other clients 1876will time out the corresponding association and 1877re-associate accordingly. 1878.Pp 1879Some administrators prefer to avoid running 1880.Xr ntpd 1ntpdmdoc 1881continuously and run either 1882.Xr ntpdate 8 1883or 1884.Xr ntpd 1ntpdmdoc 1885.Fl q 1886as a cron job. 1887In either case the servers must be 1888configured in advance and the program fails if none are 1889available when the cron job runs. 1890A really slick 1891application of manycast is with 1892.Xr ntpd 1ntpdmdoc 1893.Fl q . 1894The program wakes up, scans the local landscape looking 1895for the usual suspects, selects the best from among 1896the rascals, sets the clock and then departs. 1897Servers do not have to be configured in advance and 1898all clients throughout the network can have the same 1899configuration file. 1900.Ss Manycast Interactions with Autokey 1901Each time a manycast client sends a client mode packet 1902to a multicast group address, all manycast servers 1903in scope generate a reply including the host name 1904and status word. 1905The manycast clients then run 1906the Autokey protocol, which collects and verifies 1907all certificates involved. 1908Following the burst interval 1909all but three survivors are cast off, 1910but the certificates remain in the local cache. 1911It often happens that several complete signing trails 1912from the client to the primary servers are collected in this way. 1913.Pp 1914About once an hour or less often if the poll interval 1915exceeds this, the client regenerates the Autokey key list. 1916This is in general transparent in client/server mode. 1917However, about once per day the server private value 1918used to generate cookies is refreshed along with all 1919manycast client associations. 1920In this case all 1921cryptographic values including certificates is refreshed. 1922If a new certificate has been generated since 1923the last refresh epoch, it will automatically revoke 1924all prior certificates that happen to be in the 1925certificate cache. 1926At the same time, the manycast 1927scheme starts all over from the beginning and 1928the expanding ring shrinks to the minimum and increments 1929from there while collecting all servers in scope. 1930.Ss Manycast Options 1931.Bl -tag -width indent 1932.It Xo Ic tos 1933.Oo 1934.Cm ceiling Ar ceiling | 1935.Cm cohort { 0 | 1 } | 1936.Cm floor Ar floor | 1937.Cm minclock Ar minclock | 1938.Cm minsane Ar minsane 1939.Oc 1940.Xc 1941This command affects the clock selection and clustering 1942algorithms. 1943It can be used to select the quality and 1944quantity of peers used to synchronize the system clock 1945and is most useful in manycast mode. 1946The variables operate 1947as follows: 1948.Bl -tag -width indent 1949.It Cm ceiling Ar ceiling 1950Peers with strata above 1951.Cm ceiling 1952will be discarded if there are at least 1953.Cm minclock 1954peers remaining. 1955This value defaults to 15, but can be changed 1956to any number from 1 to 15. 1957.It Cm cohort Bro 0 | 1 Brc 1958This is a binary flag which enables (0) or disables (1) 1959manycast server replies to manycast clients with the same 1960stratum level. 1961This is useful to reduce implosions where 1962large numbers of clients with the same stratum level 1963are present. 1964The default is to enable these replies. 1965.It Cm floor Ar floor 1966Peers with strata below 1967.Cm floor 1968will be discarded if there are at least 1969.Cm minclock 1970peers remaining. 1971This value defaults to 1, but can be changed 1972to any number from 1 to 15. 1973.It Cm minclock Ar minclock 1974The clustering algorithm repeatedly casts out outlyer 1975associations until no more than 1976.Cm minclock 1977associations remain. 1978This value defaults to 3, 1979but can be changed to any number from 1 to the number of 1980configured sources. 1981.It Cm minsane Ar minsane 1982This is the minimum number of candidates available 1983to the clock selection algorithm in order to produce 1984one or more truechimers for the clustering algorithm. 1985If fewer than this number are available, the clock is 1986undisciplined and allowed to run free. 1987The default is 1 1988for legacy purposes. 1989However, according to principles of 1990Byzantine agreement, 1991.Cm minsane 1992should be at least 4 in order to detect and discard 1993a single falseticker. 1994.El 1995.It Cm ttl Ar hop ... 1996This command specifies a list of TTL values in increasing 1997order, up to 8 values can be specified. 1998In manycast mode these values are used in turn 1999in an expanding-ring search. 2000The default is eight 2001multiples of 32 starting at 31. 2002.El 2003.Sh Reference Clock Support 2004The NTP Version 4 daemon supports some three dozen different radio, 2005satellite and modem reference clocks plus a special pseudo-clock 2006used for backup or when no other clock source is available. 2007Detailed descriptions of individual device drivers and options can 2008be found in the 2009.Qq Reference Clock Drivers 2010page 2011(available as part of the HTML documentation 2012provided in 2013.Pa /usr/share/doc/ntp ) . 2014Additional information can be found in the pages linked 2015there, including the 2016.Qq Debugging Hints for Reference Clock Drivers 2017and 2018.Qq How To Write a Reference Clock Driver 2019pages 2020(available as part of the HTML documentation 2021provided in 2022.Pa /usr/share/doc/ntp ) . 2023In addition, support for a PPS 2024signal is available as described in the 2025.Qq Pulse-per-second (PPS) Signal Interfacing 2026page 2027(available as part of the HTML documentation 2028provided in 2029.Pa /usr/share/doc/ntp ) . 2030Many 2031drivers support special line discipline/streams modules which can 2032significantly improve the accuracy using the driver. 2033These are 2034described in the 2035.Qq Line Disciplines and Streams Drivers 2036page 2037(available as part of the HTML documentation 2038provided in 2039.Pa /usr/share/doc/ntp ) . 2040.Pp 2041A reference clock will generally (though not always) be a radio 2042timecode receiver which is synchronized to a source of standard 2043time such as the services offered by the NRC in Canada and NIST and 2044USNO in the US. 2045The interface between the computer and the timecode 2046receiver is device dependent, but is usually a serial port. 2047A 2048device driver specific to each reference clock must be selected and 2049compiled in the distribution; however, most common radio, satellite 2050and modem clocks are included by default. 2051Note that an attempt to 2052configure a reference clock when the driver has not been compiled 2053or the hardware port has not been appropriately configured results 2054in a scalding remark to the system log file, but is otherwise non 2055hazardous. 2056.Pp 2057For the purposes of configuration, 2058.Xr ntpd 1ntpdmdoc 2059treats 2060reference clocks in a manner analogous to normal NTP peers as much 2061as possible. 2062Reference clocks are identified by a syntactically 2063correct but invalid IP address, in order to distinguish them from 2064normal NTP peers. 2065Reference clock addresses are of the form 2066.Sm off 2067.Li 127.127. Ar t . Ar u , 2068.Sm on 2069where 2070.Ar t 2071is an integer 2072denoting the clock type and 2073.Ar u 2074indicates the unit 2075number in the range 0-3. 2076While it may seem overkill, it is in fact 2077sometimes useful to configure multiple reference clocks of the same 2078type, in which case the unit numbers must be unique. 2079.Pp 2080The 2081.Ic server 2082command is used to configure a reference 2083clock, where the 2084.Ar address 2085argument in that command 2086is the clock address. 2087The 2088.Cm key , 2089.Cm version 2090and 2091.Cm ttl 2092options are not used for reference clock support. 2093The 2094.Cm mode 2095option is added for reference clock support, as 2096described below. 2097The 2098.Cm prefer 2099option can be useful to 2100persuade the server to cherish a reference clock with somewhat more 2101enthusiasm than other reference clocks or peers. 2102Further 2103information on this option can be found in the 2104.Qq Mitigation Rules and the prefer Keyword 2105(available as part of the HTML documentation 2106provided in 2107.Pa /usr/share/doc/ntp ) 2108page. 2109The 2110.Cm minpoll 2111and 2112.Cm maxpoll 2113options have 2114meaning only for selected clock drivers. 2115See the individual clock 2116driver document pages for additional information. 2117.Pp 2118The 2119.Ic fudge 2120command is used to provide additional 2121information for individual clock drivers and normally follows 2122immediately after the 2123.Ic server 2124command. 2125The 2126.Ar address 2127argument specifies the clock address. 2128The 2129.Cm refid 2130and 2131.Cm stratum 2132options can be used to 2133override the defaults for the device. 2134There are two optional 2135device-dependent time offsets and four flags that can be included 2136in the 2137.Ic fudge 2138command as well. 2139.Pp 2140The stratum number of a reference clock is by default zero. 2141Since the 2142.Xr ntpd 1ntpdmdoc 2143daemon adds one to the stratum of each 2144peer, a primary server ordinarily displays an external stratum of 2145one. 2146In order to provide engineered backups, it is often useful to 2147specify the reference clock stratum as greater than zero. 2148The 2149.Cm stratum 2150option is used for this purpose. 2151Also, in cases 2152involving both a reference clock and a pulse-per-second (PPS) 2153discipline signal, it is useful to specify the reference clock 2154identifier as other than the default, depending on the driver. 2155The 2156.Cm refid 2157option is used for this purpose. 2158Except where noted, 2159these options apply to all clock drivers. 2160.Ss Reference Clock Commands 2161.Bl -tag -width indent 2162.It Xo Ic server 2163.Sm off 2164.Li 127.127. Ar t . Ar u 2165.Sm on 2166.Op Cm prefer 2167.Op Cm mode Ar int 2168.Op Cm minpoll Ar int 2169.Op Cm maxpoll Ar int 2170.Xc 2171This command can be used to configure reference clocks in 2172special ways. 2173The options are interpreted as follows: 2174.Bl -tag -width indent 2175.It Cm prefer 2176Marks the reference clock as preferred. 2177All other things being 2178equal, this host will be chosen for synchronization among a set of 2179correctly operating hosts. 2180See the 2181.Qq Mitigation Rules and the prefer Keyword 2182page 2183(available as part of the HTML documentation 2184provided in 2185.Pa /usr/share/doc/ntp ) 2186for further information. 2187.It Cm mode Ar int 2188Specifies a mode number which is interpreted in a 2189device-specific fashion. 2190For instance, it selects a dialing 2191protocol in the ACTS driver and a device subtype in the 2192parse 2193drivers. 2194.It Cm minpoll Ar int 2195.It Cm maxpoll Ar int 2196These options specify the minimum and maximum polling interval 2197for reference clock messages, as a power of 2 in seconds 2198For 2199most directly connected reference clocks, both 2200.Cm minpoll 2201and 2202.Cm maxpoll 2203default to 6 (64 s). 2204For modem reference clocks, 2205.Cm minpoll 2206defaults to 10 (17.1 m) and 2207.Cm maxpoll 2208defaults to 14 (4.5 h). 2209The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2210.El 2211.It Xo Ic fudge 2212.Sm off 2213.Li 127.127. Ar t . Ar u 2214.Sm on 2215.Op Cm time1 Ar sec 2216.Op Cm time2 Ar sec 2217.Op Cm stratum Ar int 2218.Op Cm refid Ar string 2219.Op Cm mode Ar int 2220.Op Cm flag1 Cm 0 \&| Cm 1 2221.Op Cm flag2 Cm 0 \&| Cm 1 2222.Op Cm flag3 Cm 0 \&| Cm 1 2223.Op Cm flag4 Cm 0 \&| Cm 1 2224.Xc 2225This command can be used to configure reference clocks in 2226special ways. 2227It must immediately follow the 2228.Ic server 2229command which configures the driver. 2230Note that the same capability 2231is possible at run time using the 2232.Xr ntpdc 1ntpdcmdoc 2233program. 2234The options are interpreted as 2235follows: 2236.Bl -tag -width indent 2237.It Cm time1 Ar sec 2238Specifies a constant to be added to the time offset produced by 2239the driver, a fixed-point decimal number in seconds. 2240This is used 2241as a calibration constant to adjust the nominal time offset of a 2242particular clock to agree with an external standard, such as a 2243precision PPS signal. 2244It also provides a way to correct a 2245systematic error or bias due to serial port or operating system 2246latencies, different cable lengths or receiver internal delay. 2247The 2248specified offset is in addition to the propagation delay provided 2249by other means, such as internal DIPswitches. 2250Where a calibration 2251for an individual system and driver is available, an approximate 2252correction is noted in the driver documentation pages. 2253Note: in order to facilitate calibration when more than one 2254radio clock or PPS signal is supported, a special calibration 2255feature is available. 2256It takes the form of an argument to the 2257.Ic enable 2258command described in 2259.Sx Miscellaneous Options 2260page and operates as described in the 2261.Qq Reference Clock Drivers 2262page 2263(available as part of the HTML documentation 2264provided in 2265.Pa /usr/share/doc/ntp ) . 2266.It Cm time2 Ar secs 2267Specifies a fixed-point decimal number in seconds, which is 2268interpreted in a driver-dependent way. 2269See the descriptions of 2270specific drivers in the 2271.Qq Reference Clock Drivers 2272page 2273(available as part of the HTML documentation 2274provided in 2275.Pa /usr/share/doc/ntp ) . 2276.It Cm stratum Ar int 2277Specifies the stratum number assigned to the driver, an integer 2278between 0 and 15. 2279This number overrides the default stratum number 2280ordinarily assigned by the driver itself, usually zero. 2281.It Cm refid Ar string 2282Specifies an ASCII string of from one to four characters which 2283defines the reference identifier used by the driver. 2284This string 2285overrides the default identifier ordinarily assigned by the driver 2286itself. 2287.It Cm mode Ar int 2288Specifies a mode number which is interpreted in a 2289device-specific fashion. 2290For instance, it selects a dialing 2291protocol in the ACTS driver and a device subtype in the 2292parse 2293drivers. 2294.It Cm flag1 Cm 0 \&| Cm 1 2295.It Cm flag2 Cm 0 \&| Cm 1 2296.It Cm flag3 Cm 0 \&| Cm 1 2297.It Cm flag4 Cm 0 \&| Cm 1 2298These four flags are used for customizing the clock driver. 2299The 2300interpretation of these values, and whether they are used at all, 2301is a function of the particular clock driver. 2302However, by 2303convention 2304.Cm flag4 2305is used to enable recording monitoring 2306data to the 2307.Cm clockstats 2308file configured with the 2309.Ic filegen 2310command. 2311Further information on the 2312.Ic filegen 2313command can be found in 2314.Sx Monitoring Options . 2315.El 2316.El 2317.Sh Miscellaneous Options 2318.Bl -tag -width indent 2319.It Ic broadcastdelay Ar seconds 2320The broadcast and multicast modes require a special calibration 2321to determine the network delay between the local and remote 2322servers. 2323Ordinarily, this is done automatically by the initial 2324protocol exchanges between the client and server. 2325In some cases, 2326the calibration procedure may fail due to network or server access 2327controls, for example. 2328This command specifies the default delay to 2329be used under these circumstances. 2330Typically (for Ethernet), a 2331number between 0.003 and 0.007 seconds is appropriate. 2332The default 2333when this command is not used is 0.004 seconds. 2334.It Ic calldelay Ar delay 2335This option controls the delay in seconds between the first and second 2336packets sent in burst or iburst mode to allow additional time for a modem 2337or ISDN call to complete. 2338.It Ic driftfile Ar driftfile 2339This command specifies the complete path and name of the file used to 2340record the frequency of the local clock oscillator. 2341This is the same 2342operation as the 2343.Fl f 2344command line option. 2345If the file exists, it is read at 2346startup in order to set the initial frequency and then updated once per 2347hour with the current frequency computed by the daemon. 2348If the file name is 2349specified, but the file itself does not exist, the starts with an initial 2350frequency of zero and creates the file when writing it for the first time. 2351If this command is not given, the daemon will always start with an initial 2352frequency of zero. 2353.Pp 2354The file format consists of a single line containing a single 2355floating point number, which records the frequency offset measured 2356in parts-per-million (PPM). 2357The file is updated by first writing 2358the current drift value into a temporary file and then renaming 2359this file to replace the old version. 2360This implies that 2361.Xr ntpd 1ntpdmdoc 2362must have write permission for the directory the 2363drift file is located in, and that file system links, symbolic or 2364otherwise, should be avoided. 2365.It Xo Ic enable 2366.Oo 2367.Cm auth | Cm bclient | 2368.Cm calibrate | Cm kernel | 2369.Cm monitor | Cm ntp | 2370.Cm pps | Cm stats 2371.Oc 2372.Xc 2373.It Xo Ic disable 2374.Oo 2375.Cm auth | Cm bclient | 2376.Cm calibrate | Cm kernel | 2377.Cm monitor | Cm ntp | 2378.Cm pps | Cm stats 2379.Oc 2380.Xc 2381Provides a way to enable or disable various server options. 2382Flags not mentioned are unaffected. 2383Note that all of these flags 2384can be controlled remotely using the 2385.Xr ntpdc 1ntpdcmdoc 2386utility program. 2387.Bl -tag -width indent 2388.It Cm auth 2389Enables the server to synchronize with unconfigured peers only if the 2390peer has been correctly authenticated using either public key or 2391private key cryptography. 2392The default for this flag is 2393.Ic enable . 2394.It Cm bclient 2395Enables the server to listen for a message from a broadcast or 2396multicast server, as in the 2397.Ic multicastclient 2398command with default 2399address. 2400The default for this flag is 2401.Ic disable . 2402.It Cm calibrate 2403Enables the calibrate feature for reference clocks. 2404The default for 2405this flag is 2406.Ic disable . 2407.It Cm kernel 2408Enables the kernel time discipline, if available. 2409The default for this 2410flag is 2411.Ic enable 2412if support is available, otherwise 2413.Ic disable . 2414.It Cm monitor 2415Enables the monitoring facility. 2416See the 2417.Xr ntpdc 1ntpdcmdoc 2418program 2419and the 2420.Ic monlist 2421command or further information. 2422The 2423default for this flag is 2424.Ic enable . 2425.It Cm ntp 2426Enables time and frequency discipline. 2427In effect, this switch opens and 2428closes the feedback loop, which is useful for testing. 2429The default for 2430this flag is 2431.Ic enable . 2432.It Cm pps 2433Enables the pulse-per-second (PPS) signal when frequency and time is 2434disciplined by the precision time kernel modifications. 2435See the 2436.Qq A Kernel Model for Precision Timekeeping 2437(available as part of the HTML documentation 2438provided in 2439.Pa /usr/share/doc/ntp ) 2440page for further information. 2441The default for this flag is 2442.Ic disable . 2443.It Cm stats 2444Enables the statistics facility. 2445See the 2446.Sx Monitoring Options 2447section for further information. 2448The default for this flag is 2449.Ic disable . 2450.El 2451.It Ic includefile Ar includefile 2452This command allows additional configuration commands 2453to be included from a separate file. 2454Include files may 2455be nested to a depth of five; upon reaching the end of any 2456include file, command processing resumes in the previous 2457configuration file. 2458This option is useful for sites that run 2459.Xr ntpd 1ntpdmdoc 2460on multiple hosts, with (mostly) common options (e.g., a 2461restriction list). 2462.It Ic logconfig Ar configkeyword 2463This command controls the amount and type of output written to 2464the system 2465.Xr syslog 3 2466facility or the alternate 2467.Ic logfile 2468log file. 2469By default, all output is turned on. 2470All 2471.Ar configkeyword 2472keywords can be prefixed with 2473.Ql = , 2474.Ql + 2475and 2476.Ql - , 2477where 2478.Ql = 2479sets the 2480.Xr syslog 3 2481priority mask, 2482.Ql + 2483adds and 2484.Ql - 2485removes 2486messages. 2487.Xr syslog 3 2488messages can be controlled in four 2489classes 2490.Po 2491.Cm clock , 2492.Cm peer , 2493.Cm sys 2494and 2495.Cm sync 2496.Pc . 2497Within these classes four types of messages can be 2498controlled: informational messages 2499.Po 2500.Cm info 2501.Pc , 2502event messages 2503.Po 2504.Cm events 2505.Pc , 2506statistics messages 2507.Po 2508.Cm statistics 2509.Pc 2510and 2511status messages 2512.Po 2513.Cm status 2514.Pc . 2515.Pp 2516Configuration keywords are formed by concatenating the message class with 2517the event class. 2518The 2519.Cm all 2520prefix can be used instead of a message class. 2521A 2522message class may also be followed by the 2523.Cm all 2524keyword to enable/disable all 2525messages of the respective message class.Thus, a minimal log configuration 2526could look like this: 2527.Bd -literal 2528logconfig =syncstatus +sysevents 2529.Ed 2530.Pp 2531This would just list the synchronizations state of 2532.Xr ntpd 1ntpdmdoc 2533and the major system events. 2534For a simple reference server, the 2535following minimum message configuration could be useful: 2536.Bd -literal 2537logconfig =syncall +clockall 2538.Ed 2539.Pp 2540This configuration will list all clock information and 2541synchronization information. 2542All other events and messages about 2543peers, system events and so on is suppressed. 2544.It Ic logfile Ar logfile 2545This command specifies the location of an alternate log file to 2546be used instead of the default system 2547.Xr syslog 3 2548facility. 2549This is the same operation as the -l command line option. 2550.It Ic setvar Ar variable Op Cm default 2551This command adds an additional system variable. 2552These 2553variables can be used to distribute additional information such as 2554the access policy. 2555If the variable of the form 2556.Sm off 2557.Va name = Ar value 2558.Sm on 2559is followed by the 2560.Cm default 2561keyword, the 2562variable will be listed as part of the default system variables 2563.Po 2564.Xr ntpq 1ntpqmdoc 2565.Ic rv 2566command 2567.Pc ) . 2568These additional variables serve 2569informational purposes only. 2570They are not related to the protocol 2571other that they can be listed. 2572The known protocol variables will 2573always override any variables defined via the 2574.Ic setvar 2575mechanism. 2576There are three special variables that contain the names 2577of all variable of the same group. 2578The 2579.Va sys_var_list 2580holds 2581the names of all system variables. 2582The 2583.Va peer_var_list 2584holds 2585the names of all peer variables and the 2586.Va clock_var_list 2587holds the names of the reference clock variables. 2588.It Xo Ic tinker 2589.Oo 2590.Cm allan Ar allan | 2591.Cm dispersion Ar dispersion | 2592.Cm freq Ar freq | 2593.Cm huffpuff Ar huffpuff | 2594.Cm panic Ar panic | 2595.Cm step Ar srep | 2596.Cm stepout Ar stepout 2597.Oc 2598.Xc 2599This command can be used to alter several system variables in 2600very exceptional circumstances. 2601It should occur in the 2602configuration file before any other configuration options. 2603The 2604default values of these variables have been carefully optimized for 2605a wide range of network speeds and reliability expectations. 2606In 2607general, they interact in intricate ways that are hard to predict 2608and some combinations can result in some very nasty behavior. 2609Very 2610rarely is it necessary to change the default values; but, some 2611folks cannot resist twisting the knobs anyway and this command is 2612for them. 2613Emphasis added: twisters are on their own and can expect 2614no help from the support group. 2615.Pp 2616The variables operate as follows: 2617.Bl -tag -width indent 2618.It Cm allan Ar allan 2619The argument becomes the new value for the minimum Allan 2620intercept, which is a parameter of the PLL/FLL clock discipline 2621algorithm. 2622The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2623limit. 2624.It Cm dispersion Ar dispersion 2625The argument becomes the new value for the dispersion increase rate, 2626normally .000015 s/s. 2627.It Cm freq Ar freq 2628The argument becomes the initial value of the frequency offset in 2629parts-per-million. 2630This overrides the value in the frequency file, if 2631present, and avoids the initial training state if it is not. 2632.It Cm huffpuff Ar huffpuff 2633The argument becomes the new value for the experimental 2634huff-n'-puff filter span, which determines the most recent interval 2635the algorithm will search for a minimum delay. 2636The lower limit is 2637900 s (15 m), but a more reasonable value is 7200 (2 hours). 2638There 2639is no default, since the filter is not enabled unless this command 2640is given. 2641.It Cm panic Ar panic 2642The argument is the panic threshold, normally 1000 s. 2643If set to zero, 2644the panic sanity check is disabled and a clock offset of any value will 2645be accepted. 2646.It Cm step Ar step 2647The argument is the step threshold, which by default is 0.128 s. 2648It can 2649be set to any positive number in seconds. 2650If set to zero, step 2651adjustments will never occur. 2652Note: The kernel time discipline is 2653disabled if the step threshold is set to zero or greater than the 2654default. 2655.It Cm stepout Ar stepout 2656The argument is the stepout timeout, which by default is 900 s. 2657It can 2658be set to any positive number in seconds. 2659If set to zero, the stepout 2660pulses will not be suppressed. 2661.El 2662.It Xo Ic rlimit 2663.Oo 2664.Cm memlock Ar Nmegabytes | 2665.Cm stacksize Ar N4kPages 2666.Cm filenum Ar Nfiledescriptors 2667.Oc 2668.Xc 2669.Bl -tag -width indent 2670.It Cm memlock Ar Nmegabytes 2671Specify the number of megabytes of memory that can be allocated. 2672Probably only available under Linux, this option is useful 2673when dropping root (the 2674.Fl i 2675option). 2676The default is 32 megabytes. Setting this to zero will prevent any attemp to lock memory. 2677.It Cm stacksize Ar N4kPages 2678Specifies the maximum size of the process stack on systems with the 2679.It Cm filenum Ar Nfiledescriptors 2680Specifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default. 2681.Fn mlockall 2682function. 2683Defaults to 50 4k pages (200 4k pages in OpenBSD). 2684.El 2685.It Xo Ic trap Ar host_address 2686.Op Cm port Ar port_number 2687.Op Cm interface Ar interface_address 2688.Xc 2689This command configures a trap receiver at the given host 2690address and port number for sending messages with the specified 2691local interface address. 2692If the port number is unspecified, a value 2693of 18447 is used. 2694If the interface address is not specified, the 2695message is sent with a source address of the local interface the 2696message is sent through. 2697Note that on a multihomed host the 2698interface used may vary from time to time with routing changes. 2699.Pp 2700The trap receiver will generally log event messages and other 2701information from the server in a log file. 2702While such monitor 2703programs may also request their own trap dynamically, configuring a 2704trap receiver will ensure that no messages are lost when the server 2705is started. 2706.It Cm hop Ar ... 2707This command specifies a list of TTL values in increasing order, up to 8 2708values can be specified. 2709In manycast mode these values are used in turn in 2710an expanding-ring search. 2711The default is eight multiples of 32 starting at 271231. 2713.El 2714 _END_PROG_MDOC_DESCRIP; 2715}; 2716 2717doc-section = { 2718 ds-type = 'FILES'; 2719 ds-format = 'mdoc'; 2720 ds-text = <<- _END_MDOC_FILES 2721.Bl -tag -width /etc/ntp.drift -compact 2722.It Pa /etc/ntp.conf 2723the default name of the configuration file 2724.It Pa ntp.keys 2725private MD5 keys 2726.It Pa ntpkey 2727RSA private key 2728.It Pa ntpkey_ Ns Ar host 2729RSA public key 2730.It Pa ntp_dh 2731Diffie-Hellman agreement parameters 2732.El 2733 _END_MDOC_FILES; 2734}; 2735 2736doc-section = { 2737 ds-type = 'SEE ALSO'; 2738 ds-format = 'mdoc'; 2739 ds-text = <<- _END_MDOC_SEE_ALSO 2740.Xr ntpd 1ntpdmdoc , 2741.Xr ntpdc 1ntpdcmdoc , 2742.Xr ntpq 1ntpqmdoc 2743.Pp 2744In addition to the manual pages provided, 2745comprehensive documentation is available on the world wide web 2746at 2747.Li http://www.ntp.org/ . 2748A snapshot of this documentation is available in HTML format in 2749.Pa /usr/share/doc/ntp . 2750.Rs 2751.%A David L. Mills 2752.%T Network Time Protocol (Version 4) 2753.%O RFC5905 2754.Re 2755 _END_MDOC_SEE_ALSO; 2756}; 2757 2758doc-section = { 2759 ds-type = 'BUGS'; 2760 ds-format = 'mdoc'; 2761 ds-text = <<- _END_MDOC_BUGS 2762The syntax checking is not picky; some combinations of 2763ridiculous and even hilarious options and modes may not be 2764detected. 2765.Pp 2766The 2767.Pa ntpkey_ Ns Ar host 2768files are really digital 2769certificates. 2770These should be obtained via secure directory 2771services when they become universally available. 2772 _END_MDOC_BUGS; 2773}; 2774 2775doc-section = { 2776 ds-type = 'NOTES'; 2777 ds-format = 'mdoc'; 2778 ds-text = <<- _END_MDOC_NOTES 2779This document corresponds to version #VERSION# of NTP. 2780This document was derived from FreeBSD. 2781 _END_MDOC_NOTES; 2782}; 2783