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