+* Updates and cleanup from Dave Mills.
* [Bug 995] Remove spurious ; from ntp-keygen.c.
* More cleanup and changes from Dave Mills.
* [Bug 980] Direct help to stdout.
<body>
<h3>NTP Bug Reporting Procedures</h3>
<img src="pic/hornraba.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>The rabbit toots to make sure you read this</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:36</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="292">Monday, December 31, 2007</csobj></p>
+ <p>The rabbit toots to make sure you read this.</p>
+ <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:52</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="296">Saturday, February 02, 2008</csobj></p>
.<br clear="left">
<hr>
<h4> Security Bug Reporting Procedures</h4>
- <p>IF YOU THINK YOU HAVE FOUND A SECURITY RELATED NTP BUG please send your report to <a href="mailto:security@ntp.org">security@ntp.org</a>. Please do not contact developers directly.</p>
- <h4> Non-Security Bug Reporting Proceduress</h4>
- <p>The best way to report a non-security bug is to use the NTP Public Service Project Bug Tracking System (Bugzilla) located at <a href="http://bugs.ntp.org/">http://bugs.ntp.org/</a>. Bugs reported this way are immediately forwarded to the developers. Please do not contact the developers directly.</p>
- <p>If you wish to report a non-security bug via electronic mail, you may do so, but please remember that your report will be held until one of our volunteers enters it in Bugzilla. The email address for these reports is <a href="mailto:bugs@ntp.org">bugs@ntp.org</a>. You will need to register at <a href="http://bugs.ntp.org/">http://bugs.ntp.org/</a> so that you may participate directly in any e-mail discussion regarding your report.</p>
+ <p>If you find or suspect a security related program bug in this distribution, please send a report to <a href="mailto:security@ntp.org">security@ntp.org</a>. Please do not contact developers directly.</p>
+ <h4>Non-Security Bug Reporting Procedures</h4>
+ <p>If you find or suspect a non-security related program bug in this distribution, please send a report to the NTP Public Service Project Bug Tracking System (Bugzilla) at <a href="http://bugs.ntp.org/">http://bugs.ntp.org/</a>. Bugs reported this way are immediately forwarded to the developers. Please do not contact the developers directly.</p>
+ <p>If you find or suspect an error in the program documention pages, please send a report directly to the editor David Mills at <a href="mailto:mills@udel.edu">mills@udel.edu</a>. The master documentation pages are not controlled by the bug tracking system. You are invited to contribute new or revised pages in similar style and DOS format.</p>
+ <p>If you wish to send a report via electronic mail, please remember that your report will be held until one of our volunteers enters it in Bugzilla. The email address for these reports is <a href="mailto:bugs@ntp.org">bugs@ntp.org</a>. You will need to register at <a href="http://bugs.ntp.org/">http://bugs.ntp.org/</a> so that you may participate directly in any e-mail discussion regarding your report.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
<h3>Miscellaneous Options</h3>
<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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">22:42</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="290">Sunday, December 16, 2007</csobj></p>
+ <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">19:43</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="296">Saturday, February 02, 2008</csobj></p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
<dl>
<dt><tt>broadcastdelay <i>seconds</i></tt>
<dd>The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers. Ordinarily, this is done automatically by the initial protocol exchanges between the client and server. In some cases, the calibration procedure may fail due to network or server access controls, for example. This command specifies the default delay to be used under these circumstances. Typically (for Ethernet), a number between 0.003 and 0.007 seconds is appropriate. The default when this command is not used is 0.004 seconds.
- <dt><tt>calldelay <i>delay</i></tt>
- <dd>This option controls the delay in seconds between the first and second packets sent in burst or iburst mode to allow additional time for a modem or ISDN call to complete.
+
<dt><tt>driftfile <i>driftfile</i> { <i>tolerance</i> ]</tt>
<dd>This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the <tt>-f</tt> command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero.
<p>The file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (PPM). The file is updated by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that <tt>ntpd</tt> must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.</p>
</dl>
<dt><tt>includefile <i>includefile</i></tt>
<dd>This command allows additional configuration commands to be included from a separate file. Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous configuration file. This option is useful for sites that run <tt>ntpd</tt> on multiple hosts, with (mostly) common options (e.g., a restriction list).
+ <dt><tt>leapfile <i>leapfile</i></tt>
+ <dd>This command loads the NIST leapseconds file and initializes the leapsecond values for the next leapsecond time, expiration time and TAI offset. The file can be obtained directly from NIST national time servers using <tt>ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.
+ <p>While not strictly a security function, the Autokey protocol provides means to securely retrieve the current or updated leapsecond values from a server.</p>
+
<dt><tt>logconfig <i>configkeyword</i></tt>
<dd>This command controls the amount and type of output written to the system <tt>syslog</tt> facility or the alternate <tt>logfile</tt> log file. All <i><tt>configkeyword</tt></i> keywords can be prefixed with <tt>=</tt>, <tt>+</tt> and <tt>-</tt>, where <tt>=</tt> sets the <tt>syslogmask</tt>, <tt>+</tt> adds and <tt>-</tt> removes messages. <tt>syslog messages</tt> can be controlled in four classes (<tt>clock</tt>, <tt>peer</tt>, <tt>sys</tt> and <tt>sync</tt>). Within these classes four types of messages can be controlled: informational messages (<tt>info</tt>), event messages (<tt>events</tt>), statistics messages (<tt>statistics</tt>) and status messages (<tt>status</tt>).
<p>Configuration keywords are formed by concatenating the message class with the event class. The <tt>all</tt> prefix can be used instead of a message class. A message class may also be followed by the <tt>all</tt> keyword to enable/disable all messages of the respective message class. By default, <tt>logconfig</tt> output is set to <tt>allsync</tt>.
<dt><tt>ttl <i>hop</i> ...</tt>
<dd>This command specifies a list of TTL values in increasing order. up to 8 values can be specified. In manycast mode these values are used in turn in an expanding-ring search. The default is eight multiples of 32 starting at 31.
</dl>
- <h4>Files</h4>
- <tt>ntp.drift</tt> frequency
- <h4 id="leap">Leapseconds File</h4>
- <p>The NIST provides a file documenting the epoch for all historic occasions of leap second insertion since 1972. The leapsecond table shows each epoch of insertion along with the offset of International Atomic Time (TAI) with respect to Coordinated Universal Time (UTC), as disseminated by NTP. The table can be obtained directly from NIST national time servers using <tt>ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.</p>
- <p>While not strictly a security function, the Autokey protocol provides means to securely retrieve the leapsecond table from a server or peer. Servers load the leapsecond table directly from the file specified in the <tt>crypto</tt> command, with default <tt>ntpkey_leap</tt>, while clients can obtain the table indirectly from the servers using the Autokey protocol. Once loaded, the table can be provided on request to other clients and servers.</p>
- <p>As explained in the <a href="authopt.html">Authentication Options</a> page, all cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal random number generator. The OpenSSL library uses a designated random seed file for this purpose. The file must be available when starting the NTP daemon and the <tt>ntp-keygen</tt> program. If a site supports OpenSSL or its companion OpenSSH, it is very likely that means to do this are already available.</p>
- <p> compensation (PPM)</p>
+
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
<h3>Monitoring Options</h3>
<img src="pic/pogo8.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
<p>The pig watches the logs.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">19:44</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="256">Friday, January 11, 2008</csobj></p>
+ <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">22:27</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="267">Friday, February 01, 2008</csobj></p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
</table>
<p>The <tt><i>message</i></tt> field includes the last timecode received in decoded ASCII format, where meaningful. In some cases a good deal of additional information is displayed. See information specific to each reference clock for further details.</p>
<dt><tt>cryptostats</tt>
- <dd>Record significant events in the Autokey protocol. This option requires the OpenSSL cryptographic software library. Each event of the protocol module appends one line to the <tt>cryptostats</tt> file set:<dd><tt>49213 525.624 127.127.4.1 <i>message</i></tt>
+ <dd>Record significant events in the Autokey protocol. This option requires the OpenSSL cryptographic software library. Each event of the protocol module appends one line to the <tt>cryptostats</tt> file set:<dd><tt>49213 525.624 128.4.1.1 <i>message</i></tt>
<dd>
<table width="100%" border="1" cellspacing="2" cellpadding="0">
<tr>
<td>time past midnight</td>
</tr>
<tr>
- <td><tt>127.127.4.1</tt></td>
+ <td><tt>128.4.1.1</tt></td>
<td>IP</td>
<td>source address</td>
</tr>
</table>
<p>The <tt><i>message</i></tt> field includes the message type and certain ancillary information. See the <a href="authopt.html">Authentication Options</a> page for further information.</p>
<dt><tt>loopstats</tt>
- <dd>Record clock disiplilne loop statistics. Each system clock update appends one line to the <tt>loopstats</tt> file set:<dd><tt>50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 6</tt>
+ <dd>Record clock disiplilne loop statistics. Each system clock update appends one line to the <tt>loopstats</tt> file set:<dd><tt>50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6</tt>
<dd>
<table width="100%" border="1" cellspacing="2" cellpadding="0">
<tr>
<td>clock offset</td>
</tr>
<tr>
- <td><tt>13.778190</tt></td>
+ <td><tt>13.778</tt></td>
<td>PPM</td>
<td>frequency offset</td>
</tr>
<td>RMS jitter</td>
</tr>
<tr>
- <td><tt>0.0133806</tt></td>
+ <td><tt>0.013380</tt></td>
<td>PPM</td>
<td>RMS wander</td>
</tr>
<tr>
<td><tt>3102453281.584327000</tt></td>
<td>NTP s</td>
- <td>receive timestamp</td>
+ <td>originate timestamp</td>
</tr>
<tr>
<td><tt>3102453281.586228000</tt></td>
<td>NTP s</td>
- <td>transmit timestamp</td>
+ <td>receive timestamp</td>
</tr>
<tr>
<td><tt>3102453332.540806000 </tt></td>
<td>NTP s</td>
- <td>destination timestamp</td>
+ <td>transmit timestamp</td>
</tr>
- </table>
+ <tr>
+ <td><tt>3102453332.541458000</tt></td>
+ <td>NTP s</td>
+ <td>destination timestamp</td>
+ </tr>
+ </table>
<dt><tt>sysstats</tt>
- <dd>Record system statistics. Each hour one line is appended to the <tt>sysstats</tt> file set in the following format:<dd><tt>50928 2132.543 36000 81965 0 9546 56 512 540 10 147</tt>
+ <dd>Record system statistics. Each hour one line is appended to the <tt>sysstats</tt> file set in the following format:<dd><tt>50928 2132.543 36 81965 0 9546 56 512 540 10 147 1</tt>
<dd>
<table width="100%" border="1" cellspacing="2" cellpadding="0">
<tr>
<td>time past midnight</td>
</tr>
<tr>
- <td><tt>36000</tt></td>
- <td>s</td>
+ <td><tt>36</tt></td>
+ <td>h</td>
<td>time since restart</td>
</tr>
<tr>
<td><tt>81965</tt></td>
<td>#</td>
- <td>packets received last hour</td>
+ <td>total packets received last hour</td>
</tr>
<tr>
<td><tt>0</tt></td>
<td>#</td>
- <td>server packets received last hour</td>
+ <td>packets received for this host last hour</td>
</tr>
<tr>
<td><tt>9546</tt></td>
<td>#</td>
<td>rate exceeded packets last hour</td>
</tr>
- </table>
+ <tr>
+ <td><tt>1</tt></td>
+ <td>#</td>
+ <td>kiss-o'-death packets sent last hour</td>
+ </tr>
+ </table>
<dt><tt>timingstats</tt>
<dd>(Only available when the deamon is compiled with process time debugging support (--enable-debug-timing - costs performance). Record processing time statistics for various selected code paths.<dd><tt>53876 36.920 10.0.3.5 1 0.000014592 input processing delay</tt>
<dd>
<h3>Rate Management and the Kiss-o'-Death Packet</h3>
<img src="pic/alice61.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>Packet blizzard</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">17:55</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="292">Monday, December 31, 2007</csobj></p>
+ <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">06:03</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="296">Saturday, February 02, 2008</csobj></p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
<li class="inline"><a href="#intro">Introduction</a>
<li class="inline"><a href="#poll">Poll Rate Control</a>
<li class="inline"><a href="#burst">Burst Control</a>
- <li class="inline"><a href="#mah">Minimum Average Headway</a>
- <li class="inline"><a href="#mgt">Minimum Guard Time</a>
+ <li class="inline"><a href="#mah">Average Headway Time</a>
+ <li class="inline"><a href="#mgt">Guard Time</a>
<li class="inline"><a href="#kod">The Kiss-o'-Death Packet</a>
</ul>
<hr>
<p>Some national time metrology laboratories, including NIST and USNO, use the <tt>ntpd</tt> reference implementation in their very busy public time servers. They operate multiple servers behind load-balancing devices to support aggregate rates up to several thousand packets per second. The servers need to defend themselves against all manner of broken implementations that can clog the server and and network infrastructure. On the other hand, friendly <tt>ntpd</tt> clients need to avoid configurations that can result in unfriendly rates.</p>
<p>There are several features in <tt>ntpd</tt> designed to defend the servers, clients and network against accidental or intentional flood attack. On the other hand these features are also used to insure <tt>ntpd</tt> is a good citizen, even if configured in unfriendly ways. The ground rules are:</p>
<ul>
- <li>Send at the lowest rate consistent with the required nominal error regime.<li>Maintain strict minimum average headway and guard intervals, even if multiple burst options and/or the Autokey protocol are configured.<li>When the first packet of a burst is sent to a server, do not send further packets until the first packet has been received from the server.<li>Upon receiving a Kiss-o'-Death packet (see below), immediately reduce the sending rate.
+ <li>Send at the lowest rate consistent with the required nominal error regime.<li>Maintain strict minimum average headway and guard times, even if multiple burst options and/or the Autokey protocol are operating.<li>When the first packet of a burst is sent to a server, do not send further packets until the first packet has been received from the server.<li>Upon receiving a Kiss-o'-Death packet (see below), immediately reduce the sending rate.
</ul>
- <p>Rate management involves four algorithms to control the poll rate control, burst control, minimum average headway and minimum guard time. These are described in following sections.</p>
+ <p>Rate management involves four algorithms to manage resources: (1) poll rate control, (2) burst control, (3) average headway time and (4) guard time. These are described in following sections.</p>
<h4 id="poll">Poll Rate Control</h4>
- <p>In the <tt>ntpd</tt> design control of the poll interval is an intricate balance between nominal error and network load. As a rule of thumb, if the poll interval increases by 100 percent, nominal error increases by 50 percent. For the default poll interval range from 64 s to 1024 s, this represents an eightfold range in nominal error. Nevertheless and unless the lowest possible nominal error is required, the well mannered NTP client should allow the interval to increase to the maximum when possible.</p>
- <p>The poll interval is proportional to the time constant of the feedback loop which controls the system clock time and frequency. The optimum time constant depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter are reduced as the time constant increases, while errors due to wander are decreased as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept. The poll algorithm follows the intercept in response to changing jitter and wander conditions. However, the intercept has a relatively broad characteristic, so the algorithm is biased towards the high side in the interests of reduced network load.</p>
- <p>The <tt>ntpd</tt> poll interval algorithms slowly but reliably increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it. In addition it avoids needless changes which can cause additional error, especially when operating at very low jitter in the order of microseconds.</p>
+ <p>In the <tt>ntpd</tt> design control of the poll interval is an intricate balance between nominal errors and network load. As a rule of thumb, the nominal errors double for a fourfold increase in poll interval. As the poll interval increases from 64 s to 1024 s, for example, the nominal errors ecrease by a factor of four. Nevertheless and unless the lowest possible nominal error is required, the well mannered NTP client should allow the interval to increase to the maximum when possible.</p>
+ <p>The poll interval is proportional to the time constant of the feedback loop which disciplines the system clock. The optimum time constant depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter are reduced as the time constant increases, while errors due to wander are decreased as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. The <tt>ntpd</tt> poll interval algorithms slowly increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it.</p>
<p>In <tt>ntpd</tt> the poll interval is represented in log<sub>2</sub> s, so the actual values span the range 6-10. The algorithm uses a jiggle counter which operates over the range from -30 to +30 and is initialized at 0. If the measured offset is less than four times the measured average jitter, the counter is increased by the poll interval; if not, it is decreased by twice the poll interval. If the counter reaches +30, the poll interval is incremented by 1; if the counter reaches -30, the poll interval is decremented by 1. In either case the counter is set to 0.</p>
<h4 id="burst">Burst Control</h4>
<p>Occasionally it is necessary to send packets at intervals less than the poll interval. For instance, with the burst and iburst options, 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. If a burst is to be sent, the client sends only 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 giving up. The result is to minimize network load if the server is not responding.</p>
- <p>For the iburst option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the burst option, the number of packets in the burst is determined by the poll interval so that the headway is never less than 16 s. For instance, if operated at the minimum poll interval of 16 s, only a single packet is sent, while the full number of eight packets is sent at poll intervals of 128 s or more.</p>
- <h4 id="mah">Minimum Average Headway</h4>
- <p>There are features in <tt>ntpd</tt> to manage the interval between one packet and the next. These features make use of a set of counters, an output counter for each client association and an input counter for each distinct client address. Each counter increments by a value called the headway when a packet is processed and decrements by one each second. The default headway in <tt>ntpd</tt> is 16 s, but this can be changed using the <tt>discard average</tt> command.</p>
- <p>If the iburst or burst options are present, the poll algorithm sends a burst of packets, instead of a single packet at each poll. The NTPv4 specification requires that bursts contain no more than eight packets; so, starting from an output counter value of zero, the maximum counter value can be no more than 128, called the output ceiling. However, if the burst starts with a counter value other than zero, there is a potential to exceed the ceiling. The poll algorithm avoids this by computing an additional interpacket delay so that the next packet sent will not exceed the ceiling. With this design the long term maximum average headway is never less than 16 s. Designs such as this are often called leaky buckets.</p>
- <p>The <tt>ntpd</tt> input packet routine uses a special list of entries for each distinct client found. Each entry includes the IP address, input counter and time of the most recent arrival. The entries are ordered by time of arrival, most recent first. As each packet arrives, the IP source address is compared to the IP address in each entry in turn. If a match is found the entry is removed and inserted first on the list. If the IP address does not match any entry, a new entry is created and inserted first, possibly discarding the last entry on the list if it is full. Observers will note this is the same algorithm used for page replacement in virtual memory systems.</p>
- <p>In the virtual memory algorithm the entry of interest is the last, whereas here the entry of interest is the first. The input counter is decreased by the time since it was last referenced, but not below zero. If the value of the counter plus the headway is greater than the input ceiling of 128, the packet is discarded. Otherwise, the counter is increased by the headway and the packets processed. The result is, if the client maintains a maximum average headway not less than 16 s and transmits no more than eight packets in a burst, the input counter will not exceed the input ceiling.</p>
- <h4 id="mgt">Minimum Guard Time</h4>
- <p>A review of past client abuse incidence shows the most frequent scenario is a broken client that attempts to send a number of packets at rates of one per second or less. There have been occasions where this abuse has persisted for days at a time. These scenarios are the most damaging, as they can threaten not only the victim server but the network infrastructure as well.</p>
- <p>In the <tt>ntpd</tt> server design the minimum headway between the last packet received and the current packet is called the guard time. If the headway is less than the guard time, the packet is discarded. The guard time defaults to 2 s, but this can be changed using the <tt>discard minimum</tt> command.</p>
+ <p>For the iburst option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the burst option, the number of packets in the burst is determined by the difference between the poll interval and the minimum poll interval set by the <tt>minpoll</tt> option of the <tt>server</tt> command. For instance, at a poll interval of 6 (64 s), only a single packet is sent for every poll, while the full number of eight packets is sent at poll intervals of 9 (512 s) or more.</p>
+ <h4 id="mah">Average Headway Time</h4>
+ <p>There are features in <tt>ntpd</tt> to manage the interval between one packet and the next. These features make use of a set of counters: an output counter for each client association and an input counter for each distinct client address. Each counter increments by a value called the headway when a packet is processed and decrements by one each second. The default headway in <tt>ntpd</tt> is 16 s, but this can be changed using the <tt>average</tt> option of the <tt>discard</tt> command.</p>
+ <p>If the iburst or burst options are present, the poll algorithm sends a burst of packets instead of a single packet at each poll opportunity. The NTPv4 specification requires that bursts contain no more than eight packets; so, starting from an output counter value of zero, the maximum counter value or ouput ceiling can be no more than eight times the minimum poll interval set by the <tt>minpoll</tt> option of the <tt>server</tt> command. However, if the burst starts with a counter value other than zero, there is a potential to exceed the ceiling. The poll algorithm avoids this by computing an additional headway time so that the next packet sent will not exceed the ceiling. Additional headway time can result from Autokey protocol operations. Designs such as this are often called leaky buckets.</p>
+ <p>The <tt>ntpd</tt> input packet routine uses a special list of entries, one for each distinct client address found. Each entry includes an IP address, input counter and time of the most recent arrival. The entries are ordered by time of arrival, most recent first. As each packet arrives, the IP source address is compared to the IP address in each entry in turn. If a match is found the entry is removed and inserted first on the list. If the IP source address does not match any entry, a new entry is created and inserted first, possibly discarding the last entry on the list if it is full. Observers will note this is the same algorithm used for page replacement in virtual memory systems.</p>
+ <p>In the virtual memory algorithm the entry of interest is the last, whereas here the entry of interest is the first. The input counter is decreased by the time since it was last referenced, but not below zero. If the value of the counter plus the headway is greater than the input ceiling set by the <tt>average</tt> option of the <tt>discard</tt> command, the packet is discarded. Otherwise, the counter is increased by the headway and the packet is processed. The result is, if the client maintains a maximum average headway not less than the input ceiling and transmits no more than eight packets in a burst, the input counter will not exceed the input ceiling.</p>
+ <h4 id="mgt">Guard Time</h4>
+ <p>A review of past client abuse incidence shows the most frequent scenario is a broken client that attempts to send a number of packets at rates of one per second or more. There have been occasions where this abuse has persisted for days at a time. These scenarios are the most damaging, as they can threaten not only the victim server but the network infrastructure as well.</p>
+ <p>In the <tt>ntpd</tt> server design the minimum headway between the last packet received and the current packet is called the guard time. If the headway is less than the guard time, the packet is discarded. The guard time defaults to 2 s, but this can be changed using the <tt>minimum</tt> option of the <tt>discard</tt> ommand.</p>
<h4 id="kod">The Kiss-o'-Death Packet</h4>
- <p>As an optional feature <tt>ntpd</tt> sends a special packet called the Kiss-o'-Death (KoD) packet, when either the minimum average headway or minimum guard time is violated. The KoD is a packet with leap bits 11, stratum 0 and reference ID field other than 0. In this case the reference ID field is a four-character ASCII string, called the kiss code, showing the reason for the KoD. At present, only one kiss code, RATE, is used to tell the client to slow down. In order to make sure the client notices the KoD, the receive and transmit timestamps are set to the transmit timestamp of the client packet and all other fields left as in the client packet. Thus, even if the client ignores the KoD indication, it cannot do any useful time computations. KoDs themselves are rate limited to no more than two per second in order to deflect a flood attack.</p>
- <p>There is some controversy about the discard and KoD provisions. The nature of the datagram service supporting NTP provides no way to throttle cleints other than behaving badly. Clients are strongly advised to support the KoD, but there are no legal or societal statutes requiring it. The reference implementation responds to a KoD by permanantly disabling the association, but then it should never ignite a KoD unless the <tt>discard</tt> commands are abused.</p>
+ <p>As an optional feature <tt>ntpd</tt> can send a special packet called the Kiss-o'-Death (KoD) packet when either the average headway or guard time is violated. The KoD is a packet with leap bits 11, stratum 0 and reference ID field other than 0. In this case the reference ID field is a four-character ASCII string, called the kiss code, showing the reason for the KoD. The KoD is enabled by the <tt>limited kod</tt> options to the <tt>restrict</tt> command.</p>
+ <p>At present, only one kiss code <tt>RATE</tt> is used to tell the client to slow down. In order to make sure the client notices the KoD, the receive and transmit timestamps are set to the transmit timestamp of the client packet and all other fields left as in the client packet. Thus, even if the client ignores the KoD, it cannot do any useful time computations. KoDs themselves are rate limited in the same way as arriving packets in order to deflect a flood attack.</p>
+ <p>There is some controversy about the KoD provisions. The nature of the datagram service supporting NTP provides no way to throttle clients other than behaving badly. Clients are strongly advised to support the KoD, but there are no legal or societal statutes requiring it. The reference implementation responds to a KoD by temporarily increasing the ouptut counter and thus the headway.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
pll_control = 1;
memset(&ntv, 0, sizeof(ntv));
ntv.modes = MOD_BITS | MOD_FREQUENCY;
- ntv.status = STA_PLL;
ntv.maxerror = MAXDISPERSE;
ntv.esterror = MAXDISPERSE;
#ifdef SIGSYS
u_long sys_oldversion; /* old version */
u_long sys_restricted; /* access denied */
-u_long sys_badlength; /* bad version, length or format */
+u_long sys_badlength; /* bad length or format */
u_long sys_badauth; /* bad authentication */
u_long sys_declined; /* packets declined */
u_long sys_limitrejected; /* rate exceeded */
int has_mac; /* length of MAC field */
int authlen; /* offset of MAC field */
int is_authentic = 0; /* cryptosum ok */
- keyid_t skeyid = 0; /* key ID */
+ int retcode = AM_NOMATCH; /* match code */
+ keyid_t skeyid = 0; /* key IDs */
struct sockaddr_storage *dstadr_sin; /* active runway */
struct peer *peer2; /* aux peer structure pointer */
l_fp p_org; /* origin timestamp */
l_fp p_rec; /* receive timestamp */
l_fp p_xmt; /* transmit timestamp */
#ifdef OPENSSL
- keyid_t tkeyid = 0; /* temporary key ID */
- keyid_t pkeyid = 0; /* previous key ID */
struct autokey *ap; /* autokey structure pointer */
int rval; /* cookie snatcher */
+ keyid_t pkeyid = 0, tkeyid = 0; /* key IDs */
#endif /* OPENSSL */
- int retcode = AM_NOMATCH;
/*
* Monitor the packet and get restrictions. Note that the packet
* length for control and private mode packets must be checked
- * by the service routines. Note that no statistics counters are
- * recorded for restrict violations, since these counters are in
- * the restriction routine. Note the careful distinctions here
- * between a packet with a format error and a packet that is
- * simply discarded without prejudice. Some restrictions have to
- * be handled later in order to generate a kiss-o'-death packet.
+ * by the service routines. Some restrictions have to be handled
+ * later in order to generate a kiss-o'-death packet.
*/
/*
* Bogus port check is before anything, since it probably
* reveals a clogging attack.
*/
sys_received++;
- if (SRCPORT(&rbufp->recv_srcadr) == 0) {
+ if (SRCPORT(&rbufp->recv_srcadr) < NTP_PORT) {
sys_badlength++;
return; /* bogus port */
}
restrict_mask = restrictions(&rbufp->recv_srcadr);
- restrict_mask = ntp_monitor(rbufp, restrict_mask);
#ifdef DEBUG
if (debug > 1)
printf("receive: at %ld %s<-%s flags %x restrict %03x\n",
sys_badlength++;
return; /* bad length */
}
-
- /*
- * Extension fields are illegal if Autokey is
- * not configured.
- */
-#ifdef OPENSSL
- if (!crypto_flags)
- restrict_mask |= RES_DONTSERVE;
-#else /* OPENSSL */
- restrict_mask |= RES_DONTSERVE;
-#endif /* OPENSSL */
authlen += temp;
has_mac -= temp;
} else {
return; /* bad length */
}
}
-#ifdef OPENSSL
- pkeyid = tkeyid = 0;
-#endif /* OPENSSL */
+
+ /*
+ * Update the MRU list and finger the cloggers. We do this in
+ * all cases mainly as a profiling tool. It can be a little
+ * expensive, so turn it off for production use. Note that we
+ * don't do this for control and monitoring packets, as they are
+ * not rate controlled. Note that if RES_DONTTRUST is lit,
+ * packets without a MAC are discarded.
+ */
+ restrict_mask = ntp_monitor(rbufp, restrict_mask);
+ if (restrict_mask & RES_DONTTRUST && has_mac == 0) {
+ sys_restricted++;
+ return; /* access denied */
+ }
+ if (restrict_mask & RES_LIMITED) {
+ sys_limitrejected++;
+ if (!(restrict_mask & RES_KOD) || hismode ==
+ MODE_BROADCAST)
+ return; /* rate exceeded */
+
+ if (hismode == MODE_CLIENT)
+ fast_xmit(rbufp, MODE_SERVER, skeyid, "RATE");
+ else
+ fast_xmit(rbufp, MODE_ACTIVE, skeyid, "RATE");
+ return; /* rate exceeded */
+ }
/*
* We have tossed out as many buggy packets as possible early in
authlen + has_mac, is_authentic);
#endif
}
- if (restrict_mask & RES_LIMITED) {
- sys_limitrejected++;
- if (hismode == MODE_CLIENT && (restrict_mask & RES_KOD))
- fast_xmit(rbufp, MODE_SERVER, skeyid, "RATE");
- return; /* rate exceeded */
- }
/*
* The association matching rules are implemented by a set of
case AM_NEWPASS:
if (!AUTH(sys_authenticate | (restrict_mask &
(RES_NOPEER | RES_DONTTRUST)), is_authentic)) {
- fast_xmit(rbufp, MODE_PASSIVE, 0, NULL);
sys_restricted++;
return; /* access denied */
}
} else if (hismode != MODE_BROADCAST) {
if (L_ISZERO(&p_org)) {
peer->flash |= TEST3; /* protocol unsynch */
- peer->seldisptoolarge++;
} else if (!L_ISEQU(&p_org, &peer->xmt)) {
peer->flash |= TEST2; /* bogus packet */
peer->bogusorg++;
*/
if (peer->hmode == MODE_CLIENT && (peer->flash &
PKT_TEST_MASK)) {
- return;
+ return; /* broken packet */
/*
* If this is a crypto_NAK and the flashers are dark, the server
} else if (!AUTH(has_mac || (restrict_mask & RES_DONTTRUST),
is_authentic)) {
peer->flash |= TEST5;
+ peer->badauth++;
if (hismode == MODE_ACTIVE || hismode == MODE_PASSIVE)
fast_xmit(rbufp, MODE_ACTIVE, 0, NULL);
sys_restricted++;
return; /* Davy Jones */
/*
- * Test for kiss-o'death packet. We carefully avoid a hazard
+ * Test for kiss-o'-death packets. We carefully avoid a hazard
* when the client has restarted the association after a kiss by
* upping the throttle to the max.
*/
if (hismode == MODE_SERVER && hisleap == LEAP_NOTINSYNC &&
hisstratum == STRATUM_UNSPEC) {
- if (memcmp(&pkt->refid, "DENY", 4) == 0) {
- peer_clear(peer, "DENY");
- peer->flash |= TEST4;
- msyslog(LOG_NOTICE,
- "receive: server %s access denied",
- stoa(&rbufp->recv_srcadr));
- } else if (memcmp(&pkt->refid, "RATE", 4) == 0) {
+ peer->selbroken++;
+ if (memcmp(&pkt->refid, "RATE", 4) == 0) {
peer->throttle += NTP_SHIFT * (1 <<
peer->minpoll);
poll_update(peer, peer->hpoll);
msyslog(LOG_NOTICE,
"receive: server %s maximum rate exceeded",
stoa(&rbufp->recv_srcadr));
+ } else if (memcmp(&pkt->refid, "DENY", 4) == 0) {
+ peer->flash |= TEST4;
+ msyslog(LOG_NOTICE,
+ "receive: server %s access denied",
+ stoa(&rbufp->recv_srcadr));
}
+ return; /* kiss-o'-death */
}
/*
* values.
*/
if (current_time > peer->refresh) {
- peer_clear(peer, "CRYP");
+ peer_clear(peer, "TIME");
return;
}
}
* receive() routine.
*/
if (peer->flash & PKT_TEST_MASK) {
+ peer->seldisptoolarge++;
#ifdef DEBUG
if (debug)
printf("packet: flash header %04x\n",
peer->nextdate = next;
else
peer->nextdate = utemp;
- next = peer->throttle - (1 << peer->minpoll);
- if (next > 0)
- peer->nextdate += res_min_interval + (next >>
+ hpoll = peer->throttle - (1 << peer->minpoll);
+ if (hpoll > 0)
+ peer->nextdate += res_min_interval + (hpoll >>
4);
}
#ifdef DEBUG
if (authlen == 0) {
msyslog(LOG_NOTICE, "transmit: %s key %u not found",
stoa(&peer->srcadr), xkeyid);
+ peer_clear(peer, "CRYP");
peer->flash |= TEST9; /* no key found */
return;
}
projects / thirdparty / ntp.git / commitdiff
