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 13310419Sdelphij.TH ntp.conf 5man "21 Nov 2016" "4.2.8p9" "File Formats" 14275970Scy.\" 15310419Sdelphij.\" EDIT THIS FILE WITH CAUTION (/tmp/.ag-Q_ai3f/ag-2_aa2f) 16275970Scy.\" 17310419Sdelphij.\" It has been AutoGen-ed November 21, 2016 at 08:01:41 AM by AutoGen 5.18.5 18275970Scy.\" From the definitions ntp.conf.def 19275970Scy.\" and the template file agman-cmd.tpl 20275970Scy.SH NAME 21275970Scy\f\*[B-Font]ntp.conf\fP 22275970Scy\- Network Time Protocol (NTP) daemon configuration file format 23275970Scy.SH SYNOPSIS 24275970Scy\f\*[B-Font]ntp.conf\fP 25275970Scy[\f\*[B-Font]\-\-option-name\f[]] 26275970Scy[\f\*[B-Font]\-\-option-name\f[] \f\*[I-Font]value\f[]] 27275970Scy.sp \n(Ppu 28275970Scy.ne 2 29275970Scy 30275970ScyAll arguments must be options. 31275970Scy.sp \n(Ppu 32275970Scy.ne 2 33275970Scy 34275970Scy.SH DESCRIPTION 35275970ScyThe 36275970Scy\f\*[B-Font]ntp.conf\fP 37275970Scyconfiguration file is read at initial startup by the 38290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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(1ntpqmdoc)\f[] 141298770Sdelphijor 142298770Sdelphij\fCntpdc\f[]\fR(1ntpdcmdoc)\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 320290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 561290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 628290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 629275970Scyand 630290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 631275970Scyutility programs. 632275970Scy.sp \n(Ppu 633275970Scy.ne 2 634275970Scy 635275970ScyWhen 636290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 650290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 656290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 657275970Scyutility, while the 658275970Scy\f\*[B-Font]controlkey\f[] 659275970Scycommand selects the key used as the password for the 660290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\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 707290000Sglebius\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 754290000Sglebius\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 854290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\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 879290000Sglebius\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 888290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 889275970Scyand 890290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 928290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\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 1016290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[], 1017290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 1018275970Scyand 1019290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 1033290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 1034275970Scyutility program, which uses a 1035275970Scyproprietary protocol specific to this implementation of 1036290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 1059290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 1060275970Scyand 1061290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 1138290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 1154290000Sglebius\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 1380290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 1454290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 1464290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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(1ntpdmdoc)\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 1558290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 1710290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 1711275970Scyand 1712290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 1730290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 1749290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 1750275970Scyand 1751290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 1759290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 1760275970Scyand 1761290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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 1786290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 1787275970Scyand 1788290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\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(1ntpqmdoc)\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 2125290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2126275970Scycontinuously and run either 2127290000Sglebius\fCsntp\f[]\fR(1sntpmdoc)\f[] 2128275970Scyor 2129290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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 2137290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\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. 2177310419Sdelphij.SS Broadcast Options 2178310419Sdelphij.TP 7 2179310419Sdelphij.NOP \f\*[B-Font]tos\f[] [\f\*[B-Font]bcpollbstep\f[] \f\*[I-Font]gate\f[]] 2180310419SdelphijThis command provides a way to delay, 2181310419Sdelphijby the specified number of broadcast poll intervals, 2182310419Sdelphijbelieving backward time steps from a broadcast server. 2183310419SdelphijBroadcast time networks are expected to be trusted. 2184310419SdelphijIn the event a broadcast server's time is stepped backwards, 2185310419Sdelphijthere is clear benefit to having the clients notice this change 2186310419Sdelphijas soon as possible. 2187310419SdelphijAttacks such as replay attacks can happen, however, 2188310419Sdelphijand even though there are a number of protections built in to 2189310419Sdelphijbroadcast mode, attempts to perform a replay attack are possible. 2190310419SdelphijThis value defaults to 0, but can be changed 2191310419Sdelphijto any number of poll intervals between 0 and 4. 2192275970Scy.SS Manycast Options 2193310419Sdelphij.RS 2194275970Scy.TP 7 2195275970Scy.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[]] 2196275970ScyThis command affects the clock selection and clustering 2197275970Scyalgorithms. 2198275970ScyIt can be used to select the quality and 2199275970Scyquantity of peers used to synchronize the system clock 2200275970Scyand is most useful in manycast mode. 2201275970ScyThe variables operate 2202275970Scyas follows: 2203275970Scy.RS 2204275970Scy.TP 7 2205275970Scy.NOP \f\*[B-Font]ceiling\f[] \f\*[I-Font]ceiling\f[] 2206275970ScyPeers with strata above 2207275970Scy\f\*[B-Font]ceiling\f[] 2208275970Scywill be discarded if there are at least 2209275970Scy\f\*[B-Font]minclock\f[] 2210275970Scypeers remaining. 2211275970ScyThis value defaults to 15, but can be changed 2212275970Scyto any number from 1 to 15. 2213275970Scy.TP 7 2214275970Scy.NOP \f\*[B-Font]cohort\f[] {0 | 1 } 2215275970ScyThis is a binary flag which enables (0) or disables (1) 2216275970Scymanycast server replies to manycast clients with the same 2217275970Scystratum level. 2218275970ScyThis is useful to reduce implosions where 2219275970Scylarge numbers of clients with the same stratum level 2220275970Scyare present. 2221275970ScyThe default is to enable these replies. 2222275970Scy.TP 7 2223275970Scy.NOP \f\*[B-Font]floor\f[] \f\*[I-Font]floor\f[] 2224275970ScyPeers with strata below 2225275970Scy\f\*[B-Font]floor\f[] 2226275970Scywill be discarded if there are at least 2227275970Scy\f\*[B-Font]minclock\f[] 2228275970Scypeers remaining. 2229275970ScyThis value defaults to 1, but can be changed 2230275970Scyto any number from 1 to 15. 2231275970Scy.TP 7 2232275970Scy.NOP \f\*[B-Font]minclock\f[] \f\*[I-Font]minclock\f[] 2233290000SglebiusThe clustering algorithm repeatedly casts out outlier 2234275970Scyassociations until no more than 2235275970Scy\f\*[B-Font]minclock\f[] 2236275970Scyassociations remain. 2237275970ScyThis value defaults to 3, 2238275970Scybut can be changed to any number from 1 to the number of 2239275970Scyconfigured sources. 2240275970Scy.TP 7 2241275970Scy.NOP \f\*[B-Font]minsane\f[] \f\*[I-Font]minsane\f[] 2242275970ScyThis is the minimum number of candidates available 2243275970Scyto the clock selection algorithm in order to produce 2244275970Scyone or more truechimers for the clustering algorithm. 2245275970ScyIf fewer than this number are available, the clock is 2246275970Scyundisciplined and allowed to run free. 2247275970ScyThe default is 1 2248275970Scyfor legacy purposes. 2249275970ScyHowever, according to principles of 2250275970ScyByzantine agreement, 2251275970Scy\f\*[B-Font]minsane\f[] 2252275970Scyshould be at least 4 in order to detect and discard 2253275970Scya single falseticker. 2254275970Scy.RE 2255275970Scy.TP 7 2256275970Scy.NOP \f\*[B-Font]ttl\f[] \f\*[I-Font]hop\f[] \f\*[I-Font]...\f[] 2257275970ScyThis command specifies a list of TTL values in increasing 2258275970Scyorder, up to 8 values can be specified. 2259275970ScyIn manycast mode these values are used in turn 2260275970Scyin an expanding-ring search. 2261275970ScyThe default is eight 2262275970Scymultiples of 32 starting at 31. 2263310419Sdelphij.RE 2264275970Scy.SH Reference Clock Support 2265275970ScyThe NTP Version 4 daemon supports some three dozen different radio, 2266275970Scysatellite and modem reference clocks plus a special pseudo-clock 2267275970Scyused for backup or when no other clock source is available. 2268275970ScyDetailed descriptions of individual device drivers and options can 2269275970Scybe found in the 2270275970Scy"Reference Clock Drivers" 2271275970Scypage 2272275970Scy(available as part of the HTML documentation 2273275970Scyprovided in 2274275970Scy\fI/usr/share/doc/ntp\f[]). 2275275970ScyAdditional information can be found in the pages linked 2276275970Scythere, including the 2277275970Scy"Debugging Hints for Reference Clock Drivers" 2278275970Scyand 2279275970Scy"How To Write a Reference Clock Driver" 2280275970Scypages 2281275970Scy(available as part of the HTML documentation 2282275970Scyprovided in 2283275970Scy\fI/usr/share/doc/ntp\f[]). 2284275970ScyIn addition, support for a PPS 2285275970Scysignal is available as described in the 2286275970Scy"Pulse-per-second (PPS) Signal Interfacing" 2287275970Scypage 2288275970Scy(available as part of the HTML documentation 2289275970Scyprovided in 2290275970Scy\fI/usr/share/doc/ntp\f[]). 2291275970ScyMany 2292275970Scydrivers support special line discipline/streams modules which can 2293275970Scysignificantly improve the accuracy using the driver. 2294275970ScyThese are 2295275970Scydescribed in the 2296275970Scy"Line Disciplines and Streams Drivers" 2297275970Scypage 2298275970Scy(available as part of the HTML documentation 2299275970Scyprovided in 2300275970Scy\fI/usr/share/doc/ntp\f[]). 2301275970Scy.sp \n(Ppu 2302275970Scy.ne 2 2303275970Scy 2304275970ScyA reference clock will generally (though not always) be a radio 2305275970Scytimecode receiver which is synchronized to a source of standard 2306275970Scytime such as the services offered by the NRC in Canada and NIST and 2307275970ScyUSNO in the US. 2308275970ScyThe interface between the computer and the timecode 2309275970Scyreceiver is device dependent, but is usually a serial port. 2310275970ScyA 2311275970Scydevice driver specific to each reference clock must be selected and 2312275970Scycompiled in the distribution; however, most common radio, satellite 2313275970Scyand modem clocks are included by default. 2314275970ScyNote that an attempt to 2315275970Scyconfigure a reference clock when the driver has not been compiled 2316275970Scyor the hardware port has not been appropriately configured results 2317275970Scyin a scalding remark to the system log file, but is otherwise non 2318275970Scyhazardous. 2319275970Scy.sp \n(Ppu 2320275970Scy.ne 2 2321275970Scy 2322275970ScyFor the purposes of configuration, 2323290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2324275970Scytreats 2325275970Scyreference clocks in a manner analogous to normal NTP peers as much 2326275970Scyas possible. 2327275970ScyReference clocks are identified by a syntactically 2328275970Scycorrect but invalid IP address, in order to distinguish them from 2329275970Scynormal NTP peers. 2330275970ScyReference clock addresses are of the form 2331275970Scy\f[C]127.127.\f[]\f\*[I-Font]t\f[].\f\*[I-Font]u\f[], 2332275970Scywhere 2333275970Scy\f\*[I-Font]t\f[] 2334275970Scyis an integer 2335275970Scydenoting the clock type and 2336275970Scy\f\*[I-Font]u\f[] 2337275970Scyindicates the unit 2338275970Scynumber in the range 0-3. 2339275970ScyWhile it may seem overkill, it is in fact 2340275970Scysometimes useful to configure multiple reference clocks of the same 2341275970Scytype, in which case the unit numbers must be unique. 2342275970Scy.sp \n(Ppu 2343275970Scy.ne 2 2344275970Scy 2345275970ScyThe 2346275970Scy\f\*[B-Font]server\f[] 2347275970Scycommand is used to configure a reference 2348275970Scyclock, where the 2349275970Scy\f\*[I-Font]address\f[] 2350275970Scyargument in that command 2351275970Scyis the clock address. 2352275970ScyThe 2353275970Scy\f\*[B-Font]key\f[], 2354275970Scy\f\*[B-Font]version\f[] 2355275970Scyand 2356275970Scy\f\*[B-Font]ttl\f[] 2357275970Scyoptions are not used for reference clock support. 2358275970ScyThe 2359275970Scy\f\*[B-Font]mode\f[] 2360275970Scyoption is added for reference clock support, as 2361275970Scydescribed below. 2362275970ScyThe 2363275970Scy\f\*[B-Font]prefer\f[] 2364275970Scyoption can be useful to 2365275970Scypersuade the server to cherish a reference clock with somewhat more 2366275970Scyenthusiasm than other reference clocks or peers. 2367275970ScyFurther 2368275970Scyinformation on this option can be found in the 2369275970Scy"Mitigation Rules and the prefer Keyword" 2370275970Scy(available as part of the HTML documentation 2371275970Scyprovided in 2372275970Scy\fI/usr/share/doc/ntp\f[]) 2373275970Scypage. 2374275970ScyThe 2375275970Scy\f\*[B-Font]minpoll\f[] 2376275970Scyand 2377275970Scy\f\*[B-Font]maxpoll\f[] 2378275970Scyoptions have 2379275970Scymeaning only for selected clock drivers. 2380275970ScySee the individual clock 2381275970Scydriver document pages for additional information. 2382275970Scy.sp \n(Ppu 2383275970Scy.ne 2 2384275970Scy 2385275970ScyThe 2386275970Scy\f\*[B-Font]fudge\f[] 2387275970Scycommand is used to provide additional 2388275970Scyinformation for individual clock drivers and normally follows 2389275970Scyimmediately after the 2390275970Scy\f\*[B-Font]server\f[] 2391275970Scycommand. 2392275970ScyThe 2393275970Scy\f\*[I-Font]address\f[] 2394275970Scyargument specifies the clock address. 2395275970ScyThe 2396275970Scy\f\*[B-Font]refid\f[] 2397275970Scyand 2398275970Scy\f\*[B-Font]stratum\f[] 2399275970Scyoptions can be used to 2400275970Scyoverride the defaults for the device. 2401275970ScyThere are two optional 2402275970Scydevice-dependent time offsets and four flags that can be included 2403275970Scyin the 2404275970Scy\f\*[B-Font]fudge\f[] 2405275970Scycommand as well. 2406275970Scy.sp \n(Ppu 2407275970Scy.ne 2 2408275970Scy 2409275970ScyThe stratum number of a reference clock is by default zero. 2410275970ScySince the 2411290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2412275970Scydaemon adds one to the stratum of each 2413275970Scypeer, a primary server ordinarily displays an external stratum of 2414275970Scyone. 2415275970ScyIn order to provide engineered backups, it is often useful to 2416275970Scyspecify the reference clock stratum as greater than zero. 2417275970ScyThe 2418275970Scy\f\*[B-Font]stratum\f[] 2419275970Scyoption is used for this purpose. 2420275970ScyAlso, in cases 2421275970Scyinvolving both a reference clock and a pulse-per-second (PPS) 2422275970Scydiscipline signal, it is useful to specify the reference clock 2423275970Scyidentifier as other than the default, depending on the driver. 2424275970ScyThe 2425275970Scy\f\*[B-Font]refid\f[] 2426275970Scyoption is used for this purpose. 2427275970ScyExcept where noted, 2428275970Scythese options apply to all clock drivers. 2429275970Scy.SS Reference Clock Commands 2430310419Sdelphij.RS 2431275970Scy.TP 7 2432275970Scy.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[]] 2433275970ScyThis command can be used to configure reference clocks in 2434275970Scyspecial ways. 2435275970ScyThe options are interpreted as follows: 2436275970Scy.RS 2437275970Scy.TP 7 2438275970Scy.NOP \f\*[B-Font]prefer\f[] 2439275970ScyMarks the reference clock as preferred. 2440275970ScyAll other things being 2441275970Scyequal, this host will be chosen for synchronization among a set of 2442275970Scycorrectly operating hosts. 2443275970ScySee the 2444275970Scy"Mitigation Rules and the prefer Keyword" 2445275970Scypage 2446275970Scy(available as part of the HTML documentation 2447275970Scyprovided in 2448275970Scy\fI/usr/share/doc/ntp\f[]) 2449275970Scyfor further information. 2450275970Scy.TP 7 2451275970Scy.NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[] 2452275970ScySpecifies a mode number which is interpreted in a 2453275970Scydevice-specific fashion. 2454275970ScyFor instance, it selects a dialing 2455275970Scyprotocol in the ACTS driver and a device subtype in the 2456275970Scyparse 2457275970Scydrivers. 2458275970Scy.TP 7 2459275970Scy.NOP \f\*[B-Font]minpoll\f[] \f\*[I-Font]int\f[] 2460275970Scy.TP 7 2461275970Scy.NOP \f\*[B-Font]maxpoll\f[] \f\*[I-Font]int\f[] 2462275970ScyThese options specify the minimum and maximum polling interval 2463275970Scyfor reference clock messages, as a power of 2 in seconds 2464275970ScyFor 2465275970Scymost directly connected reference clocks, both 2466275970Scy\f\*[B-Font]minpoll\f[] 2467275970Scyand 2468275970Scy\f\*[B-Font]maxpoll\f[] 2469275970Scydefault to 6 (64 s). 2470275970ScyFor modem reference clocks, 2471275970Scy\f\*[B-Font]minpoll\f[] 2472275970Scydefaults to 10 (17.1 m) and 2473275970Scy\f\*[B-Font]maxpoll\f[] 2474275970Scydefaults to 14 (4.5 h). 2475275970ScyThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2476275970Scy.RE 2477275970Scy.TP 7 2478275970Scy.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[]] 2479275970ScyThis command can be used to configure reference clocks in 2480275970Scyspecial ways. 2481275970ScyIt must immediately follow the 2482275970Scy\f\*[B-Font]server\f[] 2483275970Scycommand which configures the driver. 2484275970ScyNote that the same capability 2485275970Scyis possible at run time using the 2486290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 2487275970Scyprogram. 2488275970ScyThe options are interpreted as 2489275970Scyfollows: 2490275970Scy.RS 2491275970Scy.TP 7 2492275970Scy.NOP \f\*[B-Font]time1\f[] \f\*[I-Font]sec\f[] 2493275970ScySpecifies a constant to be added to the time offset produced by 2494275970Scythe driver, a fixed-point decimal number in seconds. 2495275970ScyThis is used 2496275970Scyas a calibration constant to adjust the nominal time offset of a 2497275970Scyparticular clock to agree with an external standard, such as a 2498275970Scyprecision PPS signal. 2499275970ScyIt also provides a way to correct a 2500275970Scysystematic error or bias due to serial port or operating system 2501275970Scylatencies, different cable lengths or receiver internal delay. 2502275970ScyThe 2503275970Scyspecified offset is in addition to the propagation delay provided 2504275970Scyby other means, such as internal DIPswitches. 2505275970ScyWhere a calibration 2506275970Scyfor an individual system and driver is available, an approximate 2507275970Scycorrection is noted in the driver documentation pages. 2508275970ScyNote: in order to facilitate calibration when more than one 2509275970Scyradio clock or PPS signal is supported, a special calibration 2510275970Scyfeature is available. 2511275970ScyIt takes the form of an argument to the 2512275970Scy\f\*[B-Font]enable\f[] 2513275970Scycommand described in 2514275970Scy\fIMiscellaneous\f[] \fIOptions\f[] 2515275970Scypage and operates as described in the 2516275970Scy"Reference Clock Drivers" 2517275970Scypage 2518275970Scy(available as part of the HTML documentation 2519275970Scyprovided in 2520275970Scy\fI/usr/share/doc/ntp\f[]). 2521275970Scy.TP 7 2522275970Scy.NOP \f\*[B-Font]time2\f[] \f\*[I-Font]secs\f[] 2523275970ScySpecifies a fixed-point decimal number in seconds, which is 2524275970Scyinterpreted in a driver-dependent way. 2525275970ScySee the descriptions of 2526275970Scyspecific drivers in the 2527275970Scy"Reference Clock Drivers" 2528275970Scypage 2529275970Scy(available as part of the HTML documentation 2530275970Scyprovided in 2531275970Scy\fI/usr/share/doc/ntp\f[]). 2532275970Scy.TP 7 2533275970Scy.NOP \f\*[B-Font]stratum\f[] \f\*[I-Font]int\f[] 2534275970ScySpecifies the stratum number assigned to the driver, an integer 2535275970Scybetween 0 and 15. 2536275970ScyThis number overrides the default stratum number 2537275970Scyordinarily assigned by the driver itself, usually zero. 2538275970Scy.TP 7 2539275970Scy.NOP \f\*[B-Font]refid\f[] \f\*[I-Font]string\f[] 2540275970ScySpecifies an ASCII string of from one to four characters which 2541275970Scydefines the reference identifier used by the driver. 2542275970ScyThis string 2543275970Scyoverrides the default identifier ordinarily assigned by the driver 2544275970Scyitself. 2545275970Scy.TP 7 2546275970Scy.NOP \f\*[B-Font]mode\f[] \f\*[I-Font]int\f[] 2547275970ScySpecifies a mode number which is interpreted in a 2548275970Scydevice-specific fashion. 2549275970ScyFor instance, it selects a dialing 2550275970Scyprotocol in the ACTS driver and a device subtype in the 2551275970Scyparse 2552275970Scydrivers. 2553275970Scy.TP 7 2554275970Scy.NOP \f\*[B-Font]flag1\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2555275970Scy.TP 7 2556275970Scy.NOP \f\*[B-Font]flag2\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2557275970Scy.TP 7 2558275970Scy.NOP \f\*[B-Font]flag3\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2559275970Scy.TP 7 2560275970Scy.NOP \f\*[B-Font]flag4\f[] \f\*[B-Font]0\f[] \f\*[B-Font]\&|\f[] \f\*[B-Font]1\f[] 2561275970ScyThese four flags are used for customizing the clock driver. 2562275970ScyThe 2563275970Scyinterpretation of these values, and whether they are used at all, 2564275970Scyis a function of the particular clock driver. 2565275970ScyHowever, by 2566275970Scyconvention 2567275970Scy\f\*[B-Font]flag4\f[] 2568275970Scyis used to enable recording monitoring 2569275970Scydata to the 2570275970Scy\f\*[B-Font]clockstats\f[] 2571275970Scyfile configured with the 2572275970Scy\f\*[B-Font]filegen\f[] 2573275970Scycommand. 2574275970ScyFurther information on the 2575275970Scy\f\*[B-Font]filegen\f[] 2576275970Scycommand can be found in 2577275970Scy\fIMonitoring\f[] \fIOptions\f[]. 2578275970Scy.RE 2579310419Sdelphij.RE 2580275970Scy.SH Miscellaneous Options 2581310419Sdelphij.RS 2582275970Scy.TP 7 2583275970Scy.NOP \f\*[B-Font]broadcastdelay\f[] \f\*[I-Font]seconds\f[] 2584275970ScyThe broadcast and multicast modes require a special calibration 2585275970Scyto determine the network delay between the local and remote 2586275970Scyservers. 2587275970ScyOrdinarily, this is done automatically by the initial 2588275970Scyprotocol exchanges between the client and server. 2589275970ScyIn some cases, 2590275970Scythe calibration procedure may fail due to network or server access 2591275970Scycontrols, for example. 2592275970ScyThis command specifies the default delay to 2593275970Scybe used under these circumstances. 2594275970ScyTypically (for Ethernet), a 2595275970Scynumber between 0.003 and 0.007 seconds is appropriate. 2596275970ScyThe default 2597275970Scywhen this command is not used is 0.004 seconds. 2598275970Scy.TP 7 2599275970Scy.NOP \f\*[B-Font]calldelay\f[] \f\*[I-Font]delay\f[] 2600275970ScyThis option controls the delay in seconds between the first and second 2601275970Scypackets sent in burst or iburst mode to allow additional time for a modem 2602275970Scyor ISDN call to complete. 2603275970Scy.TP 7 2604275970Scy.NOP \f\*[B-Font]driftfile\f[] \f\*[I-Font]driftfile\f[] 2605275970ScyThis command specifies the complete path and name of the file used to 2606275970Scyrecord the frequency of the local clock oscillator. 2607275970ScyThis is the same 2608275970Scyoperation as the 2609275970Scy\f\*[B-Font]\-f\f[] 2610275970Scycommand line option. 2611275970ScyIf the file exists, it is read at 2612275970Scystartup in order to set the initial frequency and then updated once per 2613275970Scyhour with the current frequency computed by the daemon. 2614275970ScyIf the file name is 2615275970Scyspecified, but the file itself does not exist, the starts with an initial 2616275970Scyfrequency of zero and creates the file when writing it for the first time. 2617275970ScyIf this command is not given, the daemon will always start with an initial 2618275970Scyfrequency of zero. 2619275970Scy.sp \n(Ppu 2620275970Scy.ne 2 2621275970Scy 2622275970ScyThe file format consists of a single line containing a single 2623275970Scyfloating point number, which records the frequency offset measured 2624275970Scyin parts-per-million (PPM). 2625275970ScyThe file is updated by first writing 2626275970Scythe current drift value into a temporary file and then renaming 2627275970Scythis file to replace the old version. 2628275970ScyThis implies that 2629290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2630275970Scymust have write permission for the directory the 2631275970Scydrift file is located in, and that file system links, symbolic or 2632275970Scyotherwise, should be avoided. 2633275970Scy.TP 7 2634290000Sglebius.NOP \f\*[B-Font]dscp\f[] \f\*[I-Font]value\f[] 2635290000SglebiusThis option specifies the Differentiated Services Control Point (DSCP) value, 2636298770Sdelphija 6-bit code. 2637298770SdelphijThe default value is 46, signifying Expedited Forwarding. 2638290000Sglebius.TP 7 2639301301Sdelphij.NOP \f\*[B-Font]enable\f[] [\f\*[B-Font]auth\f[] | \f\*[B-Font]bclient\f[] | \f\*[B-Font]calibrate\f[] | \f\*[B-Font]kernel\f[] | \f\*[B-Font]mode7\f[] | \f\*[B-Font]monitor\f[] | \f\*[B-Font]ntp\f[] | \f\*[B-Font]stats\f[] | \f\*[B-Font]peer_clear_digest_early\f[] | \f\*[B-Font]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]] 2640275970Scy.TP 7 2641301301Sdelphij.NOP \f\*[B-Font]disable\f[] [\f\*[B-Font]auth\f[] | \f\*[B-Font]bclient\f[] | \f\*[B-Font]calibrate\f[] | \f\*[B-Font]kernel\f[] | \f\*[B-Font]mode7\f[] | \f\*[B-Font]monitor\f[] | \f\*[B-Font]ntp\f[] | \f\*[B-Font]stats\f[] | \f\*[B-Font]peer_clear_digest_early\f[] | \f\*[B-Font]unpeer_crypto_early\f[] | \f\*[B-Font]unpeer_crypto_nak_early\f[] | \f\*[B-Font]unpeer_digest_early\f[]] 2642275970ScyProvides a way to enable or disable various server options. 2643275970ScyFlags not mentioned are unaffected. 2644275970ScyNote that all of these flags 2645275970Scycan be controlled remotely using the 2646290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 2647275970Scyutility program. 2648275970Scy.RS 2649275970Scy.TP 7 2650275970Scy.NOP \f\*[B-Font]auth\f[] 2651275970ScyEnables the server to synchronize with unconfigured peers only if the 2652275970Scypeer has been correctly authenticated using either public key or 2653275970Scyprivate key cryptography. 2654275970ScyThe default for this flag is 2655275970Scy\f\*[B-Font]enable\f[]. 2656275970Scy.TP 7 2657275970Scy.NOP \f\*[B-Font]bclient\f[] 2658275970ScyEnables the server to listen for a message from a broadcast or 2659275970Scymulticast server, as in the 2660275970Scy\f\*[B-Font]multicastclient\f[] 2661275970Scycommand with default 2662275970Scyaddress. 2663275970ScyThe default for this flag is 2664275970Scy\f\*[B-Font]disable\f[]. 2665275970Scy.TP 7 2666275970Scy.NOP \f\*[B-Font]calibrate\f[] 2667275970ScyEnables the calibrate feature for reference clocks. 2668275970ScyThe default for 2669275970Scythis flag is 2670275970Scy\f\*[B-Font]disable\f[]. 2671275970Scy.TP 7 2672275970Scy.NOP \f\*[B-Font]kernel\f[] 2673275970ScyEnables the kernel time discipline, if available. 2674275970ScyThe default for this 2675275970Scyflag is 2676275970Scy\f\*[B-Font]enable\f[] 2677275970Scyif support is available, otherwise 2678275970Scy\f\*[B-Font]disable\f[]. 2679275970Scy.TP 7 2680275970Scy.NOP \f\*[B-Font]mode7\f[] 2681275970ScyEnables processing of NTP mode 7 implementation-specific requests 2682275970Scywhich are used by the deprecated 2683290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 2684275970Scyprogram. 2685275970ScyThe default for this flag is disable. 2686275970ScyThis flag is excluded from runtime configuration using 2687290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[]. 2688275970ScyThe 2689290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 2690275970Scyprogram provides the same capabilities as 2691290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 2692275970Scyusing standard mode 6 requests. 2693275970Scy.TP 7 2694275970Scy.NOP \f\*[B-Font]monitor\f[] 2695275970ScyEnables the monitoring facility. 2696275970ScySee the 2697290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[] 2698275970Scyprogram 2699275970Scyand the 2700275970Scy\f\*[B-Font]monlist\f[] 2701275970Scycommand or further information. 2702275970ScyThe 2703275970Scydefault for this flag is 2704275970Scy\f\*[B-Font]enable\f[]. 2705275970Scy.TP 7 2706275970Scy.NOP \f\*[B-Font]ntp\f[] 2707275970ScyEnables time and frequency discipline. 2708275970ScyIn effect, this switch opens and 2709275970Scycloses the feedback loop, which is useful for testing. 2710275970ScyThe default for 2711275970Scythis flag is 2712275970Scy\f\*[B-Font]enable\f[]. 2713275970Scy.TP 7 2714301301Sdelphij.NOP \f\*[B-Font]peer_clear_digest_early\f[] 2715301301SdelphijBy default, if 2716301301Sdelphij\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2717301301Sdelphijis using autokey and it 2718301301Sdelphijreceives a crypto-NAK packet that 2719301301Sdelphijpasses the duplicate packet and origin timestamp checks 2720301301Sdelphijthe peer variables are immediately cleared. 2721301301SdelphijWhile this is generally a feature 2722301301Sdelphijas it allows for quick recovery if a server key has changed, 2723301301Sdelphija properly forged and appropriately delivered crypto-NAK packet 2724301301Sdelphijcan be used in a DoS attack. 2725301301SdelphijIf you have active noticable problems with this type of DoS attack 2726301301Sdelphijthen you should consider 2727301301Sdelphijdisabling this option. 2728301301SdelphijYou can check your 2729301301Sdelphij\f\*[B-Font]peerstats\f[] 2730301301Sdelphijfile for evidence of any of these attacks. 2731301301SdelphijThe 2732301301Sdelphijdefault for this flag is 2733301301Sdelphij\f\*[B-Font]enable\f[]. 2734301301Sdelphij.TP 7 2735275970Scy.NOP \f\*[B-Font]stats\f[] 2736275970ScyEnables the statistics facility. 2737275970ScySee the 2738275970Scy\fIMonitoring\f[] \fIOptions\f[] 2739275970Scysection for further information. 2740275970ScyThe default for this flag is 2741275970Scy\f\*[B-Font]disable\f[]. 2742294904Sdelphij.TP 7 2743294904Sdelphij.NOP \f\*[B-Font]unpeer_crypto_early\f[] 2744294904SdelphijBy default, if 2745294904Sdelphij\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2746294904Sdelphijreceives an autokey packet that fails TEST9, 2747294904Sdelphija crypto failure, 2748294904Sdelphijthe association is immediately cleared. 2749294904SdelphijThis is almost certainly a feature, 2750294904Sdelphijbut if, in spite of the current recommendation of not using autokey, 2751294904Sdelphijyou are 2752294904Sdelphij.B still 2753294904Sdelphijusing autokey 2754294904Sdelphij.B and 2755294904Sdelphijyou are seeing this sort of DoS attack 2756294904Sdelphijdisabling this flag will delay 2757294904Sdelphijtearing down the association until the reachability counter 2758294904Sdelphijbecomes zero. 2759294904SdelphijYou can check your 2760294904Sdelphij\f\*[B-Font]peerstats\f[] 2761294904Sdelphijfile for evidence of any of these attacks. 2762294904SdelphijThe 2763294904Sdelphijdefault for this flag is 2764294904Sdelphij\f\*[B-Font]enable\f[]. 2765294904Sdelphij.TP 7 2766294904Sdelphij.NOP \f\*[B-Font]unpeer_crypto_nak_early\f[] 2767294904SdelphijBy default, if 2768294904Sdelphij\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2769294904Sdelphijreceives a crypto-NAK packet that 2770294904Sdelphijpasses the duplicate packet and origin timestamp checks 2771294904Sdelphijthe association is immediately cleared. 2772294904SdelphijWhile this is generally a feature 2773294904Sdelphijas it allows for quick recovery if a server key has changed, 2774294904Sdelphija properly forged and appropriately delivered crypto-NAK packet 2775294904Sdelphijcan be used in a DoS attack. 2776294904SdelphijIf you have active noticable problems with this type of DoS attack 2777294904Sdelphijthen you should consider 2778294904Sdelphijdisabling this option. 2779294904SdelphijYou can check your 2780294904Sdelphij\f\*[B-Font]peerstats\f[] 2781294904Sdelphijfile for evidence of any of these attacks. 2782294904SdelphijThe 2783294904Sdelphijdefault for this flag is 2784294904Sdelphij\f\*[B-Font]enable\f[]. 2785294904Sdelphij.TP 7 2786294904Sdelphij.NOP \f\*[B-Font]unpeer_digest_early\f[] 2787294904SdelphijBy default, if 2788294904Sdelphij\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2789294904Sdelphijreceives what should be an authenticated packet 2790294904Sdelphijthat passes other packet sanity checks but 2791294904Sdelphijcontains an invalid digest 2792294904Sdelphijthe association is immediately cleared. 2793294904SdelphijWhile this is generally a feature 2794294904Sdelphijas it allows for quick recovery, 2795294904Sdelphijif this type of packet is carefully forged and sent 2796294904Sdelphijduring an appropriate window it can be used for a DoS attack. 2797294904SdelphijIf you have active noticable problems with this type of DoS attack 2798294904Sdelphijthen you should consider 2799294904Sdelphijdisabling this option. 2800294904SdelphijYou can check your 2801294904Sdelphij\f\*[B-Font]peerstats\f[] 2802294904Sdelphijfile for evidence of any of these attacks. 2803294904SdelphijThe 2804294904Sdelphijdefault for this flag is 2805294904Sdelphij\f\*[B-Font]enable\f[]. 2806275970Scy.RE 2807275970Scy.TP 7 2808275970Scy.NOP \f\*[B-Font]includefile\f[] \f\*[I-Font]includefile\f[] 2809275970ScyThis command allows additional configuration commands 2810275970Scyto be included from a separate file. 2811275970ScyInclude files may 2812275970Scybe nested to a depth of five; upon reaching the end of any 2813275970Scyinclude file, command processing resumes in the previous 2814275970Scyconfiguration file. 2815275970ScyThis option is useful for sites that run 2816290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2817275970Scyon multiple hosts, with (mostly) common options (e.g., a 2818275970Scyrestriction list). 2819275970Scy.TP 7 2820290000Sglebius.NOP \f\*[B-Font]leapsmearinterval\f[] \f\*[I-Font]seconds\f[] 2821290000SglebiusThis EXPERIMENTAL option is only available if 2822290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2823290000Sglebiuswas built with the 2824290000Sglebius\f\*[B-Font]\--enable-leap-smear\f[] 2825290000Sglebiusoption to the 2826290000Sglebius\f\*[B-Font]configure\f[] 2827290000Sglebiusscript. 2828290000SglebiusIt specifies the interval over which a leap second correction will be applied. 2829290000SglebiusRecommended values for this option are between 2830290000Sglebius7200 (2 hours) and 86400 (24 hours). 2831290000Sglebius.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2832290000SglebiusSee http://bugs.ntp.org/2855 for more information. 2833290000Sglebius.TP 7 2834275970Scy.NOP \f\*[B-Font]logconfig\f[] \f\*[I-Font]configkeyword\f[] 2835275970ScyThis command controls the amount and type of output written to 2836275970Scythe system 2837290000Sglebius\fCsyslog\f[]\fR(3)\f[] 2838275970Scyfacility or the alternate 2839275970Scy\f\*[B-Font]logfile\f[] 2840275970Scylog file. 2841275970ScyBy default, all output is turned on. 2842275970ScyAll 2843275970Scy\f\*[I-Font]configkeyword\f[] 2844275970Scykeywords can be prefixed with 2845275970Scy\[oq]=\[cq], 2846275970Scy\[oq]+\[cq] 2847275970Scyand 2848275970Scy\[oq]\-\[cq], 2849275970Scywhere 2850275970Scy\[oq]=\[cq] 2851275970Scysets the 2852290000Sglebius\fCsyslog\f[]\fR(3)\f[] 2853275970Scypriority mask, 2854275970Scy\[oq]+\[cq] 2855275970Scyadds and 2856275970Scy\[oq]\-\[cq] 2857275970Scyremoves 2858275970Scymessages. 2859290000Sglebius\fCsyslog\f[]\fR(3)\f[] 2860275970Scymessages can be controlled in four 2861275970Scyclasses 2862275970Scy(\f\*[B-Font]clock\f[], \f\*[B-Font]peer\f[], \f\*[B-Font]sys\f[] and \f\*[B-Font]sync\f[]). 2863275970ScyWithin these classes four types of messages can be 2864275970Scycontrolled: informational messages 2865275970Scy(\f\*[B-Font]info\f[]), 2866275970Scyevent messages 2867275970Scy(\f\*[B-Font]events\f[]), 2868275970Scystatistics messages 2869275970Scy(\f\*[B-Font]statistics\f[]) 2870275970Scyand 2871275970Scystatus messages 2872275970Scy(\f\*[B-Font]status\f[]). 2873275970Scy.sp \n(Ppu 2874275970Scy.ne 2 2875275970Scy 2876275970ScyConfiguration keywords are formed by concatenating the message class with 2877275970Scythe event class. 2878275970ScyThe 2879275970Scy\f\*[B-Font]all\f[] 2880275970Scyprefix can be used instead of a message class. 2881275970ScyA 2882275970Scymessage class may also be followed by the 2883275970Scy\f\*[B-Font]all\f[] 2884275970Scykeyword to enable/disable all 2885298770Sdelphijmessages of the respective message class. 2886298770SdelphijThus, a minimal log configuration 2887275970Scycould look like this: 2888275970Scy.br 2889275970Scy.in +4 2890275970Scy.nf 2891275970Scylogconfig =syncstatus +sysevents 2892275970Scy.in -4 2893275970Scy.fi 2894275970Scy.sp \n(Ppu 2895275970Scy.ne 2 2896275970Scy 2897275970ScyThis would just list the synchronizations state of 2898290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[] 2899275970Scyand the major system events. 2900275970ScyFor a simple reference server, the 2901275970Scyfollowing minimum message configuration could be useful: 2902275970Scy.br 2903275970Scy.in +4 2904275970Scy.nf 2905275970Scylogconfig =syncall +clockall 2906275970Scy.in -4 2907275970Scy.fi 2908275970Scy.sp \n(Ppu 2909275970Scy.ne 2 2910275970Scy 2911275970ScyThis configuration will list all clock information and 2912275970Scysynchronization information. 2913275970ScyAll other events and messages about 2914275970Scypeers, system events and so on is suppressed. 2915275970Scy.TP 7 2916275970Scy.NOP \f\*[B-Font]logfile\f[] \f\*[I-Font]logfile\f[] 2917275970ScyThis command specifies the location of an alternate log file to 2918275970Scybe used instead of the default system 2919290000Sglebius\fCsyslog\f[]\fR(3)\f[] 2920275970Scyfacility. 2921298770SdelphijThis is the same operation as the 2922298770Sdelphij\f\*[B-Font]\-l\f[] 2923298770Sdelphijcommand line option. 2924275970Scy.TP 7 2925275970Scy.NOP \f\*[B-Font]setvar\f[] \f\*[I-Font]variable\f[] [\f\*[B-Font]default\f[]] 2926275970ScyThis command adds an additional system variable. 2927275970ScyThese 2928275970Scyvariables can be used to distribute additional information such as 2929275970Scythe access policy. 2930275970ScyIf the variable of the form 2931275970Scy\fIname\f[]\fI=\f[]\f\*[I-Font]value\f[] 2932275970Scyis followed by the 2933275970Scy\f\*[B-Font]default\f[] 2934275970Scykeyword, the 2935275970Scyvariable will be listed as part of the default system variables 2936290000Sglebius(\fCntpq\f[]\fR(1ntpqmdoc)\f[] \f\*[B-Font]rv\f[] command)). 2937275970ScyThese additional variables serve 2938275970Scyinformational purposes only. 2939275970ScyThey are not related to the protocol 2940275970Scyother that they can be listed. 2941275970ScyThe known protocol variables will 2942275970Scyalways override any variables defined via the 2943275970Scy\f\*[B-Font]setvar\f[] 2944275970Scymechanism. 2945275970ScyThere are three special variables that contain the names 2946275970Scyof all variable of the same group. 2947275970ScyThe 2948275970Scy\fIsys_var_list\f[] 2949275970Scyholds 2950275970Scythe names of all system variables. 2951275970ScyThe 2952275970Scy\fIpeer_var_list\f[] 2953275970Scyholds 2954275970Scythe names of all peer variables and the 2955275970Scy\fIclock_var_list\f[] 2956275970Scyholds the names of the reference clock variables. 2957275970Scy.TP 7 2958290000Sglebius.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[]] 2959275970ScyThis command can be used to alter several system variables in 2960275970Scyvery exceptional circumstances. 2961275970ScyIt should occur in the 2962275970Scyconfiguration file before any other configuration options. 2963275970ScyThe 2964275970Scydefault values of these variables have been carefully optimized for 2965275970Scya wide range of network speeds and reliability expectations. 2966275970ScyIn 2967275970Scygeneral, they interact in intricate ways that are hard to predict 2968275970Scyand some combinations can result in some very nasty behavior. 2969275970ScyVery 2970275970Scyrarely is it necessary to change the default values; but, some 2971275970Scyfolks cannot resist twisting the knobs anyway and this command is 2972275970Scyfor them. 2973275970ScyEmphasis added: twisters are on their own and can expect 2974275970Scyno help from the support group. 2975275970Scy.sp \n(Ppu 2976275970Scy.ne 2 2977275970Scy 2978275970ScyThe variables operate as follows: 2979275970Scy.RS 2980275970Scy.TP 7 2981275970Scy.NOP \f\*[B-Font]allan\f[] \f\*[I-Font]allan\f[] 2982275970ScyThe argument becomes the new value for the minimum Allan 2983275970Scyintercept, which is a parameter of the PLL/FLL clock discipline 2984275970Scyalgorithm. 2985275970ScyThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 2986275970Scylimit. 2987275970Scy.TP 7 2988275970Scy.NOP \f\*[B-Font]dispersion\f[] \f\*[I-Font]dispersion\f[] 2989275970ScyThe argument becomes the new value for the dispersion increase rate, 2990275970Scynormally .000015 s/s. 2991275970Scy.TP 7 2992275970Scy.NOP \f\*[B-Font]freq\f[] \f\*[I-Font]freq\f[] 2993275970ScyThe argument becomes the initial value of the frequency offset in 2994275970Scyparts-per-million. 2995275970ScyThis overrides the value in the frequency file, if 2996275970Scypresent, and avoids the initial training state if it is not. 2997275970Scy.TP 7 2998275970Scy.NOP \f\*[B-Font]huffpuff\f[] \f\*[I-Font]huffpuff\f[] 2999275970ScyThe argument becomes the new value for the experimental 3000275970Scyhuff-n'-puff filter span, which determines the most recent interval 3001275970Scythe algorithm will search for a minimum delay. 3002275970ScyThe lower limit is 3003275970Scy900 s (15 m), but a more reasonable value is 7200 (2 hours). 3004275970ScyThere 3005275970Scyis no default, since the filter is not enabled unless this command 3006275970Scyis given. 3007275970Scy.TP 7 3008275970Scy.NOP \f\*[B-Font]panic\f[] \f\*[I-Font]panic\f[] 3009275970ScyThe argument is the panic threshold, normally 1000 s. 3010275970ScyIf set to zero, 3011275970Scythe panic sanity check is disabled and a clock offset of any value will 3012275970Scybe accepted. 3013275970Scy.TP 7 3014275970Scy.NOP \f\*[B-Font]step\f[] \f\*[I-Font]step\f[] 3015275970ScyThe argument is the step threshold, which by default is 0.128 s. 3016275970ScyIt can 3017275970Scybe set to any positive number in seconds. 3018275970ScyIf set to zero, step 3019275970Scyadjustments will never occur. 3020275970ScyNote: The kernel time discipline is 3021275970Scydisabled if the step threshold is set to zero or greater than the 3022275970Scydefault. 3023275970Scy.TP 7 3024290000Sglebius.NOP \f\*[B-Font]stepback\f[] \f\*[I-Font]stepback\f[] 3025290000SglebiusThe argument is the step threshold for the backward direction, 3026290000Sglebiuswhich by default is 0.128 s. 3027290000SglebiusIt can 3028290000Sglebiusbe set to any positive number in seconds. 3029290000SglebiusIf both the forward and backward step thresholds are set to zero, step 3030290000Sglebiusadjustments will never occur. 3031290000SglebiusNote: The kernel time discipline is 3032290000Sglebiusdisabled if 3033290000Sglebiuseach direction of step threshold are either 3034290000Sglebiusset to zero or greater than .5 second. 3035290000Sglebius.TP 7 3036290000Sglebius.NOP \f\*[B-Font]stepfwd\f[] \f\*[I-Font]stepfwd\f[] 3037290000SglebiusAs for stepback, but for the forward direction. 3038290000Sglebius.TP 7 3039275970Scy.NOP \f\*[B-Font]stepout\f[] \f\*[I-Font]stepout\f[] 3040275970ScyThe argument is the stepout timeout, which by default is 900 s. 3041275970ScyIt can 3042275970Scybe set to any positive number in seconds. 3043275970ScyIf set to zero, the stepout 3044275970Scypulses will not be suppressed. 3045275970Scy.RE 3046275970Scy.TP 7 3047275970Scy.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[]] 3048275970Scy.RS 3049275970Scy.TP 7 3050275970Scy.NOP \f\*[B-Font]memlock\f[] \f\*[I-Font]Nmegabytes\f[] 3051290000SglebiusSpecify the number of megabytes of memory that should be 3052290000Sglebiusallocated and locked. 3053290000SglebiusProbably only available under Linux, this option may be useful 3054275970Scywhen dropping root (the 3055275970Scy\f\*[B-Font]\-i\f[] 3056275970Scyoption). 3057290000SglebiusThe default is 32 megabytes on non-Linux machines, and \-1 under Linux. 3058290000Sglebius-1 means "do not lock the process into memory". 3059290000Sglebius0 means "lock whatever memory the process wants into memory". 3060275970Scy.TP 7 3061275970Scy.NOP \f\*[B-Font]stacksize\f[] \f\*[I-Font]N4kPages\f[] 3062275970ScySpecifies the maximum size of the process stack on systems with the 3063290000Sglebius\fBmlockall\f[]\fR()\f[] 3064290000Sglebiusfunction. 3065290000SglebiusDefaults to 50 4k pages (200 4k pages in OpenBSD). 3066275970Scy.TP 7 3067275970Scy.NOP \f\*[B-Font]filenum\f[] \f\*[I-Font]Nfiledescriptors\f[] 3068298770SdelphijSpecifies the maximum number of file descriptors ntpd may have open at once. 3069298770SdelphijDefaults to the system default. 3070275970Scy.RE 3071275970Scy.TP 7 3072275970Scy.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[]] 3073275970ScyThis command configures a trap receiver at the given host 3074275970Scyaddress and port number for sending messages with the specified 3075275970Scylocal interface address. 3076275970ScyIf the port number is unspecified, a value 3077275970Scyof 18447 is used. 3078275970ScyIf the interface address is not specified, the 3079275970Scymessage is sent with a source address of the local interface the 3080275970Scymessage is sent through. 3081275970ScyNote that on a multihomed host the 3082275970Scyinterface used may vary from time to time with routing changes. 3083275970Scy.sp \n(Ppu 3084275970Scy.ne 2 3085275970Scy 3086275970ScyThe trap receiver will generally log event messages and other 3087275970Scyinformation from the server in a log file. 3088275970ScyWhile such monitor 3089275970Scyprograms may also request their own trap dynamically, configuring a 3090275970Scytrap receiver will ensure that no messages are lost when the server 3091275970Scyis started. 3092275970Scy.TP 7 3093275970Scy.NOP \f\*[B-Font]hop\f[] \f\*[I-Font]...\f[] 3094275970ScyThis command specifies a list of TTL values in increasing order, up to 8 3095275970Scyvalues can be specified. 3096275970ScyIn manycast mode these values are used in turn in 3097275970Scyan expanding-ring search. 3098275970ScyThe default is eight multiples of 32 starting at 3099275970Scy31. 3100310419Sdelphij.RE 3101275970Scy.SH "OPTIONS" 3102310419Sdelphij.RS 3103275970Scy.TP 3104275970Scy.NOP \f\*[B-Font]\-\-help\f[] 3105275970ScyDisplay usage information and exit. 3106275970Scy.TP 3107275970Scy.NOP \f\*[B-Font]\-\-more-help\f[] 3108275970ScyPass the extended usage information through a pager. 3109275970Scy.TP 3110275970Scy.NOP \f\*[B-Font]\-\-version\f[] [{\f\*[I-Font]v|c|n\f[]}] 3111275970ScyOutput version of program and exit. The default mode is `v', a simple 3112275970Scyversion. The `c' mode will print copyright information and `n' will 3113275970Scyprint the full copyright notice. 3114310419Sdelphij.RE 3115275970Scy.SH "OPTION PRESETS" 3116275970ScyAny option that is not marked as \fInot presettable\fP may be preset 3117275970Scyby loading values from environment variables named: 3118275970Scy.nf 3119275970Scy \fBNTP_CONF_<option-name>\fP or \fBNTP_CONF\fP 3120275970Scy.fi 3121275970Scy.ad 3122275970Scy.SH "ENVIRONMENT" 3123275970ScySee \fBOPTION PRESETS\fP for configuration environment variables. 3124275970Scy.SH FILES 3125310419Sdelphij.RS 3126275970Scy.TP 15 3127275970Scy.NOP \fI/etc/ntp.conf\f[] 3128275970Scythe default name of the configuration file 3129275970Scy.br 3130275970Scy.ns 3131275970Scy.TP 15 3132275970Scy.NOP \fIntp.keys\f[] 3133275970Scyprivate MD5 keys 3134275970Scy.br 3135275970Scy.ns 3136275970Scy.TP 15 3137275970Scy.NOP \fIntpkey\f[] 3138275970ScyRSA private key 3139275970Scy.br 3140275970Scy.ns 3141275970Scy.TP 15 3142275970Scy.NOP \fIntpkey_\f[]\f\*[I-Font]host\f[] 3143275970ScyRSA public key 3144275970Scy.br 3145275970Scy.ns 3146275970Scy.TP 15 3147275970Scy.NOP \fIntp_dh\f[] 3148275970ScyDiffie-Hellman agreement parameters 3149310419Sdelphij.RE 3150275970Scy.SH "EXIT STATUS" 3151275970ScyOne of the following exit values will be returned: 3152310419Sdelphij.RS 3153275970Scy.TP 3154275970Scy.NOP 0 " (EXIT_SUCCESS)" 3155275970ScySuccessful program execution. 3156275970Scy.TP 3157275970Scy.NOP 1 " (EXIT_FAILURE)" 3158275970ScyThe operation failed or the command syntax was not valid. 3159275970Scy.TP 3160275970Scy.NOP 70 " (EX_SOFTWARE)" 3161275970Scylibopts had an internal operational error. Please report 3162275970Scyit to autogen-users@lists.sourceforge.net. Thank you. 3163310419Sdelphij.RE 3164275970Scy.SH "SEE ALSO" 3165290000Sglebius\fCntpd\f[]\fR(1ntpdmdoc)\f[], 3166290000Sglebius\fCntpdc\f[]\fR(1ntpdcmdoc)\f[], 3167290000Sglebius\fCntpq\f[]\fR(1ntpqmdoc)\f[] 3168275970Scy.sp \n(Ppu 3169275970Scy.ne 2 3170275970Scy 3171275970ScyIn addition to the manual pages provided, 3172275970Scycomprehensive documentation is available on the world wide web 3173275970Scyat 3174275970Scy\f[C]http://www.ntp.org/\f[]. 3175275970ScyA snapshot of this documentation is available in HTML format in 3176275970Scy\fI/usr/share/doc/ntp\f[]. 3177275970ScyDavid L. Mills, 3178275970Scy\fINetwork Time Protocol (Version 4)\fR, 3179275970ScyRFC5905 3180275970Scy.PP 3181275970Scy 3182275970Scy.SH "AUTHORS" 3183280849ScyThe University of Delaware and Network Time Foundation 3184275970Scy.SH "COPYRIGHT" 3185294904SdelphijCopyright (C) 1992-2016 The University of Delaware and Network Time Foundation all rights reserved. 3186275970ScyThis program is released under the terms of the NTP license, <http://ntp.org/license>. 3187275970Scy.SH BUGS 3188275970ScyThe syntax checking is not picky; some combinations of 3189275970Scyridiculous and even hilarious options and modes may not be 3190275970Scydetected. 3191275970Scy.sp \n(Ppu 3192275970Scy.ne 2 3193275970Scy 3194275970ScyThe 3195275970Scy\fIntpkey_\f[]\f\*[I-Font]host\f[] 3196275970Scyfiles are really digital 3197275970Scycertificates. 3198275970ScyThese should be obtained via secure directory 3199275970Scyservices when they become universally available. 3200275970Scy.sp \n(Ppu 3201275970Scy.ne 2 3202275970Scy 3203275970ScyPlease send bug reports to: http://bugs.ntp.org, bugs@ntp.org 3204275970Scy.SH NOTES 3205275970ScyThis document was derived from FreeBSD. 3206275970Scy.sp \n(Ppu 3207275970Scy.ne 2 3208275970Scy 3209275970ScyThis manual page was \fIAutoGen\fP-erated from the \fBntp.conf\fP 3210275970Scyoption definitions. 3211