ntp.conf.man.in revision 298770
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 13298770Sdelphij.TH ntp.conf 5 "26 Apr 2016" "4.2.8p7" "File Formats" 14275970Scy.\" 15298770Sdelphij.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-ana4jE/ag-QnaWiE) 16275970Scy.\" 17298770Sdelphij.\" It has been AutoGen-ed April 26, 2016 at 08:28:14 PM 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 38285612Sdelphij\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. 136298770SdelphijIn a few cases, including the 137298770Sdelphij\f\*[B-Font]reslist\f[] 138298770Sdelphijbillboard generated 139298770Sdelphijby 140298770Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 141298770Sdelphijor 142298770Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[], 143298770SdelphijIPv6 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 164275970Scy.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[]] 165275970Scy.TP 7 166298770Sdelphij.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[]] 167275970Scy.TP 7 168298770Sdelphij.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 170298770Sdelphij.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 298298770Sdelphijcan be changed with the 299298770Sdelphij\f\*[B-Font]calldelay\f[] 300298770Sdelphijcommand 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 312298770Sdelphijchanged with the 313298770Sdelphij\f\*[B-Font]calldelay\f[] 314298770Sdelphijcommand 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 320285612Sdelphij\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[] 329275970Scyidentifier with values from 1 to 65534, 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 352298770Sdelphij.NOP \f\*[B-Font]preempt\f[] 353298770SdelphijSays the association can be preempted. 354298770Sdelphij.TP 7 355298770Sdelphij.NOP \f\*[B-Font]true\f[] 356298770SdelphijMarks the server as a truechimer. 357298770SdelphijUse this option only for testing. 358298770Sdelphij.TP 7 359275970Scy.NOP \f\*[B-Font]prefer\f[] 360275970ScyMarks the server as preferred. 361275970ScyAll other things being equal, 362275970Scythis host will be chosen for synchronization among a set of 363275970Scycorrectly operating hosts. 364275970ScySee the 365275970Scy"Mitigation Rules and the prefer Keyword" 366275970Scypage 367275970Scy(available as part of the HTML documentation 368275970Scyprovided in 369275970Scy\fI/usr/share/doc/ntp\f[]) 370275970Scyfor further information. 371275970Scy.TP 7 372298770Sdelphij.NOP \f\*[B-Font]true\f[] 373298770SdelphijForces the association to always survive the selection and clustering algorithms. 374298770SdelphijThis option should almost certainly 375298770Sdelphij\fIonly\f[] 376298770Sdelphijbe used while testing an association. 377298770Sdelphij.TP 7 378275970Scy.NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]ttl\f[] 379275970ScyThis option is used only with broadcast server and manycast 380275970Scyclient modes. 381275970ScyIt specifies the time-to-live 382275970Scy\f\*[I-Font]ttl\f[] 383275970Scyto 384275970Scyuse on broadcast server and multicast server and the maximum 385275970Scy\f\*[I-Font]ttl\f[] 386275970Scyfor the expanding ring search with manycast 387275970Scyclient packets. 388275970ScySelection of the proper value, which defaults to 389275970Scy127, is something of a black art and should be coordinated with the 390275970Scynetwork administrator. 391275970Scy.TP 7 392275970Scy.NOP \f\*[B-Font]version\f[] \f\*[I-Font]version\f[] 393275970ScySpecifies the version number to be used for outgoing NTP 394275970Scypackets. 395275970ScyVersions 1-4 are the choices, with version 4 the 396275970Scydefault. 397298770Sdelphij.TP 7 398298770Sdelphij.NOP \f\*[B-Font]xleave\f[] 399298770SdelphijValid in 400298770Sdelphij\f\*[B-Font]peer\f[] 401298770Sdelphijand 402298770Sdelphij\f\*[B-Font]broadcast\f[] 403298770Sdelphijmodes only, this flag enables interleave mode. 404275970Scy.PP 405275970Scy.SS Auxiliary Commands 406275970Scy.TP 7 407275970Scy.NOP \f\*[B-Font]broadcastclient\f[] 408275970ScyThis command enables reception of broadcast server messages to 409275970Scyany local interface (type b) address. 410275970ScyUpon receiving a message for 411275970Scythe first time, the broadcast client measures the nominal server 412275970Scypropagation delay using a brief client/server exchange with the 413275970Scyserver, then enters the broadcast client mode, in which it 414275970Scysynchronizes to succeeding broadcast messages. 415275970ScyNote that, in order 416275970Scyto avoid accidental or malicious disruption in this mode, both the 417275970Scyserver and client should operate using symmetric-key or public-key 418275970Scyauthentication as described in 419275970Scy\fIAuthentication\f[] \fIOptions\f[]. 420275970Scy.TP 7 421275970Scy.NOP \f\*[B-Font]manycastserver\f[] \f\*[I-Font]address\f[] \f\*[I-Font]...\f[] 422275970ScyThis command enables reception of manycast client messages to 423275970Scythe multicast group address(es) (type m) specified. 424275970ScyAt least one 425275970Scyaddress is required, but the NTP multicast address 224.0.1.1 426275970Scyassigned by the IANA should NOT be used, unless specific means are 427275970Scytaken to limit the span of the reply and avoid a possibly massive 428275970Scyimplosion at the original sender. 429275970ScyNote that, in order to avoid 430275970Scyaccidental or malicious disruption in this mode, both the server 431275970Scyand client should operate using symmetric-key or public-key 432275970Scyauthentication as described in 433275970Scy\fIAuthentication\f[] \fIOptions\f[]. 434275970Scy.TP 7 435275970Scy.NOP \f\*[B-Font]multicastclient\f[] \f\*[I-Font]address\f[] \f\*[I-Font]...\f[] 436275970ScyThis command enables reception of multicast server messages to 437275970Scythe multicast group address(es) (type m) specified. 438275970ScyUpon receiving 439275970Scya message for the first time, the multicast client measures the 440275970Scynominal server propagation delay using a brief client/server 441275970Scyexchange with the server, then enters the broadcast client mode, in 442275970Scywhich it synchronizes to succeeding multicast messages. 443275970ScyNote that, 444275970Scyin order to avoid accidental or malicious disruption in this mode, 445275970Scyboth the server and client should operate using symmetric-key or 446275970Scypublic-key authentication as described in 447275970Scy\fIAuthentication\f[] \fIOptions\f[]. 448280849Scy.TP 7 449280849Scy.NOP \f\*[B-Font]mdnstries\f[] \f\*[I-Font]number\f[] 450280849ScyIf we are participating in mDNS, 451280849Scyafter we have synched for the first time 452280849Scywe attempt to register with the mDNS system. 453280849ScyIf that registration attempt fails, 454280849Scywe try again at one minute intervals for up to 455280849Scy\f\*[B-Font]mdnstries\f[] 456280849Scytimes. 457280849ScyAfter all, 458280849Scy\f\*[B-Font]ntpd\f[] 459280849Scymay be starting before mDNS. 460280849ScyThe default value for 461280849Scy\f\*[B-Font]mdnstries\f[] 462280849Scyis 5. 463275970Scy.PP 464275970Scy.SH Authentication Support 465275970ScyAuthentication support allows the NTP client to verify that the 466275970Scyserver is in fact known and trusted and not an intruder intending 467275970Scyaccidentally or on purpose to masquerade as that server. 468275970ScyThe NTPv3 469275970Scyspecification RFC-1305 defines a scheme which provides 470275970Scycryptographic authentication of received NTP packets. 471275970ScyOriginally, 472275970Scythis was done using the Data Encryption Standard (DES) algorithm 473275970Scyoperating in Cipher Block Chaining (CBC) mode, commonly called 474275970ScyDES-CBC. 475275970ScySubsequently, this was replaced by the RSA Message Digest 476275970Scy5 (MD5) algorithm using a private key, commonly called keyed-MD5. 477275970ScyEither algorithm computes a message digest, or one-way hash, which 478275970Scycan be used to verify the server has the correct private key and 479275970Scykey identifier. 480275970Scy.sp \n(Ppu 481275970Scy.ne 2 482275970Scy 483275970ScyNTPv4 retains the NTPv3 scheme, properly described as symmetric key 484275970Scycryptography and, in addition, provides a new Autokey scheme 485275970Scybased on public key cryptography. 486275970ScyPublic key cryptography is generally considered more secure 487275970Scythan symmetric key cryptography, since the security is based 488275970Scyon a private value which is generated by each server and 489275970Scynever revealed. 490275970ScyWith Autokey all key distribution and 491275970Scymanagement functions involve only public values, which 492275970Scyconsiderably simplifies key distribution and storage. 493275970ScyPublic key management is based on X.509 certificates, 494275970Scywhich can be provided by commercial services or 495275970Scyproduced by utility programs in the OpenSSL software library 496275970Scyor the NTPv4 distribution. 497275970Scy.sp \n(Ppu 498275970Scy.ne 2 499275970Scy 500275970ScyWhile the algorithms for symmetric key cryptography are 501275970Scyincluded in the NTPv4 distribution, public key cryptography 502275970Scyrequires the OpenSSL software library to be installed 503275970Scybefore building the NTP distribution. 504275970ScyDirections for doing that 505275970Scyare on the Building and Installing the Distribution page. 506275970Scy.sp \n(Ppu 507275970Scy.ne 2 508275970Scy 509275970ScyAuthentication is configured separately for each association 510275970Scyusing the 511275970Scy\f\*[B-Font]key\f[] 512275970Scyor 513275970Scy\f\*[B-Font]autokey\f[] 514275970Scysubcommand on the 515275970Scy\f\*[B-Font]peer\f[], 516275970Scy\f\*[B-Font]server\f[], 517275970Scy\f\*[B-Font]broadcast\f[] 518275970Scyand 519275970Scy\f\*[B-Font]manycastclient\f[] 520275970Scyconfiguration commands as described in 521275970Scy\fIConfiguration\f[] \fIOptions\f[] 522275970Scypage. 523275970ScyThe authentication 524275970Scyoptions described below specify the locations of the key files, 525275970Scyif other than default, which symmetric keys are trusted 526275970Scyand the interval between various operations, if other than default. 527275970Scy.sp \n(Ppu 528275970Scy.ne 2 529275970Scy 530275970ScyAuthentication is always enabled, 531275970Scyalthough ineffective if not configured as 532275970Scydescribed below. 533275970ScyIf a NTP packet arrives 534275970Scyincluding a message authentication 535275970Scycode (MAC), it is accepted only if it 536275970Scypasses all cryptographic checks. 537275970ScyThe 538275970Scychecks require correct key ID, key value 539275970Scyand message digest. 540275970ScyIf the packet has 541275970Scybeen modified in any way or replayed 542275970Scyby an intruder, it will fail one or more 543275970Scyof these checks and be discarded. 544275970ScyFurthermore, the Autokey scheme requires a 545275970Scypreliminary protocol exchange to obtain 546275970Scythe server certificate, verify its 547275970Scycredentials and initialize the protocol 548275970Scy.sp \n(Ppu 549275970Scy.ne 2 550275970Scy 551275970ScyThe 552275970Scy\f\*[B-Font]auth\f[] 553275970Scyflag controls whether new associations or 554275970Scyremote configuration commands require cryptographic authentication. 555275970ScyThis flag can be set or reset by the 556275970Scy\f\*[B-Font]enable\f[] 557275970Scyand 558275970Scy\f\*[B-Font]disable\f[] 559275970Scycommands and also by remote 560275970Scyconfiguration commands sent by a 561285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 562298770Sdelphijprogram running on 563275970Scyanother machine. 564275970ScyIf this flag is enabled, which is the default 565275970Scycase, new broadcast client and symmetric passive associations and 566275970Scyremote configuration commands must be cryptographically 567275970Scyauthenticated using either symmetric key or public key cryptography. 568275970ScyIf this 569275970Scyflag is disabled, these operations are effective 570275970Scyeven if not cryptographic 571275970Scyauthenticated. 572275970ScyIt should be understood 573275970Scythat operating with the 574275970Scy\f\*[B-Font]auth\f[] 575275970Scyflag disabled invites a significant vulnerability 576275970Scywhere a rogue hacker can 577275970Scymasquerade as a falseticker and seriously 578275970Scydisrupt system timekeeping. 579275970ScyIt is 580275970Scyimportant to note that this flag has no purpose 581275970Scyother than to allow or disallow 582275970Scya new association in response to new broadcast 583275970Scyand symmetric active messages 584275970Scyand remote configuration commands and, in particular, 585275970Scythe flag has no effect on 586275970Scythe authentication process itself. 587275970Scy.sp \n(Ppu 588275970Scy.ne 2 589275970Scy 590275970ScyAn attractive alternative where multicast support is available 591275970Scyis manycast mode, in which clients periodically troll 592275970Scyfor servers as described in the 593275970Scy\fIAutomatic\f[] \fINTP\f[] \fIConfiguration\f[] \fIOptions\f[] 594275970Scypage. 595275970ScyEither symmetric key or public key 596275970Scycryptographic authentication can be used in this mode. 597275970ScyThe principle advantage 598275970Scyof manycast mode is that potential servers need not be 599275970Scyconfigured in advance, 600275970Scysince the client finds them during regular operation, 601275970Scyand the configuration 602275970Scyfiles for all clients can be identical. 603275970Scy.sp \n(Ppu 604275970Scy.ne 2 605275970Scy 606275970ScyThe security model and protocol schemes for 607275970Scyboth symmetric key and public key 608275970Scycryptography are summarized below; 609275970Scyfurther details are in the briefings, papers 610275970Scyand reports at the NTP project page linked from 611275970Scy\f[C]http://www.ntp.org/\f[]. 612275970Scy.SS Symmetric-Key Cryptography 613275970ScyThe original RFC-1305 specification allows any one of possibly 614275970Scy65,534 keys, each distinguished by a 32-bit key identifier, to 615275970Scyauthenticate an association. 616275970ScyThe servers and clients involved must 617275970Scyagree on the key and key identifier to 618275970Scyauthenticate NTP packets. 619275970ScyKeys and 620275970Scyrelated information are specified in a key 621275970Scyfile, usually called 622275970Scy\fIntp.keys\f[], 623275970Scywhich must be distributed and stored using 624275970Scysecure means beyond the scope of the NTP protocol itself. 625275970ScyBesides the keys used 626275970Scyfor ordinary NTP associations, 627275970Scyadditional keys can be used as passwords for the 628285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 629275970Scyand 630285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 631275970Scyutility programs. 632275970Scy.sp \n(Ppu 633275970Scy.ne 2 634275970Scy 635275970ScyWhen 636285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 637275970Scyis first started, it reads the key file specified in the 638275970Scy\f\*[B-Font]keys\f[] 639275970Scyconfiguration command and installs the keys 640275970Scyin the key cache. 641275970ScyHowever, 642275970Scyindividual keys must be activated with the 643275970Scy\f\*[B-Font]trusted\f[] 644275970Scycommand before use. 645275970ScyThis 646275970Scyallows, for instance, the installation of possibly 647275970Scyseveral batches of keys and 648275970Scythen activating or deactivating each batch 649275970Scyremotely using 650285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[]. 651275970ScyThis also provides a revocation capability that can be used 652275970Scyif a key becomes compromised. 653275970ScyThe 654275970Scy\f\*[B-Font]requestkey\f[] 655275970Scycommand selects the key used as the password for the 656285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 657275970Scyutility, while the 658275970Scy\f\*[B-Font]controlkey\f[] 659275970Scycommand selects the key used as the password for the 660285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 661275970Scyutility. 662275970Scy.SS Public Key Cryptography 663275970ScyNTPv4 supports the original NTPv3 symmetric key scheme 664275970Scydescribed in RFC-1305 and in addition the Autokey protocol, 665275970Scywhich is based on public key cryptography. 666275970ScyThe Autokey Version 2 protocol described on the Autokey Protocol 667275970Scypage verifies packet integrity using MD5 message digests 668275970Scyand verifies the source with digital signatures and any of several 669275970Scydigest/signature schemes. 670275970ScyOptional identity schemes described on the Identity Schemes 671275970Scypage and based on cryptographic challenge/response algorithms 672275970Scyare also available. 673275970ScyUsing all of these schemes provides strong security against 674275970Scyreplay with or without modification, spoofing, masquerade 675275970Scyand most forms of clogging attacks. 676275970Scy.\" .Pp 677275970Scy.\" The cryptographic means necessary for all Autokey operations 678275970Scy.\" is provided by the OpenSSL software library. 679275970Scy.\" This library is available from http://www.openssl.org/ 680275970Scy.\" and can be installed using the procedures outlined 681275970Scy.\" in the Building and Installing the Distribution page. 682275970Scy.\" Once installed, 683275970Scy.\" the configure and build 684275970Scy.\" process automatically detects the library and links 685275970Scy.\" the library routines required. 686275970Scy.sp \n(Ppu 687275970Scy.ne 2 688275970Scy 689275970ScyThe Autokey protocol has several modes of operation 690275970Scycorresponding to the various NTP modes supported. 691275970ScyMost modes use a special cookie which can be 692275970Scycomputed independently by the client and server, 693275970Scybut encrypted in transmission. 694275970ScyAll modes use in addition a variant of the S-KEY scheme, 695275970Scyin which a pseudo-random key list is generated and used 696275970Scyin reverse order. 697275970ScyThese schemes are described along with an executive summary, 698275970Scycurrent status, briefing slides and reading list on the 699275970Scy\fIAutonomous\f[] \fIAuthentication\f[] 700275970Scypage. 701275970Scy.sp \n(Ppu 702275970Scy.ne 2 703275970Scy 704275970ScyThe specific cryptographic environment used by Autokey servers 705275970Scyand clients is determined by a set of files 706275970Scyand soft links generated by the 707285612Sdelphij\fCntp-keygen\f[]\fR(1ntpkeygenmdoc)\f[] 708275970Scyprogram. 709275970ScyThis includes a required host key file, 710275970Scyrequired certificate file and optional sign key file, 711275970Scyleapsecond file and identity scheme files. 712275970ScyThe 713275970Scydigest/signature scheme is specified in the X.509 certificate 714275970Scyalong with the matching sign key. 715275970ScyThere are several schemes 716275970Scyavailable in the OpenSSL software library, each identified 717275970Scyby a specific string such as 718275970Scy\f\*[B-Font]md5WithRSAEncryption\f[], 719275970Scywhich stands for the MD5 message digest with RSA 720275970Scyencryption scheme. 721275970ScyThe current NTP distribution supports 722275970Scyall the schemes in the OpenSSL library, including 723275970Scythose based on RSA and DSA digital signatures. 724275970Scy.sp \n(Ppu 725275970Scy.ne 2 726275970Scy 727275970ScyNTP secure groups can be used to define cryptographic compartments 728275970Scyand security hierarchies. 729275970ScyIt is important that every host 730275970Scyin the group be able to construct a certificate trail to one 731275970Scyor more trusted hosts in the same group. 732275970ScyEach group 733275970Scyhost runs the Autokey protocol to obtain the certificates 734275970Scyfor all hosts along the trail to one or more trusted hosts. 735275970ScyThis requires the configuration file in all hosts to be 736275970Scyengineered so that, even under anticipated failure conditions, 737275970Scythe NTP subnet will form such that every group host can find 738275970Scya trail to at least one trusted host. 739275970Scy.SS Naming and Addressing 740275970ScyIt is important to note that Autokey does not use DNS to 741275970Scyresolve addresses, since DNS can't be completely trusted 742275970Scyuntil the name servers have synchronized clocks. 743275970ScyThe cryptographic name used by Autokey to bind the host identity 744275970Scycredentials and cryptographic values must be independent 745275970Scyof interface, network and any other naming convention. 746275970ScyThe name appears in the host certificate in either or both 747275970Scythe subject and issuer fields, so protection against 748275970ScyDNS compromise is essential. 749275970Scy.sp \n(Ppu 750275970Scy.ne 2 751275970Scy 752275970ScyBy convention, the name of an Autokey host is the name returned 753275970Scyby the Unix 754285612Sdelphij\fCgethostname\f[]\fR(2)\f[] 755275970Scysystem call or equivalent in other systems. 756275970ScyBy the system design 757275970Scymodel, there are no provisions to allow alternate names or aliases. 758275970ScyHowever, this is not to say that DNS aliases, different names 759275970Scyfor each interface, etc., are constrained in any way. 760275970Scy.sp \n(Ppu 761275970Scy.ne 2 762275970Scy 763275970ScyIt is also important to note that Autokey verifies authenticity 764275970Scyusing the host name, network address and public keys, 765275970Scyall of which are bound together by the protocol specifically 766275970Scyto deflect masquerade attacks. 767275970ScyFor this reason Autokey 768298770Sdelphijincludes the source and destination IP addresses in message digest 769275970Scycomputations and so the same addresses must be available 770275970Scyat both the server and client. 771275970ScyFor this reason operation 772275970Scywith network address translation schemes is not possible. 773275970ScyThis reflects the intended robust security model where government 774275970Scyand corporate NTP servers are operated outside firewall perimeters. 775275970Scy.SS Operation 776275970ScyA specific combination of authentication scheme (none, 777275970Scysymmetric key, public key) and identity scheme is called 778275970Scya cryptotype, although not all combinations are compatible. 779275970ScyThere may be management configurations where the clients, 780275970Scyservers and peers may not all support the same cryptotypes. 781275970ScyA secure NTPv4 subnet can be configured in many ways while 782275970Scykeeping in mind the principles explained above and 783275970Scyin this section. 784275970ScyNote however that some cryptotype 785275970Scycombinations may successfully interoperate with each other, 786275970Scybut may not represent good security practice. 787275970Scy.sp \n(Ppu 788275970Scy.ne 2 789275970Scy 790275970ScyThe cryptotype of an association is determined at the time 791275970Scyof mobilization, either at configuration time or some time 792275970Scylater when a message of appropriate cryptotype arrives. 793275970ScyWhen mobilized by a 794275970Scy\f\*[B-Font]server\f[] 795275970Scyor 796275970Scy\f\*[B-Font]peer\f[] 797275970Scyconfiguration command and no 798275970Scy\f\*[B-Font]key\f[] 799275970Scyor 800275970Scy\f\*[B-Font]autokey\f[] 801275970Scysubcommands are present, the association is not 802275970Scyauthenticated; if the 803275970Scy\f\*[B-Font]key\f[] 804275970Scysubcommand is present, the association is authenticated 805275970Scyusing the symmetric key ID specified; if the 806275970Scy\f\*[B-Font]autokey\f[] 807275970Scysubcommand is present, the association is authenticated 808275970Scyusing Autokey. 809275970Scy.sp \n(Ppu 810275970Scy.ne 2 811275970Scy 812275970ScyWhen multiple identity schemes are supported in the Autokey 813275970Scyprotocol, the first message exchange determines which one is used. 814275970ScyThe client request message contains bits corresponding 815275970Scyto which schemes it has available. 816275970ScyThe server response message 817275970Scycontains bits corresponding to which schemes it has available. 818275970ScyBoth server and client match the received bits with their own 819275970Scyand select a common scheme. 820275970Scy.sp \n(Ppu 821275970Scy.ne 2 822275970Scy 823275970ScyFollowing the principle that time is a public value, 824275970Scya server responds to any client packet that matches 825275970Scyits cryptotype capabilities. 826275970ScyThus, a server receiving 827275970Scyan unauthenticated packet will respond with an unauthenticated 828275970Scypacket, while the same server receiving a packet of a cryptotype 829275970Scyit supports will respond with packets of that cryptotype. 830275970ScyHowever, unconfigured broadcast or manycast client 831275970Scyassociations or symmetric passive associations will not be 832275970Scymobilized unless the server supports a cryptotype compatible 833275970Scywith the first packet received. 834275970ScyBy default, unauthenticated associations will not be mobilized 835275970Scyunless overridden in a decidedly dangerous way. 836275970Scy.sp \n(Ppu 837275970Scy.ne 2 838275970Scy 839275970ScySome examples may help to reduce confusion. 840275970ScyClient Alice has no specific cryptotype selected. 841275970ScyServer Bob has both a symmetric key file and minimal Autokey files. 842275970ScyAlice's unauthenticated messages arrive at Bob, who replies with 843275970Scyunauthenticated messages. 844275970ScyCathy has a copy of Bob's symmetric 845275970Scykey file and has selected key ID 4 in messages to Bob. 846275970ScyBob verifies the message with his key ID 4. 847275970ScyIf it's the 848275970Scysame key and the message is verified, Bob sends Cathy a reply 849275970Scyauthenticated with that key. 850275970ScyIf verification fails, 851275970ScyBob sends Cathy a thing called a crypto-NAK, which tells her 852275970Scysomething broke. 853275970ScyShe can see the evidence using the 854285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 855275970Scyprogram. 856275970Scy.sp \n(Ppu 857275970Scy.ne 2 858275970Scy 859275970ScyDenise has rolled her own host key and certificate. 860275970ScyShe also uses one of the identity schemes as Bob. 861275970ScyShe sends the first Autokey message to Bob and they 862275970Scyboth dance the protocol authentication and identity steps. 863275970ScyIf all comes out okay, Denise and Bob continue as described above. 864275970Scy.sp \n(Ppu 865275970Scy.ne 2 866275970Scy 867275970ScyIt should be clear from the above that Bob can support 868275970Scyall the girls at the same time, as long as he has compatible 869275970Scyauthentication and identity credentials. 870275970ScyNow, Bob can act just like the girls in his own choice of servers; 871275970Scyhe can run multiple configured associations with multiple different 872275970Scyservers (or the same server, although that might not be useful). 873275970ScyBut, wise security policy might preclude some cryptotype 874275970Scycombinations; for instance, running an identity scheme 875275970Scywith one server and no authentication with another might not be wise. 876275970Scy.SS Key Management 877275970ScyThe cryptographic values used by the Autokey protocol are 878275970Scyincorporated as a set of files generated by the 879285612Sdelphij\fCntp-keygen\f[]\fR(1ntpkeygenmdoc)\f[] 880275970Scyutility program, including symmetric key, host key and 881275970Scypublic certificate files, as well as sign key, identity parameters 882275970Scyand leapseconds files. 883275970ScyAlternatively, host and sign keys and 884275970Scycertificate files can be generated by the OpenSSL utilities 885275970Scyand certificates can be imported from public certificate 886275970Scyauthorities. 887275970ScyNote that symmetric keys are necessary for the 888285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 889275970Scyand 890285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 891275970Scyutility programs. 892275970ScyThe remaining files are necessary only for the 893275970ScyAutokey protocol. 894275970Scy.sp \n(Ppu 895275970Scy.ne 2 896275970Scy 897275970ScyCertificates imported from OpenSSL or public certificate 898275970Scyauthorities have certian limitations. 899275970ScyThe certificate should be in ASN.1 syntax, X.509 Version 3 900275970Scyformat and encoded in PEM, which is the same format 901275970Scyused by OpenSSL. 902275970ScyThe overall length of the certificate encoded 903275970Scyin ASN.1 must not exceed 1024 bytes. 904275970ScyThe subject distinguished 905275970Scyname field (CN) is the fully qualified name of the host 906275970Scyon which it is used; the remaining subject fields are ignored. 907275970ScyThe certificate extension fields must not contain either 908275970Scya subject key identifier or a issuer key identifier field; 909275970Scyhowever, an extended key usage field for a trusted host must 910275970Scycontain the value 911275970Scy\f\*[B-Font]trustRoot\f[];. 912275970ScyOther extension fields are ignored. 913275970Scy.SS Authentication Commands 914275970Scy.TP 7 915275970Scy.NOP \f\*[B-Font]autokey\f[] [\f\*[I-Font]logsec\f[]] 916275970ScySpecifies the interval between regenerations of the session key 917275970Scylist used with the Autokey protocol. 918275970ScyNote that the size of the key 919275970Scylist for each association depends on this interval and the current 920275970Scypoll interval. 921275970ScyThe default value is 12 (4096 s or about 1.1 hours). 922275970ScyFor poll intervals above the specified interval, a session key list 923275970Scywith a single entry will be regenerated for every message 924275970Scysent. 925275970Scy.TP 7 926275970Scy.NOP \f\*[B-Font]controlkey\f[] \f\*[I-Font]key\f[] 927275970ScySpecifies the key identifier to use with the 928285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 929275970Scyutility, which uses the standard 930275970Scyprotocol defined in RFC-1305. 931275970ScyThe 932275970Scy\f\*[I-Font]key\f[] 933275970Scyargument is 934275970Scythe key identifier for a trusted key, where the value can be in the 935275970Scyrange 1 to 65,534, inclusive. 936275970Scy.TP 7 937275970Scy.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[]] 938275970ScyThis command requires the OpenSSL library. 939275970ScyIt activates public key 940275970Scycryptography, selects the message digest and signature 941275970Scyencryption scheme and loads the required private and public 942275970Scyvalues described above. 943275970ScyIf one or more files are left unspecified, 944275970Scythe default names are used as described above. 945275970ScyUnless the complete path and name of the file are specified, the 946275970Scylocation of a file is relative to the keys directory specified 947275970Scyin the 948275970Scy\f\*[B-Font]keysdir\f[] 949275970Scycommand or default 950275970Scy\fI/usr/local/etc\f[]. 951275970ScyFollowing are the subcommands: 952275970Scy.RS 953275970Scy.TP 7 954275970Scy.NOP \f\*[B-Font]cert\f[] \f\*[I-Font]file\f[] 955275970ScySpecifies the location of the required host public certificate file. 956275970ScyThis overrides the link 957275970Scy\fIntpkey_cert_\f[]\f\*[I-Font]hostname\f[] 958275970Scyin the keys directory. 959275970Scy.TP 7 960275970Scy.NOP \f\*[B-Font]gqpar\f[] \f\*[I-Font]file\f[] 961275970ScySpecifies the location of the optional GQ parameters file. 962275970ScyThis 963275970Scyoverrides the link 964275970Scy\fIntpkey_gq_\f[]\f\*[I-Font]hostname\f[] 965275970Scyin the keys directory. 966275970Scy.TP 7 967275970Scy.NOP \f\*[B-Font]host\f[] \f\*[I-Font]file\f[] 968275970ScySpecifies the location of the required host key file. 969275970ScyThis overrides 970275970Scythe link 971275970Scy\fIntpkey_key_\f[]\f\*[I-Font]hostname\f[] 972275970Scyin the keys directory. 973275970Scy.TP 7 974275970Scy.NOP \f\*[B-Font]iffpar\f[] \f\*[I-Font]file\f[] 975298770SdelphijSpecifies the location of the optional IFF parameters file. 976298770SdelphijThis overrides the link 977275970Scy\fIntpkey_iff_\f[]\f\*[I-Font]hostname\f[] 978275970Scyin the keys directory. 979275970Scy.TP 7 980275970Scy.NOP \f\*[B-Font]leap\f[] \f\*[I-Font]file\f[] 981275970ScySpecifies the location of the optional leapsecond file. 982275970ScyThis overrides the link 983275970Scy\fIntpkey_leap\f[] 984275970Scyin the keys directory. 985275970Scy.TP 7 986275970Scy.NOP \f\*[B-Font]mvpar\f[] \f\*[I-Font]file\f[] 987275970ScySpecifies the location of the optional MV parameters file. 988298770SdelphijThis overrides the link 989275970Scy\fIntpkey_mv_\f[]\f\*[I-Font]hostname\f[] 990275970Scyin the keys directory. 991275970Scy.TP 7 992275970Scy.NOP \f\*[B-Font]pw\f[] \f\*[I-Font]password\f[] 993275970ScySpecifies the password to decrypt files containing private keys and 994275970Scyidentity parameters. 995275970ScyThis is required only if these files have been 996275970Scyencrypted. 997275970Scy.TP 7 998275970Scy.NOP \f\*[B-Font]randfile\f[] \f\*[I-Font]file\f[] 999275970ScySpecifies the location of the random seed file used by the OpenSSL 1000275970Scylibrary. 1001275970ScyThe defaults are described in the main text above. 1002275970Scy.TP 7 1003275970Scy.NOP \f\*[B-Font]sign\f[] \f\*[I-Font]file\f[] 1004275970ScySpecifies the location of the optional sign key file. 1005275970ScyThis overrides 1006275970Scythe link 1007275970Scy\fIntpkey_sign_\f[]\f\*[I-Font]hostname\f[] 1008275970Scyin the keys directory. 1009275970ScyIf this file is 1010275970Scynot found, the host key is also the sign key. 1011275970Scy.RE 1012275970Scy.TP 7 1013275970Scy.NOP \f\*[B-Font]keys\f[] \f\*[I-Font]keyfile\f[] 1014275970ScySpecifies the complete path and location of the MD5 key file 1015275970Scycontaining the keys and key identifiers used by 1016285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[], 1017285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1018275970Scyand 1019285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1020275970Scywhen operating with symmetric key cryptography. 1021275970ScyThis is the same operation as the 1022275970Scy\f\*[B-Font]\-k\f[] 1023275970Scycommand line option. 1024275970Scy.TP 7 1025275970Scy.NOP \f\*[B-Font]keysdir\f[] \f\*[I-Font]path\f[] 1026275970ScyThis command specifies the default directory path for 1027275970Scycryptographic keys, parameters and certificates. 1028275970ScyThe default is 1029275970Scy\fI/usr/local/etc/\f[]. 1030275970Scy.TP 7 1031275970Scy.NOP \f\*[B-Font]requestkey\f[] \f\*[I-Font]key\f[] 1032275970ScySpecifies the key identifier to use with the 1033285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1034275970Scyutility program, which uses a 1035275970Scyproprietary protocol specific to this implementation of 1036285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[]. 1037275970ScyThe 1038275970Scy\f\*[I-Font]key\f[] 1039275970Scyargument is a key identifier 1040275970Scyfor the trusted key, where the value can be in the range 1 to 1041275970Scy65,534, inclusive. 1042275970Scy.TP 7 1043275970Scy.NOP \f\*[B-Font]revoke\f[] \f\*[I-Font]logsec\f[] 1044275970ScySpecifies the interval between re-randomization of certain 1045275970Scycryptographic values used by the Autokey scheme, as a power of 2 in 1046275970Scyseconds. 1047275970ScyThese values need to be updated frequently in order to 1048275970Scydeflect brute-force attacks on the algorithms of the scheme; 1049275970Scyhowever, updating some values is a relatively expensive operation. 1050275970ScyThe default interval is 16 (65,536 s or about 18 hours). 1051275970ScyFor poll 1052275970Scyintervals above the specified interval, the values will be updated 1053275970Scyfor every message sent. 1054275970Scy.TP 7 1055275970Scy.NOP \f\*[B-Font]trustedkey\f[] \f\*[I-Font]key\f[] \f\*[I-Font]...\f[] 1056275970ScySpecifies the key identifiers which are trusted for the 1057275970Scypurposes of authenticating peers with symmetric key cryptography, 1058275970Scyas well as keys used by the 1059285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1060275970Scyand 1061285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1062275970Scyprograms. 1063275970ScyThe authentication procedures require that both the local 1064275970Scyand remote servers share the same key and key identifier for this 1065275970Scypurpose, although different keys can be used with different 1066275970Scyservers. 1067275970ScyThe 1068275970Scy\f\*[I-Font]key\f[] 1069275970Scyarguments are 32-bit unsigned 1070275970Scyintegers with values from 1 to 65,534. 1071275970Scy.PP 1072275970Scy.SS Error Codes 1073275970ScyThe following error codes are reported via the NTP control 1074275970Scyand monitoring protocol trap mechanism. 1075275970Scy.TP 7 1076275970Scy.NOP 101 1077275970Scy(bad field format or length) 1078275970ScyThe packet has invalid version, length or format. 1079275970Scy.TP 7 1080275970Scy.NOP 102 1081275970Scy(bad timestamp) 1082275970ScyThe packet timestamp is the same or older than the most recent received. 1083275970ScyThis could be due to a replay or a server clock time step. 1084275970Scy.TP 7 1085275970Scy.NOP 103 1086275970Scy(bad filestamp) 1087275970ScyThe packet filestamp is the same or older than the most recent received. 1088275970ScyThis could be due to a replay or a key file generation error. 1089275970Scy.TP 7 1090275970Scy.NOP 104 1091275970Scy(bad or missing public key) 1092275970ScyThe public key is missing, has incorrect format or is an unsupported type. 1093275970Scy.TP 7 1094275970Scy.NOP 105 1095275970Scy(unsupported digest type) 1096275970ScyThe server requires an unsupported digest/signature scheme. 1097275970Scy.TP 7 1098275970Scy.NOP 106 1099275970Scy(mismatched digest types) 1100275970ScyNot used. 1101275970Scy.TP 7 1102275970Scy.NOP 107 1103275970Scy(bad signature length) 1104275970ScyThe signature length does not match the current public key. 1105275970Scy.TP 7 1106275970Scy.NOP 108 1107275970Scy(signature not verified) 1108275970ScyThe message fails the signature check. 1109275970ScyIt could be bogus or signed by a 1110275970Scydifferent private key. 1111275970Scy.TP 7 1112275970Scy.NOP 109 1113275970Scy(certificate not verified) 1114275970ScyThe certificate is invalid or signed with the wrong key. 1115275970Scy.TP 7 1116275970Scy.NOP 110 1117275970Scy(certificate not verified) 1118275970ScyThe certificate is not yet valid or has expired or the signature could not 1119275970Scybe verified. 1120275970Scy.TP 7 1121275970Scy.NOP 111 1122275970Scy(bad or missing cookie) 1123275970ScyThe cookie is missing, corrupted or bogus. 1124275970Scy.TP 7 1125275970Scy.NOP 112 1126275970Scy(bad or missing leapseconds table) 1127275970ScyThe leapseconds table is missing, corrupted or bogus. 1128275970Scy.TP 7 1129275970Scy.NOP 113 1130275970Scy(bad or missing certificate) 1131275970ScyThe certificate is missing, corrupted or bogus. 1132275970Scy.TP 7 1133275970Scy.NOP 114 1134275970Scy(bad or missing identity) 1135275970ScyThe identity key is missing, corrupt or bogus. 1136275970Scy.PP 1137275970Scy.SH Monitoring Support 1138285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1139275970Scyincludes a comprehensive monitoring facility suitable 1140275970Scyfor continuous, long term recording of server and client 1141275970Scytimekeeping performance. 1142275970ScySee the 1143275970Scy\f\*[B-Font]statistics\f[] 1144275970Scycommand below 1145275970Scyfor a listing and example of each type of statistics currently 1146275970Scysupported. 1147275970ScyStatistic files are managed using file generation sets 1148275970Scyand scripts in the 1149275970Scy\fI./scripts\f[] 1150298770Sdelphijdirectory of the source code distribution. 1151275970ScyUsing 1152275970Scythese facilities and 1153275970ScyUNIX 1154285612Sdelphij\fCcron\f[]\fR(8)\f[] 1155275970Scyjobs, the data can be 1156275970Scyautomatically summarized and archived for retrospective analysis. 1157275970Scy.SS Monitoring Commands 1158275970Scy.TP 7 1159275970Scy.NOP \f\*[B-Font]statistics\f[] \f\*[I-Font]name\f[] \f\*[I-Font]...\f[] 1160275970ScyEnables writing of statistics records. 1161275970ScyCurrently, eight kinds of 1162275970Scy\f\*[I-Font]name\f[] 1163275970Scystatistics are supported. 1164275970Scy.RS 1165275970Scy.TP 7 1166275970Scy.NOP \f\*[B-Font]clockstats\f[] 1167275970ScyEnables recording of clock driver statistics information. 1168275970ScyEach update 1169275970Scyreceived from a clock driver appends a line of the following form to 1170275970Scythe file generation set named 1171275970Scy\f\*[B-Font]clockstats\f[]: 1172275970Scy.br 1173275970Scy.in +4 1174275970Scy.nf 1175275970Scy49213 525.624 127.127.4.1 93 226 00:08:29.606 D 1176275970Scy.in -4 1177275970Scy.fi 1178275970Scy.sp \n(Ppu 1179275970Scy.ne 2 1180275970Scy 1181275970ScyThe first two fields show the date (Modified Julian Day) and time 1182275970Scy(seconds and fraction past UTC midnight). 1183275970ScyThe next field shows the 1184275970Scyclock address in dotted-quad notation. 1185275970ScyThe final field shows the last 1186275970Scytimecode received from the clock in decoded ASCII format, where 1187275970Scymeaningful. 1188275970ScyIn some clock drivers a good deal of additional information 1189275970Scycan be gathered and displayed as well. 1190275970ScySee information specific to each 1191275970Scyclock for further details. 1192275970Scy.TP 7 1193275970Scy.NOP \f\*[B-Font]cryptostats\f[] 1194275970ScyThis option requires the OpenSSL cryptographic software library. 1195275970ScyIt 1196275970Scyenables recording of cryptographic public key protocol information. 1197275970ScyEach message received by the protocol module appends a line of the 1198275970Scyfollowing form to the file generation set named 1199275970Scy\f\*[B-Font]cryptostats\f[]: 1200275970Scy.br 1201275970Scy.in +4 1202275970Scy.nf 1203275970Scy49213 525.624 127.127.4.1 message 1204275970Scy.in -4 1205275970Scy.fi 1206275970Scy.sp \n(Ppu 1207275970Scy.ne 2 1208275970Scy 1209275970ScyThe first two fields show the date (Modified Julian Day) and time 1210275970Scy(seconds and fraction past UTC midnight). 1211275970ScyThe next field shows the peer 1212275970Scyaddress in dotted-quad notation, The final message field includes the 1213275970Scymessage type and certain ancillary information. 1214275970ScySee the 1215275970Scy\fIAuthentication\f[] \fIOptions\f[] 1216275970Scysection for further information. 1217275970Scy.TP 7 1218275970Scy.NOP \f\*[B-Font]loopstats\f[] 1219275970ScyEnables recording of loop filter statistics information. 1220275970ScyEach 1221275970Scyupdate of the local clock outputs a line of the following form to 1222275970Scythe file generation set named 1223275970Scy\f\*[B-Font]loopstats\f[]: 1224275970Scy.br 1225275970Scy.in +4 1226275970Scy.nf 1227275970Scy50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 1228275970Scy.in -4 1229275970Scy.fi 1230275970Scy.sp \n(Ppu 1231275970Scy.ne 2 1232275970Scy 1233275970ScyThe first two fields show the date (Modified Julian Day) and 1234275970Scytime (seconds and fraction past UTC midnight). 1235275970ScyThe next five fields 1236275970Scyshow time offset (seconds), frequency offset (parts per million \- 1237275970ScyPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 1238275970Scydiscipline time constant. 1239275970Scy.TP 7 1240275970Scy.NOP \f\*[B-Font]peerstats\f[] 1241275970ScyEnables recording of peer statistics information. 1242275970ScyThis includes 1243275970Scystatistics records of all peers of a NTP server and of special 1244275970Scysignals, where present and configured. 1245275970ScyEach valid update appends a 1246275970Scyline of the following form to the current element of a file 1247275970Scygeneration set named 1248275970Scy\f\*[B-Font]peerstats\f[]: 1249275970Scy.br 1250275970Scy.in +4 1251275970Scy.nf 1252275970Scy48773 10847.650 127.127.4.1 9714 \-0.001605376 0.000000000 0.001424877 0.000958674 1253275970Scy.in -4 1254275970Scy.fi 1255275970Scy.sp \n(Ppu 1256275970Scy.ne 2 1257275970Scy 1258275970ScyThe first two fields show the date (Modified Julian Day) and 1259275970Scytime (seconds and fraction past UTC midnight). 1260275970ScyThe next two fields 1261275970Scyshow the peer address in dotted-quad notation and status, 1262275970Scyrespectively. 1263275970ScyThe status field is encoded in hex in the format 1264275970Scydescribed in Appendix A of the NTP specification RFC 1305. 1265275970ScyThe final four fields show the offset, 1266275970Scydelay, dispersion and RMS jitter, all in seconds. 1267275970Scy.TP 7 1268275970Scy.NOP \f\*[B-Font]rawstats\f[] 1269275970ScyEnables recording of raw-timestamp statistics information. 1270275970ScyThis 1271275970Scyincludes statistics records of all peers of a NTP server and of 1272275970Scyspecial signals, where present and configured. 1273275970ScyEach NTP message 1274275970Scyreceived from a peer or clock driver appends a line of the 1275275970Scyfollowing form to the file generation set named 1276275970Scy\f\*[B-Font]rawstats\f[]: 1277275970Scy.br 1278275970Scy.in +4 1279275970Scy.nf 1280275970Scy50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 1281275970Scy.in -4 1282275970Scy.fi 1283275970Scy.sp \n(Ppu 1284275970Scy.ne 2 1285275970Scy 1286275970ScyThe first two fields show the date (Modified Julian Day) and 1287275970Scytime (seconds and fraction past UTC midnight). 1288275970ScyThe next two fields 1289275970Scyshow the remote peer or clock address followed by the local address 1290275970Scyin dotted-quad notation. 1291275970ScyThe final four fields show the originate, 1292275970Scyreceive, transmit and final NTP timestamps in order. 1293275970ScyThe timestamp 1294275970Scyvalues are as received and before processing by the various data 1295275970Scysmoothing and mitigation algorithms. 1296275970Scy.TP 7 1297275970Scy.NOP \f\*[B-Font]sysstats\f[] 1298275970ScyEnables recording of ntpd statistics counters on a periodic basis. 1299275970ScyEach 1300275970Scyhour a line of the following form is appended to the file generation 1301275970Scyset named 1302275970Scy\f\*[B-Font]sysstats\f[]: 1303275970Scy.br 1304275970Scy.in +4 1305275970Scy.nf 1306275970Scy50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1307275970Scy.in -4 1308275970Scy.fi 1309275970Scy.sp \n(Ppu 1310275970Scy.ne 2 1311275970Scy 1312275970ScyThe first two fields show the date (Modified Julian Day) and time 1313275970Scy(seconds and fraction past UTC midnight). 1314275970ScyThe remaining ten fields show 1315275970Scythe statistics counter values accumulated since the last generated 1316275970Scyline. 1317275970Scy.RS 1318275970Scy.TP 7 1319275970Scy.NOP Time since restart \f\*[B-Font]36000\f[] 1320275970ScyTime in hours since the system was last rebooted. 1321275970Scy.TP 7 1322275970Scy.NOP Packets received \f\*[B-Font]81965\f[] 1323275970ScyTotal number of packets received. 1324275970Scy.TP 7 1325275970Scy.NOP Packets processed \f\*[B-Font]0\f[] 1326275970ScyNumber of packets received in response to previous packets sent 1327275970Scy.TP 7 1328275970Scy.NOP Current version \f\*[B-Font]9546\f[] 1329275970ScyNumber of packets matching the current NTP version. 1330275970Scy.TP 7 1331275970Scy.NOP Previous version \f\*[B-Font]56\f[] 1332275970ScyNumber of packets matching the previous NTP version. 1333275970Scy.TP 7 1334275970Scy.NOP Bad version \f\*[B-Font]71793\f[] 1335275970ScyNumber of packets matching neither NTP version. 1336275970Scy.TP 7 1337275970Scy.NOP Access denied \f\*[B-Font]512\f[] 1338275970ScyNumber of packets denied access for any reason. 1339275970Scy.TP 7 1340275970Scy.NOP Bad length or format \f\*[B-Font]540\f[] 1341275970ScyNumber of packets with invalid length, format or port number. 1342275970Scy.TP 7 1343275970Scy.NOP Bad authentication \f\*[B-Font]10\f[] 1344275970ScyNumber of packets not verified as authentic. 1345275970Scy.TP 7 1346275970Scy.NOP Rate exceeded \f\*[B-Font]147\f[] 1347275970ScyNumber of packets discarded due to rate limitation. 1348275970Scy.RE 1349275970Scy.TP 7 1350275970Scy.NOP \f\*[B-Font]statsdir\f[] \f\*[I-Font]directory_path\f[] 1351275970ScyIndicates the full path of a directory where statistics files 1352275970Scyshould be created (see below). 1353275970ScyThis keyword allows 1354275970Scythe (otherwise constant) 1355275970Scy\f\*[B-Font]filegen\f[] 1356275970Scyfilename prefix to be modified for file generation sets, which 1357275970Scyis useful for handling statistics logs. 1358275970Scy.TP 7 1359275970Scy.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[]] 1360275970ScyConfigures setting of generation file set name. 1361275970ScyGeneration 1362275970Scyfile sets provide a means for handling files that are 1363275970Scycontinuously growing during the lifetime of a server. 1364275970ScyServer statistics are a typical example for such files. 1365275970ScyGeneration file sets provide access to a set of files used 1366275970Scyto store the actual data. 1367275970ScyAt any time at most one element 1368275970Scyof the set is being written to. 1369275970ScyThe type given specifies 1370275970Scywhen and how data will be directed to a new element of the set. 1371275970ScyThis way, information stored in elements of a file set 1372275970Scythat are currently unused are available for administrational 1373275970Scyoperations without the risk of disturbing the operation of ntpd. 1374275970Scy(Most important: they can be removed to free space for new data 1375275970Scyproduced.) 1376275970Scy.sp \n(Ppu 1377275970Scy.ne 2 1378275970Scy 1379275970ScyNote that this command can be sent from the 1380285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1381275970Scyprogram running at a remote location. 1382275970Scy.RS 1383275970Scy.TP 7 1384275970Scy.NOP \f\*[B-Font]name\f[] 1385275970ScyThis is the type of the statistics records, as shown in the 1386275970Scy\f\*[B-Font]statistics\f[] 1387275970Scycommand. 1388275970Scy.TP 7 1389275970Scy.NOP \f\*[B-Font]file\f[] \f\*[I-Font]filename\f[] 1390275970ScyThis is the file name for the statistics records. 1391275970ScyFilenames of set 1392275970Scymembers are built from three concatenated elements 1393275970Scy\f\*[B-Font]prefix\f[], 1394275970Scy\f\*[B-Font]filename\f[] 1395275970Scyand 1396275970Scy\f\*[B-Font]suffix\f[]: 1397275970Scy.RS 1398275970Scy.TP 7 1399275970Scy.NOP \f\*[B-Font]prefix\f[] 1400275970ScyThis is a constant filename path. 1401275970ScyIt is not subject to 1402275970Scymodifications via the 1403275970Scy\f\*[I-Font]filegen\f[] 1404275970Scyoption. 1405275970ScyIt is defined by the 1406275970Scyserver, usually specified as a compile-time constant. 1407275970ScyIt may, 1408275970Scyhowever, be configurable for individual file generation sets 1409275970Scyvia other commands. 1410275970ScyFor example, the prefix used with 1411275970Scy\f\*[I-Font]loopstats\f[] 1412275970Scyand 1413275970Scy\f\*[I-Font]peerstats\f[] 1414275970Scygeneration can be configured using the 1415275970Scy\f\*[I-Font]statsdir\f[] 1416275970Scyoption explained above. 1417275970Scy.TP 7 1418275970Scy.NOP \f\*[B-Font]filename\f[] 1419275970ScyThis string is directly concatenated to the prefix mentioned 1420275970Scyabove (no intervening 1421275970Scy\[oq]/\[cq]). 1422275970ScyThis can be modified using 1423275970Scythe file argument to the 1424275970Scy\f\*[I-Font]filegen\f[] 1425275970Scystatement. 1426275970ScyNo 1427275970Scy\fI..\f[] 1428275970Scyelements are 1429275970Scyallowed in this component to prevent filenames referring to 1430275970Scyparts outside the filesystem hierarchy denoted by 1431275970Scy\f\*[I-Font]prefix\f[]. 1432275970Scy.TP 7 1433275970Scy.NOP \f\*[B-Font]suffix\f[] 1434275970ScyThis part is reflects individual elements of a file set. 1435275970ScyIt is 1436275970Scygenerated according to the type of a file set. 1437275970Scy.RE 1438275970Scy.TP 7 1439275970Scy.NOP \f\*[B-Font]type\f[] \f\*[I-Font]typename\f[] 1440275970ScyA file generation set is characterized by its type. 1441275970ScyThe following 1442275970Scytypes are supported: 1443275970Scy.RS 1444275970Scy.TP 7 1445275970Scy.NOP \f\*[B-Font]none\f[] 1446275970ScyThe file set is actually a single plain file. 1447275970Scy.TP 7 1448275970Scy.NOP \f\*[B-Font]pid\f[] 1449275970ScyOne element of file set is used per incarnation of a ntpd 1450275970Scyserver. 1451275970ScyThis type does not perform any changes to file set 1452275970Scymembers during runtime, however it provides an easy way of 1453275970Scyseparating files belonging to different 1454285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1455275970Scyserver incarnations. 1456275970ScyThe set member filename is built by appending a 1457275970Scy\[oq]\&.\[cq] 1458275970Scyto concatenated 1459275970Scy\f\*[I-Font]prefix\f[] 1460275970Scyand 1461275970Scy\f\*[I-Font]filename\f[] 1462275970Scystrings, and 1463275970Scyappending the decimal representation of the process ID of the 1464285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1465275970Scyserver process. 1466275970Scy.TP 7 1467275970Scy.NOP \f\*[B-Font]day\f[] 1468275970ScyOne file generation set element is created per day. 1469275970ScyA day is 1470275970Scydefined as the period between 00:00 and 24:00 UTC. 1471275970ScyThe file set 1472275970Scymember suffix consists of a 1473275970Scy\[oq]\&.\[cq] 1474275970Scyand a day specification in 1475275970Scythe form 1476275970Scy\f\*[B-Font]YYYYMMdd\f[]. 1477275970Scy\f\*[B-Font]YYYY\f[] 1478275970Scyis a 4-digit year number (e.g., 1992). 1479275970Scy\f\*[B-Font]MM\f[] 1480275970Scyis a two digit month number. 1481275970Scy\f\*[B-Font]dd\f[] 1482275970Scyis a two digit day number. 1483275970ScyThus, all information written at 10 December 1992 would end up 1484275970Scyin a file named 1485275970Scy\f\*[I-Font]prefix\f[] 1486275970Scy\f\*[I-Font]filename\f[].19921210. 1487275970Scy.TP 7 1488275970Scy.NOP \f\*[B-Font]week\f[] 1489275970ScyAny file set member contains data related to a certain week of 1490275970Scya year. 1491275970ScyThe term week is defined by computing day-of-year 1492275970Scymodulo 7. 1493275970ScyElements of such a file generation set are 1494275970Scydistinguished by appending the following suffix to the file set 1495275970Scyfilename base: A dot, a 4-digit year number, the letter 1496275970Scy\f\*[B-Font]W\f[], 1497275970Scyand a 2-digit week number. 1498275970ScyFor example, information from January, 1499275970Scy10th 1992 would end up in a file with suffix 1500275970Scy.NOP. \f\*[I-Font]1992W1\f[]. 1501275970Scy.TP 7 1502275970Scy.NOP \f\*[B-Font]month\f[] 1503275970ScyOne generation file set element is generated per month. 1504275970ScyThe 1505275970Scyfile name suffix consists of a dot, a 4-digit year number, and 1506275970Scya 2-digit month. 1507275970Scy.TP 7 1508275970Scy.NOP \f\*[B-Font]year\f[] 1509275970ScyOne generation file element is generated per year. 1510275970ScyThe filename 1511275970Scysuffix consists of a dot and a 4 digit year number. 1512275970Scy.TP 7 1513275970Scy.NOP \f\*[B-Font]age\f[] 1514275970ScyThis type of file generation sets changes to a new element of 1515275970Scythe file set every 24 hours of server operation. 1516275970ScyThe filename 1517275970Scysuffix consists of a dot, the letter 1518275970Scy\f\*[B-Font]a\f[], 1519275970Scyand an 8-digit number. 1520275970ScyThis number is taken to be the number of seconds the server is 1521275970Scyrunning at the start of the corresponding 24-hour period. 1522275970ScyInformation is only written to a file generation by specifying 1523275970Scy\f\*[B-Font]enable\f[]; 1524275970Scyoutput is prevented by specifying 1525275970Scy\f\*[B-Font]disable\f[]. 1526275970Scy.RE 1527275970Scy.TP 7 1528275970Scy.NOP \f\*[B-Font]link\f[] | \f\*[B-Font]nolink\f[] 1529275970ScyIt is convenient to be able to access the current element of a file 1530275970Scygeneration set by a fixed name. 1531275970ScyThis feature is enabled by 1532275970Scyspecifying 1533275970Scy\f\*[B-Font]link\f[] 1534275970Scyand disabled using 1535275970Scy\f\*[B-Font]nolink\f[]. 1536275970ScyIf link is specified, a 1537275970Scyhard link from the current file set element to a file without 1538275970Scysuffix is created. 1539275970ScyWhen there is already a file with this name and 1540275970Scythe number of links of this file is one, it is renamed appending a 1541275970Scydot, the letter 1542275970Scy\f\*[B-Font]C\f[], 1543298770Sdelphijand the pid of the 1544298770Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1545298770Sdelphijserver process. 1546275970ScyWhen the 1547275970Scynumber of links is greater than one, the file is unlinked. 1548275970ScyThis 1549275970Scyallows the current file to be accessed by a constant name. 1550275970Scy.TP 7 1551275970Scy.NOP \f\*[B-Font]enable\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]disable\f[] 1552275970ScyEnables or disables the recording function. 1553275970Scy.RE 1554275970Scy.RE 1555275970Scy.PP 1556275970Scy.SH Access Control Support 1557275970ScyThe 1558285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 1559275970Scydaemon implements a general purpose address/mask based restriction 1560275970Scylist. 1561275970ScyThe list contains address/match entries sorted first 1562275970Scyby increasing address values and and then by increasing mask values. 1563275970ScyA match occurs when the bitwise AND of the mask and the packet 1564275970Scysource address is equal to the bitwise AND of the mask and 1565275970Scyaddress in the list. 1566275970ScyThe list is searched in order with the 1567275970Scylast match found defining the restriction flags associated 1568275970Scywith the entry. 1569275970ScyAdditional information and examples can be found in the 1570275970Scy"Notes on Configuring NTP and Setting up a NTP Subnet" 1571275970Scypage 1572275970Scy(available as part of the HTML documentation 1573275970Scyprovided in 1574275970Scy\fI/usr/share/doc/ntp\f[]). 1575275970Scy.sp \n(Ppu 1576275970Scy.ne 2 1577275970Scy 1578275970ScyThe restriction facility was implemented in conformance 1579275970Scywith the access policies for the original NSFnet backbone 1580275970Scytime servers. 1581275970ScyLater the facility was expanded to deflect 1582275970Scycryptographic and clogging attacks. 1583275970ScyWhile this facility may 1584275970Scybe useful for keeping unwanted or broken or malicious clients 1585275970Scyfrom congesting innocent servers, it should not be considered 1586275970Scyan alternative to the NTP authentication facilities. 1587275970ScySource address based restrictions are easily circumvented 1588275970Scyby a determined cracker. 1589275970Scy.sp \n(Ppu 1590275970Scy.ne 2 1591275970Scy 1592275970ScyClients can be denied service because they are explicitly 1593298770Sdelphijincluded in the restrict list created by the 1594298770Sdelphij\f\*[B-Font]restrict\f[] 1595298770Sdelphijcommand 1596275970Scyor implicitly as the result of cryptographic or rate limit 1597275970Scyviolations. 1598275970ScyCryptographic violations include certificate 1599275970Scyor identity verification failure; rate limit violations generally 1600275970Scyresult from defective NTP implementations that send packets 1601275970Scyat abusive rates. 1602275970ScySome violations cause denied service 1603275970Scyonly for the offending packet, others cause denied service 1604275970Scyfor a timed period and others cause the denied service for 1605298770Sdelphijan indefinite period. 1606275970ScyWhen a client or network is denied access 1607298770Sdelphijfor an indefinite period, the only way at present to remove 1608275970Scythe restrictions is by restarting the server. 1609275970Scy.SS The Kiss-of-Death Packet 1610275970ScyOrdinarily, packets denied service are simply dropped with no 1611275970Scyfurther action except incrementing statistics counters. 1612275970ScySometimes a 1613275970Scymore proactive response is needed, such as a server message that 1614275970Scyexplicitly requests the client to stop sending and leave a message 1615275970Scyfor the system operator. 1616275970ScyA special packet format has been created 1617275970Scyfor this purpose called the "kiss-of-death" (KoD) packet. 1618275970ScyKoD packets have the leap bits set unsynchronized and stratum set 1619275970Scyto zero and the reference identifier field set to a four-byte 1620275970ScyASCII code. 1621275970ScyIf the 1622275970Scy\f\*[B-Font]noserve\f[] 1623275970Scyor 1624275970Scy\f\*[B-Font]notrust\f[] 1625275970Scyflag of the matching restrict list entry is set, 1626275970Scythe code is "DENY"; if the 1627275970Scy\f\*[B-Font]limited\f[] 1628275970Scyflag is set and the rate limit 1629275970Scyis exceeded, the code is "RATE". 1630275970ScyFinally, if a cryptographic violation occurs, the code is "CRYP". 1631275970Scy.sp \n(Ppu 1632275970Scy.ne 2 1633275970Scy 1634275970ScyA client receiving a KoD performs a set of sanity checks to 1635275970Scyminimize security exposure, then updates the stratum and 1636275970Scyreference identifier peer variables, sets the access 1637275970Scydenied (TEST4) bit in the peer flash variable and sends 1638275970Scya message to the log. 1639275970ScyAs long as the TEST4 bit is set, 1640275970Scythe client will send no further packets to the server. 1641275970ScyThe only way at present to recover from this condition is 1642275970Scyto restart the protocol at both the client and server. 1643275970ScyThis 1644275970Scyhappens automatically at the client when the association times out. 1645275970ScyIt will happen at the server only if the server operator cooperates. 1646275970Scy.SS Access Control Commands 1647275970Scy.TP 7 1648275970Scy.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[]] 1649275970ScySet the parameters of the 1650275970Scy\f\*[B-Font]limited\f[] 1651275970Scyfacility which protects the server from 1652275970Scyclient abuse. 1653275970ScyThe 1654275970Scy\f\*[B-Font]average\f[] 1655275970Scysubcommand specifies the minimum average packet 1656275970Scyspacing, while the 1657275970Scy\f\*[B-Font]minimum\f[] 1658275970Scysubcommand specifies the minimum packet spacing. 1659275970ScyPackets that violate these minima are discarded 1660275970Scyand a kiss-o'-death packet returned if enabled. 1661275970ScyThe default 1662275970Scyminimum average and minimum are 5 and 2, respectively. 1663298770SdelphijThe 1664298770Sdelphij\f\*[B-Font]monitor\f[] 1665298770Sdelphijsubcommand specifies the probability of discard 1666275970Scyfor packets that overflow the rate-control window. 1667275970Scy.TP 7 1668275970Scy.NOP \f\*[B-Font]restrict\f[] \f\*[B-Font]address\f[] [\f\*[B-Font]mask\f[] \f\*[I-Font]mask\f[]] [\f\*[I-Font]flag\f[] \f\*[I-Font]...\f[]] 1669275970ScyThe 1670275970Scy\f\*[I-Font]address\f[] 1671275970Scyargument expressed in 1672275970Scydotted-quad form is the address of a host or network. 1673275970ScyAlternatively, the 1674275970Scy\f\*[I-Font]address\f[] 1675275970Scyargument can be a valid host DNS name. 1676275970ScyThe 1677275970Scy\f\*[I-Font]mask\f[] 1678275970Scyargument expressed in dotted-quad form defaults to 1679275970Scy\f\*[B-Font]255.255.255.255\f[], 1680275970Scymeaning that the 1681275970Scy\f\*[I-Font]address\f[] 1682275970Scyis treated as the address of an individual host. 1683275970ScyA default entry (address 1684275970Scy\f\*[B-Font]0.0.0.0\f[], 1685275970Scymask 1686275970Scy\f\*[B-Font]0.0.0.0\f[]) 1687275970Scyis always included and is always the first entry in the list. 1688275970ScyNote that text string 1689275970Scy\f\*[B-Font]default\f[], 1690275970Scywith no mask option, may 1691275970Scybe used to indicate the default entry. 1692275970ScyIn the current implementation, 1693275970Scy\f\*[B-Font]flag\f[] 1694275970Scyalways 1695275970Scyrestricts access, i.e., an entry with no flags indicates that free 1696275970Scyaccess to the server is to be given. 1697275970ScyThe flags are not orthogonal, 1698275970Scyin that more restrictive flags will often make less restrictive 1699275970Scyones redundant. 1700275970ScyThe flags can generally be classed into two 1701275970Scycategories, those which restrict time service and those which 1702275970Scyrestrict informational queries and attempts to do run-time 1703275970Scyreconfiguration of the server. 1704275970ScyOne or more of the following flags 1705275970Scymay be specified: 1706275970Scy.RS 1707275970Scy.TP 7 1708275970Scy.NOP \f\*[B-Font]ignore\f[] 1709275970ScyDeny packets of all kinds, including 1710285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1711275970Scyand 1712285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1713275970Scyqueries. 1714275970Scy.TP 7 1715275970Scy.NOP \f\*[B-Font]kod\f[] 1716275970ScyIf this flag is set when an access violation occurs, a kiss-o'-death 1717275970Scy(KoD) packet is sent. 1718275970ScyKoD packets are rate limited to no more than one 1719275970Scyper second. 1720275970ScyIf another KoD packet occurs within one second after the 1721275970Scylast one, the packet is dropped. 1722275970Scy.TP 7 1723275970Scy.NOP \f\*[B-Font]limited\f[] 1724275970ScyDeny service if the packet spacing violates the lower limits specified 1725298770Sdelphijin the 1726298770Sdelphij\f\*[B-Font]discard\f[] 1727298770Sdelphijcommand. 1728275970ScyA history of clients is kept using the 1729275970Scymonitoring capability of 1730285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[]. 1731275970ScyThus, monitoring is always active as 1732275970Scylong as there is a restriction entry with the 1733275970Scy\f\*[B-Font]limited\f[] 1734275970Scyflag. 1735275970Scy.TP 7 1736275970Scy.NOP \f\*[B-Font]lowpriotrap\f[] 1737275970ScyDeclare traps set by matching hosts to be low priority. 1738275970ScyThe 1739275970Scynumber of traps a server can maintain is limited (the current limit 1740275970Scyis 3). 1741275970ScyTraps are usually assigned on a first come, first served 1742275970Scybasis, with later trap requestors being denied service. 1743275970ScyThis flag 1744275970Scymodifies the assignment algorithm by allowing low priority traps to 1745275970Scybe overridden by later requests for normal priority traps. 1746275970Scy.TP 7 1747275970Scy.NOP \f\*[B-Font]nomodify\f[] 1748275970ScyDeny 1749285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1750275970Scyand 1751285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1752275970Scyqueries which attempt to modify the state of the 1753275970Scyserver (i.e., run time reconfiguration). 1754275970ScyQueries which return 1755275970Scyinformation are permitted. 1756275970Scy.TP 7 1757275970Scy.NOP \f\*[B-Font]noquery\f[] 1758275970ScyDeny 1759285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1760275970Scyand 1761285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1762275970Scyqueries. 1763275970ScyTime service is not affected. 1764275970Scy.TP 7 1765275970Scy.NOP \f\*[B-Font]nopeer\f[] 1766275970ScyDeny packets which would result in mobilizing a new association. 1767275970ScyThis 1768275970Scyincludes broadcast and symmetric active packets when a configured 1769275970Scyassociation does not exist. 1770275970ScyIt also includes 1771275970Scy\f\*[B-Font]pool\f[] 1772275970Scyassociations, so if you want to use servers from a 1773275970Scy\f\*[B-Font]pool\f[] 1774275970Scydirective and also want to use 1775275970Scy\f\*[B-Font]nopeer\f[] 1776275970Scyby default, you'll want a 1777275970Scy\f\*[B-Font]restrict source ...\f[] \f\*[B-Font]line\f[] \f\*[B-Font]as\f[] \f\*[B-Font]well\f[] \f\*[B-Font]that\f[] \f\*[B-Font]does\f[] 1778275970Scy.TP 7 1779275970Scy.NOP not 1780275970Scyinclude the 1781275970Scy\f\*[B-Font]nopeer\f[] 1782275970Scydirective. 1783275970Scy.TP 7 1784275970Scy.NOP \f\*[B-Font]noserve\f[] 1785275970ScyDeny all packets except 1786285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1787275970Scyand 1788285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 1789275970Scyqueries. 1790275970Scy.TP 7 1791275970Scy.NOP \f\*[B-Font]notrap\f[] 1792275970ScyDecline to provide mode 6 control message trap service to matching 1793275970Scyhosts. 1794298770SdelphijThe trap service is a subsystem of the 1795298770Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 1796298770Sdelphijcontrol message 1797275970Scyprotocol which is intended for use by remote event logging programs. 1798275970Scy.TP 7 1799275970Scy.NOP \f\*[B-Font]notrust\f[] 1800275970ScyDeny service unless the packet is cryptographically authenticated. 1801275970Scy.TP 7 1802275970Scy.NOP \f\*[B-Font]ntpport\f[] 1803275970ScyThis is actually a match algorithm modifier, rather than a 1804275970Scyrestriction flag. 1805275970ScyIts presence causes the restriction entry to be 1806275970Scymatched only if the source port in the packet is the standard NTP 1807275970ScyUDP port (123). 1808275970ScyBoth 1809275970Scy\f\*[B-Font]ntpport\f[] 1810275970Scyand 1811275970Scy\f\*[B-Font]non-ntpport\f[] 1812275970Scymay 1813275970Scybe specified. 1814275970ScyThe 1815275970Scy\f\*[B-Font]ntpport\f[] 1816275970Scyis considered more specific and 1817275970Scyis sorted later in the list. 1818275970Scy.TP 7 1819275970Scy.NOP \f\*[B-Font]version\f[] 1820275970ScyDeny packets that do not match the current NTP version. 1821275970Scy.RE 1822275970Scy.sp \n(Ppu 1823275970Scy.ne 2 1824275970Scy 1825275970ScyDefault restriction list entries with the flags ignore, interface, 1826275970Scyntpport, for each of the local host's interface addresses are 1827275970Scyinserted into the table at startup to prevent the server 1828275970Scyfrom attempting to synchronize to its own time. 1829275970ScyA default entry is also always present, though if it is 1830275970Scyotherwise unconfigured; no flags are associated 1831275970Scywith the default entry (i.e., everything besides your own 1832275970ScyNTP server is unrestricted). 1833275970Scy.PP 1834275970Scy.SH Automatic NTP Configuration Options 1835275970Scy.SS Manycasting 1836275970ScyManycasting is a automatic discovery and configuration paradigm 1837275970Scynew to NTPv4. 1838275970ScyIt is intended as a means for a multicast client 1839275970Scyto troll the nearby network neighborhood to find cooperating 1840275970Scymanycast servers, validate them using cryptographic means 1841275970Scyand evaluate their time values with respect to other servers 1842275970Scythat might be lurking in the vicinity. 1843275970ScyThe intended result is that each manycast client mobilizes 1844275970Scyclient associations with some number of the "best" 1845275970Scyof the nearby manycast servers, yet automatically reconfigures 1846275970Scyto sustain this number of servers should one or another fail. 1847275970Scy.sp \n(Ppu 1848275970Scy.ne 2 1849275970Scy 1850275970ScyNote that the manycasting paradigm does not coincide 1851275970Scywith the anycast paradigm described in RFC-1546, 1852275970Scywhich is designed to find a single server from a clique 1853275970Scyof servers providing the same service. 1854275970ScyThe manycast paradigm is designed to find a plurality 1855275970Scyof redundant servers satisfying defined optimality criteria. 1856275970Scy.sp \n(Ppu 1857275970Scy.ne 2 1858275970Scy 1859275970ScyManycasting can be used with either symmetric key 1860275970Scyor public key cryptography. 1861275970ScyThe public key infrastructure (PKI) 1862275970Scyoffers the best protection against compromised keys 1863275970Scyand is generally considered stronger, at least with relatively 1864275970Scylarge key sizes. 1865275970ScyIt is implemented using the Autokey protocol and 1866275970Scythe OpenSSL cryptographic library available from 1867275970Scy\f[C]http://www.openssl.org/\f[]. 1868275970ScyThe library can also be used with other NTPv4 modes 1869275970Scyas well and is highly recommended, especially for broadcast modes. 1870275970Scy.sp \n(Ppu 1871275970Scy.ne 2 1872275970Scy 1873275970ScyA persistent manycast client association is configured 1874298770Sdelphijusing the 1875298770Sdelphij\f\*[B-Font]manycastclient\f[] 1876298770Sdelphijcommand, which is similar to the 1877298770Sdelphij\f\*[B-Font]server\f[] 1878298770Sdelphijcommand but with a multicast (IPv4 class 1879275970Scy\f\*[B-Font]D\f[] 1880275970Scyor IPv6 prefix 1881275970Scy\f\*[B-Font]FF\f[]) 1882275970Scygroup address. 1883275970ScyThe IANA has designated IPv4 address 224.1.1.1 1884275970Scyand IPv6 address FF05::101 (site local) for NTP. 1885275970ScyWhen more servers are needed, it broadcasts manycast 1886275970Scyclient messages to this address at the minimum feasible rate 1887275970Scyand minimum feasible time-to-live (TTL) hops, depending 1888275970Scyon how many servers have already been found. 1889275970ScyThere can be as many manycast client associations 1890275970Scyas different group address, each one serving as a template 1891275970Scyfor a future ephemeral unicast client/server association. 1892275970Scy.sp \n(Ppu 1893275970Scy.ne 2 1894275970Scy 1895275970ScyManycast servers configured with the 1896275970Scy\f\*[B-Font]manycastserver\f[] 1897275970Scycommand listen on the specified group address for manycast 1898275970Scyclient messages. 1899275970ScyNote the distinction between manycast client, 1900275970Scywhich actively broadcasts messages, and manycast server, 1901275970Scywhich passively responds to them. 1902275970ScyIf a manycast server is 1903275970Scyin scope of the current TTL and is itself synchronized 1904275970Scyto a valid source and operating at a stratum level equal 1905275970Scyto or lower than the manycast client, it replies to the 1906275970Scymanycast client message with an ordinary unicast server message. 1907275970Scy.sp \n(Ppu 1908275970Scy.ne 2 1909275970Scy 1910275970ScyThe manycast client receiving this message mobilizes 1911275970Scyan ephemeral client/server association according to the 1912275970Scymatching manycast client template, but only if cryptographically 1913275970Scyauthenticated and the server stratum is less than or equal 1914275970Scyto the client stratum. 1915275970ScyAuthentication is explicitly required 1916275970Scyand either symmetric key or public key (Autokey) can be used. 1917275970ScyThen, the client polls the server at its unicast address 1918275970Scyin burst mode in order to reliably set the host clock 1919275970Scyand validate the source. 1920275970ScyThis normally results 1921275970Scyin a volley of eight client/server at 2-s intervals 1922275970Scyduring which both the synchronization and cryptographic 1923275970Scyprotocols run concurrently. 1924275970ScyFollowing the volley, 1925275970Scythe client runs the NTP intersection and clustering 1926275970Scyalgorithms, which act to discard all but the "best" 1927275970Scyassociations according to stratum and synchronization 1928275970Scydistance. 1929275970ScyThe surviving associations then continue 1930275970Scyin ordinary client/server mode. 1931275970Scy.sp \n(Ppu 1932275970Scy.ne 2 1933275970Scy 1934275970ScyThe manycast client polling strategy is designed to reduce 1935275970Scyas much as possible the volume of manycast client messages 1936275970Scyand the effects of implosion due to near-simultaneous 1937275970Scyarrival of manycast server messages. 1938275970ScyThe strategy is determined by the 1939275970Scy\f\*[B-Font]manycastclient\f[], 1940275970Scy\f\*[B-Font]tos\f[] 1941275970Scyand 1942275970Scy\f\*[B-Font]ttl\f[] 1943275970Scyconfiguration commands. 1944275970ScyThe manycast poll interval is 1945275970Scynormally eight times the system poll interval, 1946275970Scywhich starts out at the 1947275970Scy\f\*[B-Font]minpoll\f[] 1948275970Scyvalue specified in the 1949275970Scy\f\*[B-Font]manycastclient\f[], 1950275970Scycommand and, under normal circumstances, increments to the 1951275970Scy\f\*[B-Font]maxpolll\f[] 1952275970Scyvalue specified in this command. 1953275970ScyInitially, the TTL is 1954298770Sdelphijset at the minimum hops specified by the 1955298770Sdelphij\f\*[B-Font]ttl\f[] 1956298770Sdelphijcommand. 1957275970ScyAt each retransmission the TTL is increased until reaching 1958275970Scythe maximum hops specified by this command or a sufficient 1959275970Scynumber client associations have been found. 1960275970ScyFurther retransmissions use the same TTL. 1961275970Scy.sp \n(Ppu 1962275970Scy.ne 2 1963275970Scy 1964275970ScyThe quality and reliability of the suite of associations 1965275970Scydiscovered by the manycast client is determined by the NTP 1966275970Scymitigation algorithms and the 1967275970Scy\f\*[B-Font]minclock\f[] 1968275970Scyand 1969275970Scy\f\*[B-Font]minsane\f[] 1970275970Scyvalues specified in the 1971275970Scy\f\*[B-Font]tos\f[] 1972275970Scyconfiguration command. 1973275970ScyAt least 1974275970Scy\f\*[B-Font]minsane\f[] 1975275970Scycandidate servers must be available and the mitigation 1976275970Scyalgorithms produce at least 1977275970Scy\f\*[B-Font]minclock\f[] 1978275970Scysurvivors in order to synchronize the clock. 1979275970ScyByzantine agreement principles require at least four 1980275970Scycandidates in order to correctly discard a single falseticker. 1981275970ScyFor legacy purposes, 1982275970Scy\f\*[B-Font]minsane\f[] 1983275970Scydefaults to 1 and 1984275970Scy\f\*[B-Font]minclock\f[] 1985275970Scydefaults to 3. 1986275970ScyFor manycast service 1987275970Scy\f\*[B-Font]minsane\f[] 1988275970Scyshould be explicitly set to 4, assuming at least that 1989275970Scynumber of servers are available. 1990275970Scy.sp \n(Ppu 1991275970Scy.ne 2 1992275970Scy 1993275970ScyIf at least 1994275970Scy\f\*[B-Font]minclock\f[] 1995275970Scyservers are found, the manycast poll interval is immediately 1996275970Scyset to eight times 1997275970Scy\f\*[B-Font]maxpoll\f[]. 1998275970ScyIf less than 1999275970Scy\f\*[B-Font]minclock\f[] 2000275970Scyservers are found when the TTL has reached the maximum hops, 2001275970Scythe manycast poll interval is doubled. 2002275970ScyFor each transmission 2003275970Scyafter that, the poll interval is doubled again until 2004275970Scyreaching the maximum of eight times 2005275970Scy\f\*[B-Font]maxpoll\f[]. 2006275970ScyFurther transmissions use the same poll interval and 2007275970ScyTTL values. 2008275970ScyNote that while all this is going on, 2009275970Scyeach client/server association found is operating normally 2010275970Scyit the system poll interval. 2011275970Scy.sp \n(Ppu 2012275970Scy.ne 2 2013275970Scy 2014275970ScyAdministratively scoped multicast boundaries are normally 2015275970Scyspecified by the network router configuration and, 2016275970Scyin the case of IPv6, the link/site scope prefix. 2017275970ScyBy default, the increment for TTL hops is 32 starting 2018275970Scyfrom 31; however, the 2019275970Scy\f\*[B-Font]ttl\f[] 2020275970Scyconfiguration command can be 2021275970Scyused to modify the values to match the scope rules. 2022275970Scy.sp \n(Ppu 2023275970Scy.ne 2 2024275970Scy 2025275970ScyIt is often useful to narrow the range of acceptable 2026275970Scyservers which can be found by manycast client associations. 2027275970ScyBecause manycast servers respond only when the client 2028275970Scystratum is equal to or greater than the server stratum, 2029275970Scyprimary (stratum 1) servers fill find only primary servers 2030275970Scyin TTL range, which is probably the most common objective. 2031275970ScyHowever, unless configured otherwise, all manycast clients 2032275970Scyin TTL range will eventually find all primary servers 2033275970Scyin TTL range, which is probably not the most common 2034275970Scyobjective in large networks. 2035275970ScyThe 2036275970Scy\f\*[B-Font]tos\f[] 2037275970Scycommand can be used to modify this behavior. 2038275970ScyServers with stratum below 2039275970Scy\f\*[B-Font]floor\f[] 2040275970Scyor above 2041275970Scy\f\*[B-Font]ceiling\f[] 2042275970Scyspecified in the 2043275970Scy\f\*[B-Font]tos\f[] 2044275970Scycommand are strongly discouraged during the selection 2045275970Scyprocess; however, these servers may be temporally 2046275970Scyaccepted if the number of servers within TTL range is 2047275970Scyless than 2048275970Scy\f\*[B-Font]minclock\f[]. 2049275970Scy.sp \n(Ppu 2050275970Scy.ne 2 2051275970Scy 2052275970ScyThe above actions occur for each manycast client message, 2053275970Scywhich repeats at the designated poll interval. 2054275970ScyHowever, once the ephemeral client association is mobilized, 2055275970Scysubsequent manycast server replies are discarded, 2056275970Scysince that would result in a duplicate association. 2057275970ScyIf during a poll interval the number of client associations 2058275970Scyfalls below 2059275970Scy\f\*[B-Font]minclock\f[], 2060275970Scyall manycast client prototype associations are reset 2061275970Scyto the initial poll interval and TTL hops and operation 2062275970Scyresumes from the beginning. 2063275970ScyIt is important to avoid 2064275970Scyfrequent manycast client messages, since each one requires 2065275970Scyall manycast servers in TTL range to respond. 2066275970ScyThe result could well be an implosion, either minor or major, 2067275970Scydepending on the number of servers in range. 2068275970ScyThe recommended value for 2069275970Scy\f\*[B-Font]maxpoll\f[] 2070275970Scyis 12 (4,096 s). 2071275970Scy.sp \n(Ppu 2072275970Scy.ne 2 2073275970Scy 2074275970ScyIt is possible and frequently useful to configure a host 2075275970Scyas both manycast client and manycast server. 2076275970ScyA number of hosts configured this way and sharing a common 2077275970Scygroup address will automatically organize themselves 2078275970Scyin an optimum configuration based on stratum and 2079275970Scysynchronization distance. 2080275970ScyFor example, consider an NTP 2081275970Scysubnet of two primary servers and a hundred or more 2082275970Scydependent clients. 2083275970ScyWith two exceptions, all servers 2084275970Scyand clients have identical configuration files including both 2085275970Scy\f\*[B-Font]multicastclient\f[] 2086275970Scyand 2087275970Scy\f\*[B-Font]multicastserver\f[] 2088275970Scycommands using, for instance, multicast group address 2089275970Scy239.1.1.1. 2090275970ScyThe only exception is that each primary server 2091275970Scyconfiguration file must include commands for the primary 2092275970Scyreference source such as a GPS receiver. 2093275970Scy.sp \n(Ppu 2094275970Scy.ne 2 2095275970Scy 2096275970ScyThe remaining configuration files for all secondary 2097275970Scyservers and clients have the same contents, except for the 2098275970Scy\f\*[B-Font]tos\f[] 2099275970Scycommand, which is specific for each stratum level. 2100275970ScyFor stratum 1 and stratum 2 servers, that command is 2101275970Scynot necessary. 2102275970ScyFor stratum 3 and above servers the 2103275970Scy\f\*[B-Font]floor\f[] 2104275970Scyvalue is set to the intended stratum number. 2105275970ScyThus, all stratum 3 configuration files are identical, 2106275970Scyall stratum 4 files are identical and so forth. 2107275970Scy.sp \n(Ppu 2108275970Scy.ne 2 2109275970Scy 2110275970ScyOnce operations have stabilized in this scenario, 2111275970Scythe primary servers will find the primary reference source 2112275970Scyand each other, since they both operate at the same 2113275970Scystratum (1), but not with any secondary server or client, 2114275970Scysince these operate at a higher stratum. 2115275970ScyThe secondary 2116275970Scyservers will find the servers at the same stratum level. 2117275970ScyIf one of the primary servers loses its GPS receiver, 2118275970Scyit will continue to operate as a client and other clients 2119275970Scywill time out the corresponding association and 2120275970Scyre-associate accordingly. 2121275970Scy.sp \n(Ppu 2122275970Scy.ne 2 2123275970Scy 2124275970ScySome administrators prefer to avoid running 2125285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2126275970Scycontinuously and run either 2127289999Sglebius\fCsntp\f[]\fR(@SNTP_MS@)\f[] 2128275970Scyor 2129285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2130275970Scy\f\*[B-Font]\-q\f[] 2131275970Scyas a cron job. 2132275970ScyIn either case the servers must be 2133275970Scyconfigured in advance and the program fails if none are 2134275970Scyavailable when the cron job runs. 2135275970ScyA really slick 2136275970Scyapplication of manycast is with 2137285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2138275970Scy\f\*[B-Font]\-q\f[]. 2139275970ScyThe program wakes up, scans the local landscape looking 2140275970Scyfor the usual suspects, selects the best from among 2141275970Scythe rascals, sets the clock and then departs. 2142275970ScyServers do not have to be configured in advance and 2143275970Scyall clients throughout the network can have the same 2144275970Scyconfiguration file. 2145275970Scy.SS Manycast Interactions with Autokey 2146275970ScyEach time a manycast client sends a client mode packet 2147275970Scyto a multicast group address, all manycast servers 2148275970Scyin scope generate a reply including the host name 2149275970Scyand status word. 2150275970ScyThe manycast clients then run 2151275970Scythe Autokey protocol, which collects and verifies 2152275970Scyall certificates involved. 2153275970ScyFollowing the burst interval 2154275970Scyall but three survivors are cast off, 2155275970Scybut the certificates remain in the local cache. 2156275970ScyIt often happens that several complete signing trails 2157275970Scyfrom the client to the primary servers are collected in this way. 2158275970Scy.sp \n(Ppu 2159275970Scy.ne 2 2160275970Scy 2161275970ScyAbout once an hour or less often if the poll interval 2162275970Scyexceeds this, the client regenerates the Autokey key list. 2163275970ScyThis is in general transparent in client/server mode. 2164275970ScyHowever, about once per day the server private value 2165275970Scyused to generate cookies is refreshed along with all 2166275970Scymanycast client associations. 2167275970ScyIn this case all 2168275970Scycryptographic values including certificates is refreshed. 2169275970ScyIf a new certificate has been generated since 2170275970Scythe last refresh epoch, it will automatically revoke 2171275970Scyall prior certificates that happen to be in the 2172275970Scycertificate cache. 2173275970ScyAt the same time, the manycast 2174275970Scyscheme starts all over from the beginning and 2175275970Scythe expanding ring shrinks to the minimum and increments 2176275970Scyfrom there while collecting all servers in scope. 2177275970Scy.SS Manycast Options 2178275970Scy.TP 7 2179275970Scy.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[]] 2180275970ScyThis command affects the clock selection and clustering 2181275970Scyalgorithms. 2182275970ScyIt can be used to select the quality and 2183275970Scyquantity of peers used to synchronize the system clock 2184275970Scyand is most useful in manycast mode. 2185275970ScyThe variables operate 2186275970Scyas follows: 2187275970Scy.RS 2188275970Scy.TP 7 2189275970Scy.NOP \f\*[B-Font]ceiling\f[] \f\*[I-Font]ceiling\f[] 2190275970ScyPeers with strata above 2191275970Scy\f\*[B-Font]ceiling\f[] 2192275970Scywill be discarded if there are at least 2193275970Scy\f\*[B-Font]minclock\f[] 2194275970Scypeers remaining. 2195275970ScyThis value defaults to 15, but can be changed 2196275970Scyto any number from 1 to 15. 2197275970Scy.TP 7 2198275970Scy.NOP \f\*[B-Font]cohort\f[] {0 | 1 } 2199275970ScyThis is a binary flag which enables (0) or disables (1) 2200275970Scymanycast server replies to manycast clients with the same 2201275970Scystratum level. 2202275970ScyThis is useful to reduce implosions where 2203275970Scylarge numbers of clients with the same stratum level 2204275970Scyare present. 2205275970ScyThe default is to enable these replies. 2206275970Scy.TP 7 2207275970Scy.NOP \f\*[B-Font]floor\f[] \f\*[I-Font]floor\f[] 2208275970ScyPeers with strata below 2209275970Scy\f\*[B-Font]floor\f[] 2210275970Scywill be discarded if there are at least 2211275970Scy\f\*[B-Font]minclock\f[] 2212275970Scypeers remaining. 2213275970ScyThis value defaults to 1, but can be changed 2214275970Scyto any number from 1 to 15. 2215275970Scy.TP 7 2216275970Scy.NOP \f\*[B-Font]minclock\f[] \f\*[I-Font]minclock\f[] 2217289999SglebiusThe clustering algorithm repeatedly casts out outlier 2218275970Scyassociations until no more than 2219275970Scy\f\*[B-Font]minclock\f[] 2220275970Scyassociations remain. 2221275970ScyThis value defaults to 3, 2222275970Scybut can be changed to any number from 1 to the number of 2223275970Scyconfigured sources. 2224275970Scy.TP 7 2225275970Scy.NOP \f\*[B-Font]minsane\f[] \f\*[I-Font]minsane\f[] 2226275970ScyThis is the minimum number of candidates available 2227275970Scyto the clock selection algorithm in order to produce 2228275970Scyone or more truechimers for the clustering algorithm. 2229275970ScyIf fewer than this number are available, the clock is 2230275970Scyundisciplined and allowed to run free. 2231275970ScyThe default is 1 2232275970Scyfor legacy purposes. 2233275970ScyHowever, according to principles of 2234275970ScyByzantine agreement, 2235275970Scy\f\*[B-Font]minsane\f[] 2236275970Scyshould be at least 4 in order to detect and discard 2237275970Scya single falseticker. 2238275970Scy.RE 2239275970Scy.TP 7 2240275970Scy.NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]hop\f[] \f\*[I-Font]...\f[] 2241275970ScyThis command specifies a list of TTL values in increasing 2242275970Scyorder, up to 8 values can be specified. 2243275970ScyIn manycast mode these values are used in turn 2244275970Scyin an expanding-ring search. 2245275970ScyThe default is eight 2246275970Scymultiples of 32 starting at 31. 2247275970Scy.PP 2248275970Scy.SH Reference Clock Support 2249275970ScyThe NTP Version 4 daemon supports some three dozen different radio, 2250275970Scysatellite and modem reference clocks plus a special pseudo-clock 2251275970Scyused for backup or when no other clock source is available. 2252275970ScyDetailed descriptions of individual device drivers and options can 2253275970Scybe found in the 2254275970Scy"Reference Clock Drivers" 2255275970Scypage 2256275970Scy(available as part of the HTML documentation 2257275970Scyprovided in 2258275970Scy\fI/usr/share/doc/ntp\f[]). 2259275970ScyAdditional information can be found in the pages linked 2260275970Scythere, including the 2261275970Scy"Debugging Hints for Reference Clock Drivers" 2262275970Scyand 2263275970Scy"How To Write a Reference Clock Driver" 2264275970Scypages 2265275970Scy(available as part of the HTML documentation 2266275970Scyprovided in 2267275970Scy\fI/usr/share/doc/ntp\f[]). 2268275970ScyIn addition, support for a PPS 2269275970Scysignal is available as described in the 2270275970Scy"Pulse-per-second (PPS) Signal Interfacing" 2271275970Scypage 2272275970Scy(available as part of the HTML documentation 2273275970Scyprovided in 2274275970Scy\fI/usr/share/doc/ntp\f[]). 2275275970ScyMany 2276275970Scydrivers support special line discipline/streams modules which can 2277275970Scysignificantly improve the accuracy using the driver. 2278275970ScyThese are 2279275970Scydescribed in the 2280275970Scy"Line Disciplines and Streams Drivers" 2281275970Scypage 2282275970Scy(available as part of the HTML documentation 2283275970Scyprovided in 2284275970Scy\fI/usr/share/doc/ntp\f[]). 2285275970Scy.sp \n(Ppu 2286275970Scy.ne 2 2287275970Scy 2288275970ScyA reference clock will generally (though not always) be a radio 2289275970Scytimecode receiver which is synchronized to a source of standard 2290275970Scytime such as the services offered by the NRC in Canada and NIST and 2291275970ScyUSNO in the US. 2292275970ScyThe interface between the computer and the timecode 2293275970Scyreceiver is device dependent, but is usually a serial port. 2294275970ScyA 2295275970Scydevice driver specific to each reference clock must be selected and 2296275970Scycompiled in the distribution; however, most common radio, satellite 2297275970Scyand modem clocks are included by default. 2298275970ScyNote that an attempt to 2299275970Scyconfigure a reference clock when the driver has not been compiled 2300275970Scyor the hardware port has not been appropriately configured results 2301275970Scyin a scalding remark to the system log file, but is otherwise non 2302275970Scyhazardous. 2303275970Scy.sp \n(Ppu 2304275970Scy.ne 2 2305275970Scy 2306275970ScyFor the purposes of configuration, 2307285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2308275970Scytreats 2309275970Scyreference clocks in a manner analogous to normal NTP peers as much 2310275970Scyas possible. 2311275970ScyReference clocks are identified by a syntactically 2312275970Scycorrect but invalid IP address, in order to distinguish them from 2313275970Scynormal NTP peers. 2314275970ScyReference clock addresses are of the form 2315275970Scy\f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[], 2316275970Scywhere 2317275970Scy\f\*[I-Font]t\f[] 2318275970Scyis an integer 2319275970Scydenoting the clock type and 2320275970Scy\f\*[I-Font]u\f[] 2321275970Scyindicates the unit 2322275970Scynumber in the range 0-3. 2323275970ScyWhile it may seem overkill, it is in fact 2324275970Scysometimes useful to configure multiple reference clocks of the same 2325275970Scytype, in which case the unit numbers must be unique. 2326275970Scy.sp \n(Ppu 2327275970Scy.ne 2 2328275970Scy 2329275970ScyThe 2330275970Scy\f\*[B-Font]server\f[] 2331275970Scycommand is used to configure a reference 2332275970Scyclock, where the 2333275970Scy\f\*[I-Font]address\f[] 2334275970Scyargument in that command 2335275970Scyis the clock address. 2336275970ScyThe 2337275970Scy\f\*[B-Font]key\f[], 2338275970Scy\f\*[B-Font]version\f[] 2339275970Scyand 2340275970Scy\f\*[B-Font]ttl\f[] 2341275970Scyoptions are not used for reference clock support. 2342275970ScyThe 2343275970Scy\f\*[B-Font]mode\f[] 2344275970Scyoption is added for reference clock support, as 2345275970Scydescribed below. 2346275970ScyThe 2347275970Scy\f\*[B-Font]prefer\f[] 2348275970Scyoption can be useful to 2349275970Scypersuade the server to cherish a reference clock with somewhat more 2350275970Scyenthusiasm than other reference clocks or peers. 2351275970ScyFurther 2352275970Scyinformation on this option can be found in the 2353275970Scy"Mitigation Rules and the prefer Keyword" 2354275970Scy(available as part of the HTML documentation 2355275970Scyprovided in 2356275970Scy\fI/usr/share/doc/ntp\f[]) 2357275970Scypage. 2358275970ScyThe 2359275970Scy\f\*[B-Font]minpoll\f[] 2360275970Scyand 2361275970Scy\f\*[B-Font]maxpoll\f[] 2362275970Scyoptions have 2363275970Scymeaning only for selected clock drivers. 2364275970ScySee the individual clock 2365275970Scydriver document pages for additional information. 2366275970Scy.sp \n(Ppu 2367275970Scy.ne 2 2368275970Scy 2369275970ScyThe 2370275970Scy\f\*[B-Font]fudge\f[] 2371275970Scycommand is used to provide additional 2372275970Scyinformation for individual clock drivers and normally follows 2373275970Scyimmediately after the 2374275970Scy\f\*[B-Font]server\f[] 2375275970Scycommand. 2376275970ScyThe 2377275970Scy\f\*[I-Font]address\f[] 2378275970Scyargument specifies the clock address. 2379275970ScyThe 2380275970Scy\f\*[B-Font]refid\f[] 2381275970Scyand 2382275970Scy\f\*[B-Font]stratum\f[] 2383275970Scyoptions can be used to 2384275970Scyoverride the defaults for the device. 2385275970ScyThere are two optional 2386275970Scydevice-dependent time offsets and four flags that can be included 2387275970Scyin the 2388275970Scy\f\*[B-Font]fudge\f[] 2389275970Scycommand as well. 2390275970Scy.sp \n(Ppu 2391275970Scy.ne 2 2392275970Scy 2393275970ScyThe stratum number of a reference clock is by default zero. 2394275970ScySince the 2395285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2396275970Scydaemon adds one to the stratum of each 2397275970Scypeer, a primary server ordinarily displays an external stratum of 2398275970Scyone. 2399275970ScyIn order to provide engineered backups, it is often useful to 2400275970Scyspecify the reference clock stratum as greater than zero. 2401275970ScyThe 2402275970Scy\f\*[B-Font]stratum\f[] 2403275970Scyoption is used for this purpose. 2404275970ScyAlso, in cases 2405275970Scyinvolving both a reference clock and a pulse-per-second (PPS) 2406275970Scydiscipline signal, it is useful to specify the reference clock 2407275970Scyidentifier as other than the default, depending on the driver. 2408275970ScyThe 2409275970Scy\f\*[B-Font]refid\f[] 2410275970Scyoption is used for this purpose. 2411275970ScyExcept where noted, 2412275970Scythese options apply to all clock drivers. 2413275970Scy.SS Reference Clock Commands 2414275970Scy.TP 7 2415275970Scy.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[]] 2416275970ScyThis command can be used to configure reference clocks in 2417275970Scyspecial ways. 2418275970ScyThe options are interpreted as follows: 2419275970Scy.RS 2420275970Scy.TP 7 2421275970Scy.NOP \f\*[B-Font]prefer\f[] 2422275970ScyMarks the reference clock as preferred. 2423275970ScyAll other things being 2424275970Scyequal, this host will be chosen for synchronization among a set of 2425275970Scycorrectly operating hosts. 2426275970ScySee the 2427275970Scy"Mitigation Rules and the prefer Keyword" 2428275970Scypage 2429275970Scy(available as part of the HTML documentation 2430275970Scyprovided in 2431275970Scy\fI/usr/share/doc/ntp\f[]) 2432275970Scyfor further information. 2433275970Scy.TP 7 2434275970Scy.NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[] 2435275970ScySpecifies a mode number which is interpreted in a 2436275970Scydevice-specific fashion. 2437275970ScyFor instance, it selects a dialing 2438275970Scyprotocol in the ACTS driver and a device subtype in the 2439275970Scyparse 2440275970Scydrivers. 2441275970Scy.TP 7 2442275970Scy.NOP \f\*[B-Font]minpoll\f[] \f\*[I-Font]int\f[] 2443275970Scy.TP 7 2444275970Scy.NOP \f\*[B-Font]maxpoll\f[] \f\*[I-Font]int\f[] 2445275970ScyThese options specify the minimum and maximum polling interval 2446275970Scyfor reference clock messages, as a power of 2 in seconds 2447275970ScyFor 2448275970Scymost directly connected reference clocks, both 2449275970Scy\f\*[B-Font]minpoll\f[] 2450275970Scyand 2451275970Scy\f\*[B-Font]maxpoll\f[] 2452275970Scydefault to 6 (64 s). 2453275970ScyFor modem reference clocks, 2454275970Scy\f\*[B-Font]minpoll\f[] 2455275970Scydefaults to 10 (17.1 m) and 2456275970Scy\f\*[B-Font]maxpoll\f[] 2457275970Scydefaults to 14 (4.5 h). 2458275970ScyThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2459275970Scy.RE 2460275970Scy.TP 7 2461275970Scy.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[]] 2462275970ScyThis command can be used to configure reference clocks in 2463275970Scyspecial ways. 2464275970ScyIt must immediately follow the 2465275970Scy\f\*[B-Font]server\f[] 2466275970Scycommand which configures the driver. 2467275970ScyNote that the same capability 2468275970Scyis possible at run time using the 2469285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2470275970Scyprogram. 2471275970ScyThe options are interpreted as 2472275970Scyfollows: 2473275970Scy.RS 2474275970Scy.TP 7 2475275970Scy.NOP \f\*[B-Font]time1\f[] \f\*[I-Font]sec\f[] 2476275970ScySpecifies a constant to be added to the time offset produced by 2477275970Scythe driver, a fixed-point decimal number in seconds. 2478275970ScyThis is used 2479275970Scyas a calibration constant to adjust the nominal time offset of a 2480275970Scyparticular clock to agree with an external standard, such as a 2481275970Scyprecision PPS signal. 2482275970ScyIt also provides a way to correct a 2483275970Scysystematic error or bias due to serial port or operating system 2484275970Scylatencies, different cable lengths or receiver internal delay. 2485275970ScyThe 2486275970Scyspecified offset is in addition to the propagation delay provided 2487275970Scyby other means, such as internal DIPswitches. 2488275970ScyWhere a calibration 2489275970Scyfor an individual system and driver is available, an approximate 2490275970Scycorrection is noted in the driver documentation pages. 2491275970ScyNote: in order to facilitate calibration when more than one 2492275970Scyradio clock or PPS signal is supported, a special calibration 2493275970Scyfeature is available. 2494275970ScyIt takes the form of an argument to the 2495275970Scy\f\*[B-Font]enable\f[] 2496275970Scycommand described in 2497275970Scy\fIMiscellaneous\f[] \fIOptions\f[] 2498275970Scypage and operates as described in the 2499275970Scy"Reference Clock Drivers" 2500275970Scypage 2501275970Scy(available as part of the HTML documentation 2502275970Scyprovided in 2503275970Scy\fI/usr/share/doc/ntp\f[]). 2504275970Scy.TP 7 2505275970Scy.NOP \f\*[B-Font]time2\f[] \f\*[I-Font]secs\f[] 2506275970ScySpecifies a fixed-point decimal number in seconds, which is 2507275970Scyinterpreted in a driver-dependent way. 2508275970ScySee the descriptions of 2509275970Scyspecific drivers in the 2510275970Scy"Reference Clock Drivers" 2511275970Scypage 2512275970Scy(available as part of the HTML documentation 2513275970Scyprovided in 2514275970Scy\fI/usr/share/doc/ntp\f[]). 2515275970Scy.TP 7 2516275970Scy.NOP \f\*[B-Font]stratum\f[] \f\*[I-Font]int\f[] 2517275970ScySpecifies the stratum number assigned to the driver, an integer 2518275970Scybetween 0 and 15. 2519275970ScyThis number overrides the default stratum number 2520275970Scyordinarily assigned by the driver itself, usually zero. 2521275970Scy.TP 7 2522275970Scy.NOP \f\*[B-Font]refid\f[] \f\*[I-Font]string\f[] 2523275970ScySpecifies an ASCII string of from one to four characters which 2524275970Scydefines the reference identifier used by the driver. 2525275970ScyThis string 2526275970Scyoverrides the default identifier ordinarily assigned by the driver 2527275970Scyitself. 2528275970Scy.TP 7 2529275970Scy.NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[] 2530275970ScySpecifies a mode number which is interpreted in a 2531275970Scydevice-specific fashion. 2532275970ScyFor instance, it selects a dialing 2533275970Scyprotocol in the ACTS driver and a device subtype in the 2534275970Scyparse 2535275970Scydrivers. 2536275970Scy.TP 7 2537275970Scy.NOP \f\*[B-Font]flag1\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2538275970Scy.TP 7 2539275970Scy.NOP \f\*[B-Font]flag2\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2540275970Scy.TP 7 2541275970Scy.NOP \f\*[B-Font]flag3\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2542275970Scy.TP 7 2543275970Scy.NOP \f\*[B-Font]flag4\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2544275970ScyThese four flags are used for customizing the clock driver. 2545275970ScyThe 2546275970Scyinterpretation of these values, and whether they are used at all, 2547275970Scyis a function of the particular clock driver. 2548275970ScyHowever, by 2549275970Scyconvention 2550275970Scy\f\*[B-Font]flag4\f[] 2551275970Scyis used to enable recording monitoring 2552275970Scydata to the 2553275970Scy\f\*[B-Font]clockstats\f[] 2554275970Scyfile configured with the 2555275970Scy\f\*[B-Font]filegen\f[] 2556275970Scycommand. 2557275970ScyFurther information on the 2558275970Scy\f\*[B-Font]filegen\f[] 2559275970Scycommand can be found in 2560275970Scy\fIMonitoring\f[] \fIOptions\f[]. 2561275970Scy.RE 2562275970Scy.PP 2563275970Scy.SH Miscellaneous Options 2564275970Scy.TP 7 2565275970Scy.NOP \f\*[B-Font]broadcastdelay\f[] \f\*[I-Font]seconds\f[] 2566275970ScyThe broadcast and multicast modes require a special calibration 2567275970Scyto determine the network delay between the local and remote 2568275970Scyservers. 2569275970ScyOrdinarily, this is done automatically by the initial 2570275970Scyprotocol exchanges between the client and server. 2571275970ScyIn some cases, 2572275970Scythe calibration procedure may fail due to network or server access 2573275970Scycontrols, for example. 2574275970ScyThis command specifies the default delay to 2575275970Scybe used under these circumstances. 2576275970ScyTypically (for Ethernet), a 2577275970Scynumber between 0.003 and 0.007 seconds is appropriate. 2578275970ScyThe default 2579275970Scywhen this command is not used is 0.004 seconds. 2580275970Scy.TP 7 2581275970Scy.NOP \f\*[B-Font]calldelay\f[] \f\*[I-Font]delay\f[] 2582275970ScyThis option controls the delay in seconds between the first and second 2583275970Scypackets sent in burst or iburst mode to allow additional time for a modem 2584275970Scyor ISDN call to complete. 2585275970Scy.TP 7 2586275970Scy.NOP \f\*[B-Font]driftfile\f[] \f\*[I-Font]driftfile\f[] 2587275970ScyThis command specifies the complete path and name of the file used to 2588275970Scyrecord the frequency of the local clock oscillator. 2589275970ScyThis is the same 2590275970Scyoperation as the 2591275970Scy\f\*[B-Font]\-f\f[] 2592275970Scycommand line option. 2593275970ScyIf the file exists, it is read at 2594275970Scystartup in order to set the initial frequency and then updated once per 2595275970Scyhour with the current frequency computed by the daemon. 2596275970ScyIf the file name is 2597275970Scyspecified, but the file itself does not exist, the starts with an initial 2598275970Scyfrequency of zero and creates the file when writing it for the first time. 2599275970ScyIf this command is not given, the daemon will always start with an initial 2600275970Scyfrequency of zero. 2601275970Scy.sp \n(Ppu 2602275970Scy.ne 2 2603275970Scy 2604275970ScyThe file format consists of a single line containing a single 2605275970Scyfloating point number, which records the frequency offset measured 2606275970Scyin parts-per-million (PPM). 2607275970ScyThe file is updated by first writing 2608275970Scythe current drift value into a temporary file and then renaming 2609275970Scythis file to replace the old version. 2610275970ScyThis implies that 2611285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2612275970Scymust have write permission for the directory the 2613275970Scydrift file is located in, and that file system links, symbolic or 2614275970Scyotherwise, should be avoided. 2615275970Scy.TP 7 2616285612Sdelphij.NOP \f\*[B-Font]dscp\f[] \f\*[I-Font]value\f[] 2617285612SdelphijThis option specifies the Differentiated Services Control Point (DSCP) value, 2618298770Sdelphija 6-bit code. 2619298770SdelphijThe default value is 46, signifying Expedited Forwarding. 2620285612Sdelphij.TP 7 2621294904Sdelphij.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]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]] 2622275970Scy.TP 7 2623294904Sdelphij.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]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]] 2624275970ScyProvides a way to enable or disable various server options. 2625275970ScyFlags not mentioned are unaffected. 2626275970ScyNote that all of these flags 2627275970Scycan be controlled remotely using the 2628285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2629275970Scyutility program. 2630275970Scy.RS 2631275970Scy.TP 7 2632275970Scy.NOP \f\*[B-Font]auth\f[] 2633275970ScyEnables the server to synchronize with unconfigured peers only if the 2634275970Scypeer has been correctly authenticated using either public key or 2635275970Scyprivate key cryptography. 2636275970ScyThe default for this flag is 2637275970Scy\f\*[B-Font]enable\f[]. 2638275970Scy.TP 7 2639275970Scy.NOP \f\*[B-Font]bclient\f[] 2640275970ScyEnables the server to listen for a message from a broadcast or 2641275970Scymulticast server, as in the 2642275970Scy\f\*[B-Font]multicastclient\f[] 2643275970Scycommand with default 2644275970Scyaddress. 2645275970ScyThe default for this flag is 2646275970Scy\f\*[B-Font]disable\f[]. 2647275970Scy.TP 7 2648275970Scy.NOP \f\*[B-Font]calibrate\f[] 2649275970ScyEnables the calibrate feature for reference clocks. 2650275970ScyThe default for 2651275970Scythis flag is 2652275970Scy\f\*[B-Font]disable\f[]. 2653275970Scy.TP 7 2654275970Scy.NOP \f\*[B-Font]kernel\f[] 2655275970ScyEnables the kernel time discipline, if available. 2656275970ScyThe default for this 2657275970Scyflag is 2658275970Scy\f\*[B-Font]enable\f[] 2659275970Scyif support is available, otherwise 2660275970Scy\f\*[B-Font]disable\f[]. 2661275970Scy.TP 7 2662275970Scy.NOP \f\*[B-Font]mode7\f[] 2663275970ScyEnables processing of NTP mode 7 implementation-specific requests 2664275970Scywhich are used by the deprecated 2665285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2666275970Scyprogram. 2667275970ScyThe default for this flag is disable. 2668275970ScyThis flag is excluded from runtime configuration using 2669285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[]. 2670275970ScyThe 2671285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 2672275970Scyprogram provides the same capabilities as 2673285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2674275970Scyusing standard mode 6 requests. 2675275970Scy.TP 7 2676275970Scy.NOP \f\*[B-Font]monitor\f[] 2677275970ScyEnables the monitoring facility. 2678275970ScySee the 2679285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[] 2680275970Scyprogram 2681275970Scyand the 2682275970Scy\f\*[B-Font]monlist\f[] 2683275970Scycommand or further information. 2684275970ScyThe 2685275970Scydefault for this flag is 2686275970Scy\f\*[B-Font]enable\f[]. 2687275970Scy.TP 7 2688275970Scy.NOP \f\*[B-Font]ntp\f[] 2689275970ScyEnables time and frequency discipline. 2690275970ScyIn effect, this switch opens and 2691275970Scycloses the feedback loop, which is useful for testing. 2692275970ScyThe default for 2693275970Scythis flag is 2694275970Scy\f\*[B-Font]enable\f[]. 2695275970Scy.TP 7 2696275970Scy.NOP \f\*[B-Font]stats\f[] 2697275970ScyEnables the statistics facility. 2698275970ScySee the 2699275970Scy\fIMonitoring\f[] \fIOptions\f[] 2700275970Scysection for further information. 2701275970ScyThe default for this flag is 2702275970Scy\f\*[B-Font]disable\f[]. 2703294904Sdelphij.TP 7 2704294904Sdelphij.NOP \f\*[B-Font]unpeer_crypto_early\f[] 2705294904SdelphijBy default, if 2706294904Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2707294904Sdelphijreceives an autokey packet that fails TEST9, 2708294904Sdelphija crypto failure, 2709294904Sdelphijthe association is immediately cleared. 2710294904SdelphijThis is almost certainly a feature, 2711294904Sdelphijbut if, in spite of the current recommendation of not using autokey, 2712294904Sdelphijyou are 2713294904Sdelphij.B still 2714294904Sdelphijusing autokey 2715294904Sdelphij.B and 2716294904Sdelphijyou are seeing this sort of DoS attack 2717294904Sdelphijdisabling this flag will delay 2718294904Sdelphijtearing down the association until the reachability counter 2719294904Sdelphijbecomes zero. 2720294904SdelphijYou can check your 2721294904Sdelphij\f\*[B-Font]peerstats\f[] 2722294904Sdelphijfile for evidence of any of these attacks. 2723294904SdelphijThe 2724294904Sdelphijdefault for this flag is 2725294904Sdelphij\f\*[B-Font]enable\f[]. 2726294904Sdelphij.TP 7 2727294904Sdelphij.NOP \f\*[B-Font]unpeer_crypto_nak_early\f[] 2728294904SdelphijBy default, if 2729294904Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2730294904Sdelphijreceives a crypto-NAK packet that 2731294904Sdelphijpasses the duplicate packet and origin timestamp checks 2732294904Sdelphijthe association is immediately cleared. 2733294904SdelphijWhile this is generally a feature 2734294904Sdelphijas it allows for quick recovery if a server key has changed, 2735294904Sdelphija properly forged and appropriately delivered crypto-NAK packet 2736294904Sdelphijcan be used in a DoS attack. 2737294904SdelphijIf you have active noticable problems with this type of DoS attack 2738294904Sdelphijthen you should consider 2739294904Sdelphijdisabling this option. 2740294904SdelphijYou can check your 2741294904Sdelphij\f\*[B-Font]peerstats\f[] 2742294904Sdelphijfile for evidence of any of these attacks. 2743294904SdelphijThe 2744294904Sdelphijdefault for this flag is 2745294904Sdelphij\f\*[B-Font]enable\f[]. 2746294904Sdelphij.TP 7 2747294904Sdelphij.NOP \f\*[B-Font]unpeer_digest_early\f[] 2748294904SdelphijBy default, if 2749294904Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2750294904Sdelphijreceives what should be an authenticated packet 2751294904Sdelphijthat passes other packet sanity checks but 2752294904Sdelphijcontains an invalid digest 2753294904Sdelphijthe association is immediately cleared. 2754294904SdelphijWhile this is generally a feature 2755294904Sdelphijas it allows for quick recovery, 2756294904Sdelphijif this type of packet is carefully forged and sent 2757294904Sdelphijduring an appropriate window it can be used for a DoS attack. 2758294904SdelphijIf you have active noticable problems with this type of DoS attack 2759294904Sdelphijthen you should consider 2760294904Sdelphijdisabling this option. 2761294904SdelphijYou can check your 2762294904Sdelphij\f\*[B-Font]peerstats\f[] 2763294904Sdelphijfile for evidence of any of these attacks. 2764294904SdelphijThe 2765294904Sdelphijdefault for this flag is 2766294904Sdelphij\f\*[B-Font]enable\f[]. 2767275970Scy.RE 2768275970Scy.TP 7 2769275970Scy.NOP \f\*[B-Font]includefile\f[] \f\*[I-Font]includefile\f[] 2770275970ScyThis command allows additional configuration commands 2771275970Scyto be included from a separate file. 2772275970ScyInclude files may 2773275970Scybe nested to a depth of five; upon reaching the end of any 2774275970Scyinclude file, command processing resumes in the previous 2775275970Scyconfiguration file. 2776275970ScyThis option is useful for sites that run 2777285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2778275970Scyon multiple hosts, with (mostly) common options (e.g., a 2779275970Scyrestriction list). 2780275970Scy.TP 7 2781285612Sdelphij.NOP \f\*[B-Font]leapsmearinterval\f[] \f\*[I-Font]seconds\f[] 2782285612SdelphijThis EXPERIMENTAL option is only available if 2783285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2784285612Sdelphijwas built with the 2785285612Sdelphij\f\*[B-Font]\--enable-leap-smear\f[] 2786285612Sdelphijoption to the 2787285612Sdelphij\f\*[B-Font]configure\f[] 2788285612Sdelphijscript. 2789285612SdelphijIt specifies the interval over which a leap second correction will be applied. 2790285612SdelphijRecommended values for this option are between 2791285612Sdelphij7200 (2 hours) and 86400 (24 hours). 2792285612Sdelphij.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2793285612SdelphijSee http://bugs.ntp.org/2855 for more information. 2794285612Sdelphij.TP 7 2795275970Scy.NOP \f\*[B-Font]logconfig\f[] \f\*[I-Font]configkeyword\f[] 2796275970ScyThis command controls the amount and type of output written to 2797275970Scythe system 2798285612Sdelphij\fCsyslog\f[]\fR(3)\f[] 2799275970Scyfacility or the alternate 2800275970Scy\f\*[B-Font]logfile\f[] 2801275970Scylog file. 2802275970ScyBy default, all output is turned on. 2803275970ScyAll 2804275970Scy\f\*[I-Font]configkeyword\f[] 2805275970Scykeywords can be prefixed with 2806275970Scy\[oq]=\[cq], 2807275970Scy\[oq]+\[cq] 2808275970Scyand 2809275970Scy\[oq]\-\[cq], 2810275970Scywhere 2811275970Scy\[oq]=\[cq] 2812275970Scysets the 2813285612Sdelphij\fCsyslog\f[]\fR(3)\f[] 2814275970Scypriority mask, 2815275970Scy\[oq]+\[cq] 2816275970Scyadds and 2817275970Scy\[oq]\-\[cq] 2818275970Scyremoves 2819275970Scymessages. 2820285612Sdelphij\fCsyslog\f[]\fR(3)\f[] 2821275970Scymessages can be controlled in four 2822275970Scyclasses 2823275970Scy(\f\*[B-Font]clock\f[], \f\*[B-Font]peer\f[], \f\*[B-Font]sys\f[] and \f\*[B-Font]sync\f[]). 2824275970ScyWithin these classes four types of messages can be 2825275970Scycontrolled: informational messages 2826275970Scy(\f\*[B-Font]info\f[]), 2827275970Scyevent messages 2828275970Scy(\f\*[B-Font]events\f[]), 2829275970Scystatistics messages 2830275970Scy(\f\*[B-Font]statistics\f[]) 2831275970Scyand 2832275970Scystatus messages 2833275970Scy(\f\*[B-Font]status\f[]). 2834275970Scy.sp \n(Ppu 2835275970Scy.ne 2 2836275970Scy 2837275970ScyConfiguration keywords are formed by concatenating the message class with 2838275970Scythe event class. 2839275970ScyThe 2840275970Scy\f\*[B-Font]all\f[] 2841275970Scyprefix can be used instead of a message class. 2842275970ScyA 2843275970Scymessage class may also be followed by the 2844275970Scy\f\*[B-Font]all\f[] 2845275970Scykeyword to enable/disable all 2846298770Sdelphijmessages of the respective message class. 2847298770SdelphijThus, a minimal log configuration 2848275970Scycould look like this: 2849275970Scy.br 2850275970Scy.in +4 2851275970Scy.nf 2852275970Scylogconfig =syncstatus +sysevents 2853275970Scy.in -4 2854275970Scy.fi 2855275970Scy.sp \n(Ppu 2856275970Scy.ne 2 2857275970Scy 2858275970ScyThis would just list the synchronizations state of 2859285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[] 2860275970Scyand the major system events. 2861275970ScyFor a simple reference server, the 2862275970Scyfollowing minimum message configuration could be useful: 2863275970Scy.br 2864275970Scy.in +4 2865275970Scy.nf 2866275970Scylogconfig =syncall +clockall 2867275970Scy.in -4 2868275970Scy.fi 2869275970Scy.sp \n(Ppu 2870275970Scy.ne 2 2871275970Scy 2872275970ScyThis configuration will list all clock information and 2873275970Scysynchronization information. 2874275970ScyAll other events and messages about 2875275970Scypeers, system events and so on is suppressed. 2876275970Scy.TP 7 2877275970Scy.NOP \f\*[B-Font]logfile\f[] \f\*[I-Font]logfile\f[] 2878275970ScyThis command specifies the location of an alternate log file to 2879275970Scybe used instead of the default system 2880285612Sdelphij\fCsyslog\f[]\fR(3)\f[] 2881275970Scyfacility. 2882298770SdelphijThis is the same operation as the 2883298770Sdelphij\f\*[B-Font]\-l\f[] 2884298770Sdelphijcommand line option. 2885275970Scy.TP 7 2886275970Scy.NOP \f\*[B-Font]setvar\f[] \f\*[I-Font]variable\f[] [\f\*[B-Font]default\f[]] 2887275970ScyThis command adds an additional system variable. 2888275970ScyThese 2889275970Scyvariables can be used to distribute additional information such as 2890275970Scythe access policy. 2891275970ScyIf the variable of the form 2892275970Scy\fIname\f[]\fI=\f[]\f\*[I-Font]value\f[] 2893275970Scyis followed by the 2894275970Scy\f\*[B-Font]default\f[] 2895275970Scykeyword, the 2896275970Scyvariable will be listed as part of the default system variables 2897285612Sdelphij(\fCntpq\f[]\fR(@NTPQ_MS@)\f[] \f\*[B-Font]rv\f[] command)). 2898275970ScyThese additional variables serve 2899275970Scyinformational purposes only. 2900275970ScyThey are not related to the protocol 2901275970Scyother that they can be listed. 2902275970ScyThe known protocol variables will 2903275970Scyalways override any variables defined via the 2904275970Scy\f\*[B-Font]setvar\f[] 2905275970Scymechanism. 2906275970ScyThere are three special variables that contain the names 2907275970Scyof all variable of the same group. 2908275970ScyThe 2909275970Scy\fIsys_var_list\f[] 2910275970Scyholds 2911275970Scythe names of all system variables. 2912275970ScyThe 2913275970Scy\fIpeer_var_list\f[] 2914275970Scyholds 2915275970Scythe names of all peer variables and the 2916275970Scy\fIclock_var_list\f[] 2917275970Scyholds the names of the reference clock variables. 2918275970Scy.TP 7 2919285612Sdelphij.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[]] 2920275970ScyThis command can be used to alter several system variables in 2921275970Scyvery exceptional circumstances. 2922275970ScyIt should occur in the 2923275970Scyconfiguration file before any other configuration options. 2924275970ScyThe 2925275970Scydefault values of these variables have been carefully optimized for 2926275970Scya wide range of network speeds and reliability expectations. 2927275970ScyIn 2928275970Scygeneral, they interact in intricate ways that are hard to predict 2929275970Scyand some combinations can result in some very nasty behavior. 2930275970ScyVery 2931275970Scyrarely is it necessary to change the default values; but, some 2932275970Scyfolks cannot resist twisting the knobs anyway and this command is 2933275970Scyfor them. 2934275970ScyEmphasis added: twisters are on their own and can expect 2935275970Scyno help from the support group. 2936275970Scy.sp \n(Ppu 2937275970Scy.ne 2 2938275970Scy 2939275970ScyThe variables operate as follows: 2940275970Scy.RS 2941275970Scy.TP 7 2942275970Scy.NOP \f\*[B-Font]allan\f[] \f\*[I-Font]allan\f[] 2943275970ScyThe argument becomes the new value for the minimum Allan 2944275970Scyintercept, which is a parameter of the PLL/FLL clock discipline 2945275970Scyalgorithm. 2946275970ScyThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 2947275970Scylimit. 2948275970Scy.TP 7 2949275970Scy.NOP \f\*[B-Font]dispersion\f[] \f\*[I-Font]dispersion\f[] 2950275970ScyThe argument becomes the new value for the dispersion increase rate, 2951275970Scynormally .000015 s/s. 2952275970Scy.TP 7 2953275970Scy.NOP \f\*[B-Font]freq\f[] \f\*[I-Font]freq\f[] 2954275970ScyThe argument becomes the initial value of the frequency offset in 2955275970Scyparts-per-million. 2956275970ScyThis overrides the value in the frequency file, if 2957275970Scypresent, and avoids the initial training state if it is not. 2958275970Scy.TP 7 2959275970Scy.NOP \f\*[B-Font]huffpuff\f[] \f\*[I-Font]huffpuff\f[] 2960275970ScyThe argument becomes the new value for the experimental 2961275970Scyhuff-n'-puff filter span, which determines the most recent interval 2962275970Scythe algorithm will search for a minimum delay. 2963275970ScyThe lower limit is 2964275970Scy900 s (15 m), but a more reasonable value is 7200 (2 hours). 2965275970ScyThere 2966275970Scyis no default, since the filter is not enabled unless this command 2967275970Scyis given. 2968275970Scy.TP 7 2969275970Scy.NOP \f\*[B-Font]panic\f[] \f\*[I-Font]panic\f[] 2970275970ScyThe argument is the panic threshold, normally 1000 s. 2971275970ScyIf set to zero, 2972275970Scythe panic sanity check is disabled and a clock offset of any value will 2973275970Scybe accepted. 2974275970Scy.TP 7 2975275970Scy.NOP \f\*[B-Font]step\f[] \f\*[I-Font]step\f[] 2976275970ScyThe argument is the step threshold, which by default is 0.128 s. 2977275970ScyIt can 2978275970Scybe set to any positive number in seconds. 2979275970ScyIf set to zero, step 2980275970Scyadjustments will never occur. 2981275970ScyNote: The kernel time discipline is 2982275970Scydisabled if the step threshold is set to zero or greater than the 2983275970Scydefault. 2984275970Scy.TP 7 2985285612Sdelphij.NOP \f\*[B-Font]stepback\f[] \f\*[I-Font]stepback\f[] 2986285612SdelphijThe argument is the step threshold for the backward direction, 2987285612Sdelphijwhich by default is 0.128 s. 2988285612SdelphijIt can 2989285612Sdelphijbe set to any positive number in seconds. 2990285612SdelphijIf both the forward and backward step thresholds are set to zero, step 2991285612Sdelphijadjustments will never occur. 2992285612SdelphijNote: The kernel time discipline is 2993285612Sdelphijdisabled if 2994285612Sdelphijeach direction of step threshold are either 2995285612Sdelphijset to zero or greater than .5 second. 2996285612Sdelphij.TP 7 2997285612Sdelphij.NOP \f\*[B-Font]stepfwd\f[] \f\*[I-Font]stepfwd\f[] 2998285612SdelphijAs for stepback, but for the forward direction. 2999285612Sdelphij.TP 7 3000275970Scy.NOP \f\*[B-Font]stepout\f[] \f\*[I-Font]stepout\f[] 3001275970ScyThe argument is the stepout timeout, which by default is 900 s. 3002275970ScyIt can 3003275970Scybe set to any positive number in seconds. 3004275970ScyIf set to zero, the stepout 3005275970Scypulses will not be suppressed. 3006275970Scy.RE 3007275970Scy.TP 7 3008275970Scy.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[]] 3009275970Scy.RS 3010275970Scy.TP 7 3011275970Scy.NOP \f\*[B-Font]memlock\f[] \f\*[I-Font]Nmegabytes\f[] 3012289999SglebiusSpecify the number of megabytes of memory that should be 3013289999Sglebiusallocated and locked. 3014289999SglebiusProbably only available under Linux, this option may be useful 3015275970Scywhen dropping root (the 3016275970Scy\f\*[B-Font]\-i\f[] 3017275970Scyoption). 3018289999SglebiusThe default is 32 megabytes on non-Linux machines, and \-1 under Linux. 3019289999Sglebius-1 means "do not lock the process into memory". 3020289999Sglebius0 means "lock whatever memory the process wants into memory". 3021275970Scy.TP 7 3022275970Scy.NOP \f\*[B-Font]stacksize\f[] \f\*[I-Font]N4kPages\f[] 3023275970ScySpecifies the maximum size of the process stack on systems with the 3024285612Sdelphij\fBmlockall\f[]\fR()\f[] 3025285612Sdelphijfunction. 3026285612SdelphijDefaults to 50 4k pages (200 4k pages in OpenBSD). 3027275970Scy.TP 7 3028275970Scy.NOP \f\*[B-Font]filenum\f[] \f\*[I-Font]Nfiledescriptors\f[] 3029298770SdelphijSpecifies the maximum number of file descriptors ntpd may have open at once. 3030298770SdelphijDefaults to the system default. 3031275970Scy.RE 3032275970Scy.TP 7 3033275970Scy.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[]] 3034275970ScyThis command configures a trap receiver at the given host 3035275970Scyaddress and port number for sending messages with the specified 3036275970Scylocal interface address. 3037275970ScyIf the port number is unspecified, a value 3038275970Scyof 18447 is used. 3039275970ScyIf the interface address is not specified, the 3040275970Scymessage is sent with a source address of the local interface the 3041275970Scymessage is sent through. 3042275970ScyNote that on a multihomed host the 3043275970Scyinterface used may vary from time to time with routing changes. 3044275970Scy.sp \n(Ppu 3045275970Scy.ne 2 3046275970Scy 3047275970ScyThe trap receiver will generally log event messages and other 3048275970Scyinformation from the server in a log file. 3049275970ScyWhile such monitor 3050275970Scyprograms may also request their own trap dynamically, configuring a 3051275970Scytrap receiver will ensure that no messages are lost when the server 3052275970Scyis started. 3053275970Scy.TP 7 3054275970Scy.NOP \f\*[B-Font]hop\f[] \f\*[I-Font]...\f[] 3055275970ScyThis command specifies a list of TTL values in increasing order, up to 8 3056275970Scyvalues can be specified. 3057275970ScyIn manycast mode these values are used in turn in 3058275970Scyan expanding-ring search. 3059275970ScyThe default is eight multiples of 32 starting at 3060275970Scy31. 3061275970Scy.PP 3062275970Scy.SH "OPTIONS" 3063275970Scy.TP 3064275970Scy.NOP \f\*[B-Font]\-\-help\f[] 3065275970ScyDisplay usage information and exit. 3066275970Scy.TP 3067275970Scy.NOP \f\*[B-Font]\-\-more-help\f[] 3068275970ScyPass the extended usage information through a pager. 3069275970Scy.TP 3070275970Scy.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 3071275970ScyOutput version of program and exit. The default mode is `v', a simple 3072275970Scyversion. The `c' mode will print copyright information and `n' will 3073275970Scyprint the full copyright notice. 3074275970Scy.PP 3075275970Scy.SH "OPTION PRESETS" 3076275970ScyAny option that is not marked as \fInot presettable\fP may be preset 3077275970Scyby loading values from environment variables named: 3078275970Scy.nf 3079275970Scy \fBNTP_CONF_<option-name>\fP or \fBNTP_CONF\fP 3080275970Scy.fi 3081275970Scy.ad 3082275970Scy.SH "ENVIRONMENT" 3083275970ScySee \fBOPTION PRESETS\fP for configuration environment variables. 3084275970Scy.SH FILES 3085275970Scy.TP 15 3086275970Scy.NOP \fI/etc/ntp.conf\f[] 3087275970Scythe default name of the configuration file 3088275970Scy.br 3089275970Scy.ns 3090275970Scy.TP 15 3091275970Scy.NOP \fIntp.keys\f[] 3092275970Scyprivate MD5 keys 3093275970Scy.br 3094275970Scy.ns 3095275970Scy.TP 15 3096275970Scy.NOP \fIntpkey\f[] 3097275970ScyRSA private key 3098275970Scy.br 3099275970Scy.ns 3100275970Scy.TP 15 3101275970Scy.NOP \fIntpkey_\f[]\f\*[I-Font]host\f[] 3102275970ScyRSA public key 3103275970Scy.br 3104275970Scy.ns 3105275970Scy.TP 15 3106275970Scy.NOP \fIntp_dh\f[] 3107275970ScyDiffie-Hellman agreement parameters 3108275970Scy.PP 3109275970Scy.SH "EXIT STATUS" 3110275970ScyOne of the following exit values will be returned: 3111275970Scy.TP 3112275970Scy.NOP 0 " (EXIT_SUCCESS)" 3113275970ScySuccessful program execution. 3114275970Scy.TP 3115275970Scy.NOP 1 " (EXIT_FAILURE)" 3116275970ScyThe operation failed or the command syntax was not valid. 3117275970Scy.TP 3118275970Scy.NOP 70 " (EX_SOFTWARE)" 3119275970Scylibopts had an internal operational error. Please report 3120275970Scyit to autogen-users@lists.sourceforge.net. Thank you. 3121275970Scy.PP 3122275970Scy.SH "SEE ALSO" 3123285612Sdelphij\fCntpd\f[]\fR(@NTPD_MS@)\f[], 3124285612Sdelphij\fCntpdc\f[]\fR(@NTPDC_MS@)\f[], 3125285612Sdelphij\fCntpq\f[]\fR(@NTPQ_MS@)\f[] 3126275970Scy.sp \n(Ppu 3127275970Scy.ne 2 3128275970Scy 3129275970ScyIn addition to the manual pages provided, 3130275970Scycomprehensive documentation is available on the world wide web 3131275970Scyat 3132275970Scy\f[C]http://www.ntp.org/\f[]. 3133275970ScyA snapshot of this documentation is available in HTML format in 3134275970Scy\fI/usr/share/doc/ntp\f[]. 3135275970ScyDavid L. Mills, 3136275970Scy\fINetwork Time Protocol (Version 4)\fR, 3137275970ScyRFC5905 3138275970Scy.PP 3139275970Scy 3140275970Scy.SH "AUTHORS" 3141280849ScyThe University of Delaware and Network Time Foundation 3142275970Scy.SH "COPYRIGHT" 3143294904SdelphijCopyright (C) 1992-2016 The University of Delaware and Network Time Foundation all rights reserved. 3144275970ScyThis program is released under the terms of the NTP license, <http://ntp.org/license>. 3145275970Scy.SH BUGS 3146275970ScyThe syntax checking is not picky; some combinations of 3147275970Scyridiculous and even hilarious options and modes may not be 3148275970Scydetected. 3149275970Scy.sp \n(Ppu 3150275970Scy.ne 2 3151275970Scy 3152275970ScyThe 3153275970Scy\fIntpkey_\f[]\f\*[I-Font]host\f[] 3154275970Scyfiles are really digital 3155275970Scycertificates. 3156275970ScyThese should be obtained via secure directory 3157275970Scyservices when they become universally available. 3158275970Scy.sp \n(Ppu 3159275970Scy.ne 2 3160275970Scy 3161275970ScyPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 3162275970Scy.SH NOTES 3163275970ScyThis document was derived from FreeBSD. 3164275970Scy.sp \n(Ppu 3165275970Scy.ne 2 3166275970Scy 3167275970ScyThis manual page was \fIAutoGen\fP-erated from the \fBntp.conf\fP 3168275970Scyoption definitions. 3169