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