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