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*4e1ef62aSXin LI <p>This document applies to version 4.2.8p12 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. 170e27abb66SXin LIIn a few cases, including the 171e27abb66SXin LI<code>reslist</code> 172e27abb66SXin LIbillboard generated 173e27abb66SXin LIby 174e27abb66SXin LI<code>ntpq(1ntpqmdoc)</code> 175e27abb66SXin LIor 176e27abb66SXin LI<code>ntpdc(1ntpdcmdoc)</code>, 177e27abb66SXin LIIPv6 addresses are automatically generated. 1782b15cb3dSCy SchubertIPv6 addresses can be identified by the presence of colons 1792b15cb3dSCy Schubert: 1802b15cb3dSCy Schubertin the address field. 1812b15cb3dSCy SchubertIPv6 addresses can be used almost everywhere where 1822b15cb3dSCy SchubertIPv4 addresses can be used, 1832b15cb3dSCy Schubertwith the exception of reference clock addresses, 1842b15cb3dSCy Schubertwhich are always IPv4. 1852b15cb3dSCy Schubert 1862b15cb3dSCy Schubert <p>Note that in contexts where a host name is expected, a 1872b15cb3dSCy Schubert<code>-4</code> 1882b15cb3dSCy Schubertqualifier preceding 1892b15cb3dSCy Schubertthe host name forces DNS resolution to the IPv4 namespace, 1902b15cb3dSCy Schubertwhile a 1912b15cb3dSCy Schubert<code>-6</code> 1922b15cb3dSCy Schubertqualifier forces DNS resolution to the IPv6 namespace. 1932b15cb3dSCy SchubertSee IPv6 references for the 1942b15cb3dSCy Schubertequivalent classes for that address family. 1952b15cb3dSCy Schubert <dl> 196e27abb66SXin LI<dt><code>pool</code> <kbd>address</kbd> <code>[burst]</code> <code>[iburst]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code><br><dt><code>server</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[burst]</code> <code>[iburst]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[true]</code><br><dt><code>peer</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[true]</code> <code>[xleave]</code><br><dt><code>broadcast</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[ttl </code><kbd>ttl</kbd><code>]</code> <code>[xleave]</code><br><dt><code>manycastclient</code> <kbd>address</kbd> <code>[key </code><kbd>key</kbd> <kbd>|</kbd><code> autokey]</code> <code>[version </code><kbd>version</kbd><code>]</code> <code>[prefer]</code> <code>[minpoll </code><kbd>minpoll</kbd><code>]</code> <code>[maxpoll </code><kbd>maxpoll</kbd><code>]</code> <code>[ttl </code><kbd>ttl</kbd><code>]</code><dd></dl> 1972b15cb3dSCy Schubert 1982b15cb3dSCy Schubert <p>These five commands specify the time server name or address to 1992b15cb3dSCy Schubertbe used and the mode in which to operate. 2002b15cb3dSCy SchubertThe 2012b15cb3dSCy Schubert<kbd>address</kbd> 2022b15cb3dSCy Schubertcan be 2032b15cb3dSCy Schuberteither a DNS name or an IP address in dotted-quad notation. 2042b15cb3dSCy SchubertAdditional information on association behavior can be found in the 2052b15cb3dSCy Schubert"Association Management" 2062b15cb3dSCy Schubertpage 2072b15cb3dSCy Schubert(available as part of the HTML documentation 2082b15cb3dSCy Schubertprovided in 2092b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 2102b15cb3dSCy Schubert <dl> 2112b15cb3dSCy Schubert<dt><code>pool</code><dd>For type s addresses, this command mobilizes a persistent 2122b15cb3dSCy Schubertclient mode association with a number of remote servers. 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 Schubert<br><dt><code>server</code><dd>For type s and r addresses, this command mobilizes a persistent 2172b15cb3dSCy Schubertclient mode association with the specified remote server or local 2182b15cb3dSCy Schubertradio clock. 2192b15cb3dSCy SchubertIn this mode the local clock can synchronized to the 2202b15cb3dSCy Schubertremote server, but the remote server can never be synchronized to 2212b15cb3dSCy Schubertthe local clock. 2222b15cb3dSCy SchubertThis command should 2232b15cb3dSCy Schubert<em>not</em> 2242b15cb3dSCy Schubertbe used for type 2252b15cb3dSCy Schubertb or m addresses. 2262b15cb3dSCy Schubert<br><dt><code>peer</code><dd>For type s addresses (only), this command mobilizes a 2272b15cb3dSCy Schubertpersistent symmetric-active mode association with the specified 2282b15cb3dSCy Schubertremote peer. 2292b15cb3dSCy SchubertIn this mode the local clock can be synchronized to 2302b15cb3dSCy Schubertthe remote peer or the remote peer can be synchronized to the local 2312b15cb3dSCy Schubertclock. 2322b15cb3dSCy SchubertThis is useful in a network of servers where, depending on 2332b15cb3dSCy Schubertvarious failure scenarios, either the local or remote peer may be 2342b15cb3dSCy Schubertthe better source of time. 2352b15cb3dSCy SchubertThis command should NOT be used for type 2362b15cb3dSCy Schubertb, m or r addresses. 2372b15cb3dSCy Schubert<br><dt><code>broadcast</code><dd>For type b and m addresses (only), this 2382b15cb3dSCy Schubertcommand mobilizes a persistent broadcast mode association. 2392b15cb3dSCy SchubertMultiple 2402b15cb3dSCy Schubertcommands can be used to specify multiple local broadcast interfaces 2412b15cb3dSCy Schubert(subnets) and/or multiple multicast groups. 2422b15cb3dSCy SchubertNote that local 2432b15cb3dSCy Schubertbroadcast messages go only to the interface associated with the 2442b15cb3dSCy Schubertsubnet specified, but multicast messages go to all interfaces. 2452b15cb3dSCy SchubertIn broadcast mode the local server sends periodic broadcast 2462b15cb3dSCy Schubertmessages to a client population at the 2472b15cb3dSCy Schubert<kbd>address</kbd> 2482b15cb3dSCy Schubertspecified, which is usually the broadcast address on (one of) the 2492b15cb3dSCy Schubertlocal network(s) or a multicast address assigned to NTP. 2502b15cb3dSCy SchubertThe IANA 2512b15cb3dSCy Schuberthas assigned the multicast group address IPv4 224.0.1.1 and 2522b15cb3dSCy SchubertIPv6 ff05::101 (site local) exclusively to 2532b15cb3dSCy SchubertNTP, but other nonconflicting addresses can be used to contain the 2542b15cb3dSCy Schubertmessages within administrative boundaries. 2552b15cb3dSCy SchubertOrdinarily, this 2562b15cb3dSCy Schubertspecification applies only to the local server operating as a 2572b15cb3dSCy Schubertsender; for operation as a broadcast client, see the 2582b15cb3dSCy Schubert<code>broadcastclient</code> 2592b15cb3dSCy Schubertor 2602b15cb3dSCy Schubert<code>multicastclient</code> 2612b15cb3dSCy Schubertcommands 2622b15cb3dSCy Schubertbelow. 2632b15cb3dSCy Schubert<br><dt><code>manycastclient</code><dd>For type m addresses (only), this command mobilizes a 2642b15cb3dSCy Schubertmanycast client mode association for the multicast address 2652b15cb3dSCy Schubertspecified. 2662b15cb3dSCy SchubertIn this case a specific address must be supplied which 2672b15cb3dSCy Schubertmatches the address used on the 2682b15cb3dSCy Schubert<code>manycastserver</code> 2692b15cb3dSCy Schubertcommand for 2702b15cb3dSCy Schubertthe designated manycast servers. 2712b15cb3dSCy SchubertThe NTP multicast address 2722b15cb3dSCy Schubert224.0.1.1 assigned by the IANA should NOT be used, unless specific 2732b15cb3dSCy Schubertmeans are taken to avoid spraying large areas of the Internet with 2742b15cb3dSCy Schubertthese messages and causing a possibly massive implosion of replies 2752b15cb3dSCy Schubertat the sender. 2762b15cb3dSCy SchubertThe 2772b15cb3dSCy Schubert<code>manycastserver</code> 2782b15cb3dSCy Schubertcommand specifies that the local server 2792b15cb3dSCy Schubertis to operate in client mode with the remote servers that are 2802b15cb3dSCy Schubertdiscovered as the result of broadcast/multicast messages. 2812b15cb3dSCy SchubertThe 2822b15cb3dSCy Schubertclient broadcasts a request message to the group address associated 2832b15cb3dSCy Schubertwith the specified 2842b15cb3dSCy Schubert<kbd>address</kbd> 2852b15cb3dSCy Schubertand specifically enabled 2862b15cb3dSCy Schubertservers respond to these messages. 2872b15cb3dSCy SchubertThe client selects the servers 2882b15cb3dSCy Schubertproviding the best time and continues as with the 2892b15cb3dSCy Schubert<code>server</code> 2902b15cb3dSCy Schubertcommand. 2912b15cb3dSCy SchubertThe remaining servers are discarded as if never 2922b15cb3dSCy Schubertheard. 2932b15cb3dSCy Schubert</dl> 2942b15cb3dSCy Schubert 2952b15cb3dSCy Schubert <p>Options: 2962b15cb3dSCy Schubert <dl> 2972b15cb3dSCy Schubert<dt><code>autokey</code><dd>All packets sent to and received from the server or peer are to 2982b15cb3dSCy Schubertinclude authentication fields encrypted using the autokey scheme 2992b15cb3dSCy Schubertdescribed in 3002b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 3012b15cb3dSCy Schubert<br><dt><code>burst</code><dd>when the server is reachable, send a burst of eight packets 3022b15cb3dSCy Schubertinstead of the usual one. 3032b15cb3dSCy SchubertThe packet spacing is normally 2 s; 3042b15cb3dSCy Schuberthowever, the spacing between the first and second packets 3054990d495SXin LIcan be changed with the 3064990d495SXin LI<code>calldelay</code> 3074990d495SXin LIcommand to allow 3082b15cb3dSCy Schubertadditional time for a modem or ISDN call to complete. 3092b15cb3dSCy SchubertThis is designed to improve timekeeping quality 3102b15cb3dSCy Schubertwith the 3112b15cb3dSCy Schubert<code>server</code> 3122b15cb3dSCy Schubertcommand and s addresses. 3132b15cb3dSCy Schubert<br><dt><code>iburst</code><dd>When the server is unreachable, send a burst of eight packets 3142b15cb3dSCy Schubertinstead of the usual one. 3152b15cb3dSCy SchubertThe packet spacing is normally 2 s; 3162b15cb3dSCy Schuberthowever, the spacing between the first two packets can be 3174990d495SXin LIchanged with the 3184990d495SXin LI<code>calldelay</code> 3194990d495SXin LIcommand to allow 3202b15cb3dSCy Schubertadditional time for a modem or ISDN call to complete. 3212b15cb3dSCy SchubertThis is designed to speed the initial synchronization 3222b15cb3dSCy Schubertacquisition with the 3232b15cb3dSCy Schubert<code>server</code> 3242b15cb3dSCy Schubertcommand and s addresses and when 3252b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 3262b15cb3dSCy Schubertis started with the 3272b15cb3dSCy Schubert<code>-q</code> 3282b15cb3dSCy Schubertoption. 3292b15cb3dSCy Schubert<br><dt><code>key</code> <kbd>key</kbd><dd>All packets sent to and received from the server or peer are to 3302b15cb3dSCy Schubertinclude authentication fields encrypted using the specified 3312b15cb3dSCy Schubert<kbd>key</kbd> 332*4e1ef62aSXin LIidentifier with values from 1 to 65535, inclusive. 3332b15cb3dSCy SchubertThe 3342b15cb3dSCy Schubertdefault is to include no encryption field. 3352b15cb3dSCy 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 3362b15cb3dSCy Schubertfor NTP messages, as a power of 2 in seconds 3372b15cb3dSCy SchubertThe maximum poll 3382b15cb3dSCy Schubertinterval defaults to 10 (1,024 s), but can be increased by the 3392b15cb3dSCy Schubert<code>maxpoll</code> 3402b15cb3dSCy Schubertoption to an upper limit of 17 (36.4 h). 3412b15cb3dSCy SchubertThe 3422b15cb3dSCy Schubertminimum poll interval defaults to 6 (64 s), but can be decreased by 3432b15cb3dSCy Schubertthe 3442b15cb3dSCy Schubert<code>minpoll</code> 3452b15cb3dSCy Schubertoption to a lower limit of 4 (16 s). 3462b15cb3dSCy Schubert<br><dt><code>noselect</code><dd>Marks the server as unused, except for display purposes. 3472b15cb3dSCy SchubertThe server is discarded by the selection algroithm. 3484990d495SXin LI<br><dt><code>preempt</code><dd>Says the association can be preempted. 3494990d495SXin LI<br><dt><code>true</code><dd>Marks the server as a truechimer. 350e27abb66SXin LIUse this option only for testing. 3512b15cb3dSCy Schubert<br><dt><code>prefer</code><dd>Marks the server as preferred. 3522b15cb3dSCy SchubertAll other things being equal, 3532b15cb3dSCy Schubertthis host will be chosen for synchronization among a set of 3542b15cb3dSCy Schubertcorrectly operating hosts. 3552b15cb3dSCy SchubertSee the 3562b15cb3dSCy Schubert"Mitigation Rules and the prefer Keyword" 3572b15cb3dSCy Schubertpage 3582b15cb3dSCy Schubert(available as part of the HTML documentation 3592b15cb3dSCy Schubertprovided in 3602b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 3612b15cb3dSCy Schubertfor further information. 362e27abb66SXin LI<br><dt><code>true</code><dd>Forces the association to always survive the selection and clustering algorithms. 363e27abb66SXin LIThis option should almost certainly 364e27abb66SXin LI<em>only</em> 365e27abb66SXin LIbe used while testing an association. 3662b15cb3dSCy Schubert<br><dt><code>ttl</code> <kbd>ttl</kbd><dd>This option is used only with broadcast server and manycast 3672b15cb3dSCy Schubertclient modes. 3682b15cb3dSCy SchubertIt specifies the time-to-live 3692b15cb3dSCy Schubert<kbd>ttl</kbd> 3702b15cb3dSCy Schubertto 3712b15cb3dSCy Schubertuse on broadcast server and multicast server and the maximum 3722b15cb3dSCy Schubert<kbd>ttl</kbd> 3732b15cb3dSCy Schubertfor the expanding ring search with manycast 3742b15cb3dSCy Schubertclient packets. 3752b15cb3dSCy SchubertSelection of the proper value, which defaults to 3762b15cb3dSCy Schubert127, is something of a black art and should be coordinated with the 3772b15cb3dSCy Schubertnetwork administrator. 3782b15cb3dSCy Schubert<br><dt><code>version</code> <kbd>version</kbd><dd>Specifies the version number to be used for outgoing NTP 3792b15cb3dSCy Schubertpackets. 3802b15cb3dSCy SchubertVersions 1-4 are the choices, with version 4 the 3812b15cb3dSCy Schubertdefault. 3824990d495SXin LI<br><dt><code>xleave</code><dd>Valid in 3834990d495SXin LI<code>peer</code> 3844990d495SXin LIand 3854990d495SXin LI<code>broadcast</code> 3864990d495SXin LImodes only, this flag enables interleave mode. 3872b15cb3dSCy Schubert</dl> 3882b15cb3dSCy Schubert 3892b15cb3dSCy Schubert<h5 class="subsubsection">Auxiliary Commands</h5> 3902b15cb3dSCy Schubert 3912b15cb3dSCy Schubert <dl> 3922b15cb3dSCy Schubert<dt><code>broadcastclient</code><dd>This command enables reception of broadcast server messages to 3932b15cb3dSCy Schubertany local interface (type b) address. 3942b15cb3dSCy SchubertUpon receiving a message for 3952b15cb3dSCy Schubertthe first time, the broadcast client measures the nominal server 3962b15cb3dSCy Schubertpropagation delay using a brief client/server exchange with the 3972b15cb3dSCy Schubertserver, then enters the broadcast client mode, in which it 3982b15cb3dSCy Schubertsynchronizes to succeeding broadcast messages. 3992b15cb3dSCy SchubertNote that, in order 4002b15cb3dSCy Schubertto avoid accidental or malicious disruption in this mode, both the 4012b15cb3dSCy Schubertserver and client should operate using symmetric-key or public-key 4022b15cb3dSCy Schubertauthentication as described in 4032b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 4042b15cb3dSCy Schubert<br><dt><code>manycastserver</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of manycast client messages to 4052b15cb3dSCy Schubertthe multicast group address(es) (type m) specified. 4062b15cb3dSCy SchubertAt least one 4072b15cb3dSCy Schubertaddress is required, but the NTP multicast address 224.0.1.1 4082b15cb3dSCy Schubertassigned by the IANA should NOT be used, unless specific means are 4092b15cb3dSCy Schuberttaken to limit the span of the reply and avoid a possibly massive 4102b15cb3dSCy Schubertimplosion at the original sender. 4112b15cb3dSCy SchubertNote that, in order to avoid 4122b15cb3dSCy Schubertaccidental or malicious disruption in this mode, both the server 4132b15cb3dSCy Schubertand client should operate using symmetric-key or public-key 4142b15cb3dSCy Schubertauthentication as described in 4152b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 4162b15cb3dSCy Schubert<br><dt><code>multicastclient</code> <kbd>address</kbd> <kbd>...</kbd><dd>This command enables reception of multicast server messages to 4172b15cb3dSCy Schubertthe multicast group address(es) (type m) specified. 4182b15cb3dSCy SchubertUpon receiving 4192b15cb3dSCy Schuberta message for the first time, the multicast client measures the 4202b15cb3dSCy Schubertnominal server propagation delay using a brief client/server 4212b15cb3dSCy Schubertexchange with the server, then enters the broadcast client mode, in 4222b15cb3dSCy Schubertwhich it synchronizes to succeeding multicast messages. 4232b15cb3dSCy SchubertNote that, 4242b15cb3dSCy Schubertin order to avoid accidental or malicious disruption in this mode, 4252b15cb3dSCy Schubertboth the server and client should operate using symmetric-key or 4262b15cb3dSCy Schubertpublic-key authentication as described in 4272b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a>. 4282b15cb3dSCy Schubert<br><dt><code>mdnstries</code> <kbd>number</kbd><dd>If we are participating in mDNS, 4292b15cb3dSCy Schubertafter we have synched for the first time 4302b15cb3dSCy Schubertwe attempt to register with the mDNS system. 4312b15cb3dSCy SchubertIf that registration attempt fails, 4322b15cb3dSCy Schubertwe try again at one minute intervals for up to 4332b15cb3dSCy Schubert<code>mdnstries</code> 4342b15cb3dSCy Schuberttimes. 4352b15cb3dSCy SchubertAfter all, 4362b15cb3dSCy Schubert<code>ntpd</code> 4372b15cb3dSCy Schubertmay be starting before mDNS. 4382b15cb3dSCy SchubertThe default value for 4392b15cb3dSCy Schubert<code>mdnstries</code> 4402b15cb3dSCy Schubertis 5. 4412b15cb3dSCy Schubert</dl> 4422b15cb3dSCy Schubert<div class="node"> 4432b15cb3dSCy Schubert<p><hr> 4442b15cb3dSCy Schubert<a name="Authentication-Support"></a> 4452b15cb3dSCy Schubert<br> 4462b15cb3dSCy Schubert</div> 4472b15cb3dSCy Schubert 4482b15cb3dSCy Schubert<h4 class="subsection">Authentication Support</h4> 4492b15cb3dSCy Schubert 4502b15cb3dSCy Schubert<p>Authentication support allows the NTP client to verify that the 4512b15cb3dSCy Schubertserver is in fact known and trusted and not an intruder intending 4522b15cb3dSCy Schubertaccidentally or on purpose to masquerade as that server. 4532b15cb3dSCy SchubertThe NTPv3 4542b15cb3dSCy Schubertspecification RFC-1305 defines a scheme which provides 4552b15cb3dSCy Schubertcryptographic authentication of received NTP packets. 4562b15cb3dSCy SchubertOriginally, 4572b15cb3dSCy Schubertthis was done using the Data Encryption Standard (DES) algorithm 4582b15cb3dSCy Schubertoperating in Cipher Block Chaining (CBC) mode, commonly called 4592b15cb3dSCy SchubertDES-CBC. 4602b15cb3dSCy SchubertSubsequently, this was replaced by the RSA Message Digest 4612b15cb3dSCy Schubert5 (MD5) algorithm using a private key, commonly called keyed-MD5. 4622b15cb3dSCy SchubertEither algorithm computes a message digest, or one-way hash, which 4632b15cb3dSCy Schubertcan be used to verify the server has the correct private key and 4642b15cb3dSCy Schubertkey identifier. 4652b15cb3dSCy Schubert 4662b15cb3dSCy Schubert <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key 4672b15cb3dSCy Schubertcryptography and, in addition, provides a new Autokey scheme 4682b15cb3dSCy Schubertbased on public key cryptography. 4692b15cb3dSCy SchubertPublic key cryptography is generally considered more secure 4702b15cb3dSCy Schubertthan symmetric key cryptography, since the security is based 4712b15cb3dSCy Schuberton a private value which is generated by each server and 4722b15cb3dSCy Schubertnever revealed. 4732b15cb3dSCy SchubertWith Autokey all key distribution and 4742b15cb3dSCy Schubertmanagement functions involve only public values, which 4752b15cb3dSCy Schubertconsiderably simplifies key distribution and storage. 4762b15cb3dSCy SchubertPublic key management is based on X.509 certificates, 4772b15cb3dSCy Schubertwhich can be provided by commercial services or 4782b15cb3dSCy Schubertproduced by utility programs in the OpenSSL software library 4792b15cb3dSCy Schubertor the NTPv4 distribution. 4802b15cb3dSCy Schubert 4812b15cb3dSCy Schubert <p>While the algorithms for symmetric key cryptography are 4822b15cb3dSCy Schubertincluded in the NTPv4 distribution, public key cryptography 4832b15cb3dSCy Schubertrequires the OpenSSL software library to be installed 4842b15cb3dSCy Schubertbefore building the NTP distribution. 4852b15cb3dSCy SchubertDirections for doing that 4862b15cb3dSCy Schubertare on the Building and Installing the Distribution page. 4872b15cb3dSCy Schubert 4882b15cb3dSCy Schubert <p>Authentication is configured separately for each association 4892b15cb3dSCy Schubertusing the 4902b15cb3dSCy Schubert<code>key</code> 4912b15cb3dSCy Schubertor 4922b15cb3dSCy Schubert<code>autokey</code> 4932b15cb3dSCy Schubertsubcommand on the 4942b15cb3dSCy Schubert<code>peer</code>, 4952b15cb3dSCy Schubert<code>server</code>, 4962b15cb3dSCy Schubert<code>broadcast</code> 4972b15cb3dSCy Schubertand 4982b15cb3dSCy Schubert<code>manycastclient</code> 4992b15cb3dSCy Schubertconfiguration commands as described in 5002b15cb3dSCy Schubert<a href="#Configuration-Options">Configuration Options</a> 5012b15cb3dSCy Schubertpage. 5022b15cb3dSCy SchubertThe authentication 5032b15cb3dSCy Schubertoptions described below specify the locations of the key files, 5042b15cb3dSCy Schubertif other than default, which symmetric keys are trusted 5052b15cb3dSCy Schubertand the interval between various operations, if other than default. 5062b15cb3dSCy Schubert 5072b15cb3dSCy Schubert <p>Authentication is always enabled, 5082b15cb3dSCy Schubertalthough ineffective if not configured as 5092b15cb3dSCy Schubertdescribed below. 5102b15cb3dSCy SchubertIf a NTP packet arrives 5112b15cb3dSCy Schubertincluding a message authentication 5122b15cb3dSCy Schubertcode (MAC), it is accepted only if it 5132b15cb3dSCy Schubertpasses all cryptographic checks. 5142b15cb3dSCy SchubertThe 5152b15cb3dSCy Schubertchecks require correct key ID, key value 5162b15cb3dSCy Schubertand message digest. 5172b15cb3dSCy SchubertIf the packet has 5182b15cb3dSCy Schubertbeen modified in any way or replayed 5192b15cb3dSCy Schubertby an intruder, it will fail one or more 5202b15cb3dSCy Schubertof these checks and be discarded. 5212b15cb3dSCy SchubertFurthermore, the Autokey scheme requires a 5222b15cb3dSCy Schubertpreliminary protocol exchange to obtain 5232b15cb3dSCy Schubertthe server certificate, verify its 5242b15cb3dSCy Schubertcredentials and initialize the protocol 5252b15cb3dSCy Schubert 5262b15cb3dSCy Schubert <p>The 5272b15cb3dSCy Schubert<code>auth</code> 5282b15cb3dSCy Schubertflag controls whether new associations or 5292b15cb3dSCy Schubertremote configuration commands require cryptographic authentication. 5302b15cb3dSCy SchubertThis flag can be set or reset by the 5312b15cb3dSCy Schubert<code>enable</code> 5322b15cb3dSCy Schubertand 5332b15cb3dSCy Schubert<code>disable</code> 5342b15cb3dSCy Schubertcommands and also by remote 5352b15cb3dSCy Schubertconfiguration commands sent by a 5362b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 537e27abb66SXin LIprogram running on 5382b15cb3dSCy Schubertanother machine. 5392b15cb3dSCy SchubertIf this flag is enabled, which is the default 5402b15cb3dSCy Schubertcase, new broadcast client and symmetric passive associations and 5412b15cb3dSCy Schubertremote configuration commands must be cryptographically 5422b15cb3dSCy Schubertauthenticated using either symmetric key or public key cryptography. 5432b15cb3dSCy SchubertIf this 5442b15cb3dSCy Schubertflag is disabled, these operations are effective 5452b15cb3dSCy Schuberteven if not cryptographic 5462b15cb3dSCy Schubertauthenticated. 5472b15cb3dSCy SchubertIt should be understood 5482b15cb3dSCy Schubertthat operating with the 5492b15cb3dSCy Schubert<code>auth</code> 5502b15cb3dSCy Schubertflag disabled invites a significant vulnerability 5512b15cb3dSCy Schubertwhere a rogue hacker can 5522b15cb3dSCy Schubertmasquerade as a falseticker and seriously 5532b15cb3dSCy Schubertdisrupt system timekeeping. 5542b15cb3dSCy SchubertIt is 5552b15cb3dSCy Schubertimportant to note that this flag has no purpose 5562b15cb3dSCy Schubertother than to allow or disallow 5572b15cb3dSCy Schuberta new association in response to new broadcast 5582b15cb3dSCy Schubertand symmetric active messages 5592b15cb3dSCy Schubertand remote configuration commands and, in particular, 5602b15cb3dSCy Schubertthe flag has no effect on 5612b15cb3dSCy Schubertthe authentication process itself. 5622b15cb3dSCy Schubert 5632b15cb3dSCy Schubert <p>An attractive alternative where multicast support is available 5642b15cb3dSCy Schubertis manycast mode, in which clients periodically troll 5652b15cb3dSCy Schubertfor servers as described in the 5662b15cb3dSCy Schubert<a href="#Automatic-NTP-Configuration-Options">Automatic NTP Configuration Options</a> 5672b15cb3dSCy Schubertpage. 5682b15cb3dSCy SchubertEither symmetric key or public key 5692b15cb3dSCy Schubertcryptographic authentication can be used in this mode. 5702b15cb3dSCy SchubertThe principle advantage 5712b15cb3dSCy Schubertof manycast mode is that potential servers need not be 5722b15cb3dSCy Schubertconfigured in advance, 5732b15cb3dSCy Schubertsince the client finds them during regular operation, 5742b15cb3dSCy Schubertand the configuration 5752b15cb3dSCy Schubertfiles for all clients can be identical. 5762b15cb3dSCy Schubert 5772b15cb3dSCy Schubert <p>The security model and protocol schemes for 5782b15cb3dSCy Schubertboth symmetric key and public key 5792b15cb3dSCy Schubertcryptography are summarized below; 5802b15cb3dSCy Schubertfurther details are in the briefings, papers 5812b15cb3dSCy Schubertand reports at the NTP project page linked from 5822b15cb3dSCy Schubert<code>http://www.ntp.org/</code>. 5832b15cb3dSCy Schubert 5842b15cb3dSCy Schubert<h5 class="subsubsection">Symmetric-Key Cryptography</h5> 5852b15cb3dSCy Schubert 5862b15cb3dSCy Schubert<p>The original RFC-1305 specification allows any one of possibly 587*4e1ef62aSXin LI65,535 keys, each distinguished by a 32-bit key identifier, to 5882b15cb3dSCy Schubertauthenticate an association. 5892b15cb3dSCy SchubertThe servers and clients involved must 5902b15cb3dSCy Schubertagree on the key and key identifier to 5912b15cb3dSCy Schubertauthenticate NTP packets. 5922b15cb3dSCy SchubertKeys and 5932b15cb3dSCy Schubertrelated information are specified in a key 5942b15cb3dSCy Schubertfile, usually called 5952b15cb3dSCy Schubert<span class="file">ntp.keys</span>, 5962b15cb3dSCy Schubertwhich must be distributed and stored using 5972b15cb3dSCy Schubertsecure means beyond the scope of the NTP protocol itself. 5982b15cb3dSCy SchubertBesides the keys used 5992b15cb3dSCy Schubertfor ordinary NTP associations, 6002b15cb3dSCy Schubertadditional keys can be used as passwords for the 6012b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 6022b15cb3dSCy Schubertand 6032b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 6042b15cb3dSCy Schubertutility programs. 6052b15cb3dSCy Schubert 6062b15cb3dSCy Schubert <p>When 6072b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 6082b15cb3dSCy Schubertis first started, it reads the key file specified in the 6092b15cb3dSCy Schubert<code>keys</code> 6102b15cb3dSCy Schubertconfiguration command and installs the keys 6112b15cb3dSCy Schubertin the key cache. 6122b15cb3dSCy SchubertHowever, 6132b15cb3dSCy Schubertindividual keys must be activated with the 6142b15cb3dSCy Schubert<code>trusted</code> 6152b15cb3dSCy Schubertcommand before use. 6162b15cb3dSCy SchubertThis 6172b15cb3dSCy Schubertallows, for instance, the installation of possibly 6182b15cb3dSCy Schubertseveral batches of keys and 6192b15cb3dSCy Schubertthen activating or deactivating each batch 6202b15cb3dSCy Schubertremotely using 6212b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code>. 6222b15cb3dSCy SchubertThis also provides a revocation capability that can be used 6232b15cb3dSCy Schubertif a key becomes compromised. 6242b15cb3dSCy SchubertThe 6252b15cb3dSCy Schubert<code>requestkey</code> 6262b15cb3dSCy Schubertcommand selects the key used as the password for the 6272b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 6282b15cb3dSCy Schubertutility, while the 6292b15cb3dSCy Schubert<code>controlkey</code> 6302b15cb3dSCy Schubertcommand selects the key used as the password for the 6312b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 6322b15cb3dSCy Schubertutility. 6332b15cb3dSCy Schubert 6342b15cb3dSCy Schubert<h5 class="subsubsection">Public Key Cryptography</h5> 6352b15cb3dSCy Schubert 6362b15cb3dSCy Schubert<p>NTPv4 supports the original NTPv3 symmetric key scheme 6372b15cb3dSCy Schubertdescribed in RFC-1305 and in addition the Autokey protocol, 6382b15cb3dSCy Schubertwhich is based on public key cryptography. 6392b15cb3dSCy SchubertThe Autokey Version 2 protocol described on the Autokey Protocol 6402b15cb3dSCy Schubertpage verifies packet integrity using MD5 message digests 6412b15cb3dSCy Schubertand verifies the source with digital signatures and any of several 6422b15cb3dSCy Schubertdigest/signature schemes. 6432b15cb3dSCy SchubertOptional identity schemes described on the Identity Schemes 6442b15cb3dSCy Schubertpage and based on cryptographic challenge/response algorithms 6452b15cb3dSCy Schubertare also available. 6462b15cb3dSCy SchubertUsing all of these schemes provides strong security against 6472b15cb3dSCy Schubertreplay with or without modification, spoofing, masquerade 6482b15cb3dSCy Schubertand most forms of clogging attacks. 6492b15cb3dSCy Schubert 6502b15cb3dSCy Schubert <p>The Autokey protocol has several modes of operation 6512b15cb3dSCy Schubertcorresponding to the various NTP modes supported. 6522b15cb3dSCy SchubertMost modes use a special cookie which can be 6532b15cb3dSCy Schubertcomputed independently by the client and server, 6542b15cb3dSCy Schubertbut encrypted in transmission. 6552b15cb3dSCy SchubertAll modes use in addition a variant of the S-KEY scheme, 6562b15cb3dSCy Schubertin which a pseudo-random key list is generated and used 6572b15cb3dSCy Schubertin reverse order. 6582b15cb3dSCy SchubertThese schemes are described along with an executive summary, 6592b15cb3dSCy Schubertcurrent status, briefing slides and reading list on the 6602b15cb3dSCy Schubert<a href="#Autonomous-Authentication">Autonomous Authentication</a> 6612b15cb3dSCy Schubertpage. 6622b15cb3dSCy Schubert 6632b15cb3dSCy Schubert <p>The specific cryptographic environment used by Autokey servers 6642b15cb3dSCy Schubertand clients is determined by a set of files 6652b15cb3dSCy Schubertand soft links generated by the 6662b15cb3dSCy Schubert<code>ntp-keygen(1ntpkeygenmdoc)</code> 6672b15cb3dSCy Schubertprogram. 6682b15cb3dSCy SchubertThis includes a required host key file, 6692b15cb3dSCy Schubertrequired certificate file and optional sign key file, 6702b15cb3dSCy Schubertleapsecond file and identity scheme files. 6712b15cb3dSCy SchubertThe 6722b15cb3dSCy Schubertdigest/signature scheme is specified in the X.509 certificate 6732b15cb3dSCy Schubertalong with the matching sign key. 6742b15cb3dSCy SchubertThere are several schemes 6752b15cb3dSCy Schubertavailable in the OpenSSL software library, each identified 6762b15cb3dSCy Schubertby a specific string such as 6772b15cb3dSCy Schubert<code>md5WithRSAEncryption</code>, 6782b15cb3dSCy Schubertwhich stands for the MD5 message digest with RSA 6792b15cb3dSCy Schubertencryption scheme. 6802b15cb3dSCy SchubertThe current NTP distribution supports 6812b15cb3dSCy Schubertall the schemes in the OpenSSL library, including 6822b15cb3dSCy Schubertthose based on RSA and DSA digital signatures. 6832b15cb3dSCy Schubert 6842b15cb3dSCy Schubert <p>NTP secure groups can be used to define cryptographic compartments 6852b15cb3dSCy Schubertand security hierarchies. 6862b15cb3dSCy SchubertIt is important that every host 6872b15cb3dSCy Schubertin the group be able to construct a certificate trail to one 6882b15cb3dSCy Schubertor more trusted hosts in the same group. 6892b15cb3dSCy SchubertEach group 6902b15cb3dSCy Schuberthost runs the Autokey protocol to obtain the certificates 6912b15cb3dSCy Schubertfor all hosts along the trail to one or more trusted hosts. 6922b15cb3dSCy SchubertThis requires the configuration file in all hosts to be 6932b15cb3dSCy Schubertengineered so that, even under anticipated failure conditions, 6942b15cb3dSCy Schubertthe NTP subnet will form such that every group host can find 6952b15cb3dSCy Schuberta trail to at least one trusted host. 6962b15cb3dSCy Schubert 6972b15cb3dSCy Schubert<h5 class="subsubsection">Naming and Addressing</h5> 6982b15cb3dSCy Schubert 6992b15cb3dSCy Schubert<p>It is important to note that Autokey does not use DNS to 7002b15cb3dSCy Schubertresolve addresses, since DNS can't be completely trusted 7012b15cb3dSCy Schubertuntil the name servers have synchronized clocks. 7022b15cb3dSCy SchubertThe cryptographic name used by Autokey to bind the host identity 7032b15cb3dSCy Schubertcredentials and cryptographic values must be independent 7042b15cb3dSCy Schubertof interface, network and any other naming convention. 7052b15cb3dSCy SchubertThe name appears in the host certificate in either or both 7062b15cb3dSCy Schubertthe subject and issuer fields, so protection against 7072b15cb3dSCy SchubertDNS compromise is essential. 7082b15cb3dSCy Schubert 7092b15cb3dSCy Schubert <p>By convention, the name of an Autokey host is the name returned 7102b15cb3dSCy Schubertby the Unix 7112b15cb3dSCy Schubert<code>gethostname(2)</code> 7122b15cb3dSCy Schubertsystem call or equivalent in other systems. 7132b15cb3dSCy SchubertBy the system design 7142b15cb3dSCy Schubertmodel, there are no provisions to allow alternate names or aliases. 7152b15cb3dSCy SchubertHowever, this is not to say that DNS aliases, different names 7162b15cb3dSCy Schubertfor each interface, etc., are constrained in any way. 7172b15cb3dSCy Schubert 7182b15cb3dSCy Schubert <p>It is also important to note that Autokey verifies authenticity 7192b15cb3dSCy Schubertusing the host name, network address and public keys, 7202b15cb3dSCy Schubertall of which are bound together by the protocol specifically 7212b15cb3dSCy Schubertto deflect masquerade attacks. 7222b15cb3dSCy SchubertFor this reason Autokey 723e27abb66SXin LIincludes the source and destination IP addresses in message digest 7242b15cb3dSCy Schubertcomputations and so the same addresses must be available 7252b15cb3dSCy Schubertat both the server and client. 7262b15cb3dSCy SchubertFor this reason operation 7272b15cb3dSCy Schubertwith network address translation schemes is not possible. 7282b15cb3dSCy SchubertThis reflects the intended robust security model where government 7292b15cb3dSCy Schubertand corporate NTP servers are operated outside firewall perimeters. 7302b15cb3dSCy Schubert 7312b15cb3dSCy Schubert<h5 class="subsubsection">Operation</h5> 7322b15cb3dSCy Schubert 7332b15cb3dSCy Schubert<p>A specific combination of authentication scheme (none, 7342b15cb3dSCy Schubertsymmetric key, public key) and identity scheme is called 7352b15cb3dSCy Schuberta cryptotype, although not all combinations are compatible. 7362b15cb3dSCy SchubertThere may be management configurations where the clients, 7372b15cb3dSCy Schubertservers and peers may not all support the same cryptotypes. 7382b15cb3dSCy SchubertA secure NTPv4 subnet can be configured in many ways while 7392b15cb3dSCy Schubertkeeping in mind the principles explained above and 7402b15cb3dSCy Schubertin this section. 7412b15cb3dSCy SchubertNote however that some cryptotype 7422b15cb3dSCy Schubertcombinations may successfully interoperate with each other, 7432b15cb3dSCy Schubertbut may not represent good security practice. 7442b15cb3dSCy Schubert 7452b15cb3dSCy Schubert <p>The cryptotype of an association is determined at the time 7462b15cb3dSCy Schubertof mobilization, either at configuration time or some time 7472b15cb3dSCy Schubertlater when a message of appropriate cryptotype arrives. 7482b15cb3dSCy SchubertWhen mobilized by a 7492b15cb3dSCy Schubert<code>server</code> 7502b15cb3dSCy Schubertor 7512b15cb3dSCy Schubert<code>peer</code> 7522b15cb3dSCy Schubertconfiguration command and no 7532b15cb3dSCy Schubert<code>key</code> 7542b15cb3dSCy Schubertor 7552b15cb3dSCy Schubert<code>autokey</code> 7562b15cb3dSCy Schubertsubcommands are present, the association is not 7572b15cb3dSCy Schubertauthenticated; if the 7582b15cb3dSCy Schubert<code>key</code> 7592b15cb3dSCy Schubertsubcommand is present, the association is authenticated 7602b15cb3dSCy Schubertusing the symmetric key ID specified; if the 7612b15cb3dSCy Schubert<code>autokey</code> 7622b15cb3dSCy Schubertsubcommand is present, the association is authenticated 7632b15cb3dSCy Schubertusing Autokey. 7642b15cb3dSCy Schubert 7652b15cb3dSCy Schubert <p>When multiple identity schemes are supported in the Autokey 7662b15cb3dSCy Schubertprotocol, the first message exchange determines which one is used. 7672b15cb3dSCy SchubertThe client request message contains bits corresponding 7682b15cb3dSCy Schubertto which schemes it has available. 7692b15cb3dSCy SchubertThe server response message 7702b15cb3dSCy Schubertcontains bits corresponding to which schemes it has available. 7712b15cb3dSCy SchubertBoth server and client match the received bits with their own 7722b15cb3dSCy Schubertand select a common scheme. 7732b15cb3dSCy Schubert 7742b15cb3dSCy Schubert <p>Following the principle that time is a public value, 7752b15cb3dSCy Schuberta server responds to any client packet that matches 7762b15cb3dSCy Schubertits cryptotype capabilities. 7772b15cb3dSCy SchubertThus, a server receiving 7782b15cb3dSCy Schubertan unauthenticated packet will respond with an unauthenticated 7792b15cb3dSCy Schubertpacket, while the same server receiving a packet of a cryptotype 7802b15cb3dSCy Schubertit supports will respond with packets of that cryptotype. 7812b15cb3dSCy SchubertHowever, unconfigured broadcast or manycast client 7822b15cb3dSCy Schubertassociations or symmetric passive associations will not be 7832b15cb3dSCy Schubertmobilized unless the server supports a cryptotype compatible 7842b15cb3dSCy Schubertwith the first packet received. 7852b15cb3dSCy SchubertBy default, unauthenticated associations will not be mobilized 7862b15cb3dSCy Schubertunless overridden in a decidedly dangerous way. 7872b15cb3dSCy Schubert 7882b15cb3dSCy Schubert <p>Some examples may help to reduce confusion. 7892b15cb3dSCy SchubertClient Alice has no specific cryptotype selected. 7902b15cb3dSCy SchubertServer Bob has both a symmetric key file and minimal Autokey files. 7912b15cb3dSCy SchubertAlice's unauthenticated messages arrive at Bob, who replies with 7922b15cb3dSCy Schubertunauthenticated messages. 7932b15cb3dSCy SchubertCathy has a copy of Bob's symmetric 7942b15cb3dSCy Schubertkey file and has selected key ID 4 in messages to Bob. 7952b15cb3dSCy SchubertBob verifies the message with his key ID 4. 7962b15cb3dSCy SchubertIf it's the 7972b15cb3dSCy Schubertsame key and the message is verified, Bob sends Cathy a reply 7982b15cb3dSCy Schubertauthenticated with that key. 7992b15cb3dSCy SchubertIf verification fails, 8002b15cb3dSCy SchubertBob sends Cathy a thing called a crypto-NAK, which tells her 8012b15cb3dSCy Schubertsomething broke. 8022b15cb3dSCy SchubertShe can see the evidence using the 8032b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 8042b15cb3dSCy Schubertprogram. 8052b15cb3dSCy Schubert 8062b15cb3dSCy Schubert <p>Denise has rolled her own host key and certificate. 8072b15cb3dSCy SchubertShe also uses one of the identity schemes as Bob. 8082b15cb3dSCy SchubertShe sends the first Autokey message to Bob and they 8092b15cb3dSCy Schubertboth dance the protocol authentication and identity steps. 8102b15cb3dSCy SchubertIf all comes out okay, Denise and Bob continue as described above. 8112b15cb3dSCy Schubert 8122b15cb3dSCy Schubert <p>It should be clear from the above that Bob can support 8132b15cb3dSCy Schubertall the girls at the same time, as long as he has compatible 8142b15cb3dSCy Schubertauthentication and identity credentials. 8152b15cb3dSCy SchubertNow, Bob can act just like the girls in his own choice of servers; 8162b15cb3dSCy Schuberthe can run multiple configured associations with multiple different 8172b15cb3dSCy Schubertservers (or the same server, although that might not be useful). 8182b15cb3dSCy SchubertBut, wise security policy might preclude some cryptotype 8192b15cb3dSCy Schubertcombinations; for instance, running an identity scheme 8202b15cb3dSCy Schubertwith one server and no authentication with another might not be wise. 8212b15cb3dSCy Schubert 8222b15cb3dSCy Schubert<h5 class="subsubsection">Key Management</h5> 8232b15cb3dSCy Schubert 8242b15cb3dSCy Schubert<p>The cryptographic values used by the Autokey protocol are 8252b15cb3dSCy Schubertincorporated as a set of files generated by the 8262b15cb3dSCy Schubert<code>ntp-keygen(1ntpkeygenmdoc)</code> 8272b15cb3dSCy Schubertutility program, including symmetric key, host key and 8282b15cb3dSCy Schubertpublic certificate files, as well as sign key, identity parameters 8292b15cb3dSCy Schubertand leapseconds files. 8302b15cb3dSCy SchubertAlternatively, host and sign keys and 8312b15cb3dSCy Schubertcertificate files can be generated by the OpenSSL utilities 8322b15cb3dSCy Schubertand certificates can be imported from public certificate 8332b15cb3dSCy Schubertauthorities. 8342b15cb3dSCy SchubertNote that symmetric keys are necessary for the 8352b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 8362b15cb3dSCy Schubertand 8372b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 8382b15cb3dSCy Schubertutility programs. 8392b15cb3dSCy SchubertThe remaining files are necessary only for the 8402b15cb3dSCy SchubertAutokey protocol. 8412b15cb3dSCy Schubert 8422b15cb3dSCy Schubert <p>Certificates imported from OpenSSL or public certificate 8432b15cb3dSCy Schubertauthorities have certian limitations. 8442b15cb3dSCy SchubertThe certificate should be in ASN.1 syntax, X.509 Version 3 8452b15cb3dSCy Schubertformat and encoded in PEM, which is the same format 8462b15cb3dSCy Schubertused by OpenSSL. 8472b15cb3dSCy SchubertThe overall length of the certificate encoded 8482b15cb3dSCy Schubertin ASN.1 must not exceed 1024 bytes. 8492b15cb3dSCy SchubertThe subject distinguished 8502b15cb3dSCy Schubertname field (CN) is the fully qualified name of the host 8512b15cb3dSCy Schuberton which it is used; the remaining subject fields are ignored. 8522b15cb3dSCy SchubertThe certificate extension fields must not contain either 8532b15cb3dSCy Schuberta subject key identifier or a issuer key identifier field; 8542b15cb3dSCy Schuberthowever, an extended key usage field for a trusted host must 8552b15cb3dSCy Schubertcontain the value 8562b15cb3dSCy Schubert<code>trustRoot</code>;. 8572b15cb3dSCy SchubertOther extension fields are ignored. 8582b15cb3dSCy Schubert 8592b15cb3dSCy Schubert<h5 class="subsubsection">Authentication Commands</h5> 8602b15cb3dSCy Schubert 8612b15cb3dSCy Schubert <dl> 8622b15cb3dSCy Schubert<dt><code>autokey</code> <code>[</code><kbd>logsec</kbd><code>]</code><dd>Specifies the interval between regenerations of the session key 8632b15cb3dSCy Schubertlist used with the Autokey protocol. 8642b15cb3dSCy SchubertNote that the size of the key 8652b15cb3dSCy Schubertlist for each association depends on this interval and the current 8662b15cb3dSCy Schubertpoll interval. 8672b15cb3dSCy SchubertThe default value is 12 (4096 s or about 1.1 hours). 8682b15cb3dSCy SchubertFor poll intervals above the specified interval, a session key list 8692b15cb3dSCy Schubertwith a single entry will be regenerated for every message 8702b15cb3dSCy Schubertsent. 8712b15cb3dSCy Schubert<br><dt><code>controlkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the 8722b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 8732b15cb3dSCy Schubertutility, which uses the standard 8742b15cb3dSCy Schubertprotocol defined in RFC-1305. 8752b15cb3dSCy SchubertThe 8762b15cb3dSCy Schubert<kbd>key</kbd> 8772b15cb3dSCy Schubertargument is 8782b15cb3dSCy Schubertthe key identifier for a trusted key, where the value can be in the 879*4e1ef62aSXin LIrange 1 to 65,535, inclusive. 8802b15cb3dSCy 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. 8812b15cb3dSCy SchubertIt activates public key 8822b15cb3dSCy Schubertcryptography, selects the message digest and signature 8832b15cb3dSCy Schubertencryption scheme and loads the required private and public 8842b15cb3dSCy Schubertvalues described above. 8852b15cb3dSCy SchubertIf one or more files are left unspecified, 8862b15cb3dSCy Schubertthe default names are used as described above. 8872b15cb3dSCy SchubertUnless the complete path and name of the file are specified, the 8882b15cb3dSCy Schubertlocation of a file is relative to the keys directory specified 8892b15cb3dSCy Schubertin the 8902b15cb3dSCy Schubert<code>keysdir</code> 8912b15cb3dSCy Schubertcommand or default 8922b15cb3dSCy Schubert<span class="file">/usr/local/etc</span>. 8932b15cb3dSCy SchubertFollowing are the subcommands: 8942b15cb3dSCy Schubert <dl> 8952b15cb3dSCy Schubert<dt><code>cert</code> <kbd>file</kbd><dd>Specifies the location of the required host public certificate file. 8962b15cb3dSCy SchubertThis overrides the link 8972b15cb3dSCy Schubert<span class="file">ntpkey_cert_</span><kbd>hostname</kbd> 8982b15cb3dSCy Schubertin the keys directory. 8992b15cb3dSCy Schubert<br><dt><code>gqpar</code> <kbd>file</kbd><dd>Specifies the location of the optional GQ parameters file. 9002b15cb3dSCy SchubertThis 9012b15cb3dSCy Schubertoverrides the link 9022b15cb3dSCy Schubert<span class="file">ntpkey_gq_</span><kbd>hostname</kbd> 9032b15cb3dSCy Schubertin the keys directory. 9042b15cb3dSCy Schubert<br><dt><code>host</code> <kbd>file</kbd><dd>Specifies the location of the required host key file. 9052b15cb3dSCy SchubertThis overrides 9062b15cb3dSCy Schubertthe link 9072b15cb3dSCy Schubert<span class="file">ntpkey_key_</span><kbd>hostname</kbd> 9082b15cb3dSCy Schubertin the keys directory. 909e27abb66SXin LI<br><dt><code>iffpar</code> <kbd>file</kbd><dd>Specifies the location of the optional IFF parameters file. 910e27abb66SXin LIThis overrides the link 9112b15cb3dSCy Schubert<span class="file">ntpkey_iff_</span><kbd>hostname</kbd> 9122b15cb3dSCy Schubertin the keys directory. 9132b15cb3dSCy Schubert<br><dt><code>leap</code> <kbd>file</kbd><dd>Specifies the location of the optional leapsecond file. 9142b15cb3dSCy SchubertThis overrides the link 9152b15cb3dSCy Schubert<span class="file">ntpkey_leap</span> 9162b15cb3dSCy Schubertin the keys directory. 9172b15cb3dSCy Schubert<br><dt><code>mvpar</code> <kbd>file</kbd><dd>Specifies the location of the optional MV parameters file. 918e27abb66SXin LIThis overrides the link 9192b15cb3dSCy Schubert<span class="file">ntpkey_mv_</span><kbd>hostname</kbd> 9202b15cb3dSCy Schubertin the keys directory. 9212b15cb3dSCy Schubert<br><dt><code>pw</code> <kbd>password</kbd><dd>Specifies the password to decrypt files containing private keys and 9222b15cb3dSCy Schubertidentity parameters. 9232b15cb3dSCy SchubertThis is required only if these files have been 9242b15cb3dSCy Schubertencrypted. 9252b15cb3dSCy Schubert<br><dt><code>randfile</code> <kbd>file</kbd><dd>Specifies the location of the random seed file used by the OpenSSL 9262b15cb3dSCy Schubertlibrary. 9272b15cb3dSCy SchubertThe defaults are described in the main text above. 9282b15cb3dSCy Schubert<br><dt><code>sign</code> <kbd>file</kbd><dd>Specifies the location of the optional sign key file. 9292b15cb3dSCy SchubertThis overrides 9302b15cb3dSCy Schubertthe link 9312b15cb3dSCy Schubert<span class="file">ntpkey_sign_</span><kbd>hostname</kbd> 9322b15cb3dSCy Schubertin the keys directory. 9332b15cb3dSCy SchubertIf this file is 9342b15cb3dSCy Schubertnot found, the host key is also the sign key. 9352b15cb3dSCy Schubert</dl> 9362b15cb3dSCy Schubert <br><dt><code>keys</code> <kbd>keyfile</kbd><dd>Specifies the complete path and location of the MD5 key file 9372b15cb3dSCy Schubertcontaining the keys and key identifiers used by 9382b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code>, 9392b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 9402b15cb3dSCy Schubertand 9412b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 9422b15cb3dSCy Schubertwhen operating with symmetric key cryptography. 9432b15cb3dSCy SchubertThis is the same operation as the 9442b15cb3dSCy Schubert<code>-k</code> 9452b15cb3dSCy Schubertcommand line option. 9462b15cb3dSCy Schubert<br><dt><code>keysdir</code> <kbd>path</kbd><dd>This command specifies the default directory path for 9472b15cb3dSCy Schubertcryptographic keys, parameters and certificates. 9482b15cb3dSCy SchubertThe default is 9492b15cb3dSCy Schubert<span class="file">/usr/local/etc/</span>. 9502b15cb3dSCy Schubert<br><dt><code>requestkey</code> <kbd>key</kbd><dd>Specifies the key identifier to use with the 9512b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 9522b15cb3dSCy Schubertutility program, which uses a 9532b15cb3dSCy Schubertproprietary protocol specific to this implementation of 9542b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code>. 9552b15cb3dSCy SchubertThe 9562b15cb3dSCy Schubert<kbd>key</kbd> 9572b15cb3dSCy Schubertargument is a key identifier 9582b15cb3dSCy Schubertfor the trusted key, where the value can be in the range 1 to 959*4e1ef62aSXin LI65,535, inclusive. 9602b15cb3dSCy Schubert<br><dt><code>revoke</code> <kbd>logsec</kbd><dd>Specifies the interval between re-randomization of certain 9612b15cb3dSCy Schubertcryptographic values used by the Autokey scheme, as a power of 2 in 9622b15cb3dSCy Schubertseconds. 9632b15cb3dSCy SchubertThese values need to be updated frequently in order to 9642b15cb3dSCy Schubertdeflect brute-force attacks on the algorithms of the scheme; 9652b15cb3dSCy Schuberthowever, updating some values is a relatively expensive operation. 9662b15cb3dSCy SchubertThe default interval is 16 (65,536 s or about 18 hours). 9672b15cb3dSCy SchubertFor poll 9682b15cb3dSCy Schubertintervals above the specified interval, the values will be updated 9692b15cb3dSCy Schubertfor every message sent. 9702b15cb3dSCy Schubert<br><dt><code>trustedkey</code> <kbd>key</kbd> <kbd>...</kbd><dd>Specifies the key identifiers which are trusted for the 9712b15cb3dSCy Schubertpurposes of authenticating peers with symmetric key cryptography, 9722b15cb3dSCy Schubertas well as keys used by the 9732b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 9742b15cb3dSCy Schubertand 9752b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 9762b15cb3dSCy Schubertprograms. 9772b15cb3dSCy SchubertThe authentication procedures require that both the local 9782b15cb3dSCy Schubertand remote servers share the same key and key identifier for this 9792b15cb3dSCy Schubertpurpose, although different keys can be used with different 9802b15cb3dSCy Schubertservers. 9812b15cb3dSCy SchubertThe 9822b15cb3dSCy Schubert<kbd>key</kbd> 9832b15cb3dSCy Schubertarguments are 32-bit unsigned 984*4e1ef62aSXin LIintegers with values from 1 to 65,535. 9852b15cb3dSCy Schubert</dl> 9862b15cb3dSCy Schubert 9872b15cb3dSCy Schubert<h5 class="subsubsection">Error Codes</h5> 9882b15cb3dSCy Schubert 9892b15cb3dSCy Schubert<p>The following error codes are reported via the NTP control 9902b15cb3dSCy Schubertand monitoring protocol trap mechanism. 9912b15cb3dSCy Schubert <dl> 9922b15cb3dSCy Schubert<dt>101<dd>(bad field format or length) 9932b15cb3dSCy SchubertThe packet has invalid version, length or format. 9942b15cb3dSCy Schubert<br><dt>102<dd>(bad timestamp) 9952b15cb3dSCy SchubertThe packet timestamp is the same or older than the most recent received. 9962b15cb3dSCy SchubertThis could be due to a replay or a server clock time step. 9972b15cb3dSCy Schubert<br><dt>103<dd>(bad filestamp) 9982b15cb3dSCy SchubertThe packet filestamp is the same or older than the most recent received. 9992b15cb3dSCy SchubertThis could be due to a replay or a key file generation error. 10002b15cb3dSCy Schubert<br><dt>104<dd>(bad or missing public key) 10012b15cb3dSCy SchubertThe public key is missing, has incorrect format or is an unsupported type. 10022b15cb3dSCy Schubert<br><dt>105<dd>(unsupported digest type) 10032b15cb3dSCy SchubertThe server requires an unsupported digest/signature scheme. 10042b15cb3dSCy Schubert<br><dt>106<dd>(mismatched digest types) 10052b15cb3dSCy SchubertNot used. 10062b15cb3dSCy Schubert<br><dt>107<dd>(bad signature length) 10072b15cb3dSCy SchubertThe signature length does not match the current public key. 10082b15cb3dSCy Schubert<br><dt>108<dd>(signature not verified) 10092b15cb3dSCy SchubertThe message fails the signature check. 10102b15cb3dSCy SchubertIt could be bogus or signed by a 10112b15cb3dSCy Schubertdifferent private key. 10122b15cb3dSCy Schubert<br><dt>109<dd>(certificate not verified) 10132b15cb3dSCy SchubertThe certificate is invalid or signed with the wrong key. 10142b15cb3dSCy Schubert<br><dt>110<dd>(certificate not verified) 10152b15cb3dSCy SchubertThe certificate is not yet valid or has expired or the signature could not 10162b15cb3dSCy Schubertbe verified. 10172b15cb3dSCy Schubert<br><dt>111<dd>(bad or missing cookie) 10182b15cb3dSCy SchubertThe cookie is missing, corrupted or bogus. 10192b15cb3dSCy Schubert<br><dt>112<dd>(bad or missing leapseconds table) 10202b15cb3dSCy SchubertThe leapseconds table is missing, corrupted or bogus. 10212b15cb3dSCy Schubert<br><dt>113<dd>(bad or missing certificate) 10222b15cb3dSCy SchubertThe certificate is missing, corrupted or bogus. 10232b15cb3dSCy Schubert<br><dt>114<dd>(bad or missing identity) 10242b15cb3dSCy SchubertThe identity key is missing, corrupt or bogus. 10252b15cb3dSCy Schubert</dl> 10262b15cb3dSCy Schubert <div class="node"> 10272b15cb3dSCy Schubert<p><hr> 10282b15cb3dSCy Schubert<a name="Monitoring-Support"></a> 10292b15cb3dSCy Schubert<br> 10302b15cb3dSCy Schubert</div> 10312b15cb3dSCy Schubert 10322b15cb3dSCy Schubert<h4 class="subsection">Monitoring Support</h4> 10332b15cb3dSCy Schubert 10342b15cb3dSCy Schubert<p><code>ntpd(1ntpdmdoc)</code> 10352b15cb3dSCy Schubertincludes a comprehensive monitoring facility suitable 10362b15cb3dSCy Schubertfor continuous, long term recording of server and client 10372b15cb3dSCy Schuberttimekeeping performance. 10382b15cb3dSCy SchubertSee the 10392b15cb3dSCy Schubert<code>statistics</code> 10402b15cb3dSCy Schubertcommand below 10412b15cb3dSCy Schubertfor a listing and example of each type of statistics currently 10422b15cb3dSCy Schubertsupported. 10432b15cb3dSCy SchubertStatistic files are managed using file generation sets 10442b15cb3dSCy Schubertand scripts in the 10452b15cb3dSCy Schubert<span class="file">./scripts</span> 1046e27abb66SXin LIdirectory of the source code distribution. 10472b15cb3dSCy SchubertUsing 10482b15cb3dSCy Schubertthese facilities and 10492b15cb3dSCy Schubert<span class="sc">unix</span> 10502b15cb3dSCy Schubert<code>cron(8)</code> 10512b15cb3dSCy Schubertjobs, the data can be 10522b15cb3dSCy Schubertautomatically summarized and archived for retrospective analysis. 10532b15cb3dSCy Schubert 10542b15cb3dSCy Schubert<h5 class="subsubsection">Monitoring Commands</h5> 10552b15cb3dSCy Schubert 10562b15cb3dSCy Schubert <dl> 10572b15cb3dSCy Schubert<dt><code>statistics</code> <kbd>name</kbd> <kbd>...</kbd><dd>Enables writing of statistics records. 10582b15cb3dSCy SchubertCurrently, eight kinds of 10592b15cb3dSCy Schubert<kbd>name</kbd> 10602b15cb3dSCy Schubertstatistics are supported. 10612b15cb3dSCy Schubert <dl> 10622b15cb3dSCy Schubert<dt><code>clockstats</code><dd>Enables recording of clock driver statistics information. 10632b15cb3dSCy SchubertEach update 10642b15cb3dSCy Schubertreceived from a clock driver appends a line of the following form to 10652b15cb3dSCy Schubertthe file generation set named 10662b15cb3dSCy Schubert<code>clockstats</code>: 10672b15cb3dSCy Schubert<pre class="verbatim"> 10682b15cb3dSCy Schubert 49213 525.624 127.127.4.1 93 226 00:08:29.606 D 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 10742b15cb3dSCy Schubertclock address in dotted-quad notation. 10752b15cb3dSCy SchubertThe final field shows the last 10762b15cb3dSCy Schuberttimecode received from the clock in decoded ASCII format, where 10772b15cb3dSCy Schubertmeaningful. 10782b15cb3dSCy SchubertIn some clock drivers a good deal of additional information 10792b15cb3dSCy Schubertcan be gathered and displayed as well. 10802b15cb3dSCy SchubertSee information specific to each 10812b15cb3dSCy Schubertclock for further details. 10822b15cb3dSCy Schubert<br><dt><code>cryptostats</code><dd>This option requires the OpenSSL cryptographic software library. 10832b15cb3dSCy SchubertIt 10842b15cb3dSCy Schubertenables recording of cryptographic public key protocol information. 10852b15cb3dSCy SchubertEach message received by the protocol module appends a line of the 10862b15cb3dSCy Schubertfollowing form to the file generation set named 10872b15cb3dSCy Schubert<code>cryptostats</code>: 10882b15cb3dSCy Schubert<pre class="verbatim"> 10892b15cb3dSCy Schubert 49213 525.624 127.127.4.1 message 10902b15cb3dSCy Schubert </pre> 10912b15cb3dSCy Schubert 10922b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and time 10932b15cb3dSCy Schubert(seconds and fraction past UTC midnight). 10942b15cb3dSCy SchubertThe next field shows the peer 10952b15cb3dSCy Schubertaddress in dotted-quad notation, The final message field includes the 10962b15cb3dSCy Schubertmessage type and certain ancillary information. 10972b15cb3dSCy SchubertSee the 10982b15cb3dSCy Schubert<a href="#Authentication-Options">Authentication Options</a> 10992b15cb3dSCy Schubertsection for further information. 11002b15cb3dSCy Schubert<br><dt><code>loopstats</code><dd>Enables recording of loop filter statistics information. 11012b15cb3dSCy SchubertEach 11022b15cb3dSCy Schubertupdate of the local clock outputs a line of the following form to 11032b15cb3dSCy Schubertthe file generation set named 11042b15cb3dSCy Schubert<code>loopstats</code>: 11052b15cb3dSCy Schubert<pre class="verbatim"> 11062b15cb3dSCy Schubert 50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 11072b15cb3dSCy Schubert </pre> 11082b15cb3dSCy Schubert 11092b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and 11102b15cb3dSCy Schuberttime (seconds and fraction past UTC midnight). 11112b15cb3dSCy SchubertThe next five fields 11122b15cb3dSCy Schubertshow time offset (seconds), frequency offset (parts per million - 11132b15cb3dSCy SchubertPPM), RMS jitter (seconds), Allan deviation (PPM) and clock 11142b15cb3dSCy Schubertdiscipline time constant. 11152b15cb3dSCy Schubert<br><dt><code>peerstats</code><dd>Enables recording of peer statistics information. 11162b15cb3dSCy SchubertThis includes 11172b15cb3dSCy Schubertstatistics records of all peers of a NTP server and of special 11182b15cb3dSCy Schubertsignals, where present and configured. 11192b15cb3dSCy SchubertEach valid update appends a 11202b15cb3dSCy Schubertline of the following form to the current element of a file 11212b15cb3dSCy Schubertgeneration set named 11222b15cb3dSCy Schubert<code>peerstats</code>: 11232b15cb3dSCy Schubert<pre class="verbatim"> 11242b15cb3dSCy Schubert 48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674 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 peer address in dotted-quad notation and status, 11312b15cb3dSCy Schubertrespectively. 11322b15cb3dSCy SchubertThe status field is encoded in hex in the format 11332b15cb3dSCy Schubertdescribed in Appendix A of the NTP specification RFC 1305. 11342b15cb3dSCy SchubertThe final four fields show the offset, 11352b15cb3dSCy Schubertdelay, dispersion and RMS jitter, all in seconds. 11362b15cb3dSCy Schubert<br><dt><code>rawstats</code><dd>Enables recording of raw-timestamp statistics information. 11372b15cb3dSCy SchubertThis 11382b15cb3dSCy Schubertincludes statistics records of all peers of a NTP server and of 11392b15cb3dSCy Schubertspecial signals, where present and configured. 11402b15cb3dSCy SchubertEach NTP message 11412b15cb3dSCy Schubertreceived from a peer or clock driver appends a line of the 11422b15cb3dSCy Schubertfollowing form to the file generation set named 11432b15cb3dSCy Schubert<code>rawstats</code>: 11442b15cb3dSCy Schubert<pre class="verbatim"> 11452b15cb3dSCy Schubert 50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000 11462b15cb3dSCy Schubert </pre> 11472b15cb3dSCy Schubert 11482b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and 11492b15cb3dSCy Schuberttime (seconds and fraction past UTC midnight). 11502b15cb3dSCy SchubertThe next two fields 11512b15cb3dSCy Schubertshow the remote peer or clock address followed by the local address 11522b15cb3dSCy Schubertin dotted-quad notation. 11532b15cb3dSCy SchubertThe final four fields show the originate, 11542b15cb3dSCy Schubertreceive, transmit and final NTP timestamps in order. 11552b15cb3dSCy SchubertThe timestamp 11562b15cb3dSCy Schubertvalues are as received and before processing by the various data 11572b15cb3dSCy Schubertsmoothing and mitigation algorithms. 11582b15cb3dSCy Schubert<br><dt><code>sysstats</code><dd>Enables recording of ntpd statistics counters on a periodic basis. 11592b15cb3dSCy SchubertEach 11602b15cb3dSCy Schuberthour a line of the following form is appended to the file generation 11612b15cb3dSCy Schubertset named 11622b15cb3dSCy Schubert<code>sysstats</code>: 11632b15cb3dSCy Schubert<pre class="verbatim"> 11642b15cb3dSCy Schubert 50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147 11652b15cb3dSCy Schubert </pre> 11662b15cb3dSCy Schubert 11672b15cb3dSCy Schubert <p>The first two fields show the date (Modified Julian Day) and time 11682b15cb3dSCy Schubert(seconds and fraction past UTC midnight). 11692b15cb3dSCy SchubertThe remaining ten fields show 11702b15cb3dSCy Schubertthe statistics counter values accumulated since the last generated 11712b15cb3dSCy Schubertline. 11722b15cb3dSCy Schubert <dl> 11732b15cb3dSCy Schubert<dt>Time since restart <code>36000</code><dd>Time in hours since the system was last rebooted. 11742b15cb3dSCy Schubert<br><dt>Packets received <code>81965</code><dd>Total number of packets received. 11752b15cb3dSCy Schubert<br><dt>Packets processed <code>0</code><dd>Number of packets received in response to previous packets sent 11762b15cb3dSCy Schubert<br><dt>Current version <code>9546</code><dd>Number of packets matching the current NTP version. 11772b15cb3dSCy Schubert<br><dt>Previous version <code>56</code><dd>Number of packets matching the previous NTP version. 11782b15cb3dSCy Schubert<br><dt>Bad version <code>71793</code><dd>Number of packets matching neither NTP version. 11792b15cb3dSCy Schubert<br><dt>Access denied <code>512</code><dd>Number of packets denied access for any reason. 11802b15cb3dSCy Schubert<br><dt>Bad length or format <code>540</code><dd>Number of packets with invalid length, format or port number. 11812b15cb3dSCy Schubert<br><dt>Bad authentication <code>10</code><dd>Number of packets not verified as authentic. 11822b15cb3dSCy Schubert<br><dt>Rate exceeded <code>147</code><dd>Number of packets discarded due to rate limitation. 11832b15cb3dSCy Schubert</dl> 11842b15cb3dSCy Schubert <br><dt><code>statsdir</code> <kbd>directory_path</kbd><dd>Indicates the full path of a directory where statistics files 11852b15cb3dSCy Schubertshould be created (see below). 11862b15cb3dSCy SchubertThis keyword allows 11872b15cb3dSCy Schubertthe (otherwise constant) 11882b15cb3dSCy Schubert<code>filegen</code> 11892b15cb3dSCy Schubertfilename prefix to be modified for file generation sets, which 11902b15cb3dSCy Schubertis useful for handling statistics logs. 11912b15cb3dSCy 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. 11922b15cb3dSCy SchubertGeneration 11932b15cb3dSCy Schubertfile sets provide a means for handling files that are 11942b15cb3dSCy Schubertcontinuously growing during the lifetime of a server. 11952b15cb3dSCy SchubertServer statistics are a typical example for such files. 11962b15cb3dSCy SchubertGeneration file sets provide access to a set of files used 11972b15cb3dSCy Schubertto store the actual data. 11982b15cb3dSCy SchubertAt any time at most one element 11992b15cb3dSCy Schubertof the set is being written to. 12002b15cb3dSCy SchubertThe type given specifies 12012b15cb3dSCy Schubertwhen and how data will be directed to a new element of the set. 12022b15cb3dSCy SchubertThis way, information stored in elements of a file set 12032b15cb3dSCy Schubertthat are currently unused are available for administrational 12042b15cb3dSCy Schubertoperations without the risk of disturbing the operation of ntpd. 12052b15cb3dSCy Schubert(Most important: they can be removed to free space for new data 12062b15cb3dSCy Schubertproduced.) 12072b15cb3dSCy Schubert 12082b15cb3dSCy Schubert <p>Note that this command can be sent from the 12092b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 12102b15cb3dSCy Schubertprogram running at a remote location. 12112b15cb3dSCy Schubert <dl> 12122b15cb3dSCy Schubert<dt><code>name</code><dd>This is the type of the statistics records, as shown in the 12132b15cb3dSCy Schubert<code>statistics</code> 12142b15cb3dSCy Schubertcommand. 12152b15cb3dSCy Schubert<br><dt><code>file</code> <kbd>filename</kbd><dd>This is the file name for the statistics records. 12162b15cb3dSCy SchubertFilenames of set 12172b15cb3dSCy Schubertmembers are built from three concatenated elements 12182b15cb3dSCy Schubert<code>prefix</code>, 12192b15cb3dSCy Schubert<code>filename</code> 12202b15cb3dSCy Schubertand 12212b15cb3dSCy Schubert<code>suffix</code>: 12222b15cb3dSCy Schubert <dl> 12232b15cb3dSCy Schubert<dt><code>prefix</code><dd>This is a constant filename path. 12242b15cb3dSCy SchubertIt is not subject to 12252b15cb3dSCy Schubertmodifications via the 12262b15cb3dSCy Schubert<kbd>filegen</kbd> 12272b15cb3dSCy Schubertoption. 12282b15cb3dSCy SchubertIt is defined by the 12292b15cb3dSCy Schubertserver, usually specified as a compile-time constant. 12302b15cb3dSCy SchubertIt may, 12312b15cb3dSCy Schuberthowever, be configurable for individual file generation sets 12322b15cb3dSCy Schubertvia other commands. 12332b15cb3dSCy SchubertFor example, the prefix used with 12342b15cb3dSCy Schubert<kbd>loopstats</kbd> 12352b15cb3dSCy Schubertand 12362b15cb3dSCy Schubert<kbd>peerstats</kbd> 12372b15cb3dSCy Schubertgeneration can be configured using the 12382b15cb3dSCy Schubert<kbd>statsdir</kbd> 12392b15cb3dSCy Schubertoption explained above. 12402b15cb3dSCy Schubert<br><dt><code>filename</code><dd>This string is directly concatenated to the prefix mentioned 12412b15cb3dSCy Schubertabove (no intervening 12422b15cb3dSCy Schubert/). 12432b15cb3dSCy SchubertThis can be modified using 12442b15cb3dSCy Schubertthe file argument to the 12452b15cb3dSCy Schubert<kbd>filegen</kbd> 12462b15cb3dSCy Schubertstatement. 12472b15cb3dSCy SchubertNo 12482b15cb3dSCy Schubert<span class="file">..</span> 12492b15cb3dSCy Schubertelements are 12502b15cb3dSCy Schubertallowed in this component to prevent filenames referring to 12512b15cb3dSCy Schubertparts outside the filesystem hierarchy denoted by 12522b15cb3dSCy Schubert<kbd>prefix</kbd>. 12532b15cb3dSCy Schubert<br><dt><code>suffix</code><dd>This part is reflects individual elements of a file set. 12542b15cb3dSCy SchubertIt is 12552b15cb3dSCy Schubertgenerated according to the type of a file set. 12562b15cb3dSCy Schubert</dl> 12572b15cb3dSCy Schubert <br><dt><code>type</code> <kbd>typename</kbd><dd>A file generation set is characterized by its type. 12582b15cb3dSCy SchubertThe following 12592b15cb3dSCy Schuberttypes are supported: 12602b15cb3dSCy Schubert <dl> 12612b15cb3dSCy Schubert<dt><code>none</code><dd>The file set is actually a single plain file. 12622b15cb3dSCy Schubert<br><dt><code>pid</code><dd>One element of file set is used per incarnation of a ntpd 12632b15cb3dSCy Schubertserver. 12642b15cb3dSCy SchubertThis type does not perform any changes to file set 12652b15cb3dSCy Schubertmembers during runtime, however it provides an easy way of 12662b15cb3dSCy Schubertseparating files belonging to different 12672b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 12682b15cb3dSCy Schubertserver incarnations. 12692b15cb3dSCy SchubertThe set member filename is built by appending a 12702b15cb3dSCy Schubert. 12712b15cb3dSCy Schubertto concatenated 12722b15cb3dSCy Schubert<kbd>prefix</kbd> 12732b15cb3dSCy Schubertand 12742b15cb3dSCy Schubert<kbd>filename</kbd> 12752b15cb3dSCy Schubertstrings, and 12762b15cb3dSCy Schubertappending the decimal representation of the process ID of the 12772b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 12782b15cb3dSCy Schubertserver process. 12792b15cb3dSCy Schubert<br><dt><code>day</code><dd>One file generation set element is created per day. 12802b15cb3dSCy SchubertA day is 12812b15cb3dSCy Schubertdefined as the period between 00:00 and 24:00 UTC. 12822b15cb3dSCy SchubertThe file set 12832b15cb3dSCy Schubertmember suffix consists of a 12842b15cb3dSCy Schubert. 12852b15cb3dSCy Schubertand a day specification in 12862b15cb3dSCy Schubertthe form 12872b15cb3dSCy Schubert<code>YYYYMMdd</code>. 12882b15cb3dSCy Schubert<code>YYYY</code> 12892b15cb3dSCy Schubertis a 4-digit year number (e.g., 1992). 12902b15cb3dSCy Schubert<code>MM</code> 12912b15cb3dSCy Schubertis a two digit month number. 12922b15cb3dSCy Schubert<code>dd</code> 12932b15cb3dSCy Schubertis a two digit day number. 12942b15cb3dSCy SchubertThus, all information written at 10 December 1992 would end up 12952b15cb3dSCy Schubertin a file named 12962b15cb3dSCy Schubert<kbd>prefix</kbd> 12972b15cb3dSCy Schubert<kbd>filename</kbd>.19921210. 12982b15cb3dSCy Schubert<br><dt><code>week</code><dd>Any file set member contains data related to a certain week of 12992b15cb3dSCy Schuberta year. 13002b15cb3dSCy SchubertThe term week is defined by computing day-of-year 13012b15cb3dSCy Schubertmodulo 7. 13022b15cb3dSCy SchubertElements of such a file generation set are 13032b15cb3dSCy Schubertdistinguished by appending the following suffix to the file set 13042b15cb3dSCy Schubertfilename base: A dot, a 4-digit year number, the letter 13052b15cb3dSCy Schubert<code>W</code>, 13062b15cb3dSCy Schubertand a 2-digit week number. 13072b15cb3dSCy SchubertFor example, information from January, 13082b15cb3dSCy Schubert10th 1992 would end up in a file with suffix 13092b15cb3dSCy Schubert.No . Ns Ar 1992W1 . 13102b15cb3dSCy Schubert<br><dt><code>month</code><dd>One generation file set element is generated per month. 13112b15cb3dSCy SchubertThe 13122b15cb3dSCy Schubertfile name suffix consists of a dot, a 4-digit year number, and 13132b15cb3dSCy Schuberta 2-digit month. 13142b15cb3dSCy Schubert<br><dt><code>year</code><dd>One generation file element is generated per year. 13152b15cb3dSCy SchubertThe filename 13162b15cb3dSCy Schubertsuffix consists of a dot and a 4 digit year number. 13172b15cb3dSCy Schubert<br><dt><code>age</code><dd>This type of file generation sets changes to a new element of 13182b15cb3dSCy Schubertthe file set every 24 hours of server operation. 13192b15cb3dSCy SchubertThe filename 13202b15cb3dSCy Schubertsuffix consists of a dot, the letter 13212b15cb3dSCy Schubert<code>a</code>, 13222b15cb3dSCy Schubertand an 8-digit number. 13232b15cb3dSCy SchubertThis number is taken to be the number of seconds the server is 13242b15cb3dSCy Schubertrunning at the start of the corresponding 24-hour period. 13252b15cb3dSCy SchubertInformation is only written to a file generation by specifying 13262b15cb3dSCy Schubert<code>enable</code>; 13272b15cb3dSCy Schubertoutput is prevented by specifying 13282b15cb3dSCy Schubert<code>disable</code>. 13292b15cb3dSCy Schubert</dl> 13302b15cb3dSCy Schubert <br><dt><code>link</code> | <code>nolink</code><dd>It is convenient to be able to access the current element of a file 13312b15cb3dSCy Schubertgeneration set by a fixed name. 13322b15cb3dSCy SchubertThis feature is enabled by 13332b15cb3dSCy Schubertspecifying 13342b15cb3dSCy Schubert<code>link</code> 13352b15cb3dSCy Schubertand disabled using 13362b15cb3dSCy Schubert<code>nolink</code>. 13372b15cb3dSCy SchubertIf link is specified, a 13382b15cb3dSCy Schuberthard link from the current file set element to a file without 13392b15cb3dSCy Schubertsuffix is created. 13402b15cb3dSCy SchubertWhen there is already a file with this name and 13412b15cb3dSCy Schubertthe number of links of this file is one, it is renamed appending a 13422b15cb3dSCy Schubertdot, the letter 13432b15cb3dSCy Schubert<code>C</code>, 1344e27abb66SXin LIand the pid of the 1345e27abb66SXin LI<code>ntpd(1ntpdmdoc)</code> 1346e27abb66SXin LIserver process. 13472b15cb3dSCy SchubertWhen the 13482b15cb3dSCy Schubertnumber of links is greater than one, the file is unlinked. 13492b15cb3dSCy SchubertThis 13502b15cb3dSCy Schubertallows the current file to be accessed by a constant name. 13512b15cb3dSCy Schubert<br><dt><code>enable</code> <code>|</code> <code>disable</code><dd>Enables or disables the recording function. 13522b15cb3dSCy Schubert</dl> 13532b15cb3dSCy Schubert </dl> 13542b15cb3dSCy Schubert </dl> 13552b15cb3dSCy Schubert<div class="node"> 13562b15cb3dSCy Schubert<p><hr> 13572b15cb3dSCy Schubert<a name="Access-Control-Support"></a> 13582b15cb3dSCy Schubert<br> 13592b15cb3dSCy Schubert</div> 13602b15cb3dSCy Schubert 13612b15cb3dSCy Schubert<h4 class="subsection">Access Control Support</h4> 13622b15cb3dSCy Schubert 13632b15cb3dSCy Schubert<p>The 13642b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 13652b15cb3dSCy Schubertdaemon implements a general purpose address/mask based restriction 13662b15cb3dSCy Schubertlist. 13672b15cb3dSCy SchubertThe list contains address/match entries sorted first 13682b15cb3dSCy Schubertby increasing address values and and then by increasing mask values. 13692b15cb3dSCy SchubertA match occurs when the bitwise AND of the mask and the packet 13702b15cb3dSCy Schubertsource address is equal to the bitwise AND of the mask and 13712b15cb3dSCy Schubertaddress in the list. 13722b15cb3dSCy SchubertThe list is searched in order with the 13732b15cb3dSCy Schubertlast match found defining the restriction flags associated 13742b15cb3dSCy Schubertwith the entry. 13752b15cb3dSCy SchubertAdditional information and examples can be found in the 13762b15cb3dSCy Schubert"Notes on Configuring NTP and Setting up a NTP Subnet" 13772b15cb3dSCy Schubertpage 13782b15cb3dSCy Schubert(available as part of the HTML documentation 13792b15cb3dSCy Schubertprovided in 13802b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 13812b15cb3dSCy Schubert 13822b15cb3dSCy Schubert <p>The restriction facility was implemented in conformance 13832b15cb3dSCy Schubertwith the access policies for the original NSFnet backbone 13842b15cb3dSCy Schuberttime servers. 13852b15cb3dSCy SchubertLater the facility was expanded to deflect 13862b15cb3dSCy Schubertcryptographic and clogging attacks. 13872b15cb3dSCy SchubertWhile this facility may 13882b15cb3dSCy Schubertbe useful for keeping unwanted or broken or malicious clients 13892b15cb3dSCy Schubertfrom congesting innocent servers, it should not be considered 13902b15cb3dSCy Schubertan alternative to the NTP authentication facilities. 13912b15cb3dSCy SchubertSource address based restrictions are easily circumvented 13922b15cb3dSCy Schubertby a determined cracker. 13932b15cb3dSCy Schubert 13942b15cb3dSCy Schubert <p>Clients can be denied service because they are explicitly 13954990d495SXin LIincluded in the restrict list created by the 13964990d495SXin LI<code>restrict</code> 13974990d495SXin LIcommand 13982b15cb3dSCy Schubertor implicitly as the result of cryptographic or rate limit 13992b15cb3dSCy Schubertviolations. 14002b15cb3dSCy SchubertCryptographic violations include certificate 14012b15cb3dSCy Schubertor identity verification failure; rate limit violations generally 14022b15cb3dSCy Schubertresult from defective NTP implementations that send packets 14032b15cb3dSCy Schubertat abusive rates. 14042b15cb3dSCy SchubertSome violations cause denied service 14052b15cb3dSCy Schubertonly for the offending packet, others cause denied service 14062b15cb3dSCy Schubertfor a timed period and others cause the denied service for 1407e27abb66SXin LIan indefinite period. 14082b15cb3dSCy SchubertWhen a client or network is denied access 1409e27abb66SXin LIfor an indefinite period, the only way at present to remove 14102b15cb3dSCy Schubertthe restrictions is by restarting the server. 14112b15cb3dSCy Schubert 14122b15cb3dSCy Schubert<h5 class="subsubsection">The Kiss-of-Death Packet</h5> 14132b15cb3dSCy Schubert 14142b15cb3dSCy Schubert<p>Ordinarily, packets denied service are simply dropped with no 14152b15cb3dSCy Schubertfurther action except incrementing statistics counters. 14162b15cb3dSCy SchubertSometimes a 14172b15cb3dSCy Schubertmore proactive response is needed, such as a server message that 14182b15cb3dSCy Schubertexplicitly requests the client to stop sending and leave a message 14192b15cb3dSCy Schubertfor the system operator. 14202b15cb3dSCy SchubertA special packet format has been created 14212b15cb3dSCy Schubertfor this purpose called the "kiss-of-death" (KoD) packet. 14222b15cb3dSCy SchubertKoD packets have the leap bits set unsynchronized and stratum set 14232b15cb3dSCy Schubertto zero and the reference identifier field set to a four-byte 14242b15cb3dSCy SchubertASCII code. 14252b15cb3dSCy SchubertIf the 14262b15cb3dSCy Schubert<code>noserve</code> 14272b15cb3dSCy Schubertor 14282b15cb3dSCy Schubert<code>notrust</code> 14292b15cb3dSCy Schubertflag of the matching restrict list entry is set, 14302b15cb3dSCy Schubertthe code is "DENY"; if the 14312b15cb3dSCy Schubert<code>limited</code> 14322b15cb3dSCy Schubertflag is set and the rate limit 14332b15cb3dSCy Schubertis exceeded, the code is "RATE". 14342b15cb3dSCy SchubertFinally, if a cryptographic violation occurs, the code is "CRYP". 14352b15cb3dSCy Schubert 14362b15cb3dSCy Schubert <p>A client receiving a KoD performs a set of sanity checks to 14372b15cb3dSCy Schubertminimize security exposure, then updates the stratum and 14382b15cb3dSCy Schubertreference identifier peer variables, sets the access 14392b15cb3dSCy Schubertdenied (TEST4) bit in the peer flash variable and sends 14402b15cb3dSCy Schuberta message to the log. 14412b15cb3dSCy SchubertAs long as the TEST4 bit is set, 14422b15cb3dSCy Schubertthe client will send no further packets to the server. 14432b15cb3dSCy SchubertThe only way at present to recover from this condition is 14442b15cb3dSCy Schubertto restart the protocol at both the client and server. 14452b15cb3dSCy SchubertThis 14462b15cb3dSCy Schuberthappens automatically at the client when the association times out. 14472b15cb3dSCy SchubertIt will happen at the server only if the server operator cooperates. 14482b15cb3dSCy Schubert 14492b15cb3dSCy Schubert<h5 class="subsubsection">Access Control Commands</h5> 14502b15cb3dSCy Schubert 14512b15cb3dSCy Schubert <dl> 14522b15cb3dSCy 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 14532b15cb3dSCy Schubert<code>limited</code> 14542b15cb3dSCy Schubertfacility which protects the server from 14552b15cb3dSCy Schubertclient abuse. 14562b15cb3dSCy SchubertThe 14572b15cb3dSCy Schubert<code>average</code> 14582b15cb3dSCy Schubertsubcommand specifies the minimum average packet 14592b15cb3dSCy Schubertspacing, while the 14602b15cb3dSCy Schubert<code>minimum</code> 14612b15cb3dSCy Schubertsubcommand specifies the minimum packet spacing. 14622b15cb3dSCy SchubertPackets that violate these minima are discarded 14632b15cb3dSCy Schubertand a kiss-o'-death packet returned if enabled. 14642b15cb3dSCy SchubertThe default 14652b15cb3dSCy Schubertminimum average and minimum are 5 and 2, respectively. 14664990d495SXin LIThe 14674990d495SXin LI<code>monitor</code> 14684990d495SXin LIsubcommand specifies the probability of discard 14692b15cb3dSCy Schubertfor packets that overflow the rate-control window. 147009100258SXin LI<br><dt><code>restrict</code> <code>address</code> <code>[mask </code><kbd>mask</kbd><code>]</code> <code>[ippeerlimit </code><kbd>int</kbd><code>]</code> <code>[</code><kbd>flag</kbd> <kbd>...</kbd><code>]</code><dd>The 14712b15cb3dSCy Schubert<kbd>address</kbd> 14722b15cb3dSCy Schubertargument expressed in 14732b15cb3dSCy Schubertdotted-quad form is the address of a host or network. 14742b15cb3dSCy SchubertAlternatively, the 14752b15cb3dSCy Schubert<kbd>address</kbd> 14762b15cb3dSCy Schubertargument can be a valid host DNS name. 14772b15cb3dSCy SchubertThe 14782b15cb3dSCy Schubert<kbd>mask</kbd> 14792b15cb3dSCy Schubertargument expressed in dotted-quad form defaults to 14802b15cb3dSCy Schubert<code>255.255.255.255</code>, 14812b15cb3dSCy Schubertmeaning that the 14822b15cb3dSCy Schubert<kbd>address</kbd> 14832b15cb3dSCy Schubertis treated as the address of an individual host. 14842b15cb3dSCy SchubertA default entry (address 14852b15cb3dSCy Schubert<code>0.0.0.0</code>, 14862b15cb3dSCy Schubertmask 14872b15cb3dSCy Schubert<code>0.0.0.0</code>) 14882b15cb3dSCy Schubertis always included and is always the first entry in the list. 14892b15cb3dSCy SchubertNote that text string 14902b15cb3dSCy Schubert<code>default</code>, 14912b15cb3dSCy Schubertwith no mask option, may 14922b15cb3dSCy Schubertbe used to indicate the default entry. 149309100258SXin LIThe 149409100258SXin LI<code>ippeerlimit</code> 149509100258SXin LIdirective limits the number of peer requests for each IP to 149609100258SXin LI<kbd>int</kbd>, 149709100258SXin LIwhere a value of -1 means "unlimited", the current default. 149809100258SXin LIA value of 0 means "none". 149909100258SXin LIThere would usually be at most 1 peering request per IP, 150009100258SXin LIbut if the remote peering requests are behind a proxy 150109100258SXin LIthere could well be more than 1 per IP. 15022b15cb3dSCy SchubertIn the current implementation, 15032b15cb3dSCy Schubert<code>flag</code> 15042b15cb3dSCy Schubertalways 15052b15cb3dSCy Schubertrestricts access, i.e., an entry with no flags indicates that free 15062b15cb3dSCy Schubertaccess to the server is to be given. 15072b15cb3dSCy SchubertThe flags are not orthogonal, 15082b15cb3dSCy Schubertin that more restrictive flags will often make less restrictive 15092b15cb3dSCy Schubertones redundant. 15102b15cb3dSCy SchubertThe flags can generally be classed into two 15112b15cb3dSCy Schubertcategories, those which restrict time service and those which 15122b15cb3dSCy Schubertrestrict informational queries and attempts to do run-time 15132b15cb3dSCy Schubertreconfiguration of the server. 15142b15cb3dSCy SchubertOne or more of the following flags 15152b15cb3dSCy Schubertmay be specified: 15162b15cb3dSCy Schubert <dl> 15172b15cb3dSCy Schubert<dt><code>ignore</code><dd>Deny packets of all kinds, including 15182b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15192b15cb3dSCy Schubertand 15202b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15212b15cb3dSCy Schubertqueries. 15222b15cb3dSCy Schubert<br><dt><code>kod</code><dd>If this flag is set when an access violation occurs, a kiss-o'-death 15232b15cb3dSCy Schubert(KoD) packet is sent. 15242b15cb3dSCy SchubertKoD packets are rate limited to no more than one 15252b15cb3dSCy Schubertper second. 15262b15cb3dSCy SchubertIf another KoD packet occurs within one second after the 15272b15cb3dSCy Schubertlast one, the packet is dropped. 15282b15cb3dSCy Schubert<br><dt><code>limited</code><dd>Deny service if the packet spacing violates the lower limits specified 15294990d495SXin LIin the 15304990d495SXin LI<code>discard</code> 15314990d495SXin LIcommand. 15322b15cb3dSCy SchubertA history of clients is kept using the 15332b15cb3dSCy Schubertmonitoring capability of 15342b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code>. 15352b15cb3dSCy SchubertThus, monitoring is always active as 15362b15cb3dSCy Schubertlong as there is a restriction entry with the 15372b15cb3dSCy Schubert<code>limited</code> 15382b15cb3dSCy Schubertflag. 15392b15cb3dSCy Schubert<br><dt><code>lowpriotrap</code><dd>Declare traps set by matching hosts to be low priority. 15402b15cb3dSCy SchubertThe 15412b15cb3dSCy Schubertnumber of traps a server can maintain is limited (the current limit 15422b15cb3dSCy Schubertis 3). 15432b15cb3dSCy SchubertTraps are usually assigned on a first come, first served 15442b15cb3dSCy Schubertbasis, with later trap requestors being denied service. 15452b15cb3dSCy SchubertThis flag 15462b15cb3dSCy Schubertmodifies the assignment algorithm by allowing low priority traps to 15472b15cb3dSCy Schubertbe overridden by later requests for normal priority traps. 154809100258SXin LI<br><dt><code>noepeer</code><dd>Deny ephemeral peer requests, 154909100258SXin LIeven if they come from an authenticated source. 155009100258SXin LINote that the ability to use a symmetric key for authentication may be restricted to 155109100258SXin LIone or more IPs or subnets via the third field of the 155209100258SXin LI<span class="file">ntp.keys</span> 155309100258SXin LIfile. 155409100258SXin LIThis restriction is not enabled by default, 155509100258SXin LIto maintain backward compatability. 155609100258SXin LIExpect 155709100258SXin LI<code>noepeer</code> 155809100258SXin LIto become the default in ntp-4.4. 15592b15cb3dSCy Schubert<br><dt><code>nomodify</code><dd>Deny 15602b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15612b15cb3dSCy Schubertand 15622b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15632b15cb3dSCy Schubertqueries which attempt to modify the state of the 15642b15cb3dSCy Schubertserver (i.e., run time reconfiguration). 15652b15cb3dSCy SchubertQueries which return 15662b15cb3dSCy Schubertinformation are permitted. 15672b15cb3dSCy Schubert<br><dt><code>noquery</code><dd>Deny 15682b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15692b15cb3dSCy Schubertand 15702b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15712b15cb3dSCy Schubertqueries. 15722b15cb3dSCy SchubertTime service is not affected. 157309100258SXin LI<br><dt><code>nopeer</code><dd>Deny unauthenticated packets which would result in mobilizing a new association. 157409100258SXin LIThis includes 157509100258SXin LIbroadcast and symmetric active packets 157609100258SXin LIwhen a configured association does not exist. 15772b15cb3dSCy SchubertIt also includes 15782b15cb3dSCy Schubert<code>pool</code> 15792b15cb3dSCy Schubertassociations, so if you want to use servers from a 15802b15cb3dSCy Schubert<code>pool</code> 15812b15cb3dSCy Schubertdirective and also want to use 15822b15cb3dSCy Schubert<code>nopeer</code> 15832b15cb3dSCy Schubertby default, you'll want a 158409100258SXin LI<code>restrict source ...</code> 158509100258SXin LIline as well that does 158609100258SXin LI<em>not</em> 158709100258SXin LIinclude the 15882b15cb3dSCy Schubert<code>nopeer</code> 15892b15cb3dSCy Schubertdirective. 15902b15cb3dSCy Schubert<br><dt><code>noserve</code><dd>Deny all packets except 15912b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 15922b15cb3dSCy Schubertand 15932b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 15942b15cb3dSCy Schubertqueries. 15952b15cb3dSCy Schubert<br><dt><code>notrap</code><dd>Decline to provide mode 6 control message trap service to matching 15962b15cb3dSCy Schuberthosts. 1597e27abb66SXin LIThe trap service is a subsystem of the 1598e27abb66SXin LI<code>ntpq(1ntpqmdoc)</code> 1599e27abb66SXin LIcontrol message 16002b15cb3dSCy Schubertprotocol which is intended for use by remote event logging programs. 16012b15cb3dSCy Schubert<br><dt><code>notrust</code><dd>Deny service unless the packet is cryptographically authenticated. 16022b15cb3dSCy Schubert<br><dt><code>ntpport</code><dd>This is actually a match algorithm modifier, rather than a 16032b15cb3dSCy Schubertrestriction flag. 16042b15cb3dSCy SchubertIts presence causes the restriction entry to be 16052b15cb3dSCy Schubertmatched only if the source port in the packet is the standard NTP 16062b15cb3dSCy SchubertUDP port (123). 16072b15cb3dSCy SchubertBoth 16082b15cb3dSCy Schubert<code>ntpport</code> 16092b15cb3dSCy Schubertand 16102b15cb3dSCy Schubert<code>non-ntpport</code> 16112b15cb3dSCy Schubertmay 16122b15cb3dSCy Schubertbe specified. 16132b15cb3dSCy SchubertThe 16142b15cb3dSCy Schubert<code>ntpport</code> 16152b15cb3dSCy Schubertis considered more specific and 16162b15cb3dSCy Schubertis sorted later in the list. 16172b15cb3dSCy Schubert<br><dt><code>version</code><dd>Deny packets that do not match the current NTP version. 16182b15cb3dSCy Schubert</dl> 16192b15cb3dSCy Schubert 16202b15cb3dSCy Schubert <p>Default restriction list entries with the flags ignore, interface, 16212b15cb3dSCy Schubertntpport, for each of the local host's interface addresses are 16222b15cb3dSCy Schubertinserted into the table at startup to prevent the server 16232b15cb3dSCy Schubertfrom attempting to synchronize to its own time. 16242b15cb3dSCy SchubertA default entry is also always present, though if it is 16252b15cb3dSCy Schubertotherwise unconfigured; no flags are associated 16262b15cb3dSCy Schubertwith the default entry (i.e., everything besides your own 16272b15cb3dSCy SchubertNTP server is unrestricted). 16282b15cb3dSCy Schubert</dl> 16292b15cb3dSCy Schubert<div class="node"> 16302b15cb3dSCy Schubert<p><hr> 16312b15cb3dSCy Schubert<a name="Automatic-NTP-Configuration-Options"></a> 16322b15cb3dSCy Schubert<br> 16332b15cb3dSCy Schubert</div> 16342b15cb3dSCy Schubert 16352b15cb3dSCy Schubert<h4 class="subsection">Automatic NTP Configuration Options</h4> 16362b15cb3dSCy Schubert 16372b15cb3dSCy Schubert<h5 class="subsubsection">Manycasting</h5> 16382b15cb3dSCy Schubert 16392b15cb3dSCy Schubert<p>Manycasting is a automatic discovery and configuration paradigm 16402b15cb3dSCy Schubertnew to NTPv4. 16412b15cb3dSCy SchubertIt is intended as a means for a multicast client 16422b15cb3dSCy Schubertto troll the nearby network neighborhood to find cooperating 16432b15cb3dSCy Schubertmanycast servers, validate them using cryptographic means 16442b15cb3dSCy Schubertand evaluate their time values with respect to other servers 16452b15cb3dSCy Schubertthat might be lurking in the vicinity. 16462b15cb3dSCy SchubertThe intended result is that each manycast client mobilizes 16472b15cb3dSCy Schubertclient associations with some number of the "best" 16482b15cb3dSCy Schubertof the nearby manycast servers, yet automatically reconfigures 16492b15cb3dSCy Schubertto sustain this number of servers should one or another fail. 16502b15cb3dSCy Schubert 16512b15cb3dSCy Schubert <p>Note that the manycasting paradigm does not coincide 16522b15cb3dSCy Schubertwith the anycast paradigm described in RFC-1546, 16532b15cb3dSCy Schubertwhich is designed to find a single server from a clique 16542b15cb3dSCy Schubertof servers providing the same service. 16552b15cb3dSCy SchubertThe manycast paradigm is designed to find a plurality 16562b15cb3dSCy Schubertof redundant servers satisfying defined optimality criteria. 16572b15cb3dSCy Schubert 16582b15cb3dSCy Schubert <p>Manycasting can be used with either symmetric key 16592b15cb3dSCy Schubertor public key cryptography. 16602b15cb3dSCy SchubertThe public key infrastructure (PKI) 16612b15cb3dSCy Schubertoffers the best protection against compromised keys 16622b15cb3dSCy Schubertand is generally considered stronger, at least with relatively 16632b15cb3dSCy Schubertlarge key sizes. 16642b15cb3dSCy SchubertIt is implemented using the Autokey protocol and 16652b15cb3dSCy Schubertthe OpenSSL cryptographic library available from 16662b15cb3dSCy Schubert<code>http://www.openssl.org/</code>. 16672b15cb3dSCy SchubertThe library can also be used with other NTPv4 modes 16682b15cb3dSCy Schubertas well and is highly recommended, especially for broadcast modes. 16692b15cb3dSCy Schubert 16702b15cb3dSCy Schubert <p>A persistent manycast client association is configured 16714990d495SXin LIusing the 16724990d495SXin LI<code>manycastclient</code> 16734990d495SXin LIcommand, which is similar to the 16744990d495SXin LI<code>server</code> 16754990d495SXin LIcommand but with a multicast (IPv4 class 16762b15cb3dSCy Schubert<code>D</code> 16772b15cb3dSCy Schubertor IPv6 prefix 16782b15cb3dSCy Schubert<code>FF</code>) 16792b15cb3dSCy Schubertgroup address. 16802b15cb3dSCy SchubertThe IANA has designated IPv4 address 224.1.1.1 16812b15cb3dSCy Schubertand IPv6 address FF05::101 (site local) for NTP. 16822b15cb3dSCy SchubertWhen more servers are needed, it broadcasts manycast 16832b15cb3dSCy Schubertclient messages to this address at the minimum feasible rate 16842b15cb3dSCy Schubertand minimum feasible time-to-live (TTL) hops, depending 16852b15cb3dSCy Schuberton how many servers have already been found. 16862b15cb3dSCy SchubertThere can be as many manycast client associations 16872b15cb3dSCy Schubertas different group address, each one serving as a template 16882b15cb3dSCy Schubertfor a future ephemeral unicast client/server association. 16892b15cb3dSCy Schubert 16902b15cb3dSCy Schubert <p>Manycast servers configured with the 16912b15cb3dSCy Schubert<code>manycastserver</code> 16922b15cb3dSCy Schubertcommand listen on the specified group address for manycast 16932b15cb3dSCy Schubertclient messages. 16942b15cb3dSCy SchubertNote the distinction between manycast client, 16952b15cb3dSCy Schubertwhich actively broadcasts messages, and manycast server, 16962b15cb3dSCy Schubertwhich passively responds to them. 16972b15cb3dSCy SchubertIf a manycast server is 16982b15cb3dSCy Schubertin scope of the current TTL and is itself synchronized 16992b15cb3dSCy Schubertto a valid source and operating at a stratum level equal 17002b15cb3dSCy Schubertto or lower than the manycast client, it replies to the 17012b15cb3dSCy Schubertmanycast client message with an ordinary unicast server message. 17022b15cb3dSCy Schubert 17032b15cb3dSCy Schubert <p>The manycast client receiving this message mobilizes 17042b15cb3dSCy Schubertan ephemeral client/server association according to the 17052b15cb3dSCy Schubertmatching manycast client template, but only if cryptographically 17062b15cb3dSCy Schubertauthenticated and the server stratum is less than or equal 17072b15cb3dSCy Schubertto the client stratum. 17082b15cb3dSCy SchubertAuthentication is explicitly required 17092b15cb3dSCy Schubertand either symmetric key or public key (Autokey) can be used. 17102b15cb3dSCy SchubertThen, the client polls the server at its unicast address 17112b15cb3dSCy Schubertin burst mode in order to reliably set the host clock 17122b15cb3dSCy Schubertand validate the source. 17132b15cb3dSCy SchubertThis normally results 17142b15cb3dSCy Schubertin a volley of eight client/server at 2-s intervals 17152b15cb3dSCy Schubertduring which both the synchronization and cryptographic 17162b15cb3dSCy Schubertprotocols run concurrently. 17172b15cb3dSCy SchubertFollowing the volley, 17182b15cb3dSCy Schubertthe client runs the NTP intersection and clustering 17192b15cb3dSCy Schubertalgorithms, which act to discard all but the "best" 17202b15cb3dSCy Schubertassociations according to stratum and synchronization 17212b15cb3dSCy Schubertdistance. 17222b15cb3dSCy SchubertThe surviving associations then continue 17232b15cb3dSCy Schubertin ordinary client/server mode. 17242b15cb3dSCy Schubert 17252b15cb3dSCy Schubert <p>The manycast client polling strategy is designed to reduce 17262b15cb3dSCy Schubertas much as possible the volume of manycast client messages 17272b15cb3dSCy Schubertand the effects of implosion due to near-simultaneous 17282b15cb3dSCy Schubertarrival of manycast server messages. 17292b15cb3dSCy SchubertThe strategy is determined by the 17302b15cb3dSCy Schubert<code>manycastclient</code>, 17312b15cb3dSCy Schubert<code>tos</code> 17322b15cb3dSCy Schubertand 17332b15cb3dSCy Schubert<code>ttl</code> 17342b15cb3dSCy Schubertconfiguration commands. 17352b15cb3dSCy SchubertThe manycast poll interval is 17362b15cb3dSCy Schubertnormally eight times the system poll interval, 17372b15cb3dSCy Schubertwhich starts out at the 17382b15cb3dSCy Schubert<code>minpoll</code> 17392b15cb3dSCy Schubertvalue specified in the 17402b15cb3dSCy Schubert<code>manycastclient</code>, 17412b15cb3dSCy Schubertcommand and, under normal circumstances, increments to the 17422b15cb3dSCy Schubert<code>maxpolll</code> 17432b15cb3dSCy Schubertvalue specified in this command. 17442b15cb3dSCy SchubertInitially, the TTL is 17454990d495SXin LIset at the minimum hops specified by the 17464990d495SXin LI<code>ttl</code> 17474990d495SXin LIcommand. 17482b15cb3dSCy SchubertAt each retransmission the TTL is increased until reaching 17492b15cb3dSCy Schubertthe maximum hops specified by this command or a sufficient 17502b15cb3dSCy Schubertnumber client associations have been found. 17512b15cb3dSCy SchubertFurther retransmissions use the same TTL. 17522b15cb3dSCy Schubert 17532b15cb3dSCy Schubert <p>The quality and reliability of the suite of associations 17542b15cb3dSCy Schubertdiscovered by the manycast client is determined by the NTP 17552b15cb3dSCy Schubertmitigation algorithms and the 17562b15cb3dSCy Schubert<code>minclock</code> 17572b15cb3dSCy Schubertand 17582b15cb3dSCy Schubert<code>minsane</code> 17592b15cb3dSCy Schubertvalues specified in the 17602b15cb3dSCy Schubert<code>tos</code> 17612b15cb3dSCy Schubertconfiguration command. 17622b15cb3dSCy SchubertAt least 17632b15cb3dSCy Schubert<code>minsane</code> 17642b15cb3dSCy Schubertcandidate servers must be available and the mitigation 17652b15cb3dSCy Schubertalgorithms produce at least 17662b15cb3dSCy Schubert<code>minclock</code> 17672b15cb3dSCy Schubertsurvivors in order to synchronize the clock. 17682b15cb3dSCy SchubertByzantine agreement principles require at least four 17692b15cb3dSCy Schubertcandidates in order to correctly discard a single falseticker. 17702b15cb3dSCy SchubertFor legacy purposes, 17712b15cb3dSCy Schubert<code>minsane</code> 17722b15cb3dSCy Schubertdefaults to 1 and 17732b15cb3dSCy Schubert<code>minclock</code> 17742b15cb3dSCy Schubertdefaults to 3. 17752b15cb3dSCy SchubertFor manycast service 17762b15cb3dSCy Schubert<code>minsane</code> 17772b15cb3dSCy Schubertshould be explicitly set to 4, assuming at least that 17782b15cb3dSCy Schubertnumber of servers are available. 17792b15cb3dSCy Schubert 17802b15cb3dSCy Schubert <p>If at least 17812b15cb3dSCy Schubert<code>minclock</code> 17822b15cb3dSCy Schubertservers are found, the manycast poll interval is immediately 17832b15cb3dSCy Schubertset to eight times 17842b15cb3dSCy Schubert<code>maxpoll</code>. 17852b15cb3dSCy SchubertIf less than 17862b15cb3dSCy Schubert<code>minclock</code> 17872b15cb3dSCy Schubertservers are found when the TTL has reached the maximum hops, 17882b15cb3dSCy Schubertthe manycast poll interval is doubled. 17892b15cb3dSCy SchubertFor each transmission 17902b15cb3dSCy Schubertafter that, the poll interval is doubled again until 17912b15cb3dSCy Schubertreaching the maximum of eight times 17922b15cb3dSCy Schubert<code>maxpoll</code>. 17932b15cb3dSCy SchubertFurther transmissions use the same poll interval and 17942b15cb3dSCy SchubertTTL values. 17952b15cb3dSCy SchubertNote that while all this is going on, 17962b15cb3dSCy Schuberteach client/server association found is operating normally 17972b15cb3dSCy Schubertit the system poll interval. 17982b15cb3dSCy Schubert 17992b15cb3dSCy Schubert <p>Administratively scoped multicast boundaries are normally 18002b15cb3dSCy Schubertspecified by the network router configuration and, 18012b15cb3dSCy Schubertin the case of IPv6, the link/site scope prefix. 18022b15cb3dSCy SchubertBy default, the increment for TTL hops is 32 starting 18032b15cb3dSCy Schubertfrom 31; however, the 18042b15cb3dSCy Schubert<code>ttl</code> 18052b15cb3dSCy Schubertconfiguration command can be 18062b15cb3dSCy Schubertused to modify the values to match the scope rules. 18072b15cb3dSCy Schubert 18082b15cb3dSCy Schubert <p>It is often useful to narrow the range of acceptable 18092b15cb3dSCy Schubertservers which can be found by manycast client associations. 18102b15cb3dSCy SchubertBecause manycast servers respond only when the client 18112b15cb3dSCy Schubertstratum is equal to or greater than the server stratum, 18122b15cb3dSCy Schubertprimary (stratum 1) servers fill find only primary servers 18132b15cb3dSCy Schubertin TTL range, which is probably the most common objective. 18142b15cb3dSCy SchubertHowever, unless configured otherwise, all manycast clients 18152b15cb3dSCy Schubertin TTL range will eventually find all primary servers 18162b15cb3dSCy Schubertin TTL range, which is probably not the most common 18172b15cb3dSCy Schubertobjective in large networks. 18182b15cb3dSCy SchubertThe 18192b15cb3dSCy Schubert<code>tos</code> 18202b15cb3dSCy Schubertcommand can be used to modify this behavior. 18212b15cb3dSCy SchubertServers with stratum below 18222b15cb3dSCy Schubert<code>floor</code> 18232b15cb3dSCy Schubertor above 18242b15cb3dSCy Schubert<code>ceiling</code> 18252b15cb3dSCy Schubertspecified in the 18262b15cb3dSCy Schubert<code>tos</code> 18272b15cb3dSCy Schubertcommand are strongly discouraged during the selection 18282b15cb3dSCy Schubertprocess; however, these servers may be temporally 18292b15cb3dSCy Schubertaccepted if the number of servers within TTL range is 18302b15cb3dSCy Schubertless than 18312b15cb3dSCy Schubert<code>minclock</code>. 18322b15cb3dSCy Schubert 18332b15cb3dSCy Schubert <p>The above actions occur for each manycast client message, 18342b15cb3dSCy Schubertwhich repeats at the designated poll interval. 18352b15cb3dSCy SchubertHowever, once the ephemeral client association is mobilized, 18362b15cb3dSCy Schubertsubsequent manycast server replies are discarded, 18372b15cb3dSCy Schubertsince that would result in a duplicate association. 18382b15cb3dSCy SchubertIf during a poll interval the number of client associations 18392b15cb3dSCy Schubertfalls below 18402b15cb3dSCy Schubert<code>minclock</code>, 18412b15cb3dSCy Schubertall manycast client prototype associations are reset 18422b15cb3dSCy Schubertto the initial poll interval and TTL hops and operation 18432b15cb3dSCy Schubertresumes from the beginning. 18442b15cb3dSCy SchubertIt is important to avoid 18452b15cb3dSCy Schubertfrequent manycast client messages, since each one requires 18462b15cb3dSCy Schubertall manycast servers in TTL range to respond. 18472b15cb3dSCy SchubertThe result could well be an implosion, either minor or major, 18482b15cb3dSCy Schubertdepending on the number of servers in range. 18492b15cb3dSCy SchubertThe recommended value for 18502b15cb3dSCy Schubert<code>maxpoll</code> 18512b15cb3dSCy Schubertis 12 (4,096 s). 18522b15cb3dSCy Schubert 18532b15cb3dSCy Schubert <p>It is possible and frequently useful to configure a host 18542b15cb3dSCy Schubertas both manycast client and manycast server. 18552b15cb3dSCy SchubertA number of hosts configured this way and sharing a common 18562b15cb3dSCy Schubertgroup address will automatically organize themselves 18572b15cb3dSCy Schubertin an optimum configuration based on stratum and 18582b15cb3dSCy Schubertsynchronization distance. 18592b15cb3dSCy SchubertFor example, consider an NTP 18602b15cb3dSCy Schubertsubnet of two primary servers and a hundred or more 18612b15cb3dSCy Schubertdependent clients. 18622b15cb3dSCy SchubertWith two exceptions, all servers 18632b15cb3dSCy Schubertand clients have identical configuration files including both 18642b15cb3dSCy Schubert<code>multicastclient</code> 18652b15cb3dSCy Schubertand 18662b15cb3dSCy Schubert<code>multicastserver</code> 18672b15cb3dSCy Schubertcommands using, for instance, multicast group address 18682b15cb3dSCy Schubert239.1.1.1. 18692b15cb3dSCy SchubertThe only exception is that each primary server 18702b15cb3dSCy Schubertconfiguration file must include commands for the primary 18712b15cb3dSCy Schubertreference source such as a GPS receiver. 18722b15cb3dSCy Schubert 18732b15cb3dSCy Schubert <p>The remaining configuration files for all secondary 18742b15cb3dSCy Schubertservers and clients have the same contents, except for the 18752b15cb3dSCy Schubert<code>tos</code> 18762b15cb3dSCy Schubertcommand, which is specific for each stratum level. 18772b15cb3dSCy SchubertFor stratum 1 and stratum 2 servers, that command is 18782b15cb3dSCy Schubertnot necessary. 18792b15cb3dSCy SchubertFor stratum 3 and above servers the 18802b15cb3dSCy Schubert<code>floor</code> 18812b15cb3dSCy Schubertvalue is set to the intended stratum number. 18822b15cb3dSCy SchubertThus, all stratum 3 configuration files are identical, 18832b15cb3dSCy Schubertall stratum 4 files are identical and so forth. 18842b15cb3dSCy Schubert 18852b15cb3dSCy Schubert <p>Once operations have stabilized in this scenario, 18862b15cb3dSCy Schubertthe primary servers will find the primary reference source 18872b15cb3dSCy Schubertand each other, since they both operate at the same 18882b15cb3dSCy Schubertstratum (1), but not with any secondary server or client, 18892b15cb3dSCy Schubertsince these operate at a higher stratum. 18902b15cb3dSCy SchubertThe secondary 18912b15cb3dSCy Schubertservers will find the servers at the same stratum level. 18922b15cb3dSCy SchubertIf one of the primary servers loses its GPS receiver, 18932b15cb3dSCy Schubertit will continue to operate as a client and other clients 18942b15cb3dSCy Schubertwill time out the corresponding association and 18952b15cb3dSCy Schubertre-associate accordingly. 18962b15cb3dSCy Schubert 18972b15cb3dSCy Schubert <p>Some administrators prefer to avoid running 18982b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 18992b15cb3dSCy Schubertcontinuously and run either 19009034852cSGleb Smirnoff<code>sntp(1sntpmdoc)</code> 19012b15cb3dSCy Schubertor 19022b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 19032b15cb3dSCy Schubert<code>-q</code> 19042b15cb3dSCy Schubertas a cron job. 19052b15cb3dSCy SchubertIn either case the servers must be 19062b15cb3dSCy Schubertconfigured in advance and the program fails if none are 19072b15cb3dSCy Schubertavailable when the cron job runs. 19082b15cb3dSCy SchubertA really slick 19092b15cb3dSCy Schubertapplication of manycast is with 19102b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 19112b15cb3dSCy Schubert<code>-q</code>. 19122b15cb3dSCy SchubertThe program wakes up, scans the local landscape looking 19132b15cb3dSCy Schubertfor the usual suspects, selects the best from among 19142b15cb3dSCy Schubertthe rascals, sets the clock and then departs. 19152b15cb3dSCy SchubertServers do not have to be configured in advance and 19162b15cb3dSCy Schubertall clients throughout the network can have the same 19172b15cb3dSCy Schubertconfiguration file. 19182b15cb3dSCy Schubert 19192b15cb3dSCy Schubert<h5 class="subsubsection">Manycast Interactions with Autokey</h5> 19202b15cb3dSCy Schubert 19212b15cb3dSCy Schubert<p>Each time a manycast client sends a client mode packet 19222b15cb3dSCy Schubertto a multicast group address, all manycast servers 19232b15cb3dSCy Schubertin scope generate a reply including the host name 19242b15cb3dSCy Schubertand status word. 19252b15cb3dSCy SchubertThe manycast clients then run 19262b15cb3dSCy Schubertthe Autokey protocol, which collects and verifies 19272b15cb3dSCy Schubertall certificates involved. 19282b15cb3dSCy SchubertFollowing the burst interval 19292b15cb3dSCy Schubertall but three survivors are cast off, 19302b15cb3dSCy Schubertbut the certificates remain in the local cache. 19312b15cb3dSCy SchubertIt often happens that several complete signing trails 19322b15cb3dSCy Schubertfrom the client to the primary servers are collected in this way. 19332b15cb3dSCy Schubert 19342b15cb3dSCy Schubert <p>About once an hour or less often if the poll interval 19352b15cb3dSCy Schubertexceeds this, the client regenerates the Autokey key list. 19362b15cb3dSCy SchubertThis is in general transparent in client/server mode. 19372b15cb3dSCy SchubertHowever, about once per day the server private value 19382b15cb3dSCy Schubertused to generate cookies is refreshed along with all 19392b15cb3dSCy Schubertmanycast client associations. 19402b15cb3dSCy SchubertIn this case all 19412b15cb3dSCy Schubertcryptographic values including certificates is refreshed. 19422b15cb3dSCy SchubertIf a new certificate has been generated since 19432b15cb3dSCy Schubertthe last refresh epoch, it will automatically revoke 19442b15cb3dSCy Schubertall prior certificates that happen to be in the 19452b15cb3dSCy Schubertcertificate cache. 19462b15cb3dSCy SchubertAt the same time, the manycast 19472b15cb3dSCy Schubertscheme starts all over from the beginning and 19482b15cb3dSCy Schubertthe expanding ring shrinks to the minimum and increments 19492b15cb3dSCy Schubertfrom there while collecting all servers in scope. 19502b15cb3dSCy Schubert 1951f391d6bcSXin LI<h5 class="subsubsection">Broadcast Options</h5> 1952f391d6bcSXin LI 1953f391d6bcSXin LI <dl> 1954f391d6bcSXin LI<dt><code>tos</code> <code>[bcpollbstep </code><kbd>gate</kbd><code>]</code><dd>This command provides a way to delay, 1955f391d6bcSXin LIby the specified number of broadcast poll intervals, 1956f391d6bcSXin LIbelieving backward time steps from a broadcast server. 1957f391d6bcSXin LIBroadcast time networks are expected to be trusted. 1958f391d6bcSXin LIIn the event a broadcast server's time is stepped backwards, 1959f391d6bcSXin LIthere is clear benefit to having the clients notice this change 1960f391d6bcSXin LIas soon as possible. 1961f391d6bcSXin LIAttacks such as replay attacks can happen, however, 1962f391d6bcSXin LIand even though there are a number of protections built in to 1963f391d6bcSXin LIbroadcast mode, attempts to perform a replay attack are possible. 1964f391d6bcSXin LIThis value defaults to 0, but can be changed 1965f391d6bcSXin LIto any number of poll intervals between 0 and 4. 196609100258SXin LI</dl> 1967f391d6bcSXin LI 19682b15cb3dSCy Schubert<h5 class="subsubsection">Manycast Options</h5> 19692b15cb3dSCy Schubert 19702b15cb3dSCy Schubert <dl> 19712b15cb3dSCy 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 19722b15cb3dSCy Schubertalgorithms. 19732b15cb3dSCy SchubertIt can be used to select the quality and 19742b15cb3dSCy Schubertquantity of peers used to synchronize the system clock 19752b15cb3dSCy Schubertand is most useful in manycast mode. 19762b15cb3dSCy SchubertThe variables operate 19772b15cb3dSCy Schubertas follows: 19782b15cb3dSCy Schubert <dl> 19792b15cb3dSCy Schubert<dt><code>ceiling</code> <kbd>ceiling</kbd><dd>Peers with strata above 19802b15cb3dSCy Schubert<code>ceiling</code> 19812b15cb3dSCy Schubertwill be discarded if there are at least 19822b15cb3dSCy Schubert<code>minclock</code> 19832b15cb3dSCy Schubertpeers remaining. 19842b15cb3dSCy SchubertThis value defaults to 15, but can be changed 19852b15cb3dSCy Schubertto any number from 1 to 15. 19862b15cb3dSCy Schubert<br><dt><code>cohort</code> <code>{0 | 1}</code><dd>This is a binary flag which enables (0) or disables (1) 19872b15cb3dSCy Schubertmanycast server replies to manycast clients with the same 19882b15cb3dSCy Schubertstratum level. 19892b15cb3dSCy SchubertThis is useful to reduce implosions where 19902b15cb3dSCy Schubertlarge numbers of clients with the same stratum level 19912b15cb3dSCy Schubertare present. 19922b15cb3dSCy SchubertThe default is to enable these replies. 19932b15cb3dSCy Schubert<br><dt><code>floor</code> <kbd>floor</kbd><dd>Peers with strata below 19942b15cb3dSCy Schubert<code>floor</code> 19952b15cb3dSCy Schubertwill be discarded if there are at least 19962b15cb3dSCy Schubert<code>minclock</code> 19972b15cb3dSCy Schubertpeers remaining. 19982b15cb3dSCy SchubertThis value defaults to 1, but can be changed 19992b15cb3dSCy Schubertto any number from 1 to 15. 20009034852cSGleb Smirnoff<br><dt><code>minclock</code> <kbd>minclock</kbd><dd>The clustering algorithm repeatedly casts out outlier 20012b15cb3dSCy Schubertassociations until no more than 20022b15cb3dSCy Schubert<code>minclock</code> 20032b15cb3dSCy Schubertassociations remain. 20042b15cb3dSCy SchubertThis value defaults to 3, 20052b15cb3dSCy Schubertbut can be changed to any number from 1 to the number of 20062b15cb3dSCy Schubertconfigured sources. 20072b15cb3dSCy Schubert<br><dt><code>minsane</code> <kbd>minsane</kbd><dd>This is the minimum number of candidates available 20082b15cb3dSCy Schubertto the clock selection algorithm in order to produce 20092b15cb3dSCy Schubertone or more truechimers for the clustering algorithm. 20102b15cb3dSCy SchubertIf fewer than this number are available, the clock is 20112b15cb3dSCy Schubertundisciplined and allowed to run free. 20122b15cb3dSCy SchubertThe default is 1 20132b15cb3dSCy Schubertfor legacy purposes. 20142b15cb3dSCy SchubertHowever, according to principles of 20152b15cb3dSCy SchubertByzantine agreement, 20162b15cb3dSCy Schubert<code>minsane</code> 20172b15cb3dSCy Schubertshould be at least 4 in order to detect and discard 20182b15cb3dSCy Schuberta single falseticker. 20192b15cb3dSCy Schubert</dl> 20202b15cb3dSCy Schubert <br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing 20212b15cb3dSCy Schubertorder, up to 8 values can be specified. 20222b15cb3dSCy SchubertIn manycast mode these values are used in turn 20232b15cb3dSCy Schubertin an expanding-ring search. 20242b15cb3dSCy SchubertThe default is eight 20252b15cb3dSCy Schubertmultiples of 32 starting at 31. 20262b15cb3dSCy Schubert</dl> 20272b15cb3dSCy Schubert<div class="node"> 20282b15cb3dSCy Schubert<p><hr> 20292b15cb3dSCy Schubert<a name="Reference-Clock-Support"></a> 20302b15cb3dSCy Schubert<br> 20312b15cb3dSCy Schubert</div> 20322b15cb3dSCy Schubert 20332b15cb3dSCy Schubert<h4 class="subsection">Reference Clock Support</h4> 20342b15cb3dSCy Schubert 20352b15cb3dSCy Schubert<p>The NTP Version 4 daemon supports some three dozen different radio, 20362b15cb3dSCy Schubertsatellite and modem reference clocks plus a special pseudo-clock 20372b15cb3dSCy Schubertused for backup or when no other clock source is available. 20382b15cb3dSCy SchubertDetailed descriptions of individual device drivers and options can 20392b15cb3dSCy Schubertbe found in the 20402b15cb3dSCy Schubert"Reference Clock Drivers" 20412b15cb3dSCy Schubertpage 20422b15cb3dSCy Schubert(available as part of the HTML documentation 20432b15cb3dSCy Schubertprovided in 20442b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 20452b15cb3dSCy SchubertAdditional information can be found in the pages linked 20462b15cb3dSCy Schubertthere, including the 20472b15cb3dSCy Schubert"Debugging Hints for Reference Clock Drivers" 20482b15cb3dSCy Schubertand 20492b15cb3dSCy Schubert"How To Write a Reference Clock Driver" 20502b15cb3dSCy Schubertpages 20512b15cb3dSCy Schubert(available as part of the HTML documentation 20522b15cb3dSCy Schubertprovided in 20532b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 20542b15cb3dSCy SchubertIn addition, support for a PPS 20552b15cb3dSCy Schubertsignal is available as described in the 20562b15cb3dSCy Schubert"Pulse-per-second (PPS) Signal Interfacing" 20572b15cb3dSCy Schubertpage 20582b15cb3dSCy Schubert(available as part of the HTML documentation 20592b15cb3dSCy Schubertprovided in 20602b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 20612b15cb3dSCy SchubertMany 20622b15cb3dSCy Schubertdrivers support special line discipline/streams modules which can 20632b15cb3dSCy Schubertsignificantly improve the accuracy using the driver. 20642b15cb3dSCy SchubertThese are 20652b15cb3dSCy Schubertdescribed in the 20662b15cb3dSCy Schubert"Line Disciplines and Streams Drivers" 20672b15cb3dSCy Schubertpage 20682b15cb3dSCy Schubert(available as part of the HTML documentation 20692b15cb3dSCy Schubertprovided in 20702b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 20712b15cb3dSCy Schubert 20722b15cb3dSCy Schubert <p>A reference clock will generally (though not always) be a radio 20732b15cb3dSCy Schuberttimecode receiver which is synchronized to a source of standard 20742b15cb3dSCy Schuberttime such as the services offered by the NRC in Canada and NIST and 20752b15cb3dSCy SchubertUSNO in the US. 20762b15cb3dSCy SchubertThe interface between the computer and the timecode 20772b15cb3dSCy Schubertreceiver is device dependent, but is usually a serial port. 20782b15cb3dSCy SchubertA 20792b15cb3dSCy Schubertdevice driver specific to each reference clock must be selected and 20802b15cb3dSCy Schubertcompiled in the distribution; however, most common radio, satellite 20812b15cb3dSCy Schubertand modem clocks are included by default. 20822b15cb3dSCy SchubertNote that an attempt to 20832b15cb3dSCy Schubertconfigure a reference clock when the driver has not been compiled 20842b15cb3dSCy Schubertor the hardware port has not been appropriately configured results 20852b15cb3dSCy Schubertin a scalding remark to the system log file, but is otherwise non 20862b15cb3dSCy Schuberthazardous. 20872b15cb3dSCy Schubert 20882b15cb3dSCy Schubert <p>For the purposes of configuration, 20892b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 20902b15cb3dSCy Schuberttreats 20912b15cb3dSCy Schubertreference clocks in a manner analogous to normal NTP peers as much 20922b15cb3dSCy Schubertas possible. 20932b15cb3dSCy SchubertReference clocks are identified by a syntactically 20942b15cb3dSCy Schubertcorrect but invalid IP address, in order to distinguish them from 20952b15cb3dSCy Schubertnormal NTP peers. 20962b15cb3dSCy SchubertReference clock addresses are of the form 20972b15cb3dSCy Schubert<code>127.127.</code><kbd>t</kbd>.<kbd>u</kbd>, 20982b15cb3dSCy Schubertwhere 20992b15cb3dSCy Schubert<kbd>t</kbd> 21002b15cb3dSCy Schubertis an integer 21012b15cb3dSCy Schubertdenoting the clock type and 21022b15cb3dSCy Schubert<kbd>u</kbd> 21032b15cb3dSCy Schubertindicates the unit 21042b15cb3dSCy Schubertnumber in the range 0-3. 21052b15cb3dSCy SchubertWhile it may seem overkill, it is in fact 21062b15cb3dSCy Schubertsometimes useful to configure multiple reference clocks of the same 21072b15cb3dSCy Schuberttype, in which case the unit numbers must be unique. 21082b15cb3dSCy Schubert 21092b15cb3dSCy Schubert <p>The 21102b15cb3dSCy Schubert<code>server</code> 21112b15cb3dSCy Schubertcommand is used to configure a reference 21122b15cb3dSCy Schubertclock, where the 21132b15cb3dSCy Schubert<kbd>address</kbd> 21142b15cb3dSCy Schubertargument in that command 21152b15cb3dSCy Schubertis the clock address. 21162b15cb3dSCy SchubertThe 21172b15cb3dSCy Schubert<code>key</code>, 21182b15cb3dSCy Schubert<code>version</code> 21192b15cb3dSCy Schubertand 21202b15cb3dSCy Schubert<code>ttl</code> 21212b15cb3dSCy Schubertoptions are not used for reference clock support. 21222b15cb3dSCy SchubertThe 21232b15cb3dSCy Schubert<code>mode</code> 21242b15cb3dSCy Schubertoption is added for reference clock support, as 21252b15cb3dSCy Schubertdescribed below. 21262b15cb3dSCy SchubertThe 21272b15cb3dSCy Schubert<code>prefer</code> 21282b15cb3dSCy Schubertoption can be useful to 21292b15cb3dSCy Schubertpersuade the server to cherish a reference clock with somewhat more 21302b15cb3dSCy Schubertenthusiasm than other reference clocks or peers. 21312b15cb3dSCy SchubertFurther 21322b15cb3dSCy Schubertinformation on this option can be found in the 21332b15cb3dSCy Schubert"Mitigation Rules and the prefer Keyword" 21342b15cb3dSCy Schubert(available as part of the HTML documentation 21352b15cb3dSCy Schubertprovided in 21362b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 21372b15cb3dSCy Schubertpage. 21382b15cb3dSCy SchubertThe 21392b15cb3dSCy Schubert<code>minpoll</code> 21402b15cb3dSCy Schubertand 21412b15cb3dSCy Schubert<code>maxpoll</code> 21422b15cb3dSCy Schubertoptions have 21432b15cb3dSCy Schubertmeaning only for selected clock drivers. 21442b15cb3dSCy SchubertSee the individual clock 21452b15cb3dSCy Schubertdriver document pages for additional information. 21462b15cb3dSCy Schubert 21472b15cb3dSCy Schubert <p>The 21482b15cb3dSCy Schubert<code>fudge</code> 21492b15cb3dSCy Schubertcommand is used to provide additional 21502b15cb3dSCy Schubertinformation for individual clock drivers and normally follows 21512b15cb3dSCy Schubertimmediately after the 21522b15cb3dSCy Schubert<code>server</code> 21532b15cb3dSCy Schubertcommand. 21542b15cb3dSCy SchubertThe 21552b15cb3dSCy Schubert<kbd>address</kbd> 21562b15cb3dSCy Schubertargument specifies the clock address. 21572b15cb3dSCy SchubertThe 21582b15cb3dSCy Schubert<code>refid</code> 21592b15cb3dSCy Schubertand 21602b15cb3dSCy Schubert<code>stratum</code> 21612b15cb3dSCy Schubertoptions can be used to 21622b15cb3dSCy Schubertoverride the defaults for the device. 21632b15cb3dSCy SchubertThere are two optional 21642b15cb3dSCy Schubertdevice-dependent time offsets and four flags that can be included 21652b15cb3dSCy Schubertin the 21662b15cb3dSCy Schubert<code>fudge</code> 21672b15cb3dSCy Schubertcommand as well. 21682b15cb3dSCy Schubert 21692b15cb3dSCy Schubert <p>The stratum number of a reference clock is by default zero. 21702b15cb3dSCy SchubertSince the 21712b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 21722b15cb3dSCy Schubertdaemon adds one to the stratum of each 21732b15cb3dSCy Schubertpeer, a primary server ordinarily displays an external stratum of 21742b15cb3dSCy Schubertone. 21752b15cb3dSCy SchubertIn order to provide engineered backups, it is often useful to 21762b15cb3dSCy Schubertspecify the reference clock stratum as greater than zero. 21772b15cb3dSCy SchubertThe 21782b15cb3dSCy Schubert<code>stratum</code> 21792b15cb3dSCy Schubertoption is used for this purpose. 21802b15cb3dSCy SchubertAlso, in cases 21812b15cb3dSCy Schubertinvolving both a reference clock and a pulse-per-second (PPS) 21822b15cb3dSCy Schubertdiscipline signal, it is useful to specify the reference clock 21832b15cb3dSCy Schubertidentifier as other than the default, depending on the driver. 21842b15cb3dSCy SchubertThe 21852b15cb3dSCy Schubert<code>refid</code> 21862b15cb3dSCy Schubertoption is used for this purpose. 21872b15cb3dSCy SchubertExcept where noted, 21882b15cb3dSCy Schubertthese options apply to all clock drivers. 21892b15cb3dSCy Schubert 21902b15cb3dSCy Schubert<h5 class="subsubsection">Reference Clock Commands</h5> 21912b15cb3dSCy Schubert 21922b15cb3dSCy Schubert <dl> 21932b15cb3dSCy 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 21942b15cb3dSCy Schubertspecial ways. 21952b15cb3dSCy SchubertThe options are interpreted as follows: 21962b15cb3dSCy Schubert <dl> 21972b15cb3dSCy Schubert<dt><code>prefer</code><dd>Marks the reference clock as preferred. 21982b15cb3dSCy SchubertAll other things being 21992b15cb3dSCy Schubertequal, this host will be chosen for synchronization among a set of 22002b15cb3dSCy Schubertcorrectly operating hosts. 22012b15cb3dSCy SchubertSee the 22022b15cb3dSCy Schubert"Mitigation Rules and the prefer Keyword" 22032b15cb3dSCy Schubertpage 22042b15cb3dSCy Schubert(available as part of the HTML documentation 22052b15cb3dSCy Schubertprovided in 22062b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>) 22072b15cb3dSCy Schubertfor further information. 22082b15cb3dSCy Schubert<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 22092b15cb3dSCy Schubertdevice-specific fashion. 22102b15cb3dSCy SchubertFor instance, it selects a dialing 22112b15cb3dSCy Schubertprotocol in the ACTS driver and a device subtype in the 22122b15cb3dSCy Schubertparse 22132b15cb3dSCy Schubertdrivers. 22142b15cb3dSCy 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 22152b15cb3dSCy Schubertfor reference clock messages, as a power of 2 in seconds 22162b15cb3dSCy SchubertFor 22172b15cb3dSCy Schubertmost directly connected reference clocks, both 22182b15cb3dSCy Schubert<code>minpoll</code> 22192b15cb3dSCy Schubertand 22202b15cb3dSCy Schubert<code>maxpoll</code> 22212b15cb3dSCy Schubertdefault to 6 (64 s). 22222b15cb3dSCy SchubertFor modem reference clocks, 22232b15cb3dSCy Schubert<code>minpoll</code> 22242b15cb3dSCy Schubertdefaults to 10 (17.1 m) and 22252b15cb3dSCy Schubert<code>maxpoll</code> 22262b15cb3dSCy Schubertdefaults to 14 (4.5 h). 22272b15cb3dSCy SchubertThe allowable range is 4 (16 s) to 17 (36.4 h) inclusive. 22282b15cb3dSCy Schubert</dl> 22292b15cb3dSCy 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 22302b15cb3dSCy Schubertspecial ways. 22312b15cb3dSCy SchubertIt must immediately follow the 22322b15cb3dSCy Schubert<code>server</code> 22332b15cb3dSCy Schubertcommand which configures the driver. 22342b15cb3dSCy SchubertNote that the same capability 22352b15cb3dSCy Schubertis possible at run time using the 22362b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 22372b15cb3dSCy Schubertprogram. 22382b15cb3dSCy SchubertThe options are interpreted as 22392b15cb3dSCy Schubertfollows: 22402b15cb3dSCy Schubert <dl> 22412b15cb3dSCy Schubert<dt><code>time1</code> <kbd>sec</kbd><dd>Specifies a constant to be added to the time offset produced by 22422b15cb3dSCy Schubertthe driver, a fixed-point decimal number in seconds. 22432b15cb3dSCy SchubertThis is used 22442b15cb3dSCy Schubertas a calibration constant to adjust the nominal time offset of a 22452b15cb3dSCy Schubertparticular clock to agree with an external standard, such as a 22462b15cb3dSCy Schubertprecision PPS signal. 22472b15cb3dSCy SchubertIt also provides a way to correct a 22482b15cb3dSCy Schubertsystematic error or bias due to serial port or operating system 22492b15cb3dSCy Schubertlatencies, different cable lengths or receiver internal delay. 22502b15cb3dSCy SchubertThe 22512b15cb3dSCy Schubertspecified offset is in addition to the propagation delay provided 22522b15cb3dSCy Schubertby other means, such as internal DIPswitches. 22532b15cb3dSCy SchubertWhere a calibration 22542b15cb3dSCy Schubertfor an individual system and driver is available, an approximate 22552b15cb3dSCy Schubertcorrection is noted in the driver documentation pages. 22562b15cb3dSCy SchubertNote: in order to facilitate calibration when more than one 22572b15cb3dSCy Schubertradio clock or PPS signal is supported, a special calibration 22582b15cb3dSCy Schubertfeature is available. 22592b15cb3dSCy SchubertIt takes the form of an argument to the 22602b15cb3dSCy Schubert<code>enable</code> 22612b15cb3dSCy Schubertcommand described in 22622b15cb3dSCy Schubert<a href="#Miscellaneous-Options">Miscellaneous Options</a> 22632b15cb3dSCy Schubertpage and operates as described in the 22642b15cb3dSCy Schubert"Reference Clock Drivers" 22652b15cb3dSCy Schubertpage 22662b15cb3dSCy Schubert(available as part of the HTML documentation 22672b15cb3dSCy Schubertprovided in 22682b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>). 22692b15cb3dSCy Schubert<br><dt><code>time2</code> <kbd>secs</kbd><dd>Specifies a fixed-point decimal number in seconds, which is 22702b15cb3dSCy Schubertinterpreted in a driver-dependent way. 22712b15cb3dSCy SchubertSee the descriptions of 22722b15cb3dSCy Schubertspecific drivers in the 22732b15cb3dSCy Schubert"Reference Clock Drivers" 22742b15cb3dSCy Schubertpage 22752b15cb3dSCy Schubert(available as part of the HTML documentation 22762b15cb3dSCy Schubertprovided in 227709100258SXin LI<span class="file">/usr/share/doc/ntp</span> <span class="file">).</span> 22782b15cb3dSCy Schubert<br><dt><code>stratum</code> <kbd>int</kbd><dd>Specifies the stratum number assigned to the driver, an integer 22792b15cb3dSCy Schubertbetween 0 and 15. 22802b15cb3dSCy SchubertThis number overrides the default stratum number 22812b15cb3dSCy Schubertordinarily assigned by the driver itself, usually zero. 22822b15cb3dSCy Schubert<br><dt><code>refid</code> <kbd>string</kbd><dd>Specifies an ASCII string of from one to four characters which 22832b15cb3dSCy Schubertdefines the reference identifier used by the driver. 22842b15cb3dSCy SchubertThis string 22852b15cb3dSCy Schubertoverrides the default identifier ordinarily assigned by the driver 22862b15cb3dSCy Schubertitself. 22872b15cb3dSCy Schubert<br><dt><code>mode</code> <kbd>int</kbd><dd>Specifies a mode number which is interpreted in a 22882b15cb3dSCy Schubertdevice-specific fashion. 22892b15cb3dSCy SchubertFor instance, it selects a dialing 22902b15cb3dSCy Schubertprotocol in the ACTS driver and a device subtype in the 22912b15cb3dSCy Schubertparse 22922b15cb3dSCy Schubertdrivers. 22932b15cb3dSCy 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. 22942b15cb3dSCy SchubertThe 22952b15cb3dSCy Schubertinterpretation of these values, and whether they are used at all, 22962b15cb3dSCy Schubertis a function of the particular clock driver. 22972b15cb3dSCy SchubertHowever, by 22982b15cb3dSCy Schubertconvention 22992b15cb3dSCy Schubert<code>flag4</code> 23002b15cb3dSCy Schubertis used to enable recording monitoring 23012b15cb3dSCy Schubertdata to the 23022b15cb3dSCy Schubert<code>clockstats</code> 23032b15cb3dSCy Schubertfile configured with the 23042b15cb3dSCy Schubert<code>filegen</code> 23052b15cb3dSCy Schubertcommand. 23062b15cb3dSCy SchubertFurther information on the 23072b15cb3dSCy Schubert<code>filegen</code> 23082b15cb3dSCy Schubertcommand can be found in 23092b15cb3dSCy Schubert<a href="#Monitoring-Options">Monitoring Options</a>. 23102b15cb3dSCy Schubert</dl> 23112b15cb3dSCy Schubert </dl> 23122b15cb3dSCy Schubert<div class="node"> 23132b15cb3dSCy Schubert<p><hr> 23142b15cb3dSCy Schubert<a name="Miscellaneous-Options"></a> 23152b15cb3dSCy Schubert<br> 23162b15cb3dSCy Schubert</div> 23172b15cb3dSCy Schubert 23182b15cb3dSCy Schubert<h4 class="subsection">Miscellaneous Options</h4> 23192b15cb3dSCy Schubert 23202b15cb3dSCy Schubert <dl> 23212b15cb3dSCy Schubert<dt><code>broadcastdelay</code> <kbd>seconds</kbd><dd>The broadcast and multicast modes require a special calibration 23222b15cb3dSCy Schubertto determine the network delay between the local and remote 23232b15cb3dSCy Schubertservers. 23242b15cb3dSCy SchubertOrdinarily, this is done automatically by the initial 23252b15cb3dSCy Schubertprotocol exchanges between the client and server. 23262b15cb3dSCy SchubertIn some cases, 23272b15cb3dSCy Schubertthe calibration procedure may fail due to network or server access 23282b15cb3dSCy Schubertcontrols, for example. 23292b15cb3dSCy SchubertThis command specifies the default delay to 23302b15cb3dSCy Schubertbe used under these circumstances. 23312b15cb3dSCy SchubertTypically (for Ethernet), a 23322b15cb3dSCy Schubertnumber between 0.003 and 0.007 seconds is appropriate. 23332b15cb3dSCy SchubertThe default 23342b15cb3dSCy Schubertwhen this command is not used is 0.004 seconds. 23352b15cb3dSCy Schubert<br><dt><code>calldelay</code> <kbd>delay</kbd><dd>This option controls the delay in seconds between the first and second 23362b15cb3dSCy Schubertpackets sent in burst or iburst mode to allow additional time for a modem 23372b15cb3dSCy Schubertor ISDN call to complete. 23382b15cb3dSCy Schubert<br><dt><code>driftfile</code> <kbd>driftfile</kbd><dd>This command specifies the complete path and name of the file used to 23392b15cb3dSCy Schubertrecord the frequency of the local clock oscillator. 23402b15cb3dSCy SchubertThis is the same 23412b15cb3dSCy Schubertoperation as the 23422b15cb3dSCy Schubert<code>-f</code> 23432b15cb3dSCy Schubertcommand line option. 23442b15cb3dSCy SchubertIf the file exists, it is read at 23452b15cb3dSCy Schubertstartup in order to set the initial frequency and then updated once per 23462b15cb3dSCy Schuberthour with the current frequency computed by the daemon. 23472b15cb3dSCy SchubertIf the file name is 23482b15cb3dSCy Schubertspecified, but the file itself does not exist, the starts with an initial 23492b15cb3dSCy Schubertfrequency of zero and creates the file when writing it for the first time. 23502b15cb3dSCy SchubertIf this command is not given, the daemon will always start with an initial 23512b15cb3dSCy Schubertfrequency of zero. 23522b15cb3dSCy Schubert 23532b15cb3dSCy Schubert <p>The file format consists of a single line containing a single 23542b15cb3dSCy Schubertfloating point number, which records the frequency offset measured 23552b15cb3dSCy Schubertin parts-per-million (PPM). 23562b15cb3dSCy SchubertThe file is updated by first writing 23572b15cb3dSCy Schubertthe current drift value into a temporary file and then renaming 23582b15cb3dSCy Schubertthis file to replace the old version. 23592b15cb3dSCy SchubertThis implies that 23602b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 23612b15cb3dSCy Schubertmust have write permission for the directory the 23622b15cb3dSCy Schubertdrift file is located in, and that file system links, symbolic or 23632b15cb3dSCy Schubertotherwise, should be avoided. 2364276da39aSCy Schubert<br><dt><code>dscp</code> <kbd>value</kbd><dd>This option specifies the Differentiated Services Control Point (DSCP) value, 2365e27abb66SXin LIa 6-bit code. 2366e27abb66SXin LIThe default value is 46, signifying Expedited Forwarding. 2367e27abb66SXin LI<br><dt><code>enable</code> <code>[auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats | peer_clear_digest_early | unpeer_crypto_early | unpeer_crypto_nak_early | unpeer_digest_early]</code><br><dt><code>disable</code> <code>[auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats | peer_clear_digest_early | unpeer_crypto_early | unpeer_crypto_nak_early | unpeer_digest_early]</code><dd>Provides a way to enable or disable various server options. 23682b15cb3dSCy SchubertFlags not mentioned are unaffected. 23692b15cb3dSCy SchubertNote that all of these flags 23702b15cb3dSCy Schubertcan be controlled remotely using the 23712b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 23722b15cb3dSCy Schubertutility program. 23732b15cb3dSCy Schubert <dl> 23742b15cb3dSCy Schubert<dt><code>auth</code><dd>Enables the server to synchronize with unconfigured peers only if the 23752b15cb3dSCy Schubertpeer has been correctly authenticated using either public key or 23762b15cb3dSCy Schubertprivate key cryptography. 23772b15cb3dSCy SchubertThe default for this flag is 23782b15cb3dSCy Schubert<code>enable</code>. 23792b15cb3dSCy Schubert<br><dt><code>bclient</code><dd>Enables the server to listen for a message from a broadcast or 23802b15cb3dSCy Schubertmulticast server, as in the 23812b15cb3dSCy Schubert<code>multicastclient</code> 23822b15cb3dSCy Schubertcommand with default 23832b15cb3dSCy Schubertaddress. 23842b15cb3dSCy SchubertThe default for this flag is 23852b15cb3dSCy Schubert<code>disable</code>. 23862b15cb3dSCy Schubert<br><dt><code>calibrate</code><dd>Enables the calibrate feature for reference clocks. 23872b15cb3dSCy SchubertThe default for 23882b15cb3dSCy Schubertthis flag is 23892b15cb3dSCy Schubert<code>disable</code>. 23902b15cb3dSCy Schubert<br><dt><code>kernel</code><dd>Enables the kernel time discipline, if available. 23912b15cb3dSCy SchubertThe default for this 23922b15cb3dSCy Schubertflag is 23932b15cb3dSCy Schubert<code>enable</code> 23942b15cb3dSCy Schubertif support is available, otherwise 23952b15cb3dSCy Schubert<code>disable</code>. 23962b15cb3dSCy Schubert<br><dt><code>mode7</code><dd>Enables processing of NTP mode 7 implementation-specific requests 23972b15cb3dSCy Schubertwhich are used by the deprecated 23982b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 23992b15cb3dSCy Schubertprogram. 24002b15cb3dSCy SchubertThe default for this flag is disable. 24012b15cb3dSCy SchubertThis flag is excluded from runtime configuration using 24022b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code>. 24032b15cb3dSCy SchubertThe 24042b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 24052b15cb3dSCy Schubertprogram provides the same capabilities as 24062b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 24072b15cb3dSCy Schubertusing standard mode 6 requests. 24082b15cb3dSCy Schubert<br><dt><code>monitor</code><dd>Enables the monitoring facility. 24092b15cb3dSCy SchubertSee the 24102b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code> 24112b15cb3dSCy Schubertprogram 24122b15cb3dSCy Schubertand the 24132b15cb3dSCy Schubert<code>monlist</code> 24142b15cb3dSCy Schubertcommand or further information. 24152b15cb3dSCy SchubertThe 24162b15cb3dSCy Schubertdefault for this flag is 24172b15cb3dSCy Schubert<code>enable</code>. 24182b15cb3dSCy Schubert<br><dt><code>ntp</code><dd>Enables time and frequency discipline. 24192b15cb3dSCy SchubertIn effect, this switch opens and 24202b15cb3dSCy Schubertcloses the feedback loop, which is useful for testing. 24212b15cb3dSCy SchubertThe default for 24222b15cb3dSCy Schubertthis flag is 24232b15cb3dSCy Schubert<code>enable</code>. 2424e27abb66SXin LI<br><dt><code>peer_clear_digest_early</code><dd>By default, if 2425e27abb66SXin LI<code>ntpd(1ntpdmdoc)</code> 2426e27abb66SXin LIis using autokey and it 2427e27abb66SXin LIreceives a crypto-NAK packet that 2428e27abb66SXin LIpasses the duplicate packet and origin timestamp checks 2429e27abb66SXin LIthe peer variables are immediately cleared. 2430e27abb66SXin LIWhile this is generally a feature 2431e27abb66SXin LIas it allows for quick recovery if a server key has changed, 2432e27abb66SXin LIa properly forged and appropriately delivered crypto-NAK packet 2433e27abb66SXin LIcan be used in a DoS attack. 2434e27abb66SXin LIIf you have active noticable problems with this type of DoS attack 2435e27abb66SXin LIthen you should consider 2436e27abb66SXin LIdisabling this option. 2437e27abb66SXin LIYou can check your 2438e27abb66SXin LI<code>peerstats</code> 2439e27abb66SXin LIfile for evidence of any of these attacks. 2440e27abb66SXin LIThe 2441e27abb66SXin LIdefault for this flag is 2442e27abb66SXin LI<code>enable</code>. 24432b15cb3dSCy Schubert<br><dt><code>stats</code><dd>Enables the statistics facility. 24442b15cb3dSCy SchubertSee the 24452b15cb3dSCy Schubert<a href="#Monitoring-Options">Monitoring Options</a> 24462b15cb3dSCy Schubertsection for further information. 24472b15cb3dSCy SchubertThe default for this flag is 24482b15cb3dSCy Schubert<code>disable</code>. 244968ba7e87SXin LI<br><dt><code>unpeer_crypto_early</code><dd>By default, if 245068ba7e87SXin LI<code>ntpd(1ntpdmdoc)</code> 245168ba7e87SXin LIreceives an autokey packet that fails TEST9, 245268ba7e87SXin LIa crypto failure, 245368ba7e87SXin LIthe association is immediately cleared. 245468ba7e87SXin LIThis is almost certainly a feature, 245568ba7e87SXin LIbut if, in spite of the current recommendation of not using autokey, 245668ba7e87SXin LIyou are 245768ba7e87SXin LI.B still 245868ba7e87SXin LIusing autokey 245968ba7e87SXin LI.B and 246068ba7e87SXin LIyou are seeing this sort of DoS attack 246168ba7e87SXin LIdisabling this flag will delay 246268ba7e87SXin LItearing down the association until the reachability counter 246368ba7e87SXin LIbecomes zero. 246468ba7e87SXin LIYou can check your 246568ba7e87SXin LI<code>peerstats</code> 246668ba7e87SXin LIfile for evidence of any of these attacks. 246768ba7e87SXin LIThe 246868ba7e87SXin LIdefault for this flag is 246968ba7e87SXin LI<code>enable</code>. 247068ba7e87SXin LI<br><dt><code>unpeer_crypto_nak_early</code><dd>By default, if 247168ba7e87SXin LI<code>ntpd(1ntpdmdoc)</code> 247268ba7e87SXin LIreceives a crypto-NAK packet that 247368ba7e87SXin LIpasses the duplicate packet and origin timestamp checks 247468ba7e87SXin LIthe association is immediately cleared. 247568ba7e87SXin LIWhile this is generally a feature 247668ba7e87SXin LIas it allows for quick recovery if a server key has changed, 247768ba7e87SXin LIa properly forged and appropriately delivered crypto-NAK packet 247868ba7e87SXin LIcan be used in a DoS attack. 247968ba7e87SXin LIIf you have active noticable problems with this type of DoS attack 248068ba7e87SXin LIthen you should consider 248168ba7e87SXin LIdisabling this option. 248268ba7e87SXin LIYou can check your 248368ba7e87SXin LI<code>peerstats</code> 248468ba7e87SXin LIfile for evidence of any of these attacks. 248568ba7e87SXin LIThe 248668ba7e87SXin LIdefault for this flag is 248768ba7e87SXin LI<code>enable</code>. 248868ba7e87SXin LI<br><dt><code>unpeer_digest_early</code><dd>By default, if 248968ba7e87SXin LI<code>ntpd(1ntpdmdoc)</code> 249068ba7e87SXin LIreceives what should be an authenticated packet 249168ba7e87SXin LIthat passes other packet sanity checks but 249268ba7e87SXin LIcontains an invalid digest 249368ba7e87SXin LIthe association is immediately cleared. 249468ba7e87SXin LIWhile this is generally a feature 249568ba7e87SXin LIas it allows for quick recovery, 249668ba7e87SXin LIif this type of packet is carefully forged and sent 249768ba7e87SXin LIduring an appropriate window it can be used for a DoS attack. 249868ba7e87SXin LIIf you have active noticable problems with this type of DoS attack 249968ba7e87SXin LIthen you should consider 250068ba7e87SXin LIdisabling this option. 250168ba7e87SXin LIYou can check your 250268ba7e87SXin LI<code>peerstats</code> 250368ba7e87SXin LIfile for evidence of any of these attacks. 250468ba7e87SXin LIThe 250568ba7e87SXin LIdefault for this flag is 250668ba7e87SXin LI<code>enable</code>. 25072b15cb3dSCy Schubert</dl> 25082b15cb3dSCy Schubert <br><dt><code>includefile</code> <kbd>includefile</kbd><dd>This command allows additional configuration commands 25092b15cb3dSCy Schubertto be included from a separate file. 25102b15cb3dSCy SchubertInclude files may 25112b15cb3dSCy Schubertbe nested to a depth of five; upon reaching the end of any 25122b15cb3dSCy Schubertinclude file, command processing resumes in the previous 25132b15cb3dSCy Schubertconfiguration file. 25142b15cb3dSCy SchubertThis option is useful for sites that run 25152b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 25162b15cb3dSCy Schuberton multiple hosts, with (mostly) common options (e.g., a 25172b15cb3dSCy Schubertrestriction list). 251809100258SXin LI<br><dt><code>interface</code> <code>[listen | ignore | drop]</code> <code>[all | ipv4 | ipv6 | wildcard </code><kbd>name</kbd><code> | </code><kbd>address</kbd><code> [/ </code><kbd>prefixlen</kbd><code>]]</code><dd>The 251909100258SXin LI<code>interface</code> 252009100258SXin LIdirective controls which network addresses 252109100258SXin LI<code>ntpd(1ntpdmdoc)</code> 252209100258SXin LIopens, and whether input is dropped without processing. 252309100258SXin LIThe first parameter determines the action for addresses 252409100258SXin LIwhich match the second parameter. 252509100258SXin LIThe second parameter specifies a class of addresses, 252609100258SXin LIor a specific interface name, 252709100258SXin LIor an address. 252809100258SXin LIIn the address case, 252909100258SXin LI<kbd>prefixlen</kbd> 253009100258SXin LIdetermines how many bits must match for this rule to apply. 253109100258SXin LI<code>ignore</code> 253209100258SXin LIprevents opening matching addresses, 253309100258SXin LI<code>drop</code> 253409100258SXin LIcauses 253509100258SXin LI<code>ntpd(1ntpdmdoc)</code> 253609100258SXin LIto open the address and drop all received packets without examination. 253709100258SXin LIMultiple 253809100258SXin LI<code>interface</code> 253909100258SXin LIdirectives can be used. 254009100258SXin LIThe last rule which matches a particular address determines the action for it. 254109100258SXin LI<code>interface</code> 254209100258SXin LIdirectives are disabled if any 254309100258SXin LI<code>-I</code>, 254409100258SXin LI<code>--interface</code>, 254509100258SXin LI<code>-L</code>, 254609100258SXin LIor 254709100258SXin LI<code>--novirtualips</code> 254809100258SXin LIcommand-line options are specified in the configuration file, 254909100258SXin LIall available network addresses are opened. 255009100258SXin LIThe 255109100258SXin LI<code>nic</code> 255209100258SXin LIdirective is an alias for 255309100258SXin LI<code>interface</code>. 255409100258SXin LI<br><dt><code>leapfile</code> <kbd>leapfile</kbd><dd>This command loads the IERS leapseconds file and initializes the 255509100258SXin LIleapsecond values for the next leapsecond event, leapfile expiration 255609100258SXin LItime, and TAI offset. 255709100258SXin LIThe file can be obtained directly from the IERS at 255809100258SXin LI<code>https://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</code> 255909100258SXin LIor 256009100258SXin LI<code>ftp://hpiers.obspm.fr/iers/bul/bulc/ntp/leap-seconds.list</code>. 256109100258SXin LIThe 256209100258SXin LI<code>leapfile</code> 256309100258SXin LIis scanned when 256409100258SXin LI<code>ntpd(1ntpdmdoc)</code> 256509100258SXin LIprocesses the 256609100258SXin LI<code>leapfile</code> <code>directive</code> <code>or</code> <code>when</code> 256709100258SXin LI<code>ntpd</code> <code>detects</code> <code>that</code> <code>the</code> 256809100258SXin LI<kbd>leapfile</kbd> 256909100258SXin LIhas changed. 257009100258SXin LI<code>ntpd</code> 257109100258SXin LIchecks once a day to see if the 257209100258SXin LI<kbd>leapfile</kbd> 257309100258SXin LIhas changed. 257409100258SXin LIThe 257509100258SXin LI<code>update-leap(1update_leapmdoc)</code> 257609100258SXin LIscript can be run to see if the 257709100258SXin LI<kbd>leapfile</kbd> 257809100258SXin LIshould be updated. 2579276da39aSCy Schubert<br><dt><code>leapsmearinterval</code> <kbd>seconds</kbd><dd>This EXPERIMENTAL option is only available if 2580276da39aSCy Schubert<code>ntpd(1ntpdmdoc)</code> 2581276da39aSCy Schubertwas built with the 2582276da39aSCy Schubert<code>--enable-leap-smear</code> 2583276da39aSCy Schubertoption to the 2584276da39aSCy Schubert<code>configure</code> 2585276da39aSCy Schubertscript. 2586276da39aSCy SchubertIt specifies the interval over which a leap second correction will be applied. 2587276da39aSCy SchubertRecommended values for this option are between 2588276da39aSCy Schubert7200 (2 hours) and 86400 (24 hours). 2589276da39aSCy Schubert.Sy DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS! 2590276da39aSCy SchubertSee http://bugs.ntp.org/2855 for more information. 25912b15cb3dSCy Schubert<br><dt><code>logconfig</code> <kbd>configkeyword</kbd><dd>This command controls the amount and type of output written to 25922b15cb3dSCy Schubertthe system 25932b15cb3dSCy Schubert<code>syslog(3)</code> 25942b15cb3dSCy Schubertfacility or the alternate 25952b15cb3dSCy Schubert<code>logfile</code> 25962b15cb3dSCy Schubertlog file. 25972b15cb3dSCy SchubertBy default, all output is turned on. 25982b15cb3dSCy SchubertAll 25992b15cb3dSCy Schubert<kbd>configkeyword</kbd> 26002b15cb3dSCy Schubertkeywords can be prefixed with 26012b15cb3dSCy Schubert=, 26022b15cb3dSCy Schubert+ 26032b15cb3dSCy Schubertand 26042b15cb3dSCy Schubert-, 26052b15cb3dSCy Schubertwhere 26062b15cb3dSCy Schubert= 26072b15cb3dSCy Schubertsets the 26082b15cb3dSCy Schubert<code>syslog(3)</code> 26092b15cb3dSCy Schubertpriority mask, 26102b15cb3dSCy Schubert+ 26112b15cb3dSCy Schubertadds and 26122b15cb3dSCy Schubert- 26132b15cb3dSCy Schubertremoves 26142b15cb3dSCy Schubertmessages. 26152b15cb3dSCy Schubert<code>syslog(3)</code> 26162b15cb3dSCy Schubertmessages can be controlled in four 26172b15cb3dSCy Schubertclasses 26182b15cb3dSCy Schubert(<code>clock</code>, <code>peer</code>, <code>sys</code> and <code>sync</code>). 26192b15cb3dSCy SchubertWithin these classes four types of messages can be 26202b15cb3dSCy Schubertcontrolled: informational messages 26212b15cb3dSCy Schubert(<code>info</code>), 26222b15cb3dSCy Schubertevent messages 26232b15cb3dSCy Schubert(<code>events</code>), 26242b15cb3dSCy Schubertstatistics messages 26252b15cb3dSCy Schubert(<code>statistics</code>) 26262b15cb3dSCy Schubertand 26272b15cb3dSCy Schubertstatus messages 26282b15cb3dSCy Schubert(<code>status</code>). 26292b15cb3dSCy Schubert 26302b15cb3dSCy Schubert <p>Configuration keywords are formed by concatenating the message class with 26312b15cb3dSCy Schubertthe event class. 26322b15cb3dSCy SchubertThe 26332b15cb3dSCy Schubert<code>all</code> 26342b15cb3dSCy Schubertprefix can be used instead of a message class. 26352b15cb3dSCy SchubertA 26362b15cb3dSCy Schubertmessage class may also be followed by the 26372b15cb3dSCy Schubert<code>all</code> 26382b15cb3dSCy Schubertkeyword to enable/disable all 2639e27abb66SXin LImessages of the respective message class. 2640e27abb66SXin LIThus, a minimal log configuration 26412b15cb3dSCy Schubertcould look like this: 26422b15cb3dSCy Schubert<pre class="verbatim"> 26432b15cb3dSCy Schubert logconfig =syncstatus +sysevents 26442b15cb3dSCy Schubert</pre> 26452b15cb3dSCy Schubert 26462b15cb3dSCy Schubert <p>This would just list the synchronizations state of 26472b15cb3dSCy Schubert<code>ntpd(1ntpdmdoc)</code> 26482b15cb3dSCy Schubertand the major system events. 26492b15cb3dSCy SchubertFor a simple reference server, the 26502b15cb3dSCy Schubertfollowing minimum message configuration could be useful: 26512b15cb3dSCy Schubert<pre class="verbatim"> 26522b15cb3dSCy Schubert logconfig =syncall +clockall 26532b15cb3dSCy Schubert</pre> 26542b15cb3dSCy Schubert 26552b15cb3dSCy Schubert <p>This configuration will list all clock information and 26562b15cb3dSCy Schubertsynchronization information. 26572b15cb3dSCy SchubertAll other events and messages about 26582b15cb3dSCy Schubertpeers, system events and so on is suppressed. 26592b15cb3dSCy Schubert<br><dt><code>logfile</code> <kbd>logfile</kbd><dd>This command specifies the location of an alternate log file to 26602b15cb3dSCy Schubertbe used instead of the default system 26612b15cb3dSCy Schubert<code>syslog(3)</code> 26622b15cb3dSCy Schubertfacility. 26634990d495SXin LIThis is the same operation as the 26644990d495SXin LI<code>-l</code> 26654990d495SXin LIcommand line option. 266609100258SXin LI<br><dt><code>mru</code> <code>[maxdepth </code><kbd>count</kbd><code> | maxmem </code><kbd>kilobytes</kbd><code> | mindepth </code><kbd>count</kbd><code> | maxage </code><kbd>seconds</kbd><code> | initialloc </code><kbd>count</kbd><code> | initmem </code><kbd>kilobytes</kbd><code> | incalloc </code><kbd>count</kbd><code> | incmem </code><kbd>kilobytes</kbd><code>]</code><dd>Controls size limite of the monitoring facility's Most Recently Used 266709100258SXin LI(MRU) list 266809100258SXin LIof client addresses, which is also used by the 266909100258SXin LIrate control facility. 267009100258SXin LI <dl> 267109100258SXin LI<dt><code>maxdepth</code> <kbd>count</kbd><br><dt><code>maxmem</code> <kbd>kilobytes</kbd><dd>Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. 267209100258SXin LIThe acutal limit will be up to 267309100258SXin LI<code>incalloc</code> 267409100258SXin LIentries or 267509100258SXin LI<code>incmem</code> 267609100258SXin LIkilobytes larger. 267709100258SXin LIAs with all of the 267809100258SXin LI<code>mru</code> 267909100258SXin LIoptions offered in units of entries or kilobytes, if both 268009100258SXin LI<code>maxdepth</code> 268109100258SXin LIand 268209100258SXin LI<code>maxmem</code> <code>are</code> <code>used,</code> <code>the</code> <code>last</code> <code>one</code> <code>used</code> <code>controls.</code> 268309100258SXin LIThe default is 1024 kilobytes. 268409100258SXin LI<br><dt><code>mindepth</code> <kbd>count</kbd><dd>Lower limit on the MRU list size. 268509100258SXin LIWhen the MRU list has fewer than 268609100258SXin LI<code>mindepth</code> 268709100258SXin LIentries, existing entries are never removed to make room for newer ones, 268809100258SXin LIregardless of their age. 268909100258SXin LIThe default is 600 entries. 269009100258SXin LI<br><dt><code>maxage</code> <kbd>seconds</kbd><dd>Once the MRU list has 269109100258SXin LI<code>mindepth</code> 269209100258SXin LIentries and an additional client is to ba added to the list, 269309100258SXin LIif the oldest entry was updated more than 269409100258SXin LI<code>maxage</code> 269509100258SXin LIseconds ago, that entry is removed and its storage is reused. 269609100258SXin LIIf the oldest entry was updated more recently the MRU list is grown, 269709100258SXin LIsubject to 269809100258SXin LI<code>maxdepth</code> <code>/</code> <code>moxmem</code>. 269909100258SXin LIThe default is 64 seconds. 270009100258SXin LI<br><dt><code>initalloc</code> <kbd>count</kbd><br><dt><code>initmem</code> <kbd>kilobytes</kbd><dd>Initial memory allocation at the time the monitoringfacility is first enabled, 270109100258SXin LIin terms of the number of entries or kilobytes. 270209100258SXin LIThe default is 4 kilobytes. 270309100258SXin LI<br><dt><code>incalloc</code> <kbd>count</kbd><br><dt><code>incmem</code> <kbd>kilobytes</kbd><dd>Size of additional memory allocations when growing the MRU list, in entries or kilobytes. 270409100258SXin LIThe default is 4 kilobytes. 270509100258SXin LI</dl> 270609100258SXin LI <br><dt><code>nonvolatile</code> <kbd>threshold</kbd><dd>Specify the 270709100258SXin LI<kbd>threshold</kbd> 270809100258SXin LIdelta in seconds before an hourly change to the 270909100258SXin LI<code>driftfile</code> 271009100258SXin LI(frequency file) will be written, with a default value of 1e-7 (0.1 PPM). 271109100258SXin LIThe frequency file is inspected each hour. 271209100258SXin LIIf the difference between the current frequency and the last value written 271309100258SXin LIexceeds the threshold, the file is written and the 271409100258SXin LI<code>threshold</code> 271509100258SXin LIbecomes the new threshold value. 271609100258SXin LIIf the threshold is not exceeeded, it is reduced by half. 271709100258SXin LIThis is intended to reduce the number of file writes 271809100258SXin LIfor embedded systems with nonvolatile memory. 271909100258SXin LI<br><dt><code>phone</code> <kbd>dial</kbd> <kbd>...</kbd><dd>This command is used in conjunction with 272009100258SXin LIthe ACTS modem driver (type 18) 272109100258SXin LIor the JJY driver (type 40, mode 100 - 180). 272209100258SXin LIFor the ACTS modem driver (type 18), the arguments consist of 272309100258SXin LIa maximum of 10 telephone numbers used to dial USNO, NIST, or European 272409100258SXin LItime service. 272509100258SXin LIFor the JJY driver (type 40 mode 100 - 180), the argument is 272609100258SXin LIone telephone number used to dial the telephone JJY service. 272709100258SXin LIThe Hayes command ATDT is normally prepended to the number. 272809100258SXin LIThe number can contain other modem control codes as well. 272909100258SXin LI<br><dt><code>reset</code> <code>[allpeers]</code> <code>[auth]</code> <code>[ctl]</code> <code>[io]</code> <code>[mem]</code> <code>[sys]</code> <code>[timer]</code><dd>Reset one or more groups of counters maintained by 273009100258SXin LI<code>ntpd</code> 273109100258SXin LIand exposed by 273209100258SXin LI<code>ntpq</code> 273309100258SXin LIand 273409100258SXin LI<code>ntpdc</code>. 273509100258SXin LI<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> 273609100258SXin LI <dl> 273709100258SXin LI<dt><code>memlock</code> <kbd>Nmegabytes</kbd><dd>Specify the number of megabytes of memory that should be 273809100258SXin LIallocated and locked. 273909100258SXin LIProbably only available under Linux, this option may be useful 274009100258SXin LIwhen dropping root (the 274109100258SXin LI<code>-i</code> 274209100258SXin LIoption). 274309100258SXin LIThe default is 32 megabytes on non-Linux machines, and -1 under Linux. 274409100258SXin LI-1 means "do not lock the process into memory". 274509100258SXin LI0 means "lock whatever memory the process wants into memory". 274609100258SXin LI<br><dt><code>stacksize</code> <kbd>N4kPages</kbd><dd>Specifies the maximum size of the process stack on systems with the 274709100258SXin LI<code>mlockall()</code> 274809100258SXin LIfunction. 274909100258SXin LIDefaults to 50 4k pages (200 4k pages in OpenBSD). 275009100258SXin LI<br><dt><code>filenum</code> <kbd>Nfiledescriptors</kbd><dd>Specifies the maximum number of file descriptors ntpd may have open at once. 275109100258SXin LIDefaults to the system default. 275209100258SXin LI</dl> 275309100258SXin LI <br><dt><code>saveconfigdir</code> <kbd>directory_path</kbd><dd>Specify the directory in which to write configuration snapshots 275409100258SXin LIrequested with 275509100258SXin LI.Cm ntpq 's 275609100258SXin LI<code>saveconfig</code> 275709100258SXin LIcommand. 275809100258SXin LIIf 275909100258SXin LI<code>saveconfigdir</code> 276009100258SXin LIdoes not appear in the configuration file, 276109100258SXin LI<code>saveconfig</code> 276209100258SXin LIrequests are rejected by 276309100258SXin LI<code>ntpd</code>. 276409100258SXin LI<br><dt><code>saveconfig</code> <kbd>filename</kbd><dd>Write the current configuration, including any runtime 276509100258SXin LImodifications given with 276609100258SXin LI<code>:config</code> 276709100258SXin LIor 276809100258SXin LI<code>config-from-file</code> 276909100258SXin LIto the 277009100258SXin LI<code>ntpd</code> 277109100258SXin LIhost's 277209100258SXin LI<kbd>filename</kbd> 277309100258SXin LIin the 277409100258SXin LI<code>saveconfigdir</code>. 277509100258SXin LIThis command will be rejected unless the 277609100258SXin LI<code>saveconfigdir</code> 277709100258SXin LIdirective appears in 277809100258SXin LI.Cm ntpd 's 277909100258SXin LIconfiguration file. 278009100258SXin LI<kbd>filename</kbd> 278109100258SXin LIcan use 278209100258SXin LI<code>strftime(3)</code> 278309100258SXin LIformat directives to substitute the current date and time, 278409100258SXin LIfor example, 278509100258SXin LI<code>saveconfig\ ntp-%Y%m%d-%H%M%S.conf</code>. 278609100258SXin LIThe filename used is stored in the system variable 278709100258SXin LI<code>savedconfig</code>. 278809100258SXin LIAuthentication is required. 27892b15cb3dSCy Schubert<br><dt><code>setvar</code> <kbd>variable</kbd> <code>[default]</code><dd>This command adds an additional system variable. 27902b15cb3dSCy SchubertThese 27912b15cb3dSCy Schubertvariables can be used to distribute additional information such as 27922b15cb3dSCy Schubertthe access policy. 27932b15cb3dSCy SchubertIf the variable of the form 27942b15cb3dSCy Schubert<code>name</code><code>=</code><kbd>value</kbd> 27952b15cb3dSCy Schubertis followed by the 27962b15cb3dSCy Schubert<code>default</code> 27972b15cb3dSCy Schubertkeyword, the 27982b15cb3dSCy Schubertvariable will be listed as part of the default system variables 27992b15cb3dSCy Schubert(<code>rv</code> command)). 28002b15cb3dSCy SchubertThese additional variables serve 28012b15cb3dSCy Schubertinformational purposes only. 28022b15cb3dSCy SchubertThey are not related to the protocol 28032b15cb3dSCy Schubertother that they can be listed. 28042b15cb3dSCy SchubertThe known protocol variables will 28052b15cb3dSCy Schubertalways override any variables defined via the 28062b15cb3dSCy Schubert<code>setvar</code> 28072b15cb3dSCy Schubertmechanism. 28082b15cb3dSCy SchubertThere are three special variables that contain the names 28092b15cb3dSCy Schubertof all variable of the same group. 28102b15cb3dSCy SchubertThe 28112b15cb3dSCy Schubert<code>sys_var_list</code> 28122b15cb3dSCy Schubertholds 28132b15cb3dSCy Schubertthe names of all system variables. 28142b15cb3dSCy SchubertThe 28152b15cb3dSCy Schubert<code>peer_var_list</code> 28162b15cb3dSCy Schubertholds 28172b15cb3dSCy Schubertthe names of all peer variables and the 28182b15cb3dSCy Schubert<code>clock_var_list</code> 28192b15cb3dSCy Schubertholds the names of the reference clock variables. 282009100258SXin LI<br><dt><code>sysinfo</code><dd>Display operational summary. 282109100258SXin LI<br><dt><code>sysstats</code><dd>Show statistics counters maintained in the protocol module. 2822a25439b6SCy 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 28232b15cb3dSCy Schubertvery exceptional circumstances. 28242b15cb3dSCy SchubertIt should occur in the 28252b15cb3dSCy Schubertconfiguration file before any other configuration options. 28262b15cb3dSCy SchubertThe 28272b15cb3dSCy Schubertdefault values of these variables have been carefully optimized for 28282b15cb3dSCy Schuberta wide range of network speeds and reliability expectations. 28292b15cb3dSCy SchubertIn 28302b15cb3dSCy Schubertgeneral, they interact in intricate ways that are hard to predict 28312b15cb3dSCy Schubertand some combinations can result in some very nasty behavior. 28322b15cb3dSCy SchubertVery 28332b15cb3dSCy Schubertrarely is it necessary to change the default values; but, some 28342b15cb3dSCy Schubertfolks cannot resist twisting the knobs anyway and this command is 28352b15cb3dSCy Schubertfor them. 28362b15cb3dSCy SchubertEmphasis added: twisters are on their own and can expect 28372b15cb3dSCy Schubertno help from the support group. 28382b15cb3dSCy Schubert 28392b15cb3dSCy Schubert <p>The variables operate as follows: 28402b15cb3dSCy Schubert <dl> 28412b15cb3dSCy Schubert<dt><code>allan</code> <kbd>allan</kbd><dd>The argument becomes the new value for the minimum Allan 28422b15cb3dSCy Schubertintercept, which is a parameter of the PLL/FLL clock discipline 28432b15cb3dSCy Schubertalgorithm. 28442b15cb3dSCy SchubertThe value in log2 seconds defaults to 7 (1024 s), which is also the lower 28452b15cb3dSCy Schubertlimit. 28462b15cb3dSCy Schubert<br><dt><code>dispersion</code> <kbd>dispersion</kbd><dd>The argument becomes the new value for the dispersion increase rate, 28472b15cb3dSCy Schubertnormally .000015 s/s. 28482b15cb3dSCy Schubert<br><dt><code>freq</code> <kbd>freq</kbd><dd>The argument becomes the initial value of the frequency offset in 28492b15cb3dSCy Schubertparts-per-million. 28502b15cb3dSCy SchubertThis overrides the value in the frequency file, if 28512b15cb3dSCy Schubertpresent, and avoids the initial training state if it is not. 28522b15cb3dSCy Schubert<br><dt><code>huffpuff</code> <kbd>huffpuff</kbd><dd>The argument becomes the new value for the experimental 28532b15cb3dSCy Schuberthuff-n'-puff filter span, which determines the most recent interval 28542b15cb3dSCy Schubertthe algorithm will search for a minimum delay. 28552b15cb3dSCy SchubertThe lower limit is 28562b15cb3dSCy Schubert900 s (15 m), but a more reasonable value is 7200 (2 hours). 28572b15cb3dSCy SchubertThere 28582b15cb3dSCy Schubertis no default, since the filter is not enabled unless this command 28592b15cb3dSCy Schubertis given. 28602b15cb3dSCy Schubert<br><dt><code>panic</code> <kbd>panic</kbd><dd>The argument is the panic threshold, normally 1000 s. 28612b15cb3dSCy SchubertIf set to zero, 28622b15cb3dSCy Schubertthe panic sanity check is disabled and a clock offset of any value will 28632b15cb3dSCy Schubertbe accepted. 28642b15cb3dSCy Schubert<br><dt><code>step</code> <kbd>step</kbd><dd>The argument is the step threshold, which by default is 0.128 s. 28652b15cb3dSCy SchubertIt can 28662b15cb3dSCy Schubertbe set to any positive number in seconds. 28672b15cb3dSCy SchubertIf set to zero, step 28682b15cb3dSCy Schubertadjustments will never occur. 28692b15cb3dSCy SchubertNote: The kernel time discipline is 28702b15cb3dSCy Schubertdisabled if the step threshold is set to zero or greater than the 28712b15cb3dSCy Schubertdefault. 2872a25439b6SCy Schubert<br><dt><code>stepback</code> <kbd>stepback</kbd><dd>The argument is the step threshold for the backward direction, 2873a25439b6SCy Schubertwhich by default is 0.128 s. 2874a25439b6SCy SchubertIt can 2875a25439b6SCy Schubertbe set to any positive number in seconds. 2876a25439b6SCy SchubertIf both the forward and backward step thresholds are set to zero, step 2877a25439b6SCy Schubertadjustments will never occur. 2878a25439b6SCy SchubertNote: The kernel time discipline is 2879a25439b6SCy Schubertdisabled if 2880a25439b6SCy Schuberteach direction of step threshold are either 2881a25439b6SCy Schubertset to zero or greater than .5 second. 2882a25439b6SCy Schubert<br><dt><code>stepfwd</code> <kbd>stepfwd</kbd><dd>As for stepback, but for the forward direction. 28832b15cb3dSCy Schubert<br><dt><code>stepout</code> <kbd>stepout</kbd><dd>The argument is the stepout timeout, which by default is 900 s. 28842b15cb3dSCy SchubertIt can 28852b15cb3dSCy Schubertbe set to any positive number in seconds. 28862b15cb3dSCy SchubertIf set to zero, the stepout 28872b15cb3dSCy Schubertpulses will not be suppressed. 28882b15cb3dSCy Schubert</dl> 288909100258SXin LI <br><dt><code>writevar</code> <kbd>assocID\ name</kbd> <kbd>=</kbd> <kbd>value</kbd> <kbd>[,...]</kbd><dd>Write (create or update) the specified variables. 289009100258SXin LIIf the 289109100258SXin LI<code>assocID</code> 289209100258SXin LIis zero, the variablea re from the 289309100258SXin LIsystem variables 289409100258SXin LIname space, otherwise they are from the 289509100258SXin LIpeer variables 289609100258SXin LIname space. 289709100258SXin LIThe 289809100258SXin LI<code>assocID</code> 289909100258SXin LIis required, as the same name can occur in both name spaces. 29002b15cb3dSCy 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 29012b15cb3dSCy Schubertaddress and port number for sending messages with the specified 29022b15cb3dSCy Schubertlocal interface address. 29032b15cb3dSCy SchubertIf the port number is unspecified, a value 29042b15cb3dSCy Schubertof 18447 is used. 29052b15cb3dSCy SchubertIf the interface address is not specified, the 29062b15cb3dSCy Schubertmessage is sent with a source address of the local interface the 29072b15cb3dSCy Schubertmessage is sent through. 29082b15cb3dSCy SchubertNote that on a multihomed host the 29092b15cb3dSCy Schubertinterface used may vary from time to time with routing changes. 291009100258SXin LI<br><dt><code>ttl</code> <kbd>hop</kbd> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order. 291109100258SXin LIUp to 8 values can be specified. 291209100258SXin LIIn 291309100258SXin LI<code>manycast</code> 291409100258SXin LImode these values are used in-turn in an expanding-ring search. 291509100258SXin LIThe default is eight multiples of 32 starting at 31. 29162b15cb3dSCy Schubert 29172b15cb3dSCy Schubert <p>The trap receiver will generally log event messages and other 29182b15cb3dSCy Schubertinformation from the server in a log file. 29192b15cb3dSCy SchubertWhile such monitor 29202b15cb3dSCy Schubertprograms may also request their own trap dynamically, configuring a 29212b15cb3dSCy Schuberttrap receiver will ensure that no messages are lost when the server 29222b15cb3dSCy Schubertis started. 29232b15cb3dSCy Schubert<br><dt><code>hop</code> <kbd>...</kbd><dd>This command specifies a list of TTL values in increasing order, up to 8 29242b15cb3dSCy Schubertvalues can be specified. 29252b15cb3dSCy SchubertIn manycast mode these values are used in turn in 29262b15cb3dSCy Schubertan expanding-ring search. 29272b15cb3dSCy SchubertThe default is eight multiples of 32 starting at 29282b15cb3dSCy Schubert31. 29292b15cb3dSCy Schubert</dl> 29302b15cb3dSCy Schubert 29312b15cb3dSCy Schubert <p>This section was generated by <strong>AutoGen</strong>, 29322b15cb3dSCy Schubertusing the <code>agtexi-cmd</code> template and the option descriptions for the <code>ntp.conf</code> program. 29332b15cb3dSCy SchubertThis software is released under the NTP license, <http://ntp.org/license>. 29342b15cb3dSCy Schubert 29352b15cb3dSCy Schubert<ul class="menu"> 29362b15cb3dSCy Schubert<li><a accesskey="1" href="#ntp_002econf-Files">ntp.conf Files</a>: Files 29372b15cb3dSCy Schubert<li><a accesskey="2" href="#ntp_002econf-See-Also">ntp.conf See Also</a>: See Also 29382b15cb3dSCy Schubert<li><a accesskey="3" href="#ntp_002econf-Bugs">ntp.conf Bugs</a>: Bugs 29392b15cb3dSCy Schubert<li><a accesskey="4" href="#ntp_002econf-Notes">ntp.conf Notes</a>: Notes 29402b15cb3dSCy Schubert</ul> 29412b15cb3dSCy Schubert 29422b15cb3dSCy Schubert<div class="node"> 29432b15cb3dSCy Schubert<p><hr> 29442b15cb3dSCy Schubert<a name="ntp_002econf-Files"></a> 29452b15cb3dSCy Schubert<br> 29462b15cb3dSCy Schubert</div> 29472b15cb3dSCy Schubert 29482b15cb3dSCy Schubert<h4 class="subsection">ntp.conf Files</h4> 29492b15cb3dSCy Schubert 29502b15cb3dSCy Schubert <dl> 29512b15cb3dSCy Schubert<dt><span class="file">/etc/ntp.conf</span><dd>the default name of the configuration file 29522b15cb3dSCy Schubert<br><dt><span class="file">ntp.keys</span><dd>private MD5 keys 29532b15cb3dSCy Schubert<br><dt><span class="file">ntpkey</span><dd>RSA private key 29542b15cb3dSCy Schubert<br><dt><span class="file">ntpkey_</span><kbd>host</kbd><dd>RSA public key 29552b15cb3dSCy Schubert<br><dt><span class="file">ntp_dh</span><dd>Diffie-Hellman agreement parameters 29562b15cb3dSCy Schubert</dl> 29572b15cb3dSCy Schubert<div class="node"> 29582b15cb3dSCy Schubert<p><hr> 29592b15cb3dSCy Schubert<a name="ntp_002econf-See-Also"></a> 29602b15cb3dSCy Schubert<br> 29612b15cb3dSCy Schubert</div> 29622b15cb3dSCy Schubert 29632b15cb3dSCy Schubert<h4 class="subsection">ntp.conf See Also</h4> 29642b15cb3dSCy Schubert 29652b15cb3dSCy Schubert<p><code>ntpd(1ntpdmdoc)</code>, 29662b15cb3dSCy Schubert<code>ntpdc(1ntpdcmdoc)</code>, 29672b15cb3dSCy Schubert<code>ntpq(1ntpqmdoc)</code> 29682b15cb3dSCy Schubert 29692b15cb3dSCy Schubert <p>In addition to the manual pages provided, 29702b15cb3dSCy Schubertcomprehensive documentation is available on the world wide web 29712b15cb3dSCy Schubertat 29722b15cb3dSCy Schubert<code>http://www.ntp.org/</code>. 29732b15cb3dSCy SchubertA snapshot of this documentation is available in HTML format in 29742b15cb3dSCy Schubert<span class="file">/usr/share/doc/ntp</span>. 29752b15cb3dSCy Schubert<br> 29762b15cb3dSCy Schubert 29772b15cb3dSCy Schubert <p><br> 29782b15cb3dSCy SchubertDavid L. Mills, <em>Network Time Protocol (Version 4)</em>, RFC5905 29792b15cb3dSCy Schubert<div class="node"> 29802b15cb3dSCy Schubert<p><hr> 29812b15cb3dSCy Schubert<a name="ntp_002econf-Bugs"></a> 29822b15cb3dSCy Schubert<br> 29832b15cb3dSCy Schubert</div> 29842b15cb3dSCy Schubert 29852b15cb3dSCy Schubert<h4 class="subsection">ntp.conf Bugs</h4> 29862b15cb3dSCy Schubert 29872b15cb3dSCy Schubert<p>The syntax checking is not picky; some combinations of 29882b15cb3dSCy Schubertridiculous and even hilarious options and modes may not be 29892b15cb3dSCy Schubertdetected. 29902b15cb3dSCy Schubert 29912b15cb3dSCy Schubert <p>The 29922b15cb3dSCy Schubert<span class="file">ntpkey_</span><kbd>host</kbd> 29932b15cb3dSCy Schubertfiles are really digital 29942b15cb3dSCy Schubertcertificates. 29952b15cb3dSCy SchubertThese should be obtained via secure directory 29962b15cb3dSCy Schubertservices when they become universally available. 29972b15cb3dSCy Schubert<div class="node"> 29982b15cb3dSCy Schubert<p><hr> 29992b15cb3dSCy Schubert<a name="ntp_002econf-Notes"></a> 30002b15cb3dSCy Schubert<br> 30012b15cb3dSCy Schubert</div> 30022b15cb3dSCy Schubert 30032b15cb3dSCy Schubert<h4 class="subsection">ntp.conf Notes</h4> 30042b15cb3dSCy Schubert 30052b15cb3dSCy Schubert<p>This document was derived from FreeBSD. 30062b15cb3dSCy Schubert 30072b15cb3dSCy Schubert</body></html> 30082b15cb3dSCy Schubert 3009