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