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