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