1275970Scy.de1 NOP 2275970Scy. it 1 an-trap 3275970Scy. if \\n[.$] \,\\$*\/ 4275970Scy.. 5275970Scy.ie t \ 6275970Scy.ds B-Font [CB] 7275970Scy.ds I-Font [CI] 8275970Scy.ds R-Font [CR] 9275970Scy.el \ 10275970Scy.ds B-Font B 11275970Scy.ds I-Font I 12275970Scy.ds R-Font R 13362716Scy.TH ntp.conf 5 "23 Jun 2020" "4.2.8p15" "File Formats" 14275970Scy.\" 15344884Scy.\" EDIT THIS FILE WITH CAUTION (in-mem file) 16275970Scy.\" 17362716Scy.\" It has been AutoGen-ed June 23, 2020 at 02:20:36 AM by AutoGen 5.18.5 18275970Scy.\" From the definitions ntp.conf.def 19275970Scy.\" and the template file agman-cmd.tpl 20275970Scy.SH NAME 21275970Scy\f\*[B-Font]ntp.conf\fP 22275970Scy\- Network Time Protocol (NTP) daemon configuration file format 23275970Scy.SH SYNOPSIS 24275970Scy\f\*[B-Font]ntp.conf\fP 25275970Scy[\f\*[B-Font]\-\-option-name\f[]] 26275970Scy[\f\*[B-Font]\-\-option-name\f[] \f\*[I-Font]value\f[]] 27275970Scy.sp \n(Ppu 28275970Scy.ne 2 29275970Scy 30275970ScyAll arguments must be options. 31275970Scy.sp \n(Ppu 32275970Scy.ne 2 33275970Scy 34275970Scy.SH DESCRIPTION 35275970ScyThe 36275970Scy\f\*[B-Font]ntp.conf\fP 37275970Scyconfiguration file is read at initial startup by the 38285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 39275970Scydaemon in order to specify the synchronization sources, 40275970Scymodes and other related information. 41275970ScyUsually, it is installed in the 42275970Scy\fI/etc\f[] 43275970Scydirectory, 44275970Scybut could be installed elsewhere 45275970Scy(see the daemon's 46275970Scy\f\*[B-Font]\-c\f[] 47275970Scycommand line option). 48275970Scy.sp \n(Ppu 49275970Scy.ne 2 50275970Scy 51275970ScyThe file format is similar to other 52275970ScyUNIX 53275970Scyconfiguration files. 54275970ScyComments begin with a 55275970Scy\[oq]#\[cq] 56275970Scycharacter and extend to the end of the line; 57275970Scyblank lines are ignored. 58275970ScyConfiguration commands consist of an initial keyword 59275970Scyfollowed by a list of arguments, 60275970Scysome of which may be optional, separated by whitespace. 61275970ScyCommands may not be continued over multiple lines. 62275970ScyArguments may be host names, 63275970Scyhost addresses written in numeric, dotted-quad form, 64275970Scyintegers, floating point numbers (when specifying times in seconds) 65275970Scyand text strings. 66275970Scy.sp \n(Ppu 67275970Scy.ne 2 68275970Scy 69275970ScyThe rest of this page describes the configuration and control options. 70275970ScyThe 71275970Scy"Notes on Configuring NTP and Setting up an NTP Subnet" 72275970Scypage 73275970Scy(available as part of the HTML documentation 74275970Scyprovided in 75275970Scy\fI/usr/share/doc/ntp\f[]) 76275970Scycontains an extended discussion of these options. 77275970ScyIn addition to the discussion of general 78275970Scy\fIConfiguration\f[] \fIOptions\f[], 79275970Scythere are sections describing the following supported functionality 80275970Scyand the options used to control it: 81275970Scy.IP \fB\(bu\fP 2 82275970Scy\fIAuthentication\f[] \fISupport\f[] 83275970Scy.IP \fB\(bu\fP 2 84275970Scy\fIMonitoring\f[] \fISupport\f[] 85275970Scy.IP \fB\(bu\fP 2 86275970Scy\fIAccess\f[] \fIControl\f[] \fISupport\f[] 87275970Scy.IP \fB\(bu\fP 2 88275970Scy\fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[] 89275970Scy.IP \fB\(bu\fP 2 90275970Scy\fIReference\f[] \fIClock\f[] \fISupport\f[] 91275970Scy.IP \fB\(bu\fP 2 92275970Scy\fIMiscellaneous\f[] \fIOptions\f[] 93275970Scy.PP 94275970Scy.sp \n(Ppu 95275970Scy.ne 2 96275970Scy 97275970ScyFollowing these is a section describing 98275970Scy\fIMiscellaneous\f[] \fIOptions\f[]. 99275970ScyWhile there is a rich set of options available, 100275970Scythe only required option is one or more 101275970Scy\f\*[B-Font]pool\f[], 102275970Scy\f\*[B-Font]server\f[], 103275970Scy\f\*[B-Font]peer\f[], 104275970Scy\f\*[B-Font]broadcast\f[] 105275970Scyor 106275970Scy\f\*[B-Font]manycastclient\f[] 107275970Scycommands. 108275970Scy.SH Configuration Support 109275970ScyFollowing is a description of the configuration commands in 110275970ScyNTPv4. 111275970ScyThese commands have the same basic functions as in NTPv3 and 112275970Scyin some cases new functions and new arguments. 113275970ScyThere are two 114275970Scyclasses of commands, configuration commands that configure a 115275970Scypersistent association with a remote server or peer or reference 116275970Scyclock, and auxiliary commands that specify environmental variables 117275970Scythat control various related operations. 118275970Scy.SS Configuration Commands 119275970ScyThe various modes are determined by the command keyword and the 120275970Scytype of the required IP address. 121275970ScyAddresses are classed by type as 122275970Scy(s) a remote server or peer (IPv4 class A, B and C), (b) the 123275970Scybroadcast address of a local interface, (m) a multicast address (IPv4 124275970Scyclass D), or (r) a reference clock address (127.127.x.x). 125275970ScyNote that 126275970Scyonly those options applicable to each command are listed below. 127275970ScyUse 128275970Scyof options not listed may not be caught as an error, but may result 129275970Scyin some weird and even destructive behavior. 130275970Scy.sp \n(Ppu 131275970Scy.ne 2 132275970Scy 133275970ScyIf the Basic Socket Interface Extensions for IPv6 (RFC-2553) 134275970Scyis detected, support for the IPv6 address family is generated 135275970Scyin addition to the default support of the IPv4 address family. 136298695SdelphijIn a few cases, including the 137298695Sdelphij\f\*[B-Font]reslist\f[] 138298695Sdelphijbillboard generated 139298695Sdelphijby 140298695Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 141298695Sdelphijor 142298695Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[], 143298695SdelphijIPv6 addresses are automatically generated. 144275970ScyIPv6 addresses can be identified by the presence of colons 145275970Scy\*[Lq]\&:\*[Rq] 146275970Scyin the address field. 147275970ScyIPv6 addresses can be used almost everywhere where 148275970ScyIPv4 addresses can be used, 149275970Scywith the exception of reference clock addresses, 150275970Scywhich are always IPv4. 151275970Scy.sp \n(Ppu 152275970Scy.ne 2 153275970Scy 154275970ScyNote that in contexts where a host name is expected, a 155275970Scy\f\*[B-Font]\-4\f[] 156275970Scyqualifier preceding 157275970Scythe host name forces DNS resolution to the IPv4 namespace, 158275970Scywhile a 159275970Scy\f\*[B-Font]\-6\f[] 160275970Scyqualifier forces DNS resolution to the IPv6 namespace. 161275970ScySee IPv6 references for the 162275970Scyequivalent classes for that address family. 163275970Scy.TP 7 164358659Scy.NOP \f\*[B-Font]pool\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]burst\f[]] [\f\*[B-Font]iburst\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]xmtnonce\f[]] 165275970Scy.TP 7 166358659Scy.NOP \f\*[B-Font]server\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]burst\f[]] [\f\*[B-Font]iburst\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]true\f[]] [\f\*[B-Font]xmtnonce\f[]] 167275970Scy.TP 7 168298695Sdelphij.NOP \f\*[B-Font]peer\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]true\f[]] [\f\*[B-Font]xleave\f[]] 169275970Scy.TP 7 170298695Sdelphij.NOP \f\*[B-Font]broadcast\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[]] [\f\*[B-Font]xleave\f[]] 171275970Scy.TP 7 172275970Scy.NOP \f\*[B-Font]manycastclient\f[] \f\*[I-Font]address\f[] [\f\*[B-Font]key\f[] \f\*[I-Font]key\f[] \f\*[I-Font]\&|\f[] \f\*[B-Font]autokey\f[]] [\f\*[B-Font]version\f[] \f\*[I-Font]version\f[]] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[]] [\f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[]] 173275970Scy.PP 174275970Scy.sp \n(Ppu 175275970Scy.ne 2 176275970Scy 177275970ScyThese five commands specify the time server name or address to 178275970Scybe used and the mode in which to operate. 179275970ScyThe 180275970Scy\f\*[I-Font]address\f[] 181275970Scycan be 182275970Scyeither a DNS name or an IP address in dotted-quad notation. 183275970ScyAdditional information on association behavior can be found in the 184275970Scy"Association Management" 185275970Scypage 186275970Scy(available as part of the HTML documentation 187275970Scyprovided in 188275970Scy\fI/usr/share/doc/ntp\f[]). 189275970Scy.TP 7 190275970Scy.NOP \f\*[B-Font]pool\f[] 191275970ScyFor type s addresses, this command mobilizes a persistent 192275970Scyclient mode association with a number of remote servers. 193275970ScyIn this mode the local clock can synchronized to the 194275970Scyremote server, but the remote server can never be synchronized to 195275970Scythe local clock. 196275970Scy.TP 7 197275970Scy.NOP \f\*[B-Font]server\f[] 198275970ScyFor type s and r addresses, this command mobilizes a persistent 199275970Scyclient mode association with the specified remote server or local 200275970Scyradio clock. 201275970ScyIn this mode the local clock can synchronized to the 202275970Scyremote server, but the remote server can never be synchronized to 203275970Scythe local clock. 204275970ScyThis command should 205275970Scy\fInot\f[] 206275970Scybe used for type 207275970Scyb or m addresses. 208275970Scy.TP 7 209275970Scy.NOP \f\*[B-Font]peer\f[] 210275970ScyFor type s addresses (only), this command mobilizes a 211275970Scypersistent symmetric-active mode association with the specified 212275970Scyremote peer. 213275970ScyIn this mode the local clock can be synchronized to 214275970Scythe remote peer or the remote peer can be synchronized to the local 215275970Scyclock. 216275970ScyThis is useful in a network of servers where, depending on 217275970Scyvarious failure scenarios, either the local or remote peer may be 218275970Scythe better source of time. 219275970ScyThis command should NOT be used for type 220275970Scyb, m or r addresses. 221275970Scy.TP 7 222275970Scy.NOP \f\*[B-Font]broadcast\f[] 223275970ScyFor type b and m addresses (only), this 224275970Scycommand mobilizes a persistent broadcast mode association. 225275970ScyMultiple 226275970Scycommands can be used to specify multiple local broadcast interfaces 227275970Scy(subnets) and/or multiple multicast groups. 228275970ScyNote that local 229275970Scybroadcast messages go only to the interface associated with the 230275970Scysubnet specified, but multicast messages go to all interfaces. 231275970ScyIn broadcast mode the local server sends periodic broadcast 232275970Scymessages to a client population at the 233275970Scy\f\*[I-Font]address\f[] 234275970Scyspecified, which is usually the broadcast address on (one of) the 235275970Scylocal network(s) or a multicast address assigned to NTP. 236275970ScyThe IANA 237275970Scyhas assigned the multicast group address IPv4 224.0.1.1 and 238275970ScyIPv6 ff05::101 (site local) exclusively to 239275970ScyNTP, but other nonconflicting addresses can be used to contain the 240275970Scymessages within administrative boundaries. 241275970ScyOrdinarily, this 242275970Scyspecification applies only to the local server operating as a 243275970Scysender; for operation as a broadcast client, see the 244275970Scy\f\*[B-Font]broadcastclient\f[] 245275970Scyor 246275970Scy\f\*[B-Font]multicastclient\f[] 247275970Scycommands 248275970Scybelow. 249275970Scy.TP 7 250275970Scy.NOP \f\*[B-Font]manycastclient\f[] 251275970ScyFor type m addresses (only), this command mobilizes a 252275970Scymanycast client mode association for the multicast address 253275970Scyspecified. 254275970ScyIn this case a specific address must be supplied which 255275970Scymatches the address used on the 256275970Scy\f\*[B-Font]manycastserver\f[] 257275970Scycommand for 258275970Scythe designated manycast servers. 259275970ScyThe NTP multicast address 260275970Scy224.0.1.1 assigned by the IANA should NOT be used, unless specific 261275970Scymeans are taken to avoid spraying large areas of the Internet with 262275970Scythese messages and causing a possibly massive implosion of replies 263275970Scyat the sender. 264275970ScyThe 265275970Scy\f\*[B-Font]manycastserver\f[] 266275970Scycommand specifies that the local server 267275970Scyis to operate in client mode with the remote servers that are 268275970Scydiscovered as the result of broadcast/multicast messages. 269275970ScyThe 270275970Scyclient broadcasts a request message to the group address associated 271275970Scywith the specified 272275970Scy\f\*[I-Font]address\f[] 273275970Scyand specifically enabled 274275970Scyservers respond to these messages. 275275970ScyThe client selects the servers 276275970Scyproviding the best time and continues as with the 277275970Scy\f\*[B-Font]server\f[] 278275970Scycommand. 279275970ScyThe remaining servers are discarded as if never 280275970Scyheard. 281275970Scy.PP 282275970Scy.sp \n(Ppu 283275970Scy.ne 2 284275970Scy 285275970ScyOptions: 286275970Scy.TP 7 287275970Scy.NOP \f\*[B-Font]autokey\f[] 288275970ScyAll packets sent to and received from the server or peer are to 289275970Scyinclude authentication fields encrypted using the autokey scheme 290275970Scydescribed in 291275970Scy\fIAuthentication\f[] \fIOptions\f[]. 292275970Scy.TP 7 293275970Scy.NOP \f\*[B-Font]burst\f[] 294275970Scywhen the server is reachable, send a burst of eight packets 295275970Scyinstead of the usual one. 296275970ScyThe packet spacing is normally 2 s; 297275970Scyhowever, the spacing between the first and second packets 298298695Sdelphijcan be changed with the 299298695Sdelphij\f\*[B-Font]calldelay\f[] 300298695Sdelphijcommand to allow 301275970Scyadditional time for a modem or ISDN call to complete. 302275970ScyThis is designed to improve timekeeping quality 303275970Scywith the 304275970Scy\f\*[B-Font]server\f[] 305275970Scycommand and s addresses. 306275970Scy.TP 7 307275970Scy.NOP \f\*[B-Font]iburst\f[] 308275970ScyWhen the server is unreachable, send a burst of eight packets 309275970Scyinstead of the usual one. 310275970ScyThe packet spacing is normally 2 s; 311275970Scyhowever, the spacing between the first two packets can be 312298695Sdelphijchanged with the 313298695Sdelphij\f\*[B-Font]calldelay\f[] 314298695Sdelphijcommand to allow 315275970Scyadditional time for a modem or ISDN call to complete. 316275970ScyThis is designed to speed the initial synchronization 317275970Scyacquisition with the 318275970Scy\f\*[B-Font]server\f[] 319275970Scycommand and s addresses and when 320285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 321275970Scyis started with the 322275970Scy\f\*[B-Font]\-q\f[] 323275970Scyoption. 324275970Scy.TP 7 325275970Scy.NOP \f\*[B-Font]key\f[] \f\*[I-Font]key\f[] 326275970ScyAll packets sent to and received from the server or peer are to 327275970Scyinclude authentication fields encrypted using the specified 328275970Scy\f\*[I-Font]key\f[] 329338530Sdelphijidentifier with values from 1 to 65535, inclusive. 330275970ScyThe 331275970Scydefault is to include no encryption field. 332275970Scy.TP 7 333275970Scy.NOP \f\*[B-Font]minpoll\f[] \f\*[I-Font]minpoll\f[] 334275970Scy.TP 7 335275970Scy.NOP \f\*[B-Font]maxpoll\f[] \f\*[I-Font]maxpoll\f[] 336275970ScyThese options specify the minimum and maximum poll intervals 337275970Scyfor NTP messages, as a power of 2 in seconds 338275970ScyThe maximum poll 339275970Scyinterval defaults to 10 (1,024 s), but can be increased by the 340275970Scy\f\*[B-Font]maxpoll\f[] 341275970Scyoption to an upper limit of 17 (36.4 h). 342275970ScyThe 343275970Scyminimum poll interval defaults to 6 (64 s), but can be decreased by 344275970Scythe 345275970Scy\f\*[B-Font]minpoll\f[] 346275970Scyoption to a lower limit of 4 (16 s). 347275970Scy.TP 7 348275970Scy.NOP \f\*[B-Font]noselect\f[] 349275970ScyMarks the server as unused, except for display purposes. 350275970ScyThe server is discarded by the selection algroithm. 351275970Scy.TP 7 352298695Sdelphij.NOP \f\*[B-Font]preempt\f[] 353298695SdelphijSays the association can be preempted. 354298695Sdelphij.TP 7 355275970Scy.NOP \f\*[B-Font]prefer\f[] 356275970ScyMarks the server as preferred. 357275970ScyAll other things being equal, 358275970Scythis host will be chosen for synchronization among a set of 359275970Scycorrectly operating hosts. 360275970ScySee the 361275970Scy"Mitigation Rules and the prefer Keyword" 362275970Scypage 363275970Scy(available as part of the HTML documentation 364275970Scyprovided in 365275970Scy\fI/usr/share/doc/ntp\f[]) 366275970Scyfor further information. 367275970Scy.TP 7 368298695Sdelphij.NOP \f\*[B-Font]true\f[] 369358659ScyMarks the server as a truechimer, 370358659Scyforcing the association to always survive the selection and clustering algorithms. 371298695SdelphijThis option should almost certainly 372298695Sdelphij\fIonly\f[] 373298695Sdelphijbe used while testing an association. 374298695Sdelphij.TP 7 375275970Scy.NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[] 376275970ScyThis option is used only with broadcast server and manycast 377275970Scyclient modes. 378275970ScyIt specifies the time-to-live 379275970Scy\f\*[I-Font]ttl\f[] 380275970Scyto 381275970Scyuse on broadcast server and multicast server and the maximum 382275970Scy\f\*[I-Font]ttl\f[] 383275970Scyfor the expanding ring search with manycast 384275970Scyclient packets. 385275970ScySelection of the proper value, which defaults to 386275970Scy127, is something of a black art and should be coordinated with the 387275970Scynetwork administrator. 388275970Scy.TP 7 389275970Scy.NOP \f\*[B-Font]version\f[] \f\*[I-Font]version\f[] 390275970ScySpecifies the version number to be used for outgoing NTP 391275970Scypackets. 392275970ScyVersions 1-4 are the choices, with version 4 the 393275970Scydefault. 394298695Sdelphij.TP 7 395298695Sdelphij.NOP \f\*[B-Font]xleave\f[] 396298695SdelphijValid in 397298695Sdelphij\f\*[B-Font]peer\f[] 398298695Sdelphijand 399298695Sdelphij\f\*[B-Font]broadcast\f[] 400298695Sdelphijmodes only, this flag enables interleave mode. 401358659Scy.TP 7 402358659Scy.NOP \f\*[B-Font]xmtnonce\f[] 403358659ScyValid only for 404358659Scy\f\*[B-Font]server\f[] 405358659Scyand 406358659Scy\f\*[B-Font]pool\f[] 407358659Scymodes, this flag puts a random number in the packet's transmit timestamp. 408275970Scy.PP 409275970Scy.SS Auxiliary Commands 410275970Scy.TP 7 411275970Scy.NOP \f\*[B-Font]broadcastclient\f[] 412275970ScyThis command enables reception of broadcast server messages to 413275970Scyany local interface (type b) address. 414275970ScyUpon receiving a message for 415275970Scythe first time, the broadcast client measures the nominal server 416275970Scypropagation delay using a brief client/server exchange with the 417275970Scyserver, then enters the broadcast client mode, in which it 418275970Scysynchronizes to succeeding broadcast messages. 419275970ScyNote that, in order 420275970Scyto avoid accidental or malicious disruption in this mode, both the 421275970Scyserver and client should operate using symmetric-key or public-key 422275970Scyauthentication as described in 423275970Scy\fIAuthentication\f[] \fIOptions\f[]. 424275970Scy.TP 7 425275970Scy.NOP \f\*[B-Font]manycastserver\f[] \f\*[I-Font]address\f[] \f\*[I-Font]...\f[] 426275970ScyThis command enables reception of manycast client messages to 427275970Scythe multicast group address(es) (type m) specified. 428275970ScyAt least one 429275970Scyaddress is required, but the NTP multicast address 224.0.1.1 430275970Scyassigned by the IANA should NOT be used, unless specific means are 431275970Scytaken to limit the span of the reply and avoid a possibly massive 432275970Scyimplosion at the original sender. 433275970ScyNote that, in order to avoid 434275970Scyaccidental or malicious disruption in this mode, both the server 435275970Scyand client should operate using symmetric-key or public-key 436275970Scyauthentication as described in 437275970Scy\fIAuthentication\f[] \fIOptions\f[]. 438275970Scy.TP 7 439275970Scy.NOP \f\*[B-Font]multicastclient\f[] \f\*[I-Font]address\f[] \f\*[I-Font]...\f[] 440275970ScyThis command enables reception of multicast server messages to 441275970Scythe multicast group address(es) (type m) specified. 442275970ScyUpon receiving 443275970Scya message for the first time, the multicast client measures the 444275970Scynominal server propagation delay using a brief client/server 445275970Scyexchange with the server, then enters the broadcast client mode, in 446275970Scywhich it synchronizes to succeeding multicast messages. 447275970ScyNote that, 448275970Scyin order to avoid accidental or malicious disruption in this mode, 449275970Scyboth the server and client should operate using symmetric-key or 450275970Scypublic-key authentication as described in 451275970Scy\fIAuthentication\f[] \fIOptions\f[]. 452280849Scy.TP 7 453280849Scy.NOP \f\*[B-Font]mdnstries\f[] \f\*[I-Font]number\f[] 454280849ScyIf we are participating in mDNS, 455280849Scyafter we have synched for the first time 456280849Scywe attempt to register with the mDNS system. 457280849ScyIf that registration attempt fails, 458280849Scywe try again at one minute intervals for up to 459280849Scy\f\*[B-Font]mdnstries\f[] 460280849Scytimes. 461280849ScyAfter all, 462280849Scy\f\*[B-Font]ntpd\f[] 463280849Scymay be starting before mDNS. 464280849ScyThe default value for 465280849Scy\f\*[B-Font]mdnstries\f[] 466280849Scyis 5. 467275970Scy.PP 468275970Scy.SH Authentication Support 469275970ScyAuthentication support allows the NTP client to verify that the 470275970Scyserver is in fact known and trusted and not an intruder intending 471275970Scyaccidentally or on purpose to masquerade as that server. 472275970ScyThe NTPv3 473275970Scyspecification RFC-1305 defines a scheme which provides 474275970Scycryptographic authentication of received NTP packets. 475275970ScyOriginally, 476275970Scythis was done using the Data Encryption Standard (DES) algorithm 477275970Scyoperating in Cipher Block Chaining (CBC) mode, commonly called 478275970ScyDES-CBC. 479275970ScySubsequently, this was replaced by the RSA Message Digest 480275970Scy5 (MD5) algorithm using a private key, commonly called keyed-MD5. 481275970ScyEither algorithm computes a message digest, or one-way hash, which 482275970Scycan be used to verify the server has the correct private key and 483275970Scykey identifier. 484275970Scy.sp \n(Ppu 485275970Scy.ne 2 486275970Scy 487275970ScyNTPv4 retains the NTPv3 scheme, properly described as symmetric key 488275970Scycryptography and, in addition, provides a new Autokey scheme 489275970Scybased on public key cryptography. 490275970ScyPublic key cryptography is generally considered more secure 491275970Scythan symmetric key cryptography, since the security is based 492275970Scyon a private value which is generated by each server and 493275970Scynever revealed. 494275970ScyWith Autokey all key distribution and 495275970Scymanagement functions involve only public values, which 496275970Scyconsiderably simplifies key distribution and storage. 497275970ScyPublic key management is based on X.509 certificates, 498275970Scywhich can be provided by commercial services or 499275970Scyproduced by utility programs in the OpenSSL software library 500275970Scyor the NTPv4 distribution. 501275970Scy.sp \n(Ppu 502275970Scy.ne 2 503275970Scy 504275970ScyWhile the algorithms for symmetric key cryptography are 505275970Scyincluded in the NTPv4 distribution, public key cryptography 506275970Scyrequires the OpenSSL software library to be installed 507275970Scybefore building the NTP distribution. 508275970ScyDirections for doing that 509275970Scyare on the Building and Installing the Distribution page. 510275970Scy.sp \n(Ppu 511275970Scy.ne 2 512275970Scy 513275970ScyAuthentication is configured separately for each association 514275970Scyusing the 515275970Scy\f\*[B-Font]key\f[] 516275970Scyor 517275970Scy\f\*[B-Font]autokey\f[] 518275970Scysubcommand on the 519275970Scy\f\*[B-Font]peer\f[], 520275970Scy\f\*[B-Font]server\f[], 521275970Scy\f\*[B-Font]broadcast\f[] 522275970Scyand 523275970Scy\f\*[B-Font]manycastclient\f[] 524275970Scyconfiguration commands as described in 525275970Scy\fIConfiguration\f[] \fIOptions\f[] 526275970Scypage. 527275970ScyThe authentication 528275970Scyoptions described below specify the locations of the key files, 529275970Scyif other than default, which symmetric keys are trusted 530275970Scyand the interval between various operations, if other than default. 531275970Scy.sp \n(Ppu 532275970Scy.ne 2 533275970Scy 534275970ScyAuthentication is always enabled, 535275970Scyalthough ineffective if not configured as 536275970Scydescribed below. 537275970ScyIf a NTP packet arrives 538275970Scyincluding a message authentication 539275970Scycode (MAC), it is accepted only if it 540275970Scypasses all cryptographic checks. 541275970ScyThe 542275970Scychecks require correct key ID, key value 543275970Scyand message digest. 544275970ScyIf the packet has 545275970Scybeen modified in any way or replayed 546275970Scyby an intruder, it will fail one or more 547275970Scyof these checks and be discarded. 548275970ScyFurthermore, the Autokey scheme requires a 549275970Scypreliminary protocol exchange to obtain 550275970Scythe server certificate, verify its 551275970Scycredentials and initialize the protocol 552275970Scy.sp \n(Ppu 553275970Scy.ne 2 554275970Scy 555275970ScyThe 556275970Scy\f\*[B-Font]auth\f[] 557275970Scyflag controls whether new associations or 558275970Scyremote configuration commands require cryptographic authentication. 559275970ScyThis flag can be set or reset by the 560275970Scy\f\*[B-Font]enable\f[] 561275970Scyand 562275970Scy\f\*[B-Font]disable\f[] 563275970Scycommands and also by remote 564275970Scyconfiguration commands sent by a 565285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 566298695Sdelphijprogram running on 567275970Scyanother machine. 568275970ScyIf this flag is enabled, which is the default 569275970Scycase, new broadcast client and symmetric passive associations and 570275970Scyremote configuration commands must be cryptographically 571275970Scyauthenticated using either symmetric key or public key cryptography. 572275970ScyIf this 573275970Scyflag is disabled, these operations are effective 574275970Scyeven if not cryptographic 575275970Scyauthenticated. 576275970ScyIt should be understood 577275970Scythat operating with the 578275970Scy\f\*[B-Font]auth\f[] 579275970Scyflag disabled invites a significant vulnerability 580275970Scywhere a rogue hacker can 581275970Scymasquerade as a falseticker and seriously 582275970Scydisrupt system timekeeping. 583275970ScyIt is 584275970Scyimportant to note that this flag has no purpose 585275970Scyother than to allow or disallow 586275970Scya new association in response to new broadcast 587275970Scyand symmetric active messages 588275970Scyand remote configuration commands and, in particular, 589275970Scythe flag has no effect on 590275970Scythe authentication process itself. 591275970Scy.sp \n(Ppu 592275970Scy.ne 2 593275970Scy 594275970ScyAn attractive alternative where multicast support is available 595275970Scyis manycast mode, in which clients periodically troll 596275970Scyfor servers as described in the 597275970Scy\fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[] 598275970Scypage. 599275970ScyEither symmetric key or public key 600275970Scycryptographic authentication can be used in this mode. 601275970ScyThe principle advantage 602275970Scyof manycast mode is that potential servers need not be 603275970Scyconfigured in advance, 604275970Scysince the client finds them during regular operation, 605275970Scyand the configuration 606275970Scyfiles for all clients can be identical. 607275970Scy.sp \n(Ppu 608275970Scy.ne 2 609275970Scy 610275970ScyThe security model and protocol schemes for 611275970Scyboth symmetric key and public key 612275970Scycryptography are summarized below; 613275970Scyfurther details are in the briefings, papers 614275970Scyand reports at the NTP project page linked from 615275970Scy\f[C]http://www.ntp.org/\f[]. 616275970Scy.SS Symmetric-Key Cryptography 617275970ScyThe original RFC-1305 specification allows any one of possibly 618338530Sdelphij65,535 keys, each distinguished by a 32-bit key identifier, to 619275970Scyauthenticate an association. 620275970ScyThe servers and clients involved must 621275970Scyagree on the key and key identifier to 622275970Scyauthenticate NTP packets. 623275970ScyKeys and 624275970Scyrelated information are specified in a key 625275970Scyfile, usually called 626275970Scy\fIntp.keys\f[], 627275970Scywhich must be distributed and stored using 628275970Scysecure means beyond the scope of the NTP protocol itself. 629275970ScyBesides the keys used 630275970Scyfor ordinary NTP associations, 631275970Scyadditional keys can be used as passwords for the 632285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 633275970Scyand 634285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 635275970Scyutility programs. 636275970Scy.sp \n(Ppu 637275970Scy.ne 2 638275970Scy 639275970ScyWhen 640285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 641275970Scyis first started, it reads the key file specified in the 642275970Scy\f\*[B-Font]keys\f[] 643275970Scyconfiguration command and installs the keys 644275970Scyin the key cache. 645275970ScyHowever, 646275970Scyindividual keys must be activated with the 647275970Scy\f\*[B-Font]trusted\f[] 648275970Scycommand before use. 649275970ScyThis 650275970Scyallows, for instance, the installation of possibly 651275970Scyseveral batches of keys and 652275970Scythen activating or deactivating each batch 653275970Scyremotely using 654285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[]. 655275970ScyThis also provides a revocation capability that can be used 656275970Scyif a key becomes compromised. 657275970ScyThe 658275970Scy\f\*[B-Font]requestkey\f[] 659275970Scycommand selects the key used as the password for the 660285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 661275970Scyutility, while the 662275970Scy\f\*[B-Font]controlkey\f[] 663275970Scycommand selects the key used as the password for the 664285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 665275970Scyutility. 666275970Scy.SS Public Key Cryptography 667275970ScyNTPv4 supports the original NTPv3 symmetric key scheme 668275970Scydescribed in RFC-1305 and in addition the Autokey protocol, 669275970Scywhich is based on public key cryptography. 670275970ScyThe Autokey Version 2 protocol described on the Autokey Protocol 671275970Scypage verifies packet integrity using MD5 message digests 672275970Scyand verifies the source with digital signatures and any of several 673275970Scydigest/signature schemes. 674275970ScyOptional identity schemes described on the Identity Schemes 675275970Scypage and based on cryptographic challenge/response algorithms 676275970Scyare also available. 677275970ScyUsing all of these schemes provides strong security against 678275970Scyreplay with or without modification, spoofing, masquerade 679275970Scyand most forms of clogging attacks. 680275970Scy.\" .Pp 681275970Scy.\" The cryptographic means necessary for all Autokey operations 682275970Scy.\" is provided by the OpenSSL software library. 683275970Scy.\" This library is available from http://www.openssl.org/ 684275970Scy.\" and can be installed using the procedures outlined 685275970Scy.\" in the Building and Installing the Distribution page. 686275970Scy.\" Once installed, 687275970Scy.\" the configure and build 688275970Scy.\" process automatically detects the library and links 689275970Scy.\" the library routines required. 690275970Scy.sp \n(Ppu 691275970Scy.ne 2 692275970Scy 693275970ScyThe Autokey protocol has several modes of operation 694275970Scycorresponding to the various NTP modes supported. 695275970ScyMost modes use a special cookie which can be 696275970Scycomputed independently by the client and server, 697275970Scybut encrypted in transmission. 698275970ScyAll modes use in addition a variant of the S-KEY scheme, 699275970Scyin which a pseudo-random key list is generated and used 700275970Scyin reverse order. 701275970ScyThese schemes are described along with an executive summary, 702275970Scycurrent status, briefing slides and reading list on the 703275970Scy\fIAutonomous\f[] \fIAuthentication\f[] 704275970Scypage. 705275970Scy.sp \n(Ppu 706275970Scy.ne 2 707275970Scy 708275970ScyThe specific cryptographic environment used by Autokey servers 709275970Scyand clients is determined by a set of files 710275970Scyand soft links generated by the 711285169Scy\fCntp-keygen\f[]\fR(1ntpkeygenmdoc)\f[] 712275970Scyprogram. 713275970ScyThis includes a required host key file, 714275970Scyrequired certificate file and optional sign key file, 715275970Scyleapsecond file and identity scheme files. 716275970ScyThe 717275970Scydigest/signature scheme is specified in the X.509 certificate 718275970Scyalong with the matching sign key. 719275970ScyThere are several schemes 720275970Scyavailable in the OpenSSL software library, each identified 721275970Scyby a specific string such as 722275970Scy\f\*[B-Font]md5WithRSAEncryption\f[], 723275970Scywhich stands for the MD5 message digest with RSA 724275970Scyencryption scheme. 725275970ScyThe current NTP distribution supports 726275970Scyall the schemes in the OpenSSL library, including 727275970Scythose based on RSA and DSA digital signatures. 728275970Scy.sp \n(Ppu 729275970Scy.ne 2 730275970Scy 731275970ScyNTP secure groups can be used to define cryptographic compartments 732275970Scyand security hierarchies. 733275970ScyIt is important that every host 734275970Scyin the group be able to construct a certificate trail to one 735275970Scyor more trusted hosts in the same group. 736275970ScyEach group 737275970Scyhost runs the Autokey protocol to obtain the certificates 738275970Scyfor all hosts along the trail to one or more trusted hosts. 739275970ScyThis requires the configuration file in all hosts to be 740275970Scyengineered so that, even under anticipated failure conditions, 741275970Scythe NTP subnet will form such that every group host can find 742275970Scya trail to at least one trusted host. 743275970Scy.SS Naming and Addressing 744275970ScyIt is important to note that Autokey does not use DNS to 745275970Scyresolve addresses, since DNS can't be completely trusted 746275970Scyuntil the name servers have synchronized clocks. 747275970ScyThe cryptographic name used by Autokey to bind the host identity 748275970Scycredentials and cryptographic values must be independent 749275970Scyof interface, network and any other naming convention. 750275970ScyThe name appears in the host certificate in either or both 751275970Scythe subject and issuer fields, so protection against 752275970ScyDNS compromise is essential. 753275970Scy.sp \n(Ppu 754275970Scy.ne 2 755275970Scy 756275970ScyBy convention, the name of an Autokey host is the name returned 757275970Scyby the Unix 758285169Scy\fCgethostname\f[]\fR(2)\f[] 759275970Scysystem call or equivalent in other systems. 760275970ScyBy the system design 761275970Scymodel, there are no provisions to allow alternate names or aliases. 762275970ScyHowever, this is not to say that DNS aliases, different names 763275970Scyfor each interface, etc., are constrained in any way. 764275970Scy.sp \n(Ppu 765275970Scy.ne 2 766275970Scy 767275970ScyIt is also important to note that Autokey verifies authenticity 768275970Scyusing the host name, network address and public keys, 769275970Scyall of which are bound together by the protocol specifically 770275970Scyto deflect masquerade attacks. 771275970ScyFor this reason Autokey 772298695Sdelphijincludes the source and destination IP addresses in message digest 773275970Scycomputations and so the same addresses must be available 774275970Scyat both the server and client. 775275970ScyFor this reason operation 776275970Scywith network address translation schemes is not possible. 777275970ScyThis reflects the intended robust security model where government 778275970Scyand corporate NTP servers are operated outside firewall perimeters. 779275970Scy.SS Operation 780275970ScyA specific combination of authentication scheme (none, 781275970Scysymmetric key, public key) and identity scheme is called 782275970Scya cryptotype, although not all combinations are compatible. 783275970ScyThere may be management configurations where the clients, 784275970Scyservers and peers may not all support the same cryptotypes. 785275970ScyA secure NTPv4 subnet can be configured in many ways while 786275970Scykeeping in mind the principles explained above and 787275970Scyin this section. 788275970ScyNote however that some cryptotype 789275970Scycombinations may successfully interoperate with each other, 790275970Scybut may not represent good security practice. 791275970Scy.sp \n(Ppu 792275970Scy.ne 2 793275970Scy 794275970ScyThe cryptotype of an association is determined at the time 795275970Scyof mobilization, either at configuration time or some time 796275970Scylater when a message of appropriate cryptotype arrives. 797275970ScyWhen mobilized by a 798275970Scy\f\*[B-Font]server\f[] 799275970Scyor 800275970Scy\f\*[B-Font]peer\f[] 801275970Scyconfiguration command and no 802275970Scy\f\*[B-Font]key\f[] 803275970Scyor 804275970Scy\f\*[B-Font]autokey\f[] 805275970Scysubcommands are present, the association is not 806275970Scyauthenticated; if the 807275970Scy\f\*[B-Font]key\f[] 808275970Scysubcommand is present, the association is authenticated 809275970Scyusing the symmetric key ID specified; if the 810275970Scy\f\*[B-Font]autokey\f[] 811275970Scysubcommand is present, the association is authenticated 812275970Scyusing Autokey. 813275970Scy.sp \n(Ppu 814275970Scy.ne 2 815275970Scy 816275970ScyWhen multiple identity schemes are supported in the Autokey 817275970Scyprotocol, the first message exchange determines which one is used. 818275970ScyThe client request message contains bits corresponding 819275970Scyto which schemes it has available. 820275970ScyThe server response message 821275970Scycontains bits corresponding to which schemes it has available. 822275970ScyBoth server and client match the received bits with their own 823275970Scyand select a common scheme. 824275970Scy.sp \n(Ppu 825275970Scy.ne 2 826275970Scy 827275970ScyFollowing the principle that time is a public value, 828275970Scya server responds to any client packet that matches 829275970Scyits cryptotype capabilities. 830275970ScyThus, a server receiving 831275970Scyan unauthenticated packet will respond with an unauthenticated 832275970Scypacket, while the same server receiving a packet of a cryptotype 833275970Scyit supports will respond with packets of that cryptotype. 834275970ScyHowever, unconfigured broadcast or manycast client 835275970Scyassociations or symmetric passive associations will not be 836275970Scymobilized unless the server supports a cryptotype compatible 837275970Scywith the first packet received. 838275970ScyBy default, unauthenticated associations will not be mobilized 839275970Scyunless overridden in a decidedly dangerous way. 840275970Scy.sp \n(Ppu 841275970Scy.ne 2 842275970Scy 843275970ScySome examples may help to reduce confusion. 844275970ScyClient Alice has no specific cryptotype selected. 845275970ScyServer Bob has both a symmetric key file and minimal Autokey files. 846275970ScyAlice's unauthenticated messages arrive at Bob, who replies with 847275970Scyunauthenticated messages. 848275970ScyCathy has a copy of Bob's symmetric 849275970Scykey file and has selected key ID 4 in messages to Bob. 850275970ScyBob verifies the message with his key ID 4. 851275970ScyIf it's the 852275970Scysame key and the message is verified, Bob sends Cathy a reply 853275970Scyauthenticated with that key. 854275970ScyIf verification fails, 855275970ScyBob sends Cathy a thing called a crypto-NAK, which tells her 856275970Scysomething broke. 857275970ScyShe can see the evidence using the 858285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 859275970Scyprogram. 860275970Scy.sp \n(Ppu 861275970Scy.ne 2 862275970Scy 863275970ScyDenise has rolled her own host key and certificate. 864275970ScyShe also uses one of the identity schemes as Bob. 865275970ScyShe sends the first Autokey message to Bob and they 866275970Scyboth dance the protocol authentication and identity steps. 867275970ScyIf all comes out okay, Denise and Bob continue as described above. 868275970Scy.sp \n(Ppu 869275970Scy.ne 2 870275970Scy 871275970ScyIt should be clear from the above that Bob can support 872275970Scyall the girls at the same time, as long as he has compatible 873275970Scyauthentication and identity credentials. 874275970ScyNow, Bob can act just like the girls in his own choice of servers; 875275970Scyhe can run multiple configured associations with multiple different 876275970Scyservers (or the same server, although that might not be useful). 877275970ScyBut, wise security policy might preclude some cryptotype 878275970Scycombinations; for instance, running an identity scheme 879275970Scywith one server and no authentication with another might not be wise. 880275970Scy.SS Key Management 881275970ScyThe cryptographic values used by the Autokey protocol are 882275970Scyincorporated as a set of files generated by the 883285169Scy\fCntp-keygen\f[]\fR(1ntpkeygenmdoc)\f[] 884275970Scyutility program, including symmetric key, host key and 885275970Scypublic certificate files, as well as sign key, identity parameters 886275970Scyand leapseconds files. 887275970ScyAlternatively, host and sign keys and 888275970Scycertificate files can be generated by the OpenSSL utilities 889275970Scyand certificates can be imported from public certificate 890275970Scyauthorities. 891275970ScyNote that symmetric keys are necessary for the 892285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 893275970Scyand 894285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 895275970Scyutility programs. 896275970ScyThe remaining files are necessary only for the 897275970ScyAutokey protocol. 898275970Scy.sp \n(Ppu 899275970Scy.ne 2 900275970Scy 901275970ScyCertificates imported from OpenSSL or public certificate 902275970Scyauthorities have certian limitations. 903275970ScyThe certificate should be in ASN.1 syntax, X.509 Version 3 904275970Scyformat and encoded in PEM, which is the same format 905275970Scyused by OpenSSL. 906275970ScyThe overall length of the certificate encoded 907275970Scyin ASN.1 must not exceed 1024 bytes. 908275970ScyThe subject distinguished 909275970Scyname field (CN) is the fully qualified name of the host 910275970Scyon which it is used; the remaining subject fields are ignored. 911275970ScyThe certificate extension fields must not contain either 912275970Scya subject key identifier or a issuer key identifier field; 913275970Scyhowever, an extended key usage field for a trusted host must 914275970Scycontain the value 915275970Scy\f\*[B-Font]trustRoot\f[];. 916275970ScyOther extension fields are ignored. 917275970Scy.SS Authentication Commands 918275970Scy.TP 7 919275970Scy.NOP \f\*[B-Font]autokey\f[] [\f\*[I-Font]logsec\f[]] 920275970ScySpecifies the interval between regenerations of the session key 921275970Scylist used with the Autokey protocol. 922275970ScyNote that the size of the key 923275970Scylist for each association depends on this interval and the current 924275970Scypoll interval. 925275970ScyThe default value is 12 (4096 s or about 1.1 hours). 926275970ScyFor poll intervals above the specified interval, a session key list 927275970Scywith a single entry will be regenerated for every message 928275970Scysent. 929275970Scy.TP 7 930275970Scy.NOP \f\*[B-Font]controlkey\f[] \f\*[I-Font]key\f[] 931275970ScySpecifies the key identifier to use with the 932285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 933275970Scyutility, which uses the standard 934275970Scyprotocol defined in RFC-1305. 935275970ScyThe 936275970Scy\f\*[I-Font]key\f[] 937275970Scyargument is 938275970Scythe key identifier for a trusted key, where the value can be in the 939338530Sdelphijrange 1 to 65,535, inclusive. 940275970Scy.TP 7 941275970Scy.NOP \f\*[B-Font]crypto\f[] [\f\*[B-Font]cert\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]leap\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]randfile\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]host\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]sign\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]gq\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]gqpar\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]iffpar\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]mvpar\f[] \f\*[I-Font]file\f[]] [\f\*[B-Font]pw\f[] \f\*[I-Font]password\f[]] 942275970ScyThis command requires the OpenSSL library. 943275970ScyIt activates public key 944275970Scycryptography, selects the message digest and signature 945275970Scyencryption scheme and loads the required private and public 946275970Scyvalues described above. 947275970ScyIf one or more files are left unspecified, 948275970Scythe default names are used as described above. 949275970ScyUnless the complete path and name of the file are specified, the 950275970Scylocation of a file is relative to the keys directory specified 951275970Scyin the 952275970Scy\f\*[B-Font]keysdir\f[] 953275970Scycommand or default 954275970Scy\fI/usr/local/etc\f[]. 955275970ScyFollowing are the subcommands: 956275970Scy.RS 957275970Scy.TP 7 958275970Scy.NOP \f\*[B-Font]cert\f[] \f\*[I-Font]file\f[] 959275970ScySpecifies the location of the required host public certificate file. 960275970ScyThis overrides the link 961275970Scy\fIntpkey_cert_\f[]\f\*[I-Font]hostname\f[] 962275970Scyin the keys directory. 963275970Scy.TP 7 964275970Scy.NOP \f\*[B-Font]gqpar\f[] \f\*[I-Font]file\f[] 965275970ScySpecifies the location of the optional GQ parameters file. 966275970ScyThis 967275970Scyoverrides the link 968275970Scy\fIntpkey_gq_\f[]\f\*[I-Font]hostname\f[] 969275970Scyin the keys directory. 970275970Scy.TP 7 971275970Scy.NOP \f\*[B-Font]host\f[] \f\*[I-Font]file\f[] 972275970ScySpecifies the location of the required host key file. 973275970ScyThis overrides 974275970Scythe link 975275970Scy\fIntpkey_key_\f[]\f\*[I-Font]hostname\f[] 976275970Scyin the keys directory. 977275970Scy.TP 7 978275970Scy.NOP \f\*[B-Font]iffpar\f[] \f\*[I-Font]file\f[] 979298695SdelphijSpecifies the location of the optional IFF parameters file. 980298695SdelphijThis overrides the link 981275970Scy\fIntpkey_iff_\f[]\f\*[I-Font]hostname\f[] 982275970Scyin the keys directory. 983275970Scy.TP 7 984275970Scy.NOP \f\*[B-Font]leap\f[] \f\*[I-Font]file\f[] 985275970ScySpecifies the location of the optional leapsecond file. 986275970ScyThis overrides the link 987275970Scy\fIntpkey_leap\f[] 988275970Scyin the keys directory. 989275970Scy.TP 7 990275970Scy.NOP \f\*[B-Font]mvpar\f[] \f\*[I-Font]file\f[] 991275970ScySpecifies the location of the optional MV parameters file. 992298695SdelphijThis overrides the link 993275970Scy\fIntpkey_mv_\f[]\f\*[I-Font]hostname\f[] 994275970Scyin the keys directory. 995275970Scy.TP 7 996275970Scy.NOP \f\*[B-Font]pw\f[] \f\*[I-Font]password\f[] 997275970ScySpecifies the password to decrypt files containing private keys and 998275970Scyidentity parameters. 999275970ScyThis is required only if these files have been 1000275970Scyencrypted. 1001275970Scy.TP 7 1002275970Scy.NOP \f\*[B-Font]randfile\f[] \f\*[I-Font]file\f[] 1003275970ScySpecifies the location of the random seed file used by the OpenSSL 1004275970Scylibrary. 1005275970ScyThe defaults are described in the main text above. 1006275970Scy.TP 7 1007275970Scy.NOP \f\*[B-Font]sign\f[] \f\*[I-Font]file\f[] 1008275970ScySpecifies the location of the optional sign key file. 1009275970ScyThis overrides 1010275970Scythe link 1011275970Scy\fIntpkey_sign_\f[]\f\*[I-Font]hostname\f[] 1012275970Scyin the keys directory. 1013275970ScyIf this file is 1014275970Scynot found, the host key is also the sign key. 1015275970Scy.RE 1016275970Scy.TP 7 1017275970Scy.NOP \f\*[B-Font]keys\f[] \f\*[I-Font]keyfile\f[] 1018275970ScySpecifies the complete path and location of the MD5 key file 1019275970Scycontaining the keys and key identifiers used by 1020285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[], 1021285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1022275970Scyand 1023285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1024275970Scywhen operating with symmetric key cryptography. 1025275970ScyThis is the same operation as the 1026275970Scy\f\*[B-Font]\-k\f[] 1027275970Scycommand line option. 1028275970Scy.TP 7 1029275970Scy.NOP \f\*[B-Font]keysdir\f[] \f\*[I-Font]path\f[] 1030275970ScyThis command specifies the default directory path for 1031275970Scycryptographic keys, parameters and certificates. 1032275970ScyThe default is 1033275970Scy\fI/usr/local/etc/\f[]. 1034275970Scy.TP 7 1035275970Scy.NOP \f\*[B-Font]requestkey\f[] \f\*[I-Font]key\f[] 1036275970ScySpecifies the key identifier to use with the 1037285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1038275970Scyutility program, which uses a 1039275970Scyproprietary protocol specific to this implementation of 1040285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[]. 1041275970ScyThe 1042275970Scy\f\*[I-Font]key\f[] 1043275970Scyargument is a key identifier 1044275970Scyfor the trusted key, where the value can be in the range 1 to 1045338530Sdelphij65,535, inclusive. 1046275970Scy.TP 7 1047275970Scy.NOP \f\*[B-Font]revoke\f[] \f\*[I-Font]logsec\f[] 1048275970ScySpecifies the interval between re-randomization of certain 1049275970Scycryptographic values used by the Autokey scheme, as a power of 2 in 1050275970Scyseconds. 1051275970ScyThese values need to be updated frequently in order to 1052275970Scydeflect brute-force attacks on the algorithms of the scheme; 1053275970Scyhowever, updating some values is a relatively expensive operation. 1054275970ScyThe default interval is 16 (65,536 s or about 18 hours). 1055275970ScyFor poll 1056275970Scyintervals above the specified interval, the values will be updated 1057275970Scyfor every message sent. 1058275970Scy.TP 7 1059275970Scy.NOP \f\*[B-Font]trustedkey\f[] \f\*[I-Font]key\f[] \f\*[I-Font]...\f[] 1060275970ScySpecifies the key identifiers which are trusted for the 1061275970Scypurposes of authenticating peers with symmetric key cryptography, 1062275970Scyas well as keys used by the 1063285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1064275970Scyand 1065285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1066275970Scyprograms. 1067275970ScyThe authentication procedures require that both the local 1068275970Scyand remote servers share the same key and key identifier for this 1069275970Scypurpose, although different keys can be used with different 1070275970Scyservers. 1071275970ScyThe 1072275970Scy\f\*[I-Font]key\f[] 1073275970Scyarguments are 32-bit unsigned 1074338530Sdelphijintegers with values from 1 to 65,535. 1075275970Scy.PP 1076275970Scy.SS Error Codes 1077275970ScyThe following error codes are reported via the NTP control 1078275970Scyand monitoring protocol trap mechanism. 1079275970Scy.TP 7 1080275970Scy.NOP 101 1081275970Scy(bad field format or length) 1082275970ScyThe packet has invalid version, length or format. 1083275970Scy.TP 7 1084275970Scy.NOP 102 1085275970Scy(bad timestamp) 1086275970ScyThe packet timestamp is the same or older than the most recent received. 1087275970ScyThis could be due to a replay or a server clock time step. 1088275970Scy.TP 7 1089275970Scy.NOP 103 1090275970Scy(bad filestamp) 1091275970ScyThe packet filestamp is the same or older than the most recent received. 1092275970ScyThis could be due to a replay or a key file generation error. 1093275970Scy.TP 7 1094275970Scy.NOP 104 1095275970Scy(bad or missing public key) 1096275970ScyThe public key is missing, has incorrect format or is an unsupported type. 1097275970Scy.TP 7 1098275970Scy.NOP 105 1099275970Scy(unsupported digest type) 1100275970ScyThe server requires an unsupported digest/signature scheme. 1101275970Scy.TP 7 1102275970Scy.NOP 106 1103275970Scy(mismatched digest types) 1104275970ScyNot used. 1105275970Scy.TP 7 1106275970Scy.NOP 107 1107275970Scy(bad signature length) 1108275970ScyThe signature length does not match the current public key. 1109275970Scy.TP 7 1110275970Scy.NOP 108 1111275970Scy(signature not verified) 1112275970ScyThe message fails the signature check. 1113275970ScyIt could be bogus or signed by a 1114275970Scydifferent private key. 1115275970Scy.TP 7 1116275970Scy.NOP 109 1117275970Scy(certificate not verified) 1118275970ScyThe certificate is invalid or signed with the wrong key. 1119275970Scy.TP 7 1120275970Scy.NOP 110 1121275970Scy(certificate not verified) 1122275970ScyThe certificate is not yet valid or has expired or the signature could not 1123275970Scybe verified. 1124275970Scy.TP 7 1125275970Scy.NOP 111 1126275970Scy(bad or missing cookie) 1127275970ScyThe cookie is missing, corrupted or bogus. 1128275970Scy.TP 7 1129275970Scy.NOP 112 1130275970Scy(bad or missing leapseconds table) 1131275970ScyThe leapseconds table is missing, corrupted or bogus. 1132275970Scy.TP 7 1133275970Scy.NOP 113 1134275970Scy(bad or missing certificate) 1135275970ScyThe certificate is missing, corrupted or bogus. 1136275970Scy.TP 7 1137275970Scy.NOP 114 1138275970Scy(bad or missing identity) 1139275970ScyThe identity key is missing, corrupt or bogus. 1140275970Scy.PP 1141275970Scy.SH Monitoring Support 1142285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1143275970Scyincludes a comprehensive monitoring facility suitable 1144275970Scyfor continuous, long term recording of server and client 1145275970Scytimekeeping performance. 1146275970ScySee the 1147275970Scy\f\*[B-Font]statistics\f[] 1148275970Scycommand below 1149275970Scyfor a listing and example of each type of statistics currently 1150275970Scysupported. 1151275970ScyStatistic files are managed using file generation sets 1152275970Scyand scripts in the 1153275970Scy\fI./scripts\f[] 1154298695Sdelphijdirectory of the source code distribution. 1155275970ScyUsing 1156275970Scythese facilities and 1157275970ScyUNIX 1158285169Scy\fCcron\f[]\fR(8)\f[] 1159275970Scyjobs, the data can be 1160275970Scyautomatically summarized and archived for retrospective analysis. 1161275970Scy.SS Monitoring Commands 1162275970Scy.TP 7 1163275970Scy.NOP \f\*[B-Font]statistics\f[] \f\*[I-Font]name\f[] \f\*[I-Font]...\f[] 1164275970ScyEnables writing of statistics records. 1165275970ScyCurrently, eight kinds of 1166275970Scy\f\*[I-Font]name\f[] 1167275970Scystatistics are supported. 1168275970Scy.RS 1169275970Scy.TP 7 1170275970Scy.NOP \f\*[B-Font]clockstats\f[] 1171275970ScyEnables recording of clock driver statistics information. 1172275970ScyEach update 1173275970Scyreceived from a clock driver appends a line of the following form to 1174275970Scythe file generation set named 1175275970Scy\f\*[B-Font]clockstats\f[]: 1176275970Scy.br 1177275970Scy.in +4 1178275970Scy.nf 1179275970Scy49213 525.624 127.127.4.1 93 226 00:08:29.606 D 1180275970Scy.in -4 1181275970Scy.fi 1182275970Scy.sp \n(Ppu 1183275970Scy.ne 2 1184275970Scy 1185275970ScyThe first two fields show the date (Modified Julian Day) and time 1186275970Scy(seconds and fraction past UTC midnight). 1187275970ScyThe next field shows the 1188275970Scyclock address in dotted-quad notation. 1189275970ScyThe final field shows the last 1190275970Scytimecode received from the clock in decoded ASCII format, where 1191275970Scymeaningful. 1192275970ScyIn some clock drivers a good deal of additional information 1193275970Scycan be gathered and displayed as well. 1194275970ScySee information specific to each 1195275970Scyclock for further details. 1196275970Scy.TP 7 1197275970Scy.NOP \f\*[B-Font]cryptostats\f[] 1198275970ScyThis option requires the OpenSSL cryptographic software library. 1199275970ScyIt 1200275970Scyenables recording of cryptographic public key protocol information. 1201275970ScyEach message received by the protocol module appends a line of the 1202275970Scyfollowing form to the file generation set named 1203275970Scy\f\*[B-Font]cryptostats\f[]: 1204275970Scy.br 1205275970Scy.in +4 1206275970Scy.nf 1207275970Scy49213 525.624 127.127.4.1 message 1208275970Scy.in -4 1209275970Scy.fi 1210275970Scy.sp \n(Ppu 1211275970Scy.ne 2 1212275970Scy 1213275970ScyThe first two fields show the date (Modified Julian Day) and time 1214275970Scy(seconds and fraction past UTC midnight). 1215275970ScyThe next field shows the peer 1216275970Scyaddress in dotted-quad notation, The final message field includes the 1217275970Scymessage type and certain ancillary information. 1218275970ScySee the 1219275970Scy\fIAuthentication\f[] \fIOptions\f[] 1220275970Scysection for further information. 1221275970Scy.TP 7 1222275970Scy.NOP \f\*[B-Font]loopstats\f[] 1223275970ScyEnables recording of loop filter statistics information. 1224275970ScyEach 1225275970Scyupdate of the local clock outputs a line of the following form to 1226275970Scythe file generation set named 1227275970Scy\f\*[B-Font]loopstats\f[]: 1228275970Scy.br 1229275970Scy.in +4 1230275970Scy.nf 1231275970Scy50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 1232275970Scy.in -4 1233275970Scy.fi 1234275970Scy.sp \n(Ppu 1235275970Scy.ne 2 1236275970Scy 1237275970ScyThe first two fields show the date (Modified Julian Day) and 1238275970Scytime (seconds and fraction past UTC midnight). 1239275970ScyThe next five fields 1240275970Scyshow time offset (seconds), frequency offset (parts per million \- 1241275970ScyPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 1242275970Scydiscipline time constant. 1243275970Scy.TP 7 1244275970Scy.NOP \f\*[B-Font]peerstats\f[] 1245275970ScyEnables recording of peer statistics information. 1246275970ScyThis includes 1247275970Scystatistics records of all peers of a NTP server and of special 1248275970Scysignals, where present and configured. 1249275970ScyEach valid update appends a 1250275970Scyline of the following form to the current element of a file 1251275970Scygeneration set named 1252275970Scy\f\*[B-Font]peerstats\f[]: 1253275970Scy.br 1254275970Scy.in +4 1255275970Scy.nf 1256275970Scy48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674 1257275970Scy.in -4 1258275970Scy.fi 1259275970Scy.sp \n(Ppu 1260275970Scy.ne 2 1261275970Scy 1262275970ScyThe first two fields show the date (Modified Julian Day) and 1263275970Scytime (seconds and fraction past UTC midnight). 1264275970ScyThe next two fields 1265275970Scyshow the peer address in dotted-quad notation and status, 1266275970Scyrespectively. 1267275970ScyThe status field is encoded in hex in the format 1268275970Scydescribed in Appendix A of the NTP specification RFC 1305. 1269275970ScyThe final four fields show the offset, 1270275970Scydelay, dispersion and RMS jitter, all in seconds. 1271275970Scy.TP 7 1272275970Scy.NOP \f\*[B-Font]rawstats\f[] 1273275970ScyEnables recording of raw-timestamp statistics information. 1274275970ScyThis 1275275970Scyincludes statistics records of all peers of a NTP server and of 1276275970Scyspecial signals, where present and configured. 1277275970ScyEach NTP message 1278275970Scyreceived from a peer or clock driver appends a line of the 1279275970Scyfollowing form to the file generation set named 1280275970Scy\f\*[B-Font]rawstats\f[]: 1281275970Scy.br 1282275970Scy.in +4 1283275970Scy.nf 1284275970Scy50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 1285275970Scy.in -4 1286275970Scy.fi 1287275970Scy.sp \n(Ppu 1288275970Scy.ne 2 1289275970Scy 1290275970ScyThe first two fields show the date (Modified Julian Day) and 1291275970Scytime (seconds and fraction past UTC midnight). 1292275970ScyThe next two fields 1293275970Scyshow the remote peer or clock address followed by the local address 1294275970Scyin dotted-quad notation. 1295275970ScyThe final four fields show the originate, 1296275970Scyreceive, transmit and final NTP timestamps in order. 1297275970ScyThe timestamp 1298275970Scyvalues are as received and before processing by the various data 1299275970Scysmoothing and mitigation algorithms. 1300275970Scy.TP 7 1301275970Scy.NOP \f\*[B-Font]sysstats\f[] 1302275970ScyEnables recording of ntpd statistics counters on a periodic basis. 1303275970ScyEach 1304275970Scyhour a line of the following form is appended to the file generation 1305275970Scyset named 1306275970Scy\f\*[B-Font]sysstats\f[]: 1307275970Scy.br 1308275970Scy.in +4 1309275970Scy.nf 1310275970Scy50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1311275970Scy.in -4 1312275970Scy.fi 1313275970Scy.sp \n(Ppu 1314275970Scy.ne 2 1315275970Scy 1316275970ScyThe first two fields show the date (Modified Julian Day) and time 1317275970Scy(seconds and fraction past UTC midnight). 1318275970ScyThe remaining ten fields show 1319275970Scythe statistics counter values accumulated since the last generated 1320275970Scyline. 1321275970Scy.RS 1322275970Scy.TP 7 1323275970Scy.NOP Time since restart \f\*[B-Font]36000\f[] 1324275970ScyTime in hours since the system was last rebooted. 1325275970Scy.TP 7 1326275970Scy.NOP Packets received \f\*[B-Font]81965\f[] 1327275970ScyTotal number of packets received. 1328275970Scy.TP 7 1329275970Scy.NOP Packets processed \f\*[B-Font]0\f[] 1330275970ScyNumber of packets received in response to previous packets sent 1331275970Scy.TP 7 1332275970Scy.NOP Current version \f\*[B-Font]9546\f[] 1333275970ScyNumber of packets matching the current NTP version. 1334275970Scy.TP 7 1335275970Scy.NOP Previous version \f\*[B-Font]56\f[] 1336275970ScyNumber of packets matching the previous NTP version. 1337275970Scy.TP 7 1338275970Scy.NOP Bad version \f\*[B-Font]71793\f[] 1339275970ScyNumber of packets matching neither NTP version. 1340275970Scy.TP 7 1341275970Scy.NOP Access denied \f\*[B-Font]512\f[] 1342275970ScyNumber of packets denied access for any reason. 1343275970Scy.TP 7 1344275970Scy.NOP Bad length or format \f\*[B-Font]540\f[] 1345275970ScyNumber of packets with invalid length, format or port number. 1346275970Scy.TP 7 1347275970Scy.NOP Bad authentication \f\*[B-Font]10\f[] 1348275970ScyNumber of packets not verified as authentic. 1349275970Scy.TP 7 1350275970Scy.NOP Rate exceeded \f\*[B-Font]147\f[] 1351275970ScyNumber of packets discarded due to rate limitation. 1352275970Scy.RE 1353275970Scy.TP 7 1354275970Scy.NOP \f\*[B-Font]statsdir\f[] \f\*[I-Font]directory_path\f[] 1355275970ScyIndicates the full path of a directory where statistics files 1356275970Scyshould be created (see below). 1357275970ScyThis keyword allows 1358275970Scythe (otherwise constant) 1359275970Scy\f\*[B-Font]filegen\f[] 1360275970Scyfilename prefix to be modified for file generation sets, which 1361275970Scyis useful for handling statistics logs. 1362275970Scy.TP 7 1363275970Scy.NOP \f\*[B-Font]filegen\f[] \f\*[I-Font]name\f[] [\f\*[B-Font]file\f[] \f\*[I-Font]filename\f[]] [\f\*[B-Font]type\f[] \f\*[I-Font]typename\f[]] [\f\*[B-Font]link\f[] | \f\*[B-Font]nolink\f[]] [\f\*[B-Font]enable\f[] | \f\*[B-Font]disable\f[]] 1364275970ScyConfigures setting of generation file set name. 1365275970ScyGeneration 1366275970Scyfile sets provide a means for handling files that are 1367275970Scycontinuously growing during the lifetime of a server. 1368275970ScyServer statistics are a typical example for such files. 1369275970ScyGeneration file sets provide access to a set of files used 1370275970Scyto store the actual data. 1371275970ScyAt any time at most one element 1372275970Scyof the set is being written to. 1373275970ScyThe type given specifies 1374275970Scywhen and how data will be directed to a new element of the set. 1375275970ScyThis way, information stored in elements of a file set 1376275970Scythat are currently unused are available for administrational 1377275970Scyoperations without the risk of disturbing the operation of ntpd. 1378275970Scy(Most important: they can be removed to free space for new data 1379275970Scyproduced.) 1380275970Scy.sp \n(Ppu 1381275970Scy.ne 2 1382275970Scy 1383275970ScyNote that this command can be sent from the 1384285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1385275970Scyprogram running at a remote location. 1386275970Scy.RS 1387275970Scy.TP 7 1388275970Scy.NOP \f\*[B-Font]name\f[] 1389275970ScyThis is the type of the statistics records, as shown in the 1390275970Scy\f\*[B-Font]statistics\f[] 1391275970Scycommand. 1392275970Scy.TP 7 1393275970Scy.NOP \f\*[B-Font]file\f[] \f\*[I-Font]filename\f[] 1394275970ScyThis is the file name for the statistics records. 1395275970ScyFilenames of set 1396275970Scymembers are built from three concatenated elements 1397275970Scy\f\*[B-Font]prefix\f[], 1398275970Scy\f\*[B-Font]filename\f[] 1399275970Scyand 1400275970Scy\f\*[B-Font]suffix\f[]: 1401275970Scy.RS 1402275970Scy.TP 7 1403275970Scy.NOP \f\*[B-Font]prefix\f[] 1404275970ScyThis is a constant filename path. 1405275970ScyIt is not subject to 1406275970Scymodifications via the 1407275970Scy\f\*[I-Font]filegen\f[] 1408275970Scyoption. 1409275970ScyIt is defined by the 1410275970Scyserver, usually specified as a compile-time constant. 1411275970ScyIt may, 1412275970Scyhowever, be configurable for individual file generation sets 1413275970Scyvia other commands. 1414275970ScyFor example, the prefix used with 1415275970Scy\f\*[I-Font]loopstats\f[] 1416275970Scyand 1417275970Scy\f\*[I-Font]peerstats\f[] 1418275970Scygeneration can be configured using the 1419275970Scy\f\*[I-Font]statsdir\f[] 1420275970Scyoption explained above. 1421275970Scy.TP 7 1422275970Scy.NOP \f\*[B-Font]filename\f[] 1423275970ScyThis string is directly concatenated to the prefix mentioned 1424275970Scyabove (no intervening 1425275970Scy\[oq]/\[cq]). 1426275970ScyThis can be modified using 1427275970Scythe file argument to the 1428275970Scy\f\*[I-Font]filegen\f[] 1429275970Scystatement. 1430275970ScyNo 1431275970Scy\fI..\f[] 1432275970Scyelements are 1433275970Scyallowed in this component to prevent filenames referring to 1434275970Scyparts outside the filesystem hierarchy denoted by 1435275970Scy\f\*[I-Font]prefix\f[]. 1436275970Scy.TP 7 1437275970Scy.NOP \f\*[B-Font]suffix\f[] 1438275970ScyThis part is reflects individual elements of a file set. 1439275970ScyIt is 1440275970Scygenerated according to the type of a file set. 1441275970Scy.RE 1442275970Scy.TP 7 1443275970Scy.NOP \f\*[B-Font]type\f[] \f\*[I-Font]typename\f[] 1444275970ScyA file generation set is characterized by its type. 1445275970ScyThe following 1446275970Scytypes are supported: 1447275970Scy.RS 1448275970Scy.TP 7 1449275970Scy.NOP \f\*[B-Font]none\f[] 1450275970ScyThe file set is actually a single plain file. 1451275970Scy.TP 7 1452275970Scy.NOP \f\*[B-Font]pid\f[] 1453275970ScyOne element of file set is used per incarnation of a ntpd 1454275970Scyserver. 1455275970ScyThis type does not perform any changes to file set 1456275970Scymembers during runtime, however it provides an easy way of 1457275970Scyseparating files belonging to different 1458285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1459275970Scyserver incarnations. 1460275970ScyThe set member filename is built by appending a 1461275970Scy\[oq]\&.\[cq] 1462275970Scyto concatenated 1463275970Scy\f\*[I-Font]prefix\f[] 1464275970Scyand 1465275970Scy\f\*[I-Font]filename\f[] 1466275970Scystrings, and 1467275970Scyappending the decimal representation of the process ID of the 1468285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1469275970Scyserver process. 1470275970Scy.TP 7 1471275970Scy.NOP \f\*[B-Font]day\f[] 1472275970ScyOne file generation set element is created per day. 1473275970ScyA day is 1474275970Scydefined as the period between 00:00 and 24:00 UTC. 1475275970ScyThe file set 1476275970Scymember suffix consists of a 1477275970Scy\[oq]\&.\[cq] 1478275970Scyand a day specification in 1479275970Scythe form 1480275970Scy\f\*[B-Font]YYYYMMdd\f[]. 1481275970Scy\f\*[B-Font]YYYY\f[] 1482275970Scyis a 4-digit year number (e.g., 1992). 1483275970Scy\f\*[B-Font]MM\f[] 1484275970Scyis a two digit month number. 1485275970Scy\f\*[B-Font]dd\f[] 1486275970Scyis a two digit day number. 1487275970ScyThus, all information written at 10 December 1992 would end up 1488275970Scyin a file named 1489275970Scy\f\*[I-Font]prefix\f[] 1490275970Scy\f\*[I-Font]filename\f[].19921210. 1491275970Scy.TP 7 1492275970Scy.NOP \f\*[B-Font]week\f[] 1493275970ScyAny file set member contains data related to a certain week of 1494275970Scya year. 1495275970ScyThe term week is defined by computing day-of-year 1496275970Scymodulo 7. 1497275970ScyElements of such a file generation set are 1498275970Scydistinguished by appending the following suffix to the file set 1499275970Scyfilename base: A dot, a 4-digit year number, the letter 1500275970Scy\f\*[B-Font]W\f[], 1501275970Scyand a 2-digit week number. 1502275970ScyFor example, information from January, 1503275970Scy10th 1992 would end up in a file with suffix 1504275970Scy.NOP. \f\*[I-Font]1992W1\f[]. 1505275970Scy.TP 7 1506275970Scy.NOP \f\*[B-Font]month\f[] 1507275970ScyOne generation file set element is generated per month. 1508275970ScyThe 1509275970Scyfile name suffix consists of a dot, a 4-digit year number, and 1510275970Scya 2-digit month. 1511275970Scy.TP 7 1512275970Scy.NOP \f\*[B-Font]year\f[] 1513275970ScyOne generation file element is generated per year. 1514275970ScyThe filename 1515275970Scysuffix consists of a dot and a 4 digit year number. 1516275970Scy.TP 7 1517275970Scy.NOP \f\*[B-Font]age\f[] 1518275970ScyThis type of file generation sets changes to a new element of 1519275970Scythe file set every 24 hours of server operation. 1520275970ScyThe filename 1521275970Scysuffix consists of a dot, the letter 1522275970Scy\f\*[B-Font]a\f[], 1523275970Scyand an 8-digit number. 1524275970ScyThis number is taken to be the number of seconds the server is 1525275970Scyrunning at the start of the corresponding 24-hour period. 1526275970ScyInformation is only written to a file generation by specifying 1527275970Scy\f\*[B-Font]enable\f[]; 1528275970Scyoutput is prevented by specifying 1529275970Scy\f\*[B-Font]disable\f[]. 1530275970Scy.RE 1531275970Scy.TP 7 1532275970Scy.NOP \f\*[B-Font]link\f[] | \f\*[B-Font]nolink\f[] 1533275970ScyIt is convenient to be able to access the current element of a file 1534275970Scygeneration set by a fixed name. 1535275970ScyThis feature is enabled by 1536275970Scyspecifying 1537275970Scy\f\*[B-Font]link\f[] 1538275970Scyand disabled using 1539275970Scy\f\*[B-Font]nolink\f[]. 1540275970ScyIf link is specified, a 1541275970Scyhard link from the current file set element to a file without 1542275970Scysuffix is created. 1543275970ScyWhen there is already a file with this name and 1544275970Scythe number of links of this file is one, it is renamed appending a 1545275970Scydot, the letter 1546275970Scy\f\*[B-Font]C\f[], 1547298695Sdelphijand the pid of the 1548298695Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1549298695Sdelphijserver process. 1550275970ScyWhen the 1551275970Scynumber of links is greater than one, the file is unlinked. 1552275970ScyThis 1553275970Scyallows the current file to be accessed by a constant name. 1554275970Scy.TP 7 1555275970Scy.NOP \f\*[B-Font]enable\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]disable\f[] 1556275970ScyEnables or disables the recording function. 1557275970Scy.RE 1558275970Scy.RE 1559275970Scy.PP 1560275970Scy.SH Access Control Support 1561275970ScyThe 1562285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1563275970Scydaemon implements a general purpose address/mask based restriction 1564275970Scylist. 1565275970ScyThe list contains address/match entries sorted first 1566275970Scyby increasing address values and and then by increasing mask values. 1567275970ScyA match occurs when the bitwise AND of the mask and the packet 1568275970Scysource address is equal to the bitwise AND of the mask and 1569275970Scyaddress in the list. 1570275970ScyThe list is searched in order with the 1571275970Scylast match found defining the restriction flags associated 1572275970Scywith the entry. 1573275970ScyAdditional information and examples can be found in the 1574275970Scy"Notes on Configuring NTP and Setting up a NTP Subnet" 1575275970Scypage 1576275970Scy(available as part of the HTML documentation 1577275970Scyprovided in 1578275970Scy\fI/usr/share/doc/ntp\f[]). 1579275970Scy.sp \n(Ppu 1580275970Scy.ne 2 1581275970Scy 1582275970ScyThe restriction facility was implemented in conformance 1583275970Scywith the access policies for the original NSFnet backbone 1584275970Scytime servers. 1585275970ScyLater the facility was expanded to deflect 1586275970Scycryptographic and clogging attacks. 1587275970ScyWhile this facility may 1588275970Scybe useful for keeping unwanted or broken or malicious clients 1589275970Scyfrom congesting innocent servers, it should not be considered 1590275970Scyan alternative to the NTP authentication facilities. 1591275970ScySource address based restrictions are easily circumvented 1592275970Scyby a determined cracker. 1593275970Scy.sp \n(Ppu 1594275970Scy.ne 2 1595275970Scy 1596275970ScyClients can be denied service because they are explicitly 1597298695Sdelphijincluded in the restrict list created by the 1598298695Sdelphij\f\*[B-Font]restrict\f[] 1599298695Sdelphijcommand 1600275970Scyor implicitly as the result of cryptographic or rate limit 1601275970Scyviolations. 1602275970ScyCryptographic violations include certificate 1603275970Scyor identity verification failure; rate limit violations generally 1604275970Scyresult from defective NTP implementations that send packets 1605275970Scyat abusive rates. 1606275970ScySome violations cause denied service 1607275970Scyonly for the offending packet, others cause denied service 1608275970Scyfor a timed period and others cause the denied service for 1609298695Sdelphijan indefinite period. 1610275970ScyWhen a client or network is denied access 1611298695Sdelphijfor an indefinite period, the only way at present to remove 1612275970Scythe restrictions is by restarting the server. 1613275970Scy.SS The Kiss-of-Death Packet 1614275970ScyOrdinarily, packets denied service are simply dropped with no 1615275970Scyfurther action except incrementing statistics counters. 1616275970ScySometimes a 1617275970Scymore proactive response is needed, such as a server message that 1618275970Scyexplicitly requests the client to stop sending and leave a message 1619275970Scyfor the system operator. 1620275970ScyA special packet format has been created 1621275970Scyfor this purpose called the "kiss-of-death" (KoD) packet. 1622275970ScyKoD packets have the leap bits set unsynchronized and stratum set 1623275970Scyto zero and the reference identifier field set to a four-byte 1624275970ScyASCII code. 1625275970ScyIf the 1626275970Scy\f\*[B-Font]noserve\f[] 1627275970Scyor 1628275970Scy\f\*[B-Font]notrust\f[] 1629275970Scyflag of the matching restrict list entry is set, 1630275970Scythe code is "DENY"; if the 1631275970Scy\f\*[B-Font]limited\f[] 1632275970Scyflag is set and the rate limit 1633275970Scyis exceeded, the code is "RATE". 1634275970ScyFinally, if a cryptographic violation occurs, the code is "CRYP". 1635275970Scy.sp \n(Ppu 1636275970Scy.ne 2 1637275970Scy 1638275970ScyA client receiving a KoD performs a set of sanity checks to 1639275970Scyminimize security exposure, then updates the stratum and 1640275970Scyreference identifier peer variables, sets the access 1641275970Scydenied (TEST4) bit in the peer flash variable and sends 1642275970Scya message to the log. 1643275970ScyAs long as the TEST4 bit is set, 1644275970Scythe client will send no further packets to the server. 1645275970ScyThe only way at present to recover from this condition is 1646275970Scyto restart the protocol at both the client and server. 1647275970ScyThis 1648275970Scyhappens automatically at the client when the association times out. 1649275970ScyIt will happen at the server only if the server operator cooperates. 1650275970Scy.SS Access Control Commands 1651275970Scy.TP 7 1652275970Scy.NOP \f\*[B-Font]discard\f[] [\f\*[B-Font]average\f[] \f\*[I-Font]avg\f[]] [\f\*[B-Font]minimum\f[] \f\*[I-Font]min\f[]] [\f\*[B-Font]monitor\f[] \f\*[I-Font]prob\f[]] 1653275970ScySet the parameters of the 1654275970Scy\f\*[B-Font]limited\f[] 1655275970Scyfacility which protects the server from 1656275970Scyclient abuse. 1657275970ScyThe 1658275970Scy\f\*[B-Font]average\f[] 1659275970Scysubcommand specifies the minimum average packet 1660275970Scyspacing, while the 1661275970Scy\f\*[B-Font]minimum\f[] 1662275970Scysubcommand specifies the minimum packet spacing. 1663275970ScyPackets that violate these minima are discarded 1664275970Scyand a kiss-o'-death packet returned if enabled. 1665275970ScyThe default 1666275970Scyminimum average and minimum are 5 and 2, respectively. 1667298695SdelphijThe 1668298695Sdelphij\f\*[B-Font]monitor\f[] 1669298695Sdelphijsubcommand specifies the probability of discard 1670275970Scyfor packets that overflow the rate-control window. 1671275970Scy.TP 7 1672330106Sdelphij.NOP \f\*[B-Font]restrict\f[] \f\*[B-Font]address\f[] [\f\*[B-Font]mask\f[] \f\*[I-Font]mask\f[]] [\f\*[B-Font]ippeerlimit\f[] \f\*[I-Font]int\f[]] [\f\*[I-Font]flag\f[] \f\*[I-Font]...\f[]] 1673275970ScyThe 1674275970Scy\f\*[I-Font]address\f[] 1675275970Scyargument expressed in 1676275970Scydotted-quad form is the address of a host or network. 1677275970ScyAlternatively, the 1678275970Scy\f\*[I-Font]address\f[] 1679275970Scyargument can be a valid host DNS name. 1680275970ScyThe 1681275970Scy\f\*[I-Font]mask\f[] 1682275970Scyargument expressed in dotted-quad form defaults to 1683275970Scy\f\*[B-Font]255.255.255.255\f[], 1684275970Scymeaning that the 1685275970Scy\f\*[I-Font]address\f[] 1686275970Scyis treated as the address of an individual host. 1687275970ScyA default entry (address 1688275970Scy\f\*[B-Font]0.0.0.0\f[], 1689275970Scymask 1690275970Scy\f\*[B-Font]0.0.0.0\f[]) 1691275970Scyis always included and is always the first entry in the list. 1692275970ScyNote that text string 1693275970Scy\f\*[B-Font]default\f[], 1694275970Scywith no mask option, may 1695275970Scybe used to indicate the default entry. 1696330106SdelphijThe 1697330106Sdelphij\f\*[B-Font]ippeerlimit\f[] 1698330106Sdelphijdirective limits the number of peer requests for each IP to 1699330106Sdelphij\f\*[I-Font]int\f[], 1700330106Sdelphijwhere a value of \-1 means "unlimited", the current default. 1701330106SdelphijA value of 0 means "none". 1702330106SdelphijThere would usually be at most 1 peering request per IP, 1703330106Sdelphijbut if the remote peering requests are behind a proxy 1704330106Sdelphijthere could well be more than 1 per IP. 1705275970ScyIn the current implementation, 1706275970Scy\f\*[B-Font]flag\f[] 1707275970Scyalways 1708275970Scyrestricts access, i.e., an entry with no flags indicates that free 1709275970Scyaccess to the server is to be given. 1710275970ScyThe flags are not orthogonal, 1711275970Scyin that more restrictive flags will often make less restrictive 1712275970Scyones redundant. 1713275970ScyThe flags can generally be classed into two 1714275970Scycategories, those which restrict time service and those which 1715275970Scyrestrict informational queries and attempts to do run-time 1716275970Scyreconfiguration of the server. 1717275970ScyOne or more of the following flags 1718275970Scymay be specified: 1719275970Scy.RS 1720275970Scy.TP 7 1721275970Scy.NOP \f\*[B-Font]ignore\f[] 1722275970ScyDeny packets of all kinds, including 1723285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1724275970Scyand 1725285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1726275970Scyqueries. 1727275970Scy.TP 7 1728275970Scy.NOP \f\*[B-Font]kod\f[] 1729275970ScyIf this flag is set when an access violation occurs, a kiss-o'-death 1730275970Scy(KoD) packet is sent. 1731275970ScyKoD packets are rate limited to no more than one 1732275970Scyper second. 1733275970ScyIf another KoD packet occurs within one second after the 1734275970Scylast one, the packet is dropped. 1735275970Scy.TP 7 1736275970Scy.NOP \f\*[B-Font]limited\f[] 1737275970ScyDeny service if the packet spacing violates the lower limits specified 1738298695Sdelphijin the 1739298695Sdelphij\f\*[B-Font]discard\f[] 1740298695Sdelphijcommand. 1741275970ScyA history of clients is kept using the 1742275970Scymonitoring capability of 1743285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[]. 1744275970ScyThus, monitoring is always active as 1745275970Scylong as there is a restriction entry with the 1746275970Scy\f\*[B-Font]limited\f[] 1747275970Scyflag. 1748275970Scy.TP 7 1749275970Scy.NOP \f\*[B-Font]lowpriotrap\f[] 1750275970ScyDeclare traps set by matching hosts to be low priority. 1751275970ScyThe 1752275970Scynumber of traps a server can maintain is limited (the current limit 1753275970Scyis 3). 1754275970ScyTraps are usually assigned on a first come, first served 1755275970Scybasis, with later trap requestors being denied service. 1756275970ScyThis flag 1757275970Scymodifies the assignment algorithm by allowing low priority traps to 1758275970Scybe overridden by later requests for normal priority traps. 1759275970Scy.TP 7 1760330106Sdelphij.NOP \f\*[B-Font]noepeer\f[] 1761330106SdelphijDeny ephemeral peer requests, 1762330106Sdelphijeven if they come from an authenticated source. 1763330106SdelphijNote that the ability to use a symmetric key for authentication may be restricted to 1764330106Sdelphijone or more IPs or subnets via the third field of the 1765330106Sdelphij\fIntp.keys\f[] 1766330106Sdelphijfile. 1767330106SdelphijThis restriction is not enabled by default, 1768330106Sdelphijto maintain backward compatability. 1769330106SdelphijExpect 1770330106Sdelphij\f\*[B-Font]noepeer\f[] 1771330106Sdelphijto become the default in ntp-4.4. 1772330106Sdelphij.TP 7 1773275970Scy.NOP \f\*[B-Font]nomodify\f[] 1774275970ScyDeny 1775285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1776275970Scyand 1777285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1778275970Scyqueries which attempt to modify the state of the 1779275970Scyserver (i.e., run time reconfiguration). 1780275970ScyQueries which return 1781275970Scyinformation are permitted. 1782275970Scy.TP 7 1783275970Scy.NOP \f\*[B-Font]noquery\f[] 1784275970ScyDeny 1785285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1786275970Scyand 1787285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1788275970Scyqueries. 1789275970ScyTime service is not affected. 1790275970Scy.TP 7 1791275970Scy.NOP \f\*[B-Font]nopeer\f[] 1792330106SdelphijDeny unauthenticated packets which would result in mobilizing a new association. 1793330106SdelphijThis includes 1794330106Sdelphijbroadcast and symmetric active packets 1795330106Sdelphijwhen a configured association does not exist. 1796275970ScyIt also includes 1797275970Scy\f\*[B-Font]pool\f[] 1798275970Scyassociations, so if you want to use servers from a 1799275970Scy\f\*[B-Font]pool\f[] 1800275970Scydirective and also want to use 1801275970Scy\f\*[B-Font]nopeer\f[] 1802275970Scyby default, you'll want a 1803330106Sdelphij\f\*[B-Font]restrict source ...\f[] 1804330106Sdelphijline as well that does 1805330106Sdelphij\fInot\f[] 1806275970Scyinclude the 1807275970Scy\f\*[B-Font]nopeer\f[] 1808275970Scydirective. 1809275970Scy.TP 7 1810275970Scy.NOP \f\*[B-Font]noserve\f[] 1811275970ScyDeny all packets except 1812285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1813275970Scyand 1814285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1815275970Scyqueries. 1816275970Scy.TP 7 1817275970Scy.NOP \f\*[B-Font]notrap\f[] 1818275970ScyDecline to provide mode 6 control message trap service to matching 1819275970Scyhosts. 1820298695SdelphijThe trap service is a subsystem of the 1821298695Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1822298695Sdelphijcontrol message 1823275970Scyprotocol which is intended for use by remote event logging programs. 1824275970Scy.TP 7 1825275970Scy.NOP \f\*[B-Font]notrust\f[] 1826275970ScyDeny service unless the packet is cryptographically authenticated. 1827275970Scy.TP 7 1828275970Scy.NOP \f\*[B-Font]ntpport\f[] 1829275970ScyThis is actually a match algorithm modifier, rather than a 1830275970Scyrestriction flag. 1831275970ScyIts presence causes the restriction entry to be 1832275970Scymatched only if the source port in the packet is the standard NTP 1833275970ScyUDP port (123). 1834275970ScyBoth 1835275970Scy\f\*[B-Font]ntpport\f[] 1836275970Scyand 1837275970Scy\f\*[B-Font]non-ntpport\f[] 1838275970Scymay 1839275970Scybe specified. 1840275970ScyThe 1841275970Scy\f\*[B-Font]ntpport\f[] 1842275970Scyis considered more specific and 1843275970Scyis sorted later in the list. 1844275970Scy.TP 7 1845358659Scy.NOP \f\*[B-Font]serverresponse fuzz\f[] 1846358659ScyWhen reponding to server requests, 1847358659Scyfuzz the low order bits of the 1848358659Scy\f\*[B-Font]reftime\f[]. 1849358659Scy.TP 7 1850275970Scy.NOP \f\*[B-Font]version\f[] 1851275970ScyDeny packets that do not match the current NTP version. 1852275970Scy.RE 1853275970Scy.sp \n(Ppu 1854275970Scy.ne 2 1855275970Scy 1856275970ScyDefault restriction list entries with the flags ignore, interface, 1857275970Scyntpport, for each of the local host's interface addresses are 1858275970Scyinserted into the table at startup to prevent the server 1859275970Scyfrom attempting to synchronize to its own time. 1860275970ScyA default entry is also always present, though if it is 1861275970Scyotherwise unconfigured; no flags are associated 1862275970Scywith the default entry (i.e., everything besides your own 1863275970ScyNTP server is unrestricted). 1864275970Scy.PP 1865275970Scy.SH Automatic NTP Configuration Options 1866275970Scy.SS Manycasting 1867275970ScyManycasting is a automatic discovery and configuration paradigm 1868275970Scynew to NTPv4. 1869275970ScyIt is intended as a means for a multicast client 1870275970Scyto troll the nearby network neighborhood to find cooperating 1871275970Scymanycast servers, validate them using cryptographic means 1872275970Scyand evaluate their time values with respect to other servers 1873275970Scythat might be lurking in the vicinity. 1874275970ScyThe intended result is that each manycast client mobilizes 1875275970Scyclient associations with some number of the "best" 1876275970Scyof the nearby manycast servers, yet automatically reconfigures 1877275970Scyto sustain this number of servers should one or another fail. 1878275970Scy.sp \n(Ppu 1879275970Scy.ne 2 1880275970Scy 1881275970ScyNote that the manycasting paradigm does not coincide 1882275970Scywith the anycast paradigm described in RFC-1546, 1883275970Scywhich is designed to find a single server from a clique 1884275970Scyof servers providing the same service. 1885275970ScyThe manycast paradigm is designed to find a plurality 1886275970Scyof redundant servers satisfying defined optimality criteria. 1887275970Scy.sp \n(Ppu 1888275970Scy.ne 2 1889275970Scy 1890275970ScyManycasting can be used with either symmetric key 1891275970Scyor public key cryptography. 1892275970ScyThe public key infrastructure (PKI) 1893275970Scyoffers the best protection against compromised keys 1894275970Scyand is generally considered stronger, at least with relatively 1895275970Scylarge key sizes. 1896275970ScyIt is implemented using the Autokey protocol and 1897275970Scythe OpenSSL cryptographic library available from 1898275970Scy\f[C]http://www.openssl.org/\f[]. 1899275970ScyThe library can also be used with other NTPv4 modes 1900275970Scyas well and is highly recommended, especially for broadcast modes. 1901275970Scy.sp \n(Ppu 1902275970Scy.ne 2 1903275970Scy 1904275970ScyA persistent manycast client association is configured 1905298695Sdelphijusing the 1906298695Sdelphij\f\*[B-Font]manycastclient\f[] 1907298695Sdelphijcommand, which is similar to the 1908298695Sdelphij\f\*[B-Font]server\f[] 1909298695Sdelphijcommand but with a multicast (IPv4 class 1910275970Scy\f\*[B-Font]D\f[] 1911275970Scyor IPv6 prefix 1912275970Scy\f\*[B-Font]FF\f[]) 1913275970Scygroup address. 1914275970ScyThe IANA has designated IPv4 address 224.1.1.1 1915275970Scyand IPv6 address FF05::101 (site local) for NTP. 1916275970ScyWhen more servers are needed, it broadcasts manycast 1917275970Scyclient messages to this address at the minimum feasible rate 1918275970Scyand minimum feasible time-to-live (TTL) hops, depending 1919275970Scyon how many servers have already been found. 1920275970ScyThere can be as many manycast client associations 1921275970Scyas different group address, each one serving as a template 1922275970Scyfor a future ephemeral unicast client/server association. 1923275970Scy.sp \n(Ppu 1924275970Scy.ne 2 1925275970Scy 1926275970ScyManycast servers configured with the 1927275970Scy\f\*[B-Font]manycastserver\f[] 1928275970Scycommand listen on the specified group address for manycast 1929275970Scyclient messages. 1930275970ScyNote the distinction between manycast client, 1931275970Scywhich actively broadcasts messages, and manycast server, 1932275970Scywhich passively responds to them. 1933275970ScyIf a manycast server is 1934275970Scyin scope of the current TTL and is itself synchronized 1935275970Scyto a valid source and operating at a stratum level equal 1936275970Scyto or lower than the manycast client, it replies to the 1937275970Scymanycast client message with an ordinary unicast server message. 1938275970Scy.sp \n(Ppu 1939275970Scy.ne 2 1940275970Scy 1941275970ScyThe manycast client receiving this message mobilizes 1942275970Scyan ephemeral client/server association according to the 1943275970Scymatching manycast client template, but only if cryptographically 1944275970Scyauthenticated and the server stratum is less than or equal 1945275970Scyto the client stratum. 1946275970ScyAuthentication is explicitly required 1947275970Scyand either symmetric key or public key (Autokey) can be used. 1948275970ScyThen, the client polls the server at its unicast address 1949275970Scyin burst mode in order to reliably set the host clock 1950275970Scyand validate the source. 1951275970ScyThis normally results 1952275970Scyin a volley of eight client/server at 2-s intervals 1953275970Scyduring which both the synchronization and cryptographic 1954275970Scyprotocols run concurrently. 1955275970ScyFollowing the volley, 1956275970Scythe client runs the NTP intersection and clustering 1957275970Scyalgorithms, which act to discard all but the "best" 1958275970Scyassociations according to stratum and synchronization 1959275970Scydistance. 1960275970ScyThe surviving associations then continue 1961275970Scyin ordinary client/server mode. 1962275970Scy.sp \n(Ppu 1963275970Scy.ne 2 1964275970Scy 1965275970ScyThe manycast client polling strategy is designed to reduce 1966275970Scyas much as possible the volume of manycast client messages 1967275970Scyand the effects of implosion due to near-simultaneous 1968275970Scyarrival of manycast server messages. 1969275970ScyThe strategy is determined by the 1970275970Scy\f\*[B-Font]manycastclient\f[], 1971275970Scy\f\*[B-Font]tos\f[] 1972275970Scyand 1973275970Scy\f\*[B-Font]ttl\f[] 1974275970Scyconfiguration commands. 1975275970ScyThe manycast poll interval is 1976275970Scynormally eight times the system poll interval, 1977275970Scywhich starts out at the 1978275970Scy\f\*[B-Font]minpoll\f[] 1979275970Scyvalue specified in the 1980275970Scy\f\*[B-Font]manycastclient\f[], 1981275970Scycommand and, under normal circumstances, increments to the 1982275970Scy\f\*[B-Font]maxpolll\f[] 1983275970Scyvalue specified in this command. 1984275970ScyInitially, the TTL is 1985298695Sdelphijset at the minimum hops specified by the 1986298695Sdelphij\f\*[B-Font]ttl\f[] 1987298695Sdelphijcommand. 1988275970ScyAt each retransmission the TTL is increased until reaching 1989275970Scythe maximum hops specified by this command or a sufficient 1990275970Scynumber client associations have been found. 1991275970ScyFurther retransmissions use the same TTL. 1992275970Scy.sp \n(Ppu 1993275970Scy.ne 2 1994275970Scy 1995275970ScyThe quality and reliability of the suite of associations 1996275970Scydiscovered by the manycast client is determined by the NTP 1997275970Scymitigation algorithms and the 1998275970Scy\f\*[B-Font]minclock\f[] 1999275970Scyand 2000275970Scy\f\*[B-Font]minsane\f[] 2001275970Scyvalues specified in the 2002275970Scy\f\*[B-Font]tos\f[] 2003275970Scyconfiguration command. 2004275970ScyAt least 2005275970Scy\f\*[B-Font]minsane\f[] 2006275970Scycandidate servers must be available and the mitigation 2007275970Scyalgorithms produce at least 2008275970Scy\f\*[B-Font]minclock\f[] 2009275970Scysurvivors in order to synchronize the clock. 2010275970ScyByzantine agreement principles require at least four 2011275970Scycandidates in order to correctly discard a single falseticker. 2012275970ScyFor legacy purposes, 2013275970Scy\f\*[B-Font]minsane\f[] 2014275970Scydefaults to 1 and 2015275970Scy\f\*[B-Font]minclock\f[] 2016275970Scydefaults to 3. 2017275970ScyFor manycast service 2018275970Scy\f\*[B-Font]minsane\f[] 2019275970Scyshould be explicitly set to 4, assuming at least that 2020275970Scynumber of servers are available. 2021275970Scy.sp \n(Ppu 2022275970Scy.ne 2 2023275970Scy 2024275970ScyIf at least 2025275970Scy\f\*[B-Font]minclock\f[] 2026275970Scyservers are found, the manycast poll interval is immediately 2027275970Scyset to eight times 2028275970Scy\f\*[B-Font]maxpoll\f[]. 2029275970ScyIf less than 2030275970Scy\f\*[B-Font]minclock\f[] 2031275970Scyservers are found when the TTL has reached the maximum hops, 2032275970Scythe manycast poll interval is doubled. 2033275970ScyFor each transmission 2034275970Scyafter that, the poll interval is doubled again until 2035275970Scyreaching the maximum of eight times 2036275970Scy\f\*[B-Font]maxpoll\f[]. 2037275970ScyFurther transmissions use the same poll interval and 2038275970ScyTTL values. 2039275970ScyNote that while all this is going on, 2040275970Scyeach client/server association found is operating normally 2041275970Scyit the system poll interval. 2042275970Scy.sp \n(Ppu 2043275970Scy.ne 2 2044275970Scy 2045275970ScyAdministratively scoped multicast boundaries are normally 2046275970Scyspecified by the network router configuration and, 2047275970Scyin the case of IPv6, the link/site scope prefix. 2048275970ScyBy default, the increment for TTL hops is 32 starting 2049275970Scyfrom 31; however, the 2050275970Scy\f\*[B-Font]ttl\f[] 2051275970Scyconfiguration command can be 2052275970Scyused to modify the values to match the scope rules. 2053275970Scy.sp \n(Ppu 2054275970Scy.ne 2 2055275970Scy 2056275970ScyIt is often useful to narrow the range of acceptable 2057275970Scyservers which can be found by manycast client associations. 2058275970ScyBecause manycast servers respond only when the client 2059275970Scystratum is equal to or greater than the server stratum, 2060275970Scyprimary (stratum 1) servers fill find only primary servers 2061275970Scyin TTL range, which is probably the most common objective. 2062275970ScyHowever, unless configured otherwise, all manycast clients 2063275970Scyin TTL range will eventually find all primary servers 2064275970Scyin TTL range, which is probably not the most common 2065275970Scyobjective in large networks. 2066275970ScyThe 2067275970Scy\f\*[B-Font]tos\f[] 2068275970Scycommand can be used to modify this behavior. 2069275970ScyServers with stratum below 2070275970Scy\f\*[B-Font]floor\f[] 2071275970Scyor above 2072275970Scy\f\*[B-Font]ceiling\f[] 2073275970Scyspecified in the 2074275970Scy\f\*[B-Font]tos\f[] 2075275970Scycommand are strongly discouraged during the selection 2076275970Scyprocess; however, these servers may be temporally 2077275970Scyaccepted if the number of servers within TTL range is 2078275970Scyless than 2079275970Scy\f\*[B-Font]minclock\f[]. 2080275970Scy.sp \n(Ppu 2081275970Scy.ne 2 2082275970Scy 2083275970ScyThe above actions occur for each manycast client message, 2084275970Scywhich repeats at the designated poll interval. 2085275970ScyHowever, once the ephemeral client association is mobilized, 2086275970Scysubsequent manycast server replies are discarded, 2087275970Scysince that would result in a duplicate association. 2088275970ScyIf during a poll interval the number of client associations 2089275970Scyfalls below 2090275970Scy\f\*[B-Font]minclock\f[], 2091275970Scyall manycast client prototype associations are reset 2092275970Scyto the initial poll interval and TTL hops and operation 2093275970Scyresumes from the beginning. 2094275970ScyIt is important to avoid 2095275970Scyfrequent manycast client messages, since each one requires 2096275970Scyall manycast servers in TTL range to respond. 2097275970ScyThe result could well be an implosion, either minor or major, 2098275970Scydepending on the number of servers in range. 2099275970ScyThe recommended value for 2100275970Scy\f\*[B-Font]maxpoll\f[] 2101275970Scyis 12 (4,096 s). 2102275970Scy.sp \n(Ppu 2103275970Scy.ne 2 2104275970Scy 2105275970ScyIt is possible and frequently useful to configure a host 2106275970Scyas both manycast client and manycast server. 2107275970ScyA number of hosts configured this way and sharing a common 2108275970Scygroup address will automatically organize themselves 2109275970Scyin an optimum configuration based on stratum and 2110275970Scysynchronization distance. 2111275970ScyFor example, consider an NTP 2112275970Scysubnet of two primary servers and a hundred or more 2113275970Scydependent clients. 2114275970ScyWith two exceptions, all servers 2115275970Scyand clients have identical configuration files including both 2116275970Scy\f\*[B-Font]multicastclient\f[] 2117275970Scyand 2118275970Scy\f\*[B-Font]multicastserver\f[] 2119275970Scycommands using, for instance, multicast group address 2120275970Scy239.1.1.1. 2121275970ScyThe only exception is that each primary server 2122275970Scyconfiguration file must include commands for the primary 2123275970Scyreference source such as a GPS receiver. 2124275970Scy.sp \n(Ppu 2125275970Scy.ne 2 2126275970Scy 2127275970ScyThe remaining configuration files for all secondary 2128275970Scyservers and clients have the same contents, except for the 2129275970Scy\f\*[B-Font]tos\f[] 2130275970Scycommand, which is specific for each stratum level. 2131275970ScyFor stratum 1 and stratum 2 servers, that command is 2132275970Scynot necessary. 2133275970ScyFor stratum 3 and above servers the 2134275970Scy\f\*[B-Font]floor\f[] 2135275970Scyvalue is set to the intended stratum number. 2136275970ScyThus, all stratum 3 configuration files are identical, 2137275970Scyall stratum 4 files are identical and so forth. 2138275970Scy.sp \n(Ppu 2139275970Scy.ne 2 2140275970Scy 2141275970ScyOnce operations have stabilized in this scenario, 2142275970Scythe primary servers will find the primary reference source 2143275970Scyand each other, since they both operate at the same 2144275970Scystratum (1), but not with any secondary server or client, 2145275970Scysince these operate at a higher stratum. 2146275970ScyThe secondary 2147275970Scyservers will find the servers at the same stratum level. 2148275970ScyIf one of the primary servers loses its GPS receiver, 2149275970Scyit will continue to operate as a client and other clients 2150275970Scywill time out the corresponding association and 2151275970Scyre-associate accordingly. 2152275970Scy.sp \n(Ppu 2153275970Scy.ne 2 2154275970Scy 2155275970ScySome administrators prefer to avoid running 2156285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2157275970Scycontinuously and run either 2158289764Sglebius\fCsntp\f[]\fR(@SNTP_MS@)\f[] 2159275970Scyor 2160285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2161275970Scy\f\*[B-Font]\-q\f[] 2162275970Scyas a cron job. 2163275970ScyIn either case the servers must be 2164275970Scyconfigured in advance and the program fails if none are 2165275970Scyavailable when the cron job runs. 2166275970ScyA really slick 2167275970Scyapplication of manycast is with 2168285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2169275970Scy\f\*[B-Font]\-q\f[]. 2170275970ScyThe program wakes up, scans the local landscape looking 2171275970Scyfor the usual suspects, selects the best from among 2172275970Scythe rascals, sets the clock and then departs. 2173275970ScyServers do not have to be configured in advance and 2174275970Scyall clients throughout the network can have the same 2175275970Scyconfiguration file. 2176275970Scy.SS Manycast Interactions with Autokey 2177275970ScyEach time a manycast client sends a client mode packet 2178275970Scyto a multicast group address, all manycast servers 2179275970Scyin scope generate a reply including the host name 2180275970Scyand status word. 2181275970ScyThe manycast clients then run 2182275970Scythe Autokey protocol, which collects and verifies 2183275970Scyall certificates involved. 2184275970ScyFollowing the burst interval 2185275970Scyall but three survivors are cast off, 2186275970Scybut the certificates remain in the local cache. 2187275970ScyIt often happens that several complete signing trails 2188275970Scyfrom the client to the primary servers are collected in this way. 2189275970Scy.sp \n(Ppu 2190275970Scy.ne 2 2191275970Scy 2192275970ScyAbout once an hour or less often if the poll interval 2193275970Scyexceeds this, the client regenerates the Autokey key list. 2194275970ScyThis is in general transparent in client/server mode. 2195275970ScyHowever, about once per day the server private value 2196275970Scyused to generate cookies is refreshed along with all 2197275970Scymanycast client associations. 2198275970ScyIn this case all 2199275970Scycryptographic values including certificates is refreshed. 2200275970ScyIf a new certificate has been generated since 2201275970Scythe last refresh epoch, it will automatically revoke 2202275970Scyall prior certificates that happen to be in the 2203275970Scycertificate cache. 2204275970ScyAt the same time, the manycast 2205275970Scyscheme starts all over from the beginning and 2206275970Scythe expanding ring shrinks to the minimum and increments 2207275970Scyfrom there while collecting all servers in scope. 2208309007Sdelphij.SS Broadcast Options 2209309007Sdelphij.TP 7 2210309007Sdelphij.NOP \f\*[B-Font]tos\f[] [\f\*[B-Font]bcpollbstep\f[] \f\*[I-Font]gate\f[]] 2211309007SdelphijThis command provides a way to delay, 2212309007Sdelphijby the specified number of broadcast poll intervals, 2213309007Sdelphijbelieving backward time steps from a broadcast server. 2214309007SdelphijBroadcast time networks are expected to be trusted. 2215309007SdelphijIn the event a broadcast server's time is stepped backwards, 2216309007Sdelphijthere is clear benefit to having the clients notice this change 2217309007Sdelphijas soon as possible. 2218309007SdelphijAttacks such as replay attacks can happen, however, 2219309007Sdelphijand even though there are a number of protections built in to 2220330106Sdelphijbroadcast mode, attempts to perform a replay attack are possible. 2221309007SdelphijThis value defaults to 0, but can be changed 2222309007Sdelphijto any number of poll intervals between 0 and 4. 2223330106Sdelphij.PP 2224275970Scy.SS Manycast Options 2225275970Scy.TP 7 2226275970Scy.NOP \f\*[B-Font]tos\f[] [\f\*[B-Font]ceiling\f[] \f\*[I-Font]ceiling\f[] | \f\*[B-Font]cohort\f[] { \f\*[B-Font]0\f[] | \f\*[B-Font]1\f[] } | \f\*[B-Font]floor\f[] \f\*[I-Font]floor\f[] | \f\*[B-Font]minclock\f[] \f\*[I-Font]minclock\f[] | \f\*[B-Font]minsane\f[] \f\*[I-Font]minsane\f[]] 2227275970ScyThis command affects the clock selection and clustering 2228275970Scyalgorithms. 2229275970ScyIt can be used to select the quality and 2230275970Scyquantity of peers used to synchronize the system clock 2231275970Scyand is most useful in manycast mode. 2232275970ScyThe variables operate 2233275970Scyas follows: 2234275970Scy.RS 2235275970Scy.TP 7 2236275970Scy.NOP \f\*[B-Font]ceiling\f[] \f\*[I-Font]ceiling\f[] 2237275970ScyPeers with strata above 2238275970Scy\f\*[B-Font]ceiling\f[] 2239275970Scywill be discarded if there are at least 2240275970Scy\f\*[B-Font]minclock\f[] 2241275970Scypeers remaining. 2242275970ScyThis value defaults to 15, but can be changed 2243275970Scyto any number from 1 to 15. 2244275970Scy.TP 7 2245275970Scy.NOP \f\*[B-Font]cohort\f[] {0 | 1 } 2246275970ScyThis is a binary flag which enables (0) or disables (1) 2247275970Scymanycast server replies to manycast clients with the same 2248275970Scystratum level. 2249275970ScyThis is useful to reduce implosions where 2250275970Scylarge numbers of clients with the same stratum level 2251275970Scyare present. 2252275970ScyThe default is to enable these replies. 2253275970Scy.TP 7 2254275970Scy.NOP \f\*[B-Font]floor\f[] \f\*[I-Font]floor\f[] 2255275970ScyPeers with strata below 2256275970Scy\f\*[B-Font]floor\f[] 2257275970Scywill be discarded if there are at least 2258275970Scy\f\*[B-Font]minclock\f[] 2259275970Scypeers remaining. 2260275970ScyThis value defaults to 1, but can be changed 2261275970Scyto any number from 1 to 15. 2262275970Scy.TP 7 2263275970Scy.NOP \f\*[B-Font]minclock\f[] \f\*[I-Font]minclock\f[] 2264289764SglebiusThe clustering algorithm repeatedly casts out outlier 2265275970Scyassociations until no more than 2266275970Scy\f\*[B-Font]minclock\f[] 2267275970Scyassociations remain. 2268275970ScyThis value defaults to 3, 2269275970Scybut can be changed to any number from 1 to the number of 2270275970Scyconfigured sources. 2271275970Scy.TP 7 2272275970Scy.NOP \f\*[B-Font]minsane\f[] \f\*[I-Font]minsane\f[] 2273275970ScyThis is the minimum number of candidates available 2274275970Scyto the clock selection algorithm in order to produce 2275275970Scyone or more truechimers for the clustering algorithm. 2276275970ScyIf fewer than this number are available, the clock is 2277275970Scyundisciplined and allowed to run free. 2278275970ScyThe default is 1 2279275970Scyfor legacy purposes. 2280275970ScyHowever, according to principles of 2281275970ScyByzantine agreement, 2282275970Scy\f\*[B-Font]minsane\f[] 2283275970Scyshould be at least 4 in order to detect and discard 2284275970Scya single falseticker. 2285275970Scy.RE 2286275970Scy.TP 7 2287275970Scy.NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]hop\f[] \f\*[I-Font]...\f[] 2288275970ScyThis command specifies a list of TTL values in increasing 2289275970Scyorder, up to 8 values can be specified. 2290275970ScyIn manycast mode these values are used in turn 2291275970Scyin an expanding-ring search. 2292275970ScyThe default is eight 2293275970Scymultiples of 32 starting at 31. 2294330106Sdelphij.PP 2295275970Scy.SH Reference Clock Support 2296275970ScyThe NTP Version 4 daemon supports some three dozen different radio, 2297275970Scysatellite and modem reference clocks plus a special pseudo-clock 2298275970Scyused for backup or when no other clock source is available. 2299275970ScyDetailed descriptions of individual device drivers and options can 2300275970Scybe found in the 2301275970Scy"Reference Clock Drivers" 2302275970Scypage 2303275970Scy(available as part of the HTML documentation 2304275970Scyprovided in 2305275970Scy\fI/usr/share/doc/ntp\f[]). 2306275970ScyAdditional information can be found in the pages linked 2307275970Scythere, including the 2308275970Scy"Debugging Hints for Reference Clock Drivers" 2309275970Scyand 2310275970Scy"How To Write a Reference Clock Driver" 2311275970Scypages 2312275970Scy(available as part of the HTML documentation 2313275970Scyprovided in 2314275970Scy\fI/usr/share/doc/ntp\f[]). 2315275970ScyIn addition, support for a PPS 2316275970Scysignal is available as described in the 2317275970Scy"Pulse-per-second (PPS) Signal Interfacing" 2318275970Scypage 2319275970Scy(available as part of the HTML documentation 2320275970Scyprovided in 2321275970Scy\fI/usr/share/doc/ntp\f[]). 2322275970ScyMany 2323275970Scydrivers support special line discipline/streams modules which can 2324275970Scysignificantly improve the accuracy using the driver. 2325275970ScyThese are 2326275970Scydescribed in the 2327275970Scy"Line Disciplines and Streams Drivers" 2328275970Scypage 2329275970Scy(available as part of the HTML documentation 2330275970Scyprovided in 2331275970Scy\fI/usr/share/doc/ntp\f[]). 2332275970Scy.sp \n(Ppu 2333275970Scy.ne 2 2334275970Scy 2335275970ScyA reference clock will generally (though not always) be a radio 2336275970Scytimecode receiver which is synchronized to a source of standard 2337275970Scytime such as the services offered by the NRC in Canada and NIST and 2338275970ScyUSNO in the US. 2339275970ScyThe interface between the computer and the timecode 2340275970Scyreceiver is device dependent, but is usually a serial port. 2341275970ScyA 2342275970Scydevice driver specific to each reference clock must be selected and 2343275970Scycompiled in the distribution; however, most common radio, satellite 2344275970Scyand modem clocks are included by default. 2345275970ScyNote that an attempt to 2346275970Scyconfigure a reference clock when the driver has not been compiled 2347275970Scyor the hardware port has not been appropriately configured results 2348275970Scyin a scalding remark to the system log file, but is otherwise non 2349275970Scyhazardous. 2350275970Scy.sp \n(Ppu 2351275970Scy.ne 2 2352275970Scy 2353275970ScyFor the purposes of configuration, 2354285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2355275970Scytreats 2356275970Scyreference clocks in a manner analogous to normal NTP peers as much 2357275970Scyas possible. 2358275970ScyReference clocks are identified by a syntactically 2359275970Scycorrect but invalid IP address, in order to distinguish them from 2360275970Scynormal NTP peers. 2361275970ScyReference clock addresses are of the form 2362275970Scy\f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[], 2363275970Scywhere 2364275970Scy\f\*[I-Font]t\f[] 2365275970Scyis an integer 2366275970Scydenoting the clock type and 2367275970Scy\f\*[I-Font]u\f[] 2368275970Scyindicates the unit 2369275970Scynumber in the range 0-3. 2370275970ScyWhile it may seem overkill, it is in fact 2371275970Scysometimes useful to configure multiple reference clocks of the same 2372275970Scytype, in which case the unit numbers must be unique. 2373275970Scy.sp \n(Ppu 2374275970Scy.ne 2 2375275970Scy 2376275970ScyThe 2377275970Scy\f\*[B-Font]server\f[] 2378275970Scycommand is used to configure a reference 2379275970Scyclock, where the 2380275970Scy\f\*[I-Font]address\f[] 2381275970Scyargument in that command 2382275970Scyis the clock address. 2383275970ScyThe 2384275970Scy\f\*[B-Font]key\f[], 2385275970Scy\f\*[B-Font]version\f[] 2386275970Scyand 2387275970Scy\f\*[B-Font]ttl\f[] 2388275970Scyoptions are not used for reference clock support. 2389275970ScyThe 2390275970Scy\f\*[B-Font]mode\f[] 2391275970Scyoption is added for reference clock support, as 2392275970Scydescribed below. 2393275970ScyThe 2394275970Scy\f\*[B-Font]prefer\f[] 2395275970Scyoption can be useful to 2396275970Scypersuade the server to cherish a reference clock with somewhat more 2397275970Scyenthusiasm than other reference clocks or peers. 2398275970ScyFurther 2399275970Scyinformation on this option can be found in the 2400275970Scy"Mitigation Rules and the prefer Keyword" 2401275970Scy(available as part of the HTML documentation 2402275970Scyprovided in 2403275970Scy\fI/usr/share/doc/ntp\f[]) 2404275970Scypage. 2405275970ScyThe 2406275970Scy\f\*[B-Font]minpoll\f[] 2407275970Scyand 2408275970Scy\f\*[B-Font]maxpoll\f[] 2409275970Scyoptions have 2410275970Scymeaning only for selected clock drivers. 2411275970ScySee the individual clock 2412275970Scydriver document pages for additional information. 2413275970Scy.sp \n(Ppu 2414275970Scy.ne 2 2415275970Scy 2416275970ScyThe 2417275970Scy\f\*[B-Font]fudge\f[] 2418275970Scycommand is used to provide additional 2419275970Scyinformation for individual clock drivers and normally follows 2420275970Scyimmediately after the 2421275970Scy\f\*[B-Font]server\f[] 2422275970Scycommand. 2423275970ScyThe 2424275970Scy\f\*[I-Font]address\f[] 2425275970Scyargument specifies the clock address. 2426275970ScyThe 2427275970Scy\f\*[B-Font]refid\f[] 2428275970Scyand 2429275970Scy\f\*[B-Font]stratum\f[] 2430275970Scyoptions can be used to 2431275970Scyoverride the defaults for the device. 2432275970ScyThere are two optional 2433275970Scydevice-dependent time offsets and four flags that can be included 2434275970Scyin the 2435275970Scy\f\*[B-Font]fudge\f[] 2436275970Scycommand as well. 2437275970Scy.sp \n(Ppu 2438275970Scy.ne 2 2439275970Scy 2440275970ScyThe stratum number of a reference clock is by default zero. 2441275970ScySince the 2442285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2443275970Scydaemon adds one to the stratum of each 2444275970Scypeer, a primary server ordinarily displays an external stratum of 2445275970Scyone. 2446275970ScyIn order to provide engineered backups, it is often useful to 2447275970Scyspecify the reference clock stratum as greater than zero. 2448275970ScyThe 2449275970Scy\f\*[B-Font]stratum\f[] 2450275970Scyoption is used for this purpose. 2451275970ScyAlso, in cases 2452275970Scyinvolving both a reference clock and a pulse-per-second (PPS) 2453275970Scydiscipline signal, it is useful to specify the reference clock 2454275970Scyidentifier as other than the default, depending on the driver. 2455275970ScyThe 2456275970Scy\f\*[B-Font]refid\f[] 2457275970Scyoption is used for this purpose. 2458275970ScyExcept where noted, 2459275970Scythese options apply to all clock drivers. 2460275970Scy.SS Reference Clock Commands 2461275970Scy.TP 7 2462275970Scy.NOP \f\*[B-Font]server\f[] \f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[] [\f\*[B-Font]prefer\f[]] [\f\*[B-Font]mode\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]minpoll\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]maxpoll\f[] \f\*[I-Font]int\f[]] 2463275970ScyThis command can be used to configure reference clocks in 2464275970Scyspecial ways. 2465275970ScyThe options are interpreted as follows: 2466275970Scy.RS 2467275970Scy.TP 7 2468275970Scy.NOP \f\*[B-Font]prefer\f[] 2469275970ScyMarks the reference clock as preferred. 2470275970ScyAll other things being 2471275970Scyequal, this host will be chosen for synchronization among a set of 2472275970Scycorrectly operating hosts. 2473275970ScySee the 2474275970Scy"Mitigation Rules and the prefer Keyword" 2475275970Scypage 2476275970Scy(available as part of the HTML documentation 2477275970Scyprovided in 2478275970Scy\fI/usr/share/doc/ntp\f[]) 2479275970Scyfor further information. 2480275970Scy.TP 7 2481275970Scy.NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[] 2482275970ScySpecifies a mode number which is interpreted in a 2483275970Scydevice-specific fashion. 2484275970ScyFor instance, it selects a dialing 2485275970Scyprotocol in the ACTS driver and a device subtype in the 2486275970Scyparse 2487275970Scydrivers. 2488275970Scy.TP 7 2489275970Scy.NOP \f\*[B-Font]minpoll\f[] \f\*[I-Font]int\f[] 2490275970Scy.TP 7 2491275970Scy.NOP \f\*[B-Font]maxpoll\f[] \f\*[I-Font]int\f[] 2492275970ScyThese options specify the minimum and maximum polling interval 2493275970Scyfor reference clock messages, as a power of 2 in seconds 2494275970ScyFor 2495275970Scymost directly connected reference clocks, both 2496275970Scy\f\*[B-Font]minpoll\f[] 2497275970Scyand 2498275970Scy\f\*[B-Font]maxpoll\f[] 2499275970Scydefault to 6 (64 s). 2500275970ScyFor modem reference clocks, 2501275970Scy\f\*[B-Font]minpoll\f[] 2502275970Scydefaults to 10 (17.1 m) and 2503275970Scy\f\*[B-Font]maxpoll\f[] 2504275970Scydefaults to 14 (4.5 h). 2505275970ScyThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2506275970Scy.RE 2507275970Scy.TP 7 2508275970Scy.NOP \f\*[B-Font]fudge\f[] \f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[] [\f\*[B-Font]time1\f[] \f\*[I-Font]sec\f[]] [\f\*[B-Font]time2\f[] \f\*[I-Font]sec\f[]] [\f\*[B-Font]stratum\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]refid\f[] \f\*[I-Font]string\f[]] [\f\*[B-Font]mode\f[] \f\*[I-Font]int\f[]] [\f\*[B-Font]flag1\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] [\f\*[B-Font]flag2\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] [\f\*[B-Font]flag3\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] [\f\*[B-Font]flag4\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[]] 2509275970ScyThis command can be used to configure reference clocks in 2510275970Scyspecial ways. 2511275970ScyIt must immediately follow the 2512275970Scy\f\*[B-Font]server\f[] 2513275970Scycommand which configures the driver. 2514275970ScyNote that the same capability 2515275970Scyis possible at run time using the 2516285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2517275970Scyprogram. 2518275970ScyThe options are interpreted as 2519275970Scyfollows: 2520275970Scy.RS 2521275970Scy.TP 7 2522275970Scy.NOP \f\*[B-Font]time1\f[] \f\*[I-Font]sec\f[] 2523275970ScySpecifies a constant to be added to the time offset produced by 2524275970Scythe driver, a fixed-point decimal number in seconds. 2525275970ScyThis is used 2526275970Scyas a calibration constant to adjust the nominal time offset of a 2527275970Scyparticular clock to agree with an external standard, such as a 2528275970Scyprecision PPS signal. 2529275970ScyIt also provides a way to correct a 2530275970Scysystematic error or bias due to serial port or operating system 2531275970Scylatencies, different cable lengths or receiver internal delay. 2532275970ScyThe 2533275970Scyspecified offset is in addition to the propagation delay provided 2534275970Scyby other means, such as internal DIPswitches. 2535275970ScyWhere a calibration 2536275970Scyfor an individual system and driver is available, an approximate 2537275970Scycorrection is noted in the driver documentation pages. 2538275970ScyNote: in order to facilitate calibration when more than one 2539275970Scyradio clock or PPS signal is supported, a special calibration 2540275970Scyfeature is available. 2541275970ScyIt takes the form of an argument to the 2542275970Scy\f\*[B-Font]enable\f[] 2543275970Scycommand described in 2544275970Scy\fIMiscellaneous\f[] \fIOptions\f[] 2545275970Scypage and operates as described in the 2546275970Scy"Reference Clock Drivers" 2547275970Scypage 2548275970Scy(available as part of the HTML documentation 2549275970Scyprovided in 2550275970Scy\fI/usr/share/doc/ntp\f[]). 2551275970Scy.TP 7 2552275970Scy.NOP \f\*[B-Font]time2\f[] \f\*[I-Font]secs\f[] 2553275970ScySpecifies a fixed-point decimal number in seconds, which is 2554275970Scyinterpreted in a driver-dependent way. 2555275970ScySee the descriptions of 2556275970Scyspecific drivers in the 2557275970Scy"Reference Clock Drivers" 2558275970Scypage 2559275970Scy(available as part of the HTML documentation 2560275970Scyprovided in 2561330106Sdelphij\fI/usr/share/doc/ntp\f[] \fI).\f[] 2562275970Scy.TP 7 2563275970Scy.NOP \f\*[B-Font]stratum\f[] \f\*[I-Font]int\f[] 2564275970ScySpecifies the stratum number assigned to the driver, an integer 2565275970Scybetween 0 and 15. 2566275970ScyThis number overrides the default stratum number 2567275970Scyordinarily assigned by the driver itself, usually zero. 2568275970Scy.TP 7 2569275970Scy.NOP \f\*[B-Font]refid\f[] \f\*[I-Font]string\f[] 2570275970ScySpecifies an ASCII string of from one to four characters which 2571275970Scydefines the reference identifier used by the driver. 2572275970ScyThis string 2573275970Scyoverrides the default identifier ordinarily assigned by the driver 2574275970Scyitself. 2575275970Scy.TP 7 2576275970Scy.NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[] 2577275970ScySpecifies a mode number which is interpreted in a 2578275970Scydevice-specific fashion. 2579275970ScyFor instance, it selects a dialing 2580275970Scyprotocol in the ACTS driver and a device subtype in the 2581275970Scyparse 2582275970Scydrivers. 2583275970Scy.TP 7 2584275970Scy.NOP \f\*[B-Font]flag1\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2585275970Scy.TP 7 2586275970Scy.NOP \f\*[B-Font]flag2\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2587275970Scy.TP 7 2588275970Scy.NOP \f\*[B-Font]flag3\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2589275970Scy.TP 7 2590275970Scy.NOP \f\*[B-Font]flag4\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2591275970ScyThese four flags are used for customizing the clock driver. 2592275970ScyThe 2593275970Scyinterpretation of these values, and whether they are used at all, 2594275970Scyis a function of the particular clock driver. 2595275970ScyHowever, by 2596275970Scyconvention 2597275970Scy\f\*[B-Font]flag4\f[] 2598275970Scyis used to enable recording monitoring 2599275970Scydata to the 2600275970Scy\f\*[B-Font]clockstats\f[] 2601275970Scyfile configured with the 2602275970Scy\f\*[B-Font]filegen\f[] 2603275970Scycommand. 2604275970ScyFurther information on the 2605275970Scy\f\*[B-Font]filegen\f[] 2606275970Scycommand can be found in 2607275970Scy\fIMonitoring\f[] \fIOptions\f[]. 2608275970Scy.RE 2609330106Sdelphij.PP 2610275970Scy.SH Miscellaneous Options 2611275970Scy.TP 7 2612275970Scy.NOP \f\*[B-Font]broadcastdelay\f[] \f\*[I-Font]seconds\f[] 2613275970ScyThe broadcast and multicast modes require a special calibration 2614275970Scyto determine the network delay between the local and remote 2615275970Scyservers. 2616275970ScyOrdinarily, this is done automatically by the initial 2617275970Scyprotocol exchanges between the client and server. 2618275970ScyIn some cases, 2619275970Scythe calibration procedure may fail due to network or server access 2620275970Scycontrols, for example. 2621275970ScyThis command specifies the default delay to 2622275970Scybe used under these circumstances. 2623275970ScyTypically (for Ethernet), a 2624275970Scynumber between 0.003 and 0.007 seconds is appropriate. 2625275970ScyThe default 2626275970Scywhen this command is not used is 0.004 seconds. 2627275970Scy.TP 7 2628275970Scy.NOP \f\*[B-Font]calldelay\f[] \f\*[I-Font]delay\f[] 2629275970ScyThis option controls the delay in seconds between the first and second 2630275970Scypackets sent in burst or iburst mode to allow additional time for a modem 2631275970Scyor ISDN call to complete. 2632275970Scy.TP 7 2633275970Scy.NOP \f\*[B-Font]driftfile\f[] \f\*[I-Font]driftfile\f[] 2634275970ScyThis command specifies the complete path and name of the file used to 2635275970Scyrecord the frequency of the local clock oscillator. 2636275970ScyThis is the same 2637275970Scyoperation as the 2638275970Scy\f\*[B-Font]\-f\f[] 2639275970Scycommand line option. 2640275970ScyIf the file exists, it is read at 2641275970Scystartup in order to set the initial frequency and then updated once per 2642275970Scyhour with the current frequency computed by the daemon. 2643275970ScyIf the file name is 2644275970Scyspecified, but the file itself does not exist, the starts with an initial 2645275970Scyfrequency of zero and creates the file when writing it for the first time. 2646275970ScyIf this command is not given, the daemon will always start with an initial 2647275970Scyfrequency of zero. 2648275970Scy.sp \n(Ppu 2649275970Scy.ne 2 2650275970Scy 2651275970ScyThe file format consists of a single line containing a single 2652275970Scyfloating point number, which records the frequency offset measured 2653275970Scyin parts-per-million (PPM). 2654275970ScyThe file is updated by first writing 2655275970Scythe current drift value into a temporary file and then renaming 2656275970Scythis file to replace the old version. 2657275970ScyThis implies that 2658285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2659275970Scymust have write permission for the directory the 2660275970Scydrift file is located in, and that file system links, symbolic or 2661275970Scyotherwise, should be avoided. 2662275970Scy.TP 7 2663285169Scy.NOP \f\*[B-Font]dscp\f[] \f\*[I-Font]value\f[] 2664285169ScyThis option specifies the Differentiated Services Control Point (DSCP) value, 2665298695Sdelphija 6-bit code. 2666298695SdelphijThe default value is 46, signifying Expedited Forwarding. 2667285169Scy.TP 7 2668301247Sdelphij.NOP \f\*[B-Font]enable\f[] [\f\*[B-Font]auth\f[] | \f\*[B-Font]bclient\f[] | \f\*[B-Font]calibrate\f[] | \f\*[B-Font]kernel\f[] | \f\*[B-Font]mode7\f[] | \f\*[B-Font]monitor\f[] | \f\*[B-Font]ntp\f[] | \f\*[B-Font]stats\f[] | \f\*[B-Font]peer_clear_digest_early\f[] | \f\*[B-Font]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]] 2669275970Scy.TP 7 2670301247Sdelphij.NOP \f\*[B-Font]disable\f[] [\f\*[B-Font]auth\f[] | \f\*[B-Font]bclient\f[] | \f\*[B-Font]calibrate\f[] | \f\*[B-Font]kernel\f[] | \f\*[B-Font]mode7\f[] | \f\*[B-Font]monitor\f[] | \f\*[B-Font]ntp\f[] | \f\*[B-Font]stats\f[] | \f\*[B-Font]peer_clear_digest_early\f[] | \f\*[B-Font]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]] 2671275970ScyProvides a way to enable or disable various server options. 2672275970ScyFlags not mentioned are unaffected. 2673275970ScyNote that all of these flags 2674275970Scycan be controlled remotely using the 2675285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2676275970Scyutility program. 2677275970Scy.RS 2678275970Scy.TP 7 2679275970Scy.NOP \f\*[B-Font]auth\f[] 2680275970ScyEnables the server to synchronize with unconfigured peers only if the 2681275970Scypeer has been correctly authenticated using either public key or 2682275970Scyprivate key cryptography. 2683275970ScyThe default for this flag is 2684275970Scy\f\*[B-Font]enable\f[]. 2685275970Scy.TP 7 2686275970Scy.NOP \f\*[B-Font]bclient\f[] 2687275970ScyEnables the server to listen for a message from a broadcast or 2688275970Scymulticast server, as in the 2689275970Scy\f\*[B-Font]multicastclient\f[] 2690275970Scycommand with default 2691275970Scyaddress. 2692275970ScyThe default for this flag is 2693275970Scy\f\*[B-Font]disable\f[]. 2694275970Scy.TP 7 2695275970Scy.NOP \f\*[B-Font]calibrate\f[] 2696275970ScyEnables the calibrate feature for reference clocks. 2697275970ScyThe default for 2698275970Scythis flag is 2699275970Scy\f\*[B-Font]disable\f[]. 2700275970Scy.TP 7 2701275970Scy.NOP \f\*[B-Font]kernel\f[] 2702275970ScyEnables the kernel time discipline, if available. 2703275970ScyThe default for this 2704275970Scyflag is 2705275970Scy\f\*[B-Font]enable\f[] 2706275970Scyif support is available, otherwise 2707275970Scy\f\*[B-Font]disable\f[]. 2708275970Scy.TP 7 2709275970Scy.NOP \f\*[B-Font]mode7\f[] 2710275970ScyEnables processing of NTP mode 7 implementation-specific requests 2711275970Scywhich are used by the deprecated 2712285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2713275970Scyprogram. 2714275970ScyThe default for this flag is disable. 2715275970ScyThis flag is excluded from runtime configuration using 2716285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[]. 2717275970ScyThe 2718285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 2719275970Scyprogram provides the same capabilities as 2720285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2721275970Scyusing standard mode 6 requests. 2722275970Scy.TP 7 2723275970Scy.NOP \f\*[B-Font]monitor\f[] 2724275970ScyEnables the monitoring facility. 2725275970ScySee the 2726285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2727275970Scyprogram 2728275970Scyand the 2729275970Scy\f\*[B-Font]monlist\f[] 2730275970Scycommand or further information. 2731275970ScyThe 2732275970Scydefault for this flag is 2733275970Scy\f\*[B-Font]enable\f[]. 2734275970Scy.TP 7 2735275970Scy.NOP \f\*[B-Font]ntp\f[] 2736275970ScyEnables time and frequency discipline. 2737275970ScyIn effect, this switch opens and 2738275970Scycloses the feedback loop, which is useful for testing. 2739275970ScyThe default for 2740275970Scythis flag is 2741275970Scy\f\*[B-Font]enable\f[]. 2742275970Scy.TP 7 2743301247Sdelphij.NOP \f\*[B-Font]peer_clear_digest_early\f[] 2744301247SdelphijBy default, if 2745301247Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2746301247Sdelphijis using autokey and it 2747301247Sdelphijreceives a crypto-NAK packet that 2748301247Sdelphijpasses the duplicate packet and origin timestamp checks 2749301247Sdelphijthe peer variables are immediately cleared. 2750301247SdelphijWhile this is generally a feature 2751301247Sdelphijas it allows for quick recovery if a server key has changed, 2752301247Sdelphija properly forged and appropriately delivered crypto-NAK packet 2753301247Sdelphijcan be used in a DoS attack. 2754301247SdelphijIf you have active noticable problems with this type of DoS attack 2755301247Sdelphijthen you should consider 2756301247Sdelphijdisabling this option. 2757301247SdelphijYou can check your 2758301247Sdelphij\f\*[B-Font]peerstats\f[] 2759301247Sdelphijfile for evidence of any of these attacks. 2760301247SdelphijThe 2761301247Sdelphijdefault for this flag is 2762301247Sdelphij\f\*[B-Font]enable\f[]. 2763301247Sdelphij.TP 7 2764275970Scy.NOP \f\*[B-Font]stats\f[] 2765275970ScyEnables the statistics facility. 2766275970ScySee the 2767275970Scy\fIMonitoring\f[] \fIOptions\f[] 2768275970Scysection for further information. 2769275970ScyThe default for this flag is 2770275970Scy\f\*[B-Font]disable\f[]. 2771294554Sdelphij.TP 7 2772294554Sdelphij.NOP \f\*[B-Font]unpeer_crypto_early\f[] 2773294554SdelphijBy default, if 2774294554Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2775294554Sdelphijreceives an autokey packet that fails TEST9, 2776294554Sdelphija crypto failure, 2777294554Sdelphijthe association is immediately cleared. 2778294554SdelphijThis is almost certainly a feature, 2779294554Sdelphijbut if, in spite of the current recommendation of not using autokey, 2780294554Sdelphijyou are 2781294554Sdelphij.B still 2782294554Sdelphijusing autokey 2783294554Sdelphij.B and 2784294554Sdelphijyou are seeing this sort of DoS attack 2785294554Sdelphijdisabling this flag will delay 2786294554Sdelphijtearing down the association until the reachability counter 2787294554Sdelphijbecomes zero. 2788294554SdelphijYou can check your 2789294554Sdelphij\f\*[B-Font]peerstats\f[] 2790294554Sdelphijfile for evidence of any of these attacks. 2791294554SdelphijThe 2792294554Sdelphijdefault for this flag is 2793294554Sdelphij\f\*[B-Font]enable\f[]. 2794294554Sdelphij.TP 7 2795294554Sdelphij.NOP \f\*[B-Font]unpeer_crypto_nak_early\f[] 2796294554SdelphijBy default, if 2797294554Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2798294554Sdelphijreceives a crypto-NAK packet that 2799294554Sdelphijpasses the duplicate packet and origin timestamp checks 2800294554Sdelphijthe association is immediately cleared. 2801294554SdelphijWhile this is generally a feature 2802294554Sdelphijas it allows for quick recovery if a server key has changed, 2803294554Sdelphija properly forged and appropriately delivered crypto-NAK packet 2804294554Sdelphijcan be used in a DoS attack. 2805294554SdelphijIf you have active noticable problems with this type of DoS attack 2806294554Sdelphijthen you should consider 2807294554Sdelphijdisabling this option. 2808294554SdelphijYou can check your 2809294554Sdelphij\f\*[B-Font]peerstats\f[] 2810294554Sdelphijfile for evidence of any of these attacks. 2811294554SdelphijThe 2812294554Sdelphijdefault for this flag is 2813294554Sdelphij\f\*[B-Font]enable\f[]. 2814294554Sdelphij.TP 7 2815294554Sdelphij.NOP \f\*[B-Font]unpeer_digest_early\f[] 2816294554SdelphijBy default, if 2817294554Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2818294554Sdelphijreceives what should be an authenticated packet 2819294554Sdelphijthat passes other packet sanity checks but 2820294554Sdelphijcontains an invalid digest 2821294554Sdelphijthe association is immediately cleared. 2822294554SdelphijWhile this is generally a feature 2823294554Sdelphijas it allows for quick recovery, 2824294554Sdelphijif this type of packet is carefully forged and sent 2825294554Sdelphijduring an appropriate window it can be used for a DoS attack. 2826294554SdelphijIf you have active noticable problems with this type of DoS attack 2827294554Sdelphijthen you should consider 2828294554Sdelphijdisabling this option. 2829294554SdelphijYou can check your 2830294554Sdelphij\f\*[B-Font]peerstats\f[] 2831294554Sdelphijfile for evidence of any of these attacks. 2832294554SdelphijThe 2833294554Sdelphijdefault for this flag is 2834294554Sdelphij\f\*[B-Font]enable\f[]. 2835275970Scy.RE 2836275970Scy.TP 7 2837275970Scy.NOP \f\*[B-Font]includefile\f[] \f\*[I-Font]includefile\f[] 2838275970ScyThis command allows additional configuration commands 2839275970Scyto be included from a separate file. 2840275970ScyInclude files may 2841275970Scybe nested to a depth of five; upon reaching the end of any 2842275970Scyinclude file, command processing resumes in the previous 2843275970Scyconfiguration file. 2844275970ScyThis option is useful for sites that run 2845285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2846275970Scyon multiple hosts, with (mostly) common options (e.g., a 2847275970Scyrestriction list). 2848275970Scy.TP 7 2849330106Sdelphij.NOP \f\*[B-Font]interface\f[] [\f\*[B-Font]listen\f[] | \f\*[B-Font]ignore\f[] | \f\*[B-Font]drop\f[]] [\f\*[B-Font]all\f[] | \f\*[B-Font]ipv4\f[] | \f\*[B-Font]ipv6\f[] | \f\*[B-Font]wildcard\f[] \f\*[I-Font]name\f[] | \f\*[I-Font]address\f[] [\f\*[B-Font]/\f[] \f\*[I-Font]prefixlen\f[]]] 2850330106SdelphijThe 2851330106Sdelphij\f\*[B-Font]interface\f[] 2852330106Sdelphijdirective controls which network addresses 2853330106Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2854330106Sdelphijopens, and whether input is dropped without processing. 2855330106SdelphijThe first parameter determines the action for addresses 2856330106Sdelphijwhich match the second parameter. 2857330106SdelphijThe second parameter specifies a class of addresses, 2858330106Sdelphijor a specific interface name, 2859330106Sdelphijor an address. 2860330106SdelphijIn the address case, 2861330106Sdelphij\f\*[I-Font]prefixlen\f[] 2862330106Sdelphijdetermines how many bits must match for this rule to apply. 2863330106Sdelphij\f\*[B-Font]ignore\f[] 2864330106Sdelphijprevents opening matching addresses, 2865330106Sdelphij\f\*[B-Font]drop\f[] 2866330106Sdelphijcauses 2867330106Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2868330106Sdelphijto open the address and drop all received packets without examination. 2869330106SdelphijMultiple 2870330106Sdelphij\f\*[B-Font]interface\f[] 2871330106Sdelphijdirectives can be used. 2872330106SdelphijThe last rule which matches a particular address determines the action for it. 2873330106Sdelphij\f\*[B-Font]interface\f[] 2874330106Sdelphijdirectives are disabled if any 2875330106Sdelphij\f\*[B-Font]\-I\f[], 2876330106Sdelphij\f\*[B-Font]\-\-interface\f[], 2877330106Sdelphij\f\*[B-Font]\-L\f[], 2878330106Sdelphijor 2879330106Sdelphij\f\*[B-Font]\-\-novirtualips\f[] 2880330106Sdelphijcommand-line options are specified in the configuration file, 2881330106Sdelphijall available network addresses are opened. 2882330106SdelphijThe 2883330106Sdelphij\f\*[B-Font]nic\f[] 2884330106Sdelphijdirective is an alias for 2885330106Sdelphij\f\*[B-Font]interface\f[]. 2886330106Sdelphij.TP 7 2887330106Sdelphij.NOP \f\*[B-Font]leapfile\f[] \f\*[I-Font]leapfile\f[] 2888330106SdelphijThis command loads the IERS leapseconds file and initializes the 2889330106Sdelphijleapsecond values for the next leapsecond event, leapfile expiration 2890330106Sdelphijtime, and TAI offset. 2891330106SdelphijThe file can be obtained directly from the IERS at 2892330106Sdelphij\f[C]https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list\f[] 2893330106Sdelphijor 2894330106Sdelphij\f[C]ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list\f[]. 2895330106SdelphijThe 2896330106Sdelphij\f\*[B-Font]leapfile\f[] 2897330106Sdelphijis scanned when 2898330106Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2899330106Sdelphijprocesses the 2900330106Sdelphij\f\*[B-Font]leapfile\f[] \f\*[B-Font]directive\f[] \f\*[B-Font]or\f[] \f\*[B-Font]when\f[] 2901330106Sdelphij\f\*[B-Font]ntpd\f[] \f\*[B-Font]detects\f[] \f\*[B-Font]that\f[] \f\*[B-Font]the\f[] 2902330106Sdelphij\f\*[I-Font]leapfile\f[] 2903330106Sdelphijhas changed. 2904330106Sdelphij\f\*[B-Font]ntpd\f[] 2905330106Sdelphijchecks once a day to see if the 2906330106Sdelphij\f\*[I-Font]leapfile\f[] 2907330106Sdelphijhas changed. 2908330106SdelphijThe 2909330106Sdelphij\fCupdate-leap\f[]\fR(1update_leapmdoc)\f[] 2910330106Sdelphijscript can be run to see if the 2911330106Sdelphij\f\*[I-Font]leapfile\f[] 2912330106Sdelphijshould be updated. 2913330106Sdelphij.TP 7 2914285169Scy.NOP \f\*[B-Font]leapsmearinterval\f[] \f\*[I-Font]seconds\f[] 2915285169ScyThis EXPERIMENTAL option is only available if 2916285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2917285169Scywas built with the 2918285169Scy\f\*[B-Font]\--enable-leap-smear\f[] 2919285169Scyoption to the 2920285169Scy\f\*[B-Font]configure\f[] 2921285169Scyscript. 2922285169ScyIt specifies the interval over which a leap second correction will be applied. 2923285169ScyRecommended values for this option are between 2924285169Scy7200 (2 hours) and 86400 (24 hours). 2925285169Scy.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2926285169ScySee http://bugs.ntp.org/2855 for more information. 2927285169Scy.TP 7 2928275970Scy.NOP \f\*[B-Font]logconfig\f[] \f\*[I-Font]configkeyword\f[] 2929275970ScyThis command controls the amount and type of output written to 2930275970Scythe system 2931285169Scy\fCsyslog\f[]\fR(3)\f[] 2932275970Scyfacility or the alternate 2933275970Scy\f\*[B-Font]logfile\f[] 2934275970Scylog file. 2935275970ScyBy default, all output is turned on. 2936275970ScyAll 2937275970Scy\f\*[I-Font]configkeyword\f[] 2938275970Scykeywords can be prefixed with 2939275970Scy\[oq]=\[cq], 2940275970Scy\[oq]+\[cq] 2941275970Scyand 2942275970Scy\[oq]\-\[cq], 2943275970Scywhere 2944275970Scy\[oq]=\[cq] 2945275970Scysets the 2946285169Scy\fCsyslog\f[]\fR(3)\f[] 2947275970Scypriority mask, 2948275970Scy\[oq]+\[cq] 2949275970Scyadds and 2950275970Scy\[oq]\-\[cq] 2951275970Scyremoves 2952275970Scymessages. 2953285169Scy\fCsyslog\f[]\fR(3)\f[] 2954275970Scymessages can be controlled in four 2955275970Scyclasses 2956275970Scy(\f\*[B-Font]clock\f[], \f\*[B-Font]peer\f[], \f\*[B-Font]sys\f[] and \f\*[B-Font]sync\f[]). 2957275970ScyWithin these classes four types of messages can be 2958275970Scycontrolled: informational messages 2959275970Scy(\f\*[B-Font]info\f[]), 2960275970Scyevent messages 2961275970Scy(\f\*[B-Font]events\f[]), 2962275970Scystatistics messages 2963275970Scy(\f\*[B-Font]statistics\f[]) 2964275970Scyand 2965275970Scystatus messages 2966275970Scy(\f\*[B-Font]status\f[]). 2967275970Scy.sp \n(Ppu 2968275970Scy.ne 2 2969275970Scy 2970275970ScyConfiguration keywords are formed by concatenating the message class with 2971275970Scythe event class. 2972275970ScyThe 2973275970Scy\f\*[B-Font]all\f[] 2974275970Scyprefix can be used instead of a message class. 2975275970ScyA 2976275970Scymessage class may also be followed by the 2977275970Scy\f\*[B-Font]all\f[] 2978275970Scykeyword to enable/disable all 2979298695Sdelphijmessages of the respective message class. 2980298695SdelphijThus, a minimal log configuration 2981275970Scycould look like this: 2982275970Scy.br 2983275970Scy.in +4 2984275970Scy.nf 2985275970Scylogconfig =syncstatus +sysevents 2986275970Scy.in -4 2987275970Scy.fi 2988275970Scy.sp \n(Ppu 2989275970Scy.ne 2 2990275970Scy 2991275970ScyThis would just list the synchronizations state of 2992285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2993275970Scyand the major system events. 2994275970ScyFor a simple reference server, the 2995275970Scyfollowing minimum message configuration could be useful: 2996275970Scy.br 2997275970Scy.in +4 2998275970Scy.nf 2999275970Scylogconfig =syncall +clockall 3000275970Scy.in -4 3001275970Scy.fi 3002275970Scy.sp \n(Ppu 3003275970Scy.ne 2 3004275970Scy 3005275970ScyThis configuration will list all clock information and 3006275970Scysynchronization information. 3007275970ScyAll other events and messages about 3008275970Scypeers, system events and so on is suppressed. 3009275970Scy.TP 7 3010275970Scy.NOP \f\*[B-Font]logfile\f[] \f\*[I-Font]logfile\f[] 3011275970ScyThis command specifies the location of an alternate log file to 3012275970Scybe used instead of the default system 3013285169Scy\fCsyslog\f[]\fR(3)\f[] 3014275970Scyfacility. 3015298695SdelphijThis is the same operation as the 3016298695Sdelphij\f\*[B-Font]\-l\f[] 3017298695Sdelphijcommand line option. 3018275970Scy.TP 7 3019330106Sdelphij.NOP \f\*[B-Font]mru\f[] [\f\*[B-Font]maxdepth\f[] \f\*[I-Font]count\f[] | \f\*[B-Font]maxmem\f[] \f\*[I-Font]kilobytes\f[] | \f\*[B-Font]mindepth\f[] \f\*[I-Font]count\f[] | \f\*[B-Font]maxage\f[] \f\*[I-Font]seconds\f[] | \f\*[B-Font]initialloc\f[] \f\*[I-Font]count\f[] | \f\*[B-Font]initmem\f[] \f\*[I-Font]kilobytes\f[] | \f\*[B-Font]incalloc\f[] \f\*[I-Font]count\f[] | \f\*[B-Font]incmem\f[] \f\*[I-Font]kilobytes\f[]] 3020330106SdelphijControls size limite of the monitoring facility's Most Recently Used 3021330106Sdelphij(MRU) list 3022330106Sdelphijof client addresses, which is also used by the 3023330106Sdelphijrate control facility. 3024330106Sdelphij.RS 3025330106Sdelphij.TP 7 3026330106Sdelphij.NOP \f\*[B-Font]maxdepth\f[] \f\*[I-Font]count\f[] 3027330106Sdelphij.TP 7 3028330106Sdelphij.NOP \f\*[B-Font]maxmem\f[] \f\*[I-Font]kilobytes\f[] 3029330106SdelphijEquivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. 3030330106SdelphijThe acutal limit will be up to 3031330106Sdelphij\f\*[B-Font]incalloc\f[] 3032330106Sdelphijentries or 3033330106Sdelphij\f\*[B-Font]incmem\f[] 3034330106Sdelphijkilobytes larger. 3035330106SdelphijAs with all of the 3036330106Sdelphij\f\*[B-Font]mru\f[] 3037330106Sdelphijoptions offered in units of entries or kilobytes, if both 3038330106Sdelphij\f\*[B-Font]maxdepth\f[] 3039330106Sdelphijand 3040330106Sdelphij\f\*[B-Font]maxmem\f[] \f\*[B-Font]are\f[] \f\*[B-Font]used,\f[] \f\*[B-Font]the\f[] \f\*[B-Font]last\f[] \f\*[B-Font]one\f[] \f\*[B-Font]used\f[] \f\*[B-Font]controls.\f[] 3041330106SdelphijThe default is 1024 kilobytes. 3042330106Sdelphij.TP 7 3043330106Sdelphij.NOP \f\*[B-Font]mindepth\f[] \f\*[I-Font]count\f[] 3044330106SdelphijLower limit on the MRU list size. 3045330106SdelphijWhen the MRU list has fewer than 3046330106Sdelphij\f\*[B-Font]mindepth\f[] 3047330106Sdelphijentries, existing entries are never removed to make room for newer ones, 3048330106Sdelphijregardless of their age. 3049330106SdelphijThe default is 600 entries. 3050330106Sdelphij.TP 7 3051330106Sdelphij.NOP \f\*[B-Font]maxage\f[] \f\*[I-Font]seconds\f[] 3052330106SdelphijOnce the MRU list has 3053330106Sdelphij\f\*[B-Font]mindepth\f[] 3054330106Sdelphijentries and an additional client is to ba added to the list, 3055330106Sdelphijif the oldest entry was updated more than 3056330106Sdelphij\f\*[B-Font]maxage\f[] 3057330106Sdelphijseconds ago, that entry is removed and its storage is reused. 3058330106SdelphijIf the oldest entry was updated more recently the MRU list is grown, 3059330106Sdelphijsubject to 3060330106Sdelphij\f\*[B-Font]maxdepth\f[] \f\*[B-Font]/\f[] \f\*[B-Font]moxmem\f[]. 3061330106SdelphijThe default is 64 seconds. 3062330106Sdelphij.TP 7 3063330106Sdelphij.NOP \f\*[B-Font]initalloc\f[] \f\*[I-Font]count\f[] 3064330106Sdelphij.TP 7 3065330106Sdelphij.NOP \f\*[B-Font]initmem\f[] \f\*[I-Font]kilobytes\f[] 3066330106SdelphijInitial memory allocation at the time the monitoringfacility is first enabled, 3067330106Sdelphijin terms of the number of entries or kilobytes. 3068330106SdelphijThe default is 4 kilobytes. 3069330106Sdelphij.TP 7 3070330106Sdelphij.NOP \f\*[B-Font]incalloc\f[] \f\*[I-Font]count\f[] 3071330106Sdelphij.TP 7 3072330106Sdelphij.NOP \f\*[B-Font]incmem\f[] \f\*[I-Font]kilobytes\f[] 3073330106SdelphijSize of additional memory allocations when growing the MRU list, in entries or kilobytes. 3074330106SdelphijThe default is 4 kilobytes. 3075330106Sdelphij.RE 3076330106Sdelphij.TP 7 3077330106Sdelphij.NOP \f\*[B-Font]nonvolatile\f[] \f\*[I-Font]threshold\f[] 3078330106SdelphijSpecify the 3079330106Sdelphij\f\*[I-Font]threshold\f[] 3080330106Sdelphijdelta in seconds before an hourly change to the 3081330106Sdelphij\f\*[B-Font]driftfile\f[] 3082330106Sdelphij(frequency file) will be written, with a default value of 1e-7 (0.1 PPM). 3083330106SdelphijThe frequency file is inspected each hour. 3084330106SdelphijIf the difference between the current frequency and the last value written 3085330106Sdelphijexceeds the threshold, the file is written and the 3086330106Sdelphij\f\*[B-Font]threshold\f[] 3087330106Sdelphijbecomes the new threshold value. 3088330106SdelphijIf the threshold is not exceeeded, it is reduced by half. 3089330106SdelphijThis is intended to reduce the number of file writes 3090330106Sdelphijfor embedded systems with nonvolatile memory. 3091330106Sdelphij.TP 7 3092330106Sdelphij.NOP \f\*[B-Font]phone\f[] \f\*[I-Font]dial\f[] \f\*[I-Font]...\f[] 3093330106SdelphijThis command is used in conjunction with 3094330106Sdelphijthe ACTS modem driver (type 18) 3095330106Sdelphijor the JJY driver (type 40, mode 100 \- 180). 3096330106SdelphijFor the ACTS modem driver (type 18), the arguments consist of 3097330106Sdelphija maximum of 10 telephone numbers used to dial USNO, NIST, or European 3098330106Sdelphijtime service. 3099330106SdelphijFor the JJY driver (type 40 mode 100 \- 180), the argument is 3100330106Sdelphijone telephone number used to dial the telephone JJY service. 3101330106SdelphijThe Hayes command ATDT is normally prepended to the number. 3102330106SdelphijThe number can contain other modem control codes as well. 3103330106Sdelphij.TP 7 3104358659Scy.NOP \f\*[B-Font]pollskewlist\f[] [\f\*[I-Font]poll\f[] \f\*[I-Font]value\f[] | \f\*[I-Font]value\f[]] \f\*[I-Font]...\f[] [\f\*[B-Font]default\f[] \f\*[I-Font]value\f[] | \f\*[I-Font]value\f[]] 3105358659ScyEnable skewing of our poll requests to our servers. 3106358659Scy\f\*[I-Font]poll\f[] 3107358659Scyis a number between 3 and 17 inclusive, identifying a specific poll interval. 3108358659ScyA poll interval is 2^n seconds in duration, 3109358659Scyso a poll value of 3 corresponds to 8 seconds 3110358659Scyand 3111358659Scya poll interval of 17 corresponds to 3112358659Scy131,072 seconds, or about a day and a half. 3113358659ScyThe next two numbers must be between 0 and one-half of the poll interval, 3114358659Scyinclusive. 3115358659ScyThe first number specifies how early the poll may start, 3116358659Scywhile 3117358659Scythe second number specifies how late the poll may be delayed. 3118358659ScyWith no arguments, internally specified default values are chosen. 3119358659Scy.TP 7 3120330106Sdelphij.NOP \f\*[B-Font]reset\f[] [\f\*[B-Font]allpeers\f[]] [\f\*[B-Font]auth\f[]] [\f\*[B-Font]ctl\f[]] [\f\*[B-Font]io\f[]] [\f\*[B-Font]mem\f[]] [\f\*[B-Font]sys\f[]] [\f\*[B-Font]timer\f[]] 3121330106SdelphijReset one or more groups of counters maintained by 3122330106Sdelphij\f\*[B-Font]ntpd\f[] 3123330106Sdelphijand exposed by 3124330106Sdelphij\f\*[B-Font]ntpq\f[] 3125330106Sdelphijand 3126330106Sdelphij\f\*[B-Font]ntpdc\f[]. 3127330106Sdelphij.TP 7 3128330106Sdelphij.NOP \f\*[B-Font]rlimit\f[] [\f\*[B-Font]memlock\f[] \f\*[I-Font]Nmegabytes\f[] | \f\*[B-Font]stacksize\f[] \f\*[I-Font]N4kPages\f[] \f\*[B-Font]filenum\f[] \f\*[I-Font]Nfiledescriptors\f[]] 3129330106Sdelphij.RS 3130330106Sdelphij.TP 7 3131330106Sdelphij.NOP \f\*[B-Font]memlock\f[] \f\*[I-Font]Nmegabytes\f[] 3132330106SdelphijSpecify the number of megabytes of memory that should be 3133330106Sdelphijallocated and locked. 3134330106SdelphijProbably only available under Linux, this option may be useful 3135330106Sdelphijwhen dropping root (the 3136330106Sdelphij\f\*[B-Font]\-i\f[] 3137330106Sdelphijoption). 3138330106SdelphijThe default is 32 megabytes on non-Linux machines, and \-1 under Linux. 3139330106Sdelphij-1 means "do not lock the process into memory". 3140330106Sdelphij0 means "lock whatever memory the process wants into memory". 3141330106Sdelphij.TP 7 3142330106Sdelphij.NOP \f\*[B-Font]stacksize\f[] \f\*[I-Font]N4kPages\f[] 3143330106SdelphijSpecifies the maximum size of the process stack on systems with the 3144330106Sdelphij\fBmlockall\f[]\fR()\f[] 3145330106Sdelphijfunction. 3146330106SdelphijDefaults to 50 4k pages (200 4k pages in OpenBSD). 3147330106Sdelphij.TP 7 3148330106Sdelphij.NOP \f\*[B-Font]filenum\f[] \f\*[I-Font]Nfiledescriptors\f[] 3149330106SdelphijSpecifies the maximum number of file descriptors ntpd may have open at once. 3150330106SdelphijDefaults to the system default. 3151330106Sdelphij.RE 3152330106Sdelphij.TP 7 3153330106Sdelphij.NOP \f\*[B-Font]saveconfigdir\f[] \f\*[I-Font]directory_path\f[] 3154330106SdelphijSpecify the directory in which to write configuration snapshots 3155330106Sdelphijrequested with 3156330106Sdelphij.Cm ntpq 's 3157330106Sdelphij\f\*[B-Font]saveconfig\f[] 3158330106Sdelphijcommand. 3159330106SdelphijIf 3160330106Sdelphij\f\*[B-Font]saveconfigdir\f[] 3161330106Sdelphijdoes not appear in the configuration file, 3162330106Sdelphij\f\*[B-Font]saveconfig\f[] 3163330106Sdelphijrequests are rejected by 3164330106Sdelphij\f\*[B-Font]ntpd\f[]. 3165330106Sdelphij.TP 7 3166330106Sdelphij.NOP \f\*[B-Font]saveconfig\f[] \f\*[I-Font]filename\f[] 3167330106SdelphijWrite the current configuration, including any runtime 3168330106Sdelphijmodifications given with 3169330106Sdelphij\f\*[B-Font]:config\f[] 3170330106Sdelphijor 3171330106Sdelphij\f\*[B-Font]config-from-file\f[] 3172330106Sdelphijto the 3173330106Sdelphij\f\*[B-Font]ntpd\f[] 3174330106Sdelphijhost's 3175330106Sdelphij\f\*[I-Font]filename\f[] 3176330106Sdelphijin the 3177330106Sdelphij\f\*[B-Font]saveconfigdir\f[]. 3178330106SdelphijThis command will be rejected unless the 3179330106Sdelphij\f\*[B-Font]saveconfigdir\f[] 3180330106Sdelphijdirective appears in 3181330106Sdelphij.Cm ntpd 's 3182330106Sdelphijconfiguration file. 3183330106Sdelphij\f\*[I-Font]filename\f[] 3184330106Sdelphijcan use 3185330106Sdelphij\fCstrftime\f[]\fR(3)\f[] 3186330106Sdelphijformat directives to substitute the current date and time, 3187330106Sdelphijfor example, 3188330106Sdelphij\f\*[B-Font]saveconfig\ ntp-%Y%m%d-%H%M%S.conf\f[]. 3189330106SdelphijThe filename used is stored in the system variable 3190330106Sdelphij\f\*[B-Font]savedconfig\f[]. 3191330106SdelphijAuthentication is required. 3192330106Sdelphij.TP 7 3193275970Scy.NOP \f\*[B-Font]setvar\f[] \f\*[I-Font]variable\f[] [\f\*[B-Font]default\f[]] 3194275970ScyThis command adds an additional system variable. 3195275970ScyThese 3196275970Scyvariables can be used to distribute additional information such as 3197275970Scythe access policy. 3198275970ScyIf the variable of the form 3199275970Scy\fIname\f[]\fI=\f[]\f\*[I-Font]value\f[] 3200275970Scyis followed by the 3201275970Scy\f\*[B-Font]default\f[] 3202275970Scykeyword, the 3203275970Scyvariable will be listed as part of the default system variables 3204285169Scy(\fCntpq\f[]\fR(@NTPQ_MS@)\f[] \f\*[B-Font]rv\f[] command)). 3205275970ScyThese additional variables serve 3206275970Scyinformational purposes only. 3207275970ScyThey are not related to the protocol 3208275970Scyother that they can be listed. 3209275970ScyThe known protocol variables will 3210275970Scyalways override any variables defined via the 3211275970Scy\f\*[B-Font]setvar\f[] 3212275970Scymechanism. 3213275970ScyThere are three special variables that contain the names 3214275970Scyof all variable of the same group. 3215275970ScyThe 3216275970Scy\fIsys_var_list\f[] 3217275970Scyholds 3218275970Scythe names of all system variables. 3219275970ScyThe 3220275970Scy\fIpeer_var_list\f[] 3221275970Scyholds 3222275970Scythe names of all peer variables and the 3223275970Scy\fIclock_var_list\f[] 3224275970Scyholds the names of the reference clock variables. 3225275970Scy.TP 7 3226330106Sdelphij.NOP \f\*[B-Font]sysinfo\f[] 3227330106SdelphijDisplay operational summary. 3228330106Sdelphij.TP 7 3229330106Sdelphij.NOP \f\*[B-Font]sysstats\f[] 3230330106SdelphijShow statistics counters maintained in the protocol module. 3231330106Sdelphij.TP 7 3232282408Scy.NOP \f\*[B-Font]tinker\f[] [\f\*[B-Font]allan\f[] \f\*[I-Font]allan\f[] | \f\*[B-Font]dispersion\f[] \f\*[I-Font]dispersion\f[] | \f\*[B-Font]freq\f[] \f\*[I-Font]freq\f[] | \f\*[B-Font]huffpuff\f[] \f\*[I-Font]huffpuff\f[] | \f\*[B-Font]panic\f[] \f\*[I-Font]panic\f[] | \f\*[B-Font]step\f[] \f\*[I-Font]step\f[] | \f\*[B-Font]stepback\f[] \f\*[I-Font]stepback\f[] | \f\*[B-Font]stepfwd\f[] \f\*[I-Font]stepfwd\f[] | \f\*[B-Font]stepout\f[] \f\*[I-Font]stepout\f[]] 3233275970ScyThis command can be used to alter several system variables in 3234275970Scyvery exceptional circumstances. 3235275970ScyIt should occur in the 3236275970Scyconfiguration file before any other configuration options. 3237275970ScyThe 3238275970Scydefault values of these variables have been carefully optimized for 3239275970Scya wide range of network speeds and reliability expectations. 3240275970ScyIn 3241275970Scygeneral, they interact in intricate ways that are hard to predict 3242275970Scyand some combinations can result in some very nasty behavior. 3243275970ScyVery 3244275970Scyrarely is it necessary to change the default values; but, some 3245275970Scyfolks cannot resist twisting the knobs anyway and this command is 3246275970Scyfor them. 3247275970ScyEmphasis added: twisters are on their own and can expect 3248275970Scyno help from the support group. 3249275970Scy.sp \n(Ppu 3250275970Scy.ne 2 3251275970Scy 3252275970ScyThe variables operate as follows: 3253275970Scy.RS 3254275970Scy.TP 7 3255275970Scy.NOP \f\*[B-Font]allan\f[] \f\*[I-Font]allan\f[] 3256275970ScyThe argument becomes the new value for the minimum Allan 3257275970Scyintercept, which is a parameter of the PLL/FLL clock discipline 3258275970Scyalgorithm. 3259275970ScyThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 3260275970Scylimit. 3261275970Scy.TP 7 3262275970Scy.NOP \f\*[B-Font]dispersion\f[] \f\*[I-Font]dispersion\f[] 3263275970ScyThe argument becomes the new value for the dispersion increase rate, 3264275970Scynormally .000015 s/s. 3265275970Scy.TP 7 3266275970Scy.NOP \f\*[B-Font]freq\f[] \f\*[I-Font]freq\f[] 3267275970ScyThe argument becomes the initial value of the frequency offset in 3268275970Scyparts-per-million. 3269275970ScyThis overrides the value in the frequency file, if 3270275970Scypresent, and avoids the initial training state if it is not. 3271275970Scy.TP 7 3272275970Scy.NOP \f\*[B-Font]huffpuff\f[] \f\*[I-Font]huffpuff\f[] 3273275970ScyThe argument becomes the new value for the experimental 3274275970Scyhuff-n'-puff filter span, which determines the most recent interval 3275275970Scythe algorithm will search for a minimum delay. 3276275970ScyThe lower limit is 3277275970Scy900 s (15 m), but a more reasonable value is 7200 (2 hours). 3278275970ScyThere 3279275970Scyis no default, since the filter is not enabled unless this command 3280275970Scyis given. 3281275970Scy.TP 7 3282275970Scy.NOP \f\*[B-Font]panic\f[] \f\*[I-Font]panic\f[] 3283275970ScyThe argument is the panic threshold, normally 1000 s. 3284275970ScyIf set to zero, 3285275970Scythe panic sanity check is disabled and a clock offset of any value will 3286275970Scybe accepted. 3287275970Scy.TP 7 3288275970Scy.NOP \f\*[B-Font]step\f[] \f\*[I-Font]step\f[] 3289275970ScyThe argument is the step threshold, which by default is 0.128 s. 3290275970ScyIt can 3291275970Scybe set to any positive number in seconds. 3292275970ScyIf set to zero, step 3293275970Scyadjustments will never occur. 3294275970ScyNote: The kernel time discipline is 3295275970Scydisabled if the step threshold is set to zero or greater than the 3296275970Scydefault. 3297275970Scy.TP 7 3298282408Scy.NOP \f\*[B-Font]stepback\f[] \f\*[I-Font]stepback\f[] 3299282408ScyThe argument is the step threshold for the backward direction, 3300282408Scywhich by default is 0.128 s. 3301282408ScyIt can 3302282408Scybe set to any positive number in seconds. 3303282408ScyIf both the forward and backward step thresholds are set to zero, step 3304282408Scyadjustments will never occur. 3305282408ScyNote: The kernel time discipline is 3306282408Scydisabled if 3307282408Scyeach direction of step threshold are either 3308282408Scyset to zero or greater than .5 second. 3309282408Scy.TP 7 3310282408Scy.NOP \f\*[B-Font]stepfwd\f[] \f\*[I-Font]stepfwd\f[] 3311282408ScyAs for stepback, but for the forward direction. 3312282408Scy.TP 7 3313275970Scy.NOP \f\*[B-Font]stepout\f[] \f\*[I-Font]stepout\f[] 3314275970ScyThe argument is the stepout timeout, which by default is 900 s. 3315275970ScyIt can 3316275970Scybe set to any positive number in seconds. 3317275970ScyIf set to zero, the stepout 3318275970Scypulses will not be suppressed. 3319275970Scy.RE 3320275970Scy.TP 7 3321330106Sdelphij.NOP \f\*[B-Font]writevar\f[] \f\*[I-Font]assocID\ name\f[] \f\*[I-Font]=\f[] \f\*[I-Font]value\f[] \f\*[I-Font][,...]\f[] 3322330106SdelphijWrite (create or update) the specified variables. 3323330106SdelphijIf the 3324330106Sdelphij\f\*[B-Font]assocID\f[] 3325330106Sdelphijis zero, the variablea re from the 3326330106Sdelphijsystem variables 3327330106Sdelphijname space, otherwise they are from the 3328330106Sdelphijpeer variables 3329330106Sdelphijname space. 3330330106SdelphijThe 3331330106Sdelphij\f\*[B-Font]assocID\f[] 3332330106Sdelphijis required, as the same name can occur in both name spaces. 3333275970Scy.TP 7 3334275970Scy.NOP \f\*[B-Font]trap\f[] \f\*[I-Font]host_address\f[] [\f\*[B-Font]port\f[] \f\*[I-Font]port_number\f[]] [\f\*[B-Font]interface\f[] \f\*[I-Font]interface_address\f[]] 3335275970ScyThis command configures a trap receiver at the given host 3336275970Scyaddress and port number for sending messages with the specified 3337275970Scylocal interface address. 3338275970ScyIf the port number is unspecified, a value 3339275970Scyof 18447 is used. 3340275970ScyIf the interface address is not specified, the 3341275970Scymessage is sent with a source address of the local interface the 3342275970Scymessage is sent through. 3343275970ScyNote that on a multihomed host the 3344275970Scyinterface used may vary from time to time with routing changes. 3345330106Sdelphij.TP 7 3346330106Sdelphij.NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]hop\f[] \f\*[I-Font]...\f[] 3347330106SdelphijThis command specifies a list of TTL values in increasing order. 3348330106SdelphijUp to 8 values can be specified. 3349330106SdelphijIn 3350330106Sdelphij\f\*[B-Font]manycast\f[] 3351330106Sdelphijmode these values are used in-turn in an expanding-ring search. 3352330106SdelphijThe default is eight multiples of 32 starting at 31. 3353275970Scy.sp \n(Ppu 3354275970Scy.ne 2 3355275970Scy 3356275970ScyThe trap receiver will generally log event messages and other 3357275970Scyinformation from the server in a log file. 3358275970ScyWhile such monitor 3359275970Scyprograms may also request their own trap dynamically, configuring a 3360275970Scytrap receiver will ensure that no messages are lost when the server 3361275970Scyis started. 3362275970Scy.TP 7 3363275970Scy.NOP \f\*[B-Font]hop\f[] \f\*[I-Font]...\f[] 3364275970ScyThis command specifies a list of TTL values in increasing order, up to 8 3365275970Scyvalues can be specified. 3366275970ScyIn manycast mode these values are used in turn in 3367275970Scyan expanding-ring search. 3368275970ScyThe default is eight multiples of 32 starting at 3369275970Scy31. 3370330106Sdelphij.PP 3371275970Scy.SH "OPTIONS" 3372275970Scy.TP 3373275970Scy.NOP \f\*[B-Font]\-\-help\f[] 3374275970ScyDisplay usage information and exit. 3375275970Scy.TP 3376275970Scy.NOP \f\*[B-Font]\-\-more-help\f[] 3377275970ScyPass the extended usage information through a pager. 3378275970Scy.TP 3379275970Scy.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 3380275970ScyOutput version of program and exit. The default mode is `v', a simple 3381275970Scyversion. The `c' mode will print copyright information and `n' will 3382275970Scyprint the full copyright notice. 3383330106Sdelphij.PP 3384275970Scy.SH "OPTION PRESETS" 3385275970ScyAny option that is not marked as \fInot presettable\fP may be preset 3386275970Scyby loading values from environment variables named: 3387275970Scy.nf 3388275970Scy \fBNTP_CONF_<option-name>\fP or \fBNTP_CONF\fP 3389275970Scy.fi 3390275970Scy.ad 3391275970Scy.SH "ENVIRONMENT" 3392275970ScySee \fBOPTION PRESETS\fP for configuration environment variables. 3393275970Scy.SH FILES 3394275970Scy.TP 15 3395275970Scy.NOP \fI/etc/ntp.conf\f[] 3396275970Scythe default name of the configuration file 3397275970Scy.br 3398275970Scy.ns 3399275970Scy.TP 15 3400275970Scy.NOP \fIntp.keys\f[] 3401275970Scyprivate MD5 keys 3402275970Scy.br 3403275970Scy.ns 3404275970Scy.TP 15 3405275970Scy.NOP \fIntpkey\f[] 3406275970ScyRSA private key 3407275970Scy.br 3408275970Scy.ns 3409275970Scy.TP 15 3410275970Scy.NOP \fIntpkey_\f[]\f\*[I-Font]host\f[] 3411275970ScyRSA public key 3412275970Scy.br 3413275970Scy.ns 3414275970Scy.TP 15 3415275970Scy.NOP \fIntp_dh\f[] 3416275970ScyDiffie-Hellman agreement parameters 3417330106Sdelphij.PP 3418275970Scy.SH "EXIT STATUS" 3419275970ScyOne of the following exit values will be returned: 3420275970Scy.TP 3421275970Scy.NOP 0 " (EXIT_SUCCESS)" 3422275970ScySuccessful program execution. 3423275970Scy.TP 3424275970Scy.NOP 1 " (EXIT_FAILURE)" 3425275970ScyThe operation failed or the command syntax was not valid. 3426275970Scy.TP 3427275970Scy.NOP 70 " (EX_SOFTWARE)" 3428275970Scylibopts had an internal operational error. Please report 3429275970Scyit to autogen-users@lists.sourceforge.net. Thank you. 3430330106Sdelphij.PP 3431275970Scy.SH "SEE ALSO" 3432285169Scy\fCntpd\f[]\fR(@NTPD_MS@)\f[], 3433285169Scy\fCntpdc\f[]\fR(@NTPDC_MS@)\f[], 3434285169Scy\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 3435275970Scy.sp \n(Ppu 3436275970Scy.ne 2 3437275970Scy 3438275970ScyIn addition to the manual pages provided, 3439275970Scycomprehensive documentation is available on the world wide web 3440275970Scyat 3441275970Scy\f[C]http://www.ntp.org/\f[]. 3442275970ScyA snapshot of this documentation is available in HTML format in 3443275970Scy\fI/usr/share/doc/ntp\f[]. 3444275970ScyDavid L. Mills, 3445275970Scy\fINetwork Time Protocol (Version 4)\fR, 3446275970ScyRFC5905 3447275970Scy.PP 3448275970Scy 3449275970Scy.SH "AUTHORS" 3450280849ScyThe University of Delaware and Network Time Foundation 3451275970Scy.SH "COPYRIGHT" 3452358659ScyCopyright (C) 1992-2020 The University of Delaware and Network Time Foundation all rights reserved. 3453275970ScyThis program is released under the terms of the NTP license, <http://ntp.org/license>. 3454275970Scy.SH BUGS 3455275970ScyThe syntax checking is not picky; some combinations of 3456275970Scyridiculous and even hilarious options and modes may not be 3457275970Scydetected. 3458275970Scy.sp \n(Ppu 3459275970Scy.ne 2 3460275970Scy 3461275970ScyThe 3462275970Scy\fIntpkey_\f[]\f\*[I-Font]host\f[] 3463275970Scyfiles are really digital 3464275970Scycertificates. 3465275970ScyThese should be obtained via secure directory 3466275970Scyservices when they become universally available. 3467275970Scy.sp \n(Ppu 3468275970Scy.ne 2 3469275970Scy 3470275970ScyPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 3471275970Scy.SH NOTES 3472275970ScyThis document was derived from FreeBSD. 3473275970Scy.sp \n(Ppu 3474275970Scy.ne 2 3475275970Scy 3476275970ScyThis manual page was \fIAutoGen\fP-erated from the \fBntp.conf\fP 3477275970Scyoption definitions. 3478