from 10 to 50ms
* [Backward Incompatible] from 4.2.6p4: sntp: -l/--filelog ->
-l/--logfile, to be consistent with ntpd.
+* Documentation updates from Dave Mills.
* From 4.2.6p4: libopts/file.c fix from Bruce Korb (arg-type=file).
(4.2.7p200) 2011/08/04 Released by Harlan Stenn <stenn@ntp.org>
* Sync with 4.2.6p4-RC2.
<img src="pic/alice44.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>Our resident cryptographer; now you see him, now you don't.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->31-Oct-2010 4:18<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->03-Aug-2011 19:50<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<p><img src="pic/sx5.gif" alt="gif"></p>
<p>Figure 1. Typical Symmetric Key File</p>
</div>
-<p>Figure 1 shows a typical keys file used by the reference implementation. In the case of MD5, the key consists of 16 characters randomized over the ASCII printing codes The string can be edited later for a password, for instance as <tt>2late4Me</tt> for key ID 10. For message digest algorithms other than MD5, the key is a 20-octet random hex string.</p>
+<p>Figure 1 shows a typical keys file used by the reference implementation. In the case of MD5, the key consists of 16 characters randomized over the ASCII printing codes The string can be edited later for a password, for instance as <tt>2late4Me</tt> for key ID 10. For message digest algorithms other than MD5, the key is a 20-octet (40 hex digits) random hex string.</p>
<h4 id="windows"></h4>
<p>When <tt>ntpd</tt> is first started, it reads the key file specified by the <tt>keys</tt> command and installs the keys in the key cache. However, individual keys must be activated with the <tt>trustedkey</tt> configuration command before use. This allows, for instance, the installation of possibly several batches of keys and then activating a key remotely using <tt>ntpdc</tt>. The <tt>requestkey</tt> command selects the key ID used as the password for the <tt>ntpdc</tt> utility, while the <tt>controlkey</tt> command selects the key ID used as the password for the <tt>ntpq</tt> utility.</p>
<p>Microsoft Windows Authentication</p>
<img src="pic/alice44.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>Our resident cryptographer; now you see him, now you don't.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->02-Jan-2011 4:45<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->04-Aug-2011 1:13<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
the algorithm must be ether <tt>SHA</tt> or <tt>SHA1</tt>.</dd>
<dt><tt>host <i>name</i></tt></dt>
<dd>Specify the cryptographic media names for the host, sign and certificate files. If this option is not specified, the default name is the string returned by the Unix <tt>gethostname()</tt> routine.</dd>
- <dd><span class="style1">Note: In the latest Autokey version, this option has no affect other than to change the cryptographic media file names.</span></dd>
+ <dd><span class="style1">Note: In the latest Autokey version, this option has no effect other than to change the cryptographic media file names.</span></dd>
<dt><tt>ident <i>group</i></tt></dt>
<dd>Specify the cryptographic media names for the identity scheme files. If this option is not specified, the default name is the string returned by the Unix <tt>gethostname()</tt> routine.</dd>
- <dd><span class="style1">Note: In the latest Autokey version, this option has no affect other than to change the cryptographic media file names.</span></dd>
+ <dd><span class="style1">Note: In the latest Autokey version, this option has no effect other than to change the cryptographic media file names.</span></dd>
<dt><tt>pw <i>password</i></tt></dt>
<dd>Specifies the password to decrypt files previously encrypted by the <tt>ntp-keygen</tt> program with the <tt>-p</tt> option. If this option is not specified, the default password is the string returned by the Unix <tt>gethostname()</tt> routine. </dd>
<dt><tt>randfile <i>file</i></tt></dt>
- <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the <tt>ntp-keygen</tt> page.</dd>
+ <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>.</dd>
</dl>
</dd>
- <dt id="keys"><tt>ident <i>group</i></tt></dt>
+ <dt id="ident"><tt>ident <i>group</i></tt></dt>
<dd>Specifies the group name for ephemeral associations mobilized by broadcast and symmetric passive modes. See the <a href="autokey.html">Autokey Public-Key Authentication</a> page for further information.</dd>
<dt id="keys"><tt>keys <i>path</i></tt></dt>
- <dd>Specifies the complete directory path for the key file containing the key IDs, key types and keys used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>ntpdc</tt> when operating with symmetric key cryptography. This is the same operation as the <tt>-k </tt>command line option. Note that the directory path for Autokey cryptographic media is specified by the <tt>keysdir</tt> command.</dd>
+ <dd>Specifies the complete directory path for the key file containing the key IDs, key types and keys used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>ntpdc</tt> when operating with symmetric key cryptography. The format of the keyfile is described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>. This is the same operation as the <tt>-k</tt> command line option. Note that the directory path for Autokey cryptographic media is specified by the <tt>keysdir</tt> command.</dd>
<dt id="keysdir"><tt>keysdir <i>path</i></tt></dt>
<dd>Specifies the complete directory path for the Autokey cryptographic keys, parameters and certificates. The default is <tt>/usr/local/etc/</tt>. Note that the path for the symmetric keys file is specified by the <tt>keys</tt> command.</dd>
<dt id="requestkey"><tt>requestkey <i>keyid</i></tt></dt>
authenticating peers with symmetric key cryptography. Key IDs
used to authenticate <tt>ntpq</tt> and <tt>ntpdc</tt> operations
must be listed here and additionally be enabled with <a href="#controlkey">controlkey</a> and/or <a href="#requestkey">requestkey</a>. The authentication
- procedure for time transfer require that both the local and
+ procedure for time transfer requires that both the local and
remote NTP servers employ the same key ID and secret for this
purpose, although different keys IDs may be used with different
servers. Ranges of trusted key IDs may be specified: <tt>trustedkey (1 ... 19) 1000 (100 ... 199)</tt> enables the
<body>
<h3>Clock State Machine</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->21-Sep-2010 4:15<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->30-Jul-2011 23:36<!-- #EndDate -->
UTC</p>
<h4>Table of Contents</h4>
<ul>
- <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#intro">General Overview</a></li>
<li class="inline"><a href="#panic">Panic Threshold</a></li>
<li class="inline"><a href="#step">Step and Stepout Thresholds</a></li>
<li class="inline"><a href="#hold">Hold Timer</a></li>
<li class="inline"><a href="#state">State Transition Function</a></li>
</ul>
<hr>
-<h4 id="intro">Introduction</h4>
+<h4 id="intro">General Overview</h4>
<p>In the NTPv4 specification and reference implementation a state machine is used to manage the system clock under exceptional conditions, as when the daemon is first started or when encountering severe network congestion. This page describes the design and operation of the state machine in detail.</p>
<p> The state machine is activated upon receipt of an update by the clock discipline algorithm. its primary purpose is to determines whether the clock is slewed or stepped and how the initial time and frequency are determined using three thresholds: <em>panic</em>, <em>step</em> and <em>stepout</em>, and one timer: <em>hold</em>.</p>
<h4 id="panic">Panic Threshold</h4>
<p>Most computers today incorporate a time-of-year (TOY) chip to maintain the time when the power is off. When the computer is restarted, the chip is used to initialize the operating system time. In case there is no TOY chip or the TOY time is different from NTP time by more than the panic threshold, the daemon <tt></tt> assumes something must be terribly wrong, so exits with a message to the system operator to set the time manually. With the <tt>-g</tt> option on the command line, the daemon sets the clock to NTP time at the first update, but exits if the offset exceeds the panic threshold at subsequent updates. The panic threshold default is 1000 s, but it can be changed with the <tt>panic</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p>
<h4 id="step"> Step and Stepout Thresholds</h4>
-<p>Under ordinary conditions, the clock discipline gradually slews the clock to the correct time, so that the time is effectively continuous and never stepped forward pr backward. If, due to extreme network congestion, an offset spike exceeds the step threshold, the spike is discarded. However, if offset spikes greater than the step threshold persist for an interval more than the stepout threshold, the system clock is stepped to the correct time. In practice, the need for a step has been extremely rare and almost always the result of a hardware failure or operator error. The step threshold and stepout thresholds default to 125 ms and 300 s, respective, but can be changed with the <tt>step</tt> and <tt>stepout</tt> options of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command, respectively. If the step threshold is set to zero, the step function is entirely disabled and the clock is always slewed. The daemon sets the step threshold to 600 s using the <tt>-x</tt> option on the command line. If the <tt>-g</tt> option is used or the step threshold is set greater than 0.5 s, the precision time kernel support is disabled.</p>
+<p>Under ordinary conditions, the clock discipline gradually slews the clock to the correct time, so that the time is effectively continuous and never stepped forward or backward. If, due to extreme network congestion, an offset spike exceeds the step threshold, by default 128 ms, the spike is discarded. However, if offset spikes greater than the step threshold persist for an interval more than the stepout threshold, by default 300 s, the system clock is stepped to the correct time.</p>
+<p> In practice, the need for a step has been extremely rare and almost always the result of a hardware failure or operator error. The step threshold and stepout threshold can be changed using the <tt>step</tt> and <tt>stepout</tt> options of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command, respectively. If the step threshold is set to zero, the step function is entirely disabled and the clock is always slewed. The daemon sets the step threshold to 600 s using the <tt>-x</tt> option on the command line. If the <tt>-g</tt> option is used or the step threshold is set greater than 0.5 s, the precision time kernel support is disabled.</p>
<p>Historically, the most important application of the step function was when a leap second was inserted in the Coordinated Universal Time (UTC) timescale and the kernel precision time support was not available. This also happened with older reference clocks that indicated an impending leap second, but the radio itself did not respond until it resynchronized some minutes later. Further details are on the <a href="leap.html">Leap Second Processing</a> page.</p>
<p>In some applications the clock can never be set backward, even it accidentally set forward a week by some evil means. The issues should be carefully considered before using these options. The slew rate is fixed at 500 parts-per-million (PPM) by the Unix kernel. As a result, the clock can take 33 minutes to amortize each second the clock is outside the acceptable range. During this interval the clock will not be consistent with any other network clock and the system cannot be used for distributed applications that require correctly synchronized network time.</p>
<h4 id="hold">Hold Timer</h4>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
<title>Clock Cluster Algorithm</title>
-<link href="scripts/style.css" type="text/css" rel="stylesheet"></head>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
<body>
<em></em>
<h3>Clock Cluster Algorithm</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->05-Oct-2010 21:29<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->29-Jul-2011 12:45<!-- #EndDate -->
UTC</p>
<hr>
<p>The clock cluster algorithm processes the truechimers produced by the clock select algorithm to produce the survivors used by the mitigation algorithms to discipline the system clock. It operates in a series of rounds, where at each round the truechimer furthest from the offset centroid is pruned from the population. The rounds are continued until a specified termination condition results. This page discusses the algorithm in detail.</p>
<p><em>d<sub>i</sub></em>(<em>j</em>) = <font face="symbol">q</font>(<em>j</em>) - <font face="symbol"> q</font>(<em>i</em>),</p>
</div>
<p> where<font face="symbol"> q</font>(<em>i</em>) is the peer offset of the <em>i</em>th entry and <font face="symbol">q</font>(<em>j</em>) is the peer offset of the <em>j</em>th entry, both produced by the clock filter algorithm. Then, the select jitter <font face="symbol">j</font><sub>S</sub>(<em>i</em>) of the <em>i</em>th entry is the root distance of the <em>i</em>th entry times the RMS sum of <em>d<sub>i</sub></em>(<em>j</em>)<em> </em>as <em>j</em> ranges from 1 to <em>n</em>. For the purpose of notation in the example to follow, let <font face="symbol">j</font><sub>R</sub>(<em>i</em>) be the peer jitter computed by the clock filter algorithm for the <em>i</em>th entry. In general, the <em>expected error</em> statistic for the <em>i</em>th entry is the RMS sum of these two components, but that is not needed by the clock cluster algorithm.</p>
-<p>The object at each round is to prune the entry with the largest select jitter until the termination condition is met. Note that the select jitter must be recomputed at each round, but the peer jitter does not change. At each round the remaining entries on the list represent the survivors of that round. While the number of entries on the list is not limited, the list is always pruned to the <em>maxclock threshold</em>. It has default 10, but can be set by the <tt>maxclock</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. This threshold is useful to limit the number of survivors when automatic server discovery schemes are in use.</p>
+<p>The object at each round is to prune the entry with the largest select jitter until the termination condition is met. Note that the select jitter must be recomputed at each round, but the peer jitter does not change. At each round the remaining entries on the list represent the survivors of that round. If the survivor to be pruned is preempt able and the number of survivors is greater than the <em>maxclock threshold</em>, the association is demobilized. This is useful in the automatic server discovery schemes described on the <a href="assoc.html">Association Management</a> page. The maxclock threshold default is 10, but it can be changed using the <tt>maxclock</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. Further pruning is subject to the following termination conditions, but no associations will be demobilized</p>
<p>The termination condition has two parts. First, if the number of candidates is not greater than the<em> </em><em>minclock threshold</em> set by the <tt>minclock</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, the pruning process terminates. The<tt> minclock</tt> default is 3, but can be changed to fit special conditions, as described on the <a href="prefer.html">Mitigation Rules and the prefer Keyword</a> page.</p>
<div align="center"><img src="pic/flt7.gif" alt="gif">
<p>Figure 1. Cluster Algorithm</p>
</div>
-<p>The second termination condition is more intricate. Figure 1 shows a round where a candidate of (a) is pruned to yield the candidates of (b). Let <font face="symbol">j</font><sub><em>max</em></sub> be the maximum select jitter and <font face="symbol">j</font><sub><em>min</em></sub> be the minimum peer jitter over all entries on the list. In (a), candidate 1 has the highest select jitter, so <font face="symbol">j</font><sub><em>max</em></sub> = <font face="symbol"> j</font><sub>S</sub>(1). Candidate 4 has the lowest peer jitter, so <font face="symbol">j</font><sub><em>min</em></sub> = <font face="symbol">j</font><sub>R</sub>(4). Since <font face="symbol">j</font><sub><em>max</em></sub> > <font face="symbol">j</font><sub><em>min</em></sub>, select jitter dominates total jitter,<em> so </em>the algorithm prunes candidate 1. In (b), <font face="symbol">j</font><sub><em>max</em></sub> = <font face="symbol">j</font><sub>S</sub>(3) and <font face="symbol">j</font><sub><em>min </em></sub>=<font face="symbol"> j</font><sub>R</sub>(4). Since <font face="symbol">j</font><sub><em>max</em></sub> < <font face="symbol">j</font><sub><em>min</em></sub>, pruning additional candidates will not significantly reduce total jitter. So, the algorithm terminates with candidates 2, 3 and 4 as survivors.</p>
+<p>The second termination condition is more intricate. Figure 1 shows a round where a candidate of (a) is pruned to yield the candidates of (b). Let <font face="symbol">j</font><sub><em>max</em></sub> be the maximum select jitter and <font face="symbol">j</font><sub><em>min</em></sub> be the minimum peer jitter over all entries on the list. In (a), candidate 1 has the highest select jitter, so <font face="symbol">j</font><sub><em>max</em></sub> = <font face="symbol"> j</font><sub>S</sub>(1). Candidate 4 has the lowest peer jitter, so <font face="symbol">j</font><sub><em>min</em></sub> = <font face="symbol">j</font><sub>R</sub>(4). Since <font face="symbol">j</font><sub><em>max</em></sub> > <font face="symbol">j</font><sub><em>min</em></sub>, select jitter dominates total jitter,<em> so </em>the algorithm prunes candidate 1. In (b), <font face="symbol">j</font><sub><em>max</em></sub> = <font face="symbol">j</font><sub>S</sub>(3) and <font face="symbol">j</font><sub><em>min </em></sub>=<font face="symbol"> j</font><sub>R</sub>(4). Since <font face="symbol">j</font><sub><em>max</em></sub> < <font face="symbol">j</font><sub><em>min</em></sub>, pruning additional candidates will not significantly reduce total jitter. So, the algorithm terminates with candidates 2, 3 and 4 as survivors.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
<body>
<h3>Copyright Notice</h3>
<img src="pic/sheepb.jpg" alt="jpg" align="left"> "Clone me," says Dolly sheepishly.
-<p>Last update: 03-Sep-2010 21:20 UTC<br clear="left">
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Aug-2011 1:37<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
</p>
<hr>
<p>The following copyright notice applies to all files collectively called the Network Time Protocol Version 4 Distribution. Unless specifically declared otherwise in an individual file, this notice applies as if the text was explicitly included in the file.</p>
<pre>
***********************************************************************
* *
-* Copyright (c) David L. Mills 1992-2010 *
+* Copyright (c) University of Delaware 1992-2011 *
* *
* Permission to use, copy, modify, and distribute this software and *
* its documentation for any purpose with or without fee is hereby *
<li><a href="mailto:%20Jean-Francois.Boudreault@viagenie.qc.ca">Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca></a> IPv6 support</li>
<li><a href="mailto:%20reg@dwf.com">Reg Clemens <reg@dwf.com></a> Oncore driver (Current maintainer)</li>
<li><a href="mailto:%20clift@ml.csiro.au">Steve Clift <clift@ml.csiro.au></a> OMEGA clock driver</li>
- <li><a href="mailto:casey@csc.co.za">Casey Crellin <casey@csc.co.za></a> vxWorks (Tornado) port and help with target configuration</li>
+ <li><a href="mailto:%20casey@csc.co.za">Casey Crellin <casey@csc.co.za></a> vxWorks (Tornado) port and help with target configuration</li>
<li><a href="mailto:%20Sven_Dietrich@trimble.COM">Sven Dietrich <sven_dietrich@trimble.com></a> Palisade reference clock driver, NT adj. residuals, integrated Greg's Winnt port.</li>
<li><a href="mailto:%20dundas@salt.jpl.nasa.gov">John A. Dundas III <dundas@salt.jpl.nasa.gov></a> Apple A/UX port</li>
<li><a href="mailto:%20duwe@immd4.informatik.uni-erlangen.de">Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de></a> Linux port</li>
<li><a href="mailto:%20iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port</li>
<li><a href="mailto:%20jagubox.gsfc.nasa.gov">Jim Jagielski <jim@jagubox.gsfc.nasa.gov></a> A/UX port</li>
<li><a href="mailto:%20jbj@chatham.usdesign.com">Jeff Johnson <jbj@chatham.usdesign.com></a> massive prototyping overhaul</li>
- <li><a href="mailto:Hans.Lambermont@nl.origin-it.com">Hans Lambermont <Hans.Lambermont@nl.origin-it.com></a> or <a href="mailto:H.Lambermont@chello.nl"><H.Lambermont@chello.nl></a> ntpsweep</li>
+ <li><a href="mailto:
%20Hans.Lambermont@nl.origin-it.com">Hans Lambermont <Hans.Lambermont@nl.origin-it.com></a> or <a href="mailto:H.Lambermont@chello.nl"><H.Lambermont@chello.nl></a> ntpsweep</li>
<li><a href="mailto:%20phk@FreeBSD.ORG">Poul-Henning Kamp <phk@FreeBSD.ORG></a> Oncore driver (Original author)</li>
<li><a href="http://www4.informatik.uni-erlangen.de/%7ekardel">Frank Kardel</a> <a href="mailto:%20kardel%20%28at%29%20ntp%20%28dot%29%20org"><kardel (at) ntp (dot) org></a> PARSE <GENERIC> (driver 14 reference clocks), STREAMS modules for PARSE, support scripts, syslog cleanup, dynamic interface handling</li>
+ <li><a href="mailto:kuehn@ntp.org">Johannes Maximilian Kuehn <kuehn@ntp.org></a> Rewrote <tt>sntp</tt> to comply with NTPv4 specification, <tt>ntpq saveconfig</tt></li>
<li><a href="mailto:%20jones@hermes.chpc.utexas.edu">William L. Jones <jones@hermes.chpc.utexas.edu></a> RS/6000 AIX modifications, HPUX modifications</li>
<li><a href="mailto:%20dkatz@cisco.com">Dave Katz <dkatz@cisco.com></a> RS/6000 AIX port</li>
<li><a href="mailto:%20leres@ee.lbl.gov">Craig Leres <leres@ee.lbl.gov></a> 4.4BSD port, ppsclock, Magnavox GPS clock driver</li>
<body>
<h3>Clock Discipline Algorithm</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->20-May-2011 2:25<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->30-Jul-2011 20:07<!-- #EndDate -->
UTC</p>
<h4>Table of Contents</h4>
<ul>
- <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#intro">General Overview</a></li>
<li class="inline"><a href="#pll">Phase-Lock Loop Operations</a></li>
<li class="inline"><a href="#loop">Loop Dynamics</a></li>
</ul>
<hr>
-<h4 id="intro">Introduction</h4>
+<h4 id="intro">General Overview</h4>
<p>At the heart of the NTP specification and reference implementation is the clock discipline algorithm, which is best described as an adaptive parameter, hybrid phase/frequency-lock feedback loop. It is an intricately crafted algorithm that automatically adapts for optimum performance while minimizing network overhead. Operation is in two modes, phase-lock loop (PLL), which is used at poll intervals below the Allan intercept, by default 2048 s, and frequency-lock loop (FLL), which is used above that.</p>
<div align="center"> <img src="pic/discipline.gif" alt="gif">
<p>Figure 1. Clock Discipline Algorithm</p>
</div>
<h4 id="pll">Clock Discipline Operations</h4>
<p>A block diagram of the clock discipline is shown in Figure 1. The timestamp of a reference clock or remote server is compared with the timestamp of the system clock, represented as a variable frequency oscillator (VFO), to produce a raw offset sample <em>V<sub>d</sub></em>. Offset samples are processed by the clock filter to produce a filtered update <em>V<sub>s</sub></em>. The loop filter implements a type-2 proportional-integrator controller (PIC). The PIC can minimize errors in both time and frequency using predictors <em>x</em> and <em>y</em>, respectively. The clock adjust process samples these predictors once each second for the daemon discipline or once each tick interrupt for the kernel discipline to produce the system clock update <em>V<sub>c</sub></em>.</p>
-<p>In PLL mode the frequency predictor is an integral of the offset over past updates, while the phase predictor is the offset amortized over time in order to avoid setting the clock backward. In FLL mode the phase predictor is not used, while the frequency predictor uses the NIST <em>lockclock</em> algorithm. In this algorithm, the frequency predictor is computed as a fraction of the current offset divided by the time since the last update in order to minimize the offset at the next update.</p>
-<p>Its response in PLL mode is determined by the <em>time constant</em>, which results in a "stiffness" depending on the jitter of the available sources and the wander of the system clock oscillator. The scaled time constant is also used as the poll interval by the poll processes. However, in NTP symmetric mode, each peer manages its own poll interval and the two might not be the same. In such cases either peer uses the minimum of its own poll interval and that of the other peer, which is included in the NTP packet header.</p>
+<p>In PLL mode the frequency predictor is an integral of the offset over past updates, while the phase predictor is the offset amortized over time in order to avoid setting the clock backward. In FLL mode the phase predictor is not used, while the frequency predictor is similar to the NIST <em>lockclock</em> algorithm. In this algorithm, the frequency predictor is computed as a fraction of the current offset divided by the time since the last update in order to minimize the offset at the next update.</p>
+<p>The discipline response in PLL mode is determined by the <em>time constant</em>, which results in a "stiffness" depending on the jitter of the available sources and the wander of the system clock oscillator. The scaled time constant is also used as the poll interval by the poll processes. However, in NTP symmetric mode, each peer manages its own poll interval and the two might not be the same. In such cases either peer uses the minimum of its own poll interval and that of the other peer, which is included in the NTP packet header.</p>
<h4 id="loop">Loop Dynamics</h4>
<p> It is necessary to verify the PLL is stable and satisfies the Nyquist criterion, which requires that the sampling rate be at least twice the bandwidth. In this case the bandwidth can be approximated by the reciprocal of the time constant. At a poll exponent of 6, the poll interval is 64 s and the time constant 2048 s. The Nyquist criterion requires the sample interval to be not more than half the time constant or 1024 s. The clock filter guarantees at least one sample in eight poll intervals, so the sample interval is not more than 512 s. This would be described as oversampling by a factor of two. Finally, the PLL parameters have been chosen for a damping factor of 2, which results in a much faster risetime than with critical damping, but results in modest overshoot of 6 percent.</p>
-<p> It is important to understand how the dynamics of the PLL are affected by the poll interval. At the default poll interval of 64 s and a offset step change of 100 ms, the time response crosses zero in about 50 min and overshoots about 6 ms, as per design. Ordinarily, a step correction would causes a temporary frequency surge of about 5 PPM, which is slowly dissipates over a few hours. The result would be that the overshoot slowly subsides over that interval.</p>
+<p> It is important to understand how the dynamics of the PLL are affected by the time constant and poll interval. At the default poll interval of 64 s and a step offset change of 100 ms, the time response crosses zero in about 50 min and overshoots about 6 ms, as per design. Ordinarily, a step correction would causes a temporary frequency surge of about 5 PPM, which along with the overshoot slowly dissipates over a few hours.</p>
<p>However, the clock state machine used with the discipline algorithm avoids this transient at startup. It does this using a previously saved frequency file, if present, or by measuring the oscillator frequency, if not. It then quickly amortizes the residual offset at startup without affecting the oscillator frequency. In this way the offset error is less than 0.5 ms within 5 min if the file is present and within 10 min if not. See the <a href="clock.html">Clock State Machine</a> page for further details.</p>
<p>Since the PLL is linear, the response with different offset step amplitudes and poll intervals has the same characteristic shape, but scaled differently in amplitude and time. The response scales exactly with step amplitude, so that the response to a 10-ms step has the same shape as at 64 s, but with amplitude compressed by one-tenth. The response scales exactly with poll interval, so that response at a poll interval of 8 s has the same shape as at 64 s, but with time compressed by one-eighth.</p>
<p>In the NTP specification and reference implementation, poll intervals are expressed as exponents of 2. The clock discipline time constant is proportional to the poll interval by a factor of 32. Thus, a poll exponent of 6 corresponds to a poll interval of 64 s and a time constant of 2048 s. A change in the poll interval changes the time constant by a corresponding amount.</p>
<body>
<h3>Clock Filter Algorithm</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->27-Sep-2010 18:00<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->29-Jul-2011 12:54<!-- #EndDate -->
UTC</p>
<hr>
<p>The clock filter algorithm processes the offset and delay samples produced by the on-wire protocol for each peer process separately. It uses a sliding window of eight samples and picks out the sample with the least expected error. This page describes the algorithm design principles along with an example of typical performance..</p>
<p>In the clock filter algorithm the offset and delay samples from the on-wire protocol are inserted as the youngest stage of an eight-stage shift register, thus discarding the oldest stage. Each time an NTP packet is received from a source, a dispersion sample is initialized as the sum of the precisions of the server and client. Precision is defined by the latency to read the system clock and various from 1000 ns to 100 ns in modern machines. The dispersion ample is inserted in the shift register along with the offset and delay samples. Subsequently, the dispersion sample in each stage is increased at a fixed rate of 15 <font face="symbol">m</font>s/s, representing the worst case error due to skew between the server and client clock frequencies's.</p>
<p>In each peer process the clock filter algorithm selects the stage with the smallest delay, which generally represents the most accurate data, and it and the associated offset sample become the peer variables of the same name. The peer jitter statistic is computed as the root-mean-square (RMS) differences between the offset samples and the offset of the selected stage.</p>
<p> The peer dispersion statistic is determined as a weighted sum of the dispersion samples in the shift register. Initially, the dispersion of all shift register stages is set to a large number "infinity" equal to 16 s. The weight factor for each stage, starting from the youngest numbered <em>i</em> = 1, is 2<sup>-<em>i</em></sup>, which means the peer dispersion is approximately 16. As samples enter the register, the peer dispersion drops from 16 to 8, 4, 2... and so forth. In practice, the dispersion falls below the select threshold of 1.5 s in about four updates. This gives some time for meaningful comparison between sources, if more than one are available. The dispersion continues to grow at the same rate as the sample dispersion. As explained elsewhere, when a source becomes unreachable, the poll process inserts a dummy infinity sample in the shift register for each poll sent. After eight polls, the register returns to its original state.</p>
-<div align="center">
<img src="pic/flt1.gif" alt="gif"> <img src="pic/flt2.gif" alt="gif">
+<div align="center"><img src="pic/flt1.gif" alt="gif"> <img src="pic/flt2.gif" alt="gif">
<p>Figure 2. Raw (left) and Filtered (right) Offsets</p>
</div>
<p>Figure 2 shows the performance of the algorithm using offsets for a typical Internet path over a 24-hr period. The graph on the left shows the raw offsets produced by the on-wired protocol, while the figure on the right shows the filtered offsets produced by the algorithm. If we consider the series formed as the absolute value of the offset samples, the mean error is defined as the mean of this series. Thus, the mean error of the raw samples is 0.724 ms, while the mean error of the filtered series is 0.192 ms. Radio engineers would interpret this as a processing gain of 11.5 dB.</p>
<img src="pic/boom3.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
<p>We have three, now looking for more.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->12-May-2011 13:17<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->04-Aug-2011 1:27<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<dd>Specify the <i><tt>threshold</tt></i> in PPM to write the frequency file, with default 0.1 PPM. The frequency file is inspected each hour. If the difference between the current frequency and the last value written exceeds the threshold, the file is written and the <tt><em>threshold</em></tt> becomes the new threshold value. If the threshold is not exceeded, it is reduced by half. This is intended to reduce the frequency of unnecessary file writes for embedded systems with nonvolatile memory.</dd>
<dt id="phone"><tt>phone <i>dial</i> ...</tt></dt>
<dd>This command is used in conjunction with the ACTS modem driver (type 18). The arguments consist of a maximum of 10 telephone numbers used to dial USNO, NIST or European time services. The Hayes command ATDT is normally prepended to the number, which can contain other modem control codes as well.</dd>
+ <dt id="reset"><tt>reset [allpeers] [auth] [ctl] [io] [mem] [sys] [timer]</tt></dt>
+ <dd>Reset one or more groups of counters maintained by ntpd and exposed by <tt>ntpq</tt> and <tt>ntpdc</tt>.</dd>
<dt id="saveconfigdir"><tt>saveconfigdir <i>directory_path</i></tt></dt>
<dd>Specify the directory in which to write configuration snapshots requested with <tt>ntpq</tt>'s <a href="ntpq.html#saveconfig">saveconfig</a> command. If <tt>saveconfigdir</tt> does not appear in the configuration file, saveconfig requests are rejected by ntpd.</dd>
<dt id="setvar"><tt>setvar <i>variable</i> [default]</tt></dt>
<body>
<h3>Orphan Mode</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->12-May-2011 13:18<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->01-Aug-2011 17:56<!-- #EndDate -->
UTC</p>
<hr>
<p>Sometimes an NTP subnet becomes isolated from all UTC sources such as local reference clocks or Internet time servers. In such cases it may be necessary that the subnet servers and clients remain synchronized to a common timescale, not necessarily the UTC timescale. Previously, this function was provided by the local clock driver to simulate a UTC source. A server with this driver could be used to synchronize other hosts in the subnet directly or indirectly.</p>
<p>There are many disadvantages using the local clock driver, primarily that the subnet is vulnerable to single-point failures and multiple server redundancy is not possible. Orphan mode is intended to replace the local clock driver. It provides a single simulated UTC source with multiple servers and provides seamless switching as servers fail and recover.</p>
<p>A common configuration for private networks includes one or more core servers operating at the lowest stratum. Good practice is to configure each of these servers as backup for the others using symmetric or broadcast modes. As long as at least one core server can reach a UTC source, the entire subnet can synchronize to it.</p>
-<p>If no UTC sources are available to any core server, one of them can provide a simulated UTC source for all other hosts in the subnet. However, only one core server can simulate the UTC source and all direct dependents, called orphan children, must select the same one, called the orphan parent.</p>
-<p>A host is enabled for orphan mode using the <tt>tos orphan <i>stratum</i></tt> command, where <tt><i>stratum</i></tt> is some stratum less than 16 and greater than any anticipated stratum that might occur with configured Internet time servers. However, sufficient headroom should remain so every subnet host dependent on the orphan children has stratum less than 16. Where no associations for other servers or reference clocks are configured, the orphan stratum can be set to 1. These are the same considerations that guide the local clock driver stratum selection.</p>
-<p>In order to avoid premature enabling orphan mode, a holdoff delay occurs when the daemon is first started and when all sources have been lost after that. The delay is intended to allow time for other sources to become reachable and selected. Only when the delay has expired with no sources will orphan parent mode be enabled. By default the delay is 300 s (five minutes), but this can be changed using the <tt>tos orphanwait <em>delay</em></tt> command.</p>
+<p>If no UTC sources are available to any core server, one of them can provide a simulated UTC source for all other hosts in the subnet. However, only one core server can simulate the UTC source and all direct dependents, called orphan children, must select the same server, called the orphan parent.</p>
+<p>Hosts sharing the same common subnet, including potential orphan parents and potential orphan children, can be enabled for orphan mode using the <tt>orphan <em>stratum</em></tt> option of the <a href="miscopt.html#tos"> <tt>tos command</tt></a>, where <tt><i>stratum</i></tt> is some stratum less than 16 and greater than any anticipated stratum that might occur with configured Internet time servers. However, sufficient headroom should remain so every subnet host dependent on the orphan children has stratum less than 16. Where no associations for other servers or reference clocks are configured, the orphan stratum can be set to 1. These are the same considerations that guide the local clock driver stratum selection.</p>
+<p>In order to avoid premature enabling orphan mode, a holdoff delay occurs when the daemon is first started and when all sources have been lost after that. The delay is intended to allow time for other sources to become reachable and selectable. Only when the delay has expired with no sources will orphan mode be enabled. By default the delay is 300 s (five minutes), but this can be changed using the <tt> orphanwait</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p>
<p>A orphan parent with no sources shows reference ID <font face="Courier New, Courier, Monaco, monospace">LOOP</font> if
operating at stratum 1 and 127.0.0.1 (IPv4 loopback address) otherwise.
While ordinary NTP clients use a selection metric based on delay
and dispersion, orphan children use a metric computed from the IP
address of each core server. Each orphan child chooses the orphan
- parent as the root server with the smallest metric.</p>
+ parent as the core server with the smallest metric.</p>
<p>For orphan mode to work well, each core server with available sources should operate at the same stratum. All core servers and orphan children should include the same <font face="Courier New, Courier, Monaco, monospace">tos</font> command in the configuration file. Each orphan child should include in the configuration file all root servers.</p>
-<div align="center"> <img src="pic/peer.gif" alt="gif"> </div>
-<p>For example, consider the peer network configuration above, where two or more campus primary or secondary (stratum 2) servers are configured with reference clocks or public Internet primary servers and with each other using symmetric modes. With this configuration a server that loses all sources continues to discipline the system clock using the other servers as backup. Only the core servers and orphan children need to be enabled for orphan mode.</p>
-<div align="center"> <img src="pic/broad.gif" alt="gif"> </div>
-<p>For broadcast networks each core server is configured in both broadcast server and broadcast client modes as shown above. Orphan children operate as broadcast clients of all core servers. As in peer networks, the core servers back up each other and only they and the orphan children need to be enabled for orphan mode.</p>
-<p>In normal operation subnet hosts operate below stratum 5, so the subnet is automatically configured as described in the NTP specification. If all UTC sources are lost, all core servers become orphans and the orphan children will select the same root server to become the orphan parent.</p>
+<div align="center"> <img src="pic/peer.gif" alt="gif">
+ <p>Figure 1. Orphan Peer Configuration</p>
+</div>
+<p>For example, consider the peer network configuration in Figure 1, where two or more campus primary or secondary (stratum 2) servers are configured with reference clocks or public Internet primary servers and with each other using symmetric modes. With this configuration a server that loses all sources continues to discipline the system clock using the other servers as backup. Only the core servers and orphan children need to be enabled for orphan mode.</p>
+<div align="center"> <img src="pic/broad.gif" alt="gif">
+ <p>Figure 2. Orphan Broadcast Configuration</p>
+</div>
+<p>For broadcast networks each core server is configured in both broadcast server and broadcast client modes as shown in Figure 2. Orphan children operate as broadcast clients of all core servers. As in peer networks, the core servers back up each other and only they and the orphan children need to be enabled for orphan mode.</p>
+<p>In normal operation subnet hosts operate below stratum 5, so the subnet is automatically configured as described in the NTP specification. If all UTC sources are lost, all core servers become orphans and the orphan children will select the same core server to become the orphan parent.</p>
<hr>
-<p><script type="text/javascript" language="javascript" src="scripts/footer.txt"></script></p>
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</p>
</body>
</html>
<body>
<h3>Poll Program</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->12-Oct-2010 3:19<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->31-Jul-2011 15:34<!-- #EndDate -->
UTC</p>
<hr>
-<p>Each poll process sends NTP packets at intervals determined by the poll program. The program is designed to provide a sufficient update rate for thc clock discipline algorithm
while minimizing network overhead. The program is designed to operate over a poll exponent range between 3 (8 s) and 17 (36 hr). The minimum and maximum within this range can be set using the <tt>minpoll</tt> and <tt>maxpoll</tt> options of the <a href="confopt.html#option"><tt>server</tt></a> command, with default 6 (64 s) and 10 (1024 s), respectively.</p>
+<p>Each poll process sends NTP packets at intervals determined by the poll program. The program is designed to provide a sufficient update rate for thc clock discipline algorithm
, while minimizing network overhead. The program is designed to operate over a poll exponent range between 3 (8 s) and 17 (36 hr). The minimum and maximum poll exponent within this range can be set using the <tt>minpoll</tt> and <tt>maxpoll</tt> options of the <a href="confopt.html#option"><tt>server</tt></a> command, with default 6 (64 s) and 10 (1024 s), respectively.</p>
<p> The poll interval is managed by a heuristic algorithm developed over several years of experimentation. It depends on an exponentially weighted average of clock offset differences, called <em>clock jitter</em>, and a jiggle counter, which is initially set to zero. When a clock update is received and the offset exceeds the clock jitter by a factor of 4, the jiggle counter is increased by the poll exponent; otherwise, it is decreased by twice the poll exponent. If the jiggle counter is greater than an arbitrary threshold of 30, it is reset to 0 and the the poll exponent is increased by 1. If the jiggle counter is less than -30, it is set to 0 and the poll exponent decreased by 1. In effect, the algorithm has a relatively slow reaction to good news, but a relatively fast reaction to bad news.</p>
<p>As an option of the <a href="confopt.html#option"><tt>server</tt></a> command, instead of a single packet, the poll program can send a burst of six packets at 2-s intervals. This is designed to reduce the time to synchronize the clock at initial startup (<tt>iburst</tt>) and/or to reduce the phase noise at the longer poll intervals (<tt>burst</tt>). The <tt>iburst</tt> option is effective only when the server is unreachable, while the <tt>burst</tt> option is effective only when the server is reachable.</p>
<p>For the <tt>iburst</tt> option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the <tt>burst</tt> option, the number of packets in the burst is determined by the difference between the current poll exponent and the minimum poll exponent as a power of 2. For instance, with the default minimum poll exponent of 6 (64 s), only a single packet is sent for every poll, while the full number of eight packets is sent at poll exponents of 9 (512 s) or more. This insures that the average headway will never exceed the minimum headway.</p>
<img src="pic/alice11.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html"> from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>Listen carefully to what I say; it is very complicated.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->29-Oct-2010 19:45<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->30-Jul-2011 19:45<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
<h4>Table of Contents</h4>
<ul>
- <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#intro">General Overview</a></li>
<li class="inline"><a href="#combine">Combine Algorithm</a></li>
<li class="inline"><a href="#clockhop">Anti-Clockhop Algorithm</a></li>
<li class="inline"><a href="#peer">Peer Classification</a></li>
<li class="inline"><a href="#mins">The <tt>minsane</tt> Option</a></li>
</ul>
<hr>
-<h4 id="intro">Introduction</h4>
+<h4 id="intro">General Overview</h4>
<p>This page summarizes the criteria for choosing from among a number of potential sources suitable contributors to the clock discipline algorithm. The criteria are very meticulous, since they have to handle many different scenarios that may be optimized for peculiar circumstances, including some scenarios designed to support planetary and deep space missions.</p>
-<p>Recall the suite of NTP data acquisition and grooming algorithms as these algorithms proceed in five phases. Phase one discovers the available sources and mobilizes an association for each candidate found. These candidates can result from explicit configuration, broadcast discovery or the pool and manycast autonomous configuration schemes. Phase two grooms the selectable candidates excluding those sources showing one or more of the following errors</p>
+<p>Recall the suite of NTP data acquisition and grooming algorithms as these algorithms proceed in five phases. Phase one discovers the available sources and mobilizes an association for each candidate found. These candidates can result from explicit configuration, broadcast discovery or the pool and manycast autonomous configuration schemes.</p>
+<p> Phase two grooms the selectable candidates excluding those sources showing one or more of the following errors</p>
<ol>
- <li>A stratum error occurs if (1) the source had never been synchronized or (2) the stratum of the source is below the <tt>floor</tt> option or not below the <tt>ceiling</tt> option specified by the <tt>tos</tt> command. The default value for these options are 0 and 16, respectively.</li>
- <li>A distance error occurs for a remote source if the root distance is not below the distance threshold <tt>maxdist</tt> option of the <tt>tos</tt> command. The default value for this option is 1.5 s for networks including only the Earth, but this should be increased to 2.5 s for networks including the Moon.</li>
+ <li>A stratum error occurs if (1) the source had never been synchronized or (2) the stratum of the source is below the <tt>floor</tt> option or not below the <tt>ceiling</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default value for these options are 0 and 16, respectively.</li>
+ <li>A distance error occurs for a remote source if the root distance is not below the distance threshold <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default value for this option is 1.5 s for networks including only the Earth, but this should be increased to 2.5 s for networks including the Moon.</li>
<li>A loop error occurs if the source is synchronized to the client or if the source is synchronized to the same source as the client.</li>
<li>An unreachable error occurs if the source is unreachable or if the <tt>server</tt> or <tt>peer</tt> command for the source includes the <tt>noselect</tt> option.</li>
</ol>
-<p>Phase three uses an intersection algorithm to select the truechimers from
- among the candidates, leaving behind the falsetickers. A server or peer configured
- with the <tt>true</tt> option is ipso facto a truechimer independent of this
- algorithm. Phase four uses a clustering algorithm to cast off statistical outliers
- from the truechimers until a set of survivors not less than <tt>minclock</tt> remain. The <tt>minclock</tt> has default 3, but can be changed with the <tt>minclock</tt> option of the <tt>tos</tt> command.</p>
-<p> Phase five uses a set of algorithms and mitigation rules to rank the survivors to produce combined statistics used to discipline the clock, as well as to select from among the survivors
- a system peer from which a set of system statistics can be inherited and passed
- along to a dependent client population. The algorithms and rules are the main topic of this page. The clock offset developed from these
- algorithms can discipline the system clock either using the <tt>ntpd</tt> clock
- discipline algorithm or enable the kernel to discipline the system clock directly,
- as described on the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page.
- Phase five is the topic of this page.</p>
+<p>Phase three uses the <a href="select.html">select algorithm</a> to determine the truechimers from among the candidates, leaving behind the falsetickers. A server or peer configured with the <tt>true</tt> option is declared a truechimer independent of this algorithm. Phase four uses the <a href="cluster.html">cluster algorithm</a> to cast off statistical outliers from the truechimers until a set of survivors not less than <tt>minclock</tt> remain. The <tt>minclock</tt> has default 3, but can be changed with the <tt>minclock</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p>
+<p> Phase five uses a set of algorithms and mitigation rules to rank the survivors to produce combined statistics used to discipline the clock, as well as to select from among the survivors a system peer from which a set of system statistics can be inherited and passed along to a dependent client population. The algorithms and rules are the main topic of this page. The clock offset developed from these algorithms can discipline the system clock either using the <a href="discipline.html"><tt>ntpd</tt> clock discipline algorithm</a> or enable the kernel to discipline the system clock directly, as described on the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. Phase five is the topic of this page.</p>
<h4 id="combine">Combine Algorithm</h4>
<p>The cluster algorithm produces a list of survivors ranked by increasing synchronization distance. The combine algorithm uses this list to produce a weighted average of both offset and jitter. Absent other considerations discussed later, the combined offset is used to discipline the clock, while the combined jitter is combined with other components to produce the system jitter statistic inherited by dependent clients.</p>
<p>The combine algorithm uses a weight factor for each survivor computed as the select threshold minus the synchronization distance. Since the select algorithm rejects candidates with synchronization distance greater than the select threshold, the weight factor is always positive. The system jitter is calculated as the RMS weighted differences between the offset of each survivor and the offset of the first candidate on the survivor list. </p>
<p>The behavior of the various algorithms and mitigation rules involved depends on how the various synchronization sources are classified. This depends on whether the source is local or remote and if local the type of source. The following classes are defined:</p>
<ol>
<li>An association configured for a remote server or peer is classified simply as a <i>server</i>. All other associations are classified as a <i>device driver</i> of one kind or another. In general, one or more sources of either or both types will be configured in each installation.</li>
- <li>If all sources have been lost and the orphan stratum has been specified by the <tt>orphan</tt> option of the <tt>tos</tt> command, a pseudo-source called the <i>orphan parent</i> is created with offset and jitter both zero. Dependent orphan children will see the orphan parent as if synchronized to a server at the orphan stratum.If the only survivor is the orphan parent, it becomes the system peer and its clock offset and jitter are inherited by the corresponding system variables. Note that by design all the orphan children having the same set of orphan parents will select the same parent.</li>
+ <li>If all sources have been lost and the orphan stratum has been specified by the <tt>orphan</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, a pseudo-source called the <i>orphan parent</i> is created with offset and jitter both zero. Dependent orphan children will see the orphan parent as if synchronized to a server at the orphan stratum.If the only survivor is the orphan parent, it becomes the system peer and its clock offset and jitter are inherited by the corresponding system variables. Note that by design all the orphan children having the same set of orphan parents will select the same parent.</li>
<li>When a device driver has been configured for pulse-per-second (PPS) signals and PPS signals are being received, it is designated the <i>PPS driver.</i> Note that the Pulse-per-Second driver (type 22) is often used as a PPS driver, but any driver can be operated as a PPS driver as well. The PPS driver provides precision clock discipline only within ±0.4 s, so is always associated with another source or sources that provide the seconds numbering function.</li>
- <li>When the Undisciplined Local Clock driver (type 1) is configured, it is designated the <i>local driver</i>. This driver is used either as a backup source (stratum greater than zero) should all sources fail, or as the primary source (stratum zero) in cases where the kernel time is disciplined by some other means of synchronization, such as the NIST <tt>lockclock</tt> scheme, or another synchronization protocol such as the Digital Time Synchronization Service (DTSS).</li>
+ <li>When the Undisciplined Local Clock driver (type 1) is configured, it is designated the <i>local driver</i>. This driver is used either as a backup source (stratum greater than zero) should all sources fail, or as the primary source (stratum zero) in cases where the kernel time is disciplined by some other means of synchronization, such as the NIST <tt>lockclock</tt> scheme, or another synchronization protocol such as the IEEE 1588 Precision Time Protocol (PTP) or Digital Time Synchronization Service (DTSS).</li>
<li>When the Automated Computer Time Service driver (type 18) is configured, it is designated the <i>modem driver</i>. This is used either as a backup source, should all other sources fail, or as the (only) primary source.</li>
</ol>
<h4 id="prefer">The <tt>prefer</tt> Peer</h4>
-<p>The mitigation rules are designed to provide an intelligent selection of the system peer from among the survivors of different types. When used with the <tt>server</tt> or <tt>peer</tt> commands, the <tt>prefer</tt> option designates one or more survivors as preferred over all others. While the rules do not forbid it, it is usually not useful to designate more than one source as preferred; however, if more than one source is so designated, they are used in the order specified in the configuration file; that is, if the first one becomes unselectable, the second one is considered and so forth. This order of priority is also applicable to multiple PPS drivers, multiple modem drivers and even multiple local drivers, although that would not normally be useful.</p>
-<p>The clustering algorithm works on the set of truechimers produced by the intersection algorithms. Ordinarily, any one of them can in principle provide correct time; however, due to various latency variations, not all can provide the most accurate and stable time. The clustering algorithm, processes the truechimers in one or more rounds to cast off a statistical outlier until no more than the <tt>minclock</tt> option of the <tt>tos</tt> command are left. The default for this option is 3.</p>
-<p>In the prefer scheme the cluster algorithm is modified so that the prefer peer is never discarded; on the contrary, its potential removal becomes a rounds-termination condition. However, the prefer peer can still be discarded by the intersection algorithm as a falseticker. To avoid this, it is usually wise to increase the <tt>mindist</tt> option of the <tt>tos</tt> command from the default .005 s to something like .05 s.</p>
+<p>The mitigation rules are designed to provide an intelligent selection of the system peer from among the selectable sources of different types. When used with the <tt>server</tt> or <tt>peer</tt> commands, the <tt>prefer</tt> option designates one or more survivors as preferred over all others. While the rules do not forbid it, it is usually not useful to designate more than one source as preferred; however, if more than one source is so designated, they are used in the order specified in the configuration file; that is, if the first one becomes unselectable, the second one is considered and so forth. This order of priority is also applicable to multiple PPS drivers, multiple modem drivers and even multiple local drivers, although that would not normally be useful.</p>
+<p>The cluster algorithm works on the set of truechimers produced by the select algorithm. At each round the algorithm casts off the survivor least likely to influence the choice of system peer. However, in the prefer scheme the cluster algorithm is modified so that the prefer peer is never discarded; on the contrary, its potential removal becomes a termination condition. However, the prefer peer can still be discarded by the select algorithm as a falseticker; otherwise, the prefer peer becomes the system peer.</p>
<p>Ordinarily, the combining algorithm computes a weighted average of the survivor
offsets to produce the final synchronization source. However, if a prefer
peer is among the survivors, the combining algorithm is not used. Instead,
remains operational. However, if the radio fails or becomes a falseticker,
the averaged backup sources continue to discipline the system clock.</p>
<h4 id="miti">Mitigation Rules</h4>
-<p>As the selection algorithm scans the associations for selectable candidates, the modem driver and local driver are segregated for later, but only if not designated a prefer peer. If so designated, a driver is included among the candidate population. In addition, if orphan parents are found the parent with the lowest metric is segregated for later; the others are discarded. For this purpose the metric is defined as the four-octet IPv4 address or the first four octets of the hashed IPv6 address. The resulting candidates, including any prefer peers found, are processed by the intersection to produce a possibly empty set of truechimers. The clustering algorithm ranks the truechimers first by stratum then by synchronization distance and designates the survivor with the lowest distance as the potential system peer.</p>
+<p>As the select algorithm scans the associations for selectable candidates, the modem driver and local driver are segregated for later, but only if not designated a prefer peer. If so designated, a driver is included among the candidate population. In addition, if orphan parents are found, the parent with the lowest metric is segregated for later; the others are discarded. For this purpose the metric is defined as the four-octet IPv4 address or the first four octets of the hashed IPv6 address. The resulting candidates, including any prefer peers found, are processed by the select algorithm to produce a possibly empty set of truechimers. The clustering algorithm ranks the truechimers first by stratum then by synchronization distance and temporarily designates the survivor with the lowest distance as the potential system peer.</p>
<p>If one or more truechimers support a pulse-per-second (PPS) signal and the
PPS signal is operating correctly, it is designated a PPS driver. If more than
one PPS diver are found, only the first one is used. The PPS driver is not included
</ul>
<p>The mitigation algorithm proceeds in three steps in turn.</p>
<ol>
- <li>If there are no survivors, the modem driver becomes the only survivor if there is one. If not, the local driver becomes the only survivor if there is one. If not, the orphan parent becomes the only survivor if there is one. If the number of survivors at this point is less than the <tt>minsane</tt> option of the <tt>tos</tt> command, the algorithm is terminated and the system variables remain unchanged. Note that <tt>minsane</tt> is by default 1, but can be set at any value including 0.</li>
- <li>If the prefer peer is among the survivors, it becomes the system peer and its clock offset and jitter are inherited by the corresponding system variables. Otherwise, the combining algorithm computes these variables from the survivor population.</li>
+ <li>If there are no survivors, the modem driver becomes the only survivor if there is one. If not, the local driver becomes the only survivor if there is one. If not, the orphan parent becomes the only survivor if there is one. If the number of survivors at this point is less than the <tt>minsane</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, the algorithm is terminated and the system variables remain unchanged. Note that <tt>minsane</tt> is by default 1, but can be set at any value including 0.</li>
+ <li>If the prefer peer is among the survivors, it becomes the system peer and its offset and jitter are inherited by the corresponding system variables. Otherwise, the combining algorithm computes these variables from the survivor population.</li>
<li>If there is a PPS driver and the system clock offset at this point is less than 0.4 s, and if there is a prefer peer among the survivors or if the PPS peer is designated as a prefer peer, the PPS driver becomes the system peer and its offset and jitter are inherited by the system variables, thus overriding any variables already computed. Note that a PPS driver is present only if PPS signals are actually being received and enabled by the associated driver.</li>
</ol>
<p>If none of the above is the case, the data are disregarded and the system variables remain as they are.</p>
<h4 id="mins">The <tt>minsane</tt> Option</H4>
-<p> The <tt>minsane</tt> option of the <tt>tos</tt> command, the <tt>prefer</tt> option of the <tt>server</tt> and <tt>peer</tt> commands and the <tt>flag</tt> options of the <tt>fudge</tt> command for the PPS driver can be used with the mitigation rules to provide many useful configurations. The <tt>minsane</tt> option specifies the minimum number of survivors required to synchronized the system clock. The <tt>prefer</tt> option designates the prefer peer. The driver-dependent <tt>flag</tt> options enable the PPS driver for various conditions.</p>
+<p> The <tt>minsane</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, the <tt>prefer</tt> option of the <tt>server</tt> and <tt>peer</tt> commands and the <tt>flag</tt> options of the <tt>fudge</tt> command for the PPS driver can be used with the mitigation rules to provide many useful configurations. The <tt>minsane</tt> option specifies the minimum number of survivors required to synchronized the system clock. The <tt>prefer</tt> option designates the prefer peer. The driver-dependent <tt>flag</tt> options enable the PPS driver for various conditions.</p>
<p>A common scenario is a GPS driver with a serial timecode and PPS signal. The
PPS signal is disabled until the system clock has been set by some means, not
necessarily the GPS driver. If the serial timecode is within 0.4 s of the PPS
disconnected, the GPS driver stops updating the system clock and so eventually
becomes unreachable and replaced by other sources.</p>
<p>Whether or not the GPS driver disables the PPS signal when unreachable is
- at the discretion of the driver. Ordinarily, the PPS signal would be disabled in this case; however, When the GPS receiver has a precision holdover oscillator, the driver may elect to continue PPS operation. In this case the PPS signal continues to discipline the system clock.</p>
+ at the discretion of the driver. Ordinarily, the PPS signal is disabled in this case; however, when the GPS receiver has a precision holdover oscillator, the driver may elect to continue PPS operation. In this case, <tt>minsane</tt> can be set to zero so the PPS signal continues to discipline the system clock.</p>
<p> </p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
<li class='inline'><a href='authopt.html#automax'>automax - specify Autokey regeneration interval</a></li>\
<li class='inline'><a href='authopt.html#controlkey'>controlkey - specify control key ID</a></li>\
<li class='inline'><a href='authopt.html#crypto'>crypto - configure Autokey parameters</a></li>\
+<li class='inline'><a href='authopt.html#ident'>ident - specify Autokey ephemeral group name</a></li>\
+<li class='inline'><a href='authopt.html#keys'>keys - specify symmetric keys filename</a></li>\
<li class='inline'><a href='authopt.html#keysdir'>keysdir - specify Autokey key directory</a></li>\
<li class='inline'><a href='authopt.html#requestkey'>requestkey - specify request key ID</a></li>\
<li class='inline'><a href='authopt.html#revoke'>revoke - specify Autokey randomization interval</a></li>\
<li class='inline'><a href='miscopt.html#logconfig'>logconfig - configure log file</a></li>\
<li class='inline'><a href='miscopt.html#mru'>mru - control monitor MRU list limits</a></li>\
<li class='inline'><a href='miscopt.html#phone'>phone - specify modem phone numbers</a></li>\
+<li class='inline'><a href='miscopt.html#reset'>reset - reset groups of counters</a></li>\
<li class='inline'><a href='miscopt.html#saveconfigdir'>saveconfigdir - specify saveconfig directory</a></li>\
<li class='inline'><a href='miscopt.html#setvar'>setvar - set system variables</a></li>\
<li class='inline'><a href='miscopt.html#tinker'>tinker - modify sacred system parameters (dangerous)</a></li>\
<title>Clock Select Algorithm</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
-<body><em></em>
+<body>
+<em></em>
<h3>Clock Select Algorithm</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->04-Jan-2011 22:18<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->29-Jul-2011 1:39<!-- #EndDate -->
UTC</p>
<hr>
<p>The clock select algorithm determines from a set of candidates, which are correct (<em>truechimers</em>) and which are not (<em>falsetickers</em>) according to a set of formal correctness assertions. The principles are based on the observation that the maximum error in determining the offset of a candidate cannot exceed one-half the roundtrip delay to the primary reference clock at the time of measurement. This must be increased by the maximum error that can accumulate since then. In NTP the total, called the <em>synchronization distance</em>, is one-half the roundtrip root delay plus the root dispersion plus minor error contributions not considered here.</p>
</div>
<p> The algorithm operates as shown in Figure 2. Let <em>m</em> be the number of candidates and <em>f</em> the number of falsetickers, initially zero. Move a pointer from the leftmost endpoint towards the rightmost endpoint in Figure 1 and count the number of candidates, stopping when that number reaches <em>m</em> - <em>f</em>; this is the left endpoint of the intersection interval. Then, do the same, but moving from the rightmost endpoint towards the leftmost endpoint; this is the right endpoint of the intersection interval. If the left endpoint is greater than the right endpoint; i.e., the interval appears backwards. increase <em>f</em> by 1. If <em>f</em> is less than <em>n</em> / 2, try again; otherwise, the algorithm fails and no truechimers could be found..</p>
<p>The clock select algorithm then scans the associations. If the right endpoint of the correctness interval for a candidate is greater than the left endpoint of the intersection interval, or if the left endpoint of the correctness interval is less than the right endpoint of the intersection interval, the candidate is a truechimer; otherwise, it is a falseticker.</p>
-<p>In practice, with fast LANs and modern computers, the correctness interval can be quite small, especially when the candidates are multiple reference clocks. In such cases the intersection interval m
ay be empty, due to insignificant differences in the reference clock offsets. To avoid this, the synchronization distance must be at least the value of <tt>mindist</tt>, with default 1 ms. This value can be changed using the <tt>mindist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p>
+<p>In practice, with fast LANs and modern computers, the correctness interval can be quite small, especially when the candidates are multiple reference clocks. In such cases the intersection interval m
ight be empty, due to insignificant differences in the reference clock offsets. To avoid this, the size of the correctness interval must be at least the value of <tt>mindist</tt>, with default 1 ms. This value can be changed using the <tt>mindist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
<img src="pic/dogsnake.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>S is for snakeoil.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->04-Sep-2010 17:48<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->04-Aug-2010 1:38<!-- #EndDate -->
UTC</p>
<br clear="left">
<hr>
<h4>Synopsis</h4>
-<tt>sntp [{-h --help -?}][{ -v -V -W }][{-r -a}][-P <i>prompt</i>][-e <i>minerr</i>][-E <i>maxerr</i>][-c <i>count</i>][-d <i>delay</i>][address(es)]</tt>
+<tt>sntp [{--help -?}][{-4 -6}][-a <i>keynum</i>][-b <i>bcaddress</i>][-B <i>bctimeout</i>][-c][-d][-D <i>debug-level</i>][-h <i>delay</i>][-K <i>kodfile</i>][-k <i>keyfile</i>][-l <i>logfile</i>][-M <i>steplimit</i>][-o <i>ntpver</i>][-r][-S][-s][-u <i>uctimeout</i>][--wait][--version][<i>address(es)</i>]</tt>
<h4>Description</h4>
-<p>This program is a Simple Network Time Protocol (SNTP) client that can be used to query a Network Time Protocol (NTP) server and display the time offset of the system clock relative to the server clock. Run as root it can correct the system clock to this offset as well. It can be run as an interactive command or from a script by a <tt>cron</tt> job. The program implements the SNTP protocol defined in RFC-4330, which is a subset of the NTP protocol defined in RFC-1305, but does not provide the sanity checks, access controls, security functions and mitigation algorithms as in the full NTP implementation.</p>
+<p>This program is a Simple Network Time Protocol (SNTP) client that can be used to query a Network Time Protocol (NTP) server and display the time offset of the system clock relative to the server clock. Run as root it can correct the system clock to this offset as well. It can be run as an interactive command or from a script by a <tt>cron</tt> job. The program implements the SNTP client protocol defined in RFC 5905, including the full on-wire protocol but does not provide the sanity checks, access controls, security functions and mitigation algorithms as in the full NTP version 4 specification, also defined in RFC 5905.</p>
<p>By default, <tt>sntp</tt> writes the local date and time (i.e., not UTC) to the standard output in the format</p>
-<p><tt>1996 Oct 15 20:17:25.123 + 4.567 +/- 0.089 secs</tt>,</p>
-<p>where the <tt>+ 4.567 +/- 0.089 secs</tt> indicates the time offset and error bound of the system clock relative to the server clock.</p>
-<p>If a NTP server <i>address</i> is explicitly specified, the program sends a single message to the server and waits up to <i>delay</i> seconds for a unicast server message. Otherwise, it sends no message and waits up to <i>delay</i> seconds for a broadcast server message.</p>
+<p><tt>2011-08-04 00:40:36.642222 (+0000) +0.006611 +/- 0.041061 psp-os1 149.20.68.26</tt></p>
+<p>where the <tt>+0.006611 +/- 0.041061</tt> indicates the time offset and error bound of the system clock relative to the server clock, in seconds.</p>
+<p>If -b <i>bcaddress</i> is not specified, the program sends a single message to each address and waits up to <i>uctimeout</i> (default 5) seconds for a unicast server response. Otherwise, it sends no message and waits up to <i>bctimeout</i> (default 68) seconds for a broadcast NTP message.</p>
<h4>Options</h4>
<p><tt>sntp</tt> recognizes the following options:</p>
<dl>
- <dt><tt>-h, --help</tt></dt>
- <dd>displays usage information.</dd>
- <dt><tt>-v</tt></dt>
- <dd>writes diagnostic messages and a limited amount of tracing to standard error. The <tt>-v, -V</tt> and <tt>-W</tt> give increasing levels of detail.</dd>
- <dt><tt>-r</tt></dt>
- <dd>steps the system clock to the correct time by the Unix <tt>settimeofday</tt> system call. Requires root privilege.</dd>
- <dt><tt>-a</tt></dt>
- <dd>slews the system clock to the correct time by the Unix <tt>adjtime</tt> system call. Requires root privilege.</dd>
- <dt><tt>-e <i>minerr</i></tt></dt>
- <dd>sets the minimum offset to <tt><i>minerr</i></tt> seconds. Measured offsets less than this are ignored. Acceptable values are from 0.001 to 1 with default 0.1 if unicast mode and 0.5 for broadcast mode.</dd>
- <dt><tt>-E <i>maxerr</i></tt></dt>
- <dd>sets the maximum offset to <tt><i>maxerr</i></tt> seconds. Measured offsets greater than this are ignored. Acceptable values are from 1 to 60 with default 5.</dd>
- <dt><tt>-P <i>prompt</i></tt></dt>
- <dd>sets the maximum automatic offset to <tt><i>maxerr</i></tt> seconds. Acceptable values are from 1 to 3600 or <tt>no</tt>, with default 30. If the program is being run interactively, measured offsets greater than this will prompt the user for confirmation. Specifying <tt>no</tt> will disable this and the correction will be made regardless.</dd>
- <dt><tt>-c <i>count</i></tt></dt>
- <dd>sets the maximum number of NTP packets required to <i>count</i>. Acceptable values are from 1 to 25 in unicast mode and 5 to 25 in broadcast mode. The default is 5 in either mode.</dd>
- <dt><tt>-d <i>delay</i></tt></dt>
- <dd>sets the maximum waiting time in broadcast mode to <i>delay</i> seconds. Acceptable values are from 1 to 3600, with default 15 in unicast mode and 300 in broadcast mode.</dd>
+ <dt><tt>-?, --help</tt></dt>
+ <dd>displays usage information. The short form typically requires shell quoting, such as <tt>-\?</tt>, otherwise <tt>?</tt> is consumed by the shell.</dd>
+ <dt><tt>-4, --ipv4</tt></dt>
+ <dd>When resolving hostnames to IP addresses, use IPv4 addresses only.</dd>
+ <dt><tt>-6, --ipv6</tt></dt>
+ <dd>When resolving hostnames to IP addresses, use IPv6 addresses only.</dd>
+ <dt><tt>-a <i>keynum</i>, --authentication <i>keynum</i></tt></dt>
+ <dd>Enable authentication with the key ID <i>keynum</i>. <i>keynum</i> is a number specified in the keyfile along with an authentication secret (password or digest). See the <tt>-k, --keyfile</tt> option for more details.</dd>
+ <dt><tt>-b <i>bcaddress</i>, --broadcast <i>bcaddress</i></tt></dt>
+ <dd>Listen for NTP packets sent to the broadcast or multicast address <i>bcaddress</i>, which can be a DNS name or IP address. The default maximum time to listen for broadcasts/multicasts, 68 seconds, can be modified with the <tt>-B, --bctimeout</tt> option.</dd>
+ <dt><tt>-B <i>bctimeout</i>, --bctimeout <i>bctimeout</i></tt></dt>
+ <dd>Wait <i>bctimeout</i> seconds for broadcast or multicast NTP message before terminating. The default is 68 seconds, chosen because ntpd typically transmits broadcasts/multicasts every 64 seconds. Note that the short option is <tt>-B</tt>, an uppercase letter B.</dd>
+ <dt><tt>-c, --concurrent</tt></dt>
+ <dd>Concurrently query all addresses returned for hostname. Requests from an NTP client to a single server should never be sent more often than once every two seconds. By default, all addresses resolved from a single hostname are assumed to be for a single instance of ntpd, and therefore sntp will send queries to these addresses one after another, waiting two seconds between queries. This option indicates multiple addresses returned for a hostname are on different machines, so sntp can send concurrent queries. This is appropriate when using *.pool.ntp.org, for example.</dd>
+ <dt><tt>-d, --debug-level</tt></dt>
+ <dd>Increase debug verbosity level by one. May be specified multiple times. See also the <tt>-D, --set-debug-level</tt> option.</dd>
+ <dt><tt>-D <i>debug-level</i>, --set-debug-level <i>debug-level</i></tt></dt>
+ <dd>Set the debug verbosity level to <i>debug-level</i>. The default level is zero. Note that the short option is <tt>-D</tt>, an uppercase letter D. See also the <tt>-d, --debug-level</tt> option.</dd>
+ <dt><tt>-h <i>delay</i>, --headspace <i>delay</i></tt></dt>
+ <dd>Specify the <i>delay</i> in milliseconds between outgoing queries, defaulting to 10. <tt>sntp</tt> sends queries to all provided hostnames/addresses in short succession, and by default terminates once the first valid response is received. With multiple time sources provided, all but one will not be used. To limit the number of queries whose responses will not be used, each query is separated from the preceding one by <i>delay</i> milliseconds, to allow time for responses to earlier queries to be received. A larger <i>delay</i> reduces the query load on the time sources, increasing the time to receive a valid response if the first source attempted is slow or unreachable.</dd>
+ <dt><tt>-K <i>kodfile</i>, --kod <i>kodfile</i></tt></dt>
+ <dd>Specifies the filename <i>kodfile</i> to be used for the persistent history of KoD (Kiss Of Death, or rate-limiting) responses received from servers. The default is <tt>/var/db/ntp-kod</tt>. Note that the short option is <tt>-K</tt>, an uppercase letter K.</dd>
+ <dt><tt>-k <i>keyfile</i>, --keyfile <i>keyfile</i></tt></dt>
+ <dd>Specifies the filename <i>keyfile</i> used with the <tt>-a</tt>/<tt>--authentication</tt> option. The format of the file is described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>.</dd>
+ <dt><tt>-l <i>logfile</i>, --filelog <i>logfile</i></tt></dt>
+ <dd>Specifies the filename in which to append a copy of status messages, which also appear on the terminal.</dd>
+ <dt><tt>-M <i>steplimit</i>, --steplimit <i>steplimit</i></tt></dt>
+ <dd>If both <tt>-S</tt>/<tt>--step</tt> and <tt>-s</tt>/<tt>--slew</tt> options are provided, an offset of less than <i>steplimit</i> milliseconds will be corrected by slewing the clock using adjtime(), while an offset of <i>steplimit</i> or more will be corrected by setting the clock to the corrected time. Note that the short option is <tt>-M</tt>, an uppercase letter M.</dd>
+ <dt><tt>-o <i>ntpver</i>, --ntpversion <i>ntpver</i></tt></dt>
+ <dd>Specifies the NTP protocol version number <i>ntpver</i> to include in requests, default 4. This option is rarely useful.</dd>
+ <dt><tt>-r, --usereservedport</tt></dt>
+ <dd>By default, <tt>sntp</tt> uses a UDP source port number selected by the operating system. When this option is used, the reserved NTP port 123 is used, which most often requires <tt>sntp</tt> be invoked as the superuser (commonly "root"). This can help identify connectivity failures due to port-based firewalling which affect <tt>ntpd</tt>, which always uses source port 123.</dd>
+ <dt><tt>-S, --step</tt></dt>
+ <dd>By default, <tt>sntp</tt> displays the clock offset but does not attempt to correct it. This option enables offset correction by stepping, that is, directly setting the clock to the corrected time. This typically requires <tt>sntp</tt> be invoked as the superuser ("root"). Note that the short option is <tt>-S</tt>, an uppercase letter S.</dd>
+ <dt><tt>-s, --slew</tt></dt>
+ <dd>By default, <tt>sntp</tt> displays the clock offset but does not attempt to correct it. This option enables offset correction by slewing using adjtime(), which changes the rate of the clock for a period long enough to accomplish the required offset (phase) correction. This typically requires <tt>sntp</tt> be invoked as the superuser ("root").</dd>
+ <dt><tt>-u <i>uctimeout</i>, --uctimeout <i>uctimeout</i></tt></dt>
+ <dd>Specifies the maximum time <i>uctimeout</i> in seconds to wait for a unicast response before terminating.</dd>
+ <dt><tt>--wait</tt></dt>
+ <dd>When neither <tt>-S</tt>/<tt>--step</tt> nor <tt>-s</tt>/<tt>--slew</tt> options are provided, <tt>sntp</tt> will by default terminate after the first valid response is received. This option causes <tt>sntp</tt> to instead wait for all pending queries' responses.</dd>
+ <dt><tt>--version</tt></dt>
+ <dd>Display the <tt>sntp</tt> program's version number and the date and time it was compiled.</dd>
</dl>
<h4>Return Value</h4>
-<p>The program returns an exit status of zero for success and non-zero otherwise.</p>
+<p>The program returns an exit status of zero for if a valid response is received and non-zero otherwise.</p>
<h4>Author</h4>
-<p><tt>sntp</tt> was developed by N.M. Maclaren of the University of Cambridge Computing Service.</p>
+<p>This <tt>sntp</tt> was originally developed by Johannes Maximilian Kuehn. Harlan Stenn and Dave Hart modified it to query more than one server at a time. See the file <tt>ChangeLog</tt> in the distribution for details.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
projects / thirdparty / ntp.git / commitdiff
