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