+* Documentation updates from Dave Mills.
* [Bug 1588] finish configure --disable-autokey implementation.
* [Bug 1616] refclock_acts.c: if (pp->leap == 2) is always false.
* [Bug 1620] [Backward Incompatible] "discard minimum" value should be in
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Access Control Support</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+<style type="text/css">
+<!--
+<style1 {
+color: #FF0000;
+ font-weight: bold;
+}
+-->
+</style>
+</head>
+<body>
+<h3>Access Control Support</h3>
+<p><img src="pic/pogo6.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a></p>
+<p>The skunk watches for intruders and sprays.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->09-Sep-2010 17:26<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/accopt.txt"></script>
+<hr>
+<h4>Access Control Support</h4>
+<p>The <tt>ntpd</tt> daemon implements a general purpose access control list (ACL) containing address/match entries sorted first by increasing address values and then by increasing mask values. A match occurs when the bitwise AND of the mask and the packet source address is equal to the bitwise AND of the mask and address in the list. The list is searched in order with the last match found defining the restriction flags associated with the entry.</p>
+<p>The ACL is specified as a list of <tt>restrict</tt> commands in the following format:</p>
+<p><tt>restrict <i>address</i> [mask <i>mask</i>] [<i>flag</i>][...]</tt></p>
+<p>The <tt><i>address</i></tt> argument expressed in dotted-quad form is the address of a host or network. Alternatively, the <tt><i>address</i></tt> argument can be a valid host DNS name. The <tt><i>mask</i></tt> argument expressed in IPv4 or IPv6 numeric address form defaults to all mask bits on, meaning that the <tt><i>address</i></tt> is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0 for IPv4 and address :: mask :: for IPv6) is always the first entry in the list. <tt>restrict default</tt>, with no mask option, modifies both IPv4 and IPv6 default entries. <tt>restrict source</tt> configures a template restriction automatically added at runtime for each association, whether configured, ephemeral, or preemptable, and removed when the association is demobilized.</p>
+<p>Some flags have the effect to deny service, some have the effect to enable service and some are conditioned by other flags. The flags. are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags that deny service are classed in two categories, those that restrict time service and those that restrict informational queries and attempts to do run-time reconfiguration of the server.</p>
+<p>An example may clarify how it works. Our campus has two class-B networks, 128.4 for the ECE and CIS departments and 128.175 for the rest of campus. Let's assume (not true!) that subnet 128.4.1 homes critical services like class rosters and spread sheets. A suitable ACL might look like this:</p>
+<pre>
+restrict default nopeer # deny new associations
+restrict 128.175.0.0 mask 255.255.0.0 # allow campus access
+restrict 128.4.0.0 mask 255.255.0.0 none # allow ECE and CIS access
+restrict 128.4.1.0 mask 255.255.255.0 notrust # require authentication on subnet 1
+restrict time.nist.gov # allow access
+</pre>
+<p>While this facility may be useful for keeping unwanted, broken or malicious clients from congesting innocent servers, it should not be considered an alternative to the NTP authentication facilities. Source address based restrictions are easily circumvented by a determined cracker.</p>
+<p>Default restriction list entries with the flags <tt>ignore, ntpport</tt>, for each of the local host's interface addresses are inserted into the table at startup to prevent the server from attempting to synchronize to its own time. A default entry is also always present, though if it is otherwise unconfigured; no flags are associated with the default entry (i.e., everything besides your own NTP server is unrestricted).</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
-<title>Access Control Options</title>
+<title>Access Control Commands and Options</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
<style type="text/css">
<!--
-.style1 {
- color: #FF0000;
- font-weight: bold;
+<style1 {
+ color: #FF0000;
+ font-weight: bold;
}
--->
</style>
</head>
-
<body>
-
-<h3>Access Control Options</h3>
-
+<h3>Access Control Commands and Options</h3>
<img src="pic/pogo6.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
-
<p>The skunk watches for intruders and sprays.</p>
-<p>Last update:
- <!-- #BeginDate format:En2m -->14-Apr-2010 3:26<!-- #EndDate -->
- UTC</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->09-Sep-2010 23:54<!-- #EndDate -->
+ UTC</p>
<br clear="left">
-
<h4>Related Links</h4>
-
<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
<script type="text/javascript" language="javascript" src="scripts/accopt.txt"></script>
-
-<h4>Table of Contents</h4>
-
-<ul>
-<li class="inline"><a href="#acx">Access Control Support</a></li>
-<li class="inline"><a href="#cmd">Access Control Commands</a></li>
-</ul>
-
<hr>
-
-<h4 id="acx">Access Control Support</h4>
-
-<p>The <tt>ntpd</tt> daemon implements a general purpose access control list
- (ACL) containing address/match entries sorted first by increasing address
- values and then by increasing mask values. A match occurs when the bitwise
- AND of the mask and the packet source address is equal to the bitwise AND of
- the mask and address in the list. The list is searched in order with the last
- match found defining the restriction flags associated with the entry.</p>
-
-<p>An example may clarify how it works. Our campus has two class-B networks,
-128.4 for the ECE and CIS departments and 128.175 for the rest of campus.
-Let's assume (not true!) that subnet 128.4.1 homes critical services like class
- rosters and spread sheets. A suitable ACL might be</p>
-<pre>
-restrict default nopeer # deny new associations
-restrict 128.175.0.0 mask 255.255.0.0 # allow campus access
-restrict 128.4.0.0 mask 255.255.0.0 none # allow ECE and CIS access
-restrict 128.4.1.0 mask 255.255.255.0 notrust # require authentication on subnet 1
-restrict time.nist.gov # allow access
-</pre>
-
-<p>While this facility may be useful for keeping unwanted, broken or malicious clients from congesting innocent servers, it should not be considered an alternative to the NTP authentication facilities. Source address based restrictions are easily circumvented by a determined cracker.</p>
-
-<h4 id="cmd">Access Control Commands</h4>
-
+<h4>Commands and Options</h4>
+<p>Unless noted otherwise, further information about these ccommands is on the <a href="accopt.html">Access Control Support</a> page.</p>
<dl>
-
-<dt id="discard"><tt>discard [ average <i>avg</i> ][ minimum <i>min</i> ] [ monitor <i>prob</i> ]</tt></dt>
-<dd>Set the parameters of the rate control facility which protects the server
- from client abuse. If the <tt>limited</tt> flag is present in the ACL, packets
- that violate these limits are discarded. If, in addition, the <tt>kod</tt> flag
- is present, a kiss-o'-death packet is returned.</dd>
-
-<dd><dl>
-
-<dt><tt>average <i>avg</i></tt></dt>
-<dd>Specify the minimum average interpacket spacing (minimum average headway
-time) in log<sub>2</sub> s with default 3.</dd>
-
-<dt><tt>minimum <i>min</i></tt></dt>
-<dd>Specify the minimum interpacket spacing (guard time) in log<sub>2</sub> s
- with default 1.</dd>
-
-<dt><tt>monitor</tt></dt>
-<dd>Specify the probability of being recorded for packets that overflow the MRU list
- size limit set by <tt>mru maxmem</tt> or <tt>mru maxdepth</tt>. This is a
- performance optimization for servers with aggregate arrivals
- of 1000 packets per second or more.</dd>
-
-</dl></dd>
-
-<dt id="restrict"><tt>restrict default [<i>flag</i>][...]<br>
- restrict source [<i>flag</i>][...]<br>
- restrict <i>address</i> [mask <i>mask</i>] [<i>flag</i>][...]</tt></dt>
-<dd>The <tt><i>address</i></tt> argument expressed in dotted-quad form is the
- address of a host or network. Alternatively, the <tt><i>address</i></tt> argument
- can be a valid host DNS name. The <tt><i>mask</i></tt> argument expressed in
- IPv4 or IPv6 numeric address form defaults to all mask bits on, meaning that the
- <tt><i>address</i></tt> is treated as the address of an individual host. A
- default entry (address 0.0.0.0, mask 0.0.0.0 for IPv4 and address :: mask
- :: for IPv6) is always the first entry in the list.
- <tt>restrict default</tt>, with no mask option, modifies both IPv4 and IPv6
- default entries. <tt>restrict source</tt> configures a template restriction
- automatically added at runtime for each association, whether configured,
- ephemeral, or preemptible, and removed when the association is demobilized.</dd>
-
-<dd>Some flags have the effect to deny service, some have the effect to
- enable service and some are conditioned by other flags. The flags. are
- not orthogonal, in that more restrictive flags will often make less restrictive
- ones redundant. The flags that deny service are classed in two categories,
- those that restrict time service and those that restrict informational queries
- and attempts to do run-time reconfiguration of the server. One or more of the
- following flags may be specified:</dd>
-<dd><dl>
-
-<dt><tt>flake</tt></dt>
-<dd>Discard received NTP packets with probability 0.1; that is, on average drop
- one packet in ten. This is for testing and amusement. The name comes from Bob
- Braden's <i>flakeway</i>, which once did a similar thing for early Internet
- testing.</dd>
-
-<dt><tt>ignore</tt></dt>
-<dd>Deny packets of all kinds, including <tt>ntpq</tt> and <tt>ntpdc</tt> queries.</dd>
-
-<dt><tt>kod</tt></dt>
-<dd>Send a kiss-o'-death (KoD) packet if the <tt>limited</tt> flag is present
- and a packet violates the rate limits established by the <tt>discard</tt> command.
- KoD packets are themselves rate limited for each source address separately.
- If the <tt>kod</tt> flag is used in a restriction which does not have the <tt>limited</tt>
- flag, no KoD responses will result.</dd>
-
-<dt id="limited"><tt>limited</tt></dt>
-<dd>Deny time service if the packet violates the rate limits established by the <tt>discard</tt> command.
- This does not apply to <tt>ntpq</tt> and <tt>ntpdc</tt> queries.</dd>
-
-<dt><tt>lowpriotrap</tt></dt>
-<dd>Declare traps set by matching hosts to be low priority. The number of traps
- a server can maintain is limited (the current limit is 3). Traps are usually
- assigned on a first come, first served basis, with later trap requestors being
- denied service. This flag modifies the assignment algorithm by allowing low
- priority traps to be overridden by later requests for normal priority traps.</dd>
-<dt><tt>mssntp</tt></dt>
-<dd>Enable Microsoft Windows MS-SNTP authentication using Active Directory services.
- <span class="style1">Note: Potential users should be aware that these services
- involve a TCP connection to another process that could potentially block,
- denying services to other users. Therefore, this flag should be used only
- for a dedicated server with no clients other than MS-SNTP.</span></dd>
-<dt><tt>nomodify</tt></dt>
-<dd>Deny <tt>ntpq</tt> and <tt>ntpdc</tt> queries which attempt to modify the
- state of the server (i.e., run time reconfiguration). Queries which return information
- are permitted.</dd>
-
-<dt><tt>noquery</tt></dt>
-<dd>Deny <tt>ntpq</tt> and <tt>ntpdc</tt> queries. Time service is not affected.</dd>
-
-<dt><tt>nopeer</tt></dt>
-<dd>Deny packets that might mobilize an association unless authenticated. This
- includes broadcast, symmetric-active and manycast server packets when a configured
- association does not exist. Note that this flag does not apply to packets
- that do not attempt to mobilize an association. </dd>
-
-<dt><tt>noserve</tt></dt>
-<dd>Deny all packets except <tt>ntpq</tt> and <tt>ntpdc</tt> queries.</dd>
-
-<dt><tt>notrap</tt></dt>
-<dd>Decline to provide mode 6 control message trap service to matching hosts.
- The trap service is a subsystem of the <tt>ntpdc</tt> control message protocol
- which is intended for use by remote event logging programs.</dd>
-
-<dt><tt>notrust</tt></dt>
-<dd>Deny packets that are not cryptographically authenticated. Note carefully
- how this flag interacts with the <tt>auth</tt> option of the <tt>enable</tt> and <tt>disable</tt> commands.
- If <tt>auth</tt> is enabled, which is the default, authentication is required
- for all packets that might mobilize an association.
- If <tt>auth</tt> is
- disabled, but the <tt>notrust</tt> flag is not present, an association can be
- mobilized whether or not authenticated. If <tt>auth</tt> is disabled, but the <tt>notrust</tt> flag
- is present, authentication is required only for the specified address/mask
- range. </dd>
-
- <dt><tt>ntpport</tt></dt>
-<dd>This is actually a match algorithm modifier, rather than a restriction
-flag. Its presence causes the restriction entry to be matched only if the
-source port in the packet is the standard NTP UDP port (123). A restrict line
-containing <tt>ntpport</tt> is considered more specific than one with the
-same address and mask, but lacking <tt>ntpport</tt>.</dd>
- <dt><tt>version</tt></dt>
- <dd>Deny packets that do not match the current NTP version.</dd>
- </dl>
-</dd>
-<dd>Default restriction list entries with the flags <tt>ignore, ntpport</tt>,
- for each of the local host's interface addresses are inserted into the table
- at startup to prevent the server from attempting to synchronize to its own time.
- A default entry is also always present, though if it is otherwise unconfigured;
- no flags are associated with the default entry (i.e., everything besides your
- own NTP server is unrestricted).</dd>
+ <dt id="discard"><tt>discard [ average <i>avg</i> ][ minimum <i>min</i> ] [ monitor <i>prob</i> ]</tt></dt>
+ <dd>Set the parameters of the rate control facility which protects the server from client abuse. If the <tt>limited</tt> flag is present in the ACL, packets that violate these limits are discarded. If, in addition, the <tt>kod</tt> flag is present, a kiss-o'-death packet is returned. See the <a href="rate.html">Rate Management</a> page for further information.
+ The options are:
+ <dl>
+ <dt><tt>average <i>avg</i></tt></dt>
+ <dd>Specify the minimum average interpacket spacing (minimum average headway
+ time) in log<sub>2</sub> s with default 3.</dd>
+ <dt><tt>minimum <i>min</i></tt></dt>
+ <dd>Specify the minimum interpacket spacing (guard time) in seconds with default 1.</dd>
+ <dt><tt>monitor</tt></dt>
+ <dd>Specify the probability of being recorded for packets that overflow the MRU list size limit set by <tt>mru maxmem</tt> or <tt>mru maxdepth</tt>. This is a performance optimization for servers with aggregate arrivals of 1000 packets per second or more.</dd>
+ </dl>
+ </dd>
+ <dt id="restrict"><tt>restrict default [<i>flag</i>][...]<br>
+ restrict source [<i>flag</i>][...]<br>
+ restrict <i>address</i> [mask <i>mask</i>] [<i>flag</i>][...]</tt></dt>
+ <dd>The <tt><i>address</i></tt> argument expressed in dotted-quad form is the address of a host or network. Alternatively, the <tt><i>address</i></tt> argument can be a valid host DNS name. The <tt><i>mask</i></tt> argument expressed in IPv4 or IPv6 numeric address form defaults to all mask bits on, meaning that the <tt><i>address</i></tt> is treated as the address of an individual host. A default entry (address 0.0.0.0, mask 0.0.0.0 for IPv4 and address :: mask :: for IPv6) is always the first entry in the list. <tt>restrict default</tt>, with no mask option, modifies both IPv4 and IPv6 default entries. <tt>restrict source</tt> configures a template restriction automatically added at runtime for each association, whether configured, ephemeral, or preemptible, and removed when the association is demobilized.</dd>
+ <dd>Some flags have the effect to deny service, some have the effect to enable service and some are conditioned by other flags. The flags. are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags that deny service are classed in two categories, those that restrict time service and those that restrict informational queries and attempts to do run-time reconfiguration of the server. One or more of the following flags may be specified:</dd>
+ <dd>
+ <dl>
+ <dt><tt>flake</tt></dt>
+ <dd>Discard received NTP packets with probability 0.1; that is, on average drop one packet in ten. This is for testing and amusement. The name comes from Bob Braden's <i>flakeway</i>, which once did a similar thing for early Internet testing.</dd>
+ <dt><tt>ignore</tt></dt>
+ <dd>Deny packets of all kinds, including <tt>ntpq</tt> and <tt>ntpdc</tt> queries.</dd>
+ <dt><tt>kod</tt></dt>
+ <dd>Send a kiss-o'-death (KoD) packet if the <tt>limited</tt> flag is present and a packet violates the rate limits established by the <tt>discard</tt> command. KoD packets are themselves rate limited for each source address separately. If the <tt>kod</tt> flag is used in a restriction which does not have the <tt>limited</tt> flag, no KoD responses will result.</dd>
+ <dt id="limited"><tt>limited</tt></dt>
+ <dd>Deny time service if the packet violates the rate limits established by the <tt>discard</tt> command. This does not apply to <tt>ntpq</tt> and <tt>ntpdc</tt> queries.</dd>
+ <dt><tt>lowpriotrap</tt></dt>
+ <dd>Declare traps set by matching hosts to be low priority. The number of traps a server can maintain is limited (the current limit is 3). Traps are usually assigned on a first come, first served basis, with later trap requestors being denied service. This flag modifies the assignment algorithm by allowing low priority traps to be overridden by later requests for normal priority traps.</dd>
+ <dt><tt>mssntp</tt></dt>
+ <dd>Enable Microsoft Windows MS-SNTP authentication using Active Directory services. <span class="style1">Note: Potential users should be aware that these services involve a TCP connection to another process that could potentially block, denying services to other users. Therefore, this flag should be used only for a dedicated server with no clients other than MS-SNTP.</span></dd>
+ <dt><tt>nomodify</tt></dt>
+ <dd>Deny <tt>ntpq</tt> and <tt>ntpdc</tt> queries which attempt to modify the state of the server (i.e., run time reconfiguration). Queries which return information are permitted.</dd>
+ <dt><tt>noquery</tt></dt>
+ <dd>Deny <tt>ntpq</tt> and <tt>ntpdc</tt> queries. Time service is not affected.</dd>
+ <dt><tt>nopeer</tt></dt>
+ <dd>Deny packets that might mobilize an association unless authenticated. This includes broadcast, symmetric-active and manycast server packets when a configured association does not exist. Note that this flag does not apply to packets that do not attempt to mobilize an association. </dd>
+ <dt><tt>noserve</tt></dt>
+ <dd>Deny all packets except <tt>ntpq</tt> and <tt>ntpdc</tt> queries.</dd>
+ <dt><tt>notrap</tt></dt>
+ <dd>Decline to provide mode 6 control message trap service to matching hosts. The trap service is a subsystem of the <tt>ntpdc</tt> control message protocol which is intended for use by remote event logging programs.</dd>
+ <dt><tt>notrust</tt></dt>
+ <dd>Deny packets that are not cryptographically authenticated. Note carefully how this flag interacts with the <tt>auth</tt> option of the <tt>enable</tt> and <tt>disable</tt> commands. If <tt>auth</tt> is enabled, which is the default, authentication is required for all packets that might mobilize an association. If <tt>auth</tt> is disabled, but the <tt>notrust</tt> flag is not present, an association can be mobilized whether or not authenticated. If <tt>auth</tt> is disabled, but the <tt>notrust</tt> flag is present, authentication is required only for the specified address/mask range. </dd>
+ <dd>This is actually a match algorithm modifier, rather than a restriction
+ flag. Its presence causes the restriction entry to be matched only if the
+ source port in the packet is the standard NTP UDP port (123). A restrict line
+ containing <tt>ntpport</tt> is considered more specific than one with the
+ same address and mask, but lacking <tt>ntpport</tt>.</dd>
+ <dt><tt>version</tt></dt>
+ <dd>Deny packets that do not match the current NTP version.</dd>
+ </dl>
+ </dd>
+ <dd>Default restriction list entries with the flags <tt>ignore, ntpport</tt>, for each of the local host's interface addresses are inserted into the table at startup to prevent the server from attempting to synchronize to its own time. A default entry is also always present, though if it is otherwise unconfigured; no flags are associated with the default entry (i.e., everything besides your own NTP server is unrestricted).</dd>
</dl>
-
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
-
</body>
-
-</html>
\ No newline at end of file
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Association Management</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Association Management</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
-
- <body>
- <h3>Association Management</h3>
- <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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">21:56</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="277">Friday, December 28, 2007</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#modes">Association Modes</a>
- <li class="inline"><a href="#client">Client/Server Mode</a>
- <li class="inline"><a href="#symact">Symmetric Active/Passive Mode</a>
- <li class="inline"><a href="#broad">Broadcast/Multicast Modes</a>
- <li class="inline"><a href="#many">Manycast Mode</a>
- <li class="inline"><a href="#orphan">Orphan Mode</a>
- <li class="inline"><a href="#burst">Burst Options</a>
- </ul>
- <hr>
- <h4 id="modes">Association Modes</h4>
- <p>This page describes the various modes of operation provided in NTPv4. Details about the configuration commands and options are given on the <a href="confopt.html">Configuration Options</a> page. Details about the cryptographic authentication schemes are given on the <a href="authopt.html">Authentication Options</a> page. Details about the automatic server discovery schemes are described on the <a href="manyopt.html">Automatic Server Discovery Schemes</a> page. Additional information is available in the papers, reports, memoranda and briefings on the <a href="http://www.eecis.udel.edu/~mills/ntp.html"> NTP Project</a> page.</p>
- <p>There are three types of associations in NTP: persistent, preemptable and ephemeral. 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 and are demobilized by a "better" server or by timeout, but only if the number of survivors exceeds the threshold set by the <tt>tos maxclock</tt> configuration command. Ephemeral associations are mobilized upon arrival of designated messages 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="authopt.html">Authentication Options</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="manyopt.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">Configuration Options</a> page. See that page for applicability and defaults.</p>
- <h4 id="client">Client/Server Mode</h4>
- <p>Client/server mode is the most common configuration in the Internet today. It operates in the classic remote-procedure-call (RPC) paradigm with stateless servers and stateful clients. In this mode a host sends a client (mode 3) request to the specified server and expects a server (mode 4) reply at some future time. In some contexts this would be described as a "pull" operation, in that the host pulls the time and related values from the server.</p>
- <p>A host is configured in client mode using the <tt>server</tt> (sic) command and specifying the server DNS name or IPv4 or IPv6 address; the server requires no prior configuration. The <tt>iburst</tt> option described later on this page is recommended for clients, as this speeds up initial synchronization from several minutes to several seconds. The <tt>burst</tt> option described later on this page can be useful to reduce jitter on very noisy dial-up or ISDN network links.</p>
- <p>Ordinarily, the program automatically manages the poll interval between the default minimum and maximum values. The <tt>minpoll</tt> and <tt>maxpoll</tt> options can be used to bracket the range. Unless noted otherwise, these options should not be used with reference clock drivers.</p>
- <h4 id="symact">Symmetric Active/Passive Mode</h4>
- <p>Symmetric active/passive mode is intended for configurations were a clique
- of low-stratum peers operate as mutual backups for each other. Each peer operates
- with one or more primary reference sources, such as a radio clock, or a set
- of secondary (stratum, 2) servers known to be reliable and authentic. Should
- one of the peers lose all reference sources or simply cease operation, the
- other peers will automatically reconfigure so that time and related values
- can flow from the surviving peers to all hosts in the subnet. In some contexts
- this would be described as a "push-pull" operation, in that the
- peer either pulls or pushes the time and related values depending on the particular
- configuration.</p>
- <p>In symmetric active mode a peer symmetric active (mode 1) message to a designated peer. If a matching configured symmetric active association is found, the designated peer returns a symmetric active message. If no matching association is found, the designated peer mobilizes a ephemeral symmetric passive association and returns a symmetric passive (mode 2) message. Since an intruder can impersonate a symmetric active peer and cause a spurious symmetric passive association to be mobilized, symmetric passive mode should always be cryptographically validated.</p>
- <p>A peer is configured in symmetric active mode using the <tt>peer</tt> command and specifying the other peer DNS name or IPv4 or IPv6 address. The <tt>burst</tt> and <tt>iburst</tt> options should not be used in symmetric modes, as this can upset the intended symmetry of the protocol and result in spurious duplicate or dropped messages.</p>
- <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="manyopt.html">Automatic NTP Configuration Options</a> page.</p>
- <h4 id="many">Manycast Mode</h4>
- <p>Manycast mode is a automatic discovery and configuration paradigm new to NTPv4. It is intended as a means for a multicast client to troll the nearby network neighborhood to find cooperating manycast 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 manycast client mobilizes ephemeral client associations with some number of the "best" of the nearby manycast servers, yet automatically reconfigures to sustain this number of servers should one or another fail. Additional information is on the <a href="manyopt.html">Automatic NTP Configuration Options</a> page.</p>
- <h4 id="orphan">Orphan Mode</h4>
- <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 mode be enabled. By default the delay is 600 s (five minutes), but this can be changed using the <tt>tos orphanwait <em>delay</em></tt> 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 (Unix 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>
- <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>
- <h4 id="burst">Burst Options</h4>
- <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
- 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>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<body>
+<h3>Association Management</h3>
+<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 -->09-Sep-2010 20:30<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#modes">Association Modes</a></li>
+ <li class="inline"><a href="#client">Client/Server Mode</a></li>
+ <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="#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 and are demobilized by a "better" server or by timeout, but only if the number of survivors exceeds the threshold set by the <tt>tos maxclock</tt> command. 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="authopt.html">Authentication Options</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="manyopt.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">Configuration Options</a> page. See that page for applicability and defaults.</p>
+<h4 id="client">Client/Server Mode</h4>
+<p>Client/server mode is the most common configuration in the Internet today. It operates in the classic remote-procedure-call (RPC) paradigm with stateless servers and stateful clients. In this mode a host sends a client (mode 3) request to the specified server and expects a server (mode 4) reply at some future time. In some contexts this would be described as a "pull" operation, in that the host pulls the time and related values from the server.</p>
+<p>A host is configured in client mode using the <tt>server</tt> (sic) command and specifying the server DNS name or IPv4 or IPv6 address; the server requires no prior configuration. The <tt>iburst</tt> option described later on this page is recommended for clients, as this speeds up initial synchronization from several minutes to several seconds. The <tt>burst</tt> option described later on this page can be useful to reduce jitter on very noisy dial-up or ISDN network links.</p>
+<p>Ordinarily, the program automatically manages the poll interval between the default minimum and maximum values. The <tt>minpoll</tt> and <tt>maxpoll</tt> options can be used to bracket the range. Unless noted otherwise, these options should not be used with reference clock drivers.</p>
+<h4 id="symact">Symmetric Active/Passive Mode</h4>
+<p>Symmetric active/passive mode is intended for configurations were a clique
+ of low-stratum peers operate as mutual backups for each other. Each peer operates
+ with one or more primary reference sources, such as a reference clock, or a set
+ of secondary (stratum, 2) servers known to be reliable and authentic. Should
+ one of the peers lose all reference sources or simply cease operation, the
+ other peers will automatically reconfigure so that time and related values
+ can flow from the surviving peers to all hosts in the subnet. In some contexts
+ this would be described as a "push-pull" operation, in that the
+ peer either pulls or pushes the time and related values depending on the particular
+ configuration.</p>
+<p>A symmetric active peer sends a symmetric active (mode 1) message to a designated peer. If a matching configured symmetric active association is found, the designated peer returns a symmetric active message. If no matching association is found, the designated peer mobilizes a ephemeral symmetric passive association and returns a symmetric passive (mode 2) message. Since an intruder can impersonate a symmetric active peer and cause a spurious symmetric passive association to be mobilized, symmetric passive mode should always be cryptographically validated.</p>
+<p>A peer is configured in symmetric active mode using the <tt>peer</tt> command and specifying the other peer DNS name or IPv4 or IPv6 address. The <tt>burst</tt> and <tt>iburst</tt> options should not be used in symmetric modes, as this can upset the intended symmetry of the protocol and result in spurious duplicate or dropped messages.</p>
+<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="manyopt.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>
+<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 "best" 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="poll2">Poll Interval Control</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.</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 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 poll exponent. It is constrained by the lower limit <tt>minpoll</tt> and upper limit <tt>maxpoll</tt> options of the <tt>server</tt> command. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases. The default limits can be changed with these options to a minimum set by the <tt>average</tt> option of the <tt>discard</tt> command (see below) to a maximum of 17 (36 h).</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>
+</ul>
+<h4 id="burst2">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 <tt>server</tt> 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>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 poll interval and the minimum poll interval set by the <tt>minpoll</tt> option of the <a href="confopt.html#server"><tt>server</tt></a> command. For instance, with a 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 intervals of 9 (512 s) or more.</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
+ 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>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Reference Clock Audio Drivers</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Reference Clock Audio Drivers</h3>
- <img src="pic/radio2.jpg" alt="jpg" align="left">ICOM R-72 shortwave receiver and Sure audio mixer
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">00:48</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="308">Saturday, November 24, 2007</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#sound">Sound Card Drivers</a>
- <li class="inline"><a href="#short">Shortwave Radio Drivers</a>
- <li class="inline"><a href="#setup">Setup and Debugging Aids</a>
- </ul>
- <hr>
- <h4 id="sound">Sound Card Drivers</h4>
- <p>There are some applications in which the computer time can be disciplined to an audio signal, rather than a serial timecode and communications port or special purpose bus peripheral. This is useful in such cases where the audio signal is sent over a telephone circuit, for example, or received directly from a shortwave receiver. In such cases the audio signal can be connected via an ordinary sound card or baseboard audio codec. The suite of NTP reference clock drivers currently includes three drivers suitable for these applications. They include a driver for the Inter Range Instrumentation Group (IRIG) signals produced by many radio clocks and timing devices, another for the Canadian time/frequency radio station CHU and a third for the NIST time/frequency radio stations WWV and WWVH. The radio drivers are designed to work with ordinary inexpensive shortwave radios and may be one of the least expensive ways to build a good primary time server.</p>
- <p>All three drivers make ample use of sophisticated digital signal processing
- algorithms designed to efficiently extract timing signals from noise and interference.
- The radio station drivers in particular implement optimum linear demodulation
- and decoding techniques, including maximum-likelihood and soft-decision methods.
- The documentation page for each driver contains an in-depth discussion on
- the algorithms and performance expectations. In some cases the algorithms
- are further analyzed, modeled and evaluated in a technical report.</p>
- <p>Currently, the audio drivers work with with Sun operating systems and audio codecs, including SunOS 4.1.3 and Solaris from 2.6 and probably all others in between. They also work with FreeBSD from 4.1 with compatible sound card. In fact, the interface is quite generic and support for other systems, in particular the various Unix generics, should not be difficult. Volunteers are solicited.</p>
- <p>The audio drivers include a number of common features designed to groom input signals, suppress spikes and normalize signal levels. An automatic gain control (AGC) feature provides protection against overdriven or underdriven input signals. It is designed to maintain adequate demodulator signal amplitude while avoiding occasional noise spikes. In order to assure reliable operation, the signal level must be in the range where the audio gain control is effective. In general, this means the input signal level must be such as to cause the AGC to set the gain somewhere in the middle of the range from 0 to 255, as indicated in the timecode displayed by the <tt>ntpq</tt> program.</p>
- <p>The IRIG and WWV drivers operate by disciplining a logical clock based on the codec sample clock to the audio signal as received. This is done by stuffing or slipping samples as required to maintain exact frequency to the order of 0.1 PPM. In order for the driver to reliably lock on the audio signal, the sample clock frequency tolerance must be less than 250 PPM (.025 percent) for the IRIG driver and half that for the WWV driver. The largest error observed so far is about 60 PPM, but it is possible some sound cards or codecs may exceed that value. In any case, the configuration file command <tt>tinker codec</tt> command can be used to change the systematic offset in units of 125 PPM.</p>
- <p>The drivers include provisions to select the input port and to monitor the input signal. The <tt>fudge flag 2</tt> command selects the microphone port if set to zero or the line-in port if set to one. It does not seem useful to specify the compact disc player port. The <tt>fudge flag 3</tt> command enables the input signal monitor using the previously selected output port and output gain. Both of these flags can be set in the configuration file or remotely using the <tt>ntpdc</tt> utility program.</p>
- <h4 id="short">Shortwave Radio Drivers</h4>
- <p>The WWV/H and CHU audio drivers require an external shortwave radio with the radio output - speaker or headphone jack - connected to either the microphone or line-in port on the computer. There is some degree of art in setting up the radio and antenna and getting the setup to work. While the drivers are highly sophisticated and efficient in extracting timing signals from noise and interference, it always helps to have as clear a signal as possible.</p>
- <p>The most important factor affecting the radio signal is the antenna. It need not be long - even 15 feet is enough if it is located outside of a metal frame building, preferably on the roof, and away from metallic objects. An ordinary CB whip mounted on a PVC pipe and wooden X-frame on the roof should work well with most portable radios, as they are optimized for small antennas.</p>
- <p>The radio need not be located near the computer; in fact, it generally works better if the radio is outside the near field of computers and other electromagnetic noisemakers. It can be in the elevator penthouse connected by house wiring, which can also be used to power the radio. A couple of center-tapped audio transformers will minimize noise pickup and provide phantom power to the radio with return via the building ground.</p>
- <p>The WWV/H and CHU transmitters operate on several frequencies simultaneously, so that in most parts of North America at least one frequency supports propagation to the receiver location at any given hour. While both drivers support the ICOM CI-V radio interface and can tune the radio automatically, computer-tunable radios are expensive and probably not cost effective compared to a GPS receiver. So, the radio frequency must usually be fixed and chosen by compromise.</p>
- <p>Shortwave (3-30 MHz) radio propagation phenomena are well known to shortwave enthusiasts. The phenomena generally obey the following rules:</p>
- <ul>
- <li>The optimum frequency is higher in daytime than nighttime, stays high longer on summer days and low longer on winter nights.
- <li>Transitions between daytime and nighttime conditions generally occur somewhat
- after sunrise and sunset at the midpoint of the path from transmitter to
- receiver.
- <li>Ambient noise (static) on the lower frequencies follows the thunderstorm season, so is higher on summer afternoons and evenings.
- <li>The lower frequency bands are best for shorter distances, while the higher bands are best for longer distances.
- <li>The optimum frequencies are higher at the peak of the 11-year sunspot cycle and lower at the trough. The current sunspot cycle began at the minimum in late 2006 and should reach its peak in 2012.</ul>
- <p>The best way to choose a frequency is to listen at various times over the day and determine the highest (daytime) and lowest (nighttime) frequencies that work well. Choose the frequency that works for the most number of hours in the day, usually the highest frequency. For instance, on the east coast the best compromise CHU frequency is 7335 kHz and the best WWV frequency is 15 MHz.</p>
- <h4>Autotune Modes</h4>
- <p>The shortwave drivers include support for an optional autotune function compatible with ICOM receivers and transceivers. The <tt>mode</tt> keyword of the <tt>server</tt> configuration command specifies the ICOM ID select code in decimal. A missing or zero argument disables the CI-V interface. Since all ICOM select codes are less than 128, the high order bit of the code is used by the driver to specify the baud rate. If this bit is not set, the rate is 9600 bps for the newer radios; if set, the rate is 1200 bps for the older radios. Following are the ID select codes for the known radios.</p>
- <table width="100%" cols="6">
- <tr>
- <td>Radio</td>
- <td>Hex</td>
- <td>Decimal</td>
- <td>Radio</td>
- <td>Hex</td>
- <td>Decimal</td>
- </tr>
- <tr>
- <td>706</td>
- <td>0x4e</td>
- <td>78</td>
- <td>775</td>
- <td>0x46</td>
- <td>70</td>
- </tr>
- <tr>
- <td>706MKIIG</td>
- <td>0x58</td>
- <td>88</td>
- <td>781</td>
- <td>0x26</td>
- <td>38</td>
- </tr>
- <tr>
- <td>725</td>
- <td>0x28</td>
- <td>40</td>
- <td>970</td>
- <td>0x2e</td>
- <td>46</td>
- </tr>
- <tr>
- <td>726</td>
- <td>0x30</td>
- <td>48</td>
- <td>7000</td>
- <td>0x70</td>
- <td>113</td>
- </tr>
- <tr>
- <td>735</td>
- <td>0x04</td>
- <td>4</td>
- <td>R71</td>
- <td>0x1A</td>
- <td>26</td>
- </tr>
- <tr>
- <td>746</td>
- <td>0x66</td>
- <td>102</td>
- <td>R72</td>
- <td>0x32</td>
- <td>50</td>
- </tr>
- <tr>
- <td>751</td>
- <td>0x1c</td>
- <td>28</td>
- <td>R75</td>
- <td>0x5a</td>
- <td>90</td>
- </tr>
- <tr>
- <td>756PROII</td>
- <td>0x64</td>
- <td>100</td>
- <td>R7000</td>
- <td>0x08</td>
- <td>8</td>
- </tr>
- <tr>
- <td>761</td>
- <td>0x1e</td>
- <td>30</td>
- <td>R7100</td>
- <td>0x34</td>
- <td>52</td>
- </tr>
- <tr>
- <td>765</td>
- <td>0x2c</td>
- <td>44</td>
- <td>R8500</td>
- <td>0x4a</td>
- <td>74</td>
- </tr>
- <tr>
- <td></td>
- <td></td>
- <td></td>
- <td>R9000</td>
- <td>0x2a</td>
- <td>42</td>
- </tr>
- </table>
- <h4 id="setup">Setup and Debugging Aids</h4>
- <p>The audio drivers include extensive setup and debugging support to help hook up the audio signals and monitor the driver operations. The documentation page for each driver describes the various messages that can be produced either in real time or written to the <tt>clockstats</tt> file for later analysis. Of particular help in verifying signal connections and compatibility is a provision to monitor the signal via headphones or speaker.</p>
- <p>Connecting radios and IRIG devices to the computer and verifying correct
- configuration is somewhat of a black art. The signals have to be connected
- to the correct ports and the signal level maintained within tolerances. Some
- radios have recorder outputs which produce a microphone-level signal not affected
- by the volume control. These signals can be connected to the microphone port
- on the computer. If the radio does not have a recorder output, connect the
- headphone or speaker output to the line-in port and adjust the volume control
- so the driver indicates comfortably above the minimum specified and the AGC
- level somewhere in the middle of the range 0-255. IRIG signals are usually
- much larger than radio outputs, usually in the range to several volts and
- may even overload the line-in port. In such cases the signal is designed to
- drive a cable terminated with a 50-ohm resistor, which results in a level
- the line-in port can handle..</p>
- <p>It is very easy to underdriven or overdrive the audio codec, in which case
- the drivers will not synchronize to the signal. The drivers use <tt>fudge
- flag2</tt> to enable audio monitoring of the input signal. This is useful
- during setup to confirm the signal is actually reaching the audio
- codec and generally free of noise and interference. Note that the monitor
- volume must be set before the driver is started.</p>
- <p>The drivers write a synthesized timecode to the <tt>clockstats</tt> file each time the clock is set or verified and at other times if verbose monitoring is enabled. The format includes several fixed-length fields defining the UTC time to the millisecond, together with additional variable-length fields specific to each driver. The data include the intervals since the clock was last set or verified, the audio gain and various state variables and counters specific to each driver.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Reference Clock Audio Drivers</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Reference Clock Audio Drivers</h3>
+<img src="pic/radio2.jpg" alt="jpg" align="left">ICOM R-72 shortwave receiver and Sure audio mixer
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 1:45<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#sound">Sound Card Drivers</a></li>
+ <li class="inline"><a href="#short">Shortwave Radio Drivers</a></li>
+ <li class="inline"><a href="#setup">Setup and Debugging Aids</a></li>
+</ul>
+<hr>
+<h4 id="sound">Sound Card Drivers</h4>
+<p>There are some applications in which the computer time can be disciplined to an audio signal, rather than a serial timecode and communications port or special purpose bus peripheral. This is useful in such cases where the audio signal is sent over a telephone circuit, for example, or received directly from a shortwave receiver. In such cases the audio signal can be connected via an ordinary sound card or baseboard audio codec. The suite of NTP reference clock drivers currently includes three drivers suitable for these applications. They include a driver for the Inter Range Instrumentation Group (IRIG) signals produced by many radio clocks and timing devices, another for the Canadian time/frequency radio station CHU and a third for the NIST time/frequency radio stations WWV and WWVH. The radio drivers are designed to work with ordinary inexpensive shortwave radios and may be one of the least expensive ways to build a good primary time server.</p>
+<p>All three drivers make ample use of sophisticated digital signal processing
+ algorithms designed to efficiently extract timing signals from noise and interference.
+ The radio station drivers in particular implement optimum linear demodulation
+ and decoding techniques, including maximum-likelihood and soft-decision methods.
+ The documentation page for each driver contains an in-depth discussion on
+ the algorithms and performance expectations. In some cases the algorithms
+ are further analyzed, modeled and evaluated in a technical report.</p>
+<p>Currently, the audio drivers work with with Sun operating systems and audio codecs, including SunOS 4.1.3 and Solaris from 2.6 and probably all others in between. They also work with FreeBSD from 4.1 with compatible sound card. In fact, the interface is quite generic and support for other systems, in particular the various Unix generics, should not be difficult. Volunteers are solicited.</p>
+<p>The audio drivers include a number of common features designed to groom input signals, suppress spikes and normalize signal levels. An automatic gain control (AGC) feature provides protection against overdriven or underdriven input signals. It is designed to maintain adequate demodulator signal amplitude while avoiding occasional noise spikes. In order to assure reliable operation, the signal level must be in the range where the audio gain control is effective. In general, this means the input signal level must be such as to cause the AGC to set the gain somewhere in the middle of the range from 0 to 255, as indicated in the timecode displayed by the <tt>ntpq</tt> program.</p>
+<p>The IRIG and WWV drivers operate by disciplining a logical clock based on the codec sample clock to the audio signal as received. This is done by stuffing or slipping samples as required to maintain exact frequency to the order of 0.1 PPM. In order for the driver to reliably lock on the audio signal, the sample clock frequency tolerance must be less than 250 PPM (.025 percent) for the IRIG driver and half that for the WWV driver. The largest error observed so far is about 60 PPM, but it is possible some sound cards or codecs may exceed that value. In any case, the configuration file command <tt>tinker codec</tt> command can be used to change the systematic offset in units of 125 PPM.</p>
+<p>The drivers include provisions to select the input port and to monitor the input signal. The <tt>fudge flag 2</tt> command selects the microphone port if set to zero or the line-in port if set to one. It does not seem useful to specify the compact disc player port. The <tt>fudge flag 3</tt> command enables the input signal monitor using the previously selected output port and output gain. Both of these flags can be set in the configuration file or remotely using the <tt>ntpdc</tt> utility program.</p>
+<h4 id="short">Shortwave Radio Drivers</h4>
+<p>The WWV/H and CHU audio drivers require an external shortwave radio with the radio output - speaker or headphone jack - connected to either the microphone or line-in port on the computer. There is some degree of art in setting up the radio and antenna and getting the setup to work. While the drivers are highly sophisticated and efficient in extracting timing signals from noise and interference, it always helps to have as clear a signal as possible.</p>
+<p>The most important factor affecting the radio signal is the antenna. It need not be long - even 15 feet is enough if it is located outside of a metal frame building, preferably on the roof, and away from metallic objects. An ordinary CB whip mounted on a PVC pipe and wooden X-frame on the roof should work well with most portable radios, as they are optimized for small antennas.</p>
+<p>The radio need not be located near the computer; in fact, it generally works better if the radio is outside the near field of computers and other electromagnetic noisemakers. It can be in the elevator penthouse connected by house wiring, which can also be used to power the radio. A couple of center-tapped audio transformers will minimize noise pickup and provide phantom power to the radio with return via the building ground.</p>
+<p>The WWV/H and CHU transmitters operate on several frequencies simultaneously, so that in most parts of North America at least one frequency supports propagation to the receiver location at any given hour. While both drivers support the ICOM CI-V radio interface and can tune the radio automatically, computer-tunable radios are expensive and probably not cost effective compared to a GPS receiver. So, the radio frequency must usually be fixed and chosen by compromise.</p>
+<p>Shortwave (3-30 MHz) radio propagation phenomena are well known to shortwave enthusiasts. The phenomena generally obey the following rules:</p>
+<ul>
+ <li>The optimum frequency is higher in daytime than nighttime, stays high longer on summer days and low longer on winter nights.</li>
+ <li>Transitions between daytime and nighttime conditions generally occur somewhat
+ after sunrise and sunset at the midpoint of the path from transmitter to
+ receiver.</li>
+ <li>Ambient noise (static) on the lower frequencies follows the thunderstorm season, so is higher on summer afternoons and evenings.</li>
+ <li>The lower frequency bands are best for shorter distances, while the higher bands are best for longer distances.</li>
+ <li>The optimum frequencies are higher at the peak of the 11-year sunspot cycle and lower at the trough. The current sunspot cycle began at the minimum in late 2006 and should reach its peak in 2012.</li>
+</ul>
+<p>The best way to choose a frequency is to listen at various times over the day and determine the highest (daytime) and lowest (nighttime) frequencies that work well. Choose the frequency that works for the most number of hours in the day, usually the highest frequency. For instance, on the east coast the best compromise CHU frequency is 7335 kHz and the best WWV frequency is 15 MHz.</p>
+<h4>Autotune Modes</h4>
+<p>The shortwave drivers include support for an optional autotune function compatible with ICOM receivers and transceivers. The <tt>mode</tt> keyword of the <tt>server</tt> configuration command specifies the ICOM ID select code in decimal. A missing or zero argument disables the CI-V interface. Since all ICOM select codes are less than 128, the high order bit of the code is used by the driver to specify the baud rate. If this bit is not set, the rate is 9600 bps for the newer radios; if set, the rate is 1200 bps for the older radios. Following are the ID select codes for the known radios.</p>
+<table width="100%" cols="6">
+ <tr>
+ <td>Radio</td>
+ <td>Hex</td>
+ <td>Decimal</td>
+ <td>Radio</td>
+ <td>Hex</td>
+ <td>Decimal</td>
+ </tr>
+ <tr>
+ <td>706</td>
+ <td>0x4e</td>
+ <td>78</td>
+ <td>775</td>
+ <td>0x46</td>
+ <td>70</td>
+ </tr>
+ <tr>
+ <td>706MKIIG</td>
+ <td>0x58</td>
+ <td>88</td>
+ <td>781</td>
+ <td>0x26</td>
+ <td>38</td>
+ </tr>
+ <tr>
+ <td>725</td>
+ <td>0x28</td>
+ <td>40</td>
+ <td>970</td>
+ <td>0x2e</td>
+ <td>46</td>
+ </tr>
+ <tr>
+ <td>726</td>
+ <td>0x30</td>
+ <td>48</td>
+ <td>7000</td>
+ <td>0x70</td>
+ <td>113</td>
+ </tr>
+ <tr>
+ <td>735</td>
+ <td>0x04</td>
+ <td>4</td>
+ <td>R71</td>
+ <td>0x1A</td>
+ <td>26</td>
+ </tr>
+ <tr>
+ <td>746</td>
+ <td>0x66</td>
+ <td>102</td>
+ <td>R72</td>
+ <td>0x32</td>
+ <td>50</td>
+ </tr>
+ <tr>
+ <td>751</td>
+ <td>0x1c</td>
+ <td>28</td>
+ <td>R75</td>
+ <td>0x5a</td>
+ <td>90</td>
+ </tr>
+ <tr>
+ <td>756PROII</td>
+ <td>0x64</td>
+ <td>100</td>
+ <td>R7000</td>
+ <td>0x08</td>
+ <td>8</td>
+ </tr>
+ <tr>
+ <td>761</td>
+ <td>0x1e</td>
+ <td>30</td>
+ <td>R7100</td>
+ <td>0x34</td>
+ <td>52</td>
+ </tr>
+ <tr>
+ <td>765</td>
+ <td>0x2c</td>
+ <td>44</td>
+ <td>R8500</td>
+ <td>0x4a</td>
+ <td>74</td>
+ </tr>
+ <tr>
+ <td></td>
+ <td></td>
+ <td></td>
+ <td>R9000</td>
+ <td>0x2a</td>
+ <td>42</td>
+ </tr>
+</table>
+<h4 id="setup">Setup and Debugging Aids</h4>
+<p>The audio drivers include extensive setup and debugging support to help hook up the audio signals and monitor the driver operations. The documentation page for each driver describes the various messages that can be produced either in real time or written to the <tt>clockstats</tt> file for later analysis. Of particular help in verifying signal connections and compatibility is a provision to monitor the signal via headphones or speaker.</p>
+<p>Connecting radios and IRIG devices to the computer and verifying correct
+ configuration is somewhat of a black art. The signals have to be connected
+ to the correct ports and the signal level maintained within tolerances. Some
+ radios have recorder outputs which produce a microphone-level signal not affected
+ by the volume control. These signals can be connected to the microphone port
+ on the computer. If the radio does not have a recorder output, connect the
+ headphone or speaker output to the line-in port and adjust the volume control
+ so the driver indicates comfortably above the minimum specified and the AGC
+ level somewhere in the middle of the range 0-255. IRIG signals are usually
+ much larger than radio outputs, usually in the range to several volts and
+ may even overload the line-in port. In such cases the signal is designed to
+ drive a cable terminated with a 50-ohm resistor, which results in a level
+ the line-in port can handle..</p>
+<p>It is very easy to underdriven or overdrive the audio codec, in which case
+ the drivers will not synchronize to the signal. The drivers use <tt>fudge
+ flag2</tt> to enable audio monitoring of the input signal. This is useful
+ during setup to confirm the signal is actually reaching the audio
+ codec and generally free of noise and interference. Note that the monitor
+ volume must be set before the driver is started.</p>
+<p>The drivers write a synthesized timecode to the <tt>clockstats</tt> file each time the clock is set or verified and at other times if verbose monitoring is enabled. The format includes several fixed-length fields defining the UTC time to the millisecond, together with additional variable-length fields specific to each driver. The data include the intervals since the clock was last set or verified, the audio gain and various state variables and counters specific to each driver.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Authentication Support</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+<style type="text/css">
+<!--
+<style1 {
+color: #FF0000;
+ font-weight: bold;
+}
+-->
+</style>
+</head>
+<body>
+<h3>Authentication Support</h3>
+<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 -->09-Sep-2010 16:39<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/authopt.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#auth">Introduction</a></li>
+ <li class="inline"><a href="#symm">Symmetric Key Cryptography</a></li>
+ <li class="inline"><a href="#pub">Public Key Cryptography</a></li>
+</ul>
+<hr>
+<h4 id="auth">Introduction</h4>
+<p>This page describes the various cryptographic authentication provisions in NTPv4. Authentication support allows the NTP client to verify that servers are in fact known and trusted and not intruders intending accidentally or intentionally to masquerade as a legitimate server.</p>
+<p> The NTPv3 specification RFC-1305 defines a scheme properly described as symmetric key cryptography. It uses the Data Encryption Standard (DES) algorithm operating in cipher-block chaining (CBC) mode. Subsequently, this algorithm was replaced by the RSA Message Digest 5 (MD5) algorithm commonly called keyed-MD5. Either algorithm computes a message digest or one-way hash which can be used to verify the client has the same key and key identifier as the server. If the OpenSSL cryptographic library is installed, support is available for all message digest algorithms included in the library. Note however, if conformance to FIPS 140-2 is required, only a limited subset of these algorithms is available.</p>
+<p>NTPv4 includes the symmetric key scheme and iin addition a new scheme based on public key cryptography and called Autokey. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on private and public values which are generated by each participant and where the private value is never revealed. Autokey uses X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library or the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program in the NTP software distribution.</p>
+<p>While the algorithms for MD5 symmetric key cryptography are included in the NTPv4 software distribution, modern algorithms for symmetric key and public key cryptograpny requires the OpenSSL software library to be installed before building the NTP distribution. This library is available from <a href="http://www.openssl.org">http://www.openssl.org</a> and can be installed using the procedures outlined in the <a href="build.html">Building and Installing the Distribution</a> page. Once installed, the configure and build process automatically detects the library and links the library routines
+ required.</p>
+<p>Note that according to US law, NTP binaries including OpenSSL library components, including the OpenSSL library itself, cannot be exported outside the US without license from the US Department of Commerce. Builders outside the US are advised to obtain the OpenSSL library directly from OpenSSL, which is outside the US, and build outside the US.</p>
+<p>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> option of the <tt>server</tt> configuration command, as described in the <a href="confopt.html">Server Options</a> page, and the options described on this page. The <a href="keygen.html">ntp-keygen</a> page describes the files required for the various authentication schemes. Further details are in the briefings, papers and reports at the NTP project page linked from <a href="http://www.ntp.org">www.ntp.org</a>.</p>
+<h4 id="symm">Symmetric Key Cryptography</h4>
+<p>The original RFC-1305 specification allows any one of possibly 65,534 keys (excluding zero), each distinguished by a 32-bit key ID, to authenticate an association. The servers and clients involved must agree on the key, key ID and key type to authenticate NTP packets. If an NTP packet includes a message authentication code (MAC), consisting of a key ID and message digest, it is accepted only if the key ID matches a trusted key and the message digest is verified with this key. Note that for historic reasons the message digest algorithm is not consistent with RFC-1828. The digest is computed directly from the concatenation of the key string followed by the packet contents with the exception of the MAC itself.</p>
+<p>Keys and related information are specified in a keys file, usually called <tt>ntp.keys</tt>, which must be distributed and stored using secure means beyond the scope of the NTP protocol itself. Besides the keys used for ordinary NTP associations, additional keys can be used as passwords for the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs. Ordinarily, the <tt>ntp.keys</tt> file is generated by the <tt><a href="keygen.html">ntp-keygen</a></tt> program, but it can be constructed and edited using an ordinary text editor. The program generates pseudo-random keys, one key for each line. Each line consists of three fields, the key identifier as a decimal number from 1 to 65534 inclusive, a key type chosen from the keywords of the <tt>digest</tt> option of the <tt>crypto</tt> command, and a 20-character printable ASCII string or a 40-character hex string as the key itself.</p>
+<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>By default, the message digest algorithm is MD5 selected by the key type <tt>M</tt> in the keys file. However, if the OpenSSL library is installed, any message digest algorithm supported by that library can be used. The key type is selected as the algorithm name given in the OpenSSL documentation. The key type is associated with the key and can be different for different keys. The server and client must share the same key, key ID and key type and both must be trusted. Note that if conformance to FIPS 140-2 is required, the message digest algorithm must conform to the Secure Hash Standard (SHS), which requires an algorithm from the Secure Hash Algorithm (SHA) family, and the digital signature encryption algorithm, if used, must conform to the Digital Signature Standard (DSS), which requires the Digital Signature Algorithm (DSA).</p>
+<p>In addition to the above means, <tt>ntpd</tt> now supports Microsoft Windows MS-SNTP authentication using Active Directory services. This support was contributed by the Samba Team and is still in development. It is enabled using the <tt>mssntp</tt> flag of the <tt>restrict</tt> command described on the <a href="authopt.html">Access Control Options</a> page. <span class="style1">Note: Potential users should be aware that these services involve a TCP connection to another process that could potentially block, denying services to other users. Therefore, this flag should be used only for a dedicated server with no clients other than MS-SNTP.</span></p>
+<h4 id="pub">Public Key Cryptography</h4>
+<p>See the <a href="autokey.html">Autokey Public-Key Authentication</a> page.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
-<title>Authentication Options</title>
+<title>Authentication Commands and Options</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
<style type="text/css">
-<!--
-.style1 { color: #FF0000;
- font-weight: bold;
+<style1 {
+color: #FF0000;
+ font-weight: bold;
}
--->
</style>
</head>
-
<body>
-<h3>Authentication Options</h3>
+<h3>Authentication Commands and Options</h3>
<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 -->14-Apr-2010 20:49<!-- #EndDate -->
-UTC</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->10-Sep-2010 0:05<!-- #EndDate -->
+ UTC</p>
<br clear="left">
-
<h4>Related Links</h4>
-
<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
<script type="text/javascript" language="javascript" src="scripts/authopt.txt"></script>
-
-<h4>Table of Contents</h4>
-
-<ul>
-<li class="inline"><a href="#auth">Introduction</a></li>
-<li class="inline"><a href="#symm">Symmetric Key Cryptography</a></li>
-<li class="inline"><a href="#pub">Public Key Cryptography</a></li>
-<li class="inline"><a href="#group">NTP Secure Groups</a></li>
-<li class="inline"><a href="#ident">Identity Schemes and Cryptotypes</a></li>
-<li class="inline"><a href="#cfg">Configuration</a></li>
-<li class="inline"><a href="#exam">Examples</a></li>
-<li class="inline"><a href="#cmd">Authentication Commands</a></li>
-<li class="inline"><a href="#err">Error Codes</a></li>
-<li class="inline"><a href="#file">Files</a></li>
-</ul>
-
-<hr>
-
-<h4 id="auth">Introduction</h4>
-
-<p>This page describes the various cryptographic authentication provisions in
- NTPv4. Details about the configuration commands and options are given on
- the <a href="confopt.html">Configuration
- Options</a> page. Details about the automatic server discovery schemes are described
- on the <a href="manyopt.html">Automatic Server Discovery Schemes</a> page. Additional
- information is available in the papers, reports, memoranda and briefings
- cited on the <a href="http://www.eecis.udel.edu/~mills/ntp.html"> NTP Project</a> page.
- Authentication support allows the NTP client to verify that servers are in
- fact known and trusted and not intruders intending accidentally or intentionally
- to masquerade as a legitimate server.</p>
-
-<p> The NTPv3 specification RFC-1305 defines a scheme properly described as
- symmetric key cryptography. It uses the Data Encryption Standard (DES)
- algorithm operating in cipher-block chaining (CBC) mode. Subsequently, this
- scheme was replaced by the RSA Message Digest 5 (MD5) algorithm commonly
- called keyed-MD5. Either algorithm computes a message digest or one-way hash
- which can be used to verify the client has the same key and key identifier
- as the server. If the OpenSSL cryptographic library is installed, support
- is available for all algorithms included in the library. Note however, if
- conformance to FIPS 140-2 is required, only a limited subset of these algorithms
- is available.</p>
-
-<p>NTPv4 includes the NTPv3 scheme
- and optionally a new scheme based on public key cryptography and called
- Autokey. Public key cryptography is generally considered more secure than
- symmetric key cryptography, since the security is based on private and public
- values which are generated by each participant and where the private value
- is never revealed. Autokey uses X.509 public certificates, which can be produced
- by commercial services, utility programs in the OpenSSL software library
- or the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility
- program in the NTP software distribution.</p>
-
-<p>While the algorithms for MD5 symmetric key cryptography are included in the
- NTPv4 software distribution, modern algorithms for symmetric key and public
- key cryptograpny requires the OpenSSL software library
- to be installed before building the NTP distribution. This library is available
- from <a href="http://www.openssl.org">http://www.openssl.org</a> and
- can be installed using the procedures outlined in the <a href="build.html">Building
- and Installing the Distribution</a> page. Once installed, the configure and
- build process automatically detects the library and links the library routines
- required.</p>
-
-<p>Note that according to US law, NTP binaries including OpenSSL library components,
- including the OpenSSL library itself, cannot be exported outside the
- US without license from the US Department of Commerce. Builders outside the
- US are advised to obtain the OpenSSL library directly from OpenSSL, which
- is outside the US, and build outside the US.</p>
-
-<p>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> option of the <tt>server</tt> configuration command, as described in the <a href="confopt.html">Server Options</a> page, and the options described on this page. The <a href="keygen.html">ntp-keygen</a> page describes the files required for the various authentication schemes. Further details are in the briefings, papers and reports at the NTP project page linked from <a href="http://www.ntp.org">www.ntp.org</a>.</p>
-
-<h4 id="symm">Symmetric Key Cryptography</h4>
-
-<p>The original RFC-1305 specification allows any one of possibly 65,534 keys
- (excluding zero), each distinguished by a 32-bit key ID, to authenticate
- an association. The servers and clients involved must agree on the key, key
- ID and key type to authenticate NTP packets. If an NTP packet includes a
- message authentication code (MAC), consisting of a key ID and message digest,
- it is accepted only if the key ID matches a trusted key and the message digest
- is verified with this key. Note that for historic reasons the message digest
- algorithm is not consistent with RFC-1828. The digest is computed directly
- from the concatenation of the key string followed by the packet contents
- with the exception of the MAC itself.</p>
-
-<p>Keys and related information are specified in a keys file, usually called <tt>ntp.keys</tt>,
- which must be distributed and stored using secure means beyond the scope
- of the NTP protocol itself. Besides the keys used for ordinary NTP associations,
- additional keys can be used as passwords for the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility
- programs. Ordinarily, the <tt>ntp.keys</tt> file is generated by the <tt><a href="keygen.html">ntp-keygen</a></tt> program,
- but it can be constructed and edited using an ordinary text editor. The
- program generates pseudo-random keys, one key for each line. Each line consists
- of three fields, the key identifier as a decimal number from 1 to 65534 inclusive,
- a key type chosen from the keywords of the <tt>digest</tt> option of the <tt>crypto</tt> command,
- and a 20-character printable ASCII string or a 40-character hex string as
- the key itself.</p>
-
-<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>By default, the message digest algorithm is MD5 selected by the key type
- <tt>M</tt> in the keys file. However, if the OpenSSL library is installed,
- any message digest algorithm supported by that library can be used. The key
- type is selected as the algorithm name given in the OpenSSL documentation.
- The key type is associated with the key and can be different for different
- keys. The server and client
- must share the same key, key ID and key type and both must be trusted. Note
- that if conformance to FIPS 140-2 is required, the message digest algorithm
- must conform to the Secure Hash Standard (SHS), which requires an algorithm
- from the Secure Hash Algorithm (SHA) family, and the digital signature encryption
- algorithm, if used, must conform to the Digital Signature Standard (DSS),
- which requires the Digital Signature Algorithm (DSA).</p>
-<p>In addition to the above means, <tt>ntpd</tt> now supports
- Microsoft Windows MS-SNTP authentication using Active Directory services.
- This support was contributed by the Samba Team and is still in development.
- It is enabled using the <tt>mssntp</tt> flag
- of the <tt>restrict</tt> command described on
- the <a href="authopt.html">Access Control Options</a> page. <span class="style1">Note:
- Potential users should be aware that these services involve a TCP connection
- to another process that could potentially block, denying services to other
- users. Therefore, this flag should be used only for a dedicated server with
- no clients other than MS-SNTP.</span></p>
-<h4 id="pub">Public Key Cryptography</h4>
-
-<p>NTPv4 supports the Autokey security protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/%7emills/proto.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page are based on cryptographic challenge/response exchanges. These schemes provide strong security against replay with or without message modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/~mills/autokey.html">Autonomous Authentication</a> page.</p>
-
-<p>Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.</p>
-
-<p>There are three timeouts associated with the Autokey scheme. The key list timeout, which defaults to about 1.1 h, specifies the interval between generating new key lists. The revoke timeout, which defaults to about 36 h, specifies the interval between generating new private values. The restart timeout, with default about 5 d, specifies the interval between protocol restarts to refresh public values. In general, the behavior when these timeouts expire is not affected by the issues discussed on this page.</p>
-
-<h4 id="group">NTP Secure Groups</h4>
-
-<p>NTP secure groups are used to define cryptographic compartments and security
- hierarchies. All hosts belonging to a secure group have the same group name
- but different host names. The string specified in the <tt>host</tt> option of
- the <tt>crypto</tt> command is the name of the host and the name used in the
- host key, sign key and certificate files. The string specified in the <tt>ident</tt> option
- of the <tt>crypto</tt> command is the group name of all group hosts and the
- name used in the identity files. The file naming conventions are described on
- the <a href="keygen.html">ntp-keygen</a> page.</p>
-
-<p>Each group includes one or more trusted hosts (THs) operating at the root, or lowest stratum in the group. The group name is used in the subject and issuer fields of the TH self-signed trusted certificate for these hosts. The host name is used in the subject and issuer fields of the self-signed certificates for all other hosts.</p>
-
-<p>All group hosts are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts and ending at a TH. When a host starts up, it recursively retrieves the certificates along the trail in order to verify group membership and avoid masquerade and middleman attacks.</p>
-
-<p>Secure groups can be configured as hierarchies where a TH of one group can be a client of one or more other groups operating at a lower stratum. A certificate trail consist of a chain of hosts starting at a client, leading through secondary servers of progressively lower stratum and ending at a TH. In one scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.</p>
-
-<h4 id="ident">Identity Schemes and Cryptotypes</h4>
-
-<p>All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three identity schemes, IFF, GQ and MV described on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page.</p>
-
-<p>A specific combination of authentication and identity schemes is called a
- cryptotype, which applies to clients and servers separately. A group can be
- configured using more than one cryptotype combination, although not all combinations
- are interoperable. Note however that some cryptotype combinations may successfully
- intemperate with each other, but may not represent good security practice. The
- server and client cryptotypes are defined by the the following codes.</p>
-
-<dl>
-<dt>NONE</dt>
-<dd>A client or server is type NONE if authentication is not available or not configured. Packets exchanged between client and server have no MAC.</dd>
-
-<dt>AUTH</dt>
-<dd>A client or server is type AUTH if the <tt>key</tt> option is specified with the <tt>server</tt> configuration command and the client and server keys are compatible. Packets exchanged between clients and servers have a MAC.</dd>
-
-<dt>PC</dt>
-<dd>A client or server is type PC if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key and private certificate files are present. Packets exchanged between clients and servers have a MAC.</dd>
-
-<dt>TC</dt>
-<dd>A client or server is type TC if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key and public certificate files are present. Packets exchanged between clients and servers have a MAC.</dd>
-
-<dt>IDENT</dt>
- <dd>A client or server is type IDENT if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key, public certificate and identity scheme files are present. Packets exchanged between clients and servers have a MAC.</dd>
-
-</dl>
-
-<p>The compatible cryptotypes for clients and servers are listed in the following table.</p>
-
-<table width="100%" border="1" cellpadding="4">
-
-<tr>
-<td rowspan="2" align="center">Client</td>
-<td colspan="5" align="center">Server</td>
-</tr>
-
-<tr>
-<td align="center">NONE</td>
-<td align="center">AUTH</td>
-<td align="center">PC</td>
-<td align="center">TC</td>
-<td align="center">IDENT</td>
-</tr>
-
-<tr>
-<td align="center">NONE</td>
-<td align="center">yes</td>
-<td align="center">yes*</td>
-<td align="center">yes*</td>
-<td align="center">yes*</td>
-<td align="center">yes*</td>
-</tr>
-
-<tr>
-<td align="center">AUTH</td>
-<td align="center">no</td>
-<td align="center">yes</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">no</td>
-</tr>
-
-<tr>
-<td align="center">PC</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">yes</td>
-<td align="center">no</td>
-<td align="center">no</td>
-</tr>
-
-<tr>
-<td align="center">TC</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">yes</td>
-<td align="center">yes</td>
-</tr>
-
-<tr>
-<td align="center">IDENT</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">no</td>
-<td align="center">yes</td>
-</tr>
-
-</table>
-
-<p>* These combinations are not valid if the restriction list includes the <tt>notrust</tt> option.</p>
-
-<h4 id="cfg">Configuration</h4>
-
-<p>Autokey has an intimidating number of configuration options, most of which are not necessary in typical scenarios. The simplest scenario consists of a TH where the host name of the TH is also the name of the group. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the <tt>ntp-keygen -T</tt> command, while the remaining group hosts use the same command with no options to generate the host key and public certificate files. All hosts use the <tt>crypto</tt> configuration command with no options. Configuration with passwords is described in the <a href="keygen.html">ntp-keygen</a> page. All group hosts are configured as an acyclic tree with root the TH.</p>
-
-<p>When an identity scheme is included, for example IFF, the TH generates host
- key, trusted certificate and private server identity key files using the <tt>ntp-keygen
- -T -I -i <i>group</i></tt> command, where <tt><i>group</i></tt> is the group
- name. The remaining group hosts use the same command as above. All hosts
- use the <tt>crypto ident group<i></i></tt> configuration command.</p>
-
-<p>Hosts with no dependent clients can retrieve client parameter files from an
- archive or web page. The <tt>ntp-keygen</tt> can export these data using the <tt>-e</tt> option.
- Hosts with dependent clients other than the TH must retrieve copies of the server
- key files using secure means. The <tt>ntp-keygen</tt> can export these data
- using the <tt>-q</tt> option. In either case the data are installed as a file
- and then renamed using the name given as the first line in the file, but without
- the filestamp.</p>
-
-<h4 id="exam">Examples</h4>
-
-<div align="center">
-<img src="pic/group.gif" alt="gif">
-</div>
-
-<p>Consider a scenario involving three secure groups RED, GREEN and BLUE. RED and BLUE are typical of national laboratories providing certified time to the Internet at large. As shown ion the figure, RED TH mort and BLUE TH macabre run NTP symmetric mode with each other for monitoring or backup. For the purpose of illustration, assume both THs are primary servers. GREEN is typical of a large university providing certified time to the campus community. GREEN TH howland is a broadcast client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys. YELLOW is a client of GREEN and for purposes of illustration a TH for YELLOW.</p>
-
-<p>The BLUE TH macabre uses configuration commands</p>
-
-<p><tt>crypto pw qqsv ident blue</tt><br>
-<tt>peer mort autokey</tt><br>
-<tt>broadcast <i>address</i> autokey</tt></p>
-
-<p>where <tt>qqsv</tt> is the password for macabre files and <i>address</i> is the broadcast address for the local LAN. It generates BLUE files using the commands</p>
-
-<p><tt>ntp-keygen -p qqsv -T -G -i blue</tt><br>
-<tt>ntp-keygen -p qqsv -e >ntpkey_gqpar_blue</tt></p>
-
-<p>The first line generates the host, trusted certificate and private GQ server keys file. The second generates the public GQ client parameters file, which can have any nonconflicting mnemonic name.</p>
-
-<p>The RED TH mort uses configuration commands</p>
-
-<p><tt>crypto pw xxx ident red</tt><br>
-<tt>peer macabre autokey</tt><br>
-<tt>broadcast <i>address</i> autokey</tt></p>
-
-<p>where <tt>xxx</tt> is the password for mort files. It generates RED files using the commands</p>
-
-<p><tt>ntp-keygen -p xxx -T -I -i red</tt><br>
-<tt>ntp-keygen -p xxx -e >ntpkey_iffpar_red</tt></p>
-
-<p> The GREEN TH howland uses configuration commands</p>
-
-<p><tt>crypto pw yyy ident green</tt><br>
-<tt>broadcastclient</tt></p>
-
-<p>where <tt>yyy</tt> is the password for howland files. It generates GREEN files using the commands</p>
-
-<p><tt>ntp-keygen -p yyy -T -G -i green</tt><br>
-<tt>ntp-keygen -p yyy -e >ntpkey_gqpar_green</tt><br>
-<tt>ntp-keygen -p yyy -q zzz >zzz_ntpkey_gqkey_green</tt></p>
-
-<p>The first two lines serve the same purpose as the preceding examples. The
- third line generates a copy of the private GREEN server file for use on another
- server in the same group, say YELLOW, but encrypted with the <tt>zzz</tt> password.</p>
-
-<p>A client of GREEN, for example YELLOW, uses the configuration commands</p>
-
-<p><tt>crypto pw abc ident green</tt><br>
-<tt>server howland autokey</tt></p>
-
-<p>where <tt>abc</tt> is the password for its files. It generates files using the command</p>
-
-<p><tt>ntp-keygen -p abc</tt></p>
-
-<p>The client retrieves the client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server keys file from the TH of that group, but it is encrypted and so must be sent using secure means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.</p>
-
-<p>Note that if servers of different groups, in this case RED and BLUE, share the same broadcast media, each server must have client files for all groups other than its own, while each client must have client files for all groups. Note also that this scenario is for illustration only and probably would not be wise for practical use, as if one of the TH reference clocks fails, the certificate trail becomes cyclic. In such cases the symmetric path between RED and BLUE, each in a different group, would not be a good idea.</p>
-
-<h4 id="cmd">Authentication Commands</h4>
-
+<h4>Commands and Options</h4>
+<p>Unless noted otherwise, further information about these commands is on the <a href="authentic.html">Authentication Support</a> page.</p>
<dl>
-
-<dt id=automax><tt>automax [<i>logsec</i>]</tt></dt>
-<dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent.</dd>
-
-<dt id="controlkey"><tt>controlkey <i>keyid</i></tt></dt>
-<dd>Specifies the key ID to use with the <a
+ <dt id=automax><tt>automax [<i>logsec</i>]</tt></dt>
+ <dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent. See the <a href="autokeyk.html">Autokey Public Key Authentication</a> page for further information.</dd>
+ <dt id="controlkey"><tt>controlkey <i>keyid</i></tt></dt>
+ <dd>Specifies the key ID to use with the <a
href="ntpq.html"><tt>ntpq</tt></a> utility, which uses the
- standard protocol defined in RFC-1305. The <tt><i>keyid</i></tt>
- argument is the key ID for a <a href="#trustedkey">trusted
- key</a>, where the value can be in the range 1 to 65534,
- inclusive.</dd>
-
-<dt id="crypto"><tt>crypto [randfile <i>file</i>] [host <i>name</i>] [ident <i>name</i>] [pw <i>password</i>]</tt></dt>
-<dd>This command requires the OpenSSL library. It activates public key cryptography
- and loads the required host key and public certificate. If one or more files
- are left unspecified, the default names are used as described below. Unless
- the complete path and name of the file are specified, the location of a file
- is relative to the keys directory specified in the <tt>keysdir</tt> configuration
- command or default <tt>/usr/local/etc</tt>. Following are the options.</dd>
-
-<dd><dl>
-
-<dt><tt>digest</tt> <tt>MD2</tt> | <tt>MD4</tt> | <tt>MD5</tt> | <tt>MDC2</tt> | <tt>RIPEMD160</tt> | <tt>SHA</tt> | <tt>SHA1</tt></dt>
-<dd>Specify the message digest algorithm, with default MD5. If the OpenSSL library
- is installed, <tt><i>name</i></tt> can be be any message digest algorithm supported
- by the library not exceeding 160 bits in length. However, all Autokey
- participants in an Autokey subnet must use the same algorithm. Note that
- the Autokey message digest algorithm is separate and distinct form the symmetric
- key message digest algorithms. Note: If compliance with FIPS 140-2 is required,
- the algorithm must be ether <tt>SHA</tt> or <tt>SHA1</tt>.</dd>
-
-<dt><tt>host <i>name</i></tt></dt>
-<dd>Specifies the string used when constructing the names for the host, sign
- and certificate files generated by the <tt>ntp-keygen</tt> program with the <tt>-s <i>name</i></tt> option.</dd>
-
-<dt><tt>ident <i>name</i></tt></dt>
-<dd>Specifies the string used in constructing the identity files generated by the <tt>ntp-keygen</tt> program with the <tt>-i <i>name</i></tt> option.</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.</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>
-
-</dl></dd>
-
-<dt id="keys"><tt>keys <i>keyfile</i></tt></dt>
-<dd>Specifies the complete path to the MD5 key file containing the keys and key IDs 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 media is specified by the <tt>keysdir</tt> command.</dd>
-
-<dt id="keysdir"><tt>keysdir <i>path</i></tt>K</dt>
-<dd>This command specifies the default directory path for 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>
-<dd>Specifies the key ID to use with the
- <a href="ntpdc.html"><tt>ntpdc</tt></a> utility program, which
- uses a proprietary protocol specific to this implementation of
- <tt>ntpd</tt>. The <tt><i>keyid</i></tt> argument is a key ID
- for a <a href="#trustedkey">trusted key</a>, in the range 1 to
- 65534, inclusive.</dd>
-
-<dt id="revoke"><tt>revoke [<i>logsec</i>]</tt></dt>
-<dd>Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms; however, updating some values is a relatively expensive operation. The default interval is 17 (about 36 h). For poll intervals above the specified interval, the values will be updated for every message sent.</dd>
-
-<dt id="trustedkey"><tt>trustedkey [<i>keyid</i> | (<i>lowid</i> ... <i>highid</i>)] [...]</tt></dt>
-<dd>Specifies the key ID(s) which are trusted for the purposes of
- 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
- 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
- lowest 120 key IDs which start with the digit 1. The spaces
- surrounding the ellipsis are required when specifying a range.</dd>
+ standard protocol defined in RFC-1305. The <tt><i>keyid</i></tt> argument is the key ID for a <a href="#trustedkey">trusted
+ key</a>, where the value can be in the range 1 to 65534,
+ inclusive.</dd>
+ <dt id="crypto"><tt>crypto [randfile <i>file</i>] [host <i>name</i>] [ident <i>name</i>] [pw <i>password</i>]</tt></dt>
+ <dd>This command requires the OpenSSL library. It activates public key cryptography
+ and loads the required host key and public certificate. If one or more files
+ are left unspecified, the default names are used as described below. Unless
+ the complete path and name of the file are specified, the location of a file
+ is relative to the keys directory specified in the <tt>keysdir</tt> configuration
+ command or default <tt>/usr/local/etc</tt>. See the <a href="autokeyk.html">Autokey Public Key Authentication</a> page for further information. Following are the options.</dd>
+ <dd>
+ <dl>
+ <dt><tt>digest</tt> <tt>MD2</tt> | <tt>MD4</tt> | <tt>MD5</tt> | <tt>MDC2</tt> | <tt>RIPEMD160</tt> | <tt>SHA</tt> | <tt>SHA1</tt></dt>
+ <dd>Specify the message digest algorithm, with default MD5. If the OpenSSL library
+ is installed, <tt><i>name</i></tt> can be be any message digest algorithm supported
+ by the library not exceeding 160 bits in length. However, all Autokey
+ participants in an Autokey subnet must use the same algorithm. Note that
+ the Autokey message digest algorithm is separate and distinct form the symmetric
+ key message digest algorithms. Note: If compliance with FIPS 140-2 is required,
+ the algorithm must be ether <tt>SHA</tt> or <tt>SHA1</tt>.</dd>
+ <dt><tt>host <i>name</i></tt></dt>
+ <dd>Specifies the string used when constructing the names for the host, sign
+ and certificate files generated by the <tt>ntp-keygen</tt> program with the <tt>-s <i>name</i></tt> option.</dd>
+ <dt><tt>ident <i>name</i></tt></dt>
+ <dd>Specifies the string used in constructing the identity files generated by the <tt>ntp-keygen</tt> program with the <tt>-i <i>name</i></tt> option.</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.</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>
+ </dl>
+ </dd>
+ <dt id="keys"><tt>keys <i>keyfile</i></tt></dt>
+ <dd>Specifies the complete path to the MD5 key file containing the keys and key IDs 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 media is specified by the <tt>keysdir</tt> command.</dd>
+ <dt id="keysdir"><tt>keysdir <i>path</i></tt>K</dt>
+ <dd>This command specifies the default directory path for 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>
+ <dd>Specifies the key ID to use with the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility program, which
+ uses a proprietary protocol specific to this implementation of <tt>ntpd</tt>. The <tt><i>keyid</i></tt> argument is a key ID
+ for a <a href="#trustedkey">trusted key</a>, in the range 1 to
+ 65534, inclusive.</dd>
+ <dt id="revoke"><tt>revoke [<i>logsec</i>]</tt></dt>
+ <dd>Specifies the interval between re-randomization of certain cryptographic values used by the Autokey scheme, as a power of 2 in seconds. These values need to be updated frequently in order to deflect brute-force attacks on the algorithms; however, updating some values is a relatively expensive operation. The default interval is 17 (about 36 h). For poll intervals above the specified interval, the values will be updated for every message sent.</dd>
+ <dt id="trustedkey"><tt>trustedkey [<i>keyid</i> | (<i>lowid</i> ... <i>highid</i>)] [...]</tt></dt>
+ <dd>Specifies the key ID(s) which are trusted for the purposes of
+ 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
+ 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
+ lowest 120 key IDs which start with the digit 1. The spaces
+ surrounding the ellipsis are required when specifying a range.</dd>
</dl>
-
-<h4 id="err">Error Codes</h4>
-
-<p>Errors can occur due to mismatched configurations, unexpected protocol restarts, expired certificates and unfriendly people. In most cases the protocol state machine recovers automatically by retransmission, timeout and restart, where necessary. Some errors are due to mismatched keys, digest schemes or identity schemes and must be corrected by installing the correct media and/or correcting the configuration file. One of the most common errors is expired certificates, which must be regenerated and signed at least once per year using the <a href="keygen.html"><tt>ntp-keygen</tt> - generate public and private keys</a> program.</p>
-
-<p>The following error codes are reported via the NTP control and monitoring protocol trap mechanism and to the <tt>cryptostats</tt> monitoring file if configured.</p>
-
-<dl>
-
-<dt>101 bad field format or length</dt>
-<dd>The packet has invalid version, length or format.</dd>
-
-<dt>102 bad timestamp</dt>
-<dd>The packet timestamp is the same or older than the most recent received. This could be due to a replay or a server clock time step.</dd>
-
-<dt>103 bad filestamp</dt>
-<dd>The packet filestamp is the same or older than the most recent received. This could be due to a replay or a key file generation error.</dd>
-
-<dt>104 bad or missing public key</dt>
-<dd>The public key is missing, has incorrect format or is an unsupported type.</dd>
-
-<dt>105 unsupported digest type</dt>
-<dd>The server requires an unsupported digest/signature scheme.</dd>
-
-<dt>106 unsupported identity type</dt>
-<dd>The client or server has requested an identity scheme the other does not support.</dd>
-
-<dt>107 bad signature length</dt>
-<dd>The signature length does not match the current public key.</dd>
-
-<dt>108 signature not verified</dt>
-<dd>The message fails the signature check. It could be bogus or signed by a different private key.</dd>
-
-<dt>109 certificate not verified</dt>
-<dd>The certificate is invalid or signed with the wrong key.</dd>
-
-<dt>110 host certificate expired</dt>
-<dd>The old server certificate has expired.</dd>
-
-<dt>111 bad or missing cookie</dt>
-<dd>The cookie is missing, corrupted or bogus.</dd>
-
-<dt>112 bad or missing leapseconds table</dt>
-<dd>The leapseconds table is missing, corrupted or bogus.</dd>
-
-<dt>113 bad or missing certificate</dt>
-<dd>The certificate is missing, corrupted or bogus.</dd>
-
-<dt>114 bad or missing group key</dt>
-<dd>The identity key is missing, corrupt or bogus.</dd>
-
-<dt>115 protocol error</dt>
-<dd>The protocol state machine has wedged due to unexpected restart.</dd>
-
</dl>
-
-<h4 id="file">Files</h4>
-
-<p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page. Note that provisions to load leap second values from the NIST files have been removed. These provisions are now available whether or not the OpenSSL library is available. However, the functions that can download these values from servers remains available.</p>
-
<hr>
-
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
-
</body>
-
-</html>
\ No newline at end of file
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Autokey Public-Key Authentication</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Autokey Public-Key Authentication</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->06-Sep-2010 18:02<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#auth">Introduction</a></li>
+ <li class="inline"><a href="#group">NTP Secure Groups</a></li>
+ <li class="inline"><a href="#ident">Identity Schemes and Cryptotypes</a></li>
+ <li class="inline"><a href="#cfg">Configuration</a></li>
+ <li class="inline"><a href="#exam">Examples</a></li>
+</ul>
+<hr>
+<h4 id="pub">Introduction</h4>
+<p>NTPv4 supports the Autokey security protocol, which is based on public key cryptography. The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/%7emills/proto.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page are based on cryptographic challenge/response exchanges. These schemes provide strong security against replay with or without message modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/~mills/autokey.html">Autonomous Authentication</a> page.</p>
+<p>Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.</p>
+<p>There are three timeouts associated with the Autokey scheme. The key list timeout, which defaults to about 1.1 h, specifies the interval between generating new key lists. The revoke timeout, which defaults to about 36 h, specifies the interval between generating new private values. The restart timeout, with default about 5 d, specifies the interval between protocol restarts to refresh public values. In general, the behavior when these timeouts expire is not affected by the issues discussed on this page.</p>
+<h4 id="group">NTP Secure Groups</h4>
+<p>NTP secure groups are used to define cryptographic compartments and security
+ hierarchies. All hosts belonging to a secure group have the same group name
+ but different host names. The string specified in the <tt>host</tt> option of
+ the <tt>crypto</tt> command is the name of the host and the name used in the
+ host key, sign key and certificate files. The string specified in the <tt>ident</tt> option
+ of the <tt>crypto</tt> command is the group name of all group hosts and the
+ name used in the identity files. The file naming conventions are described on
+ the <a href="keygen.html">ntp-keygen</a> page.</p>
+<p>Each group includes one or more trusted hosts (THs) operating at the root, or lowest stratum in the group. The group name is used in the subject and issuer fields of the TH self-signed trusted certificate for these hosts. The host name is used in the subject and issuer fields of the self-signed certificates for all other hosts.</p>
+<p>All group hosts are configured to provide an unbroken path, called a certificate trail, from each host, possibly via intermediate hosts and ending at a TH. When a host starts up, it recursively retrieves the certificates along the trail in order to verify group membership and avoid masquerade and middleman attacks.</p>
+<p>Secure groups can be configured as hierarchies where a TH of one group can be a client of one or more other groups operating at a lower stratum. A certificate trail consist of a chain of hosts starting at a client, leading through secondary servers of progressively lower stratum and ending at a TH. In one scenario, groups RED and GREEN can be cryptographically distinct, but both be clients of group BLUE operating at a lower stratum. In another scenario, group CYAN can be a client of multiple groups YELLOW and MAGENTA, both operating at a lower stratum. There are many other scenarios, but all must be configured to include only acyclic certificate trails.</p>
+<h4 id="ident">Identity Schemes and Cryptotypes</h4>
+<p>All configurations include a public/private host key pair and matching certificate. Absent an identity scheme, this is a Trusted Certificate (TC) scheme. There are three identity schemes, IFF, GQ and MV described on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page. With these schemes all servers in the group have encrypted server identity keys, while clients have nonencrypted client identity parameters. The client parameters can be obtained from a trusted agent (TA), usually one of the THs of the lower stratum group. Further information on identity schemes is on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page.</p>
+<p>A specific combination of authentication and identity schemes is called a
+ cryptotype, which applies to clients and servers separately. A group can be
+ configured using more than one cryptotype combination, although not all combinations
+ are interoperable. Note however that some cryptotype combinations may successfully
+ intemperate with each other, but may not represent good security practice. The
+ server and client cryptotypes are defined by the the following codes.</p>
+<dl>
+ <dt>NONE</dt>
+ <dd>A client or server is type NONE if authentication is not available or not configured. Packets exchanged between client and server have no MAC.</dd>
+ <dt>AUTH</dt>
+ <dd>A client or server is type AUTH if the <tt>key</tt> option is specified with the <tt>server</tt> configuration command and the client and server keys are compatible. Packets exchanged between clients and servers have a MAC.</dd>
+ <dt>PC</dt>
+ <dd>A client or server is type PC if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key and private certificate files are present. Packets exchanged between clients and servers have a MAC.</dd>
+ <dt>TC</dt>
+ <dd>A client or server is type TC if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key and public certificate files are present. Packets exchanged between clients and servers have a MAC.</dd>
+ <dt>IDENT</dt>
+ <dd>A client or server is type IDENT if the <tt>autokey</tt> option is specified with the <tt>server</tt> configuration command and compatible host key, public certificate and identity scheme files are present. Packets exchanged between clients and servers have a MAC.</dd>
+</dl>
+<p>The compatible cryptotypes for clients and servers are listed in the following table.</p>
+<table width="100%" border="1" cellpadding="4">
+ <tr>
+ <td rowspan="2" align="center">Client</td>
+ <td colspan="5" align="center">Server</td>
+ </tr>
+ <tr>
+ <td align="center">NONE</td>
+ <td align="center">AUTH</td>
+ <td align="center">PC</td>
+ <td align="center">TC</td>
+ <td align="center">IDENT</td>
+ </tr>
+ <tr>
+ <td align="center">NONE</td>
+ <td align="center">yes</td>
+ <td align="center">yes*</td>
+ <td align="center">yes*</td>
+ <td align="center">yes*</td>
+ <td align="center">yes*</td>
+ </tr>
+ <tr>
+ <td align="center">AUTH</td>
+ <td align="center">no</td>
+ <td align="center">yes</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ </tr>
+ <tr>
+ <td align="center">PC</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">yes</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ </tr>
+ <tr>
+ <td align="center">TC</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">yes</td>
+ <td align="center">yes</td>
+ </tr>
+ <tr>
+ <td align="center">IDENT</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">no</td>
+ <td align="center">yes</td>
+ </tr>
+</table>
+<p>* These combinations are not valid if the restriction list includes the <tt>notrust</tt> option.</p>
+<h4 id="cfg">Configuration</h4>
+<p>Autokey has an intimidating number of configuration options, most of which are not necessary in typical scenarios. The simplest scenario consists of a TH where the host name of the TH is also the name of the group. For the simplest identity scheme TC, the TH generates host key and trusted certificate files using the <tt>ntp-keygen -T</tt> command, while the remaining group hosts use the same command with no options to generate the host key and public certificate files. All hosts use the <tt>crypto</tt> configuration command with no options. Configuration with passwords is described in the <a href="keygen.html">ntp-keygen</a> page. All group hosts are configured as an acyclic tree with root the TH.</p>
+<p>When an identity scheme is included, for example IFF, the TH generates host
+ key, trusted certificate and private server identity key files using the <tt>ntp-keygen
+ -T -I -i <i>group</i></tt> command, where <tt><i>group</i></tt> is the group
+ name. The remaining group hosts use the same command as above. All hosts
+ use the <tt>crypto ident group<i></i></tt> configuration command.</p>
+<p>Hosts with no dependent clients can retrieve client parameter files from an
+ archive or web page. The <tt>ntp-keygen</tt> can export these data using the <tt>-e</tt> option.
+ Hosts with dependent clients other than the TH must retrieve copies of the server
+ key files using secure means. The <tt>ntp-keygen</tt> can export these data
+ using the <tt>-q</tt> option. In either case the data are installed as a file
+ and then renamed using the name given as the first line in the file, but without
+ the filestamp.</p>
+<h4 id="exam">Examples</h4>
+<div align="center"> <img src="pic/group.gif" alt="gif"> </div>
+<p>Consider a scenario involving three secure groups RED, GREEN and BLUE. RED and BLUE are typical of national laboratories providing certified time to the Internet at large. As shown ion the figure, RED TH mort and BLUE TH macabre run NTP symmetric mode with each other for monitoring or backup. For the purpose of illustration, assume both THs are primary servers. GREEN is typical of a large university providing certified time to the campus community. GREEN TH howland is a broadcast client of both RED and BLUE. BLUE uses the IFF scheme, while both RED and GREEN use the GQ scheme, but with different keys. YELLOW is a client of GREEN and for purposes of illustration a TH for YELLOW.</p>
+<p>The BLUE TH macabre uses configuration commands</p>
+<p><tt>crypto pw qqsv ident blue</tt><br>
+ <tt>peer mort autokey</tt><br>
+ <tt>broadcast <i>address</i> autokey</tt></p>
+<p>where <tt>qqsv</tt> is the password for macabre files and <i>address</i> is the broadcast address for the local LAN. It generates BLUE files using the commands</p>
+<p><tt>ntp-keygen -p qqsv -T -G -i blue</tt><br>
+ <tt>ntp-keygen -p qqsv -e >ntpkey_gqpar_blue</tt></p>
+<p>The first line generates the host, trusted certificate and private GQ server keys file. The second generates the public GQ client parameters file, which can have any nonconflicting mnemonic name.</p>
+<p>The RED TH mort uses configuration commands</p>
+<p><tt>crypto pw xxx ident red</tt><br>
+ <tt>peer macabre autokey</tt><br>
+ <tt>broadcast <i>address</i> autokey</tt></p>
+<p>where <tt>xxx</tt> is the password for mort files. It generates RED files using the commands</p>
+<p><tt>ntp-keygen -p xxx -T -I -i red</tt><br>
+ <tt>ntp-keygen -p xxx -e >ntpkey_iffpar_red</tt></p>
+<p> The GREEN TH howland uses configuration commands</p>
+<p><tt>crypto pw yyy ident green</tt><br>
+ <tt>broadcastclient</tt></p>
+<p>where <tt>yyy</tt> is the password for howland files. It generates GREEN files using the commands</p>
+<p><tt>ntp-keygen -p yyy -T -G -i green</tt><br>
+ <tt>ntp-keygen -p yyy -e >ntpkey_gqpar_green</tt><br>
+ <tt>ntp-keygen -p yyy -q zzz >zzz_ntpkey_gqkey_green</tt></p>
+<p>The first two lines serve the same purpose as the preceding examples. The
+ third line generates a copy of the private GREEN server file for use on another
+ server in the same group, say YELLOW, but encrypted with the <tt>zzz</tt> password.</p>
+<p>A client of GREEN, for example YELLOW, uses the configuration commands</p>
+<p><tt>crypto pw abc ident green</tt><br>
+ <tt>server howland autokey</tt></p>
+<p>where <tt>abc</tt> is the password for its files. It generates files using the command</p>
+<p><tt>ntp-keygen -p abc</tt></p>
+<p>The client retrieves the client file for that group from a public archive or web page using nonsecure means. In addition, each server in a group retrieves the private server keys file from the TH of that group, but it is encrypted and so must be sent using secure means. The files are installed in the keys directory with name taken from the first line in the file, but without the filestamp.</p>
+<p>Note that if servers of different groups, in this case RED and BLUE, share the same broadcast media, each server must have client files for all groups other than its own, while each client must have client files for all groups. Note also that this scenario is for illustration only and probably would not be wise for practical use, as if one of the TH reference clocks fails, the certificate trail becomes cyclic. In such cases the symmetric path between RED and BLUE, each in a different group, would not be a good idea.</p>
+<h4 id="err">Error Codes</h4>
+<p>Errors can occur due to mismatched configurations, unexpected protocol restarts, expired certificates and unfriendly people. In most cases the protocol state machine recovers automatically by retransmission, timeout and restart, where necessary. Some errors are due to mismatched keys, digest schemes or identity schemes and must be corrected by installing the correct media and/or correcting the configuration file. One of the most common errors is expired certificates, which must be regenerated and signed at least once per year using the <a href="keygen.html"><tt>ntp-keygen</tt> - generate public and private keys</a> program.</p>
+<p>The following error codes are reported via the NTP control and monitoring protocol trap mechanism and to the <tt>cryptostats</tt> monitoring file if configured.</p>
+<dl>
+ <dt>101 bad field format or length</dt>
+ <dd>The packet has invalid version, length or format.</dd>
+ <dt>102 bad timestamp</dt>
+ <dd>The packet timestamp is the same or older than the most recent received. This could be due to a replay or a server clock time step.</dd>
+ <dt>103 bad filestamp</dt>
+ <dd>The packet filestamp is the same or older than the most recent received. This could be due to a replay or a key file generation error.</dd>
+ <dt>104 bad or missing public key</dt>
+ <dd>The public key is missing, has incorrect format or is an unsupported type.</dd>
+ <dt>105 unsupported digest type</dt>
+ <dd>The server requires an unsupported digest/signature scheme.</dd>
+ <dt>106 unsupported identity type</dt>
+ <dd>The client or server has requested an identity scheme the other does not support.</dd>
+ <dt>107 bad signature length</dt>
+ <dd>The signature length does not match the current public key.</dd>
+ <dt>108 signature not verified</dt>
+ <dd>The message fails the signature check. It could be bogus or signed by a different private key.</dd>
+ <dt>109 certificate not verified</dt>
+ <dd>The certificate is invalid or signed with the wrong key.</dd>
+ <dt>110 host certificate expired</dt>
+ <dd>The old server certificate has expired.</dd>
+ <dt>111 bad or missing cookie</dt>
+ <dd>The cookie is missing, corrupted or bogus.</dd>
+ <dt>112 bad or missing leapseconds table</dt>
+ <dd>The leapseconds table is missing, corrupted or bogus.</dd>
+ <dt>113 bad or missing certificate</dt>
+ <dd>The certificate is missing, corrupted or bogus.</dd>
+ <dt>114 bad or missing group key</dt>
+ <dd>The identity key is missing, corrupt or bogus.</dd>
+ <dt>115 protocol error</dt>
+ <dd>The protocol state machine has wedged due to unexpected restart.</dd>
+</dl>
+<h4 id="file">Files</h4>
+<p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page. Note that provisions to load leap second values from the NIST files have been removed. These provisions are now available whether or not the OpenSSL library is available. However, the functions that can download these values from servers remains available.</p>
+<hr>
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</p>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>NTP Bug Reporting Procedures</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <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">04:05</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- .<br clear="left">
- <hr>
- <h4> Security Bug Reporting Procedures</h4>
- <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 documentation 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 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>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>NTP Bug Reporting Procedures</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<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:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:49<!-- #EndDate -->
+UTC</p>
+.<br clear="left">
+<hr>
+<h4> Security Bug Reporting Procedures</h4>
+<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 documentation pages, please
+ send a report directly to the editor David L. 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 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>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=windows-1252">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Building and Installing the Distribution</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Building and Installing the Distribution</h3>
- <img src="pic/beaver.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>For putting out compiler fires.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">16:45</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#build">Building and Installing the Distribution</a>
- <li class="inline"><a href="#unix">Building and Installing for Unix</a>
- <li class="inline"><a href="#win">Building and Installing for Windows</a>
- <li class="inline"><a href="#conf">Configuration</a>
- <li class="inline"><a href="#prob">If You Have Problems</a>
- <li class="inline"><a href="#make">Additional <tt>make</tt> Commands</a>
- </ul>
- <hr>
- <h4 id="build">Building and Installing the Distribution</h4>
- <p>It is not possible in a software distribution such as this to support every individual computer and operating system with a common executable, even with the same system but different versions and options. Therefore, it is necessary to configure, build and install for each system and version. In almost all cases, these procedures are completely automatic, The user types <tt>./configure</tt>, <tt>make</tt> and <tt>install</tt> in that order and the autoconfigure system does the rest. There are some exceptions, as noted below and on the <a href="hints.html">Hints and Kinks</a> pages.</p>
- <p>If available, the OpenSSL library from <a href="http://www.openssl.org">http://www.openssl.org</a> is used to support public key cryptography. The library must be built and installed prior to building NTP. The procedures for doing that are included in the OpenSSL documentation. The library is found during the normal NTP configure phase and the interface routines compiled automatically. Only the <tt>libcrypto.a</tt> library file and <tt>openssl</tt> header files are needed. If the library is not available or disabled, this step is not required.</p>
- <p>The <a href="config.html">Build Options</a> page describes a number of options that determine whether debug support is included, whether and which reference clock drivers are included and the locations of the executables and library files, if not the default. By default debugging options and all reference clock drivers are included.</p>
- <h4 id="unix">Building and Installing for Unix</h4>
- <p>This distribution uses common compilers and tools that come with most Unix distributions. Not all of these tools exist in the standard distribution of modern Unix versions (compilers are likely to be an add-on product). If this is the case, consider using the GNU tools and <tt>gcc</tt> compiler included as freeware in some systems. For a successful build, all of these tools should be accessible via the current path.</p>
- <p>The first thing to do is uncompress the distribution and extract the source tree. In the distribution base directory use the <tt>./configure </tt>command to perform an automatic configuration procedure. This command inspects the hardware and software environment and configures the build process accordingly. Use the <tt>make</tt> command to compile and link the distribution and the <tt>install</tt> command to install the executables by default in <tt>/usr/local/bin</tt>.</p>
- <p>If your site supports multiple architectures and uses NFS to share files, you can use a single source tree to build executables for multiple architectures. While running on a particular architecture, change to the base directory and create a subdirectory using a command like <tt>mkdir A.machine, </tt>which will create an architecture-specific directory, then change to this directory and mumble <tt>../configure</tt>. The remaining steps are the same whether building in the base directory or in the subdirectory.</p>
- <h4 id="win">Building and Installing for Windows</h4>
- <p>NTP supports Windows Vista, XP, NT4 and 2000 systems. See the <a href="hints/winnt.html">NTP 4.x for Windows NT</a> page for directions to compile the sources and install the executables. A precompiled executable is available.</p>
- <h4 id="conf">Configuration</h4>
- <p>You are now ready to configure the daemon. You will need to create a NTP configuration file by default in <tt>/etc/ntp.conf.</tt> Newbies should see the <a href="quick.html">Quick Start</a> page for orientation. Seasoned veterans can start with the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page and move on to the specific configuration option pages from there.</p>
- <h4 id="prob">If You Have Problems</h4>
- <p>If you have problems with your hardware and software environment (e.g. operating system-specific issues), browse the <a href="hints.html">Hints and Kinks</a> pages. For other problems a tutorial on debugging technique is in the <a href="debug.html">NTP Debugging Technique</a> page. A list of important system log messages is on the <a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> page.</p>
- <p>The first line of general assistance is the NTP web site <a href="http://www.ntp.org">www.ntp.org</a> and the helpful documents resident there. Requests for assistance of a general nature and of interest to other timekeepers should be sent to the NTP newsgroup comp.protocols.time.ntp.</p>
- <p>Users are invited to report bugs and offer suggestions via the <a href="bugs.html">NTPáBug Reporting Procedures</a> page.</p>
- <h4 id="make">Additional <tt>make</tt> commands</h4>
- <dl>
- <dt><tt>make clean</tt>
- <dd>Cleans out object files, programs and temporary files.
- <dt><tt>make distclean</tt>
- <dd>Does the work of <tt>clean</tt>, but cleans out all directories in preparation for a new distribution release.
- <dt><tt>make dist</tt>
- <dd>Does the work of <tt>make distclean</tt>, but constructs compressed tar files for distribution. You must have GNU automake to perform this function.
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=windows-1252">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Building and Installing the Distribution</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Building and Installing the Distribution</h3>
+<img src="pic/beaver.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>For putting out compiler fires.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:58<!-- #EndDate -->
+UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#build">Building and Installing the Distribution</a></li>
+ <li class="inline"><a href="#unix">Building and Installing for Unix</a></li>
+ <li class="inline"><a href="#win">Building and Installing for Windows</a></li>
+ <li class="inline"><a href="#conf">Configuration</a></li>
+ <li class="inline"><a href="#prob">If You Have Problems</a></li>
+ <li class="inline"><a href="#make">Additional <tt>make</tt> Commands</a></li>
+</ul>
+<hr>
+<h4 id="build">Building and Installing the Distribution</h4>
+<p>It is not possible in a software distribution such as this to support every individual computer and operating system with a common executable, even with the same system but different versions and options. Therefore, it is necessary to configure, build and install for each system and version. In almost all cases, these procedures are completely automatic, The user types <tt>./configure</tt>, <tt>make</tt> and <tt>install</tt> in that order and the autoconfigure system does the rest. There are some exceptions, as noted below and on the <a href="hints.html">Hints and Kinks</a> pages.</p>
+<p>If available, the OpenSSL library from <a href="http://www.openssl.org">http://www.openssl.org</a> is used to support public key cryptography. The library must be built and installed prior to building NTP. The procedures for doing that are included in the OpenSSL documentation. The library is found during the normal NTP configure phase and the interface routines compiled automatically. Only the <tt>libcrypto.a</tt> library file and <tt>openssl</tt> header files are needed. If the library is not available or disabled, this step is not required.</p>
+<p>The <a href="config.html">Build Options</a> page describes a number of options that determine whether debug support is included, whether and which reference clock drivers are included and the locations of the executables and library files, if not the default. By default debugging options and all reference clock drivers are included.</p>
+<h4 id="unix">Building and Installing for Unix</h4>
+<p>This distribution uses common compilers and tools that come with most Unix distributions. Not all of these tools exist in the standard distribution of modern Unix versions (compilers are likely to be an add-on product). If this is the case, consider using the GNU tools and <tt>gcc</tt> compiler included as freeware in some systems. For a successful build, all of these tools should be accessible via the current path.</p>
+<p>The first thing to do is uncompress the distribution and extract the source tree. In the distribution base directory use the <tt>./configure </tt>command to perform an automatic configuration procedure. This command inspects the hardware and software environment and configures the build process accordingly. Use the <tt>make</tt> command to compile and link the distribution and the <tt>install</tt> command to install the executables by default in <tt>/usr/local/bin</tt>.</p>
+<p>If your site supports multiple architectures and uses NFS to share files, you can use a single source tree to build executables for multiple architectures. While running on a particular architecture, change to the base directory and create a subdirectory using a command like <tt>mkdir A.machine, </tt>which will create an architecture-specific directory, then change to this directory and mumble <tt>../configure</tt>. The remaining steps are the same whether building in the base directory or in the subdirectory.</p>
+<h4 id="win">Building and Installing for Windows</h4>
+<p>NTP supports Windows Vista, XP, NT4 and 2000 systems. See the <a href="hints/winnt.html">NTP 4.x for Windows NT</a> page for directions to compile the sources and install the executables. A precompiled executable is available.</p>
+<h4 id="conf">Configuration</h4>
+<p>You are now ready to configure the daemon. You will need to create a NTP configuration file by default in <tt>/etc/ntp.conf.</tt> Newbies should see the <a href="quick.html">Quick Start</a> page for orientation. Seasoned veterans can start with the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page and move on to the specific configuration option pages from there.</p>
+<h4 id="prob">If You Have Problems</h4>
+<p>If you have problems with your hardware and software environment (e.g. operating system-specific issues), browse the <a href="hints.html">Hints and Kinks</a> pages. For other problems a tutorial on debugging technique is in the <a href="debug.html">NTP Debugging Technique</a> page. A list of important system log messages is on the <a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> page.</p>
+<p>The first line of general assistance is the NTP web site <a href="http://www.ntp.org">www.ntp.org</a> and the helpful documents resident there. Requests for assistance of a general nature and of interest to other timekeepers should be sent to the NTP newsgroup comp.protocols.time.ntp.</p>
+<p>Users are invited to report bugs and offer suggestions via the <a href="bugs.html">NTPáBug Reporting Procedures</a> page.</p>
+<h4 id="make">Additional <tt>make</tt> commands</h4>
+<dl>
+ <dt><tt>make clean</tt></dt>
+ <dd>Cleans out object files, programs and temporary files.</dd>
+ <dt><tt>make distclean</tt></dt>
+ <dd>Does the work of <tt>clean</tt>, but cleans out all directories in preparation for a new distribution release.</dd>
+ <dt><tt>make dist</tt></dt>
+ <dd>Does the work of <tt>make distclean</tt>, but constructs compressed tar files for distribution. You must have GNU automake to perform this function.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Clock State Machine</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Clock State Machine</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->08-Sep-2010 21:38<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Introduction</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 congesiton, for example. The state machine uses three thresolds: panic, step and stepout, and a watchdog timer. The thresholds default to 1000 s, 128 ms and 900 s, respectively, but can be changed by command options.</p>
+<h4>The Panic Threhold</h4>
+<p>Most compters today incorporate a time-of-year (TOY) chip to maintain the time when the power is off. When the machine 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, the daemon will set the clock to NTP time the first time, but exit if the offset exceed the any time after that.</p>
+<h4>The Step and Stepout Thresholds</h4>
+<p>Under ordinary conditions, the clock discipline slews the clock so that the time is effectively continuous and never runs backwards. If due to extreme network congestion, or an offset spike exceeds the step threshold, by default 128 ms, the spike is discarded. However, if offsets greater than the step threshold persist for more than the <i>stepout threshold</i>, by default 900 s, the system clock is stepped to the correct value. In practice the need for a step has been extremely rare and almost always the result of a hardware failure. Both the step threshold and stepout threshold can be set as options to the tinker command.</p>
+<p>Historically, the most important appliccation of the step function was when a leap second was inserted in the Coordinated Univesal Time (UTC) timescale and kernel precision time support was not available. Further details are on the <a href="leap">Leap Second Processing</a> page.</p>
+<p>In some applications the clock can never be set backward, even it accidentlly set forward a week by some other means. There are several ways to alter the daemon behavior to insure time is always monotone-increasing. If the step threhold is set to zero, there will never be a step. With the <tt>-x</tt> command line option the daemon will set will set the step threshold to 600 s, which is about the limit of eyeball and wristwatch. However, in any of these cases, the precision time kernel support is disabled, as it cannot handle offsets greater than ±0.5 s.</p>
+<p>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>Frequency Training</h4>
+<p>The frequency file, usually called <tt>ntp.drift</tt>, contains the latest estimate of clock frequency. If this file does not exist when the daemon is started, the clock state machine enters a special mode designed to measure the particular frequency directly. The measurement takes an interval equal to the stepout threshold, after which the frequency is set and the daemon esumes normal mode where the time and frequency are continuously adjusted. The frequency file is updated at intervals of an hour or more depending on the measured clock stability.</p>
+<hr>
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</p>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Reference Clock Options</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Reference Clock Options</h3>
- <img src="pic/stack1a.jpg" alt="gif" align="left">Master Time Facility at the <a href="http://www.eecis.udel.edu/%7emills/lab.html">UDel Internet Research Laboratory</a>
- <p>Last update:
- <!-- #BeginDate format:En2m -->04-Oct-2009 19:42<!-- #EndDate -->
- UTC</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Reference Clock Commands and Options</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Reference Clock Commands and Options</h3>
+<img src="pic/stack1a.jpg" alt="gif" align="left">Master Time Facility at the <a href="http://www.eecis.udel.edu/%7emills/lab.html">UDel Internet Research Laboratory</a>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->10-Sep-2010 0:09<!-- #EndDate -->
+ UTC</p>
<br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/clockopt.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#ref">Reference Clock Support</a>
- <li class="inline"><a href="#cmd">Reference Clock Commands</a>
- </ul>
- <hr>
- <h4 id="ref">Reference Clock Support</h4>
- <p>The NTP Version 4 daemon supports some three dozen different radio, satellite and modem reference clocks plus a special pseudo-clock used for backup or when no other clock source is available. Detailed descriptions of individual device drivers and options can be found in the <a href="refclock.html">Reference Clock Drivers</a> page. Additional information can be found in the pages linked there, including the <a href="rdebug.html">Debugging Hints for Reference Clock Drivers</a> and <a href="howto.html">How To Write a Reference Clock Driver</a> pages. In addition, support for a PPS signal is available as described in <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page.</p>
- <p>A reference clock will generally (though not always) be a radio timecode receiver which is synchronized to a source of standard time such as the services offered by the NRC in Canada and NIST and USNO in the US. The interface between the computer and the timecode receiver is device dependent, but is usually a serial port. A device driver specific to each reference clock must be selected and compiled in the distribution; however, most common radio, satellite and modem clocks are included by default. Note that an attempt to configure a reference clock when the driver has not been compiled or the hardware port has not been appropriately configured results in a scalding remark to the system log file, but is otherwise non hazardous.</p>
- <p>For the purposes of configuration, <tt>ntpd</tt> treats reference clocks in a manner analogous to normal NTP peers as much as possible. Reference clocks are identified by a syntactically correct but invalid IP address, in order to distinguish them from normal NTP peers. Reference clock addresses are of the form <tt>127.127.<i>t.u</i></tt>, where <i><tt>t</tt></i> is an integer denoting the clock type and <i><tt>u</tt></i> indicates the unit number in the range 0-3. While it may seem overkill, it is in fact sometimes useful to configure multiple reference clocks of the same type, in which case the unit numbers must be unique.</p>
- <p>The <tt>server</tt> command is used to configure a reference clock, where the <i><tt>address</tt></i> argument in that command is the clock address. The <tt>key</tt>, <tt>version</tt> and <tt>ttl</tt> options are not used for reference clock support. The <tt>mode</tt> option is added for reference clock support, as described below. The <tt>prefer</tt> option can be useful to persuade the server to cherish a reference clock with somewhat more enthusiasm than other reference clocks or peers. Further information on this option can be found in the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. The <tt>minpoll</tt> and <tt>maxpoll</tt> options have meaning only for selected clock drivers. See the individual clock driver document pages for additional information.</p>
- <p>The <tt>fudge</tt> command is used to provide additional information for individual clock drivers and normally follows immediately after the <tt>server</tt> command. The <i><tt>address</tt></i> argument specifies the clock address. The <tt>refid</tt> and <tt>stratum</tt> options control can be used to override the defaults for the device. There are two optional device-dependent time offsets and four flags that can be included in the <tt>fudge</tt> command as well.</p>
- <p>The stratum number of a reference clock is by default zero. Since the <tt>ntpd</tt> daemon adds one to the stratum of each peer, a primary server ordinarily displays an external stratum of one. In order to provide engineered backups, it is often useful to specify the reference clock stratum as greater than zero. The <tt>stratum</tt> option is used for this purpose. Also, in cases involving both a reference clock and a pulse-per-second (PPS) discipline signal, it is useful to specify the reference clock identifier as other than the default, depending on the driver. The <tt>refid</tt> option is used for this purpose. Except where noted, these options apply to all clock drivers.</p>
- <h4 id="cmd">Reference Clock Commands</h4>
- <dl>
- <dt id="server"><tt>server 127.127.<i>t.u</i> [prefer] [mode <i>int</i>] [minpoll <i>int</i>] [maxpoll <i>int</i>]</tt>
- <dd>This command can be used to configure reference clocks in special ways. The options are interpreted as follows:
- <dl>
- <dt><tt>prefer</tt>
- <dd>Marks the reference clock as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. See the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page for further information.
- <dt><tt>mode <i>int</i></tt>
- <dd>Specifies a mode number which is interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the <tt>parse</tt> drivers.
- <dt><tt>minpoll <i>int</i></tt>
- <dt><tt>maxpoll <i>int</i></tt>
- <dd>These options specify the minimum and maximum polling interval for reference clock messages in seconds, interpreted as dual logarithms (2 ^ x). For most directly connected reference clocks, both <tt>minpoll</tt> and <tt>maxpoll</tt> default to 6 (2^16 = 64 s). For modem reference clocks, <tt>minpoll</tt> defaults to 10 (2^10 = 1024 s = 17.1 m) and <tt>maxpoll</tt> defaults to 14 (2^14 = 16384 s = 4.5 h). The allowable range is 4 (16 s) to 17 (36.4 h) inclusive.
- </dl>
- <dt id="fudge"><tt>fudge 127.127.<i>t.u</i> [time1 <i>sec</i>] [time2 <i>sec</i>]
- [stratum <i>int</i>] [refid <i>string</i>] [flag1 0|1]
- [flag2 0|1] [flag3 0|1] [flag4 0|1]</tt>
- <dd>This command can be used to configure reference clocks in special ways. It must immediately follow the <tt>server</tt> command which configures the driver. Note that the same capability is possible at run time using the <tt><a href="ntpdc.html">ntpdc</a></tt> program. The options are interpreted as follows:
- <dl>
- <dt><tt>time1 <i>sec</i></tt>
- <dd>Specifies a constant to be added to the time offset produced by the driver, a fixed-point decimal number in seconds. This is used as a calibration constant to adjust the nominal time offset of a particular clock to agree with an external standard, such as a precision PPS signal. It also provides a way to correct a systematic error or bias due to serial port or operating system latencies, different cable lengths or receiver internal delay. The specified offset is in addition to the propagation delay provided by other means, such as internal DIPswitches. Where a calibration for an individual system and driver is available, an approximate correction is noted in the driver documentation pages.
- <dd>Note: in order to facilitate calibration when more than one radio clock or PPS signal is supported, a special calibration feature is available. It takes the form of an argument to the <tt>enable</tt> command described in the <a href="miscopt.html">Miscellaneous Options</a> page and operates as described in the <a href="refclock.html">Reference Clock Drivers</a> page.
- <dt><tt>time2 <i>secs</i></tt>
- <dd>Specifies a fixed-point decimal number in seconds, which is interpreted in a driver-dependent way. See the descriptions of specific drivers in the <a href="refclock.html">reference clock drivers</a> page.
- <dt><tt>stratum <i>int</i></tt>
- <dd>Specifies the stratum number assigned to the driver, an integer between 0 and 15. This number overrides the default stratum number ordinarily assigned by the driver itself, usually zero.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies an ASCII string of from one to four characters which defines the reference identifier used by the driver. This string overrides the default identifier ordinarily assigned by the driver itself.
- <dt><tt>flag1 flag2 flag3 flag4</tt>
- <dd>These four flags are used for customizing the clock driver. The interpretation of these values, and whether they are used at all, is a function of the particular clock driver. However, by convention <tt>flag4</tt> is used to enable recording monitoring data to the <tt>clockstats</tt> file configured with the <tt>filegen</tt> command. Further information on the <tt>filegen</tt> command can be found in the <a href="monopt.html">Monitoring Options</a> page.
- </dl>
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/clockopt.txt"></script>
+<hr>
+<h4 id="addrs">Reference Clock Adddresses</h4>
+<p>Unless noted otherwise, further information about these ccommands is on the <a href="refclock.html">Reference Clock Support</a> page.</p><p>Reference clocks are identified by a syntactically correct but invalid IP address, in order to distinguish them from ordinary NTP peers. These addresses are of the form 127.127.<em>t</em>.<em>u</em>, where <em>t</em> is an integer denoting the clock type and <em>u</em> indicates the unit number in the range 0-3. While it may seem overkill, it is in fact sometimes useful to configure multiple reference clocks of the same type, in which case the unit numbers must be unique.</p>
+<h4 id="cmd"> Commands and Options</h4>
+<dl>
+ <dt id="server"><tt>server 127.127.<i>t.u</i> [prefer] [mode <i>int</i>] [minpoll <i>int</i>] [maxpoll <i>int</i>]</tt></dt>
+ <dd>This command can be used to configure reference clocks in special ways. The options are interpreted as follows:
+ <dl>
+ <dt><tt>prefer</tt></dt>
+ <dd>Marks the reference clock as preferred. All other things being equal, this host will be chosen for synchronization among a set of correctly operating hosts. See the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page for further information.</dd>
+ <dt><tt>mode <i>int</i></tt></dt>
+ <dd>Specifies a mode number which is interpreted in a device-specific fashion. For instance, it selects a dialing protocol in the ACTS driver and a device subtype in the <tt>parse</tt> drivers.</dd>
+ <dt><tt>minpoll <i>int</i></tt><br>
+ <tt>maxpoll <i>int</i></tt></dt>
+ <dd>These options specify the minimum and maximum polling interval for reference clock messages in log<sub>2</sub> seconds. For most directly connected reference clocks, both <tt>minpoll</tt> and <tt>maxpoll</tt> default to 6 (64 s). For modem reference clocks, <tt>minpoll</tt> is ordinarily set to 10 (about m) and <tt>maxpoll</tt> to 15 (about 9 h). The allowable range is 4 (16 s) to 17 (36 h) inclusive.</dd>
+ </dl>
+ </dd>
+ <dt id="fudge"><tt>fudge 127.127.<i>t.u</i> [time1 <i>sec</i>] [time2 <i>sec</i>]
+ [stratum <i>int</i>] [refid <i>string</i>] [flag1 0|1]
+ [flag2 0|1] [flag3 0|1] [flag4 0|1]</tt></dt>
+ <dd>This command can be used to configure reference clocks in special ways. It must immediately follow the <tt>server</tt> command which configures the driver. Note that the same capability is possible at run time using the <tt><a href="ntpdc.html">ntpdc</a></tt> program. The options are interpreted as follows:
+ <dl>
+ <dt><tt>time1 <i>sec</i></tt></dt>
+ <dd>Specifies a constant to be added to the time offset produced by the driver, a fixed-point decimal number in seconds. This is used as a calibration constant to adjust the nominal time offset of a particular clock to agree with an external standard, such as a precision PPS signal. It also provides a way to correct a systematic error or bias due to serial port or operating system latencies, different cable lengths or receiver internal delay. The specified offset is in addition to the propagation delay provided by other means, such as internal DIPswitches. Where a calibration for an individual system and driver is available, an approximate correction is noted in the driver documentation pages.</dd>
+ <dd>Note: in order to facilitate calibration when more than one radio clock or PPS signal is supported, a special calibration feature is available. It takes the form of an argument to the <tt>enable</tt> command described in the <a href="miscopt.html">Miscellaneous Options</a> page and operates as described in the <a href="refclock.html">Reference Clock Support</a> page.</dd>
+ <dt><tt>time2 <i>secs</i></tt></dt>
+ <dd>Specifies a fixed-point decimal number in seconds, which is interpreted in a driver-dependent way. See the descriptions of specific drivers in the <a href="refclock.html">Reference Clock Support</a> page.</dd>
+ <dt><tt>stratum <i>int</i></tt></dt>
+ <dd>Specifies the stratum number assigned to the driver in the range 0 to 15, inclusive. This number overrides the default stratum number ordinarily assigned by the driver itself, usually zero.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies an ASCII string of from one to four characters which defines the reference identifier used by the driver. This string overrides the default identifier ordinarily assigned by the driver itself.</dd>
+ <dt><tt>flag1 flag2 flag3 flag4</tt></dt>
+ <dd>These four flags are used for customizing the clock driver. The interpretation of these values, and whether they are used at all, is a function of the particular driver. However, by convention <tt>flag4</tt> is used to enable recording monitoring data to the <tt>clockstats</tt> file configured with the <tt>filegen</tt> command. Additional information on the <tt>filegen</tt> command is on the <a href="monopt.html">Monitoring Options</a> page.</dd>
+ </dl>
+ </dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Command Index</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Command Index</h3>
- <img src="pic/alice38.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carrol</a>
- <p>The Mad Hatter says "Bring it on".</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->08-Apr-2009 2:56<!-- #EndDate -->
- UTC</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Command Index</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Command Index</h3>
+<img src="pic/alice38.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carrol</a>
+<p>The Mad Hatter says "Bring it on".</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->07-Sep-2010 2:11<!-- #EndDate -->
+ UTC</p>
<br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/accopt.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/authopt.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/clockopt.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/confopt.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/miscopt.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/monopt.txt"></script>
- <hr>
- <br>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/accopt.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/authopt.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/confopt.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/monopt.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/clockopt.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/miscopt.txt"></script>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
-<title>Server Options</title>
+<title>Server Commands and Options</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
<body>
-<h3>Server Options</h3>
+<h3>Server Commands and Options</h3>
<img src="pic/boom3a.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>,
Walt Kelly</a>
<p>The chicken is getting configuration advice.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->11-Apr-2010 23:07<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->10-Sep-2010 0:29<!-- #EndDate -->
</p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
<script type="text/javascript" language="javascript" src="scripts/confopt.txt"></script>
-<h4>Table of Contents</h4>
-<ul>
- <li class="inline"><a href="#cfg">Configuration Commands</a></li>
- <li class="inline"><a href="#opt">Command Options</a></li>
- <li class="inline"><a href="#aux">Auxilliary Commands</a></li>
- <li class="inline"><a href="#bug">Bugs</a></li>
-</ul>
<hr>
-<p>Following is a description of the configuration commands in NTPv4. There are
- two classes of commands, configuration commands that configure an association
- with a remote server, peer or reference clock, and auxilliary commands that
- specify environmental variables that control various related operations. </p>
-<p>The various modes described on the <a href="assoc.html">Association Management</a> page
- are determined by the command keyword and the DNS name or IP address. Addresses
- are classed by type as (s) a remote server or peer (IPv4 class A, B and C),
- (b) the IP broadcast address of a local interface, (m) a multicast address (IPv4
- class D), or (r) a reference clock address (127.127.x.x). For type m addresses
- the IANA has assigned the multicast group address IPv4 224.0.1.1 and IPv6 ff05::101
- (site local) exclusively to NTP, but other nonconflicting addresses can be used. </p>
+<h4>Server and Peer Addresses</h4>
+<p>Following is a description of the configuration commands in NTPv4. There are two classes of commands, configuration commands that configure an association with a remote server, peer or reference clock, and auxilliary commands that specify environmental variables that control various related operations. </p>
+<p>The various modes described on the <a href="assoc.html">Association Management</a> page are determined by the command keyword and the DNS name or IP address. Addresses are classed by type as (s) a remote server or peer (IPv4 class A, B and C), (b) the IP broadcast address of a local interface, (m) a multicast address (IPv4 class D), or (r) a reference clock address (127.127.x.x). For type m addresses the IANA has assigned the multicast group address IPv4 224.0.1.1 and IPv6 ff05::101 (site local) exclusively to NTP, but other nonconflicting addresses can be used. </p>
<p>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected,
- support for the IPv6 address family is generated in addition to the default
- IPv4 address family. IPv6 addresses can be identified by the presence of colons ":" in
- the address field. IPv6 addresses can be used almost everywhere where IPv4 addresses
- can be used, with the exception of reference clock addresses, which are always
- IPv4. Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier
- preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier
- forces DNS resolution to the IPv6 namespace.</p>
-<h4 id="cfg">Configuration Commands</h4>
-<dl>
+ support for the IPv6 address family is generated in addition to the default IPv4 address family. IPv6 addresses can be identified by the presence of colons ":" in the address field. IPv6 addresses can be used almost everywhere where IPv4 addresses can be used, with the exception of reference clock addresses, which are always IPv4. Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
+<h4 id="cfg">Commands and Options</h4>
+<p>Unless noted otherwise, further information about these ccommands is on the <a href="assoc.html">Association Management</a> page.</p><dl>
<dt id="server"><tt>server <i>address</i> [options ...]</tt><br>
<tt>peer <i>address</i> [options ...]</tt><br>
<tt>broadcast <i>address</i> [options ...]</tt><br>
<dl>
<dt><tt>autokey</tt></dt>
<dd>Send and receive packets authenticated by the Autokey scheme described
- in the <a href="authopt.html">Authentication Options</a> page. This option
+ in the <a href="autokey.html">Autokey Public Key Authentication</a> page. This option
is mutually exclusive with the <tt>key</tt> option.</dd>
<dt><tt>burst</tt></dt>
<dd>When the server is reachable, send a burst of eight packets instead of the
a recommended option with this command.</dd>
<dt><tt>key</tt> <i><tt>key</tt></i></dt>
<dd>Send and receive packets authenticated by the symmetric key scheme described
- in the <a href="authopt.html">Authentication Options</a> page.
+ in the <a href="authentic.html">Authentication Support</a> page.
The <i><tt>key</tt></i> specifies the key identifier with values from 1 to
65534, inclusive. This option is mutually exclusive with the <tt>autokey</tt> option.</dd>
<dt><tt>minpoll <i>minpoll<br>
or outgoing NTP packets. Versions
1-4 are the choices, with version 4 the default.</dd>
<dt><tt>xleave</tt></dt>
- <dd>Operate in interleaved mode (symmetric and broadcast modes only).
(see <a href="xleave.html">NTP
- Interleaved Modes</a>)</dd>
+ <dd>Operate in interleaved mode (symmetric and broadcast modes only).
Further information is on the <a href="xleave.html">NTP
+ Interleaved Modes</a> page.</dd>
</dl>
<h4 id="aux">Auxilliary Commands</h4>
<dl>
should operate using symmetric key or public key authentication as described
in the <a href="authopt.html">Authentication Options</a> page.</dd>
</dl>
-<h4 id="bug">Bugs</h4>
-<p>The syntax checking is not picky; some combinations of ridiculous and even
- hilarious options and modes may not be detected.</p>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <title>Copyright Notice</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Copyright Notice</h3>
- <img src="pic/sheepb.jpg" alt="jpg" align="left"> "Clone me," says Dolly sheepishly.
- <p>Last update:
- <!-- #BeginDate format:En2m -->16-May-2010 3:13<!-- #EndDate -->
- UTC<br clear="left">
- </p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<title>Copyright Notice</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Copyright Notice</h3>
+<img src="pic/sheepb.jpg" alt="jpg" align="left"> "Clone me," says Dolly sheepishly.
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 21:20<!-- #EndDate -->
+ UTC<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>
+<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) University of Delaware 1992-2010 *
* *
***********************************************************************
</pre>
- <p>The following individuals contributed in part to the Network Time Protocol Distribution Version 4 and are acknowledged as authors of this work.</p>
- <ol>
- <li class="inline"><a href="mailto:%20mark_andrews@isc.org">Mark Andrews <mark_andrews@isc.org></a> Leitch atomic clock controller
- <li class="inline"><a href="mailto:%20altmeier@atlsoft.de">Bernd Altmeier <altmeier@atlsoft.de></a> hopf Elektronik serial line and PCI-bus devices
- <li class="inline"><a href="mailto:%20vbais@mailman1.intel.co">Viraj Bais <vbais@mailman1.intel.com></a> and <a href="mailto:%20kirkwood@striderfm.intel.com">Clayton Kirkwood <kirkwood@striderfm.intel.com></a> port to WindowsNT 3.5
- <li class="inline"><a href="mailto:%20michael.barone@lmco.com">Michael Barone <michael,barone@lmco.com></a> GPSVME fixes
- <li class="inline"><a href="mailto:%20karl@owl.HQ.ileaf.com">Karl Berry <karl@owl.HQ.ileaf.com></a> syslog to file option
- <li class="inline"><a href="mailto:%20greg.brackley@bigfoot.com">Greg Brackley <greg.brackley@bigfoot.com></a> Major rework of WINNT port. Clean up recvbuf and iosignal code into separate modules.
- <li class="inline"><a href="mailto:%20Marc.Brett@westgeo.com">Marc Brett <Marc.Brett@westgeo.com></a> Magnavox GPS clock driver
- <li class="inline"><a href="mailto:%20Piete.Brooks@cl.cam.ac.uk">Piete Brooks <Piete.Brooks@cl.cam.ac.uk></a> MSF clock driver, Trimble PARSE support
- <li class="inline"><a href="mailto:%20nelson@bolyard.me">Nelson B Bolyard <nelson@bolyard.me></a> update and complete broadcast and crypto features in sntp
- <li class="inline"><a href="mailto:%20Jean-Francois.Boudreault@viagenie.qc.ca">Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca></a> IPv6 support
- <li class="inline"><a href="mailto:%20reg@dwf.com">Reg Clemens <reg@dwf.com></a> Oncore driver (Current maintainer)
- <li class="inline"><a href="mailto:%20clift@ml.csiro.au">Steve Clift <clift@ml.csiro.au></a> OMEGA clock driver
- <li class="inline"><a href="mailto:casey@csc.co.za">Casey Crellin <casey@csc.co.za></a> vxWorks (Tornado) port and help with target configuration
- <li class="inline"><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 class="inline"><a href="mailto:%20dundas@salt.jpl.nasa.gov">John A. Dundas III <dundas@salt.jpl.nasa.gov></a> Apple A/UX port
- <li class="inline"><a href="mailto:%20duwe@immd4.informatik.uni-erlangen.de">Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de></a> Linux port
- <li class="inline"><a href="mailto:%20dennis@mrbill.canet.ca">Dennis Ferguson <dennis@mrbill.canet.ca></a> foundation code for NTP Version 2 as specified in RFC-1119
- <li class="inline"><a href="mailto:%20jhay@icomtek.csir.co.za">John Hay <jhay@icomtek.csir.co.za></a> IPv6 support and testing
- <li class="inline"><a href="mailto:%20davehart@davehart.com">Dave Hart <davehart@davehart.com></a> General maintenance, Windows port interpolation rewrite
- <li class="inline"><a href="mailto:%20neoclock4x@linum.com">Claas Hilbrecht <neoclock4x@linum.com></a> NeoClock4X clock driver
- <li class="inline"><a href="mailto:%20glenn@herald.usask.ca">Glenn Hollinger <glenn@herald.usask.ca></a> GOES clock driver
- <li class="inline"><a href="mailto:%20iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port
- <li class="inline"><a href="mailto:%20jagubox.gsfc.nasa.gov">Jim Jagielski <jim@jagubox.gsfc.nasa.gov></a> A/UX port
- <li class="inline"><a href="mailto:%20jbj@chatham.usdesign.com">Jeff Johnson <jbj@chatham.usdesign.com></a> massive prototyping overhaul
- <li class="inline"><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 class="inline"><a href="mailto:%20phk@FreeBSD.ORG">Poul-Henning Kamp <phk@FreeBSD.ORG></a> Oncore driver (Original author)
- <li class="inline"><a href="http://www4.informatik.uni-erlangen.de/%7ekardel">Frank Kardel</a> <a href="mailto:%20kardel (at) ntp (dot) org"><kardel (at) ntp (dot) org></a> PARSE <GENERIC> driver (>14 reference clocks), STREAMS modules for PARSE, support scripts, syslog cleanup, dynamic interface handling
- <li class="inline"><a href="mailto:%20jones@hermes.chpc.utexas.edu">William L. Jones <jones@hermes.chpc.utexas.edu></a> RS/6000 AIX modifications, HPUX modifications
- <li class="inline"><a href="mailto:%20dkatz@cisco.com">Dave Katz <dkatz@cisco.com></a> RS/6000 AIX port
- <li class="inline"><a href="mailto:%20leres@ee.lbl.gov">Craig Leres <leres@ee.lbl.gov></a> 4.4BSD port, ppsclock, Magnavox GPS clock driver
- <li class="inline"><a href="mailto:%20lindholm@ucs.ubc.ca">George Lindholm <lindholm@ucs.ubc.ca></a> SunOS 5.1 port
- <li class="inline"><a href="mailto:%20louie@ni.umd.edu">Louis A. Mamakos <louie@ni.umd.edu></a> MD5-based authentication
- <li class="inline"><a href="mailto:%20thorinn@diku.dk">Lars H. Mathiesen <thorinn@diku.dk></a> adaptation of foundation code for Version 3 as specified in RFC-1305
- <li class="inline"><a href="mailto:%20mayer@ntp.org">Danny Mayer <mayer@ntp.org></a>Network I/O, Windows Port, Code Maintenance
- <li class="inline"><a href="mailto:%20mills@udel.edu">David L. Mills <mills@udel.edu></a> Version 4 foundation: clock discipline, authentication, precision kernel; clock drivers: Spectracom, Austron, Arbiter, Heath, ATOM, ACTS, KSI/Odetics; audio clock drivers: CHU, WWV/H, IRIG
- <li class="inline"><a href="mailto:%20moeller@gwdgv1.dnet.gwdg.de">Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de></a> VMS port
- <li class="inline"><a href="mailto:%20mogul@pa.dec.com">Jeffrey Mogul <mogul@pa.dec.com></a> ntptrace utility
- <li class="inline"><a href="mailto:%20tmoore@fievel.daytonoh.ncr.com">Tom Moore <tmoore@fievel.daytonoh.ncr.com></a> i386 svr4 port
- <li class="inline"><a href="mailto:%20kamal@whence.com">Kamal A Mostafa <kamal@whence.com></a> SCO OpenServer port
- <li class="inline"><a href="mailto:%20derek@toybox.demon.co.uk">Derek Mulcahy <derek@toybox.demon.co.uk></a> and <a href="mailto:%20d@hd.org">Damon Hart-Davis <d@hd.org></a> ARCRON MSF clock driver
- <li class="inline"><a href="mailto:%20neal@ntp.org">Rob Neal <neal@ntp.org></a> Bancomm refclock and config/parse code maintenance
- <li class="inline"><a href="mailto:%20Rainer.Pruy@informatik.uni-erlangen.de">Rainer Pruy <Rainer.Pruy@informatik.uni-erlangen.de></a> monitoring/trap scripts, statistics file handling
- <li class="inline"><a href="mailto:%20dirce@zk3.dec.com">Dirce Richards <dirce@zk3.dec.com></a> Digital UNIX V4.0 port
- <li class="inline"><a href="mailto:%20wsanchez@apple.com">Wilfredo Sánchez <wsanchez@apple.com></a> added support for NetInfo
- <li class="inline"><a href="mailto:%20mrapple@quack.kfu.com">Nick Sayer <mrapple@quack.kfu.com></a> SunOS streams modules
- <li class="inline"><a href="mailto:%20jack@innovativeinternet.com">Jack Sasportas <jack@innovativeinternet.com></a> Saved a Lot of space on the stuff in the html/pic/ subdirectory
- <li class="inline"><a href="mailto:%20schnitz@unipress.com">Ray Schnitzler <schnitz@unipress.com></a> Unixware1 port
- <li class="inline"><a href="mailto:%20shields@tembel.org">Michael Shields <shields@tembel.org></a> USNO clock driver
- <li class="inline"><a href="mailto:%20pebbles.jpl.nasa.gov">Jeff Steinman <jss@pebbles.jpl.nasa.gov></a> Datum PTS clock driver
- <li class="inline"><a href="mailto:%20harlan@pfcs.com">Harlan Stenn <harlan@pfcs.com></a> GNU automake/autoconfigure makeover, various other bits (see the ChangeLog)
- <li class="inline"><a href="mailto:%20ken@sdd.hp.com">Kenneth Stone <ken@sdd.hp.com></a> HP-UX port
- <li class="inline"><a href="mailto:%20ajit@ee.udel.edu">Ajit Thyagarajan <ajit@ee.udel.edu></a>IP multicast/anycast support
- <li class="inline"><a href="mailto:%20tsuruoka@nc.fukuoka-u.ac.jp">Tomoaki TSURUOKA <tsuruoka@nc.fukuoka-u.ac.jp></a>TRAK clock driver
- <li class="inline"><a href="mailto:%20vixie@vix.com">Paul A Vixie <vixie@vix.com></a> TrueTime GPS driver, generic TrueTime clock driver
- <li class="inline"><a href="mailto:%20Ulrich.Windl@rz.uni-regensburg.de">Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de></a> corrected and validated HTML documents according to the HTML DTD
- </ol>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<p>The following individuals contributed in part to the Network Time Protocol Distribution Version 4 and are acknowledged as authors of this work.</p>
+<ol>
+ <li class="inline"><a href="mailto:%20mark_andrews@isc.org">Mark Andrews <mark_andrews@isc.org></a> Leitch atomic clock controller</li>
+ <li class="inline"><a href="mailto:%20altmeier@atlsoft.de">Bernd Altmeier <altmeier@atlsoft.de></a> hopf Elektronik serial line and PCI-bus devices</li>
+ <li class="inline"><a href="mailto:%20vbais@mailman1.intel.co">Viraj Bais <vbais@mailman1.intel.com></a> and <a href="mailto:%20kirkwood@striderfm.intel.com">Clayton Kirkwood <kirkwood@striderfm.intel.com></a> port to WindowsNT 3.5</li>
+ <li class="inline"><a href="mailto:%20michael.barone@lmco.com">Michael Barone <michael,barone@lmco.com></a> GPSVME fixes</li>
+ <li class="inline"><a href="mailto:%20karl@owl.HQ.ileaf.com">Karl Berry <karl@owl.HQ.ileaf.com></a> syslog to file option</li>
+ <li class="inline"><a href="mailto:%20greg.brackley@bigfoot.com">Greg Brackley <greg.brackley@bigfoot.com></a> Major rework of WINNT port. Clean up recvbuf and iosignal code into separate modules.</li>
+ <li class="inline"><a href="mailto:%20Marc.Brett@westgeo.com">Marc Brett <Marc.Brett@westgeo.com></a> Magnavox GPS clock driver</li>
+ <li class="inline"><a href="mailto:%20Piete.Brooks@cl.cam.ac.uk">Piete Brooks <Piete.Brooks@cl.cam.ac.uk></a> MSF clock driver, Trimble PARSE support</li>
+ <li class="inline"><a href="mailto:%20nelson@bolyard.me">Nelson B Bolyard <nelson@bolyard.me></a> update and complete broadcast and crypto features in sntp</li>
+ <li class="inline"><a href="mailto:%20Jean-Francois.Boudreault@viagenie.qc.ca">Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca></a> IPv6 support</li>
+ <li class="inline"><a href="mailto:%20reg@dwf.com">Reg Clemens <reg@dwf.com></a> Oncore driver (Current maintainer)</li>
+ <li class="inline"><a href="mailto:%20clift@ml.csiro.au">Steve Clift <clift@ml.csiro.au></a> OMEGA clock driver</li>
+ <li class="inline"><a href="mailto:casey@csc.co.za">Casey Crellin <casey@csc.co.za></a> vxWorks (Tornado) port and help with target configuration</li>
+ <li class="inline"><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 class="inline"><a href="mailto:%20dundas@salt.jpl.nasa.gov">John A. Dundas III <dundas@salt.jpl.nasa.gov></a> Apple A/UX port</li>
+ <li class="inline"><a href="mailto:%20duwe@immd4.informatik.uni-erlangen.de">Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de></a> Linux port</li>
+ <li class="inline"><a href="mailto:%20dennis@mrbill.canet.ca">Dennis Ferguson <dennis@mrbill.canet.ca></a> foundation code for NTP Version 2 as specified in RFC-1119</li>
+ <li class="inline"><a href="mailto:%20jhay@icomtek.csir.co.za">John Hay <jhay@icomtek.csir.co.za></a> IPv6 support and testing</li>
+ <li class="inline"><a href="mailto:%20davehart@davehart.com">Dave Hart <davehart@davehart.com></a> General maintenance, Windows port interpolation rewrite</li>
+ <li class="inline"><a href="mailto:%20neoclock4x@linum.com">Claas Hilbrecht <neoclock4x@linum.com></a> NeoClock4X clock driver</li>
+ <li class="inline"><a href="mailto:%20glenn@herald.usask.ca">Glenn Hollinger <glenn@herald.usask.ca></a> GOES clock driver</li>
+ <li class="inline"><a href="mailto:%20iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port</li>
+ <li class="inline"><a href="mailto:%20jagubox.gsfc.nasa.gov">Jim Jagielski <jim@jagubox.gsfc.nasa.gov></a> A/UX port</li>
+ <li class="inline"><a href="mailto:%20jbj@chatham.usdesign.com">Jeff Johnson <jbj@chatham.usdesign.com></a> massive prototyping overhaul</li>
+ <li class="inline"><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 class="inline"><a href="mailto:%20phk@FreeBSD.ORG">Poul-Henning Kamp <phk@FreeBSD.ORG></a> Oncore driver (Original author)</li>
+ <li class="inline"><a href="http://www4.informatik.uni-erlangen.de/%7ekardel">Frank Kardel</a> <a href="mailto:%20kardel (at) ntp (dot) org"><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 class="inline"><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 class="inline"><a href="mailto:%20dkatz@cisco.com">Dave Katz <dkatz@cisco.com></a> RS/6000 AIX port</li>
+ <li class="inline"><a href="mailto:%20leres@ee.lbl.gov">Craig Leres <leres@ee.lbl.gov></a> 4.4BSD port, ppsclock, Magnavox GPS clock driver</li>
+ <li class="inline"><a href="mailto:%20lindholm@ucs.ubc.ca">George Lindholm <lindholm@ucs.ubc.ca></a> SunOS 5.1 port</li>
+ <li class="inline"><a href="mailto:%20louie@ni.umd.edu">Louis A. Mamakos <louie@ni.umd.edu></a> MD5-based authentication</li>
+ <li class="inline"><a href="mailto:%20thorinn@diku.dk">Lars H. Mathiesen <thorinn@diku.dk></a> adaptation of foundation code for Version 3 as specified in RFC-1305</li>
+ <li class="inline"><a href="mailto:%20mayer@ntp.org">Danny Mayer <mayer@ntp.org></a>Network I/O, Windows Port, Code Maintenance</li>
+ <li class="inline"><a href="mailto:%20mills@udel.edu">David L. Mills <mills@udel.edu></a> Version 4 foundation, precision kernel; clock drivers: 1, 3, 4, 6, 7, 11, 13, 18, 19, 22, 36</li>
+ <li class="inline"><a href="mailto:%20moeller@gwdgv1.dnet.gwdg.de">Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de></a> VMS port</li>
+ <li class="inline"><a href="mailto:%20mogul@pa.dec.com">Jeffrey Mogul <mogul@pa.dec.com></a> ntptrace utility</li>
+ <li class="inline"><a href="mailto:%20tmoore@fievel.daytonoh.ncr.com">Tom Moore <tmoore@fievel.daytonoh.ncr.com></a> i386 svr4 port</li>
+ <li class="inline"><a href="mailto:%20kamal@whence.com">Kamal A Mostafa <kamal@whence.com></a> SCO OpenServer port</li>
+ <li class="inline"><a href="mailto:%20derek@toybox.demon.co.uk">Derek Mulcahy <derek@toybox.demon.co.uk></a> and <a href="mailto:%20d@hd.org">Damon Hart-Davis <d@hd.org></a> ARCRON MSF clock driver</li>
+ <li class="inline"><a href="mailto:%20neal@ntp.org">Rob Neal <neal@ntp.org></a> Bancomm refclock and config/parse code maintenance</li>
+ <li class="inline"><a href="mailto:%20Rainer.Pruy@informatik.uni-erlangen.de">Rainer Pruy <Rainer.Pruy@informatik.uni-erlangen.de></a> monitoring/trap scripts, statistics file handling</li>
+ <li class="inline"><a href="mailto:%20dirce@zk3.dec.com">Dirce Richards <dirce@zk3.dec.com></a> Digital UNIX V4.0 port</li>
+ <li class="inline"><a href="mailto:%20wsanchez@apple.com">Wilfredo Sánchez <wsanchez@apple.com></a> added support for NetInfo</li>
+ <li class="inline"><a href="mailto:%20mrapple@quack.kfu.com">Nick Sayer <mrapple@quack.kfu.com></a> SunOS streams modules</li>
+ <li class="inline"><a href="mailto:%20jack@innovativeinternet.com">Jack Sasportas <jack@innovativeinternet.com></a> Saved a Lot of space on the stuff in the html/pic/ subdirectory</li>
+ <li class="inline"><a href="mailto:%20schnitz@unipress.com">Ray Schnitzler <schnitz@unipress.com></a> Unixware1 port</li>
+ <li class="inline"><a href="mailto:%20shields@tembel.org">Michael Shields <shields@tembel.org></a> USNO clock driver</li>
+ <li class="inline"><a href="mailto:%20pebbles.jpl.nasa.gov">Jeff Steinman <jss@pebbles.jpl.nasa.gov></a> Datum PTS clock driver</li>
+ <li class="inline"><a href="mailto:%20harlan@pfcs.com">Harlan Stenn <harlan@pfcs.com></a> GNU automake/autoconfigure makeover, various other bits (see the ChangeLog)</li>
+ <li class="inline"><a href="mailto:%20ken@sdd.hp.com">Kenneth Stone <ken@sdd.hp.com></a> HP-UX port</li>
+ <li class="inline"><a href="mailto:%20ajit@ee.udel.edu">Ajit Thyagarajan <ajit@ee.udel.edu></a>IP multicast/anycast support</li>
+ <li class="inline"><a href="mailto:%20tsuruoka@nc.fukuoka-u.ac.jp">Tomoaki TSURUOKA <tsuruoka@nc.fukuoka-u.ac.jp></a>TRAK clock driver</li>
+ <li class="inline"><a href="mailto:%20vixie@vix.com">Paul A Vixie <vixie@vix.com></a> TrueTime GPS driver, generic TrueTime clock driver</li>
+ <li class="inline"><a href="mailto:%20Ulrich.Windl@rz.uni-regensburg.de">Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de></a> corrected and validated HTML documents according to the HTML DTD</li>
+</ol>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>NTP Debugging Techniques</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>NTP Debugging Techniques</h3>
- <img src="pic/pogo.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>We make house calls and bring our own bugs.</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->16-Jul-2009 19:36<!-- #EndDate -->
- UTC</p>
- <h4>More Help</h4>
- <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
- <hr>
- <h4>Initial Startup</h4>
- <p>This page discusses <tt>ntpd</tt> program monitoring and debugging techniques using the <a href="ntpq.html"><tt>ntpq</tt> - standard NTP query program</a>, either on the local server or from a remote machine. In special circumstances the <a href="ntpdc.html"><tt>ntpdc</tt> - special NTP query program</a>, can be useful, but its use is not covered here. The <tt>ntpq</tt> program implements the management functions specified in the NTP specification <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305c.ps">RFC-1305, Appendix A</a>. It is used to read and write the variables defined in the NTP Version 4 specification now navigating the standards process. In addition, the program can be used to send remote configuration commands to the server.</p>
- <p>The <tt>ntpd</tt> daemon can operate in two modes, depending on the presence of the <tt>-d</tt> command-line option. Without the option the daemon detaches from the controlling terminal and proceeds autonomously. With one or more <tt>-d</tt> options the daemon does not detach and generates special trace output useful for debugging. In general, interpretation of this output requires reference to the sources. However, a single <tt>-d</tt> does produce only mildly cryptic output and can be very useful in finding problems with configuration and network troubles.</p>
- <p>Some problems are immediately apparent when the daemon first starts running. The most common of these are the lack of a UDP port for NTP (123) in the Unix <tt>/etc/services</tt> file (or equivalent in some systems). <b>Note that NTP does not use TCP in any form. Also note that NTP requires port 123 for both source and destination ports.</b> These facts should be pointed out to firewall administrators.</p>
- <p>Other problems are apparent in the system log, which ordinarily shows the startup banner, some cryptic initialization data and the computed precision value. Event messages at startup and during regular operation are sent to the optional <tt>protostats</tt> monitor file, as described on the <a href="decode.html">Event Messages and Status Words</a> page. These and other error messages are sent to the system log, as described on the <a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> page. In real emergencies the daemon will sent a terminal error message to the system log and then cease operation.</p>
- <p>The next most common problem is incorrect DNS names. Check that each DNS name used in the configuration file exists and that the address responds to the Unix <tt>ping</tt> command. The Unix <tt>traceroute</tt> or Windows <tt>tracert</tt> utility can be used to verify a partial or complete path exists. Most problems reported to the NTP newsgroup are not NTP problems, but problems with the network or firewall configuration.</p>
- <h4>Verifying Correct Operation</h4>
- <p>Unless using the <tt>iburst</tt> option, the client normally takes a few
- minutes to synchronize to a server. If the client time at startup happens
- to be more than 1000 s distant from NTP time, the daemon exits with a message
- to the system log directing the operator to manually set the time within 1000
- s and restart. If the time is less than 1000 s but more than 128 s distant,
- a step correction occurs and the daemon restarts automatically.</p>
- <p>When started for the first time and a frequency file is not present, the
- daemon enters a special mode in order to calibrate the frequency. This takes
- 900 s during which the time is not disciplined. When calibration is complete,
- the daemon creates the frequency file and enters normal mode to amortize whatever
- residual offset remains.</p>
- <p>The <tt>ntpq</tt> commands <tt>pe</tt>, <tt>as</tt> and <tt>rv</tt> are
- normally sufficient to verify correct operation and assess nominal performance.
- The <a href="ntpq.html#pe"><tt>pe</tt></a> command displays a list showing
- the DNS name or IP address for each association along with selected status
- and statistics variables. The first character in each line is the tally code,
- which shows which associations are candidates to set the system clock and
- of these which one is the system peer. The encoding is shown in the <tt>select</tt>
- field of the <a href="decode.html#peer">peer status word</a>.</p>
- <p>The <a href="ntpq.html#as"><tt>as</tt></a> command displays a list of associations and association identifiers. Note the <tt>condition</tt> column, which reflects the tally code. The <a href="ntpq.html#pe"><tt>rv</tt></a> command displays the <a href="ntpq.html#system">system variables</a> billboard, including the <a href="decode.html#sys">system status word</a>. The <a href="ntpq.html#rv"><tt>rv <i>assocID</i></tt></a> command, where <tt><i>assocID</i></tt> is the association ID, displays the <a href="ntpq.html#peer">peer variables</a> billboard, including the <a href="decode.html#peer">peer status word</a>. Note that, except for explicit calendar dates, times are in milliseconds and frequencies are in parts-per-million (PPM).</p>
- <p>A detailed explanation of the system, peer and clock variables in the billboards is beyond the scope of this page; however, a comprehensive explanation for each one is in the NTPv4 protocol specification. The following observations will be useful in debugging and monitoring.</p>
- <ol>
- <li>The server has successfully synchronized to its sources if the <tt>leap</tt> peer
- variable has value other than 3 (11b) The client has successfully synchronized
- to the server when the <tt>leap</tt> system variable has value other than
- 3.
- <li>The <tt>reach</tt> peer variable is an 8-bit shift register displayed in octal format. When a valid packet is received, the rightmost bit is lit. When a packet is sent, the register is shifted left one bit with 0 replacing the rightmost bit. If the <tt>reach</tt> value is nonzero, the server is reachable; otherwise, it is unreachable. Note that, even if all servers become unreachable, the system continues to show valid time to dependent applications.
- <li>A useful indicator of miscellaneous problems is the <tt>flash</tt> peer variable, which shows the result of 13 sanity tests. It contains the <a href="decode.html#flash">flash status word</a> bits, commonly called flashers, which displays the current errors for the association. These bits should all be zero for a valid server.
- <li>The three peer variables <tt>filtdelay</tt>, <tt>filtoffset</tt> and <tt>filtdisp</tt> show the delay, offset and jitter statistics for each of the last eight measurement rounds. These statistics and their trends are valuable performance indicators for the server, client and the network. For instance, large fluctuations in delay and jitter suggest network congestion. Missing clock filter stages suggest packet losses in the network.
- <li>The synchronization distance, defined as one-half the delay plus the dispersion, represents the maximum error statistic. The jitter represents the expected error statistic. The maximum error and expected error calculated from the peer variables represents the quality metric for the server. The maximum error and expected error calculated from the system variables represents the quality metric for the client. If the root synchronization distance for any server exceeds 1.5 s, called the select threshold, the server is considered invalid.</ol>
- <h4>Large Frequency Errors</h4>
- <p>The frequency tolerance of computer clock oscillators varies widely, sometimes above 500 PPM. While the daemon can handle frequency errors up to 500 PPM, or 43 seconds per day, values much above 100 PPM reduce the headroom, especially at the lowest poll intervals. To determine the particular oscillator frequency, start <tt>ntpd</tt> using the <tt>noselect</tt> option with the <tt>server</tt> configuration command.</p>
- <p>Record the time of day and offset displayed by the <tt>ntpq</tt> <a href="ntpq.html#pe"><tt>pe</tt></a> command. Wait for an hour or so and record the time of day and offset. Calculate the frequency as the offset difference divided by the time difference. If the frequency is much above 100 PPM, the <a href="tickadj.html">tickadj</a> program might be useful to adjust the kernel clock frequency below that value. For systems that do not support this program, this might be one using a command in the system startup file.</p>
- <h4>Access Controls</h4>
- <p>Provisions are included in <tt>ntpd</tt> for access controls which deflect unwanted traffic from selected hosts or networks. The controls described on the <a href="accopt.html">Access Control Options</a> include detailed packet filter operations based on source address and address mask. Normally, filtered packets are dropped without notice other than to increment tally counters. However, the server can be configured to send a "kiss-o'-death" (KOD) packet to the client either when explicitly configured or when cryptographic authentication fails for some reason. The client association is permanently disabled, the access denied bit (TEST4) is set in the flash variable and a message is sent to the system log.</p>
- <p>The access control provisions include a limit on the packet rate from a
- host or network. If an incoming packet exceeds the limit, it is dropped and
- a KOD sent to the source. If this occurs after the client association has
- synchronized, the association is not disabled, but a message is sent to the
- system log. See the <a href="accopt.html">Access Control Options</a> page
- for further information.</p>
- <h4>Large Delay Variations</h4>
- <p>In some reported scenarios an access line may show low to moderate network delays during some period of the day and moderate to high delays during other periods. Often the delay on one direction of transmission dominates, which can result in large time offset errors, sometimes in the range up to a few seconds. It is not usually convenient to run <tt>ntpd</tt> throughout the day in such scenarios, since this could result in several time steps, especially if the condition persists for greater than the stepout threshold.</p>
- <p>Specific provisions have been built into <tt>ntpd</tt> to cope with these problems. The scheme is called "huff-'n-puff and is described on the <a href="miscopt.html">Miscellaneous Options</a> page. An alternative approach in such scenarios is first to calibrate the local clock frequency error by running <tt>ntpd</tt> in continuous mode during the quiet interval and let it write the frequency to the <tt>ntp.drift</tt> file. Then, run <tt>ntpd -q</tt> from a cron job each day at some time in the quiet interval. In systems with the nanokernel or microkernel performance enhancements, including Solaris, Tru64, Linux and FreeBSD, the kernel continuously disciplines the frequency so that the residual correction produced by <tt>ntpd</tt> is usually less than a few milliseconds.</p>
- <h4>Cryptographic Authentication</h4>
- <p>Reliable source authentication requires the use of symmetric key or public key cryptography, as described on the <a href="authopt.html">Authentication Options</a> page. In symmetric key cryptography servers and clients share session keys contained in a secret key file In public key cryptography, which requires the OpenSSL software library, the server has a private key, never shared, and a public key with unrestricted distribution. The cryptographic media required are produced by the <a href="keygen.html"><tt>ntp-keygen</tt></a> program.</p>
- <p>Problems with symmetric key authentication are usually due to mismatched keys or improper use of the <tt>trustedkey</tt> command. A simple way to check for problems is to use the trace facility, which is enabled using the <tt>ntpd -d</tt> command line. As each packet is received a trace line is displayed which shows the authentication status in the <tt>auth</tt> field. A status of 1 indicates the packet was successful authenticated; otherwise it has failed.</p>
- <p>A common misconception is the implication of the <tt>auth</tt> bit in the <tt>enable</tt> and <tt>disable</tt> commands. <b>This bit does not affect authentication in any way other than to enable or disable mobilization of a new persistent association in broadcast/multicast client, manycast client or symmetric passive modes.</b> If enabled, which is the default, these associations require authentication; if not, an association is mobilized even if not authenticated. Users are cautioned that running with authentication disabled is very dangerous, since an intruder can easily strike up an association and inject false time values.</p>
- <p>Public key cryptography is supported in NTPv4 using the Autokey protocol, which is described in briefings on the NTP Project page linked from www.ntp.org. Development of this protocol is mature and the <tt>ntpd</tt> implementation is basically complete. Autokey version 2, which is the latest and current version, includes provisions to hike certificate trails, operate as certificate authorities and verify identity using challenge/response identification schemes. Further details of the protocol are on the <a href="authopt.html">Authentication Options</a> page. Common problems with configuration and key generation are mismatched key files, broken links and missing or broken random seed file.</p>
- <p>As in the symmetric key cryptography case, the trace facility is a good way to verify correct operation. A statistics file <tt>cryptostats</tt> records protocol transactions and error messages. The daemon requires a random seed file, public/private key file and a valid certificate file; otherwise it exits immediately with a message to the system log. As each file is loaded a trace message appears with its filestamp. There are a number of checks to insure that only consistent data are used and that the certificate is valid. When the protocol is in operation a number of checks are done to verify the server has the expected credentials and its filestamps and timestamps are consistent. Errors found are reported using NTP control and monitoring protocol traps with extended trap codes shown in the Authentication Options page.</p>
- <p>To assist debugging every NTP extension field is displayed in the trace along with the Autokey operation code. Every extension field carrying a verified signature is identified and displayed along with filestamp and timestamp where meaningful. In all except broadcast/multicast client mode, correct operation of the protocol is confirmed by the absence of extension fields and an <tt>auth</tt> value of one. It is normal in broadcast/multicast client mode that the broadcast server use one extension field to show the host name, status word and association ID.</p>
- <h4>Debugging Checklist</h4>
- <p>If the <tt>ntpq</tt> or <tt>ntpdc</tt> programs do not show that messages are being received by the daemon or that received messages do not result in correct synchronization, verify the following:</p>
- <ol>
- <li>Verify the <tt>/etc/services</tt> file host machine is configured to accept UDP packets on the NTP port 123. NTP is specifically designed to use UDP and does not respond to TCP.
- <li>Check the system log for <tt>ntpd</tt> messages about configuration errors, name-lookup failures or initialization problems. Common system log messages are summarized on the <a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> page. Check to be sure that only one copy of <tt>ntpd</tt> is running.
- <li>Verify using <tt>ping</tt> or other utility that packets actually do make the round trip between the client and server. Verify using <tt>nslookup</tt> or other utility that the DNS server names do exist and resolve to valid Internet addresses.
- <li>Check that the remote NTP server is up and running. The usual evidence that it is not is a <tt>Connection refused</tt> message.
- <li>Using the <tt>ntpdc</tt> program, verify that the packets received and packets sent counters are incrementing. If the sent counter does not increment and the configuration file includes configured servers, something may be wrong in the host network or interface configuration. If this counter does increment, but the received counter does not increment, something may be wrong in the network or the server NTP daemon may not be running or the server itself may be down or not responding.
- <li>If both the sent and received counters do increment, but the <tt>reach</tt> values in the <tt>pe</tt> billboard with <tt>ntpq</tt> continues to show zero, received packets are probably being discarded for some reason. If this is the case, the cause should be evident from the <tt>flash</tt> variable as discussed above and on the <tt>ntpq</tt> page. It could be that the server has disabled access for the client address, in which case the <tt>refid</tt> field in the <tt>ntpq pe</tt> billboard will show a kiss code. See earlier on this page for a list of kiss codes and their meaning.
- <li>If the <tt>reach</tt> values in the <tt>pe</tt> billboard show the servers are alive and responding, note the tattletale symbols at the left margin, which indicate the status of each server resulting from the various grooming and mitigation algorithms. The interpretation of these symbols is discussed on the <tt>ntpq</tt> page. After a few minutes of operation, one or another of the reachable server candidates should show a * tattletale symbol. If this doesn't happen, the intersection algorithm, which classifies the servers as truechimers or falsetickers, may be unable to find a majority of truechimers among the server population.
- <li>If all else fails, see the FAQ and/or the discussion and briefings at the NTP Project page.
- </ol>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>NTP Debugging Techniques</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>NTP Debugging Techniques</h3>
+<img src="pic/pogo.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>We make house calls and bring our own bugs.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 21:44<!-- #EndDate -->
+ UTC</p>
+<h4>More Help</h4>
+<script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+<hr>
+<h4>Initial Startup</h4>
+<p>This page discusses <tt>ntpd</tt> program monitoring and debugging techniques using the <a href="ntpq.html"><tt>ntpq</tt> - standard NTP query program</a>, either on the local server or from a remote machine. In special circumstances the <a href="ntpdc.html"><tt>ntpdc</tt> - special NTP query program</a>, can be useful, but its use is not covered here. The <tt>ntpq</tt> program implements the management functions specified in the NTP specification <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305c.ps">RFC-1305, Appendix A</a>. It is used to read and write the variables defined in the NTP Version 4 specification now navigating the standards process. In addition, the program can be used to send remote configuration commands to the server.</p>
+<p>The <tt>ntpd</tt> daemon can operate in two modes, depending on the presence of the <tt>-d</tt> command-line option. Without the option the daemon detaches from the controlling terminal and proceeds autonomously. With one or more <tt>-d</tt> options the daemon does not detach and generates special trace output useful for debugging. In general, interpretation of this output requires reference to the sources. However, a single <tt>-d</tt> does produce only mildly cryptic output and can be very useful in finding problems with configuration and network troubles.</p>
+<p>Some problems are immediately apparent when the daemon first starts running. The most common of these are the lack of a UDP port for NTP (123) in the Unix <tt>/etc/services</tt> file (or equivalent in some systems). <b>Note that NTP does not use TCP in any form. Also note that NTP requires port 123 for both source and destination ports.</b> These facts should be pointed out to firewall administrators.</p>
+<p>Other problems are apparent in the system log, which ordinarily shows the startup banner, some cryptic initialization data and the computed precision value. Event messages at startup and during regular operation are sent to the optional <tt>protostats</tt> monitor file, as described on the <a href="decode.html">Event Messages and Status Words</a> page. These and other error messages are sent to the system log, as described on the <a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> page. In real emergencies the daemon will sent a terminal error message to the system log and then cease operation.</p>
+<p>The next most common problem is incorrect DNS names. Check that each DNS name used in the configuration file exists and that the address responds to the Unix <tt>ping</tt> command. The Unix <tt>traceroute</tt> or Windows <tt>tracert</tt> utility can be used to verify a partial or complete path exists. Most problems reported to the NTP newsgroup are not NTP problems, but problems with the network or firewall configuration.</p>
+<h4>Verifying Correct Operation</h4>
+<p>Unless using the <tt>iburst</tt> option, the client normally takes a few
+ minutes to synchronize to a server. If the client time at startup happens
+ to be more than 1000 s distant from NTP time, the daemon exits with a message
+ to the system log directing the operator to manually set the time within 1000
+ s and restart. If the time is less than 1000 s but more than 128 s distant,
+ a step correction occurs and the daemon restarts automatically.</p>
+<p>When started for the first time and a frequency file is not present, the
+ daemon enters a special mode in order to calibrate the frequency. This takes
+ 900 s during which the time is not disciplined. When calibration is complete,
+ the daemon creates the frequency file and enters normal mode to amortize whatever
+ residual offset remains.</p>
+<p>The <tt>ntpq</tt> commands <tt>pe</tt>, <tt>as</tt> and <tt>rv</tt> are
+ normally sufficient to verify correct operation and assess nominal performance.
+ The <a href="ntpq.html#pe"><tt>pe</tt></a> command displays a list showing
+ the DNS name or IP address for each association along with selected status
+ and statistics variables. The first character in each line is the tally code,
+ which shows which associations are candidates to set the system clock and
+ of these which one is the system peer. The encoding is shown in the <tt>select</tt> field of the <a href="decode.html#peer">peer status word</a>.</p>
+<p>The <a href="ntpq.html#as"><tt>as</tt></a> command displays a list of associations and association identifiers. Note the <tt>condition</tt> column, which reflects the tally code. The <a href="ntpq.html#pe"><tt>rv</tt></a> command displays the <a href="ntpq.html#system">system variables</a> billboard, including the <a href="decode.html#sys">system status word</a>. The <a href="ntpq.html#rv"><tt>rv <i>assocID</i></tt></a> command, where <tt><i>assocID</i></tt> is the association ID, displays the <a href="ntpq.html#peer">peer variables</a> billboard, including the <a href="decode.html#peer">peer status word</a>. Note that, except for explicit calendar dates, times are in milliseconds and frequencies are in parts-per-million (PPM).</p>
+<p>A detailed explanation of the system, peer and clock variables in the billboards is beyond the scope of this page; however, a comprehensive explanation for each one is in the NTPv4 protocol specification. The following observations will be useful in debugging and monitoring.</p>
+<ol>
+ <li>The server has successfully synchronized to its sources if the <tt>leap</tt> peer
+ variable has value other than 3 (11b) The client has successfully synchronized
+ to the server when the <tt>leap</tt> system variable has value other than
+ 3.</li>
+ <li>The <tt>reach</tt> peer variable is an 8-bit shift register displayed in octal format. When a valid packet is received, the rightmost bit is lit. When a packet is sent, the register is shifted left one bit with 0 replacing the rightmost bit. If the <tt>reach</tt> value is nonzero, the server is reachable; otherwise, it is unreachable. Note that, even if all servers become unreachable, the system continues to show valid time to dependent applications.</li>
+ <li>A useful indicator of miscellaneous problems is the <tt>flash</tt> peer variable, which shows the result of 13 sanity tests. It contains the <a href="decode.html#flash">flash status word</a> bits, commonly called flashers, which displays the current errors for the association. These bits should all be zero for a valid server.</li>
+ <li>The three peer variables <tt>filtdelay</tt>, <tt>filtoffset</tt> and <tt>filtdisp</tt> show the delay, offset and jitter statistics for each of the last eight measurement rounds. These statistics and their trends are valuable performance indicators for the server, client and the network. For instance, large fluctuations in delay and jitter suggest network congestion. Missing clock filter stages suggest packet losses in the network.</li>
+ <li>The synchronization distance, defined as one-half the delay plus the dispersion, represents the maximum error statistic. The jitter represents the expected error statistic. The maximum error and expected error calculated from the peer variables represents the quality metric for the server. The maximum error and expected error calculated from the system variables represents the quality metric for the client. If the root synchronization distance for any server exceeds 1.5 s, called the select threshold, the server is considered invalid.</li>
+</ol>
+<h4>Large Frequency Errors</h4>
+<p>The frequency tolerance of computer clock oscillators varies widely, sometimes above 500 PPM. While the daemon can handle frequency errors up to 500 PPM, or 43 seconds per day, values much above 100 PPM reduce the headroom, especially at the lowest poll intervals. To determine the particular oscillator frequency, start <tt>ntpd</tt> using the <tt>noselect</tt> option with the <tt>server</tt> configuration command.</p>
+<p>Record the time of day and offset displayed by the <tt>ntpq</tt> <a href="ntpq.html#pe"><tt>pe</tt></a> command. Wait for an hour or so and record the time of day and offset. Calculate the frequency as the offset difference divided by the time difference. If the frequency is much above 100 PPM, the <a href="tickadj.html">tickadj</a> program might be useful to adjust the kernel clock frequency below that value. For systems that do not support this program, this might be one using a command in the system startup file.</p>
+<h4>Access Controls</h4>
+<p>Provisions are included in <tt>ntpd</tt> for access controls which deflect unwanted traffic from selected hosts or networks. The controls described on the <a href="accopt.html">Access Control Options</a> include detailed packet filter operations based on source address and address mask. Normally, filtered packets are dropped without notice other than to increment tally counters. However, the server can be configured to send a "kiss-o'-death" (KOD) packet to the client either when explicitly configured or when cryptographic authentication fails for some reason. The client association is permanently disabled, the access denied bit (TEST4) is set in the flash variable and a message is sent to the system log.</p>
+<p>The access control provisions include a limit on the packet rate from a
+ host or network. If an incoming packet exceeds the limit, it is dropped and
+ a KOD sent to the source. If this occurs after the client association has
+ synchronized, the association is not disabled, but a message is sent to the
+ system log. See the <a href="accopt.html">Access Control Options</a> page
+ for further information.</p>
+<h4>Large Delay Variations</h4>
+<p>In some reported scenarios an access line may show low to moderate network delays during some period of the day and moderate to high delays during other periods. Often the delay on one direction of transmission dominates, which can result in large time offset errors, sometimes in the range up to a few seconds. It is not usually convenient to run <tt>ntpd</tt> throughout the day in such scenarios, since this could result in several time steps, especially if the condition persists for greater than the stepout threshold.</p>
+<p>Specific provisions have been built into <tt>ntpd</tt> to cope with these problems. The scheme is called "huff-'n-puff and is described on the <a href="miscopt.html">Miscellaneous Options</a> page. An alternative approach in such scenarios is first to calibrate the local clock frequency error by running <tt>ntpd</tt> in continuous mode during the quiet interval and let it write the frequency to the <tt>ntp.drift</tt> file. Then, run <tt>ntpd -q</tt> from a cron job each day at some time in the quiet interval. In systems with the nanokernel or microkernel performance enhancements, including Solaris, Tru64, Linux and FreeBSD, the kernel continuously disciplines the frequency so that the residual correction produced by <tt>ntpd</tt> is usually less than a few milliseconds.</p>
+<h4>Cryptographic Authentication</h4>
+<p>Reliable source authentication requires the use of symmetric key or public key cryptography, as described on the <a href="authopt.html">Authentication Options</a> page. In symmetric key cryptography servers and clients share session keys contained in a secret key file In public key cryptography, which requires the OpenSSL software library, the server has a private key, never shared, and a public key with unrestricted distribution. The cryptographic media required are produced by the <a href="keygen.html"><tt>ntp-keygen</tt></a> program.</p>
+<p>Problems with symmetric key authentication are usually due to mismatched keys or improper use of the <tt>trustedkey</tt> command. A simple way to check for problems is to use the trace facility, which is enabled using the <tt>ntpd -d</tt> command line. As each packet is received a trace line is displayed which shows the authentication status in the <tt>auth</tt> field. A status of 1 indicates the packet was successful authenticated; otherwise it has failed.</p>
+<p>A common misconception is the implication of the <tt>auth</tt> bit in the <tt>enable</tt> and <tt>disable</tt> commands. <b>This bit does not affect authentication in any way other than to enable or disable mobilization of a new persistent association in broadcast/multicast client, manycast client or symmetric passive modes.</b> If enabled, which is the default, these associations require authentication; if not, an association is mobilized even if not authenticated. Users are cautioned that running with authentication disabled is very dangerous, since an intruder can easily strike up an association and inject false time values.</p>
+<p>Public key cryptography is supported in NTPv4 using the Autokey protocol, which is described in briefings on the NTP Project page linked from www.ntp.org. Development of this protocol is mature and the <tt>ntpd</tt> implementation is basically complete. Autokey version 2, which is the latest and current version, includes provisions to hike certificate trails, operate as certificate authorities and verify identity using challenge/response identification schemes. Further details of the protocol are on the <a href="authopt.html">Authentication Options</a> page. Common problems with configuration and key generation are mismatched key files, broken links and missing or broken random seed file.</p>
+<p>As in the symmetric key cryptography case, the trace facility is a good way to verify correct operation. A statistics file <tt>cryptostats</tt> records protocol transactions and error messages. The daemon requires a random seed file, public/private key file and a valid certificate file; otherwise it exits immediately with a message to the system log. As each file is loaded a trace message appears with its filestamp. There are a number of checks to insure that only consistent data are used and that the certificate is valid. When the protocol is in operation a number of checks are done to verify the server has the expected credentials and its filestamps and timestamps are consistent. Errors found are reported using NTP control and monitoring protocol traps with extended trap codes shown in the Authentication Options page.</p>
+<p>To assist debugging every NTP extension field is displayed in the trace along with the Autokey operation code. Every extension field carrying a verified signature is identified and displayed along with filestamp and timestamp where meaningful. In all except broadcast/multicast client mode, correct operation of the protocol is confirmed by the absence of extension fields and an <tt>auth</tt> value of one. It is normal in broadcast/multicast client mode that the broadcast server use one extension field to show the host name, status word and association ID.</p>
+<h4>Debugging Checklist</h4>
+<p>If the <tt>ntpq</tt> or <tt>ntpdc</tt> programs do not show that messages are being received by the daemon or that received messages do not result in correct synchronization, verify the following:</p>
+<ol>
+ <li>Verify the <tt>/etc/services</tt> file host machine is configured to accept UDP packets on the NTP port 123. NTP is specifically designed to use UDP and does not respond to TCP.</li>
+ <li>Check the system log for <tt>ntpd</tt> messages about configuration errors, name-lookup failures or initialization problems. Common system log messages are summarized on the <a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> page. Check to be sure that only one copy of <tt>ntpd</tt> is running.</li>
+ <li>Verify using <tt>ping</tt> or other utility that packets actually do make the round trip between the client and server. Verify using <tt>nslookup</tt> or other utility that the DNS server names do exist and resolve to valid Internet addresses.</li>
+ <li>Check that the remote NTP server is up and running. The usual evidence that it is not is a <tt>Connection refused</tt> message.</li>
+ <li>Using the <tt>ntpdc</tt> program, verify that the packets received and packets sent counters are incrementing. If the sent counter does not increment and the configuration file includes configured servers, something may be wrong in the host network or interface configuration. If this counter does increment, but the received counter does not increment, something may be wrong in the network or the server NTP daemon may not be running or the server itself may be down or not responding.</li>
+ <li>If both the sent and received counters do increment, but the <tt>reach</tt> values in the <tt>pe</tt> billboard with <tt>ntpq</tt> continues to show zero, received packets are probably being discarded for some reason. If this is the case, the cause should be evident from the <tt>flash</tt> variable as discussed above and on the <tt>ntpq</tt> page. It could be that the server has disabled access for the client address, in which case the <tt>refid</tt> field in the <tt>ntpq pe</tt> billboard will show a kiss code. See earlier on this page for a list of kiss codes and their meaning.</li>
+ <li>If the <tt>reach</tt> values in the <tt>pe</tt> billboard show the servers are alive and responding, note the tattletale symbols at the left margin, which indicate the status of each server resulting from the various grooming and mitigation algorithms. The interpretation of these symbols is discussed on the <tt>ntpq</tt> page. After a few minutes of operation, one or another of the reachable server candidates should show a * tattletale symbol. If this doesn't happen, the intersection algorithm, which classifies the servers as truechimers or falsetickers, may be unable to find a majority of truechimers among the server population.</li>
+ <li>If all else fails, see the FAQ and/or the discussion and briefings at the NTP Project page.</li>
+</ol>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
+<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
-<title>ntpd Event Messages and Status Words</title>
+<title>Event Messages and Status Words</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
<body>
<h3>Event Messages and Status Words</h3>
<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 -->30-Apr-2010 23:13<!-- #EndDate -->
-UTC</p>
+ <!-- #BeginDate format:En2m -->10-Sep-2010 0:20<!-- #EndDate -->
+ UTC</p>
<br clear="left">
-
<h4>Related Links</h4>
-
-<p><script type="text/javascript" language="javascript" src="scripts/install.txt"></script></p>
-
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+</p>
<h4>Table of Contents</h4>
-
<ul>
-<li class="inline"><a href="#intro">Introduction</a></li>
-<li class="inline"><a href="#sys">System Status Word</a></li>
-<li class="inline"><a href="#peer">Peer Status Word</a></li>
-<li class="inline"><a href="#clock">Clock Status Word</a></li>
-<li class="inline"><a href="#flash">Flash Status Word</a></li>
-<li class="inline"><a href="#kiss">Kiss Codes</a></li>
-<li class="inline"><a href="#crypto">Crypto Messages</a></li>
+
<li class="inline"><a href="#intro">Introduction</a></li>
+
<li class="inline"><a href="#sys">System Status Word</a></li>
+
<li class="inline"><a href="#peer">Peer Status Word</a></li>
+
<li class="inline"><a href="#clock">Clock Status Word</a></li>
+
<li class="inline"><a href="#flash">Flash Status Word</a></li>
+
<li class="inline"><a href="#kiss">Kiss Codes</a></li>
+
<li class="inline"><a href="#crypto">Crypto Messages</a></li>
</ul>
-
<hr>
-
<h4 id="intro">Introduction</h4>
-
<p>This page lists the status words, event messages and error codes used for <tt>ntpd</tt> reporting and monitoring. Status words are used to display the current status of the running program. There is one system status word and a peer status word for each association. There is a clock status word for each association that supports a reference clock. There is a flash code for each association which shows errors found in the last packet received (pkt) and during protocol processing (peer). These are commonly viewed using the <tt>ntpq</tt> program.</p>
-
<p>Significant changes in program state are reported as events. There is one
- set of system events and a set of peer events for each association. In addition,
- there is a set of clock events for each association that supports a reference
- clock. Events are normally reported to the <tt>protostats</tt> monitoring file
- and optionally to the system log. In addition, if the trap facility is configured,
- events can be reported to a remote program that can page an administrator.</p>
-
+ set of system events and a set of peer events for each association. In addition,
+ there is a set of clock events for each association that supports a reference
+ clock. Events are normally reported to the <tt>protostats</tt> monitoring file
+ and optionally to the system log. In addition, if the trap facility is configured,
+ events can be reported to a remote program that can page an administrator.</p>
<p>This page also includes a description of the error messages produced by the Autokey protocol. These messages are normally sent to the <tt>cryptostats</tt> monitoring file.</p>
-
<p>In the following tables the Code Field is the status or event code assigned and the Message Field a short string used for display and event reporting. The Description field contains a longer explanation of the status or event. Some messages include additional information useful for error diagnosis and performance assessment.</p>
-
<h4 id="sys">System Status Word</h4>
-
<p>The system status word consists of four fields LI (0-1), Source (2-7), Count (8-11) and Code (12-15). It is reported in the first line of the <tt>rv</tt> display produced by the <tt>ntpq</tt> program.</p>
-
<table width="50%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td><div align="center">Leap</div></td>
-<td><div align="center">Source</div></td>
-<td><div align="center">Count</div></td>
-<td><div align="center">Code</div></td>
-</tr>
-
+ <tr>
+ <td><div align="center">Leap</div></td>
+ <td><div align="center">Source</div></td>
+ <td><div align="center">Count</div></td>
+ <td><div align="center">Code</div></td>
+ </tr>
</table>
-
<p>The Leap Field displays the system leap indicator bits coded as follows:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>0</tt></td>
-<td><tt>leap_none</tt></td>
-<td>normal synchronized state</td>
-</tr>
-
-<tr>
-<td><tt>1</tt></td>
-<td><tt>leap_add_sec</tt></td>
-<td>insert second after 23:59:59 of the current day</td>
-</tr>
-
-<tr>
-<td><tt>2</tt></td>
-<td><tt>leap_del_sec</tt></td>
-<td>delete second 23:59:59 of the current day</td>
-</tr>
-
-<tr>
-<td><tt>3</tt></td>
-<td><tt>leap_alarm</tt></td>
-<td>never synchronized</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>0</tt></td>
+ <td><tt>leap_none</tt></td>
+ <td>normal synchronized state</td>
+ </tr>
+ <tr>
+ <td><tt>1</tt></td>
+ <td><tt>leap_add_sec</tt></td>
+ <td>insert second after 23:59:59 of the current day</td>
+ </tr>
+ <tr>
+ <td><tt>2</tt></td>
+ <td><tt>leap_del_sec</tt></td>
+ <td>delete second 23:59:59 of the current day</td>
+ </tr>
+ <tr>
+ <td><tt>3</tt></td>
+ <td><tt>leap_alarm</tt></td>
+ <td>never synchronized</td>
+ </tr>
</table>
-
<p>The Source Field displays the current synchronization source coded as follows:.</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>0</tt></td>
-<td><tt>sync_unspec</tt></td>
-<td>not yet synchronized</td>
-</tr>
-
-<tr>
-<td><tt>1</tt></td>
-<td><tt>sync_pps</tt></td>
-<td>pulse-per-second signal (Cs, Ru, GPS, etc.)</td>
-</tr>
-
-<tr>
-<td><tt>2</tt></td>
-<td><tt>sync_lf_radio</tt></td>
-<td>VLF/LF radio (WWVB, DCF77, etc.)</td>
-</tr>
-
-<tr>
-<td><tt>3</tt></td>
-<td><tt>sync_hf_radio</tt></td>
-<td>MF/HF radio (WWV, etc.)</td>
-</tr>
-
-<tr>
-<td><tt>4</tt></td>
-<td><tt>sync_uhf_radio</tt></td>
-<td>VHF/UHF radio/satellite (GPS, Galileo, etc.)</td>
-</tr>
-
-<tr>
-<td><tt>5</tt></td>
-<td><tt>sync_local</tt></td>
-<td>local timecode (IRIG, LOCAL driver, etc.)</td>
-</tr>
-
-<tr>
-<td><tt>6</tt></td>
-<td><tt>sync_ntp</tt></td>
-<td>NTP</td>
-</tr>
-
-<tr>
-<td><tt>7</tt></td>
-<td><tt>sync_other</tt></td>
-<td>other (IEEE 1588, openntp, crony, etc.)</td>
-</tr>
-
-<tr>
-<td><tt>8</tt></td>
-<td><tt>sync_wristwatch</tt></td>
-<td>eyeball and wristwatch</td>
-</tr>
-
-<tr>
-<td><tt>9</tt></td>
-<td><tt>sync_telephone</tt></td>
-<td>telephone modem (ACTS, PTB, etc.)</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>0</tt></td>
+ <td><tt>sync_unspec</tt></td>
+ <td>not yet synchronized</td>
+ </tr>
+ <tr>
+ <td><tt>1</tt></td>
+ <td><tt>sync_pps</tt></td>
+ <td>pulse-per-second signal (Cs, Ru, GPS, etc.)</td>
+ </tr>
+ <tr>
+ <td><tt>2</tt></td>
+ <td><tt>sync_lf_radio</tt></td>
+ <td>VLF/LF radio (WWVB, DCF77, etc.)</td>
+ </tr>
+ <tr>
+ <td><tt>3</tt></td>
+ <td><tt>sync_hf_radio</tt></td>
+ <td>MF/HF radio (WWV, etc.)</td>
+ </tr>
+ <tr>
+ <td><tt>4</tt></td>
+ <td><tt>sync_uhf_radio</tt></td>
+ <td>VHF/UHF radio/satellite (GPS, Galileo, etc.)</td>
+ </tr>
+ <tr>
+ <td><tt>5</tt></td>
+ <td><tt>sync_local</tt></td>
+ <td>local timecode (IRIG, LOCAL driver, etc.)</td>
+ </tr>
+ <tr>
+ <td><tt>6</tt></td>
+ <td><tt>sync_ntp</tt></td>
+ <td>NTP</td>
+ </tr>
+ <tr>
+ <td><tt>7</tt></td>
+ <td><tt>sync_other</tt></td>
+ <td>other (IEEE 1588, openntp, crony, etc.)</td>
+ </tr>
+ <tr>
+ <td><tt>8</tt></td>
+ <td><tt>sync_wristwatch</tt></td>
+ <td>eyeball and wristwatch</td>
+ </tr>
+ <tr>
+ <td><tt>9</tt></td>
+ <td><tt>sync_telephone</tt></td>
+ <td>telephone modem (ACTS, PTB, etc.)</td>
+ </tr>
</table>
-
<p>The Count Field displays the number of events since the last time the code changed. Upon reaching 15, subsequent events with the same code are ignored.</p>
-
<p>The Event Field displays the most recent event message coded as follows:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>00</tt></td>
-<td><tt>unspecified</tt></td>
-<td>unspecified</td>
-</tr>
-
-<tr>
-<td><tt>01</tt></td>
-<td><tt>freq_not_set</tt></td>
-<td>frequency file not available</td>
-</tr>
-
-<tr>
-<td><tt>02</tt></td>
-<td><tt>freq_set</tt></td>
-<td>frequency set from frequency file</td>
-</tr>
-
-<tr>
-<td><tt>03</tt></td>
-<td><tt>spike_detect</tt></td>
-<td>spike detected</td>
-</tr>
-
-<tr>
-<td><tt>04</tt></td>
-<td><tt>freq_mode</tt></td>
-<td>initial frequency training mode</td>
-</tr>
-
-<tr>
-<td><tt>05</tt></td>
-<td><tt>clock_sync</tt></td>
-<td>clock synchronized</td>
-</tr>
-
-<tr>
-<td><tt>06</tt></td>
-<td><tt>restart</tt></td>
-<td>program restart</td>
-</tr>
-
-<tr>
-<td><tt>07</tt></td>
-<td><tt>panic_stop</tt></td>
-<td>clock error more than 600 s</td>
-</tr>
-
-<tr>
-<td><tt>08</tt></td>
-<td><tt>no_system_peer</tt></td>
-<td>no system peer</td>
-</tr>
-
-<tr>
-<td><tt>09</tt></td>
-<td><tt>leap_armed</tt></td>
-<td>leap second armed from file or Autokey</td>
-</tr>
-
-<tr>
-<td><tt>0a</tt></td>
-<td><tt>leap_disarmed</tt></td>
-<td>leap second disarmed</td>
-</tr>
-
-<tr>
-<td><tt>0b</tt></td>
-<td><tt>leap_event</tt></td>
-<td>leap event</td>
-</tr>
-
-<tr>
-<td><tt>0c</tt></td>
-<td><tt>clock_step</tt></td>
-<td>clock stepped</td>
-</tr>
-
-<tr>
-<td><tt>0d</tt></td>
-<td><tt>kern</tt></td>
-<td>kernel information message</td>
-</tr>
-
-<tr>
-<td><tt>0e</tt></td>
-<td><tt>TAI...</tt></td>
-<td>leapsecond values update from file</td>
-</tr>
-
-<tr>
-<td><tt>0f</tt></td>
-<td><tt>stale leapsecond values</tt></td>
-<td>new NIST leapseconds file needed</td>
-</tr>
-<tr>
-<td><tt>10</tt></td>
-<td><tt>clockhop</tt></td>
-<td>spurious clock hop suppressed</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>00</tt></td>
+ <td><tt>unspecified</tt></td>
+ <td>unspecified</td>
+ </tr>
+ <tr>
+ <td><tt>01</tt></td>
+ <td><tt>freq_not_set</tt></td>
+ <td>frequency file not available</td>
+ </tr>
+ <tr>
+ <td><tt>02</tt></td>
+ <td><tt>freq_set</tt></td>
+ <td>frequency set from frequency file</td>
+ </tr>
+ <tr>
+ <td><tt>03</tt></td>
+ <td><tt>spike_detect</tt></td>
+ <td>spike detected</td>
+ </tr>
+ <tr>
+ <td><tt>04</tt></td>
+ <td><tt>freq_mode</tt></td>
+ <td>initial frequency training mode</td>
+ </tr>
+ <tr>
+ <td><tt>05</tt></td>
+ <td><tt>clock_sync</tt></td>
+ <td>clock synchronized</td>
+ </tr>
+ <tr>
+ <td><tt>06</tt></td>
+ <td><tt>restart</tt></td>
+ <td>program restart</td>
+ </tr>
+ <tr>
+ <td><tt>07</tt></td>
+ <td><tt>panic_stop</tt></td>
+ <td>clock error more than 600 s</td>
+ </tr>
+ <tr>
+ <td><tt>08</tt></td>
+ <td><tt>no_system_peer</tt></td>
+ <td>no system peer</td>
+ </tr>
+ <tr>
+ <td><tt>09</tt></td>
+ <td><tt>leap_armed</tt></td>
+ <td>leap second armed from file or Autokey</td>
+ </tr>
+ <tr>
+ <td><tt>0a</tt></td>
+ <td><tt>leap_disarmed</tt></td>
+ <td>leap second disarmed</td>
+ </tr>
+ <tr>
+ <td><tt>0b</tt></td>
+ <td><tt>leap_event</tt></td>
+ <td>leap event</td>
+ </tr>
+ <tr>
+ <td><tt>0c</tt></td>
+ <td><tt>clock_step</tt></td>
+ <td>clock stepped</td>
+ </tr>
+ <tr>
+ <td><tt>0d</tt></td>
+ <td><tt>kern</tt></td>
+ <td>kernel information message</td>
+ </tr>
+ <tr>
+ <td><tt>0e</tt></td>
+ <td><tt>TAI...</tt></td>
+ <td>leapsecond values update from file</td>
+ </tr>
+ <tr>
+ <td><tt>0f</tt></td>
+ <td><tt>stale leapsecond values</tt></td>
+ <td>new NIST leapseconds file needed</td>
+ </tr>
+ <tr>
+ <td><tt>10</tt></td>
+ <td><tt>clockhop</tt></td>
+ <td>spurious clock hop suppressed</td>
+ </tr>
</table>
-
<h4 id="peer">Peer Status Word</h4>
-
<p>The peer status word consists of four fields: Status (0-4), Select (5-7), Count (8-11) and Code (12-15). It is reported in the first line of the <tt>rv <i>associd</i></tt> display produced by the <tt>ntpq</tt> program.</p>
-
<table width="50%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td><div align="center">Status</div></td>
-<td><div align="center">Select</div></td>
-<td><div align="center">Count</div></td>
-<td><div align="center">Code</div></td>
-</tr>
-
+ <tr>
+ <td><div align="center">Status</div></td>
+ <td><div align="center">Select</div></td>
+ <td><div align="center">Count</div></td>
+ <td><div align="center">Code</div></td>
+ </tr>
</table>
-
<p>The Status Field displays the peer status code bits in hexadecimal; each bit is an independent flag. (Note this field is 5 bits wide, and combines with the the 3-bit-wide Select Field to create the first full byte of the peer status word.) The meaning of each bit in the Status Field is listed in the following table:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>08</tt></td>
-<td><tt>bcst</tt></td>
-<td>broadcast association</td>
-</tr>
-
-<tr>
-<td><tt>10</tt></td>
-<td><tt>reach</tt></td>
-<td>host reachable</td>
-</tr>
-
-<tr>
-<td><tt>20</tt></td>
-<td><tt>authenb</tt></td>
-<td>authentication enabled</td>
-</tr>
-
-<tr>
-<td><tt>40</tt></td>
-<td><tt>auth</tt></td>
-<td>authentication ok</td>
-</tr>
-
-<tr>
-<td><tt>80</tt></td>
-<td><tt>config</tt></td>
-<td>persistent association</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>08</tt></td>
+ <td><tt>bcst</tt></td>
+ <td>broadcast association</td>
+ </tr>
+ <tr>
+ <td><tt>10</tt></td>
+ <td><tt>reach</tt></td>
+ <td>host reachable</td>
+ </tr>
+ <tr>
+ <td><tt>20</tt></td>
+ <td><tt>authenb</tt></td>
+ <td>authentication enabled</td>
+ </tr>
+ <tr>
+ <td><tt>40</tt></td>
+ <td><tt>auth</tt></td>
+ <td>authentication ok</td>
+ </tr>
+ <tr>
+ <td><tt>80</tt></td>
+ <td><tt>config</tt></td>
+ <td>persistent association</td>
+ </tr>
</table>
-
<p>The Select Field displays the current selection status. (The T Field in the following table gives the corresponding tally codes used in the <tt>ntpq peers</tt> display.) The values are coded as follows:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>T</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>0</tt></td>
-<td><tt>sel_reject</tt></td>
-<td> </td>
-<td>discarded as not valid (TEST10-TEST13)</td>
-</tr>
-
-<tr>
-<td><tt>1</tt></td>
-<td><tt>sel_falsetick</tt></td>
-<td><tt>x</tt></td>
-<td>discarded by intersection algorithm</td>
-</tr>
-
-<tr>
-<td><tt>2</tt></td>
-<td><tt>sel_excess</tt></td>
-<td><tt>.</tt></td>
-<td>discarded by table overflow (not used)</td>
-</tr>
-
-<tr>
-<td><tt>3</tt></td>
-<td><tt>sel_outlyer</tt></td>
-<td><tt>-</tt></td>
-<td>discarded by the cluster algorithm</td>
-</tr>
-
-<tr>
-<td><tt>4</tt></td>
-<td><tt>sel_candidate</tt></td>
-<td><tt>+</tt></td>
-<td>included by the combine algorithm</td>
-</tr>
-
-<tr>
-<td><tt>5</tt></td>
-<td><tt>sel_backup</tt></td>
-<td><tt>#</tt></td>
-<td>backup (more than <tt>tos maxclock</tt> sources)</td>
-</tr>
-
-<tr>
-<td><tt>6</tt></td>
-<td><tt>sel_sys.peer</tt></td>
-<td><tt>*</tt></td>
-<td>system peer</td>
-</tr>
-
-<tr>
-<td><tt>7</tt></td>
-<td><tt>sel_pps.peer</tt></td>
-<td><tt>o</tt></td>
-<td>PPS peer (when the prefer peer is valid)</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>T</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>0</tt></td>
+ <td><tt>sel_reject</tt></td>
+ <td> </td>
+ <td>discarded as not valid (TEST10-TEST13)</td>
+ </tr>
+ <tr>
+ <td><tt>1</tt></td>
+ <td><tt>sel_falsetick</tt></td>
+ <td><tt>x</tt></td>
+ <td>discarded by intersection algorithm</td>
+ </tr>
+ <tr>
+ <td><tt>2</tt></td>
+ <td><tt>sel_excess</tt></td>
+ <td><tt>.</tt></td>
+ <td>discarded by table overflow (not used)</td>
+ </tr>
+ <tr>
+ <td><tt>3</tt></td>
+ <td><tt>sel_outlyer</tt></td>
+ <td><tt>-</tt></td>
+ <td>discarded by the cluster algorithm</td>
+ </tr>
+ <tr>
+ <td><tt>4</tt></td>
+ <td><tt>sel_candidate</tt></td>
+ <td><tt>+</tt></td>
+ <td>included by the combine algorithm</td>
+ </tr>
+ <tr>
+ <td><tt>5</tt></td>
+ <td><tt>sel_backup</tt></td>
+ <td><tt>#</tt></td>
+ <td>backup (more than <tt>tos maxclock</tt> sources)</td>
+ </tr>
+ <tr>
+ <td><tt>6</tt></td>
+ <td><tt>sel_sys.peer</tt></td>
+ <td><tt>*</tt></td>
+ <td>system peer</td>
+ </tr>
+ <tr>
+ <td><tt>7</tt></td>
+ <td><tt>sel_pps.peer</tt></td>
+ <td><tt>o</tt></td>
+ <td>PPS peer (when the prefer peer is valid)</td>
+ </tr>
</table>
-
<p>The Count Field displays the number of events since the last time the code changed. Upon reaching 15, subsequent events with the same code are ignored. </p>
-
<p>The Event Field displays the most recent event message coded as follows:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>01</tt></td>
-<td><tt>mobilize</tt></td>
-<td>association mobilized</td>
-</tr>
-
-<tr>
-<td><tt>02</tt></td>
-<td><tt>demobilize</tt></td>
-<td>association demobilized</td>
-</tr>
-
-<tr>
-<td><tt>03</tt></td>
-<td><tt>unreachable</tt></td>
-<td>server unreachable</td>
-</tr>
-
-<tr>
-<td><tt>04</tt></td>
-<td><tt>reachable</tt></td>
-<td>server reachable</td>
-</tr>
-
-<tr>
-<td><tt>05</tt></td>
-<td><tt>restart</tt></td>
-<td>association restart</td>
-</tr>
-
-<tr>
-<td><tt>06</tt></td>
-<td><tt>no_reply</tt></td>
-<td>no server found (<tt>ntpdate</tt> mode)</td>
-</tr>
-
-<tr>
-<td><tt>07</tt></td>
-<td><tt>rate_exceeded</tt></td>
-<td>rate exceeded (kiss code <tt>RATE</tt>)</td>
-</tr>
-
-<tr>
-<td><tt>08</tt></td>
-<td><tt>access_denied</tt></td>
-<td>access denied (kiss code <tt>DENY</tt>)</td>
-</tr>
-
-<tr>
-<td><tt>09</tt></td>
-<td><tt>leap_armed</tt></td>
-<td>leap armed from server LI code</td>
-</tr>
-
-<tr>
-<td><tt>0a</tt></td>
-<td><tt>sys_peer</tt></td>
-<td>become system peer</td>
-</tr>
-
-<tr>
-<td><tt>0b</tt></td>
-<td><tt>clock_event</tt></td>
-<td>see clock status word</td>
-</tr>
-
-<tr>
-<td><tt>0c</tt></td>
-<td><tt>bad_auth</tt></td>
-<td>authentication failure</td>
-</tr>
-
-<tr>
-<td><tt>0d</tt></td>
-<td><tt>popcorn</tt></td>
-<td>popcorn spike suppressor</td>
-</tr>
-
-<tr>
-<td><tt>0e</tt></td>
-<td><tt>interleave_mode</tt></td>
-<td>entering interleave mode</td>
-</tr>
-
-<tr>
-<td><tt>0f</tt></td>
-<td><tt>interleave_error</tt></td>
-<td>interleave error (recovered)</td>
-</tr>
-
-<tr>
-<td><tt>10</tt></td>
-<td><tt>TAI...</tt></td>
-<td>leapsecond values update from server</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>01</tt></td>
+ <td><tt>mobilize</tt></td>
+ <td>association mobilized</td>
+ </tr>
+ <tr>
+ <td><tt>02</tt></td>
+ <td><tt>demobilize</tt></td>
+ <td>association demobilized</td>
+ </tr>
+ <tr>
+ <td><tt>03</tt></td>
+ <td><tt>unreachable</tt></td>
+ <td>server unreachable</td>
+ </tr>
+ <tr>
+ <td><tt>04</tt></td>
+ <td><tt>reachable</tt></td>
+ <td>server reachable</td>
+ </tr>
+ <tr>
+ <td><tt>05</tt></td>
+ <td><tt>restart</tt></td>
+ <td>association restart</td>
+ </tr>
+ <tr>
+ <td><tt>06</tt></td>
+ <td><tt>no_reply</tt></td>
+ <td>no server found (<tt>ntpdate</tt> mode)</td>
+ </tr>
+ <tr>
+ <td><tt>07</tt></td>
+ <td><tt>rate_exceeded</tt></td>
+ <td>rate exceeded (kiss code <tt>RATE</tt>)</td>
+ </tr>
+ <tr>
+ <td><tt>08</tt></td>
+ <td><tt>access_denied</tt></td>
+ <td>access denied (kiss code <tt>DENY</tt>)</td>
+ </tr>
+ <tr>
+ <td><tt>09</tt></td>
+ <td><tt>leap_armed</tt></td>
+ <td>leap armed from server LI code</td>
+ </tr>
+ <tr>
+ <td><tt>0a</tt></td>
+ <td><tt>sys_peer</tt></td>
+ <td>become system peer</td>
+ </tr>
+ <tr>
+ <td><tt>0b</tt></td>
+ <td><tt>clock_event</tt></td>
+ <td>see clock status word</td>
+ </tr>
+ <tr>
+ <td><tt>0c</tt></td>
+ <td><tt>bad_auth</tt></td>
+ <td>authentication failure</td>
+ </tr>
+ <tr>
+ <td><tt>0d</tt></td>
+ <td><tt>popcorn</tt></td>
+ <td>popcorn spike suppressor</td>
+ </tr>
+ <tr>
+ <td><tt>0e</tt></td>
+ <td><tt>interleave_mode</tt></td>
+ <td>entering interleave mode</td>
+ </tr>
+ <tr>
+ <td><tt>0f</tt></td>
+ <td><tt>interleave_error</tt></td>
+ <td>interleave error (recovered)</td>
+ </tr>
+ <tr>
+ <td><tt>10</tt></td>
+ <td><tt>TAI...</tt></td>
+ <td>leapsecond values update from server</td>
+ </tr>
</table>
-
<h4 id="clock">Clock Status Word</h4>
-
<p>The clock status word consists of four fields: Unused (0-7), Count (8-11) and Code (12-15). It is reported in the first line of the <tt>clockvar <i>associd</i></tt> display produced by the <tt>ntpq</tt> program.</p>
<table width="50%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td><div align="center">Unused</div></td>
-<td><div align="center">Count</div></td>
-<td><div align="center">Code</div></td>
-</tr>
-
+ <tr>
+ <td><div align="center">Unused</div></td>
+ <td><div align="center">Count</div></td>
+ <td><div align="center">Code</div></td>
+ </tr>
</table>
-
<p>The Count Field displays the number of events since the last <tt>lockvar</tt> command, while the Event Field displays the most recent event message coded as follows:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>00</tt></td>
-<td><tt>clk_unspe</tt></td>
-<td>nominal</td>
-</tr>
-
-<tr>
-<td><tt>01</tt></td>
-<td><tt>clk_noreply</tt></td>
-<td>no reply to poll</td>
-</tr>
-
-<tr>
-<td><tt>02</tt></td>
-<td><tt>clk_badformat</tt></td>
-<td>bad timecode format</td>
-</tr>
-
-<tr>
-<td><tt>03</tt></td>
-<td><tt>clk_fault</tt></td>
-<td>hardware or software fault</td>
-</tr>
-
-<tr>
-<td><tt>04</tt></td>
-<td><tt>clk_bad_signal</tt></td>
-<td>signal loss</td>
-</tr>
-
-<tr>
-<td><tt>05</tt></td>
-<td><tt>clk_bad_date</tt></td>
-<td>bad date format</td>
-</tr>
-
-<tr>
-<td><tt>06</tt></td>
-<td><tt>clk_bad_time</tt></td>
-<td>bad time format</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>00</tt></td>
+ <td><tt>clk_unspe</tt></td>
+ <td>nominal</td>
+ </tr>
+ <tr>
+ <td><tt>01</tt></td>
+ <td><tt>clk_noreply</tt></td>
+ <td>no reply to poll</td>
+ </tr>
+ <tr>
+ <td><tt>02</tt></td>
+ <td><tt>clk_badformat</tt></td>
+ <td>bad timecode format</td>
+ </tr>
+ <tr>
+ <td><tt>03</tt></td>
+ <td><tt>clk_fault</tt></td>
+ <td>hardware or software fault</td>
+ </tr>
+ <tr>
+ <td><tt>04</tt></td>
+ <td><tt>clk_bad_signal</tt></td>
+ <td>signal loss</td>
+ </tr>
+ <tr>
+ <td><tt>05</tt></td>
+ <td><tt>clk_bad_date</tt></td>
+ <td>bad date format</td>
+ </tr>
+ <tr>
+ <td><tt>06</tt></td>
+ <td><tt>clk_bad_time</tt></td>
+ <td>bad time format</td>
+ </tr>
</table>
-
<p>When the clock driver sets the code to a new value, a <tt>clock_alarm</tt> (11) peer event is reported.</p>
-
<h4 id="flash">Flash Status Word</h4>
-
<p>The flash status word is displayed by the <tt>ntpq</tt> program <tt>rv</tt> command. It consists of a number of bits coded in hexadecimal as follows:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Tag</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>0001</tt></td>
-<td>TEST1</td>
-<td><tt>pkt_dup</tt></td>
-<td>duplicate packet</td>
-</tr>
-
-<tr>
-<td><tt>0002</tt></td>
-<td>TEST2</td>
-<td><tt>pkt_bogus</tt></td>
-<td>bogus packet</td>
-</tr>
-
-<tr>
-<td><tt>0004</tt></td>
-<td>TEST3</td>
-<td><tt>pkt_unsync</tt></td>
-<td>protocol unsynchronized</td>
-</tr>
-
-<tr>
-<td><tt>0008</tt></td>
-<td>TEST4</td>
-<td><tt>pkt_denied</tt></td>
-<td>access denied</td>
-</tr>
-
-<tr>
-<td><tt>0010</tt></td>
-<td>TEST5</td>
-<td><tt>pkt_auth</tt></td>
-<td>bad authentication</td>
-</tr>
-
-<tr>
-<td><tt>0020</tt></td>
-<td>TEST6</td>
-<td><tt>pkt_stratum</tt></td>
-<td>bad synch or stratum</td>
-</tr>
-
-<tr>
-<td><tt>0040</tt></td>
-<td>TEST7</td>
-<td><tt>pkt_header</tt></td>
-<td>bad header</td>
-</tr>
-
-<tr>
-<td><tt>0080</tt></td>
-<td>TEST8</td>
-<td><tt>pkt_autokey</tt></td>
-<td>bad autokey</td>
-</tr>
-
-<tr>
-<td><tt>0100</tt></td>
-<td>TEST9</td>
-<td><tt>pkt_crypto</tt></td>
-<td>bad crypto</td>
-</tr>
-
-<tr>
-<td><tt>0200</tt></td>
-<td>TEST10</td>
-<td><tt>peer_stratum</tt></td>
-<td>peer bad synch or stratum</td>
-</tr>
-
-<tr>
-<td><tt>0400</tt></td>
-<td>TEST11</td>
-<td><tt>peer_dist</tt></td>
-<td>peer distance exceeded</td>
-</tr>
-
-<tr>
-<td><tt>0800</tt></td>
-<td>TEST12</td>
-<td><tt>peer_loop</tt></td>
-<td>peer synchronization loop</td>
-</tr>
-
-<tr>
-<td><tt>1000</tt></td>
-<td>TEST13</td>
-<td><tt>peer_unreach</tt></td>
-<td>peer unreachable</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Tag</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>0001</tt></td>
+ <td>TEST1</td>
+ <td><tt>pkt_dup</tt></td>
+ <td>duplicate packet</td>
+ </tr>
+ <tr>
+ <td><tt>0002</tt></td>
+ <td>TEST2</td>
+ <td><tt>pkt_bogus</tt></td>
+ <td>bogus packet</td>
+ </tr>
+ <tr>
+ <td><tt>0004</tt></td>
+ <td>TEST3</td>
+ <td><tt>pkt_unsync</tt></td>
+ <td>protocol unsynchronized</td>
+ </tr>
+ <tr>
+ <td><tt>0008</tt></td>
+ <td>TEST4</td>
+ <td><tt>pkt_denied</tt></td>
+ <td>access denied</td>
+ </tr>
+ <tr>
+ <td><tt>0010</tt></td>
+ <td>TEST5</td>
+ <td><tt>pkt_auth</tt></td>
+ <td>bad authentication</td>
+ </tr>
+ <tr>
+ <td><tt>0020</tt></td>
+ <td>TEST6</td>
+ <td><tt>pkt_stratum</tt></td>
+ <td>bad synch or stratum</td>
+ </tr>
+ <tr>
+ <td><tt>0040</tt></td>
+ <td>TEST7</td>
+ <td><tt>pkt_header</tt></td>
+ <td>bad header</td>
+ </tr>
+ <tr>
+ <td><tt>0080</tt></td>
+ <td>TEST8</td>
+ <td><tt>pkt_autokey</tt></td>
+ <td>bad autokey</td>
+ </tr>
+ <tr>
+ <td><tt>0100</tt></td>
+ <td>TEST9</td>
+ <td><tt>pkt_crypto</tt></td>
+ <td>bad crypto</td>
+ </tr>
+ <tr>
+ <td><tt>0200</tt></td>
+ <td>TEST10</td>
+ <td><tt>peer_stratum</tt></td>
+ <td>peer bad synch or stratum</td>
+ </tr>
+ <tr>
+ <td><tt>0400</tt></td>
+ <td>TEST11</td>
+ <td><tt>peer_dist</tt></td>
+ <td>peer distance exceeded</td>
+ </tr>
+ <tr>
+ <td><tt>0800</tt></td>
+ <td>TEST12</td>
+ <td><tt>peer_loop</tt></td>
+ <td>peer synchronization loop</td>
+ </tr>
+ <tr>
+ <td><tt>1000</tt></td>
+ <td>TEST13</td>
+ <td><tt>peer_unreach</tt></td>
+ <td>peer unreachable</td>
+ </tr>
</table>
-
<h4 id="kiss">Kiss Codes</h4>
-
<p>Kiss codes are used in kiss-o'-death (koD) packets, billboard displays and log messages. They consist of a string of four zero-padded ASCII charactes. In practice they are informal and tend to change with time and implementation. Some of these codes can appear in the reference identifier field in <tt>ntpq</tt> billboards. Following is the current list:</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>ACST</tt></td>
-<td>manycast server</td>
-</tr>
-
-<tr>
-<td><tt>AUTH</tt></td>
-<td>authentication error</td>
-</tr>
-
-<tr>
-<td><tt>AUTO</tt></td>
-<td>Autokey sequence error</td>
-</tr>
-
-<tr>
-<td><tt>BCST</tt></td>
-<td>broadcast server</td>
-</tr>
-
-<tr>
-<td><tt>CRYPT</tt></td>
-<td>Autokey protocol error</td>
-</tr>
-
-<tr>
-<td><tt>DENY</tt></td>
-<td>access denied by server</td>
-</tr>
-
-<tr>
-<td><tt>INIT</tt></td>
-<td>association initialized</td>
-</tr>
-
-<tr>
-<td><tt>MCST</tt></td>
-<td>multicast server</td>
-</tr>
-
-<tr>
-<td><tt>RATE</tt></td>
-<td>rate exceeded</td>
-</tr>
-
-<tr>
-<td><tt>TIME</tt></td>
-<td>association timeout</td>
-</tr>
-
-<tr>
-<td><tt>STEP</tt></td>
-<td>step time change</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>ACST</tt></td>
+ <td>manycast server</td>
+ </tr>
+ <tr>
+ <td><tt>AUTH</tt></td>
+ <td>authentication error</td>
+ </tr>
+ <tr>
+ <td><tt>AUTO</tt></td>
+ <td>Autokey sequence error</td>
+ </tr>
+ <tr>
+ <td><tt>BCST</tt></td>
+ <td>broadcast server</td>
+ </tr>
+ <tr>
+ <td><tt>CRYPT</tt></td>
+ <td>Autokey protocol error</td>
+ </tr>
+ <tr>
+ <td><tt>DENY</tt></td>
+ <td>access denied by server</td>
+ </tr>
+ <tr>
+ <td><tt>INIT</tt></td>
+ <td>association initialized</td>
+ </tr>
+ <tr>
+ <td><tt>MCST</tt></td>
+ <td>multicast server</td>
+ </tr>
+ <tr>
+ <td><tt>RATE</tt></td>
+ <td>rate exceeded</td>
+ </tr>
+ <tr>
+ <td><tt>TIME</tt></td>
+ <td>association timeout</td>
+ </tr>
+ <tr>
+ <td><tt>STEP</tt></td>
+ <td>step time change</td>
+ </tr>
</table>
-
<h4 id="crypto">Crypto Messages</h4>
-
<p>These messages are sent to the <tt>cryptostats</tt> file when an error is detected in the Autokey protocol.</p>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
-
-<tr>
-<td>Code</td>
-<td>Message</td>
-<td>Description</td>
-</tr>
-
-<tr>
-<td><tt>01</tt></td>
-<td><tt>bad_format</tt></td>
-<td>bad extension field format or length</td>
-</tr>
-
-<tr>
-<td><tt>02</tt></td>
-<td><tt>bad_timestamp</tt></td>
-<td>bad timestamp</td>
-</tr>
-
-<tr>
-<td><tt>03</tt></td>
-<td><tt>bad_filestamp</tt></td>
-<td>bad filestamp</td>
-</tr>
-
-<tr>
-<td><tt>04</tt></td>
-<td><tt>bad_public_key</tt></td>
-<td>bad or missing public key</td>
-</tr>
-
-<tr>
-<td><tt>05</tt></td>
-<td><tt>bad_digest</tt></td>
-<td>unsupported digest type</td>
-</tr>
-
-<tr>
-<td><tt>06</tt></td>
-<td><tt>bad_identity</tt></td>
-<td>unsupported identity type</td>
-</tr>
-
-<tr>
-<td><tt>07</tt></td>
-<td><tt>bad_siglength</tt></td>
-<td>bad signature length</td>
-</tr>
-
-<tr>
-<td><tt>08</tt></td>
-<td><tt>bad signature</tt></td>
-<td>extension field signature not verified</td>
-</tr>
-
-<tr>
-<td><tt>09</tt></td>
-<td><tt>cert_not_verified</tt></td>
-<td>certificate signature not verified</td>
-</tr>
-
-<tr>
-<td><tt>0a</tt></td>
-<td><tt>cert_expired</tt></td>
-<td>host certificate expired</td>
-</tr>
-
-<tr>
-<td><tt>0b</tt></td>
-<td><tt>bad_cookie</tt></td>
-<td>bad or missing cookie</td>
-</tr>
-
-<tr>
-<td><tt>0c</tt></td>
-<td><tt>bad_leapseconds</tt></td>
-<td>bad or missing leapseconds values</td>
-</tr>
-
-<tr>
-<td><tt>0d</tt></td>
-<td><tt>cert_missing</tt></td>
-<td>bad or missing certificate</td>
-</tr>
-
-<tr>
-<td><tt>0e</tt></td>
-<td><tt>bad_group_key</tt></td>
-<td>bad or missing group key</td>
-</tr>
-
-<tr>
-<td><tt>0f</tt></td>
-<td><tt>proto_error</tt></td>
-<td>protocol error</td>
-</tr>
-
+ <tr>
+ <td>Code</td>
+ <td>Message</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>01</tt></td>
+ <td><tt>bad_format</tt></td>
+ <td>bad extension field format or length</td>
+ </tr>
+ <tr>
+ <td><tt>02</tt></td>
+ <td><tt>bad_timestamp</tt></td>
+ <td>bad timestamp</td>
+ </tr>
+ <tr>
+ <td><tt>03</tt></td>
+ <td><tt>bad_filestamp</tt></td>
+ <td>bad filestamp</td>
+ </tr>
+ <tr>
+ <td><tt>04</tt></td>
+ <td><tt>bad_public_key</tt></td>
+ <td>bad or missing public key</td>
+ </tr>
+ <tr>
+ <td><tt>05</tt></td>
+ <td><tt>bad_digest</tt></td>
+ <td>unsupported digest type</td>
+ </tr>
+ <tr>
+ <td><tt>06</tt></td>
+ <td><tt>bad_identity</tt></td>
+ <td>unsupported identity type</td>
+ </tr>
+ <tr>
+ <td><tt>07</tt></td>
+ <td><tt>bad_siglength</tt></td>
+ <td>bad signature length</td>
+ </tr>
+ <tr>
+ <td><tt>08</tt></td>
+ <td><tt>bad signature</tt></td>
+ <td>extension field signature not verified</td>
+ </tr>
+ <tr>
+ <td><tt>09</tt></td>
+ <td><tt>cert_not_verified</tt></td>
+ <td>certificate signature not verified</td>
+ </tr>
+ <tr>
+ <td><tt>0a</tt></td>
+ <td><tt>cert_expired</tt></td>
+ <td>host certificate expired</td>
+ </tr>
+ <tr>
+ <td><tt>0b</tt></td>
+ <td><tt>bad_cookie</tt></td>
+ <td>bad or missing cookie</td>
+ </tr>
+ <tr>
+ <td><tt>0c</tt></td>
+ <td><tt>bad_leapseconds</tt></td>
+ <td>bad or missing leapseconds values</td>
+ </tr>
+ <tr>
+ <td><tt>0d</tt></td>
+ <td><tt>cert_missing</tt></td>
+ <td>bad or missing certificate</td>
+ </tr>
+ <tr>
+ <td><tt>0e</tt></td>
+ <td><tt>bad_group_key</tt></td>
+ <td>bad or missing group key</td>
+ </tr>
+ <tr>
+ <td><tt>0f</tt></td>
+ <td><tt>proto_error</tt></td>
+ <td>protocol error</td>
+ </tr>
</table>
-
<hr>
-
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
-
</body>
-</html>
\ No newline at end of file
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Automatic Server Discoveryschemes</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Automatic Server Discovery Schemes</h3>
+<img src="pic/alice51.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>Make sure who your friends are.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2 -->09-Sep-2010<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#assoc">Association Management</a></li>
+ <li class="inline"><a href="#bcst">Broadcast/Multicast Scheme</a></li>
+ <li class="inline"><a href="#mcst">Manycast Scheme</a></li>
+ <li class="inline"><a href="#pool">Server Pool Scheme</a></li>
+</ul>
+<hr>
+<h4 id="modes">Introduction</h4>
+<p>This page describes the automatic server discovery schemes provided in NTPv4. There are three automatic server discovery schemes: broadcast/multicast, manycast and server pool described on this page. The broadcast/multicast and manycast schemes utilize the ubiquitous broadcast or one-to-many paradigm native to IPv4 and IPv6. The server pool scheme uses DNS to resolve addresses of multiple volunteer servers scattered throughout the world. All three schemes work in much the same way and might be described as <i>grab-n'-prune</i>. Through one means or another they grab a number of associations either directly or indirectly from the configuration file, order them from best to worst according to a defined metric, then cast off the associations with the lowest metric until no more than the number specified by the <tt>maxclock</tt> option of the <tt>tos</tt>command remain.</p>
+<h4 id="assoc">Association Management</h4>
+<p>All schemes use a stratum filter to select just those servers with stratum considered useful. This can avoid large numbers of clients ganging up on a small number of low-stratum servers and avoid servers below or above specified stratum levels. By default, servers of all strata are acceptable; however, the <tt>tos</tt> command can be used to restrict the acceptable range from the <tt>floor</tt> option, inclusive, to the <tt>ceiling</tt> option, exclusive. Potential servers operating at the same stratum as the client will be avoided, unless the <tt>cohort</tt> option is present.</p>
+<p>The pruning process is handled using a set of counters, one for each preemptible association. Once each poll interval the counter is increased by one. If the association survives the selection and clustering algorithms; that is, it is a candidate for synchronization, the counter is reset to zero. If not and the counter reaches a defined threshold and the number of assocations is greater than <tt>maxclock</tt>, the association becomes a candidate for pruning. The pruning algorithm assigns to each association a metric ranging from the lowest, corresponding to no possibility of synchronization, to the highest, corresponding to a very likely possibility of synchronization. Upon reaching the threshold, an association is demobilized if it has the lowest metric of all associations. Operation continues in this way until the number of remaining associations is not greater than <tt>maxclock</tt>.</p>
+<p>Following is a summary of each scheme. Note that reference to option applies to the commands described on the <a href="confopt.html">Configuration Options</a> page. See that page for applicability and defaults.</p>
+<h4 id="bcst">Broadcast/Multicast Scheme</h4>
+<p>A broadcast server generates messages continuously at intervals by default 64 s and time-to-live by default 127. These defaults can be overriden by the <tt>minpoll</tt> and <tt>ttl</tt> options, respectively. Not all kernels support the <tt>ttl</tt> option. A broadcast client responds to the first message received by waiting a randomized interval to avoid implosion at the server. It then polls the server in client/server mode using the <tt>iburst</tt> option in order to quickly authenticate the server, calibrate the propagation delay and set the host clock. This normally results in a volley of six client/server exchanges at 2-s intervals during which both the synchronization and cryptographic protocols run concurrently.</p>
+<p>Following the volley, the server continues in listen-only mode and sends no further messages. If for some reason the broadcast server does not respond to these messages, the client will cease transmission and continue in listen-only mode with a default propagation delay. The volley can be avoided by using the <tt>authdelay</tt> command with nonzero argument.</p>
+<p>A server is configured in broadcast mode using the <tt>broadcast</tt> command and specifying the broadcast address of a local interface. If two or more local interfaces are installed with different broadcast addresses, a <tt>broadcast</tt> command is needed for each address. This provides a way to limit exposure in a firewall, for example. A broadcast client is configured using the <tt>broadcastclient</tt> command. </p>
+<p>NTP multicast mode can be used to extend the scope using IPv4 multicast or IPv6 broadcast with defined span. The IANA has assigned IPv4 multicast address 224.0.1.1 and IPv6 address FF05::101 (site local) to NTP, but these addresses should be used only where the multicast span can be reliably constrained to protect neighbor networks. In general, administratively scoped IPv4 group addresses should be used, as described in RFC-2365, or GLOP group addresses, as described in RFC-2770.</p>
+<p>A multicast server is configured using the <tt>broadcast</tt> command, but specifying a multicast address instead of a broadcast address. A multicast client is configured using the <tt>multicastclient</tt> command specifying a list of one or more multicast addresses. Note that there is a subtle distinction between the IPv4 and IPv6 address families. The IPv4 broadcast or mulitcast mode is determined by the IPv4 class. For IPv6 the same distinction can be made using the link-local prefix FF02 for each interface and site-local prefix FF05 for all interfaces.</p>
+<p>It is possible and frequently useful to configure a host as both broadcast client and broadcast server. A number of hosts configured this way and sharing a common broadcast address will automatically organize themselves in an optimum configuration based on stratum and synchronization distance.</p>
+<p>Since an intruder can impersonate a broadcast server and inject false time values, broadcast mode should always be cryptographically authenticated. By default, a broadcast association will not be mobilized unless cryptographically authenticated. If necessary, the <tt>auth</tt> option of the <tt>disable</tt> command will disable this feature. The feature can be selectively enabled using the <tt>notrust</tt> option of the <tt>restrict</tt> command.</p>
+<p>With symmetric key cryptography each broadcast server can use the same or different keys. In one scenario on a broadcast LAN, a set of broadcast clients and servers share the same key along with another set that share a different key. Only the clients with matching key will respond to a server broadcast. Further information is on the <a href="authentic.html">Authentication Support</a> page.</p>
+<p>Public key cryptography can be used with some restrictions. If multiple servers belonging to different secure groups share the same broadcast LAN, the clients on that LAN must have the client keys for all of them. This scenario is illustrated in the example on the <a href="autokey.html">Autokey Public Key Authentication</a> page.</p>
+<h4 id="mcst">Manycast Scheme</h4>
+<p>Manycast is a automatic server discovery and configuration paradigm new to NTPv4. It is intended as a means for a client to troll the nearby network neighborhood to find cooperating servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. It uses the grab-n'-drop paradigm with the additional feature that active means are used to grab additional servers should the number of survivors fall below the <tt>minclock</tt> option of the <tt>tos</tt> command.</p>
+<p>The manycast paradigm is not the anycast paradigm described in RFC-1546, which is designed to find a single server from a clique of servers providing the same service. The manycast paradigm is designed to find a plurality of redundant servers satisfying defined optimality criteria.</p>
+<p>A manycast clients is configured using the <tt>manycastclient</tt> configuration command, which is similar to the <tt>server</tt> configuration command. It sends ordinary client mode messages, but with a broadcast address rather than a unicast address and sends only if less than <tt>minclock</tt> associations remain and then only at the minimum feasible rate and minimum feasible time-to-live (TTL) hops. The polling strategy is designed to reduce as much as possible the volume of broadcast messages and the effects of implosion due to near-simultaneous arrival of manycast server messages. There can be as many manycast client associations as different addresses, each one serving as a template for future unicast client/server associations.</p>
+<p>A manycast server is configured using the <tt>manycastserver</tt> command, which listens on the specified broadcast address for manycast client messages. If a manycast server is in scope of the current TTL and is itself synchronized to a valid source and operating at a stratum level equal to or lower than the manycast client, it replies with an ordinary unicast server message.</p>
+<p>The manycast client receiving this message mobilizes a preemptable client association according to the matching manycast client template, but only if cryptographically authenticated and the server stratum is less than or equal to the client stratum. </p>
+<p>It is possible and frequently useful to configure a host as both manycast client and manycast server. A number of hosts configured this way and sharing a common multicast group address will automatically organize themselves in an optimum configuration based on stratum and synchronization distance.</p>
+<p>The use of cryptograpic authentication is always a good idea in any server discovery scheme. Both symmetric key and public key cryptography can be used in the same scenarios as described above for the broadast/multicast scheme.</p>
+<h4 id="pool">Server Pool Scheme</h4>
+<p>The idea of targeting servers on a random basis to distribute and balance the load is not a new one; however, the NTP pool scheme puts this on steroids. At present, several thousand operators around the globe have volunteered their servers for public access. In general, NTP is a lightweight service and servers used for other purposes don't mind an additional small load. The trick is to randomize over the population and minimize the load on any one server while retaining the advantages of multiple servers using the NTP mitigation algorithms.</p>
+<p>To support this service custom DNS software used for pool.ntp.org and its subdomains
+ returns a random selection of participating servers in response to a DNS query.
+ The client receiving this list mobilizes some or all of them, similar to the
+ manycast discovery scheme, and casts off the excess. Unlike <tt>manycastclient</tt>,
+ cryptographic authentication is not required. The pool scheme solicits a single
+ server at a time, compared to <tt>manycastclient</tt> which solicits all servers
+ within a multicast TTL range simultaneously. Otherwise, the pool server discovery
+ scheme operates as manycast does.</p>
+<p>The pool scheme is configured using one or more <tt>pool</tt> commands with DNS names
+ indicating the pool from which to draw. The <tt>pool</tt> command can be used more
+ than once; duplicate servers are detected and discarded. In principle, it is
+ possible to use a configuration file containing a single line <tt>pool
+ pool.ntp.org</tt>. The <a href="http://www.pool.ntp.org/en/use.html">NTP Pool
+ Project</a> offers instructions on using the pool with the <tt>server</tt> command, which is suboptimal but works with older versions of <tt>ntpd</tt> predating the <tt>pool</tt> command. With recent ntpd, consider replacing the
+ multiple <tt>server</tt> commands in their example with a single <tt>pool</tt> command.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Undisciplined Local Clock</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Undisciplined Local Clock</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.1.<i>u</i><br>
- Reference ID: <tt>LCL</tt><br>
- Driver ID: <tt>LOCAL</tt></p>
- <h4>Description</h4>
- <p>Not: This driver is not recommended for new installations. A much more flexible replacement is available in the form of orphan mode described on the <a href="../assoc.html">Association Management page</a>.</p>
- <p>This driver is intended for use in an isolated network where no external source of synchronization such as a radio clock or modem is available. It allows a designated time server to act as a primary server to provide synchronization to other clients on the network. Pick a machine that has a good clock oscillator (Digital machines are good, Sun machines are not) and configure it with this driver. Set the clock using the best means available, like eyeball-and-wristwatch. Then, point all the other machines at this one or use broadcast mode to distribute time.</p>
- <p>Another application for this driver is if a particular server clock is to be used as the clock of last resort when all other normal synchronization sources have gone away. This is especially useful if that server has an ovenized oscillator. For this you would usually, but not necessarily, configure this driver at a stratum greater than any other likely sources of time, such as the default 5 for this driver, to prevent this driver taking over when legitimate sources elsewher in the network are available. To further protect the Internet infrastructure from accidental or malicious exposure to this driver, the driver is desabled if another source is available and operating.</p>
- <h4>Monitor Data</h4>
- <p>No <tt>filegen clockstats</tt> monitor data are produced by this driver.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Specifies the frequency offset calibration factor, in parts per million, with default 0.0.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 3.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>LCL</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Not used by this driver.
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Undisciplined Local Clock</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Undisciplined Local Clock</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:07<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.1.<i>u</i><br>
+ Reference ID: <tt>LCL</tt><br>
+ Driver ID: <tt>LOCAL</tt></p>
+<h4>Description</h4>
+<p>Not: This driver is not recommended for new installations. A much more flexible replacement is available in the form of orphan mode described on the <a href="../assoc.html">Association Management page</a>.</p>
+<p>This driver is intended for use in an isolated network where no external source of synchronization such as a radio clock or modem is available. It allows a designated time server to act as a primary server to provide synchronization to other clients on the network. Pick a machine that has a good clock oscillator (Digital machines are good, Sun machines are not) and configure it with this driver. Set the clock using the best means available, like eyeball-and-wristwatch. Then, point all the other machines at this one or use broadcast mode to distribute time.</p>
+<p>Another application for this driver is if a particular server clock is to be used as the clock of last resort when all other normal synchronization sources have gone away. This is especially useful if that server has an ovenized oscillator. For this you would usually, but not necessarily, configure this driver at a stratum greater than any other likely sources of time, such as the default 5 for this driver, to prevent this driver taking over when legitimate sources elsewher in the network are available. To further protect the Internet infrastructure from accidental or malicious exposure to this driver, the driver is desabled if another source is available and operating.</p>
+<h4>Monitor Data</h4>
+<p>No <tt>filegen clockstats</tt> monitor data are produced by this driver.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Specifies the frequency offset calibration factor, in parts per million, with default 0.0.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 3.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>LCL</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a></p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
- <title>Austron 2200A/2201A GPS Receivers</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Austron 2200A/2201A GPS Receivers</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.10.<i>u</i><br>
- Reference ID: <tt>GPS</tt><br>
- Driver ID: <tt>GPS_AS2201</tt><br>
- Serial Port: <tt>/dev/gps<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
- Features: <tt>tty_clk</tt></p>
- <h4>Description</h4>
- <p>This driver supports the Austron 2200A/2201A GPS/LORAN Synchronized Clock and Timing Receiver connected via a serial port. It supports several special features of the clock, including the Input Buffer Module, Output Buffer Module, IRIG-B Interface Module and LORAN Assist Module. It requires the RS232 Buffered Serial Interface module for communication with the driver.</p>
- <p>For use with a single computer, the receiver can be connected directly to the receiver. For use with multiple computers, one of them is connected directly to the receiver and generates the polling messages. The other computers just listen to the receiver output directly or through a buffer amplifier. For computers that just listen, <tt>fudge flag2</tt> must be set and the <tt>ppsclock </tt>streams module configured on each of them.</p>
- <p>This receiver is capable of a comprehensive and large volume of statistics and operational data. The specific data collection commands and attributes are embedded in the driver source code; however, the collection process can be enabled or disabled using the flag4 flag. If set, collection is enabled; if not, which is the default, it is disabled. A comprehensive suite of data reduction and summary scripts is in the ./scripts/stats directory</p>
- of the ntp3 distribution.
- <h4>Monitor Data</h4>
- <p>When enabled by the <tt>flag4</tt> fudge flag, every received timecode is written as-is to the <tt>clockstats</tt> file.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>GPS</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Set for computers that listen-only.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Enable verbose <tt>clockstats</tt> recording if set.
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
+<title>Austron 2200A/2201A GPS Receivers</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Austron 2200A/2201A GPS Receivers</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:17<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.10.<i>u</i><br>
+ Reference ID: <tt>GPS</tt><br>
+ Driver ID: <tt>GPS_AS2201</tt><br>
+ Serial Port: <tt>/dev/gps<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
+ Features: <tt>tty_clk</tt></p>
+<h4>Description</h4>
+<p>This driver supports the Austron 2200A/2201A GPS/LORAN Synchronized Clock and Timing Receiver connected via a serial port. It supports several special features of the clock, including the Input Buffer Module, Output Buffer Module, IRIG-B Interface Module and LORAN Assist Module. It requires the RS232 Buffered Serial Interface module for communication with the driver.</p>
+<p>For use with a single computer, the receiver can be connected directly to the receiver. For use with multiple computers, one of them is connected directly to the receiver and generates the polling messages. The other computers just listen to the receiver output directly or through a buffer amplifier. For computers that just listen, <tt>fudge flag2</tt> must be set and the <tt>ppsclock </tt>streams module configured on each of them.</p>
+<p>This receiver is capable of a comprehensive and large volume of statistics and operational data. The specific data collection commands and attributes are embedded in the driver source code; however, the collection process can be enabled or disabled using the flag4 flag. If set, collection is enabled; if not, which is the default, it is disabled. A comprehensive suite of data reduction and summary scripts is in the ./scripts/stats directory</p>
+of the ntp3 distribution.
+<h4>Monitor Data</h4>
+<p>When enabled by the <tt>flag4</tt> fudge flag, every received timecode is written as-is to the <tt>clockstats</tt> file.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>GPS</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Set for computers that listen-only.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Enable verbose <tt>clockstats</tt> recording if set.</dd>
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a></p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
- <title>Arbiter 1088A/B GPS Receiver</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Arbiter 1088A/B GPS Receiver</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.11.<i>u</i><br>
- Reference ID: <tt>GPS</tt><br>
- Driver ID: <tt>GPS_ARBITER</tt><br>
- Serial Port: <tt>/dev/gps<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
- Features: <tt>tty_clk</tt></p>
- <h4>Description</h4>
- <p>This driver supports the Arbiter 1088A/B Satellite Controlled Clock. The claimed accuracy of this clock is 100 ns relative to the PPS output when receiving four or more satellites.</p>
- <p>The receiver should be configured before starting the NTP daemon, in order to establish reliable position and operating conditions. It does not initiate surveying or hold mode. For use with NTP, the daylight savings time feature should be disables (<tt>D0</tt> command) and the broadcast mode set to operate in UTC (<tt>BU</tt> command).</p>
- <p>The timecode format supported by this driver is selected by the poll sequence <tt>B5</tt>, which initiates a line in the following format to be repeated once per second until turned off by the <tt>B0</tt> command.</p>
- <p>Format <tt>B5</tt> (24 ASCII printing characters):</p>
- <pre><cr><lf>i yy ddd hh:mm:ss.000bbb
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
+<title>Arbiter 1088A/B GPS Receiver</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Arbiter 1088A/B GPS Receiver</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 17:49<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.11.<i>u</i><br>
+ Reference ID: <tt>GPS</tt><br>
+ Driver ID: <tt>GPS_ARBITER</tt><br>
+ Serial Port: <tt>/dev/gps<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
+ Features: <tt>tty_clk</tt></p>
+<h4>Description</h4>
+<p>This driver supports the Arbiter 1088A/B Satellite Controlled Clock. The claimed accuracy of this clock is 100 ns relative to the PPS output when receiving four or more satellites.</p>
+<p>The receiver should be configured before starting the NTP daemon, in order to establish reliable position and operating conditions. It does not initiate surveying or hold mode. For use with NTP, the daylight savings time feature should be disables (<tt>D0</tt> command) and the broadcast mode set to operate in UTC (<tt>BU</tt> command).</p>
+<p>The timecode format supported by this driver is selected by the poll sequence <tt>B5</tt>, which initiates a line in the following format to be repeated once per second until turned off by the <tt>B0</tt> command.</p>
+<p>Format <tt>B5</tt> (24 ASCII printing characters):</p>
+<pre><cr><lf>i yy ddd hh:mm:ss.000bbb
on-time = <cr>
i = synchronization flag (' ' = locked, '?' = unlocked)
hh:mm:ss = hours, minutes, seconds
.000 = fraction of second (not used)
bbb = tailing spaces for fill</pre>
-
<p>The alarm condition is indicated by a '?' at i, which indicates the receiver is not synchronized. In normal operation, a line consisting of the timecode followed by the time quality character (TQ) followed by the receiver status string (SR) is written to the clockstats file.</p>
-
<p>The time quality character is encoded in IEEE P1344 standard:</p>
-
<p>Format <tt>TQ</tt> (IEEE P1344 estimated worst-case time quality)</p>
-
<pre>0 clock locked, maximum accuracy
+<p>The alarm condition is indicated by a '?' at i, which indicates the receiver is not synchronized. In normal operation, a line consisting of the timecode followed by the time quality character (TQ) followed by the receiver status string (SR) is written to the clockstats file.</p>
+<p>The time quality character is encoded in IEEE P1344 standard:</p>
+<p>Format <tt>TQ</tt> (IEEE P1344 estimated worst-case time quality)</p>
+<pre>0 clock locked, maximum accuracy
F clock failure, time not reliable
4 clock unlocked, accuracy < 1 us
5 clock unlocked, accuracy < 10 us
9 clock unlocked, accuracy < 100 ms
A clock unlocked, accuracy < 1 s
B clock unlocked, accuracy < 10 s</pre>
-
<p>The status string is encoded as follows:</p>
-
<p>Format <tt>SR</tt> (25 ASCII printing characters)</p>
-
<pre>V=vv S=ss T=t P=pdop E=ee
+<p>The status string is encoded as follows:</p>
+<p>Format <tt>SR</tt> (25 ASCII printing characters)</p>
+<pre>V=vv S=ss T=t P=pdop E=ee
vv = satellites visible
ss = relative signal strength
t = satellites tracked
pdop = position dilution of precision (meters)
ee = hardware errors</pre>
- <p>A three-stage median filter is used to reduce jitter and provide a dispersion measure. The driver makes no attempt to correct for the intrinsic jitter of the radio itself.</p>
- <h4>Monitor Data</h4>
- <p>When enabled by the <tt>flag4</tt> fudge flag, an additional line containing the latitude, longitude, elevation and optional deviation data is written to the <tt>clockstats</tt> file. The deviation data operates with an external pulse-per-second (PPS) input, such as a cesium oscillator or another radio clock. The PPS input should be connected to the B event channel and the radio initialized for deviation data on that channel. The deviation data consists of the mean offset and standard deviation of the external PPS signal relative the GPS signal, both in microseconds over the last 16 seconds.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>GPS</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Enable verbose <tt>clockstats</tt> recording if set.
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<p>A three-stage median filter is used to reduce jitter and provide a dispersion measure. The driver makes no attempt to correct for the intrinsic jitter of the radio itself.</p>
+<h4>Monitor Data</h4>
+<p>When enabled by the <tt>flag4</tt> fudge flag, an additional line containing the latitude, longitude, elevation and optional deviation data is written to the <tt>clockstats</tt> file. The deviation data operates with an external pulse-per-second (PPS) input, such as a cesium oscillator or another radio clock. The PPS input should be connected to the B event channel and the radio initialized for deviation data on that channel. The deviation data consists of the mean offset and standard deviation of the external PPS signal relative the GPS signal, both in microseconds over the last 16 seconds.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>GPS</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Enable verbose <tt>clockstats</tt> recording if set.</dd>
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a></p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
- <title>KSI/Odetics TPRO/S IRIG Interface</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>KSI/Odetics TPRO/S IRIG Interface</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.12.<i>u</i><br>
- Reference ID: <tt>IRIG</tt><br>
- Driver ID: <tt>IRIG_TPRO</tt><br>
- TPRO Device: <tt>/dev/tpro<i>u</i></tt><br>
- Requires: KSI/Odetics device driver, <tt>/usr/include/sys/tpro.h</tt> header file</p>
- <h4>Description</h4>
- <p>This driver supports the KSI/Odetics TPRO and TPRO-SAT IRIG-B Decoder, which is a module connected directly to the SBus of a Sun workstation. The module works with the IRIG-B signal generated by several radio clocks, including those made by Arbiter, Austron, Odetics, Spectracom and TrueTime, among others, although it is generally an add- on option. In the case of the TPRO-SAT, the module is an integral part of a GPS receiver, which serves as the primary timing source.</p>
- <p>Using the TPRO interface as a NTP reference clock provides precision time only to ntpd and its clients. With suitable kernel modifications, it is possible to use the TPRO as the CPU system clock, avoiding errors introduced by the CPU clock oscillator wander. See the <a href="../kern.html">A Kernel Model for Precision Timekeeping </a>page for further details.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>IRIG</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Not used by this driver.
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
+<title>KSI/Odetics TPRO/S IRIG Interface</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>KSI/Odetics TPRO/S IRIG Interface</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:44<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.12.<i>u</i><br>
+ Reference ID: <tt>IRIG</tt><br>
+ Driver ID: <tt>IRIG_TPRO</tt><br>
+ TPRO Device: <tt>/dev/tpro<i>u</i></tt><br>
+ Requires: KSI/Odetics device driver, <tt>/usr/include/sys/tpro.h</tt> header file</p>
+<h4>Description</h4>
+<p>This driver supports the KSI/Odetics TPRO and TPRO-SAT IRIG-B Decoder, which is a module connected directly to the SBus of a Sun workstation. The module works with the IRIG-B signal generated by several radio clocks, including those made by Arbiter, Austron, Odetics, Spectracom and TrueTime, among others, although it is generally an add- on option. In the case of the TPRO-SAT, the module is an integral part of a GPS receiver, which serves as the primary timing source.</p>
+<p>Using the TPRO interface as a NTP reference clock provides precision time only to ntpd and its clients. With suitable kernel modifications, it is possible to use the TPRO as the CPU system clock, avoiding errors introduced by the CPU clock oscillator wander. See the <a href="../kern.html">A Kernel Model for Precision Timekeeping </a>page for further details.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>IRIG</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a></p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
- <title>NIST/USNO/PTB Modem Time Services</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>NIST/USNO/PTB Modem Time Services</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.18.<i>u</i><br>
- Reference ID: <tt>NIST | USNO | PTB | WWVB</tt><br>
- Driver ID: <tt>ACTS_MODEM</tt><br>
- Serial Port: <tt>/dev/acts<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
- Features: <tt>tty_clk</tt><br>
- Requires: <tt>/usr/include/sys/termios.h</tt> header file with modem control and a dial-out (cua) device.</p>
- <h4>Description</h4>
- <p>This driver supports the US (NIST and USNO) and European (PTB (Germany), NPL (UK), etc.) modem time services, as well as Spectracom GPS and WWVB receivers connected via a modem. The driver periodically dials a number from a telephone list, receives the timecode data and calculates the local clock correction. It is designed primarily for backup when neither a radio clock nor connectivity to Internet time servers are available. It can also be configured to operate full period.</p>
- <p>For best results the indicated time must be corrected for the modem and telephone circuit propagation delays, which can reach 200 ms or more. For the NIST service, corrections are determined automatically by measuring the roundtrip delay of echoed characters. With this service the absolute accuracy is typically a millisecond or two. Corrections for the other services must be determined by other means. With these services variations from call to call and between messages during a call are typically a few milliseconds, occasionally higher.</p>
- <p>This driver requires a 9600-bps modem with a Hayes-compatible command set and control over the modem data terminal ready (DTR) control line. The actual line speed ranges from 1200 bps with USNO to 14,400 bps with NIST. The modem setup string is hard-coded in the driver and may require changes for nonstandard modems or special circumstances.</p>
- <p>There are three modes of operation selected by the <tt>mode</tt> keyword in the <tt>server</tt> configuration command. In manual mode (2) the calling program is initiated by setting fudge <tt>flag1</tt>. This can be done manually using <tt>ntpdc</tt>, or by a cron job. In auto mode (0) <tt>flag1</tt> is set at each poll event. In backup mode (1) <tt>flag1</tt> is set at each poll event, but only if no other synchronization sources are available.</p>
- <p>When <tt>flag1</tt> is set, the calling program dials the first number in the list specified by the <tt>phone</tt> command. If the call fails for any reason, the program dials the second number and so on. The phone number is specified by the Hayes ATDT prefix followed by the number itself, including the prefix and long-distance digits and delay code, if necessary. The <tt>flag1</tt> is reset and the calling program terminated if (a) valid clock update has been determined, (b) no more numbers remain in the list, (c) a device fault or timeout occurs or (d) fudge <tt>flag1</tt> is reset manually using <tt>ntpdc</tt>.</p>
- <p>The driver automatically recognizes the message format of each modem time service. It selects the parsing algorithm depending on the message length. There is some hazard should the message be corrupted. However, the data format is checked carefully and only if all checks succeed is the message accepted. Corrupted lines are discarded without complaint. Once the service is known, the reference identifier for the driver is set to NIST, USNO, PTB or WWVB as appropriate.</p>
- <p>Ordinarily, the serial port is connected to a modem; however, if fudge <tt>flag3</tt> is set, it can be connected directly to a Spectracom WWV or GPS radio for testing or calibration. The Spectracom radio can be connected via a modem if the radio is connfigured to send time codes continuoulsly at 1-s intervals. In principle, fudge <tt>flag2</tt> enables port locking, allowing the modem to be shared when not in use by this driver. At least on Solaris with the current NTP I/O routines, this results in lots of ugly error messages.</p>
- <p>The <tt>minpoll</tt> and <tt>maxpoll</tt> keywords of the server configuration command can be used to limit the intervals between calls. The recommended settings are 12 (1.1 hours) for <tt>minpoll</tt> and 17 (36 hours) for <tt>maxpoll</tt>. Ordinarily, the poll interval will start at <tt>minpoll</tt> and ramp up to <tt>maxpoll</tt> in a day or two.</p>
- <h4>US Phone Numbers and Formats</h4>
- <p>Note: Phone numbers include the entire Hayes modem command, including the <tt>ATDT</tt> and other control codes as may be necessary. For most cases only the <tt>ATDT</tt> may be necessary.</p>
- <p><a href="http://www.boulder.nist.gov/timefreq">National Institute of Science and Technology (NIST)</a></p>
- <p>Phone: (303) 494-4774 (Boulder, CO); (808) 335-4721 (Hawaii)</p>
- <p><a href="http://www.boulder.nist.gov/timefreq/service/acts.htm">Data Format</a></p>
- <p><tt>National Institute of Standards and Technology<br>
- Telephone Time Service, Generator 3B<br>
- Enter question mark "?" for HELP<br>
- MJD YR MO DA H M S ST S UT1 msADV <OTM><br>
- 47999 90-04-18 21:39:15 50 0 +.1 045.0 UTC(NIST) *<br>
- 47999 90-04-18 21:39:16 50 0 +.1 045.0 UTC(NIST) #<br>
- ...</tt></p>
- <p><tt>MJD</tt>, <tt>YR</tt>, <tt>ST</tt>, <tt>UT1</tt> and <tt>UTC(NIST)</tt> are not used by this driver. The <tt><OTM></tt> on-time character "<tt>*</tt>" changes to "<tt>#</tt>" when the delay correction is valid.</p>
- <p><a href="http://tycho.usno.navy.mil">US Naval Observatory (USNO)</a></p>
- <p>Phone: (202) 762-1594 (Washington, DC); (719) 567-6742 (Boulder, CO)</p>
- <p><a href="http://tycho.usno.navy.mil/modem_time.html">Data Format</a> (two lines, repeating at one-second intervals)</p>
- <p><tt>jjjjj nnn hhmmss UTC</tt></p>
- <p>* on-time character for previous timecode message<br>
- jjjjj modified Julian day number (not used)<br>
- nnn day of year<br>
- hhmmss second of day</p>
- <p><a href="tf582_4.html">European Phone Numbers and Formats</a></p>
- <p><a href="http://www.spectracomcorp.com">Spectracom GPS and WWVB Receivers</a></p>
- <p>If a modem is connected to a Spectracom receiver, this driver will call it and retrieve the time in one of two formats, 0 and 2. Ordinarily, the receiver requires a <tt>T</tt> in order to return the timecode. As this driver does not send data via the modem, it must either be configured in continuous mode or be polled by another local driver.</p>
- <h4>Monitor Data</h4>
- <p>The received timecode is written as-is to the <tt>clockstats</tt> file along with the Hayes connection and hangup commands and result codes.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Set by the driver to (one of) <tt>NIST</tt>, <tt>USNO</tt>, <tt>PTB</tt> or <tt>WWVB</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Initiate a call if 1. Automatically reset by program.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Enables port locking if 1, disables if 0 (default).
- <dt><tt>flag3 0 | 1</tt>
- <dd>Enables direct connection if 1, or modem if 0 (default). If set, the driver will send a single character 'T' at every poll event.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Not used by this driver.
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a> </p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
+<title>NIST/USNO/PTB Modem Time Services</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>NIST/USNO/PTB Modem Time Services</h3>
+<p>Autjhor: David L. Mills (mills@udel.edu)<br>
+ Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 17:59<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.18.<i>u</i><br>
+ Reference ID: <tt>NIST | USNO | PTB | WWVB</tt><br>
+ Driver ID: <tt>ACTS_MODEM</tt><br>
+ Serial Port: <tt>/dev/acts<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
+ Features: <tt>tty_clk</tt><br>
+ Requires: <tt>/usr/include/sys/termios.h</tt> header file with modem control and a dial-out (cua) device.</p>
+<h4>Description</h4>
+<p>This driver supports the US (NIST and USNO) and European (PTB (Germany), NPL (UK), etc.) modem time services, as well as Spectracom GPS and WWVB receivers connected via a modem. The driver periodically dials a number from a telephone list, receives the timecode data and calculates the local clock correction. It is designed primarily for backup when neither a radio clock nor connectivity to Internet time servers are available. It can also be configured to operate full period.</p>
+<p>For best results the indicated time must be corrected for the modem and telephone circuit propagation delays, which can reach 200 ms or more. For the NIST service, corrections are determined automatically by measuring the roundtrip delay of echoed characters. With this service the absolute accuracy is typically a millisecond or two. Corrections for the other services must be determined by other means. With these services variations from call to call and between messages during a call are typically a few milliseconds, occasionally higher.</p>
+<p>This driver requires a 9600-bps modem with a Hayes-compatible command set and control over the modem data terminal ready (DTR) control line. The actual line speed ranges from 1200 bps with USNO to 14,400 bps with NIST. The modem setup string is hard-coded in the driver and may require changes for nonstandard modems or special circumstances.</p>
+<p>There are three modes of operation selected by the <tt>mode</tt> keyword in the <tt>server</tt> configuration command. In manual mode (2) the calling program is initiated by setting fudge <tt>flag1</tt>. This can be done manually using <tt>ntpdc</tt>, or by a cron job. In auto mode (0) <tt>flag1</tt> is set at each poll event. In backup mode (1) <tt>flag1</tt> is set at each poll event, but only if no other synchronization sources are available.</p>
+<p>When <tt>flag1</tt> is set, the calling program dials the first number in the list specified by the <tt>phone</tt> command. If the call fails for any reason, the program dials the second number and so on. The phone number is specified by the Hayes ATDT prefix followed by the number itself, including the prefix and long-distance digits and delay code, if necessary. The <tt>flag1</tt> is reset and the calling program terminated if (a) valid clock update has been determined, (b) no more numbers remain in the list, (c) a device fault or timeout occurs or (d) fudge <tt>flag1</tt> is reset manually using <tt>ntpdc</tt>.</p>
+<p>The driver automatically recognizes the message format of each modem time service. It selects the parsing algorithm depending on the message length. There is some hazard should the message be corrupted. However, the data format is checked carefully and only if all checks succeed is the message accepted. Corrupted lines are discarded without complaint. Once the service is known, the reference identifier for the driver is set to NIST, USNO, PTB or WWVB as appropriate.</p>
+<p>Ordinarily, the serial port is connected to a modem; however, if fudge <tt>flag3</tt> is set, it can be connected directly to a Spectracom WWV or GPS radio for testing or calibration. The Spectracom radio can be connected via a modem if the radio is connfigured to send time codes continuoulsly at 1-s intervals. In principle, fudge <tt>flag2</tt> enables port locking, allowing the modem to be shared when not in use by this driver. At least on Solaris with the current NTP I/O routines, this results in lots of ugly error messages.</p>
+<p>The <tt>minpoll</tt> and <tt>maxpoll</tt> keywords of the server configuration command can be used to limit the intervals between calls. The recommended settings are 12 (1.1 hours) for <tt>minpoll</tt> and 17 (36 hours) for <tt>maxpoll</tt>. Ordinarily, the poll interval will start at <tt>minpoll</tt> and ramp up to <tt>maxpoll</tt> in a day or two.</p>
+<h4>US Phone Numbers and Formats</h4>
+<p>Note: Phone numbers include the entire Hayes modem command, including the <tt>ATDT</tt> and other control codes as may be necessary. For most cases only the <tt>ATDT</tt> may be necessary.</p>
+<p><a href="http://www.boulder.nist.gov/timefreq">National Institute of Science and Technology (NIST)</a></p>
+<p>Phone: (303) 494-4774 (Boulder, CO); (808) 335-4721 (Hawaii)</p>
+<p><a href="http://www.boulder.nist.gov/timefreq/service/acts.htm">Data Format</a></p>
+<p><tt>National Institute of Standards and Technology<br>
+ Telephone Time Service, Generator 3B<br>
+ Enter question mark "?" for HELP<br>
+ MJD YR MO DA H M S ST S UT1 msADV <OTM><br>
+ 47999 90-04-18 21:39:15 50 0 +.1 045.0 UTC(NIST) *<br>
+ 47999 90-04-18 21:39:16 50 0 +.1 045.0 UTC(NIST) #<br>
+ ...</tt></p>
+<p><tt>MJD</tt>, <tt>YR</tt>, <tt>ST</tt>, <tt>UT1</tt> and <tt>UTC(NIST)</tt> are not used by this driver. The <tt><OTM></tt> on-time character "<tt>*</tt>" changes to "<tt>#</tt>" when the delay correction is valid.</p>
+<p><a href="http://tycho.usno.navy.mil">US Naval Observatory (USNO)</a></p>
+<p>Phone: (202) 762-1594 (Washington, DC); (719) 567-6742 (Boulder, CO)</p>
+<p><a href="http://tycho.usno.navy.mil/modem_time.html">Data Format</a> (two lines, repeating at one-second intervals)</p>
+<p><tt>jjjjj nnn hhmmss UTC</tt></p>
+<p>* on-time character for previous timecode message<br>
+ jjjjj modified Julian day number (not used)<br>
+ nnn day of year<br>
+ hhmmss second of day</p>
+<p><a href="tf582_4.html">European Phone Numbers and Formats</a></p>
+<p><a href="http://www.spectracomcorp.com">Spectracom GPS and WWVB Receivers</a></p>
+<p>If a modem is connected to a Spectracom receiver, this driver will call it and retrieve the time in one of two formats, 0 and 2. Ordinarily, the receiver requires a <tt>T</tt> in order to return the timecode. As this driver does not send data via the modem, it must either be configured in continuous mode or be polled by another local driver.</p>
+<h4>Monitor Data</h4>
+<p>The received timecode is written as-is to the <tt>clockstats</tt> file along with the Hayes connection and hangup commands and result codes.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Set by the driver to (one of) <tt>NIST</tt>, <tt>USNO</tt>, <tt>PTB</tt> or <tt>WWVB</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Initiate a call if 1. Automatically reset by program.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Enables port locking if 1, disables if 0 (default).</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Enables direct connection if 1, or modem if 0 (default). If set, the driver will send a single character 'T' at every poll event.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a> </p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
- <title>Heath WWV/WWVH Receiver</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Heath WWV/WWVH Receiver</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.19.<i>u</i><br>
- Reference ID: <tt>WWV</tt><br>
- Driver ID: <tt>WWV_HEATH</tt><br>
- Serial Port: <tt>/dev/heath<i>u</i></tt>; 1200 baud, 8-bits, no parity<br>
- Features: <tt>tty_clk</tt><br>
- Requires: <tt>/usr/include/sys/termios.h</tt> header file with modem control</p>
- <h4>Description</h4>
- <p>This driver supports the Heath GC-1000 Most Accurate Clock, with RS232C Output Accessory. This is a WWV/WWVH receiver somewhat less robust than other supported receivers. It's claimed accuracy is 100 ms when actually synchronized to the broadcast signal, but this doesn't happen even most of the time, due to propagation conditions, ambient noise sources, etc. When not synchronized, the accuracy is at the whim of the internal clock oscillator, which can wander into the sunset without warning. Since the indicated precision is 100 ms, expect a host synchronized only to this thing to wander to and fro, occasionally being rudely stepped when the offset exceeds the default CLOCK_MAX of 128 ms.</p>
- <p>The internal DIPswitches should be set to operate at 1200 baud in MANUAL mode and the current year. The external DIPswitches should be set to GMT and 24-hour format. It is very important that the year be set correctly in the DIPswitches; otherwise, the day of year will be incorrect after 28 April of a normal or leap year.</p>
- <p>In MANUAL mode the clock responds to a rising edge of the request to send (RTS) modem control line by sending the timecode. Therefore, it is necessary that the operating system implement the <tt>TIOCMBIC</tt> and <tt>TIOCMBIS</tt> ioctl system calls and <tt>TIOCM_RTS</tt> control bit. Present restrictions require the use of a POSIX-compatible programming interface, although other interfaces may work as well.</p>
- <p>The clock message consists of 23 ASCII printing characters in the following format:</p>
- <pre>hh:mm:ss.f dd/mm/yr<cr>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
+<title>Heath WWV/WWVH Receiver</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Heath WWV/WWVH Receiver</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:38<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.19.<i>u</i><br>
+ Reference ID: <tt>WWV</tt><br>
+ Driver ID: <tt>WWV_HEATH</tt><br>
+ Serial Port: <tt>/dev/heath<i>u</i></tt>; 1200 baud, 8-bits, no parity<br>
+ Features: <tt>tty_clk</tt><br>
+ Requires: <tt>/usr/include/sys/termios.h</tt> header file with modem control</p>
+<h4>Description</h4>
+<p>This driver supports the Heath GC-1000 Most Accurate Clock, with RS232C Output Accessory. This is a WWV/WWVH receiver somewhat less robust than other supported receivers. It's claimed accuracy is 100 ms when actually synchronized to the broadcast signal, but this doesn't happen even most of the time, due to propagation conditions, ambient noise sources, etc. When not synchronized, the accuracy is at the whim of the internal clock oscillator, which can wander into the sunset without warning. Since the indicated precision is 100 ms, expect a host synchronized only to this thing to wander to and fro, occasionally being rudely stepped when the offset exceeds the default CLOCK_MAX of 128 ms.</p>
+<p>The internal DIPswitches should be set to operate at 1200 baud in MANUAL mode and the current year. The external DIPswitches should be set to GMT and 24-hour format. It is very important that the year be set correctly in the DIPswitches; otherwise, the day of year will be incorrect after 28 April of a normal or leap year.</p>
+<p>In MANUAL mode the clock responds to a rising edge of the request to send (RTS) modem control line by sending the timecode. Therefore, it is necessary that the operating system implement the <tt>TIOCMBIC</tt> and <tt>TIOCMBIS</tt> ioctl system calls and <tt>TIOCM_RTS</tt> control bit. Present restrictions require the use of a POSIX-compatible programming interface, although other interfaces may work as well.</p>
+<p>The clock message consists of 23 ASCII printing characters in the following format:</p>
+<pre>hh:mm:ss.f dd/mm/yr<cr>
hh:mm:ss.f = hours, minutes, seconds
f = deciseconds ('?' when out of spec)
dd/mm/yr = day, month, year</pre>
- <p>The alarm condition is indicated by '?', rather than a digit, at A. Note that 0?:??:??.? is displayed before synchronization is first established and hh:mm:ss.? once synchronization is established and then lost again for about a day.</p>
- <p>A fudge time1 value of .07 s appears to center the clock offset residuals.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>WWV</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Not used by this driver
- </dl>
- Additional Information
- <p><a href="../refclock.html">Reference Clock Drivers</a> </p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<p>The alarm condition is indicated by '?', rather than a digit, at A. Note that 0?:??:??.? is displayed before synchronization is first established and hh:mm:ss.? once synchronization is established and then lost again for about a day.</p>
+<p>A fudge time1 value of .07 s appears to center the clock offset residuals.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>WWV</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Not used by this driver</dd>
+</dl>
+Additional Information
+<p><a href="../refclock.html">Reference Clock Drivers</a> </p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
<title>PPS Clock Discipline</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
-
<body>
-
<h3>PPS Clock Discipline</h3>
-<hr>
-
-<p>Last change:
-
-<!-- #BeginDate format:En2m -->22-Apr-2009 15:02<!-- #EndDate -->
-UTC</p>
-
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ Last change:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 17:36<!-- #EndDate -->
+ UTC</p>
+ <hr>
<h4>Synopsis</h4>
-
<p>Address: 127.127.22.<i>u</i><br>
-Reference ID: <tt>PPS</tt><br>
-Driver ID: <tt>PPS</tt><br>
-Serial or Parallel Port: <tt>/dev/pps<i>u</i></tt><br>
-Requires: PPSAPI signal interface for PPS signal processing.</p>
-
+ Reference ID: <tt>PPS</tt><br>
+ Driver ID: <tt>PPS</tt><br>
+ Serial or Parallel Port: <tt>/dev/pps<i>u</i></tt><br>
+ Requires: PPSAPI signal interface for PPS signal processing.</p>
<p>Note: This driver supersedes an older one of the same name. The older driver operated with several somewhat archaic signal interface devices, required intricate configuration and was poorly documented. This driver requires the Pulse per Second API (PPSAPI)<sup>1</sup>. Note also that the <tt>pps</tt> configuration command has been obsoleted by this driver.</p>
-
<h4>Description</h4>
-
<p>This driver furnishes an interface for the pulse-per-second (PPS) signal produced by a cesium clock, radio clock or related devices. It can be used to augment the serial timecode generated by a GPS receiver, for example. It can be used to remove accumulated jitter and re-time a secondary server when synchronized to a primary server over a congested, wide-area network and before redistributing the time to local clients. The driver includes extensive signal sanity checks and grooming algorithms. A range gate and frequency discriminator reject noise and signals with incorrect frequency. A multiple-stage median filter rejects jitter due to hardware interrupt and operating system latencies. A trimmed-mean algorithm determines the best time samples. With typical workstations and processing loads, the incidental jitter can be reduced to a few microseconds.</p>
-
<p>While this driver can discipline the time and frequency relative to the PPS source, it cannot number the seconds. For this purpose an auxiliary source is required, ordinarily a radio clock operated as a primary reference (stratum 1) source; however, another NTP time server can be used as well. For this purpose, the auxiliary source should be specified as the prefer peer, as described in the <a href="../prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page.</p>
- <p>The driver requires the PPSAPI interface<sup>1</sup>, which is a proposed IETF standard. The interface consists of the <tt>timepps.h</tt> header file and associated kernel support. Support for this interface is included in current versions of Solaris, FreeBSD and Linux and proprietary versions of Tru64 (Alpha) and SunOS. See the <a href="../pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page for further information.</p>
- <p>The PPS source can be connected via a serial or parallel port, depending on the hardware and operating system. A serial port can be dedicated to the PPS source or shared with another device; however, if dedicated the data leads should not be connected, as noise or unexpected signals can cause <tt>ntpd</tt> to exit.</p>
- <p>A radio clock is usually connected via a serial port and the PPS source
- connected via a level converter to the data carrier detect (DCD)
- pin (DB-9 pin 1, DB-25 pin 8) of the same connector. In some systems
- where a parallel port and driver are available, the PPS signal can
- be connected directly to the ACK pin (DB25 pin 10) of the connector.
- Whether the PPS signal is connected via a dedicated port or shared with another
- device, the driver opens the device <tt>/dev/pps%d</tt>,
- where <tt>%d</tt> is the unit number. As with other drivers, links can be
- used to redirect the logical name to the actual physical device.</p>
- <p>The driver normally operates like any other driver and uses the same mitigation
- algorithms and PLL/FLL clock discipline incorporated in the daemon.
- If kernel PLL/FLL support is available, the kernel PLL/FLL clock
- discipline can be used instead. The default behavior is not to use
- the kernel PPS clock discipline, even if present. This driver incorporates
- a good deal of signal processing to reduce jitter using the median
- filter algorithm in the driver. As the result, performance
- with <tt>minpoll</tt> configured at 4 (16s) is generally
- better than the kernel PPS discipline. However, fudge flag 3 can
- be used to enable the kernel PPS discipline if necessary.</p>
- <p>This driver
- is enabled only under one of two conditions (a) a prefer peer other than
- this driver is among the survivors of the mitigation algorithms or (b)
- there are no survivors and the <tt>minsane</tt> option
- of the <tt>tos</tt> command is 0. The prefer peer designates another source
- that can reliably number the seconds when available . However, if no
- sources are available, the system clock continues to be disciplined by
- the PPS driver on an indefinite basis.</p>
- <p>A scenario where the latter behavior can be most useful is a planetary orbiter
- fleet, for instance in the vicinity of Mars, where contact between orbiters
- and Earth only one or two times per Sol (Mars day). These orbiters have a
- precise timing reference based on an Ultra Stable Oscillator (USO) with accuracy
- in the order of a Cesium oscillator. A PPS signal is derived from the USO
- and can be disciplined from Earth on rare occasion or from another orbiter
- via NTP. In the above scenario the PPS signal disciplines the spacecraft clock
- between NTP updates.</p>
- <p>In a similar scenario a PPS signal can be used to discipline the clock between
- updates produced by the modem driver. This would provide precise synchronization
- without needing the Internet at all.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>PPS</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Specifies PPS capture on the rising (assert) pulse edge if 0; falling
- (clear) edge if 1. (default),
- 1 for clear.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Controls the kernel PPS discipline: 0 for disable (default), 1 for enable.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Record a timestamp once for each second if 1. Useful for constructing
- Allan deviation plots..
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <p>Reference</p>
- <ol>
- <li>Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl. Pulse-per-second API for Unix-like operating systems, version 1. Request for Comments RFC-2783, Internet Engineering Task Force, March 2000, 31 pp.
- </ol>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<p>The driver requires the PPSAPI interface<sup>1</sup>, which is a proposed IETF standard. The interface consists of the <tt>timepps.h</tt> header file and associated kernel support. Support for this interface is included in current versions of Solaris, FreeBSD and Linux and proprietary versions of Tru64 (Alpha) and SunOS. See the <a href="../pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page for further information.</p>
+<p>The PPS source can be connected via a serial or parallel port, depending on the hardware and operating system. A serial port can be dedicated to the PPS source or shared with another device; however, if dedicated the data leads should not be connected, as noise or unexpected signals can cause <tt>ntpd</tt> to exit.</p>
+<p>A radio clock is usually connected via a serial port and the PPS source
+ connected via a level converter to the data carrier detect (DCD)
+ pin (DB-9 pin 1, DB-25 pin 8) of the same connector. In some systems
+ where a parallel port and driver are available, the PPS signal can
+ be connected directly to the ACK pin (DB25 pin 10) of the connector.
+ Whether the PPS signal is connected via a dedicated port or shared with another
+ device, the driver opens the device <tt>/dev/pps%d</tt>,
+ where <tt>%d</tt> is the unit number. As with other drivers, links can be
+ used to redirect the logical name to the actual physical device.</p>
+<p>The driver normally operates like any other driver and uses the same mitigation
+ algorithms and PLL/FLL clock discipline incorporated in the daemon.
+ If kernel PLL/FLL support is available, the kernel PLL/FLL clock
+ discipline can be used instead. The default behavior is not to use
+ the kernel PPS clock discipline, even if present. This driver incorporates
+ a good deal of signal processing to reduce jitter using the median
+ filter algorithm in the driver. As the result, performance
+ with <tt>minpoll</tt> configured at 4 (16s) is generally
+ better than the kernel PPS discipline. However, fudge flag 3 can
+ be used to enable the kernel PPS discipline if necessary.</p>
+<p>This driver
+ is enabled only under one of two conditions (a) a prefer peer other than
+ this driver is among the survivors of the mitigation algorithms or (b)
+ there are no survivors and the <tt>minsane</tt> option
+ of the <tt>tos</tt> command is 0. The prefer peer designates another source
+ that can reliably number the seconds when available . However, if no
+ sources are available, the system clock continues to be disciplined by
+ the PPS driver on an indefinite basis.</p>
+<p>A scenario where the latter behavior can be most useful is a planetary orbiter
+ fleet, for instance in the vicinity of Mars, where contact between orbiters
+ and Earth only one or two times per Sol (Mars day). These orbiters have a
+ precise timing reference based on an Ultra Stable Oscillator (USO) with accuracy
+ in the order of a Cesium oscillator. A PPS signal is derived from the USO
+ and can be disciplined from Earth on rare occasion or from another orbiter
+ via NTP. In the above scenario the PPS signal disciplines the spacecraft clock
+ between NTP updates.</p>
+<p>In a similar scenario a PPS signal can be used to discipline the clock between
+ updates produced by the modem driver. This would provide precise synchronization
+ without needing the Internet at all.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>PPS</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Specifies PPS capture on the rising (assert) pulse edge if 0; falling
+ (clear) edge if 1. (default), 1 for clear.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Controls the kernel PPS discipline: 0 for disable (default), 1 for enable.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Record a timestamp once for each second if 1. Useful for constructing
+ Allan deviation plots.</dd>
+ .
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a></p>
+<p>Reference</p>
+<ol>
+ <li>Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl. Pulse-per-second API for Unix-like operating systems, version 1. Request for Comments RFC-2783, Internet Engineering Task Force, March 2000, 31 pp.</li>
+</ol>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
- <meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
- <title>PSTI/Traconex 1020 WWV/WWVH Receiver</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>PSTI/Traconex 1020 WWV/WWVH Receiver</h3>
- <hr>
- <h4>Synopsis</h4>
- <p>Address: 127.127.3.<i>u</i><br>
- Reference ID: <tt>WWV</tt><br>
- Driver ID: <tt>WWV_PST</tt><br>
- Serial Port: <tt>/dev/wwv<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
- Features: <tt>tty_clk</tt></p>
- <h4>Description</h4>
- <p>This driver supports the PSTI 1010 and Traconex 1020 WWV/WWVH Receivers. No specific claim of accuracy is made for these receiver, but actual experience suggests that 10 ms would be a conservative assumption.</p>
- <p>The dipswitches should be set for 9600 bps line speed, 24-hour day-of-year format and UTC time zone. Automatic correction for DST should be disabled. It is very important that the year be set correctly in the DIP-switches; otherwise, the day of year will be incorrect after 28 April of a normal or leap year. As the there are only four dipswitches to set the year and the base value of zero correspondes to 1986, years beyond 2001 recycle with the value of zero corresponding to 2002. The propagation delay DIP-switches should be set according to the distance from the transmitter for both WWV and WWVH, as described in the instructions. While the delay can be set only to within 11 ms, the fudge time1 parameter can be used for vernier corrections.</p>
- <p>Using the poll sequence <tt>QTQDQM</tt>, the response timecode is in three sections totalling 50 ASCII printing characters, as concatenated by the driver, in the following format:</p>
- <pre>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
+<meta name="GENERATOR" content="Mozilla/4.01 [en] (Win95; I) [Netscape]">
+<title>PSTI/Traconex 1020 WWV/WWVH Receiver</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>PSTI/Traconex 1020 WWV/WWVH Receiver</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+Last update:
+ <!-- #BeginDate format:En2m -->09-Sep-2010 18:45<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<p>Address: 127.127.3.<i>u</i><br>
+ Reference ID: <tt>WWV</tt><br>
+ Driver ID: <tt>WWV_PST</tt><br>
+ Serial Port: <tt>/dev/wwv<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
+ Features: <tt>tty_clk</tt></p>
+<h4>Description</h4>
+<p>This driver supports the PSTI 1010 and Traconex 1020 WWV/WWVH Receivers. No specific claim of accuracy is made for these receiver, but actual experience suggests that 10 ms would be a conservative assumption.</p>
+<p>The dipswitches should be set for 9600 bps line speed, 24-hour day-of-year format and UTC time zone. Automatic correction for DST should be disabled. It is very important that the year be set correctly in the DIP-switches; otherwise, the day of year will be incorrect after 28 April of a normal or leap year. As the there are only four dipswitches to set the year and the base value of zero correspondes to 1986, years beyond 2001 recycle with the value of zero corresponding to 2002. The propagation delay DIP-switches should be set according to the distance from the transmitter for both WWV and WWVH, as described in the instructions. While the delay can be set only to within 11 ms, the fudge time1 parameter can be used for vernier corrections.</p>
+<p>Using the poll sequence <tt>QTQDQM</tt>, the response timecode is in three sections totalling 50 ASCII printing characters, as concatenated by the driver, in the following format:</p>
+<pre>
ahh:mm:ss.fffs<cr> yy/dd/mm/ddd<cr>
frdzycchhSSFTttttuuxx<cr>
tttt = time since last update (0000 = minutes)
uu = flush character (03 = ^c)
xx = 94 (unknown)</pre>
- <p>The alarm condition is indicated by other than <tt>8</tt> at <tt>a</tt>, which occurs during initial synchronization and when received signal is lost for an extended period; unlock condition is indicated by other than <tt>0000</tt> in the <tt>tttt</tt> subfield.</p>
- <h4>Monitor Data</h4>
- <p>When enabled by the <tt>flag4</tt> fudge flag, every received timecode is written as-is to the <tt>clockstats</tt> file.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>WWV</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Not used by this driver.
- </dl>
- <h4>Additional Information</h4>
- <p><a href="../refclock.html">Reference Clock Drivers</a></p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<p>The alarm condition is indicated by other than <tt>8</tt> at <tt>a</tt>, which occurs during initial synchronization and when received signal is lost for an extended period; unlock condition is indicated by other than <tt>0000</tt> in the <tt>tttt</tt> subfield.</p>
+<h4>Monitor Data</h4>
+<p>When enabled by the <tt>flag4</tt> fudge flag, every received timecode is written as-is to the <tt>clockstats</tt> file.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
+ <dt><tt>time2 <i>time</i></tt>
+ <dd>Not used by this driver.
+ <dt><tt>stratum <i>number</i></tt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
+ <dt><tt>refid <i>string</i></tt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>WWV</tt>.
+ <dt><tt>flag1 0 | 1</tt>
+ <dd>Not used by this driver.
+ <dt><tt>flag2 0 | 1</tt>
+ <dd>Not used by this driver.
+ <dt><tt>flag3 0 | 1</tt>
+ <dd>Not used by this driver.
+ <dt><tt>flag4 0 | 1</tt>
+ <dd>Not used by this driver.
+</dl>
+<h4>Additional Information</h4>
+<p><a href="../refclock.html">Reference Clock Drivers</a></p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Radio WWV/H Audio Demodulator/Decoder</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Radio WWV/H Audio Demodulator/Decoder</h3>
- <hr>
- <h4>Synopsis</h4>
- Address: 127.127.36.<i>u</i><br>
- Reference ID: <tt>WV<i>f</i></tt> or <tt>WH<i>f</i></tt><br>
- Driver ID: <tt>WWV_AUDIO</tt><br>
- Autotune Port: <tt>/dev/icom</tt>; 1200/9600 baud, 8-bits, no parity<br>
- Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt>
- <h4>Description</h4>This driver synchronizes the computer time using shortwave radio transmissions from NIST time/frequency stations <a href="http://www.bldrdoc.gov/timefreq/stations/wwv.html">WWV</a> in Ft. Collins, CO, and <a href="http://www.bldrdoc.gov/timefreq/stations/wwvh.htm">WWVH</a> in Kauai, HI. Transmissions are made continuously on 2.5, 5, 10 and 15 MHz from both stations and on 20 MHz from WWV. An ordinary shortwave receiver can be tuned manually to one of these frequencies or, in the case of ICOM receivers, the receiver can be tuned automatically by the driver as propagation conditions change throughout the day and season. The radio is connected via an optional attenuator and cable to either the microphone or line-in port of a workstation or PC.
- <p>The driver requires an audio codec or sound card with sampling rate 8 kHz and <font face="symbol">m</font>-law companding to demodulate the data. This is the same standard as used by the telephone industry and is supported by most hardware and operating systems, including Solaris, FreeBSD and Linux, among others. In this implementation only one audio driver and codec can be supported on a single machine. In order to assure reliable signal capture, the codec frequency error must be less than 187 PPM (.0187 percent). If necessary, the <tt>tinker codec</tt> configuration command can be used to bracket the codec frequency to this range.</p>
- <p>In general and without calibration, the driver is accurate within 1 ms relative to the broadcast time when tracking a station. However, variations up to 0.3 ms can be expected due to diurnal variations in ionospheric layer height and ray geometry. In Newark DE, 2479 km from the transmitter, the predicted two-hop propagation delay varies from 9.3 ms in sunlight to 9.0 ms in moonlight. When not tracking the station the accuracy depends on the computer clock oscillator stability, ordinarily better than 0.5 PPM.</p>
- <p>After calibration relative to the PPS signal from a GPS receiver, the mean offset with a 2.4-GHz P4 running FreeBSD 6.1 is generally within 0.1 ms short-term with 0.4 ms jitter. The long-term mean offset varies up to 0.3 ms due to propagation path geometry variations. The processor load due to the driver is 0.4 percent on the P4.</p>
- <p>The driver performs a number of error checks to protect against overdriven or underdriven input signal levels, incorrect signal format or improper hardware configuration. The specific checks are detailed later in this page. Note that additional checks are done elsewhere in the reference clock interface routines.</p>
- <p>This driver incorporates several features in common with other audio drivers such as described in the <a href="driver7.html">Radio CHU Audio Demodulator/Decoder</a> and the <a href="driver6.html">IRIG Audio Decoder</a> pages. They include automatic gain control (AGC), selectable audio codec port and signal monitoring capabilities. For a discussion of these common features, as well as a guide to hookup, debugging and monitoring, see the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
- <h4>Technical Overview</h4>
- <p>The driver processes 8-kHz <font face="symbol">m</font>-law companded codec samples using maximum-likelihood techniques which exploit the considerable degree of redundancy available in the broadcast signal. The WWV signal format is described in NIST Special Publication 432 (Revised 1990) and also available on the <a href="http://tf.nist.gov/stations/wwvtimecode.htm">WWV/H web site</a>. It consists of three elements, a 5-ms, 1000-Hz pulse, which occurs at the beginning of each second, a 800-ms, 1000-Hz pulse, which occurs at the beginning of each minute, and a pulse-width modulated 100-Hz subcarrier for the data bits, one bit per second. The WWVH format is identical, except that the 1000-Hz pulses are sent at 1200 Hz. Each minute encodes nine BCD digits for the time of century plus seven bits for the daylight savings time (DST) indicator, leap warning indicator and DUT1 correction.</p>
- <p>The demodulation and decoding algorithms used by this driver are based on a machine language program developed for the TAPR DSP93 DSP unit, which uses the TI 320C25 DSP chip. The analysis, design and performance of the program for this unit is described in: Mills, D.L. A precision radio clock for WWV transmissions. Electrical Engineering Report 97-8-1, University of Delaware, August 1997, 25 pp. Available from <a href="http://www.eecis.udel.edu/%7emills/reports.html">www.eecis.udel.edu/~mills/reports.htm</a>. For use in this driver, the original program was rebuilt in the C language and adapted to the NTP driver interface. The algorithms have been modified to improve performance, especially under weak signal conditions and to provide an automatic frequency and station selection feature.</p>
- <p>As in the original program, the clock discipline is modelled as a Markov process, with probabilistic state transitions corresponding to a conventional clock and the probabilities of received decimal digits. The result is a performance level with very high accuracy and reliability, even under conditions when the minute beep of the signal, normally its most prominent feature, can barely be detected by ear using a communications receiver.</p>
- <h4>Baseband Signal Processing</h4>
- <p>The 1000/1200-Hz pulses and 100-Hz subcarrier are first separated using a 600-Hz bandpass filter centered on 1100 Hz and a 150-Hz lowpass filter. The minute pulse is extracted using an 800-ms synchronous matched filter and pulse grooming logic which discriminates between WWV and WWVH signals and noise. The second pulse is extracted using a 5-ms FIR matched filter for each station and a single 8000-stage comb filter.</p>
- <p>The phase of the 100-Hz subcarrier relative to the second pulse is fixed at the transmitter; however, the audio stage in many radios affects the phase response at 100 Hz in unpredictable ways. The driver adjusts for each radio using two 170-ms synchronous matched filters. The I (in-phase) filter is used to demodulate the subcarrier envelope, while the Q (quadrature-phase) filter is used in a type-1 phase-lock loop (PLL) to discipline the demodulator phase.</p>
- <p>A bipolar data signal is determined from the matched filter subcarrier envelope using a pulse-width discriminator. The discriminator samples the I channel at 15 ms (<i>n</i>), 200 ms (<i>s</i><sub>0</sub>) and 500 ms (<i>s</i><sub>1</sub>), and the envelope (RMS I and Q channels) at 200 ms (<i>e</i><sub>1</sub>) and the end of the second (<i>e</i><sub>0</sub>). The bipolar data signal is expressed 2<i>s</i><sub>1</sub> - <i>s</i><sub>0</sub> - <i>n</i>, where positive values correspond to data 1 and negative values correspond to data 0. Note that, since the signals <i>s</i><sub>0</sub> and <i>s</i><sub>1</sub> include the noise <i>n</i>, the noise component cancels out. The data bit SNR is calculated as 20 log<sub>10</sub>(<i>e</i><sub>1</sub> / <i>e</i><sub>0</sub>). If the driver has not synchronized to the minute pulse, or if the data bit amplitude <i>e</i><sub>1</sub> or SNR are below thresholds, the bit is considered invalid and the bipolar signal is forced to zero.</p>
- <p>The bipolar signal is exponentially averaged in a set of 60 accumulators, one for each second, to determine the semi-static miscellaneous bits, such as DST indicator, leap second warning and DUT1 correction. In this design a data average value larger than a positive threshold is interpreted as +1 (hit) and a value smaller than a negative threshold as a -1 (miss). Values between the two thresholds, which can occur due to signal fades, are interpreted as an erasure and result in no change of indication.</p>
- <h4>Maximum-Likelihood Decoder</h4>
- <p>The BCD digit in each digit position of the timecode is represented as four data bits. The bits are correlated with the bits corresponding to each of the valid decimal digits in this position. If any of the four bits are invalid, the correlated value for all digits in this position is assumed zero. In either case, the values for all digits are exponentially averaged in a likelihood vector associated with this position. The digit associated with the maximum over all averaged values then becomes the maximum-likelihood candidate for this position and the ratio of the maximum over the next lower value represents the digit SNR.</p>
- <p>The decoding matrix contains nine row vectors, one for each digit position. Each row vector includes the maximum-likelihood digit, likelihood vector and other related data. The maximum-likelihood digit for each of the nine digit positions becomes the maximum-likelihood time of the century. A built-in transition function implements a conventional clock with decimal digits that count the minutes, hours, days and years, as corrected for leap seconds and leap years. The counting operation also rotates the likelihood vector corresponding to each digit as it advances. Thus, once the clock is set, each clock digit should correspond to the maximum-likelihood digit as transmitted.</p>
- <p>Each row of the decoding matrix also includes a compare counter and the most recently determined maximum-likelihood digit. If a digit likelihood exceeds the decision level and compares with previous digits for a number of successive minutes in any row, the maximum-likelihood digit replaces the clock digit in that row. When this condition is true for all rows and the second epoch has been reliably determined, the clock is set (or verified if it has already been set) and delivers correct time to the integral second. The fraction within the second is derived from the logical master clock, which runs at 8000 Hz and drives all system timing functions.</p>
- <h4>Master Clock Discipline</h4>
- <p>The logical master clock is derived from the audio codec clock. Its frequency is disciplined by a frequency-lock loop (FLL) which operates independently of the data recovery functions. The maximum value of the 5-ms pulse after the comb filter represents the on-time epoch of the second. At averaging intervals determined by the measured jitter, the frequency error is calculated as the difference between the epoches over the interval divided by the interval itself. The sample clock frequency is then corrected by this amount divided by a time constant of 8.</p>
- <p>When first started, the frequency averaging interval is 8 seconds, in order to compensate for intrinsic codec clock frequency offsets up to 125 PPM. Under most conditions, the averaging interval doubles in stages from the initial value to 1024 s, which results in an ultimate frequency resolution of 0.125 PPM, or about 11 ms/day.</p>
- <p>The data demodulation functions operate using the subcarrier clock, which is independent of the epoch. However, the data decoding functions are driven by the epoch. The decoder is phase-locked to the epoch in such a way that, when the clock state machine has reliably decoded the broadcast time to the second, the epoch timestamp of that second becomes a candidate to set the system clock.</p>
- <p>The comb filter can have a long memory and is vulnerable to noise and stale data, especially when coming up after a long fade. Therefore, a candidate is considered valid only if the 5-ms signal amplitude and SNR are above thresholds. In addition, the system clock is not set until after one complete averaging interval has passed with valid candidates.</p>
- <h4>Station Identification</h4>
- <p>It is important that the logical clock frequency is stable and accurately determined, since in many applications the shortwave radio will be tuned to a fixed frequency where WWV or WWVH signals are not available throughout the day. In addition, in some parts of the US, especially on the west coast, signals from either or both WWV and WWVH may be available at different times or even at the same time. Since the propagation times from either station are almost always different, each station must be reliably identified before attempting to set the clock.</p>
- <p>Reliable station identification requires accurate discrimination between very weak signals in noise and noise alone. The driver very aggressively soaks up every scrap of signal information, but has to be careful to avoid making pseudo-sense of noise alone. The signal quality metric depends on the minute pulse amplitude and SNR measured in second 0 of the minute, together with the data subcarrier amplitude and SNR measured in second 1. If all four values are above defined thresholds a hit is declared, otherwise a miss. In principle, the data pulse in second 58 is usable, but the AGC in most radios is not fast enough for a reliable measurement.</p>
- <p>The number of hits declared in the last 6 minutes for each station represents the high order bits of the metric, while the current minute pulse amplitude represents the low order bits. Only if the metric is above a defined threshold is the station signal considered acceptable. The metric is also used by the autotune function described below and reported in the timecode string.</p>
- <h4>Performance</h4>
- <p>It is the intent of the design that the accuracy and stability of the indicated time be limited only by the characteristics of the ionospheric propagation medium. Conventional wisdom is that manual synchronization via oscilloscope and HF medium is good only to a millisecond under the best propagation conditions. The performance of the NTP daemon disciplined by this driver is clearly better than this, even under marginal conditions.</p>
- <p>The figure below shows the measured offsets over a typical day near the bottom of the sunspot cycle ending in October, 2006. Variations up to ±0.4 ms can be expected due to changing ionospheric layer height and ray geometry over the day and night.</p>
- <div align="center">
- <img src="../pic/offset1211.gif" alt="gif"></div>
- <p>The figure was constructed using a 2.4-GHz P4 running FreeBSD 6.1. For these measurements the computer clock was disciplined within a few microseconds of UTC using a PPS signal and GPS receiver and the measured offsets determined from the filegen peerstats data.</p>
- <p>The predicted propagation delay from the WWV transmitter at Boulder, CO, to the receiver at Newark, DE, varies over 9.0-9.3 ms. In addition, the receiver contributes 4.7 ms and the 600-Hz bandpass filter 0.9 ms. With these values, the mean error is less than 0.1 ms and varies ±0.3 ms over the day as the result of changing ionospheric height and ray geometry.</p>
- <h4>Program Operation</h4>
- The driver begins operation immediately upon startup. It first searches for one or both of the stations WWV and WWVH and attempts to acquire minute synch. This may take some fits and starts, as the driver expects to see several consecutive minutes with good signals and low jitter. If the autotune function is active, the driver will rotate over all five frequencies and both WWV and WWVH stations until finding a station and frequency with acceptable metric.
- <p>While this is going on the the driver acquires second synch, which can take up to several minutes, depending on signal quality. When minute synch has been acquired, the driver accumulates likelihood values for the unit (seconds) digit of the nine timecode digits, plus the seven miscellaneous bits included in the WWV/H transmission format. When a good unit digit has been found, the driver accumulated likelihood values for the remaining eight digits of the timecode. When three repetitions of all nine digits have decoded correctly, which normally takes 15 minutes with good signals, and up to 40 minutes when buried in noise, and the second synch has been acquired, the clock is set (or verified) and is selectable to discipline the system clock.</p>
- <p>Once the clock is set, it continues to provide correct timecodes as long as the signal metric is above threshold, as described in the previous section. As long as the clock is correctly set or verified, the system clock offsets are provided once each minute to the reference clock interface, where they are processed using the same algorithms as with other reference clocks and remote servers.</p>
- <p>It may happen as the hours progress around the clock that WWV and WWVH signals may appear alone, together or not at all. When the driver has mitigated which station and frequency is best, it sets the reference identifier to the string WV<i>f</i> for WWV and WH<i>f</i> for WWVH, where <i>f</i> is the frequency in megahertz. If the propagation delays have been properly set with the <tt>fudge time1</tt> (WWV) and <tt>fudge time2</tt> (WWVH) commands in the configuration file, handover from one station to the other is seamless.</p>
- <p>Operation continues as long as the signal metric from at least one station on at least one frequency is acceptable. A consequence of this design is that, once the clock is set, the time and frequency are disciplined only by the second synch pulse and the clock digits themselves are driven by the clock state machine. If for some reason the state machine drifts to the wrong second, it would never resynchronize. To protect against this most unlikely situation, if after two days with no signals, the clock is considered unset and resumes the synchronization procedure from the beginning.</p>
- <p>Once the system clock been set correctly it will continue to read correctly even during the holdover interval, but with increasing dispersion. Assuming the system clock frequency can be disciplined within 1 PPM, it can coast without signals for several days without exceeding the NTP step threshold of 128 ms. During such periods the root distance increases at 15 <font face="Symbol">m</font>s per second, which makes the driver appear less likely for selection as time goes on. Eventually, when the distance due all causes exceeds 1 s, it is no longer suitable for synchronization. Ordinarily, this happens after about 18 hours with no signals. The <tt>tinker maxdist</tt> configuration command can be used to change this value.</p>
- <h4>Autotune</h4>
- <p>The driver includes provisions to automatically tune the radio in response to changing radio propagation conditions throughout the day and night. The radio interface is compatible with the ICOM CI-V standard, which is a bidirectional serial bus operating at TTL levels. The bus can be connected to a standard serial port using a level converter such as the CT-17. Further details are on the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
- <p>If specified, the driver will attempt to open the device <tt>/dev/icom</tt> and, if successful will activate the autotune function and tune the radio to each operating frequency in turn while attempting to acquire minute synch from either WWV or WWVH. However, the driver is liberal in what it assumes of the configuration. If the <tt>/dev/icom</tt> link is not present or the open fails or the CI-V bus is inoperative, the driver quietly gives up with no harm done.</p>
- <p>Once acquiring minute synch, the driver operates as described above to set the clock. However, during seconds 59, 0 and 1 of each minute it tunes the radio to one of the five broadcast frequencies to measure the signal metric as described above. Each of the five frequencies are probed in a five-minute rotation to build a database of current propagation conditions for all signals that can be heard at the time. At the end of each probe a mitigation procedure scans the database and retunes the radio to the best frequency and station found. For this to work well, the radio should be set for a fast AGC recovery time. This is most important while tracking a strong signal, which is normally the case, and then probing another frequency, which may have much weaker signals.</p>
- <p>The mitigation procedure selects the frequency and station with the highest valid metric, ties going first to the highest frequency and then to WWV in order. A station is considered valid only if the metric is above a specified threshold; if no station is above the metric, the rotating probes continue until a valid station is found.</p>
- <p>The behavior of the autotune function over a typical day is shown in the figure below.</p>
- <div align="center">
- <img src="../pic/freq1211.gif" alt="gif"></div>
- <p>As expected, the lower frequencies prevail when the ray path is in moonlight (0100-1300 UTC) and the higher frequencies when the path is in sunlight (1300-0100 UTC). Note three periods in the figure show zero frequency when signals are below the minimum for all frequencies and stations.</p>
- <h4>Debugging Aids</h4>
- <p>The most convenient way to track the driver status is using the <tt>ntpq</tt> program and the <tt>clockvar</tt> command. This displays the last determined timecode and related status and error counters, even when the driver is not disciplining the system clock. If the debugging trace feature (<tt>-d</tt> on the <tt>ntpd</tt> command line) is enabled, the driver produces detailed status messages as it operates. If the <tt>fudge flag 4</tt> is set, these messages are written to the <tt>clockstats</tt> file. All messages produced by this driver have the prefix <tt>wwv</tt> for convenient filtering with the Unix <tt>grep</tt> command.</p>
- <p>The autotune process produces diagnostic information along with the timecode. This is very useful for evaluating the performance of the algorithms, as well as radio propagation conditions in general. The message is produced once each minute for each frequency in turn after minute synch has been acquired.</p>
- <p><tt>wwv5 status agc epoch secamp/secsnr datamp/datsnr wwv wwvh</tt></p>
- <p>where the fields after the <tt>wwv5</tt> identifier are: <tt>status</tt> contains status bits, <tt>agc</tt> audio gain, <tt>epoch </tt>second epoch, <tt>secamp/secsnr </tt>second pulse amplitude/SNR, and <tt>wwv</tt> and <tt>wwvh</tt> are two sets of fields, one each for WWV and WWVH. Each of the two fields has the format</p>
- <p><tt>ident score metric minamp/minsnr</tt></p>
- <p>where <tt>ident </tt>encodes the station (<tt>WV</tt> for WWV, <tt>WH</tt> for WWVH) and frequency (2, 5, 10, 15 or 20), <tt>score</tt> 32-bit shift register recording the hits (1) and misses (0) of the last 32 probes (hits and misses enter from the right), <tt>metric</tt> is described above, and <tt>minamp/minsnr</tt> is the minute pulse ampliture/SNR. An example is:</p>
- <pre><tt>wwv5 000d 111 5753 3967/20.1 3523/10.2 WV20 bdeff 100 8348/30.0 WH20 0000 1 22/-12.4</tt></pre>
- <p>There are several other messages that can occur; these are documented in the source listing.</p>
- <h4>Monitor Data</h4>
-
-
- When enabled by the <tt>filegen</tt> facility, every received timecode is written to the <tt>clockstats</tt> file in the following format:
- <p><tt>sq yyyy ddd hh:mm:ss l d du lset agc ident metric errs freq avg<br>
- </tt></p>
- The fields beginning with <tt>yyyy</tt> and extending through <tt>du</tt> are decoded from the received data and are in fixed-length format. The remaining fields are in variable-length format. The fields are as follows:
- <dl>
- <dt><tt>s</tt>
- <dd>The synch indicator is initially <tt>?</tt> before the clock is set, but turns to space when all nine digits of the timecode are correctly set and the decoder is synchronized to the station within 125 <font face="Symbol">m</font>s.
- <dt><tt>q</tt>
- <dd>The quality character is a four-bit hexadecimal code showing which alarms have been raised. Each bit is associated with a specific alarm condition according to the following:
- <dl>
- <dt><tt>0x8</tt>
- <dd>synch alarm. The decoder is not synchronized to the station within 125 <font face="Symbol">m</font>s.
- <dt><tt>0x4</tt>
- <dd>Digit error alarm. Less than nine decimal digits were found in the last minute.<dt><tt>0x2</tt>
- <dd>Error alarm. More than 40 data bit errors were found in the last minute.<dt><tt>0x1</tt>
- <dd>Compare alarm. A maximum-likelihood digit failed to agree with the current associated clock digit in the last minute.</dl>It is important to note that one or more of the above alarms does not necessarily indicate a clock error, but only that the decoder has detected a marginal condition.<dt><tt>yyyy ddd hh:mm:ss</tt>
- <dd>The timecode format itself is self explanatory. Since the driver latches the on-time epoch directly from the second synch pulse, the seconds fraction is always zero. Although the transmitted timecode includes only the year of century, the Gregorian year is augmented by 2000.
- <dt><tt>l</tt>
- <dd>The leap second warning is normally space, but changes to <tt>L</tt> if a leap second is to occur at the end of the month.
- <dt><tt>d</tt>
- <dd>The DST state is <tt>S</tt> or <tt>D</tt> when standard time or daylight time is in effect, respectively. The state is <tt>I</tt> or <tt>O</tt> when daylight time is about to go into effect or out of effect, respectively.
- <dt><tt>du</tt>
- <dd>The DUT sign and magnitude shows the current UT1 offset relative to the displayed UTC time, in deciseconds.
- <dt><tt>lset</tt>
- <dd>Before the clock is set, the interval since last set is the number of minutes since the driver was started; after the clock is set, this is number of minutes since the decoder was last synchronized to the station within 125 <font face="Symbol">m</font>s.
- <dt><tt>agc</tt>
- <dd>The audio gain shows the current codec gain setting in the range 0 to 255. Ordinarily, the receiver audio gain control should be set for a value midway in this range.
- <dt><tt>ident</tt>
- <dd>The station identifier shows the station, <tt>WV<i>f</i></tt> for WWV or <tt>WH<i>f</i></tt> for WWVH, and frequency <i><tt>f</tt></i> being tracked. If neither station is heard on any frequency, the reference identifier shows <tt>NONE</tt>.
- <dt><tt>metric</tt>
- <dd>The signal metric described above from 0 (no signal) to 100 (best).
- <dt><tt>errs</tt>
- <dd>The bit error counter is useful to determine the quality of the data signal received in the most recent minute. It is normal to drop a couple of data bits even under good signal conditions and increasing numbers as conditions worsen. While the decoder performs moderately well even with half the bits are in error in any minute, usually by that point the metric drops below threshold and the decoder switches to a different frequency.<dt><tt>freq</tt>
- <dd>The frequency offset is the current estimate of the codec frequency offset to within 0.1 PPM. This may wander a bit over the day due to local temperature fluctuations and propagation conditions.
- <dt><tt>avg</tt>
- <dd>The averaging time is the interval between frequency updates in powers of two to a maximum of 1024 s. Attainment of the maximum indicates the driver is operating at the best possible resolution in time and frequency.
- </dl>
- <p>An example timecode is:</p>
- <p><tt>0 2000 006 22:36:00 S +3 1 115 WV20 86 5 66.4 1024</tt></p>
- <p>Here the clock has been set and no alarms are raised. The year, day and time are displayed along with no leap warning, standard time and DUT +0.3 s. The clock was set on the last minute, the AGC is safely in the middle ot the range 0-255, and the receiver is tracking WWV on 20 MHz. Good receiving conditions prevail, as indicated by the metric 86 and 5 bit errors during the last minute. The current frequency is 66.4 PPM and the averaging interval is 1024 s, indicating the maximum precision available.</p>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the propagation delay for WWV (40:40:49.0N 105:02:27.0W), in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Specifies the propagation delay for WWVH (21:59:26.0N 159:46:00.0W), in seconds and fraction, with default 0.0.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Ordinarily, this field specifies the driver reference identifier; however, the driver sets the reference identifier automatically as described above.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Specifies the microphone port if set to zero or the line-in port if set to one. It does not seem useful to specify the compact disc player port.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Enables audio monitoring of the input signal. For this purpose, the speaker volume must be set before the driver is started.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Enable verbose <tt>clockstats</tt> recording if set.
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Radio WWV/H Audio Demodulator/Decoder</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Radio WWV/H Audio Demodulator/Decoder</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+Last updage:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:10<!-- #EndDate -->
+UTC</p>
+<hr>
+<h4>Synopsis</h4>
+Address: 127.127.36.<i>u</i><br>
+Reference ID: <tt>WV<i>f</i></tt> or <tt>WH<i>f</i></tt><br>
+Driver ID: <tt>WWV_AUDIO</tt><br>
+Autotune Port: <tt>/dev/icom</tt>; 1200/9600 baud, 8-bits, no parity<br>
+Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt>
+<h4>Description</h4>
+This driver synchronizes the computer time using shortwave radio transmissions from NIST time/frequency stations <a href="http://www.bldrdoc.gov/timefreq/stations/wwv.html">WWV</a> in Ft. Collins, CO, and <a href="http://www.bldrdoc.gov/timefreq/stations/wwvh.htm">WWVH</a> in Kauai, HI. Transmissions are made continuously on 2.5, 5, 10 and 15 MHz from both stations and on 20 MHz from WWV. An ordinary shortwave receiver can be tuned manually to one of these frequencies or, in the case of ICOM receivers, the receiver can be tuned automatically by the driver as propagation conditions change throughout the day and season. The radio is connected via an optional attenuator and cable to either the microphone or line-in port of a workstation or PC.
+<p>The driver requires an audio codec or sound card with sampling rate 8 kHz and <font face="symbol">m</font>-law companding to demodulate the data. This is the same standard as used by the telephone industry and is supported by most hardware and operating systems, including Solaris, FreeBSD and Linux, among others. In this implementation only one audio driver and codec can be supported on a single machine. In order to assure reliable signal capture, the codec frequency error must be less than 187 PPM (.0187 percent). If necessary, the <tt>tinker codec</tt> configuration command can be used to bracket the codec frequency to this range.</p>
+<p>In general and without calibration, the driver is accurate within 1 ms relative to the broadcast time when tracking a station. However, variations up to 0.3 ms can be expected due to diurnal variations in ionospheric layer height and ray geometry. In Newark DE, 2479 km from the transmitter, the predicted two-hop propagation delay varies from 9.3 ms in sunlight to 9.0 ms in moonlight. When not tracking the station the accuracy depends on the computer clock oscillator stability, ordinarily better than 0.5 PPM.</p>
+<p>After calibration relative to the PPS signal from a GPS receiver, the mean offset with a 2.4-GHz P4 running FreeBSD 6.1 is generally within 0.1 ms short-term with 0.4 ms jitter. The long-term mean offset varies up to 0.3 ms due to propagation path geometry variations. The processor load due to the driver is 0.4 percent on the P4.</p>
+<p>The driver performs a number of error checks to protect against overdriven or underdriven input signal levels, incorrect signal format or improper hardware configuration. The specific checks are detailed later in this page. Note that additional checks are done elsewhere in the reference clock interface routines.</p>
+<p>This driver incorporates several features in common with other audio drivers such as described in the <a href="driver7.html">Radio CHU Audio Demodulator/Decoder</a> and the <a href="driver6.html">IRIG Audio Decoder</a> pages. They include automatic gain control (AGC), selectable audio codec port and signal monitoring capabilities. For a discussion of these common features, as well as a guide to hookup, debugging and monitoring, see the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
+<h4>Technical Overview</h4>
+<p>The driver processes 8-kHz <font face="symbol">m</font>-law companded codec samples using maximum-likelihood techniques which exploit the considerable degree of redundancy available in the broadcast signal. The WWV signal format is described in NIST Special Publication 432 (Revised 1990) and also available on the <a href="http://tf.nist.gov/stations/wwvtimecode.htm">WWV/H web site</a>. It consists of three elements, a 5-ms, 1000-Hz pulse, which occurs at the beginning of each second, a 800-ms, 1000-Hz pulse, which occurs at the beginning of each minute, and a pulse-width modulated 100-Hz subcarrier for the data bits, one bit per second. The WWVH format is identical, except that the 1000-Hz pulses are sent at 1200 Hz. Each minute encodes nine BCD digits for the time of century plus seven bits for the daylight savings time (DST) indicator, leap warning indicator and DUT1 correction.</p>
+<p>The demodulation and decoding algorithms used by this driver are based on a machine language program developed for the TAPR DSP93 DSP unit, which uses the TI 320C25 DSP chip. The analysis, design and performance of the program for this unit is described in: Mills, D.L. A precision radio clock for WWV transmissions. Electrical Engineering Report 97-8-1, University of Delaware, August 1997, 25 pp. Available from <a href="http://www.eecis.udel.edu/%7emills/reports.html">www.eecis.udel.edu/~mills/reports.htm</a>. For use in this driver, the original program was rebuilt in the C language and adapted to the NTP driver interface. The algorithms have been modified to improve performance, especially under weak signal conditions and to provide an automatic frequency and station selection feature.</p>
+<p>As in the original program, the clock discipline is modelled as a Markov process, with probabilistic state transitions corresponding to a conventional clock and the probabilities of received decimal digits. The result is a performance level with very high accuracy and reliability, even under conditions when the minute beep of the signal, normally its most prominent feature, can barely be detected by ear using a communications receiver.</p>
+<h4>Baseband Signal Processing</h4>
+<p>The 1000/1200-Hz pulses and 100-Hz subcarrier are first separated using a 600-Hz bandpass filter centered on 1100 Hz and a 150-Hz lowpass filter. The minute pulse is extracted using an 800-ms synchronous matched filter and pulse grooming logic which discriminates between WWV and WWVH signals and noise. The second pulse is extracted using a 5-ms FIR matched filter for each station and a single 8000-stage comb filter.</p>
+<p>The phase of the 100-Hz subcarrier relative to the second pulse is fixed at the transmitter; however, the audio stage in many radios affects the phase response at 100 Hz in unpredictable ways. The driver adjusts for each radio using two 170-ms synchronous matched filters. The I (in-phase) filter is used to demodulate the subcarrier envelope, while the Q (quadrature-phase) filter is used in a type-1 phase-lock loop (PLL) to discipline the demodulator phase.</p>
+<p>A bipolar data signal is determined from the matched filter subcarrier envelope using a pulse-width discriminator. The discriminator samples the I channel at 15 ms (<i>n</i>), 200 ms (<i>s</i><sub>0</sub>) and 500 ms (<i>s</i><sub>1</sub>), and the envelope (RMS I and Q channels) at 200 ms (<i>e</i><sub>1</sub>) and the end of the second (<i>e</i><sub>0</sub>). The bipolar data signal is expressed 2<i>s</i><sub>1</sub> - <i>s</i><sub>0</sub> - <i>n</i>, where positive values correspond to data 1 and negative values correspond to data 0. Note that, since the signals <i>s</i><sub>0</sub> and <i>s</i><sub>1</sub> include the noise <i>n</i>, the noise component cancels out. The data bit SNR is calculated as 20 log<sub>10</sub>(<i>e</i><sub>1</sub> / <i>e</i><sub>0</sub>). If the driver has not synchronized to the minute pulse, or if the data bit amplitude <i>e</i><sub>1</sub> or SNR are below thresholds, the bit is considered invalid and the bipolar signal is forced to zero.</p>
+<p>The bipolar signal is exponentially averaged in a set of 60 accumulators, one for each second, to determine the semi-static miscellaneous bits, such as DST indicator, leap second warning and DUT1 correction. In this design a data average value larger than a positive threshold is interpreted as +1 (hit) and a value smaller than a negative threshold as a -1 (miss). Values between the two thresholds, which can occur due to signal fades, are interpreted as an erasure and result in no change of indication.</p>
+<h4>Maximum-Likelihood Decoder</h4>
+<p>The BCD digit in each digit position of the timecode is represented as four data bits. The bits are correlated with the bits corresponding to each of the valid decimal digits in this position. If any of the four bits are invalid, the correlated value for all digits in this position is assumed zero. In either case, the values for all digits are exponentially averaged in a likelihood vector associated with this position. The digit associated with the maximum over all averaged values then becomes the maximum-likelihood candidate for this position and the ratio of the maximum over the next lower value represents the digit SNR.</p>
+<p>The decoding matrix contains nine row vectors, one for each digit position. Each row vector includes the maximum-likelihood digit, likelihood vector and other related data. The maximum-likelihood digit for each of the nine digit positions becomes the maximum-likelihood time of the century. A built-in transition function implements a conventional clock with decimal digits that count the minutes, hours, days and years, as corrected for leap seconds and leap years. The counting operation also rotates the likelihood vector corresponding to each digit as it advances. Thus, once the clock is set, each clock digit should correspond to the maximum-likelihood digit as transmitted.</p>
+<p>Each row of the decoding matrix also includes a compare counter and the most recently determined maximum-likelihood digit. If a digit likelihood exceeds the decision level and compares with previous digits for a number of successive minutes in any row, the maximum-likelihood digit replaces the clock digit in that row. When this condition is true for all rows and the second epoch has been reliably determined, the clock is set (or verified if it has already been set) and delivers correct time to the integral second. The fraction within the second is derived from the logical master clock, which runs at 8000 Hz and drives all system timing functions.</p>
+<h4>Master Clock Discipline</h4>
+<p>The logical master clock is derived from the audio codec clock. Its frequency is disciplined by a frequency-lock loop (FLL) which operates independently of the data recovery functions. The maximum value of the 5-ms pulse after the comb filter represents the on-time epoch of the second. At averaging intervals determined by the measured jitter, the frequency error is calculated as the difference between the epoches over the interval divided by the interval itself. The sample clock frequency is then corrected by this amount divided by a time constant of 8.</p>
+<p>When first started, the frequency averaging interval is 8 seconds, in order to compensate for intrinsic codec clock frequency offsets up to 125 PPM. Under most conditions, the averaging interval doubles in stages from the initial value to 1024 s, which results in an ultimate frequency resolution of 0.125 PPM, or about 11 ms/day.</p>
+<p>The data demodulation functions operate using the subcarrier clock, which is independent of the epoch. However, the data decoding functions are driven by the epoch. The decoder is phase-locked to the epoch in such a way that, when the clock state machine has reliably decoded the broadcast time to the second, the epoch timestamp of that second becomes a candidate to set the system clock.</p>
+<p>The comb filter can have a long memory and is vulnerable to noise and stale data, especially when coming up after a long fade. Therefore, a candidate is considered valid only if the 5-ms signal amplitude and SNR are above thresholds. In addition, the system clock is not set until after one complete averaging interval has passed with valid candidates.</p>
+<h4>Station Identification</h4>
+<p>It is important that the logical clock frequency is stable and accurately determined, since in many applications the shortwave radio will be tuned to a fixed frequency where WWV or WWVH signals are not available throughout the day. In addition, in some parts of the US, especially on the west coast, signals from either or both WWV and WWVH may be available at different times or even at the same time. Since the propagation times from either station are almost always different, each station must be reliably identified before attempting to set the clock.</p>
+<p>Reliable station identification requires accurate discrimination between very weak signals in noise and noise alone. The driver very aggressively soaks up every scrap of signal information, but has to be careful to avoid making pseudo-sense of noise alone. The signal quality metric depends on the minute pulse amplitude and SNR measured in second 0 of the minute, together with the data subcarrier amplitude and SNR measured in second 1. If all four values are above defined thresholds a hit is declared, otherwise a miss. In principle, the data pulse in second 58 is usable, but the AGC in most radios is not fast enough for a reliable measurement.</p>
+<p>The number of hits declared in the last 6 minutes for each station represents the high order bits of the metric, while the current minute pulse amplitude represents the low order bits. Only if the metric is above a defined threshold is the station signal considered acceptable. The metric is also used by the autotune function described below and reported in the timecode string.</p>
+<h4>Performance</h4>
+<p>It is the intent of the design that the accuracy and stability of the indicated time be limited only by the characteristics of the ionospheric propagation medium. Conventional wisdom is that manual synchronization via oscilloscope and HF medium is good only to a millisecond under the best propagation conditions. The performance of the NTP daemon disciplined by this driver is clearly better than this, even under marginal conditions.</p>
+<p>The figure below shows the measured offsets over a typical day near the bottom of the sunspot cycle ending in October, 2006. Variations up to ±0.4 ms can be expected due to changing ionospheric layer height and ray geometry over the day and night.</p>
+<div align="center"> <img src="../pic/offset1211.gif" alt="gif"></div>
+<p>The figure was constructed using a 2.4-GHz P4 running FreeBSD 6.1. For these measurements the computer clock was disciplined within a few microseconds of UTC using a PPS signal and GPS receiver and the measured offsets determined from the filegen peerstats data.</p>
+<p>The predicted propagation delay from the WWV transmitter at Boulder, CO, to the receiver at Newark, DE, varies over 9.0-9.3 ms. In addition, the receiver contributes 4.7 ms and the 600-Hz bandpass filter 0.9 ms. With these values, the mean error is less than 0.1 ms and varies ±0.3 ms over the day as the result of changing ionospheric height and ray geometry.</p>
+<h4>Program Operation</h4>
+The driver begins operation immediately upon startup. It first searches for one or both of the stations WWV and WWVH and attempts to acquire minute synch. This may take some fits and starts, as the driver expects to see several consecutive minutes with good signals and low jitter. If the autotune function is active, the driver will rotate over all five frequencies and both WWV and WWVH stations until finding a station and frequency with acceptable metric.
+<p>While this is going on the the driver acquires second synch, which can take up to several minutes, depending on signal quality. When minute synch has been acquired, the driver accumulates likelihood values for the unit (seconds) digit of the nine timecode digits, plus the seven miscellaneous bits included in the WWV/H transmission format. When a good unit digit has been found, the driver accumulated likelihood values for the remaining eight digits of the timecode. When three repetitions of all nine digits have decoded correctly, which normally takes 15 minutes with good signals, and up to 40 minutes when buried in noise, and the second synch has been acquired, the clock is set (or verified) and is selectable to discipline the system clock.</p>
+<p>Once the clock is set, it continues to provide correct timecodes as long as the signal metric is above threshold, as described in the previous section. As long as the clock is correctly set or verified, the system clock offsets are provided once each minute to the reference clock interface, where they are processed using the same algorithms as with other reference clocks and remote servers.</p>
+<p>It may happen as the hours progress around the clock that WWV and WWVH signals may appear alone, together or not at all. When the driver has mitigated which station and frequency is best, it sets the reference identifier to the string WV<i>f</i> for WWV and WH<i>f</i> for WWVH, where <i>f</i> is the frequency in megahertz. If the propagation delays have been properly set with the <tt>fudge time1</tt> (WWV) and <tt>fudge time2</tt> (WWVH) commands in the configuration file, handover from one station to the other is seamless.</p>
+<p>Operation continues as long as the signal metric from at least one station on at least one frequency is acceptable. A consequence of this design is that, once the clock is set, the time and frequency are disciplined only by the second synch pulse and the clock digits themselves are driven by the clock state machine. If for some reason the state machine drifts to the wrong second, it would never resynchronize. To protect against this most unlikely situation, if after two days with no signals, the clock is considered unset and resumes the synchronization procedure from the beginning.</p>
+<p>Once the system clock been set correctly it will continue to read correctly even during the holdover interval, but with increasing dispersion. Assuming the system clock frequency can be disciplined within 1 PPM, it can coast without signals for several days without exceeding the NTP step threshold of 128 ms. During such periods the root distance increases at 15 <font face="Symbol">m</font>s per second, which makes the driver appear less likely for selection as time goes on. Eventually, when the distance due all causes exceeds 1 s, it is no longer suitable for synchronization. Ordinarily, this happens after about 18 hours with no signals. The <tt>tinker maxdist</tt> configuration command can be used to change this value.</p>
+<h4>Autotune</h4>
+<p>The driver includes provisions to automatically tune the radio in response to changing radio propagation conditions throughout the day and night. The radio interface is compatible with the ICOM CI-V standard, which is a bidirectional serial bus operating at TTL levels. The bus can be connected to a standard serial port using a level converter such as the CT-17. Further details are on the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
+<p>If specified, the driver will attempt to open the device <tt>/dev/icom</tt> and, if successful will activate the autotune function and tune the radio to each operating frequency in turn while attempting to acquire minute synch from either WWV or WWVH. However, the driver is liberal in what it assumes of the configuration. If the <tt>/dev/icom</tt> link is not present or the open fails or the CI-V bus is inoperative, the driver quietly gives up with no harm done.</p>
+<p>Once acquiring minute synch, the driver operates as described above to set the clock. However, during seconds 59, 0 and 1 of each minute it tunes the radio to one of the five broadcast frequencies to measure the signal metric as described above. Each of the five frequencies are probed in a five-minute rotation to build a database of current propagation conditions for all signals that can be heard at the time. At the end of each probe a mitigation procedure scans the database and retunes the radio to the best frequency and station found. For this to work well, the radio should be set for a fast AGC recovery time. This is most important while tracking a strong signal, which is normally the case, and then probing another frequency, which may have much weaker signals.</p>
+<p>The mitigation procedure selects the frequency and station with the highest valid metric, ties going first to the highest frequency and then to WWV in order. A station is considered valid only if the metric is above a specified threshold; if no station is above the metric, the rotating probes continue until a valid station is found.</p>
+<p>The behavior of the autotune function over a typical day is shown in the figure below.</p>
+<div align="center"> <img src="../pic/freq1211.gif" alt="gif"></div>
+<p>As expected, the lower frequencies prevail when the ray path is in moonlight (0100-1300 UTC) and the higher frequencies when the path is in sunlight (1300-0100 UTC). Note three periods in the figure show zero frequency when signals are below the minimum for all frequencies and stations.</p>
+<h4>Debugging Aids</h4>
+<p>The most convenient way to track the driver status is using the <tt>ntpq</tt> program and the <tt>clockvar</tt> command. This displays the last determined timecode and related status and error counters, even when the driver is not disciplining the system clock. If the debugging trace feature (<tt>-d</tt> on the <tt>ntpd</tt> command line) is enabled, the driver produces detailed status messages as it operates. If the <tt>fudge flag 4</tt> is set, these messages are written to the <tt>clockstats</tt> file. All messages produced by this driver have the prefix <tt>wwv</tt> for convenient filtering with the Unix <tt>grep</tt> command.</p>
+<p>The autotune process produces diagnostic information along with the timecode. This is very useful for evaluating the performance of the algorithms, as well as radio propagation conditions in general. The message is produced once each minute for each frequency in turn after minute synch has been acquired.</p>
+<p><tt>wwv5 status agc epoch secamp/secsnr datamp/datsnr wwv wwvh</tt></p>
+<p>where the fields after the <tt>wwv5</tt> identifier are: <tt>status</tt> contains status bits, <tt>agc</tt> audio gain, <tt>epoch </tt>second epoch, <tt>secamp/secsnr </tt>second pulse amplitude/SNR, and <tt>wwv</tt> and <tt>wwvh</tt> are two sets of fields, one each for WWV and WWVH. Each of the two fields has the format</p>
+<p><tt>ident score metric minamp/minsnr</tt></p>
+<p>where <tt>ident </tt>encodes the station (<tt>WV</tt> for WWV, <tt>WH</tt> for WWVH) and frequency (2, 5, 10, 15 or 20), <tt>score</tt> 32-bit shift register recording the hits (1) and misses (0) of the last 32 probes (hits and misses enter from the right), <tt>metric</tt> is described above, and <tt>minamp/minsnr</tt> is the minute pulse ampliture/SNR. An example is:</p>
+<pre><tt>wwv5 000d 111 5753 3967/20.1 3523/10.2 WV20 bdeff 100 8348/30.0 WH20 0000 1 22/-12.4</tt></pre>
+<p>There are several other messages that can occur; these are documented in the source listing.</p>
+<h4>Monitor Data</h4>
+When enabled by the <tt>filegen</tt> facility, every received timecode is written to the <tt>clockstats</tt> file in the following format:
+<p><tt>sq yyyy ddd hh:mm:ss l d du lset agc ident metric errs freq avg<br>
+ </tt></p>
+The fields beginning with <tt>yyyy</tt> and extending through <tt>du</tt> are decoded from the received data and are in fixed-length format. The remaining fields are in variable-length format. The fields are as follows:
+<dl>
+ <dt><tt>s</tt></dt>
+ <dd>The synch indicator is initially <tt>?</tt> before the clock is set, but turns to space when all nine digits of the timecode are correctly set and the decoder is synchronized to the station within 125 <font face="Symbol">m</font>s.</dd>
+ <dt><tt>q</tt></dt>
+ <dd>The quality character is a four-bit hexadecimal code showing which alarms have been raised. Each bit is associated with a specific alarm condition according to the following:
+ <dl>
+ <dt><tt>0x8</tt></dt>
+ <dd>synch alarm. The decoder is not synchronized to the station within 125 <font face="Symbol">m</font>s.</dd>
+ <dt><tt>0x4</tt></dt>
+ <dd>Digit error alarm. Less than nine decimal digits were found in the last minute.</dd>
+ <dt><tt>0x2</tt></dt>
+ <dd>Error alarm. More than 40 data bit errors were found in the last minute.</dd>
+ <dt><tt>0x1</tt></dt>
+ <dd>Compare alarm. A maximum-likelihood digit failed to agree with the current associated clock digit in the last minute.</dd>
+ </dl>
+ It is important to note that one or more of the above alarms does not necessarily indicate a clock error, but only that the decoder has detected a marginal condition.</dd>
+ <dt><tt>yyyy ddd hh:mm:ss</tt></dt>
+ <dd>The timecode format itself is self explanatory. Since the driver latches the on-time epoch directly from the second synch pulse, the seconds fraction is always zero. Although the transmitted timecode includes only the year of century, the Gregorian year is augmented by 2000.</dd>
+ <dt><tt>l</tt></dt>
+ <dd>The leap second warning is normally space, but changes to <tt>L</tt> if a leap second is to occur at the end of the month.</dd>
+ <dt><tt>d</tt></dt>
+ <dd>The DST state is <tt>S</tt> or <tt>D</tt> when standard time or daylight time is in effect, respectively. The state is <tt>I</tt> or <tt>O</tt> when daylight time is about to go into effect or out of effect, respectively.</dd>
+ <dt><tt>du</tt></dt>
+ <dd>The DUT sign and magnitude shows the current UT1 offset relative to the displayed UTC time, in deciseconds.</dd>
+ <dt><tt>lset</tt></dt>
+ <dd>Before the clock is set, the interval since last set is the number of minutes since the driver was started; after the clock is set, this is number of minutes since the decoder was last synchronized to the station within 125 <font face="Symbol">m</font>s.</dd>
+ <dt><tt>agc</tt></dt>
+ <dd>The audio gain shows the current codec gain setting in the range 0 to 255. Ordinarily, the receiver audio gain control should be set for a value midway in this range.</dd>
+ <dt><tt>ident</tt></dt>
+ <dd>The station identifier shows the station, <tt>WV<i>f</i></tt> for WWV or <tt>WH<i>f</i></tt> for WWVH, and frequency <i><tt>f</tt></i> being tracked. If neither station is heard on any frequency, the reference identifier shows <tt>NONE</tt>.</dd>
+ <dt><tt>metric</tt></dt>
+ <dd>The signal metric described above from 0 (no signal) to 100 (best).</dd>
+ <dt><tt>errs</tt></dt>
+ <dd>The bit error counter is useful to determine the quality of the data signal received in the most recent minute. It is normal to drop a couple of data bits even under good signal conditions and increasing numbers as conditions worsen. While the decoder performs moderately well even with half the bits are in error in any minute, usually by that point the metric drops below threshold and the decoder switches to a different frequency.</dd>
+ <dt><tt>freq</tt></dt>
+ <dd>The frequency offset is the current estimate of the codec frequency offset to within 0.1 PPM. This may wander a bit over the day due to local temperature fluctuations and propagation conditions.</dd>
+ <dt><tt>avg</tt></dt>
+ <dd>The averaging time is the interval between frequency updates in powers of two to a maximum of 1024 s. Attainment of the maximum indicates the driver is operating at the best possible resolution in time and frequency.</dd>
+</dl>
+<p>An example timecode is:</p>
+<p><tt>0 2000 006 22:36:00 S +3 1 115 WV20 86 5 66.4 1024</tt></p>
+<p>Here the clock has been set and no alarms are raised. The year, day and time are displayed along with no leap warning, standard time and DUT +0.3 s. The clock was set on the last minute, the AGC is safely in the middle ot the range 0-255, and the receiver is tracking WWV on 20 MHz. Good receiving conditions prevail, as indicated by the metric 86 and 5 bit errors during the last minute. The current frequency is 66.4 PPM and the averaging interval is 1024 s, indicating the maximum precision available.</p>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the propagation delay for WWV (40:40:49.0N 105:02:27.0W), in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Specifies the propagation delay for WWVH (21:59:26.0N 159:46:00.0W), in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Ordinarily, this field specifies the driver reference identifier; however, the driver sets the reference identifier automatically as described above.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Specifies the microphone port if set to zero or the line-in port if set to one. It does not seem useful to specify the compact disc player port.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Enables audio monitoring of the input signal. For this purpose, the speaker volume must be set before the driver is started.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Enable verbose <tt>clockstats</tt> recording if set.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<title>Spectracom WWVB/GPS Receivers</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
<style type="text/css">
<!--
-.style1 {font-family: Symbol}
+.style1 {
+ font-family: Symbol
+}
-->
</style>
</head>
-
<body>
-
<h3>Spectracom WWVB/GPS Receivers</h3>
-
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:06<!-- #EndDate -->
+ UTC</p>
<hr>
-Last update:
-
-<!-- #BeginDate format:En2m -->22-Apr-2009 15:00<!-- #EndDate -->
-UTC</p>
-
<h4>Synopsis</h4>
-
<p>Address: 127.127.4.<i>u</i><br>
-Reference ID: <tt>WWVB</tt><br>
-Driver ID: <tt>WWVB_SPEC</tt><br>
-Serial Port: <tt>/dev/wwvb<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
-Features: Optional PPS signal processing, <tt>tty_clk</tt><br>
-Requires: Optional PPS signal processing requires the PPSAPI signal interface.</p>
-
+ Reference ID: <tt>WWVB</tt><br>
+ Driver ID: <tt>WWVB_SPEC</tt><br>
+ Serial Port: <tt>/dev/wwvb<i>u</i></tt>; 9600 baud, 8-bits, no parity<br>
+ Features: Optional PPS signal processing, <tt>tty_clk</tt><br>
+ Requires: Optional PPS signal processing requires the PPSAPI signal interface.</p>
<h4>Description</h4>
-
<p>This driver supports all known Spectracom radio and satellite clocks, including the Model 8170 and Netclock/2 WWVB Synchronized Clocks and the Netclock/GPS GPS Master Clock. The claimed accuracy of the WWVB clocks is 100 <span class="style1">m</span>s relative to the broadcast signal. These clocks have proven a reliable source of time, except in some parts of the country with high levels of conducted RF interference. WIth the GPS clock the claimed accuracy is 130 ns. However, in most cases the actual accuracy is limited by the precision of the timecode and the latencies of the serial interface and operating system.</p>
-
<p>The DIPswitches on these clocks should be set to 24-hour display, AUTO DST off, data format 0 or 2 (see below) and baud rate 9600. If this clock is used as the source for the IRIG Audio Decoder (<tt>refclock_irig.c</tt> in this distribution), set the DIPswitches for AM IRIG output and IRIG format 1 (IRIG B with signature control).</p>
-
<p>There are two timecode formats used by these clocks. Format 0, which is available with all clocks, and format 2, which is available with all clocks except the original (unmodified) Model 8170.</p>
-
<p>Format 0 (22 ASCII printing characters):<br>
-<cr><lf>i ddd hh:mm:ss TZ=zz<cr><lf></p>
-
+ <cr><lf>i ddd hh:mm:ss TZ=zz<cr><lf></p>
<p>on-time = first <cr><br>
-i = synchronization flag (' ' = in synch, '?' = out synch)<br>
-hh:mm:ss = hours, minutes, seconds</p>
-
+ i = synchronization flag (' ' = in synch, '?' = out synch)<br>
+ hh:mm:ss = hours, minutes, seconds</p>
<p>The alarm condition is indicated by other than ' ' at <tt>i</tt>, which occurs during initial synchronization and when received signal is lost for about ten hours.</p>
-
<p>Format 2 (24 ASCII printing characters):<br>
-lt;cr>lf>iqyy ddd hh:mm:ss.fff ld</p>
-
+ lt;cr>lf>iqyy ddd hh:mm:ss.fff ld</p>
<p>on-time = <cr><br>
-i = synchronization flag (' ' = in synch, '?' = out synch)<br>
-q = quality indicator (' ' = locked, 'A'...'D' = unlocked)<br>
-yy = year (as broadcast)<br>
-ddd = day of year<br>
-hh:mm:ss.fff = hours, minutes, seconds, milliseconds</p>
-
+ i = synchronization flag (' ' = in synch, '?' = out synch)<br>
+ q = quality indicator (' ' = locked, 'A'...'D' = unlocked)<br>
+ yy = year (as broadcast)<br>
+ ddd = day of year<br>
+ hh:mm:ss.fff = hours, minutes, seconds, milliseconds</p>
<p>The alarm condition is indicated by other than ' ' at <tt>i</tt>, which occurs during initial synchronization and when received signal is lost for about ten hours. The unlock condition is indicated by other than ' ' at <tt>q</tt>.</p>
-
<p>The <tt>q</tt> is normally ' ' when the time error is less than 1 ms and a character in the set <tt>A...D</tt> when the time error is less than 10, 100, 500 and greater than 500 ms respectively. The <tt>l</tt> is normally ' ', but is set to <tt>L</tt> early in the month of an upcoming UTC leap second and reset to ' ' on the first day of the following month. The <tt>d</tt> is set to <tt>S</tt> for standard time <tt>S</tt>, <tt>I</tt> on the day preceding a switch to daylight time, <tt>D</tt> for daylight time and <tt>O</tt> on the day preceding a switch to standard time. The start bit of the first <cr> is synchronized to the indicated time as returned.</p>
-
<p>This driver does not need to be told which format is in use - it figures out which one from the length of the message. A three-stage median filter is used to reduce jitter and provide a dispersion measure. The driver makes no attempt to correct for the intrinsic jitter of the radio itself, which is a known problem with the older radios.</p>
-
-<h4<PPS Signal Processing</h4>
-
+<h4>PPS Signal Processing</h4>
<p>When PPS signal processing is enabled, and when the system clock has been set by this or another driver and the PPS signal offset is within 0.4 s of the system clock offset, the PPS signal replaces the timecode for as long as the PPS signal is active. If for some reason the PPS signal fails for one or more poll intervals, the driver reverts to the timecode. If the timecode fails for one or more poll intervals, the PPS signal is disconnected.</p>
-
<h4>Monitor Data</h4>
-
<p>The driver writes each timecode as received to the <tt>clockstats</tt> file. When enabled by the <tt>flag4</tt> fudge flag, a table of quality data maintained internally by the Netclock/2 is retrieved and written to the <tt>clockstats</tt> file when the first timecode message of a new day is received.</p>
-
<h4>Fudge Factors</h4>
-
<dl>
-<dt><tt>time1 <i>time</i></tt>
-<dd>Specifies the PPS time offset calibration factor, in seconds and fraction, with default 0.0.
-
-<dt><tt>time2 <i>time</i></tt>
-<dd>Specifies the serial time offset calibration factor, in seconds and fraction, with default 0.0.
-
-<dt><tt>stratum <i>number</i></tt>
-<dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
-
-<dt><tt>refid <i>string</i></tt>
-<dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>WWVB</tt>.
-
-<dt><tt>flag1 0 | 1</tt>
-<dd>Disable PPS signal processing if 0 (default); enable PPS signal processing if 1.
-
-<dt><tt>flag2 0 | 1</tt>
-<dd>If PPS signal processing is enabled, capture the pulse on the rising edge if 0 (default); capture on the falling edge if 1.
-
-<dt><tt>flag3 0 | 1</tt>
-<dd>If PPS signal processing is enabled, use the <tt>ntpd</tt> clock discipline if 0 (default); use the kernel discipline if 1.
-
-<dt><tt>flag4 0 | 1</tt>
-<dd>Enable verbose <tt>clockstats</tt> recording if set.
-
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the PPS time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Specifies the serial time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>WWVB</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Disable PPS signal processing if 0 (default); enable PPS signal processing if 1.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>If PPS signal processing is enabled, capture the pulse on the rising edge if 0 (default); capture on the falling edge if 1.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>If PPS signal processing is enabled, use the <tt>ntpd</tt> clock discipline if 0 (default); use the kernel discipline if 1.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Enable verbose <tt>clockstats</tt> recording if set.</dd>
</dl>
-
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
</body>
-</html>
\ No newline at end of file
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>IRIG Audio Decoder</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
- <body>
- <h3>IRIG Audio Decoder</h3>
- <hr>
- <h4>Synopsis</h4>
- Address: 127.127.6.<i>u</i><br>
- Reference ID: <tt>IRIG</tt><br>
- Driver ID: <tt>IRIG_AUDIO</tt><br>
- Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt>
- <h4>Description</h4>
- <p>This driver synchronizes the computer time using the Inter-Range Instrumentation Group (IRIG) standard time distribution signal. This signal is generated by several radio clocks, including those made by Arbiter, Austron, Bancomm, Odetics, Spectracom, Symmetricom and TrueTime, among others, although it is often an add-on option. The signal is connected via an optional attenuator and cable to either the microphone or line-in port of a workstation or PC.</p>
- <p>The driver requires an audio codec or sound card with sampling rate 8 kHz and <font face="symbol">m</font>-law companding to demodulate the data. This is the same standard as used by the telephone industry and is supported by most hardware and operating systems, including Solaris, FreeBSD and Linux, among others. In this implementation, only one audio driver and codec can be supported on a single machine. In order to assure reliable signal capture, the codec frequency error must be less than 250 PPM (.025 percent). If necessary, the <tt>tinker codec</tt> configuration command can be used to bracket the codec frequency to this range.</p>
- <p>For proper operation the IRIG signal source should be configured for analog signal levels, not digital TTL levels. In most radios the IRIG signal is driven ±10 V behind 50 Ohms. In such cases the cable should be terminated at the line-in port with a 50-Ohm resistor to avoid overloading the codec. Where feasible, the IRIG signal source should be operated with signature control so that, if the signal is lost or mutilated, the source produces an unmodulated signal, rather than possibly random digits. The driver automatically rejects the data and declares itself unsynchronized in this case. Some devices, in particular Spectracom radio/satellite clocks, provide additional year and status indication; other devices may not.</p>
- <p>In general and without calibration, the driver is accurate within 500 <font face="symbol">m</font>s relative to the IRIG time. After calibrating relative to the PPS signal from a GPS receiver, the mean offset with a 2.4-GHz P4 running FreeBSD 6.1 is less than 20 <font face="symbol">m</font>s with standard deviation 10 <font face="symbol">m</font>s. Most of this is due to residuals after filtering and averaging the raw codec samples, which have an inherent jitter of 125 <font face="symbol">m</font>s. The processor load due to the driver is 0.6 percent on the P4.</p>
- <p>However, be acutely aware that the accuracy with Solaris 2.8 and beyond has been seriously degraded to the order of several milliseconds. The Sun kernel driver has a sawtooth modulation with amplitude over 5 ms P-P and period 5.5 s. This distortion is especially prevalent with Sun Blade 1000 and possibly other systems.</p>
- <p>The driver performs a number of error checks to protect against overdriven or underdriven input signal levels, incorrect signal format or improper hardware configuration. The specific checks are detailed later in this page. Note that additional checks are done elsewhere in the reference clock interface routines.</p>
- <p>This driver incorporates several features in common with other audio drivers such as described in the <a href="driver7.html">Radio CHU Audio Demodulator/Decoder</a> and the <a href="driver36.html">Radio WWV/H Audio Demodulator/Decoder</a> pages. They include automatic gain control (AGC), selectable audio codec port and signal monitoring capabilities. For a discussion of these common features, as well as a guide to hookup, debugging and monitoring, see the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
- <h4>Technical Overview</h4>
- <p>The IRIG signal format uses an amplitude-modulated carrier with pulse-width modulated data bits. For IRIG-B, the carrier frequency is 1000 Hz and bit rate 100 b/s; for IRIG-E, the carrier frequenchy is 100 Hz and bit rate 10 b/s. While IRIG-B provides the best accuracy, generally within a few tens of microseconds relative to IRIG time, it can also generate a significant processor load with older workstations. Generally, the accuracy with IRIG-E is about ten times worse than IRIG-B, but the processor load is somewhat less. Technical details about the IRIG formats can be found in <a href="http://handle.dtic.mil/100.2/ADA346250">IRIG Standard 200-98</a>.</p>
- <p>The driver processes 8000-Hz <font face="symbol">m</font>-law companded samples using separate signal filters for IRIG-B and IRIG-E, a comb filter, envelope detector and automatic threshold corrector. An infinite impulse response (IIR) 1000-Hz bandpass filter is used for IRIG-B and an IIR 130-Hz lowpass filter for IRIG-E. These are intended for use with noisy signals, such as might be received over a telephone line or radio circuit, or when interfering signals may be present in the audio passband. The driver determines which IRIG format is in use by sampling the amplitude of each filter output and selecting the one with maximum signal.</p>
- <p>Cycle crossings relative to the corrected slice level determine the width of each pulse and its value - zero, one or position identifier (PI). The data encode ten characters (20 BCD digits) which determine the second, minute, hour and day of the year and with some IRIG generators the year and synchronization condition. The comb filter exponentially averages the corresponding samples of successive baud intervals in order to reliably identify the reference carrier cycle.</p>
- <p>A type-II phase-lock loop (PLL) performs additional integration and interpolation to accurately determine the zero crossing of that cycle, which determines the reference timestamp. A pulse-width discriminator demodulates the data pulses, which are then encoded as the BCD digits of the timecode. The timecode and reference timestamp are updated once each second with IRIG-B (ten seconds with IRIG-E) and local clock offset samples saved for later processing. At poll intervals of 64 s, the saved samples are processed by a median filter and used to update the system clock.</p>
- <h4>Monitor Data</h4>
- The timecode format used for debugging and data recording includes data helpful in diagnosing problems with the IRIG signal and codec connections. The driver produces one line for each timecode in the following format:
- <p><tt>00 00 98 23 19:26:52 2782 143 0.694 10 0.3 66.5 3094572411.00027</tt></p>
- <p>If clockstats is enabled, the most recent line is written to the clockstats file every 64 s. If verbose recording is enabled (fudge flag 4) each line is written as generated.</p>
- <p>The first field containes the error flags in hex, where the hex bits are interpreted as below. This is followed by the year of century, day of year and time of day. Note that the time of day is for the previous minute, not the current time. The status indicator and year are not produced by some IRIG devices and appear as zeros. Following these fields are the carrier amplitude (0-3000), codec gain (0-255), modulation index (0-1), time constant (4-10), carrier phase error (0±0.5) and carrier frequency error (PPM). The last field is the on-time timestamp in NTP format.</p>
- <p>The error flags are defined as follows in hex:</p>
- <dl>
- <dt><tt>x01</tt>
- <dd>Low signal. The carrier amplitude is less than 100 units. This is usually the result of no signal or wrong input port.
- <dt><tt>x02</tt>
- <dd>Frequency error. The codec frequency error is greater than 250 PPM. This may be due to wrong signal format or (rarely) defective codec.
- <dt><tt>x04</tt>
- <dd>Modulation error. The IRIG modulation index is less than 0.5. This is usually the result of an overdriven codec, wrong signal format or wrong input port.
- <dt><tt>x08</tt>
- <dd>Frame synch error. The decoder frame does not match the IRIG frame. This is usually the result of an overdriven codec, wrong signal format or noisy IRIG signal. It may also be the result of an IRIG signature check which indicates a failure of the IRIG signal synchronization source.
- <dt><tt>x10</tt>
- <dd>Data bit error. The data bit length is out of tolerance. This is usually the result of an overdriven codec, wrong signal format or noisy IRIG signal.
- <dt><tt>x20</tt>
- <dd>Seconds numbering discrepancy. The decoder second does not match the IRIG second. This is usually the result of an overdriven codec, wrong signal format or noisy IRIG signal.
- <dt><tt>x40</tt>
- <dd>Codec error (overrun). The machine is not fast enough to keep up with the codec.
- <dt><tt>x80</tt>
- <dd>Device status error (Spectracom).
- </dl>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>IRIG</tt>.
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
- <dt><tt>flag2 0 | 1</tt>
- <dd>Specifies the microphone port if set to zero or the line-in port if set to one. It does not seem useful to specify the compact disc player port.
- <dt><tt>flag3 0 | 1</tt>
- <dd>Enables audio monitoring of the input signal. For this purpose, the speaker volume must be set before the driver is started.
- <dt><tt>flag4 0 | 1</tt>
- <dd>Enable verbose <tt>clockstats</tt> recording if set.
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>IRIG Audio Decoder</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>IRIG Audio Decoder</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ lart upsdate:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:24<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+Address: 127.127.6.<i>u</i><br>
+Reference ID: <tt>IRIG</tt><br>
+Driver ID: <tt>IRIG_AUDIO</tt><br>
+Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt>
+<h4>Description</h4>
+<p>This driver synchronizes the computer time using the Inter-Range Instrumentation Group (IRIG) standard time distribution signal. This signal is generated by several radio clocks, including those made by Arbiter, Austron, Bancomm, Odetics, Spectracom, Symmetricom and TrueTime, among others, although it is often an add-on option. The signal is connected via an optional attenuator and cable to either the microphone or line-in port of a workstation or PC.</p>
+<p>The driver requires an audio codec or sound card with sampling rate 8 kHz and <font face="symbol">m</font>-law companding to demodulate the data. This is the same standard as used by the telephone industry and is supported by most hardware and operating systems, including Solaris, FreeBSD and Linux, among others. In this implementation, only one audio driver and codec can be supported on a single machine. In order to assure reliable signal capture, the codec frequency error must be less than 250 PPM (.025 percent). If necessary, the <tt>tinker codec</tt> configuration command can be used to bracket the codec frequency to this range.</p>
+<p>For proper operation the IRIG signal source should be configured for analog signal levels, not digital TTL levels. In most radios the IRIG signal is driven ±10 V behind 50 Ohms. In such cases the cable should be terminated at the line-in port with a 50-Ohm resistor to avoid overloading the codec. Where feasible, the IRIG signal source should be operated with signature control so that, if the signal is lost or mutilated, the source produces an unmodulated signal, rather than possibly random digits. The driver automatically rejects the data and declares itself unsynchronized in this case. Some devices, in particular Spectracom radio/satellite clocks, provide additional year and status indication; other devices may not.</p>
+<p>In general and without calibration, the driver is accurate within 500 <font face="symbol">m</font>s relative to the IRIG time. After calibrating relative to the PPS signal from a GPS receiver, the mean offset with a 2.4-GHz P4 running FreeBSD 6.1 is less than 20 <font face="symbol">m</font>s with standard deviation 10 <font face="symbol">m</font>s. Most of this is due to residuals after filtering and averaging the raw codec samples, which have an inherent jitter of 125 <font face="symbol">m</font>s. The processor load due to the driver is 0.6 percent on the P4.</p>
+<p>However, be acutely aware that the accuracy with Solaris 2.8 and beyond has been seriously degraded to the order of several milliseconds. The Sun kernel driver has a sawtooth modulation with amplitude over 5 ms P-P and period 5.5 s. This distortion is especially prevalent with Sun Blade 1000 and possibly other systems.</p>
+<p>The driver performs a number of error checks to protect against overdriven or underdriven input signal levels, incorrect signal format or improper hardware configuration. The specific checks are detailed later in this page. Note that additional checks are done elsewhere in the reference clock interface routines.</p>
+<p>This driver incorporates several features in common with other audio drivers such as described in the <a href="driver7.html">Radio CHU Audio Demodulator/Decoder</a> and the <a href="driver36.html">Radio WWV/H Audio Demodulator/Decoder</a> pages. They include automatic gain control (AGC), selectable audio codec port and signal monitoring capabilities. For a discussion of these common features, as well as a guide to hookup, debugging and monitoring, see the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
+<h4>Technical Overview</h4>
+<p>The IRIG signal format uses an amplitude-modulated carrier with pulse-width modulated data bits. For IRIG-B, the carrier frequency is 1000 Hz and bit rate 100 b/s; for IRIG-E, the carrier frequenchy is 100 Hz and bit rate 10 b/s. While IRIG-B provides the best accuracy, generally within a few tens of microseconds relative to IRIG time, it can also generate a significant processor load with older workstations. Generally, the accuracy with IRIG-E is about ten times worse than IRIG-B, but the processor load is somewhat less. Technical details about the IRIG formats can be found in <a href="http://handle.dtic.mil/100.2/ADA346250">IRIG Standard 200-98</a>.</p>
+<p>The driver processes 8000-Hz <font face="symbol">m</font>-law companded samples using separate signal filters for IRIG-B and IRIG-E, a comb filter, envelope detector and automatic threshold corrector. An infinite impulse response (IIR) 1000-Hz bandpass filter is used for IRIG-B and an IIR 130-Hz lowpass filter for IRIG-E. These are intended for use with noisy signals, such as might be received over a telephone line or radio circuit, or when interfering signals may be present in the audio passband. The driver determines which IRIG format is in use by sampling the amplitude of each filter output and selecting the one with maximum signal.</p>
+<p>Cycle crossings relative to the corrected slice level determine the width of each pulse and its value - zero, one or position identifier (PI). The data encode ten characters (20 BCD digits) which determine the second, minute, hour and day of the year and with some IRIG generators the year and synchronization condition. The comb filter exponentially averages the corresponding samples of successive baud intervals in order to reliably identify the reference carrier cycle.</p>
+<p>A type-II phase-lock loop (PLL) performs additional integration and interpolation to accurately determine the zero crossing of that cycle, which determines the reference timestamp. A pulse-width discriminator demodulates the data pulses, which are then encoded as the BCD digits of the timecode. The timecode and reference timestamp are updated once each second with IRIG-B (ten seconds with IRIG-E) and local clock offset samples saved for later processing. At poll intervals of 64 s, the saved samples are processed by a median filter and used to update the system clock.</p>
+<h4>Monitor Data</h4>
+The timecode format used for debugging and data recording includes data helpful in diagnosing problems with the IRIG signal and codec connections. The driver produces one line for each timecode in the following format:
+<p><tt>00 00 98 23 19:26:52 2782 143 0.694 10 0.3 66.5 3094572411.00027</tt></p>
+<p>If clockstats is enabled, the most recent line is written to the clockstats file every 64 s. If verbose recording is enabled (fudge flag 4) each line is written as generated.</p>
+<p>The first field containes the error flags in hex, where the hex bits are interpreted as below. This is followed by the year of century, day of year and time of day. Note that the time of day is for the previous minute, not the current time. The status indicator and year are not produced by some IRIG devices and appear as zeros. Following these fields are the carrier amplitude (0-3000), codec gain (0-255), modulation index (0-1), time constant (4-10), carrier phase error (0±0.5) and carrier frequency error (PPM). The last field is the on-time timestamp in NTP format.</p>
+<p>The error flags are defined as follows in hex:</p>
+<dl>
+ <dt><tt>x01</tt></dt>
+ <dd>Low signal. The carrier amplitude is less than 100 units. This is usually the result of no signal or wrong input port.</dd>
+ <dt><tt>x02</tt></dt>
+ <dd>Frequency error. The codec frequency error is greater than 250 PPM. This may be due to wrong signal format or (rarely) defective codec.</dd>
+ <dt><tt>x04</tt></dt>
+ <dd>Modulation error. The IRIG modulation index is less than 0.5. This is usually the result of an overdriven codec, wrong signal format or wrong input port.</dd>
+ <dt><tt>x08</tt></dt>
+ <dd>Frame synch error. The decoder frame does not match the IRIG frame. This is usually the result of an overdriven codec, wrong signal format or noisy IRIG signal. It may also be the result of an IRIG signature check which indicates a failure of the IRIG signal synchronization source.</dd>
+ <dt><tt>x10</tt></dt>
+ <dd>Data bit error. The data bit length is out of tolerance. This is usually the result of an overdriven codec, wrong signal format or noisy IRIG signal.</dd>
+ <dt><tt>x20</tt></dt>
+ <dd>Seconds numbering discrepancy. The decoder second does not match the IRIG second. This is usually the result of an overdriven codec, wrong signal format or noisy IRIG signal.</dd>
+ <dt><tt>x40</tt></dt>
+ <dd>Codec error (overrun). The machine is not fast enough to keep up with the codec.</dd>
+ <dt><tt>x80</tt></dt>
+ ^
+ <dd>Device status error (Spectracom).</dd>
+</dl>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>IRIG</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>Specifies the microphone port if set to zero or the line-in port if set to one. It does not seem useful to specify the compact disc player port.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>Enables audio monitoring of the input signal. For this purpose, the speaker volume must be set before the driver is started.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Enable verbose <tt>clockstats</tt> recording if set.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Radio CHU Audio Demodulator/Decoder</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Radio CHU Audio Demodulator/Decoder</h3>
- <hr>
- <h4>Synopsis</h4>
- Address: 127.127.7.<i>u</i><br>
- Reference ID: <tt>CHU</tt><br>
- Driver ID: <tt>CHU</tt><br>
- Modem Port: <tt>/dev/chu<i>u</i></tt>; 300 baud, 8-bits, no parity<br>
- Autotune Port: <tt>/dev/icom</tt>; 1200/9600 baud, 8-bits, no parity<br>
- Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt>
- <h4>Description</h4>
- <p>This driver synchronizes the computer time using shortwave radio transmissions
- from Canadian time/frequency station <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/shortwave_broadcasts_e.html">CHU</a> in
- Ottawa, Ontario. CHU transmissions are made continuously on 3.330,
- 7.850 and 14.670 MHz in upper sideband, compatible AM mode. An ordinary
- shortwave receiver can be tuned manually to one of these frequencies or, in
- the case of ICOM receivers, the receiver can be tuned automatically as propagation
- conditions change throughout the day and season.</p>
- <p>The driver can be compiled to use either an audio codec or soundcard, or a Bell 103-compatible, 300-b/s modem or modem chip, as described on the <a href="../pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. If compiled for a modem, the driver uses it to receive the radio signal and demodulate the data. If compiled for the audio codec, it requires a sampling rate of 8 kHz and <font face="symbol">m</font>-law companding to demodulate the data. This is the same standard as used by the telephone industry and is supported by most hardware and operating systems, including Solaris, FreeBSD and Linux, among others. The radio is connected via an optional attenuator and cable to either the microphone or line-in port of a workstation or PC. In this implementation, only one audio driver and codec can be supported on a single machine.</p>
- <p>In general and without calibration, the driver is accurate within 1 ms relative to the broadcast time when tracking a station. However, variations up to 0.3 ms can be expected due to diurnal variations in ionospheric layer height and ray geometry. In Newark DE, 625 km from the transmitter, the predicted one-hop propagation delay varies from 2.8 ms in sunlight to 2.6 ms in moonlight. When not tracking the station the accuracy depends on the computer clock oscillator stability, ordinarily better than 0.5 PPM.</p>
- <p>After calibration relative to the PPS signal from a GPS receiver, the mean offset with a 2.4-GHz P4 running FreeBSD 6.1 is generally within 0.2 ms short-term with 0.4 ms jitter. The long-term mean offset varies up to 0.3 ms due to propagation path geometry variations. The processor load due to the driver is 0.4 percent on the P4.</p>
- <p>The driver performs a number of error checks to protect against overdriven or underdriven input signal levels, incorrect signal format or improper hardware configuration. The specific checks are detailed later in this page. Note that additional checks are done elsewhere in the reference clock interface routines.</p>
- <p>This driver incorporates several features in common with other audio drivers such as described in the <a href="driver36.html">Radio WWV/H Audio Demodulator/Decoder</a> and the <a href="driver6.html">IRIG Audio Decoder</a> pages. They include automatic gain control (AGC), selectable audio codec port and signal monitoring capabilities. For a discussion of these common features, as well as a guide to hookup, debugging and monitoring, see the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
- <h4>Technical Overview</h4>
- <p>The driver processes 8-kHz <font face="symbol">m</font>-law companded codec samples using maximum-likelihood techniques which exploit the considerable degree of redundancy available in each broadcast message or burst. As described below, every character is sent twice and, in the case of format A bursts, the burst is sent eight times every minute. The single format B burst is considered correct only if every character matches its repetition in the burst. For the eight format A bursts, a majority decoder requires more than half of the 16 repetitions for each digit decode to the same value. Every character in every burst provides an independent timestamp upon arrival with a potential total of 60 timestamps for each minute.</p>
- <p>The CHU timecode format is described on the <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/chu_e.html">CHU website</a>. A timecode is assembled when all bursts have been received in each minute. The timecode is considered valid and the clock set when at least one valid format B burst has been decoded and the majority decoder declares success. Once the driver has synchronized for the first time, it will appear reachable and selectable to discipline the system clock. It is normal on occasion to miss a minute or two due to signal fades or noise. If eight successive minutes are missed, the driver is considered unreachable and the system clock will free-wheel at the latest determined frequency offset. Since the signals are almost always available during some period of the day and the NTP clock discipline algorithms are designed to work well even with long intervals between updates, it is unlikely that the system clock will drift more than a few milliseconds during periods of signal loss.</p>
- <h4>Baseband Signal Processing</h4>
- <p>The program consists of four major parts: the DSP modem, maximum-likelihood UART, burst assembler and majority decoder. The DSP modem demodulates Bell 103 modem answer-frequency signals; that is, frequency-shift keyed (FSK) tones of 2225 Hz (mark) and 2025 Hz (space). It consists of a 500-Hz bandpass filter centered on 2125 Hz followed by a limiter/discriminator and raised-cosine lowpass filter optimized for the 300-b/s data rate. </p>
- <p>The maximum likelihood UART is implemented using a set of eight 11-stage shift registers, one for each of eight phases of the 300-b/s bit clock. At each phase a new baseband signal from the DSP modem is shifted into the corresponding register and the maximum and minimum over all 11 samples computed. This establishes a span (difference) and slice level (average) over all 11 stages. For each stage, a signal level above the slice is a mark (1) and below that is a space (0). A quality metric is calculated for each register with respect to the slice level and the a-priori signal consisting of a start bit (space), eight arbitrary information bits and two stop bits (mark).</p>
- <p>The shift registers are processed in round-robin order as the phases of each bit arrive. At the end of each bit all eight phases are searched for valid framing bits, sufficient span and best metric. The best candidate found in this way represents the maximum-likelihood character. The process then continues for all ten characters in the burst.</p>
- <p>The burst assembler processes characters either from the maximum-likelihood UART or directly from the serial port as configured. A burst begins when a character is received and is processed after a timeout interval when no characters are received. If the interval between characters is greater than two characters, but less than the timeout interval, the burst is rejected as a runt and a new burst begun. As each character is received, a timestamp is captured and saved for later processing.</p>
- <p>A valid burst consists of ten characters in two replicated five-character blocks, each block representing ten 4-bit BCD digits. The format B blocks sent in second 31 contain the year and other information in ten digits. The eight format A blocks sent in seconds 32-39 contain the timecode in ten digits, the first of which is a framing code (6). The burst assembler must deal with cases where the first character of a format A burst is lost or is noise. This is done using the framing codes to correct the discrepancy, either one character early or one character late.</p>
- <p>The burst distance is incremented by one for each bit in the first block that matches the corresponding bit in the second block and decremented by one otherwise. In a format B burst the second block is bit-inverted relative to the first, so a perfect burst of five 8-bit characters has distance -40. In a format A burst the two blocks are identical, so a perfect burst has distance +40. Format B bursts must be perfect to be acceptable; however, format A bursts, which are further processed by the majority decoder, are acceptable if the distance is at least 28.</p>
- <h4>Majority Decoder</h4>
- <p>Each minute of transmission includes eight format A bursts containing two timecodes for each second from 32 through 39. The majority decoder uses a decoding matrix of ten rows, one for each digit position in the timecode, and 16 columns, one for each 4-bit code combination that might be decoded at that position. In order to use the character timestamps, it is necessary to reliably determine the second number of each burst. In a valid burst, the last digit of the two timecodes in the burst must match and the value must be in the range 2-9 and greater than in the previous burst.</p>
- <p>As each digit of a valid burst is processed, the value at the row corresponding to the digit position in the timecode and column corresponding to the code found at that position is incremented. At the end of the minute, each row of the decoding matrix encodes the number of occurrences of each code found at the corresponding position.</p>
- <p>The maximum over all occurrences at each digit position is the distance for that position and the corresponding code is the maximum-likelihood digit. If the distance is not more than half the total number of occurrences, the decoder assumes a soft error and discards all information collected during the minute. The decoding distance is defined as the sum of the distances over the first nine digits; the tenth digit varies over the seconds and is uncounted.</p>
- <p>The result of the majority decoder is a nine-digit timecode representing the maximum-likelihood candidate for the transmitted timecode in that minute. Note that the second and fraction within the minute are always zero and that the actual reference point to calculate timestamp offsets is backdated to the first second of the minute. At this point the timecode block is reformatted and the year, days, hours and minutes extracted along with other information from the format B burst, including DST state, DUT1 correction and leap warning. The reformatting operation checks the timecode for invalid code combinations that might have been left by the majority decoder and rejects the entire timecode if found.</p>
- <p>If the timecode is valid, it is passed to the reference clock interface along with the backdated timestamps accumulated over the minute. A perfect set of eight bursts could generate as many as 80 timestamps, but the maximum the interface can handle is 60. These are processed using a median filter and trimmed-mean average, so the resulting system clock correction is usually much better than would otherwise be the case with radio noise, UART jitter and occasional burst errors.</p>
- <h4>Autotune</h4>
- <p>The driver includes provisions to automatically tune the radio in response to changing radio propagation conditions throughout the day and night. The radio interface is compatible with the ICOM CI-V standard, which is a bidirectional serial bus operating at TTL levels. The bus can be connected to a standard serial port using a level converter such as the CT-17. Further details are on the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
- <p>If specified, the driver will attempt to open the device <tt>/dev/icom</tt> and, if successful will tune the radio to 3.331 MHz. The 1-kHz offset is useful with a narrowband SSB filter where the passband includes the carrier and modem signals. However, the driver is liberal in what it assumes of the configuration. If the <tt>/dev/icom</tt> link is not present or the open fails or the CI-V bus is inoperative, the driver continues in single-frequency mode.</p>
- <p>As long as no bursts are received, the driver cycles over the three frequencies in turn, one minute for each station. When bursts are received from one or more stations, the driver operates in a five-minute cycle. During the first four minutes it tunes to the station with the highest metric. During the last minute it alternates between the other two stations in turn in order to measure the metric.</p>
- <h4>Debugging Aids</h4>
- <p>The most convenient way to track the program status is using the <tt>ntpq</tt> program and the <tt>clockvar</tt> command. This displays the last determined timecode and related status and error counters, even when the program is not discipline the system clock. If the debugging trace feature (<tt>-d</tt> on the <tt>ntpd</tt> command line) is enabled, the program produces detailed status messages as it operates. If the <tt>fudge flag 4</tt> is set, these messages are written to the <tt>clockstats</tt> file. All messages produced by this driver have the prefix <tt>chu</tt> for convenient filtering with the Unix <tt>grep</tt> command.</p>
- <p>With debugging enabled the driver produces messages in the following formats: A single message beginning with <tt>chuB</tt> is produced for each format B burst received in second 31, while eight messages beginning with <tt>chuA</tt> are produced for each format A burst received in seconds 32 through 39 of the minute. The first four fields are</p>
- <p><tt>stat sig n b</tt></p>
- <p>where <tt>stat</tt> is the status code, <tt>sig</tt> the character span, <tt>n</tt> the number of characters in the burst (9-11) and <tt>b</tt> the burst distance (0-40). Good bursts will have spans of a 800 or more and the other numbers near the top of the range specified. See the source for the interpretation of the remaining data in the burst. Note that each character of the burst is encoded as two digits in nibble-swapped order.</p>
- <p>If the CI-V interface for ICOM radios is active, a debug level greater than 1 will produce a trace of the CI-V command and response messages. Interpretation of these messages requires knowledge of the CI-V protocol, which is beyond the scope of this document.</p>
- <h4>Monitor Data</h4>
- When enabled by the <tt>filegen</tt> facility, every received timecode is written to the <tt>clockstats</tt> file in the following format:<pre>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Radio CHU Audio Demodulator/Decoder</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Radio CHU Audio Demodulator/Decoder</h3>
+<p>Author: David L. Mills (mills@udel.edu)<br>
+ <!-- #BeginDate format:En2m -->03-Sep-2010 20:26<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+Address: 127.127.7.<i>u</i><br>
+Reference ID: <tt>CHU</tt><br>
+Driver ID: <tt>CHU</tt><br>
+Modem Port: <tt>/dev/chu<i>u</i></tt>; 300 baud, 8-bits, no parity<br>
+Autotune Port: <tt>/dev/icom</tt>; 1200/9600 baud, 8-bits, no parity<br>
+Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt>
+<h4>Description</h4>
+<p>This driver synchronizes the computer time using shortwave radio transmissions
+ from Canadian time/frequency station <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/shortwave_broadcasts_e.html">CHU</a> in
+ Ottawa, Ontario. CHU transmissions are made continuously on 3.330,
+ 7.850 and 14.670 MHz in upper sideband, compatible AM mode. An ordinary
+ shortwave receiver can be tuned manually to one of these frequencies or, in
+ the case of ICOM receivers, the receiver can be tuned automatically as propagation
+ conditions change throughout the day and season.</p>
+<p>The driver can be compiled to use either an audio codec or soundcard, or a Bell 103-compatible, 300-b/s modem or modem chip, as described on the <a href="../pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. If compiled for a modem, the driver uses it to receive the radio signal and demodulate the data. If compiled for the audio codec, it requires a sampling rate of 8 kHz and <font face="symbol">m</font>-law companding to demodulate the data. This is the same standard as used by the telephone industry and is supported by most hardware and operating systems, including Solaris, FreeBSD and Linux, among others. The radio is connected via an optional attenuator and cable to either the microphone or line-in port of a workstation or PC. In this implementation, only one audio driver and codec can be supported on a single machine.</p>
+<p>In general and without calibration, the driver is accurate within 1 ms relative to the broadcast time when tracking a station. However, variations up to 0.3 ms can be expected due to diurnal variations in ionospheric layer height and ray geometry. In Newark DE, 625 km from the transmitter, the predicted one-hop propagation delay varies from 2.8 ms in sunlight to 2.6 ms in moonlight. When not tracking the station the accuracy depends on the computer clock oscillator stability, ordinarily better than 0.5 PPM.</p>
+<p>After calibration relative to the PPS signal from a GPS receiver, the mean offset with a 2.4-GHz P4 running FreeBSD 6.1 is generally within 0.2 ms short-term with 0.4 ms jitter. The long-term mean offset varies up to 0.3 ms due to propagation path geometry variations. The processor load due to the driver is 0.4 percent on the P4.</p>
+<p>The driver performs a number of error checks to protect against overdriven or underdriven input signal levels, incorrect signal format or improper hardware configuration. The specific checks are detailed later in this page. Note that additional checks are done elsewhere in the reference clock interface routines.</p>
+<p>This driver incorporates several features in common with other audio drivers such as described in the <a href="driver36.html">Radio WWV/H Audio Demodulator/Decoder</a> and the <a href="driver6.html">IRIG Audio Decoder</a> pages. They include automatic gain control (AGC), selectable audio codec port and signal monitoring capabilities. For a discussion of these common features, as well as a guide to hookup, debugging and monitoring, see the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
+<h4>Technical Overview</h4>
+<p>The driver processes 8-kHz <font face="symbol">m</font>-law companded codec samples using maximum-likelihood techniques which exploit the considerable degree of redundancy available in each broadcast message or burst. As described below, every character is sent twice and, in the case of format A bursts, the burst is sent eight times every minute. The single format B burst is considered correct only if every character matches its repetition in the burst. For the eight format A bursts, a majority decoder requires more than half of the 16 repetitions for each digit decode to the same value. Every character in every burst provides an independent timestamp upon arrival with a potential total of 60 timestamps for each minute.</p>
+<p>The CHU timecode format is described on the <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/chu_e.html">CHU website</a>. A timecode is assembled when all bursts have been received in each minute. The timecode is considered valid and the clock set when at least one valid format B burst has been decoded and the majority decoder declares success. Once the driver has synchronized for the first time, it will appear reachable and selectable to discipline the system clock. It is normal on occasion to miss a minute or two due to signal fades or noise. If eight successive minutes are missed, the driver is considered unreachable and the system clock will free-wheel at the latest determined frequency offset. Since the signals are almost always available during some period of the day and the NTP clock discipline algorithms are designed to work well even with long intervals between updates, it is unlikely that the system clock will drift more than a few milliseconds during periods of signal loss.</p>
+<h4>Baseband Signal Processing</h4>
+<p>The program consists of four major parts: the DSP modem, maximum-likelihood UART, burst assembler and majority decoder. The DSP modem demodulates Bell 103 modem answer-frequency signals; that is, frequency-shift keyed (FSK) tones of 2225 Hz (mark) and 2025 Hz (space). It consists of a 500-Hz bandpass filter centered on 2125 Hz followed by a limiter/discriminator and raised-cosine lowpass filter optimized for the 300-b/s data rate. </p>
+<p>The maximum likelihood UART is implemented using a set of eight 11-stage shift registers, one for each of eight phases of the 300-b/s bit clock. At each phase a new baseband signal from the DSP modem is shifted into the corresponding register and the maximum and minimum over all 11 samples computed. This establishes a span (difference) and slice level (average) over all 11 stages. For each stage, a signal level above the slice is a mark (1) and below that is a space (0). A quality metric is calculated for each register with respect to the slice level and the a-priori signal consisting of a start bit (space), eight arbitrary information bits and two stop bits (mark).</p>
+<p>The shift registers are processed in round-robin order as the phases of each bit arrive. At the end of each bit all eight phases are searched for valid framing bits, sufficient span and best metric. The best candidate found in this way represents the maximum-likelihood character. The process then continues for all ten characters in the burst.</p>
+<p>The burst assembler processes characters either from the maximum-likelihood UART or directly from the serial port as configured. A burst begins when a character is received and is processed after a timeout interval when no characters are received. If the interval between characters is greater than two characters, but less than the timeout interval, the burst is rejected as a runt and a new burst begun. As each character is received, a timestamp is captured and saved for later processing.</p>
+<p>A valid burst consists of ten characters in two replicated five-character blocks, each block representing ten 4-bit BCD digits. The format B blocks sent in second 31 contain the year and other information in ten digits. The eight format A blocks sent in seconds 32-39 contain the timecode in ten digits, the first of which is a framing code (6). The burst assembler must deal with cases where the first character of a format A burst is lost or is noise. This is done using the framing codes to correct the discrepancy, either one character early or one character late.</p>
+<p>The burst distance is incremented by one for each bit in the first block that matches the corresponding bit in the second block and decremented by one otherwise. In a format B burst the second block is bit-inverted relative to the first, so a perfect burst of five 8-bit characters has distance -40. In a format A burst the two blocks are identical, so a perfect burst has distance +40. Format B bursts must be perfect to be acceptable; however, format A bursts, which are further processed by the majority decoder, are acceptable if the distance is at least 28.</p>
+<h4>Majority Decoder</h4>
+<p>Each minute of transmission includes eight format A bursts containing two timecodes for each second from 32 through 39. The majority decoder uses a decoding matrix of ten rows, one for each digit position in the timecode, and 16 columns, one for each 4-bit code combination that might be decoded at that position. In order to use the character timestamps, it is necessary to reliably determine the second number of each burst. In a valid burst, the last digit of the two timecodes in the burst must match and the value must be in the range 2-9 and greater than in the previous burst.</p>
+<p>As each digit of a valid burst is processed, the value at the row corresponding to the digit position in the timecode and column corresponding to the code found at that position is incremented. At the end of the minute, each row of the decoding matrix encodes the number of occurrences of each code found at the corresponding position.</p>
+<p>The maximum over all occurrences at each digit position is the distance for that position and the corresponding code is the maximum-likelihood digit. If the distance is not more than half the total number of occurrences, the decoder assumes a soft error and discards all information collected during the minute. The decoding distance is defined as the sum of the distances over the first nine digits; the tenth digit varies over the seconds and is uncounted.</p>
+<p>The result of the majority decoder is a nine-digit timecode representing the maximum-likelihood candidate for the transmitted timecode in that minute. Note that the second and fraction within the minute are always zero and that the actual reference point to calculate timestamp offsets is backdated to the first second of the minute. At this point the timecode block is reformatted and the year, days, hours and minutes extracted along with other information from the format B burst, including DST state, DUT1 correction and leap warning. The reformatting operation checks the timecode for invalid code combinations that might have been left by the majority decoder and rejects the entire timecode if found.</p>
+<p>If the timecode is valid, it is passed to the reference clock interface along with the backdated timestamps accumulated over the minute. A perfect set of eight bursts could generate as many as 80 timestamps, but the maximum the interface can handle is 60. These are processed using a median filter and trimmed-mean average, so the resulting system clock correction is usually much better than would otherwise be the case with radio noise, UART jitter and occasional burst errors.</p>
+<h4>Autotune</h4>
+<p>The driver includes provisions to automatically tune the radio in response to changing radio propagation conditions throughout the day and night. The radio interface is compatible with the ICOM CI-V standard, which is a bidirectional serial bus operating at TTL levels. The bus can be connected to a standard serial port using a level converter such as the CT-17. Further details are on the <a href="../audio.html">Reference Clock Audio Drivers</a> page.</p>
+<p>If specified, the driver will attempt to open the device <tt>/dev/icom</tt> and, if successful will tune the radio to 3.331 MHz. The 1-kHz offset is useful with a narrowband SSB filter where the passband includes the carrier and modem signals. However, the driver is liberal in what it assumes of the configuration. If the <tt>/dev/icom</tt> link is not present or the open fails or the CI-V bus is inoperative, the driver continues in single-frequency mode.</p>
+<p>As long as no bursts are received, the driver cycles over the three frequencies in turn, one minute for each station. When bursts are received from one or more stations, the driver operates in a five-minute cycle. During the first four minutes it tunes to the station with the highest metric. During the last minute it alternates between the other two stations in turn in order to measure the metric.</p>
+<h4>Debugging Aids</h4>
+<p>The most convenient way to track the program status is using the <tt>ntpq</tt> program and the <tt>clockvar</tt> command. This displays the last determined timecode and related status and error counters, even when the program is not discipline the system clock. If the debugging trace feature (<tt>-d</tt> on the <tt>ntpd</tt> command line) is enabled, the program produces detailed status messages as it operates. If the <tt>fudge flag 4</tt> is set, these messages are written to the <tt>clockstats</tt> file. All messages produced by this driver have the prefix <tt>chu</tt> for convenient filtering with the Unix <tt>grep</tt> command.</p>
+<p>With debugging enabled the driver produces messages in the following formats: A single message beginning with <tt>chuB</tt> is produced for each format B burst received in second 31, while eight messages beginning with <tt>chuA</tt> are produced for each format A burst received in seconds 32 through 39 of the minute. The first four fields are</p>
+<p><tt>stat sig n b</tt></p>
+<p>where <tt>stat</tt> is the status code, <tt>sig</tt> the character span, <tt>n</tt> the number of characters in the burst (9-11) and <tt>b</tt> the burst distance (0-40). Good bursts will have spans of a 800 or more and the other numbers near the top of the range specified. See the source for the interpretation of the remaining data in the burst. Note that each character of the burst is encoded as two digits in nibble-swapped order.</p>
+<p>If the CI-V interface for ICOM radios is active, a debug level greater than 1 will produce a trace of the CI-V command and response messages. Interpretation of these messages requires knowledge of the CI-V protocol, which is beyond the scope of this document.</p>
+<h4>Monitor Data</h4>
+When enabled by the <tt>filegen</tt> facility, every received timecode is written to the <tt>clockstats</tt> file in the following format:
+<pre>
sq yyyy ddd hh:mm:ss lw dst du lset agc rfrq bcnt dist tsmp
s sync indicator
dist decoder distance
tsmp timestamps captured
</pre>
- The fields beginning with <tt>year</tt> and extending through <tt>dut</tt> are decoded from the received data and are in fixed-length format. The <tt>agc</tt> and <tt>lset</tt> fields, as well as the following driver-dependent fields, are in variable-length format.
- <dl>
- <dt><tt>s</tt>
- <dd>The sync indicator is initially <tt>?</tt> before the clock is set, but turns to space when the clock has been correctly set.
- <dt><tt>q</tt>
- <dd>The quality character is a four-bit hexadecimal code showing which alarms have been raised during the most recent minute. Each bit is associated with a specific alarm condition according to the following:
- <dl>
- <dt><tt>8</tt>
- <dd>Timestamp alarm. Fewer than 20 timestamps have been determined.
- <dt><tt>4</tt>
- <dd>Decoder alarm. A majority of repetitions for at least one digit of the timecode fails to agree.
- <dt><tt>2</tt>
- <dd>Format alarm. One or more bursts contained invalid data or was improperly formatted.<dt><tt>1</tt>
- <dd>Frame alarm. One or more bursts was improperly framed or contained too many repetition errors.</dl>
- <p>The timestamp and decoder alarms are fatal; the data accumulated during the minute are not used to set the clock. The format and fram alarm are nonfatal; only the data in the burst are discarded.</p>
-
-
-
- <dt><tt>yyyy ddd hh:mm:ss</tt>
- <dd>The timecode format itself is self explanatory. Note that the Gregorian year is decoded directly from the transmitted timecode.
-
- <dt><tt>lw</tt>
- <dd>The leap second warning is normally space, but changes to <tt>L</tt> if a leap second is to occur at the end of the month.<dt><tt>dst</tt>
- <dd>The DST code for Canada encodes the state for all provinces. It is encoded as two hex characters.
- <dt><tt>dut</tt>
- <dd>The DUT sign and magnitude shows the current UT1 offset relative to the displayed UTC time, in deciseconds. It is encoded as one digit preceeded by sign.
- <dt><tt>lset</tt>
- <dd>Before the clock is set, this is the number of minutes since the program was started; after the clock is set, this is the number of minutes since the time was last verified relative to the broadcast signal.<dt><tt>agc</tt>
- <dd>The audio gain shows the current codec gain setting in the range 0 to 255. Ordinarily, the receiver audio gain control should be set for a value midway in this range.
- <dt><tt>ident</tt>
- <dd>The CHU identifier <tt>CHU </tt>followed by the current radio frequency
- code, if the CI-V interface is active, or <tt>CHU</tt> if not. The radio
- frequncy is encoded as 0 for 3.330 MHz, 1 for 7.850 MHz and 2
- for 14.670 MHz.<dt><tt>dist</tt>
- <dd>The decoding distance determined during the most recent minute bursts were received. The values range from 0 to 160, with the higher values indicating better signals. The decoding algorithms require the distance at least 50; otherwise all data in the minute are discarded.<dt><tt>tsmp</tt>
- <dd>The number of timestamps determined during the most recent minute bursts were received. The values range from 0 to 60, with the higher values indicating better signals. The decoding algoriths require at least 20 timestamps in the minute; otherwise all data in the minute are discarded.
- </dl>
- <h4>Fudge Factors</h4>
- <dl>
- <dt><tt>time1 <i>time</i></tt>
- <dd>Specifies the propagation delay for CHU (45:18N 75:45N), in seconds and fraction, with default 0.0.
-
- <dt><tt>time2 <i>time</i></tt>
- <dd>Not used by this driver.
-
- <dt><tt>stratum <i>number</i></tt>
- <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.
-
- <dt><tt>refid <i>string</i></tt>
- <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>CHU</tt>.
-
- <dt><tt>flag1 0 | 1</tt>
- <dd>Not used by this driver.
-
- <dt><tt>flag2 0 | 1</tt>
- <dd>When the audio driver is compiled, this flag selects the audio input port, where 0 is the mike port (default) and 1 is the line-in port. It does not seem useful to select the compact disc player port.
-
- <dt><tt>flag3 0 | 1</tt>
- <dd>When the audio driver is compiled, this flag enables audio monitoring of the input signal. For this purpose, the speaker volume must be set before the driver is started.
-
- <dt><tt>flag4 0 | 1</tt>
- <dd>Enable verbose <tt>clockstats</tt> recording if set.
-
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+The fields beginning with <tt>year</tt> and extending through <tt>dut</tt> are decoded from the received data and are in fixed-length format. The <tt>agc</tt> and <tt>lset</tt> fields, as well as the following driver-dependent fields, are in variable-length format.
+<dl>
+ <dt><tt>s</tt></dt>
+ <dd>The sync indicator is initially <tt>?</tt> before the clock is set, but turns to space when the clock has been correctly set.</dd>
+ <dt><tt>q</tt></dt>
+ <dd>The quality character is a four-bit hexadecimal code showing which alarms have been raised during the most recent minute. Each bit is associated with a specific alarm condition according to the following:
+ <dl>
+ <dt><tt>8</tt></dt>
+ <dd>Timestamp alarm. Fewer than 20 timestamps have been determined.</dd>
+ <dt><tt>4</tt></dt>
+ <dd>Decoder alarm. A majority of repetitions for at least one digit of the timecode fails to agree.</dd>
+ <dt><tt>2</tt></dt>
+ <dd>Format alarm. One or more bursts contained invalid data or was improperly formatted.</dd>
+ <dt><tt>1</tt></dt>
+ <dd>Frame alarm. One or more bursts was improperly framed or contained too many repetition errors.</dd>
+ </dl>
+ The timestamp and decoder alarms are fatal; the data accumulated during the minute are not used to set the clock. The format and fram alarm are nonfatal; only the data in the burst are discarded.</dd>
+ <dt><tt>yyyy ddd hh:mm:ss</tt></dt>
+ <dd>The timecode format itself is self explanatory. Note that the Gregorian year is decoded directly from the transmitted timecode.</dd>
+ <dt><tt>lw</tt></dt>
+ <dd>The leap second warning is normally space, but changes to <tt>L</tt> if a leap second is to occur at the end of the month.</dd>
+ <dt><tt>dst</tt></dt>
+ <dd>The DST code for Canada encodes the state for all provinces. It is encoded as two hex characters.</dd>
+ <dt><tt>dut</tt></dt>
+ <dd>The DUT sign and magnitude shows the current UT1 offset relative to the displayed UTC time, in deciseconds. It is encoded as one digit preceeded by sign.</dd>
+ <dt><tt>lset</tt></dt>
+ <dd>Before the clock is set, this is the number of minutes since the program was started; after the clock is set, this is the number of minutes since the time was last verified relative to the broadcast signal.</dd>
+ <dt><tt>agc</tt></dt>
+ <dd>The audio gain shows the current codec gain setting in the range 0 to 255. Ordinarily, the receiver audio gain control should be set for a value midway in this range.</dd>
+ <dt><tt>ident</tt></dt>
+ <dd>The CHU identifier <tt>CHU </tt>followed by the current radio frequency
+ code, if the CI-V interface is active, or <tt>CHU</tt> if not. The radio
+ frequncy is encoded as 0 for 3.330 MHz, 1 for 7.850 MHz and 2
+ for 14.670 MHz.</dd>
+ <dt><tt>dist</tt></dt>
+ <dd>The decoding distance determined during the most recent minute bursts were received. The values range from 0 to 160, with the higher values indicating better signals. The decoding algorithms require the distance at least 50; otherwise all data in the minute are discarded.</dd>
+ <dt><tt>tsmp</tt></dt>
+ <dd>The number of timestamps determined during the most recent minute bursts were received. The values range from 0 to 60, with the higher values indicating better signals. The decoding algoriths require at least 20 timestamps in the minute; otherwise all data in the minute are discarded.</dd>
+</dl>
+<h4>Fudge Factors</h4>
+<dl>
+ <dt><tt>time1 <i>time</i></tt></dt>
+ <dd>Specifies the propagation delay for CHU (45:18N 75:45N), in seconds and fraction, with default 0.0.</dd>
+ <dt><tt>time2 <i>time</i></tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>stratum <i>number</i></tt></dt>
+ <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd>
+ <dt><tt>refid <i>string</i></tt></dt>
+ <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <tt>CHU</tt>.</dd>
+ <dt><tt>flag1 0 | 1</tt></dt>
+ <dd>Not used by this driver.</dd>
+ <dt><tt>flag2 0 | 1</tt></dt>
+ <dd>When the audio driver is compiled, this flag selects the audio input port, where 0 is the mike port (default) and 1 is the line-in port. It does not seem useful to select the compact disc player port.</dd>
+ <dt><tt>flag3 0 | 1</tt></dt>
+ <dd>When the audio driver is compiled, this flag enables audio monitoring of the input signal. For this purpose, the speaker volume must be set before the driver is started.</dd>
+ <dt><tt>flag4 0 | 1</tt></dt>
+ <dd>Enable verbose <tt>clockstats</tt> recording if set.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>External Clock Discipline and the Local Clock Driver</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>External Clock Discipline and the Local Clock Driver</h3>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:38</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p>
- <hr>
- <p>The NTPv4 implementation includes provisions for an external clock, where
- the system clock is implemented by some external hardware device.
- One implementation might take the form of a bus peripheral with a high resolution
- counter disciplined by a GPS receiver, for example. Another implementation
- might involve another synchronization protocol, such as the Digital Time Synchronization
- Service (DTSS), where the system time is disciplined to this protocol and
- NTP clients of the server obtain synchronization indirectly via the server.
- A third implementation might be a completely separate clock discipline algorithm
- and synchronization protocol, such as the <tt>Lockclock</tt> algorithm used
- with NIST Automated Computer Time Service (ACTS) modem synchronized time.</p>
- <p>When external clocks are used in conjunction with NTP service, some way needs to be provided for the external clock driver and NTP daemon <tt>ntpd</tt> to communicate and determine which discipline is in control. This is necessary in order to provide backup, for instance if the external clock or protocol were to fail and synchronization service fall back to other means, such as a local reference clock or another NTP server. In addition, when the external clock and driver are in control, some means needs to be provided for the clock driver to pass on status information and error statistics to the NTP daemon.</p>
- <p>Control and monitoring functions for the external clock and driver are implemented using the <a href="drivers/driver1.html">Local Clock (type 1) driver</a> and the <tt>ntp_adjtime()</tt> system call. This system call is implemented by special kernel provisions included in the kernel of several operating systems, including Solaris, Tru64, FreeBSD and Linux, and possibly others. When the external clock is disabled or not implemented, the system call is used to pass time and frequency information, as well as error statistics, to the kernel. Besides disciplining the system time, the same interface can be used by other applications to determine the operating parameters of the discipline.</p>
- <p>When the external clock is enabled, <tt>ntpd</tt> does not discipline the system clock, nor does it maintain the error statistics. In this case, the external clock and driver do this using mechanisms unknown to <tt>ntpd</tt>; however, in this case the kernel state variables are retrieved at 64-s intervals by the Local Clock driver and used by the clock selection and mitigation algorithms to determine the system variables presented to other NTP clients and peers. In this way, downstream clients and servers in the NTP subnet can make an intelligent choice when more than one server is available.</p>
- <p>In order to implement a reliable mitigation between ordinary NTP sources and the external clock source, a protocol is necessary between the local clock driver and the external clock driver. This is implemented using Boolean variables and certain bits in the kernel clock status word. The Boolean variables include the following:</p>
- <p><tt>ntp_enable</tt>. set/reset by the <tt>enable</tt> command. enables ntpd
- clock discipline</p>
- <p><tt>ntp_contro</tt>l. set during initial configuration if kernel support is available</p>
- <p><tt>kern_enable</tt> Set/reset by the <tt>enable</tt> command</p>
- <p>If the <tt>kern_enable</tt> switch is set, the daemon computes the offset,
- frequency, maximum error, estimated error, time constant and status bits,
- then provides them to the kernel via <tt>ntp_adjtime()</tt>. If this switch
- is not set, these values are not passed to the kernel; however, the daemon
- retrieves their present values and uses them in place of the values computed
- by the daemon.</p>
- <p>The <tt>pps_update</tt> bit set in the protocol routine if the prefer peer has survived and has offset less than 128 ms; otherwise set to zero.</p>
- <p>The <tt>PPS control</tt> Updated to the current time by kernel support if
- the PPS signal is enabled and working correctly. Set to zero in the adjust
- routine if the interval since the last update exceeds 120 s.</p>
- <p>The <tt>ntp_enable</tt> and <tt>kern_enable</tt> are set by the configuration module. Normally, both switches default on, so the daemon can control the time and the kernel discipline can be used, if available. The <tt>pps_update</tt> switch is set by the protocol module when it believes the PPS provider source is legitimate and operating within nominals. The <tt>ntp_control</tt> switch is set during configuration by interrogating the kernel. If both the <tt>kern_enable</tt> and <tt>ntp_control</tt> switches are set, the daemon disciplines the clock via the kernel and the internal daemon discipline is disabled.</p>
- <p>The external clock driver controls the system time and clock selection in the following way. Normally, the driver adjusts the kernel time using the <tt>ntp_adjtime()</tt> system call in the same way as the daemon. In the case where the kernel discipline is to be used intact, the clock offset is provided in this call and the loop operates as specified. In the case where the driver steers only the frequency, the offset is specified as zero.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>External Clock Discipline and the Local Clock Driver</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>External Clock Discipline and the Local Clock Driver</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 21:49<!-- #EndDate -->
+ UTC</p>
+<hr>
+<p>The NTPv4 implementation includes provisions for an external clock, where
+ the system clock is implemented by some external hardware device.
+ One implementation might take the form of a bus peripheral with a high resolution
+ counter disciplined by a GPS receiver, for example. Another implementation
+ might involve another synchronization protocol, such as the Digital Time Synchronization
+ Service (DTSS), where the system time is disciplined to this protocol and
+ NTP clients of the server obtain synchronization indirectly via the server.
+ A third implementation might be a completely separate clock discipline algorithm
+ and synchronization protocol, such as the <tt>Lockclock</tt> algorithm used
+ with NIST Automated Computer Time Service (ACTS) modem synchronized time.</p>
+<p>When external clocks are used in conjunction with NTP service, some way needs to be provided for the external clock driver and NTP daemon <tt>ntpd</tt> to communicate and determine which discipline is in control. This is necessary in order to provide backup, for instance if the external clock or protocol were to fail and synchronization service fall back to other means, such as a local reference clock or another NTP server. In addition, when the external clock and driver are in control, some means needs to be provided for the clock driver to pass on status information and error statistics to the NTP daemon.</p>
+<p>Control and monitoring functions for the external clock and driver are implemented using the <a href="drivers/driver1.html">Local Clock (type 1) driver</a> and the <tt>ntp_adjtime()</tt> system call. This system call is implemented by special kernel provisions included in the kernel of several operating systems, including Solaris, Tru64, FreeBSD and Linux, and possibly others. When the external clock is disabled or not implemented, the system call is used to pass time and frequency information, as well as error statistics, to the kernel. Besides disciplining the system time, the same interface can be used by other applications to determine the operating parameters of the discipline.</p>
+<p>When the external clock is enabled, <tt>ntpd</tt> does not discipline the system clock, nor does it maintain the error statistics. In this case, the external clock and driver do this using mechanisms unknown to <tt>ntpd</tt>; however, in this case the kernel state variables are retrieved at 64-s intervals by the Local Clock driver and used by the clock selection and mitigation algorithms to determine the system variables presented to other NTP clients and peers. In this way, downstream clients and servers in the NTP subnet can make an intelligent choice when more than one server is available.</p>
+<p>In order to implement a reliable mitigation between ordinary NTP sources and the external clock source, a protocol is necessary between the local clock driver and the external clock driver. This is implemented using Boolean variables and certain bits in the kernel clock status word. The Boolean variables include the following:</p>
+<p><tt>ntp_enable</tt>. set/reset by the <tt>enable</tt> command. enables ntpd
+ clock discipline</p>
+<p><tt>ntp_contro</tt>l. set during initial configuration if kernel support is available</p>
+<p><tt>kern_enable</tt> Set/reset by the <tt>enable</tt> command</p>
+<p>If the <tt>kern_enable</tt> switch is set, the daemon computes the offset,
+ frequency, maximum error, estimated error, time constant and status bits,
+ then provides them to the kernel via <tt>ntp_adjtime()</tt>. If this switch
+ is not set, these values are not passed to the kernel; however, the daemon
+ retrieves their present values and uses them in place of the values computed
+ by the daemon.</p>
+<p>The <tt>pps_update</tt> bit set in the protocol routine if the prefer peer has survived and has offset less than 128 ms; otherwise set to zero.</p>
+<p>The <tt>PPS control</tt> Updated to the current time by kernel support if
+ the PPS signal is enabled and working correctly. Set to zero in the adjust
+ routine if the interval since the last update exceeds 120 s.</p>
+<p>The <tt>ntp_enable</tt> and <tt>kern_enable</tt> are set by the configuration module. Normally, both switches default on, so the daemon can control the time and the kernel discipline can be used, if available. The <tt>pps_update</tt> switch is set by the protocol module when it believes the PPS provider source is legitimate and operating within nominals. The <tt>ntp_control</tt> switch is set during configuration by interrogating the kernel. If both the <tt>kern_enable</tt> and <tt>ntp_control</tt> switches are set, the daemon disciplines the clock via the kernel and the internal daemon discipline is disabled.</p>
+<p>The external clock driver controls the system time and clock selection in the following way. Normally, the driver adjusts the kernel time using the <tt>ntp_adjtime()</tt> system call in the same way as the daemon. In the case where the kernel discipline is to be used intact, the clock offset is provided in this call and the loop operates as specified. In the case where the driver steers only the frequency, the offset is specified as zero.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
+++ /dev/null
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
-<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <title>Gadget Box PPS Level Converter and CHU Modem</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Gadget Box PPS Level Converter and CHU Modem</h3>
- <img src="pic/gadget.jpg" alt="gif" align="left">A Gadget Box built by Chuck Hanavin
- <br clear="left">
- <h4>Related Links</h4>
- <p>
- <script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
- <br clear="left">
- </p>
- <h4>table of Contents</h4>
- <ul>
- <li class="inline"><a href="#intro">Introduction</a></li>
- <li class="inline"><a href="#ckt">Circuit Description</a></li>
- <li class="inline"><a href="#file">Files</a></li>
- </ul>
- <hr>
- <h4 id="intro">Introduction</h4>
- <p>Many radio clocks used as a primary reference source for NTP servers produce
- a pulse-per-second (PPS) signal that can be used to improve accuracy to a
- high degree. However, the signals produced are usually incompatible with the
- modem interface signals on the serial ports used to connect the signal to
- the host. The gadget box consists of a handful of electronic components assembled
- in a small aluminum box. It includes level converters and a optional radio
- modem designed to decode the radio timecode signals transmitted by the Canadian
- time and frequency station CHU. A complete set of schematics, PCB artwork,
- drill templates can be obtained via the web from ftp.udel.edu as <a href="ftp://ftp.udel.edu/pub/ntp/hardware/gadget.tar.Z">gadget.tar.Z</a>.</p>
- <p>The gadget box is assembled in a 5"x3"x2" aluminum minibox containing the level converter and modem circuitry. It includes two subcircuits. One of these converts a TTL positive edge into a fixed-width pulse at EIA levels and is for use with a timecode receiver or oscillator including a TTL PPS output. The other converts the timecode modulation broadcast by Canadian time/frequency standard station CHU into a 300-bps serial character stream at EIA levels and is for use with the <a href="drivers/driver7.html">Radio CHU Audio Demodulator/Decoder</a> driver.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=windows-1252">
- <title>Hints and Kinks</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Hints and Kinks</h3>
- <img src="pic/alice35.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>Mother in law has all the answers.</p>
- <p>Last update: <csobj format="ShortTime" h="24" locale="00000409" region="0" t="DateTime" w="50">20:27</csobj> UTC <csobj format="LongDate" h="24" locale="00000409" region="0" t="DateTime" w="257">Monday, December 02, 2002</csobj></p>
- <br clear="left">
- <hr>
- <p>This is an index for a set of troubleshooting notes contained in individual text files in the <tt>./hints</tt> directory. They were supplied by various volunteers in the form of mail messages, patches or just plain word of mouth. Each note applies to a specific computer and operating system and gives information found useful in setting up the NTP distribution or site configuration. The notes are very informal and subject to errors; no attempt has been made to verify the accuracy of the information contained in them.</p>
- <p>Additions or corrections to this list or the information contained in the notes is solicited. The most useful submissions include the name of the computer manufacturer (and model numbers where appropriate), operating system (specific version(s) where appropriate), problem description, problem solution and submitter's name and electric address. If the submitter is willing to continue debate on the problem, please so advise. See the <a href="hints/">directory listing</a>.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=windows-1252">
+<title>Hints and Kinks</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Hints and Kinks</h3>
+<img src="pic/alice35.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>Mother in law has all the answers.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 21:56<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<hr>
+<p>This is an index for a set of troubleshooting notes contained in individual text files in the <tt>./hints</tt> directory. They were supplied by various volunteers in the form of mail messages, patches or just plain word of mouth. Each note applies to a specific computer and operating system and gives information found useful in setting up the NTP distribution or site configuration. The notes are very informal and subject to errors; no attempt has been made to verify the accuracy of the information contained in them.</p>
+<p>Additions or corrections to this list or the information contained in the notes is solicited. The most useful submissions include the name of the computer manufacturer (and model numbers where appropriate), operating system (specific version(s) where appropriate), problem description, problem solution and submitter's name and electric address. If the submitter is willing to continue debate on the problem, please so advise. See the <a href="hints/">directory listing</a>.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>How to Write a Reference Clock Driver</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>How to Write a Reference Clock Driver</h3>
- <img src="pic/pogo4.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>You need a little magic.</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->11-Jul-2009 20:44<!-- #EndDate -->
- </p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>How to Write a Reference Clock Driver</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>How to Write a Reference Clock Driver</h3>
+<img src="pic/pogo4.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>You need a little magic.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 1:37<!-- #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="#desc">Description</a></li>
- <li class="inline"><a href="#file">Files Which Need to be Changed</a></li>
- <li class="inline"><a href="#intf">Interface Routine Overview</a></li>
- <li class="inline"><a href="#pps">Pulse-per-Second Interface</a></li>
- </ul>
- <hr>
- <h4 id="desc">Description</h4>
- <p>NTP reference clock support maintains the fiction that the clock is actually an ordinary server in the NTP tradition, but operating at a synthetic stratum of zero. The entire suite of algorithms filter the received data and select the best sources to correct the system clock. No packets are exchanged with a reference clock; however, the transmit, receive and packet procedures are replaced with code to simulate them.</p>
- <p>The driver assumes three timescales: standard time maintained by a distant laboratory such as USNO or NIST, reference time maintained by the external radio and the system time maintained by NTP. The radio synchronizes reference time via radio, satellite or modem. As the transmission means may not always be reliable, most radios continue to provide clock updates for some time after signal loss using an internal reference oscillator. In such cases the radio may or may not reveal the time since last synchronized or the estimated time error.</p>
- <p>All three timescales run only in Coordinated Universal Time (UTC) and are not adjusted for local timezone or standard/daylight time. The local timezone, standard/daylight indicator and year, if provided, are ignored. However, it is important to determine whether a leap second is to be inserted in the UTC timescale in the near future so NTP can insert it in the system timescale at the appropriate epoch.</p>
- <p>The interface routines in the <tt>ntp_refclock.c</tt> source file call the following driver routines via a transfer vector:</p>
- <dl>
- <dt><tt>startup</tt></dt>
- <dd>The association has just been mobilized. The driver may allocate a private structure and open the device(s) required.</dd>
-
- <dt><tt>shutdown</tt></dt>
- <dd>The association is about to be demobilized. The driver should close all device(s) and free private structures.</dd>
- <dt><tt>receive</tt></dt>
- <dd>A timecode string is ready for retrieval using the <tt>refclock_gtlin()</tt> or <tt>refclock_gtraw()</tt> routines and provide clock updates.</dd>
- <dt><tt>poll</tt></dt>
- <dd>Called at poll timeout, by default 64 s. Ordinarily, the driver will send a poll sequence to the radio as required.</dd>
- <dt><tt>timer</tt></dt>
- <dd>Called once per second. This can be used for housekeeping functions. In the case with pulse-per-second (PPS) signals, this can be used to process the signals and provide clock updates.</dd>
- </dl>
- <p>The receive routine retrieves a timecode string via serial or parallel port, PPS signal or other means. It decodes the timecode in days, hours, minutes, seconds and nanoseconds and checks for errors. It provides these data along with the on-time timestamp to the <tt>refclock_process</tt> routine, which saves the computed offset in a 60-sample circular buffer. On occasion, either by timeout, sample count or call to the poll routine, the driver calls <tt>refclock_receive</tt> to process the circular buffer samples and update the system clock.</p>
- <p>The best way to understand how the clock drivers work is to study one of the drivers already implemented, such as <tt>refclock_wwvb.c</tt>. The main interface is the <tt>refclockproc</tt> structure, which contains for most drivers the decoded timecode, on-time timestamp, reference timestamp, exception reports and statistics tallies, etc. The support routines are passed a pointer to the <tt>peer</tt> structure, which contains a pointer to the <tt>refclockproc</tt> structure, which in turn contains a pointer to the unit structure, if used. For legacy purposes, a table <tt>typeunit[type][unit]</tt> contains the peer structure pointer for each configured clock type and unit. This structure should not be used for new implementations.</p>
- <p>Radio and modem reference clocks by convention have addresses of the form <tt>127.127.<i>t</i>.<i>u</i></tt>, where <i>t</i> is the clock type and <i>u</i> in the range 0-3 is used to distinguish multiple instances of clocks of the same type. Most clocks require a serial or parallel port or special bus peripheral. The particular device is normally specified by adding a soft link <tt>/dev/device<i>u</i></tt> to the particular hardware device.</p>
- <p>By convention, reference clock drivers are named in the form <tt>refclock_<i>xxxx</i>.c</tt>, where <tt><i>xxxx</i></tt> is a unique string. Each driver is assigned a unique type number, long-form driver name, short-form driver name and device name. The existing assignments are in the <a href="refclock.html">Reference Clock Drivers</a> page and its dependencies. All drivers supported by the particular hardware and operating system are automatically detected in the autoconfigure phase and conditionally compiled.</p>
- <h4>Conventions, Fudge Factors and Flags</h4>
- <p>Most drivers support manual or automatic calibration for systematic offset bias using values encoded in the <tt>fudge</tt> configuration command. By convention, the <tt>time1</tt> value defines the calibration offset in seconds. For those drivers that support statistics collection using the <tt>filegen</tt> utility and the <tt>clockstats</tt> file, the <tt>flag4</tt> switch enables the utility.</p>
- <p>If the calibration feature has been enabled, the <tt>flag1</tt> switch is set and the PPS signal is actively disciplining the system time, the <tt>time1</tt> value is automatically adjusted to maintain a residual offset of zero. Once the its value has stabilized, the value can be inserted in the configuration file and the calibration feature disabled.</p>
- <h4 id="file">Files Which Need to be Changed</h4>
- <p>When a new reference clock driver is installed, the following files need to be edited. Note that changes are also necessary to properly integrate the driver in the configuration and makefile scripts, but these are decidedly beyond the scope of this page.</p>
- <dl>
- <dt><tt>./include/ntp.h</tt></dt>
- <dd>The reference clock type defines are used in many places. Each driver is assigned a unique type number. Unused numbers are clearly marked in the list. A unique <tt>REFCLK_<i>xxxx</i></tt> identification code should be recorded in the list opposite its assigned type number.</dd>
- <dt><tt>./libntp/clocktypes.c</tt></dt>
- <dd>The <tt>./libntp/clktype</tt> array is used by certain display functions. A unique short-form name of the driver should be entered together with its assigned identification code.</dd>
- <dt><tt>./ntpd/ntp_control.c</tt></dt>
- <dd>The <tt>clocktypes</tt> array is used for certain control message displays functions. It should be initialized with the reference clock class assigned to the driver, as per the NTP specification RFC-1305. See the <tt>./include/ntp_control.h</tt> header file for the assigned classes.</dd>
- <dt><tt>./ntpd/refclock_conf.c</tt></dt>
- <dd>This file contains a list of external structure definitions which are conditionally defined. A new set of entries should be installed similar to those already in the table. The <tt>refclock_conf</tt> array is a set of pointers to transfer vectors in the individual drivers. The external name of the transfer vector should be initialized in correspondence with the type number.</dd>
- </dl>
- <h4 id="intf">Interface Routine Overview</h4>
- <dl>
- <dt><tt>refclock_newpeer</tt> - initialize and start a reference clock.</dt>
- <dd>This routine allocates and initializes the interface structure which supports a reference clock in the form of an ordinary NTP peer. A driver-specific support routine completes the initialization, if used. Default peer variables which identify the clock and establish its reference ID and stratum are set here. It returns one if success and zero if the clock address is invalid or already running, insufficient resources are available or the driver declares a bum rap.</dd>
- <dt><tt>refclock_unpeer</tt> - shut down a clock</dt>
- <dd>This routine is used to shut down a clock and return its resources to the system.</dd>
- <dt><tt>refclock_transmit</tt> - simulate the transmit procedure</dt>
- <dd>This routine implements the NTP transmit procedure for a reference clock. This provides a mechanism to call the driver at the NTP poll interval, as well as provides a reachability mechanism to detect a broken radio or other madness.</dd>
- <dt><tt>refclock_process</tt> - insert a sample in the circular buffer</dt>
- <dd>This routine saves the offset computed from the on-time timestamp and the days, hours, minutes, seconds and nanoseconds in the circular buffer. Note that no provision is included for the year, as provided by some (but not all) radio clocks. Ordinarily, the year is implicit in the Unix file system and hardware/software clock support, so this is ordinarily not a problem.</dd>
- <dt><tt>refclock_receive</tt> - simulate the receive and packet procedures</dt>
- <dd>This routine simulates the NTP receive and packet procedures for a reference clock. This provides a mechanism in which the ordinary NTP filter, selection and combining algorithms can be used to suppress misbehaving radios and to mitigate between them when more than one is available for backup.</dd>
- <dt><tt>refclock_gtraw</tt>, <tt>refclock_gtlin</tt> - read the buffer and on-time timestamp</dt>
- <dd>These routines return the data received from the clock and the on-time timestamp. The <tt>refclock_gtraw</tt> routine returns a batch of one or more characters returned by the Unix terminal routines in raw mode. The <tt>refclock_gtlin</tt> routine removes the parity bit and control characters and returns all the characters up to and including the line terminator. Either routine returns the number of characters delivered.</dd>
- <dt><tt>refclock_open</tt> - open a serial port for reference clock</dt>
- <dd>This routine opens a serial port for I/O and sets default options. It returns the file descriptor if success and zero if failure.</dd>
- <dt><tt>refclock_ioctl</tt> - set serial port control functions</dt>
- <dd>This routine attempts to hide the internal, system-specific details of serial ports. It can handle POSIX (<tt>termios</tt>), SYSV (<tt>termio</tt>) and BSD (<tt>sgtty</tt>) interfaces with varying degrees of success. The routine returns one if success and zero if failure.</dd>
- <dt><tt>refclock_ppsapi</tt></dt>
- <dd>This routine initializes the Pulse-per-Second interface (see below).</dd>
- <dt><tt>refclock_pps</tt></dt>
- <dd>This routine is called once per second to read the latest PPS offset and save it in the circular buffer (see below).</dd>
- </dl>
- <h4 id="pps">Pulse-per-Second Interface</h4>
- <p>When the Pulse-per-Second Application Interface (RFC 2783) is present, a
- compact PPS interface is available to all drivers. See the <a href="prefer.html">Mitigation
- Rules and the Prefer Peer</a> page for further information. To use this interface,
- include the <tt>timeppps.h</tt> and <tt>refclock_atom.h</tt> header files
- and define the <tt>refclock_atom</tt> structure in the driver private storage.
- The <tt>timepps.h</tt> file is specific to each operating system and may not
- be available for some systems.</p>
- <p>To use the interface, call <tt>refclock_ppsapi</tt> from the startup routine
- passing the device file descriptor and <tt>refclock_atom</tt> structure pointer.
- Then, call <tt>refclock_pps</tt> from the timer routine passing the association
- pointer and <tt>refclock_atom</tt> structure pointer. See the <tt>refclock_atom.c</tt> file
- for examples and calling sequences. If the PPS signal is valid, the offset
- sample will be save in the circular buffer and a bit set in the association
- flags word indicating the sample is valid and the driver an be selected as
- a PPS peer. If this bit is set when the poll routine is called, the driver
- calls the <tt>refclock_receive</tt> routine to process the samples in the
- circular buffer and update the system clock.</p>
-
- <hr>
- <div align="center">
- <img src="pic/pogo1a.gif" alt="gif">
- </div>
- <br>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<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="#desc">Description</a></li>
+ <li class="inline"><a href="#file">Files Which Need to be Changed</a></li>
+ <li class="inline"><a href="#intf">Interface Routine Overview</a></li>
+ <li class="inline"><a href="#pps">Pulse-per-Second Interface</a></li>
+</ul>
+<hr>
+<h4 id="desc">Description</h4>
+<p>NTP reference clock support maintains the fiction that the clock is actually an ordinary server in the NTP tradition, but operating at a synthetic stratum of zero. The entire suite of algorithms filter the received data and select the best sources to correct the system clock. No packets are exchanged with a reference clock; however, the transmit, receive and packet procedures are replaced with code to simulate them.</p>
+<p>The driver assumes three timescales: standard time maintained by a distant laboratory such as USNO or NIST, reference time maintained by the external radio and the system time maintained by NTP. The radio synchronizes reference time via radio, satellite or modem. As the transmission means may not always be reliable, most radios continue to provide clock updates for some time after signal loss using an internal reference oscillator. In such cases the radio may or may not reveal the time since last synchronized or the estimated time error.</p>
+<p>All three timescales run only in Coordinated Universal Time (UTC) and are not adjusted for local timezone or standard/daylight time. The local timezone, standard/daylight indicator and year, if provided, are ignored. However, it is important to determine whether a leap second is to be inserted in the UTC timescale in the near future so NTP can insert it in the system timescale at the appropriate epoch.</p>
+<p>The interface routines in the <tt>ntp_refclock.c</tt> source file call the following driver routines via a transfer vector:</p>
+<dl>
+ <dt><tt>startup</tt></dt>
+ <dd>The association has just been mobilized. The driver may allocate a private structure and open the device(s) required.</dd>
+ <dt><tt>shutdown</tt></dt>
+ <dd>The association is about to be demobilized. The driver should close all device(s) and free private structures.</dd>
+ <dt><tt>receive</tt></dt>
+ <dd>A timecode string is ready for retrieval using the <tt>refclock_gtlin()</tt> or <tt>refclock_gtraw()</tt> routines and provide clock updates.</dd>
+ <dt><tt>poll</tt></dt>
+ <dd>Called at poll timeout, by default 64 s. Ordinarily, the driver will send a poll sequence to the radio as required.</dd>
+ <dt><tt>timer</tt></dt>
+ <dd>Called once per second. This can be used for housekeeping functions. In the case with pulse-per-second (PPS) signals, this can be used to process the signals and provide clock updates.</dd>
+</dl>
+<p>The receive routine retrieves a timecode string via serial or parallel port, PPS signal or other means. It decodes the timecode in days, hours, minutes, seconds and nanoseconds and checks for errors. It provides these data along with the on-time timestamp to the <tt>refclock_process</tt> routine, which saves the computed offset in a 60-sample circular buffer. On occasion, either by timeout, sample count or call to the poll routine, the driver calls <tt>refclock_receive</tt> to process the circular buffer samples and update the system clock.</p>
+<p>The best way to understand how the clock drivers work is to study one of the drivers already implemented, such as <tt>refclock_wwvb.c</tt>. The main interface is the <tt>refclockproc</tt> structure, which contains for most drivers the decoded timecode, on-time timestamp, reference timestamp, exception reports and statistics tallies, etc. The support routines are passed a pointer to the <tt>peer</tt> structure, which contains a pointer to the <tt>refclockproc</tt> structure, which in turn contains a pointer to the unit structure, if used. For legacy purposes, a table <tt>typeunit[type][unit]</tt> contains the peer structure pointer for each configured clock type and unit. This structure should not be used for new implementations.</p>
+<p>Radio and modem reference clocks by convention have addresses of the form <tt>127.127.<i>t</i>.<i>u</i></tt>, where <i>t</i> is the clock type and <i>u</i> in the range 0-3 is used to distinguish multiple instances of clocks of the same type. Most clocks require a serial or parallel port or special bus peripheral. The particular device is normally specified by adding a soft link <tt>/dev/device<i>u</i></tt> to the particular hardware device.</p>
+<p>By convention, reference clock drivers are named in the form <tt>refclock_<i>xxxx</i>.c</tt>, where <tt><i>xxxx</i></tt> is a unique string. Each driver is assigned a unique type number, long-form driver name, short-form driver name and device name. The existing assignments are in the <a href="refclock.html">Reference Clock Drivers</a> page and its dependencies. All drivers supported by the particular hardware and operating system are automatically detected in the autoconfigure phase and conditionally compiled.</p>
+<h4>Conventions, Fudge Factors and Flags</h4>
+<p>Most drivers support manual or automatic calibration for systematic offset bias using values encoded in the <tt>fudge</tt> configuration command. By convention, the <tt>time1</tt> value defines the calibration offset in seconds. For those drivers that support statistics collection using the <tt>filegen</tt> utility and the <tt>clockstats</tt> file, the <tt>flag4</tt> switch enables the utility.</p>
+<p>If the calibration feature has been enabled, the <tt>flag1</tt> switch is set and the PPS signal is actively disciplining the system time, the <tt>time1</tt> value is automatically adjusted to maintain a residual offset of zero. Once the its value has stabilized, the value can be inserted in the configuration file and the calibration feature disabled.</p>
+<h4 id="file">Files Which Need to be Changed</h4>
+<p>When a new reference clock driver is installed, the following files need to be edited. Note that changes are also necessary to properly integrate the driver in the configuration and makefile scripts, but these are decidedly beyond the scope of this page.</p>
+<dl>
+ <dt><tt>./include/ntp.h</tt></dt>
+ <dd>The reference clock type defines are used in many places. Each driver is assigned a unique type number. Unused numbers are clearly marked in the list. A unique <tt>REFCLK_<i>xxxx</i></tt> identification code should be recorded in the list opposite its assigned type number.</dd>
+ <dt><tt>./libntp/clocktypes.c</tt></dt>
+ <dd>The <tt>./libntp/clktype</tt> array is used by certain display functions. A unique short-form name of the driver should be entered together with its assigned identification code.</dd>
+ <dt><tt>./ntpd/ntp_control.c</tt></dt>
+ <dd>The <tt>clocktypes</tt> array is used for certain control message displays functions. It should be initialized with the reference clock class assigned to the driver, as per the NTP specification RFC-1305. See the <tt>./include/ntp_control.h</tt> header file for the assigned classes.</dd>
+ <dt><tt>./ntpd/refclock_conf.c</tt></dt>
+ <dd>This file contains a list of external structure definitions which are conditionally defined. A new set of entries should be installed similar to those already in the table. The <tt>refclock_conf</tt> array is a set of pointers to transfer vectors in the individual drivers. The external name of the transfer vector should be initialized in correspondence with the type number.</dd>
+</dl>
+<h4 id="intf">Interface Routine Overview</h4>
+<dl>
+ <dt><tt>refclock_newpeer</tt> - initialize and start a reference clock.</dt>
+ <dd>This routine allocates and initializes the interface structure which supports a reference clock in the form of an ordinary NTP peer. A driver-specific support routine completes the initialization, if used. Default peer variables which identify the clock and establish its reference ID and stratum are set here. It returns one if success and zero if the clock address is invalid or already running, insufficient resources are available or the driver declares a bum rap.</dd>
+ <dt><tt>refclock_unpeer</tt> - shut down a clock</dt>
+ <dd>This routine is used to shut down a clock and return its resources to the system.</dd>
+ <dt><tt>refclock_transmit</tt> - simulate the transmit procedure</dt>
+ <dd>This routine implements the NTP transmit procedure for a reference clock. This provides a mechanism to call the driver at the NTP poll interval, as well as provides a reachability mechanism to detect a broken radio or other madness.</dd>
+ <dt><tt>refclock_process</tt> - insert a sample in the circular buffer</dt>
+ <dd>This routine saves the offset computed from the on-time timestamp and the days, hours, minutes, seconds and nanoseconds in the circular buffer. Note that no provision is included for the year, as provided by some (but not all) radio clocks. Ordinarily, the year is implicit in the Unix file system and hardware/software clock support, so this is ordinarily not a problem.</dd>
+ <dt><tt>refclock_receive</tt> - simulate the receive and packet procedures</dt>
+ <dd>This routine simulates the NTP receive and packet procedures for a reference clock. This provides a mechanism in which the ordinary NTP filter, selection and combining algorithms can be used to suppress misbehaving radios and to mitigate between them when more than one is available for backup.</dd>
+ <dt><tt>refclock_gtraw</tt>, <tt>refclock_gtlin</tt> - read the buffer and on-time timestamp</dt>
+ <dd>These routines return the data received from the clock and the on-time timestamp. The <tt>refclock_gtraw</tt> routine returns a batch of one or more characters returned by the Unix terminal routines in raw mode. The <tt>refclock_gtlin</tt> routine removes the parity bit and control characters and returns all the characters up to and including the line terminator. Either routine returns the number of characters delivered.</dd>
+ <dt><tt>refclock_open</tt> - open a serial port for reference clock</dt>
+ <dd>This routine opens a serial port for I/O and sets default options. It returns the file descriptor if success and zero if failure.</dd>
+ <dt><tt>refclock_ioctl</tt> - set serial port control functions</dt>
+ <dd>This routine attempts to hide the internal, system-specific details of serial ports. It can handle POSIX (<tt>termios</tt>), SYSV (<tt>termio</tt>) and BSD (<tt>sgtty</tt>) interfaces with varying degrees of success. The routine returns one if success and zero if failure.</dd>
+ <dt><tt>refclock_ppsapi</tt></dt>
+ <dd>This routine initializes the Pulse-per-Second interface (see below).</dd>
+ <dt><tt>refclock_pps</tt></dt>
+ <dd>This routine is called once per second to read the latest PPS offset and save it in the circular buffer (see below).</dd>
+</dl>
+<h4 id="pps">Pulse-per-Second Interface</h4>
+<p>When the Pulse-per-Second Application Interface (RFC 2783) is present, a
+ compact PPS interface is available to all drivers. See the <a href="prefer.html">Mitigation
+ Rules and the Prefer Peer</a> page for further information. To use this interface,
+ include the <tt>timeppps.h</tt> and <tt>refclock_atom.h</tt> header files
+ and define the <tt>refclock_atom</tt> structure in the driver private storage.
+ The <tt>timepps.h</tt> file is specific to each operating system and may not
+ be available for some systems.</p>
+<p>To use the interface, call <tt>refclock_ppsapi</tt> from the startup routine
+ passing the device file descriptor and <tt>refclock_atom</tt> structure pointer.
+ Then, call <tt>refclock_pps</tt> from the timer routine passing the association
+ pointer and <tt>refclock_atom</tt> structure pointer. See the <tt>refclock_atom.c</tt> file
+ for examples and calling sequences. If the PPS signal is valid, the offset
+ sample will be save in the circular buffer and a bit set in the association
+ flags word indicating the sample is valid and the driver an be selected as
+ a PPS peer. If this bit is set when the poll routine is called, the driver
+ calls the <tt>refclock_receive</tt> routine to process the samples in the
+ circular buffer and update the system clock.</p>
+<hr>
+<div align="center"> <img src="pic/pogo1a.gif" alt="gif"> </div>
+<br>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>The Huff-n'-Puff Filter</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>The Huff-n'-Puff Filter</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 23:17<!-- #EndDate -->
+ UTC</p>
+<hr>
+<p>In scenarios where a considerable amount of data are to be downloaded or uploaded over telephone modems, timekeeping quality can be seriously degraded. This occurs because the differential delays on the two directions of transmission can be quite large. In many cases the apparent time errors are so large as to exceed the step threshold and a step correction can occur during and after the data transfer.</p>
+<p>The huff-n'-puff filter is designed to correct the apparent time offset in these cases. It depends on knowledge of the propagation delay when no other traffic is present, such as during other than work hours. The filter remembers the minimum delay over the most recent interval measured usually in hours. Under conditions of severe delay, the filter corrects the apparent offset using the sign of the offset and the difference between the apparent delay and minimum delay. The name of the filter reflects the negative (huff) and positive (puff) correction, which depends on the sign of the offset. The filter is activated by the <tt>tinker huffpuff</tt> command, as described in the <a href="miscopt.html">Miscellaneous Options</a> page.</p>
+<hr>
+<p><script type="text/javascript" language="javascript" src="scripts/footer.txt"></script></p>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>The Network Time Protocol (NTP) Distribution</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>The Network Time Protocol (NTP) Distribution</h3>
- <img src="pic/barnstable.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html"><i>P.T. Bridgeport Bear</i>; from <i>Pogo</i>, Walt Kelly</a>
- <p>Pleased to meet you.</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->07-Nov-2009 20:43<!-- #EndDate -->
- UTC</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>The Network Time Protocol (NTP) Distribution</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>The Network Time Protocol (NTP) Distribution</h3>
+<img src="pic/barnstable.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html"><i>P.T. Bridgeport Bear</i>; from <i>Pogo</i>, Walt Kelly</a>
+<p>Pleased to meet you.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->06-Sep-2010 20:10<!-- #EndDate -->
+ UTC</p>
<br clear="left">
- <h4>Related Links</h4>
- <ul>
- <li>A list of all links is on the <a href="sitemap.html">Site Map</a> page.</li>
- </ul>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#intro">Introduction</a></li>
- <li class="inline"><a href="#build">Building and Installing NTP</a></li>
- <li class="inline"><a href="#conf">Configuring Clients and Servers</a></li>
- <li class="inline"><a href="#opt">Features and Options</a></li>
- <li class="inline"><a href="#prob">Resolving Problems</a></li>
- <li class="inline"><a href="#info">Further Information</a></li>
- </ul>
- <hr>
- <h4 id="intro">Introduction</h4>
- <p>Note: The NTP Version 4 software contained in this distribution is available without charge under the conditions set forth in the <a href="copyright.html">Copyright Notice</a>.</p>
- <dl>
- <dd>It is very important that readers understand that the NTP document collection began 25 years ago and remains today a work in progress. It has evolved as new features were invented and old features retired. It has been widely copied, cached and morphed to other formats, including man pages, with varying loss of fidelity. However, these HTML pages are the ONLY authoritative and definitive reference. Readers should always use the collection that comes with the distribution they use. A copy of the online collection at <a href="http://www.ntp.org">www.ntp.org</a> is normally included in the most recent snapshot, but might not agree with an earlier snapshot or release version.</dd>
- </dl>
- <p>The Network Time Protocol (NTP) is widely used to synchronize a computer
- to Internet time servers or other sources, such as a radio or satellite
- receiver or telephone modem service. It can also be used as a server
- for dependent clients. It provides accuracies typically less than
- a millisecond on LANs and up to a few milliseconds on WANs. Typical
- NTP configurations utilize multiple redundant servers and diverse
- network paths in order to achieve high accuracy and reliability.
- Authentication is provided using symmetric key cryptography and
- the MD5 message digest algorithm included in the distribution. If
- the OpenSSL cryptographic library is installed, the SHA or SHA1 message
- digest algorithms can be used. If the OpenSSL library is installed,
- additional options based on public key cryptography are available.</p>
- <p>NTP time synchronization services are widely available in the public Internet.
- The public NTP subnet in early 2008 includes several thousand servers
- in most countries and on every continent of the globe, including Antarctica.
- These servers support a total population estimated at over 25 million computers
- in the global Internet. The NTP subnet operates with a hierarchy of levels,
- where each level is assigned a number called the stratum. Stratum 1 (primary)
- servers at the lowest level are directly synchronized to national time services.
- Stratum 2 (secondary) servers at the next higher level are synchronize to stratum
- 1 servers and so on. Normally, NTP clients and servers with a relatively small
- number of clients do not synchronize to public primary servers. There
- are several hundred public secondary servers operating at higher strata and
- are the preferred choice. </p>
- <p>Background information on computer network time synchronization is on the <a href="http://www.eecis.udel.edu/%7emills/exec.html">Executive Summary - Computer Network Time Synchronization</a> page. Discussion on new features and interoperability with previous NTP versions is on the <a href="release.html">NTP Version 4 Release Notes</a> page. Background information, bibliography and briefing slides suitable for presentations are on the <a href="http://www.eecis.udel.edu/%7emills/ntp.html">Network Time Synchronization Research Project</a> page. Additional information is at the NTP web site <a href="http://www.ntp.org">www.ntp.org</a>.</p>
- <h4 id="build">Building and Installing NTP</h4>
- <p>NTP supports Unix, VMS and Windows (Vista, XP, NT4 and 2000) systems. The <a href="build.html">Building and Installing the Distribution</a> page details the procedures for building and installing on a typical system. This distribution includes drivers for 44 radio and satellite receivers and telephone modem services in the US, Canada and Europe. A list of supported drivers is on the <a href="refclock.html">Reference Clock Drivers</a> page. The default build includes the debugging options and all drivers that run on the target machine; however, options and drivers can be included or excluded using options on the <a href="config.html">Configuration Options</a> page.</p>
- <h4 id="conf">Configuring Clients and Servers</h4>
- <p>NTP is by its very nature a complex distributed network application and can be configured for widely divergent timekeeping scenarios. The documentation on these pages attempts to cover the entire suite of configuration, operation and maintenance features which this distribution supports. However, most applications will need only a few of these features. The <a href="quick.html">Quick Start</a> page may be useful to get a simple workstation on the air with existing servers.</p>
- <p>The most important factor in providing accurate, reliable time is the selection of modes and servers in the configuration file. A discussion on the available modes is on the <a href="assoc.html">Association Management</a> page. The current public server list is maintained at the <a href="http://www.ntp.org">www.ntp.org</a> web site. In many cases the configuration can be automated using the schemes described on the <a href="manyopt.html">Automatic Server Discovery Schemes</a> page.</p>
- <h4 id="opt">Features and Options</h4>
- <p>This distribution includes a statistics data recording facility which can record performance statistics and events of various types for retrospective analysis. These include time and frequency statistics, significant events and usage statistics described on the <a href="monopt.html">Monitoring Options</a> page.</p>
- <p>Some programs included in this distribution use cryptographic algorithms to verify server authenticity. Where local security policy permits relatively weak symmetric key cryptography, the required software is included in this distribution. Where local policy requires stronger public key cryptography, the OpenSSL library available from <a href="http://www.openssl.org">http://www.openssl.org</a> is required. This library is also used by the Secure Shell facility, so is often already installed. Additional details are on the <a href="authopt.html">Authentication Options</a> page.</p>
- <p>This distribution includes features that can restrict access in various ways as described on the <a href="accopt.html">Access Control Options</a> page. This can be used to deny service if not authenticated, deny service requiring persistent resources or deny service altogether.</p>
- <p>This distribution includes a simulation framework in which substantially
- all the runtime NTP operations and most features can be tested and
- evaluated. This has been very useful in exploring in vitro response
- to unusual circumstances or over time periods impractical in vivo. Details
- are on the <a href="ntpdsim.html">Network
- Time Protocol (NTP) Simulator</a> page.</p>
- <h4 id="prob">Resolving Problems</h4>
- <p>Like other things in modern Internet life, NTP problems can be devilishly intricate. This distribution includes a number of utilities designed to identify and repair problems using an integrated management protocol supported by the <a href="ntpq.html"><tt>ntpq</tt></a> utility program In addition, the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility program can be useful in some cases.</p>
- <p>The <a href="debug.html">NTP Debugging Techniques</a> and <a href="hints.html">Hints and Kinks</a> pages contain useful information for identifying problems and devising solutions. Additional information on reference clock driver construction and debugging is in the <a href="rdebug.html">Debugging Hints for Reference Clock Drivers</a> page.</p>
- <p>Users are invited to report bugs and offer suggestions via the <a href="bugs.html">NTP Bug Reporting Procedures</a> page.</p>
- <h4 id="info">Further Information</h4>
- <p>The <a href="sitemap.html">Site Map</a> page contains a list of document collections arranged by topic. The Program Manual Pages collection may be the best place to start, followed by the <a href="comdex.html"></a>Configuration Commands and Options collection. The <a href="comdex.html">Command Index</a> collection contains a list of all configuration file commands together with a short function description. A great wealth of additional information is available via the External Links collection, including a book and numerous background papers and briefing presentations.</p>
- <hr>
- <div align="center">
- <img src="pic/pogo1a.gif" alt="gif"></div>
- <br>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<h4>Related Links</h4>
+<ul>
+ <li>A list of all links is on the <a href="sitemap.html">Site Map</a> page.</li>
+</ul>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#conf">The Handbook</a></li>
+ <li class="inline"><a href="#build">Building and Installing NTP</a></li>
+<li class="inline"><a href="#prob">Resolving Problems</a></li>
+ <li class="inline"><a href="#info">Further Information</a></li>
+</ul>
+<hr>
+<h4 id="intro">Introduction</h4>
+<p>Note: The NTP Version 4 software contained in this distribution is available without charge under the conditions set forth in the <a href="copyright.html">Copyright Notice</a>.</p>
+<dl>
+ <dd>It is very important that readers understand that the NTP document collection began 25 years ago and remains today a work in progress. It has evolved as new features were invented and old features retired. It has been widely copied, cached and morphed to other formats, including man pages, with varying loss of fidelity. However, these HTML pages are the ONLY authoritative and definitive reference. Readers should always use the collection that comes with the distribution they use. A copy of the online collection at <a href="http://www.ntp.org">www.ntp.org</a> is normally included in the most recent snapshot, but might not agree with an earlier snapshot or release version.</dd>
+</dl>
+<p>The Network Time Protocol (NTP) is widely used to synchronize a computer
+ to Internet time servers or other sources, such as a radio or satellite
+ receiver or telephone modem service. It can also be used as a server
+ for dependent clients. It provides accuracies typically less than
+ a millisecond on LANs and up to a few milliseconds on WANs. Typical
+ NTP configurations utilize multiple redundant servers and diverse
+ network paths in order to achieve high accuracy and reliability.
+ Authentication is provided using symmetric key cryptography and
+ the MD5 message digest algorithm included in the distribution. If
+ the OpenSSL cryptographic library is installed, the SHA or SHA1 message
+ digest algorithms can be used. If the OpenSSL library is installed,
+ additional options based on public key cryptography are available.</p>
+<p>NTP time synchronization services are widely available in the public Internet.
+ The public NTP subnet in late 2010 includes several thousand servers
+ in most countries and on every continent of the globe, including Antarctica.
+ These servers support a total population estimated at over 25 million computers
+ in the global Internet. The NTP subnet operates with a hierarchy of levels,
+ where each level is assigned a number called the stratum. Stratum 1 (primary)
+ servers at the lowest level are directly synchronized to national time services.
+ Stratum 2 (secondary) servers at the next higher level are synchronize to stratum
+ 1 servers and so on. Normally, NTP clients and servers with a relatively small
+ number of clients do not synchronize to public primary servers. There
+ are several hundred public secondary servers operating at higher strata and
+ are the preferred choice.</p>
+<p>This distribution includes a simulation framework in which substantially
+ all the runtime NTP operations and most features can be tested and
+ evaluated. This has been very useful in exploring in vitro response
+ to unusual circumstances or over time periods impractical in vivo. Details
+ are on the <a href="ntpdsim.html">Network
+Time Protocol (NTP) Simulator</a> page.</p>
+<h4 id="info2">The Handbook</h4>
+<p>A good deal of tutorial and directive information is availabl on the handbook pages. These should be read in conjunction with the command and opetion information available on the pages listed on the sitemap page.</p>
+<dl>
+ <dt><a href="release.html">NTP Version 4 Release NotesVersion 4 Release Notes</a></dt>
+ <dd>Lists recent changes and new features in the current distribution.</dd>
+ <dt><a href="assoc.html">Association Management</a></dt>
+ <dd>Describes how to configure servers and peers and manage the various options. Includes automatic server discovery schemes.</dd>
+ <dt><a href="discover.html">Automatic Server Discovery Schemes</a>
+ <dd>Describes automatic ser very discovery using broadcast, multicast, manycast and server pool scheme.</dd>
+ <dt><a href="access.html">Access Control Support</a></dt>
+ <dd>Describes the access control mechanisms that can be used to limit client access to various time and management functions.</dd>
+ <dt><a href="authentic.html">Authentication Support</a></dt>
+ <dd>Describes the authentication mechanisms for symmetric-key and public-key cryptography.</dd>
+ <dt><a href="rate.html">Rate Management</a></dt>
+ <dd>Describes the principles of rate management to minimize network load and defend against DoS attacks</dd>
+ <dt> </dt>
+ <dt><a href="refclock.html">Reference Clock Support</a></dt>
+ <dd>Describes the collection of radio clocks used to synchronize primary servers.</dd>
+ <dt><a href="warp.html">How NTP Works</a></dt>
+ <dd>Gives an overview of the NTP daemon architecture and how it works.</dd>
+</dl>
+<h4 id="build">Building and Installing NTP</h4>
+<p>NTP supports Unix, VMS and Windows (Vista, XP, NT4 and 2000) systems. The <a href="build.html">Building and Installing the Distribution</a> page details the procedures for building and installing on a typical system. This distribution includes drivers for 44 radio and satellite receivers and telephone modem services in the US, Canada and Europe. A list of supported drivers is on the <a href="refclock.html">Reference Clock Drivers</a> page. The default build includes the debugging options and all drivers that run on the target machine; however, options and drivers can be included or excluded using options on the <a href="config.html">Configuration Options</a> page.</p>
+<h4 id="prob">Resolving Problems</h4>
+<p>Like other things in modern Internet life, NTP problems can be devilishly intricate. This distribution includes a number of utilities designed to identify and repair problems using an integrated management protocol supported by the <a href="ntpq.html"><tt>ntpq</tt></a> utility program In addition, the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility program can be useful in some cases.</p>
+<p>The <a href="debug.html">NTP Debugging Techniques</a> and <a href="hints.html">Hints and Kinks</a> pages contain useful information for identifying problems and devising solutions. Additional information on reference clock driver construction and debugging is in the <a href="rdebug.html">Debugging Hints for Reference Clock Drivers</a> page.</p>
+<p>Users are invited to report bugs and offer suggestions via the <a href="bugs.html">NTP Bug Reporting Procedures</a> page.</p>
+<h4 id="info">Further Information</h4>
+<p>The <a href="sitemap.html">Site Map</a> page contains a list of document collections arranged by topic. The Program Manual Pages collection may be the best place to start. The <a href="comdex.html">Command Index</a> collection contains a list of all configuration file commands together with a short function description. A great wealth of additional information is available via the External Links collection, including a book and numerous background papers and briefing presentations.</p>
+<p>Background information on computer network time synchronization is on the <a href="http://www.eecis.udel.edu/%7emills/exec.html">Executive Summary - Computer Network Time Synchronization</a> page. Discussion on new features and interoperability with previous NTP versions is on the <a href="release.html">NTP Version 4 Release Notes</a> page. Background information, bibliography and briefing slides suitable for presentations are on the <a href="http://www.eecis.udel.edu/%7emills/ntp.html">Network Time Synchronization Research Project</a> page. Additional information is at the NTP web site <a href="http://www.ntp.org">www.ntp.org</a>.</p>
+<hr>
+<div align="center"> <img src="pic/pogo1a.gif" alt="gif"></div>
+<br>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Kernel Model for Precision Timekeeping</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Kernel Model for Precision Timekeeping</h3>
- <p><img src="pic/alice61.gif" alt="gif" align="left"> <a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a></p>
- <p>Alice finds the kernel a house of cards.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">15:42</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
- <hr>
- <p>The technical report [2], which is a revision and update of an earlier report [3], describes an engineering model for a precision clock discipline function for a generic operating system. The model is the same hybrid phase/frequecy-lock feedback loop used by <tt>ntpd</tt>, but implemented in the kernel. The code described in [2] is included in Solaris and Digital/Compaq/HP Tru64. It provides two system calls <tt>ntp_gettime()</tt> and <tt>ntp_adjtime()</tt> and can discipline the system clock with microsecond resolution. However, newer hardware and kernels with the same system calls can discipline the clock with nanosecond resolution. The new code described in [1] is in FreeBSD and is an option for Linux, SunOS and Tru64; however, of the options, only the Linux implementation, which does not include licensed code, is readily available. The software and documentation, including a simulator used to verify correct behavior, but not involving licensed code, is available from <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a>.</p>
- <p>The kernel model also provides support for an external precision timing source, such as described in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. The new system calls are used by the <a href="kernpps.html">PPSAPI interface</a> and in turn by the <a href="drivers/driver22.html">PPS Clock Discipline</a> driver (type 22) to provide synchronization limited in principle only by the accuracy and stability of the external timing source.</p>
- <h4>References</h4>
- <ol>
- <li>Mills, D.L., and P.-H. Kamp. The nanokernel. <i>Proc. Precision Time and Time Interval (PTTI) Applications and Planning Meeting</i> (Reston VA, November 2000). Paper: <a href="http://www.eecis.udel.edu/%7emills/database/papers/nano/nano2.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/papers/nano/nano2.pdf">PDF</a>, Slides: <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.html">HTML</a> | <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.pdf">PDF</a> | <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.ppt">PowerPoint</a></li>
- <li>Mills, D.L. Unix kernel modifications for precision time synchronization. Electrical Engineering Department Report 94-10-1, University of Delaware, October 1994, 24 pp. Abstract: <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kerna.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kerna.pdf">PDF</a>, Body: <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kernb.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kernb.pdf">PDF</a></li>
- <li>Mills, D.L. A kernel model for precision timekeeping. Network Working Group Report RFC-1589, University of Delaware, March 1994. 31 pp. <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1589.txt">ASCII</a></li>
- </ol>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Kernel Model for Precision Timekeeping</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Kernel Model for Precision Timekeeping</h3>
+<p><img src="pic/alice61.gif" alt="gif" align="left"> <a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a></p>
+<p>Alice finds the kernel a house of cards.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 22:01<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
+<hr>
+<p>The technical report [2], which is a revision and update of an earlier report [3], describes an engineering model for a precision clock discipline function for a generic operating system. The model is the same hybrid phase/frequecy-lock feedback loop used by <tt>ntpd</tt>, but implemented in the kernel. The code described in [2] is included in Solaris and Digital/Compaq/HP Tru64. It provides two system calls <tt>ntp_gettime()</tt> and <tt>ntp_adjtime()</tt> and can discipline the system clock with microsecond resolution. However, newer hardware and kernels with the same system calls can discipline the clock with nanosecond resolution. The new code described in [1] is in FreeBSD and is an option for Linux, SunOS and Tru64; however, of the options, only the Linux implementation, which does not include licensed code, is readily available. The software and documentation, including a simulator used to verify correct behavior, but not involving licensed code, is available from <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a>.</p>
+<p>The kernel model also provides support for an external precision timing source, such as described in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. The new system calls are used by the <a href="kernpps.html">PPSAPI interface</a> and in turn by the <a href="drivers/driver22.html">PPS Clock Discipline</a> driver (type 22) to provide synchronization limited in principle only by the accuracy and stability of the external timing source.</p>
+<h4>References</h4>
+<ol>
+ <li>Mills, D.L., and P.-H. Kamp. The nanokernel. <i>Proc. Precision Time and Time Interval (PTTI) Applications and Planning Meeting</i> (Reston VA, November 2000). Paper: <a href="http://www.eecis.udel.edu/%7emills/database/papers/nano/nano2.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/papers/nano/nano2.pdf">PDF</a>, Slides: <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.html">HTML</a> | <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.pdf">PDF</a> | <a href="http://www.eecis.udel.edu/%7emills/database/brief/nano/nano.ppt">PowerPoint</a></li>
+ <li>Mills, D.L. Unix kernel modifications for precision time synchronization. Electrical Engineering Department Report 94-10-1, University of Delaware, October 1994, 24 pp. Abstract: <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kerna.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kerna.pdf">PDF</a>, Body: <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kernb.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/reports/kern/kernb.pdf">PDF</a></li>
+ <li>Mills, D.L. A kernel model for precision timekeeping. Network Working Group Report RFC-1589, University of Delaware, March 1994. 31 pp. <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1589.txt">ASCII</a></li>
+</ol>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <title>PPSAPI Interface for Precision Time Signals</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>PPSAPI Interface for Precision Time Signals</h3>
- <img src="pic/tonea.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>NBS Special Publication 432, 1979</i></a> (out of print)
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">15:40</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <p>
- <script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
- <br clear="left">
- </p>
- <hr>
- <h4>Introduction</h4>
- <p>RFC-2783 describes the PPSAPI application programming interface for external precision time signals, such as the pulse-per-second (PPS) signal generated by some radio clocks and cesium oscillators. The PPSAPI provides a generic capability in the ubiquitous Unix kernel which can be used for a wide variety of measurement applications, including network time synchronization and related experiments. The hardware to do this requires only a serial port and a modem control lead, such as the data carrier detect (DCD) lead, which can be driven by an external source via a level converter/pulse generator such as described on the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. In some systems a parallel port can be used for the same purpose.</p>
- <p>The PPSAPI interface defined in RFC-2783 is the only PPS interface supported in NTP Version 4. The PPSAPI is supported in stock FreeBSD and, with the addition of the <tt>PPSkit</tt> kernel module, in Linux.</p>
- <p>The special header file <tt>/usr/include/sys/timepps.h</tt> implements the PPSAPI using whatever primitives are available in each archeticture and operating system. It obsoletes previous APIs based on the <tt>tty_clock</tt> and <tt>ppsclock</tt> line disciplines and streams modules, which are no longer supported.</p>
- <p>The <a href="drivers/driver22.html">PPS Clock Discipline</a> driver (type 22) uses the PPSAPI in conjunction with a local radio clock or remote NTP server as a reference clock. The driver can also use the PPSAPI as an interface directly to the kernel PPS facility as described on the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page.</p>
- <h4>PPSAPI Application Program Interface</h4>
- <p>The PPSAPI interface provides the following functions:</p>
- <dl>
- <dt><tt>time_pps_create</tt>
- <dd>Creates a PPS interface instance and returns a handle to it.
- <dt><tt>time_pps_destroy</tt>
- <dd>Destroys a PPS interface and returns the resources used.
- <dt><tt>time_pps_setparams</tt>
- <dd>Sets the parameters associated with a PPS interface instance, including offsets to be automatically added to captured timestamps.
- <dt><tt>time_pps_getparams</tt>
- <dd>Returns the parameters associated with a PPS interface instance.
- <dt><tt>time_pps_getcap</tt>
- <dd>Returns the capabilities of the current interface and kernel implementation.
- <dt><tt>time_pps_fetch</tt>
- <dd>Returns the current timestamps associated with a PPS interface instance in either nanoseconds and nanoseconds (Unix <tt>timespec</tt>) or seconds and fraction (NTP) format.
- <dt><tt>time_pps_kcbind</tt>
- <dd>If kernel PPS processing is supported, this binds the support to the associated PPS interface instance.
- </dl>
- <p>The entire PPS interface functionality is currently provided by inline code in the <tt>timepps.h</tt> header file. While not all implementations support the full PPSAPI specification, they do support all the functions required for the PPS driver described next. The FreeBSD, Linux and Solaris implementations can be used with the stock kernels provided with those systems; however, the Tru64 and SunOS kernels require additional functions not provided in the stock kernels. Solaris users are cautioned that these functions operate improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. Header files for other systems can be found via the web at <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a>.</p>
-<hr> <hr>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<title>PPSAPI Interface for Precision Time Signals</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>PPSAPI Interface for Precision Time Signals</h3>
+<img src="pic/tonea.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>NBS Special Publication 432, 1979</i></a> (out of print)
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 23:16<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
+ <br clear="left">
+</p>
+<hr>
+<h4>Introduction</h4>
+<p>RFC-2783 describes the PPSAPI application programming interface for external precision time signals, such as the pulse-per-second (PPS) signal generated by some radio clocks and cesium oscillators. The PPSAPI provides a generic capability in the ubiquitous Unix kernel which can be used for a wide variety of measurement applications, including network time synchronization and related experiments. The hardware to do this requires only a serial port and a modem control lead, such as the data carrier detect (DCD) lead, which can be driven by an external source via a level converter/pulse generator such as described on the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. In some systems a parallel port can be used for the same purpose.</p>
+<p>The PPSAPI interface defined in RFC-2783 is the only PPS interface supported in NTP Version 4. The PPSAPI is supported in stock FreeBSD and, with the addition of the <tt>PPSkit</tt> kernel module, in Linux.</p>
+<p>The special header file <tt>/usr/include/sys/timepps.h</tt> implements the PPSAPI using whatever primitives are available in each archeticture and operating system. It obsoletes previous APIs based on the <tt>tty_clock</tt> and <tt>ppsclock</tt> line disciplines and streams modules, which are no longer supported.</p>
+<p>The <a href="drivers/driver22.html">PPS Clock Discipline</a> driver (type 22) uses the PPSAPI in conjunction with a local radio clock or remote NTP server as a reference clock. The driver can also use the PPSAPI as an interface directly to the kernel PPS facility as described on the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page.</p>
+<h4>PPSAPI Application Program Interface</h4>
+<p>The PPSAPI interface provides the following functions:</p>
+<dl>
+ <dt><tt>time_pps_create</tt></dt>
+ <dd>Creates a PPS interface instance and returns a handle to it.</dd>
+ <dt><tt>time_pps_destroy</tt></dt>
+ <dd>Destroys a PPS interface and returns the resources used.</dd>
+ <dt><tt>time_pps_setparams</tt></dt>
+ <dd>Sets the parameters associated with a PPS interface instance, including offsets to be automatically added to captured timestamps.</dd>
+ <dt><tt>time_pps_getparams</tt></dt>
+ <dd>Returns the parameters associated with a PPS interface instance.
+ </dd><dt><tt>time_pps_getcap</tt></dt>
+ <dd>Returns the capabilities of the current interface and kernel implementation.</dd>
+ <dt><tt>time_pps_fetch</tt></dt>
+ <dd>Returns the current timestamps associated with a PPS interface instance in either nanoseconds and nanoseconds (Unix <tt>timespec</tt>) or seconds and fraction (NTP) format.</dd>
+ <dt><tt>time_pps_kcbind</tt></dt>
+ <dd>If kernel PPS processing is supported, this binds the support to the associated PPS interface instance.</dd>
+</dl>
+<p>The entire PPS interface functionality is currently provided by inline code in the <tt>timepps.h</tt> header file. While not all implementations support the full PPSAPI specification, they do support all the functions required for the PPS driver described next. The FreeBSD, Linux and Solaris implementations can be used with the stock kernels provided with those systems; however, the Tru64 and SunOS kernels require additional functions not provided in the stock kernels. Solaris users are cautioned that these functions operate improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. Header files for other systems can be found via the web at <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a>.</p>
+<hr>
+<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
<head>
<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
<meta name="generator" content="HTML Tidy, see www.w3.org">
<title>ntp-keygen - generate public and private keys</title>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
-
<body>
<h3><tt>ntp-keygen</tt> - generate public and private keys</h3>
-
<p><img src="pic/alice23.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>
-
<p>Alice holds the key.</p>
-
-<p>Last update:
- <!-- #BeginDate format:En2m -->13-Nov-2009 0:44<!-- #EndDate -->
+<p>Last update:
+ <!-- #BeginDate format:En2m -->03-Sep-2010 23:20<!-- #EndDate -->
</p>
<br clear="left">
-
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
-
<h4>Table of Contents</h4>
-
<ul>
-
-<li class="inline"><a href="#synop">Synopsis</a></li>
-<li class="inline"><a href="#descrip">Description</a></li>
-<li class="inline"><a href="#run">Running the program</a></li>
-<li class="inline"><a href="#trust">Trusted Hosts and Secure Groups</a></li>
-<li class="inline"><a href="#ident">Identity Schemes</a></li>
-<li class="inline"><a href="#cmd">Command Line Options</a></li>
-<li class="inline"><a href="#rand">Random Seed File</a></li>
-<li class="inline"><a href="#fmt">Cryptographic Data Files</a></li>
-<li class="inline"><a href="#bug">Bugs</a></li>
+ <li class="inline"><a href="#synop">Synopsis</a></li>
+ <li class="inline"><a href="#descrip">Description</a></li>
+ <li class="inline"><a href="#run">Running the program</a></li>
+ <li class="inline"><a href="#trust">Trusted Hosts and Secure Groups</a></li>
+ <li class="inline"><a href="#ident">Identity Schemes</a></li>
+ <li class="inline"><a href="#cmd">Command Line Options</a></li>
+ <li class="inline"><a href="#rand">Random Seed File</a></li>
+ <li class="inline"><a href="#fmt">Cryptographic Data Files</a></li>
+ <li class="inline"><a href="#bug">Bugs</a></li>
</ul>
-
<hr>
-
<h4 id="synop">Synopsis</h4>
-
<p id="intro"><tt>ntp-keygen [ -deGHIMPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA
- | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [
- -i <i>group</i> ]
- [ -m <i>modulus</i> ] [ -p <i>passwd2</i> ] [ -q <i>passwd1</i> ] [ -S
- [ RSA | DSA ] ] [ -s <i>host</i> ] [ -V <i>nkeys</i> ]</tt></p>
-
+ | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [
+ -i <i>group</i> ]
+ [ -m <i>modulus</i> ] [ -p <i>passwd2</i> ] [ -q <i>passwd1</i> ] [ -S
+ [ RSA | DSA ] ] [ -s <i>host</i> ] [ -V <i>nkeys</i> ]</tt></p>
<h4 id="descrip">Description</h4>
-
<p>This program generates cryptographic data files used by the NTPv4 authentication
- and identity schemes. It can generate message digest keys used in symmetric
- key cryptography and, if the OpenSSL software library has been installed,
- it can generate host keys, sign keys, certificates and identity keys used
- by the Autokey public key cryptography. The message digest keys file is generated
- in a format compatible with NTPv3. All other files are in PEM-encoded printable
- ASCII format so they can be embedded as MIME attachments in mail to other
- sites.</p>
-
+ and identity schemes. It can generate message digest keys used in symmetric
+ key cryptography and, if the OpenSSL software library has been installed,
+ it can generate host keys, sign keys, certificates and identity keys used
+ by the Autokey public key cryptography. The message digest keys file is generated
+ in a format compatible with NTPv3. All other files are in PEM-encoded printable
+ ASCII format so they can be embedded as MIME attachments in mail to other
+ sites.</p>
<p>When used to generate message digest keys, the program produces a file containing
- ten pseudo-random printable ASCII strings suitable for the MD5 message digest
- algorithm included in the distribution. If the OpenSSL library is installed,
- it produces an additional ten hex-encoded random bit strings suitable for
- the SHA1 and other message digest algorithms. Printable ASCII keys can have
- length from one to 20 characters, inclusive. Bit string keys have length
- 20 octets (40 hex characters). All keys are 160 bits in length.</p>
+ ten pseudo-random printable ASCII strings suitable for the MD5 message digest
+ algorithm included in the distribution. If the OpenSSL library is installed,
+ it produces an additional ten hex-encoded random bit strings suitable for
+ the SHA1 and other message digest algorithms. Printable ASCII keys can have
+ length from one to 20 characters, inclusive. Bit string keys have length
+ 20 octets (40 hex characters). All keys are 160 bits in length.</p>
<p> The file can be edited later with
- purpose-chosen passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> programs.
- Each line of the file contains three fields, first an integer between 1 and
- 65534, inclusive, representing the key identifier used in the <tt>server</tt> and <tt>peer</tt> configuration
- commands. Next is the key type for the message digest algorithm,
- which in the absence of the OpenSSL library should be the string <tt>MD5</tt> to
- designate the MD5 message digest algorithm.
- If the OpenSSL library is installed, the key type can be any message digest
- algorithm supported by that library. However, if compatibility with FIPS
- 140-2 is required, the key type must be either <tt>SHA</tt> or <tt>SHA1</tt>.Finally
- is the key itself as a printable ASCII string excluding the space and # characters.
- If not greater than 20 characters in length, the string is the key itself;
- otherwise, it is interpreted as a hex-encoded bit string. As is
- custom, # and the remaining characters on the line are ignored. Later, this
- file can be edited to include the passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> utilities.
- If this is the only need, run <tt>ntp-keygen</tt> with the <tt>-M</tt> option
- and disregard the remainder of this page. </p>
+ purpose-chosen passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> programs.
+ Each line of the file contains three fields, first an integer between 1 and
+ 65534, inclusive, representing the key identifier used in the <tt>server</tt> and <tt>peer</tt> configuration
+ commands. Next is the key type for the message digest algorithm,
+ which in the absence of the OpenSSL library should be the string <tt>MD5</tt> to
+ designate the MD5 message digest algorithm.
+ If the OpenSSL library is installed, the key type can be any message digest
+ algorithm supported by that library. However, if compatibility with FIPS
+ 140-2 is required, the key type must be either <tt>SHA</tt> or <tt>SHA1</tt>.Finally
+ is the key itself as a printable ASCII string excluding the space and # characters.
+ If not greater than 20 characters in length, the string is the key itself;
+ otherwise, it is interpreted as a hex-encoded bit string. As is
+ custom, # and the remaining characters on the line are ignored. Later, this
+ file can be edited to include the passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> utilities.
+ If this is the only need, run <tt>ntp-keygen</tt> with the <tt>-M</tt> option
+ and disregard the remainder of this page. </p>
<p>The remaining generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates generated by this program should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identity keys are probably not compatible with anything other than Autokey.</p>
-
<p>Most files used by this program are encrypted using a private password. The <tt>-p</tt> option specifies the password for local files and the <tt>-q</tt> option the password for files sent to remote sites. If no local password is specified, the host name returned by the Unix <tt>gethostname()</tt> function, normally the DNS name of the host, is used. If no remote password is specified, the local password is used.</p>
-
<p>The <tt>pw</tt> option of the <tt>crypto</tt> configuration command specifies the read password for previously encrypted files. This must match the local password used by this program. If not specified, the host name is used. Thus, if files are generated by this program without password, they can be read back by <tt>ntpd</tt> without password, but only on the same host.</p>
-
<p>All files and links are usually installed in the directory <tt>/usr/local/etc</tt>,
- which is normally in a shared filesystem in NFS-mounted networks and cannot
- be changed by shared clients. The location of the keys directory can be changed
- by the <tt>keysdir</tt> configuration command in such cases. Normally, encrypted
- files for each host are generated by that host and used only by that host,
- although exceptions exist as noted later on this page.</p>
-
+ which is normally in a shared filesystem in NFS-mounted networks and cannot
+ be changed by shared clients. The location of the keys directory can be changed
+ by the <tt>keysdir</tt> configuration command in such cases. Normally, encrypted
+ files for each host are generated by that host and used only by that host,
+ although exceptions exist as noted later on this page.</p>
<p>This program directs commentary and error messages to the standard error stream <tt>stderr</tt> and remote files to the standard output stream <tt>stdout</tt> where they can be piped to other applications or redirected to a file. The names used for generated files and links all begin with the string <tt>ntpkey</tt> and include the file type, generating host and filestamp, as described in the <a href="#fmt">Cryptographic Data Files</a> section below</p>
-
<h4 id="run">Running the Program</h4>
-
<p>To test and gain experience with Autokey concepts, log in as root and change to the keys directory, usually <tt>/usr/local/etc</tt>. When run for the first time, or if all files with names beginning <tt>ntpkey</tt> have been removed, use the <tt>ntp-keygen </tt>command without arguments to generate a default RSA host key and matching RSA-MD5 certificate with expiration date one year hence. If run again, the program uses the existing keys and parameters and generates only a new certificate with new expiration date one year hence; however, the certificate is not generated if the <tt>-e</tt> or <tt>-q</tt> options are present.</p>
-
<p>Run the command on as many hosts as necessary. Designate one of them as the trusted host (TH) using <tt>ntp-keygen</tt> with the <tt>-T</tt> option and configure it to synchronize from reliable Internet servers. Then configure the other hosts to synchronize to the TH directly or indirectly. A certificate trail is created when Autokey asks the immediately ascendant host towards the TH to sign its certificate, which is then provided to the immediately descendant host on request. All group hosts should have acyclic certificate trails ending on the TH.</p>
-
<p>The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. A different sign key can be assigned using the <tt>-S</tt> option and this can be either RSA or DSA type. By default, the signature message digest type is MD5, but any combination of sign key type and sign digest type supported by the OpenSSL library can be specified using the <tt>-c</tt> option. At the moment, legacy considerations require the NTP packet header digest type to be MD5.</p>
-
<h4 id="trust">Trusted Hosts and Secure Groups</h4>
-
<p>As described on the <a href="authopt.html">Authentication Options</a> page, an NTP secure group consists of one or more low-stratum THs as the root from which all other group hosts derive synchronization directly or indirectly. For authentication purposes all hosts in a group must have the same group name specified by the <tt>-i</tt> option and matching the <tt>ident</tt> option of the <tt>crypto</tt> configuration command. The group name is used in the subject and issuer fields of trusted, self-signed certificates and when constructing the file names for identity keys. All hosts must have different host names, either the default host name or as specified by the <tt>-s</tt> option and matching the <tt>host</tt> option of the <tt>crypto</tt> configuration command. Most installations need not specify the <tt>-i</tt> option nor the <tt>host</tt> option. Host names are used in the subject and issuer fields of self-signed, nontrusted certificates and when constructing the file names for host and sign keys and certificates. Host and group names are used only for authentication purposes and have nothing to do with DNS names.</p>
-
<h4 id="ident">Identity Schemes</h4>
-
<p>As described on the <a href="authopt.html">Authentication Options</a> page, there are five identity schemes, three of which - IFF, GQ and MV - require identity keys specific to each scheme. There are two types of files for each scheme, an encrypted keys file and a nonencrypted parameters file, which usually contains a subset of the keys file. In general, NTP secondary servers operating as certificate signing authorities (CSA) use the keys file and clients use the parameters file. Both files are generated by the TA operating as a certificate authority (CA) on behalf of all servers and clients in the group.</p>
-
<p>The parameters files are public; they can be stored in a public place and
- sent in the clear. The keys files are encrypted with the local password. To
- retrieve the keys file, a host can send a mail request to the TA including its
- local password. The TA encrypts the keys file with this password and returns
- it as an attachment. The attachment is then copied intact to the keys directory
- with name given in the first line of the file, but all in lower case and with
- the filestamp deleted. Alternatively, the parameters file can be retrieved from
- a secure web site.</p>
-
+ sent in the clear. The keys files are encrypted with the local password. To
+ retrieve the keys file, a host can send a mail request to the TA including its
+ local password. The TA encrypts the keys file with this password and returns
+ it as an attachment. The attachment is then copied intact to the keys directory
+ with name given in the first line of the file, but all in lower case and with
+ the filestamp deleted. Alternatively, the parameters file can be retrieved from
+ a secure web site.</p>
<p>For example, the TA generates default host key, IFF keys and trusted certificate using the command</p>
-
<p><tt>ntp-keygen -p <i>local_passwd</i> -T -I -i<i>group_name</i></tt></p>
-
<p>Each group host generates default host keys and nontrusted certificate use
- the same command line but omitting the <tt>-i</tt> option. Once these media
- have been generated, the TA can then generate the public parameters using the
- command</p>
-
+ the same command line but omitting the <tt>-i</tt> option. Once these media
+ have been generated, the TA can then generate the public parameters using the
+ command</p>
<p><tt>ntp-keygen -p local_passwd -e ><i>parameters_file</i></tt></p>
-
<p>where the <tt>-e</tt> option redirects the unencrypted parameters to the standard output stream for a mail application or stored locally for later distribution. In a similar fashion the <tt>-q</tt> option redirects the encrypted server keys to the standard output stream.</p>
-
<h4 id="cmd">Command Line Options</h4>
-
<dl>
-
-<dt><tt>-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]</tt></dt>
-<dd>Select certificate and message digest/signature encryption scheme. Note that
- RSA schemes must be used with a RSA sign key and DSA schemes must be used
- with a DSA sign key. The default without this option is <tt>RSA-MD5</tt>. If
- compatibility with FIPS 140-2 is required, either the <tt>DSA-SHA</tt> or <tt>DSA-SHA1</tt> scheme
- must be used.</dd>
-
-<dt><tt>-d</tt></dt>
-<dd>Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.</dd>
-
-<dt><tt>-e</tt></dt>
-<dd>Extract the IFF or GQ public parameters from the <tt>IFFkey</tt> or <tt>GQkey</tt> keys file previously specified. Send the unencrypted data to the standard output stream <tt>stdout</tt>. While the IFF parameters do not reveal the private group key, the GQ parameters should be used with caution, as they include the group key. Use the <tt>-q</tt> option with password instead. Note: a new certificate is not generated when this option is present. This allows multiple commands with this option but without disturbing existing media.</dd>
-
-<dt><tt>-G</tt></dt>
-<dd>Generate a new encrypted GQ key file and link for the Guillou-Quisquater
- (GQ) identity scheme.</dd>
-
-<dt><tt>-H</tt></dt>
-<dd>Generate a new encrypted RSA public/private host key file and link<tt></tt>.
- Note that if the sign key is the same as the host key, generating a new host
- key invalidates all certificates signed with the old host key.</dd>
-
-<dt><tt>-i <i>group</i></tt></dt>
-<dd>Set the group name to <tt><i>group</i></tt>. This is used in the identity file names. It must match the group name specified in the <tt>ident</tt> option of the <tt>crypto</tt> configuration command.</dd>
-
-<dt><tt>-I</tt></dt>
-<dd>Generate a new encrypted IFF key file<tt> </tt>and link<tt> </tt>for the Schnorr (IFF) identity scheme.</dd>
-
-<dt><tt>-m <i>modulus</i></tt></dt>
-<dd>Set the modulus for generating files to <i>modulus</i> bits. The modulus defaults to 512, but can be set from 256 (32 octets) to 2048 (256 octets).</dd>
-
-<dt><tt>-M</tt></dt>
-<dd>Generate a new MD5 key file containing 16, 128-bit pseudo-random keys for
- symmetric cryptography..</dd>
-
-<dt><tt>-P</tt></dt>
-<dd>Generate a new private certificate used by the PC identity scheme. By default, the program generates public certificates. Note: the PC identity scheme is not recommended for new installations.</dd>
-
-<dt><tt>-p <i>passwd</i></tt></dt>
-<dd>Set the password for reading and writing encrypted files to <tt><i>passwd</i></tt>. By default, the password is the host name.</dd>
-
-<dt><tt>-q <i>passwd</i></tt></dt>
-<dd>Extract the encrypted IFF or GQ server keys from the <tt>IFFkey</tt> or <tt>GQkey</tt> key file previously generated. The data are sent to the standard output stream <tt>stdout</tt>. Set the password for writing the data, which is also the password to read the data file in another host. By default, the password is the host name. Note: a new certificate is not generated when this option is present. This allows multiple commands with this option but without disturbing existing media.</dd>
-
-<dt><tt>-S [ RSA | DSA ]</tt></dt>
-<dd>Generate a new sign key of the specified type. By default, the sign key is
- the host key and has the same type. If compatibly with FIPS 140-2 is required,
- the sign key type must be <tt>DSA</tt>. Note that generating a new sign key
- invalidates all certificates signed with the old sign key.</dd>
-
-<dt><tt>-s <i>host</i></tt></dt>
-<dd>Set the host name to <tt><i>host</i></tt>. This is used in the host and sign key file names. It must match the host name specified in the <tt>host</tt> option of the <tt>crypto</tt> configuration command.</dd>
-
-<dt><tt>-T</tt></dt>
-<dd>Generate a trusted certificate. By default, the program generates nontrusted certificates.</dd>
-
-<dt><tt>-V <i>nkeys</i></tt></dt>
-<dd>Generate server parameters <tt>MV</tt> and <tt><i>nkeys</i></tt> client keys for the Mu-Varadharajan (MV) identity scheme. Note: support for this option should be considered a work in progress.</dd>
+ <dt><tt>-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]</tt></dt>
+ <dd>Select certificate and message digest/signature encryption scheme. Note that
+ RSA schemes must be used with a RSA sign key and DSA schemes must be used
+ with a DSA sign key. The default without this option is <tt>RSA-MD5</tt>. If
+ compatibility with FIPS 140-2 is required, either the <tt>DSA-SHA</tt> or <tt>DSA-SHA1</tt> scheme
+ must be used.</dd>
+ <dt><tt>-d</tt></dt>
+ <dd>Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.</dd>
+ <dt><tt>-e</tt></dt>
+ <dd>Extract the IFF or GQ public parameters from the <tt>IFFkey</tt> or <tt>GQkey</tt> keys file previously specified. Send the unencrypted data to the standard output stream <tt>stdout</tt>. While the IFF parameters do not reveal the private group key, the GQ parameters should be used with caution, as they include the group key. Use the <tt>-q</tt> option with password instead. Note: a new certificate is not generated when this option is present. This allows multiple commands with this option but without disturbing existing media.</dd>
+ <dt><tt>-G</tt></dt>
+ <dd>Generate a new encrypted GQ key file and link for the Guillou-Quisquater
+ (GQ) identity scheme.</dd>
+ <dt><tt>-H</tt></dt>
+ <dd>Generate a new encrypted RSA public/private host key file and link<tt></tt>.
+ Note that if the sign key is the same as the host key, generating a new host
+ key invalidates all certificates signed with the old host key.</dd>
+ <dt><tt>-i <i>group</i></tt></dt>
+ <dd>Set the group name to <tt><i>group</i></tt>. This is used in the identity file names. It must match the group name specified in the <tt>ident</tt> option of the <tt>crypto</tt> configuration command.</dd>
+ <dt><tt>-I</tt></dt>
+ <dd>Generate a new encrypted IFF key file<tt> </tt>and link<tt> </tt>for the Schnorr (IFF) identity scheme.</dd>
+ <dt><tt>-m <i>modulus</i></tt></dt>
+ <dd>Set the modulus for generating files to <i>modulus</i> bits. The modulus defaults to 512, but can be set from 256 (32 octets) to 2048 (256 octets).</dd>
+ <dt><tt>-M</tt></dt>
+ <dd>Generate a new MD5 key file containing 16, 128-bit pseudo-random keys for
+ symmetric cryptography..</dd>
+ <dt><tt>-P</tt></dt>
+ <dd>Generate a new private certificate used by the PC identity scheme. By default, the program generates public certificates. Note: the PC identity scheme is not recommended for new installations.</dd>
+ <dt><tt>-p <i>passwd</i></tt></dt>
+ <dd>Set the password for reading and writing encrypted files to <tt><i>passwd</i></tt>. By default, the password is the host name.</dd>
+ <dt><tt>-q <i>passwd</i></tt></dt>
+ <dd>Extract the encrypted IFF or GQ server keys from the <tt>IFFkey</tt> or <tt>GQkey</tt> key file previously generated. The data are sent to the standard output stream <tt>stdout</tt>. Set the password for writing the data, which is also the password to read the data file in another host. By default, the password is the host name. Note: a new certificate is not generated when this option is present. This allows multiple commands with this option but without disturbing existing media.</dd>
+ <dt><tt>-S [ RSA | DSA ]</tt></dt>
+ <dd>Generate a new sign key of the specified type. By default, the sign key is
+ the host key and has the same type. If compatibly with FIPS 140-2 is required,
+ the sign key type must be <tt>DSA</tt>. Note that generating a new sign key
+ invalidates all certificates signed with the old sign key.</dd>
+ <dt><tt>-s <i>host</i></tt></dt>
+ <dd>Set the host name to <tt><i>host</i></tt>. This is used in the host and sign key file names. It must match the host name specified in the <tt>host</tt> option of the <tt>crypto</tt> configuration command.</dd>
+ <dt><tt>-T</tt></dt>
+ <dd>Generate a trusted certificate. By default, the program generates nontrusted certificates.</dd>
+ <dt><tt>-V <i>nkeys</i></tt></dt>
+ <dd>Generate server parameters <tt>MV</tt> and <tt><i>nkeys</i></tt> client keys for the Mu-Varadharajan (MV) identity scheme. Note: support for this option should be considered a work in progress.</dd>
</dl>
-
<h4 id="rand">Random Seed File</h4>
-
<p>All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the OpenSSL library routines. If a site supports <tt>ssh</tt>, it is very likely that means to do this are already available. The entropy seed used by the OpenSSL library is contained in a file, usually called <tt>.rnd</tt>, which must be available when starting the <tt>ntp-keygen</tt> program or <tt>ntpd</tt> daemon.</p>
-
<p>The OpenSSL library looks for the file using the path specified by the <tt>RANDFILE</tt> environment variable in the user home directory, whether root or some other user. If the <tt>RANDFILE</tt> environment variable is not present, the library looks for the <tt>.rnd</tt> file in the user home directory. Since both the <tt>ntp-keygen</tt> program and <tt>ntpd</tt> daemon must run as root, the logical place to put this file is in <tt>/.rnd</tt> or <tt>/root/.rnd</tt>. If the file is not available or cannot be written, the program exits with a message to the system log.</p>
-
<h4 id="priv">Cryptographic Data Files</h4>
-
<p>File and link names are in the form <tt>ntpkey_<i>key</i>_<i>name</i>.<i>fstamp</i></tt>, where <tt><i>key</i></tt> is the key or parameter type, <tt><i>name</i></tt> is the host or group name and <tt><i>fstamp</i></tt> is the filestamp (NTP seconds) when the file was created). By convention, key fields in generated file names include both upper and lower case alphanumeric characters, while key fields in generated link names include only lower case characters. The filestamp is not used in generated link names.</p>
-
<p>The key type is a string defining the cryptographic function. Key types include public/private keys <tt>host</tt> and <tt>sign</tt>, certificate <tt>cert</tt> and several challenge/response key types. By convention, files used for challenges have a <tt>par</tt> subtype, as in the IFF challenge <tt>IFFpar</tt>, while files for responses have a <tt>key</tt> subtype, as in the GQ response <tt>GQkey</tt>.</p>
-
<p>All files begin with two nonencrypted lines. The first line contains the file name in the format <tt>ntpkey_<i>key</i>_<i>host</i>.<i>fstamp</i></tt>. The second line contains the datestamp in conventional Unix <tt>date</tt> format. Lines beginning with <tt>#</tt> are ignored.</p>
-
<p>The remainder of the file contains cryptographic data encoded first using ASN.1 rules, then encrypted using the DES-CBC algorithm and given password and finally written in PEM-encoded printable ASCII text preceded and followed by MIME content identifier lines.</p>
-
<p id="symkey">The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. Since DES-CBC is deprecated in NTPv4, the only key format of interest is MD5 alphanumeric strings. Following the header the keys are entered one per line in the format</p>
-
<p><i><tt>keyno type key</tt></i></p>
-
<p>where <i><tt>keyno</tt></i> is a positive integer in the range 1-65,535, <i><tt>type</tt></i> is the string <tt>MD5</tt> defining the key format and <i><tt>key</tt></i> is the key itself, which is a printable ASCII string 16 characters or less in length. Each character is chosen from the 93 printable characters in the range 0x21 through 0x7f excluding space and the '#' character.</p>
-
<p>Note that the keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in human readable ASCII format.</p>
-
<p>The <tt>ntp-keygen</tt> program generates a MD5 symmetric keys file <tt>ntpkey_MD5key_<i>hostname.filestamp</i></tt>. Since the file contains private shared keys, it should be visible only to root and distributed by secure means to other subnet hosts. The NTP daemon loads the file <tt>ntp.keys</tt>, so <tt>ntp-keygen</tt> installs a soft link from this name to the generated file. Subsequently, similar soft links must be installed by manual or automated means on the other subnet hosts. While this file is not used with the Autokey Version 2 protocol, it is needed to authenticate some remote configuration commands used by the <a href="ntpq.html"><tt>ntpq</tt></a> and <a href="ntpdc.html"><tt>ntpdc</tt></a> utilities.</p>
-
<h4 id="bug">Bugs</h4>
-
<p>It can take quite a while to generate some cryptographic values, from one to several minutes with modern architectures such as UltraSPARC and up to tens of minutes to an hour with older architectures such as SPARC IPC.</p>
-
<hr>
-
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
-
</body>
-
-</html>
\ No newline at end of file
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Leap Second Processing</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Leap Second Processing</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->07-Sep-2010 17:25<!-- #EndDate -->
+ UTC</p>
+<hr>
+<p>About every eighteen months the International Earth Rotation Service (IERS) issues a bulletin announcing the insertion of a leap second in the Universal Coordinated Time (UTC) timescale. Ordinarily, this happens at the end of the last day of June or December; but, in principal, it could happen at the end of any month. While these bulletins are available on the Internet at <a href="http://www.iers.org">www.iers.org</a>, advance notice of leap seconds is also available in signals broadcast from national time and frequency stations, in GPS signals and in telephone modem services. Many, but not all, reference clocks recognize these signals and many, but not all, drivers for them can decode the signals and set the leap bits in the timecode accordingly. This means that many, but not all, primary servers can pass on these bits in the NTP packet heard to dependent secondary servers and clients. Secondary servers can pass these bits to their dependents and so on throughout the NTP subnet.</p>
+<p> A leap second is inserted following second 59 of the last minute of the day and becomes second 60 of that day. A leap second is deleted by omitting second 59 of the last minute of the day, although this has never happened and is highly unlikely to happen in future. So far as is known, there are no provisions in the Unix or Windows libraries to account for this occasion other than to to affect the conversion of an NTP datestamp or timestamp to conventional civil time.</p>
+<p>When an update is received from a reference clock or downstratum server, the leap bits are inspected for all survivors of the cluster algorithm. If the number of survivors showing a leap bit is greater than half the total number of survivors, a pending leap condition exists until the end of the current month.</p>
+<p>When no means are available to determine the leap bits from a reference clock or downstratum server, a leapseconds file can be downloaded from time.nist.gov and installed using the <a href="miscopt.html#leapfile">leapfile</a> command. The file includes a list of historic leap second and the NTP time of insertion. It is parsed by the <tt>ntpd</tt> daemon at startup and the latest leap time saved for future reference. Each time the clock is set, the current time is compared with the last leap time. If the current time is later than the last leap time, nothing further is done. If earlier, the leap timer is initialized with the time in seconds until the leap time and counts down from there. When the leap timer is less than one month, a pending leap condition exists until the end of the current month. If the leapseconds file is present, the leap bits for reference clocks and downstratum servers are ignored.</p>
+<p>If the precision time kernel support is installed and enabled, at the begriming of the day of the leap event the leap bits are set in the Unix <tt>ntp_adjtime()</tt> system call to arm the kernel for the leap at the end of the day. The kernel automatically inserts one second exactly at the time of the leap, after which the leap bits are turned off. If the kernel support is not availed or disabled, the leap is implemented as a crude hack by setting the clock back one second using the Unix <tt>settimeofday() </tt>system call, which effectively repeats the last second. Note however that in any case setting the time backwards by one second does not actually set the system clock backwards, but effectively stalls the clock for one second. These points are expanded in the white paper <a href="http://www.eecis.udel.edu/~mills/leap.html">The NTP Timescale and Leap Seconds</a>. If the leap timer is less than one day, the leap bits are set for dependent servers and clients.</p>
+<p>As an additional feature when the NIST leap seconds file is installed, it is possible to determine the number of leap seconds inserted in UTC since UTC began on 1 January 1972. This represents the offset between International Atomic Time (TAI) and UTC. If the precision time kernel modifications are available and enabled, the TAI offset is available to application programs using the <tt>antipasti()</tt> system call. If the Auto key public-key cryptography feature is installed, the TAI offset is automatically propagated along with other cryptographic media to dependent servers and clients.</p>
+<hr>
+<p><script type="text/javascript" language="javascript" src="scripts/footer.txt"></script></p>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <title>Miscellaneous Options</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<title>Miscellaneous Commands and Options</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
-
- <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:
- <!-- #BeginDate format:En2m -->11-Apr-2010 22:56<!-- #EndDate -->
- UTC</p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/miscopt.txt"></script>
- <hr>
- <dl>
- <dt id="broadcastdelay"><tt>broadcastdelay <i>seconds</i></tt></dt>
- <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.</dd>
- <dt id="driftfile"><tt>driftfile <i>driftfile</i> { <i>tolerance</i> ]</tt></dt>
- <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 or more 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.</dd>
- <dd>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.</dd>
- <dd>The parameter <tt>tolerance</tt> is the wander threshold to skip writing the new value. If the value of wander computed from recent frequency changes is greater than this threshold the file will be updated once per hour. If below the threshold, the file will not be written.</dd>
- <dt id="enable"><tt>enable [auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt><br>
- <tt>disable [auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt></dt>
- <dd>Provides a way to enable or disable various system options. Flags not mentioned are unaffected. Note that all of these flags can be controlled remotely using <a href="ntpq.html"><tt>ntpq</tt></a> and <a href="ntpdc.html"><tt>ntpdc</tt></a> utility programs.
- <dl>
- <dt><tt>auth</tt></dt>
- <dd>Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using either public key or private key cryptography. The default for this flag is enable.</dd>
- <dt><tt>bclient</tt></dt>
- <dd>Enables the server to listen for a message from a broadcast or multicast server, as in the <tt>multicastclient</tt> command with default address. The default for this flag is disable.</dd>
- <dt><tt>calibrate</tt></dt>
- <dd>Enables the calibrate feature for reference clocks. The default for this flag is disable.</dd>
- <dt><tt>kernel</tt></dt>
- <dd>Enables the kernel time discipline, if available. The default for this flag is enable if support is available, otherwise disable.</dd>
- <dt><tt>monitor</tt></dt>
- <dd>Enables the monitoring facility. See the <a href="ntpq.html"><tt>ntpq</tt> program</a> and the <tt>monstats</tt> and
- <tt>mrulist</tt> commands, as well as the <a href="accopt.html#discard">Access Control Options</a> for details.
- The monitoring facility is also enabled by the presence of <a href="accopt.html#limited"><tt>limited</tt></a>
- in any <tt>restrict</tt> commands. The default for this flag is enable.</dd>
- <dt><tt>ntp</tt></dt>
- <dd>Enables time and frequency discipline. In effect, this switch opens and closes the feedback loop, which is useful for testing. The default for this flag is enable.</dd>
- <dt><tt>stats</tt></dt>
- <dd>Enables the statistics facility. See the <a href="monopt.html">Monitoring Options</a> page for further information. The default for this flag is disable.</dd>
- </dl>
- </dd>
- <dt id="includefile"><tt>includefile <i>includefile</i></tt></dt>
- <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).</dd>
- <dt id="interface"><tt>interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | <i>name</i> | <i>address</i>[/<i>prefixlen</i>]]</tt></dt>
- <dd>This command controls which network addresses <tt>ntpd</tt> opens, and whether input is dropped without processing. The first parameter determines the action for addresses which match the second parameter. That parameter specifies a class of addresses, or a specific interface name, or an address. In the address case, <tt><i>prefixlen</i></tt> determines how many bits must match for this rule to apply. <tt>ignore</tt> prevents opening matching addresses, <tt>drop</tt> causes <tt>ntpd</tt> to open the address and drop all received packets without examination. Multiple <tt>interface</tt> commands can be used. The last rule which matches a particular address determines the action for it. <tt>interface</tt> commands are disabled if any <a href="ntpd.html#--interface"><tt>-I</tt></a>, <a href="ntpd.html#--interface"><tt>--interface</tt></a>, <a href="ntpd.html#--novirtualips"><tt>-L</tt></a>, or <a href="ntpd.html#--novirtualips"><tt>--novirtualips</tt></a> command-line options are used. If none of those options are used and no <tt>interface</tt> actions are specified in the configuration file, all available network addresses are opened. The <tt>nic</tt> command is an alias for <tt>interface</tt>.</dd>
- <dt id="leapfile"><tt>leapfile <i>leapfile</i></tt></dt>
- <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>.</dd>
- <dd>While not strictly a security function, the Autokey protocol provides means to securely retrieve the current or updated leapsecond values from a server.</dd>
- <dt id="logconfig"><tt>logconfig <i>configkeyword</i></tt></dt>
- <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>).</dd>
- <dd>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>.</dd>
- <dd>Thus, a minimal log configuration could look like this:</dd>
- <dd><tt>logconfig=syncstatus +sysevents</tt></dd>
- <dd>This would just list the synchronizations state of <tt>ntpd</tt> and the major system events. For a simple reference server, the following minimum message configuration could be useful:</dd>
- <dd><tt>logconfig=syncall +clockall</tt></dd>
- <dd>This configuration will list all clock information and synchronization information. All other events and messages about peers, system events and so on is suppressed.</dd>
- <dt id="logfile"><tt>logfile <i>logfile</i></tt></dt>
- <dd>This command specifies the location of an alternate log file to be used instead of the default system <tt>syslog</tt> facility. This is the same operation as the <tt>-l </tt>command line option.</dd>
- <dt id="mru"><tt>mru [maxdepth <i>count</i> | maxmem <i>kilobytes</i> | mindepth <i>count</i> | maxage <i>seconds</i> | initalloc <i>count</i> | initmem <i>kilobytes</i> | incalloc <i>count</i> | incmem <i>kilobytes</i>]</tt></dt>
- <dd>Controls size limits of the monitoring facility Most Recently Used <a href="ntpq.html#mrulist">(MRU) list</a> of client addresses, which is also used by the <a href="accopt.html#discard">rate control facility</a>.
- <dl>
- <dt><tt>maxdepth <i>count</i><br>
- maxmem <i>kilobytes</i></tt></dt>
- <dd>Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. The actual
- limit will be up to <tt>incalloc</tt> entries or <tt>incmem</tt> kilobytes larger. As with all
- of the <tt>mru</tt> options offered in units of entries or kilobytes, if both <tt>maxdepth</tt>
- and <tt>maxmem</tt> are used, the last one used controls. The default is 1024 kilobytes.</dd>
- <dt><tt>mindepth <i>count</i></tt></dt>
- <dd>Lower limit on the MRU list size. When the MRU list has fewer than <tt>mindepth</tt> entries,
- existing entries are never removed to make room for newer ones, regardless of their age.
- The default is 600 entries.</dd>
- <dt><tt>maxage <i>seconds</i></tt></dt>
- <dd>Once the MRU list has <tt>mindepth</tt> entries and an additional client address is to be added
- to the list, if the oldest entry was updated more than <tt>maxage</tt> seconds ago, that entry
- is removed and its storage reused. If the oldest entry was updated more recently, the MRU list
- is grown, subject to <tt>maxdepth</tt>/<tt>maxmem</tt>. The default is 64 seconds.</dd>
- <dt><tt>initalloc <i>count</i><br>
- initmem <i>kilobytes</i></tt></dt>
- <dd>Initial memory allocation at the time the monitoring facility is first enabled, in terms of
- entries or kilobytes. The default is 4 kilobytes.</dd>
- <dt><tt>incalloc <i>count</i><br>
- incmem <i>kilobytes</i></tt></dt>
- <dd>Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
- The default is 4 kilobytes.</dd>
- </dl>
- </dd>
- <dt id="phone"><tt>phone <i>dial</i>1 <i>dial</i>2 ...</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="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>
- <dd>This command adds an additional system variable. These variables can be used to distribute additional information such as the access policy. If the variable of the form <tt><i>name</i> = <i>value</i></tt> is followed by the <tt>default</tt> keyword, the variable will be listed as part of the default system variables (<tt>ntpq rv</tt> command). These additional variables serve informational purposes only. They are not related to the protocol other that they can be listed. The known protocol variables will always override any variables defined via the <tt>setvar</tt> mechanism. There are three special variables that contain the names of all variable of the same group. The <tt>sys_var_list</tt> holds the names of all system variables. The <tt>peer_var_list</tt> holds the names of all peer variables and the <tt>clock_var_list</tt> holds the names of the reference clock variables.</dd>
- <dt id="tinker"><tt>tinker [ allan <i>allan</i> | dispersion <i>dispersion</i> | freq <i>freq</i> | huffpuff <i>huffpuff</i> | panic <i>panic</i> | step <i>step</i> | stepout <i>stepout</i> ]</tt></dt>
- <dd>This command alters certain system variables used by the clock discipline algorithm. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. The options are as follows:</dd>
- <dd><dl>
- <dt><tt>allan <i>allan</i></tt></dt>
- <dd>Spedifies the Allan intercept, which is a parameter of the PLL/FLL clock discipline algorithm, in seconds with default 1500 s.</dd>
- <dt><tt>dispersion <i>dispersion</i></tt></dt>
- <dd>Specifies the dispersion increase rate in parts-per-million (PPM) with default 15 PPM.</dd>
- <dt><tt>freq <i>freq</i></tt></dt>
- <dd>Spedifies the frequency offset in parts-per-million (PPM) with default the value in the frequency file.</dd>
- <dt><tt>huffpuff <i>huffpuff</i></tt></dt>
- <dd>Spedifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours).</dd>
- <dt><tt>panic <i>panic</i></tt></dt>
- <dd>Spedifies the panic threshold in seconds with default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted.</dd>
- <dt><tt>step <i>step</i></tt></dt>
- <dd>Spedifies the step threshold in seconds. The default without this command
- is 0.128 s. If set to zero, step adjustments will never
- occur. Note: The kernel time discipline is disabled if
- the step threshold is set to zero or greater than 0.5
- s.</dd>
- <dt><tt>stepout <i>stepout</i></tt></dt>
- <dd>Specifies the stepout threshold in seconds. The default without this
- command is 900 s. If set to zero, popcorn spikes will
- not be suppressed.</dd>
- </dl></dd>
- <dt id="tos"><tt>tos [ beacon <i>beacon</i> | ceiling <i>ceiling</i> | cohort {0 | 1} | floor <i>floor</i> | maxclock <i>maxclock </i>| maxdist <i>maxdist</i> | minclock <i>minclock</i> | mindist <i>mindist </i>| minsane <i>minsane</i> | orphan <i>stratum</i> | orphanwait <em>delay</em> ]</tt></dt>
- <dd>This command alters certain system variables used by the the clock selection and clustering algorithms. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. It can be used to select the quality and quantity of peers used to synchronize the system clock and is most useful in dynamic server discovery schemes. The options are as follows:</dd>
- <dd><dl>
- <dt><tt>beacon <i>beacon</i></tt></dt>
- <dd>The manycast server sends packets at intervals of 64 s if less than <tt>maxclock</tt> servers are available. Otherwise, it sends packets at the <i><tt>beacon</tt></i> interval in seconds. The default is 3600 s. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
- <dt><tt>ceiling <i>ceiling</i></tt></dt>
- <dd>Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
- <dt><tt>cohort { 0 | 1 }</tt></dt>
- <dd>Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
- <dt><tt>floor <i>floor</i></tt></dt>
- <dd>Specify the minimum stratum (inclusive) for acceptable server packest. The default is 1. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
- <dt><tt>maxclock <i>maxclock</i></tt></dt>
- <dd>Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
- <dt><tt>maxdist <i>maxdistance</i></tt></dt>
- <dd>Specify the synchronization distance threshold used by the clock selection algorithm. The default is 1.5 s. This determines both the minimum number of packets to set the system clock and the maximum roundtrip delay. It can be decreased to improve reliability or increased to synchronize clocks on the Moon or planets.</dd>
- <dt><tt>minclock <i>minclock</i></tt></dt>
- <dd>Specify the number of servers used by the clustering algorithm as the minimum to include on the candidate list. The default is 3. This is also the number of servers to be averaged by the combining algorithm.</dd>
- <dt><tt>mindist <i>mindistance</i></tt></dt>
- <dd>Specify the minimum distance used by the selection and anticlockhop
- algorithm. Larger values increase the tolerance for outliers;
- smaller values increase the selectivity. The default is .001 s. In some
- cases, such as reference clocks with high jitter and a PPS signal, it is
- useful to increase the value to insure the intersection interval is
- always nonempty.</dd>
- <dt><tt>minsane <i>minsane</i></tt></dt>
- <dd>Specify the number of servers used by the selection algorithm as the minimum to set the system clock. The default is 1 for legacy purposes; however, for critical applications the value should be somewhat higher but less than <tt>minclock</tt>.</dd>
- <dt><tt>orphan <i>stratum</i></tt></dt>
- <dd>Specify the orphan stratum with default 16. If less than 16 this is the stratum assumed by the root servers. See the <a href="assoc.html">Association Management</a> page for further details.</dd>
- <dt><tt>orphanwait <em>delay</em></tt></dt>
- <dd> </dd>
- <dd>Specify the delay in seconds from the time all sources are lost until orphan mode is enabled with default 500 s (five minutes). This allows time for one or more sources to be found without enabling orphan mode and later disabline it.</dd>
- </dl>
- </dd>
- <dt id="trap"><tt>trap <i>host_address</i> [port <i>port_number</i>] [interface <i>interfSace_address</i>]</tt></dt>
- <dd>This command configures a trap receiver at the given host address and port number for sending messages with the specified local interface address. If the port number is unspecified, a value of 18447 is used. If the interface address is not specified, the message is sent with a source address of the local interface the message is sent through. Note that on a multihomed host the interface used may vary from time to time with routing changes.</dd>
- <dd>The trap receiver will generally log event messages and other information from the server in a log file. While such monitor programs may also request their own trap dynamically, configuring a trap receiver will ensure that no messages are lost when the server is started.</dd>
- <dt id="ttl"><tt>ttl <i>hop</i> ...</tt></dt>
- <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.</dd>
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<body>
+<h3>Miscellaneous Commands and 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:
+ <!-- #BeginDate format:En2m -->06-Sep-2010 18:31<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/miscopt.txt"></script>
+<hr>
+<h4>Commands and Options</h4>
+<dl>
+ <dt id="broadcastdelay"><tt>broadcastdelay <i>seconds</i></tt></dt>
+ <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.</dd>
+ <dt id="driftfile"><tt>driftfile <i>driftfile</i> { <i>tolerance</i> ]</tt></dt>
+ <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 line option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour or more 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.</dd>
+ <dd>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.</dd>
+ <dd>The parameter <tt>tolerance</tt> is the wander threshold to skip writing the new value. If the value of wander computed from recent frequency changes is greater than this threshold the file will be updated once per hour. If below the threshold, the file will not be written.</dd>
+ <dt id="enable"><tt>enable [auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt><br>
+ <tt>disable [auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt></dt>
+ <dd>Provides a way to enable or disable various system options. Flags not mentioned are unaffected. Note that all of these flags can be controlled remotely using <a href="ntpq.html"><tt>ntpq</tt></a> and <a href="ntpdc.html"><tt>ntpdc</tt></a> utility programs.
+ <dl>
+ <dt><tt>auth</tt></dt>
+ <dd>Enables the server to synchronize with unconfigured peers only if the peer has been correctly authenticated using either public key or private key cryptography. The default for this flag is enable.</dd>
+ <dt><tt>bclient</tt></dt>
+ <dd>Enables the server to listen for a message from a broadcast or multicast server, as in the <tt>multicastclient</tt> command with default address. The default for this flag is disable.</dd>
+ <dt><tt>calibrate</tt></dt>
+ <dd>Enables the calibrate feature for reference clocks. The default for this flag is disable.</dd>
+ <dt><tt>kernel</tt></dt>
+ <dd>Enables the kernel time discipline, if available. The default for this flag is enable if support is available, otherwise disable.</dd>
+ <dt><tt>monitor</tt></dt>
+ <dd>Enables the monitoring facility. See the <a href="ntpq.html"><tt>ntpq</tt> program</a> and the <tt>monstats</tt> and <tt>mrulist</tt> commands, as well as the <a href="accopt.html#discard">Access Control Options</a> for details.
+ The monitoring facility is also enabled by the presence of <a href="accopt.html#limited"><tt>limited</tt></a> in any <tt>restrict</tt> commands. The default for this flag is enable.</dd>
+ <dt><tt>ntp</tt></dt>
+ <dd>Enables time and frequency discipline. In effect, this switch opens and closes the feedback loop, which is useful for testing. The default for this flag is enable.</dd>
+ <dt><tt>stats</tt></dt>
+ <dd>Enables the statistics facility. See the <a href="monopt.html">Monitoring Options</a> page for further information. The default for this flag is disable.</dd>
+ </dl>
+ </dd>
+ <dt id="includefile"><tt>includefile <i>includefile</i></tt></dt>
+ <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).</dd>
+ <dt id="interface"><tt>interface [listen | ignore | drop] [all | ipv4 | ipv6 | wildcard | <i>name</i> | <i>address</i>[/<i>prefixlen</i>]]</tt></dt>
+ <dd>This command controls which network addresses <tt>ntpd</tt> opens, and whether input is dropped without processing. The first parameter determines the action for addresses which match the second parameter. That parameter specifies a class of addresses, or a specific interface name, or an address. In the address case, <tt><i>prefixlen</i></tt> determines how many bits must match for this rule to apply. <tt>ignore</tt> prevents opening matching addresses, <tt>drop</tt> causes <tt>ntpd</tt> to open the address and drop all received packets without examination. Multiple <tt>interface</tt> commands can be used. The last rule which matches a particular address determines the action for it. <tt>interface</tt> commands are disabled if any <a href="ntpd.html#--interface"><tt>-I</tt></a>, <a href="ntpd.html#--interface"><tt>--interface</tt></a>, <a href="ntpd.html#--novirtualips"><tt>-L</tt></a>, or <a href="ntpd.html#--novirtualips"><tt>--novirtualips</tt></a> command-line options are used. If none of those options are used and no <tt>interface</tt> actions are specified in the configuration file, all available network addresses are opened. The <tt>nic</tt> command is an alias for <tt>interface</tt>.</dd>
+ <dt id="leapfile"><tt>leapfile <i>leapfile</i></tt></dt>
+ <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>.</dd>
+ <dd>While not strictly a security function, the Autokey protocol provides means to securely retrieve the current or updated leapsecond values from a server.</dd>
+ <dt id="logconfig"><tt>logconfig <i>configkeyword</i></tt></dt>
+ <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>).</dd>
+ <dd>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>.</dd>
+ <dd>Thus, a minimal log configuration could look like this:</dd>
+ <dd><tt>logconfig=syncstatus +sysevents</tt></dd>
+ <dd>This would just list the synchronizations state of <tt>ntpd</tt> and the major system events. For a simple reference server, the following minimum message configuration could be useful:</dd>
+ <dd><tt>logconfig=syncall +clockall</tt></dd>
+ <dd>This configuration will list all clock information and synchronization information. All other events and messages about peers, system events and so on is suppressed.</dd>
+ <dt id="logfile"><tt>logfile <i>logfile</i></tt></dt>
+ <dd>This command specifies the location of an alternate log file to be used instead of the default system <tt>syslog</tt> facility. This is the same operation as the <tt>-l </tt>command line option.</dd>
+ <dt id="mru"><tt>mru [maxdepth <i>count</i> | maxmem <i>kilobytes</i> | mindepth <i>count</i> | maxage <i>seconds</i> | initalloc <i>count</i> | initmem <i>kilobytes</i> | incalloc <i>count</i> | incmem <i>kilobytes</i>]</tt></dt>
+ <dd>Controls size limits of the monitoring facility Most Recently Used <a href="ntpq.html#mrulist">(MRU) list</a> of client addresses, which is also used by the <a href="accopt.html#discard">rate control facility</a>.
+ <dl>
+ <dt><tt>maxdepth <i>count</i><br>
+ maxmem <i>kilobytes</i></tt></dt>
+ <dd>Equivalent upper limits on the size of the MRU list, in terms of entries or kilobytes. The actual
+ limit will be up to <tt>incalloc</tt> entries or <tt>incmem</tt> kilobytes larger. As with all
+ of the <tt>mru</tt> options offered in units of entries or kilobytes, if both <tt>maxdepth</tt> and <tt>maxmem</tt> are used, the last one used controls. The default is 1024 kilobytes.</dd>
+ <dt><tt>mindepth <i>count</i></tt></dt>
+ <dd>Lower limit on the MRU list size. When the MRU list has fewer than <tt>mindepth</tt> entries,
+ existing entries are never removed to make room for newer ones, regardless of their age.
+ The default is 600 entries.</dd>
+ <dt><tt>maxage <i>seconds</i></tt></dt>
+ <dd>Once the MRU list has <tt>mindepth</tt> entries and an additional client address is to be added
+ to the list, if the oldest entry was updated more than <tt>maxage</tt> seconds ago, that entry
+ is removed and its storage reused. If the oldest entry was updated more recently, the MRU list
+ is grown, subject to <tt>maxdepth</tt>/<tt>maxmem</tt>. The default is 64 seconds.</dd>
+ <dt><tt>initalloc <i>count</i><br>
+ initmem <i>kilobytes</i></tt></dt>
+ <dd>Initial memory allocation at the time the monitoring facility is first enabled, in terms of
+ entries or kilobytes. The default is 4 kilobytes.</dd>
+ <dt><tt>incalloc <i>count</i><br>
+ incmem <i>kilobytes</i></tt></dt>
+ <dd>Size of additional memory allocations when growing the MRU list, in entries or kilobytes.
+ The default is 4 kilobytes.</dd>
+ </dl>
+ </dd>
+ <dt id="phone"><tt>phone <i>dial</i>1 <i>dial</i>2 ...</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="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>
+ <dd>This command adds an additional system variable. These variables can be used to distribute additional information such as the access policy. If the variable of the form <tt><i>name</i> = <i>value</i></tt> is followed by the <tt>default</tt> keyword, the variable will be listed as part of the default system variables (<tt>ntpq rv</tt> command). These additional variables serve informational purposes only. They are not related to the protocol other that they can be listed. The known protocol variables will always override any variables defined via the <tt>setvar</tt> mechanism. There are three special variables that contain the names of all variable of the same group. The <tt>sys_var_list</tt> holds the names of all system variables. The <tt>peer_var_list</tt> holds the names of all peer variables and the <tt>clock_var_list</tt> holds the names of the reference clock variables.</dd>
+ <dt id="tinker"><tt>tinker [ allan <i>allan</i> | dispersion <i>dispersion</i> | freq <i>freq</i> | huffpuff <i>huffpuff</i> | panic <i>panic</i> | step <i>step</i> | stepout <i>stepout</i> ]</tt></dt>
+ <dd>This command alters certain system variables used by the clock discipline algorithm. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. The options are as follows:</dd>
+ <dd>
+ <dl>
+ <dt><tt>allan <i>allan</i></tt></dt>
+ <dd>Specifies the Allan intercept, which is a parameter of the PLL/FLL clock discipline algorithm, in seconds with default 1500 s.</dd>
+ <dt><tt>dispersion <i>dispersion</i></tt></dt>
+ <dd>Specifies the dispersion increase rate in parts-per-million (PPM) with default 15 PPM.</dd>
+ <dt><tt>freq <i>freq</i></tt></dt>
+ <dd>Specifies the frequency offset in parts-per-million (PPM) with default the value in the frequency file.</dd>
+ <dt><tt>huffpuff <i>huffpuff</i></tt></dt>
+ <dd>Sp edifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours).</dd>
+ <dt><tt>panic <i>panic</i></tt></dt>
+ <dd>Sp edifies the panic threshold in seconds with default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted.</dd>
+ <dt><tt>step <i>step</i></tt></dt>
+ <dd>Sp edifies the step threshold in seconds. The default without this command
+ is 0.128 s. If set to zero, step adjustments will never
+ occur. Note: The kernel time discipline is disabled if
+ the step threshold is set to zero or greater than 0.5
+ s.</dd>
+ <dt><tt>stepout <i>stepout</i></tt></dt>
+ <dd>Specifies the stepout threshold in seconds. The default without this
+ command is 900 s. If set to zero, popcorn spikes will
+ not be suppressed.</dd>
+ </dl>
+ </dd>
+ <dt id="tos"><tt>tos [ beacon <i>beacon</i> | ceiling <i>ceiling</i> | cohort {0 | 1} | floor <i>floor</i> | maxclock <i>maxclock </i>| maxdist <i>maxdist</i> | minclock <i>minclock</i> | mindist <i>mindist </i>| minsane <i>minsane</i> | orphan <i>stratum</i> | orphanwait <em>delay</em> ]</tt></dt>
+ <dd>This command alters certain system variables used by the the clock selection and clustering algorithms. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs. It can be used to select the quality and quantity of peers used to synchronize the system clock and is most useful in dynamic server discovery schemes. The options are as follows:</dd>
+ <dd>
+ <dl>
+ <dt><tt>beacon <i>beacon</i></tt></dt>
+ <dd>The manycast server sends packets at intervals of 64 s if less than <tt>maxclock</tt> servers are available. Otherwise, it sends packets at the <i><tt>beacon</tt></i> interval in seconds. The default is 3600 s. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dt><tt>ceiling <i>ceiling</i></tt></dt>
+ <dd>Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dt><tt>cohort { 0 | 1 }</tt></dt>
+ <dd>Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dt><tt>floor <i>floor</i></tt></dt>
+ <dd>Specify the minimum stratum (inclusive) for acceptable server packets. The default is 1. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dt><tt>maxclock <i>maxclock</i></tt></dt>
+ <dd>Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dt><tt>maxdist <i>maxdistance</i></tt></dt>
+ <dd>Specify the synchronization distance threshold used by the clock selection algorithm. The default is 1.5 s. This determines both the minimum number of packets to set the system clock and the maximum roundtrip delay. It can be decreased to improve reliability or increased to synchronize clocks on the Moon or planets.</dd>
+ <dt><tt>minclock <i>minclock</i></tt></dt>
+ <dd>Specify the number of servers used by the clustering algorithm as the minimum to include on the candidate list. The default is 3. This is also the number of servers to be averaged by the combining algorithm.</dd>
+ <dt><tt>mindist <i>mindistance</i></tt></dt>
+ <dd>Specify the minimum distance used by the selection and anticlockhop
+ algorithm. Larger values increase the tolerance for outliers;
+ smaller values increase the selectivity. The default is .001 s. In some
+ cases, such as reference clocks with high jitter and a PPS signal, it is
+ useful to increase the value to insure the intersection interval is
+ always nonempty.</dd>
+ <dt><tt>minsane <i>minsane</i></tt></dt>
+ <dd>Specify the number of servers used by the selection algorithm as the minimum to set the system clock. The default is 1 for legacy purposes; however, for critical applications the value should be somewhat higher but less than <tt>minclock</tt>.</dd>
+ <dt><tt>orphan <i>stratum</i></tt></dt>
+ <dd>Specify the orphan stratum with default 16. If less than 16 this is the stratum assumed by the root servers. See the <a href="assoc.html">Association Management</a> page for further details.</dd>
+ <dt><tt>orphanwait <em>delay</em></tt></dt>
+ <dd> </dd>
+ <dd>Specify the delay in seconds from the time all sources are lost until orphan mode is enabled with default 500 s (five minutes). This allows time for one or more sources to be found without enabling orphan mode and later disabling it.</dd>
+ </dl>
+ </dd>
+ <dt id="trap"><tt>trap <i>host_address</i> [port <i>port_number</i>] [interface <i>interfSace_address</i>]</tt></dt>
+ <dd>This command configures a trap receiver at the given host address and port number for sending messages with the specified local interface address. If the port number is unspecified, a value of 18447 is used. If the interface address is not specified, the message is sent with a source address of the local interface the message is sent through. Note that on a multihomed host the interface used may vary from time to time with routing changes.</dd>
+ <dd>The trap receiver will generally log event messages and other information from the server in a log file. While such monitor programs may also request their own trap dynamically, configuring a trap receiver will ensure that no messages are lost when the server is started.</dd>
+ <dt id="ttl"><tt>ttl <i>hop</i> ...</tt></dt>
+ <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.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
<body>
-<h3>Monitoring Options</h3>
-<img src="pic/pogo8.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html"></a>
-from <i>Pogo</i>, Walt Kelly</a>
+<h3>Monitoring Commands and Options</h3>
+<img src="pic/pogo8.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html"></a> from <i>Pogo</i>, Walt Kelly</a>
<p>Pig was hired to watch the logs.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->14-Apr-2010 3:35<!-- #EndDate -->
- UTC</p>
+ <!-- #BeginDate format:En2m -->10-Sep-2010 0:29<!-- #EndDate -->
+ UTC</p>
<br clear="left">
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
<script type="text/javascript" language="javascript" src="scripts/monopt.txt"></script>
<h4>Table of Contents</h4>
<ul>
- <li class="inline"><a href="#intro">introduction</a></li>
- <li class="inline"><a href="#cmd">Monitoring Options</a></li>
-
<li class="inline"><a href="#types">File Set Types</a></li>
+ <li class="inline"><a href="#intro">Naming Conventions</a></li>
+ <li class="inline"><a href="#cmd">Monitoring Commands and Options</a></li>
+ <li class="inline"><a href="#types">File Set Types</a></li>
</ul>
<hr>
-<h4 id="intro">Introduction</h4>
+<h4 id="intro">Naming Conventions</h4>
<p>The <tt>ntpd</tt> includes a comprehensive monitoring facility which collects
- statistical data of various types and writes the data to files associated with
- each type at defined events or intervals. The files associated with a particular
- type are collectively called the generation file set for that type. The files
- in the file set are the members of that set.</p>
+ statistical data of various types and writes the data to files associated with
+ each type at defined events or intervals. The files associated with a particular
+ type are collectively called the generation file set for that type. The files
+ in the file set are the members of that set.</p>
<p>File sets have names specific to the type and generation epoch. The names
- are constructed from three concatenated elements <i><tt>prefix</tt></i>, <i><tt>filename</tt></i> and <i><tt>suffix</tt></i>:</p>
+ are constructed from three concatenated elements <i><tt>prefix</tt></i>, <i><tt>filename</tt></i> and <i><tt>suffix</tt></i>:</p>
<dl>
- <dt><i><tt>prefix</tt></i></dt>
- <dd>The directory path specified in the <tt>statsdir</tt> command.</dd>
- <dt><i><tt>name</tt></i></dt>
- <dd>The name specified by the <tt>file</tt> option of the <tt>filegen</tt> command.</dd>
- <dt><i><tt>suffix</tt></i></dt>
- <dd>A string of elements bdginning with . (dot) followed by a number of elements
- depending on the file set type.</dd>
+ <dt><i><tt>prefix</tt></i></dt>
+ <dd>The directory path specified in the <tt>statsdir</tt> command.</dd>
+ <dt><i><tt>name</tt></i></dt>
+ <dd>The name specified by the <tt>file</tt> option of the <tt>filegen</tt> command.</dd>
+ <dt><i><tt>suffix</tt></i></dt>
+ <dd>A string of elements bdginning with . (dot) followed by a number of elements
+ depending on the file set type.</dd>
</dl>
<p>Statistics files can be managed using scripts, examples of which are in the <tt>./scripts</tt> directory.
- Using these or similar scripts and Unix <tt>cron</tt> jobs, the files can be
- automatically summarized and archived for retrospective analysis.</p>
-<h4 id="cmd">Monitoring Commands</h4>
-<dl>
- <dt id="filegen"><tt>filegen <i>name</i> file <i>filename</i> [type <i>type</i>]
- [link | nolink] [enable | disable]</tt></dt>
- <dd>
- <dt><i><tt>name</tt></i></dt>
- <dd>Specifies the file set type from the list in the next section.</dd>
- <dt><tt>file <i>filename</i></tt></dt>
- <dd>Specfies the file set name.</dd>
- <dt><tt>type <i>typename</i></tt></dt>
- <dd>Specifies the file set interval. The following intervals are supported
- with default <tt>day</tt>:</dd>
- <dd>
- <dt><tt>none</tt></dt>
- <dd>The file set is actually a single plain file.</dd>
- <dt><tt>pid</tt></dt>
- <dd>One file set member is created for every incarnation of <tt>ntpd</tt>.
- The file name suffix is the string .<tt>n</tt>, where <tt>n</tt> is the
- process ID of the <tt>ntpd</tt> server process.</dd>
- <dt><tt>day</tt></dt>
- <dd>One file set member is created per day. A day is defined as the period
- between 00:00 and 23:59 UTC. The file name suffix is the string .<tt>yyyymmdd</tt>,
- where <tt>yyyy</tt> is the year, <tt>mm</tt> the month of the year and <tt>dd</tt> the
- day of the month. Thus, member created on 10 December 1992 would have suffix <tt>.19921210</tt>.</dd>
- <dt><tt>week</tt></dt>
- <dd>One file set member is created per week. The week is defined as the
- day of year modulo 7. The file name suffix is the string .<tt>yyyyWww</tt>,
- where <tt>yyyy</tt> is the year, <tt>W</tt> stands for itself and <tt>ww</tt> the
- week number starting from 0. For example, The member created on 10 January
- 1992 would have suffix <tt>.1992W1</tt>.</dd>
- <dt><tt>month</tt></dt>
- <dd>One file set member is created per month. The file name suffix is the
- string .<tt>yyyymm</tt>, where <tt>yyyy</tt> is the year and <tt>mm</tt> the
- month of the year starting from 1. For example, The member created on 10
- January 1992 would have suffix <tt>.199201</tt>.</dd>
- <dt><tt>year</tt></dt>
- <dd>One file set member is generated per year. The file name suffix is the
- string .<tt>yyyy</tt>, where <tt>yyyy</tt> is the year. For example, The
- member created on 1 January 1992 would have suffix <tt>.1992</tt>.</dd>
- <dt><tt>age</tt></dt>
- <dd>One file set member is generated every 24 hours of <tt>ntpd</tt> operation.
- The filename suffix is the string <tt>.adddddddd</tt>, where <tt>a</tt> stands
- for itself and <tt>dddddddd</tt> is the <tt>ntpd</tt> running time in seconds
- at the start of the corresponding 24-hour period.</dd>
- </dl>
- </dd>
- <dt><tt>link | nolink</tt></dt>
- <dd>It is convenient to be able to access the current file set members by
- file name, but without the suffix. This feature is enabled by <tt>link</tt> and
- disabled by <tt>nolink</tt>. If enabled, which is the default, a hard link
- from the current file set member to a file without suffix is created. When
- there is already a file with this name and the number of links to this file
- is one, it is renamed by appending a dot, the letter <tt>C</tt>, and the
- pid of the <tt>ntpd</tt> server process. When the number of links is greater
- than one, the file is unlinked. This allows the current file to be accessed
- by a constant name.</dd>
- <dt><tt>enable | disable</tt></dt>
- <dd>Enable or disable the recording function, with default <tt>enable</tt>.
- These options are intended for remote configutation commands.</dd>
- </dl>
- </dd>
- <dt><tt>statsdir <i>directory_path</i></tt></dt>
- <dd>Specify the directory path prefix for statistics file names.</dd>
+ Using these or similar scripts and Unix <tt>cron</tt> jobs, the files can be
+ automatically summarized and archived for retrospective analysis.</p>
+<h4 id="cmd">Monitoring Commands and Options</h4>
+<p>Unless noted otherwise, further information about these commands is on the <a href="decode.html">Event Messages and Status Codes</a> page.</p></a> page.</p><dl>
+ <dt id="filegen"><tt>filegen <i>name</i> file <i>filename</i> [type <i>type</i>]
+ [link | nolink] [enable | disable]</tt></dt>
+ <dd>
+ <dl>
+ <dt><i><tt>name</tt></i></dt>
+ <dd>Specifies the file set type from the list in the next section.</dd>
+ <dt><tt>file <i>filename</i></tt></dt>
+ <dd>Specfies the file set name.</dd>
+ <dt><tt>type <i>typename</i></tt></dt>
+ <dd>Specifies the file set interval. The following intervals are supported
+ with default <tt>day</tt>:</dd>
+ <dd>
+ <dl>
+ <dt><tt>none</tt></dt>
+ <dd>The file set is actually a single plain file.</dd>
+ <dt><tt>pid</tt></dt>
+ <dd>One file set member is created for every incarnation of <tt>ntpd</tt>.
+ The file name suffix is the string .<tt>n</tt>, where <tt>n</tt> is the
+ process ID of the <tt>ntpd</tt> server process.</dd>
+ <dt><tt>day</tt></dt>
+ <dd>One file set member is created per day. A day is defined as the period
+ between 00:00 and 23:59 UTC. The file name suffix is the string .<tt>yyyymmdd</tt>,
+ where <tt>yyyy</tt> is the year, <tt>mm</tt> the month of the year and <tt>dd</tt> the
+ day of the month. Thus, member created on 10 December 1992 would have suffix <tt>.19921210</tt>.</dd>
+ <dt><tt>week</tt></dt>
+ <dd>One file set member is created per week. The week is defined as the
+ day of year modulo 7. The file name suffix is the string .<tt>yyyyWww</tt>,
+ where <tt>yyyy</tt> is the year, <tt>W</tt> stands for itself and <tt>ww</tt> the
+ week number starting from 0. For example, The member created on 10 January
+ 1992 would have suffix <tt>.1992W1</tt>.</dd>
+ <dt><tt>month</tt></dt>
+ <dd>One file set member is created per month. The file name suffix is the
+ string .<tt>yyyymm</tt>, where <tt>yyyy</tt> is the year and <tt>mm</tt> the
+ month of the year starting from 1. For example, The member created on 10
+ January 1992 would have suffix <tt>.199201</tt>.</dd>
+ <dt><tt>year</tt></dt>
+ <dd>One file set member is generated per year. The file name suffix is the
+ string .<tt>yyyy</tt>, where <tt>yyyy</tt> is the year. For example, The
+ member created on 1 January 1992 would have suffix <tt>.1992</tt>.</dd>
+ <dt><tt>age</tt></dt>
+ <dd>One file set member is generated every 24 hours of <tt>ntpd</tt> operation.
+ The filename suffix is the string <tt>.adddddddd</tt>, where <tt>a</tt> stands
+ for itself and <tt>dddddddd</tt> is the <tt>ntpd</tt> running time in seconds
+ at the start of the corresponding 24-hour period.</dd>
+ </dl>
+ </dd>
+ <dt><tt>link | nolink</tt></dt>
+ <dd>It is convenient to be able to access the current file set members by
+ file name, but without the suffix. This feature is enabled by <tt>link</tt> and
+ disabled by <tt>nolink</tt>. If enabled, which is the default, a hard link
+ from the current file set member to a file without suffix is created. When
+ there is already a file with this name and the number of links to this file
+ is one, it is renamed by appending a dot, the letter <tt>C</tt>, and the
+ pid of the <tt>ntpd</tt> server process. When the number of links is greater
+ than one, the file is unlinked. This allows the current file to be accessed
+ by a constant name.</dd>
+ <dt><tt>enable | disable</tt></dt>
+ <dd>Enable or disable the recording function, with default <tt>enable</tt>.
+ These options are intended for remote configutation commands.</dd>
+ </dl>
+ </dd>
+ <dt><tt>statsdir <i>directory_path</i></tt></dt>
+ <dd>Specify the directory path prefix for statistics file names.</dd>
</dl>
<h4 id="types">File Set Types</h4>
<dl>
- <dt><tt>clockstats</tt></dt>
- <dd>Record reference clock statistics. Each update received from a reference
- clock driver appends one line to the <tt>clockstats</tt> file set:</dd>
- <dd><tt>49213 525.624 127.127.4.1 93 226 00:08:29.606 D</tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>49213</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>525.624</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>127.127.4.1</tt></td>
- <td>IP</td>
- <td>reference clock address</td>
- </tr>
- <tr>
- <td><tt><i>message</i></tt></td>
- <td>text</td>
- <td>log message</td>
- </tr>
- </table>
- </dd>
- <dd>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.</dd>
- <dt><tt>cryptostats</tt></dt>
- <dd>Record significant events in the Autokey protocol. This option requires
- the OpenSSL cryptographic software library. Each event appends one line to
- the <tt>cryptostats</tt> file set:</dd>
- <dd><tt>49213 525.624 128.4.1.1 <i>message</i></tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>49213</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>525.624</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>128.4.1.1</tt></td>
- <td>IP</td>
- <td>source address (<tt>0.0.0.0</tt> for system)</td>
- </tr>
- <tr>
- <td><tt><i>message</i></tt></td>
- <td>text</td>
- <td>log message</td>
- </tr>
- </table>
- </dd>
- <dd>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.</dd>
- <dt><tt>loopstats</tt></dt>
- <dd>Record clock discipline loop statistics. Each system clock update appends
- one line to the <tt>loopstats</tt> file set:</dd>
- <dd><tt>50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6</tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>50935</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>75440.031</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>0.000006019</tt></td>
- <td>s</td>
- <td>clock offset</td>
- </tr>
- <tr>
- <td><tt>13.778</tt></td>
- <td>PPM</td>
- <td>frequency offset</td>
- </tr>
- <tr>
- <td><tt>0.000351733</tt></td>
- <td>s</td>
- <td>RMS jitter</td>
- </tr>
- <tr>
- <td><tt>0.013380</tt></td>
- <td>PPM</td>
- <td>RMS frequency jitter (aka wander)</td>
- </tr>
- <tr>
- <td><tt>6 </tt></td>
- <td>log<sub>2</sub> s</td>
- <td>clock discipline loop time constant</td>
- </tr>
- </table>
- </dd>
- <dt><tt>peerstats</tt></dt>
- <dd>Record peer statistics. Each NTP packet or reference clock update received
- appends one line to the <tt>peerstats</tt> file set:</dd>
- <dd><tt>48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877
- 0.000958674</tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>48773</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>10847.650</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>127.127.4.1</tt></td>
- <td>IP</td>
- <td>source address</td>
- </tr>
- <tr>
- <td><tt>9714</tt></td>
- <td>hex</td>
- <td>status word</td>
- </tr>
- <tr>
- <td><tt>-0.001605376</tt></td>
- <td>s</td>
- <td>clock offset</td>
- </tr>
- <tr>
- <td><tt>0.000000000 </tt></td>
- <td>s</td>
- <td>roundtrip delay</td>
- </tr>
- <tr>
- <td><tt>0.001424877</tt></td>
- <td>s</td>
- <td>dispersion</td>
- </tr>
- <tr>
- <td><tt>0.000958674</tt></td>
- <td>s</td>
- <td>RMS jitter</td>
- </tr>
- </table>
- </dd>
- <dd>The status field is encoded in hex format as described in Appendix B of
- the NTP specification RFC 1305.</dd>
- <dt><tt>protostats</tt></dt>
- <dd>Record significant peer, system and [rptpcp; events. Each significant event
- appends one line to the <tt>protostats</tt> file set:</dd>
- <dd><tt>49213 525.624 128.4.1.1 963a 8a <i>message</i></tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>49213</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>525.624</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>128.4.1.1</tt></td>
- <td>IP</td>
- <td>source address (<tt>0.0.0.0</tt> for system)</td>
- </tr>
- <tr>
- <td><tt>963a</tt></td>
- <td>code</td>
- <td>status word</td>
- </tr>
- <tr>
- <td><tt>8a</tt></td>
- <td>code</td>
- <td>event message code</td>
- </tr>
- <tr>
- <td><tt><i>message</i></tt></td>
- <td>text</td>
- <td>event message</td>
- </tr>
- </table>
- </dd>
- <dd>The event message code and <tt><i>message</i></tt> field are described on
-
the <a href="decode.html">Event Messages and Status Words</a> page.</dd>
- <dt><tt>rawstats</tt></dt>
- <dd>Record timestamp statistics. Each NTP packet received appends one line to
- the <tt>rawstats</tt> file set:</dd>
- <dd><tt>50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031
- 02453332.540806000 3102453332.541458000</tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>50928</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>2132.543</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>128.4.1.1</tt></td>
- <td>IP</td>
- <td>source address</td>
- </tr>
- <tr>
- <td><tt>128.4.1.20</tt></td>
- <td>IP</td>
- <td>destination address</td>
- </tr>
- <tr>
- <td><tt>3102453281.584327000</tt></td>
- <td>NTP s</td>
- <td>origin timestamp</td>
- </tr>
- <tr>
- <td><tt>3102453281.586228000</tt></td>
- <td>NTP s</td>
- <td>receive timestamp</td>
- </tr>
- <tr>
- <td><tt>3102453332.540806000 </tt></td>
- <td>NTP s</td>
- <td>transmit timestamp</td>
- </tr>
- <tr>
- <td><tt>3102453332.541458000</tt></td>
- <td>NTP s</td>
- <td>destination timestamp</td>
- </tr>
- </table>
- </dd>
- <dt><tt>sysstats</tt></dt>
- <dd>Record system statistics. Each hour one line is appended to the <tt>sysstats</tt> file
- set in the following format:</dd>
- <dd><tt>50928 2132.543 3600 81965 0 9546 56 512 540 10 4 147 1</tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>50928</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>2132.543</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>3600</tt></td>
- <td>s</td>
- <td>time since reset</td>
- </tr>
- <tr>
- <td><tt>81965</tt></td>
- <td>#</td>
- <td>packets received</td>
- </tr>
- <tr>
- <td><tt>0</tt></td>
- <td>#</td>
- <td>packets for this host</td>
- </tr>
- <tr>
- <td><tt>9546</tt></td>
- <td>#</td>
- <td>current versions</td>
- </tr>
- <tr>
- <td><tt>56</tt></td>
- <td>#</td>
- <td>old version</td>
- </tr>
- <tr>
- <td><tt>512</tt></td>
- <td>#</td>
- <td>access denied</td>
- </tr>
- <tr>
- <td><tt>540</tt></td>
- <td>#</td>
- <td>bad length or format</td>
- </tr>
- <tr>
- <td><tt>10</tt></td>
- <td>#</td>
- <td>bad authentication</td>
- </tr>
- <tr>
- <td><tt>4</tt></td>
- <td>#</td>
- <td>declined</td>
- </tr>
- <tr>
- <td><tt>147</tt></td>
- <td>#</td>
- <td>rate exceeded</td>
- </tr>
- <tr>
- <td><tt>1</tt></td>
- <td>#</td>
- <td>kiss-o'-death packets sent</td>
- </tr>
- </table>
- </dd>
- <dt><tt>timingstats</tt></dt>
- <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>
- <dd><tt>53876 36.920 10.0.3.5 1 0.000014592 input processing delay</tt></dd>
- <dd>
-
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Item</td>
- <td>Units</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>53876</tt></td>
- <td>MJD</td>
- <td>date</td>
- </tr>
- <tr>
- <td><tt>36.920</tt></td>
- <td>s</td>
- <td>time past midnight</td>
- </tr>
- <tr>
- <td><tt>10.0.3.5</tt></td>
- <td>IP</td>
- <td>server address</td>
- </tr>
- <tr>
- <td><tt>1</tt></td>
- <td>#</td>
- <td>event count</td>
- </tr>
- <tr>
- <td><tt>0.000014592</tt></td>
- <td>s</td>
- <td>total time</td>
- </tr>
- <tr>
- <td><tt><i>message</i></tt></td>
- <td>text</td>
- <td>code path description (see source)</td>
- </tr>
- </table>
- </dd>
+ <dt><tt>clockstats</tt></dt>
+ <dd>Record reference clock statistics. Each update received from a reference
+ clock driver appends one line to the <tt>clockstats</tt> file set:</dd>
+ <dd><tt>49213 525.624 127.127.4.1 93 226 00:08:29.606 D</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>49213</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>525.624</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>127.127.4.1</tt></td>
+ <td>IP</td>
+ <td>reference clock address</td>
+ </tr>
+ <tr>
+ <td><tt><i>message</i></tt></td>
+ <td>text</td>
+ <td>log message</td>
+ </tr>
+ </table>
+ </dd>
+ <dd>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.</dd>
+ <dt><tt>cryptostats</tt></dt>
+ <dd>Record significant events in the Autokey protocol. This option requires
+ the OpenSSL cryptographic software library. Each event appends one line to
+ the <tt>cryptostats</tt> file set:</dd>
+ <dd><tt>49213 525.624 128.4.1.1 <i>message</i></tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>49213</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>525.624</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>128.4.1.1</tt></td>
+ <td>IP</td>
+ <td>source address (<tt>0.0.0.0</tt> for system)</td>
+ </tr>
+ <tr>
+ <td><tt><i>message</i></tt></td>
+ <td>text</td>
+ <td>log message</td>
+ </tr>
+ </table>
+ </dd>
+ <dd>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.</dd>
+ <dt><tt>loopstats</tt></dt>
+ <dd>Record clock discipline loop statistics. Each system clock update appends
+ one line to the <tt>loopstats</tt> file set:</dd>
+ <dd><tt>50935 75440.031 0.000006019 13.778 0.000351733 0.013380 6</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>50935</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>75440.031</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>0.000006019</tt></td>
+ <td>s</td>
+ <td>clock offset</td>
+ </tr>
+ <tr>
+ <td><tt>13.778</tt></td>
+ <td>PPM</td>
+ <td>frequency offset</td>
+ </tr>
+ <tr>
+ <td><tt>0.000351733</tt></td>
+ <td>s</td>
+ <td>RMS jitter</td>
+ </tr>
+ <tr>
+ <td><tt>0.013380</tt></td>
+ <td>PPM</td>
+ <td>RMS frequency jitter (aka wander)</td>
+ </tr>
+ <tr>
+ <td><tt>6 </tt></td>
+ <td>log<sub>2</sub> s</td>
+ <td>clock discipline loop time constant</td>
+ </tr>
+ </table>
+ </dd>
+ <dt><tt>peerstats</tt></dt>
+ <dd>Record peer statistics. Each NTP packet or reference clock update received
+ appends one line to the <tt>peerstats</tt> file set:</dd>
+ <dd><tt>48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877
+ 0.000958674</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>48773</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>10847.650</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>127.127.4.1</tt></td>
+ <td>IP</td>
+ <td>source address</td>
+ </tr>
+ <tr>
+ <td><tt>9714</tt></td>
+ <td>hex</td>
+ <td>status word</td>
+ </tr>
+ <tr>
+ <td><tt>-0.001605376</tt></td>
+ <td>s</td>
+ <td>clock offset</td>
+ </tr>
+ <tr>
+ <td><tt>0.000000000 </tt></td>
+ <td>s</td>
+ <td>roundtrip delay</td>
+ </tr>
+ <tr>
+ <td><tt>0.001424877</tt></td>
+ <td>s</td>
+ <td>dispersion</td>
+ </tr>
+ <tr>
+ <td><tt>0.000958674</tt></td>
+ <td>s</td>
+ <td>RMS jitter</td>
+ </tr>
+ </table>
+ </dd>
+ <dd>The status field is encoded in hex format as described in Appendix B of
+ the NTP specification RFC 1305.</dd>
+ <dt><tt>protostats</tt></dt>
+ <dd>Record significant peer, system and [rptpcp; events. Each significant event
+ appends one line to the <tt>protostats</tt> file set:</dd>
+ <dd><tt>49213 525.624 128.4.1.1 963a 8a <i>message</i></tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>49213</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>525.624</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>128.4.1.1</tt></td>
+ <td>IP</td>
+ <td>source address (<tt>0.0.0.0</tt> for system)</td>
+ </tr>
+ <tr>
+ <td><tt>963a</tt></td>
+ <td>code</td>
+ <td>status word</td>
+ </tr>
+ <tr>
+ <td><tt>8a</tt></td>
+ <td>code</td>
+ <td>event message code</td>
+ </tr>
+ <tr>
+ <td><tt><i>message</i></tt></td>
+ <td>text</td>
+ <td>event message</td>
+ </tr>
+ </table>
+ </dd>
+ <dd>The event message code and <tt><i>message</i></tt> field are described on
+ the <a href="decode.html">Event Messages and Status Words</a> page.</dd>
+ <dt><tt>rawstats</tt></dt>
+ <dd>Record timestamp statistics. Each NTP packet received appends one line to
+ the <tt>rawstats</tt> file set:</dd>
+ <dd><tt>50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031
+ 02453332.540806000 3102453332.541458000</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>50928</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>2132.543</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>128.4.1.1</tt></td>
+ <td>IP</td>
+ <td>source address</td>
+ </tr>
+ <tr>
+ <td><tt>128.4.1.20</tt></td>
+ <td>IP</td>
+ <td>destination address</td>
+ </tr>
+ <tr>
+ <td><tt>3102453281.584327000</tt></td>
+ <td>NTP s</td>
+ <td>origin timestamp</td>
+ </tr>
+ <tr>
+ <td><tt>3102453281.586228000</tt></td>
+ <td>NTP s</td>
+ <td>receive timestamp</td>
+ </tr>
+ <tr>
+ <td><tt>3102453332.540806000 </tt></td>
+ <td>NTP s</td>
+ <td>transmit timestamp</td>
+ </tr>
+ <tr>
+ <td><tt>3102453332.541458000</tt></td>
+ <td>NTP s</td>
+ <td>destination timestamp</td>
+ </tr>
+ </table>
+ </dd>
+ <dt><tt>sysstats</tt></dt>
+ <dd>Record system statistics. Each hour one line is appended to the <tt>sysstats</tt> file
+ set in the following format:</dd>
+ <dd><tt>50928 2132.543 3600 81965 0 9546 56 512 540 10 4 147 1</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>50928</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>2132.543</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>3600</tt></td>
+ <td>s</td>
+ <td>time since reset</td>
+ </tr>
+ <tr>
+ <td><tt>81965</tt></td>
+ <td>#</td>
+ <td>packets received</td>
+ </tr>
+ <tr>
+ <td><tt>0</tt></td>
+ <td>#</td>
+ <td>packets for this host</td>
+ </tr>
+ <tr>
+ <td><tt>9546</tt></td>
+ <td>#</td>
+ <td>current versions</td>
+ </tr>
+ <tr>
+ <td><tt>56</tt></td>
+ <td>#</td>
+ <td>old version</td>
+ </tr>
+ <tr>
+ <td><tt>512</tt></td>
+ <td>#</td>
+ <td>access denied</td>
+ </tr>
+ <tr>
+ <td><tt>540</tt></td>
+ <td>#</td>
+ <td>bad length or format</td>
+ </tr>
+ <tr>
+ <td><tt>10</tt></td>
+ <td>#</td>
+ <td>bad authentication</td>
+ </tr>
+ <tr>
+ <td><tt>4</tt></td>
+ <td>#</td>
+ <td>declined</td>
+ </tr>
+ <tr>
+ <td><tt>147</tt></td>
+ <td>#</td>
+ <td>rate exceeded</td>
+ </tr>
+ <tr>
+ <td><tt>1</tt></td>
+ <td>#</td>
+ <td>kiss-o'-death packets sent</td>
+ </tr>
+ </table>
+ </dd>
+ <dt><tt>timingstats</tt></dt>
+ <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>
+ <dd><tt>53876 36.920 10.0.3.5 1 0.000014592 input processing delay</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Item</td>
+ <td>Units</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>53876</tt></td>
+ <td>MJD</td>
+ <td>date</td>
+ </tr>
+ <tr>
+ <td><tt>36.920</tt></td>
+ <td>s</td>
+ <td>time past midnight</td>
+ </tr>
+ <tr>
+ <td><tt>10.0.3.5</tt></td>
+ <td>IP</td>
+ <td>server address</td>
+ </tr>
+ <tr>
+ <td><tt>1</tt></td>
+ <td>#</td>
+ <td>event count</td>
+ </tr>
+ <tr>
+ <td><tt>0.000014592</tt></td>
+ <td>s</td>
+ <td>total time</td>
+ </tr>
+ <tr>
+ <td><tt><i>message</i></tt></td>
+ <td>text</td>
+ <td>code path description (see source)</td>
+ </tr>
+ </table>
+ </dd>
</dl>
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpd System Log Messages</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
- <body>
- <h3><tt>ntpd</tt> System Log Messages</h3>
- <img src="pic/flatheads.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>The log can be shrill at times.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">02:22</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="252">Monday, March 03, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <p><script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
- </p>
- <hr>
- <p>You have come here because you found a cryptic message in the system log. This page by no means lists all messages that might be found, since new ones come and old ones go. Generally, however, the most common ones will be found here. They are listed by program module and log severity code in bold: <tt><b>LOG_ERR</b></tt>, <b><tt>LOG_NOTICE</tt></b> and <tt><b>LOG_INFO</b></tt>.</p>
- <p>Most of the time <b><tt>LOG_ERR</tt></b> messages are fatal, but often <tt>ntpd</tt> limps onward in the hopes of discovering more errors. The <tt><b>LOG_NOTICE</b></tt> messages usually mean the time has changed or some other condition that probably should be noticed. The <tt><b>LOG_INFO</b></tt> messages usually say something about the system operations, but do not affect the time.</p>
- <p>In the following a '?' character stands for text in the message. The meaning should be clear from context.</p>
- <h4>Protocol Module</h4>
- <p><tt><b>LOG_ERR</b></tt></p>
- <dl>
- <dt><tt>buffer overflow ?
- </tt>
- <dd>Fatal error. An input packet is too long for processing.
- </dl>
- <p><tt><b>LOG_NOTICE</b></tt></p>
- <dl>
- <dt><tt>no reply; clock not set</tt>
- <dd>In <tt>ntpdate</tt> mode no servers have been found. The server(s) and/or network may be down. Standard debugging procedures apply.
- <p><tt><b>LOG_INFO</b></tt></p>
- <dt><tt>proto_config: illegal item ?, value ?</tt>
- <dd>Program error. Bugs can be reported <a href="bugs.html">here</a>.
- <dt><tt>receive: autokey requires two-way communication</tt>
- <dd>Configuration error on the <tt>broadcastclient</tt> command.
- <dt><tt>receive: server <i>server</i> maaximum rate exceeded</tt>
- <dd>A kiss-o'death packet has been received. The transmit rate is automatically reduced.<dt><tt>pps sync enabled</tt>
- <dd>The PPS signal has been detected and enabled.
- <dt><tt>transmit: encryption key ? not found</tt>
- <dd>The encryption key is not defined or not trusted.
- <dt><tt>precision = ? usec </tt>
- <dd>This reports the precision measured for this machine.
- <dt><tt>using 10ms tick adjustments</tt>
- <dd>Gotcha for some machines with dirty rotten clock hardware.
- <dt><tt>no servers reachable</tt>
- <dd>The system clock is running on internal batteries. The server(s) and/or network may be down.
- </dl>
- <h4>Clock Discipline Module</h4>
- <p><tt><b>LOG_ERR</b></tt></p>
- <dl>
- <dt><tt>time correction of ? seconds exceeds sanity limit (?); set clock manually to the correct UTC time</tt>.
- <dd>Fatal error. Better do what it says, then restart the daemon. Be advised NTP and Unix know nothing about local time zones. The clock must be set to Coordinated Universal Time (UTC). Believe it; by international agreement abbreviations are in French and descriptions are in English.
- <dt><tt>sigaction() fails to save SIGSYS trap: ?<br>
- </tt><tt>sigaction() fails to restore SIGSYS trap: ?</tt>
- <dt>Program error. Bugs can be reported <a href="bugs.html">here</a>.
- </dl>
- <p><tt><b>LOG_NOTICE</b></tt></p>
- <dl>
- <dt><tt>frequency error ? exceeds tolerance 500 PPM</tt>
- <dd>The hardware clock frequency error exceeds the rate the kernel can correct. This could be a hardware or a kernel problem.
- <dt><tt>time slew ? s</tt>
- <dd>The time error exceeds the step threshold and is being slewed to the correct time. You may have to wait a very long time.
- <dt><tt>time reset ? s</tt>
- <dd>The time error exceeds the step threshold and has been reset to the correct time. Computer scientists don't like this, but they can set the <tt>ntpd -x</tt> option and wait forever.
- <dt><tt>kernel time sync disabled ?</tt>
- <dd>The kernel reports an error. See the codes in the <tt>timex.h</tt> file.
- <dt><tt>pps sync disabled</tt>
- <dd>The PPS signal has died, probably due to a dead radio, broken wire or loose connector.
- </dl>
- <p><tt><b>LOG_INFO</b></tt></p>
- <dl>
- <dt><tt>kernel time sync status ? </tt>
- <dd>For information only. See the codes in the <tt>timex.h</tt> file.
- </dl>
- <h4>Cryptographic Module</h4>
- <p><tt><b>LOG_ERR</b></tt></p>
- <dl>
- <dt><tt>cert_parse ?<br>
- </tt><tt>cert_sign ?<br>
- </tt><tt>crypto_cert ?<br>
- </tt><tt>crypto_encrypt ?<br>
- </tt><tt>crypto_gq ?<br>
- </tt><tt>crypto_iff ?<br>
- </tt><tt>crypto_key ?<br>
- </tt><tt>crypto_mv ?<br>
- </tt><tt>crypto_setup ?<br>
- </tt><tt>make_keys ?</tt>
- <dd>Usually fatal errors. These messages display error codes returned from the OpenSSL library. See the OpenSSL documentation for explanation.
- <dt><tt>crypto_setup: certificate ? is trusted, but not self signed.<br>
- </tt><tt>crypto_setup: certificate ? not for this host<br>
- </tt><tt>crypto_setup: certificate file ? not found or corrupt<br>
- </tt><tt>crypto_setup: host key file ? not found or corrupt<br>
- </tt><tt>crypto_setup: host key is not RSA key type<br>
- </tt><tt>crypto_setup: random seed file ? not found<br>
- </tt><tt>rypto_setup: random seed file not specified</tt>
- <dd>Fatal errors. These messages show problems during the initialization procedure.
- </dl>
- <p><tt><b>LOG_INFO</b></tt></p>
- <dl>
- <dt><tt>cert_parse: expired ?<br>
- </tt><tt>cert_parse: invalid issuer ?<br>
- </tt><tt>cert_parse: invalid signature ?<br>
- </tt><tt>cert_parse: invalid subject ?</tt>
- <dd>There is a problem with a certificate. Operation cannot proceed untill the problem is fixed. If the certificate is local, it can be regenerated using the <tt>ntp-keygen</tt> program. If it is held somewhere else, it must be fixed by the holder.
- <dt><tt>crypto_?: defective key<br>
- </tt><tt>crypto_?: invalid filestamp<br>
- </tt><tt>crypto_?: missing challenge<br>
- </tt><tt>crypto_?: scheme unavailable</tt>
- <dd>There is a problem with the identity scheme. Operation cannot proceed untill the problem is fixed. Usually errors are due to misconfiguration or an orphan association. If the latter, <tt>ntpd</tt> will usually time out and recover by itself.
- <dt><tt>crypto_cert: wrong PEM type ?</tt>
- <dd>The certificate does not have MIME type <tt>CERTIFICATE</tt>. You are probably using the wrong type from OpenSSL or an external certificate authority.
- <dt><tt>crypto_ident: no compatible identity scheme found</tt>
- <dd>Configuration error. The server and client identity schemes are incompatible.
- <dt><tt>crypto_tai: kernel TAI update failed</tt>
- <dd>The kernel does not support this function. You may need a new kernel or patch.
- <dt><tt>crypto_tai: leapseconds file ? error ?</tt>
- <dd>The leapseconds file is corrupt. Obtain the latest file from <tt>time.nist.gov</tt>.
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpd System Log Messages</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntpd</tt> System Log Messages</h3>
+<img src="pic/flatheads.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>The log can be shrill at times.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 0:54<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+</p>
+<hr>
+<p>You have come here because you found a cryptic message in the system log. This page by no means lists all messages that might be found, since new ones come and old ones go. Generally, however, the most common ones will be found here. They are listed by program module and log severity code in bold: <tt><b>LOG_ERR</b></tt>, <b><tt>LOG_NOTICE</tt></b> and <tt><b>LOG_INFO</b></tt>.</p>
+<p>Most of the time <b><tt>LOG_ERR</tt></b> messages are fatal, but often <tt>ntpd</tt> limps onward in the hopes of discovering more errors. The <tt><b>LOG_NOTICE</b></tt> messages usually mean the time has changed or some other condition that probably should be noticed. The <tt><b>LOG_INFO</b></tt> messages usually say something about the system operations, but do not affect the time.</p>
+<p>In the following a '?' character stands for text in the message. The meaning should be clear from context.</p>
+<h4>Protocol Module</h4>
+<p><tt><b>LOG_ERR</b></tt></p>
+<dl>
+ <dt><tt>buffer overflow ? </tt></dt>
+ <dd>Fatal error. An input packet is too long for processing.</dd>
+</dl>
+<p><tt><b>LOG_NOTICE</b></tt></p>
+<dl>
+ <dt><tt>no reply; clock not set</tt></dt>
+ <dd>In <tt>ntpdate</tt> mode no servers have been found. The server(s) and/or network may be down. Standard debugging procedures apply.</dd>
+</dl>
+<p><tt><b>LOG_INFO</b></tt></p>
+<dl>
+ <dt><tt>proto_config: illegal item ?, value ?</tt></dt>
+ <dd>Program error. Bugs can be reported <a href="bugs.html">here</a>.</dd>
+ <dt><tt>receive: autokey requires two-way communication</tt></dt>
+ <dd>Configuration error on the <tt>broadcastclient</tt> command.</dd>
+ <dt><tt>receive: server <i>server</i> maaximum rate exceeded</tt></dt>
+ <dd>A kiss-o'death packet has been received. The transmit rate is automatically reduced.</dd>
+ <dt><tt>pps sync enabled</tt></dt>
+ <dd>The PPS signal has been detected and enabled.</dd>
+ <dt><tt>transmit: encryption key ? not found</tt></dt>
+ <dd>The encryption key is not defined or not trusted.</dd>
+ <dt><tt>precision = ? usec </tt></dt>
+ <dd>This reports the precision measured for this machine.</dd>
+ <dt><tt>using 10ms tick adjustments</tt></dt>
+ <dd>Gotcha for some machines with dirty rotten clock hardware.</dd>
+ <dt><tt>no servers reachable</tt></dt>
+ <dd>The system clock is running on internal batteries. The server(s) and/or network may be down.</dd>
+</dl>
+<h4>Clock Discipline Module</h4>
+<p><tt><b>LOG_ERR</b></tt></p>
+<dl>
+ <dt><tt>time correction of ? seconds exceeds sanity limit (?); set clock manually to the correct UTC time</tt>.</dt>
+ <dd>Fatal error. Better do what it says, then restart the daemon. Be advised NTP and Unix know nothing about local time zones. The clock must be set to Coordinated Universal Time (UTC). Believe it; by international agreement abbreviations are in French and descriptions are in English.</dd>
+ <dt><tt>sigaction() fails to save SIGSYS trap: ?<br>
+ </tt><tt>sigaction() fails to restore SIGSYS trap: ?</tt></dt>
+ <dt>Program error. Bugs can be reported <a href="bugs.html">here</a>.</dt>
+</dl>
+<p><tt><b>LOG_NOTICE</b></tt></p>
+<dl>
+ <dt><tt>frequency error ? exceeds tolerance 500 PPM</tt></dt>
+ <dd>The hardware clock frequency error exceeds the rate the kernel can correct. This could be a hardware or a kernel problem.</dd>
+ <dt><tt>time slew ? s</tt></dt>
+ <dd>The time error exceeds the step threshold and is being slewed to the correct time. You may have to wait a very long time.</dd>
+ <dt><tt>time reset ? s</tt></dt>
+ <dd>The time error exceeds the step threshold and has been reset to the correct time. Computer scientists don't like this, but they can set the <tt>ntpd -x</tt> option and wait forever.</dd>
+ <dt><tt>kernel time sync disabled ?</tt></dt>
+ <dd>The kernel reports an error. See the codes in the <tt>timex.h</tt> file.</dd>
+ <dt><tt>pps sync disabled</tt></dt>
+ <dd>The PPS signal has died, probably due to a dead radio, broken wire or loose connector.</dd>
+</dl>
+<p><tt><b>LOG_INFO</b></tt></p>
+<dl>
+ <dt><tt>kernel time sync status ? </tt></dt>
+ <dd>For information only. See the codes in the <tt>timex.h</tt> file.</dd>
+</dl>
+<h4>Cryptographic Module</h4>
+<p><tt><b>LOG_ERR</b></tt></p>
+<dl>
+ <dt><tt>cert_parse ?<br>
+ </tt><tt>cert_sign ?<br>
+ </tt><tt>crypto_cert ?<br>
+ </tt><tt>crypto_encrypt ?<br>
+ </tt><tt>crypto_gq ?<br>
+ </tt><tt>crypto_iff ?<br>
+ </tt><tt>crypto_key ?<br>
+ </tt><tt>crypto_mv ?<br>
+ </tt><tt>crypto_setup ?<br>
+ </tt><tt>make_keys ?</tt></dt>
+ <dd>Usually fatal errors. These messages display error codes returned from the OpenSSL library. See the OpenSSL documentation for explanation.</dd>
+ <dt><tt>crypto_setup: certificate ? is trusted, but not self signed.<br>
+ </tt><tt>crypto_setup: certificate ? not for this host<br>
+ </tt><tt>crypto_setup: certificate file ? not found or corrupt<br>
+ </tt><tt>crypto_setup: host key file ? not found or corrupt<br>
+ </tt><tt>crypto_setup: host key is not RSA key type<br>
+ </tt><tt>crypto_setup: random seed file ? not found<br>
+ </tt><tt>rypto_setup: random seed file not specified</tt></dt>
+ <dd>Fatal errors. These messages show problems during the initialization procedure.</dd>
+</dl>
+<p><tt><b>LOG_INFO</b></tt></p>
+<dl>
+ <dt><tt>cert_parse: expired ?<br>
+ </tt><tt>cert_parse: invalid issuer ?<br>
+ </tt><tt>cert_parse: invalid signature ?<br>
+ </tt><tt>cert_parse: invalid subject ?</tt></dt>
+ <dd>There is a problem with a certificate. Operation cannot proceed untill the problem is fixed. If the certificate is local, it can be regenerated using the <tt>ntp-keygen</tt> program. If it is held somewhere else, it must be fixed by the holder.</dd>
+ <dt><tt>crypto_?: defective key<br>
+ </tt><tt>crypto_?: invalid filestamp<br>
+ </tt><tt>crypto_?: missing challenge<br>
+ </tt><tt>crypto_?: scheme unavailable</tt></dt>
+ <dd>There is a problem with the identity scheme. Operation cannot proceed untill the problem is fixed. Usually errors are due to misconfiguration or an orphan association. If the latter, <tt>ntpd</tt> will usually time out and recover by itself.</dd>
+ <dt><tt>crypto_cert: wrong PEM type ?</tt></dt>
+ <dd>The certificate does not have MIME type <tt>CERTIFICATE</tt>. You are probably using the wrong type from OpenSSL or an external certificate authority.</dd>
+ <dt><tt>crypto_ident: no compatible identity scheme found</tt></dt>
+ <dd>Configuration error. The server and client identity schemes are incompatible.</dd>
+ <dt><tt>crypto_tai: kernel TAI update failed</tt></dt>
+ <dd>The kernel does not support this function. You may need a new kernel or patch.</dd>
+ <dt><tt>crypto_tai: leapseconds file ? error ?</tt></dt>
+ <dd>The leapseconds file is corrupt. Obtain the latest file from <tt>time.nist.gov</tt>.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Configuration File Definition (Advanced)</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Configuration File Definition (Advanced)</h3>
- <img src="pic/pogo7.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>Racoon is shooting configuration bugs.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">02:20</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="252">Monday, March 03, 2008</csobj></p>
- <br clear="left">
- <hr>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#synopsis">Synopsis</a><br>
- <li class="inline"><a href="#files">Files</a>
- <li class="inline"><a href="#high-level">High-Level Description</a>
- <li class="inline"><a href="#detailed">Detailed Description</a>
- <li class="inline"><a href="#guidelines">Guidelines for Adding Configuration Commands </a>
- </ul>
- <h4 id="synopsis">Synopsis</h4>
- <p>The NTP configuration process is driven by a phrase-structure grammar which is used to specify the format of the configuration commands and the actions needed to build an abstract syntax tree (AST). The grammar is fed to a parser generator (Bison) which produces a parser for the configuration file.</p>
- <p>The generated parser is used to parse an NTP configuration file and check it for syntax and semantic errors. The result of the parse is an AST, which contains a representation of the various commands and options. This AST is then traversed to set up the NTP daemon to the correct configuration.</p>
- <p>This document is intended for developers who wish to modify the configuration code and/or add configuration commands and options. It contains a description of the files used in the configuration process as well as guidelines on how to construct them.</p>
- <h4 id="files">Files</h4>
- <p>A brief description of the files used by the configuration code is given below:</p>
- <table border="1">
- <tbody>
- <tr>
- <th width="179">File</th>
- <th width="537">Description</th>
- </tr>
- <tr>
- <td valign="top"><b>ntp_config.y</b></td>
- <td>This file is a Bison source file that contains the phrase-structure grammar and the actions that need to be performed to generate an AST.</td>
- </tr>
- <tr>
- <td valign="top"><b>ntp_config.c</b></td>
- <td>This file contains the major chunk of the configuration code. It contains all the functions that are called for building the AST as well as the functions that are needed for traversing the AST.</td>
- </tr>
- <tr>
- <td valign="top"><b>ntp_config.h</b></td>
- <td>This file is the header file for <b>ntp_config.c</b>. It mainly contains the structure definitions needed to build the AST. </td>
- </tr>
- <tr>
- <td valign="top"><b>ntp_scanner.c</b></td>
- <td>This file contains the code for a simple lexical analyzer. This file is directly included into the <b>ntp_config.c</b> file since this code is only used by the configuration code. The most important function in this file is <tt>yylex</tt>, which is called by the generated parser to get the next token on the input line.</td>
- </tr>
- <tr>
- <td valign="top"><b>ntp_data_structures.c</b></td>
- <td>This file contains a generic implementation of a priority queue and a simple queue. This code can be used to create a queue for any structure.</td>
- </tr>
- <tr>
- <td valign="top"><b>ntp_data_structures.h</b></td>
- <td>This header file contains the structure declarations and function prototypes needed to use the data structures defined in <b>ntp_data_structures.c</b>. This file forms the public interface of the data structures.</td>
- </tr>
- <tr>
- <td valign="top"><b>ntp_config.tab.c</b></td>
- <td>This file is generated by Bison from the <b>ntp_config.y</b> file. This file is also included directly into the configuration code.</td>
- </tr>
- </tbody>
- </table>
- <h4 id="high-level">High-Level Description</h4>
- <p>A high-level description of the configuration process showing where all the files fit in is given below:</p>
- <p><img src="pic/description.jpg" alt="JPEG" border="0"></p>
- <p>The scanner reads in an NTP configuration file and converts it into tokens. The Bison generated parser reads these tokens and converts them into an AST. The AST traverser consists of a set of functions that configure parts of NTP on the basis of what is on the tree. A more detailed description of these parts and the files used is given below:</p>
- <h4 id="detailed">Detailed Description</h4>
- <dl>
- <dt><b>ntp_scanner.c</b>
- <dd>This file contains the scanner. The scanner is a small program that converts an input NTP configuration file into a set of <b>tokens</b> that correspond to <b>lexemes</b> in the input. Lexemes are strings in the input, delimited by whitespace and/or special characters. Tokens are basically unique integers that represent these lexemes. A different token is generated for each reserved word and special character in the input. There are two main functions in the public interface of this file:
- <dt><tt>int yylex</tt>()
- <dd>This function is called <tt>yylex</tt> for historical reasons; <tt>lex</tt> is a program that takes a set of regular expressions and generates a scanner that returns tokens corresponding to those regular expressions. The name of the generated function is called <tt>yylex</tt>. We aren't using<b> </b><tt>lex</tt><b> </b>because it requires linking against an external library and we didn't want to increase the compile-time requirements of NTP.
- <dd>History lessons aside, this function basically checks to see if the next input character is a special character as defined in the array <tt>char special_char[]</tt>. (The function <tt>int is_special(char ch)</tt>, can be used for this.) If yes, the special character is returned as the token. If not, a set of characters is read until the next whitespace or special character is encountered. This set of characters forms the lexeme; <tt>yylex</tt> then checks whether this lexeme is an integer, a double, an IP address or a reserved word. If yes, the corresponding token is returned. If not, a token for a string is returned as the default token.
- <dt><tt>struct state *create_keyword_scanner(struct key_tok *<i>keyword_list</i>)</tt>
- <dd>This function takes a list of (<i>keyword, token</i>) pairs and converts them into a trie that can recognize the keywords (reserved words). Every time the scanner reads a lexeme, it compares it against the list of reserved words. If it finds a match, it returns the corresponding token for that keyword.
- <dt><b>ntp_data_structures.c</b>
- <dd>This file contains an implementation of a generic priority queue and FIFO queue. By generic, we mean that these queues can hold element of any type (integers, user-defined structs, etc.), provided that these elements are allocated on the heap using the function <tt>void</tt> *<tt>get_node(size_t size)</tt>. Note that the prototype for this function is exactly the same as that of <tt>malloc</tt> and that it can be used in the exact same way. Behind the scenes, <tt>get_node</tt> calls <tt>malloc</tt> to allocate <i>size</i> plus some extra memory needed for bookkeeping. The allocated memory can be freed using the function <tt>void free_node (void *<i>my_node</i>)</tt>. In addition to these two functions, the public interface of this file contains the following functions:
- <dt><tt>queue *create_priority_queue(int (*get_order)(void *, void*))</tt>
- <dd>This function creates a priority queue in which the order of the elements is determined by the <tt>get_order</tt><b> </b>function that is passed as input to the priority queue. The <tt>get_order</tt><b> </b>function should return positive if the priority of the first element is less than the priority of the second element.
- <dt><tt>queue *create_queue(void)</tt>
- <dd>This function creates a FIFO queue. It basically calls the <tt>create_priority_queue</tt> function with the <tt>get_fifo_order</tt><b> </b>function as its argument.
- <dt><tt>void destroy_queue(queue *<i>my_queue</i>)</tt>
- <dd>This function deletes <tt><i>my_queue</i></tt><b> </b>and frees up all the memory allocated to it an its elements.
- <dt><tt>int empty(queue *</tt><i><tt>my_queue</tt></i><tt>)</tt>
- <dd>This function checks to see if <i><tt>my_queue</tt></i> is empty. Returns <tt>true</tt> if <tt><i>my_queue</i></tt> does not have any elements, else it returns false.
- <dt><tt>queue *enqueue(queue *<i>my_queue</i>, void *<i>my_node</i>)</tt>
- <dd>This function adds an element, <i><tt>my_node</tt></i>, to a queue, <i><tt>my_queue</tt></i>. <i><tt>my_node</tt></i> must be allocated on the heap using the <tt>get_node</tt> function instead of <tt>malloc</tt>.
- <dt><tt>void *dequeue(queue *<i>my_queue</i>)</tt>
- <dd>This function returns the element at the front of the queue. This element will be element with the highest priority.
- <dt><tt>int get_no_of_elements(queue *<i>my_queue</i>)</tt>
- <dd>This function returns the number of elements in <tt><i>my_queue</i></tt>.
- <dt><tt>void append_queue(queue *<i>q</i>1, queue *<i>q</i>2)</tt>
- <dd>This function adds all the elements of <tt><i>q</i>2</tt> to <tt><i>q</i>1</tt>. The queue <tt><i>q</i>2</tt> is destroyed in the process.
- <dt><b>ntp_config.y</b>
- <dd>This file is structured as a standard Bison file and consists of three main parts, separated by <tt>%%</tt>:
- </dl>
- <ol>
- <li>The prologue and bison declarations: This section contains a list of the terminal symbols, the non-terminal symbols and the types of these symbols.</li>
- <li>The rules section: This section contains a description of the actual phrase-structure rules that are used to parse the configuration commands. Each rule consists of a left-hand side (LHS), a right-hand side (RHS) and an optional action. As is standard with phrase-structure grammars, the LHS consists of a single non-terminal symbol. The RHS can contain both terminal and non-terminal symbols, while the optional action can consist of any arbitrary C code.</li>
- <li>The epilogue: This section is left empty on purpose. It is traditionally used to code the support functions needed to build the ASTs Since, we have moved all the support functions to <b>ntp_config.c</b>, this section is left empty.</li>
- </ol>
- <h4>Prologue and Bison Declarations</h4>
- <p>All the terminal symbols (also known as tokens) have to be declared in the prologue section. Note that terminals and non-terminals may have values associated with them and these values have types. (More on this later). An unnamed union has to be declared with all the possible types at the start of the prologue section. For example, we declare the following union at the start of the <b>ntp_config.y</b> file:</p>
- <p class="style1"><tt>%union {<br>
- char *String;<br>
- double Double;<br>
- int Integer;<br>
- void *VoidPtr;<br>
- queue *Queue;<br>
- struct attr_val *Attr_val;<br>
- struct address_node *Address_node;<br>
- struct setvar_node *Set_var;<br>
- /* Simulation types */<br>
- server_info *Sim_server;<br>
- script_info *Sim_script;<br>
- }</tt></p>
- <p>Some tokens may not have any types. For example, tokens that correspond to reserved words do not usually have types as they simply indicate that a reserved word has been read in the input file. Such tokens have to be declared as follows:</p>
- <p><tt>%token T_Discard<br>
- %token T_Dispersion</tt></p>
- <p>Other tokens do have types. For example, a <tt>T_Double</tt> token is returned by the scanner whenever it sees a floating-point double in the configuration file. The value associated with the token is the actual number that was read in the configuration file and its type (after conversion) is double. Hence, the token <tt>T_Double</tt> will have to be declared as follows in the prologue of <b>ntp_config.y</b> file:</p>
- <p><tt>%token <Double> T_Double </tt></p>
- <p>Note that the declaration given in the angled brackets is not <tt>double</tt> but <tt>Double</tt>, which is the name of the variable given in the <tt>%union {}</tt> declaration above.</p>
- <p>Finally, non-terminal symbols may also have values associated with them, which have types. This is because Bison allows non-terminal symbols to have actions associated with them. Actions may be thought of as small functions which get executed whenever the RHS of a non-terminal is detected. The return values of these functions are the values associated with the non-terminals. The types of the non-terminals are specified with a <tt>%type</tt> declaration as shown below:</p>
- <p><tt>%type <Queue> address_list<br>
- %type <Integer> boolean</tt></p>
- <p>The <tt>%type</tt> declaration may be omitted for non-terminals that do not return any value and do not have type information associated with them.</p>
- <h4>The Rules Section </h4>
- <p>The rule section only consists of phrase-structure grammar rules. Each rule typically has the following format:</p>
- <p><tt>LHS : RHS [{ Actions }]<br>
- ;</tt></p>
- <p>where LHS consists of a single non-terminal symbol and the RHS consists of one or more terminal and non-terminal symbols. The <tt>Actions</tt> are optional and may consist of any number of arbitrary C statements. Note that Bison can only process LALR(1) grammars, which imposes additional restrictions on the kind of rules that can be specified. Examples of rules are shown below:</p>
- <p><tt>orphan_mode_command<br>
- : T_Tos tos_option_list<br>
- { append_queue(my_config.orphan_cmds, $2); }<br>
- ;</tt></p>
- <p><tt>tos_option_list<br>
- : tos_option_list tos_option { $$ = enqueue($1, $2); }<br>
- | tos_option { $$ = enqueue_in_new_queue($1); }<br>
- ;</tt></p>
- <p>The <tt>$n</tt> notation, where <tt>n</tt> is an integer, is used to refer to the value of a terminal or non-terminal symbol. All terminals and non-terminal symbols within a particular rule are numbered (starting from 1) according to the order in which they appear within the RHS of a rule. <tt>$$</tt> is used to refer to the value of the LHS terminal symbol - it is used to return a value for the non-terminal symbol specified in the LHS of the rule.</p>
- <h4>Invoking Bison </h4>
- <p>Bison needs to be invoked in order to convert the <b>ntp_config.y</b> file into a C source file. To invoke Bison, simply enter the command:</p>
- <p><tt>bison ntp_config.y</tt></p>
- <p>at the command prompt. If no errors are detected, an <b>ntp_config.tab.c</b> file will be generated by default. This generated file can be directly included into the <b>ntp_config.c</b> file.</p>
- <p>If Bison report shift-reduce errors or reduce-reduce errors, it means that the grammar specified using the rules in not LALR(1). To debug such a grammar, invoke Bison with a <tt>-v</tt> switch, as shown below. This will generate a <b>ntp_config.output</b> file, which will contain a description of the generated state machine, together with a list of states that have shift-reduce/reduce-reduce conflicts. You can then change the rules to remove such conflicts.</p>
- <p><tt>bison -v ntp_config.y</tt></p>
- <p>For more information, refer to the <a href="http://www.gnu.org/software/bison/manual/html_mono/bison.html">Bison manual</a>.</p>
- <p><b>ntp_config.c</b></p>
- <p>This file contains the major chunk of the configuration code including all the support functions needed for building and traversing the ASTs. As such, most of the functions in this file can be divided into two groups:</p>
- <ol>
- <li>Functions that have a <tt>create_</tt> prefix. These functions are used to build a node of the AST.</li>
- <li>Functions that have a <tt>config_</tt> prefix. These functions are used to traverse the AST and configure NTP according to the nodes present on the tree.</li>
- </ol>
- <h4>Guidelines for Adding Configuration Commands</h4>
- <p>The following steps may be used to add a new configuration command to the NTP reference implementation:</p>
- <ol>
- <li>Write phrase-structure grammar rules for the syntax of the new command. Add these rules to the rules section of the <b>ntp_config.y</b> file. </li>
- <li>Write the action to be performed on recognizing the rules. These actions will be used to build the AST.</li>
- <li>If new reserved words are needed, add these to the <tt>struct key_tok keyword_list[]</tt>structure in the <b>ntp_config.c </b>file. This will allow the scanner to recognize these reserved words and generate the desired tokens on recognizing them.</li>
- <li>Specify the types of all the terminals and non-terminal symbols in the prologue section of the <b>ntp_config.c</b> file.</li>
- <li>Write a function with a <tt>config_</tt> prefix that will be executed for this new command. Make sure this function is called in the <tt>config_ntpd()</tt>function.</li>
- </ol>
- <hr>
- <address><a href="mailto:skamboj@udel.edu">Sachin Kamboj</a></address>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Configuration File Definition (Advanced)</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Configuration File Definition (Advanced)</h3>
+<img src="pic/pogo7.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>Racoon is shooting configuration bugs.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 1:13<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<hr>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#synopsis">Synopsis</a></li>
+ <li class="inline"><a href="#files">Files</a></li>
+ <li class="inline"><a href="#high-level">High-Level Description</a></li>
+ <li class="inline"><a href="#detailed">Detailed Description</a></li>
+ <li class="inline"><a href="#guidelines">Guidelines for Adding Configuration Commands </a></li>
+</ul>
+<h4 id="synopsis">Synopsis</h4>
+<p>The NTP configuration process is driven by a phrase-structure grammar which is used to specify the format of the configuration commands and the actions needed to build an abstract syntax tree (AST). The grammar is fed to a parser generator (Bison) which produces a parser for the configuration file.</p>
+<p>The generated parser is used to parse an NTP configuration file and check it for syntax and semantic errors. The result of the parse is an AST, which contains a representation of the various commands and options. This AST is then traversed to set up the NTP daemon to the correct configuration.</p>
+<p>This document is intended for developers who wish to modify the configuration code and/or add configuration commands and options. It contains a description of the files used in the configuration process as well as guidelines on how to construct them.</p>
+<h4 id="files">Files</h4>
+<p>A brief description of the files used by the configuration code is given below:</p>
+<table border="1">
+ <tbody>
+ <tr>
+ <th width="179">File</th>
+ <th width="537">Description</th>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_config.y</b></td>
+ <td>This file is a Bison source file that contains the phrase-structure grammar and the actions that need to be performed to generate an AST.</td>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_config.c</b></td>
+ <td>This file contains the major chunk of the configuration code. It contains all the functions that are called for building the AST as well as the functions that are needed for traversing the AST.</td>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_config.h</b></td>
+ <td>This file is the header file for <b>ntp_config.c</b>. It mainly contains the structure definitions needed to build the AST. </td>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_scanner.c</b></td>
+ <td>This file contains the code for a simple lexical analyzer. This file is directly included into the <b>ntp_config.c</b> file since this code is only used by the configuration code. The most important function in this file is <tt>yylex</tt>, which is called by the generated parser to get the next token on the input line.</td>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_data_structures.c</b></td>
+ <td>This file contains a generic implementation of a priority queue and a simple queue. This code can be used to create a queue for any structure.</td>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_data_structures.h</b></td>
+ <td>This header file contains the structure declarations and function prototypes needed to use the data structures defined in <b>ntp_data_structures.c</b>. This file forms the public interface of the data structures.</td>
+ </tr>
+ <tr>
+ <td valign="top"><b>ntp_config.tab.c</b></td>
+ <td>This file is generated by Bison from the <b>ntp_config.y</b> file. This file is also included directly into the configuration code.</td>
+ </tr>
+ </tbody>
+</table>
+<h4 id="high-level">High-Level Description</h4>
+<p>A high-level description of the configuration process showing where all the files fit in is given below:</p>
+<p><img src="pic/description.jpg" alt="JPEG" border="0"></p>
+<p>The scanner reads in an NTP configuration file and converts it into tokens. The Bison generated parser reads these tokens and converts them into an AST. The AST traverser consists of a set of functions that configure parts of NTP on the basis of what is on the tree. A more detailed description of these parts and the files used is given below:</p>
+<h4 id="detailed">Detailed Description</h4>
+<dl>
+ <dt><b>ntp_scanner.c</b></dt>
+ <dd>This file contains the scanner. The scanner is a small program that converts an input NTP configuration file into a set of <b>tokens</b> that correspond to <b>lexemes</b> in the input. Lexemes are strings in the input, delimited by whitespace and/or special characters. Tokens are basically unique integers that represent these lexemes. A different token is generated for each reserved word and special character in the input. There are two main functions in the public interface of this file:</dd>
+ <dt><tt>int yylex</tt>()</dt>
+ <dd>This function is called <tt>yylex</tt> for historical reasons; <tt>lex</tt> is a program that takes a set of regular expressions and generates a scanner that returns tokens corresponding to those regular expressions. The name of the generated function is called <tt>yylex</tt>. We aren't using<b> </b><tt>lex</tt><b> </b>because it requires linking against an external library and we didn't want to increase the compile-time requirements of NTP.</dd>
+ <dd>History lessons aside, this function basically checks to see if the next input character is a special character as defined in the array <tt>char special_char[]</tt>. (The function <tt>int is_special(char ch)</tt>, can be used for this.) If yes, the special character is returned as the token. If not, a set of characters is read until the next whitespace or special character is encountered. This set of characters forms the lexeme; <tt>yylex</tt> then checks whether this lexeme is an integer, a double, an IP address or a reserved word. If yes, the corresponding token is returned. If not, a token for a string is returned as the default token.</dd>
+ <dt><tt>struct state *create_keyword_scanner(struct key_tok *<i>keyword_list</i>)</tt></dt>
+ <dd>This function takes a list of (<i>keyword, token</i>) pairs and converts them into a trie that can recognize the keywords (reserved words). Every time the scanner reads a lexeme, it compares it against the list of reserved words. If it finds a match, it returns the corresponding token for that keyword.</dd>
+ <dt><b>ntp_data_structures.c</b></dt>
+ <dd>This file contains an implementation of a generic priority queue and FIFO queue. By generic, we mean that these queues can hold element of any type (integers, user-defined structs, etc.), provided that these elements are allocated on the heap using the function <tt>void</tt> *<tt>get_node(size_t size)</tt>. Note that the prototype for this function is exactly the same as that of <tt>malloc</tt> and that it can be used in the exact same way. Behind the scenes, <tt>get_node</tt> calls <tt>malloc</tt> to allocate <i>size</i> plus some extra memory needed for bookkeeping. The allocated memory can be freed using the function <tt>void free_node (void *<i>my_node</i>)</tt>. In addition to these two functions, the public interface of this file contains the following functions:</dd>
+ <dt><tt>queue *create_priority_queue(int (*get_order)(void *, void*))</tt></dt>
+ <dd>This function creates a priority queue in which the order of the elements is determined by the <tt>get_order</tt><b> </b>function that is passed as input to the priority queue. The <tt>get_order</tt><b> </b>function should return positive if the priority of the first element is less than the priority of the second element.</dd>
+ <dt><tt>queue *create_queue(void)</tt></dt>
+ <dd>This function creates a FIFO queue. It basically calls the <tt>create_priority_queue</tt> function with the <tt>get_fifo_order</tt><b> </b>function as its argument.</dd>
+ <dt><tt>void destroy_queue(queue *<i>my_queue</i>)</tt></dt>
+ <dd>This function deletes <tt><i>my_queue</i></tt><b> </b>and frees up all the memory allocated to it an its elements.</dd>
+ <dt><tt>int empty(queue *</tt><i><tt>my_queue</tt></i><tt>)</tt></dt>
+ <dd>This function checks to see if <i><tt>my_queue</tt></i> is empty. Returns <tt>true</tt> if <tt><i>my_queue</i></tt> does not have any elements, else it returns false.</dd>
+ <dt><tt>queue *enqueue(queue *<i>my_queue</i>, void *<i>my_node</i>)</tt></dt>
+ <dd>This function adds an element, <i><tt>my_node</tt></i>, to a queue, <i><tt>my_queue</tt></i>. <i><tt>my_node</tt></i> must be allocated on the heap using the <tt>get_node</tt> function instead of <tt>malloc</tt>.</dd>
+ <dt><tt>void *dequeue(queue *<i>my_queue</i>)</tt></dt>
+ <dd>This function returns the element at the front of the queue. This element will be element with the highest priority.</dd>
+ <dt><tt>int get_no_of_elements(queue *<i>my_queue</i>)</tt></dt>
+ <dd>This function returns the number of elements in <tt><i>my_queue</i></tt>.</dd>
+ <dt><tt>void append_queue(queue *<i>q</i>1, queue *<i>q</i>2)</tt></dt>
+ <dd>This function adds all the elements of <tt><i>q</i>2</tt> to <tt><i>q</i>1</tt>. The queue <tt><i>q</i>2</tt> is destroyed in the process.</dd>
+ <dt><b>ntp_config.y</b></dt>
+ <dd>This file is structured as a standard Bison file and consists of three main parts, separated by <tt>%%</tt>:</dd>
+</dl>
+<ol>
+ <li>The prologue and bison declarations: This section contains a list of the terminal symbols, the non-terminal symbols and the types of these symbols.</li>
+ <li>The rules section: This section contains a description of the actual phrase-structure rules that are used to parse the configuration commands. Each rule consists of a left-hand side (LHS), a right-hand side (RHS) and an optional action. As is standard with phrase-structure grammars, the LHS consists of a single non-terminal symbol. The RHS can contain both terminal and non-terminal symbols, while the optional action can consist of any arbitrary C code.</li>
+ <li>The epilogue: This section is left empty on purpose. It is traditionally used to code the support functions needed to build the ASTs Since, we have moved all the support functions to <b>ntp_config.c</b>, this section is left empty.</li>
+</ol>
+<h4>Prologue and Bison Declarations</h4>
+<p>All the terminal symbols (also known as tokens) have to be declared in the prologue section. Note that terminals and non-terminals may have values associated with them and these values have types. (More on this later). An unnamed union has to be declared with all the possible types at the start of the prologue section. For example, we declare the following union at the start of the <b>ntp_config.y</b> file:</p>
+<p class="style1"><tt>%union {<br>
+ char *String;<br>
+ double Double;<br>
+ int Integer;<br>
+ void *VoidPtr;<br>
+ queue *Queue;<br>
+ struct attr_val *Attr_val;<br>
+ struct address_node *Address_node;<br>
+ struct setvar_node *Set_var;<br>
+ /* Simulation types */<br>
+ server_info *Sim_server;<br>
+ script_info *Sim_script;<br>
+ }</tt></p>
+<p>Some tokens may not have any types. For example, tokens that correspond to reserved words do not usually have types as they simply indicate that a reserved word has been read in the input file. Such tokens have to be declared as follows:</p>
+<p><tt>%token T_Discard<br>
+ %token T_Dispersion</tt></p>
+<p>Other tokens do have types. For example, a <tt>T_Double</tt> token is returned by the scanner whenever it sees a floating-point double in the configuration file. The value associated with the token is the actual number that was read in the configuration file and its type (after conversion) is double. Hence, the token <tt>T_Double</tt> will have to be declared as follows in the prologue of <b>ntp_config.y</b> file:</p>
+<p><tt>%token <Double> T_Double </tt></p>
+<p>Note that the declaration given in the angled brackets is not <tt>double</tt> but <tt>Double</tt>, which is the name of the variable given in the <tt>%union {}</tt> declaration above.</p>
+<p>Finally, non-terminal symbols may also have values associated with them, which have types. This is because Bison allows non-terminal symbols to have actions associated with them. Actions may be thought of as small functions which get executed whenever the RHS of a non-terminal is detected. The return values of these functions are the values associated with the non-terminals. The types of the non-terminals are specified with a <tt>%type</tt> declaration as shown below:</p>
+<p><tt>%type <Queue> address_list<br>
+ %type <Integer> boolean</tt></p>
+<p>The <tt>%type</tt> declaration may be omitted for non-terminals that do not return any value and do not have type information associated with them.</p>
+<h4>The Rules Section </h4>
+<p>The rule section only consists of phrase-structure grammar rules. Each rule typically has the following format:</p>
+<p><tt>LHS : RHS [{ Actions }]<br>
+ ;</tt></p>
+<p>where LHS consists of a single non-terminal symbol and the RHS consists of one or more terminal and non-terminal symbols. The <tt>Actions</tt> are optional and may consist of any number of arbitrary C statements. Note that Bison can only process LALR(1) grammars, which imposes additional restrictions on the kind of rules that can be specified. Examples of rules are shown below:</p>
+<p><tt>orphan_mode_command<br>
+ : T_Tos tos_option_list<br>
+ { append_queue(my_config.orphan_cmds, $2); }<br>
+ ;</tt></p>
+<p><tt>tos_option_list<br>
+ : tos_option_list tos_option { $$ = enqueue($1, $2); }<br>
+ | tos_option { $$ = enqueue_in_new_queue($1); }<br>
+ ;</tt></p>
+<p>The <tt>$n</tt> notation, where <tt>n</tt> is an integer, is used to refer to the value of a terminal or non-terminal symbol. All terminals and non-terminal symbols within a particular rule are numbered (starting from 1) according to the order in which they appear within the RHS of a rule. <tt>$$</tt> is used to refer to the value of the LHS terminal symbol - it is used to return a value for the non-terminal symbol specified in the LHS of the rule.</p>
+<h4>Invoking Bison </h4>
+<p>Bison needs to be invoked in order to convert the <b>ntp_config.y</b> file into a C source file. To invoke Bison, simply enter the command:</p>
+<p><tt>bison ntp_config.y</tt></p>
+<p>at the command prompt. If no errors are detected, an <b>ntp_config.tab.c</b> file will be generated by default. This generated file can be directly included into the <b>ntp_config.c</b> file.</p>
+<p>If Bison report shift-reduce errors or reduce-reduce errors, it means that the grammar specified using the rules in not LALR(1). To debug such a grammar, invoke Bison with a <tt>-v</tt> switch, as shown below. This will generate a <b>ntp_config.output</b> file, which will contain a description of the generated state machine, together with a list of states that have shift-reduce/reduce-reduce conflicts. You can then change the rules to remove such conflicts.</p>
+<p><tt>bison -v ntp_config.y</tt></p>
+<p>For more information, refer to the <a href="http://www.gnu.org/software/bison/manual/html_mono/bison.html">Bison manual</a>.</p>
+<p><b>ntp_config.c</b></p>
+<p>This file contains the major chunk of the configuration code including all the support functions needed for building and traversing the ASTs. As such, most of the functions in this file can be divided into two groups:</p>
+<ol>
+ <li>Functions that have a <tt>create_</tt> prefix. These functions are used to build a node of the AST.</li>
+ <li>Functions that have a <tt>config_</tt> prefix. These functions are used to traverse the AST and configure NTP according to the nodes present on the tree.</li>
+</ol>
+<h4>Guidelines for Adding Configuration Commands</h4>
+<p>The following steps may be used to add a new configuration command to the NTP reference implementation:</p>
+<ol>
+ <li>Write phrase-structure grammar rules for the syntax of the new command. Add these rules to the rules section of the <b>ntp_config.y</b> file. </li>
+ <li>Write the action to be performed on recognizing the rules. These actions will be used to build the AST.</li>
+ <li>If new reserved words are needed, add these to the <tt>struct key_tok keyword_list[]</tt>structure in the <b>ntp_config.c </b>file. This will allow the scanner to recognize these reserved words and generate the desired tokens on recognizing them.</li>
+ <li>Specify the types of all the terminals and non-terminal symbols in the prologue section of the <b>ntp_config.c</b> file.</li>
+ <li>Write a function with a <tt>config_</tt> prefix that will be executed for this new command. Make sure this function is called in the <tt>config_ntpd()</tt>function.</li>
+</ol>
+<hr>
+<address>
+<a href="mailto:skamboj@udel.edu">Sachin Kamboj</a>
+</address>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpd - Network Time Protocol (NTP) daemon</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntpd</tt> - Network Time Protocol (NTP) Daemon</h3>
- <img src="pic/wingdorothy.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
- <p>You need help from the monkeys.</p>
- <p>Last update: <!-- #BeginDate format:En1m -->14-oct-09 22:23<!-- #EndDate --></p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpd - Network Time Protocol (NTP) daemon</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntpd</tt> - Network Time Protocol (NTP) Daemon</h3>
+<img src="pic/wingdorothy.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
+<p>You need help from the monkeys.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->06-Sep-2010 18:50<!-- #EndDate -->
+UTC</p>
<br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#synop">Synopsis</a></li>
- <li class="inline"><a href="#descr">Description</a></li>
- <li class="inline"><a href="#time">Setting the Time and Frequency</a></li>
- <li class="inline"><a href="#modes">Operating Modes</a></li>
- <li class="inline"><a href="#poll">Poll Interval Control</a></li>
- <li class="inline"><a href="#leap">Leap Second Processing</a></li>
- <li class="inline"><a href="#notes">Additional Features</a></li>
- <li class="inline"><a href="#cmd">Command Line Options</a></li>
- <li class="inline"><a href="#cfg">The Configuration File</a></li>
- <li class="inline"><a href="#files">Files</a></li>
- </ul>
- <hr>
- <h4 id="synop">Synopsis</h4>
- <tt>ntpd [ -46aAbdDgLmnNqx ] [ -c <i>conffile</i> ] [ -f <i>driftfile</i> ] [ -i <i>jaildir</i> ] [ -k <i>keyfile</i> ] [ -l <i>logfile</i> ] [ -p <i>pidfile</i> ] [ -P <i>priority</i> ] [ -r <i>broadcastdelay</i> ] [ -s <i>statsdir</i> ] [ -t <i>key</i> ] [ -u <i>user</i>[:<i>group</i>] ] [ -U <i>interface_update_interval</i> ] [ -v <i>variable</i> ] [ -V <i>variable</i> ]</tt>
- <h4 id="descr">Description</h4>
- <p>The <tt>ntpd</tt> program is an operating system daemon that synchronises the system clock with remote NTP time servers or local reference clocks. It is a complete implementation of the Network Time Protocol (NTP) version 4, but also retains compatibility with version 3, as defined by RFC-1305, and version 1 and 2, as defined by RFC-1059 and RFC-1119, respectively. The program can operate in any of several modes, as described on the <a href="assoc.html">Association Management</a> page, and with both symmetric key and public key cryptography, as described on the <a href="manyopt.html">Authentication Options</a> page.</p>
- <p>The <tt>ntpd</tt> program ordinarily requires a configuration file as desccribe on the Configuration Commands and Options collection above. However a client can discover remote servers and configure them automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. Further details are on the <a href="manyopt.html">Automatic Server Discovery</a> page.</p>
- <p>Once the NTP software distribution has been compiled and installed and the configuration file constructed, the next step is to verify correct operation and fix any bugs that may result. Usually, the command line that starts the daemon is included in the system startup file, so it is executed only at system boot time; however, the daemon can be stopped and restarted from root at any time. Once started, the daemon will begin sending and receiving messages, as specified in the configuration file.</p>
- <h4 id="time">Setting the Time and Frequency</h4>
- <p>The <tt>ntpd</tt> program operates by exchanging messages with one or more servers at designated intervals ranging from about one minute to about 17 minutes. When started, the program requires several exchanges while the algorithms accumulate and groom the data before setting the clock. The initial delay to set the clock can be reduced using options on the <a href="confopt.html">Server Options</a> page.</p>
- <p>Most compters today incorporate a time-of-year (TOY) chip to maintain the time during periods when the power is off. When the machine is booted, the chip is used to initialize the operating system time. In case there is no TOY chip or the TOY time is more than 1000 s from the server time, <tt>ntpd</tt> assumes something must be terribly wrong and exits with a panic message to the system operator. With the <tt>-g</tt> option the clock will be initially set to the server time regardless of the chip time. However, once the clock has been set, an error greater than 1000 s will cause <tt>ntpd</tt> to exit anyway.</p>
- <p>Under ordinary conditions, <tt>ntpd</tt> slews the clock so that the time is effectively continuous and never runs backwards. If due to extreme network congestion an error spike exceeds the <i>step threshold</i>, by default 128 ms, the spike is discarded. However, if the error persists for more than the <i>stepout threshold</i>, by default 900 s, the system clock is stepped to the correct value. In practice the need for a step has is extremely rare and almost always the result of a hardware failure. With the <tt>-x</tt> option the step threshold is increased to 600 s. Other options are available using the <tt>tinker</tt> command on the <a href="miscopt.html">Miscellaneous Options</a> page.</p>
- <p>The issues should be carefully considered before using these options. The maximum slew rate possible is limited to 500 parts-per-million (PPM) by the Unix kernel. As a result, the clock can take 2000 s for 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>
- <p>The frequency file, usually called <tt>ntp.drift</tt>, contains the latest estimate of clock frequency. If this file does not exist when <tt>ntpd</tt> is started, it enters a special mode designed to measure the particular frequency directly. The measurement takes 15 minutes, after which the frequency is set and <tt>ntpd</tt> resumes normal mode where the time and frequency are continuously adjusted. The frequency file is updated at intervals of an hour or more depending on the measured clock stability.</p>
- <h4 id="modes">Operating Modes</h4>
- <p>The <tt>ntpd</tt> program normally operates continuously while adjusting the time and frequency, but in some cases it may not be practical to run it continuously. With the <tt>-q</tt> option <tt>ntpd</tt> operates as in continous mode, but exits just after setting the clock for the first time. Most applications will probably want to specify the <tt>iburst</tt> option with the <tt>server</tt> command. With this option a volley of messages is exchanged to groom the data and set the clock in about 10 s. If nothing is heard after a few minutes, the daemon times out and exits.</p>
- <h4 id="poll">Poll Interval Control</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.</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 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>
- <h4 id="huff">The huff-n'-puff Filter</h4>
- <p>In scenarios where a considerable amount of data are to be downloaded or uploaded over telephone modems, timekeeping quality can be seriously degraded. This occurs because the differential delays on the two directions of transmission can be quite large. In many cases the apparent time errors are so large as to exceed the step threshold and a step correction can occur during and after the data transfer.</p>
- <p>The huff-n'-puff filter is designed to correct the apparent time offset in these cases. It depends on knowledge of the propagation delay when no other traffic is present, such as during other than work hours. The filter remembers the minimum delay over the most recent interval measured usually in hours. Under conditions of severe delay, the filter corrects the apparent offset using the sign of the offset and the difference between the apparent delay and minimum delay. The name of the filter reflects the negative (huff) and positive (puff) correction, which depends on the sign of the offset. The filter is activated by the <tt>tinker huffpuff</tt> command, as described in the <a href="miscopt.html">Miscellaneous Options</a> page.</p>
- <h4 id="leap">Leap Second Processing</h4>
- <p>As provided by international agreement, an extra second is sometimes inserted
- in Coordinated Universal Time (UTC) at the end of a selected month,
- usually June or December. The National Institutes of Standards and
- Technology (NIST) provides an historic leapseconds file at <tt>time.nist.gov</tt> for
- retrieval via FTP. When this file, usually called <tt>ntp-leapseconds.list</tt>,
- is copied and installed in a directory.
- The <tt>leapfile</tt> configuration command specifies the path to
- this file. At startup, <tt>ntpd</tt> reads
- it and initializes three leapsecond values: the NTP seconds
- at the next leap event, the offset of UTC relative to International
- Atomic Time (TAI) after the leap and the NTP seconds when the leapseconds
- file expires and should be retrieved again.</p>
- <p>If a host does not have the leapsecond values, they can be obtained over the net using the Autokey security protocol. Ordinarily, the leapseconds file is installed on the primary servers and the values flow from them via secondary servers to the clients. When multiple servers are involved, the values with the latest expiration time are used.</p>
- <p>If the latest leap is in the past, nothing further is done other than to install the TAI offset. If the leap is in the future less than 28 days, the leap warning bits are set. If in the future less than 23 hours, the kernel is armed to insert one second at the end of the current day. If the kernel is enabled, the leap is done automatically at that time; otherwise, the clock is effectively stopped for one second at the leap. Additional details are in the <a href='http://www.eecis.udel.edu/~mills/leap.html'>The NTP Timescale and Leap Seconds</a> white paper</p>
- <p>If none of the above provisions are available, dsependent servers and clients
- tally the leap warning bits of surviving servers and reference clocks.
- When a majority of the survivors show warning, a leap is programmed
- at the end of the current month. During the month and day of insertion,
- they operate as above. In this way the leap is is propagated at all
- dependent servers and clients.</p>
- <h4 id="notes">Additional Features</h4>
- <p>A new experimental feature called interleaved modes can be used in NTP
- symmetric or broadcast modes. It is designed to improve accuracy
- by avoiding kernel latency and queueing delay, as described on the <a href="xleave.html">NTP
- Interleaved Modes</a> page. It is activated by the <tt>xleave</tt> option
- with the <tt>peer</tt> or <tt>broadcast</tt> configuration commands. The NTP
- protocol automatically reconfigures in normal or interleaved mode
- as required. Ordinary broadcast clients can use the same servers
- as interleaved clients at the same time. Further details are in the
- white paper <a href="http://www.eecis.udel.edu/~mills/onwire.html">NTP
- Interleaved On-Wire Protocol</a> and the briefing <a href="http://www.eecis.udel.edu/~mills/database/brief/onwire/onwire.ppt">Interleaved
- Synchronization Protocols for LANs and Space Data Links</a>.</p>
- <p>If <tt>ntpd</tt>, is configured with NetInfo support, it will attempt to read its configuration from the NetInfo service if the default <tt>ntp.conf</tt> file cannot be read and no file is specified by the <tt>-c</tt> option.</p>
- <p>In contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
- <p>Various internal <tt>ntpd</tt> variables can be displayed and configuration options altered while the <tt>ntpd</tt> is running using the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs.</p>
- <p>When <tt>ntpd</tt> starts it looks at the value of <tt>umask</tt>, and if zero <tt>ntpd</tt> will set the <tt>umask</tt> to <tt>022</tt>.</p>
- <h4 id="cmd">Command Line Options</h4>
- <dl>
- <dt><tt>-a</tt></dt>
- <dd>Require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the same operation as the <tt>enable auth</tt> command and is the default.</dd>
- <dt><tt>-A</tt></dt>
- <dd>Do not require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the same operation as the <tt>disable auth</tt> command and almost never a good idea.</dd>
- <dt><tt>-b</tt></dt>
- <dd>Enable the client to synchronize to broadcast servers.</dd>
- <dt><tt>-c <i>conffile</i></tt></dt>
- <dd>Specify the name and path of the configuration file, default <tt>/etc/ntp.conf</tt>.</dd>
- <dt><tt>-d</tt></dt>
- <dd>Specify debugging mode. This option may occur more than once, with each occurrence indicating greater detail of display.</dd>
- <dt><tt>-D <i>level</i></tt></dt>
- <dd>Specify debugging level directly.</dd>
- <dt><tt>-f <i>driftfile</i></tt></dt>
- <dd>Specify the name and path of the frequency file, default <tt>/etc/ntp.drift</tt>. This is the same operation as the <tt>driftfile <i>driftfile</i></tt> command.</dd>
- <dt><tt>-g</tt></dt>
- <dd>Normally, <tt>ntpd</tt> exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, <tt>ntpd</tt> will exit with a message to the system log. This option can be used with the <tt>-q</tt> and <tt>-x</tt> options. See the <tt>tinker</tt> command for other options.</dd>
- <dt><tt>-i <i>jaildir</i></tt></dt>
- <dd>Chroot the server to the directory <i><tt>jaildir</tt></i>. This option also implies that the server attempts to drop root privileges at startup (otherwise, chroot gives very little additional security), and it is only available if the OS supports to run the server without full root privileges. You may need to also specify a <tt>-u</tt> option.</dd>
- <dt id="--interface"><tt>-I [<i>address</i> | <i>interface name</i>]</tt></dt>
- <dd>Open the network address given, or all the addresses associated with the given interface name. This option may appear multiple times. This option also implies not opening other addresses, except wildcard and localhost. This option is deprecated. Please consider using the configuration file <a href="miscopt.html#interface">interface</a> command, which is more versatile.</dd>
- <dt><tt>-k <i>keyfile</i></tt></dt>
- <dd>Specify the name and path of the symmetric key file, default <tt>/etc/ntp.keys</tt>. This is the same operation as the <tt>keys <i>keyfile</i></tt> command.</dd>
- <dt><tt>-l <i>logfile</i></tt></dt>
- <dd>Specify the name and path of the log file. The default is the system log file. This is the same operation as the <tt>logfile <i>logfile</i></tt> command.</dd>
- <dt id="--novirtualips"><tt>-L</tt></dt>
- <dd>Do not listen to virtual interfaces, defined as those with names containing a colon. This option is deprecated. Please consider using the configuration file <a href="miscopt.html#interface">interface</a> command, which is more versatile.</dd>
- <dt><tt>-M</tt></dt>
- <dd>Raise scheduler precision to its maximum (1 msec) using timeBeginPeriod. (Windows only)</dd>
- <dt><tt>-n</tt></dt>
- <dd>Don't fork.</dd>
- <dt><tt>-N</tt></dt>
- <dd>To the extent permitted by the operating system, run the <tt>ntpd</tt> at the highest priority.</dd>
- <dt><tt>-p <i>pidfile</i></tt></dt>
- <dd>Specify the name and path of the file used to record the <tt>ntpd</tt> process ID. This is the same operation as the <tt>pidfile <i>pidfile</i></tt> command.</dd>
- <dt><tt>-P <i>priority</i></tt></dt>
- <dd>To the extent permitted by the operating system, run the <tt>ntpd</tt> at the specified priority.</dd>
- <dt><tt>-q</tt></dt>
- <dd>Exit the <tt>ntpd</tt> just after the first time the clock is set. This behavior mimics that of the <tt>ntpdate</tt> program, which is to be retired. The <tt>-g</tt> and <tt>-x</tt> options can be used with this option. Note: The kernel time discipline is disabled with this option.</dd>
- <dt><tt>-r <i>broadcastdelay</i></tt></dt>
- <dd>Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol.</dd>
- <dt><tt>-s <i>statsdir</i></tt></dt>
- <dd>Specify the directory path for files created by the statistics facility. This is the same operation as the <tt>statsdir <i>statsdir</i></tt> command.</dd>
- <dt><tt>-t <i>key</i></tt></dt>
- <dd>Add a key number to the trusted key list. This option can occur more than once. This is the same operation as the <tt>trustedkey <i>key</i></tt> command.</dd>
- <dt><tt>-u <i>user[:group]</i> </tt></dt>
- <dd>Specify a user, and optionally a group, to switch to. This option is only available if the OS supports running the server without full root privileges. Currently, this option is supported under NetBSD (configure with <tt>--enable-clockctl</tt>) and Linux (configure with --<tt>enable-linuxcaps</tt>).</dd>
- <dt><tt>-U <i>interface update interval</i></tt></dt>
- <dd>Number of seconds to wait between interface list scans to pick up new and delete network interface. Set to 0 to disable dynamic interface list updating. The default is to scan every 5 minutes.</dd>
- <dt><tt>-v <i>variable</i></tt></dt>
- <dt><tt>-V <i>variable</i></tt></dt>
- <dd>Add a system variable listed by default.</dd>
- <dt><tt>-x</tt></dt>
- <dd>Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus, an adjustment as much as 600 s will take almost 14 days to complete. This option can be used with the <tt>-g</tt> and <tt>-q</tt> options. See the <tt>tinker</tt> command for other options. Note: The kernel time discipline is disabled with this option.</dd>
- <dt><tt>--pccfreq <i>frequency</i></tt></dt>
- <dd>Substitute processor cycle counter for QueryPerformanceCounter unconditionally
- using the given frequency (in Hz). <tt>--pccfreq</tt> can be used on systems
- which do not use the PCC to implement QueryPerformanceCounter
- and have a fixed PCC frequency. The frequency specified must
- be accurate within 0.5 percent. <tt>--usepcc</tt> is equivalent on many systems and should
- be tried first, as it does not require determining the frequency
- of the processor cycle counter. For x86-compatible processors, the PCC is
- also referred to as <tt>RDTSC</tt>, which is the assembly-language instruction to retrieve
- the current value. (Windows only)</dd>
- <dt><tt>--usepcc</tt></dt>
- <dd>Substitute processor cycle counter for QueryPerformanceCounter if they
- appear equivalent. This option should be used only if the PCC
- frequency is fixed. Power-saving functionality on many laptops varies the
- PCC frequency. (Windows only)</dd>
- </dl>
- <h4 id="cfg">The Configuration File</h4>
- <p>Ordinarily, <tt>ntpd</tt> reads the <tt>ntp.conf</tt> configuration file at startup in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited, configuration entirely on the command line, obviating the need for a configuration file. This may be particularly useful when the local host is to be configured as a broadcast client, with servers determined by listening to broadcasts at run time.</p>
- <p>Usually, the configuration file is installed as<tt>/etc/ntp.conf</tt>, but could be installed elsewhere (see the <tt>-c <i>conffile</i></tt> command line option). The file format is similar to other Unix configuration files - comments begin with a <tt>#</tt> character and extend to the end of the line; blank lines are ignored.</p>
- <p>Configuration commands consist of an initial command keyword followed by a list of option keywords separated by whitespace. Commands may not be continued over multiple lines. Options may be host names, host addresses written in numeric, dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by <tt>[ ]</tt> in the options pages, while alternatives are separated by <tt>|</tt>. The notation <tt>[ ... ]</tt> means an optional, indefinite repetition of the last item before the <tt>[ ... ]</tt>.</p>
- <h4 id="files">Files</h4>
- <table width="100%" border="1">
- <tr>
- <td width="30%">File</td>
- <td width="30%">Default</td>
- <td width="20%">Option</td>
- <td width="20%">Command</td>
- </tr>
- <tr>
- <td width="30%">configuration file</td>
- <td width="30%"><tt>/etc/ntp.conf</tt></td>
- <td width="20%"><tt>-c</tt></td>
- <td width="20%">none</td>
- </tr>
- <tr>
- <td width="30%">frequency file</td>
- <td width="30%">none</td>
- <td width="20%"><tt>-f</tt></td>
- <td width="20%"><tt>driftfile</tt></td>
- </tr>
- <tr>
- <td width="30%">leapseconds file</td>
- <td width="30%">none</td>
- <td width="20%"></td>
- <td width="20%"><tt>leapfile</tt></td>
- </tr>
- <tr>
- <td width="30%">process ID file</td>
- <td width="30%">none</td>
- <td width="20%"><tt>-p</tt></td>
- <td width="20%"><tt>pidfile</tt></td>
- </tr>
- <tr>
- <td width="30%">log file</td>
- <td width="30%">system log</td>
- <td width="20%"><tt>-l</tt></td>
- <td width="20%"><tt>logfile</tt></td>
- </tr>
- <tr>
- <td width="30%">include file</td>
- <td width="30%">none</td>
- <td width="20%">none</td>
- <td width="20%"><tt>includefile</tt></td>
- </tr>
- <tr>
- <td width="30%">statistics path</td>
- <td width="30%"><tt>/var/NTP</tt></td>
- <td width="20%"><tt>-s</tt></td>
- <td width="20%"><tt>statsdir</tt></td>
- </tr>
- <tr>
- <td width="30%">keys path</td>
- <td width="30%"><tt>/usr/local/etc</tt></td>
- <td width="20%"><tt>-k</tt></td>
- <td width="20%"><tt>keysdir</tt></td>
- </tr>
- </table>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#synop">Synopsis</a></li>
+ <li class="inline"><a href="#descr">Description</a></li>
+ <li class="inline"><a href="#info">Additional Information</a></li>
+ <li class="inline"><a href="#cmd">Command Line Options</a></li>
+ <li class="inline"><a href="#cfg">The Configuration File</a></li>
+ <li class="inline"><a href="#files">Files</a></li>
+</ul>
+<hr>
+<h4 id="synop">Synopsis</h4>
+<tt>ntpd [ -46aAbdDgLmnNqx ] [ -c <i>conffile</i> ] [ -f <i>driftfile</i> ] [ -i <i>jaildir</i> ] [ -k <i>keyfile</i> ] [ -l <i>logfile</i> ] [ -p <i>pidfile</i> ] [ -P <i>priority</i> ] [ -r <i>broadcastdelay</i> ] [ -s <i>statsdir</i> ] [ -t <i>key</i> ] [ -u <i>user</i>[:<i>group</i>] ] [ -U <i>interface_update_interval</i> ] [ -v <i>variable</i> ] [ -V <i>variable</i> ]</tt>
+<h4 id="descr">Description</h4>
+<p>The <tt>ntpd</tt> program is an operating system daemon that synchronises the system clock to remote NTP time servers or local reference clocks. It is a complete implementation of NTP version 4 defined by RFC-5905, but also retains compatibley with version 3 defined by RFC-1305 and versions 1 and 2, defined by RFC-1059 and RFC-1119, respectively. The program can operate in any of several modes, including client/server, symmetric and broadcasrt modes, and with both symmetric-key and public key-cryptography</p>
+<p>The <tt>ntpd</tt> program ordinarily requires a configuration file described on this page. It contains configuration commands described on the pages listed above. However a client can discover remote servers and configure them automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment. Further details are on the </p>
+<p>The <tt>ntpd</tt> program normally operates continuously while adjusting the system time and frequency, but in some cases this might not be practical. With the <tt>-q</tt> option <tt>ntpd</tt> operates as in continous mode, but exits just after setting the clock for the first time. Most applications will probably want to specify the <tt>iburst</tt> option with the <tt>server</tt> command. With this option a volley of messages is exchanged to groom the data and set the clock in about ten seconds. If nothing is heard after a few minutes, the daemon times out and exits without setting the clock.</p>
+<h4 id="cmd">Command Line Options</h4>
+<dl>
+ <dt><tt>-a</tt></dt>
+ <dd>Require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the same operation as the <tt>enable auth</tt> command and is the default.</dd>
+ <dt><tt>-A</tt></dt>
+ <dd>Do not require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the same operation as the <tt>disable auth</tt> command and almost never a good idea.</dd>
+ <dt><tt>-b</tt></dt>
+ <dd>Enable the client to synchronize to broadcast servers.</dd>
+ <dt><tt>-c <i>conffile</i></tt></dt>
+ <dd>Specify the name and path of the configuration file, default <tt>/etc/ntp.conf</tt>.</dd>
+ <dt><tt>-d</tt></dt>
+ <dd>Specify debugging mode. This option may occur more than once, with each occurrence indicating greater detail of display.</dd>
+ <dt><tt>-D <i>level</i></tt></dt>
+ <dd>Specify debugging level directly.</dd>
+ <dt><tt>-f <i>driftfile</i></tt></dt>
+ <dd>Specify the name and path of the frequency file, default <tt>/etc/ntp.drift</tt>. This is the same operation as the <tt>driftfile <i>driftfile</i></tt> command.</dd>
+ <dt><tt>-g</tt></dt>
+ <dd>Normally, <tt>ntpd</tt> exits with a message to the system log if the offset exceeds the panic threshold, which is 1000 s by default. This option allows the time to be set to any value without restriction; however, this can happen only once. If the threshold is exceeded after that, <tt>ntpd</tt> will exit with a message to the system log. This option can be used with the <tt>-q</tt> and <tt>-x</tt> options. See the <tt>tinker</tt> command for other options.</dd>
+ <dt><tt>-i <i>jaildir</i></tt></dt>
+ <dd>Chroot the server to the directory <i><tt>jaildir</tt></i>. This option also implies that the server attempts to drop root privileges at startup (otherwise, chroot gives very little additional security), and it is only available if the OS supports to run the server without full root privileges. You may need to also specify a <tt>-u</tt> option.</dd>
+ <dt id="--interface"><tt>-I [<i>address</i> | <i>interface name</i>]</tt></dt>
+ <dd>Open the network address given, or all the addresses associated with the given interface name. This option may appear multiple times. This option also implies not opening other addresses, except wildcard and localhost. This option is deprecated. Please consider using the configuration file <a href="miscopt.html#interface">interface</a> command, which is more versatile.</dd>
+ <dt><tt>-k <i>keyfile</i></tt></dt>
+ <dd>Specify the name and path of the symmetric key file, default <tt>/etc/ntp.keys</tt>. This is the same operation as the <tt>keys <i>keyfile</i></tt> command.</dd>
+ <dt><tt>-l <i>logfile</i></tt></dt>
+ <dd>Specify the name and path of the log file. The default is the system log file. This is the same operation as the <tt>logfile <i>logfile</i></tt> command.</dd>
+ <dt id="--novirtualips"><tt>-L</tt></dt>
+ <dd>Do not listen to virtual interfaces, defined as those with names containing a colon. This option is deprecated. Please consider using the configuration file <a href="miscopt.html#interface">interface</a> command, which is more versatile.</dd>
+ <dt><tt>-M</tt></dt>
+ <dd>Raise scheduler precision to its maximum (1 msec) using timeBeginPeriod. (Windows only)</dd>
+ <dt><tt>-n</tt></dt>
+ <dd>Don't fork.</dd>
+ <dt><tt>-N</tt></dt>
+ <dd>To the extent permitted by the operating system, run the <tt>ntpd</tt> at the highest priority.</dd>
+ <dt><tt>-p <i>pidfile</i></tt></dt>
+ <dd>Specify the name and path of the file used to record the <tt>ntpd</tt> process ID. This is the same operation as the <tt>pidfile <i>pidfile</i></tt> command.</dd>
+ <dt><tt>-P <i>priority</i></tt></dt>
+ <dd>To the extent permitted by the operating system, run the <tt>ntpd</tt> at the specified priority.</dd>
+ <dt><tt>-q</tt></dt>
+ <dd>Exit the <tt>ntpd</tt> just after the first time the clock is set. This behavior mimics that of the <tt>ntpdate</tt> program, which is to be retired. The <tt>-g</tt> and <tt>-x</tt> options can be used with this option. Note: The kernel time discipline is disabled with this option.</dd>
+ <dt><tt>-r <i>broadcastdelay</i></tt></dt>
+ <dd>Specify the default propagation delay from the broadcast/multicast server to this client. This is necessary only if the delay cannot be computed automatically by the protocol.</dd>
+ <dt><tt>-s <i>statsdir</i></tt></dt>
+ <dd>Specify the directory path for files created by the statistics facility. This is the same operation as the <tt>statsdir <i>statsdir</i></tt> command.</dd>
+ <dt><tt>-t <i>key</i></tt></dt>
+ <dd>Add a key number to the trusted key list. This option can occur more than once. This is the same operation as the <tt>trustedkey <i>key</i></tt> command.</dd>
+ <dt><tt>-u <i>user[:group]</i> </tt></dt>
+ <dd>Specify a user, and optionally a group, to switch to. This option is only available if the OS supports running the server without full root privileges. Currently, this option is supported under NetBSD (configure with <tt>--enable-clockctl</tt>) and Linux (configure with --<tt>enable-linuxcaps</tt>).</dd>
+ <dt><tt>-U <i>interface update interval</i></tt></dt>
+ <dd>Number of seconds to wait between interface list scans to pick up new and delete network interface. Set to 0 to disable dynamic interface list updating. The default is to scan every 5 minutes.</dd>
+ <dt><tt>-v <i>variable</i></tt></dt>
+ <dt><tt>-V <i>variable</i></tt></dt>
+ <dd>Add a system variable listed by default.</dd>
+ <dt><tt>-x</tt></dt>
+ <dd>Normally, the time is slewed if the offset is less than the step threshold, which is 128 ms by default, and stepped if above the threshold. This option sets the threshold to 600 s, which is well within the accuracy window to set the clock manually. Note: Since the slew rate of typical Unix kernels is limited to 0.5 ms/s, each second of adjustment requires an amortization interval of 2000 s. Thus, an adjustment as much as 600 s will take almost 14 days to complete. This option can be used with the <tt>-g</tt> and <tt>-q</tt> options. See the <tt>tinker</tt> command for other options. Note: The kernel time discipline is disabled with this option.</dd>
+ <dt><tt>--pccfreq <i>frequency</i></tt></dt>
+ <dd>Substitute processor cycle counter for QueryPerformanceCounter unconditionally
+ using the given frequency (in Hz). <tt>--pccfreq</tt> can be used on systems
+ which do not use the PCC to implement QueryPerformanceCounter
+ and have a fixed PCC frequency. The frequency specified must
+ be accurate within 0.5 percent. <tt>--usepcc</tt> is equivalent on many systems and should
+ be tried first, as it does not require determining the frequency
+ of the processor cycle counter. For x86-compatible processors, the PCC is
+ also referred to as <tt>RDTSC</tt>, which is the assembly-language instruction to retrieve
+ the current value. (Windows only)</dd>
+ <dt><tt>--usepcc</tt></dt>
+ <dd>Substitute processor cycle counter for QueryPerformanceCounter if they
+ appear equivalent. This option should be used only if the PCC
+ frequency is fixed. Power-saving functionality on many laptops varies the
+ PCC frequency. (Windows only)</dd>
+</dl>
+<h4 id="cfg">The Configuration File</h4>
+<p>Ordinarily, <tt>ntpd</tt> reads the <tt>ntp.conf</tt> configuration file at startup in order to determine the synchronization sources and operating modes. It is also possible to specify a working, although limited, configuration entirely on the command line, obviating the need for a configuration file. This may be particularly useful when the local host is to be configured as a broadcast client, with servers determined by listening to broadcasts at run time.</p>
+<p>Usually, the configuration file is installed as<tt>/etc/ntp.conf</tt>, but could be installed elsewhere (see the <tt>-c <i>conffile</i></tt> command line option). The file format is similar to other Unix configuration files - comments begin with a <tt>#</tt> character and extend to the end of the line; blank lines are ignored.</p>
+<p>Configuration commands consist of an initial command keyword followed by a list of option keywords separated by whitespace. Commands may not be continued over multiple lines. Options may be host names, host addresses written in numeric, dotted-quad form, integers, floating point numbers (when specifying times in seconds) and text strings. Optional arguments are delimited by <tt>[ ]</tt> in the options pages, while alternatives are separated by <tt>|</tt>. The notation <tt>[ ... ]</tt> means an optional, indefinite repetition of the last item before the <tt>[ ... ]</tt>.</p>
+<h4 id="files">Files</h4>
+<table width="100%" border="1">
+ <tr>
+ <td width="30%">File</td>
+ <td width="30%">Default</td>
+ <td width="20%">Option</td>
+ <td width="20%">Command</td>
+ </tr>
+ <tr>
+ <td width="30%">configuration file</td>
+ <td width="30%"><tt>/etc/ntp.conf</tt></td>
+ <td width="20%"><tt>-c</tt></td>
+ <td width="20%">none</td>
+ </tr>
+ <tr>
+ <td width="30%">frequency file</td>
+ <td width="30%">none</td>
+ <td width="20%"><tt>-f</tt></td>
+ <td width="20%"><tt>driftfile</tt></td>
+ </tr>
+ <tr>
+ <td width="30%">leapseconds file</td>
+ <td width="30%">none</td>
+ <td width="20%"></td>
+ <td width="20%"><tt>leapfile</tt></td>
+ </tr>
+ <tr>
+ <td width="30%">process ID file</td>
+ <td width="30%">none</td>
+ <td width="20%"><tt>-p</tt></td>
+ <td width="20%"><tt>pidfile</tt></td>
+ </tr>
+ <tr>
+ <td width="30%">log file</td>
+ <td width="30%">system log</td>
+ <td width="20%"><tt>-l</tt></td>
+ <td width="20%"><tt>logfile</tt></td>
+ </tr>
+ <tr>
+ <td width="30%">include file</td>
+ <td width="30%">none</td>
+ <td width="20%">none</td>
+ <td width="20%"><tt>includefile</tt></td>
+ </tr>
+ <tr>
+ <td width="30%">statistics path</td>
+ <td width="30%"><tt>/var/NTP</tt></td>
+ <td width="20%"><tt>-s</tt></td>
+ <td width="20%"><tt>statsdir</tt></td>
+ </tr>
+ <tr>
+ <td width="30%">keys path</td>
+ <td width="30%"><tt>/usr/local/etc</tt></td>
+ <td width="20%"><tt>-k</tt></td>
+ <td width="20%"><tt>keysdir</tt></td>
+ </tr>
+</table>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpdate - set the date and time via NTP</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntpdate</tt> - set the date and time via NTP</h3>
- <img src="pic/rabbit.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>I told you it was eyeball and wristwatch.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:44</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p>
- <br clear="left">
- <hr>
- <p>Disclaimer: The functionality of this program is now available in the <tt>ntpd</tt> program. See the <tt>-q</tt> command line option in the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page. After a suitable period of mourning, the <tt>ntpdate</tt> program is to be retired from this distribution</p>
- <h4>Synopsis</h4>
- <tt>ntpdate [ -bBdoqsuv ] [ -a <i>key</i> ] [ -e <i>authdelay</i> ] [ -k <i>keyfile</i> ] [ -o <i>version</i> ] [ -p <i>samples</i> ] [ -t <i>timeout</i> ] <i>server</i> [ ... ]</tt>
- <h4>Description</h4>
- <tt>ntpdate</tt> sets the local date and time by polling the Network Time Protocol (NTP) server(s) given as the <i>server</i> arguments to determine the correct time. It must be run as root on the local host. A number of samples are obtained from each of the servers specified and a subset of the NTP clock filter and selection algorithms are applied to select the best of these. Note that the accuracy and reliability of <tt>ntpdate</tt> depends on the number of servers, the number of polls each time it is run and the interval between runs.
- <p><tt>ntpdate</tt> can be run manually as necessary to set the host clock, or it can be run from the host startup script to set the clock at boot time. This is useful in some cases to set the clock initially before starting the NTP daemon <tt>ntpd</tt>. It is also possible to run <tt>ntpdate</tt> from a <tt>cron</tt> script. However, it is important to note that <tt>ntpdate</tt> with contrived <tt>cron</tt> scripts is no substitute for the NTP daemon, which uses sophisticated algorithms to maximize accuracy and reliability while minimizing resource use. Finally, since <tt>ntpdate</tt> does not discipline the host clock frequency as does <tt>ntpd</tt>, the accuracy using <tt>ntpdate</tt> is limited.</p>
- <p>Time adjustments are made by <tt>ntpdate</tt> in one of two ways. If <tt>ntpdate</tt> determines the clock is in error more than 0.5 second it will simply step the time by calling the system <tt>settimeofday()</tt> routine. If the error is less than 0.5 seconds, it will slew the time by calling the system <tt>adjtime()</tt> routine. The latter technique is less disruptive and more accurate when the error is small, and works quite well when <tt>ntpdate</tt> is run by <tt>cron</tt> every hour or two.</p>
- <p><tt>ntpdate</tt> will decline to set the date if an NTP server daemon (e.g., <tt>ntpd</tt>) is running on the same host. When running <tt>ntpdate</tt> on a regular basis from <tt>cron</tt> as an alternative to running a daemon, doing so once every hour or two will result in precise enough timekeeping to avoid stepping the clock.</p>
- <p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
- <p>If NetInfo support is compiled into <tt>ntpdate</tt>, then the <tt>server</tt> argument is optional if <tt>ntpdate</tt> can find a time server in the NetInfo configuration for <tt>ntpd</tt>.</p>
- <h4>Command Line Options</h4>
- <dl>
- <dt><tt>-4</tt>
- <dd>Force DNS resolution of following host names on the command line to the IPv4 namespace.
- <dt><tt>-6</tt>
- <dd>Force DNS resolution of following host names on the command line to the IPv6 namespace.
- <dt><tt>-a <i>key</i></tt>
- <dd>Enable the authentication function and specify the key identifier to be used for authentication as the argument <i>key</i><tt>ntpdate</tt>. The keys and key identifiers must match in both the client and server key files. The default is to disable the authentication function.
- <dt><tt>-B</tt>
- <dd>Force the time to always be slewed using the adjtime() system call, even if the measured offset is greater than +-128 ms. The default is to step the time using settimeofday() if the offset is greater than +-128 ms. Note that, if the offset is much greater than +-128 ms in this case, that it can take a long time (hours) to slew the clock to the correct value. During this time. the host should not be used to synchronize clients.
- <dt><tt>-b</tt>
- <dd>Force the time to be stepped using the settimeofday() system call, rather than slewed (default) using the adjtime() system call. This option should be used when called from a startup file at boot time.
- <dt><tt>-d</tt>
- <dd>Enable the debugging mode, in which <tt>ntpdate</tt> will go through all the steps, but not adjust the local clock. Information useful for general debugging will also be printed.
- <dt><tt>-e <i>authdelay</i></tt>
- <dd>Specify the processing delay to perform an authentication function as the value <i>authdelay</i>, in seconds and fraction (see <tt>ntpd</tt> for details). This number is usually small enough to be negligible for most purposes, though specifying a value may improve timekeeping on very slow CPU's.
- <dt><tt>-k <i>keyfile</i></tt>
- <dd>Specify the path for the authentication key file as the string <i>keyfile</i>. The default is <tt>/etc/ntp.keys</tt>. This file should be in the format described in <tt>ntpd</tt>.
- <dt><tt>-o <i>version</i></tt>
- <dd>Specify the NTP version for outgoing packets as the integer <i>version</i>, which can be 1 or 2. The default is 3. This allows <tt>ntpdate</tt> to be used with older NTP versions.
- <dt><tt>-p <i>samples</i></tt>
- <dd>Specify the number of samples to be acquired from each server as the integer <i>samples</i>, with values from 1 to 8 inclusive. The default is 4.
- <dt><i><tt>-q</tt></i>
- <dd>Query only - don't set the clock.
- <dt><tt>-s</tt>
- <dd>Divert logging output from the standard output (default) to the system <tt>syslog</tt> facility. This is designed primarily for convenience of <tt>cron</tt> scripts.
- <dt><tt>-t <i>timeout</i></tt>
- <dd>Specify the maximum time waiting for a server response as the value <i>timeout</i>, in seconds and fraction. The value is is rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN.
- <dt><tt>-u</tt>
- <dd>Direct <tt>ntpdate</tt> to use an unprivileged port or outgoing packets. This is most useful when behind a firewall that blocks incoming traffic to privileged ports, and you want to synchronise with hosts beyond the firewall. Note that the <tt>-d</tt> option always uses unprivileged ports.
- <dt><tt>-<i>v</i></tt>
- <dd>Be verbose. This option will cause <tt>ntpdate</tt>'s version identification string to be logged.
- </dl>
- <h4>Diagnostics</h4>
- <tt>ntpdate</tt>'s exit status is zero if it finds a server and updates the clock, and nonzero otherwise.
- <h4>Files</h4>
- <tt>/etc/ntp.keys</tt> - encryption keys used by <tt>ntpdate</tt>.
- <h4>Bugs</h4>
- The slew adjustment is actually 50% larger than the measured offset, since this (it is argued) will tend to keep a badly drifting clock more accurate. This is probably not a good idea and may cause a troubling hunt for some values of the kernel variables <tt>tick</tt> and <tt>tickadj</tt>.
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpdate - set the date and time via NTP</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntpdate</tt> - set the date and time via NTP</h3>
+<img src="pic/rabbit.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>I told you it was eyeball and wristwatch.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 1:24<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<hr>
+<p>Disclaimer: The functionality of this program is now available in the <tt>ntpd</tt> program. See the <tt>-q</tt> command line option in the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page. After a suitable period of mourning, the <tt>ntpdate</tt> program is to be retired from this distribution</p>
+<h4>Synopsis</h4>
+<tt>ntpdate [ -bBdoqsuv ] [ -a <i>key</i> ] [ -e <i>authdelay</i> ] [ -k <i>keyfile</i> ] [ -o <i>version</i> ] [ -p <i>samples</i> ] [ -t <i>timeout</i> ] <i>server</i> [ ... ]</tt>
+<h4>Description</h4>
+<tt>ntpdate</tt> sets the local date and time by polling the Network Time Protocol (NTP) server(s) given as the <i>server</i> arguments to determine the correct time. It must be run as root on the local host. A number of samples are obtained from each of the servers specified and a subset of the NTP clock filter and selection algorithms are applied to select the best of these. Note that the accuracy and reliability of <tt>ntpdate</tt> depends on the number of servers, the number of polls each time it is run and the interval between runs.
+<p><tt>ntpdate</tt> can be run manually as necessary to set the host clock, or it can be run from the host startup script to set the clock at boot time. This is useful in some cases to set the clock initially before starting the NTP daemon <tt>ntpd</tt>. It is also possible to run <tt>ntpdate</tt> from a <tt>cron</tt> script. However, it is important to note that <tt>ntpdate</tt> with contrived <tt>cron</tt> scripts is no substitute for the NTP daemon, which uses sophisticated algorithms to maximize accuracy and reliability while minimizing resource use. Finally, since <tt>ntpdate</tt> does not discipline the host clock frequency as does <tt>ntpd</tt>, the accuracy using <tt>ntpdate</tt> is limited.</p>
+<p>Time adjustments are made by <tt>ntpdate</tt> in one of two ways. If <tt>ntpdate</tt> determines the clock is in error more than 0.5 second it will simply step the time by calling the system <tt>settimeofday()</tt> routine. If the error is less than 0.5 seconds, it will slew the time by calling the system <tt>adjtime()</tt> routine. The latter technique is less disruptive and more accurate when the error is small, and works quite well when <tt>ntpdate</tt> is run by <tt>cron</tt> every hour or two.</p>
+<p><tt>ntpdate</tt> will decline to set the date if an NTP server daemon (e.g., <tt>ntpd</tt>) is running on the same host. When running <tt>ntpdate</tt> on a regular basis from <tt>cron</tt> as an alternative to running a daemon, doing so once every hour or two will result in precise enough timekeeping to avoid stepping the clock.</p>
+<p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
+<p>If NetInfo support is compiled into <tt>ntpdate</tt>, then the <tt>server</tt> argument is optional if <tt>ntpdate</tt> can find a time server in the NetInfo configuration for <tt>ntpd</tt>.</p>
+<h4>Command Line Options</h4>
+<dl>
+ <dt><tt>-4</tt></dt>
+ <dd>Force DNS resolution of following host names on the command line to the IPv4 namespace.</dd>
+ <dt><tt>-6</tt></dt>
+ <dd>Force DNS resolution of following host names on the command line to the IPv6 namespace.</dd>
+ <dt><tt>-a <i>key</i></tt></dt>
+ <dd>Enable the authentication function and specify the key identifier to be used for authentication as the argument <i>key</i><tt>ntpdate</tt>. The keys and key identifiers must match in both the client and server key files. The default is to disable the authentication function.</dd>
+ <dt><tt>-B</tt></dt>
+ <dd>Force the time to always be slewed using the adjtime() system call, even if the measured offset is greater than +-128 ms. The default is to step the time using settimeofday() if the offset is greater than +-128 ms. Note that, if the offset is much greater than +-128 ms in this case, that it can take a long time (hours) to slew the clock to the correct value. During this time. the host should not be used to synchronize clients.</dd>
+ <dt><tt>-b</tt></dt>
+ <dd>Force the time to be stepped using the settimeofday() system call, rather than slewed (default) using the adjtime() system call. This option should be used when called from a startup file at boot time.</dd>
+ <dt><tt>-d</tt></dt>
+ <dd>Enable the debugging mode, in which <tt>ntpdate</tt> will go through all the steps, but not adjust the local clock. Information useful for general debugging will also be printed.</dd>
+ <dt><tt>-e <i>authdelay</i></tt></dt>
+ <dd>Specify the processing delay to perform an authentication function as the value <i>authdelay</i>, in seconds and fraction (see <tt>ntpd</tt> for details). This number is usually small enough to be negligible for most purposes, though specifying a value may improve timekeeping on very slow CPU's.</dd>
+ <dt><tt>-k <i>keyfile</i></tt></dt>
+ <dd>Specify the path for the authentication key file as the string <i>keyfile</i>. The default is <tt>/etc/ntp.keys</tt>. This file should be in the format described in <tt>ntpd</tt>.</dd>
+ <dt><tt>-o <i>version</i></tt></dt>
+ <dd>Specify the NTP version for outgoing packets as the integer <i>version</i>, which can be 1 or 2. The default is 3. This allows <tt>ntpdate</tt> to be used with older NTP versions.</dd>
+ <dt><tt>-p <i>samples</i></tt></dt>
+ <dd>Specify the number of samples to be acquired from each server as the integer <i>samples</i>, with values from 1 to 8 inclusive. The default is 4.</dd>
+ <dt><i><tt>-q</tt></i></dt>
+ <dd>Query only - don't set the clock.</dd>
+ <dt><tt>-s</tt></dt>
+ <dd>Divert logging output from the standard output (default) to the system <tt>syslog</tt> facility. This is designed primarily for convenience of <tt>cron</tt> scripts.</dd>
+ <dt><tt>-t <i>timeout</i></tt></dt>
+ <dd>Specify the maximum time waiting for a server response as the value <i>timeout</i>, in seconds and fraction. The value is is rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN.</dd>
+ <dt><tt>-u</tt></dt>
+ <dd>Direct <tt>ntpdate</tt> to use an unprivileged port or outgoing packets. This is most useful when behind a firewall that blocks incoming traffic to privileged ports, and you want to synchronise with hosts beyond the firewall. Note that the <tt>-d</tt> option always uses unprivileged ports.</dd>
+ <dt><tt>-<i>v</i></tt></dt>
+ <dd>Be verbose. This option will cause <tt>ntpdate</tt>'s version identification string to be logged.</dd>
+</dl>
+<h4>Diagnostics</h4>
+<tt>ntpdate</tt>'s exit status is zero if it finds a server and updates the clock, and nonzero otherwise.
+<h4>Files</h4>
+<tt>/etc/ntp.keys</tt> - encryption keys used by <tt>ntpdate</tt>.
+<h4>Bugs</h4>
+The slew adjustment is actually 50% larger than the measured offset, since this (it is argued) will tend to keep a badly drifting clock more accurate. This is probably not a good idea and may cause a troubling hunt for some values of the kernel variables <tt>tick</tt> and <tt>tickadj</tt>.
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpdc - special NTP query program</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntpdc</tt> - special NTP query program</h3>
- <img src="pic/alice31.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>This program is a big puppy.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:17</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="308">Sunday, April 11, 2010</csobj></p>
- <br clear="left">
- <h4>More Help</h4>
- <script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
- <hr>
- <h4>Synopsis</h4>
- <tt>ntpdc [ -ilnps ] [ -c <i>command</i> ] [ <i>host</i> ] [ ... ]</tt>
- <h4>Description</h4>
- <tt>ntpdc</tt> is used to query the <tt>ntpd</tt> daemon about its current state and to request changes in that state. The program may be run either in interactive mode or controlled using command line arguments. Extensive state and statistics information is available through the <tt>ntpdc</tt> interface. In addition, nearly all the configuration options which can be specified at startup using ntpd's configuration file may also be specified at run time using <tt>ntpdc</tt>.
- <p>If one or more request options are included on the command line when <tt>ntpdc</tt> is executed, each of the requests will be sent to the NTP servers running on each of the hosts given as command line arguments, or on localhost by default. If no request options are given, <tt>ntpdc</tt> will attempt to read commands from the standard input and execute these on the NTP server running on the first host given on the command line, again defaulting to localhost when no other host is specified. <tt>ntpdc</tt> will prompt for commands if the standard input is a terminal device.</p>
- <p><tt>ntpdc</tt> uses NTP mode 7 packets to communicate with the NTP server, and hence can be used to query any compatible server on the network which permits it. Note that since NTP is a UDP protocol this communication will be somewhat unreliable, especially over large distances in terms of network topology. <tt>ntpdc</tt> makes no attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.</p>
- <p>The operation of <tt>ntpdc</tt> are specific to the particular implementation of the <tt>ntpd</tt> daemon and can be expected to work only with this and maybe some previous versions of the daemon. Requests from a remote <tt>ntpdc</tt> program which affect the state of the local server must be authenticated, which requires both the remote program and local server share a common key and key identifier.</p>
- <p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
- <h4>Command Line Options</h4>
- <p>Specifying a command line option other than <tt>-i</tt> or <tt>-n</tt> will cause the specified query (queries) to be sent to the indicated host(s) immediately. Otherwise, <tt>ntpdc</tt> will attempt to read interactive format commands from the standard input.</p>
- <dl>
- <dt><tt>-4</tt>
- <dd>Force DNS resolution of following host names on the command line to the IPv4 namespace.
- <dt><tt>-6</tt>
- <dd>Force DNS resolution of following host names on the command line to the IPv6 namespace.
- <dt><tt>-c <i>command</i></tt>
- <dd>The following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). Multiple -c options may be given.
- <dt><tt>-i</tt>
- <dd>Force <tt>ntpdc</tt> to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.
- <dt><tt>-l</tt>
- <dd>Obtain a list of peers which are known to the server(s). This switch is equivalent to <tt>-c listpeers</tt>.
- <dt><tt>-n</tt>
- <dd>Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
- <dt><tt>-p</tt>
- <dd>Print a list of the peers known to the server as well as a summary of their state. This is equivalent to <tt>-c peers</tt>.
- <dt><tt>-s</tt>
- <dd>Print a list of the peers known to the server as well as a summary of their state, but in a slightly different format than the -p switch. This is equivalent to <tt>-c dmpeers</tt>.
- </dl>
- <h4>Interactive Commands</h4>
- <p>Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but optionally the output of individual commands may be sent to a file by appending a <tt><</tt>, followed by a file name, to the command line.</p>
- <p>A number of interactive format commands are executed entirely within the <tt>ntpdc</tt> program itself and do not result in NTP mode 7 requests being sent to a server. These are described following.</p>
- <dl>
- <dt><tt>? [ <i>command_keyword</i> ]</tt><br>
- <tt>help [ <i>command_keyword</i> ]</tt>
- <dd>A <tt>?</tt> by itself will print a list of all the command keywords known to this incarnation of <tt>ntpq</tt>. A <tt>?</tt> followed by a command keyword will print function and usage information about the command. This command is probably a better source of information about <tt>ntpq</tt> than this manual page.
- <dt><tt>delay <i>milliseconds</i></tt>
- <dd>Specify a time interval to be added to timestamps included in requests which require authentication. This is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. Actually the server does not now require timestamps in authenticated requests, so this command may be obsolete.
- <dt><tt>host <i>hostname</i></tt>
- <dd>Set the host to which future queries will be sent. Hostname may be either a host name or a numeric address.
- <dt><tt>hostnames [ yes | no ]</tt>
- <dd>If <tt>yes</tt> is specified, host names are printed in information displays. If <tt>no</tt> is specified, numeric addresses are printed instead. The default is <tt>yes</tt>, unless modified using the command line <tt>-n</tt> switch.
- <dt><tt>keyid <i>keyid</i></tt>
- <dd>This command allows the specification of a
- key number to be used to authenticate configuration
- requests from ntpdc to the host(s). This must
- correspond to a key number which the host/server has
- been configured to use for this purpose (server
- options: <tt>trustedkey</tt>, and
- <tt>requestkey</tt>). If authentication is not
- enabled on the host(s) for ntpdc
- commands, the command
- <tt>"keyid 0"</tt> should be given; otherwise the
- <i>keyid</i> of the next subsequent <tt>addpeer/addserver/broadcast
- </tt> command will
- be used.
- <dt><tt>quit</tt>
- <dd>Exit <tt>ntpdc</tt>.
- <dt><tt>passwd</tt>
- <dd>This command prompts you to type in a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server for this purpose if such requests are to be successful.
- <dt><tt>timeout <i>milliseconds</i></tt>
- <dd>Specify a timeout period for responses to server queries. The default is about 8000 milliseconds. Note that since <tt>ntpdc</tt> retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.
- </dl>
- <h4>Control Message Commands</h4>
- <p>Query commands result in NTP mode 7 packets containing requests for information being sent to the server. These are read-only commands in that they make no modification of the server configuration state.</p>
- <dl>
- <dt><tt>listpeers</tt>
- <dd>Obtains and prints a brief list of the peers for which the server is maintaining state. These should include all configured peer associations as well as those peers whose stratum is such that they are considered by the server to be possible future synchronization candidates.
- <dt><tt>peers</tt>
- <dd>Obtains a list of peers for which the server is maintaining state, along with a summary of that state. Summary information includes the address of the remote peer, the local interface address (0.0.0.0 if a local address has yet to be determined), the stratum of the remote peer (a stratum of 16 indicates the remote peer is unsynchronized), the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in seconds.
- <p>The character in the left margin indicates the mode this peer entry is operating in. A <tt>+</tt> denotes symmetric active, a <tt>-</tt> indicates symmetric passive, a <tt>=</tt> means the remote server is being polled in client mode, a <tt>^</tt> indicates that the server is broadcasting to this address, a <tt>~</tt> denotes that the remote peer is sending broadcasts and a <tt>*</tt> marks the peer the server is currently synchronizing to.</p>
- <p>The contents of the host field may be one of four forms. It may be a host name, an IP address, a reference clock implementation name with its parameter or <tt>REFCLK(<i>implementation number</i>, <i>parameter</i>)</tt>. On <tt>hostnames no</tt> only IP-addresses will be displayed.</p>
- <dt><tt>dmpeers</tt>
- <dd>A slightly different peer summary list. Identical to the output of the <tt>peers</tt> command, except for the character in the leftmost column. Characters only appear beside peers which were included in the final stage of the clock selection algorithm. A <tt>.</tt> indicates that this peer was cast off in the falseticker detection, while a <tt>+</tt> indicates that the peer made it through. A <tt>*</tt> denotes the peer the server is currently synchronizing with.
- <dt><tt>showpeer <i>peer_address</i> [...]</tt>
- <dd>Shows a detailed display of the current peer variables for one or more peers. Most of these values are described in the NTP Version 2 specification.
- <dt><tt>pstats <i>peer_address</i> [...]</tt>
- <dd>Show per-peer statistic counters associated with the specified peer(s).
- <dt><tt>clockinfo <i>clock_peer_address</i> [...]</tt>
- <dd>Obtain and print information concerning a peer clock. The values obtained provide information on the setting of fudge factors and other clock performance information.
- <dt><tt>kerninfo</tt>
- <dd>Obtain and print kernel phase-lock loop operating parameters. This information is available only if the kernel has been specially modified for a precision timekeeping function.
- <dt><tt>loopinfo [ oneline | multiline ]</tt>
- <dd>Print the values of selected loop filter variables. The loop filter is the part of NTP which deals with adjusting the local system clock. The <tt>offset</tt> is the last offset given to the loop filter by the packet processing code. The <tt>frequency</tt> is the frequency error of the local clock in parts-per-million (ppm). The <tt>time_const</tt> controls the stiffness of the phase-lock loop and thus the speed at which it can adapt to oscillator drift. The <tt>watchdog timer</tt> value is the number of seconds which have elapsed since the last sample offset was given to the loop filter. The <tt>oneline</tt> and <tt>multiline</tt> options specify the format in which this information is to be printed, with <tt>multiline</tt> as the default.
- <dt><tt>sysinfo</tt>
- <dd>Print a variety of system state variables, i.e., state related to the local server. All except the last four lines are described in the NTP Version 3 specification, RFC-1305.
- <p>The <tt>system flags</tt> show various system flags, some of which can be set and cleared by the <tt>enable</tt> and <tt>disable</tt> configuration commands, respectively. These are the <tt>auth</tt>, <tt>bclient</tt>, <tt>monitor</tt>, <tt>pll</tt>, <tt>pps</tt> and <tt>stats</tt> flags. See the <tt>ntpd</tt> documentation for the meaning of these flags. There are two additional flags which are read only, the <tt>kernel_pll</tt> and <tt>kernel_pps</tt>. These flags indicate the synchronization status when the precision time kernel modifications are in use. The <tt>kernel_pll</tt> indicates that the local clock is being disciplined by the kernel, while the kernel_pps indicates the kernel discipline is provided by the PPS signal.</p>
- <p>The <tt>stability</tt> is the residual frequency error remaining after the system frequency correction is applied and is intended for maintenance and debugging. In most architectures, this value will initially decrease from as high as 500 ppm to a nominal value in the range .01 to 0.1 ppm. If it remains high for some time after starting the daemon, something may be wrong with the local clock, or the value of the kernel variable <tt>tick</tt> may be incorrect.</p>
- <p>The <tt>broadcastdelay</tt> shows the default broadcast delay, as set by the <tt>broadcastdelay</tt> configuration command.</p>
- <p>The <tt>authdelay</tt> shows the default authentication delay, as set by the <tt>authdelay</tt> configuration command.</p>
- <dt><tt>sysstats</tt>
- <dd>Print statistics counters maintained in the protocol module.
- <dt><tt>memstats</tt>
- <dd>Print statistics counters related to memory allocation code.
- <dt><tt>iostats</tt>
- <dd>Print statistics counters maintained in the input-output module.
- <dt><tt>timerstats</tt>
- <dd>Print statistics counters maintained in the timer/event queue support code.
- <dt><tt>reslist</tt>
- <dd>Obtain and print the server's restriction list. This list is (usually) printed in sorted order and may help to understand how the restrictions are applied.
- <dt><tt>ifstats</tt>
- <dd>List interface statistics for interfaces used by ntpd for network communication.</dd>
- <dt><tt>ifreload</tt>
- <dd>Force rescan of current system interfaces. Outputs interface statistics for interfaces that could possibly change. Marks unchanged interfaces with <b>.</b>, added interfaces with <b>+</b> and deleted interfaces with <b>-</b>.</dd>
- <dt><tt>monlist [ <i>version</i> ]</tt>
- <dd>Obtain and print traffic counts collected and maintained by the monitor facility. The version number should not normally need to be specified. At most, 600 entries are displayed by <tt>monlist</tt>. To display the entire MRU list, use the <tt>ntpq</tt> program's <tt><a href="ntpq.html#mrulist">mrulist<a/></tt> command.</dd>
- <dt><tt>clkbug <i>clock_peer_address</i> [...]</tt>
- <dd>Obtain debugging information for a reference clock driver. This information is provided only by some clock drivers and is mostly undecodable without a copy of the driver source in hand.
- </dl>
- <h4>Runtime Configuration Requests</h4>
- <p>All requests which cause state changes in the server are authenticated by the server using a configured NTP key (the facility can also be disabled by the server by not configuring a key). The key number and the corresponding key must also be made known to <tt>ntpdc</tt>. This can be done using the keyid and passwd commands, the latter of which will prompt at the terminal for a password to use as the encryption key. You will also be prompted automatically for both the key number and password the first time a command which would result in an authenticated request to the server is given. Authentication not only provides verification that the requester has permission to make such changes, but also gives an extra degree of protection again transmission errors.</p>
- <p>Authenticated requests always include a timestamp in the packet data, which is included in the computation of the authentication code. This timestamp is compared by the server to its receive time stamp. If they differ by more than a small amount the request is rejected. This is done for two reasons. First, it makes simple replay attacks on the server, by someone who might be able to overhear traffic on your LAN, much more difficult. Second, it makes it more difficult to request configuration changes to your server from topologically remote hosts. While the reconfiguration facility will work well with a server on the local host, and may work adequately between time-synchronized hosts on the same LAN, it will work very poorly for more distant hosts. As such, if reasonable passwords are chosen, care is taken in the distribution and protection of keys and appropriate source address restrictions are applied, the run time reconfiguration facility should provide an adequate level of security.</p>
- <p>The following commands all make authenticated requests.</p>
- <dl>
- <dt><tt>addpeer <i>peer_address</i> [
- <i>keyid</i> ] [ <i>version</i> ] [
- <tt>minpoll# | prefer | iburst | burst | minpoll
- <i>N</i> | <tt>maxpoll</tt> <i>N</i> [...] ]</tt>
- <dt><tt>addpeer <i>peer_address</i> [
- <tt>prefer | iburst | burst | minpoll
- <i>N</i> | <tt>maxpoll</tt> <i>N</i> | <tt>keyid</tt>
- <i>N</i> | <tt>version</tt> <i>N</i> [...] ]</tt>
- <dd>Add a configured peer association at the
- given address and operating in symmetric
- active mode. Note that an existing association
- with the same peer may be deleted when this
- command is executed, or may simply be
- converted to conform to the new configuration,
- as appropriate. If the <tt>keyid</tt>
- is nonzero, all outgoing packets to
- the remote server will have an authentication
- field attached encrypted with this key. If the
- value is 0 (or not given) no authentication
- will be done. If ntpdc's key number has not
- yet been set (<i>e.g.,</i> by the keyid
- command), it will be set to this value.
- The <tt>version#</tt> can be 1 through 4 and defaults to 3. The remaining
- options are either a numeric value for <tt>minpoll</tt> or
- literals <tt>prefer</tt>, <tt>iburst</tt>,
- <tt>burst</tt>, <tt>minpoll </tt><i>N</i>,
- <tt>keyid </tt><i>N</i>, <tt>version </tt> <i>N</i>, or
- <tt>maxpoll </tt><i>N</i> (where <i>N</i> is a numeric value), and have the action as specified in the
- <tt>peer</tt> configuration file command of
- ntpd. See the <a href="confopt.html">Server Options</a> page for further information.
- Each flag (or its absence) replaces the
- previous setting. The <tt>prefer</tt> keyword indicates a preferred peer (and thus will be used primarily for clock synchronisation if possible). The preferred peer also determines the validity of the PPS signal - if the preferred peer is suitable for synchronisation so is the PPS signal.
- The <tt>dynamic</tt> keyword allows association configuration even when no suitable network interface is found at configuration time. The dynamic interface update mechanism may complete the configuration when new interfaces appear (e.g. WLAN/PPP interfaces) at a later time and thus render the association operable.
- <dt><tt>addserver <i>peer_address</i> [
- <i>keyid</i> ] [ <i>version</i> ] [
- <tt>minpoll# | prefer | iburst | burst | minpoll
- <i>N</i> | <tt>maxpoll</tt> <i>N</i> [...] ]</tt>
- <dt><tt>addserver <i>peer_address</i> [
- <tt>prefer | iburst | burst | minpoll
- <i>N</i> | <tt>maxpoll</tt> <i>N</i> | <tt>keyid</tt>
- <i>N</i> | <tt>version</tt> <i>N</i> [...] ]</tt>
- <dd>Identical to the addpeer command, except that the operating mode is client.
- <dt><tt>broadcast <i>peer_address</i> [
- <i>keyid</i> ] [ <i>version</i> ] [ <i>prefer</i> ]</tt>
- <dd>Identical to the addpeer command, except
- that the operating mode is broadcast. In this
- case a valid non-zero key identifier and key are required. The <tt>peer_address</tt> parameter can be the broadcast address of the local network or a multicast group address assigned to NTP. If a multicast address, a multicast-capable kernel is required.
- <dt><tt>unconfig <i>peer_address</i> [...]</tt>
- <dd>This command causes the configured bit to be removed from the specified peer(s). In many cases this will cause the peer association to be deleted. When appropriate, however, the association may persist in an unconfigured mode if the remote peer is willing to continue on in this fashion.
- <dt><tt>fudge <i>peer_address</i> [ <i>time1</i> ] [ <i>time2</i> ] [ <i>stratum</i> ] [ <i>refid</i> ]</tt>
- <dd>This command provides a way to set certain data for a reference clock. See the source listing for further information.
- <dt><tt>enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt><br>
- <tt>disable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt>
- <dd>These commands operate in the same way as the <tt>enable</tt> and <tt>disable</tt> configuration file commands of <tt>ntpd</tt>. See the <a href="miscopt.html">Miscellaneous Options</a> page for further information.
- <dt><tt>restrict <i>address mask flag</i> [ <i>flag</i> ]</tt>
- <dd>This command operates in the same way as the <tt>restrict</tt> configuration file commands of <tt>ntpd</tt>.
- <dt><tt>unrestrict <i>address mask flag</i> [ <i>flag</i> ]</tt>
- <dd>Unrestrict the matching entry from the restrict list.
- <dt><tt>delrestrict <i>address mask [ ntpport ]</i></tt>
- <dd>Delete the matching entry from the restrict list.
- <dt><tt>readkeys</tt>
- <dd>Causes the current set of authentication keys to be purged and a new set to be obtained by rereading the keys file (which must have been specified in the <tt>ntpd</tt> configuration file). This allows encryption keys to be changed without restarting the server.
- <dt><tt>trustedkey <i>keyid</i> [...]</tt>
- <dt><tt>untrustedkey <i>keyid</i> [...]</tt>
- <dd>These commands operate in the same way as the <tt>trustedkey</tt> and <tt>untrustedkey</tt> configuration file commands of <tt>ntpd</tt>.
- <dt><tt>authinfo</tt>
- <dd>Returns information concerning the authentication module, including known keys and counts of encryptions and decryptions which have been done.
- <dt><tt>traps</tt>
- <dd>Display the traps set in the server. See the source listing for further information.
- <dt><tt>addtrap [ <i>address</i> [ <i>port</i> ] [ <i>interface</i> ]</tt>
- <dd>Set a trap for asynchronous messages. See the source listing for further information.
- <dt><tt>clrtrap [ <i>address</i> [ <i>port</i> ] [ <i>interface</i>]</tt>
- <dd>Clear a trap for asynchronous messages. See the source listing for further information.
- <dt><tt>reset</tt>
- <dd>Clear the statistics counters in various modules of the server. See the source listing for further information.
- </dl>
- <h4>Bugs</h4>
- <p><tt>ntpdc</tt> is a crude hack. Much of the information it shows is deadly boring and could only be loved by its implementer. The program was designed so that new (and temporary) features were easy to hack in, at great expense to the program's ease of use. Despite this, the program is occasionally useful.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpdc - special NTP query program</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntpdc</tt> - special NTP query program</h3>
+<img src="pic/alice31.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>This program is a big puppy.</p>
+<p>Last update
+ <!-- #BeginDate format:En2m -->04-Sep-2010 14:15<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>More Help</h4>
+<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
+<hr>
+<h4>Synopsis</h4>
+<tt>ntpdc [ -ilnps ] [ -c <i>command</i> ] [ <i>host</i> ] [ ... ]</tt>
+<h4>Description</h4>
+<tt>ntpdc</tt> is used to query the <tt>ntpd</tt> daemon about its current state and to request changes in that state. The program may be run either in interactive mode or controlled using command line arguments. Extensive state and statistics information is available through the <tt>ntpdc</tt> interface. In addition, nearly all the configuration options which can be specified at startup using ntpd's configuration file may also be specified at run time using <tt>ntpdc</tt>.
+<p>If one or more request options are included on the command line when <tt>ntpdc</tt> is executed, each of the requests will be sent to the NTP servers running on each of the hosts given as command line arguments, or on localhost by default. If no request options are given, <tt>ntpdc</tt> will attempt to read commands from the standard input and execute these on the NTP server running on the first host given on the command line, again defaulting to localhost when no other host is specified. <tt>ntpdc</tt> will prompt for commands if the standard input is a terminal device.</p>
+<p><tt>ntpdc</tt> uses NTP mode 7 packets to communicate with the NTP server, and hence can be used to query any compatible server on the network which permits it. Note that since NTP is a UDP protocol this communication will be somewhat unreliable, especially over large distances in terms of network topology. <tt>ntpdc</tt> makes no attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.</p>
+<p>The operation of <tt>ntpdc</tt> are specific to the particular implementation of the <tt>ntpd</tt> daemon and can be expected to work only with this and maybe some previous versions of the daemon. Requests from a remote <tt>ntpdc</tt> program which affect the state of the local server must be authenticated, which requires both the remote program and local server share a common key and key identifier.</p>
+<p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
+<h4>Command Line Options</h4>
+<p>Specifying a command line option other than <tt>-i</tt> or <tt>-n</tt> will cause the specified query (queries) to be sent to the indicated host(s) immediately. Otherwise, <tt>ntpdc</tt> will attempt to read interactive format commands from the standard input.</p>
+<dl>
+ <dt><tt>-4</tt></dt>
+ <dd>Force DNS resolution of following host names on the command line to the IPv4 namespace.</dd>
+ <dt><tt>-6</tt></dt>
+ <dd>Force DNS resolution of following host names on the command line to the IPv6 namespace.</dd>
+ <dt><tt>-c <i>command</i></tt></dt>
+ <dd>The following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). Multiple -c options may be given.</dd>
+ <dt><tt>-i</tt></dt>
+ <dd>Force <tt>ntpdc</tt> to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.</dd>
+ <dt><tt>-l</tt></dt>
+ <dd>Obtain a list of peers which are known to the server(s). This switch is equivalent to <tt>-c listpeers</tt>.</dd>
+ <dt><tt>-n</tt></dt>
+ <dd>Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.</dd>
+ <dt><tt>-p</tt></dt>
+ <dd>Print a list of the peers known to the server as well as a summary of their state. This is equivalent to <tt>-c peers</tt>.</dd>
+ <dt><tt>-s</tt></dt>
+ <dd>Print a list of the peers known to the server as well as a summary of their state, but in a slightly different format than the -p switch. This is equivalent to <tt>-c dmpeers</tt>.</dd>
+</dl>
+<h4>Interactive Commands</h4>
+<p>Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but optionally the output of individual commands may be sent to a file by appending a <tt><</tt>, followed by a file name, to the command line.</p>
+<p>A number of interactive format commands are executed entirely within the <tt>ntpdc</tt> program itself and do not result in NTP mode 7 requests being sent to a server. These are described following.</p>
+<dl>
+ <dt><tt>? [ <i>command_keyword</i> ]</tt><br>
+ <tt>help [ <i>command_keyword</i> ]</tt></dt>
+ <dd>A <tt>?</tt> by itself will print a list of all the command keywords known to this incarnation of <tt>ntpq</tt>. A <tt>?</tt> followed by a command keyword will print function and usage information about the command. This command is probably a better source of information about <tt>ntpq</tt> than this manual page.</dd>
+ <dt><tt>delay <i>milliseconds</i></tt></dt>
+ <dd>Specify a time interval to be added to timestamps included in requests which require authentication. This is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. Actually the server does not now require timestamps in authenticated requests, so this command may be obsolete.</dd>
+ <dt><tt>host <i>hostname</i></tt></dt>
+ <dd>Set the host to which future queries will be sent. Hostname may be either a host name or a numeric address.</dd>
+ <dt><tt>hostnames [ yes | no ]</tt></dt>
+ <dd>If <tt>yes</tt> is specified, host names are printed in information displays. If <tt>no</tt> is specified, numeric addresses are printed instead. The default is <tt>yes</tt>, unless modified using the command line <tt>-n</tt> switch.</dd>
+ <dt><tt>keyid <i>keyid</i></tt></dt>
+ <dd>This command allows the specification of a
+ key number to be used to authenticate configuration
+ requests from ntpdc to the host(s). This must
+ correspond to a key number which the host/server has
+ been configured to use for this purpose (server
+ options: <tt>trustedkey</tt>, and <tt>requestkey</tt>). If authentication is not
+ enabled on the host(s) for ntpdc
+ commands, the command <tt>"keyid 0"</tt> should be given; otherwise the <i>keyid</i> of the next subsequent <tt>addpeer/addserver/broadcast </tt> command will
+ be used.</dd>
+ <dt><tt>quit</tt></dt>
+ <dd>Exit <tt>ntpdc</tt>.</dd>
+ <dt><tt>passwd</tt></dt>
+ <dd>This command prompts you to type in a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server for this purpose if such requests are to be successful.</dd>
+ <dt><tt>timeout <i>milliseconds</i></tt></dt>
+ <dd>Specify a timeout period for responses to server queries. The default is about 8000 milliseconds. Note that since <tt>ntpdc</tt> retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.</dd>
+</dl>
+<h4>Control Message Commands</h4>
+<p>Query commands result in NTP mode 7 packets containing requests for information being sent to the server. These are read-only commands in that they make no modification of the server configuration state.</p>
+<dl>
+ <dt><tt>listpeers</tt></dt>
+ <dd>Obtains and prints a brief list of the peers for which the server is maintaining state. These should include all configured peer associations as well as those peers whose stratum is such that they are considered by the server to be possible future synchronization candidates.</dd>
+ <dt><tt>peers</tt></dt>
+ <dd>Obtains a list of peers for which the server is maintaining state, along with a summary of that state. Summary information includes the address of the remote peer, the local interface address (0.0.0.0 if a local address has yet to be determined), the stratum of the remote peer (a stratum of 16 indicates the remote peer is unsynchronized), the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in seconds.</dd>
+ <dd>The character in the left margin indicates the mode this peer entry is operating in. A <tt>+</tt> denotes symmetric active, a <tt>-</tt> indicates symmetric passive, a <tt>=</tt> means the remote server is being polled in client mode, a <tt>^</tt> indicates that the server is broadcasting to this address, a <tt>~</tt> denotes that the remote peer is sending broadcasts and a <tt>*</tt> marks the peer the server is currently synchronizing to.</dd>
+ <dd>The contents of the host field may be one of four forms. It may be a host name, an IP address, a reference clock implementation name with its parameter or <tt>REFCLK(<i>implementation number</i>, <i>parameter</i>)</tt>. On <tt>hostnames no</tt> only IP-addresses will be displayed.</dd>
+ <dt><tt>dmpeers</tt></dt>
+ <dd>A slightly different peer summary list. Identical to the output of the <tt>peers</tt> command, except for the character in the leftmost column. Characters only appear beside peers which were included in the final stage of the clock selection algorithm. A <tt>.</tt> indicates that this peer was cast off in the falseticker detection, while a <tt>+</tt> indicates that the peer made it through. A <tt>*</tt> denotes the peer the server is currently synchronizing with.</dd>
+ <dt><tt>showpeer <i>peer_address</i> [...]</tt></dt>
+ <dd>Shows a detailed display of the current peer variables for one or more peers. Most of these values are described in the NTP Version 2 specification.</dd>
+ <dt><tt>pstats <i>peer_address</i> [...]</tt></dt>
+ <dd>Show per-peer statistic counters associated with the specified peer(s).</dd>
+ <dt><tt>clockinfo <i>clock_peer_address</i> [...]</tt></dt>
+ <dd>Obtain and print information concerning a peer clock. The values obtained provide information on the setting of fudge factors and other clock performance information.</dd>
+ <dt><tt>kerninfo</tt></dt>
+ <dd>Obtain and print kernel phase-lock loop operating parameters. This information is available only if the kernel has been specially modified for a precision timekeeping function.</dd>
+ <dt><tt>loopinfo [ oneline | multiline ]</tt></dt>
+ <dd>Print the values of selected loop filter variables. The loop filter is the part of NTP which deals with adjusting the local system clock. The <tt>offset</tt> is the last offset given to the loop filter by the packet processing code. The <tt>frequency</tt> is the frequency error of the local clock in parts-per-million (ppm). The <tt>time_const</tt> controls the stiffness of the phase-lock loop and thus the speed at which it can adapt to oscillator drift. The <tt>watchdog timer</tt> value is the number of seconds which have elapsed since the last sample offset was given to the loop filter. The <tt>oneline</tt> and <tt>multiline</tt> options specify the format in which this information is to be printed, with <tt>multiline</tt> as the default.</dd>
+ <dt><tt>sysinfo</tt></dt>
+ <dd>Print a variety of system state variables, i.e., state related to the local server. All except the last four lines are described in the NTP Version 3 specification, RFC-1305.</dd>
+ <dd>The <tt>system flags</tt> show various system flags, some of which can be set and cleared by the <tt>enable</tt> and <tt>disable</tt> configuration commands, respectively. These are the <tt>auth</tt>, <tt>bclient</tt>, <tt>monitor</tt>, <tt>pll</tt>, <tt>pps</tt> and <tt>stats</tt> flags. See the <tt>ntpd</tt> documentation for the meaning of these flags. There are two additional flags which are read only, the <tt>kernel_pll</tt> and <tt>kernel_pps</tt>. These flags indicate the synchronization status when the precision time kernel modifications are in use. The <tt>kernel_pll</tt> indicates that the local clock is being disciplined by the kernel, while the kernel_pps indicates the kernel discipline is provided by the PPS signal.</dd>
+ <dd>The <tt>stability</tt> is the residual frequency error remaining after the system frequency correction is applied and is intended for maintenance and debugging. In most architectures, this value will initially decrease from as high as 500 ppm to a nominal value in the range .01 to 0.1 ppm. If it remains high for some time after starting the daemon, something may be wrong with the local clock, or the value of the kernel variable <tt>tick</tt> may be incorrect.</dd>
+ <dd>The <tt>broadcastdelay</tt> shows the default broadcast delay, as set by the <tt>broadcastdelay</tt> configuration command.</dd>
+ <dd>The <tt>authdelay</tt> shows the default authentication delay, as set by the <tt>authdelay</tt> configuration command.</dd>
+ <dt><tt>sysstats</tt></dt>
+ <dd>Print statistics counters maintained in the protocol module.</dd>
+ <dt><tt>memstats</tt></dt>
+ <dd>Print statistics counters related to memory allocation code.</dd>
+ <dt><tt>iostats</tt></dt>
+ <dd>Print statistics counters maintained in the input-output module.</dd>
+ <dt><tt>timerstats</tt></dt>
+ <dd>Print statistics counters maintained in the timer/event queue support code.</dd>
+ <dt><tt>reslist</tt></dt>
+ <dd>Obtain and print the server's restriction list. This list is (usually) printed in sorted order and may help to understand how the restrictions are applied.</dd>
+ <dt><tt>ifstats</tt></dt>
+ <dd>List interface statistics for interfaces used by ntpd for network communication.</dd>
+ <dt><tt>ifreload</tt></dt>
+ <dd>Force rescan of current system interfaces. Outputs interface statistics for interfaces that could possibly change. Marks unchanged interfaces with <b>.</b>, added interfaces with <b>+</b> and deleted interfaces with <b>-</b>.</dd>
+ <dt><tt>monlist [ <i>version</i> ]</tt></dt>
+ <dd>Obtain and print traffic counts collected and maintained by the monitor facility. The version number should not normally need to be specified. At most, 600 entries are displayed by <tt>monlist</tt>. To display the entire MRU list, use the <tt>ntpq</tt> program's <a href="ntpq.html#mrulist"><tt>mrulist</tt></a> command.</dd>
+ <dt><tt>clkbug <i>clock_peer_address</i> [...]</tt></dt>
+ <dd>Obtain debugging information for a reference clock driver. This information is provided only by some clock drivers and is mostly undecodable without a copy of the driver source in hand.</dd>
+</dl>
+<h4>Runtime Configuration Requests</h4>
+<p>All requests which cause state changes in the server are authenticated by the server using a configured NTP key (the facility can also be disabled by the server by not configuring a key). The key number and the corresponding key must also be made known to <tt>ntpdc</tt>. This can be done using the keyid and passwd commands, the latter of which will prompt at the terminal for a password to use as the encryption key. You will also be prompted automatically for both the key number and password the first time a command which would result in an authenticated request to the server is given. Authentication not only provides verification that the requester has permission to make such changes, but also gives an extra degree of protection again transmission errors.</p>
+<p>Authenticated requests always include a timestamp in the packet data, which is included in the computation of the authentication code. This timestamp is compared by the server to its receive time stamp. If they differ by more than a small amount the request is rejected. This is done for two reasons. First, it makes simple replay attacks on the server, by someone who might be able to overhear traffic on your LAN, much more difficult. Second, it makes it more difficult to request configuration changes to your server from topologically remote hosts. While the reconfiguration facility will work well with a server on the local host, and may work adequately between time-synchronized hosts on the same LAN, it will work very poorly for more distant hosts. As such, if reasonable passwords are chosen, care is taken in the distribution and protection of keys and appropriate source address restrictions are applied, the run time reconfiguration facility should provide an adequate level of security.</p>
+<p>The following commands all make authenticated requests.</p>
+<dl>
+ <dt><tt>addpeer <i>peer_address</i> [ <i>keyid</i> ] [ <i>version</i> ] [ <tt>minpoll# | prefer | iburst | burst | minpoll <i>N</i> | <tt>maxpoll</tt> <i>N</i> [...] ]</tt></tt></dt>
+ <dt><tt>addpeer <i>peer_address</i> [ <tt>prefer | iburst | burst | minpoll <i>N</i> | <tt>maxpoll</tt> <i>N</i> | <tt>keyid</tt> <i>N</i> | <tt>version</tt> <i>N</i> [...] ]</tt></tt></dt>
+ <dd>Add a configured peer association at the given address and operating in symmetric
+ active mode. Note that an existing association with the same peer may be deleted when this
+ command is executed, or may simply be converted to conform to the new configuration, as appropriate. If the <tt>keyid</tt> is nonzero, all outgoing packets to the remote server will have an authentication field attached encrypted with this key. If the value is 0 (or not given) no authentication will be done. If ntpdc's key number has not yet been set (<i>e.g.,</i> by the keyid command), it will be set to this value. The <tt>version#</tt> can be 1 through 4 and defaults to 3. The remaining options are either a numeric value for <tt>minpoll</tt> or literals <tt>prefer</tt>, <tt>iburst</tt>, <tt>burst</tt>, <tt>minpoll </tt><i>N</i>, <tt>keyid </tt><i>N</i>, <tt>version </tt> <i>N</i>, or <tt>maxpoll </tt><i>N</i> (where <i>N</i> is a numeric value), and have the action as specified in the <tt>peer</tt> configuration file command of
+ ntpd. See the <a href="confopt.html">Server Options</a> page for further information. Each flag (or its absence) replaces the previous setting. The <tt>prefer</tt> keyword indicates a preferred peer (and thus will be used primarily for clock synchronisation if possible). The preferred peer also determines the validity of the PPS signal - if the preferred peer is suitable for synchronisation so is the PPS signal. The <tt>dynamic</tt> keyword allows association configuration even when no suitable network interface is found at configuration time. The dynamic interface update mechanism may complete the configuration when new interfaces appear (e.g. WLAN/PPP interfaces) at a later time and thus render the association operable.</dd>
+ <dt><tt>addserver <i>peer_address</i> [ <i>address</i> [ <i>keyid</i> ] [ <i>version</i> ] [ minpoll | prefer | iburst | burst | minpoll <i>N</i> | maxpoll <i>N</i> [...] ] prefer | iburst | burst | minpoll <i>N</i> | maxpoll <i>N</i> | keyid <i>N</i> | version <i>N</i> [...] ]</tt></dt>
+ <dd>Identical to the addpeer command, except that the operating mode is client.</dd>
+ <dt><tt>broadcast <i>peer_address</i> [ <i>keyid</i> ] [ <i>version</i> ] [ <i>prefer</i> ]</tt></dt>
+ <dd>Identical to the addpeer command, except that the operating mode is broadcast. In this case a valid non-zero key identifier and key are required. The <tt>peer_address</tt> parameter can be the broadcast address of the local network or a multicast group address assigned to NTP. If a multicast address, a multicast-capable kernel is required.</dd>
+ <dt><tt>unconfig <i>peer_address</i> [...]</tt></dt>
+ <dd>This command causes the configured bit to be removed from the specified peer(s). In many cases this will cause the peer association to be deleted. When appropriate, however, the association may persist in an unconfigured mode if the remote peer is willing to continue on in this fashion.</dd>
+ <dt><tt>fudge <i>peer_address</i> [ <i>time1</i> ] [ <i>time2</i> ] [ <i>stratum</i> ] [ <i>refid</i> ]</tt></dt>
+ <dd>This command provides a way to set certain data for a reference clock. See the source listing for further information.</dd>
+ <dt><tt>enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt><br>
+ <tt>disable [ auth | bclient | calibrate | kernel | monitor | ntp | pps | stats]</tt></dt>
+ <dd>These commands operate in the same way as the <tt>enable</tt> and <tt>disable</tt> configuration file commands of <tt>ntpd</tt>. See the <a href="miscopt.html">Miscellaneous Options</a> page for further information.</dd>
+ <dt><tt>restrict <i>address mask flag</i> [ <i>flag</i> ]</tt></dt>
+ <dd>This command operates in the same way as the <tt>restrict</tt> configuration file commands of <tt>ntpd</tt>.</dd>
+ <dt><tt>unrestrict <i>address mask flag</i> [ <i>flag</i> ]</tt></dt>
+ <dd>Unrestrict the matching entry from the restrict list.</dd>
+ <dt><tt>delrestrict <i>address mask [ ntpport ]</i></tt></dt>
+ <dd>Delete the matching entry from the restrict list.</dd>
+ <dt><tt>readkeys</tt></dt>
+ <dd>Causes the current set of authentication keys to be purged and a new set to be obtained by rereading the keys file (which must have been specified in the <tt>ntpd</tt> configuration file). This allows encryption keys to be changed without restarting the server.</dd>
+ <dt><tt>trustedkey <i>keyid</i> [...]</tt></dt>
+ <dt><tt>untrustedkey <i>keyid</i> [...]</tt></dt>
+ <dd>These commands operate in the same way as the <tt>trustedkey</tt> and <tt>untrustedkey</tt> configuration file commands of <tt>ntpd</tt>.</dd>
+ <dt><tt>authinfo</tt></dt>
+ <dd>Returns information concerning the authentication module, including known keys and counts of encryptions and decryptions which have been done.</dd>
+ <dt><tt>traps</tt></dt>
+ <dd>Display the traps set in the server. See the source listing for further information.</dd>
+ <dt><tt>addtrap [ <i>address</i> [ <i>port</i> ] [ <i>interface</i> ]</tt></dt>
+ <dd>Set a trap for asynchronous messages. See the source listing for further information.</dd>
+ <dt><tt>clrtrap [ <i>address</i> [ <i>port</i> ] [ <i>interface</i>]</tt></dt>
+ <dd>Clear a trap for asynchronous messages. See the source listing for further information.</dd>
+ <dt><tt>reset</tt></dt>
+ <dd>Clear the statistics counters in various modules of the server. See the source listing for further information.</dd>
+</dl>
+<h4>Bugs</h4>
+<p><tt>ntpdc</tt> is a crude hack. Much of the information it shows is deadly boring and could only be loved by its implementer. The program was designed so that new (and temporary) features were easy to hack in, at great expense to the program's ease of use. Despite this, the program is occasionally useful.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpdsim - Network Time Protocol (NTP) simulator</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</h3>
- <img src="pic/oz2.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
- <p>All in a row.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">15:55</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
- <h4>Table of Contents</h4>
- <li class="inline"><a href="#synop">Synopsis</a><br>
- <li class="inline"><a href="#descr">Description</a><br>
- <li class="inline"><a href="#cmd">Command Line Oprionts</a>
- <li class="inline"><a href="#files">Files</a>
- </ul>
- <hr>
- <h4 id="synop">Synopsis</h4>
- <tt>ntpdsim [ -B <i>bdly</i> ] [ -C <i>snse</i> ] [ -O <i>clk_time</i> ] [ -S <i>sim_time</i> ] [ -T <i>ferr</i> ] [ -W <i>fsne</i> ] [ -Y </tt><i><tt>ndly</tt></i><tt> ] [ -X </tt><i><tt>pdly</tt></i><tt> ]</tt>
- <h4 id="descr">Description</h4>
-
<p>The <tt>ntpdsim</tt> program is an adaptation of the <tt>ntpd</tt> operating system daemon. The program operates as a discrete time simulator using specified systematic and random driving sources. It includes all the mitigation and discipline algorithms of the actual daemon, but with the packet I/O and system clock algorithms driven by simulation. Most functions of the real <tt>ntpd</tt> remain intact, including the monitoring, statistics recording, trace and host name resolution features. Further information on the simulator is on the <a href="http://www.eecis.udel.edu/%7emills/ntpsim.html">NTP Discrete Event Simulator</a> page.</p>
-
<p>The simulator is most useful to study NTP behavior in response to time and/or frequency transients under specific conditions of network jitter and oscillator wander. For this purpose the daemon can be driven by pseudorandom jitter and wander sample sequences characteristic of real networks and oscillators. The jitter generator produces samples from a Poisson distribution, while the wander generator produces samples from a Guassian distribution.</p>
-
<p>The easiest way to use this program is to create a <tt>ntpstats</tt> directory, configuration file <tt>ntp.conf</tt> and frequency file <tt>ntp.drift</tt> and test shell <tt>test.sh</tt> in the base directory. The <tt>ntp.drift</tt> file and <tt>ntpstats</tt> directory can be empty to start. The <tt>test.sh</tt> script can contain something like</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpdsim - Network Time Protocol (NTP) simulator</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</h3>
+<img src="pic/oz2.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
+<p>All in a row.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 14:26<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#synop">Synopsis</a></li>
+ <li class="inline"><a href="#descr">Description</a></li>
+ <li class="inline"><a href="#cmd">Command Line Oprionts</a></li>
+ <li class="inline"><a href="#files">Files</a></li>
+</ul>
+<hr>
+<h4 id="synop">Synopsis</h4>
+<tt>ntpdsim [ -B <i>bdly</i> ] [ -C <i>snse</i> ] [ -O <i>clk_time</i> ] [ -S <i>sim_time</i> ] [ -T <i>ferr</i> ] [ -W <i>fsne</i> ] [ -Y </tt><i><tt>ndly</tt></i><tt> ] [ -X </tt><i><tt>pdly</tt></i><tt> ]</tt>
+<h4 id="descr">Description</h4>
+<p>The <tt>ntpdsim</tt> program is an adaptation of the <tt>ntpd</tt> operating system daemon. The program operates as a discrete time simulator using specified systematic and random driving sources. It includes all the mitigation and discipline algorithms of the actual daemon, but with the packet I/O and system clock algorithms driven by simulation. Most functions of the real <tt>ntpd</tt> remain intact, including the monitoring, statistics recording, trace and host name resolution features. Further information on the simulator is on the <a href="http://www.eecis.udel.edu/%7emills/ntpsim.html">NTP Discrete Event Simulator</a> page.</p>
+<p>The simulator is most useful to study NTP behavior in response to time and/or frequency transients under specific conditions of network jitter and oscillator wander. For this purpose the daemon can be driven by pseudorandom jitter and wander sample sequences characteristic of real networks and oscillators. The jitter generator produces samples from a Poisson distribution, while the wander generator produces samples from a Guassian distribution.</p>
+<p>The easiest way to use this program is to create a <tt>ntpstats</tt> directory, configuration file <tt>ntp.conf</tt> and frequency file <tt>ntp.drift</tt> and test shell <tt>test.sh</tt> in the base directory. The <tt>ntp.drift</tt> file and <tt>ntpstats</tt> directory can be empty to start. The <tt>test.sh</tt> script can contain something like</p>
+<pre>rm ./ntpstats/*
ntpdsim -O 0.1 -C .001 -T 400 -W 1 -c ./ntp.conf,
</pre>
-
<p>which starts the simulator with a time offset 100 ms, network jitter 1 ms, frequency offset 400 PPM and oscillator wander 1 PPM/s. These parameters represent typical conditions with modern workstations on a Ethernet LAN. The ntp.conf file should contain something like</p>
+<p>which starts the simulator with a time offset 100 ms, network jitter 1 ms, frequency offset 400 PPM and oscillator wander 1 PPM/s. These parameters represent typical conditions with modern workstations on a Ethernet LAN. The ntp.conf file should contain something like</p>
+<pre>disable kernel
server pogo
driftfile ./ntp.drift
statsdir ./ntpstats/
filegen loopstats type day enable
filegen peerstats type day enable
</pre>
- <h4 id="cmd">Command Line Options</h4>
- <dl>
- <dt>Note: The NTP development team is moving to the use of a syntax-directed configuration file design. When complete these options will be replaced by a <a href="ntpdsim_new.html">new one</a>. Most of the <tt>ntpd</tt> command line options apply also to <tt>ntpdsim</tt>. In addition, the following command line options apply to <tt>ntpdsim.</tt>
- <dt><tt>-B <i>bdly</i></tt>
- <dd>Specify beep delay (3600) s.
- <dt><tt>-C <i>snse</i></tt>
- <dd>Specify network jitter parameter (0) s.
- <dt><tt>-O <i>clk_time</i></tt>
- <dd>Specify initial time offset (0) s.
- <dt><tt>-S <i>sim_time</i></tt>
- <dd>Specify simulation duration (86400) s.
- <dt><tt>-T <i>ferr</i></tt>
- <dd>Specify initial frequency offset (0) PPM.
- <dt><tt>-W <i>fnse</i></tt>
- <dd>Specify oscillator wander parameter (0) PPM/s.
- <dt><tt>-Y <i>ndly</i></tt>
- <dd>Specify network propagation delay (.001) s.
- <dt><tt>-Z <i>pdly</i></tt>
- <dd>Specify server processing delay (.001) s.
- </dl>
- <h4 id="files">Files</h4>
- <tt>/etc/ntp.conf</tt> - the default name of the configuration file<br>
- <tt>/etc/ntp.drift</tt> - the default name of the drift file<br>
- <tt>/etc/ntp.keys</tt> - the default name of the key file
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<h4 id="cmd">Command Line Options</h4>
+<dl>
+ <dt>Note: The NTP development team is moving to the use of a syntax-directed configuration file design. When complete these options will be replaced by a <a href="ntpdsim_new.html">new one</a>. Most of the <tt>ntpd</tt> command line options apply also to <tt>ntpdsim</tt>. In addition, the following command line options apply to <tt>ntpdsim.</tt></dt>
+ <dt><tt>-B <i>bdly</i></tt></dt>
+ <dd>Specify beep delay (3600) s.</dd>
+ <dt><tt>-C <i>snse</i></tt></dt>
+ <dd>Specify network jitter parameter (0) s.</dd>
+ <dt><tt>-O <i>clk_time</i></tt></dt>
+ <dd>Specify initial time offset (0) s.</dd>
+ <dt><tt>-S <i>sim_time</i></tt></dt>
+ <dd>Specify simulation duration (86400) s.</dd>
+ <dt><tt>-T <i>ferr</i></tt></dt>
+ <dd>Specify initial frequency offset (0) PPM.</dd>
+ <dt><tt>-W <i>fnse</i></tt></dt>
+ <dd>Specify oscillator wander parameter (0) PPM/s.</dd>
+ <dt><tt>-Y <i>ndly</i></tt></dt>
+ <dd>Specify network propagation delay (.001) s.</dd>
+ <dt><tt>-Z <i>pdly</i></tt></dt>
+ <dd>Specify server processing delay (.001) s.</dd>
+</dl>
+<h4 id="files">Files</h4>
+<tt>/etc/ntp.conf</tt> - the default name of the configuration file<br>
+<tt>/etc/ntp.drift</tt> - the default name of the drift file<br>
+<tt>/etc/ntp.keys</tt> - the default name of the key file
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpdsim - Network Time Protocol (NTP) Simulator</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntpdsim</tt> - Network Time Protocol (NTP) Simulator</h3>
- <img src="pic/oz2.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
- <p>All in a row.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">15:56</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
- <h4>Table of Contents</h4>
- <li><a href="#description">Description</a><br>
- <li><a href="#configuration">Configuration</a>
- <li><a href="#sample">Sample Configuration File</a>
- </ul>
- <h4 id="description">Description</h4>
-
<p>The ntpdsim program is used to simulate and study the behavior of an NTP daemon that derives its time from a number of different simulated time sources (servers). Each simulated server can be configured to have a different time offset, frequency offset, propagation delay, processing delay, network jitter and oscillator wander.</p>
-
<p>The ntpdsim program runs all the same selection, mitigation, and discipline
- algorithms as the actual ntpd daemon at the client. (It actually
- uses the same code). However, the input/output routines and servers are simulated.
- That is, instead of sending the client messages over the network
- to the actual servers, the client messages are intercepted by the ntpdsim
- program, which then generates the replies to those messages. The reply messages
- are carefully "inserted" into the input queue of the client at the right time
- according to the specified server properties (like propagation delay).</p>
-
<p>Each simulated server runs according to a specified script that describes the server properties at a particular time. Each script consists of a series of consecutive acts. Each act runs for a particular duration and specifies the frequency offset, propagation delay, processing delay, network jitter and oscillator wander of the server for that duration. Once the duration of an act expires, the simulated server reconfigures itself according to the properties specified in the next act.</p>
- <h4 id="configuration">Configuration</h4>
-
<p>The ntpdsim program is configured by providing a configuration file at startup. The crux of the simulator configuration is specified using a <tt>simulate</tt> command, the syntax of which is given below. Note that all time quantities are in seconds and all frequency quantities are in parts per million (PPM):</p>
-
<p><<i>simulate_command</i>> ::= <tt>simulate</tt> { <<i>init_statement_list</i>> <<i>server_list</i>> }<br>
- <<i>init_statement_list</i>> ::= <init_statement_list> <init_statement> | <init_statement><br>
- <<i>init_statement</i>> ::= <tt>beep_delay</tt> = <number> | <tt>simulation_duration</tt> = <number><br>
- <<i>server_list</i>> ::= <<i>server_list</i>> <server> | <server><br>
- <<i>server_list</i>> ::= <tt>server</tt> = <address> { <tt>server_offset</tt> = <number> <act_list> }<br>
- <<i>act_list</i>> ::= <<i>act_list</i>> <<i>act</i>> | <<i>act</i>><br>
- <<i>act</i>> ::= <tt>duration</tt> = <number> { <<i>act_stmt_list</i>> }<br>
- <<i>act_stmt_list</i>> ::= <<i>act_stmt_list</i>> <<i>act_stmt</i>> | <<i>act_stmt</i>><br>
- <<i>act_stmt</i>> ::= <tt>freq_offset</tt> = <number> | <tt>wander</tt> = <number> | <tt>jitter</tt> = <number> | <tt>prop_delay</tt> = <number> | <tt>proc_delay</tt> = <number></p>
-
<p>In addition to the simulate command, other standard NTP configuration commands can be specified. These commands have the same meaning as in the ntpd configuration. Note that newlines are <b>not</b> significant within the simulate command even though they are used to mark the end of a normal NTP configuration command.</p>
- <h4 id="sample">Sample Configuration File</h4>
-
<p>A sample ntpdsim configuration file is given below. It specifies two simulated servers, each of which has two acts.</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpdsim - Network Time Protocol (NTP) Simulator</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntpdsim</tt> - Network Time Protocol (NTP) Simulator</h3>
+<img src="pic/oz2.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
+<p>All in a row.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 14:31<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li><a href="#description">Description</a></li>
+ <li><a href="#configuration">Configuration</a></li>
+ <li><a href="#sample">Sample Configuration File</a></li>
+</ul>
+<h4 id="description">Description</h4>
+<p>The ntpdsim program is used to simulate and study the behavior of an NTP daemon that derives its time from a number of different simulated time sources (servers). Each simulated server can be configured to have a different time offset, frequency offset, propagation delay, processing delay, network jitter and oscillator wander.</p>
+<p>The ntpdsim program runs all the same selection, mitigation, and discipline
+ algorithms as the actual ntpd daemon at the client. (It actually
+ uses the same code). However, the input/output routines and servers are simulated.
+ That is, instead of sending the client messages over the network
+ to the actual servers, the client messages are intercepted by the ntpdsim
+ program, which then generates the replies to those messages. The reply messages
+ are carefully "inserted" into the input queue of the client at the right time
+ according to the specified server properties (like propagation delay).</p>
+<p>Each simulated server runs according to a specified script that describes the server properties at a particular time. Each script consists of a series of consecutive acts. Each act runs for a particular duration and specifies the frequency offset, propagation delay, processing delay, network jitter and oscillator wander of the server for that duration. Once the duration of an act expires, the simulated server reconfigures itself according to the properties specified in the next act.</p>
+<h4 id="configuration">Configuration</h4>
+<p>The ntpdsim program is configured by providing a configuration file at startup. The crux of the simulator configuration is specified using a <tt>simulate</tt> command, the syntax of which is given below. Note that all time quantities are in seconds and all frequency quantities are in parts per million (PPM):</p>
+<p><<i>simulate_command</i>> ::= <tt>simulate</tt> { <<i>init_statement_list</i>> <<i>server_list</i>> }<br>
+ <<i>init_statement_list</i>> ::= <init_statement_list> <init_statement> | <init_statement><br>
+ <<i>init_statement</i>> ::= <tt>beep_delay</tt> = <number> | <tt>simulation_duration</tt> = <number><br>
+ <<i>server_list</i>> ::= <<i>server_list</i>> <server> | <server><br>
+ <<i>server_list</i>> ::= <tt>server</tt> = <address> { <tt>server_offset</tt> = <number> <act_list> }<br>
+ <<i>act_list</i>> ::= <<i>act_list</i>> <<i>act</i>> | <<i>act</i>><br>
+ <<i>act</i>> ::= <tt>duration</tt> = <number> { <<i>act_stmt_list</i>> }<br>
+ <<i>act_stmt_list</i>> ::= <<i>act_stmt_list</i>> <<i>act_stmt</i>> | <<i>act_stmt</i>><br>
+ <<i>act_stmt</i>> ::= <tt>freq_offset</tt> = <number> | <tt>wander</tt> = <number> | <tt>jitter</tt> = <number> | <tt>prop_delay</tt> = <number> | <tt>proc_delay</tt> = <number></p>
+<p>In addition to the simulate command, other standard NTP configuration commands can be specified. These commands have the same meaning as in the ntpd configuration. Note that newlines are <b>not</b> significant within the simulate command even though they are used to mark the end of a normal NTP configuration command.</p>
+<h4 id="sample">Sample Configuration File</h4>
+<p>A sample ntpdsim configuration file is given below. It specifies two simulated servers, each of which has two acts.</p>
+<pre>
# Client configuration
disable kernel
server pogo
proc_delay = 0.001
}
}
- }
+ }
</pre>
- <hr>
- <address><a href="mailto:skamboj@udel.edu">Sachin Kamboj</a></address>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
+<hr>
+<address>
+<a href="mailto:skamboj@udel.edu">Sachin Kamboj</a>
+</address>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntpq - standard NTP query program</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntpq - standard NTP query program</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
-
- <body>
- <h3><tt>ntpq</tt> - standard NTP query program</h3>
- <img src="pic/bustardfly.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>A typical NTP monitoring packet</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->11-Apr-2010 20:18<!-- #EndDate -->
- UTC</p>
+<body>
+<h3><tt>ntpq</tt> - standard NTP query program</h3>
+<img src="pic/bustardfly.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>A typical NTP monitoring packet</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 14:40<!-- #EndDate -->
+ UTC</p>
<br clear="left">
- <h4>More Help</h4>
- <script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
- <hr>
- <h4>Synopsis</h4>
- <tt>ntpq [-inp] [-c <i>command</i>] [<i>host</i>] [...]</tt>
- <h4>Description</h4>
- <p>The <tt>ntpq</tt> utility program is used to monitor NTP daemon <tt>ntpd</tt> operations
- and determine performance. It uses the standard NTP mode 6 control
- message formats defined in Appendix B of the NTPv3 specification
- RFC1305. The same formats are used in NTPv4, although some of the
- variable names have changed and new ones added. The description
- on this page is for the NTPv4 variables.</p>
- <p>The program can be run either in interactive mode or controlled using command line arguments. Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options being available. The <tt>ntpq</tt> can also obtain and print a list of peers in a common format by sending multiple queries to the server.</p>
- <p>If one or more request options is included on the command line when <tt>ntpq</tt> is executed, each of the requests will be sent to the NTP servers running on each of the hosts given as command line arguments, or on localhost by default. If no request options are given, <tt>ntpq</tt> will attempt to read commands from the standard input and execute these on the NTP server running on the first host given on the command line, again defaulting to localhost when no other host is specified. <tt>ntpq</tt> will prompt for commands if the standard input is a terminal device.</p>
- <p><tt>ntpq</tt> uses NTP mode 6 packets to communicate with the NTP server, and hence can be used to query any compatible server on the network which permits it. Note that since NTP is a UDP protocol this communication will be somewhat unreliable, especially over large distances in terms of network topology. <tt>ntpq</tt> makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.</p>
- <p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
- <p>For examples and usage, see the <a href="debug.html">NTP Debugging Techniques</a> page.</p>
- <p>Command line options are described following. Specifying a command line option other than <tt>-i</tt> or <tt>-n</tt> will cause the specified query (queries) to be sent to the indicated host(s) immediately. Otherwise, <tt>ntpq</tt> will attempt to read interactive format commands from the standard input.</p>
- <dl>
- <dt><tt>-4</tt></dt>
- <dd>Force DNS resolution of following host names on the command line to the IPv4 namespace.</dd>
- <dt><tt>-6</tt></dt>
- <dd>Force DNS resolution of following host names on the command line to the IPv6 namespace.</dd>
- <dt><tt>-c</tt></dt>
- <dd>The following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). Multiple <tt>-c</tt> options may be given.</dd>
- <dt><tt>-d</tt></dt>
- <dd>Turn on debugging mode.</dd>
- <dt><tt>-i</tt></dt>
- <dd>Force <tt>ntpq</tt> to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.</dd>
- <dt><tt>-n</tt></dt>
- <dd>Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.</dd>
- <dt><tt>-p</tt></dt>
- <dd>Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the <tt>peers</tt> interactive command.</dd>
- </dl>
- <h4>Internal Commands</h4>
- <p>Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but optionally the output of individual commands may be sent to a file by appending a <tt>></tt>, followed by a file name, to the command line. A number of interactive format commands are executed entirely within the <tt>ntpq</tt> program itself and do not result in NTP mode-6 requests being sent to a server. These are described following.</p>
- <dl>
- <dt><tt>? [<i>command_keyword</i>]</tt><br>
- <tt>help [<i>command_keyword</i>]</tt></dt>
- <dd>A <tt>?</tt> by itself will print a list of all the command keywords known to <tt>ntpq</tt>. A <tt>?</tt> followed by a command keyword will print function and usage information about the command.</dd>
- <dt><tt>addvars <i>name</i> [ = <i>value</i>] [...]</tt><br>
- <tt>rmvars <i>name</i> [...]</tt><br>
- <tt>clearvars</tt></dt>
- <dd>The arguments to this command consist of a list of items of the form <tt><i>name</i> = <i>value</i></tt>, where the <tt>= <i>value</i></tt> is ignored, and can be omitted in read requests. <tt>ntpq</tt> maintains an internal list in which data to be included in control messages can be assembled, and sent using the <tt>readlist</tt> and <tt>writelist</tt> commands described below. The <tt>addvars</tt> command allows variables and optional values to be added to the list. If more than one variable is to be added, the list should be comma-separated and not contain white space. The <tt>rmvars</tt> command can be used to remove individual variables from the list, while the <tt>clearlist</tt> command removes all variables from the list.</dd>
- <dt><tt>cooked</tt></dt>
- <dd>Display server messages in prettyprint format.</dd>
- <dt><tt>debug more | less | off</tt></dt>
- <dd>Turns internal query program debugging on and off.</dd>
- <dt><tt>delay <i>milliseconds</i></tt></dt>
- <dd>Specify a time interval to be added to timestamps included in requests which require authentication. This is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. Actually the server does not now require timestamps in authenticated requests, so this command may be obsolete.</dd>
- <dt><tt>host <i>name</i></tt></dt>
- <dd>Set the host to which future queries will be sent. The name may be either a DNS name or a numeric address.</dd>
- <dt><tt>hostnames [yes | no]</tt></dt>
- <dd>If <tt>yes</tt> is specified, host names are printed in information displays. If <tt>no</tt> is specified, numeric addresses are printed instead. The default is <tt>yes</tt>, unless modified using the command line <tt>-n</tt> switch.</dd>
- <dt><tt>keyid <i>keyid</i></tt></dt>
- <dd>This command specifies the key number to be used to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose.</dd>
- <dt><tt>ntpversion 1 | 2 | 3 | 4</tt></dt>
- <dd>Sets the NTP version number which <tt>ntpq</tt> claims in packets. Defaults to 2, Note that mode-6 control messages (and modes, for that matter) didn't exist in NTP version 1.</dd>
- <dt><tt>passwd</tt></dt>
- <dd>This command prompts for a password to authenticate configuration requests. The password must correspond to the key configured for NTP server for this purpose.</dd>
- <dt><tt>quit</tt></dt>
- <dd>Exit <tt>ntpq</tt>.</dd>
- <dt><tt>raw</tt></dt>
- <dd>Display server messages as received and without reformatting.</dd>
- <dt><tt>timeout <i>millseconds</i></tt></dt>
- <dd>Specify a timeout period for responses to server queries. The default is about 5000 milliseconds. Note that since <tt>ntpq</tt> retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.</dd>
- </dl>
- <h4>Control Message Commands</h4>
- <p>Association IDs are used to identify system, peer and clock variables. System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace. Most control commands send a single mode-6 message to the server and expect a single response message. The exceptions are the <tt>peers</tt> command, which sends a series of messages, and the <tt>mreadlist</tt> and <tt>mreadvar</tt> commands, which iterate over a range of associations.</p>
- <dl>
- <dt id="as"><tt>associations</tt></dt>
- <dd>Display a list of mobilized associations in the form</dd>
- <dd><tt>ind assid status conf reach auth condition last_event cnt</tt></dd>
- <dd>
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>ind</tt></td>
- <td>index on this list</td>
- </tr>
- <tr>
- <td><tt>assid</tt></td>
- <td>association ID</td>
- </tr>
- <tr>
- <td><tt>status</tt></td>
- <td><a href="decode.html#peer">peer status word</a></td>
- </tr>
- <tr>
- <td><tt>conf</tt></td>
- <td><tt>yes</tt>: persistent, <tt>no</tt>: ephemeral</td>
- </tr>
- <tr>
- <td><tt>reach</tt></td>
- <td><tt>yes</tt>: reachable, <tt>no</tt>: unreachable</td>
- </tr>
- <tr>
- <td><tt>auth</tt></td>
- <td><tt>ok</tt>, <tt>yes</tt>, <tt>bad</tt> and <tt>none</tt></td>
- </tr>
- <tr>
- <td><tt>condition</tt></td>
- <td>selection status (see the <tt>select</tt> field of the <a href="decode.html#peer">peer status word</a>)</td>
- </tr>
- <tr>
- <td><tt>last_event</tt></td>
- <td>event report (see the <tt>event</tt> field of the <a href="decode.html#peer">peer status word</a>)</td>
- </tr>
- <tr>
- <td><tt>cnt</tt></td>
- <td>event count (see the <tt>count</tt> field of the <a href="decode.html#peer">peer status word</a>)</td>
- </tr>
- </table>
- </dd>
- <dt><tt>clockvar <i>assocID</i> [<i>name</i> [ = <i>value</i> [...]] [...]</tt><br>
- <tt>cv <i>assocID</i> [<i>name</i> [ = <i>value</i> [...] ][...]</tt></dt>
- <dd>Display a list of <a href="#clock">clock variables</a> for those assocations supporting a reference clock.</dd>
- <dt><tt>:config [...]</tt></dt>
- <dd>Send the remainder of the command line, including whitespace, to the server as a run-time configuration command in the same format as the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.</dd>
- <dt><tt>config-from-file <i>filename</i></tt></dt>
- <dd>Send the each line of <i>filename</i> to the server as run-time configuration commands in the same format as the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.</dd>
- <dt><tt>keyid</tt></dt>
- <dd>Specify the key ID to use for write requests.</dd>
- <dt><tt>lassociations</tt></dt>
- <dd>Perform the same function as the associations command, execept display mobilized and unmobilized associations.</dd>
- <dt id="monstats"><tt>monstats</tt></dt>
- <dd>Display monitor facility statistics.</dd>
- <dt id="mrulist"><tt>mrulist [limited | kod | mincount=<i>count</i> | laddr=<i>localaddr</i> | sort=<i>sortorder</i> | resany=<i>hexmask</i> | resall=<i>hexmask</i>]</tt></dt>
- <dd>Obtain and print traffic counts collected and maintained by the monitor facility. With the exception of
- <tt>sort=<i>sortorder</i></tt>, the options filter the list returned by <tt>ntpd</tt>. The <tt>limited</tt>
- and <tt>kod</tt> options return only entries representing client addresses from which the last packet
- received triggered either discarding or a KoD response. The <tt>mincount=<i>count</i></tt> option filters entries
- representing less than <tt><i>count</i></tt> packets. The <tt>laddr=<i>localaddr</i></tt> option filters entries
- for packets received on any local address other than <tt><i>localaddr</i></tt>. <tt>resany=<i>hexmask</i></tt> and
- <tt>resall=<i>hexmask</i></tt> filter entries containing none or less than all, respectively, of the bits in
- <tt><i>hexmask</i></tt>, which must begin with <tt>0x</tt>.</dd> The <tt><i>sortorder</i></tt> defaults to
- <tt>lstint</tt> and may be any of <tt>addr</tt>, <tt>count</tt>, <tt>avgint</tt>, <tt>lstint</tt>, or any of
- those preceded by a minus sign (hyphen) to reverse the sort order. The output columns are:
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Column</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>lstint</tt></td>
- <td>Interval in s between the receipt of the most recent packet from this address and the completion of the
- retrieval of the MRU list by <tt>ntpq</tt>.</td>
- </tr>
- <tr>
- <td><tt>avgint</tt></td>
- <td>Average interval in s between packets from this address.</td>
- </tr>
- <tr>
- <td><tt>rstr</tt></td>
- <td>Restriction flags associated with this address. Most are copied unchanged from the matching <tt>restrict</tt>
- command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this
- address triggered a rate control response.</td>
- </tr>
- <tr>
- <td><tt>r</tt></td>
- <td>Rate control indicator, either a period, <tt>L</tt> or <tt>K</tt> for no rate control response,
- rate limiting by discarding, or rate limiting with a KoD response, respectively.</td>
- </tr>
- <tr>
- <td><tt>m</tt></td>
- <td>Packet mode.</dt>
- </tr>
- <tr>
- <td><tt>v</tt></td>
- <td>Packet version number.</td>
- </tr>
- <tr>
- <td><tt>count</tt></td>
- <td>Packets received from this address.</td>
- </tr>
- <tr>
- <td><tt>rport</tt></td>
- <td>Source port of last packet from this address.</td>
- </tr>
- <tr>
- <td><tt>remote address</tt></td>
- <td>DNS name, numeric address, or address followed by claimed DNS name which
- could not be verified in parentheses.</dt>
- </tr>
- </table>
- </dd>
- <dt><tt>mreadvar <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt><br>
- <tt>mrv <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt></dt>
- <dd>Perform the same function as the <tt>readvar</tt> command, except for a range of association IDs. This range is determined from the association list cached by the most recent <tt>associations</tt> command.</dd>
- <dt><tt>passociations</tt></dt>
- <dd>Perform the same function as the <tt>associations command</tt>, except that it uses previously stored data rather than making a new query.</dd>
- <dt><tt>passwd</tt></dt>
- <dd>Specify the password to use for write requests.</dd>
- <dt id="pe"><tt>peers</tt></dt>
- <dd>Display a list of peers in the form</dd>
- <dd><tt>[tally]remote refid st t when pool reach delay offset jitter</tt></dd>
- <dd>
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>[tally]</tt></td>
- <td>single-character code indicating current value of the <tt>select</tt> field of the <a href="decode.html#peer">peer status word</a></td>
- </tr>
- <tr>
- <td><tt>remote</tt></td>
- <td>host name (or IP number) of peer</td>
- </tr>
- <tr>
- <td><tt>refid</tt></td>
- <td>association ID or <a href="decode.html#kiss">kiss code</a></td>
- </tr>
- <tr>
- <td><tt>st</tt></td>
- <td>stratum</td>
- </tr>
- <tr>
- <td><tt>t</tt></td>
- <td><tt>u</tt>: unicast or manycast client, <tt>b</tt>:
-broadcast or multicast client, <tt>l</tt>: local (reference clock),
-<tt>s</tt>: symmetric (peer), <tt>A</tt>: manycast server, <tt>B</tt>:
-broadcast server, <tt>M</tt>: multicast server</td>
- </tr>
- <tr>
- <td><tt>when</tt></td>
- <td>sec/min/hr since last received packet</td>
- </tr>
- <tr>
- <td><tt>poll</tt></td>
- <td>poll interval (log<sub>2</sub> s)</td>
- </tr>
- <tr>
- <td><tt>reach</tt></td>
- <td>reach shift register (octal)</td>
- </tr>
- <tr>
- <td><tt>delay</tt></td>
- <td>roundtrip delay</td>
- </tr>
- <tr>
- <td><tt>offset</tt></td>
- <td>offset</td>
- </tr>
- <tr>
- <td><tt>jitter</tt></td>
- <td>jitter</td>
- </tr>
- </table>
- </dd>
- <dt id="rv"><tt>readvar <i>assocID</i> <i>name</i> [ = <i>value</i> ] [,...]</tt><br>
- <tt>rv <i>assocID</i> [ <i>name</i> ] [,...]</tt></dt>
- <dd>Display the specified variables. If <tt><i>assocID</i></tt> is zero, the
- variables are from the <a href="#system">system variables</a> name space,
- otherwise they are from the <a href="#peer">peer variables</a> name space.
- The <tt><i>assocID</i></tt> is required, as the same name can occur in both spaces. If no <tt><i>name</i></tt> is
- included, all operative variables in the name space are displayed.
- In this case only, if the <tt><i>assocID</i></tt> is omitted, it is assumed zero. Multiple
- names are specified with comma separators and without whitespace.
- Note that time values are represented in milliseconds and frequency
- values in parts-per-million (PPM). Some NTP timestamps are represented
- in the format YYYYMMDDTTTT, where YYYY is the year, MM the month
- of year, DD the day of month and TTTT the time of day.</dd>
- <dt id="saveconfig"><tt>saveconfig <i>filename</i></tt></dt>
- <dd>Write the current configuration, including any runtime modifications given with <tt>:config</tt> or <tt>config-from-file</tt>, to the ntpd host's file <i>filename</i>. This command will be rejected by the server unless <a href="miscopt.html#saveconfigdir">saveconfigdir</a> appears in the <tt>ntpd</tt> configuration file. <i>filename</i> can use strftime() format specifiers to substitute the current date and time, for example, <tt>saveconfig ntp-%Y%m%d-%H%M%S.conf</tt>. The filename used is stored in system variable <tt>savedconfig</tt>. Authentication is required.</dd>
- <dt><tt>writevar <i>assocID</i> <i>name</i> = <i>value</i> [,...]</tt></dt>
- <dd>Write the specified variables. If the <tt><i>assocID</i></tt> is zero, the variables
- are from the <a href="#system">system variables</a> name space, otherwise they are from the <a href="#peer">peer variables</a> name space. The <tt><i>assocID</i></tt> is required, as the same name can occur
- in both spaces.</dd>
- <dt id="sysstats"><tt>sysstats</tt>
- <dd>Print statistics counters maintained in the protocol module.</dd>
- </dl>
- <h4 id="status">Status Words and Kiss Codes</h4>
- <p>The current state of the operating program is shown in a set of status words maintained by the system and each association separately. These words are displayed in the <tt>rv</tt> and <tt>as</tt> commands both in hexadecimal and decoded short tip strings. The codes, tips and short explanations are on the <a href="decode.html">Event Messages and Status Words</a> page. The page also includes a list of system and peer messages, the code for the latest of which is included in the status word.</p>
- <p>Information resulting from protocol machine state transitions is displayed using an informal set of ASCII strings called <a href="decode.html#kiss">kiss codes</a>. The original purpose was for kiss-o'-death (KoD) packets sent by the server to advise the client of an unusual condition. They are now displayed, when appropriate, in the reference identifier field in various billboards.</p>
- <h4 id="system">System Variables</h4>
- <p>The following system variables appear in the <tt>rv</tt> billboard. Not all variables are displayed in some configurations.</p>
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>status</tt></td>
- <td><a href="decode.html#sys">system status word</a></td>
- </tr>
- <tr>
- <td><tt>version</tt></td>
- <td>NTP software version and build time</td>
- </tr>
- <tr>
- <td><tt>processor</tt></td>
- <td>hardware platform and version</td>
- </tr>
- <tr>
- <td><tt>system</tt></td>
- <td>operating system and version</td>
- </tr>
- <tr>
- <td><tt>leap</tt></td>
- <td>leap warning indicator (0-3)</td>
- </tr>
- <tr>
- <td><tt>stratum</tt></td>
- <td>stratum (1-15)</td>
- </tr>
- <tr>
- <td><tt>precision</tt></td>
- <td>precision (log<sub>2</sub> s)</td>
- </tr>
- <tr>
- <td><tt>rootdelay</tt></td>
- <td>total roundtrip delay to the primary reference clock</td>
- </tr>
- <tr>
- <td><tt>rootdisp</tt></td>
- <td>total dispersion to the primary reference clock</td>
- </tr>
- <tr>
- <td><tt>peer</tt></td>
- <td>system peer association ID</td>
- </tr>
- <tr>
- <td><tt>tc</tt></td>
- <td>time constant and poll exponent (log<sub>2</sub> s) (3-17)</td>
- </tr>
- <tr>
- <td><tt>mintc</tt></td>
- <td>minimum time constant (log<sub>2</sub> s) (3-10)</td>
- </tr>
- <tr>
- <td><tt>clock</tt></td>
- <td>date and time of day</td>
- </tr>
- <tr>
- <td><tt>refid</tt></td>
- <td>reference ID or <a href="decode.html#kiss">kiss code</a></td>
- </tr>
- <tr>
- <td><tt>reftime</tt></td>
- <td>reference time</td>
- </tr>
- <tr>
- <td><tt>offset</tt></td>
- <td>combined time offset</td>
- </tr>
- <tr>
- <td><tt>sys_jitter</tt></td>
- <td>combined system jitter</td>
- </tr>
- <tr>
- <td><tt>frequency</tt></td>
- <td>clock frequency offset (PPM)</td>
- </tr>
- <tr>
- <td><tt>clk_wander</tt></td>
- <td>clock frequency wander (PPM)</td>
- </tr>
- <tr>
- <td><tt>clk_jitter</tt></td>
- <td>clock jitter</td>
- </tr>
- <tr>
- <td><tt>tai</tt></td>
- <td>TAI-UTC offset (s)</td>
- </tr>
- <tr>
- <td><tt>leapsec</tt></td>
- <td>NTP seconds when the next leap second is/was inserted</td>
- </tr>
- <tr>
- <td><tt>expire</tt></td>
- <td>NTP seconds when the NIST leapseconds file expires</td>
- </tr>
- </table>
- <dl>
- <dt>The jitter and wander statistics are exponentially-weighted RMS averages.
- The system jitter is defined in the NTPv4 specification; the
- clock jitter statistic is computed by the clock discipline module.</dt>
- <dt>When the NTPv4 daemon is compiled with the OpenSSL software library, additional
- system variables are displayed, including some or all of the following, depending
- on the particular Autokey dance:</dt>
- </dl>
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>host</tt></td>
- <td>Autokey host name</td>
- </tr>
- <tr>
- <td><tt>group</tt></td>
- <td>Autokey group name</td>
- </tr>
- <tr>
- <td><tt>flags</tt></td>
- <td>host flags (see Autokey specification)</td>
- </tr>
- <tr>
- <td><tt>digest</tt></td>
- <td>OpenSSL message digest algorithm</td>
- </tr>
- <tr>
- <td><tt>signature</tt></td>
- <td>OpenSSL digest/signature scheme</td>
- </tr>
- <tr>
- <td><tt>update</tt></td>
- <td>NTP seconds at last signature update</td>
- </tr>
- <tr>
- <td><tt>cert</tt></td>
- <td>certificate subject, issuer and certificate flags</td>
- </tr>
- <tr>
- <td><tt>until</tt></td>
- <td>NTP seconds when the certificate expires</td>
- </tr>
- </table>
- <h4 id="peer">Peer Variables</h4>
- <p>The following system variables apear in the <tt>rv</tt> billboard for each association. Not all variables are displayed in some configurations.</p>
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>associd</tt></td>
- <td>association ID</td>
- </tr>
- <tr>
- <td><tt>status</tt></td>
- <td><a href="decode.html#peer">peer status word</a></td>
- </tr>
- <tr>
- <td><tt>srcadr<br>
- srcport</tt></td>
- <td>source (remote) IP address and port</td>
- </tr>
- <tr>
- <td><tt>dstadr<br>
- dstport</tt></td>
- <td>destination (local) IP address and port</td>
- </tr>
- <tr>
- <td><tt>leap</tt></td>
- <td>leap indicator (0-3)</td>
- </tr>
- <tr>
- <td><tt>stratum</tt></td>
- <td>stratum (0-15)</td>
- </tr>
- <tr>
- <td><tt>precision</tt></td>
- <td>precision (log<sub>2</sub> s)</td>
- </tr>
- <tr>
- <td><tt>rootdelay</tt></td>
- <td>total roundtrip delay to the primary reference clock</td>
- </tr>
- <tr>
- <td><tt>rootdisp</tt></td>
- <td>total root dispersion to the primary reference clock</td>
- </tr>
- <tr>
- <td><tt>refid</tt></td>
- <td>reference ID or <a href="decode.html#kiss">kiss code</a></td>
- </tr>
- <tr>
- <td><tt>reftime</tt></td>
- <td>reference time</td>
- </tr>
- <tr>
- <td><tt>reach</tt></td>
- <td>reach register (octal)</td>
- </tr>
- <tr>
- <td><tt>unreach</tt></td>
- <td>unreach counter</td>
- </tr>
- <tr>
- <td><tt>hmode</tt></td>
- <td>host mode (1-6)</td>
- </tr>
- <tr>
- <td><tt>pmode</tt></td>
- <td>peer mode (1-5)</td>
- </tr>
- <tr>
- <td><tt>hpoll</tt></td>
- <td>host poll exponent (log<sub>2</sub> s) (3-17)</td>
- </tr>
- <tr>
- <td><tt>ppoll</tt></td>
- <td>peer poll exponent (log<sub>2</sub> s) (3-17)</td>
- </tr>
- <tr>
- <td><tt>headway</tt></td>
- <td>headway (see <a href="rate.html">Rate Management and the Kiss-o'-Death Packet)</a></td>
- </tr>
- <tr>
- <td><tt>flash</tt></td>
- <td><a href="decode.html#flash">flash status word</a></td>
- </tr>
- <tr>
- <td><tt>offset</tt></td>
- <td>filter offset</td>
- </tr>
- <tr>
- <td><tt>delay</tt></td>
- <td>filter delay</td>
- </tr>
- <tr>
- <td><tt>dispersion</tt></td>
- <td>filter dispersion</td>
- </tr>
- <tr>
- <td><tt>jitter</tt></td>
- <td>filter jitter</td>
- </tr>
- <tr>
- <td><tt>bias</tt></td>
- <td>unicast/broadcast bias</td>
- </tr>
- <tr>
- <td><tt>xleave</tt></td>
- <td>interleave delay (see <a href="xleave.html">NTP Interleaved Modes</a>)</td>
- </tr>
- </table>
- <p>The bias vaqriable is calculated when the first broadcast packet is received
- after the calibration volley. It represents the offset of the broadcast
- subgraph relative to the unicast subgraph. The xleave variable appears
- only the interleaved symmetric and ingterleaved modes. It represents
- the internal queueing, buffering and transmission delays for the preceeding
- packet.</p>
- <p>When the NTPv4 daemon is compiled with the OpenSSL software library, additional peer variables are displayed, including the following:</p>
+<h4>More Help</h4>
+<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
+<hr>
+<h4>Synopsis</h4>
+<tt>ntpq [-inp] [-c <i>command</i>] [<i>host</i>] [...]</tt>
+<h4>Description</h4>
+<p>The <tt>ntpq</tt> utility program is used to monitor NTP daemon <tt>ntpd</tt> operations
+ and determine performance. It uses the standard NTP mode 6 control
+ message formats defined in Appendix B of the NTPv3 specification
+ RFC1305. The same formats are used in NTPv4, although some of the
+ variable names have changed and new ones added. The description
+ on this page is for the NTPv4 variables.</p>
+<p>The program can be run either in interactive mode or controlled using command line arguments. Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options being available. The <tt>ntpq</tt> can also obtain and print a list of peers in a common format by sending multiple queries to the server.</p>
+<p>If one or more request options is included on the command line when <tt>ntpq</tt> is executed, each of the requests will be sent to the NTP servers running on each of the hosts given as command line arguments, or on localhost by default. If no request options are given, <tt>ntpq</tt> will attempt to read commands from the standard input and execute these on the NTP server running on the first host given on the command line, again defaulting to localhost when no other host is specified. <tt>ntpq</tt> will prompt for commands if the standard input is a terminal device.</p>
+<p><tt>ntpq</tt> uses NTP mode 6 packets to communicate with the NTP server, and hence can be used to query any compatible server on the network which permits it. Note that since NTP is a UDP protocol this communication will be somewhat unreliable, especially over large distances in terms of network topology. <tt>ntpq</tt> makes one attempt to retransmit requests, and will time requests out if the remote host is not heard from within a suitable timeout time.</p>
+<p>Note that in contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</p>
+<p>For examples and usage, see the <a href="debug.html">NTP Debugging Techniques</a> page.</p>
+<p>Command line options are described following. Specifying a command line option other than <tt>-i</tt> or <tt>-n</tt> will cause the specified query (queries) to be sent to the indicated host(s) immediately. Otherwise, <tt>ntpq</tt> will attempt to read interactive format commands from the standard input.</p>
+<dl>
+ <dt><tt>-4</tt></dt>
+ <dd>Force DNS resolution of following host names on the command line to the IPv4 namespace.</dd>
+ <dt><tt>-6</tt></dt>
+ <dd>Force DNS resolution of following host names on the command line to the IPv6 namespace.</dd>
+ <dt><tt>-c</tt></dt>
+ <dd>The following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host(s). Multiple <tt>-c</tt> options may be given.</dd>
+ <dt><tt>-d</tt></dt>
+ <dd>Turn on debugging mode.</dd>
+ <dt><tt>-i</tt></dt>
+ <dd>Force <tt>ntpq</tt> to operate in interactive mode. Prompts will be written to the standard output and commands read from the standard input.</dd>
+ <dt><tt>-n</tt></dt>
+ <dd>Output all host addresses in dotted-quad numeric format rather than converting to the canonical host names.</dd>
+ <dt><tt>-p</tt></dt>
+ <dd>Print a list of the peers known to the server as well as a summary of their state. This is equivalent to the <tt>peers</tt> interactive command.</dd>
+</dl>
+<h4>Internal Commands</h4>
+<p>Interactive format commands consist of a keyword followed by zero to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. The output of a command is normally sent to the standard output, but optionally the output of individual commands may be sent to a file by appending a <tt>></tt>, followed by a file name, to the command line. A number of interactive format commands are executed entirely within the <tt>ntpq</tt> program itself and do not result in NTP mode-6 requests being sent to a server. These are described following.</p>
+<dl>
+ <dt><tt>? [<i>command_keyword</i>]</tt><br>
+ <tt>help [<i>command_keyword</i>]</tt></dt>
+ <dd>A <tt>?</tt> by itself will print a list of all the command keywords known to <tt>ntpq</tt>. A <tt>?</tt> followed by a command keyword will print function and usage information about the command.</dd>
+ <dt><tt>addvars <i>name</i> [ = <i>value</i>] [...]</tt><br>
+ <tt>rmvars <i>name</i> [...]</tt><br>
+ <tt>clearvars</tt></dt>
+ <dd>The arguments to this command consist of a list of items of the form <tt><i>name</i> = <i>value</i></tt>, where the <tt>= <i>value</i></tt> is ignored, and can be omitted in read requests. <tt>ntpq</tt> maintains an internal list in which data to be included in control messages can be assembled, and sent using the <tt>readlist</tt> and <tt>writelist</tt> commands described below. The <tt>addvars</tt> command allows variables and optional values to be added to the list. If more than one variable is to be added, the list should be comma-separated and not contain white space. The <tt>rmvars</tt> command can be used to remove individual variables from the list, while the <tt>clearlist</tt> command removes all variables from the list.</dd>
+ <dt><tt>cooked</tt></dt>
+ <dd>Display server messages in prettyprint format.</dd>
+ <dt><tt>debug more | less | off</tt></dt>
+ <dd>Turns internal query program debugging on and off.</dd>
+ <dt><tt>delay <i>milliseconds</i></tt></dt>
+ <dd>Specify a time interval to be added to timestamps included in requests which require authentication. This is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. Actually the server does not now require timestamps in authenticated requests, so this command may be obsolete.</dd>
+ <dt><tt>host <i>name</i></tt></dt>
+ <dd>Set the host to which future queries will be sent. The name may be either a DNS name or a numeric address.</dd>
+ <dt><tt>hostnames [yes | no]</tt></dt>
+ <dd>If <tt>yes</tt> is specified, host names are printed in information displays. If <tt>no</tt> is specified, numeric addresses are printed instead. The default is <tt>yes</tt>, unless modified using the command line <tt>-n</tt> switch.</dd>
+ <dt><tt>keyid <i>keyid</i></tt></dt>
+ <dd>This command specifies the key number to be used to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose.</dd>
+ <dt><tt>ntpversion 1 | 2 | 3 | 4</tt></dt>
+ <dd>Sets the NTP version number which <tt>ntpq</tt> claims in packets. Defaults to 2, Note that mode-6 control messages (and modes, for that matter) didn't exist in NTP version 1.</dd>
+ <dt><tt>passwd</tt></dt>
+ <dd>This command prompts for a password to authenticate configuration requests. The password must correspond to the key configured for NTP server for this purpose.</dd>
+ <dt><tt>quit</tt></dt>
+ <dd>Exit <tt>ntpq</tt>.</dd>
+ <dt><tt>raw</tt></dt>
+ <dd>Display server messages as received and without reformatting.</dd>
+ <dt><tt>timeout <i>millseconds</i></tt></dt>
+ <dd>Specify a timeout period for responses to server queries. The default is about 5000 milliseconds. Note that since <tt>ntpq</tt> retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.</dd>
+</dl>
+<h4>Control Message Commands</h4>
+<p>Association IDs are used to identify system, peer and clock variables. System variables are assigned an association ID of zero and system name space, while each association is assigned a nonzero association ID and peer namespace. Most control commands send a single mode-6 message to the server and expect a single response message. The exceptions are the <tt>peers</tt> command, which sends a series of messages, and the <tt>mreadlist</tt> and <tt>mreadvar</tt> commands, which iterate over a range of associations.</p>
+<dl>
+ <dt id="as"><tt>associations</tt></dt>
+ <dd>Display a list of mobilized associations in the form</dd>
+ <dd><tt>ind assid status conf reach auth condition last_event cnt</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>ind</tt></td>
+ <td>index on this list</td>
+ </tr>
+ <tr>
+ <td><tt>assid</tt></td>
+ <td>association ID</td>
+ </tr>
+ <tr>
+ <td><tt>status</tt></td>
+ <td><a href="decode.html#peer">peer status word</a></td>
+ </tr>
+ <tr>
+ <td><tt>conf</tt></td>
+ <td><tt>yes</tt>: persistent, <tt>no</tt>: ephemeral</td>
+ </tr>
+ <tr>
+ <td><tt>reach</tt></td>
+ <td><tt>yes</tt>: reachable, <tt>no</tt>: unreachable</td>
+ </tr>
+ <tr>
+ <td><tt>auth</tt></td>
+ <td><tt>ok</tt>, <tt>yes</tt>, <tt>bad</tt> and <tt>none</tt></td>
+ </tr>
+ <tr>
+ <td><tt>condition</tt></td>
+ <td>selection status (see the <tt>select</tt> field of the <a href="decode.html#peer">peer status word</a>)</td>
+ </tr>
+ <tr>
+ <td><tt>last_event</tt></td>
+ <td>event report (see the <tt>event</tt> field of the <a href="decode.html#peer">peer status word</a>)</td>
+ </tr>
+ <tr>
+ <td><tt>cnt</tt></td>
+ <td>event count (see the <tt>count</tt> field of the <a href="decode.html#peer">peer status word</a>)</td>
+ </tr>
+ </table>
+ </dd>
+ <dt><tt>clockvar <i>assocID</i> [<i>name</i> [ = <i>value</i> [...]] [...]</tt><br>
+ <tt>cv <i>assocID</i> [<i>name</i> [ = <i>value</i> [...] ][...]</tt></dt>
+ <dd>Display a list of <a href="#clock">clock variables</a> for those assocations supporting a reference clock.</dd>
+ <dt><tt>:config [...]</tt></dt>
+ <dd>Send the remainder of the command line, including whitespace, to the server as a run-time configuration command in the same format as the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.</dd>
+ <dt><tt>config-from-file <i>filename</i></tt></dt>
+ <dd>Send the each line of <i>filename</i> to the server as run-time configuration commands in the same format as the configuration file. This command is experimental until further notice and clarification. Authentication is of course required.</dd>
+ <dt><tt>keyid</tt></dt>
+ <dd>Specify the key ID to use for write requests.</dd>
+ <dt><tt>lassociations</tt></dt>
+ <dd>Perform the same function as the associations command, execept display mobilized and unmobilized associations.</dd>
+ <dt id="monstats"><tt>monstats</tt></dt>
+ <dd>Display monitor facility statistics.</dd>
+ <dt id="mrulist"><tt>mrulist [limited | kod | mincount=<i>count</i> | laddr=<i>localaddr</i> | sort=<i>sortorder</i> | resany=<i>hexmask</i> | resall=<i>hexmask</i>]</tt></dt>
+ <dd>Obtain and print traffic counts collected and maintained by the monitor facility. With the exception of <tt>sort=<i>sortorder</i></tt>, the options filter the list returned by <tt>ntpd</tt>. The <tt>limited</tt> and <tt>kod</tt> options return only entries representing client addresses from which the last packet received triggered either discarding or a KoD response. The <tt>mincount=<i>count</i></tt> option filters entries representing less than <tt><i>count</i></tt> packets. The <tt>laddr=<i>localaddr</i></tt> option filters entries for packets received on any local address other than <tt><i>localaddr</i></tt>. <tt>resany=<i>hexmask</i></tt> and <tt>resall=<i>hexmask</i></tt> filter entries containing none or less than all, respectively, of the bits in <tt><i>hexmask</i></tt>, which must begin with <tt>0x</tt>.</dd>
+ <dd>The <tt><i>sortorder</i></tt> defaults to <tt>lstint</tt> and may be any of <tt>addr</tt>, <tt>count</tt>, <tt>avgint</tt>, <tt>lstint</tt>, or any of those preceded by a minus sign (hyphen) to reverse the sort order. The output columns are:
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Column</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>lstint</tt></td>
+ <td>Interval in s between the receipt of the most recent packet from this address and the completion of the
+ retrieval of the MRU list by <tt>ntpq</tt>.</td>
+ </tr>
+ <tr>
+ <td><tt>avgint</tt></td>
+ <td>Average interval in s between packets from this address.</td>
+ </tr>
+ <tr>
+ <td><tt>rstr</tt></td>
+ <td>Restriction flags associated with this address. Most are copied unchanged from the matching <tt>restrict</tt> command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless the last packet from this
+ address triggered a rate control response.</td>
+ </tr>
+ <tr>
+ <td><tt>r</tt></td>
+ <td>Rate control indicator, either a period, <tt>L</tt> or <tt>K</tt> for no rate control response,
+ rate limiting by discarding, or rate limiting with a KoD response, respectively.</td>
+ </tr>
+ <tr>
+ <td><tt>m</tt></td>
+ <td>Packet mode.</td>
+ </tr>
+ <tr>
+ <td><tt>v</tt></td>
+ <td>Packet version number.</td>
+ </tr>
+ <tr>
+ <td><tt>count</tt></td>
+ <td>Packets received from this address.</td>
+ </tr>
+ <tr>
+ <td><tt>rport</tt></td>
+ <td>Source port of last packet from this address.</td>
+ </tr>
+ <tr>
+ <td><tt>remote address</tt></td>
+ <td>DNS name, numeric address, or address followed by claimed DNS name which
+ could not be verified in parentheses.</td>
+ </tr>
+ </table>
+ </dd>
+ <dt><tt>mreadvar <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt></dt>
+ <dt><tt>mrv <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt></dt>
+ <dd>Perform the same function as the <tt>readvar</tt> command, except for a range of association IDs. This range is determined from the association list cached by the most recent <tt>associations</tt> command.</dd>
+ <dt><tt>passociations</tt></dt>
+ <dd>Perform the same function as the <tt>associations command</tt>, except that it uses previously stored data rather than making a new query.</dd>
+ <dt><tt>passwd</tt></dt>
+ <dd>Specify the password to use for write requests.</dd>
+ <dt id="pe"><tt>peers</tt></dt>
+ <dd>Display a list of peers in the form</dd>
+ <dd><tt>[tally]remote refid st t when pool reach delay offset jitter</tt></dd>
+ <dd>
+ <table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>[tally]</tt></td>
+ <td>single-character code indicating current value of the <tt>select</tt> field of the <a href="decode.html#peer">peer status word</a></td>
+ </tr>
+ <tr>
+ <td><tt>remote</tt></td>
+ <td>host name (or IP number) of peer</td>
+ </tr>
+ <tr>
+ <td><tt>refid</tt></td>
+ <td>association ID or <a href="decode.html#kiss">kiss code</a></td>
+ </tr>
+ <tr>
+ <td><tt>st</tt></td>
+ <td>stratum</td>
+ </tr>
+ <tr>
+ <td><tt>t</tt></td>
+ <td><tt>u</tt>: unicast or manycast client, <tt>b</tt>:
+ broadcast or multicast client, <tt>l</tt>: local (reference clock), <tt>s</tt>: symmetric (peer), <tt>A</tt>: manycast server, <tt>B</tt>:
+ broadcast server, <tt>M</tt>: multicast server</td>
+ </tr>
+ <tr>
+ <td><tt>when</tt></td>
+ <td>sec/min/hr since last received packet</td>
+ </tr>
+ <tr>
+ <td><tt>poll</tt></td>
+ <td>poll interval (log<sub>2</sub> s)</td>
+ </tr>
+ <tr>
+ <td><tt>reach</tt></td>
+ <td>reach shift register (octal)</td>
+ </tr>
+ <tr>
+ <td><tt>delay</tt></td>
+ <td>roundtrip delay</td>
+ </tr>
+ <tr>
+ <td><tt>offset</tt></td>
+ <td>offset</td>
+ </tr>
+ <tr>
+ <td><tt>jitter</tt></td>
+ <td>jitter</td>
+ </tr>
+ </table>
+ </dd>
+ <dt id="rv"><tt>readvar <i>assocID</i> <i>name</i> [ = <i>value</i> ] [,...]</tt><br>
+ <tt>rv <i>assocID</i> [ <i>name</i> ] [,...]</tt></dt>
+ <dd>Display the specified variables. If <tt><i>assocID</i></tt> is zero, the
+ variables are from the <a href="#system">system variables</a> name space,
+ otherwise they are from the <a href="#peer">peer variables</a> name space.
+ The <tt><i>assocID</i></tt> is required, as the same name can occur in both spaces. If no <tt><i>name</i></tt> is
+ included, all operative variables in the name space are displayed.
+ In this case only, if the <tt><i>assocID</i></tt> is omitted, it is assumed zero. Multiple
+ names are specified with comma separators and without whitespace.
+ Note that time values are represented in milliseconds and frequency
+ values in parts-per-million (PPM). Some NTP timestamps are represented
+ in the format YYYYMMDDTTTT, where YYYY is the year, MM the month
+ of year, DD the day of month and TTTT the time of day.</dd>
+ <dt id="saveconfig"><tt>saveconfig <i>filename</i></tt></dt>
+ <dd>Write the current configuration, including any runtime modifications given with <tt>:config</tt> or <tt>config-from-file</tt>, to the ntpd host's file <i>filename</i>. This command will be rejected by the server unless <a href="miscopt.html#saveconfigdir">saveconfigdir</a> appears in the <tt>ntpd</tt> configuration file. <i>filename</i> can use strftime() format specifiers to substitute the current date and time, for example, <tt>saveconfig ntp-%Y%m%d-%H%M%S.conf</tt>. The filename used is stored in system variable <tt>savedconfig</tt>. Authentication is required.</dd>
+ <dt><tt>writevar <i>assocID</i> <i>name</i> = <i>value</i> [,...]</tt></dt>
+ <dd>Write the specified variables. If the <tt><i>assocID</i></tt> is zero, the variables are from the <a href="#system">system variables</a> name space, otherwise they are from the <a href="#peer">peer variables</a> name space. The <tt><i>assocID</i></tt> is required, as the same name can occur in both spaces.</dd>
+ <dt id="sysstats"><tt>sysstats</tt></dt>
+ <dd>Print statistics counters maintained in the protocol module.</dd>
+</dl>
+<h4 id="status">Status Words and Kiss Codes</h4>
+<p>The current state of the operating program is shown in a set of status words maintained by the system and each association separately. These words are displayed in the <tt>rv</tt> and <tt>as</tt> commands both in hexadecimal and decoded short tip strings. The codes, tips and short explanations are on the <a href="decode.html">Event Messages and Status Words</a> page. The page also includes a list of system and peer messages, the code for the latest of which is included in the status word.</p>
+<p>Information resulting from protocol machine state transitions is displayed using an informal set of ASCII strings called <a href="decode.html#kiss">kiss codes</a>. The original purpose was for kiss-o'-death (KoD) packets sent by the server to advise the client of an unusual condition. They are now displayed, when appropriate, in the reference identifier field in various billboards.</p>
+<h4 id="system">System Variables</h4>
+<p>The following system variables appear in the <tt>rv</tt> billboard. Not all variables are displayed in some configurations.</p>
<table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>flags</tt></td>
- <td>peer flags (see Autokey specification)</td>
- </tr>
- <tr>
- <td><tt>host</tt></td>
- <td>Autokey server name</td>
- </tr>
- <tr>
- <td><tt>flags</tt></td>
- <td>peer flags (see Autokey specification)</td>
- </tr>
- <tr>
- <td><tt>signature</tt></td>
- <td>OpenSSL digest/signature shceme</td>
- </tr>
- <tr>
- <td><tt>initsequence</tt></td>
- <td>initial key ID</td>
- </tr>
- <tr>
- <td><tt>initkey</tt></td>
- <td>initial key index</td>
- </tr>
- <tr>
- <td><tt>timestamp</tt></td>
- <td>Autokey signature timestamp</td>
- </tr>
- </table>
- <h4 id="clock">Clock Variables</h4>
- <p>The following clock variables apear in the <tt>cv</tt> billboard for each association with a reference clock. Not all variables are displayed in some configurations.</p>
- <table width="100%" border="1" cellspacing="2" cellpadding="2">
- <tr>
- <td>Variable</td>
- <td>Description</td>
- </tr>
- <tr>
- <td><tt>associd</tt></td>
- <td>association ID</td>
- </tr>
- <tr>
- <td><tt>status</tt></td>
- <td><a href="decode.html#clock">clock status word</a></td>
- </tr>
- <tr>
- <td><tt>device</tt></td>
- <td>device description</td>
- </tr>
- <tr>
- <td><tt>timecode</tt></td>
- <td>ASCII timecode string (specific to device)</td>
- </tr>
- <tr>
- <td><tt>poll</tt></td>
- <td>poll messages sent</td>
- </tr>
- <tr>
- <td><tt>noreply</tt></td>
- <td>no reply</td>
- </tr>
- <tr>
- <td><tt>badformat</tt></td>
- <td>bad format</td>
- </tr>
- <tr>
- <td><tt>baddata</tt></td>
- <td>bad date or time</td>
- </tr>
- <tr>
- <td><tt>fudgetime1</tt></td>
- <td>fudge time 1</td>
- </tr>
- <tr>
- <td><tt>fudgetime2</tt></td>
- <td>fudge time 2</td>
- </tr>
- <tr>
- <td><tt>stratum</tt></td>
- <td>driver stratum</td>
- </tr>
- <tr>
- <td><tt>refid</tt></td>
- <td>driver reference ID</td>
- </tr>
- <tr>
- <td><tt>flags</tt></td>
- <td>driver flags</td>
- </tr>
- </table>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>status</tt></td>
+ <td><a href="decode.html#sys">system status word</a></td>
+ </tr>
+ <tr>
+ <td><tt>version</tt></td>
+ <td>NTP software version and build time</td>
+ </tr>
+ <tr>
+ <td><tt>processor</tt></td>
+ <td>hardware platform and version</td>
+ </tr>
+ <tr>
+ <td><tt>system</tt></td>
+ <td>operating system and version</td>
+ </tr>
+ <tr>
+ <td><tt>leap</tt></td>
+ <td>leap warning indicator (0-3)</td>
+ </tr>
+ <tr>
+ <td><tt>stratum</tt></td>
+ <td>stratum (1-15)</td>
+ </tr>
+ <tr>
+ <td><tt>precision</tt></td>
+ <td>precision (log<sub>2</sub> s)</td>
+ </tr>
+ <tr>
+ <td><tt>rootdelay</tt></td>
+ <td>total roundtrip delay to the primary reference clock</td>
+ </tr>
+ <tr>
+ <td><tt>rootdisp</tt></td>
+ <td>total dispersion to the primary reference clock</td>
+ </tr>
+ <tr>
+ <td><tt>peer</tt></td>
+ <td>system peer association ID</td>
+ </tr>
+ <tr>
+ <td><tt>tc</tt></td>
+ <td>time constant and poll exponent (log<sub>2</sub> s) (3-17)</td>
+ </tr>
+ <tr>
+ <td><tt>mintc</tt></td>
+ <td>minimum time constant (log<sub>2</sub> s) (3-10)</td>
+ </tr>
+ <tr>
+ <td><tt>clock</tt></td>
+ <td>date and time of day</td>
+ </tr>
+ <tr>
+ <td><tt>refid</tt></td>
+ <td>reference ID or <a href="decode.html#kiss">kiss code</a></td>
+ </tr>
+ <tr>
+ <td><tt>reftime</tt></td>
+ <td>reference time</td>
+ </tr>
+ <tr>
+ <td><tt>offset</tt></td>
+ <td>combined time offset</td>
+ </tr>
+ <tr>
+ <td><tt>sys_jitter</tt></td>
+ <td>combined system jitter</td>
+ </tr>
+ <tr>
+ <td><tt>frequency</tt></td>
+ <td>clock frequency offset (PPM)</td>
+ </tr>
+ <tr>
+ <td><tt>clk_wander</tt></td>
+ <td>clock frequency wander (PPM)</td>
+ </tr>
+ <tr>
+ <td><tt>clk_jitter</tt></td>
+ <td>clock jitter</td>
+ </tr>
+ <tr>
+ <td><tt>tai</tt></td>
+ <td>TAI-UTC offset (s)</td>
+ </tr>
+ <tr>
+ <td><tt>leapsec</tt></td>
+ <td>NTP seconds when the next leap second is/was inserted</td>
+ </tr>
+ <tr>
+ <td><tt>expire</tt></td>
+ <td>NTP seconds when the NIST leapseconds file expires</td>
+ </tr>
+</table>
+<dl>
+ <dt>The jitter and wander statistics are exponentially-weighted RMS averages.
+ The system jitter is defined in the NTPv4 specification; the
+ clock jitter statistic is computed by the clock discipline module.</dt>
+ <dt>When the NTPv4 daemon is compiled with the OpenSSL software library, additional
+ system variables are displayed, including some or all of the following, depending
+ on the particular Autokey dance:</dt>
+</dl>
+<table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>host</tt></td>
+ <td>Autokey host name</td>
+ </tr>
+ <tr>
+ <td><tt>group</tt></td>
+ <td>Autokey group name</td>
+ </tr>
+ <tr>
+ <td><tt>flags</tt></td>
+ <td>host flags (see Autokey specification)</td>
+ </tr>
+ <tr>
+ <td><tt>digest</tt></td>
+ <td>OpenSSL message digest algorithm</td>
+ </tr>
+ <tr>
+ <td><tt>signature</tt></td>
+ <td>OpenSSL digest/signature scheme</td>
+ </tr>
+ <tr>
+ <td><tt>update</tt></td>
+ <td>NTP seconds at last signature update</td>
+ </tr>
+ <tr>
+ <td><tt>cert</tt></td>
+ <td>certificate subject, issuer and certificate flags</td>
+ </tr>
+ <tr>
+ <td><tt>until</tt></td>
+ <td>NTP seconds when the certificate expires</td>
+ </tr>
+</table>
+<h4 id="peer">Peer Variables</h4>
+<p>The following system variables apear in the <tt>rv</tt> billboard for each association. Not all variables are displayed in some configurations.</p>
+<table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>associd</tt></td>
+ <td>association ID</td>
+ </tr>
+ <tr>
+ <td><tt>status</tt></td>
+ <td><a href="decode.html#peer">peer status word</a></td>
+ </tr>
+ <tr>
+ <td><tt>srcadr<br>
+ srcport</tt></td>
+ <td>source (remote) IP address and port</td>
+ </tr>
+ <tr>
+ <td><tt>dstadr<br>
+ dstport</tt></td>
+ <td>destination (local) IP address and port</td>
+ </tr>
+ <tr>
+ <td><tt>leap</tt></td>
+ <td>leap indicator (0-3)</td>
+ </tr>
+ <tr>
+ <td><tt>stratum</tt></td>
+ <td>stratum (0-15)</td>
+ </tr>
+ <tr>
+ <td><tt>precision</tt></td>
+ <td>precision (log<sub>2</sub> s)</td>
+ </tr>
+ <tr>
+ <td><tt>rootdelay</tt></td>
+ <td>total roundtrip delay to the primary reference clock</td>
+ </tr>
+ <tr>
+ <td><tt>rootdisp</tt></td>
+ <td>total root dispersion to the primary reference clock</td>
+ </tr>
+ <tr>
+ <td><tt>refid</tt></td>
+ <td>reference ID or <a href="decode.html#kiss">kiss code</a></td>
+ </tr>
+ <tr>
+ <td><tt>reftime</tt></td>
+ <td>reference time</td>
+ </tr>
+ <tr>
+ <td><tt>reach</tt></td>
+ <td>reach register (octal)</td>
+ </tr>
+ <tr>
+ <td><tt>unreach</tt></td>
+ <td>unreach counter</td>
+ </tr>
+ <tr>
+ <td><tt>hmode</tt></td>
+ <td>host mode (1-6)</td>
+ </tr>
+ <tr>
+ <td><tt>pmode</tt></td>
+ <td>peer mode (1-5)</td>
+ </tr>
+ <tr>
+ <td><tt>hpoll</tt></td>
+ <td>host poll exponent (log<sub>2</sub> s) (3-17)</td>
+ </tr>
+ <tr>
+ <td><tt>ppoll</tt></td>
+ <td>peer poll exponent (log<sub>2</sub> s) (3-17)</td>
+ </tr>
+ <tr>
+ <td><tt>headway</tt></td>
+ <td>headway (see <a href="rate.html">Rate Management and the Kiss-o'-Death Packet)</a></td>
+ </tr>
+ <tr>
+ <td><tt>flash</tt></td>
+ <td><a href="decode.html#flash">flash status word</a></td>
+ </tr>
+ <tr>
+ <td><tt>offset</tt></td>
+ <td>filter offset</td>
+ </tr>
+ <tr>
+ <td><tt>delay</tt></td>
+ <td>filter delay</td>
+ </tr>
+ <tr>
+ <td><tt>dispersion</tt></td>
+ <td>filter dispersion</td>
+ </tr>
+ <tr>
+ <td><tt>jitter</tt></td>
+ <td>filter jitter</td>
+ </tr>
+ <tr>
+ <td><tt>bias</tt></td>
+ <td>unicast/broadcast bias</td>
+ </tr>
+ <tr>
+ <td><tt>xleave</tt></td>
+ <td>interleave delay (see <a href="xleave.html">NTP Interleaved Modes</a>)</td>
+ </tr>
+</table>
+<p>The bias vaqriable is calculated when the first broadcast packet is received
+ after the calibration volley. It represents the offset of the broadcast
+ subgraph relative to the unicast subgraph. The xleave variable appears
+ only the interleaved symmetric and ingterleaved modes. It represents
+ the internal queueing, buffering and transmission delays for the preceeding
+ packet.</p>
+<p>When the NTPv4 daemon is compiled with the OpenSSL software library, additional peer variables are displayed, including the following:</p>
+<table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>flags</tt></td>
+ <td>peer flags (see Autokey specification)</td>
+ </tr>
+ <tr>
+ <td><tt>host</tt></td>
+ <td>Autokey server name</td>
+ </tr>
+ <tr>
+ <td><tt>flags</tt></td>
+ <td>peer flags (see Autokey specification)</td>
+ </tr>
+ <tr>
+ <td><tt>signature</tt></td>
+ <td>OpenSSL digest/signature shceme</td>
+ </tr>
+ <tr>
+ <td><tt>initsequence</tt></td>
+ <td>initial key ID</td>
+ </tr>
+ <tr>
+ <td><tt>initkey</tt></td>
+ <td>initial key index</td>
+ </tr>
+ <tr>
+ <td><tt>timestamp</tt></td>
+ <td>Autokey signature timestamp</td>
+ </tr>
+</table>
+<h4 id="clock">Clock Variables</h4>
+<p>The following clock variables apear in the <tt>cv</tt> billboard for each association with a reference clock. Not all variables are displayed in some configurations.</p>
+<table width="100%" border="1" cellspacing="2" cellpadding="2">
+ <tr>
+ <td>Variable</td>
+ <td>Description</td>
+ </tr>
+ <tr>
+ <td><tt>associd</tt></td>
+ <td>association ID</td>
+ </tr>
+ <tr>
+ <td><tt>status</tt></td>
+ <td><a href="decode.html#clock">clock status word</a></td>
+ </tr>
+ <tr>
+ <td><tt>device</tt></td>
+ <td>device description</td>
+ </tr>
+ <tr>
+ <td><tt>timecode</tt></td>
+ <td>ASCII timecode string (specific to device)</td>
+ </tr>
+ <tr>
+ <td><tt>poll</tt></td>
+ <td>poll messages sent</td>
+ </tr>
+ <tr>
+ <td><tt>noreply</tt></td>
+ <td>no reply</td>
+ </tr>
+ <tr>
+ <td><tt>badformat</tt></td>
+ <td>bad format</td>
+ </tr>
+ <tr>
+ <td><tt>baddata</tt></td>
+ <td>bad date or time</td>
+ </tr>
+ <tr>
+ <td><tt>fudgetime1</tt></td>
+ <td>fudge time 1</td>
+ </tr>
+ <tr>
+ <td><tt>fudgetime2</tt></td>
+ <td>fudge time 2</td>
+ </tr>
+ <tr>
+ <td><tt>stratum</tt></td>
+ <td>driver stratum</td>
+ </tr>
+ <tr>
+ <td><tt>refid</tt></td>
+ <td>driver reference ID</td>
+ </tr>
+ <tr>
+ <td><tt>flags</tt></td>
+ <td>driver flags</td>
+ </tr>
+</table>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntptime - read and set kernel time variables</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntptime</tt> - read and set kernel time variables</h3>
- <img src="pic/pogo5.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>The turtle has been swimming in the kernel.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">16:40</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="289">Wednesday, March 12, 2008</csobj></p>
- <br clear="left">
- <hr>
- <h4>Synopsis</h4>
- <tt>ntptime [ -chr ] [ -e <i>est_error</i> ] [ -f <i>frequency</i> ] [ -m <i>max_error</i> ] [ -o <i>offset</i> ] [ -s <i>status</i> ] [ -t <i>time_constant</i>]</tt>
- <h4>Description</h4>
- <p>This program is useful only with special kernels described in the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. It reads and displays time-related kernel variables using the <tt>ntp_gettime()</tt> system call. A similar display can be obtained using the <tt>ntpdc</tt> program and <tt>kerninfo</tt> command.</p>
- <h4>Options</h4>
- <dl>
- <dt><tt>-c</tt>
- <dd>Display the execution time of <tt>ntptime</tt> itself.
- <dt><tt>-e <i>est_error</i></tt>
- <dd>Specify estimated error, in microseconds.
- <dt><tt>-f <i>frequency</i></tt>
- <dd>Specify frequency offset, in parts per million.
- <dt><tt>-h</tt>
- <dd>Display help information.
- <dt><tt>-m <i>max_error</i></tt>
- <dd>Specify max possible errors, in microseconds.
- <dt><tt>-o <i>offset</i></tt>
- <dd>Specify clock offset, in microseconds.
- <dt><tt>-r</tt>
- <dd>Display Unix and NTP times in raw format.
- <dt><tt>-s <i>status</i></tt>
- <dd>Specify clock status. Better know what you are doing.
- <dt><tt>-t <i>time_constant</i></tt>
- <dd>Specify time constant, an integer in the range 0-10.
- </dl>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntptime - read and set kernel time variables</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntptime</tt> - read and set kernel time variables</h3>
+<img src="pic/pogo5.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>The turtle has been swimming in the kernel.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 14:46<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<hr>
+<h4>Synopsis</h4>
+<tt>ntptime [ -chr ] [ -e <i>est_error</i> ] [ -f <i>frequency</i> ] [ -m <i>max_error</i> ] [ -o <i>offset</i> ] [ -s <i>status</i> ] [ -t <i>time_constant</i>]</tt>
+<h4>Description</h4>
+<p>This program is useful only with special kernels described in the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. It reads and displays time-related kernel variables using the <tt>ntp_gettime()</tt> system call. A similar display can be obtained using the <tt>ntpdc</tt> program and <tt>kerninfo</tt> command.</p>
+<h4>Options</h4>
+<dl>
+ <dt><tt>-c</tt></dt>
+ <dd>Display the execution time of <tt>ntptime</tt> itself.</dd>
+ <dt><tt>-e <i>est_error</i></tt></dt>
+ <dd>Specify estimated error, in microseconds.</dd>
+ <dt><tt>-f <i>frequency</i></tt></dt>
+ <dd>Specify frequency offset, in parts per million.</dd>
+ <dt><tt>-h</tt></dt>
+ <dd>Display help information.</dd>
+ <dt><tt>-m <i>max_error</i></tt></dt>
+ <dd>Specify max possible errors, in microseconds.</dd>
+ <dt><tt>-o <i>offset</i></tt></dt>
+ <dd>Specify clock offset, in microseconds.</dd>
+ <dt><tt>-r</tt></dt>
+ <dd>Display Unix and NTP times in raw format.</dd>
+ <dt><tt>-s <i>status</i></tt></dt>
+ <dd>Specify clock status. Better know what you are doing.</dd>
+ <dt><tt>-t <i>time_constant</i></tt></dt>
+ <dd>Specify time constant, an integer in the range 0-10.</dd>
+</dl>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>ntptrace - trace a chain of NTP servers back to the primary source</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>ntptrace</tt> - trace a chain of NTP servers back to the primary source</h3>
- <img src="pic/alice13.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>The rabbit knows the way back.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">19:06</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="308">Wednesday, January 16, 2008</csobj></p>
- <br clear="left">
- <hr>
- <h4>Synopsis</h4>
- <tt>ntptrace [ -vdn ] [ -r <i>retries</i> ] [ -t <i>timeout</i> ] [ <i>server</i> ]</tt>
- <h4>Description</h4>
-
<p><tt>ntptrace</tt> is a <tt>perl</tt> script that uses the <tt>ntpq</tt> utility program to follow the chain of NTP servers from a given host back to the primary time source. For <tt>ntptrace</tt> to work properly, each of these servers must implement the NTP Control and Monitoring Protocol specified in RFC 1305 and enable NTP Mode 6 packets.</p>
-
<p>If given no arguments, <tt>ntptrace</tt> starts with <tt>localhost</tt>. Here is an example of the output from <tt>ntptrace</tt>:</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>ntptrace - trace a chain of NTP servers back to the primary source</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>ntptrace</tt> - trace a chain of NTP servers back to the primary source</h3>
+<img src="pic/alice13.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>The rabbit knows the way back.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 14:51<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<hr>
+<h4>Synopsis</h4>
+<tt>ntptrace [ -vdn ] [ -r <i>retries</i> ] [ -t <i>timeout</i> ] [ <i>server</i> ]</tt>
+<h4>Description</h4>
+<p><tt>ntptrace</tt> is a <tt>perl</tt> script that uses the <tt>ntpq</tt> utility program to follow the chain of NTP servers from a given host back to the primary time source. For <tt>ntptrace</tt> to work properly, each of these servers must implement the NTP Control and Monitoring Protocol specified in RFC 1305 and enable NTP Mode 6 packets.</p>
+<p>If given no arguments, <tt>ntptrace</tt> starts with <tt>localhost</tt>. Here is an example of the output from <tt>ntptrace</tt>:</p>
+<pre>
% ntptrace
localhost: stratum 4, offset 0.0019529, synch distance 0.144135
server2ozo.com: stratum 2, offset 0.0124263, synch distance 0.115784
usndh.edu: stratum 1, offset 0.0019298, synch distance 0.011993, refid 'WWVB'
</pre>
- <p>On each line, the fields are (left to right): the host name, the host stratum, the time offset between that host and the local host (as measured by <tt>ntptrace</tt>; this is why it is not always zero for "<tt>localhost</tt>"), the host synchronization distance, and (only for stratum-1 servers) the reference clock ID. All times are given in seconds. Note that the stratum is the server hop count to the primary source, while the synchronization distance is the estimated error relative to the primary source. These terms are precisely defined in RFC-1305.</p>
- <h4>Options</h4>
- <dl>
- <dt><tt>-d</tt>
- <dd>Turns on some debugging output.
- <dt><tt>-n</tt>
- <dd>Turns off the printing of host names; instead, host IP addresses are given. This may be useful if a nameserver is down.
- <dt><tt>-r <i>retries</i></tt>
- <dd>Sets the number of retransmission attempts for each host (default = 5).
- <dt><tt>-t <i>timeout</i></tt>
- <dd>Sets the retransmission timeout (in seconds) (default = 2).
- <dt><tt>-v</tt>
- <dd>Prints verbose information about the NTP servers.
- </dl>
- <h4>Bugs</h4>
- <p>This program makes no attempt to improve accuracy by doing multiple samples.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<p>On each line, the fields are (left to right): the host name, the host stratum, the time offset between that host and the local host (as measured by <tt>ntptrace</tt>; this is why it is not always zero for "<tt>localhost</tt>"), the host synchronization distance, and (only for stratum-1 servers) the reference clock ID. All times are given in seconds. Note that the stratum is the server hop count to the primary source, while the synchronization distance is the estimated error relative to the primary source. These terms are precisely defined in RFC-1305.</p>
+<h4>Options</h4>
+<dl>
+ <dt><tt>-d</tt></dt>
+ <dd>Turns on some debugging output.</dd>
+ <dt><tt>-n</tt></dt>
+ <dd>Turns off the printing of host names; instead, host IP addresses are given. This may be useful if a nameserver is down.</dd>
+ <dt><tt>-r <i>retries</i></tt></dt>
+ <dd>Sets the number of retransmission attempts for each host (default = 5).</dd>
+ <dt><tt>-t <i>timeout</i></tt></dt>
+ <dd>Sets the retransmission timeout (in seconds) (default = 2).</dd>
+ <dt><tt>-v</tt></dt>
+ <dd>Prints verbose information about the NTP servers.</dd>
+</dl>
+<h4>Bugs</h4>
+<p>This program makes no attempt to improve accuracy by doing multiple samples.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Orphan Mode</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Orphan Mode</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 23:19<!-- #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 mode be enabled. By default the delay is 600 s (five minutes), but this can be changed using the <tt>tos orphanwait <em>delay</em></tt> 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 (Unix 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>
+<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>
+<hr>
+<p><script type="text/javascript" language="javascript" src="scripts/footer.txt"></script></p>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Pulse-per-second (PPS) Signal Interfacing</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Pulse-per-second (PPS) Signal Interfacing</h3>
- <img src="pic/alice32.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>Alice is trying to find the PPS signal connector.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">22:01</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="308">Wednesday, January 02, 2008</csobj></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="#gadget">Gadget Box</a></li>
- <li class="inline"><a href="#opsys">Operating System Support</a></li>
- <li class="inline"><a href="#use">Using the Pulse-per-Second (PPS) Signal</a></li>
- </ul>
- <hr>
- <h4 id="intro">Introduction</h4>
- <p>Most radio clocks are connected using a serial port operating at speeds of 9600 bps. The accuracy using typical timecode formats, where the on-time epoch is indicated by a designated ASCII character like carriage-return <tt><cr></tt>, is normally limited to a hundred microseconds. Using carefuly crafted averaging techniques, the NTP algorithms can whittle this down to a few tens of microseconds. However, some radios produce a PPS signal which can be used to improve the accuracy to few microseconds. This page describes the hardware and software necessar for NTP to use the PPS signal.</p>
- <div align="center">
- <img src="pic/gadget.jpg" alt="gif"><br>
- A Gadget Box built by Chuck Hanavin
- </div>
- <h4 id="gadget">Gadget Box</h4>
- <p>The PPS signal can be connected in either of two ways: via the DCD data carrier detect pin of a serial port or via the ACK acknowledge pin of a parallel port, depending on the hardware and operating system. Note that NTP no longer supports connection via the RD data pin of a serial port.</p>
- <p>However, the PPS signal levels are usually incompatible with serial port levels. The gadget box consists of a handful of electronic components assembled in a small aluminum box. It includes level converters and a optional modem designed to decode the radio timecode signals transmitted by Canadian time and frequency station CHU. This can be used with the <a href="drivers/driver7.html">Radio CHU Audio Demodulator/Decoder</a>. A complete set of schematics, PCB artwork and drill templates can be obrtained via the web at <a href="ftp://ftp.udel.edu/pub/ntp/hardware/gadget.tar.Z">gadget.tar.Z</a>.</p>
- <h4 id="opsys">Operating System Support</h4>
- <p>Both the serial and parallel port connection require operating system support, which is available in only a few operating systems, including FreeBSD, Linux (with PPSkit patch) and Solaris. Support on an experimental basis is available for several other systems, including SunOS and HP/Compaq/Digital Tru64. The kernel interface described on the <a href="kernpps.html">PPSAPI Interface for Precision Time Signals</a> page is the only interface currently supported. Older PPS interfaces based on the <tt>ppsclock</tt> and <tt>tty_clk</tt> streams modules are no longer supported.</p>
- <h4>PPS Driver</h4>
- <p>PPS support requires the PPS driver (described on the <a href="drivers/driver22.html">Type 22 PPS Clock Discipline</a> page. The driver operates in conjunction with a prefer peer, as described in the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. The prefer peer is ordinarily the radio clock that provides the PPS signal, but in principle another radio clock or remote Internet server could be designated prerred. A source is desgnated prefer using the <tt>prefer</tt> keyword, as described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> keyword</a> page. Only one source can be designated preferred. PPS signals are processed by the PPS driver and other clock drivers which might be involved need not know or care about PPS capability. Note that the <tt>pps</tt> configuration command has been obsoleted by this driver.</p>
- <h4 id="pps">Using the Pulse-per-Second (PPS) Signal</h4>
- <p>The PPS signal can be used in two ways, one using the NTP grooming and mitigations algorithms and the other using PPS signal support in the kernel, as described in the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page. In either case, the PPS signal must be present and within nominal jitter and wander tolerances. In addition, the PPS driver and prefer peer must survive the sanity checks and intersection algorithms. Finally, the offset of the system clock relative to the prefer peer must be less than 128 ms, or well within the 0.5-s unambiguous range. The PPS peer remains active as long as these conditions are met.</p>
- <p>The presence of PPS kernel support is automatically detected during the NTP configuration process and supporting code automatically compiled. When kernel PPS support is enabled, the PPS driver can direct the signal directly to the kernel. Note that the PPS driver does not normally enable the PPS kernel, since performance is generally better with older systems. However, the kernel can be enabled by a driver fudge flag if necessary. This is advised for newer machines in the Pentium class.</p>
- <p>The kernel maintains a watchdog timer for the PPS signal; if the signal has not been heard or is out of tolerance for more than some interval, currently two minutes, the kernel discipline is disabled and operation continues as if it were not present. </p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Pulse-Per-Second (PPS) Signal Interfacing</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Pulse-Per-Second (PPS) Signal Interfacing</h3>
+<img src="pic/alice32.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>Alice is trying to find the PPS signal connector.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->09-Sep-2010 18:15<!-- #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="#gadget">Gadget Box</a></li>
+ <li class="inline"><a href="#opsys">Operating System Support</a></li>
+ <li class="inline"><a href="#use">Using the Pulse-per-Second (PPS) Signal</a></li>
+</ul>
+<hr>
+<h4 id="intro">Introduction</h4>
+<p>Most radio clocks are connected using a serial port operating at speeds of 9600 bps. The accuracy using typical timecode formats, where the on-time epoch is indicated by a designated ASCII character such as carriage-return <tt><cr></tt>, is normally limited to 100 <font face="symbol">m</font>s. Using carefully crafted averaging techniques, the NTP algorithms can whittle this down to a few tens of microseconds. However, some radios produce a pulse-per-second (PPS) signal which can be used to improve the accuracy to a few microseconds. This page describes the hardware and software necessary for NTP to use the PPS signal.</p>
+<p> The PPS signal can be connected in either of two ways. On FreeBSD systems (with the PPS_SYNC and pps kernel options) it can be connected directly to the ACK pin of a parallel port. This is the preferred way, as it requires no additional hardware. Alternatively, it can be connected via the DCD pin of a serial port. However, the PPS signal levels are usually incompatible with the serial port interface signals. Note that NTP no longer supports connection via the RD pin of a serial port.</p>
+<div align="center">
+ <p><img src="pic/gadget.jpg" alt="gif"></p>
+ <p>A Gadget Box built by Chuck Hanavin</p>
+</div>
+<p>The gadget box shown above is assembled in a 5"x3"x2" aluminum minibox containing the the circuitry, serial connector and optional 12-V power connector. A complete set of schematics, PCB artwork, drill templates can be obtained via the web from ftp.udel.edu as <a href="ftp://ftp.udel.edu/pub/ntp/hardware/gadget.tar.Z">gadget.tar.Z</a>.</p>
+<p> The gadget box includes two subcircuits. One of these converts a TTL positive edge into a fixed-width pulse at EIA levels and is for use with a timecode receiver or precision oscillator with a TTL PPS output. The other converts the timecode modulation broadcast by Canadian time/frequency standard station CHU into a 300-bps serial character stream at EIA levels and is for use with the <a href="drivers/driver7.html">Radio CHU Audio Demodulator/Decoder</a> driver.</p>
+<h4 id="opsys">Operating System Support</h4>
+<p>Both the serial and parallel port connection require operating system support, which is available in a few operating systems, including FreeBSD, Linux (with PPSkit patch) and Solaris. Support on an experimental basis is available for several other systems, including SunOS and HP/Compaq/Digital Tru64. The kernel interface described on the <a href="kernpps.html">PPSAPI Interface for Precision Time Signals</a> page is the only interface currently supported. Older PPS interfaces based on the <tt>ppsclock</tt> and <tt>tty_clk</tt> streams modules are no longer supported. The interface consists of the <tt>ppstime.h</tt> header file which is specific to each system. It is included automatically when the distribution is built.</p>
+<h4>PPS Driver</h4>
+<p>PPS support requires is built into some drivers, in particular the WWVB and NMEA drivers, and may be added to other drivers in future. Alternatively, the PPS driver described on the <a href="drivers/driver22.html">Type 22 PPS Clock Discipline</a> page can be used. It operates in conjunction with another source that provides seconds numbering. The selected source is designate a prefer peer, as using the <tt>prefer</tt> option, as described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. The prefer peer is ordinarily the radio clock that provides the PPS signal, but in principle another radio clock or even a remote Internet server could be designated preferred Note that the <tt>pps</tt> configuration command has been obsoleted by this driver.</p>
+<h4 id="pps">Using the Pulse-per-Second (PPS) Signal</h4>
+<p>The PPS signal can be used in either of two ways, one using the NTP grooming and mitigation algorithms and the other using the kernel PPS signal support described in the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page. The presence of kernel support is automatically detected during the NTP build process and supporting code automatically compiled. In either case, the PPS signal must be present and within nominal jitter and wander tolerances. In addition, the prefer peer must be a truechimer; that is, survive the sanity checks and intersection algorithm. Finally, the offset of the system clock relative to the prefer peer must be within ±0.5 s. The kernel maintains a watchdog timer for the PPS signal; if the signal has not been heard or is out of tolerance for more than some interval, currently two minutes, the kernel discipline is disabled and operation continues as if it were not present. </p>
+<p> An option flag in the driver determines whether the NTP algorithms or kernel support is enabled (if available). For historical reasons, the NTP algorithms are selected by by default, since performance is generally better using older, slower systems. However, performance is generally better with kernl support using newer, faster systems.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<link href="scripts/style.css" type="text/css" rel="stylesheet">
</head>
<body>
-
<h3>Mitigation Rules and the <tt>prefer</tt> Keyword</h3>
-
<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 -->22-Apr-2009 14:04<!-- #EndDate -->
-UTC</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->
+ 22-Apr-2009 14:04
+ <!-- #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="#peer">Peer Classification</a></li>
-<li class="inline"><a href="#prefer">The <tt>prefer</tt> Peer</a></li>
-<li class="inline"><a href="#miti">Mitigation Rules</a></li>
-<li class="inline"><a href="#mins">The <tt>minsane</tt> Option</a></li>
-
+ <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#peer">Peer Classification</a></li>
+ <li class="inline"><a href="#prefer">The <tt>prefer</tt> Peer</a></li>
+ <li class="inline"><a href="#miti">Mitigation Rules</a></li>
+ <li class="inline"><a href="#mins">The <tt>minsane</tt> Option</a></li>
</ul>
-
<hr>
-
<h4 id="intro">Introduction</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>
-
<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 loop error occurs if the source is synchronized to the client of 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>
-
+ <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 loop error occurs if the source is synchronized to the client of 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 the number specified
- as the <tt>minclock</tt> option of the <tt>tos</tt> command, with default 3.
- Phase five uses a set of mitigation rules 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 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>
-
+ 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 the number specified
+ as the <tt>minclock</tt> option of the <tt>tos</tt> command, with default 3.
+ Phase five uses a set of mitigation rules 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 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>
<h4 id="peer">Peer Classification</h4>
-
<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>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.5 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 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>
-
+ <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>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.5 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 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 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 clustering 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>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,
- the offset of the prefer peer is used exclusively as the final synchronization
- source. In the common case involving a radio clock and a flock of remote backup
- servers, and with the radio clock designated a prefer peer, the result is that
- the radio clock normally disciplines the system clock as long as the radio itself
- remains operational. However, if the radio fails or becomes a falseticker,
- the averaged backup sources continue to discipline the system clock.</p>
-
+ offsets to produce the final synchronization source. However, if a prefer
+ peer is among the survivors, the combining algorithm is not used. Instead,
+ the offset of the prefer peer is used exclusively as the final synchronization
+ source. In the common case involving a radio clock and a flock of remote backup
+ servers, and with the radio clock designated a prefer peer, the result is that
+ the radio clock normally disciplines the system clock as long as the radio itself
+ 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>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
- in the combining algorithm and is mitigated separately.</p>
-
+ 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
+ in the combining algorithm and is mitigated separately.</p>
<p>At this point we have the following contributors to the system clock discipline:</p>
-
<ul>
-
-<li>(potential) system peer, if there are survivors;</li>
-<li>orphan parent, if present;</li>
-<li>local driver and zero offset, if present;</li>
-<li>modem driver and modem offset, if present;</li>
-<li>prefer peer and offset, if present;</li>
-<li>PPS driver and offset, if present.</li>
+ <li>(potential) system peer, if there are survivors;</li>
+ <li>orphan parent, if present;</li>
+ <li>local driver and zero offset, if present;</li>
+ <li>modem driver and modem offset, if present;</li>
+ <li>prefer peer and offset, if present;</li>
+ <li>PPS driver and offset, if present.</li>
</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 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>
-
+ <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 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>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
- signal, the GPS driver is designated the PPS driver and the PPS signal disciplines
- the system clock. If no GPS satellites are in view, or if the PPS signal is
- disconnected, the GPS driver stops updating the system clock and so eventually
- becomes unreachable and replaced by other sources..</p>
-
+ 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
+ signal, the GPS driver is designated the PPS driver and the PPS signal disciplines
+ the system clock. If no GPS satellites are in view, or if the PPS signal is
+ 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 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>
<p> </p>
-
<hr>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=windows-1252">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Quick Start</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Quick Start</h3>
- <img src="pic/panda.gif" alt="gif" align="left">FAX test image for SATNET (1979).
- <p>The baby panda was scanned at University College London and used as a FAX test image for a demonstration of the DARPA Atlantic SATNET Program and the first transatlantic Internet connection in 1978. The computing system used for that demonstration was called the <a href="http://www.eecis.udel.edu/%7emills/database/papers/fuzz.ps">Fuzzball</a>. As it happened, this was also the first Internet multimedia presentation and the first to use NTP in regular operation. The image was widely copied and used for testing purpose throughout much of the 1980s.</p>
- <p>Last update:
- <!-- #BeginDate format:En1m -->25-nov-09 22:13<!-- #EndDate -->
- UTC</p>
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
- <hr>
- <p>For the rank amateur the sheer volume of the documentation collection must be intimidating. However, it doesn't take much to fly the <tt>ntpd</tt> daemon with a simple configuration where a workstation needs to synchronize to some server elsewhere in the Internet. The first thing is to build the distribution for the particular workstation and install in the usual place. The <a href="build.html">Building and Installing the Distribution</a> page describes how to do this.</p>
- <p>While it is possible that certain configurations do not need a configuration file, most do. The file, called by default <tt>/etc/ntp.conf</tt>, need only contain one command specifying a remote server, for instance</p>
- <p><tt>server foo.bar.com</tt></p>
- <p>Choosing an appropriate remote server is somewhat of a black art, but a
- suboptimal choice is seldom a problem. The simplest is to use the
- Server Pool Scheme on the <a href="manyopt.html">Automatic Server Discovery</a> page. There
- are about two dozen public time servers operated by the <a href="http://tf.nist.gov/tf-cgi/servers.cgi">National
- Institutes of Science and Technology (NIST)</a>, <a href="http://tycho.usno.navy.mil/ntp.html">US
- Naval Observatory (USNO)</a>, <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/network_time_protocol_e.html"> Canadian
- Metrology Centre (CMC)</a> and many others available on the Internet. Lists
- of public primary and secondary NTP servers maintained on the <a href="http://support.ntp.org/bin/view/Servers/WebHome">Public
- NTP Time Servers</a> page, which is updated frequently.The lists are sorted
- by country and, in the case of the US, by state. Usually, the best
- choice is the nearest in geographical terms, but the terms of engagement
- specified in each list entry should be carefully respected.</p>
- <p>During operation <tt>ntpd</tt> measures and corrects for incidental clock frequency error and occasionally writes the current value to a file specified by the</p>
- <p><tt>driftfile /etc/ntp.drift</tt></p>
- <p>configuration command. If <tt>ntpd</tt> is stopped and restarted, it initializes the frequency from this file and avoids the potentially lengthy interval to relearn the correction.</p>
- <p>That's all there is to it, unless some problem in network connectivity or local operating system configuration occurs. The most common problem is some firewall between the workstation and server. System administrators should understand NTP uses UDP port 123 as both the source and destination port and that NTP does not involve any operating system interaction other than to set the system clock. While almost all modern Unix systems have included NTP and UDP port 123 defined in the services file, this should be checked if <tt>ntpd</tt> fails to come up at all.</p>
- <p>The best way to confirm NTP is working is using the <a href="ntpq.html"><tt>ntpq</tt></a> utility, although the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility may be useful in extreme cases. See the documentation pages for further information. Don't forget to check for <a href="msyslog.html"> system log messages</a>. In the most extreme cases the <tt>-d</tt> option on the <tt>ntpd</tt> command line results in a blow-by-blow trace of the daemon operations. While the trace output can be cryptic, to say the least, it gives a general idea of what the program is doing and, in particular, details the arriving and departing packets and any errors found.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=windows-1252">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Quick Start</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 17:16<!-- #EndDate -->
+ UTC</p>
+<h3>Quick Start</h3>
+<img src="pic/panda.gif" alt="gif" align="left">FAX test image for SATNET (1979).
+<p>The baby panda was scanned at University College London and used as a FAX test image for a demonstration of the DARPA Atlantic SATNET Program and the first transatlantic Internet connection in 1978. The computing system used for that demonstration was called the <a href="http://www.eecis.udel.edu/%7emills/database/papers/fuzz.ps">Fuzzball</a>. As it happened, this was also the first Internet multimedia presentation and the first to use a predecessor of NTP in regular operation. The image was widely copied and used for testing purpose throughout much of the 1980s.</p>
+<p>Last update:
+ <!-- #BeginDate format:En1m -->4-sep-10 17:16<!-- #EndDate -->
+ UTC</p>
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+<hr>
+<p>For the rank amateur the sheer volume of the documentation collection must be intimidating. However, it doesn't take much to fly the <tt>ntpd</tt> daemon with a simple configuration where a workstation needs to synchronize to some server elsewhere in the Internet. The first thing is to build the distribution for the particular workstation and install in the usual place. The <a href="build.html">Building and Installing the Distribution</a> page describes how to do this.</p>
+<p>While it is possible that certain configurations do not need a configuration file, most do. The file, called by default <tt>/etc/ntp.conf</tt>, need only contain one command specifying a remote server, for instance</p>
+<p><tt>server foo.bar.com</tt></p>
+<p>Choosing an appropriate remote server is somewhat of a black art, but a
+ suboptimal choice is seldom a problem. The simplest is to use the
+ Server Pool Scheme on the <a href="manyopt.html">Automatic Server Discovery</a> page. There
+ are about two dozen public time servers operated by the <a href="http://tf.nist.gov/tf-cgi/servers.cgi">National
+ Institutes of Science and Technology (NIST)</a>, <a href="http://tycho.usno.navy.mil/ntp.html">US
+ Naval Observatory (USNO)</a>, <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/network_time_protocol_e.html"> Canadian
+ Metrology Centre (CMC)</a> and many others available on the Internet. Lists
+ of public primary and secondary NTP servers maintained on the <a href="http://support.ntp.org/bin/view/Servers/WebHome">Public
+ NTP Time Servers</a> page, which is updated frequently.The lists are sorted
+ by country and, in the case of the US, by state. Usually, the best
+ choice is the nearest in geographical terms, but the terms of engagement
+ specified in each list entry should be carefully respected.</p>
+<p>During operation <tt>ntpd</tt> measures and corrects for incidental clock frequency error and occasionally writes the current value to a file specified by the</p>
+<p><tt>driftfile /etc/ntp.drift</tt></p>
+<p>configuration command. If <tt>ntpd</tt> is stopped and restarted, it initializes the frequency from this file and avoids the potentially lengthy interval to relearn the correction.</p>
+<p>That's all there is to it, unless some problem in network connectivity or local operating system configuration occurs. The most common problem is some firewall between the workstation and server. System administrators should understand NTP uses UDP port 123 as both the source and destination port and that NTP does not involve any operating system interaction other than to set the system clock. While almost all modern Unix systems have included NTP and UDP port 123 defined in the services file, this should be checked if <tt>ntpd</tt> fails to come up at all.</p>
+<p>The best way to confirm NTP is working is using the <a href="ntpq.html"><tt>ntpq</tt></a> utility, although the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility may be useful in extreme cases. See the documentation pages for further information. Don't forget to check for <a href="msyslog.html"> system log messages</a>. In the most extreme cases the <tt>-d</tt> option on the <tt>ntpd</tt> command line results in a blow-by-blow trace of the daemon operations. While the trace output can be cryptic, to say the least, it gives a general idea of what the program is doing and, in particular, details the arriving and departing packets and any errors found.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Rate Management and the Kiss-o'-Death</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Rate Management and the Kiss-o'-Death Packet</h3>
- <img src="pic/boom4.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>Our junior managers and the administrators.</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->03-May-2009 3:34<!-- #EndDate -->
- UTC</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Rate Management and the Kiss-o'-Death</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Rate Management and the Kiss-o'-Death Packet</h3>
+<img src="pic/boom4.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>Our junior managers and the administrators.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->09-Sep-2010 20:49<!-- #EndDate -->
+ UTC</p>
<br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#intro">Introduction</a></li>
- <li class="inline"><a href="#poll">Poll Rate Control</a></li>
- <li class="inline"><a href="#burst">Burst Control</a></li>
- <li class="inline"><a href="#mah">Average Headway Time</a></li>
- <li class="inline"><a href="#mgt">Guard Time</a></li>
- <li class="inline"><a href="#kiss">The Kiss-o'-Death Packet</a></li>
- </ul>
- <hr>
- <h4 id="intro">Introduction</h4>
- <p>This page describes the various rate management provisions in NTPv4. Details about the configuration commands and options are given on the <a href="confopt.html">Configuration Options</a> page. Details about the cryptographic authentication schemes are given on the <a href="authopt.html">Authentication Options</a> page. Details about the automatic server discovery schemes are described on the <a href="manyopt.html">Automatic Server Discovery Schemes</a> page. Additional information is available in the papers, reports, memoranda and briefings on the <a href="http://www.eecis.udel.edu/~mills/ntp.html"> NTP Project</a> page.</p>
- <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 expected accuracy expectations.</li>
- <li>Maintain strict minimum average headway and guard times, even if multiple burst options and/or the Autokey protocol are operating.</li>
- <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>
- <li>Upon receiving a Kiss-o'-Death packet (see below), immediately reduce the sending rate.</li>
- </ul>
- <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>Control of the poll interval is an intricate balance between expected acuracy and network load. The poll interval is constrained by the lower limit <tt>minpoll</tt> and upper limit <tt>maxpoll</tt> options of the <tt>server</tt> command and represented by the poll exponent in log<sub>2</sub> s units. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases. The default limits can be changed with these options to a minimum set by the <tt>average</tt> option of the <tt>discard</tt> command (see below) to a maximum of 17 (36 h). Unless the best possible accuracy is required, the well mannered NTP client automatically increases the poll interval to the maximum when possible, whether or not the server is reachable. The current poll interval for each association is displayed by the <tt>ntpq</tt> program <a href="ntpq.html#pe"><tt>pe</tt></a> command. The global poll interval/time constant is displayed as the poll system variable by the rv command. The minimum global poll interval/time constant is displayed as the minpoll system variable by the <a href="ntpq.html#pe"><tt>rv</tt></a> command.</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 <tt>ntpd</tt> poll interval algorithm slowly increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it. The algorithm uses a jiggle counter which operates over the range from <font face="symbol">-</font>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 pollcurrent exponent; if not, it is decreased by twice the poll exponent. If the counter reaches +30, the poll exponent is incremented by 1; if the counter reaches <font face="symbol">-</font>30, the exponent is decremented by 1. In either case the counter is set to 0.</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 decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. With a compromise Allan intercept of 2000 s, the optimim poll interval is about 64 s, which corresponds to a poll exponent of 6.</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>
- </ul>
- <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 <tt>burst</tt> and <tt>iburst</tt> options of the <tt>server</tt> 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>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 poll interval and the minimum poll interval set by the <tt>minpoll</tt> option of the <a href="confopt.html#server"><tt>server</tt></a> command. For instance, with a 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 intervals of 9 (512 s) or more.</p>
- <h4 id="mah">Average Headway Time</h4>
- <p>There are two features in <tt>ntpd</tt> to manage the interval between one packet and the next. These features make use of a set of counters: a client output counter for each association and a server 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 minimum average headway in <tt>ntpd</tt> is 8 s, but this can be changed using the <tt>average</tt> option of the <a href="miscopt.html#discard"><tt>discard</tt></a> command, but not less than 3 (8 s).</p>
- <p>If the <tt>iburst</tt> or <tt>burst</tt> 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 <a href="confopt.html#server"><tt>server</tt></a> 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. The current headway is displayed as the headway peer variable by the <tt>ntpq</tt> <a href="ntpq.html#pe"><tt>rv</tt></a> command.</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 interval since the last packet arrival. The entries are ordered by interval from the smallest to the largest. 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 interval 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, 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 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. On one occasion due to a defective client design, over 750,000 clients fell into this mode. 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> 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 <a href="miscopt.html#discard"><tt>discard</tt></a> ommand.</p>
- <h4 id="kiss">The Kiss-of-Death Packet</h4>
- <p>Ordinarily, packets denied service are simply dropped with no further action except incrementing statistics counters. Sometimes a more proactive response is needed to cause the client to slow down. A special packet format has been created for this purpose called the kiss-o'-death (KoD) packet. KoD packets have leap indicator 3, stratum 0 and the reference identifier set to a four-byte ASCII code. At present, only one code <tt>RATE</tt> is sent by the server if the <tt>limited</tt> and <tt>kod</tt> flags are set in the <a href="accopt.html#restrict"><tt>restrict</tt></a> command and the rate limit is exceeded.</p>
- <p>A client receiving a KoD packet is expected to slow down; however, no explicit mechanism is specified in the protocol to do this. In the current reference implementation, the server sets the packet poll to the greater of (a) minimum average headway and (b) client packet poll. The client sets the peer poll field to the maximum of (a) minimum average headway and (b) server packet poll. For KoD packets (only), the minimum peer poll is clamped not less than the peer poll and the headway temporarily increased. </p>
- <p>At present there is only one KoD packet with code <tt>RATE.</tt> 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>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#poll">Poll Rate Control</a></li>
+ <li class="inline"><a href="#burst">Burst Control</a></li>
+ <li class="inline"><a href="#guard">Guard Time</a></li>
+ <li class="inline"><a href="#mah">Average Headway Time</a></li>
+ <li class="inline"><a href="#kiss">The Kiss-o'-Death Packet</a></li>
+</ul>
+<hr>
+<h4 id="intro">Introduction</h4>
+<p>This page describes the various rate management provisions in NTPv4. Some national time metrology laboratories, including NIST and USNO, use the NTP reference implementation in their very busy public time servers. They operate multiple servers behind load-balancing devices to support aggregate rates up to ten 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 clients need to avoid configurations that can result in unfriendly rates.</p>
+<p>There are several features in the reference implementation<tt></tt> designed to defend the servers and network against accidental or intentional flood attack. On the other hand these features are also used to insure the client <tt></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 expected accuracy expectations.</li>
+ <li>Maintain strict guard time and minimum average headway time, even if multiple burst options and/or the Autokey protocol are operating.</li>
+ <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>
+ <li>Upon receiving a Kiss-o'-Death packet (see below), immediately reduce the sending rate.</li>
+</ul>
+<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="guard">Guard Time</h4>
+<p>Guard time is the minimum time between successive packets. By default this is 2 s, but can be changed using the <tt>minimum</tt> option of the <tt>discard</tt> command. By design, this is also the interval between packets sent using the <tt>burst</tt> and <tt>iburst</tt> options.</p>
+<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. On one occasion due to a defective client design, over 750,000 clients fell into this mode. 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> 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 <a href="acccopt.html#discard"><tt>discard</tt></a> command.</p>
+<h4 id="mah">Average Headway Time</h4>
+<p>There are two features in <tt>ntpd</tt> to manage the interval between one packet and the next. These features make use of a set of counters: a client output counter for each association and a server 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 minimum average headway in <tt>ntpd</tt> is 8 s, but this can be changed using the <tt>average</tt> option of the <a href="accopt.html#discard"><tt>discard</tt></a> command, but not less than 3 (8 s).</p>
+<p>If the <tt>iburst</tt> or <tt>burst</tt> 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 output ceiling can be no more than eight times the minimum poll interval set by the <tt>minpoll</tt> option of the <a href="confopt.html#server"><tt>server</tt></a> 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. The current headway is displayed as the headway peer variable by the <tt>ntpq</tt> <a href="ntpq.html#pe"><tt>rv</tt></a> command.</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 interval since the last packet arrival. The entries are ordered by interval from the smallest to the largest. 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 interval 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, 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 ceiling.</p>
+<h4 id="kiss">The Kiss-of-Death Packet</h4>
+<p>Ordinarily, packets denied service are simply dropped with no further action except incrementing statistics counters. Sometimes a more proactive response is needed to cause the client to slow down. A special packet format has been created for this purpose called the kiss-o'-death (KoD) packet. KoD packets have leap indicator 3, stratum 0 and the reference identifier set to a four-byte ASCII code. At present, only one code <tt>RATE</tt> is sent by the server if the <tt>limited</tt> and <tt>kod</tt> flags are set in the <a href="accopt.html#restrict"><tt>restrict</tt></a> command and the rate limit is exceeded.</p>
+<p>A client receiving a KoD packet is expected to slow down; however, no explicit mechanism is specified in the protocol to do this. In the current reference implementation, the server sets the packet poll to the greater of (a) minimum average headway and (b) client packet poll. The client sets the peer poll field to the maximum of (a) minimum average headway and (b) server packet poll. For KoD packets (only), the minimum peer poll is clamped not less than the peer poll and the headway temporarily increased. </p>
+<p>At present there is only one KoD packet with code <tt>RATE.</tt> 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>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <title>Debugging Reference Clock Drivers</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Debugging Reference Clock Drivers</h3>
- <img src="pic/oz2.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
- <p>Call the girls and the'll sweep your bugs.</p>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">01:24</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="308">Saturday, November 24, 2007</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
- <hr>
- <p>The <a href="ntpq.html"><tt>ntpq</tt></a> and <a href="ntpdc.html"><tt>ntpdc</tt></a> utility programs can be used to debug reference clocks, either on the server itself or from another machine elsewhere in the network. The server is compiled, installed and started using the configuration file described in the <a href="ntpd.html"><tt>ntpd</tt></a> page and its dependencies. If the clock appears in the <tt>ntpq</tt> utility and <tt>pe</tt> command, no errors have occurred and the daemon has started, opened the devices specified and waiting for peers and radios to come up. If not, the first thing to look for are error messages on the system log. These are usually due to improper configuration, missing links or multiple instances of the daemon.</p>
- <p>It normally takes a minute or so for evidence to appear that the clock is running and the driver is operating correctly. The first indication is a nonzero value in the <tt>reach</tt> column in the <tt>pe</tt> billboard. If nothing appears after a few minutes, the next step is to be sure the RS232 messages, if used, are getting to and from the clock. The most reliable way to do this is with an RS232 tester and to look for data flashes as the driver polls the clock and/or as data arrive from the clock. Our experience is that the overwhelming fraction of problems occurring during installation are due to problems such as miswired connectors or improperly configured device links at this stage.</p>
- <p>If RS232 messages are getting to and from the clock, the variables of interest can be inspected using the <tt>ntpq</tt> program and various commands described on the documentation page. First, use the <tt>pe</tt> and <tt>as</tt> commands to display billboards showing the peer configuration and association IDs for all peers, including the radio clock. The assigned clock address should appear in the <tt>pe</tt> billboard and the association ID for it at the same relative line position in the <tt>as</tt> billboard.</p>
- <p>Additional information is available with the <tt>rv</tt> and <tt>clockvar</tt> commands, which take as argument the association ID shown in the <tt>as</tt> billboard. The <tt>rv</tt> command with no argument shows the system variables, while the <tt>rv</tt> command with association ID argument shows the peer variables for the clock, as well as other peers of interest. The <tt>clockvar</tt> command with argument shows the peer variables specific to reference clock peers, including the clock status, device name, last received timecode (if relevant), and various event counters. In addition, a subset of the <tt>fudge</tt> parameters is included. The poll and error counters in the <tt>clockvar</tt> billboard are useful debugging aids. The <tt>poll</tt> counts the poll messages sent to the clock, while the <tt>noreply</tt>, <tt>badformat</tt> and <tt>baddate</tt> count various errors. Check the timecode to be sure it matches what the driver expects. This may require consulting the clock hardware reference manual, which is probably pretty dusty at this stage.</p>
- <p>The <tt>ntpdc</tt> utility program can be used for detailed inspection of the clock driver status. The most useful are the <tt>clockstat</tt> and <tt>clkbug</tt> commands described in the document page. While these commands permit getting quite personal with the particular driver involved, their use is seldom necessary, unless an implementation bug shows up. If all else fails, turn on the debugging trace using two <tt>-d</tt> flags in the <tt>ntpd</tt> startup command line. Most drivers will dump status at every received message in this case. While the displayed trace can be intimidating, this provides the most detailed and revealing indicator of how the driver and clock are performing and where bugs might lurk.</p>
- <p>Most drivers write a message to the <tt>clockstats</tt> file as each timecode or surrogate is received from the radio clock. By convention, this is the last ASCII timecode (or ASCII gloss of a binary-coded one) received from the radio clock. This file is managed by the <tt>filegen</tt> facility described in the <tt>ntpd</tt> page and requires specific commands in the configuration file. This forms a highly useful record to discover anomalies during regular operation of the clock. The scripts included in the <tt>./scripts/stats</tt> directory can be run from a <tt>cron</tt> job to collect and summarize these data on a daily or weekly basis. The summary files have proven inspirational to detect infrequent misbehavior due to clock implementation bugs in some radios.</p>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<title>Debugging Reference Clock Drivers</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Debugging Reference Clock Drivers</h3>
+<img src="pic/oz2.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>The Wizard of Oz</i>, L. Frank Baum</a>
+<p>Call the girls and the'll sweep your bugs.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->
+ 03-Sep-2010 1:35
+ <!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+<hr>
+<p>The <a href="ntpq.html"><tt>ntpq</tt></a> and <a href="ntpdc.html"><tt>ntpdc</tt></a> utility programs can be used to debug reference clocks, either on the server itself or from another machine elsewhere in the network. The server is compiled, installed and started using the configuration file described in the <a href="ntpd.html"><tt>ntpd</tt></a> page and its dependencies. If the clock appears in the <tt>ntpq</tt> utility and <tt>pe</tt> command, no errors have occurred and the daemon has started, opened the devices specified and waiting for peers and radios to come up. If not, the first thing to look for are error messages on the system log. These are usually due to improper configuration, missing links or multiple instances of the daemon.</p>
+<p>It normally takes a minute or so for evidence to appear that the clock is running and the driver is operating correctly. The first indication is a nonzero value in the <tt>reach</tt> column in the <tt>pe</tt> billboard. If nothing appears after a few minutes, the next step is to be sure the RS232 messages, if used, are getting to and from the clock. The most reliable way to do this is with an RS232 tester and to look for data flashes as the driver polls the clock and/or as data arrive from the clock. Our experience is that the overwhelming fraction of problems occurring during installation are due to problems such as miswired connectors or improperly configured device links at this stage.</p>
+<p>If RS232 messages are getting to and from the clock, the variables of interest can be inspected using the <tt>ntpq</tt> program and various commands described on the documentation page. First, use the <tt>pe</tt> and <tt>as</tt> commands to display billboards showing the peer configuration and association IDs for all peers, including the radio clock. The assigned clock address should appear in the <tt>pe</tt> billboard and the association ID for it at the same relative line position in the <tt>as</tt> billboard.</p>
+<p>Additional information is available with the <tt>rv</tt> and <tt>clockvar</tt> commands, which take as argument the association ID shown in the <tt>as</tt> billboard. The <tt>rv</tt> command with no argument shows the system variables, while the <tt>rv</tt> command with association ID argument shows the peer variables for the clock, as well as other peers of interest. The <tt>clockvar</tt> command with argument shows the peer variables specific to reference clock peers, including the clock status, device name, last received timecode (if relevant), and various event counters. In addition, a subset of the <tt>fudge</tt> parameters is included. The poll and error counters in the <tt>clockvar</tt> billboard are useful debugging aids. The <tt>poll</tt> counts the poll messages sent to the clock, while the <tt>noreply</tt>, <tt>badformat</tt> and <tt>baddate</tt> count various errors. Check the timecode to be sure it matches what the driver expects. This may require consulting the clock hardware reference manual, which is probably pretty dusty at this stage.</p>
+<p>The <tt>ntpdc</tt> utility program can be used for detailed inspection of the clock driver status. The most useful are the <tt>clockstat</tt> and <tt>clkbug</tt> commands described in the document page. While these commands permit getting quite personal with the particular driver involved, their use is seldom necessary, unless an implementation bug shows up. If all else fails, turn on the debugging trace using two <tt>-d</tt> flags in the <tt>ntpd</tt> startup command line. Most drivers will dump status at every received message in this case. While the displayed trace can be intimidating, this provides the most detailed and revealing indicator of how the driver and clock are performing and where bugs might lurk.</p>
+<p>Most drivers write a message to the <tt>clockstats</tt> file as each timecode or surrogate is received from the radio clock. By convention, this is the last ASCII timecode (or ASCII gloss of a binary-coded one) received from the radio clock. This file is managed by the <tt>filegen</tt> facility described in the <tt>ntpd</tt> page and requires specific commands in the configuration file. This forms a highly useful record to discover anomalies during regular operation of the clock. The scripts included in the <tt>./scripts/stats</tt> directory can be run from a <tt>cron</tt> job to collect and summarize these data on a daily or weekly basis. The summary files have proven inspirational to detect infrequent misbehavior due to clock implementation bugs in some radios.</p>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Reference Clock Drivers</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Reference Clock Drivers</h3>
- <img src="pic/stack1a.jpg" alt="gif" align="left">Master Time Facility at the <a href="http://www.eecis.udel.edu/%7emills/lab.html">UDel Internet Research Laboratory</a>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:45</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="286">Thursday, January 03, 2008</csobj></p>
- <br clear="left">
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
- <h4>Table of Contents</h4>
- <ul>
- <li class="inline"><a href="#clock">Introduction</a></li>
- <li class="inline"><a href="#cal">Driver Calibration</a></li>
- <li class="inline"><a href="#list">Comprehensive List of Clock Drivers</a></li>
- </ul>
- <hr>
- <h4 id="clock">Introduction</h4>
- <p>Drivers for most radio and modem reference clocks is included by default in the NTP distribution. Individual drivers can be activated using <tt>server</tt> commands as described in the <a href="ntpd.html"><tt>ntpd</tt> program manual page</a>. Drivers have addresses in the form 127.127.<i>t.u</i>, where <i>t</i> is the driver type and <i>u</i> is a unit number in the range 0-3 to distinguish multiple instances of the same driver. Most drivers require a serial or parallel port or special bus peripheral, but some can work directly from an audio codec or sound card when availble. The particular device is specified by adding a soft link from the name used by the driver to the device name.</p>
- <p>All radio clock drivers require that the radio be set for Coordinated Universal Time (UTC) only. Timezone and standard/daylight adjustments are performed by the kernel. There are difference in the various Unix and Windows port interfaces detected at configuration time, so it is important that the NTP daemon and utilities be compiled on the target system or clone.</p>
- <p>When a pulse-per-second (PPS) signal is available, the <a href="drivers/driver22.html"> PPS Clock Discipline</a> driver is can be used. It normally works in conjunction with the reference clock that produces the signal, but can work with another driver or remote server. When PPS kernel features are present, the driver can redirect the PPS signal to the kernel.</p>
- <p>In general, performance can be improved, especially when more than one driver is supported, to use the prefer peer function described in the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. The prefer peer is ordinarily designated the remote peer or local clock driver which provides the best quality time. All other things equal, only the prefer peer is used to discipline the system clock and jitter-producing "clockhopping" between sources is avoided. This is especially valuable when the PPS clock discipline driver is available.</p>
- <p>There are audio drivers for each of the NIST time stations WWV and WWVH, Canadian time station CHU and generic IRIG signals. Currently, support for FreeBSD, Solaris and SunOS is in the distribution. It is left to the volunteer corps to confirm this works in other systems. Further information on hookup, debugging and monitoring is given in the <a href="audio.html">Audio Drivers</a> page.</p>
- <p>The <a href="drivers/driver1.html"> Undisciplined Local Clock</a> driver can simulate a reference clock when no external synchronization sources are available. If a server with this driver is connected directly or indirectly to the public Internet, there is some danger that it can destabilize other clients. It is not recommended that the loccal clock driver be used in this way, as the orphan mode descibed on the <a href="assoc.html">Association Management</a> page provides a generic backup capability.</p>
- <p>The local clock driver can also be used when an external synchronization source such as the IEEE 1588 Precision Time Protocol or NIST Lockclock directly synchronizes the computer time. Further information is on the <a href="extern.html">External Clock Discipline and the Local Clock Driver</a> page.</p>
- <h4 id="cal">Driver Calibration</h4>
- <p>Some drivers depending on longwave or shortwave radio services need to know the radio propagation time from the transmitter to the receiver. This must be calculated for each specific receiver location and requires the geographic coordinates of both the transmitter and receiver. The transmitter coordinates for various radio services are given in the <a href="http://www.eecis.udel.edu/%7emills/ntp/qth.html">Time and Frequency Standard Station Information</a> page. Receiver coordinates can be obtained locally or from Google Earth. The actual calculations are beyond the scope of this document.</p>
- <p>Depending on interface type, port speed, etc., a reference clock can have a small residual offset relative to another. To reduce the effects of jitter when switching from one driver to the another, it is useful to calibrate the drivers to a common ensemble offset. The <tt>enable calibrate</tt> configuration command described on the <a href="miscopt.html">Miscellaneous Options</a> page activates a special feature which automatically calculates a correction factor for each driver relative to an association designated the prefer peer.</p>
- <h4 id="list">Comprehensive List of Clock Drivers</h4>
- <p>Following is a list showing the type and title of each driver currently implemented. The compile-time identifier for each is shown in parentheses. Click on a selected type for specific description and configuration documentation, including the clock address, reference ID, driver ID, device name and serial line speed. For those drivers without specific documentation, please contact the author listed in the <a href="copyright.html">Copyright Notice</a> page.</p>
- <ul>
- <li class="inline"><a href="drivers/driver1.html">Type 1</a> Undisciplined Local Clock (<tt>LOCAL</tt>)</li>
- <li class="inline"><a href="drivers/driver2.html">Type 2</a> Trak 8820 GPS Receiver (<tt>GPS_TRAK</tt>)</li>
- <li class="inline"><a href="drivers/driver3.html">Type 3</a> PSTI/Traconex 1020 WWV/WWVH Receiver (<tt>WWV_PST</tt>)</li>
- <li class="inline"><a href="drivers/driver4.html">Type 4</a> Spectracom WWVB/GPS Receivers (<tt>WWVB_SPEC</tt>)</li>
- <li class="inline"><a href="drivers/driver5.html">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers (<tt>TRUETIME</tt>)</li>
- <li class="inline"><a href="drivers/driver6.html">Type 6</a> IRIG Audio Decoder (<tt>IRIG_AUDIO</tt>)</li>
- <li class="inline"><a href="drivers/driver7.html">Type 7</a> Radio CHU Audio Demodulator/Decoder (<tt>CHU</tt>)</li>
- <li class="inline"><a href="drivers/driver8.html">Type 8</a> Generic Reference Driver (<tt>PARSE</tt>)</li>
- <li class="inline"><a href="drivers/driver9.html">Type 9</a> Magnavox MX4200 GPS Receiver (<tt>GPS_MX4200</tt>)</li>
- <li class="inline"><a href="drivers/driver10.html">Type 10</a> Austron 2200A/2201A GPS Receivers (<tt>GPS_AS2201</tt>)</li>
- <li class="inline"><a href="drivers/driver11.html">Type 11</a> Arbiter 1088A/B GPS Receiver (<tt>GPS_ARBITER</tt>)</li>
- <li class="inline"><a href="drivers/driver12.html">Type 12</a> KSI/Odetics TPRO/S IRIG Interface (<tt>IRIG_TPRO</tt>)</li>
- <li class="inline">Type 13 Leitch CSD 5300 Master Clock Controller (<tt>ATOM_LEITCH</tt>)</li>
- <li class="inline">Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>)</li>
- <li class="inline">Type 15 reserved</li>
- <li class="inline"><a href="drivers/driver16.html">Type 16</a> Bancomm GPS/IRIG Receiver (<tt>GPS_BANCOMM</tt>)</li>
- <li class="inline">Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>)</li>
- <li class="inline"><a href="drivers/driver18.html">Type 18</a> NIST/USNO/PTB Modem Time Services (<tt>ACTS_MODEM</tt>)</li>
- <li class="inline"><a href="drivers/driver19.html">Type 19</a> Heath WWV/WWVH Receiver (<tt>WWV_HEATH</tt>)</li>
- <li class="inline"><a href="drivers/driver20.html">Type 20</a> Generic NMEA GPS Receiver (<tt>NMEA</tt>)</li>
- <li class="inline">Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>)</li>
- <li class="inline"><a href="drivers/driver22.html">Type 22</a> PPS Clock Discipline (<tt>PPS</tt>)</li>
- <li class="inline">Type 23 reserved</li>
- <li class="inline">Type 24 reserved</li>
- <li class="inline">Type 25 reserved</li>
- <li class="inline"><a href="drivers/driver26.html">Type 26</a> Hewlett Packard 58503A GPS Receiver (<tt>GPS_HP</tt>)</li>
- <li class="inline"><a href="drivers/driver27.html">Type 27</a> Arcron MSF Receiver (<tt>MSF_ARCRON</tt>)</li>
- <li class="inline"><a href="drivers/driver28.html">Type 28</a> Shared Memory Driver (<tt>SHM</tt>)</li>
- <li class="inline"><a href="drivers/driver29.html">Type 29</a> Trimble Navigation Palisade GPS (<tt>GPS_PALISADE</tt>)</li>
- <li class="inline"><a href="drivers/driver30.html">Type 30</a> Motorola UT Oncore GPS <tt>GPS_ONCORE</tt>)</li>
- <li class="inline"><a href="drivers/driver31.html">Type 31</a> Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)</li>
- <li class="inline"><a href="drivers/driver32.html">Type 32</a> Chrono-log K-series WWVB receiver (<tt>CHRONOLOG</tt>)</li>
- <li class="inline"><a href="drivers/driver33.html">Type 33</a> Dumb Clock (<tt>DUMBCLOCK</tt>)</li>
- <li class="inline"><a href="drivers/driver34.html">Type 34</a> Ultralink WWVB Receivers (<tt>ULINK</tt>)</li>
- <li class="inline"><a href="drivers/driver35.html">Type 35</a> Conrad Parallel Port Radio Clock (<tt>PCF</tt>)</li>
- <li class="inline"><a href="drivers/driver36.html">Type 36</a> Radio WWV/H Audio Demodulator/Decoder (<tt>WWV</tt>)</li>
- <li class="inline"><a href="drivers/driver37.html">Type 37</a> Forum Graphic GPS Dating station (<tt>FG</tt>)</li>
- <li class="inline"><a href="drivers/driver38.html">Type 38</a> hopf GPS/DCF77 6021/komp for Serial Line (<tt>HOPF_S</tt>)</li>
- <li class="inline"><a href="drivers/driver39.html">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus (<tt>HOPF_P</tt>)</li>
- <li class="inline"><a href="drivers/driver40.html">Type 40</a> JJY Receivers (<tt>JJY</tt>)</li>
- <li class="inline">Type 41 TrueTime 560 IRIG-B Decoder</li>
- <li class="inline"><a href="drivers/driver42.html">Type 42</a> Zyfer GPStarplus Receiver</li>
- <li class="inline"><a href="drivers/driver43.html">Type 43</a> RIPE NCC interface for Trimble Palisade</li>
- <li class="inline"><a href="drivers/driver44.html">Type 44</a> NeoClock4X - DCF77 / TDF serial line</li>
- </ul>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Reference Clock Support</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Reference Clock Support</h3>
+<img src="pic/stack1a.jpg" alt="gif" align="left">Master Time Facility at the <a href="http://www.eecis.udel.edu/%7emills/lab.html">UDel Internet Research Laboratory</a>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->09-Sep-2010 18:33<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#intro">Introduction</a></li>
+ <li class="inline"><a href="#spec">Special Considerations</a></li>
+ <li class="inline"><a href="#list">List of Reference Clock Drivers</a></li>
+</ul>
+<hr>
+<h4 id="intro">Introduction</h4>
+<p>NTP Version 4 supports almost four dozen satellite, radio and telephone modem reference clocks plus several audio devices for instrumentation signals. A general description of the reference clock support is on this page. Additional information about each reference clock driver can be found via links from this page. Additional information is on the <a href="rdebug.html">Debugging Hints for Reference Clock Drivers</a> and <a href="howto.html">How To Write a Reference Clock Driver</a> pages. Information on how to support pulse-per-second (PPS) signals produced by some devices is on the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. All reference clock drivers require that the reference clock use only Coordinated Universal Time (UTC). Timezone and standard/daylight adjustments are performed by the operating system kernel.</p>
+<p>A reference clock will generally (though not always) be a radio timecode receiver synchronized to standard time as provided by NIST and USNO in the US, NRC in Canada and their counterparts elsewhere in the world. A device driver specific to each reference clock must be compiled in the distribution; however, most common radio, satellite and telephone modem clocks are included by default and are activated by configuration commands.</p>
+<p>Reference clocks are supported in the same way as ordinary NTP clients and use the same filter, select, cluster and combine algorithms. Drivers have addresses in the form 127.127.<i>t.u</i>, where <i>t</i> is the driver type and <i>u</i> is a unit number in the range 0-3 to distinguish multiple instances of the same driver. The connection to the computer is device dependent, usually a serial port, parallel port or special bus peripheral, but some can work directly from an audio codec or sound card. The particular device is specified by adding a soft link from the name used by the driver to the particular device name.</p>
+<p>The <tt>server</tt> command is used to configure a reference clock. Only the <tt>minpoll</tt>, <tt>maxpoll</tt>, <tt>prefer</tt> and <tt>maxpoll</tt> options are supported for reference clocks, as described on the <a href="clockopt.html">Reference Clock Commands</a> page. The <tt>prefer</tt> option is discussed on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. Some of these options have meaning only for selected clock drivers.</p>
+<p>The <tt>fudge</tt> command can be used to provide additional information for individual drivers and normally follows immediately after the <tt>server</tt> command. The reference clock stratum is by default 0, so that the server stratum appears to clients as 1. The <tt>stratum</tt> option can be used to set the stratum to any value in the range 0 through 15. The <tt>refid</tt> option can be used to change the reference identifier, as might in the case when the driver is disciplined by a pulse-per-second (PPS) source. The device-dependent <tt>mode</tt>, <tt>time</tt> and <tt>flag</tt> options can provide additional driver customization.</p>
+<h4 id="spec">Special Considerations</h4>
+<p>The <a href="audio.html">Audio Drivers</a> page describes three software drivers that process audio signals from an audio codec or sound card. One is for the NIST time and frequency stations WWV and WWVH, another for the Canadian time and frequency station CHU. These require an external shortwave radio and antenna. A third is for the generic IRIG signal produced by some timing devices. Currently, these are supported in FreeBSD, Solaris and SunOS and likely in other system as well.</p>
+<p>The <a href="drivers/driver1.html"> Undisciplined Local Clock</a> driver can simulate a reference clock when no external synchronization sources are available. If a server with this driver is connected directly or indirectly to the public Internet, there is some danger that it can destabilize other clients. It is not recommended that the local clock driver be used in this way, as the orphan mode described on the <a href="assoc.html">Association Management</a> page provides a generic backup capability.</p>
+<p>The local clock driver can also be used when an external synchronization source such as the IEEE 1588 Precision Time Protocol or NIST Lockclock directly synchronizes the computer time. Further information is on the <a href="extern.html">External Clock Discipline and the Local Clock Driver</a> page.</p>
+<p>Several drivers make use of the pulse-per-second (PPS) signal discipline, which is part of the generic driver interface, so require no specific configuration. For those drivers that do not use this interface, the <a href="drivers/driver22.html"> PPS Clock Discipline</a> driver can be can provide this function. It normally works in conjunction with the reference clock that produces the timecode signal, but can work with another driver or remote server. When PPS kernel features are present, the driver can redirect the PPS signal to the kernel.</p>
+<p>Some drivers depending on longwave or shortwave radio services need to know the radio propagation time from the transmitter to the receiver. This must be calculated for each specific receiver location and requires the geographic coordinates of both the transmitter and receiver. The transmitter coordinates for various radio services are given in the <a href="http://www.eecis.udel.edu/%7emills/ntp/qth.html">Time and Frequency Standard Station Information</a> page. Receiver coordinates can be obtained locally or from Google Earth. The actual calculations are beyond the scope of this document.</p>
+<p>Depending on interface type, port speed, etc., a reference clock can have a small residual offset relative to another. To reduce the effects of jitter when switching from one driver to the another, it is useful to calibrate the drivers to a common ensemble offset. The <tt>enable calibrate</tt> configuration command described on the <a href="miscopt.html">Miscellaneous Options</a> page activates a special feature which automatically calculates a correction factor for each driver relative to an association designated the prefer peer.</p>
+<h4 id="list"> List of Reference Clock Drivers</h4>
+<p>Following is a list showing the type and title of each driver currently implemented. The compile-time identifier for each is shown in parentheses. Click on a selected type for specific description and configuration documentation, including the clock address, reference ID, driver ID, device name and serial line speed. For those drivers without specific documentation, please contact the author listed in the <a href="copyright.html">Copyright Notice</a> page.</p>
+<ul>
+ <li class="inline"><a href="drivers/driver1.html">Type 1</a> Undisciplined Local Clock (<tt>LOCAL</tt>)</li>
+ <li class="inline"><a href="drivers/driver2.html">Type 2</a> Trak 8820 GPS Receiver (<tt>GPS_TRAK</tt>)</li>
+ <li class="inline"><a href="drivers/driver3.html">Type 3</a> PSTI/Traconex 1020 WWV/WWVH Receiver (<tt>WWV_PST</tt>)</li>
+ <li class="inline"><a href="drivers/driver4.html">Type 4</a> Spectracom WWVB/GPS Receivers (<tt>WWVB_SPEC</tt>)</li>
+ <li class="inline"><a href="drivers/driver5.html">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers (<tt>TRUETIME</tt>)</li>
+ <li class="inline"><a href="drivers/driver6.html">Type 6</a> IRIG Audio Decoder (<tt>IRIG_AUDIO</tt>)</li>
+ <li class="inline"><a href="drivers/driver7.html">Type 7</a> Radio CHU Audio Demodulator/Decoder (<tt>CHU</tt>)</li>
+ <li class="inline"><a href="drivers/driver8.html">Type 8</a> Generic Reference Driver (<tt>PARSE</tt>)</li>
+ <li class="inline"><a href="drivers/driver9.html">Type 9</a> Magnavox MX4200 GPS Receiver (<tt>GPS_MX4200</tt>)</li>
+ <li class="inline"><a href="drivers/driver10.html">Type 10</a> Austron 2200A/2201A GPS Receivers (<tt>GPS_AS2201</tt>)</li>
+ <li class="inline"><a href="drivers/driver11.html">Type 11</a> Arbiter 1088A/B GPS Receiver (<tt>GPS_ARBITER</tt>)</li>
+ <li class="inline"><a href="drivers/driver12.html">Type 12</a> KSI/Odetics TPRO/S IRIG Interface (<tt>IRIG_TPRO</tt>)</li>
+ <li class="inline">Type 13 Leitch CSD 5300 Master Clock Controller (<tt>ATOM_LEITCH</tt>)</li>
+ <li class="inline">Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>)</li>
+ <li class="inline">Type 15 reserved</li>
+ <li class="inline"><a href="drivers/driver16.html">Type 16</a> Bancomm GPS/IRIG Receiver (<tt>GPS_BANCOMM</tt>)</li>
+ <li class="inline">Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>)</li>
+ <li class="inline"><a href="drivers/driver18.html">Type 18</a> NIST/USNO/PTB Modem Time Services (<tt>ACTS_MODEM</tt>)</li>
+ <li class="inline"><a href="drivers/driver19.html">Type 19</a> Heath WWV/WWVH Receiver (<tt>WWV_HEATH</tt>)</li>
+ <li class="inline"><a href="drivers/driver20.html">Type 20</a> Generic NMEA GPS Receiver (<tt>NMEA</tt>)</li>
+ <li class="inline">Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>)</li>
+ <li class="inline"><a href="drivers/driver22.html">Type 22</a> PPS Clock Discipline (<tt>PPS</tt>)</li>
+ <li class="inline">Type 23 reserved</li>
+ <li class="inline">Type 24 reserved</li>
+ <li class="inline">Type 25 reserved</li>
+ <li class="inline"><a href="drivers/driver26.html">Type 26</a> Hewlett Packard 58503A GPS Receiver (<tt>GPS_HP</tt>)</li>
+ <li class="inline"><a href="drivers/driver27.html">Type 27</a> Arcron MSF Receiver (<tt>MSF_ARCRON</tt>)</li>
+ <li class="inline"><a href="drivers/driver28.html">Type 28</a> Shared Memory Driver (<tt>SHM</tt>)</li>
+ <li class="inline"><a href="drivers/driver29.html">Type 29</a> Trimble Navigation Palisade GPS (<tt>GPS_PALISADE</tt>)</li>
+ <li class="inline"><a href="drivers/driver30.html">Type 30</a> Motorola UT Oncore GPS <tt>GPS_ONCORE</tt>)</li>
+ <li class="inline"><a href="drivers/driver31.html">Type 31</a> Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)</li>
+ <li class="inline"><a href="drivers/driver32.html">Type 32</a> Chrono-log K-series WWVB receiver (<tt>CHRONOLOG</tt>)</li>
+ <li class="inline"><a href="drivers/driver33.html">Type 33</a> Dumb Clock (<tt>DUMBCLOCK</tt>)</li>
+ <li class="inline"><a href="drivers/driver34.html">Type 34</a> Ultralink WWVB Receivers (<tt>ULINK</tt>)</li>
+ <li class="inline"><a href="drivers/driver35.html">Type 35</a> Conrad Parallel Port Radio Clock (<tt>PCF</tt>)</li>
+ <li class="inline"><a href="drivers/driver36.html">Type 36</a> Radio WWV/H Audio Demodulator/Decoder (<tt>WWV</tt>)</li>
+ <li class="inline"><a href="drivers/driver37.html">Type 37</a> Forum Graphic GPS Dating station (<tt>FG</tt>)</li>
+ <li class="inline"><a href="drivers/driver38.html">Type 38</a> hopf GPS/DCF77 6021/komp for Serial Line (<tt>HOPF_S</tt>)</li>
+ <li class="inline"><a href="drivers/driver39.html">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus (<tt>HOPF_P</tt>)</li>
+ <li class="inline"><a href="drivers/driver40.html">Type 40</a> JJY Receivers (<tt>JJY</tt>)</li>
+ <li class="inline">Type 41 TrueTime 560 IRIG-B Decoder</li>
+ <li class="inline"><a href="drivers/driver42.html">Type 42</a> Zyfer GPStarplus Receiver</li>
+ <li class="inline"><a href="drivers/driver43.html">Type 43</a> RIPE NCC interface for Trimble Palisade</li>
+ <li class="inline"><a href="drivers/driver44.html">Type 44</a> NeoClock4X - DCF77 / TDF serial line</li>
+</ul>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>NTP Version 4 Release Notes</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>NTP Version 4 Release Notes</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">16:10</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="250">Sunday, March 02, 2008</csobj></p>
- .<br clear="left">
- <hr>
- <h4>NTP Version 4 Release Notes</h4>
- <p>This release of the NTP Version 4 (NTPv4) daemon for Unix, VMS and Windows incorporates new features and refinements to the NTP Version 3 (NTPv3) algorithms. However, it continues the tradition of retaining backwards compatibility with older versions, including NTPv3 and NTPv2, but not NTPv1. Support for NTPv1 has been discontinued because of certain security vulnerabilities. The NTPv4 version has been under development for 25 years and the paint still isn't dry.</p>
- <p>The code compiles and runs properly in all test host configurations available to the developer corps, including Sun Microsystems, Digital/Compaq/Hewlett Packard, FreeBSD and Linux. Other volunteers have verified it works in IRIX and Windows NT and XP. We invite comments and corrections about the various architectures, operating systems and hardware complement that can't be verified by the developer corps. Of particular interest are other Windows versions, VMS and various reference clock drivers.</p>
- <p>This release has been compiled and tested on many systems, including SunOS 4.1.3, Solaris 2.5.1-2.10, Alpha Tru64 4.0-5.1, Ultrix 4.4, Linux 2.4.2, FreeBSD 4.5-6.2 and HP-UX 10.02. It has been compiled and tested by others on Windows NT4, 2000 and XP, but not yet on other Windows versions or for VMS. There are several new features apparently incompatible with Linux systems, including some modes used with the Autokey protocol. The developer corps looks for help elsewhere to resolve these differences.</p>
- <p>This note summarizes the differences between this software release of NTPv4, called ntp-4.x.x, and the previous NTPv3 version, called xntp3-5.x.x.</p>
- <h4>New Features</h4>
- <ol>
- <li>Support for the IPv6 addressing family is included in this distribution. If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected, support for the IPv6 address family is generated in addition to the default support for the IPv4 address family.</li>
- <li>Most calculations are now done using 64-bit floating double format, rather than 64-bit fixed point format. The motivation for this is to reduce size, improve speed and avoid messy bounds checking.</li>
- <li>The clock discipline algorithm has been redesigned to improve accuracy, reduce the impact of network jitter and allow increased in poll intervals to 36 hours with only moderate sacrifice in accuracy.</li>
- <li>A new feature called "huffpuff" maximizes accuracy in cases of highly asymmetric network delays typical of ISDN and telephone modems.</li>
- <li>The clock selection algorithm has been redesigned to reduce "clockhopping" when the choice of servers changes frequently as the result of comparatively insignificant quality changes.</li>
- <li>This release includes support for the <a href="ftp://ftp.udel.edu/usa/ftp/pub/ntp/software/">nanokernel</a> precision time kernel modifications, which are now in stock FreeBSD and optional in Linux kernels. With this support the system clock can be disciplined to the order of one nanosecon. The older microtime kernel modifications in Digital/Compaq/HP Tru64, Digital Ultrix and Sun Microsystems SunOS and Solaris, continue to be supported. In either case the support eliminates sawtooth error, which can be in the hundreds of microseconds.</li>
- <li>This release includes support for Autokey public-key cryptography, which is the preferred scheme for authenticating servers to clients. Additional information about Autokey cryptography is on the <a href="authopt.html">Authentication Options</a> page and links from there. See also the new <tt>cryptostats</tt> monitoring statistics file in the <a href="monopt.html">Monitoring Options</a> page.</li>
- <li>The OpenSSL cryptographic library has replaced the library formerly available from RSA Laboratories. All cryptographic routines except a version of the MD5 message digest routine have been removed from the base distribution.</li>
- <li>As the result of the above, the <tt>authstuff</tt> directory, intended as a development and testing aid for porting cryptographic routines to exotic architectures, has been removed. Testing and conformance validation tools are in the OpenSSL software distrbution.</li>
- <li>This release includes support for a discrete event simulator (DES), which allows the NTP algorithms to be tested in an embedded environment with systematic and pseudorandom network delay and oscillator wander distributions. This has been used to verify correct operation under conditions of extreme error and misconfiguration. See the <a href="ntpdsim.html"><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a> page.</li>
- <li>NTPv4 includes three new server discovery schemes, which in most applications can avoid per-host configuration altogether. Two of these are based on IP multicast technology, while the remaining one is based on crafted DNS lookups. See the <a href="manyopt.html">Automatic NTP Configuration Schemes</a> page for further information.</li>
- <li>This release includes comprehensive packet rate management tools to help reduce the level of spurious network traffic and protect the busiest servers from overload. See the <a href="rate.html">Rate Management and the Kiss-o'-Death Packet</a> page for further information.</li>
- <li>This release includes support for the orphan mode, which replaces the local clock driver for most configurations. Orphan mode provides an automatic, subnet-wide synchronization feature with multiple sources. It can be used in isolated networks or in Internet subnets where the servers or Internet connection have failed. See the <a href="manyopt.html">Automatic NTP Configuration Options</a> page for further information.</li>
- <li>There are two new burst mode features available where special conditions apply. One of these is enabled by the <tt>iburst</tt> keyword in the <tt>server</tt> configuration command. It is intended for cases where it is important to set the clock quickly when an association is first mobilized. The other is enabled by the <tt>burst</tt> keyword in the <tt>server</tt> configuration command. It is intended for cases where the network attachment requires an initial calling or training procedure. See the <a href="assoc.html">Association Management</a> page for further information.</li>
- <li>The reference clock driver interface is smaller, more rational and more accurate.</li>
- <li>Support for pulse-per-second (PPS) signals has been extended to all drivers as an intrinsic function. Most of the drivers in NTPv3 have been converted to the NTPv4 interface and continue to operate as before. New drivers have been added for several GPS receivers now on the market for a total of 44 drivers. Audio drivers for the Canadian standard time and frequency station CHU, the US standard time and frequency stations WWV/H and for IRIG signals have been updated and capabilities added to allow direct connection of these signals to an audio port. See the <a href="audio.html">Reference Clock Audio Drivers</a> page for further information.</li>
- <li>In all except a very few cases, all timing intervals are randomized, so that the tendency for NTPv3 to self-synchronize and bunch messages, especially with a large number of configured associations, is minimized.</li>
- <li>In NTPv3 a large number of weeds and useless code had grown over the years since the original NTP code was implemented 25 years ago. Using a powerful weedwacker, much of the shrubbery has been removed, with effect a substantial reduction in size of almost 40 percent.</li>
- <li>The entire distribution has been converted to gnu <tt>automake</tt>, which should greatly ease the task of porting to new and different programming environments, as well as reduce the incidence of bugs due to improper handling of idiosyncratic kernel functions. Version control is provided by Bitkeeper using an online repository at www.ntp.org. Trouble ticket reporting is provided using Bugzilla.</li>
- <li>Several new options have been added for the <tt>ntpd</tt> command line. For the inveterate knob twiddlers several of the more important performance variables can be changed to fit actual or perceived special conditions. In particular, the <tt>tos</tt> and <tt>tos</tt> commands can be used to adjust thresholds, throw switches and change limits.</li>
- <li>The <tt>ntpd</tt> daemon can be operated in a one-time mode similar to <tt>ntpdate</tt>, which program is headed for retirement. See the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page for the new features.</li>
- </ol>
- <h4>Nasty Surprises</h4>
- <p>There are a few things different about this release that have changed since the latest NTP Version 3 release. Following are a few things to worry about:</p>
- <ol>
- <li>Some configuration commands have been removed, others added and some changed in minor ways. See the Commands and Options collection on the <a href="sitemap.html">Site Map</a> page.</li>
- <li>When both IPv4 and IPv6 address families are in use, the host's resolver library may not choose the intended address family if a server has an IPv4 and IPv6 address associated with the same DNS name. The solution is to use the IPv4 or IPv6 address directly in such cases or use another DNS name that resolves to the intended address family. Older versions of <tt>ntpdc</tt> will show only the IPv4 associations with the <tt>peers</tt> and some other commands. Older versions of <tt>ntpq</tt> will show 0.0.0.0 for IPv6 associations with the <tt>peers</tt> and some other commands.</li>
- <li>There is a minor change to the reference ID field of the NTP packet header when operating with IPv6 associations. In IPv4 associations this field contains the 32-bit IPv4 address of the server, in order to detect and avoid loops. In IPv6 associations this field contains the first 32-bits of a MD5 hash formed from the IPv6 address. All programs in the distribution have been modified to work with both address families.</li>
- <li>The <tt>tty_clk</tt> and <tt>ppsclock</tt> pulse-per-second (PPS) line discipline/streams modules are no longer supported. The PPS function is now handled by the <a href="drivers/driver22.html">PPS Clock Discipline</a> driver, which uses the new PPSAPI application program interface adopted by the IETF. Note that the <tt>pps</tt> configuration file command has been obsoleted by the driver. See the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page for further information.</li>
- <li>Support for the NTPv1 symmetric mode has been discontinued, since it hasn't worked for years. Support continues for the NTPv1 client mode, which is used by some SNTP clients.</li>
- </ol>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>NTP Version 4 Release Notes</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>NTP Version 4 Release Notes</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:
+ <!-- #BeginDate format:En1m -->9-sep-10 18:25<!-- #EndDate -->
+ UTC</p>
+<br clear="left">
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<h4>Table of Contents</h4>
+<ul>
+ <li class="inline"><a href="#new">New Features Modes</a></li>
+ <li class="inline"><a href="#change">Changes and Upgrades Since the NTPv3 Version (xntp3-5)</a></li>
+ <li class="inline"><a href="#nasty">Nasty Surprises</a></li>
+</ul>
+<hr>
+<p>NTP has been under development for almost 30 years, but the paint ain't dry even now. This release of the NTP Version 4 (NTPv4) distribution for Unix, VMS and Windows incorporates new features and refinements, but retaining backwards compatibility with older versions, including NTPv3 and NTPv2, but not NTPv1. Support for NTPv1 has been discontinued because of certain security vulnerabilities.</p>
+<h4 id="new">New Features</h4>
+<ul>
+ <li>A new feature called interleaved mode can be used in NTP
+ symmetric and broadcast modes. It is designed to improve accuracy
+ by minimizing errors due to queueing and transmission delays. It is described on the <a href="xleave.html">NTP
+ Interleaved Modes</a> page.</li>
+ <li>The huff-n'-puff filter is designed to avoid large errors with DSL circuits and highly asymmetrical traffic, as when downloading large files. Details are on the <a href="huffpuff.html">The Huff-n'-Puff Filter</a> page.</li>
+ <li>A new feature called orphan mode provides an automatic, subnet-wide synchronization feature with multiple sources. It provides relable backup in isolated networks or in pr when Internet sources have become unavaillable. See the <a href="orphan.html">Orphan Mode</a> page for further information.</li>
+ <li>This release includes comprehensive packet rate management tools to help reduce the level of spurious network traffic and protect the busiest servers from overload. There is support for the optional Kiss-o'- Death (KoD) packet intended to slow down an abusive client. See the <a href="rate.html">Rate Management and the Kiss-o'-Death Packet</a> page for further information.</li>
+ <li>There are two new burst mode features available where special conditions apply. One of these is enabled by the <tt>iburst</tt> keyword in the <tt>server</tt> configuration command. It is intended for cases where it is important to set the clock quickly when an association is first mobilized. The other is enabled by the <tt>burst</tt> keyword in the <tt>server</tt> configuration command. It is intended for cases where the network attachment requires an initial calling or training procedure. See the <a href="assoc.html">Association Management</a> page for further information.</li>
+ <li>The OpenSSL cryptographic library has replaced the library formerly available from RSA Laboratories. All cryptographic routines except a version of the MD5 message digest routine have been removed from the base distribution. All 128- and 160- bit message digests routines are now supported for both symmetric key and public key cryptosystems. See the <a href="authentic">Authetication Support</a> pagefor further information and the <a href="authopt.html">Authentication Options</a> page for a list of supported digest algorithms.</li>
+ <li>This release includes support for Autokey public-key cryptography for authenticating public servers to clients, as described in RFC 5906. This support requires the --enabld-autokey option when building the distribution. Additional information about Autokey is on the <a href="autokey.html">Autokey Publid Key Authentication</a> page and links from there.</li>
+ <li>The NTP descrete even simulator has been substantially upgraded, now including scenarios with multiple servers and time-sensitive scripts. This allows the NTP algorithms to be tested in an embedded environment with systematic and pseudo-random network delay and oscillator wander distributions. This has been used to verify correct operation under conditions of extreme error and misconfiguration. See the <a href="ntpdsim.html"><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a> page. A technical description and performance analysis is given in the white papers at the <a href="http://www.eecis.udel.edu/~mills/ntp.html">NTP Project Page</a>.</li>
+ <li>NTPv4 includes three new server discovery schemes, which in most applications can avoid per-host configuration altogether. Two of these are based on IP multicast technology, while the remaining one is based on crafted DNS lookups. See the <a href="manyopt.html">Automatic NTP Configuration Schemes</a> page for further information.</li>
+ <li>The status display and event report monitoring functions have been considerably expanded, including new statistics files and event reporting to files and the system log. See the <a href="decode.html">Event Messages and Status Words</a> page for further information.</li>
+ <li>Several new options have been added for the <tt>ntpd</tt> command line. For the inveterate knob twiddlers several of the more important performance variables can be changed to fit actual or perceived special conditions. In particular, the <tt>tinker</tt> and <tt>tos</tt> commands can be used to adjust thresholds, throw switches and change limits.</li>
+ <li>The <tt>ntpd</tt> daemon can be operated in a one-time mode similar to <tt>ntpdate</tt>, which program is headed for retirement. See the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page for the new features.</li>
+</ul>
+<h4 id="change">Changes and Upgrades Since the NTPv3 Version (xntp3-5) </h4>
+<ul>
+ <li>If the Basic Socket Interface Extensions for IPv6 (RFC-2553) is detected, support for the IPv6 address family is supported in addition to the default support for the IPv4 address family. In contexts where a host name is expected, a <tt>-4</tt> qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a <tt>-6</tt> qualifier forces DNS resolution to the IPv6 namespace.</li>
+ <li>Many changes have been made in the NTP algorithms to improve performance and reliability A clock state machine has been incorporated to improve behavior under transient conditions. The clock discipline algorithm has been redesigned to improve accuracy, reduce the impact of network disruptions and allow increased poll intervals to 36 hours with only moderate sacrifice in accuracy. The clock select, cluster and combine algorithms have been overhauled as the result of a thorough statistical analysis.</li>
+ <li>In all except a very few cases, all timing intervals are randomized, so that the tendency for NTPv3 to self-synchronize and bunch messages, especially with a large number of configured associations, is minimized.</li>
+ <li>Support for the precision time kernel modifications, which are now in stock FreeBSD and optional in Linux kernels, is included. With this support the system clock can be disciplined to the order of one nanosecond. The older microtime kernel modifications in Digital/Compaq/HP Tru64, Digital Ultrix and Sun Microsystems SunOS and Solaris, continue to be supported. In either case the support eliminates sawtooth error, which can be in the hundreds of microseconds. Further information is on the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page.</li>
+ <li>New reference clock drivers have been added for several GPS receivers now on the market for a total of 44 drivers. The reference clock driver interface is smaller, more rational, more flexible and more accurate. Most of the drivers in NTPv3 have been converted to the NTPv4 interface and continue to operate as before. A summary of the supported drivers is on the <a href="refclock.html">Reference Clock Support</a> page. Audio drivers for the Canadian standard time and frequency station CHU, the US standard time and frequency stations WWV/H and for IRIG signals have been updated and capabilities added to allow direct connection of these signals to an audio port. See the <a href="audio.html">Reference Clock Audio Drivers</a> page for further information.</li>
+ <li>Support for pulse-per-second (PPS) signals has been extended to all drivers as an intrinsic function. Further information is on the <a href="pps.html">Pulse-Per-Second (PPS) Signal Interfacing</a> page. Typical performance with the PPS interface and a fast machine are in the low microseconds.</li>
+ <li>Several small changes have been made to make administration and maintenance more convenience. The entire distribution has been converted to gnu <tt>automake</tt>, which greatly ease the task of porting to new and different programming environments, as well as reduce the incidence of bugs due to improper handling of idiosyncratic kernel functions. Version control is provided by Bitkeeper using an online repository at www.ntp.org. Trouble ticket reporting is provided using Bugzilla. If <tt>ntpd</tt>, is configured with NetInfo support, it will attempt to read its configuration from the NetInfo service if the default <tt>ntp.conf</tt> file cannot be read and no file is specified by the <tt>-c</tt> option.When <tt>ntpd</tt> starts it looks at the value of <tt>umask</tt>, and if zero <tt>ntpd</tt> will set the <tt>umask</tt> to <tt>022</tt>.</li>
+</ul>
+<h4 id="nasty">Nasty Surprises</h4>
+<p>There are a few things different about this release that have changed since the latest NTP Version 3 release. Following are a few things to worry about:</p>
+<ul>
+ <li>Some configuration commands have been removed, others added and some changed in minor ways. See the Commands and Options collection on the <a href="sitemap.html">Site Map</a> page.</li>
+ <li>When both IPv4 and IPv6 address families are in use, the host's resolver library may not choose the intended address family if a server has an IPv4 and IPv6 address associated with the same DNS name. The solution is to use the IPv4 or IPv6 address directly in such cases or use another DNS name that resolves to the intended address family. Older versions of <tt>ntpdc</tt> will show only the IPv4 associations with the <tt>peers</tt> and some other commands. Older versions of <tt>ntpq</tt> will show 0.0.0.0 for IPv6 associations with the <tt>peers</tt> and some other commands.</li>
+ <li>There is a minor change to the reference ID field of the NTP packet header when operating with IPv6 associations. In IPv4 associations this field contains the 32-bit IPv4 address of the server, in order to detect and avoid loops. In IPv6 associations this field contains the first 32-bits of a MD5 hash formed from the IPv6 address. All programs in the distribution have been modified to work with both address families.</li>
+ <li>The <tt>tty_clk</tt> and <tt>ppsclock</tt> pulse-per-second (PPS) line discipline/streams modules are no longer supported. The PPS function is now handled by the <a href="drivers/driver22.html">PPS Clock Discipline</a> driver, which uses the new PPSAPI application program interface adopted by the IETF. Note that the <tt>pps</tt> configuration file command has been obsoleted by the driver. See the <a href="pps.html">Pulse-Per-Second (PPS) Signal Interfacing</a> page for further information.</li>
+ <li>Support for the NTPv1 symmetric mode has been discontinued, since it hasn't worked for years. Support continues for the NTPv1 client mode, which is used by some SNTP clients.</li>
+ <li>The <tt>authstuff</tt> directory, intended as a development and testing aid for porting cryptographic routines to exotic architectures, has been removed. Testing and conformance validation tools are available in the OpenSSL software distribution.</li>
+</ul>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
-document.write("<
h4>Access Control Commands</h4><p><ul>\
-<li class='inline'><a href='accopt.html#discard'>discard - specify headway parameters</a><br>\
-<li class='inline'><a href='accopt.html#restrict'>restrict - specify access restrictions</a><br>\
-<li class='inline'><a href='comdex.html'>Command Index</a></p>\
+document.write("<
p>Access Control Commands and Options</p><ul>\
+<li class='inline'><a href='accopt.html#discard'>discard - specify headway parameters</a></li>\
+<li class='inline'><a href='accopt.html#restrict'>restrict - specify access restrictions</a></li>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
</ul>")
\ No newline at end of file
-document.write("<ul><p>Reference Clock Audio Drivers<br><ul>\
-<li class='inline'><a href='audio.html'>Reference Clock Audio Drivers</a><br>\
-<li class='inline'><a href='drivers/driver7.html'>Radio CHU Audio Demodulator/Decoder</a><br>\
-<li class='inline'><a href='drivers/driver36.html'>Radio WWV/H Audio Demodulator/Decoder</a><br>\
+document.write("<p>Reference Clock Audio Drivers</p><ul>\
<li class='inline'><a href='drivers/driver6.html'>IRIG Audio Decoder</a>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
-</ul></ul>")
\ No newline at end of file
+<li class='inline'><a href='drivers/driver7.html'>Radio CHU Audio Demodulator/Decoder</a></li>\
+<li class='inline'><a href='drivers/driver36.html'>Radio WWV/H Audio Demodulator/Decoder</a></li>\
+<li class='inline'><a href='audio.html'>Reference Clock Audio Drivers</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
-document.write("<
h4>Authentication Commands</h4><p><ul>\
-<li class='inline'><a href='authopt.html#automax'>automax - specify Autokey regeneration interval</a><br>\
-<li class='inline'><a href='authopt.html#controlkey'>controlkey - specify control key ID</a><br>\
-<li class='inline'><a href='authopt.html#crypto'>crypto - configure Autokey parameters</a><br>\
-<li class='inline'><a href='authopt.html#keysdir'>keysdir - specify Autokey key directory</a><br>\
-<li class='inline'><a href='authopt.html#requestkey'>requestkey - specify request key ID</a><br>\
-<li class='inline'><a href='authopt.html#revoke'>revoke - specify Autokey randomization interval</a><br>\
-<li class='inline'><a href='authopt.html#trustedkey'>trustedkey - specify trusted key IDs</a><br>\
-<li class='inline'><a href='comdex.html'>Command Index</a></p>\
+document.write("<
p>Authentication Commands and Options</p4><ul>\
+<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#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='authopt.html#trustedkey'>trustedkey - specify trusted key IDs</a></li>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
</ul>")
\ No newline at end of file
-document.write("<h4>Reference Clock Commands</h4><p><ul>\
-<li class='inline'><a href='clockopt.html#server'>server - specify reference clock server</a><br>\
+document.write("<p>Reference Clock Commands and Options</p><ul>\
<li class='inline'><a href='clockopt.html#fudge'>fudge - specify fudge parameters</a><br>\
-<li class='inline'><a href='comdex.html'>Command Index</a></p>\
+<li class='inline'><a href='clockopt.html#server'>server - specify reference clock server</a><br>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
</ul>")
\ No newline at end of file
-document.write("<ul><p>Configuration Commands and Options<br><ul>\
-<li class='inline'><a href='comdex.html'>Command Index</a><br>\
-<li class='inline'><a href='confopt.html'>Server Options</a><br>\
-<li class='inline'><a href='accopt.html'>Access Control Options</a><br>\
-<li class='inline'><a href='authopt.html'>Authentication Options</a><br>\
-<li class='inline'><a href='monopt.html'>Monitoring Options</a><br>\
-<li class='inline'><a href='clockopt.html'>Reference Clock Options</a><br>\
-<li class='inline'><a href='miscopt.html'>Miscellaneous Options</a><br>\
-<li class='inline'><a href='ntp_conf.html'>Configuration File Definition (Advanced)</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
-</ul></ul>")
\ No newline at end of file
+document.write("<p>Configuration Commands and Options</p><ul>\
+<li class='inline'><a href='accopt.html'>Access Control Commands and Options</a><br>\
+<li class='inline'><a href='authopt.html'>Authentication Commands and Options</a><br>\
+<li class='inline'><a href='miscopt.html'>Miscellaneous Commands and Options</a><br>\
+<li class='inline'><a href='monopt.html'>Monitoring Commands and Options</a><br>\
+<li class='inline'><a href='clockopt.html'>Reference Clock Commands and Options</a><br>\
+<li class='inline'><a href='confopt.html'>Server Commands and Options</a><br>\
+<li class='inline'><a href='sitemap.html'>Site Map</a>\</li>
+</ul>")
\ No newline at end of file
-document.write("<ul><p>Client and Server Configuration<br>\
-<ul>\
-<li class='inline'><a href='assoc.html'>Association Management</a><br>\
-<li class='inline'><a href='rate.html'>Rate Management and the Kiss-o'-Death Packet</a><br>\
-<li class='inline'><a href='manyopt.html'>Automatic Server Discovery</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
-</ul></ul>")
\ No newline at end of file
+document.write("<p>Client and Server Configuration</p><ul>\
+<li class='inline'><a href='assoc.html'>Association Management</a></li>\
+<li class='inline'><a href='manyopt.html'>Automatic Server Discovery</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
-document.write("<
h4>Server Commands</h4><p><ul>\
-<li class='inline'><a href='confopt.html#server'>server - configure client association</a><br>\
-<li class='inline'><a href='confopt.html#server'>peer - configure symmetric peer association</a><br>\
-<li class='inline'><a href='confopt.html#server'>broadcast - configure broadcast server association</a><br>\
-<li class='inline'><a href='confopt.html#server'>manycastclient - configure manycast client association</a><br>\
-<li class='inline'><a href='confopt.html#server'>pool - configure pool association</a><br>\
-<li class='inline'><a href='confopt.html#server'>unpeer - remove association</a><br>\
-<li class='inline'><a href='confopt.html#broadcastclient'>broadcastclient - enable broadcast client</a><br>\
-<li class='inline'><a href='confopt.html#manycastserver'>manycastserver - enable manycast server</a><br>\
-<li class='inline'><a href='confopt.html#multicastclient'>multicastclient - enable multicast client</a><br>\
-<li class='inline'><a href='comdex.html'>Command Index</a></p>\
+document.write("<
p>Server Commands and Options</p><ul>\
+<li class='inline'><a href='confopt.html#server'>server - configure client association</a></li>\
+<li class='inline'><a href='confopt.html#server'>peer - configure symmetric peer association</a></li>\
+<li class='inline'><a href='confopt.html#server'>broadcast - configure broadcast server association</a></li>\
+<li class='inline'><a href='confopt.html#server'>manycastclient - configure manycast client association</a></li>\
+<li class='inline'><a href='confopt.html#server'>pool - configure pool association</a></li>\
+<li class='inline'><a href='confopt.html#server'>unpeer - remove association</a></li>\
+<li class='inline'><a href='confopt.html#broadcastclient'>broadcastclient - enable broadcast client</a></li>\
+<li class='inline'><a href='confopt.html#manycastserver'>manycastserver - enable manycast server</a></li>\
+<li class='inline'><a href='confopt.html#multicastclient'>multicastclient - enable multicast client</a></li>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
</ul>")
\ No newline at end of file
-document.write("<ul><p>External Links<br><ul>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/book.html'>Computer Network Time Synchronization - The Network Time Protocol (book)</a><br>\
-<li class='inline'><a href='http://www.ntp.org/index.html'>NTP Public Services Project (home page)</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/ntp.html'>NTP Research Project (home page)</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/exec.html'>Executive Summary: Computer Network Time Synchronization</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/leap.html'>The NTP Timescale and Leap Seconds</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/time.html'>NTP Timestamp Calculations</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/y2k.html'>The NTP Era and Era Numbering</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/stamp.html'>Timestamp Capture Principles</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/autocfg.html'>Autonomous Configuration</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/autokey.html'>Autonomous Authentication</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/proto.html'>Autokey Protocol</a><br>\
-<li class='inline'><a href='http://www.eecis.udel.edu/~mills/ident.html'>Autokey Identity Schemes</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a><\p>\
-</ul></ul>")
\ No newline at end of file
+document.write("<p>External Links</p><ul>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/book.html'>Computer Network Time Synchronization - The Network Time Protocol (book)</a></li>\
+<li class='inline'><a href='http://www.ntp.org/index.html'>NTP Public Services Project (home page)</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/ntp.html'>NTP Research Project (home page)</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/exec.html'>Executive Summary: Computer Network Time Synchronization</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/leap.html'>The NTP Timescale and Leap Seconds</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/time.html'>NTP Timestamp Calculations</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/y2k.html'>The NTP Era and Era Numbering</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/stamp.html'>Timestamp Capture Principles</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/onwire.html'>Analysis and Simulation of the NTP On-Wire Protocols</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/proximity.html'>Time Synchroization for Space Data Links</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/autocfg.html'>Autonomous Configuration</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/autokey.html'>Autonomous Authentication</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/proto.html'>Autokey Protocol</a></li>\
+<li class='inline'><a href='http://www.eecis.udel.edu/~mills/ident.html'>Autokey Identity Schemes</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
--- /dev/null
+document.write("<p>Handbook Pages</p><ul>\
+<li class='inline'><a href='release.html'>NTP Version 4 Release Notes</a></li>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
+<li class='inline'><a href='access.html'>Access Control Support</a></li>\
+<li class='inline'><a href='assoc.html'>Association Management</a></li>\
+<li class='inline'><a href='authentic.html'>Authentication Support</a></li>\
+<li class='inline'><a href='discover.html'>Automatic Server Discovery Schemes Timekeeping</a></li>\
+<li class='inline'><a href='rate.html'>Rate Management</a></li>\
+<li class='inline'><a href='refclock.html'>Reference Clock Support</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
-document.write("<ul><p>Build and Install<br><ul>\
-<li class='inline'><a href='build.html'>Building and Installing the Distribution</a><br>\
-<li class='inline'><a href='quick.html'>Quick Start</a><br>\
-<li class='inline'><a href='release.html'>Release Notes</a><br>\
-<li class='inline'><a href='config.html'>Build Options</a><br>\
-<li class='inline'><a href='debug.html'>NTP Debugging Techniques</a><br>\
-<li class='inline'><a href='rdebug.html'>Debugging Reference Clock Drivers</a><br>\
-<li class='inline'><a href='decode.html'><tt>ntpd</tt> Event Messages and Status Words</a><br>\
-<li class='inline'><a href='msyslog.html'><tt>ntpd</tt> System Log Messages</a><br>\
-<li class='inline'><a href='bugs.html'>NTP Bug Reporting Procedures</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
-</ul></ul>")
\ No newline at end of file
+document.write("<p>Build and Install</p><ul>\
+<li class='inline'><a href='build.html'>Building and Installing the Distribution</a></li>\
+<li class='inline'><a href='config.html'>Build Options</a></li>\
+<li class='inline'><a href='rdebug.html'>Debugging Reference Clock Drivers</a></li>\
+<li class='inline'><a href='quick.html'>Quick Start</a></li>\
+<li class='inline'><a href='release.html'>NTP Version 4 Release Notes</a></li>\
+<li class='inline'><a href='debug.html'>NTP Debugging Techniques</a></li>\
+<li class='inline'><a href='bugs.html'>NTP Bug Reporting Procedures</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
-document.write("<
ul><p>Program Manual Pages<br><ul>\
-<li class='inline'><a href='ntpd.html'><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a><br>\
-<li class='inline'><a href='ntpq.html'><tt>ntpq</tt> - standard NTP query program</a><br>\
-<li class='inline'><a href='ntpdc.html'><tt>ntpdc</tt> - special NTP query program</a><br>\
-<li class='inline'><a href='ntpdate.html'><tt>ntpdate</tt> - set the date and time via NTP</a><br>\
-<li class='inline'><a href='sntp.html'><tt>sntp</tt> - Simple Network Time Protocol (SNTP) client</a><br>\
-<li class='inline'><a href='ntptrace.html'><tt>ntptrace</tt> - trace a chain of NTP servers back to the primary source</a><br>\
-<li class='inline'><a href='tickadj.html'><tt>tickadj</tt> - set time-related kernel variables</a><br>\
-<li class='inline'><a href='ntptime.html'><tt>ntptime</tt> - read and set kernel time variables</a><br>\
-<li class='inline'><a href='keygen.html'><tt>ntp-keygen</tt> - generate public and private keys</a><br>\
-<li class='inline'><a href='ntpdsim_new.html'><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
-</ul></ul>")
\ No newline at end of file
+document.write("<
p>Program Manual Pages<p><ul>\
+<li class='inline'><a href='ntpd.html'><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a></li>\
+<li class='inline'><a href='ntpq.html'><tt>ntpq</tt> - standard NTP query program</a></li>\
+<li class='inline'><a href='ntpdc.html'><tt>ntpdc</tt> - special NTP query program</a></li>\
+<li class='inline'><a href='ntpdate.html'><tt>ntpdate</tt> - set the date and time via NTP</a></li>\
+<li class='inline'><a href='sntp.html'><tt>sntp</tt> - Simple Network Time Protocol (SNTP) client</a></li>\
+<li class='inline'><a href='ntptrace.html'><tt>ntptrace</tt> - trace a chain of NTP servers back to the primary source</a></li>\
+<li class='inline'><a href='tickadj.html'><tt>tickadj</tt> - set time-related kernel variables</a></li>\
+<li class='inline'><a href='ntptime.html'><tt>ntptime</tt> - read and set kernel time variables</a></li>\
+<li class='inline'><a href='keygen.html'><tt>ntp-keygen</tt> - generate public and private keys</a></li>\
+<li class='inline'><a href='ntpdsim_new.html'><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
-document.write("<
ul><p>Miscellaneous<br><ul>\
-<li class='inline'><a href='copyright.html'>Copyright Notice</a><br>\
-<li class='inline'><a href='prefer.html'>Mitigation Rules and the <tt>prefer</tt> Keyword</a><br>\
-<li class='inline'><a href='kern.html'>Kernel Model for Precision Timekeeping</a><br>\
-<li class='inline'><a href='kernpps.html'>PPSAPI Interface for Precision Time Signals</a><br>\
-<li class='inline'><a href='pps.html'>Pulse-per-second (PPS) Signal Interfacing</a><br>\
-<li class='inline'><a href='gadget.html'>Gadget Box PPS Level Converter and CHU Modem</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
-</ul></ul>")
\ No newline at end of file
+document.write("<
p>Miscellaneous Pages</p><ul>\
+<li class='inline'><a href='copyright.html'>Copyright Notice</a></li>\
+<li class='inline'><a href='decode.html'>Event Messages and Status Words</a></li>\
+<li class='inline'><a href='kern.html'>Kernel Model for Precision Timekeeping</a></li>\
+<li class='inline'><a href='msyslog.html'><tt>ntpd</tt> System Log Messages</a></li>\
+<li class='inline'><a href='kernpps.html'>PPSAPI Interface for Precision Time Signals</a></li>\
+<li class='inline'><a href='pps.html'>Pulse-per-second (PPS) Signal Interfacing</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
-document.write("<
h4>Miscellaneous Commands</h4><p><ul>\
-<li class='inline'><a href='miscopt.html#broadcastdelay'>broadcastdelay - specify broadcast delay</a><br>\
-<li class='inline'><a href='miscopt.html#driftfile'>driftfile - specify frequency file</a><br>\
-<li class='inline'><a href='miscopt.html#enable'>enable - enable options</a><br>\
-<li class='inline'><a href='miscopt.html#enable'>disable - disable options</a><br>\
-<li class='inline'><a href='miscopt.html#includefile'>includefile - specify include file</a><br>\
-<li class='inline'><a href='miscopt.html#interface'>interface - specify which local network addresses to use</a><br>\
-<li class='inline'><a href='miscopt.html#leapfile'>leapfile - specify leapseconds file</a><br>\
-<li class='inline'><a href='miscopt.html#logconfig'>logconfig - configure log file</a><br>\
-<li class='inline'><a href='miscopt.html#interface'>nic - alias for interface</a><br>\
-<li class='inline'><a href='miscopt.html#mru'>mru - control monitor MRU list limits</a><br>\
-<li class='inline'><a href='miscopt.html#phone'>phone - specify modem phone numbers</a><br>\
-<li class='inline'><a href='miscopt.html#saveconfigdir'>saveconfigdir - specify saveconfig directory</a><br>\
-<li class='inline'><a href='miscopt.html#setvar'>setvar - set system variables</a><br>\
-<li class='inline'><a href='miscopt.html#tinker'>tinker - modify sacred system parameters (dangerous)</a><br>\
-<li class='inline'><a href='miscopt.html#tos'>tos - modify service parameters</a><br>\
-<li class='inline'><a href='miscopt.html#trap'>trap - set trap address</a><br>\
-<li class='inline'><a href='miscopt.html#ttl'>ttl - set time to live</a><br>\
-<li class='inline'><a href='comdex.html'>Command Index</a></p>\
+document.write("<
p>Miscellaneous Commands and Options</p><ul>\
+<li class='inline'><a href='miscopt.html#broadcastdelay'>broadcastdelay - specify broadcast delay</a></li>\
+<li class='inline'><a href='miscopt.html#discard'>discard - specify minimum guard time and average headway</a></li>\
+<li class='inline'><a href='miscopt.html#driftfile'>driftfile - specify frequency file</a></li>\
+<li class='inline'><a href='miscopt.html#enable'>enable - enable options</a></li>\
+<li class='inline'><a href='miscopt.html#enable'>disable - disable options</a></li>\
+<li class='inline'><a href='miscopt.html#includefile'>includefile - specify include file</a></li>\
+<li class='inline'><a href='miscopt.html#interface'>interface - specify which local network addresses to use</a></li>\
+<li class='inline'><a href='miscopt.html#leapfile'>leapfile - specify leapseconds file</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#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>\
+<li class='inline'><a href='miscopt.html#tos'>tos - modify service parameters</a></li>\
+<li class='inline'><a href='miscopt.html#trap'>trap - set trap address</a></li>\
+<li class='inline'><a href='miscopt.html#ttl'>ttl - set time to live</a></li>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
</ul>")
\ No newline at end of file
-document.write("<
h4>Monitoring Commands</h4><p><ul>\
-<li class='inline'><a href='monopt.html#filegen'>filegen - specify monitor files</a><br>\
-<li class='inline'><a href='monopt.html#statsdir'>statsdir - specify monitor files directory</a><br>\
-<li class='inline'><a href='comdex.html'>Command Index</a></p>\
+document.write("<
p>Monitoring Commands and Options</p><ul>\
+<li class='inline'><a href='monopt.html#filegen'>filegen - specify monitor files</a></li>\
+<li class='inline'><a href='monopt.html#statsdir'>statsdir - specify monitor files directory</a></li>\
+<li class='inline'><a href='comdex.html'>Command Index</a></li>\
</ul>")
\ No newline at end of file
-document.write("<
ul><p>Reference Clock Support<br><ul>\
-<li class='inline'><a href='refclock.html'>Reference Clock Drivers</a><br>\
-<li class='inline'><a href='extern.html'>External Clock Discipline and the Local Clock Driver</a><br>\
-<li class='inline'><a href='howto.html'>How to Write a Reference Clock Driver</a><br>\
-<li class='inline'><a href='howto.html'>How to build new PARSE clocks</a><br>\
-<li class='inline'><a href='sitemap.html'>Site Map</a></p>\
+document.write("<
p>Reference Clock Support</p><ul>\
+<li class='inline'><a href='extern.html'>External Clock Discipline and the Local Clock Driver</a></li>\
+<li class='inline'><a href='howto.html'>How to Write a Reference Clock Driver</a></li>\
+<li class='inline'><a href='howto.html'>How to build new PARSE clocks</a></li>\
+<li class='inline'><a href='refclock.html'>Reference Clock Drivers</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
</ul></ul>")
\ No newline at end of file
--- /dev/null
+document.write("<p>Special Topics</p><ul>\
+<li class='inline'><a href='warp.html'>How NTP Works</a></li>\
+<li class='inline'><a href='prefer.html'>Mitigation Rules and the <tt>prefer</tt> Keyword</a></li>\
+<li class='inline'><a href='autokey.html'>Autokey Public-Key Authentication</a></li>\
+<li class='inline'><a href='orphan.html'>Orphan Mode</a></li>\
+<li class='inline'><a href='xleave.html'>NTP Interleaved Modes</a></li>\
+<li class='inline'><a href='huffpuff.html'>Huff-n'-Puff Filter</a></li>\
+<li class='inline'><a href='clock.html'>Clock State Machine</a></li>\
+<li class='inline'><a href='leap.html'>Leap Second Processing</a></li>\
+<li class='inline'><a href='sitemap.html'>Site Map</a></li>\
+</ul>")
\ No newline at end of file
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>Site Map</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>Site Map</h3>
- <img src="pic/alice15.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice in Wonderland</i>, Lewis Carroll</a>
- <p>Welcome to the tea party.</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->08-Apr-2009 2:54<!-- #EndDate -->
- UTC<br clear="left">
- </p>
- <h4>Related Links</h4>
- <script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
- <script type="text/javascript" language="javascript" src="scripts/external.txt"></script>
- <hr>
- <div align="center">
- <img src="pic/tribeb.gif" alt="gif"></div>
- <br>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Site Map</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>Site Map</h3>
+<img src="pic/alice15.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice in Wonderland</i>, Lewis Carroll</a>
+<p>Welcome to the tea party.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->06-Sep-2010 20:57<!-- #EndDate -->
+ UTC<br clear="left">
+</p>
+<h4>Related Links</h4>
+<script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/manual.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/hand.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/command.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/config.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/refclock.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/audio.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/misc.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/special.txt"></script>
+<script type="text/javascript" language="javascript" src="scripts/external.txt"></script>
+<hr>
+<div align="center"> <img src="pic/tribeb.gif" alt="gif"></div>
+<br>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <title><tt>sntp</tt> - Simple Network Time Protocol (SNTP) Client</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>sntp</tt> - Simple Network Time Protocol (SNTP) Client</h3>
- <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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">16:31</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="289">Wednesday, March 12, 2008</csobj></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>
- <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>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>
- <h4>Options</h4>
- <p><tt>sntp</tt> recognizes the following options:</p>
- <dl>
- <dt><tt>-h, --help</tt>
- <dd>displays usage information.
- <dt><tt>-v</tt>
- <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.
- <dt><tt>-r</tt>
- <dd>steps the system clock to the correct time by the Unix <tt>settimeofday</tt> system call. Requires root priviledge.
- <dt><tt>-a</tt>
- <dd>slews the system clock to the correct time by the Unix <tt>adjtime</tt> system call. Requires root priviledge.
- <dt><tt>-e <i>minerr</i></tt>
- <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.
- <dt><tt>-E <i>maxerr</i></tt>
- <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.
- <dt><tt>-P <i>prompt</i></tt>
- <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.
- <dt><tt>-c <i>count</i></tt>
- <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.
- <dt><tt>-d <i>delay</i></tt>
- <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.
- </dl>
- <h4>Return Value</h4>
- <p>The program returns an exit status of zero for success 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>
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<title>sntp - Simple Network Time Protocol (SNTP) Client</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>sntp</tt> - Simple Network Time Protocol (SNTP) Client</h3>
+<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 -->
+ 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>
+<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>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>
+<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>
+</dl>
+<h4>Return Value</h4>
+<p>The program returns an exit status of zero for success 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>
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>tickadj - set time-related kernel variables</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3><tt>tickadj</tt> - set time-related kernel variables</h3>
- <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:53</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="308">Wednesday, January 16, 2008</csobj></p>
- <hr>
- <h4>Synopsis</h4>
- <tt>tickadj [ -Aqs ] [ -a <i>tickadj</i> ] [ -t <i>tick</i> ]</tt>
- <h4>Description</h4>
- <p>The <tt>tickadj</tt> program reads, and optionally modifies, several timekeeping-related variables in older kernels that do not have support for precision ttimekeeping, including HP-UX, SunOS, Ultrix, SGI and probably others. Those machines provide means to patch the kernel <tt>/dev/kmem</tt>. Newer machines with kernel time support, including Solaris, Tru64, FreeBSD and Linux, should NOT use the program, even if it appears to work, as it will destabilize the kernel time support. Use the <a href="ntptime.html"><tt>ntptime</tt></a> program instead.</p>
- <p>The particular variables that can be changed with <tt>tickadj</tt> include <tt>tick</tt>, which is the number of microseconds added to the system time for a clock interrupt, <tt>tickadj</tt>, which sets the slew rate and resolution used by the <tt>adjtime</tt> system call, and <tt>dosynctodr</tt>, which indicates to the kernels on some machines whether they should internally adjust the system clock to keep it in line with time-of-day clock or not.</p>
- <p>By default, with no arguments, <tt>tickadj</tt> reads the variables of interest in the kernel and displays them. At the same time, it determines an "optimal" value for the value of the <tt>tickadj</tt> variable if the intent is to run the <tt>ntpd</tt> Network Time Protocol (NTP) daemon, and prints this as well. Since the operation of <tt>tickadj</tt> when reading the kernel mimics the operation of similar parts of the <tt>ntpd</tt> program fairly closely, this can be useful when debugging problems with <tt>ntpd</tt>.</p>
- <p>Note that <tt>tickadj</tt> should be run with some caution when being used for the first time on different types of machines. The operations which <tt>tickadj</tt> tries to perform are not guaranteed to work on all Unix machines and may in rare cases cause the kernel to crash.</p>
- <h4>Command Line Options</h4>
- <dl>
- <dt><tt>-a <i>tickadj</i></tt>
- <dd>Set the kernel variable <tt>tickadj</tt> to the value <i><tt>tickadj</tt></i>specified.
- <dt><tt>-A</tt>
- <dd>Set the kernel variable <tt>tickadj</tt> to an internally computed "optimal" value.
- <dt><tt>-t <i>tick</i></tt>
- <dd>Set the kernel variable <tt>tick</tt> to the value <i><tt>tick</tt></i> specified.
- <dt><tt>-s</tt>
- <dd>Set the kernel variable <tt>dosynctodr</tt> to zero, which disables the hardware time-of-year clock, a prerequisite for running the <tt>ntpd</tt> daemon under SunOS 4.x.<dt><tt>-q</tt>
- <dd>Normally, <tt>tickadj</tt> is quite verbose about what it is doing. The <tt>-q</tt> flag tells it to shut up about everything except errors.
- </dl>
- <h4>Files</h4>
- <tt>/vmunix<br>
- /unix<br>
- /dev/kmem<br>
- </tt>
- <h4>Bugs</h4>
- Fiddling with kernel variables at run time as a part of ordinary operations is a hideous practice which is only necessary to make up for deficiencies in the implementation of <tt>adjtime</tt> in many kernels and/or brokenness of the system clock in some vendors' kernels. It would be much better if the kernels were fixed and the <tt>tickadj</tt> program went away.
- <hr>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>tickadj - set time-related kernel variables</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3><tt>tickadj</tt> - set time-related kernel variables</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 17:59<!-- #EndDate -->
+ UTC</p>
+<hr>
+<h4>Synopsis</h4>
+<tt>tickadj [ -Aqs ] [ -a <i>tickadj</i> ] [ -t <i>tick</i> ]</tt>
+<h4>Description</h4>
+<p>The <tt>tickadj</tt> program reads, and optionally modifies, several timekeeping-related variables in older kernels that do not have support for precision timekeeping, including HP-UX, SunOS, Ultrix, SGI and probably others. Those machines provide means to patch the kernel <tt>/dev/kmem</tt>. Newer machines with kernel time support, including Solaris, Tru64, FreeBSD and Linux, should NOT use the program, even if it appears to work, as it will destabilize the kernel time support. Use the <a href="ntptime.html"><tt>ntptime</tt></a> program instead.</p>
+<p>The particular variables that can be changed with <tt>tickadj</tt> include <tt>tick</tt>, which is the number of microseconds added to the system time for a clock interrupt, <tt>tickadj</tt>, which sets the slew rate and resolution used by the <tt>adjtime</tt> system call, and <tt>dosynctodr</tt>, which indicates to the kernels on some machines whether they should internally adjust the system clock to keep it in line with time-of-day clock or not.</p>
+<p>By default, with no arguments, <tt>tickadj</tt> reads the variables of interest in the kernel and displays them. At the same time, it determines an "optimal" value for the value of the <tt>tickadj</tt> variable if the intent is to run the <tt>ntpd</tt> Network Time Protocol (NTP) daemon, and prints this as well. Since the operation of <tt>tickadj</tt> when reading the kernel mimics the operation of similar parts of the <tt>ntpd</tt> program fairly closely, this can be useful when debugging problems with <tt>ntpd</tt>.</p>
+<p>Note that <tt>tickadj</tt> should be run with some caution when being used for the first time on different types of machines. The operations which <tt>tickadj</tt> tries to perform are not guaranteed to work on all Unix machines and may in rare cases cause the kernel to crash.</p>
+<h4>Command Line Options</h4>
+<dl>
+ <dt><tt>-a <i>tickadj</i></tt></dt>
+ <dd>Set the kernel variable <tt>tickadj</tt> to the value <i><tt>tickadj specified.</tt></i></dd>
+ <dt><tt>-A</tt></dt>
+ <dd>Set the kernel variable <tt>tickadj</tt> to an internally computed "optimal" value.</dd>
+ <dt><tt>-t <i>tick</i></tt></dt>
+ <dd>Set the kernel variable <tt>tick</tt> to the value <i><tt>tick</tt></i> specified.</dd>
+ <dt><tt>-s</tt></dt>
+ <dd>Set the kernel variable <tt>dosynctodr</tt> to zero, which disables the hardware time-of-year clock, a prerequisite for running the <tt>ntpd</tt> daemon under SunOS 4.x.</dd>
+ <dt><tt>-q</tt></dt>
+ <dd>Normally, <tt>tickadj</tt> is quite verbose about what it is doing. The <tt>-q</tt> flag tells it to shut up about everything except errors.</dd>
+</dl>
+<h4>Files</h4>
+<tt>/vmunix<br>
+/unix<br>
+/dev/kmem<br>
+</tt>
+<h4>Bugs</h4>
+Fiddling with kernel variables at run time as a part of ordinary operations is a hideous practice which is only necessary to make up for deficiencies in the implementation of <tt>adjtime</tt> in many kernels and/or brokenness of the system clock in some vendors' kernels. It would be much better if the kernels were fixed and the <tt>tickadj</tt> program went away.
+<hr>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>How NTP Works</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>How NTP Works</h3>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->
+ 08-Sep-2010 21:25
+ <!-- #EndDate -->
+ UTC</p>
+<hr>
+<div align="center">
+ <p><img src="pic/fig_3_1.gif" alt="gif"></p>
+ <p>Figure 1. NTP Host Processes and Algorithms</p>
+</div>
+<h4>NTP Host Architecture and Basic Operation</h4>
+<p>The overall organization of the NTP daemon is shown in Figure 1. It is useful in this context to consider the daemon as both a client of downstatum servers and as a server for upstratum clients. It includes a pair of peer/poll processes for each reference clock or remote server used as a synchronization source. The poll process sends NTP packets at intervals ranging from 8 s to 36 h. The peer process receives NTP packets and runs the on-wire protocol that collects four timestamps: the <em>origin timestamp</em> <em>T</em><sub>1</sub> upon departure of the client request and the <em>receive timestamp</em> <em>T</em><sub>2</sub> upon arrival at the server, the <em>transmit timestamp</em> <em>T</em><sub>3</sub> upon departure of the server reply and the <em>destination timestamp</em> <em>T</em><sub>4</sub> upon arrival at the client. These timestamps are used to calculate the clock offset and roundtrip delay:</p>
+<div align="center">
+ <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>Those sources that have passed a number of sanity checks are declared <em>selectable</em>. From the selectable population the statistics are used by the select algorithm to determine a number of <em>truechimers</em> according to correctness principles. From the truechimer population a number of <em>survivors</em> are determined on the basis of statistical principles. One of the survivors is declared the <em>system peer</em> and the system statistics inherited from it. The combine algorithm computes a weighted average of the peer offset and jitter to produce the final values used by the clock discipline algorithm to adjust the system clock time and frequency.</p>
+<p> When started, the program requires several measurements sufficient data fro these a algorithms to work properly before setting the clock. As the default poll interval is 64 s, it can take several minutes to set the clock. The time can be reduced using the <tt>iburst</tt> option on the <a href="confopt.html">Server Options</a> page. For additional details about the clock filter, select, cluster and combine algorithms see the Architecture Briefing on the NTP Project Page.</p>
+<h4>How Statistics are Determined</h4>
+<p>Each source is characterized by the offset and delay measured by the on-wire protocol and the dispersion and jitter calculated by the clock filter algorithm of the peer process. Each time an NTP packet is received from a source, the dispersion is initialized by the sum of the precisions of the server and client. The offset, delay and dispersion values are inserted as the youngest stage of an 8-stage shift register, thus discarding the oldest stage. Subsequently, the dispersion 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 clocks. The clock filter algorithm in each peer process selects the stage with the lowest delay, which generally represents the most accurate values, and the associated offset and delay values become the peer variables of the same name. The peer dispersion continues to grow at the same rate as the register dispersion. The peer dispersion is determined as a weighted average of the dispersion samples in the shift register. Finally, the peer jitter is determined as the root-mean-square (RMS) average of all the offset samples in the shift register relative to the selected sample. </p>
+<p> The clock filter algorithm continues to process packets in this way until the source is no longer reachable. In this case the algorithm inserts dummy samples with "infinite" dispersion are inserted in the shift register, thus displacing old samples.</p>
+<p>The composition of the survivor population and the system peer selection is redetermined as each update from each server is received. The system variables are copied from the peer variables of the same name and the system stratum set one greater than the system peer stratum. Like peer dispersion, the system dispersion increases at the same rate so, even if all sources have become unreachable, the daemon appears to upstratum clients at ever increasing dispersion.</p>
+<h4>Reachability and Selection Criteria</h4>
+<p>Of interest in this discussion is how an NTP client determines if a server is reachable and suitable as a source of synchronization. Reachability is determined by an 8-bit shift register, which is shifted left by one bit as each poll message is sent, with zero replacing the vacated rightmost bit. Each time an update is received the rightmost bit is set. The source is considered reachable if any bit is set in the register; otherwise, it is considered unreachable. The peer dispersion is used as a filter to determine whether a source is usable or not. If the server is unreachable or the dispersion exceeds the select threshold threshold (1.5 s by default), it is not selectable to synchronize the system clock.</p>
+<p>The quality of time service is determined by a quantity called the <em>synchronization distance.</em> It is computed as one-half the <em>root delay</em> to the primary source of time; i.e., the primary reference clock, plus the <em>root dispersion</em>. The root root delay and root dispersion are included in the NTP packet header. The client adds the current system peer delay and dispersion to the corresponding root values and saves them in its own system variables which are passed on to dependent clients. Like peer dispersion, the root dispersion increases at the same rate.</p>
+<p>Although it might seem counterintuitive, a cardinal rule in the selection processes is, once a sample has been selected by the clock filter algorithm, that sample and any older samples are no longer selectable. This applies also to the select algorithm. Once the peer variables for a source have been selected, older variables of the same or other sources are no longer selectable. This means that not every sample can be used to update the peer variables and up to seven samples can be ignored between selected samples. This fact has been carefully considered in the discipline algorithm design with due consideration of the feedback loop delay and minimum sampling rate. In engineering terms, even if only one sample in eight survives, the resulting sample rate is twice the Nyquist rate at any time constant and poll interval.</p>
+<h4>Clock Discipline Algorithm</h4>
+<p>At the heart of the NTP host is the clock discipline algorithm, which is best described as a hybrid phase/frequency-lock feedback loop. In the NTP reference implementation, it is an intricately crafted algorithm that automatically adapts for optimum performance while minimizing network overhead. Its response is determined by the <em>time constant</em>, which results in a "stiffness" depending on the jitter of the available sources and the stability of the system clock oscillator. The 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>It is important to understand how the dynamics of the discipline are affected by the poll interval. At an interval of 64 s and a step change of 100 ms, the time response crosses zero in about 50 minutes and overshoots about 7 ms, as per design. However, the step correction causes a temporary frequency change of about 5 PPM, which is slowly corrected within a few hours. The result is that the overshoot slowly subsides over the that interval. This is an intrinsic feature of a discipline loop that can minimize both time and frequency offset.</p>
+<p>Since the discipline loop is linear, the response with different step sizes and poll intervals has the characteristic, 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 characteristic, but with amplitude one-tenth that with the 100-ms step. The response scales exactly with poll interval, so at a poll interval of 8 s the time response is the same as at 64 s, but at a time scale one-eighth that at 64 s.</p>
+<p>In the NTP specification and reference implementation, poll intervals are expressed as exponents of 2; thus, a poll exponent of 6 represents an actual poll interval; of 64 s. The clock discipline time constant is also expressed in powers of 2 and, with proper scaling, the two have the same value. Thus, a change in one corresponds to the same change in the other.</p>
+<p> The optimum time constant, and thus the poll interval, depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. With a compromise Allan intercept of 2000 s, the optimum poll interval is about 64 s, which corresponds to a poll exponent of 6.</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 the clock jitter, 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, the poll exponent. if jiggle counter exceed an arbitrary threshold of 30, it is reset to zero and the poll exponent increased by 1. If the jiggle counter is less than -30, it is set to zero 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>The optimum time constant, and thus the poll exponent, depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. With a compromise Allan intercept of 2000 s, the optimum poll interval is about 64 s, which corresponds to a poll exponent of 6.</p>
+<p>Additional information about the clock discipline behavior is on the <a href="clock.html">Clock State Machine</a> page. </p>
+<hr>
+<p>
+ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</p>
+</body>
+</html>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-
<html>
-
- <head>
- <meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
- <meta name="generator" content="HTML Tidy, see www.w3.org">
- <title>NTP Interleaved Modes</title>
- <link href="scripts/style.css" type="text/css" rel="stylesheet">
- </head>
-
- <body>
- <h3>NTP Interleaved Modes </h3>
- <img src="pic/pogo4.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
- <p>You need a little magic.</p>
- <p>Last update:
- <!-- #BeginDate format:En2m -->03-May-2009 3:37<!-- #EndDate -->
- UTC</p>
+<head>
+<meta http-equiv="content-type" content="text/html;charset=iso-8859-1">
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>NTP Interleaved Modes</title>
+<link href="scripts/style.css" type="text/css" rel="stylesheet">
+</head>
+<body>
+<h3>NTP Interleaved Modes </h3>
+<img src="pic/pogo4.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
+<p>You need a little magic.</p>
+<p>Last update:
+ <!-- #BeginDate format:En2m -->04-Sep-2010 19:44<!-- #EndDate -->
+ UTC</p>
<br clear="left">
- <hr>
- <p>In the protocol described in the NTP specification and implemented today the transmit timestamp is captured before the MD5 digest is computed and the packet is sent, while the receive timestamp is captured after the packet is received. For enhanced accuracy it is desirable to capture the timestamps as close to the wire as possible; i.e., with hardware assist or with a modified driver.</p>
- <p> The problem is, while the receive timestamp could in principle be piggybacked in the receive buffer, the transmit timestamp cannot ordinarily be transmitted in the same packet. A solution for this problem is the two-step or interleaved protocol described on this page and included in the the current reference implementation. In this experimental variant the transmit timestamp for one packet is actually carried in the immediately following packet. The trick, however, is to implement the interleaved protocol without changing the NTP packet header format, without compromising backwards compatibility and without compromising the error recovery properties.</p>
- <p>Currently, the reference implementation uses only software timestamps (softstamps). The receive softstamp is captured at software interrupt time and before the buffer is queued for later processing. The reference implementation captures a softstamp before the message digest routine and another after the send-packet routine. In this design the latter timestamp can be considered most accurate, as it avoids the kernel latencies and queueing mechanisms. The difference, called the interleaved or output delay, varies from 16 <font face="symbol">m</font>s for a dual-core, 2.8 GHz Pentium 4 running FreeBSD 6.1 to 1100 <font face="symbol">m</font>s for a Sun Blade 1500 running Solaris 10.</p>
- <p>Performacne varies widely between machines and network interface cards on a 100-Mb switched Ethernet where the NTP packet is about 1000 bits or 10 <font face="symbol">m</font>s. On two identical Pentium 4 machines in symmetric mode, the measured output delay is 16 <font face="symbol">m</font>s and remaining one-way delay components 45-150 <font face="symbol">m</font>s. Two LAN segments account for 20 <font face="symbol">m</font>s, which leaves 25-130 <font face="symbol">m</font>s for input delay. On two identical UltraSPARC machines running Solaris 10 in symmetric mode, the measured output delay is 160 <font face="symbol">m</font>s and remaining one-way delay components 195 <font face="symbol">m</font>s. Two LAN segments account for 20 <font face="symbol">m</font>s, which leaves 175 ms for input delay.</p>
- <p>Performance with the Pentia show a residual jitter of about 20 <font face="symbol">m</font>s, which is by far the best performance so far. However, much better performance could result if the input delay could be reduced or elminated with driver or hardware timestamps. Should that be done, performance should be in the same order as the the PPS and kernel discipline, which is in the order of 2 <font face="symbol">m</font>s.</p>
- <p>Interleaved modes can be used only in NTP symmetric and broadcast modes.
- It is activated by the <tt>xleave</tt> option with the <tt>peer</tt> or <tt>broadcast</tt> configuration
- commands. The NTP protocol automatically reconfigures in normal or
- interleaved mode as required. Ordinary broadcast clients can use
- the same servers as interleaved broadcast clients at the same time.
- Further details are in the white paper <a href="http://www.eecis.udel.edu/~mills/onwire.html">NTP
- Interleaved On-Wire Protocol</a> and the briefing <a href="http://www.eecis.udel.edu/~mills/database/brief/onwire/onwire.ppt">Interleaved
- Synchronization Protocols for LANs and Space Data Links</a>.</p>
- <hr>
- <div align="center">
- <img src="pic/pogo1a.gif" alt="gif">
- </div>
- <br>
- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
- </body>
-
-</html>
\ No newline at end of file
+<hr>
+<p>In the protocol described in the NTP specification and reference implementation up to now, the transmit timestamp, which is captured before the message digest is computed and the packet queued for output, is properly called as a <em>softstamp</em> The receive timestamp, which is captured after the input driver interrupt routine and before the packet is queued for input, is properly called a <em>drivestamp</em>. For enhanced accuracy it is desirable to capture the transmit timestamp as close to the wire as possible; for example, after the output driver interrupt routine.</p>
+<p> In other words, we would like to replace the transmit softstamp with a drivestamp, but the problem is the transmit drivestamp is available only after the packet has been sent. A solution for this problem is the two-step or interleaved protocol described on this page and included in the the current reference implementation. In interleaved modes the transmit drivestamp for one packet is actually carried in the immediately following packet. The trick, however, is to implement the interleaved protocol without changing the NTP packet header format, without compromising backwards compatibility and without compromising the error recovery properties.</p>
+<p> The reference implementation captures a softstamp before the message digest routine and a drivestamp after the output interrupt routine. In this design the latter timestamp can be considered most accurate, as it avoids the various queuing and transmission latencies. The difference between the two timestamps, which is called the interleaved or output delay, varies from 16 <font face="symbol">m</font>s for a dual-core Pentium running FreeBSD 6.1 to 1100 <font face="symbol">m</font>s for a Sun Blade 1500 running Solaris 10.</p>
+<p>Interleaved mode can be used only in NTP symmetric and broadcast modes.
+ It is activated by the <tt>xleave</tt> option with the <tt>peer</tt> or <tt>broadcast</tt> configuration
+commands. A broadcast server configured for interleaved mode is transparent to ordinary broadcast clients, so both ordinary and interleaved broadcast clients can use the same packets. An interleaved symmetric active peer automatically switches to ordinary symmetric mode if the other peer is not capable of operation in interleaved mode. </p>
+<p>As demonstrated in the white paper <a href="http://www.eecis.udel.edu/~mills/onwire.html">Analysis and Simulation of the NTP On-Wire Protocols</a>, the interleaved modes have the same resistance to lost packets, duplicate packets, packets crossed in flight and protocol restarts as the ordinary modes. An application of the interleaved symmetric mode in space missions is presented in the white paper <a href="http://www.eecis.udel.edu/~mills/database/brief/onwire/onwire.ppt">Interleaved
+ Synchronization Protocols for LANs and Space Data Links</a>.</p>
+<hr>
+<div align="center"> <img src="pic/pogo1a.gif" alt="gif"> </div>
+<br>
+<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
+</body>
+</html>
projects / thirdparty / ntp.git / commitdiff
