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