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