1290001Sglebius<html lang="en"> 2290001Sglebius<head> 3290001Sglebius<title>NTP Configuration File User's Manual</title> 4290001Sglebius<meta http-equiv="Content-Type" content="text/html"> 5290001Sglebius<meta name="description" content="NTP Configuration File User's Manual"> 6290001Sglebius<meta name="generator" content="makeinfo 4.7"> 7290001Sglebius<link title="Top" rel="top" href="#Top"> 8290001Sglebius<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 9290001Sglebius<meta http-equiv="Content-Style-Type" content="text/css"> 10290001Sglebius<style type="text/css"><!-- 11290001Sglebius pre.display { font-family:inherit } 12290001Sglebius pre.format { font-family:inherit } 13290001Sglebius pre.smalldisplay { font-family:inherit; font-size:smaller } 14290001Sglebius pre.smallformat { font-family:inherit; font-size:smaller } 15290001Sglebius pre.smallexample { font-size:smaller } 16290001Sglebius pre.smalllisp { font-size:smaller } 17290001Sglebius span.sc { font-variant:small-caps } 18290001Sglebius span.roman { font-family: serif; font-weight: normal; } 19290001Sglebius--></style> 20290001Sglebius</head> 21290001Sglebius<body> 22290001Sglebius<h1 class="settitle">NTP Configuration File User's Manual</h1> 23290001Sglebius<div class="node"> 24290001Sglebius<p><hr> 25290001Sglebius<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#ntp_002econf-Description">ntp.conf Description</a>, 26290001SglebiusPrevious: <a rel="previous" accesskey="p" href="#dir">(dir)</a>, 27290001SglebiusUp: <a rel="up" accesskey="u" href="#dir">(dir)</a> 28290001Sglebius<br> 29290001Sglebius</div> 30290001Sglebius 31290001Sglebius<h2 class="unnumbered">NTP's Configuration File User Manual</h2> 32290001Sglebius 33290001Sglebius<p>This document describes the configuration file for the NTP Project's 34290001Sglebius<code>ntpd</code> program. 35290001Sglebius 36310419Sdelphij <p>This document applies to version 4.2.8p9 of <code>ntp.conf</code>. 37290001Sglebius 38310419Sdelphij <div class="shortcontents"> 39290001Sglebius<h2>Short Contents</h2> 40290001Sglebius<ul> 41290001Sglebius<a href="#Top">NTP's Configuration File User Manual</a> 42290001Sglebius</ul> 43290001Sglebius</div> 44290001Sglebius 45290001Sglebius<ul class="menu"> 46290001Sglebius<li><a accesskey="1" href="#ntp_002econf-Description">ntp.conf Description</a> 47290001Sglebius<li><a accesskey="2" href="#ntp_002econf-Notes">ntp.conf Notes</a> 48290001Sglebius</ul> 49290001Sglebius 50290001Sglebius<div class="node"> 51290001Sglebius<p><hr> 52290001Sglebius<a name="ntp_002econf-Description"></a>Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, 53290001SglebiusUp: <a rel="up" accesskey="u" href="#Top">Top</a> 54290001Sglebius<br> 55290001Sglebius</div> 56290001Sglebius 57290001Sglebius<!-- node-name, next, previous, up --> 58290001Sglebius<h3 class="section">Description</h3> 59290001Sglebius 60290001Sglebius<p>The behavior of <code>ntpd</code> can be changed by a configuration file, 61290001Sglebiusby default <code>ntp.conf</code>. 62290001Sglebius 63290001Sglebius<div class="node"> 64290001Sglebius<p><hr> 65290001Sglebius<a name="ntp_002econf-Notes"></a> 66290001Sglebius<br> 67290001Sglebius</div> 68290001Sglebius 69290001Sglebius<h3 class="section">Notes about ntp.conf</h3> 70290001Sglebius 71290001Sglebius<p><a name="index-ntp_002econf-1"></a><a name="index-Network-Time-Protocol-_0028NTP_0029-daemon-configuration-file-format-2"></a> 72290001Sglebius 73290001Sglebius <p>The 74290001Sglebius<code>ntp.conf</code> 75290001Sglebiusconfiguration file is read at initial startup by the 76290001Sglebius<code>ntpd(1ntpdmdoc)</code> 77290001Sglebiusdaemon in order to specify the synchronization sources, 78290001Sglebiusmodes and other related information. 79290001SglebiusUsually, it is installed in the 80290001Sglebius<span class="file">/etc</span> 81290001Sglebiusdirectory, 82290001Sglebiusbut could be installed elsewhere 83290001Sglebius(see the daemon's 84290001Sglebius<code>-c</code> 85290001Sglebiuscommand line option). 86290001Sglebius 87290001Sglebius <p>The file format is similar to other 88290001Sglebius<span class="sc">unix</span> 89290001Sglebiusconfiguration files. 90290001SglebiusComments begin with a 91290001Sglebius# 92290001Sglebiuscharacter and extend to the end of the line; 93290001Sglebiusblank lines are ignored. 94290001SglebiusConfiguration commands consist of an initial keyword 95290001Sglebiusfollowed by a list of arguments, 96290001Sglebiussome of which may be optional, separated by whitespace. 97290001SglebiusCommands may not be continued over multiple lines. 98290001SglebiusArguments may be host names, 99290001Sglebiushost addresses written in numeric, dotted-quad form, 100290001Sglebiusintegers, floating point numbers (when specifying times in seconds) 101290001Sglebiusand text strings. 102290001Sglebius 103290001Sglebius <p>The rest of this page describes the configuration and control options. 104290001SglebiusThe 105290001Sglebius"Notes on Configuring NTP and Setting up an NTP Subnet" 106290001Sglebiuspage 107290001Sglebius(available as part of the HTML documentation 108290001Sglebiusprovided in 109290001Sglebius<span class="file">/usr/share/doc/ntp</span>) 110290001Sglebiuscontains an extended discussion of these options. 111290001SglebiusIn addition to the discussion of general 112290001Sglebius<a href="#Configuration-Options">Configuration Options</a>, 113290001Sglebiusthere are sections describing the following supported functionality 114290001Sglebiusand the options used to control it: 115290001Sglebius <ul> 116290001Sglebius<li><a href="#Authentication-Support">Authentication Support</a> 117290001Sglebius<li><a href="#Monitoring-Support">Monitoring Support</a> 118290001Sglebius<li><a href="#Access-Control-Support">Access Control Support</a> 119290001Sglebius<li><a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a> 120290001Sglebius<li><a href="#Reference-Clock-Support">Reference Clock Support</a> 121290001Sglebius<li><a href="#Miscellaneous-Options">Miscellaneous Options</a> 122290001Sglebius</ul> 123290001Sglebius 124290001Sglebius <p>Following these is a section describing 125290001Sglebius<a href="#Miscellaneous-Options">Miscellaneous Options</a>. 126290001SglebiusWhile there is a rich set of options available, 127290001Sglebiusthe only required option is one or more 128290001Sglebius<code>pool</code>, 129290001Sglebius<code>server</code>, 130290001Sglebius<code>peer</code>, 131290001Sglebius<code>broadcast</code> 132290001Sglebiusor 133290001Sglebius<code>manycastclient</code> 134290001Sglebiuscommands. 135290001Sglebius<div class="node"> 136290001Sglebius<p><hr> 137290001Sglebius<a name="Configuration-Support"></a> 138290001Sglebius<br> 139290001Sglebius</div> 140290001Sglebius 141290001Sglebius<h4 class="subsection">Configuration Support</h4> 142290001Sglebius 143290001Sglebius<p>Following is a description of the configuration commands in 144290001SglebiusNTPv4. 145290001SglebiusThese commands have the same basic functions as in NTPv3 and 146290001Sglebiusin some cases new functions and new arguments. 147290001SglebiusThere are two 148290001Sglebiusclasses of commands, configuration commands that configure a 149290001Sglebiuspersistent association with a remote server or peer or reference 150290001Sglebiusclock, and auxiliary commands that specify environmental variables 151290001Sglebiusthat control various related operations. 152290001Sglebius 153290001Sglebius<h5 class="subsubsection">Configuration Commands</h5> 154290001Sglebius 155290001Sglebius<p>The various modes are determined by the command keyword and the 156290001Sglebiustype of the required IP address. 157290001SglebiusAddresses are classed by type as 158290001Sglebius(s) a remote server or peer (IPv4 class A, B and C), (b) the 159290001Sglebiusbroadcast address of a local interface, (m) a multicast address (IPv4 160290001Sglebiusclass D), or (r) a reference clock address (127.127.x.x). 161290001SglebiusNote that 162290001Sglebiusonly those options applicable to each command are listed below. 163290001SglebiusUse 164290001Sglebiusof options not listed may not be caught as an error, but may result 165290001Sglebiusin some weird and even destructive behavior. 166290001Sglebius 167290001Sglebius <p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) 168290001Sglebiusis detected, support for the IPv6 address family is generated 169290001Sglebiusin addition to the default support of the IPv4 address family. 170301301SdelphijIn a few cases, including the 171301301Sdelphij<code>reslist</code> 172301301Sdelphijbillboard generated 173301301Sdelphijby 174301301Sdelphij<code>ntpq(1ntpqmdoc)</code> 175301301Sdelphijor 176301301Sdelphij<code>ntpdc(1ntpdcmdoc)</code>, 177301301SdelphijIPv6 addresses are automatically generated. 178290001SglebiusIPv6 addresses can be identified by the presence of colons 179290001Sglebius: 180290001Sglebiusin the address field. 181290001SglebiusIPv6 addresses can be used almost everywhere where 182290001SglebiusIPv4 addresses can be used, 183290001Sglebiuswith the exception of reference clock addresses, 184290001Sglebiuswhich are always IPv4. 185290001Sglebius 186290001Sglebius <p>Note that in contexts where a host name is expected, a 187290001Sglebius<code>-4</code> 188290001Sglebiusqualifier preceding 189290001Sglebiusthe host name forces DNS resolution to the IPv4 namespace, 190290001Sglebiuswhile a 191290001Sglebius<code>-6</code> 192290001Sglebiusqualifier forces DNS resolution to the IPv6 namespace. 193290001SglebiusSee IPv6 references for the 194290001Sglebiusequivalent classes for that address family. 195290001Sglebius <dl> 196301301Sdelphij<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> 197290001Sglebius 198290001Sglebius <p>These five commands specify the time server name or address to 199290001Sglebiusbe used and the mode in which to operate. 200290001SglebiusThe 201290001Sglebius<kbd>address</kbd> 202290001Sglebiuscan be 203290001Sglebiuseither a DNS name or an IP address in dotted-quad notation. 204290001SglebiusAdditional information on association behavior can be found in the 205290001Sglebius"Association Management" 206290001Sglebiuspage 207290001Sglebius(available as part of the HTML documentation 208290001Sglebiusprovided in 209290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 210290001Sglebius <dl> 211290001Sglebius<dt><code>pool</code><dd>For type s addresses, this command mobilizes a persistent 212290001Sglebiusclient mode association with a number of remote servers. 213290001SglebiusIn this mode the local clock can synchronized to the 214290001Sglebiusremote server, but the remote server can never be synchronized to 215290001Sglebiusthe local clock. 216290001Sglebius<br><dt><code>server</code><dd>For type s and r addresses, this command mobilizes a persistent 217290001Sglebiusclient mode association with the specified remote server or local 218290001Sglebiusradio clock. 219290001SglebiusIn this mode the local clock can synchronized to the 220290001Sglebiusremote server, but the remote server can never be synchronized to 221290001Sglebiusthe local clock. 222290001SglebiusThis command should 223290001Sglebius<em>not</em> 224290001Sglebiusbe used for type 225290001Sglebiusb or m addresses. 226290001Sglebius<br><dt><code>peer</code><dd>For type s addresses (only), this command mobilizes a 227290001Sglebiuspersistent symmetric-active mode association with the specified 228290001Sglebiusremote peer. 229290001SglebiusIn this mode the local clock can be synchronized to 230290001Sglebiusthe remote peer or the remote peer can be synchronized to the local 231290001Sglebiusclock. 232290001SglebiusThis is useful in a network of servers where, depending on 233290001Sglebiusvarious failure scenarios, either the local or remote peer may be 234290001Sglebiusthe better source of time. 235290001SglebiusThis command should NOT be used for type 236290001Sglebiusb, m or r addresses. 237290001Sglebius<br><dt><code>broadcast</code><dd>For type b and m addresses (only), this 238290001Sglebiuscommand mobilizes a persistent broadcast mode association. 239290001SglebiusMultiple 240290001Sglebiuscommands can be used to specify multiple local broadcast interfaces 241290001Sglebius(subnets) and/or multiple multicast groups. 242290001SglebiusNote that local 243290001Sglebiusbroadcast messages go only to the interface associated with the 244290001Sglebiussubnet specified, but multicast messages go to all interfaces. 245290001SglebiusIn broadcast mode the local server sends periodic broadcast 246290001Sglebiusmessages to a client population at the 247290001Sglebius<kbd>address</kbd> 248290001Sglebiusspecified, which is usually the broadcast address on (one of) the 249290001Sglebiuslocal network(s) or a multicast address assigned to NTP. 250290001SglebiusThe IANA 251290001Sglebiushas assigned the multicast group address IPv4 224.0.1.1 and 252290001SglebiusIPv6 ff05::101 (site local) exclusively to 253290001SglebiusNTP, but other nonconflicting addresses can be used to contain the 254290001Sglebiusmessages within administrative boundaries. 255290001SglebiusOrdinarily, this 256290001Sglebiusspecification applies only to the local server operating as a 257290001Sglebiussender; for operation as a broadcast client, see the 258290001Sglebius<code>broadcastclient</code> 259290001Sglebiusor 260290001Sglebius<code>multicastclient</code> 261290001Sglebiuscommands 262290001Sglebiusbelow. 263290001Sglebius<br><dt><code>manycastclient</code><dd>For type m addresses (only), this command mobilizes a 264290001Sglebiusmanycast client mode association for the multicast address 265290001Sglebiusspecified. 266290001SglebiusIn this case a specific address must be supplied which 267290001Sglebiusmatches the address used on the 268290001Sglebius<code>manycastserver</code> 269290001Sglebiuscommand for 270290001Sglebiusthe designated manycast servers. 271290001SglebiusThe NTP multicast address 272290001Sglebius224.0.1.1 assigned by the IANA should NOT be used, unless specific 273290001Sglebiusmeans are taken to avoid spraying large areas of the Internet with 274290001Sglebiusthese messages and causing a possibly massive implosion of replies 275290001Sglebiusat the sender. 276290001SglebiusThe 277290001Sglebius<code>manycastserver</code> 278290001Sglebiuscommand specifies that the local server 279290001Sglebiusis to operate in client mode with the remote servers that are 280290001Sglebiusdiscovered as the result of broadcast/multicast messages. 281290001SglebiusThe 282290001Sglebiusclient broadcasts a request message to the group address associated 283290001Sglebiuswith the specified 284290001Sglebius<kbd>address</kbd> 285290001Sglebiusand specifically enabled 286290001Sglebiusservers respond to these messages. 287290001SglebiusThe client selects the servers 288290001Sglebiusproviding the best time and continues as with the 289290001Sglebius<code>server</code> 290290001Sglebiuscommand. 291290001SglebiusThe remaining servers are discarded as if never 292290001Sglebiusheard. 293290001Sglebius</dl> 294290001Sglebius 295290001Sglebius <p>Options: 296290001Sglebius <dl> 297290001Sglebius<dt><code>autokey</code><dd>All packets sent to and received from the server or peer are to 298290001Sglebiusinclude authentication fields encrypted using the autokey scheme 299290001Sglebiusdescribed in 300290001Sglebius<a href="#Authentication-Options">Authentication Options</a>. 301290001Sglebius<br><dt><code>burst</code><dd>when the server is reachable, send a burst of eight packets 302290001Sglebiusinstead of the usual one. 303290001SglebiusThe packet spacing is normally 2 s; 304290001Sglebiushowever, the spacing between the first and second packets 305298770Sdelphijcan be changed with the 306298770Sdelphij<code>calldelay</code> 307298770Sdelphijcommand to allow 308290001Sglebiusadditional time for a modem or ISDN call to complete. 309290001SglebiusThis is designed to improve timekeeping quality 310290001Sglebiuswith the 311290001Sglebius<code>server</code> 312290001Sglebiuscommand and s addresses. 313290001Sglebius<br><dt><code>iburst</code><dd>When the server is unreachable, send a burst of eight packets 314290001Sglebiusinstead of the usual one. 315290001SglebiusThe packet spacing is normally 2 s; 316290001Sglebiushowever, the spacing between the first two packets can be 317298770Sdelphijchanged with the 318298770Sdelphij<code>calldelay</code> 319298770Sdelphijcommand to allow 320290001Sglebiusadditional time for a modem or ISDN call to complete. 321290001SglebiusThis is designed to speed the initial synchronization 322290001Sglebiusacquisition with the 323290001Sglebius<code>server</code> 324290001Sglebiuscommand and s addresses and when 325290001Sglebius<code>ntpd(1ntpdmdoc)</code> 326290001Sglebiusis started with the 327290001Sglebius<code>-q</code> 328290001Sglebiusoption. 329290001Sglebius<br><dt><code>key</code> <kbd>key</kbd><dd>All packets sent to and received from the server or peer are to 330290001Sglebiusinclude authentication fields encrypted using the specified 331290001Sglebius<kbd>key</kbd> 332290001Sglebiusidentifier with values from 1 to 65534, inclusive. 333290001SglebiusThe 334290001Sglebiusdefault is to include no encryption field. 335290001Sglebius<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 336290001Sglebiusfor NTP messages, as a power of 2 in seconds 337290001SglebiusThe maximum poll 338290001Sglebiusinterval defaults to 10 (1,024 s), but can be increased by the 339290001Sglebius<code>maxpoll</code> 340290001Sglebiusoption to an upper limit of 17 (36.4 h). 341290001SglebiusThe 342290001Sglebiusminimum poll interval defaults to 6 (64 s), but can be decreased by 343290001Sglebiusthe 344290001Sglebius<code>minpoll</code> 345290001Sglebiusoption to a lower limit of 4 (16 s). 346290001Sglebius<br><dt><code>noselect</code><dd>Marks the server as unused, except for display purposes. 347290001SglebiusThe server is discarded by the selection algroithm. 348298770Sdelphij<br><dt><code>preempt</code><dd>Says the association can be preempted. 349298770Sdelphij<br><dt><code>true</code><dd>Marks the server as a truechimer. 350301301SdelphijUse this option only for testing. 351290001Sglebius<br><dt><code>prefer</code><dd>Marks the server as preferred. 352290001SglebiusAll other things being equal, 353290001Sglebiusthis host will be chosen for synchronization among a set of 354290001Sglebiuscorrectly operating hosts. 355290001SglebiusSee the 356290001Sglebius"Mitigation Rules and the prefer Keyword" 357290001Sglebiuspage 358290001Sglebius(available as part of the HTML documentation 359290001Sglebiusprovided in 360290001Sglebius<span class="file">/usr/share/doc/ntp</span>) 361290001Sglebiusfor further information. 362301301Sdelphij<br><dt><code>true</code><dd>Forces the association to always survive the selection and clustering algorithms. 363301301SdelphijThis option should almost certainly 364301301Sdelphij<em>only</em> 365301301Sdelphijbe used while testing an association. 366290001Sglebius<br><dt><code>ttl</code> <kbd>ttl</kbd><dd>This option is used only with broadcast server and manycast 367290001Sglebiusclient modes. 368290001SglebiusIt specifies the time-to-live 369290001Sglebius<kbd>ttl</kbd> 370290001Sglebiusto 371290001Sglebiususe on broadcast server and multicast server and the maximum 372290001Sglebius<kbd>ttl</kbd> 373290001Sglebiusfor the expanding ring search with manycast 374290001Sglebiusclient packets. 375290001SglebiusSelection of the proper value, which defaults to 376290001Sglebius127, is something of a black art and should be coordinated with the 377290001Sglebiusnetwork administrator. 378290001Sglebius<br><dt><code>version</code> <kbd>version</kbd><dd>Specifies the version number to be used for outgoing NTP 379290001Sglebiuspackets. 380290001SglebiusVersions 1-4 are the choices, with version 4 the 381290001Sglebiusdefault. 382298770Sdelphij<br><dt><code>xleave</code><dd>Valid in 383298770Sdelphij<code>peer</code> 384298770Sdelphijand 385298770Sdelphij<code>broadcast</code> 386298770Sdelphijmodes only, this flag enables interleave mode. 387290001Sglebius</dl> 388290001Sglebius 389290001Sglebius<h5 class="subsubsection">Auxiliary Commands</h5> 390290001Sglebius 391290001Sglebius <dl> 392290001Sglebius<dt><code>broadcastclient</code><dd>This command enables reception of broadcast server messages to 393290001Sglebiusany local interface (type b) address. 394290001SglebiusUpon receiving a message for 395290001Sglebiusthe first time, the broadcast client measures the nominal server 396290001Sglebiuspropagation delay using a brief client/server exchange with the 397290001Sglebiusserver, then enters the broadcast client mode, in which it 398290001Sglebiussynchronizes to succeeding broadcast messages. 399290001SglebiusNote that, in order 400290001Sglebiusto avoid accidental or malicious disruption in this mode, both the 401290001Sglebiusserver and client should operate using symmetric-key or public-key 402290001Sglebiusauthentication as described in 403290001Sglebius<a href="#Authentication-Options">Authentication Options</a>. 404290001Sglebius<br><dt><code>manycastserver</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of manycast client messages to 405290001Sglebiusthe multicast group address(es) (type m) specified. 406290001SglebiusAt least one 407290001Sglebiusaddress is required, but the NTP multicast address 224.0.1.1 408290001Sglebiusassigned by the IANA should NOT be used, unless specific means are 409290001Sglebiustaken to limit the span of the reply and avoid a possibly massive 410290001Sglebiusimplosion at the original sender. 411290001SglebiusNote that, in order to avoid 412290001Sglebiusaccidental or malicious disruption in this mode, both the server 413290001Sglebiusand client should operate using symmetric-key or public-key 414290001Sglebiusauthentication as described in 415290001Sglebius<a href="#Authentication-Options">Authentication Options</a>. 416290001Sglebius<br><dt><code>multicastclient</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of multicast server messages to 417290001Sglebiusthe multicast group address(es) (type m) specified. 418290001SglebiusUpon receiving 419290001Sglebiusa message for the first time, the multicast client measures the 420290001Sglebiusnominal server propagation delay using a brief client/server 421290001Sglebiusexchange with the server, then enters the broadcast client mode, in 422290001Sglebiuswhich it synchronizes to succeeding multicast messages. 423290001SglebiusNote that, 424290001Sglebiusin order to avoid accidental or malicious disruption in this mode, 425290001Sglebiusboth the server and client should operate using symmetric-key or 426290001Sglebiuspublic-key authentication as described in 427290001Sglebius<a href="#Authentication-Options">Authentication Options</a>. 428290001Sglebius<br><dt><code>mdnstries</code> <kbd>number</kbd><dd>If we are participating in mDNS, 429290001Sglebiusafter we have synched for the first time 430290001Sglebiuswe attempt to register with the mDNS system. 431290001SglebiusIf that registration attempt fails, 432290001Sglebiuswe try again at one minute intervals for up to 433290001Sglebius<code>mdnstries</code> 434290001Sglebiustimes. 435290001SglebiusAfter all, 436290001Sglebius<code>ntpd</code> 437290001Sglebiusmay be starting before mDNS. 438290001SglebiusThe default value for 439290001Sglebius<code>mdnstries</code> 440290001Sglebiusis 5. 441290001Sglebius</dl> 442290001Sglebius<div class="node"> 443290001Sglebius<p><hr> 444290001Sglebius<a name="Authentication-Support"></a> 445290001Sglebius<br> 446290001Sglebius</div> 447290001Sglebius 448290001Sglebius<h4 class="subsection">Authentication Support</h4> 449290001Sglebius 450290001Sglebius<p>Authentication support allows the NTP client to verify that the 451290001Sglebiusserver is in fact known and trusted and not an intruder intending 452290001Sglebiusaccidentally or on purpose to masquerade as that server. 453290001SglebiusThe NTPv3 454290001Sglebiusspecification RFC-1305 defines a scheme which provides 455290001Sglebiuscryptographic authentication of received NTP packets. 456290001SglebiusOriginally, 457290001Sglebiusthis was done using the Data Encryption Standard (DES) algorithm 458290001Sglebiusoperating in Cipher Block Chaining (CBC) mode, commonly called 459290001SglebiusDES-CBC. 460290001SglebiusSubsequently, this was replaced by the RSA Message Digest 461290001Sglebius5 (MD5) algorithm using a private key, commonly called keyed-MD5. 462290001SglebiusEither algorithm computes a message digest, or one-way hash, which 463290001Sglebiuscan be used to verify the server has the correct private key and 464290001Sglebiuskey identifier. 465290001Sglebius 466290001Sglebius <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key 467290001Sglebiuscryptography and, in addition, provides a new Autokey scheme 468290001Sglebiusbased on public key cryptography. 469290001SglebiusPublic key cryptography is generally considered more secure 470290001Sglebiusthan symmetric key cryptography, since the security is based 471290001Sglebiuson a private value which is generated by each server and 472290001Sglebiusnever revealed. 473290001SglebiusWith Autokey all key distribution and 474290001Sglebiusmanagement functions involve only public values, which 475290001Sglebiusconsiderably simplifies key distribution and storage. 476290001SglebiusPublic key management is based on X.509 certificates, 477290001Sglebiuswhich can be provided by commercial services or 478290001Sglebiusproduced by utility programs in the OpenSSL software library 479290001Sglebiusor the NTPv4 distribution. 480290001Sglebius 481290001Sglebius <p>While the algorithms for symmetric key cryptography are 482290001Sglebiusincluded in the NTPv4 distribution, public key cryptography 483290001Sglebiusrequires the OpenSSL software library to be installed 484290001Sglebiusbefore building the NTP distribution. 485290001SglebiusDirections for doing that 486290001Sglebiusare on the Building and Installing the Distribution page. 487290001Sglebius 488290001Sglebius <p>Authentication is configured separately for each association 489290001Sglebiususing the 490290001Sglebius<code>key</code> 491290001Sglebiusor 492290001Sglebius<code>autokey</code> 493290001Sglebiussubcommand on the 494290001Sglebius<code>peer</code>, 495290001Sglebius<code>server</code>, 496290001Sglebius<code>broadcast</code> 497290001Sglebiusand 498290001Sglebius<code>manycastclient</code> 499290001Sglebiusconfiguration commands as described in 500290001Sglebius<a href="#Configuration-Options">Configuration Options</a> 501290001Sglebiuspage. 502290001SglebiusThe authentication 503290001Sglebiusoptions described below specify the locations of the key files, 504290001Sglebiusif other than default, which symmetric keys are trusted 505290001Sglebiusand the interval between various operations, if other than default. 506290001Sglebius 507290001Sglebius <p>Authentication is always enabled, 508290001Sglebiusalthough ineffective if not configured as 509290001Sglebiusdescribed below. 510290001SglebiusIf a NTP packet arrives 511290001Sglebiusincluding a message authentication 512290001Sglebiuscode (MAC), it is accepted only if it 513290001Sglebiuspasses all cryptographic checks. 514290001SglebiusThe 515290001Sglebiuschecks require correct key ID, key value 516290001Sglebiusand message digest. 517290001SglebiusIf the packet has 518290001Sglebiusbeen modified in any way or replayed 519290001Sglebiusby an intruder, it will fail one or more 520290001Sglebiusof these checks and be discarded. 521290001SglebiusFurthermore, the Autokey scheme requires a 522290001Sglebiuspreliminary protocol exchange to obtain 523290001Sglebiusthe server certificate, verify its 524290001Sglebiuscredentials and initialize the protocol 525290001Sglebius 526290001Sglebius <p>The 527290001Sglebius<code>auth</code> 528290001Sglebiusflag controls whether new associations or 529290001Sglebiusremote configuration commands require cryptographic authentication. 530290001SglebiusThis flag can be set or reset by the 531290001Sglebius<code>enable</code> 532290001Sglebiusand 533290001Sglebius<code>disable</code> 534290001Sglebiuscommands and also by remote 535290001Sglebiusconfiguration commands sent by a 536290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 537301301Sdelphijprogram running on 538290001Sglebiusanother machine. 539290001SglebiusIf this flag is enabled, which is the default 540290001Sglebiuscase, new broadcast client and symmetric passive associations and 541290001Sglebiusremote configuration commands must be cryptographically 542290001Sglebiusauthenticated using either symmetric key or public key cryptography. 543290001SglebiusIf this 544290001Sglebiusflag is disabled, these operations are effective 545290001Sglebiuseven if not cryptographic 546290001Sglebiusauthenticated. 547290001SglebiusIt should be understood 548290001Sglebiusthat operating with the 549290001Sglebius<code>auth</code> 550290001Sglebiusflag disabled invites a significant vulnerability 551290001Sglebiuswhere a rogue hacker can 552290001Sglebiusmasquerade as a falseticker and seriously 553290001Sglebiusdisrupt system timekeeping. 554290001SglebiusIt is 555290001Sglebiusimportant to note that this flag has no purpose 556290001Sglebiusother than to allow or disallow 557290001Sglebiusa new association in response to new broadcast 558290001Sglebiusand symmetric active messages 559290001Sglebiusand remote configuration commands and, in particular, 560290001Sglebiusthe flag has no effect on 561290001Sglebiusthe authentication process itself. 562290001Sglebius 563290001Sglebius <p>An attractive alternative where multicast support is available 564290001Sglebiusis manycast mode, in which clients periodically troll 565290001Sglebiusfor servers as described in the 566290001Sglebius<a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a> 567290001Sglebiuspage. 568290001SglebiusEither symmetric key or public key 569290001Sglebiuscryptographic authentication can be used in this mode. 570290001SglebiusThe principle advantage 571290001Sglebiusof manycast mode is that potential servers need not be 572290001Sglebiusconfigured in advance, 573290001Sglebiussince the client finds them during regular operation, 574290001Sglebiusand the configuration 575290001Sglebiusfiles for all clients can be identical. 576290001Sglebius 577290001Sglebius <p>The security model and protocol schemes for 578290001Sglebiusboth symmetric key and public key 579290001Sglebiuscryptography are summarized below; 580290001Sglebiusfurther details are in the briefings, papers 581290001Sglebiusand reports at the NTP project page linked from 582290001Sglebius<code>http://www.ntp.org/</code>. 583290001Sglebius 584290001Sglebius<h5 class="subsubsection">Symmetric-Key Cryptography</h5> 585290001Sglebius 586290001Sglebius<p>The original RFC-1305 specification allows any one of possibly 587290001Sglebius65,534 keys, each distinguished by a 32-bit key identifier, to 588290001Sglebiusauthenticate an association. 589290001SglebiusThe servers and clients involved must 590290001Sglebiusagree on the key and key identifier to 591290001Sglebiusauthenticate NTP packets. 592290001SglebiusKeys and 593290001Sglebiusrelated information are specified in a key 594290001Sglebiusfile, usually called 595290001Sglebius<span class="file">ntp.keys</span>, 596290001Sglebiuswhich must be distributed and stored using 597290001Sglebiussecure means beyond the scope of the NTP protocol itself. 598290001SglebiusBesides the keys used 599290001Sglebiusfor ordinary NTP associations, 600290001Sglebiusadditional keys can be used as passwords for the 601290001Sglebius<code>ntpq(1ntpqmdoc)</code> 602290001Sglebiusand 603290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 604290001Sglebiusutility programs. 605290001Sglebius 606290001Sglebius <p>When 607290001Sglebius<code>ntpd(1ntpdmdoc)</code> 608290001Sglebiusis first started, it reads the key file specified in the 609290001Sglebius<code>keys</code> 610290001Sglebiusconfiguration command and installs the keys 611290001Sglebiusin the key cache. 612290001SglebiusHowever, 613290001Sglebiusindividual keys must be activated with the 614290001Sglebius<code>trusted</code> 615290001Sglebiuscommand before use. 616290001SglebiusThis 617290001Sglebiusallows, for instance, the installation of possibly 618290001Sglebiusseveral batches of keys and 619290001Sglebiusthen activating or deactivating each batch 620290001Sglebiusremotely using 621290001Sglebius<code>ntpdc(1ntpdcmdoc)</code>. 622290001SglebiusThis also provides a revocation capability that can be used 623290001Sglebiusif a key becomes compromised. 624290001SglebiusThe 625290001Sglebius<code>requestkey</code> 626290001Sglebiuscommand selects the key used as the password for the 627290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 628290001Sglebiusutility, while the 629290001Sglebius<code>controlkey</code> 630290001Sglebiuscommand selects the key used as the password for the 631290001Sglebius<code>ntpq(1ntpqmdoc)</code> 632290001Sglebiusutility. 633290001Sglebius 634290001Sglebius<h5 class="subsubsection">Public Key Cryptography</h5> 635290001Sglebius 636290001Sglebius<p>NTPv4 supports the original NTPv3 symmetric key scheme 637290001Sglebiusdescribed in RFC-1305 and in addition the Autokey protocol, 638290001Sglebiuswhich is based on public key cryptography. 639290001SglebiusThe Autokey Version 2 protocol described on the Autokey Protocol 640290001Sglebiuspage verifies packet integrity using MD5 message digests 641290001Sglebiusand verifies the source with digital signatures and any of several 642290001Sglebiusdigest/signature schemes. 643290001SglebiusOptional identity schemes described on the Identity Schemes 644290001Sglebiuspage and based on cryptographic challenge/response algorithms 645290001Sglebiusare also available. 646290001SglebiusUsing all of these schemes provides strong security against 647290001Sglebiusreplay with or without modification, spoofing, masquerade 648290001Sglebiusand most forms of clogging attacks. 649290001Sglebius 650290001Sglebius <p>The Autokey protocol has several modes of operation 651290001Sglebiuscorresponding to the various NTP modes supported. 652290001SglebiusMost modes use a special cookie which can be 653290001Sglebiuscomputed independently by the client and server, 654290001Sglebiusbut encrypted in transmission. 655290001SglebiusAll modes use in addition a variant of the S-KEY scheme, 656290001Sglebiusin which a pseudo-random key list is generated and used 657290001Sglebiusin reverse order. 658290001SglebiusThese schemes are described along with an executive summary, 659290001Sglebiuscurrent status, briefing slides and reading list on the 660290001Sglebius<a href="#Autonomous-Authentication">Autonomous Authentication</a> 661290001Sglebiuspage. 662290001Sglebius 663290001Sglebius <p>The specific cryptographic environment used by Autokey servers 664290001Sglebiusand clients is determined by a set of files 665290001Sglebiusand soft links generated by the 666290001Sglebius<code>ntp-keygen(1ntpkeygenmdoc)</code> 667290001Sglebiusprogram. 668290001SglebiusThis includes a required host key file, 669290001Sglebiusrequired certificate file and optional sign key file, 670290001Sglebiusleapsecond file and identity scheme files. 671290001SglebiusThe 672290001Sglebiusdigest/signature scheme is specified in the X.509 certificate 673290001Sglebiusalong with the matching sign key. 674290001SglebiusThere are several schemes 675290001Sglebiusavailable in the OpenSSL software library, each identified 676290001Sglebiusby a specific string such as 677290001Sglebius<code>md5WithRSAEncryption</code>, 678290001Sglebiuswhich stands for the MD5 message digest with RSA 679290001Sglebiusencryption scheme. 680290001SglebiusThe current NTP distribution supports 681290001Sglebiusall the schemes in the OpenSSL library, including 682290001Sglebiusthose based on RSA and DSA digital signatures. 683290001Sglebius 684290001Sglebius <p>NTP secure groups can be used to define cryptographic compartments 685290001Sglebiusand security hierarchies. 686290001SglebiusIt is important that every host 687290001Sglebiusin the group be able to construct a certificate trail to one 688290001Sglebiusor more trusted hosts in the same group. 689290001SglebiusEach group 690290001Sglebiushost runs the Autokey protocol to obtain the certificates 691290001Sglebiusfor all hosts along the trail to one or more trusted hosts. 692290001SglebiusThis requires the configuration file in all hosts to be 693290001Sglebiusengineered so that, even under anticipated failure conditions, 694290001Sglebiusthe NTP subnet will form such that every group host can find 695290001Sglebiusa trail to at least one trusted host. 696290001Sglebius 697290001Sglebius<h5 class="subsubsection">Naming and Addressing</h5> 698290001Sglebius 699290001Sglebius<p>It is important to note that Autokey does not use DNS to 700290001Sglebiusresolve addresses, since DNS can't be completely trusted 701290001Sglebiusuntil the name servers have synchronized clocks. 702290001SglebiusThe cryptographic name used by Autokey to bind the host identity 703290001Sglebiuscredentials and cryptographic values must be independent 704290001Sglebiusof interface, network and any other naming convention. 705290001SglebiusThe name appears in the host certificate in either or both 706290001Sglebiusthe subject and issuer fields, so protection against 707290001SglebiusDNS compromise is essential. 708290001Sglebius 709290001Sglebius <p>By convention, the name of an Autokey host is the name returned 710290001Sglebiusby the Unix 711290001Sglebius<code>gethostname(2)</code> 712290001Sglebiussystem call or equivalent in other systems. 713290001SglebiusBy the system design 714290001Sglebiusmodel, there are no provisions to allow alternate names or aliases. 715290001SglebiusHowever, this is not to say that DNS aliases, different names 716290001Sglebiusfor each interface, etc., are constrained in any way. 717290001Sglebius 718290001Sglebius <p>It is also important to note that Autokey verifies authenticity 719290001Sglebiususing the host name, network address and public keys, 720290001Sglebiusall of which are bound together by the protocol specifically 721290001Sglebiusto deflect masquerade attacks. 722290001SglebiusFor this reason Autokey 723301301Sdelphijincludes the source and destination IP addresses in message digest 724290001Sglebiuscomputations and so the same addresses must be available 725290001Sglebiusat both the server and client. 726290001SglebiusFor this reason operation 727290001Sglebiuswith network address translation schemes is not possible. 728290001SglebiusThis reflects the intended robust security model where government 729290001Sglebiusand corporate NTP servers are operated outside firewall perimeters. 730290001Sglebius 731290001Sglebius<h5 class="subsubsection">Operation</h5> 732290001Sglebius 733290001Sglebius<p>A specific combination of authentication scheme (none, 734290001Sglebiussymmetric key, public key) and identity scheme is called 735290001Sglebiusa cryptotype, although not all combinations are compatible. 736290001SglebiusThere may be management configurations where the clients, 737290001Sglebiusservers and peers may not all support the same cryptotypes. 738290001SglebiusA secure NTPv4 subnet can be configured in many ways while 739290001Sglebiuskeeping in mind the principles explained above and 740290001Sglebiusin this section. 741290001SglebiusNote however that some cryptotype 742290001Sglebiuscombinations may successfully interoperate with each other, 743290001Sglebiusbut may not represent good security practice. 744290001Sglebius 745290001Sglebius <p>The cryptotype of an association is determined at the time 746290001Sglebiusof mobilization, either at configuration time or some time 747290001Sglebiuslater when a message of appropriate cryptotype arrives. 748290001SglebiusWhen mobilized by a 749290001Sglebius<code>server</code> 750290001Sglebiusor 751290001Sglebius<code>peer</code> 752290001Sglebiusconfiguration command and no 753290001Sglebius<code>key</code> 754290001Sglebiusor 755290001Sglebius<code>autokey</code> 756290001Sglebiussubcommands are present, the association is not 757290001Sglebiusauthenticated; if the 758290001Sglebius<code>key</code> 759290001Sglebiussubcommand is present, the association is authenticated 760290001Sglebiususing the symmetric key ID specified; if the 761290001Sglebius<code>autokey</code> 762290001Sglebiussubcommand is present, the association is authenticated 763290001Sglebiususing Autokey. 764290001Sglebius 765290001Sglebius <p>When multiple identity schemes are supported in the Autokey 766290001Sglebiusprotocol, the first message exchange determines which one is used. 767290001SglebiusThe client request message contains bits corresponding 768290001Sglebiusto which schemes it has available. 769290001SglebiusThe server response message 770290001Sglebiuscontains bits corresponding to which schemes it has available. 771290001SglebiusBoth server and client match the received bits with their own 772290001Sglebiusand select a common scheme. 773290001Sglebius 774290001Sglebius <p>Following the principle that time is a public value, 775290001Sglebiusa server responds to any client packet that matches 776290001Sglebiusits cryptotype capabilities. 777290001SglebiusThus, a server receiving 778290001Sglebiusan unauthenticated packet will respond with an unauthenticated 779290001Sglebiuspacket, while the same server receiving a packet of a cryptotype 780290001Sglebiusit supports will respond with packets of that cryptotype. 781290001SglebiusHowever, unconfigured broadcast or manycast client 782290001Sglebiusassociations or symmetric passive associations will not be 783290001Sglebiusmobilized unless the server supports a cryptotype compatible 784290001Sglebiuswith the first packet received. 785290001SglebiusBy default, unauthenticated associations will not be mobilized 786290001Sglebiusunless overridden in a decidedly dangerous way. 787290001Sglebius 788290001Sglebius <p>Some examples may help to reduce confusion. 789290001SglebiusClient Alice has no specific cryptotype selected. 790290001SglebiusServer Bob has both a symmetric key file and minimal Autokey files. 791290001SglebiusAlice's unauthenticated messages arrive at Bob, who replies with 792290001Sglebiusunauthenticated messages. 793290001SglebiusCathy has a copy of Bob's symmetric 794290001Sglebiuskey file and has selected key ID 4 in messages to Bob. 795290001SglebiusBob verifies the message with his key ID 4. 796290001SglebiusIf it's the 797290001Sglebiussame key and the message is verified, Bob sends Cathy a reply 798290001Sglebiusauthenticated with that key. 799290001SglebiusIf verification fails, 800290001SglebiusBob sends Cathy a thing called a crypto-NAK, which tells her 801290001Sglebiussomething broke. 802290001SglebiusShe can see the evidence using the 803290001Sglebius<code>ntpq(1ntpqmdoc)</code> 804290001Sglebiusprogram. 805290001Sglebius 806290001Sglebius <p>Denise has rolled her own host key and certificate. 807290001SglebiusShe also uses one of the identity schemes as Bob. 808290001SglebiusShe sends the first Autokey message to Bob and they 809290001Sglebiusboth dance the protocol authentication and identity steps. 810290001SglebiusIf all comes out okay, Denise and Bob continue as described above. 811290001Sglebius 812290001Sglebius <p>It should be clear from the above that Bob can support 813290001Sglebiusall the girls at the same time, as long as he has compatible 814290001Sglebiusauthentication and identity credentials. 815290001SglebiusNow, Bob can act just like the girls in his own choice of servers; 816290001Sglebiushe can run multiple configured associations with multiple different 817290001Sglebiusservers (or the same server, although that might not be useful). 818290001SglebiusBut, wise security policy might preclude some cryptotype 819290001Sglebiuscombinations; for instance, running an identity scheme 820290001Sglebiuswith one server and no authentication with another might not be wise. 821290001Sglebius 822290001Sglebius<h5 class="subsubsection">Key Management</h5> 823290001Sglebius 824290001Sglebius<p>The cryptographic values used by the Autokey protocol are 825290001Sglebiusincorporated as a set of files generated by the 826290001Sglebius<code>ntp-keygen(1ntpkeygenmdoc)</code> 827290001Sglebiusutility program, including symmetric key, host key and 828290001Sglebiuspublic certificate files, as well as sign key, identity parameters 829290001Sglebiusand leapseconds files. 830290001SglebiusAlternatively, host and sign keys and 831290001Sglebiuscertificate files can be generated by the OpenSSL utilities 832290001Sglebiusand certificates can be imported from public certificate 833290001Sglebiusauthorities. 834290001SglebiusNote that symmetric keys are necessary for the 835290001Sglebius<code>ntpq(1ntpqmdoc)</code> 836290001Sglebiusand 837290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 838290001Sglebiusutility programs. 839290001SglebiusThe remaining files are necessary only for the 840290001SglebiusAutokey protocol. 841290001Sglebius 842290001Sglebius <p>Certificates imported from OpenSSL or public certificate 843290001Sglebiusauthorities have certian limitations. 844290001SglebiusThe certificate should be in ASN.1 syntax, X.509 Version 3 845290001Sglebiusformat and encoded in PEM, which is the same format 846290001Sglebiusused by OpenSSL. 847290001SglebiusThe overall length of the certificate encoded 848290001Sglebiusin ASN.1 must not exceed 1024 bytes. 849290001SglebiusThe subject distinguished 850290001Sglebiusname field (CN) is the fully qualified name of the host 851290001Sglebiuson which it is used; the remaining subject fields are ignored. 852290001SglebiusThe certificate extension fields must not contain either 853290001Sglebiusa subject key identifier or a issuer key identifier field; 854290001Sglebiushowever, an extended key usage field for a trusted host must 855290001Sglebiuscontain the value 856290001Sglebius<code>trustRoot</code>;. 857290001SglebiusOther extension fields are ignored. 858290001Sglebius 859290001Sglebius<h5 class="subsubsection">Authentication Commands</h5> 860290001Sglebius 861290001Sglebius <dl> 862290001Sglebius<dt><code>autokey</code> <code>[</code><kbd>logsec</kbd><code>]</code><dd>Specifies the interval between regenerations of the session key 863290001Sglebiuslist used with the Autokey protocol. 864290001SglebiusNote that the size of the key 865290001Sglebiuslist for each association depends on this interval and the current 866290001Sglebiuspoll interval. 867290001SglebiusThe default value is 12 (4096 s or about 1.1 hours). 868290001SglebiusFor poll intervals above the specified interval, a session key list 869290001Sglebiuswith a single entry will be regenerated for every message 870290001Sglebiussent. 871290001Sglebius<br><dt><code>controlkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the 872290001Sglebius<code>ntpq(1ntpqmdoc)</code> 873290001Sglebiusutility, which uses the standard 874290001Sglebiusprotocol defined in RFC-1305. 875290001SglebiusThe 876290001Sglebius<kbd>key</kbd> 877290001Sglebiusargument is 878290001Sglebiusthe key identifier for a trusted key, where the value can be in the 879290001Sglebiusrange 1 to 65,534, inclusive. 880290001Sglebius<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. 881290001SglebiusIt activates public key 882290001Sglebiuscryptography, selects the message digest and signature 883290001Sglebiusencryption scheme and loads the required private and public 884290001Sglebiusvalues described above. 885290001SglebiusIf one or more files are left unspecified, 886290001Sglebiusthe default names are used as described above. 887290001SglebiusUnless the complete path and name of the file are specified, the 888290001Sglebiuslocation of a file is relative to the keys directory specified 889290001Sglebiusin the 890290001Sglebius<code>keysdir</code> 891290001Sglebiuscommand or default 892290001Sglebius<span class="file">/usr/local/etc</span>. 893290001SglebiusFollowing are the subcommands: 894290001Sglebius <dl> 895290001Sglebius<dt><code>cert</code> <kbd>file</kbd><dd>Specifies the location of the required host public certificate file. 896290001SglebiusThis overrides the link 897290001Sglebius<span class="file">ntpkey_cert_</span><kbd>hostname</kbd> 898290001Sglebiusin the keys directory. 899290001Sglebius<br><dt><code>gqpar</code> <kbd>file</kbd><dd>Specifies the location of the optional GQ parameters file. 900290001SglebiusThis 901290001Sglebiusoverrides the link 902290001Sglebius<span class="file">ntpkey_gq_</span><kbd>hostname</kbd> 903290001Sglebiusin the keys directory. 904290001Sglebius<br><dt><code>host</code> <kbd>file</kbd><dd>Specifies the location of the required host key file. 905290001SglebiusThis overrides 906290001Sglebiusthe link 907290001Sglebius<span class="file">ntpkey_key_</span><kbd>hostname</kbd> 908290001Sglebiusin the keys directory. 909301301Sdelphij<br><dt><code>iffpar</code> <kbd>file</kbd><dd>Specifies the location of the optional IFF parameters file. 910301301SdelphijThis overrides the link 911290001Sglebius<span class="file">ntpkey_iff_</span><kbd>hostname</kbd> 912290001Sglebiusin the keys directory. 913290001Sglebius<br><dt><code>leap</code> <kbd>file</kbd><dd>Specifies the location of the optional leapsecond file. 914290001SglebiusThis overrides the link 915290001Sglebius<span class="file">ntpkey_leap</span> 916290001Sglebiusin the keys directory. 917290001Sglebius<br><dt><code>mvpar</code> <kbd>file</kbd><dd>Specifies the location of the optional MV parameters file. 918301301SdelphijThis overrides the link 919290001Sglebius<span class="file">ntpkey_mv_</span><kbd>hostname</kbd> 920290001Sglebiusin the keys directory. 921290001Sglebius<br><dt><code>pw</code> <kbd>password</kbd><dd>Specifies the password to decrypt files containing private keys and 922290001Sglebiusidentity parameters. 923290001SglebiusThis is required only if these files have been 924290001Sglebiusencrypted. 925290001Sglebius<br><dt><code>randfile</code> <kbd>file</kbd><dd>Specifies the location of the random seed file used by the OpenSSL 926290001Sglebiuslibrary. 927290001SglebiusThe defaults are described in the main text above. 928290001Sglebius<br><dt><code>sign</code> <kbd>file</kbd><dd>Specifies the location of the optional sign key file. 929290001SglebiusThis overrides 930290001Sglebiusthe link 931290001Sglebius<span class="file">ntpkey_sign_</span><kbd>hostname</kbd> 932290001Sglebiusin the keys directory. 933290001SglebiusIf this file is 934290001Sglebiusnot found, the host key is also the sign key. 935290001Sglebius</dl> 936290001Sglebius <br><dt><code>keys</code> <kbd>keyfile</kbd><dd>Specifies the complete path and location of the MD5 key file 937290001Sglebiuscontaining the keys and key identifiers used by 938290001Sglebius<code>ntpd(1ntpdmdoc)</code>, 939290001Sglebius<code>ntpq(1ntpqmdoc)</code> 940290001Sglebiusand 941290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 942290001Sglebiuswhen operating with symmetric key cryptography. 943290001SglebiusThis is the same operation as the 944290001Sglebius<code>-k</code> 945290001Sglebiuscommand line option. 946290001Sglebius<br><dt><code>keysdir</code> <kbd>path</kbd><dd>This command specifies the default directory path for 947290001Sglebiuscryptographic keys, parameters and certificates. 948290001SglebiusThe default is 949290001Sglebius<span class="file">/usr/local/etc/</span>. 950290001Sglebius<br><dt><code>requestkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the 951290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 952290001Sglebiusutility program, which uses a 953290001Sglebiusproprietary protocol specific to this implementation of 954290001Sglebius<code>ntpd(1ntpdmdoc)</code>. 955290001SglebiusThe 956290001Sglebius<kbd>key</kbd> 957290001Sglebiusargument is a key identifier 958290001Sglebiusfor the trusted key, where the value can be in the range 1 to 959290001Sglebius65,534, inclusive. 960290001Sglebius<br><dt><code>revoke</code> <kbd>logsec</kbd><dd>Specifies the interval between re-randomization of certain 961290001Sglebiuscryptographic values used by the Autokey scheme, as a power of 2 in 962290001Sglebiusseconds. 963290001SglebiusThese values need to be updated frequently in order to 964290001Sglebiusdeflect brute-force attacks on the algorithms of the scheme; 965290001Sglebiushowever, updating some values is a relatively expensive operation. 966290001SglebiusThe default interval is 16 (65,536 s or about 18 hours). 967290001SglebiusFor poll 968290001Sglebiusintervals above the specified interval, the values will be updated 969290001Sglebiusfor every message sent. 970290001Sglebius<br><dt><code>trustedkey</code> <kbd>key</kbd> <kbd>...</kbd><dd>Specifies the key identifiers which are trusted for the 971290001Sglebiuspurposes of authenticating peers with symmetric key cryptography, 972290001Sglebiusas well as keys used by the 973290001Sglebius<code>ntpq(1ntpqmdoc)</code> 974290001Sglebiusand 975290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 976290001Sglebiusprograms. 977290001SglebiusThe authentication procedures require that both the local 978290001Sglebiusand remote servers share the same key and key identifier for this 979290001Sglebiuspurpose, although different keys can be used with different 980290001Sglebiusservers. 981290001SglebiusThe 982290001Sglebius<kbd>key</kbd> 983290001Sglebiusarguments are 32-bit unsigned 984290001Sglebiusintegers with values from 1 to 65,534. 985290001Sglebius</dl> 986290001Sglebius 987290001Sglebius<h5 class="subsubsection">Error Codes</h5> 988290001Sglebius 989290001Sglebius<p>The following error codes are reported via the NTP control 990290001Sglebiusand monitoring protocol trap mechanism. 991290001Sglebius <dl> 992290001Sglebius<dt>101<dd>(bad field format or length) 993290001SglebiusThe packet has invalid version, length or format. 994290001Sglebius<br><dt>102<dd>(bad timestamp) 995290001SglebiusThe packet timestamp is the same or older than the most recent received. 996290001SglebiusThis could be due to a replay or a server clock time step. 997290001Sglebius<br><dt>103<dd>(bad filestamp) 998290001SglebiusThe packet filestamp is the same or older than the most recent received. 999290001SglebiusThis could be due to a replay or a key file generation error. 1000290001Sglebius<br><dt>104<dd>(bad or missing public key) 1001290001SglebiusThe public key is missing, has incorrect format or is an unsupported type. 1002290001Sglebius<br><dt>105<dd>(unsupported digest type) 1003290001SglebiusThe server requires an unsupported digest/signature scheme. 1004290001Sglebius<br><dt>106<dd>(mismatched digest types) 1005290001SglebiusNot used. 1006290001Sglebius<br><dt>107<dd>(bad signature length) 1007290001SglebiusThe signature length does not match the current public key. 1008290001Sglebius<br><dt>108<dd>(signature not verified) 1009290001SglebiusThe message fails the signature check. 1010290001SglebiusIt could be bogus or signed by a 1011290001Sglebiusdifferent private key. 1012290001Sglebius<br><dt>109<dd>(certificate not verified) 1013290001SglebiusThe certificate is invalid or signed with the wrong key. 1014290001Sglebius<br><dt>110<dd>(certificate not verified) 1015290001SglebiusThe certificate is not yet valid or has expired or the signature could not 1016290001Sglebiusbe verified. 1017290001Sglebius<br><dt>111<dd>(bad or missing cookie) 1018290001SglebiusThe cookie is missing, corrupted or bogus. 1019290001Sglebius<br><dt>112<dd>(bad or missing leapseconds table) 1020290001SglebiusThe leapseconds table is missing, corrupted or bogus. 1021290001Sglebius<br><dt>113<dd>(bad or missing certificate) 1022290001SglebiusThe certificate is missing, corrupted or bogus. 1023290001Sglebius<br><dt>114<dd>(bad or missing identity) 1024290001SglebiusThe identity key is missing, corrupt or bogus. 1025290001Sglebius</dl> 1026290001Sglebius <div class="node"> 1027290001Sglebius<p><hr> 1028290001Sglebius<a name="Monitoring-Support"></a> 1029290001Sglebius<br> 1030290001Sglebius</div> 1031290001Sglebius 1032290001Sglebius<h4 class="subsection">Monitoring Support</h4> 1033290001Sglebius 1034290001Sglebius<p><code>ntpd(1ntpdmdoc)</code> 1035290001Sglebiusincludes a comprehensive monitoring facility suitable 1036290001Sglebiusfor continuous, long term recording of server and client 1037290001Sglebiustimekeeping performance. 1038290001SglebiusSee the 1039290001Sglebius<code>statistics</code> 1040290001Sglebiuscommand below 1041290001Sglebiusfor a listing and example of each type of statistics currently 1042290001Sglebiussupported. 1043290001SglebiusStatistic files are managed using file generation sets 1044290001Sglebiusand scripts in the 1045290001Sglebius<span class="file">./scripts</span> 1046301301Sdelphijdirectory of the source code distribution. 1047290001SglebiusUsing 1048290001Sglebiusthese facilities and 1049290001Sglebius<span class="sc">unix</span> 1050290001Sglebius<code>cron(8)</code> 1051290001Sglebiusjobs, the data can be 1052290001Sglebiusautomatically summarized and archived for retrospective analysis. 1053290001Sglebius 1054290001Sglebius<h5 class="subsubsection">Monitoring Commands</h5> 1055290001Sglebius 1056290001Sglebius <dl> 1057290001Sglebius<dt><code>statistics</code> <kbd>name</kbd> <kbd>...</kbd><dd>Enables writing of statistics records. 1058290001SglebiusCurrently, eight kinds of 1059290001Sglebius<kbd>name</kbd> 1060290001Sglebiusstatistics are supported. 1061290001Sglebius <dl> 1062290001Sglebius<dt><code>clockstats</code><dd>Enables recording of clock driver statistics information. 1063290001SglebiusEach update 1064290001Sglebiusreceived from a clock driver appends a line of the following form to 1065290001Sglebiusthe file generation set named 1066290001Sglebius<code>clockstats</code>: 1067290001Sglebius<pre class="verbatim"> 1068290001Sglebius 49213 525.624 127.127.4.1 93 226 00:08:29.606 D 1069290001Sglebius </pre> 1070290001Sglebius 1071290001Sglebius <p>The first two fields show the date (Modified Julian Day) and time 1072290001Sglebius(seconds and fraction past UTC midnight). 1073290001SglebiusThe next field shows the 1074290001Sglebiusclock address in dotted-quad notation. 1075290001SglebiusThe final field shows the last 1076290001Sglebiustimecode received from the clock in decoded ASCII format, where 1077290001Sglebiusmeaningful. 1078290001SglebiusIn some clock drivers a good deal of additional information 1079290001Sglebiuscan be gathered and displayed as well. 1080290001SglebiusSee information specific to each 1081290001Sglebiusclock for further details. 1082290001Sglebius<br><dt><code>cryptostats</code><dd>This option requires the OpenSSL cryptographic software library. 1083290001SglebiusIt 1084290001Sglebiusenables recording of cryptographic public key protocol information. 1085290001SglebiusEach message received by the protocol module appends a line of the 1086290001Sglebiusfollowing form to the file generation set named 1087290001Sglebius<code>cryptostats</code>: 1088290001Sglebius<pre class="verbatim"> 1089290001Sglebius 49213 525.624 127.127.4.1 message 1090290001Sglebius </pre> 1091290001Sglebius 1092290001Sglebius <p>The first two fields show the date (Modified Julian Day) and time 1093290001Sglebius(seconds and fraction past UTC midnight). 1094290001SglebiusThe next field shows the peer 1095290001Sglebiusaddress in dotted-quad notation, The final message field includes the 1096290001Sglebiusmessage type and certain ancillary information. 1097290001SglebiusSee the 1098290001Sglebius<a href="#Authentication-Options">Authentication Options</a> 1099290001Sglebiussection for further information. 1100290001Sglebius<br><dt><code>loopstats</code><dd>Enables recording of loop filter statistics information. 1101290001SglebiusEach 1102290001Sglebiusupdate of the local clock outputs a line of the following form to 1103290001Sglebiusthe file generation set named 1104290001Sglebius<code>loopstats</code>: 1105290001Sglebius<pre class="verbatim"> 1106290001Sglebius 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 1107290001Sglebius </pre> 1108290001Sglebius 1109290001Sglebius <p>The first two fields show the date (Modified Julian Day) and 1110290001Sglebiustime (seconds and fraction past UTC midnight). 1111290001SglebiusThe next five fields 1112290001Sglebiusshow time offset (seconds), frequency offset (parts per million - 1113290001SglebiusPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 1114290001Sglebiusdiscipline time constant. 1115290001Sglebius<br><dt><code>peerstats</code><dd>Enables recording of peer statistics information. 1116290001SglebiusThis includes 1117290001Sglebiusstatistics records of all peers of a NTP server and of special 1118290001Sglebiussignals, where present and configured. 1119290001SglebiusEach valid update appends a 1120290001Sglebiusline of the following form to the current element of a file 1121290001Sglebiusgeneration set named 1122290001Sglebius<code>peerstats</code>: 1123290001Sglebius<pre class="verbatim"> 1124290001Sglebius 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 1125290001Sglebius </pre> 1126290001Sglebius 1127290001Sglebius <p>The first two fields show the date (Modified Julian Day) and 1128290001Sglebiustime (seconds and fraction past UTC midnight). 1129290001SglebiusThe next two fields 1130290001Sglebiusshow the peer address in dotted-quad notation and status, 1131290001Sglebiusrespectively. 1132290001SglebiusThe status field is encoded in hex in the format 1133290001Sglebiusdescribed in Appendix A of the NTP specification RFC 1305. 1134290001SglebiusThe final four fields show the offset, 1135290001Sglebiusdelay, dispersion and RMS jitter, all in seconds. 1136290001Sglebius<br><dt><code>rawstats</code><dd>Enables recording of raw-timestamp statistics information. 1137290001SglebiusThis 1138290001Sglebiusincludes statistics records of all peers of a NTP server and of 1139290001Sglebiusspecial signals, where present and configured. 1140290001SglebiusEach NTP message 1141290001Sglebiusreceived from a peer or clock driver appends a line of the 1142290001Sglebiusfollowing form to the file generation set named 1143290001Sglebius<code>rawstats</code>: 1144290001Sglebius<pre class="verbatim"> 1145290001Sglebius 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 1146290001Sglebius </pre> 1147290001Sglebius 1148290001Sglebius <p>The first two fields show the date (Modified Julian Day) and 1149290001Sglebiustime (seconds and fraction past UTC midnight). 1150290001SglebiusThe next two fields 1151290001Sglebiusshow the remote peer or clock address followed by the local address 1152290001Sglebiusin dotted-quad notation. 1153290001SglebiusThe final four fields show the originate, 1154290001Sglebiusreceive, transmit and final NTP timestamps in order. 1155290001SglebiusThe timestamp 1156290001Sglebiusvalues are as received and before processing by the various data 1157290001Sglebiussmoothing and mitigation algorithms. 1158290001Sglebius<br><dt><code>sysstats</code><dd>Enables recording of ntpd statistics counters on a periodic basis. 1159290001SglebiusEach 1160290001Sglebiushour a line of the following form is appended to the file generation 1161290001Sglebiusset named 1162290001Sglebius<code>sysstats</code>: 1163290001Sglebius<pre class="verbatim"> 1164290001Sglebius 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 1165290001Sglebius </pre> 1166290001Sglebius 1167290001Sglebius <p>The first two fields show the date (Modified Julian Day) and time 1168290001Sglebius(seconds and fraction past UTC midnight). 1169290001SglebiusThe remaining ten fields show 1170290001Sglebiusthe statistics counter values accumulated since the last generated 1171290001Sglebiusline. 1172290001Sglebius <dl> 1173290001Sglebius<dt>Time since restart <code>36000</code><dd>Time in hours since the system was last rebooted. 1174290001Sglebius<br><dt>Packets received <code>81965</code><dd>Total number of packets received. 1175290001Sglebius<br><dt>Packets processed <code>0</code><dd>Number of packets received in response to previous packets sent 1176290001Sglebius<br><dt>Current version <code>9546</code><dd>Number of packets matching the current NTP version. 1177290001Sglebius<br><dt>Previous version <code>56</code><dd>Number of packets matching the previous NTP version. 1178290001Sglebius<br><dt>Bad version <code>71793</code><dd>Number of packets matching neither NTP version. 1179290001Sglebius<br><dt>Access denied <code>512</code><dd>Number of packets denied access for any reason. 1180290001Sglebius<br><dt>Bad length or format <code>540</code><dd>Number of packets with invalid length, format or port number. 1181290001Sglebius<br><dt>Bad authentication <code>10</code><dd>Number of packets not verified as authentic. 1182290001Sglebius<br><dt>Rate exceeded <code>147</code><dd>Number of packets discarded due to rate limitation. 1183290001Sglebius</dl> 1184290001Sglebius <br><dt><code>statsdir</code> <kbd>directory_path</kbd><dd>Indicates the full path of a directory where statistics files 1185290001Sglebiusshould be created (see below). 1186290001SglebiusThis keyword allows 1187290001Sglebiusthe (otherwise constant) 1188290001Sglebius<code>filegen</code> 1189290001Sglebiusfilename prefix to be modified for file generation sets, which 1190290001Sglebiusis useful for handling statistics logs. 1191290001Sglebius<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. 1192290001SglebiusGeneration 1193290001Sglebiusfile sets provide a means for handling files that are 1194290001Sglebiuscontinuously growing during the lifetime of a server. 1195290001SglebiusServer statistics are a typical example for such files. 1196290001SglebiusGeneration file sets provide access to a set of files used 1197290001Sglebiusto store the actual data. 1198290001SglebiusAt any time at most one element 1199290001Sglebiusof the set is being written to. 1200290001SglebiusThe type given specifies 1201290001Sglebiuswhen and how data will be directed to a new element of the set. 1202290001SglebiusThis way, information stored in elements of a file set 1203290001Sglebiusthat are currently unused are available for administrational 1204290001Sglebiusoperations without the risk of disturbing the operation of ntpd. 1205290001Sglebius(Most important: they can be removed to free space for new data 1206290001Sglebiusproduced.) 1207290001Sglebius 1208290001Sglebius <p>Note that this command can be sent from the 1209290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 1210290001Sglebiusprogram running at a remote location. 1211290001Sglebius <dl> 1212290001Sglebius<dt><code>name</code><dd>This is the type of the statistics records, as shown in the 1213290001Sglebius<code>statistics</code> 1214290001Sglebiuscommand. 1215290001Sglebius<br><dt><code>file</code> <kbd>filename</kbd><dd>This is the file name for the statistics records. 1216290001SglebiusFilenames of set 1217290001Sglebiusmembers are built from three concatenated elements 1218290001Sglebius<code>prefix</code>, 1219290001Sglebius<code>filename</code> 1220290001Sglebiusand 1221290001Sglebius<code>suffix</code>: 1222290001Sglebius <dl> 1223290001Sglebius<dt><code>prefix</code><dd>This is a constant filename path. 1224290001SglebiusIt is not subject to 1225290001Sglebiusmodifications via the 1226290001Sglebius<kbd>filegen</kbd> 1227290001Sglebiusoption. 1228290001SglebiusIt is defined by the 1229290001Sglebiusserver, usually specified as a compile-time constant. 1230290001SglebiusIt may, 1231290001Sglebiushowever, be configurable for individual file generation sets 1232290001Sglebiusvia other commands. 1233290001SglebiusFor example, the prefix used with 1234290001Sglebius<kbd>loopstats</kbd> 1235290001Sglebiusand 1236290001Sglebius<kbd>peerstats</kbd> 1237290001Sglebiusgeneration can be configured using the 1238290001Sglebius<kbd>statsdir</kbd> 1239290001Sglebiusoption explained above. 1240290001Sglebius<br><dt><code>filename</code><dd>This string is directly concatenated to the prefix mentioned 1241290001Sglebiusabove (no intervening 1242290001Sglebius/). 1243290001SglebiusThis can be modified using 1244290001Sglebiusthe file argument to the 1245290001Sglebius<kbd>filegen</kbd> 1246290001Sglebiusstatement. 1247290001SglebiusNo 1248290001Sglebius<span class="file">..</span> 1249290001Sglebiuselements are 1250290001Sglebiusallowed in this component to prevent filenames referring to 1251290001Sglebiusparts outside the filesystem hierarchy denoted by 1252290001Sglebius<kbd>prefix</kbd>. 1253290001Sglebius<br><dt><code>suffix</code><dd>This part is reflects individual elements of a file set. 1254290001SglebiusIt is 1255290001Sglebiusgenerated according to the type of a file set. 1256290001Sglebius</dl> 1257290001Sglebius <br><dt><code>type</code> <kbd>typename</kbd><dd>A file generation set is characterized by its type. 1258290001SglebiusThe following 1259290001Sglebiustypes are supported: 1260290001Sglebius <dl> 1261290001Sglebius<dt><code>none</code><dd>The file set is actually a single plain file. 1262290001Sglebius<br><dt><code>pid</code><dd>One element of file set is used per incarnation of a ntpd 1263290001Sglebiusserver. 1264290001SglebiusThis type does not perform any changes to file set 1265290001Sglebiusmembers during runtime, however it provides an easy way of 1266290001Sglebiusseparating files belonging to different 1267290001Sglebius<code>ntpd(1ntpdmdoc)</code> 1268290001Sglebiusserver incarnations. 1269290001SglebiusThe set member filename is built by appending a 1270290001Sglebius. 1271290001Sglebiusto concatenated 1272290001Sglebius<kbd>prefix</kbd> 1273290001Sglebiusand 1274290001Sglebius<kbd>filename</kbd> 1275290001Sglebiusstrings, and 1276290001Sglebiusappending the decimal representation of the process ID of the 1277290001Sglebius<code>ntpd(1ntpdmdoc)</code> 1278290001Sglebiusserver process. 1279290001Sglebius<br><dt><code>day</code><dd>One file generation set element is created per day. 1280290001SglebiusA day is 1281290001Sglebiusdefined as the period between 00:00 and 24:00 UTC. 1282290001SglebiusThe file set 1283290001Sglebiusmember suffix consists of a 1284290001Sglebius. 1285290001Sglebiusand a day specification in 1286290001Sglebiusthe form 1287290001Sglebius<code>YYYYMMdd</code>. 1288290001Sglebius<code>YYYY</code> 1289290001Sglebiusis a 4-digit year number (e.g., 1992). 1290290001Sglebius<code>MM</code> 1291290001Sglebiusis a two digit month number. 1292290001Sglebius<code>dd</code> 1293290001Sglebiusis a two digit day number. 1294290001SglebiusThus, all information written at 10 December 1992 would end up 1295290001Sglebiusin a file named 1296290001Sglebius<kbd>prefix</kbd> 1297290001Sglebius<kbd>filename</kbd>.19921210. 1298290001Sglebius<br><dt><code>week</code><dd>Any file set member contains data related to a certain week of 1299290001Sglebiusa year. 1300290001SglebiusThe term week is defined by computing day-of-year 1301290001Sglebiusmodulo 7. 1302290001SglebiusElements of such a file generation set are 1303290001Sglebiusdistinguished by appending the following suffix to the file set 1304290001Sglebiusfilename base: A dot, a 4-digit year number, the letter 1305290001Sglebius<code>W</code>, 1306290001Sglebiusand a 2-digit week number. 1307290001SglebiusFor example, information from January, 1308290001Sglebius10th 1992 would end up in a file with suffix 1309290001Sglebius.No . Ns Ar 1992W1 . 1310290001Sglebius<br><dt><code>month</code><dd>One generation file set element is generated per month. 1311290001SglebiusThe 1312290001Sglebiusfile name suffix consists of a dot, a 4-digit year number, and 1313290001Sglebiusa 2-digit month. 1314290001Sglebius<br><dt><code>year</code><dd>One generation file element is generated per year. 1315290001SglebiusThe filename 1316290001Sglebiussuffix consists of a dot and a 4 digit year number. 1317290001Sglebius<br><dt><code>age</code><dd>This type of file generation sets changes to a new element of 1318290001Sglebiusthe file set every 24 hours of server operation. 1319290001SglebiusThe filename 1320290001Sglebiussuffix consists of a dot, the letter 1321290001Sglebius<code>a</code>, 1322290001Sglebiusand an 8-digit number. 1323290001SglebiusThis number is taken to be the number of seconds the server is 1324290001Sglebiusrunning at the start of the corresponding 24-hour period. 1325290001SglebiusInformation is only written to a file generation by specifying 1326290001Sglebius<code>enable</code>; 1327290001Sglebiusoutput is prevented by specifying 1328290001Sglebius<code>disable</code>. 1329290001Sglebius</dl> 1330290001Sglebius <br><dt><code>link</code> | <code>nolink</code><dd>It is convenient to be able to access the current element of a file 1331290001Sglebiusgeneration set by a fixed name. 1332290001SglebiusThis feature is enabled by 1333290001Sglebiusspecifying 1334290001Sglebius<code>link</code> 1335290001Sglebiusand disabled using 1336290001Sglebius<code>nolink</code>. 1337290001SglebiusIf link is specified, a 1338290001Sglebiushard link from the current file set element to a file without 1339290001Sglebiussuffix is created. 1340290001SglebiusWhen there is already a file with this name and 1341290001Sglebiusthe number of links of this file is one, it is renamed appending a 1342290001Sglebiusdot, the letter 1343290001Sglebius<code>C</code>, 1344301301Sdelphijand the pid of the 1345301301Sdelphij<code>ntpd(1ntpdmdoc)</code> 1346301301Sdelphijserver process. 1347290001SglebiusWhen the 1348290001Sglebiusnumber of links is greater than one, the file is unlinked. 1349290001SglebiusThis 1350290001Sglebiusallows the current file to be accessed by a constant name. 1351290001Sglebius<br><dt><code>enable</code> <code>|</code> <code>disable</code><dd>Enables or disables the recording function. 1352290001Sglebius</dl> 1353290001Sglebius </dl> 1354290001Sglebius </dl> 1355290001Sglebius<div class="node"> 1356290001Sglebius<p><hr> 1357290001Sglebius<a name="Access-Control-Support"></a> 1358290001Sglebius<br> 1359290001Sglebius</div> 1360290001Sglebius 1361290001Sglebius<h4 class="subsection">Access Control Support</h4> 1362290001Sglebius 1363290001Sglebius<p>The 1364290001Sglebius<code>ntpd(1ntpdmdoc)</code> 1365290001Sglebiusdaemon implements a general purpose address/mask based restriction 1366290001Sglebiuslist. 1367290001SglebiusThe list contains address/match entries sorted first 1368290001Sglebiusby increasing address values and and then by increasing mask values. 1369290001SglebiusA match occurs when the bitwise AND of the mask and the packet 1370290001Sglebiussource address is equal to the bitwise AND of the mask and 1371290001Sglebiusaddress in the list. 1372290001SglebiusThe list is searched in order with the 1373290001Sglebiuslast match found defining the restriction flags associated 1374290001Sglebiuswith the entry. 1375290001SglebiusAdditional information and examples can be found in the 1376290001Sglebius"Notes on Configuring NTP and Setting up a NTP Subnet" 1377290001Sglebiuspage 1378290001Sglebius(available as part of the HTML documentation 1379290001Sglebiusprovided in 1380290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 1381290001Sglebius 1382290001Sglebius <p>The restriction facility was implemented in conformance 1383290001Sglebiuswith the access policies for the original NSFnet backbone 1384290001Sglebiustime servers. 1385290001SglebiusLater the facility was expanded to deflect 1386290001Sglebiuscryptographic and clogging attacks. 1387290001SglebiusWhile this facility may 1388290001Sglebiusbe useful for keeping unwanted or broken or malicious clients 1389290001Sglebiusfrom congesting innocent servers, it should not be considered 1390290001Sglebiusan alternative to the NTP authentication facilities. 1391290001SglebiusSource address based restrictions are easily circumvented 1392290001Sglebiusby a determined cracker. 1393290001Sglebius 1394290001Sglebius <p>Clients can be denied service because they are explicitly 1395298770Sdelphijincluded in the restrict list created by the 1396298770Sdelphij<code>restrict</code> 1397298770Sdelphijcommand 1398290001Sglebiusor implicitly as the result of cryptographic or rate limit 1399290001Sglebiusviolations. 1400290001SglebiusCryptographic violations include certificate 1401290001Sglebiusor identity verification failure; rate limit violations generally 1402290001Sglebiusresult from defective NTP implementations that send packets 1403290001Sglebiusat abusive rates. 1404290001SglebiusSome violations cause denied service 1405290001Sglebiusonly for the offending packet, others cause denied service 1406290001Sglebiusfor a timed period and others cause the denied service for 1407301301Sdelphijan indefinite period. 1408290001SglebiusWhen a client or network is denied access 1409301301Sdelphijfor an indefinite period, the only way at present to remove 1410290001Sglebiusthe restrictions is by restarting the server. 1411290001Sglebius 1412290001Sglebius<h5 class="subsubsection">The Kiss-of-Death Packet</h5> 1413290001Sglebius 1414290001Sglebius<p>Ordinarily, packets denied service are simply dropped with no 1415290001Sglebiusfurther action except incrementing statistics counters. 1416290001SglebiusSometimes a 1417290001Sglebiusmore proactive response is needed, such as a server message that 1418290001Sglebiusexplicitly requests the client to stop sending and leave a message 1419290001Sglebiusfor the system operator. 1420290001SglebiusA special packet format has been created 1421290001Sglebiusfor this purpose called the "kiss-of-death" (KoD) packet. 1422290001SglebiusKoD packets have the leap bits set unsynchronized and stratum set 1423290001Sglebiusto zero and the reference identifier field set to a four-byte 1424290001SglebiusASCII code. 1425290001SglebiusIf the 1426290001Sglebius<code>noserve</code> 1427290001Sglebiusor 1428290001Sglebius<code>notrust</code> 1429290001Sglebiusflag of the matching restrict list entry is set, 1430290001Sglebiusthe code is "DENY"; if the 1431290001Sglebius<code>limited</code> 1432290001Sglebiusflag is set and the rate limit 1433290001Sglebiusis exceeded, the code is "RATE". 1434290001SglebiusFinally, if a cryptographic violation occurs, the code is "CRYP". 1435290001Sglebius 1436290001Sglebius <p>A client receiving a KoD performs a set of sanity checks to 1437290001Sglebiusminimize security exposure, then updates the stratum and 1438290001Sglebiusreference identifier peer variables, sets the access 1439290001Sglebiusdenied (TEST4) bit in the peer flash variable and sends 1440290001Sglebiusa message to the log. 1441290001SglebiusAs long as the TEST4 bit is set, 1442290001Sglebiusthe client will send no further packets to the server. 1443290001SglebiusThe only way at present to recover from this condition is 1444290001Sglebiusto restart the protocol at both the client and server. 1445290001SglebiusThis 1446290001Sglebiushappens automatically at the client when the association times out. 1447290001SglebiusIt will happen at the server only if the server operator cooperates. 1448290001Sglebius 1449290001Sglebius<h5 class="subsubsection">Access Control Commands</h5> 1450290001Sglebius 1451290001Sglebius <dl> 1452290001Sglebius<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 1453290001Sglebius<code>limited</code> 1454290001Sglebiusfacility which protects the server from 1455290001Sglebiusclient abuse. 1456290001SglebiusThe 1457290001Sglebius<code>average</code> 1458290001Sglebiussubcommand specifies the minimum average packet 1459290001Sglebiusspacing, while the 1460290001Sglebius<code>minimum</code> 1461290001Sglebiussubcommand specifies the minimum packet spacing. 1462290001SglebiusPackets that violate these minima are discarded 1463290001Sglebiusand a kiss-o'-death packet returned if enabled. 1464290001SglebiusThe default 1465290001Sglebiusminimum average and minimum are 5 and 2, respectively. 1466298770SdelphijThe 1467298770Sdelphij<code>monitor</code> 1468298770Sdelphijsubcommand specifies the probability of discard 1469290001Sglebiusfor packets that overflow the rate-control window. 1470290001Sglebius<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 1471290001Sglebius<kbd>address</kbd> 1472290001Sglebiusargument expressed in 1473290001Sglebiusdotted-quad form is the address of a host or network. 1474290001SglebiusAlternatively, the 1475290001Sglebius<kbd>address</kbd> 1476290001Sglebiusargument can be a valid host DNS name. 1477290001SglebiusThe 1478290001Sglebius<kbd>mask</kbd> 1479290001Sglebiusargument expressed in dotted-quad form defaults to 1480290001Sglebius<code>255.255.255.255</code>, 1481290001Sglebiusmeaning that the 1482290001Sglebius<kbd>address</kbd> 1483290001Sglebiusis treated as the address of an individual host. 1484290001SglebiusA default entry (address 1485290001Sglebius<code>0.0.0.0</code>, 1486290001Sglebiusmask 1487290001Sglebius<code>0.0.0.0</code>) 1488290001Sglebiusis always included and is always the first entry in the list. 1489290001SglebiusNote that text string 1490290001Sglebius<code>default</code>, 1491290001Sglebiuswith no mask option, may 1492290001Sglebiusbe used to indicate the default entry. 1493290001SglebiusIn the current implementation, 1494290001Sglebius<code>flag</code> 1495290001Sglebiusalways 1496290001Sglebiusrestricts access, i.e., an entry with no flags indicates that free 1497290001Sglebiusaccess to the server is to be given. 1498290001SglebiusThe flags are not orthogonal, 1499290001Sglebiusin that more restrictive flags will often make less restrictive 1500290001Sglebiusones redundant. 1501290001SglebiusThe flags can generally be classed into two 1502290001Sglebiuscategories, those which restrict time service and those which 1503290001Sglebiusrestrict informational queries and attempts to do run-time 1504290001Sglebiusreconfiguration of the server. 1505290001SglebiusOne or more of the following flags 1506290001Sglebiusmay be specified: 1507290001Sglebius <dl> 1508290001Sglebius<dt><code>ignore</code><dd>Deny packets of all kinds, including 1509290001Sglebius<code>ntpq(1ntpqmdoc)</code> 1510290001Sglebiusand 1511290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 1512290001Sglebiusqueries. 1513290001Sglebius<br><dt><code>kod</code><dd>If this flag is set when an access violation occurs, a kiss-o'-death 1514290001Sglebius(KoD) packet is sent. 1515290001SglebiusKoD packets are rate limited to no more than one 1516290001Sglebiusper second. 1517290001SglebiusIf another KoD packet occurs within one second after the 1518290001Sglebiuslast one, the packet is dropped. 1519290001Sglebius<br><dt><code>limited</code><dd>Deny service if the packet spacing violates the lower limits specified 1520298770Sdelphijin the 1521298770Sdelphij<code>discard</code> 1522298770Sdelphijcommand. 1523290001SglebiusA history of clients is kept using the 1524290001Sglebiusmonitoring capability of 1525290001Sglebius<code>ntpd(1ntpdmdoc)</code>. 1526290001SglebiusThus, monitoring is always active as 1527290001Sglebiuslong as there is a restriction entry with the 1528290001Sglebius<code>limited</code> 1529290001Sglebiusflag. 1530290001Sglebius<br><dt><code>lowpriotrap</code><dd>Declare traps set by matching hosts to be low priority. 1531290001SglebiusThe 1532290001Sglebiusnumber of traps a server can maintain is limited (the current limit 1533290001Sglebiusis 3). 1534290001SglebiusTraps are usually assigned on a first come, first served 1535290001Sglebiusbasis, with later trap requestors being denied service. 1536290001SglebiusThis flag 1537290001Sglebiusmodifies the assignment algorithm by allowing low priority traps to 1538290001Sglebiusbe overridden by later requests for normal priority traps. 1539290001Sglebius<br><dt><code>nomodify</code><dd>Deny 1540290001Sglebius<code>ntpq(1ntpqmdoc)</code> 1541290001Sglebiusand 1542290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 1543290001Sglebiusqueries which attempt to modify the state of the 1544290001Sglebiusserver (i.e., run time reconfiguration). 1545290001SglebiusQueries which return 1546290001Sglebiusinformation are permitted. 1547290001Sglebius<br><dt><code>noquery</code><dd>Deny 1548290001Sglebius<code>ntpq(1ntpqmdoc)</code> 1549290001Sglebiusand 1550290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 1551290001Sglebiusqueries. 1552290001SglebiusTime service is not affected. 1553290001Sglebius<br><dt><code>nopeer</code><dd>Deny packets which would result in mobilizing a new association. 1554290001SglebiusThis 1555290001Sglebiusincludes broadcast and symmetric active packets when a configured 1556290001Sglebiusassociation does not exist. 1557290001SglebiusIt also includes 1558290001Sglebius<code>pool</code> 1559290001Sglebiusassociations, so if you want to use servers from a 1560290001Sglebius<code>pool</code> 1561290001Sglebiusdirective and also want to use 1562290001Sglebius<code>nopeer</code> 1563290001Sglebiusby default, you'll want a 1564290001Sglebius<code>restrict source ...</code> <code>line</code> <code>as</code> <code>well</code> <code>that</code> <code>does</code> 1565290001Sglebius<br><dt>not<dd>include the 1566290001Sglebius<code>nopeer</code> 1567290001Sglebiusdirective. 1568290001Sglebius<br><dt><code>noserve</code><dd>Deny all packets except 1569290001Sglebius<code>ntpq(1ntpqmdoc)</code> 1570290001Sglebiusand 1571290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 1572290001Sglebiusqueries. 1573290001Sglebius<br><dt><code>notrap</code><dd>Decline to provide mode 6 control message trap service to matching 1574290001Sglebiushosts. 1575301301SdelphijThe trap service is a subsystem of the 1576301301Sdelphij<code>ntpq(1ntpqmdoc)</code> 1577301301Sdelphijcontrol message 1578290001Sglebiusprotocol which is intended for use by remote event logging programs. 1579290001Sglebius<br><dt><code>notrust</code><dd>Deny service unless the packet is cryptographically authenticated. 1580290001Sglebius<br><dt><code>ntpport</code><dd>This is actually a match algorithm modifier, rather than a 1581290001Sglebiusrestriction flag. 1582290001SglebiusIts presence causes the restriction entry to be 1583290001Sglebiusmatched only if the source port in the packet is the standard NTP 1584290001SglebiusUDP port (123). 1585290001SglebiusBoth 1586290001Sglebius<code>ntpport</code> 1587290001Sglebiusand 1588290001Sglebius<code>non-ntpport</code> 1589290001Sglebiusmay 1590290001Sglebiusbe specified. 1591290001SglebiusThe 1592290001Sglebius<code>ntpport</code> 1593290001Sglebiusis considered more specific and 1594290001Sglebiusis sorted later in the list. 1595290001Sglebius<br><dt><code>version</code><dd>Deny packets that do not match the current NTP version. 1596290001Sglebius</dl> 1597290001Sglebius 1598290001Sglebius <p>Default restriction list entries with the flags ignore, interface, 1599290001Sglebiusntpport, for each of the local host's interface addresses are 1600290001Sglebiusinserted into the table at startup to prevent the server 1601290001Sglebiusfrom attempting to synchronize to its own time. 1602290001SglebiusA default entry is also always present, though if it is 1603290001Sglebiusotherwise unconfigured; no flags are associated 1604290001Sglebiuswith the default entry (i.e., everything besides your own 1605290001SglebiusNTP server is unrestricted). 1606290001Sglebius</dl> 1607290001Sglebius<div class="node"> 1608290001Sglebius<p><hr> 1609290001Sglebius<a name="Automatic-NTP-Configuration-Options"></a> 1610290001Sglebius<br> 1611290001Sglebius</div> 1612290001Sglebius 1613290001Sglebius<h4 class="subsection">Automatic NTP Configuration Options</h4> 1614290001Sglebius 1615290001Sglebius<h5 class="subsubsection">Manycasting</h5> 1616290001Sglebius 1617290001Sglebius<p>Manycasting is a automatic discovery and configuration paradigm 1618290001Sglebiusnew to NTPv4. 1619290001SglebiusIt is intended as a means for a multicast client 1620290001Sglebiusto troll the nearby network neighborhood to find cooperating 1621290001Sglebiusmanycast servers, validate them using cryptographic means 1622290001Sglebiusand evaluate their time values with respect to other servers 1623290001Sglebiusthat might be lurking in the vicinity. 1624290001SglebiusThe intended result is that each manycast client mobilizes 1625290001Sglebiusclient associations with some number of the "best" 1626290001Sglebiusof the nearby manycast servers, yet automatically reconfigures 1627290001Sglebiusto sustain this number of servers should one or another fail. 1628290001Sglebius 1629290001Sglebius <p>Note that the manycasting paradigm does not coincide 1630290001Sglebiuswith the anycast paradigm described in RFC-1546, 1631290001Sglebiuswhich is designed to find a single server from a clique 1632290001Sglebiusof servers providing the same service. 1633290001SglebiusThe manycast paradigm is designed to find a plurality 1634290001Sglebiusof redundant servers satisfying defined optimality criteria. 1635290001Sglebius 1636290001Sglebius <p>Manycasting can be used with either symmetric key 1637290001Sglebiusor public key cryptography. 1638290001SglebiusThe public key infrastructure (PKI) 1639290001Sglebiusoffers the best protection against compromised keys 1640290001Sglebiusand is generally considered stronger, at least with relatively 1641290001Sglebiuslarge key sizes. 1642290001SglebiusIt is implemented using the Autokey protocol and 1643290001Sglebiusthe OpenSSL cryptographic library available from 1644290001Sglebius<code>http://www.openssl.org/</code>. 1645290001SglebiusThe library can also be used with other NTPv4 modes 1646290001Sglebiusas well and is highly recommended, especially for broadcast modes. 1647290001Sglebius 1648290001Sglebius <p>A persistent manycast client association is configured 1649298770Sdelphijusing the 1650298770Sdelphij<code>manycastclient</code> 1651298770Sdelphijcommand, which is similar to the 1652298770Sdelphij<code>server</code> 1653298770Sdelphijcommand but with a multicast (IPv4 class 1654290001Sglebius<code>D</code> 1655290001Sglebiusor IPv6 prefix 1656290001Sglebius<code>FF</code>) 1657290001Sglebiusgroup address. 1658290001SglebiusThe IANA has designated IPv4 address 224.1.1.1 1659290001Sglebiusand IPv6 address FF05::101 (site local) for NTP. 1660290001SglebiusWhen more servers are needed, it broadcasts manycast 1661290001Sglebiusclient messages to this address at the minimum feasible rate 1662290001Sglebiusand minimum feasible time-to-live (TTL) hops, depending 1663290001Sglebiuson how many servers have already been found. 1664290001SglebiusThere can be as many manycast client associations 1665290001Sglebiusas different group address, each one serving as a template 1666290001Sglebiusfor a future ephemeral unicast client/server association. 1667290001Sglebius 1668290001Sglebius <p>Manycast servers configured with the 1669290001Sglebius<code>manycastserver</code> 1670290001Sglebiuscommand listen on the specified group address for manycast 1671290001Sglebiusclient messages. 1672290001SglebiusNote the distinction between manycast client, 1673290001Sglebiuswhich actively broadcasts messages, and manycast server, 1674290001Sglebiuswhich passively responds to them. 1675290001SglebiusIf a manycast server is 1676290001Sglebiusin scope of the current TTL and is itself synchronized 1677290001Sglebiusto a valid source and operating at a stratum level equal 1678290001Sglebiusto or lower than the manycast client, it replies to the 1679290001Sglebiusmanycast client message with an ordinary unicast server message. 1680290001Sglebius 1681290001Sglebius <p>The manycast client receiving this message mobilizes 1682290001Sglebiusan ephemeral client/server association according to the 1683290001Sglebiusmatching manycast client template, but only if cryptographically 1684290001Sglebiusauthenticated and the server stratum is less than or equal 1685290001Sglebiusto the client stratum. 1686290001SglebiusAuthentication is explicitly required 1687290001Sglebiusand either symmetric key or public key (Autokey) can be used. 1688290001SglebiusThen, the client polls the server at its unicast address 1689290001Sglebiusin burst mode in order to reliably set the host clock 1690290001Sglebiusand validate the source. 1691290001SglebiusThis normally results 1692290001Sglebiusin a volley of eight client/server at 2-s intervals 1693290001Sglebiusduring which both the synchronization and cryptographic 1694290001Sglebiusprotocols run concurrently. 1695290001SglebiusFollowing the volley, 1696290001Sglebiusthe client runs the NTP intersection and clustering 1697290001Sglebiusalgorithms, which act to discard all but the "best" 1698290001Sglebiusassociations according to stratum and synchronization 1699290001Sglebiusdistance. 1700290001SglebiusThe surviving associations then continue 1701290001Sglebiusin ordinary client/server mode. 1702290001Sglebius 1703290001Sglebius <p>The manycast client polling strategy is designed to reduce 1704290001Sglebiusas much as possible the volume of manycast client messages 1705290001Sglebiusand the effects of implosion due to near-simultaneous 1706290001Sglebiusarrival of manycast server messages. 1707290001SglebiusThe strategy is determined by the 1708290001Sglebius<code>manycastclient</code>, 1709290001Sglebius<code>tos</code> 1710290001Sglebiusand 1711290001Sglebius<code>ttl</code> 1712290001Sglebiusconfiguration commands. 1713290001SglebiusThe manycast poll interval is 1714290001Sglebiusnormally eight times the system poll interval, 1715290001Sglebiuswhich starts out at the 1716290001Sglebius<code>minpoll</code> 1717290001Sglebiusvalue specified in the 1718290001Sglebius<code>manycastclient</code>, 1719290001Sglebiuscommand and, under normal circumstances, increments to the 1720290001Sglebius<code>maxpolll</code> 1721290001Sglebiusvalue specified in this command. 1722290001SglebiusInitially, the TTL is 1723298770Sdelphijset at the minimum hops specified by the 1724298770Sdelphij<code>ttl</code> 1725298770Sdelphijcommand. 1726290001SglebiusAt each retransmission the TTL is increased until reaching 1727290001Sglebiusthe maximum hops specified by this command or a sufficient 1728290001Sglebiusnumber client associations have been found. 1729290001SglebiusFurther retransmissions use the same TTL. 1730290001Sglebius 1731290001Sglebius <p>The quality and reliability of the suite of associations 1732290001Sglebiusdiscovered by the manycast client is determined by the NTP 1733290001Sglebiusmitigation algorithms and the 1734290001Sglebius<code>minclock</code> 1735290001Sglebiusand 1736290001Sglebius<code>minsane</code> 1737290001Sglebiusvalues specified in the 1738290001Sglebius<code>tos</code> 1739290001Sglebiusconfiguration command. 1740290001SglebiusAt least 1741290001Sglebius<code>minsane</code> 1742290001Sglebiuscandidate servers must be available and the mitigation 1743290001Sglebiusalgorithms produce at least 1744290001Sglebius<code>minclock</code> 1745290001Sglebiussurvivors in order to synchronize the clock. 1746290001SglebiusByzantine agreement principles require at least four 1747290001Sglebiuscandidates in order to correctly discard a single falseticker. 1748290001SglebiusFor legacy purposes, 1749290001Sglebius<code>minsane</code> 1750290001Sglebiusdefaults to 1 and 1751290001Sglebius<code>minclock</code> 1752290001Sglebiusdefaults to 3. 1753290001SglebiusFor manycast service 1754290001Sglebius<code>minsane</code> 1755290001Sglebiusshould be explicitly set to 4, assuming at least that 1756290001Sglebiusnumber of servers are available. 1757290001Sglebius 1758290001Sglebius <p>If at least 1759290001Sglebius<code>minclock</code> 1760290001Sglebiusservers are found, the manycast poll interval is immediately 1761290001Sglebiusset to eight times 1762290001Sglebius<code>maxpoll</code>. 1763290001SglebiusIf less than 1764290001Sglebius<code>minclock</code> 1765290001Sglebiusservers are found when the TTL has reached the maximum hops, 1766290001Sglebiusthe manycast poll interval is doubled. 1767290001SglebiusFor each transmission 1768290001Sglebiusafter that, the poll interval is doubled again until 1769290001Sglebiusreaching the maximum of eight times 1770290001Sglebius<code>maxpoll</code>. 1771290001SglebiusFurther transmissions use the same poll interval and 1772290001SglebiusTTL values. 1773290001SglebiusNote that while all this is going on, 1774290001Sglebiuseach client/server association found is operating normally 1775290001Sglebiusit the system poll interval. 1776290001Sglebius 1777290001Sglebius <p>Administratively scoped multicast boundaries are normally 1778290001Sglebiusspecified by the network router configuration and, 1779290001Sglebiusin the case of IPv6, the link/site scope prefix. 1780290001SglebiusBy default, the increment for TTL hops is 32 starting 1781290001Sglebiusfrom 31; however, the 1782290001Sglebius<code>ttl</code> 1783290001Sglebiusconfiguration command can be 1784290001Sglebiusused to modify the values to match the scope rules. 1785290001Sglebius 1786290001Sglebius <p>It is often useful to narrow the range of acceptable 1787290001Sglebiusservers which can be found by manycast client associations. 1788290001SglebiusBecause manycast servers respond only when the client 1789290001Sglebiusstratum is equal to or greater than the server stratum, 1790290001Sglebiusprimary (stratum 1) servers fill find only primary servers 1791290001Sglebiusin TTL range, which is probably the most common objective. 1792290001SglebiusHowever, unless configured otherwise, all manycast clients 1793290001Sglebiusin TTL range will eventually find all primary servers 1794290001Sglebiusin TTL range, which is probably not the most common 1795290001Sglebiusobjective in large networks. 1796290001SglebiusThe 1797290001Sglebius<code>tos</code> 1798290001Sglebiuscommand can be used to modify this behavior. 1799290001SglebiusServers with stratum below 1800290001Sglebius<code>floor</code> 1801290001Sglebiusor above 1802290001Sglebius<code>ceiling</code> 1803290001Sglebiusspecified in the 1804290001Sglebius<code>tos</code> 1805290001Sglebiuscommand are strongly discouraged during the selection 1806290001Sglebiusprocess; however, these servers may be temporally 1807290001Sglebiusaccepted if the number of servers within TTL range is 1808290001Sglebiusless than 1809290001Sglebius<code>minclock</code>. 1810290001Sglebius 1811290001Sglebius <p>The above actions occur for each manycast client message, 1812290001Sglebiuswhich repeats at the designated poll interval. 1813290001SglebiusHowever, once the ephemeral client association is mobilized, 1814290001Sglebiussubsequent manycast server replies are discarded, 1815290001Sglebiussince that would result in a duplicate association. 1816290001SglebiusIf during a poll interval the number of client associations 1817290001Sglebiusfalls below 1818290001Sglebius<code>minclock</code>, 1819290001Sglebiusall manycast client prototype associations are reset 1820290001Sglebiusto the initial poll interval and TTL hops and operation 1821290001Sglebiusresumes from the beginning. 1822290001SglebiusIt is important to avoid 1823290001Sglebiusfrequent manycast client messages, since each one requires 1824290001Sglebiusall manycast servers in TTL range to respond. 1825290001SglebiusThe result could well be an implosion, either minor or major, 1826290001Sglebiusdepending on the number of servers in range. 1827290001SglebiusThe recommended value for 1828290001Sglebius<code>maxpoll</code> 1829290001Sglebiusis 12 (4,096 s). 1830290001Sglebius 1831290001Sglebius <p>It is possible and frequently useful to configure a host 1832290001Sglebiusas both manycast client and manycast server. 1833290001SglebiusA number of hosts configured this way and sharing a common 1834290001Sglebiusgroup address will automatically organize themselves 1835290001Sglebiusin an optimum configuration based on stratum and 1836290001Sglebiussynchronization distance. 1837290001SglebiusFor example, consider an NTP 1838290001Sglebiussubnet of two primary servers and a hundred or more 1839290001Sglebiusdependent clients. 1840290001SglebiusWith two exceptions, all servers 1841290001Sglebiusand clients have identical configuration files including both 1842290001Sglebius<code>multicastclient</code> 1843290001Sglebiusand 1844290001Sglebius<code>multicastserver</code> 1845290001Sglebiuscommands using, for instance, multicast group address 1846290001Sglebius239.1.1.1. 1847290001SglebiusThe only exception is that each primary server 1848290001Sglebiusconfiguration file must include commands for the primary 1849290001Sglebiusreference source such as a GPS receiver. 1850290001Sglebius 1851290001Sglebius <p>The remaining configuration files for all secondary 1852290001Sglebiusservers and clients have the same contents, except for the 1853290001Sglebius<code>tos</code> 1854290001Sglebiuscommand, which is specific for each stratum level. 1855290001SglebiusFor stratum 1 and stratum 2 servers, that command is 1856290001Sglebiusnot necessary. 1857290001SglebiusFor stratum 3 and above servers the 1858290001Sglebius<code>floor</code> 1859290001Sglebiusvalue is set to the intended stratum number. 1860290001SglebiusThus, all stratum 3 configuration files are identical, 1861290001Sglebiusall stratum 4 files are identical and so forth. 1862290001Sglebius 1863290001Sglebius <p>Once operations have stabilized in this scenario, 1864290001Sglebiusthe primary servers will find the primary reference source 1865290001Sglebiusand each other, since they both operate at the same 1866290001Sglebiusstratum (1), but not with any secondary server or client, 1867290001Sglebiussince these operate at a higher stratum. 1868290001SglebiusThe secondary 1869290001Sglebiusservers will find the servers at the same stratum level. 1870290001SglebiusIf one of the primary servers loses its GPS receiver, 1871290001Sglebiusit will continue to operate as a client and other clients 1872290001Sglebiuswill time out the corresponding association and 1873290001Sglebiusre-associate accordingly. 1874290001Sglebius 1875290001Sglebius <p>Some administrators prefer to avoid running 1876290001Sglebius<code>ntpd(1ntpdmdoc)</code> 1877290001Sglebiuscontinuously and run either 1878290001Sglebius<code>sntp(1sntpmdoc)</code> 1879290001Sglebiusor 1880290001Sglebius<code>ntpd(1ntpdmdoc)</code> 1881290001Sglebius<code>-q</code> 1882290001Sglebiusas a cron job. 1883290001SglebiusIn either case the servers must be 1884290001Sglebiusconfigured in advance and the program fails if none are 1885290001Sglebiusavailable when the cron job runs. 1886290001SglebiusA really slick 1887290001Sglebiusapplication of manycast is with 1888290001Sglebius<code>ntpd(1ntpdmdoc)</code> 1889290001Sglebius<code>-q</code>. 1890290001SglebiusThe program wakes up, scans the local landscape looking 1891290001Sglebiusfor the usual suspects, selects the best from among 1892290001Sglebiusthe rascals, sets the clock and then departs. 1893290001SglebiusServers do not have to be configured in advance and 1894290001Sglebiusall clients throughout the network can have the same 1895290001Sglebiusconfiguration file. 1896290001Sglebius 1897290001Sglebius<h5 class="subsubsection">Manycast Interactions with Autokey</h5> 1898290001Sglebius 1899290001Sglebius<p>Each time a manycast client sends a client mode packet 1900290001Sglebiusto a multicast group address, all manycast servers 1901290001Sglebiusin scope generate a reply including the host name 1902290001Sglebiusand status word. 1903290001SglebiusThe manycast clients then run 1904290001Sglebiusthe Autokey protocol, which collects and verifies 1905290001Sglebiusall certificates involved. 1906290001SglebiusFollowing the burst interval 1907290001Sglebiusall but three survivors are cast off, 1908290001Sglebiusbut the certificates remain in the local cache. 1909290001SglebiusIt often happens that several complete signing trails 1910290001Sglebiusfrom the client to the primary servers are collected in this way. 1911290001Sglebius 1912290001Sglebius <p>About once an hour or less often if the poll interval 1913290001Sglebiusexceeds this, the client regenerates the Autokey key list. 1914290001SglebiusThis is in general transparent in client/server mode. 1915290001SglebiusHowever, about once per day the server private value 1916290001Sglebiusused to generate cookies is refreshed along with all 1917290001Sglebiusmanycast client associations. 1918290001SglebiusIn this case all 1919290001Sglebiuscryptographic values including certificates is refreshed. 1920290001SglebiusIf a new certificate has been generated since 1921290001Sglebiusthe last refresh epoch, it will automatically revoke 1922290001Sglebiusall prior certificates that happen to be in the 1923290001Sglebiuscertificate cache. 1924290001SglebiusAt the same time, the manycast 1925290001Sglebiusscheme starts all over from the beginning and 1926290001Sglebiusthe expanding ring shrinks to the minimum and increments 1927290001Sglebiusfrom there while collecting all servers in scope. 1928290001Sglebius 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 1945290001Sglebius<h5 class="subsubsection">Manycast Options</h5> 1946290001Sglebius 1947310419Sdelphij <dl> 1948290001Sglebius<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 1949290001Sglebiusalgorithms. 1950290001SglebiusIt can be used to select the quality and 1951290001Sglebiusquantity of peers used to synchronize the system clock 1952290001Sglebiusand is most useful in manycast mode. 1953290001SglebiusThe variables operate 1954290001Sglebiusas follows: 1955310419Sdelphij <dl> 1956290001Sglebius<dt><code>ceiling</code> <kbd>ceiling</kbd><dd>Peers with strata above 1957290001Sglebius<code>ceiling</code> 1958290001Sglebiuswill be discarded if there are at least 1959290001Sglebius<code>minclock</code> 1960290001Sglebiuspeers remaining. 1961290001SglebiusThis value defaults to 15, but can be changed 1962290001Sglebiusto any number from 1 to 15. 1963290001Sglebius<br><dt><code>cohort</code> <code>{0 | 1}</code><dd>This is a binary flag which enables (0) or disables (1) 1964290001Sglebiusmanycast server replies to manycast clients with the same 1965290001Sglebiusstratum level. 1966290001SglebiusThis is useful to reduce implosions where 1967290001Sglebiuslarge numbers of clients with the same stratum level 1968290001Sglebiusare present. 1969290001SglebiusThe default is to enable these replies. 1970290001Sglebius<br><dt><code>floor</code> <kbd>floor</kbd><dd>Peers with strata below 1971290001Sglebius<code>floor</code> 1972290001Sglebiuswill be discarded if there are at least 1973290001Sglebius<code>minclock</code> 1974290001Sglebiuspeers remaining. 1975290001SglebiusThis value defaults to 1, but can be changed 1976290001Sglebiusto any number from 1 to 15. 1977290001Sglebius<br><dt><code>minclock</code> <kbd>minclock</kbd><dd>The clustering algorithm repeatedly casts out outlier 1978290001Sglebiusassociations until no more than 1979290001Sglebius<code>minclock</code> 1980290001Sglebiusassociations remain. 1981290001SglebiusThis value defaults to 3, 1982290001Sglebiusbut can be changed to any number from 1 to the number of 1983290001Sglebiusconfigured sources. 1984290001Sglebius<br><dt><code>minsane</code> <kbd>minsane</kbd><dd>This is the minimum number of candidates available 1985290001Sglebiusto the clock selection algorithm in order to produce 1986290001Sglebiusone or more truechimers for the clustering algorithm. 1987290001SglebiusIf fewer than this number are available, the clock is 1988290001Sglebiusundisciplined and allowed to run free. 1989290001SglebiusThe default is 1 1990290001Sglebiusfor legacy purposes. 1991290001SglebiusHowever, according to principles of 1992290001SglebiusByzantine agreement, 1993290001Sglebius<code>minsane</code> 1994290001Sglebiusshould be at least 4 in order to detect and discard 1995290001Sglebiusa single falseticker. 1996290001Sglebius</dl> 1997310419Sdelphij <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing 1998290001Sglebiusorder, up to 8 values can be specified. 1999290001SglebiusIn manycast mode these values are used in turn 2000290001Sglebiusin an expanding-ring search. 2001290001SglebiusThe default is eight 2002290001Sglebiusmultiples of 32 starting at 31. 2003290001Sglebius</dl> 2004310419Sdelphij <div class="node"> 2005290001Sglebius<p><hr> 2006290001Sglebius<a name="Reference-Clock-Support"></a> 2007290001Sglebius<br> 2008290001Sglebius</div> 2009290001Sglebius 2010290001Sglebius<h4 class="subsection">Reference Clock Support</h4> 2011290001Sglebius 2012310419Sdelphij <p>The NTP Version 4 daemon supports some three dozen different radio, 2013290001Sglebiussatellite and modem reference clocks plus a special pseudo-clock 2014290001Sglebiusused for backup or when no other clock source is available. 2015290001SglebiusDetailed descriptions of individual device drivers and options can 2016290001Sglebiusbe found in the 2017290001Sglebius"Reference Clock Drivers" 2018290001Sglebiuspage 2019290001Sglebius(available as part of the HTML documentation 2020290001Sglebiusprovided in 2021290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 2022290001SglebiusAdditional information can be found in the pages linked 2023290001Sglebiusthere, including the 2024290001Sglebius"Debugging Hints for Reference Clock Drivers" 2025290001Sglebiusand 2026290001Sglebius"How To Write a Reference Clock Driver" 2027290001Sglebiuspages 2028290001Sglebius(available as part of the HTML documentation 2029290001Sglebiusprovided in 2030290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 2031290001SglebiusIn addition, support for a PPS 2032290001Sglebiussignal is available as described in the 2033290001Sglebius"Pulse-per-second (PPS) Signal Interfacing" 2034290001Sglebiuspage 2035290001Sglebius(available as part of the HTML documentation 2036290001Sglebiusprovided in 2037290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 2038290001SglebiusMany 2039290001Sglebiusdrivers support special line discipline/streams modules which can 2040290001Sglebiussignificantly improve the accuracy using the driver. 2041290001SglebiusThese are 2042290001Sglebiusdescribed in the 2043290001Sglebius"Line Disciplines and Streams Drivers" 2044290001Sglebiuspage 2045290001Sglebius(available as part of the HTML documentation 2046290001Sglebiusprovided in 2047290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 2048290001Sglebius 2049310419Sdelphij <p>A reference clock will generally (though not always) be a radio 2050290001Sglebiustimecode receiver which is synchronized to a source of standard 2051290001Sglebiustime such as the services offered by the NRC in Canada and NIST and 2052290001SglebiusUSNO in the US. 2053290001SglebiusThe interface between the computer and the timecode 2054290001Sglebiusreceiver is device dependent, but is usually a serial port. 2055290001SglebiusA 2056290001Sglebiusdevice driver specific to each reference clock must be selected and 2057290001Sglebiuscompiled in the distribution; however, most common radio, satellite 2058290001Sglebiusand modem clocks are included by default. 2059290001SglebiusNote that an attempt to 2060290001Sglebiusconfigure a reference clock when the driver has not been compiled 2061290001Sglebiusor the hardware port has not been appropriately configured results 2062290001Sglebiusin a scalding remark to the system log file, but is otherwise non 2063290001Sglebiushazardous. 2064290001Sglebius 2065310419Sdelphij <p>For the purposes of configuration, 2066290001Sglebius<code>ntpd(1ntpdmdoc)</code> 2067290001Sglebiustreats 2068290001Sglebiusreference clocks in a manner analogous to normal NTP peers as much 2069290001Sglebiusas possible. 2070290001SglebiusReference clocks are identified by a syntactically 2071290001Sglebiuscorrect but invalid IP address, in order to distinguish them from 2072290001Sglebiusnormal NTP peers. 2073290001SglebiusReference clock addresses are of the form 2074290001Sglebius<code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd>, 2075290001Sglebiuswhere 2076290001Sglebius<kbd>t</kbd> 2077290001Sglebiusis an integer 2078290001Sglebiusdenoting the clock type and 2079290001Sglebius<kbd>u</kbd> 2080290001Sglebiusindicates the unit 2081290001Sglebiusnumber in the range 0-3. 2082290001SglebiusWhile it may seem overkill, it is in fact 2083290001Sglebiussometimes useful to configure multiple reference clocks of the same 2084290001Sglebiustype, in which case the unit numbers must be unique. 2085290001Sglebius 2086310419Sdelphij <p>The 2087290001Sglebius<code>server</code> 2088290001Sglebiuscommand is used to configure a reference 2089290001Sglebiusclock, where the 2090290001Sglebius<kbd>address</kbd> 2091290001Sglebiusargument in that command 2092290001Sglebiusis the clock address. 2093290001SglebiusThe 2094290001Sglebius<code>key</code>, 2095290001Sglebius<code>version</code> 2096290001Sglebiusand 2097290001Sglebius<code>ttl</code> 2098290001Sglebiusoptions are not used for reference clock support. 2099290001SglebiusThe 2100290001Sglebius<code>mode</code> 2101290001Sglebiusoption is added for reference clock support, as 2102290001Sglebiusdescribed below. 2103290001SglebiusThe 2104290001Sglebius<code>prefer</code> 2105290001Sglebiusoption can be useful to 2106290001Sglebiuspersuade the server to cherish a reference clock with somewhat more 2107290001Sglebiusenthusiasm than other reference clocks or peers. 2108290001SglebiusFurther 2109290001Sglebiusinformation on this option can be found in the 2110290001Sglebius"Mitigation Rules and the prefer Keyword" 2111290001Sglebius(available as part of the HTML documentation 2112290001Sglebiusprovided in 2113290001Sglebius<span class="file">/usr/share/doc/ntp</span>) 2114290001Sglebiuspage. 2115290001SglebiusThe 2116290001Sglebius<code>minpoll</code> 2117290001Sglebiusand 2118290001Sglebius<code>maxpoll</code> 2119290001Sglebiusoptions have 2120290001Sglebiusmeaning only for selected clock drivers. 2121290001SglebiusSee the individual clock 2122290001Sglebiusdriver document pages for additional information. 2123290001Sglebius 2124310419Sdelphij <p>The 2125290001Sglebius<code>fudge</code> 2126290001Sglebiuscommand is used to provide additional 2127290001Sglebiusinformation for individual clock drivers and normally follows 2128290001Sglebiusimmediately after the 2129290001Sglebius<code>server</code> 2130290001Sglebiuscommand. 2131290001SglebiusThe 2132290001Sglebius<kbd>address</kbd> 2133290001Sglebiusargument specifies the clock address. 2134290001SglebiusThe 2135290001Sglebius<code>refid</code> 2136290001Sglebiusand 2137290001Sglebius<code>stratum</code> 2138290001Sglebiusoptions can be used to 2139290001Sglebiusoverride the defaults for the device. 2140290001SglebiusThere are two optional 2141290001Sglebiusdevice-dependent time offsets and four flags that can be included 2142290001Sglebiusin the 2143290001Sglebius<code>fudge</code> 2144290001Sglebiuscommand as well. 2145290001Sglebius 2146310419Sdelphij <p>The stratum number of a reference clock is by default zero. 2147290001SglebiusSince the 2148290001Sglebius<code>ntpd(1ntpdmdoc)</code> 2149290001Sglebiusdaemon adds one to the stratum of each 2150290001Sglebiuspeer, a primary server ordinarily displays an external stratum of 2151290001Sglebiusone. 2152290001SglebiusIn order to provide engineered backups, it is often useful to 2153290001Sglebiusspecify the reference clock stratum as greater than zero. 2154290001SglebiusThe 2155290001Sglebius<code>stratum</code> 2156290001Sglebiusoption is used for this purpose. 2157290001SglebiusAlso, in cases 2158290001Sglebiusinvolving both a reference clock and a pulse-per-second (PPS) 2159290001Sglebiusdiscipline signal, it is useful to specify the reference clock 2160290001Sglebiusidentifier as other than the default, depending on the driver. 2161290001SglebiusThe 2162290001Sglebius<code>refid</code> 2163290001Sglebiusoption is used for this purpose. 2164290001SglebiusExcept where noted, 2165290001Sglebiusthese options apply to all clock drivers. 2166290001Sglebius 2167290001Sglebius<h5 class="subsubsection">Reference Clock Commands</h5> 2168290001Sglebius 2169310419Sdelphij <dl> 2170290001Sglebius<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 2171290001Sglebiusspecial ways. 2172290001SglebiusThe options are interpreted as follows: 2173310419Sdelphij <dl> 2174290001Sglebius<dt><code>prefer</code><dd>Marks the reference clock as preferred. 2175290001SglebiusAll other things being 2176290001Sglebiusequal, this host will be chosen for synchronization among a set of 2177290001Sglebiuscorrectly operating hosts. 2178290001SglebiusSee the 2179290001Sglebius"Mitigation Rules and the prefer Keyword" 2180290001Sglebiuspage 2181290001Sglebius(available as part of the HTML documentation 2182290001Sglebiusprovided in 2183290001Sglebius<span class="file">/usr/share/doc/ntp</span>) 2184290001Sglebiusfor further information. 2185290001Sglebius<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 2186290001Sglebiusdevice-specific fashion. 2187290001SglebiusFor instance, it selects a dialing 2188290001Sglebiusprotocol in the ACTS driver and a device subtype in the 2189290001Sglebiusparse 2190290001Sglebiusdrivers. 2191290001Sglebius<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 2192290001Sglebiusfor reference clock messages, as a power of 2 in seconds 2193290001SglebiusFor 2194290001Sglebiusmost directly connected reference clocks, both 2195290001Sglebius<code>minpoll</code> 2196290001Sglebiusand 2197290001Sglebius<code>maxpoll</code> 2198290001Sglebiusdefault to 6 (64 s). 2199290001SglebiusFor modem reference clocks, 2200290001Sglebius<code>minpoll</code> 2201290001Sglebiusdefaults to 10 (17.1 m) and 2202290001Sglebius<code>maxpoll</code> 2203290001Sglebiusdefaults to 14 (4.5 h). 2204290001SglebiusThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 2205290001Sglebius</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 2207290001Sglebiusspecial ways. 2208290001SglebiusIt must immediately follow the 2209290001Sglebius<code>server</code> 2210290001Sglebiuscommand which configures the driver. 2211290001SglebiusNote that the same capability 2212290001Sglebiusis possible at run time using the 2213290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 2214290001Sglebiusprogram. 2215290001SglebiusThe options are interpreted as 2216290001Sglebiusfollows: 2217310419Sdelphij <dl> 2218290001Sglebius<dt><code>time1</code> <kbd>sec</kbd><dd>Specifies a constant to be added to the time offset produced by 2219290001Sglebiusthe driver, a fixed-point decimal number in seconds. 2220290001SglebiusThis is used 2221290001Sglebiusas a calibration constant to adjust the nominal time offset of a 2222290001Sglebiusparticular clock to agree with an external standard, such as a 2223290001Sglebiusprecision PPS signal. 2224290001SglebiusIt also provides a way to correct a 2225290001Sglebiussystematic error or bias due to serial port or operating system 2226290001Sglebiuslatencies, different cable lengths or receiver internal delay. 2227290001SglebiusThe 2228290001Sglebiusspecified offset is in addition to the propagation delay provided 2229290001Sglebiusby other means, such as internal DIPswitches. 2230290001SglebiusWhere a calibration 2231290001Sglebiusfor an individual system and driver is available, an approximate 2232290001Sglebiuscorrection is noted in the driver documentation pages. 2233290001SglebiusNote: in order to facilitate calibration when more than one 2234290001Sglebiusradio clock or PPS signal is supported, a special calibration 2235290001Sglebiusfeature is available. 2236290001SglebiusIt takes the form of an argument to the 2237290001Sglebius<code>enable</code> 2238290001Sglebiuscommand described in 2239290001Sglebius<a href="#Miscellaneous-Options">Miscellaneous Options</a> 2240290001Sglebiuspage and operates as described in the 2241290001Sglebius"Reference Clock Drivers" 2242290001Sglebiuspage 2243290001Sglebius(available as part of the HTML documentation 2244290001Sglebiusprovided in 2245290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 2246290001Sglebius<br><dt><code>time2</code> <kbd>secs</kbd><dd>Specifies a fixed-point decimal number in seconds, which is 2247290001Sglebiusinterpreted in a driver-dependent way. 2248290001SglebiusSee the descriptions of 2249290001Sglebiusspecific drivers in the 2250290001Sglebius"Reference Clock Drivers" 2251290001Sglebiuspage 2252290001Sglebius(available as part of the HTML documentation 2253290001Sglebiusprovided in 2254290001Sglebius<span class="file">/usr/share/doc/ntp</span>). 2255290001Sglebius<br><dt><code>stratum</code> <kbd>int</kbd><dd>Specifies the stratum number assigned to the driver, an integer 2256290001Sglebiusbetween 0 and 15. 2257290001SglebiusThis number overrides the default stratum number 2258290001Sglebiusordinarily assigned by the driver itself, usually zero. 2259290001Sglebius<br><dt><code>refid</code> <kbd>string</kbd><dd>Specifies an ASCII string of from one to four characters which 2260290001Sglebiusdefines the reference identifier used by the driver. 2261290001SglebiusThis string 2262290001Sglebiusoverrides the default identifier ordinarily assigned by the driver 2263290001Sglebiusitself. 2264290001Sglebius<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 2265290001Sglebiusdevice-specific fashion. 2266290001SglebiusFor instance, it selects a dialing 2267290001Sglebiusprotocol in the ACTS driver and a device subtype in the 2268290001Sglebiusparse 2269290001Sglebiusdrivers. 2270290001Sglebius<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. 2271290001SglebiusThe 2272290001Sglebiusinterpretation of these values, and whether they are used at all, 2273290001Sglebiusis a function of the particular clock driver. 2274290001SglebiusHowever, by 2275290001Sglebiusconvention 2276290001Sglebius<code>flag4</code> 2277290001Sglebiusis used to enable recording monitoring 2278290001Sglebiusdata to the 2279290001Sglebius<code>clockstats</code> 2280290001Sglebiusfile configured with the 2281290001Sglebius<code>filegen</code> 2282290001Sglebiuscommand. 2283290001SglebiusFurther information on the 2284290001Sglebius<code>filegen</code> 2285290001Sglebiuscommand can be found in 2286290001Sglebius<a href="#Monitoring-Options">Monitoring Options</a>. 2287290001Sglebius</dl> 2288310419Sdelphij </dl> 2289310419Sdelphij <div class="node"> 2290290001Sglebius<p><hr> 2291290001Sglebius<a name="Miscellaneous-Options"></a> 2292290001Sglebius<br> 2293290001Sglebius</div> 2294290001Sglebius 2295290001Sglebius<h4 class="subsection">Miscellaneous Options</h4> 2296290001Sglebius 2297310419Sdelphij <dl> 2298290001Sglebius<dt><code>broadcastdelay</code> <kbd>seconds</kbd><dd>The broadcast and multicast modes require a special calibration 2299290001Sglebiusto determine the network delay between the local and remote 2300290001Sglebiusservers. 2301290001SglebiusOrdinarily, this is done automatically by the initial 2302290001Sglebiusprotocol exchanges between the client and server. 2303290001SglebiusIn some cases, 2304290001Sglebiusthe calibration procedure may fail due to network or server access 2305290001Sglebiuscontrols, for example. 2306290001SglebiusThis command specifies the default delay to 2307290001Sglebiusbe used under these circumstances. 2308290001SglebiusTypically (for Ethernet), a 2309290001Sglebiusnumber between 0.003 and 0.007 seconds is appropriate. 2310290001SglebiusThe default 2311290001Sglebiuswhen this command is not used is 0.004 seconds. 2312290001Sglebius<br><dt><code>calldelay</code> <kbd>delay</kbd><dd>This option controls the delay in seconds between the first and second 2313290001Sglebiuspackets sent in burst or iburst mode to allow additional time for a modem 2314290001Sglebiusor ISDN call to complete. 2315290001Sglebius<br><dt><code>driftfile</code> <kbd>driftfile</kbd><dd>This command specifies the complete path and name of the file used to 2316290001Sglebiusrecord the frequency of the local clock oscillator. 2317290001SglebiusThis is the same 2318290001Sglebiusoperation as the 2319290001Sglebius<code>-f</code> 2320290001Sglebiuscommand line option. 2321290001SglebiusIf the file exists, it is read at 2322290001Sglebiusstartup in order to set the initial frequency and then updated once per 2323290001Sglebiushour with the current frequency computed by the daemon. 2324290001SglebiusIf the file name is 2325290001Sglebiusspecified, but the file itself does not exist, the starts with an initial 2326290001Sglebiusfrequency of zero and creates the file when writing it for the first time. 2327290001SglebiusIf this command is not given, the daemon will always start with an initial 2328290001Sglebiusfrequency of zero. 2329290001Sglebius 2330310419Sdelphij <p>The file format consists of a single line containing a single 2331290001Sglebiusfloating point number, which records the frequency offset measured 2332290001Sglebiusin parts-per-million (PPM). 2333290001SglebiusThe file is updated by first writing 2334290001Sglebiusthe current drift value into a temporary file and then renaming 2335290001Sglebiusthis file to replace the old version. 2336290001SglebiusThis implies that 2337290001Sglebius<code>ntpd(1ntpdmdoc)</code> 2338290001Sglebiusmust have write permission for the directory the 2339290001Sglebiusdrift file is located in, and that file system links, symbolic or 2340290001Sglebiusotherwise, should be avoided. 2341290001Sglebius<br><dt><code>dscp</code> <kbd>value</kbd><dd>This option specifies the Differentiated Services Control Point (DSCP) value, 2342301301Sdelphija 6-bit code. 2343301301SdelphijThe default value is 46, signifying Expedited Forwarding. 2344301301Sdelphij<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. 2345290001SglebiusFlags not mentioned are unaffected. 2346290001SglebiusNote that all of these flags 2347290001Sglebiuscan be controlled remotely using the 2348290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 2349290001Sglebiusutility program. 2350310419Sdelphij <dl> 2351290001Sglebius<dt><code>auth</code><dd>Enables the server to synchronize with unconfigured peers only if the 2352290001Sglebiuspeer has been correctly authenticated using either public key or 2353290001Sglebiusprivate key cryptography. 2354290001SglebiusThe default for this flag is 2355290001Sglebius<code>enable</code>. 2356290001Sglebius<br><dt><code>bclient</code><dd>Enables the server to listen for a message from a broadcast or 2357290001Sglebiusmulticast server, as in the 2358290001Sglebius<code>multicastclient</code> 2359290001Sglebiuscommand with default 2360290001Sglebiusaddress. 2361290001SglebiusThe default for this flag is 2362290001Sglebius<code>disable</code>. 2363290001Sglebius<br><dt><code>calibrate</code><dd>Enables the calibrate feature for reference clocks. 2364290001SglebiusThe default for 2365290001Sglebiusthis flag is 2366290001Sglebius<code>disable</code>. 2367290001Sglebius<br><dt><code>kernel</code><dd>Enables the kernel time discipline, if available. 2368290001SglebiusThe default for this 2369290001Sglebiusflag is 2370290001Sglebius<code>enable</code> 2371290001Sglebiusif support is available, otherwise 2372290001Sglebius<code>disable</code>. 2373290001Sglebius<br><dt><code>mode7</code><dd>Enables processing of NTP mode 7 implementation-specific requests 2374290001Sglebiuswhich are used by the deprecated 2375290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 2376290001Sglebiusprogram. 2377290001SglebiusThe default for this flag is disable. 2378290001SglebiusThis flag is excluded from runtime configuration using 2379290001Sglebius<code>ntpq(1ntpqmdoc)</code>. 2380290001SglebiusThe 2381290001Sglebius<code>ntpq(1ntpqmdoc)</code> 2382290001Sglebiusprogram provides the same capabilities as 2383290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 2384290001Sglebiususing standard mode 6 requests. 2385290001Sglebius<br><dt><code>monitor</code><dd>Enables the monitoring facility. 2386290001SglebiusSee the 2387290001Sglebius<code>ntpdc(1ntpdcmdoc)</code> 2388290001Sglebiusprogram 2389290001Sglebiusand the 2390290001Sglebius<code>monlist</code> 2391290001Sglebiuscommand or further information. 2392290001SglebiusThe 2393290001Sglebiusdefault for this flag is 2394290001Sglebius<code>enable</code>. 2395290001Sglebius<br><dt><code>ntp</code><dd>Enables time and frequency discipline. 2396290001SglebiusIn effect, this switch opens and 2397290001Sglebiuscloses the feedback loop, which is useful for testing. 2398290001SglebiusThe default for 2399290001Sglebiusthis flag is 2400290001Sglebius<code>enable</code>. 2401301301Sdelphij<br><dt><code>peer_clear_digest_early</code><dd>By default, if 2402301301Sdelphij<code>ntpd(1ntpdmdoc)</code> 2403301301Sdelphijis using autokey and it 2404301301Sdelphijreceives a crypto-NAK packet that 2405301301Sdelphijpasses the duplicate packet and origin timestamp checks 2406301301Sdelphijthe peer variables are immediately cleared. 2407301301SdelphijWhile this is generally a feature 2408301301Sdelphijas it allows for quick recovery if a server key has changed, 2409301301Sdelphija properly forged and appropriately delivered crypto-NAK packet 2410301301Sdelphijcan be used in a DoS attack. 2411301301SdelphijIf you have active noticable problems with this type of DoS attack 2412301301Sdelphijthen you should consider 2413301301Sdelphijdisabling this option. 2414301301SdelphijYou can check your 2415301301Sdelphij<code>peerstats</code> 2416301301Sdelphijfile for evidence of any of these attacks. 2417301301SdelphijThe 2418301301Sdelphijdefault for this flag is 2419301301Sdelphij<code>enable</code>. 2420290001Sglebius<br><dt><code>stats</code><dd>Enables the statistics facility. 2421290001SglebiusSee the 2422290001Sglebius<a href="#Monitoring-Options">Monitoring Options</a> 2423290001Sglebiussection for further information. 2424290001SglebiusThe default for this flag is 2425290001Sglebius<code>disable</code>. 2426294905Sdelphij<br><dt><code>unpeer_crypto_early</code><dd>By default, if 2427294905Sdelphij<code>ntpd(1ntpdmdoc)</code> 2428294905Sdelphijreceives an autokey packet that fails TEST9, 2429294905Sdelphija crypto failure, 2430294905Sdelphijthe association is immediately cleared. 2431294905SdelphijThis is almost certainly a feature, 2432294905Sdelphijbut if, in spite of the current recommendation of not using autokey, 2433294905Sdelphijyou are 2434294905Sdelphij.B still 2435294905Sdelphijusing autokey 2436294905Sdelphij.B and 2437294905Sdelphijyou are seeing this sort of DoS attack 2438294905Sdelphijdisabling this flag will delay 2439294905Sdelphijtearing down the association until the reachability counter 2440294905Sdelphijbecomes zero. 2441294905SdelphijYou can check your 2442294905Sdelphij<code>peerstats</code> 2443294905Sdelphijfile for evidence of any of these attacks. 2444294905SdelphijThe 2445294905Sdelphijdefault for this flag is 2446294905Sdelphij<code>enable</code>. 2447294905Sdelphij<br><dt><code>unpeer_crypto_nak_early</code><dd>By default, if 2448294905Sdelphij<code>ntpd(1ntpdmdoc)</code> 2449294905Sdelphijreceives a crypto-NAK packet that 2450294905Sdelphijpasses the duplicate packet and origin timestamp checks 2451294905Sdelphijthe association is immediately cleared. 2452294905SdelphijWhile this is generally a feature 2453294905Sdelphijas it allows for quick recovery if a server key has changed, 2454294905Sdelphija properly forged and appropriately delivered crypto-NAK packet 2455294905Sdelphijcan be used in a DoS attack. 2456294905SdelphijIf you have active noticable problems with this type of DoS attack 2457294905Sdelphijthen you should consider 2458294905Sdelphijdisabling this option. 2459294905SdelphijYou can check your 2460294905Sdelphij<code>peerstats</code> 2461294905Sdelphijfile for evidence of any of these attacks. 2462294905SdelphijThe 2463294905Sdelphijdefault for this flag is 2464294905Sdelphij<code>enable</code>. 2465294905Sdelphij<br><dt><code>unpeer_digest_early</code><dd>By default, if 2466294905Sdelphij<code>ntpd(1ntpdmdoc)</code> 2467294905Sdelphijreceives what should be an authenticated packet 2468294905Sdelphijthat passes other packet sanity checks but 2469294905Sdelphijcontains an invalid digest 2470294905Sdelphijthe association is immediately cleared. 2471294905SdelphijWhile this is generally a feature 2472294905Sdelphijas it allows for quick recovery, 2473294905Sdelphijif this type of packet is carefully forged and sent 2474294905Sdelphijduring an appropriate window it can be used for a DoS attack. 2475294905SdelphijIf you have active noticable problems with this type of DoS attack 2476294905Sdelphijthen you should consider 2477294905Sdelphijdisabling this option. 2478294905SdelphijYou can check your 2479294905Sdelphij<code>peerstats</code> 2480294905Sdelphijfile for evidence of any of these attacks. 2481294905SdelphijThe 2482294905Sdelphijdefault for this flag is 2483294905Sdelphij<code>enable</code>. 2484290001Sglebius</dl> 2485310419Sdelphij <br><dt><code>includefile</code> <kbd>includefile</kbd><dd>This command allows additional configuration commands 2486290001Sglebiusto be included from a separate file. 2487290001SglebiusInclude files may 2488290001Sglebiusbe nested to a depth of five; upon reaching the end of any 2489290001Sglebiusinclude file, command processing resumes in the previous 2490290001Sglebiusconfiguration file. 2491290001SglebiusThis option is useful for sites that run 2492290001Sglebius<code>ntpd(1ntpdmdoc)</code> 2493290001Sglebiuson multiple hosts, with (mostly) common options (e.g., a 2494290001Sglebiusrestriction list). 2495290001Sglebius<br><dt><code>leapsmearinterval</code> <kbd>seconds</kbd><dd>This EXPERIMENTAL option is only available if 2496290001Sglebius<code>ntpd(1ntpdmdoc)</code> 2497290001Sglebiuswas built with the 2498290001Sglebius<code>--enable-leap-smear</code> 2499290001Sglebiusoption to the 2500290001Sglebius<code>configure</code> 2501290001Sglebiusscript. 2502290001SglebiusIt specifies the interval over which a leap second correction will be applied. 2503290001SglebiusRecommended values for this option are between 2504290001Sglebius7200 (2 hours) and 86400 (24 hours). 2505290001Sglebius.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2506290001SglebiusSee http://bugs.ntp.org/2855 for more information. 2507290001Sglebius<br><dt><code>logconfig</code> <kbd>configkeyword</kbd><dd>This command controls the amount and type of output written to 2508290001Sglebiusthe system 2509290001Sglebius<code>syslog(3)</code> 2510290001Sglebiusfacility or the alternate 2511290001Sglebius<code>logfile</code> 2512290001Sglebiuslog file. 2513290001SglebiusBy default, all output is turned on. 2514290001SglebiusAll 2515290001Sglebius<kbd>configkeyword</kbd> 2516290001Sglebiuskeywords can be prefixed with 2517290001Sglebius=, 2518290001Sglebius+ 2519290001Sglebiusand 2520290001Sglebius-, 2521290001Sglebiuswhere 2522290001Sglebius= 2523290001Sglebiussets the 2524290001Sglebius<code>syslog(3)</code> 2525290001Sglebiuspriority mask, 2526290001Sglebius+ 2527290001Sglebiusadds and 2528290001Sglebius- 2529290001Sglebiusremoves 2530290001Sglebiusmessages. 2531290001Sglebius<code>syslog(3)</code> 2532290001Sglebiusmessages can be controlled in four 2533290001Sglebiusclasses 2534290001Sglebius(<code>clock</code>, <code>peer</code>, <code>sys</code> and <code>sync</code>). 2535290001SglebiusWithin these classes four types of messages can be 2536290001Sglebiuscontrolled: informational messages 2537290001Sglebius(<code>info</code>), 2538290001Sglebiusevent messages 2539290001Sglebius(<code>events</code>), 2540290001Sglebiusstatistics messages 2541290001Sglebius(<code>statistics</code>) 2542290001Sglebiusand 2543290001Sglebiusstatus messages 2544290001Sglebius(<code>status</code>). 2545290001Sglebius 2546310419Sdelphij <p>Configuration keywords are formed by concatenating the message class with 2547290001Sglebiusthe event class. 2548290001SglebiusThe 2549290001Sglebius<code>all</code> 2550290001Sglebiusprefix can be used instead of a message class. 2551290001SglebiusA 2552290001Sglebiusmessage class may also be followed by the 2553290001Sglebius<code>all</code> 2554290001Sglebiuskeyword to enable/disable all 2555301301Sdelphijmessages of the respective message class. 2556301301SdelphijThus, a minimal log configuration 2557290001Sglebiuscould look like this: 2558310419Sdelphij<pre class="verbatim"> 2559310419Sdelphij logconfig =syncstatus +sysevents 2560310419Sdelphij </pre> 2561290001Sglebius 2562310419Sdelphij <p>This would just list the synchronizations state of 2563290001Sglebius<code>ntpd(1ntpdmdoc)</code> 2564290001Sglebiusand the major system events. 2565290001SglebiusFor a simple reference server, the 2566290001Sglebiusfollowing minimum message configuration could be useful: 2567310419Sdelphij<pre class="verbatim"> 2568310419Sdelphij logconfig =syncall +clockall 2569310419Sdelphij </pre> 2570290001Sglebius 2571310419Sdelphij <p>This configuration will list all clock information and 2572290001Sglebiussynchronization information. 2573290001SglebiusAll other events and messages about 2574290001Sglebiuspeers, system events and so on is suppressed. 2575290001Sglebius<br><dt><code>logfile</code> <kbd>logfile</kbd><dd>This command specifies the location of an alternate log file to 2576290001Sglebiusbe used instead of the default system 2577290001Sglebius<code>syslog(3)</code> 2578290001Sglebiusfacility. 2579298770SdelphijThis is the same operation as the 2580298770Sdelphij<code>-l</code> 2581298770Sdelphijcommand line option. 2582290001Sglebius<br><dt><code>setvar</code> <kbd>variable</kbd> <code>[default]</code><dd>This command adds an additional system variable. 2583290001SglebiusThese 2584290001Sglebiusvariables can be used to distribute additional information such as 2585290001Sglebiusthe access policy. 2586290001SglebiusIf the variable of the form 2587290001Sglebius<code>name</code><code>=</code><kbd>value</kbd> 2588290001Sglebiusis followed by the 2589290001Sglebius<code>default</code> 2590290001Sglebiuskeyword, the 2591290001Sglebiusvariable will be listed as part of the default system variables 2592290001Sglebius(<code>rv</code> command)). 2593290001SglebiusThese additional variables serve 2594290001Sglebiusinformational purposes only. 2595290001SglebiusThey are not related to the protocol 2596290001Sglebiusother that they can be listed. 2597290001SglebiusThe known protocol variables will 2598290001Sglebiusalways override any variables defined via the 2599290001Sglebius<code>setvar</code> 2600290001Sglebiusmechanism. 2601290001SglebiusThere are three special variables that contain the names 2602290001Sglebiusof all variable of the same group. 2603290001SglebiusThe 2604290001Sglebius<code>sys_var_list</code> 2605290001Sglebiusholds 2606290001Sglebiusthe names of all system variables. 2607290001SglebiusThe 2608290001Sglebius<code>peer_var_list</code> 2609290001Sglebiusholds 2610290001Sglebiusthe names of all peer variables and the 2611290001Sglebius<code>clock_var_list</code> 2612290001Sglebiusholds the names of the reference clock variables. 2613290001Sglebius<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 2614290001Sglebiusvery exceptional circumstances. 2615290001SglebiusIt should occur in the 2616290001Sglebiusconfiguration file before any other configuration options. 2617290001SglebiusThe 2618290001Sglebiusdefault values of these variables have been carefully optimized for 2619290001Sglebiusa wide range of network speeds and reliability expectations. 2620290001SglebiusIn 2621290001Sglebiusgeneral, they interact in intricate ways that are hard to predict 2622290001Sglebiusand some combinations can result in some very nasty behavior. 2623290001SglebiusVery 2624290001Sglebiusrarely is it necessary to change the default values; but, some 2625290001Sglebiusfolks cannot resist twisting the knobs anyway and this command is 2626290001Sglebiusfor them. 2627290001SglebiusEmphasis added: twisters are on their own and can expect 2628290001Sglebiusno help from the support group. 2629290001Sglebius 2630310419Sdelphij <p>The variables operate as follows: 2631310419Sdelphij <dl> 2632290001Sglebius<dt><code>allan</code> <kbd>allan</kbd><dd>The argument becomes the new value for the minimum Allan 2633290001Sglebiusintercept, which is a parameter of the PLL/FLL clock discipline 2634290001Sglebiusalgorithm. 2635290001SglebiusThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 2636290001Sglebiuslimit. 2637290001Sglebius<br><dt><code>dispersion</code> <kbd>dispersion</kbd><dd>The argument becomes the new value for the dispersion increase rate, 2638290001Sglebiusnormally .000015 s/s. 2639290001Sglebius<br><dt><code>freq</code> <kbd>freq</kbd><dd>The argument becomes the initial value of the frequency offset in 2640290001Sglebiusparts-per-million. 2641290001SglebiusThis overrides the value in the frequency file, if 2642290001Sglebiuspresent, and avoids the initial training state if it is not. 2643290001Sglebius<br><dt><code>huffpuff</code> <kbd>huffpuff</kbd><dd>The argument becomes the new value for the experimental 2644290001Sglebiushuff-n'-puff filter span, which determines the most recent interval 2645290001Sglebiusthe algorithm will search for a minimum delay. 2646290001SglebiusThe lower limit is 2647290001Sglebius900 s (15 m), but a more reasonable value is 7200 (2 hours). 2648290001SglebiusThere 2649290001Sglebiusis no default, since the filter is not enabled unless this command 2650290001Sglebiusis given. 2651290001Sglebius<br><dt><code>panic</code> <kbd>panic</kbd><dd>The argument is the panic threshold, normally 1000 s. 2652290001SglebiusIf set to zero, 2653290001Sglebiusthe panic sanity check is disabled and a clock offset of any value will 2654290001Sglebiusbe accepted. 2655290001Sglebius<br><dt><code>step</code> <kbd>step</kbd><dd>The argument is the step threshold, which by default is 0.128 s. 2656290001SglebiusIt can 2657290001Sglebiusbe set to any positive number in seconds. 2658290001SglebiusIf set to zero, step 2659290001Sglebiusadjustments will never occur. 2660290001SglebiusNote: The kernel time discipline is 2661290001Sglebiusdisabled if the step threshold is set to zero or greater than the 2662290001Sglebiusdefault. 2663290001Sglebius<br><dt><code>stepback</code> <kbd>stepback</kbd><dd>The argument is the step threshold for the backward direction, 2664290001Sglebiuswhich by default is 0.128 s. 2665290001SglebiusIt can 2666290001Sglebiusbe set to any positive number in seconds. 2667290001SglebiusIf both the forward and backward step thresholds are set to zero, step 2668290001Sglebiusadjustments will never occur. 2669290001SglebiusNote: The kernel time discipline is 2670290001Sglebiusdisabled if 2671290001Sglebiuseach direction of step threshold are either 2672290001Sglebiusset to zero or greater than .5 second. 2673290001Sglebius<br><dt><code>stepfwd</code> <kbd>stepfwd</kbd><dd>As for stepback, but for the forward direction. 2674290001Sglebius<br><dt><code>stepout</code> <kbd>stepout</kbd><dd>The argument is the stepout timeout, which by default is 900 s. 2675290001SglebiusIt can 2676290001Sglebiusbe set to any positive number in seconds. 2677290001SglebiusIf set to zero, the stepout 2678290001Sglebiuspulses will not be suppressed. 2679290001Sglebius</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> 2682290001Sglebius<dt><code>memlock</code> <kbd>Nmegabytes</kbd><dd>Specify the number of megabytes of memory that should be 2683290001Sglebiusallocated and locked. 2684290001SglebiusProbably only available under Linux, this option may be useful 2685290001Sglebiuswhen dropping root (the 2686290001Sglebius<code>-i</code> 2687290001Sglebiusoption). 2688290001SglebiusThe default is 32 megabytes on non-Linux machines, and -1 under Linux. 2689290001Sglebius-1 means "do not lock the process into memory". 2690290001Sglebius0 means "lock whatever memory the process wants into memory". 2691290001Sglebius<br><dt><code>stacksize</code> <kbd>N4kPages</kbd><dd>Specifies the maximum size of the process stack on systems with the 2692290001Sglebius<code>mlockall()</code> 2693290001Sglebiusfunction. 2694290001SglebiusDefaults to 50 4k pages (200 4k pages in OpenBSD). 2695301301Sdelphij<br><dt><code>filenum</code> <kbd>Nfiledescriptors</kbd><dd>Specifies the maximum number of file descriptors ntpd may have open at once. 2696301301SdelphijDefaults to the system default. 2697290001Sglebius</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 2699290001Sglebiusaddress and port number for sending messages with the specified 2700290001Sglebiuslocal interface address. 2701290001SglebiusIf the port number is unspecified, a value 2702290001Sglebiusof 18447 is used. 2703290001SglebiusIf the interface address is not specified, the 2704290001Sglebiusmessage is sent with a source address of the local interface the 2705290001Sglebiusmessage is sent through. 2706290001SglebiusNote that on a multihomed host the 2707290001Sglebiusinterface used may vary from time to time with routing changes. 2708290001Sglebius 2709310419Sdelphij <p>The trap receiver will generally log event messages and other 2710290001Sglebiusinformation from the server in a log file. 2711290001SglebiusWhile such monitor 2712290001Sglebiusprograms may also request their own trap dynamically, configuring a 2713290001Sglebiustrap receiver will ensure that no messages are lost when the server 2714290001Sglebiusis started. 2715290001Sglebius<br><dt><code>hop</code> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order, up to 8 2716290001Sglebiusvalues can be specified. 2717290001SglebiusIn manycast mode these values are used in turn in 2718290001Sglebiusan expanding-ring search. 2719290001SglebiusThe default is eight multiples of 32 starting at 2720290001Sglebius31. 2721290001Sglebius</dl> 2722290001Sglebius 2723310419Sdelphij <p>This section was generated by <strong>AutoGen</strong>, 2724290001Sglebiususing the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program. 2725290001SglebiusThis software is released under the NTP license, <http://ntp.org/license>;. 2726290001Sglebius 2727310419Sdelphij <ul class="menu"> 2728290001Sglebius<li><a accesskey="1" href="#ntp_002econf-Files">ntp.conf Files</a>: Files 2729290001Sglebius<li><a accesskey="2" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also 2730290001Sglebius<li><a accesskey="3" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs 2731290001Sglebius<li><a accesskey="4" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes 2732290001Sglebius</ul> 2733290001Sglebius 2734290001Sglebius<div class="node"> 2735290001Sglebius<p><hr> 2736290001Sglebius<a name="ntp_002econf-Files"></a> 2737290001Sglebius<br> 2738290001Sglebius</div> 2739290001Sglebius 2740290001Sglebius<h4 class="subsection">ntp.conf Files</h4> 2741290001Sglebius 2742310419Sdelphij <dl> 2743290001Sglebius<dt><span class="file">/etc/ntp.conf</span><dd>the default name of the configuration file 2744290001Sglebius<br><dt><span class="file">ntp.keys</span><dd>private MD5 keys 2745290001Sglebius<br><dt><span class="file">ntpkey</span><dd>RSA private key 2746290001Sglebius<br><dt><span class="file">ntpkey_</span><kbd>host</kbd><dd>RSA public key 2747290001Sglebius<br><dt><span class="file">ntp_dh</span><dd>Diffie-Hellman agreement parameters 2748290001Sglebius</dl> 2749310419Sdelphij <div class="node"> 2750290001Sglebius<p><hr> 2751290001Sglebius<a name="ntp_002econf-See-Also"></a> 2752290001Sglebius<br> 2753290001Sglebius</div> 2754290001Sglebius 2755290001Sglebius<h4 class="subsection">ntp.conf See Also</h4> 2756290001Sglebius 2757310419Sdelphij <p><code>ntpd(1ntpdmdoc)</code>, 2758290001Sglebius<code>ntpdc(1ntpdcmdoc)</code>, 2759290001Sglebius<code>ntpq(1ntpqmdoc)</code> 2760290001Sglebius 2761310419Sdelphij <p>In addition to the manual pages provided, 2762290001Sglebiuscomprehensive documentation is available on the world wide web 2763290001Sglebiusat 2764290001Sglebius<code>http://www.ntp.org/</code>. 2765290001SglebiusA snapshot of this documentation is available in HTML format in 2766290001Sglebius<span class="file">/usr/share/doc/ntp</span>. 2767290001Sglebius<br> 2768290001Sglebius 2769310419Sdelphij <p><br> 2770290001SglebiusDavid L. Mills, <em>Network Time Protocol (Version 4)</em>, RFC5905 2771290001Sglebius<div class="node"> 2772290001Sglebius<p><hr> 2773290001Sglebius<a name="ntp_002econf-Bugs"></a> 2774290001Sglebius<br> 2775290001Sglebius</div> 2776290001Sglebius 2777290001Sglebius<h4 class="subsection">ntp.conf Bugs</h4> 2778290001Sglebius 2779310419Sdelphij <p>The syntax checking is not picky; some combinations of 2780290001Sglebiusridiculous and even hilarious options and modes may not be 2781290001Sglebiusdetected. 2782290001Sglebius 2783310419Sdelphij <p>The 2784290001Sglebius<span class="file">ntpkey_</span><kbd>host</kbd> 2785290001Sglebiusfiles are really digital 2786290001Sglebiuscertificates. 2787290001SglebiusThese should be obtained via secure directory 2788290001Sglebiusservices when they become universally available. 2789290001Sglebius<div class="node"> 2790290001Sglebius<p><hr> 2791290001Sglebius<a name="ntp_002econf-Notes"></a> 2792290001Sglebius<br> 2793290001Sglebius</div> 2794290001Sglebius 2795290001Sglebius<h4 class="subsection">ntp.conf Notes</h4> 2796290001Sglebius 2797310419Sdelphij <p>This document was derived from FreeBSD. 2798290001Sglebius 2799290001Sglebius</body></html> 2800290001Sglebius 2801