1.Dd December 24 2013 2.Dt NTP_CONF 5 File Formats 3.Os SunOS 5.10 4.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) 5.\" 6.\" It has been AutoGen-ed December 24, 2013 at 11:38:23 AM by AutoGen 5.18.3pre5 7.\" From the definitions ntp.conf.def 8.\" and the template file agmdoc-cmd.tpl 9.Sh NAME 10.Nm ntp.conf 11.Nd Network Time Protocol (NTP) daemon configuration file format 12.Sh SYNOPSIS 13.Nm 14.Op Fl \-option\-name 15.Op Fl \-option\-name Ar value 16.Pp 17All arguments must be options. 18.Pp 19.Sh DESCRIPTION 20The 21.Nm 22configuration file is read at initial startup by the 23.Xr ntpd @NTPD_MS@ 24daemon in order to specify the synchronization sources, 25modes and other related information. 26Usually, it is installed in the 27.Pa /etc 28directory, 29but could be installed elsewhere 30(see the daemon's 31.Fl c 32command line option). 33.Pp 34The file format is similar to other 35.Ux 36configuration files. 37Comments begin with a 38.Ql # 39character and extend to the end of the line; 40blank lines are ignored. 41Configuration commands consist of an initial keyword 42followed by a list of arguments, 43some of which may be optional, separated by whitespace. 44Commands may not be continued over multiple lines. 45Arguments may be host names, 46host addresses written in numeric, dotted\-quad form, 47integers, floating point numbers (when specifying times in seconds) 48and text strings. 49.Pp 50The rest of this page describes the configuration and control options. 51The 52.Qq Notes on Configuring NTP and Setting up an NTP Subnet 53page 54(available as part of the HTML documentation 55provided in 56.Pa /usr/share/doc/ntp ) 57contains an extended discussion of these options. 58In addition to the discussion of general 59.Sx Configuration Options , 60there are sections describing the following supported functionality 61and the options used to control it: 62.Bl -bullet -offset indent 63.It 64.Sx Authentication Support 65.It 66.Sx Monitoring Support 67.It 68.Sx Access Control Support 69.It 70.Sx Automatic NTP Configuration Options 71.It 72.Sx Reference Clock Support 73.It 74.Sx Miscellaneous Options 75.El 76.Pp 77Following these is a section describing 78.Sx Miscellaneous Options . 79While there is a rich set of options available, 80the only required option is one or more 81.Ic pool , 82.Ic server , 83.Ic peer , 84.Ic broadcast 85or 86.Ic manycastclient 87commands. 88.Sh Configuration Support 89Following is a description of the configuration commands in 90NTPv4. 91These commands have the same basic functions as in NTPv3 and 92in some cases new functions and new arguments. 93There are two 94classes of commands, configuration commands that configure a 95persistent association with a remote server or peer or reference 96clock, and auxiliary commands that specify environmental variables 97that control various related operations. 98.Ss Configuration Commands 99The various modes are determined by the command keyword and the 100type of the required IP address. 101Addresses are classed by type as 102(s) a remote server or peer (IPv4 class A, B and C), (b) the 103broadcast address of a local interface, (m) a multicast address (IPv4 104class D), or (r) a reference clock address (127.127.x.x). 105Note that 106only those options applicable to each command are listed below. 107Use 108of options not listed may not be caught as an error, but may result 109in some weird and even destructive behavior. 110.Pp 111If the Basic Socket Interface Extensions for IPv6 (RFC\-2553) 112is detected, support for the IPv6 address family is generated 113in addition to the default support of the IPv4 address family. 114In a few cases, including the reslist billboard generated 115by ntpdc, IPv6 addresses are automatically generated. 116IPv6 addresses can be identified by the presence of colons 117.Dq \&: 118in the address field. 119IPv6 addresses can be used almost everywhere where 120IPv4 addresses can be used, 121with the exception of reference clock addresses, 122which are always IPv4. 123.Pp 124Note that in contexts where a host name is expected, a 125.Fl 4 126qualifier preceding 127the host name forces DNS resolution to the IPv4 namespace, 128while a 129.Fl 6 130qualifier forces DNS resolution to the IPv6 namespace. 131See IPv6 references for the 132equivalent classes for that address family. 133.Bl -tag -width indent 134.It Xo Ic pool Ar address 135.Op Cm burst 136.Op Cm iburst 137.Op Cm version Ar version 138.Op Cm prefer 139.Op Cm minpoll Ar minpoll 140.Op Cm maxpoll Ar maxpoll 141.Xc 142.It Xo Ic server Ar address 143.Op Cm key Ar key \&| Cm autokey 144.Op Cm burst 145.Op Cm iburst 146.Op Cm version Ar version 147.Op Cm prefer 148.Op Cm minpoll Ar minpoll 149.Op Cm maxpoll Ar maxpoll 150.Xc 151.It Xo Ic peer Ar address 152.Op Cm key Ar key \&| Cm autokey 153.Op Cm version Ar version 154.Op Cm prefer 155.Op Cm minpoll Ar minpoll 156.Op Cm maxpoll Ar maxpoll 157.Xc 158.It Xo Ic broadcast Ar address 159.Op Cm key Ar key \&| Cm autokey 160.Op Cm version Ar version 161.Op Cm prefer 162.Op Cm minpoll Ar minpoll 163.Op Cm ttl Ar ttl 164.Xc 165.It Xo Ic manycastclient Ar address 166.Op Cm key Ar key \&| Cm autokey 167.Op Cm version Ar version 168.Op Cm prefer 169.Op Cm minpoll Ar minpoll 170.Op Cm maxpoll Ar maxpoll 171.Op Cm ttl Ar ttl 172.Xc 173.El 174.Pp 175These five commands specify the time server name or address to 176be used and the mode in which to operate. 177The 178.Ar address 179can be 180either a DNS name or an IP address in dotted\-quad notation. 181Additional information on association behavior can be found in the 182.Qq Association Management 183page 184(available as part of the HTML documentation 185provided in 186.Pa /usr/share/doc/ntp ) . 187.Bl -tag -width indent 188.It Ic pool 189For type s addresses, this command mobilizes a persistent 190client mode association with a number of remote servers. 191In this mode the local clock can synchronized to the 192remote server, but the remote server can never be synchronized to 193the local clock. 194.It Ic server 195For type s and r addresses, this command mobilizes a persistent 196client mode association with the specified remote server or local 197radio clock. 198In this mode the local clock can synchronized to the 199remote server, but the remote server can never be synchronized to 200the local clock. 201This command should 202.Em not 203be used for type 204b or m addresses. 205.It Ic peer 206For type s addresses (only), this command mobilizes a 207persistent symmetric\-active mode association with the specified 208remote peer. 209In this mode the local clock can be synchronized to 210the remote peer or the remote peer can be synchronized to the local 211clock. 212This is useful in a network of servers where, depending on 213various failure scenarios, either the local or remote peer may be 214the better source of time. 215This command should NOT be used for type 216b, m or r addresses. 217.It Ic broadcast 218For type b and m addresses (only), this 219command mobilizes a persistent broadcast mode association. 220Multiple 221commands can be used to specify multiple local broadcast interfaces 222(subnets) and/or multiple multicast groups. 223Note that local 224broadcast messages go only to the interface associated with the 225subnet specified, but multicast messages go to all interfaces. 226In broadcast mode the local server sends periodic broadcast 227messages to a client population at the 228.Ar address 229specified, which is usually the broadcast address on (one of) the 230local network(s) or a multicast address assigned to NTP. 231The IANA 232has assigned the multicast group address IPv4 224.0.1.1 and 233IPv6 ff05::101 (site local) exclusively to 234NTP, but other nonconflicting addresses can be used to contain the 235messages within administrative boundaries. 236Ordinarily, this 237specification applies only to the local server operating as a 238sender; for operation as a broadcast client, see the 239.Ic broadcastclient 240or 241.Ic multicastclient 242commands 243below. 244.It Ic manycastclient 245For type m addresses (only), this command mobilizes a 246manycast client mode association for the multicast address 247specified. 248In this case a specific address must be supplied which 249matches the address used on the 250.Ic manycastserver 251command for 252the designated manycast servers. 253The NTP multicast address 254224.0.1.1 assigned by the IANA should NOT be used, unless specific 255means are taken to avoid spraying large areas of the Internet with 256these messages and causing a possibly massive implosion of replies 257at the sender. 258The 259.Ic manycastserver 260command specifies that the local server 261is to operate in client mode with the remote servers that are 262discovered as the result of broadcast/multicast messages. 263The 264client broadcasts a request message to the group address associated 265with the specified 266.Ar address 267and specifically enabled 268servers respond to these messages. 269The client selects the servers 270providing the best time and continues as with the 271.Ic server 272command. 273The remaining servers are discarded as if never 274heard. 275.El 276.Pp 277Options: 278.Bl -tag -width indent 279.It Cm autokey 280All packets sent to and received from the server or peer are to 281include authentication fields encrypted using the autokey scheme 282described in 283.Sx Authentication Options . 284.It Cm burst 285when the server is reachable, send a burst of eight packets 286instead of the usual one. 287The packet spacing is normally 2 s; 288however, the spacing between the first and second packets 289can be changed with the calldelay command to allow 290additional time for a modem or ISDN call to complete. 291This is designed to improve timekeeping quality 292with the 293.Ic server 294command and s addresses. 295.It Cm iburst 296When the server is unreachable, send a burst of eight packets 297instead of the usual one. 298The packet spacing is normally 2 s; 299however, the spacing between the first two packets can be 300changed with the calldelay command to allow 301additional time for a modem or ISDN call to complete. 302This is designed to speed the initial synchronization 303acquisition with the 304.Ic server 305command and s addresses and when 306.Xr ntpd @NTPD_MS@ 307is started with the 308.Fl q 309option. 310.It Cm key Ar key 311All packets sent to and received from the server or peer are to 312include authentication fields encrypted using the specified 313.Ar key 314identifier with values from 1 to 65534, inclusive. 315The 316default is to include no encryption field. 317.It Cm minpoll Ar minpoll 318.It Cm maxpoll Ar maxpoll 319These options specify the minimum and maximum poll intervals 320for NTP messages, as a power of 2 in seconds 321The maximum poll 322interval defaults to 10 (1,024 s), but can be increased by the 323.Cm maxpoll 324option to an upper limit of 17 (36.4 h). 325The 326minimum poll interval defaults to 6 (64 s), but can be decreased by 327the 328.Cm minpoll 329option to a lower limit of 4 (16 s). 330.It Cm noselect 331Marks the server as unused, except for display purposes. 332The server is discarded by the selection algroithm. 333.It Cm prefer 334Marks the server as preferred. 335All other things being equal, 336this host will be chosen for synchronization among a set of 337correctly operating hosts. 338See the 339.Qq Mitigation Rules and the prefer Keyword 340page 341(available as part of the HTML documentation 342provided in 343.Pa /usr/share/doc/ntp ) 344for further information. 345.It Cm ttl Ar ttl 346This option is used only with broadcast server and manycast 347client modes. 348It specifies the time\-to\-live 349.Ar ttl 350to 351use on broadcast server and multicast server and the maximum 352.Ar ttl 353for the expanding ring search with manycast 354client packets. 355Selection of the proper value, which defaults to 356127, is something of a black art and should be coordinated with the 357network administrator. 358.It Cm version Ar version 359Specifies the version number to be used for outgoing NTP 360packets. 361Versions 1\-4 are the choices, with version 4 the 362default. 363.El 364.Ss Auxiliary Commands 365.Bl -tag -width indent 366.It Ic broadcastclient 367This command enables reception of broadcast server messages to 368any local interface (type b) address. 369Upon receiving a message for 370the first time, the broadcast client measures the nominal server 371propagation delay using a brief client/server exchange with the 372server, then enters the broadcast client mode, in which it 373synchronizes to succeeding broadcast messages. 374Note that, in order 375to avoid accidental or malicious disruption in this mode, both the 376server and client should operate using symmetric\-key or public\-key 377authentication as described in 378.Sx Authentication Options . 379.It Ic manycastserver Ar address ... 380This command enables reception of manycast client messages to 381the multicast group address(es) (type m) specified. 382At least one 383address is required, but the NTP multicast address 224.0.1.1 384assigned by the IANA should NOT be used, unless specific means are 385taken to limit the span of the reply and avoid a possibly massive 386implosion at the original sender. 387Note that, in order to avoid 388accidental or malicious disruption in this mode, both the server 389and client should operate using symmetric\-key or public\-key 390authentication as described in 391.Sx Authentication Options . 392.It Ic multicastclient Ar address ... 393This command enables reception of multicast server messages to 394the multicast group address(es) (type m) specified. 395Upon receiving 396a message for the first time, the multicast client measures the 397nominal server propagation delay using a brief client/server 398exchange with the server, then enters the broadcast client mode, in 399which it synchronizes to succeeding multicast messages. 400Note that, 401in order to avoid accidental or malicious disruption in this mode, 402both the server and client should operate using symmetric\-key or 403public\-key authentication as described in 404.Sx Authentication Options . 405.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 @NTPDC_MS@ 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 @NTPQ_MS@ 557and 558.Xr ntpdc @NTPDC_MS@ 559utility programs. 560.Pp 561When 562.Xr ntpd @NTPD_MS@ 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 @NTPDC_MS@ . 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 @NTPDC_MS@ 583utility, while the 584.Ic controlkey 585command selects the key used as the password for the 586.Xr ntpq @NTPQ_MS@ 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 @NTPQ_MS@ 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 @NTPQ_MS@ 793and 794.Xr ntpdc @NTPDC_MS@ 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 @NTPQ_MS@ 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 @NTPD_MS@ , 919.Xr ntpq @NTPQ_MS@ 920and 921.Xr ntpdc @NTPDC_MS@ 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 @NTPDC_MS@ 934utility program, which uses a 935proprietary protocol specific to this implementation of 936.Xr ntpd @NTPD_MS@ . 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 @NTPQ_MS@ 958and 959.Xr ntpdc @NTPDC_MS@ 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 @NTPD_MS@ 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, four 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 @NTPDC_MS@ 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 @NTPD_MS@ 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 @NTPD_MS@ 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 @NTPD_MS@ 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 @NTPQ_MS@ 1529and 1530.Xr ntpdc @NTPDC_MS@ 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 @NTPD_MS@ . 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 @NTPQ_MS@ 1562and 1563.Xr ntpdc @NTPDC_MS@ 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 @NTPQ_MS@ 1571and 1572.Xr ntpdc @NTPDC_MS@ 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. 1580.It Cm noserve 1581Deny all packets except 1582.Xr ntpq @NTPQ_MS@ 1583and 1584.Xr ntpdc @NTPDC_MS@ 1585queries. 1586.It Cm notrap 1587Decline to provide mode 6 control message trap service to matching 1588hosts. 1589The trap service is a subsystem of the ntpdq control message 1590protocol which is intended for use by remote event logging programs. 1591.It Cm notrust 1592Deny service unless the packet is cryptographically authenticated. 1593.It Cm ntpport 1594This is actually a match algorithm modifier, rather than a 1595restriction flag. 1596Its presence causes the restriction entry to be 1597matched only if the source port in the packet is the standard NTP 1598UDP port (123). 1599Both 1600.Cm ntpport 1601and 1602.Cm non\-ntpport 1603may 1604be specified. 1605The 1606.Cm ntpport 1607is considered more specific and 1608is sorted later in the list. 1609.It Cm version 1610Deny packets that do not match the current NTP version. 1611.El 1612.Pp 1613Default restriction list entries with the flags ignore, interface, 1614ntpport, for each of the local host's interface addresses are 1615inserted into the table at startup to prevent the server 1616from attempting to synchronize to its own time. 1617A default entry is also always present, though if it is 1618otherwise unconfigured; no flags are associated 1619with the default entry (i.e., everything besides your own 1620NTP server is unrestricted). 1621.El 1622.Sh Automatic NTP Configuration Options 1623.Ss Manycasting 1624Manycasting is a automatic discovery and configuration paradigm 1625new to NTPv4. 1626It is intended as a means for a multicast client 1627to troll the nearby network neighborhood to find cooperating 1628manycast servers, validate them using cryptographic means 1629and evaluate their time values with respect to other servers 1630that might be lurking in the vicinity. 1631The intended result is that each manycast client mobilizes 1632client associations with some number of the "best" 1633of the nearby manycast servers, yet automatically reconfigures 1634to sustain this number of servers should one or another fail. 1635.Pp 1636Note that the manycasting paradigm does not coincide 1637with the anycast paradigm described in RFC\-1546, 1638which is designed to find a single server from a clique 1639of servers providing the same service. 1640The manycast paradigm is designed to find a plurality 1641of redundant servers satisfying defined optimality criteria. 1642.Pp 1643Manycasting can be used with either symmetric key 1644or public key cryptography. 1645The public key infrastructure (PKI) 1646offers the best protection against compromised keys 1647and is generally considered stronger, at least with relatively 1648large key sizes. 1649It is implemented using the Autokey protocol and 1650the OpenSSL cryptographic library available from 1651.Li http://www.openssl.org/ . 1652The library can also be used with other NTPv4 modes 1653as well and is highly recommended, especially for broadcast modes. 1654.Pp 1655A persistent manycast client association is configured 1656using the manycastclient command, which is similar to the 1657server command but with a multicast (IPv4 class 1658.Cm D 1659or IPv6 prefix 1660.Cm FF ) 1661group address. 1662The IANA has designated IPv4 address 224.1.1.1 1663and IPv6 address FF05::101 (site local) for NTP. 1664When more servers are needed, it broadcasts manycast 1665client messages to this address at the minimum feasible rate 1666and minimum feasible time\-to\-live (TTL) hops, depending 1667on how many servers have already been found. 1668There can be as many manycast client associations 1669as different group address, each one serving as a template 1670for a future ephemeral unicast client/server association. 1671.Pp 1672Manycast servers configured with the 1673.Ic manycastserver 1674command listen on the specified group address for manycast 1675client messages. 1676Note the distinction between manycast client, 1677which actively broadcasts messages, and manycast server, 1678which passively responds to them. 1679If a manycast server is 1680in scope of the current TTL and is itself synchronized 1681to a valid source and operating at a stratum level equal 1682to or lower than the manycast client, it replies to the 1683manycast client message with an ordinary unicast server message. 1684.Pp 1685The manycast client receiving this message mobilizes 1686an ephemeral client/server association according to the 1687matching manycast client template, but only if cryptographically 1688authenticated and the server stratum is less than or equal 1689to the client stratum. 1690Authentication is explicitly required 1691and either symmetric key or public key (Autokey) can be used. 1692Then, the client polls the server at its unicast address 1693in burst mode in order to reliably set the host clock 1694and validate the source. 1695This normally results 1696in a volley of eight client/server at 2\-s intervals 1697during which both the synchronization and cryptographic 1698protocols run concurrently. 1699Following the volley, 1700the client runs the NTP intersection and clustering 1701algorithms, which act to discard all but the "best" 1702associations according to stratum and synchronization 1703distance. 1704The surviving associations then continue 1705in ordinary client/server mode. 1706.Pp 1707The manycast client polling strategy is designed to reduce 1708as much as possible the volume of manycast client messages 1709and the effects of implosion due to near\-simultaneous 1710arrival of manycast server messages. 1711The strategy is determined by the 1712.Ic manycastclient , 1713.Ic tos 1714and 1715.Ic ttl 1716configuration commands. 1717The manycast poll interval is 1718normally eight times the system poll interval, 1719which starts out at the 1720.Cm minpoll 1721value specified in the 1722.Ic manycastclient , 1723command and, under normal circumstances, increments to the 1724.Cm maxpolll 1725value specified in this command. 1726Initially, the TTL is 1727set at the minimum hops specified by the ttl command. 1728At each retransmission the TTL is increased until reaching 1729the maximum hops specified by this command or a sufficient 1730number client associations have been found. 1731Further retransmissions use the same TTL. 1732.Pp 1733The quality and reliability of the suite of associations 1734discovered by the manycast client is determined by the NTP 1735mitigation algorithms and the 1736.Cm minclock 1737and 1738.Cm minsane 1739values specified in the 1740.Ic tos 1741configuration command. 1742At least 1743.Cm minsane 1744candidate servers must be available and the mitigation 1745algorithms produce at least 1746.Cm minclock 1747survivors in order to synchronize the clock. 1748Byzantine agreement principles require at least four 1749candidates in order to correctly discard a single falseticker. 1750For legacy purposes, 1751.Cm minsane 1752defaults to 1 and 1753.Cm minclock 1754defaults to 3. 1755For manycast service 1756.Cm minsane 1757should be explicitly set to 4, assuming at least that 1758number of servers are available. 1759.Pp 1760If at least 1761.Cm minclock 1762servers are found, the manycast poll interval is immediately 1763set to eight times 1764.Cm maxpoll . 1765If less than 1766.Cm minclock 1767servers are found when the TTL has reached the maximum hops, 1768the manycast poll interval is doubled. 1769For each transmission 1770after that, the poll interval is doubled again until 1771reaching the maximum of eight times 1772.Cm maxpoll . 1773Further transmissions use the same poll interval and 1774TTL values. 1775Note that while all this is going on, 1776each client/server association found is operating normally 1777it the system poll interval. 1778.Pp 1779Administratively scoped multicast boundaries are normally 1780specified by the network router configuration and, 1781in the case of IPv6, the link/site scope prefix. 1782By default, the increment for TTL hops is 32 starting 1783from 31; however, the 1784.Ic ttl 1785configuration command can be 1786used to modify the values to match the scope rules. 1787.Pp 1788It is often useful to narrow the range of acceptable 1789servers which can be found by manycast client associations. 1790Because manycast servers respond only when the client 1791stratum is equal to or greater than the server stratum, 1792primary (stratum 1) servers fill find only primary servers 1793in TTL range, which is probably the most common objective. 1794However, unless configured otherwise, all manycast clients 1795in TTL range will eventually find all primary servers 1796in TTL range, which is probably not the most common 1797objective in large networks. 1798The 1799.Ic tos 1800command can be used to modify this behavior. 1801Servers with stratum below 1802.Cm floor 1803or above 1804.Cm ceiling 1805specified in the 1806.Ic tos 1807command are strongly discouraged during the selection 1808process; however, these servers may be temporally 1809accepted if the number of servers within TTL range is 1810less than 1811.Cm minclock . 1812.Pp 1813The above actions occur for each manycast client message, 1814which repeats at the designated poll interval. 1815However, once the ephemeral client association is mobilized, 1816subsequent manycast server replies are discarded, 1817since that would result in a duplicate association. 1818If during a poll interval the number of client associations 1819falls below 1820.Cm minclock , 1821all manycast client prototype associations are reset 1822to the initial poll interval and TTL hops and operation 1823resumes from the beginning. 1824It is important to avoid 1825frequent manycast client messages, since each one requires 1826all manycast servers in TTL range to respond. 1827The result could well be an implosion, either minor or major, 1828depending on the number of servers in range. 1829The recommended value for 1830.Cm maxpoll 1831is 12 (4,096 s). 1832.Pp 1833It is possible and frequently useful to configure a host 1834as both manycast client and manycast server. 1835A number of hosts configured this way and sharing a common 1836group address will automatically organize themselves 1837in an optimum configuration based on stratum and 1838synchronization distance. 1839For example, consider an NTP 1840subnet of two primary servers and a hundred or more 1841dependent clients. 1842With two exceptions, all servers 1843and clients have identical configuration files including both 1844.Ic multicastclient 1845and 1846.Ic multicastserver 1847commands using, for instance, multicast group address 1848239.1.1.1. 1849The only exception is that each primary server 1850configuration file must include commands for the primary 1851reference source such as a GPS receiver. 1852.Pp 1853The remaining configuration files for all secondary 1854servers and clients have the same contents, except for the 1855.Ic tos 1856command, which is specific for each stratum level. 1857For stratum 1 and stratum 2 servers, that command is 1858not necessary. 1859For stratum 3 and above servers the 1860.Cm floor 1861value is set to the intended stratum number. 1862Thus, all stratum 3 configuration files are identical, 1863all stratum 4 files are identical and so forth. 1864.Pp 1865Once operations have stabilized in this scenario, 1866the primary servers will find the primary reference source 1867and each other, since they both operate at the same 1868stratum (1), but not with any secondary server or client, 1869since these operate at a higher stratum. 1870The secondary 1871servers will find the servers at the same stratum level. 1872If one of the primary servers loses its GPS receiver, 1873it will continue to operate as a client and other clients 1874will time out the corresponding association and 1875re\-associate accordingly. 1876.Pp 1877Some administrators prefer to avoid running 1878.Xr ntpd @NTPD_MS@ 1879continuously and run either 1880.Xr ntpdate 8 1881or 1882.Xr ntpd @NTPD_MS@ 1883.Fl q 1884as a cron job. 1885In either case the servers must be 1886configured in advance and the program fails if none are 1887available when the cron job runs. 1888A really slick 1889application of manycast is with 1890.Xr ntpd @NTPD_MS@ 1891.Fl q . 1892The program wakes up, scans the local landscape looking 1893for the usual suspects, selects the best from among 1894the rascals, sets the clock and then departs. 1895Servers do not have to be configured in advance and 1896all clients throughout the network can have the same 1897configuration file. 1898.Ss Manycast Interactions with Autokey 1899Each time a manycast client sends a client mode packet 1900to a multicast group address, all manycast servers 1901in scope generate a reply including the host name 1902and status word. 1903The manycast clients then run 1904the Autokey protocol, which collects and verifies 1905all certificates involved. 1906Following the burst interval 1907all but three survivors are cast off, 1908but the certificates remain in the local cache. 1909It often happens that several complete signing trails 1910from the client to the primary servers are collected in this way. 1911.Pp 1912About once an hour or less often if the poll interval 1913exceeds this, the client regenerates the Autokey key list. 1914This is in general transparent in client/server mode. 1915However, about once per day the server private value 1916used to generate cookies is refreshed along with all 1917manycast client associations. 1918In this case all 1919cryptographic values including certificates is refreshed. 1920If a new certificate has been generated since 1921the last refresh epoch, it will automatically revoke 1922all prior certificates that happen to be in the 1923certificate cache. 1924At the same time, the manycast 1925scheme starts all over from the beginning and 1926the expanding ring shrinks to the minimum and increments 1927from there while collecting all servers in scope. 1928.Ss Manycast Options 1929.Bl -tag -width indent 1930.It Xo Ic tos 1931.Oo 1932.Cm ceiling Ar ceiling | 1933.Cm cohort { 0 | 1 } | 1934.Cm floor Ar floor | 1935.Cm minclock Ar minclock | 1936.Cm minsane Ar minsane 1937.Oc 1938.Xc 1939This command affects the clock selection and clustering 1940algorithms. 1941It can be used to select the quality and 1942quantity of peers used to synchronize the system clock 1943and is most useful in manycast mode. 1944The variables operate 1945as follows: 1946.Bl -tag -width indent 1947.It Cm ceiling Ar ceiling 1948Peers with strata above 1949.Cm ceiling 1950will be discarded if there are at least 1951.Cm minclock 1952peers remaining. 1953This value defaults to 15, but can be changed 1954to any number from 1 to 15. 1955.It Cm cohort Bro 0 | 1 Brc 1956This is a binary flag which enables (0) or disables (1) 1957manycast server replies to manycast clients with the same 1958stratum level. 1959This is useful to reduce implosions where 1960large numbers of clients with the same stratum level 1961are present. 1962The default is to enable these replies. 1963.It Cm floor Ar floor 1964Peers with strata below 1965.Cm floor 1966will be discarded if there are at least 1967.Cm minclock 1968peers remaining. 1969This value defaults to 1, but can be changed 1970to any number from 1 to 15. 1971.It Cm minclock Ar minclock 1972The clustering algorithm repeatedly casts out outlyer 1973associations until no more than 1974.Cm minclock 1975associations remain. 1976This value defaults to 3, 1977but can be changed to any number from 1 to the number of 1978configured sources. 1979.It Cm minsane Ar minsane 1980This is the minimum number of candidates available 1981to the clock selection algorithm in order to produce 1982one or more truechimers for the clustering algorithm. 1983If fewer than this number are available, the clock is 1984undisciplined and allowed to run free. 1985The default is 1 1986for legacy purposes. 1987However, according to principles of 1988Byzantine agreement, 1989.Cm minsane 1990should be at least 4 in order to detect and discard 1991a single falseticker. 1992.El 1993.It Cm ttl Ar hop ... 1994This command specifies a list of TTL values in increasing 1995order, up to 8 values can be specified. 1996In manycast mode these values are used in turn 1997in an expanding\-ring search. 1998The default is eight 1999multiples of 32 starting at 31. 2000.El 2001.Sh Reference Clock Support 2002The NTP Version 4 daemon supports some three dozen different radio, 2003satellite and modem reference clocks plus a special pseudo\-clock 2004used for backup or when no other clock source is available. 2005Detailed descriptions of individual device drivers and options can 2006be found in the 2007.Qq Reference Clock Drivers 2008page 2009(available as part of the HTML documentation 2010provided in 2011.Pa /usr/share/doc/ntp ) . 2012Additional information can be found in the pages linked 2013there, including the 2014.Qq Debugging Hints for Reference Clock Drivers 2015and 2016.Qq How To Write a Reference Clock Driver 2017pages 2018(available as part of the HTML documentation 2019provided in 2020.Pa /usr/share/doc/ntp ) . 2021In addition, support for a PPS 2022signal is available as described in the 2023.Qq Pulse\-per\-second (PPS) Signal Interfacing 2024page 2025(available as part of the HTML documentation 2026provided in 2027.Pa /usr/share/doc/ntp ) . 2028Many 2029drivers support special line discipline/streams modules which can 2030significantly improve the accuracy using the driver. 2031These are 2032described in the 2033.Qq Line Disciplines and Streams Drivers 2034page 2035(available as part of the HTML documentation 2036provided in 2037.Pa /usr/share/doc/ntp ) . 2038.Pp 2039A reference clock will generally (though not always) be a radio 2040timecode receiver which is synchronized to a source of standard 2041time such as the services offered by the NRC in Canada and NIST and 2042USNO in the US. 2043The interface between the computer and the timecode 2044receiver is device dependent, but is usually a serial port. 2045A 2046device driver specific to each reference clock must be selected and 2047compiled in the distribution; however, most common radio, satellite 2048and modem clocks are included by default. 2049Note that an attempt to 2050configure a reference clock when the driver has not been compiled 2051or the hardware port has not been appropriately configured results 2052in a scalding remark to the system log file, but is otherwise non 2053hazardous. 2054.Pp 2055For the purposes of configuration, 2056.Xr ntpd @NTPD_MS@ 2057treats 2058reference clocks in a manner analogous to normal NTP peers as much 2059as possible. 2060Reference clocks are identified by a syntactically 2061correct but invalid IP address, in order to distinguish them from 2062normal NTP peers. 2063Reference clock addresses are of the form 2064.Sm off 2065.Li 127.127. Ar t . Ar u , 2066.Sm on 2067where 2068.Ar t 2069is an integer 2070denoting the clock type and 2071.Ar u 2072indicates the unit 2073number in the range 0\-3. 2074While it may seem overkill, it is in fact 2075sometimes useful to configure multiple reference clocks of the same 2076type, in which case the unit numbers must be unique. 2077.Pp 2078The 2079.Ic server 2080command is used to configure a reference 2081clock, where the 2082.Ar address 2083argument in that command 2084is the clock address. 2085The 2086.Cm key , 2087.Cm version 2088and 2089.Cm ttl 2090options are not used for reference clock support. 2091The 2092.Cm mode 2093option is added for reference clock support, as 2094described below. 2095The 2096.Cm prefer 2097option can be useful to 2098persuade the server to cherish a reference clock with somewhat more 2099enthusiasm than other reference clocks or peers. 2100Further 2101information on this option can be found in the 2102.Qq Mitigation Rules and the prefer Keyword 2103(available as part of the HTML documentation 2104provided in 2105.Pa /usr/share/doc/ntp ) 2106page. 2107The 2108.Cm minpoll 2109and 2110.Cm maxpoll 2111options have 2112meaning only for selected clock drivers. 2113See the individual clock 2114driver document pages for additional information. 2115.Pp 2116The 2117.Ic fudge 2118command is used to provide additional 2119information for individual clock drivers and normally follows 2120immediately after the 2121.Ic server 2122command. 2123The 2124.Ar address 2125argument specifies the clock address. 2126The 2127.Cm refid 2128and 2129.Cm stratum 2130options can be used to 2131override the defaults for the device. 2132There are two optional 2133device\-dependent time offsets and four flags that can be included 2134in the 2135.Ic fudge 2136command as well. 2137.Pp 2138The stratum number of a reference clock is by default zero. 2139Since the 2140.Xr ntpd @NTPD_MS@ 2141daemon adds one to the stratum of each 2142peer, a primary server ordinarily displays an external stratum of 2143one. 2144In order to provide engineered backups, it is often useful to 2145specify the reference clock stratum as greater than zero. 2146The 2147.Cm stratum 2148option is used for this purpose. 2149Also, in cases 2150involving both a reference clock and a pulse\-per\-second (PPS) 2151discipline signal, it is useful to specify the reference clock 2152identifier as other than the default, depending on the driver. 2153The 2154.Cm refid 2155option is used for this purpose. 2156Except where noted, 2157these options apply to all clock drivers. 2158.Ss Reference Clock Commands 2159.Bl -tag -width indent 2160.It Xo Ic server 2161.Sm off 2162.Li 127.127. Ar t . Ar u 2163.Sm on 2164.Op Cm prefer 2165.Op Cm mode Ar int 2166.Op Cm minpoll Ar int 2167.Op Cm maxpoll Ar int 2168.Xc 2169This command can be used to configure reference clocks in 2170special ways. 2171The options are interpreted as follows: 2172.Bl -tag -width indent 2173.It Cm prefer 2174Marks the reference clock as preferred. 2175All other things being 2176equal, this host will be chosen for synchronization among a set of 2177correctly operating hosts. 2178See the 2179.Qq Mitigation Rules and the prefer Keyword 2180page 2181(available as part of the HTML documentation 2182provided in 2183.Pa /usr/share/doc/ntp ) 2184for further information. 2185.It Cm mode Ar int 2186Specifies a mode number which is interpreted in a 2187device\-specific fashion. 2188For instance, it selects a dialing 2189protocol in the ACTS driver and a device subtype in the 2190parse 2191drivers. 2192.It Cm minpoll Ar int 2193.It Cm maxpoll Ar int 2194These options specify the minimum and maximum polling interval 2195for reference clock messages, as a power of 2 in seconds 2196For 2197most directly connected reference clocks, both 2198.Cm minpoll 2199and 2200.Cm maxpoll 2201default to 6 (64 s). 2202For modem reference clocks, 2203.Cm minpoll 2204defaults to 10 (17.1 m) and 2205.Cm maxpoll 2206defaults to 14 (4.5 h). 2207The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2208.El 2209.It Xo Ic fudge 2210.Sm off 2211.Li 127.127. Ar t . Ar u 2212.Sm on 2213.Op Cm time1 Ar sec 2214.Op Cm time2 Ar sec 2215.Op Cm stratum Ar int 2216.Op Cm refid Ar string 2217.Op Cm mode Ar int 2218.Op Cm flag1 Cm 0 \&| Cm 1 2219.Op Cm flag2 Cm 0 \&| Cm 1 2220.Op Cm flag3 Cm 0 \&| Cm 1 2221.Op Cm flag4 Cm 0 \&| Cm 1 2222.Xc 2223This command can be used to configure reference clocks in 2224special ways. 2225It must immediately follow the 2226.Ic server 2227command which configures the driver. 2228Note that the same capability 2229is possible at run time using the 2230.Xr ntpdc @NTPDC_MS@ 2231program. 2232The options are interpreted as 2233follows: 2234.Bl -tag -width indent 2235.It Cm time1 Ar sec 2236Specifies a constant to be added to the time offset produced by 2237the driver, a fixed\-point decimal number in seconds. 2238This is used 2239as a calibration constant to adjust the nominal time offset of a 2240particular clock to agree with an external standard, such as a 2241precision PPS signal. 2242It also provides a way to correct a 2243systematic error or bias due to serial port or operating system 2244latencies, different cable lengths or receiver internal delay. 2245The 2246specified offset is in addition to the propagation delay provided 2247by other means, such as internal DIPswitches. 2248Where a calibration 2249for an individual system and driver is available, an approximate 2250correction is noted in the driver documentation pages. 2251Note: in order to facilitate calibration when more than one 2252radio clock or PPS signal is supported, a special calibration 2253feature is available. 2254It takes the form of an argument to the 2255.Ic enable 2256command described in 2257.Sx Miscellaneous Options 2258page and operates as described in the 2259.Qq Reference Clock Drivers 2260page 2261(available as part of the HTML documentation 2262provided in 2263.Pa /usr/share/doc/ntp ) . 2264.It Cm time2 Ar secs 2265Specifies a fixed\-point decimal number in seconds, which is 2266interpreted in a driver\-dependent way. 2267See the descriptions of 2268specific drivers in the 2269.Qq Reference Clock Drivers 2270page 2271(available as part of the HTML documentation 2272provided in 2273.Pa /usr/share/doc/ntp ) . 2274.It Cm stratum Ar int 2275Specifies the stratum number assigned to the driver, an integer 2276between 0 and 15. 2277This number overrides the default stratum number 2278ordinarily assigned by the driver itself, usually zero. 2279.It Cm refid Ar string 2280Specifies an ASCII string of from one to four characters which 2281defines the reference identifier used by the driver. 2282This string 2283overrides the default identifier ordinarily assigned by the driver 2284itself. 2285.It Cm mode Ar int 2286Specifies a mode number which is interpreted in a 2287device\-specific fashion. 2288For instance, it selects a dialing 2289protocol in the ACTS driver and a device subtype in the 2290parse 2291drivers. 2292.It Cm flag1 Cm 0 \&| Cm 1 2293.It Cm flag2 Cm 0 \&| Cm 1 2294.It Cm flag3 Cm 0 \&| Cm 1 2295.It Cm flag4 Cm 0 \&| Cm 1 2296These four flags are used for customizing the clock driver. 2297The 2298interpretation of these values, and whether they are used at all, 2299is a function of the particular clock driver. 2300However, by 2301convention 2302.Cm flag4 2303is used to enable recording monitoring 2304data to the 2305.Cm clockstats 2306file configured with the 2307.Ic filegen 2308command. 2309Further information on the 2310.Ic filegen 2311command can be found in 2312.Sx Monitoring Options . 2313.El 2314.El 2315.Sh Miscellaneous Options 2316.Bl -tag -width indent 2317.It Ic broadcastdelay Ar seconds 2318The broadcast and multicast modes require a special calibration 2319to determine the network delay between the local and remote 2320servers. 2321Ordinarily, this is done automatically by the initial 2322protocol exchanges between the client and server. 2323In some cases, 2324the calibration procedure may fail due to network or server access 2325controls, for example. 2326This command specifies the default delay to 2327be used under these circumstances. 2328Typically (for Ethernet), a 2329number between 0.003 and 0.007 seconds is appropriate. 2330The default 2331when this command is not used is 0.004 seconds. 2332.It Ic calldelay Ar delay 2333This option controls the delay in seconds between the first and second 2334packets sent in burst or iburst mode to allow additional time for a modem 2335or ISDN call to complete. 2336.It Ic driftfile Ar driftfile 2337This command specifies the complete path and name of the file used to 2338record the frequency of the local clock oscillator. 2339This is the same 2340operation as the 2341.Fl f 2342command line option. 2343If the file exists, it is read at 2344startup in order to set the initial frequency and then updated once per 2345hour with the current frequency computed by the daemon. 2346If the file name is 2347specified, but the file itself does not exist, the starts with an initial 2348frequency of zero and creates the file when writing it for the first time. 2349If this command is not given, the daemon will always start with an initial 2350frequency of zero. 2351.Pp 2352The file format consists of a single line containing a single 2353floating point number, which records the frequency offset measured 2354in parts\-per\-million (PPM). 2355The file is updated by first writing 2356the current drift value into a temporary file and then renaming 2357this file to replace the old version. 2358This implies that 2359.Xr ntpd @NTPD_MS@ 2360must have write permission for the directory the 2361drift file is located in, and that file system links, symbolic or 2362otherwise, should be avoided. 2363.It Xo Ic enable 2364.Oo 2365.Cm auth | Cm bclient | 2366.Cm calibrate | Cm kernel | 2367.Cm monitor | Cm ntp | 2368.Cm pps | Cm stats 2369.Oc 2370.Xc 2371.It Xo Ic disable 2372.Oo 2373.Cm auth | Cm bclient | 2374.Cm calibrate | Cm kernel | 2375.Cm monitor | Cm ntp | 2376.Cm pps | Cm stats 2377.Oc 2378.Xc 2379Provides a way to enable or disable various server options. 2380Flags not mentioned are unaffected. 2381Note that all of these flags 2382can be controlled remotely using the 2383.Xr ntpdc @NTPDC_MS@ 2384utility program. 2385.Bl -tag -width indent 2386.It Cm auth 2387Enables the server to synchronize with unconfigured peers only if the 2388peer has been correctly authenticated using either public key or 2389private key cryptography. 2390The default for this flag is 2391.Ic enable . 2392.It Cm bclient 2393Enables the server to listen for a message from a broadcast or 2394multicast server, as in the 2395.Ic multicastclient 2396command with default 2397address. 2398The default for this flag is 2399.Ic disable . 2400.It Cm calibrate 2401Enables the calibrate feature for reference clocks. 2402The default for 2403this flag is 2404.Ic disable . 2405.It Cm kernel 2406Enables the kernel time discipline, if available. 2407The default for this 2408flag is 2409.Ic enable 2410if support is available, otherwise 2411.Ic disable . 2412.It Cm monitor 2413Enables the monitoring facility. 2414See the 2415.Xr ntpdc @NTPDC_MS@ 2416program 2417and the 2418.Ic monlist 2419command or further information. 2420The 2421default for this flag is 2422.Ic enable . 2423.It Cm ntp 2424Enables time and frequency discipline. 2425In effect, this switch opens and 2426closes the feedback loop, which is useful for testing. 2427The default for 2428this flag is 2429.Ic enable . 2430.It Cm pps 2431Enables the pulse\-per\-second (PPS) signal when frequency and time is 2432disciplined by the precision time kernel modifications. 2433See the 2434.Qq A Kernel Model for Precision Timekeeping 2435(available as part of the HTML documentation 2436provided in 2437.Pa /usr/share/doc/ntp ) 2438page for further information. 2439The default for this flag is 2440.Ic disable . 2441.It Cm stats 2442Enables the statistics facility. 2443See the 2444.Sx Monitoring Options 2445section for further information. 2446The default for this flag is 2447.Ic disable . 2448.El 2449.It Ic includefile Ar includefile 2450This command allows additional configuration commands 2451to be included from a separate file. 2452Include files may 2453be nested to a depth of five; upon reaching the end of any 2454include file, command processing resumes in the previous 2455configuration file. 2456This option is useful for sites that run 2457.Xr ntpd @NTPD_MS@ 2458on multiple hosts, with (mostly) common options (e.g., a 2459restriction list). 2460.It Ic logconfig Ar configkeyword 2461This command controls the amount and type of output written to 2462the system 2463.Xr syslog 3 2464facility or the alternate 2465.Ic logfile 2466log file. 2467By default, all output is turned on. 2468All 2469.Ar configkeyword 2470keywords can be prefixed with 2471.Ql = , 2472.Ql + 2473and 2474.Ql \- , 2475where 2476.Ql = 2477sets the 2478.Xr syslog 3 2479priority mask, 2480.Ql + 2481adds and 2482.Ql \- 2483removes 2484messages. 2485.Xr syslog 3 2486messages can be controlled in four 2487classes 2488.Po 2489.Cm clock , 2490.Cm peer , 2491.Cm sys 2492and 2493.Cm sync 2494.Pc . 2495Within these classes four types of messages can be 2496controlled: informational messages 2497.Po 2498.Cm info 2499.Pc , 2500event messages 2501.Po 2502.Cm events 2503.Pc , 2504statistics messages 2505.Po 2506.Cm statistics 2507.Pc 2508and 2509status messages 2510.Po 2511.Cm status 2512.Pc . 2513.Pp 2514Configuration keywords are formed by concatenating the message class with 2515the event class. 2516The 2517.Cm all 2518prefix can be used instead of a message class. 2519A 2520message class may also be followed by the 2521.Cm all 2522keyword to enable/disable all 2523messages of the respective message class.Thus, a minimal log configuration 2524could look like this: 2525.Bd -literal 2526logconfig =syncstatus +sysevents 2527.Ed 2528.Pp 2529This would just list the synchronizations state of 2530.Xr ntpd @NTPD_MS@ 2531and the major system events. 2532For a simple reference server, the 2533following minimum message configuration could be useful: 2534.Bd -literal 2535logconfig =syncall +clockall 2536.Ed 2537.Pp 2538This configuration will list all clock information and 2539synchronization information. 2540All other events and messages about 2541peers, system events and so on is suppressed. 2542.It Ic logfile Ar logfile 2543This command specifies the location of an alternate log file to 2544be used instead of the default system 2545.Xr syslog 3 2546facility. 2547This is the same operation as the \-l command line option. 2548.It Ic setvar Ar variable Op Cm default 2549This command adds an additional system variable. 2550These 2551variables can be used to distribute additional information such as 2552the access policy. 2553If the variable of the form 2554.Sm off 2555.Va name = Ar value 2556.Sm on 2557is followed by the 2558.Cm default 2559keyword, the 2560variable will be listed as part of the default system variables 2561.Po 2562.Xr ntpq @NTPQ_MS@ 2563.Ic rv 2564command 2565.Pc ) . 2566These additional variables serve 2567informational purposes only. 2568They are not related to the protocol 2569other that they can be listed. 2570The known protocol variables will 2571always override any variables defined via the 2572.Ic setvar 2573mechanism. 2574There are three special variables that contain the names 2575of all variable of the same group. 2576The 2577.Va sys_var_list 2578holds 2579the names of all system variables. 2580The 2581.Va peer_var_list 2582holds 2583the names of all peer variables and the 2584.Va clock_var_list 2585holds the names of the reference clock variables. 2586.It Xo Ic tinker 2587.Oo 2588.Cm allan Ar allan | 2589.Cm dispersion Ar dispersion | 2590.Cm freq Ar freq | 2591.Cm huffpuff Ar huffpuff | 2592.Cm panic Ar panic | 2593.Cm step Ar srep | 2594.Cm stepout Ar stepout 2595.Oc 2596.Xc 2597This command can be used to alter several system variables in 2598very exceptional circumstances. 2599It should occur in the 2600configuration file before any other configuration options. 2601The 2602default values of these variables have been carefully optimized for 2603a wide range of network speeds and reliability expectations. 2604In 2605general, they interact in intricate ways that are hard to predict 2606and some combinations can result in some very nasty behavior. 2607Very 2608rarely is it necessary to change the default values; but, some 2609folks cannot resist twisting the knobs anyway and this command is 2610for them. 2611Emphasis added: twisters are on their own and can expect 2612no help from the support group. 2613.Pp 2614The variables operate as follows: 2615.Bl -tag -width indent 2616.It Cm allan Ar allan 2617The argument becomes the new value for the minimum Allan 2618intercept, which is a parameter of the PLL/FLL clock discipline 2619algorithm. 2620The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2621limit. 2622.It Cm dispersion Ar dispersion 2623The argument becomes the new value for the dispersion increase rate, 2624normally .000015 s/s. 2625.It Cm freq Ar freq 2626The argument becomes the initial value of the frequency offset in 2627parts\-per\-million. 2628This overrides the value in the frequency file, if 2629present, and avoids the initial training state if it is not. 2630.It Cm huffpuff Ar huffpuff 2631The argument becomes the new value for the experimental 2632huff\-n'\-puff filter span, which determines the most recent interval 2633the algorithm will search for a minimum delay. 2634The lower limit is 2635900 s (15 m), but a more reasonable value is 7200 (2 hours). 2636There 2637is no default, since the filter is not enabled unless this command 2638is given. 2639.It Cm panic Ar panic 2640The argument is the panic threshold, normally 1000 s. 2641If set to zero, 2642the panic sanity check is disabled and a clock offset of any value will 2643be accepted. 2644.It Cm step Ar step 2645The argument is the step threshold, which by default is 0.128 s. 2646It can 2647be set to any positive number in seconds. 2648If set to zero, step 2649adjustments will never occur. 2650Note: The kernel time discipline is 2651disabled if the step threshold is set to zero or greater than the 2652default. 2653.It Cm stepout Ar stepout 2654The argument is the stepout timeout, which by default is 900 s. 2655It can 2656be set to any positive number in seconds. 2657If set to zero, the stepout 2658pulses will not be suppressed. 2659.El 2660.It Xo Ic rlimit 2661.Oo 2662.Cm memlock Ar Nmegabytes | 2663.Cm stacksize Ar N4kPages 2664.Cm filenum Ar Nfiledescriptors 2665.Oc 2666.Xc 2667.Bl -tag -width indent 2668.It Cm memlock Ar Nmegabytes 2669Specify the number of megabytes of memory that can be allocated. 2670Probably only available under Linux, this option is useful 2671when dropping root (the 2672.Fl i 2673option). 2674The default is 32 megabytes. Setting this to zero will prevent any attemp to lock memory. 2675.It Cm stacksize Ar N4kPages 2676Specifies the maximum size of the process stack on systems with the 2677.It Cm filenum Ar Nfiledescriptors 2678Specifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default. 2679.Fn mlockall 2680function. 2681Defaults to 50 4k pages (200 4k pages in OpenBSD). 2682.El 2683.It Xo Ic trap Ar host_address 2684.Op Cm port Ar port_number 2685.Op Cm interface Ar interface_address 2686.Xc 2687This command configures a trap receiver at the given host 2688address and port number for sending messages with the specified 2689local interface address. 2690If the port number is unspecified, a value 2691of 18447 is used. 2692If the interface address is not specified, the 2693message is sent with a source address of the local interface the 2694message is sent through. 2695Note that on a multihomed host the 2696interface used may vary from time to time with routing changes. 2697.Pp 2698The trap receiver will generally log event messages and other 2699information from the server in a log file. 2700While such monitor 2701programs may also request their own trap dynamically, configuring a 2702trap receiver will ensure that no messages are lost when the server 2703is started. 2704.It Cm hop Ar ... 2705This command specifies a list of TTL values in increasing order, up to 8 2706values can be specified. 2707In manycast mode these values are used in turn in 2708an expanding\-ring search. 2709The default is eight multiples of 32 starting at 271031. 2711.El 2712.Sh "OPTIONS" 2713.Bl -tag 2714.It Fl \-help 2715Display usage information and exit. 2716.It Fl \-more\-help 2717Pass the extended usage information through a pager. 2718.It Fl \-version Op Brq Ar v|c|n 2719Output version of program and exit. The default mode is `v', a simple 2720version. The `c' mode will print copyright information and `n' will 2721print the full copyright notice. 2722.El 2723.Sh "OPTION PRESETS" 2724Any option that is not marked as \fInot presettable\fP may be preset 2725by loading values from environment variables named: 2726.nf 2727 \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP 2728.fi 2729.ad 2730cvt_prog='/usr/local/gnu/share/autogen/texi2mdoc' 2731cvt_prog=`cd \`dirname "$cvt_prog"\` >/dev/null && pwd 2732 `/`basename "$cvt_prog"` 2733cd $tmp_dir 2734test \-x "$cvt_prog" || die "'$cvt_prog' is not executable" 2735{ 2736 list='synopsis description options option\-presets' 2737 for f in $list ; do cat $f ; echo ; done 2738 rm \-f $list name 2739 list='implementation\-notes environment files examples exit\-status errors 2740 compatibility see\-also conforming\-to history authors copyright bugs 2741 notes' 2742 for f in $list ; do cat $f ; echo ; done > .end\-doc 2743 rm \-f $list 2744 list=`ls \-1 *`' .end\-doc' 2745 for f in $list ; do cat $f ; echo ; done 2746 rm \-f $list 2747} 1>.doc 2>/dev/null 2748sed \-f .cmds .doc | /usr/local/gnu/bin/grep \-E \-v '^[ ]*$' | $cvt_prog 2749.Sh "ENVIRONMENT" 2750See \fBOPTION PRESETS\fP for configuration environment variables. 2751.Sh FILES 2752.Bl -tag -width /etc/ntp.drift -compact 2753.It Pa /etc/ntp.conf 2754the default name of the configuration file 2755.It Pa ntp.keys 2756private MD5 keys 2757.It Pa ntpkey 2758RSA private key 2759.It Pa ntpkey_ Ns Ar host 2760RSA public key 2761.It Pa ntp_dh 2762Diffie\-Hellman agreement parameters 2763.El 2764.Sh "EXIT STATUS" 2765One of the following exit values will be returned: 2766.Bl -tag 2767.It 0 " (EXIT_SUCCESS)" 2768Successful program execution. 2769.It 1 " (EXIT_FAILURE)" 2770The operation failed or the command syntax was not valid. 2771.It 70 " (EX_SOFTWARE)" 2772libopts had an internal operational error. Please report 2773it to autogen\-users@lists.sourceforge.net. Thank you. 2774.El 2775.Sh "SEE ALSO" 2776.Xr ntpd @NTPD_MS@ , 2777.Xr ntpdc @NTPDC_MS@ , 2778.Xr ntpq @NTPQ_MS@ 2779.Pp 2780In addition to the manual pages provided, 2781comprehensive documentation is available on the world wide web 2782at 2783.Li http://www.ntp.org/ . 2784A snapshot of this documentation is available in HTML format in 2785.Pa /usr/share/doc/ntp . 2786.Rs 2787.%A David L. Mills 2788.%T Network Time Protocol (Version 4) 2789.%O RFC5905 2790.Re 2791.Sh "AUTHORS" 2792The University of Delaware 2793.Sh "COPYRIGHT" 2794Copyright (C) 1970\-2013 The University of Delaware all rights reserved. 2795This program is released under the terms of the NTP license, <http://ntp.org/license>. 2796.Sh BUGS 2797The syntax checking is not picky; some combinations of 2798ridiculous and even hilarious options and modes may not be 2799detected. 2800.Pp 2801The 2802.Pa ntpkey_ Ns Ar host 2803files are really digital 2804certificates. 2805These should be obtained via secure directory 2806services when they become universally available. 2807.Pp 2808Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org 2809.Sh NOTES 2810This document corresponds to version 4.2.7p404 of NTP. 2811This document was derived from FreeBSD. 2812.Pp 2813This manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP 2814option definitions. 2815