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