12b15cb3dSCy Schubert<html lang="en"> 22b15cb3dSCy Schubert<head> 32b15cb3dSCy Schubert<title>NTP Configuration File User's Manual</title> 42b15cb3dSCy Schubert<meta http-equiv="Content-Type" content="text/html"> 52b15cb3dSCy Schubert<meta name="description" content="NTP Configuration File User's Manual"> 62b15cb3dSCy Schubert<meta name="generator" content="makeinfo 4.7"> 72b15cb3dSCy Schubert<link title="Top" rel="top" href="#Top"> 82b15cb3dSCy Schubert<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 92b15cb3dSCy Schubert<meta http-equiv="Content-Style-Type" content="text/css"> 102b15cb3dSCy Schubert<style type="text/css"><!-- 112b15cb3dSCy Schubert pre.display { font-family:inherit } 122b15cb3dSCy Schubert pre.format { font-family:inherit } 132b15cb3dSCy Schubert pre.smalldisplay { font-family:inherit; font-size:smaller } 142b15cb3dSCy Schubert pre.smallformat { font-family:inherit; font-size:smaller } 152b15cb3dSCy Schubert pre.smallexample { font-size:smaller } 162b15cb3dSCy Schubert pre.smalllisp { font-size:smaller } 172b15cb3dSCy Schubert span.sc { font-variant:small-caps } 182b15cb3dSCy Schubert span.roman { font-family: serif; font-weight: normal; } 192b15cb3dSCy Schubert--></style> 202b15cb3dSCy Schubert</head> 212b15cb3dSCy Schubert<body> 222b15cb3dSCy Schubert<h1 class="settitle">NTP Configuration File User's Manual</h1> 232b15cb3dSCy Schubert<div class="node"> 242b15cb3dSCy Schubert<p><hr> 252b15cb3dSCy Schubert<a name="Top"></a>Next: <a rel="next" accesskey="n" href="#ntp_002econf-Description">ntp.conf Description</a>, 262b15cb3dSCy SchubertPrevious: <a rel="previous" accesskey="p" href="#dir">(dir)</a>, 272b15cb3dSCy SchubertUp: <a rel="up" accesskey="u" href="#dir">(dir)</a> 282b15cb3dSCy Schubert<br> 292b15cb3dSCy Schubert</div> 302b15cb3dSCy Schubert 312b15cb3dSCy Schubert<h2 class="unnumbered">NTP's Configuration File User Manual</h2> 322b15cb3dSCy Schubert 332b15cb3dSCy Schubert<p>This document describes the configuration file for the NTP Project's 342b15cb3dSCy Schubert<code>ntpd</code> program. 352b15cb3dSCy Schubert 36*9034852cSGleb Smirnoff <p>This document applies to version 4.2.8p4 of <code>ntp.conf</code>. 372b15cb3dSCy Schubert 382b15cb3dSCy Schubert <div class="shortcontents"> 392b15cb3dSCy Schubert<h2>Short Contents</h2> 402b15cb3dSCy Schubert<ul> 412b15cb3dSCy Schubert<a href="#Top">NTP's Configuration File User Manual</a> 422b15cb3dSCy Schubert</ul> 432b15cb3dSCy Schubert</div> 442b15cb3dSCy Schubert 452b15cb3dSCy Schubert<ul class="menu"> 462b15cb3dSCy Schubert<li><a accesskey="1" href="#ntp_002econf-Description">ntp.conf Description</a> 472b15cb3dSCy Schubert<li><a accesskey="2" href="#ntp_002econf-Notes">ntp.conf Notes</a> 482b15cb3dSCy Schubert</ul> 492b15cb3dSCy Schubert 502b15cb3dSCy Schubert<div class="node"> 512b15cb3dSCy Schubert<p><hr> 522b15cb3dSCy Schubert<a name="ntp_002econf-Description"></a>Previous: <a rel="previous" accesskey="p" href="#Top">Top</a>, 532b15cb3dSCy SchubertUp: <a rel="up" accesskey="u" href="#Top">Top</a> 542b15cb3dSCy Schubert<br> 552b15cb3dSCy Schubert</div> 562b15cb3dSCy Schubert 572b15cb3dSCy Schubert<!-- node-name, next, previous, up --> 582b15cb3dSCy Schubert<h3 class="section">Description</h3> 592b15cb3dSCy Schubert 602b15cb3dSCy Schubert<p>The behavior of <code>ntpd</code> can be changed by a configuration file, 612b15cb3dSCy Schubertby default <code>ntp.conf</code>. 622b15cb3dSCy Schubert 632b15cb3dSCy Schubert<div class="node"> 642b15cb3dSCy Schubert<p><hr> 652b15cb3dSCy Schubert<a name="ntp_002econf-Notes"></a> 662b15cb3dSCy Schubert<br> 672b15cb3dSCy Schubert</div> 682b15cb3dSCy Schubert 692b15cb3dSCy Schubert<h3 class="section">Notes about ntp.conf</h3> 702b15cb3dSCy Schubert 712b15cb3dSCy Schubert<p><a name="index-ntp_002econf-1"></a><a name="index-Network-Time-Protocol-_0028NTP_0029-daemon-configuration-file-format-2"></a> 722b15cb3dSCy Schubert 732b15cb3dSCy Schubert <p>The 742b15cb3dSCy Schubert<code>ntp.conf</code> 752b15cb3dSCy Schubertconfiguration file is read at initial startup by the 762b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 772b15cb3dSCy Schubertdaemon in order to specify the synchronization sources, 782b15cb3dSCy Schubertmodes and other related information. 792b15cb3dSCy SchubertUsually, it is installed in the 802b15cb3dSCy Schubert<span class="file">/etc</span> 812b15cb3dSCy Schubertdirectory, 822b15cb3dSCy Schubertbut could be installed elsewhere 832b15cb3dSCy Schubert(see the daemon's 842b15cb3dSCy Schubert<code>-c</code> 852b15cb3dSCy Schubertcommand line option). 862b15cb3dSCy Schubert 872b15cb3dSCy Schubert <p>The file format is similar to other 882b15cb3dSCy Schubert<span class="sc">unix</span> 892b15cb3dSCy Schubertconfiguration files. 902b15cb3dSCy SchubertComments begin with a 912b15cb3dSCy Schubert# 922b15cb3dSCy Schubertcharacter and extend to the end of the line; 932b15cb3dSCy Schubertblank lines are ignored. 942b15cb3dSCy SchubertConfiguration commands consist of an initial keyword 952b15cb3dSCy Schubertfollowed by a list of arguments, 962b15cb3dSCy Schubertsome of which may be optional, separated by whitespace. 972b15cb3dSCy SchubertCommands may not be continued over multiple lines. 982b15cb3dSCy SchubertArguments may be host names, 992b15cb3dSCy Schuberthost addresses written in numeric, dotted-quad form, 1002b15cb3dSCy Schubertintegers, floating point numbers (when specifying times in seconds) 1012b15cb3dSCy Schubertand text strings. 1022b15cb3dSCy Schubert 1032b15cb3dSCy Schubert <p>The rest of this page describes the configuration and control options. 1042b15cb3dSCy SchubertThe 1052b15cb3dSCy Schubert"Notes on Configuring NTP and Setting up an NTP Subnet" 1062b15cb3dSCy Schubertpage 1072b15cb3dSCy Schubert(available as part of the HTML documentation 1082b15cb3dSCy Schubertprovided in 1092b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 1102b15cb3dSCy Schubertcontains an extended discussion of these options. 1112b15cb3dSCy SchubertIn addition to the discussion of general 1122b15cb3dSCy Schubert<a href="#Configuration-Options">Configuration Options</a>, 1132b15cb3dSCy Schubertthere are sections describing the following supported functionality 1142b15cb3dSCy Schubertand the options used to control it: 1152b15cb3dSCy Schubert <ul> 1162b15cb3dSCy Schubert<li><a href="#Authentication-Support">Authentication Support</a> 1172b15cb3dSCy Schubert<li><a href="#Monitoring-Support">Monitoring Support</a> 1182b15cb3dSCy Schubert<li><a href="#Access-Control-Support">Access Control Support</a> 1192b15cb3dSCy Schubert<li><a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a> 1202b15cb3dSCy Schubert<li><a href="#Reference-Clock-Support">Reference Clock Support</a> 1212b15cb3dSCy Schubert<li><a href="#Miscellaneous-Options">Miscellaneous Options</a> 1222b15cb3dSCy Schubert</ul> 1232b15cb3dSCy Schubert 1242b15cb3dSCy Schubert <p>Following these is a section describing 1252b15cb3dSCy Schubert<a href="#Miscellaneous-Options">Miscellaneous Options</a>. 1262b15cb3dSCy SchubertWhile there is a rich set of options available, 1272b15cb3dSCy Schubertthe only required option is one or more 1282b15cb3dSCy Schubert<code>pool</code>, 1292b15cb3dSCy Schubert<code>server</code>, 1302b15cb3dSCy Schubert<code>peer</code>, 1312b15cb3dSCy Schubert<code>broadcast</code> 1322b15cb3dSCy Schubertor 1332b15cb3dSCy Schubert<code>manycastclient</code> 1342b15cb3dSCy Schubertcommands. 1352b15cb3dSCy Schubert<div class="node"> 1362b15cb3dSCy Schubert<p><hr> 1372b15cb3dSCy Schubert<a name="Configuration-Support"></a> 1382b15cb3dSCy Schubert<br> 1392b15cb3dSCy Schubert</div> 1402b15cb3dSCy Schubert 1412b15cb3dSCy Schubert<h4 class="subsection">Configuration Support</h4> 1422b15cb3dSCy Schubert 1432b15cb3dSCy Schubert<p>Following is a description of the configuration commands in 1442b15cb3dSCy SchubertNTPv4. 1452b15cb3dSCy SchubertThese commands have the same basic functions as in NTPv3 and 1462b15cb3dSCy Schubertin some cases new functions and new arguments. 1472b15cb3dSCy SchubertThere are two 1482b15cb3dSCy Schubertclasses of commands, configuration commands that configure a 1492b15cb3dSCy Schubertpersistent association with a remote server or peer or reference 1502b15cb3dSCy Schubertclock, and auxiliary commands that specify environmental variables 1512b15cb3dSCy Schubertthat control various related operations. 1522b15cb3dSCy Schubert 1532b15cb3dSCy Schubert<h5 class="subsubsection">Configuration Commands</h5> 1542b15cb3dSCy Schubert 1552b15cb3dSCy Schubert<p>The various modes are determined by the command keyword and the 1562b15cb3dSCy Schuberttype of the required IP address. 1572b15cb3dSCy SchubertAddresses are classed by type as 1582b15cb3dSCy Schubert(s) a remote server or peer (IPv4 class A, B and C), (b) the 1592b15cb3dSCy Schubertbroadcast address of a local interface, (m) a multicast address (IPv4 1602b15cb3dSCy Schubertclass D), or (r) a reference clock address (127.127.x.x). 1612b15cb3dSCy SchubertNote that 1622b15cb3dSCy Schubertonly those options applicable to each command are listed below. 1632b15cb3dSCy SchubertUse 1642b15cb3dSCy Schubertof options not listed may not be caught as an error, but may result 1652b15cb3dSCy Schubertin some weird and even destructive behavior. 1662b15cb3dSCy Schubert 1672b15cb3dSCy Schubert <p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) 1682b15cb3dSCy Schubertis detected, support for the IPv6 address family is generated 1692b15cb3dSCy Schubertin addition to the default support of the IPv4 address family. 1702b15cb3dSCy SchubertIn a few cases, including the reslist billboard generated 1712b15cb3dSCy Schubertby ntpdc, IPv6 addresses are automatically generated. 1722b15cb3dSCy SchubertIPv6 addresses can be identified by the presence of colons 1732b15cb3dSCy Schubert: 1742b15cb3dSCy Schubertin the address field. 1752b15cb3dSCy SchubertIPv6 addresses can be used almost everywhere where 1762b15cb3dSCy SchubertIPv4 addresses can be used, 1772b15cb3dSCy Schubertwith the exception of reference clock addresses, 1782b15cb3dSCy Schubertwhich are always IPv4. 1792b15cb3dSCy Schubert 1802b15cb3dSCy Schubert <p>Note that in contexts where a host name is expected, a 1812b15cb3dSCy Schubert<code>-4</code> 1822b15cb3dSCy Schubertqualifier preceding 1832b15cb3dSCy Schubertthe host name forces DNS resolution to the IPv4 namespace, 1842b15cb3dSCy Schubertwhile a 1852b15cb3dSCy Schubert<code>-6</code> 1862b15cb3dSCy Schubertqualifier forces DNS resolution to the IPv6 namespace. 1872b15cb3dSCy SchubertSee IPv6 references for the 1882b15cb3dSCy Schubertequivalent classes for that address family. 1892b15cb3dSCy Schubert <dl> 1902b15cb3dSCy Schubert<dt><code>pool</code> <kbd>address</kbd> <code>[burst]</code> <code>[iburst]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code><br><dt><code>server</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[burst]</code> <code>[iburst]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code><br><dt><code>peer</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code><br><dt><code>broadcast</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[ttl </code><kbd>ttl</kbd><code>]</code><br><dt><code>manycastclient</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[ttl </code><kbd>ttl</kbd><code>]</code><dd></dl> 1912b15cb3dSCy Schubert 1922b15cb3dSCy Schubert <p>These five commands specify the time server name or address to 1932b15cb3dSCy Schubertbe used and the mode in which to operate. 1942b15cb3dSCy SchubertThe 1952b15cb3dSCy Schubert<kbd>address</kbd> 1962b15cb3dSCy Schubertcan be 1972b15cb3dSCy Schuberteither a DNS name or an IP address in dotted-quad notation. 1982b15cb3dSCy SchubertAdditional information on association behavior can be found in the 1992b15cb3dSCy Schubert"Association Management" 2002b15cb3dSCy Schubertpage 2012b15cb3dSCy Schubert(available as part of the HTML documentation 2022b15cb3dSCy Schubertprovided in 2032b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 2042b15cb3dSCy Schubert <dl> 2052b15cb3dSCy Schubert<dt><code>pool</code><dd>For type s addresses, this command mobilizes a persistent 2062b15cb3dSCy Schubertclient mode association with a number of remote servers. 2072b15cb3dSCy SchubertIn this mode the local clock can synchronized to the 2082b15cb3dSCy Schubertremote server, but the remote server can never be synchronized to 2092b15cb3dSCy Schubertthe local clock. 2102b15cb3dSCy Schubert<br><dt><code>server</code><dd>For type s and r addresses, this command mobilizes a persistent 2112b15cb3dSCy Schubertclient mode association with the specified remote server or local 2122b15cb3dSCy Schubertradio clock. 2132b15cb3dSCy SchubertIn this mode the local clock can synchronized to the 2142b15cb3dSCy Schubertremote server, but the remote server can never be synchronized to 2152b15cb3dSCy Schubertthe local clock. 2162b15cb3dSCy SchubertThis command should 2172b15cb3dSCy Schubert<em>not</em> 2182b15cb3dSCy Schubertbe used for type 2192b15cb3dSCy Schubertb or m addresses. 2202b15cb3dSCy Schubert<br><dt><code>peer</code><dd>For type s addresses (only), this command mobilizes a 2212b15cb3dSCy Schubertpersistent symmetric-active mode association with the specified 2222b15cb3dSCy Schubertremote peer. 2232b15cb3dSCy SchubertIn this mode the local clock can be synchronized to 2242b15cb3dSCy Schubertthe remote peer or the remote peer can be synchronized to the local 2252b15cb3dSCy Schubertclock. 2262b15cb3dSCy SchubertThis is useful in a network of servers where, depending on 2272b15cb3dSCy Schubertvarious failure scenarios, either the local or remote peer may be 2282b15cb3dSCy Schubertthe better source of time. 2292b15cb3dSCy SchubertThis command should NOT be used for type 2302b15cb3dSCy Schubertb, m or r addresses. 2312b15cb3dSCy Schubert<br><dt><code>broadcast</code><dd>For type b and m addresses (only), this 2322b15cb3dSCy Schubertcommand mobilizes a persistent broadcast mode association. 2332b15cb3dSCy SchubertMultiple 2342b15cb3dSCy Schubertcommands can be used to specify multiple local broadcast interfaces 2352b15cb3dSCy Schubert(subnets) and/or multiple multicast groups. 2362b15cb3dSCy SchubertNote that local 2372b15cb3dSCy Schubertbroadcast messages go only to the interface associated with the 2382b15cb3dSCy Schubertsubnet specified, but multicast messages go to all interfaces. 2392b15cb3dSCy SchubertIn broadcast mode the local server sends periodic broadcast 2402b15cb3dSCy Schubertmessages to a client population at the 2412b15cb3dSCy Schubert<kbd>address</kbd> 2422b15cb3dSCy Schubertspecified, which is usually the broadcast address on (one of) the 2432b15cb3dSCy Schubertlocal network(s) or a multicast address assigned to NTP. 2442b15cb3dSCy SchubertThe IANA 2452b15cb3dSCy Schuberthas assigned the multicast group address IPv4 224.0.1.1 and 2462b15cb3dSCy SchubertIPv6 ff05::101 (site local) exclusively to 2472b15cb3dSCy SchubertNTP, but other nonconflicting addresses can be used to contain the 2482b15cb3dSCy Schubertmessages within administrative boundaries. 2492b15cb3dSCy SchubertOrdinarily, this 2502b15cb3dSCy Schubertspecification applies only to the local server operating as a 2512b15cb3dSCy Schubertsender; for operation as a broadcast client, see the 2522b15cb3dSCy Schubert<code>broadcastclient</code> 2532b15cb3dSCy Schubertor 2542b15cb3dSCy Schubert<code>multicastclient</code> 2552b15cb3dSCy Schubertcommands 2562b15cb3dSCy Schubertbelow. 2572b15cb3dSCy Schubert<br><dt><code>manycastclient</code><dd>For type m addresses (only), this command mobilizes a 2582b15cb3dSCy Schubertmanycast client mode association for the multicast address 2592b15cb3dSCy Schubertspecified. 2602b15cb3dSCy SchubertIn this case a specific address must be supplied which 2612b15cb3dSCy Schubertmatches the address used on the 2622b15cb3dSCy Schubert<code>manycastserver</code> 2632b15cb3dSCy Schubertcommand for 2642b15cb3dSCy Schubertthe designated manycast servers. 2652b15cb3dSCy SchubertThe NTP multicast address 2662b15cb3dSCy Schubert224.0.1.1 assigned by the IANA should NOT be used, unless specific 2672b15cb3dSCy Schubertmeans are taken to avoid spraying large areas of the Internet with 2682b15cb3dSCy Schubertthese messages and causing a possibly massive implosion of replies 2692b15cb3dSCy Schubertat the sender. 2702b15cb3dSCy SchubertThe 2712b15cb3dSCy Schubert<code>manycastserver</code> 2722b15cb3dSCy Schubertcommand specifies that the local server 2732b15cb3dSCy Schubertis to operate in client mode with the remote servers that are 2742b15cb3dSCy Schubertdiscovered as the result of broadcast/multicast messages. 2752b15cb3dSCy SchubertThe 2762b15cb3dSCy Schubertclient broadcasts a request message to the group address associated 2772b15cb3dSCy Schubertwith the specified 2782b15cb3dSCy Schubert<kbd>address</kbd> 2792b15cb3dSCy Schubertand specifically enabled 2802b15cb3dSCy Schubertservers respond to these messages. 2812b15cb3dSCy SchubertThe client selects the servers 2822b15cb3dSCy Schubertproviding the best time and continues as with the 2832b15cb3dSCy Schubert<code>server</code> 2842b15cb3dSCy Schubertcommand. 2852b15cb3dSCy SchubertThe remaining servers are discarded as if never 2862b15cb3dSCy Schubertheard. 2872b15cb3dSCy Schubert</dl> 2882b15cb3dSCy Schubert 2892b15cb3dSCy Schubert <p>Options: 2902b15cb3dSCy Schubert <dl> 2912b15cb3dSCy Schubert<dt><code>autokey</code><dd>All packets sent to and received from the server or peer are to 2922b15cb3dSCy Schubertinclude authentication fields encrypted using the autokey scheme 2932b15cb3dSCy Schubertdescribed in 2942b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 2952b15cb3dSCy Schubert<br><dt><code>burst</code><dd>when the server is reachable, send a burst of eight packets 2962b15cb3dSCy Schubertinstead of the usual one. 2972b15cb3dSCy SchubertThe packet spacing is normally 2 s; 2982b15cb3dSCy Schuberthowever, the spacing between the first and second packets 2992b15cb3dSCy Schubertcan be changed with the calldelay command to allow 3002b15cb3dSCy Schubertadditional time for a modem or ISDN call to complete. 3012b15cb3dSCy SchubertThis is designed to improve timekeeping quality 3022b15cb3dSCy Schubertwith the 3032b15cb3dSCy Schubert<code>server</code> 3042b15cb3dSCy Schubertcommand and s addresses. 3052b15cb3dSCy Schubert<br><dt><code>iburst</code><dd>When the server is unreachable, send a burst of eight packets 3062b15cb3dSCy Schubertinstead of the usual one. 3072b15cb3dSCy SchubertThe packet spacing is normally 2 s; 3082b15cb3dSCy Schuberthowever, the spacing between the first two packets can be 3092b15cb3dSCy Schubertchanged with the calldelay command to allow 3102b15cb3dSCy Schubertadditional time for a modem or ISDN call to complete. 3112b15cb3dSCy SchubertThis is designed to speed the initial synchronization 3122b15cb3dSCy Schubertacquisition with the 3132b15cb3dSCy Schubert<code>server</code> 3142b15cb3dSCy Schubertcommand and s addresses and when 3152b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 3162b15cb3dSCy Schubertis started with the 3172b15cb3dSCy Schubert<code>-q</code> 3182b15cb3dSCy Schubertoption. 3192b15cb3dSCy Schubert<br><dt><code>key</code> <kbd>key</kbd><dd>All packets sent to and received from the server or peer are to 3202b15cb3dSCy Schubertinclude authentication fields encrypted using the specified 3212b15cb3dSCy Schubert<kbd>key</kbd> 3222b15cb3dSCy Schubertidentifier with values from 1 to 65534, inclusive. 3232b15cb3dSCy SchubertThe 3242b15cb3dSCy Schubertdefault is to include no encryption field. 3252b15cb3dSCy Schubert<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 3262b15cb3dSCy Schubertfor NTP messages, as a power of 2 in seconds 3272b15cb3dSCy SchubertThe maximum poll 3282b15cb3dSCy Schubertinterval defaults to 10 (1,024 s), but can be increased by the 3292b15cb3dSCy Schubert<code>maxpoll</code> 3302b15cb3dSCy Schubertoption to an upper limit of 17 (36.4 h). 3312b15cb3dSCy SchubertThe 3322b15cb3dSCy Schubertminimum poll interval defaults to 6 (64 s), but can be decreased by 3332b15cb3dSCy Schubertthe 3342b15cb3dSCy Schubert<code>minpoll</code> 3352b15cb3dSCy Schubertoption to a lower limit of 4 (16 s). 3362b15cb3dSCy Schubert<br><dt><code>noselect</code><dd>Marks the server as unused, except for display purposes. 3372b15cb3dSCy SchubertThe server is discarded by the selection algroithm. 3382b15cb3dSCy Schubert<br><dt><code>prefer</code><dd>Marks the server as preferred. 3392b15cb3dSCy SchubertAll other things being equal, 3402b15cb3dSCy Schubertthis host will be chosen for synchronization among a set of 3412b15cb3dSCy Schubertcorrectly operating hosts. 3422b15cb3dSCy SchubertSee the 3432b15cb3dSCy Schubert"Mitigation Rules and the prefer Keyword" 3442b15cb3dSCy Schubertpage 3452b15cb3dSCy Schubert(available as part of the HTML documentation 3462b15cb3dSCy Schubertprovided in 3472b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 3482b15cb3dSCy Schubertfor further information. 3492b15cb3dSCy Schubert<br><dt><code>ttl</code> <kbd>ttl</kbd><dd>This option is used only with broadcast server and manycast 3502b15cb3dSCy Schubertclient modes. 3512b15cb3dSCy SchubertIt specifies the time-to-live 3522b15cb3dSCy Schubert<kbd>ttl</kbd> 3532b15cb3dSCy Schubertto 3542b15cb3dSCy Schubertuse on broadcast server and multicast server and the maximum 3552b15cb3dSCy Schubert<kbd>ttl</kbd> 3562b15cb3dSCy Schubertfor the expanding ring search with manycast 3572b15cb3dSCy Schubertclient packets. 3582b15cb3dSCy SchubertSelection of the proper value, which defaults to 3592b15cb3dSCy Schubert127, is something of a black art and should be coordinated with the 3602b15cb3dSCy Schubertnetwork administrator. 3612b15cb3dSCy Schubert<br><dt><code>version</code> <kbd>version</kbd><dd>Specifies the version number to be used for outgoing NTP 3622b15cb3dSCy Schubertpackets. 3632b15cb3dSCy SchubertVersions 1-4 are the choices, with version 4 the 3642b15cb3dSCy Schubertdefault. 3652b15cb3dSCy Schubert</dl> 3662b15cb3dSCy Schubert 3672b15cb3dSCy Schubert<h5 class="subsubsection">Auxiliary Commands</h5> 3682b15cb3dSCy Schubert 3692b15cb3dSCy Schubert <dl> 3702b15cb3dSCy Schubert<dt><code>broadcastclient</code><dd>This command enables reception of broadcast server messages to 3712b15cb3dSCy Schubertany local interface (type b) address. 3722b15cb3dSCy SchubertUpon receiving a message for 3732b15cb3dSCy Schubertthe first time, the broadcast client measures the nominal server 3742b15cb3dSCy Schubertpropagation delay using a brief client/server exchange with the 3752b15cb3dSCy Schubertserver, then enters the broadcast client mode, in which it 3762b15cb3dSCy Schubertsynchronizes to succeeding broadcast messages. 3772b15cb3dSCy SchubertNote that, in order 3782b15cb3dSCy Schubertto avoid accidental or malicious disruption in this mode, both the 3792b15cb3dSCy Schubertserver and client should operate using symmetric-key or public-key 3802b15cb3dSCy Schubertauthentication as described in 3812b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 3822b15cb3dSCy Schubert<br><dt><code>manycastserver</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of manycast client messages to 3832b15cb3dSCy Schubertthe multicast group address(es) (type m) specified. 3842b15cb3dSCy SchubertAt least one 3852b15cb3dSCy Schubertaddress is required, but the NTP multicast address 224.0.1.1 3862b15cb3dSCy Schubertassigned by the IANA should NOT be used, unless specific means are 3872b15cb3dSCy Schuberttaken to limit the span of the reply and avoid a possibly massive 3882b15cb3dSCy Schubertimplosion at the original sender. 3892b15cb3dSCy SchubertNote that, in order to avoid 3902b15cb3dSCy Schubertaccidental or malicious disruption in this mode, both the server 3912b15cb3dSCy Schubertand client should operate using symmetric-key or public-key 3922b15cb3dSCy Schubertauthentication as described in 3932b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 3942b15cb3dSCy Schubert<br><dt><code>multicastclient</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of multicast server messages to 3952b15cb3dSCy Schubertthe multicast group address(es) (type m) specified. 3962b15cb3dSCy SchubertUpon receiving 3972b15cb3dSCy Schuberta message for the first time, the multicast client measures the 3982b15cb3dSCy Schubertnominal server propagation delay using a brief client/server 3992b15cb3dSCy Schubertexchange with the server, then enters the broadcast client mode, in 4002b15cb3dSCy Schubertwhich it synchronizes to succeeding multicast messages. 4012b15cb3dSCy SchubertNote that, 4022b15cb3dSCy Schubertin order to avoid accidental or malicious disruption in this mode, 4032b15cb3dSCy Schubertboth the server and client should operate using symmetric-key or 4042b15cb3dSCy Schubertpublic-key authentication as described in 4052b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 4062b15cb3dSCy Schubert<br><dt><code>mdnstries</code> <kbd>number</kbd><dd>If we are participating in mDNS, 4072b15cb3dSCy Schubertafter we have synched for the first time 4082b15cb3dSCy Schubertwe attempt to register with the mDNS system. 4092b15cb3dSCy SchubertIf that registration attempt fails, 4102b15cb3dSCy Schubertwe try again at one minute intervals for up to 4112b15cb3dSCy Schubert<code>mdnstries</code> 4122b15cb3dSCy Schuberttimes. 4132b15cb3dSCy SchubertAfter all, 4142b15cb3dSCy Schubert<code>ntpd</code> 4152b15cb3dSCy Schubertmay be starting before mDNS. 4162b15cb3dSCy SchubertThe default value for 4172b15cb3dSCy Schubert<code>mdnstries</code> 4182b15cb3dSCy Schubertis 5. 4192b15cb3dSCy Schubert</dl> 4202b15cb3dSCy Schubert<div class="node"> 4212b15cb3dSCy Schubert<p><hr> 4222b15cb3dSCy Schubert<a name="Authentication-Support"></a> 4232b15cb3dSCy Schubert<br> 4242b15cb3dSCy Schubert</div> 4252b15cb3dSCy Schubert 4262b15cb3dSCy Schubert<h4 class="subsection">Authentication Support</h4> 4272b15cb3dSCy Schubert 4282b15cb3dSCy Schubert<p>Authentication support allows the NTP client to verify that the 4292b15cb3dSCy Schubertserver is in fact known and trusted and not an intruder intending 4302b15cb3dSCy Schubertaccidentally or on purpose to masquerade as that server. 4312b15cb3dSCy SchubertThe NTPv3 4322b15cb3dSCy Schubertspecification RFC-1305 defines a scheme which provides 4332b15cb3dSCy Schubertcryptographic authentication of received NTP packets. 4342b15cb3dSCy SchubertOriginally, 4352b15cb3dSCy Schubertthis was done using the Data Encryption Standard (DES) algorithm 4362b15cb3dSCy Schubertoperating in Cipher Block Chaining (CBC) mode, commonly called 4372b15cb3dSCy SchubertDES-CBC. 4382b15cb3dSCy SchubertSubsequently, this was replaced by the RSA Message Digest 4392b15cb3dSCy Schubert5 (MD5) algorithm using a private key, commonly called keyed-MD5. 4402b15cb3dSCy SchubertEither algorithm computes a message digest, or one-way hash, which 4412b15cb3dSCy Schubertcan be used to verify the server has the correct private key and 4422b15cb3dSCy Schubertkey identifier. 4432b15cb3dSCy Schubert 4442b15cb3dSCy Schubert <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key 4452b15cb3dSCy Schubertcryptography and, in addition, provides a new Autokey scheme 4462b15cb3dSCy Schubertbased on public key cryptography. 4472b15cb3dSCy SchubertPublic key cryptography is generally considered more secure 4482b15cb3dSCy Schubertthan symmetric key cryptography, since the security is based 4492b15cb3dSCy Schuberton a private value which is generated by each server and 4502b15cb3dSCy Schubertnever revealed. 4512b15cb3dSCy SchubertWith Autokey all key distribution and 4522b15cb3dSCy Schubertmanagement functions involve only public values, which 4532b15cb3dSCy Schubertconsiderably simplifies key distribution and storage. 4542b15cb3dSCy SchubertPublic key management is based on X.509 certificates, 4552b15cb3dSCy Schubertwhich can be provided by commercial services or 4562b15cb3dSCy Schubertproduced by utility programs in the OpenSSL software library 4572b15cb3dSCy Schubertor the NTPv4 distribution. 4582b15cb3dSCy Schubert 4592b15cb3dSCy Schubert <p>While the algorithms for symmetric key cryptography are 4602b15cb3dSCy Schubertincluded in the NTPv4 distribution, public key cryptography 4612b15cb3dSCy Schubertrequires the OpenSSL software library to be installed 4622b15cb3dSCy Schubertbefore building the NTP distribution. 4632b15cb3dSCy SchubertDirections for doing that 4642b15cb3dSCy Schubertare on the Building and Installing the Distribution page. 4652b15cb3dSCy Schubert 4662b15cb3dSCy Schubert <p>Authentication is configured separately for each association 4672b15cb3dSCy Schubertusing the 4682b15cb3dSCy Schubert<code>key</code> 4692b15cb3dSCy Schubertor 4702b15cb3dSCy Schubert<code>autokey</code> 4712b15cb3dSCy Schubertsubcommand on the 4722b15cb3dSCy Schubert<code>peer</code>, 4732b15cb3dSCy Schubert<code>server</code>, 4742b15cb3dSCy Schubert<code>broadcast</code> 4752b15cb3dSCy Schubertand 4762b15cb3dSCy Schubert<code>manycastclient</code> 4772b15cb3dSCy Schubertconfiguration commands as described in 4782b15cb3dSCy Schubert<a href="#Configuration-Options">Configuration Options</a> 4792b15cb3dSCy Schubertpage. 4802b15cb3dSCy SchubertThe authentication 4812b15cb3dSCy Schubertoptions described below specify the locations of the key files, 4822b15cb3dSCy Schubertif other than default, which symmetric keys are trusted 4832b15cb3dSCy Schubertand the interval between various operations, if other than default. 4842b15cb3dSCy Schubert 4852b15cb3dSCy Schubert <p>Authentication is always enabled, 4862b15cb3dSCy Schubertalthough ineffective if not configured as 4872b15cb3dSCy Schubertdescribed below. 4882b15cb3dSCy SchubertIf a NTP packet arrives 4892b15cb3dSCy Schubertincluding a message authentication 4902b15cb3dSCy Schubertcode (MAC), it is accepted only if it 4912b15cb3dSCy Schubertpasses all cryptographic checks. 4922b15cb3dSCy SchubertThe 4932b15cb3dSCy Schubertchecks require correct key ID, key value 4942b15cb3dSCy Schubertand message digest. 4952b15cb3dSCy SchubertIf the packet has 4962b15cb3dSCy Schubertbeen modified in any way or replayed 4972b15cb3dSCy Schubertby an intruder, it will fail one or more 4982b15cb3dSCy Schubertof these checks and be discarded. 4992b15cb3dSCy SchubertFurthermore, the Autokey scheme requires a 5002b15cb3dSCy Schubertpreliminary protocol exchange to obtain 5012b15cb3dSCy Schubertthe server certificate, verify its 5022b15cb3dSCy Schubertcredentials and initialize the protocol 5032b15cb3dSCy Schubert 5042b15cb3dSCy Schubert <p>The 5052b15cb3dSCy Schubert<code>auth</code> 5062b15cb3dSCy Schubertflag controls whether new associations or 5072b15cb3dSCy Schubertremote configuration commands require cryptographic authentication. 5082b15cb3dSCy SchubertThis flag can be set or reset by the 5092b15cb3dSCy Schubert<code>enable</code> 5102b15cb3dSCy Schubertand 5112b15cb3dSCy Schubert<code>disable</code> 5122b15cb3dSCy Schubertcommands and also by remote 5132b15cb3dSCy Schubertconfiguration commands sent by a 5142b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 5152b15cb3dSCy Schubertprogram running in 5162b15cb3dSCy Schubertanother machine. 5172b15cb3dSCy SchubertIf this flag is enabled, which is the default 5182b15cb3dSCy Schubertcase, new broadcast client and symmetric passive associations and 5192b15cb3dSCy Schubertremote configuration commands must be cryptographically 5202b15cb3dSCy Schubertauthenticated using either symmetric key or public key cryptography. 5212b15cb3dSCy SchubertIf this 5222b15cb3dSCy Schubertflag is disabled, these operations are effective 5232b15cb3dSCy Schuberteven if not cryptographic 5242b15cb3dSCy Schubertauthenticated. 5252b15cb3dSCy SchubertIt should be understood 5262b15cb3dSCy Schubertthat operating with the 5272b15cb3dSCy Schubert<code>auth</code> 5282b15cb3dSCy Schubertflag disabled invites a significant vulnerability 5292b15cb3dSCy Schubertwhere a rogue hacker can 5302b15cb3dSCy Schubertmasquerade as a falseticker and seriously 5312b15cb3dSCy Schubertdisrupt system timekeeping. 5322b15cb3dSCy SchubertIt is 5332b15cb3dSCy Schubertimportant to note that this flag has no purpose 5342b15cb3dSCy Schubertother than to allow or disallow 5352b15cb3dSCy Schuberta new association in response to new broadcast 5362b15cb3dSCy Schubertand symmetric active messages 5372b15cb3dSCy Schubertand remote configuration commands and, in particular, 5382b15cb3dSCy Schubertthe flag has no effect on 5392b15cb3dSCy Schubertthe authentication process itself. 5402b15cb3dSCy Schubert 5412b15cb3dSCy Schubert <p>An attractive alternative where multicast support is available 5422b15cb3dSCy Schubertis manycast mode, in which clients periodically troll 5432b15cb3dSCy Schubertfor servers as described in the 5442b15cb3dSCy Schubert<a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a> 5452b15cb3dSCy Schubertpage. 5462b15cb3dSCy SchubertEither symmetric key or public key 5472b15cb3dSCy Schubertcryptographic authentication can be used in this mode. 5482b15cb3dSCy SchubertThe principle advantage 5492b15cb3dSCy Schubertof manycast mode is that potential servers need not be 5502b15cb3dSCy Schubertconfigured in advance, 5512b15cb3dSCy Schubertsince the client finds them during regular operation, 5522b15cb3dSCy Schubertand the configuration 5532b15cb3dSCy Schubertfiles for all clients can be identical. 5542b15cb3dSCy Schubert 5552b15cb3dSCy Schubert <p>The security model and protocol schemes for 5562b15cb3dSCy Schubertboth symmetric key and public key 5572b15cb3dSCy Schubertcryptography are summarized below; 5582b15cb3dSCy Schubertfurther details are in the briefings, papers 5592b15cb3dSCy Schubertand reports at the NTP project page linked from 5602b15cb3dSCy Schubert<code>http://www.ntp.org/</code>. 5612b15cb3dSCy Schubert 5622b15cb3dSCy Schubert<h5 class="subsubsection">Symmetric-Key Cryptography</h5> 5632b15cb3dSCy Schubert 5642b15cb3dSCy Schubert<p>The original RFC-1305 specification allows any one of possibly 5652b15cb3dSCy Schubert65,534 keys, each distinguished by a 32-bit key identifier, to 5662b15cb3dSCy Schubertauthenticate an association. 5672b15cb3dSCy SchubertThe servers and clients involved must 5682b15cb3dSCy Schubertagree on the key and key identifier to 5692b15cb3dSCy Schubertauthenticate NTP packets. 5702b15cb3dSCy SchubertKeys and 5712b15cb3dSCy Schubertrelated information are specified in a key 5722b15cb3dSCy Schubertfile, usually called 5732b15cb3dSCy Schubert<span class="file">ntp.keys</span>, 5742b15cb3dSCy Schubertwhich must be distributed and stored using 5752b15cb3dSCy Schubertsecure means beyond the scope of the NTP protocol itself. 5762b15cb3dSCy SchubertBesides the keys used 5772b15cb3dSCy Schubertfor ordinary NTP associations, 5782b15cb3dSCy Schubertadditional keys can be used as passwords for the 5792b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 5802b15cb3dSCy Schubertand 5812b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 5822b15cb3dSCy Schubertutility programs. 5832b15cb3dSCy Schubert 5842b15cb3dSCy Schubert <p>When 5852b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 5862b15cb3dSCy Schubertis first started, it reads the key file specified in the 5872b15cb3dSCy Schubert<code>keys</code> 5882b15cb3dSCy Schubertconfiguration command and installs the keys 5892b15cb3dSCy Schubertin the key cache. 5902b15cb3dSCy SchubertHowever, 5912b15cb3dSCy Schubertindividual keys must be activated with the 5922b15cb3dSCy Schubert<code>trusted</code> 5932b15cb3dSCy Schubertcommand before use. 5942b15cb3dSCy SchubertThis 5952b15cb3dSCy Schubertallows, for instance, the installation of possibly 5962b15cb3dSCy Schubertseveral batches of keys and 5972b15cb3dSCy Schubertthen activating or deactivating each batch 5982b15cb3dSCy Schubertremotely using 5992b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code>. 6002b15cb3dSCy SchubertThis also provides a revocation capability that can be used 6012b15cb3dSCy Schubertif a key becomes compromised. 6022b15cb3dSCy SchubertThe 6032b15cb3dSCy Schubert<code>requestkey</code> 6042b15cb3dSCy Schubertcommand selects the key used as the password for the 6052b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 6062b15cb3dSCy Schubertutility, while the 6072b15cb3dSCy Schubert<code>controlkey</code> 6082b15cb3dSCy Schubertcommand selects the key used as the password for the 6092b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 6102b15cb3dSCy Schubertutility. 6112b15cb3dSCy Schubert 6122b15cb3dSCy Schubert<h5 class="subsubsection">Public Key Cryptography</h5> 6132b15cb3dSCy Schubert 6142b15cb3dSCy Schubert<p>NTPv4 supports the original NTPv3 symmetric key scheme 6152b15cb3dSCy Schubertdescribed in RFC-1305 and in addition the Autokey protocol, 6162b15cb3dSCy Schubertwhich is based on public key cryptography. 6172b15cb3dSCy SchubertThe Autokey Version 2 protocol described on the Autokey Protocol 6182b15cb3dSCy Schubertpage verifies packet integrity using MD5 message digests 6192b15cb3dSCy Schubertand verifies the source with digital signatures and any of several 6202b15cb3dSCy Schubertdigest/signature schemes. 6212b15cb3dSCy SchubertOptional identity schemes described on the Identity Schemes 6222b15cb3dSCy Schubertpage and based on cryptographic challenge/response algorithms 6232b15cb3dSCy Schubertare also available. 6242b15cb3dSCy SchubertUsing all of these schemes provides strong security against 6252b15cb3dSCy Schubertreplay with or without modification, spoofing, masquerade 6262b15cb3dSCy Schubertand most forms of clogging attacks. 6272b15cb3dSCy Schubert 6282b15cb3dSCy Schubert <p>The Autokey protocol has several modes of operation 6292b15cb3dSCy Schubertcorresponding to the various NTP modes supported. 6302b15cb3dSCy SchubertMost modes use a special cookie which can be 6312b15cb3dSCy Schubertcomputed independently by the client and server, 6322b15cb3dSCy Schubertbut encrypted in transmission. 6332b15cb3dSCy SchubertAll modes use in addition a variant of the S-KEY scheme, 6342b15cb3dSCy Schubertin which a pseudo-random key list is generated and used 6352b15cb3dSCy Schubertin reverse order. 6362b15cb3dSCy SchubertThese schemes are described along with an executive summary, 6372b15cb3dSCy Schubertcurrent status, briefing slides and reading list on the 6382b15cb3dSCy Schubert<a href="#Autonomous-Authentication">Autonomous Authentication</a> 6392b15cb3dSCy Schubertpage. 6402b15cb3dSCy Schubert 6412b15cb3dSCy Schubert <p>The specific cryptographic environment used by Autokey servers 6422b15cb3dSCy Schubertand clients is determined by a set of files 6432b15cb3dSCy Schubertand soft links generated by the 6442b15cb3dSCy Schubert<code>ntp-keygen(1ntpkeygenmdoc)</code> 6452b15cb3dSCy Schubertprogram. 6462b15cb3dSCy SchubertThis includes a required host key file, 6472b15cb3dSCy Schubertrequired certificate file and optional sign key file, 6482b15cb3dSCy Schubertleapsecond file and identity scheme files. 6492b15cb3dSCy SchubertThe 6502b15cb3dSCy Schubertdigest/signature scheme is specified in the X.509 certificate 6512b15cb3dSCy Schubertalong with the matching sign key. 6522b15cb3dSCy SchubertThere are several schemes 6532b15cb3dSCy Schubertavailable in the OpenSSL software library, each identified 6542b15cb3dSCy Schubertby a specific string such as 6552b15cb3dSCy Schubert<code>md5WithRSAEncryption</code>, 6562b15cb3dSCy Schubertwhich stands for the MD5 message digest with RSA 6572b15cb3dSCy Schubertencryption scheme. 6582b15cb3dSCy SchubertThe current NTP distribution supports 6592b15cb3dSCy Schubertall the schemes in the OpenSSL library, including 6602b15cb3dSCy Schubertthose based on RSA and DSA digital signatures. 6612b15cb3dSCy Schubert 6622b15cb3dSCy Schubert <p>NTP secure groups can be used to define cryptographic compartments 6632b15cb3dSCy Schubertand security hierarchies. 6642b15cb3dSCy SchubertIt is important that every host 6652b15cb3dSCy Schubertin the group be able to construct a certificate trail to one 6662b15cb3dSCy Schubertor more trusted hosts in the same group. 6672b15cb3dSCy SchubertEach group 6682b15cb3dSCy Schuberthost runs the Autokey protocol to obtain the certificates 6692b15cb3dSCy Schubertfor all hosts along the trail to one or more trusted hosts. 6702b15cb3dSCy SchubertThis requires the configuration file in all hosts to be 6712b15cb3dSCy Schubertengineered so that, even under anticipated failure conditions, 6722b15cb3dSCy Schubertthe NTP subnet will form such that every group host can find 6732b15cb3dSCy Schuberta trail to at least one trusted host. 6742b15cb3dSCy Schubert 6752b15cb3dSCy Schubert<h5 class="subsubsection">Naming and Addressing</h5> 6762b15cb3dSCy Schubert 6772b15cb3dSCy Schubert<p>It is important to note that Autokey does not use DNS to 6782b15cb3dSCy Schubertresolve addresses, since DNS can't be completely trusted 6792b15cb3dSCy Schubertuntil the name servers have synchronized clocks. 6802b15cb3dSCy SchubertThe cryptographic name used by Autokey to bind the host identity 6812b15cb3dSCy Schubertcredentials and cryptographic values must be independent 6822b15cb3dSCy Schubertof interface, network and any other naming convention. 6832b15cb3dSCy SchubertThe name appears in the host certificate in either or both 6842b15cb3dSCy Schubertthe subject and issuer fields, so protection against 6852b15cb3dSCy SchubertDNS compromise is essential. 6862b15cb3dSCy Schubert 6872b15cb3dSCy Schubert <p>By convention, the name of an Autokey host is the name returned 6882b15cb3dSCy Schubertby the Unix 6892b15cb3dSCy Schubert<code>gethostname(2)</code> 6902b15cb3dSCy Schubertsystem call or equivalent in other systems. 6912b15cb3dSCy SchubertBy the system design 6922b15cb3dSCy Schubertmodel, there are no provisions to allow alternate names or aliases. 6932b15cb3dSCy SchubertHowever, this is not to say that DNS aliases, different names 6942b15cb3dSCy Schubertfor each interface, etc., are constrained in any way. 6952b15cb3dSCy Schubert 6962b15cb3dSCy Schubert <p>It is also important to note that Autokey verifies authenticity 6972b15cb3dSCy Schubertusing the host name, network address and public keys, 6982b15cb3dSCy Schubertall of which are bound together by the protocol specifically 6992b15cb3dSCy Schubertto deflect masquerade attacks. 7002b15cb3dSCy SchubertFor this reason Autokey 7012b15cb3dSCy Schubertincludes the source and destinatino IP addresses in message digest 7022b15cb3dSCy Schubertcomputations and so the same addresses must be available 7032b15cb3dSCy Schubertat both the server and client. 7042b15cb3dSCy SchubertFor this reason operation 7052b15cb3dSCy Schubertwith network address translation schemes is not possible. 7062b15cb3dSCy SchubertThis reflects the intended robust security model where government 7072b15cb3dSCy Schubertand corporate NTP servers are operated outside firewall perimeters. 7082b15cb3dSCy Schubert 7092b15cb3dSCy Schubert<h5 class="subsubsection">Operation</h5> 7102b15cb3dSCy Schubert 7112b15cb3dSCy Schubert<p>A specific combination of authentication scheme (none, 7122b15cb3dSCy Schubertsymmetric key, public key) and identity scheme is called 7132b15cb3dSCy Schuberta cryptotype, although not all combinations are compatible. 7142b15cb3dSCy SchubertThere may be management configurations where the clients, 7152b15cb3dSCy Schubertservers and peers may not all support the same cryptotypes. 7162b15cb3dSCy SchubertA secure NTPv4 subnet can be configured in many ways while 7172b15cb3dSCy Schubertkeeping in mind the principles explained above and 7182b15cb3dSCy Schubertin this section. 7192b15cb3dSCy SchubertNote however that some cryptotype 7202b15cb3dSCy Schubertcombinations may successfully interoperate with each other, 7212b15cb3dSCy Schubertbut may not represent good security practice. 7222b15cb3dSCy Schubert 7232b15cb3dSCy Schubert <p>The cryptotype of an association is determined at the time 7242b15cb3dSCy Schubertof mobilization, either at configuration time or some time 7252b15cb3dSCy Schubertlater when a message of appropriate cryptotype arrives. 7262b15cb3dSCy SchubertWhen mobilized by a 7272b15cb3dSCy Schubert<code>server</code> 7282b15cb3dSCy Schubertor 7292b15cb3dSCy Schubert<code>peer</code> 7302b15cb3dSCy Schubertconfiguration command and no 7312b15cb3dSCy Schubert<code>key</code> 7322b15cb3dSCy Schubertor 7332b15cb3dSCy Schubert<code>autokey</code> 7342b15cb3dSCy Schubertsubcommands are present, the association is not 7352b15cb3dSCy Schubertauthenticated; if the 7362b15cb3dSCy Schubert<code>key</code> 7372b15cb3dSCy Schubertsubcommand is present, the association is authenticated 7382b15cb3dSCy Schubertusing the symmetric key ID specified; if the 7392b15cb3dSCy Schubert<code>autokey</code> 7402b15cb3dSCy Schubertsubcommand is present, the association is authenticated 7412b15cb3dSCy Schubertusing Autokey. 7422b15cb3dSCy Schubert 7432b15cb3dSCy Schubert <p>When multiple identity schemes are supported in the Autokey 7442b15cb3dSCy Schubertprotocol, the first message exchange determines which one is used. 7452b15cb3dSCy SchubertThe client request message contains bits corresponding 7462b15cb3dSCy Schubertto which schemes it has available. 7472b15cb3dSCy SchubertThe server response message 7482b15cb3dSCy Schubertcontains bits corresponding to which schemes it has available. 7492b15cb3dSCy SchubertBoth server and client match the received bits with their own 7502b15cb3dSCy Schubertand select a common scheme. 7512b15cb3dSCy Schubert 7522b15cb3dSCy Schubert <p>Following the principle that time is a public value, 7532b15cb3dSCy Schuberta server responds to any client packet that matches 7542b15cb3dSCy Schubertits cryptotype capabilities. 7552b15cb3dSCy SchubertThus, a server receiving 7562b15cb3dSCy Schubertan unauthenticated packet will respond with an unauthenticated 7572b15cb3dSCy Schubertpacket, while the same server receiving a packet of a cryptotype 7582b15cb3dSCy Schubertit supports will respond with packets of that cryptotype. 7592b15cb3dSCy SchubertHowever, unconfigured broadcast or manycast client 7602b15cb3dSCy Schubertassociations or symmetric passive associations will not be 7612b15cb3dSCy Schubertmobilized unless the server supports a cryptotype compatible 7622b15cb3dSCy Schubertwith the first packet received. 7632b15cb3dSCy SchubertBy default, unauthenticated associations will not be mobilized 7642b15cb3dSCy Schubertunless overridden in a decidedly dangerous way. 7652b15cb3dSCy Schubert 7662b15cb3dSCy Schubert <p>Some examples may help to reduce confusion. 7672b15cb3dSCy SchubertClient Alice has no specific cryptotype selected. 7682b15cb3dSCy SchubertServer Bob has both a symmetric key file and minimal Autokey files. 7692b15cb3dSCy SchubertAlice's unauthenticated messages arrive at Bob, who replies with 7702b15cb3dSCy Schubertunauthenticated messages. 7712b15cb3dSCy SchubertCathy has a copy of Bob's symmetric 7722b15cb3dSCy Schubertkey file and has selected key ID 4 in messages to Bob. 7732b15cb3dSCy SchubertBob verifies the message with his key ID 4. 7742b15cb3dSCy SchubertIf it's the 7752b15cb3dSCy Schubertsame key and the message is verified, Bob sends Cathy a reply 7762b15cb3dSCy Schubertauthenticated with that key. 7772b15cb3dSCy SchubertIf verification fails, 7782b15cb3dSCy SchubertBob sends Cathy a thing called a crypto-NAK, which tells her 7792b15cb3dSCy Schubertsomething broke. 7802b15cb3dSCy SchubertShe can see the evidence using the 7812b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 7822b15cb3dSCy Schubertprogram. 7832b15cb3dSCy Schubert 7842b15cb3dSCy Schubert <p>Denise has rolled her own host key and certificate. 7852b15cb3dSCy SchubertShe also uses one of the identity schemes as Bob. 7862b15cb3dSCy SchubertShe sends the first Autokey message to Bob and they 7872b15cb3dSCy Schubertboth dance the protocol authentication and identity steps. 7882b15cb3dSCy SchubertIf all comes out okay, Denise and Bob continue as described above. 7892b15cb3dSCy Schubert 7902b15cb3dSCy Schubert <p>It should be clear from the above that Bob can support 7912b15cb3dSCy Schubertall the girls at the same time, as long as he has compatible 7922b15cb3dSCy Schubertauthentication and identity credentials. 7932b15cb3dSCy SchubertNow, Bob can act just like the girls in his own choice of servers; 7942b15cb3dSCy Schuberthe can run multiple configured associations with multiple different 7952b15cb3dSCy Schubertservers (or the same server, although that might not be useful). 7962b15cb3dSCy SchubertBut, wise security policy might preclude some cryptotype 7972b15cb3dSCy Schubertcombinations; for instance, running an identity scheme 7982b15cb3dSCy Schubertwith one server and no authentication with another might not be wise. 7992b15cb3dSCy Schubert 8002b15cb3dSCy Schubert<h5 class="subsubsection">Key Management</h5> 8012b15cb3dSCy Schubert 8022b15cb3dSCy Schubert<p>The cryptographic values used by the Autokey protocol are 8032b15cb3dSCy Schubertincorporated as a set of files generated by the 8042b15cb3dSCy Schubert<code>ntp-keygen(1ntpkeygenmdoc)</code> 8052b15cb3dSCy Schubertutility program, including symmetric key, host key and 8062b15cb3dSCy Schubertpublic certificate files, as well as sign key, identity parameters 8072b15cb3dSCy Schubertand leapseconds files. 8082b15cb3dSCy SchubertAlternatively, host and sign keys and 8092b15cb3dSCy Schubertcertificate files can be generated by the OpenSSL utilities 8102b15cb3dSCy Schubertand certificates can be imported from public certificate 8112b15cb3dSCy Schubertauthorities. 8122b15cb3dSCy SchubertNote that symmetric keys are necessary for the 8132b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 8142b15cb3dSCy Schubertand 8152b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 8162b15cb3dSCy Schubertutility programs. 8172b15cb3dSCy SchubertThe remaining files are necessary only for the 8182b15cb3dSCy SchubertAutokey protocol. 8192b15cb3dSCy Schubert 8202b15cb3dSCy Schubert <p>Certificates imported from OpenSSL or public certificate 8212b15cb3dSCy Schubertauthorities have certian limitations. 8222b15cb3dSCy SchubertThe certificate should be in ASN.1 syntax, X.509 Version 3 8232b15cb3dSCy Schubertformat and encoded in PEM, which is the same format 8242b15cb3dSCy Schubertused by OpenSSL. 8252b15cb3dSCy SchubertThe overall length of the certificate encoded 8262b15cb3dSCy Schubertin ASN.1 must not exceed 1024 bytes. 8272b15cb3dSCy SchubertThe subject distinguished 8282b15cb3dSCy Schubertname field (CN) is the fully qualified name of the host 8292b15cb3dSCy Schuberton which it is used; the remaining subject fields are ignored. 8302b15cb3dSCy SchubertThe certificate extension fields must not contain either 8312b15cb3dSCy Schuberta subject key identifier or a issuer key identifier field; 8322b15cb3dSCy Schuberthowever, an extended key usage field for a trusted host must 8332b15cb3dSCy Schubertcontain the value 8342b15cb3dSCy Schubert<code>trustRoot</code>;. 8352b15cb3dSCy SchubertOther extension fields are ignored. 8362b15cb3dSCy Schubert 8372b15cb3dSCy Schubert<h5 class="subsubsection">Authentication Commands</h5> 8382b15cb3dSCy Schubert 8392b15cb3dSCy Schubert <dl> 8402b15cb3dSCy Schubert<dt><code>autokey</code> <code>[</code><kbd>logsec</kbd><code>]</code><dd>Specifies the interval between regenerations of the session key 8412b15cb3dSCy Schubertlist used with the Autokey protocol. 8422b15cb3dSCy SchubertNote that the size of the key 8432b15cb3dSCy Schubertlist for each association depends on this interval and the current 8442b15cb3dSCy Schubertpoll interval. 8452b15cb3dSCy SchubertThe default value is 12 (4096 s or about 1.1 hours). 8462b15cb3dSCy SchubertFor poll intervals above the specified interval, a session key list 8472b15cb3dSCy Schubertwith a single entry will be regenerated for every message 8482b15cb3dSCy Schubertsent. 8492b15cb3dSCy Schubert<br><dt><code>controlkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the 8502b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 8512b15cb3dSCy Schubertutility, which uses the standard 8522b15cb3dSCy Schubertprotocol defined in RFC-1305. 8532b15cb3dSCy SchubertThe 8542b15cb3dSCy Schubert<kbd>key</kbd> 8552b15cb3dSCy Schubertargument is 8562b15cb3dSCy Schubertthe key identifier for a trusted key, where the value can be in the 8572b15cb3dSCy Schubertrange 1 to 65,534, inclusive. 8582b15cb3dSCy Schubert<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. 8592b15cb3dSCy SchubertIt activates public key 8602b15cb3dSCy Schubertcryptography, selects the message digest and signature 8612b15cb3dSCy Schubertencryption scheme and loads the required private and public 8622b15cb3dSCy Schubertvalues described above. 8632b15cb3dSCy SchubertIf one or more files are left unspecified, 8642b15cb3dSCy Schubertthe default names are used as described above. 8652b15cb3dSCy SchubertUnless the complete path and name of the file are specified, the 8662b15cb3dSCy Schubertlocation of a file is relative to the keys directory specified 8672b15cb3dSCy Schubertin the 8682b15cb3dSCy Schubert<code>keysdir</code> 8692b15cb3dSCy Schubertcommand or default 8702b15cb3dSCy Schubert<span class="file">/usr/local/etc</span>. 8712b15cb3dSCy SchubertFollowing are the subcommands: 8722b15cb3dSCy Schubert <dl> 8732b15cb3dSCy Schubert<dt><code>cert</code> <kbd>file</kbd><dd>Specifies the location of the required host public certificate file. 8742b15cb3dSCy SchubertThis overrides the link 8752b15cb3dSCy Schubert<span class="file">ntpkey_cert_</span><kbd>hostname</kbd> 8762b15cb3dSCy Schubertin the keys directory. 8772b15cb3dSCy Schubert<br><dt><code>gqpar</code> <kbd>file</kbd><dd>Specifies the location of the optional GQ parameters file. 8782b15cb3dSCy SchubertThis 8792b15cb3dSCy Schubertoverrides the link 8802b15cb3dSCy Schubert<span class="file">ntpkey_gq_</span><kbd>hostname</kbd> 8812b15cb3dSCy Schubertin the keys directory. 8822b15cb3dSCy Schubert<br><dt><code>host</code> <kbd>file</kbd><dd>Specifies the location of the required host key file. 8832b15cb3dSCy SchubertThis overrides 8842b15cb3dSCy Schubertthe link 8852b15cb3dSCy Schubert<span class="file">ntpkey_key_</span><kbd>hostname</kbd> 8862b15cb3dSCy Schubertin the keys directory. 8872b15cb3dSCy Schubert<br><dt><code>iffpar</code> <kbd>file</kbd><dd>Specifies the location of the optional IFF parameters file.This 8882b15cb3dSCy Schubertoverrides the link 8892b15cb3dSCy Schubert<span class="file">ntpkey_iff_</span><kbd>hostname</kbd> 8902b15cb3dSCy Schubertin the keys directory. 8912b15cb3dSCy Schubert<br><dt><code>leap</code> <kbd>file</kbd><dd>Specifies the location of the optional leapsecond file. 8922b15cb3dSCy SchubertThis overrides the link 8932b15cb3dSCy Schubert<span class="file">ntpkey_leap</span> 8942b15cb3dSCy Schubertin the keys directory. 8952b15cb3dSCy Schubert<br><dt><code>mvpar</code> <kbd>file</kbd><dd>Specifies the location of the optional MV parameters file. 8962b15cb3dSCy SchubertThis 8972b15cb3dSCy Schubertoverrides the link 8982b15cb3dSCy Schubert<span class="file">ntpkey_mv_</span><kbd>hostname</kbd> 8992b15cb3dSCy Schubertin the keys directory. 9002b15cb3dSCy Schubert<br><dt><code>pw</code> <kbd>password</kbd><dd>Specifies the password to decrypt files containing private keys and 9012b15cb3dSCy Schubertidentity parameters. 9022b15cb3dSCy SchubertThis is required only if these files have been 9032b15cb3dSCy Schubertencrypted. 9042b15cb3dSCy Schubert<br><dt><code>randfile</code> <kbd>file</kbd><dd>Specifies the location of the random seed file used by the OpenSSL 9052b15cb3dSCy Schubertlibrary. 9062b15cb3dSCy SchubertThe defaults are described in the main text above. 9072b15cb3dSCy Schubert<br><dt><code>sign</code> <kbd>file</kbd><dd>Specifies the location of the optional sign key file. 9082b15cb3dSCy SchubertThis overrides 9092b15cb3dSCy Schubertthe link 9102b15cb3dSCy Schubert<span class="file">ntpkey_sign_</span><kbd>hostname</kbd> 9112b15cb3dSCy Schubertin the keys directory. 9122b15cb3dSCy SchubertIf this file is 9132b15cb3dSCy Schubertnot found, the host key is also the sign key. 9142b15cb3dSCy Schubert</dl> 9152b15cb3dSCy Schubert <br><dt><code>keys</code> <kbd>keyfile</kbd><dd>Specifies the complete path and location of the MD5 key file 9162b15cb3dSCy Schubertcontaining the keys and key identifiers used by 9172b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code>, 9182b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 9192b15cb3dSCy Schubertand 9202b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 9212b15cb3dSCy Schubertwhen operating with symmetric key cryptography. 9222b15cb3dSCy SchubertThis is the same operation as the 9232b15cb3dSCy Schubert<code>-k</code> 9242b15cb3dSCy Schubertcommand line option. 9252b15cb3dSCy Schubert<br><dt><code>keysdir</code> <kbd>path</kbd><dd>This command specifies the default directory path for 9262b15cb3dSCy Schubertcryptographic keys, parameters and certificates. 9272b15cb3dSCy SchubertThe default is 9282b15cb3dSCy Schubert<span class="file">/usr/local/etc/</span>. 9292b15cb3dSCy Schubert<br><dt><code>requestkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the 9302b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 9312b15cb3dSCy Schubertutility program, which uses a 9322b15cb3dSCy Schubertproprietary protocol specific to this implementation of 9332b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code>. 9342b15cb3dSCy SchubertThe 9352b15cb3dSCy Schubert<kbd>key</kbd> 9362b15cb3dSCy Schubertargument is a key identifier 9372b15cb3dSCy Schubertfor the trusted key, where the value can be in the range 1 to 9382b15cb3dSCy Schubert65,534, inclusive. 9392b15cb3dSCy Schubert<br><dt><code>revoke</code> <kbd>logsec</kbd><dd>Specifies the interval between re-randomization of certain 9402b15cb3dSCy Schubertcryptographic values used by the Autokey scheme, as a power of 2 in 9412b15cb3dSCy Schubertseconds. 9422b15cb3dSCy SchubertThese values need to be updated frequently in order to 9432b15cb3dSCy Schubertdeflect brute-force attacks on the algorithms of the scheme; 9442b15cb3dSCy Schuberthowever, updating some values is a relatively expensive operation. 9452b15cb3dSCy SchubertThe default interval is 16 (65,536 s or about 18 hours). 9462b15cb3dSCy SchubertFor poll 9472b15cb3dSCy Schubertintervals above the specified interval, the values will be updated 9482b15cb3dSCy Schubertfor every message sent. 9492b15cb3dSCy Schubert<br><dt><code>trustedkey</code> <kbd>key</kbd> <kbd>...</kbd><dd>Specifies the key identifiers which are trusted for the 9502b15cb3dSCy Schubertpurposes of authenticating peers with symmetric key cryptography, 9512b15cb3dSCy Schubertas well as keys used by the 9522b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 9532b15cb3dSCy Schubertand 9542b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 9552b15cb3dSCy Schubertprograms. 9562b15cb3dSCy SchubertThe authentication procedures require that both the local 9572b15cb3dSCy Schubertand remote servers share the same key and key identifier for this 9582b15cb3dSCy Schubertpurpose, although different keys can be used with different 9592b15cb3dSCy Schubertservers. 9602b15cb3dSCy SchubertThe 9612b15cb3dSCy Schubert<kbd>key</kbd> 9622b15cb3dSCy Schubertarguments are 32-bit unsigned 9632b15cb3dSCy Schubertintegers with values from 1 to 65,534. 9642b15cb3dSCy Schubert</dl> 9652b15cb3dSCy Schubert 9662b15cb3dSCy Schubert<h5 class="subsubsection">Error Codes</h5> 9672b15cb3dSCy Schubert 9682b15cb3dSCy Schubert<p>The following error codes are reported via the NTP control 9692b15cb3dSCy Schubertand monitoring protocol trap mechanism. 9702b15cb3dSCy Schubert <dl> 9712b15cb3dSCy Schubert<dt>101<dd>(bad field format or length) 9722b15cb3dSCy SchubertThe packet has invalid version, length or format. 9732b15cb3dSCy Schubert<br><dt>102<dd>(bad timestamp) 9742b15cb3dSCy SchubertThe packet timestamp is the same or older than the most recent received. 9752b15cb3dSCy SchubertThis could be due to a replay or a server clock time step. 9762b15cb3dSCy Schubert<br><dt>103<dd>(bad filestamp) 9772b15cb3dSCy SchubertThe packet filestamp is the same or older than the most recent received. 9782b15cb3dSCy SchubertThis could be due to a replay or a key file generation error. 9792b15cb3dSCy Schubert<br><dt>104<dd>(bad or missing public key) 9802b15cb3dSCy SchubertThe public key is missing, has incorrect format or is an unsupported type. 9812b15cb3dSCy Schubert<br><dt>105<dd>(unsupported digest type) 9822b15cb3dSCy SchubertThe server requires an unsupported digest/signature scheme. 9832b15cb3dSCy Schubert<br><dt>106<dd>(mismatched digest types) 9842b15cb3dSCy SchubertNot used. 9852b15cb3dSCy Schubert<br><dt>107<dd>(bad signature length) 9862b15cb3dSCy SchubertThe signature length does not match the current public key. 9872b15cb3dSCy Schubert<br><dt>108<dd>(signature not verified) 9882b15cb3dSCy SchubertThe message fails the signature check. 9892b15cb3dSCy SchubertIt could be bogus or signed by a 9902b15cb3dSCy Schubertdifferent private key. 9912b15cb3dSCy Schubert<br><dt>109<dd>(certificate not verified) 9922b15cb3dSCy SchubertThe certificate is invalid or signed with the wrong key. 9932b15cb3dSCy Schubert<br><dt>110<dd>(certificate not verified) 9942b15cb3dSCy SchubertThe certificate is not yet valid or has expired or the signature could not 9952b15cb3dSCy Schubertbe verified. 9962b15cb3dSCy Schubert<br><dt>111<dd>(bad or missing cookie) 9972b15cb3dSCy SchubertThe cookie is missing, corrupted or bogus. 9982b15cb3dSCy Schubert<br><dt>112<dd>(bad or missing leapseconds table) 9992b15cb3dSCy SchubertThe leapseconds table is missing, corrupted or bogus. 10002b15cb3dSCy Schubert<br><dt>113<dd>(bad or missing certificate) 10012b15cb3dSCy SchubertThe certificate is missing, corrupted or bogus. 10022b15cb3dSCy Schubert<br><dt>114<dd>(bad or missing identity) 10032b15cb3dSCy SchubertThe identity key is missing, corrupt or bogus. 10042b15cb3dSCy Schubert</dl> 10052b15cb3dSCy Schubert <div class="node"> 10062b15cb3dSCy Schubert<p><hr> 10072b15cb3dSCy Schubert<a name="Monitoring-Support"></a> 10082b15cb3dSCy Schubert<br> 10092b15cb3dSCy Schubert</div> 10102b15cb3dSCy Schubert 10112b15cb3dSCy Schubert<h4 class="subsection">Monitoring Support</h4> 10122b15cb3dSCy Schubert 10132b15cb3dSCy Schubert<p><code>ntpd(1ntpdmdoc)</code> 10142b15cb3dSCy Schubertincludes a comprehensive monitoring facility suitable 10152b15cb3dSCy Schubertfor continuous, long term recording of server and client 10162b15cb3dSCy Schuberttimekeeping performance. 10172b15cb3dSCy SchubertSee the 10182b15cb3dSCy Schubert<code>statistics</code> 10192b15cb3dSCy Schubertcommand below 10202b15cb3dSCy Schubertfor a listing and example of each type of statistics currently 10212b15cb3dSCy Schubertsupported. 10222b15cb3dSCy SchubertStatistic files are managed using file generation sets 10232b15cb3dSCy Schubertand scripts in the 10242b15cb3dSCy Schubert<span class="file">./scripts</span> 10252b15cb3dSCy Schubertdirectory of this distribution. 10262b15cb3dSCy SchubertUsing 10272b15cb3dSCy Schubertthese facilities and 10282b15cb3dSCy Schubert<span class="sc">unix</span> 10292b15cb3dSCy Schubert<code>cron(8)</code> 10302b15cb3dSCy Schubertjobs, the data can be 10312b15cb3dSCy Schubertautomatically summarized and archived for retrospective analysis. 10322b15cb3dSCy Schubert 10332b15cb3dSCy Schubert<h5 class="subsubsection">Monitoring Commands</h5> 10342b15cb3dSCy Schubert 10352b15cb3dSCy Schubert <dl> 10362b15cb3dSCy Schubert<dt><code>statistics</code> <kbd>name</kbd> <kbd>...</kbd><dd>Enables writing of statistics records. 10372b15cb3dSCy SchubertCurrently, eight kinds of 10382b15cb3dSCy Schubert<kbd>name</kbd> 10392b15cb3dSCy Schubertstatistics are supported. 10402b15cb3dSCy Schubert <dl> 10412b15cb3dSCy Schubert<dt><code>clockstats</code><dd>Enables recording of clock driver statistics information. 10422b15cb3dSCy SchubertEach update 10432b15cb3dSCy Schubertreceived from a clock driver appends a line of the following form to 10442b15cb3dSCy Schubertthe file generation set named 10452b15cb3dSCy Schubert<code>clockstats</code>: 10462b15cb3dSCy Schubert<pre class="verbatim"> 10472b15cb3dSCy Schubert 49213 525.624 127.127.4.1 93 226 00:08:29.606 D 10482b15cb3dSCy Schubert </pre> 10492b15cb3dSCy Schubert 10502b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and time 10512b15cb3dSCy Schubert(seconds and fraction past UTC midnight). 10522b15cb3dSCy SchubertThe next field shows the 10532b15cb3dSCy Schubertclock address in dotted-quad notation. 10542b15cb3dSCy SchubertThe final field shows the last 10552b15cb3dSCy Schuberttimecode received from the clock in decoded ASCII format, where 10562b15cb3dSCy Schubertmeaningful. 10572b15cb3dSCy SchubertIn some clock drivers a good deal of additional information 10582b15cb3dSCy Schubertcan be gathered and displayed as well. 10592b15cb3dSCy SchubertSee information specific to each 10602b15cb3dSCy Schubertclock for further details. 10612b15cb3dSCy Schubert<br><dt><code>cryptostats</code><dd>This option requires the OpenSSL cryptographic software library. 10622b15cb3dSCy SchubertIt 10632b15cb3dSCy Schubertenables recording of cryptographic public key protocol information. 10642b15cb3dSCy SchubertEach message received by the protocol module appends a line of the 10652b15cb3dSCy Schubertfollowing form to the file generation set named 10662b15cb3dSCy Schubert<code>cryptostats</code>: 10672b15cb3dSCy Schubert<pre class="verbatim"> 10682b15cb3dSCy Schubert 49213 525.624 127.127.4.1 message 10692b15cb3dSCy Schubert </pre> 10702b15cb3dSCy Schubert 10712b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and time 10722b15cb3dSCy Schubert(seconds and fraction past UTC midnight). 10732b15cb3dSCy SchubertThe next field shows the peer 10742b15cb3dSCy Schubertaddress in dotted-quad notation, The final message field includes the 10752b15cb3dSCy Schubertmessage type and certain ancillary information. 10762b15cb3dSCy SchubertSee the 10772b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a> 10782b15cb3dSCy Schubertsection for further information. 10792b15cb3dSCy Schubert<br><dt><code>loopstats</code><dd>Enables recording of loop filter statistics information. 10802b15cb3dSCy SchubertEach 10812b15cb3dSCy Schubertupdate of the local clock outputs a line of the following form to 10822b15cb3dSCy Schubertthe file generation set named 10832b15cb3dSCy Schubert<code>loopstats</code>: 10842b15cb3dSCy Schubert<pre class="verbatim"> 10852b15cb3dSCy Schubert 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 10862b15cb3dSCy Schubert </pre> 10872b15cb3dSCy Schubert 10882b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and 10892b15cb3dSCy Schuberttime (seconds and fraction past UTC midnight). 10902b15cb3dSCy SchubertThe next five fields 10912b15cb3dSCy Schubertshow time offset (seconds), frequency offset (parts per million - 10922b15cb3dSCy SchubertPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 10932b15cb3dSCy Schubertdiscipline time constant. 10942b15cb3dSCy Schubert<br><dt><code>peerstats</code><dd>Enables recording of peer statistics information. 10952b15cb3dSCy SchubertThis includes 10962b15cb3dSCy Schubertstatistics records of all peers of a NTP server and of special 10972b15cb3dSCy Schubertsignals, where present and configured. 10982b15cb3dSCy SchubertEach valid update appends a 10992b15cb3dSCy Schubertline of the following form to the current element of a file 11002b15cb3dSCy Schubertgeneration set named 11012b15cb3dSCy Schubert<code>peerstats</code>: 11022b15cb3dSCy Schubert<pre class="verbatim"> 11032b15cb3dSCy Schubert 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 11042b15cb3dSCy Schubert </pre> 11052b15cb3dSCy Schubert 11062b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and 11072b15cb3dSCy Schuberttime (seconds and fraction past UTC midnight). 11082b15cb3dSCy SchubertThe next two fields 11092b15cb3dSCy Schubertshow the peer address in dotted-quad notation and status, 11102b15cb3dSCy Schubertrespectively. 11112b15cb3dSCy SchubertThe status field is encoded in hex in the format 11122b15cb3dSCy Schubertdescribed in Appendix A of the NTP specification RFC 1305. 11132b15cb3dSCy SchubertThe final four fields show the offset, 11142b15cb3dSCy Schubertdelay, dispersion and RMS jitter, all in seconds. 11152b15cb3dSCy Schubert<br><dt><code>rawstats</code><dd>Enables recording of raw-timestamp statistics information. 11162b15cb3dSCy SchubertThis 11172b15cb3dSCy Schubertincludes statistics records of all peers of a NTP server and of 11182b15cb3dSCy Schubertspecial signals, where present and configured. 11192b15cb3dSCy SchubertEach NTP message 11202b15cb3dSCy Schubertreceived from a peer or clock driver appends a line of the 11212b15cb3dSCy Schubertfollowing form to the file generation set named 11222b15cb3dSCy Schubert<code>rawstats</code>: 11232b15cb3dSCy Schubert<pre class="verbatim"> 11242b15cb3dSCy Schubert 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 11252b15cb3dSCy Schubert </pre> 11262b15cb3dSCy Schubert 11272b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and 11282b15cb3dSCy Schuberttime (seconds and fraction past UTC midnight). 11292b15cb3dSCy SchubertThe next two fields 11302b15cb3dSCy Schubertshow the remote peer or clock address followed by the local address 11312b15cb3dSCy Schubertin dotted-quad notation. 11322b15cb3dSCy SchubertThe final four fields show the originate, 11332b15cb3dSCy Schubertreceive, transmit and final NTP timestamps in order. 11342b15cb3dSCy SchubertThe timestamp 11352b15cb3dSCy Schubertvalues are as received and before processing by the various data 11362b15cb3dSCy Schubertsmoothing and mitigation algorithms. 11372b15cb3dSCy Schubert<br><dt><code>sysstats</code><dd>Enables recording of ntpd statistics counters on a periodic basis. 11382b15cb3dSCy SchubertEach 11392b15cb3dSCy Schuberthour a line of the following form is appended to the file generation 11402b15cb3dSCy Schubertset named 11412b15cb3dSCy Schubert<code>sysstats</code>: 11422b15cb3dSCy Schubert<pre class="verbatim"> 11432b15cb3dSCy Schubert 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 11442b15cb3dSCy Schubert </pre> 11452b15cb3dSCy Schubert 11462b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and time 11472b15cb3dSCy Schubert(seconds and fraction past UTC midnight). 11482b15cb3dSCy SchubertThe remaining ten fields show 11492b15cb3dSCy Schubertthe statistics counter values accumulated since the last generated 11502b15cb3dSCy Schubertline. 11512b15cb3dSCy Schubert <dl> 11522b15cb3dSCy Schubert<dt>Time since restart <code>36000</code><dd>Time in hours since the system was last rebooted. 11532b15cb3dSCy Schubert<br><dt>Packets received <code>81965</code><dd>Total number of packets received. 11542b15cb3dSCy Schubert<br><dt>Packets processed <code>0</code><dd>Number of packets received in response to previous packets sent 11552b15cb3dSCy Schubert<br><dt>Current version <code>9546</code><dd>Number of packets matching the current NTP version. 11562b15cb3dSCy Schubert<br><dt>Previous version <code>56</code><dd>Number of packets matching the previous NTP version. 11572b15cb3dSCy Schubert<br><dt>Bad version <code>71793</code><dd>Number of packets matching neither NTP version. 11582b15cb3dSCy Schubert<br><dt>Access denied <code>512</code><dd>Number of packets denied access for any reason. 11592b15cb3dSCy Schubert<br><dt>Bad length or format <code>540</code><dd>Number of packets with invalid length, format or port number. 11602b15cb3dSCy Schubert<br><dt>Bad authentication <code>10</code><dd>Number of packets not verified as authentic. 11612b15cb3dSCy Schubert<br><dt>Rate exceeded <code>147</code><dd>Number of packets discarded due to rate limitation. 11622b15cb3dSCy Schubert</dl> 11632b15cb3dSCy Schubert <br><dt><code>statsdir</code> <kbd>directory_path</kbd><dd>Indicates the full path of a directory where statistics files 11642b15cb3dSCy Schubertshould be created (see below). 11652b15cb3dSCy SchubertThis keyword allows 11662b15cb3dSCy Schubertthe (otherwise constant) 11672b15cb3dSCy Schubert<code>filegen</code> 11682b15cb3dSCy Schubertfilename prefix to be modified for file generation sets, which 11692b15cb3dSCy Schubertis useful for handling statistics logs. 11702b15cb3dSCy Schubert<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. 11712b15cb3dSCy SchubertGeneration 11722b15cb3dSCy Schubertfile sets provide a means for handling files that are 11732b15cb3dSCy Schubertcontinuously growing during the lifetime of a server. 11742b15cb3dSCy SchubertServer statistics are a typical example for such files. 11752b15cb3dSCy SchubertGeneration file sets provide access to a set of files used 11762b15cb3dSCy Schubertto store the actual data. 11772b15cb3dSCy SchubertAt any time at most one element 11782b15cb3dSCy Schubertof the set is being written to. 11792b15cb3dSCy SchubertThe type given specifies 11802b15cb3dSCy Schubertwhen and how data will be directed to a new element of the set. 11812b15cb3dSCy SchubertThis way, information stored in elements of a file set 11822b15cb3dSCy Schubertthat are currently unused are available for administrational 11832b15cb3dSCy Schubertoperations without the risk of disturbing the operation of ntpd. 11842b15cb3dSCy Schubert(Most important: they can be removed to free space for new data 11852b15cb3dSCy Schubertproduced.) 11862b15cb3dSCy Schubert 11872b15cb3dSCy Schubert <p>Note that this command can be sent from the 11882b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 11892b15cb3dSCy Schubertprogram running at a remote location. 11902b15cb3dSCy Schubert <dl> 11912b15cb3dSCy Schubert<dt><code>name</code><dd>This is the type of the statistics records, as shown in the 11922b15cb3dSCy Schubert<code>statistics</code> 11932b15cb3dSCy Schubertcommand. 11942b15cb3dSCy Schubert<br><dt><code>file</code> <kbd>filename</kbd><dd>This is the file name for the statistics records. 11952b15cb3dSCy SchubertFilenames of set 11962b15cb3dSCy Schubertmembers are built from three concatenated elements 11972b15cb3dSCy Schubert<code>prefix</code>, 11982b15cb3dSCy Schubert<code>filename</code> 11992b15cb3dSCy Schubertand 12002b15cb3dSCy Schubert<code>suffix</code>: 12012b15cb3dSCy Schubert <dl> 12022b15cb3dSCy Schubert<dt><code>prefix</code><dd>This is a constant filename path. 12032b15cb3dSCy SchubertIt is not subject to 12042b15cb3dSCy Schubertmodifications via the 12052b15cb3dSCy Schubert<kbd>filegen</kbd> 12062b15cb3dSCy Schubertoption. 12072b15cb3dSCy SchubertIt is defined by the 12082b15cb3dSCy Schubertserver, usually specified as a compile-time constant. 12092b15cb3dSCy SchubertIt may, 12102b15cb3dSCy Schuberthowever, be configurable for individual file generation sets 12112b15cb3dSCy Schubertvia other commands. 12122b15cb3dSCy SchubertFor example, the prefix used with 12132b15cb3dSCy Schubert<kbd>loopstats</kbd> 12142b15cb3dSCy Schubertand 12152b15cb3dSCy Schubert<kbd>peerstats</kbd> 12162b15cb3dSCy Schubertgeneration can be configured using the 12172b15cb3dSCy Schubert<kbd>statsdir</kbd> 12182b15cb3dSCy Schubertoption explained above. 12192b15cb3dSCy Schubert<br><dt><code>filename</code><dd>This string is directly concatenated to the prefix mentioned 12202b15cb3dSCy Schubertabove (no intervening 12212b15cb3dSCy Schubert/). 12222b15cb3dSCy SchubertThis can be modified using 12232b15cb3dSCy Schubertthe file argument to the 12242b15cb3dSCy Schubert<kbd>filegen</kbd> 12252b15cb3dSCy Schubertstatement. 12262b15cb3dSCy SchubertNo 12272b15cb3dSCy Schubert<span class="file">..</span> 12282b15cb3dSCy Schubertelements are 12292b15cb3dSCy Schubertallowed in this component to prevent filenames referring to 12302b15cb3dSCy Schubertparts outside the filesystem hierarchy denoted by 12312b15cb3dSCy Schubert<kbd>prefix</kbd>. 12322b15cb3dSCy Schubert<br><dt><code>suffix</code><dd>This part is reflects individual elements of a file set. 12332b15cb3dSCy SchubertIt is 12342b15cb3dSCy Schubertgenerated according to the type of a file set. 12352b15cb3dSCy Schubert</dl> 12362b15cb3dSCy Schubert <br><dt><code>type</code> <kbd>typename</kbd><dd>A file generation set is characterized by its type. 12372b15cb3dSCy SchubertThe following 12382b15cb3dSCy Schuberttypes are supported: 12392b15cb3dSCy Schubert <dl> 12402b15cb3dSCy Schubert<dt><code>none</code><dd>The file set is actually a single plain file. 12412b15cb3dSCy Schubert<br><dt><code>pid</code><dd>One element of file set is used per incarnation of a ntpd 12422b15cb3dSCy Schubertserver. 12432b15cb3dSCy SchubertThis type does not perform any changes to file set 12442b15cb3dSCy Schubertmembers during runtime, however it provides an easy way of 12452b15cb3dSCy Schubertseparating files belonging to different 12462b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 12472b15cb3dSCy Schubertserver incarnations. 12482b15cb3dSCy SchubertThe set member filename is built by appending a 12492b15cb3dSCy Schubert. 12502b15cb3dSCy Schubertto concatenated 12512b15cb3dSCy Schubert<kbd>prefix</kbd> 12522b15cb3dSCy Schubertand 12532b15cb3dSCy Schubert<kbd>filename</kbd> 12542b15cb3dSCy Schubertstrings, and 12552b15cb3dSCy Schubertappending the decimal representation of the process ID of the 12562b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 12572b15cb3dSCy Schubertserver process. 12582b15cb3dSCy Schubert<br><dt><code>day</code><dd>One file generation set element is created per day. 12592b15cb3dSCy SchubertA day is 12602b15cb3dSCy Schubertdefined as the period between 00:00 and 24:00 UTC. 12612b15cb3dSCy SchubertThe file set 12622b15cb3dSCy Schubertmember suffix consists of a 12632b15cb3dSCy Schubert. 12642b15cb3dSCy Schubertand a day specification in 12652b15cb3dSCy Schubertthe form 12662b15cb3dSCy Schubert<code>YYYYMMdd</code>. 12672b15cb3dSCy Schubert<code>YYYY</code> 12682b15cb3dSCy Schubertis a 4-digit year number (e.g., 1992). 12692b15cb3dSCy Schubert<code>MM</code> 12702b15cb3dSCy Schubertis a two digit month number. 12712b15cb3dSCy Schubert<code>dd</code> 12722b15cb3dSCy Schubertis a two digit day number. 12732b15cb3dSCy SchubertThus, all information written at 10 December 1992 would end up 12742b15cb3dSCy Schubertin a file named 12752b15cb3dSCy Schubert<kbd>prefix</kbd> 12762b15cb3dSCy Schubert<kbd>filename</kbd>.19921210. 12772b15cb3dSCy Schubert<br><dt><code>week</code><dd>Any file set member contains data related to a certain week of 12782b15cb3dSCy Schuberta year. 12792b15cb3dSCy SchubertThe term week is defined by computing day-of-year 12802b15cb3dSCy Schubertmodulo 7. 12812b15cb3dSCy SchubertElements of such a file generation set are 12822b15cb3dSCy Schubertdistinguished by appending the following suffix to the file set 12832b15cb3dSCy Schubertfilename base: A dot, a 4-digit year number, the letter 12842b15cb3dSCy Schubert<code>W</code>, 12852b15cb3dSCy Schubertand a 2-digit week number. 12862b15cb3dSCy SchubertFor example, information from January, 12872b15cb3dSCy Schubert10th 1992 would end up in a file with suffix 12882b15cb3dSCy Schubert.No . Ns Ar 1992W1 . 12892b15cb3dSCy Schubert<br><dt><code>month</code><dd>One generation file set element is generated per month. 12902b15cb3dSCy SchubertThe 12912b15cb3dSCy Schubertfile name suffix consists of a dot, a 4-digit year number, and 12922b15cb3dSCy Schuberta 2-digit month. 12932b15cb3dSCy Schubert<br><dt><code>year</code><dd>One generation file element is generated per year. 12942b15cb3dSCy SchubertThe filename 12952b15cb3dSCy Schubertsuffix consists of a dot and a 4 digit year number. 12962b15cb3dSCy Schubert<br><dt><code>age</code><dd>This type of file generation sets changes to a new element of 12972b15cb3dSCy Schubertthe file set every 24 hours of server operation. 12982b15cb3dSCy SchubertThe filename 12992b15cb3dSCy Schubertsuffix consists of a dot, the letter 13002b15cb3dSCy Schubert<code>a</code>, 13012b15cb3dSCy Schubertand an 8-digit number. 13022b15cb3dSCy SchubertThis number is taken to be the number of seconds the server is 13032b15cb3dSCy Schubertrunning at the start of the corresponding 24-hour period. 13042b15cb3dSCy SchubertInformation is only written to a file generation by specifying 13052b15cb3dSCy Schubert<code>enable</code>; 13062b15cb3dSCy Schubertoutput is prevented by specifying 13072b15cb3dSCy Schubert<code>disable</code>. 13082b15cb3dSCy Schubert</dl> 13092b15cb3dSCy Schubert <br><dt><code>link</code> | <code>nolink</code><dd>It is convenient to be able to access the current element of a file 13102b15cb3dSCy Schubertgeneration set by a fixed name. 13112b15cb3dSCy SchubertThis feature is enabled by 13122b15cb3dSCy Schubertspecifying 13132b15cb3dSCy Schubert<code>link</code> 13142b15cb3dSCy Schubertand disabled using 13152b15cb3dSCy Schubert<code>nolink</code>. 13162b15cb3dSCy SchubertIf link is specified, a 13172b15cb3dSCy Schuberthard link from the current file set element to a file without 13182b15cb3dSCy Schubertsuffix is created. 13192b15cb3dSCy SchubertWhen there is already a file with this name and 13202b15cb3dSCy Schubertthe number of links of this file is one, it is renamed appending a 13212b15cb3dSCy Schubertdot, the letter 13222b15cb3dSCy Schubert<code>C</code>, 13232b15cb3dSCy Schubertand the pid of the ntpd server process. 13242b15cb3dSCy SchubertWhen the 13252b15cb3dSCy Schubertnumber of links is greater than one, the file is unlinked. 13262b15cb3dSCy SchubertThis 13272b15cb3dSCy Schubertallows the current file to be accessed by a constant name. 13282b15cb3dSCy Schubert<br><dt><code>enable</code> <code>|</code> <code>disable</code><dd>Enables or disables the recording function. 13292b15cb3dSCy Schubert</dl> 13302b15cb3dSCy Schubert </dl> 13312b15cb3dSCy Schubert </dl> 13322b15cb3dSCy Schubert<div class="node"> 13332b15cb3dSCy Schubert<p><hr> 13342b15cb3dSCy Schubert<a name="Access-Control-Support"></a> 13352b15cb3dSCy Schubert<br> 13362b15cb3dSCy Schubert</div> 13372b15cb3dSCy Schubert 13382b15cb3dSCy Schubert<h4 class="subsection">Access Control Support</h4> 13392b15cb3dSCy Schubert 13402b15cb3dSCy Schubert<p>The 13412b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 13422b15cb3dSCy Schubertdaemon implements a general purpose address/mask based restriction 13432b15cb3dSCy Schubertlist. 13442b15cb3dSCy SchubertThe list contains address/match entries sorted first 13452b15cb3dSCy Schubertby increasing address values and and then by increasing mask values. 13462b15cb3dSCy SchubertA match occurs when the bitwise AND of the mask and the packet 13472b15cb3dSCy Schubertsource address is equal to the bitwise AND of the mask and 13482b15cb3dSCy Schubertaddress in the list. 13492b15cb3dSCy SchubertThe list is searched in order with the 13502b15cb3dSCy Schubertlast match found defining the restriction flags associated 13512b15cb3dSCy Schubertwith the entry. 13522b15cb3dSCy SchubertAdditional information and examples can be found in the 13532b15cb3dSCy Schubert"Notes on Configuring NTP and Setting up a NTP Subnet" 13542b15cb3dSCy Schubertpage 13552b15cb3dSCy Schubert(available as part of the HTML documentation 13562b15cb3dSCy Schubertprovided in 13572b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 13582b15cb3dSCy Schubert 13592b15cb3dSCy Schubert <p>The restriction facility was implemented in conformance 13602b15cb3dSCy Schubertwith the access policies for the original NSFnet backbone 13612b15cb3dSCy Schuberttime servers. 13622b15cb3dSCy SchubertLater the facility was expanded to deflect 13632b15cb3dSCy Schubertcryptographic and clogging attacks. 13642b15cb3dSCy SchubertWhile this facility may 13652b15cb3dSCy Schubertbe useful for keeping unwanted or broken or malicious clients 13662b15cb3dSCy Schubertfrom congesting innocent servers, it should not be considered 13672b15cb3dSCy Schubertan alternative to the NTP authentication facilities. 13682b15cb3dSCy SchubertSource address based restrictions are easily circumvented 13692b15cb3dSCy Schubertby a determined cracker. 13702b15cb3dSCy Schubert 13712b15cb3dSCy Schubert <p>Clients can be denied service because they are explicitly 13722b15cb3dSCy Schubertincluded in the restrict list created by the restrict command 13732b15cb3dSCy Schubertor implicitly as the result of cryptographic or rate limit 13742b15cb3dSCy Schubertviolations. 13752b15cb3dSCy SchubertCryptographic violations include certificate 13762b15cb3dSCy Schubertor identity verification failure; rate limit violations generally 13772b15cb3dSCy Schubertresult from defective NTP implementations that send packets 13782b15cb3dSCy Schubertat abusive rates. 13792b15cb3dSCy SchubertSome violations cause denied service 13802b15cb3dSCy Schubertonly for the offending packet, others cause denied service 13812b15cb3dSCy Schubertfor a timed period and others cause the denied service for 13822b15cb3dSCy Schubertan indefinate period. 13832b15cb3dSCy SchubertWhen a client or network is denied access 13842b15cb3dSCy Schubertfor an indefinate period, the only way at present to remove 13852b15cb3dSCy Schubertthe restrictions is by restarting the server. 13862b15cb3dSCy Schubert 13872b15cb3dSCy Schubert<h5 class="subsubsection">The Kiss-of-Death Packet</h5> 13882b15cb3dSCy Schubert 13892b15cb3dSCy Schubert<p>Ordinarily, packets denied service are simply dropped with no 13902b15cb3dSCy Schubertfurther action except incrementing statistics counters. 13912b15cb3dSCy SchubertSometimes a 13922b15cb3dSCy Schubertmore proactive response is needed, such as a server message that 13932b15cb3dSCy Schubertexplicitly requests the client to stop sending and leave a message 13942b15cb3dSCy Schubertfor the system operator. 13952b15cb3dSCy SchubertA special packet format has been created 13962b15cb3dSCy Schubertfor this purpose called the "kiss-of-death" (KoD) packet. 13972b15cb3dSCy SchubertKoD packets have the leap bits set unsynchronized and stratum set 13982b15cb3dSCy Schubertto zero and the reference identifier field set to a four-byte 13992b15cb3dSCy SchubertASCII code. 14002b15cb3dSCy SchubertIf the 14012b15cb3dSCy Schubert<code>noserve</code> 14022b15cb3dSCy Schubertor 14032b15cb3dSCy Schubert<code>notrust</code> 14042b15cb3dSCy Schubertflag of the matching restrict list entry is set, 14052b15cb3dSCy Schubertthe code is "DENY"; if the 14062b15cb3dSCy Schubert<code>limited</code> 14072b15cb3dSCy Schubertflag is set and the rate limit 14082b15cb3dSCy Schubertis exceeded, the code is "RATE". 14092b15cb3dSCy SchubertFinally, if a cryptographic violation occurs, the code is "CRYP". 14102b15cb3dSCy Schubert 14112b15cb3dSCy Schubert <p>A client receiving a KoD performs a set of sanity checks to 14122b15cb3dSCy Schubertminimize security exposure, then updates the stratum and 14132b15cb3dSCy Schubertreference identifier peer variables, sets the access 14142b15cb3dSCy Schubertdenied (TEST4) bit in the peer flash variable and sends 14152b15cb3dSCy Schuberta message to the log. 14162b15cb3dSCy SchubertAs long as the TEST4 bit is set, 14172b15cb3dSCy Schubertthe client will send no further packets to the server. 14182b15cb3dSCy SchubertThe only way at present to recover from this condition is 14192b15cb3dSCy Schubertto restart the protocol at both the client and server. 14202b15cb3dSCy SchubertThis 14212b15cb3dSCy Schuberthappens automatically at the client when the association times out. 14222b15cb3dSCy SchubertIt will happen at the server only if the server operator cooperates. 14232b15cb3dSCy Schubert 14242b15cb3dSCy Schubert<h5 class="subsubsection">Access Control Commands</h5> 14252b15cb3dSCy Schubert 14262b15cb3dSCy Schubert <dl> 14272b15cb3dSCy Schubert<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 14282b15cb3dSCy Schubert<code>limited</code> 14292b15cb3dSCy Schubertfacility which protects the server from 14302b15cb3dSCy Schubertclient abuse. 14312b15cb3dSCy SchubertThe 14322b15cb3dSCy Schubert<code>average</code> 14332b15cb3dSCy Schubertsubcommand specifies the minimum average packet 14342b15cb3dSCy Schubertspacing, while the 14352b15cb3dSCy Schubert<code>minimum</code> 14362b15cb3dSCy Schubertsubcommand specifies the minimum packet spacing. 14372b15cb3dSCy SchubertPackets that violate these minima are discarded 14382b15cb3dSCy Schubertand a kiss-o'-death packet returned if enabled. 14392b15cb3dSCy SchubertThe default 14402b15cb3dSCy Schubertminimum average and minimum are 5 and 2, respectively. 14412b15cb3dSCy SchubertThe monitor subcommand specifies the probability of discard 14422b15cb3dSCy Schubertfor packets that overflow the rate-control window. 14432b15cb3dSCy Schubert<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 14442b15cb3dSCy Schubert<kbd>address</kbd> 14452b15cb3dSCy Schubertargument expressed in 14462b15cb3dSCy Schubertdotted-quad form is the address of a host or network. 14472b15cb3dSCy SchubertAlternatively, the 14482b15cb3dSCy Schubert<kbd>address</kbd> 14492b15cb3dSCy Schubertargument can be a valid host DNS name. 14502b15cb3dSCy SchubertThe 14512b15cb3dSCy Schubert<kbd>mask</kbd> 14522b15cb3dSCy Schubertargument expressed in dotted-quad form defaults to 14532b15cb3dSCy Schubert<code>255.255.255.255</code>, 14542b15cb3dSCy Schubertmeaning that the 14552b15cb3dSCy Schubert<kbd>address</kbd> 14562b15cb3dSCy Schubertis treated as the address of an individual host. 14572b15cb3dSCy SchubertA default entry (address 14582b15cb3dSCy Schubert<code>0.0.0.0</code>, 14592b15cb3dSCy Schubertmask 14602b15cb3dSCy Schubert<code>0.0.0.0</code>) 14612b15cb3dSCy Schubertis always included and is always the first entry in the list. 14622b15cb3dSCy SchubertNote that text string 14632b15cb3dSCy Schubert<code>default</code>, 14642b15cb3dSCy Schubertwith no mask option, may 14652b15cb3dSCy Schubertbe used to indicate the default entry. 14662b15cb3dSCy SchubertIn the current implementation, 14672b15cb3dSCy Schubert<code>flag</code> 14682b15cb3dSCy Schubertalways 14692b15cb3dSCy Schubertrestricts access, i.e., an entry with no flags indicates that free 14702b15cb3dSCy Schubertaccess to the server is to be given. 14712b15cb3dSCy SchubertThe flags are not orthogonal, 14722b15cb3dSCy Schubertin that more restrictive flags will often make less restrictive 14732b15cb3dSCy Schubertones redundant. 14742b15cb3dSCy SchubertThe flags can generally be classed into two 14752b15cb3dSCy Schubertcategories, those which restrict time service and those which 14762b15cb3dSCy Schubertrestrict informational queries and attempts to do run-time 14772b15cb3dSCy Schubertreconfiguration of the server. 14782b15cb3dSCy SchubertOne or more of the following flags 14792b15cb3dSCy Schubertmay be specified: 14802b15cb3dSCy Schubert <dl> 14812b15cb3dSCy Schubert<dt><code>ignore</code><dd>Deny packets of all kinds, including 14822b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 14832b15cb3dSCy Schubertand 14842b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 14852b15cb3dSCy Schubertqueries. 14862b15cb3dSCy Schubert<br><dt><code>kod</code><dd>If this flag is set when an access violation occurs, a kiss-o'-death 14872b15cb3dSCy Schubert(KoD) packet is sent. 14882b15cb3dSCy SchubertKoD packets are rate limited to no more than one 14892b15cb3dSCy Schubertper second. 14902b15cb3dSCy SchubertIf another KoD packet occurs within one second after the 14912b15cb3dSCy Schubertlast one, the packet is dropped. 14922b15cb3dSCy Schubert<br><dt><code>limited</code><dd>Deny service if the packet spacing violates the lower limits specified 14932b15cb3dSCy Schubertin the discard command. 14942b15cb3dSCy SchubertA history of clients is kept using the 14952b15cb3dSCy Schubertmonitoring capability of 14962b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code>. 14972b15cb3dSCy SchubertThus, monitoring is always active as 14982b15cb3dSCy Schubertlong as there is a restriction entry with the 14992b15cb3dSCy Schubert<code>limited</code> 15002b15cb3dSCy Schubertflag. 15012b15cb3dSCy Schubert<br><dt><code>lowpriotrap</code><dd>Declare traps set by matching hosts to be low priority. 15022b15cb3dSCy SchubertThe 15032b15cb3dSCy Schubertnumber of traps a server can maintain is limited (the current limit 15042b15cb3dSCy Schubertis 3). 15052b15cb3dSCy SchubertTraps are usually assigned on a first come, first served 15062b15cb3dSCy Schubertbasis, with later trap requestors being denied service. 15072b15cb3dSCy SchubertThis flag 15082b15cb3dSCy Schubertmodifies the assignment algorithm by allowing low priority traps to 15092b15cb3dSCy Schubertbe overridden by later requests for normal priority traps. 15102b15cb3dSCy Schubert<br><dt><code>nomodify</code><dd>Deny 15112b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15122b15cb3dSCy Schubertand 15132b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15142b15cb3dSCy Schubertqueries which attempt to modify the state of the 15152b15cb3dSCy Schubertserver (i.e., run time reconfiguration). 15162b15cb3dSCy SchubertQueries which return 15172b15cb3dSCy Schubertinformation are permitted. 15182b15cb3dSCy Schubert<br><dt><code>noquery</code><dd>Deny 15192b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15202b15cb3dSCy Schubertand 15212b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15222b15cb3dSCy Schubertqueries. 15232b15cb3dSCy SchubertTime service is not affected. 15242b15cb3dSCy Schubert<br><dt><code>nopeer</code><dd>Deny packets which would result in mobilizing a new association. 15252b15cb3dSCy SchubertThis 15262b15cb3dSCy Schubertincludes broadcast and symmetric active packets when a configured 15272b15cb3dSCy Schubertassociation does not exist. 15282b15cb3dSCy SchubertIt also includes 15292b15cb3dSCy Schubert<code>pool</code> 15302b15cb3dSCy Schubertassociations, so if you want to use servers from a 15312b15cb3dSCy Schubert<code>pool</code> 15322b15cb3dSCy Schubertdirective and also want to use 15332b15cb3dSCy Schubert<code>nopeer</code> 15342b15cb3dSCy Schubertby default, you'll want a 15352b15cb3dSCy Schubert<code>restrict source ...</code> <code>line</code> <code>as</code> <code>well</code> <code>that</code> <code>does</code> 15362b15cb3dSCy Schubert<br><dt>not<dd>include the 15372b15cb3dSCy Schubert<code>nopeer</code> 15382b15cb3dSCy Schubertdirective. 15392b15cb3dSCy Schubert<br><dt><code>noserve</code><dd>Deny all packets except 15402b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15412b15cb3dSCy Schubertand 15422b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15432b15cb3dSCy Schubertqueries. 15442b15cb3dSCy Schubert<br><dt><code>notrap</code><dd>Decline to provide mode 6 control message trap service to matching 15452b15cb3dSCy Schuberthosts. 15462b15cb3dSCy SchubertThe trap service is a subsystem of the ntpdq control message 15472b15cb3dSCy Schubertprotocol which is intended for use by remote event logging programs. 15482b15cb3dSCy Schubert<br><dt><code>notrust</code><dd>Deny service unless the packet is cryptographically authenticated. 15492b15cb3dSCy Schubert<br><dt><code>ntpport</code><dd>This is actually a match algorithm modifier, rather than a 15502b15cb3dSCy Schubertrestriction flag. 15512b15cb3dSCy SchubertIts presence causes the restriction entry to be 15522b15cb3dSCy Schubertmatched only if the source port in the packet is the standard NTP 15532b15cb3dSCy SchubertUDP port (123). 15542b15cb3dSCy SchubertBoth 15552b15cb3dSCy Schubert<code>ntpport</code> 15562b15cb3dSCy Schubertand 15572b15cb3dSCy Schubert<code>non-ntpport</code> 15582b15cb3dSCy Schubertmay 15592b15cb3dSCy Schubertbe specified. 15602b15cb3dSCy SchubertThe 15612b15cb3dSCy Schubert<code>ntpport</code> 15622b15cb3dSCy Schubertis considered more specific and 15632b15cb3dSCy Schubertis sorted later in the list. 15642b15cb3dSCy Schubert<br><dt><code>version</code><dd>Deny packets that do not match the current NTP version. 15652b15cb3dSCy Schubert</dl> 15662b15cb3dSCy Schubert 15672b15cb3dSCy Schubert <p>Default restriction list entries with the flags ignore, interface, 15682b15cb3dSCy Schubertntpport, for each of the local host's interface addresses are 15692b15cb3dSCy Schubertinserted into the table at startup to prevent the server 15702b15cb3dSCy Schubertfrom attempting to synchronize to its own time. 15712b15cb3dSCy SchubertA default entry is also always present, though if it is 15722b15cb3dSCy Schubertotherwise unconfigured; no flags are associated 15732b15cb3dSCy Schubertwith the default entry (i.e., everything besides your own 15742b15cb3dSCy SchubertNTP server is unrestricted). 15752b15cb3dSCy Schubert</dl> 15762b15cb3dSCy Schubert<div class="node"> 15772b15cb3dSCy Schubert<p><hr> 15782b15cb3dSCy Schubert<a name="Automatic-NTP-Configuration-Options"></a> 15792b15cb3dSCy Schubert<br> 15802b15cb3dSCy Schubert</div> 15812b15cb3dSCy Schubert 15822b15cb3dSCy Schubert<h4 class="subsection">Automatic NTP Configuration Options</h4> 15832b15cb3dSCy Schubert 15842b15cb3dSCy Schubert<h5 class="subsubsection">Manycasting</h5> 15852b15cb3dSCy Schubert 15862b15cb3dSCy Schubert<p>Manycasting is a automatic discovery and configuration paradigm 15872b15cb3dSCy Schubertnew to NTPv4. 15882b15cb3dSCy SchubertIt is intended as a means for a multicast client 15892b15cb3dSCy Schubertto troll the nearby network neighborhood to find cooperating 15902b15cb3dSCy Schubertmanycast servers, validate them using cryptographic means 15912b15cb3dSCy Schubertand evaluate their time values with respect to other servers 15922b15cb3dSCy Schubertthat might be lurking in the vicinity. 15932b15cb3dSCy SchubertThe intended result is that each manycast client mobilizes 15942b15cb3dSCy Schubertclient associations with some number of the "best" 15952b15cb3dSCy Schubertof the nearby manycast servers, yet automatically reconfigures 15962b15cb3dSCy Schubertto sustain this number of servers should one or another fail. 15972b15cb3dSCy Schubert 15982b15cb3dSCy Schubert <p>Note that the manycasting paradigm does not coincide 15992b15cb3dSCy Schubertwith the anycast paradigm described in RFC-1546, 16002b15cb3dSCy Schubertwhich is designed to find a single server from a clique 16012b15cb3dSCy Schubertof servers providing the same service. 16022b15cb3dSCy SchubertThe manycast paradigm is designed to find a plurality 16032b15cb3dSCy Schubertof redundant servers satisfying defined optimality criteria. 16042b15cb3dSCy Schubert 16052b15cb3dSCy Schubert <p>Manycasting can be used with either symmetric key 16062b15cb3dSCy Schubertor public key cryptography. 16072b15cb3dSCy SchubertThe public key infrastructure (PKI) 16082b15cb3dSCy Schubertoffers the best protection against compromised keys 16092b15cb3dSCy Schubertand is generally considered stronger, at least with relatively 16102b15cb3dSCy Schubertlarge key sizes. 16112b15cb3dSCy SchubertIt is implemented using the Autokey protocol and 16122b15cb3dSCy Schubertthe OpenSSL cryptographic library available from 16132b15cb3dSCy Schubert<code>http://www.openssl.org/</code>. 16142b15cb3dSCy SchubertThe library can also be used with other NTPv4 modes 16152b15cb3dSCy Schubertas well and is highly recommended, especially for broadcast modes. 16162b15cb3dSCy Schubert 16172b15cb3dSCy Schubert <p>A persistent manycast client association is configured 16182b15cb3dSCy Schubertusing the manycastclient command, which is similar to the 16192b15cb3dSCy Schubertserver command but with a multicast (IPv4 class 16202b15cb3dSCy Schubert<code>D</code> 16212b15cb3dSCy Schubertor IPv6 prefix 16222b15cb3dSCy Schubert<code>FF</code>) 16232b15cb3dSCy Schubertgroup address. 16242b15cb3dSCy SchubertThe IANA has designated IPv4 address 224.1.1.1 16252b15cb3dSCy Schubertand IPv6 address FF05::101 (site local) for NTP. 16262b15cb3dSCy SchubertWhen more servers are needed, it broadcasts manycast 16272b15cb3dSCy Schubertclient messages to this address at the minimum feasible rate 16282b15cb3dSCy Schubertand minimum feasible time-to-live (TTL) hops, depending 16292b15cb3dSCy Schuberton how many servers have already been found. 16302b15cb3dSCy SchubertThere can be as many manycast client associations 16312b15cb3dSCy Schubertas different group address, each one serving as a template 16322b15cb3dSCy Schubertfor a future ephemeral unicast client/server association. 16332b15cb3dSCy Schubert 16342b15cb3dSCy Schubert <p>Manycast servers configured with the 16352b15cb3dSCy Schubert<code>manycastserver</code> 16362b15cb3dSCy Schubertcommand listen on the specified group address for manycast 16372b15cb3dSCy Schubertclient messages. 16382b15cb3dSCy SchubertNote the distinction between manycast client, 16392b15cb3dSCy Schubertwhich actively broadcasts messages, and manycast server, 16402b15cb3dSCy Schubertwhich passively responds to them. 16412b15cb3dSCy SchubertIf a manycast server is 16422b15cb3dSCy Schubertin scope of the current TTL and is itself synchronized 16432b15cb3dSCy Schubertto a valid source and operating at a stratum level equal 16442b15cb3dSCy Schubertto or lower than the manycast client, it replies to the 16452b15cb3dSCy Schubertmanycast client message with an ordinary unicast server message. 16462b15cb3dSCy Schubert 16472b15cb3dSCy Schubert <p>The manycast client receiving this message mobilizes 16482b15cb3dSCy Schubertan ephemeral client/server association according to the 16492b15cb3dSCy Schubertmatching manycast client template, but only if cryptographically 16502b15cb3dSCy Schubertauthenticated and the server stratum is less than or equal 16512b15cb3dSCy Schubertto the client stratum. 16522b15cb3dSCy SchubertAuthentication is explicitly required 16532b15cb3dSCy Schubertand either symmetric key or public key (Autokey) can be used. 16542b15cb3dSCy SchubertThen, the client polls the server at its unicast address 16552b15cb3dSCy Schubertin burst mode in order to reliably set the host clock 16562b15cb3dSCy Schubertand validate the source. 16572b15cb3dSCy SchubertThis normally results 16582b15cb3dSCy Schubertin a volley of eight client/server at 2-s intervals 16592b15cb3dSCy Schubertduring which both the synchronization and cryptographic 16602b15cb3dSCy Schubertprotocols run concurrently. 16612b15cb3dSCy SchubertFollowing the volley, 16622b15cb3dSCy Schubertthe client runs the NTP intersection and clustering 16632b15cb3dSCy Schubertalgorithms, which act to discard all but the "best" 16642b15cb3dSCy Schubertassociations according to stratum and synchronization 16652b15cb3dSCy Schubertdistance. 16662b15cb3dSCy SchubertThe surviving associations then continue 16672b15cb3dSCy Schubertin ordinary client/server mode. 16682b15cb3dSCy Schubert 16692b15cb3dSCy Schubert <p>The manycast client polling strategy is designed to reduce 16702b15cb3dSCy Schubertas much as possible the volume of manycast client messages 16712b15cb3dSCy Schubertand the effects of implosion due to near-simultaneous 16722b15cb3dSCy Schubertarrival of manycast server messages. 16732b15cb3dSCy SchubertThe strategy is determined by the 16742b15cb3dSCy Schubert<code>manycastclient</code>, 16752b15cb3dSCy Schubert<code>tos</code> 16762b15cb3dSCy Schubertand 16772b15cb3dSCy Schubert<code>ttl</code> 16782b15cb3dSCy Schubertconfiguration commands. 16792b15cb3dSCy SchubertThe manycast poll interval is 16802b15cb3dSCy Schubertnormally eight times the system poll interval, 16812b15cb3dSCy Schubertwhich starts out at the 16822b15cb3dSCy Schubert<code>minpoll</code> 16832b15cb3dSCy Schubertvalue specified in the 16842b15cb3dSCy Schubert<code>manycastclient</code>, 16852b15cb3dSCy Schubertcommand and, under normal circumstances, increments to the 16862b15cb3dSCy Schubert<code>maxpolll</code> 16872b15cb3dSCy Schubertvalue specified in this command. 16882b15cb3dSCy SchubertInitially, the TTL is 16892b15cb3dSCy Schubertset at the minimum hops specified by the ttl command. 16902b15cb3dSCy SchubertAt each retransmission the TTL is increased until reaching 16912b15cb3dSCy Schubertthe maximum hops specified by this command or a sufficient 16922b15cb3dSCy Schubertnumber client associations have been found. 16932b15cb3dSCy SchubertFurther retransmissions use the same TTL. 16942b15cb3dSCy Schubert 16952b15cb3dSCy Schubert <p>The quality and reliability of the suite of associations 16962b15cb3dSCy Schubertdiscovered by the manycast client is determined by the NTP 16972b15cb3dSCy Schubertmitigation algorithms and the 16982b15cb3dSCy Schubert<code>minclock</code> 16992b15cb3dSCy Schubertand 17002b15cb3dSCy Schubert<code>minsane</code> 17012b15cb3dSCy Schubertvalues specified in the 17022b15cb3dSCy Schubert<code>tos</code> 17032b15cb3dSCy Schubertconfiguration command. 17042b15cb3dSCy SchubertAt least 17052b15cb3dSCy Schubert<code>minsane</code> 17062b15cb3dSCy Schubertcandidate servers must be available and the mitigation 17072b15cb3dSCy Schubertalgorithms produce at least 17082b15cb3dSCy Schubert<code>minclock</code> 17092b15cb3dSCy Schubertsurvivors in order to synchronize the clock. 17102b15cb3dSCy SchubertByzantine agreement principles require at least four 17112b15cb3dSCy Schubertcandidates in order to correctly discard a single falseticker. 17122b15cb3dSCy SchubertFor legacy purposes, 17132b15cb3dSCy Schubert<code>minsane</code> 17142b15cb3dSCy Schubertdefaults to 1 and 17152b15cb3dSCy Schubert<code>minclock</code> 17162b15cb3dSCy Schubertdefaults to 3. 17172b15cb3dSCy SchubertFor manycast service 17182b15cb3dSCy Schubert<code>minsane</code> 17192b15cb3dSCy Schubertshould be explicitly set to 4, assuming at least that 17202b15cb3dSCy Schubertnumber of servers are available. 17212b15cb3dSCy Schubert 17222b15cb3dSCy Schubert <p>If at least 17232b15cb3dSCy Schubert<code>minclock</code> 17242b15cb3dSCy Schubertservers are found, the manycast poll interval is immediately 17252b15cb3dSCy Schubertset to eight times 17262b15cb3dSCy Schubert<code>maxpoll</code>. 17272b15cb3dSCy SchubertIf less than 17282b15cb3dSCy Schubert<code>minclock</code> 17292b15cb3dSCy Schubertservers are found when the TTL has reached the maximum hops, 17302b15cb3dSCy Schubertthe manycast poll interval is doubled. 17312b15cb3dSCy SchubertFor each transmission 17322b15cb3dSCy Schubertafter that, the poll interval is doubled again until 17332b15cb3dSCy Schubertreaching the maximum of eight times 17342b15cb3dSCy Schubert<code>maxpoll</code>. 17352b15cb3dSCy SchubertFurther transmissions use the same poll interval and 17362b15cb3dSCy SchubertTTL values. 17372b15cb3dSCy SchubertNote that while all this is going on, 17382b15cb3dSCy Schuberteach client/server association found is operating normally 17392b15cb3dSCy Schubertit the system poll interval. 17402b15cb3dSCy Schubert 17412b15cb3dSCy Schubert <p>Administratively scoped multicast boundaries are normally 17422b15cb3dSCy Schubertspecified by the network router configuration and, 17432b15cb3dSCy Schubertin the case of IPv6, the link/site scope prefix. 17442b15cb3dSCy SchubertBy default, the increment for TTL hops is 32 starting 17452b15cb3dSCy Schubertfrom 31; however, the 17462b15cb3dSCy Schubert<code>ttl</code> 17472b15cb3dSCy Schubertconfiguration command can be 17482b15cb3dSCy Schubertused to modify the values to match the scope rules. 17492b15cb3dSCy Schubert 17502b15cb3dSCy Schubert <p>It is often useful to narrow the range of acceptable 17512b15cb3dSCy Schubertservers which can be found by manycast client associations. 17522b15cb3dSCy SchubertBecause manycast servers respond only when the client 17532b15cb3dSCy Schubertstratum is equal to or greater than the server stratum, 17542b15cb3dSCy Schubertprimary (stratum 1) servers fill find only primary servers 17552b15cb3dSCy Schubertin TTL range, which is probably the most common objective. 17562b15cb3dSCy SchubertHowever, unless configured otherwise, all manycast clients 17572b15cb3dSCy Schubertin TTL range will eventually find all primary servers 17582b15cb3dSCy Schubertin TTL range, which is probably not the most common 17592b15cb3dSCy Schubertobjective in large networks. 17602b15cb3dSCy SchubertThe 17612b15cb3dSCy Schubert<code>tos</code> 17622b15cb3dSCy Schubertcommand can be used to modify this behavior. 17632b15cb3dSCy SchubertServers with stratum below 17642b15cb3dSCy Schubert<code>floor</code> 17652b15cb3dSCy Schubertor above 17662b15cb3dSCy Schubert<code>ceiling</code> 17672b15cb3dSCy Schubertspecified in the 17682b15cb3dSCy Schubert<code>tos</code> 17692b15cb3dSCy Schubertcommand are strongly discouraged during the selection 17702b15cb3dSCy Schubertprocess; however, these servers may be temporally 17712b15cb3dSCy Schubertaccepted if the number of servers within TTL range is 17722b15cb3dSCy Schubertless than 17732b15cb3dSCy Schubert<code>minclock</code>. 17742b15cb3dSCy Schubert 17752b15cb3dSCy Schubert <p>The above actions occur for each manycast client message, 17762b15cb3dSCy Schubertwhich repeats at the designated poll interval. 17772b15cb3dSCy SchubertHowever, once the ephemeral client association is mobilized, 17782b15cb3dSCy Schubertsubsequent manycast server replies are discarded, 17792b15cb3dSCy Schubertsince that would result in a duplicate association. 17802b15cb3dSCy SchubertIf during a poll interval the number of client associations 17812b15cb3dSCy Schubertfalls below 17822b15cb3dSCy Schubert<code>minclock</code>, 17832b15cb3dSCy Schubertall manycast client prototype associations are reset 17842b15cb3dSCy Schubertto the initial poll interval and TTL hops and operation 17852b15cb3dSCy Schubertresumes from the beginning. 17862b15cb3dSCy SchubertIt is important to avoid 17872b15cb3dSCy Schubertfrequent manycast client messages, since each one requires 17882b15cb3dSCy Schubertall manycast servers in TTL range to respond. 17892b15cb3dSCy SchubertThe result could well be an implosion, either minor or major, 17902b15cb3dSCy Schubertdepending on the number of servers in range. 17912b15cb3dSCy SchubertThe recommended value for 17922b15cb3dSCy Schubert<code>maxpoll</code> 17932b15cb3dSCy Schubertis 12 (4,096 s). 17942b15cb3dSCy Schubert 17952b15cb3dSCy Schubert <p>It is possible and frequently useful to configure a host 17962b15cb3dSCy Schubertas both manycast client and manycast server. 17972b15cb3dSCy SchubertA number of hosts configured this way and sharing a common 17982b15cb3dSCy Schubertgroup address will automatically organize themselves 17992b15cb3dSCy Schubertin an optimum configuration based on stratum and 18002b15cb3dSCy Schubertsynchronization distance. 18012b15cb3dSCy SchubertFor example, consider an NTP 18022b15cb3dSCy Schubertsubnet of two primary servers and a hundred or more 18032b15cb3dSCy Schubertdependent clients. 18042b15cb3dSCy SchubertWith two exceptions, all servers 18052b15cb3dSCy Schubertand clients have identical configuration files including both 18062b15cb3dSCy Schubert<code>multicastclient</code> 18072b15cb3dSCy Schubertand 18082b15cb3dSCy Schubert<code>multicastserver</code> 18092b15cb3dSCy Schubertcommands using, for instance, multicast group address 18102b15cb3dSCy Schubert239.1.1.1. 18112b15cb3dSCy SchubertThe only exception is that each primary server 18122b15cb3dSCy Schubertconfiguration file must include commands for the primary 18132b15cb3dSCy Schubertreference source such as a GPS receiver. 18142b15cb3dSCy Schubert 18152b15cb3dSCy Schubert <p>The remaining configuration files for all secondary 18162b15cb3dSCy Schubertservers and clients have the same contents, except for the 18172b15cb3dSCy Schubert<code>tos</code> 18182b15cb3dSCy Schubertcommand, which is specific for each stratum level. 18192b15cb3dSCy SchubertFor stratum 1 and stratum 2 servers, that command is 18202b15cb3dSCy Schubertnot necessary. 18212b15cb3dSCy SchubertFor stratum 3 and above servers the 18222b15cb3dSCy Schubert<code>floor</code> 18232b15cb3dSCy Schubertvalue is set to the intended stratum number. 18242b15cb3dSCy SchubertThus, all stratum 3 configuration files are identical, 18252b15cb3dSCy Schubertall stratum 4 files are identical and so forth. 18262b15cb3dSCy Schubert 18272b15cb3dSCy Schubert <p>Once operations have stabilized in this scenario, 18282b15cb3dSCy Schubertthe primary servers will find the primary reference source 18292b15cb3dSCy Schubertand each other, since they both operate at the same 18302b15cb3dSCy Schubertstratum (1), but not with any secondary server or client, 18312b15cb3dSCy Schubertsince these operate at a higher stratum. 18322b15cb3dSCy SchubertThe secondary 18332b15cb3dSCy Schubertservers will find the servers at the same stratum level. 18342b15cb3dSCy SchubertIf one of the primary servers loses its GPS receiver, 18352b15cb3dSCy Schubertit will continue to operate as a client and other clients 18362b15cb3dSCy Schubertwill time out the corresponding association and 18372b15cb3dSCy Schubertre-associate accordingly. 18382b15cb3dSCy Schubert 18392b15cb3dSCy Schubert <p>Some administrators prefer to avoid running 18402b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 18412b15cb3dSCy Schubertcontinuously and run either 1842*9034852cSGleb Smirnoff<code>sntp(1sntpmdoc)</code> 18432b15cb3dSCy Schubertor 18442b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 18452b15cb3dSCy Schubert<code>-q</code> 18462b15cb3dSCy Schubertas a cron job. 18472b15cb3dSCy SchubertIn either case the servers must be 18482b15cb3dSCy Schubertconfigured in advance and the program fails if none are 18492b15cb3dSCy Schubertavailable when the cron job runs. 18502b15cb3dSCy SchubertA really slick 18512b15cb3dSCy Schubertapplication of manycast is with 18522b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 18532b15cb3dSCy Schubert<code>-q</code>. 18542b15cb3dSCy SchubertThe program wakes up, scans the local landscape looking 18552b15cb3dSCy Schubertfor the usual suspects, selects the best from among 18562b15cb3dSCy Schubertthe rascals, sets the clock and then departs. 18572b15cb3dSCy SchubertServers do not have to be configured in advance and 18582b15cb3dSCy Schubertall clients throughout the network can have the same 18592b15cb3dSCy Schubertconfiguration file. 18602b15cb3dSCy Schubert 18612b15cb3dSCy Schubert<h5 class="subsubsection">Manycast Interactions with Autokey</h5> 18622b15cb3dSCy Schubert 18632b15cb3dSCy Schubert<p>Each time a manycast client sends a client mode packet 18642b15cb3dSCy Schubertto a multicast group address, all manycast servers 18652b15cb3dSCy Schubertin scope generate a reply including the host name 18662b15cb3dSCy Schubertand status word. 18672b15cb3dSCy SchubertThe manycast clients then run 18682b15cb3dSCy Schubertthe Autokey protocol, which collects and verifies 18692b15cb3dSCy Schubertall certificates involved. 18702b15cb3dSCy SchubertFollowing the burst interval 18712b15cb3dSCy Schubertall but three survivors are cast off, 18722b15cb3dSCy Schubertbut the certificates remain in the local cache. 18732b15cb3dSCy SchubertIt often happens that several complete signing trails 18742b15cb3dSCy Schubertfrom the client to the primary servers are collected in this way. 18752b15cb3dSCy Schubert 18762b15cb3dSCy Schubert <p>About once an hour or less often if the poll interval 18772b15cb3dSCy Schubertexceeds this, the client regenerates the Autokey key list. 18782b15cb3dSCy SchubertThis is in general transparent in client/server mode. 18792b15cb3dSCy SchubertHowever, about once per day the server private value 18802b15cb3dSCy Schubertused to generate cookies is refreshed along with all 18812b15cb3dSCy Schubertmanycast client associations. 18822b15cb3dSCy SchubertIn this case all 18832b15cb3dSCy Schubertcryptographic values including certificates is refreshed. 18842b15cb3dSCy SchubertIf a new certificate has been generated since 18852b15cb3dSCy Schubertthe last refresh epoch, it will automatically revoke 18862b15cb3dSCy Schubertall prior certificates that happen to be in the 18872b15cb3dSCy Schubertcertificate cache. 18882b15cb3dSCy SchubertAt the same time, the manycast 18892b15cb3dSCy Schubertscheme starts all over from the beginning and 18902b15cb3dSCy Schubertthe expanding ring shrinks to the minimum and increments 18912b15cb3dSCy Schubertfrom there while collecting all servers in scope. 18922b15cb3dSCy Schubert 18932b15cb3dSCy Schubert<h5 class="subsubsection">Manycast Options</h5> 18942b15cb3dSCy Schubert 18952b15cb3dSCy Schubert <dl> 18962b15cb3dSCy Schubert<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 18972b15cb3dSCy Schubertalgorithms. 18982b15cb3dSCy SchubertIt can be used to select the quality and 18992b15cb3dSCy Schubertquantity of peers used to synchronize the system clock 19002b15cb3dSCy Schubertand is most useful in manycast mode. 19012b15cb3dSCy SchubertThe variables operate 19022b15cb3dSCy Schubertas follows: 19032b15cb3dSCy Schubert <dl> 19042b15cb3dSCy Schubert<dt><code>ceiling</code> <kbd>ceiling</kbd><dd>Peers with strata above 19052b15cb3dSCy Schubert<code>ceiling</code> 19062b15cb3dSCy Schubertwill be discarded if there are at least 19072b15cb3dSCy Schubert<code>minclock</code> 19082b15cb3dSCy Schubertpeers remaining. 19092b15cb3dSCy SchubertThis value defaults to 15, but can be changed 19102b15cb3dSCy Schubertto any number from 1 to 15. 19112b15cb3dSCy Schubert<br><dt><code>cohort</code> <code>{0 | 1}</code><dd>This is a binary flag which enables (0) or disables (1) 19122b15cb3dSCy Schubertmanycast server replies to manycast clients with the same 19132b15cb3dSCy Schubertstratum level. 19142b15cb3dSCy SchubertThis is useful to reduce implosions where 19152b15cb3dSCy Schubertlarge numbers of clients with the same stratum level 19162b15cb3dSCy Schubertare present. 19172b15cb3dSCy SchubertThe default is to enable these replies. 19182b15cb3dSCy Schubert<br><dt><code>floor</code> <kbd>floor</kbd><dd>Peers with strata below 19192b15cb3dSCy Schubert<code>floor</code> 19202b15cb3dSCy Schubertwill be discarded if there are at least 19212b15cb3dSCy Schubert<code>minclock</code> 19222b15cb3dSCy Schubertpeers remaining. 19232b15cb3dSCy SchubertThis value defaults to 1, but can be changed 19242b15cb3dSCy Schubertto any number from 1 to 15. 1925*9034852cSGleb Smirnoff<br><dt><code>minclock</code> <kbd>minclock</kbd><dd>The clustering algorithm repeatedly casts out outlier 19262b15cb3dSCy Schubertassociations until no more than 19272b15cb3dSCy Schubert<code>minclock</code> 19282b15cb3dSCy Schubertassociations remain. 19292b15cb3dSCy SchubertThis value defaults to 3, 19302b15cb3dSCy Schubertbut can be changed to any number from 1 to the number of 19312b15cb3dSCy Schubertconfigured sources. 19322b15cb3dSCy Schubert<br><dt><code>minsane</code> <kbd>minsane</kbd><dd>This is the minimum number of candidates available 19332b15cb3dSCy Schubertto the clock selection algorithm in order to produce 19342b15cb3dSCy Schubertone or more truechimers for the clustering algorithm. 19352b15cb3dSCy SchubertIf fewer than this number are available, the clock is 19362b15cb3dSCy Schubertundisciplined and allowed to run free. 19372b15cb3dSCy SchubertThe default is 1 19382b15cb3dSCy Schubertfor legacy purposes. 19392b15cb3dSCy SchubertHowever, according to principles of 19402b15cb3dSCy SchubertByzantine agreement, 19412b15cb3dSCy Schubert<code>minsane</code> 19422b15cb3dSCy Schubertshould be at least 4 in order to detect and discard 19432b15cb3dSCy Schuberta single falseticker. 19442b15cb3dSCy Schubert</dl> 19452b15cb3dSCy Schubert <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing 19462b15cb3dSCy Schubertorder, up to 8 values can be specified. 19472b15cb3dSCy SchubertIn manycast mode these values are used in turn 19482b15cb3dSCy Schubertin an expanding-ring search. 19492b15cb3dSCy SchubertThe default is eight 19502b15cb3dSCy Schubertmultiples of 32 starting at 31. 19512b15cb3dSCy Schubert</dl> 19522b15cb3dSCy Schubert<div class="node"> 19532b15cb3dSCy Schubert<p><hr> 19542b15cb3dSCy Schubert<a name="Reference-Clock-Support"></a> 19552b15cb3dSCy Schubert<br> 19562b15cb3dSCy Schubert</div> 19572b15cb3dSCy Schubert 19582b15cb3dSCy Schubert<h4 class="subsection">Reference Clock Support</h4> 19592b15cb3dSCy Schubert 19602b15cb3dSCy Schubert<p>The NTP Version 4 daemon supports some three dozen different radio, 19612b15cb3dSCy Schubertsatellite and modem reference clocks plus a special pseudo-clock 19622b15cb3dSCy Schubertused for backup or when no other clock source is available. 19632b15cb3dSCy SchubertDetailed descriptions of individual device drivers and options can 19642b15cb3dSCy Schubertbe found in the 19652b15cb3dSCy Schubert"Reference Clock Drivers" 19662b15cb3dSCy Schubertpage 19672b15cb3dSCy Schubert(available as part of the HTML documentation 19682b15cb3dSCy Schubertprovided in 19692b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 19702b15cb3dSCy SchubertAdditional information can be found in the pages linked 19712b15cb3dSCy Schubertthere, including the 19722b15cb3dSCy Schubert"Debugging Hints for Reference Clock Drivers" 19732b15cb3dSCy Schubertand 19742b15cb3dSCy Schubert"How To Write a Reference Clock Driver" 19752b15cb3dSCy Schubertpages 19762b15cb3dSCy Schubert(available as part of the HTML documentation 19772b15cb3dSCy Schubertprovided in 19782b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 19792b15cb3dSCy SchubertIn addition, support for a PPS 19802b15cb3dSCy Schubertsignal is available as described in the 19812b15cb3dSCy Schubert"Pulse-per-second (PPS) Signal Interfacing" 19822b15cb3dSCy Schubertpage 19832b15cb3dSCy Schubert(available as part of the HTML documentation 19842b15cb3dSCy Schubertprovided in 19852b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 19862b15cb3dSCy SchubertMany 19872b15cb3dSCy Schubertdrivers support special line discipline/streams modules which can 19882b15cb3dSCy Schubertsignificantly improve the accuracy using the driver. 19892b15cb3dSCy SchubertThese are 19902b15cb3dSCy Schubertdescribed in the 19912b15cb3dSCy Schubert"Line Disciplines and Streams Drivers" 19922b15cb3dSCy Schubertpage 19932b15cb3dSCy Schubert(available as part of the HTML documentation 19942b15cb3dSCy Schubertprovided in 19952b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 19962b15cb3dSCy Schubert 19972b15cb3dSCy Schubert <p>A reference clock will generally (though not always) be a radio 19982b15cb3dSCy Schuberttimecode receiver which is synchronized to a source of standard 19992b15cb3dSCy Schuberttime such as the services offered by the NRC in Canada and NIST and 20002b15cb3dSCy SchubertUSNO in the US. 20012b15cb3dSCy SchubertThe interface between the computer and the timecode 20022b15cb3dSCy Schubertreceiver is device dependent, but is usually a serial port. 20032b15cb3dSCy SchubertA 20042b15cb3dSCy Schubertdevice driver specific to each reference clock must be selected and 20052b15cb3dSCy Schubertcompiled in the distribution; however, most common radio, satellite 20062b15cb3dSCy Schubertand modem clocks are included by default. 20072b15cb3dSCy SchubertNote that an attempt to 20082b15cb3dSCy Schubertconfigure a reference clock when the driver has not been compiled 20092b15cb3dSCy Schubertor the hardware port has not been appropriately configured results 20102b15cb3dSCy Schubertin a scalding remark to the system log file, but is otherwise non 20112b15cb3dSCy Schuberthazardous. 20122b15cb3dSCy Schubert 20132b15cb3dSCy Schubert <p>For the purposes of configuration, 20142b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 20152b15cb3dSCy Schuberttreats 20162b15cb3dSCy Schubertreference clocks in a manner analogous to normal NTP peers as much 20172b15cb3dSCy Schubertas possible. 20182b15cb3dSCy SchubertReference clocks are identified by a syntactically 20192b15cb3dSCy Schubertcorrect but invalid IP address, in order to distinguish them from 20202b15cb3dSCy Schubertnormal NTP peers. 20212b15cb3dSCy SchubertReference clock addresses are of the form 20222b15cb3dSCy Schubert<code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd>, 20232b15cb3dSCy Schubertwhere 20242b15cb3dSCy Schubert<kbd>t</kbd> 20252b15cb3dSCy Schubertis an integer 20262b15cb3dSCy Schubertdenoting the clock type and 20272b15cb3dSCy Schubert<kbd>u</kbd> 20282b15cb3dSCy Schubertindicates the unit 20292b15cb3dSCy Schubertnumber in the range 0-3. 20302b15cb3dSCy SchubertWhile it may seem overkill, it is in fact 20312b15cb3dSCy Schubertsometimes useful to configure multiple reference clocks of the same 20322b15cb3dSCy Schuberttype, in which case the unit numbers must be unique. 20332b15cb3dSCy Schubert 20342b15cb3dSCy Schubert <p>The 20352b15cb3dSCy Schubert<code>server</code> 20362b15cb3dSCy Schubertcommand is used to configure a reference 20372b15cb3dSCy Schubertclock, where the 20382b15cb3dSCy Schubert<kbd>address</kbd> 20392b15cb3dSCy Schubertargument in that command 20402b15cb3dSCy Schubertis the clock address. 20412b15cb3dSCy SchubertThe 20422b15cb3dSCy Schubert<code>key</code>, 20432b15cb3dSCy Schubert<code>version</code> 20442b15cb3dSCy Schubertand 20452b15cb3dSCy Schubert<code>ttl</code> 20462b15cb3dSCy Schubertoptions are not used for reference clock support. 20472b15cb3dSCy SchubertThe 20482b15cb3dSCy Schubert<code>mode</code> 20492b15cb3dSCy Schubertoption is added for reference clock support, as 20502b15cb3dSCy Schubertdescribed below. 20512b15cb3dSCy SchubertThe 20522b15cb3dSCy Schubert<code>prefer</code> 20532b15cb3dSCy Schubertoption can be useful to 20542b15cb3dSCy Schubertpersuade the server to cherish a reference clock with somewhat more 20552b15cb3dSCy Schubertenthusiasm than other reference clocks or peers. 20562b15cb3dSCy SchubertFurther 20572b15cb3dSCy Schubertinformation on this option can be found in the 20582b15cb3dSCy Schubert"Mitigation Rules and the prefer Keyword" 20592b15cb3dSCy Schubert(available as part of the HTML documentation 20602b15cb3dSCy Schubertprovided in 20612b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 20622b15cb3dSCy Schubertpage. 20632b15cb3dSCy SchubertThe 20642b15cb3dSCy Schubert<code>minpoll</code> 20652b15cb3dSCy Schubertand 20662b15cb3dSCy Schubert<code>maxpoll</code> 20672b15cb3dSCy Schubertoptions have 20682b15cb3dSCy Schubertmeaning only for selected clock drivers. 20692b15cb3dSCy SchubertSee the individual clock 20702b15cb3dSCy Schubertdriver document pages for additional information. 20712b15cb3dSCy Schubert 20722b15cb3dSCy Schubert <p>The 20732b15cb3dSCy Schubert<code>fudge</code> 20742b15cb3dSCy Schubertcommand is used to provide additional 20752b15cb3dSCy Schubertinformation for individual clock drivers and normally follows 20762b15cb3dSCy Schubertimmediately after the 20772b15cb3dSCy Schubert<code>server</code> 20782b15cb3dSCy Schubertcommand. 20792b15cb3dSCy SchubertThe 20802b15cb3dSCy Schubert<kbd>address</kbd> 20812b15cb3dSCy Schubertargument specifies the clock address. 20822b15cb3dSCy SchubertThe 20832b15cb3dSCy Schubert<code>refid</code> 20842b15cb3dSCy Schubertand 20852b15cb3dSCy Schubert<code>stratum</code> 20862b15cb3dSCy Schubertoptions can be used to 20872b15cb3dSCy Schubertoverride the defaults for the device. 20882b15cb3dSCy SchubertThere are two optional 20892b15cb3dSCy Schubertdevice-dependent time offsets and four flags that can be included 20902b15cb3dSCy Schubertin the 20912b15cb3dSCy Schubert<code>fudge</code> 20922b15cb3dSCy Schubertcommand as well. 20932b15cb3dSCy Schubert 20942b15cb3dSCy Schubert <p>The stratum number of a reference clock is by default zero. 20952b15cb3dSCy SchubertSince the 20962b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 20972b15cb3dSCy Schubertdaemon adds one to the stratum of each 20982b15cb3dSCy Schubertpeer, a primary server ordinarily displays an external stratum of 20992b15cb3dSCy Schubertone. 21002b15cb3dSCy SchubertIn order to provide engineered backups, it is often useful to 21012b15cb3dSCy Schubertspecify the reference clock stratum as greater than zero. 21022b15cb3dSCy SchubertThe 21032b15cb3dSCy Schubert<code>stratum</code> 21042b15cb3dSCy Schubertoption is used for this purpose. 21052b15cb3dSCy SchubertAlso, in cases 21062b15cb3dSCy Schubertinvolving both a reference clock and a pulse-per-second (PPS) 21072b15cb3dSCy Schubertdiscipline signal, it is useful to specify the reference clock 21082b15cb3dSCy Schubertidentifier as other than the default, depending on the driver. 21092b15cb3dSCy SchubertThe 21102b15cb3dSCy Schubert<code>refid</code> 21112b15cb3dSCy Schubertoption is used for this purpose. 21122b15cb3dSCy SchubertExcept where noted, 21132b15cb3dSCy Schubertthese options apply to all clock drivers. 21142b15cb3dSCy Schubert 21152b15cb3dSCy Schubert<h5 class="subsubsection">Reference Clock Commands</h5> 21162b15cb3dSCy Schubert 21172b15cb3dSCy Schubert <dl> 21182b15cb3dSCy Schubert<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 21192b15cb3dSCy Schubertspecial ways. 21202b15cb3dSCy SchubertThe options are interpreted as follows: 21212b15cb3dSCy Schubert <dl> 21222b15cb3dSCy Schubert<dt><code>prefer</code><dd>Marks the reference clock as preferred. 21232b15cb3dSCy SchubertAll other things being 21242b15cb3dSCy Schubertequal, this host will be chosen for synchronization among a set of 21252b15cb3dSCy Schubertcorrectly operating hosts. 21262b15cb3dSCy SchubertSee the 21272b15cb3dSCy Schubert"Mitigation Rules and the prefer Keyword" 21282b15cb3dSCy Schubertpage 21292b15cb3dSCy Schubert(available as part of the HTML documentation 21302b15cb3dSCy Schubertprovided in 21312b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 21322b15cb3dSCy Schubertfor further information. 21332b15cb3dSCy Schubert<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 21342b15cb3dSCy Schubertdevice-specific fashion. 21352b15cb3dSCy SchubertFor instance, it selects a dialing 21362b15cb3dSCy Schubertprotocol in the ACTS driver and a device subtype in the 21372b15cb3dSCy Schubertparse 21382b15cb3dSCy Schubertdrivers. 21392b15cb3dSCy Schubert<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 21402b15cb3dSCy Schubertfor reference clock messages, as a power of 2 in seconds 21412b15cb3dSCy SchubertFor 21422b15cb3dSCy Schubertmost directly connected reference clocks, both 21432b15cb3dSCy Schubert<code>minpoll</code> 21442b15cb3dSCy Schubertand 21452b15cb3dSCy Schubert<code>maxpoll</code> 21462b15cb3dSCy Schubertdefault to 6 (64 s). 21472b15cb3dSCy SchubertFor modem reference clocks, 21482b15cb3dSCy Schubert<code>minpoll</code> 21492b15cb3dSCy Schubertdefaults to 10 (17.1 m) and 21502b15cb3dSCy Schubert<code>maxpoll</code> 21512b15cb3dSCy Schubertdefaults to 14 (4.5 h). 21522b15cb3dSCy SchubertThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 21532b15cb3dSCy Schubert</dl> 21542b15cb3dSCy Schubert <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 21552b15cb3dSCy Schubertspecial ways. 21562b15cb3dSCy SchubertIt must immediately follow the 21572b15cb3dSCy Schubert<code>server</code> 21582b15cb3dSCy Schubertcommand which configures the driver. 21592b15cb3dSCy SchubertNote that the same capability 21602b15cb3dSCy Schubertis possible at run time using the 21612b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 21622b15cb3dSCy Schubertprogram. 21632b15cb3dSCy SchubertThe options are interpreted as 21642b15cb3dSCy Schubertfollows: 21652b15cb3dSCy Schubert <dl> 21662b15cb3dSCy Schubert<dt><code>time1</code> <kbd>sec</kbd><dd>Specifies a constant to be added to the time offset produced by 21672b15cb3dSCy Schubertthe driver, a fixed-point decimal number in seconds. 21682b15cb3dSCy SchubertThis is used 21692b15cb3dSCy Schubertas a calibration constant to adjust the nominal time offset of a 21702b15cb3dSCy Schubertparticular clock to agree with an external standard, such as a 21712b15cb3dSCy Schubertprecision PPS signal. 21722b15cb3dSCy SchubertIt also provides a way to correct a 21732b15cb3dSCy Schubertsystematic error or bias due to serial port or operating system 21742b15cb3dSCy Schubertlatencies, different cable lengths or receiver internal delay. 21752b15cb3dSCy SchubertThe 21762b15cb3dSCy Schubertspecified offset is in addition to the propagation delay provided 21772b15cb3dSCy Schubertby other means, such as internal DIPswitches. 21782b15cb3dSCy SchubertWhere a calibration 21792b15cb3dSCy Schubertfor an individual system and driver is available, an approximate 21802b15cb3dSCy Schubertcorrection is noted in the driver documentation pages. 21812b15cb3dSCy SchubertNote: in order to facilitate calibration when more than one 21822b15cb3dSCy Schubertradio clock or PPS signal is supported, a special calibration 21832b15cb3dSCy Schubertfeature is available. 21842b15cb3dSCy SchubertIt takes the form of an argument to the 21852b15cb3dSCy Schubert<code>enable</code> 21862b15cb3dSCy Schubertcommand described in 21872b15cb3dSCy Schubert<a href="#Miscellaneous-Options">Miscellaneous Options</a> 21882b15cb3dSCy Schubertpage and operates as described in the 21892b15cb3dSCy Schubert"Reference Clock Drivers" 21902b15cb3dSCy Schubertpage 21912b15cb3dSCy Schubert(available as part of the HTML documentation 21922b15cb3dSCy Schubertprovided in 21932b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 21942b15cb3dSCy Schubert<br><dt><code>time2</code> <kbd>secs</kbd><dd>Specifies a fixed-point decimal number in seconds, which is 21952b15cb3dSCy Schubertinterpreted in a driver-dependent way. 21962b15cb3dSCy SchubertSee the descriptions of 21972b15cb3dSCy Schubertspecific drivers in the 21982b15cb3dSCy Schubert"Reference Clock Drivers" 21992b15cb3dSCy Schubertpage 22002b15cb3dSCy Schubert(available as part of the HTML documentation 22012b15cb3dSCy Schubertprovided in 22022b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 22032b15cb3dSCy Schubert<br><dt><code>stratum</code> <kbd>int</kbd><dd>Specifies the stratum number assigned to the driver, an integer 22042b15cb3dSCy Schubertbetween 0 and 15. 22052b15cb3dSCy SchubertThis number overrides the default stratum number 22062b15cb3dSCy Schubertordinarily assigned by the driver itself, usually zero. 22072b15cb3dSCy Schubert<br><dt><code>refid</code> <kbd>string</kbd><dd>Specifies an ASCII string of from one to four characters which 22082b15cb3dSCy Schubertdefines the reference identifier used by the driver. 22092b15cb3dSCy SchubertThis string 22102b15cb3dSCy Schubertoverrides the default identifier ordinarily assigned by the driver 22112b15cb3dSCy Schubertitself. 22122b15cb3dSCy Schubert<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 22132b15cb3dSCy Schubertdevice-specific fashion. 22142b15cb3dSCy SchubertFor instance, it selects a dialing 22152b15cb3dSCy Schubertprotocol in the ACTS driver and a device subtype in the 22162b15cb3dSCy Schubertparse 22172b15cb3dSCy Schubertdrivers. 22182b15cb3dSCy Schubert<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. 22192b15cb3dSCy SchubertThe 22202b15cb3dSCy Schubertinterpretation of these values, and whether they are used at all, 22212b15cb3dSCy Schubertis a function of the particular clock driver. 22222b15cb3dSCy SchubertHowever, by 22232b15cb3dSCy Schubertconvention 22242b15cb3dSCy Schubert<code>flag4</code> 22252b15cb3dSCy Schubertis used to enable recording monitoring 22262b15cb3dSCy Schubertdata to the 22272b15cb3dSCy Schubert<code>clockstats</code> 22282b15cb3dSCy Schubertfile configured with the 22292b15cb3dSCy Schubert<code>filegen</code> 22302b15cb3dSCy Schubertcommand. 22312b15cb3dSCy SchubertFurther information on the 22322b15cb3dSCy Schubert<code>filegen</code> 22332b15cb3dSCy Schubertcommand can be found in 22342b15cb3dSCy Schubert<a href="#Monitoring-Options">Monitoring Options</a>. 22352b15cb3dSCy Schubert</dl> 22362b15cb3dSCy Schubert </dl> 22372b15cb3dSCy Schubert<div class="node"> 22382b15cb3dSCy Schubert<p><hr> 22392b15cb3dSCy Schubert<a name="Miscellaneous-Options"></a> 22402b15cb3dSCy Schubert<br> 22412b15cb3dSCy Schubert</div> 22422b15cb3dSCy Schubert 22432b15cb3dSCy Schubert<h4 class="subsection">Miscellaneous Options</h4> 22442b15cb3dSCy Schubert 22452b15cb3dSCy Schubert <dl> 22462b15cb3dSCy Schubert<dt><code>broadcastdelay</code> <kbd>seconds</kbd><dd>The broadcast and multicast modes require a special calibration 22472b15cb3dSCy Schubertto determine the network delay between the local and remote 22482b15cb3dSCy Schubertservers. 22492b15cb3dSCy SchubertOrdinarily, this is done automatically by the initial 22502b15cb3dSCy Schubertprotocol exchanges between the client and server. 22512b15cb3dSCy SchubertIn some cases, 22522b15cb3dSCy Schubertthe calibration procedure may fail due to network or server access 22532b15cb3dSCy Schubertcontrols, for example. 22542b15cb3dSCy SchubertThis command specifies the default delay to 22552b15cb3dSCy Schubertbe used under these circumstances. 22562b15cb3dSCy SchubertTypically (for Ethernet), a 22572b15cb3dSCy Schubertnumber between 0.003 and 0.007 seconds is appropriate. 22582b15cb3dSCy SchubertThe default 22592b15cb3dSCy Schubertwhen this command is not used is 0.004 seconds. 22602b15cb3dSCy Schubert<br><dt><code>calldelay</code> <kbd>delay</kbd><dd>This option controls the delay in seconds between the first and second 22612b15cb3dSCy Schubertpackets sent in burst or iburst mode to allow additional time for a modem 22622b15cb3dSCy Schubertor ISDN call to complete. 22632b15cb3dSCy Schubert<br><dt><code>driftfile</code> <kbd>driftfile</kbd><dd>This command specifies the complete path and name of the file used to 22642b15cb3dSCy Schubertrecord the frequency of the local clock oscillator. 22652b15cb3dSCy SchubertThis is the same 22662b15cb3dSCy Schubertoperation as the 22672b15cb3dSCy Schubert<code>-f</code> 22682b15cb3dSCy Schubertcommand line option. 22692b15cb3dSCy SchubertIf the file exists, it is read at 22702b15cb3dSCy Schubertstartup in order to set the initial frequency and then updated once per 22712b15cb3dSCy Schuberthour with the current frequency computed by the daemon. 22722b15cb3dSCy SchubertIf the file name is 22732b15cb3dSCy Schubertspecified, but the file itself does not exist, the starts with an initial 22742b15cb3dSCy Schubertfrequency of zero and creates the file when writing it for the first time. 22752b15cb3dSCy SchubertIf this command is not given, the daemon will always start with an initial 22762b15cb3dSCy Schubertfrequency of zero. 22772b15cb3dSCy Schubert 22782b15cb3dSCy Schubert <p>The file format consists of a single line containing a single 22792b15cb3dSCy Schubertfloating point number, which records the frequency offset measured 22802b15cb3dSCy Schubertin parts-per-million (PPM). 22812b15cb3dSCy SchubertThe file is updated by first writing 22822b15cb3dSCy Schubertthe current drift value into a temporary file and then renaming 22832b15cb3dSCy Schubertthis file to replace the old version. 22842b15cb3dSCy SchubertThis implies that 22852b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 22862b15cb3dSCy Schubertmust have write permission for the directory the 22872b15cb3dSCy Schubertdrift file is located in, and that file system links, symbolic or 22882b15cb3dSCy Schubertotherwise, should be avoided. 2289276da39aSCy Schubert<br><dt><code>dscp</code> <kbd>value</kbd><dd>This option specifies the Differentiated Services Control Point (DSCP) value, 2290276da39aSCy Schuberta 6-bit code. The default value is 46, signifying Expedited Forwarding. 22912b15cb3dSCy Schubert<br><dt><code>enable</code> <code>[auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats]</code><br><dt><code>disable</code> <code>[auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats]</code><dd>Provides a way to enable or disable various server options. 22922b15cb3dSCy SchubertFlags not mentioned are unaffected. 22932b15cb3dSCy SchubertNote that all of these flags 22942b15cb3dSCy Schubertcan be controlled remotely using the 22952b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 22962b15cb3dSCy Schubertutility program. 22972b15cb3dSCy Schubert <dl> 22982b15cb3dSCy Schubert<dt><code>auth</code><dd>Enables the server to synchronize with unconfigured peers only if the 22992b15cb3dSCy Schubertpeer has been correctly authenticated using either public key or 23002b15cb3dSCy Schubertprivate key cryptography. 23012b15cb3dSCy SchubertThe default for this flag is 23022b15cb3dSCy Schubert<code>enable</code>. 23032b15cb3dSCy Schubert<br><dt><code>bclient</code><dd>Enables the server to listen for a message from a broadcast or 23042b15cb3dSCy Schubertmulticast server, as in the 23052b15cb3dSCy Schubert<code>multicastclient</code> 23062b15cb3dSCy Schubertcommand with default 23072b15cb3dSCy Schubertaddress. 23082b15cb3dSCy SchubertThe default for this flag is 23092b15cb3dSCy Schubert<code>disable</code>. 23102b15cb3dSCy Schubert<br><dt><code>calibrate</code><dd>Enables the calibrate feature for reference clocks. 23112b15cb3dSCy SchubertThe default for 23122b15cb3dSCy Schubertthis flag is 23132b15cb3dSCy Schubert<code>disable</code>. 23142b15cb3dSCy Schubert<br><dt><code>kernel</code><dd>Enables the kernel time discipline, if available. 23152b15cb3dSCy SchubertThe default for this 23162b15cb3dSCy Schubertflag is 23172b15cb3dSCy Schubert<code>enable</code> 23182b15cb3dSCy Schubertif support is available, otherwise 23192b15cb3dSCy Schubert<code>disable</code>. 23202b15cb3dSCy Schubert<br><dt><code>mode7</code><dd>Enables processing of NTP mode 7 implementation-specific requests 23212b15cb3dSCy Schubertwhich are used by the deprecated 23222b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 23232b15cb3dSCy Schubertprogram. 23242b15cb3dSCy SchubertThe default for this flag is disable. 23252b15cb3dSCy SchubertThis flag is excluded from runtime configuration using 23262b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code>. 23272b15cb3dSCy SchubertThe 23282b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 23292b15cb3dSCy Schubertprogram provides the same capabilities as 23302b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 23312b15cb3dSCy Schubertusing standard mode 6 requests. 23322b15cb3dSCy Schubert<br><dt><code>monitor</code><dd>Enables the monitoring facility. 23332b15cb3dSCy SchubertSee the 23342b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 23352b15cb3dSCy Schubertprogram 23362b15cb3dSCy Schubertand the 23372b15cb3dSCy Schubert<code>monlist</code> 23382b15cb3dSCy Schubertcommand or further information. 23392b15cb3dSCy SchubertThe 23402b15cb3dSCy Schubertdefault for this flag is 23412b15cb3dSCy Schubert<code>enable</code>. 23422b15cb3dSCy Schubert<br><dt><code>ntp</code><dd>Enables time and frequency discipline. 23432b15cb3dSCy SchubertIn effect, this switch opens and 23442b15cb3dSCy Schubertcloses the feedback loop, which is useful for testing. 23452b15cb3dSCy SchubertThe default for 23462b15cb3dSCy Schubertthis flag is 23472b15cb3dSCy Schubert<code>enable</code>. 23482b15cb3dSCy Schubert<br><dt><code>stats</code><dd>Enables the statistics facility. 23492b15cb3dSCy SchubertSee the 23502b15cb3dSCy Schubert<a href="#Monitoring-Options">Monitoring Options</a> 23512b15cb3dSCy Schubertsection for further information. 23522b15cb3dSCy SchubertThe default for this flag is 23532b15cb3dSCy Schubert<code>disable</code>. 23542b15cb3dSCy Schubert</dl> 23552b15cb3dSCy Schubert <br><dt><code>includefile</code> <kbd>includefile</kbd><dd>This command allows additional configuration commands 23562b15cb3dSCy Schubertto be included from a separate file. 23572b15cb3dSCy SchubertInclude files may 23582b15cb3dSCy Schubertbe nested to a depth of five; upon reaching the end of any 23592b15cb3dSCy Schubertinclude file, command processing resumes in the previous 23602b15cb3dSCy Schubertconfiguration file. 23612b15cb3dSCy SchubertThis option is useful for sites that run 23622b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 23632b15cb3dSCy Schuberton multiple hosts, with (mostly) common options (e.g., a 23642b15cb3dSCy Schubertrestriction list). 2365276da39aSCy Schubert<br><dt><code>leapsmearinterval</code> <kbd>seconds</kbd><dd>This EXPERIMENTAL option is only available if 2366276da39aSCy Schubert<code>ntpd(1ntpdmdoc)</code> 2367276da39aSCy Schubertwas built with the 2368276da39aSCy Schubert<code>--enable-leap-smear</code> 2369276da39aSCy Schubertoption to the 2370276da39aSCy Schubert<code>configure</code> 2371276da39aSCy Schubertscript. 2372276da39aSCy SchubertIt specifies the interval over which a leap second correction will be applied. 2373276da39aSCy SchubertRecommended values for this option are between 2374276da39aSCy Schubert7200 (2 hours) and 86400 (24 hours). 2375276da39aSCy Schubert.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2376276da39aSCy SchubertSee http://bugs.ntp.org/2855 for more information. 23772b15cb3dSCy Schubert<br><dt><code>logconfig</code> <kbd>configkeyword</kbd><dd>This command controls the amount and type of output written to 23782b15cb3dSCy Schubertthe system 23792b15cb3dSCy Schubert<code>syslog(3)</code> 23802b15cb3dSCy Schubertfacility or the alternate 23812b15cb3dSCy Schubert<code>logfile</code> 23822b15cb3dSCy Schubertlog file. 23832b15cb3dSCy SchubertBy default, all output is turned on. 23842b15cb3dSCy SchubertAll 23852b15cb3dSCy Schubert<kbd>configkeyword</kbd> 23862b15cb3dSCy Schubertkeywords can be prefixed with 23872b15cb3dSCy Schubert=, 23882b15cb3dSCy Schubert+ 23892b15cb3dSCy Schubertand 23902b15cb3dSCy Schubert-, 23912b15cb3dSCy Schubertwhere 23922b15cb3dSCy Schubert= 23932b15cb3dSCy Schubertsets the 23942b15cb3dSCy Schubert<code>syslog(3)</code> 23952b15cb3dSCy Schubertpriority mask, 23962b15cb3dSCy Schubert+ 23972b15cb3dSCy Schubertadds and 23982b15cb3dSCy Schubert- 23992b15cb3dSCy Schubertremoves 24002b15cb3dSCy Schubertmessages. 24012b15cb3dSCy Schubert<code>syslog(3)</code> 24022b15cb3dSCy Schubertmessages can be controlled in four 24032b15cb3dSCy Schubertclasses 24042b15cb3dSCy Schubert(<code>clock</code>, <code>peer</code>, <code>sys</code> and <code>sync</code>). 24052b15cb3dSCy SchubertWithin these classes four types of messages can be 24062b15cb3dSCy Schubertcontrolled: informational messages 24072b15cb3dSCy Schubert(<code>info</code>), 24082b15cb3dSCy Schubertevent messages 24092b15cb3dSCy Schubert(<code>events</code>), 24102b15cb3dSCy Schubertstatistics messages 24112b15cb3dSCy Schubert(<code>statistics</code>) 24122b15cb3dSCy Schubertand 24132b15cb3dSCy Schubertstatus messages 24142b15cb3dSCy Schubert(<code>status</code>). 24152b15cb3dSCy Schubert 24162b15cb3dSCy Schubert <p>Configuration keywords are formed by concatenating the message class with 24172b15cb3dSCy Schubertthe event class. 24182b15cb3dSCy SchubertThe 24192b15cb3dSCy Schubert<code>all</code> 24202b15cb3dSCy Schubertprefix can be used instead of a message class. 24212b15cb3dSCy SchubertA 24222b15cb3dSCy Schubertmessage class may also be followed by the 24232b15cb3dSCy Schubert<code>all</code> 24242b15cb3dSCy Schubertkeyword to enable/disable all 24252b15cb3dSCy Schubertmessages of the respective message class.Thus, a minimal log configuration 24262b15cb3dSCy Schubertcould look like this: 24272b15cb3dSCy Schubert<pre class="verbatim"> 24282b15cb3dSCy Schubert logconfig =syncstatus +sysevents 24292b15cb3dSCy Schubert</pre> 24302b15cb3dSCy Schubert 24312b15cb3dSCy Schubert <p>This would just list the synchronizations state of 24322b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 24332b15cb3dSCy Schubertand the major system events. 24342b15cb3dSCy SchubertFor a simple reference server, the 24352b15cb3dSCy Schubertfollowing minimum message configuration could be useful: 24362b15cb3dSCy Schubert<pre class="verbatim"> 24372b15cb3dSCy Schubert logconfig =syncall +clockall 24382b15cb3dSCy Schubert</pre> 24392b15cb3dSCy Schubert 24402b15cb3dSCy Schubert <p>This configuration will list all clock information and 24412b15cb3dSCy Schubertsynchronization information. 24422b15cb3dSCy SchubertAll other events and messages about 24432b15cb3dSCy Schubertpeers, system events and so on is suppressed. 24442b15cb3dSCy Schubert<br><dt><code>logfile</code> <kbd>logfile</kbd><dd>This command specifies the location of an alternate log file to 24452b15cb3dSCy Schubertbe used instead of the default system 24462b15cb3dSCy Schubert<code>syslog(3)</code> 24472b15cb3dSCy Schubertfacility. 24482b15cb3dSCy SchubertThis is the same operation as the -l command line option. 24492b15cb3dSCy Schubert<br><dt><code>setvar</code> <kbd>variable</kbd> <code>[default]</code><dd>This command adds an additional system variable. 24502b15cb3dSCy SchubertThese 24512b15cb3dSCy Schubertvariables can be used to distribute additional information such as 24522b15cb3dSCy Schubertthe access policy. 24532b15cb3dSCy SchubertIf the variable of the form 24542b15cb3dSCy Schubert<code>name</code><code>=</code><kbd>value</kbd> 24552b15cb3dSCy Schubertis followed by the 24562b15cb3dSCy Schubert<code>default</code> 24572b15cb3dSCy Schubertkeyword, the 24582b15cb3dSCy Schubertvariable will be listed as part of the default system variables 24592b15cb3dSCy Schubert(<code>rv</code> command)). 24602b15cb3dSCy SchubertThese additional variables serve 24612b15cb3dSCy Schubertinformational purposes only. 24622b15cb3dSCy SchubertThey are not related to the protocol 24632b15cb3dSCy Schubertother that they can be listed. 24642b15cb3dSCy SchubertThe known protocol variables will 24652b15cb3dSCy Schubertalways override any variables defined via the 24662b15cb3dSCy Schubert<code>setvar</code> 24672b15cb3dSCy Schubertmechanism. 24682b15cb3dSCy SchubertThere are three special variables that contain the names 24692b15cb3dSCy Schubertof all variable of the same group. 24702b15cb3dSCy SchubertThe 24712b15cb3dSCy Schubert<code>sys_var_list</code> 24722b15cb3dSCy Schubertholds 24732b15cb3dSCy Schubertthe names of all system variables. 24742b15cb3dSCy SchubertThe 24752b15cb3dSCy Schubert<code>peer_var_list</code> 24762b15cb3dSCy Schubertholds 24772b15cb3dSCy Schubertthe names of all peer variables and the 24782b15cb3dSCy Schubert<code>clock_var_list</code> 24792b15cb3dSCy Schubertholds the names of the reference clock variables. 2480a25439b6SCy Schubert<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 24812b15cb3dSCy Schubertvery exceptional circumstances. 24822b15cb3dSCy SchubertIt should occur in the 24832b15cb3dSCy Schubertconfiguration file before any other configuration options. 24842b15cb3dSCy SchubertThe 24852b15cb3dSCy Schubertdefault values of these variables have been carefully optimized for 24862b15cb3dSCy Schuberta wide range of network speeds and reliability expectations. 24872b15cb3dSCy SchubertIn 24882b15cb3dSCy Schubertgeneral, they interact in intricate ways that are hard to predict 24892b15cb3dSCy Schubertand some combinations can result in some very nasty behavior. 24902b15cb3dSCy SchubertVery 24912b15cb3dSCy Schubertrarely is it necessary to change the default values; but, some 24922b15cb3dSCy Schubertfolks cannot resist twisting the knobs anyway and this command is 24932b15cb3dSCy Schubertfor them. 24942b15cb3dSCy SchubertEmphasis added: twisters are on their own and can expect 24952b15cb3dSCy Schubertno help from the support group. 24962b15cb3dSCy Schubert 24972b15cb3dSCy Schubert <p>The variables operate as follows: 24982b15cb3dSCy Schubert <dl> 24992b15cb3dSCy Schubert<dt><code>allan</code> <kbd>allan</kbd><dd>The argument becomes the new value for the minimum Allan 25002b15cb3dSCy Schubertintercept, which is a parameter of the PLL/FLL clock discipline 25012b15cb3dSCy Schubertalgorithm. 25022b15cb3dSCy SchubertThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 25032b15cb3dSCy Schubertlimit. 25042b15cb3dSCy Schubert<br><dt><code>dispersion</code> <kbd>dispersion</kbd><dd>The argument becomes the new value for the dispersion increase rate, 25052b15cb3dSCy Schubertnormally .000015 s/s. 25062b15cb3dSCy Schubert<br><dt><code>freq</code> <kbd>freq</kbd><dd>The argument becomes the initial value of the frequency offset in 25072b15cb3dSCy Schubertparts-per-million. 25082b15cb3dSCy SchubertThis overrides the value in the frequency file, if 25092b15cb3dSCy Schubertpresent, and avoids the initial training state if it is not. 25102b15cb3dSCy Schubert<br><dt><code>huffpuff</code> <kbd>huffpuff</kbd><dd>The argument becomes the new value for the experimental 25112b15cb3dSCy Schuberthuff-n'-puff filter span, which determines the most recent interval 25122b15cb3dSCy Schubertthe algorithm will search for a minimum delay. 25132b15cb3dSCy SchubertThe lower limit is 25142b15cb3dSCy Schubert900 s (15 m), but a more reasonable value is 7200 (2 hours). 25152b15cb3dSCy SchubertThere 25162b15cb3dSCy Schubertis no default, since the filter is not enabled unless this command 25172b15cb3dSCy Schubertis given. 25182b15cb3dSCy Schubert<br><dt><code>panic</code> <kbd>panic</kbd><dd>The argument is the panic threshold, normally 1000 s. 25192b15cb3dSCy SchubertIf set to zero, 25202b15cb3dSCy Schubertthe panic sanity check is disabled and a clock offset of any value will 25212b15cb3dSCy Schubertbe accepted. 25222b15cb3dSCy Schubert<br><dt><code>step</code> <kbd>step</kbd><dd>The argument is the step threshold, which by default is 0.128 s. 25232b15cb3dSCy SchubertIt can 25242b15cb3dSCy Schubertbe set to any positive number in seconds. 25252b15cb3dSCy SchubertIf set to zero, step 25262b15cb3dSCy Schubertadjustments will never occur. 25272b15cb3dSCy SchubertNote: The kernel time discipline is 25282b15cb3dSCy Schubertdisabled if the step threshold is set to zero or greater than the 25292b15cb3dSCy Schubertdefault. 2530a25439b6SCy Schubert<br><dt><code>stepback</code> <kbd>stepback</kbd><dd>The argument is the step threshold for the backward direction, 2531a25439b6SCy Schubertwhich by default is 0.128 s. 2532a25439b6SCy SchubertIt can 2533a25439b6SCy Schubertbe set to any positive number in seconds. 2534a25439b6SCy SchubertIf both the forward and backward step thresholds are set to zero, step 2535a25439b6SCy Schubertadjustments will never occur. 2536a25439b6SCy SchubertNote: The kernel time discipline is 2537a25439b6SCy Schubertdisabled if 2538a25439b6SCy Schuberteach direction of step threshold are either 2539a25439b6SCy Schubertset to zero or greater than .5 second. 2540a25439b6SCy Schubert<br><dt><code>stepfwd</code> <kbd>stepfwd</kbd><dd>As for stepback, but for the forward direction. 25412b15cb3dSCy Schubert<br><dt><code>stepout</code> <kbd>stepout</kbd><dd>The argument is the stepout timeout, which by default is 900 s. 25422b15cb3dSCy SchubertIt can 25432b15cb3dSCy Schubertbe set to any positive number in seconds. 25442b15cb3dSCy SchubertIf set to zero, the stepout 25452b15cb3dSCy Schubertpulses will not be suppressed. 25462b15cb3dSCy Schubert</dl> 25472b15cb3dSCy Schubert <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> 25482b15cb3dSCy Schubert <dl> 2549*9034852cSGleb Smirnoff<dt><code>memlock</code> <kbd>Nmegabytes</kbd><dd>Specify the number of megabytes of memory that should be 2550*9034852cSGleb Smirnoffallocated and locked. 2551*9034852cSGleb SmirnoffProbably only available under Linux, this option may be useful 25522b15cb3dSCy Schubertwhen dropping root (the 25532b15cb3dSCy Schubert<code>-i</code> 25542b15cb3dSCy Schubertoption). 2555*9034852cSGleb SmirnoffThe default is 32 megabytes on non-Linux machines, and -1 under Linux. 2556*9034852cSGleb Smirnoff-1 means "do not lock the process into memory". 2557*9034852cSGleb Smirnoff0 means "lock whatever memory the process wants into memory". 25582b15cb3dSCy Schubert<br><dt><code>stacksize</code> <kbd>N4kPages</kbd><dd>Specifies the maximum size of the process stack on systems with the 25592b15cb3dSCy Schubert<code>mlockall()</code> 25602b15cb3dSCy Schubertfunction. 25612b15cb3dSCy SchubertDefaults to 50 4k pages (200 4k pages in OpenBSD). 2562276da39aSCy Schubert<br><dt><code>filenum</code> <kbd>Nfiledescriptors</kbd><dd>Specifies the maximum number of file descriptors ntpd may have open at once. Defaults to the system default. 25632b15cb3dSCy Schubert</dl> 25642b15cb3dSCy Schubert <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 25652b15cb3dSCy Schubertaddress and port number for sending messages with the specified 25662b15cb3dSCy Schubertlocal interface address. 25672b15cb3dSCy SchubertIf the port number is unspecified, a value 25682b15cb3dSCy Schubertof 18447 is used. 25692b15cb3dSCy SchubertIf the interface address is not specified, the 25702b15cb3dSCy Schubertmessage is sent with a source address of the local interface the 25712b15cb3dSCy Schubertmessage is sent through. 25722b15cb3dSCy SchubertNote that on a multihomed host the 25732b15cb3dSCy Schubertinterface used may vary from time to time with routing changes. 25742b15cb3dSCy Schubert 25752b15cb3dSCy Schubert <p>The trap receiver will generally log event messages and other 25762b15cb3dSCy Schubertinformation from the server in a log file. 25772b15cb3dSCy SchubertWhile such monitor 25782b15cb3dSCy Schubertprograms may also request their own trap dynamically, configuring a 25792b15cb3dSCy Schuberttrap receiver will ensure that no messages are lost when the server 25802b15cb3dSCy Schubertis started. 25812b15cb3dSCy Schubert<br><dt><code>hop</code> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order, up to 8 25822b15cb3dSCy Schubertvalues can be specified. 25832b15cb3dSCy SchubertIn manycast mode these values are used in turn in 25842b15cb3dSCy Schubertan expanding-ring search. 25852b15cb3dSCy SchubertThe default is eight multiples of 32 starting at 25862b15cb3dSCy Schubert31. 25872b15cb3dSCy Schubert</dl> 25882b15cb3dSCy Schubert 25892b15cb3dSCy Schubert <p>This section was generated by <strong>AutoGen</strong>, 25902b15cb3dSCy Schubertusing the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program. 25912b15cb3dSCy SchubertThis software is released under the NTP license, <http://ntp.org/license>. 25922b15cb3dSCy Schubert 25932b15cb3dSCy Schubert<ul class="menu"> 25942b15cb3dSCy Schubert<li><a accesskey="1" href="#ntp_002econf-Files">ntp.conf Files</a>: Files 25952b15cb3dSCy Schubert<li><a accesskey="2" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also 25962b15cb3dSCy Schubert<li><a accesskey="3" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs 25972b15cb3dSCy Schubert<li><a accesskey="4" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes 25982b15cb3dSCy Schubert</ul> 25992b15cb3dSCy Schubert 26002b15cb3dSCy Schubert<div class="node"> 26012b15cb3dSCy Schubert<p><hr> 26022b15cb3dSCy Schubert<a name="ntp_002econf-Files"></a> 26032b15cb3dSCy Schubert<br> 26042b15cb3dSCy Schubert</div> 26052b15cb3dSCy Schubert 26062b15cb3dSCy Schubert<h4 class="subsection">ntp.conf Files</h4> 26072b15cb3dSCy Schubert 26082b15cb3dSCy Schubert <dl> 26092b15cb3dSCy Schubert<dt><span class="file">/etc/ntp.conf</span><dd>the default name of the configuration file 26102b15cb3dSCy Schubert<br><dt><span class="file">ntp.keys</span><dd>private MD5 keys 26112b15cb3dSCy Schubert<br><dt><span class="file">ntpkey</span><dd>RSA private key 26122b15cb3dSCy Schubert<br><dt><span class="file">ntpkey_</span><kbd>host</kbd><dd>RSA public key 26132b15cb3dSCy Schubert<br><dt><span class="file">ntp_dh</span><dd>Diffie-Hellman agreement parameters 26142b15cb3dSCy Schubert</dl> 26152b15cb3dSCy Schubert<div class="node"> 26162b15cb3dSCy Schubert<p><hr> 26172b15cb3dSCy Schubert<a name="ntp_002econf-See-Also"></a> 26182b15cb3dSCy Schubert<br> 26192b15cb3dSCy Schubert</div> 26202b15cb3dSCy Schubert 26212b15cb3dSCy Schubert<h4 class="subsection">ntp.conf See Also</h4> 26222b15cb3dSCy Schubert 26232b15cb3dSCy Schubert<p><code>ntpd(1ntpdmdoc)</code>, 26242b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code>, 26252b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 26262b15cb3dSCy Schubert 26272b15cb3dSCy Schubert <p>In addition to the manual pages provided, 26282b15cb3dSCy Schubertcomprehensive documentation is available on the world wide web 26292b15cb3dSCy Schubertat 26302b15cb3dSCy Schubert<code>http://www.ntp.org/</code>. 26312b15cb3dSCy SchubertA snapshot of this documentation is available in HTML format in 26322b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>. 26332b15cb3dSCy Schubert<br> 26342b15cb3dSCy Schubert 26352b15cb3dSCy Schubert <p><br> 26362b15cb3dSCy SchubertDavid L. Mills, <em>Network Time Protocol (Version 4)</em>, RFC5905 26372b15cb3dSCy Schubert<div class="node"> 26382b15cb3dSCy Schubert<p><hr> 26392b15cb3dSCy Schubert<a name="ntp_002econf-Bugs"></a> 26402b15cb3dSCy Schubert<br> 26412b15cb3dSCy Schubert</div> 26422b15cb3dSCy Schubert 26432b15cb3dSCy Schubert<h4 class="subsection">ntp.conf Bugs</h4> 26442b15cb3dSCy Schubert 26452b15cb3dSCy Schubert<p>The syntax checking is not picky; some combinations of 26462b15cb3dSCy Schubertridiculous and even hilarious options and modes may not be 26472b15cb3dSCy Schubertdetected. 26482b15cb3dSCy Schubert 26492b15cb3dSCy Schubert <p>The 26502b15cb3dSCy Schubert<span class="file">ntpkey_</span><kbd>host</kbd> 26512b15cb3dSCy Schubertfiles are really digital 26522b15cb3dSCy Schubertcertificates. 26532b15cb3dSCy SchubertThese should be obtained via secure directory 26542b15cb3dSCy Schubertservices when they become universally available. 26552b15cb3dSCy Schubert<div class="node"> 26562b15cb3dSCy Schubert<p><hr> 26572b15cb3dSCy Schubert<a name="ntp_002econf-Notes"></a> 26582b15cb3dSCy Schubert<br> 26592b15cb3dSCy Schubert</div> 26602b15cb3dSCy Schubert 26612b15cb3dSCy Schubert<h4 class="subsection">ntp.conf Notes</h4> 26622b15cb3dSCy Schubert 26632b15cb3dSCy Schubert<p>This document was derived from FreeBSD. 26642b15cb3dSCy Schubert 26652b15cb3dSCy Schubert</body></html> 26662b15cb3dSCy Schubert 2667