invoke-ntp.conf.texi revision 310419
1275970Scy@node ntp.conf Notes 2275970Scy@section Notes about ntp.conf 3275970Scy@pindex ntp.conf 4275970Scy@cindex Network Time Protocol (NTP) daemon configuration file format 5275970Scy@ignore 6275970Scy# 7275970Scy# EDIT THIS FILE WITH CAUTION (invoke-ntp.conf.texi) 8275970Scy# 9310419Sdelphij# It has been AutoGen-ed November 21, 2016 at 08:01:55 AM by AutoGen 5.18.5 10275970Scy# From the definitions ntp.conf.def 11275970Scy# and the template file agtexi-file.tpl 12275970Scy@end ignore 13275970Scy 14275970Scy 15275970Scy 16275970ScyThe 17275970Scy@code{ntp.conf} 18275970Scyconfiguration file is read at initial startup by the 19275970Scy@code{ntpd(1ntpdmdoc)} 20275970Scydaemon in order to specify the synchronization sources, 21275970Scymodes and other related information. 22275970ScyUsually, it is installed in the 23275970Scy@file{/etc} 24275970Scydirectory, 25275970Scybut could be installed elsewhere 26275970Scy(see the daemon's 27275970Scy@code{-c} 28275970Scycommand line option). 29275970Scy 30275970ScyThe file format is similar to other 31275970Scy@sc{unix} 32275970Scyconfiguration files. 33275970ScyComments begin with a 34275970Scy@quoteleft{}#@quoteright{} 35275970Scycharacter and extend to the end of the line; 36275970Scyblank lines are ignored. 37275970ScyConfiguration commands consist of an initial keyword 38275970Scyfollowed by a list of arguments, 39275970Scysome of which may be optional, separated by whitespace. 40275970ScyCommands may not be continued over multiple lines. 41275970ScyArguments may be host names, 42275970Scyhost addresses written in numeric, dotted-quad form, 43275970Scyintegers, floating point numbers (when specifying times in seconds) 44275970Scyand text strings. 45275970Scy 46275970ScyThe rest of this page describes the configuration and control options. 47275970ScyThe 48275970Scy"Notes on Configuring NTP and Setting up an NTP Subnet" 49275970Scypage 50275970Scy(available as part of the HTML documentation 51275970Scyprovided in 52275970Scy@file{/usr/share/doc/ntp}) 53275970Scycontains an extended discussion of these options. 54275970ScyIn addition to the discussion of general 55275970Scy@ref{Configuration Options}, 56275970Scythere are sections describing the following supported functionality 57275970Scyand the options used to control it: 58275970Scy@itemize @bullet 59275970Scy@item 60275970Scy@ref{Authentication Support} 61275970Scy@item 62275970Scy@ref{Monitoring Support} 63275970Scy@item 64275970Scy@ref{Access Control Support} 65275970Scy@item 66275970Scy@ref{Automatic NTP Configuration Options} 67275970Scy@item 68275970Scy@ref{Reference Clock Support} 69275970Scy@item 70275970Scy@ref{Miscellaneous Options} 71275970Scy@end itemize 72275970Scy 73275970ScyFollowing these is a section describing 74275970Scy@ref{Miscellaneous Options}. 75275970ScyWhile there is a rich set of options available, 76275970Scythe only required option is one or more 77275970Scy@code{pool}, 78275970Scy@code{server}, 79275970Scy@code{peer}, 80275970Scy@code{broadcast} 81275970Scyor 82275970Scy@code{manycastclient} 83275970Scycommands. 84275970Scy@node Configuration Support 85275970Scy@subsection Configuration Support 86275970ScyFollowing is a description of the configuration commands in 87275970ScyNTPv4. 88275970ScyThese commands have the same basic functions as in NTPv3 and 89275970Scyin some cases new functions and new arguments. 90275970ScyThere are two 91275970Scyclasses of commands, configuration commands that configure a 92275970Scypersistent association with a remote server or peer or reference 93275970Scyclock, and auxiliary commands that specify environmental variables 94275970Scythat control various related operations. 95275970Scy@subsubsection Configuration Commands 96275970ScyThe various modes are determined by the command keyword and the 97275970Scytype of the required IP address. 98275970ScyAddresses are classed by type as 99275970Scy(s) a remote server or peer (IPv4 class A, B and C), (b) the 100275970Scybroadcast address of a local interface, (m) a multicast address (IPv4 101275970Scyclass D), or (r) a reference clock address (127.127.x.x). 102275970ScyNote that 103275970Scyonly those options applicable to each command are listed below. 104275970ScyUse 105275970Scyof options not listed may not be caught as an error, but may result 106275970Scyin some weird and even destructive behavior. 107275970Scy 108275970ScyIf the Basic Socket Interface Extensions for IPv6 (RFC-2553) 109275970Scyis detected, support for the IPv6 address family is generated 110275970Scyin addition to the default support of the IPv4 address family. 111298770SdelphijIn a few cases, including the 112298770Sdelphij@code{reslist} 113298770Sdelphijbillboard generated 114298770Sdelphijby 115298770Sdelphij@code{ntpq(1ntpqmdoc)} 116298770Sdelphijor 117298770Sdelphij@code{ntpdc(1ntpdcmdoc)}, 118298770SdelphijIPv6 addresses are automatically generated. 119275970ScyIPv6 addresses can be identified by the presence of colons 120275970Scy@quotedblleft{}:@quotedblright{} 121275970Scyin the address field. 122275970ScyIPv6 addresses can be used almost everywhere where 123275970ScyIPv4 addresses can be used, 124275970Scywith the exception of reference clock addresses, 125275970Scywhich are always IPv4. 126275970Scy 127275970ScyNote that in contexts where a host name is expected, a 128275970Scy@code{-4} 129275970Scyqualifier preceding 130275970Scythe host name forces DNS resolution to the IPv4 namespace, 131275970Scywhile a 132275970Scy@code{-6} 133275970Scyqualifier forces DNS resolution to the IPv6 namespace. 134275970ScySee IPv6 references for the 135275970Scyequivalent classes for that address family. 136275970Scy@table @asis 137275970Scy@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}]} 138298770Sdelphij@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}]} @code{[@code{true}]} 139298770Sdelphij@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}]} @code{[@code{true}]} @code{[@code{xleave}]} 140298770Sdelphij@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}]} @code{[@code{xleave}]} 141275970Scy@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}]} 142275970Scy@end table 143275970Scy 144275970ScyThese five commands specify the time server name or address to 145275970Scybe used and the mode in which to operate. 146275970ScyThe 147275970Scy@kbd{address} 148275970Scycan be 149275970Scyeither a DNS name or an IP address in dotted-quad notation. 150275970ScyAdditional information on association behavior can be found in the 151275970Scy"Association Management" 152275970Scypage 153275970Scy(available as part of the HTML documentation 154275970Scyprovided in 155275970Scy@file{/usr/share/doc/ntp}). 156275970Scy@table @asis 157275970Scy@item @code{pool} 158275970ScyFor type s addresses, this command mobilizes a persistent 159275970Scyclient mode association with a number of remote servers. 160275970ScyIn this mode the local clock can synchronized to the 161275970Scyremote server, but the remote server can never be synchronized to 162275970Scythe local clock. 163275970Scy@item @code{server} 164275970ScyFor type s and r addresses, this command mobilizes a persistent 165275970Scyclient mode association with the specified remote server or local 166275970Scyradio clock. 167275970ScyIn this mode the local clock can synchronized to the 168275970Scyremote server, but the remote server can never be synchronized to 169275970Scythe local clock. 170275970ScyThis command should 171275970Scy@emph{not} 172275970Scybe used for type 173275970Scyb or m addresses. 174275970Scy@item @code{peer} 175275970ScyFor type s addresses (only), this command mobilizes a 176275970Scypersistent symmetric-active mode association with the specified 177275970Scyremote peer. 178275970ScyIn this mode the local clock can be synchronized to 179275970Scythe remote peer or the remote peer can be synchronized to the local 180275970Scyclock. 181275970ScyThis is useful in a network of servers where, depending on 182275970Scyvarious failure scenarios, either the local or remote peer may be 183275970Scythe better source of time. 184275970ScyThis command should NOT be used for type 185275970Scyb, m or r addresses. 186275970Scy@item @code{broadcast} 187275970ScyFor type b and m addresses (only), this 188275970Scycommand mobilizes a persistent broadcast mode association. 189275970ScyMultiple 190275970Scycommands can be used to specify multiple local broadcast interfaces 191275970Scy(subnets) and/or multiple multicast groups. 192275970ScyNote that local 193275970Scybroadcast messages go only to the interface associated with the 194275970Scysubnet specified, but multicast messages go to all interfaces. 195275970ScyIn broadcast mode the local server sends periodic broadcast 196275970Scymessages to a client population at the 197275970Scy@kbd{address} 198275970Scyspecified, which is usually the broadcast address on (one of) the 199275970Scylocal network(s) or a multicast address assigned to NTP. 200275970ScyThe IANA 201275970Scyhas assigned the multicast group address IPv4 224.0.1.1 and 202275970ScyIPv6 ff05::101 (site local) exclusively to 203275970ScyNTP, but other nonconflicting addresses can be used to contain the 204275970Scymessages within administrative boundaries. 205275970ScyOrdinarily, this 206275970Scyspecification applies only to the local server operating as a 207275970Scysender; for operation as a broadcast client, see the 208275970Scy@code{broadcastclient} 209275970Scyor 210275970Scy@code{multicastclient} 211275970Scycommands 212275970Scybelow. 213275970Scy@item @code{manycastclient} 214275970ScyFor type m addresses (only), this command mobilizes a 215275970Scymanycast client mode association for the multicast address 216275970Scyspecified. 217275970ScyIn this case a specific address must be supplied which 218275970Scymatches the address used on the 219275970Scy@code{manycastserver} 220275970Scycommand for 221275970Scythe designated manycast servers. 222275970ScyThe NTP multicast address 223275970Scy224.0.1.1 assigned by the IANA should NOT be used, unless specific 224275970Scymeans are taken to avoid spraying large areas of the Internet with 225275970Scythese messages and causing a possibly massive implosion of replies 226275970Scyat the sender. 227275970ScyThe 228275970Scy@code{manycastserver} 229275970Scycommand specifies that the local server 230275970Scyis to operate in client mode with the remote servers that are 231275970Scydiscovered as the result of broadcast/multicast messages. 232275970ScyThe 233275970Scyclient broadcasts a request message to the group address associated 234275970Scywith the specified 235275970Scy@kbd{address} 236275970Scyand specifically enabled 237275970Scyservers respond to these messages. 238275970ScyThe client selects the servers 239275970Scyproviding the best time and continues as with the 240275970Scy@code{server} 241275970Scycommand. 242275970ScyThe remaining servers are discarded as if never 243275970Scyheard. 244275970Scy@end table 245275970Scy 246275970ScyOptions: 247275970Scy@table @asis 248275970Scy@item @code{autokey} 249275970ScyAll packets sent to and received from the server or peer are to 250275970Scyinclude authentication fields encrypted using the autokey scheme 251275970Scydescribed in 252275970Scy@ref{Authentication Options}. 253275970Scy@item @code{burst} 254275970Scywhen the server is reachable, send a burst of eight packets 255275970Scyinstead of the usual one. 256275970ScyThe packet spacing is normally 2 s; 257275970Scyhowever, the spacing between the first and second packets 258298770Sdelphijcan be changed with the 259298770Sdelphij@code{calldelay} 260298770Sdelphijcommand to allow 261275970Scyadditional time for a modem or ISDN call to complete. 262275970ScyThis is designed to improve timekeeping quality 263275970Scywith the 264275970Scy@code{server} 265275970Scycommand and s addresses. 266275970Scy@item @code{iburst} 267275970ScyWhen the server is unreachable, send a burst of eight packets 268275970Scyinstead of the usual one. 269275970ScyThe packet spacing is normally 2 s; 270275970Scyhowever, the spacing between the first two packets can be 271298770Sdelphijchanged with the 272298770Sdelphij@code{calldelay} 273298770Sdelphijcommand to allow 274275970Scyadditional time for a modem or ISDN call to complete. 275275970ScyThis is designed to speed the initial synchronization 276275970Scyacquisition with the 277275970Scy@code{server} 278275970Scycommand and s addresses and when 279275970Scy@code{ntpd(1ntpdmdoc)} 280275970Scyis started with the 281275970Scy@code{-q} 282275970Scyoption. 283275970Scy@item @code{key} @kbd{key} 284275970ScyAll packets sent to and received from the server or peer are to 285275970Scyinclude authentication fields encrypted using the specified 286275970Scy@kbd{key} 287275970Scyidentifier with values from 1 to 65534, inclusive. 288275970ScyThe 289275970Scydefault is to include no encryption field. 290275970Scy@item @code{minpoll} @kbd{minpoll} 291275970Scy@item @code{maxpoll} @kbd{maxpoll} 292275970ScyThese options specify the minimum and maximum poll intervals 293275970Scyfor NTP messages, as a power of 2 in seconds 294275970ScyThe maximum poll 295275970Scyinterval defaults to 10 (1,024 s), but can be increased by the 296275970Scy@code{maxpoll} 297275970Scyoption to an upper limit of 17 (36.4 h). 298275970ScyThe 299275970Scyminimum poll interval defaults to 6 (64 s), but can be decreased by 300275970Scythe 301275970Scy@code{minpoll} 302275970Scyoption to a lower limit of 4 (16 s). 303275970Scy@item @code{noselect} 304275970ScyMarks the server as unused, except for display purposes. 305275970ScyThe server is discarded by the selection algroithm. 306298770Sdelphij@item @code{preempt} 307298770SdelphijSays the association can be preempted. 308298770Sdelphij@item @code{true} 309298770SdelphijMarks the server as a truechimer. 310298770SdelphijUse this option only for testing. 311275970Scy@item @code{prefer} 312275970ScyMarks the server as preferred. 313275970ScyAll other things being equal, 314275970Scythis host will be chosen for synchronization among a set of 315275970Scycorrectly operating hosts. 316275970ScySee the 317275970Scy"Mitigation Rules and the prefer Keyword" 318275970Scypage 319275970Scy(available as part of the HTML documentation 320275970Scyprovided in 321275970Scy@file{/usr/share/doc/ntp}) 322275970Scyfor further information. 323298770Sdelphij@item @code{true} 324298770SdelphijForces the association to always survive the selection and clustering algorithms. 325298770SdelphijThis option should almost certainly 326298770Sdelphij@emph{only} 327298770Sdelphijbe used while testing an association. 328275970Scy@item @code{ttl} @kbd{ttl} 329275970ScyThis option is used only with broadcast server and manycast 330275970Scyclient modes. 331275970ScyIt specifies the time-to-live 332275970Scy@kbd{ttl} 333275970Scyto 334275970Scyuse on broadcast server and multicast server and the maximum 335275970Scy@kbd{ttl} 336275970Scyfor the expanding ring search with manycast 337275970Scyclient packets. 338275970ScySelection of the proper value, which defaults to 339275970Scy127, is something of a black art and should be coordinated with the 340275970Scynetwork administrator. 341275970Scy@item @code{version} @kbd{version} 342275970ScySpecifies the version number to be used for outgoing NTP 343275970Scypackets. 344275970ScyVersions 1-4 are the choices, with version 4 the 345275970Scydefault. 346298770Sdelphij@item @code{xleave} 347298770SdelphijValid in 348298770Sdelphij@code{peer} 349298770Sdelphijand 350298770Sdelphij@code{broadcast} 351298770Sdelphijmodes only, this flag enables interleave mode. 352275970Scy@end table 353275970Scy@subsubsection Auxiliary Commands 354275970Scy@table @asis 355275970Scy@item @code{broadcastclient} 356275970ScyThis command enables reception of broadcast server messages to 357275970Scyany local interface (type b) address. 358275970ScyUpon receiving a message for 359275970Scythe first time, the broadcast client measures the nominal server 360275970Scypropagation delay using a brief client/server exchange with the 361275970Scyserver, then enters the broadcast client mode, in which it 362275970Scysynchronizes to succeeding broadcast messages. 363275970ScyNote that, in order 364275970Scyto avoid accidental or malicious disruption in this mode, both the 365275970Scyserver and client should operate using symmetric-key or public-key 366275970Scyauthentication as described in 367275970Scy@ref{Authentication Options}. 368275970Scy@item @code{manycastserver} @kbd{address} @kbd{...} 369275970ScyThis command enables reception of manycast client messages to 370275970Scythe multicast group address(es) (type m) specified. 371275970ScyAt least one 372275970Scyaddress is required, but the NTP multicast address 224.0.1.1 373275970Scyassigned by the IANA should NOT be used, unless specific means are 374275970Scytaken to limit the span of the reply and avoid a possibly massive 375275970Scyimplosion at the original sender. 376275970ScyNote that, in order to avoid 377275970Scyaccidental or malicious disruption in this mode, both the server 378275970Scyand client should operate using symmetric-key or public-key 379275970Scyauthentication as described in 380275970Scy@ref{Authentication Options}. 381275970Scy@item @code{multicastclient} @kbd{address} @kbd{...} 382275970ScyThis command enables reception of multicast server messages to 383275970Scythe multicast group address(es) (type m) specified. 384275970ScyUpon receiving 385275970Scya message for the first time, the multicast client measures the 386275970Scynominal server propagation delay using a brief client/server 387275970Scyexchange with the server, then enters the broadcast client mode, in 388275970Scywhich it synchronizes to succeeding multicast messages. 389275970ScyNote that, 390275970Scyin order to avoid accidental or malicious disruption in this mode, 391275970Scyboth the server and client should operate using symmetric-key or 392275970Scypublic-key authentication as described in 393275970Scy@ref{Authentication Options}. 394280849Scy@item @code{mdnstries} @kbd{number} 395280849ScyIf we are participating in mDNS, 396280849Scyafter we have synched for the first time 397280849Scywe attempt to register with the mDNS system. 398280849ScyIf that registration attempt fails, 399280849Scywe try again at one minute intervals for up to 400280849Scy@code{mdnstries} 401280849Scytimes. 402280849ScyAfter all, 403280849Scy@code{ntpd} 404280849Scymay be starting before mDNS. 405280849ScyThe default value for 406280849Scy@code{mdnstries} 407280849Scyis 5. 408275970Scy@end table 409275970Scy@node Authentication Support 410275970Scy@subsection Authentication Support 411275970ScyAuthentication support allows the NTP client to verify that the 412275970Scyserver is in fact known and trusted and not an intruder intending 413275970Scyaccidentally or on purpose to masquerade as that server. 414275970ScyThe NTPv3 415275970Scyspecification RFC-1305 defines a scheme which provides 416275970Scycryptographic authentication of received NTP packets. 417275970ScyOriginally, 418275970Scythis was done using the Data Encryption Standard (DES) algorithm 419275970Scyoperating in Cipher Block Chaining (CBC) mode, commonly called 420275970ScyDES-CBC. 421275970ScySubsequently, this was replaced by the RSA Message Digest 422275970Scy5 (MD5) algorithm using a private key, commonly called keyed-MD5. 423275970ScyEither algorithm computes a message digest, or one-way hash, which 424275970Scycan be used to verify the server has the correct private key and 425275970Scykey identifier. 426275970Scy 427275970ScyNTPv4 retains the NTPv3 scheme, properly described as symmetric key 428275970Scycryptography and, in addition, provides a new Autokey scheme 429275970Scybased on public key cryptography. 430275970ScyPublic key cryptography is generally considered more secure 431275970Scythan symmetric key cryptography, since the security is based 432275970Scyon a private value which is generated by each server and 433275970Scynever revealed. 434275970ScyWith Autokey all key distribution and 435275970Scymanagement functions involve only public values, which 436275970Scyconsiderably simplifies key distribution and storage. 437275970ScyPublic key management is based on X.509 certificates, 438275970Scywhich can be provided by commercial services or 439275970Scyproduced by utility programs in the OpenSSL software library 440275970Scyor the NTPv4 distribution. 441275970Scy 442275970ScyWhile the algorithms for symmetric key cryptography are 443275970Scyincluded in the NTPv4 distribution, public key cryptography 444275970Scyrequires the OpenSSL software library to be installed 445275970Scybefore building the NTP distribution. 446275970ScyDirections for doing that 447275970Scyare on the Building and Installing the Distribution page. 448275970Scy 449275970ScyAuthentication is configured separately for each association 450275970Scyusing the 451275970Scy@code{key} 452275970Scyor 453275970Scy@code{autokey} 454275970Scysubcommand on the 455275970Scy@code{peer}, 456275970Scy@code{server}, 457275970Scy@code{broadcast} 458275970Scyand 459275970Scy@code{manycastclient} 460275970Scyconfiguration commands as described in 461275970Scy@ref{Configuration Options} 462275970Scypage. 463275970ScyThe authentication 464275970Scyoptions described below specify the locations of the key files, 465275970Scyif other than default, which symmetric keys are trusted 466275970Scyand the interval between various operations, if other than default. 467275970Scy 468275970ScyAuthentication is always enabled, 469275970Scyalthough ineffective if not configured as 470275970Scydescribed below. 471275970ScyIf a NTP packet arrives 472275970Scyincluding a message authentication 473275970Scycode (MAC), it is accepted only if it 474275970Scypasses all cryptographic checks. 475275970ScyThe 476275970Scychecks require correct key ID, key value 477275970Scyand message digest. 478275970ScyIf the packet has 479275970Scybeen modified in any way or replayed 480275970Scyby an intruder, it will fail one or more 481275970Scyof these checks and be discarded. 482275970ScyFurthermore, the Autokey scheme requires a 483275970Scypreliminary protocol exchange to obtain 484275970Scythe server certificate, verify its 485275970Scycredentials and initialize the protocol 486275970Scy 487275970ScyThe 488275970Scy@code{auth} 489275970Scyflag controls whether new associations or 490275970Scyremote configuration commands require cryptographic authentication. 491275970ScyThis flag can be set or reset by the 492275970Scy@code{enable} 493275970Scyand 494275970Scy@code{disable} 495275970Scycommands and also by remote 496275970Scyconfiguration commands sent by a 497275970Scy@code{ntpdc(1ntpdcmdoc)} 498298770Sdelphijprogram running on 499275970Scyanother machine. 500275970ScyIf this flag is enabled, which is the default 501275970Scycase, new broadcast client and symmetric passive associations and 502275970Scyremote configuration commands must be cryptographically 503275970Scyauthenticated using either symmetric key or public key cryptography. 504275970ScyIf this 505275970Scyflag is disabled, these operations are effective 506275970Scyeven if not cryptographic 507275970Scyauthenticated. 508275970ScyIt should be understood 509275970Scythat operating with the 510275970Scy@code{auth} 511275970Scyflag disabled invites a significant vulnerability 512275970Scywhere a rogue hacker can 513275970Scymasquerade as a falseticker and seriously 514275970Scydisrupt system timekeeping. 515275970ScyIt is 516275970Scyimportant to note that this flag has no purpose 517275970Scyother than to allow or disallow 518275970Scya new association in response to new broadcast 519275970Scyand symmetric active messages 520275970Scyand remote configuration commands and, in particular, 521275970Scythe flag has no effect on 522275970Scythe authentication process itself. 523275970Scy 524275970ScyAn attractive alternative where multicast support is available 525275970Scyis manycast mode, in which clients periodically troll 526275970Scyfor servers as described in the 527275970Scy@ref{Automatic NTP Configuration Options} 528275970Scypage. 529275970ScyEither symmetric key or public key 530275970Scycryptographic authentication can be used in this mode. 531275970ScyThe principle advantage 532275970Scyof manycast mode is that potential servers need not be 533275970Scyconfigured in advance, 534275970Scysince the client finds them during regular operation, 535275970Scyand the configuration 536275970Scyfiles for all clients can be identical. 537275970Scy 538275970ScyThe security model and protocol schemes for 539275970Scyboth symmetric key and public key 540275970Scycryptography are summarized below; 541275970Scyfurther details are in the briefings, papers 542275970Scyand reports at the NTP project page linked from 543275970Scy@code{http://www.ntp.org/}. 544275970Scy@subsubsection Symmetric-Key Cryptography 545275970ScyThe original RFC-1305 specification allows any one of possibly 546275970Scy65,534 keys, each distinguished by a 32-bit key identifier, to 547275970Scyauthenticate an association. 548275970ScyThe servers and clients involved must 549275970Scyagree on the key and key identifier to 550275970Scyauthenticate NTP packets. 551275970ScyKeys and 552275970Scyrelated information are specified in a key 553275970Scyfile, usually called 554275970Scy@file{ntp.keys}, 555275970Scywhich must be distributed and stored using 556275970Scysecure means beyond the scope of the NTP protocol itself. 557275970ScyBesides the keys used 558275970Scyfor ordinary NTP associations, 559275970Scyadditional keys can be used as passwords for the 560275970Scy@code{ntpq(1ntpqmdoc)} 561275970Scyand 562275970Scy@code{ntpdc(1ntpdcmdoc)} 563275970Scyutility programs. 564275970Scy 565275970ScyWhen 566275970Scy@code{ntpd(1ntpdmdoc)} 567275970Scyis first started, it reads the key file specified in the 568275970Scy@code{keys} 569275970Scyconfiguration command and installs the keys 570275970Scyin the key cache. 571275970ScyHowever, 572275970Scyindividual keys must be activated with the 573275970Scy@code{trusted} 574275970Scycommand before use. 575275970ScyThis 576275970Scyallows, for instance, the installation of possibly 577275970Scyseveral batches of keys and 578275970Scythen activating or deactivating each batch 579275970Scyremotely using 580275970Scy@code{ntpdc(1ntpdcmdoc)}. 581275970ScyThis also provides a revocation capability that can be used 582275970Scyif a key becomes compromised. 583275970ScyThe 584275970Scy@code{requestkey} 585275970Scycommand selects the key used as the password for the 586275970Scy@code{ntpdc(1ntpdcmdoc)} 587275970Scyutility, while the 588275970Scy@code{controlkey} 589275970Scycommand selects the key used as the password for the 590275970Scy@code{ntpq(1ntpqmdoc)} 591275970Scyutility. 592275970Scy@subsubsection Public Key Cryptography 593275970ScyNTPv4 supports the original NTPv3 symmetric key scheme 594275970Scydescribed in RFC-1305 and in addition the Autokey protocol, 595275970Scywhich is based on public key cryptography. 596275970ScyThe Autokey Version 2 protocol described on the Autokey Protocol 597275970Scypage verifies packet integrity using MD5 message digests 598275970Scyand verifies the source with digital signatures and any of several 599275970Scydigest/signature schemes. 600275970ScyOptional identity schemes described on the Identity Schemes 601275970Scypage and based on cryptographic challenge/response algorithms 602275970Scyare also available. 603275970ScyUsing all of these schemes provides strong security against 604275970Scyreplay with or without modification, spoofing, masquerade 605275970Scyand most forms of clogging attacks. 606275970Scy 607275970ScyThe Autokey protocol has several modes of operation 608275970Scycorresponding to the various NTP modes supported. 609275970ScyMost modes use a special cookie which can be 610275970Scycomputed independently by the client and server, 611275970Scybut encrypted in transmission. 612275970ScyAll modes use in addition a variant of the S-KEY scheme, 613275970Scyin which a pseudo-random key list is generated and used 614275970Scyin reverse order. 615275970ScyThese schemes are described along with an executive summary, 616275970Scycurrent status, briefing slides and reading list on the 617275970Scy@ref{Autonomous Authentication} 618275970Scypage. 619275970Scy 620275970ScyThe specific cryptographic environment used by Autokey servers 621275970Scyand clients is determined by a set of files 622275970Scyand soft links generated by the 623275970Scy@code{ntp-keygen(1ntpkeygenmdoc)} 624275970Scyprogram. 625275970ScyThis includes a required host key file, 626275970Scyrequired certificate file and optional sign key file, 627275970Scyleapsecond file and identity scheme files. 628275970ScyThe 629275970Scydigest/signature scheme is specified in the X.509 certificate 630275970Scyalong with the matching sign key. 631275970ScyThere are several schemes 632275970Scyavailable in the OpenSSL software library, each identified 633275970Scyby a specific string such as 634275970Scy@code{md5WithRSAEncryption}, 635275970Scywhich stands for the MD5 message digest with RSA 636275970Scyencryption scheme. 637275970ScyThe current NTP distribution supports 638275970Scyall the schemes in the OpenSSL library, including 639275970Scythose based on RSA and DSA digital signatures. 640275970Scy 641275970ScyNTP secure groups can be used to define cryptographic compartments 642275970Scyand security hierarchies. 643275970ScyIt is important that every host 644275970Scyin the group be able to construct a certificate trail to one 645275970Scyor more trusted hosts in the same group. 646275970ScyEach group 647275970Scyhost runs the Autokey protocol to obtain the certificates 648275970Scyfor all hosts along the trail to one or more trusted hosts. 649275970ScyThis requires the configuration file in all hosts to be 650275970Scyengineered so that, even under anticipated failure conditions, 651275970Scythe NTP subnet will form such that every group host can find 652275970Scya trail to at least one trusted host. 653275970Scy@subsubsection Naming and Addressing 654275970ScyIt is important to note that Autokey does not use DNS to 655275970Scyresolve addresses, since DNS can't be completely trusted 656275970Scyuntil the name servers have synchronized clocks. 657275970ScyThe cryptographic name used by Autokey to bind the host identity 658275970Scycredentials and cryptographic values must be independent 659275970Scyof interface, network and any other naming convention. 660275970ScyThe name appears in the host certificate in either or both 661275970Scythe subject and issuer fields, so protection against 662275970ScyDNS compromise is essential. 663275970Scy 664275970ScyBy convention, the name of an Autokey host is the name returned 665275970Scyby the Unix 666275970Scy@code{gethostname(2)} 667275970Scysystem call or equivalent in other systems. 668275970ScyBy the system design 669275970Scymodel, there are no provisions to allow alternate names or aliases. 670275970ScyHowever, this is not to say that DNS aliases, different names 671275970Scyfor each interface, etc., are constrained in any way. 672275970Scy 673275970ScyIt is also important to note that Autokey verifies authenticity 674275970Scyusing the host name, network address and public keys, 675275970Scyall of which are bound together by the protocol specifically 676275970Scyto deflect masquerade attacks. 677275970ScyFor this reason Autokey 678298770Sdelphijincludes the source and destination IP addresses in message digest 679275970Scycomputations and so the same addresses must be available 680275970Scyat both the server and client. 681275970ScyFor this reason operation 682275970Scywith network address translation schemes is not possible. 683275970ScyThis reflects the intended robust security model where government 684275970Scyand corporate NTP servers are operated outside firewall perimeters. 685275970Scy@subsubsection Operation 686275970ScyA specific combination of authentication scheme (none, 687275970Scysymmetric key, public key) and identity scheme is called 688275970Scya cryptotype, although not all combinations are compatible. 689275970ScyThere may be management configurations where the clients, 690275970Scyservers and peers may not all support the same cryptotypes. 691275970ScyA secure NTPv4 subnet can be configured in many ways while 692275970Scykeeping in mind the principles explained above and 693275970Scyin this section. 694275970ScyNote however that some cryptotype 695275970Scycombinations may successfully interoperate with each other, 696275970Scybut may not represent good security practice. 697275970Scy 698275970ScyThe cryptotype of an association is determined at the time 699275970Scyof mobilization, either at configuration time or some time 700275970Scylater when a message of appropriate cryptotype arrives. 701275970ScyWhen mobilized by a 702275970Scy@code{server} 703275970Scyor 704275970Scy@code{peer} 705275970Scyconfiguration command and no 706275970Scy@code{key} 707275970Scyor 708275970Scy@code{autokey} 709275970Scysubcommands are present, the association is not 710275970Scyauthenticated; if the 711275970Scy@code{key} 712275970Scysubcommand is present, the association is authenticated 713275970Scyusing the symmetric key ID specified; if the 714275970Scy@code{autokey} 715275970Scysubcommand is present, the association is authenticated 716275970Scyusing Autokey. 717275970Scy 718275970ScyWhen multiple identity schemes are supported in the Autokey 719275970Scyprotocol, the first message exchange determines which one is used. 720275970ScyThe client request message contains bits corresponding 721275970Scyto which schemes it has available. 722275970ScyThe server response message 723275970Scycontains bits corresponding to which schemes it has available. 724275970ScyBoth server and client match the received bits with their own 725275970Scyand select a common scheme. 726275970Scy 727275970ScyFollowing the principle that time is a public value, 728275970Scya server responds to any client packet that matches 729275970Scyits cryptotype capabilities. 730275970ScyThus, a server receiving 731275970Scyan unauthenticated packet will respond with an unauthenticated 732275970Scypacket, while the same server receiving a packet of a cryptotype 733275970Scyit supports will respond with packets of that cryptotype. 734275970ScyHowever, unconfigured broadcast or manycast client 735275970Scyassociations or symmetric passive associations will not be 736275970Scymobilized unless the server supports a cryptotype compatible 737275970Scywith the first packet received. 738275970ScyBy default, unauthenticated associations will not be mobilized 739275970Scyunless overridden in a decidedly dangerous way. 740275970Scy 741275970ScySome examples may help to reduce confusion. 742275970ScyClient Alice has no specific cryptotype selected. 743275970ScyServer Bob has both a symmetric key file and minimal Autokey files. 744275970ScyAlice's unauthenticated messages arrive at Bob, who replies with 745275970Scyunauthenticated messages. 746275970ScyCathy has a copy of Bob's symmetric 747275970Scykey file and has selected key ID 4 in messages to Bob. 748275970ScyBob verifies the message with his key ID 4. 749275970ScyIf it's the 750275970Scysame key and the message is verified, Bob sends Cathy a reply 751275970Scyauthenticated with that key. 752275970ScyIf verification fails, 753275970ScyBob sends Cathy a thing called a crypto-NAK, which tells her 754275970Scysomething broke. 755275970ScyShe can see the evidence using the 756275970Scy@code{ntpq(1ntpqmdoc)} 757275970Scyprogram. 758275970Scy 759275970ScyDenise has rolled her own host key and certificate. 760275970ScyShe also uses one of the identity schemes as Bob. 761275970ScyShe sends the first Autokey message to Bob and they 762275970Scyboth dance the protocol authentication and identity steps. 763275970ScyIf all comes out okay, Denise and Bob continue as described above. 764275970Scy 765275970ScyIt should be clear from the above that Bob can support 766275970Scyall the girls at the same time, as long as he has compatible 767275970Scyauthentication and identity credentials. 768275970ScyNow, Bob can act just like the girls in his own choice of servers; 769275970Scyhe can run multiple configured associations with multiple different 770275970Scyservers (or the same server, although that might not be useful). 771275970ScyBut, wise security policy might preclude some cryptotype 772275970Scycombinations; for instance, running an identity scheme 773275970Scywith one server and no authentication with another might not be wise. 774275970Scy@subsubsection Key Management 775275970ScyThe cryptographic values used by the Autokey protocol are 776275970Scyincorporated as a set of files generated by the 777275970Scy@code{ntp-keygen(1ntpkeygenmdoc)} 778275970Scyutility program, including symmetric key, host key and 779275970Scypublic certificate files, as well as sign key, identity parameters 780275970Scyand leapseconds files. 781275970ScyAlternatively, host and sign keys and 782275970Scycertificate files can be generated by the OpenSSL utilities 783275970Scyand certificates can be imported from public certificate 784275970Scyauthorities. 785275970ScyNote that symmetric keys are necessary for the 786275970Scy@code{ntpq(1ntpqmdoc)} 787275970Scyand 788275970Scy@code{ntpdc(1ntpdcmdoc)} 789275970Scyutility programs. 790275970ScyThe remaining files are necessary only for the 791275970ScyAutokey protocol. 792275970Scy 793275970ScyCertificates imported from OpenSSL or public certificate 794275970Scyauthorities have certian limitations. 795275970ScyThe certificate should be in ASN.1 syntax, X.509 Version 3 796275970Scyformat and encoded in PEM, which is the same format 797275970Scyused by OpenSSL. 798275970ScyThe overall length of the certificate encoded 799275970Scyin ASN.1 must not exceed 1024 bytes. 800275970ScyThe subject distinguished 801275970Scyname field (CN) is the fully qualified name of the host 802275970Scyon which it is used; the remaining subject fields are ignored. 803275970ScyThe certificate extension fields must not contain either 804275970Scya subject key identifier or a issuer key identifier field; 805275970Scyhowever, an extended key usage field for a trusted host must 806275970Scycontain the value 807275970Scy@code{trustRoot};. 808275970ScyOther extension fields are ignored. 809275970Scy@subsubsection Authentication Commands 810275970Scy@table @asis 811275970Scy@item @code{autokey} @code{[@kbd{logsec}]} 812275970ScySpecifies the interval between regenerations of the session key 813275970Scylist used with the Autokey protocol. 814275970ScyNote that the size of the key 815275970Scylist for each association depends on this interval and the current 816275970Scypoll interval. 817275970ScyThe default value is 12 (4096 s or about 1.1 hours). 818275970ScyFor poll intervals above the specified interval, a session key list 819275970Scywith a single entry will be regenerated for every message 820275970Scysent. 821275970Scy@item @code{controlkey} @kbd{key} 822275970ScySpecifies the key identifier to use with the 823275970Scy@code{ntpq(1ntpqmdoc)} 824275970Scyutility, which uses the standard 825275970Scyprotocol defined in RFC-1305. 826275970ScyThe 827275970Scy@kbd{key} 828275970Scyargument is 829275970Scythe key identifier for a trusted key, where the value can be in the 830275970Scyrange 1 to 65,534, inclusive. 831275970Scy@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}]} 832275970ScyThis command requires the OpenSSL library. 833275970ScyIt activates public key 834275970Scycryptography, selects the message digest and signature 835275970Scyencryption scheme and loads the required private and public 836275970Scyvalues described above. 837275970ScyIf one or more files are left unspecified, 838275970Scythe default names are used as described above. 839275970ScyUnless the complete path and name of the file are specified, the 840275970Scylocation of a file is relative to the keys directory specified 841275970Scyin the 842275970Scy@code{keysdir} 843275970Scycommand or default 844275970Scy@file{/usr/local/etc}. 845275970ScyFollowing are the subcommands: 846275970Scy@table @asis 847275970Scy@item @code{cert} @kbd{file} 848275970ScySpecifies the location of the required host public certificate file. 849275970ScyThis overrides the link 850275970Scy@file{ntpkey_cert_}@kbd{hostname} 851275970Scyin the keys directory. 852275970Scy@item @code{gqpar} @kbd{file} 853275970ScySpecifies the location of the optional GQ parameters file. 854275970ScyThis 855275970Scyoverrides the link 856275970Scy@file{ntpkey_gq_}@kbd{hostname} 857275970Scyin the keys directory. 858275970Scy@item @code{host} @kbd{file} 859275970ScySpecifies the location of the required host key file. 860275970ScyThis overrides 861275970Scythe link 862275970Scy@file{ntpkey_key_}@kbd{hostname} 863275970Scyin the keys directory. 864275970Scy@item @code{iffpar} @kbd{file} 865298770SdelphijSpecifies the location of the optional IFF parameters file. 866298770SdelphijThis overrides the link 867275970Scy@file{ntpkey_iff_}@kbd{hostname} 868275970Scyin the keys directory. 869275970Scy@item @code{leap} @kbd{file} 870275970ScySpecifies the location of the optional leapsecond file. 871275970ScyThis overrides the link 872275970Scy@file{ntpkey_leap} 873275970Scyin the keys directory. 874275970Scy@item @code{mvpar} @kbd{file} 875275970ScySpecifies the location of the optional MV parameters file. 876298770SdelphijThis overrides the link 877275970Scy@file{ntpkey_mv_}@kbd{hostname} 878275970Scyin the keys directory. 879275970Scy@item @code{pw} @kbd{password} 880275970ScySpecifies the password to decrypt files containing private keys and 881275970Scyidentity parameters. 882275970ScyThis is required only if these files have been 883275970Scyencrypted. 884275970Scy@item @code{randfile} @kbd{file} 885275970ScySpecifies the location of the random seed file used by the OpenSSL 886275970Scylibrary. 887275970ScyThe defaults are described in the main text above. 888275970Scy@item @code{sign} @kbd{file} 889275970ScySpecifies the location of the optional sign key file. 890275970ScyThis overrides 891275970Scythe link 892275970Scy@file{ntpkey_sign_}@kbd{hostname} 893275970Scyin the keys directory. 894275970ScyIf this file is 895275970Scynot found, the host key is also the sign key. 896275970Scy@end table 897275970Scy@item @code{keys} @kbd{keyfile} 898275970ScySpecifies the complete path and location of the MD5 key file 899275970Scycontaining the keys and key identifiers used by 900275970Scy@code{ntpd(1ntpdmdoc)}, 901275970Scy@code{ntpq(1ntpqmdoc)} 902275970Scyand 903275970Scy@code{ntpdc(1ntpdcmdoc)} 904275970Scywhen operating with symmetric key cryptography. 905275970ScyThis is the same operation as the 906275970Scy@code{-k} 907275970Scycommand line option. 908275970Scy@item @code{keysdir} @kbd{path} 909275970ScyThis command specifies the default directory path for 910275970Scycryptographic keys, parameters and certificates. 911275970ScyThe default is 912275970Scy@file{/usr/local/etc/}. 913275970Scy@item @code{requestkey} @kbd{key} 914275970ScySpecifies the key identifier to use with the 915275970Scy@code{ntpdc(1ntpdcmdoc)} 916275970Scyutility program, which uses a 917275970Scyproprietary protocol specific to this implementation of 918275970Scy@code{ntpd(1ntpdmdoc)}. 919275970ScyThe 920275970Scy@kbd{key} 921275970Scyargument is a key identifier 922275970Scyfor the trusted key, where the value can be in the range 1 to 923275970Scy65,534, inclusive. 924275970Scy@item @code{revoke} @kbd{logsec} 925275970ScySpecifies the interval between re-randomization of certain 926275970Scycryptographic values used by the Autokey scheme, as a power of 2 in 927275970Scyseconds. 928275970ScyThese values need to be updated frequently in order to 929275970Scydeflect brute-force attacks on the algorithms of the scheme; 930275970Scyhowever, updating some values is a relatively expensive operation. 931275970ScyThe default interval is 16 (65,536 s or about 18 hours). 932275970ScyFor poll 933275970Scyintervals above the specified interval, the values will be updated 934275970Scyfor every message sent. 935275970Scy@item @code{trustedkey} @kbd{key} @kbd{...} 936275970ScySpecifies the key identifiers which are trusted for the 937275970Scypurposes of authenticating peers with symmetric key cryptography, 938275970Scyas well as keys used by the 939275970Scy@code{ntpq(1ntpqmdoc)} 940275970Scyand 941275970Scy@code{ntpdc(1ntpdcmdoc)} 942275970Scyprograms. 943275970ScyThe authentication procedures require that both the local 944275970Scyand remote servers share the same key and key identifier for this 945275970Scypurpose, although different keys can be used with different 946275970Scyservers. 947275970ScyThe 948275970Scy@kbd{key} 949275970Scyarguments are 32-bit unsigned 950275970Scyintegers with values from 1 to 65,534. 951275970Scy@end table 952275970Scy@subsubsection Error Codes 953275970ScyThe following error codes are reported via the NTP control 954275970Scyand monitoring protocol trap mechanism. 955275970Scy@table @asis 956275970Scy@item 101 957275970Scy(bad field format or length) 958275970ScyThe packet has invalid version, length or format. 959275970Scy@item 102 960275970Scy(bad timestamp) 961275970ScyThe packet timestamp is the same or older than the most recent received. 962275970ScyThis could be due to a replay or a server clock time step. 963275970Scy@item 103 964275970Scy(bad filestamp) 965275970ScyThe packet filestamp is the same or older than the most recent received. 966275970ScyThis could be due to a replay or a key file generation error. 967275970Scy@item 104 968275970Scy(bad or missing public key) 969275970ScyThe public key is missing, has incorrect format or is an unsupported type. 970275970Scy@item 105 971275970Scy(unsupported digest type) 972275970ScyThe server requires an unsupported digest/signature scheme. 973275970Scy@item 106 974275970Scy(mismatched digest types) 975275970ScyNot used. 976275970Scy@item 107 977275970Scy(bad signature length) 978275970ScyThe signature length does not match the current public key. 979275970Scy@item 108 980275970Scy(signature not verified) 981275970ScyThe message fails the signature check. 982275970ScyIt could be bogus or signed by a 983275970Scydifferent private key. 984275970Scy@item 109 985275970Scy(certificate not verified) 986275970ScyThe certificate is invalid or signed with the wrong key. 987275970Scy@item 110 988275970Scy(certificate not verified) 989275970ScyThe certificate is not yet valid or has expired or the signature could not 990275970Scybe verified. 991275970Scy@item 111 992275970Scy(bad or missing cookie) 993275970ScyThe cookie is missing, corrupted or bogus. 994275970Scy@item 112 995275970Scy(bad or missing leapseconds table) 996275970ScyThe leapseconds table is missing, corrupted or bogus. 997275970Scy@item 113 998275970Scy(bad or missing certificate) 999275970ScyThe certificate is missing, corrupted or bogus. 1000275970Scy@item 114 1001275970Scy(bad or missing identity) 1002275970ScyThe identity key is missing, corrupt or bogus. 1003275970Scy@end table 1004275970Scy@node Monitoring Support 1005275970Scy@subsection Monitoring Support 1006275970Scy@code{ntpd(1ntpdmdoc)} 1007275970Scyincludes a comprehensive monitoring facility suitable 1008275970Scyfor continuous, long term recording of server and client 1009275970Scytimekeeping performance. 1010275970ScySee the 1011275970Scy@code{statistics} 1012275970Scycommand below 1013275970Scyfor a listing and example of each type of statistics currently 1014275970Scysupported. 1015275970ScyStatistic files are managed using file generation sets 1016275970Scyand scripts in the 1017275970Scy@file{./scripts} 1018298770Sdelphijdirectory of the source code distribution. 1019275970ScyUsing 1020275970Scythese facilities and 1021275970Scy@sc{unix} 1022275970Scy@code{cron(8)} 1023275970Scyjobs, the data can be 1024275970Scyautomatically summarized and archived for retrospective analysis. 1025275970Scy@subsubsection Monitoring Commands 1026275970Scy@table @asis 1027275970Scy@item @code{statistics} @kbd{name} @kbd{...} 1028275970ScyEnables writing of statistics records. 1029275970ScyCurrently, eight kinds of 1030275970Scy@kbd{name} 1031275970Scystatistics are supported. 1032275970Scy@table @asis 1033275970Scy@item @code{clockstats} 1034275970ScyEnables recording of clock driver statistics information. 1035275970ScyEach update 1036275970Scyreceived from a clock driver appends a line of the following form to 1037275970Scythe file generation set named 1038275970Scy@code{clockstats}: 1039275970Scy@verbatim 1040275970Scy49213 525.624 127.127.4.1 93 226 00:08:29.606 D 1041275970Scy@end verbatim 1042275970Scy 1043275970ScyThe first two fields show the date (Modified Julian Day) and time 1044275970Scy(seconds and fraction past UTC midnight). 1045275970ScyThe next field shows the 1046275970Scyclock address in dotted-quad notation. 1047275970ScyThe final field shows the last 1048275970Scytimecode received from the clock in decoded ASCII format, where 1049275970Scymeaningful. 1050275970ScyIn some clock drivers a good deal of additional information 1051275970Scycan be gathered and displayed as well. 1052275970ScySee information specific to each 1053275970Scyclock for further details. 1054275970Scy@item @code{cryptostats} 1055275970ScyThis option requires the OpenSSL cryptographic software library. 1056275970ScyIt 1057275970Scyenables recording of cryptographic public key protocol information. 1058275970ScyEach message received by the protocol module appends a line of the 1059275970Scyfollowing form to the file generation set named 1060275970Scy@code{cryptostats}: 1061275970Scy@verbatim 1062275970Scy49213 525.624 127.127.4.1 message 1063275970Scy@end verbatim 1064275970Scy 1065275970ScyThe first two fields show the date (Modified Julian Day) and time 1066275970Scy(seconds and fraction past UTC midnight). 1067275970ScyThe next field shows the peer 1068275970Scyaddress in dotted-quad notation, The final message field includes the 1069275970Scymessage type and certain ancillary information. 1070275970ScySee the 1071275970Scy@ref{Authentication Options} 1072275970Scysection for further information. 1073275970Scy@item @code{loopstats} 1074275970ScyEnables recording of loop filter statistics information. 1075275970ScyEach 1076275970Scyupdate of the local clock outputs a line of the following form to 1077275970Scythe file generation set named 1078275970Scy@code{loopstats}: 1079275970Scy@verbatim 1080275970Scy50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 1081275970Scy@end verbatim 1082275970Scy 1083275970ScyThe first two fields show the date (Modified Julian Day) and 1084275970Scytime (seconds and fraction past UTC midnight). 1085275970ScyThe next five fields 1086275970Scyshow time offset (seconds), frequency offset (parts per million - 1087275970ScyPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 1088275970Scydiscipline time constant. 1089275970Scy@item @code{peerstats} 1090275970ScyEnables recording of peer statistics information. 1091275970ScyThis includes 1092275970Scystatistics records of all peers of a NTP server and of special 1093275970Scysignals, where present and configured. 1094275970ScyEach valid update appends a 1095275970Scyline of the following form to the current element of a file 1096275970Scygeneration set named 1097275970Scy@code{peerstats}: 1098275970Scy@verbatim 1099275970Scy48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 1100275970Scy@end verbatim 1101275970Scy 1102275970ScyThe first two fields show the date (Modified Julian Day) and 1103275970Scytime (seconds and fraction past UTC midnight). 1104275970ScyThe next two fields 1105275970Scyshow the peer address in dotted-quad notation and status, 1106275970Scyrespectively. 1107275970ScyThe status field is encoded in hex in the format 1108275970Scydescribed in Appendix A of the NTP specification RFC 1305. 1109275970ScyThe final four fields show the offset, 1110275970Scydelay, dispersion and RMS jitter, all in seconds. 1111275970Scy@item @code{rawstats} 1112275970ScyEnables recording of raw-timestamp statistics information. 1113275970ScyThis 1114275970Scyincludes statistics records of all peers of a NTP server and of 1115275970Scyspecial signals, where present and configured. 1116275970ScyEach NTP message 1117275970Scyreceived from a peer or clock driver appends a line of the 1118275970Scyfollowing form to the file generation set named 1119275970Scy@code{rawstats}: 1120275970Scy@verbatim 1121275970Scy50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 1122275970Scy@end verbatim 1123275970Scy 1124275970ScyThe first two fields show the date (Modified Julian Day) and 1125275970Scytime (seconds and fraction past UTC midnight). 1126275970ScyThe next two fields 1127275970Scyshow the remote peer or clock address followed by the local address 1128275970Scyin dotted-quad notation. 1129275970ScyThe final four fields show the originate, 1130275970Scyreceive, transmit and final NTP timestamps in order. 1131275970ScyThe timestamp 1132275970Scyvalues are as received and before processing by the various data 1133275970Scysmoothing and mitigation algorithms. 1134275970Scy@item @code{sysstats} 1135275970ScyEnables recording of ntpd statistics counters on a periodic basis. 1136275970ScyEach 1137275970Scyhour a line of the following form is appended to the file generation 1138275970Scyset named 1139275970Scy@code{sysstats}: 1140275970Scy@verbatim 1141275970Scy50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1142275970Scy@end verbatim 1143275970Scy 1144275970ScyThe first two fields show the date (Modified Julian Day) and time 1145275970Scy(seconds and fraction past UTC midnight). 1146275970ScyThe remaining ten fields show 1147275970Scythe statistics counter values accumulated since the last generated 1148275970Scyline. 1149275970Scy@table @asis 1150275970Scy@item Time since restart @code{36000} 1151275970ScyTime in hours since the system was last rebooted. 1152275970Scy@item Packets received @code{81965} 1153275970ScyTotal number of packets received. 1154275970Scy@item Packets processed @code{0} 1155275970ScyNumber of packets received in response to previous packets sent 1156275970Scy@item Current version @code{9546} 1157275970ScyNumber of packets matching the current NTP version. 1158275970Scy@item Previous version @code{56} 1159275970ScyNumber of packets matching the previous NTP version. 1160275970Scy@item Bad version @code{71793} 1161275970ScyNumber of packets matching neither NTP version. 1162275970Scy@item Access denied @code{512} 1163275970ScyNumber of packets denied access for any reason. 1164275970Scy@item Bad length or format @code{540} 1165275970ScyNumber of packets with invalid length, format or port number. 1166275970Scy@item Bad authentication @code{10} 1167275970ScyNumber of packets not verified as authentic. 1168275970Scy@item Rate exceeded @code{147} 1169275970ScyNumber of packets discarded due to rate limitation. 1170275970Scy@end table 1171275970Scy@item @code{statsdir} @kbd{directory_path} 1172275970ScyIndicates the full path of a directory where statistics files 1173275970Scyshould be created (see below). 1174275970ScyThis keyword allows 1175275970Scythe (otherwise constant) 1176275970Scy@code{filegen} 1177275970Scyfilename prefix to be modified for file generation sets, which 1178275970Scyis useful for handling statistics logs. 1179275970Scy@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}]} 1180275970ScyConfigures setting of generation file set name. 1181275970ScyGeneration 1182275970Scyfile sets provide a means for handling files that are 1183275970Scycontinuously growing during the lifetime of a server. 1184275970ScyServer statistics are a typical example for such files. 1185275970ScyGeneration file sets provide access to a set of files used 1186275970Scyto store the actual data. 1187275970ScyAt any time at most one element 1188275970Scyof the set is being written to. 1189275970ScyThe type given specifies 1190275970Scywhen and how data will be directed to a new element of the set. 1191275970ScyThis way, information stored in elements of a file set 1192275970Scythat are currently unused are available for administrational 1193275970Scyoperations without the risk of disturbing the operation of ntpd. 1194275970Scy(Most important: they can be removed to free space for new data 1195275970Scyproduced.) 1196275970Scy 1197275970ScyNote that this command can be sent from the 1198275970Scy@code{ntpdc(1ntpdcmdoc)} 1199275970Scyprogram running at a remote location. 1200275970Scy@table @asis 1201275970Scy@item @code{name} 1202275970ScyThis is the type of the statistics records, as shown in the 1203275970Scy@code{statistics} 1204275970Scycommand. 1205275970Scy@item @code{file} @kbd{filename} 1206275970ScyThis is the file name for the statistics records. 1207275970ScyFilenames of set 1208275970Scymembers are built from three concatenated elements 1209275970Scy@code{prefix}, 1210275970Scy@code{filename} 1211275970Scyand 1212275970Scy@code{suffix}: 1213275970Scy@table @asis 1214275970Scy@item @code{prefix} 1215275970ScyThis is a constant filename path. 1216275970ScyIt is not subject to 1217275970Scymodifications via the 1218275970Scy@kbd{filegen} 1219275970Scyoption. 1220275970ScyIt is defined by the 1221275970Scyserver, usually specified as a compile-time constant. 1222275970ScyIt may, 1223275970Scyhowever, be configurable for individual file generation sets 1224275970Scyvia other commands. 1225275970ScyFor example, the prefix used with 1226275970Scy@kbd{loopstats} 1227275970Scyand 1228275970Scy@kbd{peerstats} 1229275970Scygeneration can be configured using the 1230275970Scy@kbd{statsdir} 1231275970Scyoption explained above. 1232275970Scy@item @code{filename} 1233275970ScyThis string is directly concatenated to the prefix mentioned 1234275970Scyabove (no intervening 1235275970Scy@quoteleft{}/@quoteright{}). 1236275970ScyThis can be modified using 1237275970Scythe file argument to the 1238275970Scy@kbd{filegen} 1239275970Scystatement. 1240275970ScyNo 1241275970Scy@file{..} 1242275970Scyelements are 1243275970Scyallowed in this component to prevent filenames referring to 1244275970Scyparts outside the filesystem hierarchy denoted by 1245275970Scy@kbd{prefix}. 1246275970Scy@item @code{suffix} 1247275970ScyThis part is reflects individual elements of a file set. 1248275970ScyIt is 1249275970Scygenerated according to the type of a file set. 1250275970Scy@end table 1251275970Scy@item @code{type} @kbd{typename} 1252275970ScyA file generation set is characterized by its type. 1253275970ScyThe following 1254275970Scytypes are supported: 1255275970Scy@table @asis 1256275970Scy@item @code{none} 1257275970ScyThe file set is actually a single plain file. 1258275970Scy@item @code{pid} 1259275970ScyOne element of file set is used per incarnation of a ntpd 1260275970Scyserver. 1261275970ScyThis type does not perform any changes to file set 1262275970Scymembers during runtime, however it provides an easy way of 1263275970Scyseparating files belonging to different 1264275970Scy@code{ntpd(1ntpdmdoc)} 1265275970Scyserver incarnations. 1266275970ScyThe set member filename is built by appending a 1267275970Scy@quoteleft{}.@quoteright{} 1268275970Scyto concatenated 1269275970Scy@kbd{prefix} 1270275970Scyand 1271275970Scy@kbd{filename} 1272275970Scystrings, and 1273275970Scyappending the decimal representation of the process ID of the 1274275970Scy@code{ntpd(1ntpdmdoc)} 1275275970Scyserver process. 1276275970Scy@item @code{day} 1277275970ScyOne file generation set element is created per day. 1278275970ScyA day is 1279275970Scydefined as the period between 00:00 and 24:00 UTC. 1280275970ScyThe file set 1281275970Scymember suffix consists of a 1282275970Scy@quoteleft{}.@quoteright{} 1283275970Scyand a day specification in 1284275970Scythe form 1285275970Scy@code{YYYYMMdd}. 1286275970Scy@code{YYYY} 1287275970Scyis a 4-digit year number (e.g., 1992). 1288275970Scy@code{MM} 1289275970Scyis a two digit month number. 1290275970Scy@code{dd} 1291275970Scyis a two digit day number. 1292275970ScyThus, all information written at 10 December 1992 would end up 1293275970Scyin a file named 1294275970Scy@kbd{prefix} 1295275970Scy@kbd{filename}.19921210. 1296275970Scy@item @code{week} 1297275970ScyAny file set member contains data related to a certain week of 1298275970Scya year. 1299275970ScyThe term week is defined by computing day-of-year 1300275970Scymodulo 7. 1301275970ScyElements of such a file generation set are 1302275970Scydistinguished by appending the following suffix to the file set 1303275970Scyfilename base: A dot, a 4-digit year number, the letter 1304275970Scy@code{W}, 1305275970Scyand a 2-digit week number. 1306275970ScyFor example, information from January, 1307275970Scy10th 1992 would end up in a file with suffix 1308275970Scy.No . Ns Ar 1992W1 . 1309275970Scy@item @code{month} 1310275970ScyOne generation file set element is generated per month. 1311275970ScyThe 1312275970Scyfile name suffix consists of a dot, a 4-digit year number, and 1313275970Scya 2-digit month. 1314275970Scy@item @code{year} 1315275970ScyOne generation file element is generated per year. 1316275970ScyThe filename 1317275970Scysuffix consists of a dot and a 4 digit year number. 1318275970Scy@item @code{age} 1319275970ScyThis type of file generation sets changes to a new element of 1320275970Scythe file set every 24 hours of server operation. 1321275970ScyThe filename 1322275970Scysuffix consists of a dot, the letter 1323275970Scy@code{a}, 1324275970Scyand an 8-digit number. 1325275970ScyThis number is taken to be the number of seconds the server is 1326275970Scyrunning at the start of the corresponding 24-hour period. 1327275970ScyInformation is only written to a file generation by specifying 1328275970Scy@code{enable}; 1329275970Scyoutput is prevented by specifying 1330275970Scy@code{disable}. 1331275970Scy@end table 1332275970Scy@item @code{link} | @code{nolink} 1333275970ScyIt is convenient to be able to access the current element of a file 1334275970Scygeneration set by a fixed name. 1335275970ScyThis feature is enabled by 1336275970Scyspecifying 1337275970Scy@code{link} 1338275970Scyand disabled using 1339275970Scy@code{nolink}. 1340275970ScyIf link is specified, a 1341275970Scyhard link from the current file set element to a file without 1342275970Scysuffix is created. 1343275970ScyWhen there is already a file with this name and 1344275970Scythe number of links of this file is one, it is renamed appending a 1345275970Scydot, the letter 1346275970Scy@code{C}, 1347298770Sdelphijand the pid of the 1348298770Sdelphij@code{ntpd(1ntpdmdoc)} 1349298770Sdelphijserver process. 1350275970ScyWhen the 1351275970Scynumber of links is greater than one, the file is unlinked. 1352275970ScyThis 1353275970Scyallows the current file to be accessed by a constant name. 1354275970Scy@item @code{enable} @code{|} @code{disable} 1355275970ScyEnables or disables the recording function. 1356275970Scy@end table 1357275970Scy@end table 1358275970Scy@end table 1359275970Scy@node Access Control Support 1360275970Scy@subsection Access Control Support 1361275970ScyThe 1362275970Scy@code{ntpd(1ntpdmdoc)} 1363275970Scydaemon implements a general purpose address/mask based restriction 1364275970Scylist. 1365275970ScyThe list contains address/match entries sorted first 1366275970Scyby increasing address values and and then by increasing mask values. 1367275970ScyA match occurs when the bitwise AND of the mask and the packet 1368275970Scysource address is equal to the bitwise AND of the mask and 1369275970Scyaddress in the list. 1370275970ScyThe list is searched in order with the 1371275970Scylast match found defining the restriction flags associated 1372275970Scywith the entry. 1373275970ScyAdditional information and examples can be found in the 1374275970Scy"Notes on Configuring NTP and Setting up a NTP Subnet" 1375275970Scypage 1376275970Scy(available as part of the HTML documentation 1377275970Scyprovided in 1378275970Scy@file{/usr/share/doc/ntp}). 1379275970Scy 1380275970ScyThe restriction facility was implemented in conformance 1381275970Scywith the access policies for the original NSFnet backbone 1382275970Scytime servers. 1383275970ScyLater the facility was expanded to deflect 1384275970Scycryptographic and clogging attacks. 1385275970ScyWhile this facility may 1386275970Scybe useful for keeping unwanted or broken or malicious clients 1387275970Scyfrom congesting innocent servers, it should not be considered 1388275970Scyan alternative to the NTP authentication facilities. 1389275970ScySource address based restrictions are easily circumvented 1390275970Scyby a determined cracker. 1391275970Scy 1392275970ScyClients can be denied service because they are explicitly 1393298770Sdelphijincluded in the restrict list created by the 1394298770Sdelphij@code{restrict} 1395298770Sdelphijcommand 1396275970Scyor implicitly as the result of cryptographic or rate limit 1397275970Scyviolations. 1398275970ScyCryptographic violations include certificate 1399275970Scyor identity verification failure; rate limit violations generally 1400275970Scyresult from defective NTP implementations that send packets 1401275970Scyat abusive rates. 1402275970ScySome violations cause denied service 1403275970Scyonly for the offending packet, others cause denied service 1404275970Scyfor a timed period and others cause the denied service for 1405298770Sdelphijan indefinite period. 1406275970ScyWhen a client or network is denied access 1407298770Sdelphijfor an indefinite period, the only way at present to remove 1408275970Scythe restrictions is by restarting the server. 1409275970Scy@subsubsection The Kiss-of-Death Packet 1410275970ScyOrdinarily, packets denied service are simply dropped with no 1411275970Scyfurther action except incrementing statistics counters. 1412275970ScySometimes a 1413275970Scymore proactive response is needed, such as a server message that 1414275970Scyexplicitly requests the client to stop sending and leave a message 1415275970Scyfor the system operator. 1416275970ScyA special packet format has been created 1417275970Scyfor this purpose called the "kiss-of-death" (KoD) packet. 1418275970ScyKoD packets have the leap bits set unsynchronized and stratum set 1419275970Scyto zero and the reference identifier field set to a four-byte 1420275970ScyASCII code. 1421275970ScyIf the 1422275970Scy@code{noserve} 1423275970Scyor 1424275970Scy@code{notrust} 1425275970Scyflag of the matching restrict list entry is set, 1426275970Scythe code is "DENY"; if the 1427275970Scy@code{limited} 1428275970Scyflag is set and the rate limit 1429275970Scyis exceeded, the code is "RATE". 1430275970ScyFinally, if a cryptographic violation occurs, the code is "CRYP". 1431275970Scy 1432275970ScyA client receiving a KoD performs a set of sanity checks to 1433275970Scyminimize security exposure, then updates the stratum and 1434275970Scyreference identifier peer variables, sets the access 1435275970Scydenied (TEST4) bit in the peer flash variable and sends 1436275970Scya message to the log. 1437275970ScyAs long as the TEST4 bit is set, 1438275970Scythe client will send no further packets to the server. 1439275970ScyThe only way at present to recover from this condition is 1440275970Scyto restart the protocol at both the client and server. 1441275970ScyThis 1442275970Scyhappens automatically at the client when the association times out. 1443275970ScyIt will happen at the server only if the server operator cooperates. 1444275970Scy@subsubsection Access Control Commands 1445275970Scy@table @asis 1446275970Scy@item @code{discard} @code{[@code{average} @kbd{avg}]} @code{[@code{minimum} @kbd{min}]} @code{[@code{monitor} @kbd{prob}]} 1447275970ScySet the parameters of the 1448275970Scy@code{limited} 1449275970Scyfacility which protects the server from 1450275970Scyclient abuse. 1451275970ScyThe 1452275970Scy@code{average} 1453275970Scysubcommand specifies the minimum average packet 1454275970Scyspacing, while the 1455275970Scy@code{minimum} 1456275970Scysubcommand specifies the minimum packet spacing. 1457275970ScyPackets that violate these minima are discarded 1458275970Scyand a kiss-o'-death packet returned if enabled. 1459275970ScyThe default 1460275970Scyminimum average and minimum are 5 and 2, respectively. 1461298770SdelphijThe 1462298770Sdelphij@code{monitor} 1463298770Sdelphijsubcommand specifies the probability of discard 1464275970Scyfor packets that overflow the rate-control window. 1465275970Scy@item @code{restrict} @code{address} @code{[@code{mask} @kbd{mask}]} @code{[@kbd{flag} @kbd{...}]} 1466275970ScyThe 1467275970Scy@kbd{address} 1468275970Scyargument expressed in 1469275970Scydotted-quad form is the address of a host or network. 1470275970ScyAlternatively, the 1471275970Scy@kbd{address} 1472275970Scyargument can be a valid host DNS name. 1473275970ScyThe 1474275970Scy@kbd{mask} 1475275970Scyargument expressed in dotted-quad form defaults to 1476275970Scy@code{255.255.255.255}, 1477275970Scymeaning that the 1478275970Scy@kbd{address} 1479275970Scyis treated as the address of an individual host. 1480275970ScyA default entry (address 1481275970Scy@code{0.0.0.0}, 1482275970Scymask 1483275970Scy@code{0.0.0.0}) 1484275970Scyis always included and is always the first entry in the list. 1485275970ScyNote that text string 1486275970Scy@code{default}, 1487275970Scywith no mask option, may 1488275970Scybe used to indicate the default entry. 1489275970ScyIn the current implementation, 1490275970Scy@code{flag} 1491275970Scyalways 1492275970Scyrestricts access, i.e., an entry with no flags indicates that free 1493275970Scyaccess to the server is to be given. 1494275970ScyThe flags are not orthogonal, 1495275970Scyin that more restrictive flags will often make less restrictive 1496275970Scyones redundant. 1497275970ScyThe flags can generally be classed into two 1498275970Scycategories, those which restrict time service and those which 1499275970Scyrestrict informational queries and attempts to do run-time 1500275970Scyreconfiguration of the server. 1501275970ScyOne or more of the following flags 1502275970Scymay be specified: 1503275970Scy@table @asis 1504275970Scy@item @code{ignore} 1505275970ScyDeny packets of all kinds, including 1506275970Scy@code{ntpq(1ntpqmdoc)} 1507275970Scyand 1508275970Scy@code{ntpdc(1ntpdcmdoc)} 1509275970Scyqueries. 1510275970Scy@item @code{kod} 1511275970ScyIf this flag is set when an access violation occurs, a kiss-o'-death 1512275970Scy(KoD) packet is sent. 1513275970ScyKoD packets are rate limited to no more than one 1514275970Scyper second. 1515275970ScyIf another KoD packet occurs within one second after the 1516275970Scylast one, the packet is dropped. 1517275970Scy@item @code{limited} 1518275970ScyDeny service if the packet spacing violates the lower limits specified 1519298770Sdelphijin the 1520298770Sdelphij@code{discard} 1521298770Sdelphijcommand. 1522275970ScyA history of clients is kept using the 1523275970Scymonitoring capability of 1524275970Scy@code{ntpd(1ntpdmdoc)}. 1525275970ScyThus, monitoring is always active as 1526275970Scylong as there is a restriction entry with the 1527275970Scy@code{limited} 1528275970Scyflag. 1529275970Scy@item @code{lowpriotrap} 1530275970ScyDeclare traps set by matching hosts to be low priority. 1531275970ScyThe 1532275970Scynumber of traps a server can maintain is limited (the current limit 1533275970Scyis 3). 1534275970ScyTraps are usually assigned on a first come, first served 1535275970Scybasis, with later trap requestors being denied service. 1536275970ScyThis flag 1537275970Scymodifies the assignment algorithm by allowing low priority traps to 1538275970Scybe overridden by later requests for normal priority traps. 1539275970Scy@item @code{nomodify} 1540275970ScyDeny 1541275970Scy@code{ntpq(1ntpqmdoc)} 1542275970Scyand 1543275970Scy@code{ntpdc(1ntpdcmdoc)} 1544275970Scyqueries which attempt to modify the state of the 1545275970Scyserver (i.e., run time reconfiguration). 1546275970ScyQueries which return 1547275970Scyinformation are permitted. 1548275970Scy@item @code{noquery} 1549275970ScyDeny 1550275970Scy@code{ntpq(1ntpqmdoc)} 1551275970Scyand 1552275970Scy@code{ntpdc(1ntpdcmdoc)} 1553275970Scyqueries. 1554275970ScyTime service is not affected. 1555275970Scy@item @code{nopeer} 1556275970ScyDeny packets which would result in mobilizing a new association. 1557275970ScyThis 1558275970Scyincludes broadcast and symmetric active packets when a configured 1559275970Scyassociation does not exist. 1560275970ScyIt also includes 1561275970Scy@code{pool} 1562275970Scyassociations, so if you want to use servers from a 1563275970Scy@code{pool} 1564275970Scydirective and also want to use 1565275970Scy@code{nopeer} 1566275970Scyby default, you'll want a 1567275970Scy@code{restrict source ...} @code{line} @code{as} @code{well} @code{that} @code{does} 1568275970Scy@item not 1569275970Scyinclude the 1570275970Scy@code{nopeer} 1571275970Scydirective. 1572275970Scy@item @code{noserve} 1573275970ScyDeny all packets except 1574275970Scy@code{ntpq(1ntpqmdoc)} 1575275970Scyand 1576275970Scy@code{ntpdc(1ntpdcmdoc)} 1577275970Scyqueries. 1578275970Scy@item @code{notrap} 1579275970ScyDecline to provide mode 6 control message trap service to matching 1580275970Scyhosts. 1581298770SdelphijThe trap service is a subsystem of the 1582298770Sdelphij@code{ntpq(1ntpqmdoc)} 1583298770Sdelphijcontrol message 1584275970Scyprotocol which is intended for use by remote event logging programs. 1585275970Scy@item @code{notrust} 1586275970ScyDeny service unless the packet is cryptographically authenticated. 1587275970Scy@item @code{ntpport} 1588275970ScyThis is actually a match algorithm modifier, rather than a 1589275970Scyrestriction flag. 1590275970ScyIts presence causes the restriction entry to be 1591275970Scymatched only if the source port in the packet is the standard NTP 1592275970ScyUDP port (123). 1593275970ScyBoth 1594275970Scy@code{ntpport} 1595275970Scyand 1596275970Scy@code{non-ntpport} 1597275970Scymay 1598275970Scybe specified. 1599275970ScyThe 1600275970Scy@code{ntpport} 1601275970Scyis considered more specific and 1602275970Scyis sorted later in the list. 1603275970Scy@item @code{version} 1604275970ScyDeny packets that do not match the current NTP version. 1605275970Scy@end table 1606275970Scy 1607275970ScyDefault restriction list entries with the flags ignore, interface, 1608275970Scyntpport, for each of the local host's interface addresses are 1609275970Scyinserted into the table at startup to prevent the server 1610275970Scyfrom attempting to synchronize to its own time. 1611275970ScyA default entry is also always present, though if it is 1612275970Scyotherwise unconfigured; no flags are associated 1613275970Scywith the default entry (i.e., everything besides your own 1614275970ScyNTP server is unrestricted). 1615275970Scy@end table 1616275970Scy@node Automatic NTP Configuration Options 1617275970Scy@subsection Automatic NTP Configuration Options 1618275970Scy@subsubsection Manycasting 1619275970ScyManycasting is a automatic discovery and configuration paradigm 1620275970Scynew to NTPv4. 1621275970ScyIt is intended as a means for a multicast client 1622275970Scyto troll the nearby network neighborhood to find cooperating 1623275970Scymanycast servers, validate them using cryptographic means 1624275970Scyand evaluate their time values with respect to other servers 1625275970Scythat might be lurking in the vicinity. 1626275970ScyThe intended result is that each manycast client mobilizes 1627275970Scyclient associations with some number of the "best" 1628275970Scyof the nearby manycast servers, yet automatically reconfigures 1629275970Scyto sustain this number of servers should one or another fail. 1630275970Scy 1631275970ScyNote that the manycasting paradigm does not coincide 1632275970Scywith the anycast paradigm described in RFC-1546, 1633275970Scywhich is designed to find a single server from a clique 1634275970Scyof servers providing the same service. 1635275970ScyThe manycast paradigm is designed to find a plurality 1636275970Scyof redundant servers satisfying defined optimality criteria. 1637275970Scy 1638275970ScyManycasting can be used with either symmetric key 1639275970Scyor public key cryptography. 1640275970ScyThe public key infrastructure (PKI) 1641275970Scyoffers the best protection against compromised keys 1642275970Scyand is generally considered stronger, at least with relatively 1643275970Scylarge key sizes. 1644275970ScyIt is implemented using the Autokey protocol and 1645275970Scythe OpenSSL cryptographic library available from 1646275970Scy@code{http://www.openssl.org/}. 1647275970ScyThe library can also be used with other NTPv4 modes 1648275970Scyas well and is highly recommended, especially for broadcast modes. 1649275970Scy 1650275970ScyA persistent manycast client association is configured 1651298770Sdelphijusing the 1652298770Sdelphij@code{manycastclient} 1653298770Sdelphijcommand, which is similar to the 1654298770Sdelphij@code{server} 1655298770Sdelphijcommand but with a multicast (IPv4 class 1656275970Scy@code{D} 1657275970Scyor IPv6 prefix 1658275970Scy@code{FF}) 1659275970Scygroup address. 1660275970ScyThe IANA has designated IPv4 address 224.1.1.1 1661275970Scyand IPv6 address FF05::101 (site local) for NTP. 1662275970ScyWhen more servers are needed, it broadcasts manycast 1663275970Scyclient messages to this address at the minimum feasible rate 1664275970Scyand minimum feasible time-to-live (TTL) hops, depending 1665275970Scyon how many servers have already been found. 1666275970ScyThere can be as many manycast client associations 1667275970Scyas different group address, each one serving as a template 1668275970Scyfor a future ephemeral unicast client/server association. 1669275970Scy 1670275970ScyManycast servers configured with the 1671275970Scy@code{manycastserver} 1672275970Scycommand listen on the specified group address for manycast 1673275970Scyclient messages. 1674275970ScyNote the distinction between manycast client, 1675275970Scywhich actively broadcasts messages, and manycast server, 1676275970Scywhich passively responds to them. 1677275970ScyIf a manycast server is 1678275970Scyin scope of the current TTL and is itself synchronized 1679275970Scyto a valid source and operating at a stratum level equal 1680275970Scyto or lower than the manycast client, it replies to the 1681275970Scymanycast client message with an ordinary unicast server message. 1682275970Scy 1683275970ScyThe manycast client receiving this message mobilizes 1684275970Scyan ephemeral client/server association according to the 1685275970Scymatching manycast client template, but only if cryptographically 1686275970Scyauthenticated and the server stratum is less than or equal 1687275970Scyto the client stratum. 1688275970ScyAuthentication is explicitly required 1689275970Scyand either symmetric key or public key (Autokey) can be used. 1690275970ScyThen, the client polls the server at its unicast address 1691275970Scyin burst mode in order to reliably set the host clock 1692275970Scyand validate the source. 1693275970ScyThis normally results 1694275970Scyin a volley of eight client/server at 2-s intervals 1695275970Scyduring which both the synchronization and cryptographic 1696275970Scyprotocols run concurrently. 1697275970ScyFollowing the volley, 1698275970Scythe client runs the NTP intersection and clustering 1699275970Scyalgorithms, which act to discard all but the "best" 1700275970Scyassociations according to stratum and synchronization 1701275970Scydistance. 1702275970ScyThe surviving associations then continue 1703275970Scyin ordinary client/server mode. 1704275970Scy 1705275970ScyThe manycast client polling strategy is designed to reduce 1706275970Scyas much as possible the volume of manycast client messages 1707275970Scyand the effects of implosion due to near-simultaneous 1708275970Scyarrival of manycast server messages. 1709275970ScyThe strategy is determined by the 1710275970Scy@code{manycastclient}, 1711275970Scy@code{tos} 1712275970Scyand 1713275970Scy@code{ttl} 1714275970Scyconfiguration commands. 1715275970ScyThe manycast poll interval is 1716275970Scynormally eight times the system poll interval, 1717275970Scywhich starts out at the 1718275970Scy@code{minpoll} 1719275970Scyvalue specified in the 1720275970Scy@code{manycastclient}, 1721275970Scycommand and, under normal circumstances, increments to the 1722275970Scy@code{maxpolll} 1723275970Scyvalue specified in this command. 1724275970ScyInitially, the TTL is 1725298770Sdelphijset at the minimum hops specified by the 1726298770Sdelphij@code{ttl} 1727298770Sdelphijcommand. 1728275970ScyAt each retransmission the TTL is increased until reaching 1729275970Scythe maximum hops specified by this command or a sufficient 1730275970Scynumber client associations have been found. 1731275970ScyFurther retransmissions use the same TTL. 1732275970Scy 1733275970ScyThe quality and reliability of the suite of associations 1734275970Scydiscovered by the manycast client is determined by the NTP 1735275970Scymitigation algorithms and the 1736275970Scy@code{minclock} 1737275970Scyand 1738275970Scy@code{minsane} 1739275970Scyvalues specified in the 1740275970Scy@code{tos} 1741275970Scyconfiguration command. 1742275970ScyAt least 1743275970Scy@code{minsane} 1744275970Scycandidate servers must be available and the mitigation 1745275970Scyalgorithms produce at least 1746275970Scy@code{minclock} 1747275970Scysurvivors in order to synchronize the clock. 1748275970ScyByzantine agreement principles require at least four 1749275970Scycandidates in order to correctly discard a single falseticker. 1750275970ScyFor legacy purposes, 1751275970Scy@code{minsane} 1752275970Scydefaults to 1 and 1753275970Scy@code{minclock} 1754275970Scydefaults to 3. 1755275970ScyFor manycast service 1756275970Scy@code{minsane} 1757275970Scyshould be explicitly set to 4, assuming at least that 1758275970Scynumber of servers are available. 1759275970Scy 1760275970ScyIf at least 1761275970Scy@code{minclock} 1762275970Scyservers are found, the manycast poll interval is immediately 1763275970Scyset to eight times 1764275970Scy@code{maxpoll}. 1765275970ScyIf less than 1766275970Scy@code{minclock} 1767275970Scyservers are found when the TTL has reached the maximum hops, 1768275970Scythe manycast poll interval is doubled. 1769275970ScyFor each transmission 1770275970Scyafter that, the poll interval is doubled again until 1771275970Scyreaching the maximum of eight times 1772275970Scy@code{maxpoll}. 1773275970ScyFurther transmissions use the same poll interval and 1774275970ScyTTL values. 1775275970ScyNote that while all this is going on, 1776275970Scyeach client/server association found is operating normally 1777275970Scyit the system poll interval. 1778275970Scy 1779275970ScyAdministratively scoped multicast boundaries are normally 1780275970Scyspecified by the network router configuration and, 1781275970Scyin the case of IPv6, the link/site scope prefix. 1782275970ScyBy default, the increment for TTL hops is 32 starting 1783275970Scyfrom 31; however, the 1784275970Scy@code{ttl} 1785275970Scyconfiguration command can be 1786275970Scyused to modify the values to match the scope rules. 1787275970Scy 1788275970ScyIt is often useful to narrow the range of acceptable 1789275970Scyservers which can be found by manycast client associations. 1790275970ScyBecause manycast servers respond only when the client 1791275970Scystratum is equal to or greater than the server stratum, 1792275970Scyprimary (stratum 1) servers fill find only primary servers 1793275970Scyin TTL range, which is probably the most common objective. 1794275970ScyHowever, unless configured otherwise, all manycast clients 1795275970Scyin TTL range will eventually find all primary servers 1796275970Scyin TTL range, which is probably not the most common 1797275970Scyobjective in large networks. 1798275970ScyThe 1799275970Scy@code{tos} 1800275970Scycommand can be used to modify this behavior. 1801275970ScyServers with stratum below 1802275970Scy@code{floor} 1803275970Scyor above 1804275970Scy@code{ceiling} 1805275970Scyspecified in the 1806275970Scy@code{tos} 1807275970Scycommand are strongly discouraged during the selection 1808275970Scyprocess; however, these servers may be temporally 1809275970Scyaccepted if the number of servers within TTL range is 1810275970Scyless than 1811275970Scy@code{minclock}. 1812275970Scy 1813275970ScyThe above actions occur for each manycast client message, 1814275970Scywhich repeats at the designated poll interval. 1815275970ScyHowever, once the ephemeral client association is mobilized, 1816275970Scysubsequent manycast server replies are discarded, 1817275970Scysince that would result in a duplicate association. 1818275970ScyIf during a poll interval the number of client associations 1819275970Scyfalls below 1820275970Scy@code{minclock}, 1821275970Scyall manycast client prototype associations are reset 1822275970Scyto the initial poll interval and TTL hops and operation 1823275970Scyresumes from the beginning. 1824275970ScyIt is important to avoid 1825275970Scyfrequent manycast client messages, since each one requires 1826275970Scyall manycast servers in TTL range to respond. 1827275970ScyThe result could well be an implosion, either minor or major, 1828275970Scydepending on the number of servers in range. 1829275970ScyThe recommended value for 1830275970Scy@code{maxpoll} 1831275970Scyis 12 (4,096 s). 1832275970Scy 1833275970ScyIt is possible and frequently useful to configure a host 1834275970Scyas both manycast client and manycast server. 1835275970ScyA number of hosts configured this way and sharing a common 1836275970Scygroup address will automatically organize themselves 1837275970Scyin an optimum configuration based on stratum and 1838275970Scysynchronization distance. 1839275970ScyFor example, consider an NTP 1840275970Scysubnet of two primary servers and a hundred or more 1841275970Scydependent clients. 1842275970ScyWith two exceptions, all servers 1843275970Scyand clients have identical configuration files including both 1844275970Scy@code{multicastclient} 1845275970Scyand 1846275970Scy@code{multicastserver} 1847275970Scycommands using, for instance, multicast group address 1848275970Scy239.1.1.1. 1849275970ScyThe only exception is that each primary server 1850275970Scyconfiguration file must include commands for the primary 1851275970Scyreference source such as a GPS receiver. 1852275970Scy 1853275970ScyThe remaining configuration files for all secondary 1854275970Scyservers and clients have the same contents, except for the 1855275970Scy@code{tos} 1856275970Scycommand, which is specific for each stratum level. 1857275970ScyFor stratum 1 and stratum 2 servers, that command is 1858275970Scynot necessary. 1859275970ScyFor stratum 3 and above servers the 1860275970Scy@code{floor} 1861275970Scyvalue is set to the intended stratum number. 1862275970ScyThus, all stratum 3 configuration files are identical, 1863275970Scyall stratum 4 files are identical and so forth. 1864275970Scy 1865275970ScyOnce operations have stabilized in this scenario, 1866275970Scythe primary servers will find the primary reference source 1867275970Scyand each other, since they both operate at the same 1868275970Scystratum (1), but not with any secondary server or client, 1869275970Scysince these operate at a higher stratum. 1870275970ScyThe secondary 1871275970Scyservers will find the servers at the same stratum level. 1872275970ScyIf one of the primary servers loses its GPS receiver, 1873275970Scyit will continue to operate as a client and other clients 1874275970Scywill time out the corresponding association and 1875275970Scyre-associate accordingly. 1876275970Scy 1877275970ScySome administrators prefer to avoid running 1878275970Scy@code{ntpd(1ntpdmdoc)} 1879275970Scycontinuously and run either 1880289999Sglebius@code{sntp(1sntpmdoc)} 1881275970Scyor 1882275970Scy@code{ntpd(1ntpdmdoc)} 1883275970Scy@code{-q} 1884275970Scyas a cron job. 1885275970ScyIn either case the servers must be 1886275970Scyconfigured in advance and the program fails if none are 1887275970Scyavailable when the cron job runs. 1888275970ScyA really slick 1889275970Scyapplication of manycast is with 1890275970Scy@code{ntpd(1ntpdmdoc)} 1891275970Scy@code{-q}. 1892275970ScyThe program wakes up, scans the local landscape looking 1893275970Scyfor the usual suspects, selects the best from among 1894275970Scythe rascals, sets the clock and then departs. 1895275970ScyServers do not have to be configured in advance and 1896275970Scyall clients throughout the network can have the same 1897275970Scyconfiguration file. 1898275970Scy@subsubsection Manycast Interactions with Autokey 1899275970ScyEach time a manycast client sends a client mode packet 1900275970Scyto a multicast group address, all manycast servers 1901275970Scyin scope generate a reply including the host name 1902275970Scyand status word. 1903275970ScyThe manycast clients then run 1904275970Scythe Autokey protocol, which collects and verifies 1905275970Scyall certificates involved. 1906275970ScyFollowing the burst interval 1907275970Scyall but three survivors are cast off, 1908275970Scybut the certificates remain in the local cache. 1909275970ScyIt often happens that several complete signing trails 1910275970Scyfrom the client to the primary servers are collected in this way. 1911275970Scy 1912275970ScyAbout once an hour or less often if the poll interval 1913275970Scyexceeds this, the client regenerates the Autokey key list. 1914275970ScyThis is in general transparent in client/server mode. 1915275970ScyHowever, about once per day the server private value 1916275970Scyused to generate cookies is refreshed along with all 1917275970Scymanycast client associations. 1918275970ScyIn this case all 1919275970Scycryptographic values including certificates is refreshed. 1920275970ScyIf a new certificate has been generated since 1921275970Scythe last refresh epoch, it will automatically revoke 1922275970Scyall prior certificates that happen to be in the 1923275970Scycertificate cache. 1924275970ScyAt the same time, the manycast 1925275970Scyscheme starts all over from the beginning and 1926275970Scythe expanding ring shrinks to the minimum and increments 1927275970Scyfrom there while collecting all servers in scope. 1928310419Sdelphij@subsubsection Broadcast Options 1929310419Sdelphij@table @asis 1930310419Sdelphij@item @code{tos} @code{[@code{bcpollbstep} @kbd{gate}]} 1931310419SdelphijThis command provides a way to delay, 1932310419Sdelphijby the specified number of broadcast poll intervals, 1933310419Sdelphijbelieving backward time steps from a broadcast server. 1934310419SdelphijBroadcast time networks are expected to be trusted. 1935310419SdelphijIn the event a broadcast server's time is stepped backwards, 1936310419Sdelphijthere is clear benefit to having the clients notice this change 1937310419Sdelphijas soon as possible. 1938310419SdelphijAttacks such as replay attacks can happen, however, 1939310419Sdelphijand even though there are a number of protections built in to 1940310419Sdelphijbroadcast mode, attempts to perform a replay attack are possible. 1941310419SdelphijThis value defaults to 0, but can be changed 1942310419Sdelphijto any number of poll intervals between 0 and 4. 1943275970Scy@subsubsection Manycast Options 1944275970Scy@table @asis 1945275970Scy@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}]} 1946275970ScyThis command affects the clock selection and clustering 1947275970Scyalgorithms. 1948275970ScyIt can be used to select the quality and 1949275970Scyquantity of peers used to synchronize the system clock 1950275970Scyand is most useful in manycast mode. 1951275970ScyThe variables operate 1952275970Scyas follows: 1953275970Scy@table @asis 1954275970Scy@item @code{ceiling} @kbd{ceiling} 1955275970ScyPeers with strata above 1956275970Scy@code{ceiling} 1957275970Scywill be discarded if there are at least 1958275970Scy@code{minclock} 1959275970Scypeers remaining. 1960275970ScyThis value defaults to 15, but can be changed 1961275970Scyto any number from 1 to 15. 1962275970Scy@item @code{cohort} @code{@{0 | 1@}} 1963275970ScyThis is a binary flag which enables (0) or disables (1) 1964275970Scymanycast server replies to manycast clients with the same 1965275970Scystratum level. 1966275970ScyThis is useful to reduce implosions where 1967275970Scylarge numbers of clients with the same stratum level 1968275970Scyare present. 1969275970ScyThe default is to enable these replies. 1970275970Scy@item @code{floor} @kbd{floor} 1971275970ScyPeers with strata below 1972275970Scy@code{floor} 1973275970Scywill be discarded if there are at least 1974275970Scy@code{minclock} 1975275970Scypeers remaining. 1976275970ScyThis value defaults to 1, but can be changed 1977275970Scyto any number from 1 to 15. 1978275970Scy@item @code{minclock} @kbd{minclock} 1979289999SglebiusThe clustering algorithm repeatedly casts out outlier 1980275970Scyassociations until no more than 1981275970Scy@code{minclock} 1982275970Scyassociations remain. 1983275970ScyThis value defaults to 3, 1984275970Scybut can be changed to any number from 1 to the number of 1985275970Scyconfigured sources. 1986275970Scy@item @code{minsane} @kbd{minsane} 1987275970ScyThis is the minimum number of candidates available 1988275970Scyto the clock selection algorithm in order to produce 1989275970Scyone or more truechimers for the clustering algorithm. 1990275970ScyIf fewer than this number are available, the clock is 1991275970Scyundisciplined and allowed to run free. 1992275970ScyThe default is 1 1993275970Scyfor legacy purposes. 1994275970ScyHowever, according to principles of 1995275970ScyByzantine agreement, 1996275970Scy@code{minsane} 1997275970Scyshould be at least 4 in order to detect and discard 1998275970Scya single falseticker. 1999275970Scy@end table 2000275970Scy@item @code{ttl} @kbd{hop} @kbd{...} 2001275970ScyThis command specifies a list of TTL values in increasing 2002275970Scyorder, up to 8 values can be specified. 2003275970ScyIn manycast mode these values are used in turn 2004275970Scyin an expanding-ring search. 2005275970ScyThe default is eight 2006275970Scymultiples of 32 starting at 31. 2007275970Scy@end table 2008275970Scy@node Reference Clock Support 2009275970Scy@subsection Reference Clock Support 2010275970ScyThe NTP Version 4 daemon supports some three dozen different radio, 2011275970Scysatellite and modem reference clocks plus a special pseudo-clock 2012275970Scyused for backup or when no other clock source is available. 2013275970ScyDetailed descriptions of individual device drivers and options can 2014275970Scybe found in the 2015275970Scy"Reference Clock Drivers" 2016275970Scypage 2017275970Scy(available as part of the HTML documentation 2018275970Scyprovided in 2019275970Scy@file{/usr/share/doc/ntp}). 2020275970ScyAdditional information can be found in the pages linked 2021275970Scythere, including the 2022275970Scy"Debugging Hints for Reference Clock Drivers" 2023275970Scyand 2024275970Scy"How To Write a Reference Clock Driver" 2025275970Scypages 2026275970Scy(available as part of the HTML documentation 2027275970Scyprovided in 2028275970Scy@file{/usr/share/doc/ntp}). 2029275970ScyIn addition, support for a PPS 2030275970Scysignal is available as described in the 2031275970Scy"Pulse-per-second (PPS) Signal Interfacing" 2032275970Scypage 2033275970Scy(available as part of the HTML documentation 2034275970Scyprovided in 2035275970Scy@file{/usr/share/doc/ntp}). 2036275970ScyMany 2037275970Scydrivers support special line discipline/streams modules which can 2038275970Scysignificantly improve the accuracy using the driver. 2039275970ScyThese are 2040275970Scydescribed in the 2041275970Scy"Line Disciplines and Streams Drivers" 2042275970Scypage 2043275970Scy(available as part of the HTML documentation 2044275970Scyprovided in 2045275970Scy@file{/usr/share/doc/ntp}). 2046275970Scy 2047275970ScyA reference clock will generally (though not always) be a radio 2048275970Scytimecode receiver which is synchronized to a source of standard 2049275970Scytime such as the services offered by the NRC in Canada and NIST and 2050275970ScyUSNO in the US. 2051275970ScyThe interface between the computer and the timecode 2052275970Scyreceiver is device dependent, but is usually a serial port. 2053275970ScyA 2054275970Scydevice driver specific to each reference clock must be selected and 2055275970Scycompiled in the distribution; however, most common radio, satellite 2056275970Scyand modem clocks are included by default. 2057275970ScyNote that an attempt to 2058275970Scyconfigure a reference clock when the driver has not been compiled 2059275970Scyor the hardware port has not been appropriately configured results 2060275970Scyin a scalding remark to the system log file, but is otherwise non 2061275970Scyhazardous. 2062275970Scy 2063275970ScyFor the purposes of configuration, 2064275970Scy@code{ntpd(1ntpdmdoc)} 2065275970Scytreats 2066275970Scyreference clocks in a manner analogous to normal NTP peers as much 2067275970Scyas possible. 2068275970ScyReference clocks are identified by a syntactically 2069275970Scycorrect but invalid IP address, in order to distinguish them from 2070275970Scynormal NTP peers. 2071275970ScyReference clock addresses are of the form 2072275970Scy@code{127.127.}@kbd{t}.@kbd{u}, 2073275970Scywhere 2074275970Scy@kbd{t} 2075275970Scyis an integer 2076275970Scydenoting the clock type and 2077275970Scy@kbd{u} 2078275970Scyindicates the unit 2079275970Scynumber in the range 0-3. 2080275970ScyWhile it may seem overkill, it is in fact 2081275970Scysometimes useful to configure multiple reference clocks of the same 2082275970Scytype, in which case the unit numbers must be unique. 2083275970Scy 2084275970ScyThe 2085275970Scy@code{server} 2086275970Scycommand is used to configure a reference 2087275970Scyclock, where the 2088275970Scy@kbd{address} 2089275970Scyargument in that command 2090275970Scyis the clock address. 2091275970ScyThe 2092275970Scy@code{key}, 2093275970Scy@code{version} 2094275970Scyand 2095275970Scy@code{ttl} 2096275970Scyoptions are not used for reference clock support. 2097275970ScyThe 2098275970Scy@code{mode} 2099275970Scyoption is added for reference clock support, as 2100275970Scydescribed below. 2101275970ScyThe 2102275970Scy@code{prefer} 2103275970Scyoption can be useful to 2104275970Scypersuade the server to cherish a reference clock with somewhat more 2105275970Scyenthusiasm than other reference clocks or peers. 2106275970ScyFurther 2107275970Scyinformation on this option can be found in the 2108275970Scy"Mitigation Rules and the prefer Keyword" 2109275970Scy(available as part of the HTML documentation 2110275970Scyprovided in 2111275970Scy@file{/usr/share/doc/ntp}) 2112275970Scypage. 2113275970ScyThe 2114275970Scy@code{minpoll} 2115275970Scyand 2116275970Scy@code{maxpoll} 2117275970Scyoptions have 2118275970Scymeaning only for selected clock drivers. 2119275970ScySee the individual clock 2120275970Scydriver document pages for additional information. 2121275970Scy 2122275970ScyThe 2123275970Scy@code{fudge} 2124275970Scycommand is used to provide additional 2125275970Scyinformation for individual clock drivers and normally follows 2126275970Scyimmediately after the 2127275970Scy@code{server} 2128275970Scycommand. 2129275970ScyThe 2130275970Scy@kbd{address} 2131275970Scyargument specifies the clock address. 2132275970ScyThe 2133275970Scy@code{refid} 2134275970Scyand 2135275970Scy@code{stratum} 2136275970Scyoptions can be used to 2137275970Scyoverride the defaults for the device. 2138275970ScyThere are two optional 2139275970Scydevice-dependent time offsets and four flags that can be included 2140275970Scyin the 2141275970Scy@code{fudge} 2142275970Scycommand as well. 2143275970Scy 2144275970ScyThe stratum number of a reference clock is by default zero. 2145275970ScySince the 2146275970Scy@code{ntpd(1ntpdmdoc)} 2147275970Scydaemon adds one to the stratum of each 2148275970Scypeer, a primary server ordinarily displays an external stratum of 2149275970Scyone. 2150275970ScyIn order to provide engineered backups, it is often useful to 2151275970Scyspecify the reference clock stratum as greater than zero. 2152275970ScyThe 2153275970Scy@code{stratum} 2154275970Scyoption is used for this purpose. 2155275970ScyAlso, in cases 2156275970Scyinvolving both a reference clock and a pulse-per-second (PPS) 2157275970Scydiscipline signal, it is useful to specify the reference clock 2158275970Scyidentifier as other than the default, depending on the driver. 2159275970ScyThe 2160275970Scy@code{refid} 2161275970Scyoption is used for this purpose. 2162275970ScyExcept where noted, 2163275970Scythese options apply to all clock drivers. 2164275970Scy@subsubsection Reference Clock Commands 2165275970Scy@table @asis 2166275970Scy@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}]} 2167275970ScyThis command can be used to configure reference clocks in 2168275970Scyspecial ways. 2169275970ScyThe options are interpreted as follows: 2170275970Scy@table @asis 2171275970Scy@item @code{prefer} 2172275970ScyMarks the reference clock as preferred. 2173275970ScyAll other things being 2174275970Scyequal, this host will be chosen for synchronization among a set of 2175275970Scycorrectly operating hosts. 2176275970ScySee the 2177275970Scy"Mitigation Rules and the prefer Keyword" 2178275970Scypage 2179275970Scy(available as part of the HTML documentation 2180275970Scyprovided in 2181275970Scy@file{/usr/share/doc/ntp}) 2182275970Scyfor further information. 2183275970Scy@item @code{mode} @kbd{int} 2184275970ScySpecifies a mode number which is interpreted in a 2185275970Scydevice-specific fashion. 2186275970ScyFor instance, it selects a dialing 2187275970Scyprotocol in the ACTS driver and a device subtype in the 2188275970Scyparse 2189275970Scydrivers. 2190275970Scy@item @code{minpoll} @kbd{int} 2191275970Scy@item @code{maxpoll} @kbd{int} 2192275970ScyThese options specify the minimum and maximum polling interval 2193275970Scyfor reference clock messages, as a power of 2 in seconds 2194275970ScyFor 2195275970Scymost directly connected reference clocks, both 2196275970Scy@code{minpoll} 2197275970Scyand 2198275970Scy@code{maxpoll} 2199275970Scydefault to 6 (64 s). 2200275970ScyFor modem reference clocks, 2201275970Scy@code{minpoll} 2202275970Scydefaults to 10 (17.1 m) and 2203275970Scy@code{maxpoll} 2204275970Scydefaults to 14 (4.5 h). 2205275970ScyThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2206275970Scy@end table 2207275970Scy@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}]} 2208275970ScyThis command can be used to configure reference clocks in 2209275970Scyspecial ways. 2210275970ScyIt must immediately follow the 2211275970Scy@code{server} 2212275970Scycommand which configures the driver. 2213275970ScyNote that the same capability 2214275970Scyis possible at run time using the 2215275970Scy@code{ntpdc(1ntpdcmdoc)} 2216275970Scyprogram. 2217275970ScyThe options are interpreted as 2218275970Scyfollows: 2219275970Scy@table @asis 2220275970Scy@item @code{time1} @kbd{sec} 2221275970ScySpecifies a constant to be added to the time offset produced by 2222275970Scythe driver, a fixed-point decimal number in seconds. 2223275970ScyThis is used 2224275970Scyas a calibration constant to adjust the nominal time offset of a 2225275970Scyparticular clock to agree with an external standard, such as a 2226275970Scyprecision PPS signal. 2227275970ScyIt also provides a way to correct a 2228275970Scysystematic error or bias due to serial port or operating system 2229275970Scylatencies, different cable lengths or receiver internal delay. 2230275970ScyThe 2231275970Scyspecified offset is in addition to the propagation delay provided 2232275970Scyby other means, such as internal DIPswitches. 2233275970ScyWhere a calibration 2234275970Scyfor an individual system and driver is available, an approximate 2235275970Scycorrection is noted in the driver documentation pages. 2236275970ScyNote: in order to facilitate calibration when more than one 2237275970Scyradio clock or PPS signal is supported, a special calibration 2238275970Scyfeature is available. 2239275970ScyIt takes the form of an argument to the 2240275970Scy@code{enable} 2241275970Scycommand described in 2242275970Scy@ref{Miscellaneous Options} 2243275970Scypage and operates as described in the 2244275970Scy"Reference Clock Drivers" 2245275970Scypage 2246275970Scy(available as part of the HTML documentation 2247275970Scyprovided in 2248275970Scy@file{/usr/share/doc/ntp}). 2249275970Scy@item @code{time2} @kbd{secs} 2250275970ScySpecifies a fixed-point decimal number in seconds, which is 2251275970Scyinterpreted in a driver-dependent way. 2252275970ScySee the descriptions of 2253275970Scyspecific drivers in the 2254275970Scy"Reference Clock Drivers" 2255275970Scypage 2256275970Scy(available as part of the HTML documentation 2257275970Scyprovided in 2258275970Scy@file{/usr/share/doc/ntp}). 2259275970Scy@item @code{stratum} @kbd{int} 2260275970ScySpecifies the stratum number assigned to the driver, an integer 2261275970Scybetween 0 and 15. 2262275970ScyThis number overrides the default stratum number 2263275970Scyordinarily assigned by the driver itself, usually zero. 2264275970Scy@item @code{refid} @kbd{string} 2265275970ScySpecifies an ASCII string of from one to four characters which 2266275970Scydefines the reference identifier used by the driver. 2267275970ScyThis string 2268275970Scyoverrides the default identifier ordinarily assigned by the driver 2269275970Scyitself. 2270275970Scy@item @code{mode} @kbd{int} 2271275970ScySpecifies a mode number which is interpreted in a 2272275970Scydevice-specific fashion. 2273275970ScyFor instance, it selects a dialing 2274275970Scyprotocol in the ACTS driver and a device subtype in the 2275275970Scyparse 2276275970Scydrivers. 2277275970Scy@item @code{flag1} @code{0} @code{|} @code{1} 2278275970Scy@item @code{flag2} @code{0} @code{|} @code{1} 2279275970Scy@item @code{flag3} @code{0} @code{|} @code{1} 2280275970Scy@item @code{flag4} @code{0} @code{|} @code{1} 2281275970ScyThese four flags are used for customizing the clock driver. 2282275970ScyThe 2283275970Scyinterpretation of these values, and whether they are used at all, 2284275970Scyis a function of the particular clock driver. 2285275970ScyHowever, by 2286275970Scyconvention 2287275970Scy@code{flag4} 2288275970Scyis used to enable recording monitoring 2289275970Scydata to the 2290275970Scy@code{clockstats} 2291275970Scyfile configured with the 2292275970Scy@code{filegen} 2293275970Scycommand. 2294275970ScyFurther information on the 2295275970Scy@code{filegen} 2296275970Scycommand can be found in 2297275970Scy@ref{Monitoring Options}. 2298275970Scy@end table 2299275970Scy@end table 2300275970Scy@node Miscellaneous Options 2301275970Scy@subsection Miscellaneous Options 2302275970Scy@table @asis 2303275970Scy@item @code{broadcastdelay} @kbd{seconds} 2304275970ScyThe broadcast and multicast modes require a special calibration 2305275970Scyto determine the network delay between the local and remote 2306275970Scyservers. 2307275970ScyOrdinarily, this is done automatically by the initial 2308275970Scyprotocol exchanges between the client and server. 2309275970ScyIn some cases, 2310275970Scythe calibration procedure may fail due to network or server access 2311275970Scycontrols, for example. 2312275970ScyThis command specifies the default delay to 2313275970Scybe used under these circumstances. 2314275970ScyTypically (for Ethernet), a 2315275970Scynumber between 0.003 and 0.007 seconds is appropriate. 2316275970ScyThe default 2317275970Scywhen this command is not used is 0.004 seconds. 2318275970Scy@item @code{calldelay} @kbd{delay} 2319275970ScyThis option controls the delay in seconds between the first and second 2320275970Scypackets sent in burst or iburst mode to allow additional time for a modem 2321275970Scyor ISDN call to complete. 2322275970Scy@item @code{driftfile} @kbd{driftfile} 2323275970ScyThis command specifies the complete path and name of the file used to 2324275970Scyrecord the frequency of the local clock oscillator. 2325275970ScyThis is the same 2326275970Scyoperation as the 2327275970Scy@code{-f} 2328275970Scycommand line option. 2329275970ScyIf the file exists, it is read at 2330275970Scystartup in order to set the initial frequency and then updated once per 2331275970Scyhour with the current frequency computed by the daemon. 2332275970ScyIf the file name is 2333275970Scyspecified, but the file itself does not exist, the starts with an initial 2334275970Scyfrequency of zero and creates the file when writing it for the first time. 2335275970ScyIf this command is not given, the daemon will always start with an initial 2336275970Scyfrequency of zero. 2337275970Scy 2338275970ScyThe file format consists of a single line containing a single 2339275970Scyfloating point number, which records the frequency offset measured 2340275970Scyin parts-per-million (PPM). 2341275970ScyThe file is updated by first writing 2342275970Scythe current drift value into a temporary file and then renaming 2343275970Scythis file to replace the old version. 2344275970ScyThis implies that 2345275970Scy@code{ntpd(1ntpdmdoc)} 2346275970Scymust have write permission for the directory the 2347275970Scydrift file is located in, and that file system links, symbolic or 2348275970Scyotherwise, should be avoided. 2349285612Sdelphij@item @code{dscp} @kbd{value} 2350285612SdelphijThis option specifies the Differentiated Services Control Point (DSCP) value, 2351298770Sdelphija 6-bit code. 2352298770SdelphijThe default value is 46, signifying Expedited Forwarding. 2353301301Sdelphij@item @code{enable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats} | @code{peer_clear_digest_early} | @code{unpeer_crypto_early} | @code{unpeer_crypto_nak_early} | @code{unpeer_digest_early}]} 2354301301Sdelphij@item @code{disable} @code{[@code{auth} | @code{bclient} | @code{calibrate} | @code{kernel} | @code{mode7} | @code{monitor} | @code{ntp} | @code{stats} | @code{peer_clear_digest_early} | @code{unpeer_crypto_early} | @code{unpeer_crypto_nak_early} | @code{unpeer_digest_early}]} 2355275970ScyProvides a way to enable or disable various server options. 2356275970ScyFlags not mentioned are unaffected. 2357275970ScyNote that all of these flags 2358275970Scycan be controlled remotely using the 2359275970Scy@code{ntpdc(1ntpdcmdoc)} 2360275970Scyutility program. 2361275970Scy@table @asis 2362275970Scy@item @code{auth} 2363275970ScyEnables the server to synchronize with unconfigured peers only if the 2364275970Scypeer has been correctly authenticated using either public key or 2365275970Scyprivate key cryptography. 2366275970ScyThe default for this flag is 2367275970Scy@code{enable}. 2368275970Scy@item @code{bclient} 2369275970ScyEnables the server to listen for a message from a broadcast or 2370275970Scymulticast server, as in the 2371275970Scy@code{multicastclient} 2372275970Scycommand with default 2373275970Scyaddress. 2374275970ScyThe default for this flag is 2375275970Scy@code{disable}. 2376275970Scy@item @code{calibrate} 2377275970ScyEnables the calibrate feature for reference clocks. 2378275970ScyThe default for 2379275970Scythis flag is 2380275970Scy@code{disable}. 2381275970Scy@item @code{kernel} 2382275970ScyEnables the kernel time discipline, if available. 2383275970ScyThe default for this 2384275970Scyflag is 2385275970Scy@code{enable} 2386275970Scyif support is available, otherwise 2387275970Scy@code{disable}. 2388275970Scy@item @code{mode7} 2389275970ScyEnables processing of NTP mode 7 implementation-specific requests 2390275970Scywhich are used by the deprecated 2391275970Scy@code{ntpdc(1ntpdcmdoc)} 2392275970Scyprogram. 2393275970ScyThe default for this flag is disable. 2394275970ScyThis flag is excluded from runtime configuration using 2395275970Scy@code{ntpq(1ntpqmdoc)}. 2396275970ScyThe 2397275970Scy@code{ntpq(1ntpqmdoc)} 2398275970Scyprogram provides the same capabilities as 2399275970Scy@code{ntpdc(1ntpdcmdoc)} 2400275970Scyusing standard mode 6 requests. 2401275970Scy@item @code{monitor} 2402275970ScyEnables the monitoring facility. 2403275970ScySee the 2404275970Scy@code{ntpdc(1ntpdcmdoc)} 2405275970Scyprogram 2406275970Scyand the 2407275970Scy@code{monlist} 2408275970Scycommand or further information. 2409275970ScyThe 2410275970Scydefault for this flag is 2411275970Scy@code{enable}. 2412275970Scy@item @code{ntp} 2413275970ScyEnables time and frequency discipline. 2414275970ScyIn effect, this switch opens and 2415275970Scycloses the feedback loop, which is useful for testing. 2416275970ScyThe default for 2417275970Scythis flag is 2418275970Scy@code{enable}. 2419301301Sdelphij@item @code{peer_clear_digest_early} 2420301301SdelphijBy default, if 2421301301Sdelphij@code{ntpd(1ntpdmdoc)} 2422301301Sdelphijis using autokey and it 2423301301Sdelphijreceives a crypto-NAK packet that 2424301301Sdelphijpasses the duplicate packet and origin timestamp checks 2425301301Sdelphijthe peer variables are immediately cleared. 2426301301SdelphijWhile this is generally a feature 2427301301Sdelphijas it allows for quick recovery if a server key has changed, 2428301301Sdelphija properly forged and appropriately delivered crypto-NAK packet 2429301301Sdelphijcan be used in a DoS attack. 2430301301SdelphijIf you have active noticable problems with this type of DoS attack 2431301301Sdelphijthen you should consider 2432301301Sdelphijdisabling this option. 2433301301SdelphijYou can check your 2434301301Sdelphij@code{peerstats} 2435301301Sdelphijfile for evidence of any of these attacks. 2436301301SdelphijThe 2437301301Sdelphijdefault for this flag is 2438301301Sdelphij@code{enable}. 2439275970Scy@item @code{stats} 2440275970ScyEnables the statistics facility. 2441275970ScySee the 2442275970Scy@ref{Monitoring Options} 2443275970Scysection for further information. 2444275970ScyThe default for this flag is 2445275970Scy@code{disable}. 2446294904Sdelphij@item @code{unpeer_crypto_early} 2447294904SdelphijBy default, if 2448294904Sdelphij@code{ntpd(1ntpdmdoc)} 2449294904Sdelphijreceives an autokey packet that fails TEST9, 2450294904Sdelphija crypto failure, 2451294904Sdelphijthe association is immediately cleared. 2452294904SdelphijThis is almost certainly a feature, 2453294904Sdelphijbut if, in spite of the current recommendation of not using autokey, 2454294904Sdelphijyou are 2455294904Sdelphij.B still 2456294904Sdelphijusing autokey 2457294904Sdelphij.B and 2458294904Sdelphijyou are seeing this sort of DoS attack 2459294904Sdelphijdisabling this flag will delay 2460294904Sdelphijtearing down the association until the reachability counter 2461294904Sdelphijbecomes zero. 2462294904SdelphijYou can check your 2463294904Sdelphij@code{peerstats} 2464294904Sdelphijfile for evidence of any of these attacks. 2465294904SdelphijThe 2466294904Sdelphijdefault for this flag is 2467294904Sdelphij@code{enable}. 2468294904Sdelphij@item @code{unpeer_crypto_nak_early} 2469294904SdelphijBy default, if 2470294904Sdelphij@code{ntpd(1ntpdmdoc)} 2471294904Sdelphijreceives a crypto-NAK packet that 2472294904Sdelphijpasses the duplicate packet and origin timestamp checks 2473294904Sdelphijthe association is immediately cleared. 2474294904SdelphijWhile this is generally a feature 2475294904Sdelphijas it allows for quick recovery if a server key has changed, 2476294904Sdelphija properly forged and appropriately delivered crypto-NAK packet 2477294904Sdelphijcan be used in a DoS attack. 2478294904SdelphijIf you have active noticable problems with this type of DoS attack 2479294904Sdelphijthen you should consider 2480294904Sdelphijdisabling this option. 2481294904SdelphijYou can check your 2482294904Sdelphij@code{peerstats} 2483294904Sdelphijfile for evidence of any of these attacks. 2484294904SdelphijThe 2485294904Sdelphijdefault for this flag is 2486294904Sdelphij@code{enable}. 2487294904Sdelphij@item @code{unpeer_digest_early} 2488294904SdelphijBy default, if 2489294904Sdelphij@code{ntpd(1ntpdmdoc)} 2490294904Sdelphijreceives what should be an authenticated packet 2491294904Sdelphijthat passes other packet sanity checks but 2492294904Sdelphijcontains an invalid digest 2493294904Sdelphijthe association is immediately cleared. 2494294904SdelphijWhile this is generally a feature 2495294904Sdelphijas it allows for quick recovery, 2496294904Sdelphijif this type of packet is carefully forged and sent 2497294904Sdelphijduring an appropriate window it can be used for a DoS attack. 2498294904SdelphijIf you have active noticable problems with this type of DoS attack 2499294904Sdelphijthen you should consider 2500294904Sdelphijdisabling this option. 2501294904SdelphijYou can check your 2502294904Sdelphij@code{peerstats} 2503294904Sdelphijfile for evidence of any of these attacks. 2504294904SdelphijThe 2505294904Sdelphijdefault for this flag is 2506294904Sdelphij@code{enable}. 2507275970Scy@end table 2508275970Scy@item @code{includefile} @kbd{includefile} 2509275970ScyThis command allows additional configuration commands 2510275970Scyto be included from a separate file. 2511275970ScyInclude files may 2512275970Scybe nested to a depth of five; upon reaching the end of any 2513275970Scyinclude file, command processing resumes in the previous 2514275970Scyconfiguration file. 2515275970ScyThis option is useful for sites that run 2516275970Scy@code{ntpd(1ntpdmdoc)} 2517275970Scyon multiple hosts, with (mostly) common options (e.g., a 2518275970Scyrestriction list). 2519285612Sdelphij@item @code{leapsmearinterval} @kbd{seconds} 2520285612SdelphijThis EXPERIMENTAL option is only available if 2521285612Sdelphij@code{ntpd(1ntpdmdoc)} 2522285612Sdelphijwas built with the 2523285612Sdelphij@code{--enable-leap-smear} 2524285612Sdelphijoption to the 2525285612Sdelphij@code{configure} 2526285612Sdelphijscript. 2527285612SdelphijIt specifies the interval over which a leap second correction will be applied. 2528285612SdelphijRecommended values for this option are between 2529285612Sdelphij7200 (2 hours) and 86400 (24 hours). 2530285612Sdelphij.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2531285612SdelphijSee http://bugs.ntp.org/2855 for more information. 2532275970Scy@item @code{logconfig} @kbd{configkeyword} 2533275970ScyThis command controls the amount and type of output written to 2534275970Scythe system 2535275970Scy@code{syslog(3)} 2536275970Scyfacility or the alternate 2537275970Scy@code{logfile} 2538275970Scylog file. 2539275970ScyBy default, all output is turned on. 2540275970ScyAll 2541275970Scy@kbd{configkeyword} 2542275970Scykeywords can be prefixed with 2543275970Scy@quoteleft{}=@quoteright{}, 2544275970Scy@quoteleft{}+@quoteright{} 2545275970Scyand 2546275970Scy@quoteleft{}-@quoteright{}, 2547275970Scywhere 2548275970Scy@quoteleft{}=@quoteright{} 2549275970Scysets the 2550275970Scy@code{syslog(3)} 2551275970Scypriority mask, 2552275970Scy@quoteleft{}+@quoteright{} 2553275970Scyadds and 2554275970Scy@quoteleft{}-@quoteright{} 2555275970Scyremoves 2556275970Scymessages. 2557275970Scy@code{syslog(3)} 2558275970Scymessages can be controlled in four 2559275970Scyclasses 2560275970Scy(@code{clock}, @code{peer}, @code{sys} and @code{sync}). 2561275970ScyWithin these classes four types of messages can be 2562275970Scycontrolled: informational messages 2563275970Scy(@code{info}), 2564275970Scyevent messages 2565275970Scy(@code{events}), 2566275970Scystatistics messages 2567275970Scy(@code{statistics}) 2568275970Scyand 2569275970Scystatus messages 2570275970Scy(@code{status}). 2571275970Scy 2572275970ScyConfiguration keywords are formed by concatenating the message class with 2573275970Scythe event class. 2574275970ScyThe 2575275970Scy@code{all} 2576275970Scyprefix can be used instead of a message class. 2577275970ScyA 2578275970Scymessage class may also be followed by the 2579275970Scy@code{all} 2580275970Scykeyword to enable/disable all 2581298770Sdelphijmessages of the respective message class. 2582298770SdelphijThus, a minimal log configuration 2583275970Scycould look like this: 2584275970Scy@verbatim 2585275970Scylogconfig =syncstatus +sysevents 2586275970Scy@end verbatim 2587275970Scy 2588275970ScyThis would just list the synchronizations state of 2589275970Scy@code{ntpd(1ntpdmdoc)} 2590275970Scyand the major system events. 2591275970ScyFor a simple reference server, the 2592275970Scyfollowing minimum message configuration could be useful: 2593275970Scy@verbatim 2594275970Scylogconfig =syncall +clockall 2595275970Scy@end verbatim 2596275970Scy 2597275970ScyThis configuration will list all clock information and 2598275970Scysynchronization information. 2599275970ScyAll other events and messages about 2600275970Scypeers, system events and so on is suppressed. 2601275970Scy@item @code{logfile} @kbd{logfile} 2602275970ScyThis command specifies the location of an alternate log file to 2603275970Scybe used instead of the default system 2604275970Scy@code{syslog(3)} 2605275970Scyfacility. 2606298770SdelphijThis is the same operation as the 2607298770Sdelphij@code{-l} 2608298770Sdelphijcommand line option. 2609275970Scy@item @code{setvar} @kbd{variable} @code{[@code{default}]} 2610275970ScyThis command adds an additional system variable. 2611275970ScyThese 2612275970Scyvariables can be used to distribute additional information such as 2613275970Scythe access policy. 2614275970ScyIf the variable of the form 2615275970Scy@code{name}@code{=}@kbd{value} 2616275970Scyis followed by the 2617275970Scy@code{default} 2618275970Scykeyword, the 2619275970Scyvariable will be listed as part of the default system variables 2620275970Scy(@code{rv} command)). 2621275970ScyThese additional variables serve 2622275970Scyinformational purposes only. 2623275970ScyThey are not related to the protocol 2624275970Scyother that they can be listed. 2625275970ScyThe known protocol variables will 2626275970Scyalways override any variables defined via the 2627275970Scy@code{setvar} 2628275970Scymechanism. 2629275970ScyThere are three special variables that contain the names 2630275970Scyof all variable of the same group. 2631275970ScyThe 2632275970Scy@code{sys_var_list} 2633275970Scyholds 2634275970Scythe names of all system variables. 2635275970ScyThe 2636275970Scy@code{peer_var_list} 2637275970Scyholds 2638275970Scythe names of all peer variables and the 2639275970Scy@code{clock_var_list} 2640275970Scyholds the names of the reference clock variables. 2641285612Sdelphij@item @code{tinker} @code{[@code{allan} @kbd{allan} | @code{dispersion} @kbd{dispersion} | @code{freq} @kbd{freq} | @code{huffpuff} @kbd{huffpuff} | @code{panic} @kbd{panic} | @code{step} @kbd{step} | @code{stepback} @kbd{stepback} | @code{stepfwd} @kbd{stepfwd} | @code{stepout} @kbd{stepout}]} 2642275970ScyThis command can be used to alter several system variables in 2643275970Scyvery exceptional circumstances. 2644275970ScyIt should occur in the 2645275970Scyconfiguration file before any other configuration options. 2646275970ScyThe 2647275970Scydefault values of these variables have been carefully optimized for 2648275970Scya wide range of network speeds and reliability expectations. 2649275970ScyIn 2650275970Scygeneral, they interact in intricate ways that are hard to predict 2651275970Scyand some combinations can result in some very nasty behavior. 2652275970ScyVery 2653275970Scyrarely is it necessary to change the default values; but, some 2654275970Scyfolks cannot resist twisting the knobs anyway and this command is 2655275970Scyfor them. 2656275970ScyEmphasis added: twisters are on their own and can expect 2657275970Scyno help from the support group. 2658275970Scy 2659275970ScyThe variables operate as follows: 2660275970Scy@table @asis 2661275970Scy@item @code{allan} @kbd{allan} 2662275970ScyThe argument becomes the new value for the minimum Allan 2663275970Scyintercept, which is a parameter of the PLL/FLL clock discipline 2664275970Scyalgorithm. 2665275970ScyThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 2666275970Scylimit. 2667275970Scy@item @code{dispersion} @kbd{dispersion} 2668275970ScyThe argument becomes the new value for the dispersion increase rate, 2669275970Scynormally .000015 s/s. 2670275970Scy@item @code{freq} @kbd{freq} 2671275970ScyThe argument becomes the initial value of the frequency offset in 2672275970Scyparts-per-million. 2673275970ScyThis overrides the value in the frequency file, if 2674275970Scypresent, and avoids the initial training state if it is not. 2675275970Scy@item @code{huffpuff} @kbd{huffpuff} 2676275970ScyThe argument becomes the new value for the experimental 2677275970Scyhuff-n'-puff filter span, which determines the most recent interval 2678275970Scythe algorithm will search for a minimum delay. 2679275970ScyThe lower limit is 2680275970Scy900 s (15 m), but a more reasonable value is 7200 (2 hours). 2681275970ScyThere 2682275970Scyis no default, since the filter is not enabled unless this command 2683275970Scyis given. 2684275970Scy@item @code{panic} @kbd{panic} 2685275970ScyThe argument is the panic threshold, normally 1000 s. 2686275970ScyIf set to zero, 2687275970Scythe panic sanity check is disabled and a clock offset of any value will 2688275970Scybe accepted. 2689275970Scy@item @code{step} @kbd{step} 2690275970ScyThe argument is the step threshold, which by default is 0.128 s. 2691275970ScyIt can 2692275970Scybe set to any positive number in seconds. 2693275970ScyIf set to zero, step 2694275970Scyadjustments will never occur. 2695275970ScyNote: The kernel time discipline is 2696275970Scydisabled if the step threshold is set to zero or greater than the 2697275970Scydefault. 2698285612Sdelphij@item @code{stepback} @kbd{stepback} 2699285612SdelphijThe argument is the step threshold for the backward direction, 2700285612Sdelphijwhich by default is 0.128 s. 2701285612SdelphijIt can 2702285612Sdelphijbe set to any positive number in seconds. 2703285612SdelphijIf both the forward and backward step thresholds are set to zero, step 2704285612Sdelphijadjustments will never occur. 2705285612SdelphijNote: The kernel time discipline is 2706285612Sdelphijdisabled if 2707285612Sdelphijeach direction of step threshold are either 2708285612Sdelphijset to zero or greater than .5 second. 2709285612Sdelphij@item @code{stepfwd} @kbd{stepfwd} 2710285612SdelphijAs for stepback, but for the forward direction. 2711275970Scy@item @code{stepout} @kbd{stepout} 2712275970ScyThe argument is the stepout timeout, which by default is 900 s. 2713275970ScyIt can 2714275970Scybe set to any positive number in seconds. 2715275970ScyIf set to zero, the stepout 2716275970Scypulses will not be suppressed. 2717275970Scy@end table 2718275970Scy@item @code{rlimit} @code{[@code{memlock} @kbd{Nmegabytes} | @code{stacksize} @kbd{N4kPages} @code{filenum} @kbd{Nfiledescriptors}]} 2719275970Scy@table @asis 2720275970Scy@item @code{memlock} @kbd{Nmegabytes} 2721289999SglebiusSpecify the number of megabytes of memory that should be 2722289999Sglebiusallocated and locked. 2723289999SglebiusProbably only available under Linux, this option may be useful 2724275970Scywhen dropping root (the 2725275970Scy@code{-i} 2726275970Scyoption). 2727289999SglebiusThe default is 32 megabytes on non-Linux machines, and -1 under Linux. 2728289999Sglebius-1 means "do not lock the process into memory". 2729289999Sglebius0 means "lock whatever memory the process wants into memory". 2730275970Scy@item @code{stacksize} @kbd{N4kPages} 2731275970ScySpecifies the maximum size of the process stack on systems with the 2732275970Scy@code{mlockall()} 2733275970Scyfunction. 2734275970ScyDefaults to 50 4k pages (200 4k pages in OpenBSD). 2735285612Sdelphij@item @code{filenum} @kbd{Nfiledescriptors} 2736298770SdelphijSpecifies the maximum number of file descriptors ntpd may have open at once. 2737298770SdelphijDefaults to the system default. 2738275970Scy@end table 2739275970Scy@item @code{trap} @kbd{host_address} @code{[@code{port} @kbd{port_number}]} @code{[@code{interface} @kbd{interface_address}]} 2740275970ScyThis command configures a trap receiver at the given host 2741275970Scyaddress and port number for sending messages with the specified 2742275970Scylocal interface address. 2743275970ScyIf the port number is unspecified, a value 2744275970Scyof 18447 is used. 2745275970ScyIf the interface address is not specified, the 2746275970Scymessage is sent with a source address of the local interface the 2747275970Scymessage is sent through. 2748275970ScyNote that on a multihomed host the 2749275970Scyinterface used may vary from time to time with routing changes. 2750275970Scy 2751275970ScyThe trap receiver will generally log event messages and other 2752275970Scyinformation from the server in a log file. 2753275970ScyWhile such monitor 2754275970Scyprograms may also request their own trap dynamically, configuring a 2755275970Scytrap receiver will ensure that no messages are lost when the server 2756275970Scyis started. 2757275970Scy@item @code{hop} @kbd{...} 2758275970ScyThis command specifies a list of TTL values in increasing order, up to 8 2759275970Scyvalues can be specified. 2760275970ScyIn manycast mode these values are used in turn in 2761275970Scyan expanding-ring search. 2762275970ScyThe default is eight multiples of 32 starting at 2763275970Scy31. 2764275970Scy@end table 2765275970Scy 2766275970ScyThis section was generated by @strong{AutoGen}, 2767275970Scyusing the @code{agtexi-cmd} template and the option descriptions for the @code{ntp.conf} program. 2768275970ScyThis software is released under the NTP license, <http://ntp.org/license>. 2769275970Scy 2770275970Scy@menu 2771275970Scy* ntp.conf Files:: Files 2772275970Scy* ntp.conf See Also:: See Also 2773275970Scy* ntp.conf Bugs:: Bugs 2774275970Scy* ntp.conf Notes:: Notes 2775275970Scy@end menu 2776275970Scy 2777275970Scy@node ntp.conf Files 2778275970Scy@subsection ntp.conf Files 2779275970Scy@table @asis 2780275970Scy@item @file{/etc/ntp.conf} 2781275970Scythe default name of the configuration file 2782275970Scy@item @file{ntp.keys} 2783275970Scyprivate MD5 keys 2784275970Scy@item @file{ntpkey} 2785275970ScyRSA private key 2786275970Scy@item @file{ntpkey_}@kbd{host} 2787275970ScyRSA public key 2788275970Scy@item @file{ntp_dh} 2789275970ScyDiffie-Hellman agreement parameters 2790275970Scy@end table 2791275970Scy@node ntp.conf See Also 2792275970Scy@subsection ntp.conf See Also 2793275970Scy@code{ntpd(1ntpdmdoc)}, 2794275970Scy@code{ntpdc(1ntpdcmdoc)}, 2795275970Scy@code{ntpq(1ntpqmdoc)} 2796275970Scy 2797275970ScyIn addition to the manual pages provided, 2798275970Scycomprehensive documentation is available on the world wide web 2799275970Scyat 2800275970Scy@code{http://www.ntp.org/}. 2801275970ScyA snapshot of this documentation is available in HTML format in 2802275970Scy@file{/usr/share/doc/ntp}. 2803275970Scy@* 2804275970Scy 2805275970Scy@* 2806275970ScyDavid L. Mills, @emph{Network Time Protocol (Version 4)}, RFC5905 2807275970Scy@node ntp.conf Bugs 2808275970Scy@subsection ntp.conf Bugs 2809275970ScyThe syntax checking is not picky; some combinations of 2810275970Scyridiculous and even hilarious options and modes may not be 2811275970Scydetected. 2812275970Scy 2813275970ScyThe 2814275970Scy@file{ntpkey_}@kbd{host} 2815275970Scyfiles are really digital 2816275970Scycertificates. 2817275970ScyThese should be obtained via secure directory 2818275970Scyservices when they become universally available. 2819275970Scy@node ntp.conf Notes 2820275970Scy@subsection ntp.conf Notes 2821275970ScyThis document was derived from FreeBSD. 2822