diff options
author | delphij <delphij@FreeBSD.org> | 2015-07-15 19:21:26 +0000 |
---|---|---|
committer | delphij <delphij@FreeBSD.org> | 2015-07-15 19:21:26 +0000 |
commit | 2a25cee78ab1d37e7d2bc40ae675646974d99f56 (patch) | |
tree | b0302ac4be59e104f4e1e54014561a1389397192 /contrib/ntp/html | |
parent | a0741a75537b2e0514472ac3b28afc55a7846c30 (diff) | |
download | FreeBSD-src-2a25cee78ab1d37e7d2bc40ae675646974d99f56.zip FreeBSD-src-2a25cee78ab1d37e7d2bc40ae675646974d99f56.tar.gz |
MFC r280849,280915-280916,281015-281016,282097,282408,282415,283542,
284864,285169-285170,285435:
ntp 4.2.8p3.
Relnotes: yes
Approved by: re (?)
Diffstat (limited to 'contrib/ntp/html')
259 files changed, 10427 insertions, 6484 deletions
diff --git a/contrib/ntp/html/access.html b/contrib/ntp/html/access.html new file mode 100644 index 0000000..3489f8f --- /dev/null +++ b/contrib/ntp/html/access.html @@ -0,0 +1,50 @@ +<!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 -->11-Sep-2010 05:53<!-- #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> diff --git a/contrib/ntp/html/accopt.html b/contrib/ntp/html/accopt.html index be8a5bb..6caff48 100644 --- a/contrib/ntp/html/accopt.html +++ b/contrib/ntp/html/accopt.html @@ -1,73 +1,91 @@ <!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> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Access Control 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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:35</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#acx">Access Control Support</a> - <li class="inline"><a href="#kiss">The Kiss-of-Death Packet</a> - <li class="inline"><a href="#cmd">Access Control Commands</a> - </ul> - <hr> - <h4 id="acx">Access Control Support</h4> - The<tt> ntpd</tt> daemon implements a general purpose address/mask based restriction list. The list contains address/match entries sorted first by increasing address values and 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. Additional information and examples can be found in the <a href="notes.html">Notes on Configuring NTP and Setting up a NTP Subnet</a> page. - <p>The restriction facility was implemented in conformance with the access policies for the original NSFnet backbone time servers. Later the facility was expanded to deflect cryptographic and clogging attacks. While this facility may be useful for keeping unwanted or 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>Clients can be denied service because they are explicitly included in the restrict list created by the <tt>restrict</tt> command or implicitly as the result of cryptographic or rate limit violations. Cryptographic violations include certificate or identity verification failure; rate limit violations generally result from defective NTP implementations that send packets at abusive rates. Some violations cause denied service only for the offending packet, others cause denied service for a timed period and others cause the denied service for an indefinate period. When a client or network is denied access for an indefinate period, the only way at present to remove the restrictions is by restarting the server.</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, such as a server message that explicitly requests the client to stop sending and leave a message for the system operator. A special packet format has been created for this purpose called the "kiss-o'-death" (KoD) packet. KoD packets have the leap bits set unsynchronized and stratum set to zero and the reference identifier field set to a four-byte ASCII code. If the <tt>noserve</tt> or <tt>notrust</tt> flag of the matching restrict list entry is set, the code is "DENY"; if the <tt>limited</tt> flag is set and the rate limit is exceeded, the code is "RATE". Finally, if a cryptographic violation occurs, the code is "CRYP".</p> - <p>A client receiving a KoD performs a set of sanity checks to minimize security exposure, then updates the stratum and reference identifier peer variables, sets the access denied (TEST4) bit in the peer flash variable and sends a message to the log. As long as the TEST4 bit is set, the client will send no further packets to the server. The only way at present to recover from this condition is to restart the protocol at both the client and server. This happens automatically at the client when the association times out. It will happen at the server only if the server operator cooperates.</p> - <h4 id="cmd">Access Control Commands</h4> - <dl> - <dt><tt>discard [ average <i>avg</i> ][ minimum <i>min</i> ] [ monitor <i>prob</i> ]</tt> - <dd>Set the parameters of the <tt>limited</tt> facility which protects the server from client abuse. The <tt>average</tt> subcommand specifies the minimum average packet spacing, while the <tt>minimum</tt> subcommand specifies the minimum packet spacing. Packets that violate these minima are discarded and a kiss-o'-death packet returned if enabled. The default minimum average and minimum are 5 and 2, respectively. The monitor subcommand specifies the probability of discard for packets that overflow the rate-control window. - <dt><tt>restrict <i>address</i> [mask <i>mask</i>] [<i>flag</i>][...]</tt> - <dd>The <i><tt>address</tt></i> 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 <i><tt>mask</tt></i> argument expressed in dotted-quad form defaults to <tt>255.255.255.255</tt>, meaning that the <i><tt>address</tt></i> is treated as the address of an individual host. A default entry (address <tt>0.0.0.0</tt>, mask <tt>0.0.0.0</tt>) is always included and is always the first entry in the list. Note that text string <tt>default</tt>, with no mask option, may be used to indicate the default entry. - <dd>In the current implementation, <i><tt>flag</tt></i> always restricts access, i.e., an entry with no flags indicates that free access to the server is to be given. The flags are not orthogonal, in that more restrictive flags will often make less restrictive ones redundant. The flags can generally be classed into two catagories, those which restrict time service and those which restrict informational queries and attempts to do run-time reconfiguration of the server. One or more of the following flags may be specified: - <dl> - <dt><tt>ignore</tt> - <dd>Deny packets of all kinds, including <tt>ntpq</tt> and <tt>ntpdc</tt> queries. - <dt><tt>kod</tt> - <dd>If this flag is set when an access violation occurs, a kiss-o'-death (KoD) packet is sent. KoD packets are rate limited to no more than one per second. If another KoD packet occurs within one second after the last one, the packet is dropped - <dt><tt>limited</tt> - <dd>Deny service if the packet spacing violates the lower limits specified in the <tt>discard</tt> command. A history of clients is kept using the monitoring capability of <tt>ntpd</tt>. Thus, monitoring is always active as long as there is a restriction entry with the <tt>limited</tt> flag. - <dt><tt>lowpriotrap</tt> - <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. - <dt><tt>nomodify</tt> - <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. - <dt><tt>noquery</tt> - <dd>Deny <tt>ntpq</tt> and <tt>ntpdc</tt> queries. Time service is not affected. - <dt><tt>nopeer</tt> - <dd>Deny packets which would result in mobilizing a new association. This includes broadcast, symmetric-active and manycast client packets when a configured association does not exist. - <dt><tt>noserve</tt> - <dd>Deny all packets except <tt>ntpq</tt> and <tt>ntpdc</tt> queries. - <dt><tt>notrap</tt> - <dd>Decline to provide mode 6 control message trap service to matching hosts. The trap service is a subsystem of the <tt>ntpdq</tt> control message protocol which is intended for use by remote event logging programs. - <dt><tt>notrust</tt> - <dd>Deny packets unless the packet is cryptographically authenticated. - <dt><tt>ntpport</tt> - <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). Both <tt>ntpport</tt> and <tt>non-ntpport</tt> may be specified. The <tt>ntpport</tt> is considered more specific and is sorted later in the list. - <dt><tt>version</tt> - <dd>Deny packets that do not match the current NTP version. - </dl> - <dd>Default restriction list entries with the flags <tt>ignore, interface, 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). - </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>Access Control Commands and Options</title> +<!-- Changed by: Harlan &, 13-Nov-2014 --> +<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 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 -->13-Nov-2014 03:00<!-- #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> +<hr> +<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. 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 2.</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"><b>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.</b></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. It also includes <tt>pool</tt> associations, so if you want to use servers from a <tt>pool</tt> directive and also want to use <tt>nopeer</tt> by default, you'll want a <tt>"restrict source ..."</tt> line as well that does <i>not</i> include the <tt>nopeer</tt> directive. 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> +</dl> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/assoc.html b/contrib/ntp/html/assoc.html index 0ca1426..8dc0b1b 100644 --- a/contrib/ntp/html/assoc.html +++ b/contrib/ntp/html/assoc.html @@ -1,59 +1,81 @@ <!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> - - <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">18:35</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.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="#umlt">Multicasting</a> - <li class="inline"><a href="#umlt">Multicasting</a> - <li class="inline"><a href="#burst">Burst Modes</a> - </ul> - <hr> - <h4 id="modes">Association Modes</h4> - <p>NTP Version 4 (NTPv4) incorporates new features and refinements to the NTP Version 3 (NTPv3) algorithms; however, it continues the tradition of backwards compatibility with older versions. A number of new operating modes for automatic server discovery and improved accuracy in occasionally connected networks are provided. Following is an overview of the new features; additional information is available on the <a href="confopt.html">Configuration Options</a> and <a href="authopt.html">Authentication Options</a> pages and in the papers, reports, memoranda and briefings at <a href="http://www.ntp.org">www.ntp.org</a>.</p> - <p>There are two types of associations: persistent associations, which result from configuration file commands, and ephemeral associations, which result from protocol operations described below. A persistent association is never demobilized, although it may become dormant when the associated server becomes unreachable. An ephemeral association is mobilized when a message arrives from a server; for instance, a symmetric passive association is mobilized upon arrival of a symmetric active message. A broadcast client association is mobilized upon arrival of a broadcast server message, while a Manycast client association is mobilized upon arrival of a Manycast server message.</p> - <p>Ordinarily, successful mobilization of an ephemeral association requires the server to be cryptographically authenticated to the dependent client. This can be done using either symmetric-key or public-key cryptography, as described in the <a href="authopt.html">Authentication Options</a> page. The cryptographic means insure an unbroken chain of trust between the dependent client and the primary servers at the root of the synchronization subnet. We call this chain the <i>provenance</i> of the client and define new vocabulary as to proventicate a client or provide proventic credentials. Once mobilized, ephemeral associations are demobilized when either (a) the server becomes unreachable or (b) the server refreshes the key media without notifying the client.</p> - <p>There are three principal modes of operation: client/server, symmetric active/passive and broadcast. In addition, there are two modes using IP multicast support: multicast and manycast. These modes are selected based on the scope of service, intended flow of time and proventic values and means of configuration. Following is a summary of the operations in each mode.</p> - <h4 id="client">Client/Server Mode</h4> - <p>Client/server mode is probably the most common configuration in the Internet today. It operates in the classic remote-procedure-call (RPC) paradigm with stateless servers. In this mode a client sends a request to the server and expects a reply at some future time. In some contexts this would be described as a "pull" operation, in that the client pulls the time and proventic values from the server. A client is configured in client mode using the <tt>server</tt> (sic) command and specifying the server IPv4 or IPv6 DNS name or address; the server requires no prior configuration. The original NTPv3 authentication scheme is applicable in this mode, as well as the new NTPv4 Autokey proventication scheme. In addition, two burst modes described below can be used in appropriate cases.</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 subset of secondary servers known to be reliable and proventicated. Should one of the peers lose all reference sources or simply cease operation, the other peers will automatically reconfigure so that time and proventication values can flow from the surviving peers to all the others in the clique. In some contexts this would be described as a "push-pull" operation, in that the peer either pulls or pushes the time and proventic values depending on the particular configuration.</p> - <p>Symmetric peers operate with their sources in some NTP mode and with each other in symmetric mode. A peer is configured in symmetric active mode using the <tt>peer</tt> command and specifying the other peer IPv4 or IPv6 DNS name or address. The other peer can also be configured in symmetric active mode in a similar way. However, if the other peer is not specifically configured in this way, a symmetric passive association is mobilized upon arrival of a symmetric active message. Since an intruder can impersonate a symmetric active peer and inject false time values, symmetric mode should always be cryptographically validated. The original NTPv3 authentication scheme is applicable in this mode, as well as the new NTPv4 Autokey proventication scheme.</p> - <h4 id="broad">Broadcast/Multicast Modes</h4> - <p>IPv4 broadcast mode in both NTPv3 and NTPv4 is limited to directly connected subnets such as Ethernets which support broadcast technology. Ordinarily, this technology does not operate beyond the first hop router or gateway. In IPv6 and where service is intended beyond the local subnet, IP multicasting can be used where supported by the operating system and the routers support the Internet Group Management Protocol (IGMP). Most current kernels and available routers do support IP multicast technology, although service providers are sometimes reluctant to deploy it.</p> - <p>IPv4 broadcast mode is intended for configurations involving one or a few servers and a possibly very large client population on the same subnet. A broadcast server is configured using the <tt>broadcast</tt> command and a IPv4 local subnet broadcast address. A broadcast client is configured using the <tt>broadcastclient</tt> command, in which case it responds to broadcast messages received on any interface. Since an intruder can impersonate a broadcast server and inject false time values, this mode should always be cryptographically validated. The original NTPv3 authentication scheme is applicable in this mode, as well as the new NTPv4 Autokey proventication scheme.</p> - <p>The server generates broadcast messages continuously at intervals specified by the <tt>minpoll</tt> keyword and with a time-to-live span specified by the <tt>ttl</tt> keyword. A broadcast client responds to the first message received by waiting a short interval to avoid implosion at the server. Then, the client polls the server in burst mode in order to quickly set the host clock and validate the source. This normally results in a volley of eight client/server cycles at 2-s intervals during which both the synchronization and cryptographic protocols run concurrently. Following the volley, the client computes the offset between the apparent broadcast time and the (unicast) client time. This offset is used to compensate for the propagation time between the broadcast server and client. Once the offset is computed, the server continues as before and the client sends no further messages. If for some reason the broadcast server does not respond to client messages, the client will time out the volley and continue in listen-only mode with a default propagation delay.</p> - <h4 id="umlt">Multicasting</h4> - <p>Multicasting can be used to extend the scope of a timekeeping subnet in two ways: multicasting and manycasting. A general discussion of IP multicast technology is beyond the scope of this page. In simple terms a host or router sending to a IPv4 or IPv6 multicast group address expects all hosts or routers listening on this address to receive the message. There is no intrinsic limit on the number of senders or receivers and senders can be receivers and vice versa. The IANA has assigned multicast group address IPv4 224.0.1.1 and IPv6 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 with a multicast group address instead of a broadcast address. A multicast client is configured using the <tt>multicastclient</tt> command with a multicast group address. However, there is a subtle difference between IPv4 broadcasting and multicasting. IPv4 broadcasting is specific to each interface and local subnet address. If more than one interface is attached to a machine, a separate <tt>broadcast</tt> command applies to each one separately. This provides a way to limit exposure in a firewall, for example. For IPv6 the same distinction can be made using link-local prefix FF02 for each interface and site-local FF05 for all interfacesl.</p> - <p>IP multicasting is a different paradigm. By design, multicast messages travel from the sender via a shortest-path or shared tree to the receivers, which may require these messages emit from one or all interfaces, but carry a common source address. However, it is possible to configure multiple multicast group addresses using multiple <tt>broadcast</tt> or <tt>multicastclient</tt> commands. Other than these particulars, multicast messages are processed just like broadcast messages. Note that the calibration feature in broadcast mode is extremely important, since IP multicast messages can travel far different paths through the IP routing fabric than ordinary IP unicast messages.</p> - <h4 id="many">Manycasting</h4> - <p>Manycasting 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 client associations with some number of the "best" of the nearby anycast 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="burst">Burst Modes</h4> - <p>There are two burst modes where a single poll event triggers a burst of eight packets at 2-s intervals instead of the usual one. The <tt>burst</tt> mode sends a burst when the server is reachable, while the <tt>iburst</tt> mode sends a burst when the server is unreachable. Each mode is independently of the other and both can be used if necessary. The <tt>calldelay</tt> command can be used to increase the interval between the first and second packets in the burst in order to allow a modem to complete a call. 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 sets the system clock in the usual manner, as if only a single client/server cycle had occurred. The result is not only a rapid and reliable setting of the system clock, but a considerable reduction in network jitter.</p> - <p>The <tt>iburst</tt> keyword is used where it is important to set the clock quickly when an association is first mobilized or first becomes reachable or when the network attachment requires an initial calling or training procedure. The burst is initiated only when the server first becomes reachable and results in good accuracy with intermittent connections typical of PPP and ISDN services. Outlyers due to initial dial-up delays, etc., are avoided and the client sets the clock within a few seconds after the first message.</p> - <p>The <tt>burst</tt> keyword can be configured in cases of excessive network jitter or when the network attachment requires an initial calling or training procedure. The burst is initiated at each poll interval when the server is reachable. The burst does produce additional network overhead and can cause trouble if used indiscriminately. It should only be used where the poll interval is expected to settle to values at or above 1024 s.</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>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: + <!-- #BeginDate format:En2m -->31-Jan-2014 06:54<!-- #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 Management</a></li> + <li class="inline"><a href="#burst">Burst Options</a></li> +</ul> +<hr> +<h4 id="modes">Association Modes</h4> +<p>This page describes the various modes of operation provided in NTPv4. There are three types of associations in NTP: <em>persistent</em>, <em>preemptable</em> and <em>ephemeral</em>. Persistent associations are mobilized by a configuration command and never demobilized. Preemptable associations, which are new to NTPv4, are mobilized by a configuration command which includes the <tt>preempt</tt> option or upon arrival of an automatic server discovery packet. They are are demobilized by timeout or when preempted by a "better" server, as described on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. Ephemeral associations are mobilized upon arrival of broadcast or multicast server packets and demobilized by timeout.</p> +<p>Ordinarily, successful mobilization of ephemeral associations requires the server to be cryptographically authenticated to the client. This can be done using either symmetric key or Autokey public key cryptography, as described on the <a href="authentic.html">Authentication Support</a> page.</p> +<p>There are three principal modes of operation in NTP: client/server, symmetric active/passive and broadcast/multicast. There are three automatic server discovery schemes in NTP: broadcast/multicast, manycast and pool described on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. In addition, the <a href="#burst">burst options</a> and <a href="orphan.html">orphan mode</a> can be used in appropriate cases.</p> +<p>Following is a summary of the operations in each mode. Note that reference to option applies to the commands described on the <a href="confopt.html">Server Commands and Options</a> page. See that page for applicability and defaults.</p> +<h4 id="client">Client/Server Mode</h4> +<p>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 where 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="discover.html">Automatic NTP Configuration Options</a> page.</p> +<p>A server is configured to send broadcast or multicast messages using the <tt>broadcast</tt> command and specifying the subnet address for broadcast or the multicast group address for multicast. A broadcast client is enabled using the <a href="confopt.html#broadcastclient"><tt>broadcastclient</tt></a> command, while a multicast client is enabled using the <a href="confopt.html#multicastclient"><tt>multicastclient</tt></a> command and specifying the multicast group address. Multiple commands of either type can be used. However, the association is not mobilized until the first broadcast or multicast message is actually received.</p> +<h4 id="many">Manycast and Pool Modes</h4> +<p>Manycast and pool modes are automatic discovery and configuration paradigms new to NTPv4. They are intended as a means for a client to troll the nearby network neighborhood to find cooperating willing servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. The intended result is that each client mobilizes ephemeral client associations with some number of the "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="poll">Poll Interval Management</h4> +<p>NTP uses an intricate heuristic algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network overhead. The algorithm measures the incidental offset and jitter to determine the best poll interval. When <tt>ntpd</tt> starts, the interval is the default minimum 64 s. Under normal conditions when the clock discipline has stabilized, the interval increases in steps to the default maximum 1024 s. In addition, should a server become unreachable after some time, the interval increases in steps to the maximum in order to reduce network overhead. Additional information about the algorithm is on the <a href="poll.html">Poll Program</a> page.</p> +<p>The default poll interval range is suitable for most conditions, but can be changed using options on the <a href="confopt.html">Server Commands and Options</a> and <a href="miscopt.html">Miscellaneous Options</a> pages. However, when using maximum intervals much larger than the default, the residual clock frequency error must be small enough for the discipline loop to capture and correct. The capture range is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM.</p> +<p>In the NTPv4 specification and reference implementation, the poll interval is expressed in log<sub>2</sub> units, properly called the <em>poll exponent.</em> It is constrained by the lower limit <tt>minpoll</tt> and upper limit <tt>maxpoll</tt> options of the <a href="confopt.html"><tt>server</tt></a> command. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases.</p> +<p>As a rule of thumb, the expected errors increase by a factor of two as the poll interval increases by a factor of four. The poll interval algorithm slowly increases the poll interval when jitter dominates the error budget, but quickly reduces the interval when wander dominates it. More information about this algorithm is on the <a href="warp.html">How NTP Works</a> page.</p> +<p>There is normally no need to change the poll limits, as the poll interval is managed automatically as a function of prevailing jitter and wander. The most common exceptions are the following.</p> +<ul> + <li>With fast, lightly loaded LANs and modern processors, the nominal Allan intercept is about 500 s. In these cases the expected errors can be further reduced using a poll exponent of 4 (16 s). In the case of the pulse-per-second (PPS) driver, this is the recommended value.</li> + <li>With symmetric modes the most stable behavior results when both peers are configured in symmetric active mode with matching poll intervals of 6 (64 s).</li> + <li>The poll interval should not be modified for reference clocks, with the single exception the ACTS telephone modem driver. In this case the recommended minimum and maximum intervals are 12 (1.1 hr) and 17 (36 hr), respectively.</li> +</ul> +<h4 id="burst">Burst Options</h4> +<p>Occasionally it is necessary to send packets temporarily at intervals less than the poll interval. For instance, with the <tt>burst</tt> and <tt>iburst</tt> options of the <a href="confopt.html"><tt>server</tt></a> command, the poll program sends a burst of several packets at 2-s intervals. In either case the poll program avoids sending needless packets if the server is not responding. The client begins a burst with a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before beginning backoff. The result is to minimize network load if the server is not responding. Additional details are on the <a href="poll.html">Poll Program</a> page.</p> +<p>There are two burst options where a single poll event triggers a burst. They should be used only with the <tt>server</tt> and <tt>pool</tt> commands, but not with reference clock drivers nor symmetric mode peers. In both modes, received server packets update the clock filter, which selects the best (most accurate) time values. When the last packet in the burst is sent, the next received packet updates the system variables and adjusts the system clock as if only a single packet exchange had occurred.</p> +<p>The <tt>iburst</tt> option is useful where the system clock must be set quickly or when the network attachment requires an initial calling or training sequence, as in PPP or ISDN services. In general, this option is recommended for <tt>server</tt> and <tt>pool</tt> commands. A burst is sent only when the server is unreachable; in particular, when first starting up. Ordinarily, the clock is set within a few seconds after the first received packet. See the <a href="clock.html">Clock State Machine</a> page for further details about the startup behavior.</p> +<p>The <tt>burst</tt> option is useful in cases of severe network + jitter or when the network attachment requires an initial calling or training + sequence. This option is recommended when the minimum poll exponent is larger than 10 (1024 s). A burst is sent only when the server is reachable. The number of packets in the burst is determined by the poll interval + so that the average interval between packets (headway) is no less than the minimum poll interval for the association.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/audio.html b/contrib/ntp/html/audio.html index 9cea273..908cac8 100644 --- a/contrib/ntp/html/audio.html +++ b/contrib/ntp/html/audio.html @@ -1,148 +1,180 @@ <!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">18:36</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links8.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, modelled 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 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 radio drivers. The largest error observed so far is about 60 PPM, but it is possible some sound cards or codecs may exceed that value.</p> - <p>The drivers include provisions to select the input port and to monitor the input signal. The <tt>fudge flag 2</tt> 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> 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 nightime 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 should peak in the first couple of years beginning the century. - </ul> - <p>The best way to choose a frequency is to listen at various times over the day and determine the best highest (daytime) and lowest (nighttime) frequencies. Then, assuming one is available, choose the highest frequency between these frequencies. This strategy assumes that the high frequency is more problematic than the low, that the low frequency probably comes with severe multipath and static, and insures that probably twice a day the chosen frequency will work. For instance, on the east coast the best compromise CHU frequency is probably 7335 kHz and the best WWV frequency is probably 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>R71</td> - <td>0x1A</td> - <td>26</td> - </tr> - <tr> - <td>735</td> - <td>0x04</td> - <td>4</td> - <td>R72</td> - <td>0x32</td> - <td>50</td> - </tr> - <tr> - <td>746</td> - <td>0x66</td> - <td>102</td> - <td>R75</td> - <td>0x5a</td> - <td>90</td> - </tr> - <tr> - <td>751</td> - <td>0x1c</td> - <td>28</td> - <td>R7000</td> - <td>0x08</td> - <td>8</td> - </tr> - <tr> - <td>756PROII</td> - <td>0x64</td> - <td>100</td> - <td>R7100</td> - <td>0x34</td> - <td>52</td> - </tr> - <tr> - <td>761</td> - <td>0x1e</td> - <td>30</td> - <td>R8500</td> - <td>0x4a</td> - <td>74</td> - </tr> - <tr> - <td>765</td> - <td>0x2c</td> - <td>44</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 line level signal not affected by the volume control. These signals can be connected to the line-in port on the computer. If the level is too low, connect to the microphone-in port instead. 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 an attenuator must be used to reduce the signal level below the overload point.</p> - <p>It is very easy to underdrive 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 hum and interference. This feature is not intended for regular use, since it does increase the processor load on the system. Note that the speaker 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 -->11-Sep-2010 05:55<!-- #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> diff --git a/contrib/ntp/html/authentic.html b/contrib/ntp/html/authentic.html new file mode 100644 index 0000000..ecfb466 --- /dev/null +++ b/contrib/ntp/html/authentic.html @@ -0,0 +1,65 @@ +<!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; +} +.style1 {color: #FF0000} +--> +</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 -->1-Dec-2012 04:44<!-- #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="#windows">Microsoft Windows Authentication</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. A detailed discussion of the NTP multi-layer security model and vulnerability analysis is in the white paper <a href="http://www.eecis.udel.edu/~mills/security.html">NTP Security Analysis</a>.</p> +<p> The NTPv3 specification (RFC-1305) defined an authentication scheme properly described as <em>symmetric key cryptography</em>. It used 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 message digest as the server. The MD5 message digest algorithm is included in the distribution, so without further cryptographic support, the distribution can be freely exported.</p> +<p>If the OpenSSL cryptographic library is installed prior to building the distribution, all message digest algorithms included in the library may be used, including SHA and SHA1. However, if conformance to FIPS 140-2 is required, only a limited subset of these algorithms can be used. 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>In addition to the symmetric key algorithms, this distribution includes support for the Autokey public key algorithms and protocol specified in RFC-5906 "Network Time Protocol Version 4: Autokey Specification". This support is available only if the OpenSSL library has been installed and the <tt>--enable-autokey</tt> option is used when the distribution is built.</p> +<p> 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, the OpenSSL application program, or the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program in the NTP software distribution.</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. 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> +<p>By default, the client sends non-authenticated packets and the server responds with non-authenticated packets. If the client sends authenticated packets, the server responds with authenticated packets if correct, or a crypto-NAK packet if not.. In the case of unsolicited packets which might consume significant resources, such as broadcast or symmetric mode packets, , authentication is required, unless overridden by a <tt>disable auth</tt> command. In the current climate of targeted broadcast or "letterbomb" attacks, defeating this requirement would be decidedly dangerous. In any case, the <tt>notrust </tt>flag, described on the <a href="authopt.html">Access Control Options</a> page, can be used to disable access to all but correctly authenticated clients..</p> +<h4 id="symm">Symmetric Key Cryptography</h4> +<p>The original NTPv3 specification (RFC-1305), as well as the current NTPv4 specification (RFC-5905), allows any one of possibly 65,534 message digest 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 ID, key type and key to authenticate NTP packets.</p> +<p>The message digest is a cryptographic hash computed by an algorithm such as MD5 or SHA. When authentication is specified, a message authentication code (MAC) is appended to the NTP packet header. The MAC consists of a 32-bit key identifier (key ID) followed by a 128- or 160-bit message digest. The algorithm computes the digest as the hash of a 128- or 160- bit message digest key concatenated with the NTP packet header fields with the exception of the MAC. On transmit, the message digest is computed and inserted in the MAC. On receive, the message digest is computed and compared with the MAC. The packet is accepted only if the two MACs are identical. If a discrepancy is found by the client, the client ignores the packet, but raises an alarm. If this happens at the server, the server returns a special message called a <em>crypto-NAK</em>. Since the crypto-NAK is protected by the loopback test, an intruder cannot disrupt the protocol by sending a bogus crypto-NAK.</p> +<p>Keys and related information are specified in a keys file, 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.</p> +<p> Each line of the keys file consists of three fields: a key ID in the range 1 to 65,534, inclusive, a key type, and a message digest key consisting of a printable ASCII string less than 40 characters, or a 40-character hex digit string. If the OpenSSL library is installed, the key type can be any message digest algorithm supported by the library. If the OpenSSL library is not installed, the only permitted key type is MD5.</p> +<div align="center"> + <p><img src="pic/sx5.gif" alt="gif"></p> + <p>Figure 1. Typical Symmetric Key File</p> +</div> +<p>Figure 1 shows a typical keys file used by the reference implementation when the OpenSSL library is installed. In this figure, for key IDs in he range 1-10, the key is interpreted as a printable ASCII string. For key IDs in the range 11-20, the key is a 40-character hex digit string. The key is truncated or zero-filled internally to either 128 or 160 bits, depending on the key type. The line can be edited later or new lines can be added to change any field. The key can be change to a password, such as <tt>2late4Me</tt> for key ID 10. Note that two or more keys files can be combined in any order as long as the key IDs are distinct.</p> +<p>When <tt>ntpd</tt> is started, it reads the keys 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>ntpq</tt> or <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> +<h4 id="windows">Microsoft Windows Authentication</h4> +<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="accopt.html#restrict">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> diff --git a/contrib/ntp/html/authopt.html b/contrib/ntp/html/authopt.html index 5f67b3c..9504deb 100644 --- a/contrib/ntp/html/authopt.html +++ b/contrib/ntp/html/authopt.html @@ -1,155 +1,95 @@ <!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> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Authentication 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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">01:29</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="338">Wednesday, September 13, 2006</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links9.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#auth">Authentication Support</a> - <li class="inline"><a href="#symm">Symmetric Key Cryptography</a> - <li class="inline"><a href="#pub">Public Key Cryptography</a> - <li class="inline"><a href="#cfg">Configuration</a> - <li class="inline"><a href="#inter">Operation</a> - <li class="inline"><a href="#key">Key Management</a> - <li class="inline"><a href="#cmd">Authentication Commands</a> - <li class="inline"><a href="#err">Error Codes</a> - <li class="inline"><a href="#file">Files</a> - </ul> - <hr> - <h4 id="auth">Authentication Support</h4> - <p>Authentication support allows the NTP client to verify that the server is in fact known and trusted and not an intruder intending accidentally or on purpose to masquerade as that server. The NTPv3 specification RFC-1305 defines a scheme which provides cryptographic authentication of received NTP packets. Originally, this was done using the Data Encryption Standard (DES) algorithm operating in Cipher Block Chaining (CBC) mode, commonly called DES-CBC. Subsequently, this was replaced by the RSA Message Digest 5 (MD5) algorithm using a private key, commonly called keyed-MD5. Either algorithm computes a message digest, or one-way hash, which can be used to verify the server has the correct private key and key identifier.</p> - <p>NTPv4 retains the NTPv3 scheme, properly described as symmetric key cryptography, and, in addition, provides a new Autokey scheme based on public key cryptography. Public key cryptography is generally considered more secure than symmetric key cryptography, since the security is based on a private value which is generated by each host and never revealed. With the exception of the group key described later, all key distribution and management functions involve only public values, which considerably simplifies key distribution and storage. Public key management is based on X.509 certificates, which can be provided by commercial services or produced by utility programs in the OpenSSL software library or the NTPv4 distribution.</p> - <p>While the algorithms for symmetric key cryptography are included in the NTPv4 distribution, public key cryptography 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/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>Authentication is configured separately for each association using the <tt>key</tt> or <tt>autokey</tt> subcommand on the <tt>peer</tt>, <tt>server</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> configuration commands as described in the <a href="confopt.html">Configuration Options</a> page. The authentication options described below specify the locations of the key files, if other than default, which symmetric keys are trusted and the interval between various operations, if other than default.</p> - <p>Authentication is always enabled, although ineffective if not configured as described below. If a NTP packet arrives including a message authentication code (MAC), it is accepted only if it passes all cryptographic checks. The checks require correct key ID, key value and message digest. If the packet has been modified in any way or replayed by an intruder, it will fail one or more of these checks and be discarded. Furthermore, the Autokey scheme requires a preliminary protocol exchange to obtain the server certificate, verify its credentials and initialize the protocol</p> - <p>The <tt>auth</tt> flag controls whether new associations or remote configuration commands require cryptographic authentication. This flag can be set or reset by the <tt>enable</tt> and <tt>disable</tt> commands and also by remote configuration commands sent by a <tt>ntpdc</tt> program running on another machine. If this flag is enabled, which is the default case, new broadcast/manycast client and symmetric passive associations and remote configuration commands must be cryptographically authenticated using either symmetric key or public key cryptography. If this flag is disabled, these operations are effective even if not cryptographic authenticated. It should be understood that operating with the <tt>auth</tt> flag disabled invites a significant vulnerability where a rogue hacker can masquerade as a truechimer and seriously disrupt system timekeeping. It is important to note that this flag has no purpose other than to allow or disallow a new association in response to new broadcast and symmetric active messages and remote configuration commands and, in particular, the flag has no effect on the authentication process itself.</p> - <p>The security model and protocol schemes for both symmetric key and public key cryptography are summarized below; 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> - - The original RFC-1305 specification allows any one of possibly 65,534 keys, each distinguished by a 32-bit key identifier, to authenticate an association. The servers and clients involved must agree on the key and key identifier to authenticate NTP packets. Keys and related information are specified in a key 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. - <p>When <tt>ntpd</tt> is first started, it reads the key file specified in the <tt>keys</tt> configuration command and installs the keys in the key cache. However, individual keys must be activated with the <tt>trustedkey</tt> command before use. This allows, for instance, the installation of possibly several batches of keys and then activating or deactivating each batch remotely using <tt>ntpdc</tt>. This also provides a revocation capability that can be used if a key becomes compromised. The <tt>requestkey</tt> command selects the key used as the password for the <tt>ntpdc</tt> utility, while the <tt>controlkey</tt> command selects the key used as the password for the <tt>ntpq</tt> utility.</p> - <h4 id="pub">Public Key Cryptography</h4> - <p>NTPv4 supports the original NTPv3 symmetric key scheme described in RFC-1305 and in addition the Autokey 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 with digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/%7emills/ident.html">Identity Schemes</a> page and based on cryptographic challenge/response algorithms are also available. Using these schemes provides strong security against replay with or without modification, spoofing, masquerade and most forms of clogging attacks.</p> - <p>The Autokey protocol has several modes of operation corresponding to the various NTP modes supported. Most modes use a special cookie which can be computed independently by the client and server, but encrypted in transmission. All modes use in addition a variant of the S-KEY scheme, in which a pseudo-random key list is generated and used in reverse order. 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/%7emills/autokey.html">Autonomous Authentication</a> page.</p> - <p>The specific cryptographic environment used by Autokey servers and clients is determined by a set of files and soft links generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> program. This includes a required host key file, required host certificate file and optional sign key file, leapsecond file and identity scheme files. The digest/signature scheme is specified in the X.509 certificate along with the matching sign key. There are several schemes available in the OpenSSL software library, each identified by a specific string such as <tt>md5WithRSAEncryption</tt>, which stands for the MD5 message digest with RSA encryption scheme. The current NTP distribution supports all the schemes in the OpenSSL library, including those based on RSA and DSA digital signatures.</p> - <p>NTP secure groups can be used to define cryptographic compartments and security hierarchies. It is important that every host in the group be able to construct a certificate trail to one or more trusted hosts in the same group. Each group host runs the Autokey protocol to obtain the certificates for all hosts along the trail to one or more trusted hosts. This requires the configuration file in all hosts to be engineered so that, even under anticipated failure conditions, the NTP subnet will form such that every group host can find a trail to at least one trusted host.</p> - <h4>Naming and Addressing</h4> - <p>It is important to note that Autokey does not use DNS to resolve addresses, since DNS can't be completely trusted until the name servers have synchronized clocks. The cryptographic name used by Autokey to bind the host identity credentials and cryptographic values must be independent of interface, network and any other naming convention. The name appears in the host certificate in either or both the subject and issuer fields, so protection against DNS compromise is essential.</p> - <p>By convention, the name of an Autokey host is the name returned by the Unix <tt>gethostname()</tt> system call or equivalent in other systems. By the system design model, there are no provisions to allow alternate names or aliases. However, this is not to say that DNS aliases, different names for each interface, etc., are constrained in any way.</p> - <p>It is also important to note that Autokey verifies authenticity using the host name, network address and public keys, all of which are bound together by the protocol specifically to deflect masquerade attacks. For this reason Autokey includes the source and destinatino IP addresses in message digest computations and so the same addresses must be available 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> - <h4 id="cfg">Configuration</h4> - <p>Autokey has an intimidating number of options, most of which are not necessary in typical scenarios. The simplest configuration consists of a subnet with one or more servers at the same low stratum acting as trusted hosts and with dependent clients at higher strata and sharing a single secure group and identity scheme. Each trusted host generates a host key, trusted certificate and group key. Each client generates a host key, normal certificate and installs the group key of each trusted host using secure means and renames it as the name of the trusted host.</p> - <p>For example, trusted host Alice generates keys using</p> - <p><tt>ntp-keygen -H -T -I -p xyz</tt></p> - <p>where H specifies a new host key, T the trusted certificate, I the IFF identity scheme and p the password used to encrypt the private key files. The group key file is <tt>ntpkey_IFFpar_alice.<i>filestamp</i></tt><i>, </i>where <i>filestamp </i>represents the NTP time in seconds when the file was generated.</p> - <p>Host Bob generate keys using</p> - <p><tt>ntp-keygen -H -p abc</tt></p> - <p>where <tt>abc</tt> is different for each group host. The trusted host generates a password-protected group key using</p> - <p><tt>ntp-keygen -q xyz -p abc -e ><i>temp</i></tt></p> - <p>where <tt>xyz</tt> is the trusted host password, <tt>abc</tt> is the password supplied by the client and <i><tt>temp</tt></i> is a temporary file. This file is transmitted to Bob using secure means and renamed to the fully qualified host name for Alice preceded by the string <tt>ntpkey_iff_</tt>.</p> - <h4>Operation</h4> - <p>A specific combination of authentication scheme (none, symmetric key, public key) and identity scheme is called a cryptotype, although not all combinations are compatible. There may be management configurations where the clients, servers and peers may not all support the same cryptotypes. A secure NTPv4 subnet can be configured in many ways while keeping in mind the principles explained above and in this section. Note however that some cryptotype combinations may successfully interoperate with each other, but may not represent good security practice.</p> - <p>The cryptotype of an association is determined at the time of mobilization, either at configuration time or some time later when a message of appropriate cryptotype arrives. When mobilized by a <tt>server</tt> or <tt>peer</tt> configuration command and no <tt>key</tt> or <tt>autokey</tt> subcommands are present, the association is not authenticated; if the <tt>key</tt> subcommand is present, the association is authenticated using the symmetric key ID specified; if the <tt>autokey</tt> subcommand is present, the association is authenticated using Autokey.</p> - <h4 id="key">Key Management</h4> - <p>The cryptographic values used by the Autokey protocol are incorporated as a set of files generated by the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program, including symmetric key, host key and public certificate files, as well as sign key, identity parameters and leapseconds files. Alternatively, host and sign keys and certificate files can be generated by the OpenSSL utilities and certificates can be imported from public certificate authorities. Note that symmetric keys are necessary for the <tt>ntpq</tt> and <tt>ntpdc</tt> utility programs. The remaining files are necessary only for the Autokey protocol.</p> - <p>Certificates imported from OpenSSL or public certificate authorities have certian limitations. The certificate should be in ASN.1 syntax, X.509 Version 3 format and encoded in PEM, which is the same format used by OpenSSL. The overall length of the certificate encoded in ASN.1 must not exceed 1024 bytes. The subject distinguished name field (<tt>CN</tt>) is the fully qualified name of the host on which it is used; the remaining subject fields are ignored. The certificate extension fields must not contain either a subject key identifier or a issuer key identifier field; however, an extended key usage field for a trusted host must contain the value <tt>trustRoot</tt>;. Other extension fields are ignored.</p> - <h4 id="cmd">Authentication Commands</h4> - <dl> - <dt><tt>autokey [<i>logsec</i>]</tt> - <dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol. Note that the size of the key list for each association depends on this interval and the current poll interval. The default value is 12 (4096 s or about 1.1 hours). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent. - <dt><tt>controlkey <i>key</i></tt> - <dd>Specifies the key identifier 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>key</i></tt> argument is the key identifier for a trusted key, where the value can be in the range 1 to 65,534, inclusive. - <dt><tt>crypto [cert <i>file</i>] [leap <i>file</i>] [randfile <i>file</i>] [host <i>file</i>] [sign <i>file</i>] [ident <i>scheme</i>] [iffpar <i>file</i>] [gqpar <i>file</i>] [mvpar <i>file</i>] [pw <i>password</i>]</tt> - <dd>This command requires the OpenSSL library. It activates public key cryptography, selects the message digest and signature encryption scheme and loads the required private and public values described above. If one or more files are left unspecified, the default names are used as described above. 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> command or default <tt>/usr/local/etc</tt>. Following are the subcommands: - <dl> - <dt><tt>cert <i>file</i></tt> - <dd>Specifies the location of the required host public certificate file. This overrides the link <tt>ntpkey_cert_<i>hostname</i></tt> in the keys directory. - - <dt><tt>gqpar <i>file</i></tt> - <dd>Specifies the location of the client GQ parameters file. This overrides the link <tt>ntpkey_gq_<i>hostname</i></tt> in the keys directory. - - <dt><tt>host <i>file</i></tt> - <dd>Specifies the location of the required host key file. This overrides the link <tt>ntpkey_key_<i>hostname</i></tt> in the keys directory. - <dt><tt>ident <i>scheme</i></tt> - <dd>Requests the server identity <i><tt>scheme</tt></i>, which can be <tt>IFF</tt>, <tt>GQ</tt> or <tt>MV</tt>. This is used when the host will not be a server for a dependent client.<dt><tt>iffpar <i>file</i></tt> - <dd>Specifies the location of the optional IFF parameters file.This overrides the link <tt>ntpkey_iff_<i>hostname</i></tt> in the keys directory. - <dt><tt>leap <i>file</i></tt> - <dd>Specifies the location of the client leapsecond file. This overrides the link <tt>ntpkey_leap</tt> in the keys directory. - <dt><tt>mv</tt> - <dd>Requests the MV server identity scheme. - <dt><tt>mvpar <i>file</i></tt> - <dd>Specifies the location of the client MV parameters file. This overrides the link <tt>ntpkey_mv_<i>hostname</i></tt> in the keys directory. - <dt><tt>pw <i>password</i></tt> - <dd>Specifies the password to decrypt files containing private keys and identity parameters. This is required only if these files have been encrypted. - <dt><tt>randfile <i>file</i></tt> - <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described in the main text above. - <dt><tt>sign <i>file</i></tt> - <dd>Specifies the location of the optional sign key file. This overrides the link <tt>ntpkey_sign_<i>hostname</i></tt> in the keys directory. If this file is not found, the host key is also the sign key. - </dl> - <dt><tt>keys <i>keyfile</i></tt> - <dd>Specifies the complete path and location of the MD5 key file containing the keys and key identifiers 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. - <dt><tt>keysdir <i>path</i></tt> - <dd>This command specifies the default directory path for cryptographic keys, parameters and certificates. The default is <tt>/usr/local/etc/</tt>. - <dt><tt>requestkey <i>key</i></tt> - <dd>Specifies the key identifier 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>key</i></tt> argument is a key identifier for the trusted key, where the value can be in the range 1 to 65,534, inclusive. - <dt><tt>revoke [<i>logsec</i>]</tt> - <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 of the scheme; however, updating some values is a relatively expensive operation. The default interval is 16 (65,536 s or about 18 hours). For poll intervals above the specified interval, the values will be updated for every message sent. - <dt><tt>trustedkey <i>key</i> [...]</tt> - <dd>Specifies the key identifiers which are trusted for the purposes of authenticating peers with symmetric key cryptography, as well as keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> programs. The authentication procedures require that both the local and remote servers share the same key and key identifier for this purpose, although different keys can be used with different servers. The <tt><i>key</i></tt> arguments are 32-bit unsigned integers with values from 1 to 65,534. - </dl> - <h4 id="err">Error Codes</h4> - <p>Errors can occur due to mismatched configurations, unexpected 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 <tt><a href="keygen.html">ntp-keygen</a></tt> program.</p> - <p>The following error codes are reported via the NTP control and monitoring protocol trap mechanism.</p> - <dl> - <dt>101 (bad field format or length) - <dd>The packet has invalid version, length or format. - <dt>102 (bad timestamp) - <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. - <dt>103 (bad filestamp) - <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. - <dt>104 (bad or missing public key) - <dd>The public key is missing, has incorrect format or is an unsupported type. - <dt>105 (unsupported digest type) - <dd>The server requires an unsupported digest/signature scheme. - <dt>106 (unsupported identity type)<dd>The client or server has requested an identity scheme the other does not support.<dt>107 (bad signature length) - <dd>The signature length does not match the current public key. - <dt>108 (signature not verified) - <dd>The message fails the signature check. It could be bogus or signed by a different private key. - <dt>109 (certificate not verified) - <dd>The certificate is invalid or signed with the wrong key.<dt>110 (host certificate expired)<dd>The old server certificate has expired.<dt>111 (bad or missing cookie) - <dd>The cookie is missing, corrupted or bogus. - <dt>112 (bad or missing leapseconds table) - <dd>The leapseconds table is missing, corrupted or bogus. - <dt>113 (bad or missing certificate) - <dd>The certificate is missing, corrupted or bogus. - <dt>114 (bad or missing group key)<dd>The identity key is missing, corrupt or bogus. - - <dt>115 (protocol error) - <dd>The protocol state machine has wedged due to unexpected restart - <dt>116 (server certificate expired) - <dd>The old server certificate has expired. - </dl> - <h4 id="file">Files</h4> - <p>See the <a href="keygen.html"><tt>ntp-keygen</tt></a> page.</p> - <h4 id="leap">Leapseconds Table</h4> - <p>The NIST provides a file documenting the epoch for all historic occasions of leap second insertion since 1972. The leapsecond table shows each epoch of insertion along with the offset of International Atomic Time (TAI) with respect to Coordinated Universal Time (UTC), as disseminated by NTP. The table can be obtained directly from NIST national time servers using <tt>ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.</p> - <p>While not strictly a security function, the Autokey protocol provides means to securely retrieve the leapsecond table from a server or peer. Servers load the leapsecond table directly from the file specified in the <tt>crypto</tt> command, with default <tt>ntpkey_leap</tt>, while clients can obtain the table indirectly from the servers using the Autokey protocol. Once loaded, the table can be provided on request to other clients and servers.</p> - <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>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; +} +</style> +</head> +<body> +<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 -->15-Oct-2011 01:00<!-- #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> +<hr> +<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 hr). 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="autokey.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 for 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 [digest</tt> <em><tt>digest</tt></em><tt>]</tt> <tt>[host <i>name</i>] [ident <i>name</i>] [pw <i>password</i>] [randfile <i>file</i>]</tt></dt> + <dd>This command activates the Autokey public key cryptography + and loads the required host keys and certificate. If one or more files + are unspecified, the default names are used. 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 with default <tt>/usr/local/etc</tt>. See the <a href="autokey.html">Autokey Public Key Authentication</a> page for further information. Following are the options.</dd> + <dd> + <dl> + <dt><tt>digest</tt> <em><tt>digest</tt></em></dt> + <dd> </dd> + <dd>Specify the message digest algorithm, with default MD5. If the OpenSSL library + is installed, <tt><i>digest</i></tt> can be be any message digest algorithm supported + by the library. The current selections are: <tt>MD2</tt>, <tt>MD4</tt>, <tt>MD5,</tt> <tt>MDC2</tt>, <tt>RIPEMD160</tt>, <tt>SHA</tt> and <tt>SHA1</tt>. All + participants in an Autokey subnet must use the same algorithm. The Autokey message digest algorithm is separate and distinct from the symmetric + key message digest algorithm. 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>Specify the cryptographic media names for the host, sign and certificate files. If this option is not specified, the default name is the string returned by the Unix <tt>gethostname()</tt> routine.</dd> + <dd><span class="style1">Note: In the latest Autokey version, this option has no effect other than to change the cryptographic media file names.</span></dd> + <dt><tt>ident <i>group</i></tt></dt> + <dd>Specify the cryptographic media names for the identity scheme files. If this option is not specified, the default name is the string returned by the Unix <tt>gethostname()</tt> routine.</dd> + <dd><span class="style1">Note: In the latest Autokey version, this option has no effect other than to change the cryptographic media file names.</span></dd> + <dt><tt>pw <i>password</i></tt></dt> + <dd>Specifies the password to decrypt files previously encrypted by the <tt>ntp-keygen</tt> program with the <tt>-p</tt> option. If this option is not specified, the default password is the string returned by the Unix <tt>gethostname()</tt> routine. </dd> + <dt><tt>randfile <i>file</i></tt></dt> + <dd>Specifies the location of the random seed file used by the OpenSSL library. The defaults are described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>.</dd> + </dl> + </dd> + <dt id="ident"><tt>ident <i>group</i></tt></dt> + <dd>Specifies the group name for ephemeral associations mobilized by broadcast and symmetric passive modes. See the <a href="autokey.html">Autokey Public-Key Authentication</a> page for further information.</dd> + <dt id="keys"><tt>keys <i>path</i></tt></dt> + <dd>Specifies the complete directory path for the key file containing the key IDs, key types and keys used by <tt>ntpd</tt>, <tt>ntpq</tt> and <tt>ntpdc</tt> when operating with symmetric key cryptography. The format of the keyfile is described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>. This is the same operation as the <tt>-k</tt> command line option. Note that the directory path for Autokey cryptographic media is specified by the <tt>keysdir</tt> command.</dd> + <dt id="keysdir"><tt>keysdir <i>path</i></tt></dt> + <dd>Specifies the complete directory path for the Autokey cryptographic keys, parameters and certificates. The default is <tt>/usr/local/etc/</tt>. Note that the path for the symmetric keys file is specified by the <tt>keys</tt> command.</dd> + <dt id="requestkey"><tt>requestkey <i>keyid</i></tt></dt> + <dd>Specifies the key ID for 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, with default 17 (36 hr). See the <a href="autokey.html">Autokey Public-Key Authentication</a> page for further information.</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 requires that both the local and + remote NTP servers employ the same key ID and secret for this + purpose, although different keys IDs may be used with different + servers. Ranges of trusted key IDs may be specified: <tt>trustedkey (1 ... 19) 1000 (100 ... 199)</tt> enables the + lowest 120 key IDs which start with the digit 1. The spaces + surrounding the ellipsis are required when specifying a range.</dd> +</dl> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/autokey.html b/contrib/ntp/html/autokey.html new file mode 100644 index 0000000..ba220e6 --- /dev/null +++ b/contrib/ntp/html/autokey.html @@ -0,0 +1,215 @@ +<!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"> +<style type="text/css"> +<!-- +.style1 { + color: #FF0000 +} +--> +</style> +</head> +<body> +<h3>Autokey Public-Key Authentication</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->3-Oct-2011 21:51<!-- #EndDate --> + UTC</p> +<hr> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#intro">Introduction</a></li> + <li class="inline"><a href="#subnet">Autokey Subnets</a></li> + <li class="inline"><a href="#names">Subnet Group Names's</a></li> + <li class="inline"><a href="#secure">Secure Groups</a></li> + <li class="inline"><a href="#cfg">Configuration - Authentication Schemes</a></li> + <li class="inline"><a href="#scfg">Configuration - Identity Schemes</a></li> + <li class="inline"><a href="#ident">Identity Schemes and Cryptotypes</a></li> + <li class="inline"><a href="#files">Files</a></li> +</ul> +<hr> +<h4 id="intro">Introduction</h4> +<p>This distribution includes support for the Autokey public key algorithms and protocol specified in RFC-5906 "Network Time Protocol Version 4: Autokey Specification". This support is available only if the OpenSSL library has been installed and the <tt>--enable-autokey</tt> option is specified when the distribution is built.</p> +<p> Public key cryptography is generally considered more secure than symmetric key cryptography. Symmetric key cryptography is based on a shared secret key which must be distributed by secure means to all participants. Public key cryptography is based on a private secret key known only to the originator and a public key known to all participants. A recipient can verify the originator has the correct private key using the public key and any of several digital signature algorithms.</p> +<p>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 message digest algorithms, such as MD5 or SHA, and verifies the source using digital signature schemes, such as RSA or DSA. As used in Autokey, message digests are exceptionally difficult to cryptanalyze, as the keys are used only once.</p> +<p> 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. Optional identity schemes provide strong security against masquerade and most forms of clogging attacks. These schemes are exceptionally difficult to cryptanalyze, as the challenge/response exchange data are used only once. They 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 IP 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 and clients are operated outside firewall perimeters.</p> +<p>Autokey is designed to authenticate servers to clients, not the other way around as in SSH. An Autokey server can support an authentication scheme such as the Trusted Certificate (TC) scheme described in RFC 5906, while a client is free to choose between the various options. It is important to understand that these provisions are optional and that selection of which option is at the discretion of the client. If the client does not require authentication, it is free to ignore it, even if some other client of the same server elects to participate in either symmetric key or public key cryptography.</p> +<p> Autokey uses industry standard X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library, and the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program in the NTP software distribution. A certificate includes the subject name of the client, the issuer name of the server, the public key of the client and the time period over which the the public and private keys are valid. All Autokey hosts have a self-signed certificate with the Autokey name as both the subject and issuer. During the protocol, additional certificates are produced with the Autokey host name as subject and the host that signs the certificate as issuer.</p> +<p>There are two timeouts associated with the Autokey scheme. The <em>key list timeout</em> is set by the <tt>automax</tt> command, which specifies the interval between generating new key lists by the client or server. The default timeout of about 1.1 hr is appropriate for the majority of configurations and ordinarily should not be changed. The <em>revoke timeout</em> is set by the <tt>revoke</tt> command, which specifies the interval between generating new server private values. It is intended to reduce the vulnerability to cryptanalysis; however, new values require the server to encrypt each client cookie separately. The default timeout of about 36 hr is appropriate for most servers, but might be too short for national time servers.</p> +<h4 id="subnet">Autokey Subnets</h4> +<p> An Autokey subnet consists of a collection of hosts configured as an acyclic, directed tree with roots one or more trusted hosts (THs) operating at the lowest stratum of the subnet. Note that the requirement that the NTP subnet be acyclic means that, if two hosts are configured with each other in symmetric modes, each must be a TH. The THs are synchronized directly or indirectly to national time services via trusted means, such as radio, satellite or telephone modem, or one or more trusted agents (TAs) of a parent subnet. NTP subnets can be nested, with the THs of a child subnet configured for one or more TAs of a parent subnet. The TAs can serve one or more child subnets, each with its own security policy and set of THs.</p> +<p>A certificate trail is a sequence of certificates, each signed by a host one step closer to the THs and terminating at the self-signed certificate of a TH. The requirement that the subnet be acyclic means certificate trails can never loop. NTP servers operate as certificate authorities (CAs) to sign certificates provided by their clients. The CAs include the TAs of the parent subnet and those subnet servers with dependent clients.</p> +<p> In order for the signature to succeed, the client certificate valid period must begin within the valid period of the server certificate. If the server period begins later than the client period, the client certificate has expired; if the client period begins later than the server period, the server certificate has expired.</p> +<p>The Autokey protocol runs for each association separately, During the protocol, the client recursively obtains the certificates on the trail to a TH, saving each in a cache ordered from most recent to oldest. If an expired certificate is found, it is invalidated and marked for later replacement. As the client certificate itself is not involved in the certificate trail, it can only be declared valid or expired when the server signs it. </p> +<p>The certificates derived from each association are combined in the cache with duplicates suppressed. If it happens that two different associations contribute certificates to the cache, a certificate on the trail from one association could expire before any on another trail. In this case the remaining trails will survive until the expired certificate is replaced. Once saved in the cache, a certificate remains valid until it expires or is replaced by a new one.</p> +<p> It is important to note that the certificate trail is validated only at startup when an association is mobilized. Once validated in this way, the server remains valid until it is demobilized, even if certificates on the trail to the THs expire. While the certificate trail authenticates each host on the trail to the THs, it does not validate the time values themselves. Ultimately, this is determined by the NTP on-wire protocol.</p> +<p>Example</p> +<div align="center"><img src="pic/flt8.gif" alt="gif"> + <p>Figure 1. Example Configuration</p> +</div> +<p>Figure 1 shows an example configuration with three NTP subnets, Alice, Helen and Carol. Alice and Helen are parent groups for Carol with TA C belonging to Alice and TA S belonging to Helen. Hosts A and B are THs of Alice, host R is the TH of Helen and host X is the TH of Carol. Assume that all associations are client/server, child subnet TH X has two mobilized associations, one to Alice TA host C and the other to Carol TA host S. While not shown in the figure, Alice hosts A and B could configure symmetric mode associations between them for redundancy and backup.</p> +<p>Note that host D certificate trail is D→C→A or D→C→B, depending on the particular order the trails are built. Host Y certificate trail is only Y→X, since X is a TH. Host X has two certificate trails X→C→A or X→C→B, and X→S→R.</p> +<h4 id="names">Subnet Group Names</h4> +<p>In some configurations where more than one subnet shares an Ethernet or when multiple subnets exist in a manycast or pool configuration, it is useful to isolate one subnet from another. In Autokey this can be done using group names. An Autokey host name is specified by the <tt>-s</tt><tt><em> host</em>@<em>group</em></tt> option of the <tt>ntp-keygen</tt> program, where <em><tt>host</tt></em> is the host name and <em><tt>group</tt></em> is the group name. If <em><tt>host</tt></em> is omitted, the name defaults to the string returned by the Unix <tt>gethostname()</tt> routine, ordinarily the DNS name of the host. Thus, for host <tt>beauregard.udel.edu</tt> the option <tt>-s @red</tt> specifies the Autokey host name <tt>beauegard.udel.edu@red</tt>.</p> +<p>A subnet host with a given group name will discard ASSOC packets from all subnets with a different group name. This effectively disables the Autokey protocol without additional packet overhead. For instance, one or more manycast or pool servers will not respond to ASSOC packets from subnets with difference group names. Groups sharing an Ethernet will be filtered in the same way.</p> +<p>However, as shown in Figure 1, there are configurations where a TH of one group needs to listen to a TA of a different group. This is accomplished using the <tt>ident <em>group</em></tt> option of the <tt>crypto</tt> command and/or the <tt>ident <em>group</em></tt> option of the <tt>server</tt> command. The former case applies to all hosts sharing a common broadcast, manycast or symmetric passive modes, while the latter case applies to each individual client/server or symmetric active mode association. In either case the host listens to the specified group name in addition to the group name specified in the <tt>-s</tt> option of the <tt>ntp-keygen</tt> program.</p> +<h4 id="secure">Secure Groups</h4> +<p>NTP security groups are an extension of the NTP subnets described in the previous section. They include in addition to certificate trails one or another identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page. NTP secure groups are used to define cryptographic compartments and security + hierarchies. The identity scheme insures that the server is authentic and not victim of masquerade by an intruder acting as a middleman.</p> +<p> An NTP secure group is an NTP subnet configured as an acyclic tree rooted on the THs. The THs are at the lowest stratum of the secure group. They run an identity exchange with the TAs of parent subnets All group hosts construct an unbroken certificate trail from each host, possibly via intermediate hosts, and ending at a TH of that group. The TH verifies authenticity with the TA of the parent subnet using an identity exchange.</p> +<div align="center"><img src="pic/flt9.gif" alt="gif"> + <p>Figure 2. Identify Scheme</p> +</div> +<p>The identity exchange is run between a TA acting as a server and a TH acting as a client. As shown in Figure 2, the identity exchange involves a challenge-response protocol where a client generates a nonce and sends it to the server. The server performs a mathematical operation involving a second nonce and the secret group key, and sends the result along with a hash to the client. The client performs a another mathematical operation and verifies the result with the hash.</p> +<p> Since each exchange involves two nonces, even after repeated observations of many exchanges, an intruder cannot learn the secret group key. It is this quality that allows the secret group key to persist long after the longest period of certificate validity. In the Schnorr (Identify Friend or Foe - IFF) scheme, the secret group key is not divulged to the clients, so they cannot conspire to prove identity to other hosts.</p> +<p>As described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page, there are five identity schemes, three of which - IFF, GQ and MV - require identity files specific to each scheme. There are two types of files for each scheme, an encrypted server keys file and a nonencrypted client keys file, also called the parameters file, which usually contains a subset of the keys file.</p> +<p> Figure 2 shows how keys and parameters are distributed to servers and clients. A TA constructs the encrypted keys file and the nonencrypted parameters file. Hosts with no dependent clients can retrieve client parameter files from an + archive or web page. The <tt>ntp-keygen</tt> program can export parameter files using the <tt>-e</tt> option. By convention, the file name is the name of the secure group and must match the <tt>ident</tt> option of the <tt>crypto</tt> command or the <tt>ident</tt> option of the <tt>server</tt> command.</p> +<p> When more than one TH Is involved in the secure group, it is convenient for the TAs and THs to use the same encrypted key files. To do this, one of the parent TAs includes the <tt>-i <em>group</em></tt> option on the <tt>ntp-keygen</tt> command line, where <em><tt>group</tt></em> is the name of the child secure group. The <tt>ntp-keygen</tt> program can export server keys files using the <tt>-q</tt> option and a chosen remote password. The files are installed on the TAs and then renamed using the name given as the first line in the file, but without the filestamp. The secure group name must match the <tt>ident</tt> option for all TAs.</p> +<dl> + <dd><span class="style1">In the latest Autokey version, the host name and group name are independent of each other and the <tt>host</tt> option of the <tt>crypto</tt> command is deprecated. When compatibility with older versions is required, specify the same name for both the <tt>-s</tt> and <tt>-i</tt> options.</span></dd> +</dl> +<p>In special circumstances the Autokey message digest algorithm can be changed using the <tt>digest</tt> option of the <tt>crypto</tt> command. The digest algorithm is separate and distinct from the symmetric + key message digest algorithm. If compliance with FIPS 140-2 is required, + the algorithm must be ether <tt>SHA</tt> or <tt>SHA1</tt>. The Autokey message digest algorithm must be the same for all participants in the NTP subnet.</p> +<p>Example</p> +<p>Returning to the example of Figure 1, Alice, Helen and Carol run run the Trusted Certificate (TC) scheme, internally, as the environment is secure and without threat from external attack, in particular a middleman masquerade. However, TH X of Carol is vulnerable to masquerade on the links between X and C and between X and S. Therefore, both parent subnet TAs C and S run an identity exchange with child subnet TH X. Both have the same encrypted keys file and X the common parameters file.</p> +<h4 id="cfg">Configuration - Authentication Schemes</h4> +<p>Autokey has an intimidating number of options, most of which are not necessary in typical scenarios. However, the Trusted Certificate (TC) scheme is recommended for national NTP time services, such as those operated by NIST and USNO. Configuration for TC is very simple.</p> +<p> Referring to Figure 1, for each TH, A, B, R and X, as root:</p> +<p><tt># cd /usr/local/etc<br> + # ntp-keygen -T</tt></p> +<p>and for the other hosts the same commands without the <tt>-T</tt> option. This generates an RSA private/public host key file and a self-signed certificate file for the RSA digital signature algorithm with the MD5 message digest algorithm. For the THs a trusted certificate is generated; for the others a nontreusted certificate is generated. Include in the <tt>ntp.conf</tt> configuration file for all hosts other than the primary servers, A, B and R, something like</p> +<p><tt> # server <em>host</em> autokey<br> + # crypto<br> + # driftfile /etc/ntp.drift</tt></p> +<p>where <em><tt>host</tt></em> is the selected server name as shown in the figure. Servers A, B and R are configured for local reference clocks or trusted remoter servers as required.</p> +<p>In the above configuration examples, the default host name is the string returned by the Unix <tt>gethostname()</tt> routine, ordinarily the DNS name of the host. This name is used as the subject and issuer names on the certificate, as well as the default password for the encrypted keys file. The host name can be changed using the <tt>-s</tt> option of the <tt>ntp-keygen</tt> program. The default password can be changed using the <tt>-p</tt> option of the <tt>ntp-keygen</tt> program and the <tt>pw</tt> option of the <tt>crypto</tt> configuration command.</p> +<p>Group names can be added to this configuration by including the <tt>-s <em>host</em>@<em>group</em></tt> option with the <tt>ntp-keygen</tt> program. For the purpose of illustration, the <tt><em>host</em></tt> string is empty, signifying the default host name. For example, @<tt>yellow</tt> can be used for the Alice group, @<tt>orange</tt> for the Helen group and @<tt>blue</tt> for the Carol group. In addition, for TH X the <tt>ident yellow</tt> option should be added to the <tt>server</tt> command for the Alice group and the <tt>ident orange</tt> option should be added to the <tt>server</tt> command for the Helen group.</p> +<h4 id="scfg">Configuration - Identity Schemes</h4> +<p> The example in this section uses the IFF identity scheme, but others, including GQ and MV, can be used as well. It's best to start with a functioning TC configuration and add commands as necessary. We start with the subnets of Figure 1 configured as in the previous section. Recall that the parent subnet TA for Alice is C and for Helen is S. Each of the TAs generates an encrypted server keys file and nonencrypted client parameters file for the IFF identity scheme using the <tt>-I</tt> option of the <tt>ntp-keygen</tt> program. Note the TAs are not necessarily trusted hosts, so may not need the <tt>-T</tt> option.</p> +<p>The nonencrypted client parameters can be exported using the command</p> +<p><tt>ntp-keygen -e ><i>file</i></tt>,</p> +<p>where the <tt>-e</tt> option redirects the client parameters to <em><tt>file</tt></em> via the standard output stream for a mail application or stored locally for later distribution to one or more THs. In a similar fashion the encrypted keys file can be exported using the command</p> +<p><tt>ntp-keygen -q <em>passw2</em> ><i>file</i></tt>,</p> +<p>where <em><tt>passwd2</tt></em> is the read password for another TA. We won't need this file here.</p> +<p> While the file names used for the exported files are arbitrary, it is common practice to use the name given as the first line in the file with the filestamp suppressed. Thus, the nonencryted parameters file from each TA is copied to X with this name.</p> +<p>To complete the configuration, the TH includes the client parameters file name in the <tt>ident</tt> option of the the <tt>server</tt> command for the TA association</p> +<p><tt>server 1.2.3.4 ident <em>group</em>,</tt></p> +<p> where <em><tt>group</tt></em> is the file name given above. </p> +<h4 id="ident">Identity Schemes and Cryptotypes</h4> +<p>A specific combination of authentication and identity schemes is called a <em>cryptotype</em>, 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="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="files">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> diff --git a/contrib/ntp/html/bugs.html b/contrib/ntp/html/bugs.html new file mode 100644 index 0000000..7be6a4c --- /dev/null +++ b/contrib/ntp/html/bugs.html @@ -0,0 +1,27 @@ +<!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> +<!-- Changed by: Harlan &, 23-Aug-2014 --> +<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 -->23-Aug-2014 05:32<!-- #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 or documentation 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 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> to participate directly in any e-mail discussion regarding your report. If you don't register and we have questions for you we won't be able to make progress on fixing your problem. Please directly register on and use our Bugzilla instance to report issues.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/build.html b/contrib/ntp/html/build.html new file mode 100644 index 0000000..5e3c2d8 --- /dev/null +++ b/contrib/ntp/html/build.html @@ -0,0 +1,57 @@ +<!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: + <!-- #BeginDate format:En2m -->1-Apr-2015 02:57<!-- #EndDate --> +</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>, and <tt>make 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 2000 and later. 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> diff --git a/contrib/ntp/html/build/build.html b/contrib/ntp/html/build/build.html deleted file mode 100644 index 0bb49af..0000000 --- a/contrib/ntp/html/build/build.html +++ /dev/null @@ -1,83 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <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="99">03:06 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="270">Monday, October 13, 2003</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.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 under Unix</a> - <li class="inline"><a href="#comp">Compilation</a> - <li class="inline"><a href="#install">Installation</a> - <li class="inline"><a href="#config">Configuration</a> - <li class="inline"><a href="#prob">If You Have Problems</a> - <li class="inline"><a href="#win">Building and Installing under Windows NT</a> - </ul> - <hr> - <h4 id="build">Building and Installing the Distribution</h4> - <p>As a practical matter, every computer architecture and operating system version seems to be different than any other. The device drivers may be different, the input/output system may be idiosyncratic and the libraries may have different semantics. It is not possible in a software distribution such as this one to support every individual system with a common set of binaries, even with the same system but different versions. Therefore, it is necessary to individually configure the software build for each system and version, both at compile time and at run time. In almost all cases, these procedures are completely automatic and all the newbie user need do is type "configure", "make" and "install" 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> page.</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 NTPv4. The procedures for doing that are included in the OpenSSL documentation. The library is found during the normal NTPv4 configure phase and the interface routines compiled automatically. Only the <tt>libcrypto.a</tt> library and associated header files are used. If the library is not available or disabled, this step is not required.</p> - <h4 id="unix">Building and Installing under Unix</h4> - <p>Make sure that you have all necessary tools for building executables. These tools include <tt>cc/gcc, make, awk, sed, tr, sh, grep, egrep</tt> and a few others. 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. 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 tests for the presence of system header files and the contents of these files to determine if certain features are present. When one or more of these features are present, the code is compiled to use them; if not, no special code is compiled. However, even if the code is compiled to use these features, the code does a special test at run time to see if one or more are actually present and avoids using them if not present. In such cases a warning message is sent to the system log, but the daemon should still work properly.</p> - <p>The default build normally includes the debugging code, which can be useful in diagnosing problems found in initial test, and all reference clock drivers known to work with each machine and operating system. Unless memory space is at a premium, this is a sensible strategy and greatly simplifies debugging and support. If you need to delete either the debugging code or one or all reference clock drivers to save space, see the <a href="config.html">Configuration Options</a> page.</p> - <p>If your site supports multiple architectures and uses NFS to share files, you can use a single source tree to compile executables for all architectures. While running on a target architecture machine and in the distribution base directory create a subdirectory using a command like <tt>mkdir A.`config.guess`</tt>, which will create an architecture-specific directory with name peculiar to the architecture and operating system. Then change to this directory and emit a <tt>../configure</tt> command. The remaining steps are the same whether building in the base directory or in the subdirectory.</p> - <h4 id="comp">Compilation</h4> - <p>Use the <tt>make</tt> command to compile all source modules, construct the libraries and link the distribution. Expect few or no warnings using <tt>cc</tt> and a moderate level of warnings using <tt>gcc</tt>. Note: On some Unix platforms <tt>gcc</tt> may show quite a few complaints about system header files and type inconsistencies, especially with pointer variables. This is usually the case when the system header files are not up to ANSI standards or <tt>gcc </tt>expectations, when <tt>gcc</tt> is not installed properly, or when operating system updates and patches are applied and <tt>gcc</tt> is not reinstalled. While the autoconfigure process is quite thorough, the Unix programming cultures of the various workstation makers still remain idiosyncratic.</p> - <h4 id="install">Installation</h4> - <p>As root, use the <tt>make install</tt> command to install the binaries in the destination directory. Most commonly, these programs are installed in <tt>/usr/local/bin</tt>, but this can be overridden during configuration. You must of course have write permission on the install in the destination directory. This includes the following programs:</p> - <ul> - <li><a href="../ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> - <li><a href="../ntpq.html"><tt>ntpq</tt> - standard NTP query program</a> - <li><a href="../ntpdc.html"><tt>ntpdc</tt> - special NTP query program</a> - <li><a href="../ntpdate.html"><tt>ntpdate</tt> - set the date and time via NTP</a> - <li><a href="../ntptrace.html"><tt>ntptrace</tt> - trace a chain of NTP servers back to the primary source</a> - </ul> - <p>If the precision time kernel modifications are present, the following program is installed:</p> - <ul> - <li><a href="../ntptime.html"><tt>ntptime</tt> - read kernel time variables</a> - </ul> - <p>If the public key authentication functions are present, the following program is installed:</p> - <ul> - <li><a href="../keygen.html"><tt>ntp-keygen</tt> - generate public and private keys</a> - </ul> - <p>In some systems that include the capability to edit kernel variables, the following program is installed:</p> - <ul> - <li><a href="../tickadj.html"><tt>tickadj</tt> - set time-related kernel variables</a> - </ul> - <p>Cryptographic support, both symmetric and public key, requires one or more key files, commonly installed in <tt>/usr/local/etc</tt>. Public key cryptography requires a random seed file, usually called <tt>.rnd</tt>, installed in a dark place such as the root directory or <tt>/etc</tt>. Directions for generating keys is on the <a href="../authopt.html">Authentication Options</a> page.</p> - <h4 id="config">Configuration</h4> - <p>You are now ready to configure the daemon and start it. You will need to create a NTP configuration file <tt>ntp.conf</tt> and a cryptographic key file <tt>ntp.keys</tt>. The latter file is necessary only for remote configuration support, if needed. 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. A tutorial on NTP subnet design and configuration options is in the <a href="../notes.html">Notes on Configuring NTP and Setting up a NTP Subnet</a> page.</p> - <h4 id="prob">If You Have Problems</h4> - <p>If you have problems peculiar to the particular hardware and software environment (e.g. operating system-specific issues), browse the <a href="hints.html">Hints and Kinks</a> page. For other problems a tutorial on debugging technique is in the <a href="../debug.html">NTP Debugging Technique</a> page. As always, the first line of general assistance is the NTP web site <a href="http://www.ntp.org">www.ntp.org</a> and the FAQ 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. Bug reports of a specific nature should be sent to <a href="mailto:bugs@mail.ntp.org">bugs@ntp.org</a>. Bug reports of a specific nature on features implemented by the programmer corps mentioned in the <a href="../copyright.html">Copyright</a> page should be sent directly to the implementor listed in that page, with copy to bugs@ntp.org.</p> - <p>Please include the version of the source distribution (e.g., ntp-4.0.70a) in your bug report, as well as billboards from the relevant utility programs and debug trace, if available. Please include the output of <tt>config.guess</tt> in your bug report. It will look something like:</p> - <p><tt>pdp11-dec-fuzzos3.4</tt></p> - <h4>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> - <h4 id="win">Building and Installing under Windows NT</h4> - <p>See <tt><a href="hints/winnt.html">hints/winnt.htm</a></tt> for directions to compile the sources and install the executables.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/build/config.html b/contrib/ntp/html/build/config.html deleted file mode 100644 index 961779d..0000000 --- a/contrib/ntp/html/build/config.html +++ /dev/null @@ -1,168 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <meta name="generator" content="HTML Tidy, see www.w3.org"> - <title>Configuration Options</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Configuration Options</h3> - <img src="../pic/pogo3a.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Pogo</i>, Walt Kelly</a> - <p>Gnu autoconfigure tools are in the backpack.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="99">12:56 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="266">Saturday, March 20, 2004</csobj></p> - <br clear="left"> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#basic">Basic Configuration Options - the <tt>configure</tt> utility</a> - <li class="inline"><a href="#opt">Options</a> - <li class="inline"><a href="#dir">Directory and File Names</a> - <li class="inline"><a href="#host">Host Type</a> - <li class="inline"><a href="#pkg">Optional Packages</a> - <li class="inline"><a href="#feat">Optional Features</a> - <li class="inline"><a href="#radio">Radio Clocks</a> - <li class="inline"><a href="#parse">PARSE Clocks</a> - </ul> - <hr> - <h4 id="basic">Basic Configuration Options - the <tt>configure</tt> utility</h4> - <p>The following options are for compiling and installing a working version of the NTP distribution. In most cases, the build process is completely automatic. In some cases where memory space is at a premium, or the binaries are to be installed in a different place, it is possible to tailor the configuration to remove such features as reference clock driver support, debugging support, and so forth.</p> - <p>Configuration options are specified as arguments to the <tt>configure</tt> script. Following is a summary of the current options, as of the 4.0.99m version:</p> - <p>Usage: <tt>configure [options] [host]</tt><br> - </p> - <h4 id="opt">Options</h4> - <p><tt>[defaults in brackets after descriptions]</tt> Configuration:</p> - <pre> - --cache-file=FILE cache test results in FILE - --help print this message - --no-create do not create output files - --quiet, --silent do not print `checking...' messages - --version print the version of autoconf that created -configure -</pre> - <h4 id="dir">Directory and File Names</h4> - <pre> - --prefix=PREFIX install architecture-independent files in PREFIX [/usr/local] - --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX [same as prefix] - --bindir=DIR user executables in DIR [EPREFIX/bin] - --sbindir=DIR system admin executables in DIR [EPREFIX/sbin] - --libexecdir=DIR program executables in DIR [EPREFIX/libexec] - --datadir=DIR read-only architecture-independent data in DIR [PREFIX/share] - --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] - --sharedstatedir=DIR modifiable architecture-independent data in DIR [PREFIX/com] - --localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var] - --libdir=DIR object code libraries in DIR [EPREFIX/lib] - --includedir=DIR C header files in DIR [PREFIX/include] - --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] - --infodir=DIR info documentation in DIR [PREFIX/info] - --mandir=DIR man documentation in DIR [PREFIX/man] - --srcdir=DIR find the sources in DIR [configure dir or ..] - --x-includes=DIR X include files are in DIR - --x-libraries=DIR X library files are in DIR - --program-prefix=PREFIX prepend PREFIX to installed program names - --program-suffix=SUFFIX append SUFFIX to installed program names - --program-transform-name=PROGRAM run sed PROGRAM on installed program names -</pre> - <h4 id="host">Host Type</h4> - <pre> - --build=BUILD configure for building on BUILD [BUILD=HOST] - --host=HOST configure for HOST [guessed] - --target=TARGET configure for TARGET [TARGET=HOST] -</pre> - <h4 id="pkg">Optional Packages</h4> - <pre> - --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] - --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) - - openssl-libdir=DIR OpenSSL object code libraries in DIR [/usr/lib/usr/local/lib/usr/local/ssl/lib] - openssl-incdir=DIR OpenSSL header files in DIR [/usr/include/usr/local/include/usr/local/ssl/include] - crypto=autokey Use autokey cryptography - crypto=rsaref Use the RSAREF library - electricfence Compile with ElectricFence malloc debugger -</pre> - <h4 id="feat">Optional Features</h4> - <pre> - --disable-FEATURE do not include FEATURE (same as - --enable-FEATURE=no) - --enable-FEATURE[=ARG] include FEATURE [ARG=yes] - - accurate-adjtime The adjtime() call is accurate - clockctl use /dev/clockctl (non root control of system clock) - debugging Include debugging code [enable] - des Include support for DES keys [enable] - dst-minutes=VALUE Minutes per DST adjustment [60] - gdt-surveying Include GDT survey code [disable] - hourly-todr-sync If we should sync TODR hourly - kernel-fll-bug If we should avoid a (Solaris) kernel FLL bug - kmem Read /dev/kmem for 'tick' and/or 'tickadj' - md5 Include support for MD5 keys [enable] - ntpdate-step If ntpdate should step the time - slew-always Always slew the time - step-slew Step and slew the time - tick=VALUE Force a value for 'tick' - tickadj=VALUE Force a value for 'tickadj' - udp-wildcard Use UDP wildcard delivery -</pre> - <h4 id="radio">Radio Clocks</h4> - <p>(these are ordinarily enabled, if supported by the machine and operating system):</p> - <pre> - all-clocks Include drivers for all suitable non-PARSE clocks [enable] - ACTS NIST dialup clock - ARBITER Arbiter 1088A/B GPS receiver - ARCRON_MSF Arcron MSF receiver - AS2201 Austron 2200A or 2201A GPS receiver - ATOM ATOM PPS interface - AUDIO-CHU CHU audio decoder - BANCOMM Datum/Bancomm BC635/VME interface (requires an explicit --enable-BANCOMM request) - CHRONOLOG Chrono-log K-series WWVB receiver - CHU CHU modem decoder - DATUM Datum Programmable Time System - DUMBCLOCK Dumb generic hh:mm:ss local clock - FG Forum Graphic GPS - GPSVME TrueTime GPS receiver with VME interface (requires an explicit --enable-GPSVME request) - HEATH HeathKit GC-1000 Most Accurate Clock - HOPFPCI HOPF 6039 PCI board - HOPFSERIAL HOPF serial clock device - HPGPS HP 58503A GPS Time & Frequency receiver - IRIG IRIG (Audio) Clock - JUPITER Rockwell Jupiter GPS receiver - LEITCH Leitch CSD 5300 Master Clock System Driver - LOCAL-CLOCK Local clock driver - MSFEES EES M201 MSF receiver - MX4200 Magnavox MX4200 GPS receiver - NMEA NMEA GPS receiver - ONCORE Motorola VP/UT Oncore GPS receiver - PALISADE Palisade clock - PCF Conrad parallel port radio clock - PST PST/Traconex 1020 WWV/H receiver - PTBACTS PTB dialup clock support - SHM Clock attached through shared memory (requires an explicit --enable-SHM request) - SPECTRACOM Spectracom 8170/Netclock/2 WWVB receiver - TRAK TRAK 8810 GPS station clock - TPRO KSI/Odetics TPRO/S IRIG Interface - TRUETIME Kinemetrics/TrueTime (generic) receiver - ULINK Ultralink WWVB receiver - USNO US Naval Observatory dialup clock - WWV WWV audio receiver -</pre> - <h4 id="parse">PARSE Clocks</h4> - <pre> - parse-clocks Include drivers for all suitable PARSE clocks [enable] - COMPUTIME Diem Computime Radio Clock - DCF7000 ELV/DCF7000 Clock - HOPF6021 HOPF 6021 Radio Clock support - MEINBERG Meinberg clocks - RAWDCF DCF77 raw time code - RCC8000 RCC 8000 Radio Clock support - SCHMID SCHMID DCF77 clock support - TRIMTAIP Trimble GPS/TAIP Protocol - TRIMTSIP Trimble GPS/TSIP Protocol - VARITEXT VARITEXT clock - WHARTON Wharton 400A Series clock -</pre> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/build/hints.html b/contrib/ntp/html/build/hints.html deleted file mode 100644 index b9e230b..0000000 --- a/contrib/ntp/html/build/hints.html +++ /dev/null @@ -1,23 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <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" alt="gif"><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="25" locale="00000409" region="0" t="DateTime" w="99">12:56 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="266">Saturday, March 20, 2004</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 diff --git a/contrib/ntp/html/build/hints/netbsd b/contrib/ntp/html/build/hints/netbsd deleted file mode 100644 index f5f628d..0000000 --- a/contrib/ntp/html/build/hints/netbsd +++ /dev/null @@ -1,37 +0,0 @@ -Starting with NetBSD-1.6, it is possible to delegate the system clock -control to a non root user. This enable running ntpd in a chroot -jail under a non privilegied UID/GID, using ntpd -i and -u flags. - -The delegation is done through the clockctl(4) pseudodevice driver. -This driver makes privilegied system calls such as ntp_adjtime(2) -available through ioctl(2) on the /dev/clockctl device. If a user -is able to write to /dev/clockctl, then (s)he can control the system -clock. - -In order to use this feature, make sure that: - -1) Your kernel is compiled with the following option: -pseudo-device clockctl -This is true for GENERIC kernels on most ports. Please check -http://wwW.netbsd.org/Documentation/kernel/ -if you need information about building a kernel. - -2) You have a ntpd user on your system. Here is the /etc/master.passwd -entry for ntpd user on NetBSD-1.6: -ntpd:*:15:15::0:0:& pseudo-user:/var/chroot/ntpd:/sbin/nologin -And here is the /etc/group entry for group 15: -ntpd:*:15: - -3) /dev/clockctl exists and is writtable by user ntpd. Default -NetBSD-1.6 setting is: -crw-rw---- 1 root ntpd 61, 0 Apr 1 2002 /dev/clockctl -Major device number and date is likely to be different on your system. -If you need to create the device, issue the following command: -cd /dev && ./MAKEDEV clockctl - -Here is an example of how to run ntpd chrooted in /var/chroot/ntpd, -running with ntpd UID and ntpd GID: -ntpd -i /var/chroot/ntpd -u ntpd:ntpd -Note that -i and -u options are enabled at configure time if your -system supports system clock control by an unprivilegied user. If this -is not the case, then the -i and -u options will not be available. diff --git a/contrib/ntp/html/build/hints/solaris.html b/contrib/ntp/html/build/hints/solaris.html deleted file mode 100644 index 9dc2ab1..0000000 --- a/contrib/ntp/html/build/hints/solaris.html +++ /dev/null @@ -1,144 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Solaris hints and kinks</title><link href="scripts/style.css" type="text/css" rel="stylesheet"> - -</HEAD> -<BODY> -Information on compiling and executing ntpd under Solaris. -<BR> -Last Updated: Sun Jun 21 01:32:18 EDT 1998, -John Hawkinson, -<! -- This is deliberately not a mailto -- > <jhawk@MIT.EDU> -<P> -If you're not running Solaris 2.5.1 or later, it is likely -that you will have problems; upgrading would be a really good plan. -<P> -<H3>All Solaris versions</H3> -<P> - We have a report that says starting with Solaris 2.6 we should leave - <I>dosynctodr</I> alone. - <A HREF="solaris-dosynctodr.html">Here is the report</A>. -<P> -Proper operation of ntp under Solaris may require setting the kernel -variable <I>dosynctodr</I> to zero (meaning "do not synchronize the clock -to the hardware time-of-day clock"). This can be done with the -tickadj utility: -<BLOCKQUOTE><TT> -tickadj -s -</TT></BLOCKQUOTE> -If you prefer, it can also be done with the native Solaris kernel debugger: -<BLOCKQUOTE><TT> -echo dosynctodr/W0 | adb -k -w /dev/ksyms /dev/mem -</BLOCKQUOTE></TT> -<P> -Or, it can also be set by adding a line to /etc/system: -<BLOCKQUOTE><TT> -set dosynctodr = 0 -</BLOCKQUOTE></TT> -<P> -Instead of the <I>tick</I> kernel variable, which many operating -systems use to control microseconds added to the system time every -clock tick (c.f. <A HREF="../../notes.html#frequency_tolerance">Dealing -with Frequency Tolerance Violations</A>), Solaris has the variables -<I>nsec_per_tick</I> and <I>usec_per_tick</I>. -<P> -<I>nsec_per_tick</I> and <I>usec_per_tick</I> control the number of -nanoseconds and microseconds, respectively, added to the system clock -each clock interrupt. Enterprising souls may set these based on -information collected by ntpd in the <CODE>/etc/ntp.drift</CODE> file -to correct for individual hardware variations. -<P> -On UltraSPARC systems, <I>nsec_per_tick</I> and <I>usec_per_tick</I> -are ignored in favor of the <I>cpu_tick_freq</I> variable, which -should be automatically be determined by the PROM in an accurate -fashion. -<P> -In general, the same ntp binaries should not be used across multiple -operating system releases. There is enough variation in the core operating -system support for timekeeping that a rebuild of ntpd for the idiosyncracies -of your specific operating system version is advisable. -<P> -It is recommended that ntp be started via a script like <A -HREF="solaris.xtra.S99ntpd">this one</A>, installed in -<CODE>/etc/init.d/ntpd</CODE> with a symbol link from -<CODE>/etc/rc2.d/S99ntpd</CODE>. - -<H3>Solaris 2.6</H3> -<P> -Solaris 2.6 adds support for kernel PLL timekeeping, but breaks this -support in such a fashion that using it worse than not. This is <A -HREF="solaris.xtra.4095849"> SUN Bug ID 4095849</A>, and it is not yet -fixed as of June 1998. -<P> -<H3>Solaris 2.5 and 2.5.1</H3> -<P> -On UltraSPARC systems, calculation of <I>cpu_tick_freq</I> is broken -such that values that are off by significant amounts may be used -instead. This unfortunately means that ntpd may have severe problems -keeping synchronization. This is <A HREF="solaris.xtra.4023118"> SUN Bug ID -4023118</A>. Bryan Cantrill <! -- <bmc@eng.sun.com> --> of Sun -posted <A HREF="solaris.xtra.patchfreq">patchfreq</A>, a workaround script, -to comp.protocols.time.ntp in March of 1997. -<P> -<HR> -<H2>OLD DATA</H2> -<STRONG>I can't vouch for the accuracy the information below this -rule. It may be significantly dated or incorrect.</STRONG> -<P> -<P> -<H3>Solaris 2.2</H3> -<P> -Solaris 2.2 and later contain completely re-written clock code to -provide high resolution microsecond timers. A benefit of the -re-written clock code is that adjtime does not round off its -adjustments, so ntp does not have to compensate for this -rounding. Under Solaris 2.2 and later, ntp #define's -<CODE>ADJTIME_IS_ACCURATE</CODE>, and does not look for the <I>tickadj</I> -kernel variable. -<P> -<H3>Solaris 2.1</H3> -(This originally written by William L. Jones <jones@chpc.utexas.edu>) -<P> -Solaris 2.1 contains fairly traditional clock code, with <I>tick</I> -and <I>tickadj</I>. -<P> -Since settimeofday under Solaris 2.1 only sets the seconds part of timeval -care must be used in starting xntpd. I suggest the following start -up script: -<BLOCKQUOTE><TT> -tickadj -s -a 1000 -<BR>ntpdate -v server1 server2 -<BR>sleep 20 -<BR>ntpdate -v server1 server2 -<BR>sleep 20 -<BR>tickadj -a 200 -<BR>xntpd -</TT></BLOCKQUOTE> - -The first tickadj turns of the time of day clock and sets the tick -adjust value to 1 millisecond. This will insure that an adjtime value -of at most 2 seconds will complete in 20 seconds. -<P> -The first ntpdate will set the time to within two seconds -using settimeofday or it will adjust time using adjtime. -<P> -The first sleep insures the adjtime has completed for the first ntpdate. -<P> -The second ntpdate will use adjtime to set the time of day since the -clock should be within 2 seconds of the correct time. -<P> -The second tickadj set the tick adjust system value to 5 microseconds. -<P> -The second sleeps insure that adjtime will complete before starting -the next xntpd. -<P> -I tried running with a tickadj of 5 microseconds with out much success. -200 microseconds seems to work well. -<P> -<HR> -Prior versions of this file had major text contributed by: -<MENU> -<LI>Denny Gentry <denny@eng.sun.com> -</MENU> -<BODY> -</HTML> diff --git a/contrib/ntp/html/build/hints/vxworks.html b/contrib/ntp/html/build/hints/vxworks.html deleted file mode 100644 index 95ad222..0000000 --- a/contrib/ntp/html/build/hints/vxworks.html +++ /dev/null @@ -1,82 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <title>vxWorks Port of NTP</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body link="#00008B" vlink="#8B0000"> - <h1>VxWorks port of NTP</h1> - <p>Creating a port for vxWorks posed some problems. This port may help as a starting point for similar ports to real-time OS's and other embeddable kernels, particularly where main() is not allowed, and where the configure scripts need to be altered.</p> - <h1><b>Configuration issues</b></h1> - <p>I decided to do as little invasive surgery as possible on the NTP code, so I brought the vxWorks header tree in line with the standard unix tree. The following changes were needed, as a side effect these changes will allow for easy porting of other autoconfigure enabled code.</p> - <p>Where I have 386 you will need to put in your target type. The vxWorks tree entry point is /usr/wind. If these are the same for your system, you should be able to cut and paste the changes.</p> - <p><blink>WARNING: Check you are not overwriting files, before entering the following: there should be no conflict, but check first... </blink></p> - <p>export CC="cc386 -nostdlib -m486 -DCPU=I80486 -I/usr/wind/target/h"<br> - export RANLIB=ranlib386<br> - export AR=ar386<br> - export VX_KERNEL=/usr/wind/target/config/ims_std_bsp/vxWorks<br> - cd /usr/wind/target/sys<br> - ln -s ../signal.h<br> - ln -s ../time.h<br> - ln -s socket.h sockio.h<br> - ln -s ../selectLib.h select.h<br> - ln -s ../timers.h<br> - touch file.h param.h resource.h utsname.h var.h ../netdb.h ../a.out.h ../termios.h<br> - echo " ******ADD #include \"sys/times.h\" to sys/time.h "</p> - <p>The configure script must be changed in the following way to get the linking tests to work, once in the correct directory issue the following commands:<br> - sed -e 's%main.*()%vxmain()%' configure > configure.vxnew<br> - mv configure.vxnew configure<br> - chmod 755 configure</p> - <p>The new version 4 of NTP requires some maths functions so it links in the maths library (-lm) in the ntpd <a href="../../ntpd/Makefile.am">Makefile.am</a> change the line "ntpd_LDADD = $(LDADD) -lm" by removing the "-lm".<br> - You are now ready to compile</p> - <p><br> - The <a href="../../configure.in">configure.in </a>file needed to be altered to allow for a host-target configuration to take place.</p> - <ul> - <li>The define SYS_VXWORKS was added to the compilation flags. - <li>Little endianess is set if the target is of type iX86. - <li>The size of char, integer, long values are all set. If Wind River ever changes these values they will need to be updated. - <li>clock_settime() is defined to be used for setting the clock. - <li>The Linking flags have -r added to allow for relinking into the vxWorks kernel - </ul> - <p>Unfortunately I have had to make use of the <a href="../../include/ntp_machine.h">ntp_machine.h </a>file to add in the checks that would have been checked at linking stage by autoconf, a better method should be devised.</p> - <ul> - <li>There is now a NO_MAIN_ALLOWED define that simulates command line args, this allows the use of the normal startup sysntax. - <li>POSIX timers have been added. - <li>Structures normally found in netdb.h have been added with, the corresponding code is in <a href="../../libntp/machines.c">machines.c </a>. Where possible the defines for these have been kept non-vxWorks specific. - </ul> - <p>Unfortunately there are still quite a few SYS_VXWORKS type defines in the source, but I have eliminated as many as possible. You have the choice of using the usrtime.a library avaliable from the vxworks archives or forgoing adjtime() and using the clock_[get|set]time().The <a href="../../include/ntp_machine.h">ntp_machine.h </a>file clearly marks how to do this.</p> - <h1><b>Compilation issues</b></h1> - <p>You will need autoconf and automake ... available free from the gnu archives worldwide.</p> - <p>The variable arch is the target architecture (e.g. i486)</p> - <p>mkdir A.vxworks (or whatever....)<br> - cd A.vxworks<br> - ../configure --target=arch-wrs-vxworks [any other options]<br> - make</p> - <p>Options I normally use are the --disable-all-clocks --enable-LOCAL-CLOCK flags. The program should proceed to compile without problem. The daemon ntpd, ntpdate, ntptrace, ntpdc, ntpq programs and of course the libraries are all fully ported. The other utilities are not, but they should be easy to port.</p> - <h1>Running the software</h1> - <p>Load in the various files, call them in the normal vxWorks function type manner. Here are some examples. Refer to the man pages for further information.</p> - <p>ld < ntpdate/ntpdate<br> - ld < ntpd/ntpd<br> - ld < ntptrace/ntptrace<br> - ld < ntpq/ntpq<br> - ld < ntpdc/ntpdc<br> - ntpdate ("-b", "192.168.0.245")<br> - sp(ntpd, "-c", "/export/home/casey/ntp/ntp.conf")<br> - ntpdc("-c", "monlist", "192.168.0.244")<br> - ntpq("-c", "peers", "192.168.0.244")<br> - ntptrace("192.168.0.244")<br> - </p> - <h1>Bugs and such</h1> - <p>Should you happen across any bugs, please let me know, or better yet fix them and submit a patch. Remember to make you patch general for Vxworks, not just for your particular architecture. <a href="http://www.ccii.co.za">CCII Systems (Pty) Ltd</a>, my ex employers, sponsored the time to this port. Please let me know how it goes, I would be most interested in offsets and configurations.</p> - <p><br> - </p> - <p>Casey Crellin<br> - <a href="mailto:casey@csc.co.za">casey@csc.co.za</a></p> - <p><br> - </p> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/build/hints/winnt.html b/contrib/ntp/html/build/hints/winnt.html deleted file mode 100644 index 78de15d..0000000 --- a/contrib/ntp/html/build/hints/winnt.html +++ /dev/null @@ -1,281 +0,0 @@ -<!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>NTP on Windows NT</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h1>NTP 4.x for Windows NT</h1> - - <h2>Introduction</h2> - The NTP 4 distribution runs as service on Windows NT 4.0, Windows 2000, Windows XP, - Windows .NET Server 2003. It will NOT run on Windows 95, 98, ME, etc. - The binaries work on multi-processor systems. This port has not been tested - on the Alpha platform. This release now uses OpenSSL for authentication. - IPv6 is not implemented yet for Win32 platforms. - <h2>Authentication Keys</h2> - With this release ntp-keygen is supported. See the <a href="../../keygen.html"> - ntp keygen documentation</a> for details on how to use ntp-keygen. - <p> - ntpd can now use the generated keys in the same way as on Unix platforms. Please - refer to the <a href="../../authopt.html">Authentication Options</a> for details - on how to use these. - <p><B>NOTE:</B> ntpd and ntp-keygen both use OpenSSL which requires a random - character file called .rnd by default. Both of these programs will automatically - generate this file if they are not found. The programs will look for an - environmental variable called RANDFILE and use that for the name of the - random character file if the variable exists. If it does not exist it will look for an environmental - variable called HOME and use that directory to search for a filed called .rnd - in that directory. Finally, if neither RANDFILE nor HOME exists it will look - in C:\ for a .rnd file. In each case it will search for and create the file - if the environmental variable exists or in the C:\ directory if it doesn't. - Note that ntpd normally runs as a service so that the only way that it will - have either RANDFILE or HOME defined is if it is a System environmental - variable or if the service is run under a specific account name and that - account has one of those variables defined. Otherwise it will use the file - "c:\.rnd". This was done so that OpenSSL will work normally on Win32 systems. - This obviates the need to ship the OpenSSL.exe file and explain how to - generate the .rnd file. A future version may change this behavior. - - <p>Refer to <a href="#Compiling">Compiling Requirements</a> and Instructions for how to compile the program.</p> - <h2>Reference Clocks</h2> - Reference clock support under Windows NT is tricky because the IO functions are - so much different. Some of the clock types have been built into the ntpd executable - and should work but have not been tested by the ntp project. If you have a clock - that runs on Win32 and the driver is there but not implemented on Win32 you will have - make the required configuration changes in config.h and then build ntpd from source - and test it. The following reference clocks are known to work and are supported - by Windows NT: - <p><a href="../../driver1.html">Type 1</a> Undisciplined Local Clock (LOCAL)<br> - <a href="../../driver29.html">Type 29</a> Trimble Navigation Palisade GPS (GPS_PALISADE)</p> - <h2>Functions Supported</h2> - All NTP functions are supported with some constraints. See the <a href="#ToDo">TODO list</a> below. - Note that the ntptrace executable is not supported and you should use the PERL script - version instead. - <h2>Accuracy</h2> - Greg Brackley has implemented a fantastic interpolation scheme that improves the precision of the NTP clock - using a realtime thread (is that poetic or what!) which captures a tick count from the 8253 counter after each - OS tick. The count is used to interpolate the time between operating system ticks. - <p>On a typical 200+ MHz system NTP achieves a precision of about 5 microseconds and synchronizes the clock - to +/-500 microseconds using the <a href="http://www.trimble.com/products/ntp">Trimble Palisade</a> as UTC reference. - This allows distributed applications to use the 10 milliseconds ticks available to them with high confidence.</p> - <h2>Binaries</h2> - Recent InstallShield based executable versions of NTP for Windows NT (intel) are available from: - <ul> - <li><a href="http://www.trimble.com/oem/ntp">http://www.trimble.com/oem/ntp</a> - <li><a href="http://www.five-ten-sg.com/">http://www.five-ten-sg.com/</a> - <li><a href="http://www.meinberg.de/english/sw/ntp.htm">http://www.meinberg.de/english/sw/ntp.htm</a> - </ul> - <a name="ToDo"><h2>ToDo</h2></a> - These tasks are in no particular order of priority. - <ul> - <li>Create a proper install/uninstall program - <li>Add sntp to the list of supported programs - <li>Add support for Visual C++ 7.0 or later (.NET) - <li>Add IPv6 support - <li>See if precision can be improved by using CPU cycle counter for tick interpolation. - <li>Make precision time available to applications using NTP_GETTIME API - </ul> - <h2>Compiling Requirements</h2> - <ul> - <li>Windows NT 4.0 Windows 2000, Windows XP, or Windows.NET Server 2003 - <li>Microsoft Visual C++ 6.0. <B>NOTE:</B> VC++ 7.0 (aka .NET) is not yet supported - but will probably work fine. - <li>Some way of uncompressing and untarring the gzipped tar file. - <li>OpenSSL must be built on the box before building NTP. Additional steps would - be required to not use OpenSSL. - </ul> - <a name="Compiling"><h2>Compiling Instructions</h2></a> - <ol> - <li>Unpack and build OpenSSL according to the OpenSSL instructions for building on - Windows. An environment variable named OPENSSL must be set up to specify the base path - of the OpenSSL directory to be used to build the NTP package - (e.g. <code>OPENSSL=C:\openssl-0.9.8b</code>). - <li>Unpack the ntp-*.tar.gz archive using utilities such as WinZip. - <li>Open the .\ports\winnt\ntp.dsw Visual C workspace - <li>Batch build all projects - <li>The built binaries can be found in the port\winnt\bin\Release subdirectory - <li>In addition you will need to install the OpenSSL libeay32.dll - <li>If you are shipping binaries in a kit it is strongly recommended that you - ship this file (winnt.html) along with the binaries. - </ol> - <h2>Configuration File</h2> - The default NTP configuration file path is %SystemRoot%<tt>\system32\drivers\etc\. </tt>(%SystemRoot% - is an environmental variable that can be determined by typing "set" at the "Command Prompt" - or from the "System" icon in the "Control Panel").<br> - Refer to your system environment and <tt>c</tt>reate your<tt> ntp.conf</tt> file in the directory - corresponding to your system installation.<br> - <tt>The older <WINDIR>\ntp.conf </tt>is still supported but you will get a log entry reporting that - the first file wasn't found. - <h2>Installation Instructions</h2> - The <tt>instsrv</tt> program in the instsrv subdirectory of the distribution can be used to install 'ntpd' as - a service and start automatically at boot time. Instsrv is automatically compiled with the rest of the distribution - if you followed the steps above. - <ol> - <li>Start a command prompt and enter "instsrv.exe <pathname_for_ntpd.exe>" - <li>Clicking on the "Services" icon in the "Control Panel" will display the list of - currently installed services in a dialog box. The NetworkTimeProtocol service should show up in this list. - Select it in the list and hit the "Start" button in the dialog box. The NTP service should start. - <li>You can also stop and start the service by typing net start|stop NetworkTimeProtocol at the DOS prompt. - <li>View the event log by clicking on the "Event Viewer" icon in the "Administrative Tools" - group, there should be several successful startup messages from NTP. NTP will keep running and restart - automatically when the machine is rebooted. - </ol> - You can change the start mode (automatic/manual) and other startup parameters corresponding to the NTP service - in the "Services" dialog box if you wish. - <h2>Removing NTP</h2> - You can also use <tt>instsrv</tt> to delete the NTP service by entering: "instsrv.exe remove" - <h2>Command Line Parameters and Registry Entries</h2> - Unlike the Unix environment, there is no clean way to run 'ntpdate' and reset the clock before starting 'ntpd' at boot time.<br> - NTP will step the clock up to 1000 seconds by default. While there is no reason that the system clock should be that much off - during bootup if 'ntpd' was running before, you may wish to override this default and/or pass other command line directives. - <p>Use the registry editor to edit the value for the ntpd executable under LocalMachine\System\CurrentControlSet\Services\NTP.</p> - <p>Add the -g option to the ImagePath key, behind "%INSTALLDIR>\ntpd.exe". This will force NTP to accept - large time errors (including 1.1.1980 00:00)</p> - <h2>Bug Reports</h2> - Send questions to <a href="news://comp.protocols.time.ntp">news://comp.protocols.time.ntp</a> - and bug reports should be entered in <a href="http://bugzilla.ntp.org/">Bugzilla</a> on the - NTP Web site. - <h2>Change Log</h2> - <h3>Last revision 2 July 2003 Version 4.2.0</h3> - <b>by Danny Mayer (mayer@ntp.org>)</b> - <h3>Significant Changes:</h3> - This latest release of NTP constitutes a major upgrade to its ability to build and - run on Windows platforms and should now build and run cleanly. More importantly it - is now able to support all authentication in the same way as Unix boxes. This does - require the usage of OpenSSL which is now a prerequisite for build on Windows. - ntp-keygen is now supported and builds on Win32 platforms. - - <h3>Last revision 16 February 1999 Version 4.0.99e.</h3> - <b>by Sven Dietrich (sven_dietrich@trimble.com)</b> - <p><b>Significant Changes:</b></p> - <ul> - <li>Perl 5 is no longer needed to compile NTP. The configuration script which creates version.c - with the current date and time was modified by Frederick Czajka [w2k@austin.rr.com] so that Perl - is no longer required. - </ul> - <h3>Last revision 15 November 1999 Version 4.0.98f.</h3> - <b>by Sven Dietrich (sven_dietrich@trimble.com)</b> - <p><b>Significant Changes:</b></p> - <ul> - <li>Fixed I/O problem delaying packet responses which resulted in no-replys to NTPQ and others. - <li>The default configuration file path is <tt><WINDIR>\system32\drivers\etc\ntp.conf. - The old <WINDIR>\ntp.conf </tt>is still supported but you will get a log entry reporting - that the first file wasn't found. The NTP 3.x legacy <tt>ntp.ini</tt> file is no longer supported. - </ul> - <b>Known Problems / TODO:</b> - <ul> - <li>MD5 and name resolution do not yet get along. If you define MD5, you cannot use DNS names, only IP numbers. - </ul> - <h3>Last revision 27 July 1999 Version 4.0.95.</h3> - This version compiles under WINNT with Visual C 6.0. - <p>Greg Brackley and Sven Dietrich</p> - <p>Significant changes:<br> - -Visual Studio v6.0 support<br> - -Winsock 2.0 support<br> - -Use of I/O completion ports for sockets and comm port I/O<br> - -Removed the use of multimedia timers (from ntpd, others need removing)<br> - -Use of waitable timers (with user mode APC) and performance counters to fake getting a better time<br> - -Trimble Palisade NTP Reference Clock support<br> - -General cleanup, prototyping of functions<br> - -Moved receiver buffer code to a separate module (removed unused members from the recvbuff struct)<br> - -Moved io signal code to a separate module</p> - <h3>Last revision: 20-Oct-1996</h3> - This version corrects problems with building the XNTP<br> - version 3.5-86 distribution under Windows NT. - <p>The following files were modified:<br> - blddbg.bat<br> - bldrel.bat<br> - include\ntp_machine.h<br> - xntpd\ntp_unixclock.c<br> - xntpd\ntp_refclock.c<br> - scripts\wininstall\build.bat<br> - scripts\wininstall\setup.rul<br> - scripts\wininstall\readme.nt<br> - scripts\wininstall\distrib\ntpog.wri<br> - html\hints\winnt (this file)</p> - <p>In order to build the entire Windows NT distribution you<br> - need to modify the file scripts\wininstall\build.bat<br> - with the installation directory of the InstallShield<br> - software. Then, simply type "bldrel" for non-debug<br> - or "blddbg" for debug executables.</p> - <p>Greg Schueman<br> - <schueman@acm.org></p> - <h3>Last revision: 07-May-1996</h3> - This set of changes fixes all known bugs, and it includes<br> - several major enhancements. - <p>Many changes have been made both to the build environment as<br> - well as the code. There is no longer an ntp.mak file, instead<br> - there is a buildntall.bat file that will build the entire<br> - release in one shot. The batch file requires Perl. Perl<br> - is easily available from the NT Resource Kit or on the Net.</p> - <p>The multiple interface support was adapted from Larry Kahn's<br> - work on the BIND NT port. I have not been able to test it<br> - adequately as I only have NT servers with one network<br> - interfaces on which to test.</p> - <p>Enhancements:<br> - * Event Logging now works correctly.<br> - * Version numbers now work (requires Perl during build)<br> - * Support for multiple network interface cards (untested)<br> - * NTP.CONF now default, but supports ntp.ini if not found<br> - * Installation procedure automated.<br> - * All paths now allow environment variables such as %windir%</p> - <p>Bug fixes:<br> - * INSTSRV replaced, works correctly<br> - * Cleaned up many warnings<br> - * Corrected use of an uninitialized variable in XNTPD<br> - * Fixed ntpdate -b option<br> - * Fixed ntpdate to accept names as well as IP addresses<br> - (Winsock WSAStartup was called after a gethostbyname())<br> - * Fixed problem with "longjmp" in xntpdc/ntpdc.c that<br> - caused a software exception on doing a Control-C in xntpdc.<br> - A Cntrl-C now terminates the program.</p> - <p>See below for more detail:</p> - <p> Note: SIGINT is not supported for any Win32 application including<br> - Windows NT and Windows 95. When a CTRL+C interrupt occurs, Win32<br> - operating systems generate a new thread to specifically handle that<br> - interrupt. This can cause a single-thread application such as UNIX,<br> - to become multithreaded, resulting in unexpected behavior.<br> - </p> - <p>Possible enhancements and things left to do:<br> - * Reference clock drivers for NT (at least Local Clock support)<br> - * Control Panel Applet<br> - * InstallShield based installation, like NT BIND has<br> - * Integration with NT Performance Monitor<br> - * SNMP integration<br> - * Fully test multiple interface support<br> - </p> - <p>Known problems:<br> - * bug in ntptrace - if no Stratum 1 servers are available,<br> - such as on an - IntraNet, the application crashes.</p> - <h3>Last revision: 12-Apr-1995</h3> - This NTPv3 distribution includes a sample configuration file and the project<br> - makefiles for WindowsNT 3.5 platform using Microsoft Visual C++ 2.0 compiler.<br> - Also included is a small routine to install the NTP daemon as a "service"<br> - on a WindowsNT box. Besides xntpd, the utilities that have been ported are<br> - ntpdate and xntpdc. The port to WindowsNT 3.5 has been tested using a Bancomm<br> - TimeServe2000 GPS receiver clock that acts as a strata 1 NTP server with no<br> - authentication (it has not been tested with any refclock drivers compiled in).<br> - Following are the known flaws in this port:<br> - 1) currently, I do not know of a way in NT to get information about multiple<br> - network interface cards. The current port uses just one socket bound to<br> - INADDR_ANY address. Therefore when dealing with a multihomed NT time server,<br> - clients should point to the default address on the server (otherwise the<br> - reply is not guaranteed to come from the same interface to which the<br> - request was sent). Working with Microsoft to get this resolved.<br> - 2) There is some problem with "longjmp" in xntpdc/ntpdc.c that causes a<br> - software exception on doing a Control-C in xntpdc. Be patient!<br> - 3) The error messages logged by xntpd currently contain only the numerical<br> - error code. Corresponding error message string has to be looked up in<br> - "Books Online" on Visual C++ 2.0 under the topic "Numerical List of Error<br> - Codes". - <p>Last HTML Update: November 17, 1999<br> - <a href="mailto://sven_dietrich@trimble.com">Sven_Dietrich@Trimble.COM</a></p> - </body> - -</html> diff --git a/contrib/ntp/html/build/patches.html b/contrib/ntp/html/build/patches.html deleted file mode 100644 index 00b2923..0000000 --- a/contrib/ntp/html/build/patches.html +++ /dev/null @@ -1,36 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <title>Patching Procedures</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Patching Procedures</h3> - <img src="../pic/alice38.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html"> rom <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> - <p>The Mad Hatter needs patches.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="99">12:56 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="266">Saturday, March 20, 2004</csobj></p> - <br clear="left"> - <hr> - <p>A distribution so widely used as this one eventually develops numerous barnacles as the result of <a href="porting.html">porting</a> to new systems, idiosyncratic new features and just plain bugs. In order to help keep order and make maintenance bearable, we ask that proposed changes to the distribution be submitted in the following form.</p> - <ol> - <li>Please submit patches to <a href="mailto:bugs@mail.ntp.org">bugs@mail.ntp.org</a> in the form of either unified-diffs (<tt>diff -u</tt>) or context-diffs (<tt>diff -c</tt>). - <li>Please include the <strong>output</strong> from <tt>config.guess</tt> in the description of your patch. If <tt>config.guess</tt> does not produce any output for your machine, please fix that, too! - <li>Please base the patch on the root directory of the distribution. The preferred procedure here is to copy your patch to the root directory and mumble - <p><tt>patch -p <your_patch></tt></p> - <li>Please avoid patching the RCS subdirectories; better yet, clean them out before submitting patches. - <li>If you have whole new files, as well as patches, wrap the files and patches in a shell script. If you need to compress it, use either GNU <tt>gzip</tt> or the stock Unix <tt>compress</tt> utility. - <li>Don't forget the documentation that may be affected by the patch. Send us patches for the <tt>./htm</tt> files as well. - <li>We would be glad to include your name, electric address and descriptive phrase in the <a href="../copyright.html">Copyright</a> page, if you wish. - </ol> - <p>Prior to ntp3-5.83 (releases up to and including ntp3.5f) a complete patch history back to the dark ages was kept in the <tt>./patches</tt> directory, which might have been helpful to see if the same problem occurred in another port, etc. Patches were saved in that directory with file name in the form <tt>patch.<i>nnn</i></tt>, where <i>nnn</i> was approaching 200. All patches in that directory have been made; so, if yours was there, it was in the distribution.</p> - <p>Since we have been getting multple patches for some bugs, plus many changes are implemented locally, no two maintainers here use the same tools, and since we're not using any bug-tracking software or even source code control, there is currently no tracking of specific changes.</p> - <p>The best way to see what's changed between two distributions is to run a <tt>diff</tt> against them.</p> - <p>Thanks for your contribution and happy chime.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html> diff --git a/contrib/ntp/html/build/porting.html b/contrib/ntp/html/build/porting.html deleted file mode 100644 index 976cc66..0000000 --- a/contrib/ntp/html/build/porting.html +++ /dev/null @@ -1,40 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <title>Porting Hints</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Porting Hints</h3> - <img src="../pic/wingdorothy.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>Porting Dorothy in Oz - </p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="99">12:56 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="266">Saturday, March 20, 2004</csobj></p> - <br clear="left"> - <hr> - <p>NOTE: The following procedures have been replaced by GNU <tt>automake</tt> and <tt>autoconfigure</tt>. This page is to be updated in the next release.</p> - <p>Porting to a new machine or operating system ordinarily requires updating the <tt>./machines</tt> directory and the <tt>./compilers</tt> directories in order to define the build environment and autoconfigure means. You will probably have to modify the <tt>ntp_machines.h</tt> file and <tt>"l_stdlib.h"</tt> files as well. The two most famous trouble spots are the I/O code in <tt>./ntpd/ntp_io.c</tt> and the clock adjustment code in <tt>./ntpd/ntp_unixclock.c</tt>.</p> - <p>These are the rules so that older bsd systems and the POSIX standard system can coexist together.</p> - <ol> - <li>If you use <tt>select</tt> then include <tt>"ntp_select.h"</tt>. <tt>select</tt> is not standard, since it is very system dependent as to where it is defined. The logic to include the right system dependent include file is in <tt>"ntp_select.h"</tt>. - <li>Always use POSIX definition of strings. Include <tt>"ntp_string.h"</tt> instead of <tt><string.h></tt>. - <li>Always include <tt>"ntp_malloc.h"</tt> if you use <tt>malloc</tt>. - <li>Always include <tt>"ntp_io.h"</tt> instead of <tt><sys/file.h></tt> or <tt><fnctl.h></tt> to get <tt>O_*</tt> flags. - <li>Always include <tt>"ntp_if.h"</tt> instead of <tt><net/if.h></tt>. - <li>Always include <tt>"ntp_stdlib.h"</tt> instead of <tt><stdlib.h></tt>. - <li>Define any special defines needed for a system in <tt>./include/ntp_machine.h</tt> based on system identifier. This file is included by the <tt>"ntp_types.h"</tt> file and should always be placed first after the <tt><></tt> defines. - <li>Define any special library prototypes left over from the system library and include files in the <tt>"l_stdlib.h"</tt> file. This file is included by the <tt>"ntp_stdlib.h"</tt> file and should ordinarily be placed last in the includes list. - <li>Don't define a include file by the same name as a system include file. - </ol> - <p><tt>"l_stdlib.h"</tt> can contain any extra definitions that are needed so that <tt>gcc</tt> will shut up. They should be controlled by a system identifier and there should be a separate section for each system. Really this will make it easier to maintain.</p> - <p>See <tt>include/ntp_machines.h</tt> for the various compile time options.</p> - <p>When you are satisfied the port works and that other ports are not adversely affected, please send <a href="patches.html">patches</a> for the system files you have changed, as well as any documentation that should be updated, including the advice herein.</p> - <p>Good luck.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/build/quick.html b/contrib/ntp/html/build/quick.html deleted file mode 100644 index 1693b5d..0000000 --- a/contrib/ntp/html/build/quick.html +++ /dev/null @@ -1,30 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> - -<html> - - <head> - <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.pdf">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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="99">01:01 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="266">Saturday, March 20, 2004</csobj></p> - <br clear="left"> - <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 that needs to be done 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 require one. The file, called by default <tt>/etc/ntp.conf</tt>, need only contain one line 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. There are about two dozen public time servers operated by National Institutes of Science and Technology (NIST), US Naval Observatory (USNO), Canadian Metrology Centre (CMC) and many others available on the Internet. Lists of public primary and secondary NTP servers maintained on the <a href="http://www.eecis.udel.edu/%7emills/ntp/servers.html">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 writes the current value to a file called by default <tt>/etc/ntp.drift</tt>. If <tt>ntpd</tt> is stopped and restarted, it initializes the frequency from this file. In this way the potentially lengthy interval to relearn the frequency error is avoided.</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. 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 detected errors, if present.</p> - <p>Sometimes the <tt>ntpd</tt>. behavior may seem to violate the Principle of Least Astonishment, but there are good reasons for this. See the <a href="../ntpd.html">Network Time Protocol (NTP) daemon</a> page for revealing insights. See this page and its dependencies for additional configuration and control options. The <a href="../notes.html">Notes on Configuring NTP and Setting up a NTP Subnet</a> page contains an extended discussion of these options.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/footer.txt b/contrib/ntp/html/build/scripts/footer.txt deleted file mode 100644 index 89216ce..0000000 --- a/contrib/ntp/html/build/scripts/footer.txt +++ /dev/null @@ -1,7 +0,0 @@ -document.write("\ -<table><tr>\ -<td width='50%' ><img src='../icons/home.gif' align='middle' alt='gif'>\ -<a href='../index.html'>Home Page</a></td>\ -<td width='50%' ><img src='../icons/mail2.gif' align='middle' alt='gif'>\ -<a href='http://www.ntp.org/contact.html'>Contacts</a></i></td>\ -</tr></table>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/links10.txt b/contrib/ntp/html/build/scripts/links10.txt deleted file mode 100644 index 7bf9d06..0000000 --- a/contrib/ntp/html/build/scripts/links10.txt +++ /dev/null @@ -1,5 +0,0 @@ -document.write("<ul>\ -<li class='inline'><a href='refclock.html'>Reference Clock Drivers</a><br>\ -<li class='inline'><a href='prefer.html'>Mitigation Rules and the <tt>prefer</tt> Keyword</a><br>\ -<li class='inline'><a href='howto.html'>How to Write a Reference Clock Driver</a><br>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/links11.txt b/contrib/ntp/html/build/scripts/links11.txt deleted file mode 100644 index 1fce362..0000000 --- a/contrib/ntp/html/build/scripts/links11.txt +++ /dev/null @@ -1,5 +0,0 @@ -document.write("<ul>\ -<li class='inline'><a href='refclock.html'>Reference Clock Drivers</a><br>\ -<li class='inline'><a href='pps.html'>Pulse-per-second (PPS) Signal Interfacing</a><br>\ -<li class='inline'><a href='ldisc.html'>Line Disciplines and Streams Modules</a><br>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/links12.txt b/contrib/ntp/html/build/scripts/links12.txt deleted file mode 100644 index 512cbcf..0000000 --- a/contrib/ntp/html/build/scripts/links12.txt +++ /dev/null @@ -1,5 +0,0 @@ -document.write("<ul>\ -<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='msyslog.html'><tt>ntpd</tt> System Log Messages</a><br>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/links7.txt b/contrib/ntp/html/build/scripts/links7.txt deleted file mode 100644 index 4a6f186..0000000 --- a/contrib/ntp/html/build/scripts/links7.txt +++ /dev/null @@ -1,5 +0,0 @@ -document.write("<ul>\ -<li class='inline'><a href='../confopt.html'>Server 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>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/links8.txt b/contrib/ntp/html/build/scripts/links8.txt deleted file mode 100644 index af33dca..0000000 --- a/contrib/ntp/html/build/scripts/links8.txt +++ /dev/null @@ -1,6 +0,0 @@ -document.write("<ul>\ -<li class='inline'><a href='refclock.html'>Reference Clock 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>\ -<li class='inline'><a href='drivers/driver6.html'>IRIG Audio Decoder</a>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/links9.txt b/contrib/ntp/html/build/scripts/links9.txt deleted file mode 100644 index 38ffe90..0000000 --- a/contrib/ntp/html/build/scripts/links9.txt +++ /dev/null @@ -1,7 +0,0 @@ -document.write("<ul>\ -<li class='inline'><a href='authopt.html'>Authentication Options</a><br>\ -<li class='inline'><a href='manyopt.html'>Automatic NTP Configuration Options</a><br>\ -<li class='inline'><a href='confopt.html'>Server Options</a><br>\ -<li class='inline'><a href='keygen.html'><tt>ntp-keygen</tt> - generate public and private keys</a>\ -<li class='inline'><a href='http://www.eecis.udel.edu/~mills/autokey.html'>Autonomous Authentication</a>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/build/scripts/style.css b/contrib/ntp/html/build/scripts/style.css deleted file mode 100644 index 096b18a..0000000 --- a/contrib/ntp/html/build/scripts/style.css +++ /dev/null @@ -1,64 +0,0 @@ -body {background: #FDF1E1; - color: #006600; - font-family: "verdana", sans-serif; - text-align: justify; - margin-left: 5px;} - -p, h4, hr, li {margin-top: .6em; margin-bottom: .6em} -li.inline {text-align: left; margin-top: 0; margin-bottom: 0} - -ul, dl, ol, {margin-top: .6em; margin-bottom: .6em; margin-left 5em} - -dt {margin-top: .6em} -dd {margin-bottom: .6em} - -div.header {text-align: center; - font-style: italic;} - -div.footer {text-align: center; - font-size: 60%;} - -img.cell {align: left;} - -td.sidebar {width: 40px; align: center; valign: top;} -img.sidebar {align: center; margin-top: 5px;} -h4.sidebar {align: center;} - -p.top {background: #FDF1E1; - color: #006600; - position: absolute; - margin-left: -90px; - text-align: center;} - -a:link.sidebar {background: transparent; - color: #990033; - font-weight: bold;} - -a:visited.sidebar {background: transparent; - color: #990033; - font-weight: bold;} - -a:hover.sidebar {background: #FDF1E1; - color: #006600;} - -img {margin: 5px;} - -div {text-align: center;} - -h1 {text-align: center; - font-size: 250%;} - -caption {background: #EEEEEE; - color: #339999;} - -tx {text-align: center;} - -th {background: #FFFFCC; - color: #006600; - text-align: center; - text-decoration: underline; - padding-top: 5px;} - -th.caption {background: #EEEEEE; - color: #006600; - text-align: center;}
\ No newline at end of file diff --git a/contrib/ntp/html/clock.html b/contrib/ntp/html/clock.html new file mode 100644 index 0000000..32f3ed8 --- /dev/null +++ b/contrib/ntp/html/clock.html @@ -0,0 +1,65 @@ +<!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 -->4-Aug-2011 23:40<!-- #EndDate --> + UTC</p> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#intro">General Overview</a></li> + <li class="inline"><a href="#panic">Panic Threshold</a></li> + <li class="inline"><a href="#step">Step and Stepout Thresholds</a></li> + <li class="inline"><a href="#hold">Hold Timer</a></li> + <li class="inline"><a href="#inter">Operating Intervals</a></li> + <li class="inline"><a href="#state">State Transition Function</a></li> +</ul> +<hr> +<h4 id="intro">General Overview</h4> +<p>In the NTPv4 specification and reference implementation a state machine is used to manage the system clock under exceptional conditions, as when the daemon is first started or when encountering severe network congestion. This page describes the design and operation of the state machine in detail.</p> +<p> The state machine is activated upon receipt of an update by the clock discipline algorithm. its primary purpose is to determines whether the clock is slewed or stepped and how the initial time and frequency are determined using three thresholds: <em>panic</em>, <em>step</em> and <em>stepout</em>, and one timer: <em>hold</em>.</p> +<h4 id="panic">Panic Threshold</h4> +<p>Most computers today incorporate a time-of-year (TOY) chip to maintain the time when the power is off. When the computer is restarted, the chip is used to initialize the operating system time. In case there is no TOY chip or the TOY time is different from NTP time by more than the panic threshold, the daemon <tt></tt> assumes something must be terribly wrong, so exits with a message to the system operator to set the time manually. With the <tt>-g</tt> option on the command line, the daemon sets the clock to NTP time at the first update, but exits if the offset exceeds the panic threshold at subsequent updates. The panic threshold default is 1000 s, but it can be changed with the <tt>panic</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> +<h4 id="step"> Step and Stepout Thresholds</h4> +<p>Under ordinary conditions, the clock discipline gradually slews the clock to the correct time, so that the time is effectively continuous and never stepped forward or backward. If, due to extreme network congestion, an offset spike exceeds the step threshold, by default 128 ms, the spike is discarded. However, if offset spikes greater than the step threshold persist for an interval more than the stepout threshold, by default 300 s, the system clock is stepped to the correct time.</p> +<p> In practice, the need for a step has been extremely rare and almost always the result of a hardware failure or operator error. The step threshold and stepout threshold can be changed using the <tt>step</tt> and <tt>stepout</tt> options of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command, respectively. If the step threshold is set to zero, the step function is entirely disabled and the clock is always slewed. The daemon sets the step threshold to 600 s using the <tt>-x</tt> option on the command line. If the <tt>-g</tt> option is used or the step threshold is set greater than 0.5 s, the precision time kernel support is disabled.</p> +<p>Historically, the most important application of the step function was when a leap second was inserted in the Coordinated Universal Time (UTC) timescale and the kernel precision time support was not available. This also happened with older reference clocks that indicated an impending leap second, but the radio itself did not respond until it resynchronized some minutes later. Further details are on the <a href="leap.html">Leap Second Processing</a> page.</p> +<p>In some applications the clock can never be set backward, even it accidentally set forward a week by some evil means. The issues should be carefully considered before using these options. The slew rate is fixed at 500 parts-per-million (PPM) by the Unix kernel. As a result, the clock can take 33 minutes to amortize each second the clock is outside the acceptable range. During this interval the clock will not be consistent with any other network clock and the system cannot be used for distributed applications that require correctly synchronized network time.</p> +<h4 id="hold">Hold Timer</h4> +<p>When the daemon is started after a considerable downtime, it could be the TOY chip clock has drifted significantly from NTP time. This can cause a transient at system startup. In the past, this has produced a phase transient and resulted in a frequency surge that could take some time, even hours, to subside. When the highest accuracy is required, some means is necessary to manage the startup process so that the the clock is quickly set correctly and the frequency is undisturbed. The hold timer is used to suppress frequency adjustments during the training and startup intervals described below. At the beginning of the interval the hold timer is set to the stepout threshold and decrements at one second intervals until reaching zero. However, the hold timer is forced to zero if the residual clock offset is less than 0.5 ms. When nonzero, the discipline algorithm uses a small time constant (equivalent to a poll exponent of 2), but does not adjust the frequency. Assuming that the frequency has been set to within 1 PPM, either from the frequency file or by the training interval described later, the clock is set to within 0.5 ms in less than 300 s.</p> +<h4 id="inter">Operating Intervals</h4> +<p>The state machine operates in one of four nonoverlapping intervals.</p> +<dl> + <dt>Training interval</dt> + <dd>This interval is used at startup when the frequency file is nor present at startup. It begins when the first update is received by the discipline algorithm and ends when an update is received following the stepout threshold. The clock phase is steered to the offset presented at the beginning of the interval, but without affecting the frequency. During the interval further updates are ignored. At the end of the interval the frequency is calculated as the phase change during the interval divided by the length of the interval. This generally results in a frequency error less than 0.5 PPM. Note that, if the intrinsic oscillator frequency error is large, the offset will in general have significant error. This is corrected during the subsequent startup interval.</dd> + <dt>Startup interval</dt> + <dd> This interval is used at startup to amortize the residual offset while not affecting the frequency. If the frequency file is present, it begins when the first update is received by the discipline. If not, it begins after the training interval. It ends when the hold timer decrements to zero or when the residual offset falls below 0.5 ms.</dd> + <dt>Step interval</dt> + <dd>This interval is used as a spike blanker during periods when the offsets exceed the step threshold. The interval continues as long as offsets are received that are greater than the step threshold, but ends when either an offset is received less than the step threshold or until the time since the last valid update exceeds the stepout threshold.</dd> + <dt>Sync Interval</dt> + <dd> This interval is implicit; that is, it is used when none of the above intervals are used.</dd> +</dl> +<h4 id="state">State Transition Function</h4> +<p>The state machine consists of five states. An event is created when an update is received by the discipline algorithm. Depending on the state and the the offset magnitude, the machine performs some actions and transitions to the same or another state. Following is a short description of the states.</p> +<dl> + <dt>FSET - The frequency file is present</dt> + <dd> Load the frequency file, initialize the hold timer and continue in SYNC state.</dd> + <dt>NSET - The frequency file is not present</dt> + <dd>Initialize the hold timer and continue in FREQ state.</dd> + <dt>FREQ - Frequency training state</dt> + <dd>Disable the clock discipline until the time since the last update exceeds the stepout threshold. When this happens, calculate the frequency, initialize the hold counter and transition to SYNC state.</dd> + <dt>SPIK - Spike state</dt> + <dd>A update greater than the step threshold has occurred. Ignore the update and continue in this state as long as updates greater than the step threshold occur. If a valid update is received, continue in SYNC state. When the time since the last valid update was received exceeds the stepout threshold, step the system clock and continue in SYNC state. </dd> + <dt>SYNC - Ordinary clock discipline state</dt> + <dd>Discipline the system clock time and frequency using the hybrid phase/frequency feedback loop. However, do not discipline the frequency if the hold timer is nonzero.</dd> +</dl> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/clockopt.html b/contrib/ntp/html/clockopt.html index c4690a3..0fe4c24 100644 --- a/contrib/ntp/html/clockopt.html +++ b/contrib/ntp/html/clockopt.html @@ -1,68 +1,59 @@ <!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"> - <p>See the radios, all in a row.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:37</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.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. Many drivers support special line discipline/streams modules which can significantly improve the accuracy using the driver. These are described in the <a href="ldisc.html">Line Disciplines and Streams Drivers</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><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><tt>fudge 127.127.<i>t.u</i> [time1 <i>sec</i>] [time2 <i>sec</i>] [stratum <i>int</i>] [refid <i>string</i>] [mode <i>int</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>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>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> - +<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 -->11-Sep-2010 05:55<!-- #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> +<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 17 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> diff --git a/contrib/ntp/html/cluster.html b/contrib/ntp/html/cluster.html new file mode 100644 index 0000000..3132a46 --- /dev/null +++ b/contrib/ntp/html/cluster.html @@ -0,0 +1,32 @@ +<!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 Cluster Algorithm</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<em></em> +<h3>Clock Cluster Algorithm</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->15-Nov-2012 06:02<!-- #EndDate --> + UTC</p> +<hr> +<p>The clock cluster algorithm processes the truechimers produced by the clock select algorithm to produce a list of <em>survivors</em>. These survivors are used by the mitigation algorithms to discipline the system clock. The cluster algorithm operates in a series of rounds, where at each round the truechimer furthest from the offset centroid is pruned from the population. The rounds are continued until a specified termination condition is met. This page discusses the algorithm in detail.</p> +<p>First, the truechimer associations are saved on an unordered list with each candidate entry identified with index <em>i</em> (<em>i </em>= 1, ..., <em>n)</em>, where <em>n</em> is the number of candidates. Let θ(<em>i</em>), be the offset and λ(<em>i</em>) be the root distance of the <em>i</em>th entry. Recall that the root distance is equal to the root dispersion plus half the root delay. For the <em>i</em>th candidate on the list, a statistic called the <em>select jitter</em> relative to the <em>i</em>th candidate is calculated as follows. Let</p> +<div align="center"> + <p><em>d<sub>i</sub></em>(<em>j</em>) = |θ(<em>j</em>) − θ(<em>i</em>)| λ(<em>i</em>),</p> +</div> +<p> where θ(<em>i)</em> is the peer offset of the <em>i</em>th entry and θ(<em>j</em>) is the peer offset of the <em>j</em>th entry, both produced by the clock filter algorithm. The metric used by the cluster algorithm is the select jitter φ<sub>S</sub>(<em>i</em>) computed as the root mean square (RMS) of the <em>d<sub>i</sub></em>(<em>j</em>) as <em>j</em> ranges from 1 to <em>n</em>. <em> </em>For the purpose of notation in the example to follow, let φ<sub>R</sub>(<em>i</em>) be the peer jitter computed by the clock filter algorithm for the <em>i</em>th candidate.</p> +<p>The object at each round is to prune the entry with the largest metric until the termination condition is met. Note that the select jitter must be recomputed at each round, but the peer jitter does not change. At each round the remaining entries on the list represent the survivors of that round. If the candidate to be pruned is preemptable and the number of candidates is greater than the <em>maxclock threshold</em>, the association is demobilized. This is useful in the schemes described on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. The maxclock threshold default is 10, but it can be changed using the <tt>maxclock</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. Further pruning is subject to the following termination conditions, but no associations will be automatically demobilized.</p> +<p>The termination condition has two parts. First, if the number of survivors is not greater than the<em> </em><em>minclock threshold</em> set by the <tt>minclock</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, the pruning process terminates. The<tt> minclock</tt> default is 3, but can be changed to fit special conditions, as described on the <a href="prefer.html">Mitigation Rules and the prefer Keyword</a> page.</p> +<div align="center"><img src="pic/flt7.gif" alt="gif"> + <p>Figure 1. Cluster Algorithm</p> +</div> +<p>The second termination condition is more intricate. Figure 1 shows a round where a candidate of (a) is pruned to yield the candidates of (b). Let φ<sub><em>max</em></sub> be the maximum select jitter and φ<sub><em>min</em></sub> be the minimum peer jitter over all candidates on the list. In (a), candidate 1 has the highest select jitter, so φ<sub><em>max</em></sub> = φ<sub>S</sub>(1). Candidate 4 has the lowest peer jitter, so φ<sub><em>min</em></sub> = φ<sub>R</sub>(4). Since φ<sub><em>max</em></sub> > φ<sub><em>min</em></sub>, select jitter dominates peer jitter,the algorithm prunes candidate 1. In (b), φ<sub><em>max</em></sub> = φ<sub>S</sub>(3) and φ<sub><em>min </em></sub>=φ<sub>R</sub>(4). Since φ<sub><em>max</em></sub> < φ<sub><em>min</em></sub>, pruning additional candidates does not reduce select jitter, the algorithm terminates with candidates 2, 3 and 4 as survivors.</p> +<p>The survivor list is passed on to the the mitigation algorithms, which combine the survivors, select a system peer, and compute the system statistics passed on to dependent clients. Note the use of root distance λ as a weight factor at each round in the clock cluster algorithm. This is to favor the survivors with the lowest root distance and thus the smallest maximum error.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/comdex.html b/contrib/ntp/html/comdex.html new file mode 100644 index 0000000..0d632f1 --- /dev/null +++ b/contrib/ntp/html/comdex.html @@ -0,0 +1,29 @@ +<!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 -->31-Jan-2014 06:54<!-- #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/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> +<!-- <hr> --> +<!-- <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> --> +</body> +</html> diff --git a/contrib/ntp/html/config.html b/contrib/ntp/html/config.html new file mode 100644 index 0000000..ae68c89 --- /dev/null +++ b/contrib/ntp/html/config.html @@ -0,0 +1,40 @@ +<!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>Build Options</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> + + <body> + <h3>Build Options</h3> + <img src="pic/pogo3a.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a> + <p>Gnu autoconfigure tools are in the backpack.</p> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 04:59<!-- #EndDate --> + UTC</p> +<br clear="left"> + <hr> + <p>Most modern software distributions include an autoconfigure utility which + customizes the build and install configuration according to the specific + hardware, operating system and file system conventions. For NTP this + utility is called <tt>configure</tt>, which is run before building and installing + the program components. For most installations no additional actions + are required other than running <tt>configure</tt> with no options. + However, it is possible to customize the build and install configuration + through the use of <tt>configure</tt> options.</p> + <p>The available options, together with + a concise description, can be displayed by running <tt>configure</tt> with + the <tt>--help</tt> option. Various options can be used to reduce the memory + footprint, adjust the scheduling priority, enable or disable debugging + support or reference clock driver support. The options can be used + to specify where to install the program components or where to find + various libraries if they are not in the default place.</p> +<hr> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body> + +</html> diff --git a/contrib/ntp/html/confopt.html b/contrib/ntp/html/confopt.html index e2a04c4..b964d24 100644 --- a/contrib/ntp/html/confopt.html +++ b/contrib/ntp/html/confopt.html @@ -1,82 +1,105 @@ <!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>Server Options</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Server 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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:57</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="270">Monday, October 10, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#cfg">Configuration Commands</a> - <li class="inline"><a href="#opt">Command Options</a> - <li class="inline"><a href="#aux">Auxilliary Commands</a> - <li class="inline"><a href="#bug">Bugs</a> - </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> - <h4 id="cfg">Configuration Commands</h4> - <p>The various modes are determined by the command keyword and the required IP address. Addresses are classed by type as (s) a remote server or peer (IPv4 class A, B and C), (b) the broadcast address of a local interface, (m) a multicast address (IPv4 class D), or (r) a reference clock address (127.127.x.x). The options that can be used with these commands are listed below.</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 support of the 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> - <p>There are three types of associations: 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>prempt</tt> flag and are demobilized by timeout or error. Ephemeral associations are mobilized upon arrival of designated messages and demobilized by timeout or error.</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>Server Commands and Options</title> +<!-- Changed by: Harlan &, 31-Jan-2014 --> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<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 -->10-Mar-2014 05:01<!-- #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/confopt.txt"></script> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#address">Server and Peer Addresses</a></li> + <li class="inline"><a href="#command">Server Commands</a></li> + <li class="inline"><a href="#option">Server Command Options</a></li> +</ul> +<hr> +<h4 id="address">Server and Peer Addresses</h4> +<p>Following is a description of the server 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 auxiliary commands that specify environment 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 or IPv6), (b) the IPv4 broadcast address of a local interface, (m) a multicast address (IPv4 class D or IPv6), 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="command">Server Commands</h4> +<p>Unless noted otherwise, further information about these commands 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> + <tt>manycastclient <i>address</i> [options ...]</tt><br> + <tt>pool <i>address</i> [options ...]</tt><br> + <tt>unpeer [<i>address</i> | <i>associd</i>]</tt></dt> + <dd>These commands specify the remote server name or address to be used and the mode in which to operate. The <i>address</i> can be either a DNS name or a IPv4 or IPv6 address in standard notation. In general, multiple commands of each type can be used for different server and peer addresses or multicast groups. <dl> - <dt><tt>server <i>address</i> [options ...]</tt><br> - <tt>peer <i>address</i> [</tt><tt>options ...]<br> - broadcast <i>address</i> [options ...]</tt><br> - <tt>manycastclient <i>address</i> [options ...]</tt> - <dd>These four commands specify the time server name or address to be used and the mode in which to operate. The <i>address</i> can be either a DNS name or a IP address in dotted-quad notation. Additional information on association behavior can be found in the <a href="assoc.html">Association Management</a> page. - <dl> - <dt><tt>server</tt> - <dd>For type s and r addresses (only), this command normally mobilizes a persistent client mode association with the specified remote server or local reference clock. If the <tt>preempt</tt> flag is specified, a preemptable association is mobilized instead. In client mode the client clock can synchronize to the remote server or local reference clock, but the remote server can never be synchronized to the client clock. This command should NOT be used for type <tt>b</tt> or <tt>m</tt> addresses. <dt><tt>peer</tt> - <dd>For type s addresses (only), this command mobilizes a persistent symmetric-active mode association with the specified remote peer. In this mode the local clock can be synchronized to the remote peer or the remote peer can be synchronized to the local clock. This is useful in a network of servers where, depending on various failure scenarios, either the local or remote peer may be the better source of time. This command should NOT be used for type <tt>b</tt>, <tt>m</tt> or <tt>r</tt> addresses. - <dt><tt>broadcast</tt> - <dd>For type <tt>b</tt> and <tt>m</tt> addresses (only), this command mobilizes a persistent broadcast mode association. Multiple commands can be used to specify multiple local broadcast interfaces (subnets) and/or multiple multicast groups. Note that local broadcast messages go only to the interface associated with the subnet specified, but multicast messages go to all interfaces. - <dd>In broadcast mode the local server sends periodic broadcast messages to a client population at the <i><tt>address</tt></i> specified, which is usually the broadcast address on (one of) the local network(s) or a multicast address assigned to NTP. 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 to contain the messages within administrative boundaries. Ordinarily, this specification applies only to the local server operating as a sender; for operation as a broadcast client, see the <tt>broadcastclient</tt> or <tt>multicastclient</tt> commands below. - <dt><tt>manycastclient</tt> - <dd>For type <tt>m</tt> addresses (only), this command mobilizes a preemptable manycast client mode association for the multicast group address specified. In this mode a specific address must be supplied which matches the address used on the <tt>manycastserver</tt> command for the designated manycast servers. The NTP multicast address 224.0.1.1 assigned by the IANA should NOT be used, unless specific means are taken to avoid spraying large areas of the Internet with these messages and causing a possibly massive implosion of replies at the sender. - <dd>The <tt>manycastclient</tt> command specifies that the host is to operate in client mode with the remote servers that are discovered as the result of broadcast/multicast messages. The client broadcasts a request message to the group address associated with the specified <i><tt>address</tt></i> and specifically enabled servers respond to these messages. The client selects the servers providing the best time and continues as with the <tt>server </tt>command. The remaining servers are discarded as if never heard. - </dl> - </dl> - <h4 id="opt">Command Options</h4> - <dl> - <dt><tt>autokey</tt> - <dd>All packets sent to and received from the server or peer are to include authentication fields encrypted using the autokey scheme described in the <a href="authopt.html">Authentication Options</a> page. This option is valid with all commands.<dt><tt>burst</tt> - <dd>When the server is reachable, send a burst of eight packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the <a href="miscopt.html"><tt>calldelay</tt></a> command to allow additional time for a modem or ISDN call to complete. This option is valid with only the <tt>server</tt> command and is a recommended option with this command when the <tt>maxpoll</tt> option is 11 or greater. <dt><tt>iburst</tt> - <dd>When the server is unreachable, send a burst of eight packets instead of the usual one. The packet spacing is normally 2 s; however, the spacing between the first and second packets can be changed with the <a href="miscopt.html"><tt>calldelay</tt></a> command to allow additional time for a modem or ISDN call to complete. This option is valid with only the <tt>server</tt> command and is a recommended option with this command.<dt><tt>key</tt> <i><tt>key</tt></i> - <dd>All packets sent to and received from the server or peer are to include authentication fields encrypted using the specified <i><tt>key</tt></i> identifier with values from 1 to 65534, inclusive. The default is to include no encryption field. This option is valid with all commands.<dt><tt>minpoll <i>minpoll</i></tt><br> - <tt>maxpoll <i>maxpoll</i></tt> - <dd>These options specify the minimum and maximum poll intervals for NTP messages, in seconds as a power of two. The maximum poll interval defaults to 10 (1,024 s), but can be increased by the <tt>maxpoll</tt> option to an upper limit of 17 (36.4 h). The minimum poll interval defaults to 6 (64 s), but can be decreased by the <tt>minpoll</tt> option to a lower limit of 4 (16 s). These option are valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>noselect</tt> - <dd>Marks the server as unused, except for display purposes. The server is discarded by the selection algorithm. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>preempt</tt> - <dd>Specifies the association as preemptable rather than the default persistent. This option is valied only with the <tt>server</tt> command.<dt><tt>prefer</tt> - <dd>Marks the server 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. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>true</tt> - <dd>Force the association to assume truechimer status; that is, always survive the selection and clustering algorithms. This option can be used with any association, but is most useful for reference clocks with large jitter on the serial port and precision pulse-per-second (PPS) signals. Caution: this option defeats the algorithms designed to cast out falsetickers and can allow these sources to set the system clock. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.<dt><tt>ttl <i>ttl</i></tt> - <dd>This option is used only with broadcast server and manycast client modes. It specifies the time-to-live <i><tt>ttl</tt></i> to use on broadcast server and multicast server and the maximum <i><tt>ttl</tt></i> for the expanding ring search with manycast client packets. Selection of the proper value, which defaults to 127, is something of a black art and should be coordinated with the network administrator. - <dt><tt>version <i>version</i></tt> - <dd>Specifies the version number to be used for outgoing NTP packets. Versions 1-4 are the choices, with version 4 the default. This option is valid only with the <tt>server,</tt> <tt>peer</tt> and <tt>broadcast</tt> commands. - </dl> - <h4 id="aux">Auxilliary Commands</h4> - <dl> - <dt><tt>broadcastclient [novolley]</tt> - <dd>This command enables reception of broadcast server messages to any local interface (type <tt>b</tt>) address. Ordinarily, upon receiving a message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange with the server, after which it continues in listen-only mode. If the <tt>novolley</tt> keyword is present, the exchange is not used and the value specified in the <tt>broadcastdelay</tt> command is used or, if the <tt>broadcastdelay</tt> command is not used, the default 4.0 ms. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the <a href="authopt.html">Authentication Options</a> page. Note that the <tt>novolley</tt> keyword is incompatible with public key authentication.<dt><tt>manycastserver <i>address</i> [...]</tt> - <dd>This command enables reception of manycast client messages to the multicast group address(es) (type <tt>m</tt>) specified. At least one address is required. The NTP multicast address 224.0.1.1 assigned by the IANA should NOT be used, unless specific means are taken to limit the span of the reply and avoid a possibly massive implosion at the original sender. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the <a href="authopt.html">Authentication Options</a> page. - <dt><tt>multicastclient <i>address</i> [...]</tt> - <dd>This command enables reception of multicast server messages to the multicast group address(es) (type <tt>m</tt>) specified. Upon receiving a message for the first time, the multicast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding multicast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the <a href="authopt.html">Authentication Options</a> page. - </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> - + <dt><tt>server</tt></dt> + <dd>For type s and r addresses (only), this command mobilizes a persistent client mode association with the specified remote server or local reference clock. If the <tt>preempt</tt> flag is specified, a preemptable client mode association is mobilized instead.</dd> + <dt id="peer"><tt>peer</tt></dt> + <dd>For type s addresses (only), this command mobilizes a persistent symmetric-active mode association with the specified remote peer.</dd> + <dt id="broadcast"><tt>broadcast</tt></dt> + <dd>For type b and m addressees (only), this command mobilizes a broadcast or multicast server mode association. Note that type b messages go only to the interface specified, but type m messages go to all interfaces.</dd> + <dt id="manycastclient"><tt>manycastclient</tt></dt> + <dd>For type m addresses (only), this command mobilizes a preemptable manycast client mode association for the multicast group address specified. In this mode the address must match the address specified on the <tt>manycastserver</tt> command of one or more designated manycast servers. Additional information about this command is on the <a href="discover.html#mcst">Automatic Server Discovery</a> page.</dd> + <dt id="pool"><tt>pool</tt></dt> + <dd>For type s addresses (only) this command mobilizes a preemptable pool client mode association for the DNS name specified. The DNS name must resolve to one or more IPv4 or IPv6 addresses. Additional information about this command is on the <a href="discover.html#pool">Automatic Server Discovery</a> page. The <a href="http://www.pool.ntp.org/">www.pool.ntp.org</a> page describes a compatible pool of public NTP servers.</dd> + <dt id="unpeer"><tt>unpeer</tt></dt> + <dd>This command removes a previously configured association. An address or association ID can be used to identify the association. Either an IP address or DNS name can be used. This command is most useful when supplied via <tt><a href="ntpq.html">ntpq</a></tt> runtime configuration commands <tt>:config</tt> and <tt>config-from-file</tt>.</dd> + </dl></dd> +</dl> +<h4 id="option">Server Command Options</h4> +<dl> + <dt><tt>autokey</tt></dt> + <dd>Send and receive packets authenticated by the Autokey scheme described + on the <a href="autokey.html">Autokey Public Key Authentication</a> page. This option is mutually exclusive with the <tt>key</tt> option.</dd> + <dt id="burst"><tt>burst</tt></dt> + <dd>When the server is reachable, send a burst of packets instead of the usual one. This option is valid only with the <tt>server</tt> command and type s addresses. It is a recommended option when the <tt>maxpoll</tt> option is greater than 10 (1024 s). Additional information about this option is on the <a href="poll.html">Poll Program</a> page.</dd> + <dt><tt>iburst</tt></dt> + <dd>When the server is unreachable, send a burst of packets instead of the usual one. This option is valid only with the <tt>server</tt> command and type <tt>s</tt> addresses. It is a recommended option with this command. Additional information about this option is on the <a href="poll.html">Poll Program</a> page.</dd> + <dt><tt>ident</tt> <em><tt>group</tt></em></dt> + <dd>Specify the group name for the association. See the <a href="autokey.html">Autokey Public-Key Authentication</a> page for further information.</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="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> + </i></tt><tt>maxpoll <i>maxpoll</i></tt></dt> + <dd>These options specify the minimum and maximum poll intervals for NTP messages, in seconds as a power of two. The maximum poll interval defaults to 10 (1024 s), but can be increased by the <tt>maxpoll</tt> option to an upper limit of 17 (36 hr). The minimum poll interval defaults to 6 (64 s), but can be decreased by the <tt>minpoll</tt> option to a lower limit of 3 (8 s). Additional information about this option is on the <a href="poll.html">Poll Program</a> page.</dd> + <dt><tt>mode <i>option</i></tt></dt> + <dd>Pass the <tt><i>option</i></tt> to a reference clock driver, where <tt><i>option</i></tt> is an integer in the range from 0 to 255, inclusive. This option is valid only with type r addresses.</dd> + <dt><tt>noselect</tt></dt> + <dd>Marks the server or peer to be ignored by the selection algorithm as unreachable, but visible to the monitoring program. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.</dd> + <dt><tt>preempt</tt></dt> + <dd>Specifies the association as preemptable rather than the default persistent. This option is ignored with the <tt>broadcast</tt> command and is most useful with the <tt>manycastclient</tt> and <tt>pool</tt> commands.</dd> + <dt><tt>prefer</tt></dt> + <dd>Mark the server 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. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.</dd> + <dt><tt>true</tt></dt> + <dd>Mark the association to assume truechimer status; that is, always survive the selection and clustering algorithms. This option can be used with any association, but is most useful for reference clocks with large jitter on the serial port and precision pulse-per-second (PPS) signals. Caution: this option defeats the algorithms designed to cast out falsetickers and can allow these sources to set the system clock. This option is valid only with the <tt>server</tt> and <tt>peer</tt> commands.</dd> + <dt><tt>ttl <i>ttl</i></tt></dt> + <dd>This option specifies the time-to-live <i><tt>ttl</tt></i> for the <tt>broadcast</tt> command and the maximum <i><tt>ttl</tt></i> for the expanding ring search used by the <tt>manycastclient</tt> command. Selection of the proper value, which defaults to 127, is something of a black art and should be coordinated with the network administrator. This option is invalid with type r addresses.</dd> + <dt><tt>version <i>version</i></tt></dt> + <dd>Specifies the version number to be used for +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). Further information is on the <a href="xleave.html">NTP Interleaved Modes</a> page.</dd> +</dl> +<h4 id="aux">Auxiliary Commands</h4> +<dl> + <dt id="broadcastclient"><tt>broadcastclient</tt></dt> + <dd>Enable reception of broadcast server messages to any local interface (type b address). Ordinarily, upon receiving a broadcast message for the first time, the broadcast client measures the nominal server propagation delay using a brief client/server exchange, after which it continues in listen-only mode. If a nonzero value is specified in the <tt>broadcastdelay</tt> command, the value becomes the delay and the volley is not executed. Note: the <tt>novolley</tt> option has been deprecated for future enhancements. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the <a href="authopt.html">Authentication Options</a> page. Note that the volley is required with public key authentication in order to run the Autokey protocol.</dd> + <dt id="manycastserver"><tt>manycastserver <i>address</i> [...]</tt></dt> + <dd>Enable reception of manycast client messages (type m) to the multicasts group address(es) (type m) specified. At least one address is required. Note that, in order to avoid accidental or malicious disruption, both the server and client should operate using symmetric key or public key authentication as described in the <a href="authopt.html">Authentication Options</a> page.</dd> + <dt id="multicastclient"><tt>multicastclient <i>address</i> [...]</tt></dt> + <dd>Enable reception of multicast server messages to the multicast group address(es) (type m) specified. Upon receiving a message for the first time, the multicast client measures the nominal server propagation delay using a brief client/server exchange with the server, then enters the broadcast client mode, in which it synchronizes to succeeding multicast messages. Note that, in order to avoid accidental or malicious disruption in this mode, both the server and client should operate using symmetric key or public key authentication as described in the <a href="authopt.html">Authentication Options</a> page.</dd> + <dt id="mdnstries"><tt>mdnstries</tt> <i>number</i></dt> + <dd>If we are participating in mDNS, after we have synched for the first time we attempt to register with the mDNS system. If that registration attempt fails, we try again at one minute intervals for up to <tt>mdnstries</tt> times. After all, <tt>ntpd</tt> may be starting before mDNS. The default value for <tt>mdnstries</tt> is 5.</dd> +</dl> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> </html> diff --git a/contrib/ntp/html/copyright.html b/contrib/ntp/html/copyright.html index cf34979..94fffc4 100644 --- a/contrib/ntp/html/copyright.html +++ b/contrib/ntp/html/copyright.html @@ -1,25 +1,25 @@ <!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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:31</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="285">Saturday, January 06, 2007</csobj></p> - <br clear="left"> - <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.<br> - </p> - <pre> +<head> +<meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> +<title>Copyright Notice</title> +<!-- Changed by: Harlan Stenn, 10-Mar-2014 --> +<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 -->17-Jan-2015 00:16<!-- #EndDate --> + UTC</p> +<br clear="left"> +</p> +<hr> +<p>The following copyright notice applies to all files collectively called the Network Time Protocol Version 4 Distribution. Unless specifically declared otherwise in an individual file, this entire notice applies as if the text was explicitly included in the file.</p> +<pre> *********************************************************************** * * -* Copyright (c) David L. Mills 1992-2009 * +* Copyright (c) University of Delaware 1992-2015 * * * * Permission to use, copy, modify, and distribute this software and * * its documentation for any purpose with or without fee is hereby * @@ -35,62 +35,100 @@ * * *********************************************************************** </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:%20Jean-Francois.Boudreault@viagenie.qc.ca">Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca></a>IPv6 support - <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:%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:%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:%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>Content starting in 2011 from Harlan Stenn, Danny Mayer, and Martin Burnicki is:</p> +<pre> +*********************************************************************** +* * +* Copyright (c) Network Time Foundation 2011-2015 * +* * +* All Rights Reserved * +* * +* Redistribution and use in source and binary forms, with or without * +* modification, are permitted provided that the following conditions * +* are met: * +* 1. Redistributions of source code must retain the above copyright * +* notice, this list of conditions and the following disclaimer. * +* 2. Redistributions in binary form must reproduce the above * +* copyright notice, this list of conditions and the following * +* disclaimer in the documentation and/or other materials provided * +* with the distribution. * +* * +* THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS * +* OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED * +* WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * +* ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE * +* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR * +* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT * +* OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR * +* BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF * +* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * +* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE * +* USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH * +* DAMAGE. * +*********************************************************************** +</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><a href="mailto:%20takao_abe@xurb.jp">Takao Abe <takao_abe@xurb.jp></a> Clock driver for JJY receivers</li> + <li><a href="mailto:%20mark_andrews@isc.org">Mark Andrews <mark_andrews@isc.org></a> Leitch atomic clock controller</li> + <li><a href="mailto:%20altmeier@atlsoft.de">Bernd Altmeier <altmeier@atlsoft.de></a> hopf Elektronik serial line and PCI-bus devices</li> + <li><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><a href="mailto:%20michael.barone@lmco.com">Michael Barone <michael,barone@lmco.com></a> GPSVME fixes</li> + <li><a href="mailto:%20karl@owl.HQ.ileaf.com">Karl Berry <karl@owl.HQ.ileaf.com></a> syslog to file option</li> + <li><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><a href="mailto:%20Marc.Brett@westgeo.com">Marc Brett <Marc.Brett@westgeo.com></a> Magnavox GPS clock driver</li> + <li><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><a href="mailto:%20nelson@bolyard.me">Nelson B Bolyard <nelson@bolyard.me></a> update and complete broadcast and crypto features in sntp</li> + <li><a href="mailto:%20Jean-Francois.Boudreault@viagenie.qc.ca">Jean-Francois Boudreault <Jean-Francois.Boudreault@viagenie.qc.ca></a> IPv6 support</li> + <li><a href="mailto:%20reg@dwf.com">Reg Clemens <reg@dwf.com></a> Oncore driver (Current maintainer)</li> + <li><a href="mailto:%20clift@ml.csiro.au">Steve Clift <clift@ml.csiro.au></a> OMEGA clock driver</li> + <li><a href="mailto:%20casey@csc.co.za">Casey Crellin <casey@csc.co.za></a> vxWorks (Tornado) port and help with target configuration</li> + <li><a href="mailto:%20Sven_Dietrich@trimble.COM">Sven Dietrich <sven_dietrich@trimble.com></a> Palisade reference clock driver, NT adj. residuals, integrated Greg's Winnt port.</li> + <li><a href="mailto:%20dundas@salt.jpl.nasa.gov">John A. Dundas III <dundas@salt.jpl.nasa.gov></a> Apple A/UX port</li> + <li><a href="mailto:%20duwe@immd4.informatik.uni-erlangen.de">Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de></a> Linux port</li> + <li><a href="mailto:%20dennis@mrbill.canet.ca">Dennis Ferguson <dennis@mrbill.canet.ca></a> foundation code for NTP Version 2 as specified in RFC-1119</li> + <li><a href="mailto:%20jhay@icomtek.csir.co.za">John Hay <jhay@icomtek.csir.co.za></a> IPv6 support and testing</li> + <li><a href="mailto:%20davehart@davehart.com">Dave Hart <davehart@davehart.com></a> General maintenance, Windows port interpolation rewrite</li> + <li><a href="mailto:%20neoclock4x@linum.com">Claas Hilbrecht <neoclock4x@linum.com></a> NeoClock4X clock driver</li> + <li><a href="mailto:%20glenn@herald.usask.ca">Glenn Hollinger <glenn@herald.usask.ca></a> GOES clock driver</li> + <li><a href="mailto:%20iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port</li> + <li><a href="mailto:%20jagubox.gsfc.nasa.gov">Jim Jagielski <jim@jagubox.gsfc.nasa.gov></a> A/UX port</li> + <li><a href="mailto:%20jbj@chatham.usdesign.com">Jeff Johnson <jbj@chatham.usdesign.com></a> massive prototyping overhaul</li> + <li><a href="mailto:%20Hans.Lambermont@nl.origin-it.com">Hans Lambermont <Hans.Lambermont@nl.origin-it.com></a> or <a href="mailto:H.Lambermont@chello.nl"><H.Lambermont@chello.nl></a> ntpsweep</li> + <li><a href="mailto:%20phk@FreeBSD.ORG">Poul-Henning Kamp <phk@FreeBSD.ORG></a> Oncore driver (Original author)</li> + <li><a href="http://www4.informatik.uni-erlangen.de/%7ekardel">Frank Kardel</a> <a href="mailto:%20kardel%20%28at%29%20ntp%20%28dot%29%20org"><kardel (at) ntp (dot) org></a> PARSE <GENERIC> (driver 14 reference clocks), STREAMS modules for PARSE, support scripts, syslog cleanup, dynamic interface handling</li> + <li><a href="mailto:kuehn@ntp.org">Johannes Maximilian Kuehn <kuehn@ntp.org></a> Rewrote <tt>sntp</tt> to comply with NTPv4 specification, <tt>ntpq saveconfig</tt></li> + <li><a href="mailto:%20jones@hermes.chpc.utexas.edu">William L. Jones <jones@hermes.chpc.utexas.edu></a> RS/6000 AIX modifications, HPUX modifications</li> + <li><a href="mailto:%20dkatz@cisco.com">Dave Katz <dkatz@cisco.com></a> RS/6000 AIX port</li> + <li><a href="mailto:%20leres@ee.lbl.gov">Craig Leres <leres@ee.lbl.gov></a> 4.4BSD port, ppsclock, Magnavox GPS clock driver</li> + <li><a href="mailto:%20lindholm@ucs.ubc.ca">George Lindholm <lindholm@ucs.ubc.ca></a> SunOS 5.1 port</li> + <li><a href="mailto:%20louie@ni.umd.edu">Louis A. Mamakos <louie@ni.umd.edu></a> MD5-based authentication</li> + <li><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><a href="mailto:%20mayer@ntp.org">Danny Mayer <mayer@ntp.org></a>Network I/O, Windows Port, Code Maintenance</li> + <li><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><a href="mailto:%20moeller@gwdgv1.dnet.gwdg.de">Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de></a> VMS port</li> + <li><a href="mailto:%20mogul@pa.dec.com">Jeffrey Mogul <mogul@pa.dec.com></a> ntptrace utility</li> + <li><a href="mailto:%20tmoore@fievel.daytonoh.ncr.com">Tom Moore <tmoore@fievel.daytonoh.ncr.com></a> i386 svr4 port</li> + <li><a href="mailto:%20kamal@whence.com">Kamal A Mostafa <kamal@whence.com></a> SCO OpenServer port</li> + <li><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><a href="mailto:%20neal@ntp.org">Rob Neal <neal@ntp.org></a> Bancomm refclock and config/parse code maintenance</li> + <li><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><a href="mailto:%20dirce@zk3.dec.com">Dirce Richards <dirce@zk3.dec.com></a> Digital UNIX V4.0 port</li> + <li><a href="mailto:%20wsanchez@apple.com">Wilfredo Sánchez <wsanchez@apple.com></a> added support for NetInfo</li> + <li><a href="mailto:%20mrapple@quack.kfu.com">Nick Sayer <mrapple@quack.kfu.com></a> SunOS streams modules</li> + <li><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><a href="mailto:%20schnitz@unipress.com">Ray Schnitzler <schnitz@unipress.com></a> Unixware1 port</li> + <li><a href="mailto:%20shields@tembel.org">Michael Shields <shields@tembel.org></a> USNO clock driver</li> + <li><a href="mailto:%20pebbles.jpl.nasa.gov">Jeff Steinman <jss@pebbles.jpl.nasa.gov></a> Datum PTS clock driver</li> + <li><a href="mailto:%20harlan@pfcs.com">Harlan Stenn <harlan@pfcs.com></a> GNU automake/autoconfigure makeover, various other bits (see the ChangeLog)</li> + <li><a href="mailto:%20ken@sdd.hp.com">Kenneth Stone <ken@sdd.hp.com></a> HP-UX port</li> + <li><a href="mailto:%20ajit@ee.udel.edu">Ajit Thyagarajan <ajit@ee.udel.edu></a>IP multicast/anycast support</li> + <li><a href="mailto:%20tsuruoka@nc.fukuoka-u.ac.jp">Tomoaki TSURUOKA <tsuruoka@nc.fukuoka-u.ac.jp></a>TRAK clock driver</li> + <li><a href="mailto:%20brian.utterback@oracle.com">Brian Utterback <brian.utterback@oracle.com></a> General codebase, Solaris issues</li> + <li><a href="mailto:%20loganaden@gmail.com">Loganaden Velvindron <loganaden@gmail.com></a> Sandboxing (libseccomp) support</li> + <li><a href="mailto:%20vixie@vix.com">Paul A Vixie <vixie@vix.com></a> TrueTime GPS driver, generic TrueTime clock driver</li> + <li><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> +</body> </html> diff --git a/contrib/ntp/html/debug.html b/contrib/ntp/html/debug.html index c732c42..1a4981a 100644 --- a/contrib/ntp/html/debug.html +++ b/contrib/ntp/html/debug.html @@ -1,172 +1,93 @@ <!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: <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> - <br clear="left"> - <h4>More Help</h4> - <script type="text/javascript" language="javascript" src="scripts/links12.txt"></script> - <hr> - <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. Usually, no command-line arguments are required, unless special actions described in the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page are required. Once started, the daemon will begin sending and receiving messages, as specified in the configuration file.</p> - <h4>Initial Startup</h4> - <p>When started for the first time, the frequency file, usually called <tt>ntp.drift</tt>, has not yet been created. The daemon switches to a special training routine designed to quickly determine the system clock frequency offset of the particular machine. The routine first measures the current clock offset and sets the clock, then continues for up to twenty minutes before measuring the clock offset, which might involve setting the clock again. The two measurements are used to compute the initial frequency offset and the daemon continues in regular operation, during which the frequency offset is continuously updated. Once each hour the daemon writes the current frequency offset to the <tt>ntp.drift</tt> file. When restarted after that, the daemon reads the frequency offset from the <tt>ntp.drift</tt> file and avoids the training routine.</p> - <p>Note that the daemon requires at least four packet exchanges when first started in any case. This is required in order for the mitigation algorithms to insure valid and accurate measurements and defend against network delay spikes and accidental or malicious errors induced by the servers selected in the configuration file. It normally takes less than four minutes to set the clock when first started, but this can be reduced to less than ten seconds with the <tt>iburst</tt> configuration option.</p> - <p>The best way to verify correct operation is using the <a href="ntpq.html"><tt>ntpq</tt> - standard NTP query program</a> and <a href="ntpdc.html"><tt>ntpdc</tt> - special NTP query program</a> utility programs, either on the server itself or from another machine elsewhere in the network. 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>. The <tt>ntpdc</tt> program implements additional functions not provided in the standard. Both programs can be used to inspect the state variables defined in the specification and, in the case of <tt>ntpdc</tt>, additional ones intended for serious debugging. In addition, the <tt>ntpdc</tt> program can be used to selectively reconfigure and enable or disable some functions while the daemon is running.</p> - <p>In extreme cases with elusive bugs, the daemon can operate in two modes, depending on the presence of the <tt>-d</tt> command-line debug switch. If not present, the daemon detaches from the controlling terminal and proceeds autonomously. If one or more <tt>-d</tt> switches are present, the daemon does not detach and generates special 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. With a little experience, the volume of output can be reduced by piping the output to <tt>grep</tt> and specifying the keyword of the trace you want to see.</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 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. Error messages at startup and during regular operation are sent to the system log. 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> - <p>When first started, the daemon polls the servers listed in the configuration file at 64-s intervals. In order to allow a sufficient number of samples for the NTP algorithms to reliably discriminate between truechimer servers and possible falsetickers, at least four valid messages from at least one server or peer listed in the configuration file is required before the daemon can set the clock. However, if the difference between the client time and server time is greater than the panic threshold, which defaults to 1000 s, the daemon sends a message to the system log and shuts down without setting the clock. It is necessary to set the local clock to within the panic threshold first, either manually by eyeball and wristwatch and the Unix <tt>date</tt> command, or by the <tt>ntpdate</tt> or <tt>ntpd -q</tt> commands. The panic threshold can be changed by the <tt>tinker panic</tt> command discribed on the <a href="miscopt.html">Miscellaneous Options</a> page. The panic threshold can be disabled for the first measurement by the <tt>-g</tt> command line option described on the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page.</p> - <p>If the difference between local time and server time is less than the panic threshold but greater than the step threshold, which defaults to 128 ms, the daemon will perform a step adjustment; otherwise, it will gradually slew the clock to the nominal time. Step adjustments are extremely rare in ordinary operation, usually as the result of reboot or hardware failure. The step threshold can be changed to 300 s using the <tt>-x</tt> command line option described on the <tt>ntpd</tt> page. This is usually sufficient to avoid a step after reboot or when the operator has set the system clock to within five minutes by eyeball-and-wristwatch. In extreme cases the step threshold can be changed by the <tt>tinker step</tt> command discribed on the <a href="miscopt.html">Miscellaneous Options</a> page. If set to zero, the clock will never be stepped; however, users should understand the implications for doing this in a distributed data network where all processing must be tightly synchronized. See the <a href="http://www.eecis.udel.edu/%7emills/leap.html">NTP Timescale and Leap Seconds</a> page for further information. If a step adjustment is made, the clock discipline algorithm will start all over again, requiring another round of at least four messages as before. This is necessary so that all servers and peers operate on the same set of time values.</p> - <p>The clock discipline algorithm is designed to avoid large noise spikes that might occur on a congested network or access line. If an offset sample exceeds the step threshold, it is ignored and a timer started. If a later sample is below the step threshold, the counter is reset and operation continues normally. However, if the counter is greater than the stepout interval, which defaults to 900 s, the next sample will step the time as directed. The stepout threshold can be changed by the <tt>tinker stepout</tt> command discribed on the Miscellaneous Options page.</p> - <p>If for some reason the hardware clock oscillator frequency error is very large, say over 400 PPM, the time offset when the daemon is started for the first time may increase over time until exceeding the step threshold, which requires a frequency adjustment and another step correction. However, due to provisions that reduce vulnerability to noise spikes, the second correction will not be done until after the stepout threshold. When the frequency error is very large, it may take a number of cycles like this until converging to the nominal frequency correction and writing the <tt>ntp.drift</tt> file. If the frequency error is over 500 PPM, convergence will never occur and occasional step adjustments will occur indefinitely.</p> - <h4>Verifying Correct Operation</h4> - <p>After starting the daemon, run the <tt>ntpq</tt> program using the <tt>-n</tt> switch, which will avoid possible distractions due to name resolution problems. Use the <tt>pe</tt> command to display a billboard showing the status of configured peers and possibly other clients poking the daemon. After operating for a few minutes, the display should be something like:</p> - <pre> -ntpq> pe - remote refid st t when poll reach delay offset jitter -===================================================================== --isipc6.cairn.ne .GPS1. 1 u 18 64 377 65.592 -5.891 0.044 -+saicpc-isiepc2. pogo.udel.edu 2 u 241 128 370 10.477 -0.117 0.067 -+uclpc.cairn.net pogo.udel.edu 2 u 37 64 177 212.111 -0.551 0.187 -*pogo.udel.edu .GPS1. 1 u 95 128 377 0.607 0.123 0.027 -</pre> - <p>The host names or addresses shown in the <tt>remote</tt> column correspond to the server and peer entries listed in the configuration file; however, the DNS names might not agree if the names listed are not the canonical DNS names. IPv4 addresses are shown in dotted quad notation, while IPv6 addresses are shown alarmingly. The <tt>refid</tt> column shows the current source of synchronization, while the <tt>st</tt> column reveals the stratum, <tt>t</tt> the type (<tt>u</tt> = unicast, <tt>m</tt> = multicast, <tt>l</tt> = local, <tt>-</tt> = don't know), and <tt>poll</tt> the poll interval in seconds. The <tt>when</tt> column shows the time since the peer was last heard in seconds, while the <tt>reach</tt> column shows the status of the reachability register (see RFC-1305) in octal. The remaining entries show the latest delay, offset and jitter in milliseconds. Note that in NTP Version 4 what used to be the <tt>dispersion</tt> column has been replaced by the <tt>jitter</tt> column.</p> - <p>As per the NTP specification RFC-1305, when the <tt>stratum</tt> is between 0 and 15 for a NTP server, the <tt>refid</tt> field shows the server DNS name or, if not found, the IP address in dotted-quad. When the <tt>stratum</tt> is any value for a reference clock, this field shows the identification string assigned to the clock. However, until the client has synchronized to a server, or when the <tt>stratum</tt> for a NTP server is 0 (appears as 16 in the billboards), the status cannot be determined. As a help in debugging, the <tt>refid</tt> field is set to a four-character string called the kiss code. The current kiss codes are as as follows.</p> - <p>Peer Kiss Codes</p> - <p><tt>ACST</tt></p> - <dl> - <dd>The association belongs to a anycast server. - <dt><tt>AUTH</tt> - <dd>Server authentication failed. Please wait while the association is restarted. - <dt><tt>AUTO</tt> - <dd>Autokey sequence failed. Please wait while the association is restarted. - <dt><tt>BCST</tt> - <dd>The association belongs to a broadcast server. - <dt><tt>CRYP</tt> - <dd>Cryptographic authentication or identification failed. The details should be in the system log file or the <tt>cryptostats</tt> statistics file, if configured. No further messages will be sent to the server. - <dt><tt>DENY</tt> - <dd>Access denied by remote server. No further messages will be sent to the server. - <dt><tt>DROP</tt> - <dd>Lost peer in symmetric mode. Please wait while the association is restarted. - <dt><tt>RSTR</tt> - <dd>Access denied due to local policy. No further messages will be sent to the server. - <dt><tt>INIT</tt> - <dd>The association has not yet synchronized for the first time. - <dt><tt>MCST</tt> - <dd>The association belongs to a manycast server. - <dt><tt>NKEY</tt> - <dd>No key found. Either the key was never installed or is not trusted. - <dt><tt>RATE</tt> - <dd>Rate exceeded. The server has temporarily denied access because the client exceeded the rate threshold. - <dt><tt>RMOT</tt> - <dd>Somebody is tinkering with the association from a remote host running <tt>ntpdc</tt>. Not to worry unless some rascal has stolen your keys. - <dt><tt>STEP</tt> - <dd>A step change in system time has occurred, but the association has not yet resynchronized. - </dl> - <p>System Kiss Codes</p> - <dl> - <dt><tt>INIT</tt> - <dd>The system clock has not yet synchronized for the first time. - <dt><tt>STEP</tt> - <dd>A step change in system time has occurred, but the system clock has not yet resynchronized. - </dl> - <p>The tattletale symbol at the left margin displays the synchronization status of each peer. The currently selected peer is marked <tt>*</tt>, while additional peers designated acceptable for synchronization are marked <tt>+</tt>. Peers marked <tt>*</tt> and <tt>+</tt> are included in the weighted average computation to set the local clock; the data produced by peers marked with other symbols are discarded. See the <tt>ntpq</tt> page for the meaning of these symbols.</p> - <p>Additional details for each peer separately can be determined by the following procedure. First, use the <tt>as</tt> command to display an index of association identifiers, such as</p> - <pre> -ntpq> as -ind assID status conf reach auth condition last_event cnt -=========================================================== - 1 50252 f314 yes yes ok outlyer reachable 1 - 2 50253 f414 yes yes ok candidat reachable 1 - 3 50254 f414 yes yes ok candidat reachable 1 - 4 50255 f614 yes yes ok sys.peer reachable 1 -</pre> - <p>Each line in this billboard is associated with the corresponding line in the <tt>pe</tt> billboard above. The <tt>assID</tt> shows the unique identifier for each mobilized association, while the <tt>status</tt> column shows the peer status word in hex, as defined in the NTP specification. Next, use the <tt>rv</tt> command and the respective <tt>assID</tt> identifier to display a detailed synopsis for the selected peer, such as</p> - <pre> -ntpq> rv 50253 -status=f414 reach, conf, auth, sel_candidat, 1 event, event_reach, -srcadr=saicpc-isiepc2.cairn.net, srcport=123, dstadr=140.173.1.46, -dstport=123, keyid=3816249004, stratum=2, precision=-27, -rootdelay=10.925, rootdispersion=12.848, refid=pogo.udel.edu, -reftime=bd11b225.133e1437 Sat, Jul 8 2000 13:59:01.075, delay=10.550, -offset=-1.357, jitter=0.074, dispersion=1.444, reach=377, valid=7, -hmode=1, pmode=1, hpoll=6, ppoll=7, leap=00, flash=00 ok, -org=bd11b23c.01385836 Sat, Jul 8 2000 13:59:24.004, -rec=bd11b23c.02dc8fb8 Sat, Jul 8 2000 13:59:24.011, -xmt=bd11b21a.ac34c1a8 Sat, Jul 8 2000 13:58:50.672, -filtdelay= 10.45 10.50 10.63 10.40 10.48 10.43 10.49 11.26, -filtoffset= -1.18 -1.26 -1.26 -1.35 -1.35 -1.42 -1.54 -1.81, -filtdisp= 0.51 1.47 2.46 3.45 4.40 5.34 6.33 7.28, -hostname="miro.time.saic.com", signature=md5WithRSAEncryption, flags=0x83f01, initsequence=61, initkey=0x287b649c, -timestamp=3172053041 -</pre> - <p>A detailed explanation of the fields in this billboard are beyond the scope of this discussion; however, most variables defined in the NTP Version 3 specification RFC-1305 are available along with others defined for NTPv4 on the <tt>ntpq</tt> page. This particular example was chosen to illustrate probably the most complex configuration involving symmetric modes and public-key cryptography. As the result of debugging experience, the names and values of these variables may change from time to time.</p> - <p>A useful indicator of miscellaneous problems is the <tt>flash</tt> value, which reveals the state of the various sanity tests on incoming packets. There are currently 12 bits, one for each test, numbered from the right, which is for test 1. If the test fails, the corresponding bit is set to one and zero otherwise. If any bit is set following each processing step, the packet is discarded. The meaning of each test is described on the <tt>ntpq</tt> page.</p> - <p>The three lines identified as <tt>filtdelay</tt>, <tt>filtoffset</tt> and <tt>filtdisp</tt> reveal the roundtrip delay, clock offset and dispersion for each of the last eight measurement rounds, all in milliseconds. Note that the dispersion, which is an estimate of the error, increases as the age of the sample increases. From these data, it is usually possible to determine the incidence of severe packet loss, network congestion, and unstable local clock oscillators. There are no hard and fast rules here, since every case is unique; however, if one or more of the rounds show large values or change radically from one round to another, the network is probably congested or lossy.</p> - <p>Once the daemon has set the local clock, it will continuously track the discrepancy between local time and NTP time and adjust the local clock accordingly. There are two components of this adjustment, time and frequency. These adjustments are automatically determined by the clock discipline algorithm, which functions as a hybrid phase/frequency feedback loop. The behavior of this algorithm is carefully controlled to minimize residual errors due to network jitter and frequency variations of the local clock hardware oscillator that normally occur in practice. However, when started for the first time, the algorithm may take some time to converge on the intrinsic frequency error of the host machine.</p> - <p>The state of the local clock itself can be determined using the <tt>rv</tt> command (without the argument), such as</p> - <pre> -ntpq> rv -status=0644 leap_none, sync_ntp, 4 events, event_peer/strat_chg, -version="ntpd 4.0.99j4-r Fri Jul 7 23:38:17 GMT 2000 (1)", -processor="i386", system="FreeBSD3.4-RELEASE", leap=00, stratum=2, -precision=-27, rootdelay=0.552, rootdispersion=12.532, peer=50255, -refid=pogo.udel.edu, -reftime=bd11b220.ac89f40a Sat, Jul 8 2000 13:58:56.673, poll=6, -clock=bd11b225.ee201472 Sat, Jul 8 2000 13:59:01.930, state=4, -phase=0.179, frequency=44.298, jitter=0.022, stability=0.001, -hostname="barnstable.udel.edu", signature=md5WithRSAEncryption, -flags=0x80011, hostkey=3171372095, refresh=3172016539 -cert="grundoon.udel.edu grundoon.udel.edu 0x3 3233600829" -cert="whimsy.udel.edu whimsy.udel.edu 0x5 3233682156" -</pre> - <p>An explanation about most of these variables is in the RFC-1305 specification. The most useful ones include <tt>clock</tt>, which shows when the clock was last adjusted, and <tt>reftime</tt>, which shows when the server clock of <tt>refid</tt> was last adjusted. The <tt>version</tt>, <tt>processor</tt> and <tt>system</tt> values are very helpful when included in bug reports. The mean millisecond time offset (<tt>phase</tt>) and deviation (<tt>jitter</tt>) monitor the clock quality, while the mean PPM frequency offset (<tt>frequency</tt>) and deviation (<tt>stability</tt>) monitor the clock stability and serve as a useful diagnostic tool. It has been the experience of NTP operators over the years that these data represent useful environment and hardware alarms. If the motherboard fan freezes up or some hardware bit sticks, the system clock is usually the first to notice it.</p> - <p>Among the new variables added for NTP Version 4 are the <tt>hostname</tt>, <tt>signature</tt>, <tt>flags, hostkey, refresh </tt>and<tt> cert</tt>, which are used for the Autokey public-key cryptography described on the <a href="authopt.html">Authentication Options</a> page. The numeric values show the filestamps, in NTP seconds, that the associated media files were created. These are useful in diagnosing problems with cryptographic key consistency and ordering principles.</p> - <p>When nothing seems to happen in the <tt>pe</tt> billboard after some minutes, there may be a network problem. One common network problem is an access controlled router on the path to the selected peer or an access controlled server using methods described on the <a href="accopt.html">Access Control Options</a> page. Another common problem is that the server is down or running in unsynchronized mode due to a local problem. Use the <tt>ntpq</tt> program to spy on the server variables in the same way you can spy on your own.</p> - <p>Normally, the daemon will adjust the local clock in small steps in such a way that system and user programs are unaware of its operation. The adjustment process operates continuously unless the apparent clock error exceeds the step threshold for a period longer than the stepout threshold, which for most Internet paths is a very rare event. If the event is simply an outlyer due to an occasional network delay spike, the correction is simply discarded; however, if the apparent time error persists for longer than the stepout threshold of about 17 minutes, the local clock is stepped or slewed to the new value as directed. This behavior is designed to resist errors due to severely congested network paths, as well as errors due to confused radio clocks upon the epoch of a leap second.</p> - <h4>Large Frequency Errors</h4> - <p>The frequency tolerance of computer clock oscillators can vary widely, which can put a strain on the daemon's ability to compensate for the intrinsic frequency error. While the daemon can handle frequency errors up to 500 parts-per-million (PPM), or 43 seconds per day, values much above 100 PPM reduce the headroom and increase the time to learn the particular value and record it in the <tt>ntp.drift</tt> file. In extreme cases before the particular oscillator frequency error has been determined, the residual system time offsets can sweep from one extreme to the other of the 128-ms tracking window only for the behavior to repeat at 900-s intervals until the measurements have converged.</p> - <p>In order to determine if excessive frequency error is a problem, observe the nominal <tt>filtoffset</tt> values for a number of rounds and divide by the poll interval. If the result is something approaching 500 PPM, there is a good chance that NTP will not work properly until the frequency error is reduced by some means. A common cause is the hardware time-of-year (TOY) clock chip, which must be disabled when NTP disciplines the software clock. For some systems this can be done using the <tt><a href="tickadj.html">tickadj</a></tt> utility and the <tt>-s</tt> command line argument. For other systems this can be done using a command in the system startup file.</p> - <p>If the TOY chip is not the cause, the problem may be that the hardware clock frequency may simply be too slow or two fast. In some systems this might require tweaking a trimmer capacitor on the motherboard. For other systems the clock frequency can be adjusted in increments of 100 PPM using the <tt>tickadj</tt> utility and the <tt>-t</tt> command line argument. Note that the <tt>tickadj</tt> alters certain kernel variables and, while the utility attempts to figure out an acceptable way to do this, there are many cases where <tt>tickadj</tt> is incompatible with a running kernel.</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 informatin.</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 refid 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 -->16-Jul-2014 08:38<!-- #EndDate --> + UTC</p> + <br clear="left"> + <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> diff --git a/contrib/ntp/html/decode.html b/contrib/ntp/html/decode.html new file mode 100644 index 0000000..51603ad --- /dev/null +++ b/contrib/ntp/html/decode.html @@ -0,0 +1,692 @@ +<!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>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 -->16-Jul-2014 04:48<!-- #EndDate --> + UTC</p> +</p> +<br clear="left"> +<h4>Related Links</h4> +<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> +</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> +<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 Event 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 Event (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">Event</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> +</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> +</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> +</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> +</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>auth</tt></td> + <td>authentication ok</td> + </tr> + <tr> + <td><tt>40</tt></td> + <td><tt>authenb</tt></td> + <td>authentication enabled</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> +</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> +</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> +</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> +</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 width="10%">Code</td> + <td width="15%">Tag</td> + <td width="20%">Message</td> + <td width="55%">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>server not synchronized</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> authentication failure</td> + </tr> + <tr> + <td><tt>0020</tt></td> + <td>TEST6</td> + <td><tt>pkt_stratum</tt></td> + <td>invalid leap or stratum</td> + </tr> + <tr> + <td><tt>0040</tt></td> + <td>TEST7</td> + <td><tt>pkt_header</tt></td> + <td> header distance exceeded</td> + </tr> + <tr> + <td><tt>0080</tt></td> + <td>TEST8</td> + <td><tt>pkt_autokey</tt></td> + <td>Autokey sequence error</td> + </tr> + <tr> + <td><tt>0100</tt></td> + <td>TEST9</td> + <td><tt>pkt_crypto</tt></td> + <td>Autokey protocol error</td> + </tr> + <tr> + <td><tt>0200</tt></td> + <td>TEST10</td> + <td><tt>peer_stratum</tt></td> + <td> invalid header or stratum</td> + </tr> + <tr> + <td><tt>0400</tt></td> + <td>TEST11</td> + <td><tt>peer_dist</tt></td> + <td> distance threshold exceeded</td> + </tr> + <tr> + <td><tt>0800</tt></td> + <td>TEST12</td> + <td><tt>peer_loop</tt></td> + <td> synchronization loop</td> + </tr> + <tr> + <td><tt>1000</tt></td> + <td>TEST13</td> + <td><tt>peer_unreach</tt></td> + <td> unreachable or nonselect</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> +</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> +</table> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/discipline.html b/contrib/ntp/html/discipline.html new file mode 100644 index 0000000..53b60cc --- /dev/null +++ b/contrib/ntp/html/discipline.html @@ -0,0 +1,49 @@ +<!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 Discipline Algorithm</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>Clock Discipline Algorithm</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:03<!-- #EndDate --> + UTC</p> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#intro">General Overview</a></li> + <li class="inline"><a href="#pll">Phase-Lock Loop Operations</a></li> + <li class="inline"><a href="#loop">Loop Dynamics</a></li> + <li class="inline"><a href="#house">Clock Initialization and Management</a></li> +</ul> +<hr> +<h4 id="intro">General Overview</h4> +<p>At the heart of the NTP specification and reference implementation is the clock discipline algorithm, which is best described as an adaptive parameter, hybrid phase/frequency-lock feedback loop. It is an intricately crafted algorithm that automatically adapts for optimum performance while minimizing network overhead. Operation is in two modes, phase-lock loop (PLL), which is used at poll intervals below the Allan intercept, by default 2048 s, and frequency-lock loop (FLL), which is used above that.</p> +<div align="center"> <img src="pic/discipline.gif" alt="gif"> + <p>Figure 1. Clock Discipline Algorithm</p> +</div> +<h4 id="pll">Clock Discipline Operations</h4> +<p>A block diagram of the clock discipline is shown in Figure 1. The timestamp of a reference clock or remote server is compared with the timestamp of the system clock, represented as a variable frequency oscillator (VFO), to produce a raw offset sample <em>V<sub>d</sub></em>. Offset samples are processed by the clock filter to produce a filtered update <em>V<sub>s</sub></em>. The loop filter implements a type-2 proportional-integrator controller (PIC). The PIC can minimize errors in both time and frequency using predictors <em>x</em> and <em>y</em>, respectively. The clock adjust process samples these predictors once each second for the daemon discipline or once each tick interrupt for the kernel discipline to produce the system clock update <em>V<sub>c</sub></em>.</p> +<p>In PLL mode the frequency predictor is an integral of the offset over past updates, while the phase predictor is the offset amortized over time in order to avoid setting the clock backward. In FLL mode the phase predictor is not used, while the frequency predictor is similar to the NIST <em>lockclock</em> algorithm. In this algorithm, the frequency predictor is computed as a fraction of the current offset divided by the time since the last update in order to minimize the offset at the next update.</p> +<p>The discipline response in PLL mode is determined by the <em>time constant</em>, which results in a "stiffness" depending on the jitter of the available sources and the wander of the system clock oscillator. The scaled time constant is also used as the poll interval described on the <a href="poll.html">Poll Program</a> page. However, in NTP symmetric mode, each peer manages its own poll interval and the two might not be the same. In such cases either peer uses the minimum of its own poll interval and that of the other peer, which is included in the NTP packet header.</p> +<h4 id="loop">Loop Dynamics</h4> +<p> It is necessary to verify that the clock discipline algorithm is stable and satisfies the Nyquist criterion, which requires that the sampling rate be at least twice the bandwidth. In this case the bandwidth can be approximated by the reciprocal of the time constant. In the NTP specification and reference implementation, time constants and poll intervals are expressed as exponents of 2. By construction, the time constant exponent is five times the poll interval exponent. Thus, the default poll exponent of 6 corresponds to a poll interval of 64 s and a time constant of 2048 s. A change in the poll interval changes the time constant by a corresponding amount.. The Nyquist criterion requires the sample interval to be not more than half the time constant or 1024 s. The clock filter guarantees at least one sample in eight poll intervals, so the sample interval is not more than 512 s. This would be described as oversampling by a factor of two. Finally, the PLL parameters have been chosen for a damping factor of 2, which results in a much faster risetime than with critical damping, but results in modest overshoot of 6 percent.</p> +<p> It is important to understand how the dynamics of the PLL are affected by the time constant and poll interval. At the default poll interval of 64 s and a step offset change of 100 ms, the time response crosses zero in about 50 min and overshoots about 6 ms, as per design. Ordinarily, a step correction would causes a temporary frequency surge of about 5 PPM, which along with the overshoot slowly dissipates over a few hours.</p> +<p>However, the clock state machine used with the discipline algorithm avoids this transient at startup. It does this using a previously saved frequency file, if present, or by measuring the oscillator frequency, if not. It then quickly amortizes the residual offset at startup without affecting the oscillator frequency. In this way the offset error is less than 0.5 ms within 5 min, if the file is present, and within 10 min if not. See the <a href="clock.html">Clock State Machine</a> page for further details.</p> +<p>Since the PLL is linear, the response with different offset step amplitudes and poll intervals has the same characteristic shape, but scaled differently in amplitude and time. The response scales exactly with step amplitude, so that the response to a 10-ms step has the same shape as at 64 s, but with amplitude compressed by one-tenth. The response scales exactly with poll interval, so that response at a poll interval of 8 s has the same shape as at 64 s, but with time compressed by one-eighth.</p> +<p>The optimum time constant, and thus the poll interval, depends on the network time jitter and the oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. For typical Internet paths, the two error characteristics intersect at a point called the <em>Allan intercept</em>, which represents the optimum time constant. With a compromise Allan intercept of 2048 s, the optimum poll interval is about 64 s, which corresponds to a compromise poll exponent of 6. For fast LANs with modern computers, the Allan intercept is somewhat lower at around 512 s, so a compromise poll exponent of 4 (16 s) is appropriate. An intricate, heuristic algorithm is used to manage the actual poll interval within a specified range. Details are on the <a href="poll.html">Poll Program</a> page.</p> +<p>In the NTPv4 specification and reference implementation a state machine is used to manage the system clock under exceptional conditions, as when the daemon is first started or when encountering severe network congestion. In extreme cases not likely to be encountered in normal operation, the system time can be stepped forward or backward more than 128 ms. Further details are on the <a href="clock.html">Clock State Machine</a> page.</p> +<h4 id="house">Clock Initialization and Management</h4> +<p>If left running continuously, an NTP client on a fast LAN in a home or office environment can maintain synchronization nominally within one millisecond. When the ambient temperature variations are less than a degree Celsius, the clock oscillator frequency is disciplined to within one part per million (PPM), even when the clock oscillator native frequency offset is 100 PPM or more.</p> +<p> For laptops and portable devices when the power is turned off, the battery backup clock offset error can increase as much as one second per day. When power is restored after several hours or days, the clock offset and oscillator frequency errors must be resolved by the clock discipline algorithm, but this can take several hours without specific provisions.</p> +<p> The provisions described in this section insure that, in all but pathological situations, the startup transient is suppressed to within nominal levels in no more than five minutes after a warm start or ten minutes after a cold start. Following is a summary of these provisions. A detailed discussion of these provisions is on the <a href="clock.html">Clock State Machine</a> page.</p> +<p> The reference implementation measures the clock oscillator frequency and updates a frequency file at intervals of one hour or more, depending on the measured frequency wander. This design is intended to minimize write cycles in NVRAM that might be used in a laptop or portable device. In a warm start, the frequency is initialized from this file, which avoids a possibly lengthy convergence time. In a cold start when no frequency file is available, the reference implementation first measures the oscillator frequency over a five-min interval. This generally results in a residual frequency error less than 1 PPM. The measurement interval can be changed using the <tt>stepout</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> +<p>In order to reduce the clock offset error at restart, the reference implementation mext disables oscillator frequency discipline and enables clock offset discipline with a small time constant. This is designed to quickly reduce the clock offset error without causing a frequency surge. This configuration is continued for an interval of five-min, after which the clock offset error is usually no more than a millisecond. The measurement interval can be changed using the <tt>stepout</tt> option of the <a href="miscopt.html#tinker"><tt>tinker</tt></a> command.</p> +<p>Another concern at restart is the time necessary for the select and cluster algorithms to refine and validate the initial clock offset estimate. Normally, this takes several updates before setting the system clock. As the default minimum poll interval in most configurations is about one minute, it can take several minutes before setting the system clock. The <tt>iburst</tt> option of the <a href="confopt.html#burst"><tt>server</tt></a> command changes the behavior at restart and is recommended for client/server configurations. When this option is enabled, the client sends a volley of six requests at intervals of two seconds. This usually insures a reliable estimate is available in about ten seconds before setting the clock. Once this initial volley is complete, the procedures described above are executed.</p> +<p>As a result of the above considerations, when a backup source, such as the local clock driver, ACTS modem driver or orphan mode is included in the system configuration, it may happen that one or more of them are selectable before one or more of the regular sources are selectable. When backup sources are included in the configuration, the reference implementation waits an interval of several minutes without regular sources before switching to backup sources. This is generally enough to avoid startup transients due to premature switching to backup sources. The interval can be changed using the <tt>orphanwait</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/discover.html b/contrib/ntp/html/discover.html new file mode 100644 index 0000000..b35359c --- /dev/null +++ b/contrib/ntp/html/discover.html @@ -0,0 +1,75 @@ +<!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:En2m -->10-Mar-2014 05:04<!-- #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, many cast, and server pool, which are described on this page. The broadcast/multicast and many cast 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.</p> +<p> 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 the NTP mitigation algorithms, and prune the surplus associations.</p> +<h4 id="assoc">Association Management</h4> +<p>All schemes use an iterated process to discover new preemptable client associations as long as the total number of client associations is less than the <tt>maxclock</tt> option of the <tt>tos</tt> command. The <tt>maxclock</tt> default is 10, but it should be changed in typical configuration to some lower number, usually two greater than the <tt>minclock</tt> option of the same command. </p> +<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. Additional filters can be supplied using the methods described on the <a href="authentic.html">Authentication Support</a> page.</p> +<p>The pruning process uses a set of unreach counters, one for each association created by the configuration or discovery processes. At each poll interval, the counter is increased by one. If an acceptable packet arrives for a persistent (configured) or ephemeral (broadcast/multicast) association, the counter is set to zero. If an acceptable packet arrives for a preemptable (manycast, pool) association and survives the selection and clustering algorithms, the counter is set to zero. If the the counter reaches an arbitrary threshold of 10, the association becomes a candidate for pruning.</p> +<p>The pruning algorithm is very simple. If an ephemeral or preemptable association becomes a candidate for pruning, it is immediately demobilized. If a persistent association becomes a candidate for pruning, it is not demobilized, but its poll interval is set at the maximum. The pruning algorithm design avoids needless discovery/prune cycles for associations that wander in and out of the survivor list, but otherwise have similar characteristics. </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 overridden 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 client 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>broadcastdelay</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 an 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 associations fall below the <tt>maxclock</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 client 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>maxclock</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. This requires the server to be cryptographically authenticated and the server stratum to be 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 is used by pool.ntp.org and its subdomains + to discover 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 prunes 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> diff --git a/contrib/ntp/html/drivers/driver1.html b/contrib/ntp/html/drivers/driver1.html index afd85d2..4518b72 100644 --- a/contrib/ntp/html/drivers/driver1.html +++ b/contrib/ntp/html/drivers/driver1.html @@ -1,65 +1,50 @@ <!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>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 (not multicast) 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 configure this driver at a stratum greater than any other likely sources of time (say 3 or 4) to prevent the server taking over when legitimate sources are still available.</p> - <p>A third application for this driver is when an external discipline source is available, such as the NIST <tt>lockclock</tt> program, which synchronizes the local clock via a telephone modem and the NIST Automated Computer Time Service (ACTS), or the Digital Time Synchronization Service (DTSS), which runs on DCE machines. In this case the stratum should be set at zero, indicating a bona fide stratum-1 source. In the case of DTSS, the local clock can have a rather large jitter, depending on the interval between corrections and the intrinsic frequency error of the clock oscillator. In extreme cases, this can cause clients to exceed the 128-ms slew window and drop off the NTP subnet.</p> - <p>In the case where a NTP time server is synchronized to some device or protocol that is not external to the NTP daemon itself, some means should be provided to pass such things as error and health values to the NTP daemon for dissemination to its clients. If this is not done, there is a very real danger that the device or protocol could fail and with no means to tell NTP clients of the mishap. When ordinary Unix system calls like <tt>adjtime()</tt> are used to discipline the kernel clock, there is no obvious way this can be done without modifying the code for each case. However, when a modified kernel with the <tt>ntp_adjtime()</tt> system call is available, that routine can be used for the same purpose as the <tt>adjtime()</tt> routine and in addition provided with the estimated error, maximum error, and leap-indicator values. This is the preferred way to synchronize the kernel clock and pass information to the NTP clients.</p> - <p>In the default mode the behavior of the clock selection algorithm is modified when this driver is in use. The algorithm is designed so that this driver will never be selected unless no other discipline source is available. This can be overridden with the <tt>prefer</tt> keyword of the <tt>server</tt> configuration command, in which case only this driver will be selected for synchronization and all other discipline sources will be ignored. This behavior is intended for use when an external discipline source controls the system clock. See the <a href="../prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page for a detailed description of the exact behavior.</p> - <p>The stratum for this driver is set at 5 by default, but can be changed by the <tt>fudge</tt> configuration command and/or the <tt>ntpdc</tt> utility. The reference ID is <tt>LCL</tt> by default, but can be changed using the same mechanisms. <b>*NEVER*</b> configure this driver to operate at a stratum which might possibly disrupt a client with access to a bona fide primary server, unless the local clock oscillator is reliably disciplined by another source. <b>*NEVER NEVER*</b> configure a server which might devolve to an undisciplined local clock to use multicast mode.</p> - <p>This driver provides a mechanism to trim the local clock in both time and frequency, as well as a way to manipulate the leap bits. The <tt>fudge time1</tt> parameter adjusts the time (in seconds) and the <tt>fudge time2</tt> parameter adjusts the frequency (in parts per million). Both parameters are additive and operate only once; that is, each command (as from <tt>ntpdc</tt>) adds signed increments in time or frequency to the nominal local clock time and frequency.</p> - <h4>Operation with an External Reference Source</h4> - <p>There are special provisions for this driver to operate in conjunction with an external reference source, such as the <tt>LOCKCLOCK</tt> scheme used by the NIST time servers. In such schemes the system clock is disciplined by a source external to NTP, in the <tt>LOCKCLOCK</tt> case an ACTS telephone modem. To support <tt>LOCKCLOCK</tt> the NTP distribution should be built with the <tt>--enable-nist</tt> parameter in the configuration phase of the build procedure. This changes the system behavior as follows:</p> - <ol> - <li>The system clock is not disciplined in any way other than to call the <tt>ntp_adjtime()</tt> system call to obtain the kernel leap code, which becomes the driver leap code and. If the kernel leap code is 11 (not synchronized), the driver stratum is infinity; otherwise the stratum is set by the <tt>stratum</tt> subcommand on the <tt>fudge</tt> command applying to the driver. - <li>The NTP algorithms operate in the normal fashion with this driver and possibly other drivers and servers; however, the local clock driver as the <tt>prefer</tt> peer will always be selected, even if declared falseticker by the selection algorithm or fails to survive the clustering algorithm. - <li>If the driver leap code is 11, the system leap code is 11, system stratum infinity and system reference identifier <tt>DOWN</tt>. This provides a definitive status condition to dependent clients. - </ol> - <p>The local clock driver should be configured something like this:</p> - <p><tt>server 127.127.1.1 prefer</tt></p> - <p><tt>fudge 127.127.1.1 stratum 0 refid NIST</tt></p> - <p>The <tt>prefer</tt> keyword forces the driver to discipline the clock, even if other servers are configured and running correctly. This is convenient when a number of servers watch each other for monitoring and statistics gathering. In particular, the <tt>peerstats</tt> data and <tt>sysstats</tt> data can be collected at each server, aggregated for daily or weekly reports and sent by electric mail to a monitoring site. In addition, the full suite of cryptographic authentication algorithms is avialable to other servers and dependent clients.</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 -->9-May-2014 08:34<!-- #EndDate --> + UTC</p> +<hr> +<h4>Synopsis</h4> +<p>Address: 127.127.1.<i>u</i><br> + Reference ID: <tt>LOCL</tt><br> + Driver ID: <tt>LOCAL</tt></p> +<h4>Description</h4> +<p>Note: <strong>We recommend against using this driver.</strong> A much more flexible replacement is described on the <a href="../orphan.html">Orphan Mode</a> page.</p> +<p>This driver was 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 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 elsewhere in the network are available. To further protect the Internet infrastructure from accidental or malicious exposure to this driver, the driver is disabled 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 5.</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>LOCL</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> diff --git a/contrib/ntp/html/drivers/driver10.html b/contrib/ntp/html/drivers/driver10.html index 97b0495..1dd56c1 100644 --- a/contrib/ntp/html/drivers/driver10.html +++ b/contrib/ntp/html/drivers/driver10.html @@ -1,53 +1,53 @@ <!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. For operation with multiple computers, it requires the <tt>ppsclock</tt> streams module described in the <a href="../ldisc.html">Line Disciplines and Streams Modules</a> page. The streams module requires a gadget box and 1-PPS level converter, such as described in the <a href="../pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page.</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 -->11-Sep-2010 05:56<!-- #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> diff --git a/contrib/ntp/html/drivers/driver11.html b/contrib/ntp/html/drivers/driver11.html index b36f7f3..f3c9a81 100644 --- a/contrib/ntp/html/drivers/driver11.html +++ b/contrib/ntp/html/drivers/driver11.html @@ -1,31 +1,30 @@ <!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> - <p>Description</p> - </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 -->11-Sep-2010 05:56<!-- #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) @@ -34,10 +33,10 @@ ddd = day of year 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 @@ -47,41 +46,40 @@ F clock failure, time not reliable 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> diff --git a/contrib/ntp/html/drivers/driver12.html b/contrib/ntp/html/drivers/driver12.html index 6d0b38a..3b6fc15 100644 --- a/contrib/ntp/html/drivers/driver12.html +++ b/contrib/ntp/html/drivers/driver12.html @@ -1,49 +1,49 @@ <!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 -->11-Sep-2010 05:56<!-- #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> diff --git a/contrib/ntp/html/drivers/driver16.html b/contrib/ntp/html/drivers/driver16.html index 95308ba..74a3bd6 100644 --- a/contrib/ntp/html/drivers/driver16.html +++ b/contrib/ntp/html/drivers/driver16.html @@ -2,30 +2,33 @@ <html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <meta name="GENERATOR" content="Mozilla/4.6 [en] (Win95; U) [Netscape]"> - <meta name="Author" content="Ganesh Ramasivan"> - <title>Bancomm bc635VME Time and Frequency Processor</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> + <head> + <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.6 [en] (Win95; U) [Netscape]"> + <meta name="Author" content="Ganesh Ramasivan"> + <title>Bancomm bc635VME Time and Frequency Processor</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> - <body> - <h3>bc635VME/bc350VXI Time and Frequency Processor</h3> - <hr> - <h4>Synopsis</h4> - <p>Address: 127.127.16.<i>u</i><br> - Reference ID: BTFP<br> - Driver ID: GPS_BANCOMM<br> - Bancomm Device <tt>/dev/btfp0</tt><br> - Requires: Bancomm bc635 TFP device module driver for SunOS 4.x/SunOS 5.x</p> - <h4>Description</h4> - <p>This is the clock driver for the Bancomm bc635VME Time and Frequency Processor. It requires the BANCOMM bc635VME bc350VXI Time and Frequency Processor Module Driver for SunOS 4.x/SunOS 5.x UNIX Systems.</p> - <p>Most of this code is originally from refclock_bancomm.c with thanks. It has been modified and tested on an UltraSparc IIi-cEngine running Solaris 2.6. A port for HPUX is not available henceforth.</p> - <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> + <body> + <h3>bc635VME/bc350VXI Time and Frequency Processor</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + <p>Address: 127.127.16.<i>u</i><br> + Reference ID: BTFP<br> + Driver ID: GPS_BANCOMM<br> + Bancomm Device <tt>/dev/btfp0</tt><br> + Requires: Bancomm bc635 TFP device module driver for SunOS 4.x/SunOS 5.x</p> + <h4>Description</h4> + <p>This is the clock driver for the Bancomm bc635VME Time and Frequency Processor. It requires the BANCOMM bc635VME bc350VXI Time and Frequency Processor Module Driver for SunOS 4.x/SunOS 5.x UNIX Systems.</p> + <p>Most of this code is originally from refclock_bancomm.c with thanks. It has been modified and tested on an UltraSparc IIi-cEngine running Solaris 2.6. A port for HPUX is not available henceforth.</p> + <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 +</html> diff --git a/contrib/ntp/html/drivers/driver18.html b/contrib/ntp/html/drivers/driver18.html index 6acf5f2..02fb5d2 100644 --- a/contrib/ntp/html/drivers/driver18.html +++ b/contrib/ntp/html/drivers/driver18.html @@ -1,82 +1,82 @@ <!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 Modem Time Service</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Automated Computer Time Service (ACTS)</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>Author: David L. Mills (mills@udel.edu)<br> + Last update: + <!-- #BeginDate format:En2m -->1-Dec-2012 10:44<!-- #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>ntpq</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>ntpq</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>The Spectracom radio can be connected via a modem if the radio is configured to send time codes continuously 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 hang-up 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>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> diff --git a/contrib/ntp/html/drivers/driver19.html b/contrib/ntp/html/drivers/driver19.html index 961ca09..2c8278f 100644 --- a/contrib/ntp/html/drivers/driver19.html +++ b/contrib/ntp/html/drivers/driver19.html @@ -1,59 +1,59 @@ <!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. Its 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 -->11-Sep-2010 05:56<!-- #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> diff --git a/contrib/ntp/html/drivers/driver2.html b/contrib/ntp/html/drivers/driver2.html deleted file mode 100644 index 20bad64..0000000 --- a/contrib/ntp/html/drivers/driver2.html +++ /dev/null @@ -1,67 +0,0 @@ -<!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>Trak 8820 GPS Receiver</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Trak 8820 GPS Receiver</h3> - <hr> - <h4>Synopsis</h4> - <p>Address: 127.127.2.<i>u</i><br> - Reference ID: <tt>GPS</tt><br> - Driver ID: <tt>GPS_TRAK</tt><br> - Serial Port: <tt>/dev/trak<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 Trak 8820 GPS Station Clock. The claimed accuracy at the 1-PPS output is 200-300 ns relative to the broadcast signal; 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>For best accuracy, this radio requires the <tt>tty_clk</tt> line discipline, which captures a timestamp at the <tt>*</tt> on-time character of the timecode. Using this discipline the jitter is in the order of 1 ms and systematic error about 0.5 ms. If unavailable, the buffer timestamp is used, which is captured at the <tt>\r</tt> ending the timecode message. This introduces a systematic error of 23 character times, or about 24 ms at 9600 bps, together with a jitter well over 8 ms on Sun IPC-class machines.</p> - <p>Using the menus, the radio should be set for 9600 bps, one stop bit and no parity. It should be set to operate in computer (no echo) mode. The timecode format includes neither the year nor leap-second warning.</p> - <p>In operation, this driver sends a <tt>RQTS\r</tt> request to the radio at initialization in order to put it in continuous time output mode. The radio then sends the following message once each second:</p> - <pre>*RQTS U,ddd:hh:mm:ss.0,q<cr><lf> -on-time = '*' -ddd = day of year -hh:mm:ss = hours, minutes, seconds -q = quality indicator (phase error), 0-6: - 0 > 20 us - 6 > 10 us - 5 > 1 us - 4 > 100 ns - 3 > 10 ns - 2 < 10 ns</pre> - The alarm condition is indicated by <tt>0</tt> at <tt>Q</tt>, which means the radio has a phase error greater than 20 us relative to the broadcast time. The absence of year, DST and leap-second warning in this format is also alarmed. - <p>The continuous time mode is disabled using the <tt>RQTX\r</tt> request, following which the radio sends a <tt>RQTX DONE<cr><lf></tt> response. In the normal mode, other control and status requests are effective, including the leap-second status request <tt>RQLS<cr></tt>. The radio responds with <tt>RQLS yy,mm,dd<cr><lf></tt>, where <tt>yy,mm,dd</tt> are the year, month and day. Presumably, this gives the epoch of the next leap second, <tt>RQLS 00,00,00</tt> if none is specified in the GPS message. Specified in this form, the information is generally useless and is ignored by the driver.</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> - <p></p> - <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>Not used by this driver. - <p>Additional Information</p> - <p><a href="../refclock.html">Reference Clock Drivers</a></p> - </dl> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/drivers/driver20.html b/contrib/ntp/html/drivers/driver20.html index 17be32c..6391e86 100644 --- a/contrib/ntp/html/drivers/driver20.html +++ b/contrib/ntp/html/drivers/driver20.html @@ -1,91 +1,432 @@ <!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>Generic NMEA GPS Receiver</title> + <!-- Changed by: Harlan &, 31-Mar-2014 --> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <style type="text/css"> + table.dlstable { font-size:85%; } + td.ttf{ font-family:Courier; font-weight:bold; } + </style></head> -<html> - - <head> - <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> - <meta name="GENERATOR" content="Mozilla/4.76 [en] (X11; U; Linux 2.2.16-22 i586) [Netscape]"> - <title>Generic NMEA GPS Receiver</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Generic NMEA GPS Receiver</h3> - <hr> - <h4>Synopsis</h4> - <p>Address: 127.127.20.<i>u</i><br> - Reference ID: <tt>GPS</tt><br> - Driver ID: <tt>GPS_NMEA</tt><br> - Serial Port: <tt>/dev/gps<i>u</i></tt>; 4800 baud, 8-bits, no parity<br> - Serial Port: <tt>/dev/gps<i>u</i></tt>; symlink to server:port (for nmead) Features: <tt>tty_clk</tt></p> - <h4>Description</h4> - <p>This driver supports GPS receivers with the <tt>$GPRMC</tt> NMEA output string by default. Alternately the <tt>$GPGGA</tt> or <tt>$GPGLL </tt>may be selected.</p> - <p>The driver expects the receiver to be set up to transmit a <tt>$GPRMC</tt> message every second.</p> - <p>The accuracy depend on the receiver used. Inexpesive GPS models are available with a claimed PPS signal accuracy of 1 <font face="Symbol">m</font>s or better relative to the broadcast signal. 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>If the Operating System supports the PPSAPI, RFC-2783, it will be used.<br> </p> - <p>The various GPS sentences that this driver recognises look like this:<br> - (others quietly ignored)</p> - <pre><tt>$GPRMC,POS_UTC,POS_STAT,LAT,LAT_REF,LON,LON_REF,SPD,HDG,DATE,MAG_VAR,MAG_REF*CC<cr><lf> -$GPGLL,LAT,LAT_REF,LONG,LONG_REF,POS_UTC,POS_STAT*CC<cr><lf> -$GPGGA,POS_UTC,LAT,LAT_REF,LONG,LONG_REF,FIX_MODE,SAT_USED,HDOP,ALT,ALT_UNIT,GEO,G_UNIT,D_AGE,D_REF*CC<cr><lf> - - POS_UTC - UTC of position. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.fff]) - POS_STAT - Position status. (A = Data valid, V = Data invalid) - LAT - Latitude (llll.ll) - LAT_REF - Latitude direction. (N = North, S = South) - LON - Longitude (yyyyy.yy) - LON_REF - Longitude direction (E = East, W = West) - SPD - Speed over ground. (knots) (x.x) - HDG - Heading/track made good (degrees True) (x.x) - DATE - Date (ddmmyy) - MAG_VAR - Magnetic variation (degrees) (x.x) - MAG_REF - Magnetic variation (E = East, W = West) - FIX_MODE - Position Fix Mode ( 0 = Invalid, >0 = Valid) - SAT_USED - Number Satellites used in solution - HDOP - Horizontal Dilution of Precision - ALT - Antenna Altitude - ALT_UNIT - Altitude Units (Metres/Feet) - GEO - Geoid/Elipsoid separation - G_UNIT - Geoid units (M/F) - D_AGE - Age of last DGPS Fix - D_REF - Reference ID of DGPS station - CC - Checksum (optional) - <cr><lf> - Sentence terminator.</tt></pre> - Alternate GPS sentences (other than <tt>$GPRMC</tt> - the default) may be enabled by setting the relevent bits of 'mode' in the server configuration line<br> * server 127.127.20.x mode X<br> bit 0 - enables RMC ( value = 1)<br> bit 1 - enables GGA ( value = 2)<br> bit 2 - enables GLL ( value = 4)<br> - multiple sentences may be selected<br> - <p>The driver will send a <tt>$PMOTG,RMC,0000*1D<cr><lf></tt> message each time a <tt>$GPRMC</tt> string is needed. This is not needed on most GPS receivers because they automatically send the <tt>$GPRMC</tt> string every second and will only work on GPS receivers that understand the <tt>$PMOTG</tt> string. Others will just ignore it.</p> - <h4>Setting up the Garmin GPS-25XL</h4> - Switch off all output with by sending it the following string. - <pre>"$PGRMO,,2<cr><lf>"</pre> - <p>Now switch only $GPRMC on by sending it the following string.</p> - <pre>"$PGRMO,GPRMC,1<cr><lf>"</pre> - <p>On some systems the PPS signal isn't switched on by default. It can be switched on by sending the following string.</p> - <pre>"$PGRMC,,,,,,,,,,,,2<cr><lf>"</pre> - <h4>Monitor Data</h4> - <p>The GPS sentence(s) that is used is written to the clockstats 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>Specifies the PPS signal on-time edge: 0 for assert (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>Not used by this driver. - </dl> - <p>Additional Information</p> - <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 + + + <body> + <h3>Generic NMEA GPS Receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->31-Mar-2014 03:55<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + + <p> + Address: 127.127.20.<i>u</i><br> + Reference ID: <tt>GPS</tt><br> + Driver ID: <tt>GPS_NMEA</tt><br> + Serial Port: <tt>/dev/gps<i>u</i></tt>; 4800 - 115200 bps, 8-bits, no parity<br> + Serial Port: <tt>/dev/gpspps<i>u</i></tt>; for just the PPS signal (this + is tried first for PPS, before <tt>/dev/gps<i>u</i></tt>)<br> + Serial Port: <tt>/dev/gps<i>u</i></tt>; symlink to server:port (for nmead)<br> + Features: <tt>tty_clk</tt> + </p> + + <h4>Description</h4> + + <p> + This driver supports GPS receivers with + the <tt>$GPRMC</tt>, <tt>$GPGLL</tt>, <tt>$GPGGA</tt>, <tt>$GPZDA</tt> + and <tt>$GPZDG</tt> NMEA sentences by default. Note that Accord's + custom NMEA sentence <tt>$GPZDG</tt> reports using the GPS timescale, + while the rest of the sentences report UTC. The difference between + the two is a whole number of seconds which increases with each leap + second insertion in UTC. To avoid problems mixing UTC and GPS + timescales, the driver disables processing of UTC sentences + once <tt>$GPZDG</tt> is received. + </p> + <p> + The driver expects the receiver to be set up to transmit at least one + supported sentence every second. + </p> + <p> + The accuracy depends on the receiver used. Inexpensive GPS models are + available with a claimed PPS signal accuracy of + 1 μs or better relative to the broadcast + signal. 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> + If the Operating System supports PPSAPI + (<a href="http://www.ietf.org/rfc/rfc2783.txt">RFC 2783</a>), fudge flag1 + 1 enables its use. + </p> + <p> + The various GPS sentences that this driver recognises look like this:<br> + (others quietly ignored) + </p> + + <p><table class="dlstable" border="1"> + <caption>Accepted NMEA sentences</caption> + <tbody><tr> + <th>Sentence</th> + <th>Vendor</th> + </tr><tr> + <td class="ttf">$GPRMC,UTC,POS_STAT,LAT,LAT_REF,LON,LON_REF,SPD,HDG,DATE,MAG_VAR,MAG_REF*CS<cr><lf></td> + </tr><tr> + <td class="ttf">$GPGLL,LAT,LAT_REF,LON,LON_REF,UTC,POS_STAT*CS<cr><lf></td> + </tr><tr> + <td class="ttf">$GPGGA,UTC,LAT,LAT_REF,LON,LON_REF,FIX_MODE,SAT_USED,HDOP,ALT,ALT_UNIT,GEO,G_UNIT,D_AGE,D_REF*CS<cr><lf></td> + </tr><tr> + <td class="ttf">$GPZDA,UTC,DD,MM,YYYY,TH,TM,*CS<cr><lf></td> + </tr><tr> + <td class="ttf">$GPZDG,GPSTIME,DD,MM,YYYY,AA.BB,V*CS<cr><lf></td> + <td>Accord</td> + </tr> + </tbody></table></p> + + <p><table class="dlstable" border="1"> + <caption>NMEA data items</caption> + <tbody><tr> + <th>Symbol</th> + <th>Meaning and Format</th> + </tr> + + <tr> + <td class="ttf">UTC</td> + <td>Time of day on UTC timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.fff])</td> + </tr><tr> + <td class="ttf">POS_STAT</td> + <td>Position status. (A = Data valid, V = Data invalid)</td> + </tr><tr> + <td class="ttf">LAT</td> + <td>Latitude (llll.ll)</td> + </tr><tr> + <td class="ttf">LAT_REF</td> + <td>Latitude direction. (N = North, S = South)</td> + </tr><tr> + <td class="ttf">LON</td> + <td>Longitude (yyyyy.yy)</td> + </tr><tr> + <td class="ttf">LON_REF</td> + <td>Longitude direction (E = East, W = West)</td> + </tr><tr> + <td class="ttf">SPD</td> + <td>Speed over ground. (knots) (x.x)</td> + </tr><tr> + <td class="ttf">HDG</td> + <td>Heading/track made good (degrees True) (x.x)</td> + </tr><tr> + <td class="ttf">DATE</td> + <td>Date (ddmmyy)</td> + </tr><tr> + <td class="ttf">MAG_VAR</td> + <td>Magnetic variation (degrees) (x.x)</td> + </tr><tr> + <td class="ttf">MAG_REF</td> + <td>Magnetic variation (E = East, W = West)</td> + </tr><tr> + <td class="ttf">FIX_MODE</td> + <td>Position Fix Mode (0 = Invalid, >0 = Valid)</td> + </tr><tr> + <td class="ttf">SAT_USED</td> + <td>Number of Satellites used in solution</td> + </tr><tr> + <td class="ttf">HDOP</td> + <td>Horizontal Dilution of Precision</td> + </tr><tr> + <td class="ttf">ALT</td> + <td>Antenna Altitude</td> + </tr><tr> + <td class="ttf">ALT_UNIT</td> + <td>Altitude Units (Metres/Feet)</td> + </tr><tr> + <td class="ttf">GEO</td> + <td>Geoid/Elipsoid separation</td> + </tr><tr> + <td class="ttf">G_UNIT</td> + <td>Geoid units (M/F)</td> + </tr><tr> + <td class="ttf">D_AGE</td> + <td>Age of last DGPS Fix</td> + </tr><tr> + <td class="ttf">D_REF</td> + <td>Reference ID of DGPS station</td> + </tr><tr> + <td class="ttf">GPSTIME</td> + <td>Time of day on GPS timescale. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.f])</td> + </tr><tr> + <td class="ttf">DD</td> + <td>Day of the month (1-31)</td> + </tr><tr> + <td class="ttf">MM</td> + <td>Month of the year (1-12)</td> + </tr><tr> + <td class="ttf">YYYY</td> + <td>Year</td> + </tr><tr> + <td class="ttf">AA.BB</td> + <td>Denotes the signal strength (should be < 05.00)</td> + </tr><tr> + <td class="ttf">V</td> + <td>GPS sync status<br> + '0' => INVALID time,<br> + '1' => accuracy of +/- 20ms,<br> + '2' => accuracy of +/- 100ns</td> + </tr><tr> + <td class="ttf">CS</td> + <td> Checksum</td> + </tr><tr> + <td class="ttf"><cr><lf></td> + <td>Sentence terminator.</td> + </tr> + </tbody></table></p> + + + <h4>The 'mode' byte</h4> + + <p> + Specific GPS sentences and bitrates may be selected by setting bits of + the 'mode' in the server configuration line:<br> <tt>server + 127.127.20.x mode X</tt> + </p> + + <table border="1"> + <caption>mode byte bits and bit groups</caption> + <tbody><tr> + <th align="center">Bit</th> + <th align="center">Decimal</th> + <th align="center">Hex</th> + <th align="left">Meaning</th> + </tr> + + <tr> + <td align="center">0</td> + <td align="center">1</td> + <td align="center">1</td> + <td>process <tt>$GPMRC</tt></td> + </tr><tr> + <td align="center">1</td> + <td align="center">2</td> + <td align="center">2</td> + <td>process <tt>$GPGGA</tt></td> + </tr><tr> + <td align="center">2</td> + <td align="center">4</td> + <td align="center">4</td> + <td>process <tt>$GPGLL</tt></td> + </tr><tr> + <td align="center">3</td> + <td align="center">8</td> + <td align="center">8</td> + <td>process <tt>$GPZDA</tt> or <tt>$GPZDG</tt></td> + </tr><tr> + <td rowspan="6" align="center">4-6</td> + <td align="center">0</td> + <td align="center">0</td> + <td>linespeed 4800 bps</td> + </tr><tr> + <td align="center">16</td> + <td align="center">0x10</td> + <td>linespeed 9600 bps</td> + </tr><tr> + <td align="center">32</td> + <td align="center">0x20</td> + <td>linespeed 19200 bps</td> + </tr><tr> + <td align="center">48</td> + <td align="center">0x30</td> + <td>linespeed 38400 bps</td> + </tr><tr> + <td align="center">64</td> + <td align="center">0x40</td> + <td>linespeed 57600 bps</td> + </tr><tr> + <td align="center">80</td> + <td align="center">0x50</td> + <td>linespeed 115200 bps</td> + </tr><tr> + <td align="center">7</td> + <td align="center">128</td> + <td align="center">0x80</td> + <td>Write the sub-second fraction of the receive time stamp to the + clockstat file for all recognised NMEA sentences. This can be used to + get a useful value for fudge time2.<br><strong>Caveat:</strong> This + will fill your clockstat file rather fast. Use it only temporarily to + get the numbers for the NMEA sentence of your choice.</td> + </tr> + </tr><tr> + <td align="center">8</td> + <td align="center">256</td> + <td align="center">0x100</td> + <td>process <tt>$PGRMF</tt></td> + </tr><tr> + <td align="center">9-15</td> + <td align="center"></td> + <td align="center">0xFE00</td> + <td>reserved - leave 0</td> + </tr><tr> + <td align="center">16</td> + <td align="center">65536</td> + <td align="center">0x10000</td> + <td>Append extra statistics to the clockstats line. + Details below.</td> + </tr> + </tbody></table> + + + <p> + The default (mode 0) is to process all supported sentences at a linespeed + of 4800 bps, which results in the first one received and recognised in + each cycle being used. If only specific sentences should be + recognised, then the mode byte must be chosen to enable only the selected + ones. Multiple sentences may be selected by adding their mode bit + values, but of those enabled still only the first received sentence in a + cycle will be used. Using more than one sentence per cycle is + impossible, because + </p><ul> + <li>there is only <a href="#fudgetime2">fudge time2</a> available to + compensate for transmission delays but every sentence would need a + different one and + </li><li>using more than one sentence per cycle overstuffs the internal data + filters. + </li></ul> + The driver uses 4800 bits per second by default, but faster bitrates can + be selected using bits 4 to 6 of the mode field. + <p></p> + + <p> + <strong>Caveat:</strong> Using higher line speeds does not necessarily + increase the precision of the timing device. Higher line speeds are + not necessarily helpful for the NMEA driver, either. They can be + used to accomodate for an amount of data that does not fit into a + 1-second cycle at 4800 bps, but high-speed high-volume NMEA data is likely + to cause trouble with the serial line driver since NMEA supports no + protocol handshake. Any device that is exclusively used for time + synchronisation purposes should be configured to transmit the relevant + data only, e.g. one <tt>$GPRMC</tt> or <tt>$GPZDA</tt> per second, at a + linespeed of 4800 bps or 9600 bps. + </p> + + <h4>Monitor Data</h4> + + <p>The last GPS sentence that is accepted or rejected is written to the + clockstats file and available with <code>ntpq -c clockvar</code>. + (Logging the rejected sentences lets you see/debug why they were rejected.) + Filtered sentences are not logged.</p> + + <p> + If the 0x10000 mode bit is on and clockstats is enabled, several extra + counters will be appended to the NMEA sentence that gets logged. + For example: +<pre> +56299 76876.691 127.127.20.20 $GPGGA,212116.000,3726.0785,N,12212.2605,W,1,05,2.0,17.0,M,-25.7,M,,0000*5C 228 64 0 0 64 0 +</pre> + </p> + + <table border="1"> + <caption>Clockstats</caption> + <tbody><tr> + <th align="center">Column</th> + <th align="center">Sample</th> + <th align="left">Meaning</th> + </tr> + + <tr> + <td align="center">1</td> + <td align="center">56299</td> + <td>MJD</td> + </tr><tr> + <td align="center">2</td> + <td align="center">76876.691</td> + <td>Time of day in seconds</td> + </tr><tr> + <td align="center">3</td> + <td align="center">127.127.20.20</td> + <td>IP Address from server config line</td> + </tr><tr> + <td align="center">4</td> + <td align="center">$GPGGA,...0*5C</td> + <td>NMEA Sentence</td> + </tr><tr> + <td align="center">5</td> + <td align="center">228</td> + <td>Number of sentences received</td> + </tr><tr> + <td align="center">6</td> + <td align="center">64</td> + <td>Number of sentences accepted and used for timekeeping</td> + </tr><tr> + <td align="center">7</td> + <td align="center">0</td> + <td>Number of sentences rejected because they were marked invalid (poor signal)</td> + </tr><tr> + <td align="center">8</td> + <td align="center">0</td> + <td>Number of sentences rejected because of bad checksum or invalid date/time</td> + </tr><tr> + <td align="center">9</td> + <td align="center">64</td> + <td>Number of sentences filtered by mode bits or same second</td> + </tr><tr> + <td align="center">10</td> + <td align="center">0</td> + <td>Number of PPS pulses used, overrides NMEA sentences</td> + </tr> + </tbody></table> + + Sentences like $GPGSV that don't contain the time will get + counted in the total but otherwise ignored. + + <p> + <a href="https://support.ntp.org/bin/view/Support/ConfiguringNMEARefclocks">Configuring + NMEA Refclocks</a> might give further useful hints for specific hardware + devices that exhibit strange or curious behaviour. + </p> + + <p> + To make a specific setting, select the corresponding decimal values from + the mode byte table, add them all together and enter the resulting + decimal value into the clock configuration line. + </p> + + <h4>Setting up the Garmin GPS-25XL</h4> + + Switch off all output with by sending it the following string. + <pre>"$PGRMO,,2<cr><lf>"</pre> + <p>Now switch only $GPRMC on by sending it the following string.</p> + <pre>"$PGRMO,GPRMC,1<cr><lf>"</pre> + + <p>On some systems the PPS signal isn't switched on by default. It can be + switched on by sending the following string.</p> + <pre>"$PGRMC,,,,,,,,,,,,2<cr><lf>"</pre> + + <h4>Fudge Factors</h4> + + <dl> + <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><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> + <dd>Specifies the serial end of line 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>GPS</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>Obscures location in timecode: 0 for disable (default), 1 for enable.</dd> + </dl> + + <p>Additional Information</p> + <p><tt>flag1</tt>, <tt>flag2</tt>, and <tt>flag3</tt> are ignored under Windows.</p> + <p><a href="../refclock.html">Reference Clock Drivers</a></p> + <hr> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body></html> diff --git a/contrib/ntp/html/drivers/driver22.html b/contrib/ntp/html/drivers/driver22.html index e1ed132..acae265 100644 --- a/contrib/ntp/html/drivers/driver22.html +++ b/contrib/ntp/html/drivers/driver22.html @@ -1,60 +1,98 @@ <!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> - <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 interface</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 operates only with the PPSAPI interface proposed as an IETF standard. 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 (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 and trimmed average algorithms in the driver interface. As the result, performance with minpoll and maxpoll configured at the minimum 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>Note that the PPS source is considered valid only if the auxiliary source is the prefer peer, is reachable and is selectable to discipline the system clock. By default the stratum assigned to the PPS source is automatically determined. If the auxiliary source is unreachable or inoperative, the stratum is set to 16. Otherwise it is set to the stratum specified by the <tt>fudge stratum</tt> command, if present, or the auxiliary source stratum if not present. Please note the temptation to masquerade as a primary server by forcing the stratum to zero is decidedly dangerous, as it invites timing loops.</p> - <p>The <tt>mode</tt> keyword of the <tt>server</tt> command can be used to set the PPSAPI mode bits which determine the capture edge and echo options. See the <tt>/usr/include/sys/timepps.h</tt> header file for the bit definitions, which must be converted to their decimal equivalents. This overrides the fudge <tt>flag2</tt> option.</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 the PPS signal on-time edge: 0 for assert (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>Not used by this driver. - </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 +<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> +<!-- Changed by: Harlan &, 31-Mar-2014 --> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>PPS Clock Discipline</h3> +<p>Author: David L. Mills (mills@udel.edu)<br> + Last change: + <!-- #BeginDate format:En2m -->31-Mar-2014 07:46<!-- #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> +<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></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 (default) or falling + (clear) pulse edge if 1. Not used under Windows - if the special <tt>serialpps.sys</tt> serial port driver is installed then the leading edge will <i>always</i> be used.</dd> + <dt><tt>flag3 0 | 1</tt></dt> + <dd>Controls the kernel PPS discipline: 0 for disable (default), 1 for enable. Not used under Windows - if the special <tt>serialpps.sys</tt> serial port driver is used then kernel PPS will be available and used.</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> diff --git a/contrib/ntp/html/drivers/driver26.html b/contrib/ntp/html/drivers/driver26.html index f840a03..dc84cc1 100644 --- a/contrib/ntp/html/drivers/driver26.html +++ b/contrib/ntp/html/drivers/driver26.html @@ -11,6 +11,9 @@ <body> <h3>Hewlett Packard 58503A GPS Receiver and HP Z3801A</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->5-Oct-2005 04:37<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.26.<i>u</i><br> diff --git a/contrib/ntp/html/drivers/driver27.html b/contrib/ntp/html/drivers/driver27.html index 8c2633c..91534ad 100644 --- a/contrib/ntp/html/drivers/driver27.html +++ b/contrib/ntp/html/drivers/driver27.html @@ -11,6 +11,9 @@ <body> <h3>Arcron MSF Receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.27.<i>u</i><br> @@ -46,7 +49,6 @@ <dl> <dt><tt>g</tt> CR <dd>Request for signal quality. Answer only valid during (late part of) resync to MSF signal. The response consists of two characters as follows: - <ol> <dl compact> <dt>bit 7 <dd>parity @@ -79,7 +81,6 @@ <dt>bit 2--0 <dd>reception signal quality in the range 0--5 (very poor to very good); if in the range 0--2 no successful reception is to be expected. The reported value drops to zero when not resyncing, ie when first returned byte is not `3'. </dl> - </ol> <dt><tt>h</tt> CR <dd>Request to resync to signal. Can take up from about 30s to 360s. Drains batteries so should not be used excessively. After this the clock time and date should be correct and the phase within 20ms of time as transmitted from the source signal (remember to allow for propagation time). By default the clock resyncs once per day in the late evening/early morning (presumably to catch transitions to/from daylight saving time quickly). This driver code, by default, resyncs at least once per hour to minimise clock wander. <dt><tt>o</tt> CR @@ -244,4 +245,4 @@ May 10 12:41:34 oolong ntpd[615]: ARCRON: sync finished, signal quality 3: OK, w <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver28.html b/contrib/ntp/html/drivers/driver28.html index 244de1a..efa862f 100644 --- a/contrib/ntp/html/drivers/driver28.html +++ b/contrib/ntp/html/drivers/driver28.html @@ -5,72 +5,249 @@ <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>Shared memoy Driver</title> + <title>Shared Memory Driver</title> <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <style type="text/css"> + table.dlstable { font-size:85%; } + td.ttf{ font-family:Courier; font-weight:bold; } + </style> </head> <body> <h3>Shared Memory Driver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->8-Aug-2014 19:17<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.28.<i>u</i><br> Reference ID: <tt>SHM</tt><br> Driver ID: <tt>SHM</tt></p> + <h4>Description</h4> - <p>This driver receives its reference clock info from a shared memory-segment. The shared memory-segment is created with owner-only access for unit 0 and 1, and world access for unit 2 and 3</p> + <p>This driver receives its reference clock info from a shared + memory-segment. The shared memory-segment is created with owner-only + access by default, unless otherwise requested by the mode word for units + ≥2. Units 0 and 1 are always created with owner-only access for + backward compatibility. + </p> + + <h4>Structure of shared memory-segment</h4> <pre>struct shmTime { - int mode; /* 0 - if valid set - * use values, - * clear valid - * 1 - if valid set - * if count before and after read of - * values is equal, - * use values - * clear valid - */ - int count; - time_t clockTimeStampSec; /* external clock */ - int clockTimeStampUSec; /* external clock */ - time_t receiveTimeStampSec; /* internal clock, when external value was received */ - int receiveTimeStampUSec; /* internal clock, when external value was received */ - int leap; - int precision; - int nsamples; - int valid; - int dummy[10]; + int mode; /* 0 - if valid is set: + * use values, + * clear valid + * 1 - if valid is set: + * if count before and after read of data is equal: + * use values + * clear valid + */ + volatile int count; + time_t clockTimeStampSec; + int clockTimeStampUSec; + time_t receiveTimeStampSec; + int receiveTimeStampUSec; + int leap; + int precision; + int nsamples; + volatile int valid; + unsigned clockTimeStampNSec; /* Unsigned ns timestamps */ + unsigned receiveTimeStampNSec; /* Unsigned ns timestamps */ + int dummy[8]; };</pre> + <h4>Operation mode=0</h4> - <p>When the poll-method of the driver is called, the valid-flag of the shared memory-segment is checked:</p> - <p>If set, the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are passed to ntp, and the valid-flag is cleared.</p> - <p>If not set, a timeout is reported to ntp, nothing else happend</p> + <p>Each second, the value of <code>valid</code> of the shared memory-segment is checked:</p> + <p>If set, the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are passed to <i>NTPD</i>, and <code>valid</code> is cleared and <code>count</code> is bumped.</p> + <p>If not set, <code>count</code> is bumped.</p> <h4>Operation mode=1</h4> - <p>When the poll-method of the driver is called, the valid-flag of the shared memory-segment is checked:</p> - <p>If set, the count-field of the record is remembered, and the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are read. Then, the remembered count is compared to the count now in the record. If both are equal, the values read from the record are passed to ntp. If they differ, another process has modified the record while it was read out (was not able to produce this case), and failure is reported to ntp. The valid flag is cleared.</p> - <p>If not set, a timeout is reported to ntp, nothing else happend</p> - <h4>Fudge Factors</h4> + <p>Each second, <code>valid</code> in the shared memory-segment is checked:</p> + <p>If set, the <code>count</code> field of the record is remembered, and the values in the record (clockTimeStampSec, clockTimeStampUSec, receiveTimeStampSec, receiveTimeStampUSec, leap, precision) are read. Then, the remembered <code>count</code> is compared to current value of <code>count</code> now in the record. If both are equal, the values read from the record are passed to <i>NTPD</i>. If they differ, another process has modified the record while it was read out (was not able to produce this case), and failure is reported to <i>NTPD</i>. The <code>valid</code> flag is cleared and <code>count</code> is bumped.</p> + <p>If not set, <code>count</code> is bumped</p> + +<h4>Mode-independent post-processing</h4> +After the time stamps have been successfully plucked from the SHM +segment, some sanity checks take place: +<ul> + <li>The receive time stamp of the SHM data must be in the last 5 + seconds before the time the data is processed. This helps in weeding + out stale data. + <li>If the absolute difference between remote and local clock + exceeds the limit (either <i>time2</i> or the default of 4hrs), then + the sample is discarded. This check is disabled when <i>flag1</i> is + set to 1. +</ul> + +<h4>GPSD</h4> + +<a href="http://gpsd.berlios.de/"><i>GPSD</i></a> +knows how to talk to many GPS devices. +It can work with <i>NTPD</i> through the SHM driver. +<P> +The <i>GPSD</i> man page suggests setting minpoll and maxpoll to 4. +That was an attempt to reduce jitter. +The SHM driver was fixed (ntp-4.2.5p138) to collect data each second rather than +once per polling interval so that suggestion is no longer reasonable. +<P> + <b>Note:</b> The <i>GPSD</i> client driver (type 46) uses the <i>GPSD</i> + client protocol to connect and talk to <i>GPSD</i>, but using the + SHM driver is the ancient way to have <i>GPSD</i> talk to <i>NTPD</i>. There + are some tricky points when using the SHM interface to interface + with <i>GPSD</i>, because <i>GPSD</i> will use two SHM clocks, one for the + serial data stream and one for the PPS information when + available. Receivers with a loose/sloppy timing between PPS and serial data + can easily cause trouble here because <i>NTPD</i> has no way to join the two + data streams and correlate the serial data with the PPS events. +</p> +<p> + +<h4>Clockstats</h4> +If flag4 is set when the driver is polled, a clockstats record is written. +The first 3 fields are the normal date, time, and IP address common to all clockstats records. +<P> +The 4th field is the number of second ticks since the last poll. +The 5th field is the number of good data samples found. The last 64 will be used by <i>NTPD</i>. +The 6th field is the number of sample that didn't have valid data ready. +The 7th field is the number of bad samples. +The 8th field is the number of times the the mode 1 info was update while <i>NTPD</i> was trying to grab a sample. +<P> + +Here is a sample showing the GPS reception fading out: +<pre> +54364 84927.157 127.127.28.0 66 65 1 0 0 +54364 84990.161 127.127.28.0 63 63 0 0 0 +54364 85053.160 127.127.28.0 63 63 0 0 0 +54364 85116.159 127.127.28.0 63 62 1 0 0 +54364 85180.158 127.127.28.0 64 63 1 0 0 +54364 85246.161 127.127.28.0 66 66 0 0 0 +54364 85312.157 127.127.28.0 66 50 16 0 0 +54364 85375.160 127.127.28.0 63 41 22 0 0 +54364 85439.155 127.127.28.0 64 64 0 0 0 +54364 85505.158 127.127.28.0 66 36 30 0 0 +54364 85569.157 127.127.28.0 64 0 64 0 0 +54364 85635.157 127.127.28.0 66 0 66 0 0 +54364 85700.160 127.127.28.0 65 0 65 0 0 +</pre> + + <h4>The 'mode' word</h4> + + <p> + Some aspects of the driver behavior can be adjusted by setting bits of + the 'mode' word in the server configuration line:<br> + <tt>server 127.127.28.</tt><i>x</i><tt> mode </tt><i>Y</i> + </p> + + <table border="1" width="100%"> + <caption>mode word bits and bit groups</caption> + <tbody><tr> + <th align="center">Bit</th> + <th align="center">Dec</th> + <th align="center">Hex</th> + <th align="left">Meaning</th> + </tr> + + <tr> + <td align="center">0</td> + <td align="center">1</td> + <td align="center">1</td> + <td>The SHM segment is private (mode 0600). This is the fixed + default for clock units 0 and 1; clock units >1 are mode + 0666 unless this bit is set for the specific unit.</td> + </tr><tr> + <td align="center">1-31</td> + <td align="center">-</td> + <td align="center">-</td> + <td><i>reserved -- do not use</i></td> + </tr> + </tbody> + </table> + + <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. + <dd>Maximum allowed difference between remote and local + clock, in seconds. Values <1.0 or >86400.0 are ignored, and the + default value of 4hrs (14400s) is used instead. See also flag 1. <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>SHM</tt>. <dt><tt>flag1 0 | 1</tt> - <dd>Not used by this driver. + <dd><i>Skip</i> the difference limit check if set. Useful + for systems where the RTC backup cannot keep the time over + long periods without power and the SHM clock must be able + to force long-distance initial jumps. <i>Check</i> the + difference limit if cleared (default). <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. - <h4>Additional Information</h4> - <p><a href="../refclock.html">Reference Clock Drivers</a></p> + <dd>If flag4 is set, clockstats records will be written when the driver is polled. </dl> + + <h4>Public vs. Private SHM segments</h4> + + <p>The driver attempts to create a shared memory segment with an + identifier depending on the unit number. This identifier (which can be + a numeric value or a string) clearly depends on the method used, which + in turn depends on the host operating system:</p> + + <ul> + <li><p> + <tt>Windows</tt> uses a file mapping to the page file with the + name '<tt>Global\NTP</tt><i>u</i>' for public accessible + mappings, where <i>u</i> is the clock unit. Private / + non-public mappings are created as + '<tt>Local\NTP</tt><i>u</i>'. + </p><p> + Public access assigns a NULL DACL to the memory mapping, while + private access just uses the default DACL of the process creating + the mapping. + </p> + </li> + <li><p> + <tt>SYSV IPC</tt> creates a shared memory segment with a key value + of <tt>0x4E545030</tt> + <i>u</i>, where <i>u</i> is again + the clock unit. (This value could be hex-decoded as 'NTP0', + 'NTP1',..., with funny characters for units > 9.) + </p><p> + Public access means a permission set of 0666, while private access + creates the mapping with a permission set of 0600. + </p> + </li> + </ul> + + <p>There's no support for POSIX shared memory yet.</p> + + <p><i>NTPD</i> is started as root on most POSIX-like operating systems + and uses the setuid/setgid system API to run under reduced rights once + the initial setup of the process is done. One consequence out of this + is that the allocation of SHM segments must be done early during the + clock setup. The actual polling of the clock is done as the run-time + user; deferring the creation of the SHM segment to this point will + create a SHM segment owned by the runtime-user account. The internal + structure of <i>NTPD</i> does not permit the use of a fudge flag if + this is to be avoided; this is the reason why a mode bit is used for + the configuration of a public segment. + </p> + + <p>When running under Windows, the chosen user account must be able to + create a SHM segment in the global object name space for SHM clocks with + public access. Otherwise the session isolation used by Windows kernels + after WinXP will get into the way if the client program does not run in + the same session. + </p> + + <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 +</html> + diff --git a/contrib/ntp/html/drivers/driver29.html b/contrib/ntp/html/drivers/driver29.html index 479978f..4939d80 100644 --- a/contrib/ntp/html/drivers/driver29.html +++ b/contrib/ntp/html/drivers/driver29.html @@ -4,15 +4,27 @@ <head> <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> - <title>Trimble Palisade Receiver</title> + <title>Trimble Palisade and Thunderbolt Receivers</title> <link href="scripts/style.css" type="text/css" rel="stylesheet"> </head> <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> - <h1><font size="+2">Trimble Palisade Receiver</font> + <h1><font size="+2">Trimble Palisade and Thunderbolt Receivers</font> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> </h1> + <table> + <tr> + <td> <h2><img src="../pic/driver29.gif" alt="gif" nosave height="100" width="420"></h2> + </td> + <td> + <h2><img src="../pic/thunderbolt.jpg" alt="jpg" nosave height="270" width="420"></h2> + </td> + </tr> + </table> <h2><font size="+1">Synopsis</font></h2> <table> <tr> @@ -50,12 +62,20 @@ </td> <td><b>9600 baud, 8-bits, 1-stop, odd parity</b></td> </tr> + <tr> + <td> + <div align="right"> + <tt><font size="+1">Serial I/O (Thunderbolt):</font></tt></div> + </td> + <td><b>9600 baud, 8-bits, 1-stop, no parity</b></td> + </tr> </table> <h2><font size="+1">Description</font></h2> The <b>refclock_palisade</b> driver supports <a href="http://www.trimble.com/products/ntp">Trimble Navigation's Palisade Smart Antenna GPS receiver</a>.<br> Additional software and information about the Palisade GPS is available from: <a href="http://www.trimble.com/oem/ntp">http://www.trimble.com/oem/ntp</a>.<br> Latest NTP driver source, executables and documentation is maintained at: <a href="ftp://ftp.trimble.com/pub/ntp">ftp://ftp.trimble.com/pub/ntp</a> <p>This documentation describes version 7.12 of the GPS Firmware and version 2.46 (July 15, 1999) and later, of the driver source.<br> </p> + <p>This documentation describes version 1 of the Thunderbolt Receiver Firmware, no tests have been made on further firmwares, please read "Notes on the Thunderbolt Receiver's Firmware" at the end of this documentation for more information.</p> <h2><font size="+1">Operating System Compatibility</font></h2> The Palisade driver has been tested on the following software and hardware platforms:<br> <center> @@ -97,7 +117,8 @@ <td>20 us</td> </tr> </table> - </center> + </center><P> + <b>Attention</b>: Thunderbolt Receiver has not being tested on the previous software and hardware plataforms. <h2><font size="+1">GPS Receiver</font></h2> The Palisade GPS receiver is an 8-channel smart antenna, housing the GPS receiver, antenna and interface in a single unit, and is designed for rooftop deployment in static timing applications. <p>Palisade generates a PPS synchronized to UTC within +/- 100 ns. The Palisade's external event input with 40 nanosecond resolution is utilized by the Palisade NTP driver for asynchronous precision time transfer.</p> @@ -199,6 +220,19 @@ <tt># and set flag2 to turn off event polling.</tt><br> <tt><a href="#flag2">fudge 127.127.29.0 flag2 1</a></tt><br> <tt>#------------------------------------------------------------------------------</tt><br> </p> + + <h4>Thunderbolt NTP Configuration file</h4> + <tt>#------------------------------------------------------------------------------</tt> + <p>Configuration without event polling:<br> + <tt>#------------------------------------------------------------------------------</tt><br> + <tt># The Primary reference</tt><br> + <tt>server 127.127.29.0 mode 2 # Trimble Thunderbolt GPS (Stratum 1).</tt><br> + <tt># Set packet delay</tt><br> + <tt><a href="#time1">fudge 127.127.29.0 time1 0.020</a></tt><br> + <tt># and set flag2 to turn off event polling.</tt><br> + <tt><a href="#flag2">fudge 127.127.29.0 flag2 1</a></tt><br> + <tt>#------------------------------------------------------------------------------</tt><br> </p> + Currently the Thunderbolt mode doesn't support event polling, the reasons are explained on the "Notes on the Thunderbolt Receiver's Firmware" section at the end of this documentation. <h2><a name="TimeTransfer"></a><font size="+1">Time Transfer and Polling</font></h2> Time transfer to the NTP host is performed via the Palisade's comprehensive time packet output. The time packets are output once per second, and whenever an event timestamp is requested. <p>The driver requests an event time stamp at the end of each polling interval, by pulsing the RTS (request to send) line on the serial port. The Palisade GPS responds with a time stamped event packet.</p> @@ -235,7 +269,7 @@ <h2><font size="+1">Mode Parameter</font></h2> <dl> <dt><tt><font size="+1">mode <i>number</i></font></tt> - <dd>The mode parameter to the server command specifies the specific hardware this driver is for. The default is 0 for a normal Trimble Palisade. The only other option at this time is 1 for a Endrun Praecis in Trimble emulation mode. + <dd>The mode parameter to the server command specifies the specific hardware this driver is for. The default is 0 for a normal Trimble Palisade. The other options are <b>1</b> for an <b>Endrun Praecis</b> in Trimble emulation mode, and <b>2</b> for the <b>Trimble Thunderbolt</b> GPS Disciplined Clock Receiver. </dl> <h2><font size="+1">DEFINEs</font></h2> The following constants are defined in the driver source code. These defines may be modified to improve performance or adapt to new operating systems.<br> @@ -369,6 +403,7 @@ </tr> </table> </center> + <blockquote> <h4>Leap Second Flag Definition:</h4>Bit 0: (1) UTC Time is available<br> Bits 1 - 3: Undefined<br>Bit 4: (1) Leap Scheduled: Leap second pending asserted by GPS control segment.<br>Bit 5: (1) Leap Pending: set 24 hours before, until beginning of leap second.<br>Bit 6: (1) GPS Leap Warning: 6 hours before until 6 hours after leap event<br>Bit 7: (1) Leap In Progress. Only set during the leap second. @@ -576,6 +611,281 @@ </tr> </table> </center> + <h3>Thunderbolt Timing packets Data Format</h3> + Thunderbolt can output 2 synchronous packets. + <h4><b>Primary Timing Packet - 0x8FAB</h4> + <center> + <table> + <tr> + <td><b>Byte</b></td> + <td><b>Bit</b></td> + <td><b>Item</b></td> + <td><b>Type</b></td> + <td><b>Value</b></td> + <td><b>Description</b></td> + </tr> + <tr> + <td>0</td> + <td></td> + <td>Subcode</td> + <td>UINT8</td> + <td></td> + <td>0xAB</td> + </tr> + <tr> + <td>1-4</td> + <td></td> + <td>Time of Week</td> + <td>UINT32</td> + <td></td> + <td>GPS seconds of week</td> + </tr> + <tr> + <td>5-6</td> + <td></td> + <td>Week Number</td> + <td>UINT16</td> + <td></td> + <td>GPS Week Number</td> + </tr> + <tr> + <td>7-8</td> + <td></td> + <td>UTC Offset</td> + <td>SINT16</td> + <td></td> + <td>UTC Offset (seconds)</td> + </tr> + <tr> + <td valign="top">9</td> + <td><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>2</td></tr><tr><td>3</tr><tr><td>4</tr></table></td> + <td valign="top">Timing Flag</td> + <td valign="top">Bit field</td> + <td valign="top"><table><tr><td>0 or 1</td></tr><tr><td>0 or 1</td></tr><tr><td>0 or 1</td></tr><tr><td>0 or 1</tr><tr><td>0 or 1</tr></table></td></td> + <td valign="top"><table><tr><td>GPS Time or UTC Time</td></tr><tr><td>GPS PPS or UTC PPS</td></tr><tr><td>time is set or time is not set</td></tr><tr><td>have UTC info or no UTC info</td></tr><tr><td>Time from GPS or time from user</td></tr></table></td> + </tr> + <tr> + <td>10</td> + <td></td> + <td>Seconds</td> + <td>UINT8</td> + <td>0-59</td> + <td>(60 for UTC leap second event)</td> + </tr> + <tr> + <td>11</td> + <td></td> + <td>Minutes</td> + <td>UINT8</td> + <td>0-59</td> + <td>Minutes of Hour</td> + </tr> + <tr> + <td>12</td> + <td></td> + <td>Hours</td> + <td>UINT8</td> + <td>0-23</td> + <td>Hour of Day</td> + </tr> + <tr> + <td>13</td> + <td></td> + <td>Day of Month</td> + <td>UINT8</td> + <td>1-31</td> + <td>Day of Month</td> + </tr> + <tr> + <td>14</td> + <td></td> + <td>Month</td> + <td>UINT8</td> + <td>1-12</td> + <td>Month of Year</td> + </tr> + <tr> + <td>15-16</td> + <td></td> + <td>Year</td> + <td>UINT16</td> + <td></td> + <td>Four digits of Year (e.g. 1998)</td> + </tr> + </table> + </center> + <h4><b>Supplemental Timing Packet - 0x8FAC</h4> + <center> + <table> + <tr> + <td><b>Byte</b></td> + <td><b>Bit</b></td> + <td><b>Item</b></td> + <td><b>Type</b></td> + <td><b>Value</b></td> + <td><b>Description</b></td> + </tr> + <tr> + <td>0</td> + <td></td> + <td>Subcode</td> + <td>UINT8</td> + <td></td> + <td>0xAC</td> + </tr> + <tr> + <td valign="top">1</td> + <td></td> + <td valign="top">Receiver Mode</td> + <td valign="top">UINT8</td> + <td valign="top"><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>2</td></tr><tr><td>3</td></tr><tr><td>4</td></tr><tr><td>5</td></tr><tr><td>6</td></tr></table></td> + <td valign="top"><table><tr><td>Automatic (2D/3D)</td></tr><tr><td>Single Satellite (Time)</td></tr><tr><td>Horizontal (2D)</td></tr><tr><td>Full Position (3D)</td></tr><tr><td>DGPS Reference</td></tr><tr><td>Clock Hold (2D)</td></tr><tr><td>Overdetermined Clock</td></tr></table></td> + </tr> + <tr> + <td valign="top">2</td> + <td></td> + <td valign="top">Disciplining Mode</td> + <td valign="top">UINT8</td> + <td valign="top"><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>2</td></tr><tr><td>3</td></tr><tr><td>4</td></tr><tr><td>5</td></tr><tr><td>6</td></tr></table></td> + <td valign="top"><table><tr>Normal<td></td></tr><tr><td>Power-Up</td></tr><tr><td>Auto Holdover</td></tr><tr><td>Manual Holdover</td></tr><tr><td>Recovery</td></tr><tr><td>Not Used</td></tr><tr><td>Disciplining disabled</td></tr></table></td> + </tr> + <tr> + <td>3</td> + <td></td> + <td>Self-Survey Progress</td> + <td>UINT 8</td> + <td>0-100%</td> + <td></td> + <tr> + <td>4-7</td> + <td></td> + <td>Holdover Duration</td> + <td>UINT 32</td> + <td></td> + <td>seconds</td> + </tr> + <tr> + <td valign="top">8-9</td> + <td><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>2</td></tr><tr><td>3</tr><tr><td>4</tr></table></td> + <td valign="top">Critical Alarms</td> + <td valign="top">UINT16</td> + <td valign="top">Bit field</td> + <td valign="top"><table><tr><td>ROM checksum error</td></tr><tr><td>RAM check has failed</td></tr><tr><td>Power supply failure</td></tr><tr><td>FPGA check has failed</td></tr><tr><td>Oscillator control voltage at rail</td></tr></table></td> + </tr> + <tr> + <td valign="top">10-11</td> + <td valign="top"><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>2</td></tr><tr><td>3</tr><tr><td>4</tr><tr><td>5</td></tr><tr><td>6</td></tr></table></td> + <td valign="top">Minor Alarms</td> + <td valign="top">UINT16</td> + <td valign="top">Bit field</td> + <td valign="top"><table><tr><td>Normal</td></tr><tr><td>Power-Up</td></tr><tr><td>Auto Holdover</td></tr><tr><td>Manual Holdover</tr><tr><td>Recovery</tr><tr><td>Not Used</td></tr><tr><td>Disciplining disabled</td></tr></table></td> + </tr> + <tr> + <td valign="top">12</td> + <td></td> + <td valign="top">GPS Decoding Status</td> + <td valign="top">UINT8</td> + <td valign="top"><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>3</td></tr><tr><td>8</tr><tr><td>9</tr><tr><td>0x0A</td></tr><tr><td>0x0B</td></tr><tr><td>0x0C</td></tr><tr><td>0x10</tr></table></td> + <td valign="top"><table><tr><td>Doing fixes</td></tr><tr><td>Don t have GPS time</td></tr><tr><td>PDOP is too high</td></tr><tr><td>No usable sats</tr><tr><td>Only 1 usable sat</tr><tr><td>Only 2 usable sats</td></tr><tr><td>Only 3 usable sats</td></tr><tr><td>The chosen sat is unusable</td></tr><tr><td>TRAIM rejected the fix</tr></table></td> + </tr> + <tr> + <td valign="top">13</td> + <td></td> + <td valign="top">Disciplining Activity</td> + <td valign="top">UINT8</td> + <td><table><tr><td>0</td></tr><tr><td>1</td></tr><tr><td>2</td></tr><tr><td>3</tr><tr><td>4</tr><tr><td>5</td></tr><tr><td>6</td></tr><tr><td>7</td></tr><tr><td>8</tr></table></td> + <td><table><tr><td>Phase locking</td></tr><tr><td>Oscillator warming up</td></tr><tr><td>Frequency locking</td></tr><tr><td>Placing PPS</tr><tr><td>Initializing loop filter</tr><tr><td>Compensating OCXO</td></tr><tr><td>Inactive</td></tr><tr><td>Not used</td></tr><tr><td>Recovery mode</tr></table></td> + </tr> + <tr> + <td>14</td> + <td></td> + <td>Spare Status 1</td> + <td>UINT8</td> + <td>0</td> + <td></td> + </tr> + <tr> + <td>15</td> + <td></td> + <td>Spare Status 2</td> + <td>UINT8</td> + <td>0</td> + <td></td> + </tr> + <tr> + <td>16-19</td> + <td></td> + <td>PPS Offset</td> + <td>Single</td> + <td></td> + <td>Estimate of UTC/GPS offset (ns)</td> + </tr> + <tr> + <td>20-23</td> + <td></td> + <td>10 MHz Offset</td> + <td>Single</td> + <td></td> + <td>Estimate of UTC/GPS offset (ns)</td> + </tr> + <tr> + <td>24-27</td> + <td></td> + <td>DAC Value</td> + <td>UINT32</td> + <td></td> + <td>Offset binary (0x00 - 0xFFFFF)</td> + </tr> + <tr> + <td>28-31</td> + <td></td> + <td>DAC Voltage</td> + <td>Single</td> + <td></td> + <td>Volts</td> + </tr> + <tr> + <td>32-35</td> + <td></td> + <td>Temperature</td> + <td>Single</td> + <td></td> + <td>degrees C</td> + </tr> + <tr> + <td>36-43</td> + <td></td> + <td>Latitude</td> + <td>Double</td> + <td></td> + <td>radians</td> + </tr> + <tr> + <td>44-51</td> + <td></td> + <td>Longitude</td> + <td>Double</td> + <td></td> + <td>radians</td> + </tr> + <tr> + <td>52-59</td> + <td></td> + <td>Altitude</td> + <td>Double</td> + <td></td> + <td>Meters</td> + </tr> + <tr> + <td>60-67</td> + <td></td> + <td>Spare</td> + <td></td> + <td></td> + <td>For Future Expantion</td> + </tr> + </table> + </center> <h2><a name="Pinouts"></a><font size="+1">Pinouts</font></h2> <a href="#Connection">The following connections are required when connecting Palisade with a host:</a><br> <br> <center> @@ -762,15 +1072,22 @@ </tr> </table> </center> + + <b><h3>Notes on the Thunderbolt Receiver's Firmware</h3></b> + + The support for Thunderbolt Receiver in the palisade driver doesn't support (for now) event-polling, the reason is that the Thunderbolt receiver the patch is written for doesn't support time-on-request, so you just have to sit there and wait for the time to arrive with the PPS. We tried to contact Trimble because there's presumably a firmware update that support it, but we didn't have much luck. +Here is a link explaining the situation:<p> +<a href="https://lists.ntp.isc.org/pipermail/hackers/2006-April/002216.html">https://lists.ntp.isc.org/pipermail/hackers/2006-April/002216.html <p></p> <hr> <p>Questions or Comments:<br> <a href="mailto:sven_dietrich@trimble.com">Sven Dietrich</a><br> <a href="http://www.trimble.com/">Trimble Navigation Ltd.</a></p> - <p>(last updated July 29, 1999)</p> + <a href="mailto:fernandoph@iar.unlp.edu.ar">Fernando P. Hauscarriaga</a><br> + <p>(last updated January 15, 2007)</p> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> ; </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver3.html b/contrib/ntp/html/drivers/driver3.html index e5a06be..457e5a2 100644 --- a/contrib/ntp/html/drivers/driver3.html +++ b/contrib/ntp/html/drivers/driver3.html @@ -1,28 +1,29 @@ <!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 -->11-Sep-2010 05:56<!-- #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> @@ -45,32 +46,31 @@ T = transmitter (C = WWV, H = WWVH) 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> diff --git a/contrib/ntp/html/drivers/driver30.html b/contrib/ntp/html/drivers/driver30.html index d29dbcf..ddf9b94 100644 --- a/contrib/ntp/html/drivers/driver30.html +++ b/contrib/ntp/html/drivers/driver30.html @@ -11,6 +11,9 @@ <body> <h3>Motorola Oncore GPS receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.30.<i>u</i><br> @@ -80,4 +83,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver31.html b/contrib/ntp/html/drivers/driver31.html index aff093c..a329faf 100644 --- a/contrib/ntp/html/drivers/driver31.html +++ b/contrib/ntp/html/drivers/driver31.html @@ -11,6 +11,9 @@ <body> <h3>Rockwell Jupiter GPS receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.31.<i>u</i><br> @@ -55,4 +58,4 @@ </html> -=
\ No newline at end of file += diff --git a/contrib/ntp/html/drivers/driver32.html b/contrib/ntp/html/drivers/driver32.html index 9479248..8cb810a 100644 --- a/contrib/ntp/html/drivers/driver32.html +++ b/contrib/ntp/html/drivers/driver32.html @@ -10,6 +10,9 @@ <body> <h3>Chrono-log K-series WWVB receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.32.<i>u</i><br> @@ -30,9 +33,8 @@ L - \n (newline) Z - timestamp indicator hh:mm:ss - local time </pre> - <!-- hhmts start -->Last modified: Sun Feb 14 11:57:27 EST 1999 <!-- hhmts end --> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver33.html b/contrib/ntp/html/drivers/driver33.html index f50dfb63..6142f53 100644 --- a/contrib/ntp/html/drivers/driver33.html +++ b/contrib/ntp/html/drivers/driver33.html @@ -10,6 +10,9 @@ <body> <h3>Dumb Clock</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.33.<i>u</i><br> @@ -27,9 +30,7 @@ C - \r (carriage return) L - \n (newline) </pre> <hr> - <!-- hhmts start -->Last modified: Sun Feb 14 12:07:01 EST 1999 <!-- hhmts end --> - <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver34.html b/contrib/ntp/html/drivers/driver34.html index a98fad8..65ce819 100644 --- a/contrib/ntp/html/drivers/driver34.html +++ b/contrib/ntp/html/drivers/driver34.html @@ -1,117 +1,82 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<!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>Ultralink Clock</title> - <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> - <link <link href="scripts/style.css" type="text/css" rel="stylesheet"> </HEAD> <BODY> <H3> Ultralink Clock</H3> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> + + <body> + <h3>Ultralink Clock</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->31-Dec-2007 19:43<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> - Address: 127.127.34.<i>u</i><br> - Reference ID: <tt>WWVB</tt><br> - Driver ID: <tt>ULINK</tt><br> - Serial Port: <tt>/dev/wwvb<i>u</i></tt>; 9600 bps, 8-bits, no parity<br> - <br> - Features: <tt>(none)</tt> + <p>Address: 127.127.34.<i>u</i><br> + Reference ID: <tt>WWVB</tt><br> + Driver ID: <tt>ULINK</tt><br> + Serial Port: <tt>/dev/wwvb<i>u</i></tt>; 9600 bps, 8-bits, no parity<br> + Features: <tt>(none)</tt></p> <h4>Description</h4> - <p>This driver supports the Ultralink Model 325 (replacement for Model 320) RS-232 powered WWVB receiver. PDF specs available on <a href="http://www.ulio.com/">http://www.ulio.com/</a>. This driver also supports the Model 320, 330,331,332 decoders in both polled or continous time code mode.<br> - Leap second and quality are supported.</p> - <p>Most of this code is originally from refclock_wwvb.c with thanks. Any mistakes are mine. Any improvements are welcome.</p> - <hr> - <pre> The Model 325 timecode format is: - - <cr><lf>RQ_1C00LYYYY+DDDUTCS_HH:MM:SSL+5 - - where: - - R = Signal readability indicator, ranging from R1 to R5 - Q R1 is unreadable, R5 is best reception - _ = Space - 1 = prev. received data bit, values: 0, 1 ,M or ? unknown - C = Signal reception from (C)olorado or (H)awaii - 0 = Hours since last WWVB time and flag code update, values - 0 00 to 99 (hopefully always 00) - L = HEX A5 if receiver is locked to WWVB, Space if not - YYYY = Year from 2000 to 2099 - + = '+' if current year is a leap year, else ' ' - DDD = current day in the year from 1 to 365/366 - UTC = timezone (always UTC) - S = Daylight savings indicator, (S)TD, (D)ST, (O) transition - into DST, (I) transition out of DST - _ = Space - HH = UTC hour 0 to 23 - : = Time delimiter, ':' if synced, Space if not - MM = Minutes of current hour from 0 to 59 - : = Time delimiter, ':' if synced, Space if not - SS = Seconds of current minute from 0 to 59 - mm = 10's milliseconds of the current second from 00 to 99 - L = Leap second pending at end of month, (I)nsert, (D)elete - or Space - +5 = UT1 correction, +/- .1 sec increments - </pre> + <p>This driver supports the Ultralink Model 325 (replacement for Model 320) RS-232 powered WWVB receiver. PDF specs available on <a href="http://www.ulio.com/">http://www.ulio.com/</a>. This driver also supports the Model 320, 330,331,332 decoders in both polled or continous time code mode.Leap second and quality are supported. Most of this code is originally from refclock_wwvb.c with thanks. Any mistakes are mine. Any improvements are welcome.</p> + <h4>Model 325 timecode format</h4> + <p><tt><cr><lf>RQ_1C00LYYYY+DDDUTCS_HH:MM:SSL+5</tt></p> + <p>R = Signal readability indicator, ranging from R1 to R5 Q R1 is unreadable, R5 is best reception<br> + _ = Space<br> + 1 = prev. received data bit, values: 0, 1 ,M or ? unknown + C = Signal reception from (C)olorado or (H)awaii 0 = Hours since last WWVB time and flag code update, values 0 00 to 99 (hopefully always 00)<br> + L = HEX A5 if receiver is locked to WWVB, Space if not<br> + YYYY = Year from 2000 to 2099<br> + + = '+' if current year is a leap year, else ' '<br> + DDD = current day in the year from 1 to 365/366<br> + UTC = timezone (always UTC)<br> + S = Daylight savings indicator, (S)TD, (D)ST, (O) transition into DST, (I) transition out of DST<br> + _ = Space<br> + HH = UTC hour 0 to 23<br> + : = Time delimiter, ':' if synced, Space if not<br> + MM = Minutes of current hour from 0 to 59<br> + : = Time delimiter, ':' if synced, Space if not<br> + SS = Seconds of current minute from 0 to 59<br> + mm = 10's milliseconds of the current second from 00 to 99<br> + L = Leap second pending at end of month, (I)nsert, (D)elete or Space<br> + +5 = UT1 correction, +/- .1 sec increments</p> <p>Note that Model 325 reports a very similar output like Model 33X series. The driver for this clock is similar to Model 33X behavior. On a unmodified new ULM325 clock, the polling flag (flag1 =1) needs to be set.</p> - <hr> - <pre> The Model 320 timecode format is: - - <cr><lf>SQRYYYYDDD+HH:MM:SS.mmLT<cr> - - where: - - S = 'S' -- sync'd in last hour, '0'-'9' - hours x 10 since last update, else '?' - Q = Number of correlating time-frames, from 0 to 5 - R = 'R' -- reception in progress, 'N' -- Noisy reception, ' ' -- standby mode - YYYY = year from 1990 to 2089 - DDD = current day from 1 to 366 - + = '+' if current year is a leap year, else ' ' - HH = UTC hour 0 to 23 - MM = Minutes of current hour from 0 to 59 - SS = Seconds of current minute from 0 to 59 - mm = 10's milliseconds of the current second from 00 to 99 - L = Leap second pending at end of month -- 'I' = inset, 'D'=delete - T = DST <-> STD transition indicators - </pre> - <p>Note that this driver does not do anything with the T flag.</p> - <p>The M320 also has a 'U' command which returns UT1 correction information. It is not used in this driver.</p> - <hr> - <pre> The Model 33x timecode format is: - - S9+D 00 YYYY+DDDUTCS HH:MM:SSl+5 - - Where: - - S = sync indicator S insync N not in sync - the sync flag is WWVB decoder sync - nothing to do with time being correct - 9+ = signal level 0 thru 9+ If over 9 indicated as 9+ - D = data bit ( fun to watch but useless ;-) - space - 00 = hours since last GOOD WWVB frame sync - space - YYYY = current year - + = leap year indicator - DDD = day of year - UTC = timezone (always UTC) - S = daylight savings indicator - space - HH = hours - : = This is the REAL in sync indicator (: = insync) - MM = minutes - : = : = in sync ? = NOT in sync - SS = seconds - L = leap second flag - +5 = UT1 correction (sign + digit )) - </pre> - <p>This driver ignores UT1 correction,DST indicator,Leap year and signal level.</p> - <hr> + <h4>Model 320 timecode format</h4> + <p><tt><cr><lf>SQRYYYYDDD+HH:MM:SS.mmLT<cr></tt></p> + <p>S = 'S' -- sync'd in last hour, '0'-'9' - hours x 10 since last update, else '?'<br> + Q = Number of correlating time-frames, from 0 to 5<br> + R = 'R' -- reception in progress,'N' -- Noisy reception, ' ' -- standby mode<br> + YYYY = year from 1990 to 2089<br> + DDD = current day from 1 to 366 + = '+' if current year is a leap year, else ' '<br> + HH = UTC hour 0 to 23<br> + MM = Minutes of current hour from 0 to 59<br> + SS = Seconds of current minute from 0 to 59<br> + mm = 10's milliseconds of the current second from 00 to 99<br> + L = Leap second pending at end of month -- 'I' = insert, 'D'=delete<br> + T = DST <-> STD transition indicators</p> + <p>Note that this driver does not do anything with the T flag. The M320 also has a 'U' command which returns UT1 correction information. It is not used in this driver.</p> + <h4>Model 33x timecode format</h4> + <p><tt>S9+D 00 YYYY+DDDUTCS HH:MM:SSl+5</tt></p> + <p>S = sync indicator S insync N not in sync the sync flag is WWVB decoder sync nothing to do with time being correct </p> + <p>9+ = signal level 0 thru 9+ If over 9 indicated as 9<br> + D = data bit (fun to watch but useless ;-) space<br> + 00 = hours since last GOOD WWVB frame sync space<br> + YYYY = current year + = leap year indicator<br> + DDD = day of year<br> + UTC = timezone (always UTC)<br> + S = daylight savings indicator space<br> + HH = hours : = This is the REAL in sync indicator (: = insync)<br> + MM = minutes : = : = in sync ? = NOT in sync<br> + SS = seconds<br> + L = leap second flag<br> + +5 = UT1 correction (sign + digit ))</p> + <p>This driver ignores UT1 correction, DST indicator,Leap year and signal level.</p> <h4>Fudge factors</h4> <p>flag1 polling enable (1=poll 0=no poll)</p> <hr> - <address><a href="mailto:frank.migge@oracle.com">mail</a></address> - <!-- hhmts start -->Last modified: Mon Mar 8 10:12:08 PST 2004<!-- hhmts end --> - <hr> - <script type="text/javascript" language="javascript" src="Ultralink Clock_files/footer.txt"></script> - </BODY> - </head> - -</html>
\ No newline at end of file + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body> +</html> diff --git a/contrib/ntp/html/drivers/driver35.html b/contrib/ntp/html/drivers/driver35.html index 78a0881..3ded63f 100644 --- a/contrib/ntp/html/drivers/driver35.html +++ b/contrib/ntp/html/drivers/driver35.html @@ -10,6 +10,9 @@ <body> <h3>Conrad parallel port radio clock</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.35.<i>u</i><br> @@ -45,4 +48,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver36.html b/contrib/ntp/html/drivers/driver36.html index 72fa665..2b25324 100644 --- a/contrib/ntp/html/drivers/driver36.html +++ b/contrib/ntp/html/drivers/driver36.html @@ -1,146 +1,150 @@ <!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 data encoded in 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 performance of this driver when tracking one of the stations is ordinarily better than 1 ms in time with frequency drift less than 0.1 PPM when not tracking any station.<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 running on 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>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> - <p>The WWV signal format is described in NIST Special Publication 432 (Revised 1990). 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> - <h4>Program Architecture</h4> - <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 which results in 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> - <p>The analog audio signal from the shortwave radio is sampled at 8000 Hz and converted to digital representation. The 1000/1200-Hz pulses and 100-Hz subcarrier are first separated using two IIR filters, a 600-Hz bandpass filter centered on 1100 Hz and a 150-Hz lowpass filter. The minute synch 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 synch pulse is extracted using a 5-ms FIR matched filter and 8000-stage comb filter.</p> - <p>The phase of the 100-Hz subcarrier relative to the second synch 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 tracking loop to discipline the codec sample clock and thus the demodulator phase.</p> - <p>A bipolar data signal is determined from the matched filter I and Q channels using a pulse-width discriminator. The discriminator samples the I channel at 15 ms (<i>n</i>), 200 ms (<i>s</i><sub>1</sub>) and 500 ms (<i>s</i><sub>0</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 <i>s</i><sub>1</sub> - 2<i>s</i><sub>0 </sub>- <i>n.</i> Note that, since the signals <i>s</i><sub>0</sub> and <i>s</i><sub>1</sub> include the noise <i>n</i>, this term 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> - <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 selection 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> - <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. At averaging intervals determined by the measured jitter, the frequency error is calculated as the difference between the most recent and the current second epoch divided by the interval. The sample clock frequency is then corrected by this amount. When first started, the frequency averaging interval is eight 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 over 1000 seconds, which results in an ultimate frequency precision of 0.125 PPM, or about 11 ms/day.</p> - <p>It is important that the logical clock frequency is stable and accurately determined, since in most 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 aggresively 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. The number of hits declared in the last six minutes by each station represents the high order bits of the metric value, while the current minute pulse amplitude repressents the low order bits. The resulting value is then scaled from zero to 100 for use as a quality indicator. It is 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 synchronization via the HF medium is good only to a millisecond under the best propagation conditions. The performance of the NTP daemon disciplined by the driver is clearly better than this, even under marginal conditions. Ordinarily, with marginal to good signals and a frequency averaging interval of 1024 s, the frequency is stabilized within 0.1 PPM and the time within 0.5 ms. The frequency stability characteristic is highly important, since the clock may have to free-run for several hours before reacquiring the WWV/H signal.</p> - <p>The expected accuracy over a typical day was determined using the DSP93 and an oscilloscope and cesium oscillator calibrated with a GPS receiver. With marginal signals and allowing 15 minutes for initial synchronization and frequency compensation, the time accuracy determined from the WWV/H second synch pulse was reliably within 125 <font face="Symbol">m</font>s. In the particular DSP93 used for program development, the uncorrected CPU clock frequency offset was 45.8±0.1 PPM. Over the first hour after initial synchronization, the clock frequency drifted about 1 PPM as the frequency averaging interval increased to the maximum 1024 s. Once reaching the maximum, the frequency wandered over the day up to 1 PPM, but it is not clear whether this is due to the stability of the DSP93 clock oscillator or the changing height of the ionosphere. Once the frequency had stabilized and after loss of the WWV/H signal, the frequency drift was less than 0.5 PPM, which is equivalent to 1.8 ms/h or 43 ms/d. This resulted in a step phase correction up to several milliseconds when the signal returned.</p> - <p>The measured propagation delay from the WWV transmitter at Boulder, CO, to the receiver at Newark, DE, is 23.5±0.1 ms. This is measured to the peak of the pulse after the second synch comb filter and includes components due to the ionospheric propagation delay, nominally 8.9 ms, communications receiver delay and program delay. The propagation delay can be expected to change about 0.2 ms over the day, as the result of changing ionosphere height. The DSP93 program delay was measured at 5.5 ms, most of which is due to the 400-Hz bandpass filter and 5-ms matched filter. Similar delays can be expected of this driver.</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 at least three good minutes are found.<p>When a minute synch candidate has been found, the driver acquires second synch, which can take up to several minutes, depending on signal quality. At the same time the driver accumulates likelihood values for the unit (seconds) digit of the nine digits of the timecode, plus the seven miscellaneous bits included in the WWV/H transmission format. When a good unit digit has been found, the driver accumlates 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, even if all signals are losst. The time is considered correct as long as the second synch amplitude and SNR are above specified thresholds and jitter is below threshold. As long as the clock is 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 used with other local reference clocks and remote servers. Using these algorithms, the system clock can in principle be disciplined to a much finer resolution than the 125-<font face="Symbol">m</font>s sample interval would suggest, although the ultimate accuracy is probably limited by propagation delay variations as the ionspheric height varies throughout the day and night.</p> - <p>The codec clock frequency is disciplined during times when WWV/H signals are available. The algorithm refines the frequency offset using increasingly longer averaging intervals to 1024 s, where the precision is about 0.1 PPM. With good signals, it takes well over two hours to reach this degree of precision; however, it can take many more hours than this in case of marginal signals. Once reaching the limit, the algorithm will follow frequency variations due to temperature fluctuations and ionospheric height variations.</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>Once the clock has been set for the first time, it will appear reachable and selectable to discipline the system clock. Operation continues as long as the signal quality 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 reresynchronize. 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>However, as long as the clock has once been set correctly and allowed to converge to the intrinsic codec clock frequency, it will continue to read correctly even during the holdover interval, but with increasing dispersion. Assuming the 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 dispersion increases at 5 <font face="Symbol">m</font>s per second, which makes the driver appear less likely for selection as time goes on. Eventually, when the dispersion due all causes exceeds 1 s, it is no longer suitable for synchronization.</p> - <p>To work well, the driver needs a shortwave receiver with good audio response at 100 Hz. Most shortwave and communications receivers roll off the audio response below 250 Hz, so this can be a problem, especially with receivers using DSP technology, since DSP filters can have very fast rolloff outside the passband. Some DSP transceivers, in particular the ICOM 775, have a programmable low frequency cutoff which can be set as low as 80 Hz. However, this particular radio has a strong low frequency buzz at about 10 Hz which appears in the audio output and can affect data recovery under marginal conditions. Although not tested, it would seem very likely that a cheap shortwave receiver could function just as well as an expensive communications receiver.</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 serial port using a level converter such as the CT-17.</p> - <p>Each ICOM radio is assigned a unique 8-bit ID select code, usually expressed in hex format. To activate the CI-V interface, the <tt>mode</tt> keyword of the <tt>server</tt> configuration command specifies a nonzero select code in decimal format. A table of ID select codes for the known ICOM radios is given on the <a href="../audio.html">Reference Clock Audio Drivers</a> page. A missing <tt>mode</tt> keyword or a zero argument leaves the interface disabled.</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 or radio 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 minute synch pulse amplitude and SNR in second 0 and data pulse amplitude and SNR in second 1 to update the signal metric. In principle, the data pulse in second 58 is usable, but the AGC in most radios is not fast enough for a reliable measurement. 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>At the end of each probe, the frequency and station with the maximum metric is chosen, with 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 below, the rotating probes continue until a valid station is found.</p> - <dl> - </dl> - <h4>Diagnostics</h4> - <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 ampliture/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> minute pulse ampliture/SNR. An example is:</p> - <p><tt>wwv5 000d 111 5753 3967/20.1 3523/10.2 WV20 bdeff 100 8348/30.0 WH20 0000 1 22/-12.4</tt></p> - <p>There are several other messages that can occur; these are documented in the source listing.</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> - <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 ld du lset agc ident metric errs freq avg<br> - s</tt> synch indicator (<tt>?</tt> or space) - <tt>q </tt>quality character (see below) - <tt>yyyy </tt>Gregorian year - <tt>ddd </tt>day of year - <tt>hh </tt>hour of day - <tt>mm </tt>minute of hour - <tt>l </tt>leap second warning <tt>L</tt> - <tt>d </tt>DST state <tt>S, D, I, O</tt><br> - <tt>dut </tt>DUT sign and magnitude - <tt>lset </tt>minutes since last set - <tt>agc </tt>audio gain - <tt>ident </tt>station identifier and frequency - <tt>metric </tt>signal metric (0-100) - <tt>errs </tt>data bit errors in last minute - <tt>freq </tt>codec frequency offset (PPM) - <tt>avg </tt>frequency averaging interval (s) -</p> - 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 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 condition that may result in an error. However, the local clock update is not suppressed if any alarm bits are set other than a synch alarm.<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 of June or December. - <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>dut</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 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>avgt</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 -->15-Nov-2012 06:42<!-- #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 μ-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 μ-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 μ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 μ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 μ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 μ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> diff --git a/contrib/ntp/html/drivers/driver37.html b/contrib/ntp/html/drivers/driver37.html index 3bd5085..c87a82f 100644 --- a/contrib/ntp/html/drivers/driver37.html +++ b/contrib/ntp/html/drivers/driver37.html @@ -10,6 +10,9 @@ <body> <h3>Forum Graphic GPS Dating station</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> <p>Address: 127.127.37.<i>u</i><br> @@ -48,4 +51,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver38.html b/contrib/ntp/html/drivers/driver38.html index 283e38f..445d70d 100644 --- a/contrib/ntp/html/drivers/driver38.html +++ b/contrib/ntp/html/drivers/driver38.html @@ -10,6 +10,9 @@ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> <h1><font face="Arial"><i><blink><font size="5">hopf</font></blink></i><font size="+2"> </font><font size="3">Serial Line Receivers (6021 and kompatible)</font></font></h1> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h2><font size="+1">Synopsis</font></h2> <table width="100%"> @@ -110,7 +113,7 @@ <hr> <h2><font size="+1">Fudge Factors</font></h2> <dl> - <dt><b><a name="time1"></a><tt><font size="+1"><a href="#Configuration">time1 <i>time</i></a></font></tt></b> + <dt><b><tt><font size="+1">time1 <i>time</i></font></tt></b> <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0. Should be set to 20 milliseconds to correct serial line and operating system delays incurred in capturing time stamps from the synchronous packets. <dt><tt><font size="+1"><a href="#REFID"><b>refid <i>string</i></b></a></font></tt> <dd>Specifies the driver reference identifier, <b>GPS </b><i>or</i> <b>DCF</b>. @@ -123,9 +126,8 @@ <hr> <h3>Questions or Comments:</h3> <p><a href="mailto:altmeier@atlsoft.de">Bernd Altmeier</a><a href="http://www.ATLSoft.de"><br>Ing.-Büro für Software www.ATLSoft.de</a></p> - <p>(last updated 02/28/2001)<br> </p> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver39.html b/contrib/ntp/html/drivers/driver39.html index 482134e..9e1605f 100644 --- a/contrib/ntp/html/drivers/driver39.html +++ b/contrib/ntp/html/drivers/driver39.html @@ -10,6 +10,9 @@ <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> <h1><font face="Arial"><i><blink><font size="5">hopf</font></blink></i><font size="+2"> </font><font size="3">PCI-Bus Receiver (6039 GPS/DCF77)</font></font></h1> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <div align="center"> <center> @@ -105,9 +108,8 @@ <hr> <h3>Questions or Comments:</h3> <p><a href="mailto:altmeier@atlsoft.de">Bernd Altmeier</a><a href="http://www.ATLSoft.de"><br>Ing.-Büro für Software www.ATLSoft.de</a></p> - <p>(last updated 03/02/2001)<br> </p> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver4.html b/contrib/ntp/html/drivers/driver4.html index bda4a10..2139289 100644 --- a/contrib/ntp/html/drivers/driver4.html +++ b/contrib/ntp/html/drivers/driver4.html @@ -1,66 +1,76 @@ <!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 8170 and Netclock/2 WWVB Receivers</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Spectracom 8170 and Netclock/2 WWVB Receivers</h3> - <hr> - <h4>Synopsis</h4> - 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: <tt>tty_clk</tt> - <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 usec 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> - <p>on-time = first <cr><br> - 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> - <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> - <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>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 dayis received.</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>WWVB</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> - <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>Spectracom WWVB/GPS Receivers</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +<style type="text/css"> +<!-- +.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 -->11-Sep-2010 05:56<!-- #EndDate --> + UTC</p> +<hr> +<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> +<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> +<p>on-time = first <cr><br> + 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> +<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> +<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> +<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></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> diff --git a/contrib/ntp/html/drivers/driver40-ja.html b/contrib/ntp/html/drivers/driver40-ja.html new file mode 100644 index 0000000..8b67e90 --- /dev/null +++ b/contrib/ntp/html/drivers/driver40-ja.html @@ -0,0 +1,534 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + +<html lang="ja"> + + <head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"> + <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Style-Type" content="text/css"> + <meta http-equiv="Content-Script-Type" content="text/javascript"> + <title>JJY Receivers</title> + <link rev="made" href="http://www.bea.hi-ho.ne.jp/abetakao/"> + <link rel="start" href="http://www.eecis.udel.edu/~mills/ntp/html/refclock.html"> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> + + <body> + <h3>JJY Receivers</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->15-May-2015 00:00<!-- #EndDate --> + UTC <a href="driver40.html">ENGLISH(英語)</a> <a href="driver40-ja.html">JAPANESE(日本語)</a></p> + <hr> + <h4>Synopsis</h4> + Address: 127.127.40.<em>u</em><br> + Reference ID: <code>JJY</code><br> + Driver ID: <code>JJY</code><br> + Serial Port: <code>/dev/jjy<em>u</em></code>; ãã‚Œãžã‚Œã®JJYå—ä¿¡æ©Ÿã€GPS時計ã€ãƒ†ãƒ¬ãƒ•ã‚©ãƒ³JJYã‚’å‚ç…§ã—ã¦ä¸‹ã•ã„。 + <h4>Description</h4> + <p>ã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã¯ã€ä»¥ä¸‹ã®ã€æ—¥æœ¬ã§è²©å£²ã•ã‚Œã¦ã„ã‚‹ JJYå—ä¿¡æ©Ÿã€GPS時計ã¨ã€é›»è©±å›žç·šã«ã‚ˆã‚‹æ™‚刻é…信サービスをサãƒãƒ¼ãƒˆã—ã¦ã„ã¾ã™ã€‚ + </p> + <table width="100%"> + <tr> + <td width="50%" style="vertical-align:top;"> + <a href="#mode-1">トライステート TS-JJY01, TS-JJY02</a><br> + <a href="#mode-2">シーデックス JST2000</a><br> + <a href="#mode-3">エコー計測器 LT-2000</a><br> + <a href="#mode-4">ã‚·ãƒã‚ºãƒ³TIC JJY-200</a><br> + <a href="#mode-5">トライステート TS-GPSclock-01</a><br> + </td> + <td width="50%" style="vertical-align:top; border-left:solid; padding:0px 0px 0px 10px;"> + <a href="#mode-6">セイコー タイムシステムTDC-300</a><br> + <a href="#mode-100">テレフォンJJY</a><br> + </td> + </tr> + </table> + <ul> + + <li> + <p><a name="mode-1">トライステート TS-JJY01, TS-JJY02</a> <a href="http://www.tristate.ne.jp/">http://www.tristate.ne.jp/</a> (日本語)</p><br> + <dl> + <dt>NTPã®è¨å®š ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 1</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN flag1 0|1</dt> + <dd> + <p>Time1 ã¯ã€å—ä¿¡æ©Ÿã‹ã‚‰ã®æ™‚刻ã«åŠ ç®—ã™ã‚‹èª¿æ•´æ™‚é–“ã‚’ã€å›ºå®šå°æ•°ç‚¹å½¢å¼ã®ç§’ã§è¨å®šã—ã¾ã™ã€‚<br> + ã“ã®å—ä¿¡æ©Ÿã«ã¯ã€æ•°10ミリ秒 ( 0.0NN秒 ) ã‹ã‚‰ç™¾æ•°10ミリ秒 ( 0.1NN秒 ) ã®èª¿æ•´æ™‚é–“ã‚’è¨å®šã™ã‚‹ã¨è‰¯ã„ã§ã—ょã†ã€‚</p> + <p>Flag1 ã¯ã€æ™‚刻åŒæœŸã«ã¯ç„¡é–¢ä¿‚ã§ã™ã€‚Flag1 ã‚’ 1 ã«è¨å®šã™ã‚‹ã¨ã€çŠ¶æ…‹ã‚’å•ã„åˆã‚ã›ã‚‹ã‚³ãƒžãƒ³ãƒ‰ã‚’ DATE コマンド㨠STIM コマンドã®å‰ã«ç™ºè¡Œã—ã¦ã€å¿œç”ã‚’ clockstats ファイルã«è¨˜éŒ²ã—ã¾ã™ã€‚</p> + <table border="1" summary="fudge flag1"> + <tr><td>0 (Default)</td><td>DCST 㨠STUS コマンドã¯ã€ç™ºè¡Œã—ã¾ã›ã‚“。</td></tr> + <tr><td>1</td><td>DCST 㨠STUS コマンドをã€ç™ºè¡Œã—ã¾ã™ã€‚</td></tr> + </table> + </dd> + </dl> + <br> + </dd> + <dt>インターフェース</dt> + <dd> + <p>RS-232C, 9600 BPS, 8ビット, パリティãªã—, 1ストップ・ビット</p> + <br> + </dd> + <dt>日時データã®å½¢å¼</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td><code>dcst{CR}{LF}</code></td> + <td> --> </td> + <td><code>valid{CR}{LF} | invalid{CR}{LF}</code></td> + </tr> + <tr> + <td><code>stus{CR}{LF}</code></td> + <td> --> </td> + <td><code>adjusted{CR}{LF} | unadjusted{CR}{LF}</code></td> + </tr> + <tr> + <td><code>time{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> + </tr> + <tr> + <td><code>date{CR}{LF}</code></td> + <td> --> </td> + <td><code>YYYY/MM/DD WWW{CR}{LF}</code></td> + </tr> + <tr> + <td><code>stim{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> + </tr> + </table> + <p>日付ã¨æ™‚刻ã¯ã€åˆ¥ã€…ã«å•ã„åˆã‚ã›ã¾ã™ã€‚日付ãŒæ·±å¤œï¼æ™‚ã®å‰ã‹å¾Œã‹ã®ä¸ç¢ºå®šã‚’ãƒã‚§ãƒƒã‚¯ã™ã‚‹ãŸã‚ã€æ—¥ä»˜ã®å•ã„åˆã‚ã›ã®å‰å¾Œã«æ™‚刻をå•ã„åˆã‚ã›ã¦ã„ã¾ã™ã€‚</p><br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-2">シーデックス JST2000</a> <a href="http://www.c-dex.co.jp/">http://www.c-dex.co.jp/</a> (日本語)</p><br> + <dl> + <dt>NTPã®è¨å®š ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 2</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> + <br> + </dd> + <dt>インターフェース</dt> + <dd> + <p>RS-232C, 9600 BPS, 8ビット, パリティãªã—, 1ストップ・ビット</p> + <br> + </dd> + <dt>日時データã®å½¢å¼</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td><code>{ENQ}1J{ETX}</code></td> + <td> --> </td> + <td><code>{STX}JYYMMDD HHMMSSS{ETX}</code></td> + </tr> + </table> + <br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-3">エコー計測器 LT-2000</a> <a href="http://www.clock.co.jp/">http://www.clock.co.jp/</a> (日本語)</p><br> + <dl> + <dt>NTPã®è¨å®š ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 3</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> + <br> + </dd> + <dt>Interface</dt> + <dd> + <p>RS-232C, 9600 BPS, 8ビット, パリティãªã—, 1ストップ・ビット</p> + <br> + </dd> + <dt>Time code format</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td><code>C</code></td> + <td> --> </td> + <td>( Mode 2 : Continuous )</td> + </tr> + <tr> + <td>( Every second before 0.5 second )</td> + <td></td> + <td><code>YYMMDDWHHMMSS{ST1}{ST2}{ST3}{ST4}{CR}</code></td> + </tr> + <tr> + <td><code>#</code></td> + <td> --> </td> + <td>( Mode 1 : Request&Send )</td> + </tr> + </table> + <br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-4">ã‚·ãƒã‚ºãƒ³TIC JJY-200</a> <a href="http://www.tic-citizen.co.jp/">http://www.tic-citizen.co.jp/</a> (日本語)</p><br> + <dl> + <dt>NTPã®è¨å®š ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 4</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> + <br> + </dd> + <dt>インターフェース</dt> + <dd> + <p>RS-232C, 4800 BPS, 8ビット, パリティãªã—, 1ストップ・ビット</p> + <br> + </dd> + <dt>日時データã®å½¢å¼</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td>( Every second )</td> + <td></td> + <td><code>'XX YY/MM/DD W HH:MM:SS{CR}</code></td> + </tr> + </table> + <br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-5">トライステート TS-GPSclock-01</a> <a href="http://www.tristate.ne.jp/">http://www.tristate.ne.jp/</a> (日本語)</p> + <p>ã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã¯ã€JJYå—ä¿¡æ©Ÿã§ã¯ãªã„GPS時計ã®ãƒˆãƒ©ã‚¤ã‚¹ãƒ†ãƒ¼ãƒˆ TS-GPSclock-01 ã®ã‚³ãƒžãƒ³ãƒ‰ãƒ»ãƒ¬ã‚¹ãƒãƒ³ã‚¹ãƒ»ãƒ¢ãƒ¼ãƒ‰ã‚’サãƒãƒ¼ãƒˆã—ã¾ã™ã€‚<br> + TS-GPSclock-01 ã¯ã€ã‚ªãƒ³ãƒœãƒ¼ãƒ‰ã®ã‚¹ã‚¤ãƒƒãƒã¨ãƒ¡ãƒ‹ãƒ¥ãƒ¼ã§ã‚³ãƒžãƒ³ãƒ‰ãƒ»ãƒ¬ã‚¹ãƒãƒ³ã‚¹ãƒ»ãƒ¢ãƒ¼ãƒ‰ã¨ã‚¿ã‚¤ãƒ ・ゾーンをJST(日本標準時)ã«è¨å®šã—ãªã‘ã‚Œã°ãªã‚Šã¾ã‚“。<br> + ã“ã® Type 40 ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã®ä»–, TS-GPSclock-01 ã®NMEAモードã¯ã€<a href="driver20.html">一般 NMEA GPS ドライãƒãƒ¼ ( Type 20 )</a> ã§ã‚‚利用ã™ã‚‹ã“ã¨ãŒã§ãã¾ã™ã€‚</p> + <dl> + <dt>NTPã®è¨å®š ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 5</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN flag1 0|1</dt> + <dd> + <p>Time1 ã¯ã€å—ä¿¡æ©Ÿã‹ã‚‰ã®æ™‚刻ã«åŠ ç®—ã™ã‚‹èª¿æ•´æ™‚é–“ã‚’ã€å›ºå®šå°æ•°ç‚¹å½¢å¼ã®ç§’ã§è¨å®šã—ã¾ã™</p> + <p>Flag1 ã¯ã€æ™‚刻åŒæœŸã«ã¯ç„¡é–¢ä¿‚ã§ã™ã€‚Flag1 ã‚’ 1 ã«è¨å®šã™ã‚‹ã¨ã€çŠ¶æ…‹ã‚’å•ã„åˆã‚ã›ã‚‹ã‚³ãƒžãƒ³ãƒ‰ã‚’ DATE コマンド㨠STIM コマンドã®å‰ã«ç™ºè¡Œã—ã¦ã€å¿œç”ã‚’ clockstats ファイルã«è¨˜éŒ²ã—ã¾ã™ã€‚</p> + <table border="1" summary="fudge flag1"> + <tr><td>0 (Default)</td><td>STUS コマンドã¯ã€ç™ºè¡Œã—ã¾ã›ã‚“。</td></tr> + <tr><td>1</td><td>STUS コマンドをã€ç™ºè¡Œã—ã¾ã™ã€‚</td></tr> + </table> + </dd> + </dl> + <br> + </dd> + <dt>インターフェース</dt> + <dd> + <p>USB ( /dev/ttyACM<em>0</em> )</p> + <br> + </dd> + <dt>日時データã®å½¢å¼</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td><code>stus{CR}{LF}</code></td> + <td> --> </td> + <td><code>*R{CR}{LF} | *G{CR}{LF} | *U{CR}{LF} | +U{CR}{LF}</code></td> + </tr> + <tr> + <td><code>time{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> + </tr> + <tr> + <td><code>date{CR}{LF}</code></td> + <td> --> </td> + <td><code>YYYY/MM/DD{CR}{LF}</code></td> + </tr> + <tr> + <td><code>time{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> + </tr> + </table> + <p>日付ã¨æ™‚刻ã¯ã€åˆ¥ã€…ã«å•ã„åˆã‚ã›ã¾ã™ã€‚日付ãŒæ·±å¤œï¼æ™‚ã®å‰ã‹å¾Œã‹ã®ä¸ç¢ºå®šã‚’ãƒã‚§ãƒƒã‚¯ã™ã‚‹ãŸã‚ã€æ—¥ä»˜ã®å•ã„åˆã‚ã›ã®å‰å¾Œã«æ™‚刻をå•ã„åˆã‚ã›ã¦ã„ã¾ã™ã€‚</p><br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-6">セイコー タイムシステムTDC-300</a> <a href="http://www.seiko-sts.co.jp/">http://www.seiko-sts.co.jp/</a> (英語ã¨æ—¥æœ¬èªž)</p><br> + <p>TDC-300 ã¯ã€ãƒ•ãƒãƒ³ãƒˆãƒ»ãƒ‘ãƒãƒ«ã®ãƒ¡ãƒ‹ãƒ¥ãƒ¼è¡¨ç¤ºã¨ã‚¹ã‚¤ãƒƒãƒã§ type 3 ã®ãƒ‡ãƒ¼ã‚¿å½¢å¼ã«è¨å®šã—ãªã‘ã‚Œã°ãªã‚Šã¾ã›ã‚“。</p> + <dl> + <dt>NTP configuration ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 6</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> + <br> + </dd> + <dt>インターフェース</dt> + <dd> + <p>RS-232C, 2400 BPS, 8-bits, no parity, 1 stop bit</p> + <br> + </dd> + <dt>日時データã®å½¢å¼</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td></td> + <td></td> + <td><code>{STX}YYMMDDWHHMMSS{ETX}</code></td> + </tr> + <tr> + <td>( 5 to 10 mSec. before second )</td> + <td></td> + <td><code>{STX}{xE5}{ETX}</code></td> + </tr> + </table> + <br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-100">テレフォンJJY</a> <a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a> (英語ã¨æ—¥æœ¬èªž)</p> + <p>テレフォンJJYã¯ã€é›»è©±å›žç·šã«ã‚ˆã‚‹æ™‚刻é…信サービスã§ã™ã€‚<br> + ã“ã®ã‚µãƒ¼ãƒ“スã¯ã€å›½ç«‹ç ”ç©¶é–‹ç™ºæ³•äººã€€æƒ…å ±é€šä¿¡ç ”ç©¶æ©Ÿæ§‹ãŒæä¾›ã—ã¦ã„ã¾ã™ã€‚</p> + <p>注æ„: ã“ã®ãƒ¢ãƒ¼ãƒ‰ï¼ˆãƒ†ãƒ¬ãƒ•ã‚©ãƒ³JJY)ã¯ã€refclock_acts ( Type 18 ) ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã¨åŒæ™‚ã«åˆ©ç”¨ã™ã‚‹ã“ã¨ã¯ã§ãã¾ã›ã‚“。 + è¨å®šãƒ•ã‚¡ã‚¤ãƒ«ã® phone ã¯ã€server ã¨é–¢ä¿‚付ã‘られã¦ã„ãªã„ãŸã‚ã€ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã® refclock_acts ( type 18 ) ã‚‚ã€ã“ã® refclock_jjy ( type 40, mode 100 to 180 ) ã®ã„ãšã‚Œã‚‚〠+ 複数㮠phone ã®ã†ã¡ã€ã©ã‚ŒãŒè‡ªåˆ†ã«é–¢ä¿‚ã™ã‚‹ã‚‚ã®ã‹è˜åˆ¥ã§ããªã„ã‹ã‚‰ã§ã™ã€‚</p> + <dl> + <dt>NTPã®è¨å®š ( ntp.conf )</dt> + <dd> + <dl> + <dt>server 127.127.40.X mode (100, 101 to 180) minpoll N</dt> + <dd> + <p>モード 100 ã‚’è¨å®šã—ãŸå ´åˆã€ã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã¯ã€é…延を計測ã™ã‚‹ãŸã‚ã®ãƒ«ãƒ¼ãƒ—ãƒãƒƒã‚¯ãƒ»ã‚³ãƒžãƒ³ãƒ‰ã¯ç™ºè¡Œã›ãšã€é›»è©±å›žç·šã¨ã‚·ã‚¹ãƒ†ãƒ ã®å‡¦ç†ã«ã‚ˆã‚‹é…延ã¯èª¿æ•´ã—ã¾ã›ã‚“。<br> + モード 101 ã‹ã‚‰ 180 ã‚’è¨å®šã—ãŸå ´åˆã€ã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã¯ã€ãƒ«ãƒ¼ãƒ—ãƒãƒƒã‚¯ãƒ»ã‚³ãƒžãƒ³ãƒ‰ã‚’発行ã—ã¦ã€ãƒ†ãƒ¬ãƒ•ã‚©ãƒ³JJYã®ãƒ«ãƒ¼ãƒ—ãƒãƒƒã‚¯å›žè·¯ã‚’通ã—ã¦é›»è©±å›žç·šã¨ã‚·ã‚¹ãƒ†ãƒ ã®å‡¦ç†ã«ã‚ˆã‚‹é…延を計測ã—ã¾ã™ã€‚<br> + テレフォンJJYã®ãƒ«ãƒ¼ãƒ—ãƒãƒƒã‚¯å›žè·¯ã‚’経由ã—ãŸå¾€å¾©ã®æ™‚é–“ã¯ã€5回ã€è¨ˆæ¸¬ã•ã‚Œã¾ã™ã€‚ + ãã‚Œãžã‚Œã®é…延時間ã®ã†ã¡ã€700ミリ秒を超ãˆãŸã‚‚ã®ã¯ã€å¹³å‡é…延時間ã®è¨ˆç®—より除外ã•ã‚Œã¾ã™ã€‚ + ã¾ãŸã€700ミリ秒以下ã®æœ‰åŠ¹ãªé…延時間ãŒã€3回以上ã®å ´åˆã¯ã€ãã®ã†ã¡ã€æœ€å¤§ã®é…延時間ã¯ã€å¹³å‡é…延時間ã®è¨ˆç®—より除外ã•ã‚Œã€ + 4回以上ã®å ´åˆã¯ã€ãã®ã†ã¡ã€æœ€å°ã®é…延時間ã¯ã€å¹³å‡é…延時間ã®è¨ˆç®—より除外ã•ã‚Œã¾ã™ã€‚ + 調整時間ã¯ã€å¾€å¾©æ™‚間 × ( ãƒ¢ãƒ¼ãƒ‰ç•ªå· - 100 ) % ã§è¨ˆç®—ã—ã€åŒæœŸã™ã‚‹æ™‚刻ã«åŠ ç®—ã•ã‚Œã¾ã™ã€‚<br> + モード 101 ã‹ã‚‰ 180 ã‚’è¨å®šã—ã¦è‡ªå‹•é…延補æ£ã‚’é¸æŠžã™ã‚‹ãªã‚‰ã€ãƒ¢ãƒ¼ãƒ‰ 145 ã‹ã‚‰ 165 ãŒè‰¯ã„ã§ã—ょã†ã€‚</p> + <p>デフォルトã®æ—¥æ™‚å•ã„åˆã‚ã›å‡¦ç†é–“éš” 6 ( 64 秒 ) ã¯ã€ã“ã®ãƒ¢ãƒ¼ãƒ‰ã«ã¯ã€çŸã™ãŽã¾ã™ã€‚ "minpoll" ã¯ã€8 ( 256 秒, ç´„ 4 分 ) 以上をè¨å®šã—ã¦ä¸‹ã•ã„。<br> + 日時å•ã„åˆã‚ã›å‡¦ç†é–“éš”ã¯ã€ç§’æ•°ã‚’ 2 ã®ã¹ãä¹—ã§æŒ‡å®šã—ã¾ã™ã€‚ minpoll ã®å€¤ãŒã€12 ãªã‚‰ 4096 秒(約1時間)ã€14 ãªã‚‰ 16384 秒(約4.5時間)ã€16 ãªã‚‰ 65536 秒(約18時間)ã¨ãªã‚Šã¾ã™ã€‚</p><br> + </dd> + <dt>fudge 127.127.40.X flag1 0|1 flag2 0|1 flag3 0|1 flag4 0|1</dt> + <dd> + <p>Time1 ã¯ã€å—ä¿¡æ©Ÿã‹ã‚‰ã®æ™‚刻ã«åŠ ç®—ã™ã‚‹èª¿æ•´æ™‚é–“ã‚’ã€å›ºå®šå°æ•°ç‚¹å½¢å¼ã®ç§’ã§è¨å®šã—ã¾ã™ã€‚<br> + mode 100 ã®å ´åˆã¯ã€time1 ã§èª¿æ•´ã™ã‚‹æ™‚é–“ã‚’è¨å®šã—ãŸã»ã†ãŒè‰¯ã„ã§ã—ょã†ã€‚<br> + mode 101 ã‹ã‚‰ 180 ã®å ´åˆã¯ã€ã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ãŒè¨ˆæ¸¬ã—ãŸãƒ«ãƒ¼ãƒ—ãƒãƒƒã‚¯ã®é…延時間ã®ä¸€å®šã®å‰²åˆã‚’åŒæœŸæ™‚刻ã«åŠ ç®—ã—ã¾ã™ã®ã§ã€time1 ã¯è¨å®šã—ãªã„ã»ã†ãŒè‰¯ã„ã§ã—ょã†ã€‚</p> + <div style="text-align:left;">Flag1 ã¯ã€ã‚¿ãƒƒãƒãƒ»ãƒˆãƒ¼ãƒ³ã‹ãƒ€ã‚¤ãƒ¤ãƒ«ãƒ»ãƒ‘ルスã‹ã‚’指定ã—ã¾ã™ã€‚</div> + <table border="1" summary="fudge flag1"> + <tr><td>0 (Default)</td><td>タッãƒãƒ»ãƒˆãƒ¼ãƒ³</td><td>ATDWTnn...nn</td></tr> + <tr><td>1</td><td>ダイヤル・パルス</td><td>ATDWPnn...nn</td></tr> + </table> + <br> + <div style="text-align:left;">Flag2 ã¯ã€ã‚¨ãƒ©ãƒ¼è¨‚æ£ãƒ—ãƒãƒˆã‚³ãƒ«ã‚’指定ã—ã¾ã™ã€‚</div> + <table border="1" summary="fudge flag2"> + <tr><td>0 (Default)</td><td>ノーマル(エラー訂æ£ãªã—)</td><td>AT\N0</td></tr> + <tr><td>1</td><td>V42, MNP, ノーマルã®è‡ªå‹•é¸æŠž</td><td>AT\N3</td></tr> + </table> + <br> + <div style="text-align:left;">Flag3 ã¯ã€ã‚¹ãƒ”ーカーã®ã‚ªãƒ³ï¼ã‚ªãƒ•ã‚’指定ã—ã¾ã™ã€‚</div> + <table border="1" summary="fudge flag3"> + <tr><td>0 (Default)</td><td>オフ</td><td>ATM0Ln</td></tr> + <tr><td>1</td><td>オン</td><td>ATM2Ln</td></tr> + </table> + <br> + <div style="text-align:left;">Flag4 ã¯ã€ã‚¹ãƒ”ーカーã®éŸ³é‡ã‚’指定ã—ã¾ã™ã€‚</div> + <table border="1" summary="fudge flag4"> + <tr><td>0 (Default)</td><td>低</td><td>ATMnL1</td></tr> + <tr><td>1</td><td>ä¸</td><td>ATMnL2</td></tr> + </table> + <br> + </dd> + <dt>phone 042NNNNNNN</dt> + <dd> + <p>電話番å·ã¯ã€<a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a> ã§å…¬é–‹ã•ã‚Œã¦ã„ã¾ã™ã€‚<br> + 電話番å·ã®æ¡æ•°ã‚’ãƒã‚§ãƒƒã‚¯ã—ã¦ã„ã¾ã™ã€‚ã‚‚ã—ã€æ—¥æœ¬å›½å¤–ã‹ã‚‰ç™ºä¿¡ã™ã‚‹ãŸã‚ã«å›½éš›é›»è©±ã‚¢ã‚¯ã‚»ã‚¹ç•ªå·ã¨å›½ç•ªå·ã‚’ä»˜åŠ ã™ã‚‹ã¨ã€æ¡æ•°åˆ¶é™ã‚’超ãˆã¾ã™ã€‚<br> + ã¾ãŸã€é›»è©±ç•ªå·ã®æœ€åˆã®2æ¡ã‚„3æ¡ã‚’ãƒã‚§ãƒƒã‚¯ã—ã¦ã„ã¾ã™ã€‚日本ã®ç·Šæ€¥ç•ªå·ã‚„特別ã®ã‚µãƒ¼ãƒ“スã®ç•ªå·ã‚’指定ã™ã‚‹ã“ã¨ã¯ã§ãã¾ã›ã‚“。<br> + 内線ã‹ã‚‰å¤–ç·šã«ç™ºä¿¡ã™ã‚‹æ™‚ã¯ã€"0," ( ゼãƒã¨ã‚«ãƒ³ãƒž ) ã‚’å…ˆé ã«ä»˜åŠ ã—ã¦ä¸‹ã•ã„。外線発信番å·ã¯ã€ãƒã‚§ãƒƒã‚¯ã—ã¦ã„ã¦ã€ãれ以外ã®å¤–線発信番å·ã‚’指定ã™ã‚‹ã“ã¨ã¯ã§ãã¾ã›ã‚“。</p> + </dd> + </dl> + <br> + </dd> + <dt>インターフェース</dt> + <dd> + <p>RS-232C åˆã¯ USB, 2400 BPS, 8ビット, パリティãªã—, 1ストップ・ビット</p> + <p>モデム制御コマンド:<br> + <code>ATE0Q0V1, ATMnLn, AT&K4, AT+MS=V22B, AT%C0, AT\Nn, ATH1, ATDWxnn...nn</code><br> + <code>+++, ATH0</code></p> + <br> + </dd> + <dt>日時データã®å½¢å¼</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>プãƒãƒ³ãƒ—ト</td> + <td> --> </td> + <td>コマンド</td> + <td> --> </td> + <td>å¿œç”</td> + </tr> + <tr> + <td><code>Name{SP}?{SP}</code></td> + <td> --> </td> + <td><code>TJJY{CR}</code></td> + <td> --> </td> + <td>Welcome messages</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>LOOP{CR}</code></td> + <td> --> </td> + <td>( Switch to the loopback circuit )</td> + </tr> + <tr> + <td><code> </code></td> + <td> </td> + <td><code>( One char. )</code></td> + <td> --> </td> + <td><code>( One char. )</code></td> + </tr> + <tr> + <td><code> </code></td> + <td> </td> + <td><code>COM{CR}</code></td> + <td> --> </td> + <td>( Exit from the loopback circuit )</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>TIME{CR}</code></td> + <td> --> </td> + <td><code>HHMMSS{CR}HHMMSS{CR}HHMMSS{CR}</code> 3 times on second</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>4DATE{CR}</code></td> + <td> --> </td> + <td><code>YYYYMMDD{CR}</code></td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>LEAPSEC{CR}</code></td> + <td> --> </td> + <td><code>{SP}0{CR} | +1{CR} | -1{CR}</code></td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>TIME{CR}</code></td> + <td> --> </td> + <td><code>HHMMSS{CR}HHMMSS{CR}HHMMSS{CR}</code> 3 times on second</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>BYE{CR}</code></td> + <td> --> </td> + <td>Sayounara messages</td> + </tr> + </table> + <p>日付ã¨æ™‚刻ã¯ã€åˆ¥ã€…ã«å•ã„åˆã‚ã›ã¾ã™ã€‚日付ãŒæ·±å¤œï¼æ™‚ã®å‰ã‹å¾Œã‹ã®ä¸ç¢ºå®šã‚’ãƒã‚§ãƒƒã‚¯ã™ã‚‹ãŸã‚ã€æ—¥ä»˜ã®å•ã„åˆã‚ã›ã®å‰å¾Œã«æ™‚刻をå•ã„åˆã‚ã›ã¦ã„ã¾ã™ã€‚<br> + ã†ã‚‹ã†ç§’ã¯ã€å‡¦ç†ã—ã¦ã„ã¾ã›ã‚“ã€‚æƒ…å ±ã¨ã—㦠clockstats ファイルã«è¨˜éŒ²ã—ã¦ã„ã‚‹ã ã‘ã§ã™ã€‚</p> + <br> + </dd> + </dl> + </li> + + </ul> + + <p>JJY ã¯ã€é•·æ³¢ã§æ—¥æœ¬æ¨™æº–時(JST)ã‚’é€ä¿¡ã—ã¦ã„ã‚‹ç„¡ç·šå±€ã§ã€å›½ç«‹ç ”ç©¶é–‹ç™ºæ³•äººã€€æƒ…å ±é€šä¿¡ç ”ç©¶æ©Ÿæ§‹ãŒé‹ç”¨ã—ã¦ã„ã¾ã™ã€‚JJY ã®é‹ç”¨æƒ…å ±ãªã©ã¯ã€ <a href="http://www.nict.go.jp/">http://www.nict.go.jp/</a>(英語ã¨æ—¥æœ¬èªžï¼‰ã‚„ <a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a>(英語ã¨æ—¥æœ¬èªžï¼‰ã§æä¾›ã•ã‚Œã¦ã„ã¾ã™ã€‚</p> + <p>実際ã®ã‚·ãƒªã‚¢ãƒ«ãƒ»ãƒãƒ¼ãƒˆã®ãƒ‡ãƒã‚¤ã‚¹ã«ã‚·ãƒ³ãƒœãƒªãƒƒã‚¯ãƒ»ãƒªãƒ³ã‚¯ã‚’作æˆã—ã¦ä¸‹ã•ã„。シンボリック・リンクを作æˆã™ã‚‹ã‚³ãƒžãƒ³ãƒ‰ã¯ã€ä»¥ä¸‹ã®ã¨ãŠã‚Šã§ã™ã€‚</p> + <p><code>ln -s /dev/ttyS0 /dev/jjy0</code></p> + <p>RS-232C ã‹ã‚‰ USB ã¸ã®å¤‰æ›ã‚±ãƒ¼ãƒ–ルを利用ã—ã¦ã€JJYå—ä¿¡æ©Ÿã€GPS時計ã€ãƒ¢ãƒ‡ãƒ ã‚’RS-232Cãƒãƒ¼ãƒˆã§ã¯ãªãã€USBã«æŽ¥ç¶šã™ã‚‹ã“ã¨ãŒã§ãã¾ã™ã€‚ã“ã®å ´åˆã®ã‚·ãƒ³ãƒœãƒªãƒƒã‚¯ãƒ»ãƒªãƒ³ã‚¯ã‚’作æˆã™ã‚‹ã‚³ãƒžãƒ³ãƒ‰ã¯ã€ä»¥ä¸‹ã®ã¨ãŠã‚Šã§ã™ã€‚</p> + <p><code>ln -s /dev/ttyUSB0 /dev/jjy0</code></p> + <p>Windows NT ã®å ´åˆã¯ã€ COM<em>X</em>: ã®æ•°å—部分ãŒãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã®ãƒ¦ãƒ‹ãƒƒãƒˆç•ªå·ã«ä½¿ç”¨ã•ã‚Œã¾ã™ã€‚ ドライãƒãƒ¼ã®ãƒ¦ãƒ‹ãƒƒãƒˆ 1 ã¯ã€COM1: ã«ãƒ¦ãƒ‹ãƒƒãƒˆ 3 ã¯ã€COM3: ã«å¯¾å¿œã—ã¾ã™ã€‚</p> + <h4>Monitor Data</h4> + <p>ã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã¯ã€JJYå—ä¿¡æ©Ÿã€GPS時計ã€ãƒ¢ãƒ‡ãƒ ã¨ã®é€å—信データを <code>clockstats</code> ファイルã«è¨˜éŒ²ã—ã¾ã™ã€‚</p> + <p><code> + statsdir /var/log/ntpd/<br> + filegen clockstats file clockstats type day enable + </code></p> + <div style="text-align:left;">レコードä¸ã®ãƒžãƒ¼ã‚¯ã«ã¤ã„ã¦</div> + <table border="1" summary="Clockstats"> + <tr><td><code>JJY</code> </td><td>æƒ…å ±ï¼ˆã“ã®ãƒ‰ãƒ©ã‚¤ãƒãƒ¼ã®é–‹å§‹ã¾ãŸã¯çµ‚了)</td></tr> + <tr><td><code>--></code> </td><td>é€ä¿¡ãƒ‡ãƒ¼ã‚¿</td></tr> + <tr><td><code><--</code> </td><td>å—信データ</td></tr> + <tr><td><code>---</code> </td><td>æƒ…å ±</td></tr> + <tr><td><code>===</code> </td><td>æƒ…å ±ï¼ˆãƒãƒ¼ãƒªãƒ³ã‚°ã®é–‹å§‹ã€ãŠã‚ˆã³ã€åŒæœŸæ™‚刻)</td></tr> + <tr><td><code>-W-</code> </td><td>è¦å‘Šãƒ¡ãƒƒã‚»ãƒ¼ã‚¸</td></tr> + <tr><td><code>-X-</code> </td><td>エラー・メッセージ</td></tr> + </table> + <h4>Fudge Factors</h4> + <dl> + <dt><code>time1 <em>time</em></code></dt> + <dd>å—ä¿¡æ©Ÿã‹ã‚‰ã®æ™‚刻ã«å¯¾ã™ã‚‹èª¿æ•´æ™‚é–“ã‚’ã€å›ºå®šå°æ•°ç‚¹å½¢å¼ã®ç§’ã§è¨å®šã—ã¾ã™ã€‚デフォルトã¯ã€0.0秒ã§ã™ã€‚</dd> + <dt><code>time2 <em>time</em></code></dt> + <dd>未使用。</dd> + <dt><code>stratum <em>number</em></code></dt> + <dd>NTPã®éšŽå±¤ç•ªå·ã‚’ 0 ã‹ã‚‰ 15 ã§æŒ‡å®šã—ã¾ã™ã€‚デフォルトã¯ã€0ã§ã™ã€‚</dd> + <dt><code>refid <em>string</em></code></dt> + <dd>ドライãƒãƒ¼IDã§ã€ASCII ã®1æ–‡å—ã‹ã‚‰4æ–‡å—ã§æŒ‡å®šã—ã¾ã™ã€‚デフォルトã¯ã€<code>JJY</code> ã§ã™ã€‚</dd> + <dt><code>flag1 0 | 1</code></dt> + <dd>ãã‚Œãžã‚Œã®ãƒ¢ãƒ¼ãƒ‰ã‚’å‚ç…§ã—ã¦ä¸‹ã•ã„。</dd> + <dt><code>flag2 0 | 1</code></dt> + <dd>ãã‚Œãžã‚Œã®ãƒ¢ãƒ¼ãƒ‰ã‚’å‚ç…§ã—ã¦ä¸‹ã•ã„。</dd> + <dt><code>flag3 0 | 1</code></dt> + <dd>ãã‚Œãžã‚Œã®ãƒ¢ãƒ¼ãƒ‰ã‚’å‚ç…§ã—ã¦ä¸‹ã•ã„。</dd> + <dt><code>flag4 0 | 1</code></dt> + <dd>ãã‚Œãžã‚Œã®ãƒ¢ãƒ¼ãƒ‰ã‚’å‚ç…§ã—ã¦ä¸‹ã•ã„。</dd> + </dl> + <hr> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body> + +</html> diff --git a/contrib/ntp/html/drivers/driver40.html b/contrib/ntp/html/drivers/driver40.html index 1901dcd..356429e 100644 --- a/contrib/ntp/html/drivers/driver40.html +++ b/contrib/ntp/html/drivers/driver40.html @@ -5,6 +5,7 @@ <head> <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> <meta name="generator" content="HTML Tidy, see www.w3.org"> + <meta http-equiv="Content-Style-Type" content="text/css"> <meta http-equiv="Content-Script-Type" content="text/javascript"> <title>JJY Receivers</title> <link rev="made" href="http://www.bea.hi-ho.ne.jp/abetakao/"> @@ -14,25 +15,58 @@ <body> <h3>JJY Receivers</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->15-May-2015 00:00<!-- #EndDate --> + UTC <a href="driver40.html">ENGLISH</a> <a href="driver40-ja.html">JAPANESE</a></p> <hr> <h4>Synopsis</h4> Address: 127.127.40.<em>u</em><br> Reference ID: <code>JJY</code><br> Driver ID: <code>JJY</code><br> - Serial Port: <code>/dev/jjy<em>u</em></code>; 9600|4800(See corresponding receiver) baud, 8-bits, no parity, 1 stop bit + Serial Port: <code>/dev/jjy<em>u</em></code>; See corresponding receiver <h4>Description</h4> - <p>This driver supports the following JJY receivers sold in Japan.</p> + <p>This driver supports the following the JJY receivers and the GPS clock sold in Japan, and the time service through a telephone line. + </p> + <table width="100%"> + <tr> + <td width="50%" style="vertical-align:top;"> + <a href="#mode-1">Tristate Ltd. TS-JJY01, TS-JJY02</a><br> + <a href="#mode-2">C-DEX Co.,Ltd. JST2000</a><br> + <a href="#mode-3">Echo Keisokuki Co.,Ltd. LT-2000</a><br> + <a href="#mode-4">CITIZEN T.I.C. CO.,LTD. JJY-200</a><br> + <a href="#mode-5">Tristate Ltd. TS-GPSclock-01</a><br> + </td> + <td width="50%" style="vertical-align:top; border-left:solid; padding:0px 0px 0px 10px;"> + <a href="#mode-6">SEIKO TIME SYSTEMS INC. TDC-300</a><br> + <a href="#mode-100">Telephone JJY</a><br> + </td> + </tr> + </table> <ul> - <li>Tristate Ltd. JJY01 <a href="http://www.tristate.ne.jp/">http://www.tristate.ne.jp/</a> (Japanese only)<br> + + <li> + <p><a name="mode-1">Tristate Ltd. TS-JJY01, TS-JJY02</a> <a href="http://www.tristate.ne.jp/">http://www.tristate.ne.jp/</a> (Japanese only)</p><br> <dl> <dt>NTP configuration ( ntp.conf )</dt> - <dd> - <p>server 127.127.40.X mode 1</p> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 1</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN flag1 0|1</dt> + <dd> + <p>Time1 may specify a constant to be added to the time offset for the time from the receiver, a fixed-point decimal number in seconds. You may specify the time offset from several tens of milli-seconds ( 0.0NN seconds ) to a hundred and several tens of milli-seconds ( 0.1NN seconds ) for this clock.</p> + <p>Flag1 has no effect for time synchronization. When flag1 is set to 1, status commands are issued before DATE and STIM commands, and write a response text into the clockstats file.</p> + <table border="1" summary="fudge flag1"> + <tr><td>0 (Default)</td><td>DCST and STUS commands are not issued</td></tr> + <tr><td>1</td><td>DCST and STUS commands are issued</td></tr> + </table> + </dd> + </dl> <br> </dd> - <dt>RS-232C</dt> + <dt>Interface</dt> <dd> - <p>9600 Baud</p> + <p>RS-232C, 9600 BPS, 8-bits, no parity, 1 stop bit</p> <br> </dd> <dt>Time code format</dt> @@ -44,29 +78,51 @@ <td>Reply</td> </tr> <tr> - <td><code>date<CR><LF></code></td> + <td><code>dcst{CR}{LF}</code></td> + <td> --> </td> + <td><code>valid{CR}{LF} | invalid{CR}{LF}</code></td> + </tr> + <tr> + <td><code>stus{CR}{LF}</code></td> + <td> --> </td> + <td><code>adjusted{CR}{LF} | unadjusted{CR}{LF}</code></td> + </tr> + <tr> + <td><code>time{CR}{LF}</code></td> <td> --> </td> - <td><code>YYYY/MM/DD WWW<CR><LF></code></td> + <td><code>HH:MM:SS{CR}{LF}</code></td> </tr> <tr> - <td><code>stim<CR><LF></code></td> + <td><code>date{CR}{LF}</code></td> <td> --> </td> - <td><code>HH:MM:SS<CR><LF></code></td> + <td><code>YYYY/MM/DD WWW{CR}{LF}</code></td> + </tr> + <tr> + <td><code>stim{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> </tr> </table> - <br> + <p>The date and time are requested separately. The time is requested before and after the date request to check uncertainty of the date whether it's before or after midnight.</p><br> </dd> </dl> - <li>C-DEX Co.,Ltd. JST2000 <a href="http://www.c-dex.co.jp/">http://www.c-dex.co.jp/</a> (Japanese only)<br> + </li> + + <li> + <p><a name="mode-2">C-DEX Co.,Ltd. JST2000</a> <a href="http://www.c-dex.co.jp/">http://www.c-dex.co.jp/</a> (Japanese only)</p><br> <dl> <dt>NTP configuration ( ntp.conf )</dt> - <dd> - <p>server 127.127.40.X mode 2</p> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 2</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> <br> </dd> - <dt>RS-232C</dt> + <dt>Interface</dt> <dd> - <p>9600 Baud</p> + <p>RS-232C, 9600 BPS, 8-bits, no parity, 1 stop bit</p> <br> </dd> <dt>Time code format</dt> @@ -78,25 +134,31 @@ <td>Reply</td> </tr> <tr> - <td><code><ENQ>1J<ETX></code></td> + <td><code>{ENQ}1J{ETX}</code></td> <td> --> </td> - <td><code><STX>JYYMMDD HHMMSSS<ETX></code></td> + <td><code>{STX}JYYMMDD HHMMSSS{ETX}</code></td> </tr> </table> <br> </dd> </dl> + </li> + <li> - <p>Echo Keisokuki Co.,Ltd. LT-2000 <a href="http://www.clock.co.jp/">http://www.clock.co.jp/</a> (Japanese only)</p> + <p><a name="mode-3">Echo Keisokuki Co.,Ltd. LT-2000</a> <a href="http://www.clock.co.jp/">http://www.clock.co.jp/</a> (Japanese only)</p><br> <dl> <dt>NTP configuration ( ntp.conf )</dt> - <dd> - <p>server 127.127.40.X mode 3</p> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 3</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> <br> </dd> - <dt>RS-232C</dt> + <dt>Interface</dt> <dd> - <p>9600 Baud</p> + <p>RS-232C, 9600 BPS, 8-bits, no parity, 1 stop bit</p> <br> </dd> <dt>Time code format</dt> @@ -115,7 +177,7 @@ <tr> <td>( Every second before 0.5 second )</td> <td></td> - <td><code>YYMMDDWHHMMSS<ST1><ST2><ST3><ST4><CR></code></td> + <td><code>YYMMDDWHHMMSS{ST1}{ST2}{ST3}{ST4}{CR}</code></td> </tr> <tr> <td><code>#</code></td> @@ -126,17 +188,23 @@ <br> </dd> </dl> + </li> + <li> - <p>CITIZEN T.I.C. CO.,LTD. JJY-200 <a href="http://www.tic-citizen.co.jp/">http://www.tic-citizen.co.jp/</a> (Japanese only)</p> + <p><a name="mode-4">CITIZEN T.I.C. CO.,LTD. JJY-200</a> <a href="http://www.tic-citizen.co.jp/">http://www.tic-citizen.co.jp/</a> (Japanese only)</p><br> <dl> <dt>NTP configuration ( ntp.conf )</dt> - <dd> - <p>server 127.127.40.X mode 4</p> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 4</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> <br> </dd> - <dt>RS-232C</dt> + <dt>Interface</dt> <dd> - <p>4800 Baud</p> + <p>RS-232C, 4800 BPS, 8-bits, no parity, 1 stop bit</p> <br> </dd> <dt>Time code format</dt> @@ -150,37 +218,314 @@ <tr> <td>( Every second )</td> <td></td> - <td><code>'XX YY/MM/DD W HH:MM:SS<CR></code></td> + <td><code>'XX YY/MM/DD W HH:MM:SS{CR}</code></td> </tr> </table> <br> </dd> </dl> + </li> + + <li> + <p><a name="mode-5">Tristate Ltd. TS-GPSclock-01</a> <a href="http://www.tristate.ne.jp/">http://www.tristate.ne.jp/</a> (Japanese only)</p> + <p>This driver supports the Tristate TS-GPSclock-01 in command/response mode, though it is a GPS clock, not JJY radio clock. Using the menus and the onboard switches, the TS-GPSclock-01 should be set to command/response mode and JST time zone.<br> + Besides this driver ( Type 40 ), <a href="driver20.html">the generic NMEA GPS driver ( Type 20 )</a> supports the TS-GPSclock-01 in NMEA mode.</p> + <dl> + <dt>NTP configuration ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 5</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN flag1 0|1</dt> + <dd> + <p>Time1 may specify a constant to be added to the time offset for the time from the receiver, a fixed-point decimal number in seconds.</p> + <p>Flag1 has no effect for time synchronization. When a flag1 is set to 1, status command is issued before DATE and TIME commands, and write a response text into a clockstats file.</p> + <table border="1" summary="fudge flag1"> + <tr><td>0 (Default)</td><td>STUS command is not issued</td></tr> + <tr><td>1</td><td>STUS command is issued</td></tr> + </table> + </dd> + </dl> + <br> + </dd> + <dt>Interface</dt> + <dd> + <p>USB ( /dev/ttyACM<em>0</em> )</p> + <br> + </dd> + <dt>Time code format</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>Command</td> + <td> --> </td> + <td>Reply</td> + </tr> + <tr> + <td><code>stus{CR}{LF}</code></td> + <td> --> </td> + <td><code>*R{CR}{LF} | *G{CR}{LF} | *U{CR}{LF} | +U{CR}{LF}</code></td> + </tr> + <tr> + <td><code>time{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> + </tr> + <tr> + <td><code>date{CR}{LF}</code></td> + <td> --> </td> + <td><code>YYYY/MM/DD{CR}{LF}</code></td> + </tr> + <tr> + <td><code>time{CR}{LF}</code></td> + <td> --> </td> + <td><code>HH:MM:SS{CR}{LF}</code></td> + </tr> + </table> + <p>The date and time are requested separately. The time is requested before and after the date request to check uncertainty of the date whether it's before or after midnight.</p><br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-6">SEIKO TIME SYSTEMS INC. TDC-300</a> <a href="http://www.seiko-sts.co.jp/">http://www.seiko-sts.co.jp/</a> (English and Japanese)</p><br> + <p>The TDC-300 must be set to the type 3 data format using the front panel menu display and the switches.</p> + <dl> + <dt>NTP configuration ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode 6</dt> + <dd><br></dd> + <dt>fudge 127.127.40.X time1 0.NNN</dt> + </dl> + <br> + </dd> + <dt>Interface</dt> + <dd> + <p>RS-232C, 2400 BPS, 8-bits, no parity, 1 stop bit</p> + <br> + </dd> + <dt>Time code format</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>Command</td> + <td> --> </td> + <td>Reply</td> + </tr> + <tr> + <td></td> + <td></td> + <td><code>{STX}YYMMDDWHHMMSS{ETX}</code></td> + </tr> + <tr> + <td>( 5 to 10 mSec. before second )</td> + <td></td> + <td><code>{STX}{xE5}{ETX}</code></td> + </tr> + </table> + <br> + </dd> + </dl> + </li> + + <li> + <p><a name="mode-100">Telephone JJY</a> <a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a> (English and Japanese)</p> + <p>The telephone JJY is the time service through a public telephone line.<br> + The service is provided by the National Institute of Information and Communications Technology in Japan.</p> + <p>ATTENTION; This mode, the telephone JJY, can not be used with the refclock_acts ( type 18 ) at the same time. + Because the "phone" statement in the ntp configuration file is not involved with the "server" statement, + so the both the refclock_acts ( type 18 ) and this refclock_jjy ( type 40, mode 100 to 180 ) can not recognize the appropriate "phone" statement among the "phone" statements.</p> + <dl> + <dt>NTP configuration ( ntp.conf )</dt> + <dd><br> + <dl> + <dt>server 127.127.40.X mode (100, 101 to 180) minpoll N</dt> + <dd> + <p>The mode 100 is specified, this driver does not issue the loopback command in order to measure the delay, and the delay of the telephone line and the system processing is not adjusted.<br> + The mode 101 to 180 is specified, this driver issues the loopback command and measures the delay of the telephone line and the system processing through the Telphone JJY loopback circuit.<br> + The round trip time through the Telphone JJY loopback circuit is measured 5 times, and each delay time is greater than 700 milli-seconds, + that delay time is ignored during average delay time calculation. Also, if the valid delay time ( <= 700 mS. ) is measured more than 3 times, the maximum delay time among the valid delay times is ignored, + and if the valid delay time is measured more than 4 times, the minimum delay time among them is ignored, like marking/grading sports judgment.<br> + The adjustment time is calculated by the formula,<br> + multiply ( the measured round trip time ) by ( ( the mode number ) - 100 ) %,<br> + and the adjustment delay time is added to the syncronizing time.<br> + If you choose the automatic delay ajustment, in other words, the mode 101 to 180 is specifed, the recommended mode number is 145 to 165.</p> + <p>The default polling interval 6 ( 64 seconds ) is too short for this mode. The "minpoll" should be set to greater than or equal to 8 ( 256 seconds, about 4 minutes ).<br> + The interval time is given the value in second power of 2. The minpoll value 12 is 4096 seconds interval ( about 1 hour ), 14 is 16384 seconds interval ( about 4.5 hours ), 16 is 65536 seconds ( about 18 hours ), respectively.</p><br> + </dd> + <dt>fudge 127.127.40.X flag1 0|1 flag2 0|1 flag3 0|1 flag4 0|1</dt> + <dd> + <p>Time1 may specify a constant to be added to the time offset for the time from the receiver, a fixed-point decimal number in seconds.<br> + When the mode 100 is specified, the time1 may be specified in order to adjust the time offset.<br> + When the mode 101 to 180 is specified, the time1 should not be specified because this driver adds some percentage of the measured loopback delay, depending on the value of the mode number.</p> + <div style="text-align:left;">Flag1 is the modem dialing type.</div> + <table border="1" summary="fudge flag1"> + <tr><td>0 (Default)</td><td>Tone</td><td>ATDWTnn...nn</td></tr> + <tr><td>1</td><td>Pulse</td><td>ATDWPnn...nn</td></tr> + </table> + <br> + <div style="text-align:left;">Flag2 is the modem error correction type.</div> + <table border="1" summary="fudge flag2"> + <tr><td>0 (Default)</td><td>Normal</td><td>AT\N0</td></tr> + <tr><td>1</td><td>Auto V42, MNP, Normal</td><td>AT\N3</td></tr> + </table> + <br> + <div style="text-align:left;">Flag3 is the modem speaker switch.</div> + <table border="1" summary="fudge flag3"> + <tr><td>0 (Default)</td><td>Off</td><td>ATM0Ln</td></tr> + <tr><td>1</td><td>On</td><td>ATM2Ln</td></tr> + </table> + <br> + <div style="text-align:left;">Flag4 is the modem speaker volume.</div> + <table border="1" summary="fudge flag4"> + <tr><td>0 (Default)</td><td>Low</td><td>ATMnL1</td></tr> + <tr><td>1</td><td>Middle</td><td>ATMnL2</td></tr> + </table> + <br> + </dd> + <dt>phone 042NNNNNNN</dt> + <dd> + <p>The phone number is available at <a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a><br> + The number of digits of the phone number is checked. If the international access number and the country number are added in order to call from outside of Japan, the number of digits is over the limit.<br> + The first 2 or 3 digits are checked. The emergency service number and the special service number in Japan are not allowed.<br> + Calling from extension line, the number for an outside line should be prefix "0," ( Zero, Comma ). The prefix is also checked, and no other outside access number is allowed.</p> + </dd> + </dl> + <br> + </dd> + <dt>Interface</dt> + <dd> + <p>RS-232C or USB, 2400 BPS, 8-bits, no parity, 1 stop bit</p> + <p>Modem control commands:<br> + <code>ATE0Q0V1, ATMnLn, AT&K4, AT+MS=V22B, AT%C0, AT\Nn, ATH1, ATDWxnn...nn</code><br> + <code>+++, ATH0</code></p> + <br> + </dd> + <dt>Time code format</dt> + <dd><br> + <table summary="CommandAndReply"> + <tr> + <td>Prompt</td> + <td> --> </td> + <td>Command</td> + <td> --> </td> + <td>Reply</td> + </tr> + <tr> + <td><code>Name{SP}?{SP}</code></td> + <td> --> </td> + <td><code>TJJY{CR}</code></td> + <td> --> </td> + <td>Welcome messages</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>LOOP{CR}</code></td> + <td> --> </td> + <td>( Switch to the loopback circuit )</td> + </tr> + <tr> + <td><code> </code></td> + <td> </td> + <td><code>( One char. )</code></td> + <td> --> </td> + <td><code>( One char. )</code></td> + </tr> + <tr> + <td><code> </code></td> + <td> </td> + <td><code>COM{CR}</code></td> + <td> --> </td> + <td>( Exit from the loopback circuit )</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>TIME{CR}</code></td> + <td> --> </td> + <td><code>HHMMSS{CR}HHMMSS{CR}HHMMSS{CR}</code> 3 times on second</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>4DATE{CR}</code></td> + <td> --> </td> + <td><code>YYYYMMDD{CR}</code></td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>LEAPSEC{CR}</code></td> + <td> --> </td> + <td><code>{SP}0{CR} | +1{CR} | -1{CR}</code></td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>TIME{CR}</code></td> + <td> --> </td> + <td><code>HHMMSS{CR}HHMMSS{CR}HHMMSS{CR}</code> 3 times on second</td> + </tr> + <tr> + <td><code>></code></td> + <td> --> </td> + <td><code>BYE{CR}</code></td> + <td> --> </td> + <td>Sayounara messages</td> + </tr> + </table> + <p>The date and time are requested separately. The time is requested before and after the date request to check uncertainty of the date whether it's before or after midnight.<br> + The leap second is not handled, and only written in the clockstats file as an information.</p> + <br> + </dd> + </dl> + </li> + </ul> - <p>JJY is the radio station which transmites the JST (Japan Standard Time) in long wave radio. The station JJY is operated by the National Institute of Information and Communications Technology. An operating announcement and some information are avaiable from <a href="http://www.nict.go.jp/">http://www.nict.go.jp/</a> (English and Japanese) and <a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a> (English and Japanese)</p> - <p>The user is expected to provide a symbolic link to an available serial port device. This is typically performed by a command such as:</p> + + <p>The JJY is the radio station which transmits the JST (Japan Standard Time) in long wave radio. The station JJY is operated by the National Institute of Information and Communications Technology. + An operating announcement and some information are available from <a href="http://www.nict.go.jp/">http://www.nict.go.jp/</a> (English and Japanese) and <a href="http://jjy.nict.go.jp/">http://jjy.nict.go.jp/</a> (English and Japanese)</p> + <p>The user is expected to provide a symbolic link to an available serial port device. This is typically performed by a command such as;</p> <p><code>ln -s /dev/ttyS0 /dev/jjy0</code></p> + <p>Using an RS-232C to USB converter cable, the clock or a modem can be connected to a USB port instead of a serial port. In this case, the typical symbolic link command is as follows;</p> + <p><code>ln -s /dev/ttyUSB0 /dev/jjy0</code></p> <p>Windows NT does not support symbolic links to device files. COM<em>X</em>: is the unit used by the driver, based on the refclock unit number, where unit 1 corresponds to COM1: and unit 3 corresponds to COM3:</p> <h4>Monitor Data</h4> - <p>The driver writes each timecode as received to the <code>clockstats</code> file.</p> + <p>The driver writes sent and received data to/from the JJY receivers, GPS clock, and the modem into the <code>clockstats</code> file.</p> + <p><code> + statsdir /var/log/ntpd/<br> + filegen clockstats file clockstats type day enable + </code></p> + <div style="text-align:left;">Mark of the clockstats record</div> + <table border="1" summary="Clockstats"> + <tr><td><code>JJY</code> </td><td>Infomation message ( This refclock starts or stops. )</td></tr> + <tr><td><code>--></code> </td><td>Sent data</td></tr> + <tr><td><code><--</code> </td><td>Received data</td></tr> + <tr><td><code>---</code> </td><td>Infomation message</td></tr> + <tr><td><code>===</code> </td><td>Infomation message ( Start of each polling, and sync. time. )</td></tr> + <tr><td><code>-W-</code> </td><td>Warning message</td></tr> + <tr><td><code>-X-</code> </td><td>Error message</td></tr> + </table> <h4>Fudge Factors</h4> <dl> - <dt><code>time1 <em>time</em></code> - <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0. - <dt><code>time2 <em>time</em></code> - <dd>Not used by this driver. - <dt><code>stratum <em>number</em></code> - <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0. - <dt><code>refid <em>string</em></code> - <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <code>JJY</code>. - <dt><code>flag1 0 | 1</code> - <dd>Not used by this driver. - <dt><code>flag2 0 | 1</code> - <dd>Not used by this driver. - <dt><code>flag3 0 | 1</code> - <dd>Not used by this driver. - <dt><code>flag4 0 | 1</code> + <dt><code>time1 <em>time</em></code></dt> + <dd>Specifies the time offset calibration factor, in seconds and fraction, with default 0.0.</dd> + <dt><code>time2 <em>time</em></code></dt> <dd>Not used by this driver. + <dt><code>stratum <em>number</em></code></dt> + <dd>Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd> + <dt><code>refid <em>string</em></code></dt> + <dd>Specifies the driver reference identifier, an ASCII string from one to four characters, with default <code>JJY</code>.</dd> + <dt><code>flag1 0 | 1</code></dt> + <dd>See corresponding receiver.</dd> + <dt><code>flag2 0 | 1</code></dt> + <dd>See corresponding receiver.</dd> + <dt><code>flag3 0 | 1</code></dt> + <dd>See corresponding receiver.</dd> + <dt><code>flag4 0 | 1</code></dt> + <dd>See corresponding receiver.</dd> </dl> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> diff --git a/contrib/ntp/html/drivers/driver42.html b/contrib/ntp/html/drivers/driver42.html index 7082050..86f676e 100644 --- a/contrib/ntp/html/drivers/driver42.html +++ b/contrib/ntp/html/drivers/driver42.html @@ -10,6 +10,9 @@ <body> <h3>Zyfer GPStarplus Receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Synopsis</h4> Address: 127.127.42.<i>u</i><br> @@ -27,4 +30,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver43.html b/contrib/ntp/html/drivers/driver43.html index 0e1553f..6d04102 100644 --- a/contrib/ntp/html/drivers/driver43.html +++ b/contrib/ntp/html/drivers/driver43.html @@ -10,6 +10,9 @@ <body> <h3>RIPE NCC interface for Trimble Palisade</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <img src="../pic/driver43_2.jpg" alt="Trimble Acutime 2000" align="right"> <h4>Synopsis</h4> @@ -62,4 +65,4 @@ S1 [prn] [channel] [aqflag] [ephstat] [snr] [azinuth] [elevation] <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver44.html b/contrib/ntp/html/drivers/driver44.html index d2cddb9..a3fac5c 100644 --- a/contrib/ntp/html/drivers/driver44.html +++ b/contrib/ntp/html/drivers/driver44.html @@ -11,6 +11,9 @@ <body> <h1>NeoClock4X - DCF77 / TDF serial line receiver<br> </h1> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr size="2" width="100%"> <h2>Synopsis</h2> <table width="100%"> @@ -85,4 +88,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/driver45.html b/contrib/ntp/html/drivers/driver45.html new file mode 100644 index 0000000..bef883f --- /dev/null +++ b/contrib/ntp/html/drivers/driver45.html @@ -0,0 +1,32 @@ +<!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 TSYNC PCI</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> + + <body> + <h3>Spectracom TSYNC PCI</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->26-Mar-2012 05:10<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + Address: 127.127.45.<i>u</i><br> + Reference ID: one of <tt>GPS</tt>, <tt>IRIG</tt>, <tt>HVQ</tt>, <tt>FREQ</tt>, <tt>ACTS</tt>, <tt>PPS</tt>, <tt>PTP</tt>, <tt>ACT</tt>, <tt>USR</tt>, <tt>LOCL</tt><br> + Driver ID: <tt>Spectracom TSYNC PCI</tt><br> + Driver Port: <tt>/dev/tsyncpci<i>u</i></tt> + Features: <tt>(none)</tt> + <h4>Description</h4> + <p>This driver supports the <a + href="http://www.spectracomcorp.com/ProductsServices/TimingSynchronization/BuslevelTiming">Spectracom TSYNC PCI</a> receiver.</p> + <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> diff --git a/contrib/ntp/html/drivers/driver46.html b/contrib/ntp/html/drivers/driver46.html new file mode 100644 index 0000000..cdb0b68 --- /dev/null +++ b/contrib/ntp/html/drivers/driver46.html @@ -0,0 +1,363 @@ +<!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>GPSD-NG client driver</title> + + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <style type="text/css"> + table.dlstable { font-size:85%; } + td.ttf{ font-family:Courier; font-weight:bold; } + </style></head> + + + + <body> + <h3>GPSD NG client driver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->30-Apr-2015 05:53<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + + <p> + Address: 127.127.46.<i>u</i><br> + Reference ID: <tt>GPSD</tt><br> + Driver ID: <tt>GPSD_JSON</tt><br> + Serial Port: <tt>/dev/gps<i>u</i></tt> as symlink to the true + device (not used directly; see below)<br> + Features: <tt></tt> + </p> + + <!-- --------------------------------------------------------- --> + + <br><h4>Description</h4> + <p> + This driver is a client driver to the <i>GPSD</i> daemon, which + over the time became increasingly popular for UN*Xish + platforms. <i>GPSD</i> can manage several devices in parallel, + aggregate information, and acts as a data hub for client + applications. <i>GPSD</i> can also auto-detect and handle PPS + hardware signals on serial ports. Have a look + at <a href="http://www.catb.org/gpsd/">the + <i>GPSD</i> project page</a>. + </p> + <p> + <b>It is important to understand that this driver works best + using a GPS device with PPS support.</b> + </p> + <p> + The GPSD-NG protocol is text based, using JSON notation to + transfer records in form of JSON objects. The driver uses a + TCP/IP connection to <tt>localhost:gpsd</tt> to connect to the + daemon and then requests the GPS + device <tt>/dev/gps<i>u</i></tt> to be watched. (Different clock + units use different devices, and + <i>GPSD</i> is able to give only the relevant information to a clock + instance.) + </p> + <p> + This driver does not expect <i>GPSD</i> to be running or the + clock device to be present <i>a priori</i>; it will try to + re-establish a lost or hitherto unsuccessful connection and will + wait for device to come up in <i>GPSD.</i> There is an initial + 10 seconds delay between a connection loss or failed attempt and + the next reconnect attempt; this makes sure that there is no + thrashing on the network layer. If the connection fails again, + an exponential back off is used with an upper limit of + approximately 10 minutes. + </p> + <p> + The overall accuracy depends on the receiver used. The driver + uses the error estimations (95% probability limits) provided by + <i>GPSD</i> to set the clock precision dynamically according to + these readings. + </p> + <p> + The driver needs the VERSION, TPV, PPS, WATCH and TOFF objects + of the <i>GPSD</i> protocol. (Others are quietly ignored.) The + driver can operate without the TOFF objects, which are available + with the <i>protocol</i> version 3.10 and above. (Not to be + confused with the <i>release</i> version of <i>GPSD</i>!) + Running without TOFF objects has a negative impact on the jitter + and offset of the serial timing information; if possible, a + version of <i>GPSD</i> with support for TOFF objects should be + used. + </p> + <p>The acronym <u>STI</u> is used here as a synonym for <i>serial + time information</i> from the data channel of the receiver, no + matter what objects were used to obtain it. + </p> + + <!-- --------------------------------------------------------- --> + + <br><h4>Naming a Device</h4> + <p> + The <i>GPSD</i> driver uses the same device name as the NMEA + driver, namely <tt>/dev/gps<i>u</i></tt>. There is a simple + reason for that: While the NMEA driver and the <i>GPSD</i> + driver can be active at the same time <b>for different + devices</b>, they cannot access the same device at a + time. Having the same name helps on that. It also eases + migration from using NMEA directly to using <i>GPSD</i>, as no + new links etc need to be created. + </p> + <p> + <i>GPSD</i> is normally started with the device name to access; + it can also be instructed by hot-plug scripts to add or remove + devices from its device pool. Luckily, the symlinks used by the + NMEA driver are happily accepted and used by <i>GPSD</i>; this + makes it possible to use the symlink names as device + identification. This makes the migration from the built-in NMEA + driver a bit easier. + </p> + <p><b>Note:</b> <i>GPSD</i> (as of version 3.10) cannot use kernel + mode PPS on devices that are hot-plugged. This would require to + attach the PPS line discipline to the character special file, + which is not possible when running with root privileges already + dropped. This is not likely to change in the future. + </p> + + <!-- --------------------------------------------------------- --> + + <br><h4>The 'mode' word</h4> + <p> + A few operation modes can be selected with the mode word. + </p> + <p> + <table border="1" frame="box" rules="all"> + <th colspan="3">The Mode Word</th> + <tr> <td>Bits</td><td>Value</td><td>Description</td> + </tr> + <tr> <td rowspan="4"align="center">0..1</td> + <td align="center">0</td> + <td>STI only operation. This mode is affected by the timing + stability of whatever protocol is used between the GPS + device and GPSD. + <br> + Running on STI only is not recommended in general. Possible + use cases include: + <ul> + <li>The receiver does not provide a PPS signal. + <li>The receiver <i>does</i> provide a PPS signal and + the secondary PPS unit is used. + <li>The receiver has a stable serial timing and a proper + fudge can be established. + <li>You have other time sources available and want to + establish a useful fudge value for <tt>time2</tt>. + </ul> + </td> + </tr> + <tr> + <td align="center">1</td> + <td>Strict operation. This mode needs a valid PPS and a + valid STI to combine the absolute time from the STI with + the time stamp from the PPS record. Does not feed clock + samples if no valid PPS+STI pair is available. + <br><br> + This type of operation results in an ordinary clock with a + very low jitter as long as the PPS data is available, but + the clock fails once PPS drops out. This mode is a + possible choice for receivers that provide a PPS signal + most of the time but have an unstable serial timing that + cannot be fudge-compensated. + </td> + </tr> + <tr><td align="center">2</td> + <td>Automatic mode. Tries to operate in strict mode unless + it fails to process valid samples for some time, currently + 120s. Then it reverts to STI-only operation until the PPS + is stable again for 40s, when strict mode is engaged + again. + <br><br><b>Important Notice: This is an expiremental + feature!</b><br> Switching between strict and STI-only + mode will cause changes in offset and jitter. Use this + mode only if STI-only works fairly well with your setup, + or if you expect longer dropouts of the PPS signal and + prefer to use STI alone over not getting synchronised at + all.</td> + </tr> + <tr> + <td align="center">3</td> + <td><i>(reserved for future extension, do not use)</i></td> + </tr> + <tr> + <td align="center">2..31</td> + <td colspan="2"><i>(reserved for future extension, do not + use)</i></td> + </tr> + </table> + </p> + + <!-- --------------------------------------------------------- --> + + <br><h4>Syslog flood throttle</h4> + <p>This driver can create a lot of syslog messages when things go + wrong, and cluttering the log files is frowned upon. So we + attempt to log persistent or recurring errors only once per + hour. On the other hand, when tracking a problem the syslog + flood throttle can get into the way.</p> + <p>Therefore, fudge <i>flag3</i> can be used to <i>disable</i> the + flood throttle at any time; the throttle is engaged by + default. Running with the syslog flood throttle disabled for + lengthy time is not recommended unless the log files are closely + monitored.</p> + + <!-- --------------------------------------------------------- --> + + <br><h4>PPS secondary clock unit</h4> + <p>Units with numbers ≥128 act as secondary clock unit for the + primary clock unit (u mod 128). A secondary unit processes only + the PPS data from <i>GPSD</i> and needs the corresponding master + unit to work<a href="#fn1" name="fn1bl"><sup>1</sup></a>. Use + the 'noselect' keyword on the primary unit if you are not + interested in its data. + </p><p>The secondary unit employs the usual precautions before + feeding clock samples:</p> + <ul> + <li>The system must be already in a synchronised state. + <li>The system offset must be less than 400ms absolute. + <li>The phase adjustment from the PPS signal must also be less + than 400ms absolute. + </ul> + <p>If fudge flag <tt>flag1</tt> is set for the secondary unit, the + unit asserts the PPS flag on the clock as long as PPS data is + available. This makes the unit eligible as PPS peer and should + only be used if the GPS receiver can be trusted for the quality + of its PPS signal<a href="fn2" + name="fn2bl"><sup>2</sup></a>. The PPS flag gets cleared if no + PPS records can be aquired for some time. The unit also flushes + the sample buffer at this point to avoid the use of stale PPS + data.</p> + <p><b>Attention:</b> This unit uses its own PPS fudge value + which must be set as fudge <tt>time1</tt>. Only the fudge + values <tt>time1</tt> and <tt>flag1</tt> have an impact on secondary + units.</p> + + <!-- --------------------------------------------------------- --> + + <br><h4>Clockstats</h4> + <p>If flag4 is set when the driver is polled, a clockstats record + is written for the primary clock unit. (The secondary PPS unit + does not provide clock stats on its own.) The first 3 fields are + the normal date, time, and IP address common to all clockstats + records. + </p><p> + <table border="1" frame="box" rules="all"> + <th colspan="2">The Clockstats Line</th> + <tr> <td>field</td><td>Description</td> </tr> + <tr> + <td align="center">1</td> + <td>Date as day number since NTP epoch.</td> + </tr><tr> + <td align="center">2</td> + <td>Time as seconds since midnight.</td> + </tr><tr> + <td align="center">3</td> + <td>(Pseudo-) IP address of clock unit.</td> + </tr><tr> + <td align="center">4</td> + <td>Number of received known JSON records since last + poll. The driver knows about TPV, PPS, TOFF, VERSION and + WATCH records; others are silently ignored. + </td> + </tr><tr> + <td align="center">5</td> + <td>Bad replies since last poll. A record is considered + malformed or a bad reply when it is missing vital fields + or the fields contain malformed data that cannot be + parsed. + </td> + </tr><tr> + <td align="center">6</td> + <td>Number of sample cycles since last poll that were + discarded because there was no GPS fix. This is + effectively the number of TPV records with a fix value + < 2 or without a time stamp. + </td> + </tr><tr> + <td align="center">7</td> + <td>Number of serial time information records (TPV or TOFF, + depending on the GPSD version) received since last poll. + </td> + </tr><tr> + <td align="center">8</td> + <td>Number of serial time information records used for + clock samples since the last poll. + </td> + </tr><tr> + <td align="center">9</td> + <td>Number of PPS records received since the last poll.</td> + </tr><tr> + <td align="center">10</td> + <td>Number of PPS records used for clock samples on the + secondary channel since the last poll. + </td> + </tr> + </table> + </p> + + <!-- --------------------------------------------------------- --> + + <br><h4>Fudge Factors</h4> + + <dl> + <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><a name="fudgetime2"><tt>time2 <i>time</i></tt></a></dt> + <dd><em>[Primary Unit]</em> Specifies the TPV/TIME 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>GPSD</tt>.</dd> + <dt><tt>flag1 0 | 1</tt></dt><dd><em>[<b>Secondary</b> + Unit]</em> When set, flags the secondary clock unit as a + potential PPS peer as long as good PPS data is available. + </dd> + <dt><tt>flag2 0 | 1</tt></dt> + <dd><em>[Primary Unit]</em> When set, <u>disables</u> the + processing of incoming PPS records. Intended as an aide to + test the effects of a PPS dropout when using automatic mode + (mode 2). + </dd> + <dt><tt>flag3 0 | 1</tt></dt><dd><em>[Primary Unit]</em> + If set, <u>disables</u> the log throttle. Useful when tracking + problems in the interaction between <i>GPSD</i> and <i>NTPD</i>, + since now all error events are logged. Persistent/recurrent + errors can easily fill up the log, so this should only be + enabled during bug hunts.</dd> + <dt><tt>flag4 0 | 1</tt></dt><dd><em>[Primary Unit]</em> + If set, write a clock stats line on every poll cycle. + </dd> + </dl> + + <!-- -- footnotes -------------------------------------------- --> + + <hr> + <p><a name="fn1" href="#fn1bl"><sup>1</sup>) </a>Data transmission + an decoding is done only once by the primary unit. The decoded + data is then processed independently in both clock units. This + avoids double transmission over two sockets and decoding the + same data twice, but the primary unit is always needed as a + downside of this approach. + </p> + <p><a name="fn2" href="#fn2bl"><sup>2</sup>) </a>The clock driver + suppresses the processing PPS records when the TPV/TIME data + indicates the receiver has no fix. It can also deal with + situations where the PPS signal is not delivered + to <i>GPSD</i>. But once it is available, it is also processed + and used to create samples. If a receiver cannot be trusted for + the precision of its PPS signal, it should not be used to create + a possible PPS peer: These get extra clout and can effectively + become the sole source of input for the control loop. You do not + want to use sloppy data for that. + <hr> + <p>Additional Information</p> + <p><a href="../refclock.html">Reference Clock Drivers</a></p> + <hr> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body></html> diff --git a/contrib/ntp/html/drivers/driver5.html b/contrib/ntp/html/drivers/driver5.html index 1b539ac..fa19764 100644 --- a/contrib/ntp/html/drivers/driver5.html +++ b/contrib/ntp/html/drivers/driver5.html @@ -2,71 +2,82 @@ <html> - <head> - <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> - <title>TrueTime GPS/GOES/OMEGA Receivers</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> + <head> + <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> + <title>TrueTime GPS/GOES/OMEGA/WWV Receivers</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> - <body> - <h3>TrueTime GPS/GOES/OMEGA Receivers</h3> - <hr> - <h4>Synopsis</h4> - Address: 127.127.5.<i>u</i><br> - Reference ID: <tt>GPS, OMEGA, GOES</tt><br> - Driver ID: <tt>TRUETIME</tt><br> - Serial Port: <tt>/dev/true<i>u</i></tt>; 9600 baud, 8-bits, no parity<br> - Features: <tt>tty_clk</tt> - <h4>Description</h4> - <p>This driver supports several models models of Kinemetrics/TrueTime timing receivers, including 468-DC MK III GOES Synchronized Clock, GPS- DC MK III and GPS/TM-TMD GPS Synchronized Clock, XL-DC (a 151-602-210, reported by the driver as a GPS/TM-TMD), GPS-800 TCU (an 805-957 with the RS232 Talker/Listener module), OM-DC OMEGA Synchronized Clock, and very likely others in the same model family that use the same timecode formats.</p> - <p>Most of this code is originally from refclock_wwvb.c with thanks. It has been so mangled that wwvb is not a recognizable ancestor.</p> - <p>Timcode format: <tt>ADDD:HH:MM:SSQCL</tt> A - control A (this is stripped before we see it) Q - Quality indication (see below) C - Carriage return L - Line feed Quality codes indicate possible error of</p> - <dl> - <dt>468-DC GOES Receiver<br> - GPS-TM/TMD Receiver - <dd>? +/- 500 milliseconds # +/- 50 milliseconds<br> - * +/- 5 milliseconds . +/- 1 millisecond<br> - space less than 1 millisecond - <dt>OM-DC OMEGA Receiver: - <dd>> +/- 5 seconds<br> - ? +/- 500 milliseconds # +/- 50 milliseconds<br> - * +/- 5 milliseconds . +/- 1 millisecond<br> - A-H less than 1 millisecond. Character indicates which station is being received as follows<br> - A = Norway, B = Liberia, C = Hawaii, D = North Dakota, E = La Reunion, F = Argentina, G = Australia, H = Japan<br> - The carriage return start bit begins on 0 seconds and extends to 1 bit time. - </dl> - <h4>Notes on 468-DC and OMEGA receiver:</h4> - <p>Send the clock a <tt>R</tt> or <tt>C</tt> and once per second a timestamp will appear. Send a <tt>R</tt> to get the satellite position once (GOES only).</p> - <h4>Notes on the 468-DC receiver:</h4> - <p>Since the old east/west satellite locations are only historical, you can't set your clock propagation delay settings correctly and still use automatic mode. The manual says to use a compromise when setting the switches. This results in significant errors. The solution; use fudge time1 and time2 to incorporate corrections. If your clock is set for 50 and it should be 58 for using the west and 46 for using the east, use the line</p> - <p><tt>fudge 127.127.5.0 time1 +0.008 time2 -0.004</tt></p> - <p>This corrects the 4 milliseconds advance and 8 milliseconds retard needed. The software will ask the clock which satellite it sees.</p> - <p>The PCL720 from PC Labs has an Intel 8253 look-alike, as well as a bunch of TTL input and output pins, all brought out to the back panel. If you wire a PPS signal (such as the TTL PPS coming out of a GOES or other Kinemetrics/Truetime clock) to the 8253's GATE0, and then also wire the 8253's OUT0 to the PCL720's INPUT3.BIT0, then we can read CTR0 to get the number of microseconds since the last PPS upward edge, mediated by reading OUT0 to find out if the counter has wrapped around (this happens if more than 65535us (65ms) elapses between the PPS event and our being called.)</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, to be used for the West satellite, with default 0.0. - <dt><tt>time2 <i>time</i></tt> - <dd>. Specifies the time offset calibration factor, in seconds and fraction, to be used for the East satellite, 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>TRUE</tt>. - <dt><tt>flag1 0 | 1</tt> - <dd>Silence the clock side of ntpd, just reading the clock without trying to write to it. - <dt><tt>flag2 0 | 1</tt> - <dd>Generate a debug file /tmp/true%d. - <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> + <body> + <h3>TrueTime GPS/GOES/OMEGA/WWV Receivers</h3> + <hr> + <h4>Synopsis</h4> + Address: 127.127.5.<i>u</i><br> + Reference ID: <tt>GPS, OMEGA, GOES, WWV</tt><br> + Driver ID: <tt>TRUETIME</tt><br> + Serial Port: <tt>/dev/true<i>u</i></tt>; 9600 baud, 8-bits, no parity<br> + Features: <tt>tty_clk</tt> + <h4>Description</h4> + <p>This driver supports several models models of Kinemetrics/TrueTime timing receivers, including 468-DC MK III GOES Synchronized Clock, GPS- DC MK III and GPS/TM-TMD GPS Synchronized Clock, XL-DC (a 151-602-210, reported by the driver as a GPS/TM-TMD), GPS-800 TCU (an 805-957 with the RS232 Talker/Listener module), OM-DC OMEGA Synchronized Clock, the TL-3 WWV receiver, and very likely others in the same model families that use the same timecode formats.</p> + <p>Most of this code is originally from refclock_wwvb.c with thanks. It has been so mangled that wwvb is not a recognizable ancestor.</p> + <p>Timcode format: <tt>ADDD:HH:MM:SSQCL</tt><br> +A - control A (this is stripped before we see it) Q - Quality indication (see below) C - Carriage return L - Line feed</p><br> +Quality codes indicate possible error of: + <dl> + <dt>468-DC GOES Receiver<br> + GPS-TM/TMD Receiver + <dd>? +/- 500 milliseconds # +/- 50 milliseconds<br> + * +/- 5 milliseconds . +/- 1 millisecond<br> + space less than 1 millisecond + <dt>OM-DC OMEGA Receiver: + <dd>> +/- 5 seconds<br> + ? +/- 500 milliseconds # +/- 50 milliseconds<br> + * +/- 5 milliseconds . +/- 1 millisecond<br> + A-H less than 1 millisecond. Character indicates which station is being received as follows<br> + A = Norway, B = Liberia, C = Hawaii, D = North Dakota, E = La Reunion, F = Argentina, G = Australia, H = Japan<br> + The carriage return start bit begins on 0 seconds and extends to 1 bit time. + <dt>TL-3 WWV Receiver: + <dd>? receiver is unlocked<br> + <dd>space +/- 5 milliseconds<br> + </dl> + <h4>Notes on 468-DC and OMEGA receiver:</h4> + <p>Send the clock a <tt>R</tt> or <tt>C</tt> and once per second a timestamp will appear. Send a <tt>R</tt> to get the satellite position once (GOES only).</p> + <h4>Notes on the 468-DC receiver:</h4> + <p>Since the old east/west satellite locations are only historical, you can't set your clock propagation delay settings correctly and still use automatic mode. The manual says to use a compromise when setting the switches. This results in significant errors. The solution; use fudge time1 and time2 to incorporate corrections. If your clock is set for 50 and it should be 58 for using the west and 46 for using the east, use the line</p> + <p><tt>fudge 127.127.5.0 time1 +0.008 time2 -0.004</tt></p> + <p>This corrects the 4 milliseconds advance and 8 milliseconds retard needed. The software will ask the clock which satellite it sees.</p> + <p>The PCL720 from PC Labs has an Intel 8253 look-alike, as well as a bunch of TTL input and output pins, all brought out to the back panel. If you wire a PPS signal (such as the TTL PPS coming out of a GOES or other Kinemetrics/Truetime clock) to the 8253's GATE0, and then also wire the 8253's OUT0 to the PCL720's INPUT3.BIT0, then we can read CTR0 to get the number of microseconds since the last PPS upward edge, mediated by reading OUT0 to find out if the counter has wrapped around (this happens if more than 65535us (65ms) elapses between the PPS event and our being called.)</p> + <h4>Notes on the TL-3 receiver:</h4> + <p>The mini-DIN RS-232 port uses the Apple pinout.<br> + Send the clock ST1 to turn on continuous (1/sec) timecodes. +You can also enable "mode C" via the front panel. ST0 turns off this mode.<br> +QV will return the firmware revision (and is useful in identifying this clock.)<br> +QW will return its weekly signal log, useful if you're testing antennas. You may wish to turn the loss interval down from 4h (04) to 1h (01), so the receiver declares itself unlocked sooner. When in holdover, drift can be on the order of 10 ms/hr since there is no high quality reference oscillator.</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, to be used for the West satellite, with default 0.0. + <dt><tt>time2 <i>time</i></tt> + <dd>. Specifies the time offset calibration factor, in seconds and fraction, to be used for the East satellite, 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>TRUE</tt>. + <dt><tt>flag1 0 | 1</tt> + <dd>Silence the clock side of ntpd, just reading the clock without trying to write to it. + <dt><tt>flag2 0 | 1</tt> + <dd>Generate a debug file /tmp/true%d. + <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 +</html> diff --git a/contrib/ntp/html/drivers/driver6.html b/contrib/ntp/html/drivers/driver6.html index 8a51f16..ebb3683 100644 --- a/contrib/ntp/html/drivers/driver6.html +++ b/contrib/ntp/html/drivers/driver6.html @@ -1,92 +1,80 @@ <!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> - <p>Note: This driver supersedes an older one of the same name, address and ID which required replacing the original kernel audio driver with another which worked only on older Sun SPARC architectures and SunOS operating systems. The new driver requires no modification of the operating system and works on FreeBSD, SunOS and Solaris. While it is generic and likely portable to other systems, it is somewhat slower than the original, since the extensive signal conditioning, filtering and decoding is done in user space, not kernel space.</p> - <h4>Description</h4> - <p>This driver supports the Inter-Range Instrumentation Group (IRIG) standard time distribution signal using the audio codec native to some workstations. This signal is generated by several radio clocks, including those made by Arbiter, Austron, Bancomm, Odetics, Spectracom and TrueTime, among others, although it is often an add-on option. The signal is connected via an optional attenuator box and cable to either the microphone or line-in port. The driver receives, demodulates and decodes the IRIG-B and IRIG-E signal formats using internal filters designed to reduce the effects of noise and interference.</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> - <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 load on the processor with older workstations. Generally, the accuracy with IRIG-E is about ten times worse than IRIG-B, but the processor load is ten times less.</p> - <p>The program 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. Cycle crossings relative to the corrected slice level determine the width of each pulse and its value - zero, one or position identifier. The data encode 20 BCD digits which determine the second, minute, hour and day of the year and sometimes 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. 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 trimmed-mean filter and used to update the system clock.</p> - <p>Infinite impulse response (IIR) filters are used with both IRIG-B and IRIG-E formats. An 800-Hz highpass filter is used for IRIG-B and a 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. An automatic gain control feature provides protection against overdriven or underdriven input signal amplitudes. It is designed to maintain adequate demodulator signal amplitude while avoiding occasional noise spikes. In order to assure reliable capture, the decompanded input signal amplitude must be greater than 100 units and the codec sample frequency error less than 250 PPM (.025 percent).</p> - <p>The program 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>Unlike other drivers, which can have multiple instantiations, this one supports only one. It does not seem likely that more than one audio codec would be useful in a single machine. More than one would probably chew up too much CPU time anyway.</p> - <h4>IRIG-B Timecode Format</h4> - <p>The 100 elements of the IRIG timecode are numbered from 0 through 99. Position identifiers occur at elements 0, 9, 19 and every ten thereafter to 99. The control function (CF) elements begin at element 50 (CF 1) and extend to element 78 (CF 27). The straight-binary-seconds (SBS) field, which encodes the seconds of the UTC day, begins at element 80 (CF 28) and extends to element 97 (CF 44). The encoding of elements 50 (CF 1) through 78 (CF 27) is device dependent. This driver presently decodes the CF elements, but does nothing with them.</p> - <p>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 will automatically reject the data and declare itself unsynchronized in this case. Some devices, in particular Spectracom radio/satellite clocks, provide additional year and status indication in the format:</p> - <pre> - Element CF Function - ------------------------------------- - 55 6 time sync status - 60-63 10-13 BCD year units - 65-68 15-18 BCD year tens -</pre> - Other devices set these elements to zero. - <h4>Performance and Horror Stories</h4> - <p>The <font face="symbol">m</font>-law companded data format allows considerable latitude in signal levels; however, an automatic gain control (AGC) function is implemented to further compensate for varying input signal levels and to avoid signal distortion. For proper operation, the IRIG signal source should be configured for analog signal levels, NOT digital TTL levels.</p> - <p>The accuracy of the system clock synchronized to the IRIG-B source with this driver and the <tt>ntpd</tt> daemon is 10-20 <font face="symbol">m</font>s with a Sun UltraSPARC II running Solaris 2.6 and maybe twice that with a Sun SPARC IPC running SunOS 4.1.3. Be however acutely aware that the accuracy with Solaris 2.8 and presumably beyond has seriously degraded to the order of several milliseconds. The Sun kernel driver has a sawtooth modulation with amplitude over 5 ms peak-peak and period 5.5 s. The crafty IRIG driver uses a transverse filter to remove the modulation and something called a botttom-fisher to remove incidental positive spikes especially prevalent with Sun Blade 1000 and possibly other systems. The result is nominal accuracy and jitter something less than 0.5 ms, but the this is still far inferior to the performance with older systems.</p> - <p>The processor resources consumed by the daemon can be significant, ranging from about 1.2 percent on the faster UltraSPARC II to 38 percent on the slower SPARC IPC. However, the overall timing accuracy is limited by the resolution and stability of the CPU clock oscillator and the interval between clock corrections, which is 64 s with this driver. This performance, while probably the best that can be achieved by the daemon itself, can be improved with assist from the PPS discipline as described elsewhere in this documentation.</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 serial port using a level converter such as the CT-17.</p> - <p>Each ICOM radio is assigned a unique 8-bit ID select code, usually expressed in hex format. To activate the CI-V interface, the <tt>mode</tt> keyword of the <tt>server</tt> configuration command specifies a nonzero select code in decimal format. A table of ID select codes for the known ICOM radios is given on the <a href="../audio.html">Reference Clock Audio Drivers</a> page. A missing <tt>mode</tt> keyword or a zero argument leaves the interface disabled.</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 sync from CHU. 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 or radio is inoperative, the driver quietly gives up with no harm done.</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. With debugging enabled (-d on the ntpd command line), the driver produces one line for each timecode in the following format: - <p><tt>00 1 98 23 19:26:52 721 143 0.694 47 20 0.083 66.5 3094572411.00027</tt></p> - <p>The first field containes the error flags in hex, where the hex bits are interpreted as below. This is followed by the IRIG status indicator, year of century, day of year and time of day. The status indicator and year are not produced by some IRIG devices. Following these fields are the carrier amplitude (0-8100), codec gain (0-255), field phase (0-79), time constant (2-20), modulation index (0-1), carrier phase error (0±0.5) and carrier frequency error (PPM). The last field is the on-time timestamp in NTP format. The fraction part is a good indicator of how well the driver is doing. With an UltrSPARC 30, this is normally within a few tens of microseconds relative to the IRIG-B signal and within a few hundred microseconds with IRIG-E.</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. - </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> +Last update: + <!-- #BeginDate format:En2m -->17-Jul-2014 02:17<!-- #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 μ-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 μ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 μs with standard deviation 10 μs. Most of this is due to residuals after filtering and averaging the raw codec samples, which have an inherent jitter of 125 μ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 μ-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> diff --git a/contrib/ntp/html/drivers/driver7.html b/contrib/ntp/html/drivers/driver7.html index 8e050e7..90baf61 100644 --- a/contrib/ntp/html/drivers/driver7.html +++ b/contrib/ntp/html/drivers/driver7.html @@ -1,88 +1,68 @@ <!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/chu_audio</tt> and <tt>/dev/audioctl</tt> - <h4>Description</h4> - <p>This driver synchronizes the computer time using data encoded in radio transmissions from Canadian time/frequency station CHU in Ottawa, Ontario. It replaces an earlier one, built by Dennis Ferguson in 1988, which required a special line discipline to preprocessed the signal. The new driver includes more powerful algorithms implemented directly in the driver and requires no preprocessing.</p> - <p>CHU transmissions are made continuously on 3330 kHz, 7335 kHz and 14670 kHz 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 night. The performance of this driver when tracking the station is ordinarily better than 1 ms in time with frequency drift less than 0.5 PPM when not tracking the station.</p> - <p>While there are currently no known commercial CHU receivers, a simple but effective receiver/demodulator can be constructed from an ordinary shortwave receiver and 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. The driver can use the modem to receive the radio signal and demodulate the data or, if available, the driver can use the audio codec of the Sun workstation or another with compatible audio interface. In the latter case, the driver implements the modem using DSP routines, so the radio can be connected directly to either the microphone or line input port.</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> - <p>Ordinarily, the driver poll interval is set to 14 (about 4.5 h), although this can be changed with configuration commands. As long as the clock is set or verified at least once during this interval, the NTP algorithms will consider the source reachable and selectable to discipline the system clock. However, if this does not happen for eight poll intervals, the algorithms will consider the source unreachable and some other source will be chosen (if available) to discipline the system clock.</p> - <p>The decoding algorithms process the data 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. In the case of format B bursts, which are sent once each minute, the burst is considered correct only if every character matches its repetition in the burst. In the case of format A messages, a majority decoder requires at least six repetitions for each digit in the timecode and more than half of the repetitions decode to the same digit. Every character in every burst provides an independent timestamp upon arrival with a potential total of over 60 timestamps for each minute.</p> - <p>A timecode in the format described below is assembled when all bursts have been received in the minute. The timecode is considered valid and the clock set when at least one valid format B burst has been decoded and the above requirements are met. The <tt>yyyy</tt> year field in the timecode indicates whether a valid format B burst has been received. Upon startup, this field is initialized at zero; when a valid format B burst is received, it is set to the current Gregorian year. The <tt>q</tt> quality character field in the timecode indicates whether a valid timecode has been determined. If any of the high order three bits of this character are set, the timecode is invalid.</p> - <p>Once the clock has been set for the first time, it will appear reachable and selectable to discipline the system clock, even if the broadcast signal is lost. 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 in this case, it is unlikely that the system clock could drift more than a few tens of milliseconds during periods of signal loss. To protect against this most unlikely situation, if after four days with no signals, the clock is considered unset and resumes the synchronization procedure from the beginning.</p> - <p>The last three fields in the timecode are useful in assessing the quality of the radio channel during the most recent minute bursts were received. The <tt>bcnt</tt> field shows the number of format A bursts in the range 1-8. The <tt>dist</tt> field shows the majority decoder distance, or the minimum number of sample repetitions for each digit of the timecode in the range 0-16. The <tt>tsmp</tt> field shows the number of timestamps determined in the range 0-60. For a valid timecode, <tt>bcnt</tt> must be at least 3, <tt>dist</tt> must be greater than <tt>bcnt</tt> and <tt>tsmp</tt> must be at least 20.</p> - <h4>Program Operation</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). This is done using a 4th-order IIR filter and limiter/discriminator with 500-Hz bandpass centered on 2125 Hz and followed by a FIR raised-cosine lowpass filter optimized for the 300-b/s data rate. Alternately, the driver can be compiled to delete the modem and input 300 b/s data directly from an external modem via a serial port.</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 value from the DSP modem is shifted into the corresponding register and the maximum and minimum over all 11 samples computed. This establishes a slice level midway between the maximum and minimum over all stages. For each stage, a signal level above this level is a mark (1) and below 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 mark bit (previous stop bit), space (start) bit, eight arbitrary information bits and the first of the two mark (stop) bits.</p> - <p>The shift registers are processed in round-robin order as each modem value arrives until one of them shows a valid framing pattern consisting of a mark bit, space bit, eight arbitrary data bits and a mark bit. When found, the data bits from the register with the best metric is chosen as the maximum likelihood character and the UART begins to process the next character.</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. A format B block contains the year and other information in ten hexadecimal digits. A format A block contains the timecode in ten decimal 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 code to correct the phase, 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 block 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> - <p>Each minute of transmission includes eight format A bursts containing two timecodes for each second from 31 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 block must match and the value must be in the range 2-9 and greater than in the previous burst.</p> - <p>As each hex 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 each minute of transmission, each row of the decoding matrix encodes the number of occurrences of each code found at the corresponding position of the timecode. However, the first digit (framing code) is always 6, the ninth (second tens) is always 3 and the last (second units) changes for each burst, so are not used.</p> - <p>The maximum over all occurrences at each timecode digit position is the distance for that position and the corresponding code is the maximum likelihood candidate. If the distance is zero, the decoder assumes a miss; if the distance is not more than half the total number of occurrences, the decoder assumes a soft error; if two different codes with the same distance are found, the decoder assumes a hard error. In all these cases the decoder encodes a non-decimal character which will later cause a format error when the timecode is reformatted. The decoding distance is defined as the minimum distance 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 timestamp offsets accumulated over the minute. A perfect set of nine bursts could generate as many as 90 timestamps, but the maximum the interface can handle is 60. These are processed by the interface 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.</p> - <p>Each ICOM radio is assigned a unique 8-bit ID select code, usually expressed in hex format. To activate the CI-V interface, the <tt>mode</tt> keyword of the <tt>server</tt> configuration command specifies a nonzero select code in decimal format. A table of ID select codes for the known ICOM radios is given below. 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. A missing <tt>mode</tt> keyword or a zero argument leaves the interface disabled.</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.330 MHz. If after five minutes at this frequency not more than two format A bursts have been received for any minute, the driver will tune to 7.335 MHz, then to 14.670 MHz, then return to 3.330 MHz and continue in this cycle. 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 or radio is inoperative, the driver quietly gives up with no harm done.</p> - <h4>Radio Broadcast Format</h4> - <p>The CHU time broadcast includes an audio signal compatible with the Bell 103 modem standard (mark = 2225 Hz, space = 2025 Hz). It consist of nine, ten-character bursts transmitted at 300 b/s and beginning each second from second 31 to second 39 of the minute. Each character consists of eight data bits plus one start bit and two stop bits to encode two hex digits. The burst data consist of five characters (ten hex digits) followed by a repeat of these characters. In format A, the characters are repeated in the same polarity; in format B, the characters are repeated in the opposite polarity.</p> - <p>Format A bursts are sent at seconds 32 through 39 of the minute in hex digits</p> - <p><tt>6dddhhmmss6dddhhmmss</tt></p> - <p>The first ten digits encode a frame marker (<tt>6</tt>) followed by the day (<tt>ddd</tt>), hour (<tt>hh</tt>), minute (<tt>mm</tt>) and second (<tt>ss</tt>). Since format A bursts are sent during the third decade of seconds the tens digit of <tt>ss</tt> is always 3. The driver uses this to determine correct burst synchronization. These digits are then repeated with the same polarity.</p> - <p>Format B bursts are sent at second 31 of the minute in hex digits</p> - <p><tt>xdyyyyttaaxdyyyyttaa</tt></p> - <p>The first ten digits encode a code (<tt>x</tt> described below) followed by the DUT1 (<tt>d</tt> in deciseconds), Gregorian year (<tt>yyyy</tt>), difference TAI - UTC (<tt>tt</tt>) and daylight time indicator (<tt>aa</tt>) peculiar to Canada. These digits are then repeated with inverted polarity.</p> - <p>The <tt>x</tt> is coded</p> - <dl> - <dt><tt>1</tt> - <dd>Sign of DUT (0 = +)/dd> - <dt><tt>2</tt> - <dd>Leap second warning. One second will be added. - <dt><tt>4</tt> - <dd>Leap second warning. One second will be subtracted. This is not likely to happen in our universe. - <dt><tt>8</tt> - <dd>Even parity bit for this nibble. - </dl> - <p>By design, the last stop bit of the last character in the burst coincides with 0.5 second. Since characters have 11 bits and are transmitted at 300 b/s, the last stop bit of the first character coincides with 0.5 - 10 * 11/300 = 0.133 second. Depending on the UART, character interrupts can vary somewhere between the beginning of bit 9 and end of bit 11. These eccentricities can be corrected along with the radio propagation delay using the <tt>fudge time1</tt> variable.</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:</p> - <p>A format <tt>chuA</tt> message is produced for each format A burst received in seconds 32 through 39 of the minute:</p> - <p><tt>chuA n b s code</tt></p> - <p>where <tt>n</tt> is the number of characters in the burst (0-11), <tt>b</tt> the burst distance (0-40), <tt>s</tt> the synchronization distance (0-40) and <tt>code</tt> the burst characters as received. Note that the hex digits in each character are reversed and the last ten digits inverted, so the burst</p> - <p><tt>11 40 1091891300ef6e76ecff</tt></p> - <p>is interpreted as containing 11 characters with burst distance 40. The nibble-swapped timecode shows DUT1 +0.1 second, year 1998 and TAI -UTC 31 seconds.</p> - <p>A format <tt>chuB</tt> message is produced for each format B burst received in second 31 of the minute:</p> - <p><tt>chuB n b f s m code</tt></p> - <p>where <tt>n</tt> is the number of characters in the burst (0-11), <tt>b</tt> the burst distance (0-40), <tt>f</tt> the field alignment (-1, 0, 1), <tt>s</tt>the synchronization distance (0-16), <tt>m</tt>the burst number (2-9) and <tt>code</tt> the burst characters as received. Note that the hex digits in each character are reversed, so the burst</p> - <p><tt>10 38 0 16 9 06851292930685129293</tt></p> - <p>is interpreted as containing 11 characters with burst distance 38, field alignment 0, synchronization distance 16 and burst number 9. The nibble-swapped timecode shows day 58, hour 21, minute 29 and second 39.</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 yy ddd hh:mm:ss.fff ld dut lset agc rfrq bcnt dist tsmp +<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> +Last update: + <!-- #BeginDate format:En2m -->17-Jul-2014 02:17<!-- #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 μ-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 μ-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 q quality character @@ -91,144 +71,74 @@ hh hour of day mm minute of hour ss second of minute - fff millisecond of second - l leap second warning - d DST state + lw leap second warning + dst DST state dut DUT sign and magnitude in deciseconds lset minutes since last set agc audio gain (0-255) - rfrq radio frequency - bcnt burst count - dist decoding distance + ident CHU identifier code + 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 is 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>Decoder alarm. A majority of repetitions for at least one digit of the timecode fails to agree. - <dt><tt>4</tt> - <dd>Timestamp alarm. Fewer than 20 timestamps have been determined. - <dt><tt>2</tt> - <dd>Format alarm. The majority timecode contains invalid bit combinations. - <dt><tt>1</tt> - <dd>Frame alarm. A framing or format error occurred on at least one burst during the minute. - </dl> - <p>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 condition that may in future result in an error.</p> - <dt><tt>yyyy ddd hh:mm:ss.fff</tt> - <dd>The timecode format itself is self explanatory. Note that the Gregorian year is decoded directly from the transmitted timecode. - <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 of June or December. - <dt><tt>d</tt> - <dd>The DST code for Canada encodes the state for all provinces. - <dt><tt>dut</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 program was started; after the clock is set, this is 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 or IRIG level control should be set for a value midway in this range. - <dt><tt>rfrq</tt> - <dd>The current radio frequency, if the CI-V interface is active, or 'X' if not. - <dt><tt>bcnt</tt> - <dd>The number of format A bursts received during the most recent minute bursts were received. - <dt><tt>dist</tt> - <dd>The minimum decoding distance determined during the most recent minute bursts were received. - <dt><tt>tsmp</tt> - <dd>The number of timestamps determined during the most recent minute bursts were received. - </dl> - <h4>Modes</h4> - <p>The <tt>mode</tt> keyword of the <tt>server</tt> configuration command specifies the ICOM ID select code. A missing or zero argument disables the CI-V interface. 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>IC725</td> - <td>0x28</td> - <td>40</td> - <td>IC781</td> - <td>0x26</td> - <td>38</td> - </tr> - <tr> - <td>IC726</td> - <td>0x30</td> - <td>48</td> - <td>R7000</td> - <td>0x08</td> - <td>8</td> - </tr> - <tr> - <td>IC735</td> - <td>0x04</td> - <td>4</td> - <td>R71</td> - <td>0x1A</td> - <td>26</td> - </tr> - <tr> - <td>IC751</td> - <td>0x1c</td> - <td>28</td> - <td>R7100</td> - <td>0x34</td> - <td>52</td> - </tr> - <tr> - <td>IC761</td> - <td>0x1e</td> - <td>30</td> - <td>R72</td> - <td>0x32</td> - <td>50</td> - </tr> - <tr> - <td>IC765</td> - <td>0x2c</td> - <td>44</td> - <td>R8500</td> - <td>0x4a</td> - <td>74</td> - </tr> - <tr> - <td>IC775</td> - <td>0x46</td> - <td>68</td> - <td>R9000</td> - <td>0x2a</td> - <td>42</td> - </tr> - </table> - <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> diff --git a/contrib/ntp/html/drivers/driver8.html b/contrib/ntp/html/drivers/driver8.html index fc12f33..ab21f0f 100644 --- a/contrib/ntp/html/drivers/driver8.html +++ b/contrib/ntp/html/drivers/driver8.html @@ -2,278 +2,277 @@ <html> - <head> - <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> - <title>Generic Reference Driver</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Generic Reference Driver</h3> - <hr> - <h4>Synopsis</h4> - Address: 127.127.8.<i>u</i><br> - Reference ID: <tt>PARSE</tt><br> - Driver ID: <tt>GENERIC</tt><br> - Serial Port: <tt>/dev/refclock-<i>u</i></tt>; TTY mode according to clock type<br> - PPS device: <tt>/dev/refclockpps-<i>u</i></tt>; alternate PPS device (if not available via the serial port) - <h4>Description</h4> - The PARSE driver supports 20 different clock types/configurations. PARSE is actually a multi-clock driver.<br> - <br> - <p>The actual receiver status is mapped into various synchronization states generally used by receivers. The driver is configured to interpret the time codes of Meinberg DCF77 AM receivers, DCF77 FM receivers, Meinberg GPS16x/17x receivers, Trimble SV6 GPS, ELV DCF7000, Schmid, Wharton 400A and low cost receivers (see <a href="#clocklist">list below</a>).</p> - <p>The reference clock support in NTP contains the necessary configuration tables for those receivers. In addition to supporting several different clock types and up to 4 devices, the processing of a PPS signal is also provided as a configuration option. The PPS configuration option uses the receiver-generated time stamps for feeding the PPS loopfilter control for much finer clock synchronization.</p> - <p>CAUTION: The PPS configuration option is different from the hardware PPS signal, which is also supported (see below), as it controls the way ntpd is synchronized to the reference clock, while the hardware PPS signal controls the way time offsets are determined.</p> - <p>The use of the PPS option requires receivers with an accuracy of better than 1ms.</p> - <h4>Timecode variables listed by ntpq (8)</h4> - <p>The ntpq program can read and display several clock variables. These hold the following information:</p> - <dl> - <dt><tt>refclock_format</tt></dt> - <dd>A qualification of the decoded time code format.</dd> - <dt><tt>refclock_states</tt></dt> - <dd>The overall running time and the accumulated times for the clock event states.</dd> - <dt><tt>refclock_status</tt></dt> - <dd>Lists the currently active receiver flags. Additional feature flags for the receiver are optionally listed in parentheses.</dd> - <dt><tt>refclock_time</tt></dt> - <dd>The local time with the offset to UTC (format HHMM).</dd> - <dt><tt>timecode</tt></dt> - <dd>The actual time code.</dd> - </dl> - <p>If PPS information is present, additional variables are available:</p> - <dl> - <dt><tt>refclock_ppsskew</tt></dt> - <dd>The difference between the RS-232-derived timestamp and the PPS timestamp.</dd> - <dt><tt>refclock_ppstime</tt></dt> - <dd>The PPS timestamp.</dd> - </dl> - <h4>Supported Devices</h4> - <p>Currently, nineteen clock types (devices /dev/refclock-0 - /dev/refclock-3) are supported by the PARSE driver.<br> - A note on the implementations:</p> - <ul> - <li>These implementations were mainly done without actual access to the hardware, thus not all implementations provide full support. The development was done with the help of many kind souls who had the hardware and kindly lent me their time and patience during the development and debugging cycle. Thus for continued support and quality, direct access to the receivers is a big help. Nevertheless I am not prepared to buy these reference clocks - donations to (<a href="mailto:kardel <AT> ntp.org">kardel <AT> ntp.org</a>) are welcome as long as they work within Europe 8-). - <p>Verified implementations are:</p> - <ul> - <li>RAWDCF variants - <p>These variants have been tested for correct decoding with my own homegrown receivers. Interfacing with specific commercial products may involve some fiddling with cables. In particular, commercial RAWDCF receivers have a seemingly unlimited number of ways to draw power from the RS-232 port and to encode the DCF77 datastream. You are mainly on your own here unless I have a sample of the receiver.</p> - <li><a href="http://www.meinberg.de">Meinberg clocks</a> - <p>These implementations have been verified by the Meinberg people themselves and I have access to one of these clocks.</p> - </ul> - </ul> - <p>The pictures below have been taken from and are linked to the vendors' web pages.</p> - <a name="clocklist"></a> - <ul> - <li><b><tt>server 127.127.8.0-3 mode 0</tt></b> - <p><b><tt><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/timesource.htm#dcf---freq_sync">PZF5xx receiver family</a> (FM demodulation/TCXO / 50μs)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 1</tt></b> - <p><b><tt><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/timesource.htm#dcf---freq_sync">PZF5xx receiver family</a> (FM demodulation/OCXO / 50μs)</tt></b><br> - <a href="http://www.meinberg.de/english/products/pzf-eurocard.htm"><img src="../pic/pzf511.jpg" alt="Image PZF511" height="300" width="260" align="top" border="0"></a><br> - <br></p> - - <li><a name="mode2"></a><b><tt>server 127.127.8.0-3 mode 2</tt></b> - <p><b><tt><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/c51.htm">DCF C51 receiver and similar</a> (AM demodulation / 4ms)</tt></b><br> - <a href="http://www.meinberg.de/english/products/c51.htm"><img src="../pic/c51.jpg" alt="Image C51" height="239" width="330" align="top" border="0"></a><br> - </p> - <p>This mode expects the Meinberg standard time string format with 9600/7E2.</p> - <p><b>Note:</b> mode 2 must also be used for <a href="http://www.meinberg.de/english/products/formfactor.htm#slot_card">Meinberg PCI cards</a> under Linux, e.g. <a href="http://www.meinberg.de/english/products/gps-pcicard.htm">the GPS PCI card</a> or <a href="http://www.meinberg.de/english/products/dcf-pcicard.htm">the DCF77 PCI card</a>. Please note the <a href="http://www.meinberg.de/english/sw/#linux">Meinberg Linux driver</a> must be installed. That driver emulates a refclock device in order to allow ntpd to access those cards. For details, please refer to the README file that comes with the Meinberg driver package.<br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 3</tt></b> - <p><b><tt><a href="http://www.elv.de">ELV</a> DCF7000 (sloppy AM demodulation / 50ms)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 4</tt></b> - <p><b><tt>Walter Schmid DCF receiver Kit (AM demodulation / 1ms)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 5</tt></b> - <p><b><tt>RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 6</tt></b> - <p><b><tt>RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 7</tt></b> - <p><b><tt><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/timesource.htm#gps---freq_sync">GPS16x/GPS17x receivers</a> (GPS / <<1μs)</tt></b><br> - <a href="http://www.meinberg.de/english/products/gps-eurocard.htm"><img src="../pic/gps167.jpg" alt="Image GPS167" height="300" width="280" align="top" border="0"></a><br> - </p> - <p>This mode expects either the University of Erlangen time string format or the Meinberg standard time string format at 19200/8N1.</p> - <p>The University of Erlangen format is preferred. Newer Meinberg GPS receivers can be configured to transmit that format; for older devices, a special firmware version may be available.</p> - <p>In this mode some additional GPS receiver status information is also read. However, this requires a point-to-point connection. <a href="#mode18">Mode 18</a> should be used if the device is accessed by a multidrop connection.</p> - <p><b>Note:</b> mode 7 must not be used with Meinberg PCI cards; use <a href="#mode2">mode 2</a> instead.<br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 8</tt></b> - <p><b><tt><a href="http://www.igel.de">IGEL</a> <a href="http://www.igel.de/eigelmn.html">clock</a></tt></b><br> - <a href="http://www.igel.de/eigelmn.html"><img src="../pic/igclock.gif" alt="Image IGEL clock" height="174" width="200" border="0"></a><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 9</tt></b> - <p><b><tt><a href="http://www.trimble.com">Trimble</a> <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om011.html">SVeeSix GPS receiver</a> TAIP protocol (GPS / <<1μs)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 10</tt></b> - <p><b><tt><a href="http://www.trimble.com">Trimble</a> <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om011.html">SVeeSix GPS receiver</a> TSIP protocol (GPS / <<1μs) (no kernel support yet)</tt></b><br> - <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om011.html"><img src="../pic/pd_om011.gif" alt="Image SVeeSix-CM3" height="100" width="420" align="top" border="0"></a><br> - <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om006.html"><img src="../pic/pd_om006.gif" alt="Image Lassen-SK8" height="100" width="420" border="0"></a><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 11</tt></b> - <p><b><tt>Radiocode Clocks Ltd RCC 8000 Intelligent Off-Air Master Clock support </tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 12</tt></b> - <p><b><tt><a href="http://www.hopf-time.com">HOPF</a> <a href="http://www.hopf-time.com/kart6021.html">Funkuhr 6021</a></tt></b><br> - <a href="http://www.hopf-time.com/engl/kart6021.html"><img src="../pic/fg6021.gif" alt="Image DCF77 Interface Board" height="207" width="238" align="top" border="0"></a><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 13</tt></b> - <p><b><tt>Diem's Computime Radio Clock</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 14</tt></b> - <p><b><tt>RAWDCF receiver (DTR=high/RTS=low)</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 15</tt></b> - <p><b><tt>WHARTON 400A Series Clocks with a 404.2 Serial Interface</tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 16</tt></b> - <p><b><tt>RAWDCF receiver (DTR=low/RTS=high) </tt></b><br> - <br></p> - - <li><b><tt>server 127.127.8.0-3 mode 17</tt></b> - <p><b><tt>VARITEXT Receiver (MSF) </tt></b><br> - <br></p> - - <li><a name="mode18"></a><b><tt>server 127.127.8.0-3 mode 18</tt></b> - <p><b><tt><a href="http://www.meinberg.de">Meinberg </a><a href="http://www.meinberg.de/english/products/timesource.htm#gps---freq_sync">GPS16x/GPS17x receivers</a> (GPS / <<1μs)</tt></b><br> - </p> - <p>This mode works without additional data communication (version, GPS status etc.) and thus should be used with multidrop, heterogeneous multiclient operation.</p> - <p><b>Note:</b> mode 18 must not be used with Meinberg PCI cards, use mode 2 instead.<br> - <br></p> - <li><b><tt>server 127.127.8.0-3 mode 19</tt></b> - <p><b><tt>Gude Analog- und Digitalsystem GmbH 'Expert mouseCLOCK USB v2.0'</tt></b><br> - <br></p> - - </ul> - <p>Actual data formats and setup requirements of the various clocks can be found in <a href="../parsedata.html">NTP PARSE clock data formats</a>.</p> - <h4>Operation</h4> - <p>The reference clock support software carefully monitors the state transitions of the receiver. All state changes and exceptional events (such as loss of time code transmission) are logged via the syslog facility. Every hour a summary of the accumulated times for the clock states is listed via syslog.</p> - <p>PPS support is only available when the receiver is completely synchronized. The receiver is believed to deliver correct time for an additional period of time after losing synchronization, unless a disruption in time code transmission is detected (possible power loss). The trust period is dependent on the receiver oscillator and thus is a function of clock type.</p> - <p>Raw DCF77 pulses can be fed via a level converter to the RXD pin of an RS-232 serial port (pin 3 of a 25-pin connector or pin 2 of a 9-pin connector). The telegrams are decoded and used for synchronization. DCF77 AM receivers can be bought for as little as $25. The accuracy is dependent on the receiver and is somewhere between 2ms (expensive) and 10ms (cheap). Synchronization ceases when reception of the DCF77 signal deteriorates, since no backup oscillator is available as usually found in other reference clock receivers. So it is important to have a good place for the DCF77 antenna. During transmitter shutdowns you are out of luck unless you have other NTP servers with alternate time sources available.</p> - <p>In addition to the PPS loopfilter control, a true PPS hardware signal can be utilized via the PPSAPI interface. PPS pulses are usually fed via a level converter to the DCD pin of an RS-232 serial port (pin 8 of a 25-pin connector or pin 1 of a 9-pin connector). To select PPS support, the mode parameter is the mode value as above plus 128. If 128 is not added to the mode value, PPS will be detected to be available but will not be used. - </p> - <h4>Hardware PPS support<br> - </h4> - <p>For PPS to be used, add 128 to the mode parameter.</p> - <p>If the PPS signal is fed in from a device different from the device providing the serial communication (/dev/refclock-{0..3}), this device is configured as /dev/refclockpps-{0..3}. This allows the PPS information to be fed in e.g. via the parallel port (if supported by the underlying operation system) and the date/time telegrams to be handled via the serial port.</p> - <h4>Monitor Data</h4> - <p>Clock state statistics are written hourly to the syslog service. Online information can be found by examining the clock variables via the <code>ntpq cv</code> command.<br> - Some devices have quite extensive additional information (GPS16x/GPS17x, Trimble). The driver reads out much of the internal GPS data - and makes it accessible via clock variables. To find out about additional variable names, query for the clock_var_list variable on - a specific clock association as shown below. - </p> - <p>First let <code>ntpq</code> display the table of associations:</p> - <pre> - ntpq> as - ind assID status conf reach auth condition last_event cnt - =========================================================== - 1 19556 9154 yes yes none falsetick reachable 5 - 2 19557 9435 yes yes none candidat clock expt 3 - 3 19558 9714 yes yes none pps.peer reachable 1 - </pre> - <p>Then switch to raw output. This may be required because of display limitations in ntpq/ntpd - so large lists need to be retrieved in several queries.</p> - <pre> - ntpq> raw - Output set to raw - </pre> - <p>Use the cv command to read the list of clock variables of a selected association:</p> - <pre> - ntpq> cv 19557 clock_var_list - </pre> - <p>The long output of the command above looks similar to:</p> - <pre> - assID=19557 status=0x0000, - clock_var_list="type,timecode,poll,noreply,badformat,baddata,fudgetime1, - fudgetime2,stratum,refid,flags,device,clock_var_list,refclock_time,refclock_status, - refclock_format,refclock_states,refclock_id,refclock_iomode,refclock_driver_version, - meinberg_gps_status,gps_utc_correction,gps_message,meinberg_antenna_status,gps_tot_51, - gps_tot_63,gps_t0a,gps_cfg[1],gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3], - gps_health[3],gps_cfg[4],gps_health[4],gps_cfg[5]" - </pre> - <p>Then use the cv command again to list selected clock variables. The following command must be entered as a single line:</p> - <pre> - ntpq> cv 19557 refclock_status,refclock_format,refclock_states,refclock_id, - refclock_iomode,refclock_driver_version,meinberg_gps_status,gps_utc_correction, - gps_message,meinberg_antenna_status,gps_tot_51,gps_tot_63,gps_t0a,gps_cfg[1], - gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3],gps_health[3],gps_cfg[4], - gps_health[4],gps_cfg[5] - </pre> - <p>The output of the command above is wrapped around depending on the screen width and looks similar to:</p> - <pre> - status=0x0003, - refclock_status="UTC DISPLAY; TIME CODE; PPS; POSITION; (LEAP INDICATION; - PPS SIGNAL; POSITION)", - refclock_format="Meinberg GPS Extended", - refclock_states="*NOMINAL: 21:21:36 (99.99%); FAULT: 00:00:03 (0.00%); - running time: 21:21:39", - refclock_id="GPS", refclock_iomode="normal", - refclock_driver_version="refclock_parse.c,v 4.77 2006/08/05 07:44:49 - kardel RELEASE_20060805_A", - meinberg_gps_status="[0x0000] <OK>", - gps_utc_correction="current correction 14 sec, last correction - on c7619a00.00000000 Sun, Jan 1 2006 0:00:00.000", - gps_message="/PFU3SOP-4WG14EPU0V1KA", - meinberg_antenna_status="RECONNECTED on 2006-07-18 08:13:20.0000000 (+0000) - UTC CORR, LOCAL TIME, reconnect clockoffset +0.0000000 s, - disconnect time 0000-00-00 00:00:00.0000000 (+0000) ", - gps_tot_51="week 1400 + 3 days + 42300.0000000 sec", - gps_tot_63="week 1400 + 3 days + 42294.0000000 sec", - gps_t0a="week 1400 + 5 days + 71808.0000000 sec", - gps_cfg[1]="[0x9] BLOCK II", gps_health[1]="[0x0] OK;SIGNAL OK", - gps_cfg[2]="[0x0] BLOCK I", gps_health[2]="[0x3f] PARITY;MULTIPLE ERRS", - gps_cfg[3]="[0x9] BLOCK II", gps_health[3]="[0x0] OK;SIGNAL OK", - gps_cfg[4]="[0x9] BLOCK II", gps_health[6]="[0x0] OK;SIGNAL OK", - gps_cfg[5]="[0x9] BLOCK II" - </pre> - <h4>Fudge Factors</h4> - <dl> - <dt><tt>time1 <i>time</i></tt> - <dd>Specifies the time offset calibration factor, in seconds and fraction. The default value depends on the clock type. - <dt><tt>time2 <i>time</i></tt> - <dd> - If flag1 is 0, time2 specifies the offset of the PPS signal from the actual time (PPS fine tuning). - <dd> - If flag1 is 1, time2 specifies the number of seconds a receiver with a premium local oscillator can be trusted after losing synchronisation. - <dt><tt>stratum <i>stratum</i></tt> - <dd>The stratum for this reference clock. - <dt><tt>refid <i>refid</i></tt> - <dd>The refid for this reference clock. - </dl> - <dl> - <dt><tt>flag1 { 0 | 1 }</tt> - <dd>If 0, the fudge factor <tt>time2</tt> refers to the PPS offset. - <dd>If 1, <tt>time2</tt> refers to the TRUST TIME. - <dt><tt>flag2 { 0 | 1 }</tt> - <dd>If <tt>flag2</tt> is 1, sample PPS on CLEAR instead of on ASSERT. - <dt><tt>flag3 { 0 | 1 }</tt> - <dd>If <tt>flag3</tt> is 1, link kernel PPS tracking to this refclock instance. - <dt><tt>flag4 { 0 | 1 }</tt> - <dd>Delete next leap second instead of adding it. (You'll need to wait a bit for that to happen 8-) - </dl> - <span style="font-weight: bold;">Note about auxiliary Sun STREAMS modules (SunOS and Solaris):</span><br> - <dl> - <dt>The timecode of these receivers can be sampled via a STREAMS module in the kernel. (The STREAMS module has been designed for use with Sun systems under SunOS 4.1.x or Solaris 2.3 - 2.8. It can be linked directly into the kernel or loaded via the loadable driver mechanism.) This STREAMS module can be adapted to convert different time code formats. Nowadays the PPSAPI mechanism is usually used. - </dl> - <h4>Making your own PARSE clocks</h4> - <p>The parse clock mechanism deviates from the way other NTP reference clocks work. For a short description of how to build parse reference clocks, see <a href="../parsenew.html">making PARSE clocks</a>.</p> - <p>Additional Information</p> - <p><a href="../refclock.html">Reference Clock Drivers</a></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"> + <title>Generic Reference Driver</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> + <body> + <h3>Generic Reference Driver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->27-Jan-2014 05:31<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + Address: 127.127.8.<em>u</em><br> + Reference ID: PARSE<br> + Driver ID: GENERIC<br> + Serial Port: /dev/refclock-<em>u</em>; TTY mode according to clock type<br> + PPS device: /dev/refclockpps-<em>u</em>; alternate PPS device (if not available via the serial port) + <h4>Description</h4> + The PARSE driver supports 20 different clock types/configurations. PARSE is actually a multi-clock driver.<br> + <br> + <p>The actual receiver status is mapped into various synchronization states generally used by receivers. The driver is configured to interpret the time codes of Meinberg DCF77 AM receivers, DCF77 FM receivers, Meinberg GPS16x/17x receivers, Trimble SV6 GPS, ELV DCF7000, Schmid, Wharton 400A and low cost receivers (see <a href="imap://mills@mail.eecis.udel.edu:993/fetch%3EUID%3E.INBOX%3E67132?part=1.3&type=text/html&filename=driver8.html#clocklist">list below</a>).</p> + <p>The reference clock support in NTP contains the necessary configuration tables for those receivers. In addition to supporting several different clock types and up to 4 devices, the processing of a PPS signal is also provided as a configuration option. The PPS configuration option uses the receiver-generated time stamps for feeding the PPS loopfilter control for much finer clock synchronization.</p> + <p>CAUTION: The PPS configuration option is different from the hardware PPS signal, which is also supported (see below), as it controls the way ntpd is synchronized to the reference clock, while the hardware PPS signal controls the way time offsets are determined.</p> + <p>The use of the PPS option requires receivers with an accuracy of better than 1ms.</p> + <h4>Timecode variables listed by ntpq (8)</h4> + <p>The ntpq program can read and display several clock variables. These hold the following information:</p> + <dl> + <dt>refclock_format</dt> + <dd>A qualification of the decoded time code format.</dd> + <dt>refclock_states</dt> + <dd>The overall running time and the accumulated times for the clock event states.</dd> + <dt>refclock_status</dt> + <dd>Lists the currently active receiver flags. Additional feature flags for the receiver are optionally listed in parentheses.</dd> + <dt>refclock_time</dt> + <dd>The local time with the offset to UTC (format HHMM).</dd> + <dt>timecode</dt> + <dd>The actual time code.</dd> + </dl> + <p>If PPS information is present, additional variables are available:</p> + <dl> + <dt>refclock_ppsskew</dt> + <dd>The difference between the RS-232-derived timestamp and the PPS timestamp.</dd> + <dt>refclock_ppstime</dt> + <dd>The PPS timestamp.</dd> + </dl> + <h4>Supported Devices</h4> + <p>Currently, twenty-four clock types are supported by the PARSE driver and up to four (devices /dev/refclock-0 - /dev/refclock-3) of these clocks may be operational at any one time.<br> + A note on the implementations:</p> + <ul> + <li>These implementations were mainly done without actual access to the hardware, thus not all implementations provide full support. The development was done with the help of many kind souls who had the hardware and kindly lent me their time and patience during the development and debugging cycle. Thus for continued support and quality, direct access to the receivers is a big help. Nevertheless I am not prepared to buy these reference clocks - donations to (<a href="mailto:kardel%20%3CAT%3E%20ntp.org">kardel <AT> ntp.org</a>) are welcome as long as they work within Europe 8-). + <p>Verified implementations are:</p> + <ul> + <li>RAWDCF variants + <p>These variants have been tested for correct decoding with my own homegrown receivers. Interfacing with specific commercial products may involve some fiddling with cables. In particular, commercial RAWDCF receivers have a seemingly unlimited number of ways to draw power from the RS-232 port and to encode the DCF77 datastream. You are mainly on your own here unless I have a sample of the receiver.</p> + </li> + <li><a href="http://www.meinberg.de">Meinberg clocks</a> + <p>These implementations have been verified by the Meinberg people themselves and I have access to one of these clocks.</p> + </li> + <li><a href="http://www.selinc.com">Schweitzer Engineering + Laboratories SEL-240x clocks</a> + <p>This implementation was provided and verified by SEL and <a + href="http://networktimefoundation.org">Network Time Foundation</a> + has an SEL-2407 in one of its development labs.</p> + </li> + </ul> + </li> + </ul> + <p>The pictures below have been taken from and are linked to the vendors' web pages.</p> + <a name="clocklist"></a> + <ul> + <li><strong>server 127.127.8.0-3 mode 0</strong> + <p><strong><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/timesource.htm#dcf---freq_sync">PZF5xx receiver family</a> (FM demodulation/TCXO / 50μs)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 1</strong> + <p><strong><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/timesource.htm#dcf---freq_sync">PZF5xx receiver family</a> (FM demodulation/OCXO / 50μs)</strong><br> + <a href="http://www.meinberg.de/english/products/pzf-eurocard.htm"><img src="../pic/pzf511.jpg" alt="Image PZF511" align="top" border="0" height="300" width="260"></a><br> + <br> + </p> + </li> + <li><a name="mode2"></a><strong>server 127.127.8.0-3 mode 2</strong> + <p><strong><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/c51.htm">DCF C51 receiver and similar</a> (AM demodulation / 4ms)</strong><br> + <a href="http://www.meinberg.de/english/products/c51.htm"><img src="../pic/c51.jpg" alt="Image C51" align="top" border="0" height="239" width="330"></a><br> + </p> + <p>This mode expects the Meinberg standard time string format with 9600/7E2.</p> + <p><strong>Note:</strong> mode 2 must also be used for <a href="http://www.meinberg.de/english/products/formfactor.htm#slot_card">Meinberg PCI cards</a> under Linux, e.g. <a href="http://www.meinberg.de/english/products/gps-pcicard.htm">the GPS PCI card</a> or <a href="http://www.meinberg.de/english/products/dcf-pcicard.htm">the DCF77 PCI card</a>. Please note the <a href="http://www.meinberg.de/english/sw/#linux">Meinberg Linux driver</a> must be installed. That driver emulates a refclock device in order to allow ntpd to access those cards. For details, please refer to the README file that comes with the Meinberg driver package.<br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 3</strong> + <p><strong><a href="http://www.elv.de">ELV</a> DCF7000 (sloppy AM demodulation / 50ms)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 4</strong> + <p><strong>Walter Schmid DCF receiver Kit (AM demodulation / 1ms)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 5</strong> + <p><strong>RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 6</strong> + <p><strong>RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 7</strong> + <p><strong><a href="http://www.meinberg.de">Meinberg</a> <a href="http://www.meinberg.de/english/products/timesource.htm#gps---freq_sync">GPS16x/GPS17x receivers</a> (GPS / <<1μs)</strong><br> + <a href="http://www.meinberg.de/english/products/gps-eurocard.htm"><img src="../pic/gps167.jpg" alt="Image GPS167" align="top" border="0" height="300" width="280"></a><br> + </p> + <p>This mode expects either the University of Erlangen time string format or the Meinberg standard time string format at 19200/8N1.</p> + <p>The University of Erlangen format is preferred. Newer Meinberg GPS receivers can be configured to transmit that format; for older devices, a special firmware version may be available.</p> + <p>In this mode some additional GPS receiver status information is also read. However, this requires a point-to-point connection. <a href="imap://mills@mail.eecis.udel.edu:993/fetch%3EUID%3E.INBOX%3E67132?part=1.3&type=text/html&filename=driver8.html#mode18">Mode 18</a> should be used if the device is accessed by a multidrop connection.</p> + <p><strong>Note:</strong> mode 7 must not be used with Meinberg PCI cards; use <a href="imap://mills@mail.eecis.udel.edu:993/fetch%3EUID%3E.INBOX%3E67132?part=1.3&type=text/html&filename=driver8.html#mode2">mode 2</a> instead.<br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 8</strong> + <p><strong><a href="http://www.igel.de">IGEL</a> <a href="http://www.igel.de/eigelmn.html">clock</a></strong><br> + <a href="http://www.igel.de/eigelmn.html"><img src="../pic/igclock.gif" alt="Image IGEL clock" border="0" height="174" width="200"></a><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 9</strong> + <p><strong><a href="http://www.trimble.com">Trimble</a> <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om011.html">SVeeSix GPS receiver</a> TAIP protocol (GPS / <<1μs)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 10</strong> + <p><strong><a href="http://www.trimble.com">Trimble</a> <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om011.html">SVeeSix GPS receiver</a> TSIP protocol (GPS / <<1μs) (no kernel support yet)</strong><br> + <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om011.html"><img src="../pic/pd_om011.gif" alt="Image SVeeSix-CM3" align="top" border="0" height="100" width="420"></a><br> + <a href="http://www.trimble.com/cgi/omprod.cgi/pd_om006.html"><img src="../pic/pd_om006.gif" alt="Image Lassen-SK8" border="0" height="100" width="420"></a><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 11</strong> + <p><strong>Radiocode Clocks Ltd RCC 8000 Intelligent Off-Air Master Clock support </strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 12</strong> + <p><strong><a href="http://www.hopf-time.com">HOPF</a> <a href="http://www.hopf-time.com/kart6021.html">Funkuhr 6021</a></strong><br> + <a href="http://www.hopf-time.com/engl/kart6021.html"><img src="../pic/fg6021.gif" alt="Image DCF77 Interface Board" align="top" border="0" height="207" width="238"></a><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 13</strong> + <p><strong>Diem's Computime Radio Clock</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 14</strong> + <p><strong>RAWDCF receiver (DTR=high/RTS=low)</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 15</strong> + <p><strong>WHARTON 400A Series Clocks with a 404.2 Serial Interface</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 16</strong> + <p><strong>RAWDCF receiver (DTR=low/RTS=high) </strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 17</strong> + <p><strong>VARITEXT Receiver (MSF) </strong><br> + <br> + </p> + </li> + <li><a name="mode18"></a><strong>server 127.127.8.0-3 mode 18</strong> + <p><strong><a href="http://www.meinberg.de">Meinberg </a><a href="http://www.meinberg.de/english/products/timesource.htm#gps---freq_sync">GPS16x/GPS17x receivers</a> (GPS / <<1μs)</strong><br> + </p> + <p>This mode works without additional data communication (version, GPS status etc.) and thus should be used with multidrop, heterogeneous multiclient operation.</p> + <p><strong>Note:</strong> mode 18 must not be used with Meinberg PCI cards, use mode 2 instead.<br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 19</strong> + <p><strong>Gude Analog- und Digitalsystem GmbH 'Expert mouseCLOCK USB v2.0'</strong><br> + <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 20</strong> + <p><strong>RAWDCF receiver similar to mode 14, but operating @ 75 baud (DTR=high/RTS=low)</strong><br> + </p> + <p>Driving the DCF clocks at 75 baud may help to get them to work with a bunch of common USB serial converters, that do 75 but cannot do 50 baud at all, e.g. those based on Prolific PL2303. <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 21</strong> + <p><strong>RAWDCF receiver similar to mode 16, but operating @ 75 baud (DTR=low/RTS=high) </strong><br> + </p> + <p>See comment from mode 20 clock. <br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 22</strong> + <p><strong>MEINBERG, mode 2 but with POWERUP trust </strong><br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 23</strong> + <p><strong>MEINBERG, mode 7 but with POWERUP trust </strong><br> + </p> + </li> + <li><strong>server 127.127.8.0-3 mode 24</strong> + <p><strong><a href="http://www.selinc.com/">Schweitzer Engineering Laboratories</a></strong><br> + </p> + </li> + </ul> + <p>Actual data formats and setup requirements of the various clocks can be found in <a href="../parsedata.html">NTP PARSE clock data formats</a>.</p> + <h4>Operation</h4> + <p>The reference clock support software carefully monitors the state transitions of the receiver. All state changes and exceptional events (such as loss of time code transmission) are logged via the syslog facility. Every hour a summary of the accumulated times for the clock states is listed via syslog.</p> + <p>PPS support is only available when the receiver is completely synchronized. The receiver is believed to deliver correct time for an additional period of time after losing synchronization, unless a disruption in time code transmission is detected (possible power loss). The trust period is dependent on the receiver oscillator and thus is a function of clock type.</p> + <p>Raw DCF77 pulses can be fed via a level converter to the RXD pin of an RS-232 serial port (pin 3 of a 25-pin connector or pin 2 of a 9-pin connector). The telegrams are decoded and used for synchronization. DCF77 AM receivers can be bought for as little as $25. The accuracy is dependent on the receiver and is somewhere between 2ms (expensive) and 10ms (cheap). Synchronization ceases when reception of the DCF77 signal deteriorates, since no backup oscillator is available as usually found in other reference clock receivers. So it is important to have a good place for the DCF77 antenna. During transmitter shutdowns you are out of luck unless you have other NTP servers with alternate time sources available.</p> + <p>In addition to the PPS loopfilter control, a true PPS hardware signal can be utilized via the PPSAPI interface. PPS pulses are usually fed via a level converter to the DCD pin of an RS-232 serial port (pin 8 of a 25-pin connector or pin 1 of a 9-pin connector). To select PPS support, the mode parameter is the mode value as above plus 128. If 128 is not added to the mode value, PPS will be detected to be available but will not be used. </p> + <h4>Hardware PPS support<br> + </h4> + <p>For PPS to be used, add 128 to the mode parameter.</p> + <p>If the PPS signal is fed in from a device different from the device providing the serial communication (/dev/refclock-{0..3}), this device is configured as /dev/refclockpps-{0..3}. This allows the PPS information to be fed in e.g. via the parallel port (if supported by the underlying operation system) and the date/time telegrams to be handled via the serial port.</p> + <h4>Monitor Data</h4> + <p>Clock state statistics are written hourly to the syslog service. Online information can be found by examining the clock variables via the ntpq cv command.<br> + Some devices have quite extensive additional information (GPS16x/GPS17x, Trimble). The driver reads out much of the internal GPS data and makes it accessible via clock variables. To find out about additional variable names, query for the clock_var_list variable on a specific clock association as shown below. </p> + <p>First let ntpq display the table of associations:</p> + <pre> ntpq> as ind assID status conf reach auth condition last_event cnt =========================================================== 1 19556 9154 yes yes none falsetick reachable 5 2 19557 9435 yes yes none candidat clock expt 3 3 19558 9714 yes yes none pps.peer reachable 1 </pre> + <p>Then switch to raw output. This may be required because of display limitations in ntpq/ntpd - so large lists need to be retrieved in several queries.</p> + <pre> ntpq> raw Output set to raw </pre> + <p>Use the cv command to read the list of clock variables of a selected association:</p> + <pre> ntpq> cv 19557 clock_var_list </pre> + <p>The long output of the command above looks similar to:</p> + <pre> assID=19557 status=0x0000, clock_var_list="type,timecode,poll,noreply,badformat,baddata,fudgetime1, fudgetime2,stratum,refid,flags,device,clock_var_list,refclock_time,refclock_status, refclock_format,refclock_states,refclock_id,refclock_iomode,refclock_driver_version, meinberg_gps_status,gps_utc_correction,gps_message,meinberg_antenna_status,gps_tot_51, gps_tot_63,gps_t0a,gps_cfg[1],gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3], gps_health[3],gps_cfg[4],gps_health[4],gps_cfg[5]" </pre> + <p>Then use the cv command again to list selected clock variables. The following command must be entered as a single line:</p> + <pre> ntpq> cv 19557 refclock_status,refclock_format,refclock_states,refclock_id, refclock_iomode,refclock_driver_version,meinberg_gps_status,gps_utc_correction, gps_message,meinberg_antenna_status,gps_tot_51,gps_tot_63,gps_t0a,gps_cfg[1], gps_health[1],gps_cfg[2],gps_health[2],gps_cfg[3],gps_health[3],gps_cfg[4], gps_health[4],gps_cfg[5] </pre> + <p>The output of the command above is wrapped around depending on the screen width and looks similar to:</p> + <pre> status=0x0003, refclock_status="UTC DISPLAY; TIME CODE; PPS; POSITION; (LEAP INDICATION; PPS SIGNAL; POSITION)", refclock_format="Meinberg GPS Extended", refclock_states="*NOMINAL: 21:21:36 (99.99%); FAULT: 00:00:03 (0.00%); running time: 21:21:39", refclock_id="GPS", refclock_iomode="normal", refclock_driver_version="refclock_parse.c,v 4.77 2006/08/05 07:44:49 kardel RELEASE_20060805_A", meinberg_gps_status="[0x0000] <OK>", gps_utc_correction="current correction 14 sec, last correction on c7619a00.00000000 Sun, Jan 1 2006 0:00:00.000", gps_message="/PFU3SOP-4WG14EPU0V1KA", meinberg_antenna_status="RECONNECTED on 2006-07-18 08:13:20.0000000 (+0000) UTC CORR, LOCAL TIME, reconnect clockoffset +0.0000000 s, disconnect time 0000-00-00 00:00:00.0000000 (+0000) ", gps_tot_51="week 1400 + 3 days + 42300.0000000 sec", gps_tot_63="week 1400 + 3 days + 42294.0000000 sec", gps_t0a="week 1400 + 5 days + 71808.0000000 sec", gps_cfg[1]="[0x9] BLOCK II", gps_health[1]="[0x0] OK;SIGNAL OK", gps_cfg[2]="[0x0] BLOCK I", gps_health[2]="[0x3f] PARITY;MULTIPLE ERRS", gps_cfg[3]="[0x9] BLOCK II", gps_health[3]="[0x0] OK;SIGNAL OK", gps_cfg[4]="[0x9] BLOCK II", gps_health[6]="[0x0] OK;SIGNAL OK", gps_cfg[5]="[0x9] BLOCK II" </pre> + <h4>Fudge Factors</h4> + <dl> + <dt>time1 <em>time</em> </dt> + <dd>Specifies the time offset calibration factor, in seconds and fraction. The default value depends on the clock type. </dd> + <dt>time2 <em>time</em> </dt> + <dd> If flag1 is 0, time2 specifies the offset of the PPS signal from the actual time (PPS fine tuning). </dd> + <dd> If flag1 is 1, time2 specifies the number of seconds a receiver with a premium local oscillator can be trusted after losing synchronisation. </dd> + <dt>stratum <em>stratum</em> </dt> + <dd>The stratum for this reference clock. </dd> + <dt>refid <em>refid</em> </dt> + <dd>The refid for this reference clock. </dd> + </dl> + <dl> + <dt>flag1 { 0 | 1 } </dt> + <dd>If 0, the fudge factor time2 refers to the PPS offset. </dd> + <dd>If 1, time2 refers to the TRUST TIME. </dd> + <dt>flag2 { 0 | 1 } </dt> + <dd>If flag2 is 1, sample PPS on CLEAR instead of on ASSERT. </dd> + <dt>flag3 { 0 | 1 } </dt> + <dd>If flag3 is 1, link kernel PPS tracking to this refclock instance. </dd> + <dt>flag4 { 0 | 1 } </dt> + <dd>Delete next leap second instead of adding it. (You'll need to wait a bit for that to happen 8-) </dd> + </dl> + Note about auxiliary Sun STREAMS modules (SunOS and Solaris):<br> + <dl> + <dt>The timecode of these receivers can be sampled via a STREAMS module in the kernel. (The STREAMS module has been designed for use with Sun systems under SunOS 4.1.x or Solaris 2.3 - 2.8. It can be linked directly into the kernel or loaded via the loadable driver mechanism.) This STREAMS module can be adapted to convert different time code formats. Nowadays the PPSAPI mechanism is usually used. </dt> + </dl> + <h4>Making your own PARSE clocks</h4> + <p>The parse clock mechanism deviates from the way other NTP reference clocks work. For a short description of how to build parse reference clocks, see <a href="../parsenew.html">making PARSE clocks</a>.</p> + <p>Additional Information</p> + <p><a href="../refclock.html">Reference Clock Drivers</a></p> + <hr> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body> </html> diff --git a/contrib/ntp/html/drivers/driver9.html b/contrib/ntp/html/drivers/driver9.html index 112f2d7..2e52af8 100644 --- a/contrib/ntp/html/drivers/driver9.html +++ b/contrib/ntp/html/drivers/driver9.html @@ -2,57 +2,59 @@ <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>Magnavox MX4200 GPS Receiver</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> + <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>Magnavox MX4200 GPS Receiver</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> - <body> - <h3>Magnavox MX4200 GPS Receiver</h3> - <hr> - <h4>Synopsis</h4> - Address: 127.127.9.<i>u</i><br> - Reference ID: <tt>GPS</tt><br> - Driver ID: <tt>GPS_MX4200</tt><br> - Serial Port: <tt>/dev/gps<i>u</i></tt>; 4800 baud, 8-bits, no parity<br> - Features: <tt>ppsclock</tt> (required) - <h4>Description</h4> - <p>This driver supports the Magnavox MX4200 Navigation Receiver adapted to precision timing applications. It requires the <tt>ppsclock</tt> line discipline or streams module described in the <a href="../ldisc.html">Line Disciplines and Streams Modules</a> page. It also requires a level converter such as described in the <a href="../pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page.</p> - <p>This driver supports all compatible receivers such as the 6-channel MX4200, MX4200D, and the 12-channel MX9212, MX9012R, MX9112.</p> - <p><a href="http://www.leica-gps.com/"><img src="../pic/9400n.jpg" alt="Leica MX9400N Navigator" height="143" width="180" align="left"></a> <a href="http://www.leica-gps.com/">Leica Geosystems</a> acquired the Magnavox commercial GPS technology business in February of 1994. They now market and support former Magnavox GPS products such as the MX4200 and its successors.</p> - <br clear="LEFT"> - <p>Leica MX9400N Navigator.</p> - <h4>Operating Modes</h4> - <p>This driver supports two modes of operation, static and mobile, controlled by clock flag 2.</p> - <p>In static mode (the default) the driver assumes that the GPS antenna is in a fixed location. The receiver is initially placed in a "Static, 3D Nav" mode, where latitude, longitude, elevation and time are calculated for a fixed station. An average position is calculated from this data. After 24 hours, the receiver is placed into a "Known Position" mode, initialized with the calculated position, and then solves only for time.</p> - <p>In mobile mode, the driver assumes the GPS antenna is mounted on a moving platform such as a car, ship, or aircraft. The receiver is placed in "Dynamic, 3D Nav" mode and solves for position, altitude and time while moving. No position averaging is performed.</p> - <h4>Monitor Data</h4> - <p>The driver writes each timecode as received to the <tt>clockstats</tt> file. Documentation for the <cite>NMEA-0183</cite> proprietary sentences produced by the MX4200 can be found in <a href="../mx4200data.html">MX4200 Receiver Data Format</a>.</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>Assume GPS receiver is on a mobile platform if set. - <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> + <body> + <h3>Magnavox MX4200 GPS Receiver</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + Address: 127.127.9.<i>u</i><br> + Reference ID: <tt>GPS</tt><br> + Driver ID: <tt>GPS_MX4200</tt><br> + Serial Port: <tt>/dev/gps<i>u</i></tt>; 4800 baud, 8-bits, no parity<br> + Features: <tt>ppsclock</tt> (required) + <h4>Description</h4> + <p>This driver supports the Magnavox MX4200 Navigation Receiver adapted to precision timing applications. This driver supports all compatible receivers such as the 6-channel MX4200, MX4200D, and the 12-channel MX9212, MX9012R, MX9112.</p> + <p><a href="http://www.leica-gps.com/"><img src="../pic/9400n.jpg" alt="Leica MX9400N Navigator" height="143" width="180" align="left"></a> <a href="http://www.leica-gps.com/">Leica Geosystems</a> acquired the Magnavox commercial GPS technology business in February of 1994. They now market and support former Magnavox GPS products such as the MX4200 and its successors.</p> + <br clear="LEFT"> + <p>Leica MX9400N Navigator.</p> + <h4>Operating Modes</h4> + <p>This driver supports two modes of operation, static and mobile, controlled by clock flag 2.</p> + <p>In static mode (the default) the driver assumes that the GPS antenna is in a fixed location. The receiver is initially placed in a "Static, 3D Nav" mode, where latitude, longitude, elevation and time are calculated for a fixed station. An average position is calculated from this data. After 24 hours, the receiver is placed into a "Known Position" mode, initialized with the calculated position, and then solves only for time.</p> + <p>In mobile mode, the driver assumes the GPS antenna is mounted on a moving platform such as a car, ship, or aircraft. The receiver is placed in "Dynamic, 3D Nav" mode and solves for position, altitude and time while moving. No position averaging is performed.</p> + <h4>Monitor Data</h4> + <p>The driver writes each timecode as received to the <tt>clockstats</tt> file. Documentation for the <cite>NMEA-0183</cite> proprietary sentences produced by the MX4200 can be found in <a href="mx4200data.html">MX4200 Receiver Data Format</a>.</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>Assume GPS receiver is on a mobile platform if set. + <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 +</html> diff --git a/contrib/ntp/html/mx4200data.html b/contrib/ntp/html/drivers/mx4200data.html index 7bf66b1..611da6a 100644 --- a/contrib/ntp/html/mx4200data.html +++ b/contrib/ntp/html/drivers/mx4200data.html @@ -3,11 +3,14 @@ <head> <meta http-equiv="content-type" content="text/html;charset=iso-8859-1"> <title>MX4200 Receiver Data Format</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <link href="../scripts/style.css" type="text/css" rel="stylesheet"> </head> <body> <h1>MX4200 Receiver Data Format</h1> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h2>Table of Contents</h2> <ul> @@ -1068,7 +1071,7 @@ Example:<br> <code>$PMVXG,830,T,1998,10,12,15:30:46,U,S,000298,00003,000000,01*02</code> <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + <script type="text/javascript" language="javascript" src="../scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/oncore-shmem.html b/contrib/ntp/html/drivers/oncore-shmem.html index 8942927..ec1d974 100644 --- a/contrib/ntp/html/drivers/oncore-shmem.html +++ b/contrib/ntp/html/drivers/oncore-shmem.html @@ -10,6 +10,9 @@ <body> <h3>Motorola ONCORE - The Shared Memory Interface</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Introduction</h4> <p>In NMEA mode, the Oncore GPS receiver provides the user with the same information as other GPS receivers. In BINARY mode, it can provide a lot of additional information.</p> @@ -158,4 +161,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/drivers/scripts/footer.txt b/contrib/ntp/html/drivers/scripts/footer.txt index 89216ce..d716cbf 100644 --- a/contrib/ntp/html/drivers/scripts/footer.txt +++ b/contrib/ntp/html/drivers/scripts/footer.txt @@ -1,7 +1,9 @@ document.write("\ <table><tr>\ -<td width='50%' ><img src='../icons/home.gif' align='middle' alt='gif'>\ +<td width='33%' align='center'><img src='../icons/home.gif' align='middle'>\ <a href='../index.html'>Home Page</a></td>\ -<td width='50%' ><img src='../icons/mail2.gif' align='middle' alt='gif'>\ -<a href='http://www.ntp.org/contact.html'>Contacts</a></i></td>\ -</tr></table>")
\ No newline at end of file +<td width='33%' ><img src='../icons/sitemap.png' align='middle'>\ +<a href='../sitemap.html'>Site Map</a></td>\ +<td width='33%' ><img src='../icons/mail2.gif' align='middle'>\ +<a href='http://www.ntp.org/contact'>Contacts</a></td>\ +</tr></table>") diff --git a/contrib/ntp/html/drivers/scripts/style.css b/contrib/ntp/html/drivers/scripts/style.css index 096b18a..7b90fce 100644 --- a/contrib/ntp/html/drivers/scripts/style.css +++ b/contrib/ntp/html/drivers/scripts/style.css @@ -61,4 +61,4 @@ th {background: #FFFFCC; th.caption {background: #EEEEEE; color: #006600; - text-align: center;}
\ No newline at end of file + text-align: center;} diff --git a/contrib/ntp/html/drivers/tf582_4.html b/contrib/ntp/html/drivers/tf582_4.html index 6b0ce0a..177976c 100644 --- a/contrib/ntp/html/drivers/tf582_4.html +++ b/contrib/ntp/html/drivers/tf582_4.html @@ -11,6 +11,9 @@ <body> <h3>European Automated Computer Time Services</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <p>Several European countries use the following message data format:</p> <p><font size="-1" face="Courier New">Data format<br> @@ -68,4 +71,4 @@ <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/extern.html b/contrib/ntp/html/extern.html index 3245fca..764631d 100644 --- a/contrib/ntp/html/extern.html +++ b/contrib/ntp/html/extern.html @@ -1,33 +1,48 @@ <!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 ntp 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 constand 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_contro</tt>l 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 -->9-May-2014 04:46<!-- #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> diff --git a/contrib/ntp/html/filter.html b/contrib/ntp/html/filter.html new file mode 100644 index 0000000..5f9ed0a --- /dev/null +++ b/contrib/ntp/html/filter.html @@ -0,0 +1,34 @@ +<!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 Filter Algorithm</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>Clock Filter Algorithm</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:05<!-- #EndDate --> + UTC</p> +<hr> +<p>The clock filter algorithm processes the offset and delay samples produced by the on-wire protocol for each peer process separately. It uses a sliding window of eight samples and picks out the sample with the least expected error. This page describes the algorithm design principles along with an example of typical performance.</p> +<div align="center"><img src="pic/flt5.gif" alt="gif"> + <p>Figure 1. Wedge Scattergram</p> +</div> +<p>Figure 1 shows a typical <em>wedge scattergram</em> plotting sample points of offset versus delay collected over a 24-hr period. As the delay increases, the offset variation increases, so the best samples are those at the lowest delay. There are two limb lines at slope ±0.5, representing the limits of sample variation. However, it is apparent that, if a way could be found to find the sample of lowest delay, it would have the least offset variation and would be the best candidate to synchronize the system clock.</p> +<p>The clock filter algorithm works best when the delays are statistically identical in the reciprocal directions between the server and client. This is apparent in Figure 1, where the scattergram is symmetric about the x axis through the apex sample. In configurations where the delays are not reciprocal, or where the transmission delays on the two directions are traffic dependent, this may not be the case. A common case with DSL links is when downloading or uploading a large file. During the download or upload process, the delays may be significantly different resulting in large errrors. However, these errors can be largely eliminated using samples near the limb lines, as described on the <a href="huffpuff.html">Huff-n'-Puff Filter</a> page.</p> +<p>In the clock filter algorithm the offset and delay samples from the on-wire protocol are inserted as the youngest stage of an eight-stage shift register, thus discarding the oldest stage. Each time an NTP packet is received from a source, a dispersion sample is initialized as the sum of the precisions of the server and client. Precision is defined by the latency to read the system clock and varies from 1000 ns to 100 ns in modern machines. The dispersion sample is inserted in the shift register along with the associated offset and delay samples. Subsequently, the dispersion sample in each stage is increased at a fixed rate of 15 μs/s, representing the worst case error due to skew between the server and client clock frequencies.</p> +<p>In each peer process the clock filter algorithm selects the stage with the smallest delay, which generally represents the most accurate data, and it and the associated offset sample become the peer variables of the same name. The peer jitter statistic is computed as the root mean square (RMS) differences between the offset samples and the offset of the selected stage.</p> +<p> The peer dispersion statistic is determined as a weighted sum of the dispersion samples in the shift register. Initially, the dispersion of all shift register stages is set to a large number "infinity" equal to 16 s. The weight factor for each stage, starting from the youngest numbered <em>i</em> = 1, is 2<sup>-<em>i</em></sup>, which means the peer dispersion is approximately 16 s.</p> +<p> As samples enter the register, the peer dispersion drops from 16 s to 8 s, 4 s, 2 s, and so forth. In practice, the synchronization distance, which is equal to one-half the delay plus the dispersion, falls below the select threshold of 1.5 s in about four updates. This gives some time for meaningful comparison between sources, if more than one are available. The dispersion continues to grow at the same rate as the sample dispersion. For additional information on statistacl principles and performance metrics, see the <a href="stats.html">Performance Metrics</a> page.</p> +<p> As explained elsewhere, when a source becomes unreachable, the poll process inserts a dummy infinity sample in the shift register for each poll sent. After eight polls, the register returns to its original state.</p> +<div align="center"><img src="pic/flt1.gif" alt="gif"> <img src="pic/flt2.gif" alt="gif"> + <p>Figure 2. Raw (left) and Filtered (right) Offsets</p> +</div> +<p>Figure 2 shows the performance of the algorithm for a typical Internet path over a 24-hr period. The graph on the left shows the raw offsets produced by the on-wired protocol, while the figure on the right shows the filtered offsets produced by the clock filter algorithm. If we consider the series formed as the absolute value of the offset samples, the mean error is defined as the mean of this series. Thus, the mean error of the raw samples is 0.724 ms, while the mean error of the filtered series is 0.192 ms. Radio engineers would interpret this as a processing gain of 11.5 dB.</p> +<p>The reader might notice the somewhat boxy characteristic of the filtered offsets. Once a sample is selected, it remains selected until a newer sample with lower delay is available. This commonly occurs when an older selected sample is discarded from the shift register. The reason for this is to preserve causality; that is, time always moves forward, never backward. The result can be the loss of up to seven samples in the shift register, or more to the point, the output sample rate can never be less than one in eight input samples. The clock discipline algorithm is specifically designed to operate at this rate.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/gadget.html b/contrib/ntp/html/gadget.html deleted file mode 100644 index b13fe08..0000000 --- a/contrib/ntp/html/gadget.html +++ /dev/null @@ -1,33 +0,0 @@ -<!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 - <h4>Related Links</h4> - <p> - <script type="text/javascript" language="javascript" src="scripts/links11.txt"></script> - <br clear="left"> - </p> - <h4>table of Contents</h4> - <ul> - <li class="inline"><a href="#intro">Introduction</a> - <li class="inline"><a href="#ckt">Circuit Description</a> - <li class="inline"><a href="#file">Files</a> - </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 obrtained 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 diff --git a/contrib/ntp/html/groups.html b/contrib/ntp/html/groups.html deleted file mode 100644 index 7f6d14b..0000000 --- a/contrib/ntp/html/groups.html +++ /dev/null @@ -1,47 +0,0 @@ -<!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>Trusted Hosts and Groups</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Trusted Hosts and Groups</h3> - <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>Alice holds the key.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">00:12</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="299">Tuesday, November 08, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links9.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#idexp">Identity Schemes</a> - <li class="inline"><a href="#exam">Example</a> - <li class="inline"><a href="#cmd">Command Line Options</a> - <li class="inline"><a href="#rand">Random Seed File</a> - <li class="inline"><a href="#fmt">Cryptographic Data Files</a> - <li class="inline"><a href="#bug">Bugs</a> - </ul> - <hr> - <h4 id="synop">Trusted Hosts and Groups</h4> - <p>Each cryptographic configuration involves selection of a signature scheme and identification scheme, called a cryptotype, as explained in the <a href="authopt.html">Authentication Options</a> page. The default cryptotype uses RSA encryption, MD5 message digest and TC identification. First, configure a NTP subnet including one or more low-stratum trusted hosts from which all other hosts derive synchronization directly or indirectly. Trusted hosts have trusted certificates; all other hosts have nontrusted certificates. These hosts will automatically and dynamically build authoritative certificate trails to one or more trusted hosts. A trusted group is the set of all hosts that have, directly or indirectly, a certificate trail ending at a trusted host. The trail is defined by static configuration file entries or dynamic means described on the <a href="manyopt.html">Automatic NTP Configuration Options</a> page.</p> - <p>On each trusted host as root, change to the keys directory. To insure a fresh fileset, remove all <tt>ntpkey</tt> files. Then run <tt>ntp-keygen -T</tt> to generate keys and a trusted certificate. On all other hosts do the same, but leave off the <tt>-T</tt> flag to generate keys and nontrusted certificates. When complete, start the NTP daemons beginning at the lowest stratum and working up the tree. It may take some time for Autokey to instantiate the certificate trails throughout the subnet, but setting up the environment is completely automatic.</p> - <p>If it is necessary to use a different sign key or different digest/signature scheme than the default, run <tt>ntp-keygen</tt> with the <tt>-S</tt><i><tt> type</tt></i> option, where <i><tt>type</tt></i> is either <tt>RSA</tt> or <tt>DSA</tt>. The most often need to do this is when a DSA-signed certificate is used. If it is necessary to use a different certificate scheme than the default, run <tt>ntp-keygen</tt> with the <tt>-c <i>scheme</i></tt> option and selected <i><tt>scheme</tt></i> as needed. If <tt>ntp-keygen</tt> is run again without these options, it generates a new certificate using the same scheme and sign key.</p> - <p>After setting up the environment it is advisable to update certificates from time to time, if only to extend the validity interval. Simply run <tt>ntp-keygen</tt> with the same flags as before to generate new certificates using existing keys. However, if the host or sign key is changed, <tt>ntpd</tt> should be restarted. When ntpd is restarted, it loads any new files and restarts the protocol. Other dependent hosts will continue as usual until signatures are refreshed, at which time the protocol is restarted.</p> - <h4 id="idexp">Identity Schemes</h4> - <p>As mentioned on the Autonomous Authentication page, the default TC identity scheme is vulnerable to a middleman attack. However, there are more secure identity schemes available, including PC, IFF, GQ and MV described on the <a href="http://www.eecis.udel.edu/%7emills/keygen.html">Identification Schemes</a> page. These schemes are based on a TA, one or more trusted hosts and some number of nontrusted hosts. Trusted hosts prove identity using values provided by the TA, while the remaining hosts prove identity using values provided by a trusted host and certificate trails that end on that host. The name of a trusted host is also the name of its sugroup and also the subject and issuer name on its trusted certificate. The TA is not necessarily a trusted host in this sense, but often is.</p> - <p>In some schemes there are separate keys for servers and clients. A server can also be a client of another server, but a client can never be a server for another client. In general, trusted hosts and nontrusted hosts that operate as both server and client have parameter files that contain both server and client keys. Hosts that operate only as clients have key files that contain only client keys.</p> - <p>The PC scheme supports only one trusted host in the group. On trusted host <i>alice</i> run <tt>ntp-keygen -P -p <i>password</i></tt> to generate the host key file <tt>ntpkey_RSAkey_<i>alice.filestamp</i></tt> and trusted private certificate file <tt>ntpkey_RSA-MD5_cert_<i>alice.filestamp</i></tt>. Copy both files to all group hosts; they replace the files which would be generated in other schemes. On each host <i>bob</i> install a soft link from the generic name <tt>ntpkey_host_<i>bob</i></tt> to the host key file and soft link <tt>ntpkey_cert_<i>bob</i></tt> to the private certificate file. Note the generic links are on <i>bob</i>, but point to files generated by trusted host <i>alice</i>. In this scheme it is not possible to refresh either the keys or certificates without copying them to all other hosts in the group.</p> - <p>For the IFF scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host <i>alice</i> run <tt>ntp-keygen -T </tt><tt>-I -p <i>password</i></tt> to produce her parameter file <tt>ntpkey_IFFpar_<i>alice.filestamp</i></tt>, which includes both server and client keys. Copy this file to all group hosts that operate as both servers and clients and install a soft link from the generic <tt>ntpkey_iff_<i>alice</i></tt> to this file. If there are no hosts restricted to operate only as clients, there is nothing further to do. As the IFF scheme is independent of keys and certificates, these files can be refreshed as needed.</p> - <p>If a rogue client has the parameter file, it could masquerade as a legitimate server and present a middleman threat. To eliminate this threat, the client keys can be extracted from the parameter file and distributed to all restricted clients. After generating the parameter file, on <i>alice</i> run <tt>ntp-keygen</tt> <tt>-e</tt> and pipe the output to a file or mail program. Copy or mail this file to all restricted clients. On these clients install a soft link from the generic <tt>ntpkey_iff_<i>alice</i></tt> to this file. To further protect the integrity of the keys, each file can be encrypted with a secret password.</p> - <p>For the GQ scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host <i>alice</i> run <tt>ntp-keygen -T </tt><tt>-G -p <i>password</i></tt> to produce her parameter file <tt>ntpkey_GQpar_<i>alice.filestamp</i></tt>, which includes both server and client keys. Copy this file to all group hosts and install a soft link from the generic <tt>ntpkey_gq_<i>alice</i></tt> to this file. In addition, on each host <i>bob</i> install a soft link from generic <tt>ntpkey_gq_<i>bob</i></tt> to this file. As the GQ scheme updates the GQ parameters file and certificate at the same time, keys and certificates can be regenerated as needed.</p> - <p>For the MV scheme, proceed as in the TC scheme to generate keys and certificates for all group hosts. For illustration assume <i>trish</i> is the TA, <i>alice</i> one of several trusted hosts and <i>bob</i> one of her clients. On TA <i>trish</i> run <tt>ntp-keygen </tt><tt>-V <i>n</i> -p <i>password</i></tt>, where <i>n</i> is the number of revokable keys (typically 5) to produce the parameter file <tt>ntpkeys_MVpar_<i>trish.filestamp </i></tt>and client key files <tt>ntpkeys_MVkey<i>d</i>_<i>trish.filestamp</i></tt> where <i><tt>d</tt></i> is the key number (0 < <i><tt>d</tt></i> < <i>n</i>). Copy the parameter file to <i>alice</i> and install a soft link from the generic <tt>ntpkey_mv_<i>alice</i></tt> to this file. Copy one of the client key files to <i>alice</i> for later distribution to her clients. It doesn't matter which client key file goes to <i>alice</i>, since they all work the same way. <i>Alice</i> copies the client key file to all of her cliens. On client <i>bob</i> install a soft link from generic <tt>ntpkey_mvkey_<i>bob </i></tt>to the client key file. As the MV scheme is independent of keys and certificates, these files can be refreshed as needed.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/hints.html b/contrib/ntp/html/hints.html new file mode 100644 index 0000000..7749ba9 --- /dev/null +++ b/contrib/ntp/html/hints.html @@ -0,0 +1,22 @@ +<!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: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:06<!-- #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> diff --git a/contrib/ntp/html/build/hints/a-ux b/contrib/ntp/html/hints/a-ux index f8c26d2..f8c26d2 100644 --- a/contrib/ntp/html/build/hints/a-ux +++ b/contrib/ntp/html/hints/a-ux diff --git a/contrib/ntp/html/build/hints/aix b/contrib/ntp/html/hints/aix index e53beff..e53beff 100644 --- a/contrib/ntp/html/build/hints/aix +++ b/contrib/ntp/html/hints/aix diff --git a/contrib/ntp/html/build/hints/bsdi b/contrib/ntp/html/hints/bsdi index 3b8bc38..3b8bc38 100644 --- a/contrib/ntp/html/build/hints/bsdi +++ b/contrib/ntp/html/hints/bsdi diff --git a/contrib/ntp/html/build/hints/changes b/contrib/ntp/html/hints/changes index 177e562..177e562 100644 --- a/contrib/ntp/html/build/hints/changes +++ b/contrib/ntp/html/hints/changes diff --git a/contrib/ntp/html/build/hints/decosf1 b/contrib/ntp/html/hints/decosf1 index bc4ce0b..bc4ce0b 100644 --- a/contrib/ntp/html/build/hints/decosf1 +++ b/contrib/ntp/html/hints/decosf1 diff --git a/contrib/ntp/html/build/hints/decosf2 b/contrib/ntp/html/hints/decosf2 index e4a8828..e4a8828 100644 --- a/contrib/ntp/html/build/hints/decosf2 +++ b/contrib/ntp/html/hints/decosf2 diff --git a/contrib/ntp/html/build/hints/freebsd b/contrib/ntp/html/hints/freebsd index ef84732..ef84732 100644 --- a/contrib/ntp/html/build/hints/freebsd +++ b/contrib/ntp/html/hints/freebsd diff --git a/contrib/ntp/html/build/hints/hpux b/contrib/ntp/html/hints/hpux index 1640d05..1640d05 100644 --- a/contrib/ntp/html/build/hints/hpux +++ b/contrib/ntp/html/hints/hpux diff --git a/contrib/ntp/html/build/hints/linux b/contrib/ntp/html/hints/linux index b06a36a..b06a36a 100644 --- a/contrib/ntp/html/build/hints/linux +++ b/contrib/ntp/html/hints/linux diff --git a/contrib/ntp/html/build/hints/mpeix b/contrib/ntp/html/hints/mpeix index 83c7241e..83c7241e 100644 --- a/contrib/ntp/html/build/hints/mpeix +++ b/contrib/ntp/html/hints/mpeix diff --git a/contrib/ntp/html/build/hints/notes-xntp-v3 b/contrib/ntp/html/hints/notes-xntp-v3 index ba027f2..ba027f2 100644 --- a/contrib/ntp/html/build/hints/notes-xntp-v3 +++ b/contrib/ntp/html/hints/notes-xntp-v3 diff --git a/contrib/ntp/html/build/hints/parse b/contrib/ntp/html/hints/parse index 07fbc6b..d252351 100644 --- a/contrib/ntp/html/build/hints/parse +++ b/contrib/ntp/html/hints/parse @@ -24,7 +24,7 @@ Directory contents: - Trimble SV6 GPS receiver If you want to add new clock types please check - with kardel <AT> informatik.uni-erlangen.de. These files + with kardel@informatik.uni-erlangen.de. These files implement the conversion of RS232 data streams into timing information used by refclock_parse.c which is mostly generic except for NTP configuration constants. diff --git a/contrib/ntp/html/build/hints/refclocks b/contrib/ntp/html/hints/refclocks index 17e7643..17e7643 100644 --- a/contrib/ntp/html/build/hints/refclocks +++ b/contrib/ntp/html/hints/refclocks diff --git a/contrib/ntp/html/build/hints/rs6000 b/contrib/ntp/html/hints/rs6000 index 8561ac2..8561ac2 100644 --- a/contrib/ntp/html/build/hints/rs6000 +++ b/contrib/ntp/html/hints/rs6000 diff --git a/contrib/ntp/html/build/hints/sco.html b/contrib/ntp/html/hints/sco.html index bd08e98..d5d1933 100644 --- a/contrib/ntp/html/build/hints/sco.html +++ b/contrib/ntp/html/hints/sco.html @@ -1,24 +1,29 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<!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>SCO Unix hints</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> + <link href="../scripts/style.css" type="text/css" rel="stylesheet"> </head> <body> - <h1>SCO Unix hints</h1> - <h2>Older SCO Unix versions</h2> + <h3>SCO Unix hints</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> + <h4>Older SCO Unix versions</h4> <p>NTP 4.0.x does not run on SCO Unix prior to version 3.2.5.0.0. If you need NTP on an older SCO Unix system and don't mind to modify your kernel, use 3.5.91 which has patches for SCO Unix 3.2.4.x. Apply the kernel modifications as described in <a href="http://www.echelon.nl/en/ntp/sco3-recipe.html">XNTP on SCO 3.2.4.2</a>.</p> - <h2>Compiling NTP</h2> + <h4>Compiling NTP</h4> <p>Delete the old SCO supplied NTP programs using the "custom" utility. Run the NTP configure program with CFLAGS="-b elf -K <i>processor-type</i>" for best results.</p> - <h2>Running NTP</h2> + <h4>Running NTP</h4> <p>Run "tickadj -As" after every reboot to set the variables "clock_drift" and "track_rtc" to the right values.</p> <p>Run "ntpd" with a high negative nice-value, i.e. "nice --19 ntpd" for best results.</p> - <h2>More information</h2> + <h4>More information</h4> <p>More information on the way SCO Unix and NTP interact can be found in <a href="http://www.echelon.nl/en/ntp/ntp-on-sco.html">NTP on SCO Unix</a>, which includes links to precompiled versions of NTP.</p> - <p><a href="mailto:kees@echelon.nl">Kees Hendrikse</a>, January 1999</p> + <p>Kees Hendrikse, January 1999</p> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/build/hints/sgi b/contrib/ntp/html/hints/sgi index 5e4f7de..5e4f7de 100644 --- a/contrib/ntp/html/build/hints/sgi +++ b/contrib/ntp/html/hints/sgi diff --git a/contrib/ntp/html/build/hints/solaris-dosynctodr.html b/contrib/ntp/html/hints/solaris-dosynctodr.html index fc7fae9..89a12b2 100644 --- a/contrib/ntp/html/build/hints/solaris-dosynctodr.html +++ b/contrib/ntp/html/hints/solaris-dosynctodr.html @@ -25,7 +25,7 @@ <BODY BGCOLOR="#FFFFFF" LINK="#666699" ALINK="#FFFFFF"> -<TABLE WIDTH="623" BORDER="0"> +<TABLE WIDTH="623" BORDER="0" CELLSPACING="0" CELLPADDING="0"> <TR> <TD COLSPAN="2" VALIGN="TOP" WIDTH="623"> <IMG BORDER="0" SRC="/images/homebuy.gif" WIDTH="149" HEIGHT="32" ALT="Home * Buy * My Sun(sm)" USEMAP="#lefttop"><IMG BORDER="0" SRC="/images/globalnavbar.gif" WIDTH="474" HEIGHT="32" ALT="sun.com Global Sections" USEMAP="#topnav"></TD> @@ -35,12 +35,12 @@ <!-- TITLEBAR IMAGE: INSERT CUSTOMIZED TITLEBAR IMAGE BELOW --> - <A HREF="http://www.sun.com/"><IMG BORDER="0" SRC="/images/sunlogo.gif" WIDTH="149" HEIGHT="72" ALT="Sun Microsystems"></A><IMG BORDER="0" SRC="/images/titlebar/doc.title.gif" alt="gif" WIDTH="474" HEIGHT="72"></TD> + <A HREF="http://www.sun.com/"><IMG BORDER="0" SRC="/images/sunlogo.gif" WIDTH="149" HEIGHT="72" ALT="Sun Microsystems"></A><IMG BORDER="0" SRC="/images/titlebar/doc.title.gif" WIDTH="474" HEIGHT="72"></TD> </TR> <!-- Begin Search Elements --> <TR VALIGN="top"> <TD BGCOLOR="#666699"> - <TABLE> + <TABLE BORDER="0" WIDTH="157" CELLSPACING="0" CELLPADDING="0"> <TR> <TD BGCOLOR="#666699" COLSPAN="2" WIDTH="157" VALIGN="TOP"><IMG BORDER="0" SRC="/images/search/contract/search1.gif" WIDTH="157" HEIGHT="16" ALT="Search SunSolve"></TD> </TR> @@ -58,7 +58,7 @@ <!-- End Search Elements --> <!-- Begin User Personalization (Must limit to 10 Characters)--> <TR> - <TD COLSPAN="2"><TABLE><TR><TD COLSPAN="3" ALIGN="right"><IMG SRC="/images/home_con/welcom_1.gif" ALT="" WIDTH="156" HEIGHT="4" BORDER="0"></TD></TR> + <TD COLSPAN="2"><TABLE BORDER="0" CELLSPACING="0" CELLPADDING="0" WIDTH="157"><TR><TD COLSPAN="3" ALIGN="right"><IMG SRC="/images/home_con/welcom_1.gif" ALT="" WIDTH="156" HEIGHT="4" BORDER="0"></TD></TR> <TR><TD BGCOLOR="#333366"><IMG SRC="/images/home_con/welcom_2.gif" ALT="" WIDTH="17" HEIGHT="19" BORDER="0"></TD><TD BGCOLOR="#333366" VALIGN="middle"><NOBR><FONT FACE="Geneva, Helvetica, Arial, SunSans-Regular" COLOR="#99CC33" SIZE="-2">sopko</FONT></NOBR></TD><TD BGCOLOR="#333366" ALIGN="right"><A HREF="edit-user-form.pl?viewmode=contractuser"><IMG SRC="/images/home_con/welcom_3.gif" ALT="Edit" WIDTH="45" HEIGHT="19" BORDER="0"></A></TD></TR> </TABLE> </TD> @@ -86,9 +86,9 @@ <IMG BORDER="0" SRC="/images/nav/p3.gif" WIDTH="157" HEIGHT="19" ALT="Y2K Central"></A><BR> <A HREF="show.pl?target=security/sec" onmouseover="window.status='Security Information'; return true" onmouseout="window.status=''; return true"> <IMG BORDER="0" SRC="/images/nav/p2.gif" WIDTH="157" HEIGHT="19" ALT="Security Information"></A><BR> -<br><table width="157"> +<br><table cellpadding="0" cellspacing="0" border="0" width="157"> <tr><td width="8"> </td><td width="149"> -<table> +<table cellpadding="0" cellspacing="0" border="0"> <BR><tr><td><BR><img src="/images/line.gif" alt="------" width="140" height="11" border="0"><br> <A HREF="mark.pl" onmouseover="window.status='Marked Docs.';return true" @@ -149,7 +149,7 @@ -<table width=100%> +<table width=100% cellpadding=16 cellspacing=0 border=0> <tr> <td width=100% valign=top> <CENTER><FONT FACE="Geneva, Helvetica, Arial, SunSans-Regular" SIZE="2"> @@ -177,7 +177,7 @@ <option value="#SRDB-ID">SRDB ID</option> <option value="#OS">OS</option> </select></div></form> -<table width=100%> +<table width=100% cellpadding=2 cellspacing=0 border=0> <tr bgcolor=#666699><td><font size=2 color=#ffffff><b>SRDB ID</b></font></td> <td bgcolor=#ffffff><font size=2> </font></td> <td><font size=2 color=#ffffff><b>Synopsis</b></font></td> @@ -191,7 +191,7 @@ <td><font size=2><b>4 Sep 1999</b></font></td> </tr> </table><br clear> -<table width=100%><tr bgcolor=#999999> +<table width=100% cellpadding=2 cellspacing=0 border=0><tr bgcolor=#999999> <td><font size=2 color=#ffffff><b><a name=Problem-Description>Problem Description</a></b></font></td> <td align=right><b><a href="#top"><font size=2 color=#ffffff>Top</font></a></b></td></tr></table> <pre>Ever since upgrading to Solaris 2.6, the system clock has been drifting and @@ -200,7 +200,7 @@ didn''t complete' and 'time reset (step)' a lot in the /var/adm/messages file. The system either was previously working fine with the freeware xntpd or the configuration was copied from another system that was using the freeware version. --- 23-Apr-99 08:22 US/Eastern --</pre><table width=100%><tr bgcolor=#999999> +-- 23-Apr-99 08:22 US/Eastern --</pre><table width=100% cellpadding=2 cellspacing=0 border=0><tr bgcolor=#999999> <td><font size=2 color=#ffffff><b><a name=Problem-Solution>Problem Solution</a></b></font></td> <td align=right><b><a href="#top"><font size=2 color=#ffffff>Top</font></a></b></td></tr></table> <pre>The common lore for setting up xntpd on Solaris using @@ -221,7 +221,7 @@ clock, the hard clock is also controlled. Setting defaulkt behavior, having exactly the opposite effect as that intended. -Do not set <font color=red>dosynctodr</font> to 0.</pre><table width=100%> +Do not set <font color=red>dosynctodr</font> to 0.</pre><table width=100% cellpadding=2 cellspacing=0 border=0> <tr><td bgcolor=#999999 valign=top width=25%><font color=#ffffff size=2><b><a name=Product-Area>Product Area</a></b></font></td> <td bgcolor=#cccccc valign=top width=75%><font size=2>Bundled Network</font></td></tr> <tr><td bgcolor=#999999 valign=top width=25%><font color=#ffffff size=2><b><a name=Product>Product</a></b></font></td> diff --git a/contrib/ntp/html/hints/solaris.html b/contrib/ntp/html/hints/solaris.html new file mode 100644 index 0000000..4b83862 --- /dev/null +++ b/contrib/ntp/html/hints/solaris.html @@ -0,0 +1,236 @@ +<HTML> +<HEAD> +<TITLE>Solaris hints and kinks</title><link href="scripts/style.css" type="text/css" rel="stylesheet"> + +</HEAD> +<BODY> +Information on compiling and executing ntpd under Solaris. +<BR> +<p>Last update: + <!-- #BeginDate format:En2m -->27-Jan-2014 05:31<!-- #EndDate --> + UTC, +John Hawkinson, +<! -- This is deliberately not a mailto -- > <jhawk@MIT.EDU> +</p> +<P> +If you're not running Solaris 2.5.1 or later, it is likely +that you will have problems; upgrading would be a really good plan. +<P> +<H3>All Solaris versions</H3> +<P> + We have a report that says starting with Solaris 2.6 we should leave + <I>dosynctodr</I> alone. + <A HREF="solaris-dosynctodr.html">Here is the report</A>. +<P> +Proper operation of ntp under Solaris may require setting the kernel +variable <I>dosynctodr</I> to zero (meaning "do not synchronize the clock +to the hardware time-of-day clock"). This can be done with the +tickadj utility: +<BLOCKQUOTE><TT> +tickadj -s +</TT></BLOCKQUOTE> +If you prefer, it can also be done with the native Solaris kernel debugger: +<BLOCKQUOTE><TT> +echo dosynctodr/W0 | adb -k -w /dev/ksyms /dev/mem +</BLOCKQUOTE></TT> +<P> +Or, it can also be set by adding a line to /etc/system: +<BLOCKQUOTE><TT> +set dosynctodr = 0 +</BLOCKQUOTE></TT> +<P> +Instead of the <I>tick</I> kernel variable, which many operating +systems use to control microseconds added to the system time every +clock tick (c.f. <A HREF="#frequency_tolerance">Dealing +with Frequency Tolerance Violations</A>), Solaris has the variables +<I>nsec_per_tick</I> and <I>usec_per_tick</I>. +<P> +<I>nsec_per_tick</I> and <I>usec_per_tick</I> control the number of +nanoseconds and microseconds, respectively, added to the system clock +each clock interrupt. Enterprising souls may set these based on +information collected by ntpd in the <CODE>/etc/ntp.drift</CODE> file +to correct for individual hardware variations. +<P> +On UltraSPARC systems, <I>nsec_per_tick</I> and <I>usec_per_tick</I> +are ignored in favor of the <I>cpu_tick_freq</I> variable, which +should be automatically be determined by the PROM in an accurate +fashion. +<P> +In general, the same ntp binaries should not be used across multiple +operating system releases. There is enough variation in the core operating +system support for timekeeping that a rebuild of ntpd for the idiosyncracies +of your specific operating system version is advisable. +<P> +It is recommended that ntp be started via a script like <A +HREF="solaris.xtra.S99ntpd">this one</A>, installed in +<CODE>/etc/init.d/ntpd</CODE> with a symbol link from +<CODE>/etc/rc2.d/S99ntpd</CODE>. + +<a id="frequency_tolerance" /> +<h4>Dealing with Frequency Tolerance Violations (<tt>tickadj</tt> and +Friends)</h4> + The NTP Version 3 specification RFC-1305 calls for a maximum + oscillator frequency tolerance of +-100 parts-per-million (PPM), which is +representative of those components suitable for use in relatively +inexpensive workstation platforms. For those platforms meeting this +tolerance, NTP will automatically compensate for the frequency errors of the +individual oscillator and no further adjustments are required, either to the +configuration file or to various kernel variables. For the NTP Version 4 +release, this tolerance has been increased to +-500 PPM. <p>However, in the +case of certain notorious platforms, in particular Sun 4.1.1 systems, the +performance can be improved by adjusting the values of certain kernel +variables; in particular, <tt>tick</tt> and <tt>tickadj</tt>. The variable +<tt>tick</tt> is the increment in microseconds added to the system time on +each interval- timer interrupt, while the variable <tt>tickadj</tt> is used +by the time adjustment code as a slew rate, in microseconds per tick. When +the time is being adjusted via a call to the system routine +<tt>adjtime()</tt>, the kernel increases or reduces tick by <tt>tickadj</tt> +microseconds per tick until the specified adjustment has been +completed. Unfortunately, in most Unix implementations the tick increment +must be either zero or plus/minus exactly <tt>tickadj</tt> microseconds, +meaning that adjustments are truncated to be an integral multiple of +<tt>tickadj</tt> (this latter behaviour is a misfeature, and is the only +reason the <tt>tickadj</tt> code needs to concern itself with the internal +implementation of <tt>tickadj</tt> at all). In addition, the stock Unix +implementation considers it an error to request another adjustment before a +prior one has completed.</p> <p>Thus, to make very sure it avoids problems +related to the roundoff, the <tt>tickadj</tt> program can be used to adjust +the values of <tt>tick</tt> and <tt>tickadj</tt>. This ensures that all +adjustments given to <tt>adjtime()</tt> are an even multiple of +<tt>tickadj</tt> microseconds and computes the largest adjustment that can +be completed in the adjustment interval (using both the value of +<tt>tick</tt> and the value of <tt>tickadj</tt>) so it can avoid exceeding +this limit. It is important to note that not all systems will allow +inspection or modification of kernel variables other than at system build +time. It is also important to know that, with the current NTP tolerances, it +is rarely necessary to make these changes, but in many cases they will +substantially improve the general accuracy of the time service.</p> +<p>Unfortunately, the value of <tt>tickadj</tt> set by default is almost +always too large for <tt>ntpd</tt>. NTP operates by continuously making +small adjustments to the clock, usually at one-second intervals. If +<tt>tickaj</tt> is set too large, the adjustments will disappear in the +roundoff; while, if <tt>tickadj</tt> is too small, NTP will have difficulty +if it needs to make an occasional large adjustment. While the daemon itself +will read the kernel's values of these variables, it will not change the +values, even if they are unsuitable. You must do this yourself before the +daemon is started using the <tt>tickadj</tt> program included in the +<tt>./util</tt> directory of the distribution. Note that the latter program +will also compute an optimal value of <tt>tickadj</tt> for NTP use based on +the kernel's value of <tt>tick</tt>.</p> <p>The <tt>tickadj</tt> program can +reset several other kernel variables if asked. It can change the value of +<tt>tick</tt> if asked. This is handy to compensate for kernel bugs which +cause the clock to run with a very large frequency error, as with SunOS +4.1.1 systems. It can also be used to set the value of the kernel +<tt>dosynctodr</tt> variable to zero. This variable controls whether to +synchronize the system clock to the time-of-day clock, something you really +don't want to be happen when <tt>ntpd</tt> is trying to keep it under +control. In some systems, such as recent Sun Solaris kernels, the +<tt>dosynctodr</tt > variable is the only one that can be changed by the +<tt>tickadj</tt> program. In this and other modern kernels, it is not +necessary to change the other variables in any case.</p> + +<p>We have a report that says starting with Solaris 2.6 we should leave +<i>dosynctodr</i> alone.</p> <p>In order to maintain reasonable correctness +bounds, as well as reasonably good accuracy with acceptable polling +intervals, <tt>ntpd</tt> will complain if the frequency error is greater +than 500 PPM. For machines with a value of <tt>tick</tt> in the 10-ms range, +a change of one in the value of <tt>tick</tt> will change the frequency by +about 100 PPM. In order to determine the value of <tt>tick</tt> for a +particular CPU, disconnect the machine from all source s of time +(<tt>dosynctodr</tt> = 0) and record its actual time compared to an outside +source (eyeball-and-wristwatch will do) over a day or more. Multiply the +time change over the day by 0.116 and add or subtract the result to tick, +depending on whether the CPU is fast or slow. An example call to +<tt>tickadj</tt> useful on SunOS 4.1.1 is:</p> + <pre> + <tt>tickadj</tt> -t 9999 -a 5 -s +</pre> +which sets tick 100 PPM fast, <tt>tickadj</tt> to 5 microseconds and turns +off the clock/calendar chip fiddle. This line can be added to the <tt +>rc.local</tt> configuration file to automatically set the kernel variables +at boot time. <p>All this stuff about diddling kernel variables so the NTP +daemon will work is really silly. If vendors would ship machines with clocks +that kept reasonable time and would make their <tt>adjtime()</tt> system +call apply the slew it is given exactly, independent of the value of +<tt>tickadj</tt>, all this could go away. This is in fact the case on many +current Unix systems.</p> + +<H3>Solaris 2.6</H3> +<P> +Solaris 2.6 adds support for kernel PLL timekeeping, but breaks this +support in such a fashion that using it worse than not. This is <A +HREF="solaris.xtra.4095849"> SUN Bug ID 4095849</A>, and it is not yet +fixed as of June 1998. +<P> +<H3>Solaris 2.5 and 2.5.1</H3> +<P> +On UltraSPARC systems, calculation of <I>cpu_tick_freq</I> is broken +such that values that are off by significant amounts may be used +instead. This unfortunately means that ntpd may have severe problems +keeping synchronization. This is <A HREF="solaris.xtra.4023118"> SUN Bug ID +4023118</A>. Bryan Cantrill <! -- <bmc@eng.sun.com> --> of Sun +posted <A HREF="solaris.xtra.patchfreq">patchfreq</A>, a workaround script, +to comp.protocols.time.ntp in March of 1997. +<P> +<HR> +<H2>OLD DATA</H2> +<STRONG>I can't vouch for the accuracy the information below this +rule. It may be significantly dated or incorrect.</STRONG> +<P> +<P> +<H3>Solaris 2.2</H3> +<P> +Solaris 2.2 and later contain completely re-written clock code to +provide high resolution microsecond timers. A benefit of the +re-written clock code is that adjtime does not round off its +adjustments, so ntp does not have to compensate for this +rounding. Under Solaris 2.2 and later, ntp #define's +<CODE>ADJTIME_IS_ACCURATE</CODE>, and does not look for the <I>tickadj</I> +kernel variable. +<P> +<H3>Solaris 2.1</H3> +(This originally written by William L. Jones <jones@chpc.utexas.edu>) +<P> +Solaris 2.1 contains fairly traditional clock code, with <I>tick</I> +and <I>tickadj</I>. +<P> +Since settimeofday under Solaris 2.1 only sets the seconds part of timeval +care must be used in starting xntpd. I suggest the following start +up script: +<BLOCKQUOTE><TT> +tickadj -s -a 1000 +<BR>ntpdate -v server1 server2 +<BR>sleep 20 +<BR>ntpdate -v server1 server2 +<BR>sleep 20 +<BR>tickadj -a 200 +<BR>xntpd +</TT></BLOCKQUOTE> + +The first tickadj turns of the time of day clock and sets the tick +adjust value to 1 millisecond. This will insure that an adjtime value +of at most 2 seconds will complete in 20 seconds. +<P> +The first ntpdate will set the time to within two seconds +using settimeofday or it will adjust time using adjtime. +<P> +The first sleep insures the adjtime has completed for the first ntpdate. +<P> +The second ntpdate will use adjtime to set the time of day since the +clock should be within 2 seconds of the correct time. +<P> +The second tickadj set the tick adjust system value to 5 microseconds. +<P> +The second sleeps insure that adjtime will complete before starting +the next xntpd. +<P> +I tried running with a tickadj of 5 microseconds with out much success. +200 microseconds seems to work well. +<P> +<HR> +Prior versions of this file had major text contributed by: +<MENU> +<LI>Denny Gentry <denny@eng.sun.com> +</MENU> +<BODY> +</HTML> diff --git a/contrib/ntp/html/build/hints/solaris.xtra.4023118 b/contrib/ntp/html/hints/solaris.xtra.4023118 index 84c5d15..84c5d15 100644 --- a/contrib/ntp/html/build/hints/solaris.xtra.4023118 +++ b/contrib/ntp/html/hints/solaris.xtra.4023118 diff --git a/contrib/ntp/html/build/hints/solaris.xtra.4095849 b/contrib/ntp/html/hints/solaris.xtra.4095849 index 8d3ce80..8d3ce80 100644 --- a/contrib/ntp/html/build/hints/solaris.xtra.4095849 +++ b/contrib/ntp/html/hints/solaris.xtra.4095849 diff --git a/contrib/ntp/html/build/hints/solaris.xtra.S99ntpd b/contrib/ntp/html/hints/solaris.xtra.S99ntpd index d8058fd..d8058fd 100644 --- a/contrib/ntp/html/build/hints/solaris.xtra.S99ntpd +++ b/contrib/ntp/html/hints/solaris.xtra.S99ntpd diff --git a/contrib/ntp/html/build/hints/solaris.xtra.patchfreq b/contrib/ntp/html/hints/solaris.xtra.patchfreq index 9600881..9600881 100644 --- a/contrib/ntp/html/build/hints/solaris.xtra.patchfreq +++ b/contrib/ntp/html/hints/solaris.xtra.patchfreq diff --git a/contrib/ntp/html/build/hints/sun4 b/contrib/ntp/html/hints/sun4 index 424fa18..424fa18 100644 --- a/contrib/ntp/html/build/hints/sun4 +++ b/contrib/ntp/html/hints/sun4 diff --git a/contrib/ntp/html/build/hints/svr4-dell b/contrib/ntp/html/hints/svr4-dell index 2c92f8a..2c92f8a 100644 --- a/contrib/ntp/html/build/hints/svr4-dell +++ b/contrib/ntp/html/hints/svr4-dell diff --git a/contrib/ntp/html/build/hints/svr4_package b/contrib/ntp/html/hints/svr4_package index b9f5ca3..b9f5ca3 100644 --- a/contrib/ntp/html/build/hints/svr4_package +++ b/contrib/ntp/html/hints/svr4_package diff --git a/contrib/ntp/html/build/hints/todo b/contrib/ntp/html/hints/todo index e0e5ffa..e0e5ffa 100644 --- a/contrib/ntp/html/build/hints/todo +++ b/contrib/ntp/html/hints/todo diff --git a/contrib/ntp/html/hints/vxworks.html b/contrib/ntp/html/hints/vxworks.html new file mode 100644 index 0000000..eac9312 --- /dev/null +++ b/contrib/ntp/html/hints/vxworks.html @@ -0,0 +1,88 @@ +<!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>vxWorks Port of NTP</title> + <link href="../scripts/style.css" type="text/css" rel="stylesheet"> + </head> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> + + <body link="#00008B" vlink="#8B0000"> + <h4>VxWorks port of NTP</h4> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> + <p>Creating a port for vxWorks posed some problems. This port may help as a starting point for similar ports to real-time OS's and other embeddable kernels, particularly where <tt>main()</tt> is not allowed, and where the configure scripts need to be altered.</p> + <h4>Configuration issues</h4> + <p>I decided to do as little invasive surgery as possible on the NTP code, so I brought the vxWorks header tree in line with the standard Unix tree. The following changes were needed, as a side effect these changes will allow for easy porting of other autoconfigure enabled code.</p> + <p>Where I have 386 you will need to put in your target type. The vxWorks tree entry point is <tt>/usr/wind</tt>. If these are the same for your system, you should be able to cut and paste the changes.</p> + <p><blink>WARNING: Check you are not overwriting files, before entering the following: there should be no conflict, but check first...</blink></p> + <pre> + export CC="cc386 -nostdlib -m486 -DCPU=I80486 -I/usr/wind/target/h" + export RANLIB=ranlib386 + export AR=ar386 + export VX_KERNEL=/usr/wind/target/config/ims_std_bsp/vxWorks<br> + + cd /usr/wind/target/sys + ln -s ../signal.h + ln -s ../time.h + ln -s socket.h sockio.h + ln -s ../selectLib.h select.h + ln -s ../timers.h + touch file.h param.h resource.h utsname.h var.h ../netdb.h ../a.out.h ../termios.h + echo " ******ADD #include \"sys/times.h\" to sys/time.h " + </pre> + The configure script must be changed in the following way to get the linking tests to work, once in the correct directory issue the following commands: + + <pre> sed -e 's%main.*()%vxmain()%' configure > configure.vxnew + mv configure.vxnew configure + chmod 755 configure + </pre> + <p></p>The new version 4 of NTP requires some maths functions so it links in the maths library (-lm) in the <tt>./ntpd/Makefile.am</tt> file change the line <tt>ntpd_LDADD = $(LDADD) -lm</tt> by removing the "-lm".</p> + <p>>You are now ready to compile + <p>The ./configure.in file needed to be altered to allow for a host-target configuration to take place.</p> + <ul> + <li>The define SYS_VXWORKS was added to the compilation flags. + <li>Little endianess is set if the target is of type iX86. + <li>The size of char, integer, long values are all set. If Wind River ever changes these values they will need to be updated. + <li>clock_settime() is defined to be used for setting the clock. + <li>The Linking flags have -r added to allow for relinking into the vxWorks kernel + </ul> + <p>Unfortunately I have had to make use of the <tt>./include/ntp_machine.h</tt> file to add in the checks that would have been checked at linking stage by <tt>autoconf</tt>, a better method should be devised.</p> + <ul> + <li>There is now a <tt>NO_MAIN_ALLOWED</tt> define that simulates command line args, this allows the use of the normal startup sysntax. + <li>POSIX timers have been added. + <li>Structures normally found in <tt>netdb.h</tt> have been added with, the corresponding code is in <tt>./libntp/machines.c</tt>. Where possible the defines for these have been kept non-vxWorks specific. + </ul> + <p>Unfortunately there are still quite a few <tt>SYS_VXWORKS</tt> type defines in the source, but I have eliminated as many as possible. You have the choice of using the <tt>usrtime.a</tt> library avaliable from the vxworks archives or forgoing <tt>adjtime()</tt> and using the <tt>clock_[get|set]time()</tt>. The <tt>./include/ntp_machine.h</tt> file clearly marks how to do this.</p> + <h4>Compilation issues</h4> + <p>You will need autoconf and automake ... available free from the gnu archives worldwide.</p> + <p>The variable <tt>arch</tt> is the target architecture (e.g. i486)</p> + <pre> + mkdir A.vxworks) + cd A.vxworks + ../configure --target=arch-wrs-vxworks + make + </pre> + <p>Options I normally use are the <tt>--disable-all-clocks --enable-LOCAL-CLOCK</tt> flags. The program should proceed to compile without problem. The daemon ntpd, ntpdate, ntptrace, ntpdc, ntpq programs and of course the libraries are all fully ported. The other utilities are not, but they should be easy to port.</p> + <h4>Running the software</h4> + <p>Load in the various files, call them in the normal vxWorks function type manner. Here are some examples. Refer to the man pages for further information.</p> + <pre> + ld < ntpdate/ntpdate + ld < ntpd/ntpd + ld < ntptrace/ntptrace + ld < ntpq/ntpq + ld < ntpdc/ntpdc + ntpdate ("-b", "192.168.0.245") + sp(ntpd, "-c", "/export/home/casey/ntp/ntp.conf") + ntpdc("-c", "monlist", "192.168.0.244") + ntpq("-c", "peers", "192.168.0.244") + ntptrace("192.168.0.244") + </pre> + <p>Casey Crellin, casey@csc.co.za</p> + </body> + +</html> diff --git a/contrib/ntp/html/hints/winnt.html b/contrib/ntp/html/hints/winnt.html new file mode 100644 index 0000000..7c41b86 --- /dev/null +++ b/contrib/ntp/html/hints/winnt.html @@ -0,0 +1,90 @@ +<!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 on Windows NT</title> + <link href="../scripts/style.css" type="text/css" rel="stylesheet"> + </head> + <body> + <h3>NTP 4.x for Windows</h3> + + <h4>Introduction</h4> + <p>The NTP 4 distribution runs as service on Windows 2000 and later. It will NOT run on Windows 95, 98, ME, etc. Lately it has been run the most on Windows-7 and later. The binaries work on multi-processor systems. This port has not been tested on the Alpha platform. This release now uses OpenSSL for authentication. IPv6 is not implemented yet for Win32 platforms. A ready-to-run install distribution is available from Meinberg at <a href="http://www.meinberg.de/english/sw/ntp.htm">http://www.meinberg.de/english/sw/ntp.htm.</a></p> + <p>Users should note that the stock Windows client sends requests as mode-1 packets, which can have unintended consequences and create a security risk. The client should send requests as mode-3 (client) packets, which conform to the protocol specification. The issues and resolution are described in Microsoft KB 875424. A less desirable alternative that avoids changing registry keys is to use the <tt>--with-wintime</tt> option when building the executable.</p> + <h4>Authentication Keys</h4> + <p>With this release ntp-keygen is supported. See the <a href="../keygen.html"> ntp keygen documentation</a> for details on how to use ntp-keygen.</p> + <p><tt>ntpd</tt> can now use the generated keys in the same way as on Unix platforms. Please refer to the <a href="../authopt.html">Authentication Options</a> for details on how to use these.</p> + <p><B>NOTE:</B> ntpd and <tt>ntp-keygen</tt> both use OpenSSL which requires a random + character file called <tt>.rnd</tt> by default. Both of these programs will automatically generate this file if they are not found. The programs will look for an environmental variable called RANDFILE and use that for the name of the random character file if the variable exists. If it does not exist it will look for an environmental variable called HOME and use that directory to search for a file called <tt>.rnd</tt> in that directory. Finally, if neither RANDFILE nor HOME exists it will look in <tt>C:\</tt> for a .rnd file. In each case it will search for and create the file if the environmental variable exists or in the C:\ directory if it doesn't.</p> + <p>Note that ntpd normally runs as a service so that the only way that it will have either RANDFILE or HOME defined is if it is a System environmental variable or if the service is run under a specific account name and that account has one of those variables defined. Otherwise it will use the file <tt>c:\.rnd</tt>. This was done so that OpenSSL will work normally on Win32 systems. This obviates the need to ship the OpenSSL.exe file and explain how to generate the .rnd file. A future version may change this behavior.</p> + <p>Refer to <a href="#Compiling">Compiling Requirements</a> and Instructions for how to compile the program.</p> + <h4>Reference Clocks</h4> + <p>Reference clock support under Windows NT is tricky because the IO functions are so much different. Some of the clock types have been built into the ntpd executable and should work but have not been tested by the ntp project. If you have a clock that runs on Win32 and the driver is there but not implemented on Win32 you will have make the required configuration changes in config.h and then build ntpd from source and test it. The following reference clock is known to work and is supported by Windows NT: <a href="../drivers/driver1.html">Type 1</a> Undisciplined Local Clock (LOCAL)</p> + <h4>Functions Supported</h4> + <p>All NTP functions are supported with some constraints. See the <a href="#ToDo">TODO list</a> below. Note that the ntptrace executable is not supported and you should use the PERL script version instead.</p> + <h4>Accuracy</h4> + <p>Greg Brackley has implemented a fantastic interpolation scheme that improves the precision of the NTP clock using a realtime thread (is that poetic or what!) which captures a tick count from the 8253 counter after each OS tick. The count is used to interpolate the time between operating system ticks.</p> + <p>On a typical 200+ MHz system NTP achieves a precision of about 5 microseconds and synchronizes the clock to +/-500 microseconds using the <a href="http://www.trimble.com/products/ntp">Trimble Palisade</a> as UTC reference. This allows distributed applications to use the 10 milliseconds ticks available to them with high confidence.</p> + <h4>Binaries</h4> + <p>Recent InstallShield based executable versions of NTP for Windows NT (intel) are available from:</p> + <ul> + <li><a href="http://www.five-ten-sg.com/">http://www.five-ten-sg.com/</a> + </ul> + <h4 id="ToDo">ToDo</h4> + <p>These tasks are in no particular order of priority.</p> + <ul> + <li>Add IPv6 support + <li>See if precision can be improved by using CPU cycle counter for tick interpolation. + <li>Make precision time available to applications using NTP_GETTIME API + </ul> + <h4>Compiling Requirements</h4> + <ul> + <li>Windows 7 or Windows.NET Server 2003, or later. + <li>Windows NT 4.0 Windows 2000, Windows XP or Windows Vista <i>may</i> still work. + <li>Microsoft Visual C++ 2008, 2010, or 2013 EE + <li>Some way of uncompressing and untarring the gzipped tar file. + <li>OpenSSL must be built on the box before building NTP. Additional steps would + be required to not use OpenSSL. + <li>Microsoft Visual C++ redistributables</ul> + <a name="Compiling"><B>Compiling Instructions</B></a> + <ol> + <li>Install Micosoft Visual C++ <a href="http://www.microsoft.com/downloads/details.aspx?familyid=9B2DA534-3E03-4391-8A4D-074B9F2BC1BF">redistributables</a> + <li>Install <a href="http://www.slproweb.com/products/Win32OpenSSL.html">OpenSSL full installer for Windows</a>. Add the following to your system environment variables in the control panel (adjusting paths as appropriate to point to the directory containing only an openssl subdirectory, for OPENSSL_INC, and to the directory containing openssl .lib files for OPENSSL_LIB: +<ul><li> OPENSSL_INC=C:\OpenSSL\include +<li> OPENSSL_LIB=C:\OpenSSL\lib</ul> + <li>Unpack the NTP-4.x.tar.gz using utilities such as WinZip or WinRar. + <li>Run Microsoft Visual C++ 2008 EE. + <li>Open the ports\winnt\vs2008\ntp.sln solution file + <li>Batch build all projects (Build menu, Batch Build..., select all, build). + <li>The built binaries can be found in the <tt>ports\winnt\v2008\Win32-bin\Release</tt> directory. + <li>If you are shipping binaries in a kit it is strongly recommended that you ship this file (winnt.html) along with the binaries. + </ol> + <h4>Configuration File</h4> + <p>The default NTP configuration file path is %SystemRoot%<tt>\system32\drivers\etc\. </tt>(%SystemRoot% is an environmental variable that can be determined by typing "set" at the "Command Prompt" or from the "System" icon in the "Control Panel").</p> + <p>Refer to your system environment and create your<tt> ntp.conf</tt> file in the directory corresponding to your system installation. The older <tt><WINDIR>\ntp.conf</tt> is still supported but you will get a log entry reporting that the first file wasn't found. + <h4>Installation Instructions</h4> + <p>The <tt>instsrv</tt> program in the instsrv subdirectory of the distribution can be used to install 'ntpd' as a service and start automatically at boot time. Instsrv is automatically compiled with the rest of the distribution if you followed the steps above.</p> + <ol> + <li>Start a command prompt and enter "instsrv.exe <pathname_for_ntpd.exe>" + <li>Clicking on the "Services" icon in the "Control Panel" will display the list of currently installed services in a dialog box. The NetworkTimeProtocol service should show up in this list. Select it in the list and hit the "Start" button in the dialog box. The NTP service should start. + <li>You can also stop and start the service by typing net start|stop NetworkTimeProtocol at the DOS prompt. + <li>View the event log by clicking on the "Event Viewer" icon in the "Administrative Tools" group, there should be several successful startup messages from NTP. NTP will keep running and restart automatically when the machine is rebooted. + </ol> + <p>You can change the start mode (automatic/manual) and other startup parameters corresponding to the NTP service in the "Services" dialog box if you wish.</p> + <h4>Removing NTP</h4> + <p>You can also use <tt>instsrv</tt> to delete the NTP service by entering: <tt>>"instsrv.exe remove"</tt> + <h4>Command Line Parameters and Registry Entries</h4> + <p>Unlike the Unix environment, there is no clean way to run 'ntpdate' and reset the clock before starting 'ntpd' at boot time. NTP will step the clock up to 1000 seconds by default. While there is no reason that the system clock should be that much off during bootup if <tt>ntpd</tt> was running before, you may wish to override this default and/or pass other command line directives. + <p>Use the registry editor to edit the value for the ntpd executable under LocalMachine\System\CurrentControlSet\Services\NTP.</p> + <p>Add the -g option to the ImagePath key, behind "%INSTALLDIR>\ntpd.exe". This will force NTP to accept large time errors (including 1.1.1980 00:00)</p> + <h4>Bug Reports</h4> + <p>Please follow the <a href="../bugs.html">NTP Bug Reporting Procedures</a> to report bugs or request enhancements.</p> + <p>Last update: + <!-- #BeginDate format:En2m -->6-Apr-2014 23:27<!-- #EndDate --> + </p> + + </body> +</html> diff --git a/contrib/ntp/html/history.html b/contrib/ntp/html/history.html new file mode 100644 index 0000000..8b1ad50 --- /dev/null +++ b/contrib/ntp/html/history.html @@ -0,0 +1,74 @@ +<!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>Historical Notes</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>Historical Notes</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:07<!-- #EndDate --> + UTC</p> +<hr> +<h4>Historical Notes on NTP Upgrades</h4> +<p>This is an interim report on recent upgrades to the NTPv4 reference implementation code base and documentation. This report documents the upgrade program, which began in June 2007 and continued until March 2008. It is very important to recognize that this historic document describes the upgrade status as of 2008. Additional upgrades have been implemented since then. As of mid 2011, the additional upgrades are documented on the <a href="release.html">NTP Version 4 Release Notes</a> page.</p> +<p>The motivation for this project was the overhaul and refinement of the code, some of which dates back twenty years. Some four dozen sets of fingers have introduced sometimes incompatible "improvements" that to some degree enhance or burden the product. There has been a continuing effort over the years to maintain the briar patch and pluck the more flagrant weeds, but it now requires a more systematic and thorough examination of purpose, design and implementation. The project is not complete, but far enough along to present a status report and review of significant changes.</p> +<p>Please note THE CHANGES DO NOT AFFECT THE PROTOCOL SPECIFICATION AND DO NOT AFFECT INTEROPERABILITY WITH PREVIOUS VERSIONS.</p> +<h4>1. Transparent Design</h4> +<p>During the project a number of minor inconsistencies in various algorithms were found and resolved. In most cases this did not result in any changes in behavior, just a more simplified, transparent and easier to maintain design. In a few cases behavior has been modified to correct deficiencies and to avoid hostile attacks, as described below.</p> +<h4>2. Documentation</h4> +<p>The documentation required a major upgrade. Many pages have been overhauled, some completely rewritten and new ones added. A site map has been added and sorted by page category. A comprehensive command index has been added and sorted by page category. The command index includes a brief gloss for each command. A page has been added to show the various status word and event decodes used for monitoring and event reporting. The decodes show the internal code, ASCII report and short function gloss.</p> +<p>New pages have been added on association management, automatic server discovery and rate management. Much of the overburden on the program manual and configuration pages has been moved to these pages with the intent of the original pages to contain primarily a functional description for the commands and command line options. This is still an ongoing process.</p> +<h4>3. Bulletproofing</h4> +<p>In a continuing mission the code flow has been carefully adjusted to decrease vulnerability to configuration errors and possibly hostile attack. The order of restriction processing was adjusted to deflect access denials as early as possible and without consuming useless processor cycles. This is especially important in rate defense, as the MRU list should only be used for clients that could be legitimately served. In addition, the Autokey protocol was adjusted to avoid some potentially nasty disruption attacks.</p> +<h4>4. Rate Management</h4> +<p>Strict rate controls have been refined in both outbound and inbound traffic for both minimum headway (guard time) and minimum average headway. This is a major improvement over the original limitreject design of 1992 and upgrade circa 2003. Headway violations result in an optional <em>kiss-o'-death</em> (KoD) packet. To avoid a clogging vulnerability, the KoD packets are themselves rate controlled for each source address separately.</p> +<p>The main feature of the revised design is that it is responsive to the server minimum headway and avoids guessing. This is done by setting the ppoll field in the server packet to the maximum of (a) the ppoll field in the client packet and (b) the server headway. The client sets the ppoll field in the association to the maximum of (a) the ppoll field in the server packet and (b) the minpoll field in the association. If this is a KoD and this value is greater than minpoll, minpoll is set to this value. The result is that the client continues sending, but only at headway at least as large as the server.</p> +<p>The revised design makes possible a decrease in the minimum time constant/poll interval to 3 (8 s), which reduces the risetime to 250 s. This may be useful for rapid convergence when a client is first started, but should not be used for links with moderate to large jitter. This is done using the average option of the discard command, which sets the minimum poll interval and headway from the default 4 (16 s) to a value in the range 3 (8 s) to 6 (64 s). Larger values than 4 might be appropriate for very busy public servers.</p> +<p>Rate management applies also to Autokey messages. This fixes a problem when iburst and autokey are both in play and when for some reason an association with iburst is repeatedly restarted. This may appear spooky to some folks that frequently restart a client for testing. The server remembers. Further information is in the current web documentation.</p> +<h4>5. Frequency File</h4> +<p>Initial frequency training has always been a problem, as it can take a very long time to trim the frequency estimate to nominal values. Once this happens and the frequency file is written, subsequent reboots will restore the frequency and frequency training is avoided. The problem is exacerbated using toll modem services such as ACTS which make a call at each poll interval. Until the training is complete the poll interval is held below the desired maximum as toll charges accrue.</p> +<p>The problem was solved by changing the clock state machine so that, if no frequency file is available, an initial training interval of 300 s occurs, after which the frequency is directly calculated and the discipline then turned over to the feedback loop. The choice of 300 s is based on the assumption that time can be estimated within 1 ms and the resulting frequency estimate within nominal 1 PPM.</p> +<p>Note that once the initial time offset is either stepped or slewed, no further time offsets are amortized during the training period. If the frequency error is large, the time offset at the end of the period can be moderately large, which then must be amortized by the feedback loop. While this may take up to an hour and result in a minor frequency tweak, the behavior is very much better than without the initial training. The remedy would require intricate and fragile code revisions.</p> +<p>In the original design the frequency file was written at one-hour intervals. This apparently makes embedded systems folks nervous, since this can tire the flash NVRAM after several years. The interval between writes now depends on the ambient clock stability and normally maxes out at something over one day unless the frequency takes an unusual twitch. </p> +<h4>6. Leapseconds</h4> +<p>The leapsecond processing has been overhauled once again. The problem is to avoid fake leap warnings displayed by an errant server and to insure correct response in case of large time changes which might validate or invalidate arming for a subsequent leap. No leap information is used unless the client is synchronized to a proventic source. The values obtained from an Autokey server or peer are updated if newer than the current values. Server leap warning bits are disregarded if these values are available. If not, and if either a majority of the servers show leap warning bits or if one or more of the survivors are a reference clock with leap warning bit, the leap is armed. If armed by server leap warning bits and these provisions no longer prevail, the leap is disarmed. The NTPv4 protocol specifically does not speak to this issue.</p> +<p>The leap armed condition is displayed in the host status word. Transitions between warnings and no warnings are reported to the protostats file, system log and traps.</p> +<h4>7. Orphan Mode and Local Clock Driver</h4> +<p>The orphan mode code has been overhauled to correct some minor bugs and to clarify operation under normal and recovery conditions. The requirement that all subnet hosts have orphan configuration has been removed. The only requirement is that the orphan clients on the DMZ network sharing the root server(s) be so configured The scheme now works if the root servers are configured with each other, either in symmetric or broadcast modes. Orphan mode is not considered in the NTPv4 protocol specification.</p> +<p>The local clock driver can be very dangerous when used as a fallback when connectivity to Internet time servers is interrupted. Orphan mode was designed to reduce the need for the local clock driver, as it is active only if no server is available. The local clock driver has been modified to have the same characteristics, regardless of stratum. Only if the host running the local clock driver loses all servers, regardless of stratum, is the driver activated. Thus, it is possible, but not recommended, to run the driver at any stratum, including zero.</p> +<h4>8. Poll Rate Control</h4> +<p>One of the most persistent problems is when after long operation and then a failure and then subsequently recovery, a client can take a long time to refresh the clock filter and resynchronize. Once the client has backed off the poll interval after a lengthy outage, it sends polls at that interval until receiving a response. At that time it temporarily retries at the minimum poll interval to fill up the clock filter. If iburst is configured, this will happen after 10 seconds or so and the client then resumes its poll interval required by the discipline time constant. This avoids needless network traffic while the poll interval increases gradually to the maximum. Further information is in the current web documentation.</p> +<p>The same thing happens on initial startup or when an association is restarted. The intent is to avoid a blast of <tt>iburst</tt> packets unless the server actually responds to the first one and to retry only while responding to the the rate controls.</p> +<p>In order to speed response to initial startup when a reference clock is available, the clock is set on the first message received from the driver. This exposed an interesting bug, now fixed, with the ACTS modem driver, which began prematurely to ramp up the poll interval.</p> +<h4>9. Autokey</h4> +<p>The management of host and group names with respect to Autokey configuration and key generation has been removed and simplified. On host certificates, the subject and issuer fields carry the group name, while other certificates carry the host name, which can be an arbitrary string having nothing to do with the DNS name. This opens up a possible future plan to use the Autokey name rather than the IP address when constructing the session key. It also allows a client to easily switch from one group to another without regenerating the certificate. Further information is in the current web documentation and in the latest Autokey ID.</p> +<p>Various protocol refinements have been done in the Autokey state machine. A bug was found in symmetric modes where the peer cookies were not EXORed. A bug was found in processing the certificate cache when a participant was a client of two or more server in the same group which themselves had certificate trails to different trusted hosts.</p> +<p>The protocol machine is now restarted every several days in order to update certificates and leapseconds values when they are changed.</p> +<h4> 10. Report, Log and Event Codes </h4> +<p>The status, selection, source, event and log decodes have been adjusted for consistency. Some of the decodes were missing, some with errors and a few new ones added. Old versions of ntpq continue to work without change, but display a new code as space. Except for the new codes, this behavior is consistent with RFC 1305 and proposed for the NTPv4 protocol specification.</p> +<p>The ntpq as command has been changed to fix some very old bugs. The display is now consistent with the system and peer billboards. The authentication state is correctly displayed for broadcast server associations.</p> +<p>The event reporting has been cleaned up for more straightforward interpretation by a remote agent. All significant state transitions are reported, including clock state machine changes, mobilization, /demobilization, system and peer restart, system peer change, panic stop and so forth.</p> +<p>A new protostats monitoring file facility has been added. It works just like the other monitor files. All events are recorded to this file as reported and optionally to the system log. Many reports that sometimes clog up the system log are more usefully directed to this file. The reports also trigger a trap packet that can be sent via an agent to page an administrator.</p> +<p>When the current mode-6 monitoring protocol was designed circa 1988 the considered intent was that monitoring functions rely only on the NTP packet itself and the system, peer and clock status words provided in the mode-6 packet. While the strongly felt advice at that time was to avoid reformatting the plain ASCII text sent by the server, at various times folks have cheated and reformatted the text. In some places this is good, like displaying the filter shift register; in some places this is bad, like reformatting the timestamps. There is nothing much that can be done about this now without angry mobs rioting when forced to upgrade to a new ntpq. I will not rule this out in future.</p> +<p>A more serious comment has to do with using other than the NTP packet, status words and events for monitoring purposes. Emphasis added: monitors should not parse such things as the flash codes, clock state or anything else not called out in the NTPv4 specification. The clock state machine is defined in the specification, but no specific numbers are assigned to the states.</p> +<p>When the numbers were changed to align for reporting purposes, some scripts no longer worked. The scripts should be changed to use only the leap and select fields of the system status word. If the leap field is other than 0, the client has synchronized at least once; if the select field is other than 0, the client is currently synchronized to the source indicated in the decode.</p> +<h4>11. Two-step and timestamp capture</h4> +<p>A number of interesting ideas were found in the IEEE 1588 Precision Time Protocol specification. One of them was the two-step protocol in which the transmit timestamp is sent in a following message. However, the PTP design operates only in a master-slave configuration and is not directly usable in NTP. The protocol was adapted to the NTP symmetric design, which requires four state variables rather than two. It is described on <a href="http://www.eecis.udel.edu/~mills/stamp.html">Timestamp Capture Principles</a>. This might be an interesting project for future research.</p> +<p>A detailed study of the timestamp capture opportunities for both hardware and software timestamping revealed that the most accurate and interoperable design involves the transmit timestamp at the beginning of the packet and then receive timestamp at the end. This makes it possible to accurately measure the offset and delay even if the ends of the synchronization path operate at different rates. It is described on the Timestamp Capture Principles page.</p> +<h4>12. Windows client bug</h4> +<p>The Windows XP and Vista clients send the NTP request in symmetric active mode rather than client mode. An unsuspecting server could mobilize a symmetric passive association, which is a serious security vulnerability. The NTPv4 servers, including those at NIST and USNO, discard symmetric active requests unless cryptographically authenticated, so Windows clients do not work. The Microsoft KB 875424 discusses the preferred workaround; however, an optional workaround is now available so that, if the request is not authenticated, the server responds with symmetric passive mode, but without mobilize an association. The workaround is enabled with the WINTIME build option.</p> +<p>The spec assumes that either peer in symmetric modes can synchronize the other should a peer lose all sources. The workaround violates that assumption and some legitimate configuration might be badly misused. It should be used only with this understanding.</p> +<h4>13. Autonomous configuration</h4> +<p>The autonomous configuration (pool and manycast) code was refined to more reliably prune excess servers. If a truechimer is discarded by the clustering algorithm and the total number of survivors is greater than the maxclock option of the tos command, it is considered excess and shows a "#" tally code. If the association is ephemeral and survives the clustering algorithm, the watchdog counter is reset. If the watchdog timer expires and the total number of associations is greater than the maxclock option of the tos command, it is demobilized. This behavior is not considered in the NTPv4 protocol specification.</p> +<h4>14. Code ornamentation</h4> +<p>When auditing the code and figuring out its historic origin and evolution, additional commentary has been added so future generations can figure it out, too. </p> +<p>David L. Mills<br> + 17 March 2008<br> +</p> +<hr> +<p><script type="text/javascript" language="javascript" src="scripts/footer.txt"></script></p> +</body> +</html> diff --git a/contrib/ntp/html/howto.html b/contrib/ntp/html/howto.html index 3a1007f..e89fa78 100644 --- a/contrib/ntp/html/howto.html +++ b/contrib/ntp/html/howto.html @@ -1,109 +1,109 @@ <!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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:39</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links10.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#desc">Description</a> - <li class="inline"><a href="#file">Files Which Need to be Changed</a> - <li class="inline"><a href="#intf">Interface Routine Overview</a> - </ul> - <hr> - <h4 id="desc">Description</h4> - <p>NTP reference clock support maintains the fiction that the clock is actually an ordinary peer in the NTP tradition, but operating at a synthetic stratum of zero. The entire suite of algorithms used to filter the received data, select the best clocks or peers and combine them to produce a system clock correction operate just like ordinary NTP peers. In this way, defective clocks can be detected and removed from the peer population. As no packets are exchanged with a reference clock; however, the transmit, receive and packet procedures are replaced with separate code to simulate them.</p> - <p>It is important to understand how the NTP clock driver interface works. 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 and frequency to standard 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 and/or the estimated time error.</p> - <p>All three timescales run <i>only</i> in Coordinated Universal Time (UTC), 24-hour format, 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 NTP clock driver synchronizes the system time and frequency to the radio via serial or parallel port, PPS signal or other means. The driver routinely checks the radio timecode string or status indicators to determine whether it is operating correctly or not. If it is, the driver decodes the radio timecode in days, hours, minutes, seconds and nanoseconds and provides these data with the NTP receive timestamp corresponding to the on-time epoch of the timecode. The driver interface computes the difference between the timecode time and NTP timestamp and saves the difference in a circular buffer for later processing. Once each poll interval, usually 64 s, the driver provides ancillary data including leap bits and last reference time to the interface. The interface processes the circular buffer using a median/trimmed mean algorithm to extract the best estimate and provides this and the ancillary data to the clock filter as with ordinary NTP peers.</p> - <p>The audio drivers are designed to look like a typical external radio in that the reference oscillator is derived from the audio codec oscillator and separate from the system clock oscillator. In the WWV and IRIG drivers, the codec oscillator is disciplined in frequency to the standard timescale via radio or local sources and can be assumed to have the same reliability and accuracy as an external radio. In these cases the driver continues to provide updates to the clock filter even if the WWV or IRIG signals are lost. However, the interface is provided the last reference time when the signals were received and increases the dispersion as expected with an ordinary peer.</p> - <p>The best way to understand how the clock drivers work is to study the <tt>ntp_refclock.c</tt> module and one of the drivers already implemented, such as <tt>refclock_wwvb.c</tt>. Routines <tt>refclock_transmit()</tt> and <tt>refclock_receive()</tt> maintain the peer variables in a state analogous to a network peer and pass received data on through the clock filters. Routines <tt>refclock_peer()</tt> and <tt>refclock_unpeer()</tt> initialize and terminate reference clock associations, should this ever be necessary. A set of utility routines is included to open serial devices, process sample data, edit input lines to extract embedded timestamps and to perform various debugging functions.</p> - <p>The main interface used by these routines is the <tt>refclockproc</tt> structure, which contains for most drivers the decimal equivalents of the year, day, month, hour, second and nanosecond decoded from the radio timecode. Additional information includes the receive timestamp, reference timestamp, exception reports, statistics tallies, etc. The support routines are passed a pointer to the <tt>peer</tt> structure, which is used for all peer-specific processing and 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>The reference clock interface supports auxiliary functions to support in-stream timestamping, pulse-per-second (PPS) interfacing and precision time kernel support. In most cases the drivers do not need to be aware of them, since they are detected at autoconfigure time and loaded automatically when the device is opened. These include the <tt>tty_clk</tt> STREAMS module and <tt>ppsapi</tt> PPS interface described in the <a href="ldisc.html">Line Disciplines and Streams Modules</a> page. The <tt>tty_clk</tt> module reduces latency errors due to the operating system and serial port code in slower systems. The <tt>ppsapi</tt> PPS interface replaces the <tt>ppsclock</tt> STREAMS module and is expected to become the IETF standard cross-platform interface for PPS signals. In either case, the PPS signal can be connected via a level converter/pulse generator described in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page.</p> - <p>Radio and modem reference clocks by convention have addresses in 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>d</i>d</tt> to the particular hardware device involved, where <tt><i>d</i></tt> corresponds to the unit number.</p> - <p>By convention, reference clock drivers are named in the form <tt>refclock_<i>xxxx</i>.c</tt>, where <i>xxxx</i> 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. They are configured when the daemon is started according to the configuration file, as described in the <a href="build/config.html">Configuration Options</a> page.</p> - <p>The standard clock driver interface includes a set of common support routines some of which do such things as start and stop the device, open the serial port, and establish special functions such as PPS signal support. Other routines read and write data to the device and process time values. Most drivers need only a little customizing code to, for instance, transform idiosyncratic timecode formats to standard form, poll the device as necessary, and handle exception conditions. A standard interface is available for remote debugging and monitoring programs, such as <tt>ntpq</tt> and <tt>ntpdc</tt>, as well as the <tt>filegen</tt> facility, which can be used to record device status on a continuous basis.</p> - <p>The general organization of a typical clock driver includes a receive-interrupt routine to read a timecode from the I/O buffer and convert to internal format, generally in days, hours, minutes, seconds and fraction. Some timecode formats include provisions for leap-second warning and determine the clock hardware and software health. The interrupt routine then calls <tt>refclock_process()</tt> with these data and the timestamp captured at the on-time character of the timecode. This routine saves each sample as received in a circular buffer, which can store from a few up to 60 samples, in cases where the timecodes arrive one per second.</p> - <p>The <tt>refclock_transmit()</tt> routine in the interface is called by the system at intervals defined by the poll interval in the peer structure, generally 64 s. This routine in turn calls the transmit poll routine in the driver. In the intended design, the driver calls the <tt>refclock_receive()</tt> to process the offset samples that have accumulated since the last poll and produce the final offset and variance. The samples are processed by recursively discarding median outlyers until about 60 percent of samples remain, then averaging the surviving samples. When a reference clock must be explicitly polled to produce a timecode, the driver can reset the poll interval so that the poll routine is called a specified number of times at 1-s intervals.</p> - <p>The interface code and this documentation have been developed over some time and required not a little hard work converting old drivers, etc. Should you find success writing a driver for a new radio or modem service, please consider contributing it to the common good. Send the driver file itself and patches for the other files to Dave Mills (mills@udel.edu).</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. When a PPS signal is available, a special automatic calibration facility is provided. If the <tt>flag1</tt> switch is set and the PPS signal is actively disciplining the system time, the calibration value is automatically adjusted to maintain a residual offset of zero. Should the PPS signal or the prefer peer fail, the adjustment is frozen and the remaining drivers continue to discipline the system clock with a minimum of residual error.</p> - <h4 id="file">Files Which Need to be Changed</h4> - <p>A new reference clock implementation needs to supply, in addition to the driver itself, several changes to existing files.</p> - <dl> - <dt><tt>./include/ntp.h</tt> - <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. - <dt><tt>./libntp/clocktypes.c</tt> - <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. - <dt><tt>./ntpd/ntp_control.c</tt> - <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. - <dt><tt>./ntpd/refclock_conf.c</tt> - <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. - <dt><tt>./configure.in</tt> - <dd>This is a configuration file used by the autoconfigure scheme. Add lines similar to the following: - <pre> - AC_MSG_CHECKING(FOO clock_description) - AC_ARG_ENABLE(FOO, - AC_HELP_STRING([--enable-FOO], [x clock_description]), - [ntp_ok=$enableval], [ntp_ok=$ntp_eac]) - if test "$ntp_ok" = "yes"; then - ntp_refclock=yes - AC_DEFINE(CLOCK_FOO, 1, [Foo clock?]) - fi - AC_MSG_RESULT($ntp_ok) -</pre> - <dd>(Note that <tt>$ntp_eac</tt> is the value from <tt>--{dis,en}able-all-clocks</tt> for non-PARSE clocks and <tt>$ntp_eacp</tt> is the value from <tt>--{dis,en}able-parse-clocks</tt> for PARSE clocks. See the documentation on the autoconf and automake tools from the GNU distributions.) - <dt><tt>./ntpd/Makefile.am</tt> - <dd>This is the makefile prototype used by the autoconfigure scheme. Add the driver file name to the entries already in the <tt>ntpd_SOURCES</tt> list. - <dd>Do the following sequence of commands: - <pre> - autoreconf - configure -</pre> - <dd>or simply run <tt>make</tt>, which will do this command sequence automatically. - </dl> - <h4 id="intf">Interface Routine Overview</h4> - <dl> - <dt><tt>refclock_newpeer</tt> - initialize and start a reference clock - <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. - <dt><tt>refclock_unpeer</tt> - shut down a clock - <dd>This routine is used to shut down a clock and return its resources to the system. - <dt><tt>refclock_transmit</tt> - simulate the transmit procedure - <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. - <dt><tt>refclock_sample</tt> - process a pile of samples from the clock - <dd>This routine converts the timecode in the form days, hours, minutes, seconds, milliseconds/microseconds to internal timestamp format. It then calculates the difference from the receive timestamp and assembles the samples in a shift register. It implements a recursive median filter to suppress spikes in the data, as well as determine a rough dispersion estimate. A configuration constant time adjustment <tt>fudgetime1</tt> can be added to the final offset to compensate for various systematic errors. The routine returns one if success and zero if failure due to invalid timecode data or very noisy offsets. - <dd>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. Nevertheless, the absence of the year should be considered more a bug than a feature and may be supported in future. - <dt><tt>refclock_receive</tt> - simulate the receive and packet procedures - <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. - <dt><tt>refclock_gtlin</tt> - groom next input line and extract timestamp - <dd>This routine processes the timecode received from the clock and removes the parity bit and control characters. If a timestamp is present in the timecode, as produced by the <tt>tty_clk</tt> line discipline/streams module, it returns that as the timestamp; otherwise, it returns the buffer timestamp. The routine return code is the number of characters in the line. - <dt><tt>refclock_open</tt> - open serial port for reference clock - <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. - <dt><tt>refclock_ioctl</tt> - set serial port control functions - <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 sets up the <tt>tty_clk, chu_clk</tt> and <tt>ppsclock</tt> streams module/line discipline, if compiled in the daemon and requested in the call. The routine returns one if success and zero if failure. - <dt><tt>refclock_control</tt> - set and/or return clock values - <dd>This routine is used mainly for debugging. It returns designated values from the interface structure that can be displayed using ntpdc and the clockstat command. It can also be used to initialize configuration variables, such as <tt>fudgetimes, fudgevalues,</tt> reference ID and stratum. - <dt><tt>refclock_buginfo</tt> - return debugging info - <dd>This routine is used mainly for debugging. It returns designated values from the interface structure that can be displayed using <tt>ntpdc</tt> and the <tt>clkbug</tt> command. - </dl> - <hr> - <center> - <img src="pic/pogo1a.gif" alt="gif"></center> - <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>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 -->10-Mar-2014 05:08<!-- #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> diff --git a/contrib/ntp/html/huffpuff.html b/contrib/ntp/html/huffpuff.html new file mode 100644 index 0000000..2be4d4a --- /dev/null +++ b/contrib/ntp/html/huffpuff.html @@ -0,0 +1,31 @@ +<!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 -->10-Mar-2014 05:09<!-- #EndDate --> + UTC</p> +<hr> +<p>In scenarios where a considerable amount of data are downloaded or uploaded using DSL or telephone modem lines, timekeeping quality can be seriously degraded. This occurs because the traffic volume, and thus the queuing delays, on the upload and download directions of transmission can be very different. 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 large 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> +<div align="center"><img src="pic/flt4.gif" alt="gif"> +<p>Figure 1. Huff-n'-Puff Wedge Scattergram</p> +</div> +<p>Figure 1 shows how the huff-n'-puff filter works. Recall from the <a href="filter.html">Clock Filter Algorithm</a> page that the wedge scattergram plots sample points (<em>x</em>, <em>y</em>) corresponding to the measured delay and offset, and that the limb lines are at slope ±0.5. Note in the figure that the samples are clustered close to the upper limb line, representing heavy traffic in the download direction. The apparent offset <i>y</i><sub>0</sub> is near zero at the minimum delay <i>x</i><sub>0</sub>, which is near 0.1s. Thus, for a point (<em>x</em>, <em>y</em>), the true offset is</p> +<blockquote> + <p> θ = <em>y</em> <font face="symbol">-</font> (<em>x </em><font face="symbol">- </font><i>x</i><sub>0</sub>) / 2 for <em>y</em> > <i>y</i><sub>0</sub> at or near the upper limb line or<br> + θ = <em>y</em> <font face="symbol">+</font> (<em>x </em><font face="symbol">- </font><i>x</i><sub>0</sub>) / 2 for <em>y</em> < <i>y</i><sub>0</sub> at or near the lower limb line.</p> +</blockquote> +<p>In either case the associated delay is δ = <em>x</em>.</p> +<p>In the interior of the wedge scattergram far from the limb lines, the corrections are less effective and can lead to significant errors if the area between the limb lines is heavily populated.</p> +<hr> +<p><script type="text/javascript" language="javascript" src="scripts/footer.txt"></script></p> +</body> +</html> diff --git a/contrib/ntp/html/icons/sitemap.png b/contrib/ntp/html/icons/sitemap.png Binary files differnew file mode 100644 index 0000000..17c7c55 --- /dev/null +++ b/contrib/ntp/html/icons/sitemap.png diff --git a/contrib/ntp/html/index.html b/contrib/ntp/html/index.html index 5c19313..d409837 100644 --- a/contrib/ntp/html/index.html +++ b/contrib/ntp/html/index.html @@ -1,101 +1,73 @@ <!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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:39</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <br clear="left"> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#intro">Introduction</a> - <li class="inline"><a href="#build">Building and Installing NTP</a> - <li class="inline"><a href="#conf">Configuring Clients and Servers</a> - <li class="inline"><a href="#prog">Program Manual Pages</a> - <li class="inline"><a href="#docs">Supporting Documentation</a> - <li class="inline"><a href="#back">Background Information</a> - <li class="inline"><a href="#app">Application Notes</a> - </ul> - <hr> - <h4 id="intro">Introduction</h4> - <p>Note: The software contained in this distribution is available without charge under the conditions set forth in the <a href="copyright.html">Copyright Notice</a>.</p> - <p>The Network Time Protocol (NTP) is used to synchronize the time of a computer client or server to another server or reference time source, such as a radio or satellite receiver or modem. It provides accuracies typically within a millisecond on LANs and up to a few tens of milliseconds on WANs relative to Coordinated Universal Time (UTC) via a Global Positioning Service (GPS) receiver, for example. Typical NTP configurations utilize multiple redundant servers and diverse network paths in order to achieve high accuracy and reliability.</p> - <p>This software release implements NTP Version 4 (NTPv4), but is in general backwards compatible with previous versions except NTP Version 1, support for which is no longer viable. NTPv4 includes support for both symmetric key and public key cryptography to prevent accidental or malicious protocol attacks, as well as automatic server discovery using IP multicast means. This release includes full support for the IPv6 address family, where the operating system supports it, as well as the default IPv4 address family. Either or both families can be used at the same time on the same machine.</p> - <p>Background information on computer network time synchronization can be found on the <a href="http://www.eecis.udel.edu/%7emills/exec.html">Executive Summary - Computer Network Time Synchronization</a> page. Discussion on protocol conformance issues and interoperability with previous NTP versions can be found on the <a href="http://www.eecis.udel.edu/%7emills/biblio.html">Protocol Conformance Statement</a> page. Discussion on how NTP reckons the time can be found on the <a href="http://www.eecis.udel.edu/%7emills/leap.html">NTP Timescale and Leap Seconds</a> page. Background information, bibliography and briefing slides suitable for presentations can be found on the <a href="http://www.eecis.udel.edu/%7emills/ntp.html">Network Time Synchronization Project</a> page. Additional information can be found at the NTP web site <a href="http://www.ntp.org">www.ntp.org</a>. Please send bug reports to <a href="mailto:bugs@mail.ntp.org"><bugs@mail.ntp.org></a>.</p> - <h4 id="build">Building and Installing NTP</h4> - <p>NTP supports Unix and Windows (XP, NT4 and 2000) systems. The <a href="build/build.html">Building and Installing the Distribution</a> page presents an overview of the procedures for compiling the distribution and installing it on a typical client or server. The build procedures inspect the system hardware and software environment and automatically select the appropriate options for that environment. While these procedures work with most computers and operating systems marketed today, exceptions requiring manual intervention do exist, as documented on the <a href="build/config.html">Configuration Options</a> and <a href="release.html">Release Notes</a> pages.</p> - <p>Bringing up a NTP primary server requires a radio or satellite receiver or modem. The distribution includes hardware drivers for some forty radio and satellite clocks and modem services. A list of supported drivers is given on the <a href="refclock.html">Reference Clock Drivers</a> page. It is also possible to use an otherwise undisciplined machine as a primary or backup server, as described on the <a href="drivers/driver1.html">Undisciplined Local Clock</a> page. For most popular workstations marketed by Sun, Silicon Graphics and Hewlett Packard, as well as widely available Unix clones such as FreeBSD and Linux, the automatic build procedures select all drivers that run on the target machine. While this increases the size of the executable binary somewhat, individual drivers can be included or excluded using the configure utility documented in the Configuration Options page.</p> - <p>Some programs included in this distribution use cryptographic algorithms to verify authenticity and credentials. Where local security policy permits relatively weak symmetric key cryptography, the required software is included in this distribution. However, where local policy requires stronger public key cryptography, additional software not in this distribution is required. This distribution uses the OpenSSL library available from <a href="http://www.openssl.org">http://www.openssl.org</a>. This library is also used by the Secure Shell facility, so is often already installed on Unix workstations and servers. It includes support for most message digest and digital signature algorithms used in the industry, as well as X.509 certificate generation, signing and verification.</p> - <p>While public key cryptography is optional but highly recommended for all NTP operations, it is required for the NTPv4 Autokey protocol described on the <a href="http://www.eecis.udel.edu/%7emills/autokey.html">Autonomous Authentication</a> page and is an integral component of the generic automatic configuration scheme described on the <a href="http://www.eecis.udel.edu/%7emills/autocfg.html">Autonomous Configuration</a> page. In addition, access can be restricted in various ways described on the <a href="accopt.html">Access Control 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 and used for a great many widely divergent timekeeping scenarios. The documentation presented on these pages attempts to cover the entire suite of configuration, operation and maintenance facilities which this distribution supports. However, most applications will need only a few of these facilities. If this is the case, the <a href="build/quick.html">Quick Start</a> page may be useful to get a simple workstation on the air with an existing server.</p> - <p>However, in order to participate in the existing NTP synchronization subnet and obtain accurate, reliable time, it is usually necessary to construct an appropriate configuration file, commonly called <tt>ntp.conf</tt>, which establishes the servers and/or external receivers or modems to be used by this particular machine. Directions for constructing this file are in the <a href="notes.html">Notes on Configuring NTP and Setting up a NTP Subnet</a> page. However, in many common cases involving simple network topologies and workstations, the configuration data can be specified entirely on the command line for the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a>.</p> - <p>The most important factor in providing accurate, reliable time is the selection of modes and servers to be used in the configuration file. A discussion on the available modes is on the <a href="assoc.html">Association Management</a> page. NTP support for one or more computers is normally engineered as part of the existing public NTP synchronization subnet. The public subnet consists of a multiply redundant hierarchy of servers and clients, with each level in the hierarchy identified by stratum number. Primary servers operate at stratum one and provide synchronization to secondary servers operating at stratum two and so on to higher strata. In this hierarchy, clients are simply servers that have no dependents.</p> - <p>Configuring a corporate or campus NTP subnet can be an engineering challenge. NTP contains many features designed to survive system and network failures, software bugs, clock errors and hacker attacks. Surviving these hazards requires intricate design of the timekeeping network using good principles of server redundancy and path diversity. The Manycast mode, new to NTPv4, is designed to track the current server and network states and adjust the client/server configuration for the best available accuracy and reliability. More information on the Manycast mode is on the <a href="authopt.html">Athentication Options</a> and <a href="manyopt.html">Automatic NTP Configuration Options</a> pages.</p> - <p>The NTP subnet in early 2003 includes well over a hundred public primary (stratum 1) servers synchronized directly to UTC by radio, satellite or modem and located in every continent of the globe, including Antarctica. Normally, client workstations and servers with a relatively small number of clients do not synchronize to primary servers. There are well over a hundred public secondary (stratum 2) servers synchronized to the primary servers and providing synchronization to a total well over 100,000 clients and servers in the Internet. The current lists are maintained on the <a href="http://www.eecis.udel.edu/%7emills/ntp/index.html">Information on Time and Frequency Services</a> page, which is updated frequently. There are thousands upon thousands of private primary and secondary servers not normally available to the public, many hiding behind firewalls. Clients are strongly discouraged against using these servers, since they sometimes hide in little ghettos behind dinky links to the outside world and unwanted traffic can bring up expensive ISDN lines, causing much grief and frustration. There are defensive means described on the Access Control Options page, including the Kiss-of-Death packet.</p> - <h4 id="prob">Resolving Problems</h4> - <p>Like other things Internet, the NTP synchronization subnets tend to be large and devilishly intricate, with many opportunities for misconfiguration and network problems. The NTP engineering model is specifically designed to help isolate and repair such problems using an integrated management protocol, together with a suite of monitoring and debugging tools. There is an optional statistics data recording facility which can be used to record normal and aberrant operation, log problems to the system log facility, and retain records of client access. The <a href="debug.html">NTP Debugging Techniques</a> and <a href="build/hints.html">Hints and Kinks</a> pages contain useful information for identifying problems and devising solutions. In extreme cases, problems can be detected through the use of the <a href="ntpdsim.html"><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a> included in this software distribution.</p> - <p>Users are requested to report bugs, offer suggestions and contribute additions to this distribution. The <a href="build/patches.html">Patching Procedures</a> page suggests procedures which greatly simplify distribution updates, while the <a href="build/porting.html">Porting Hints</a> page suggest ways to make porting this code to new hardware and operating systems easier. Additional information on reference clock driver construction and debugging can be found in the <a href="rdebug.html">Debugging Hints for Reference Clock Drivers</a> page.</p> - <h4 id="prog">Program Manual Pages</h4> - <ul> - <li class="inline"><a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> - <li class="inline"><a href="ntpq.html"><tt>ntpq</tt> - standard NTP query program</a> - <li class="inline"><a href="ntpdc.html"><tt>ntpdc</tt> - special NTP query program</a> - <li class="inline"><a href="ntpdate.html"><tt>ntpdate</tt> - set the date and time via NTP</a> - <li class="inline"><a href="ntptrace.html"><tt>ntptrace</tt> - trace a chain of NTP servers back to the primary source</a> - <li class="inline"><a href="tickadj.html"><tt>tickadj</tt> - set time-related kernel variables</a> - <li class="inline"><a href="ntptime.html"><tt>ntptime</tt> - read kernel time variables</a> - <li class="inline"><a href="keygen.html"><tt>ntp-keygen</tt> - generate public and private keys</a> - <li class="inline"><a href="ntpdsim.html"><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a> - </ul> - <h4 id="docs">Supporting Documentation</h4> - <ul> - <li class="inline"><a href="copyright.html">Copyright Notice</a> - <li class="inline"><a href="notes.html">Notes on Configuring NTP and Setting up a NTP Subnet</a> - <li class="inline"><a href="release.html">NTP Version 4 Release Notes</a> - <li class="inline"><a href="build/build.html">Building and Installing the Distribution</a> - <li class="inline"><a href="build/config.html">Configuration Options</a> - <li class="inline"><a href="refclock.html">Reference Clock Drivers</a> - <li class="inline"><a href="debug.html">NTP Debugging Techniques</a> - <li class="inline"><a href="rdebug.html">Debugging Reference Clock Drivers</a> - <li class="inline"><a href="msyslog.html"><tt>ntpd</tt> System Log Messages</a> - <li class="inline"><a href="build/patches.html">Patching Procedures</a> - <li class="inline"><a href="build/hints.html">Hints and Kinks</a> - <li class="inline"><a href="build/porting.html">Porting Hints</a> - </ul> - <h4 id="back">Background Information</h4> - <ul> - <li class="inline"><a href="http://www.eecis.udel.edu/%7emills/ntp.html">NTP Project and Reference Library</a> - <li class="inline"><a href="http://www.eecis.udel.edu/%7emills/exec.html">Executive Summary - Computer Network Time Synchronization</a> - <li class="inline"><a href="http://www.eecis.udel.edu/%7emills/y2k.html">The Network Time Protocol Timescale and Era Numbering</a> - <li class="inline"><a href="http://www.eecis.udel.edu/%7emills/leap.html">NTP Timescale and Leap Seconds</a> - <li class="inline"><a href="http://www.eecis.udel.edu/%7emills/biblio.html">Protocol Conformance Statement</a> - </ul> - <h4 id="app">Application Notes</h4> - <ul> - <li class="inline"><a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> - <li class="inline"><a href="assoc.html">Association Management</a> - <li class="inline"><a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> - <li class="inline"><a href="measure.html">Time and Time Interval Measurement with Application to Computer and Network Performance Evaluation</a> - <li class="inline"><a href="kern.html">Kernel Model for Precision Timekeeping</a> - </ul> - <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 +<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 -->31-Mar-2014 05:41<!-- #EndDate --> +</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="#hand">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>This distribution is an implementation of RFC-5905 "Network Time Protocol Version 4: Protocol and Algorithms Specification".<br> + 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.</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="hand">The Handbook</h4> +<p>A good deal of tutorial and directive information is available on the handbook pages. These should be read in conjunction with the command and option information available on the pages listed on the sitemap page.</p> +<dl> + <dt><a href="release.html">NTP Version 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></dt> + <dd>Describes automatic server 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 (2000 and later) 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 many 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. </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> diff --git a/contrib/ntp/html/kern.html b/contrib/ntp/html/kern.html index cc23504..b166045 100644 --- a/contrib/ntp/html/kern.html +++ b/contrib/ntp/html/kern.html @@ -1,34 +1,32 @@ <!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 touched the kernel and it exploded.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:40</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links11.txt"></script> - <hr> - <p>The technical report [2], which is a major revision and update of RFC-1589 [3], describes an engineering model for a precision time-of-day function for a generic operating system. The model is based on the principles of disciplined oscillators using phase-lock loops (PLL) and frequency-lock loops (FLL) often found in the engineering literature. The model uses a hybrid PLL/FLL discipline algorithm implemented in the kernel. The algorithm, which is very similar to the algorithm implemented in the NTP daemon, provides automatic time and frequency steering with update intervals from a few seconds to tens of minutes.</p> - <p>The hybrid PLL/FLL code described in [2] is included in Solaris and Digital/Compaq/HP Tru64. It includes 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 available for Linux, FreeBSD, SunOS and Tru64; however, only the Linux and FreeBSD implementations, which do not include licensed code, are readily available. The software and documentation, including a simulator used to verify correct behavior, but not involving licensed code, is available at <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a>.</p> - <p>The model also changes the way the system clock is adjusted in time and frequency relative to an external precision timing source, such as described in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. The NTP software daemon uses the PPS 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>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>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> - </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 -->10-Mar-2014 05:10<!-- #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, Linux and Tru64. The software and documentation, including a simulator used to verify correct behavior, but not involving licensed code, is available in the <a href="ftp://ftp.udel.edu/pub/ntp/software/nanokernel.tar.gz">nanokernel.tar.gz</a> distribution</p> +<p>Ordinarily, the kernel clock discipline function is used with the NTP daemon, but could be used for other purposes. The <a href="ntptime.html"><tt>ntptime</tt></a> utility program can be used to control it manually.</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. Typical results with the PPS signal from a GPS receiver and a modern computer are in the 3 μs range.</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> diff --git a/contrib/ntp/html/kernpps.html b/contrib/ntp/html/kernpps.html new file mode 100644 index 0000000..b7536bd --- /dev/null +++ b/contrib/ntp/html/kernpps.html @@ -0,0 +1,49 @@ +<!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: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:10<!-- #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> diff --git a/contrib/ntp/html/keygen.html b/contrib/ntp/html/keygen.html index 7953eb1..191b714 100644 --- a/contrib/ntp/html/keygen.html +++ b/contrib/ntp/html/keygen.html @@ -1,116 +1,116 @@ <!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> - <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>Alice holds the key.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">22:32</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="294">Monday, November 07, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links9.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#synop">Synopsis</a> - <li class="inline"><a href="#descrip">Description</a> - <li class="inline"><a href="#run">Running the program</a> - <li class="inline"><a href="#trust">Trusted Hosts and Groups</a> - <li class="inline"><a href="#idexp">Identity Schemes</a> - <li class="inline"><a href="#exam">Example</a> - <li class="inline"><a href="#cmd">Command Line Options</a> - <li class="inline"><a href="#rand">Random Seed File</a> - <li class="inline"><a href="#fmt">Cryptographic Data Files</a> - <li class="inline"><a href="#bug">Bugs</a> - </ul> - <hr> - <h4 id="synop">Synopsis</h4> - <p id="intro"><tt>ntp-keygen [ -deGgHIMnPT ] [ -c [RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] [ -i <i>name</i> ] [ -p <i>password</i> ] [ -S [ RSA | DSA ] ] [ -s <i>name</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 identification schemes. It generates MD5 key files used in symmetric key cryptography. In addition, if the OpenSSL software library has been installed, it generates keys, certificate and identity files used in public key cryptography. These files are used for cookie encryption, digital signature and challenge/response identification algorithms compatible with the Internet standard security infrastructure.</p> - <p>By default, files are not encrypted by <tt>ntp-keygen</tt>. The <tt>-p <i>password</i></tt> option specifies the write password and <tt>-q <i>password</i></tt> option the read password for previously encrypted files. The <tt>ntp-keygen</tt> program prompts for the password if it reads an encrypted file and the password is missing or incorrect. If an encrypted file is read successfully and no write password is specified, the read password is used as the write password by default.</p> - <p>The <tt>ntpd</tt> configuration command <tt>crypto pw <i>password</i></tt> specifies the read password for previously encrypted files. The daemon expires on the spot if the password is missing or incorrect. For convenience, if a file has been previously encrypted, the default read password is the name of the host running the program. If the previous write password is specified as the host name, these files can be read by that host with no explicit password.</p> - <p>All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities. File names begin with the prefix <tt>ntpkey_</tt> and end with the postfix <tt><i>_hostname.filestamp</i></tt>, where <tt><i>hostname</i></tt> is usually the string returned by the Unix <tt>gethostname()</tt> routine, and <tt><i>filestamp</i></tt> is the NTP seconds when the file was generated, in decimal digits. This both guarantees uniqueness and simplifies maintenance procedures, since all files can be quickly removed by a <tt>rm ntpkey*</tt> command or all files generated at a specific time can be removed by a <tt>rm *<i>filestamp</i></tt> command. To further reduce the risk of misconfiguration, the first two lines of a file contain the file name and generation date and time as comments.</p> - <p>All files are installed by default in the keys directory <tt>/usr/local/etc</tt>, which is normally in a shared filesystem in NFS-mounted networks. The actual location of the keys directory and each file can be overridden by configuration commands, but this is not recommended. Normally, the 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>Normally, files containing private values, including the host key, sign key and identification parameters, are permitted root read/write-only; while others containing public values are permitted world readable. Alternatively, files containing private values can be encrypted and these files permitted world readable, which simplifies maintenance in shared file systems. Since uniqueness is insured by the hostname and file name extensions, the files for a NFS server and dependent clients can all be installed in the same shared directory.</p> - <p>The recommended practice is to keep the file name extensions when installing a file and to install a soft link from the generic names specified elsewhere on this page to the generated files. This allows new file generations to be activated simply by changing the link. If a link is present, <tt>ntpd</tt> follows it to the file name to extract the filestamp. If a link is not present, <tt>ntpd</tt> extracts the filestamp from the file itself. This allows clients to verify that the file and generation times are always current. The <tt>ntp-keygen</tt> program uses the same extension for all files generated at one time, so each generation is distinct and can be readily recognized in monitoring data.</p> - <h4 id="run">Running the program</h4> - <p>The safest way to run the <tt>ntp-keygen</tt> program is logged in directly as root. The recommended procedure is change to the keys directory, usually <tt>/ust/local/etc</tt>, then run the program. When run for the first time, or if all <tt>ntpkey</tt> files have been removed, the program generates a RSA host key file and matching RSA-MD5 certificate file, which is all that is necessary in many cases. The program also generates soft links from the generic names to the respective files. If run again, the program uses the same host key file, but generates a new certificate file and link.</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. When necessary, a different sign key can be specified and this can be either RSA or DSA type. By default, the message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 and RIPE160 message digest algorithms. However, the scheme specified in the certificate must be compatible with the sign key. Certificates using any digest algorithm are compatible with RSA sign keys; however, only SHA and SHA1 certificates are compatible with DSA sign keys.</p> - <p>Private/public key files and certificates are compatible with other OpenSSL applications and very likely other libraries as well. Certificates or certificate requests derived from them should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identification parameter files, although encoded as the other files, are probably not compatible with anything other than Autokey.</p> - <p>Running the program as other than root and using the Unix <tt>su</tt> command to assume root may not work properly, since by default the OpenSSL library looks for the random seed file <tt>.rnd</tt> in the user home directory. However, there should be only one <tt>.rnd</tt>, most conveniently in the root directory, so it is convenient to define the <tt>$RANDFILE</tt> environment variable used by the OpenSSL library as the path to <tt>/.rnd</tt>.</p> - <p>Installing the keys as root might not work in NFS-mounted shared file systems, as NFS clients may not be able to write to the shared keys directory, even as root. In this case, NFS clients can specify the files in another directory such as <tt>/etc</tt> using the <tt>keysdir</tt> command. There is no need for one client to read the keys and certificates of other clients or servers, as these data are obtained automatically by the Autokey protocol.</p> - <p>Ordinarily, cryptographic files are generated by the host that uses them, but it is possible for a trusted agent (TA) to generate these files for other hosts; however, in such cases files should always be encrypted. The subject name and trusted name default to the hostname of the host generating the files, but can be changed by command line options. It is convenient to designate the owner name and trusted name as the subject and issuer fields, respectively, of the certificate. The owner name is also used for the host and sign key files, while the trusted name is used for the identity files.</p> - <h4 id="trust">Trusted Hosts and Groups</h4> - <p>Each cryptographic configuration involves selection of a signature scheme and identification scheme, called a cryptotype, as explained in the <a href="authopt.html">Authentication Options</a> page. The default cryptotype uses RSA encryption, MD5 message digest and TC identification. First, configure a NTP subnet including one or more low-stratum trusted hosts from which all other hosts derive synchronization directly or indirectly. Trusted hosts have trusted certificates; all other hosts have nontrusted certificates. These hosts will automatically and dynamically build authoritative certificate trails to one or more trusted hosts. A trusted group is the set of all hosts that have, directly or indirectly, a certificate trail ending at a trusted host. The trail is defined by static configuration file entries or dynamic means described on the <a href="manyopt.html">Automatic NTP Configuration Options</a> page.</p> - <p>On each trusted host as root, change to the keys directory. To insure a fresh fileset, remove all <tt>ntpkey</tt> files. Then run <tt>ntp-keygen -T</tt> to generate keys and a trusted certificate. On all other hosts do the same, but leave off the <tt>-T</tt> flag to generate keys and nontrusted certificates. When complete, start the NTP daemons beginning at the lowest stratum and working up the tree. It may take some time for Autokey to instantiate the certificate trails throughout the subnet, but setting up the environment is completely automatic.</p> - <p>If it is necessary to use a different sign key or different digest/signature scheme than the default, run <tt>ntp-keygen</tt> with the <tt>-S</tt><i><tt> type</tt></i> option, where <i><tt>type</tt></i> is either <tt>RSA</tt> or <tt>DSA</tt>. The most often need to do this is when a DSA-signed certificate is used. If it is necessary to use a different certificate scheme than the default, run <tt>ntp-keygen</tt> with the <tt>-c <i>scheme</i></tt> option and selected <i><tt>scheme</tt></i> as needed. If <tt>ntp-keygen</tt> is run again without these options, it generates a new certificate using the same scheme and sign key.</p> - <p>After setting up the environment it is advisable to update certificates from time to time, if only to extend the validity interval. Simply run <tt>ntp-keygen</tt> with the same flags as before to generate new certificates using existing keys. However, if the host or sign key is changed, <tt>ntpd</tt> should be restarted. When ntpd is restarted, it loads any new files and restarts the protocol. Other dependent hosts will continue as usual until signatures are refreshed, at which time the protocol is restarted.</p> - <h4 id="idexp">Identity Schemes</h4> - <p>As mentioned on the Autonomous Authentication page, the default TC identity scheme is vulnerable to a middleman attack. However, there are more secure identity schemes available, including PC, IFF, GQ and MV described on the <a href="http://www.eecis.udel.edu/%7emills/keygen.html">Identification Schemes</a> page. These schemes are based on a TA, one or more trusted hosts and some number of nontrusted hosts. Trusted hosts prove identity using values provided by the TA, while the remaining hosts prove identity using values provided by a trusted host and certificate trails that end on that host. The name of a trusted host is also the name of its sugroup and also the subject and issuer name on its trusted certificate. The TA is not necessarily a trusted host in this sense, but often is.</p> - <p>In some schemes there are separate keys for servers and clients. A server can also be a client of another server, but a client can never be a server for another client. In general, trusted hosts and nontrusted hosts that operate as both server and client have parameter files that contain both server and client keys. Hosts that operate only as clients have key files that contain only client keys.</p> - <p>The PC scheme supports only one trusted host in the group. On trusted host <i>alice</i> run <tt>ntp-keygen -P -p <i>password</i></tt> to generate the host key file <tt>ntpkey_RSAkey_<i>alice.filestamp</i></tt> and trusted private certificate file <tt>ntpkey_RSA-MD5_cert_<i>alice.filestamp</i></tt>. Copy both files to all group hosts; they replace the files which would be generated in other schemes. On each host <i>bob</i> install a soft link from the generic name <tt>ntpkey_host_<i>bob</i></tt> to the host key file and soft link <tt>ntpkey_cert_<i>bob</i></tt> to the private certificate file. Note the generic links are on <i>bob</i>, but point to files generated by trusted host <i>alice</i>. In this scheme it is not possible to refresh either the keys or certificates without copying them to all other hosts in the group.</p> - <p>For the IFF scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host <i>alice</i> run <tt>ntp-keygen -T </tt><tt>-I -p <i>password</i></tt> to produce her parameter file <tt>ntpkey_IFFpar_<i>alice.filestamp</i></tt>, which includes both server and client keys. Copy this file to all group hosts that operate as both servers and clients and install a soft link from the generic <tt>ntpkey_iff_<i>alice</i></tt> to this file. If there are no hosts restricted to operate only as clients, there is nothing further to do. As the IFF scheme is independent of keys and certificates, these files can be refreshed as needed.</p> - <p>If a rogue client has the parameter file, it could masquerade as a legitimate server and present a middleman threat. To eliminate this threat, the client keys can be extracted from the parameter file and distributed to all restricted clients. After generating the parameter file, on <i>alice</i> run <tt>ntp-keygen</tt> <tt>-e</tt> and pipe the output to a file or mail program. Copy or mail this file to all restricted clients. On these clients install a soft link from the generic <tt>ntpkey_iff_<i>alice</i></tt> to this file. To further protect the integrity of the keys, each file can be encrypted with a secret password.</p> - <p>For the GQ scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host <i>alice</i> run <tt>ntp-keygen -T </tt><tt>-G -p <i>password</i></tt> to produce her parameter file <tt>ntpkey_GQpar_<i>alice.filestamp</i></tt>, which includes both server and client keys. Copy this file to all group hosts and install a soft link from the generic <tt>ntpkey_gq_<i>alice</i></tt> to this file. In addition, on each host <i>bob</i> install a soft link from generic <tt>ntpkey_gq_<i>bob</i></tt> to this file. As the GQ scheme updates the GQ parameters file and certificate at the same time, keys and certificates can be regenerated as needed.</p> - <p>For the MV scheme, proceed as in the TC scheme to generate keys and certificates for all group hosts. For illustration assume <i>trish</i> is the TA, <i>alice</i> one of several trusted hosts and <i>bob</i> one of her clients. On TA <i>trish</i> run <tt>ntp-keygen </tt><tt>-V <i>n</i> -p <i>password</i></tt>, where <i>n</i> is the number of revokable keys (typically 5) to produce the parameter file <tt>ntpkeys_MVpar_<i>trish.filestamp </i></tt>and client key files <tt>ntpkeys_MVkey<i>d</i>_<i>trish.filestamp</i></tt> where <i><tt>d</tt></i> is the key number (0 < <i><tt>d</tt></i> < <i>n</i>). Copy the parameter file to <i>alice</i> and install a soft link from the generic <tt>ntpkey_mv_<i>alice</i></tt> to this file. Copy one of the client key files to <i>alice</i> for later distribution to her clients. It doesn't matter which client key file goes to <i>alice</i>, since they all work the same way. <i>Alice</i> copies the client key file to all of her cliens. On client <i>bob</i> install a soft link from generic <tt>ntpkey_mvkey_<i>bob </i></tt>to the client key file. As the MV scheme is independent of keys and certificates, these files can be refreshed as needed.</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> - <dd>Select certificate 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>. - <dt><tt>-d</tt> - <dd>Enable debugging. This option displays the cryptographic data produced in eye-friendly billboards. - <dt><tt>-e</tt> - <dd>Write the IFF client keys to the standard output. This is intended for automatic key distribution by mail. - <dt><tt>-G</tt> - <dd>Generate parameters and keys for the GQ identification scheme, obsoleting any that may exist. - <dt><tt>-g</tt> - <dd>Generate keys for the GQ identification scheme using the existing GQ parameters. If the GQ parameters do not yet exist, create them first. - <dt><tt>-H</tt> - <dd>Generate new host keys, obsoleting any that may exist. - <dt><tt>-I</tt> - <dd>Generate parameters for the IFF identification scheme, obsoleting any that may exist. - <dt><tt>-i <i>name</i></tt> - <dd>Set the suject name to <i>name</i>. This is used as the subject field in certificates and in the file name for host and sign keys. - <dt><tt>-M</tt> - <dd>Generate MD5 keys, obsoleting any that may exist. - <dt><tt>-P</tt> - <dd>Generate a private certificate. By default, the program generates public certificates. - <dt><tt>-p <i>password</i></tt> - <dd>Encrypt generated files containing private data with <tt><i>password</i></tt> and the DES-CBC algorithm. - <dt><tt>-q</tt> - <dd>Set the password for reading files to <tt><i>password</i></tt>. - <dt><tt>-S [ RSA | DSA ]</tt> - <dd>Generate a new sign key of the designated type, obsoleting any that may exist. By default, the program uses the host key as the sign key. - <dt><tt>-s <i>name</i></tt> - <dd>Set the issuer name to <i>name</i>. This is used for the issuer field in certificates and in the file name for identity files. - <dt><tt>-T</tt> - <dd>Generate a trusted certificate. By default, the program generates a non-trusted certificate. - <dt><tt>-V <i>nkeys</i></tt> - <dd>Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. - </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 library routines. The OpenSSL library uses a designated random seed file for this purpose. The file must be available when starting the NTP daemon and <tt>ntp-keygen</tt> program. If a site supports OpenSSL or its companion OpenSSH, it is very likely that means to do this are already available.</p> - <p>It is important to understand that entropy must be evolved for each generation, for otherwise the random number sequence would be predictable. Various means dependent on external events, such as keystroke intervals, can be used to do this and some systems have built-in entropy sources. Suitable means are described in the OpenSSL software documentation, but are outside the scope of this page.</p> - <p>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 NTP daemon or the <tt>ntp-keygen</tt> program. The NTP daemon will first look for the file using the path specified by the <tt>randfile</tt> subcommand of the <tt>crypto</tt> configuration command. If not specified in this way, or when starting the <tt>ntp-keygen</tt> program, the OpenSSL library will look 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 will look for the <tt>.rnd</tt> file in the user home directory. If the file is not available or cannot be written, the daemon exits with a message to the system log and the program exits with a suitable error message.</p> - <h4 id="priv">Cryptographic Data Files</h4> - <p>All other file formats begin with two lines. The first contains the file name, including the generated host name and filestamp. The second contains the datestamp in conventional Unix <tt>date</tt> format. Lines beginning with <tt>#</tt> are considered comments and ignored by the <i><tt>ntp-keygen </tt></i>program and <tt>ntpd</tt> daemon. Cryptographic values are encoded first using ASN.1 rules, then encrypted if necessary, and finally written PEM-encoded printable ASCII format 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 hte heard 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="ntpdc.html"><tt>ntpq</tt></a> and <a href="ntpq.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 +<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 -->10-Mar-2014 05:11<!-- #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="#descrip">Description</a></li> + <li class="inline"><a href="#run">Running the program</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 ] [ -b <i>modulus</i> ] [ -c [ RSA-MD2 | RSA-MD5 | RSA-SHA + | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ] ] + [ -C <i>cipher</i> ] [-i <i>group</i> ] [ -l <em>days</em>] + [ -m <i>modulus</i> ] [ -p <i>passwd1</i> ] [ -q <i>passwd2</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 and parameters 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. The message digest keys file must be distributed and stored using secure means beyond the scope of NTP itself. Besides the keys used for ordinary NTP associations, additional keys can be defined as passwords for the <tt><a href="ntpq.html">ntpq</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> utility programs.</p> +<p>The remaining generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates generated by this program are 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>Some files used by this program are encrypted using a private password. The <tt>-p</tt> option specifies the password for local encrypted files and the <tt>-q</tt> option the password for encrypted files sent to remote sites. If no password is specified, the host name returned by the Unix <tt>gethostname()</tt> function, normally the DNS name of the host, is used.</p> +<p>The <tt>pw</tt> option of the <tt>crypto</tt> configuration command specifies the read password for previously encrypted local 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>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. The symmetric keys file, normally called <tt>ntp.keys</tt>, is usually installed in <tt>/etc</tt>. Other files and links are usually installed in <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, this is in <tt>/etc</tt>.</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 files. 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 without options, the program uses the existing keys and parameters and generates only a new certificate with new expiration date one year hence.</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 message digest type supported by the OpenSSL library can be specified using the <tt>-c</tt> option.</p> +<dd>The rules say cryptographic media should be generated with proventic filestamps, which means the host should already be synchronized before this program is run. This of course creates a chicken-and-egg problem when the host is started for the first time. Accordingly, the host time should be set by some other means, such as eyeball-and-wristwatch, at least so that the certificate lifetime is within the current year. After that and when the host is synchronized to a proventic source, the certificate should be re-generated.</dd> +<p>Additional information on trusted groups and identity schemes is on the <a href="autokey.html">Autokey Public-Key Authentication</a> page.</p> +<h4 id="cmd">Command Line Options</h4> +<dl> + <dt><tt>-b <i>modulus</i></tt></dt> + <dd>Set the modulus for generating identity keys to <i>modulus</i> bits. The modulus defaults to 256, but can be set from 256 (32 octets) to 2048 (256 octets). Use the larger moduli with caution, as this can consume considerable computing resources and increases the size of authenticated packets.</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 digital signature and message digest scheme. Note that RSA schemes must be used with an 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>-C <i>cipher</i></tt></dt> + <dd>Select the OpenSSL cipher to use for password-protected keys. The <tt>openssl -h</tt> command provided with OpenSSL displays available ciphers. The default without this option is <tt>des-ede3-cbc</tt>.</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>.</dd> + <dt><tt>-G</tt></dt> + <dd>Generate a new encrypted GQ key file for the Guillou-Quisquater (GQ) identity scheme. This option is mutually exclusive with the <tt>-I</tt> and <tt>-V</tt> options.</dd> + <dt><tt>-H</tt></dt> + <dd>Generate a new encrypted RSA public/private host key file.</dd> + <dt><tt>-i <i>group</i></tt></dt> + <dd>Set the optional Autokey group name to <tt><i>group</i></tt>. This is used in the identity scheme parameter file names. In that role, the default is the host name if no group is provided. The group name, if specified using <tt>-i</tt> or using <tt>-s</tt> following an <tt>@</tt> character, is also used in certificate subject and issuer names in the form <tt><i>host</i>@<i>group</i></tt> and should match the group specified via <tt>crypto ident</tt> or <tt>server ident</tt> in ntpd's configuration file.</dd> + <dt><tt>-I</tt></dt> + <dd>Generate a new encrypted IFF key file for the Schnorr (IFF) identity scheme. This option is mutually exclusive with the <tt>-G</tt> and <tt>-V</tt> options.</dd> + <dt><tt>-l <i>days</i></tt></dt> + <dd>Set the lifetime for certificates to <tt><i>days</i></tt>. The default lifetime is one year (365 d).</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). Use the larger moduli with caution, as this can consume considerable computing resources and increases the size of authenticated packets.</dd> + <dt><tt>-M</tt></dt> + <dd>Generate a new keys file containing 10 MD5 keys and 10 SHA keys. An MD5 key is a string of 20 random printable ASCII characters, while a SHA key is a string of 40 random hex digits. The file can be edited using a text editor to change the key type or key content. This option is mutually exclusive with all other option.</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> These include the host, sign and identify key files. By default, the password is the string returned by the Unix <tt>gethostname()</tt> routine.</dd> + <dt><tt>-q <i>passwd</i></tt></dt> + <dd>Set the password for writing encrypted IFF, GQ and MV identity files redirected to <tt>stdout</tt> to <tt><i>passwd.</i></tt> In effect, these files are decrypted with the <tt>-p</tt> password, then encrypted with the <tt>-q</tt> password. By default, the password is the string returned by the Unix <tt>gethostname()</tt> routine.</dd> + <dt><tt>-S [ RSA | DSA ]</tt></dt> + <dd>Generate a new encrypted public/private sign key file 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>.</dd> + <dt><tt>-s <i>host</i>[@<i>group</i>]</tt></dt> + <dd>Specify the Autokey host name, where <tt><i>host</i></tt> is the host name and <tt><i>group</i></tt> is the optional group name. The host name, and if provided, group name are used in <tt><i>host</i>@<i>group</i></tt> form as certificate subject and issuer. Specifying <tt>-s @<i>group</i></tt> is allowed, and results in leaving the host name unchanged, as with <tt>-i <i>group</i></tt>. The group name, or if no group is provided, the host name are also used in the file names of IFF, GQ, and MV identity scheme parameter files. If <tt><i>host</i></tt> is not specified, the default host name is the string returned by the <tt>gethostname()</tt> routine.</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 <tt>nkeys</tt> encrypted server keys for the Mu-Varadharajan (MV) identity scheme. This option is mutually exclusive with the <tt>-I</tt> and <tt>-G</tt> options. 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="fmt">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, <em><tt>key</tt></em> names in generated file names include both upper and lower case characters, while <em><tt>key</tt></em> names in generated link names include only lower case characters. The filestamp is not used in generated link names.</p> +<p>The <em><tt>key</tt></em> name is a string defining the cryptographic key type. 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, client files used for challenges have a <tt>par</tt> subtype, as in the IFF challenge <tt>IFFpar</tt>, while server 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 with given password and finally written in PEM-encoded printable ASCII text preceded and followed by MIME content identifier lines.</p> +<p>The format of the symmetric keys file, ordinarily named <tt>ntp.keys,</tt> is somewhat different than the other files in the interest of backward compatibility. Ordinarily, the file is generated by this program, but it can be constructed and edited using an ordinary text editor.</p> +<div align="center"> + <p><img src="pic/sx5.gif" alt="gif"></p> + <p>Figure 1. Typical Symmetric Key File</p> +</div> +<p>Figure 1 shows a typical symmetric keys file used by the reference implementation. 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 must be <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>. The key type can be changed using an ASCII text editor.</p> +<p> An MD5 key consists of a printable ASCII string less than or equal to 16 characters and terminated by whitespace or a # character. An OpenSSL key consists of a hex-encoded ASCII string of 40 characters, which is truncated as necessary.</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> diff --git a/contrib/ntp/html/ldisc.html b/contrib/ntp/html/ldisc.html deleted file mode 100644 index 428a251..0000000 --- a/contrib/ntp/html/ldisc.html +++ /dev/null @@ -1,47 +0,0 @@ -<!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>Line Disciplines and Streams Modules</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Line Disciplines and Streams Modules</h3> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:40</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links11.txt"></script> - <hr> - <h4>Description</h4> - <p>Most radio and modem clocks used for a primary (stratum-1) NTP server utilize serial ports operating at speeds of 9600 baud or greater. The intrinsic delay and jitter contributed by the serial port hardware and software driver can accumulate up to a millisecond in newer Unix systems and tens of milliseconds in older ones. In order to reduce the effects of delay and jitter, a set of special line disciplines, stream modules and operating system calls (<tt>ioctls</tt>) can be configured in some Unix kernels. These routines intercept special characters or signals provided by the radio or modem clock and save a timestamp for later processing.</p> - <p>The routines provide two important functions. Some insert a timestamp in the receive data stream upon occurance of a designated character or characters at the serial interface. This can be used to timestamp an on-time character produced by a radio clock, for example. Other routines support an application program interface for pulse-per-second (PPS) signals generated by some radio clocks and laboratory instruments. These routines are normally accessed through the PPSAPI application program interface described below.</p> - <p>The routines can be compiled in the kernel in older BSD-derived systems, or installed as System V streams modules and either compiled in the kernel or dynamically loaded when required. In either case, they require minor changes in some kernel files and in the NTP daemon <tt>ntpd</tt>. The streams modules can be pushed and popped from the streams stack using conventional System V streams program primitives. Note that some Unix kernels do not support line disciplines and some do not support System V streams. The routines described here are known to work correctly with the Unix kernels called out in the descriptions, but have not been tested for other kernels.</p> - <h4><tt>tty_clk</tt> Line Discipline/Streams Module</h4> - <p>This routine intercepts characters received from the serial port and passes unchanged all except a set of designated characters to the generic serial port discipline. For each of the exception characters, the character is inserted in the receiver buffer followed by a local timestamp in Unix <tt>timeval</tt> format. Both <tt>select()</tt> and <tt>SIGIO</tt> are supported by the routine. Support for this routine is automatically detected during the NTP build process and interface code compiled as necessary.</p> - <p>There are two versions of the <tt>tty_clk</tt> routine. The <tt>tty_clk.c</tt> line discipline is designed for older BSD systems and is compiled in the kernel. The <tt>tty_clk_STREAMS.c</tt> is designed for System V streams, in which case it can be either compiled in the kernel or dynamically loaded. Since these programs are small, unobtrusive, and do nothing unless specifically enabled by an application program, it probably doesn't matter which version is chosen. Instructions on how to configure and build a kernel supporting either of these routines is in the <tt>README</tt> file in the <tt>./kernel</tt> directory.</p> - <p>The <tt>tty_clk</tt> routine defines a new ioctl <tt>CLK_SETSTR</tt>, which takes a pointer to a string of no more than 32 characters. Until the first <tt>CLK_SETSTR</tt> is performed, the routine will simply pass through characters. Once it is passed a string by <tt>CLK_SETSTR</tt>, any character in that string will be immediately followed by a timestamp in Unix <tt>timeval</tt> format. You can change the string whenever you want by doing another <tt>CLK_SETSTR</tt>. The character must be an exact, 8 bit match. The character '\000' cannot, be used, as it is the string terminator. Passing an empty string to <tt>CLK_SETSTR</tt> turns off timestamping. Passing <tt>NULL</tt> may produce surprising results.</p> - <h4><tt>TIOCDCDTIMESTAMP</tt> ioctl in FreeBSD</h4> - <p>This ioctl is included in FreeBSD 2.2 and later. It causes a timestamp to be inserted in the serial port receive data stream when the data carrier detect (DCD) signal is asserted. This is useful for those radio clocks that indicate the on-time epoch by means of a modem control signal. It is not recommended that this be used for PPS timestamps, as this function is available using the PPS application program interface included in FreeBSD 3.4 and later.</p> - <p>The <tt>TIOCDCDTIMESTAMP</tt> ioctl() is detected and compiled automatically on FreeBSD systems if available. With FreeBSD 2.2 the measured delay between activation of the DCD signal and the time the timestamp is captured on a 66MHz 486DX2 is 19 <font face="Symbol">m</font>s and on a 100MHz Pentium is 6 <font face="Symbol">m</font>s.</p> - <h4><tt>ppsclock</tt>Streams Module (depredated)</h4> - <p>This routine is a streams module which causes a timestamp to be captured when the DCD signal is asserted. It is normally used in connection with a PPS signal generated by some radio clocks. However, it is normally used only by the PPSAPI interface and SunOS 4.1.3 and should be avoided in other contexts. Instructions on how to configure and build a kernel supporting either of these routines is in the <tt>README</tt> file in the <tt>./kernel</tt> directory.</p> - <p>The ppsclock streams module implements the <tt>CIOGETEV</tt> ioctl, which takes a pointer to the structure</p> - <pre> -struct ppsclockev { - struct timeval tv; - u_int serial; -}; -</pre> - <p>The <tt>ppsclock</tt> module is pushed on the streams stack of the serial port connected to the DCD line. At each positive-going edge of the PPS signal, the routine latches the current local timestamp and increments a counter. At each <tt>CIOGETEV</tt> ioctl call, the current values of the timestamp and counter are returned in the <tt>ppsclockev</tt> structure.</p> - <h4><tt>TIOCSPPS</tt> and <tt>TIOCGETPPSEV</tt> ioctls in Solaris</h4> - <p>These ioctls are included in Solaris 2.4 and later. They implement the same function as the <tt>ppsclock</tt> streams module, but are implemented as integrated system calls independent of the streams facility. They are normally used in connection with a pulse-per-second (PPS) signal generated by some radio clocks. However, these ioctls are normally used only by the PPSAPI interface and should be avoided in other contexts. See the Sun documentation for the calling sequence and return values.</p> - <p>Users are cautioned that these ioctls function improperly in Solaris versions prior to 2.8 with patch Generic_108528-02.</p> - <h4><tt>tty_chu</tt> Line Discipline/Streams Module (depredated)</h4> - <p>This routine is a special purpose line discipline for receiving a special timecode broadcast by Canadian time and frequency standard station CHU. It has been removed from the distribution since its function has been replaced by the <a href="drivers/driver7.html">Radio CHU Audio Demodulator/Decoder (type 7)</a> clock driver.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/leap.html b/contrib/ntp/html/leap.html new file mode 100644 index 0000000..8abec14 --- /dev/null +++ b/contrib/ntp/html/leap.html @@ -0,0 +1,24 @@ +<!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 -->10-Mar-2014 05:11<!-- #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 principle, 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 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 seconds 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 available and enabled, at the beginning of the day of the leap event, the leap bits are set by 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 Autokey 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> diff --git a/contrib/ntp/html/manyopt.html b/contrib/ntp/html/manyopt.html deleted file mode 100644 index 83869ca..0000000 --- a/contrib/ntp/html/manyopt.html +++ /dev/null @@ -1,83 +0,0 @@ -<!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 NTP Configuration Options</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Automatic NTP Configuration Options</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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:55</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="275">Tuesday, October 11, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links9.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#bcst">Broadcasting</a> - <li class="inline"><a href="#mcst">Manycasting</a> - <li class="inline"><a href="#orphan">Orphan Mode</a> - <li class="inline"><a href="#opt">Server Discovery Options</a> - </ul> - <hr> - <h4 id="bcst">Broadcasting</h4> - <p>Broadcasting is the simplest way to provide automatic server discovery. It uses the multi-destination paradigm, where the subnet spanning tree is constructed automatically, either by the switches in an Ethernet LAN or the DVMRP or PIM protocols when spanning multiple networks.</p> - <p>A broadcast or multicast server is mobilized by the broadcast configuration command. The addresses can be either from the IPv4 broadcast/mulitcast address family or the IPv6 address family. Multiple broadcast server associations can be specified for a single host.</p> - <p>A host is enabled for broadcast reception using the <tt>broadcastclient</tt> configuration command, with or without the <tt>novolley</tt> option. Upon receiving the first message from a broadcast server, the client mobilizes an ephemeral client association and exchanges a volley of client/server messages in order to quickly authenticate the source, set the clock and measure the propagation delay, then reverts to listen-only mode. A multicast client is mobilized in the same way using the <tt>multicastclient</tt> configuration command and specified multicast group address.</p> - <p>Broadcasting can be used with either symmetric key or public key cryptography. Public key cryptography offers the best protection against compromised keys and is generally considered stronger. By default, either of these two means is required, but this can be overridden by the <tt>disable auth</tt> command.</p> - <p>In both broadcast and multicast client operations the client association is demobilized in case of error or timeout due to loss of server or connectivity. </p> - <h4 id="mcst">Manycasting</h4> - <p>Manycasting is a automatic 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. The intended result is that each client mobilizes associations with a given number of the "best" nearby servers, yet automatically reconfigures to sustain this number of servers should one or another fail.</p> - <p>Note that the manycast paradigm does not coincide with 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>Manycasting can be used with either symmetric key or public key cryptography. Public key cryptography offers the best protection against compromised keys and is generally considered stronger. By default, either of these two means is required, but this can be overridden by the <tt>disable auth</tt> command.</p> - <p>A manycast client association is configured using the <tt>manycastclient</tt> configuration command, which is similar to the <tt>server</tt> configuration command, but with a broadcast or multicast address. Depending on address family. The manycast client sends ordinary client mode messages, but with a broadcast address rather than a unicast address. It sends only if less than a given threshold of servers have been found and then only at the minimum feasible rate and minimum feasible time-to-live (TTL) hops. There can be as many manycast client associations as different broadcast addresses, each one serving as a template for a future unicast client/server association.</p> - <p>Manycast servers configured with the <tt>manycastserver</tt> command listen 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 to the manycast client message 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. The client runs the NTP mitigation algorithms, which act to demobilize all but a threshold number of associations according to stratum and synchronization distance. The surviving associations then continue in ordinary client/server mode.</p> - <p>If for some reason the number of available servers falls below the threshold, the manycast client resumes sending broadcast messages. 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. The strategy is determined by the <tt>tos</tt> and <tt>ttl</tt> configuration commands described below.</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 group address will automatically organize themselves in an optimum configuration based on stratum and synchronization distance.</p> - <p>For example, consider an NTP subnet of two primary servers and several secondary servers and a number of dependent clients. With twoAll servers and clients have identical configuration files including both <tt>multicastclient</tt> and <tt>multicastserver</tt> commands using, for instance, multicast group address 239.1.1.1. Each primary server configuration file must include commands for the primary reference source such as a GPS receiver.</p> - <p>The remaining configuration files for all secondary servers and clients have the same contents, except for the <tt>tos</tt> command, which is specific for each stratum level. For stratum 1 and stratum 2 servers, that command is not necessary. For stratum 3 and above servers the <tt>tos floor</tt> value is set to the intended stratum number. Thus, all stratum 3 configuration files use <tt>tos floor 3</tt>, all stratum 4 files use <tt>tos floor 4</tt> and so forth.</p> - <p>Once operations have stabilized, the primary servers will find the primary reference source and each other, since they both operate at the same stratum (1), but not with any secondary server or client, since these operate at a higher stratum. The secondary servers will find the servers at the same stratum level. If one of the primary servers loses its GPS receiver, it will continue to operate as a client and other clients will time out the corresponding association and re-associate accordingly.</p> - <h4 id="orphan">Orphan Mode</h4> - <p>Sometimes it is necessary to operate an NTP subnet in isolation, because a local reference clock is unavailable or connectivity to the Internet is not provided. 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, which could be configured for a server that could be reached, directly or indirectly from all other servers and clients in the subnet.</p> - <p>There are many disadvantages using the local clock driver: multiple source redundancy is not possible and the subnet is vulnerable to single-point failures. Orphan mode is intended to replace the need for the local clock driver. It operates in subnet configurations in all modes, including broadcast, and multiple servers and clients and handles seamless switching as primary sources fail and recover.</p> - <p>A server or client 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 ordinary Internet servers. This is the same consideration that guides the local clock driver stratum.</p> - <p>As long as the stratum of any orphan is less than the orphan stratum, the servers and clients operate in the normal way. However, if the stratum equals or exceeds this stratum, the server or client is considered an orphan. If under these conditions a host has no sources of the same or lower stratum, it is designated an orphan parent; otherwise, it is considered an orphan child. Orphan parents show offset zero, root delay zero and reference ID 127.0.0.1, which of course is the Unix loopback address. Orphan children show the mitigated offset of their servers, root delay randomized over a moderate range and reference ID of their system peer. An important distinction is that the entire subnet operates at the same orphan stratum and that the order of preference is the root delay, not the stratum and root distance as usual.</p> - <p>For the most flexible and reliable operation, all servers and clients in the subnet should include the <tt>orphan</tt> command in the configuration file and with the same orphan stratum. This provides mutual redundancy and diversity for all NTP modes of operation, including broadcast.</p> - <p>For example, consider the case where several campus secondary (stratum 2) servers are configured for public Internet primary servers and with each other using symmetric modes. These servers provide synchronization with a number of department servers using broadcast mode, where each of these servers is configured as both a broadcast server and broadcast client. Individual workstations on the department LAN are configured as broadcast clients only. All servers (not necessarily the clients) have the <tt>orphan 5</tt> command, for example.</p> - <p>In normal operation all servers and clients operate below stratum 5, so operate with the subnet configuration determined by stratum and root distance. If all sources are lost at any stratum level, the server or client continues operation as orphan parent. However, if sources at the orphan stratum are found, the host synchronizes to the source with lowest root delay. Since orphan root delay is determined randomly at startup, loops are avoided, even in broadcast modes where multiple servers are available.</p> - <h4 id="opt">Server Discovery Options</h4> - <dl> - <dt><tt>tos [ ceiling <i>ceiling</i> | cohort {0 | 1} | floor <i>floor</i> | orphan <i>orphan</i> | maxdistance <i>maxdistance</i> | minclock <i>minclock</i> | minsane <i>minsane</i> ]</tt> - <dd>This command affects the clock selection and clustering algorithms. It can be used to select the quality and quantity of peers used to synchronize the system clock and is most useful in manycast mode. The variables operate as follows: - <dl> <dt><tt>beacon <i>beacon</i></tt> - <dd>The manycast server sends packets at intervals of 64 s if less than <i><tt>maxclock</tt></i> servers are available. Otherwise, it sends packets at the <i><tt>beacon</tt></i> interval in seconds. The default is 3600 s.<dt><tt>ceiling <i>ceiling</i></tt> - <dd>Servers with stratum at or above <i>ceiling</i> will be discarded if there are at least <i><tt>minclock</tt></i> peers remaining. This value defaults to 15, but can be changed to any number from 1 to 15. - <dt><tt>cohort { 0 | 1 }</tt> - <dd>This is a binary flag which enables (0) or disables (1) manycast server replies to manycast clients with the same stratum level. This is useful to reduce implosions where large numbers of clients with the same stratum level are present. The default is to enable these replies. - <dt><tt>floor <i>floor</i></tt> - <dd>Peers with strata below <i>floor</i> will be discarded if there are at least <i>minclock</i> peers remaining. This value defaults to 1, but can be changed to any number from 1 to 15. - <dt><tt>orphan <i>stratum</i></tt> - <dd>If <tt><i>stratum</i></tt> is set at some value less than 16 a special orphan mode is enterred when no outside source of synchronization is available. To use orphan mode a number of participants are identically configured both as broadcast client and as broadcast server. One or more participants are configured to use an outside source, either a reference clock or another Internet server. When the source or sources fail, the system stratum is set at <tt><i>stratum</i></tt> and a leader is elected to serve as the reference source. When an outside source of synchronization is again available, the orphan mode is disabled.<dt><tt>mindist <i>mindistance</i></tt> - <dd>The slection algorithm normally pads each intersection a minimum of one millisecond to avoid needless classification. In some cases, such as reference clocks with high jitter and a PPS signal, it is useful to increase the padding. This command can be used for that purpose. As a general rule, set the mindistance to the maximum expected offset plus the maxiumum expected jitter, in seconds. - <dt><tt>maxdist <i>maxdistance</i></tt> - <dd>The selection algorithm accumulates a number of packets before setting the clock in order to use the best data available. The number is determined by the synchronization distance for each association and a limit called the distance threshold. The synchronization distance starts at 16, then drops by a factor of about two as each packet is received. The default distance threshold is 1.0, which usually results in four packets. Setting maxdistance to some value between 1 and 16 can be used to change the number of packets required. For instance, setting it to 16 will set the clock on the first packet received; howver, setting it to this value essentially disables the mitigation and grooming algorithms. - <dt><tt>minclock <i>minclock</i></tt> - <dd>The clustering algorithm repeatedly casts out outlyer associations until no more than <i>minclock</i> associations remain. This value defaults to 3, but can be changed to any number from 1 to the number of configured sources. - <dt><tt>minsane <i>minsane</i></tt> - <dd>This is the minimum number of candidates available to the clock selection algorithm in order to produce one or more truechimers for the clustering algorithm. If fewer than this number are available, the clock is undisciplined and allowed to run free. The default is 1 for legacy purposes. However, according to principles of Byzantine agreement, <i>minsane</i> should be at least 4 in order to detect and discard a single falseticker. - </dl> - - <dt><tt>ttl <i>hop</i> ...</tt> - <dd>This command specifies a list of TTL values in increasing order. up to 8 values can be specified. In manycast mode these values are used in turn in an expanding-ring search. The default is eight multiples of 32 starting at 31. - </dl> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/measure.html b/contrib/ntp/html/measure.html deleted file mode 100644 index 9cce97a..0000000 --- a/contrib/ntp/html/measure.html +++ /dev/null @@ -1,23 +0,0 @@ -<!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>Time and Time Interval Measurement with Application to Computer and Network Performance Evaluation</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Time and Time Interval Measurement with Application to Computer and Network Performance Evaluation</h3> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:41</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <hr> - <p>The technical memorandum: <cite>Time and Time Interval Measurement with Application to Computer and Network Performance Evaluation</cite><a href="http://www.eecis.udel.edu/%7emills/database/memos/memo96a.ps">(PostScript) </a>describes a number of techniques for conducting experiments typical of computer network and transmission systems engineering.</p> - <p>In most experiments in which time is involved, it is necessary to develop estimates of time, frequency and measurement errors from a series of time measurements between the clocks of a number of computers and ancillary devices interconnected by some kind of computer network. However, time is not a physical quantity, such as mass, nor can it be measured relative to an absolute frame of reference, such as velocity. The only way to measure time in our universe is to compare the reading of one clock, which runs according to its own timescale, with another clock, which runs according to a given timescale, at some given instant or epoch. The errors arise from the precision of time comparisons and the accuracy of frequency estimates between the timescales involved.</p> - <p>The usual data collected during a performance run of some experiment might include time offsets, time delays, frequency offsets and various error statistics. While time offsets between two clocks can be measured directly, frequency offsets can be estimated only from two or more time offsets made over some time interval in the experiment. In practice, a sequence of time comparisons can be performed over the lifetime of the experiment and the instantaneous frequency estimated either in real time with a recurrence relation, or retrospectively with a polynomial fit to the data.</p> - <p>Estimating time and frequency errors in real time has been studied by a distinct subspecies of physicists who have made a career of the technology involved. Various means including autoregressive models, Kalman filters and simple weighted-average algorithms are used extensively by national standards laboratories to model cesium-clock ensembles. These techniques have been adapted to computer network and transmission engineering problems as well. This memorandum explores issues in performing experiments of this type and summarizes various techniques found useful in practice.</p> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html>
\ No newline at end of file diff --git a/contrib/ntp/html/miscopt.html b/contrib/ntp/html/miscopt.html index 54041b1..ac32419 100644 --- a/contrib/ntp/html/miscopt.html +++ b/contrib/ntp/html/miscopt.html @@ -1,123 +1,182 @@ <!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> - - <body> - <h3>Miscellaneous Options</h3> - <img src="pic/boom3.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a> - <p>We have three, now looking for more.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:50</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="271">Monday, January 09, 2006</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <hr> - <dl> - <dt><tt>broadcastdelay <i>seconds</i></tt> - <dd>The broadcast and multicast modes require a special calibration to determine the network delay between the local and remote servers. Ordinarily, this is done automatically by the initial protocol exchanges between the client and server. In some cases, the calibration procedure may fail due to network or server access controls, for example. This command specifies the default delay to be used under these circumstances. Typically (for Ethernet), a number between 0.003 and 0.007 seconds is appropriate. The default when this command is not used is 0.004 seconds. - <dt><tt>calldelay <i>delay</i></tt> - <dd>This option controls the delay in seconds between the first and second packets sent in burst or iburst mode to allow additional time for a modem or ISDN call to complete. - <dt><tt>driftfile <i>driftfile</i> [<i> - minutes </i> [<i> tolerance </i>] ]</tt> - <dd>This command specifies the complete path and name of the file used to record the frequency of the local clock oscillator. This is the same operation as the <tt>-f</tt> command linke option. If the file exists, it is read at startup in order to set the initial frequency and then updated once per hour with the current frequency computed by the daemon. If the file name is specified, but the file itself does not exist, the starts with an initial frequency of zero and creates the file when writing it for the first time. If this command is not given, the daemon will always start with an initial frequency of zero. - <p>The file format consists of a single line containing a single floating point number, which records the frequency offset measured in parts-per-million (PPM). The file is updated by first writing the current drift value into a temporary file and then renaming this file to replace the old version. This implies that <tt>ntpd</tt> must have write permission for the directory the drift file is located in, and that file system links, symbolic or otherwise, should be avoided.</p> - -<p>The two optional values determine how often the file is written, and -are particuarly useful when is it desirable to avoid spinning up the -disk unnecessarily. The parameter <tt>minutes</tt> is how often the file will be written. If omitted or less -than 1, the interval will be 60 minutes (one hour). The parameter <tt>tolerance</tt> is the -threshold to skip writing the new value. If the new value is within -<tt>tolerance</tt> percent of the last value written (compared out to 3 -decimal places), the write will be -skipped. The default is 0.0, which means that the write will occur -unless the current and previous values are the same. A tolerance of -.1 equates roughly to a difference in the 2nd decimal place.</p> -<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>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 the <a href="ntpdc.html"><tt>ntpdc</tt></a> utility program. - <dl> - <dt><tt>auth</tt> - <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. - <dt><tt>bclient</tt> - <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. - <dt><tt>calibrate</tt> - <dd>Enables the calibrate feature for reference clocks. The default for this flag is disable. - <dt><tt>kernel</tt> - <dd>Enables the kernel time discipline, if available. The default for this flag is enable if support is available, otherwise disable. - <dt><tt>monitor</tt> - <dd>Enables the monitoring facility. See the <tt>ntpdc</tt> program and the <tt>monlist</tt> command or further information. The default for this flag is enable. - <dt><tt>ntp</tt> - <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. - <dt><tt>pps</tt> - <dd>Enables the pulse-per-second (PPS) signal when frequency and time is disciplined by the precision time kernel modifications. See the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page for further information. The default for this flag is disable. - <dt><tt>stats</tt> - <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 - </dl> - <dt><tt>includefile <i>includefile</i></tt> - <dd>This command allows additional configuration commands to be included from a separate file. Include files may be nested to a depth of five; upon reaching the end of any include file, command processing resumes in the previous configuration file. This option is useful for sites that run <tt>ntpd</tt> on multiple hosts, with (mostly) common options (e.g., a restriction list). - <dt><tt>logconfig <i>configkeyword</i></tt> - <dd>This command controls the amount and type of output written to the system <tt>syslog</tt> facility or the alternate <tt>logfile</tt> log file. All <i><tt>configkeyword</tt></i> keywords can be prefixed with <tt>=</tt>, <tt>+</tt> and <tt>-</tt>, where <tt>=</tt> sets the <tt>syslogmask</tt>, <tt>+</tt> adds and <tt>-</tt> removes messages. <tt>syslog messages</tt> can be controlled in four classes (<tt>clock</tt>, <tt>peer</tt>, <tt>sys</tt> and <tt>sync</tt>). Within these classes four types of messages can be controlled: informational messages (<tt>info</tt>), event messages (<tt>events</tt>), statistics messages (<tt>statistics</tt>) and status messages (<tt>status</tt>). - <p>Configuration keywords are formed by concatenating the message class with the event class. The <tt>all</tt> prefix can be used instead of a message class. A message class may also be followed by the <tt>all</tt> keyword to enable/disable all messages of the respective message class. By default, <tt>logconfig</tt> output is set to <tt>allsync</tt>. - <p>Thus, a minimal log configuration could look like this:</p> - <p><tt>logconfig=syncstatus +sysevents</tt></p> - <dl> - <dd> - <p>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:</p> - - </dl> - - <dd> - <p><tt>logconfig=allsync +allclock</tt></p> - <dl> - <dd> - <p>This configuration will list all clock information and synchronization information. All other events and messages about peers, system events and so on is suppressed.</p> - - </dl> - <dt><tt>logfile <i>logfile</i></tt> - <dl> - <dd> - <p>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.</p> - - </dl> - <dt><tt>phone <i>dial</i>1 <i>dial</i>2 ...</tt> - <dl> - <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. - </dl> - <dt><tt>setvar <i>variable</i> [default]</tt> - <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. - <dt><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> - <dd>This command can be used to alter several system variables in very exceptional circumstances. It should occur in the configuration file before any other configuration options. The default values of these variables have been carefully optimized for a wide range of network speeds and reliability expectations. In general, they interact in intricate ways that are hard to predict and some combinations can result in some very nasty behavior. Very rarely is it necessary to change the default values; but, some folks can't resist twisting the knobs anyway and this command is for them. Emphasis added: twisters are on their own and can expect no help from the support group. - <p>The variables operate as follows:</p> - <dl> - <dt><tt>allan <i>allan</i></tt> - <dd>The argument becomes the new value for the Allan intercept, which is a parameter of the PLL/FLL clock discipline algorithm. The value is in seconds with default 1500 s, which is appropriate for most computer clocks.<dt><tt>dispersion <i>dispersion</i></tt> - <dd>The argument becomes the new value for the dispersion increase rate, normally .000015 s/s. - <dt><tt>freq <i>freq</i></tt> - <dd>The argument becomes the initial value of the frequency offset in parts-per-million. This overrides the value in the frequency file, if present, and avoids the initial training state if it is not. - <dt><tt>huffpuff <i>huffpuff</i></tt> - <dd>The argument becomes the new value for the experimental 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). There is no default, since the filter is not enabled unless this command is given. - <dt><tt>panic <i>panic</i></tt> - <dd>The argument is the panic threshold, by default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted. - <dt><tt>step <i>step</i></tt> - <dd>The argument is the step threshold, by default 0.128 s. It can be set to any positive number in seconds. 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 the default. - <dt><tt>stepout <i>stepout</i></tt> - <dd>The argument is the stepout timeout, by default 900 s. It can be set to any positive number in seconds. If set to zero, the stepout pulses will not be suppressed. - </dl> - <dt><tt>trap <i>host_address</i> [port <i>port_number</i>] [interface <i>interface_address</i>]</tt> - <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. - <p>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.</p> - <dt><tt>ttl <i>hop</i> ...</tt> - <dd>This command specifies a list of TTL values in increasing order. up to 8 values can be specified. In manycast mode these values are used in turn in an expanding-ring search. The default is eight multiples of 32 starting at 31. - </dl> - <h4>Files</h4> - <tt>ntp.drift</tt> frequency compensation (PPM) - <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"> +<title>Miscellaneous Commands and Options</title> +<!-- Changed by: Harlan Stenn, 29-Jun-2015 --> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<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 -->29-Jun-2015 05: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> +<h4>Commands and Options</h4> +<dl> + <dt id="broadcastdelay"><tt>broadcastdelay <i>delay</i></tt></dt> + <dd>In broadcast and multicast modes, means are required to determine the network delay between the server and client. Ordinarily, this is done automatically by the initial calibration exchanges between the client and server. In some cases, the exchange might not be possible due to network or server access controls. The value of <em><tt>delay</tt></em> is by default zero, in which case the exchange is enabled. If <em><tt>delay</tt></em> is greater than zero, it becomes the roundtrip delay (s), as measured by the Unix <tt>ping</tt> program, and the exchange is disabled. </dd> + <dt> </dt> + <dt id="driftfile"><tt>driftfile <i>driftfile</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. This command is mutually exclusive with the <tt>freq</tt> option of the <tt>tinker</tt> command.</dd> + <dd> 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.</dd> + <dt id="dscp"><tt>dscp <i>dscp</i></tt></dt> + <dd>This command specifies the Differentiated Services Code Point (DSCP) value that is used in sent NTP packets. The default value is 46 for Expedited Forwarding (EF).</dd> + <dt id="enable"><tt>enable [auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats]</tt><br> + <tt>disable [auth | bclient | calibrate | kernel | mode7 | monitor | ntp | stats]</tt></dt> + <dd>Provides a way to enable or disable various system options. Flags not mentioned are unaffected. Note that most of these flags can be modified remotely using <a href="ntpq.html"><tt>ntpq</tt></a> utility program's <tt>:config</tt> and <tt>config-from-file</tt> commands. + <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>mode7</tt></dt> + <dd>Enables processing of NTP mode 7 implementation-specific requests which are used by the deprecated <tt>ntpdc</tt> program. The default for this flag is disable. This flag is excluded from runtime configuration using <tt>ntpq</tt>. The <tt>ntpq</tt> program provides the same capabilities as <tt>ntpdc</tt> using standard mode 6 requests.</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 enabled. This flag is excluded from runtime configuration using <tt>ntpq</tt>.</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>The <i>leapfile</i> is scanned when <tt>ntpd</tt> processes the <tt>leapfile</tt> directive or when <tt>ntpd</tt> detects that <i>leapfile</i> has changed. <tt>ntpd</tt> checks once a day to see if the <i>leapfile</i> has changed.</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="leapsmearinterval"><tt>leapsmearinterval <i>seconds</i></tt></dt> + <dd>This EXPERIMENTAL option is only available if <tt>ntpd</tt> was built with the <tt>--enable-leap-smear</tt> option to the <tt>configure</tt> script. It specifies the interval over which a leap second correction will be applied. Recommended values for this option are between 7200 (2 hours) and 86400 (24 hours). <b>DO NOT USE THIS OPTION ON PUBLIC-ACCESS SERVERS!</b> See http://bugs.ntp.org/2855 for more information.</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="nonvolatile"><tt>nonvolatile <i>threshold</i></tt></dt> + <dd>Specify the <i><tt>threshold</tt></i> in seconds to write the frequency file, with default of 1e-7 (0.1 PPM). The frequency file is inspected each hour. If the difference between the current frequency and the last value written exceeds the threshold, the file is written and the <tt><em>threshold</em></tt> becomes the new threshold value. If the threshold is not exceeded, it is reduced by half. This is intended to reduce the frequency of unnecessary file writes for embedded systems with nonvolatile memory.</dd> + <dt id="phone"><tt>phone <i>dial</i> ...</tt></dt> + <dd>This command is used in conjunction with the ACTS modem driver (type 18). The arguments consist of a maximum of 10 telephone numbers used to dial USNO, NIST or European time services. The Hayes command ATDT is normally prepended to the number, which can contain other modem control codes as well.</dd> + <dt id="reset"><tt>reset [allpeers] [auth] [ctl] [io] [mem] [sys] [timer]</tt></dt> + <dd>Reset one or more groups of counters maintained by ntpd and exposed by <tt>ntpq</tt> and <tt>ntpdc</tt>.</dd> + <dt id="rlimit"><tt>rlimit [memlock <i>Nmegabytes</i> | stacksize <i>N4kPages</i> | filenum <i>Nfiledescriptors</i>]</tt></dt> + <dd>This command alters certain process storage allocation limits, and is only available on some operating systems. Options are as follows:</dd> + <dd> + <dl> + <dt><tt>memlock <i>Nmegabytes</i></tt></dt> + <dd>Specify the number of megabytes of memory that can be allocated. Probably only available under Linux, this option is useful when dropping root (the <tt>-i</tt> option). The default is 32 megabytes. Setting this to zero will prevent any attemp to lock memory.</dd> + <dt><tt>stacksize <i>N4kPages</i></tt></dt> + <dd>Specifies the maximum size of the process stack on systems with the <tt>mlockall()</tt> function. Defaults to 50 4k pages (200 4k pages in OpenBSD).</dd> + <dt><tt>filenum <i>Nfiledescriptors</i></tt></dt> + <dd>Specifies the maximum number of file descriptors ntp may have open at the same time. Defaults to system default.</dd> + </dl> + </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. 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). This option is mutually exclusive with the driftfile command.</dd> + <dt><tt>huffpuff <i>huffpuff</i></tt></dt> + <dd>Specifies 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 min), but a more reasonable value is 7200 (2 hours).See the <a href="huffpuff.html">Huff-n'-Puff Filter</a> page for further information.</dd> + <dt><tt>panic <i>panic</i></tt></dt> + <dd>Specifies 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>Specifies 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. Further details are on the <a href="clock.html">Clock State Machine</a> page.</dd> + <dt><tt>stepout <i>stepout</i></tt></dt> + <dd>Specifies the stepout threshold in seconds. The default without this command is 300 s. Since this option also affects the training and startup intervals, it should not be set less than the default. Further details are on the <a href="clock.html">Clock State Machine</a> page.</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="discover.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="discover.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="discover.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="discover.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="discover.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="orphan.html">Orphan Mode</a> page for further details.</dd> + <dt><tt>orphanwait <em>delay</em></tt></dt> + <dd>Specify the delay in seconds from the time all sources are lost until orphan parent mode is enabled with default 300 s (five minutes). During this period, the local clock driver and the modem driver are not selectable, unless marked with the <tt>prefer</tt> keyword. This allows time for one or more primary sources to become reachable and selectable before using backup sources, and avoids transient use of the backup sources at startup.</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> diff --git a/contrib/ntp/html/monopt.html b/contrib/ntp/html/monopt.html index a4c073a..acf4847 100644 --- a/contrib/ntp/html/monopt.html +++ b/contrib/ntp/html/monopt.html @@ -1,132 +1,566 @@ <!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>Monitoring Options</title> - <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">from <i>Pogo</i>, Walt Kelly</a> - <p>The pig watches the logs.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">00:40</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="290">Sunday, December 24, 2006</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <hr> - <tt>ntpd</tt> includes a comprehensive monitoring facility suitable for continuous, long term recording of server and client timekeeping performance. See the <tt>statistics</tt> command below for a listing and example of each type of statistics currently supported. Statistic files are managed using file generation sets and scripts in the <tt>./scripts</tt> directory of this distribution. Using these facilities and Unix <tt>cron</tt> jobs, the datacan be automatically summarized and archived for retrospective analysis. - <h4>Monitoring Commands</h4> - <dl> - <dt><tt>statistics <i>name</i> [...]</tt> - <dd>Enables writing of statistics records. Currently, six kinds of <i><tt>name</tt></i>statistics are supported. - <dl> - <dt><tt>clockstats</tt> - <dd>Enables recording of clock driver statistics information. Each update received from a clock driver appends a line of the following form to the file generation set named <tt>clockstats</tt>: - <dd><tt>49213 525.624 127.127.4.1 93 226 00:08:29.606 D</tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next field shows the clock address in dotted-quad notation, The final field shows the last timecode received from the clock in decoded ASCII format, where meaningful. In some clock drivers a good deal of additional information can be gathered and displayed as well. See information specific to each clock for further details. - <dt><tt>cryptostats</tt> - <dd>This option requires the OpenSSL cryptographic software library. It enables recording of cryptographic public key protocol information. Each message received by the protocol module appends a line of the following form to the file generation set named <tt>cryptostats</tt>: - <dd><tt>49213 525.624 127.127.4.1 <i>message</i></tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next field shows the peer address in dotted-quad notation, The final <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. - <dt><tt>loopstats</tt> - <dd>Enables recording of loop filter statistics information. Each update of the local clock outputs a line of the following form to the file generation set named <tt>loopstats</tt>: - <dd><tt>50935 75440.031 0.000006019 13.778190 0.000351733 0.0133806 6</tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next five fields show time offset (seconds), frequency offset (parts per million - PPM), RMS jitter (seconds), Allan deviation (PPM) and clock discipline time constant. - <dt><tt>peerstats</tt> - <dd>Enables recording of peer statistics information. This includes statistics records of all peers of a NTP server and of special signals, where present and configured. Each valid update appends a line of the following form to the current element of a file generation set named <tt>peerstats</tt>: - <dt><tt>48773 10847.650 127.127.4.1 9714 -0.001605376 0.000000000 0.001424877 0.000958674</tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next two fields show the peer address in dotted-quad notation and status, respectively. The status field is encoded in hex in the format described in Appendix B of the NTP specification RFC 1305. The final four fields show the offset, delay, dispersion and RMS jitter, all in seconds. - <dt><tt>rawstats</tt> - <dd>Enables recording of raw-timestamp statistics information. This includes statistics records of all peers of a NTP server and of special signals, where present and configured. Each NTP message received from a peer or clock driver appends a line of the following form to the file generation set named <tt>rawstats</tt>: - <dt><tt>50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 02453332.540806000 3102453332.541458000</tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next two fields show the remote peer or clock address followed by the local address in dotted-quad notation, The final four fields show the originate, receive, transmit and final NTP timestamps in order. The timestamp values are as received and before processing by the various data smoothing and mitigation algorithms. - <dt><tt>sysstats</tt> - <dd>Enables recording of <tt>ntpd</tt> statistics counters on a periodic basis. Each hour a line of the following form is appended to the file generation set named <tt>sysstats</tt>: - <dd><tt>50928 2132.543 36000 81965 0 9546 56 71793 512 540 10 147</tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The remaining ten fields show the statistics counter values accumulated since the last generated line. - <dl> - <dt>Time since restart <tt>36000</tt> - <dd>Time in hours since the system was last rebooted. - <dt>Packets received <tt>81965</tt> - <dd>Total number of packets received. - <dt>Packets processed <tt>0</tt> - <dd>Number of packets received in response to previous packets sent - <dt>Current version <tt>9546</tt> - <dd>Number of packets matching the current NTP version. - <dt>Previous version <tt>56</tt> - <dd>Number of packets matching the previous NTP version. - <dt>Bad version <tt>71793</tt> - <dd>Number of packets matching neither NTP version. - <dt>Access denied <tt>512</tt> - <dd>Number of packets denied access for any reason. - <dt>Bad length or format <tt>540</tt> - <dd>Number of packets with invalid length, format or port number. - <dt>Bad authentication <tt>10</tt> - <dd>Number of packets not verified as authentic. - <dt>Rate exceeded <tt>147</tt> - <dd>Number of packets discarded due to rate limitation. - </dl> - <dt><tt>timingstats</tt> - <dd><b>ONLY</b> available when the deamon is compiled with process time debugging support (--enable-debug-timing - costs performance). Enables recording of <tt>ntpd</tt> processing time information for various selected code paths: - <dd><tt>53876 36.920 10.0.3.5 1 0.000014592 input processing delay</tt> - <dd>The first two fields show the date (Modified Julian Day) and time (seconds and fraction past UTC midnight). The next field is a potential <tt>peer address</tt>, <tt>-</tt> or <tt>-REFCLOCK-</tt> depending on the associated io source. Then an event count for the number of processed events in the code path follows. The fifth field is the total time spend for the events. The rest of the line denotes the code path description (see source for more information). - <dt><tt>statsdir <i>directory_path</i></tt> - <dd>Indicates the full path of a directory where statistics files should be created (see below). This keyword allows the (otherwise constant) <tt>filegen</tt> filename prefix to be modified for file generation sets, which is useful for handling statistics logs. - <dt><tt>filegen <i>name</i> [file <i>filename</i>] [type <i>typename</i>] [link | nolink] [enable | disable]</tt> - <dd>Configures setting of generation file set <i>name</i>. Generation file sets provide a means for handling files that are continuously growing during the lifetime of a server. Server statistics are a typical example for such files. Generation file sets provide access to a set of files used to store the actual data. At any time at most one element of the set is being written to. The type given specifies when and how data will be directed to a new element of the set. This way, information stored in elements of a file set that are currently unused are available for administrational operations without the risk of disturbing the operation of <tt>ntpd</tt>. (Most important: they can be removed to free space for new data produced.) - <dd>Note that this command can be sent from the <tt>ntpdc</tt> program running at a remote location. - <dl> - <dt><i><tt>name</tt></i> - <dd>This is the type of the statistics records, as shown in the <tt>statistics</tt> command. - </dl> - <dd><tt>file <i>filename</i></tt> - <dl> - <dd>This is the file name for the statistics records. Filenames of set members are built from three concatenated elements <i><tt>prefix</tt></i>, <i><tt>filename</tt></i> and <i><tt>suffix</tt></i>: - <dl> - <dt><i><tt>prefix</tt></i> - <dd>This is a constant filename path. It is not subject to modifications via the <tt>filegen</tt> option. It is defined by the server, usually specified as a compile-time constant. It may, however, be configurable for individual file generation sets via other commands. For example, the prefix used with <tt>loopstats</tt> and <tt>peerstats</tt> generation can be configured using the <tt>statsdir</tt> option explained above. - <dt><i><tt>filename</tt></i> - <dd>This string is directly concatenated to the prefix mentioned above (no intervening <tt>/</tt> (slash)). This can be modified using the <tt>file</tt> argument to the <tt>filegen</tt> statement. No <tt>..</tt> elements are allowed in this component to prevent filenames referring to parts outside the filesystem hierarchy denoted by <tt>prefix</tt>. - <dt><i><tt>suffix</tt></i> - <dd>This part is reflects individual elements of a file set. It is generated according to the type of a file set. - </dl> - </dl> - <dd><tt>type <i>typename</i></tt> - <dl> - <dd>A file generation set is characterized by its type. The following types are supported: - <dl> - <dt><tt>none</tt> - <dd>The file set is actually a single plain file. - <dt><tt>pid</tt> - <dd>One element of file set is used per incarnation of a <tt>ntpd</tt> server. This type does not perform any changes to file set members during runtime, however it provides an easy way of separating files belonging to different <tt>ntpd</tt> server incarnations. The set member filename is built by appending a <tt>.</tt> (dot) to concatenated <i>prefix</i> and <i>filename</i> strings, and appending the decimal representation of the process ID of the <tt>ntpd</tt> server process. - <dt><tt>day</tt> - <dd>One file generation set element is created per day. A day is defined as the period between 00:00 and 24:00 UTC. The file set member suffix consists of a <tt>.</tt> (dot) and a day specification in the form <tt>YYYYMMdd. YYYY</tt> is a 4-digit year number (e.g., 1992). <tt>MM</tt> is a two digit month number. <tt>dd</tt> is a two digit day number. Thus, all information written at 10 December 1992 would end up in a file named <tt><i>prefix filename</i>.19921210</tt>. - <dt><tt>week</tt> - <dd>Any file set member contains data related to a certain week of a year. The term week is defined by computing day-of-year modulo 7. Elements of such a file generation set are distinguished by appending the following suffix to the file set filename base: A dot, a 4-digit year number, the letter <tt>W</tt>, and a 2-digit week number. For example, information from January, 10th 1992 would end up in a file with suffix <tt>.1992W1</tt>. - <dt><tt>month</tt> - <dd>One generation file set element is generated per month. The file name suffix consists of a dot, a 4-digit year number, and a 2-digit month. - <dt><tt>year</tt> - <dd>One generation file element is generated per year. The filename suffix consists of a dot and a 4 digit year number. - <dt><tt>age</tt> - <dd>This type of file generation sets changes to a new element of the file set every 24 hours of server operation. The filename suffix consists of a dot, the letter <tt>a</tt>, and an 8-digit number. This number is taken to be the number of seconds the server is running at the start of the corresponding 24-hour period. Information is only written to a file generation by specifying <tt>enable</tt>; output is prevented by specifying <tt>disable</tt>. - </dl> - </dl> - <dd><tt>link | nolink</tt> - <dl> - <dd>It is convenient to be able to access the current element of a file generation set by a fixed name. This feature is enabled by specifying <tt>link</tt> and disabled using <tt>nolink</tt>. If <tt>link</tt> is specified, a hard link from the current file set element to a file without suffix is created. When there is already a file with this name and the number of links of this file is one, it is renamed 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. - </dl> - <dd><tt>enable | disable</tt> - <dl> - <dd>Enables or disables the recording function. - </dl> - </dl> - <hr> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </dl> - </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>Monitoring Options</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<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 -->31-Jan-2014 06: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/monopt.txt"></script> +<h4>Table of Contents</h4> +<ul> + <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">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> +<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> +<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> +</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 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>Specifies the filename prefix. The default is the file set type, such as "loopstats".</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 configuration commands.</dd> + </dl> + </dd> + <dt id="statistics"><tt>statistics <i>name</i>...</tt></dt> + <dd>Enables writing of statistics records. Currently, eight kinds of + statistics are supported: <i>name</i>s specify the file set type(s) from + the list in the next section.</dd> + <dt id="statsdir"><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>56285 54575.160 128.4.1.1 192.168.1.5 3565350574.400229473 3565350574.442385200 3565350574.442436000 3565350575.154505763 0 4 4 1 8 -21 0.000000 0.000320 .PPS.</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>56285</tt></td> + <td>MJD</td> + <td>date</td> + </tr> + <tr> + <td><tt>54575.160</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>192.168.1.5</tt></td> + <td>IP</td> + <td>destination address</td> + </tr> + <tr> + <td><tt>3565350574.400229473</tt></td> + <td>NTP s</td> + <td>origin timestamp</td> + </tr> + <tr> + <td><tt>3565350574.442385200</tt></td> + <td>NTP s</td> + <td>receive timestamp</td> + </tr> + <tr> + <td><tt>3565350574.442436000</tt></td> + <td>NTP s</td> + <td>transmit timestamp</td> + </tr> + <tr> + <td><tt>3565350575.154505763</tt></td> + <td>NTP s</td> + <td>destination timestamp</td> + </tr> + <tr> + <td><tt>0</tt></td> + <td>0: OK, 1: insert pending,<br>2: delete pending, 3: not synced</td> + <td>leap warning indicator</td> + </tr> + <tr> + <td><tt>4</tt></td> + <td>4 was current in 2012</td> + <td>NTP version</td> + </tr> + <tr> + <td><tt>4</tt></td> + <td>3: client, 4: server, 5: broadcast</td> + <td>mode</td> + </tr> + <tr> + <td><tt>1</tt></td> + <td>1-15, 16: not synced</td> + <td>stratum</td> + </tr> + <tr> + <td><tt>8</tt></td> + <td>log<sub>2</sub> seconds</td> + <td>poll</td> + </tr> + <tr> + <td><tt>-21</tt></td> + <td>log<sub>2</sub> seconds</td> + <td>precision</td> + </tr> + <tr> + <td><tt>0.000000</tt></td> + <td>seconds</td> + <td>total roundtrip delay to the primary reference clock</td> + </tr> + <tr> + <td><tt>0.000320</tt></td> + <td>seconds</td> + <td>total dispersion to the primary reference clock</td> + </tr> + <tr> + <td><tt>PPS.</tt></td> + <td>IP or text</td> + <td>refid, association ID</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> +</body> </html> diff --git a/contrib/ntp/html/msyslog.html b/contrib/ntp/html/msyslog.html index 9e03cf8..affa088 100644 --- a/contrib/ntp/html/msyslog.html +++ b/contrib/ntp/html/msyslog.html @@ -1,122 +1,129 @@ <!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/alice47.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 mushroom knows all the error codes, which is more than most of us do.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">19:24</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="284">Saturday, October 01, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <p><script type="text/javascript" language="javascript" src="scripts/links7.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. Please report to bugs@ntp.org. - <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. Please report to bugs@ntp.org. - </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 -->10-Mar-2014 05:12<!-- #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> diff --git a/contrib/ntp/html/notes.html b/contrib/ntp/html/notes.html deleted file mode 100644 index e757dbd..0000000 --- a/contrib/ntp/html/notes.html +++ /dev/null @@ -1,280 +0,0 @@ -<!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>Notes on setting up a NTP subnet</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>Notes on setting up a NTP subnet</h3> - <img src="pic/tonea.gif" alt="gif" align="left">From NBS Special Publication 432 (out of print) - <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> - <h4>Introduction</h4> - <p>This document is a collection of notes concerning the use of ntpd and related programs, and on coping with the Network Time Protocol (NTP) in general. It is a major rewrite and update of an earlier document written by Dennis Ferguson of the University of Toronto and includes many changes and additions resulting from the NTP Version 3 specification and new Version 4 implementation features. It supersedes earlier documents, which should no longer be used for new configurations.</p> - <p><tt>ntpd</tt> includes a complete implementation of the NTP Version 3 specification, as defined in:</p> - <ul> - <li>Mills, D.L. Network Time Protocol (Version 3) specification, implementation and analysis. Network Working Group Report RFC-1305, University of Delaware, March 1992, 113 pp. Abstract: <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305a.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305a.pdf">PDF</a>, Body: <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305b.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305b.pdf">PDF</a>, Appendices: <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305c.ps">PostScript</a> | <a href="http://www.eecis.udel.edu/%7emills/database/rfc/rfc1305/rfc1305c.pdf">PDF</a> - </ul> - <p>Additional features have are described for <a href="release.html">NTP Version 4 Release Notes</a>. It also retains compatibility with both NTP Version 2, as defined in RFC-1119, and NTP Version 1, as defined in RFC-1059, although this compatibility is sometimes strained and only semiautomatic. In order to support in principle the ultimate precision of about 232 picoseconds in the NTP specification, <tt>ntpd</tt> uses NTP timestamp format for external communication and double precision floating point arithmetic internally. <tt>ntpd</tt> fully implements NTP Versions 2 and 3 authentication and in addition Version 4 autokey. It supports the NTP mode-6 control message facility along with a private mode-7 control- message facility used to remotely reconfigure the system and monitor a considerable amount of internal detail. As extensions to the specification, a flexible address-and-mask restriction facility has been included.</p> - <p>The code is biased towards the needs of a busy time server with numerous, often hundreds, of clients and other servers. Tables are hashed to allow efficient handling of many associations, though at the expense of additional overhead when the number of associations is small. Many fancy features have been included to permit efficient management and monitoring of a busy primary server, features which are probably excess baggage for a high stratum client. In such cases, a stripped-down version of the protocol, the Simple Network Time Protocol (SNTP) can be used. SNTP and NTP servers and clients can interwork in most situations, as described in: Mills, D.L. Simple Network Time Protocol (SNTP). Network Working Group Report RFC-2030, University of Delaware, October 1996, 14 pp. <a href="http://www.eecis.udel.edu/%7emills/database/rfc2030.txt">(ASCII)</a>.</p> - <p>The code was written with near demonic attention to details which can affect precision and as a consequence should be able to make good use of high performance, special purpose hardware such as precision oscillators and radio clocks. The present code supports a number of radio clocks, including those for the WWV, CHU, WWVB, MSF, DCF77, GOES and GPS radio and satellite time services and USNO, ACTS and PTB modem time services. It also supports the IRIG-B and IRIG-E signal format connected via an audio codec. The server methodically avoids the use of Unix-specific library routines where possible by implementing local versions, in order to aid in porting the code to perverse Unix and non-Unix platforms.</p> - <p>While this implementation conforms in most respects to the NTP Version 3 specification RFC-1305, a number of improvements have been made which are described in the conformance statement in the <a href="http://www.eecis.udel.edu/%7emills/biblio.html">NTP Protocol Conformance Statement</a> page. It has been specifically tuned to achieve the highest accuracy possible on whatever hardware and operating-system platform is available. In general, its precision and stability are limited only by the characteristics of the onboard clock source used by the hardware and operating system, usually an uncompensated crystal oscillator. On modern RISC-based processors connected directly to radio clocks via serial-asynchronous interfaces, the accuracy is usually limited by the radio clock and interface to the order of a millisecond or less. The code includes special features to support a pulse-per-second (PPS) signal and/or an IRIG-B signal generated by some radio clocks. When used in conjunction with a suitable hardware level converter, the accuracy can be improved to a few tens of microseconds. Further improvement is possible using an outboard, stabilized frequency source, in which the accuracy and stability are limited only by the characteristics of that source.</p> - <p>The NTP Version 4 distribution includes, in addition to the daemon itself (<tt><a href="ntpd.html">ntpd</a></tt>), several utility programs, including two remote-monitoring programs (<a href="ntpq.html"><tt>ntpq</tt></a>, <tt><a href="ntpdc.html">ntpdc</a></tt>), a remote clock-setting program similar to the Unix rdate program (<tt>ntpdate</tt>), a traceback utility useful to discover suitable synchronization sources (<tt>ntptrace</tt>), and various programs used to configure the local platform and calibrate the intrinsic errors. NTP has been ported to a large number of platforms, including most RISC and CISC workstations and mainframes manufactured today. Example configuration files for many models of these machines are included in the distribution. While in most cases the standard version of the implementation runs with no hardware or operating system modifications, not all features of the distribution are available on all platforms. For instance, a special feature allowing Sun workstations to achieve accuracies in the order of 100 microseconds requires some minor changes and additions to the kernel and input/output support.</p> - <p>There are, however, several drawbacks to all of this. <tt>ntpd</tt> is quite fat. This is rotten if your intended platform for the daemon is memory limited. <tt>ntpd</tt> uses <tt>SIGIO</tt> for all input, a facility which appears to not enjoy universal support and whose use seems to exercise the parts of your vendors' kernels which are most likely to have been done poorly. The code is unforgiving in the face of kernel problems which affect performance, and generally requires that you repair the problems in order to achieve acceptable performance. The code has a distinctly experimental flavour and contains features which could charitably be termed failed experiments, but which have not been completely hacked out. Much was learned from the addition of support for a variety of radio clocks, with the result that some radio clock drivers could use some rewriting.</p> - <h4>How NTP Works</h4> - <p>The approach used by NTP to achieve reliable time synchronization from a set of possibly unreliable remote time servers is somewhat different than other protocols. In particular, NTP does not attempt to synchronize clocks to each other. Rather, each server attempts to synchronize to Universal Coordinated Time (UTC) using the best available source and available transmission paths to that source. This is a fine point which is worth understanding. A group of NTP-synchronized clocks may be close to each other in time, but this is not a consequence of the clocks in the group having synchronized to each other, but rather because each clock has synchronized closely to UTC via the best source it has access to. As such, trying to synchronize a set of clocks to a set of servers whose time is not in mutual agreement may not result in any sort of useful synchronization of the clocks, even if you don't care about UTC. However, in networks isolated from UTC sources, provisions can made to nominate one of them as a phantom UTC source.</p> - <p>NTP operates on the premise that there is one true standard time, and that if several servers which claim synchronization to standard time disagree about what that time is, then one or more of them must be broken. There is no attempt to resolve differences more gracefully since the premise is that substantial differences cannot exist. In essence, NTP expects that the time being distributed from the root of the synchronization subnet will be derived from some external source of UTC (e.g., a radio clock). This makes it somewhat inconvenient (though by no means impossible) to synchronize hosts together without a reliable source of UTC to synchronize them to. If your network is isolated and you cannot access other people's servers across the Internet, a radio clock may make a good investment.</p> - <p>Time is distributed through a hierarchy of NTP servers, with each server adopting a <i>stratum</i> which indicates how far away from an external source of UTC it is operating at. Stratum-1 servers, which are at the top of the pile (or bottom, depending on your point of view), have access to some external time source, usually a radio clock synchronized to time signal broadcasts from radio stations which explicitly provide a standard time service. A stratum-2 server is one which is currently obtaining time from a stratum-1 server, a stratum-3 server gets its time from a stratum-2 server, and so on. To avoid long lived synchronization loops the number of strata is limited to 15.</p> - <p>Each client in the synchronization subnet (which may also be a server for other, higher stratum clients) chooses exactly one of the available servers to synchronize to, usually from among the lowest stratum servers it has access to. This is, however, not always an optimal configuration, for indeed NTP operates under another premise as well, that each server's time should be viewed with a certain amount of distrust. NTP really prefers to have access to several sources of lower stratum time (at least three) since it can then apply an agreement algorithm to detect insanity on the part of any one of these. Normally, when all servers are in agreement, NTP will choose the best of these, where "best" is defined in terms of lowest stratum, closest (in terms of network delay) and claimed precision, along with several other considerations. The implication is that, while one should aim to provide each client with three or more sources of lower stratum time, several of these will only be providing backup service and may be of lesser quality in terms of network delay and stratum (i.e., a same-stratum peer which receives time from lower stratum sources the local server doesn't access directly can also provide good backup service).</p> - <p>Finally, there is the issue of association modes. There are a number of modes in which NTP servers can associate with each other, with the mode of each server in the pair indicating the behaviour the other server can expect from it. In particular, when configuring a server to obtain time from other servers, there is a choice of two modes which may be used. Configuring an association in symmetric-active mode (usually indicated by a <tt>peer</tt> declaration in the configuration file) indicates to the remote server that one wishes to obtain time from the remote server and that one is also willing to supply time to the remote server if need be. This mode is appropriate in configurations involving a number of redundant time servers interconnected via diverse network paths, which is presently the case for most stratum-1 and stratum-2 servers on the Internet today. Configuring an association in client mode (usually indicated by a <tt>server</tt> declaration in the configuration file) indicates that one wishes to obtain time from the remote server, but that one is not willing to provide time to the remote server. This mode is appropriate for file-server and workstation clients that do not provide synchronization to other local clients. Client mode is also useful for boot-date-setting programs and the like, which really have no time to provide and which don't retain state about associations over the longer term.</p> - <p>Where the requirements in accuracy and reliability are modest, clients can be configured to use broadcast and/or multicast modes. These modes are not normally utilized by servers with dependent clients. The advantage of these modes is that clients do not need to be configured for a specific server, so that all clients operating can use the same configuration file. Broadcast mode requires a broadcast server on the same subnet, while multicast mode requires support for IP multicast on the client machine, as well as connectivity via the MBONE to a multicast server. Since broadcast messages are not propagated by routers, only those broadcast servers on the same subnet will be used. There is at present no way to select which of possibly many multicast servers will be used, since all operate on the same group address.</p> - <p>Where the maximum accuracy and reliability provided by NTP are needed, clients and servers operate in either client/server or symmetric modes. Symmetric modes are most often used between two or more servers operating as a mutually redundant group. In these modes, the servers in the group members arrange the synchronization paths for maximum performance, depending on network jitter and propagation delay. If one or more of the group members fail, the remaining members automatically reconfigure as required. Dependent clients and servers normally operate in client/server mode, in which a client or dependent server can be synchronized to a group member, but no group member can synchronize to the client or dependent server. This provides protection against malfunctions or protocol attacks.</p> - <p>Servers that provide synchronization to a sizeable population of clients normally operate as a group of three or more mutually redundant servers, each operating with three or more stratum-one or stratum-two servers in client-server modes, as well as all other members of the group in symmetric modes. This provides protection against malfunctions in which one or more servers fail to operate or provide incorrect time. The NTP algorithms have been specifically engineered to resist attacks where some fraction of the configured synchronization sources accidently or purposely provide incorrect time. In these cases a special voting procedure is used to identify spurious sources and discard their data.</p> - <h4>Configuring Your Subnet</h4> - At startup time the <tt>ntpd</tt> daemon running on a host reads the initial configuration information from a file, usually <tt>/etc/ntp.conf</tt>, unless a different name has been specified at compile time. Putting something in this file which will enable the host to obtain time from somewhere else is usually the first big hurdle after installation of the software itself, which is described in the <a href="build/build.html">Building and Installing the Distribution</a> page. At its simplest, what you need to do in the configuration file is declare the servers that the daemon should poll for time synchronization. In principle, no such list is needed if some other time server operating in broadcast/multicast mode is available, which requires the client to operate in a broadcastclient mode. - <p>In the case of a workstation operating in an enterprise network for a public or private organization, there is often an administrative department that coordinates network services, including NTP. Where available, the addresses of appropriate servers can be provided by that department. However, if this infrastructure is not available, it is necessary to explore some portion of the existing NTP subnet now running in the Internet. There are at present many thousands of time servers running NTP in the Internet, a significant number of which are willing to provide a public time- synchronization service. Some of these are listed in the list of public time servers, which can be accessed via the <a href="http://www.eecis.udel.edu/%7entp">NTP web page</a>. These data are updated on a regular basis using information provided voluntarily by various site administrators. There are other ways to explore the nearby subnet using the <tt><a href="ntptrace.html">ntptrace</a></tt> and <tt><a href="ntpdc.html">ntpdc</a></tt> programs.</p> - <p>It is vital to carefully consider the issues of robustness and reliability when selecting the sources of synchronization. Normally, not less than three sources should be available, preferably selected to avoid common points of failure. It is usually better to choose sources which are likely to be "close" to you in terms of network topology, though you shouldn't worry overly about this if you are unable to determine who is close and who isn't. Normally, it is much more serious when a server becomes faulty and delivers incorrect time than when it simply stops operating, since an NTP-synchronized host normally can coast for hours or even days without its clock accumulating serious error approaching a second, for instance. Selecting at least three sources from different operating administrations, where possible, is the minimum recommended, although a lesser number could provide acceptable service with a degraded degree of robustness.</p> - <p>Normally, it is not considered good practice for a single workstation to request synchronization from a primary (stratum-1) time server. At present, these servers provide synchronization for hundreds of clients in many cases and could, along with the network access paths, become seriously overloaded if large numbers of workstation clients requested synchronization directly. Therefore, workstations located in sparsely populated administrative domains with no local synchronization infrastructure should request synchronization from nearby stratum-2 servers instead. In most cases the keepers of those servers in the lists of public servers provide unrestricted access without prior permission; however, in all cases it is considered polite to notify the administrator listed in the file upon commencement of regular service. In all cases the access mode and notification requirements listed in the file must be respected. Under no conditions should servers not in these lists be used without prior permission, as to do so can create severe problems in the local infrastructure, especially in cases of dial-up access to the Internet.</p> - <p>In the case of a gateway or file server providing service to a significant number of workstations or file servers in an enterprise network it is even more important to provide multiple, redundant sources of synchronization and multiple, diversity-routed, network access paths. The preferred configuration is at least three administratively coordinated time servers providing service throughout the administrative domain including campus networks and subnetworks. Each of these should obtain service from at least two different outside sources of synchronization, preferably via different gateways and access paths. These sources should all operate at the same stratum level, which is one less than the stratum level to be used by the local time servers themselves. In addition, each of these time servers should peer with all of the other time servers in the local administrative domain at the stratum level used by the local time servers, as well as at least one (different) outside source at this level. This configuration results in the use of six outside sources at a lower stratum level (toward the primary source of synchronization, usually a radio clock), plus three outside sources at the same stratum level, for a total of nine outside sources of synchronization. While this may seem excessive, the actual load on network resources is minimal, since the interval between polling messages exchanged between peers usually ratchets back to no more than one message every 17 minutes.</p> - <p>The stratum level to be used by the local time servers is an engineering choice. As a matter of policy, and in order to reduce the load on the primary servers, it is desirable to use the highest stratum consistent with reliable, accurate time synchronization throughout the administrative domain. In the case of enterprise networks serving hundreds or thousands of client file servers and workstations, conventional practice is to obtain service from stratum-1 primary servers listed for public access. When choosing sources away from the primary sources, the particular synchronization path in use at any time can be verified using the <tt>ntptrace</tt> program included in this distribution. It is important to avoid loops and possible common points of failure when selecting these sources. Note that, while NTP detects and rejects loops involving neighboring servers, it does not detect loops involving intervening servers. In the unlikely case that all primary sources of synchronization are lost throughout the subnet, the remaining servers on that subnet can form temporary loops and, if the loss continues for an interval of many hours, the servers will drop off the subnet and free-run with respect to their internal (disciplined) timing sources. After some period with no outside timing source (currently one day), a host will declare itself unsynchronized and provide this information to local application programs.</p> - <p>In many cases the purchase of one or more radio clocks is justified, in which cases good engineering practice is to use the configurations described above anyway and connect the radio clock to one of the local servers. This server is then encouraged to participate in a special primary-server subnetwork in which each radio-equipped server peers with several other similarly equipped servers. In this way the radio-equipped server may provide synchronization, as well as receive synchronization, should the local or remote radio clock(s) fail or become faulty. <tt>ntpd</tt> treats attached radio clock(s) in the same way as other servers and applies the same criteria and algorithms to the time indications, so can detect when the radio fails or becomes faulty and switch to alternate sources of synchronization. It is strongly advised, and in practice for most primary servers today, to employ the authentication or access-control features of the NTP specification in order to protect against hostile intruders and possible destabilization of the time service. Using this or similar strategies, the remaining hosts in the same administrative domain can be synchronized to the three (or more) selected time servers. Assuming these servers are synchronized directly to stratum-1 sources and operate normally as stratum-2, the next level away from the primary source of synchronization, for instance various campus file servers, will operate at stratum 3 and dependent workstations at stratum 4. Engineered correctly, such a subnet will survive all but the most exotic failures or even hostile penetrations of the various, distributed timekeeping resources.</p> - <p>The above arrangement should provide very good, robust time service with a minimum of traffic to distant servers and with manageable loads on the local servers. While it is theoretically possible to extend the synchronization subnet to even higher strata, this is seldom justified and can make the maintenance of configuration files unmanageable. Serving time to a higher stratum peer is very inexpensive in terms of the load on the lower stratum server if the latter is located on the same concatenated LAN. When justified by the accuracy expectations, NTP can be operated in broadcast and multicast modes, so that clients need only listen for periodic broadcasts and do not need to send anything.</p> - <p>When planning your network you might, beyond this, keep in mind a few generic don'ts, in particular:</p> - <ul> - <li>Don't synchronize a local time server to another peer at the same stratum, unless the latter is receiving time from lower stratum sources the former doesn't talk to directly. This minimizes the occurrence of common points of failure, but does not eliminate them in cases where the usual chain of associations to the primary sources of synchronization are disrupted due to failures. - <li style="list-style: none"><br> - <li>Don't configure peer associations with higher stratum servers. Let the higher strata configure lower stratum servers, but not the reverse. This greatly simplifies configuration file maintenance, since there is usually much greater configuration churn in the high stratum clients such as personal workstations. - <li style="list-style: none"><br> - <li>Don't synchronize more than one time server in a particular administrative domain to the same time server outside that domain. Such a practice invites common points of failure, as well as raises the possibility of massive abuse, should the configuration file be automatically distributed do a large number of clients. - </ul> - There are many useful exceptions to these rules. When in doubt, however, follow them. - <h4>Configuring Your Server or Client</h4> - <p>As mentioned previously, the configuration file is usually called /etc/ntp.conf. This is an ASCII file conforming to the usual comment and whitespace conventions. A working configuration file might look like (in this and other examples, do not copy this directly):</p> - <pre> - # peer configuration for host whimsy - # (expected to operate at stratum 2) - - server rackety.udel.edu - server umd1.umd.edu - server lilben.tn.cornell.edu - - driftfile /etc/ntp.drift -</pre> - (Note the use of host names, although host addresses in dotted-quad notation can also be used. It is always preferable to use names rather than addresses, since over time the addresses can change, while the names seldom change.) - <p>This particular host is expected to operate as a client at stratum 2 by virtue of the <tt>server</tt> keyword and the fact that two of the three servers declared (the first two) have radio clocks and usually run at stratum 1. The third server in the list has no radio clock, but is known to maintain associations with a number of stratum 1 peers and usually operates at stratum 2. Of particular importance with the last host is that it maintains associations with peers besides the two stratum 1 peers mentioned. This can be verified using the <tt>ntpq</tt> program mentioned above. When configured using the <tt>server</tt> keyword, this host can receive synchronization from any of the listed servers, but can never provide synchronization to them.</p> - <p>Unless restricted using facilities described later, this host can provide synchronization to dependent clients, which do not have to be listed in the configuration file. Associations maintained for these clients are transitory and result in no persistent state in the host. These clients are normally not visible using the <tt>ntpq</tt> program included in the distribution; however, <tt>ntpd</tt> includes a monitoring feature (described later) which caches a minimal amount of client information useful for debugging administrative purposes.</p> - <p>A time server expected to both receive synchronization from another server, as well as to provide synchronization to it, is declared using the <tt>peer</tt> keyword instead of the <tt>server</tt> keyword. In all other aspects the server operates the same in either mode and can provide synchronization to dependent clients or other peers. If a local source of UTC time is available, it is considered good engineering practice to declare time servers outside the administrative domain as <tt>peer</tt> and those inside as <tt>server</tt> in order to provide redundancy in the global Internet, while minimizing the possibility of instability within the domain itself. A time server in one domain can in principle heal another domain temporarily isolated from all other sources of synchronization. However, it is probably unwise for a casual workstation to bridge fragments of the local domain which have become temporarily isolated.</p> - <p>Note the inclusion of a <tt>driftfile</tt> declaration. One of the things the NTP daemon does when it is first started is to compute the error in the intrinsic frequency of the clock on the computer it is running on. It usually takes about a day or so after the daemon is started to compute a good estimate of this (and it needs a good estimate to synchronize closely to its server). Once the initial value is computed, it will change only by relatively small amounts during the course of continued operation. The <tt>driftfile</tt> declaration indicates to the daemon the name of a file where it may store the current value of the frequency error so that, if the daemon is stopped and restarted, it can reinitialize itself to the previous estimate and avoid the day's worth of time it will take to recompute the frequency estimate. Since this is a desirable feature, a <tt>driftfile</tt> declaration should always be included in the configuration file.</p> - <p>An implication in the above is that, should <tt>ntpd</tt> be stopped for some reason, the local platform time will diverge from UTC by an amount that depends on the intrinsic error of the clock oscillator and the time since last synchronized. In view of the length of time necessary to refine the frequency estimate, every effort should be made to operate the daemon on a continuous basis and minimize the intervals when for some reason it is not running.</p> - <h4>Configuring NTP with NetInfo</h4> - If NetInfo support is compiled into NTP, you can opt to configure NTP in your NetInfo domain. NTP will look in the NetInfo directory <tt>/locations/ntp</tt> for property/value pairs which are equivalent to the lines in the configuration file described above. Each configuration keyword may have a corresponding property in NetInfo. Each value for a given property is treated as arguments to that property, similar to a line in the configuration file. - <p>For example, the configuration shown in the configuration file above can be duplicated in NetInfo by adding a property "<tt>server</tt>" with values "<tt>rackety.udel.edu</tt>", "<tt>umd1.umd.edu</tt>", and "<tt>lilben.tn.cornell.edu</tt>"; and a property "<tt>driftfile</tt>" with the single value "<tt>/etc/ntp.drift</tt>".</p> - <p>Values may contain multiple tokens similar to the arguments available in the configuration file. For example, to use <tt>mimsy.mil</tt> as an NTP version 1 time server, you would add a value "<tt>mimsy.mil version 1</tt>" to the "<tt>server</tt>" property.</p> - <h4>Ntp4 Versus Previous Versions</h4> - There are several items of note when dealing with a mixture of <tt>ntp4</tt> and previous distributions of NTP Version 2 (<tt>ntpd</tt>) and NTP Version 1 (<tt>ntp3.4</tt>). The <tt>ntp4</tt> implementation conforms to the NTP Version 3 specification RFC-1305 and, in addition, contains additional features documented in the <a href="release.html">Release Notes</a> page. As such, by default when no additional information is available concerning the preferences of the peer, <tt>ntpd</tt> claims to be version 4 in the packets that it sends from configured associations. The <tt>version</tt> subcommand of the <tt>server</tt>, <tt>peer</tt>, <tt>broadcast</tt> and <tt>manycastclient</tt> command can be used to change the default. In unconfigured (ephemeral) associaitons, the daemon always replies in the same version as the request. - <p>An NTP implementation conforming to a previous version specification ordinarily discards packets from a later version. However, in most respects documented in RFC-1305, The version 2 implementation is compatible with the version 3 algorithms and protocol. The version 1 implementation contains most of the version 2 algorithms, but without important features for clock selection and robustness. Nevertheless, in most respects the NTP versions are backwards compatible. The sticky part here is that, when a previous version implementation receives a packet claiming to be from a version 4 server, it discards it without further processing. Hence there is a danger that in some situations synchronization with previous versions will fail.</p> - <p>The trouble occurs when an previous version is to be included in an <tt>ntpd</tt> configuration file. With no further indication, <tt>ntpd</tt> will send packets claiming to be version 4 when it polls. To get around this, <tt>ntpd</tt> allows a qualifier to be added to configuration entries to indicate which version to use when polling. Hence the entries</p> - <pre> - # specify NTP version 1 - - server mimsy.mil version -1 # server running ntpd version 1 - server apple.com version -2 # server running ntpd version 2 -</pre> - will cause version 1 packets to be sent to the host mimsy.mil and version 2 packets to be sent to apple.com. If you are testing <tt>ntpd</tt> against previous version servers you will need to be careful about this. Note that, as indicated in the RFC-1305 specification, there is no longer support for the original NTP specification, once called NTP Version 0. - <h4>Traffic Monitoring</h4> - <tt>ntpd</tt> handles peers whose stratum is higher than the stratum of the local server and polls using client mode by a fast path which minimizes the work done in responding to their polls, and normally retains no memory of these pollers. Sometimes, however, it is interesting to be able to determine who is polling the server, and how often, as well as who has been sending other types of queries to the server. - <p>To allow this, <tt>ntpd</tt> implements a traffic monitoring facility which records the source address and a minimal amount of other information from each packet which is received by the server. This feature is normally enabled, but can be disabled if desired using the configuration file entry:</p> - <pre> - # disable monitoring feature - disable monitor -</pre> - The recorded information can be displayed using the <tt>ntpdc</tt> query program, described briefly below. - <h4>Address-and-Mask Restrictions</h4> - The address-and-mask configuration facility supported by <tt>ntpd</tt> is quite flexible and general, but is not an integral part of the NTP Version 3 specification. The major drawback is that, while the internal implementation is very nice, the user interface is not. For this reason it is probably worth doing an example here. Briefly, the facility works as follows. There is an internal list, each entry of which holds an address, a mask and a set of flags. On receipt of a packet, the source address of the packet is compared to each entry in the list, with a match being posted when the following is true: - <pre> - (source_addr & mask) == (address & -mask) -</pre> - A particular source address may match several list entries. In this case the entry with the most one bits in the mask is chosen. The flags associated with this entry are used to control the access. - <p>In the current implementation the flags always add restrictions. In effect, an entry with no flags set leaves matching hosts unrestricted. An entry can be added to the internal list using a <tt>restrict</tt> declaration. The flags associated with the entry are specified textually. For example, the <tt>notrust</tt> flag indicates that hosts matching this entry, while treated normally in other respects, shouldn't be trusted to provide synchronization even if otherwise so enabled. The <tt>nomodify</tt> flag indicates that hosts matching this entry should not be allowed to do run-time configuration. There are many more flags, see the <a href="ntpd.html"><tt>ntpd</tt></a> page.</p> - <p>Now the example. Suppose you are running the server on a host whose address is 128.100.100.7. You would like to ensure that run time reconfiguration requests can only be made from the local host and that the server only ever synchronizes to one of a pair of off-campus servers or, failing that, a time source on net 128.100. The following entries in the configuration file would implement this policy:</p> - <pre> - # by default, don't trust and don't allow -modifications - - restrict default notrust nomodify - - # these guys are trusted for time, but no -modifications allowed - - restrict 128.100.0.0 mask 255.255.0.0 nomodify - restrict 128.8.10.1 nomodify - restrict 192.35.82.50 nomodify - - # the local addresses are unrestricted - - restrict 128.100.100.7 - restrict 127.0.0.1 -</pre> - The first entry is the default entry, which all hosts match and hence which provides the default set of flags. The next three entries indicate that matching hosts will only have the <tt>nomodify</tt> flag set and hence will be trusted for time. If the mask isn't specified in the <tt>restrict</tt> keyword, it defaults to 255.255.255.255. Note that the address 128.100.100.7 matches three entries in the table, the default entry (mask 0.0.0.0), the entry for net 128.100 (mask 255.255.0.0) and the entry for the host itself (mask 255.255.255.255). As expected, the flags for the host are derived from the last entry since the mask has the most bits set. - <p>The only other thing worth mentioning is that the <tt>restrict</tt> declarations apply to packets from all hosts, including those that are configured elsewhere in the configuration file and even including your clock pseudopeer(s), if any. Hence, if you specify a default set of restrictions which you don't wish to be applied to your configured peers, you must remove those restrictions for the configured peers with additional <tt>restrict</tt> declarations mentioning each peer separately.</p> - <h4>Authentication</h4> - <tt>ntpd</tt> supports the optional authentication procedure specified in the NTP Version 2 and 3 specifications. Briefly, when an association runs in authenticated mode, each packet transmitted has appended to it a 32-bit key ID and a 64/128-bit cryptographic checksum of the packet contents computed using either the Data Encryption Standard (DES) or Message Digest (MD5) algorithms. Note that, while either of these algorithms provide sufficient protection from message- modification attacks, distribution of the former algorithm implementation is restricted to the U.S. and Canada, while the latter presently is free from such restrictions. For this reason, the DES algorithm is not included in the current distribution. Directions for obtaining it in other countries is in the <a href="build/build.html">Building and Installing the Distribution</a> page. With either algorithm the receiving peer recomputes the checksum and compares it with the one included in the packet. For this to work, the peers must share at least one encryption key and, furthermore, must associate the shared key with the same key ID. - <p>This facility requires some minor modifications to the basic packet processing procedures, as required by the specification. These modifications are enabled by the <tt>enable auth</tt> configuration declaration, which is currently the default. In authenticated mode, peers which send unauthenticated packets, peers which send authenticated packets which the local server is unable to decrypt and peers which send authenticated packets encrypted using a key we don't trust are all marked untrustworthy and unsuitable for synchronization. Note that, while the server may know many keys (identified by many key IDs), it is possible to declare only a subset of these as trusted. This allows the server to share keys with a client which requires authenticated time and which trusts the server, but which is not trusted by the server. Also, some additional configuration language is required to specify the key ID to be used to authenticate each configured peer association. Hence, for a server running in authenticated mode, the configuration file might look similar to the following:</p> - <pre> - # peer configuration for 128.100.100.7 - # (expected to operate at stratum 2) - # fully authenticated this time - - peer 128.100.49.105 key 22 # -suzuki.ccie.utoronto.ca - peer 128.8.10.1 key 4 # -umd1.umd.edu - peer 192.35.82.50 key 6 # -lilben.tn.cornell.edu - - keys /usr/local/etc/ntp.keys # path for -key file - trustedkey 1 2 14 15 # -define trusted keys - requestkey -15 # -key (7) for accessing server variables - controlkey -15 # -key (6) for accessing server variables - - authdelay -0.000094 # authentication delay -(Sun4c/50 IPX) -</pre> - There are a couple of previously unmentioned things in here. The <tt>keys</tt> line specifies the path to the keys file (see below and the <tt>ntpd</tt> document page for details of the file format). The <tt>trustedkey</tt> declaration identifies those keys that are known to be uncompromised; the remainder presumably represent the expired or possibly compromised keys. Both sets of keys must be declared by key identifier in the <tt>ntp.keys</tt> file described below. This provides a way to retire old keys while minimizing the frequency of delicate key-distribution procedures. The <tt>requestkey</tt> line establishes the key to be used for mode-6 control messages as specified in RFC-1305 and used by the <tt>ntpq</tt> utility program, while the <tt>controlkey</tt> line establishes the key to be used for mode-7 private control messages used by the <tt>ntpdc</tt> utility program. These keys are used to prevent unauthorized modification of daemon variables. - <p>Ordinarily, the authentication delay; that is, the processing time taken between the freezing of a transmit timestamp and the actual transmission of the packet when authentication is enabled (i.e. more or less the time it takes for the DES or MD5 routine to encrypt a single block) is computed automatically by the daemon. If necessary, the delay can be overridden by the <tt>authdelay</tt> line, which is used as a correction for the transmit timestamp.</p> - Additional utility programs included in the <tt>./authstuff</tt> directory can be used to generate random keys, certify implementation correctness and display sample keys. As a general rule, keys should be chosen randomly, except possibly the request and control keys, which must be entered by the user as a password. - <p>The <tt>ntp.keys</tt> file contains the list of keys and associated key IDs the server knows about (for obvious reasons this file is better left unreadable by anyone except root). The contents of this file might look like:</p> - <pre> - # ntp keys file (ntp.keys) - 1 N -29233E0461ECD6AE # DES key in NTP format - 2 M -RIrop8KPPvQvYotM # md5 key as an ASCII random string - 14 M -sundial -; # md5 key as an ASCII string - 15 A -sundial -; # DES key as an ASCII string - - # the following 3 keys are identical - - 10 A SeCReT - 10 N -d3e54352e5548080 - 10 S -a7cb86a4cba80101 -</pre> - In the keys file the first token on each line indicates the key ID, the second token the format of the key and the third the key itself. There are four key formats. An <tt>A</tt> indicates a DES key written as a 1- to-8 character string in 7-bit ASCII representation, with each character standing for a key octet (like a Unix password). An <tt>S</tt> indicates a DES key written as a hex number in the DES standard format, with the low order bit (LSB) of each octet being the (odd) parity bit. An <tt>N</tt> indicates a DES key again written as a hex number, but in NTP standard format with the high order bit of each octet being the (odd) parity bit (confusing enough?). An <tt>M</tt> indicates an MD5 key written as a 1-to-31 character ASCII string in the <tt>A</tt> format. Note that, because of the simple tokenizing routine, the characters <tt>' ', '#', '\t', '\n'</tt> and <tt>'\0'</tt> can't be used in either a DES or MD5 ASCII key. Everything else is fair game, though. Key 0 (zero) is used for special purposes and should not appear in this file. - <p>The big trouble with the authentication facility is the keys file. It is a maintenance headache and a security problem. This should be fixed some day. Presumably, this whole bag of worms goes away if/when a generic security regime for the Internet is established. An alternative with NTP Version 4 is the autokey feature, which uses random session keys and public-key cryptography and avoids the key file entirely. While this feature is not completely finished yet, details can be found in the <a href="release.html">Release Notes</a> page.</p> - <h4>Query Programs</h4> - Three utility query programs are included with the distribution, <tt>ntpq</tt>, <tt>ntptrace</tt> and <tt>ntpdc</tt>. <tt>ntpq</tt> is a handy program which sends queries and receives responses using NTP standard mode-6 control messages. Since it uses the standard control protocol specified in RFC- 1305, it may be used with NTP Version 2 and Version 3 implementations for both Unix and Fuzzball, but not Version 1 implementations. It is most useful to query remote NTP implementations to assess timekeeping accuracy and expose bugs in configuration or operation. - <p><tt>ntptrace</tt> can be used to display the current synchronization path from a selected host through possibly intervening servers to the primary source of synchronization, usually a radio clock. It works with both version 2 and version 3 servers, but not version 1.</p> - <p><tt>ntpdc</tt> is a horrid program which uses NTP private mode-7 control messages to query local or remote servers. The format and contents of these messages are specific to this version of <tt>ntpd</tt> and some older versions. The program does allow inspection of a wide variety of internal counters and other state data, and hence does make a pretty good debugging tool, even if it is frustrating to use. The other thing of note about <tt>ntpdc</tt> is that it provides a user interface to the run time reconfiguration facility. See the respective document pages for details on the use of these programs.</p> - <h4>Run-Time Reconfiguration</h4> - <tt>ntpd</tt> was written specifically to allow its configuration to be fully modifiable at run time. Indeed, the only way to configure the server is at run time. The configuration file is read only after the rest of the server has been initialized into a running default-configured state. This facility was included not so much for the benefit of Unix, where it is handy but not strictly essential, but rather for dedicated platforms where the feature is more important for maintenance. Nevertheless, run time configuration works very nicely for Unix servers as well. - <p>Nearly all of the things it is possible to configure in the configuration file may be altered via NTP mode-7 messages using the <tt>ntpdc</tt> program. Mode-6 messages may also provide some limited configuration functionality (though the only thing you can currently do with mode-6 messages is set the leap-second warning bits) and the <tt>ntpq</tt> program provides generic support for the latter. The leap bits that can be set in the <tt>leap_warning</tt> variable (up to one month ahead) and in the <tt>leap_indication</tt> variable have a slightly different encoding than the usual interpretation:</p> - <pre> - -Value Action - - -00 -p; The daemon passes the leap bits of its - - -synchronisation source (usual mode of operation) - - 01/10 A leap -second is added/deleted - - -11 -p; Leap information from the synchronization source - - is -ignored (thus LEAP_NOWARNING is passed on) -</pre> - Mode-6 and mode-7 messages which would modify the configuration of the server are required to be authenticated using standard NTP authentication. To enable the facilities one must, in addition to specifying the location of a keys file, indicate in the configuration file the key IDs to be used for authenticating reconfiguration commands. Hence the following fragment might be added to a configuration file to enable the mode-6 (ntpq) and mode-7 (ntpdc) facilities in the daemon: - <pre> - # specify mode-6 and mode-7 trusted keys - - requestkey 65535 # for mode-7 -requests - controlkey 65534 # for mode-6 -requests -</pre> - If the <tt>requestkey</tt> and/or the <tt>controlkey</tt> configuration declarations are omitted from the configuration file, the corresponding run-time reconfiguration facility is disabled. - <p>The query programs require the user to specify a key ID and a key to use for authenticating requests to be sent. The key ID provided should be the same as the one mentioned in the configuration file, while the key should match that corresponding to the key ID in the keys file. As the query programs prompt for the key as a password, it is useful to make the request and control authentication keys typeable (in ASCII format) from the keyboard.</p> - <h4>Name Resolution</h4> - <tt>ntpd</tt> includes the capability to specify host names requiring resolution in <tt>peer</tt> and <tt>server</tt> declarations in the configuration file. However, in some outposts of the Internet, name resolution is unreliable and the interface to the Unix resolver routines is synchronous. The hangups and delays resulting from name-resolver clanking can be unacceptable once the NTP server is running (and remember it is up and running before the configuration file is read). However, it is advantageous to resolve time server names, since their addresses are occasionally changed. - <p>In order to prevent configuration delays due to the name resolver, the daemon runs the name resolution process in parallel with the main daemon code. When the daemon comes across a <tt>peer</tt> or <tt>server</tt> entry with a non-numeric host address, it records the relevant information in a temporary file and continues on. When the end of the configuration file has been reached and one or more entries requiring name resolution have been found, the server runs the name resolver from the temporary file. The server then continues on normally but with the offending peers/servers omitted from its configuration.</p> - <p>As each name is resolved, it configures the associated entry into the server using the same mode-7 run time reconfiguration facility that <tt>ntpdc</tt> uses. If temporary resolver failures occur, the resolver will periodically retry the requests until a definite response is received. The program will continue to run until all entries have been resolved.</p> - <h4>Dealing with Frequency Tolerance Violations (<tt>tickadj</tt> and Friends)</h4> - The NTP Version 3 specification RFC-1305 calls for a maximum oscillator frequency tolerance of +-100 parts-per-million (PPM), which is representative of those components suitable for use in relatively inexpensive workstation platforms. For those platforms meeting this tolerance, NTP will automatically compensate for the frequency errors of the individual oscillator and no further adjustments are required, either to the configuration file or to various kernel variables. For the NTP Version 4 release, this tolerance has been increased to +-500 PPM. - <p>However, in the case of certain notorious platforms, in particular Sun 4.1.1 systems, the performance can be improved by adjusting the values of certain kernel variables; in particular, <tt>tick</tt> and <tt>tickadj</tt>. The variable <tt>tick</tt> is the increment in microseconds added to the system time on each interval- timer interrupt, while the variable <tt>tickadj</tt> is used by the time adjustment code as a slew rate, in microseconds per tick. When the time is being adjusted via a call to the system routine <tt>adjtime()</tt>, the kernel increases or reduces tick by <tt>tickadj</tt> microseconds per tick until the specified adjustment has been completed. Unfortunately, in most Unix implementations the tick increment must be either zero or plus/minus exactly <tt>tickadj</tt> microseconds, meaning that adjustments are truncated to be an integral multiple of <tt>tickadj</tt> (this latter behaviour is a misfeature, and is the only reason the <tt>tickadj</tt> code needs to concern itself with the internal implementation of <tt>tickadj</tt> at all). In addition, the stock Unix implementation considers it an error to request another adjustment before a prior one has completed.</p> - <p>Thus, to make very sure it avoids problems related to the roundoff, the <tt>tickadj</tt> program can be used to adjust the values of <tt>tick</tt> and <tt>tickadj</tt>. This ensures that all adjustments given to <tt>adjtime()</tt> are an even multiple of <tt>tickadj</tt> microseconds and computes the largest adjustment that can be completed in the adjustment interval (using both the value of <tt>tick</tt> and the value of <tt>tickadj</tt>) so it can avoid exceeding this limit. It is important to note that not all systems will allow inspection or modification of kernel variables other than at system build time. It is also important to know that, with the current NTP tolerances, it is rarely necessary to make these changes, but in many cases they will substantially improve the general accuracy of the time service.</p> - <p>Unfortunately, the value of <tt>tickadj</tt> set by default is almost always too large for <tt>ntpd</tt>. NTP operates by continuously making small adjustments to the clock, usually at one-second intervals. If <tt>tickadj</tt> is set too large, the adjustments will disappear in the roundoff; while, if <tt>tickadj</tt> is too small, NTP will have difficulty if it needs to make an occasional large adjustment. While the daemon itself will read the kernel's values of these variables, it will not change the values, even if they are unsuitable. You must do this yourself before the daemon is started using the <tt>tickadj</tt> program included in the <tt>./util</tt> directory of the distribution. Note that the latter program will also compute an optimal value of <tt>tickadj</tt> for NTP use based on the kernel's value of <tt>tick</tt>.</p> - <p>The <tt>tickadj</tt> program can reset several other kernel variables if asked. It can change the value of <tt>tick</tt> if asked. This is handy to compensate for kernel bugs which cause the clock to run with a very large frequency error, as with SunOS 4.1.1 systems. It can also be used to set the value of the kernel <tt>dosynctodr</tt> variable to zero. This variable controls whether to synchronize the system clock to the time-of-day clock, something you really don't want to be happen when <tt>ntpd</tt> is trying to keep it under control. In some systems, such as recent Sun Solaris kernels, the <tt>dosynctodr</tt> variable is the only one that can be changed by the <tt>tickadj</tt> program. In this and other modern kernels, it is not necessary to change the other variables in any case.</p> - <p>We have a report that says starting with Solaris 2.6 we should leave <i>dosynctodr</i> alone.</p> - <p>In order to maintain reasonable correctness bounds, as well as reasonably good accuracy with acceptable polling intervals, <tt>ntpd</tt> will complain if the frequency error is greater than 500 PPM. For machines with a value of <tt>tick</tt> in the 10-ms range, a change of one in the value of <tt>tick</tt> will change the frequency by about 100 PPM. In order to determine the value of <tt>tick</tt> for a particular CPU, disconnect the machine from all sources of time (<tt>dosynctodr</tt> = 0) and record its actual time compared to an outside source (eyeball-and-wristwatch will do) over a day or more. Multiply the time change over the day by 0.116 and add or subtract the result to tick, depending on whether the CPU is fast or slow. An example call to <tt>tickadj</tt> useful on SunOS 4.1.1 is:</p> - <pre> - <tt>tickadj</tt> -t 9999 -a 5 -s -</pre> - which sets tick 100 PPM fast, <tt>tickadj</tt> to 5 microseconds and turns off the clock/calendar chip fiddle. This line can be added to the <tt>rc.local</tt> configuration file to automatically set the kernel variables at boot time. - <p>All this stuff about diddling kernel variables so the NTP daemon will work is really silly. If vendors would ship machines with clocks that kept reasonable time and would make their <tt>adjtime()</tt> system call apply the slew it is given exactly, independent of the value of <tt>tickadj</tt>, all this could go away. This is in fact the case on many current Unix systems.</p> - <h4>Tuning Your Subnet</h4> - There are several parameters available for tuning the NTP subnet for maximum accuracy and minimum jitter. One of these is the <tt>prefer</tt> configuration declaration described in <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> documentation page. When more than one eligible server exists, the NTP clock-selection and combining algorithms act to winnow out all except the "best" set of servers using several criteria based on differences between the readings of different servers and between successive readings of the same server. The result is usually a set of surviving servers that are apparently statistically equivalent in accuracy, jitter and stability. The population of survivors remaining in this set depends on the individual server characteristics measured during the selection process and may vary from time to time as the result of normal statistical variations. In LANs with high speed RISC-based time servers, the population can become somewhat unstable, with individual servers popping in and out of the surviving population, generally resulting in a regime called <i>clockhopping</i>. - <p>When only the smallest residual jitter can be tolerated, it may be convenient to elect one of the servers at each stratum level as the preferred one using the keyword <tt>prefer</tt> on the configuration declaration for the selected server:</p> - <pre> - # preferred server declaration - - peer rackety.udel.edu prefer -# preferred server -</pre> - The preferred server will always be included in the surviving population, regardless of its characteristics and as long as it survives preliminary sanity checks and validation procedures. - <p>The most useful application of the <tt>prefer</tt> keyword is in high speed LANs equipped with precision radio clocks, such as a GPS receiver. In order to insure robustness, the hosts need to include outside peers as well as the GPS-equipped server; however, as long as that server is running, the synchronization preference should be that server. The keyword should normally be used in all cases in order to prefer an attached radio clock. It is probably inadvisable to use this keyword for peers outside the LAN, since it interferes with the carefully crafted judgement of the selection and combining algorithms.</p> - <h4>Provisions for Leap Seconds and Accuracy Metrics</h4> - <tt>ntpd</tt> understands leap seconds and will attempt to take appropriate action when one occurs. In principle, every host running ntpd will insert a leap second in the local timescale in precise synchronization with UTC. This requires that the leap-warning bits be activated some time prior to the occurrence of a leap second at the primary (stratum 1) servers. Subsequently, these bits are propagated throughout the subnet depending on these servers by the NTP protocol itself and automatically implemented by <tt>ntpd</tt> and the time- conversion routines of each host. The implementation is independent of the idiosyncrasies of the particular radio clock, which vary widely among the various devices, as long as the idiosyncratic behavior does not last for more than about 20 minutes following the leap. Provisions are included to modify the behavior in cases where this cannot be guaranteed. While provisions for leap seconds have been carefully crafted so that correct timekeeping immediately before, during and after the occurrence of a leap second is scrupulously correct, stock Unix systems are mostly inept in responding to the available information. This caveat goes also for the maximum-error and statistical-error bounds carefully calculated for all clients and servers, which could be very useful for application programs needing to calibrate the delays and offsets to achieve a near- simultaneous commit procedure, for example. While this information is maintained in the <tt>ntpd</tt> data structures, there is at present no way for application programs to access it. This may be a topic for further development. - <h4>Clock Support Overview</h4> - <tt>ntpd</tt> was designed to support radio (and other external) clocks and does some parts of this function with utmost care. Clocks are treated by the protocol as ordinary NTP peers, even to the point of referring to them with an (invalid) IP host address. Clock addresses are of the form 127.127.<i>t.u</i>, where <i>t</i> specifies the particular type of clock (i.e., refers to a particular clock driver) and <i>u</i> is a unit number whose interpretation is clock-driver dependent. This is analogous to the use of major and minor device numbers by Unix and permits multiple instantiations of clocks of the same type on the same server, should such magnificent redundancy be required. - <p>Because clocks look much like peers, both configuration file syntax and run time reconfiguration commands can be used to control clocks in the same way as ordinary peers. Clocks are configured via <tt>server</tt> declarations in the configuration file, can be started and stopped using ntpdc and are subject to address-and-mask restrictions much like a normal peer, should this stretch of imagination ever be useful. As a concession to the need to sometimes transmit additional information to clock drivers, an additional configuration file is available: the <tt>fudge</tt> statement. This enables one to specify the values of two time quantities, two integral values and two flags, the use of which is dependent on the particular clock driver. For example, to configure a PST radio clock which can be accessed through the serial device <tt>/dev/pst1</tt>, with propagation delays to WWV and WWVH of 7.5 and 26.5 milliseconds, respectively, on a machine with an imprecise system clock and with the driver set to disbelieve the radio clock once it has gone 30 minutes without an update, one might use the following configuration file entries:</p> - <pre> - # radio clock fudge fiddles - server 127.127.3.1 - fudge 127.127.3.1 time1 0.0075 time2 0.0265 - fudge 127.127.3.1 value2 30 flag1 1 -</pre> - Additional information on the interpretation of these data with respect to various radio clock drivers is given in the <a href="refclock.html">Reference Clock Drivers</a> document page and in the individual driver documents accessible via that page. - <h4>Towards the Ultimate Tick</h4> - This section considers issues in providing precision time synchronization in NTP subnets which need the highest quality time available in the present technology. These issues are important in subnets supporting real-time services such as distributed multimedia conferencing and wide-area experiment control and monitoring. - <p>In the Internet of today synchronization paths often span continents and oceans with moderate to high variations in delay due to traffic spasms. NTP is specifically designed to minimize timekeeping jitter due to delay variations using intricately crafted filtering and selection algorithms; however, in cases where these variations are as much as a second or more, the residual jitter following these algorithms may still be excessive. Sometimes, as in the case of some isolated NTP subnets where a local source of precision time is available, such as a PPS signal produced by a calibrated cesium clock, it is possible to remove the jitter and retime the local clock oscillator of the NTP server. This has turned out to be a useful feature to improve the synchronization quality of time distributed in remote places where radio clocks are not available. In these cases special features of the distribution are used together with the PPS signal to provide a jitter-free timing signal, while NTP itself is used to provide the coarse timing and resolve the seconds numbering.</p> - <p>Most available radio clocks can provide time to an accuracy in the order of milliseconds, depending on propagation conditions, local noise levels and so forth. However, as a practical matter, all clocks can occasionally display errors significantly exceeding nominal specifications. Usually, the algorithms used by NTP for ordinary network peers, as well as radio clock peers will detect and discard these errors as discrepancies between the disciplined local clock oscillator and the decoded time message produced by the radio clock. Some radio clocks can produce a special PPS signal which can be interfaced to the server platform in a number of ways and used to substantially improve the (disciplined) clock oscillator jitter and wander characteristics by at least an order of magnitude. Using these features it is possible to achieve accuracies in the order of a few tens of microseconds with a fast RISC- based platform.</p> - <p>There are three ways to implement PPS support, depending on the radio clock model, platform model and serial line interface. These are described in detail in the application notes mentioned in the <a href="index.html">The Network Time Protocol (NTP) Distribution</a> document page. Each of these requires circuitry to convert the TTL signal produced by most clocks to the EIA levels used by most serial interfaces. The <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page describes a device designed to do this. Besides being useful for this purpose, this device includes an inexpensive modem designed for use with the Canadian CHU time/frequency radio station.</p> - <p>In order to select the appropriate implementation, it is important to understand the underlying PPS mechanism used by ntpd. The PPS support depends on a continuous source of PPS pulses used to calculate an offset within +-500 milliseconds relative to the local clock. The serial timecode produced by the radio or the time determined by NTP in absence of the radio is used to adjust the local clock within +-128 milliseconds of the actual time. As long as the local clock is within this interval the PPS support is used to discipline the local clock and the timecode used only to verify that the local clock is in fact within the interval. Outside this interval the PPS support is disabled and the timecode used directly to control the local clock.</p> - <h4>Parting Shots</h4> - There are several undocumented programs which can be useful in unusual cases. They can be found in the <tt>./clockstuff</tt> and <tt>./authstuff</tt> directories of the distribution. One of these is the <tt>propdelay</tt> program, which can compute high frequency radio propagation delays between any two points whose latitude and longitude are known. The program understands something about the phenomena which allow high frequency radio propagation to occur, and will generally provide a better estimate than a calculation based on the great circle distance. Other programs of interest include <tt>clktest</tt>, which allows one to exercise the generic clock line discipline, and <tt>chutest</tt>, which runs the basic reduction algorithms used by the daemon on data received from a serial port. - <hr> - <center> - <img src="pic/pogo1a.gif" alt="gif"></center> - <br> - <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> - </body> - -</html> diff --git a/contrib/ntp/html/ntp-wait.html b/contrib/ntp/html/ntp-wait.html new file mode 100644 index 0000000..dcc6a10 --- /dev/null +++ b/contrib/ntp/html/ntp-wait.html @@ -0,0 +1,33 @@ +<!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-wait - waits until ntpd is in synchronized state</title> + <link href="scripts/style.css" type="text/css" rel="stylesheet"> + </head> + <body> + <h3><tt>ntp-wait</tt> - waits until ntpd is in synchronized state</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->12-Jul-2011 22:03<!-- #EndDate --> + UTC</p> + <hr> + <h4>Synopsis</h4> + <p><tt>ntp-wait [ -v ] [ -n <i>tries</i> ] [ -s <i>seconds</i> ]</tt></p> + <h4>Description</h4> + <p>The <tt>ntp-wait</tt> program blocks until ntpd is in synchronized state. + This can be useful at boot time, to delay the boot sequence + until after "ntpd -g" has set the time. + <h4>Command Line Options</h4> + <dl> + <dt><tt>-n <i>tries</i></tt> + <dd>Number of tries before giving up. The default is 1000. + <dt><tt>-s <i>seconds</i></tt> + <dd>Seconds to sleep between tries. The default is 6 seconds. + <dt><tt>-v</tt> + <dd>Be verbose. + </dl> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> + </body> + +</html> diff --git a/contrib/ntp/html/ntp_conf.html b/contrib/ntp/html/ntp_conf.html index 520ce45..73d26cd 100644 --- a/contrib/ntp/html/ntp_conf.html +++ b/contrib/ntp/html/ntp_conf.html @@ -1,173 +1,174 @@ <!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/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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">19:46</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="223">Friday, June 16, 2006</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>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>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. - </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>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. - </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>Write the action to be performed on recognizing the rules. These actions will be used to build the AST. - <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>Specify the types of all the terminals and non-terminal symbols in the prologue section of the <b>ntp_config.c</b> file. - <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. - </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 -->4-Oct-2010 05:13<!-- #EndDate --> + UTC</p> +<br clear="left"> +<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> +<hr> +<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 id="guidelines">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> diff --git a/contrib/ntp/html/ntpd.html b/contrib/ntp/html/ntpd.html index 3b70694..418d199 100644 --- a/contrib/ntp/html/ntpd.html +++ b/contrib/ntp/html/ntpd.html @@ -1,185 +1,176 @@ <!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/alice47.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 mushroom knows all the command line options.</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"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#synop">Synopsis</a><br> - <li class="inline"><a href="#descr">Description</a><br> - <li class="inline"><a href="#op">How NTP Operates</a><br> - <li class="inline"><a href="#freq">Frequency Discipline</a><br> - <li class="inline"><a href="#modes">Operating Modes</a><br> - <li class="inline"><a href="#poll">Poll Interval Control</a><br> - <li class="inline"><a href="#poll">Poll Interval Control</a><br> - <li class="inline"><a href="#notes">Notes</a><br> - <li class="inline"><a href="#cmd">Command Line Options</a><br> - <li class="inline"><a href="#cfg">The Configuration File</a><br> - <li class="inline"><a href="#opt">Configuration Options</a><br> - <li class="inline"><a href="#files">Files</a> - </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 which sets and maintains the system time of day in synchronism with Internet standard time servers. 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. <tt>ntpd</tt> does most computations in 64-bit floating point arithmetic and does relatively clumsy 64-bit fixed point operations only when necessary to preserve the ultimate precision, about 232 picoseconds. While the ultimate precision is not achievable with ordinary workstations and networks of today, it may be required with future gigahertz CPU clocks and gigabit LANs.</p> - <h4 id="op">How NTP Operates</h4> - <p>The <tt>ntpd</tt> program operates by exchanging messages with one or more configured servers at designated poll intervals. When started, whether for the first or subsequent times, the program requires several exchanges from the majority of these servers so the signal processing and mitigation algorithms can accumulate and groom the data and set the clock. In order to protect the network from bursts, the initial poll interval for each server is delayed an interval randomized over a few seconds. At the default initial poll interval of 64s, several minutes can elapse before the clock is set. The initial delay to set the clock can be reduced using the <tt>iburst</tt> keyword with the <tt>server</tt> configuration command, as described on the <a href="confopt.html">Configuration Options</a> page.</p> - <p>Most operating systems and hardware of 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. After the machine has synchronized to a NTP server, the operating system corrects the chip from time to time. In case there is no TOY chip or for some reason its time is more than 1000s from the server time, <tt>ntpd</tt> assumes something must be terribly wrong and the only reliable action is for the operator to intervene and set the clock by hand. This causes <tt>ntpd</tt> to exit with a panic message to the system log. The <tt>-g</tt> option overrides this check and the clock will be set to the server time regardless of the chip time. However, and to protect against broken hardware, such as when the CMOS battery fails or the clock counter becomes defective, once the clock has been set, an error greater than 1000s will cause <tt>ntpd</tt> to exit anyway.</p> - <p>Under ordinary conditions, <tt>ntpd</tt> adjusts the clock in small steps so that the timescale is effectively continuous and without discontinuities. Under conditions of extreme network congestion, the roundtrip delay jitter can exceed three seconds and the synchronization distance, which is equal to one-half the roundtrip delay plus error budget terms, can become very large. The <tt>ntpd</tt> algorithms discard sample offsets exceeding 128 ms, unless the interval during which no sample offset is less than 128 ms exceeds 900s. The first sample after that, no matter what the offset, steps the clock to the indicated time. In practice this reduces the false alarm rate where the clock is stepped in error to a vanishingly low incidence.</p> - <p>As the result of this behavior, once the clock has been set, it very rarely strays more than 128 ms, even under extreme cases of network path congestion and jitter. Sometimes, in particular when <tt>ntpd</tt> is first started, the error might exceed 128 ms. This may on occasion cause the clock to be set backwards if the local clock time is more than 128 s in the future relative to the server. In some applications, this behavior may be unacceptable. If the <tt>-x</tt> option is included on the command line, the clock will never be stepped and only slew corrections will be used.</p> - <p>The issues should be carefully explored before deciding to use the <tt>-x</tt> option. The maximum slew rate possible is limited to 500 parts-per-million (PPM) as a consequence of the correctness principles on which the NTP protocol and algorithm design are based. As a result, the local clock can take a long time to converge to an acceptable offset, about 2,000 s for each second the clock is outside the acceptable range. During this interval the local 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>In spite of the above precautions, sometimes when large frequency errors are present the resulting time offsets stray outside the 128-ms range and an eventual step or slew time correction is required. If following such a correction the frequency error is so large that the first sample is outside the acceptable range, <tt>ntpd</tt> enters the same state as when the <tt>ntp.drift</tt> file is not present. The intent of this behavior is to quickly correct the frequency and restore operation to the normal tracking mode. In the most extreme cases (<tt>time.ien.it</tt> comes to mind), there may be occasional step/slew corrections and subsequent frequency corrections. It helps in these cases to use the <tt>burst</tt> keyword when configuring the server.</p> - <h4 id="freq">Frequency Discipline</h4> - <p>The <tt>ntpd</tt> behavior at startup depends on whether the frequency file, usually <tt>ntp.drift</tt>, exists. This file contains the latest estimate of clock frequency error. When the <tt>ntpd</tt> is started and the file does not exist, the <tt>ntpd</tt> enters a special mode designed to quickly adapt to the particular system clock oscillator time and frequency error. This takes approximately 15 minutes, after which the time and frequency are set to nominal values and the <tt>ntpd</tt> enters normal mode, where the time and frequency are continuously tracked relative to the server. After one hour the frequency file is created and the current frequency offset written to it. When the <tt>ntpd</tt> is started and the file does exist, the <tt>ntpd</tt> frequency is initialized from the file and enters normal mode immediately. After that the current frequency offset is written to the file at hourly intervals.</p> - <h4 id="modes">Operating Modes</h4> - <p><tt>ntpd</tt> can operate in any of several modes, including symmetric active/passive, client/server broadcast/multicast and manycast, as described in the <a href="assoc.html">Association Management</a> page. It normally operates continuously while monitoring for small changes in frequency and trimming the clock for the ultimate precision. However, it can operate in a one-time mode where the time is set from an external server and frequency is set from a previously recorded frequency file. A broadcast/multicast or manycast client can discover remote servers, compute server-client propagation delay correction factors and configure itself automatically. This makes it possible to deploy a fleet of workstations without specifying configuration details specific to the local environment.</p> - <p>By default, <tt>ntpd</tt> runs in continuous mode where each of possibly several external servers is polled at intervals determined by an intricate state machine. The state machine measures the incidental roundtrip delay jitter and oscillator frequency wander and determines the best poll interval using a heuristic algorithm. Ordinarily, and in most operating environments, the state machine will start with 64s intervals and eventually increase in steps to 1024s. A small amount of random variation is introduced in order to avoid bunching at the servers. In addition, should a server become unreachable for some time, the poll interval is increased in steps to 1024s in order to reduce network overhead.</p> - <p>In some cases it may not be practical for <tt>ntpd</tt> to run continuously. A common workaround has been to run the <tt>ntpdate</tt> program from a <tt>cron</tt> job at designated times. However, this program does not have the crafted signal processing, error checking and mitigation algorithms of <tt>ntpd</tt>. The <tt>-q</tt> option is intended for this purpose. Setting this option will cause <tt>ntpd</tt> to exit just after setting the clock for the first time. The procedure for initially setting the clock is the same as in continuous mode; most applications will probably want to specify the <tt>iburst</tt> keyword with the <tt>server</tt> configuration command. With this keyword a volley of messages are exchanged to groom the data and the clock is set in about 10 s. If nothing is heard after a couple of minutes, the daemon times out and exits. After a suitable period of mourning, the <tt>ntpdate</tt> program may be retired.</p> - <p>When kernel support is available to discipline the clock frequency, which is the case for stock Solaris, Tru64, Linux and FreeBSD, a useful feature is available to discipline the clock frequency. First, <tt>ntpd</tt> is run in continuous mode with selected servers in order to measure and record the intrinsic clock frequency offset in the frequency file. It may take some hours for the frequency and offset to settle down. Then the <tt>ntpd</tt> is stopped and run in one-time mode as required. At each startup, the frequency is read from the file and initializes the kernel frequency.</p> - <h4 id="poll">Poll Interval Control</h4> - <p>This version of NTP includes an intricate state machine to reduce the network load while maintaining a quality of synchronization consistent with the observed jitter and wander. There are a number of ways to tailor the operation in order enhance accuracy by reducing the interval or to reduce network overhead by increasing it. However, the user is advised to carefully consider the consequences of changing the poll adjustment range from the default minimum of 64 s to the default maximum of 1,024 s. The default minimum can be changed with the <tt>tinker minpoll</tt> command to a value not less than 16 s. This value is used for all configured associations, unless overridden by the <tt>minpoll</tt> option on the configuration command. Note that most device drivers will not operate properly if the poll interval is less than 64 s and that the broadcast server and manycast client associations will also use the default, unless overridden.</p> - <p>In some cases involving dial up or toll services, it may be useful to increase the minimum interval to a few tens of minutes and maximum interval to a day or so. Under normal operation conditions, once the clock discipline loop has stabilized the interval will be increased in steps from the minimum to the maximum. However, this assumes the intrinsic clock frequency error is small enough for the discipline loop correct it. The capture range of the loop is 500 PPM at an interval of 64s decreasing by a factor of two for each doubling of interval. At a minimum of 1,024 s, for example, the capture range is only 31 PPM. If the intrinsic error is greater than this, the drift file <tt>ntp.drift</tt> will have to be specially tailored to reduce the residual error below this limit. Once this is done, the drift file is automatically updated once per hour and is available to initialize the frequency on subsequent daemon restarts.</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 is in progress.</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. In common scenarios this occurs during other than work hours. The filter maintains a shift register that 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.</p> - <p>The filter is activated by the <tt>tinker</tt> command and <tt>huffpuff</tt> keyword, as described in the <a href="miscopt.html">Miscellaneous Options</a> page.</p> - <h4 id="notes">Notes</h4> - <p>If NetInfo support is built into <tt>ntpd</tt>, then <tt>ntpd</tt> will attempt to read its configuration from the NetInfo if the default ntp.conf 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> - <dd>Require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is the default. - <dt><tt>-A</tt> - <dd>Do not require cryptographic authentication for broadcast client, multicast client and symmetric passive associations. This is almost never a good idea. - <dt><tt>-b</tt> - <dd>Enable the client to synchronize to broadcast servers. - <dt><tt>-c <i>conffile</i></tt> - <dd>Specify the name and path of the configuration file, default <tt>/etc/ntp.conf</tt>. - <dt><tt>-d</tt> - <dd>Specify debugging mode. This option may occur more than once, with each occurrence indicating greater detail of display. - <dt><tt>-D <i>level</i></tt> - <dd>Specify debugging level directly. - <dt><tt>-f <i>driftfile</i></tt> - <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> configuration command. - <dt><tt>-g</tt> - <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. - <dt><tt>-i <i>jaildir</i></tt> - <dd>Chroot the server to the directory <i>jaildir</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. - <dt><tt>-k <i>keyfile</i></tt> - <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> configuration command. - <dt><tt>-l <i>logfile</i></tt> - <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> configuration command. - <dt><tt>-L</tt> - <dd>Do not listen to virtual IPs. The default is to listen. - <dt><tt>-n</tt> - <dd>Don't fork. - <dt><tt>-N</tt> - <dd>To the extent permitted by the operating system, run the <tt>ntpd</tt> at the highest priority. - <dt><tt>-p <i>pidfile</i></tt> - <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> configuration command. - <dt><tt>-P <i>priority</i></tt> - <dd>To the extent permitted by the operating system, run the <tt>ntpd</tt> at the specified priority. - <dt><tt>-q</tt> - <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. - <dt><tt>-r <i>broadcastdelay</i></tt> - <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. - <dt><tt>-s <i>statsdir</i></tt> - <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> configuration command. - <dt><tt>-t <i>key</i></tt> - <dd>Add a key number to the trusted key list. This option can occur more than once. - <dt><tt>-u <i>user[:group]</i> </tt> - <dd>Specify a user, and optionally a group, to switch to. This option is only available if the OS supports to run the server without full root privileges. Currently, this option is supported under NetBSD (configure with --enable-clockctl) and Linux (configure with --enable-linuxcaps). - <dt><tt>-U <i>interface update interval</i></tt> - <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><tt>-V <i>variable</i></tt> - <dd>Add a system variable listed by default. - <dt><tt>-x</tt> - <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. - </dl> - <h4 id="cfg">The Configuration File</h4> - <p>Ordinarily, <tt>ntpd</tt> reads the <tt>ntp.conf</tt> configuration file at startup time 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/multicast client, with all peers being determined by listening to broadcasts at run time.</p> - <p>Usually, the configuration file is installed in the <tt>/etc</tt> directory, 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 keyword followed by a list of arguments, some of which may be optional, separated by whitespace. Commands may not be continued over multiple lines. Arguments 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 following descriptions, 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="opt">Configuration Options</h4> - <p><a href="confopt.html">Server Options</a><br> - <a href="authopt.html">Authentication Options</a><br> - <a href="monopt.html">Monitoring Options</a><br> - <a href="accopt.html">Access Control Options</a><br> - <a href="manyopt.html">Automatic NTP Configuration Options</a><br> - <a href="clockopt.html">Reference Clock Options</a><br> - <a href="miscopt.html">Miscellaneous Options</a></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%"><tt>/etc/ntp.drift</tt></td> - <td width="20%"><tt>-f</tt></td> - <td width="20%"><tt>driftfile</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> - +<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> +<!-- Changed by: Harlan &, 10-Feb-2014 --> +<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 -->10-Mar-2014 05:14<!-- #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="#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> ] [ -I <i>InterfaceOrAddress</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 synchronizes 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 compatible 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 broadcast 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 continuous 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>-4</tt> + <dd>Force DNS resolution of host names to the IPv4 namespace. + <dt><tt>-6</tt> + <dd>Force DNS resolution of host names to the IPv6 namespace. + <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. Without the option the default is <tt>/etc/ntp.conf</tt>.</dd> + <dt><tt>-d</tt></dt> + <dd> Disable switching into daemon mode, so <tt>ntpd</tt> stays attached to the starting terminal which will get all the debugging printout. Also, ^C will kill it. 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, with <tt>level</tt> corresponding to the numbe of <tt>-d</tt> options..</dd> + <dt><tt>-f <i>driftfile</i></tt></dt> + <dd>Specify the name and path of the frequency file. This is the same operation as the <tt>driftfile <i>driftfile</i></tt> configuration command. + <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. 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="--mdns"><tt>-m</tt></dt> + <dd>Once the system clock is synchronized, register with mDNS as an available server.</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 ms) 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 old 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><br> + <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%">Option</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%"><tt>conffile</tt></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%">none</td> + <td width="20%"><tt>keysdir</tt></td> + </tr> +</table> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> </html> diff --git a/contrib/ntp/html/ntpdate.html b/contrib/ntp/html/ntpdate.html index 30d8cad..9216b6c 100644 --- a/contrib/ntp/html/ntpdate.html +++ b/contrib/ntp/html/ntpdate.html @@ -1,72 +1,81 @@ <!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 -->9-Feb-2014 03:34<!-- #EndDate --> + UTC</p> +<br clear="left"> +<hr> +<p>Disclaimer: This program has known bugs and deficiencies and nobody +has volunteered to fix them in a long time. The good news is the +functionality originally intended for this program is available in the <tt>ntpd</tt> and +<tt>sntp</tt> programs. See the <a +href="http://support.ntp.org/Dev/DeprecatingNtpdate">Deprecating +<tt>ntpdate</tt> topic</a> in the NTP Support wiki +for a thorough discussion and analysis of the issues. +See the <tt>-q</tt> command line option in the <a +href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> +page and/or the <a href="sntp.html"><tt>sntp</tt> - Simple Network Time +Protocol (SNTP) Client</a> page. After a suitable period of mourning, the <tt>ntpdate</tt> program will be retired from this distribution.</p> +<h4>Synopsis</h4> +<tt>ntpdate [ -46bBdqsuv ] [ -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> +<p><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> +<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, if the <tt>-u</tt> flag was not specified, 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>. 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></dt> + <dd>Force the time to always be slewed using the adjtime() system call, even if the measured offset is greater than +-500 ms. The default is to step the time using settimeofday() if the offset is greater than +-500 ms. Note that, if the offset is much greater than +-500 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></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 and using an unprivileged port. 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, 2, 3 or 4. The default is 4. 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 for outgoing packets. This is most useful when behind a firewall that blocks incoming traffic to privileged ports, and you want to synchronize with hosts beyond the firewall. Note that the <tt>-d</tt> option always uses unprivileged ports. + <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> diff --git a/contrib/ntp/html/ntpdc.html b/contrib/ntp/html/ntpdc.html index 92fde1d..7a68dd2 100644 --- a/contrib/ntp/html/ntpdc.html +++ b/contrib/ntp/html/ntpdc.html @@ -1,215 +1,178 @@ <!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="99">04:11 AM</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="294">Monday, November 27, 2006</csobj></p> - <br clear="left"> - <h4>More Help</h4> - <script type="text/javascript" language="javascript" src="scripts/links12.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. - <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. - <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> +<!-- Changed by: Harlan &, 31-Jan-2014 --> +<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, deprecated puppy.</p> +<p>Last update: + <!-- #BeginDate format:En2m -->31-Jan-2014 06:54<!-- #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 [ -46dilnps ] [ -c <i>command</i> ] [ <i>host</i> ] [ ... ]</tt> +<h4>Description</h4> +<p><tt>ntpdc</tt> is deprecated - please use <tt>ntpq</tt> now, as it uses a more sane interface and can provide all of the information that <tt>ntpdc</tt> used to provide.</p> +<p><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> +<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>-d</tt> + <dd>Turn on debugging mode. + <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>clockstat <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>Note that some directives, like <tt>enable pps</tt>, are only supported on certain versions of <tt>ntpd</tt>.</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 | minpoll <i>N</i> | <tt>maxpoll</tt> <i>N</i> [...] ]</tt></tt></dt> + <dt><tt>addpeer <i>peer_address</i> [ <tt>prefer | 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>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> diff --git a/contrib/ntp/html/ntpdsim.html b/contrib/ntp/html/ntpdsim.html index 31eccf8..3f823df 100644 --- a/contrib/ntp/html/ntpdsim.html +++ b/contrib/ntp/html/ntpdsim.html @@ -1,73 +1,71 @@ <!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/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>The mushroom knows all the command line options.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">20:07</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="223">Friday, June 16, 2006</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <h4>Table of Contents</h4> - <ul> - <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> - <pre>rm ./ntpstats/* +<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 -->11-Sep-2010 05:55<!-- #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> - <pre>disable kernel +<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> diff --git a/contrib/ntp/html/ntpdsim_new.html b/contrib/ntp/html/ntpdsim_new.html index 47c226a..54c6743 100644 --- a/contrib/ntp/html/ntpdsim_new.html +++ b/contrib/ntp/html/ntpdsim_new.html @@ -1,47 +1,54 @@ <!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/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>The mushroom knows all the command line options.</p> - <p>Last update: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">21:32</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="223">Friday, June 16, 2006</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links7.txt"></script> - <h4>Table of Contents</h4> - <ul> - <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> - <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>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 -->31-Jan-2014 06:54<!-- #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> +<hr> +<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 <tt>simulate</tt> 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 <tt>simulate</tt> command even though they are used to mark the end of a normal NTP configuration command. While a newline is an "end of command" terminator for other configuration commands, in the <tt>simulate</tt> stanza <tt>;</tt> (the semicolon) is the "end of command" terminator.</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 @@ -52,51 +59,52 @@ # Simulation configuration simulate { - simulation_duration = 86400 - beep_delay = 3600 + simulation_duration = 86400; + beep_delay = 3600; # Server 1 server = louie.udel.edu { - server_offset = 0 + server_offset = 0; duration = 50000 { - freq_offset = 400 - wander = 1.0 - jitter = 0.001 - prop_delay = 0.001 - proc_delay = 0.001 + freq_offset = 400; + wander = 1.0; + jitter = 0.001; + prop_delay = 0.001; + proc_delay = 0.001; } duration = 6400 { - freq_offset = 200 - wander = 1.0 - jitter = 0.001 - prop_delay = 0.001 - proc_delay = 0.001 + freq_offset = 200; + wander = 1.0; + jitter = 0.001; + prop_delay = 0.001; + proc_delay = 0.001; } } # Server 2 server = baldwin.udel.edu { - server_offset = 0.02 + server_offset = 0.02; duration = 10000 { - freq_offset = 400 - wander = 1.0 - jitter = 0.001 - prop_delay = 0.5 - proc_delay = 0.001 + freq_offset = 400; + wander = 1.0; + jitter = 0.001; + prop_delay = 0.5; + proc_delay = 0.001; } duration = 60000 { - freq_offset = 200 - wander = 1.0 - jitter = 0.05 - prop_delay = 0.005 - proc_delay = 0.001 + freq_offset = 200; + wander = 1.0; + jitter = 0.05; + prop_delay = 0.005; + 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> diff --git a/contrib/ntp/html/ntpq.html b/contrib/ntp/html/ntpq.html index 4c077e2..1aa8df3 100644 --- a/contrib/ntp/html/ntpq.html +++ b/contrib/ntp/html/ntpq.html @@ -1,264 +1,654 @@ <!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> - - <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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:45</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>More Help</h4> - <script type="text/javascript" language="javascript" src="scripts/links12.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 variables 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> - <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</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 <tt>-c</tt> options may be given. - <dt><tt>-d</tt> - <dd>Turn on debugging mode. - <dt><tt>-i</tt> - <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. - <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 the <tt>peers</tt> interactive command. - </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>helpl [<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>addvars <i>variable_name</i> [ = <i>value</i>] [...]</tt><br> - <tt>rmvars <i>variable_name</i> [...]</tt><br> - <tt>clearvars</tt> - <dd>The data carried by NTP mode 6 messages consists of a list of items of the form <tt><i>variable_name</i> = <i>value</i></tt>, where the <tt>= <i>value</i></tt> is ignored, and can be omitted, in requests to the server to read variables. <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 their 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. - <dt><tt>cooked</tt> - <dd>Causes output from query commands to be "cooked", so that variables which are recognized by <tt>ntpq</tt> will have their values reformatted for human consumption. Variables which <tt>ntpq</tt> thinks should have a decodable value but didn't are marked with a trailing <tt>?</tt>. - <dt><tt>debug more | less | off</tt> - <dd>Turns internal query program debugging on and off. - <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 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. - <dt><tt>ntpversion 1 | 2 | 3 | 4</tt> - <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. - <dt><tt>passwd</tt> - <dd>This command prompts for a password (which will not be echoed) which will be used to authenticate configuration requests. The password must correspond to the key configured for NTP server for this purpose. - <dt><tt>quit</tt> - <dd>Exit <tt>ntpq</tt>. - <dt><tt>raw</tt> - <dd>Causes all output from query commands is printed as received from the remote server. The only formating/interpretation done on the data is to transform nonascii data into a printable (but barely understandable) form. - <dt><tt>timeout <i>millseconds</i></tt> - <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. - </dl> - <h4>Control Message Commands</h4> - <p>Each association known to an NTP server has a 16 bit integer association identifier. NTP control messages which carry peer variables must identify the peer the values correspond to by including its association ID. An association ID of 0 is special, and indicates the variables are system variables, whose names are drawn from a separate name space.</p> - <p>Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be printed in some format. Most commands currently implemented send a single message and expect a single response. The current exceptions are the peers command, which will send a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which will iterate over a range of associations.</p> - <dl> - <dt><tt>associations</tt> - <dd>Obtains and prints a list of association identifiers and peer statuses for in-spec peers of the server being queried. The list is printed in columns. The first of these is an index numbering the associations from 1 for internal use, the second the actual association identifier returned by the server and the third the status word for the peer. This is followed by a number of columns containing data decoded from the status word. See the peers command for a decode of the <tt>condition</tt> field. Note that the data returned by the <tt>associations</tt> command is cached internally in <tt>ntpq</tt>. The index is then of use when dealing with stupid servers which use association identifiers which are hard for humans to type, in that for any subsequent commands which require an association identifier as an argument, the form &index may be used as an alternative. - <dt><tt>clockvar [<i>assocID</i>] [<i>variable_name</i> [ = <i>value</i> [...]] [...]</tt> - <dt><tt>cv [<i>assocID</i>] [<i>variable_name</i> [ = <i>value</i> [...] ][...]</tt> - <dd>Requests that a list of the server's clock variables be sent. Servers which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or zero the request is for the variables of the <tt>system clock</tt> and will generally get a positive response from all servers with a clock. If the server treats clocks as pseudo-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. Omitting the variable list will cause the server to return a default variable display. - <dt><tt>lassociations</tt> - <dd>Obtains and prints a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This command differs from the <tt>associations</tt> command only for servers which retain state for out-of-spec client associations (i.e., fuzzballs). Such associations are normally omitted from the display when the <tt>associations</tt> command is used, but are included in the output of <tt>lassociations</tt>. - <dt><tt>lpassociations</tt> - <dd>Print data for all associations, including out-of-spec client associations, from the internally cached list of associations. This command differs from <tt>passociations</tt> only when dealing with fuzzballs. - <dt><tt>lpeers</tt> - <dd>Like R peers, except a summary of all associations for which the server is maintaining state is printed. This can produce a much longer list of peers from fuzzball servers. - <dt><tt>mreadlist <i>assocID</i> <i>assocID</i></tt><br> - <tt>mrl <i>assocID</i> <i>assocID</i></tt> - <dd>Like the <tt>readlist</tt> command, except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent <tt>associations</tt> command. - <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> - <dd>Like the <tt>readvar</tt> command, except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent <tt>associations</tt> command. - <dt><tt>opeers</tt> - <dd>An old form of the <tt>peers</tt> command with the reference ID replaced by the local interface address. - <dt><tt>passociations</tt> - <dd>Displays association data concerning in-spec peers from the internally cached list of associations. This command performs identically to the <tt>associations</tt> except that it displays the internally stored data rather than making a new query. - <dt><tt>peers</tt> - <dd>Obtains a current list peers of the server, along with a summary of each peer's state. Summary information includes the address of the remote peer, the reference ID (0.0.0.0 if this is unknown), the stratum of the remote peer, the type of the peer (local, unicast, multicast or broadcast), when the last packet was received, the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in milliseconds. The character at the left margin of each line shows the synchronization status of the association and is a valuable diagnostic tool. The encoding and meaning of this character, called the tally code, is given later in this page. - <dt><tt>pstatus <i>assocID</i></tt> - <dd>Sends a read status request to the server for the given association. The names and values of the peer variables returned will be printed. Note that the status word from the header is displayed preceding the variables, both in hexadecimal and in pidgeon English. - <dt><tt>readlist [ <i>assocID</i> ]</tt><br> - <tt>rl [ <i>assocID</i> ]</tt> - <dd>Requests that the values of the variables in the internal variable list be returned by the server. If the association ID is omitted or is 0 the variables are assumed to be system variables. Otherwise they are treated as peer variables. If the internal variable list is empty a request is sent without data, which should induce the remote server to return a default display. - <dt><tt>readvar <i>assocID</i> <i>variable_name</i> [ = <i>value</i> ] [ ...]</tt><br> - <tt>rv <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i> ] [...]</tt> - <dd>Requests that the values of the specified variables be returned by the server by sending a read variables request. If the association ID is omitted or is given as zero the variables are system variables, otherwise they are peer variables and the values returned will be those of the corresponding peer. Omitting the variable list will send a request with no data which should induce the server to return a default display. The encoding and meaning of the variables derived from NTPv3 is given in RFC-1305; the encoding and meaning of the additional NTPv4 variables are given later in this page. - <dt><tt>writevar <i>assocID</i> <i>variable_name</i> [ = <i>value</i> [ ...]</tt> - <dd>Like the readvar request, except the specified variables are written instead of read. - <dt><tt>writelist [ <i>assocID</i> ]</tt> - <dd>Like the readlist request, except the internal list variables are written instead of read. - </dl> - <h4>Tally Codes</h4> - <p>The character in the left margin in the <tt>peers</tt> billboard, called the tally code, shows the fate of each association in the clock selection process. Following is a list of these characters, the pigeon used in the <tt>rv</tt> command, and a short explanation of the condition revealed.</p> - <dl> - <dt><tt>space reject</tt> - <dd>The peer is discarded as unreachable, synchronized to this server (synch loop) or outrageous synchronization distance. - <dt><tt>x falsetick</tt> - <dd>The peer is discarded by the intersection algorithm as a falseticker. - <dt><tt>. excess</tt> - <dd>The peer is discarded as not among the first ten peers sorted by synchronization distance and so is probably a poor candidate for further consideration. - <dt><tt>- outlyer</tt> - <dd>The peer is discarded by the clustering algorithm as an outlyer. - <dt><tt>+ candidat</tt> - <dd>The peer is a survivor and a candidate for the combining algorithm. - <dt><tt># selected</tt> - <dd>The peer is a survivor, but not among the first six peers sorted by synchronization distance. If the association is ephemeral, it may be demobilized to conserve resources. - <dt><tt>* sys.peer</tt> - <dd>The peer has been declared the system peer and lends its variables to the system variables. - <dt><tt>o pps.peer</tt> - <dd>The peer has been declared the system peer and lends its variables to thesystem variables. However, the actual system synchronization is derived from a pulse-per-second (PPS) signal, either indirectly via the PPS reference clock driver or directly via kernel interface. - </dl> - <h4>System Variables</h4> - <p>The <tt>status, leap, stratum, precision, rootdelay, rootdispersion, refid, reftime, poll, offset, and frequency</tt> variables are described in RFC-1305 specification. Additional NTPv4 system variables include the following.</p> - <dl> - <dt><tt>version</tt> - <dd>Everything you might need to know about the software version and generation time. - <dt><tt>processor</tt> - <dd>The processor and kernel identification string. - <dt><tt>system</tt> - <dd>The operating system version and release identifier. - <dt><tt>state</tt> - <dd>The state of the clock discipline state machine. The values are described in the architecture briefing on the NTP Project page linked from www.ntp.org. - <dt><tt>peer</tt> - <dd>The internal integer used to identify the association currently designated the system peer. - <dt><tt>jitter</tt> - <dd>The estimated time error of the system clock measured as an exponential average of RMS time differences. - <dt><tt>stability</tt> - <dd>The estimated frequency stability of the system clock measured as an exponential average of RMS frequency differences. - </dl> - <p>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 dance:</p> - <dl> - <dt><tt>flags</tt> - <dd>The current flags word bits and message digest algorithm identifier (NID) in hex format. The high order 16 bits of the four-byte word contain the NID from the OpenSSL ligrary, while the low-order bits are interpreted as follows: - <dd> - <dl> - <dt><tt>0x01</tt> - <dd>autokey enabled - <dt><tt>0x02</tt> - <dd>NIST leapseconds file loaded - <dt><tt>0x10</tt> - <dd>PC identity scheme - <dt><tt>0x20</tt> - <dd>IFF identity scheme - <dt><tt>0x40</tt> - <dd>GQ identity scheme - </dl> - <dt><tt>hostname</tt> - <dd>The name of the host as returned by the Unix <tt>gethostname()</tt> library function. - <dt><tt>hostkey</tt> - <dd>The NTP filestamp of the host key file. - <dt><tt>cert</tt> - <dd>A list of certificates held by the host. Each entry includes the subject, issuer, flags and NTP filestamp in order. The bits are interpreted as follows: - <dd> - <dl> - <dt><tt>0x01</tt> - <dd>certificate has been signed by the server - <dt><tt>0x02</tt> - <dd>certificate is trusted - <dt><tt>0x04</tt> - <dd>certificate is private - <dt><tt>0x08</tt> - <dd>certificate contains errors and should not be trusted - </dl> - <dt><tt>leapseconds</tt> - <dd>The NTP filestamp of the NIST leapseconds file. - <dt><tt>refresh</tt> - <dd>The NTP timestamp when the host public cryptographic values were refreshed and signed. - <dt><tt>signature</tt> - <dd>The host digest/signature scheme name from the OpenSSL library. - <dt><tt>tai</tt> - <dd>The TAI-UTC offset in seconds obtained from the NIST leapseconds table. - </dl> - <h4>Peer Variables</h4> - <p>The <tt>status, srcadr, srcport, dstadr, dstport, leap, stratum, precision, rootdelay, rootdispersion, readh, hmode, pmode, hpoll, ppoll, offset, delay, dspersion, reftime</tt> variables are described in the RFC-1305 specification, as are the timestamps <tt>org, rec and xmt</tt>. Additional NTPv4 system variables include the following.</p> - <dl> - <dt><tt>flash</tt> - <dd>The flash code for the most recent packet received. The encoding and meaning of these codes is given later in this page. - <dt><tt>jitter</tt> - <dd>The estimated time error of the peer clock measured as an exponential average of RMS time differences. - <dt><tt>unreach</tt> - <dd>The value of the counter which records the number of poll intervals since the last valid packet was received. - </dl> - <p>When the NTPv4 daemon is compiled with the OpenSSL software library, additional peer variables are displayed, including the following:</p> - <dl> - <dt><tt>flags</tt> - <dd>The current flag bits. This word is the server host status word with additional bits used by the Autokey state machine. See the source code for the bit encoding. - <dt><tt>hostname</tt> - <dd>The server host name. - <dt><tt>initkey <i>key</i></tt> - <dd>The initial key used by the key list generator in the Autokey protocol. - <dt><tt>initsequence <i>index</i></tt> - <dd>The initial index used by the key list generator in the Autokey protocol. - <dt><tt>signature</tt> - <dd>The server message digest/signature scheme name from the OpenSSL software library. - <dt><tt>timestamp <i>time</i></tt> - <dd>The NTP timestamp when the last Autokey key list was generated and signed. - </dl> - <h4>Flash Codes</h4> - <p>The <tt>flash</tt> code is a valuable debugging aid displayed in the peer variables list. It shows the results of the original sanity checks defined in the NTP specification RFC-1305 and additional ones added in NTPv4. There are 12 tests designated <tt>TEST1</tt> through <tt>TEST12</tt>. The tests are performed in a certain order designed to gain maximum diagnostic information while protecting against accidental or malicious errors. The <tt>flash</tt> variable is initialized to zero as each packet is received. If after each set of tests one or more bits are set, the packet is discarded.</p> - <p>Tests <tt>TEST1</tt> through <tt>TEST3</tt> check the packet timestamps from which the offset and delay are calculated. If any bits are set, the packet is discarded; otherwise, the packet header variables are saved. <tt>TEST4</tt> and <tt>TEST5</tt> are associated with access control and cryptographic authentication. If any bits are set, the packet is discarded immediately with nothing changed.</p> - <p>Tests <tt>TEST6</tt> through <tt>TEST8</tt> check the health of the server. If any bits are set, the packet is discarded; otherwise, the offset and delay relative to the server are calculated and saved. <tt>TEST9</tt> checks the health of the association itself. If any bits are set, the packet is discarded; otherwise, the saved variables are passed to the clock filter and mitigation algorithms.</p> - <p>Tests <tt>TEST10</tt> through <tt>TEST12</tt> check the authentication state using Autokey public-key cryptography, as described in the <a href="authopt.html">Authentication Options</a> page. If any bits are set and the association has previously been marked reachable, the packet is discarded; otherwise, the originate and receive timestamps are saved, as required by the NTP protocol, and processing continues.</p> - <p>The <tt>flash</tt> bits for each test are defined as follows.</p> - <dl> - <dt><tt>0x001 TEST1</tt> - <dd>Duplicate packet. The packet is at best a casual retransmission and at worst a malicious replay. - <dt><tt>0x002 TEST2</tt> - <dd>Bogus packet. The packet is not a reply to a message previously sent. This can happen when the NTP daemon is restarted and before somebody else notices. - <dt><tt>0x004 TEST3</tt> - <dd>Unsynchronized. One or more timestamp fields are invalid. This normally happens when the first packet from a peer is received. - <dt><tt>0x008 TEST4</tt> - <dd>Access is denied. See the <a href="accopt.html">Access Control Options</a> page. - <dt><tt>0x010 TEST5</tt> - <dd>Cryptographic authentication fails. See the <a href="authopt.html">Authentication Options</a> page. - <dt><tt>0x020TEST6</tt> - <dd>The server is unsynchronized. Wind up its clock first. - <dt><tt>0x040 TEST7</tt> - <dd>The server stratum is at the maximum than 15. It is probably unsynchronized and its clock needs to be wound up. - <dt><tt>0x080 TEST8</tt> - <dd>Either the root delay or dispersion is greater than one second, which is highly unlikely unless the peer is unsynchronized to Mars. - <dt><tt>0x100 TEST9</tt> - <dd>Either the peer delay or dispersion is greater than one second, which is higly unlikely unless the peer is on Mars. - <dt><tt>0x200 TEST10</tt> - <dd>The autokey protocol has detected an authentication failure. See the <a href="authopt.html">Authentication Options</a> page. - <dt><tt>0x400 TEST11</tt> - <dd>The autokey protocol has not verified the server or peer is proventic and has valid public key credentials. See the <a href="authopt.html">Authentication Options</a> page. - <dt><tt>0x800 TEST12</tt> - <dd>A protocol or configuration error has occurred in the public key algorithms or a possible intrusion event has been detected. See the <a href="authopt.html">Authentication Options</a> page. - </dl> - <h4>Bugs</h4> - <p>The peers command is non-atomic and may occasionally result in spurious error messages about invalid associations occurring and terminating the command. The timeout time is a fixed constant, which means you wait a long time for timeouts since it assumes sort of a worst case. The program should improve the timeout estimate as it sends queries to a particular host, but doesn't.</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>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 -->31-Jan-2014 06:54<!-- #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 [-46dinp] [-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 id="help"><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 id="addvars"><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 id="cooked"><tt>cooked</tt></dt> + <dd>Display server messages in prettyprint format.</dd> + <dt id="debug"><tt>debug more | less | off</tt></dt> + <dd>Turns internal query program debugging on and off.</dd> + <dt id="delay"><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 id="host"><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 id="hostnames"><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 id="keyid"><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 ID configured in <tt>ntp.conf</tt> for this purpose.</dd> + <dt id="keytype"><tt>keytype</tt></dt> + <dd>Specify the digest algorithm to use for authenticated requests, with default <tt>MD5</tt>. If the OpenSSL library is installed, digest can be be any message digest algorithm supported by the library. The current selections are: <tt>MD2</tt>, <tt>MD4</tt>, <tt>MD5</tt>, <tt>MDC2</tt>, <tt>RIPEMD160</tt>, <tt>SHA</tt> and <tt>SHA1</tt>.</dd> + <dt id="ntpversion"><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 id="passwd"><tt>passwd</tt></dt> + <dd>This command prompts for a password to authenticate requests. The password must correspond to the key ID configured in <tt>ntp.conf</tt> for this purpose.</dd> + <dt id="quit"><tt>quit</tt></dt> + <dd>Exit <tt>ntpq</tt>.</dd> + <dt id="raw"><tt>raw</tt></dt> + <dd>Display server messages as received and without reformatting.</dd> + <dt id="timeout"><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 id="cv"><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 associations supporting a reference clock.</dd> + <dt id=":config"><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 id="config-from-file"><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 required.</dd> + <dt id="ifstats"><tt>ifstats</tt></dt> + <dd>Display statistics for each local network address. Authentication is required.</dd> + <dt id="iostats"><tt>iostats</tt></dt> + <dd>Display network and reference clock I/O statistics.</dd> + <dt id="kerninfo"><tt>kerninfo</tt></dt> + <dd>Display kernel loop and PPS statistics. As with other ntpq output, times are in milliseconds. The precision value displayed is in milliseconds as well, unlike the precision system variable.</dd> + <dt id="lassoc"><tt>lassociations</tt></dt> + <dd>Perform the same function as the associations command, except 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 id="mreadvar"><tt>mreadvar <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i>[ ... ]</tt></dt> + <dt id="mrv"><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 id="passoc"><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 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 of server relative to this host</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 specifies 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 id="writevar"><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="sysinfo"><tt>sysinfo</tt></dt> + <dd>Display operational summary.</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>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 offset of server relative to this host</td> + </tr> + <tr> + <td><tt>sys_jitter</tt></td> + <td>combined system jitter</td> + </tr> + <tr> + <td><tt>frequency</tt></td> + <td> frequency offset (PPM) relative to hardware clock</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 for this host</td> + </tr> + <tr> + <td><tt>ident</tt></td> + <td>Autokey group name for this host</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 peer variables appear 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>ident</tt></td> + <td>Autokey group name for this association</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 variable 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 interleaved modes. It represents + the internal queuing, buffering and transmission delays for the preceding + 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 scheme</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 appear 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 time code 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> diff --git a/contrib/ntp/html/ntptime.html b/contrib/ntp/html/ntptime.html index a9ea33b..8f14761 100644 --- a/contrib/ntp/html/ntptime.html +++ b/contrib/ntp/html/ntptime.html @@ -1,48 +1,46 @@ <!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 kernel time variables</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3><tt>ntptime</tt> - read 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">18:46</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> - <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 -->11-Sep-2010 05:55<!-- #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> diff --git a/contrib/ntp/html/ntptrace.html b/contrib/ntp/html/ntptrace.html index 3b533f9..bd47bd9 100644 --- a/contrib/ntp/html/ntptrace.html +++ b/contrib/ntp/html/ntptrace.html @@ -1,49 +1,42 @@ <!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">18:47</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> - <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> determines where a given Network Time Protocol (NTP) server gets its time from, and follows the chain of NTP servers back to their master time source. If given no arguments, it starts with <tt>localhost</tt>. Here is an example of the output from <tt>ntptrace</tt>:</p> - <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>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 -->31-Jan-2014 06:54<!-- #EndDate --> + UTC</p> +<br clear="left"> +<hr> +<h4>Synopsis</h4> +<tt>ntptrace [ -n ] [ -m <i>maxhosts</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>-m <i>max_hosts</i></tt></dt> + <dd>Sets the upper limit of the number of hosts to check (default: unlimited).</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> +</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> diff --git a/contrib/ntp/html/orphan.html b/contrib/ntp/html/orphan.html new file mode 100644 index 0000000..3174c8e --- /dev/null +++ b/contrib/ntp/html/orphan.html @@ -0,0 +1,42 @@ +<!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 -->4-Aug-2011 23:40<!-- #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 server, called the orphan parent.</p> +<p>Hosts sharing the same common subnet, including potential orphan parents and potential orphan children, can be enabled for orphan mode using the <tt>orphan <em>stratum</em></tt> option of the <a href="miscopt.html#tos"> <tt>tos command</tt></a>, where <tt><i>stratum</i></tt> is some stratum less than 16 and greater than any anticipated stratum that might occur with configured Internet time servers. However, sufficient headroom should remain so every subnet host dependent on the orphan children has stratum less than 16. Where no associations for other servers or reference clocks are configured, the orphan stratum can be set to 1. These are the same considerations that guide the local clock driver stratum selection.</p> +<p>In order to avoid premature enabling orphan mode, a holdoff delay occurs when the daemon is first started and when all sources have been lost after that. The delay is intended to allow time for other sources to become reachable and selectable. Only when the delay has expired with no sources will orphan mode be enabled. By default the delay is 300 s (five minutes), but this can be changed using the <tt> orphanwait</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p> +<p>A orphan parent with no sources shows reference ID <font face="Courier New, Courier, Monaco, monospace">LOOP</font> if + operating at stratum 1 and 127.0.0.1 (IPv4 loopback address) otherwise. + While ordinary NTP clients use a selection metric based on delay + and dispersion, orphan children use a metric computed from the IP + address of each core server. Each orphan child chooses the orphan + parent as the core server with the smallest metric.</p> +<p>For orphan mode to work well, each core server with available sources should operate at the same stratum. All core servers and orphan children should include the same <font face="Courier New, Courier, Monaco, monospace">tos</font> command in the configuration file. Each orphan child should include in the configuration file all root servers.</p> +<div align="center"> <img src="pic/peer.gif" alt="gif"> + <p>Figure 1. Orphan Peer Configuration</p> +</div> +<p>For example, consider the peer network configuration in Figure 1, where two or more campus primary or secondary (stratum 2) servers are configured with reference clocks or public Internet primary servers and with each other using symmetric modes. With this configuration a server that loses all sources continues to discipline the system clock using the other servers as backup. Only the core servers and orphan children need to be enabled for orphan mode.</p> +<div align="center"> <img src="pic/broad.gif" alt="gif"> + <p>Figure 2. Orphan Broadcast Configuration</p> +</div> +<p>For broadcast networks each core server is configured in both broadcast server and broadcast client modes as shown in Figure 2. Orphan children operate as broadcast clients of all core servers. As in peer networks, the core servers back up each other and only they and the orphan children need to be enabled for orphan mode.</p> +<p>In normal operation subnet hosts operate below stratum 5, so the subnet is automatically configured as described in the NTP specification. If all UTC sources are lost, all core servers become orphans and the orphan children will select the same core server to become the orphan parent.</p> +<hr> +<p> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</p> +</body> +</html> diff --git a/contrib/ntp/html/parsedata.html b/contrib/ntp/html/parsedata.html index 301d8e7..4d3734b 100644 --- a/contrib/ntp/html/parsedata.html +++ b/contrib/ntp/html/parsedata.html @@ -12,6 +12,9 @@ <body> <h3>NTP PARSE clock data formats</h3> <p>The parse driver currently supports several clocks with different query mechanisms. In order for you to find a sample that might be similar to a clock you might want to integrate into parse I'll sum up the major features of the clocks (this information is distributed in the parse/clk_*.c and ntpd/refclock_parse.c files).</p> +<p>Last update: + <!-- #BeginDate format:En2m -->21-Oct-2010 23:44<!-- #EndDate --> + UTC</p> <hr> <h4>Meinberg clocks</h4> <pre> @@ -346,4 +349,4 @@ Meinberg: start=<STX>, end=<ETX>, sync on start <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> </body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/parsenew.html b/contrib/ntp/html/parsenew.html index 4f11a46..244612f 100644 --- a/contrib/ntp/html/parsenew.html +++ b/contrib/ntp/html/parsenew.html @@ -11,6 +11,9 @@ <body> <h3>How to build new PARSE clocks</h3> <p>Here is an attempt to sketch out what you need to do in order to add another clock to the parse driver: Currently the implementation is being cleaned up - so not all information in here is completely correct. Refer to the included code where in doubt.</p> +<p>Last update: + <!-- #BeginDate format:En2m -->13-Oct-2010 00:33<!-- #EndDate --> + UTC</p> <p>Prerequisites:</p> <ul> <li>Does the system you want the clock connect to have the include files termio.h or termios.h ? (You need that for the parse driver) @@ -185,9 +188,7 @@ struct clockformat </ol> <p>Well, this is very sketchy, i know. But I hope it helps a little bit. The best way is to look which clock comes closest to your and tweak that code.</p> <p>Two sorts of clocks are used with parse. Clocks that automatically send their time code (once a second) do not need entries in the poll routines because they send the data all the time. The second sort are the clocks that need a command sent to them in order to reply with a time code (like the Trimble clock).</p> - <p>For questions: <a href="mailto:%20kardel <AT> acm.org">kardel - <AT> - acm.org</a>.</p> + <p>For questions: <a href="mailto:%20kardel AT acm.org">kardel@acm.org</a>.</p> <p>Please include an exact description on how your clock works. (initialisation, TTY modes, strings to be sent to it, responses received from the clock).</p> <hr> <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> @@ -195,4 +196,4 @@ struct clockformat <body></body> -</html>
\ No newline at end of file +</html> diff --git a/contrib/ntp/html/pic/9400n.jpg b/contrib/ntp/html/pic/9400n.jpg Binary files differnew file mode 100644 index 0000000..9209b90 --- /dev/null +++ b/contrib/ntp/html/pic/9400n.jpg diff --git a/contrib/ntp/html/pic/alice11.gif b/contrib/ntp/html/pic/alice11.gif Binary files differnew file mode 100644 index 0000000..62d0c9b --- /dev/null +++ b/contrib/ntp/html/pic/alice11.gif diff --git a/contrib/ntp/html/pic/alice13.gif b/contrib/ntp/html/pic/alice13.gif Binary files differnew file mode 100644 index 0000000..c928ff7 --- /dev/null +++ b/contrib/ntp/html/pic/alice13.gif diff --git a/contrib/ntp/html/pic/alice15.gif b/contrib/ntp/html/pic/alice15.gif Binary files differnew file mode 100644 index 0000000..e17b5fd --- /dev/null +++ b/contrib/ntp/html/pic/alice15.gif diff --git a/contrib/ntp/html/pic/alice23.gif b/contrib/ntp/html/pic/alice23.gif Binary files differnew file mode 100644 index 0000000..bc258a0 --- /dev/null +++ b/contrib/ntp/html/pic/alice23.gif diff --git a/contrib/ntp/html/pic/alice31.gif b/contrib/ntp/html/pic/alice31.gif Binary files differnew file mode 100644 index 0000000..ea3d20c --- /dev/null +++ b/contrib/ntp/html/pic/alice31.gif diff --git a/contrib/ntp/html/pic/alice32.gif b/contrib/ntp/html/pic/alice32.gif Binary files differnew file mode 100644 index 0000000..db7cc40 --- /dev/null +++ b/contrib/ntp/html/pic/alice32.gif diff --git a/contrib/ntp/html/pic/alice35.gif b/contrib/ntp/html/pic/alice35.gif Binary files differnew file mode 100644 index 0000000..aa0ca43 --- /dev/null +++ b/contrib/ntp/html/pic/alice35.gif diff --git a/contrib/ntp/html/pic/alice38.gif b/contrib/ntp/html/pic/alice38.gif Binary files differnew file mode 100644 index 0000000..e40adba --- /dev/null +++ b/contrib/ntp/html/pic/alice38.gif diff --git a/contrib/ntp/html/pic/alice44.gif b/contrib/ntp/html/pic/alice44.gif Binary files differnew file mode 100644 index 0000000..953387e --- /dev/null +++ b/contrib/ntp/html/pic/alice44.gif diff --git a/contrib/ntp/html/pic/alice47.gif b/contrib/ntp/html/pic/alice47.gif Binary files differnew file mode 100644 index 0000000..6b27160 --- /dev/null +++ b/contrib/ntp/html/pic/alice47.gif diff --git a/contrib/ntp/html/pic/alice51.gif b/contrib/ntp/html/pic/alice51.gif Binary files differnew file mode 100644 index 0000000..1e9082a --- /dev/null +++ b/contrib/ntp/html/pic/alice51.gif diff --git a/contrib/ntp/html/pic/alice61.gif b/contrib/ntp/html/pic/alice61.gif Binary files differnew file mode 100644 index 0000000..5687c38 --- /dev/null +++ b/contrib/ntp/html/pic/alice61.gif diff --git a/contrib/ntp/html/pic/barnstable.gif b/contrib/ntp/html/pic/barnstable.gif Binary files differnew file mode 100644 index 0000000..17d9cdd --- /dev/null +++ b/contrib/ntp/html/pic/barnstable.gif diff --git a/contrib/ntp/html/pic/beaver.gif b/contrib/ntp/html/pic/beaver.gif Binary files differnew file mode 100644 index 0000000..3d0c8eb --- /dev/null +++ b/contrib/ntp/html/pic/beaver.gif diff --git a/contrib/ntp/html/pic/boom3.gif b/contrib/ntp/html/pic/boom3.gif Binary files differnew file mode 100644 index 0000000..1a95d40 --- /dev/null +++ b/contrib/ntp/html/pic/boom3.gif diff --git a/contrib/ntp/html/pic/boom3a.gif b/contrib/ntp/html/pic/boom3a.gif Binary files differnew file mode 100644 index 0000000..14bfe5b --- /dev/null +++ b/contrib/ntp/html/pic/boom3a.gif diff --git a/contrib/ntp/html/pic/boom4.gif b/contrib/ntp/html/pic/boom4.gif Binary files differnew file mode 100644 index 0000000..0661ac4 --- /dev/null +++ b/contrib/ntp/html/pic/boom4.gif diff --git a/contrib/ntp/html/pic/broad.gif b/contrib/ntp/html/pic/broad.gif Binary files differnew file mode 100644 index 0000000..b372bb5 --- /dev/null +++ b/contrib/ntp/html/pic/broad.gif diff --git a/contrib/ntp/html/pic/bustardfly.gif b/contrib/ntp/html/pic/bustardfly.gif Binary files differnew file mode 100644 index 0000000..b5c6e91 --- /dev/null +++ b/contrib/ntp/html/pic/bustardfly.gif diff --git a/contrib/ntp/html/pic/c51.jpg b/contrib/ntp/html/pic/c51.jpg Binary files differnew file mode 100644 index 0000000..d90ad55 --- /dev/null +++ b/contrib/ntp/html/pic/c51.jpg diff --git a/contrib/ntp/html/pic/description.jpg b/contrib/ntp/html/pic/description.jpg Binary files differnew file mode 100644 index 0000000..2153180 --- /dev/null +++ b/contrib/ntp/html/pic/description.jpg diff --git a/contrib/ntp/html/pic/discipline.gif b/contrib/ntp/html/pic/discipline.gif Binary files differnew file mode 100644 index 0000000..3280d14 --- /dev/null +++ b/contrib/ntp/html/pic/discipline.gif diff --git a/contrib/ntp/html/pic/dogsnake.gif b/contrib/ntp/html/pic/dogsnake.gif Binary files differnew file mode 100644 index 0000000..1f9755d --- /dev/null +++ b/contrib/ntp/html/pic/dogsnake.gif diff --git a/contrib/ntp/html/pic/driver29.gif b/contrib/ntp/html/pic/driver29.gif Binary files differnew file mode 100644 index 0000000..b0415ae --- /dev/null +++ b/contrib/ntp/html/pic/driver29.gif diff --git a/contrib/ntp/html/pic/driver43_1.gif b/contrib/ntp/html/pic/driver43_1.gif Binary files differnew file mode 100644 index 0000000..f1ff7c7 --- /dev/null +++ b/contrib/ntp/html/pic/driver43_1.gif diff --git a/contrib/ntp/html/pic/driver43_2.jpg b/contrib/ntp/html/pic/driver43_2.jpg Binary files differnew file mode 100644 index 0000000..c53639c --- /dev/null +++ b/contrib/ntp/html/pic/driver43_2.jpg diff --git a/contrib/ntp/html/pic/fg6021.gif b/contrib/ntp/html/pic/fg6021.gif Binary files differnew file mode 100644 index 0000000..e6e3071 --- /dev/null +++ b/contrib/ntp/html/pic/fg6021.gif diff --git a/contrib/ntp/html/pic/fg6039.jpg b/contrib/ntp/html/pic/fg6039.jpg Binary files differnew file mode 100644 index 0000000..25fc7c4 --- /dev/null +++ b/contrib/ntp/html/pic/fg6039.jpg diff --git a/contrib/ntp/html/pic/fig_3_1.gif b/contrib/ntp/html/pic/fig_3_1.gif Binary files differnew file mode 100644 index 0000000..a280a89 --- /dev/null +++ b/contrib/ntp/html/pic/fig_3_1.gif diff --git a/contrib/ntp/html/pic/flatheads.gif b/contrib/ntp/html/pic/flatheads.gif Binary files differnew file mode 100644 index 0000000..707cb8c --- /dev/null +++ b/contrib/ntp/html/pic/flatheads.gif diff --git a/contrib/ntp/html/pic/flt1.gif b/contrib/ntp/html/pic/flt1.gif Binary files differnew file mode 100644 index 0000000..d08c5ac --- /dev/null +++ b/contrib/ntp/html/pic/flt1.gif diff --git a/contrib/ntp/html/pic/flt2.gif b/contrib/ntp/html/pic/flt2.gif Binary files differnew file mode 100644 index 0000000..d4909cb --- /dev/null +++ b/contrib/ntp/html/pic/flt2.gif diff --git a/contrib/ntp/html/pic/flt3.gif b/contrib/ntp/html/pic/flt3.gif Binary files differnew file mode 100644 index 0000000..1eefbe1 --- /dev/null +++ b/contrib/ntp/html/pic/flt3.gif diff --git a/contrib/ntp/html/pic/flt4.gif b/contrib/ntp/html/pic/flt4.gif Binary files differnew file mode 100644 index 0000000..3f8b671 --- /dev/null +++ b/contrib/ntp/html/pic/flt4.gif diff --git a/contrib/ntp/html/pic/flt5.gif b/contrib/ntp/html/pic/flt5.gif Binary files differnew file mode 100644 index 0000000..52714ac --- /dev/null +++ b/contrib/ntp/html/pic/flt5.gif diff --git a/contrib/ntp/html/pic/flt6.gif b/contrib/ntp/html/pic/flt6.gif Binary files differnew file mode 100644 index 0000000..0451e86 --- /dev/null +++ b/contrib/ntp/html/pic/flt6.gif diff --git a/contrib/ntp/html/pic/flt7.gif b/contrib/ntp/html/pic/flt7.gif Binary files differnew file mode 100644 index 0000000..55f07d8 --- /dev/null +++ b/contrib/ntp/html/pic/flt7.gif diff --git a/contrib/ntp/html/pic/flt8.gif b/contrib/ntp/html/pic/flt8.gif Binary files differnew file mode 100644 index 0000000..04bd32b --- /dev/null +++ b/contrib/ntp/html/pic/flt8.gif diff --git a/contrib/ntp/html/pic/flt9.gif b/contrib/ntp/html/pic/flt9.gif Binary files differnew file mode 100644 index 0000000..e107c48 --- /dev/null +++ b/contrib/ntp/html/pic/flt9.gif diff --git a/contrib/ntp/html/pic/freq1211.gif b/contrib/ntp/html/pic/freq1211.gif Binary files differnew file mode 100644 index 0000000..2a56416 --- /dev/null +++ b/contrib/ntp/html/pic/freq1211.gif diff --git a/contrib/ntp/html/pic/gadget.jpg b/contrib/ntp/html/pic/gadget.jpg Binary files differnew file mode 100644 index 0000000..6289911 --- /dev/null +++ b/contrib/ntp/html/pic/gadget.jpg diff --git a/contrib/ntp/html/pic/gps167.jpg b/contrib/ntp/html/pic/gps167.jpg Binary files differnew file mode 100644 index 0000000..8a87a75 --- /dev/null +++ b/contrib/ntp/html/pic/gps167.jpg diff --git a/contrib/ntp/html/pic/group.gif b/contrib/ntp/html/pic/group.gif Binary files differnew file mode 100644 index 0000000..26aff06 --- /dev/null +++ b/contrib/ntp/html/pic/group.gif diff --git a/contrib/ntp/html/pic/hornraba.gif b/contrib/ntp/html/pic/hornraba.gif Binary files differnew file mode 100644 index 0000000..3077d75 --- /dev/null +++ b/contrib/ntp/html/pic/hornraba.gif diff --git a/contrib/ntp/html/pic/igclock.gif b/contrib/ntp/html/pic/igclock.gif Binary files differnew file mode 100644 index 0000000..940f330 --- /dev/null +++ b/contrib/ntp/html/pic/igclock.gif diff --git a/contrib/ntp/html/pic/neoclock4x.gif b/contrib/ntp/html/pic/neoclock4x.gif Binary files differnew file mode 100755 index 0000000..4df95af --- /dev/null +++ b/contrib/ntp/html/pic/neoclock4x.gif diff --git a/contrib/ntp/html/pic/offset1211.gif b/contrib/ntp/html/pic/offset1211.gif Binary files differnew file mode 100644 index 0000000..8a73287 --- /dev/null +++ b/contrib/ntp/html/pic/offset1211.gif diff --git a/contrib/ntp/html/pic/oncore_evalbig.gif b/contrib/ntp/html/pic/oncore_evalbig.gif Binary files differnew file mode 100644 index 0000000..931a7f1 --- /dev/null +++ b/contrib/ntp/html/pic/oncore_evalbig.gif diff --git a/contrib/ntp/html/pic/oncore_remoteant.jpg b/contrib/ntp/html/pic/oncore_remoteant.jpg Binary files differnew file mode 100644 index 0000000..0f1d048 --- /dev/null +++ b/contrib/ntp/html/pic/oncore_remoteant.jpg diff --git a/contrib/ntp/html/pic/oncore_utplusbig.gif b/contrib/ntp/html/pic/oncore_utplusbig.gif Binary files differnew file mode 100644 index 0000000..dec7e71 --- /dev/null +++ b/contrib/ntp/html/pic/oncore_utplusbig.gif diff --git a/contrib/ntp/html/pic/oz2.gif b/contrib/ntp/html/pic/oz2.gif Binary files differnew file mode 100644 index 0000000..d4982f0 --- /dev/null +++ b/contrib/ntp/html/pic/oz2.gif diff --git a/contrib/ntp/html/pic/panda.gif b/contrib/ntp/html/pic/panda.gif Binary files differnew file mode 100644 index 0000000..6feb743 --- /dev/null +++ b/contrib/ntp/html/pic/panda.gif diff --git a/contrib/ntp/html/pic/pd_om006.gif b/contrib/ntp/html/pic/pd_om006.gif Binary files differnew file mode 100644 index 0000000..3266285 --- /dev/null +++ b/contrib/ntp/html/pic/pd_om006.gif diff --git a/contrib/ntp/html/pic/pd_om011.gif b/contrib/ntp/html/pic/pd_om011.gif Binary files differnew file mode 100644 index 0000000..06566b9 --- /dev/null +++ b/contrib/ntp/html/pic/pd_om011.gif diff --git a/contrib/ntp/html/pic/peer.gif b/contrib/ntp/html/pic/peer.gif Binary files differnew file mode 100644 index 0000000..35bd36f --- /dev/null +++ b/contrib/ntp/html/pic/peer.gif diff --git a/contrib/ntp/html/pic/pogo.gif b/contrib/ntp/html/pic/pogo.gif Binary files differnew file mode 100644 index 0000000..68dacbe --- /dev/null +++ b/contrib/ntp/html/pic/pogo.gif diff --git a/contrib/ntp/html/pic/pogo1a.gif b/contrib/ntp/html/pic/pogo1a.gif Binary files differnew file mode 100644 index 0000000..433e467 --- /dev/null +++ b/contrib/ntp/html/pic/pogo1a.gif diff --git a/contrib/ntp/html/pic/pogo3a.gif b/contrib/ntp/html/pic/pogo3a.gif Binary files differnew file mode 100644 index 0000000..49f1359 --- /dev/null +++ b/contrib/ntp/html/pic/pogo3a.gif diff --git a/contrib/ntp/html/pic/pogo4.gif b/contrib/ntp/html/pic/pogo4.gif Binary files differnew file mode 100644 index 0000000..e0a3b17 --- /dev/null +++ b/contrib/ntp/html/pic/pogo4.gif diff --git a/contrib/ntp/html/pic/pogo5.gif b/contrib/ntp/html/pic/pogo5.gif Binary files differnew file mode 100644 index 0000000..87ad8e4 --- /dev/null +++ b/contrib/ntp/html/pic/pogo5.gif diff --git a/contrib/ntp/html/pic/pogo6.gif b/contrib/ntp/html/pic/pogo6.gif Binary files differnew file mode 100644 index 0000000..3f98c52 --- /dev/null +++ b/contrib/ntp/html/pic/pogo6.gif diff --git a/contrib/ntp/html/pic/pogo7.gif b/contrib/ntp/html/pic/pogo7.gif Binary files differnew file mode 100644 index 0000000..36befe7 --- /dev/null +++ b/contrib/ntp/html/pic/pogo7.gif diff --git a/contrib/ntp/html/pic/pogo8.gif b/contrib/ntp/html/pic/pogo8.gif Binary files differnew file mode 100644 index 0000000..6860efb --- /dev/null +++ b/contrib/ntp/html/pic/pogo8.gif diff --git a/contrib/ntp/html/pic/pzf509.jpg b/contrib/ntp/html/pic/pzf509.jpg Binary files differnew file mode 100644 index 0000000..b51303b --- /dev/null +++ b/contrib/ntp/html/pic/pzf509.jpg diff --git a/contrib/ntp/html/pic/pzf511.jpg b/contrib/ntp/html/pic/pzf511.jpg Binary files differnew file mode 100644 index 0000000..c470af2 --- /dev/null +++ b/contrib/ntp/html/pic/pzf511.jpg diff --git a/contrib/ntp/html/pic/rabbit.gif b/contrib/ntp/html/pic/rabbit.gif Binary files differnew file mode 100644 index 0000000..ab6ec5f --- /dev/null +++ b/contrib/ntp/html/pic/rabbit.gif diff --git a/contrib/ntp/html/pic/radio2.jpg b/contrib/ntp/html/pic/radio2.jpg Binary files differnew file mode 100644 index 0000000..ceb7c76 --- /dev/null +++ b/contrib/ntp/html/pic/radio2.jpg diff --git a/contrib/ntp/html/pic/sheepb.jpg b/contrib/ntp/html/pic/sheepb.jpg Binary files differnew file mode 100644 index 0000000..1b3323e --- /dev/null +++ b/contrib/ntp/html/pic/sheepb.jpg diff --git a/contrib/ntp/html/pic/stack1a.jpg b/contrib/ntp/html/pic/stack1a.jpg Binary files differnew file mode 100644 index 0000000..1e023cb --- /dev/null +++ b/contrib/ntp/html/pic/stack1a.jpg diff --git a/contrib/ntp/html/pic/stats.gif b/contrib/ntp/html/pic/stats.gif Binary files differnew file mode 100644 index 0000000..b0d0aaa --- /dev/null +++ b/contrib/ntp/html/pic/stats.gif diff --git a/contrib/ntp/html/pic/sx5.gif b/contrib/ntp/html/pic/sx5.gif Binary files differnew file mode 100644 index 0000000..504e38b --- /dev/null +++ b/contrib/ntp/html/pic/sx5.gif diff --git a/contrib/ntp/html/pic/thunderbolt.jpg b/contrib/ntp/html/pic/thunderbolt.jpg Binary files differnew file mode 100644 index 0000000..49253ab --- /dev/null +++ b/contrib/ntp/html/pic/thunderbolt.jpg diff --git a/contrib/ntp/html/pic/time1.gif b/contrib/ntp/html/pic/time1.gif Binary files differnew file mode 100644 index 0000000..88e7042 --- /dev/null +++ b/contrib/ntp/html/pic/time1.gif diff --git a/contrib/ntp/html/pic/tonea.gif b/contrib/ntp/html/pic/tonea.gif Binary files differnew file mode 100644 index 0000000..195a3df --- /dev/null +++ b/contrib/ntp/html/pic/tonea.gif diff --git a/contrib/ntp/html/pic/tribeb.gif b/contrib/ntp/html/pic/tribeb.gif Binary files differnew file mode 100644 index 0000000..59e8a7c --- /dev/null +++ b/contrib/ntp/html/pic/tribeb.gif diff --git a/contrib/ntp/html/pic/wingdorothy.gif b/contrib/ntp/html/pic/wingdorothy.gif Binary files differnew file mode 100644 index 0000000..3f2e0be --- /dev/null +++ b/contrib/ntp/html/pic/wingdorothy.gif diff --git a/contrib/ntp/html/poll.html b/contrib/ntp/html/poll.html new file mode 100644 index 0000000..aeb9c32 --- /dev/null +++ b/contrib/ntp/html/poll.html @@ -0,0 +1,26 @@ +<!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>Poll Process</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>Poll Process</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:17<!-- #EndDate --> + UTC</p> +<hr> +<p>The poll process sends NTP packets at intervals determined by the clock discipline algorithm. The process is designed to provide a sufficient update rate to maximize accuracy while minimizing network overhead. The process is designed to operate over a poll exponent range between 3 (8 s) and 17 (36 hr). The minimum and maximum poll exponent within this range can be set using the <tt>minpoll</tt> and <tt>maxpoll</tt> options of the <a href="confopt.html#option"><tt>server</tt></a> command, with default 6 (64 s) and 10 (1024 s), respectively.</p> +<p> The poll interval is managed by a heuristic algorithm developed over several years of experimentation. It depends on an exponentially weighted average of clock offset differences, called <em>clock jitter</em>, and a jiggle counter, which is initially set to zero. When a clock update is received and the offset exceeds the clock jitter by a factor of 4, the jiggle counter is increased by the poll exponent; otherwise, it is decreased by twice the poll exponent. If the jiggle counter is greater than an arbitrary threshold of 30, it is reset to 0 and the the poll exponent is increased by 1. If the jiggle counter is less than -30, it is set to 0 and the poll exponent decreased by 1. In effect, the algorithm has a relatively slow reaction to good news, but a relatively fast reaction to bad news.</p> +<p>As an option of the <a href="confopt.html#option"><tt>server</tt></a> command, instead of a single packet, the poll process can send a burst of several packets at 2-s intervals. This is designed to reduce the time to synchronize the clock at initial startup (<tt>iburst</tt>) and/or to reduce the phase noise at the longer poll intervals (<tt>burst</tt>). The <tt>iburst</tt> option is effective only when the server is unreachable, while the <tt>burst</tt> option is effective only when the server is reachable. The two options are independent of each other and both can be enabled at the same time.</p> +<p>For the <tt>iburst</tt> option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the <tt>burst</tt> option, the number of packets in the burst is determined by the difference between the current poll exponent and the minimum poll exponent as a power of 2. For instance, with the default minimum poll exponent of 6 (64 s), only one packet is sent for every poll, while the full number of eight packets is sent at poll exponents of 9 (512 s) or more. This insures that the average headway will never exceed the minimum headway.</p> +<p>The burst options can result in increased load on the network if not carefully designed. Both options are affected by the provisions described on the <a href="rate.html">Rate Management and the Kiss-o'-Death Packet</a> page. In addition, when <tt>iburst</tt> or <tt>burst</tt> are enabled, the first packet of the burst is sent, but the remaining packets sent only when the reply to the fist packet is received. If no reply has been received after a timeout set by the <tt>minpoll</tt> option, the first packet is sent again. This means that, even if a server is unreachable, the network load is no more than at the minimum poll interval.</p> +<p>To further reduce the network load when a server is unreachable, an unreach timer is incremented by 1 at each poll interval, but is set to 0 as each packet is received. If the timer exceeds the <em>unreach threshold</em> set at 10, the poll exponent is incremented by 1 and the unreach timer set to 0. This continues until the poll exponent reaches the maximum set by the <tt>maxpoll</tt> option.</p> +<hr> +<p> + <script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</p> +</body> +</html> diff --git a/contrib/ntp/html/pps.html b/contrib/ntp/html/pps.html index b9fcd7f..0b9bd5d 100644 --- a/contrib/ntp/html/pps.html +++ b/contrib/ntp/html/pps.html @@ -1,41 +1,47 @@ <!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">18:48</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links11.txt"></script> - <hr> - <p>Some radio clocks and related timekeeping gear have a pulse-per-second (PPS) signal that can be used to discipline the system clock to a high degree of precision, typically to the order less than 10 <font face="Symbol">m</font>s in time and 0.01 parts-per-million (PPM) in frequency. This page describes the hardware and software necessar for NTP to use this signal.</p> - <img src="pic/gadget.jpg" alt="gif" align="left">A Gadget Box built by Chuck Hanavin<br clear="left"> - <h4>Gadget Box</h4> - <p>The PPS signal can be connected in either of two ways: via the data carrier detector (DCD) pin of a serial port or via the acknowledge (ACK) pin of a parallel port, depending on the hardware and operating system. Note that NTP no longer supports connection via the data leads of a serial port. 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>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 PPSAPI application program interface defined in [1] 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. As the PPSAPI is expected to become an IETF cross-platform standard, it should be used by new applications.</p> - <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> - <h4>PPS Driver</h4> - <p>In the preferred mode of operation, PPS signals are processed by the <a href="drivers/driver22.html">PPS Clock Discipline</a> driver and other clock drivers which might be involved need not know or care about them. In some cases where there is no other driver, time might be obtained from remote NTP servers via the network and local PPS signals, for instance from a calibrated cesium oscillator, used to stabilize the frequency and remove network jitter. Note that the <tt>pps</tt> configuration command has been obsoleted by this driver.</p> - <p>The PPS driver operates in conjunction with a preferred peer, as described in the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. One of the drivers described in the <a href="refclock.html">Reference Clock Drivers</a> page or another NTP server furnishes the coarse timing and disambiguates the seconds numbering of the PPS signal itself. The NTP daemon mitigates between the clock driver or NTP server and the PPS driver as described in that page in order to provide the most accurate time, while respecting the various types of equipment failures that could happen.</p> - <p>Some Unix system kernels support a PPS signal directly, as described in the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. Specifically, the PPS driver can be used to direct the PPS signal to the kernel for use as a discipline source for both time and frequency. The presence of the kernel support is automatically detected during the NTP build process and supporting code automatically compiled. Note that the PPS driver does not normally enable the PPS kernel code, since performance is generally better without it. However, this code can be enabled by a driver fudge flag if necessary.</p> - <p>Some configurations may include multiple radio clocks with individual PPS outputs. In some PPSAPI designs multiple PPS signals can be connected to multiple instances of the PPS driver. In such cases the NTP mitigation and grooming algorithms operate with all the radio timecodes and PPS signals to develop the highest degree of redundancy and survivability.</p> - <h4>Reference</h4> - <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. <a href="http://www.eecis.udel.edu/mills/database/rfc/rfc2783.txt">ASCII</a> - </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>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 -->10-Mar-2014 05:17<!-- #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 μ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> +<h4 id="gadget">Gadget Box</h4> +<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>timepps.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="use">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> diff --git a/contrib/ntp/html/prefer.html b/contrib/ntp/html/prefer.html index 00225d1..0fd0b8f 100644 --- a/contrib/ntp/html/prefer.html +++ b/contrib/ntp/html/prefer.html @@ -1,72 +1,93 @@ <!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>Mitigation Rules and the prefer Keyword</title> - <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: <csobj format="ShortTime" h="25" locale="00000409" region="0" t="DateTime" w="61">18:49</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links10.txt"></script> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#intro">Introduction</a> - <li class="inline"><a href="#prefer">The <tt>prefer</tt> Peer</a> - <li class="inline"><a href="#peer">Peer Classification</a> - <li class="inline"><a href="#miti">Mitigation Rules</a> - <li class="inline"><a href="#pps">Using the Pulse-per-Second (PPS) Signal</a> - </ul> - <hr> - <h4 id="intro">Introduction</h4> - <p>The mechanics of the NTP algorithms which select the best data sample from each available server and the best subset of the server population have been finely crafted to resist network jitter, faults in the network or server operations, and to deliver the best possible accuracy. Most of the time these algorithms do a good job without requiring explicit manual tailoring of the configuration file. However, there are times when the accuracy can be improved by some careful tailoring. The following sections explain how to do this using explicit configuration items and special signals, when available, that are generated by some radio clocks and laboratory instruments.</p> - <p>In order to provide robust backup sources, primary (stratum-1) servers are usually operated in a diversity configuration, in which the server operates with a number of remote servers in addition to one or more radio or modem clocks. In these configurations the suite of algorithms used in NTP to refine the data from each peer separately and to select and combine the data from a number of servers and clocks. As the result of these algorithms, a set of <i>survivors</i> are identified which can presumably provide the most reliable and accurate time. Ordinarily, the individual clock offsets of the survivors are combined on a weighted average basis to produce an offset used to control the system clock.</p> - <p>However, because of small but significant systematic time offsets between the survivors, it is in general not possible to achieve the lowest jitter and highest stability in these configurations. This happens because the selection algorithm tends to <i>clockhop</i> between survivors of substantially the same quality, but showing small systematic offsets between them. In addition, there are a number of configurations involving pulse-per-second (PPS) signals, modem backup services and other special cases, so that a set of mitigation rules becomes necessary to select a single peer from among the survivors. These rules are based on a set of special characteristics of the various remote servers and reference clock drivers specified in the configuration file.</p> - <h4 id="prefer">The <tt>prefer</tt> Peer</h4> - <p>The mitigation rules are designed to provide an intelligent selection between various sources of substantially the same statistical quality without compromising the normal operation of the NTP algorithms. While they have been implemented in NTP Version 4 and will be incorporated in the NTP Version 4 specification when published, they are not in the NTP Version 3 specification RFC-1305. The rules are based on the concept of <i>prefer peer</i>, which is specified by including the <tt>prefer</tt> keyword with the associated <tt>server</tt> or <tt>peer</tt> command in the configuration file. This keyword can be used with any server or peer, but is most commonly used with a radio clock. While the rules do not forbid it, it does not seem useful to designate more than one peer as preferred, since the additional complexities to mitigate among them do not seem justified from on-air experience.</p> - <p>The prefer scheme works on the set of peers that have survived the sanity checks and intersection algorithms of the clock selection procedures. Ordinarily, the members of this set can be considered <i>truechimers</i> and any one of them could in principle provide correct time; however, due to various error contributions, not all can provide the most accurate and stable time. The job of the clustering algorithm, which is invoked at this point, is to select the best subset of the survivors providing the least variance in the combined ensemble average, compared to the variance in each member of the subset separately. The detailed operation of the clustering algorithm, which is given in RFC-1305, is beyond the scope of discussion here. It operates in rounds, where a survivor, presumably the worst of the lot, is discarded in each round until one of several termination conditions is met. An example terminating condition is when the number of survivors is about to be reduced below three.</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 termination condition. If the original algorithm were about to toss out the prefer peer, the algorithm terminates immediately. The prefer peer can still be discarded by the sanity checks and intersection algorithm, of course, but it will always survive the clustering algorithm. If it does not survive or for some reason it fails to provide updates, it will eventually become unreachable and the clock selection will remitigate to select the next best source.</p> - <p>Along with this behavior, the clock selection procedures are modified so that the combining algorithm is not used when a prefer peer is present. Instead, the offset of the prefer peer is used exclusively as the synchronization source. In the usual case involving a radio clock and a flock of remote stratum-1 peers, and with the radio clock designated a prefer peer, the result is that the high quality radio time disciplines the server clock as long as the radio itself remains operational and with valid time, as determined from the remote peers, sanity checks and intersection algorithm.</p> - <h4 id="peer">Peer Classification</h4> - <p>In order to understand the effects of the various intricate schemes involved, it is necessary to understand some arcane details on how the algorithms decide on a synchronization source when more than one source is available. This is done on the basis of a set of explicit mitigation rules, which define special classes of remote serves and local radio clocks as a function of configuration declarations and clock driver type:</p> - <ol> - <li>The prefer peer is designated using the <tt>prefer</tt> keyword with the <tt>server</tt> or <tt>peer</tt> commands. All other things being equal, this peer will be selected for synchronization over all other survivors of the clock selection procedures. - <li>When a PPS signal is connected via the PPS Clock Discipline driver (type 22), this is called the <i>PPS peer</i>. This driver provides precision clock corrections only within one second, so is always operated in conjunction with another server or radio clock driver, which provides the seconds numbering. The PPS peer is active only under conditions explained below. - <li>When the Undisciplined Local Clock driver (type 1) is configured, this is called the <i>local clock peer</i>. This is used either as a backup reference source (stratum greater than zero), should all other synchronization sources fail, or as the primary reference 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>When a modem driver such as the Automated Computer Time Service driver (type 18) is configured, this is called the <i>modem peer</i>. This is used either as a backup reference source, should all other primary sources fail, or as the (only) primary reference source. - <li>Where support is available, the PPS signal may be processed directly by the kernel, as described in the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. This is called the <i>kernel discipline</i>. The PPS signal can discipline the kernel in both frequency and time. The frequency discipline is active as long as the PPS interface device and signal itself is operating correctly, as determined by the kernel algorithms. The time discipline is active only under conditions explained below. - </ol> - <p>Reference clock drivers operate in the manner described in the <a href="refclock.html">Reference Clock Drivers</a> page and its dependencies. The drivers are ordinarily operated at stratum zero, so that as the result of ordinary NTP operations, the server itself operates at stratum one, as required by the NTP specification. In some cases described below, the driver is intentionally operated at an elevated stratum, so that it will be selected only if no other survivor is present with a lower stratum. In the case of the PPS peer or kernel time discipline, these sources appear active only if the prefer peer has survived the intersection and clustering algorithms, as described below, and its clock offset relative to the current local clock is less than a specified value, currently 128 ms.</p> - <p>The modem clock drivers are a special case. Ordinarily, the update interval between modem calls to synchronize the system clock is many times longer than the interval between polls of either a remote server or local radio clock. In order to provide the best stability, the operation of the clock discipline algorithm changes gradually from a phase-lock mode at the shorter update intervals to a frequency-lock mode at the longer update intervals. If remote servers or local radio clocks together with a modem peer operate in the same client, the following things can happen.</p> - <p>First the clock selection algorithm can select one or more remote servers or local radio clocks and the clock discipline algorithm will optimize for the shorter update intervals. Then, the selection algorithm can select the modem peer, which requires a much different optimization. The intent in the design is to allow the modem peer to control the system clock either when no other source is available or, if the modem peer happens to be marked as prefer, then it always controls the clock, as long as it passes the sanity checks and intersection algorithm. There still is room for suboptimal operation in this scheme, since a noise spike can still cause a clockhop either way. Nevertheless, the optimization function is slow to adapt, so that a clockhop or two does not cause much harm.</p> - <p>The local clock driver is another special case. Normally, this driver is eligible for selection only if no other source is available. When selected, vernier adjustments introduced via the configuration file or remotely using the <tt><a href="ntpdc.html">ntpdc</a> </tt>program can be used to trim the local clock frequency and time. However, if the local clock driver is designated the prefer peer, this driver is always selected and all other sources are ignored. This behavior is intended for use when the kernel time is controlled by some means external to NTP, such as the NIST <tt>lockclock</tt> algorithm or another time synchronization protocol such as DTSS. In this case the only way to disable the local clock driver is to mark it unsynchronized using the leap indicator bits. In the case of modified kernels with the <tt>ntp_adjtime()</tt> system call, this can be done automatically if the external synchronization protocol uses it to discipline the kernel time.</p> - <h4 id="miti">Mitigation Rules</h4> - <p>The mitigation rules apply in the intersection and clustering algorithms described in the NTP specification. The intersection algorithm first scans all peers with a persistent association and includes only those that satisfy specified sanity checks. In addition to the checks required by the specification, the mitigation rules require either the local-clock peer or modem peer to be included only if marked as the prefer peer. The intersection algorithm operates on the included population to select only those peers believed to represent the correct time. If one or more peers survive the algorithm, processing continues in the clustering algorithm. Otherwise, if there is a modem peer, it is declared the only survivor; otherwise, if there is a local-clock peer, it is declared the only survivor. Processing then continues in the clustering algorithm.</p> - <p>The clustering algorithm repeatedly discards outlyers in order to reduce the residual jitter in the survivor population. As required by the NTP specification, these operations continue until either a specified minimum number of survivors remain or the minimum select dispersion of the population is greater than the maximum peer dispersion of any member. The mitigation rules require an additional terminating condition which stops these operations at the point where the prefer peer is about to be discarded.</p> - <p>The mitigation rules establish the choice of <i>system peer</i>, which determines the stratum, reference identifier and several other system variables which are visible to clients of the server. In addition, they establish which source or combination of sources control the local clock.</p> - <ol> - <li>If there is a prefer peer and it is the local-clock peer or the modem peer; or, if there is a prefer peer and the kernel time discipline is active, choose the prefer peer as the system peer and its offset as the system clock offset. If the prefer peer is the local-clock peer, an offset can be calculated by the driver to produce a frequency offset in order to correct for systematic frequency errors. In case a source other than NTP is controlling the system clock, corrections determined by NTP can be ignored by using the <tt>disable pll</tt> in the configuration file. If the prefer peer is the modem peer, it must be the primary source for the reasons noted above. If the kernel time discipline is active, the system clock offset is ignored and the corrections handled directly by the kernel. - <li>If the above is not the case and there is a PPS peer, then choose it as the system peer and its offset as the system clock offset. - <li>If the above is not the case and there is a prefer peer (not the local-clock or modem peer in this case), then choose it as the system peer and its offset as the system clock offset. - <li>If the above is not the case and the peer previously chosen as the system peer is in the surviving population, then choose it as the system peer and average its offset along with the other survivors to determine the system clock offset. This behavior is designed to avoid excess jitter due to clockhopping, when switching the system peer would not materially improve the time accuracy. - <li>If the above is not the case, then choose the first candidate in the list of survivors ranked in order of synchronization distance and average its offset along with the other survivors to determine the system clock offset. This is the default case and the only case considered in the current NTP specification. - </ol> - <h4 id="pps">Using the Pulse-per-Second (PPS) Signal</h4> - <p>Most radio clocks are connected using a serial port operating at speeds of 9600 bps or higher. 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 limited to a millisecond or two. However, some radios produce a PPS signal which can be used to improve the accuracy with typical workstation servers to the order of microseconds. The details of how this can be accomplished are discussed in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. The following paragraphs discuss how the PPS signal is affected by the mitigation rules.</p> - <p>First, it should be pointed out that the PPS signal is inherently ambiguous, in that it provides a precise seconds epoch, but does not provide a way to number the seconds. In principle and most commonly, another source of synchronization, either the timecode from an associated radio clock, or even one or more remote NTP servers, is available to perform that function. In all cases, a specific, configured peer or server must be designated as associated with the PPS signal. This is done using the <tt>prefer</tt> keyword as described previously. The PPS signal can be associated in this way with any peer, but is most commonly used with the radio clock generating the PPS signal.</p> - <p>The PPS signal can be used in two ways to discipline the local clock, one using a special PPS driver described in the <a href="drivers/driver22.html">PPS Clock Discipline</a> page, the other using PPS signal support in the kernel, as described in the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. In either case, the signal must be present and within nominal jitter and wander error tolerances. In addition, the associated prefer peer must have survived the sanity checks and intersection algorithms and the dispersion settled below 1 s. This insures that the radio clock hardware is operating correctly and that, presumably, the PPS signal is operating correctly as well. Second, the absolute offset of the local clock from that peer must be less than 128 ms, or well within the 0.5-s unambiguous range of the PPS signal itself. In the case of the PPS driver, the time offsets generated from the PPS signal are propagated via the clock filter to the clock selection procedures just like any other peer. Should these pass the sanity checks and intersection algorithms, they will show up along with the offsets of the prefer peer itself. Note that, unlike the prefer peer, the PPS peer samples are not protected from discard by the clustering algorithm. These complicated procedures insure that the PPS offsets developed in this way are the most accurate, reliable available for synchronization.</p> - <p>The PPS peer remains active as long as it survives the intersection algorithm and the prefer peer is reachable; however, like any other clock driver, it runs a reachability algorithm on the PPS signal itself. If for some reason the signal fails or displays gross errors, the PPS peer will either become unreachable or stray out of the survivor population. In this case the clock selection remitigates as described above.</p> - <p>When kernel support for the PPS signal is available, the PPS signal is interfaced to the kernel serial driver code via a modem control lead. As the PPS signal is derived from external equipment, cables, etc., which sometimes fail, a good deal of error checking is done in the kernel to detect signal failure and excessive noise. The way in which the mitigation rules affect the kernel discipline is as follows.</p> - <p>PPS support requires the PPS driver (type 22) and PPSAPI interface described in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page. In order to operate, the prefer peer must be designated and the kernel support enabled by the <tt>enable pps</tt> command in the configuration file and the signal must be present and within nominal jitter and wander error tolerances. In the NTP daemon, the PPS discipline is active only when the prefer peer is among the survivors of the clustering algorithm, and its absolute offset is within 128 ms, as determined by the PPS driver. Under these conditions the kernel disregards updates produced by the NTP daemon and uses its internal PPS source instead. 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 declared inoperable 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"> +<title>Mitigation Rules and the prefer Keyword</title> +<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 -->10-Mar-2014 05:18<!-- #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">1. Introduction and Overview</a></li> + <li class="inline"><a href="#combine">2. Combine Algorithm</a></li> + <li class="inline"><a href="#clockhop">3. Anti-Clockhop Algorithm</a></li> + <li class="inline"><a href="#peer">4. Peer Classification</a></li> + <li class="inline"><a href="#prefer">5. 5. The <tt>prefer</tt> Peer</a></li> + <li class="inline"><a href="#miti">6. Mitigation Rules</a></li> + <li class="inline"><a href="#mins">7. The <tt>minsane</tt> Option</a></li> +</ul> +<hr> +<h4 id="intro">1. Introduction and Overview</h4> +<p>This page summarizes the criteria for choosing from among the survivors of the clock cluster algorithm a set of contributors to the clock discipline algorithm. The criteria are very meticulous, since they have to handle many different scenarios that may be optimized for special circumstances, including some scenarios designed to support planetary and deep space missions. For additional information on statistical principles and performance metrics, see the <a href="stats.html">Performance Metrics</a> page.</p> +<p>Recall the suite of NTP data acquisition and grooming algorithms. These algorithms proceed in five phases. Phase one discovers the available <em>sources</em> and mobilizes an association for each source found. These sources can result from explicit configuration, broadcast discovery or the pool and manycast autonomous configuration schemes. See the <a href="discover.html">Automatic Server Discovery Schemes</a> page for further information.</p> +<p> Phase two selects the <em> candidates</em> from among the sources by excluding those sources showing one or more of the errors summarized on the <a href="select.html">Clock Select Algorithm</a> page and to determine the <em>truechimers</em> from among the candidates, leaving behind the <em>falsetickers</em>. A server or peer configured with the <tt>true</tt> option is declared a truechimer independent of this algorithm. Phase four uses the algorithm described on the <a href="cluster.html">Clock Cluster Algorithm</a> page to prune the statistical outliers from the truechimers, leaving the <em>survivor list</em><em></em> as result. </p> +<p> Phase five uses a set of algorithms and mitigation rules to combined the survivor statistics and discipline the system clock. The mitigation rules select from among the survivors a <em>system peer</em> from which a set of system statistics can be inherited and passed along to dependent clients, if any. The mitigation algorithms and rules are the main topic of this page. The clock offset developed from these algorithms can discipline the system clock, either using the <a href="discipline.html">clock discipline algorithm</a> or using the kernel to discipline the system clock directly, as described on the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. </p> +<h4 id="combine">2. Combine Algorithm</h4> +<p> The clock combine algorithm uses the survivor list to produce a weighted average of both offset and jitter. Absent other considerations discussed later, the <em>combined offset</em> is used to discipline the system clock, while the <em>combined jitter</em> is augmented with other components to produce the system jitter statistic inherited by dependent clients, if any.</p> +<p> The clock combine algorithm uses a weight factor for each survivor equal to the reciprocal of the root distance. This is normalized so that the sum of the reciprocals is equal to unity. This design favors the survivors at the smallest root distance and thus the smallest maximum error.</p> +<h4 id="clockhop">3. Anti-Clockhop Algorithm</h4> +<p>The anti-clockhop algorithm is intended for cases where multiple servers are available on a fast LAN with modern computers. Typical offset differences between servers in such cases are less than 0.5 ms. However, changes between servers can result in unnecessary system jitter. The object of the anti-clockhop algorithm is to avoid changing the current system peer, unless it becomes stale or has significant offset relative to other candidates on the survivor list.</p> +<p>For the purposes of the following description, call the last selected system peer the <em>old peer</em>, and the currently selected source the <em>candidate peer</em>. At each update, the candidate peer is selected as the first peer on the survivor list sorted by increasing root distance. The algorithm initializes the -<em>clockhop threshold</em> with the value of <tt>mindist</tt>, by default 1 ms. </p> +<p>The anti-clockhop algorithm is called immediately after the combine algorithm. If there was no old peer or the old and candidate peers are the same, the candidate peer becomes the system peer. If the old peer and the candidate peer are different, the algorithm measures the difference between the offset of the old peer and the candidate peer. If the difference exceeds the clockhop threshold, the candidate peer becomes the system peer and the clockhop threshold is restored to its original value. If the difference is less than the clockhop threshold, the old peer continues as the system peer. However, at each subsequent update, the algorithm reduces the clockhop threshold by half. Should operation continue in this way, the candidate peer will eventually become the system peer.</p> +<h4 id="peer">4. 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>A selectable association configured for a remote server or peer is classified as a <i>client association</i>. All other selectable associations are classified as <i>device driver associations</i> of one kind or another. In general, one or more sources of either type will be available in each installation.</li> + <li>If all sources have been lost and one or more hosts on a common DMZ network have specified the orphan stratum in the <tt>orphan</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, each of them can become an <i>orphan parent</i>. Dependent orphan children on the same DMZ network will see the orphan parents as if synchronized to a server at the orphan stratum. Note that, as described on the <a href="orphan.html">Orphan Mode</a> page, all orphan children will select the same orphan parent for synchronization.</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 configure as a PPS driver if the hardware facilities are available. The PPS driver provides precision clock discipline only within ±0.4 s, so it 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>. It can be used either as a backup source (stratum greater than zero) should all sources fail, or as the primary source (stratum zero) whether or not other sources are available if the <tt>prefer</tt> option is present. The local driver can be used when the kernel time is disciplined by some other means of synchronization, such as the NIST <tt>lock clock</tt> scheme, or another synchronization protocol such as the IEEE 1588 Precision Time Protocol (PTP) or Digital Time Synchronization Service (DTSS).</li> + <li>When the Automated Computer Time Service driver (type 18) is configured, it is designated the <i>modem driver</i>. It is used either as a backup source, should all other sources fail, or as the primary source if the <tt>prefer</tt> option is present.</li> +</ol> +<h4 id="prefer">5. The <tt>prefer</tt> Peer</h4> +<p>The mitigation rules are designed to provide an intelligent selection of the system peer from among the selectable sources of different types. When used with the <tt>server</tt> or <tt>peer</tt> commands, the <tt>prefer</tt> option designates one or more sources 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. If the first one becomes un selectable, the second one is considered and so forth. This order of priority is also applicable to multiple PPS drivers, multiple modem drivers and even multiple local drivers, although that would not normally be useful.</p> +<p>The cluster algorithm works on the set of truechimers produced by the select algorithm. At each round the algorithm casts off the survivor least likely to influence the choice of system peer. If selectable, the prefer peer is never discarded; on the contrary, its potential removal becomes a termination condition. However, the prefer peer can still be discarded by the select algorithm as a falseticker; otherwise, the prefer peer becomes the system peer.</p> +<p>Ordinarily, the combine algorithm computes a weighted average of the survivor + offset and jitter to produce the final values. However, if a prefer + peer is among the survivors, the combine algorithm is not used. Instead, + the offset and jitter of the prefer peer are used exclusively as the final values. 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 + the radio clock disciplines the system clock as long as the radio itself + remains operational. However, if the radio fails or becomes a falseticker, + the combined backup sources continue to discipline the system clock.</p> +<h4 id="miti">6. Mitigation Rules</h4> +<p>As the select algorithm scans the associations for selectable candidates, the modem driver and local driver are segregated for later, but only if not designated a prefer peer. If so designated, the driver is included among the candidate population. In addition, if orphan parents are found, the parent with the lowest metric is segregated for later; the others are discarded. For this purpose the metric is defined as the four-octet IPv4 address or the first four octets of the hashed IPv6 address. The resulting candidates, including any prefer peers found, are processed by the select algorithm to produce a possibly empty set of truechimers.</p> +<p> As previously noted, the cluster algorithm casts out outliers, leaving the survivor list for later processing. The survivor list is then sorted by increasing root distance and the first entry temporarily designated the system peer. At this point the following contributors to the system clock discipline may be available:</p> +<ul> + <li>(potential) system peer, if there are survivors;</li> + <li>orphan parent, if present;</li> + <li>local driver, if present;</li> + <li>modem driver, if present;</li> + <li>prefer peer, if present;</li> + <li>PPS driver, 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 <a href="miscopt.html#tos"><tt>tos</tt></a> command, the algorithm is terminated and the system variables remain unchanged. Note that <tt>minsane</tt> is by default 1, but can be set at any value including 0.</li> + <li>If the prefer peer is among the survivors, it becomes the system peer and its offset and jitter are inherited by the corresponding system variables. Otherwise, the combine 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">7. The <tt>minsane</tt> Option</H4> +<p> The <tt>minsane</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command, the <tt>prefer</tt> option of the <tt>server</tt> and <tt>peer</tt> commands and the <tt>flag</tt> option of the <tt>fudge</tt> command for a selected 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 synchronize the system clock. The <tt>prefer</tt> option operates as described in previous sections. The <tt>flag</tt> option enables the PPS signal for the selected driver.</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 the serial timecode becomes unreliable, or if the PPS signal is + disconnected, the GPS driver stops updating the system clock and so eventually + becomes unreachable and is replaced by other sources.</p> +<p>Whether or not the GPS driver disables the PPS signal when the timecode becomes unreliable is + at the discretion of the driver. Ordinarily, the PPS signal is disabled in this case; however, when the GPS receiver has a precision holdover oscillator, the driver may elect to continue PPS discipline . In this case, <tt>minsane</tt> can be set to zero so the PPS signal continues to discipline the system clock.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/quick.html b/contrib/ntp/html/quick.html new file mode 100644 index 0000000..9b6859b --- /dev/null +++ b/contrib/ntp/html/quick.html @@ -0,0 +1,45 @@ +<!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> +<p>Last update: + <!-- #BeginDate format:En2m -->1-Dec-2012 04:44<!-- #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 -->1-Dec-2012 04:44<!-- #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 and best is to use the + Server Pool Scheme on the <a href="discover.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/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> diff --git a/contrib/ntp/html/rate.html b/contrib/ntp/html/rate.html new file mode 100644 index 0000000..2b47db8 --- /dev/null +++ b/contrib/ntp/html/rate.html @@ -0,0 +1,67 @@ +<!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"> +<style type="text/css"> +<!-- +<style1 { +color: #FF0000; + font-weight: bold; +} +--> +</style> +</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 -->10-Mar-2014 05:19<!-- #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="#intro">Introduction</a></li> + <li class="inline"><a href="#guard">Minimum Headway Time</a></li> + <li class="inline"><a href="#mah">Minimum Average Headway Time</a></li> + <li class="inline"><a href="#kiss">The Kiss-o'-Death Packet</a></li> + <li class="inline"><a href="#ref">References</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 client implementations that can clog the server and network infrastructure. On the other hand, friendly clients need to avoid configurations that can result in unfriendly behavior.</p> +<p>A review of past client abuse incidence shows the most frequent scenario is a broken client that attempts to send packets at rates of one per second or more. On one occasion due to a defective client design [1], over 750,000 clients demonstrated this abuse. 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>There are several features in the reference implementation<tt></tt> designed to defend the servers and network against accidental or intentional flood attack. Other features are used to insure that 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 requirements.</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 (KoD, 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. The first two algorithms are described on the <a href="poll.html">Poll Program</a> page; the remaining two are described in following sections.</p> +<h4 id="guard">Minimum Headway Time</h4> +<p>The headway is defined for each source as the interval between the last packet sent or received and the next packet for that source. The minimum receive headway is defined as the guard time. In the reference implementation, if the receive 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="accopt.html#discard"><tt>discard</tt></a> command. By design, the minimum interval between <tt>burst</tt> and <tt>iburst</tt> packets sent by any client is 2 s, which does not violate this constraint. Packets sent by other implementations that violate this constraint will be dropped and a KoD packet returned, if enabled.</p> +<h4 id="mah">Minimum Average Headway Time</h4> +<p>There are two features in the reference implementation to manage the minimum average headway time between one packet and the next, and thus the maximum average rate for each source. The transmit throttle limits the rate for transmit packets, while the receive discard limits the rate for receive packets. These features make use of a pair of counters: a client output counter for each association and a server input counter for each distinct client IP address. For each packet received, the input counter increments by a value equal to the minimum average headway (MAH) and then decrements by one each second. For each packet transmitted, the output counter increments by the MAH and then decrements by one each second. The default MAH 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.</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. Starting from an output counter value of zero, the maximum counter value, called the ceiling, can be no more than eight times the MAH. However, if the burst starts with a counter value other than zero, there is a potential to exceed the ceiling. This can result from protocol restarts and/or Autokey protocol operations. In these cases the poll algorithm throttles the output rate by computing an additional headway time so that the next packet sent will not exceed the ceiling. Designs such as this are often called leaky buckets.</p> +<p>The reference implementation uses a special most-recently used (MRU) list of entries, one entry for each distinct client IP address found. Each entry includes the IP address, input counter and process time at the last packet arrival. 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 if the list is full. Observers will note this is the same algorithm used for page replacement in virtual memory systems. However, in the virtual memory algorithm the entry of interest is the last, whereas here the entry of interest is the first.</p> +<p> The input counter for the first entry on the MRU list, representing the current input packet, is decreased by the interval since the entry was last referenced, but not below zero. If the input counter is greater than the ceiling, the packet is discarded. Otherwise, the counter is increased by the MAH and the packet is processed. The result is, if the client maintains an average headway greater than the ceiling and transmits no more than eight packets in a burst, the input counter will not exceed the ceiling. Packets sent by other implementations that violate this constraint will be dropped and a KoD packet returned, if enabled.</p> +<p>The reference implementation has a maximum MRU list size of a few hundred entries. The national time servers operated by NIST and USNO have an aggregate packet rate in the thousands of packets per second from many thousands of customers. Under these conditions, the list overflows after only a few seconds of traffic. However, analysis shows that the vast majority of the abusive traffic is due to a tiny minority of the customers, some of which send at over one packet per second. This means that the few seconds retained on the list is sufficient to identify and discard by far the majority of the abusive traffic.</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 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-octet 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 of the <a href="accopt.html#restrict"><tt>restrict</tt></a> command are present and either the guard time or MAH time are violated.</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 reference implementation, the server sets the poll field of the KoD packet to the greater of (a) the server MAH and (b) client packet poll field. In response to the KoD packet, the client sets the peer poll interval to the maximum of (a) the client MAH and (b) the server packet poll field. This automatically increases the headway for following client packets. </p> +<p> In order to make sure the client notices the KoD packet, the server sets the receive and transmit timestamps to the transmit timestamp of the client packet. Thus, even if the client ignores all except the timestamps, it cannot do any useful time computations. KoD packets themselves are rate limited to no more than one packet per guard time, in order to defend against flood attacks.</p> +<h4 id="ref">References</h4> +<ol> + <li>Mills, D.L., J. Levine, R. Schmidt and D. Plonka. Coping with overload on the Network Time Protocol public servers. <i>Proc. Precision Time and Time Interval (PTTI) Applications and Planning Meeting</i> (Washington DC, December 2004), 5-16. Paper: <a href="http://www.eecis.udel.edu/~mills/database/papers/ptti/ptti04a.pdf">PDF</a>, Slides:<a href="http://www.eecis.udel.edu/~mills/database/brief/ptti/ptti04.pdf">PDF</a> | <a href="http://www.eecis.udel.edu/~mills/database/brief/ptti/ptti04.ppt">PowerPoint</a></li> +</ol> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/rdebug.html b/contrib/ntp/html/rdebug.html index d49514d..f14bf43 100644 --- a/contrib/ntp/html/rdebug.html +++ b/contrib/ntp/html/rdebug.html @@ -1,32 +1,29 @@ <!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">18:49</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links10.txt"></script> - <h4>More Help</h4> - <script type="text/javascript" language="javascript" src="scripts/links12.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 they'll sweep your bugs.</p> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:19<!-- #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> diff --git a/contrib/ntp/html/refclock.html b/contrib/ntp/html/refclock.html index 733b7bf..46d4908 100644 --- a/contrib/ntp/html/refclock.html +++ b/contrib/ntp/html/refclock.html @@ -1,103 +1,93 @@ <!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">13:06</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="298">Wednesday, August 10, 2005</csobj></p> - <br clear="left"> - <h4>Related Links</h4> - <script type="text/javascript" language="javascript" src="scripts/links10.txt"></script> - <h4>Pulse-Per-Second Interfacing Links</h4> - <p> - <script type="text/javascript" language="javascript" src="scripts/links11.txt"></script> - </p> - <h4>Audio Driver Links</h4> - <p> - <script type="text/javascript" language="javascript" src="scripts/links8.txt"></script> - </p> - <h4>Table of Contents</h4> - <ul> - <li class="inline"><a href="#clock">Reference Clock Drivers</a> - <li class="inline"><a href="#cal">Driver Calibration</a> - <li class="inline"><a href="#perf">Performance Enhancements</a> - <li class="inline"><a href="#list">Comprehensive List of Clock Drivers</a> - </ul> - <hr> - <h4 id="clock">Reference Clock Drivers</h4> - <p>Support for most of the commonly available radio and modem reference clocks is included in the default configuration of the NTP daemon for Unix <tt>ntpd</tt>. Individual clocks can be activated by configuration file commands, specifically the <tt>server</tt> and <tt>fudge</tt> commands described in the <a href="ntpd.html"><tt>ntpd</tt> program manual page</a>. The following discussion presents Information on how to select and configure the device drivers in a running Unix system.</p> - <p>Many radio reference clocks can be set to display local time as adjusted for timezone and daylight saving mode. For use with NTP the clock must be set for Coordinated Universal Time (UTC) only. Ordinarily, these adjustments are performed by the kernel, so the fact that the clock runs on UTC will be transparent to the user.</p> - <p>Radio and modem clocks by convention have addresses in the form 127.127.<i>t.u</i>, where <i>t</i> is the clock type and <i>u</i> is a unit number in the range 0-3 used to distinguish multiple instances of clocks of the same type. Most of these clocks require support in the form of a serial port or special bus peripheral, but some can work directly from the audio codec found in some workstations. The particular device is normally specified by adding a soft link <tt>/dev/device<i>u</i></tt> to the particular hardware device involved, where <i><tt>u</tt></i> correspond to the unit number above.</p> - <p>Most clock drivers communicate with the reference clock using a serial port, usually at 9600 bps. There are several application program interfaces (API) used in the various Unix and NT systems, most of which can be detected at configuration time. Thus, it is important that the NTP daemon and utilities be compiled on the target system or clone. In some cases special features are available, such as timestamping in the kernel or pulse-per-second (PPS) interface. In most cases these features can be detected at configuration time as well; however, the kernel may have to be recompiled in order for them to work.</p> - <p>The audio drivers are a special case. These include support for the NIST time/frequency stations WWV and WWVH, the Canadian time/frequency station CHU and generic IRIG signals. Currently, support for the Solaris and SunOS audio API is included in the distribution. It is left to the volunteer corps to extend this support to other systems. Further information on hookup, debugging and monitoring is given in the <a href="audio.html">Audio Drivers</a> page.</p> - <p>The local clock driver is also a special case. A server configured with this driver can operate as a primary server to synchronize other clients when no other external synchronization sources are available. If the server is connected directly or indirectly to the public Internet, there is some danger that it can adversely affect the operation of unrelated clients. Carefully read the <a href="drivers/driver1.html">Undisciplined Local Clock</a> page and respect the stratum limit.</p> - <p>The local clock driver also supports an external synchronization source such as a high resolution counter disciplined by a GPS receiver, for example. 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 and shortwave radio services need to know the radio propagation time from the transmitter to the receiver, which can amount to some tens of milliseconds. 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 or estimated from various sources. The actual calculations are beyond the scope of this document.</p> - <p>When more than one clock driver is supported, it is often the case that each shows small systematic offset differences relative to the rest. 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 in the <a href="miscopt.html">Miscellaneous Options</a> page is useful for this purpose. The calibration function can also be enabled and disabled using the <tt>ntpdc</tt> program utility.</p> - <p>Most clock drivers use the <tt>time1</tt> value specified in the <tt>fudge</tt> configuration command to provide the calibration correction when this cannot be provided by the clock or interface. When the calibration function is enabled, the <tt>time1</tt> value is automatically adjusted to match the offset of the remote server or local clock driver selected for synchronization. Ordinarily, the NTP selection algorithm chooses the best from among all sources, usually the best radio clock determined on the basis of stratum, synchronization distance and jitter. The calibration function adjusts the <tt>time1</tt> values for all clock drivers except this source so that their indicated offsets tend to zero. If the selected source is the kernel PPS discipline, the <tt>fudge time1</tt> values for all clock drivers are adjusted.</p> - <p>The adjustment function is an exponential average designed to improve accuracy, so the function takes some time to converge. The recommended procedure is to enable the function, let it run for an hour or so, then edit the configuration file using the <tt>time1</tt> values displayed by the <tt>ntpq</tt> utility and <tt>clockvar</tt> command. Finally, disable the calibration function to avoid possible future disruptions due to misbehaving clocks or drivers.</p> - <h4 id="perf">Performance Enhancements</h4> - <p>In general, performance can be improved, especially when more than one clock 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 source is used to discipline the system clock and jitter-producing "clockhopping" between sources is avoided. This is valuable when more than one clock driver is present and especially valuable when the PPS clock driver (type 22) is used. Support for PPS signals is summarized in the <a href="pps.html">Pulse-per-second (PPS) Signal Interfacing</a> page.</p> - <p>Where the highest performance is required, generally better than one millisecond, additional hardware and/or software functions may be required. Kernel modifications for precision time are described in the <a href="kern.html">A Kernel Model for Precision Timekeeping</a> page. Special line discipline and streams modules for use in capturing precision timestamps are described in the <a href="ldisc.html">Line Disciplines and Streams Drivers</a> page.</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, and features (line disciplines, etc.). 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 class="inline"><a href="drivers/driver2.html">Type 2</a> Trak 8820 GPS Receiver (<tt>GPS_TRAK</tt>) - <li class="inline"><a href="drivers/driver3.html">Type 3</a> PSTI/Traconex 1020 WWV/WWVH Receiver (<tt>WWV_PST</tt>) - <li class="inline"><a href="drivers/driver4.html">Type 4</a> Spectracom WWVB and GPS Receivers (<tt>WWVB_SPEC</tt>) - <li class="inline"><a href="drivers/driver5.html">Type 5</a> TrueTime GPS/GOES/OMEGA Receivers (<tt>TRUETIME</tt>) - <li class="inline"><a href="drivers/driver6.html">Type 6</a> IRIG Audio Decoder (<tt>IRIG_AUDIO</tt>) - <li class="inline"><a href="drivers/driver7.html">Type 7</a> Radio CHU Audio Demodulator/Decoder (<tt>CHU</tt>) - <li class="inline"><a href="drivers/driver8.html">Type 8</a> Generic Reference Driver (<tt>PARSE</tt>) - <li class="inline"><a href="drivers/driver9.html">Type 9</a> Magnavox MX4200 GPS Receiver (<tt>GPS_MX4200</tt>) - <li class="inline"><a href="drivers/driver10.html">Type 10</a> Austron 2200A/2201A GPS Receivers (<tt>GPS_AS2201</tt>) - <li class="inline"><a href="drivers/driver11.html">Type 11</a> Arbiter 1088A/B GPS Receiver (<tt>GPS_ARBITER</tt>) - <li class="inline"><a href="drivers/driver12.html">Type 12</a> KSI/Odetics TPRO/S IRIG Interface (<tt>IRIG_TPRO</tt>) - <li class="inline">Type 13 Leitch CSD 5300 Master Clock Controller (<tt>ATOM_LEITCH</tt>) - <li class="inline">Type 14 EES M201 MSF Receiver (<tt>MSF_EES</tt>) - <li class="inline">Type 15 reserved - <li class="inline"><a href="drivers/driver16.html">Type 16</a> Bancomm GPS/IRIG Receiver (<tt>GPS_BANCOMM</tt>) - <li class="inline">Type 17 Datum Precision Time System (<tt>GPS_DATUM</tt>) - <li class="inline"><a href="drivers/driver18.html">Type 18</a> Automated Computer Time Service (<tt>ACTS_MODEM</tt>) - <li class="inline"><a href="drivers/driver19.html">Type 19</a> Heath WWV/WWVH Receiver (<tt>WWV_HEATH</tt>) - <li class="inline"><a href="drivers/driver20.html">Type 20</a> Generic NMEA GPS Receiver (<tt>NMEA</tt>) - <li class="inline">Type 21 TrueTime GPS-VME Interface (<tt>GPS_VME</tt>) - <li class="inline"><a href="drivers/driver22.html">Type 22</a> PPS Clock Discipline (<tt>PPS</tt>) - <li class="inline">Type 23 reserved - <li class="inline">Type 24 reserved - <li class="inline">Type 25 reserved - <li class="inline"><a href="drivers/driver26.html">Type 26</a> Hewlett Packard 58503A GPS Receiver (<tt>GPS_HP</tt>) - <li class="inline"><a href="drivers/driver27.html">Type 27</a> Arcron MSF Receiver (<tt>MSF_ARCRON</tt>) - <li class="inline"><a href="drivers/driver28.html">Type 28</a> Shared Memory Driver (<tt>SHM</tt>) - <li class="inline"><a href="drivers/driver29.html">Type 29</a> Trimble Navigation Palisade GPS (<tt>GPS_PALISADE</tt>) - <li class="inline"><a href="drivers/driver30.html">Type 30</a> Motorola UT Oncore GPS <tt>GPS_ONCORE</tt>) - <li class="inline"><a href="drivers/driver31.html">Type 31</a> Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>) - <li class="inline"><a href="drivers/driver32.html">Type 32</a> Chrono-log K-series WWVB receiver (<tt>CHRONOLOG</tt>) - <li class="inline"><a href="drivers/driver33.html">Type 33</a> Dumb Clock (<tt>DUMBCLOCK</tt>) - <li class="inline"><a href="drivers/driver34.html">Type 34</a> Ultralink WWVB Receivers (<tt>ULINK</tt>) - <li class="inline"><a href="drivers/driver35.html">Type 35</a> Conrad Parallel Port Radio Clock (<tt>PCF</tt>) - <li class="inline"><a href="drivers/driver36.html">Type 36</a> Radio WWV/H Audio Demodulator/Decoder (<tt>WWV</tt>) - <li class="inline"><a href="drivers/driver37.html">Type 37</a> Forum Graphic GPS Dating station (<tt>FG</tt>) - <li class="inline"><a href="drivers/driver38.html">Type 38</a> hopf GPS/DCF77 6021/komp for Serial Line (<tt>HOPF_S</tt>) - <li class="inline"><a href="drivers/driver39.html">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus (<tt>HOPF_P</tt>) - <li class="inline"><a href="drivers/driver40.html">Type 40</a> JJY Receivers (<tt>JJY</tt>) - <li class="inline">Type 41 TrueTime 560 IRIG-B Decoder - <li class="inline"><a href="drivers/driver42.html">Type 42</a> Zyfer GPStarplus Receiver - <li class="inline"><a href="drivers/driver43.html">Type 43</a> RIPE NCC interface for Trimble Palisade - <li class="inline"><a href="drivers/driver44.html">Type 44</a> NeoClock4X - DCF77 / TDF serial line - </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 -->10-Mar-2014 05:20<!-- #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>mode</tt>, <tt>minpoll</tt>, <tt>maxpoll</tt>, and <tt>prefer</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">Type 2 Deprecated: was Trak 8820 GPS Receiver</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> + <li class="inline"><a href="drivers/driver45.html">Type 45</a> Spectracom TSYNC PCI</li> + <li class="inline"><a href="drivers/driver46.html">Type 46</a> GPSD NG client protocol</li> +</ul> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/release.html b/contrib/ntp/html/release.html index b2f4d05..f940603 100644 --- a/contrib/ntp/html/release.html +++ b/contrib/ntp/html/release.html @@ -1,70 +1,72 @@ <!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">19:17</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="270">Monday, October 10, 2005</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 quite a while and isn't finished yet. In fact, quite a number of NTPv4 features have already been retrofitted in the older NTPv3, although this version is not actively maintained by the NTPv4 developer corps.</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. As always, corrections and bugfixes are warmly received, especially in the form of context diffs sent to <a href="mailto:bugs@ntp.org">bugs@ntp.org</a>.</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-5.3 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. Additional information on protocol compatibility details is on the <a href="http://www.eecis.udel.edu/%7emills/biblio.html">Protocol Conformance Statement</a> page.</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. Combination IPv6 and IPv4 configurations have been successfully tested in all protocol modes supported by NTP and using both symmetric and public key (Autokey) cryptography. However, users should note that IPv6 support is new and we have not had a lot of experience with it in various operational scenarios and local infrastructure environments. As always, feedback is welcome. - <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. Workstations of today are much faster than when the original NTP version was designed in the early 1980s, and it is rare to find a processor architecture that does not support floating double. The fixed point format is still used with raw timestamps, in order to retain the full precision of about 212 picoseconds. However, the algorithms which process raw timestamps all produce fixed point differences before converting to floating double. The differences are ordinarily quite small so can be expressed without loss of accuracy in this format. - - <li>The clock discipline algorithm has been redesigned to improve accuracy, reduce the impact of network jitter and allow increased in poll intervals to well over one day with only moderate sacrifice in accuracy. - </ol> - <ul> - <ul> - <li>A new feature called <i>huffpuff</i> maximizes accuracy in cases of highly asymmetric network delays typical of ISDN and modem access circuits. - <li>The NTPv4 design allows clients to increase the poll intervals even when synchronized directly to the server. In NTPv3 the poll interval in such cases was clamped to the minimum, usually 64 s. For those servers with hundreds of clients, the new design can dramatically reduce the network load, especially when large numbers of potential clients, as in national laboratory services. - <li>A scheme designed to reduce "clockhopping" when the choice of servers changes frequently as the result of comparatively insignificant quality changes. - </ul> - </ul> - <ol> - <li>This release includes support for the <a href="ftp://ftp.udel.edu/usa/ftp/pub/ntp/software/"><i>nanokernel</i></a> precision time kernel support, which is now in stock FreeBSD and optional Linux kernels. If a precision time source such as a GPS timing receiver or cesium clock is available, kernel timekeeping can be improved to the order of one microsecond. The older <i>microtime</i> kernel for Digital/Compaq/HP Tru64, Digital Ultrix, as well as Sun Microsystems SunOS and Solaris, continues to be supported. - <li>This release includes support for Autokey public-key cryptography, which is the preferred scheme for authenticating servers to clients. Autokey Version 2 uses NTP header extension fields and protocols as described on the NTP project page linked from www.ntp.org. This release includes support for additional message digest and digital signature schemes supported by the OpenSSL software library, as well as new identity schemes based on cryptographic challenge/responce algorithms. The new design greatly simplifies key generation and distribution and provides orderly key refreshment. Security procedures and media formats are consistent with industry standard X.509 Version 3 certificates and authority procedures. Specific improvements to the protocol include a reduction in the number of messages required and a method to protect the cookie used in client/server mode against disclosure. Additional information about Autokey cryptography is contained in 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>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>NTPv4 includes two new association modes which in most applications can avoid per-host configuration altogether. Both of these are based on IP multicast technology and Autokey cryptography. They provide automatic discovery, configuration and authentication of servers and clients without identifying servers or clients in advance. In multicast mode a server sends a message at fixed intervals using specified multicast group addresses, while clients listen on these addresses. - <p>Upon receiving the the first message, a client exchanges several messages with the server in order to calibrate the multicast propagation delay between the client and server and run the authentication protocol. In manycast mode a client sends a message to a specified multicast group address and expects one or more servers to reply. Using engineered algorithms, the client selects an appropriate subset of servers from the messages received and continues an ordinary client/server campaign. The manycast scheme can provide somewhat better accuracy than the multicast scheme at the price of additional network overhead. See the <a href="manyopt.html">Automatic NTP Configuration Options</a> page for further information.</p> - <li>This release includes support for the orphan mode, which replaces the local clock driver for most configurations. The local clock driver provides a synchronization source for networks not connected to the public Internet or reference clock driver. However, it does not opperate with multiple sources nor multiple failures. The 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>This release includes support for preemptable servers, which are provisionally mobilized in manycast mode or by participants in the pool scheme. Manycast mode is described in these notes. In the pool scheme multiple client associations are mobilized for a designated DNS name such as pool.ntp.org. The DNS resolver randomizes replies over a set of volunteer service providers. The NTP mitigation algorithms select the best three from among the set and demobilizes the excess. See the <a href="manyopt.html">Automatic NTP Configuration Options</a> page for further information.<li>There are two 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>The reference clock driver interface is smaller, more rational and more accurate. 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 a Sun or FreeBSD audio port. See the <a href="audio.html">Reference Clock Audio Drivers</a> page for further information. - <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>In NTPv3 a large number of weeds and useless code had grown over the years since the original NTPv1 code was implemented almost twenty 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>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 <tt>Bitkeeper</tt> using an online repository at www.ntp.org. - <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 tos command can be used to limit the accepted stratum range, specify minimum dispersion increment and maximum selection theshold, and activate orphan mode. - <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. - </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>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 only show the IPv4 associations with the <tt>peers</tt> and other simular commands. Older versions of <tt>ntpq</tt> will show 0.0.0.0 for IPv6 associations with the <tt>peers</tt> and other simular commands. - <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 address (IPv4 or IPv6) each of the configured associations. Normally, this detail would not be of concern; however, the <tt>ntptrace</tt> program originally depended on that field in order to display a server traceback to the primary reference source. This program has now been replaced by a script that does the same function, but does not depend on the reference ID field. The <tt>ntpdc</tt> utility now uses a special version number to communicate with the <tt>ntpd</tt> server. The server uses this version number to select which address family to used in reply packets. The <tt>ntpdc</tt> program falls back to the older version behavior when communicating with older NTP versions. - <li>As required by Defense Trade Regulations (DTR), the cryptographic routines supporting the Data Encryption Standard (DES) have been removed from the base distribution of NTPv3. For NTPv4 a new interface has been implemented for the OpenSSL cryptographic library, which is widely available on the web at www.openssl.org. This library replaces the library formerly available from RSA Laboratories. Besides being somewhat faster and more widely available, the OpenSSL library supports many additional cryptographic algorithms, which are now selectable at run time. Directions for using OpenSSL are in the <a href="build/build.html">Building and Installing the Distribution</a> page. - <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>The NTPv4 enable and disable commands have a few changes in the arguments. See the <tt>ntpd</tt> <a href="miscopt.html">Miscellaneous Options</a> page for details. Note that the <tt>authenticate</tt> command has been removed. - <li>To help reduce the level of spurious network traffic due to obsolete configuration files, a special control message called the <i>kiss-o'-death</i> packet has been implemented. If enabled and a packet is denied service or exceeds the client limits, a compliant server will send this message to the client. A compliant client will cease further transmission and send a message to the system log. See the <a href="accopt.html">Authentication Options</a> page for further information. - <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>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 in some SNTP clients. - <li>The precision time support in stock Solaris 2.6 has bugs that were fixed in 2.7. A patch is available that fixes the 2.6 bugs. The 2.6 PPS kernel discipline has been disabled by default. For testing, the kernel can be enabled using the <tt>enable kernel</tt> command either in the configuration file or via <tt>ntpdc</tt>. - <li>The HTML documentation has been partially updated. However, most of the NTPv3 documentation continues to apply to NTPv4. Until a comprehensive update happens, what you see is what you get. We are always happy to accept comments, corrections and bug reports. However, we are most thrilled upon receipt of patches to fix the dang bugs. <b>Please send bug reports to <a href="mailto:bugs@ntp.org">bugs@ntp.org</a>, not the individual members on the team</b>. - </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 -->3-Oct-2011 21:51<!-- #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>The behavior of the daemon at startup has been considerably improved. The time to measure the frequency and correct an initial offset error when started for the first time is now no more than ten minutes. Upon restart, it takes no more than five minutes to reduce the initial offset to less than one millisecond without adversely affecting the frequency. This avoids a subsequent frequency correction which could take up to several hours.</li> + <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 queuing 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 reliable backup in isolated networks or in pr when Internet sources have become unavailable. 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 algorithm have been removed from the base distribution. All 128-bit and 160-bit message digests algorithms are now supported for both symmetric key and public key cryptosystems. See the <a href="authentic.html">Authentication Support</a> page for 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 --enable-autokey option when building the distribution, which is the default is OpenSSL is available. The deployment of Autokey subnets is now considerably simpler than in earlier versions. A subnet naming scheme is now available to filter manycast and pool configurations. Additional information about Autokey is on the <a href="autokey.html">Autokey Public 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="discover.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> + <li>A number of white papers have been added to the library on the NTP Reseatch Project Page, including:</li> +</ul> +<script type="text/javascript" language="javascript" src="scripts/external.txt"></script> +<h4 id="change">Changes and Upgrades Since the NTPv3 Version (xntp3-5) </h4> +<p>This section summarizes general changes since the publication of RFC-1305. Specific changes made during the code upgrade of 2007-2008 are summarized in <a href="history.html">Historical Notes</a>.</p> +<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> diff --git a/contrib/ntp/html/scripts/accopt.txt b/contrib/ntp/html/scripts/accopt.txt new file mode 100644 index 0000000..d8f0280 --- /dev/null +++ b/contrib/ntp/html/scripts/accopt.txt @@ -0,0 +1,5 @@ +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>") diff --git a/contrib/ntp/html/scripts/audio.txt b/contrib/ntp/html/scripts/audio.txt new file mode 100644 index 0000000..5fb11fc --- /dev/null +++ b/contrib/ntp/html/scripts/audio.txt @@ -0,0 +1,7 @@ +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='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>") diff --git a/contrib/ntp/html/scripts/authopt.txt b/contrib/ntp/html/scripts/authopt.txt new file mode 100644 index 0000000..5064b18 --- /dev/null +++ b/contrib/ntp/html/scripts/authopt.txt @@ -0,0 +1,12 @@ +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#ident'>ident - specify Autokey ephemeral group name</a></li>\ +<li class='inline'><a href='authopt.html#keys'>keys - specify symmetric keys filename</a></li>\ +<li class='inline'><a href='authopt.html#keysdir'>keysdir - specify Autokey key directory</a></li>\ +<li class='inline'><a href='authopt.html#requestkey'>requestkey - specify request key ID</a></li>\ +<li class='inline'><a href='authopt.html#revoke'>revoke - specify Autokey randomization interval</a></li>\ +<li class='inline'><a href='authopt.html#trustedkey'>trustedkey - specify trusted key IDs</a></li>\ +<li class='inline'><a href='comdex.html'>Command Index</a></li>\ +</ul>") diff --git a/contrib/ntp/html/scripts/clockopt.txt b/contrib/ntp/html/scripts/clockopt.txt new file mode 100644 index 0000000..1c76a1c --- /dev/null +++ b/contrib/ntp/html/scripts/clockopt.txt @@ -0,0 +1,5 @@ +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='clockopt.html#server'>server - specify reference clock server</a><br>\ +<li class='inline'><a href='comdex.html'>Command Index</a></li>\ +</ul>") diff --git a/contrib/ntp/html/scripts/command.txt b/contrib/ntp/html/scripts/command.txt new file mode 100644 index 0000000..ec6169e --- /dev/null +++ b/contrib/ntp/html/scripts/command.txt @@ -0,0 +1,7 @@ +document.write("\ +<table><tr>\ +<td width='50%' ><img src='icons/home.gif' align='middle' alt='gif'>\ +<a href='index.html'>Home Page</a></td>\ +<td width='50%' ><img src='icons/mail2.gif' align='middle' alt='gif'>\ +<a href='http://www.ntp.org/contact'>Contacts</a></i></td>\ +</tr></table>") diff --git a/contrib/ntp/html/scripts/config.txt b/contrib/ntp/html/scripts/config.txt new file mode 100644 index 0000000..84c226a --- /dev/null +++ b/contrib/ntp/html/scripts/config.txt @@ -0,0 +1,5 @@ +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='discover.html'>Automatic Server Discovery Schemes</a></li>\ +<li class='inline'><a href='sitemap.html'>Site Map</a></li>\ +</ul>") diff --git a/contrib/ntp/html/scripts/confopt.txt b/contrib/ntp/html/scripts/confopt.txt new file mode 100644 index 0000000..c524f59 --- /dev/null +++ b/contrib/ntp/html/scripts/confopt.txt @@ -0,0 +1,12 @@ +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#peer'>peer - configure symmetric peer association</a></li>\ +<li class='inline'><a href='confopt.html#broadcast'>broadcast - configure broadcast server association</a></li>\ +<li class='inline'><a href='confopt.html#manycastclient'>manycastclient - configure manycast client association</a></li>\ +<li class='inline'><a href='confopt.html#pool'>pool - configure pool association</a></li>\ +<li class='inline'><a href='confopt.html#unpeer'>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>") diff --git a/contrib/ntp/html/scripts/external.txt b/contrib/ntp/html/scripts/external.txt new file mode 100644 index 0000000..5e70705 --- /dev/null +++ b/contrib/ntp/html/scripts/external.txt @@ -0,0 +1,19 @@ +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/security.html'>NTP Security Analysis</a></li>\ +<li class='inline'><a href='http://www.eecis.udel.edu/~mills/ptp.html'>IEEE 1588 Precision Time Protocol (PTP)</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>") diff --git a/contrib/ntp/html/scripts/footer.txt b/contrib/ntp/html/scripts/footer.txt index 7fc6dd8..48830e6 100644 --- a/contrib/ntp/html/scripts/footer.txt +++ b/contrib/ntp/html/scripts/footer.txt @@ -1,7 +1,9 @@ document.write("\
<table><tr>\
-<td width='50%' ><img src='icons/home.gif' align='middle' alt='gif'>\
+<td width='33%' align='center'><img src='icons/home.gif' align='middle'>\ <a href='index.html'>Home Page</a></td>\
-<td width='50%' ><img src='icons/mail2.gif' align='middle' alt='gif'>\
-<a href='http://www.ntp.org/contact.html'>Contacts</a></i></td>\ -</tr></table>")
\ No newline at end of file +<td width='33%' align='center'><img src='icons/sitemap.png' align='middle'>\ +<a href='sitemap.html'>Site Map</a></td>\ +<td width='33%' align='center'><img src='icons/mail2.gif' align='middle'>\ +<a href='http://www.ntp.org/contact'>Contacts</a></td>\ +</tr></table>") diff --git a/contrib/ntp/html/scripts/hand.txt b/contrib/ntp/html/scripts/hand.txt new file mode 100644 index 0000000..95da082 --- /dev/null +++ b/contrib/ntp/html/scripts/hand.txt @@ -0,0 +1,11 @@ +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>") diff --git a/contrib/ntp/html/scripts/install.txt b/contrib/ntp/html/scripts/install.txt new file mode 100644 index 0000000..e8185f2 --- /dev/null +++ b/contrib/ntp/html/scripts/install.txt @@ -0,0 +1,10 @@ +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>") diff --git a/contrib/ntp/html/scripts/links10.txt b/contrib/ntp/html/scripts/links10.txt deleted file mode 100644 index 880e379..0000000 --- a/contrib/ntp/html/scripts/links10.txt +++ /dev/null @@ -1,5 +0,0 @@ -document.write("<ul>\
-<li class='inline'><a href='refclock.html'>Reference Clock Drivers</a><br>\
-<li class='inline'><a href='prefer.html'>Mitigation Rules and the <tt>prefer</tt> Keyword</a><br>\
-<li class='inline'><a href='howto.html'>How to Write a Reference Clock Driver</a><br>\
-</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/scripts/links11.txt b/contrib/ntp/html/scripts/links11.txt deleted file mode 100644 index 59e7017..0000000 --- a/contrib/ntp/html/scripts/links11.txt +++ /dev/null @@ -1,7 +0,0 @@ -document.write("<ul>\
-<li class='inline'><a href='refclock.html'>Reference Clock Drivers</a><br>\
-<li class='inline'><a href='pps.html'>Pulse-per-second (PPS) Signal Interfacing</a><br>\
-<li class='inline'><a href='ldisc.html'>Line Disciplines and Streams Modules</a><br>\
-<li class='inline'><a href='kernpps.html'>PPSAPI Interface for Precision Time Signals</a><br>\ -<li class='inline'><a href='gadget.html'>Gadget Box PPS Level Converter and CHU Modem</a><br>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/scripts/links12.txt b/contrib/ntp/html/scripts/links12.txt deleted file mode 100644 index 7ca9249..0000000 --- a/contrib/ntp/html/scripts/links12.txt +++ /dev/null @@ -1,5 +0,0 @@ -document.write("<ul>\
-<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='msyslog.html'><tt>ntpd</tt> System Log Messages</a><br>\
-</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/scripts/links7.txt b/contrib/ntp/html/scripts/links7.txt deleted file mode 100644 index 0d33473..0000000 --- a/contrib/ntp/html/scripts/links7.txt +++ /dev/null @@ -1,6 +0,0 @@ -document.write("<ul>\
-<li class='inline'><a href='confopt.html'>Server 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='ntp_conf.html'>Configuration File Definition (Advanced)</a><br>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/scripts/links8.txt b/contrib/ntp/html/scripts/links8.txt deleted file mode 100644 index 135310c..0000000 --- a/contrib/ntp/html/scripts/links8.txt +++ /dev/null @@ -1,6 +0,0 @@ -document.write("<ul>\
-<li class='inline'><a href='refclock.html'>Reference Clock 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>\ -<li class='inline'><a href='drivers/driver6.html'>IRIG Audio Decoder</a>\ -</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/scripts/links9.txt b/contrib/ntp/html/scripts/links9.txt deleted file mode 100644 index 6ea32f0..0000000 --- a/contrib/ntp/html/scripts/links9.txt +++ /dev/null @@ -1,8 +0,0 @@ -document.write("<ul>\
-<li class='inline'><a href='authopt.html'>Authentication Options</a><br>\
-<li class='inline'><a href='manyopt.html'>Automatic NTP Configuration Options</a><br>\
-<li class='inline'><a href='confopt.html'>Server Options</a><br>\
-<li class='inline'><a href='groups.html'>Trusted Hosts and Groups</a><br>\ -<li class='inline'><a href='keygen.html'><tt>ntp-keygen</tt> - generate public and private keys</a>\ -<li class='inline'><a href='http://www.eecis.udel.edu/~mills/autokey.html'>Autonomous Authentication</a>\
-</ul>")
\ No newline at end of file diff --git a/contrib/ntp/html/scripts/manual.txt b/contrib/ntp/html/scripts/manual.txt new file mode 100644 index 0000000..bad1f93 --- /dev/null +++ b/contrib/ntp/html/scripts/manual.txt @@ -0,0 +1,13 @@ +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>") diff --git a/contrib/ntp/html/scripts/misc.txt b/contrib/ntp/html/scripts/misc.txt new file mode 100644 index 0000000..2dfb289 --- /dev/null +++ b/contrib/ntp/html/scripts/misc.txt @@ -0,0 +1,9 @@ +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>") diff --git a/contrib/ntp/html/scripts/miscopt.txt b/contrib/ntp/html/scripts/miscopt.txt new file mode 100644 index 0000000..64987c8 --- /dev/null +++ b/contrib/ntp/html/scripts/miscopt.txt @@ -0,0 +1,21 @@ +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#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#reset'>reset - reset groups of counters</a></li>\ +<li class='inline'><a href='miscopt.html#saveconfigdir'>saveconfigdir - specify saveconfig directory</a></li>\ +<li class='inline'><a href='miscopt.html#setvar'>setvar - set system variables</a></li>\ +<li class='inline'><a href='miscopt.html#tinker'>tinker - modify sacred system parameters (dangerous)</a></li>\ +<li class='inline'><a href='miscopt.html#rlimit'>rlimit - alters certain process storage allocation limits</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>") diff --git a/contrib/ntp/html/scripts/monopt.txt b/contrib/ntp/html/scripts/monopt.txt new file mode 100644 index 0000000..b7d5a2f --- /dev/null +++ b/contrib/ntp/html/scripts/monopt.txt @@ -0,0 +1,6 @@ +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#statistics'>statistics - enable writing of statistics records</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>") diff --git a/contrib/ntp/html/scripts/refclock.txt b/contrib/ntp/html/scripts/refclock.txt new file mode 100644 index 0000000..b32e5fa --- /dev/null +++ b/contrib/ntp/html/scripts/refclock.txt @@ -0,0 +1,7 @@ +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>") diff --git a/contrib/ntp/html/scripts/special.txt b/contrib/ntp/html/scripts/special.txt new file mode 100644 index 0000000..b62d15e --- /dev/null +++ b/contrib/ntp/html/scripts/special.txt @@ -0,0 +1,17 @@ +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='filter.html'>Clock Filter Algorithm</a></li>\ +<li class='inline'><a href='select.html'>Clock Select Algorithm</a></li>\ +<li class='inline'><a href='cluster.html'>Clock Cluster Algorithm</a></li>\ +<li class='inline'><a href='prefer.html'>Mitigation Rules and the <tt>prefer</tt> Keyword</a></li>\ +<li class='inline'><a href='discipline.html'>Clock Discipline Algorithm</a></li>\ +<li class='inline'><a href='poll.html'>Poll Process</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>") diff --git a/contrib/ntp/html/scripts/style.css b/contrib/ntp/html/scripts/style.css index 7d7b276..7a0cc54 100644 --- a/contrib/ntp/html/scripts/style.css +++ b/contrib/ntp/html/scripts/style.css @@ -61,4 +61,4 @@ th {background: #FFFFCC; th.caption {background: #EEEEEE;
color: #006600;
- text-align: center;}
\ No newline at end of file + text-align: center;} diff --git a/contrib/ntp/html/select.html b/contrib/ntp/html/select.html new file mode 100644 index 0000000..6cfa186 --- /dev/null +++ b/contrib/ntp/html/select.html @@ -0,0 +1,41 @@ +<!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 Select Algorithm</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<em></em> +<h3>Clock Select Algorithm</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:22<!-- #EndDate --> + UTC</p> +<hr> +<p>The clock select algorithm determines from a set of sources , which are correct (<em>truechimers</em>) and which are not (<em>falsetickers</em>) according to a set of formal correctness assertions. The principles are based on the observation that the maximum error in determining the offset of a candidate cannot exceed one-half the roundtrip delay to the primary reference clock at the time of measurement. This must be increased by the maximum error that can accumulate since then. The selection metric, called the <em>root distance,</em>, is one-half the roundtrip root delay plus the root dispersion plus minor error contributions not considered here.</p> +<p>First, a number of sanity checks is performed to sift the selectable candidate from among the source population. The sanity checks are sumarized as follows:.</p> +<ol> + <li>A <em>stratum error</em> occurs if (1) the source had never been synchronized or (2) the stratum of the source is below the <tt>floor</tt> option or not below the <tt>ceiling</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default values for these options are 0 and 15, respectively. Note that 15 is a valid stratum, but a server operating at that stratum cannot synchronize clients.</li> + <li>A <em>distance error</em> occurs for a source if the root distance (also known ad synchronization distance) of the source is not below the distance threshold <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. The default value for this option is 1.5 s for networks including only the Earth, but this should be increased to 2.5 s for networks including the Moon.</li> + <li>A <em>loop</em> <em>error</em> occurs if the source is synchronized to the client. This can occur if two peers are configured with each other in symmetric modes.</li> + <li>An <em>unreachable</em> <em>error</em> 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> +Sources showing one or more of these errors are considered nonselectable; only the selectable candidates are considered in the following algorithm. Given the measured offset θ<sub>0</sub> and root distance λ, this defines a <em>correctness interval</em> [θ<sub>0</sub> − λ, θ<sub>0</sub> + λ] of points where the true value of θ lies somewhere on the interval. The given problem is to determine from a set of correctness intervals, which represent truechimers and which represent falsetickers. The principles must be given a precise definition. The <em>intersection interval</em> is the <em>smallest interval containing points from the largest number of correctness intervals.</em> An algorithm that finds the intersection interval was devised by Keith Marzullo in his doctoral dissertation. It was first implemented in the Digital Time Synchronization Service (DTSS) for the VMS operating system for the VAX. +<p> While the NTP algorithm is based on DTSS, it remains to establish which point in the correctness interval represents the best estimate of the offset for each candidate. The best point is at the midpoint θ<sub>0</sub> of the correctness interval; however, the midpoint might not be within the intersection interval. A candidate with a correctness interval that contains points in the intersection interval is a truechimer and the best offset estimate is the midpoint of its correctness interval. A candidate with a correctness interval that contains no points in the intersection interval is a falseticker.</p> +<div align="center"><img src="pic/flt3.gif" alt="gif"> + <p>Figure 1. Intersection Interval</p> +</div> +<p>Figure 1 shows correctness intervals for each of four candidates A, B, C and D. We need to find the maximum number of candidates that contain points in common. The result is the interval labeled DTSS. In the figure there are three truechimers A, B and C, and one falseticker D. In DTSS any point in the intersection interval can represent the true time; however, as shown below, this may throw away valuable statistical information. In any case, the clock is considered correct if the number of truechimers found in this way are greater than half the total number of candidates.</p> +<p>The question remains, which is the best point to represent the true time of each correctness interval? Fortunately, we already have the maximum likelihood estimate at the midpoint of each correctness interval. But, while the midpoint of candidate C is outside the intersection interval, its correctness interval contains points in common with the intersection interval, so the candidate is a truechimer and the midpoint is chosen to represent its time.</p> +<p>The DTSS correctness assertions do not consider how best to represent the truechimer time. To support the midpoint choice, consider the selection algorithm as a method to reject correctness intervals that cannot contribute to the final outcome; that is, they are falsetickers. The remaining correctness intervals can contribute to the final outcome; that is, they are truechimers. Samples in the intersection interval are usually of very low probability and thus poor estimates for truechimer time. On the other hand, the midpoint sample produced by the clock filter algorithm is the maximum likelihood estimate and thus best represents the truechimer time.</p> +<div align="center"><img src="pic/flt6.gif" alt="gif"> + <p>Figure 2. Clock Select Algorithm</p> +</div> +<p> The algorithm operates as shown in Figure 2. Let <em>m</em> be the number of candidates and <em>f</em> the number of falsetickers, initially zero. Move a pointer from the leftmost endpoint towards the rightmost endpoint in Figure 1 and count the number of candidates, stopping when that number reaches <em>m</em> − <em>f</em>; this is the left endpoint of the intersection interval. Then, do the same, but moving from the rightmost endpoint towards the leftmost endpoint; this is the right endpoint of the intersection interval. If the left endpoint is less than the right endpoint, the intersection interval has been found. Otherwise, increase <em>f</em> by 1. If <em>f</em> is less than <em>n</em> / 2, try again; otherwise, the algorithm fails and no truechimers could be found.</p> +<p>The clock select algorithm again scans the correctness intervals. If the right endpoint of the correctness interval for a candidate is greater than the left endpoint of the intersection interval, or if the left endpoint of the correctness interval is less than the right endpoint of the intersection interval, the candidate is a truechimer; otherwise, it is a falseticker.</p> +<p>In practice, with fast LANs and modern computers, the correctness interval can be quite small, especially when the candidates are multiple reference clocks. In such cases the intersection interval might be empty, due to insignificant differences in the reference clock offsets. To avoid this, the size of the correctness interval is padded to the value of <tt>mindist</tt>, with default 1 ms. This value can be changed using the <tt>mindist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/sitemap.html b/contrib/ntp/html/sitemap.html new file mode 100644 index 0000000..c4b9110 --- /dev/null +++ b/contrib/ntp/html/sitemap.html @@ -0,0 +1,33 @@ +<!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 -->11-Sep-2010 05:55<!-- #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> diff --git a/contrib/ntp/html/sntp.html b/contrib/ntp/html/sntp.html index 839271e..84c6f29 100644 --- a/contrib/ntp/html/sntp.html +++ b/contrib/ntp/html/sntp.html @@ -1,57 +1,79 @@ <!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>Simple Network Time Protocol (SNTP) Client</title> - <link href="scripts/style.css" type="text/css" rel="stylesheet"> - </head> - - <body> - <h3>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">18:50</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> - <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-2030, 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>While this program can do other things, including operation as a primitive server, some of these things are truly dangerous in a ubiquitous public time server network. A full disclosure is in the man page in the <tt>./sntp</tt> directory, but be truly advised RFC-2030 specifically <b>forbids</b> a SNTP client to operate as a server for other NTP or SNTP clients. If such operation is contemplated, do <b>not</b> allow access by clients on the public Internet.</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> +<!-- Changed by: Harlan &, 07-Dec-2014 --> +<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 -->1-Apr-2015 11:05<!-- #EndDate --> + UTC</p> +<br clear="left"> +<hr> +<h4>Synopsis</h4> +<tt>sntp [{--help -?}][{-4 -6}][-a <i>keynum</i>][-b <i>bcaddress</i>][-B <i>bctimeout</i>][-c][-d][-D <i>debug-level</i>][-g <i>delay</i>][-K <i>kodfile</i>][-k <i>keyfile</i>][-l <i>logfile</i>][-M <i>steplimit</i>][-o <i>ntpver</i>][-r][-S][-s][-u <i>uctimeout</i>][--wait][--version][<i>address(es)</i>]</tt> +<h4>Description</h4> +<p>This program is a Simple Network Time Protocol (SNTP) client that can be used to query a Network Time Protocol (NTP) server and display the time offset of the system clock relative to the server clock. Run as root it can correct the system clock to this offset as well. It can be run as an interactive command or from a script by a <tt>cron</tt> job. The program implements the SNTP client protocol defined in RFC 5905, including the full on-wire protocol but does not provide the sanity checks, access controls, security functions and mitigation algorithms as in the full NTP version 4 specification, also defined in RFC 5905.</p> +<p>By default, <tt>sntp</tt> writes the local date and time (i.e., not UTC) to the standard output in the format</p> +<p><tt>2011-08-04 00:40:36.642222 (+0000) +0.006611 +/- 0.041061 psp-os1 149.20.68.26 s3 no-leap</tt></p> +<p>where the <tt>+0.006611 +/- 0.041061</tt> indicates the time offset and error bound of the system clock relative to the server clock, in seconds. The hostname and/or the IP is displayed, as is the stratum of the server. Finally, the leap indicator status is displayed.</p> +<p>If -b <i>bcaddress</i> is not specified, the program sends a single message to each address and waits up to <i>uctimeout</i> (default 5) seconds for a unicast server response. Otherwise, it sends no message and waits up to <i>bctimeout</i> (default 68) seconds for a broadcast NTP message.</p> +<h4>Options</h4> +<p><tt>sntp</tt> recognizes the following options:</p> +<dl> + <dt><tt>-?, --help</tt></dt> + <dd>displays usage information. The short form typically requires shell quoting, such as <tt>-\?</tt>, otherwise <tt>?</tt> is consumed by the shell.</dd> + <dt><tt>-4, --ipv4</tt></dt> + <dd>When resolving hostnames to IP addresses, use IPv4 addresses only.</dd> + <dt><tt>-6, --ipv6</tt></dt> + <dd>When resolving hostnames to IP addresses, use IPv6 addresses only.</dd> + <dt><tt>-a <i>keynum</i>, --authentication <i>keynum</i></tt></dt> + <dd>Enable authentication with the key ID <i>keynum</i>. <i>keynum</i> is a number specified in the keyfile along with an authentication secret (password or digest). See the <tt>-k, --keyfile</tt> option for more details.</dd> + <dt><tt>-b <i>bcaddress</i>, --broadcast <i>bcaddress</i></tt></dt> + <dd>Listen for NTP packets sent to the broadcast or multicast address <i>bcaddress</i>, which can be a DNS name or IP address. The default maximum time to listen for broadcasts/multicasts, 68 seconds, can be modified with the <tt>-B, --bctimeout</tt> option.</dd> + <dt><tt>-B <i>bctimeout</i>, --bctimeout <i>bctimeout</i></tt></dt> + <dd>Wait <i>bctimeout</i> seconds for broadcast or multicast NTP message before terminating. The default is 68 seconds, chosen because ntpd typically transmits broadcasts/multicasts every 64 seconds. Note that the short option is <tt>-B</tt>, an uppercase letter B.</dd> + <dt><tt>-c, --concurrent</tt></dt> + <dd>Concurrently query all addresses returned for hostname. Requests from an NTP client to a single server should never be sent more often than once every two seconds. By default, all addresses resolved from a single hostname are assumed to be for a single instance of ntpd, and therefore sntp will send queries to these addresses one after another, waiting two seconds between queries. This option indicates multiple addresses returned for a hostname are on different machines, so sntp can send concurrent queries. This is appropriate when using *.pool.ntp.org, for example.</dd> + <dt><tt>-d, --debug-level</tt></dt> + <dd>Increase debug verbosity level by one. May be specified multiple times. See also the <tt>-D, --set-debug-level</tt> option.</dd> + <dt><tt>-D <i>debug-level</i>, --set-debug-level <i>debug-level</i></tt></dt> + <dd>Set the debug verbosity level to <i>debug-level</i>. The default level is zero. Note that the short option is <tt>-D</tt>, an uppercase letter D. See also the <tt>-d, --debug-level</tt> option.</dd> + <dt><tt>-g <i>delay</i>, --gap <i>delay</i></tt></dt> + <dd>Specify the <i>delay</i> in milliseconds between outgoing queries, defaulting to 50. <tt>sntp</tt> sends queries to all provided hostnames/addresses in short succession, and by default terminates once the first valid response is received. With multiple time sources provided, all but one will not be used. To limit the number of queries whose responses will not be used, each query is separated from the preceding one by <i>delay</i> milliseconds, to allow time for responses to earlier queries to be received. A larger <i>delay</i> reduces the query load on the time sources, increasing the time to receive a valid response if the first source attempted is slow or unreachable.</dd> + <dt><tt>-K <i>kodfile</i>, --kod <i>kodfile</i></tt></dt> + <dd>Specifies the filename <i>kodfile</i> to be used for the persistent history of KoD (Kiss Of Death, or rate-limiting) responses received from servers. The default is <tt>/var/db/ntp-kod</tt>. If the file does not exist, a warning message will be displayed. The file will not be created. Note that the short option is <tt>-K</tt>, an uppercase letter K.</dd> + <dt><tt>-k <i>keyfile</i>, --keyfile <i>keyfile</i></tt></dt> + <dd>Specifies the filename <i>keyfile</i> used with the <tt>-a</tt>/<tt>--authentication</tt> option. The format of the file is described on the <a href="keygen.html"><tt>ntp-keygen</tt> page</a>.</dd> + <dt><tt>-l <i>logfile</i>, --filelog <i>logfile</i></tt></dt> + <dd>Specifies the filename in which to append a copy of status messages, which also appear on the terminal.</dd> + <dt><tt>-M <i>steplimit</i>, --steplimit <i>steplimit</i></tt></dt> + <dd>If both <tt>-S</tt>/<tt>--step</tt> and <tt>-s</tt>/<tt>--slew</tt> options are provided, an offset of less than <i>steplimit</i> milliseconds will be corrected by slewing the clock using adjtime(), while an offset of <i>steplimit</i> or more will be corrected by setting the clock to the corrected time. Note that the short option is <tt>-M</tt>, an uppercase letter M.</dd> + <dt><tt>-o <i>ntpver</i>, --ntpversion <i>ntpver</i></tt></dt> + <dd>Specifies the NTP protocol version number <i>ntpver</i> to include in requests, default 4. This option is rarely useful.</dd> + <dt><tt>-r, --usereservedport</tt></dt> + <dd>By default, <tt>sntp</tt> uses a UDP source port number selected by the operating system. When this option is used, the reserved NTP port 123 is used, which most often requires <tt>sntp</tt> be invoked as the superuser (commonly "root"). This can help identify connectivity failures due to port-based firewalling which affect <tt>ntpd</tt>, which always uses source port 123.</dd> + <dt><tt>-S, --step</tt></dt> + <dd>By default, <tt>sntp</tt> displays the clock offset but does not attempt to correct it. This option enables offset correction by stepping, that is, directly setting the clock to the corrected time. This typically requires <tt>sntp</tt> be invoked as the superuser ("root"). Note that the short option is <tt>-S</tt>, an uppercase letter S.</dd> + <dt><tt>-s, --slew</tt></dt> + <dd>By default, <tt>sntp</tt> displays the clock offset but does not attempt to correct it. This option enables offset correction by slewing using adjtime(), which changes the rate of the clock for a period long enough to accomplish the required offset (phase) correction. This typically requires <tt>sntp</tt> be invoked as the superuser ("root").</dd> + <dt><tt>-u <i>uctimeout</i>, --uctimeout <i>uctimeout</i></tt></dt> + <dd>Specifies the maximum time <i>uctimeout</i> in seconds to wait for a unicast response before terminating.</dd> + <dt><tt>--wait</tt></dt> + <dd>When neither <tt>-S</tt>/<tt>--step</tt> nor <tt>-s</tt>/<tt>--slew</tt> options are provided, <tt>sntp</tt> will by default terminate after the first valid response is received. This option causes <tt>sntp</tt> to instead wait for all pending queries' responses.</dd> + <dt><tt>--version</tt></dt> + <dd>Display the <tt>sntp</tt> program's version number and the date and time it was compiled.</dd> +</dl> +<h4>Return Value</h4> +<p>The program returns an exit status of zero for if a valid response is received and non-zero otherwise.</p> +<h4>Author</h4> +<p>This <tt>sntp</tt> was originally developed by Johannes Maximilian Kuehn. Harlan Stenn and Dave Hart modified it to query more than one server at a time. See the file <tt>ChangeLog</tt> in the distribution for details.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/stats.html b/contrib/ntp/html/stats.html new file mode 100644 index 0000000..9438517 --- /dev/null +++ b/contrib/ntp/html/stats.html @@ -0,0 +1,70 @@ +<!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>Performance Metrics</title> +<link href="scripts/style.css" type="text/css" rel="stylesheet"> +</head> +<body> +<h3>Performance Metrics</h3> +<p>Last update: + <!-- #BeginDate format:En2m -->10-Mar-2014 05:23<!-- #EndDate --> + UTC</p> +<h4>Related Links</h4> +<script type="text/javascript" language="javascript" src="scripts/special.txt"></script> +<script type="text/javascript" language="javascript" src="scripts/external.txt"></script> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#intro">1. Introduction</a></li> + <li class="inline"><a href="#budget">2. Statistics Summary</a></li> + <li class="inline"><a href="#quality">3. Quality of Service</a></li> +</ul> +<hr> +<h4 id="intro">1. Introduction</h4> + +<p>This page describes several statistics provided in the NTP specification and reference implementation and how they determine the accuracy and error measured during routine and exceptional operation. These statistics provide the following information.</p> +<ul> + <li>Nominal estimate of the server clock time relative to the client clock time. This is called <em>clock offset</em> symbolized by the Greek letter θ.</li> + <li>Roundtrip system and network delay measured by the on-wire protocol. This is call <em>roundtrip delay</em> symbolized by the Greek letter δ.</li> + <li>Potential clock offset error due to the maximum uncorrected system clock frequency error. This is called <em>dispersion</em> symbolized by the Greek letter ε.</li> + <li>Expected error, consisting of the root mean square (RMS) nominal clock offset sample differencess in a sliding window of several samples. This is called <em>jitter</em> symbolized by the Greek letter φ.</li> +</ul> +<p> Figure 1 shows how the various measured statistics are collected and compiled to calibrate NTP performance.</p> +<div align="center"> +<img src="pic/stats.gif" alt="gif"> +<p>Figure 1. Statistics Budget</p> +</div> +<p>The data represented in boxes labeled Server are contained in fields in packet received from the server. The data represented in boxes labeled Peer are computed by the on-wire protocol, as described below. The algorithms of the box labeled Selection and Combining Algorithms process the peer data to select a system peer. The System box represents summary data inherited from the system peer. These data are available to application programs and dependent downstream clients.</p> +<h4 id="budget">2. Statistics Summary</h4> +<p>Each NTP synchronization source is characterized by the offset θ and delay δ samples measured by the on-wire protocol, as described on the <a href="warp.html">How NTP Works</a> page. In addition, the dispersion ε sample is initialized with the sum of the source precision ρ<sub>R</sub> and the client precision ρ (not shown) as each source packet is received. The dispersion increases at a rate of 15 μs/s after that. For this purpose, the precision is equal to the latency to read the system clock. The offset, delay and dispersion are called the sample statistics.</p> +<blockquote> + <p>Note. In very fast networks where the client clock frequency is not within 1 PPM or so of the the server clock frequency, the roundtrip delay may have small negative values. This is usually a temporary condition when the client is first started. When using the roundtrip delay in calculations, negative values are assumed zero.</p> +</blockquote> +<p> In a window of eight (offset, delay, dispersion) samples, the algorithm described on the <a href="filter.html">Clock Filter Algorithm</a> page selects the sample with minimum delay, which generally represents the most accurate offset statistic. The selected offset sample determines the <em>peer offset</em> and <em>peer delay </em>statistics. The <em>peer dispersion</em> is a weighted average of the dispersion samples in the window. These quantities are recalculated as each update is received from the source. Between updates, both the sample dispersion and peer dispersion continue to grow at the same rate, 15 μs/s. Finally, the <em>peer jitter</em> φ is determined as the RMS differences between the offset samples in the window relative to the selected offset sample. The peer statistics are recorded by the <tt>peerstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. Peer variables are displayed by the <tt>rv</tt> command of the <a href="ntpq.html#peer"><tt>ntpq</tt></a> program.</p> +<p> The clock filter algorithm continues to process updates in this way until the source is no longer reachable. Reachability is determined by an eight-bit shift register, which is shifted left by one bit as each poll packet is sent, with 0 replacing the vacated rightmost bit. Each time a valid update is received, the rightmost bit is set to 1. The source is considered reachable if any bit is set to 1 in the register; otherwise, it is considered unreachable. When a source becomes unreachable, a dummy sample with "infinite" dispersion is inserted in the filter window at each poll, thus displacing old samples. This causes the peer dispersion to increase eventually to infinity.</p> +<p>The composition of the source population and the system peer selection is redetermined as each update from each source is received. The system peer and system variables are determined as described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. The system variables Θ, Δ, Ε and Φ are updated from the system peer variables of the same name and the system stratum set one greater than the system peer stratum. The system statistics are recorded by the <tt>loopstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. System variables are displayed by the <tt>rv</tt> command of the <a href="ntpq.html#system"><tt>ntpq</tt></a> program.</p> +<p>Although it might seem counterintuitive, a cardinal rule in the selection process is, once a sample has been selected by the clock filter algorithm, older samples are no longer selectable. This applies also to the clock select algorithm. Once the peer variables for a source have been selected, older variables of the same or other sources are no longer selectable. The reason for these rules is to limit the time delay in the clock discipline algorithm. This is necessary to preserve the optimum impulse response and thus the risetime and overshoot.</p> +<p>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 for 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 id="quality">3. Quality of Service</h4> +<p>This section discusses how an NTP client determines the system performance using a peer population including reference clocks and remote servers. This is determined for each peer from two statistics, <em>peer jitter</em> and <em>root distance.</em> Peer jitter is determined from various jitter components as described above. It represents the expected error in determining the clock offset estimate. Root distance represents the maximum error of the estimate due to all causes.</p> +<p>The root distance statistic is computed as one-half the <em> root delay</em> of the primary source of time; i.e., the reference clock, plus the <em> root dispersion</em> of that source. The root variables are included in the NTP packet header received from each source. At each update the root delay is recomputed as the sum of the root delay in the packet plus the peer delay, while the root dispersion is recomputed as the sum of the root dispersion in the packet plus the peer dispersion.</p> +<blockquote> + <p>Note. In order to avoid timing loops, the root distance is adjusted to the maximum of the above computation and a <em>minimum threshold.</em> The minimum threshold defaults to 1 ms, but can be changed according to client preference using the <tt>mindist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command.</p> +</blockquote> +<p>A source is considered selectable only if its root distance is less than the <em>select threshold</em>, by default 1.5 s, but can be changed according to client preference using the <tt>maxdist</tt> option of the <a href="miscopt.html#tos"><tt>tos</tt></a> command. When an upstream server loses all sources, its root distance apparent to dependent clients continues to increase. The clients are not aware of this condition and continue to accept synchronization as long as the root distance is less than the select threshold.</p> +<p>The root distance statistic is used by the select, cluster and mitigation algorithms. In this respect, it is sometimes called the <em>synchronization distance</em> often shortened simply to <em>distance</em>. The root distance is also used in the following ways.</p> +<ul> + <li>Root distance defines the maximum error of the clock offset estimate due to all causes as long as the source remains reachable..</li> + <li>Root distance defines the upper and lower limits of the correctness interval. This interval represents the maximum clock offset for each of possibly several sources. The clock select algorithm computes the intersection of the correctness intervals to determine the truechimers from the selectable source population.</li> + <li>Root distance is used by the clock cluster algorithm as a weight factor when pruning outlyers from the truechimer population.</li> + <li>The (normalized) reciprocal of the root distance is used as a weight factor by the combine algorithm when computing the system clock offset and system jitter.</li> + <li>Root distance is used by the mitigation algorithm to select the system peer from among the cluster algorithm survivors.</li> +</ul> +<p>The root distance thus functions as a metric in the selection and weighting of the various available sources. The strategy is to select the system peer as the source with the minimum root distance and thus the minimum maximum error. The reference implementation uses the Bellman-Ford algorithm described in the literature, where the goal is to minimize the root distance. The algorithm selects the <em>system peer</em>, from which the system root delay and system root dispersion are inherited.</p> +<p>The algorithms described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page deliver several important statistics. The <em>system offset</em> and <em>system jitter</em> are weighted averages computed by the clock combine algorithm. System offset is best interpreted as the maximum-likelihood estimate of the system clock offset, while system jitter, also called estimated error, is best interpreted as the expected error of this estimate. <em>System delay</em> is the root delay inherited from the system peer, while <em>s</em><em>ystem dispersion</em> is the root dispersion plus contributions due to jitter and the absolute value of the system offset.</p> +<p>The maximum system error, or <em>system distance</em>, is computed as one-half the system delay plus the system dispersion. In order to simplify discussion, certain minor contributions to the maximum error statistic are ignored. If the precision time kernel support is available, both the estimated error and maximum error are reported to user programs via the <tt>ntp_adjtime()</tt> kernel system call. See the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page for further information.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/tickadj.html b/contrib/ntp/html/tickadj.html index 14559ed..3c38f84 100644 --- a/contrib/ntp/html/tickadj.html +++ b/contrib/ntp/html/tickadj.html @@ -1,49 +1,45 @@ <!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:50</csobj> UTC <csobj format="LongDate" h="25" locale="00000409" region="0" t="DateTime" w="246">Thursday, July 28, 2005</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 precision time support, including Solaris, Tru64, FreeBSD and Linux (with PPSkit patch) should NOT use the program. 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 SunOS4. - <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> - <pre> -/vmunix - -/unix - -/dev/kmem -</pre> - <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 -->10-Mar-2014 05:24<!-- #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> diff --git a/contrib/ntp/html/warp.html b/contrib/ntp/html/warp.html new file mode 100644 index 0000000..1d42dd6 --- /dev/null +++ b/contrib/ntp/html/warp.html @@ -0,0 +1,60 @@ +<!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 -->10-Mar-2014 05:24<!-- #EndDate --> + UTC</p> +<h4>Related Links</h4> +<script type="text/javascript" language="javascript" src="scripts/special.txt"></script> +<script type="text/javascript" language="javascript" src="scripts/external.txt"></script> +<h4>Table of Contents</h4> +<ul> + <li class="inline"><a href="#intro">1. Introduction and Overview</a></li> + <li class="inline"><a href="#scale">2. NTP Timescale and Data Formats</a></li> + <li class="inline"><a href="#arch">3. Architecture and Algorithms</a></li> +</ul> +<hr> +<h4 align="center">Abstract</h4> +<blockquote> + <p align="left"> This page and its dependencies contain a technical description of the Network Time Protocol (NTP) architecture and operation. It is intended for administrators, operators and monitoring personnel. Additional information for nontechnical readers can be found in the white paper <a href="http://www.eecis.udel.edu/~mills/exec.html">Executive Summary: Computer Network Time Synchronization</a>. While this page and its dependencies are primarily concerned with NTP, additional information on related protocols can be found in the white papers <a href="http://www.eecis.udel.edu/~mills/ptp.html">IEEE 1588 Precision Time Protocol (PTP)</a> and <a href="http://www.eecis.udel.edu/~mills/proximity.html">Time Synchronization for Space Data Links</a>. Note that reference to a page in this document collection is to a page in the collection, while reference to a <em>white paper</em> is to a document at the <a href="http://www.eecis.udel.edu/~mills/ntp.html">Network Time Synchronization Research Project</a> web site.</p> +</blockquote> +<h4 id="intro">1. Introduction and Overview</h4> + +<p>NTP time synchronization services are widely available in the public Internet. The public NTP subnet currently includes several thousand servers in most countries and on every continent of the globe, including Antarctica, and sometimes in space and on the sea floor. These servers support, directly or indirectly, a total population estimated at over 25 million computers in the global Internet.</p> +<p> 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 via satellite, radio or telephone modem. Stratum 2 (secondary) servers at the next higher level are synchronized 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 page presents an overview of the NTP implementation included in this software distribution. We refer to this implementation as the <em>reference implementation</em> only because it was used to test and validate the NTPv4 specification RFC-5905. It is best read in conjunction with the briefings and white papers on the <a href="http://www.eecis.udel.edu/~mills/ntp.html">Network Time Synchronization Research Project</a> page. An executive summary suitable for management and planning purposes is in the white paper <a href="http://www.eecis.udel.edu/~mills/exec.html">Executive Summary: Computer Network Time Synchronization</a>.</p> +<h4 id="scale">2. NTP Timescale and Data Formats</h4> +<p>NTP clients and servers synchronize to the Coordinated Universal Time (UTC) timescale used by national laboratories and disseminated by radio, satellite and telephone modem. This is a global timescale independent of geographic position. There are no provisions to correct for local time zone or daylight savings time; however, these functions can be performed by the operating system on a per-user basis.</p> +<p> The UT1 timescale, upon which UTC is based, is determined by the rotation of the Earth about its axis. The Earth rotation is gradually slowing down relative to International Atomic Time (TAI). In order to rationalize UTC with respect to TAI, a leap second is inserted at intervals of about 18 months, as determined by the International Earth Rotation Service (IERS). Reckoning with leap seconds in the NTP timescale is described in the white paper <a href="http://www.eecis.udel.edu/~mills/leap.html">The NTP Timescale and Leap Seconds</a>.</p> +<p>The historic insertions are documented in the <tt>leap-seconds.list</tt> file, which can be downloaded from the NIST FTP servers. This file is updated at intervals not exceeding six months. Leap second warnings are disseminated by the national laboratories in the broadcast timecode format. These warnings are propagated from the NTP primary servers via other server to the clients by the NTP on-wire protocol. The leap second is implemented by the operating system kernel, as described in the white paper <a href="http://www.eecis.udel.edu/~mills/leap.html">The NTP Timescale and Leap Seconds</a>. Implementation details are described on the <a href="leap.html">Leap Second Processing</a> page.</p> +<div align="center"> +<img src="pic/time1.gif" alt="gif"> +<p>Figure 1. NTP Data Formats</p> +</div> +<p>Figure 1 shows two NTP time formats, a 64-bit <em>timestamp</em> format and a 128-bit <em>datestamp</em> format. The datestamp format is used internally, while the timestamp format is used in packet headers exchanged between clients and servers. The timestamp format spans 136 years, called an <em>era</em>. The current era began on 1 January 1900, while the next one begins in 2036. Details on these formats and conversions between them are in the white paper <a href="http://www.eecis.udel.edu/~mills/y2k.html">The NTP Era and Era Numbering</a>. However, the NTP protocol will synchronize correctly, regardless of era, as long as the system clock is set initially within 68 years of the correct time. Further discussion on this issue is in the white paper <a href="http://www.eecis.udel.edu/~mills/time.html">NTP Timestamp Calculations</a>. Ordinarily, these formats are not seen by application programs, which convert these NTP formats to native Unix or Windows formats.</p> +<h4 id="arch">3. Architecture and Algorithms</h4> +<div align="center"> + <p><img src="pic/fig_3_1.gif" alt="gif"></p> + <p>Figure 2. NTP Daemon Processes and Algorithms</p> +</div> +<p>The overall organization of the NTP architecture is shown in Figure 2. It is useful in this context to consider the implementation as both a client of upstream (lower stratum) servers and as a server for downstream (higher stratum) clients. It includes a pair of peer/poll processes for each reference clock or remote server used as a synchronization source. Packets are exchanged between the client and server using the <em>on-wire protocol</em> described 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 protocol is resistant to lost, replayed or spoofed packets.</p> +<p> The poll process sends NTP packets at intervals ranging from 8 s to 36 hr. The intervals are managed as described on the <a href="poll.html">Poll Process</a> page to maximize accuracy while minimizing network load. The peer process receives NTP packets and performs the packet sanity tests described on the <a href="decode.html">Event Messages and Status Words</a> page and <a href="decode.html#flash">flash status word</a>. The flash status word reports in addition the results of various access control and security checks described in the white paper <a href="http://www.eecis.udel.edu/~mills/security.html">NTP Security Analysis</a>. A sophisticated traffic monitoring facility described on the <a href="rate.html">Rate Management and the Kiss-o'-Death Packet</a> page protects against denial-of-service (DoS) attacks.</p> +<p>Packets that fail one or more of these tests are summarily discarded. Otherwise, the peer process runs the on-wire protocol that uses four raw timestamps: the <em>origin timestamp</em> <em>T</em><sub>1</sub> upon departure of the client request, 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, which are recorded by the <tt>rawstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command, are used to calculate the clock offset and roundtrip delay samples:</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>In this description the transmit timestamps <em>T</em><sub>1</sub> and <em>T</em><sub>3</sub> are <em>softstamps</em> measured by the inline code. Softstamps are subject to various queuing and processing delays. A more accurate measurement uses <em>drivestamps</em>, as described on the <a href="xleave.html">NTP Interleaved Modes</a> page. These issues along with mathematical models are discussed in the white paper <a href="http://www.eecis.udel.edu/~mills/time.html">NTP Timestamp Calculations</a>.</p> +<p>The offset and delay statistics for one or more peer processes are processed by a suite of mitigation algorithms. The algorithm described on the <a href="filter.html">Clock Filter Algorithm</a> page selects the offset and delay samples most likely to produce accurate results. Those servers that have passed the sanity tests are declared <em>selectable</em>. From the selectable population the statistics are used by the algorithm described on the <a href="select.html">Clock Select Algorithm</a> page to determine a number of <em>truechimers</em> according to Byzantine agreement and correctness principles. From the truechimer population the algorithm described on the <a href="cluster.html">Clock Cluster Algorithm</a> page determines a number of <em>survivors</em> on the basis of statistical clustering principles.</p> +<p> The algorithms described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page combine the survivor offsets, designate one of them as the <em>system peer</em> and produces the final offset used by the algorithm described on the <a href="discipline.html">Clock Discipline Algorithm</a> page to adjust the system clock time and frequency. The clock offset and frequency, are recorded by the <tt>loopstats</tt> option of the <a href="monopt.html#filegen"><tt>filegen</tt></a> command. For additional details about these algorithms, see the Architecture Briefing on the <a href="http://www.eecis.udel.edu/~mills/ntp.html">Network Time Synchronization Research Project</a> page. For additional information on statistacl principles and performance metrics, see the <a href="stats.html">Performance Metrics</a> page.</p> +<hr> +<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script> +</body> +</html> diff --git a/contrib/ntp/html/xleave.html b/contrib/ntp/html/xleave.html new file mode 100644 index 0000000..417185c --- /dev/null +++ b/contrib/ntp/html/xleave.html @@ -0,0 +1,30 @@ +<!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 -->10-Mar-2014 05:25<!-- #EndDate --> + UTC</p> +<br clear="left"> +<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 μs for a dual-core Pentium running FreeBSD 6.1 to 1100 μ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/proximity.html">Time Synchronization for 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> |