1310419Sdelphij.Dd November 21 2016 2285612Sdelphij.Dt NTP_CONF 5 File Formats 3285612Sdelphij.Os 4285612Sdelphij.\" EDIT THIS FILE WITH CAUTION (ntp.mdoc) 555895Ssheldonh.\" 655895Ssheldonh.\" $FreeBSD: releng/10.2/usr.sbin/ntp/doc/ntp.conf.5 310419 2016-12-22 16:19:05Z delphij $ 755895Ssheldonh.\" 8310419Sdelphij.\" It has been AutoGen-ed November 21, 2016 at 08:02:03 AM by AutoGen 5.18.5 9285612Sdelphij.\" From the definitions ntp.conf.def 10285612Sdelphij.\" and the template file agmdoc-cmd.tpl 1155895Ssheldonh.Sh NAME 1255895Ssheldonh.Nm ntp.conf 13285612Sdelphij.Nd Network Time Protocol (NTP) daemon configuration file format 1455895Ssheldonh.Sh SYNOPSIS 15285612Sdelphij.Nm 16285612Sdelphij.Op Fl \-option\-name 17285612Sdelphij.Op Fl \-option\-name Ar value 18285612Sdelphij.Pp 19285612SdelphijAll arguments must be options. 20285612Sdelphij.Pp 2155895Ssheldonh.Sh DESCRIPTION 2255895SsheldonhThe 2355895Ssheldonh.Nm 2455895Ssheldonhconfiguration file is read at initial startup by the 2555895Ssheldonh.Xr ntpd 8 2655895Ssheldonhdaemon in order to specify the synchronization sources, 2755895Ssheldonhmodes and other related information. 2855895SsheldonhUsually, it is installed in the 2955895Ssheldonh.Pa /etc 3055895Ssheldonhdirectory, 3155895Ssheldonhbut could be installed elsewhere 3255895Ssheldonh(see the daemon's 3355895Ssheldonh.Fl c 3455895Ssheldonhcommand line option). 3555895Ssheldonh.Pp 3682501SsheldonhThe file format is similar to other 3782501Ssheldonh.Ux 3882501Ssheldonhconfiguration files. 3955895SsheldonhComments begin with a 4082501Ssheldonh.Ql # 4155895Ssheldonhcharacter and extend to the end of the line; 4255895Ssheldonhblank lines are ignored. 4355895SsheldonhConfiguration commands consist of an initial keyword 4455895Ssheldonhfollowed by a list of arguments, 4555895Ssheldonhsome of which may be optional, separated by whitespace. 4655895SsheldonhCommands may not be continued over multiple lines. 4755895SsheldonhArguments may be host names, 48285612Sdelphijhost addresses written in numeric, dotted\-quad form, 4955895Ssheldonhintegers, floating point numbers (when specifying times in seconds) 5055895Ssheldonhand text strings. 5155895Ssheldonh.Pp 5255895SsheldonhThe rest of this page describes the configuration and control options. 5355895SsheldonhThe 54285612Sdelphij.Qq Notes on Configuring NTP and Setting up an NTP Subnet 5555895Ssheldonhpage 5655895Ssheldonh(available as part of the HTML documentation 5755895Ssheldonhprovided in 5855895Ssheldonh.Pa /usr/share/doc/ntp ) 5955895Ssheldonhcontains an extended discussion of these options. 6055895SsheldonhIn addition to the discussion of general 6155895Ssheldonh.Sx Configuration Options , 6255895Ssheldonhthere are sections describing the following supported functionality 6355895Ssheldonhand the options used to control it: 6455895Ssheldonh.Bl -bullet -offset indent 6555895Ssheldonh.It 6655895Ssheldonh.Sx Authentication Support 6755895Ssheldonh.It 6855895Ssheldonh.Sx Monitoring Support 6955895Ssheldonh.It 7055895Ssheldonh.Sx Access Control Support 7155895Ssheldonh.It 72158688Spav.Sx Automatic NTP Configuration Options 73158688Spav.It 7455895Ssheldonh.Sx Reference Clock Support 75158688Spav.It 76158688Spav.Sx Miscellaneous Options 7755895Ssheldonh.El 7855895Ssheldonh.Pp 7955895SsheldonhFollowing these is a section describing 8055895Ssheldonh.Sx Miscellaneous Options . 8155895SsheldonhWhile there is a rich set of options available, 8255895Ssheldonhthe only required option is one or more 83285612Sdelphij.Ic pool , 8455895Ssheldonh.Ic server , 8555895Ssheldonh.Ic peer , 8655895Ssheldonh.Ic broadcast 8755895Ssheldonhor 8855895Ssheldonh.Ic manycastclient 8955895Ssheldonhcommands. 9082501Ssheldonh.Sh Configuration Support 9182501SsheldonhFollowing is a description of the configuration commands in 9282501SsheldonhNTPv4. 9382501SsheldonhThese commands have the same basic functions as in NTPv3 and 9482501Ssheldonhin some cases new functions and new arguments. 9582501SsheldonhThere are two 9682501Ssheldonhclasses of commands, configuration commands that configure a 9782501Ssheldonhpersistent association with a remote server or peer or reference 98108317Sschweikhclock, and auxiliary commands that specify environmental variables 9982501Ssheldonhthat control various related operations. 10082501Ssheldonh.Ss Configuration Commands 10182501SsheldonhThe various modes are determined by the command keyword and the 10282501Ssheldonhtype of the required IP address. 10355895SsheldonhAddresses are classed by type as 104158688Spav(s) a remote server or peer (IPv4 class A, B and C), (b) the 105158688Spavbroadcast address of a local interface, (m) a multicast address (IPv4 10682501Ssheldonhclass D), or (r) a reference clock address (127.127.x.x). 10782501SsheldonhNote that 10882501Ssheldonhonly those options applicable to each command are listed below. 10982501SsheldonhUse 11082501Ssheldonhof options not listed may not be caught as an error, but may result 11182501Ssheldonhin some weird and even destructive behavior. 112158688Spav.Pp 113285612SdelphijIf the Basic Socket Interface Extensions for IPv6 (RFC\-2553) 114158688Spavis detected, support for the IPv6 address family is generated 115158688Spavin addition to the default support of the IPv4 address family. 116298770SdelphijIn a few cases, including the 117298770Sdelphij.Cm reslist 118298770Sdelphijbillboard generated 119298770Sdelphijby 120298770Sdelphij.Xr ntpq 8 121298770Sdelphijor 122298770Sdelphij.Xr ntpdc 8 , 123298770SdelphijIPv6 addresses are automatically generated. 124158688SpavIPv6 addresses can be identified by the presence of colons 125158688Spav.Dq \&: 126158688Spavin the address field. 127158688SpavIPv6 addresses can be used almost everywhere where 128158688SpavIPv4 addresses can be used, 129158688Spavwith the exception of reference clock addresses, 130158688Spavwhich are always IPv4. 131158688Spav.Pp 132158688SpavNote that in contexts where a host name is expected, a 133158688Spav.Fl 4 134158688Spavqualifier preceding 135158688Spavthe host name forces DNS resolution to the IPv4 namespace, 136158688Spavwhile a 137158688Spav.Fl 6 138158688Spavqualifier forces DNS resolution to the IPv6 namespace. 139158688SpavSee IPv6 references for the 140158688Spavequivalent classes for that address family. 14155895Ssheldonh.Bl -tag -width indent 142285612Sdelphij.It Xo Ic pool Ar address 143285612Sdelphij.Op Cm burst 144285612Sdelphij.Op Cm iburst 145285612Sdelphij.Op Cm version Ar version 146285612Sdelphij.Op Cm prefer 147285612Sdelphij.Op Cm minpoll Ar minpoll 148285612Sdelphij.Op Cm maxpoll Ar maxpoll 149285612Sdelphij.Xc 15082501Ssheldonh.It Xo Ic server Ar address 15182501Ssheldonh.Op Cm key Ar key \&| Cm autokey 15282501Ssheldonh.Op Cm burst 15382501Ssheldonh.Op Cm iburst 15482501Ssheldonh.Op Cm version Ar version 15582501Ssheldonh.Op Cm prefer 15682501Ssheldonh.Op Cm minpoll Ar minpoll 15782501Ssheldonh.Op Cm maxpoll Ar maxpoll 158298770Sdelphij.Op Cm true 15955895Ssheldonh.Xc 16082501Ssheldonh.It Xo Ic peer Ar address 16182501Ssheldonh.Op Cm key Ar key \&| Cm autokey 16282501Ssheldonh.Op Cm version Ar version 16382501Ssheldonh.Op Cm prefer 16482501Ssheldonh.Op Cm minpoll Ar minpoll 16582501Ssheldonh.Op Cm maxpoll Ar maxpoll 166298770Sdelphij.Op Cm true 167298770Sdelphij.Op Cm xleave 16855895Ssheldonh.Xc 16982501Ssheldonh.It Xo Ic broadcast Ar address 17082501Ssheldonh.Op Cm key Ar key \&| Cm autokey 17182501Ssheldonh.Op Cm version Ar version 17282501Ssheldonh.Op Cm prefer 17382501Ssheldonh.Op Cm minpoll Ar minpoll 17482501Ssheldonh.Op Cm ttl Ar ttl 175298770Sdelphij.Op Cm xleave 17655895Ssheldonh.Xc 17782501Ssheldonh.It Xo Ic manycastclient Ar address 17882501Ssheldonh.Op Cm key Ar key \&| Cm autokey 17982501Ssheldonh.Op Cm version Ar version 18082501Ssheldonh.Op Cm prefer 18182501Ssheldonh.Op Cm minpoll Ar minpoll 18282501Ssheldonh.Op Cm maxpoll Ar maxpoll 18382501Ssheldonh.Op Cm ttl Ar ttl 18482501Ssheldonh.Xc 18582501Ssheldonh.El 18682501Ssheldonh.Pp 187285612SdelphijThese five commands specify the time server name or address to 18882501Ssheldonhbe used and the mode in which to operate. 18982501SsheldonhThe 19055895Ssheldonh.Ar address 19182501Ssheldonhcan be 192285612Sdelphijeither a DNS name or an IP address in dotted\-quad notation. 19382501SsheldonhAdditional information on association behavior can be found in the 194158688Spav.Qq Association Management 195158688Spavpage 196158688Spav(available as part of the HTML documentation 197158688Spavprovided in 198158688Spav.Pa /usr/share/doc/ntp ) . 19955895Ssheldonh.Bl -tag -width indent 200285612Sdelphij.It Ic pool 201285612SdelphijFor type s addresses, this command mobilizes a persistent 202285612Sdelphijclient mode association with a number of remote servers. 203285612SdelphijIn this mode the local clock can synchronized to the 204285612Sdelphijremote server, but the remote server can never be synchronized to 205285612Sdelphijthe local clock. 20682501Ssheldonh.It Ic server 20782501SsheldonhFor type s and r addresses, this command mobilizes a persistent 20882501Ssheldonhclient mode association with the specified remote server or local 20982501Ssheldonhradio clock. 21082501SsheldonhIn this mode the local clock can synchronized to the 21182501Ssheldonhremote server, but the remote server can never be synchronized to 21282501Ssheldonhthe local clock. 21355895SsheldonhThis command should 21455895Ssheldonh.Em not 21582501Ssheldonhbe used for type 21682501Ssheldonhb or m addresses. 21782501Ssheldonh.It Ic peer 21882501SsheldonhFor type s addresses (only), this command mobilizes a 219285612Sdelphijpersistent symmetric\-active mode association with the specified 22082501Ssheldonhremote peer. 22182501SsheldonhIn this mode the local clock can be synchronized to 22282501Ssheldonhthe remote peer or the remote peer can be synchronized to the local 22382501Ssheldonhclock. 22482501SsheldonhThis is useful in a network of servers where, depending on 22582501Ssheldonhvarious failure scenarios, either the local or remote peer may be 22682501Ssheldonhthe better source of time. 22782501SsheldonhThis command should NOT be used for type 22882501Ssheldonhb, m or r addresses. 22955895Ssheldonh.It Ic broadcast 23082501SsheldonhFor type b and m addresses (only), this 23182501Ssheldonhcommand mobilizes a persistent broadcast mode association. 23282501SsheldonhMultiple 23382501Ssheldonhcommands can be used to specify multiple local broadcast interfaces 23482501Ssheldonh(subnets) and/or multiple multicast groups. 23582501SsheldonhNote that local 23682501Ssheldonhbroadcast messages go only to the interface associated with the 23782501Ssheldonhsubnet specified, but multicast messages go to all interfaces. 23882501SsheldonhIn broadcast mode the local server sends periodic broadcast 23993633Ssheldonhmessages to a client population at the 24093633Ssheldonh.Ar address 24182501Ssheldonhspecified, which is usually the broadcast address on (one of) the 24282501Ssheldonhlocal network(s) or a multicast address assigned to NTP. 24382501SsheldonhThe IANA 244158688Spavhas assigned the multicast group address IPv4 224.0.1.1 and 245158688SpavIPv6 ff05::101 (site local) exclusively to 24682501SsheldonhNTP, but other nonconflicting addresses can be used to contain the 24782501Ssheldonhmessages within administrative boundaries. 24882501SsheldonhOrdinarily, this 24982501Ssheldonhspecification applies only to the local server operating as a 25082501Ssheldonhsender; for operation as a broadcast client, see the 25155895Ssheldonh.Ic broadcastclient 25255895Ssheldonhor 25355895Ssheldonh.Ic multicastclient 25482501Ssheldonhcommands 25582501Ssheldonhbelow. 25655895Ssheldonh.It Ic manycastclient 25782501SsheldonhFor type m addresses (only), this command mobilizes a 25882501Ssheldonhmanycast client mode association for the multicast address 25982501Ssheldonhspecified. 26082501SsheldonhIn this case a specific address must be supplied which 26182501Ssheldonhmatches the address used on the 26255895Ssheldonh.Ic manycastserver 26382501Ssheldonhcommand for 26482501Ssheldonhthe designated manycast servers. 26582501SsheldonhThe NTP multicast address 26682501Ssheldonh224.0.1.1 assigned by the IANA should NOT be used, unless specific 26782501Ssheldonhmeans are taken to avoid spraying large areas of the Internet with 26882501Ssheldonhthese messages and causing a possibly massive implosion of replies 26982501Ssheldonhat the sender. 27055895SsheldonhThe 27182501Ssheldonh.Ic manycastserver 27282501Ssheldonhcommand specifies that the local server 27382501Ssheldonhis to operate in client mode with the remote servers that are 27482501Ssheldonhdiscovered as the result of broadcast/multicast messages. 27582501SsheldonhThe 27682501Ssheldonhclient broadcasts a request message to the group address associated 27782501Ssheldonhwith the specified 27882501Ssheldonh.Ar address 27982501Ssheldonhand specifically enabled 28082501Ssheldonhservers respond to these messages. 28182501SsheldonhThe client selects the servers 28282501Ssheldonhproviding the best time and continues as with the 28355895Ssheldonh.Ic server 28455895Ssheldonhcommand. 28582501SsheldonhThe remaining servers are discarded as if never 28682501Ssheldonhheard. 28755895Ssheldonh.El 28855895Ssheldonh.Pp 28982501SsheldonhOptions: 29055895Ssheldonh.Bl -tag -width indent 29182501Ssheldonh.It Cm autokey 29282501SsheldonhAll packets sent to and received from the server or peer are to 29382501Ssheldonhinclude authentication fields encrypted using the autokey scheme 29482501Ssheldonhdescribed in 295285612Sdelphij.Sx Authentication Options . 29682501Ssheldonh.It Cm burst 297158688Spavwhen the server is reachable, send a burst of eight packets 298162806Sruinstead of the usual one. 299162806SruThe packet spacing is normally 2 s; 300158688Spavhowever, the spacing between the first and second packets 301298770Sdelphijcan be changed with the 302298770Sdelphij.Ic calldelay 303298770Sdelphijcommand to allow 304158688Spavadditional time for a modem or ISDN call to complete. 305158688SpavThis is designed to improve timekeeping quality 306158688Spavwith the 30782501Ssheldonh.Ic server 308158688Spavcommand and s addresses. 30982501Ssheldonh.It Cm iburst 310158688SpavWhen the server is unreachable, send a burst of eight packets 311162806Sruinstead of the usual one. 312162806SruThe packet spacing is normally 2 s; 313158688Spavhowever, the spacing between the first two packets can be 314298770Sdelphijchanged with the 315298770Sdelphij.Ic calldelay 316298770Sdelphijcommand to allow 317158688Spavadditional time for a modem or ISDN call to complete. 318158688SpavThis is designed to speed the initial synchronization 319158688Spavacquisition with the 32082501Ssheldonh.Ic server 32182501Ssheldonhcommand and s addresses and when 32293633Ssheldonh.Xr ntpd 8 323158688Spavis started with the 32482501Ssheldonh.Fl q 32582501Ssheldonhoption. 32682501Ssheldonh.It Cm key Ar key 32782501SsheldonhAll packets sent to and received from the server or peer are to 32882501Ssheldonhinclude authentication fields encrypted using the specified 32982501Ssheldonh.Ar key 33082501Ssheldonhidentifier with values from 1 to 65534, inclusive. 33182501SsheldonhThe 33282501Ssheldonhdefault is to include no encryption field. 33382501Ssheldonh.It Cm minpoll Ar minpoll 33482501Ssheldonh.It Cm maxpoll Ar maxpoll 33582501SsheldonhThese options specify the minimum and maximum poll intervals 336285612Sdelphijfor NTP messages, as a power of 2 in seconds 33782501SsheldonhThe maximum poll 33882501Ssheldonhinterval defaults to 10 (1,024 s), but can be increased by the 33982501Ssheldonh.Cm maxpoll 34082501Ssheldonhoption to an upper limit of 17 (36.4 h). 34182501SsheldonhThe 34282501Ssheldonhminimum poll interval defaults to 6 (64 s), but can be decreased by 34382501Ssheldonhthe 34482501Ssheldonh.Cm minpoll 34582501Ssheldonhoption to a lower limit of 4 (16 s). 346158688Spav.It Cm noselect 347158688SpavMarks the server as unused, except for display purposes. 348285612SdelphijThe server is discarded by the selection algroithm. 349298770Sdelphij.It Cm preempt 350298770SdelphijSays the association can be preempted. 351298770Sdelphij.It Cm true 352298770SdelphijMarks the server as a truechimer. 353298770SdelphijUse this option only for testing. 35482501Ssheldonh.It Cm prefer 35555895SsheldonhMarks the server as preferred. 35655895SsheldonhAll other things being equal, 35782501Ssheldonhthis host will be chosen for synchronization among a set of 35882501Ssheldonhcorrectly operating hosts. 35955895SsheldonhSee the 360158688Spav.Qq Mitigation Rules and the prefer Keyword 361158688Spavpage 362158688Spav(available as part of the HTML documentation 363158688Spavprovided in 364158688Spav.Pa /usr/share/doc/ntp ) 365158688Spavfor further information. 366298770Sdelphij.It Cm true 367298770SdelphijForces the association to always survive the selection and clustering algorithms. 368298770SdelphijThis option should almost certainly 369298770Sdelphij.Em only 370298770Sdelphijbe used while testing an association. 37182501Ssheldonh.It Cm ttl Ar ttl 37282501SsheldonhThis option is used only with broadcast server and manycast 37382501Ssheldonhclient modes. 374285612SdelphijIt specifies the time\-to\-live 375158688Spav.Ar ttl 37682501Ssheldonhto 37782501Ssheldonhuse on broadcast server and multicast server and the maximum 378158688Spav.Ar ttl 37982501Ssheldonhfor the expanding ring search with manycast 38082501Ssheldonhclient packets. 38182501SsheldonhSelection of the proper value, which defaults to 38282501Ssheldonh127, is something of a black art and should be coordinated with the 38382501Ssheldonhnetwork administrator. 38482501Ssheldonh.It Cm version Ar version 38582501SsheldonhSpecifies the version number to be used for outgoing NTP 38682501Ssheldonhpackets. 387285612SdelphijVersions 1\-4 are the choices, with version 4 the 38882501Ssheldonhdefault. 389298770Sdelphij.It Cm xleave 390298770SdelphijValid in 391298770Sdelphij.Cm peer 392298770Sdelphijand 393298770Sdelphij.Cm broadcast 394298770Sdelphijmodes only, this flag enables interleave mode. 39555895Ssheldonh.El 396108317Sschweikh.Ss Auxiliary Commands 39782501Ssheldonh.Bl -tag -width indent 39855895Ssheldonh.It Ic broadcastclient 39982501SsheldonhThis command enables reception of broadcast server messages to 40082501Ssheldonhany local interface (type b) address. 40182501SsheldonhUpon receiving a message for 40282501Ssheldonhthe first time, the broadcast client measures the nominal server 40382501Ssheldonhpropagation delay using a brief client/server exchange with the 40482501Ssheldonhserver, then enters the broadcast client mode, in which it 40582501Ssheldonhsynchronizes to succeeding broadcast messages. 40682501SsheldonhNote that, in order 40782501Ssheldonhto avoid accidental or malicious disruption in this mode, both the 408285612Sdelphijserver and client should operate using symmetric\-key or public\-key 40982501Ssheldonhauthentication as described in 410285612Sdelphij.Sx Authentication Options . 41182501Ssheldonh.It Ic manycastserver Ar address ... 41282501SsheldonhThis command enables reception of manycast client messages to 41382501Ssheldonhthe multicast group address(es) (type m) specified. 41482501SsheldonhAt least one 41593633Ssheldonhaddress is required, but the NTP multicast address 224.0.1.1 41682501Ssheldonhassigned by the IANA should NOT be used, unless specific means are 41782501Ssheldonhtaken to limit the span of the reply and avoid a possibly massive 41882501Ssheldonhimplosion at the original sender. 41982501SsheldonhNote that, in order to avoid 42082501Ssheldonhaccidental or malicious disruption in this mode, both the server 421285612Sdelphijand client should operate using symmetric\-key or public\-key 42282501Ssheldonhauthentication as described in 423285612Sdelphij.Sx Authentication Options . 42482501Ssheldonh.It Ic multicastclient Ar address ... 42582501SsheldonhThis command enables reception of multicast server messages to 42682501Ssheldonhthe multicast group address(es) (type m) specified. 42782501SsheldonhUpon receiving 42882501Ssheldonha message for the first time, the multicast client measures the 42982501Ssheldonhnominal server propagation delay using a brief client/server 43082501Ssheldonhexchange with the server, then enters the broadcast client mode, in 43182501Ssheldonhwhich it synchronizes to succeeding multicast messages. 43255895SsheldonhNote that, 43355895Ssheldonhin order to avoid accidental or malicious disruption in this mode, 434285612Sdelphijboth the server and client should operate using symmetric\-key or 435285612Sdelphijpublic\-key authentication as described in 436285612Sdelphij.Sx Authentication Options . 437285612Sdelphij.It Ic mdnstries Ar number 438285612SdelphijIf we are participating in mDNS, 439285612Sdelphijafter we have synched for the first time 440285612Sdelphijwe attempt to register with the mDNS system. 441285612SdelphijIf that registration attempt fails, 442285612Sdelphijwe try again at one minute intervals for up to 443285612Sdelphij.Ic mdnstries 444285612Sdelphijtimes. 445285612SdelphijAfter all, 446285612Sdelphij.Ic ntpd 447285612Sdelphijmay be starting before mDNS. 448285612SdelphijThe default value for 449285612Sdelphij.Ic mdnstries 450285612Sdelphijis 5. 45182501Ssheldonh.El 45282501Ssheldonh.Sh Authentication Support 45382501SsheldonhAuthentication support allows the NTP client to verify that the 45482501Ssheldonhserver is in fact known and trusted and not an intruder intending 45582501Ssheldonhaccidentally or on purpose to masquerade as that server. 45682501SsheldonhThe NTPv3 457285612Sdelphijspecification RFC\-1305 defines a scheme which provides 45882501Ssheldonhcryptographic authentication of received NTP packets. 45982501SsheldonhOriginally, 46082501Ssheldonhthis was done using the Data Encryption Standard (DES) algorithm 46182501Ssheldonhoperating in Cipher Block Chaining (CBC) mode, commonly called 462285612SdelphijDES\-CBC. 463158688SpavSubsequently, this was replaced by the RSA Message Digest 464285612Sdelphij5 (MD5) algorithm using a private key, commonly called keyed\-MD5. 465285612SdelphijEither algorithm computes a message digest, or one\-way hash, which 46682501Ssheldonhcan be used to verify the server has the correct private key and 46782501Ssheldonhkey identifier. 46855895Ssheldonh.Pp 469158688SpavNTPv4 retains the NTPv3 scheme, properly described as symmetric key 470158688Spavcryptography and, in addition, provides a new Autokey scheme 471158688Spavbased on public key cryptography. 472158688SpavPublic key cryptography is generally considered more secure 473158688Spavthan symmetric key cryptography, since the security is based 474158688Spavon a private value which is generated by each server and 475162806Srunever revealed. 476162806SruWith Autokey all key distribution and 477158688Spavmanagement functions involve only public values, which 478158688Spavconsiderably simplifies key distribution and storage. 479158688SpavPublic key management is based on X.509 certificates, 480158688Spavwhich can be provided by commercial services or 481158688Spavproduced by utility programs in the OpenSSL software library 482158688Spavor the NTPv4 distribution. 48382501Ssheldonh.Pp 484158688SpavWhile the algorithms for symmetric key cryptography are 485158688Spavincluded in the NTPv4 distribution, public key cryptography 486158688Spavrequires the OpenSSL software library to be installed 487162806Srubefore building the NTP distribution. 488162806SruDirections for doing that 489158688Spavare on the Building and Installing the Distribution page. 490158688Spav.Pp 49182501SsheldonhAuthentication is configured separately for each association 49255895Ssheldonhusing the 49382501Ssheldonh.Cm key 49482501Ssheldonhor 49582501Ssheldonh.Cm autokey 496158688Spavsubcommand on the 497131531Sru.Ic peer , 498131531Sru.Ic server , 49955895Ssheldonh.Ic broadcast 50055895Ssheldonhand 50155895Ssheldonh.Ic manycastclient 502158688Spavconfiguration commands as described in 503158688Spav.Sx Configuration Options 504158688Spavpage. 50582501SsheldonhThe authentication 506158688Spavoptions described below specify the locations of the key files, 507158688Spavif other than default, which symmetric keys are trusted 508158688Spavand the interval between various operations, if other than default. 50955895Ssheldonh.Pp 510158688SpavAuthentication is always enabled, 511158688Spavalthough ineffective if not configured as 512162806Srudescribed below. 513162806SruIf a NTP packet arrives 514158688Spavincluding a message authentication 515158688Spavcode (MAC), it is accepted only if it 516162806Srupasses all cryptographic checks. 517162806SruThe 518158688Spavchecks require correct key ID, key value 519162806Sruand message digest. 520162806SruIf the packet has 521158688Spavbeen modified in any way or replayed 522158688Spavby an intruder, it will fail one or more 523158688Spavof these checks and be discarded. 524158688SpavFurthermore, the Autokey scheme requires a 525158688Spavpreliminary protocol exchange to obtain 526158688Spavthe server certificate, verify its 527285612Sdelphijcredentials and initialize the protocol 528158688Spav.Pp 52982501SsheldonhThe 53082501Ssheldonh.Cm auth 53182501Ssheldonhflag controls whether new associations or 53282501Ssheldonhremote configuration commands require cryptographic authentication. 53382501SsheldonhThis flag can be set or reset by the 53455895Ssheldonh.Ic enable 53555895Ssheldonhand 53655895Ssheldonh.Ic disable 537158688Spavcommands and also by remote 53882501Ssheldonhconfiguration commands sent by a 53955895Ssheldonh.Xr ntpdc 8 540298770Sdelphijprogram running on 54182501Ssheldonhanother machine. 54282501SsheldonhIf this flag is enabled, which is the default 54382501Ssheldonhcase, new broadcast client and symmetric passive associations and 54482501Ssheldonhremote configuration commands must be cryptographically 545158688Spavauthenticated using either symmetric key or public key cryptography. 546158688SpavIf this 547158688Spavflag is disabled, these operations are effective 548158688Spaveven if not cryptographic 549162806Sruauthenticated. 550162806SruIt should be understood 551158688Spavthat operating with the 552158688Spav.Ic auth 553158688Spavflag disabled invites a significant vulnerability 554158688Spavwhere a rogue hacker can 555158688Spavmasquerade as a falseticker and seriously 556162806Srudisrupt system timekeeping. 557162806SruIt is 558158688Spavimportant to note that this flag has no purpose 559158688Spavother than to allow or disallow 560158688Spava new association in response to new broadcast 561158688Spavand symmetric active messages 562158688Spavand remote configuration commands and, in particular, 563158688Spavthe flag has no effect on 564158688Spavthe authentication process itself. 56555895Ssheldonh.Pp 56682501SsheldonhAn attractive alternative where multicast support is available 567158688Spavis manycast mode, in which clients periodically troll 568158688Spavfor servers as described in the 569158688Spav.Sx Automatic NTP Configuration Options 570158688Spavpage. 571158688SpavEither symmetric key or public key 572158688Spavcryptographic authentication can be used in this mode. 573158688SpavThe principle advantage 574158688Spavof manycast mode is that potential servers need not be 575158688Spavconfigured in advance, 576158688Spavsince the client finds them during regular operation, 577158688Spavand the configuration 578158688Spavfiles for all clients can be identical. 57955895Ssheldonh.Pp 580158688SpavThe security model and protocol schemes for 581158688Spavboth symmetric key and public key 582158688Spavcryptography are summarized below; 583158688Spavfurther details are in the briefings, papers 584158688Spavand reports at the NTP project page linked from 585158688Spav.Li http://www.ntp.org/ . 586285612Sdelphij.Ss Symmetric\-Key Cryptography 587285612SdelphijThe original RFC\-1305 specification allows any one of possibly 588285612Sdelphij65,534 keys, each distinguished by a 32\-bit key identifier, to 58982501Ssheldonhauthenticate an association. 59082501SsheldonhThe servers and clients involved must 591158688Spavagree on the key and key identifier to 592162806Sruauthenticate NTP packets. 593162806SruKeys and 594158688Spavrelated information are specified in a key 595158688Spavfile, usually called 596131531Sru.Pa ntp.keys , 597158688Spavwhich must be distributed and stored using 598158688Spavsecure means beyond the scope of the NTP protocol itself. 599158688SpavBesides the keys used 600158688Spavfor ordinary NTP associations, 60182501Ssheldonhadditional keys can be used as passwords for the 60255895Ssheldonh.Xr ntpq 8 60355895Ssheldonhand 60455895Ssheldonh.Xr ntpdc 8 60555895Ssheldonhutility programs. 60655895Ssheldonh.Pp 60755895SsheldonhWhen 60855895Ssheldonh.Xr ntpd 8 609158688Spavis first started, it reads the key file specified in the 61082501Ssheldonh.Ic keys 611158688Spavconfiguration command and installs the keys 612162806Sruin the key cache. 613162806SruHowever, 614158688Spavindividual keys must be activated with the 61582501Ssheldonh.Ic trusted 616162806Srucommand before use. 617162806SruThis 618158688Spavallows, for instance, the installation of possibly 619158688Spavseveral batches of keys and 620158688Spavthen activating or deactivating each batch 621158688Spavremotely using 622131531Sru.Xr ntpdc 8 . 623158688SpavThis also provides a revocation capability that can be used 624162806Sruif a key becomes compromised. 625162806SruThe 62655895Ssheldonh.Ic requestkey 62755895Ssheldonhcommand selects the key used as the password for the 62855895Ssheldonh.Xr ntpdc 8 62982501Ssheldonhutility, while the 63055895Ssheldonh.Ic controlkey 631158688Spavcommand selects the key used as the password for the 63255895Ssheldonh.Xr ntpq 8 63355895Ssheldonhutility. 634158688Spav.Ss Public Key Cryptography 635158688SpavNTPv4 supports the original NTPv3 symmetric key scheme 636285612Sdelphijdescribed in RFC\-1305 and in addition the Autokey protocol, 637158688Spavwhich is based on public key cryptography. 638158688SpavThe Autokey Version 2 protocol described on the Autokey Protocol 639158688Spavpage verifies packet integrity using MD5 message digests 640158688Spavand verifies the source with digital signatures and any of several 641158688Spavdigest/signature schemes. 642158688SpavOptional identity schemes described on the Identity Schemes 643158688Spavpage and based on cryptographic challenge/response algorithms 644158688Spavare also available. 645158688SpavUsing all of these schemes provides strong security against 646158688Spavreplay with or without modification, spoofing, masquerade 647158688Spavand most forms of clogging attacks. 648162806Sru.\" .Pp 649162806Sru.\" The cryptographic means necessary for all Autokey operations 650162806Sru.\" is provided by the OpenSSL software library. 651162806Sru.\" This library is available from http://www.openssl.org/ 652162806Sru.\" and can be installed using the procedures outlined 653162806Sru.\" in the Building and Installing the Distribution page. 654162806Sru.\" Once installed, 655162806Sru.\" the configure and build 656162806Sru.\" process automatically detects the library and links 657162806Sru.\" the library routines required. 658158688Spav.Pp 659158688SpavThe Autokey protocol has several modes of operation 660158688Spavcorresponding to the various NTP modes supported. 661158688SpavMost modes use a special cookie which can be 662158688Spavcomputed independently by the client and server, 663158688Spavbut encrypted in transmission. 664285612SdelphijAll modes use in addition a variant of the S\-KEY scheme, 665285612Sdelphijin which a pseudo\-random key list is generated and used 666158688Spavin reverse order. 66782501SsheldonhThese schemes are described along with an executive summary, 668158688Spavcurrent status, briefing slides and reading list on the 669158688Spav.Sx Autonomous Authentication 67082501Ssheldonhpage. 67155895Ssheldonh.Pp 672158688SpavThe specific cryptographic environment used by Autokey servers 673158688Spavand clients is determined by a set of files 674158688Spavand soft links generated by the 675285612Sdelphij.Xr ntp\-keygen 1ntpkeygenmdoc 676162806Sruprogram. 677162806SruThis includes a required host key file, 678158688Spavrequired certificate file and optional sign key file, 679162806Sruleapsecond file and identity scheme files. 680162806SruThe 681158688Spavdigest/signature scheme is specified in the X.509 certificate 682162806Srualong with the matching sign key. 683162806SruThere are several schemes 684158688Spavavailable in the OpenSSL software library, each identified 685158688Spavby a specific string such as 686158688Spav.Cm md5WithRSAEncryption , 687158688Spavwhich stands for the MD5 message digest with RSA 688162806Sruencryption scheme. 689162806SruThe current NTP distribution supports 690158688Spavall the schemes in the OpenSSL library, including 691158688Spavthose based on RSA and DSA digital signatures. 69255895Ssheldonh.Pp 693158688SpavNTP secure groups can be used to define cryptographic compartments 694162806Sruand security hierarchies. 695162806SruIt is important that every host 696158688Spavin the group be able to construct a certificate trail to one 697162806Sruor more trusted hosts in the same group. 698162806SruEach group 699158688Spavhost runs the Autokey protocol to obtain the certificates 700158688Spavfor all hosts along the trail to one or more trusted hosts. 701158688SpavThis requires the configuration file in all hosts to be 702158688Spavengineered so that, even under anticipated failure conditions, 703158688Spavthe NTP subnet will form such that every group host can find 704158688Spava trail to at least one trusted host. 705158688Spav.Ss Naming and Addressing 706158688SpavIt is important to note that Autokey does not use DNS to 707158688Spavresolve addresses, since DNS can't be completely trusted 708158688Spavuntil the name servers have synchronized clocks. 709158688SpavThe cryptographic name used by Autokey to bind the host identity 710158688Spavcredentials and cryptographic values must be independent 711158688Spavof interface, network and any other naming convention. 712158688SpavThe name appears in the host certificate in either or both 713158688Spavthe subject and issuer fields, so protection against 714158688SpavDNS compromise is essential. 71555895Ssheldonh.Pp 716158688SpavBy convention, the name of an Autokey host is the name returned 717158688Spavby the Unix 718158688Spav.Xr gethostname 2 719162806Srusystem call or equivalent in other systems. 720162806SruBy the system design 721158688Spavmodel, there are no provisions to allow alternate names or aliases. 722158688SpavHowever, this is not to say that DNS aliases, different names 723158688Spavfor each interface, etc., are constrained in any way. 72455895Ssheldonh.Pp 725158688SpavIt is also important to note that Autokey verifies authenticity 726158688Spavusing the host name, network address and public keys, 727158688Spavall of which are bound together by the protocol specifically 728162806Sruto deflect masquerade attacks. 729162806SruFor this reason Autokey 730298770Sdelphijincludes the source and destination IP addresses in message digest 731158688Spavcomputations and so the same addresses must be available 732162806Sruat both the server and client. 733162806SruFor this reason operation 734158688Spavwith network address translation schemes is not possible. 735158688SpavThis reflects the intended robust security model where government 736158688Spavand corporate NTP servers are operated outside firewall perimeters. 737158688Spav.Ss Operation 738158688SpavA specific combination of authentication scheme (none, 739158688Spavsymmetric key, public key) and identity scheme is called 740158688Spava cryptotype, although not all combinations are compatible. 741158688SpavThere may be management configurations where the clients, 742158688Spavservers and peers may not all support the same cryptotypes. 743158688SpavA secure NTPv4 subnet can be configured in many ways while 744158688Spavkeeping in mind the principles explained above and 745162806Sruin this section. 746162806SruNote however that some cryptotype 747158688Spavcombinations may successfully interoperate with each other, 748158688Spavbut may not represent good security practice. 749158688Spav.Pp 750158688SpavThe cryptotype of an association is determined at the time 751158688Spavof mobilization, either at configuration time or some time 752158688Spavlater when a message of appropriate cryptotype arrives. 753158688SpavWhen mobilized by a 75482501Ssheldonh.Ic server 75582501Ssheldonhor 75682501Ssheldonh.Ic peer 757158688Spavconfiguration command and no 758158688Spav.Ic key 759158688Spavor 760158688Spav.Ic autokey 761158688Spavsubcommands are present, the association is not 762158688Spavauthenticated; if the 763158688Spav.Ic key 764158688Spavsubcommand is present, the association is authenticated 765158688Spavusing the symmetric key ID specified; if the 766158688Spav.Ic autokey 767158688Spavsubcommand is present, the association is authenticated 768158688Spavusing Autokey. 76955895Ssheldonh.Pp 770158688SpavWhen multiple identity schemes are supported in the Autokey 771158688Spavprotocol, the first message exchange determines which one is used. 772158688SpavThe client request message contains bits corresponding 773162806Sruto which schemes it has available. 774162806SruThe server response message 775158688Spavcontains bits corresponding to which schemes it has available. 776158688SpavBoth server and client match the received bits with their own 777158688Spavand select a common scheme. 77882501Ssheldonh.Pp 779158688SpavFollowing the principle that time is a public value, 780158688Spava server responds to any client packet that matches 781162806Sruits cryptotype capabilities. 782162806SruThus, a server receiving 783158688Spavan unauthenticated packet will respond with an unauthenticated 784158688Spavpacket, while the same server receiving a packet of a cryptotype 785158688Spavit supports will respond with packets of that cryptotype. 786158688SpavHowever, unconfigured broadcast or manycast client 787158688Spavassociations or symmetric passive associations will not be 788158688Spavmobilized unless the server supports a cryptotype compatible 789158688Spavwith the first packet received. 790158688SpavBy default, unauthenticated associations will not be mobilized 791158688Spavunless overridden in a decidedly dangerous way. 79282501Ssheldonh.Pp 793158688SpavSome examples may help to reduce confusion. 794158688SpavClient Alice has no specific cryptotype selected. 795158688SpavServer Bob has both a symmetric key file and minimal Autokey files. 796158688SpavAlice's unauthenticated messages arrive at Bob, who replies with 797162806Sruunauthenticated messages. 798162806SruCathy has a copy of Bob's symmetric 799158688Spavkey file and has selected key ID 4 in messages to Bob. 800162806SruBob verifies the message with his key ID 4. 801162806SruIf it's the 802158688Spavsame key and the message is verified, Bob sends Cathy a reply 803162806Sruauthenticated with that key. 804162806SruIf verification fails, 805285612SdelphijBob sends Cathy a thing called a crypto\-NAK, which tells her 806162806Srusomething broke. 807285612SdelphijShe can see the evidence using the 808285612Sdelphij.Xr ntpq 8 809285612Sdelphijprogram. 81082501Ssheldonh.Pp 811158688SpavDenise has rolled her own host key and certificate. 812158688SpavShe also uses one of the identity schemes as Bob. 813158688SpavShe sends the first Autokey message to Bob and they 814158688Spavboth dance the protocol authentication and identity steps. 815158688SpavIf all comes out okay, Denise and Bob continue as described above. 81682501Ssheldonh.Pp 817158688SpavIt should be clear from the above that Bob can support 818158688Spavall the girls at the same time, as long as he has compatible 819158688Spavauthentication and identity credentials. 820158688SpavNow, Bob can act just like the girls in his own choice of servers; 821158688Spavhe can run multiple configured associations with multiple different 822158688Spavservers (or the same server, although that might not be useful). 823158688SpavBut, wise security policy might preclude some cryptotype 824158688Spavcombinations; for instance, running an identity scheme 825158688Spavwith one server and no authentication with another might not be wise. 826158688Spav.Ss Key Management 827158688SpavThe cryptographic values used by the Autokey protocol are 828158688Spavincorporated as a set of files generated by the 829285612Sdelphij.Xr ntp\-keygen 1ntpkeygenmdoc 830158688Spavutility program, including symmetric key, host key and 831158688Spavpublic certificate files, as well as sign key, identity parameters 832162806Sruand leapseconds files. 833162806SruAlternatively, host and sign keys and 834158688Spavcertificate files can be generated by the OpenSSL utilities 835158688Spavand certificates can be imported from public certificate 836162806Sruauthorities. 837162806SruNote that symmetric keys are necessary for the 838158688Spav.Xr ntpq 8 839158688Spavand 840158688Spav.Xr ntpdc 8 841162806Sruutility programs. 842162806SruThe remaining files are necessary only for the 843158688SpavAutokey protocol. 84482501Ssheldonh.Pp 845158688SpavCertificates imported from OpenSSL or public certificate 846285612Sdelphijauthorities have certian limitations. 847158688SpavThe certificate should be in ASN.1 syntax, X.509 Version 3 848158688Spavformat and encoded in PEM, which is the same format 849162806Sruused by OpenSSL. 850162806SruThe overall length of the certificate encoded 851162806Sruin ASN.1 must not exceed 1024 bytes. 852162806SruThe subject distinguished 853158688Spavname field (CN) is the fully qualified name of the host 854158688Spavon which it is used; the remaining subject fields are ignored. 855158688SpavThe certificate extension fields must not contain either 856158688Spava subject key identifier or a issuer key identifier field; 857158688Spavhowever, an extended key usage field for a trusted host must 858158688Spavcontain the value 859285612Sdelphij.Cm trustRoot ; . 860158688SpavOther extension fields are ignored. 86182501Ssheldonh.Ss Authentication Commands 86255895Ssheldonh.Bl -tag -width indent 86382501Ssheldonh.It Ic autokey Op Ar logsec 86482501SsheldonhSpecifies the interval between regenerations of the session key 86582501Ssheldonhlist used with the Autokey protocol. 86682501SsheldonhNote that the size of the key 86782501Ssheldonhlist for each association depends on this interval and the current 86882501Ssheldonhpoll interval. 86982501SsheldonhThe default value is 12 (4096 s or about 1.1 hours). 87082501SsheldonhFor poll intervals above the specified interval, a session key list 87182501Ssheldonhwith a single entry will be regenerated for every message 87282501Ssheldonhsent. 87382501Ssheldonh.It Ic controlkey Ar key 87482501SsheldonhSpecifies the key identifier to use with the 87555895Ssheldonh.Xr ntpq 8 87682501Ssheldonhutility, which uses the standard 877285612Sdelphijprotocol defined in RFC\-1305. 87882501SsheldonhThe 87955895Ssheldonh.Ar key 88082501Ssheldonhargument is 88182501Ssheldonhthe key identifier for a trusted key, where the value can be in the 882158688Spavrange 1 to 65,534, inclusive. 88382501Ssheldonh.It Xo Ic crypto 884158688Spav.Op Cm cert Ar file 88582501Ssheldonh.Op Cm leap Ar file 886158688Spav.Op Cm randfile Ar file 887158688Spav.Op Cm host Ar file 888158688Spav.Op Cm sign Ar file 889158688Spav.Op Cm gq Ar file 890158688Spav.Op Cm gqpar Ar file 891158688Spav.Op Cm iffpar Ar file 892158688Spav.Op Cm mvpar Ar file 893158688Spav.Op Cm pw Ar password 89455895Ssheldonh.Xc 895162806SruThis command requires the OpenSSL library. 896162806SruIt activates public key 897158688Spavcryptography, selects the message digest and signature 898158688Spavencryption scheme and loads the required private and public 899162806Sruvalues described above. 900162806SruIf one or more files are left unspecified, 901158688Spavthe default names are used as described above. 902158688SpavUnless the complete path and name of the file are specified, the 903158688Spavlocation of a file is relative to the keys directory specified 904158688Spavin the 905158688Spav.Ic keysdir 906158688Spavcommand or default 907158688Spav.Pa /usr/local/etc . 908158688SpavFollowing are the subcommands: 90982501Ssheldonh.Bl -tag -width indent 910158688Spav.It Cm cert Ar file 911158688SpavSpecifies the location of the required host public certificate file. 912158688SpavThis overrides the link 913158688Spav.Pa ntpkey_cert_ Ns Ar hostname 914158688Spavin the keys directory. 915158688Spav.It Cm gqpar Ar file 916162806SruSpecifies the location of the optional GQ parameters file. 917162806SruThis 918158688Spavoverrides the link 919158688Spav.Pa ntpkey_gq_ Ns Ar hostname 920158688Spavin the keys directory. 921158688Spav.It Cm host Ar file 922162806SruSpecifies the location of the required host key file. 923162806SruThis overrides 924158688Spavthe link 925158688Spav.Pa ntpkey_key_ Ns Ar hostname 926158688Spavin the keys directory. 927158688Spav.It Cm iffpar Ar file 928298770SdelphijSpecifies the location of the optional IFF parameters file. 929298770SdelphijThis overrides the link 930158688Spav.Pa ntpkey_iff_ Ns Ar hostname 931158688Spavin the keys directory. 93282501Ssheldonh.It Cm leap Ar file 933158688SpavSpecifies the location of the optional leapsecond file. 934158688SpavThis overrides the link 935158688Spav.Pa ntpkey_leap 936158688Spavin the keys directory. 937158688Spav.It Cm mvpar Ar file 938162806SruSpecifies the location of the optional MV parameters file. 939298770SdelphijThis overrides the link 940158688Spav.Pa ntpkey_mv_ Ns Ar hostname 941158688Spavin the keys directory. 942158688Spav.It Cm pw Ar password 943158688SpavSpecifies the password to decrypt files containing private keys and 944162806Sruidentity parameters. 945162806SruThis is required only if these files have been 946158688Spavencrypted. 947158688Spav.It Cm randfile Ar file 948158688SpavSpecifies the location of the random seed file used by the OpenSSL 949162806Srulibrary. 950162806SruThe defaults are described in the main text above. 951158688Spav.It Cm sign Ar file 952162806SruSpecifies the location of the optional sign key file. 953162806SruThis overrides 954158688Spavthe link 955158688Spav.Pa ntpkey_sign_ Ns Ar hostname 956162806Sruin the keys directory. 957162806SruIf this file is 958158688Spavnot found, the host key is also the sign key. 95982501Ssheldonh.El 96082501Ssheldonh.It Ic keys Ar keyfile 961158688SpavSpecifies the complete path and location of the MD5 key file 96282501Ssheldonhcontaining the keys and key identifiers used by 96382501Ssheldonh.Xr ntpd 8 , 96455895Ssheldonh.Xr ntpq 8 96555895Ssheldonhand 966285612Sdelphij.Xr ntpdc 8 967158688Spavwhen operating with symmetric key cryptography. 968158688SpavThis is the same operation as the 969158688Spav.Fl k 970158688Spavcommand line option. 97182501Ssheldonh.It Ic keysdir Ar path 972158688SpavThis command specifies the default directory path for 973158688Spavcryptographic keys, parameters and certificates. 974158688SpavThe default is 975158688Spav.Pa /usr/local/etc/ . 97655895Ssheldonh.It Ic requestkey Ar key 97755895SsheldonhSpecifies the key identifier to use with the 97855895Ssheldonh.Xr ntpdc 8 97982501Ssheldonhutility program, which uses a 98082501Ssheldonhproprietary protocol specific to this implementation of 981131531Sru.Xr ntpd 8 . 98255895SsheldonhThe 98355895Ssheldonh.Ar key 98482501Ssheldonhargument is a key identifier 98582501Ssheldonhfor the trusted key, where the value can be in the range 1 to 986158688Spav65,534, inclusive. 98782501Ssheldonh.It Ic revoke Ar logsec 988285612SdelphijSpecifies the interval between re\-randomization of certain 98982501Ssheldonhcryptographic values used by the Autokey scheme, as a power of 2 in 99082501Ssheldonhseconds. 99182501SsheldonhThese values need to be updated frequently in order to 992285612Sdelphijdeflect brute\-force attacks on the algorithms of the scheme; 99382501Ssheldonhhowever, updating some values is a relatively expensive operation. 99482501SsheldonhThe default interval is 16 (65,536 s or about 18 hours). 99582501SsheldonhFor poll 99682501Ssheldonhintervals above the specified interval, the values will be updated 99782501Ssheldonhfor every message sent. 99882501Ssheldonh.It Ic trustedkey Ar key ... 99982501SsheldonhSpecifies the key identifiers which are trusted for the 1000158688Spavpurposes of authenticating peers with symmetric key cryptography, 100182501Ssheldonhas well as keys used by the 100255895Ssheldonh.Xr ntpq 8 100382501Ssheldonhand 100482501Ssheldonh.Xr ntpdc 8 100582501Ssheldonhprograms. 100682501SsheldonhThe authentication procedures require that both the local 100782501Ssheldonhand remote servers share the same key and key identifier for this 100882501Ssheldonhpurpose, although different keys can be used with different 100982501Ssheldonhservers. 101055895SsheldonhThe 101155895Ssheldonh.Ar key 1012285612Sdelphijarguments are 32\-bit unsigned 101382501Ssheldonhintegers with values from 1 to 65,534. 101455895Ssheldonh.El 1015158688Spav.Ss Error Codes 1016158688SpavThe following error codes are reported via the NTP control 1017158688Spavand monitoring protocol trap mechanism. 1018158688Spav.Bl -tag -width indent 1019158688Spav.It 101 1020158688Spav.Pq bad field format or length 1021158688SpavThe packet has invalid version, length or format. 1022158688Spav.It 102 1023158688Spav.Pq bad timestamp 1024158688SpavThe packet timestamp is the same or older than the most recent received. 1025158688SpavThis could be due to a replay or a server clock time step. 1026158688Spav.It 103 1027158688Spav.Pq bad filestamp 1028158688SpavThe packet filestamp is the same or older than the most recent received. 1029158688SpavThis could be due to a replay or a key file generation error. 1030158688Spav.It 104 1031158688Spav.Pq bad or missing public key 1032158688SpavThe public key is missing, has incorrect format or is an unsupported type. 1033158688Spav.It 105 1034158688Spav.Pq unsupported digest type 1035158688SpavThe server requires an unsupported digest/signature scheme. 1036158688Spav.It 106 1037158688Spav.Pq mismatched digest types 1038158688SpavNot used. 1039158688Spav.It 107 1040158688Spav.Pq bad signature length 1041158688SpavThe signature length does not match the current public key. 1042158688Spav.It 108 1043158688Spav.Pq signature not verified 1044162806SruThe message fails the signature check. 1045162806SruIt could be bogus or signed by a 1046158688Spavdifferent private key. 1047158688Spav.It 109 1048158688Spav.Pq certificate not verified 1049158688SpavThe certificate is invalid or signed with the wrong key. 1050158688Spav.It 110 1051158688Spav.Pq certificate not verified 1052158688SpavThe certificate is not yet valid or has expired or the signature could not 1053158688Spavbe verified. 1054158688Spav.It 111 1055158688Spav.Pq bad or missing cookie 1056158688SpavThe cookie is missing, corrupted or bogus. 1057158688Spav.It 112 1058158688Spav.Pq bad or missing leapseconds table 1059158688SpavThe leapseconds table is missing, corrupted or bogus. 1060158688Spav.It 113 1061158688Spav.Pq bad or missing certificate 1062158688SpavThe certificate is missing, corrupted or bogus. 1063158688Spav.It 114 1064158688Spav.Pq bad or missing identity 1065158688SpavThe identity key is missing, corrupt or bogus. 1066158688Spav.El 106782501Ssheldonh.Sh Monitoring Support 106893633Ssheldonh.Xr ntpd 8 106982501Ssheldonhincludes a comprehensive monitoring facility suitable 107082501Ssheldonhfor continuous, long term recording of server and client 107182501Ssheldonhtimekeeping performance. 107255895SsheldonhSee the 1073107311Sru.Ic statistics 107482501Ssheldonhcommand below 107582501Ssheldonhfor a listing and example of each type of statistics currently 107682501Ssheldonhsupported. 107755895SsheldonhStatistic files are managed using file generation sets 107855895Ssheldonhand scripts in the 107955895Ssheldonh.Pa ./scripts 1080298770Sdelphijdirectory of the source code distribution. 108182501SsheldonhUsing 108282501Ssheldonhthese facilities and 108382501Ssheldonh.Ux 1084107311Sru.Xr cron 8 108582501Ssheldonhjobs, the data can be 108682501Ssheldonhautomatically summarized and archived for retrospective analysis. 108782501Ssheldonh.Ss Monitoring Commands 108855895Ssheldonh.Bl -tag -width indent 108982501Ssheldonh.It Ic statistics Ar name ... 109055895SsheldonhEnables writing of statistics records. 1091285612SdelphijCurrently, eight kinds of 109255895Ssheldonh.Ar name 109355895Ssheldonhstatistics are supported. 109455895Ssheldonh.Bl -tag -width indent 1095158688Spav.It Cm clockstats 1096162806SruEnables recording of clock driver statistics information. 1097162806SruEach update 1098158688Spavreceived from a clock driver appends a line of the following form to 1099158688Spavthe file generation set named 1100158688Spav.Cm clockstats : 1101158688Spav.Bd -literal 1102158688Spav49213 525.624 127.127.4.1 93 226 00:08:29.606 D 1103158688Spav.Ed 1104158688Spav.Pp 1105158688SpavThe first two fields show the date (Modified Julian Day) and time 1106162806Sru(seconds and fraction past UTC midnight). 1107162806SruThe next field shows the 1108285612Sdelphijclock address in dotted\-quad notation. 1109162806SruThe final field shows the last 1110158688Spavtimecode received from the clock in decoded ASCII format, where 1111162806Srumeaningful. 1112162806SruIn some clock drivers a good deal of additional information 1113162806Srucan be gathered and displayed as well. 1114162806SruSee information specific to each 1115158688Spavclock for further details. 1116158688Spav.It Cm cryptostats 1117162806SruThis option requires the OpenSSL cryptographic software library. 1118162806SruIt 1119158688Spavenables recording of cryptographic public key protocol information. 1120158688SpavEach message received by the protocol module appends a line of the 1121158688Spavfollowing form to the file generation set named 1122158688Spav.Cm cryptostats : 1123158688Spav.Bd -literal 1124158688Spav49213 525.624 127.127.4.1 message 1125158688Spav.Ed 1126158688Spav.Pp 1127158688SpavThe first two fields show the date (Modified Julian Day) and time 1128162806Sru(seconds and fraction past UTC midnight). 1129162806SruThe next field shows the peer 1130285612Sdelphijaddress in dotted\-quad notation, The final message field includes the 1131162806Srumessage type and certain ancillary information. 1132162806SruSee the 1133285612Sdelphij.Sx Authentication Options 1134158688Spavsection for further information. 1135107311Sru.It Cm loopstats 113655895SsheldonhEnables recording of loop filter statistics information. 113782501SsheldonhEach 113882501Ssheldonhupdate of the local clock outputs a line of the following form to 1139158688Spavthe file generation set named 1140158688Spav.Cm loopstats : 114182501Ssheldonh.Bd -literal 1142158688Spav50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 114382501Ssheldonh.Ed 114455895Ssheldonh.Pp 114582501SsheldonhThe first two fields show the date (Modified Julian Day) and 114682501Ssheldonhtime (seconds and fraction past UTC midnight). 114782501SsheldonhThe next five fields 1148285612Sdelphijshow time offset (seconds), frequency offset (parts per million \- 114982501SsheldonhPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 115082501Ssheldonhdiscipline time constant. 1151107311Sru.It Cm peerstats 115255895SsheldonhEnables recording of peer statistics information. 115382501SsheldonhThis includes 115482501Ssheldonhstatistics records of all peers of a NTP server and of special 115582501Ssheldonhsignals, where present and configured. 115682501SsheldonhEach valid update appends a 115782501Ssheldonhline of the following form to the current element of a file 1158158688Spavgeneration set named 1159158688Spav.Cm peerstats : 116082501Ssheldonh.Bd -literal 1161285612Sdelphij48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674 116282501Ssheldonh.Ed 116355895Ssheldonh.Pp 116482501SsheldonhThe first two fields show the date (Modified Julian Day) and 116582501Ssheldonhtime (seconds and fraction past UTC midnight). 116682501SsheldonhThe next two fields 1167285612Sdelphijshow the peer address in dotted\-quad notation and status, 116882501Ssheldonhrespectively. 116955895SsheldonhThe status field is encoded in hex in the format 117055895Ssheldonhdescribed in Appendix A of the NTP specification RFC 1305. 1171158688SpavThe final four fields show the offset, 1172158688Spavdelay, dispersion and RMS jitter, all in seconds. 117382501Ssheldonh.It Cm rawstats 1174285612SdelphijEnables recording of raw\-timestamp statistics information. 117582501SsheldonhThis 117682501Ssheldonhincludes statistics records of all peers of a NTP server and of 117782501Ssheldonhspecial signals, where present and configured. 117882501SsheldonhEach NTP message 117982501Ssheldonhreceived from a peer or clock driver appends a line of the 1180158688Spavfollowing form to the file generation set named 1181158688Spav.Cm rawstats : 118282501Ssheldonh.Bd -literal 118382501Ssheldonh50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 118455895Ssheldonh.Ed 1185158688Spav.Pp 118682501SsheldonhThe first two fields show the date (Modified Julian Day) and 118782501Ssheldonhtime (seconds and fraction past UTC midnight). 118882501SsheldonhThe next two fields 118982501Ssheldonhshow the remote peer or clock address followed by the local address 1190285612Sdelphijin dotted\-quad notation. 119193633SsheldonhThe final four fields show the originate, 119255895Ssheldonhreceive, transmit and final NTP timestamps in order. 119382501SsheldonhThe timestamp 119482501Ssheldonhvalues are as received and before processing by the various data 119582501Ssheldonhsmoothing and mitigation algorithms. 1196158688Spav.It Cm sysstats 1197162806SruEnables recording of ntpd statistics counters on a periodic basis. 1198162806SruEach 1199158688Spavhour a line of the following form is appended to the file generation 1200158688Spavset named 1201158688Spav.Cm sysstats : 1202158688Spav.Bd -literal 1203158688Spav50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1204158688Spav.Ed 1205158688Spav.Pp 1206158688SpavThe first two fields show the date (Modified Julian Day) and time 1207162806Sru(seconds and fraction past UTC midnight). 1208162806SruThe remaining ten fields show 1209158688Spavthe statistics counter values accumulated since the last generated 1210158688Spavline. 1211158688Spav.Bl -tag -width indent 1212158688Spav.It Time since restart Cm 36000 1213158688SpavTime in hours since the system was last rebooted. 1214158688Spav.It Packets received Cm 81965 1215158688SpavTotal number of packets received. 1216158688Spav.It Packets processed Cm 0 1217285612SdelphijNumber of packets received in response to previous packets sent 1218158688Spav.It Current version Cm 9546 1219158688SpavNumber of packets matching the current NTP version. 1220158688Spav.It Previous version Cm 56 1221158688SpavNumber of packets matching the previous NTP version. 1222158688Spav.It Bad version Cm 71793 1223158688SpavNumber of packets matching neither NTP version. 1224158688Spav.It Access denied Cm 512 1225158688SpavNumber of packets denied access for any reason. 1226158688Spav.It Bad length or format Cm 540 1227158688SpavNumber of packets with invalid length, format or port number. 1228158688Spav.It Bad authentication Cm 10 1229158688SpavNumber of packets not verified as authentic. 1230158688Spav.It Rate exceeded Cm 147 1231158688SpavNumber of packets discarded due to rate limitation. 123255895Ssheldonh.El 1233158688Spav.It Cm statsdir Ar directory_path 123482501SsheldonhIndicates the full path of a directory where statistics files 1235162806Srushould be created (see below). 1236162806SruThis keyword allows 1237158688Spavthe (otherwise constant) 1238158688Spav.Cm filegen 1239158688Spavfilename prefix to be modified for file generation sets, which 1240158688Spavis useful for handling statistics logs. 1241158688Spav.It Cm filegen Ar name Xo 124282501Ssheldonh.Op Cm file Ar filename 124382501Ssheldonh.Op Cm type Ar typename 1244158688Spav.Op Cm link | nolink 1245158688Spav.Op Cm enable | disable 124655895Ssheldonh.Xc 1247162806SruConfigures setting of generation file set name. 1248162806SruGeneration 1249158688Spavfile sets provide a means for handling files that are 125082501Ssheldonhcontinuously growing during the lifetime of a server. 1251158688SpavServer statistics are a typical example for such files. 1252158688SpavGeneration file sets provide access to a set of files used 1253162806Sruto store the actual data. 1254162806SruAt any time at most one element 1255162806Sruof the set is being written to. 1256162806SruThe type given specifies 1257158688Spavwhen and how data will be directed to a new element of the set. 1258158688SpavThis way, information stored in elements of a file set 1259158688Spavthat are currently unused are available for administrational 1260158688Spavoperations without the risk of disturbing the operation of ntpd. 1261158688Spav(Most important: they can be removed to free space for new data 1262158688Spavproduced.) 1263158688Spav.Pp 126455895SsheldonhNote that this command can be sent from the 1265107311Sru.Xr ntpdc 8 126655895Ssheldonhprogram running at a remote location. 126755895Ssheldonh.Bl -tag -width indent 1268158688Spav.It Cm name 126982501SsheldonhThis is the type of the statistics records, as shown in the 1270158688Spav.Cm statistics 127155895Ssheldonhcommand. 127282501Ssheldonh.It Cm file Ar filename 1273162806SruThis is the file name for the statistics records. 1274162806SruFilenames of set 1275158688Spavmembers are built from three concatenated elements 1276158688Spav.Ar Cm prefix , 1277158688Spav.Ar Cm filename 1278158688Spavand 1279158688Spav.Ar Cm suffix : 128055895Ssheldonh.Bl -tag -width indent 1281158688Spav.It Cm prefix 1282162806SruThis is a constant filename path. 1283162806SruIt is not subject to 128482501Ssheldonhmodifications via the 1285158688Spav.Ar filegen 1286162806Sruoption. 1287162806SruIt is defined by the 1288285612Sdelphijserver, usually specified as a compile\-time constant. 1289162806SruIt may, 1290158688Spavhowever, be configurable for individual file generation sets 1291162806Sruvia other commands. 1292162806SruFor example, the prefix used with 1293158688Spav.Ar loopstats 129482501Ssheldonhand 1295158688Spav.Ar peerstats 1296158688Spavgeneration can be configured using the 1297158688Spav.Ar statsdir 129855895Ssheldonhoption explained above. 1299158688Spav.It Cm filename 130082501SsheldonhThis string is directly concatenated to the prefix mentioned 130182501Ssheldonhabove (no intervening 1302158688Spav.Ql / ) . 1303158688SpavThis can be modified using 1304158688Spavthe file argument to the 1305158688Spav.Ar filegen 1306162806Srustatement. 1307162806SruNo 1308162806Sru.Pa .. 1309162806Sruelements are 1310158688Spavallowed in this component to prevent filenames referring to 1311158688Spavparts outside the filesystem hierarchy denoted by 1312158688Spav.Ar prefix . 1313158688Spav.It Cm suffix 1314162806SruThis part is reflects individual elements of a file set. 1315162806SruIt is 131682501Ssheldonhgenerated according to the type of a file set. 131755895Ssheldonh.El 131882501Ssheldonh.It Cm type Ar typename 1319162806SruA file generation set is characterized by its type. 1320162806SruThe following 1321158688Spavtypes are supported: 132255895Ssheldonh.Bl -tag -width indent 1323158688Spav.It Cm none 132455895SsheldonhThe file set is actually a single plain file. 1325158688Spav.It Cm pid 1326158688SpavOne element of file set is used per incarnation of a ntpd 1327162806Sruserver. 1328162806SruThis type does not perform any changes to file set 1329158688Spavmembers during runtime, however it provides an easy way of 133082501Ssheldonhseparating files belonging to different 1331107311Sru.Xr ntpd 8 1332162806Sruserver incarnations. 1333162806SruThe set member filename is built by appending a 133482501Ssheldonh.Ql \&. 1335158688Spavto concatenated 1336158688Spav.Ar prefix 1337158688Spavand 1338158688Spav.Ar filename 1339158688Spavstrings, and 1340158688Spavappending the decimal representation of the process ID of the 1341107311Sru.Xr ntpd 8 134255895Ssheldonhserver process. 1343158688Spav.It Cm day 1344162806SruOne file generation set element is created per day. 1345162806SruA day is 1346162806Srudefined as the period between 00:00 and 24:00 UTC. 1347162806SruThe file set 134882501Ssheldonhmember suffix consists of a 134982501Ssheldonh.Ql \&. 1350158688Spavand a day specification in 1351158688Spavthe form 1352158688Spav.Cm YYYYMMdd . 1353158688Spav.Cm YYYY 1354285612Sdelphijis a 4\-digit year number (e.g., 1992). 1355158688Spav.Cm MM 135682501Ssheldonhis a two digit month number. 1357158688Spav.Cm dd 135882501Ssheldonhis a two digit day number. 1359158688SpavThus, all information written at 10 December 1992 would end up 1360158688Spavin a file named 1361158688Spav.Ar prefix 1362158688Spav.Ar filename Ns .19921210 . 1363158688Spav.It Cm week 136482501SsheldonhAny file set member contains data related to a certain week of 1365162806Srua year. 1366285612SdelphijThe term week is defined by computing day\-of\-year 1367162806Srumodulo 7. 1368162806SruElements of such a file generation set are 1369158688Spavdistinguished by appending the following suffix to the file set 1370285612Sdelphijfilename base: A dot, a 4\-digit year number, the letter 1371158688Spav.Cm W , 1372285612Sdelphijand a 2\-digit week number. 1373162806SruFor example, information from January, 1374158688Spav10th 1992 would end up in a file with suffix 1375158688Spav.No . Ns Ar 1992W1 . 1376158688Spav.It Cm month 1377162806SruOne generation file set element is generated per month. 1378162806SruThe 1379285612Sdelphijfile name suffix consists of a dot, a 4\-digit year number, and 1380285612Sdelphija 2\-digit month. 1381158688Spav.It Cm year 1382162806SruOne generation file element is generated per year. 1383162806SruThe filename 138482501Ssheldonhsuffix consists of a dot and a 4 digit year number. 1385158688Spav.It Cm age 138682501SsheldonhThis type of file generation sets changes to a new element of 1387162806Sruthe file set every 24 hours of server operation. 1388162806SruThe filename 138982501Ssheldonhsuffix consists of a dot, the letter 1390158688Spav.Cm a , 1391285612Sdelphijand an 8\-digit number. 1392158688SpavThis number is taken to be the number of seconds the server is 1393285612Sdelphijrunning at the start of the corresponding 24\-hour period. 139482501SsheldonhInformation is only written to a file generation by specifying 1395158688Spav.Cm enable ; 139682501Ssheldonhoutput is prevented by specifying 1397158688Spav.Cm disable . 139882501Ssheldonh.El 1399158688Spav.It Cm link | nolink 1400158688SpavIt is convenient to be able to access the current element of a file 1401162806Srugeneration set by a fixed name. 1402162806SruThis feature is enabled by 140382501Ssheldonhspecifying 140482501Ssheldonh.Cm link 140582501Ssheldonhand disabled using 140682501Ssheldonh.Cm nolink . 1407158688SpavIf link is specified, a 1408158688Spavhard link from the current file set element to a file without 1409162806Srusuffix is created. 1410162806SruWhen there is already a file with this name and 1411158688Spavthe number of links of this file is one, it is renamed appending a 1412158688Spavdot, the letter 1413158688Spav.Cm C , 1414298770Sdelphijand the pid of the 1415298770Sdelphij.Xr ntpd 8 1416298770Sdelphijserver process. 1417162806SruWhen the 1418162806Srunumber of links is greater than one, the file is unlinked. 1419162806SruThis 1420158688Spavallows the current file to be accessed by a constant name. 142182501Ssheldonh.It Cm enable \&| Cm disable 142255895SsheldonhEnables or disables the recording function. 142355895Ssheldonh.El 142455895Ssheldonh.El 1425159236Spav.El 142682501Ssheldonh.Sh Access Control Support 1427158688SpavThe 1428107311Sru.Xr ntpd 8 1429158688Spavdaemon implements a general purpose address/mask based restriction 1430162806Srulist. 1431162806SruThe list contains address/match entries sorted first 1432285612Sdelphijby increasing address values and and then by increasing mask values. 1433158688SpavA match occurs when the bitwise AND of the mask and the packet 1434158688Spavsource address is equal to the bitwise AND of the mask and 1435162806Sruaddress in the list. 1436162806SruThe list is searched in order with the 1437158688Spavlast match found defining the restriction flags associated 1438158688Spavwith the entry. 143955895SsheldonhAdditional information and examples can be found in the 1440158688Spav.Qq Notes on Configuring NTP and Setting up a NTP Subnet 1441158688Spavpage 1442158688Spav(available as part of the HTML documentation 1443158688Spavprovided in 1444158688Spav.Pa /usr/share/doc/ntp ) . 144555895Ssheldonh.Pp 1446158688SpavThe restriction facility was implemented in conformance 1447158688Spavwith the access policies for the original NSFnet backbone 1448162806Srutime servers. 1449162806SruLater the facility was expanded to deflect 1450162806Srucryptographic and clogging attacks. 1451162806SruWhile this facility may 1452158688Spavbe useful for keeping unwanted or broken or malicious clients 1453158688Spavfrom congesting innocent servers, it should not be considered 1454158688Spavan alternative to the NTP authentication facilities. 145555895SsheldonhSource address based restrictions are easily circumvented 145655895Ssheldonhby a determined cracker. 1457158688Spav.Pp 1458158688SpavClients can be denied service because they are explicitly 1459298770Sdelphijincluded in the restrict list created by the 1460298770Sdelphij.Ic restrict 1461298770Sdelphijcommand 1462158688Spavor implicitly as the result of cryptographic or rate limit 1463162806Sruviolations. 1464162806SruCryptographic violations include certificate 1465158688Spavor identity verification failure; rate limit violations generally 1466158688Spavresult from defective NTP implementations that send packets 1467162806Sruat abusive rates. 1468162806SruSome violations cause denied service 1469158688Spavonly for the offending packet, others cause denied service 1470158688Spavfor a timed period and others cause the denied service for 1471298770Sdelphijan indefinite period. 1472162806SruWhen a client or network is denied access 1473298770Sdelphijfor an indefinite period, the only way at present to remove 1474158688Spavthe restrictions is by restarting the server. 1475285612Sdelphij.Ss The Kiss\-of\-Death Packet 147682501SsheldonhOrdinarily, packets denied service are simply dropped with no 147782501Ssheldonhfurther action except incrementing statistics counters. 147882501SsheldonhSometimes a 147982501Ssheldonhmore proactive response is needed, such as a server message that 148082501Ssheldonhexplicitly requests the client to stop sending and leave a message 148182501Ssheldonhfor the system operator. 148282501SsheldonhA special packet format has been created 1483285612Sdelphijfor this purpose called the "kiss\-of\-death" (KoD) packet. 1484158688SpavKoD packets have the leap bits set unsynchronized and stratum set 1485285612Sdelphijto zero and the reference identifier field set to a four\-byte 1486158688SpavASCII code. 148782501SsheldonhIf the 1488158688Spav.Cm noserve 1489158688Spavor 1490158688Spav.Cm notrust 1491158688Spavflag of the matching restrict list entry is set, 1492158688Spavthe code is "DENY"; if the 1493158688Spav.Cm limited 1494158688Spavflag is set and the rate limit 1495158688Spavis exceeded, the code is "RATE". 1496158688SpavFinally, if a cryptographic violation occurs, the code is "CRYP". 149782501Ssheldonh.Pp 1498158688SpavA client receiving a KoD performs a set of sanity checks to 1499158688Spavminimize security exposure, then updates the stratum and 1500158688Spavreference identifier peer variables, sets the access 1501158688Spavdenied (TEST4) bit in the peer flash variable and sends 1502162806Srua message to the log. 1503162806SruAs long as the TEST4 bit is set, 1504158688Spavthe client will send no further packets to the server. 1505158688SpavThe only way at present to recover from this condition is 1506162806Sruto restart the protocol at both the client and server. 1507162806SruThis 1508158688Spavhappens automatically at the client when the association times out. 1509158688SpavIt will happen at the server only if the server operator cooperates. 151082501Ssheldonh.Ss Access Control Commands 151155895Ssheldonh.Bl -tag -width indent 1512158688Spav.It Xo Ic discard 1513158688Spav.Op Cm average Ar avg 1514158688Spav.Op Cm minimum Ar min 1515158688Spav.Op Cm monitor Ar prob 1516158688Spav.Xc 1517158688SpavSet the parameters of the 1518158688Spav.Cm limited 1519158688Spavfacility which protects the server from 1520162806Sruclient abuse. 1521162806SruThe 1522158688Spav.Cm average 1523158688Spavsubcommand specifies the minimum average packet 1524158688Spavspacing, while the 1525158688Spav.Cm minimum 1526158688Spavsubcommand specifies the minimum packet spacing. 1527285612SdelphijPackets that violate these minima are discarded 1528285612Sdelphijand a kiss\-o'\-death packet returned if enabled. 1529162806SruThe default 1530158688Spavminimum average and minimum are 5 and 2, respectively. 1531298770SdelphijThe 1532298770Sdelphij.Ic monitor 1533298770Sdelphijsubcommand specifies the probability of discard 1534285612Sdelphijfor packets that overflow the rate\-control window. 1535158688Spav.It Xo Ic restrict address 1536158688Spav.Op Cm mask Ar mask 153782501Ssheldonh.Op Ar flag ... 153855895Ssheldonh.Xc 153955895SsheldonhThe 1540158688Spav.Ar address 1541158688Spavargument expressed in 1542285612Sdelphijdotted\-quad form is the address of a host or network. 1543158688SpavAlternatively, the 1544158688Spav.Ar address 1545162806Sruargument can be a valid host DNS name. 1546162806SruThe 1547158688Spav.Ar mask 1548285612Sdelphijargument expressed in dotted\-quad form defaults to 1549158688Spav.Cm 255.255.255.255 , 1550158688Spavmeaning that the 1551158688Spav.Ar address 1552158688Spavis treated as the address of an individual host. 1553158688SpavA default entry (address 1554158688Spav.Cm 0.0.0.0 , 1555158688Spavmask 1556158688Spav.Cm 0.0.0.0 ) 1557158688Spavis always included and is always the first entry in the list. 1558158688SpavNote that text string 1559158688Spav.Cm default , 156082501Ssheldonhwith no mask option, may 156182501Ssheldonhbe used to indicate the default entry. 156282501SsheldonhIn the current implementation, 156382501Ssheldonh.Cm flag 156482501Ssheldonhalways 156582501Ssheldonhrestricts access, i.e., an entry with no flags indicates that free 156682501Ssheldonhaccess to the server is to be given. 156782501SsheldonhThe flags are not orthogonal, 156882501Ssheldonhin that more restrictive flags will often make less restrictive 156982501Ssheldonhones redundant. 157082501SsheldonhThe flags can generally be classed into two 1571108317Sschweikhcategories, those which restrict time service and those which 1572285612Sdelphijrestrict informational queries and attempts to do run\-time 157382501Ssheldonhreconfiguration of the server. 157482501SsheldonhOne or more of the following flags 157582501Ssheldonhmay be specified: 157655895Ssheldonh.Bl -tag -width indent 1577158688Spav.It Cm ignore 1578158688SpavDeny packets of all kinds, including 1579158688Spav.Xr ntpq 8 1580158688Spavand 1581158688Spav.Xr ntpdc 8 1582158688Spavqueries. 158382501Ssheldonh.It Cm kod 1584285612SdelphijIf this flag is set when an access violation occurs, a kiss\-o'\-death 1585162806Sru(KoD) packet is sent. 1586162806SruKoD packets are rate limited to no more than one 1587162806Sruper second. 1588162806SruIf another KoD packet occurs within one second after the 1589158688Spavlast one, the packet is dropped. 1590158688Spav.It Cm limited 1591158688SpavDeny service if the packet spacing violates the lower limits specified 1592298770Sdelphijin the 1593298770Sdelphij.Ic discard 1594298770Sdelphijcommand. 1595162806SruA history of clients is kept using the 1596158688Spavmonitoring capability of 1597158688Spav.Xr ntpd 8 . 1598158688SpavThus, monitoring is always active as 1599158688Spavlong as there is a restriction entry with the 1600158688Spav.Cm limited 1601158688Spavflag. 160282501Ssheldonh.It Cm lowpriotrap 160355895SsheldonhDeclare traps set by matching hosts to be low priority. 160482501SsheldonhThe 160582501Ssheldonhnumber of traps a server can maintain is limited (the current limit 160682501Ssheldonhis 3). 160782501SsheldonhTraps are usually assigned on a first come, first served 160882501Ssheldonhbasis, with later trap requestors being denied service. 160982501SsheldonhThis flag 161082501Ssheldonhmodifies the assignment algorithm by allowing low priority traps to 161182501Ssheldonhbe overridden by later requests for normal priority traps. 1612158688Spav.It Cm nomodify 1613158688SpavDeny 1614158688Spav.Xr ntpq 8 1615158688Spavand 1616158688Spav.Xr ntpdc 8 1617158688Spavqueries which attempt to modify the state of the 1618162806Sruserver (i.e., run time reconfiguration). 1619162806SruQueries which return 1620158688Spavinformation are permitted. 1621158688Spav.It Cm noquery 1622158688SpavDeny 1623158688Spav.Xr ntpq 8 1624158688Spavand 1625158688Spav.Xr ntpdc 8 1626162806Sruqueries. 1627162806SruTime service is not affected. 1628158688Spav.It Cm nopeer 1629162806SruDeny packets which would result in mobilizing a new association. 1630162806SruThis 1631158688Spavincludes broadcast and symmetric active packets when a configured 1632158688Spavassociation does not exist. 1633285612SdelphijIt also includes 1634285612Sdelphij.Cm pool 1635285612Sdelphijassociations, so if you want to use servers from a 1636285612Sdelphij.Cm pool 1637285612Sdelphijdirective and also want to use 1638285612Sdelphij.Cm nopeer 1639285612Sdelphijby default, you'll want a 1640285612Sdelphij.Cm "restrict source ..." line as well that does 1641285612Sdelphij.It not 1642285612Sdelphijinclude the 1643285612Sdelphij.Cm nopeer 1644285612Sdelphijdirective. 164582501Ssheldonh.It Cm noserve 1646158688SpavDeny all packets except 1647107311Sru.Xr ntpq 8 164855895Ssheldonhand 1649107311Sru.Xr ntpdc 8 1650158688Spavqueries. 1651158688Spav.It Cm notrap 1652158688SpavDecline to provide mode 6 control message trap service to matching 1653162806Sruhosts. 1654298770SdelphijThe trap service is a subsystem of the 1655298770Sdelphij.Xr ntpq 8 1656298770Sdelphijcontrol message 1657158688Spavprotocol which is intended for use by remote event logging programs. 1658158688Spav.It Cm notrust 1659158688SpavDeny service unless the packet is cryptographically authenticated. 166082501Ssheldonh.It Cm ntpport 166182501SsheldonhThis is actually a match algorithm modifier, rather than a 166282501Ssheldonhrestriction flag. 166382501SsheldonhIts presence causes the restriction entry to be 166482501Ssheldonhmatched only if the source port in the packet is the standard NTP 166582501SsheldonhUDP port (123). 166682501SsheldonhBoth 166782501Ssheldonh.Cm ntpport 166882501Ssheldonhand 1669285612Sdelphij.Cm non\-ntpport 167082501Ssheldonhmay 167182501Ssheldonhbe specified. 167282501SsheldonhThe 167382501Ssheldonh.Cm ntpport 167482501Ssheldonhis considered more specific and 167582501Ssheldonhis sorted later in the list. 1676107311Sru.It Cm version 1677158688SpavDeny packets that do not match the current NTP version. 167855895Ssheldonh.El 167955895Ssheldonh.Pp 1680158688SpavDefault restriction list entries with the flags ignore, interface, 1681158688Spavntpport, for each of the local host's interface addresses are 1682158688Spavinserted into the table at startup to prevent the server 1683158688Spavfrom attempting to synchronize to its own time. 1684158688SpavA default entry is also always present, though if it is 1685158688Spavotherwise unconfigured; no flags are associated 1686158688Spavwith the default entry (i.e., everything besides your own 1687158688SpavNTP server is unrestricted). 168855895Ssheldonh.El 1689158688Spav.Sh Automatic NTP Configuration Options 1690158688Spav.Ss Manycasting 1691158688SpavManycasting is a automatic discovery and configuration paradigm 1692162806Srunew to NTPv4. 1693162806SruIt is intended as a means for a multicast client 1694158688Spavto troll the nearby network neighborhood to find cooperating 1695158688Spavmanycast servers, validate them using cryptographic means 1696158688Spavand evaluate their time values with respect to other servers 1697158688Spavthat might be lurking in the vicinity. 1698158688SpavThe intended result is that each manycast client mobilizes 1699158688Spavclient associations with some number of the "best" 1700158688Spavof the nearby manycast servers, yet automatically reconfigures 1701158688Spavto sustain this number of servers should one or another fail. 1702158688Spav.Pp 1703158688SpavNote that the manycasting paradigm does not coincide 1704285612Sdelphijwith the anycast paradigm described in RFC\-1546, 1705158688Spavwhich is designed to find a single server from a clique 1706158688Spavof servers providing the same service. 1707158688SpavThe manycast paradigm is designed to find a plurality 1708158688Spavof redundant servers satisfying defined optimality criteria. 1709158688Spav.Pp 1710158688SpavManycasting can be used with either symmetric key 1711162806Sruor public key cryptography. 1712162806SruThe public key infrastructure (PKI) 1713158688Spavoffers the best protection against compromised keys 1714158688Spavand is generally considered stronger, at least with relatively 1715158688Spavlarge key sizes. 1716158688SpavIt is implemented using the Autokey protocol and 1717158688Spavthe OpenSSL cryptographic library available from 1718158688Spav.Li http://www.openssl.org/ . 1719158688SpavThe library can also be used with other NTPv4 modes 1720158688Spavas well and is highly recommended, especially for broadcast modes. 1721158688Spav.Pp 1722158688SpavA persistent manycast client association is configured 1723298770Sdelphijusing the 1724298770Sdelphij.Ic manycastclient 1725298770Sdelphijcommand, which is similar to the 1726298770Sdelphij.Ic server 1727298770Sdelphijcommand but with a multicast (IPv4 class 1728158688Spav.Cm D 1729158688Spavor IPv6 prefix 1730158688Spav.Cm FF ) 1731162806Srugroup address. 1732162806SruThe IANA has designated IPv4 address 224.1.1.1 1733158688Spavand IPv6 address FF05::101 (site local) for NTP. 1734158688SpavWhen more servers are needed, it broadcasts manycast 1735158688Spavclient messages to this address at the minimum feasible rate 1736285612Sdelphijand minimum feasible time\-to\-live (TTL) hops, depending 1737158688Spavon how many servers have already been found. 1738158688SpavThere can be as many manycast client associations 1739158688Spavas different group address, each one serving as a template 1740158688Spavfor a future ephemeral unicast client/server association. 1741158688Spav.Pp 1742158688SpavManycast servers configured with the 1743158688Spav.Ic manycastserver 1744158688Spavcommand listen on the specified group address for manycast 1745162806Sruclient messages. 1746162806SruNote the distinction between manycast client, 1747158688Spavwhich actively broadcasts messages, and manycast server, 1748162806Sruwhich passively responds to them. 1749162806SruIf a manycast server is 1750158688Spavin scope of the current TTL and is itself synchronized 1751158688Spavto a valid source and operating at a stratum level equal 1752158688Spavto or lower than the manycast client, it replies to the 1753158688Spavmanycast client message with an ordinary unicast server message. 1754158688Spav.Pp 1755158688SpavThe manycast client receiving this message mobilizes 1756158688Spavan ephemeral client/server association according to the 1757158688Spavmatching manycast client template, but only if cryptographically 1758158688Spavauthenticated and the server stratum is less than or equal 1759162806Sruto the client stratum. 1760162806SruAuthentication is explicitly required 1761158688Spavand either symmetric key or public key (Autokey) can be used. 1762158688SpavThen, the client polls the server at its unicast address 1763158688Spavin burst mode in order to reliably set the host clock 1764162806Sruand validate the source. 1765162806SruThis normally results 1766285612Sdelphijin a volley of eight client/server at 2\-s intervals 1767158688Spavduring which both the synchronization and cryptographic 1768162806Sruprotocols run concurrently. 1769162806SruFollowing the volley, 1770158688Spavthe client runs the NTP intersection and clustering 1771158688Spavalgorithms, which act to discard all but the "best" 1772158688Spavassociations according to stratum and synchronization 1773162806Srudistance. 1774162806SruThe surviving associations then continue 1775158688Spavin ordinary client/server mode. 1776158688Spav.Pp 1777158688SpavThe manycast client polling strategy is designed to reduce 1778158688Spavas much as possible the volume of manycast client messages 1779285612Sdelphijand the effects of implosion due to near\-simultaneous 1780158688Spavarrival of manycast server messages. 1781158688SpavThe strategy is determined by the 1782158688Spav.Ic manycastclient , 1783158688Spav.Ic tos 1784158688Spavand 1785158688Spav.Ic ttl 1786162806Sruconfiguration commands. 1787162806SruThe manycast poll interval is 1788158688Spavnormally eight times the system poll interval, 1789158688Spavwhich starts out at the 1790158688Spav.Cm minpoll 1791158688Spavvalue specified in the 1792158688Spav.Ic manycastclient , 1793158688Spavcommand and, under normal circumstances, increments to the 1794158688Spav.Cm maxpolll 1795162806Sruvalue specified in this command. 1796162806SruInitially, the TTL is 1797298770Sdelphijset at the minimum hops specified by the 1798298770Sdelphij.Ic ttl 1799298770Sdelphijcommand. 1800158688SpavAt each retransmission the TTL is increased until reaching 1801158688Spavthe maximum hops specified by this command or a sufficient 1802158688Spavnumber client associations have been found. 1803158688SpavFurther retransmissions use the same TTL. 1804158688Spav.Pp 1805158688SpavThe quality and reliability of the suite of associations 1806158688Spavdiscovered by the manycast client is determined by the NTP 1807158688Spavmitigation algorithms and the 1808158688Spav.Cm minclock 1809158688Spavand 1810158688Spav.Cm minsane 1811158688Spavvalues specified in the 1812158688Spav.Ic tos 1813162806Sruconfiguration command. 1814162806SruAt least 1815158688Spav.Cm minsane 1816158688Spavcandidate servers must be available and the mitigation 1817158688Spavalgorithms produce at least 1818158688Spav.Cm minclock 1819158688Spavsurvivors in order to synchronize the clock. 1820158688SpavByzantine agreement principles require at least four 1821158688Spavcandidates in order to correctly discard a single falseticker. 1822158688SpavFor legacy purposes, 1823158688Spav.Cm minsane 1824158688Spavdefaults to 1 and 1825158688Spav.Cm minclock 1826162806Srudefaults to 3. 1827162806SruFor manycast service 1828158688Spav.Cm minsane 1829162806Srushould be explicitly set to 4, assuming at least that 1830158688Spavnumber of servers are available. 1831158688Spav.Pp 1832158688SpavIf at least 1833158688Spav.Cm minclock 1834158688Spavservers are found, the manycast poll interval is immediately 1835158688Spavset to eight times 1836158688Spav.Cm maxpoll . 1837158688SpavIf less than 1838158688Spav.Cm minclock 1839158688Spavservers are found when the TTL has reached the maximum hops, 1840162806Sruthe manycast poll interval is doubled. 1841162806SruFor each transmission 1842158688Spavafter that, the poll interval is doubled again until 1843158688Spavreaching the maximum of eight times 1844158688Spav.Cm maxpoll . 1845158688SpavFurther transmissions use the same poll interval and 1846162806SruTTL values. 1847162806SruNote that while all this is going on, 1848158688Spaveach client/server association found is operating normally 1849158688Spavit the system poll interval. 1850158688Spav.Pp 1851158688SpavAdministratively scoped multicast boundaries are normally 1852158688Spavspecified by the network router configuration and, 1853158688Spavin the case of IPv6, the link/site scope prefix. 1854158688SpavBy default, the increment for TTL hops is 32 starting 1855158688Spavfrom 31; however, the 1856158688Spav.Ic ttl 1857158688Spavconfiguration command can be 1858158688Spavused to modify the values to match the scope rules. 1859158688Spav.Pp 1860158688SpavIt is often useful to narrow the range of acceptable 1861158688Spavservers which can be found by manycast client associations. 1862158688SpavBecause manycast servers respond only when the client 1863158688Spavstratum is equal to or greater than the server stratum, 1864285612Sdelphijprimary (stratum 1) servers fill find only primary servers 1865158688Spavin TTL range, which is probably the most common objective. 1866158688SpavHowever, unless configured otherwise, all manycast clients 1867158688Spavin TTL range will eventually find all primary servers 1868158688Spavin TTL range, which is probably not the most common 1869162806Sruobjective in large networks. 1870162806SruThe 1871158688Spav.Ic tos 1872158688Spavcommand can be used to modify this behavior. 1873158688SpavServers with stratum below 1874158688Spav.Cm floor 1875158688Spavor above 1876158688Spav.Cm ceiling 1877158688Spavspecified in the 1878158688Spav.Ic tos 1879158688Spavcommand are strongly discouraged during the selection 1880158688Spavprocess; however, these servers may be temporally 1881158688Spavaccepted if the number of servers within TTL range is 1882158688Spavless than 1883158688Spav.Cm minclock . 1884158688Spav.Pp 1885158688SpavThe above actions occur for each manycast client message, 1886158688Spavwhich repeats at the designated poll interval. 1887158688SpavHowever, once the ephemeral client association is mobilized, 1888158688Spavsubsequent manycast server replies are discarded, 1889158688Spavsince that would result in a duplicate association. 1890158688SpavIf during a poll interval the number of client associations 1891158688Spavfalls below 1892158688Spav.Cm minclock , 1893158688Spavall manycast client prototype associations are reset 1894158688Spavto the initial poll interval and TTL hops and operation 1895162806Sruresumes from the beginning. 1896162806SruIt is important to avoid 1897158688Spavfrequent manycast client messages, since each one requires 1898158688Spavall manycast servers in TTL range to respond. 1899158688SpavThe result could well be an implosion, either minor or major, 1900158688Spavdepending on the number of servers in range. 1901158688SpavThe recommended value for 1902158688Spav.Cm maxpoll 1903158688Spavis 12 (4,096 s). 1904158688Spav.Pp 1905158688SpavIt is possible and frequently useful to configure a host 1906158688Spavas both manycast client and manycast server. 1907158688SpavA number of hosts configured this way and sharing a common 1908158688Spavgroup address will automatically organize themselves 1909158688Spavin an optimum configuration based on stratum and 1910162806Srusynchronization distance. 1911162806SruFor example, consider an NTP 1912158688Spavsubnet of two primary servers and a hundred or more 1913162806Srudependent clients. 1914162806SruWith two exceptions, all servers 1915158688Spavand clients have identical configuration files including both 1916158688Spav.Ic multicastclient 1917158688Spavand 1918158688Spav.Ic multicastserver 1919158688Spavcommands using, for instance, multicast group address 1920162806Sru239.1.1.1. 1921162806SruThe only exception is that each primary server 1922158688Spavconfiguration file must include commands for the primary 1923158688Spavreference source such as a GPS receiver. 1924158688Spav.Pp 1925158688SpavThe remaining configuration files for all secondary 1926158688Spavservers and clients have the same contents, except for the 1927158688Spav.Ic tos 1928158688Spavcommand, which is specific for each stratum level. 1929158688SpavFor stratum 1 and stratum 2 servers, that command is 1930162806Srunot necessary. 1931162806SruFor stratum 3 and above servers the 1932158688Spav.Cm floor 1933158688Spavvalue is set to the intended stratum number. 1934158688SpavThus, all stratum 3 configuration files are identical, 1935158688Spavall stratum 4 files are identical and so forth. 1936158688Spav.Pp 1937158688SpavOnce operations have stabilized in this scenario, 1938158688Spavthe primary servers will find the primary reference source 1939158688Spavand each other, since they both operate at the same 1940158688Spavstratum (1), but not with any secondary server or client, 1941162806Srusince these operate at a higher stratum. 1942162806SruThe secondary 1943158688Spavservers will find the servers at the same stratum level. 1944158688SpavIf one of the primary servers loses its GPS receiver, 1945158688Spavit will continue to operate as a client and other clients 1946158688Spavwill time out the corresponding association and 1947285612Sdelphijre\-associate accordingly. 1948158688Spav.Pp 1949158688SpavSome administrators prefer to avoid running 1950158688Spav.Xr ntpd 8 1951158688Spavcontinuously and run either 1952289999Sglebius.Xr sntp 8 1953158688Spavor 1954158688Spav.Xr ntpd 8 1955158688Spav.Fl q 1956162806Sruas a cron job. 1957162806SruIn either case the servers must be 1958158688Spavconfigured in advance and the program fails if none are 1959162806Sruavailable when the cron job runs. 1960162806SruA really slick 1961158688Spavapplication of manycast is with 1962158688Spav.Xr ntpd 8 1963158688Spav.Fl q . 1964158688SpavThe program wakes up, scans the local landscape looking 1965158688Spavfor the usual suspects, selects the best from among 1966158688Spavthe rascals, sets the clock and then departs. 1967158688SpavServers do not have to be configured in advance and 1968158688Spavall clients throughout the network can have the same 1969158688Spavconfiguration file. 1970158688Spav.Ss Manycast Interactions with Autokey 1971158688SpavEach time a manycast client sends a client mode packet 1972158688Spavto a multicast group address, all manycast servers 1973158688Spavin scope generate a reply including the host name 1974162806Sruand status word. 1975162806SruThe manycast clients then run 1976158688Spavthe Autokey protocol, which collects and verifies 1977162806Sruall certificates involved. 1978162806SruFollowing the burst interval 1979158688Spavall but three survivors are cast off, 1980158688Spavbut the certificates remain in the local cache. 1981158688SpavIt often happens that several complete signing trails 1982158688Spavfrom the client to the primary servers are collected in this way. 1983158688Spav.Pp 1984158688SpavAbout once an hour or less often if the poll interval 1985158688Spavexceeds this, the client regenerates the Autokey key list. 1986158688SpavThis is in general transparent in client/server mode. 1987158688SpavHowever, about once per day the server private value 1988158688Spavused to generate cookies is refreshed along with all 1989162806Srumanycast client associations. 1990162806SruIn this case all 1991158688Spavcryptographic values including certificates is refreshed. 1992158688SpavIf a new certificate has been generated since 1993158688Spavthe last refresh epoch, it will automatically revoke 1994158688Spavall prior certificates that happen to be in the 1995162806Srucertificate cache. 1996162806SruAt the same time, the manycast 1997158688Spavscheme starts all over from the beginning and 1998158688Spavthe expanding ring shrinks to the minimum and increments 1999158688Spavfrom there while collecting all servers in scope. 2000310419Sdelphij.Ss Broadcast Options 2001310419Sdelphij.Bl -tag -width indent 2002310419Sdelphij.It Xo Ic tos 2003310419Sdelphij.Oo 2004310419Sdelphij.Cm bcpollbstep Ar gate 2005310419Sdelphij.Oc 2006310419Sdelphij.Xc 2007310419SdelphijThis command provides a way to delay, 2008310419Sdelphijby the specified number of broadcast poll intervals, 2009310419Sdelphijbelieving backward time steps from a broadcast server. 2010310419SdelphijBroadcast time networks are expected to be trusted. 2011310419SdelphijIn the event a broadcast server's time is stepped backwards, 2012310419Sdelphijthere is clear benefit to having the clients notice this change 2013310419Sdelphijas soon as possible. 2014310419SdelphijAttacks such as replay attacks can happen, however, 2015310419Sdelphijand even though there are a number of protections built in to 2016310419Sdelphijbroadcast mode, attempts to perform a replay attack are possible. 2017310419SdelphijThis value defaults to 0, but can be changed 2018310419Sdelphijto any number of poll intervals between 0 and 4. 2019158688Spav.Ss Manycast Options 2020158688Spav.Bl -tag -width indent 2021158688Spav.It Xo Ic tos 2022158688Spav.Oo 2023158688Spav.Cm ceiling Ar ceiling | 2024158688Spav.Cm cohort { 0 | 1 } | 2025158688Spav.Cm floor Ar floor | 2026158688Spav.Cm minclock Ar minclock | 2027158688Spav.Cm minsane Ar minsane 2028158688Spav.Oc 2029158688Spav.Xc 2030158688SpavThis command affects the clock selection and clustering 2031162806Srualgorithms. 2032162806SruIt can be used to select the quality and 2033158688Spavquantity of peers used to synchronize the system clock 2034162806Sruand is most useful in manycast mode. 2035162806SruThe variables operate 2036158688Spavas follows: 2037158688Spav.Bl -tag -width indent 2038158688Spav.It Cm ceiling Ar ceiling 2039158688SpavPeers with strata above 2040158688Spav.Cm ceiling 2041158688Spavwill be discarded if there are at least 2042158688Spav.Cm minclock 2043158688Spavpeers remaining. 2044158688SpavThis value defaults to 15, but can be changed 2045158688Spavto any number from 1 to 15. 2046158688Spav.It Cm cohort Bro 0 | 1 Brc 2047158688SpavThis is a binary flag which enables (0) or disables (1) 2048158688Spavmanycast server replies to manycast clients with the same 2049162806Srustratum level. 2050162806SruThis is useful to reduce implosions where 2051158688Spavlarge numbers of clients with the same stratum level 2052162806Sruare present. 2053162806SruThe default is to enable these replies. 2054158688Spav.It Cm floor Ar floor 2055158688SpavPeers with strata below 2056158688Spav.Cm floor 2057158688Spavwill be discarded if there are at least 2058158688Spav.Cm minclock 2059158688Spavpeers remaining. 2060158688SpavThis value defaults to 1, but can be changed 2061158688Spavto any number from 1 to 15. 2062158688Spav.It Cm minclock Ar minclock 2063289999SglebiusThe clustering algorithm repeatedly casts out outlier 2064158688Spavassociations until no more than 2065158688Spav.Cm minclock 2066162806Sruassociations remain. 2067162806SruThis value defaults to 3, 2068158688Spavbut can be changed to any number from 1 to the number of 2069158688Spavconfigured sources. 2070158688Spav.It Cm minsane Ar minsane 2071158688SpavThis is the minimum number of candidates available 2072158688Spavto the clock selection algorithm in order to produce 2073285612Sdelphijone or more truechimers for the clustering algorithm. 2074158688SpavIf fewer than this number are available, the clock is 2075162806Sruundisciplined and allowed to run free. 2076162806SruThe default is 1 2077162806Srufor legacy purposes. 2078162806SruHowever, according to principles of 2079158688SpavByzantine agreement, 2080158688Spav.Cm minsane 2081158688Spavshould be at least 4 in order to detect and discard 2082158688Spava single falseticker. 2083158688Spav.El 2084158688Spav.It Cm ttl Ar hop ... 2085158688SpavThis command specifies a list of TTL values in increasing 2086162806Sruorder, up to 8 values can be specified. 2087158688SpavIn manycast mode these values are used in turn 2088285612Sdelphijin an expanding\-ring search. 2089162806SruThe default is eight 2090158688Spavmultiples of 32 starting at 31. 2091158688Spav.El 209282501Ssheldonh.Sh Reference Clock Support 209382501SsheldonhThe NTP Version 4 daemon supports some three dozen different radio, 2094285612Sdelphijsatellite and modem reference clocks plus a special pseudo\-clock 209582501Ssheldonhused for backup or when no other clock source is available. 209682501SsheldonhDetailed descriptions of individual device drivers and options can 209782501Ssheldonhbe found in the 2098158688Spav.Qq Reference Clock Drivers 209982501Ssheldonhpage 210082501Ssheldonh(available as part of the HTML documentation 210182501Ssheldonhprovided in 210282501Ssheldonh.Pa /usr/share/doc/ntp ) . 210382501SsheldonhAdditional information can be found in the pages linked 210482501Ssheldonhthere, including the 2105158688Spav.Qq Debugging Hints for Reference Clock Drivers 210655895Ssheldonhand 2107158688Spav.Qq How To Write a Reference Clock Driver 2108158688Spavpages 2109158688Spav(available as part of the HTML documentation 2110158688Spavprovided in 2111158688Spav.Pa /usr/share/doc/ntp ) . 211282501SsheldonhIn addition, support for a PPS 211382501Ssheldonhsignal is available as described in the 2114285612Sdelphij.Qq Pulse\-per\-second (PPS) Signal Interfacing 2115158688Spavpage 2116158688Spav(available as part of the HTML documentation 2117158688Spavprovided in 2118158688Spav.Pa /usr/share/doc/ntp ) . 211982501SsheldonhMany 212082501Ssheldonhdrivers support special line discipline/streams modules which can 212182501Ssheldonhsignificantly improve the accuracy using the driver. 212282501SsheldonhThese are 212382501Ssheldonhdescribed in the 2124158688Spav.Qq Line Disciplines and Streams Drivers 2125158688Spavpage 2126158688Spav(available as part of the HTML documentation 2127158688Spavprovided in 2128158688Spav.Pa /usr/share/doc/ntp ) . 212955895Ssheldonh.Pp 213082501SsheldonhA reference clock will generally (though not always) be a radio 213182501Ssheldonhtimecode receiver which is synchronized to a source of standard 213282501Ssheldonhtime such as the services offered by the NRC in Canada and NIST and 213382501SsheldonhUSNO in the US. 213482501SsheldonhThe interface between the computer and the timecode 213582501Ssheldonhreceiver is device dependent, but is usually a serial port. 213682501SsheldonhA 213782501Ssheldonhdevice driver specific to each reference clock must be selected and 213882501Ssheldonhcompiled in the distribution; however, most common radio, satellite 213982501Ssheldonhand modem clocks are included by default. 214082501SsheldonhNote that an attempt to 214182501Ssheldonhconfigure a reference clock when the driver has not been compiled 214282501Ssheldonhor the hardware port has not been appropriately configured results 214382501Ssheldonhin a scalding remark to the system log file, but is otherwise non 214482501Ssheldonhhazardous. 214555895Ssheldonh.Pp 214655895SsheldonhFor the purposes of configuration, 214755895Ssheldonh.Xr ntpd 8 214882501Ssheldonhtreats 214982501Ssheldonhreference clocks in a manner analogous to normal NTP peers as much 215082501Ssheldonhas possible. 215182501SsheldonhReference clocks are identified by a syntactically 215282501Ssheldonhcorrect but invalid IP address, in order to distinguish them from 215382501Ssheldonhnormal NTP peers. 215482501SsheldonhReference clock addresses are of the form 215582501Ssheldonh.Sm off 215682501Ssheldonh.Li 127.127. Ar t . Ar u , 215782501Ssheldonh.Sm on 215855895Ssheldonhwhere 215955895Ssheldonh.Ar t 216082501Ssheldonhis an integer 216182501Ssheldonhdenoting the clock type and 216255895Ssheldonh.Ar u 216382501Ssheldonhindicates the unit 2164285612Sdelphijnumber in the range 0\-3. 216582501SsheldonhWhile it may seem overkill, it is in fact 216682501Ssheldonhsometimes useful to configure multiple reference clocks of the same 216782501Ssheldonhtype, in which case the unit numbers must be unique. 216855895Ssheldonh.Pp 216955895SsheldonhThe 217055895Ssheldonh.Ic server 217182501Ssheldonhcommand is used to configure a reference 217282501Ssheldonhclock, where the 217382501Ssheldonh.Ar address 217482501Ssheldonhargument in that command 217582501Ssheldonhis the clock address. 217682501SsheldonhThe 2177131531Sru.Cm key , 217882501Ssheldonh.Cm version 217982501Ssheldonhand 218082501Ssheldonh.Cm ttl 218182501Ssheldonhoptions are not used for reference clock support. 218282501SsheldonhThe 218382501Ssheldonh.Cm mode 218482501Ssheldonhoption is added for reference clock support, as 218582501Ssheldonhdescribed below. 218682501SsheldonhThe 218782501Ssheldonh.Cm prefer 218882501Ssheldonhoption can be useful to 218982501Ssheldonhpersuade the server to cherish a reference clock with somewhat more 219082501Ssheldonhenthusiasm than other reference clocks or peers. 219182501SsheldonhFurther 219282501Ssheldonhinformation on this option can be found in the 2193158688Spav.Qq Mitigation Rules and the prefer Keyword 2194158688Spav(available as part of the HTML documentation 2195158688Spavprovided in 2196158688Spav.Pa /usr/share/doc/ntp ) 219755895Ssheldonhpage. 219882501SsheldonhThe 219982501Ssheldonh.Cm minpoll 220082501Ssheldonhand 220182501Ssheldonh.Cm maxpoll 220282501Ssheldonhoptions have 220382501Ssheldonhmeaning only for selected clock drivers. 220482501SsheldonhSee the individual clock 220582501Ssheldonhdriver document pages for additional information. 220655895Ssheldonh.Pp 220782501SsheldonhThe 220882501Ssheldonh.Ic fudge 220982501Ssheldonhcommand is used to provide additional 221082501Ssheldonhinformation for individual clock drivers and normally follows 221182501Ssheldonhimmediately after the 221282501Ssheldonh.Ic server 221382501Ssheldonhcommand. 221482501SsheldonhThe 221582501Ssheldonh.Ar address 221682501Ssheldonhargument specifies the clock address. 221782501SsheldonhThe 221882501Ssheldonh.Cm refid 221982501Ssheldonhand 222082501Ssheldonh.Cm stratum 222193633Ssheldonhoptions can be used to 222282501Ssheldonhoverride the defaults for the device. 222382501SsheldonhThere are two optional 2224285612Sdelphijdevice\-dependent time offsets and four flags that can be included 222582501Ssheldonhin the 2226107311Sru.Ic fudge 222782501Ssheldonhcommand as well. 222882501Ssheldonh.Pp 222955895SsheldonhThe stratum number of a reference clock is by default zero. 223055895SsheldonhSince the 223155895Ssheldonh.Xr ntpd 8 223282501Ssheldonhdaemon adds one to the stratum of each 223382501Ssheldonhpeer, a primary server ordinarily displays an external stratum of 223482501Ssheldonhone. 223582501SsheldonhIn order to provide engineered backups, it is often useful to 223682501Ssheldonhspecify the reference clock stratum as greater than zero. 223782501SsheldonhThe 2238107311Sru.Cm stratum 223982501Ssheldonhoption is used for this purpose. 224082501SsheldonhAlso, in cases 2241285612Sdelphijinvolving both a reference clock and a pulse\-per\-second (PPS) 224282501Ssheldonhdiscipline signal, it is useful to specify the reference clock 224382501Ssheldonhidentifier as other than the default, depending on the driver. 224482501SsheldonhThe 224582501Ssheldonh.Cm refid 224682501Ssheldonhoption is used for this purpose. 224755895SsheldonhExcept where noted, 224855895Ssheldonhthese options apply to all clock drivers. 224982501Ssheldonh.Ss Reference Clock Commands 225055895Ssheldonh.Bl -tag -width indent 225182501Ssheldonh.It Xo Ic server 225282501Ssheldonh.Sm off 225382501Ssheldonh.Li 127.127. Ar t . Ar u 225482501Ssheldonh.Sm on 225582501Ssheldonh.Op Cm prefer 225682501Ssheldonh.Op Cm mode Ar int 225782501Ssheldonh.Op Cm minpoll Ar int 225882501Ssheldonh.Op Cm maxpoll Ar int 225955895Ssheldonh.Xc 226082501SsheldonhThis command can be used to configure reference clocks in 226182501Ssheldonhspecial ways. 226255895SsheldonhThe options are interpreted as follows: 226355895Ssheldonh.Bl -tag -width indent 226482501Ssheldonh.It Cm prefer 226555895SsheldonhMarks the reference clock as preferred. 226682501SsheldonhAll other things being 226782501Ssheldonhequal, this host will be chosen for synchronization among a set of 226882501Ssheldonhcorrectly operating hosts. 226955895SsheldonhSee the 2270158688Spav.Qq Mitigation Rules and the prefer Keyword 2271158688Spavpage 2272158688Spav(available as part of the HTML documentation 2273158688Spavprovided in 2274158688Spav.Pa /usr/share/doc/ntp ) 2275158688Spavfor further information. 227682501Ssheldonh.It Cm mode Ar int 227782501SsheldonhSpecifies a mode number which is interpreted in a 2278285612Sdelphijdevice\-specific fashion. 227982501SsheldonhFor instance, it selects a dialing 228082501Ssheldonhprotocol in the ACTS driver and a device subtype in the 228182501Ssheldonhparse 228282501Ssheldonhdrivers. 228382501Ssheldonh.It Cm minpoll Ar int 228482501Ssheldonh.It Cm maxpoll Ar int 228555895SsheldonhThese options specify the minimum and maximum polling interval 2286165445Scerifor reference clock messages, as a power of 2 in seconds 228782501SsheldonhFor 228882501Ssheldonhmost directly connected reference clocks, both 228982501Ssheldonh.Cm minpoll 229082501Ssheldonhand 229182501Ssheldonh.Cm maxpoll 229282501Ssheldonhdefault to 6 (64 s). 229355895SsheldonhFor modem reference clocks, 229482501Ssheldonh.Cm minpoll 229582501Ssheldonhdefaults to 10 (17.1 m) and 229682501Ssheldonh.Cm maxpoll 229782501Ssheldonhdefaults to 14 (4.5 h). 229855895SsheldonhThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 229955895Ssheldonh.El 230082501Ssheldonh.It Xo Ic fudge 230182501Ssheldonh.Sm off 230282501Ssheldonh.Li 127.127. Ar t . Ar u 230382501Ssheldonh.Sm on 230482501Ssheldonh.Op Cm time1 Ar sec 230582501Ssheldonh.Op Cm time2 Ar sec 230682501Ssheldonh.Op Cm stratum Ar int 230782501Ssheldonh.Op Cm refid Ar string 230882501Ssheldonh.Op Cm mode Ar int 230982501Ssheldonh.Op Cm flag1 Cm 0 \&| Cm 1 231082501Ssheldonh.Op Cm flag2 Cm 0 \&| Cm 1 231182501Ssheldonh.Op Cm flag3 Cm 0 \&| Cm 1 231282501Ssheldonh.Op Cm flag4 Cm 0 \&| Cm 1 231355895Ssheldonh.Xc 231482501SsheldonhThis command can be used to configure reference clocks in 231582501Ssheldonhspecial ways. 231655895SsheldonhIt must immediately follow the 231755895Ssheldonh.Ic server 231855895Ssheldonhcommand which configures the driver. 231982501SsheldonhNote that the same capability 232082501Ssheldonhis possible at run time using the 232155895Ssheldonh.Xr ntpdc 8 232255895Ssheldonhprogram. 232382501SsheldonhThe options are interpreted as 232482501Ssheldonhfollows: 232555895Ssheldonh.Bl -tag -width indent 232682501Ssheldonh.It Cm time1 Ar sec 232782501SsheldonhSpecifies a constant to be added to the time offset produced by 2328285612Sdelphijthe driver, a fixed\-point decimal number in seconds. 232982501SsheldonhThis is used 233082501Ssheldonhas a calibration constant to adjust the nominal time offset of a 233182501Ssheldonhparticular clock to agree with an external standard, such as a 233282501Ssheldonhprecision PPS signal. 233382501SsheldonhIt also provides a way to correct a 233482501Ssheldonhsystematic error or bias due to serial port or operating system 233582501Ssheldonhlatencies, different cable lengths or receiver internal delay. 233682501SsheldonhThe 233782501Ssheldonhspecified offset is in addition to the propagation delay provided 233882501Ssheldonhby other means, such as internal DIPswitches. 233982501SsheldonhWhere a calibration 234082501Ssheldonhfor an individual system and driver is available, an approximate 234182501Ssheldonhcorrection is noted in the driver documentation pages. 234282501SsheldonhNote: in order to facilitate calibration when more than one 234382501Ssheldonhradio clock or PPS signal is supported, a special calibration 234482501Ssheldonhfeature is available. 234582501SsheldonhIt takes the form of an argument to the 234682501Ssheldonh.Ic enable 234782501Ssheldonhcommand described in 234882501Ssheldonh.Sx Miscellaneous Options 234982501Ssheldonhpage and operates as described in the 2350158688Spav.Qq Reference Clock Drivers 2351158688Spavpage 2352158688Spav(available as part of the HTML documentation 2353158688Spavprovided in 2354158688Spav.Pa /usr/share/doc/ntp ) . 235582501Ssheldonh.It Cm time2 Ar secs 2356285612SdelphijSpecifies a fixed\-point decimal number in seconds, which is 2357285612Sdelphijinterpreted in a driver\-dependent way. 235882501SsheldonhSee the descriptions of 235982501Ssheldonhspecific drivers in the 2360158688Spav.Qq Reference Clock Drivers 2361158688Spavpage 2362158688Spav(available as part of the HTML documentation 2363158688Spavprovided in 2364158688Spav.Pa /usr/share/doc/ntp ) . 236582501Ssheldonh.It Cm stratum Ar int 236682501SsheldonhSpecifies the stratum number assigned to the driver, an integer 236782501Ssheldonhbetween 0 and 15. 236855895SsheldonhThis number overrides the default stratum number 236955895Ssheldonhordinarily assigned by the driver itself, usually zero. 237082501Ssheldonh.It Cm refid Ar string 237182501SsheldonhSpecifies an ASCII string of from one to four characters which 237282501Ssheldonhdefines the reference identifier used by the driver. 237382501SsheldonhThis string 237482501Ssheldonhoverrides the default identifier ordinarily assigned by the driver 237582501Ssheldonhitself. 237682501Ssheldonh.It Cm mode Ar int 237782501SsheldonhSpecifies a mode number which is interpreted in a 2378285612Sdelphijdevice\-specific fashion. 237982501SsheldonhFor instance, it selects a dialing 238082501Ssheldonhprotocol in the ACTS driver and a device subtype in the 238182501Ssheldonhparse 238282501Ssheldonhdrivers. 238382501Ssheldonh.It Cm flag1 Cm 0 \&| Cm 1 238482501Ssheldonh.It Cm flag2 Cm 0 \&| Cm 1 238582501Ssheldonh.It Cm flag3 Cm 0 \&| Cm 1 238682501Ssheldonh.It Cm flag4 Cm 0 \&| Cm 1 238755895SsheldonhThese four flags are used for customizing the clock driver. 238882501SsheldonhThe 238982501Ssheldonhinterpretation of these values, and whether they are used at all, 239055895Ssheldonhis a function of the particular clock driver. 239182501SsheldonhHowever, by 239282501Ssheldonhconvention 239382501Ssheldonh.Cm flag4 239482501Ssheldonhis used to enable recording monitoring 239582501Ssheldonhdata to the 239682501Ssheldonh.Cm clockstats 239782501Ssheldonhfile configured with the 239855895Ssheldonh.Ic filegen 239955895Ssheldonhcommand. 240055895SsheldonhFurther information on the 240155895Ssheldonh.Ic filegen 240282501Ssheldonhcommand can be found in 240382501Ssheldonh.Sx Monitoring Options . 240455895Ssheldonh.El 240555895Ssheldonh.El 240682501Ssheldonh.Sh Miscellaneous Options 240755895Ssheldonh.Bl -tag -width indent 240855895Ssheldonh.It Ic broadcastdelay Ar seconds 240955895SsheldonhThe broadcast and multicast modes require a special calibration 241055895Ssheldonhto determine the network delay between the local and remote 241155895Ssheldonhservers. 241282501SsheldonhOrdinarily, this is done automatically by the initial 241382501Ssheldonhprotocol exchanges between the client and server. 241482501SsheldonhIn some cases, 241582501Ssheldonhthe calibration procedure may fail due to network or server access 241682501Ssheldonhcontrols, for example. 241782501SsheldonhThis command specifies the default delay to 241882501Ssheldonhbe used under these circumstances. 241982501SsheldonhTypically (for Ethernet), a 242082501Ssheldonhnumber between 0.003 and 0.007 seconds is appropriate. 242182501SsheldonhThe default 242282501Ssheldonhwhen this command is not used is 0.004 seconds. 2423158688Spav.It Ic calldelay Ar delay 2424158688SpavThis option controls the delay in seconds between the first and second 2425158688Spavpackets sent in burst or iburst mode to allow additional time for a modem 2426158688Spavor ISDN call to complete. 242782501Ssheldonh.It Ic driftfile Ar driftfile 2428158688SpavThis command specifies the complete path and name of the file used to 2429162806Srurecord the frequency of the local clock oscillator. 2430162806SruThis is the same 2431158688Spavoperation as the 2432158688Spav.Fl f 2433165704Scericommand line option. 2434162806SruIf the file exists, it is read at 2435158688Spavstartup in order to set the initial frequency and then updated once per 2436162806Sruhour with the current frequency computed by the daemon. 2437162806SruIf the file name is 2438158688Spavspecified, but the file itself does not exist, the starts with an initial 2439158688Spavfrequency of zero and creates the file when writing it for the first time. 2440158688SpavIf this command is not given, the daemon will always start with an initial 2441158688Spavfrequency of zero. 244282501Ssheldonh.Pp 244382501SsheldonhThe file format consists of a single line containing a single 244482501Ssheldonhfloating point number, which records the frequency offset measured 2445285612Sdelphijin parts\-per\-million (PPM). 244682501SsheldonhThe file is updated by first writing 244782501Ssheldonhthe current drift value into a temporary file and then renaming 244882501Ssheldonhthis file to replace the old version. 244982501SsheldonhThis implies that 245082501Ssheldonh.Xr ntpd 8 245182501Ssheldonhmust have write permission for the directory the 2452107788Srudrift file is located in, and that file system links, symbolic or 245382501Ssheldonhotherwise, should be avoided. 2454289999Sglebius.It Ic dscp Ar value 2455289999SglebiusThis option specifies the Differentiated Services Control Point (DSCP) value, 2456298770Sdelphija 6\-bit code. 2457298770SdelphijThe default value is 46, signifying Expedited Forwarding. 245882501Ssheldonh.It Xo Ic enable 245982501Ssheldonh.Oo 246082501Ssheldonh.Cm auth | Cm bclient | 246182501Ssheldonh.Cm calibrate | Cm kernel | 2462294904Sdelphij.Cm mode7 | Cm monitor | 2463294904Sdelphij.Cm ntp | Cm stats | 2464301301Sdelphij.Cm peer_clear_digest_early | 2465294904Sdelphij.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early 246682501Ssheldonh.Oc 246755895Ssheldonh.Xc 246882501Ssheldonh.It Xo Ic disable 246982501Ssheldonh.Oo 247082501Ssheldonh.Cm auth | Cm bclient | 247182501Ssheldonh.Cm calibrate | Cm kernel | 2472294904Sdelphij.Cm mode7 | Cm monitor | 2473294904Sdelphij.Cm ntp | Cm stats | 2474301301Sdelphij.Cm peer_clear_digest_early | 2475294904Sdelphij.Cm unpeer_crypto_early | Cm unpeer_crypto_nak_early | Cm unpeer_digest_early 247682501Ssheldonh.Oc 247782501Ssheldonh.Xc 247882501SsheldonhProvides a way to enable or disable various server options. 247982501SsheldonhFlags not mentioned are unaffected. 248082501SsheldonhNote that all of these flags 248182501Ssheldonhcan be controlled remotely using the 248282501Ssheldonh.Xr ntpdc 8 248382501Ssheldonhutility program. 248482501Ssheldonh.Bl -tag -width indent 2485158688Spav.It Cm auth 2486158688SpavEnables the server to synchronize with unconfigured peers only if the 2487158688Spavpeer has been correctly authenticated using either public key or 2488162806Sruprivate key cryptography. 2489162806SruThe default for this flag is 2490158688Spav.Ic enable . 249182501Ssheldonh.It Cm bclient 2492158688SpavEnables the server to listen for a message from a broadcast or 2493158688Spavmulticast server, as in the 2494158688Spav.Ic multicastclient 2495158688Spavcommand with default 2496162806Sruaddress. 2497162806SruThe default for this flag is 2498131531Sru.Ic disable . 249982501Ssheldonh.It Cm calibrate 2500162806SruEnables the calibrate feature for reference clocks. 2501162806SruThe default for 2502158688Spavthis flag is 2503131531Sru.Ic disable . 250482501Ssheldonh.It Cm kernel 2505162806SruEnables the kernel time discipline, if available. 2506162806SruThe default for this 250782501Ssheldonhflag is 2508158688Spav.Ic enable 2509158688Spavif support is available, otherwise 2510158688Spav.Ic disable . 2511285612Sdelphij.It Cm mode7 2512285612SdelphijEnables processing of NTP mode 7 implementation\-specific requests 2513285612Sdelphijwhich are used by the deprecated 2514285612Sdelphij.Xr ntpdc 8 2515285612Sdelphijprogram. 2516285612SdelphijThe default for this flag is disable. 2517285612SdelphijThis flag is excluded from runtime configuration using 2518285612Sdelphij.Xr ntpq 8 . 2519285612SdelphijThe 2520285612Sdelphij.Xr ntpq 8 2521285612Sdelphijprogram provides the same capabilities as 2522285612Sdelphij.Xr ntpdc 8 2523285612Sdelphijusing standard mode 6 requests. 252482501Ssheldonh.It Cm monitor 252582501SsheldonhEnables the monitoring facility. 252682501SsheldonhSee the 252782501Ssheldonh.Xr ntpdc 8 252882501Ssheldonhprogram 252982501Ssheldonhand the 253082501Ssheldonh.Ic monlist 253182501Ssheldonhcommand or further information. 253255895SsheldonhThe 253382501Ssheldonhdefault for this flag is 2534131531Sru.Ic enable . 253582501Ssheldonh.It Cm ntp 2536162806SruEnables time and frequency discipline. 2537162806SruIn effect, this switch opens and 2538162806Srucloses the feedback loop, which is useful for testing. 2539162806SruThe default for 2540158688Spavthis flag is 2541158688Spav.Ic enable . 2542301301Sdelphij.It Cm peer_clear_digest_early 2543301301SdelphijBy default, if 2544301301Sdelphij.Xr ntpd 8 2545301301Sdelphijis using autokey and it 2546301301Sdelphijreceives a crypto\-NAK packet that 2547301301Sdelphijpasses the duplicate packet and origin timestamp checks 2548301301Sdelphijthe peer variables are immediately cleared. 2549301301SdelphijWhile this is generally a feature 2550301301Sdelphijas it allows for quick recovery if a server key has changed, 2551301301Sdelphija properly forged and appropriately delivered crypto\-NAK packet 2552301301Sdelphijcan be used in a DoS attack. 2553301301SdelphijIf you have active noticable problems with this type of DoS attack 2554301301Sdelphijthen you should consider 2555301301Sdelphijdisabling this option. 2556301301SdelphijYou can check your 2557301301Sdelphij.Cm peerstats 2558301301Sdelphijfile for evidence of any of these attacks. 2559301301SdelphijThe 2560301301Sdelphijdefault for this flag is 2561301301Sdelphij.Ic enable . 256282501Ssheldonh.It Cm stats 256382501SsheldonhEnables the statistics facility. 256482501SsheldonhSee the 2565158688Spav.Sx Monitoring Options 2566158688Spavsection for further information. 256782501SsheldonhThe default for this flag is 2568158688Spav.Ic disable . 2569294904Sdelphij.It Cm unpeer_crypto_early 2570294904SdelphijBy default, if 2571294904Sdelphij.Xr ntpd 8 2572294904Sdelphijreceives an autokey packet that fails TEST9, 2573294904Sdelphija crypto failure, 2574294904Sdelphijthe association is immediately cleared. 2575294904SdelphijThis is almost certainly a feature, 2576294904Sdelphijbut if, in spite of the current recommendation of not using autokey, 2577294904Sdelphijyou are 2578294904Sdelphij.B still 2579294904Sdelphijusing autokey 2580294904Sdelphij.B and 2581294904Sdelphijyou are seeing this sort of DoS attack 2582294904Sdelphijdisabling this flag will delay 2583294904Sdelphijtearing down the association until the reachability counter 2584294904Sdelphijbecomes zero. 2585294904SdelphijYou can check your 2586294904Sdelphij.Cm peerstats 2587294904Sdelphijfile for evidence of any of these attacks. 2588294904SdelphijThe 2589294904Sdelphijdefault for this flag is 2590294904Sdelphij.Ic enable . 2591294904Sdelphij.It Cm unpeer_crypto_nak_early 2592294904SdelphijBy default, if 2593294904Sdelphij.Xr ntpd 8 2594294904Sdelphijreceives a crypto\-NAK packet that 2595294904Sdelphijpasses the duplicate packet and origin timestamp checks 2596294904Sdelphijthe association is immediately cleared. 2597294904SdelphijWhile this is generally a feature 2598294904Sdelphijas it allows for quick recovery if a server key has changed, 2599294904Sdelphija properly forged and appropriately delivered crypto\-NAK packet 2600294904Sdelphijcan be used in a DoS attack. 2601294904SdelphijIf you have active noticable problems with this type of DoS attack 2602294904Sdelphijthen you should consider 2603294904Sdelphijdisabling this option. 2604294904SdelphijYou can check your 2605294904Sdelphij.Cm peerstats 2606294904Sdelphijfile for evidence of any of these attacks. 2607294904SdelphijThe 2608294904Sdelphijdefault for this flag is 2609294904Sdelphij.Ic enable . 2610294904Sdelphij.It Cm unpeer_digest_early 2611294904SdelphijBy default, if 2612294904Sdelphij.Xr ntpd 8 2613294904Sdelphijreceives what should be an authenticated packet 2614294904Sdelphijthat passes other packet sanity checks but 2615294904Sdelphijcontains an invalid digest 2616294904Sdelphijthe association is immediately cleared. 2617294904SdelphijWhile this is generally a feature 2618294904Sdelphijas it allows for quick recovery, 2619294904Sdelphijif this type of packet is carefully forged and sent 2620294904Sdelphijduring an appropriate window it can be used for a DoS attack. 2621294904SdelphijIf you have active noticable problems with this type of DoS attack 2622294904Sdelphijthen you should consider 2623294904Sdelphijdisabling this option. 2624294904SdelphijYou can check your 2625294904Sdelphij.Cm peerstats 2626294904Sdelphijfile for evidence of any of these attacks. 2627294904SdelphijThe 2628294904Sdelphijdefault for this flag is 2629294904Sdelphij.Ic enable . 263082501Ssheldonh.El 2631158688Spav.It Ic includefile Ar includefile 2632158688SpavThis command allows additional configuration commands 2633162806Sruto be included from a separate file. 2634162806SruInclude files may 2635158688Spavbe nested to a depth of five; upon reaching the end of any 2636158688Spavinclude file, command processing resumes in the previous 2637162806Sruconfiguration file. 2638162806SruThis option is useful for sites that run 2639158688Spav.Xr ntpd 8 2640158688Spavon multiple hosts, with (mostly) common options (e.g., a 2641158688Spavrestriction list). 2642289999Sglebius.It Ic leapsmearinterval Ar seconds 2643289999SglebiusThis EXPERIMENTAL option is only available if 2644289999Sglebius.Xr ntpd 8 2645289999Sglebiuswas built with the 2646289999Sglebius.Cm \-\-enable\-leap\-smear 2647289999Sglebiusoption to the 2648289999Sglebius.Cm configure 2649289999Sglebiusscript. 2650289999SglebiusIt specifies the interval over which a leap second correction will be applied. 2651289999SglebiusRecommended values for this option are between 2652289999Sglebius7200 (2 hours) and 86400 (24 hours). 2653289999Sglebius.Sy DO NOT USE THIS OPTION ON PUBLIC\-ACCESS SERVERS! 2654289999SglebiusSee http://bugs.ntp.org/2855 for more information. 265555895Ssheldonh.It Ic logconfig Ar configkeyword 265682501SsheldonhThis command controls the amount and type of output written to 265782501Ssheldonhthe system 265855895Ssheldonh.Xr syslog 3 265955895Ssheldonhfacility or the alternate 266055895Ssheldonh.Ic logfile 266155895Ssheldonhlog file. 266255895SsheldonhBy default, all output is turned on. 266355895SsheldonhAll 266455895Ssheldonh.Ar configkeyword 266582501Ssheldonhkeywords can be prefixed with 266682501Ssheldonh.Ql = , 266782501Ssheldonh.Ql + 266882501Ssheldonhand 2669285612Sdelphij.Ql \- , 267082501Ssheldonhwhere 267182501Ssheldonh.Ql = 267282501Ssheldonhsets the 267355895Ssheldonh.Xr syslog 3 267482501Ssheldonhpriority mask, 267582501Ssheldonh.Ql + 267682501Ssheldonhadds and 2677285612Sdelphij.Ql \- 267882501Ssheldonhremoves 267982501Ssheldonhmessages. 268082501Ssheldonh.Xr syslog 3 268182501Ssheldonhmessages can be controlled in four 268282501Ssheldonhclasses 268382501Ssheldonh.Po 268482501Ssheldonh.Cm clock , 268582501Ssheldonh.Cm peer , 268682501Ssheldonh.Cm sys 268782501Ssheldonhand 268882501Ssheldonh.Cm sync 268982501Ssheldonh.Pc . 269082501SsheldonhWithin these classes four types of messages can be 2691158688Spavcontrolled: informational messages 2692158688Spav.Po 2693158688Spav.Cm info 2694158688Spav.Pc , 2695158688Spavevent messages 2696158688Spav.Po 2697158688Spav.Cm events 2698158688Spav.Pc , 2699158688Spavstatistics messages 2700158688Spav.Po 270182501Ssheldonh.Cm statistics 2702158688Spav.Pc 2703158688Spavand 2704158688Spavstatus messages 2705158688Spav.Po 2706158688Spav.Cm status 2707158688Spav.Pc . 2708158688Spav.Pp 2709158688SpavConfiguration keywords are formed by concatenating the message class with 2710162806Sruthe event class. 2711162806SruThe 271282501Ssheldonh.Cm all 2713162806Sruprefix can be used instead of a message class. 2714162806SruA 2715158688Spavmessage class may also be followed by the 271682501Ssheldonh.Cm all 2717158688Spavkeyword to enable/disable all 2718298770Sdelphijmessages of the respective message class. 2719298770SdelphijThus, a minimal log configuration 2720158688Spavcould look like this: 272182501Ssheldonh.Bd -literal 2722126916Scpercivalogconfig =syncstatus +sysevents 272382501Ssheldonh.Ed 272455895Ssheldonh.Pp 272555895SsheldonhThis would just list the synchronizations state of 272655895Ssheldonh.Xr ntpd 8 272755895Ssheldonhand the major system events. 272882501SsheldonhFor a simple reference server, the 272982501Ssheldonhfollowing minimum message configuration could be useful: 273082501Ssheldonh.Bd -literal 2731126916Scpercivalogconfig =syncall +clockall 273282501Ssheldonh.Ed 273355895Ssheldonh.Pp 273482501SsheldonhThis configuration will list all clock information and 273582501Ssheldonhsynchronization information. 273682501SsheldonhAll other events and messages about 273782501Ssheldonhpeers, system events and so on is suppressed. 273882501Ssheldonh.It Ic logfile Ar logfile 273982501SsheldonhThis command specifies the location of an alternate log file to 274082501Ssheldonhbe used instead of the default system 2741107311Sru.Xr syslog 3 2742162806Srufacility. 2743298770SdelphijThis is the same operation as the 2744298770Sdelphij.Fl l 2745298770Sdelphijcommand line option. 274682501Ssheldonh.It Ic setvar Ar variable Op Cm default 274782501SsheldonhThis command adds an additional system variable. 274882501SsheldonhThese 274982501Ssheldonhvariables can be used to distribute additional information such as 275082501Ssheldonhthe access policy. 275182501SsheldonhIf the variable of the form 275282501Ssheldonh.Sm off 275382501Ssheldonh.Va name = Ar value 275482501Ssheldonh.Sm on 275582501Ssheldonhis followed by the 275682501Ssheldonh.Cm default 275782501Ssheldonhkeyword, the 275882501Ssheldonhvariable will be listed as part of the default system variables 275982501Ssheldonh.Po 276082501Ssheldonh.Xr ntpq 8 276182501Ssheldonh.Ic rv 276282501Ssheldonhcommand 276382501Ssheldonh.Pc ) . 276482501SsheldonhThese additional variables serve 276582501Ssheldonhinformational purposes only. 276682501SsheldonhThey are not related to the protocol 276782501Ssheldonhother that they can be listed. 276882501SsheldonhThe known protocol variables will 276982501Ssheldonhalways override any variables defined via the 277082501Ssheldonh.Ic setvar 277182501Ssheldonhmechanism. 277282501SsheldonhThere are three special variables that contain the names 277382501Ssheldonhof all variable of the same group. 277482501SsheldonhThe 277582501Ssheldonh.Va sys_var_list 277682501Ssheldonhholds 277782501Ssheldonhthe names of all system variables. 277882501SsheldonhThe 277982501Ssheldonh.Va peer_var_list 278082501Ssheldonhholds 278182501Ssheldonhthe names of all peer variables and the 278282501Ssheldonh.Va clock_var_list 278382501Ssheldonhholds the names of the reference clock variables. 278482501Ssheldonh.It Xo Ic tinker 278582501Ssheldonh.Oo 2786158688Spav.Cm allan Ar allan | 2787158688Spav.Cm dispersion Ar dispersion | 2788158688Spav.Cm freq Ar freq | 2789158688Spav.Cm huffpuff Ar huffpuff | 279082501Ssheldonh.Cm panic Ar panic | 2791289999Sglebius.Cm step Ar step | 2792289999Sglebius.Cm stepback Ar stepback | 2793289999Sglebius.Cm stepfwd Ar stepfwd | 2794158688Spav.Cm stepout Ar stepout 279582501Ssheldonh.Oc 279682501Ssheldonh.Xc 279782501SsheldonhThis command can be used to alter several system variables in 279882501Ssheldonhvery exceptional circumstances. 279982501SsheldonhIt should occur in the 280082501Ssheldonhconfiguration file before any other configuration options. 280182501SsheldonhThe 280282501Ssheldonhdefault values of these variables have been carefully optimized for 280382501Ssheldonha wide range of network speeds and reliability expectations. 280482501SsheldonhIn 280582501Ssheldonhgeneral, they interact in intricate ways that are hard to predict 280682501Ssheldonhand some combinations can result in some very nasty behavior. 280782501SsheldonhVery 280882501Ssheldonhrarely is it necessary to change the default values; but, some 2809141846Srufolks cannot resist twisting the knobs anyway and this command is 281082501Ssheldonhfor them. 281182501SsheldonhEmphasis added: twisters are on their own and can expect 281282501Ssheldonhno help from the support group. 281355895Ssheldonh.Pp 281482501SsheldonhThe variables operate as follows: 281582501Ssheldonh.Bl -tag -width indent 281682501Ssheldonh.It Cm allan Ar allan 281782501SsheldonhThe argument becomes the new value for the minimum Allan 281882501Ssheldonhintercept, which is a parameter of the PLL/FLL clock discipline 281982501Ssheldonhalgorithm. 2820158688SpavThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 282182501Ssheldonhlimit. 2822158688Spav.It Cm dispersion Ar dispersion 2823158688SpavThe argument becomes the new value for the dispersion increase rate, 2824158688Spavnormally .000015 s/s. 2825158688Spav.It Cm freq Ar freq 2826158688SpavThe argument becomes the initial value of the frequency offset in 2827285612Sdelphijparts\-per\-million. 2828162806SruThis overrides the value in the frequency file, if 2829158688Spavpresent, and avoids the initial training state if it is not. 283082501Ssheldonh.It Cm huffpuff Ar huffpuff 283182501SsheldonhThe argument becomes the new value for the experimental 2832285612Sdelphijhuff\-n'\-puff filter span, which determines the most recent interval 283382501Ssheldonhthe algorithm will search for a minimum delay. 283482501SsheldonhThe lower limit is 283582501Ssheldonh900 s (15 m), but a more reasonable value is 7200 (2 hours). 283682501SsheldonhThere 283782501Ssheldonhis no default, since the filter is not enabled unless this command 283882501Ssheldonhis given. 2839158688Spav.It Cm panic Ar panic 2840162806SruThe argument is the panic threshold, normally 1000 s. 2841162806SruIf set to zero, 2842158688Spavthe panic sanity check is disabled and a clock offset of any value will 2843158688Spavbe accepted. 2844158688Spav.It Cm step Ar step 2845162806SruThe argument is the step threshold, which by default is 0.128 s. 2846162806SruIt can 2847162806Srube set to any positive number in seconds. 2848162806SruIf set to zero, step 2849162806Sruadjustments will never occur. 2850162806SruNote: The kernel time discipline is 2851158688Spavdisabled if the step threshold is set to zero or greater than the 2852158688Spavdefault. 2853289999Sglebius.It Cm stepback Ar stepback 2854289999SglebiusThe argument is the step threshold for the backward direction, 2855289999Sglebiuswhich by default is 0.128 s. 2856289999SglebiusIt can 2857289999Sglebiusbe set to any positive number in seconds. 2858289999SglebiusIf both the forward and backward step thresholds are set to zero, step 2859289999Sglebiusadjustments will never occur. 2860289999SglebiusNote: The kernel time discipline is 2861289999Sglebiusdisabled if 2862289999Sglebiuseach direction of step threshold are either 2863289999Sglebiusset to zero or greater than .5 second. 2864289999Sglebius.It Cm stepfwd Ar stepfwd 2865289999SglebiusAs for stepback, but for the forward direction. 2866158688Spav.It Cm stepout Ar stepout 2867162806SruThe argument is the stepout timeout, which by default is 900 s. 2868162806SruIt can 2869162806Srube set to any positive number in seconds. 2870162806SruIf set to zero, the stepout 2871158688Spavpulses will not be suppressed. 287255895Ssheldonh.El 2873285612Sdelphij.It Xo Ic rlimit 2874285612Sdelphij.Oo 2875285612Sdelphij.Cm memlock Ar Nmegabytes | 2876285612Sdelphij.Cm stacksize Ar N4kPages 2877285612Sdelphij.Cm filenum Ar Nfiledescriptors 2878285612Sdelphij.Oc 2879285612Sdelphij.Xc 2880285612Sdelphij.Bl -tag -width indent 2881285612Sdelphij.It Cm memlock Ar Nmegabytes 2882289999SglebiusSpecify the number of megabytes of memory that should be 2883289999Sglebiusallocated and locked. 2884289999SglebiusProbably only available under Linux, this option may be useful 2885285612Sdelphijwhen dropping root (the 2886285612Sdelphij.Fl i 2887285612Sdelphijoption). 2888289999SglebiusThe default is 32 megabytes on non\-Linux machines, and \-1 under Linux. 2889289999Sglebius-1 means "do not lock the process into memory". 2890289999Sglebius0 means "lock whatever memory the process wants into memory". 2891285612Sdelphij.It Cm stacksize Ar N4kPages 2892285612SdelphijSpecifies the maximum size of the process stack on systems with the 2893285612Sdelphij.Fn mlockall 2894285612Sdelphijfunction. 2895285612SdelphijDefaults to 50 4k pages (200 4k pages in OpenBSD). 2896289999Sglebius.It Cm filenum Ar Nfiledescriptors 2897298770SdelphijSpecifies the maximum number of file descriptors ntpd may have open at once. 2898298770SdelphijDefaults to the system default. 2899285612Sdelphij.El 290082501Ssheldonh.It Xo Ic trap Ar host_address 290182501Ssheldonh.Op Cm port Ar port_number 290282501Ssheldonh.Op Cm interface Ar interface_address 290382501Ssheldonh.Xc 290482501SsheldonhThis command configures a trap receiver at the given host 290582501Ssheldonhaddress and port number for sending messages with the specified 290682501Ssheldonhlocal interface address. 290782501SsheldonhIf the port number is unspecified, a value 290882501Ssheldonhof 18447 is used. 290982501SsheldonhIf the interface address is not specified, the 291082501Ssheldonhmessage is sent with a source address of the local interface the 291182501Ssheldonhmessage is sent through. 291282501SsheldonhNote that on a multihomed host the 291382501Ssheldonhinterface used may vary from time to time with routing changes. 291482501Ssheldonh.Pp 291582501SsheldonhThe trap receiver will generally log event messages and other 291682501Ssheldonhinformation from the server in a log file. 291782501SsheldonhWhile such monitor 291882501Ssheldonhprograms may also request their own trap dynamically, configuring a 291982501Ssheldonhtrap receiver will ensure that no messages are lost when the server 292082501Ssheldonhis started. 2921158688Spav.It Cm hop Ar ... 2922162806SruThis command specifies a list of TTL values in increasing order, up to 8 2923162806Sruvalues can be specified. 2924162806SruIn manycast mode these values are used in turn in 2925285612Sdelphijan expanding\-ring search. 2926162806SruThe default is eight multiples of 32 starting at 2927158688Spav31. 292882501Ssheldonh.El 2929285612Sdelphij.Sh "OPTIONS" 2930285612Sdelphij.Bl -tag 2931285612Sdelphij.It Fl \-help 2932285612SdelphijDisplay usage information and exit. 2933285612Sdelphij.It Fl \-more\-help 2934285612SdelphijPass the extended usage information through a pager. 2935285612Sdelphij.It Fl \-version Op Brq Ar v|c|n 2936285612SdelphijOutput version of program and exit. The default mode is `v', a simple 2937285612Sdelphijversion. The `c' mode will print copyright information and `n' will 2938285612Sdelphijprint the full copyright notice. 2939285612Sdelphij.El 2940285612Sdelphij.Sh "OPTION PRESETS" 2941285612SdelphijAny option that is not marked as \fInot presettable\fP may be preset 2942285612Sdelphijby loading values from environment variables named: 2943285612Sdelphij.nf 2944285612Sdelphij \fBNTP_CONF_<option\-name>\fP or \fBNTP_CONF\fP 2945285612Sdelphij.fi 2946285612Sdelphij.ad 2947285612Sdelphij.Sh "ENVIRONMENT" 2948285612SdelphijSee \fBOPTION PRESETS\fP for configuration environment variables. 294955895Ssheldonh.Sh FILES 295055895Ssheldonh.Bl -tag -width /etc/ntp.drift -compact 295155895Ssheldonh.It Pa /etc/ntp.conf 295255895Ssheldonhthe default name of the configuration file 295382501Ssheldonh.It Pa ntp.keys 295482501Ssheldonhprivate MD5 keys 295582501Ssheldonh.It Pa ntpkey 295682501SsheldonhRSA private key 295782501Ssheldonh.It Pa ntpkey_ Ns Ar host 295882501SsheldonhRSA public key 295982501Ssheldonh.It Pa ntp_dh 2960285612SdelphijDiffie\-Hellman agreement parameters 296155895Ssheldonh.El 2962285612Sdelphij.Sh "EXIT STATUS" 2963285612SdelphijOne of the following exit values will be returned: 2964285612Sdelphij.Bl -tag 2965285612Sdelphij.It 0 " (EXIT_SUCCESS)" 2966285612SdelphijSuccessful program execution. 2967285612Sdelphij.It 1 " (EXIT_FAILURE)" 2968285612SdelphijThe operation failed or the command syntax was not valid. 2969285612Sdelphij.It 70 " (EX_SOFTWARE)" 2970285612Sdelphijlibopts had an internal operational error. Please report 2971285612Sdelphijit to autogen\-users@lists.sourceforge.net. Thank you. 2972285612Sdelphij.El 2973285612Sdelphij.Sh "SEE ALSO" 297455895Ssheldonh.Xr ntpd 8 , 297555895Ssheldonh.Xr ntpdc 8 , 297655895Ssheldonh.Xr ntpq 8 297755895Ssheldonh.Pp 297855895SsheldonhIn addition to the manual pages provided, 297955895Ssheldonhcomprehensive documentation is available on the world wide web 298055895Ssheldonhat 298155895Ssheldonh.Li http://www.ntp.org/ . 298255895SsheldonhA snapshot of this documentation is available in HTML format in 298355895Ssheldonh.Pa /usr/share/doc/ntp . 298455895Ssheldonh.Rs 298555895Ssheldonh.%A David L. Mills 2986285612Sdelphij.%T Network Time Protocol (Version 4) 2987285612Sdelphij.%O RFC5905 298855895Ssheldonh.Re 2989285612Sdelphij.Sh "AUTHORS" 2990285612SdelphijThe University of Delaware and Network Time Foundation 2991285612Sdelphij.Sh "COPYRIGHT" 2992294904SdelphijCopyright (C) 1992\-2016 The University of Delaware and Network Time Foundation all rights reserved. 2993285612SdelphijThis program is released under the terms of the NTP license, <http://ntp.org/license>. 299455895Ssheldonh.Sh BUGS 299582501SsheldonhThe syntax checking is not picky; some combinations of 299682501Ssheldonhridiculous and even hilarious options and modes may not be 299782501Ssheldonhdetected. 299882501Ssheldonh.Pp 299982501SsheldonhThe 300082501Ssheldonh.Pa ntpkey_ Ns Ar host 300182501Ssheldonhfiles are really digital 300282501Ssheldonhcertificates. 300382501SsheldonhThese should be obtained via secure directory 300482501Ssheldonhservices when they become universally available. 3005285612Sdelphij.Pp 3006285612SdelphijPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 3007285612Sdelphij.Sh NOTES 3008285612SdelphijThis document was derived from FreeBSD. 3009285612Sdelphij.Pp 3010285612SdelphijThis manual page was \fIAutoGen\fP\-erated from the \fBntp.conf\fP 3011285612Sdelphijoption definitions. 3012