invoke-ntp.conf.texi revision 294905
1290001Sglebius@node ntp.conf Notes 2290001Sglebius@section Notes about ntp.conf 3290001Sglebius@pindex ntp.conf 4290001Sglebius@cindex Network Time Protocol (NTP) daemon configuration file format 5290001Sglebius@ignore 6290001Sglebius# 7290001Sglebius# EDIT THIS FILE WITH CAUTION (invoke-ntp.conf.texi) 8290001Sglebius# 9294905Sdelphij# It has been AutoGen-ed January 20, 2016 at 04:17:59 AM by AutoGen 5.18.5 10290001Sglebius# From the definitions ntp.conf.def 11290001Sglebius# and the template file agtexi-file.tpl 12290001Sglebius@end ignore 13290001Sglebius 14290001Sglebius 15290001Sglebius 16290001SglebiusThe 17290001Sglebius@code{ntp.conf} 18290001Sglebiusconfiguration file is read at initial startup by the 19290001Sglebius@code{ntpd(1ntpdmdoc)} 20290001Sglebiusdaemon in order to specify the synchronization sources, 21290001Sglebiusmodes and other related information. 22290001SglebiusUsually, it is installed in the 23290001Sglebius@file{/etc} 24290001Sglebiusdirectory, 25290001Sglebiusbut could be installed elsewhere 26290001Sglebius(see the daemon's 27290001Sglebius@code{-c} 28290001Sglebiuscommand line option). 29290001Sglebius 30290001SglebiusThe file format is similar to other 31290001Sglebius@sc{unix} 32290001Sglebiusconfiguration files. 33290001SglebiusComments begin with a 34290001Sglebius@quoteleft{}#@quoteright{} 35290001Sglebiuscharacter and extend to the end of the line; 36290001Sglebiusblank lines are ignored. 37290001SglebiusConfiguration commands consist of an initial keyword 38290001Sglebiusfollowed by a list of arguments, 39290001Sglebiussome of which may be optional, separated by whitespace. 40290001SglebiusCommands may not be continued over multiple lines. 41290001SglebiusArguments may be host names, 42290001Sglebiushost addresses written in numeric, dotted-quad form, 43290001Sglebiusintegers, floating point numbers (when specifying times in seconds) 44290001Sglebiusand text strings. 45290001Sglebius 46290001SglebiusThe rest of this page describes the configuration and control options. 47290001SglebiusThe 48290001Sglebius"Notes on Configuring NTP and Setting up an NTP Subnet" 49290001Sglebiuspage 50290001Sglebius(available as part of the HTML documentation 51290001Sglebiusprovided in 52290001Sglebius@file{/usr/share/doc/ntp}) 53290001Sglebiuscontains an extended discussion of these options. 54290001SglebiusIn addition to the discussion of general 55290001Sglebius@ref{Configuration Options}, 56290001Sglebiusthere are sections describing the following supported functionality 57290001Sglebiusand the options used to control it: 58290001Sglebius@itemize @bullet 59290001Sglebius@item 60290001Sglebius@ref{Authentication Support} 61290001Sglebius@item 62290001Sglebius@ref{Monitoring Support} 63290001Sglebius@item 64290001Sglebius@ref{Access Control Support} 65290001Sglebius@item 66290001Sglebius@ref{Automatic NTP Configuration Options} 67290001Sglebius@item 68290001Sglebius@ref{Reference Clock Support} 69290001Sglebius@item 70290001Sglebius@ref{Miscellaneous Options} 71290001Sglebius@end itemize 72290001Sglebius 73290001SglebiusFollowing these is a section describing 74290001Sglebius@ref{Miscellaneous Options}. 75290001SglebiusWhile there is a rich set of options available, 76290001Sglebiusthe only required option is one or more 77290001Sglebius@code{pool}, 78290001Sglebius@code{server}, 79290001Sglebius@code{peer}, 80290001Sglebius@code{broadcast} 81290001Sglebiusor 82290001Sglebius@code{manycastclient} 83290001Sglebiuscommands. 84290001Sglebius@node Configuration Support 85290001Sglebius@subsection Configuration Support 86290001SglebiusFollowing is a description of the configuration commands in 87290001SglebiusNTPv4. 88290001SglebiusThese commands have the same basic functions as in NTPv3 and 89290001Sglebiusin some cases new functions and new arguments. 90290001SglebiusThere are two 91290001Sglebiusclasses of commands, configuration commands that configure a 92290001Sglebiuspersistent association with a remote server or peer or reference 93290001Sglebiusclock, and auxiliary commands that specify environmental variables 94290001Sglebiusthat control various related operations. 95290001Sglebius@subsubsection Configuration Commands 96290001SglebiusThe various modes are determined by the command keyword and the 97290001Sglebiustype of the required IP address. 98290001SglebiusAddresses are classed by type as 99290001Sglebius(s) a remote server or peer (IPv4 class A, B and C), (b) the 100290001Sglebiusbroadcast address of a local interface, (m) a multicast address (IPv4 101290001Sglebiusclass D), or (r) a reference clock address (127.127.x.x). 102290001SglebiusNote that 103290001Sglebiusonly those options applicable to each command are listed below. 104290001SglebiusUse 105290001Sglebiusof options not listed may not be caught as an error, but may result 106290001Sglebiusin some weird and even destructive behavior. 107290001Sglebius 108290001SglebiusIf the Basic Socket Interface Extensions for IPv6 (RFC-2553) 109290001Sglebiusis detected, support for the IPv6 address family is generated 110290001Sglebiusin addition to the default support of the IPv4 address family. 111290001SglebiusIn a few cases, including the reslist billboard generated 112290001Sglebiusby ntpdc, IPv6 addresses are automatically generated. 113290001SglebiusIPv6 addresses can be identified by the presence of colons 114290001Sglebius@quotedblleft{}:@quotedblright{} 115290001Sglebiusin the address field. 116290001SglebiusIPv6 addresses can be used almost everywhere where 117290001SglebiusIPv4 addresses can be used, 118290001Sglebiuswith the exception of reference clock addresses, 119290001Sglebiuswhich are always IPv4. 120290001Sglebius 121290001SglebiusNote that in contexts where a host name is expected, a 122290001Sglebius@code{-4} 123290001Sglebiusqualifier preceding 124290001Sglebiusthe host name forces DNS resolution to the IPv4 namespace, 125290001Sglebiuswhile a 126290001Sglebius@code{-6} 127290001Sglebiusqualifier forces DNS resolution to the IPv6 namespace. 128290001SglebiusSee IPv6 references for the 129290001Sglebiusequivalent classes for that address family. 130290001Sglebius@table @asis 131290001Sglebius@item @code{pool} @kbd{address} @code{[@code{burst}]} @code{[@code{iburst}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} 132290001Sglebius@item @code{server} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{burst}]} @code{[@code{iburst}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} 133290001Sglebius@item @code{peer} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} 134290001Sglebius@item @code{broadcast} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{ttl} @kbd{ttl}]} 135290001Sglebius@item @code{manycastclient} @kbd{address} @code{[@code{key} @kbd{key} @kbd{|} @code{autokey}]} @code{[@code{version} @kbd{version}]} @code{[@code{prefer}]} @code{[@code{minpoll} @kbd{minpoll}]} @code{[@code{maxpoll} @kbd{maxpoll}]} @code{[@code{ttl} @kbd{ttl}]} 136290001Sglebius@end table 137290001Sglebius 138290001SglebiusThese five commands specify the time server name or address to 139290001Sglebiusbe used and the mode in which to operate. 140290001SglebiusThe 141290001Sglebius@kbd{address} 142290001Sglebiuscan be 143290001Sglebiuseither a DNS name or an IP address in dotted-quad notation. 144290001SglebiusAdditional information on association behavior can be found in the 145290001Sglebius"Association Management" 146290001Sglebiuspage 147290001Sglebius(available as part of the HTML documentation 148290001Sglebiusprovided in 149290001Sglebius@file{/usr/share/doc/ntp}). 150290001Sglebius@table @asis 151290001Sglebius@item @code{pool} 152290001SglebiusFor type s addresses, this command mobilizes a persistent 153290001Sglebiusclient mode association with a number of remote servers. 154290001SglebiusIn this mode the local clock can synchronized to the 155290001Sglebiusremote server, but the remote server can never be synchronized to 156290001Sglebiusthe local clock. 157290001Sglebius@item @code{server} 158290001SglebiusFor type s and r addresses, this command mobilizes a persistent 159290001Sglebiusclient mode association with the specified remote server or local 160290001Sglebiusradio clock. 161290001SglebiusIn this mode the local clock can synchronized to the 162290001Sglebiusremote server, but the remote server can never be synchronized to 163290001Sglebiusthe local clock. 164290001SglebiusThis command should 165290001Sglebius@emph{not} 166290001Sglebiusbe used for type 167290001Sglebiusb or m addresses. 168290001Sglebius@item @code{peer} 169290001SglebiusFor type s addresses (only), this command mobilizes a 170290001Sglebiuspersistent symmetric-active mode association with the specified 171290001Sglebiusremote peer. 172290001SglebiusIn this mode the local clock can be synchronized to 173290001Sglebiusthe remote peer or the remote peer can be synchronized to the local 174290001Sglebiusclock. 175290001SglebiusThis is useful in a network of servers where, depending on 176290001Sglebiusvarious failure scenarios, either the local or remote peer may be 177290001Sglebiusthe better source of time. 178290001SglebiusThis command should NOT be used for type 179290001Sglebiusb, m or r addresses. 180290001Sglebius@item @code{broadcast} 181290001SglebiusFor type b and m addresses (only), this 182290001Sglebiuscommand mobilizes a persistent broadcast mode association. 183290001SglebiusMultiple 184290001Sglebiuscommands can be used to specify multiple local broadcast interfaces 185290001Sglebius(subnets) and/or multiple multicast groups. 186290001SglebiusNote that local 187290001Sglebiusbroadcast messages go only to the interface associated with the 188290001Sglebiussubnet specified, but multicast messages go to all interfaces. 189290001SglebiusIn broadcast mode the local server sends periodic broadcast 190290001Sglebiusmessages to a client population at the 191290001Sglebius@kbd{address} 192290001Sglebiusspecified, which is usually the broadcast address on (one of) the 193290001Sglebiuslocal network(s) or a multicast address assigned to NTP. 194290001SglebiusThe IANA 195290001Sglebiushas assigned the multicast group address IPv4 224.0.1.1 and 196290001SglebiusIPv6 ff05::101 (site local) exclusively to 197290001SglebiusNTP, but other nonconflicting addresses can be used to contain the 198290001Sglebiusmessages within administrative boundaries. 199290001SglebiusOrdinarily, this 200290001Sglebiusspecification applies only to the local server operating as a 201290001Sglebiussender; for operation as a broadcast client, see the 202290001Sglebius@code{broadcastclient} 203290001Sglebiusor 204290001Sglebius@code{multicastclient} 205290001Sglebiuscommands 206290001Sglebiusbelow. 207290001Sglebius@item @code{manycastclient} 208290001SglebiusFor type m addresses (only), this command mobilizes a 209290001Sglebiusmanycast client mode association for the multicast address 210290001Sglebiusspecified. 211290001SglebiusIn this case a specific address must be supplied which 212290001Sglebiusmatches the address used on the 213290001Sglebius@code{manycastserver} 214290001Sglebiuscommand for 215290001Sglebiusthe designated manycast servers. 216290001SglebiusThe NTP multicast address 217290001Sglebius224.0.1.1 assigned by the IANA should NOT be used, unless specific 218290001Sglebiusmeans are taken to avoid spraying large areas of the Internet with 219290001Sglebiusthese messages and causing a possibly massive implosion of replies 220290001Sglebiusat the sender. 221290001SglebiusThe 222290001Sglebius@code{manycastserver} 223290001Sglebiuscommand specifies that the local server 224290001Sglebiusis to operate in client mode with the remote servers that are 225290001Sglebiusdiscovered as the result of broadcast/multicast messages. 226290001SglebiusThe 227290001Sglebiusclient broadcasts a request message to the group address associated 228290001Sglebiuswith the specified 229290001Sglebius@kbd{address} 230290001Sglebiusand specifically enabled 231290001Sglebiusservers respond to these messages. 232290001SglebiusThe client selects the servers 233290001Sglebiusproviding the best time and continues as with the 234290001Sglebius@code{server} 235290001Sglebiuscommand. 236290001SglebiusThe remaining servers are discarded as if never 237290001Sglebiusheard. 238290001Sglebius@end table 239290001Sglebius 240290001SglebiusOptions: 241290001Sglebius@table @asis 242290001Sglebius@item @code{autokey} 243290001SglebiusAll packets sent to and received from the server or peer are to 244290001Sglebiusinclude authentication fields encrypted using the autokey scheme 245290001Sglebiusdescribed in 246290001Sglebius@ref{Authentication Options}. 247290001Sglebius@item @code{burst} 248290001Sglebiuswhen the server is reachable, send a burst of eight packets 249290001Sglebiusinstead of the usual one. 250290001SglebiusThe packet spacing is normally 2 s; 251290001Sglebiushowever, the spacing between the first and second packets 252290001Sglebiuscan be changed with the calldelay command to allow 253290001Sglebiusadditional time for a modem or ISDN call to complete. 254290001SglebiusThis is designed to improve timekeeping quality 255290001Sglebiuswith the 256290001Sglebius@code{server} 257290001Sglebiuscommand and s addresses. 258290001Sglebius@item @code{iburst} 259290001SglebiusWhen the server is unreachable, send a burst of eight packets 260290001Sglebiusinstead of the usual one. 261290001SglebiusThe packet spacing is normally 2 s; 262290001Sglebiushowever, the spacing between the first two packets can be 263290001Sglebiuschanged with the calldelay command to allow 264290001Sglebiusadditional time for a modem or ISDN call to complete. 265290001SglebiusThis is designed to speed the initial synchronization 266290001Sglebiusacquisition with the 267290001Sglebius@code{server} 268290001Sglebiuscommand and s addresses and when 269290001Sglebius@code{ntpd(1ntpdmdoc)} 270290001Sglebiusis started with the 271290001Sglebius@code{-q} 272290001Sglebiusoption. 273290001Sglebius@item @code{key} @kbd{key} 274290001SglebiusAll packets sent to and received from the server or peer are to 275290001Sglebiusinclude authentication fields encrypted using the specified 276290001Sglebius@kbd{key} 277290001Sglebiusidentifier with values from 1 to 65534, inclusive. 278290001SglebiusThe 279290001Sglebiusdefault is to include no encryption field. 280290001Sglebius@item @code{minpoll} @kbd{minpoll} 281290001Sglebius@item @code{maxpoll} @kbd{maxpoll} 282290001SglebiusThese options specify the minimum and maximum poll intervals 283290001Sglebiusfor NTP messages, as a power of 2 in seconds 284290001SglebiusThe maximum poll 285290001Sglebiusinterval defaults to 10 (1,024 s), but can be increased by the 286290001Sglebius@code{maxpoll} 287290001Sglebiusoption to an upper limit of 17 (36.4 h). 288290001SglebiusThe 289290001Sglebiusminimum poll interval defaults to 6 (64 s), but can be decreased by 290290001Sglebiusthe 291290001Sglebius@code{minpoll} 292290001Sglebiusoption to a lower limit of 4 (16 s). 293290001Sglebius@item @code{noselect} 294290001SglebiusMarks the server as unused, except for display purposes. 295290001SglebiusThe server is discarded by the selection algroithm. 296290001Sglebius@item @code{prefer} 297290001SglebiusMarks the server as preferred. 298290001SglebiusAll other things being equal, 299290001Sglebiusthis host will be chosen for synchronization among a set of 300290001Sglebiuscorrectly operating hosts. 301290001SglebiusSee the 302290001Sglebius"Mitigation Rules and the prefer Keyword" 303290001Sglebiuspage 304290001Sglebius(available as part of the HTML documentation 305290001Sglebiusprovided in 306290001Sglebius@file{/usr/share/doc/ntp}) 307290001Sglebiusfor further information. 308290001Sglebius@item @code{ttl} @kbd{ttl} 309290001SglebiusThis option is used only with broadcast server and manycast 310290001Sglebiusclient modes. 311290001SglebiusIt specifies the time-to-live 312290001Sglebius@kbd{ttl} 313290001Sglebiusto 314290001Sglebiususe on broadcast server and multicast server and the maximum 315290001Sglebius@kbd{ttl} 316290001Sglebiusfor the expanding ring search with manycast 317290001Sglebiusclient packets. 318290001SglebiusSelection of the proper value, which defaults to 319290001Sglebius127, is something of a black art and should be coordinated with the 320290001Sglebiusnetwork administrator. 321290001Sglebius@item @code{version} @kbd{version} 322290001SglebiusSpecifies the version number to be used for outgoing NTP 323290001Sglebiuspackets. 324290001SglebiusVersions 1-4 are the choices, with version 4 the 325290001Sglebiusdefault. 326290001Sglebius@end table 327290001Sglebius@subsubsection Auxiliary Commands 328290001Sglebius@table @asis 329290001Sglebius@item @code{broadcastclient} 330290001SglebiusThis command enables reception of broadcast server messages to 331290001Sglebiusany local interface (type b) address. 332290001SglebiusUpon receiving a message for 333290001Sglebiusthe first time, the broadcast client measures the nominal server 334290001Sglebiuspropagation delay using a brief client/server exchange with the 335290001Sglebiusserver, then enters the broadcast client mode, in which it 336290001Sglebiussynchronizes to succeeding broadcast messages. 337290001SglebiusNote that, in order 338290001Sglebiusto avoid accidental or malicious disruption in this mode, both the 339290001Sglebiusserver and client should operate using symmetric-key or public-key 340290001Sglebiusauthentication as described in 341290001Sglebius@ref{Authentication Options}. 342290001Sglebius@item @code{manycastserver} @kbd{address} @kbd{...} 343290001SglebiusThis command enables reception of manycast client messages to 344290001Sglebiusthe multicast group address(es) (type m) specified. 345290001SglebiusAt least one 346290001Sglebiusaddress is required, but the NTP multicast address 224.0.1.1 347290001Sglebiusassigned by the IANA should NOT be used, unless specific means are 348290001Sglebiustaken to limit the span of the reply and avoid a possibly massive 349290001Sglebiusimplosion at the original sender. 350290001SglebiusNote that, in order to avoid 351290001Sglebiusaccidental or malicious disruption in this mode, both the server 352290001Sglebiusand client should operate using symmetric-key or public-key 353290001Sglebiusauthentication as described in 354290001Sglebius@ref{Authentication Options}. 355290001Sglebius@item @code{multicastclient} @kbd{address} @kbd{...} 356290001SglebiusThis command enables reception of multicast server messages to 357290001Sglebiusthe multicast group address(es) (type m) specified. 358290001SglebiusUpon receiving 359290001Sglebiusa message for the first time, the multicast client measures the 360290001Sglebiusnominal server propagation delay using a brief client/server 361290001Sglebiusexchange with the server, then enters the broadcast client mode, in 362290001Sglebiuswhich it synchronizes to succeeding multicast messages. 363290001SglebiusNote that, 364290001Sglebiusin order to avoid accidental or malicious disruption in this mode, 365290001Sglebiusboth the server and client should operate using symmetric-key or 366290001Sglebiuspublic-key authentication as described in 367290001Sglebius@ref{Authentication Options}. 368290001Sglebius@item @code{mdnstries} @kbd{number} 369290001SglebiusIf we are participating in mDNS, 370290001Sglebiusafter we have synched for the first time 371290001Sglebiuswe attempt to register with the mDNS system. 372290001SglebiusIf that registration attempt fails, 373290001Sglebiuswe try again at one minute intervals for up to 374290001Sglebius@code{mdnstries} 375290001Sglebiustimes. 376290001SglebiusAfter all, 377290001Sglebius@code{ntpd} 378290001Sglebiusmay be starting before mDNS. 379290001SglebiusThe default value for 380290001Sglebius@code{mdnstries} 381290001Sglebiusis 5. 382290001Sglebius@end table 383290001Sglebius@node Authentication Support 384290001Sglebius@subsection Authentication Support 385290001SglebiusAuthentication support allows the NTP client to verify that the 386290001Sglebiusserver is in fact known and trusted and not an intruder intending 387290001Sglebiusaccidentally or on purpose to masquerade as that server. 388290001SglebiusThe NTPv3 389290001Sglebiusspecification RFC-1305 defines a scheme which provides 390290001Sglebiuscryptographic authentication of received NTP packets. 391290001SglebiusOriginally, 392290001Sglebiusthis was done using the Data Encryption Standard (DES) algorithm 393290001Sglebiusoperating in Cipher Block Chaining (CBC) mode, commonly called 394290001SglebiusDES-CBC. 395290001SglebiusSubsequently, this was replaced by the RSA Message Digest 396290001Sglebius5 (MD5) algorithm using a private key, commonly called keyed-MD5. 397290001SglebiusEither algorithm computes a message digest, or one-way hash, which 398290001Sglebiuscan be used to verify the server has the correct private key and 399290001Sglebiuskey identifier. 400290001Sglebius 401290001SglebiusNTPv4 retains the NTPv3 scheme, properly described as symmetric key 402290001Sglebiuscryptography and, in addition, provides a new Autokey scheme 403290001Sglebiusbased on public key cryptography. 404290001SglebiusPublic key cryptography is generally considered more secure 405290001Sglebiusthan symmetric key cryptography, since the security is based 406290001Sglebiuson a private value which is generated by each server and 407290001Sglebiusnever revealed. 408290001SglebiusWith Autokey all key distribution and 409290001Sglebiusmanagement functions involve only public values, which 410290001Sglebiusconsiderably simplifies key distribution and storage. 411290001SglebiusPublic key management is based on X.509 certificates, 412290001Sglebiuswhich can be provided by commercial services or 413290001Sglebiusproduced by utility programs in the OpenSSL software library 414290001Sglebiusor the NTPv4 distribution. 415290001Sglebius 416290001SglebiusWhile the algorithms for symmetric key cryptography are 417290001Sglebiusincluded in the NTPv4 distribution, public key cryptography 418290001Sglebiusrequires the OpenSSL software library to be installed 419290001Sglebiusbefore building the NTP distribution. 420290001SglebiusDirections for doing that 421290001Sglebiusare on the Building and Installing the Distribution page. 422290001Sglebius 423290001SglebiusAuthentication is configured separately for each association 424290001Sglebiususing the 425290001Sglebius@code{key} 426290001Sglebiusor 427290001Sglebius@code{autokey} 428290001Sglebiussubcommand on the 429290001Sglebius@code{peer}, 430290001Sglebius@code{server}, 431290001Sglebius@code{broadcast} 432290001Sglebiusand 433290001Sglebius@code{manycastclient} 434290001Sglebiusconfiguration commands as described in 435290001Sglebius@ref{Configuration Options} 436290001Sglebiuspage. 437290001SglebiusThe authentication 438290001Sglebiusoptions described below specify the locations of the key files, 439290001Sglebiusif other than default, which symmetric keys are trusted 440290001Sglebiusand the interval between various operations, if other than default. 441290001Sglebius 442290001SglebiusAuthentication is always enabled, 443290001Sglebiusalthough ineffective if not configured as 444290001Sglebiusdescribed below. 445290001SglebiusIf a NTP packet arrives 446290001Sglebiusincluding a message authentication 447290001Sglebiuscode (MAC), it is accepted only if it 448290001Sglebiuspasses all cryptographic checks. 449290001SglebiusThe 450290001Sglebiuschecks require correct key ID, key value 451290001Sglebiusand message digest. 452290001SglebiusIf the packet has 453290001Sglebiusbeen modified in any way or replayed 454290001Sglebiusby an intruder, it will fail one or more 455290001Sglebiusof these checks and be discarded. 456290001SglebiusFurthermore, the Autokey scheme requires a 457290001Sglebiuspreliminary protocol exchange to obtain 458290001Sglebiusthe server certificate, verify its 459290001Sglebiuscredentials and initialize the protocol 460290001Sglebius 461290001SglebiusThe 462290001Sglebius@code{auth} 463290001Sglebiusflag controls whether new associations or 464290001Sglebiusremote configuration commands require cryptographic authentication. 465290001SglebiusThis flag can be set or reset by the 466290001Sglebius@code{enable} 467290001Sglebiusand 468290001Sglebius@code{disable} 469290001Sglebiuscommands and also by remote 470290001Sglebiusconfiguration commands sent by a 471290001Sglebius@code{ntpdc(1ntpdcmdoc)} 472290001Sglebiusprogram running in 473290001Sglebiusanother machine. 474290001SglebiusIf this flag is enabled, which is the default 475290001Sglebiuscase, new broadcast client and symmetric passive associations and 476290001Sglebiusremote configuration commands must be cryptographically 477290001Sglebiusauthenticated using either symmetric key or public key cryptography. 478290001SglebiusIf this 479290001Sglebiusflag is disabled, these operations are effective 480290001Sglebiuseven if not cryptographic 481290001Sglebiusauthenticated. 482290001SglebiusIt should be understood 483290001Sglebiusthat operating with the 484290001Sglebius@code{auth} 485290001Sglebiusflag disabled invites a significant vulnerability 486290001Sglebiuswhere a rogue hacker can 487290001Sglebiusmasquerade as a falseticker and seriously 488290001Sglebiusdisrupt system timekeeping. 489290001SglebiusIt is 490290001Sglebiusimportant to note that this flag has no purpose 491290001Sglebiusother than to allow or disallow 492290001Sglebiusa new association in response to new broadcast 493290001Sglebiusand symmetric active messages 494290001Sglebiusand remote configuration commands and, in particular, 495290001Sglebiusthe flag has no effect on 496290001Sglebiusthe authentication process itself. 497290001Sglebius 498290001SglebiusAn attractive alternative where multicast support is available 499290001Sglebiusis manycast mode, in which clients periodically troll 500290001Sglebiusfor servers as described in the 501290001Sglebius@ref{Automatic NTP Configuration Options} 502290001Sglebiuspage. 503290001SglebiusEither symmetric key or public key 504290001Sglebiuscryptographic authentication can be used in this mode. 505290001SglebiusThe principle advantage 506290001Sglebiusof manycast mode is that potential servers need not be 507290001Sglebiusconfigured in advance, 508290001Sglebiussince the client finds them during regular operation, 509290001Sglebiusand the configuration 510290001Sglebiusfiles for all clients can be identical. 511290001Sglebius 512290001SglebiusThe security model and protocol schemes for 513290001Sglebiusboth symmetric key and public key 514290001Sglebiuscryptography are summarized below; 515290001Sglebiusfurther details are in the briefings, papers 516290001Sglebiusand reports at the NTP project page linked from 517290001Sglebius@code{http://www.ntp.org/}. 518290001Sglebius@subsubsection Symmetric-Key Cryptography 519290001SglebiusThe original RFC-1305 specification allows any one of possibly 520290001Sglebius65,534 keys, each distinguished by a 32-bit key identifier, to 521290001Sglebiusauthenticate an association. 522290001SglebiusThe servers and clients involved must 523290001Sglebiusagree on the key and key identifier to 524290001Sglebiusauthenticate NTP packets. 525290001SglebiusKeys and 526290001Sglebiusrelated information are specified in a key 527290001Sglebiusfile, usually called 528290001Sglebius@file{ntp.keys}, 529290001Sglebiuswhich must be distributed and stored using 530290001Sglebiussecure means beyond the scope of the NTP protocol itself. 531290001SglebiusBesides the keys used 532290001Sglebiusfor ordinary NTP associations, 533290001Sglebiusadditional keys can be used as passwords for the 534290001Sglebius@code{ntpq(1ntpqmdoc)} 535290001Sglebiusand 536290001Sglebius@code{ntpdc(1ntpdcmdoc)} 537290001Sglebiusutility programs. 538290001Sglebius 539290001SglebiusWhen 540290001Sglebius@code{ntpd(1ntpdmdoc)} 541290001Sglebiusis first started, it reads the key file specified in the 542290001Sglebius@code{keys} 543290001Sglebiusconfiguration command and installs the keys 544290001Sglebiusin the key cache. 545290001SglebiusHowever, 546290001Sglebiusindividual keys must be activated with the 547290001Sglebius@code{trusted} 548290001Sglebiuscommand before use. 549290001SglebiusThis 550290001Sglebiusallows, for instance, the installation of possibly 551290001Sglebiusseveral batches of keys and 552290001Sglebiusthen activating or deactivating each batch 553290001Sglebiusremotely using 554290001Sglebius@code{ntpdc(1ntpdcmdoc)}. 555290001SglebiusThis also provides a revocation capability that can be used 556290001Sglebiusif a key becomes compromised. 557290001SglebiusThe 558290001Sglebius@code{requestkey} 559290001Sglebiuscommand selects the key used as the password for the 560290001Sglebius@code{ntpdc(1ntpdcmdoc)} 561290001Sglebiusutility, while the 562290001Sglebius@code{controlkey} 563290001Sglebiuscommand selects the key used as the password for the 564290001Sglebius@code{ntpq(1ntpqmdoc)} 565290001Sglebiusutility. 566290001Sglebius@subsubsection Public Key Cryptography 567290001SglebiusNTPv4 supports the original NTPv3 symmetric key scheme 568290001Sglebiusdescribed in RFC-1305 and in addition the Autokey protocol, 569290001Sglebiuswhich is based on public key cryptography. 570290001SglebiusThe Autokey Version 2 protocol described on the Autokey Protocol 571290001Sglebiuspage verifies packet integrity using MD5 message digests 572290001Sglebiusand verifies the source with digital signatures and any of several 573290001Sglebiusdigest/signature schemes. 574290001SglebiusOptional identity schemes described on the Identity Schemes 575290001Sglebiuspage and based on cryptographic challenge/response algorithms 576290001Sglebiusare also available. 577290001SglebiusUsing all of these schemes provides strong security against 578290001Sglebiusreplay with or without modification, spoofing, masquerade 579290001Sglebiusand most forms of clogging attacks. 580290001Sglebius 581290001SglebiusThe Autokey protocol has several modes of operation 582290001Sglebiuscorresponding to the various NTP modes supported. 583290001SglebiusMost modes use a special cookie which can be 584290001Sglebiuscomputed independently by the client and server, 585290001Sglebiusbut encrypted in transmission. 586290001SglebiusAll modes use in addition a variant of the S-KEY scheme, 587290001Sglebiusin which a pseudo-random key list is generated and used 588290001Sglebiusin reverse order. 589290001SglebiusThese schemes are described along with an executive summary, 590290001Sglebiuscurrent status, briefing slides and reading list on the 591290001Sglebius@ref{Autonomous Authentication} 592290001Sglebiuspage. 593290001Sglebius 594290001SglebiusThe specific cryptographic environment used by Autokey servers 595290001Sglebiusand clients is determined by a set of files 596290001Sglebiusand soft links generated by the 597290001Sglebius@code{ntp-keygen(1ntpkeygenmdoc)} 598290001Sglebiusprogram. 599290001SglebiusThis includes a required host key file, 600290001Sglebiusrequired certificate file and optional sign key file, 601290001Sglebiusleapsecond file and identity scheme files. 602290001SglebiusThe 603290001Sglebiusdigest/signature scheme is specified in the X.509 certificate 604290001Sglebiusalong with the matching sign key. 605290001SglebiusThere are several schemes 606290001Sglebiusavailable in the OpenSSL software library, each identified 607290001Sglebiusby a specific string such as 608290001Sglebius@code{md5WithRSAEncryption}, 609290001Sglebiuswhich stands for the MD5 message digest with RSA 610290001Sglebiusencryption scheme. 611290001SglebiusThe current NTP distribution supports 612290001Sglebiusall the schemes in the OpenSSL library, including 613290001Sglebiusthose based on RSA and DSA digital signatures. 614290001Sglebius 615290001SglebiusNTP secure groups can be used to define cryptographic compartments 616290001Sglebiusand security hierarchies. 617290001SglebiusIt is important that every host 618290001Sglebiusin the group be able to construct a certificate trail to one 619290001Sglebiusor more trusted hosts in the same group. 620290001SglebiusEach group 621290001Sglebiushost runs the Autokey protocol to obtain the certificates 622290001Sglebiusfor all hosts along the trail to one or more trusted hosts. 623290001SglebiusThis requires the configuration file in all hosts to be 624290001Sglebiusengineered so that, even under anticipated failure conditions, 625290001Sglebiusthe NTP subnet will form such that every group host can find 626290001Sglebiusa trail to at least one trusted host. 627290001Sglebius@subsubsection Naming and Addressing 628290001SglebiusIt is important to note that Autokey does not use DNS to 629290001Sglebiusresolve addresses, since DNS can't be completely trusted 630290001Sglebiusuntil the name servers have synchronized clocks. 631290001SglebiusThe cryptographic name used by Autokey to bind the host identity 632290001Sglebiuscredentials and cryptographic values must be independent 633290001Sglebiusof interface, network and any other naming convention. 634290001SglebiusThe name appears in the host certificate in either or both 635290001Sglebiusthe subject and issuer fields, so protection against 636290001SglebiusDNS compromise is essential. 637290001Sglebius 638290001SglebiusBy convention, the name of an Autokey host is the name returned 639290001Sglebiusby the Unix 640290001Sglebius@code{gethostname(2)} 641290001Sglebiussystem call or equivalent in other systems. 642290001SglebiusBy the system design 643290001Sglebiusmodel, there are no provisions to allow alternate names or aliases. 644290001SglebiusHowever, this is not to say that DNS aliases, different names 645290001Sglebiusfor each interface, etc., are constrained in any way. 646290001Sglebius 647290001SglebiusIt is also important to note that Autokey verifies authenticity 648290001Sglebiususing the host name, network address and public keys, 649290001Sglebiusall of which are bound together by the protocol specifically 650290001Sglebiusto deflect masquerade attacks. 651290001SglebiusFor this reason Autokey 652290001Sglebiusincludes the source and destinatino IP addresses in message digest 653290001Sglebiuscomputations and so the same addresses must be available 654290001Sglebiusat both the server and client. 655290001SglebiusFor this reason operation 656290001Sglebiuswith network address translation schemes is not possible. 657290001SglebiusThis reflects the intended robust security model where government 658290001Sglebiusand corporate NTP servers are operated outside firewall perimeters. 659290001Sglebius@subsubsection Operation 660290001SglebiusA specific combination of authentication scheme (none, 661290001Sglebiussymmetric key, public key) and identity scheme is called 662290001Sglebiusa cryptotype, although not all combinations are compatible. 663290001SglebiusThere may be management configurations where the clients, 664290001Sglebiusservers and peers may not all support the same cryptotypes. 665290001SglebiusA secure NTPv4 subnet can be configured in many ways while 666290001Sglebiuskeeping in mind the principles explained above and 667290001Sglebiusin this section. 668290001SglebiusNote however that some cryptotype 669290001Sglebiuscombinations may successfully interoperate with each other, 670290001Sglebiusbut may not represent good security practice. 671290001Sglebius 672290001SglebiusThe cryptotype of an association is determined at the time 673290001Sglebiusof mobilization, either at configuration time or some time 674290001Sglebiuslater when a message of appropriate cryptotype arrives. 675290001SglebiusWhen mobilized by a 676290001Sglebius@code{server} 677290001Sglebiusor 678290001Sglebius@code{peer} 679290001Sglebiusconfiguration command and no 680290001Sglebius@code{key} 681290001Sglebiusor 682290001Sglebius@code{autokey} 683290001Sglebiussubcommands are present, the association is not 684290001Sglebiusauthenticated; if the 685290001Sglebius@code{key} 686290001Sglebiussubcommand is present, the association is authenticated 687290001Sglebiususing the symmetric key ID specified; if the 688290001Sglebius@code{autokey} 689290001Sglebiussubcommand is present, the association is authenticated 690290001Sglebiususing Autokey. 691290001Sglebius 692290001SglebiusWhen multiple identity schemes are supported in the Autokey 693290001Sglebiusprotocol, the first message exchange determines which one is used. 694290001SglebiusThe client request message contains bits corresponding 695290001Sglebiusto which schemes it has available. 696290001SglebiusThe server response message 697290001Sglebiuscontains bits corresponding to which schemes it has available. 698290001SglebiusBoth server and client match the received bits with their own 699290001Sglebiusand select a common scheme. 700290001Sglebius 701290001SglebiusFollowing the principle that time is a public value, 702290001Sglebiusa server responds to any client packet that matches 703290001Sglebiusits cryptotype capabilities. 704290001SglebiusThus, a server receiving 705290001Sglebiusan unauthenticated packet will respond with an unauthenticated 706290001Sglebiuspacket, while the same server receiving a packet of a cryptotype 707290001Sglebiusit supports will respond with packets of that cryptotype. 708290001SglebiusHowever, unconfigured broadcast or manycast client 709290001Sglebiusassociations or symmetric passive associations will not be 710290001Sglebiusmobilized unless the server supports a cryptotype compatible 711290001Sglebiuswith the first packet received. 712290001SglebiusBy default, unauthenticated associations will not be mobilized 713290001Sglebiusunless overridden in a decidedly dangerous way. 714290001Sglebius 715290001SglebiusSome examples may help to reduce confusion. 716290001SglebiusClient Alice has no specific cryptotype selected. 717290001SglebiusServer Bob has both a symmetric key file and minimal Autokey files. 718290001SglebiusAlice's unauthenticated messages arrive at Bob, who replies with 719290001Sglebiusunauthenticated messages. 720290001SglebiusCathy has a copy of Bob's symmetric 721290001Sglebiuskey file and has selected key ID 4 in messages to Bob. 722290001SglebiusBob verifies the message with his key ID 4. 723290001SglebiusIf it's the 724290001Sglebiussame key and the message is verified, Bob sends Cathy a reply 725290001Sglebiusauthenticated with that key. 726290001SglebiusIf verification fails, 727290001SglebiusBob sends Cathy a thing called a crypto-NAK, which tells her 728290001Sglebiussomething broke. 729290001SglebiusShe can see the evidence using the 730290001Sglebius@code{ntpq(1ntpqmdoc)} 731290001Sglebiusprogram. 732290001Sglebius 733290001SglebiusDenise has rolled her own host key and certificate. 734290001SglebiusShe also uses one of the identity schemes as Bob. 735290001SglebiusShe sends the first Autokey message to Bob and they 736290001Sglebiusboth dance the protocol authentication and identity steps. 737290001SglebiusIf all comes out okay, Denise and Bob continue as described above. 738290001Sglebius 739290001SglebiusIt should be clear from the above that Bob can support 740290001Sglebiusall the girls at the same time, as long as he has compatible 741290001Sglebiusauthentication and identity credentials. 742290001SglebiusNow, Bob can act just like the girls in his own choice of servers; 743290001Sglebiushe can run multiple configured associations with multiple different 744290001Sglebiusservers (or the same server, although that might not be useful). 745290001SglebiusBut, wise security policy might preclude some cryptotype 746290001Sglebiuscombinations; for instance, running an identity scheme 747290001Sglebiuswith one server and no authentication with another might not be wise. 748290001Sglebius@subsubsection Key Management 749290001SglebiusThe cryptographic values used by the Autokey protocol are 750290001Sglebiusincorporated as a set of files generated by the 751290001Sglebius@code{ntp-keygen(1ntpkeygenmdoc)} 752290001Sglebiusutility program, including symmetric key, host key and 753290001Sglebiuspublic certificate files, as well as sign key, identity parameters 754290001Sglebiusand leapseconds files. 755290001SglebiusAlternatively, host and sign keys and 756290001Sglebiuscertificate files can be generated by the OpenSSL utilities 757290001Sglebiusand certificates can be imported from public certificate 758290001Sglebiusauthorities. 759290001SglebiusNote that symmetric keys are necessary for the 760290001Sglebius@code{ntpq(1ntpqmdoc)} 761290001Sglebiusand 762290001Sglebius@code{ntpdc(1ntpdcmdoc)} 763290001Sglebiusutility programs. 764290001SglebiusThe remaining files are necessary only for the 765290001SglebiusAutokey protocol. 766290001Sglebius 767290001SglebiusCertificates imported from OpenSSL or public certificate 768290001Sglebiusauthorities have certian limitations. 769290001SglebiusThe certificate should be in ASN.1 syntax, X.509 Version 3 770290001Sglebiusformat and encoded in PEM, which is the same format 771290001Sglebiusused by OpenSSL. 772290001SglebiusThe overall length of the certificate encoded 773290001Sglebiusin ASN.1 must not exceed 1024 bytes. 774290001SglebiusThe subject distinguished 775290001Sglebiusname field (CN) is the fully qualified name of the host 776290001Sglebiuson which it is used; the remaining subject fields are ignored. 777290001SglebiusThe certificate extension fields must not contain either 778290001Sglebiusa subject key identifier or a issuer key identifier field; 779290001Sglebiushowever, an extended key usage field for a trusted host must 780290001Sglebiuscontain the value 781290001Sglebius@code{trustRoot};. 782290001SglebiusOther extension fields are ignored. 783290001Sglebius@subsubsection Authentication Commands 784290001Sglebius@table @asis 785290001Sglebius@item @code{autokey} @code{[@kbd{logsec}]} 786290001SglebiusSpecifies the interval between regenerations of the session key 787290001Sglebiuslist used with the Autokey protocol. 788290001SglebiusNote that the size of the key 789290001Sglebiuslist for each association depends on this interval and the current 790290001Sglebiuspoll interval. 791290001SglebiusThe default value is 12 (4096 s or about 1.1 hours). 792290001SglebiusFor poll intervals above the specified interval, a session key list 793290001Sglebiuswith a single entry will be regenerated for every message 794290001Sglebiussent. 795290001Sglebius@item @code{controlkey} @kbd{key} 796290001SglebiusSpecifies the key identifier to use with the 797290001Sglebius@code{ntpq(1ntpqmdoc)} 798290001Sglebiusutility, which uses the standard 799290001Sglebiusprotocol defined in RFC-1305. 800290001SglebiusThe 801290001Sglebius@kbd{key} 802290001Sglebiusargument is 803290001Sglebiusthe key identifier for a trusted key, where the value can be in the 804290001Sglebiusrange 1 to 65,534, inclusive. 805290001Sglebius@item @code{crypto} @code{[@code{cert} @kbd{file}]} @code{[@code{leap} @kbd{file}]} @code{[@code{randfile} @kbd{file}]} @code{[@code{host} @kbd{file}]} @code{[@code{sign} @kbd{file}]} @code{[@code{gq} @kbd{file}]} @code{[@code{gqpar} @kbd{file}]} @code{[@code{iffpar} @kbd{file}]} @code{[@code{mvpar} @kbd{file}]} @code{[@code{pw} @kbd{password}]} 806290001SglebiusThis command requires the OpenSSL library. 807290001SglebiusIt activates public key 808290001Sglebiuscryptography, selects the message digest and signature 809290001Sglebiusencryption scheme and loads the required private and public 810290001Sglebiusvalues described above. 811290001SglebiusIf one or more files are left unspecified, 812290001Sglebiusthe default names are used as described above. 813290001SglebiusUnless the complete path and name of the file are specified, the 814290001Sglebiuslocation of a file is relative to the keys directory specified 815290001Sglebiusin the 816290001Sglebius@code{keysdir} 817290001Sglebiuscommand or default 818290001Sglebius@file{/usr/local/etc}. 819290001SglebiusFollowing are the subcommands: 820290001Sglebius@table @asis 821290001Sglebius@item @code{cert} @kbd{file} 822290001SglebiusSpecifies the location of the required host public certificate file. 823290001SglebiusThis overrides the link 824290001Sglebius@file{ntpkey_cert_}@kbd{hostname} 825290001Sglebiusin the keys directory. 826290001Sglebius@item @code{gqpar} @kbd{file} 827290001SglebiusSpecifies the location of the optional GQ parameters file. 828290001SglebiusThis 829290001Sglebiusoverrides the link 830290001Sglebius@file{ntpkey_gq_}@kbd{hostname} 831290001Sglebiusin the keys directory. 832290001Sglebius@item @code{host} @kbd{file} 833290001SglebiusSpecifies the location of the required host key file. 834290001SglebiusThis overrides 835290001Sglebiusthe link 836290001Sglebius@file{ntpkey_key_}@kbd{hostname} 837290001Sglebiusin the keys directory. 838290001Sglebius@item @code{iffpar} @kbd{file} 839290001SglebiusSpecifies the location of the optional IFF parameters file.This 840290001Sglebiusoverrides the link 841290001Sglebius@file{ntpkey_iff_}@kbd{hostname} 842290001Sglebiusin the keys directory. 843290001Sglebius@item @code{leap} @kbd{file} 844290001SglebiusSpecifies the location of the optional leapsecond file. 845290001SglebiusThis overrides the link 846290001Sglebius@file{ntpkey_leap} 847290001Sglebiusin the keys directory. 848290001Sglebius@item @code{mvpar} @kbd{file} 849290001SglebiusSpecifies the location of the optional MV parameters file. 850290001SglebiusThis 851290001Sglebiusoverrides the link 852290001Sglebius@file{ntpkey_mv_}@kbd{hostname} 853290001Sglebiusin the keys directory. 854290001Sglebius@item @code{pw} @kbd{password} 855290001SglebiusSpecifies the password to decrypt files containing private keys and 856290001Sglebiusidentity parameters. 857290001SglebiusThis is required only if these files have been 858290001Sglebiusencrypted. 859290001Sglebius@item @code{randfile} @kbd{file} 860290001SglebiusSpecifies the location of the random seed file used by the OpenSSL 861290001Sglebiuslibrary. 862290001SglebiusThe defaults are described in the main text above. 863290001Sglebius@item @code{sign} @kbd{file} 864290001SglebiusSpecifies the location of the optional sign key file. 865290001SglebiusThis overrides 866290001Sglebiusthe link 867290001Sglebius@file{ntpkey_sign_}@kbd{hostname} 868290001Sglebiusin the keys directory. 869290001SglebiusIf this file is 870290001Sglebiusnot found, the host key is also the sign key. 871290001Sglebius@end table 872290001Sglebius@item @code{keys} @kbd{keyfile} 873290001SglebiusSpecifies the complete path and location of the MD5 key file 874290001Sglebiuscontaining the keys and key identifiers used by 875290001Sglebius@code{ntpd(1ntpdmdoc)}, 876290001Sglebius@code{ntpq(1ntpqmdoc)} 877290001Sglebiusand 878290001Sglebius@code{ntpdc(1ntpdcmdoc)} 879290001Sglebiuswhen operating with symmetric key cryptography. 880290001SglebiusThis is the same operation as the 881290001Sglebius@code{-k} 882290001Sglebiuscommand line option. 883290001Sglebius@item @code{keysdir} @kbd{path} 884290001SglebiusThis command specifies the default directory path for 885290001Sglebiuscryptographic keys, parameters and certificates. 886290001SglebiusThe default is 887290001Sglebius@file{/usr/local/etc/}. 888290001Sglebius@item @code{requestkey} @kbd{key} 889290001SglebiusSpecifies the key identifier to use with the 890290001Sglebius@code{ntpdc(1ntpdcmdoc)} 891290001Sglebiusutility program, which uses a 892290001Sglebiusproprietary protocol specific to this implementation of 893290001Sglebius@code{ntpd(1ntpdmdoc)}. 894290001SglebiusThe 895290001Sglebius@kbd{key} 896290001Sglebiusargument is a key identifier 897290001Sglebiusfor the trusted key, where the value can be in the range 1 to 898290001Sglebius65,534, inclusive. 899290001Sglebius@item @code{revoke} @kbd{logsec} 900290001SglebiusSpecifies the interval between re-randomization of certain 901290001Sglebiuscryptographic values used by the Autokey scheme, as a power of 2 in 902290001Sglebiusseconds. 903290001SglebiusThese values need to be updated frequently in order to 904290001Sglebiusdeflect brute-force attacks on the algorithms of the scheme; 905290001Sglebiushowever, updating some values is a relatively expensive operation. 906290001SglebiusThe default interval is 16 (65,536 s or about 18 hours). 907290001SglebiusFor poll 908290001Sglebiusintervals above the specified interval, the values will be updated 909290001Sglebiusfor every message sent. 910290001Sglebius@item @code{trustedkey} @kbd{key} @kbd{...} 911290001SglebiusSpecifies the key identifiers which are trusted for the 912290001Sglebiuspurposes of authenticating peers with symmetric key cryptography, 913290001Sglebiusas well as keys used by the 914290001Sglebius@code{ntpq(1ntpqmdoc)} 915290001Sglebiusand 916290001Sglebius@code{ntpdc(1ntpdcmdoc)} 917290001Sglebiusprograms. 918290001SglebiusThe authentication procedures require that both the local 919290001Sglebiusand remote servers share the same key and key identifier for this 920290001Sglebiuspurpose, although different keys can be used with different 921290001Sglebiusservers. 922290001SglebiusThe 923290001Sglebius@kbd{key} 924290001Sglebiusarguments are 32-bit unsigned 925290001Sglebiusintegers with values from 1 to 65,534. 926290001Sglebius@end table 927290001Sglebius@subsubsection Error Codes 928290001SglebiusThe following error codes are reported via the NTP control 929290001Sglebiusand monitoring protocol trap mechanism. 930290001Sglebius@table @asis 931290001Sglebius@item 101 932290001Sglebius(bad field format or length) 933290001SglebiusThe packet has invalid version, length or format. 934290001Sglebius@item 102 935290001Sglebius(bad timestamp) 936290001SglebiusThe packet timestamp is the same or older than the most recent received. 937290001SglebiusThis could be due to a replay or a server clock time step. 938290001Sglebius@item 103 939290001Sglebius(bad filestamp) 940290001SglebiusThe packet filestamp is the same or older than the most recent received. 941290001SglebiusThis could be due to a replay or a key file generation error. 942290001Sglebius@item 104 943290001Sglebius(bad or missing public key) 944290001SglebiusThe public key is missing, has incorrect format or is an unsupported type. 945290001Sglebius@item 105 946290001Sglebius(unsupported digest type) 947290001SglebiusThe server requires an unsupported digest/signature scheme. 948290001Sglebius@item 106 949290001Sglebius(mismatched digest types) 950290001SglebiusNot used. 951290001Sglebius@item 107 952290001Sglebius(bad signature length) 953290001SglebiusThe signature length does not match the current public key. 954290001Sglebius@item 108 955290001Sglebius(signature not verified) 956290001SglebiusThe message fails the signature check. 957290001SglebiusIt could be bogus or signed by a 958290001Sglebiusdifferent private key. 959290001Sglebius@item 109 960290001Sglebius(certificate not verified) 961290001SglebiusThe certificate is invalid or signed with the wrong key. 962290001Sglebius@item 110 963290001Sglebius(certificate not verified) 964290001SglebiusThe certificate is not yet valid or has expired or the signature could not 965290001Sglebiusbe verified. 966290001Sglebius@item 111 967290001Sglebius(bad or missing cookie) 968290001SglebiusThe cookie is missing, corrupted or bogus. 969290001Sglebius@item 112 970290001Sglebius(bad or missing leapseconds table) 971290001SglebiusThe leapseconds table is missing, corrupted or bogus. 972290001Sglebius@item 113 973290001Sglebius(bad or missing certificate) 974290001SglebiusThe certificate is missing, corrupted or bogus. 975290001Sglebius@item 114 976290001Sglebius(bad or missing identity) 977290001SglebiusThe identity key is missing, corrupt or bogus. 978290001Sglebius@end table 979290001Sglebius@node Monitoring Support 980290001Sglebius@subsection Monitoring Support 981290001Sglebius@code{ntpd(1ntpdmdoc)} 982290001Sglebiusincludes a comprehensive monitoring facility suitable 983290001Sglebiusfor continuous, long term recording of server and client 984290001Sglebiustimekeeping performance. 985290001SglebiusSee the 986290001Sglebius@code{statistics} 987290001Sglebiuscommand below 988290001Sglebiusfor a listing and example of each type of statistics currently 989290001Sglebiussupported. 990290001SglebiusStatistic files are managed using file generation sets 991290001Sglebiusand scripts in the 992290001Sglebius@file{./scripts} 993290001Sglebiusdirectory of this distribution. 994290001SglebiusUsing 995290001Sglebiusthese facilities and 996290001Sglebius@sc{unix} 997290001Sglebius@code{cron(8)} 998290001Sglebiusjobs, the data can be 999290001Sglebiusautomatically summarized and archived for retrospective analysis. 1000290001Sglebius@subsubsection Monitoring Commands 1001290001Sglebius@table @asis 1002290001Sglebius@item @code{statistics} @kbd{name} @kbd{...} 1003290001SglebiusEnables writing of statistics records. 1004290001SglebiusCurrently, eight kinds of 1005290001Sglebius@kbd{name} 1006290001Sglebiusstatistics are supported. 1007290001Sglebius@table @asis 1008290001Sglebius@item @code{clockstats} 1009290001SglebiusEnables recording of clock driver statistics information. 1010290001SglebiusEach update 1011290001Sglebiusreceived from a clock driver appends a line of the following form to 1012290001Sglebiusthe file generation set named 1013290001Sglebius@code{clockstats}: 1014290001Sglebius@verbatim 1015290001Sglebius49213 525.624 127.127.4.1 93 226 00:08:29.606 D 1016290001Sglebius@end verbatim 1017290001Sglebius 1018290001SglebiusThe first two fields show the date (Modified Julian Day) and time 1019290001Sglebius(seconds and fraction past UTC midnight). 1020290001SglebiusThe next field shows the 1021290001Sglebiusclock address in dotted-quad notation. 1022290001SglebiusThe final field shows the last 1023290001Sglebiustimecode received from the clock in decoded ASCII format, where 1024290001Sglebiusmeaningful. 1025290001SglebiusIn some clock drivers a good deal of additional information 1026290001Sglebiuscan be gathered and displayed as well. 1027290001SglebiusSee information specific to each 1028290001Sglebiusclock for further details. 1029290001Sglebius@item @code{cryptostats} 1030290001SglebiusThis option requires the OpenSSL cryptographic software library. 1031290001SglebiusIt 1032290001Sglebiusenables recording of cryptographic public key protocol information. 1033290001SglebiusEach message received by the protocol module appends a line of the 1034290001Sglebiusfollowing form to the file generation set named 1035290001Sglebius@code{cryptostats}: 1036290001Sglebius@verbatim 1037290001Sglebius49213 525.624 127.127.4.1 message 1038290001Sglebius@end verbatim 1039290001Sglebius 1040290001SglebiusThe first two fields show the date (Modified Julian Day) and time 1041290001Sglebius(seconds and fraction past UTC midnight). 1042290001SglebiusThe next field shows the peer 1043290001Sglebiusaddress in dotted-quad notation, The final message field includes the 1044290001Sglebiusmessage type and certain ancillary information. 1045290001SglebiusSee the 1046290001Sglebius@ref{Authentication Options} 1047290001Sglebiussection for further information. 1048290001Sglebius@item @code{loopstats} 1049290001SglebiusEnables recording of loop filter statistics information. 1050290001SglebiusEach 1051290001Sglebiusupdate of the local clock outputs a line of the following form to 1052290001Sglebiusthe file generation set named 1053290001Sglebius@code{loopstats}: 1054290001Sglebius@verbatim 1055290001Sglebius50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 1056290001Sglebius@end verbatim 1057290001Sglebius 1058290001SglebiusThe first two fields show the date (Modified Julian Day) and 1059290001Sglebiustime (seconds and fraction past UTC midnight). 1060290001SglebiusThe next five fields 1061290001Sglebiusshow time offset (seconds), frequency offset (parts per million - 1062290001SglebiusPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 1063290001Sglebiusdiscipline time constant. 1064290001Sglebius@item @code{peerstats} 1065290001SglebiusEnables recording of peer statistics information. 1066290001SglebiusThis includes 1067290001Sglebiusstatistics records of all peers of a NTP server and of special 1068290001Sglebiussignals, where present and configured. 1069290001SglebiusEach valid update appends a 1070290001Sglebiusline of the following form to the current element of a file 1071290001Sglebiusgeneration set named 1072290001Sglebius@code{peerstats}: 1073290001Sglebius@verbatim 1074290001Sglebius48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 1075290001Sglebius@end verbatim 1076290001Sglebius 1077290001SglebiusThe first two fields show the date (Modified Julian Day) and 1078290001Sglebiustime (seconds and fraction past UTC midnight). 1079290001SglebiusThe next two fields 1080290001Sglebiusshow the peer address in dotted-quad notation and status, 1081290001Sglebiusrespectively. 1082290001SglebiusThe status field is encoded in hex in the format 1083290001Sglebiusdescribed in Appendix A of the NTP specification RFC 1305. 1084290001SglebiusThe final four fields show the offset, 1085290001Sglebiusdelay, dispersion and RMS jitter, all in seconds. 1086290001Sglebius@item @code{rawstats} 1087290001SglebiusEnables recording of raw-timestamp statistics information. 1088290001SglebiusThis 1089290001Sglebiusincludes statistics records of all peers of a NTP server and of 1090290001Sglebiusspecial signals, where present and configured. 1091290001SglebiusEach NTP message 1092290001Sglebiusreceived from a peer or clock driver appends a line of the 1093290001Sglebiusfollowing form to the file generation set named 1094290001Sglebius@code{rawstats}: 1095290001Sglebius@verbatim 1096290001Sglebius50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 1097290001Sglebius@end verbatim 1098290001Sglebius 1099290001SglebiusThe first two fields show the date (Modified Julian Day) and 1100290001Sglebiustime (seconds and fraction past UTC midnight). 1101290001SglebiusThe next two fields 1102290001Sglebiusshow the remote peer or clock address followed by the local address 1103290001Sglebiusin dotted-quad notation. 1104290001SglebiusThe final four fields show the originate, 1105290001Sglebiusreceive, transmit and final NTP timestamps in order. 1106290001SglebiusThe timestamp 1107290001Sglebiusvalues are as received and before processing by the various data 1108290001Sglebiussmoothing and mitigation algorithms. 1109290001Sglebius@item @code{sysstats} 1110290001SglebiusEnables recording of ntpd statistics counters on a periodic basis. 1111290001SglebiusEach 1112290001Sglebiushour a line of the following form is appended to the file generation 1113290001Sglebiusset named 1114290001Sglebius@code{sysstats}: 1115290001Sglebius@verbatim 1116290001Sglebius50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1117290001Sglebius@end verbatim 1118290001Sglebius 1119290001SglebiusThe first two fields show the date (Modified Julian Day) and time 1120290001Sglebius(seconds and fraction past UTC midnight). 1121290001SglebiusThe remaining ten fields show 1122290001Sglebiusthe statistics counter values accumulated since the last generated 1123290001Sglebiusline. 1124290001Sglebius@table @asis 1125290001Sglebius@item Time since restart @code{36000} 1126290001SglebiusTime in hours since the system was last rebooted. 1127290001Sglebius@item Packets received @code{81965} 1128290001SglebiusTotal number of packets received. 1129290001Sglebius@item Packets processed @code{0} 1130290001SglebiusNumber of packets received in response to previous packets sent 1131290001Sglebius@item Current version @code{9546} 1132290001SglebiusNumber of packets matching the current NTP version. 1133290001Sglebius@item Previous version @code{56} 1134290001SglebiusNumber of packets matching the previous NTP version. 1135290001Sglebius@item Bad version @code{71793} 1136290001SglebiusNumber of packets matching neither NTP version. 1137290001Sglebius@item Access denied @code{512} 1138290001SglebiusNumber of packets denied access for any reason. 1139290001Sglebius@item Bad length or format @code{540} 1140290001SglebiusNumber of packets with invalid length, format or port number. 1141290001Sglebius@item Bad authentication @code{10} 1142290001SglebiusNumber of packets not verified as authentic. 1143290001Sglebius@item Rate exceeded @code{147} 1144290001SglebiusNumber of packets discarded due to rate limitation. 1145290001Sglebius@end table 1146290001Sglebius@item @code{statsdir} @kbd{directory_path} 1147290001SglebiusIndicates the full path of a directory where statistics files 1148290001Sglebiusshould be created (see below). 1149290001SglebiusThis keyword allows 1150290001Sglebiusthe (otherwise constant) 1151290001Sglebius@code{filegen} 1152290001Sglebiusfilename prefix to be modified for file generation sets, which 1153290001Sglebiusis useful for handling statistics logs. 1154290001Sglebius@item @code{filegen} @kbd{name} @code{[@code{file} @kbd{filename}]} @code{[@code{type} @kbd{typename}]} @code{[@code{link} | @code{nolink}]} @code{[@code{enable} | @code{disable}]} 1155290001SglebiusConfigures setting of generation file set name. 1156290001SglebiusGeneration 1157290001Sglebiusfile sets provide a means for handling files that are 1158290001Sglebiuscontinuously growing during the lifetime of a server. 1159290001SglebiusServer statistics are a typical example for such files. 1160290001SglebiusGeneration file sets provide access to a set of files used 1161290001Sglebiusto store the actual data. 1162290001SglebiusAt any time at most one element 1163290001Sglebiusof the set is being written to. 1164290001SglebiusThe type given specifies 1165290001Sglebiuswhen and how data will be directed to a new element of the set. 1166290001SglebiusThis way, information stored in elements of a file set 1167290001Sglebiusthat are currently unused are available for administrational 1168290001Sglebiusoperations without the risk of disturbing the operation of ntpd. 1169290001Sglebius(Most important: they can be removed to free space for new data 1170290001Sglebiusproduced.) 1171290001Sglebius 1172290001SglebiusNote that this command can be sent from the 1173290001Sglebius@code{ntpdc(1ntpdcmdoc)} 1174290001Sglebiusprogram running at a remote location. 1175290001Sglebius@table @asis 1176290001Sglebius@item @code{name} 1177290001SglebiusThis is the type of the statistics records, as shown in the 1178290001Sglebius@code{statistics} 1179290001Sglebiuscommand. 1180290001Sglebius@item @code{file} @kbd{filename} 1181290001SglebiusThis is the file name for the statistics records. 1182290001SglebiusFilenames of set 1183290001Sglebiusmembers are built from three concatenated elements 1184290001Sglebius@code{prefix}, 1185290001Sglebius@code{filename} 1186290001Sglebiusand 1187290001Sglebius@code{suffix}: 1188290001Sglebius@table @asis 1189290001Sglebius@item @code{prefix} 1190290001SglebiusThis is a constant filename path. 1191290001SglebiusIt is not subject to 1192290001Sglebiusmodifications via the 1193290001Sglebius@kbd{filegen} 1194290001Sglebiusoption. 1195290001SglebiusIt is defined by the 1196290001Sglebiusserver, usually specified as a compile-time constant. 1197290001SglebiusIt may, 1198290001Sglebiushowever, be configurable for individual file generation sets 1199290001Sglebiusvia other commands. 1200290001SglebiusFor example, the prefix used with 1201290001Sglebius@kbd{loopstats} 1202290001Sglebiusand 1203290001Sglebius@kbd{peerstats} 1204290001Sglebiusgeneration can be configured using the 1205290001Sglebius@kbd{statsdir} 1206290001Sglebiusoption explained above. 1207290001Sglebius@item @code{filename} 1208290001SglebiusThis string is directly concatenated to the prefix mentioned 1209290001Sglebiusabove (no intervening 1210290001Sglebius@quoteleft{}/@quoteright{}). 1211290001SglebiusThis can be modified using 1212290001Sglebiusthe file argument to the 1213290001Sglebius@kbd{filegen} 1214290001Sglebiusstatement. 1215290001SglebiusNo 1216290001Sglebius@file{..} 1217290001Sglebiuselements are 1218290001Sglebiusallowed in this component to prevent filenames referring to 1219290001Sglebiusparts outside the filesystem hierarchy denoted by 1220290001Sglebius@kbd{prefix}. 1221290001Sglebius@item @code{suffix} 1222290001SglebiusThis part is reflects individual elements of a file set. 1223290001SglebiusIt is 1224290001Sglebiusgenerated according to the type of a file set. 1225290001Sglebius@end table 1226290001Sglebius@item @code{type} @kbd{typename} 1227290001SglebiusA file generation set is characterized by its type. 1228290001SglebiusThe following 1229290001Sglebiustypes are supported: 1230290001Sglebius@table @asis 1231290001Sglebius@item @code{none} 1232290001SglebiusThe file set is actually a single plain file. 1233290001Sglebius@item @code{pid} 1234290001SglebiusOne element of file set is used per incarnation of a ntpd 1235290001Sglebiusserver. 1236290001SglebiusThis type does not perform any changes to file set 1237290001Sglebiusmembers during runtime, however it provides an easy way of 1238290001Sglebiusseparating files belonging to different 1239290001Sglebius@code{ntpd(1ntpdmdoc)} 1240290001Sglebiusserver incarnations. 1241290001SglebiusThe set member filename is built by appending a 1242290001Sglebius@quoteleft{}.@quoteright{} 1243290001Sglebiusto concatenated 1244290001Sglebius@kbd{prefix} 1245290001Sglebiusand 1246290001Sglebius@kbd{filename} 1247290001Sglebiusstrings, and 1248290001Sglebiusappending the decimal representation of the process ID of the 1249290001Sglebius@code{ntpd(1ntpdmdoc)} 1250290001Sglebiusserver process. 1251290001Sglebius@item @code{day} 1252290001SglebiusOne file generation set element is created per day. 1253290001SglebiusA day is 1254290001Sglebiusdefined as the period between 00:00 and 24:00 UTC. 1255290001SglebiusThe file set 1256290001Sglebiusmember suffix consists of a 1257290001Sglebius@quoteleft{}.@quoteright{} 1258290001Sglebiusand a day specification in 1259290001Sglebiusthe form 1260290001Sglebius@code{YYYYMMdd}. 1261290001Sglebius@code{YYYY} 1262290001Sglebiusis a 4-digit year number (e.g., 1992). 1263290001Sglebius@code{MM} 1264290001Sglebiusis a two digit month number. 1265290001Sglebius@code{dd} 1266290001Sglebiusis a two digit day number. 1267290001SglebiusThus, all information written at 10 December 1992 would end up 1268290001Sglebiusin a file named 1269290001Sglebius@kbd{prefix} 1270290001Sglebius@kbd{filename}.19921210. 1271290001Sglebius@item @code{week} 1272290001SglebiusAny file set member contains data related to a certain week of 1273290001Sglebiusa year. 1274290001SglebiusThe term week is defined by computing day-of-year 1275290001Sglebiusmodulo 7. 1276290001SglebiusElements of such a file generation set are 1277290001Sglebiusdistinguished by appending the following suffix to the file set 1278290001Sglebiusfilename base: A dot, a 4-digit year number, the letter 1279290001Sglebius@code{W}, 1280290001Sglebiusand a 2-digit week number. 1281290001SglebiusFor example, information from January, 1282290001Sglebius10th 1992 would end up in a file with suffix 1283290001Sglebius.No . Ns Ar 1992W1 . 1284290001Sglebius@item @code{month} 1285290001SglebiusOne generation file set element is generated per month. 1286290001SglebiusThe 1287290001Sglebiusfile name suffix consists of a dot, a 4-digit year number, and 1288290001Sglebiusa 2-digit month. 1289290001Sglebius@item @code{year} 1290290001SglebiusOne generation file element is generated per year. 1291290001SglebiusThe filename 1292290001Sglebiussuffix consists of a dot and a 4 digit year number. 1293290001Sglebius@item @code{age} 1294290001SglebiusThis type of file generation sets changes to a new element of 1295290001Sglebiusthe file set every 24 hours of server operation. 1296290001SglebiusThe filename 1297290001Sglebiussuffix consists of a dot, the letter 1298290001Sglebius@code{a}, 1299290001Sglebiusand an 8-digit number. 1300290001SglebiusThis number is taken to be the number of seconds the server is 1301290001Sglebiusrunning at the start of the corresponding 24-hour period. 1302290001SglebiusInformation is only written to a file generation by specifying 1303290001Sglebius@code{enable}; 1304290001Sglebiusoutput is prevented by specifying 1305290001Sglebius@code{disable}. 1306290001Sglebius@end table 1307290001Sglebius@item @code{link} | @code{nolink} 1308290001SglebiusIt is convenient to be able to access the current element of a file 1309290001Sglebiusgeneration set by a fixed name. 1310290001SglebiusThis feature is enabled by 1311290001Sglebiusspecifying 1312290001Sglebius@code{link} 1313290001Sglebiusand disabled using 1314290001Sglebius@code{nolink}. 1315290001SglebiusIf link is specified, a 1316290001Sglebiushard link from the current file set element to a file without 1317290001Sglebiussuffix is created. 1318290001SglebiusWhen there is already a file with this name and 1319290001Sglebiusthe number of links of this file is one, it is renamed appending a 1320290001Sglebiusdot, the letter 1321290001Sglebius@code{C}, 1322290001Sglebiusand the pid of the ntpd server process. 1323290001SglebiusWhen the 1324290001Sglebiusnumber of links is greater than one, the file is unlinked. 1325290001SglebiusThis 1326290001Sglebiusallows the current file to be accessed by a constant name. 1327290001Sglebius@item @code{enable} @code{|} @code{disable} 1328290001SglebiusEnables or disables the recording function. 1329290001Sglebius@end table 1330290001Sglebius@end table 1331290001Sglebius@end table 1332290001Sglebius@node Access Control Support 1333290001Sglebius@subsection Access Control Support 1334290001SglebiusThe 1335290001Sglebius@code{ntpd(1ntpdmdoc)} 1336290001Sglebiusdaemon implements a general purpose address/mask based restriction 1337290001Sglebiuslist. 1338290001SglebiusThe list contains address/match entries sorted first 1339290001Sglebiusby increasing address values and and then by increasing mask values. 1340290001SglebiusA match occurs when the bitwise AND of the mask and the packet 1341290001Sglebiussource address is equal to the bitwise AND of the mask and 1342290001Sglebiusaddress in the list. 1343290001SglebiusThe list is searched in order with the 1344290001Sglebiuslast match found defining the restriction flags associated 1345290001Sglebiuswith the entry. 1346290001SglebiusAdditional information and examples can be found in the 1347290001Sglebius"Notes on Configuring NTP and Setting up a NTP Subnet" 1348290001Sglebiuspage 1349290001Sglebius(available as part of the HTML documentation 1350290001Sglebiusprovided in 1351290001Sglebius@file{/usr/share/doc/ntp}). 1352290001Sglebius 1353290001SglebiusThe restriction facility was implemented in conformance 1354290001Sglebiuswith the access policies for the original NSFnet backbone 1355290001Sglebiustime servers. 1356290001SglebiusLater the facility was expanded to deflect 1357290001Sglebiuscryptographic and clogging attacks. 1358290001SglebiusWhile this facility may 1359290001Sglebiusbe useful for keeping unwanted or broken or malicious clients 1360290001Sglebiusfrom congesting innocent servers, it should not be considered 1361290001Sglebiusan alternative to the NTP authentication facilities. 1362290001SglebiusSource address based restrictions are easily circumvented 1363290001Sglebiusby a determined cracker. 1364290001Sglebius 1365290001SglebiusClients can be denied service because they are explicitly 1366290001Sglebiusincluded in the restrict list created by the restrict command 1367290001Sglebiusor implicitly as the result of cryptographic or rate limit 1368290001Sglebiusviolations. 1369290001SglebiusCryptographic violations include certificate 1370290001Sglebiusor identity verification failure; rate limit violations generally 1371290001Sglebiusresult from defective NTP implementations that send packets 1372290001Sglebiusat abusive rates. 1373290001SglebiusSome violations cause denied service 1374290001Sglebiusonly for the offending packet, others cause denied service 1375290001Sglebiusfor a timed period and others cause the denied service for 1376290001Sglebiusan indefinate period. 1377290001SglebiusWhen a client or network is denied access 1378290001Sglebiusfor an indefinate period, the only way at present to remove 1379290001Sglebiusthe restrictions is by restarting the server. 1380290001Sglebius@subsubsection The Kiss-of-Death Packet 1381290001SglebiusOrdinarily, packets denied service are simply dropped with no 1382290001Sglebiusfurther action except incrementing statistics counters. 1383290001SglebiusSometimes a 1384290001Sglebiusmore proactive response is needed, such as a server message that 1385290001Sglebiusexplicitly requests the client to stop sending and leave a message 1386290001Sglebiusfor the system operator. 1387290001SglebiusA special packet format has been created 1388290001Sglebiusfor this purpose called the "kiss-of-death" (KoD) packet. 1389290001SglebiusKoD packets have the leap bits set unsynchronized and stratum set 1390290001Sglebiusto zero and the reference identifier field set to a four-byte 1391290001SglebiusASCII code. 1392290001SglebiusIf the 1393290001Sglebius@code{noserve} 1394290001Sglebiusor 1395290001Sglebius@code{notrust} 1396290001Sglebiusflag of the matching restrict list entry is set, 1397290001Sglebiusthe code is "DENY"; if the 1398290001Sglebius@code{limited} 1399290001Sglebiusflag is set and the rate limit 1400290001Sglebiusis exceeded, the code is "RATE". 1401290001SglebiusFinally, if a cryptographic violation occurs, the code is "CRYP". 1402290001Sglebius 1403290001SglebiusA client receiving a KoD performs a set of sanity checks to 1404290001Sglebiusminimize security exposure, then updates the stratum and 1405290001Sglebiusreference identifier peer variables, sets the access 1406290001Sglebiusdenied (TEST4) bit in the peer flash variable and sends 1407290001Sglebiusa message to the log. 1408290001SglebiusAs long as the TEST4 bit is set, 1409290001Sglebiusthe client will send no further packets to the server. 1410290001SglebiusThe only way at present to recover from this condition is 1411290001Sglebiusto restart the protocol at both the client and server. 1412290001SglebiusThis 1413290001Sglebiushappens automatically at the client when the association times out. 1414290001SglebiusIt will happen at the server only if the server operator cooperates. 1415290001Sglebius@subsubsection Access Control Commands 1416290001Sglebius@table @asis 1417290001Sglebius@item @code{discard} @code{[@code{average} @kbd{avg}]} @code{[@code{minimum} @kbd{min}]} @code{[@code{monitor} @kbd{prob}]} 1418290001SglebiusSet the parameters of the 1419290001Sglebius@code{limited} 1420290001Sglebiusfacility which protects the server from 1421290001Sglebiusclient abuse. 1422290001SglebiusThe 1423290001Sglebius@code{average} 1424290001Sglebiussubcommand specifies the minimum average packet 1425290001Sglebiusspacing, while the 1426290001Sglebius@code{minimum} 1427290001Sglebiussubcommand specifies the minimum packet spacing. 1428290001SglebiusPackets that violate these minima are discarded 1429290001Sglebiusand a kiss-o'-death packet returned if enabled. 1430290001SglebiusThe default 1431290001Sglebiusminimum average and minimum are 5 and 2, respectively. 1432290001SglebiusThe monitor subcommand specifies the probability of discard 1433290001Sglebiusfor packets that overflow the rate-control window. 1434290001Sglebius@item @code{restrict} @code{address} @code{[@code{mask} @kbd{mask}]} @code{[@kbd{flag} @kbd{...}]} 1435290001SglebiusThe 1436290001Sglebius@kbd{address} 1437290001Sglebiusargument expressed in 1438290001Sglebiusdotted-quad form is the address of a host or network. 1439290001SglebiusAlternatively, the 1440290001Sglebius@kbd{address} 1441290001Sglebiusargument can be a valid host DNS name. 1442290001SglebiusThe 1443290001Sglebius@kbd{mask} 1444290001Sglebiusargument expressed in dotted-quad form defaults to 1445290001Sglebius@code{255.255.255.255}, 1446290001Sglebiusmeaning that the 1447290001Sglebius@kbd{address} 1448290001Sglebiusis treated as the address of an individual host. 1449290001SglebiusA default entry (address 1450290001Sglebius@code{0.0.0.0}, 1451290001Sglebiusmask 1452290001Sglebius@code{0.0.0.0}) 1453290001Sglebiusis always included and is always the first entry in the list. 1454290001SglebiusNote that text string 1455290001Sglebius@code{default}, 1456290001Sglebiuswith no mask option, may 1457290001Sglebiusbe used to indicate the default entry. 1458290001SglebiusIn the current implementation, 1459290001Sglebius@code{flag} 1460290001Sglebiusalways 1461290001Sglebiusrestricts access, i.e., an entry with no flags indicates that free 1462290001Sglebiusaccess to the server is to be given. 1463290001SglebiusThe flags are not orthogonal, 1464290001Sglebiusin that more restrictive flags will often make less restrictive 1465290001Sglebiusones redundant. 1466290001SglebiusThe flags can generally be classed into two 1467290001Sglebiuscategories, those which restrict time service and those which 1468290001Sglebiusrestrict informational queries and attempts to do run-time 1469290001Sglebiusreconfiguration of the server. 1470290001SglebiusOne or more of the following flags 1471290001Sglebiusmay be specified: 1472290001Sglebius@table @asis 1473290001Sglebius@item @code{ignore} 1474290001SglebiusDeny packets of all kinds, including 1475290001Sglebius@code{ntpq(1ntpqmdoc)} 1476290001Sglebiusand 1477290001Sglebius@code{ntpdc(1ntpdcmdoc)} 1478290001Sglebiusqueries. 1479290001Sglebius@item @code{kod} 1480290001SglebiusIf this flag is set when an access violation occurs, a kiss-o'-death 1481290001Sglebius(KoD) packet is sent. 1482290001SglebiusKoD packets are rate limited to no more than one 1483290001Sglebiusper second. 1484290001SglebiusIf another KoD packet occurs within one second after the 1485290001Sglebiuslast one, the packet is dropped. 1486290001Sglebius@item @code{limited} 1487290001SglebiusDeny service if the packet spacing violates the lower limits specified 1488290001Sglebiusin the discard command. 1489290001SglebiusA history of clients is kept using the 1490290001Sglebiusmonitoring capability of 1491290001Sglebius@code{ntpd(1ntpdmdoc)}. 1492290001SglebiusThus, monitoring is always active as 1493290001Sglebiuslong as there is a restriction entry with the 1494290001Sglebius@code{limited} 1495290001Sglebiusflag. 1496290001Sglebius@item @code{lowpriotrap} 1497290001SglebiusDeclare traps set by matching hosts to be low priority. 1498290001SglebiusThe 1499290001Sglebiusnumber of traps a server can maintain is limited (the current limit 1500290001Sglebiusis 3). 1501290001SglebiusTraps are usually assigned on a first come, first served 1502290001Sglebiusbasis, with later trap requestors being denied service. 1503290001SglebiusThis flag 1504290001Sglebiusmodifies the assignment algorithm by allowing low priority traps to 1505290001Sglebiusbe overridden by later requests for normal priority traps. 1506290001Sglebius@item @code{nomodify} 1507290001SglebiusDeny 1508290001Sglebius@code{ntpq(1ntpqmdoc)} 1509290001Sglebiusand 1510290001Sglebius@code{ntpdc(1ntpdcmdoc)} 1511290001Sglebiusqueries which attempt to modify the state of the 1512290001Sglebiusserver (i.e., run time reconfiguration). 1513290001SglebiusQueries which return 1514290001Sglebiusinformation are permitted. 1515290001Sglebius@item @code{noquery} 1516290001SglebiusDeny 1517290001Sglebius@code{ntpq(1ntpqmdoc)} 1518290001Sglebiusand 1519290001Sglebius@code{ntpdc(1ntpdcmdoc)} 1520290001Sglebiusqueries. 1521290001SglebiusTime service is not affected. 1522290001Sglebius@item @code{nopeer} 1523290001SglebiusDeny packets which would result in mobilizing a new association. 1524290001SglebiusThis 1525290001Sglebiusincludes broadcast and symmetric active packets when a configured 1526290001Sglebiusassociation does not exist. 1527290001SglebiusIt also includes 1528290001Sglebius@code{pool} 1529290001Sglebiusassociations, so if you want to use servers from a 1530290001Sglebius@code{pool} 1531290001Sglebiusdirective and also want to use 1532290001Sglebius@code{nopeer} 1533290001Sglebiusby default, you'll want a 1534290001Sglebius@code{restrict source ...} @code{line} @code{as} @code{well} @code{that} @code{does} 1535290001Sglebius@item not 1536290001Sglebiusinclude the 1537290001Sglebius@code{nopeer} 1538290001Sglebiusdirective. 1539290001Sglebius@item @code{noserve} 1540290001SglebiusDeny all packets except 1541290001Sglebius@code{ntpq(1ntpqmdoc)} 1542290001Sglebiusand 1543290001Sglebius@code{ntpdc(1ntpdcmdoc)} 1544290001Sglebiusqueries. 1545290001Sglebius@item @code{notrap} 1546290001SglebiusDecline to provide mode 6 control message trap service to matching 1547290001Sglebiushosts. 1548290001SglebiusThe trap service is a subsystem of the ntpdq control message 1549290001Sglebiusprotocol which is intended for use by remote event logging programs. 1550290001Sglebius@item @code{notrust} 1551290001SglebiusDeny service unless the packet is cryptographically authenticated. 1552290001Sglebius@item @code{ntpport} 1553290001SglebiusThis is actually a match algorithm modifier, rather than a 1554290001Sglebiusrestriction flag. 1555290001SglebiusIts presence causes the restriction entry to be 1556290001Sglebiusmatched only if the source port in the packet is the standard NTP 1557290001SglebiusUDP port (123). 1558290001SglebiusBoth 1559290001Sglebius@code{ntpport} 1560290001Sglebiusand 1561290001Sglebius@code{non-ntpport} 1562290001Sglebiusmay 1563290001Sglebiusbe specified. 1564290001SglebiusThe 1565290001Sglebius@code{ntpport} 1566290001Sglebiusis considered more specific and 1567290001Sglebiusis sorted later in the list. 1568290001Sglebius@item @code{version} 1569290001SglebiusDeny packets that do not match the current NTP version. 1570290001Sglebius@end table 1571290001Sglebius 1572290001SglebiusDefault restriction list entries with the flags ignore, interface, 1573290001Sglebiusntpport, for each of the local host's interface addresses are 1574290001Sglebiusinserted into the table at startup to prevent the server 1575290001Sglebiusfrom attempting to synchronize to its own time. 1576290001SglebiusA default entry is also always present, though if it is 1577290001Sglebiusotherwise unconfigured; no flags are associated 1578290001Sglebiuswith the default entry (i.e., everything besides your own 1579290001SglebiusNTP server is unrestricted). 1580290001Sglebius@end table 1581290001Sglebius@node Automatic NTP Configuration Options 1582290001Sglebius@subsection Automatic NTP Configuration Options 1583290001Sglebius@subsubsection Manycasting 1584290001SglebiusManycasting is a automatic discovery and configuration paradigm 1585290001Sglebiusnew to NTPv4. 1586290001SglebiusIt is intended as a means for a multicast client 1587290001Sglebiusto troll the nearby network neighborhood to find cooperating 1588290001Sglebiusmanycast servers, validate them using cryptographic means 1589290001Sglebiusand evaluate their time values with respect to other servers 1590290001Sglebiusthat might be lurking in the vicinity. 1591290001SglebiusThe intended result is that each manycast client mobilizes 1592290001Sglebiusclient associations with some number of the "best" 1593290001Sglebiusof the nearby manycast servers, yet automatically reconfigures 1594290001Sglebiusto sustain this number of servers should one or another fail. 1595290001Sglebius 1596290001SglebiusNote that the manycasting paradigm does not coincide 1597290001Sglebiuswith the anycast paradigm described in RFC-1546, 1598290001Sglebiuswhich is designed to find a single server from a clique 1599290001Sglebiusof servers providing the same service. 1600290001SglebiusThe manycast paradigm is designed to find a plurality 1601290001Sglebiusof redundant servers satisfying defined optimality criteria. 1602290001Sglebius 1603290001SglebiusManycasting can be used with either symmetric key 1604290001Sglebiusor public key cryptography. 1605290001SglebiusThe public key infrastructure (PKI) 1606290001Sglebiusoffers the best protection against compromised keys 1607290001Sglebiusand is generally considered stronger, at least with relatively 1608290001Sglebiuslarge key sizes. 1609290001SglebiusIt is implemented using the Autokey protocol and 1610290001Sglebiusthe OpenSSL cryptographic library available from 1611290001Sglebius@code{http://www.openssl.org/}. 1612290001SglebiusThe library can also be used with other NTPv4 modes 1613290001Sglebiusas well and is highly recommended, especially for broadcast modes. 1614290001Sglebius 1615290001SglebiusA persistent manycast client association is configured 1616290001Sglebiususing the manycastclient command, which is similar to the 1617290001Sglebiusserver command but with a multicast (IPv4 class 1618290001Sglebius@code{D} 1619290001Sglebiusor IPv6 prefix 1620290001Sglebius@code{FF}) 1621290001Sglebiusgroup address. 1622290001SglebiusThe IANA has designated IPv4 address 224.1.1.1 1623290001Sglebiusand IPv6 address FF05::101 (site local) for NTP. 1624290001SglebiusWhen more servers are needed, it broadcasts manycast 1625290001Sglebiusclient messages to this address at the minimum feasible rate 1626290001Sglebiusand minimum feasible time-to-live (TTL) hops, depending 1627290001Sglebiuson how many servers have already been found. 1628290001SglebiusThere can be as many manycast client associations 1629290001Sglebiusas different group address, each one serving as a template 1630290001Sglebiusfor a future ephemeral unicast client/server association. 1631290001Sglebius 1632290001SglebiusManycast servers configured with the 1633290001Sglebius@code{manycastserver} 1634290001Sglebiuscommand listen on the specified group address for manycast 1635290001Sglebiusclient messages. 1636290001SglebiusNote the distinction between manycast client, 1637290001Sglebiuswhich actively broadcasts messages, and manycast server, 1638290001Sglebiuswhich passively responds to them. 1639290001SglebiusIf a manycast server is 1640290001Sglebiusin scope of the current TTL and is itself synchronized 1641290001Sglebiusto a valid source and operating at a stratum level equal 1642290001Sglebiusto or lower than the manycast client, it replies to the 1643290001Sglebiusmanycast client message with an ordinary unicast server message. 1644290001Sglebius 1645290001SglebiusThe manycast client receiving this message mobilizes 1646290001Sglebiusan ephemeral client/server association according to the 1647290001Sglebiusmatching manycast client template, but only if cryptographically 1648290001Sglebiusauthenticated and the server stratum is less than or equal 1649290001Sglebiusto the client stratum. 1650290001SglebiusAuthentication is explicitly required 1651290001Sglebiusand either symmetric key or public key (Autokey) can be used. 1652290001SglebiusThen, the client polls the server at its unicast address 1653290001Sglebiusin burst mode in order to reliably set the host clock 1654290001Sglebiusand validate the source. 1655290001SglebiusThis normally results 1656290001Sglebiusin a volley of eight client/server at 2-s intervals 1657290001Sglebiusduring which both the synchronization and cryptographic 1658290001Sglebiusprotocols run concurrently. 1659290001SglebiusFollowing the volley, 1660290001Sglebiusthe client runs the NTP intersection and clustering 1661290001Sglebiusalgorithms, which act to discard all but the "best" 1662290001Sglebiusassociations according to stratum and synchronization 1663290001Sglebiusdistance. 1664290001SglebiusThe surviving associations then continue 1665290001Sglebiusin ordinary client/server mode. 1666290001Sglebius 1667290001SglebiusThe manycast client polling strategy is designed to reduce 1668290001Sglebiusas much as possible the volume of manycast client messages 1669290001Sglebiusand the effects of implosion due to near-simultaneous 1670290001Sglebiusarrival of manycast server messages. 1671290001SglebiusThe strategy is determined by the 1672290001Sglebius@code{manycastclient}, 1673290001Sglebius@code{tos} 1674290001Sglebiusand 1675290001Sglebius@code{ttl} 1676290001Sglebiusconfiguration commands. 1677290001SglebiusThe manycast poll interval is 1678290001Sglebiusnormally eight times the system poll interval, 1679290001Sglebiuswhich starts out at the 1680290001Sglebius@code{minpoll} 1681290001Sglebiusvalue specified in the 1682290001Sglebius@code{manycastclient}, 1683290001Sglebiuscommand and, under normal circumstances, increments to the 1684290001Sglebius@code{maxpolll} 1685290001Sglebiusvalue specified in this command. 1686290001SglebiusInitially, the TTL is 1687290001Sglebiusset at the minimum hops specified by the ttl command. 1688290001SglebiusAt each retransmission the TTL is increased until reaching 1689290001Sglebiusthe maximum hops specified by this command or a sufficient 1690290001Sglebiusnumber client associations have been found. 1691290001SglebiusFurther retransmissions use the same TTL. 1692290001Sglebius 1693290001SglebiusThe quality and reliability of the suite of associations 1694290001Sglebiusdiscovered by the manycast client is determined by the NTP 1695290001Sglebiusmitigation algorithms and the 1696290001Sglebius@code{minclock} 1697290001Sglebiusand 1698290001Sglebius@code{minsane} 1699290001Sglebiusvalues specified in the 1700290001Sglebius@code{tos} 1701290001Sglebiusconfiguration command. 1702290001SglebiusAt least 1703290001Sglebius@code{minsane} 1704290001Sglebiuscandidate servers must be available and the mitigation 1705290001Sglebiusalgorithms produce at least 1706290001Sglebius@code{minclock} 1707290001Sglebiussurvivors in order to synchronize the clock. 1708290001SglebiusByzantine agreement principles require at least four 1709290001Sglebiuscandidates in order to correctly discard a single falseticker. 1710290001SglebiusFor legacy purposes, 1711290001Sglebius@code{minsane} 1712290001Sglebiusdefaults to 1 and 1713290001Sglebius@code{minclock} 1714290001Sglebiusdefaults to 3. 1715290001SglebiusFor manycast service 1716290001Sglebius@code{minsane} 1717290001Sglebiusshould be explicitly set to 4, assuming at least that 1718290001Sglebiusnumber of servers are available. 1719290001Sglebius 1720290001SglebiusIf at least 1721290001Sglebius@code{minclock} 1722290001Sglebiusservers are found, the manycast poll interval is immediately 1723290001Sglebiusset to eight times 1724290001Sglebius@code{maxpoll}. 1725290001SglebiusIf less than 1726290001Sglebius@code{minclock} 1727290001Sglebiusservers are found when the TTL has reached the maximum hops, 1728290001Sglebiusthe manycast poll interval is doubled. 1729290001SglebiusFor each transmission 1730290001Sglebiusafter that, the poll interval is doubled again until 1731290001Sglebiusreaching the maximum of eight times 1732290001Sglebius@code{maxpoll}. 1733290001SglebiusFurther transmissions use the same poll interval and 1734290001SglebiusTTL values. 1735290001SglebiusNote that while all this is going on, 1736290001Sglebiuseach client/server association found is operating normally 1737290001Sglebiusit the system poll interval. 1738290001Sglebius 1739290001SglebiusAdministratively scoped multicast boundaries are normally 1740290001Sglebiusspecified by the network router configuration and, 1741290001Sglebiusin the case of IPv6, the link/site scope prefix. 1742290001SglebiusBy default, the increment for TTL hops is 32 starting 1743290001Sglebiusfrom 31; however, the 1744290001Sglebius@code{ttl} 1745290001Sglebiusconfiguration command can be 1746290001Sglebiusused to modify the values to match the scope rules. 1747290001Sglebius 1748290001SglebiusIt is often useful to narrow the range of acceptable 1749290001Sglebiusservers which can be found by manycast client associations. 1750290001SglebiusBecause manycast servers respond only when the client 1751290001Sglebiusstratum is equal to or greater than the server stratum, 1752290001Sglebiusprimary (stratum 1) servers fill find only primary servers 1753290001Sglebiusin TTL range, which is probably the most common objective. 1754290001SglebiusHowever, unless configured otherwise, all manycast clients 1755290001Sglebiusin TTL range will eventually find all primary servers 1756290001Sglebiusin TTL range, which is probably not the most common 1757290001Sglebiusobjective in large networks. 1758290001SglebiusThe 1759290001Sglebius@code{tos} 1760290001Sglebiuscommand can be used to modify this behavior. 1761290001SglebiusServers with stratum below 1762290001Sglebius@code{floor} 1763290001Sglebiusor above 1764290001Sglebius@code{ceiling} 1765290001Sglebiusspecified in the 1766290001Sglebius@code{tos} 1767290001Sglebiuscommand are strongly discouraged during the selection 1768290001Sglebiusprocess; however, these servers may be temporally 1769290001Sglebiusaccepted if the number of servers within TTL range is 1770290001Sglebiusless than 1771290001Sglebius@code{minclock}. 1772290001Sglebius 1773290001SglebiusThe above actions occur for each manycast client message, 1774290001Sglebiuswhich repeats at the designated poll interval. 1775290001SglebiusHowever, once the ephemeral client association is mobilized, 1776290001Sglebiussubsequent manycast server replies are discarded, 1777290001Sglebiussince that would result in a duplicate association. 1778290001SglebiusIf during a poll interval the number of client associations 1779290001Sglebiusfalls below 1780290001Sglebius@code{minclock}, 1781290001Sglebiusall manycast client prototype associations are reset 1782290001Sglebiusto the initial poll interval and TTL hops and operation 1783290001Sglebiusresumes from the beginning. 1784290001SglebiusIt is important to avoid 1785290001Sglebiusfrequent manycast client messages, since each one requires 1786290001Sglebiusall manycast servers in TTL range to respond. 1787290001SglebiusThe result could well be an implosion, either minor or major, 1788290001Sglebiusdepending on the number of servers in range. 1789290001SglebiusThe recommended value for 1790290001Sglebius@code{maxpoll} 1791290001Sglebiusis 12 (4,096 s). 1792290001Sglebius 1793290001SglebiusIt is possible and frequently useful to configure a host 1794290001Sglebiusas both manycast client and manycast server. 1795290001SglebiusA number of hosts configured this way and sharing a common 1796290001Sglebiusgroup address will automatically organize themselves 1797290001Sglebiusin an optimum configuration based on stratum and 1798290001Sglebiussynchronization distance. 1799290001SglebiusFor example, consider an NTP 1800290001Sglebiussubnet of two primary servers and a hundred or more 1801290001Sglebiusdependent clients. 1802290001SglebiusWith two exceptions, all servers 1803290001Sglebiusand clients have identical configuration files including both 1804290001Sglebius@code{multicastclient} 1805290001Sglebiusand 1806290001Sglebius@code{multicastserver} 1807290001Sglebiuscommands using, for instance, multicast group address 1808290001Sglebius239.1.1.1. 1809290001SglebiusThe only exception is that each primary server 1810290001Sglebiusconfiguration file must include commands for the primary 1811290001Sglebiusreference source such as a GPS receiver. 1812290001Sglebius 1813290001SglebiusThe remaining configuration files for all secondary 1814290001Sglebiusservers and clients have the same contents, except for the 1815290001Sglebius@code{tos} 1816290001Sglebiuscommand, which is specific for each stratum level. 1817290001SglebiusFor stratum 1 and stratum 2 servers, that command is 1818290001Sglebiusnot necessary. 1819290001SglebiusFor stratum 3 and above servers the 1820290001Sglebius@code{floor} 1821290001Sglebiusvalue is set to the intended stratum number. 1822290001SglebiusThus, all stratum 3 configuration files are identical, 1823290001Sglebiusall stratum 4 files are identical and so forth. 1824290001Sglebius 1825290001SglebiusOnce operations have stabilized in this scenario, 1826290001Sglebiusthe primary servers will find the primary reference source 1827290001Sglebiusand each other, since they both operate at the same 1828290001Sglebiusstratum (1), but not with any secondary server or client, 1829290001Sglebiussince these operate at a higher stratum. 1830290001SglebiusThe secondary 1831290001Sglebiusservers will find the servers at the same stratum level. 1832290001SglebiusIf one of the primary servers loses its GPS receiver, 1833290001Sglebiusit will continue to operate as a client and other clients 1834290001Sglebiuswill time out the corresponding association and 1835290001Sglebiusre-associate accordingly. 1836290001Sglebius 1837290001SglebiusSome administrators prefer to avoid running 1838290001Sglebius@code{ntpd(1ntpdmdoc)} 1839290001Sglebiuscontinuously and run either 1840290001Sglebius@code{sntp(1sntpmdoc)} 1841290001Sglebiusor 1842290001Sglebius@code{ntpd(1ntpdmdoc)} 1843290001Sglebius@code{-q} 1844290001Sglebiusas a cron job. 1845290001SglebiusIn either case the servers must be 1846290001Sglebiusconfigured in advance and the program fails if none are 1847290001Sglebiusavailable when the cron job runs. 1848290001SglebiusA really slick 1849290001Sglebiusapplication of manycast is with 1850290001Sglebius@code{ntpd(1ntpdmdoc)} 1851290001Sglebius@code{-q}. 1852290001SglebiusThe program wakes up, scans the local landscape looking 1853290001Sglebiusfor the usual suspects, selects the best from among 1854290001Sglebiusthe rascals, sets the clock and then departs. 1855290001SglebiusServers do not have to be configured in advance and 1856290001Sglebiusall clients throughout the network can have the same 1857290001Sglebiusconfiguration file. 1858290001Sglebius@subsubsection Manycast Interactions with Autokey 1859290001SglebiusEach time a manycast client sends a client mode packet 1860290001Sglebiusto a multicast group address, all manycast servers 1861290001Sglebiusin scope generate a reply including the host name 1862290001Sglebiusand status word. 1863290001SglebiusThe manycast clients then run 1864290001Sglebiusthe Autokey protocol, which collects and verifies 1865290001Sglebiusall certificates involved. 1866290001SglebiusFollowing the burst interval 1867290001Sglebiusall but three survivors are cast off, 1868290001Sglebiusbut the certificates remain in the local cache. 1869290001SglebiusIt often happens that several complete signing trails 1870290001Sglebiusfrom the client to the primary servers are collected in this way. 1871290001Sglebius 1872290001SglebiusAbout once an hour or less often if the poll interval 1873290001Sglebiusexceeds this, the client regenerates the Autokey key list. 1874290001SglebiusThis is in general transparent in client/server mode. 1875290001SglebiusHowever, about once per day the server private value 1876290001Sglebiusused to generate cookies is refreshed along with all 1877290001Sglebiusmanycast client associations. 1878290001SglebiusIn this case all 1879290001Sglebiuscryptographic values including certificates is refreshed. 1880290001SglebiusIf a new certificate has been generated since 1881290001Sglebiusthe last refresh epoch, it will automatically revoke 1882290001Sglebiusall prior certificates that happen to be in the 1883290001Sglebiuscertificate cache. 1884290001SglebiusAt the same time, the manycast 1885290001Sglebiusscheme starts all over from the beginning and 1886290001Sglebiusthe expanding ring shrinks to the minimum and increments 1887290001Sglebiusfrom there while collecting all servers in scope. 1888290001Sglebius@subsubsection Manycast Options 1889290001Sglebius@table @asis 1890290001Sglebius@item @code{tos} @code{[@code{ceiling} @kbd{ceiling} | @code{cohort} @code{@{} @code{0} | @code{1} @code{@}} | @code{floor} @kbd{floor} | @code{minclock} @kbd{minclock} | @code{minsane} @kbd{minsane}]} 1891290001SglebiusThis command affects the clock selection and clustering 1892290001Sglebiusalgorithms. 1893290001SglebiusIt can be used to select the quality and 1894290001Sglebiusquantity of peers used to synchronize the system clock 1895290001Sglebiusand is most useful in manycast mode. 1896290001SglebiusThe variables operate 1897290001Sglebiusas follows: 1898290001Sglebius@table @asis 1899290001Sglebius@item @code{ceiling} @kbd{ceiling} 1900290001SglebiusPeers with strata above 1901290001Sglebius@code{ceiling} 1902290001Sglebiuswill be discarded if there are at least 1903290001Sglebius@code{minclock} 1904290001Sglebiuspeers remaining. 1905290001SglebiusThis value defaults to 15, but can be changed 1906290001Sglebiusto any number from 1 to 15. 1907290001Sglebius@item @code{cohort} @code{@{0 | 1@}} 1908290001SglebiusThis is a binary flag which enables (0) or disables (1) 1909290001Sglebiusmanycast server replies to manycast clients with the same 1910290001Sglebiusstratum level. 1911290001SglebiusThis is useful to reduce implosions where 1912290001Sglebiuslarge numbers of clients with the same stratum level 1913290001Sglebiusare present. 1914290001SglebiusThe default is to enable these replies. 1915290001Sglebius@item @code{floor} @kbd{floor} 1916290001SglebiusPeers with strata below 1917290001Sglebius@code{floor} 1918290001Sglebiuswill be discarded if there are at least 1919290001Sglebius@code{minclock} 1920290001Sglebiuspeers remaining. 1921290001SglebiusThis value defaults to 1, but can be changed 1922290001Sglebiusto any number from 1 to 15. 1923290001Sglebius@item @code{minclock} @kbd{minclock} 1924290001SglebiusThe clustering algorithm repeatedly casts out outlier 1925290001Sglebiusassociations until no more than 1926290001Sglebius@code{minclock} 1927290001Sglebiusassociations remain. 1928290001SglebiusThis value defaults to 3, 1929290001Sglebiusbut can be changed to any number from 1 to the number of 1930290001Sglebiusconfigured sources. 1931290001Sglebius@item @code{minsane} @kbd{minsane} 1932290001SglebiusThis is the minimum number of candidates available 1933290001Sglebiusto the clock selection algorithm in order to produce 1934290001Sglebiusone or more truechimers for the clustering algorithm. 1935290001SglebiusIf fewer than this number are available, the clock is 1936290001Sglebiusundisciplined and allowed to run free. 1937290001SglebiusThe default is 1 1938290001Sglebiusfor legacy purposes. 1939290001SglebiusHowever, according to principles of 1940290001SglebiusByzantine agreement, 1941290001Sglebius@code{minsane} 1942290001Sglebiusshould be at least 4 in order to detect and discard 1943290001Sglebiusa single falseticker. 1944290001Sglebius@end table 1945290001Sglebius@item @code{ttl} @kbd{hop} @kbd{...} 1946290001SglebiusThis command specifies a list of TTL values in increasing 1947290001Sglebiusorder, up to 8 values can be specified. 1948290001SglebiusIn manycast mode these values are used in turn 1949290001Sglebiusin an expanding-ring search. 1950290001SglebiusThe default is eight 1951290001Sglebiusmultiples of 32 starting at 31. 1952290001Sglebius@end table 1953290001Sglebius@node Reference Clock Support 1954290001Sglebius@subsection Reference Clock Support 1955290001SglebiusThe NTP Version 4 daemon supports some three dozen different radio, 1956290001Sglebiussatellite and modem reference clocks plus a special pseudo-clock 1957290001Sglebiusused for backup or when no other clock source is available. 1958290001SglebiusDetailed descriptions of individual device drivers and options can 1959290001Sglebiusbe found in the 1960290001Sglebius"Reference Clock Drivers" 1961290001Sglebiuspage 1962290001Sglebius(available as part of the HTML documentation 1963290001Sglebiusprovided in 1964290001Sglebius@file{/usr/share/doc/ntp}). 1965290001SglebiusAdditional information can be found in the pages linked 1966290001Sglebiusthere, including the 1967290001Sglebius"Debugging Hints for Reference Clock Drivers" 1968290001Sglebiusand 1969290001Sglebius"How To Write a Reference Clock Driver" 1970290001Sglebiuspages 1971290001Sglebius(available as part of the HTML documentation 1972290001Sglebiusprovided in 1973290001Sglebius@file{/usr/share/doc/ntp}). 1974290001SglebiusIn addition, support for a PPS 1975290001Sglebiussignal is available as described in the 1976290001Sglebius"Pulse-per-second (PPS) Signal Interfacing" 1977290001Sglebiuspage 1978290001Sglebius(available as part of the HTML documentation 1979290001Sglebiusprovided in 1980290001Sglebius@file{/usr/share/doc/ntp}). 1981290001SglebiusMany 1982290001Sglebiusdrivers support special line discipline/streams modules which can 1983290001Sglebiussignificantly improve the accuracy using the driver. 1984290001SglebiusThese are 1985290001Sglebiusdescribed in the 1986290001Sglebius"Line Disciplines and Streams Drivers" 1987290001Sglebiuspage 1988290001Sglebius(available as part of the HTML documentation 1989290001Sglebiusprovided in 1990290001Sglebius@file{/usr/share/doc/ntp}). 1991290001Sglebius 1992290001SglebiusA reference clock will generally (though not always) be a radio 1993290001Sglebiustimecode receiver which is synchronized to a source of standard 1994290001Sglebiustime such as the services offered by the NRC in Canada and NIST and 1995290001SglebiusUSNO in the US. 1996290001SglebiusThe interface between the computer and the timecode 1997290001Sglebiusreceiver is device dependent, but is usually a serial port. 1998290001SglebiusA 1999290001Sglebiusdevice driver specific to each reference clock must be selected and 2000290001Sglebiuscompiled in the distribution; however, most common radio, satellite 2001290001Sglebiusand modem clocks are included by default. 2002290001SglebiusNote that an attempt to 2003290001Sglebiusconfigure a reference clock when the driver has not been compiled 2004290001Sglebiusor the hardware port has not been appropriately configured results 2005290001Sglebiusin a scalding remark to the system log file, but is otherwise non 2006290001Sglebiushazardous. 2007290001Sglebius 2008290001SglebiusFor the purposes of configuration, 2009290001Sglebius@code{ntpd(1ntpdmdoc)} 2010290001Sglebiustreats 2011290001Sglebiusreference clocks in a manner analogous to normal NTP peers as much 2012290001Sglebiusas possible. 2013290001SglebiusReference clocks are identified by a syntactically 2014290001Sglebiuscorrect but invalid IP address, in order to distinguish them from 2015290001Sglebiusnormal NTP peers. 2016290001SglebiusReference clock addresses are of the form 2017290001Sglebius@code{127.127.}@kbd{t}.@kbd{u}, 2018290001Sglebiuswhere 2019290001Sglebius@kbd{t} 2020290001Sglebiusis an integer 2021290001Sglebiusdenoting the clock type and 2022290001Sglebius@kbd{u} 2023290001Sglebiusindicates the unit 2024290001Sglebiusnumber in the range 0-3. 2025290001SglebiusWhile it may seem overkill, it is in fact 2026290001Sglebiussometimes useful to configure multiple reference clocks of the same 2027290001Sglebiustype, in which case the unit numbers must be unique. 2028290001Sglebius 2029290001SglebiusThe 2030290001Sglebius@code{server} 2031290001Sglebiuscommand is used to configure a reference 2032290001Sglebiusclock, where the 2033290001Sglebius@kbd{address} 2034290001Sglebiusargument in that command 2035290001Sglebiusis the clock address. 2036290001SglebiusThe 2037290001Sglebius@code{key}, 2038290001Sglebius@code{version} 2039290001Sglebiusand 2040290001Sglebius@code{ttl} 2041290001Sglebiusoptions are not used for reference clock support. 2042290001SglebiusThe 2043290001Sglebius@code{mode} 2044290001Sglebiusoption is added for reference clock support, as 2045290001Sglebiusdescribed below. 2046290001SglebiusThe 2047290001Sglebius@code{prefer} 2048290001Sglebiusoption can be useful to 2049290001Sglebiuspersuade the server to cherish a reference clock with somewhat more 2050290001Sglebiusenthusiasm than other reference clocks or peers. 2051290001SglebiusFurther 2052290001Sglebiusinformation on this option can be found in the 2053290001Sglebius"Mitigation Rules and the prefer Keyword" 2054290001Sglebius(available as part of the HTML documentation 2055290001Sglebiusprovided in 2056290001Sglebius@file{/usr/share/doc/ntp}) 2057290001Sglebiuspage. 2058290001SglebiusThe 2059290001Sglebius@code{minpoll} 2060290001Sglebiusand 2061290001Sglebius@code{maxpoll} 2062290001Sglebiusoptions have 2063290001Sglebiusmeaning only for selected clock drivers. 2064290001SglebiusSee the individual clock 2065290001Sglebiusdriver document pages for additional information. 2066290001Sglebius 2067290001SglebiusThe 2068290001Sglebius@code{fudge} 2069290001Sglebiuscommand is used to provide additional 2070290001Sglebiusinformation for individual clock drivers and normally follows 2071290001Sglebiusimmediately after the 2072290001Sglebius@code{server} 2073290001Sglebiuscommand. 2074290001SglebiusThe 2075290001Sglebius@kbd{address} 2076290001Sglebiusargument specifies the clock address. 2077290001SglebiusThe 2078290001Sglebius@code{refid} 2079290001Sglebiusand 2080290001Sglebius@code{stratum} 2081290001Sglebiusoptions can be used to 2082290001Sglebiusoverride the defaults for the device. 2083290001SglebiusThere are two optional 2084290001Sglebiusdevice-dependent time offsets and four flags that can be included 2085290001Sglebiusin the 2086290001Sglebius@code{fudge} 2087290001Sglebiuscommand as well. 2088290001Sglebius 2089290001SglebiusThe stratum number of a reference clock is by default zero. 2090290001SglebiusSince the 2091290001Sglebius@code{ntpd(1ntpdmdoc)} 2092290001Sglebiusdaemon adds one to the stratum of each 2093290001Sglebiuspeer, a primary server ordinarily displays an external stratum of 2094290001Sglebiusone. 2095290001SglebiusIn order to provide engineered backups, it is often useful to 2096290001Sglebiusspecify the reference clock stratum as greater than zero. 2097290001SglebiusThe 2098290001Sglebius@code{stratum} 2099290001Sglebiusoption is used for this purpose. 2100290001SglebiusAlso, in cases 2101290001Sglebiusinvolving both a reference clock and a pulse-per-second (PPS) 2102290001Sglebiusdiscipline signal, it is useful to specify the reference clock 2103290001Sglebiusidentifier as other than the default, depending on the driver. 2104290001SglebiusThe 2105290001Sglebius@code{refid} 2106290001Sglebiusoption is used for this purpose. 2107290001SglebiusExcept where noted, 2108290001Sglebiusthese options apply to all clock drivers. 2109290001Sglebius@subsubsection Reference Clock Commands 2110290001Sglebius@table @asis 2111290001Sglebius@item @code{server} @code{127.127.}@kbd{t}.@kbd{u} @code{[@code{prefer}]} @code{[@code{mode} @kbd{int}]} @code{[@code{minpoll} @kbd{int}]} @code{[@code{maxpoll} @kbd{int}]} 2112290001SglebiusThis command can be used to configure reference clocks in 2113290001Sglebiusspecial ways. 2114290001SglebiusThe options are interpreted as follows: 2115290001Sglebius@table @asis 2116290001Sglebius@item @code{prefer} 2117290001SglebiusMarks the reference clock as preferred. 2118290001SglebiusAll other things being 2119290001Sglebiusequal, this host will be chosen for synchronization among a set of 2120290001Sglebiuscorrectly operating hosts. 2121290001SglebiusSee the 2122290001Sglebius"Mitigation Rules and the prefer Keyword" 2123290001Sglebiuspage 2124290001Sglebius(available as part of the HTML documentation 2125290001Sglebiusprovided in 2126290001Sglebius@file{/usr/share/doc/ntp}) 2127290001Sglebiusfor further information. 2128290001Sglebius@item @code{mode} @kbd{int} 2129290001SglebiusSpecifies a mode number which is interpreted in a 2130290001Sglebiusdevice-specific fashion. 2131290001SglebiusFor instance, it selects a dialing 2132290001Sglebiusprotocol in the ACTS driver and a device subtype in the 2133290001Sglebiusparse 2134290001Sglebiusdrivers. 2135290001Sglebius@item @code{minpoll} @kbd{int} 2136290001Sglebius@item @code{maxpoll} @kbd{int} 2137290001SglebiusThese options specify the minimum and maximum polling interval 2138290001Sglebiusfor reference clock messages, as a power of 2 in seconds 2139290001SglebiusFor 2140290001Sglebiusmost directly connected reference clocks, both 2141290001Sglebius@code{minpoll} 2142290001Sglebiusand 2143290001Sglebius@code{maxpoll} 2144290001Sglebiusdefault to 6 (64 s). 2145290001SglebiusFor modem reference clocks, 2146290001Sglebius@code{minpoll} 2147290001Sglebiusdefaults to 10 (17.1 m) and 2148290001Sglebius@code{maxpoll} 2149290001Sglebiusdefaults to 14 (4.5 h). 2150290001SglebiusThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2151290001Sglebius@end table 2152290001Sglebius@item @code{fudge} @code{127.127.}@kbd{t}.@kbd{u} @code{[@code{time1} @kbd{sec}]} @code{[@code{time2} @kbd{sec}]} @code{[@code{stratum} @kbd{int}]} @code{[@code{refid} @kbd{string}]} @code{[@code{mode} @kbd{int}]} @code{[@code{flag1} @code{0} @code{|} @code{1}]} @code{[@code{flag2} @code{0} @code{|} @code{1}]} @code{[@code{flag3} @code{0} @code{|} @code{1}]} @code{[@code{flag4} @code{0} @code{|} @code{1}]} 2153290001SglebiusThis command can be used to configure reference clocks in 2154290001Sglebiusspecial ways. 2155290001SglebiusIt must immediately follow the 2156290001Sglebius@code{server} 2157290001Sglebiuscommand which configures the driver. 2158290001SglebiusNote that the same capability 2159290001Sglebiusis possible at run time using the 2160290001Sglebius@code{ntpdc(1ntpdcmdoc)} 2161290001Sglebiusprogram. 2162290001SglebiusThe options are interpreted as 2163290001Sglebiusfollows: 2164290001Sglebius@table @asis 2165290001Sglebius@item @code{time1} @kbd{sec} 2166290001SglebiusSpecifies a constant to be added to the time offset produced by 2167290001Sglebiusthe driver, a fixed-point decimal number in seconds. 2168290001SglebiusThis is used 2169290001Sglebiusas a calibration constant to adjust the nominal time offset of a 2170290001Sglebiusparticular clock to agree with an external standard, such as a 2171290001Sglebiusprecision PPS signal. 2172290001SglebiusIt also provides a way to correct a 2173290001Sglebiussystematic error or bias due to serial port or operating system 2174290001Sglebiuslatencies, different cable lengths or receiver internal delay. 2175290001SglebiusThe 2176290001Sglebiusspecified offset is in addition to the propagation delay provided 2177290001Sglebiusby other means, such as internal DIPswitches. 2178290001SglebiusWhere a calibration 2179290001Sglebiusfor an individual system and driver is available, an approximate 2180290001Sglebiuscorrection is noted in the driver documentation pages. 2181290001SglebiusNote: in order to facilitate calibration when more than one 2182290001Sglebiusradio clock or PPS signal is supported, a special calibration 2183290001Sglebiusfeature is available. 2184290001SglebiusIt takes the form of an argument to the 2185290001Sglebius@code{enable} 2186290001Sglebiuscommand described in 2187290001Sglebius@ref{Miscellaneous Options} 2188290001Sglebiuspage and operates as described in the 2189290001Sglebius"Reference Clock Drivers" 2190290001Sglebiuspage 2191290001Sglebius(available as part of the HTML documentation 2192290001Sglebiusprovided in 2193290001Sglebius@file{/usr/share/doc/ntp}). 2194290001Sglebius@item @code{time2} @kbd{secs} 2195290001SglebiusSpecifies a fixed-point decimal number in seconds, which is 2196290001Sglebiusinterpreted in a driver-dependent way. 2197290001SglebiusSee the descriptions of 2198290001Sglebiusspecific drivers in the 2199290001Sglebius"Reference Clock Drivers" 2200290001Sglebiuspage 2201290001Sglebius(available as part of the HTML documentation 2202290001Sglebiusprovided in 2203290001Sglebius@file{/usr/share/doc/ntp}). 2204290001Sglebius@item @code{stratum} @kbd{int} 2205290001SglebiusSpecifies the stratum number assigned to the driver, an integer 2206290001Sglebiusbetween 0 and 15. 2207290001SglebiusThis number overrides the default stratum number 2208290001Sglebiusordinarily assigned by the driver itself, usually zero. 2209290001Sglebius@item @code{refid} @kbd{string} 2210290001SglebiusSpecifies an ASCII string of from one to four characters which 2211290001Sglebiusdefines the reference identifier used by the driver. 2212290001SglebiusThis string 2213290001Sglebiusoverrides the default identifier ordinarily assigned by the driver 2214290001Sglebiusitself. 2215290001Sglebius@item @code{mode} @kbd{int} 2216290001SglebiusSpecifies a mode number which is interpreted in a 2217290001Sglebiusdevice-specific fashion. 2218290001SglebiusFor instance, it selects a dialing 2219290001Sglebiusprotocol in the ACTS driver and a device subtype in the 2220290001Sglebiusparse 2221290001Sglebiusdrivers. 2222290001Sglebius@item @code{flag1} @code{0} @code{|} @code{1} 2223290001Sglebius@item @code{flag2} @code{0} @code{|} @code{1} 2224290001Sglebius@item @code{flag3} @code{0} @code{|} @code{1} 2225290001Sglebius@item @code{flag4} @code{0} @code{|} @code{1} 2226290001SglebiusThese four flags are used for customizing the clock driver. 2227290001SglebiusThe 2228290001Sglebiusinterpretation of these values, and whether they are used at all, 2229290001Sglebiusis a function of the particular clock driver. 2230290001SglebiusHowever, by 2231290001Sglebiusconvention 2232290001Sglebius@code{flag4} 2233290001Sglebiusis used to enable recording monitoring 2234290001Sglebiusdata to the 2235290001Sglebius@code{clockstats} 2236290001Sglebiusfile configured with the 2237290001Sglebius@code{filegen} 2238290001Sglebiuscommand. 2239290001SglebiusFurther information on the 2240290001Sglebius@code{filegen} 2241290001Sglebiuscommand can be found in 2242290001Sglebius@ref{Monitoring Options}. 2243290001Sglebius@end table 2244290001Sglebius@end table 2245290001Sglebius@node Miscellaneous Options 2246290001Sglebius@subsection Miscellaneous Options 2247290001Sglebius@table @asis 2248290001Sglebius@item @code{broadcastdelay} @kbd{seconds} 2249290001SglebiusThe broadcast and multicast modes require a special calibration 2250290001Sglebiusto determine the network delay between the local and remote 2251290001Sglebiusservers. 2252290001SglebiusOrdinarily, this is done automatically by the initial 2253290001Sglebiusprotocol exchanges between the client and server. 2254290001SglebiusIn some cases, 2255290001Sglebiusthe calibration procedure may fail due to network or server access 2256290001Sglebiuscontrols, for example. 2257290001SglebiusThis command specifies the default delay to 2258290001Sglebiusbe used under these circumstances. 2259290001SglebiusTypically (for Ethernet), a 2260290001Sglebiusnumber between 0.003 and 0.007 seconds is appropriate. 2261290001SglebiusThe default 2262290001Sglebiuswhen this command is not used is 0.004 seconds. 2263290001Sglebius@item @code{calldelay} @kbd{delay} 2264290001SglebiusThis option controls the delay in seconds between the first and second 2265290001Sglebiuspackets sent in burst or iburst mode to allow additional time for a modem 2266290001Sglebiusor ISDN call to complete. 2267290001Sglebius@item @code{driftfile} @kbd{driftfile} 2268290001SglebiusThis command specifies the complete path and name of the file used to 2269290001Sglebiusrecord the frequency of the local clock oscillator. 2270290001SglebiusThis is the same 2271290001Sglebiusoperation as the 2272290001Sglebius@code{-f} 2273290001Sglebiuscommand line option. 2274290001SglebiusIf the file exists, it is read at 2275290001Sglebiusstartup in order to set the initial frequency and then updated once per 2276290001Sglebiushour with the current frequency computed by the daemon. 2277290001SglebiusIf the file name is 2278290001Sglebiusspecified, but the file itself does not exist, the starts with an initial 2279290001Sglebiusfrequency of zero and creates the file when writing it for the first time. 2280290001SglebiusIf this command is not given, the daemon will always start with an initial 2281290001Sglebiusfrequency of zero. 2282290001Sglebius 2283290001SglebiusThe file format consists of a single line containing a single 2284290001Sglebiusfloating point number, which records the frequency offset measured 2285290001Sglebiusin parts-per-million (PPM). 2286290001SglebiusThe file is updated by first writing 2287290001Sglebiusthe current drift value into a temporary file and then renaming 2288290001Sglebiusthis file to replace the old version. 2289290001SglebiusThis implies that 2290290001Sglebius@code{ntpd(1ntpdmdoc)} 2291290001Sglebiusmust have write permission for the directory the 2292290001Sglebiusdrift file is located in, and that file system links, symbolic or 2293290001Sglebiusotherwise, should be avoided. 2294290001Sglebius@item @code{dscp} @kbd{value} 2295290001SglebiusThis option specifies the Differentiated Services Control Point (DSCP) value, 2296290001Sglebiusa 6-bit code. The default value is 46, signifying Expedited Forwarding. 2297294905Sdelphij@item @code{enable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats} | @code{unpeer_crypto_early} | @code{unpeer_crypto_nak_early} | @code{unpeer_digest_early}]} 2298294905Sdelphij@item @code{disable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats} | @code{unpeer_crypto_early} | @code{unpeer_crypto_nak_early} | @code{unpeer_digest_early}]} 2299290001SglebiusProvides a way to enable or disable various server options. 2300290001SglebiusFlags not mentioned are unaffected. 2301290001SglebiusNote that all of these flags 2302290001Sglebiuscan be controlled remotely using the 2303290001Sglebius@code{ntpdc(1ntpdcmdoc)} 2304290001Sglebiusutility program. 2305290001Sglebius@table @asis 2306290001Sglebius@item @code{auth} 2307290001SglebiusEnables the server to synchronize with unconfigured peers only if the 2308290001Sglebiuspeer has been correctly authenticated using either public key or 2309290001Sglebiusprivate key cryptography. 2310290001SglebiusThe default for this flag is 2311290001Sglebius@code{enable}. 2312290001Sglebius@item @code{bclient} 2313290001SglebiusEnables the server to listen for a message from a broadcast or 2314290001Sglebiusmulticast server, as in the 2315290001Sglebius@code{multicastclient} 2316290001Sglebiuscommand with default 2317290001Sglebiusaddress. 2318290001SglebiusThe default for this flag is 2319290001Sglebius@code{disable}. 2320290001Sglebius@item @code{calibrate} 2321290001SglebiusEnables the calibrate feature for reference clocks. 2322290001SglebiusThe default for 2323290001Sglebiusthis flag is 2324290001Sglebius@code{disable}. 2325290001Sglebius@item @code{kernel} 2326290001SglebiusEnables the kernel time discipline, if available. 2327290001SglebiusThe default for this 2328290001Sglebiusflag is 2329290001Sglebius@code{enable} 2330290001Sglebiusif support is available, otherwise 2331290001Sglebius@code{disable}. 2332290001Sglebius@item @code{mode7} 2333290001SglebiusEnables processing of NTP mode 7 implementation-specific requests 2334290001Sglebiuswhich are used by the deprecated 2335290001Sglebius@code{ntpdc(1ntpdcmdoc)} 2336290001Sglebiusprogram. 2337290001SglebiusThe default for this flag is disable. 2338290001SglebiusThis flag is excluded from runtime configuration using 2339290001Sglebius@code{ntpq(1ntpqmdoc)}. 2340290001SglebiusThe 2341290001Sglebius@code{ntpq(1ntpqmdoc)} 2342290001Sglebiusprogram provides the same capabilities as 2343290001Sglebius@code{ntpdc(1ntpdcmdoc)} 2344290001Sglebiususing standard mode 6 requests. 2345290001Sglebius@item @code{monitor} 2346290001SglebiusEnables the monitoring facility. 2347290001SglebiusSee the 2348290001Sglebius@code{ntpdc(1ntpdcmdoc)} 2349290001Sglebiusprogram 2350290001Sglebiusand the 2351290001Sglebius@code{monlist} 2352290001Sglebiuscommand or further information. 2353290001SglebiusThe 2354290001Sglebiusdefault for this flag is 2355290001Sglebius@code{enable}. 2356290001Sglebius@item @code{ntp} 2357290001SglebiusEnables time and frequency discipline. 2358290001SglebiusIn effect, this switch opens and 2359290001Sglebiuscloses the feedback loop, which is useful for testing. 2360290001SglebiusThe default for 2361290001Sglebiusthis flag is 2362290001Sglebius@code{enable}. 2363290001Sglebius@item @code{stats} 2364290001SglebiusEnables the statistics facility. 2365290001SglebiusSee the 2366290001Sglebius@ref{Monitoring Options} 2367290001Sglebiussection for further information. 2368290001SglebiusThe default for this flag is 2369290001Sglebius@code{disable}. 2370294905Sdelphij@item @code{unpeer_crypto_early} 2371294905SdelphijBy default, if 2372294905Sdelphij@code{ntpd(1ntpdmdoc)} 2373294905Sdelphijreceives an autokey packet that fails TEST9, 2374294905Sdelphija crypto failure, 2375294905Sdelphijthe association is immediately cleared. 2376294905SdelphijThis is almost certainly a feature, 2377294905Sdelphijbut if, in spite of the current recommendation of not using autokey, 2378294905Sdelphijyou are 2379294905Sdelphij.B still 2380294905Sdelphijusing autokey 2381294905Sdelphij.B and 2382294905Sdelphijyou are seeing this sort of DoS attack 2383294905Sdelphijdisabling this flag will delay 2384294905Sdelphijtearing down the association until the reachability counter 2385294905Sdelphijbecomes zero. 2386294905SdelphijYou can check your 2387294905Sdelphij@code{peerstats} 2388294905Sdelphijfile for evidence of any of these attacks. 2389294905SdelphijThe 2390294905Sdelphijdefault for this flag is 2391294905Sdelphij@code{enable}. 2392294905Sdelphij@item @code{unpeer_crypto_nak_early} 2393294905SdelphijBy default, if 2394294905Sdelphij@code{ntpd(1ntpdmdoc)} 2395294905Sdelphijreceives a crypto-NAK packet that 2396294905Sdelphijpasses the duplicate packet and origin timestamp checks 2397294905Sdelphijthe association is immediately cleared. 2398294905SdelphijWhile this is generally a feature 2399294905Sdelphijas it allows for quick recovery if a server key has changed, 2400294905Sdelphija properly forged and appropriately delivered crypto-NAK packet 2401294905Sdelphijcan be used in a DoS attack. 2402294905SdelphijIf you have active noticable problems with this type of DoS attack 2403294905Sdelphijthen you should consider 2404294905Sdelphijdisabling this option. 2405294905SdelphijYou can check your 2406294905Sdelphij@code{peerstats} 2407294905Sdelphijfile for evidence of any of these attacks. 2408294905SdelphijThe 2409294905Sdelphijdefault for this flag is 2410294905Sdelphij@code{enable}. 2411294905Sdelphij@item @code{unpeer_digest_early} 2412294905SdelphijBy default, if 2413294905Sdelphij@code{ntpd(1ntpdmdoc)} 2414294905Sdelphijreceives what should be an authenticated packet 2415294905Sdelphijthat passes other packet sanity checks but 2416294905Sdelphijcontains an invalid digest 2417294905Sdelphijthe association is immediately cleared. 2418294905SdelphijWhile this is generally a feature 2419294905Sdelphijas it allows for quick recovery, 2420294905Sdelphijif this type of packet is carefully forged and sent 2421294905Sdelphijduring an appropriate window it can be used for a DoS attack. 2422294905SdelphijIf you have active noticable problems with this type of DoS attack 2423294905Sdelphijthen you should consider 2424294905Sdelphijdisabling this option. 2425294905SdelphijYou can check your 2426294905Sdelphij@code{peerstats} 2427294905Sdelphijfile for evidence of any of these attacks. 2428294905SdelphijThe 2429294905Sdelphijdefault for this flag is 2430294905Sdelphij@code{enable}. 2431290001Sglebius@end table 2432290001Sglebius@item @code{includefile} @kbd{includefile} 2433290001SglebiusThis command allows additional configuration commands 2434290001Sglebiusto be included from a separate file. 2435290001SglebiusInclude files may 2436290001Sglebiusbe nested to a depth of five; upon reaching the end of any 2437290001Sglebiusinclude file, command processing resumes in the previous 2438290001Sglebiusconfiguration file. 2439290001SglebiusThis option is useful for sites that run 2440290001Sglebius@code{ntpd(1ntpdmdoc)} 2441290001Sglebiuson multiple hosts, with (mostly) common options (e.g., a 2442290001Sglebiusrestriction list). 2443290001Sglebius@item @code{leapsmearinterval} @kbd{seconds} 2444290001SglebiusThis EXPERIMENTAL option is only available if 2445290001Sglebius@code{ntpd(1ntpdmdoc)} 2446290001Sglebiuswas built with the 2447290001Sglebius@code{--enable-leap-smear} 2448290001Sglebiusoption to the 2449290001Sglebius@code{configure} 2450290001Sglebiusscript. 2451290001SglebiusIt specifies the interval over which a leap second correction will be applied. 2452290001SglebiusRecommended values for this option are between 2453290001Sglebius7200 (2 hours) and 86400 (24 hours). 2454290001Sglebius.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2455290001SglebiusSee http://bugs.ntp.org/2855 for more information. 2456290001Sglebius@item @code{logconfig} @kbd{configkeyword} 2457290001SglebiusThis command controls the amount and type of output written to 2458290001Sglebiusthe system 2459290001Sglebius@code{syslog(3)} 2460290001Sglebiusfacility or the alternate 2461290001Sglebius@code{logfile} 2462290001Sglebiuslog file. 2463290001SglebiusBy default, all output is turned on. 2464290001SglebiusAll 2465290001Sglebius@kbd{configkeyword} 2466290001Sglebiuskeywords can be prefixed with 2467290001Sglebius@quoteleft{}=@quoteright{}, 2468290001Sglebius@quoteleft{}+@quoteright{} 2469290001Sglebiusand 2470290001Sglebius@quoteleft{}-@quoteright{}, 2471290001Sglebiuswhere 2472290001Sglebius@quoteleft{}=@quoteright{} 2473290001Sglebiussets the 2474290001Sglebius@code{syslog(3)} 2475290001Sglebiuspriority mask, 2476290001Sglebius@quoteleft{}+@quoteright{} 2477290001Sglebiusadds and 2478290001Sglebius@quoteleft{}-@quoteright{} 2479290001Sglebiusremoves 2480290001Sglebiusmessages. 2481290001Sglebius@code{syslog(3)} 2482290001Sglebiusmessages can be controlled in four 2483290001Sglebiusclasses 2484290001Sglebius(@code{clock}, @code{peer}, @code{sys} and @code{sync}). 2485290001SglebiusWithin these classes four types of messages can be 2486290001Sglebiuscontrolled: informational messages 2487290001Sglebius(@code{info}), 2488290001Sglebiusevent messages 2489290001Sglebius(@code{events}), 2490290001Sglebiusstatistics messages 2491290001Sglebius(@code{statistics}) 2492290001Sglebiusand 2493290001Sglebiusstatus messages 2494290001Sglebius(@code{status}). 2495290001Sglebius 2496290001SglebiusConfiguration keywords are formed by concatenating the message class with 2497290001Sglebiusthe event class. 2498290001SglebiusThe 2499290001Sglebius@code{all} 2500290001Sglebiusprefix can be used instead of a message class. 2501290001SglebiusA 2502290001Sglebiusmessage class may also be followed by the 2503290001Sglebius@code{all} 2504290001Sglebiuskeyword to enable/disable all 2505290001Sglebiusmessages of the respective message class.Thus, a minimal log configuration 2506290001Sglebiuscould look like this: 2507290001Sglebius@verbatim 2508290001Sglebiuslogconfig =syncstatus +sysevents 2509290001Sglebius@end verbatim 2510290001Sglebius 2511290001SglebiusThis would just list the synchronizations state of 2512290001Sglebius@code{ntpd(1ntpdmdoc)} 2513290001Sglebiusand the major system events. 2514290001SglebiusFor a simple reference server, the 2515290001Sglebiusfollowing minimum message configuration could be useful: 2516290001Sglebius@verbatim 2517290001Sglebiuslogconfig =syncall +clockall 2518290001Sglebius@end verbatim 2519290001Sglebius 2520290001SglebiusThis configuration will list all clock information and 2521290001Sglebiussynchronization information. 2522290001SglebiusAll other events and messages about 2523290001Sglebiuspeers, system events and so on is suppressed. 2524290001Sglebius@item @code{logfile} @kbd{logfile} 2525290001SglebiusThis command specifies the location of an alternate log file to 2526290001Sglebiusbe used instead of the default system 2527290001Sglebius@code{syslog(3)} 2528290001Sglebiusfacility. 2529290001SglebiusThis is the same operation as the -l command line option. 2530290001Sglebius@item @code{setvar} @kbd{variable} @code{[@code{default}]} 2531290001SglebiusThis command adds an additional system variable. 2532290001SglebiusThese 2533290001Sglebiusvariables can be used to distribute additional information such as 2534290001Sglebiusthe access policy. 2535290001SglebiusIf the variable of the form 2536290001Sglebius@code{name}@code{=}@kbd{value} 2537290001Sglebiusis followed by the 2538290001Sglebius@code{default} 2539290001Sglebiuskeyword, the 2540290001Sglebiusvariable will be listed as part of the default system variables 2541290001Sglebius(@code{rv} command)). 2542290001SglebiusThese additional variables serve 2543290001Sglebiusinformational purposes only. 2544290001SglebiusThey are not related to the protocol 2545290001Sglebiusother that they can be listed. 2546290001SglebiusThe known protocol variables will 2547290001Sglebiusalways override any variables defined via the 2548290001Sglebius@code{setvar} 2549290001Sglebiusmechanism. 2550290001SglebiusThere are three special variables that contain the names 2551290001Sglebiusof all variable of the same group. 2552290001SglebiusThe 2553290001Sglebius@code{sys_var_list} 2554290001Sglebiusholds 2555290001Sglebiusthe names of all system variables. 2556290001SglebiusThe 2557290001Sglebius@code{peer_var_list} 2558290001Sglebiusholds 2559290001Sglebiusthe names of all peer variables and the 2560290001Sglebius@code{clock_var_list} 2561290001Sglebiusholds the names of the reference clock variables. 2562290001Sglebius@item @code{tinker} @code{[@code{allan} @kbd{allan} | @code{dispersion} @kbd{dispersion} | @code{freq} @kbd{freq} | @code{huffpuff} @kbd{huffpuff} | @code{panic} @kbd{panic} | @code{step} @kbd{step} | @code{stepback} @kbd{stepback} | @code{stepfwd} @kbd{stepfwd} | @code{stepout} @kbd{stepout}]} 2563290001SglebiusThis command can be used to alter several system variables in 2564290001Sglebiusvery exceptional circumstances. 2565290001SglebiusIt should occur in the 2566290001Sglebiusconfiguration file before any other configuration options. 2567290001SglebiusThe 2568290001Sglebiusdefault values of these variables have been carefully optimized for 2569290001Sglebiusa wide range of network speeds and reliability expectations. 2570290001SglebiusIn 2571290001Sglebiusgeneral, they interact in intricate ways that are hard to predict 2572290001Sglebiusand some combinations can result in some very nasty behavior. 2573290001SglebiusVery 2574290001Sglebiusrarely is it necessary to change the default values; but, some 2575290001Sglebiusfolks cannot resist twisting the knobs anyway and this command is 2576290001Sglebiusfor them. 2577290001SglebiusEmphasis added: twisters are on their own and can expect 2578290001Sglebiusno help from the support group. 2579290001Sglebius 2580290001SglebiusThe variables operate as follows: 2581290001Sglebius@table @asis 2582290001Sglebius@item @code{allan} @kbd{allan} 2583290001SglebiusThe argument becomes the new value for the minimum Allan 2584290001Sglebiusintercept, which is a parameter of the PLL/FLL clock discipline 2585290001Sglebiusalgorithm. 2586290001SglebiusThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 2587290001Sglebiuslimit. 2588290001Sglebius@item @code{dispersion} @kbd{dispersion} 2589290001SglebiusThe argument becomes the new value for the dispersion increase rate, 2590290001Sglebiusnormally .000015 s/s. 2591290001Sglebius@item @code{freq} @kbd{freq} 2592290001SglebiusThe argument becomes the initial value of the frequency offset in 2593290001Sglebiusparts-per-million. 2594290001SglebiusThis overrides the value in the frequency file, if 2595290001Sglebiuspresent, and avoids the initial training state if it is not. 2596290001Sglebius@item @code{huffpuff} @kbd{huffpuff} 2597290001SglebiusThe argument becomes the new value for the experimental 2598290001Sglebiushuff-n'-puff filter span, which determines the most recent interval 2599290001Sglebiusthe algorithm will search for a minimum delay. 2600290001SglebiusThe lower limit is 2601290001Sglebius900 s (15 m), but a more reasonable value is 7200 (2 hours). 2602290001SglebiusThere 2603290001Sglebiusis no default, since the filter is not enabled unless this command 2604290001Sglebiusis given. 2605290001Sglebius@item @code{panic} @kbd{panic} 2606290001SglebiusThe argument is the panic threshold, normally 1000 s. 2607290001SglebiusIf set to zero, 2608290001Sglebiusthe panic sanity check is disabled and a clock offset of any value will 2609290001Sglebiusbe accepted. 2610290001Sglebius@item @code{step} @kbd{step} 2611290001SglebiusThe argument is the step threshold, which by default is 0.128 s. 2612290001SglebiusIt can 2613290001Sglebiusbe set to any positive number in seconds. 2614290001SglebiusIf set to zero, step 2615290001Sglebiusadjustments will never occur. 2616290001SglebiusNote: The kernel time discipline is 2617290001Sglebiusdisabled if the step threshold is set to zero or greater than the 2618290001Sglebiusdefault. 2619290001Sglebius@item @code{stepback} @kbd{stepback} 2620290001SglebiusThe argument is the step threshold for the backward direction, 2621290001Sglebiuswhich by default is 0.128 s. 2622290001SglebiusIt can 2623290001Sglebiusbe set to any positive number in seconds. 2624290001SglebiusIf both the forward and backward step thresholds are set to zero, step 2625290001Sglebiusadjustments will never occur. 2626290001SglebiusNote: The kernel time discipline is 2627290001Sglebiusdisabled if 2628290001Sglebiuseach direction of step threshold are either 2629290001Sglebiusset to zero or greater than .5 second. 2630290001Sglebius@item @code{stepfwd} @kbd{stepfwd} 2631290001SglebiusAs for stepback, but for the forward direction. 2632290001Sglebius@item @code{stepout} @kbd{stepout} 2633290001SglebiusThe argument is the stepout timeout, which by default is 900 s. 2634290001SglebiusIt can 2635290001Sglebiusbe set to any positive number in seconds. 2636290001SglebiusIf set to zero, the stepout 2637290001Sglebiuspulses will not be suppressed. 2638290001Sglebius@end table 2639290001Sglebius@item @code{rlimit} @code{[@code{memlock} @kbd{Nmegabytes} | @code{stacksize} @kbd{N4kPages} @code{filenum} @kbd{Nfiledescriptors}]} 2640290001Sglebius@table @asis 2641290001Sglebius@item @code{memlock} @kbd{Nmegabytes} 2642290001SglebiusSpecify the number of megabytes of memory that should be 2643290001Sglebiusallocated and locked. 2644290001SglebiusProbably only available under Linux, this option may be useful 2645290001Sglebiuswhen dropping root (the 2646290001Sglebius@code{-i} 2647290001Sglebiusoption). 2648290001SglebiusThe default is 32 megabytes on non-Linux machines, and -1 under Linux. 2649290001Sglebius-1 means "do not lock the process into memory". 2650290001Sglebius0 means "lock whatever memory the process wants into memory". 2651290001Sglebius@item @code{stacksize} @kbd{N4kPages} 2652290001SglebiusSpecifies the maximum size of the process stack on systems with the 2653290001Sglebius@code{mlockall()} 2654290001Sglebiusfunction. 2655290001SglebiusDefaults to 50 4k pages (200 4k pages in OpenBSD). 2656290001Sglebius@item @code{filenum} @kbd{Nfiledescriptors} 2657290001SglebiusSpecifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default. 2658290001Sglebius@end table 2659290001Sglebius@item @code{trap} @kbd{host_address} @code{[@code{port} @kbd{port_number}]} @code{[@code{interface} @kbd{interface_address}]} 2660290001SglebiusThis command configures a trap receiver at the given host 2661290001Sglebiusaddress and port number for sending messages with the specified 2662290001Sglebiuslocal interface address. 2663290001SglebiusIf the port number is unspecified, a value 2664290001Sglebiusof 18447 is used. 2665290001SglebiusIf the interface address is not specified, the 2666290001Sglebiusmessage is sent with a source address of the local interface the 2667290001Sglebiusmessage is sent through. 2668290001SglebiusNote that on a multihomed host the 2669290001Sglebiusinterface used may vary from time to time with routing changes. 2670290001Sglebius 2671290001SglebiusThe trap receiver will generally log event messages and other 2672290001Sglebiusinformation from the server in a log file. 2673290001SglebiusWhile such monitor 2674290001Sglebiusprograms may also request their own trap dynamically, configuring a 2675290001Sglebiustrap receiver will ensure that no messages are lost when the server 2676290001Sglebiusis started. 2677290001Sglebius@item @code{hop} @kbd{...} 2678290001SglebiusThis command specifies a list of TTL values in increasing order, up to 8 2679290001Sglebiusvalues can be specified. 2680290001SglebiusIn manycast mode these values are used in turn in 2681290001Sglebiusan expanding-ring search. 2682290001SglebiusThe default is eight multiples of 32 starting at 2683290001Sglebius31. 2684290001Sglebius@end table 2685290001Sglebius 2686290001SglebiusThis section was generated by @strong{AutoGen}, 2687290001Sglebiususing the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program. 2688290001SglebiusThis software is released under the NTP license, <http://ntp.org/license>. 2689290001Sglebius 2690290001Sglebius@menu 2691290001Sglebius* ntp.conf Files:: Files 2692290001Sglebius* ntp.conf See Also:: See Also 2693290001Sglebius* ntp.conf Bugs:: Bugs 2694290001Sglebius* ntp.conf Notes:: Notes 2695290001Sglebius@end menu 2696290001Sglebius 2697290001Sglebius@node ntp.conf Files 2698290001Sglebius@subsection ntp.conf Files 2699290001Sglebius@table @asis 2700290001Sglebius@item @file{/etc/ntp.conf} 2701290001Sglebiusthe default name of the configuration file 2702290001Sglebius@item @file{ntp.keys} 2703290001Sglebiusprivate MD5 keys 2704290001Sglebius@item @file{ntpkey} 2705290001SglebiusRSA private key 2706290001Sglebius@item @file{ntpkey_}@kbd{host} 2707290001SglebiusRSA public key 2708290001Sglebius@item @file{ntp_dh} 2709290001SglebiusDiffie-Hellman agreement parameters 2710290001Sglebius@end table 2711290001Sglebius@node ntp.conf See Also 2712290001Sglebius@subsection ntp.conf See Also 2713290001Sglebius@code{ntpd(1ntpdmdoc)}, 2714290001Sglebius@code{ntpdc(1ntpdcmdoc)}, 2715290001Sglebius@code{ntpq(1ntpqmdoc)} 2716290001Sglebius 2717290001SglebiusIn addition to the manual pages provided, 2718290001Sglebiuscomprehensive documentation is available on the world wide web 2719290001Sglebiusat 2720290001Sglebius@code{http://www.ntp.org/}. 2721290001SglebiusA snapshot of this documentation is available in HTML format in 2722290001Sglebius@file{/usr/share/doc/ntp}. 2723290001Sglebius@* 2724290001Sglebius 2725290001Sglebius@* 2726290001SglebiusDavid L. Mills, @emph{Network Time Protocol (Version 4)}, RFC5905 2727290001Sglebius@node ntp.conf Bugs 2728290001Sglebius@subsection ntp.conf Bugs 2729290001SglebiusThe syntax checking is not picky; some combinations of 2730290001Sglebiusridiculous and even hilarious options and modes may not be 2731290001Sglebiusdetected. 2732290001Sglebius 2733290001SglebiusThe 2734290001Sglebius@file{ntpkey_}@kbd{host} 2735290001Sglebiusfiles are really digital 2736290001Sglebiuscertificates. 2737290001SglebiusThese should be obtained via secure directory 2738290001Sglebiusservices when they become universally available. 2739290001Sglebius@node ntp.conf Notes 2740290001Sglebius@subsection ntp.conf Notes 2741290001SglebiusThis document was derived from FreeBSD. 2742