invoke-ntp.conf.texi revision 280849
1135446Strhodes@node ntp.conf Notes 2262706Serwin@section Notes about ntp.conf 3135446Strhodes@pindex ntp.conf 4135446Strhodes@cindex Network Time Protocol (NTP) daemon configuration file format 5182645Sdougb@ignore 6135446Strhodes# 7135446Strhodes# EDIT THIS FILE WITH CAUTION (invoke-ntp.conf.texi) 8135446Strhodes# 9135446Strhodes# It has been AutoGen-ed February 4, 2015 at 02:41:59 AM by AutoGen 5.18.5pre4 10135446Strhodes# From the definitions ntp.conf.def 11135446Strhodes# and the template file agtexi-file.tpl 12135446Strhodes@end ignore 13135446Strhodes 14135446Strhodes 15135446Strhodes 16135446StrhodesThe 17135446Strhodes@code{ntp.conf} 18254897Serwinconfiguration file is read at initial startup by the 19135446Strhodes@code{ntpd(1ntpdmdoc)} 20170222Sdougbdaemon in order to specify the synchronization sources, 21170222Sdougbmodes and other related information. 22135446StrhodesUsually, it is installed in the 23135446Strhodes@file{/etc} 24135446Strhodesdirectory, 25135446Strhodesbut could be installed elsewhere 26135446Strhodes(see the daemon's 27135446Strhodes@code{-c} 28135446Strhodescommand line option). 29135446Strhodes 30135446StrhodesThe file format is similar to other 31135446Strhodes@sc{unix} 32135446Strhodesconfiguration files. 33135446StrhodesComments begin with a 34135446Strhodes@quoteleft{}#@quoteright{} 35170222Sdougbcharacter and extend to the end of the line; 36135446Strhodesblank lines are ignored. 37135446StrhodesConfiguration commands consist of an initial keyword 38135446Strhodesfollowed by a list of arguments, 39135446Strhodessome of which may be optional, separated by whitespace. 40135446StrhodesCommands may not be continued over multiple lines. 41135446StrhodesArguments may be host names, 42135446Strhodeshost addresses written in numeric, dotted-quad form, 43135446Strhodesintegers, floating point numbers (when specifying times in seconds) 44135446Strhodesand text strings. 45135446Strhodes 46135446StrhodesThe rest of this page describes the configuration and control options. 47135446StrhodesThe 48135446Strhodes"Notes on Configuring NTP and Setting up an NTP Subnet" 49135446Strhodespage 50135446Strhodes(available as part of the HTML documentation 51135446Strhodesprovided in 52135446Strhodes@file{/usr/share/doc/ntp}) 53135446Strhodescontains an extended discussion of these options. 54135446StrhodesIn addition to the discussion of general 55135446Strhodes@ref{Configuration Options}, 56170222Sdougbthere are sections describing the following supported functionality 57170222Sdougband the options used to control it: 58135446Strhodes@itemize @bullet 59135446Strhodes@item 60135446Strhodes@ref{Authentication Support} 61135446Strhodes@item 62135446Strhodes@ref{Monitoring Support} 63135446Strhodes@item 64186462Sdougb@ref{Access Control Support} 65135446Strhodes@item 66135446Strhodes@ref{Automatic NTP Configuration Options} 67135446Strhodes@item 68135446Strhodes@ref{Reference Clock Support} 69135446Strhodes@item 70135446Strhodes@ref{Miscellaneous Options} 71135446Strhodes@end itemize 72170222Sdougb 73170222SdougbFollowing these is a section describing 74135446Strhodes@ref{Miscellaneous Options}. 75135446StrhodesWhile there is a rich set of options available, 76135446Strhodesthe only required option is one or more 77135446Strhodes@code{pool}, 78135446Strhodes@code{server}, 79135446Strhodes@code{peer}, 80135446Strhodes@code{broadcast} 81135446Strhodesor 82224092Sdougb@code{manycastclient} 83135446Strhodescommands. 84135446Strhodes@node Configuration Support 85135446Strhodes@subsection Configuration Support 86135446StrhodesFollowing is a description of the configuration commands in 87135446StrhodesNTPv4. 88135446StrhodesThese commands have the same basic functions as in NTPv3 and 89135446Strhodesin some cases new functions and new arguments. 90135446StrhodesThere are two 91135446Strhodesclasses of commands, configuration commands that configure a 92135446Strhodespersistent association with a remote server or peer or reference 93224092Sdougbclock, and auxiliary commands that specify environmental variables 94224092Sdougbthat control various related operations. 95224092Sdougb@subsubsection Configuration Commands 96135446StrhodesThe various modes are determined by the command keyword and the 97135446Strhodestype of the required IP address. 98135446StrhodesAddresses are classed by type as 99224092Sdougb(s) a remote server or peer (IPv4 class A, B and C), (b) the 100186462Sdougbbroadcast address of a local interface, (m) a multicast address (IPv4 101135446Strhodesclass D), or (r) a reference clock address (127.127.x.x). 102135446StrhodesNote that 103135446Strhodesonly those options applicable to each command are listed below. 104135446StrhodesUse 105135446Strhodesof options not listed may not be caught as an error, but may result 106135446Strhodesin some weird and even destructive behavior. 107135446Strhodes 108135446StrhodesIf the Basic Socket Interface Extensions for IPv6 (RFC-2553) 109135446Strhodesis detected, support for the IPv6 address family is generated 110135446Strhodesin addition to the default support of the IPv4 address family. 111170222SdougbIn a few cases, including the reslist billboard generated 112135446Strhodesby ntpdc, IPv6 addresses are automatically generated. 113186462SdougbIPv6 addresses can be identified by the presence of colons 114170222Sdougb@quotedblleft{}:@quotedblright{} 115135601Sdesin the address field. 116186462SdougbIPv6 addresses can be used almost everywhere where 117254897SerwinIPv4 addresses can be used, 118254897Serwinwith the exception of reference clock addresses, 119254897Serwinwhich are always IPv4. 120254897Serwin 121254897SerwinNote that in contexts where a host name is expected, a 122170222Sdougb@code{-4} 123170222Sdougbqualifier preceding 124135446Strhodesthe host name forces DNS resolution to the IPv4 namespace, 125224092Sdougbwhile a 126224092Sdougb@code{-6} 127224092Sdougbqualifier forces DNS resolution to the IPv6 namespace. 128224092SdougbSee IPv6 references for the 129135446Strhodesequivalent classes for that address family. 130254897Serwin@table @asis 131254897Serwin@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}]} 132153816Sdougb@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}]} 133153816Sdougb@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}]} 134224092Sdougb@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}]} 135224092Sdougb@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}]} 136135446Strhodes@end table 137135446Strhodes 138135446StrhodesThese five commands specify the time server name or address to 139135446Strhodesbe used and the mode in which to operate. 140135446StrhodesThe 141135446Strhodes@kbd{address} 142135446Strhodescan be 143135446Strhodeseither a DNS name or an IP address in dotted-quad notation. 144135446StrhodesAdditional information on association behavior can be found in the 145135446Strhodes"Association Management" 146135446Strhodespage 147135446Strhodes(available as part of the HTML documentation 148135446Strhodesprovided in 149254897Serwin@file{/usr/share/doc/ntp}). 150254897Serwin@table @asis 151135446Strhodes@item @code{pool} 152135446StrhodesFor type s addresses, this command mobilizes a persistent 153234010Sdougbclient mode association with a number of remote servers. 154234010SdougbIn this mode the local clock can synchronized to the 155234010Sdougbremote server, but the remote server can never be synchronized to 156234010Sdougbthe local clock. 157170222Sdougb@item @code{server} 158170222SdougbFor type s and r addresses, this command mobilizes a persistent 159224092Sdougbclient mode association with the specified remote server or local 160224092Sdougbradio clock. 161224092SdougbIn this mode the local clock can synchronized to the 162224092Sdougbremote server, but the remote server can never be synchronized to 163254897Serwinthe local clock. 164254897SerwinThis command should 165254897Serwin@emph{not} 166254897Serwinbe used for type 167254897Serwinb or m addresses. 168254897Serwin@item @code{peer} 169254897SerwinFor type s addresses (only), this command mobilizes a 170254897Serwinpersistent symmetric-active mode association with the specified 171254897Serwinremote peer. 172254897SerwinIn this mode the local clock can be synchronized to 173254897Serwinthe remote peer or the remote peer can be synchronized to the local 174254897Serwinclock. 175254897SerwinThis is useful in a network of servers where, depending on 176254897Serwinvarious failure scenarios, either the local or remote peer may be 177234010Sdougbthe better source of time. 178135446StrhodesThis command should NOT be used for type 179135446Strhodesb, m or r addresses. 180135446Strhodes@item @code{broadcast} 181135446StrhodesFor type b and m addresses (only), this 182135446Strhodescommand mobilizes a persistent broadcast mode association. 183135446StrhodesMultiple 184135446Strhodescommands can be used to specify multiple local broadcast interfaces 185135446Strhodes(subnets) and/or multiple multicast groups. 186135446StrhodesNote that local 187135446Strhodesbroadcast messages go only to the interface associated with the 188135446Strhodessubnet specified, but multicast messages go to all interfaces. 189170222SdougbIn broadcast mode the local server sends periodic broadcast 190135446Strhodesmessages to a client population at the 191170222Sdougb@kbd{address} 192170222Sdougbspecified, which is usually the broadcast address on (one of) the 193170222Sdougblocal network(s) or a multicast address assigned to NTP. 194170222SdougbThe IANA 195186462Sdougbhas assigned the multicast group address IPv4 224.0.1.1 and 196170222SdougbIPv6 ff05::101 (site local) exclusively to 197170222SdougbNTP, but other nonconflicting addresses can be used to contain the 198170222Sdougbmessages within administrative boundaries. 199170222SdougbOrdinarily, this 200170222Sdougbspecification applies only to the local server operating as a 201170222Sdougbsender; for operation as a broadcast client, see the 202170222Sdougb@code{broadcastclient} 203135446Strhodesor 204135446Strhodes@code{multicastclient} 205135446Strhodescommands 206135446Strhodesbelow. 207135446Strhodes@item @code{manycastclient} 208135446StrhodesFor type m addresses (only), this command mobilizes a 209135446Strhodesmanycast client mode association for the multicast address 210135446Strhodesspecified. 211135446StrhodesIn this case a specific address must be supplied which 212135446Strhodesmatches the address used on the 213135446Strhodes@code{manycastserver} 214135446Strhodescommand for 215135446Strhodesthe designated manycast servers. 216135446StrhodesThe NTP multicast address 217135446Strhodes224.0.1.1 assigned by the IANA should NOT be used, unless specific 218135446Strhodesmeans are taken to avoid spraying large areas of the Internet with 219165071Sdougbthese messages and causing a possibly massive implosion of replies 220165071Sdougbat the sender. 221165071SdougbThe 222165071Sdougb@code{manycastserver} 223165071Sdougbcommand specifies that the local server 224135446Strhodesis to operate in client mode with the remote servers that are 225135446Strhodesdiscovered as the result of broadcast/multicast messages. 226135446StrhodesThe 227135446Strhodesclient broadcasts a request message to the group address associated 228135446Strhodeswith the specified 229135446Strhodes@kbd{address} 230135446Strhodesand specifically enabled 231135446Strhodesservers respond to these messages. 232135446StrhodesThe client selects the servers 233135446Strhodesproviding the best time and continues as with the 234135446Strhodes@code{server} 235135446Strhodescommand. 236135446StrhodesThe remaining servers are discarded as if never 237135446Strhodesheard. 238135446Strhodes@end table 239170222Sdougb 240170222SdougbOptions: 241170222Sdougb@table @asis 242170222Sdougb@item @code{autokey} 243193149SdougbAll packets sent to and received from the server or peer are to 244170222Sdougbinclude authentication fields encrypted using the autokey scheme 245135446Strhodesdescribed in 246135446Strhodes@ref{Authentication Options}. 247135446Strhodes@item @code{burst} 248135446Strhodeswhen the server is reachable, send a burst of eight packets 249135446Strhodesinstead of the usual one. 250135446StrhodesThe packet spacing is normally 2 s; 251135446Strhodeshowever, the spacing between the first and second packets 252135446Strhodescan be changed with the calldelay command to allow 253135446Strhodesadditional time for a modem or ISDN call to complete. 254135446StrhodesThis is designed to improve timekeeping quality 255296611Sdelphijwith the 256296611Sdelphij@code{server} 257135446Strhodescommand and s addresses. 258135446Strhodes@item @code{iburst} 259135446StrhodesWhen the server is unreachable, send a burst of eight packets 260135446Strhodesinstead of the usual one. 261135446StrhodesThe packet spacing is normally 2 s; 262135446Strhodeshowever, the spacing between the first two packets can be 263135446Strhodeschanged with the calldelay command to allow 264135446Strhodesadditional time for a modem or ISDN call to complete. 265135446StrhodesThis is designed to speed the initial synchronization 266135446Strhodesacquisition with the 267135446Strhodes@code{server} 268262706Serwincommand and s addresses and when 269262706Serwin@code{ntpd(1ntpdmdoc)} 270262706Serwinis started with the 271262706Serwin@code{-q} 272135446Strhodesoption. 273135446Strhodes@item @code{key} @kbd{key} 274135446StrhodesAll packets sent to and received from the server or peer are to 275135446Strhodesinclude authentication fields encrypted using the specified 276135446Strhodes@kbd{key} 277165071Sdougbidentifier with values from 1 to 65534, inclusive. 278165071SdougbThe 279165071Sdougbdefault is to include no encryption field. 280165071Sdougb@item @code{minpoll} @kbd{minpoll} 281165071Sdougb@item @code{maxpoll} @kbd{maxpoll} 282135446StrhodesThese options specify the minimum and maximum poll intervals 283135446Strhodesfor NTP messages, as a power of 2 in seconds 284135446StrhodesThe maximum poll 285135446Strhodesinterval defaults to 10 (1,024 s), but can be increased by the 286135446Strhodes@code{maxpoll} 287135446Strhodesoption to an upper limit of 17 (36.4 h). 288135446StrhodesThe 289135446Strhodesminimum poll interval defaults to 6 (64 s), but can be decreased by 290135446Strhodesthe 291135446Strhodes@code{minpoll} 292135446Strhodesoption to a lower limit of 4 (16 s). 293135446Strhodes@item @code{noselect} 294135446StrhodesMarks the server as unused, except for display purposes. 295135446StrhodesThe server is discarded by the selection algroithm. 296135446Strhodes@item @code{prefer} 297135446StrhodesMarks the server as preferred. 298135446StrhodesAll other things being equal, 299135446Strhodesthis host will be chosen for synchronization among a set of 300135446Strhodescorrectly operating hosts. 301135446StrhodesSee the 302135446Strhodes"Mitigation Rules and the prefer Keyword" 303170222Sdougbpage 304170222Sdougb(available as part of the HTML documentation 305170222Sdougbprovided in 306170222Sdougb@file{/usr/share/doc/ntp}) 307193149Sdougbfor further information. 308170222Sdougb@item @code{ttl} @kbd{ttl} 309135446StrhodesThis option is used only with broadcast server and manycast 310135446Strhodesclient modes. 311135446StrhodesIt specifies the time-to-live 312135446Strhodes@kbd{ttl} 313135446Strhodesto 314135446Strhodesuse on broadcast server and multicast server and the maximum 315135446Strhodes@kbd{ttl} 316135446Strhodesfor the expanding ring search with manycast 317135446Strhodesclient packets. 318135446StrhodesSelection of the proper value, which defaults to 319296611Sdelphij127, is something of a black art and should be coordinated with the 320296611Sdelphijnetwork administrator. 321135446Strhodes@item @code{version} @kbd{version} 322135446StrhodesSpecifies the version number to be used for outgoing NTP 323135446Strhodespackets. 324135446StrhodesVersions 1-4 are the choices, with version 4 the 325135446Strhodesdefault. 326135446Strhodes@end table 327135446Strhodes@subsubsection Auxiliary Commands 328135446Strhodes@table @asis 329135446Strhodes@item @code{broadcastclient} 330135446StrhodesThis command enables reception of broadcast server messages to 331135446Strhodesany local interface (type b) address. 332135446StrhodesUpon receiving a message for 333135446Strhodesthe first time, the broadcast client measures the nominal server 334135446Strhodespropagation delay using a brief client/server exchange with the 335135446Strhodesserver, then enters the broadcast client mode, in which it 336135446Strhodessynchronizes to succeeding broadcast messages. 337135446StrhodesNote that, in order 338135446Strhodesto avoid accidental or malicious disruption in this mode, both the 339135446Strhodesserver and client should operate using symmetric-key or public-key 340135446Strhodesauthentication as described in 341135446Strhodes@ref{Authentication Options}. 342135446Strhodes@item @code{manycastserver} @kbd{address} @kbd{...} 343135446StrhodesThis command enables reception of manycast client messages to 344135446Strhodesthe multicast group address(es) (type m) specified. 345135446StrhodesAt least one 346135446Strhodesaddress is required, but the NTP multicast address 224.0.1.1 347135446Strhodesassigned by the IANA should NOT be used, unless specific means are 348135446Strhodestaken to limit the span of the reply and avoid a possibly massive 349135446Strhodesimplosion at the original sender. 350135446StrhodesNote that, in order to avoid 351135446Strhodesaccidental or malicious disruption in this mode, both the server 352135446Strhodesand client should operate using symmetric-key or public-key 353135446Strhodesauthentication as described in 354135446Strhodes@ref{Authentication Options}. 355135446Strhodes@item @code{multicastclient} @kbd{address} @kbd{...} 356135446StrhodesThis command enables reception of multicast server messages to 357135446Strhodesthe multicast group address(es) (type m) specified. 358135446StrhodesUpon receiving 359135446Strhodesa message for the first time, the multicast client measures the 360135446Strhodesnominal server propagation delay using a brief client/server 361135446Strhodesexchange with the server, then enters the broadcast client mode, in 362135446Strhodeswhich it synchronizes to succeeding multicast messages. 363135446StrhodesNote that, 364135446Strhodesin order to avoid accidental or malicious disruption in this mode, 365165071Sdougbboth the server and client should operate using symmetric-key or 366135446Strhodespublic-key authentication as described in 367135446Strhodes@ref{Authentication Options}. 368135446Strhodes@item @code{mdnstries} @kbd{number} 369135446StrhodesIf we are participating in mDNS, 370135446Strhodesafter we have synched for the first time 371135446Strhodeswe attempt to register with the mDNS system. 372135446StrhodesIf that registration attempt fails, 373135446Strhodeswe try again at one minute intervals for up to 374135446Strhodes@code{mdnstries} 375135446Strhodestimes. 376135446StrhodesAfter all, 377135446Strhodes@code{ntpd} 378135446Strhodesmay be starting before mDNS. 379165071SdougbThe default value for 380165071Sdougb@code{mdnstries} 381135446Strhodesis 5. 382165071Sdougb@end table 383135446Strhodes@node Authentication Support 384165071Sdougb@subsection Authentication Support 385135446StrhodesAuthentication support allows the NTP client to verify that the 386135446Strhodesserver is in fact known and trusted and not an intruder intending 387135446Strhodesaccidentally or on purpose to masquerade as that server. 388165071SdougbThe NTPv3 389135446Strhodesspecification RFC-1305 defines a scheme which provides 390135446Strhodescryptographic authentication of received NTP packets. 391165071SdougbOriginally, 392135446Strhodesthis was done using the Data Encryption Standard (DES) algorithm 393135446Strhodesoperating in Cipher Block Chaining (CBC) mode, commonly called 394135446StrhodesDES-CBC. 395135446StrhodesSubsequently, this was replaced by the RSA Message Digest 396135446Strhodes5 (MD5) algorithm using a private key, commonly called keyed-MD5. 397135446StrhodesEither algorithm computes a message digest, or one-way hash, which 398135446Strhodescan be used to verify the server has the correct private key and 399135446Strhodeskey identifier. 400135446Strhodes 401135446StrhodesNTPv4 retains the NTPv3 scheme, properly described as symmetric key 402135446Strhodescryptography and, in addition, provides a new Autokey scheme 403135446Strhodesbased on public key cryptography. 404135446StrhodesPublic key cryptography is generally considered more secure 405135446Strhodesthan symmetric key cryptography, since the security is based 406135446Strhodeson a private value which is generated by each server and 407135446Strhodesnever revealed. 408135446StrhodesWith Autokey all key distribution and 409135446Strhodesmanagement functions involve only public values, which 410135446Strhodesconsiderably simplifies key distribution and storage. 411135446StrhodesPublic key management is based on X.509 certificates, 412135446Strhodeswhich can be provided by commercial services or 413193149Sdougbproduced by utility programs in the OpenSSL software library 414135446Strhodesor the NTPv4 distribution. 415135446Strhodes 416135446StrhodesWhile the algorithms for symmetric key cryptography are 417135446Strhodesincluded in the NTPv4 distribution, public key cryptography 418135446Strhodesrequires the OpenSSL software library to be installed 419135446Strhodesbefore building the NTP distribution. 420135446StrhodesDirections for doing that 421135446Strhodesare on the Building and Installing the Distribution page. 422135446Strhodes 423135446StrhodesAuthentication is configured separately for each association 424135446Strhodesusing the 425135446Strhodes@code{key} 426135446Strhodesor 427170222Sdougb@code{autokey} 428170222Sdougbsubcommand on the 429135446Strhodes@code{peer}, 430135446Strhodes@code{server}, 431135446Strhodes@code{broadcast} 432135446Strhodesand 433135446Strhodes@code{manycastclient} 434135446Strhodesconfiguration commands as described in 435135446Strhodes@ref{Configuration Options} 436170222Sdougbpage. 437170222SdougbThe authentication 438170222Sdougboptions described below specify the locations of the key files, 439170222Sdougbif other than default, which symmetric keys are trusted 440170222Sdougband the interval between various operations, if other than default. 441170222Sdougb 442170222SdougbAuthentication is always enabled, 443170222Sdougbalthough ineffective if not configured as 444182645Sdougbdescribed below. 445170222SdougbIf a NTP packet arrives 446170222Sdougbincluding a message authentication 447182645Sdougbcode (MAC), it is accepted only if it 448170222Sdougbpasses all cryptographic checks. 449170222SdougbThe 450170222Sdougbchecks require correct key ID, key value 451170222Sdougband message digest. 452135446StrhodesIf the packet has 453135446Strhodesbeen modified in any way or replayed 454135446Strhodesby an intruder, it will fail one or more 455135446Strhodesof these checks and be discarded. 456135446StrhodesFurthermore, the Autokey scheme requires a 457135446Strhodespreliminary protocol exchange to obtain 458135446Strhodesthe server certificate, verify its 459135446Strhodescredentials and initialize the protocol 460135446Strhodes 461135446StrhodesThe 462165071Sdougb@code{auth} 463135446Strhodesflag controls whether new associations or 464135446Strhodesremote configuration commands require cryptographic authentication. 465135446StrhodesThis flag can be set or reset by the 466135446Strhodes@code{enable} 467135446Strhodesand 468135446Strhodes@code{disable} 469135446Strhodescommands and also by remote 470135446Strhodesconfiguration commands sent by a 471170222Sdougb@code{ntpdc(1ntpdcmdoc)} 472165071Sdougbprogram running in 473165071Sdougbanother machine. 474165071SdougbIf this flag is enabled, which is the default 475165071Sdougbcase, new broadcast client and symmetric passive associations and 476165071Sdougbremote configuration commands must be cryptographically 477165071Sdougbauthenticated using either symmetric key or public key cryptography. 478165071SdougbIf this 479165071Sdougbflag is disabled, these operations are effective 480165071Sdougbeven if not cryptographic 481135446Strhodesauthenticated. 482170222SdougbIt should be understood 483165071Sdougbthat operating with the 484135446Strhodes@code{auth} 485135446Strhodesflag disabled invites a significant vulnerability 486135446Strhodeswhere a rogue hacker can 487135446Strhodesmasquerade as a falseticker and seriously 488135446Strhodesdisrupt system timekeeping. 489170222SdougbIt is 490135446Strhodesimportant to note that this flag has no purpose 491135446Strhodesother than to allow or disallow 492135446Strhodesa new association in response to new broadcast 493135446Strhodesand symmetric active messages 494135446Strhodesand remote configuration commands and, in particular, 495262706Serwinthe flag has no effect on 496262706Serwinthe authentication process itself. 497262706Serwin 498135446StrhodesAn attractive alternative where multicast support is available 499135446Strhodesis manycast mode, in which clients periodically troll 500135446Strhodesfor servers as described in the 501135446Strhodes@ref{Automatic NTP Configuration Options} 502224092Sdougbpage. 503224092SdougbEither symmetric key or public key 504224092Sdougbcryptographic authentication can be used in this mode. 505224092SdougbThe principle advantage 506135446Strhodesof manycast mode is that potential servers need not be 507135446Strhodesconfigured in advance, 508135446Strhodessince the client finds them during regular operation, 509135446Strhodesand the configuration 510135446Strhodesfiles for all clients can be identical. 511135446Strhodes 512135446StrhodesThe security model and protocol schemes for 513135446Strhodesboth symmetric key and public key 514135446Strhodescryptography are summarized below; 515135446Strhodesfurther details are in the briefings, papers 516135446Strhodesand reports at the NTP project page linked from 517135446Strhodes@code{http://www.ntp.org/}. 518135446Strhodes@subsubsection Symmetric-Key Cryptography 519135446StrhodesThe original RFC-1305 specification allows any one of possibly 520135446Strhodes65,534 keys, each distinguished by a 32-bit key identifier, to 521135446Strhodesauthenticate an association. 522135446StrhodesThe servers and clients involved must 523165071Sdougbagree on the key and key identifier to 524135446Strhodesauthenticate NTP packets. 525135446StrhodesKeys and 526135446Strhodesrelated information are specified in a key 527135446Strhodesfile, usually called 528135446Strhodes@file{ntp.keys}, 529135446Strhodeswhich must be distributed and stored using 530135446Strhodessecure means beyond the scope of the NTP protocol itself. 531135446StrhodesBesides the keys used 532135446Strhodesfor ordinary NTP associations, 533135446Strhodesadditional keys can be used as passwords for the 534135446Strhodes@code{ntpq(1ntpqmdoc)} 535135446Strhodesand 536186462Sdougb@code{ntpdc(1ntpdcmdoc)} 537135446Strhodesutility programs. 538135446Strhodes 539135446StrhodesWhen 540135446Strhodes@code{ntpd(1ntpdmdoc)} 541135446Strhodesis first started, it reads the key file specified in the 542135446Strhodes@code{keys} 543135446Strhodesconfiguration command and installs the keys 544135446Strhodesin the key cache. 545135446StrhodesHowever, 546135446Strhodesindividual keys must be activated with the 547135446Strhodes@code{trusted} 548135446Strhodescommand before use. 549135446StrhodesThis 550135446Strhodesallows, for instance, the installation of possibly 551135446Strhodesseveral batches of keys and 552135446Strhodesthen activating or deactivating each batch 553135446Strhodesremotely using 554135446Strhodes@code{ntpdc(1ntpdcmdoc)}. 555135446StrhodesThis also provides a revocation capability that can be used 556135446Strhodesif a key becomes compromised. 557135446StrhodesThe 558135446Strhodes@code{requestkey} 559135446Strhodescommand selects the key used as the password for the 560135446Strhodes@code{ntpdc(1ntpdcmdoc)} 561135446Strhodesutility, while the 562135446Strhodes@code{controlkey} 563135446Strhodescommand selects the key used as the password for the 564135446Strhodes@code{ntpq(1ntpqmdoc)} 565135446Strhodesutility. 566135446Strhodes@subsubsection Public Key Cryptography 567135446StrhodesNTPv4 supports the original NTPv3 symmetric key scheme 568135446Strhodesdescribed in RFC-1305 and in addition the Autokey protocol, 569135446Strhodeswhich is based on public key cryptography. 570135446StrhodesThe Autokey Version 2 protocol described on the Autokey Protocol 571135446Strhodespage verifies packet integrity using MD5 message digests 572186462Sdougband verifies the source with digital signatures and any of several 573135446Strhodesdigest/signature schemes. 574135446StrhodesOptional identity schemes described on the Identity Schemes 575135446Strhodespage and based on cryptographic challenge/response algorithms 576135446Strhodesare also available. 577135446StrhodesUsing all of these schemes provides strong security against 578135446Strhodesreplay with or without modification, spoofing, masquerade 579135446Strhodesand most forms of clogging attacks. 580135446Strhodes 581135446StrhodesThe Autokey protocol has several modes of operation 582135446Strhodescorresponding to the various NTP modes supported. 583135446StrhodesMost modes use a special cookie which can be 584135446Strhodescomputed independently by the client and server, 585135446Strhodesbut encrypted in transmission. 586135446StrhodesAll modes use in addition a variant of the S-KEY scheme, 587135446Strhodesin which a pseudo-random key list is generated and used 588135446Strhodesin reverse order. 589135446StrhodesThese schemes are described along with an executive summary, 590135446Strhodescurrent status, briefing slides and reading list on the 591135446Strhodes@ref{Autonomous Authentication} 592135446Strhodespage. 593135446Strhodes 594135446StrhodesThe specific cryptographic environment used by Autokey servers 595135446Strhodesand clients is determined by a set of files 596135446Strhodesand soft links generated by the 597135446Strhodes@code{ntp-keygen(1ntpkeygenmdoc)} 598135446Strhodesprogram. 599135446StrhodesThis includes a required host key file, 600135446Strhodesrequired certificate file and optional sign key file, 601135446Strhodesleapsecond file and identity scheme files. 602135446StrhodesThe 603135446Strhodesdigest/signature scheme is specified in the X.509 certificate 604135446Strhodesalong with the matching sign key. 605135446StrhodesThere are several schemes 606135446Strhodesavailable in the OpenSSL software library, each identified 607135446Strhodesby a specific string such as 608135446Strhodes@code{md5WithRSAEncryption}, 609135446Strhodeswhich stands for the MD5 message digest with RSA 610135446Strhodesencryption scheme. 611135446StrhodesThe current NTP distribution supports 612135446Strhodesall the schemes in the OpenSSL library, including 613135446Strhodesthose based on RSA and DSA digital signatures. 614170222Sdougb 615135446StrhodesNTP secure groups can be used to define cryptographic compartments 616135446Strhodesand security hierarchies. 617135446StrhodesIt is important that every host 618170222Sdougbin the group be able to construct a certificate trail to one 619170222Sdougbor more trusted hosts in the same group. 620170222SdougbEach group 621170222Sdougbhost runs the Autokey protocol to obtain the certificates 622170222Sdougbfor all hosts along the trail to one or more trusted hosts. 623170222SdougbThis requires the configuration file in all hosts to be 624170222Sdougbengineered so that, even under anticipated failure conditions, 625170222Sdougbthe NTP subnet will form such that every group host can find 626170222Sdougba trail to at least one trusted host. 627170222Sdougb@subsubsection Naming and Addressing 628170222SdougbIt is important to note that Autokey does not use DNS to 629170222Sdougbresolve addresses, since DNS can't be completely trusted 630170222Sdougbuntil the name servers have synchronized clocks. 631170222SdougbThe cryptographic name used by Autokey to bind the host identity 632170222Sdougbcredentials and cryptographic values must be independent 633170222Sdougbof interface, network and any other naming convention. 634170222SdougbThe name appears in the host certificate in either or both 635170222Sdougbthe subject and issuer fields, so protection against 636170222SdougbDNS compromise is essential. 637170222Sdougb 638170222SdougbBy convention, the name of an Autokey host is the name returned 639170222Sdougbby the Unix 640170222Sdougb@code{gethostname(2)} 641170222Sdougbsystem call or equivalent in other systems. 642170222SdougbBy the system design 643170222Sdougbmodel, there are no provisions to allow alternate names or aliases. 644170222SdougbHowever, this is not to say that DNS aliases, different names 645170222Sdougbfor each interface, etc., are constrained in any way. 646170222Sdougb 647170222SdougbIt is also important to note that Autokey verifies authenticity 648170222Sdougbusing the host name, network address and public keys, 649170222Sdougball of which are bound together by the protocol specifically 650186462Sdougbto deflect masquerade attacks. 651170222SdougbFor this reason Autokey 652170222Sdougbincludes the source and destinatino IP addresses in message digest 653170222Sdougbcomputations and so the same addresses must be available 654170222Sdougbat both the server and client. 655170222SdougbFor this reason operation 656170222Sdougbwith network address translation schemes is not possible. 657170222SdougbThis reflects the intended robust security model where government 658170222Sdougband corporate NTP servers are operated outside firewall perimeters. 659170222Sdougb@subsubsection Operation 660170222SdougbA specific combination of authentication scheme (none, 661170222Sdougbsymmetric key, public key) and identity scheme is called 662170222Sdougba cryptotype, although not all combinations are compatible. 663170222SdougbThere may be management configurations where the clients, 664170222Sdougbservers and peers may not all support the same cryptotypes. 665170222SdougbA secure NTPv4 subnet can be configured in many ways while 666170222Sdougbkeeping in mind the principles explained above and 667170222Sdougbin this section. 668170222SdougbNote however that some cryptotype 669170222Sdougbcombinations may successfully interoperate with each other, 670170222Sdougbbut may not represent good security practice. 671170222Sdougb 672170222SdougbThe cryptotype of an association is determined at the time 673170222Sdougbof mobilization, either at configuration time or some time 674170222Sdougblater when a message of appropriate cryptotype arrives. 675170222SdougbWhen mobilized by a 676170222Sdougb@code{server} 677170222Sdougbor 678170222Sdougb@code{peer} 679170222Sdougbconfiguration command and no 680170222Sdougb@code{key} 681170222Sdougbor 682170222Sdougb@code{autokey} 683170222Sdougbsubcommands are present, the association is not 684170222Sdougbauthenticated; if the 685170222Sdougb@code{key} 686170222Sdougbsubcommand is present, the association is authenticated 687170222Sdougbusing the symmetric key ID specified; if the 688170222Sdougb@code{autokey} 689170222Sdougbsubcommand is present, the association is authenticated 690170222Sdougbusing Autokey. 691170222Sdougb 692170222SdougbWhen multiple identity schemes are supported in the Autokey 693170222Sdougbprotocol, the first message exchange determines which one is used. 694170222SdougbThe client request message contains bits corresponding 695170222Sdougbto which schemes it has available. 696170222SdougbThe server response message 697170222Sdougbcontains bits corresponding to which schemes it has available. 698170222SdougbBoth server and client match the received bits with their own 699170222Sdougband select a common scheme. 700170222Sdougb 701170222SdougbFollowing the principle that time is a public value, 702170222Sdougba server responds to any client packet that matches 703170222Sdougbits cryptotype capabilities. 704135446StrhodesThus, a server receiving 705135446Strhodesan unauthenticated packet will respond with an unauthenticated 706135446Strhodespacket, while the same server receiving a packet of a cryptotype 707135446Strhodesit supports will respond with packets of that cryptotype. 708135446StrhodesHowever, unconfigured broadcast or manycast client 709135446Strhodesassociations or symmetric passive associations will not be 710135446Strhodesmobilized unless the server supports a cryptotype compatible 711135446Strhodeswith the first packet received. 712135446StrhodesBy default, unauthenticated associations will not be mobilized 713135446Strhodesunless overridden in a decidedly dangerous way. 714135446Strhodes 715135446StrhodesSome examples may help to reduce confusion. 716135446StrhodesClient Alice has no specific cryptotype selected. 717135446StrhodesServer Bob has both a symmetric key file and minimal Autokey files. 718135446StrhodesAlice's unauthenticated messages arrive at Bob, who replies with 719170222Sdougbunauthenticated messages. 720170222SdougbCathy has a copy of Bob's symmetric 721135446Strhodeskey file and has selected key ID 4 in messages to Bob. 722135446StrhodesBob verifies the message with his key ID 4. 723135446StrhodesIf it's the 724135446Strhodessame key and the message is verified, Bob sends Cathy a reply 725135446Strhodesauthenticated with that key. 726135446StrhodesIf verification fails, 727135446StrhodesBob sends Cathy a thing called a crypto-NAK, which tells her 728262706Serwinsomething broke. 729135446StrhodesShe can see the evidence using the 730135446Strhodes@code{ntpq(1ntpqmdoc)} 731135446Strhodesprogram. 732135446Strhodes 733135446StrhodesDenise has rolled her own host key and certificate. 734170222SdougbShe also uses one of the identity schemes as Bob. 735170222SdougbShe sends the first Autokey message to Bob and they 736170222Sdougbboth dance the protocol authentication and identity steps. 737135446StrhodesIf all comes out okay, Denise and Bob continue as described above. 738135446Strhodes 739135446StrhodesIt should be clear from the above that Bob can support 740135446Strhodesall the girls at the same time, as long as he has compatible 741193149Sdougbauthentication and identity credentials. 742193149SdougbNow, Bob can act just like the girls in his own choice of servers; 743193149Sdougbhe can run multiple configured associations with multiple different 744135446Strhodesservers (or the same server, although that might not be useful). 745135446StrhodesBut, wise security policy might preclude some cryptotype 746170222Sdougbcombinations; for instance, running an identity scheme 747170222Sdougbwith one server and no authentication with another might not be wise. 748170222Sdougb@subsubsection Key Management 749170222SdougbThe cryptographic values used by the Autokey protocol are 750170222Sdougbincorporated as a set of files generated by the 751170222Sdougb@code{ntp-keygen(1ntpkeygenmdoc)} 752170222Sdougbutility program, including symmetric key, host key and 753170222Sdougbpublic certificate files, as well as sign key, identity parameters 754170222Sdougband leapseconds files. 755170222SdougbAlternatively, host and sign keys and 756170222Sdougbcertificate files can be generated by the OpenSSL utilities 757170222Sdougband certificates can be imported from public certificate 758135446Strhodesauthorities. 759135446StrhodesNote that symmetric keys are necessary for the 760224092Sdougb@code{ntpq(1ntpqmdoc)} 761135446Strhodesand 762135446Strhodes@code{ntpdc(1ntpdcmdoc)} 763135446Strhodesutility programs. 764135446StrhodesThe remaining files are necessary only for the 765135446StrhodesAutokey protocol. 766135446Strhodes 767135446StrhodesCertificates imported from OpenSSL or public certificate 768135446Strhodesauthorities have certian limitations. 769135446StrhodesThe certificate should be in ASN.1 syntax, X.509 Version 3 770135446Strhodesformat and encoded in PEM, which is the same format 771135446Strhodesused by OpenSSL. 772135446StrhodesThe overall length of the certificate encoded 773135446Strhodesin ASN.1 must not exceed 1024 bytes. 774135446StrhodesThe subject distinguished 775135446Strhodesname field (CN) is the fully qualified name of the host 776135446Strhodeson which it is used; the remaining subject fields are ignored. 777135446StrhodesThe certificate extension fields must not contain either 778135446Strhodesa subject key identifier or a issuer key identifier field; 779135446Strhodeshowever, an extended key usage field for a trusted host must 780135446Strhodescontain the value 781135446Strhodes@code{trustRoot};. 782135446StrhodesOther extension fields are ignored. 783135446Strhodes@subsubsection Authentication Commands 784135446Strhodes@table @asis 785170222Sdougb@item @code{autokey} @code{[@kbd{logsec}]} 786135446StrhodesSpecifies the interval between regenerations of the session key 787135446Strhodeslist used with the Autokey protocol. 788135446StrhodesNote that the size of the key 789170222Sdougblist for each association depends on this interval and the current 790135446Strhodespoll interval. 791135446StrhodesThe default value is 12 (4096 s or about 1.1 hours). 792135446StrhodesFor poll intervals above the specified interval, a session key list 793186462Sdougbwith a single entry will be regenerated for every message 794135446Strhodessent. 795193149Sdougb@item @code{controlkey} @kbd{key} 796193149SdougbSpecifies the key identifier to use with the 797193149Sdougb@code{ntpq(1ntpqmdoc)} 798193149Sdougbutility, which uses the standard 799193149Sdougbprotocol defined in RFC-1305. 800254402SerwinThe 801193149Sdougb@kbd{key} 802135446Strhodesargument is 803135446Strhodesthe key identifier for a trusted key, where the value can be in the 804135446Strhodesrange 1 to 65,534, inclusive. 805193149Sdougb@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}]} 806193149SdougbThis command requires the OpenSSL library. 807193149SdougbIt activates public key 808135446Strhodescryptography, selects the message digest and signature 809135446Strhodesencryption scheme and loads the required private and public 810135446Strhodesvalues described above. 811135446StrhodesIf one or more files are left unspecified, 812135446Strhodesthe default names are used as described above. 813135446StrhodesUnless the complete path and name of the file are specified, the 814135446Strhodeslocation of a file is relative to the keys directory specified 815135446Strhodesin the 816135446Strhodes@code{keysdir} 817135446Strhodescommand or default 818135446Strhodes@file{/usr/local/etc}. 819135446StrhodesFollowing are the subcommands: 820135446Strhodes@table @asis 821135446Strhodes@item @code{cert} @kbd{file} 822135446StrhodesSpecifies the location of the required host public certificate file. 823135446StrhodesThis overrides the link 824135446Strhodes@file{ntpkey_cert_}@kbd{hostname} 825135446Strhodesin the keys directory. 826135446Strhodes@item @code{gqpar} @kbd{file} 827135446StrhodesSpecifies the location of the optional GQ parameters file. 828135446StrhodesThis 829135446Strhodesoverrides the link 830135446Strhodes@file{ntpkey_gq_}@kbd{hostname} 831135446Strhodesin the keys directory. 832135446Strhodes@item @code{host} @kbd{file} 833186462SdougbSpecifies the location of the required host key file. 834135446StrhodesThis overrides 835135446Strhodesthe link 836135446Strhodes@file{ntpkey_key_}@kbd{hostname} 837135446Strhodesin the keys directory. 838135446Strhodes@item @code{iffpar} @kbd{file} 839135446StrhodesSpecifies the location of the optional IFF parameters file.This 840135446Strhodesoverrides the link 841135446Strhodes@file{ntpkey_iff_}@kbd{hostname} 842135446Strhodesin the keys directory. 843135446Strhodes@item @code{leap} @kbd{file} 844135446StrhodesSpecifies the location of the optional leapsecond file. 845135446StrhodesThis overrides the link 846135446Strhodes@file{ntpkey_leap} 847135446Strhodesin the keys directory. 848135446Strhodes@item @code{mvpar} @kbd{file} 849135446StrhodesSpecifies the location of the optional MV parameters file. 850135446StrhodesThis 851135446Strhodesoverrides the link 852135446Strhodes@file{ntpkey_mv_}@kbd{hostname} 853135446Strhodesin the keys directory. 854135446Strhodes@item @code{pw} @kbd{password} 855135446StrhodesSpecifies the password to decrypt files containing private keys and 856135446Strhodesidentity parameters. 857135446StrhodesThis is required only if these files have been 858135446Strhodesencrypted. 859135446Strhodes@item @code{randfile} @kbd{file} 860262706SerwinSpecifies the location of the random seed file used by the OpenSSL 861135446Strhodeslibrary. 862135446StrhodesThe defaults are described in the main text above. 863135446Strhodes@item @code{sign} @kbd{file} 864135446StrhodesSpecifies the location of the optional sign key file. 865135446StrhodesThis overrides 866135446Strhodesthe link 867135446Strhodes@file{ntpkey_sign_}@kbd{hostname} 868135446Strhodesin the keys directory. 869135446StrhodesIf this file is 870135446Strhodesnot found, the host key is also the sign key. 871135446Strhodes@end table 872135446Strhodes@item @code{keys} @kbd{keyfile} 873135446StrhodesSpecifies the complete path and location of the MD5 key file 874170222Sdougbcontaining the keys and key identifiers used by 875170222Sdougb@code{ntpd(1ntpdmdoc)}, 876170222Sdougb@code{ntpq(1ntpqmdoc)} 877135446Strhodesand 878135446Strhodes@code{ntpdc(1ntpdcmdoc)} 879135446Strhodeswhen operating with symmetric key cryptography. 880135446StrhodesThis is the same operation as the 881135446Strhodes@code{-k} 882135446Strhodescommand line option. 883135446Strhodes@item @code{keysdir} @kbd{path} 884135446StrhodesThis command specifies the default directory path for 885135446Strhodescryptographic keys, parameters and certificates. 886135446StrhodesThe default is 887135446Strhodes@file{/usr/local/etc/}. 888135446Strhodes@item @code{requestkey} @kbd{key} 889135446StrhodesSpecifies the key identifier to use with the 890135446Strhodes@code{ntpdc(1ntpdcmdoc)} 891135446Strhodesutility program, which uses a 892135446Strhodesproprietary protocol specific to this implementation of 893135446Strhodes@code{ntpd(1ntpdmdoc)}. 894135446StrhodesThe 895135446Strhodes@kbd{key} 896135446Strhodesargument is a key identifier 897135446Strhodesfor the trusted key, where the value can be in the range 1 to 898170222Sdougb65,534, inclusive. 899170222Sdougb@item @code{revoke} @kbd{logsec} 900135446StrhodesSpecifies the interval between re-randomization of certain 901135446Strhodescryptographic values used by the Autokey scheme, as a power of 2 in 902135446Strhodesseconds. 903135446StrhodesThese values need to be updated frequently in order to 904135446Strhodesdeflect brute-force attacks on the algorithms of the scheme; 905135446Strhodeshowever, updating some values is a relatively expensive operation. 906135446StrhodesThe default interval is 16 (65,536 s or about 18 hours). 907135446StrhodesFor poll 908135446Strhodesintervals above the specified interval, the values will be updated 909135446Strhodesfor every message sent. 910@item @code{trustedkey} @kbd{key} @kbd{...} 911Specifies the key identifiers which are trusted for the 912purposes of authenticating peers with symmetric key cryptography, 913as well as keys used by the 914@code{ntpq(1ntpqmdoc)} 915and 916@code{ntpdc(1ntpdcmdoc)} 917programs. 918The authentication procedures require that both the local 919and remote servers share the same key and key identifier for this 920purpose, although different keys can be used with different 921servers. 922The 923@kbd{key} 924arguments are 32-bit unsigned 925integers with values from 1 to 65,534. 926@end table 927@subsubsection Error Codes 928The following error codes are reported via the NTP control 929and monitoring protocol trap mechanism. 930@table @asis 931@item 101 932(bad field format or length) 933The packet has invalid version, length or format. 934@item 102 935(bad timestamp) 936The packet timestamp is the same or older than the most recent received. 937This could be due to a replay or a server clock time step. 938@item 103 939(bad filestamp) 940The packet filestamp is the same or older than the most recent received. 941This could be due to a replay or a key file generation error. 942@item 104 943(bad or missing public key) 944The public key is missing, has incorrect format or is an unsupported type. 945@item 105 946(unsupported digest type) 947The server requires an unsupported digest/signature scheme. 948@item 106 949(mismatched digest types) 950Not used. 951@item 107 952(bad signature length) 953The signature length does not match the current public key. 954@item 108 955(signature not verified) 956The message fails the signature check. 957It could be bogus or signed by a 958different private key. 959@item 109 960(certificate not verified) 961The certificate is invalid or signed with the wrong key. 962@item 110 963(certificate not verified) 964The certificate is not yet valid or has expired or the signature could not 965be verified. 966@item 111 967(bad or missing cookie) 968The cookie is missing, corrupted or bogus. 969@item 112 970(bad or missing leapseconds table) 971The leapseconds table is missing, corrupted or bogus. 972@item 113 973(bad or missing certificate) 974The certificate is missing, corrupted or bogus. 975@item 114 976(bad or missing identity) 977The identity key is missing, corrupt or bogus. 978@end table 979@node Monitoring Support 980@subsection Monitoring Support 981@code{ntpd(1ntpdmdoc)} 982includes a comprehensive monitoring facility suitable 983for continuous, long term recording of server and client 984timekeeping performance. 985See the 986@code{statistics} 987command below 988for a listing and example of each type of statistics currently 989supported. 990Statistic files are managed using file generation sets 991and scripts in the 992@file{./scripts} 993directory of this distribution. 994Using 995these facilities and 996@sc{unix} 997@code{cron(8)} 998jobs, the data can be 999automatically summarized and archived for retrospective analysis. 1000@subsubsection Monitoring Commands 1001@table @asis 1002@item @code{statistics} @kbd{name} @kbd{...} 1003Enables writing of statistics records. 1004Currently, eight kinds of 1005@kbd{name} 1006statistics are supported. 1007@table @asis 1008@item @code{clockstats} 1009Enables recording of clock driver statistics information. 1010Each update 1011received from a clock driver appends a line of the following form to 1012the file generation set named 1013@code{clockstats}: 1014@verbatim 101549213 525.624 127.127.4.1 93 226 00:08:29.606 D 1016@end verbatim 1017 1018The first two fields show the date (Modified Julian Day) and time 1019(seconds and fraction past UTC midnight). 1020The next field shows the 1021clock address in dotted-quad notation. 1022The final field shows the last 1023timecode received from the clock in decoded ASCII format, where 1024meaningful. 1025In some clock drivers a good deal of additional information 1026can be gathered and displayed as well. 1027See information specific to each 1028clock for further details. 1029@item @code{cryptostats} 1030This option requires the OpenSSL cryptographic software library. 1031It 1032enables recording of cryptographic public key protocol information. 1033Each message received by the protocol module appends a line of the 1034following form to the file generation set named 1035@code{cryptostats}: 1036@verbatim 103749213 525.624 127.127.4.1 message 1038@end verbatim 1039 1040The first two fields show the date (Modified Julian Day) and time 1041(seconds and fraction past UTC midnight). 1042The next field shows the peer 1043address in dotted-quad notation, The final message field includes the 1044message type and certain ancillary information. 1045See the 1046@ref{Authentication Options} 1047section for further information. 1048@item @code{loopstats} 1049Enables recording of loop filter statistics information. 1050Each 1051update of the local clock outputs a line of the following form to 1052the file generation set named 1053@code{loopstats}: 1054@verbatim 105550935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 1056@end verbatim 1057 1058The first two fields show the date (Modified Julian Day) and 1059time (seconds and fraction past UTC midnight). 1060The next five fields 1061show time offset (seconds), frequency offset (parts per million - 1062PPM), RMS jitter (seconds), Allan deviation (PPM) and clock 1063discipline time constant. 1064@item @code{peerstats} 1065Enables recording of peer statistics information. 1066This includes 1067statistics records of all peers of a NTP server and of special 1068signals, where present and configured. 1069Each valid update appends a 1070line of the following form to the current element of a file 1071generation set named 1072@code{peerstats}: 1073@verbatim 107448773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 1075@end verbatim 1076 1077The first two fields show the date (Modified Julian Day) and 1078time (seconds and fraction past UTC midnight). 1079The next two fields 1080show the peer address in dotted-quad notation and status, 1081respectively. 1082The status field is encoded in hex in the format 1083described in Appendix A of the NTP specification RFC 1305. 1084The final four fields show the offset, 1085delay, dispersion and RMS jitter, all in seconds. 1086@item @code{rawstats} 1087Enables recording of raw-timestamp statistics information. 1088This 1089includes statistics records of all peers of a NTP server and of 1090special signals, where present and configured. 1091Each NTP message 1092received from a peer or clock driver appends a line of the 1093following form to the file generation set named 1094@code{rawstats}: 1095@verbatim 109650928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 1097@end verbatim 1098 1099The first two fields show the date (Modified Julian Day) and 1100time (seconds and fraction past UTC midnight). 1101The next two fields 1102show the remote peer or clock address followed by the local address 1103in dotted-quad notation. 1104The final four fields show the originate, 1105receive, transmit and final NTP timestamps in order. 1106The timestamp 1107values are as received and before processing by the various data 1108smoothing and mitigation algorithms. 1109@item @code{sysstats} 1110Enables recording of ntpd statistics counters on a periodic basis. 1111Each 1112hour a line of the following form is appended to the file generation 1113set named 1114@code{sysstats}: 1115@verbatim 111650928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1117@end verbatim 1118 1119The first two fields show the date (Modified Julian Day) and time 1120(seconds and fraction past UTC midnight). 1121The remaining ten fields show 1122the statistics counter values accumulated since the last generated 1123line. 1124@table @asis 1125@item Time since restart @code{36000} 1126Time in hours since the system was last rebooted. 1127@item Packets received @code{81965} 1128Total number of packets received. 1129@item Packets processed @code{0} 1130Number of packets received in response to previous packets sent 1131@item Current version @code{9546} 1132Number of packets matching the current NTP version. 1133@item Previous version @code{56} 1134Number of packets matching the previous NTP version. 1135@item Bad version @code{71793} 1136Number of packets matching neither NTP version. 1137@item Access denied @code{512} 1138Number of packets denied access for any reason. 1139@item Bad length or format @code{540} 1140Number of packets with invalid length, format or port number. 1141@item Bad authentication @code{10} 1142Number of packets not verified as authentic. 1143@item Rate exceeded @code{147} 1144Number of packets discarded due to rate limitation. 1145@end table 1146@item @code{statsdir} @kbd{directory_path} 1147Indicates the full path of a directory where statistics files 1148should be created (see below). 1149This keyword allows 1150the (otherwise constant) 1151@code{filegen} 1152filename prefix to be modified for file generation sets, which 1153is useful for handling statistics logs. 1154@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}]} 1155Configures setting of generation file set name. 1156Generation 1157file sets provide a means for handling files that are 1158continuously growing during the lifetime of a server. 1159Server statistics are a typical example for such files. 1160Generation file sets provide access to a set of files used 1161to store the actual data. 1162At any time at most one element 1163of the set is being written to. 1164The type given specifies 1165when and how data will be directed to a new element of the set. 1166This way, information stored in elements of a file set 1167that are currently unused are available for administrational 1168operations without the risk of disturbing the operation of ntpd. 1169(Most important: they can be removed to free space for new data 1170produced.) 1171 1172Note that this command can be sent from the 1173@code{ntpdc(1ntpdcmdoc)} 1174program running at a remote location. 1175@table @asis 1176@item @code{name} 1177This is the type of the statistics records, as shown in the 1178@code{statistics} 1179command. 1180@item @code{file} @kbd{filename} 1181This is the file name for the statistics records. 1182Filenames of set 1183members are built from three concatenated elements 1184@code{prefix}, 1185@code{filename} 1186and 1187@code{suffix}: 1188@table @asis 1189@item @code{prefix} 1190This is a constant filename path. 1191It is not subject to 1192modifications via the 1193@kbd{filegen} 1194option. 1195It is defined by the 1196server, usually specified as a compile-time constant. 1197It may, 1198however, be configurable for individual file generation sets 1199via other commands. 1200For example, the prefix used with 1201@kbd{loopstats} 1202and 1203@kbd{peerstats} 1204generation can be configured using the 1205@kbd{statsdir} 1206option explained above. 1207@item @code{filename} 1208This string is directly concatenated to the prefix mentioned 1209above (no intervening 1210@quoteleft{}/@quoteright{}). 1211This can be modified using 1212the file argument to the 1213@kbd{filegen} 1214statement. 1215No 1216@file{..} 1217elements are 1218allowed in this component to prevent filenames referring to 1219parts outside the filesystem hierarchy denoted by 1220@kbd{prefix}. 1221@item @code{suffix} 1222This part is reflects individual elements of a file set. 1223It is 1224generated according to the type of a file set. 1225@end table 1226@item @code{type} @kbd{typename} 1227A file generation set is characterized by its type. 1228The following 1229types are supported: 1230@table @asis 1231@item @code{none} 1232The file set is actually a single plain file. 1233@item @code{pid} 1234One element of file set is used per incarnation of a ntpd 1235server. 1236This type does not perform any changes to file set 1237members during runtime, however it provides an easy way of 1238separating files belonging to different 1239@code{ntpd(1ntpdmdoc)} 1240server incarnations. 1241The set member filename is built by appending a 1242@quoteleft{}.@quoteright{} 1243to concatenated 1244@kbd{prefix} 1245and 1246@kbd{filename} 1247strings, and 1248appending the decimal representation of the process ID of the 1249@code{ntpd(1ntpdmdoc)} 1250server process. 1251@item @code{day} 1252One file generation set element is created per day. 1253A day is 1254defined as the period between 00:00 and 24:00 UTC. 1255The file set 1256member suffix consists of a 1257@quoteleft{}.@quoteright{} 1258and a day specification in 1259the form 1260@code{YYYYMMdd}. 1261@code{YYYY} 1262is a 4-digit year number (e.g., 1992). 1263@code{MM} 1264is a two digit month number. 1265@code{dd} 1266is a two digit day number. 1267Thus, all information written at 10 December 1992 would end up 1268in a file named 1269@kbd{prefix} 1270@kbd{filename}.19921210. 1271@item @code{week} 1272Any file set member contains data related to a certain week of 1273a year. 1274The term week is defined by computing day-of-year 1275modulo 7. 1276Elements of such a file generation set are 1277distinguished by appending the following suffix to the file set 1278filename base: A dot, a 4-digit year number, the letter 1279@code{W}, 1280and a 2-digit week number. 1281For example, information from January, 128210th 1992 would end up in a file with suffix 1283.No . Ns Ar 1992W1 . 1284@item @code{month} 1285One generation file set element is generated per month. 1286The 1287file name suffix consists of a dot, a 4-digit year number, and 1288a 2-digit month. 1289@item @code{year} 1290One generation file element is generated per year. 1291The filename 1292suffix consists of a dot and a 4 digit year number. 1293@item @code{age} 1294This type of file generation sets changes to a new element of 1295the file set every 24 hours of server operation. 1296The filename 1297suffix consists of a dot, the letter 1298@code{a}, 1299and an 8-digit number. 1300This number is taken to be the number of seconds the server is 1301running at the start of the corresponding 24-hour period. 1302Information is only written to a file generation by specifying 1303@code{enable}; 1304output is prevented by specifying 1305@code{disable}. 1306@end table 1307@item @code{link} | @code{nolink} 1308It is convenient to be able to access the current element of a file 1309generation set by a fixed name. 1310This feature is enabled by 1311specifying 1312@code{link} 1313and disabled using 1314@code{nolink}. 1315If link is specified, a 1316hard link from the current file set element to a file without 1317suffix is created. 1318When there is already a file with this name and 1319the number of links of this file is one, it is renamed appending a 1320dot, the letter 1321@code{C}, 1322and the pid of the ntpd server process. 1323When the 1324number of links is greater than one, the file is unlinked. 1325This 1326allows the current file to be accessed by a constant name. 1327@item @code{enable} @code{|} @code{disable} 1328Enables or disables the recording function. 1329@end table 1330@end table 1331@end table 1332@node Access Control Support 1333@subsection Access Control Support 1334The 1335@code{ntpd(1ntpdmdoc)} 1336daemon implements a general purpose address/mask based restriction 1337list. 1338The list contains address/match entries sorted first 1339by increasing address values and and then by increasing mask values. 1340A match occurs when the bitwise AND of the mask and the packet 1341source address is equal to the bitwise AND of the mask and 1342address in the list. 1343The list is searched in order with the 1344last match found defining the restriction flags associated 1345with the entry. 1346Additional information and examples can be found in the 1347"Notes on Configuring NTP and Setting up a NTP Subnet" 1348page 1349(available as part of the HTML documentation 1350provided in 1351@file{/usr/share/doc/ntp}). 1352 1353The restriction facility was implemented in conformance 1354with the access policies for the original NSFnet backbone 1355time servers. 1356Later the facility was expanded to deflect 1357cryptographic and clogging attacks. 1358While this facility may 1359be useful for keeping unwanted or broken or malicious clients 1360from congesting innocent servers, it should not be considered 1361an alternative to the NTP authentication facilities. 1362Source address based restrictions are easily circumvented 1363by a determined cracker. 1364 1365Clients can be denied service because they are explicitly 1366included in the restrict list created by the restrict command 1367or implicitly as the result of cryptographic or rate limit 1368violations. 1369Cryptographic violations include certificate 1370or identity verification failure; rate limit violations generally 1371result from defective NTP implementations that send packets 1372at abusive rates. 1373Some violations cause denied service 1374only for the offending packet, others cause denied service 1375for a timed period and others cause the denied service for 1376an indefinate period. 1377When a client or network is denied access 1378for an indefinate period, the only way at present to remove 1379the restrictions is by restarting the server. 1380@subsubsection The Kiss-of-Death Packet 1381Ordinarily, packets denied service are simply dropped with no 1382further action except incrementing statistics counters. 1383Sometimes a 1384more proactive response is needed, such as a server message that 1385explicitly requests the client to stop sending and leave a message 1386for the system operator. 1387A special packet format has been created 1388for this purpose called the "kiss-of-death" (KoD) packet. 1389KoD packets have the leap bits set unsynchronized and stratum set 1390to zero and the reference identifier field set to a four-byte 1391ASCII code. 1392If the 1393@code{noserve} 1394or 1395@code{notrust} 1396flag of the matching restrict list entry is set, 1397the code is "DENY"; if the 1398@code{limited} 1399flag is set and the rate limit 1400is exceeded, the code is "RATE". 1401Finally, if a cryptographic violation occurs, the code is "CRYP". 1402 1403A client receiving a KoD performs a set of sanity checks to 1404minimize security exposure, then updates the stratum and 1405reference identifier peer variables, sets the access 1406denied (TEST4) bit in the peer flash variable and sends 1407a message to the log. 1408As long as the TEST4 bit is set, 1409the client will send no further packets to the server. 1410The only way at present to recover from this condition is 1411to restart the protocol at both the client and server. 1412This 1413happens automatically at the client when the association times out. 1414It will happen at the server only if the server operator cooperates. 1415@subsubsection Access Control Commands 1416@table @asis 1417@item @code{discard} @code{[@code{average} @kbd{avg}]} @code{[@code{minimum} @kbd{min}]} @code{[@code{monitor} @kbd{prob}]} 1418Set the parameters of the 1419@code{limited} 1420facility which protects the server from 1421client abuse. 1422The 1423@code{average} 1424subcommand specifies the minimum average packet 1425spacing, while the 1426@code{minimum} 1427subcommand specifies the minimum packet spacing. 1428Packets that violate these minima are discarded 1429and a kiss-o'-death packet returned if enabled. 1430The default 1431minimum average and minimum are 5 and 2, respectively. 1432The monitor subcommand specifies the probability of discard 1433for packets that overflow the rate-control window. 1434@item @code{restrict} @code{address} @code{[@code{mask} @kbd{mask}]} @code{[@kbd{flag} @kbd{...}]} 1435The 1436@kbd{address} 1437argument expressed in 1438dotted-quad form is the address of a host or network. 1439Alternatively, the 1440@kbd{address} 1441argument can be a valid host DNS name. 1442The 1443@kbd{mask} 1444argument expressed in dotted-quad form defaults to 1445@code{255.255.255.255}, 1446meaning that the 1447@kbd{address} 1448is treated as the address of an individual host. 1449A default entry (address 1450@code{0.0.0.0}, 1451mask 1452@code{0.0.0.0}) 1453is always included and is always the first entry in the list. 1454Note that text string 1455@code{default}, 1456with no mask option, may 1457be used to indicate the default entry. 1458In the current implementation, 1459@code{flag} 1460always 1461restricts access, i.e., an entry with no flags indicates that free 1462access to the server is to be given. 1463The flags are not orthogonal, 1464in that more restrictive flags will often make less restrictive 1465ones redundant. 1466The flags can generally be classed into two 1467categories, those which restrict time service and those which 1468restrict informational queries and attempts to do run-time 1469reconfiguration of the server. 1470One or more of the following flags 1471may be specified: 1472@table @asis 1473@item @code{ignore} 1474Deny packets of all kinds, including 1475@code{ntpq(1ntpqmdoc)} 1476and 1477@code{ntpdc(1ntpdcmdoc)} 1478queries. 1479@item @code{kod} 1480If this flag is set when an access violation occurs, a kiss-o'-death 1481(KoD) packet is sent. 1482KoD packets are rate limited to no more than one 1483per second. 1484If another KoD packet occurs within one second after the 1485last one, the packet is dropped. 1486@item @code{limited} 1487Deny service if the packet spacing violates the lower limits specified 1488in the discard command. 1489A history of clients is kept using the 1490monitoring capability of 1491@code{ntpd(1ntpdmdoc)}. 1492Thus, monitoring is always active as 1493long as there is a restriction entry with the 1494@code{limited} 1495flag. 1496@item @code{lowpriotrap} 1497Declare traps set by matching hosts to be low priority. 1498The 1499number of traps a server can maintain is limited (the current limit 1500is 3). 1501Traps are usually assigned on a first come, first served 1502basis, with later trap requestors being denied service. 1503This flag 1504modifies the assignment algorithm by allowing low priority traps to 1505be overridden by later requests for normal priority traps. 1506@item @code{nomodify} 1507Deny 1508@code{ntpq(1ntpqmdoc)} 1509and 1510@code{ntpdc(1ntpdcmdoc)} 1511queries which attempt to modify the state of the 1512server (i.e., run time reconfiguration). 1513Queries which return 1514information are permitted. 1515@item @code{noquery} 1516Deny 1517@code{ntpq(1ntpqmdoc)} 1518and 1519@code{ntpdc(1ntpdcmdoc)} 1520queries. 1521Time service is not affected. 1522@item @code{nopeer} 1523Deny packets which would result in mobilizing a new association. 1524This 1525includes broadcast and symmetric active packets when a configured 1526association does not exist. 1527It also includes 1528@code{pool} 1529associations, so if you want to use servers from a 1530@code{pool} 1531directive and also want to use 1532@code{nopeer} 1533by default, you'll want a 1534@code{restrict source ...} @code{line} @code{as} @code{well} @code{that} @code{does} 1535@item not 1536include the 1537@code{nopeer} 1538directive. 1539@item @code{noserve} 1540Deny all packets except 1541@code{ntpq(1ntpqmdoc)} 1542and 1543@code{ntpdc(1ntpdcmdoc)} 1544queries. 1545@item @code{notrap} 1546Decline to provide mode 6 control message trap service to matching 1547hosts. 1548The trap service is a subsystem of the ntpdq control message 1549protocol which is intended for use by remote event logging programs. 1550@item @code{notrust} 1551Deny service unless the packet is cryptographically authenticated. 1552@item @code{ntpport} 1553This is actually a match algorithm modifier, rather than a 1554restriction flag. 1555Its presence causes the restriction entry to be 1556matched only if the source port in the packet is the standard NTP 1557UDP port (123). 1558Both 1559@code{ntpport} 1560and 1561@code{non-ntpport} 1562may 1563be specified. 1564The 1565@code{ntpport} 1566is considered more specific and 1567is sorted later in the list. 1568@item @code{version} 1569Deny packets that do not match the current NTP version. 1570@end table 1571 1572Default restriction list entries with the flags ignore, interface, 1573ntpport, for each of the local host's interface addresses are 1574inserted into the table at startup to prevent the server 1575from attempting to synchronize to its own time. 1576A default entry is also always present, though if it is 1577otherwise unconfigured; no flags are associated 1578with the default entry (i.e., everything besides your own 1579NTP server is unrestricted). 1580@end table 1581@node Automatic NTP Configuration Options 1582@subsection Automatic NTP Configuration Options 1583@subsubsection Manycasting 1584Manycasting is a automatic discovery and configuration paradigm 1585new to NTPv4. 1586It is intended as a means for a multicast client 1587to troll the nearby network neighborhood to find cooperating 1588manycast servers, validate them using cryptographic means 1589and evaluate their time values with respect to other servers 1590that might be lurking in the vicinity. 1591The intended result is that each manycast client mobilizes 1592client associations with some number of the "best" 1593of the nearby manycast servers, yet automatically reconfigures 1594to sustain this number of servers should one or another fail. 1595 1596Note that the manycasting paradigm does not coincide 1597with the anycast paradigm described in RFC-1546, 1598which is designed to find a single server from a clique 1599of servers providing the same service. 1600The manycast paradigm is designed to find a plurality 1601of redundant servers satisfying defined optimality criteria. 1602 1603Manycasting can be used with either symmetric key 1604or public key cryptography. 1605The public key infrastructure (PKI) 1606offers the best protection against compromised keys 1607and is generally considered stronger, at least with relatively 1608large key sizes. 1609It is implemented using the Autokey protocol and 1610the OpenSSL cryptographic library available from 1611@code{http://www.openssl.org/}. 1612The library can also be used with other NTPv4 modes 1613as well and is highly recommended, especially for broadcast modes. 1614 1615A persistent manycast client association is configured 1616using the manycastclient command, which is similar to the 1617server command but with a multicast (IPv4 class 1618@code{D} 1619or IPv6 prefix 1620@code{FF}) 1621group address. 1622The IANA has designated IPv4 address 224.1.1.1 1623and IPv6 address FF05::101 (site local) for NTP. 1624When more servers are needed, it broadcasts manycast 1625client messages to this address at the minimum feasible rate 1626and minimum feasible time-to-live (TTL) hops, depending 1627on how many servers have already been found. 1628There can be as many manycast client associations 1629as different group address, each one serving as a template 1630for a future ephemeral unicast client/server association. 1631 1632Manycast servers configured with the 1633@code{manycastserver} 1634command listen on the specified group address for manycast 1635client messages. 1636Note the distinction between manycast client, 1637which actively broadcasts messages, and manycast server, 1638which passively responds to them. 1639If a manycast server is 1640in scope of the current TTL and is itself synchronized 1641to a valid source and operating at a stratum level equal 1642to or lower than the manycast client, it replies to the 1643manycast client message with an ordinary unicast server message. 1644 1645The manycast client receiving this message mobilizes 1646an ephemeral client/server association according to the 1647matching manycast client template, but only if cryptographically 1648authenticated and the server stratum is less than or equal 1649to the client stratum. 1650Authentication is explicitly required 1651and either symmetric key or public key (Autokey) can be used. 1652Then, the client polls the server at its unicast address 1653in burst mode in order to reliably set the host clock 1654and validate the source. 1655This normally results 1656in a volley of eight client/server at 2-s intervals 1657during which both the synchronization and cryptographic 1658protocols run concurrently. 1659Following the volley, 1660the client runs the NTP intersection and clustering 1661algorithms, which act to discard all but the "best" 1662associations according to stratum and synchronization 1663distance. 1664The surviving associations then continue 1665in ordinary client/server mode. 1666 1667The manycast client polling strategy is designed to reduce 1668as much as possible the volume of manycast client messages 1669and the effects of implosion due to near-simultaneous 1670arrival of manycast server messages. 1671The strategy is determined by the 1672@code{manycastclient}, 1673@code{tos} 1674and 1675@code{ttl} 1676configuration commands. 1677The manycast poll interval is 1678normally eight times the system poll interval, 1679which starts out at the 1680@code{minpoll} 1681value specified in the 1682@code{manycastclient}, 1683command and, under normal circumstances, increments to the 1684@code{maxpolll} 1685value specified in this command. 1686Initially, the TTL is 1687set at the minimum hops specified by the ttl command. 1688At each retransmission the TTL is increased until reaching 1689the maximum hops specified by this command or a sufficient 1690number client associations have been found. 1691Further retransmissions use the same TTL. 1692 1693The quality and reliability of the suite of associations 1694discovered by the manycast client is determined by the NTP 1695mitigation algorithms and the 1696@code{minclock} 1697and 1698@code{minsane} 1699values specified in the 1700@code{tos} 1701configuration command. 1702At least 1703@code{minsane} 1704candidate servers must be available and the mitigation 1705algorithms produce at least 1706@code{minclock} 1707survivors in order to synchronize the clock. 1708Byzantine agreement principles require at least four 1709candidates in order to correctly discard a single falseticker. 1710For legacy purposes, 1711@code{minsane} 1712defaults to 1 and 1713@code{minclock} 1714defaults to 3. 1715For manycast service 1716@code{minsane} 1717should be explicitly set to 4, assuming at least that 1718number of servers are available. 1719 1720If at least 1721@code{minclock} 1722servers are found, the manycast poll interval is immediately 1723set to eight times 1724@code{maxpoll}. 1725If less than 1726@code{minclock} 1727servers are found when the TTL has reached the maximum hops, 1728the manycast poll interval is doubled. 1729For each transmission 1730after that, the poll interval is doubled again until 1731reaching the maximum of eight times 1732@code{maxpoll}. 1733Further transmissions use the same poll interval and 1734TTL values. 1735Note that while all this is going on, 1736each client/server association found is operating normally 1737it the system poll interval. 1738 1739Administratively scoped multicast boundaries are normally 1740specified by the network router configuration and, 1741in the case of IPv6, the link/site scope prefix. 1742By default, the increment for TTL hops is 32 starting 1743from 31; however, the 1744@code{ttl} 1745configuration command can be 1746used to modify the values to match the scope rules. 1747 1748It is often useful to narrow the range of acceptable 1749servers which can be found by manycast client associations. 1750Because manycast servers respond only when the client 1751stratum is equal to or greater than the server stratum, 1752primary (stratum 1) servers fill find only primary servers 1753in TTL range, which is probably the most common objective. 1754However, unless configured otherwise, all manycast clients 1755in TTL range will eventually find all primary servers 1756in TTL range, which is probably not the most common 1757objective in large networks. 1758The 1759@code{tos} 1760command can be used to modify this behavior. 1761Servers with stratum below 1762@code{floor} 1763or above 1764@code{ceiling} 1765specified in the 1766@code{tos} 1767command are strongly discouraged during the selection 1768process; however, these servers may be temporally 1769accepted if the number of servers within TTL range is 1770less than 1771@code{minclock}. 1772 1773The above actions occur for each manycast client message, 1774which repeats at the designated poll interval. 1775However, once the ephemeral client association is mobilized, 1776subsequent manycast server replies are discarded, 1777since that would result in a duplicate association. 1778If during a poll interval the number of client associations 1779falls below 1780@code{minclock}, 1781all manycast client prototype associations are reset 1782to the initial poll interval and TTL hops and operation 1783resumes from the beginning. 1784It is important to avoid 1785frequent manycast client messages, since each one requires 1786all manycast servers in TTL range to respond. 1787The result could well be an implosion, either minor or major, 1788depending on the number of servers in range. 1789The recommended value for 1790@code{maxpoll} 1791is 12 (4,096 s). 1792 1793It is possible and frequently useful to configure a host 1794as both manycast client and manycast server. 1795A number of hosts configured this way and sharing a common 1796group address will automatically organize themselves 1797in an optimum configuration based on stratum and 1798synchronization distance. 1799For example, consider an NTP 1800subnet of two primary servers and a hundred or more 1801dependent clients. 1802With two exceptions, all servers 1803and clients have identical configuration files including both 1804@code{multicastclient} 1805and 1806@code{multicastserver} 1807commands using, for instance, multicast group address 1808239.1.1.1. 1809The only exception is that each primary server 1810configuration file must include commands for the primary 1811reference source such as a GPS receiver. 1812 1813The remaining configuration files for all secondary 1814servers and clients have the same contents, except for the 1815@code{tos} 1816command, which is specific for each stratum level. 1817For stratum 1 and stratum 2 servers, that command is 1818not necessary. 1819For stratum 3 and above servers the 1820@code{floor} 1821value is set to the intended stratum number. 1822Thus, all stratum 3 configuration files are identical, 1823all stratum 4 files are identical and so forth. 1824 1825Once operations have stabilized in this scenario, 1826the primary servers will find the primary reference source 1827and each other, since they both operate at the same 1828stratum (1), but not with any secondary server or client, 1829since these operate at a higher stratum. 1830The secondary 1831servers will find the servers at the same stratum level. 1832If one of the primary servers loses its GPS receiver, 1833it will continue to operate as a client and other clients 1834will time out the corresponding association and 1835re-associate accordingly. 1836 1837Some administrators prefer to avoid running 1838@code{ntpd(1ntpdmdoc)} 1839continuously and run either 1840@code{ntpdate(8)} 1841or 1842@code{ntpd(1ntpdmdoc)} 1843@code{-q} 1844as a cron job. 1845In either case the servers must be 1846configured in advance and the program fails if none are 1847available when the cron job runs. 1848A really slick 1849application of manycast is with 1850@code{ntpd(1ntpdmdoc)} 1851@code{-q}. 1852The program wakes up, scans the local landscape looking 1853for the usual suspects, selects the best from among 1854the rascals, sets the clock and then departs. 1855Servers do not have to be configured in advance and 1856all clients throughout the network can have the same 1857configuration file. 1858@subsubsection Manycast Interactions with Autokey 1859Each time a manycast client sends a client mode packet 1860to a multicast group address, all manycast servers 1861in scope generate a reply including the host name 1862and status word. 1863The manycast clients then run 1864the Autokey protocol, which collects and verifies 1865all certificates involved. 1866Following the burst interval 1867all but three survivors are cast off, 1868but the certificates remain in the local cache. 1869It often happens that several complete signing trails 1870from the client to the primary servers are collected in this way. 1871 1872About once an hour or less often if the poll interval 1873exceeds this, the client regenerates the Autokey key list. 1874This is in general transparent in client/server mode. 1875However, about once per day the server private value 1876used to generate cookies is refreshed along with all 1877manycast client associations. 1878In this case all 1879cryptographic values including certificates is refreshed. 1880If a new certificate has been generated since 1881the last refresh epoch, it will automatically revoke 1882all prior certificates that happen to be in the 1883certificate cache. 1884At the same time, the manycast 1885scheme starts all over from the beginning and 1886the expanding ring shrinks to the minimum and increments 1887from there while collecting all servers in scope. 1888@subsubsection Manycast Options 1889@table @asis 1890@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}]} 1891This command affects the clock selection and clustering 1892algorithms. 1893It can be used to select the quality and 1894quantity of peers used to synchronize the system clock 1895and is most useful in manycast mode. 1896The variables operate 1897as follows: 1898@table @asis 1899@item @code{ceiling} @kbd{ceiling} 1900Peers with strata above 1901@code{ceiling} 1902will be discarded if there are at least 1903@code{minclock} 1904peers remaining. 1905This value defaults to 15, but can be changed 1906to any number from 1 to 15. 1907@item @code{cohort} @code{@{0 | 1@}} 1908This is a binary flag which enables (0) or disables (1) 1909manycast server replies to manycast clients with the same 1910stratum level. 1911This is useful to reduce implosions where 1912large numbers of clients with the same stratum level 1913are present. 1914The default is to enable these replies. 1915@item @code{floor} @kbd{floor} 1916Peers with strata below 1917@code{floor} 1918will be discarded if there are at least 1919@code{minclock} 1920peers remaining. 1921This value defaults to 1, but can be changed 1922to any number from 1 to 15. 1923@item @code{minclock} @kbd{minclock} 1924The clustering algorithm repeatedly casts out outlyer 1925associations until no more than 1926@code{minclock} 1927associations remain. 1928This value defaults to 3, 1929but can be changed to any number from 1 to the number of 1930configured sources. 1931@item @code{minsane} @kbd{minsane} 1932This is the minimum number of candidates available 1933to the clock selection algorithm in order to produce 1934one or more truechimers for the clustering algorithm. 1935If fewer than this number are available, the clock is 1936undisciplined and allowed to run free. 1937The default is 1 1938for legacy purposes. 1939However, according to principles of 1940Byzantine agreement, 1941@code{minsane} 1942should be at least 4 in order to detect and discard 1943a single falseticker. 1944@end table 1945@item @code{ttl} @kbd{hop} @kbd{...} 1946This command specifies a list of TTL values in increasing 1947order, up to 8 values can be specified. 1948In manycast mode these values are used in turn 1949in an expanding-ring search. 1950The default is eight 1951multiples of 32 starting at 31. 1952@end table 1953@node Reference Clock Support 1954@subsection Reference Clock Support 1955The NTP Version 4 daemon supports some three dozen different radio, 1956satellite and modem reference clocks plus a special pseudo-clock 1957used for backup or when no other clock source is available. 1958Detailed descriptions of individual device drivers and options can 1959be found in the 1960"Reference Clock Drivers" 1961page 1962(available as part of the HTML documentation 1963provided in 1964@file{/usr/share/doc/ntp}). 1965Additional information can be found in the pages linked 1966there, including the 1967"Debugging Hints for Reference Clock Drivers" 1968and 1969"How To Write a Reference Clock Driver" 1970pages 1971(available as part of the HTML documentation 1972provided in 1973@file{/usr/share/doc/ntp}). 1974In addition, support for a PPS 1975signal is available as described in the 1976"Pulse-per-second (PPS) Signal Interfacing" 1977page 1978(available as part of the HTML documentation 1979provided in 1980@file{/usr/share/doc/ntp}). 1981Many 1982drivers support special line discipline/streams modules which can 1983significantly improve the accuracy using the driver. 1984These are 1985described in the 1986"Line Disciplines and Streams Drivers" 1987page 1988(available as part of the HTML documentation 1989provided in 1990@file{/usr/share/doc/ntp}). 1991 1992A reference clock will generally (though not always) be a radio 1993timecode receiver which is synchronized to a source of standard 1994time such as the services offered by the NRC in Canada and NIST and 1995USNO in the US. 1996The interface between the computer and the timecode 1997receiver is device dependent, but is usually a serial port. 1998A 1999device driver specific to each reference clock must be selected and 2000compiled in the distribution; however, most common radio, satellite 2001and modem clocks are included by default. 2002Note that an attempt to 2003configure a reference clock when the driver has not been compiled 2004or the hardware port has not been appropriately configured results 2005in a scalding remark to the system log file, but is otherwise non 2006hazardous. 2007 2008For the purposes of configuration, 2009@code{ntpd(1ntpdmdoc)} 2010treats 2011reference clocks in a manner analogous to normal NTP peers as much 2012as possible. 2013Reference clocks are identified by a syntactically 2014correct but invalid IP address, in order to distinguish them from 2015normal NTP peers. 2016Reference clock addresses are of the form 2017@code{127.127.}@kbd{t}.@kbd{u}, 2018where 2019@kbd{t} 2020is an integer 2021denoting the clock type and 2022@kbd{u} 2023indicates the unit 2024number in the range 0-3. 2025While it may seem overkill, it is in fact 2026sometimes useful to configure multiple reference clocks of the same 2027type, in which case the unit numbers must be unique. 2028 2029The 2030@code{server} 2031command is used to configure a reference 2032clock, where the 2033@kbd{address} 2034argument in that command 2035is the clock address. 2036The 2037@code{key}, 2038@code{version} 2039and 2040@code{ttl} 2041options are not used for reference clock support. 2042The 2043@code{mode} 2044option is added for reference clock support, as 2045described below. 2046The 2047@code{prefer} 2048option can be useful to 2049persuade the server to cherish a reference clock with somewhat more 2050enthusiasm than other reference clocks or peers. 2051Further 2052information on this option can be found in the 2053"Mitigation Rules and the prefer Keyword" 2054(available as part of the HTML documentation 2055provided in 2056@file{/usr/share/doc/ntp}) 2057page. 2058The 2059@code{minpoll} 2060and 2061@code{maxpoll} 2062options have 2063meaning only for selected clock drivers. 2064See the individual clock 2065driver document pages for additional information. 2066 2067The 2068@code{fudge} 2069command is used to provide additional 2070information for individual clock drivers and normally follows 2071immediately after the 2072@code{server} 2073command. 2074The 2075@kbd{address} 2076argument specifies the clock address. 2077The 2078@code{refid} 2079and 2080@code{stratum} 2081options can be used to 2082override the defaults for the device. 2083There are two optional 2084device-dependent time offsets and four flags that can be included 2085in the 2086@code{fudge} 2087command as well. 2088 2089The stratum number of a reference clock is by default zero. 2090Since the 2091@code{ntpd(1ntpdmdoc)} 2092daemon adds one to the stratum of each 2093peer, a primary server ordinarily displays an external stratum of 2094one. 2095In order to provide engineered backups, it is often useful to 2096specify the reference clock stratum as greater than zero. 2097The 2098@code{stratum} 2099option is used for this purpose. 2100Also, in cases 2101involving both a reference clock and a pulse-per-second (PPS) 2102discipline signal, it is useful to specify the reference clock 2103identifier as other than the default, depending on the driver. 2104The 2105@code{refid} 2106option is used for this purpose. 2107Except where noted, 2108these options apply to all clock drivers. 2109@subsubsection Reference Clock Commands 2110@table @asis 2111@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}]} 2112This command can be used to configure reference clocks in 2113special ways. 2114The options are interpreted as follows: 2115@table @asis 2116@item @code{prefer} 2117Marks the reference clock as preferred. 2118All other things being 2119equal, this host will be chosen for synchronization among a set of 2120correctly operating hosts. 2121See the 2122"Mitigation Rules and the prefer Keyword" 2123page 2124(available as part of the HTML documentation 2125provided in 2126@file{/usr/share/doc/ntp}) 2127for further information. 2128@item @code{mode} @kbd{int} 2129Specifies a mode number which is interpreted in a 2130device-specific fashion. 2131For instance, it selects a dialing 2132protocol in the ACTS driver and a device subtype in the 2133parse 2134drivers. 2135@item @code{minpoll} @kbd{int} 2136@item @code{maxpoll} @kbd{int} 2137These options specify the minimum and maximum polling interval 2138for reference clock messages, as a power of 2 in seconds 2139For 2140most directly connected reference clocks, both 2141@code{minpoll} 2142and 2143@code{maxpoll} 2144default to 6 (64 s). 2145For modem reference clocks, 2146@code{minpoll} 2147defaults to 10 (17.1 m) and 2148@code{maxpoll} 2149defaults to 14 (4.5 h). 2150The allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2151@end table 2152@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}]} 2153This command can be used to configure reference clocks in 2154special ways. 2155It must immediately follow the 2156@code{server} 2157command which configures the driver. 2158Note that the same capability 2159is possible at run time using the 2160@code{ntpdc(1ntpdcmdoc)} 2161program. 2162The options are interpreted as 2163follows: 2164@table @asis 2165@item @code{time1} @kbd{sec} 2166Specifies a constant to be added to the time offset produced by 2167the driver, a fixed-point decimal number in seconds. 2168This is used 2169as a calibration constant to adjust the nominal time offset of a 2170particular clock to agree with an external standard, such as a 2171precision PPS signal. 2172It also provides a way to correct a 2173systematic error or bias due to serial port or operating system 2174latencies, different cable lengths or receiver internal delay. 2175The 2176specified offset is in addition to the propagation delay provided 2177by other means, such as internal DIPswitches. 2178Where a calibration 2179for an individual system and driver is available, an approximate 2180correction is noted in the driver documentation pages. 2181Note: in order to facilitate calibration when more than one 2182radio clock or PPS signal is supported, a special calibration 2183feature is available. 2184It takes the form of an argument to the 2185@code{enable} 2186command described in 2187@ref{Miscellaneous Options} 2188page and operates as described in the 2189"Reference Clock Drivers" 2190page 2191(available as part of the HTML documentation 2192provided in 2193@file{/usr/share/doc/ntp}). 2194@item @code{time2} @kbd{secs} 2195Specifies a fixed-point decimal number in seconds, which is 2196interpreted in a driver-dependent way. 2197See the descriptions of 2198specific drivers in the 2199"Reference Clock Drivers" 2200page 2201(available as part of the HTML documentation 2202provided in 2203@file{/usr/share/doc/ntp}). 2204@item @code{stratum} @kbd{int} 2205Specifies the stratum number assigned to the driver, an integer 2206between 0 and 15. 2207This number overrides the default stratum number 2208ordinarily assigned by the driver itself, usually zero. 2209@item @code{refid} @kbd{string} 2210Specifies an ASCII string of from one to four characters which 2211defines the reference identifier used by the driver. 2212This string 2213overrides the default identifier ordinarily assigned by the driver 2214itself. 2215@item @code{mode} @kbd{int} 2216Specifies a mode number which is interpreted in a 2217device-specific fashion. 2218For instance, it selects a dialing 2219protocol in the ACTS driver and a device subtype in the 2220parse 2221drivers. 2222@item @code{flag1} @code{0} @code{|} @code{1} 2223@item @code{flag2} @code{0} @code{|} @code{1} 2224@item @code{flag3} @code{0} @code{|} @code{1} 2225@item @code{flag4} @code{0} @code{|} @code{1} 2226These four flags are used for customizing the clock driver. 2227The 2228interpretation of these values, and whether they are used at all, 2229is a function of the particular clock driver. 2230However, by 2231convention 2232@code{flag4} 2233is used to enable recording monitoring 2234data to the 2235@code{clockstats} 2236file configured with the 2237@code{filegen} 2238command. 2239Further information on the 2240@code{filegen} 2241command can be found in 2242@ref{Monitoring Options}. 2243@end table 2244@end table 2245@node Miscellaneous Options 2246@subsection Miscellaneous Options 2247@table @asis 2248@item @code{broadcastdelay} @kbd{seconds} 2249The broadcast and multicast modes require a special calibration 2250to determine the network delay between the local and remote 2251servers. 2252Ordinarily, this is done automatically by the initial 2253protocol exchanges between the client and server. 2254In some cases, 2255the calibration procedure may fail due to network or server access 2256controls, for example. 2257This command specifies the default delay to 2258be used under these circumstances. 2259Typically (for Ethernet), a 2260number between 0.003 and 0.007 seconds is appropriate. 2261The default 2262when this command is not used is 0.004 seconds. 2263@item @code{calldelay} @kbd{delay} 2264This option controls the delay in seconds between the first and second 2265packets sent in burst or iburst mode to allow additional time for a modem 2266or ISDN call to complete. 2267@item @code{driftfile} @kbd{driftfile} 2268This command specifies the complete path and name of the file used to 2269record the frequency of the local clock oscillator. 2270This is the same 2271operation as the 2272@code{-f} 2273command line option. 2274If the file exists, it is read at 2275startup in order to set the initial frequency and then updated once per 2276hour with the current frequency computed by the daemon. 2277If the file name is 2278specified, but the file itself does not exist, the starts with an initial 2279frequency of zero and creates the file when writing it for the first time. 2280If this command is not given, the daemon will always start with an initial 2281frequency of zero. 2282 2283The file format consists of a single line containing a single 2284floating point number, which records the frequency offset measured 2285in parts-per-million (PPM). 2286The file is updated by first writing 2287the current drift value into a temporary file and then renaming 2288this file to replace the old version. 2289This implies that 2290@code{ntpd(1ntpdmdoc)} 2291must have write permission for the directory the 2292drift file is located in, and that file system links, symbolic or 2293otherwise, should be avoided. 2294@item @code{enable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats}]} 2295@item @code{disable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats}]} 2296Provides a way to enable or disable various server options. 2297Flags not mentioned are unaffected. 2298Note that all of these flags 2299can be controlled remotely using the 2300@code{ntpdc(1ntpdcmdoc)} 2301utility program. 2302@table @asis 2303@item @code{auth} 2304Enables the server to synchronize with unconfigured peers only if the 2305peer has been correctly authenticated using either public key or 2306private key cryptography. 2307The default for this flag is 2308@code{enable}. 2309@item @code{bclient} 2310Enables the server to listen for a message from a broadcast or 2311multicast server, as in the 2312@code{multicastclient} 2313command with default 2314address. 2315The default for this flag is 2316@code{disable}. 2317@item @code{calibrate} 2318Enables the calibrate feature for reference clocks. 2319The default for 2320this flag is 2321@code{disable}. 2322@item @code{kernel} 2323Enables the kernel time discipline, if available. 2324The default for this 2325flag is 2326@code{enable} 2327if support is available, otherwise 2328@code{disable}. 2329@item @code{mode7} 2330Enables processing of NTP mode 7 implementation-specific requests 2331which are used by the deprecated 2332@code{ntpdc(1ntpdcmdoc)} 2333program. 2334The default for this flag is disable. 2335This flag is excluded from runtime configuration using 2336@code{ntpq(1ntpqmdoc)}. 2337The 2338@code{ntpq(1ntpqmdoc)} 2339program provides the same capabilities as 2340@code{ntpdc(1ntpdcmdoc)} 2341using standard mode 6 requests. 2342@item @code{monitor} 2343Enables the monitoring facility. 2344See the 2345@code{ntpdc(1ntpdcmdoc)} 2346program 2347and the 2348@code{monlist} 2349command or further information. 2350The 2351default for this flag is 2352@code{enable}. 2353@item @code{ntp} 2354Enables time and frequency discipline. 2355In effect, this switch opens and 2356closes the feedback loop, which is useful for testing. 2357The default for 2358this flag is 2359@code{enable}. 2360@item @code{stats} 2361Enables the statistics facility. 2362See the 2363@ref{Monitoring Options} 2364section for further information. 2365The default for this flag is 2366@code{disable}. 2367@end table 2368@item @code{includefile} @kbd{includefile} 2369This command allows additional configuration commands 2370to be included from a separate file. 2371Include files may 2372be nested to a depth of five; upon reaching the end of any 2373include file, command processing resumes in the previous 2374configuration file. 2375This option is useful for sites that run 2376@code{ntpd(1ntpdmdoc)} 2377on multiple hosts, with (mostly) common options (e.g., a 2378restriction list). 2379@item @code{logconfig} @kbd{configkeyword} 2380This command controls the amount and type of output written to 2381the system 2382@code{syslog(3)} 2383facility or the alternate 2384@code{logfile} 2385log file. 2386By default, all output is turned on. 2387All 2388@kbd{configkeyword} 2389keywords can be prefixed with 2390@quoteleft{}=@quoteright{}, 2391@quoteleft{}+@quoteright{} 2392and 2393@quoteleft{}-@quoteright{}, 2394where 2395@quoteleft{}=@quoteright{} 2396sets the 2397@code{syslog(3)} 2398priority mask, 2399@quoteleft{}+@quoteright{} 2400adds and 2401@quoteleft{}-@quoteright{} 2402removes 2403messages. 2404@code{syslog(3)} 2405messages can be controlled in four 2406classes 2407(@code{clock}, @code{peer}, @code{sys} and @code{sync}). 2408Within these classes four types of messages can be 2409controlled: informational messages 2410(@code{info}), 2411event messages 2412(@code{events}), 2413statistics messages 2414(@code{statistics}) 2415and 2416status messages 2417(@code{status}). 2418 2419Configuration keywords are formed by concatenating the message class with 2420the event class. 2421The 2422@code{all} 2423prefix can be used instead of a message class. 2424A 2425message class may also be followed by the 2426@code{all} 2427keyword to enable/disable all 2428messages of the respective message class.Thus, a minimal log configuration 2429could look like this: 2430@verbatim 2431logconfig =syncstatus +sysevents 2432@end verbatim 2433 2434This would just list the synchronizations state of 2435@code{ntpd(1ntpdmdoc)} 2436and the major system events. 2437For a simple reference server, the 2438following minimum message configuration could be useful: 2439@verbatim 2440logconfig =syncall +clockall 2441@end verbatim 2442 2443This configuration will list all clock information and 2444synchronization information. 2445All other events and messages about 2446peers, system events and so on is suppressed. 2447@item @code{logfile} @kbd{logfile} 2448This command specifies the location of an alternate log file to 2449be used instead of the default system 2450@code{syslog(3)} 2451facility. 2452This is the same operation as the -l command line option. 2453@item @code{setvar} @kbd{variable} @code{[@code{default}]} 2454This command adds an additional system variable. 2455These 2456variables can be used to distribute additional information such as 2457the access policy. 2458If the variable of the form 2459@code{name}@code{=}@kbd{value} 2460is followed by the 2461@code{default} 2462keyword, the 2463variable will be listed as part of the default system variables 2464(@code{rv} command)). 2465These additional variables serve 2466informational purposes only. 2467They are not related to the protocol 2468other that they can be listed. 2469The known protocol variables will 2470always override any variables defined via the 2471@code{setvar} 2472mechanism. 2473There are three special variables that contain the names 2474of all variable of the same group. 2475The 2476@code{sys_var_list} 2477holds 2478the names of all system variables. 2479The 2480@code{peer_var_list} 2481holds 2482the names of all peer variables and the 2483@code{clock_var_list} 2484holds the names of the reference clock variables. 2485@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{srep} | @code{stepout} @kbd{stepout}]} 2486This command can be used to alter several system variables in 2487very exceptional circumstances. 2488It should occur in the 2489configuration file before any other configuration options. 2490The 2491default values of these variables have been carefully optimized for 2492a wide range of network speeds and reliability expectations. 2493In 2494general, they interact in intricate ways that are hard to predict 2495and some combinations can result in some very nasty behavior. 2496Very 2497rarely is it necessary to change the default values; but, some 2498folks cannot resist twisting the knobs anyway and this command is 2499for them. 2500Emphasis added: twisters are on their own and can expect 2501no help from the support group. 2502 2503The variables operate as follows: 2504@table @asis 2505@item @code{allan} @kbd{allan} 2506The argument becomes the new value for the minimum Allan 2507intercept, which is a parameter of the PLL/FLL clock discipline 2508algorithm. 2509The value in log2 seconds defaults to 7 (1024 s), which is also the lower 2510limit. 2511@item @code{dispersion} @kbd{dispersion} 2512The argument becomes the new value for the dispersion increase rate, 2513normally .000015 s/s. 2514@item @code{freq} @kbd{freq} 2515The argument becomes the initial value of the frequency offset in 2516parts-per-million. 2517This overrides the value in the frequency file, if 2518present, and avoids the initial training state if it is not. 2519@item @code{huffpuff} @kbd{huffpuff} 2520The argument becomes the new value for the experimental 2521huff-n'-puff filter span, which determines the most recent interval 2522the algorithm will search for a minimum delay. 2523The lower limit is 2524900 s (15 m), but a more reasonable value is 7200 (2 hours). 2525There 2526is no default, since the filter is not enabled unless this command 2527is given. 2528@item @code{panic} @kbd{panic} 2529The argument is the panic threshold, normally 1000 s. 2530If set to zero, 2531the panic sanity check is disabled and a clock offset of any value will 2532be accepted. 2533@item @code{step} @kbd{step} 2534The argument is the step threshold, which by default is 0.128 s. 2535It can 2536be set to any positive number in seconds. 2537If set to zero, step 2538adjustments will never occur. 2539Note: The kernel time discipline is 2540disabled if the step threshold is set to zero or greater than the 2541default. 2542@item @code{stepout} @kbd{stepout} 2543The argument is the stepout timeout, which by default is 900 s. 2544It can 2545be set to any positive number in seconds. 2546If set to zero, the stepout 2547pulses will not be suppressed. 2548@end table 2549@item @code{rlimit} @code{[@code{memlock} @kbd{Nmegabytes} | @code{stacksize} @kbd{N4kPages} @code{filenum} @kbd{Nfiledescriptors}]} 2550@table @asis 2551@item @code{memlock} @kbd{Nmegabytes} 2552Specify the number of megabytes of memory that can be allocated. 2553Probably only available under Linux, this option is useful 2554when dropping root (the 2555@code{-i} 2556option). 2557The default is 32 megabytes. Setting this to zero will prevent any attemp to lock memory. 2558@item @code{stacksize} @kbd{N4kPages} 2559Specifies the maximum size of the process stack on systems with the 2560@item @code{filenum} @kbd{Nfiledescriptors} 2561Specifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default. 2562@code{mlockall()} 2563function. 2564Defaults to 50 4k pages (200 4k pages in OpenBSD). 2565@end table 2566@item @code{trap} @kbd{host_address} @code{[@code{port} @kbd{port_number}]} @code{[@code{interface} @kbd{interface_address}]} 2567This command configures a trap receiver at the given host 2568address and port number for sending messages with the specified 2569local interface address. 2570If the port number is unspecified, a value 2571of 18447 is used. 2572If the interface address is not specified, the 2573message is sent with a source address of the local interface the 2574message is sent through. 2575Note that on a multihomed host the 2576interface used may vary from time to time with routing changes. 2577 2578The trap receiver will generally log event messages and other 2579information from the server in a log file. 2580While such monitor 2581programs may also request their own trap dynamically, configuring a 2582trap receiver will ensure that no messages are lost when the server 2583is started. 2584@item @code{hop} @kbd{...} 2585This command specifies a list of TTL values in increasing order, up to 8 2586values can be specified. 2587In manycast mode these values are used in turn in 2588an expanding-ring search. 2589The default is eight multiples of 32 starting at 259031. 2591@end table 2592 2593This section was generated by @strong{AutoGen}, 2594using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program. 2595This software is released under the NTP license, <http://ntp.org/license>. 2596 2597@menu 2598* ntp.conf Files:: Files 2599* ntp.conf See Also:: See Also 2600* ntp.conf Bugs:: Bugs 2601* ntp.conf Notes:: Notes 2602@end menu 2603 2604@node ntp.conf Files 2605@subsection ntp.conf Files 2606@table @asis 2607@item @file{/etc/ntp.conf} 2608the default name of the configuration file 2609@item @file{ntp.keys} 2610private MD5 keys 2611@item @file{ntpkey} 2612RSA private key 2613@item @file{ntpkey_}@kbd{host} 2614RSA public key 2615@item @file{ntp_dh} 2616Diffie-Hellman agreement parameters 2617@end table 2618@node ntp.conf See Also 2619@subsection ntp.conf See Also 2620@code{ntpd(1ntpdmdoc)}, 2621@code{ntpdc(1ntpdcmdoc)}, 2622@code{ntpq(1ntpqmdoc)} 2623 2624In addition to the manual pages provided, 2625comprehensive documentation is available on the world wide web 2626at 2627@code{http://www.ntp.org/}. 2628A snapshot of this documentation is available in HTML format in 2629@file{/usr/share/doc/ntp}. 2630@* 2631 2632@* 2633David L. Mills, @emph{Network Time Protocol (Version 4)}, RFC5905 2634@node ntp.conf Bugs 2635@subsection ntp.conf Bugs 2636The syntax checking is not picky; some combinations of 2637ridiculous and even hilarious options and modes may not be 2638detected. 2639 2640The 2641@file{ntpkey_}@kbd{host} 2642files are really digital 2643certificates. 2644These should be obtained via secure directory 2645services when they become universally available. 2646@node ntp.conf Notes 2647@subsection ntp.conf Notes 2648This document was derived from FreeBSD. 2649