]> git.ipfire.org Git - thirdparty/ntp.git/commitdiff
Documentation updates from Dave Mills
authorHarlan Stenn <stenn@ntp.org>
Thu, 14 Oct 2010 06:34:58 +0000 (02:34 -0400)
committerHarlan Stenn <stenn@ntp.org>
Thu, 14 Oct 2010 06:34:58 +0000 (02:34 -0400)
bk: 4cb6a492bE6f0qBE9Qz4vDOaoo_E0w

ChangeLog
html/assoc.html
html/decode.html
html/warp.html

index 94b9b8b9a734144371d3a7b18adfcb66344bb7fb..3b82fe374bf568f53bc0f8ad5903aafdd49b1487 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,4 @@
+* Documentation updates from Dave Mills.
 (4.2.7p63) 2010/10/13 Released by Harlan Stenn <stenn@ntp.org>
 * [Bug 1080] from 4.2.6p3-RC3: ntpd on ipv6 routers very chatty.
 * Documentation nit cleanup.
index b0e246695cc6942d77ad2b9f20aa66864fac2a55..8822a2dce3356ae9c92f33aceadb10a0a2d2da6b 100644 (file)
@@ -11,7 +11,7 @@
 <img src="pic/alice51.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>Make sure who your friends are.</p>
 <p>Last update:
-  <!-- #BeginDate format:En2m -->12-Oct-2010  3:19<!-- #EndDate -->
+  <!-- #BeginDate format:En2m -->14-Oct-2010  3:20<!-- #EndDate -->
   UTC</p>
 <br clear="left">
 <h4>Related Links</h4>
   <li class="inline"><a href="#symact">Symmetric Active/Passive Mode</a></li>
   <li class="inline"><a href="#broad">Broadcast/Multicast Modes</a></li>
   <li class="inline"><a href="#many">Manycast Mode</a></li>
-  <li class="inline"><a href="#poll">Poll Interval Control</a></li>
+  <li class="inline"><a href="#poll">Poll Interval Management</a></li>
   <li class="inline"><a href="#burst">Burst Options</a></li>
 </ul>
 <hr>
 <h4 id="modes">Association Modes</h4>
-<p>This page describes the various modes of operation provided in NTPv4. There are three types of associations in NTP: <em>persistent</em>, <em>preemptable</em> and <em>ephemeral</em>. Persistent associations are mobilized by a configuration command and never demobilized. Preemptable associations, which are new to NTPv4, are mobilized by a configuration command which includes the <tt>preempt</tt> option or upon arrival of an automatic server discovery response. They are are demobilized by timeout or when preempted by  a &quot;better&quot; server, as descrivbed on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. Ephemeral associations are mobilized upon arrival of designated NTP packets and demobilized by timeout.</p>
-<p>Ordinarily, successful mobilization of ephemeral associations requires the server to be cryptographically authenticated to the client. This can be done using either symmetric key or Autokey public key cryptography, as described in the <a href="authentic.html">Authentication Support</a> page.</p>
+<p>This page describes the various modes of operation provided in NTPv4. There are three types of associations in NTP: <em>persistent</em>, <em>preemptable</em> and <em>ephemeral</em>. Persistent associations are mobilized by a configuration command and never demobilized. Preemptable associations, which are new to NTPv4, are mobilized by a configuration command which includes the <tt>preempt</tt> option or upon arrival of an automatic server discovery packet. They are are demobilized by timeout or when preempted by  a &quot;better&quot; server, as described on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. Ephemeral associations are mobilized upon arrival of   broadcast or multicast server packets and demobilized by timeout.</p>
+<p>Ordinarily, successful mobilization of ephemeral associations requires the server to be cryptographically authenticated to the client. This can be done using either symmetric key or Autokey public key cryptography, as described on the <a href="authentic.html">Authentication Support</a> page.</p>
 <p>There are three principal modes of operation in NTP: client/server, symmetric active/passive and broadcast/multicast. There are three automatic server discovery schemes in NTP: broadcast/multicast, manycast and pool described on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. In addition, the orphan mode and burst options described on this page can be used in appropriate cases.</p>
 <p>Following is a summary of the operations in each mode. Note that reference to option applies to the commands described on the <a href="confopt.html">Server Commands and  Options</a> page. See that page for applicability and defaults.</p>
 <h4 id="client">Client/Server Mode</h4>
 <p>As symmetric modes are most often used as root servers for moderate to large subnets where rapid response is required, it is generally best to set the minimum and maximum poll intervals of each root server to the same value using the <tt>minpoll</tt> and <tt>maxpoll</tt> options.</p>
 <h4 id="broad">Broadcast/Multicast Modes</h4>
 <p>NTP broadcast and multicast modes are intended for configurations involving one or a few servers and a possibly very large client population. Broadcast mode can be used with Ethernet, FDDI and WiFi spans interconnected by hubs or switches. Ordinarily, broadcast packets do not extend beyond a level-3 router. Where service is intended beyond a level-3 router, multicast mode can be used. Additional information is on the <a href="discover.html">Automatic NTP Configuration Options</a> page.</p>
-<p>A server is configured to send broadcast or multicast messages  using the <tt>broadcast</tt> command and specifying the subnet address for broadcast  or the multicast group address for multicast. A broadcast client is enabled using the <tt>broadcastclient</tt> command, while a multicasst client is enabled using the <tt>multicstclient</tt> command and specifiying the multicast group address. Multiple commands of either type can be used. However,  the association is not mobilized until the first broadcast or multicast message is actuayl received.</p>
+<p>A server is configured to send broadcast or multicast messages  using the <tt>broadcast</tt> command and specifying the subnet address for broadcast  or the multicast group address for multicast. A broadcast client is enabled using the <tt>broadcastclient</tt> command, while a multicast client is enabled using the <tt>multicstclient</tt> command and specifying the multicast group address. Multiple commands of either type can be used. However,  the association is not mobilized until the first broadcast or multicast message is actually received.</p>
 <h4 id="many">Manycast and Pool Modes</h4>
 <p>Manycast and pool modes are automatic discovery and configuration paradigms new to NTPv4. They are intended as a means for a  client to troll the nearby network neighborhood to find cooperating willing servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. The intended result is that each  client mobilizes ephemeral client associations with some number of the &quot;best&quot; of the nearby  servers, yet automatically reconfigures to sustain this number of servers should one or another fail. Additional information is on the <a href="discover.html">Automatic Server Discovery Schemes</a> page.</p>
-<h4 id="poll">Poll Interval Control</h4>
+<h4 id="poll">Poll Interval Management</h4>
 <p>NTP uses an intricate heuristic algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network overhead. The algorithm measures the incidental offset and jitter to determine the best poll interval. When <tt>ntpd</tt> starts, the interval is the default minimum 64 s. Under normal conditions when the clock discipline has stabilized, the interval increases in steps to the default maximum 1024 s. In addition, should a server become unreachable after some time, the interval increases in steps to the maximum in order to reduce network overhead. Additional information about the algorithm is on the <a href="poll.html">Poll Program</a> page.</p>
 <p>The default poll interval range is suitable for most conditions, but can be changed using options on the <a href="confopt.html">Server Commands and Options</a> and <a href="miscopt.html">Miscellaneous Options</a> pages. However, when using maximum intervals much larger than the default, the residual clock frequency error must be small enough for the discipline loop to capture and correct. The capture range is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM.</p>
-<p>In the NTPv4 specificationn and reference implementation, the poll interval is expressed in log<sub>2</sub> units, properly called the <em>poll exponent.</em> It is constrained by the lower limit <tt>minpoll</tt> and upper limit <tt>maxpoll</tt> options of the <a href="confopt.html"><tt>server</tt></a> command. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases.</p>
+<p>In the NTPv4 specification and reference implementation, the poll interval is expressed in log<sub>2</sub> units, properly called the <em>poll exponent.</em> It is constrained by the lower limit <tt>minpoll</tt> and upper limit <tt>maxpoll</tt> options of the <a href="confopt.html"><tt>server</tt></a> command. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases.</p>
 <p>As a rule of thumb, the expected errors increase by a factor of two as the poll interval increases by a factor of four. The poll interval algorithm slowly increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it. More information about this algorithm is on the <a href="warp.html">How NTP Works</a> page.</p>
 <p>There is normally no need to change the poll limits, as the poll interval is managed automatically as a function of prevailing jitter and wander. The most common exceptions are the following.</p>
 <ul>
   <li>With fast, lightly loaded LANs and modern processors, the nominal Allan intercept is about 500 s. In these cases the expected errors can be further reduced using a poll exponent of 4 (16 s). In the case of the pulse-per-second (PPS) driver, this is the recommended value.</li>
   <li>With symmetric modes the most stable behavior results when both peers are configured in symmetric active mode with matching poll intervals of 6 (64 s).</li>
-  <li>The poll interval should not be modified for reference clocks, with the single exception the ACTS telephone modem driver. In this case the recommended minimum and maximum intervals are 12 (1.1 h) and 17 (36 h), respectively.</li>
+  <li>The poll interval should not be modified for reference clocks, with the single exception the ACTS telephone modem driver. In this case the recommended minimum and maximum intervals are 12 (1.1 hr) and 17 (36 hr), respectively.</li>
 </ul>
 <h4 id="burst">Burst Options</h4>
-<p>Occasionally it is necessary to send packets at intervals less than the poll interval. For instance, with the <tt>burst</tt> and <tt>iburst</tt> options of the <a href="confopt.html"><tt>server</tt></a> command, the poll algorithm sends a burst of several packets at 2-s intervals. The <tt>ntpd</tt> poll algorithm avoids sending needless packets if the server is not responding. The client begins a burst with a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before beginning backoff. The result is to minimize network load if the server is not responding.</p>
-<p>There are two burst options where a single poll event triggers a burst of eight packets at 2-s intervals instead of the normal one packet. They should be used only with the <tt>server</tt> and <tt>pool</tt> commands, but not with reference clock drivers nor symmetric peers. The <tt>burst</tt> option sends a burst when the server is reachable, while the <tt>iburst</tt> option sends a burst when the server is unreachable. Each mode is independently of the other and both can be used at the same time. In either mode the client sends one packet, waits for the reply, then sends the remaining packets in the burst.  This may be useful to allow a modem to complete a call.</p>
-<p>In both modes received server packets update the clock filter, which selects the best (most accurate) time values. When the last packet in the burst is sent, the next received packet updates the system variables and adjusts the system clock as if only a single packet exchange had occurred.</p>
-<p>The <tt>iburst</tt> option is useful where the system clock must be set quickly or when the network attachment requires an initial calling or training sequence. The burst is initiated only when the server first becomes reachable. This improves accuracy with intermittent connections typical of PPP and ISDN services. Outliers due to initial dial-up delays, etc., are avoided and the client sets the clock within a few seconds after the first received packet.</p>
-<p>The <tt>burst</tt> option can be configured in cases of excessive network
+<p>Occasionally it is necessary to send packets temporarily at intervals less than the poll interval. For instance, with the <tt>burst</tt> and <tt>iburst</tt> options of the <a href="confopt.html"><tt>server</tt></a> command, the poll program sends a burst of several packets at 2-s intervals. In either case the poll program avoids sending needless packets if the server is not responding. The client begins a burst with a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before beginning backoff. The result is to minimize network load if the server is not responding. Additional details are  on the <a href="poll.html">Poll Program</a> page.</p>
+<p>There are two burst options where a single poll event triggers a burst. They should be used only with the <tt>server</tt> and <tt>pool</tt> commands, but not with reference clock drivers nor symmetric mode peers. In both modes, received server packets update the clock filter, which selects the best (most accurate) time values. When the last packet in the burst is sent, the next received packet updates the system variables and adjusts the system clock as if only a single packet exchange had occurred.</p>
+<p>The <tt>iburst</tt> option is useful where the system clock must be set quickly or when the network attachment requires an initial calling or training sequence, as in PPP or ISDN services. In general, this option is recommended for  <tt>server</tt> and <tt>pool</tt> commands. A burst is sent only when the server is unreachable; in particular, when first starting up. Ordinarily, the clock is set within a few seconds after the first received packet. See the <a href="clock.html">Clock State Machine</a> page for further details about the startup behavior.</p>
+<p>The <tt>burst</tt> option  is useful in cases of severe network
   jitter or when the network attachment requires an initial calling or training
-  sequence. The burst is initiated at each poll interval when the server is
-  reachable. The number of packets in the burst is determined by the poll interval
-  so that the average interval between packets is no less than 16. At a poll
-  interval of 16 s, only one packet is sent in the burst; at 32 s, two packets
-  are sent and so forth until at 128 s and above eight packets are sent.</p>
+  sequence. This option is recommended when the minimum poll exponent is  larger than 10 (1024 s). A burst is sent only when the server is reachable.  The number of packets in the burst is determined by the poll interval
+  so that the average interval  between packets (headway) is no less than the minimum poll interval for the association.</p>
 <hr>
 <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
 </body>
index 468f51ec9a7523bde270889d8cc05de2709b5089..009a8404cbcb10662ff833557b17ee6b5e18a452 100644 (file)
@@ -11,7 +11,7 @@
 <img src="pic/alice47.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>Caterpillar knows all the error codes, which is more than most of us do.</p>
 <p>Last update:
-  <!-- #BeginDate format:En2m -->10-Sep-2010  0:20<!-- #EndDate -->
+  <!-- #BeginDate format:En2m -->14-Oct-2010  3:34<!-- #EndDate -->
   UTC</p>
 <br clear="left">
 <h4>Related Links</h4>
     <td><tt>0400</tt></td>
     <td>TEST11</td>
     <td><tt>peer_dist</tt></td>
-    <td>peer distance exceeded</td>
+    <td>peer distance threshold exceeded</td>
   </tr>
   <tr>
     <td><tt>0800</tt></td>
     <td><tt>1000</tt></td>
     <td>TEST13</td>
     <td><tt>peer_unreach</tt></td>
-    <td>peer unreachable</td>
+    <td>peer unreachable or nonselectable</td>
   </tr>
 </table>
 <h4 id="kiss">Kiss Codes</h4>
index 69fbce6520e04d98045d2b184ff9f1f41810c88c..90bb68217b8e333dac435b7966969e12f5d473d8 100644 (file)
@@ -9,7 +9,7 @@
 <body>
 <h3>How NTP Works</h3>
 <p>Last update:
-  <!-- #BeginDate format:En2m -->09-Oct-2010  23:00<!-- #EndDate -->
+  <!-- #BeginDate format:En2m -->14-Oct-2010  3:26<!-- #EndDate -->
   UTC</p>
 <h4>Related Links</h4>
 <script type="text/javascript" language="javascript" src="scripts/special.txt"></script>
@@ -33,7 +33,7 @@
   <p>offset = [(<em>T</em><sub>2</sub> -<em> T</em><sub>1</sub>) + (<em>T</em><sub>3</sub> - <em>T</em><sub>4</sub>)] / 2<br>
     delay = (<em>T</em><sub>4</sub> - <em>T</em><sub>1</sub>) - (<em>T</em><sub>3</sub> - <em>T</em><sub>2</sub>).</p>
 </div>
-<p>The  algorithm described on the <a href="filter.html">Clock Filter Algorithm</a> page  selects the    offset  and  delay samples most likely to produce accurate time. Those peers that have passed  the peer sanity tests     of the <a href="decode.html#flash">flash status word</a> are declared <em>selectable</em>. From the selectable population the statistics are used by the algorithm described on the <a href="select.html">Clock Select Algorithm</a> page to determine a number of <em>truechimers</em> according to correctness principles. From the truechimer population the algorithm described on the <a href="cluster.html">Clock Cluster Algorithm</a> page determines a number of <em>survivors</em>  on the basis of statistical clustering principles. The algorithms described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page combine the survivor offsets, designate one of them as the <em>system peer</em> and produces the final offset used by the algorithm described on the <a href="discipline.html">Clock Discipline Algorithm</a> page to adjust the system clock time and frequency. The clock offset and frequency, are recorded by the <tt>loopstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. For additional details about these algorithms, see the Architecture Briefing on the <a href="htttp://www.eecis.udel.edu/~mills/ntp.html">Network Time Synchronization Research Project</a> page.</p>
+<p>The  algorithm described on the <a href="filter.html">Clock Filter Algorithm</a> page  selects the    offset  and  delay samples most likely to produce accurate time. Those peers that have passed  the peer sanity tests     of the <a href="decode.html#flash">flash status word</a> are declared <em>selectable</em>. From the selectable population the statistics are used by the algorithm described on the <a href="select.html">Clock Select Algorithm</a> page to determine a number of <em>truechimers</em> according to correctness principles. From the truechimer population the algorithm described on the <a href="cluster.html">Clock Cluster Algorithm</a> page determines a number of <em>survivors</em>  on the basis of statistical clustering principles. The algorithms described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page combine the survivor offsets, designate one of them as the <em>system peer</em> and produces the final offset used by the algorithm described on the <a href="discipline.html">Clock Discipline Algorithm</a> page to adjust the system clock time and frequency. The clock offset and frequency, are recorded by the <tt>loopstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. For additional details about these algorithms, see the Architecture Briefing on the <a href="http://www.eecis.udel.edu/~mills/ntp.html">Network Time Synchronization Research Project</a> page.</p>
 <h4 id="budget">Statistics Budget</h4>
 <p>Each source is characterized by the   offset and delay samples  measured by the on-wire protocol and the  dispersion and jitter calculated by the clock filter algorithm. In a window of eight samples, this algorithm  selects the offset sample with the lowest  delay, which generally represents the most accurate data. The selected samples become the <em>peer offset</em> and <em>peer delay</em>. The <em>peer dispersion</em>  is determined as a weighted average of the dispersion samples in the window.  It continues to grow at the same  rate as the sample dispersion, 15 <font face="symbol">m</font>s/s. Finally, the <em>peer jitter</em> is determined as the root-mean-square (RMS) average of  the offset samples in the window relative to the selected offset sample. The peer offset, peer delay, peer dispersion and peer jitter are recorded by the <tt>peerstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. Peer variables are displayed by the <tt>rv</tt> command of the <a href="ntpq.html#peer"><tt>ntpq</tt></a> program.</p>
 <p> The clock filter algorithm continues to process packets in this way until the source is no longer reachable. Reachability is determined by an eight-bit shift register, which is shifted left by one bit as each poll packet is sent, with 0 replacing the vacated rightmost bit. Each time an update is received, the rightmost bit is set to 1. The source is considered reachable if any bit is set to 1 in the register; otherwise, it is considered unreachable.</p>