diff options
| author | roberto <roberto@FreeBSD.org> | 1999-12-09 13:01:21 +0000 |
|---|---|---|
| committer | roberto <roberto@FreeBSD.org> | 1999-12-09 13:01:21 +0000 |
| commit | ef64b99e8412f2273dd2e8b3291c2f78ffc4667f (patch) | |
| tree | fc0cfa1aab0ff6b228f511b410733ef4f35d1ead /contrib/ntp/html | |
| download | FreeBSD-src-ef64b99e8412f2273dd2e8b3291c2f78ffc4667f.zip FreeBSD-src-ef64b99e8412f2273dd2e8b3291c2f78ffc4667f.tar.gz | |
Virgin import of ntpd 4.0.98f
Diffstat (limited to 'contrib/ntp/html')
96 files changed, 18312 insertions, 0 deletions
diff --git a/contrib/ntp/html/accopt.htm b/contrib/ntp/html/accopt.htm new file mode 100644 index 0000000..d64a0d1 --- /dev/null +++ b/contrib/ntp/html/accopt.htm @@ -0,0 +1,219 @@ +<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>Access Control Options +</TITLE> +</HEAD> +<BODY> + +<H3> +Access Control Options</H3> + +<HR> +<H4> +Access Control Support</H4> +<TT>ntpd</TT> implements a general purpose address-and-mask based restriction +list. The list is sorted by address and by mask, and the list is searched +in this order for matches, with the last match found defining the restriction +flags associated with the incoming packets. The source address of incoming +packets is used for the match, with the 32-bit address being and'ed with +the mask associated with the restriction entry and then compared with the +entry's address (which has also been and'ed with the mask) to look for +a match. Additional information and examples can be found in the <A HREF="notes.htm">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. While this facility +may be otherwise useful for keeping unwanted or broken remote time servers +from affecting your own, it should not be considered an alternative to +the standard NTP authentication facility. Source address based restrictions +are easily circumvented by a determined cracker. +<H4> +Access Control Commands</H4> + +<DL> +<DT> +<TT>restrict <I>numeric_address</I> [mask <I>numeric_mask</I>] [<I>flag</I>] +[...]</TT></DT> + +<DD> +The <I><TT>numeric_address</TT></I> argument, expressed in dotted-quad +form, is the address of an host or network. The <I><TT>mask</TT></I> argument, +also expressed in dotted-quad form, defaults to <TT>255.255.255.255</TT>, +meaning that the <I><TT>numeric_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, given the sort algorithm, is +always the first entry in the list. Note that, while <I><TT>numeric_address</TT></I> +is normally given in dotted-quad format, the text string <TT>default</TT>, +with no mask option, may be used to indicate the default entry.</DD> + +<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:</DD> + +<DD> + </DD> + +<DL> +<DT> +<TT>ignore</TT></DT> + +<DD> +Ignore all packets from hosts which match this entry. If this flag is specified +neither queries nor time server polls will be responded to.</DD> + +<DD> + </DD> + +<DT> +<TT>noquery</TT></DT> + +<DD> +Ignore all NTP mode 6 and 7 packets (i.e. information queries and configuration +requests) from the source. Time service is not affected.</DD> + +<DD> + </DD> + +<DT> +<TT>nomodify</TT></DT> + +<DD> +Ignore all NTP mode 6 and 7 packets which attempt to modify the state of +the server (i.e. run time reconfiguration). Queries which return information +are permitted.</DD> + +<DD> + </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 mode 6 control message protocol +which is intended for use by remote event logging programs.</DD> + +<DD> + </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> + +<DD> + </DD> + +<DT> +<TT>noserve</TT></DT> + +<DD> +Ignore NTP packets whose mode is other than 6 or 7. In effect, time service +is denied, though queries may still be permitted.</DD> + +<DD> + </DD> + +<DT> +<TT>nopeer</TT></DT> + +<DD> +Provide stateless time service to polling hosts, but do not allocate peer +memory resources to these hosts even if they otherwise might be considered +useful as future synchronization partners.</DD> + +<DD> + </DD> + +<DT> +<TT>notrust</TT></DT> + +<DD> +Treat these hosts normally in other respects, but never use them as synchronization +sources.</DD> + +<DD> + </DD> + +<DT> +<TT>limited</TT></DT> + +<DD> +These hosts are subject to limitation of number of clients from the same +net. Net in this context refers to the IP notion of net (class A, class +B, class C, etc.). Only the first <TT>client_limit</TT> hosts that have +shown up at the server and that have been active during the last <TT>client_limit_period</TT> +seconds are accepted. Requests from other clients from the same net are +rejected. Only time request packets are taken into account. Query packets +sent by the <TT>ntpq</TT> and <TT>ntpdc</TT> programs are not subject to +these limits. 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.</DD> + +<DD> + </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). 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.</DD> + +<DD> + </DD> +</DL> + +<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> + +<DD> + </DD> + +<DT> +<TT>clientlimit <I>limit</I></TT></DT> + +<DD> +Set the <TT>client_limit</TT> variable, which limits the number of simultaneous +access-controlled clients. The default value for this variable is 3.</DD> + +<DD> + </DD> + +<DT> +<TT>clientperiod <I>period</I></TT></DT> + +<DD> +Set the <TT>client_limit_period</TT> variable, which specifies the number +of seconds after which a client is considered inactive and thus no longer +is counted for client limit restriction. The default value for this variable +is 3600 seconds.</DD> +</DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/assoc.htm b/contrib/ntp/html/assoc.htm new file mode 100644 index 0000000..69cb7bc --- /dev/null +++ b/contrib/ntp/html/assoc.htm @@ -0,0 +1,170 @@ +<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>Release Notes +</TITLE> +</HEAD> +<BODY> + +<H3> +Association Management</H3> + +<HR> +<H4> +Association Modes</H4> +This release of the NTP Version 4 (NTPv4) daemon for Unix incorporates +new features and refinements to the NTP Version 3 (NTPv3) algorithms. However, +it continues the tradition of retaining backwards compatibility with older +versions. 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 implemented in the current NTPv3, including a number of new +operating modes for automatic server discovery and improved accuracy in +occasionally-connected networks. Following is an extended abstract describing +the new features.. + +<P>An ephemeral association of some mode is mobilized when a message arrives +from another client or server. For instance, a symmetric-passive association +is mobilized upon arrival of a message from a symmetric- active peer. A +client association is mobilized upon arrival of a broadcast message from +a multicast server or a server message from a manycast server. Ephemeral +associations are demobilized when either (a) the server becomes unreachable +or (b) an error occurs on initial contact before the association is mobilized. + +<P>The one exception to (a) and (b) above is when +<TT><A HREF="authopt.htm">autokey</A></TT> is in use and the initial +authentication check fails due to unknown +key identifier or autokey mismatch. This exception is necessary because +the Unix kernel does not bind the local address until the first packet +is received. The result in broadcast mode is a rather painful initial exchange, +where authentication fails until after the first round of messages. The +result in multicast mode is in general fatal, especially if multiple interfaces +are in use. As promiscuous modes such as multicast and manycast require +authentication for reliable and safe operation, autokey is in general useless +with these modes until and if the input/output machinery is overhauled. + +<P>Following is a summary of the protocol operations for each mode. + +<P>Peer Modes (Active and Passive) +<UL>In these modes, two client/server peers agree to back each other up, +should the synchronization source for either peer fail. One or both peers +is configured in symmetric-active mode using the peer command. Alternatively, +one - the active peer - is configured in this mode and the other, the passive +peer, operates in symmetric-passive mode and requires no prior configuration. +Both association scenarios operate in NTPv4 as in NTPv3; however, several +bugs in the handling of keys and recovery of resources when an active peer +fails, have been corrected in NTPv4. The original NTPv3 authentication +scheme is applicable in this mode, as well as the new NTPv3 autokey scheme.</UL> +Client/Server Modes +<UL>In these modes, a client sends a request to the server and expects +a reply at some future time. The client is configured in client mode using +the server (sic) command; the server requires no prior configuration. The +original NTPv3 authentication scheme is applicable in this mode, as well +as the new NTPv3 autokey scheme.</UL> +Broadcast/Multicast Modes +<UL>In these modes, the server generates messages at intervals specified +by the minpoll subcommand. When using IP multicast addresses, the scope +of the multicast tree is specified by the ttl subcommand in hops. When +using a local interface broadcast address, the scope is limited to the +attached subnet. The client responds to the first message received by waiting +an interval randomized over the minpoll interval, in order to avoid implosions. +Then, it polls the server in burst mode, in order to accumulate data to +reliably set the host clock. This normally results in eight client/server +cycles over a 32-s interval. When the next multicast message is received, +the client computes the offset between the system clock just set and the +apparent time of the multicast message in order to correct the apparent +time in future multicast messages.</UL> +Manycast Mode +<UL>In this mode, a configured client broadcasts a request message as in +client mode to a designated multicast group address. All servers configured +as manycast clients and in ttl range respond with a server reply message. +Each reply mobilizes a persistent client/server association as in client +mode. Then, the NTP intersection and clustering algorithms act to discard +all but the "best" of these associations, which then continue as in client/server +mode.</UL> + +<H4> +Burst Mode</H4> +Burst mode can be configured when the network attachment requires an initial +calling or training procedure. Each poll initiates a burst of eight request +messages at intervals randomized over the range 3-5 s. The reply messages +update the clock filter, which then selects the best (most accurate) among +them. When the last reply in the burst is sent, the next reply updates +the client variables and system clock in the usual manner, as if only a +single request/reply cycle had occurred. This mode 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 above +1024 s. +<H4> +Revised Error Checking</H4> +It is very important to avoid spurious mobilizations from possibly broken +or rogue servers; in particular, to avoid denial-of-service attacks. In +order to resist such attacks, arriving messages that might mobilize ephemeral +associations are carefully screened using a series of eleven sanity checks. +<OL> +<LI> +Duplicate packet. This message is a duplicate of one previously received.</LI> + +<BR> +<LI> +Bogus packet. This message did not result from a message previously sent, +or messages have been received out of order.</LI> + +<BR> +<LI> +Unsynchronized. The server has not yet stored the previous timestamps.</LI> + +<BR> +<LI> +Invalid delay or dispersion. Either the delay or dispersion or both computed +from the message timestamps are above the normal range.</LI> + +<BR> +<LI> +Authentication failed. The sent MAC does not match the received MAC, either +due to the wrong key material or damaged message.</LI> + +<BR> +<LI> +Server unsynchronized. The server indicates unsynchronized in the leap +bits included in the packet.</LI> + +<BR> +<LI> +Server stratum check. The server is operating at a stratum above the normal +range.</LI> + +<BR> +<LI> +Delay/dispersion check. The related server packet data values are above +the normal range.</LI> + +<BR> +<LI> +Autokey failed. The hash of the current session key does not match the +most recent key identifiers used. (The hash is repeated four times, in +order to recover from lost packets whenever possible.)</LI> + +<BR> +<LI> +Access denied. The sender has been blocked by the access control list.</LI> + +<BR> +<LI> +Key not found. The key identifier does not match any identifier in the +key list or the key has expired or been revoked.</LI> +</OL> +Failure to pass tests 5-11 is sufficient evidence to discard the packet +without forming an association. However, failure to pass tests 1-4 is not +necessarily grounds to reject the packet, since subsequent packets may +be acceptable. In this case, the association is mobilized, but only the +packet timestamps are stored. For the moment, and until the cryptographic +signature algorithm is available, test 9 is temporarily disabled. +<BR> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +<BR> +</BODY> +</HTML> diff --git a/contrib/ntp/html/authopt.htm b/contrib/ntp/html/authopt.htm new file mode 100644 index 0000000..506d4f3 --- /dev/null +++ b/contrib/ntp/html/authopt.htm @@ -0,0 +1,281 @@ +<HTML><HEAD><TITLE> +Authentication Options +</TITLE></HEAD><BODY><H3> +Authentication Options +</H3><HR> + +<H4>Authentication Support</H4> + +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 an scheme which provides cryptographic authentication of received +NTP packets. Originally, this was done using the Data Encryption Standard +(DES) operating in Cipher Block Chaining (CBC) mode, commonly called DES-CBC. +Subsequently, this was augmented by the RSA Message Digest 5 (MD5) 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. NTPv4 retains this scheme and, +in addition, provides a new <I>autokey </I>scheme based on reverse hashing +and public key cryptography. Authentication can be configured separately +for each association using the <TT>key </TT>or <TT>autokey </TT>subcommands +on the <TT>peer</TT>, <TT>server</TT>, <TT>broadcast</TT> and <TT>manycastclient</TT> +commands as described in the <A HREF="config.htm">Configuration Options</A> +page. + +<P>The authentication options specify the suite of keys, select the key +for each configured association and manage the configuration operations, +as described below. The <TT>auth</TT> flag which controls these functions +can be set or reset by the <TT>enable</TT> and <TT>disable</TT> configuration +commands and also by remote configuration commands sent by a <TT>ntpdc</TT> +program running in another machine. If this flag is set, persistent peer +associations and remote configuration commands are effective only if cryptographically +authenticated. If this flag is disabled, these operations are effective +even if not cryptographic authenticated. It should be understood that operating +in the latter mode invites a significant vulnerability where a rogue hacker +can seriously disrupt client operations. + +<P>The <TT>auth</TT> flag affects all authentication procedures described +below; however, it operates differently if cryptographic support is compiled +in the distribution. If this support is available and the flag is enabled, +then persistent associations are mobilized and remote configuration commands +are effective only if successfully authenticated. If the support is unavailable +and the flag is enabled, then it is not possible under any conditions to +mobilize persistent associations or respond to remote configuration commands. +The <TT>auth </TT>flag normally defaults to set if cryptographic support +is available and to reset otherwise. + +<P>With the above vulnerabilities in mind, it is desirable to set the auth +flag in all cases. One aspect which is often confusing is the name resolution +process which maps server names in the configuration file to IP addresses. +In order to protect against bogus name server messages, this process is +authenticated using an internally generated key which is normally invisible +to the user. However, if cryptographic support is unavailable and the <TT>auth</TT> +flag is enabled, the name resolution process will fail. This can be avoided +either by specifying IP addresses instead of host names, which is generally +inadvisable, or by leaving the flag disabled and enabling it once the name +resolution process is complete. +<H4> +Private Key Scheme</H4> +The original RFC-1305 specification allows any one of possibly 65,536 keys, +each distinguished a 32-bit key identifier, to authenticate an association. +The servers involved must agree on the key and key identifier to authenticate +their messages. Keys and related information are specified in a key file, +usually called <TT>ntp.key</TT>s, which should be exchanged and stored +using secure procedures beyond the scope of the NTP protocol itself. Besides +the keys used for ordinary NTP associations, additional ones can be used +as passwords for the <TT><A HREF="ntpq.htm">ntpq</A></TT> and <TT><A HREF="ntpdc.htm">ntpdc</A></TT> +utility programs. + +<P>When <TT>ntpd </TT>is first started, it reads the key file and installs +the keys in the key cache. However, the keys must be activated before they +can be used with the <TT>trusted </TT>command. This allows, for instance, +the installation of possibly several batches of keys and then activating +or inactivating 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 the <TT>ntpq </TT>utility. +<H4> +Autokey Scheme</H4> +The original NTPv3 authentication scheme described in RFC-1305 continues +to be supported. In NTPv4, an additional authentication scheme called <I>autokey +</I>is available. It operates much like the S-KEY scheme, in that a session +key list is constructed and the entries used in reverse order. A description +of the scheme, along with a comprehensive security analysis, is contained +in a technical report available from the IETF web page <A HREF="www.ietf.org">www.ietf.org</A> +. + +<P>The autokey scheme is specifically designed for multicast modes, where +clients normally do not send messages to the server. In these modes, the +server uses the scheme to generate a key list by repeated hashing of a +secret value. The list is used in reverse order to generate a unique session +key for each message sent. The client regenerates the session key and verifies +the hash matches the previous session key. Each message contains the public +values binding the session key to the secret value, but these values need +to be verified only when the server generates a new key list or more than +four server messages have been lost. + +<P>The scheme is appropriate for client/server and symmetric-peer modes +as well. In these modes, the client generates a session key as in multicast +modes. The server regenerates the session key and uses it to formulates +a reply using its own public values. The client verifies the key identifier +of the reply matches the request, verifies the public values and validates +the message. In peer mode, each peer independently generates a key list +and operates as in the multicast mode. + +<P>The autokey scheme requires no change to the NTP packet header format +or message authentication code (MAC), which is appended to the header; +however, if autokey is in use, an extensions field is inserted between +the header and MAC. The extensions field contains a random public value +which is updated at intervals specified by the revoke command, together +with related cryptographic values used in the signing algorithm. The format +of the extensions field is defined in Internet Draft draft-NTP- auth-coexist-00.txt. +The MAC itself is constructed in the same way as NTPv3, but using the original +NTP header and the extensions field padded to a 64-bit boundary. Each new +public value is encrypted by the host private value. It is the intent of +the design, not yet finalized, that the public value, encrypted public +value, public key and certificate be embedded in the extensions field where +the client can decrypt as needed. However, the relatively expensive encryption +and decryption operations are necessary only when the public value is changed. + +<P>Note that both the original NTPv3 authentication scheme and the new +NTPv4 autokey scheme operate separately for each configured association, +so there may be several session key lists operating independently at the +same time. Since all keys, including session keys, occupy the same key +cache, provisions have been made to avoid collisions, where some random +roll happens to collide with another already generated. Since something +like four billion different session key identifiers are available, the +chances are small that this might happen. If it happens during generation, +the generator terminates the current session key list. By the time the +next list is generated, the collided key will probably have been expired +or revoked. + +<P>While permanent keys have lifetimes that expire only when manually revoked, +random session keys have a lifetime specified at the time of generation. +When generating a key list for an association, the lifetime of each key +is set to expire one poll interval later than it is scheduled to be used. +The maximum lifetime of any key in the list is specified by the <TT>autokey</TT> +command. Lifetime enforcement is a backup to the normal procedure that +revokes the last-used key at the time the next key on the key list is used. +<H4> +Authentication Commands</H4> + +<DL> +<DT> +<TT>keys <I>keyfile</I></TT></DT> + +<DD> +Specifies the file name containing the encryption keys and key identifiers +used by <TT>ntpd</TT>, <TT>ntpq</TT> and <TT>ntpdc</TT> when operating +in authenticated mode. The format of this file is described later in this +document.</DD> + +<DD> + </DD> + +<DT> +<TT>trustedkey <I>key</I> [...]</TT></DT> + +<DD> +Specifies the encryption key identifiers which are trusted for the purposes +of authenticating peers suitable for synchronization, 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 <I><TT>key</TT></I> arguments are 32-bit unsigned integers +with values less than 65,536. Note that NTP key 0 is used to indicate an +invalid key and/or key identifier, so should not be used for any other +purpose.</DD> + +<DD> + </DD> + +<DT> +<TT>requestkey <I>key</I></TT></DT> + +<DD> +Specifies the key identifier to use with the <TT>ntpdc</TT> program, which +uses a proprietary protocol specific to this implementation of <TT>ntpd</TT>. +This program is useful to diagnose and repair problems that affect <TT>ntpd</TT> +operation. The <I><TT>key</TT></I> argument to this command is a 32-bit +key identifier for a previously defined trusted key. If no <TT>requestkey +</TT>command is included in the configuration file, or if the keys don't +match, any request to change a server variable with be denied.</DD> + +<DD> + </DD> + +<DT> +<TT>controlkey <I>key</I></TT></DT> + +<DD> +Specifies the key identifier to use with the <TT>ntpq</TT> program, which +uses the standard protocol defined in RFC-1305. This program is useful +to diagnose and repair problems that affect <TT>ntpd</TT> operation. The +<I><TT>key</TT></I> argument to this command is a 32-bit key identifier +for a trusted key in the key cache. If no <TT>controlkey </TT>command is +included in the configuration file, or if the keys don't match, any request +to change a server variable with be denied.</DD> +</DL> + +<H4> +Authentication Key File Format</H4> +In the case of DES, the keys are 56 bits long with, depending on type, +a parity check on each byte. In the case of MD5, the keys are 64 bits (8 +bytes). <TT>ntpd</TT> reads its keys from a file specified using the <TT>-k</TT> +command line option or the <TT>keys</TT> statement in the configuration +file. While key number 0 is fixed by the NTP standard (as 56 zero bits) +and may not be changed, one or more of the keys numbered 1 through 15 may +be arbitrarily set in the keys file. + +<P>The key file uses the same comment conventions as the configuration +file. Key entries use a fixed format of the form + +<P><I><TT>keyno type key</TT></I> + +<P>where <I><TT>keyno</TT></I> is a positive integer, <I><TT>type</TT></I> +is a single character which defines the key format, and <I><TT>key</TT></I> +is the key itself. + +<P>The key may be given in one of three different formats, controlled by +the <I><TT>type</TT></I> character. The three key types, and corresponding +formats, are listed following. +<DL> +<DT> +<TT>S</TT></DT> + +<DD> +The key is a 64-bit hexadecimal number in the format specified in the DES +specification; that is, the high order seven bits of each octet are used +to form the 56-bit key while the low order bit of each octet is given a +value such that odd parity is maintained for the octet. Leading zeroes +must be specified (i.e., the key must be exactly 16 hex digits long) and +odd parity must be maintained. Hence a zero key, in standard format, would +be given as <TT>0101010101010101</TT>.</DD> + +<DD> + </DD> + +<DT> +<TT>N</TT></DT> + +<DD> +The key is a 64-bit hexadecimal number in the format specified in the NTP +standard. This is the same as the DES format, except the bits in each octet +have been rotated one bit right so that the parity bit is now the high +order bit of the octet. Leading zeroes must be specified and odd parity +must be maintained. A zero key in NTP format would be specified as <TT>8080808080808080</TT>.</DD> + +<DD> + </DD> + +<DT> +<TT>A</TT></DT> + +<DD> +The key is a 1-to-8 character ASCII string. A key is formed from this by +using the low order 7 bits of each ASCII character in the string, with +zeroes added on the right when necessary to form a full width 56-bit key, +in the same way that encryption keys are formed from Unix passwords.</DD> + +<DD> + </DD> + +<DT> +<TT>M</TT></DT> + +<DD> +The key is a 1-to-8 character ASCII string, using the MD5 authentication +scheme. Note that both the keys and the authentication schemes (DES or +MD5) must be identical between a set of peers sharing the same key number.</DD> +</DL> +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 ASCII format. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/biblio.htm b/contrib/ntp/html/biblio.htm new file mode 100644 index 0000000..3396481 --- /dev/null +++ b/contrib/ntp/html/biblio.htm @@ -0,0 +1,259 @@ +<html><head><title> +Protocol Conformance Statement +</title></head><body><h3> +Protocol Conformance Statement +</h3> +<BR><IMG align=left SRC="pic/flatheads.gif">From <i>The +Wizard of Oz</i>, L. Frank Baum + +<p>Say it three times and it must be right. +<br clear=left> +<hr> + +<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 up to a few tens of milliseconds +on WANs relative to Coordinated Universal Time (UTC), as provided by a +Global Positioning Service (GPS) receiver, for example. + +<p>Typical NTP configurations utilize multiple redundant servers and +diverse network paths, in order to achieve high accuracy and +reliability. Some configurations include cryptographic authentication to +prevent accidental or malicious protocol attacks. Information on the NTP +architecture, protocol and algorithms can be found in the following +articles and reports, which are available online. General issues of the +concepts and facilities assumed by NTP are discussed in tne <a +href=exec.htm>Executive Summary - Computer Network Time +Synchronization</a> page, while issues related to the NTP timescale and +pending century are discussed in the <A HREF=y2k.htm> Network Time +Protocol Year 2000 Conformance Statement</A> page, both of which are +included in this document. + +<p>Note that network timekeeping technology continues to advance and may +obsolete some of the following documents. For a current list of all +papers, reports, briefings and other documents relevant to the NTP +community, see the <a href=http://www.eecis.udel.edu/~mills>David L. +Mills</a> web page. + +<P>The NTP architecture, protocol and algorithm models are described in + +<UL> + +<li>Mills, D.L. Internet time synchronization: the Network Time +Protocol. <I>IEEE Trans. Communications COM-39, 10</I> (October 1991), +1482-1493. <A +HREF=http://www.eecis.udel.edu/~mills/database/papers/trans.ps> +PostScript</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/papers/trans.pdf> +PDF</a>. Also in: Yang, Z., and T.A. Marsland (Eds.). <I>Global States +and Time in Distributed Systems</I>. IEEE Computer Society Press, Los +Alamitos, CA, 1994, 91-102. +</UL> + +The NTP specification and implementation has evolved over the last two +decades to the current Version 4 of the protocol. This version includes +significant enhancements in accuracy and reliability, as determined by +experience in an estimated total of well over 100,000 clients and +servers in the Internet, while retaining backward compatibility with +previous versions. + +<P>This software distribution contains an implementation of the NTP +Version 4 architecture, protocol and algorithms. While a formal +specification of this version is not yet available, this version is +fully compliant with the previous NTP Version 3 specification and +implementation defined in +<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/~mills/database/rfc/rfc1305/rfc1305a.ps> +PostScript)</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305a.pdf> +PDF</A>, Body: <a +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.ps> +PostScript)</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.pdf> +PDF</A>, Appendices: <A +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.ps> +PostScript</a> | <a +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.pdf> +PDF</A>. + +</UL> + +The NTP Version 4 implementation adds a number of extensions and +refinements to the previous version, including an autonomous +configuration and authentication capability, improved clock discipline +algorithms capable of submicrosecond accuracy and many other +refinements. Specific changes since the Version 3 specification was +issued include: + +<OL> + +<p><LI>Support for precision-time kernel modifications, as described +in</LI> + +<P>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/~mills/database/reports/kern/kerna.ps> +PostScript</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/reports/kern/kerna.pdf> +PDF</a>, Body: <A +HREF=http://www.eecis.udel.edu/~mills/database/reports/kern/kernb.ps> +PostScript</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/reports/kern/kernb.pdf> +PDF</a>. Major revision and update of: Network Working Group Report +RFC-1589, University of Delaware, March 1994. 31 pp. <A +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc1589.txt>ASCII</A> + +<p><LI>Support for IP Multicasting, as described in</LI> + +<P>Mills, D.L, and A. Thyagarajan. Network time protocol version 4 +proposed changes. Electrical Engineering Department Report 94-10-2, +University of Delaware, October 1994, 32 pp. Abstract: <A +HREF=http://www.eecis.udel.edu/~mills/database/reports/acts/actsa.ps> +PostScript</A> | <A +HREF=http://www.eecis.udel.edu/~mills/database/reports/acts/actsa.pdf> +PDF</A>, Body: <a +HREF=http://www.eecis.udel.edu/~mills/database/reports/acts/actsb.ps> +PostScript</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/reports/acts/actsb.pdf> +PDF</a> + +<p><LI>A new hybrid phase/frequency-lock clock discipline, which +replaces the RFC-1305 local clock algorithm, as described in</LI> + + +<P>Mills, D.L. Clock discipline algorithms for the Network Time Protocol +Version 4. Electrical Engineering Report 97-3-3, University of Delaware, +March 1997, 35 pp. Abstract: <A +HREF=http://www.eecis.udel.edu/~mills/database/reports/allan/securea.ps> +PostScript</A> | <a +HREF= +http://www.eecis.udel.edu/~mills/database/reports/allan/securea.pdf> +PDF</a>, Body: <A +HREF=http://www.eecis.udel.edu/~mills/database/reports/allan/secureb.ps> +PostScript</A> | <a +HREF= +http://www.eecis.udel.edu/~mills/database/reports/allan/secureb.pdf> +PDF</a> + +<P>Mills, D.L. Improved algorithms for synchronizing computer network +clocks. <I>IEEE/ACM Trans. Networks 3, 3</I> (June 1995), 245-254. <A +HREF=http://www.eecis.udel.edu/~mills/database/papers/tune2.ps> +PostScript</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/papers/tune2.pdf> +PDF</a> + +<P><LI>Engineered refinements to radio clock drivers and interface code, +as describedin:</LI> + +<P>Mills, D.L. Precision synchronization of computer network clocks. +<I>ACM Computer Communication Review 24, 2</I> (April 1994). 28-43. <A +HREF=http://www.eecis.udel.edu/~mills/database/papers/fine.ps> +PostScript</A> | <A +HREF=http://www.eecis.udel.edu/~mills/database/papers/fine.pdf> +PDF</a> + +<P><LI>Support for over two dozen reference clock drivers for all known +national and international radio, satellite and modem standard time +services known at this time. See the <A HREF=refclock.htm>Reference +Clock Drivers </A>page.</LI> + +<P><LI>A new security model and authentication scheme based on public- +key cryptography called <I>autokey</I>, as described in</LI> + +<P>Mills, D.L., T.S. Glassey, and M.E. McNeil. Coexistence and +interoperability of NTP authentication schemes. Internet Draft +draft-mills-ntp-auth-coexist-00.txt, University of Delaware and Coastek +InfoSys, Inc., November 1997, 8 pp. <A +HREF=http://www.eecis.udel.edu/~mills/memos/draft.txt>ASCII</A> + +<P>Mills, D.L. Authentication scheme for distributed, ubiquitous, real- +time protocols. <I>Proc. Advanced Telecommunications/Information +Distribution Research Program (ATIRP) Conference</I> (College Park MD, +January 1997), 293-298. <A +HREF=http://www.eecis.udel.edu/~mills/database/papers/atirp.ps> +PostScript</A> | <a +HREF=http://www.eecis.udel.edu/~mills/database/papers/atirp.pdf> +PDF</a> + +<P>Mills, D.L. Proposed authentication enhancements for the Network Time +Protocol version 4. Electrical Engineering Report 96-10-3, University of +Delaware, October 1996, 36 pp. Abstract: <A +HREF= +http://www.eecis.udel.edu/~mills/database/reports/secure/securea.ps> +PostScript</A> | <a +HREF= +http://www.eecis.udel.edu/~mills/database/reports/secure/securea.pdf> +PDF</a>, Body: <A +HREF= +http://www.eecis.udel.edu/~mills/database/reports/secure/secureb.ps> +PostScript</A> | <a +HREF= +http://www.eecis.udel.edu/~mills/database/reports/secure/secureb.pdf> +PDF</a> + +<P><LI> Support for the MD5 cryptographic hash algorithm, in addition to +the DES-CBC algorithm described in RFC-1305, as described in the <A +HREF=ntpd.htm><TT>ntpd</TT> - Network Time Protocol (NTP) daemon +</A>page.</LI> + +<P><LI>The prefer-peer scheme, as described in the <A +HREF=prefer.htm>Mitigation Rules and the <TT>prefer</TT> Keyword +</A>page.</LI> + +<P><LI>Specification for the Simple Network Time Protocol (SNTP), as +described in</LI> + +<P>Mills, D.L. Simple network time protocol (SNTP) version 4 for IPv4, +IPv6 and OSI. Network Working Group Report RFC-2030, University of +Delaware, October 1996, 18 pp. <A +HREF=http://www.eecis.udel.edu/~mills/database/rfc/rfc2030.txt> +ASCII</A>. Obsoletes RFC-1769 and RFC-1361. + +<P><LI>Performance surveys for NTP Version 4 can be found in</LI> + +<p><li>Mills, D.L., A. Thyagarajan and B.C. Huffman. Internet +timekeeping around the globe. <i>Proc. Precision Time and Time Interval +(PTTI) Applications and Planning Meeting</i> (Long Beach CA, December +1997), 365-371. Paper: <a +href=http://www.eecis.udel.edu/~mills/database/papers/survey5.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/papers/survey5.pdf> +PDF</a>, Slides: <a +href= +http://www.eecis.udel.edu/~mills/database/brief/survey/survey/index.htm> +HTML</a> | <a +href=http://www.eecis.udel.edu/~mills/database/brief/survey/survey.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/brief/survey.ppt> +PowerPoint</a> | <a +href=http://www.eecis.udel.edu/~mills/database/brief/survey/survey.pdf> +PDF</a></li> + +<p><li>Mills, D.L. The network computer as precision timekeeper. +<i>Proc. Precision Time and Time Interval (PTTI) Applications and +Planning Meeting</i> (Reston VA, December 1996), 96-108. Paper: <a +href=http://www.eecis.udel.edu/~mills/database/papers/ptti.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/papers/ptti.pdf> +PDF</a>, Slides: <a +href= +http://www.eecis.udel.edu/~mills/database/brief/ptti/ptti/index.htm> +HTML</a> | <a +href=http://www.eecis.udel.edu/~mills/database/brief/ptti/ptti.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/brief/ptti/ptti.ppt> +PowerPoint</a> | <a +href=http://www.eecis.udel.edu/~mills/database/brief/ptti/ptti.pdf> +PDF</a></li> + +</OL> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/build.htm b/contrib/ntp/html/build.htm new file mode 100644 index 0000000..c321bf3 --- /dev/null +++ b/contrib/ntp/html/build.htm @@ -0,0 +1,206 @@ +<HTML><HEAD><TITLE> +Building and Installing the Distribution +</TITLE></HEAD><BODY><H3> +Building and Installing the Distribution +</H3> + +<img align=left src=pic/beaver.gif>From <i>pogo</i>, Walt Kelly + +<p>For putting out compiler fires. +<br clear=left><hr> + +<H4>Building and Installing the Distribution</H4> + +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 bew idiosyncratic and the +libraries may have different semantics. It is not possible in a software +distribution such as this one to support every individual sysdtem with a +common set of binaries, even with the same system but different +versions. Therefore, it is necessary to configure each system +individually 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 "make" and the autoconfigure +system does the rest. There are some exceptions, as noted below. + +<p>The autoconfigure system 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 available. +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. + +Some programs included in this distribution use cryptographic algorithms +to verify server authenticity and credentials. As required by the +International Trade in Arms Regulations (ITAR), now called the Defense +Trade Regulations (DTR), certain cryptographic products and media, +including the Data Encryption Standard (DES), cannot be exported without +per-instance license. For this reason, the DES encryption routine has +been removed from the the current version, even though it is used only +to compute a message digest. Current DTR regulations allow export of the +the MD5 message digest routine, which is in fact the preferred +algorithm, and this is included in the current +version. + +<P>The NTP authentication routines conform to the interface used by RSA +Laboratories in the <TT>rsaref20.zip</TT> package, which is downloadable +from <TT>ftp.rsa.com</TT> or via the web at <TT>www.rsa.com</TT>. +Outside the U.S. and Canada, the functionally identical +<TT>rsaeuro.zip</TT> package is available from J.S.A. Kapp and other +sources. The recommended way to integrate the DES routines in either +package with the NTP build procedures is to copy the <TT>desc.c</TT> +file from the <TT>./source</TT> directory in the package to the +<TT>./libntp</TT> directory in the distribution. Then copy the header +files <TT>rsaref.h</TT>, <TT>des.h</TT> and <TT>md2.h</TT> in the +<TT>./source</TT> directory to the <TT>./include</TT> directory. Do not +copy the <TT>global.h</TT> header file; the one in the distribution has +been modified. These steps must be completed before the configuration +process described below. + +<H4>Building and Installing under Unix</H4> + +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 - consider using the GNU tools and <TT>gcc</TT> +compiler in this case). For a successful build, all of these tools +should be accessible via the current path. + +<H4>Configuration</H4> + +Use the <TT>./configure</TT> command to perform an automatic +configuration procedure. This procedure 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 saves lots of messy fiddling. If you need to +delete either the debugging code or one or more or all reference clock +drivers to save space, see the <A HREF="config.htm">Configuration +Options</A> page. + +<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 with +the distribution base directory active, 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 configure with +the <TT>../configure</TT> command. The remaining steps are the same +whether building in the base directory or in the subdirectory. + +<H4>Compilation</H4> + +Peruse the operating-system-specific information for your architecture +under <A HREF="hints.htm">Hints and Kinks</A>. + +<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 the use of <TT>gcc</TT> can +result in quite a few complaints about system header files and type +inconsistencies, especially about pointer variables. This is usually the +case when the system header files are not up to ANSI standards or +<TT>gcc</TT>-isms, when gcc is not installed properly, or when operating +system updates and patches are applied and gcc is not reinstalled. While +the autoconfigure process is quite thorough, the Unix programming +cultures of the various workstation makers still remain idiosyncratic. + +<H4>Installation</H4> + +As root, use the <TT>make install</TT> command to install the binaries +in the destination directory. You must of course have write permission +on the install destination directory. This includes the programs <TT><A +HREF="ntpd.htm">ntpd</A></TT> (the daemon), <TT><A +HREF="ntpdc.htm">ntpdc</A></TT> (an <TT>ntpd</TT>-dependent query +program), <TT><A HREF="ntpq.htm">ntpq</A></TT> (a standard query +program), <TT><A HREF="ntpdate.htm">ntpdate</A></TT> (an <TT>rdate</TT> +replacement for boot time date setting and sloppy time keeping) and +<TT><A HREF="ntptrace.htm">ntptrace</A></TT> (a utility useful to find +the primary (stratum-1) servers). In some systems, the <TT><A +HREF="tickadj.htm">tickadj</A></TT> (a utility useful to adjust kernel +variables) is installed. If the precision time kernel modifications are +present, the <TT><A HREF="ntptime.htm">ntptime</A></TT> (a utility +useful to debug kernel time functions) is installed. + +<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 possibly a +cryptographic key file <TT>ntp.keys</TT>. Directions for doing that are +in the <A HREF="notes.htm">Notes on Configuring NTP and Setting up a NTP +Subnet</A>. The behavior when the daemon starts for the first time can +be counterintuitive. To reduce the level of angst, see the <a +href=quick.htm>Quick Start</a> page. A tutorial on debugging technique +is in <A HREF="debug.htm">NTP Debugging Technique</A>. + +<P>If problems peculiar to the particular hardware and software +environment (e.g. operating system -specific issues) are suspected, +browse the <A HREF="hints.htm">Hints and Kinks</A> page. + +<P>Bug reports of a general nature can be sent to David Mills <A +HREF="mailto: mills@udel.edu"><mills@udel.edu></A>. Bug reports of a +specific nature on features implemented by the programmer corps +mentioned in the <A HREF="copyright.htm">Copyright</A> page should be +sent directly to the implementor listed in that page, with copy to +mills@udel.edu. + +<P><B>Please include the version of the source distribution (e.g., ntp- +4.0.70a) in your bug report.</B> + +<P><B>Please include the <B>output</B> of <TT>config.guess</TT> in your +bug report.</B> + +<P><B>It will look something like: <TT>pdp11-dec-fuzzos3.4</TT></B> + +<P>Additional <TT>make</TT> commands + +<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> + +<H4>Building and Installing under Windows NT</H4> + +Under Windows NT, you will need <TT>Visual C++ 5.0</TT> or above, +<TT>InstallShield</TT> SDK, <TT>Perl5</TT> and some version of the +archiving program <TT>ZIP</TT>. Note that the version of +<TT>InstallShield</TT> that comes with VC++5.0 is not useable here, +since it does not include the command line tools. + +<P>See the <TT>./scripts/wininstall/readme.nt</TT> file for directions +to compile the sources, build the libraries and link the executables. +Initiate the build by running either <TT>bldrel.bat</TT> or +<TT>blddbg.bat</TT> to compile all of the source and create an +<TT>InstallShield</TT> based graphical installation package. + +<P>To install the executables, make sure that you are logged in as a +system account, or one with administrator privileges such as the +"administrator" account. As part of the build an <TT>InstallShield</TT> +based graphical installer was created. Run +<TT>\ntp\scripts\wininstall\intel\disk1\setup.exe</TT> to begin the +installation. This installer will prompt for basic defaults, +copy the binaries, install the service, and start it up. The other +option is to run <TT>\ntp\scripts\wininstall\distrib\install.bat</TT> +which will do the basic installation from the command line. + +<hr><a href=index.htm><img align=left +src=pic/home.gif></a><address><a href="mailto:mills@udel.edu"> David L. +Mills <mills@udel.edu></a> +</address></body></html> diff --git a/contrib/ntp/html/clockopt.htm b/contrib/ntp/html/clockopt.htm new file mode 100644 index 0000000..b128b42 --- /dev/null +++ b/contrib/ntp/html/clockopt.htm @@ -0,0 +1,193 @@ +<HTML><HEAD><TITLE> +Reference Clock Options +</TITLE></HEAD><BODY><H3> +Reference Clock Options +</H3><HR> + +<H4>Reference Clock Support</H4> + +The NTP Version 4 daemon supports many 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.htm">Reference Clock Drivers </A>page. Additional +information can be found in the pages referenced there, including the <A +HREF="rdebug.htm">Debugging Hints for Reference Clock Drivers</A> and <A +HREF="howto.html">How To Write a Reference Clock Driver</A> pages. In +many drivers, support for a PPS signal is available as described in <A +HREF="pps.htm">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.htm">Line Disciplines and Streams Drivers</A> +page. + +<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 U.S. 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 included 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>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. 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>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.htm">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>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 stratum 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. + +<H4>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></DT> +<DD>This command can be used to configure reference clocks in special +ways. The options are interpreted as follows:</DD> + +<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.htm">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></DT> +<DT><TT>maxpoll<I> int</I></TT></DT> +<DD>These options specify the minimum and maximum polling interval for +reference clock messages, in seconds to the power of two. 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> defaults to 10 (17.1 m) and <TT>maxpoll</TT> defaults +to 14 (4.5 h). The allowable range is 4 (16 s) to 17 (36.4 h) +inclusive.</DD> + +</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></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.htm">ntpdc</A></TT> program. The +options are interpreted as follows:</DD> + +<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 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> + +<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.htm">reference clock drivers</A> +page.</DD> + +<DT><TT>stratum <I>int</I></TT></DT> +<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.</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>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>flag1</TT> <TT>flag2</TT> <TT>flag3</TT> <TT>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 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. +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. Further +information on the <TT>filegen</TT> command can be found in the <A +HREF="monopt.htm">Monitoring Options </A>page.</DD> + +</DL> + +<DT><TT>pps <I>device</I> [assert|clear] [hardpps]</TT></DT> +<DD>Specifies the name and options for the serial port device to which +the PPS signal is connected. Note, this command replaces use of +<TT>fudge flag3</TT>, which was used for the same purpose in NTPv3. Note +that this command should preceed the <TT>server</TT> and <TT>fudge</TT> +command for the same device. Note also that the <TT>assert</TT>, +<TT>clear</TT> and <TT>hardpps</TT> options are only available if the +<tt>ppsapi</tt> standard PPS interface is available.</DD> + +<DL> + +<DT><TT>device</TT></DT> +<DD>Specify the device name associated with the PPS signal. The name +must match exactly the link name specified in the driver documentation +page.</DD> + +<DT><TT>assert</TT></DT> +<DT><TT>clear</TT></DT> +<DD>Using <TT>assert</TT> or <TT>clear</TT> specifies if the high going +or low going edge of the signal must be used. The default is +<TT>assert</TT>.</DD> + +<DT><TT>hardpps</TT></DT> +<DD>This flag is used to tell the kernel that the signal from this +device must be used to drive hardpps().</DD> + +<DD>The <TT>assert</TT>, <TT>clear</TT> and <TT>hardpps</TT> options +are only available if the PPSAPI is used.</DD> + +</DL> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/config.htm b/contrib/ntp/html/config.htm new file mode 100644 index 0000000..f8606f2 --- /dev/null +++ b/contrib/ntp/html/config.htm @@ -0,0 +1,291 @@ +<HTML><HEAD><TITLE> +Configuration Options +</TITLE></HEAD><BODY><H3> +Configuration Options +</H3> + +<IMG align=left SRC="pic/pogo3a.gif">From <i>pogo</i>, Walt Kelly +<BR clear=left><HR> + +<H4>Basic Configuration Options - the <TT>configure</TT> utility</H4> + +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>Configuration options are specified as arguments to the +<TT>configure</TT> script. Following is a summary of the current +options: + +<P>Usage: <TT>configure [options] [host]</TT> +<BR>Options: <TT>[defaults in brackets after descriptions]</TT> +<PRE>Configuration + + --cache-file=FILE cache test +results in FILE + -- +help &n +bsp; 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 +Directory and file names + + --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 ..] + --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 +Host type + + -- +build=BUILD +configure for building on BUILD [BUILD=HOST] + -- +host=HOST &nb +sp; configure for HOST [guessed] + --target=TARGET +configure for TARGET [TARGET=HOST]</PRE> + +<PRE>Features and packages + + --disable-FEATURE do not include +FEATURE (same as --enable- + + +FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] + --without-PACKAGE do not use +PACKAGE (same as --with-PACKAGE=no) + --x-includes=DIR X include +files are in DIR + --x-libraries=DIR X library files +are in DIR + +--enable- and --disable- with options recognized + + +debugging +Include debugging code [enable] + gdt- +surveying Include GDT survey code +[disable] + +md5 &nb +sp; Include support for MD5 keys [enable] + +des &nb +sp; Include support for DES keys [enable] + all- +clocks Include +drivers for all reference clocks + + +[enable] + + Radio Clocks (these are ordinarily enabled, if supported by the + + +machine and operating system) + + +ACTS &n +bsp; NIST dialup clock + +ARBITER   +; Arbiter 1088A/B GPS receiver + +AS2201 + Austron 2200A or 2201A GPS receiver + +ATOM &n +bsp; ATOM clock + +BANCOMM   +; BANCOMM clock + +CHU &nb +sp; CHU clock + +DATUM & +nbsp; Datum Programmable Time System + +DCF7000   +; ELV/DCF7000 + +GPSVME + GPS-VME Clock + +HEATH & +nbsp; HeathKit GC-1000 Most Accurate Clock + +HOPF6021 &nbs +p; HOPF6021 Radio Clock support + +HPGPS & +nbsp; HP 58503A GPS Time & Frequency receiver + +IRIG &n +bsp; IRIG (Audio) Clock + +LEITCH + Leitch CSD 5300 Master Clock System Driver + LOCAL- +CLOCK Local Clock driver + +MEINBERG &nbs +p; Meinberg clocks + +MSFEES + MSFEES clock + +MOTO &n +bsp; Motorola GPS clock + +MX4200 + MX4200 clock + +NMEA &n +bsp; NMEA GPS clock + +PARSE & +nbsp; PARSE clock code + +PST &nb +sp; PST/Traconex 1020 WWV/H receiver + +PTBACTS   +; PTB dialup clock support + +RAWDCF + use raw DCF77 time code + +RCC8000   +; RCC8000 Radio Clock support + +SCHMID + SCHMID DCF77 clock support + +TRAK &n +bsp; TRAK 8810 GPS station clock + +TPRO &n +bsp; KSI/Odetics TPRO/S IRIG Interface + +TRIMTAIP &nbs +p; Trimble GPS/TAIP Protocol + +TRIMTSIP &nbs +p; Trimble GPS/TSIP Protocol + +TRUETIME &nbs +p; Kinemetrics/TrueTime (generic) receiver + +WWVB &n +bsp; Spectracom 8170 or Netclock/2 WWVB receiver + +USNO &n +bsp; US Naval Observatory dialup clock + Miscellany + + accurate-adjtime The +adjtime() call is accurate + +kmem &n +bsp; Read kmem + +tick=VALUE Force a +value for 'tick' + +tickadj=VALUE Force a value for +'tickadj' + udp- +wildcard Use UDP wildcard +delivery + slew- +always Always slew the +time + step- +slew Step +and slew the time + ntpdate- +step If ntpdate should step +the time + hourly-todr-sync If we should +sync TODR hourly</PRE> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/confopt.htm b/contrib/ntp/html/confopt.htm new file mode 100644 index 0000000..68ddf7f --- /dev/null +++ b/contrib/ntp/html/confopt.htm @@ -0,0 +1,330 @@ +<html><head><title> +Configuration Options +</title></head><body><h3> +Configuration Options +</h3><hr> + +<h4>Configuration Support</h4> + +<p>Following is a description of the configuration commands in +NTPv4. These commands have the same basic functions as in NTPv3 +and in some cases new functions and new operands. The various +modes are determined by the command keyword and the type of the +required IP address. Addresses are classed by type as (s) a +remote server or peer (IP class A, B and C), (b) the broadcast +address of a local interface, (m) a multicast address (IP class +D), or (r) a reference clock address (127.127.x.x). Note that, +while autokey and burst modes are supported by these commands, +their effect in some weird mode combinations can be meaningless +or even destructive.</p> + +<dl> + <dt><tt>peer </tt><i><tt>address</tt></i><tt> [autokey | key </tt><i><tt>key</tt></i><tt>] + [burst] [version </tt><i><tt>version</tt></i><tt>] + [prefer] [minpoll </tt><i><tt>minpoll</tt></i><tt>]</tt><i><tt> + </tt></i><tt>[maxpoll </tt><i><tt>maxpoll</tt></i><tt>]</tt></dt> + <dd> </dd> + <dt><tt>server </tt><i><tt>address</tt></i><tt> [autokey | + key </tt><i><tt>key</tt></i><tt>] [burst] [version </tt><i><tt>version</tt></i><tt>] + [prefer] [minpoll </tt><i><tt>minpoll</tt></i><tt>]</tt><i><tt> + </tt></i><tt>[maxpoll </tt><i><tt>maxpoll</tt></i><tt>]</tt></dt> + <dd> </dd> + <dt><tt>broadcast </tt><i><tt>address</tt></i><tt> [autokey | + key </tt><i><tt>key</tt></i><tt>] [burst] [version </tt><i><tt>version</tt></i><tt>] + [minpoll </tt><i><tt>minpoll</tt></i><tt>]</tt><i><tt> </tt></i><tt>[maxpoll + </tt><i><tt>maxpoll</tt></i><tt>] [ttl </tt><i><tt>ttl</tt></i><tt>]</tt></dt> + <dd> </dd> + <dt><tt>manycastclient </tt><i><tt>address</tt></i><tt> + [autokey | key </tt><i><tt>key</tt></i><tt>] [burst] + [version </tt><i><tt>version</tt></i><tt>] [minpoll </tt><i><tt>minpoll + </tt></i><tt>[maxpoll </tt><i><tt>maxpoll</tt></i><tt>] + [ttl </tt><i><tt>ttl</tt></i><tt>]</tt></dt> + <dd> </dd> + <dd>These four commands specify the time server name or + address to be used and the mode in which to operate. The <i><tt>address</tt></i><tt> + </tt>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.htm">Association Management</a> page.</dd> + <dd> </dd> + <dd><dl> + <dt><tt>server</tt></dt> + <dd>For type s and r addresses, this operates as the + NTPv3 server command, which mobilizes a + persistent client mode association. The <tt>server</tt> + command specifies that the local server is to + operate in client mode with the specified remote + server. In this mode, the local server can be + synchronized to the remote server, but the remote + server can never be synchronized to the local + server.</dd> + <dd> </dd> + <dt><tt>peer</tt></dt> + <dd>For type s addresses (only), this operates as the + current <tt>peer </tt>command, which mobilizes a + persistent symmetric-active mode association, + except that additional modes are available. This + command should NOT be used for type b, m or r + addresses.</dd> + <dd> </dd> + <dd>The <tt>peer</tt> command specifies that the + local server is to operate in symmetric active + mode with the remote server. In this mode, the + local server can be synchronized to the remote + server and, in addition, the remote server can be + synchronized by the local server. This is useful + in a network of servers where, depending on + various failure scenarios, either the local or + remote server may be the better source of time.</dd> + <dd> </dd> + <dt><tt>broadcast</tt></dt> + <dd>For type b and m addresses (only), this is + operates as the current NTPv3 <tt>broadcast </tt>command, + which mobilizes a persistent broadcast mode + association, except that additional modes are + available. 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. In + the current implementation, the source address + used for these messages is the Unix host default + address.</dd> + <dd> </dd> + <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 224.0.1.1 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.</dd> + <dd> </dd> + <dt><tt>manycastclient</tt> </dt> + <dd>For type m addresses (only), this mobilizes a + manycast client-mode association for the + multicast address specified. In this case 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> + <dd> </dd> + <dd>The <tt>manycast </tt>command specifies that the + local server is to operate in client mode with + the remote server 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.</dd> + <dd> </dd> + </dl> + </dd> + <dd>Options</dd> + <dd> </dd> + <dd><dl> + <dt><tt>autokey</tt></dt> + <dd>All packets sent to the address are to include + authentication fields encrypted using the autokey + scheme.</dd> + <dd> </dd> + <dt><tt>burst</tt></dt> + <dd>At each poll interval, send a burst of eight + packets spaced, instead of the usual one.</dd> + <dd> </dd> + <dt><tt>key </tt><i><tt>key</tt></i></dt> + <dd>All packets sent to the address are to include + authentication fields encrypted using the + specified <i>key</i> identifier, which is an + unsigned 32-bit integer less than 65536. The + default is to include no encryption field.</dd> + <dd> </dd> + <dt><tt>version </tt><i><tt>version</tt></i></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> + <dd> </dd> + <dt><tt>prefer</tt></dt> + <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.htm">Mitigation + Rules and the <tt>prefer</tt> Keyword </a>page + for further information.</dd> + <dd> </dd> + <dt><tt>ttl </tt><i><tt>ttl</tt></i></dt> + <dd>This option is used only with broadcast mode. It + specifies the time-to-live <i><tt>ttl</tt></i> to + use on multicast packets. Selection of the proper + value, which defaults to 127, is something of a + black art and must be coordinated with the + network administrator.</dd> + <dd> </dd> + <dt><tt>minpoll </tt><i><tt>minpoll</tt></i></dt> + <dt><tt>maxpoll </tt><i><tt>maxpoll</tt></i></dt> + <dd>These options specify the minimum and maximum + polling intervals for NTP messages, in seconds to + the power of two. The default range is 6 (64 s) + to 10 (1,024 s).The allowable range is 4 (16 s) + to 17 (36.4 h) inclusive.</dd> + <dd> </dd> + </dl> + </dd> + <dt><tt>broadcastclient</tt></dt> + <dd>This command directs the local server to listen for and + respond to broadcast messages received on any local + interface. Upon hearing a broadcast message for the first + time, the local server measures the nominal network delay + using a brief client/server exchange with the remote + server, then enters the broadcastclient mode, in which it + listens for and synchronizes to succeeding broadcast + messages. Note that, in order to avoid accidental or + malicious disruption in this mode, both the local and + remote servers should operate using authentication and + the same trusted key and key identifier.</dd> + <dd> </dd> + <dt><tt>multicastclient [</tt><i><tt>address</tt></i><tt>] + [...]</tt></dt> + <dd>This command directs the local server to listen for + multicast messages at the group address(es) of the global + network. The default address is that assigned by the + Numbers Czar to NTP (224.0.1.1). This command operates in + the same way as the <tt>broadcastclient</tt> command, but + uses IP multicasting. Support for this command requires a + multicast kernel.</dd> + <dd> </dd> + <dt><tt>driftfile </tt><i><tt>driftfile</tt></i></dt> + <dd>This command specifies the name of the file used to + record the frequency offset of the local clock + oscillator. If the file exists, it is read at startup in + order to set the initial frequency offset and then + updated once per hour with the current frequency offset + computed by the daemon. If the file does not exist or + this command is not given, the initial frequency offset + is assumed zero. In this case, it may take some hours for + the frequency to stabilize and the residual timing errors + to subside.</dd> + <dd> </dd> + <dd>The file format consists of a single line containing a + single floating point number, which records the frequency + offset measured in parts-per-million (PPM). The file is + updated by first writing the current drift value into a + temporary file and then renaming this file to replace the + old version. This implies that <tt>ntpd</tt> must have + write permission for the directory the drift file is + located in, and that file system links, symbolic or + otherwise, should be avoided.</dd> + <dd> </dd> + <dt><tt>manycastserver </tt><i><tt>address </tt></i><tt>[...]</tt></dt> + <dd>This command directs the local server to listen for and + respond to broadcast messages received on any local + interface, and in addition enables the server to respond + to client mode messages to the multicast group + address(es) (type m) specified. At least one address is + required, but 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.</dd> + <dd> </dd> + <dt><tt>revoke [</tt><i><tt>logsec</tt></i><tt>]</tt> </dt> + <dd>Specifies the interval between recomputations of the + private value used with the autokey feature, which + ordinarily requires an expensive public- key computation. + The default value is 12 (65,536 s or about 18 hours). For + poll intervals above the specified interval, a new + private value will be recomputed for every message sent.</dd> + <dd> </dd> + <dt><tt>autokey [</tt><i><tt>logsec</tt></i><tt>]</tt> </dt> + <dd>Specifies the interval between regenerations of the + session key list used with the autokey feature. 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.</dd> + <dd> </dd> + <dt><tt>enable [auth | bclient | kernel | monitor | ntp | + stats]</tt></dt> + <dt><tt>disable [auth | bclient | kernel | monitor | ntp | + stats</tt><font face="Courier New">] </font></dt> + <dd>Provides a way to enable or disable various server + options. Flags not mentioned are unaffected. Note that + all of these flags can be controlled remotely using the <a + href="ntpdc.htm"><tt>ntpdc</tt></a> utility program.</dd> + <dd> </dd> + <dd><dl> + <dt><tt>auth</tt></dt> + <dd>Enables the server to synchronize with + unconfigured peers only if the peer has been + correctly authenticated using a trusted key and + key identifier. The default for this flag is + enable.</dd> + <dd> </dd> + <dt><tt>bclient</tt></dt> + <dd>When enabled, this is identical to the <tt>broadcastclient</tt> + command. The default for this flag is disable.</dd> + <dd> </dd> + <dt><tt>kernel</tt></dt> + <dd>Enables the precision-time kernel support for the + <tt>ntp_adjtime()</tt> system call, if + implemented. Ordinarily, support for this routine + is detected automatically when the NTP daemon is + compiled, so it is not necessary for the user to + worry about this flag. It flag is provided + primarily so that this support can be disabled + during kernel development.</dd> + <dd> </dd> + <dt><tt>monitor</tt></dt> + <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.</dd> + <dd> </dd> + <dt><tt>ntp</tt></dt> + <dd>Enables the server to adjust its local clock by + means of NTP. If disabled, the local clock + free-runs at its intrinsic time and frequency + offset. This flag is useful in case the local + clock is controlled by some other device or + protocol and NTP is used only to provide + synchronization to other clients. In this case, + the local clock driver can be used to provide + this function and also certain time variables for + error estimates and leap-indicators. See the <a + href="refclock.htm">Reference Clock Drivers </a>page + for further information. The default for this + flag is enable.</dd> + <dd> </dd> + <dt><tt>stats</tt></dt> + <dd>Enables the statistics facility. See the <a + href="monopt.htm">Monitoring Options </a>page for + further information. The default for this flag is + enable.</dd> + <dd> </dd> + </dl> + </dd> +</dl> + +<hr> + +<address> + David L. Mills (mills@udel.edu) +</address> +</body> +</html> diff --git a/contrib/ntp/html/copyright.htm b/contrib/ntp/html/copyright.htm new file mode 100644 index 0000000..d5d8243 --- /dev/null +++ b/contrib/ntp/html/copyright.htm @@ -0,0 +1,123 @@ +<HTML><HEAD><TITLE> +Copyright Notice +</TITLE></HEAD><BODY><H3> +Copyright Notice +</H3> + +<IMG align=left HEIGHT=264 WIDTH=206 SRC=pic/sheepb.jpg >"Clone +me," says Dolly sheepishly +<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> + +<PRE>/*********************************************************************** + * * + * Copyright (c) David L. Mills 1992-1999 * + * * + * Permission to use, copy, modify, and distribute this software and * + * its documentation for any purpose and without fee is hereby * + * granted, provided that the above copyright notice appears in all * + * copies and that both the copyright notice and this permission * + * notice appear in supporting documentation, and that the name * + * University of Delaware not be used in advertising or publicity * + * pertaining to distribution of the software without specific, * + * written prior permission. The University of Delaware makes no * + * representations about the suitability this software for any * + * purpose. It is provided "as is" without express or implied * + * warranty. * + **********************************************************************/</PRE> + +The following individuals contributed in part to the Network Time Protocol Distribution Version 4 and are acknowledged as authors of this work. + +<OL> + +<LI><A HREF="mailto: marka@syd.dms.csiro.au">Mark Andrews <marka@syd.dms.csiro.au></a> Leitch atomic clock controller</LI> + +<LI><A HREF="mailto: vbais@mailman1.intel.co">Viraj Bais <vbais@mailman1.intel.com></a> and <A HREF="mailto: kirkwood@striderfm.intel.com">Clayton Kirkwood <kirkwood@striderfm.intel.com></a> port to WindowsNT 3.5</LI> + +<LI><A HREF="mailto: karl@owl.HQ.ileaf.com">Karl Berry <karl@owl.HQ.ileaf.com></a> syslog to file option</LI> + +<LI><A HREF="mailto: Piete.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: clift@ml.csiro.au">Steve Clift <clift@ml.csiro.au></a> OMEGA clock driver</LI> + +<LI><A HREF="mailto:casey@csc.co.za">Casey Crellin <casey@csc.co.za></a> vxWorks (Tornado) port and help with target configuration</LI> + +<LI><A HREF="mailto: duwe@immd4.informatik.uni-erlangen.de">Torsten Duwe <duwe@immd4.informatik.uni-erlangen.de></a> Linux port</LI> + +<LI><A HREF="mailto: dundas@salt.jpl.nasa.gov">John A. Dundas III <dundas@salt.jpl.nasa.gov></a> Apple A/UX port</LI> + +<LI><A HREF="mailto: dennis@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: glenn@herald.usask.ca">Glenn Hollinger <glenn@herald.usask.ca></a> GOES clock driver</LI> + +<LI><A HREF="mailto: iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port</LI> + +<LI><A HREF="mailto: jagubox.gsfc.nasa.gov">Jim Jagielski <jim@jagubox.gsfc.nasa.gov></a> A/UX port</LI> + +<LI><A HREF="mailto: jbj@chatham.usdesign.com">Jeff Johnson <jbj@chatham.usdesign.com></a> massive prototyping overhaul</LI> + +<LI><A HREF="mailto: jones@hermes.chpc.utexas.edu">William L. Jones <jones@hermes.chpc.utexas.edu></a> RS/6000 AIX modifications, HPUX modifications</LI> + +<LI><A HREF="mailto: dkatz@cisco.com">Dave Katz <dkatz@cisco.com></a> RS/6000 AIX port</LI> + +<LI><A HREF="mailto: leres@ee.lbl.gov">Craig Leres <leres@ee.lbl.gov></a> 4.4BSD port, ppsclock, Maganavox GPS clock driver</LI> + +<LI><A HREF="mailto: lindholm@ucs.ubc.ca">George Lindholm <lindholm@ucs.ubc.ca></a> SunOS 5.1 port</LI> + +<LI> +<A HREF="mailto: louie@ni.umd.edu">Louis A. Mamakos <louie@ni.umd.edu></a> +MD5-based authentication</LI> + +<LI><A HREF="mailto: derek@toybox.demon.co.uk">Derek Mulcahy <derek@toybox.demon.co.uk></a> and <A HREF="mailto: d@hd.org">Damon Hart-Davis <d@hd.org></a> ARCRON MSF clock driver</LI> + +<LI><A HREF="mailto: thorinn@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: mills@udel.edu">David L. Mills <mills@udel.edu></a> Version 4 foundation, Spectractom WWVB, Austron GPS, Arbiter GPS, CHU, Heath, ATOM, ACTS, KSI/Odetics, IRIG clock drivers; PPS support; precision kernel; NTPv4 changes</LI> + +<LI><A HREF="mailto: moeller@gwdgv1.dnet.gwdg.de">Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de></a> VMS port</LI> + +<LI><A HREF="mailto: mogul@pa.dec.com">Jeffrey Mogul <mogul@pa.dec.com></a> ntptrace utility</LI> + +<LI><A HREF="mailto: tmoore@fievel.daytonoh.ncr.com">Tom Moore <tmoore@fievel.daytonoh.ncr.com></a> i386 svr4 port</LI> + +<LI><A HREF="mailto: Rainer.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: dirce@zk3.dec.com">Dirce Richards <dirce@zk3.dec.com></a> Digital UNIX V4.0 port</LI> + +<LI><A HREF="mailto: mrapple@quack.kfu.com">Nick Sayer <mrapple@quack.kfu.com></a> SunOS streams modules</LI> + +<LI><A HREF="http://www4.informatik.uni-erlangen.de/~kardel">Frank Kardel</A> <A HREF="mailto: +Frank.Kardel@informatik.uni-erlangen.de"> +<Frank.Kardel@informatik.uni-erlangen.de></a> +PARSE <GENERIC> driver (14 reference clocks), STREAMS modules for PARSE, support scripts, syslog cleanup</LI> + +<LI><A HREF="mailto: schnitz@unipress.com">Ray Schnitzler <schnitz@unipress.com></a> Unixware1 port</LI> + +<LI><A HREF="mailto: shields@tembel.org">Michael Shields <shields@tembel.org></a> USNO clock driver</LI> + +<LI><A HREF="mailto: pebbles.jpl.nasa.gov">Jeff Steinman <jss@pebbles.jpl.nasa.gov></a> Datum PTS clock driver</LI> + +<LI><A HREF="mailto: harlan@pfcs.com">Harlan Stenn <harlan@pfcs.com></a> GNU automake/autoconfigure makeover</LI> + +<LI><A HREF="mailto: ken@sdd.hp.com">Kenneth Stone <ken@sdd.hp.com></a> HP-UX port</LI> + +<LI><A HREF="mailto: ajit@ee.udel.edu">Ajit Thyagarajan <ajit@ee.udel.edu></a>IP multicast support</LI> + +<LI><A HREF="mailto: tsuruoka@nc.fukuoka-u.ac.jp">Tomoaki TSURUOKA <tsuruoka@nc.fukuoka-u.ac.jp></a>TRAK clock driver</LI> + +<LI><A HREF="mailto: vixie@vix.com">Paul A Vixie <vixie@vix.com></a> TrueTime GPS driver, generic TrueTime clock driver</LI> + +<LI><A HREF="mailto: Ulrich.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> + +<LI><A HREF="mailto: greg.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: Sven_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: wsanchez@apple.com">Wilfredo Sánchez <wsanchez@apple.com></A> added support for NetInfo</LI> +</OL> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/debug.htm b/contrib/ntp/html/debug.htm new file mode 100644 index 0000000..bf16049 --- /dev/null +++ b/contrib/ntp/html/debug.htm @@ -0,0 +1,288 @@ +<HTML><HEAD><TITLE> +NTP Debugging Techniques +</TITLE></HEAD><BODY><H3> +NTP Debugging Techniques +</H3> + +<IMG align=left SRC="pic/pogo.gif"><I>Pogo Possum</I>, with toolkit +and bug, Walt Kelly +<br clear=left><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 +<TT><A HREF="ntpd.htm">ntpd</A></TT> page are required. Once started, +the daemon will begin sending messages, as specified in the +configuration file, and interpreting received messages. + +<P>The best way to verify correct operation is using the <TT><A +HREF="ntpq.htm">ntpq</A></TT> and <TT><A HREF="ntpdc.htm">ntpdc</A></TT> +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 Appendix A of the NTP specification <A +HREF="http://www.eecis.udel.edu/~mills/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 of interest. In addition, +the <TT>ntpdc</TT> program can be used to selectively enable and disable +some functions of the daemon while the daemon is running. + +<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>Some problems are immediately apparent when the daemon first starts +running. The most common of these are the lack of a ntp (UDP port 123) +in the host <TT>/etc/services</TT> file. Note that NTP does not use TCP +in any form. Other problems are apparent in the system log file. The log +file should show the startup banner, some cryptic initialization data, +and the computed precision value. The next most common problem is +incorrect DNS names. Check that each DNS name used in the configuration +file responds to the Unix <TT>ping</TT> command. + +<P>When first started, the daemon normally polls the servers listed in +the configuration file at 64-second intervals. In order to allow a +sufficient number of samples for the NTP algorithms to reliably +discriminate between correctly operating servers and possible intruders, +at least four valid messages from at least one server is required before +the daemon can set the local clock. However, if the current local time +is greater than 1000 seconds in error from the server time, the daemon +will not set the local clock; instead, it will plant a message in the +system log and shut down. It is necessary to set the local clock to +within 1000 seconds first, either by a time-of-year hardware clock, by +first using the <A HREF="ntpdate.htm"><TT>ntpdate</TT> </A>program or +manually be eyeball and wristwatch. + +<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: + +<PRE>ntpq>pe +remote refid st t when poll reach delay offset disp +=================================================================== ++128.4.2.6 132.249.16.1 2 u 131 256 373 9.89 16.28 23.25 +*128.4.1.20 .WWVB. 1 u 137 256 377 280.62 21.74 20.23 +-128.8.2.88 128.8.10.1 2 u 49 128 376 294.14 5.94 17.47 ++128.4.2.17 .WWVB. 1 u 173 256 377 279.95 20.56 16.40 +</PRE> + +The host addresses shown in the <TT>remote</TT> column should agree with +the DNS entries in the configuration file, plus any peers not mentioned +in the file at the same or lower than your stratum that happen to be +configured to peer with you. Be prepared for surprises in cases where +the peer has multiple addresses or multiple names. The <TT>refid</TT> +entry shows the current source of synchronization for each peer, while +the <TT>st</TT> 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 polling interval in seconds. The +<TT>when</TT> entry shows the time since the peer was last heard, +normally in seconds, while the <TT>reach</TT> entry shows the status of +the reachability register (see RFC-1305) in octal. The remaining entries +show the latest delay, offset and dispersion computed for the peer in +milliseconds. Note that in NTP Version 4 the dispersion entry includes +only the RMS error component; earlier versions included all components. + +<P>The tattletale character 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, but not currently selected, are marked <TT>+</TT>. +Peers marked <TT>*</TT> and <TT>+</TT> are included in a weighted +average computation to set the local clock; the data produced by peers +marked with other symbols are discarded. See the <TT>ntpq</TT> +documentation for the meaning of these symbols. + +<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 + +<PRE>ntpq>as +ind assID status conf reach auth condition last_event cnt +========================================================= + 1 11670 7414 no yes ok candidate reachable 1 + 2 11673 7614 no yes ok sys.peer reachable 1 + 3 11833 7314 no yes ok outlyer reachable 1 + 4 11868 7414 no yes ok candidate reachable 1 + </PRE> + +Each line in this billboard is associated with the corresponding line +the <TT>pe</TT> billboard above. Next, use the <TT>rv</TT> command and +the respective identifier to display a detailed synopsis of the selected +peer, such as + +<PRE>ntpq>rv 11670 +status=7414 reach, auth, sel_sync, 1 event, event_reach +srcadr=128.4.2.6, srcport=123, dstadr=128.4.2.7, dstport=123, keyid=1, +stratum=2, precision=-10, rootdelay=362.00, rootdispersion=21.99, +refid=132.249.16.1, +reftime=af00bb44.849b0000 Fri, Jan 15 1993 4:25:40.517, +delay= 9.89, offset= 16.28, +dispersion=23.25, reach=373, valid=8, +hmode=2, pmode=1, hpoll=8, ppoll=10, leap=00, flash=0x0, +org=af00bb48.31a90000 Fri, Jan 15 1993 4:25:44.193, +rec=af00bb48.305e3000 Fri, Jan 15 1993 4:25:44.188, +xmt=af00bb1e.16689000 Fri, Jan 15 1993 4:25:02.087, +filtdelay= 16.40 9.89 140.08 9.63 9.72 9.22 10.79 122.99, +filtoffset= 13.24 16.28 -49.19 16.04 16.83 16.49 16.95 -39.43, +filterror= 16.27 20.17 27.98 31.89 35.80 39.70 43.61 47.52 +</PRE> + +A detailed explanation of the fields in this billboard are beyond the +scope of this discussion; however, most variables defined in the +specification RFC-1305 can be found. The most useful portion for +debugging is the last three lines, which give 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 zeros, or if the clock offset changes +dramatically in the same direction for each round, cause for alarm +exists. + +<P>Finally, the state of the local clock can be determined using the +<TT>rv</TT> command (without the argument), such as + +<PRE>ntpq>rv +status=0664 leap_none, sync_ntp, 6 events, event_peer/strat_chg +system="UNIX", leap=00, stratum=2, rootdelay=280.62, +rootdispersion=45.26, peer=11673, refid=128.4.1.20, +reftime=af00bb42.56111000 Fri, Jan 15 1993 4:25:38.336, +poll=8, clock=af00bbcd.8a5de000 Fri, Jan 15 1993 4:27:57.540, +phase=21.147, freq=13319.46, compliance=2 +</PRE> + +The most useful data in this billboard show when the clock was last +adjusted <TT>reftime</TT>, together with its status and most recent +exception event. An explanation of these data is in the specification +RFC-1305. + +<P>When nothing seems to happen in the <TT>pe</TT> billboard after some +minutes, there may be a network problem. The most common network problem +is an access controlled router on the path to the selected peer. No +known public NTP time server selectively restricts access at this time, +although this may change in future; however, many private networks do. +It also may be the case that the server is down or running in +unsynchronized mode due to a local problem. Use the <TT>ntpq</TT> +program to spy on its own variables in the same way you can spy on your +own. + +<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>It has sometimes been the experience that the local clock oscillator +frequency error is too large for the NTP discipline algorithm, which can +correct frequency errors as large as 43 seconds per day. There are two +possibilities that may result in this problem. First, the hardware time- +of-year clock chip must be disabled when using NTP, since this can +destabilize the discipline process. This is usually done using the +<TT><A HREF="tickadj.htm">tickadj</A></TT> program and the <TT>-s</TT> +command line argument, but other means may be necessary. For instance, +in the Sun Solaris kernel, this can be done using a command in the +system startup file. + +<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 as long as the apparent +clock error exceeds 128 milliseconds, which for most Internet paths is a +quite 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 an interval of about 20 minutes, the +local clock is stepped to the new value (as an option, the daemon can be +compiled to slew at an accelerated rate to the new value, rather than be +stepped). 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. + +<H4>Debugging Checklist</H4> + +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: + +<OL> + +<P><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> + +<P><LI>Check the system log for <TT>ntpd</TT> messages about +configuration +errors, name-lookup failures or initialization problems.</LI> + +<P><LI>Using the <TT>ntpdc</TT> program and <TT>iostats</TT> command, +verify that the received packets and packets sent counters are +incrementing. If the packets send counter does not increment and the +configuration file includes designated servers, something may be wrong +in the network configuration of the ntpd host. If this counter does +increment and packets are actually being sent to the network, but the +received packets counter does not increment, something may be wrong in +the network or the server may not be responding.</LI> + +<P><LI>If both the packets sent counter and received packets counter do +increment, but the <TT>rec</TT> timestamp in the <TT>pe</TT> billboard +shows far from the current date, received packets are probably being +discarded for some reason. There is a handy, undocumented state variable +<TT>flash</TT> visible in the <TT>pe</TT>billboard. The value is in hex +and normally has the value zero (OK). However, if something is wrong, +the bits of this variable, reading from the right, correspond to the +sanity checks listed in Section 3.4.3 of the NTP specification <A +HREF="http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.ps" +>RFC-1305</A>. A bit other than zero indicates the associated sanity +check failed.</LI> + +<P><LI>If the <TT>org, rec</TT> and <TT>xmt</TT> timestamps in the +<TT>pe</TT> billboard appear current, but the local clock is not set, as +indicated by a stratum number less than 16 in the <TT>rv</TT> command +without arguments, verify that valid clock offset, roundtrip delay and +dispersion are displayed for at least one peer. The clock offset should +be less than 1000 seconds, the roundtrip delay less than one second and +the dispersion less than one second.</LI> + + +<P><LI>While the algorithm can tolerate a relatively large frequency +error (up to 500 parts per million or 43 seconds per day), various +configuration errors (and in some cases kernel bugs) can exceed this +tolerance, leading to erratic behavior. This can result in frequent loss +of synchronization, together with wildly swinging offsets. Use the +<TT>ntpdc</TT> program (or temporary configuration file) and <TT>disable +pll</TT> command to prevent the <TT>ntpd</TT> daemon from setting the +clock. Using the <TT>ntpq</TT> or <TT>ntpdc</TT> programs, watch the +apparent offset as it varies over time to determine the intrinsic +frequency error. If the error increases by more than 22 milliseconds per +64-second poll interval, the intrinsic frequency must be reduced by some +means. The easiest way to do this is with the <TT><A +HREF="tickadj.htm">tickadj</A></TT> program and the <TT>-t</TT> +command line argument.</LI> + +</OL> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/driver1.htm b/contrib/ntp/html/driver1.htm new file mode 100644 index 0000000..1f88e7d --- /dev/null +++ b/contrib/ntp/html/driver1.htm @@ -0,0 +1,157 @@ +<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>Undisciplined Local Clock +</TITLE> +</HEAD> +<BODY> + +<H3> +Undisciplined Local Clock</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.1.<I>u</I> +<BR>Reference ID: <TT>LCL</TT> +<BR>Driver ID: <TT>LOCAL</TT> +<H4> +Description</H4> +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>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>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>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>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.htm">Mitigation +Rules and the <TT>prefer</TT> Keyword </A>page for a detailed description +of the exact behavior. + +<P>The stratum for this driver is set at 3 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>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. +<H4> +Monitor Data</H4> +No <TT>filegen clockstats</TT> monitor data are produced by this driver. +<H4> +Fudge Factors</H4> + +<DL> +<DT> +<TT>time1 <I>time</I></TT></DT> + +<DD> +Specifies the time offset calibration factor, in seconds and fraction, +with default 0.0.</DD> + +<DT> +<TT>time2 <I>time</I></TT></DT> + +<DD> +Specifies the frequency offset calibration factor, in parts per million, +with default 0.0.</DD> + +<DT> +<TT>stratum <I>number</I></TT></DT> + +<DD> +Specifies the driver stratum, in decimal from 0 to 15, with default 3.</DD> + +<DT> +<TT>refid <I>string</I></TT></DT> + +<DD> +Specifies the driver reference identifier, an ASCII string from one to +four characters, with default <TT>LCL</TT>.</DD> + +<DT> +<TT>flag1 0 | 1</TT></DT> + +<DD> +Not used by this driver.</DD> + +<DT> +<TT>flag2 0 | 1</TT></DT> + +<DD> +Not used by this driver.</DD> + +<DT> +<TT>flag3 0 | 1</TT></DT> + +<DD> +Not used by this driver.</DD> + +<DT> +<TT>flag4 0 | 1</TT></DT> + +<DD> +Not used by this driver.</DD> + + +<P>Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver10.htm b/contrib/ntp/html/driver10.htm new file mode 100644 index 0000000..bdf314a --- /dev/null +++ b/contrib/ntp/html/driver10.htm @@ -0,0 +1,114 @@ +<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> +</HEAD> +<BODY> + +<H3> +Austron 2200A/2201A GPS Receivers</H3> + +<HR> +<H4> +Synopsis</H4> +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> +<H4> +Description</H4> +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.htm">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.htm">Pulse-per-second +(PPS) Signal Interfacing</A> page. + +<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>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 +of the ntp3 distribution. +<H4> +Monitor Data</H4> +When enabled by the <TT>flag4</TT> fudge flag, every received timecode +is written as-is to the <TT>clockstats</TT> file. +<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> +Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver11.htm b/contrib/ntp/html/driver11.htm new file mode 100644 index 0000000..6e5dd7a --- /dev/null +++ b/contrib/ntp/html/driver11.htm @@ -0,0 +1,150 @@ +<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> +</HEAD> +<BODY> + +<H3> +Arbiter 1088A/B GPS Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +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> +<H4> +Description</H4> +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>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>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>Format <TT>B5</TT> (24 ASCII printing characters): +<PRE><cr><lf>i yy ddd hh:mm:ss.000bbb + +on-time = <cr> +i = synchronization flag (' ' = locked, '?' = unlocked) +yy = year of century +ddd = day of year +hh:mm:ss = hours, minutes, seconds +.000 = fraction of second (not used) +bbb = tailing spaces for fill</PRE> +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>The time quality character is encoded in IEEE P1344 standard: + +<P>Format <TT>TQ</TT> (IEEE P1344 estimated worst-case time quality) +<PRE>0 clock locked, maximum accuracy +F clock failure, time not reliable +4 clock unlocked, accuracy < 1 us +5 clock unlocked, accuracy < 10 us +6 clock unlocked, accuracy < 100 us +7 clock unlocked, accuracy < 1 ms +8 clock unlocked, accuracy < 10 ms +9 clock unlocked, accuracy < 100 ms +A clock unlocked, accuracy < 1 s +B clock unlocked, accuracy < 10 s</PRE> +The status string is encoded as follows: + +<P>Format <TT>SR</TT> (25 ASCII printing characters) +<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> +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. +<H4> +Monitor Data</H4> +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. +<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> +Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver12.htm b/contrib/ntp/html/driver12.htm new file mode 100644 index 0000000..57dbb71 --- /dev/null +++ b/contrib/ntp/html/driver12.htm @@ -0,0 +1,98 @@ +<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> +</HEAD> +<BODY> + +<H3> +KSI/Odetics TPRO/S IRIG Interface</H3> + +<HR> +<H4> +Synopsis</H4> +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 +<H4> +Description</H4> +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>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.htm">A +Kernel Model for Precision Timekeeping </A>page for further details. +<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> +Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver16.htm b/contrib/ntp/html/driver16.htm new file mode 100644 index 0000000..a4b9f0c --- /dev/null +++ b/contrib/ntp/html/driver16.htm @@ -0,0 +1,43 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<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> +</head> +<body> + +<h3> +bc635VME/bc350VXI Time and Frequency Processor</h3> + +<hr> +<h4> +Synopsis</h4> +Address: <font size=-1>127.127.16</font>.<i>u</i> +<br>Reference ID: <font size=-1>BTFP</font> +<br>Driver ID: <font size=-1>GPS_BANCOMM</font> +<br>Bancomm Device<font size=-1>: /dev/btfp0</font> +<br>Requires<font size=-1>: Bancomm bc635 TFP device module driver for +SunOS 4.x/SunOS 5.x</font> +<h4> +Description</h4> +This is the clock driver for the Bancomm bc635VME Time and Frequency Processor. +It requires the BANCOMM bc635VME / +<br>bc350VXI Time and Frequency Processor Module Driver for SunOS 4.x/SunOS +5.x UNIX Systems. +<p>Most of this code is originally from refclock_bancomm.c with thanks. +It has been modified and tested on an UltraSparc IIi-cEngine +<br>running Solaris 2.6. A port for HPUX is not available henceforth. +<br> +<h4> +Additional Information</h4> + +<p><br><a href="http://www.eecis.udel.edu/~ntp/ntp_spool/html/refclock.htm">Reference +Clock Drivers</a> +<hr> +<address> +David L. Mills (mills@udel.edu)</address> + +</body> +</html> diff --git a/contrib/ntp/html/driver18.htm b/contrib/ntp/html/driver18.htm new file mode 100644 index 0000000..5410d98 --- /dev/null +++ b/contrib/ntp/html/driver18.htm @@ -0,0 +1,235 @@ +<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> +</HEAD> +<BODY> + +<H3> +NIST Modem Time Service</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.18.<I>u</I> +<BR>Reference ID: <TT>NIST</TT> +<BR>Driver ID: <TT>ACTS_NIST</TT> +<BR>Serial Port: <TT>/dev/acts<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 +<H4> +Description</H4> +This driver supports the NIST Automated Computer Time Service (ACTS). It +periodically dials a prespecified telephone number, receives the NIST timecode +data and calculates the local clock correction. It designed primarily for +use when neither a radio clock nor connectivity to Internet time servers +is available. For the best accuracy, the individual telephone line/modem +delay needs to be calibrated using outside sources. + +<P>The ACTS is located at NIST Boulder, CO, telephone 303 494 4774. A toll +call from Newark, DE, costs between three and four cents, although it is +not clear what carrier and time of day discounts apply. The modem dial +string will differ depending on local telephone configuration, etc., and +is specified by the phone command in the configuration file. The argument +to this command is an AT command for a Hayes compatible modem. + +<P>The driver can operate in either of two modes, as determined by the +mode parameter in the server configuration command. In mode 0 the driver +operates continuously at intervals determined by the fudge time1 parameter, +as described above. In mode 1 the driver is enabled only when no other +sources of synchronization are available and when we have gone more than +MAXOUTAGE (3600 s) since last synchronized by other sources of synchronization. + +<P>The accuracy produced by this driver should be in the range of a millisecond +or two, but may need correction due to the delay characteristics of the +individual modem involved. For undetermined reasons, some modems work with +the ACTS echo-delay measurement scheme and some don't. This driver tries +to do the best it can with what it gets. Initial experiments with a Practical +Peripherals 9600SA modem here in Delaware suggest an accuracy of a millisecond +or two can be achieved without the scheme by using a fudge time1 value +of 65.0 ms. In either case, the dispersion for a single call involving +ten samples is about 1.3 ms. + +<P>For reliable call management, this driver requires a 1200-bps modem +with a Hayes-compatible command set and control over the modem data terminal +ready (DTR) control line. Present restrictions require the use of a POSIX-compatible +programming interface, although other interfaces may work as well. The +ACTS telephone number and modem setup string are hard-coded in the driver +and may require changes for nonstandard modems or special circumstances. + +<P>The fudge time1 parameter represents a propagation-delay correction +factor which is added to the value computed by ACTS when the echo-delay +scheme is used. This scheme does not work with all modems; for those that +don't, fudge flag2 should be set to disable the feature. In this case the +fudge time1 parameter represents the total propagation delay due to all +causes and must be determined by external calibration. + +<P>The ACTS call interval is determined by a counter initially set to the +fudge time2 parameter. At each poll interval, minpoll (usually 64 s) is +subtracted from the counter. When the counter is equal to or less than +zero, the fudge flag1 is set, which causes up to three call attempts to +be made to ACTS. The fudge flag1 is reset after a valid clock update has +been determined or by a device fault, timeout or manually using <TT>ntpdc</TT>. +After a valid clock update, the counter is reset for the next interval. +Setting the <TT>fudge time2</TT> parameter to zero disables automatic call +attempts. Manual call attempts can be made at any time by setting <TT>fudge +flag1</TT> using ntpdc. + +<P>The NIST timecode message is transmitted at 1200 bps in the following +format: +<PRE> +jjjjj yy-mm-dd hh:mm:ss tt l uuu mmmmm UTC(NIST) * + +jjjjj = modified Julian day +yy-mm-dd = year, month, day +hh:mm:ss = hours, minutes, seconds +tt = DST indicator (see driver listing) +l = leap-second warning (see driver listing) +uuu = DUT1 correction (see driver listing) +mmmmm = modem calibration (see driver listing) +on-time = '*'</PRE> +The timecode message is transmitted continuously after a signon banner, +which this driver ignores. The driver also ignores all but the yy-mm-dd, +hh:mm:ss and on-time character '*' fields, although it checks the format +of all fields of the message. A timestamp is captured at the '*' character, +as required by the ACTS specification, and used as the reference time of +the timecode. If a message with an on-time character of '#' is received, +the driver updates the propagation delay. The driver disconnects when (a) +ten valid messages have been received, (b) no message has been received +for 15 s, (c) an on-time character of '#' is received. These messages are +processed by a trimmed-mean filter to reduce timing noise and then by the +usual NTP algorithms to develop the clock correction. + +<P>Since the accumulated error grows with the interval between calls, it +is important that the intrinsic frequency error be minimized. This can +be done by observing difference in offsets between two calls placed some +hours apart and calculating the uncorrected frequency error. This error, +as a fixed-point value in parts-per-million, should be installed in the +ntp.drift file before the daemon is started. Some experimentation may be +necessary in order to reduce the intrinsic frequency error to the order +of 1 ppm. + +<P>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 prefer keyword of the server configuration command, +in which case only this driver will be selected for synchronization and +all other discipline sources will be ignored. + +<P>Unlike other drivers, each ACTS call generates one clock correction +and that correction is processed immediately. There is no wait to allow +the clock filter to accumulate samples. In addition, the watchdog timeout +of the local clock algorithm is disabled, so that a correction received +from this driver that exceeds CLOCK_MAX (128 ms) causes an immediate step/slew. + +<P>Since the interval between updates can be much longer than used with +ordinary NTP peers, the local clock procedure has been modified to operate +in either of two modes, depending on whether the interval between updates +is less than or greater than CLOCK_MAXSEC (1200 s). If less than this value, +the local clock procedure operates using the standard NTP phase-lock loop +as with other NTP peers. If greater than this value, the procedure operates +using a modified frequency-lock loop suggested by Judah Levine in his lockclock +algorithm designed specifically for ACTS. +<H4> +Call Management</H4> +Since ACTS will be a toll call in most areas of the country, it is necessary +to carefully manage the call frequency. This can be done in two ways, by +specifying the interval between calls, or by setting a flag bit manually +or via a cron job. The call interval is determined by a counter initially +set to the fudge time2 parameter. At each poll interval, minpoll (usually +64 s) is subtracted from the counter. When the counter is equal to or less +than zero, the fudge flag1 is set, which causes up to three call attempts +to be made. The fudge flag1 is reset after ten offset samples have been +determined in a single call or by a device fault, timeout or manually using +ntpdc. Upon successful completion of a call, the eight samples have been +shifted into the clock filter, the local clock updated and the counter +reset for the next interval. Setting the fudge time2 parameter to zero +disables automatic call attempts. + +<P>Manual call attempts can be made at any time by setting fudge flag1 +using ntpdc. For example, the ntpdc command +<PRE> +fudge 127.127.18.1 flags 1</PRE> +will ask for a key identifier and password and, if authenticated by the +server, will set flag1. There may be a short delay until the expiration +of the current poll timeout. + +<P>The flag1 can be set from a cron job in the following way. Construct +a file with contents +<PRE>keyid 11 +passwd dialup +fudge 127.127.18.1 flags 1 +quit</PRE> +Then, run the following program at specified times as required. +<PRE>/usr/local/bin/ntpdc <file</PRE> + +<H4> +Monitor Data</H4> +When enabled by the <TT>flag4</TT> fudge flag, every received timecode +is written as-is to the <TT>clockstats</TT> file. +<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>NIST</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.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver19.htm b/contrib/ntp/html/driver19.htm new file mode 100644 index 0000000..a5cd5e0 --- /dev/null +++ b/contrib/ntp/html/driver19.htm @@ -0,0 +1,124 @@ +<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> +</HEAD> +<BODY> + +<H3> +Heath WWV/WWVH Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +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 +<H4> +Description</H4> +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>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>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>The clock message consists of 23 ASCII printing characters in the following +format: +<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> +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>A fudge time1 value of .07 s appears to center the clock offset residuals. +<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.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver2.htm b/contrib/ntp/html/driver2.htm new file mode 100644 index 0000000..885a1b2 --- /dev/null +++ b/contrib/ntp/html/driver2.htm @@ -0,0 +1,137 @@ +<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> +</HEAD> +<BODY> + +<H3> +Trak 8820 GPS Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +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> +<H4> +Description</H4> +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>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>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>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: +<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. +<H4> +Monitor Data</H4> +When enabled by the <TT>flag4</TT> fudge flag, every received timecode +is written as-is to the <TT>clockstats</TT> file. +<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> +Not used by this driver.</DD> + + +<P>Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver20.htm b/contrib/ntp/html/driver20.htm new file mode 100644 index 0000000..e6a4bd2 --- /dev/null +++ b/contrib/ntp/html/driver20.htm @@ -0,0 +1,131 @@ +<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>Generic NMEA GPS Receiver +</TITLE> +</HEAD> +<BODY> + +<H3> +Generic NMEA GPS Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +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>Features: <TT>tty_clk</TT> +<H4> +Description</H4> +This driver supports GPS receivers with the <TT>$GPRMC</TT> NMEA output string. +The driver expect the receiver to be set up to transmit a <TT>$GPRMC</TT> +message every second. + +<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>The $GPRMC message that the GPS transmits look like this: +<PRE>$GPRMC,POS_UTC,POS_STAT,LAT,LAT_REF,LON,LON_REF,SPD,HDG,DATE,MAG_VAR,MAG_REF*CC<cr><lf> + + POS_UTC - UTC of position. Hours, minutes and seconds. (hhmmss) + 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) + CC - Checksum (optional) + <cr><lf> - Sentence terminator.</PRE> +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. +<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> +Now switch only $GPRMC on by sending it the following string. +<PRE>"$PGRMO,GPRMC,1<cr><lf>"</PRE> +On some systems the PPS signal isn't switched on by default. It can be +switched on by sending the following string. +<PRE>"$PGRMC,,,,,,,,,,,,2<cr><lf>"</PRE> + +<H4> +Monitor Data</H4> +The $GPRMC string that is used is written to the clockstats file. +<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> +Not used by this driver.</DD> + + +<P>Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver22.htm b/contrib/ntp/html/driver22.htm new file mode 100644 index 0000000..313d2b8 --- /dev/null +++ b/contrib/ntp/html/driver22.htm @@ -0,0 +1,129 @@ +<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>PPS Clock Discipline +</TITLE> +</HEAD> +<BODY> + +<H3> +PPS Clock Discipline</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.22.<I>u</I> +<BR>Reference ID: <TT>PPS</TT> +<BR>Driver ID: <TT>PPS</TT> +<BR>Serial Port: <TT>/dev/pps<I>u</I></TT>; 9600 baud, 8-bits, no parity +<BR>Features: <TT>tty_clk</TT> +<H4> +Description</H4> +This driver furnishes an interface for pulse-per-second (PPS) signals produced +by a cesium clock, radio clock or related equipment. It can be used to +remove accumulated jitter and retime a secondary server when synchronized +to a primary server over a congested, wide-area network and before redistributing +the time to local clients. + +<P>In order for this driver to work, the local clock must be set to within ++-500 ms by another means, such as a radio clock or NTP itself. The PPS +signal is connected via a serial port and <A HREF="gadget.htm">gadget box</A> +consisting of a one-shot and RS232 level converter. When operated at 38.4 +kbps with a SPARCstation IPC, this arrangement has a worst-case jitter +less than 26 us. + +<P>There are three ways in which this driver can be used. The first way +uses the <TT>ppsclock</TT> line discipline and works only for the baseboard +serial ports of the Sun SPARCstation running SunOS 4.x. The PPS signal +is connected via the gadget box to the carrier detect (DCD) line of a serial +port. The signal is activated for this port by a <TT>fudge flag3 1</TT> +command following the <TT>server</TT> command in the configuration file. +This causes the <TT>ppsclock</TT> streams module to be configured for that +port and to capture a timestamp at the on-time transition of the PPS signal. +This driver then reads the timestamp directly by a designated <TT>ioctl()</TT> +system call. This provides the most accurate time and least jitter of any +other scheme. There is no need to configure a dedicated device for this +purpose, which ordinarily is the device used for the associated radio clock. + +<P>The second way uses the <TT>tty_clk</TT> line discipline and works for +any architecture supporting a serial port. If after a few seconds this +driver finds no <TT>ppsclock</TT> module configured, it attempts to open +a serial port device <TT>/dev/pps%d</TT>, where <TT>%d</TT> is the unit +number, and assign the <TT>tty_clk</TT> line discipline to it. If the line +discipline fails, no harm is done except the accuracy is reduced somewhat. +The pulse generator in the gadget box must be adjusted to produce a start +bit of length 26 usec at 38400 bps. Used with the <TT>tty_clk</TT> line +discipline, this produces an ASCII DEL character ('\377') followed by a +timestamp at the on-time transition of the PPS signal. + +<P>The third way involves an auxiliary radio clock driver which calls the +PPS driver with a timestamp captured by that driver. This use is documented +in the source code for the driver(s) involved. +<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. This parameter can be used to compensate for the UART +and OS delays. Allow about 247 us for UART delays at 38400 bps and about +1 ms for SunOS streams nonsense.</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> +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> + + +<P>Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver23.htm b/contrib/ntp/html/driver23.htm new file mode 100644 index 0000000..6633999 --- /dev/null +++ b/contrib/ntp/html/driver23.htm @@ -0,0 +1,87 @@ +<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>PTB Modem Time Service +</TITLE> +</HEAD> +<BODY> + +<H3> +PTB Modem Time Service</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.23.<I>u</I> +<BR>Reference ID: <TT>PTB</TT> +<BR>Driver ID: <TT>ACTS_PTP</TT> +<BR>Serial Port: <TT>/dev/ptb<I>u</I></TT>; 1200 baud, 8-bits, no parity +<BR>Requires: <TT>/usr/include/sys/termios.h</TT> header file with modem +control +<H4> +Description</H4> +No further information available. +<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 PTB.</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 drivert.</DD> +</DL> +Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver24.htm b/contrib/ntp/html/driver24.htm new file mode 100644 index 0000000..70c623b --- /dev/null +++ b/contrib/ntp/html/driver24.htm @@ -0,0 +1,85 @@ +<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>USNO Modem Time Service +</TITLE> +</HEAD> +<BODY> + +<H3> +USNO Modem Time Service</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.24.<I>u</I> +<BR>Reference ID: <TT>USNO</TT> +<BR>Driver ID: <TT>ACTS_USNO</TT> +<BR>Serial Port: <TT>/dev/cua<I>u</I></TT>; 1200 baud, 8-bits, no parity +<BR>Requires: <TT>/usr/include/sys/termios.h</TT> header file with modem +control +<H4> +Description</H4> +No information available. +<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>USNO</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 <TT>clockstats</TT> recording if set.</DD> +</DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver26.htm b/contrib/ntp/html/driver26.htm new file mode 100644 index 0000000..eabbc96 --- /dev/null +++ b/contrib/ntp/html/driver26.htm @@ -0,0 +1,109 @@ +<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>Hewlett Packard 58503A GPS Receiver +</TITLE> +</HEAD> +<BODY> + +<H3> +Hewlett Packard 58503A GPS Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.26.<I>u</I> +<BR>Reference ID: <TT>GPS</TT> +<BR>Driver ID: <TT>GPS_HP</TT> +<BR>Serial Port: <TT>/dev/hpgps<I>u</I></TT>; 9600 baud, 8-bits, no parity +<H4> +Description</H4> +This driver supports the HP 58503A Time and Frequency Reference Receiver. +It uses HP SmartClock (TM) to implement an Enhanced GPS receiver. The receiver +accuracy when locked to GPS in normal operation is better than 1 usec. +The accuracy when operating in holdover is typically better than 10 us +per day. It receiver should be operated with factory default settings. +Initial driver operation: expects the receiver to be already locked to +GPS, configured and able to output timecode format 2 messages. + +<P>The driver uses the poll sequence <TT>:PTIME:TCODE?</TT> to get a response +from the receiver. The receiver responds with a timecode string of ASCII +printing characters, followed by a <cr><lf>, followed by a prompt +string issued by the receiver, in the following format: +<PRE>T#yyyymmddhhmmssMFLRVcc<cr><lf></PRE> +The driver processes the response at the <cr> and <lf><cr> and +<lf>, so what the driver sees is the prompt from the previous poll, +followed by this timecode. The prompt from the current poll is (usually) +left unread until the next poll. So (except on the very first poll) the +driver sees this: +<PRE>T#yyyymmddhhmmssMFLRVcc<cr><lf></PRE> +The T is the on-time character, at 980 msec. before the next 1PPS edge. +The # is the timecode format type. We look for format 2. Without any of +the CLK or PPS stuff, then, the receiver buffer timestamp at the <cr>y +is 24 characters later, which is about 25 msec. at 9600 bps, so the first +approximation for fudge time1 is nominally -0.955 seconds. This number +probably needs adjusting for each machine / OS type, so far: -0.955000 +on an HP 9000 Model 712/80 HP-UX 9.05 -0.953175 on an HP 9000 Model 370 +HP-UX 9.10 +<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> +Not used by this driver.</DD> +</DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver27.htm b/contrib/ntp/html/driver27.htm new file mode 100644 index 0000000..686e985 --- /dev/null +++ b/contrib/ntp/html/driver27.htm @@ -0,0 +1,634 @@ +<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>Arcron MSF Receiver +</TITLE> +</HEAD> +<BODY> + +<H3> +Arcron MSF Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.27.<I>u</I> +<BR>Reference ID: <TT>MSFa</TT> +<BR>Driver ID: <TT>MSF_ARCRON</TT> +<BR>Serial Port: <TT>/dev/arc<I>u</I></TT>; 300 baud, 8-bits, 2-stop, no +parity +<BR>Features: <TT>tty_clk</TT> +<H4> +Description</H4> +This driver supports the Arcron MSF receiver, and would probably also support +the DCF77 variant of the same clock. The clock reports its ID as ``<TT>MSFa</TT>'' +to indicate MSF as a source and the use of the ARCRON driver. + +<P>This documentation describes version V1.1 (1997/06/23) of the source +and has been tested (amongst others) against ntpd3-5.90 on Solaris-1 (SunOS +4.1.3_U1 on an SS1 serving as a router and firewall) and against ntpd3-5.90 +on Solaris-2.5 (on a SS1+ and TurboSPARC 170MHz). This code will probably +work, and show increased stability, reduced jitter and more efficiency +(fewer context switches) with the <TT>tty_clk</TT> discipline/STREAMS module +installed, but this has not been tested. For a to-do list see the comments +at the start of the code. + +<P>This code has been significantly slimmed down since the V1.0 version, +roughly halving the memory footprint of its code and data. + +<P>This driver is designed to allow the unit to run from batteries as designed, +for something approaching the 2.5 years expected in the usual stand-alone +mode, but no battery-life measurements have been taken. + +<P>Much of this code is originally from the other refclock driver files +with thanks. The code was originally made to work with the clock by <A HREF="mailto:derek@toybox.demon.co.uk">Derek +Mulcahy</A>, with modifications by <A HREF="mailto:d@hd.org">Damon Hart-Davis</A>. +Thanks also to <A HREF="mailto:lyndond@sentinet.co.uk">Lyndon David</A> +for some of the specifications of the clock. + +<P>There is support for a Tcl/Tk monitor written by Derek Mulcahy that +examines the output stats; see the <A HREF="http://www2.exnet.com/NTP/ARC/ARC.htm">ARC +Rugby MSF Receiver</A> page for more details and the code. + +<P>Look at the notes at the start of the code for further information; +some of the more important details follow. + +<P>The driver interrogates the clock at each poll (ie every 64s by default) +for a timestamp. The clock responds at the start of the next second (with +the start bit of the first byte being on-time). The time is in `local' +format, including the daylight savings adjustment when it is in effect. +The driver code converts the time back to UTC. + +<P>The clock claims to be accurate to within about 20ms of the MSF-broadcast +time, and given the low data transmission speed from clock to host, and +the fact that the clock is not in continuous sync with MSF, it seems sensible +to set the `precision' of this clock to -5 or -4, -4 being used in this +code, which builds in a reported dispersion of over 63ms (ie says ``This +clock is not very good.''). You can improve the reported precision to -4 +(and thus reduce the base dispersion to about 31ms) by setting the fudge +<TT>flag3</TT> to <TT>1</TT>. + +<P>Even a busy and slow IP link can yield lower dispersions than this from +polls of primary time servers on the Internet, which reinforces the idea +that this clock should be used as a backup in case of problems with such +an IP link, or in the unfortunate event of failure of more accurate sources +such as GPS. + +<P>By default this clock reports itself to be at stratum 2 rather than +the usual stratum 0 for a refclock, because it is not really suited to +be used as other than a backup source. The stratum reported can be changed +with the <TT>fudge</TT> directive to be whatever you like. After careful +monitoring of your clock, and appropriate choice of the <TT>time1</TT> +fudge factor to remove systematic errors in the clock's reported time, +you might fudge the clock to stratum 1 to allow a stratum-2 secondary server +to sync to it. + +<P>The driver code arranges to resync the clock to MSF at intervals of +a little less than an hour (deliberately avoiding the same time each hour +to avoid any systematic problems with the signal or host). Whilst resyncing, +the driver supplements the normal polls for time from the clock with polls +for the reception signal quality reported by the clock. If the signal quality +is too low (0--2 out of a range of 0--5), we chose not to trust the clock +until the next resync (which we bring forward by about half an hour). If +we don't catch the resync, and so don't know the signal quality, we do +trust the clock (because this would generally be when the signal is very +good and a resync happens quickly), but we still bring the next resync +forward and reduce the reported precision (and thus increase reported dispersion). + +<P>If we force resyncs to MSF too often we will needlessly exhaust the +batteries the unit runs from. During clock resync this driver tries to +take enough time samples to avoid <TT>ntpd</TT> losing sync in case this +clock is the current peer. By default the clock would only resync to MSF +about once per day, which would almost certainly not be acceptable for +NTP purposes. + +<P>The driver does not force an immediate resync of the clock to MSF when +it starts up to avoid excessive battery drain in case <TT>ntpd</TT> is +going to be repeatedly restarted for any reason, and also to allow enough +samples of the clock to be taken for <TT>ntpd</TT> to sync immediately +to this clock (and not remain unsynchronised or to sync briefly to another +configured peer, only to hop back in a few poll times, causing unnecessary +disturbance). This behaviour should not cause problems because the driver +will not accept the timestamps from the clock if the status flag delivered +with the time code indicates that the last resync attempt was unsuccessful, +so the initial timestamps will be close to reality, even if with up to +a day's clock drift in the worst case (the clock by default resyncs to +MSF once per day). + +<P>The clock has a peculiar RS232 arrangement where the transmit lines +are powered from the receive lines, presumably to minimise battery drain. +This arrangement has two consequences: +<UL> +<LI> +Your RS232 interface must drive both +ve and -ve</LI> + +<LI> +You must (in theory) wait for an echo and a further 10ms between characters</LI> +</UL> +This driver, running on standard Sun hardware, seems to work fine; note +the use of the <TT>send_slow()</TT> routine to queue up command characters +to be sent once every two seconds. + +<P>Three commands are sent to the clock by this driver. Each command consists +of a single letter (of which only the bottom four bits are significant), +followed by a CR (ASCII 13). Each character sent to the clock should be +followed by a delay to allow the unit to echo the character, and then by +a further 10ms. Following the echo of the command string, there may be +a response (ie in the cae of the <TT>g</TT> and <TT>o</TT> commands below), +which in the case of the <TT>o</TT> command may be delayed by up to 1 second +so as the start bit of the first byte of the response can arrive on time. +The commands and their responses are: +<DL> +<DT> +<TT>g</TT> CR</DT> + +<DD> +Request for signal quality. Answer only valid during (late part of) resync +to MSF signal. The response consists of two characters as follows:</DD> + +<OL> +<DL compact> +<DT> +bit 7</DT> + +<DD> +parity</DD> + +<DT> +bit 6</DT> + +<DD> +always 0</DD> + +<DT> +bit 5</DT> + +<DD> +always 1</DD> + +<DT> +bit 4</DT> + +<DD> +always 1</DD> + +<DT> +bit 3</DT> + +<DD> +always 0</DD> + +<DT> +bit 2</DT> + +<DD> +always 0</DD> + +<DT> +bit 1</DT> + +<DD> +always 1</DD> + +<DT> +bit 0</DT> + +<DD> += 0 if no reception attempt at the moment, = 1 if reception attempt (ie +resync) in progress</DD> +</DL> + +<DL compact> +<DT> +bit 7</DT> + +<DD> +parity</DD> + +<DT> +bit 6</DT> + +<DD> +always 0</DD> + +<DT> +bit 5</DT> + +<DD> +always 1</DD> + +<DT> +bit 4</DT> + +<DD> +always 1</DD> + +<DT> +bit 3</DT> + +<DD> +always 0</DD> + +<DT> +bit 2--0</DT> + +<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'.</DD> +</DL> +</OL> + +<DT> +<TT>h</TT> CR</DT> + +<DD> +Request to resync to MSF. 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 Rugby +MSF (remember to allow for propagation time). By default the clock resyncs +once per day shortly after 2am (presumably to catch transitions to/from +daylight saving time quickly). With this driver code we resync at least +once per hour to minimise clock wander.</DD> + +<DT> +<TT>o</TT> CR</DT> + +<DD> +Request timestamp. Start bit of first byte of response is on-time, so may +be delayed up to 1 second. Note that when the BST mode is in effect the +time is GMT/UTC +0100, ie an hour ahead of UTC to reflect local time in +the UK. The response data is as follows:</DD> + +<OL> +<LI> +hours tens (hours range from 00 to 23)</LI> + +<LI> +hours units</LI> + +<LI> +minutes tens (minutes range from 00 to 59)</LI> + +<LI> +minutes units</LI> + +<LI> +seconds tens (seconds presumed to range from 00 to 60 to allow for leap +second)</LI> + +<LI> +seconds units</LI> + +<LI> +day of week 1 (Monday) to 7 (Sunday)</LI> + +<LI> +day of month tens (day ranges from 01 to 31)</LI> + +<LI> +day of month units</LI> + +<LI> +month tens (months range from 01 to 12)</LI> + +<LI> +month units</LI> + +<LI> +year tens (years range from 00 to 99)</LI> + +<LI> +year units</LI> + +<LI> +BST/UTC status</LI> + +<DL compact> +<DT> +bit 7</DT> + +<DD> +parity</DD> + +<DT> +bit 6</DT> + +<DD> +always 0</DD> + +<DT> +bit 5</DT> + +<DD> +always 1</DD> + +<DT> +bit 4</DT> + +<DD> +always 1</DD> + +<DT> +bit 3</DT> + +<DD> +always 0</DD> + +<DT> +bit 2</DT> + +<DD> += 1 if UTC is in effect (reverse of bit 1)</DD> + +<DT> +bit 1</DT> + +<DD> += 1 if BST is in effect (reverse of bit 2)</DD> + +<DT> +bit 0</DT> + +<DD> += 1 if BST/UTC change pending</DD> +</DL> + +<LI> +clock status</LI> + +<DL compact> +<DT> +bit 7</DT> + +<DD> +parity</DD> + +<DT> +bit 6</DT> + +<DD> +always 0</DD> + +<DT> +bit 5</DT> + +<DD> +always 1</DD> + +<DT> +bit 4</DT> + +<DD> +always 1</DD> + +<DT> +bit 3</DT> + +<DD> += 1 if low battery is detected</DD> + +<DT> +bit 2</DT> + +<DD> += 1 if last resync failed (though officially undefined for the MSF clock)</DD> + +<DT> +bit 1</DT> + +<DD> += 1 if at least one reception attempt since 0230 for the MSF clock was +successful (0300 for the DCF77 clock)</DD> + +<DT> +bit 0</DT> + +<DD> += 1 if the clock has valid time---reset to zero when clock is reset (eg +at power-up), and set to 1 after first successful resync attempt.</DD> +</DL> +</OL> +The driver only accepts time from the clock if the bottom three bits of +the status byte are <TT>011</TT>. The leap-year logic for computing day-in-year +is only valid until 2099, and the clock will ignore stamps from the clock +that claim BST is in effect in the first hour of each year. If the UK parliament +decides to move us to +0100/+0200 time as opposed to the current +0000/+0100 +time, it is not clear what effect that will have on the time broadcast +by MSF, and therefore on this driver's usefulness.</DL> +A typical <TT>ntp.conf</TT> configuration file for this driver might be: +<PRE># hostname(n) means we expect (n) to be the stratum at which hostname runs. + +#------------------------------------------------------------------------------ +# SYNCHRONISATION PARTNERS +# ======================== + +# Our betters... +server 127.127.27.0 # ARCRON MSF radio clock(1). +# Fudge stratum and other features as required. +# ADJUST time1 VALUE FOR YOUR HOST, CLOCK AND LOCATION! +fudge 127.127.27.0 stratum 1 time1 0.016 flag3 1 flag4 1 + +peer 11.22.33.9 # tick(1--2). +peer 11.22.33.4 # tock(3), boot/NFS server. + +# This shouldn't get swept away unless left untouched for a long time. +driftfile /var/tmp/ntp.drift + +#------------------------------------------------------------------------------ +# RESTRICTIONS +# ============ + +# By default, don't trust and don't allow modifications. Ignore in fact. +restrict default ignore notrust nomodify + +# Allow others in our subnet to check us out... +restrict 11.22.33.0 mask 255.255.255.0 nomodify notrust + +# Trust our peers for time. Don't trust others in case they are insane. +restrict 127.127.27.0 nomodify +restrict 11.22.33.4 nomodify +restrict 11.22.33.9 nomodify + +# Allow anything from the local host. +restrict 127.0.0.1</PRE> +There are a few <TT>#define</TT>s in the code that you might wish to play +with: +<DL> +<DT> +<TT>ARCRON_KEEN</TT></DT> + +<DD> +With this defined, the code is relatively trusting of the clock, and assumes +that you will have the clock as one of a few time sources, so will bend +over backwards to use the time from the clock when available and avoid +<TT>ntpd</TT> dropping sync from the clock where possible. You may wish +to undefine this, especially if you have better sources of time or your +reception is ropey. However, there are many checks built in even with this +flag defined.</DD> + +<DT> +<TT>ARCRON_OWN_FILTER</TT></DT> + +<DD> +When defined, the code uses its own median-filter code rather than that +available in <TT>ntp_refclock.c</TT> since the latter seems to have a minor +bug, at least in version 3-5.90. If this bug goes away this flag should +be turned off to avoid duplication of code. (The bug, if that's what it +is, causes the last raw offset to be used rather than the median offset.)</DD> + + +<P>Without this defined (and without <TT>ARCRON_MULTIPLE_SAMPLES</TT> below) +a typical set of offsets reported and used to drive the clock-filter algorithm +is (oldest last): +<PRE>filtoffset= -4.32 -34.82 -0.78 0.89 2.76 4.58 -3.92 -2.17</PRE> +Look at that spike! + +<P>With this defined a typical set of offsets is: +<PRE>filtoffset= -7.06 -7.06 -2.91 -2.91 -2.91 -1.27 -9.54 -6.70</PRE> +with the repeated values being some evidence of outlyers being discarded. +<DT> +<TT>ARCRON_MULTIPLE_SAMPLES</TT></DT> + +<DD> +When is defined, we regard each character in the returned timecode as at +a known delay from the start of the second, and use the smallest (most +negative) offset implied by any such character, ie with the smallest kernel-induced +display, and use that. This helps to reduce jitter and spikes.</DD> + +<DT> +<TT>ARCRON_LEAPSECOND_KEEN</TT></DT> + +<DD> +When is defined, we try to do a resync to MSF as soon as possible in the +first hour of the morning of the first day of the first and seventh months, +ie just after a leap-second insertion or deletion would happen if it is +going to. This should help compensate for the fact that this clock does +not continuously sample MSF, which compounds the fact that MSF itself gives +no warning of an impending leap-second event. This code did not seem functional +at the leap-second insertion of 30th June 1997 so is by default disabled.</DD> + +<DT> +<TT>PRECISION</TT></DT> + +<DD> +Currently set to <TT>-4</TT>, but you may wish to set it to <TT>-5</TT> +if you are more conservative, or to <TT>-6</TT> if you have particularly +good experience with the clock and you live on the edge. Note that the +<TT>flag3</TT> fudge value will improve the reported dispersion one notch +if clock signal quality is known good. So maybe just leave this alone. +B^)</DD> + +<DT> +<TT>NSAMPLES</TT></DT> + +<DD> +Should be at least 3 to help smooth out sampling jitters. Can be more, +but if made too long can make <TT>ntpd</TT> overshoot on clock corrections +and can hold onto bad samples longer than you would like. With this set +to 4 and <TT>NKEEP</TT> set to 3 this allows the occasional bad sample +(in my experience less than 1 value in 10) to be dropped. (Note that there +seems to be some sort of `beat' effect in the offset with a periodicity +of about 7 samples as of this writing (1997/05/11) still under investigation; +a filter of approximately this length should be able to almost completely +suppress this effect.) Note that if the fudge-factor <TT>flag3</TT> is +set to 1, a larger <TT>NSAMPLES</TT> is used.</DD> +</DL> + +<H4> +Monitor Data</H4> +Each timecode is written to the <TT>clockstats</TT> file with a signal +quality value appended (`0'--`5' as reported by the clock, or `6' for unknown). + +<P>Each resync and result (plus gaining or losing MSF sync) is logged to +the system log at level <TT>LOG_NOTICE</TT>; note that each resync drains +the unit's batteries, so the syslog entry seems justified. + +<P>Syslog entries are of the form: +<PRE>May 10 10:15:24 oolong ntpd[615]: ARCRON: unit 0: sending resync command +May 10 10:17:32 oolong ntpd[615]: ARCRON: sync finished, signal quality 5: OK, will use clock +May 10 11:13:01 oolong ntpd[615]: ARCRON: unit 0: sending resync command +May 10 11:14:06 oolong ntpd[615]: ARCRON: sync finished, signal quality -1: UNKNOWN, will use clock anyway +May 10 11:41:49 oolong ntpd[615]: ARCRON: unit 0: sending resync command +May 10 11:43:57 oolong ntpd[615]: ARCRON: sync finished, signal quality 5: OK, will use clock +May 10 12:39:26 oolong ntpd[615]: ARCRON: unit 0: sending resync command +May 10 12:41:34 oolong ntpd[615]: ARCRON: sync finished, signal quality 3: OK, will use clock</PRE> + +<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. On a Sun SparcStation 1 running SunOS 4.1.3_U1, with +the receiver in London, a value of 0.020 (20ms) seems to be appropriate.</DD> + +<DT> +<TT>time2 <I>time</I></TT></DT> + +<DD> +Not currently 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. +It is suggested that the clock be fudged to stratum 1 so this it is used +a backup time source rather than a primary when more accurate sources are +available.</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>MSFa</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> +If set to 1, better precision is reported (and thus lower dispersion) while +clock's received signal quality is known to be good.</DD> + +<DT> +<TT>flag4 0 | 1</TT></DT> + +<DD> +If set to 1, a longer-than-normal (8-stage rather than 4-stage) median +filter is used, to provide some extra smoothing of clock output and reduction +in jitter, at the cost of extra clock overshoot. Probably not advisable +unless the server using this clock has other sources it can use to help +mitigate the overshoot.</DD> +</DL> + +<H4> +Additional Information</H4> +<A HREF="refclock.htm">Reference Clock Drivers</A> + +<P><A HREF="http://www2.exnet.com/NTP/ARC/ARC.htm">ARC Rugby MSF Receiver</A> +page +<HR> +<ADDRESS> +Damon Hart-Davis (d@hd.org)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver28.htm b/contrib/ntp/html/driver28.htm new file mode 100644 index 0000000..787ccb4 --- /dev/null +++ b/contrib/ntp/html/driver28.htm @@ -0,0 +1,133 @@ +<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>Shared memoy Driver +</TITLE> +</HEAD> +<BODY> + +<H3> +Shared Memory Driver</H3> + +<HR> +<H4> +Synopsis</H4> +Address: 127.127.28.<I>u</I> +<BR>Reference ID: <TT>SHM</TT> +<BR>Driver ID: <TT>SHM</TT> +<H4> +Description</H4> +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 +<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]; +};</PRE> + +<H4> +Operation mode=0</H4> +When the poll-method of the driver is called, the valid-flag of the shared +memory-segment is checked: + +<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>If not set, a timeout is reported to ntp, nothing else happend +<H4> +Operation mode=1</H4> +When the poll-method of the driver is called, the valid-flag of the shared +memory-segment is checked: + +<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>If not set, a timeout is reported to ntp, nothing else happend +<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>SHM</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> + + +<P>Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver29.htm b/contrib/ntp/html/driver29.htm new file mode 100644 index 0000000..3cddfc2 --- /dev/null +++ b/contrib/ntp/html/driver29.htm @@ -0,0 +1,1254 @@ +<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <title>Trimble Palisade Receiver</title> +</head> +<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<h1> +<font size=+2>Trimble Palisade Receiver</font> +<hr></h1> + +<h2> +<img SRC="pic/driver29.gif" NOSAVE height=100 width=420></h2> + +<h2> +<font size=+1>Synopsis</font></h2> + +<table> +<tr> +<td> +<div align=right><tt>Address: </tt></div> +</td> + +<td><b>127.127.29.<i>u</i></b></td> +</tr> + +<tr> +<td> +<div align=right><tt>Reference ID:</tt></div> +</td> + +<td><a NAME="REFID"></a><b>GPS</b></td> +</tr> + +<tr> +<td> +<div align=right><tt>Driver ID:</tt></div> +</td> + +<td><b>GPS_PALISADE</b></td> +</tr> + +<tr> +<td> +<div align=right><tt>Serial Port:</tt></div> +</td> + +<td><b>/dev/palisade<i>u</i></b></td> +</tr> + +<tr> +<td> +<div align=right><tt><font size=+1>Serial I/O:</font></tt></div> +</td> + +<td><b>9600 baud, 8-bits, 1-stop, odd 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> +<h2> +<font size=+1>Operating System Compatibility</font></h2> +The Palisade driver has been tested on the following software and hardware +platforms: +<br> +<center><table> +<tr> +<td VALIGN=CENTER WIDTH="23%">Platform</td> + +<td VALIGN=CENTER>Operating System</td> + +<td>NTP Sources</td> + +<td>Accuracy</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="23%">i386 (PC) </td> + +<td VALIGN=CENTER>Linux</td> + +<td>NTP Distribution</td> + +<td>10 us</td> +</tr> + +<tr> +<td>i386 (PC) </td> + +<td>Windows NT</td> + +<td><a href="ftp://ftp.trimble.com/pub/ntp">ftp://ftp.trimble.com/pub/ntp</a></td> + +<td>1 ms</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="23%">SUN</td> + +<td VALIGN=CENTER>Solaris 2.x</td> + +<td>NTP Distribution</td> + +<td>50 us</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="23%">Hewlett-Packard</td> + +<td VALIGN=CENTER>HPUX 9, 10, 11</td> + +<td><a href="http://us-support.external.hp.com">http://us-support.external.hp.com</a></td> + +<td>50 us</td> +</tr> + +<tr> +<td>Various</td> + +<td>Free BSD</td> + +<td>NTP Distribution</td> + +<td>20 us</td> +</tr> +</table></center> + +<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>No user initialization of the receiver is required. This driver is compatible +with the following versions of Palisade: +<br> +<center><table> +<tr> +<td VALIGN=CENTER> +<center>Version</center> +</td> + +<td VALIGN=TOP> +<center>Event Input</center> +</td> + +<td VALIGN=CENTER> +<center>Trimble Part Number</center> +</td> +</tr> + +<tr> +<td VALIGN=CENTER> +<center>7.02</center> +</td> + +<td VALIGN=TOP> +<center>No</center> +</td> + +<td VALIGN=CENTER> +<center>26664-00</center> +</td> +</tr> + +<tr> +<td ALIGN=CENTER VALIGN=CENTER> +<center>7.02E</center> +</td> + +<td VALIGN=TOP> +<center>Yes</center> +</td> + +<td VALIGN=CENTER> +<center>26664-10</center> +</td> +</tr> + +<tr> +<td VALIGN=CENTER> +<center>7.12</center> +</td> + +<td VALIGN=TOP> +<center>Yes</center> +</td> + +<td VALIGN=CENTER> +<center>38158-00</center> +</td> +</tr> +</table></center> + +<dl> +<dl>Note: When using Palisade 26664-00, you must set fudge flag2 to 1 in +<b>ntp.conf</b>. +See <a href="#Configuration">configuration</a>.</dl> + +<dl> +<h3> +<font size=+1>GPS <a NAME="Installation"></a>Installation</font></h3> +A location with unobstructed view of the horizon is recommended. Palisade +is designed to be securely mounted atop standard 3/4 inch threaded pipe. +<p>The 12 conductor (dia. 10 mm) power and I/O cable must be routed +from the rooftop site to the NTP server and properly strain relieved. +<h3> +<font size=+1>GPS <a NAME="Connection"></a>Connection</font></h3> +The Palisade is equipped with dual (A & B) RS-422 serial interfaces +and a differential TTL PPS output. An RS-232 / RS-422 Interface Module +is supplied with the Palisade NTP Synchronization Kit. Palisade <a href="#PortA">port +A</a> must be connected to the NTP host server. Maximum antenna cable length +is 500 meters. See the <a href="#Pinouts">pinouts</a> table for detailed +connection Information. +<p>Palisade's <a href="#PortB">port B</a> provides a TSIP (Trimble Standard +Interface Protocol) interface for diagnostics, configuration, and monitoring. +Port B and the PPS output are not currently used by the Palisade NTP reference +clock driver. +<br> </dl> +</dl> + +<h2> +<font size=+1>O/S Serial Port Configuration</font></h2> +The driver attempts to open the device <b><tt><a href="#REFID">/dev/palisade<i>u</i></a></tt></b> +where +<b><i>u</i></b> is the NTP refclock unit number as defined by the +LSB of the refclock address. Valid refclock unit numbers are 0 - +3. +<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: +<blockquote><tt>ln -s /dev/ttyS0 /dev/palisade0</tt></blockquote> +Windows NT does not support symbolic links to device files. COM<b>x</b>: +is used by the driver, based on the refclock unit number, where unit 1 +corresponds to COM<b>1</b>: and unit 3 corresponds to COM3: +<br> +<h2> +<a NAME="Configuration"></a><font size=+1>NTP Configuration</font></h2> +Palisade NTP configuration file <b><tt>"ntp.conf"</tt></b> with event polling: +<br><tt>#------------------------------------------------------------------------------</tt> +<br><tt># The Primary reference</tt> +<br><tt>server 127.127.29.0 # Trimble Palisade GPS Refclock Unit #0</tt> +<br><tt>peer terrapin.csc.ncsu.edu # internet server</tt> +<br><tt># Drift file for expedient re-synchronization after downtime or +reboot.</tt> +<br><tt>driftfile /etc/ntp.drift</tt> +<br><tt>#------------------------------------------------------------------------------</tt> +<p>Configuration without event polling: +<br><tt>#------------------------------------------------------------------------------</tt> +<br><tt># The Primary reference</tt> +<br><tt>server 127.127.29.0 # Trimble Palisade 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> +<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>Time stamps are reported by the Palisade with respect to UTC time. The +GPS receiver must download UTC offset information from GPS satellites. +After an initial UTC download, the receiver will always start with correct +UTC offset information. +<br> +<h2> +<font size=+1>Run NTP in Debugging Mode</font></h2> +The following procedure is recommended for installing and testing a Palisade +NTP driver: +<ol> +<li> +Perform initial checkout procedures. Place the GPS receiver outdoors; with +clear view of the sky. Allow the receiver to obtain an UTC almanac.</li> + +<li> +Verify presence of timing packets by observing the 1 Hz (PPS) led on the +interface module. It should flash once per second.</li> + +<li> +Connect Palisade's port A to the NTP host.</li> + +<li> +Configure NTP and the serial I/O port on the host system.</li> + +<li> +Initially use <tt><a href="#flag2">fudge flag2</a></tt> in <b><a href="#Configuration">ntp.conf</a>,</b> +to disable event polling (see configuration).</li> + +<li> +Run NTP in debug mode (-d -d), to observe Palisade_receive events.</li> + +<li> +The driver reports the <a href="#TrackingStatus">tracking status of the +receiver</a>. Make sure it is tracking several satellites.</li> + +<li> +Remove fudge flag2 and restart <b>ntpd</b> in debug mode to observe palisade_receive +events.</li> + +<li> +If event polling fails, verify the <a href="#Pinouts">connections</a> and +that the host hardware supports RTS control.</li> +</ol> + +<h2> +<font size=+1>Event Logging</font></h2> +System and Event log entries are generated by NTP to report significant +system events. Administrators should monitor the system log to observe +NTP error messages. Log entries generated by the Palisade NTP reference +clock driver will be of the form: +<blockquote> +<pre>Nov 14 16:16:21 terrapin ntpd[1127]: Palisade #0: <i>message</i></pre> +</blockquote> + +<h2> +<font size=+1>Fudge Factors</font></h2> + +<dl> +<dt> +<a NAME="time1"></a><tt><font size=+1><a href="#Configuration">time1 <i>time</i></a></font></tt></dt> + +<dd> +Specifies the time offset calibration factor, in seconds and fraction, +with default 0.0. If event capture is not used, time1 should be set to +20 milliseconds to correct serial line and operating system delays incurred +in capturing time stamps from the synchronous packets.</dd> + +<dt> +<tt><font size=+1>stratum <i>number</i></font></tt></dt> + +<dd> +Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd> + +<dt> +<tt><font size=+1><a href="#REFID">refid <i>string</i></a></font></tt></dt> + +<dd> +Specifies the driver reference identifier, <b>GPS</b>.</dd> + +<dt> +<a NAME="flag2"></a><tt><font size=+1><a href="#Configuration">flag2 0 +| 1</a></font></tt></dt> + +<dd> +When set to 1, driver does not use hardware event capture. The synchronous +packet output by the receiver at the beginning of each second is time stamped +by the driver. If triggering the event pulse fails, the driver falls back +to this mode automatically.</dd> +</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> +<center><table BORDER > +<tr> +<td><b>Label</b></td> + +<td>Definition</td> + +<td>Default Value</td> +</tr> + +<tr> +<td>DEVICE</td> + +<td>The serial port device to be used by the driver</td> + +<td>/dev/palisade<b><i>u</i></b></td> +</tr> + +<tr> +<td>PRECISION</td> + +<td>Accuracy of time transfer</td> + +<td>1 microsecond</td> +</tr> + +<tr> +<td>CURRENT_UTC</td> + +<td>Valid GPS - UTC offset</td> + +<td>13</td> +</tr> + +<tr> +<td>SPEED232</td> + +<td>Host RS-232 baud rate</td> + +<td>B9600</td> +</tr> + +<tr> +<td>TRMB_MINPOLL </td> + +<td>Minimum polling interval</td> + +<td>5 (32 seconds)</td> +</tr> + +<tr> +<td>TRMB_MAXPOLL</td> + +<td>Maximum interval between polls</td> + +<td>7 (128 seconds)</td> +</tr> +</table></center> + +<h2> +<a NAME="DataFormat"></a><font size=+1>Data Format</font></h2> +Palisade port A can output two synchronous time packets. The NTP driver +can use either packet for synchronization. Packets are formatted as follows: +<h3> +<b><font size=+0>Packet 8F-AD (Primary NTP Packet)</font></b></h3> + +<center><table> +<tr> +<td>Byte</td> + +<td>Item</td> + +<td>Type</td> + +<td>Meaning</td> +</tr> + +<tr> +<td>0</td> + +<td>Sub-Packet ID</td> + +<td>BYTE</td> + +<td>Subcode 0xAD</td> +</tr> + +<tr> +<td>1 - 2</td> + +<td>Event Count</td> + +<td>INTEGER</td> + +<td>External event count recorded (0 = PPS)</td> +</tr> + +<tr> +<td>3 - 10</td> + +<td>Fractional Second</td> + +<td>DOUBLE</td> + +<td>Time elapsed in current second (s)</td> +</tr> + +<tr> +<td>11</td> + +<td>Hour</td> + +<td>BYTE</td> + +<td>Hour (0 - 23)</td> +</tr> + +<tr> +<td>12</td> + +<td>Minute</td> + +<td>BYTE</td> + +<td>Minute (0 - 59)</td> +</tr> + +<tr> +<td>13</td> + +<td>Second</td> + +<td>BYTE</td> + +<td>Second (0 - 59; 60 = leap)</td> +</tr> + +<tr> +<td>14</td> + +<td>Day</td> + +<td>BYTE</td> + +<td>Date (1 - 31)</td> +</tr> + +<tr> +<td>15</td> + +<td>Month</td> + +<td>BYTE</td> + +<td>Month (1 - 12)</td> +</tr> + +<tr> +<td>16 - 17</td> + +<td>Year</td> + +<td>INTEGER</td> + +<td>Year (4 digit)</td> +</tr> + +<tr> +<td>18</td> + +<td>Receiver Status</td> + +<td>BYTE</td> + +<td>Tracking Status</td> +</tr> + +<tr> +<td>19</td> + +<td>UTC Flags</td> + +<td>BYTE</td> + +<td>Leap Second Flags</td> +</tr> + +<tr> +<td>20</td> + +<td>Reserved</td> + +<td>BYTE</td> + +<td>Contains 0xFF</td> +</tr> + +<tr> +<td>21</td> + +<td>Reserved</td> + +<td>BYTE</td> + +<td>Contains 0xFF</td> +</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. +<h4> +<a NAME="TrackingStatus"></a>Tracking Status Flag Definitions:</h4> +</blockquote> + +<center><table BORDER=0 CELLSPACING=0 WIDTH="712" > +<tr> +<td VALIGN=CENTER WIDTH="5%">Code</td> + +<td VALIGN=CENTER WIDTH="59%">Meaning</td> + +<td>Accuracy</td> + +<td>Receiver Mode</td> +</tr> + +<tr> +<td>0</td> + +<td>Receiver is Navigating</td> + +<td>+/- 1 us</td> + +<td>Self Survey</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">1</td> + +<td VALIGN=CENTER WIDTH="59%">Static 1 Sat. Timing Mode </td> + +<td>+/- 1 us</td> + +<td>1-D Timing</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">2</td> + +<td VALIGN=CENTER WIDTH="59%">Approximate Time</td> + +<td>20 - 50 ms</td> + +<td>Acquisition</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">3</td> + +<td VALIGN=CENTER WIDTH="59%">Startup</td> + +<td>N/A</td> + +<td>Initialization</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">4</td> + +<td VALIGN=CENTER WIDTH="59%">Startup</td> + +<td>N/A</td> + +<td>Initialization</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">5</td> + +<td VALIGN=CENTER WIDTH="59%">Dilution of Position too High </td> + +<td>5 ppm</td> + +<td>Self Survey</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">6</td> + +<td VALIGN=CENTER WIDTH="59%">Static 1 Sat. Timing: Sat. not usable</td> + +<td>5 ppm</td> + +<td>1-D Timing</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">7</td> + +<td VALIGN=CENTER WIDTH="59%">No Satellites Usable</td> + +<td>N/A</td> + +<td>Self Survey</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">8</td> + +<td VALIGN=CENTER WIDTH="59%">Only 1 Satellite Usable</td> + +<td>20 - 50 ms</td> + +<td>Self Survey</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">9</td> + +<td VALIGN=CENTER WIDTH="59%">Only 2 Satellite Usable</td> + +<td>20 - 50 ms</td> + +<td>Self Survey</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">10</td> + +<td VALIGN=CENTER WIDTH="59%">Only 3 Satellites Usable</td> + +<td>20 - 50 ms</td> + +<td>Self Survey</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">11</td> + +<td VALIGN=CENTER WIDTH="59%">Invalid Solution</td> + +<td>N/A</td> + +<td>Error</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">12</td> + +<td VALIGN=CENTER WIDTH="59%">Differential Corrections </td> + +<td>N/A</td> + +<td>N/A</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="5%">13</td> + +<td VALIGN=CENTER WIDTH="59%">Overdetermined Fixes</td> + +<td>+/- 100 ns</td> + +<td>Timing Steady State</td> +</tr> +</table></center> + +<h3> +<b><font size=+0>Packet 8F-0B (Comprehensive Timing Packet)</font></b></h3> + +<center><table BORDER=0 CELLSPACING=0 > +<tr> +<td VALIGN=CENTER WIDTH="9%">Byte</td> + +<td VALIGN=CENTER WIDTH="27%">Item</td> + +<td VALIGN=CENTER WIDTH="16%">Type</td> + +<td VALIGN=CENTER WIDTH="48%">Meaning</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">0</td> + +<td VALIGN=CENTER WIDTH="27%">Sub-Packet ID</td> + +<td VALIGN=CENTER WIDTH="16%">BYTE</td> + +<td VALIGN=CENTER WIDTH="48%">Subcode 0x0B</td> +</tr> + +<tr> +<td VALIGN=TOP WIDTH="9%">1 - 2</td> + +<td VALIGN=TOP WIDTH="27%">Event Count</td> + +<td VALIGN=TOP WIDTH="16%">INTEGER</td> + +<td VALIGN=TOP WIDTH="48%">External event count recorded (0 = PPS)</td> +</tr> + +<tr> +<td VALIGN=TOP WIDTH="9%">3 - 10</td> + +<td VALIGN=TOP WIDTH="27%">UTC / GPS TOW</td> + +<td VALIGN=TOP WIDTH="16%">DOUBLE</td> + +<td VALIGN=TOP WIDTH="48%">UTC / GPS time of week (seconds)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">11</td> + +<td VALIGN=CENTER WIDTH="27%">Date</td> + +<td VALIGN=CENTER WIDTH="16%">BYTE</td> + +<td VALIGN=CENTER WIDTH="48%">Day of Month</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">12</td> + +<td VALIGN=CENTER WIDTH="27%">Month</td> + +<td VALIGN=CENTER WIDTH="16%">BYTE</td> + +<td VALIGN=CENTER WIDTH="48%">Month of Event</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">13 - 14</td> + +<td VALIGN=CENTER WIDTH="27%">Year</td> + +<td VALIGN=CENTER WIDTH="16%">INT</td> + +<td VALIGN=CENTER WIDTH="48%">Year of event</td> +</tr> + +<tr> +<td VALIGN=TOP WIDTH="9%">15</td> + +<td VALIGN=TOP WIDTH="27%">Receiver Mode</td> + +<td VALIGN=TOP WIDTH="16%">BYTE</td> + +<td VALIGN=TOP WIDTH="48%">Receiver operating dimensions: +<br>0: Horizontal (2D) +<br>1: Full Position (3D) +<br>2: Single Satellite (0D) +<br>3: Automatic (2D / 3D) +<br>4: DGPS reference +<br>5: Clock hold (2D) +<br>6: Over determined Clock</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">15 - 17</td> + +<td VALIGN=CENTER WIDTH="27%">UTC Offset</td> + +<td VALIGN=CENTER WIDTH="16%">INTEGER</td> + +<td VALIGN=CENTER WIDTH="48%">UTC Offset value (seconds)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">18 - 25</td> + +<td VALIGN=CENTER WIDTH="27%">Oscillator Bias</td> + +<td VALIGN=CENTER WIDTH="16%">DOUBLE</td> + +<td VALIGN=CENTER WIDTH="48%">Oscillator BIAS (meters)</td> +</tr> + +<tr> +<td VALIGN=TOP WIDTH="9%">26 - 33</td> + +<td VALIGN=TOP WIDTH="27%">Oscillator Drift Rate</td> + +<td VALIGN=TOP WIDTH="16%">DOUBLE</td> + +<td VALIGN=TOP WIDTH="48%">Oscillator Drift (meters / second)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">34 - 37</td> + +<td VALIGN=CENTER WIDTH="27%">Bias Uncertainty</td> + +<td VALIGN=CENTER WIDTH="16%">SINGLE</td> + +<td VALIGN=CENTER WIDTH="48%">Oscillator bias uncertainty (meters)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">38 - 41</td> + +<td VALIGN=CENTER WIDTH="27%">Drift Uncertainty</td> + +<td VALIGN=CENTER WIDTH="16%">SINGLE</td> + +<td VALIGN=CENTER WIDTH="48%">Oscillator bias rate uncertainty (m / sec)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">42 - 49</td> + +<td VALIGN=CENTER WIDTH="27%">Latitude</td> + +<td VALIGN=CENTER WIDTH="16%">DOUBLE</td> + +<td VALIGN=CENTER WIDTH="48%">Latitude in radians</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">50 - 57</td> + +<td VALIGN=CENTER WIDTH="27%">Longitude</td> + +<td VALIGN=CENTER WIDTH="16%">DOUBLE</td> + +<td VALIGN=CENTER WIDTH="48%">Longitude in radians</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">58 - 65</td> + +<td VALIGN=CENTER WIDTH="27%">Altitude</td> + +<td VALIGN=CENTER WIDTH="16%">DOUBLE</td> + +<td VALIGN=CENTER WIDTH="48%">Altitude above mean sea level, in meters</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="9%">66 - 73</td> + +<td VALIGN=CENTER WIDTH="27%">Satellite ID</td> + +<td VALIGN=CENTER WIDTH="16%">BYTE</td> + +<td VALIGN=CENTER WIDTH="48%">SV Id No. of tracked satellites</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><table> +<tr> +<td><u>Description</u></td> + +<td><b>Host</b></td> + +<td></td> + +<td></td> + +<td><b>Palisade </b></td> + +<td></td> + +<td></td> +</tr> + +<tr> +<td><a NAME="PortA"></a><b>Port A</b></td> + +<td><u>DB-9</u></td> + +<td><u>DB-25</u></td> + +<td></td> + +<td><u>RS-232</u></td> + +<td><u>RS-422</u></td> + +<td><u>Palisade Pin</u></td> +</tr> + +<tr> +<td>Receive Data </td> + +<td>2</td> + +<td>3</td> + +<td><--></td> + +<td>Green</td> + +<td>Green / Blue</td> + +<td>8 (T-) & 10 (T+)</td> +</tr> + +<tr> +<td>Request to Send</td> + +<td>7</td> + +<td>4</td> + +<td><--></td> + +<td>Gray</td> + +<td>Gray / White</td> + +<td>6 (R-) & 7 (R+)</td> +</tr> + +<tr> +<td>Signal Ground</td> + +<td>5</td> + +<td>7</td> + +<td><--></td> + +<td>Black</td> + +<td>Black</td> + +<td>9 (GND)</td> +</tr> + +<tr> +<td></td> + +<td></td> + +<td></td> + +<td></td> + +<td></td> + +<td></td> + +<td></td> +</tr> + +<tr> +<td><a NAME="PortB"></a><b>Port B</b></td> + +<td></td> + +<td></td> + +<td></td> + +<td></td> + +<td></td> + +<td></td> +</tr> + +<tr> +<td>Receive Data </td> + +<td>2</td> + +<td>3</td> + +<td><--></td> + +<td>Brown</td> + +<td>Brown / Yellow</td> + +<td>4 (T-) & 5 (T+)</td> +</tr> + +<tr> +<td>Transmit Data</td> + +<td>3</td> + +<td>2</td> + +<td><--></td> + +<td>Violet</td> + +<td>Orange/ Violet</td> + +<td>2 (R-) & 3 (R+)</td> +</tr> + +<tr> +<td>Signal Ground</td> + +<td>5</td> + +<td>7</td> + +<td><--></td> + +<td>Black</td> + +<td>Black</td> + +<td>9 (GND)</td> +</tr> +</table></center> + +<blockquote>Note: If driving the RS-422 inputs on the Palisade single ended, +i.e. using the Green and Gray connections only, does not work on all serial +ports. Use of the Palisade NTP Synchronization Interface Module is recommended.</blockquote> + +<blockquote>The 12 pin connector pinout definition: +<br>Face the round 12 pin connector at the end of the cable, with the notch +turned upwards. +<br>Pin 1 is to the left of the notch. Pins 2 - 8 wrap around the bottom, +counterclockwise to pin 9 on the right of the notch. Pin 10 is just below +the notch. Pins 10 (top), 11 (bottom left) and 12 (bottom right) form a +triangle in the center of the connector.</blockquote> + +<blockquote><a NAME="SIM"></a>Pinouts for the Palisade NTP host adapter +(Trimble PN 37070) DB-25 M connector are as follows:</blockquote> + +<center><table BORDER=0 CELLSPACING=0 WIDTH="682" > +<tr> +<td VALIGN=CENTER WIDTH="12%">DB-25M</td> + +<td VALIGN=CENTER WIDTH="31%">Conductor </td> + +<td VALIGN=CENTER WIDTH="16%">Palisade</td> + +<td VALIGN=CENTER WIDTH="41%">Description</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">1 </td> + +<td VALIGN=CENTER WIDTH="31%">Red</td> + +<td VALIGN=CENTER WIDTH="16%">1</td> + +<td VALIGN=CENTER WIDTH="41%">Power</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">7 </td> + +<td VALIGN=CENTER WIDTH="31%">Black</td> + +<td VALIGN=CENTER WIDTH="16%">9</td> + +<td VALIGN=CENTER WIDTH="41%">Ground</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">9</td> + +<td VALIGN=CENTER WIDTH="31%">Black/White</td> + +<td VALIGN=CENTER WIDTH="16%">12</td> + +<td VALIGN=CENTER WIDTH="41%">PPS -</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">10 </td> + +<td VALIGN=CENTER WIDTH="31%">Green</td> + +<td VALIGN=CENTER WIDTH="16%">8</td> + +<td VALIGN=CENTER WIDTH="41%">Transmit Port A (T-)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">11 </td> + +<td VALIGN=CENTER WIDTH="31%">Brown</td> + +<td VALIGN=CENTER WIDTH="16%">4</td> + +<td VALIGN=CENTER WIDTH="41%">Transmit Port B (T-)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">12 </td> + +<td VALIGN=CENTER WIDTH="31%">Gray</td> + +<td VALIGN=CENTER WIDTH="16%">7</td> + +<td VALIGN=CENTER WIDTH="41%">Receive Port A (R+)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">13</td> + +<td VALIGN=CENTER WIDTH="31%">Orange</td> + +<td VALIGN=CENTER WIDTH="16%">3</td> + +<td VALIGN=CENTER WIDTH="41%">Receive Port B (R+)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">21</td> + +<td VALIGN=CENTER WIDTH="31%">Orange/White</td> + +<td VALIGN=CENTER WIDTH="16%">11</td> + +<td VALIGN=CENTER WIDTH="41%">PPS +</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">22</td> + +<td VALIGN=CENTER WIDTH="31%">Blue</td> + +<td VALIGN=CENTER WIDTH="16%">10</td> + +<td VALIGN=CENTER WIDTH="41%">Transmit Port A (T+)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">23</td> + +<td VALIGN=CENTER WIDTH="31%">Yellow</td> + +<td VALIGN=CENTER WIDTH="16%">5</td> + +<td VALIGN=CENTER WIDTH="41%">Transmit Port B (T+)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">24</td> + +<td VALIGN=CENTER WIDTH="31%">White</td> + +<td VALIGN=CENTER WIDTH="16%">6</td> + +<td VALIGN=CENTER WIDTH="41%">Receive Port A (R-)</td> +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="12%">25</td> + +<td VALIGN=CENTER WIDTH="31%">Violet</td> + +<td VALIGN=CENTER WIDTH="16%">2</td> + +<td VALIGN=CENTER WIDTH="41%">Receive Port B (R-)</td> +</tr> +</table></center> + +<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>(last updated July 29, 1999) +<br> +</body> +</html> diff --git a/contrib/ntp/html/driver3.htm b/contrib/ntp/html/driver3.htm new file mode 100644 index 0000000..47511d8 --- /dev/null +++ b/contrib/ntp/html/driver3.htm @@ -0,0 +1,131 @@ +<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> +</HEAD> +<BODY> + +<H3> +PSTI/Traconex 1020 WWV/WWVH Receiver</H3> + +<HR> +<H4> +Synopsis</H4> +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> +<H4> +Description</H4> +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>The DIP-switches 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. 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>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: +<PRE>ahh:mm:ss.fffs<cr> yy/dd/mm/ddd<cr> +frdzycchhSSFTttttuuxx<cr> + +on-time = first <cr> +hh:mm:ss.fff = hours, minutes, seconds, milliseconds +a = AM/PM indicator (' ' for 24-hour mode) +yy = year (from DIPswitches) +dd/mm/ddd = day of month, month, day of year +s = daylight-saving indicator (' ' for 24-hour mode) +f = frequency enable (O = all frequencies enabled) +r = baud rate (3 = 1200, 6 = 9600) +d = features indicator (@ = month/day display enabled) +z = time zone (0 = UTC) +y = year (5 = 91) +cc = WWV propagation delay (52 = 22 ms) +hh = WWVH propagation delay (81 = 33 ms) +SS = status (80 or 82 = operating correctly) +F = current receive frequency (4 = 15 MHz) +T = transmitter (C = WWV, H = WWVH) +tttt = time since last update (0000 = minutes) +uu = flush character (03 = ^c) +xx = 94 (unknown)</PRE> +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. +<H4> +Monitor Data</H4> +When enabled by the <TT>flag4</TT> fudge flag, every received timecode +is written as-is to the <TT>clockstats</TT> file. +<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.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver30.htm b/contrib/ntp/html/driver30.htm new file mode 100644 index 0000000..8d547b1 --- /dev/null +++ b/contrib/ntp/html/driver30.htm @@ -0,0 +1,153 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859- +1"> + <META NAME="GENERATOR" CONTENT="Mozilla/4.06 [en] (X11; I; FreeBSD +3.0-CURRENT i386) [Netscape]"> + <TITLE>Motorola Oncore GPS Receiver +</TITLE> +</HEAD> +<BODY> + +<H3> +Motorola Oncore GPS receiver</H3> + +<HR> +<H4> +Synopsis</H4> + +Address: 127.127.30.0 +<BR>Reference ID: <TT>GPS</TT> +<BR>Driver ID: ONCORE +<BR>Serial Port: <TT>/dev/cuaa0</TT>; 9600 baud, 8-bits, no parity +<BR>PPS Port: <TT>/dev/xpps0</TT>; <TT>PPS_CAPTUREASSERT</TT> +required, <TT>PPS_OFFSETASSERT</TT> supported. +<H4> +Description</H4> +This driver supports various models of the <A +HREF="http://www.mot.com/AECS/PNSB/products">Motorola Oncore GPS +receivers</A>. as long as they support the <I>Motorola Binary +Protocol</I>. + +<P>The two most interesting version of the Oncore are the "UT+" +and the "Remote" which is a prepackaged "UT+". The evaluation kit +can also be recommended, it interfaces to a PC straightaway, using the +parallel port for PPS input (supported under FreeBSD), and packs the +receiver in a nice and sturdy box. +<BR> +<CENTER><TABLE NOSAVE > +<TR NOSAVE> +<TD NOSAVE><IMG SRC="pic/oncore_utplusbig.gif" HEIGHT=124 +WIDTH=210></TD> + +<TD><IMG SRC="pic/oncore_evalbig.gif" HEIGHT=124 WIDTH=182></TD> + +<TD><IMG SRC="pic/oncore_remoteant.jpg" HEIGHT=188 WIDTH=178></TD> +</TR> + +<TR> +<TD> +<CENTER>UT+ oncore</CENTER> +</TD> + +<TD> +<CENTER>Evaluation kit</CENTER> +</TD> + +<TD> +<CENTER>Oncore Remote</CENTER> +</TD> +</TR> +</TABLE></CENTER> + +<P>The driver requires a standard <TT>PPS</TT> interface for the pulse- +per-second output from the receiver. The serial data stream alone +does not provide precision time stamps (0-50msec variance, according to +the manual), whereas the PPS output is precise down to 50 nsec (1 sigma) +for the UT models. <P>The driver will use the "position hold" mode if +available, with either the receivers built-in site-survey or a similar +algorithm implemented in this driver. +<H4> +Monitor Data</H4> +The driver is quite chatty on stdout if ntpd is run with +debugging. +A manual will be required though. +<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> +Assume GPS receiver is on a mobile platform if set.</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> +<B>Additional Information</B><B></B> +<P>The driver has been developed under FreeBSD, and may still be pretty +FreeBSD centric. Patches are most welcome. +<P><B>Performance</B><B></B> +<P>Really good. With the UT+, the generated PPS pulse is +referenced +to UTC(GPS) with better than 50 nsec (1 sigma) accuracy. The +limiting factor will be the timebase of the computer and the precision +with which you can timestamp the rising flank of the +PPS signal. +Using FreeBSD, a FPGA based Timecounter/PPS interface +and +an ovenized quartz oscillator, that performance has been reproduced. + For +more details on this aspect: <A +HREF="http://phk.freebsd.dk/rover.html">Sub-Microsecond +timekeeping under FreeBSD</A> +<HR> +<ADDRESS> +Poul-Henning Kamp (phk@FreeBSD.org)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver32.htm b/contrib/ntp/html/driver32.htm new file mode 100644 index 0000000..208ad5c --- /dev/null +++ b/contrib/ntp/html/driver32.htm @@ -0,0 +1,42 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=iso8859-1"> +<title>Chrono-log K-series WWVB receiver</title> +</head> + +<body> +<h3>Chrono-log K-series WWVB receiver</h3> + +<hr> +<h4>Synopsis</h4> +Address: 127.127.32.<i>u</i><br> +Reference ID: <TT>CHRONOLOG</TT><br> +Driver ID: <tt>CHRONOLOG</tt><br> +Serial Port: <tt>/dev/chronolog<i>u</i></tt>; 2400 bps, 8-bits, +no parity<br> +<br>Features: <tt>(none)</tt> +<h4>Description</h4> +This driver supports the Chrono-log K-series WWVB receiver. This is a +very old receiver without provisions for leap seconds, quality codes, +etc. It assumes output in the local time zone, and that the C library +mktime()/localtime() routines will correctly convert back and forth +between local and UTC. There is a hack in the driver for permitting +UTC, but it has not been tested. + +<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. +<pre> +Timecode format: Y yy/mm/ddCLZhh:mm:ssCL +Y - year/month/date line indicator +yy/mm/dd -- two-digit year/month/day +C - \r (carriage return) +L - \n (newline) +Z - timestamp indicator +hh:mm:ss - local time +</pre> +<hr> +<address></address> +<!-- hhmts start --> +Last modified: Sun Feb 14 11:57:27 EST 1999 +<!-- hhmts end --> +</body> </html> diff --git a/contrib/ntp/html/driver33.htm b/contrib/ntp/html/driver33.htm new file mode 100644 index 0000000..768cfe7 --- /dev/null +++ b/contrib/ntp/html/driver33.htm @@ -0,0 +1,38 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=iso8859-1"> +<title>Dumb Clock</title> +</head> + +<body> +<h3>Dumb Clock</h3> + +<hr> +<h4>Synopsis</h4> +Address: 127.127.33.<i>u</i><br> +Reference ID: <TT>DUMBCLOCK</TT><br> +Driver ID: <tt>DUMBCLOCK</tt><br> +Serial Port: <tt>/dev/dumbclock<i>u</i></tt>; 9600 bps, 8-bits, +no parity<br> +<br>Features: <tt>(none)</tt> +<h4>Description</h4> +This driver supports a dumb ASCII clock that only emits localtime at a reliable +interval. This has no provisions for leap seconds, quality codes, +etc. It assumes output in the local time zone, and that the C library +mktime()/localtime() routines will correctly convert back and forth +between local and UTC. + +<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. +<pre> +Timecode format: hh:mm:ssCL +hh:mm:ss - local time +C - \r (carriage return) +L - \n (newline) +</pre> +<hr> +<address></address> +<!-- hhmts start --> +Last modified: Sun Feb 14 12:07:01 EST 1999 +<!-- hhmts end --> +</body> </html> diff --git a/contrib/ntp/html/driver34.htm b/contrib/ntp/html/driver34.htm new file mode 100644 index 0000000..e9dcdbc --- /dev/null +++ b/contrib/ntp/html/driver34.htm @@ -0,0 +1,54 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=iso8859-1"> +<title>Dumb Clock</title> +</head> + +<body> +<h3>Ultralink Clock</h3> + +<hr> +<h4>Synopsis</h4> +Address: 127.127.34.<i>u</i><br> +Reference ID: <TT>ULINK</TT><br> +Driver ID: <tt>ULINK</tt><br> +Serial Port: <tt>/dev/ulink<i>u</i></tt>; 9600 bps, 8-bits, +no parity<br> +<br>Features: <tt>(none)</tt> +<h4>Description</h4> +This driver supports the Ultralink Model 320 RS-232 powered WWVB receiver. PDF specs available on <a href="http://www.linuxfoundary.com">www.linuxfoundary.com</a>. While the unit may support them, this driver does nothing with leap seconds, quality codes, etc. (though it probably should). + +<P>Most of this code is originally from refclock_wwvb.c with thanks. Any mistakes are mine. Any improvements are welcome. + +<pre> + The 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 + + Note that this driver does not do anything with the L or T flags. + + The M320 also has a 'U' command which returns UT1 correction information. It + is not used in this driver. + +</pre> +<hr> + <address><a href="mailto:dstrout@linuxfoundary.com">root</a></address> +<!-- hhmts start --> +Last modified: Tue Sep 14 05:53:08 EDT 1999 +<!-- hhmts end --> +</body> </html> diff --git a/contrib/ntp/html/driver4.htm b/contrib/ntp/html/driver4.htm new file mode 100644 index 0000000..4f3abd7 --- /dev/null +++ b/contrib/ntp/html/driver4.htm @@ -0,0 +1,126 @@ +<HTML><HEAD><TITLE> +Spectracom 8170 and Netclock/2 WWVB Receivers +</TITLE></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> + +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>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>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>Format 0 (22 ASCII printing characters): +<br><cr><lf>i ddd hh:mm:ss TZ=zz<cr><lf> + +<p>on-time = first <cr> +<br>i = synchronization flag (' ' = in synch, '?' = out synch) +<br>hh:mm:ss = hours, minutes, seconds</PRE> + +<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>Format 2 (24 ASCII printing characters): +<br>lt;cr>lf>iqyy ddd hh:mm:ss.fff ld + +<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</PRE> + +<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>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>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. + +<H4>Monitor Data</H4> + +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. + +<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>WWVB</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> + +Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> +<HR><ADDRESS>David L. Mills (mills@udel.edu)</ADDRESS></BODY></HTML> diff --git a/contrib/ntp/html/driver5.htm b/contrib/ntp/html/driver5.htm new file mode 100644 index 0000000..edbd045 --- /dev/null +++ b/contrib/ntp/html/driver5.htm @@ -0,0 +1,159 @@ +<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>TrueTime GPS/GOES/OMEGA Receivers +</TITLE> +</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> +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>Most of this code is originally from refclock_wwvb.c with thanks. It +has been so mangled that wwvb is not a recognizable ancestor. +<PRE>Timcode format: ADDD:HH:MM:SSQCL + +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 + + 468-DC GOES Receiver: + GPS-TM/TMD Receiver: + ? +/- 500 milliseconds # +/- 50 milliseconds + * +/- 5 milliseconds . +/- 1 millisecond + space less than 1 millisecond + + OM-DC OMEGA Receiver: + + > +/- 5 seconds + + ? +/- 500 milliseconds # +/- 50 milliseconds + * +/- 5 milliseconds . +/- 1 millisecond + + A-H less than 1 millisecond. Character indicates which +station + is being received as follows: A = Norway, B = Liberia, + C = Hawaii, D = North Dakota, E = La Reunion, F = +Argentina, + G = Australia, H = Japan.</PRE> +The carriage return start bit begins on 0 seconds and extends to 1 bit +time. + +<P>Notes on 468-DC and OMEGA receiver: + +<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>Notes on the 468-DC receiver: + +<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><TT>fudge 127.127.5.0 time1 +0.008 time2 -0.004</TT> + +<P>This corrects the 4 milliseconds advance and 8 milliseconds retard needed. +The software will ask the clock which satellite it sees. + +<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.) +<H4> +Monitor Data</H4> +When enabled by the <TT>flag4</TT> fudge flag, every received timecode +is written as-is to the <TT>clockstats</TT> file. +<H4> +Fudge Factors</H4> + +<DL> +<DT> +<TT>time1 <I>time</I></TT></DT> + +<DD> +Specifies the time offset calibration factor, in seconds and fraction, +to be used for the West satellite, with default 0.0.</DD> + +<DT> +<TT>time2 <I>time</I></TT></DT> + +<DD> +. Specifies the time offset calibration factor, in seconds and fraction, +to be used for the East satellite, 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>TRUE</TT>.</DD> + +<DT> +<TT>flag1 0 | 1</TT></DT> + +<DD> +Silence the clock side of ntpd, just reading the clock without trying to +write to it.</DD> + +<DT> +<TT>flag2 0 | 1</TT></DT> + +<DD> +Generate a debug file /tmp/true%d.</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.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver6.htm b/contrib/ntp/html/driver6.htm new file mode 100644 index 0000000..a728a54 --- /dev/null +++ b/contrib/ntp/html/driver6.htm @@ -0,0 +1,253 @@ +<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>IRIG Audio Decoder II for Sun SPARCstation +</TITLE> +</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 works only on older Sun SPARCstation systems. The new driver described +here uses the stock kernel audio driver and works in SunOS 4.1.3 and Solaris +2.6 versions and probably all versions in between. The new driver requires +no modification of the operating system. 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. +<H4> +Description</H4> +This driver supports the Inter-Range Instrumentation Group (IRIG) standard +time distribution signal using the audio codec native to the Sun SPARCstation. +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 ports on a +Sun SPARCstation <TT>/dev/audio</TT> audio codec device. 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 interfering signals. + +<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>The program processes 8000-Hz mu-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>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>The program performs a number of error checks to protect against overdriven +or underdriven input signal levels, incorrect signal format or improper +hardware configuration. Specifically, if any of the following errors occur +for a timecode, the data are rejected. Secifically, if any of the following +errors occur for a time measurement, the data are rejected. +<OL> +<LI> +The peak carrier amplitude is less than 100 units. This usually means dead +IRIG signal source, broken cable or wrong input port.</LI> + +<BR> +<LI> +The frequency error is greater than +-250 PPM (.025 percent). This usually +means broken codec hardware or wrong codec configuration.</LI> + +<BR> +<LI> +The modulation index is less than 0.5. This usually means overdriven IRIG +signal or wrong IRIG format.</LI> + +<BR> +<LI> +A frame synchronization error has occured. This usually means wrong IRIG +signal format or the IRIG signal source has lost synchronization (signature +control).</LI> + +<BR> +<LI> +A data decoding error has occured. This usually means wrong IRIG signal +format.</LI> + +<BR> +<LI> +The current second of the day is not exactly one greater than the previous +one. This usually means a very noisy IRIG signal or insufficient CPU resources.</LI> + +<BR> +<LI> +An audio codec error (overrun) occured. This usually means insufficient +CPU resources, as sometimes happens with Sun SPARC IPCs when doing something +useful.</LI> +</OL> +Note that additional checks are done elsewhere in the reference clock interface +routines. + +<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. +<H4> +IRIG-B Timecode Format</H4> +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>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: +<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</H4> +The mu-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>The accuracy of the system clock synchronized to the IRIG-B source with +this driver and the <TT>ntpd</TT> daemon is 10-20 microseconds with a Sun +UltraSPARC II and maybe twice that with a Sun SPARC IPC. 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 the documentation. +<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 -d -d on the ntpd command line), the driver +produces one line for each timecode in the following format: +<PRE>00 1 98 23 19:26:52 721 143 0.694 47 20 0.083 66.5 3094572411.00027</PRE> +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 signal +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. +<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> +Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver7.htm b/contrib/ntp/html/driver7.htm new file mode 100644 index 0000000..0394fbf --- /dev/null +++ b/contrib/ntp/html/driver7.htm @@ -0,0 +1,227 @@ +<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>Canadian CHU Radio Modem/Audio Decoder +</TITLE> +</HEAD> +<BODY> + +<H3> +CHU Audio/Modem 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>Serial Port: <TT>/dev/chu<I>u</I></TT>; 300 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 radio +transmissions from Canadian time/frequency station CHU in Ottawa, Ontario. +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 using the <TT>minimuf</TT> and +<TT>icom</TT> programs as propagation conditions change throughout the +day and night. + +<P>This driver replaces an earlier one built by Dennis Ferguson in 1988. +The earlier driver required a special line discipline which preprocessed +the signal in order to improve accuracy and avoid errors. The new driver +includes more powerful algorithms implemented directly in the driver and +requires no line discipline. It decodes the data using a maximum-likelihood +technique which exploits the considerable degree of redundancy available +to maximize accuracy and minimize errors. + +<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-bps modem or modem chip, +as described in the <A HREF="file:///J|/ntp4/html/pps.htm">Pulse-per-second +(PPS) Signal Interfacing</A> page. The driver can be compiled to use this +modem to receive the radio signal and demodulate the data. Alternatively, +the driver can be compiled to use the audio codec of the Sun workstation +or another with compatible audio drivers. In the latter case, the driver +implements the modem using DSP routines, so the radio can be connected +directly to either the microphone on line input port. + +<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 bps 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>Format A bursts are sent at seconds 32 through 39 of the minute in hex +digits + +<P><TT> 6dddhhmmss6dddhhmmss</TT> + +<P>The first ten digits encode a frame marker (<TT>6</TT>) followed by +the day (<TT>ddd</TT>), hour (<TT>hh </TT>in UTC), minute (<TT>mm</TT>) +and the 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>Format B bursts are sent at second 31 of the minute in hex digits + +<P><TT> xdyyyyttaaxdyyyyttaa</TT> + +<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>The <TT>x </TT>is coded + +<P>1 Sign of DUT (0 = +) +<BR>2 Leap second warning. One second will be added. +<BR>4 Leap second warning. One second will be subtracted. +This is not likely to happen in our universe. +<BR>8 Even parity bit for this nibble. + +<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 +bps, 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 <TT>fudge time1</TT>. +<H4> +Debugging aids</H4> +The timecode format used for debugging and data recording includes data +helpful in diagnosing problems with the radio signal and serial connections. +With debugging enabled (<TT>-d -d -d</TT> on the <TT>ntpd </TT>command +line), the driver produces one line for each burst in two formats corresponding +to format A and B. Following is format A: + +<P><TT> n b f s m code</TT> + +<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><TT> 10 38 0 16 9 06851292930685129293</TT> + +<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>When the audio driver is compiled, format A is preceded by the gain +(0-255) and relative signal level (0-9999). The receiver volume control +should be set so that the gain is near the middle of the range 0-255, which +results in a signal level near 1000. + +<P>Following is format B: + +<P><TT> n b s code</TT> + +<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> <TT>11 40 1091891300ef6e76ecff</TT> + +<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>In addition to the above, the reference timecode is updated and written +to the clockstats file and debug score after the last burst received in +the minute. The format is + +<P> <TT> qq yyyy ddd hh:mm:ss nn dd tt</TT> + +<P>where <TT>qq </TT>are the error flags, as described below, <TT>yyyy +</TT>is the year, <TT>ddd </TT>the day, <TT>hh:mm:ss </TT>the time of day, +<TT>nn </TT>the number of format A bursts received during the previous +minute, <TT>dd </TT>the decoding distance and <TT>tt </TT>the number of +timestamps. The error flags are cleared after every update. + +<P>For accuracy better than the low milliseconds, the <TT>fudge time1</TT> +variable can be used to set the propagation delay and compensate for inherent +latencies in the serial port hardware and operating system. This can be +done conveniently using the <TT>minimuf</TT> program. +<H4> +Monitor Data</H4> +When enabled by the <TT>flag4</TT> fudge flag, every received timecode +burst in both format A or format B is written to the <TT>clockstats</TT> +file. +<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>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> +Additional Information + +<P><A HREF="file:///J|/ntp4/html/refclock.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/driver8.htm b/contrib/ntp/html/driver8.htm new file mode 100644 index 0000000..890b6c5 --- /dev/null +++ b/contrib/ntp/html/driver8.htm @@ -0,0 +1,343 @@ +<HTML><HEAD><TITLE> +Generic Reference Driver +</TITLE></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 + +<H4>Description</H4> + +The timecode of these receivers is 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.6. It can be linked directly into +the kernel or loaded via the loadable driver mechanism). This STREAMS +module can be adapted to be able to convert different time code formats. +If the daemon is compiled without the STREAM definition synchronization +will work without the Sun streams module, though accuracy is +significantly degraded. This feature allows to use PARSE also on non Sun +machines. + +<P>The actual receiver status is mapped into various synchronization +states generally used by receivers. The STREAMS module is configured to +interpret the time codes of DCF C51, PZF535, PZF509, GPS166, Trimble SV6 +GPS, ELV DCF7000, Schmid, Wharton 400A and low cost receivers (see list +below). + +<P>The reference clock support in ntp contains the necessary +configuration tables for those receivers. In addition to supporting +several different clock types and 4 devices, the generation a a PPS +signal is also provided as an configuration option. The PPS +configuration option uses the receiver generated time stamps for feeding +the PPS loopfilter control for much finer clock synchronization. + +<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>The use of the PPS option requires receivers with an accuracy of +better than 1ms. + +<P>Fudge factors + +<P>Only two fudge factors are utilized. The time1 fudge factor defines +the phase offset of the synchronization character to the actual time. On +the availability of PPS information the time2 fudge factor defines the +skew between the PPS time stamp and the receiver timestamp of the PPS +signal. This parameter is usually zero, as usually the PPS signal is +believed in time and OS delays should be corrected in the machine +specific section of the kernel driver. time2 needs only be set when the +actual PPS signal is delayed for some reason. The flag1 enables input +filtering. This a median filter with continuous sampling. The flag2 +selects averaging of the samples remaining after the filtering. Leap +second-handling is controlled with the flag3. When set a leap second +will be deleted on receipt of a leap second indication from the +receiver. Otherwise the leap second will be added, (which is the +default). flag3 should never be set. PPS handling is enabled by adding +128 to the mode parameter in the server/peer command. + +<P>ntpq (8) +<P>timecode variable + +<P>The ntpq program can read clock variables command list several +variables. +These hold the following information: refclock_time is the local time +with +the offset to UTC (format HHMM). The currently active receiver flags are +listed in refclock_status. Additional feature flags of the receiver are +optionally listed in parentheses. The actual time code is listed in +timecode. +A qualification of the decoded time code format is following in +refclock_format. The last piece of information is the overall running +time and the accumulated times for the clock event states in +refclock_states. When PPS information is present additional variable are +available. refclock_ppstime lists then the PPS timestamp and +refclock_ppsskew lists the difference between RS232 +derived timestamp and the PPS timestamp. + +<P>Currently, fourteen clock types (devices /dev/refclock-0 - +/dev/refclock-3) are supported by the PARSE driver. +<BR>A note on the implementations: +<UL><li>These implementations where mainly done <B><I>WITHOUT</I></B> +actual access to the hardware. Thus not all implementations provide full +support. The development was done with the help of many souls who had +the hardware and where so kind to borrow me their time an 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="http://www4.informatik.uni-erlangen.de/~kardel">me</A> +(<A HREF="mailto: kardel@acm.org">kardel@acm.org</A>) are welcome as +long as they work within Europe 8-). + +<P>Verified implementations are: +<UL> +<LI> +RAWDCF variants + +<p>These variants are tested for the decoding with my own homegrown +receivers. Interfacing with specific commercial products may involve +some fiddeling with cables. Especially commericial RAWDCF receivers have +a seemingly unlimited number of ways to draw power from the RS232 port +and to encode the DCF77 datastream. You are mainly on your own here +unless i have a sample of the receiver. +<LI> +<A HREF="http://www.meinberg.de">Meinberg clocks</A> + +<p>These implementations are verified by the Meinberg people themselves +and i have access to one of these clocks.</UL> +</UL> +The pictures below refer to the respective clock and where taken from +the vendors web pages. They are linked to the respective vendors. +<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>PZF535/<A +HREF="http://www.meinberg.de/english/pzf509.htm">PZF509 receiver</A> (FM +demodulation/TCXO / 50us)</TT></B> +<BR> +<LI> +<B><TT>server 127.127.8.0-3 mode 1</TT></B> + +<p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> PZF535/<A +HREF="http://www.meinberg.de/english/pzf509.htm">PZF509 +receiver</A> (FM demodulation/OCXO / 50us)</TT></B> +<BR><A HREF="http://www.meinberg.de/english/pzf509.htm"><IMG +SRC="pic/pzf509.jpg" ALT="BILD PZF509" HEIGHT=300 WIDTH=260 +ALIGN=TEXTTOP></A> +<BR> +<LI> +<B><TT>server 127.127.8.0-3 mode 2</TT></B> + +<p><B><TT><A HREF="http://www.meinberg.de">Meinberg </A> DCF U/A +31/<A HREF="http://www.meinberg.de/english/c51.htm">DCF C51 receiver</A> +(AM demodulation / 4ms)</TT></B> +<BR><A HREF="http://www.meinberg.de/english/c51.htm"><IMG +SRC="pic/c51.jpg" ALT="BILD C51" HEIGHT=180 WIDTH=330 ALIGN=TEXTTOP></A> +<BR> +<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> +<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> +<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> +<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> +<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/gps167.htm">GPS166/GPS167 +receiver</A> (GPS / <<1us)</TT></B> +<BR><A HREF="http://www.meinberg.de/english/gps167.htm"><IMG +SRC="pic/gps167.jpg" ALT="BILD GPS167" HEIGHT=300 WIDTH=280 +ALIGN=TEXTTOP></A> +<BR> +<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.htm">clock</A></TT></B> +<BR><A HREF="http://www.igel.de/eigelmn.htm"><IMG SRC="pic/igclock.gif" +HEIGHT=174 WIDTH=200></A> +<BR> +<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.htm">SVeeSix +GPS receiver</A>TAIP protocol (GPS / <<1us)</TT></B> +<BR> +<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.htm">SVeeSix +GPS receiver</A> TSIP protocol (GPS / <<1us) (no kernel support +yet)</TT></B> +<BR><A HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om011.htm"><IMG +SRC="pic/pd_om011.gif" ALT="SVeeSix-CM3" BORDER=0 HEIGHT=100 WIDTH=420 +ALIGN=TEXTTOP></A> +<BR><A HREF="http://www.trimble.com/cgi/omprod.cgi/pd_om006.htm"><IMG +SRC="pic/pd_om006.gif" ALT="Lassen-SK8" BORDER=0 HEIGHT=100 +WIDTH=420></A> +<BR> +<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> +<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.htm">Funkuhr +6021</A></TT></B> +<BR><A HREF="http://www.hopf-time.com/engl/kart6021.htm"><IMG +SRC="pic/fg6021.gif" ALT="DCF77-Interface Board" HEIGHT=207 WIDTH=238 +ALIGN=TEXTTOP></A> +<BR> +<LI> +<B><TT>server 127.127.8.0-3 mode 13</TT></B> + +<p><B><TT>Diem's Computime Radio Clock</TT></B> +<BR> +<LI> +<B><TT>server 127.127.8.0-3 mode 14</TT></B> + +<p><B><TT>RAWDCF receiver (DTR=high/RTS=low)</TT></B> + +<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> +</UL> +<p> +Actual data formats and set-up requirements of the various clocks can be +found in <A HREF="parsedata.htm">NTP PARSE clock data formats</A>. + +<P>The reference clock support 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>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 synchronizations, unless a +disruption in time code transmission is detected (possible power loss). +The trust period is dependent on the receiver oscillator and thus a +function of clock type. This is one of the parameters in the clockinfo +field of the reference clock implementation. This parameter cannot be +configured by ntpdc. + +<P>In addition to the PPS loopfilter control a true PPS hardware signal +can be applied on Sun Sparc stations via the CPU serial ports on the CD +pin. This signal is automatically detected and will be used for offset +calculation. The input signal must be the time mark for the following +time code. (The edge sensitivity can be selected - look into the +appropriate kernel/parsestreams.c for details). Meinberg receivers can +be connected by feeding the PPS pulse of the receiver via a 1488 level +converter to Pin 8 (CD) of a Sun serial zs-port. To select PPS support +the STREAMS driver for PARSE must be loaded and the mode parameter ist +the mode value of above plus 128. If 128 is not added to the mode value +PPS will be detected to be available but it will not be used. For PPS to +be used you MUST add 128 to the mode parameter. + +<P>For the Meinberg GPS166/GPS167 receiver is also a special firmware +release available (Uni-Erlangen). This release should be used for proper +operation. + +<P>The raw DCF77 pulses can be fed via a level converter directly into +Pin 3 (Rx) of the Sun. The telegrams will be decoded an used for +synchronization. AM DCF77 receivers are running as low as $25. The +accuracy is dependent on the receiver and is somewhere between 2ms +(expensive) to 10ms (cheap). Upon bad signal reception of DCF77 +synchronizations will cease as 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. For transmitter shutdowns you +are out of luck unless you have other NTP servers with alternate time +sources available. + +<H4>Monitor Data</H4> + +Clock states statistics are written hourly the the syslog service. +Online information can be found by examining the clock variable via the +ntpq cv command. + +<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 depending on clock type.</DD> + +<DT><TT>time2 <I>time</I></TT></DT> +<DD>Specifies the offset if the PPS signal to the actual time. (PPS fine +tuning).</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 according to current clock type.</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>delete next leap second instead of adding it.</DD> + +<DT> +<TT>flag4 0 | 1</TT></DT> +<DD>Delete next leap second instead of adding it - flag will be re- +defined soon - so don't use it. Statistics are provided by more common +means (syslog, clock variable via ntpq)</DD> + +</DL> + +<H4>Making your own PARSE clocks</H4> + +The parse clock mechanismis deviated from the way other ntp reference +clocks work. For a short description how to build parse reference clocks +see <A HREF="parsenew.htm">making PARSE clocks</A> + +<P>Additional Information + +<P><A HREF="refclock.htm">Reference Clock Drivers</A> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href="mailto:mills@udel.edu"> David L. Mills <mills@udel.edu></a> +</address></body></html> diff --git a/contrib/ntp/html/driver9.htm b/contrib/ntp/html/driver9.htm new file mode 100644 index 0000000..8a11a02 --- /dev/null +++ b/contrib/ntp/html/driver9.htm @@ -0,0 +1,133 @@ +<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> +</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> +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.htm">Line +Disciplines and Streams Modules</A> page. It also requires a <A +HREF="gadget.htm">gadget box</A> and 1-PPS level converter, such as +described in the <A HREF="pps.htm">Pulse-per-second (PPS) Signal +Interfacing</A> page. + +<P>This driver supports all compatible receivers such as the 6-channel +MX4200, MX4200D, and the 12-channel MX9212, MX9012R, MX9112. + +<P> +<A HREF="http://www.leica-gps.com/"> +<IMG SRC="pic/9400n.jpg" ALT="Leica MX9400N Navigator" 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> +Leica MX9400N Navigator. + +<P> + +<H4> +Operating Modes</H4> +This driver supports two modes of operation, static and mobile, controlled +by clock flag 2. + +<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. A DOP-weighted running 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>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. +<H4> +Monitor Data</H4> +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.htm">MX4200 Receiver Data Format</A>. + +<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> +Assume GPS receiver is on a mobile platform if set.</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.htm">Reference Clock Drivers</A> +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/exec.htm b/contrib/ntp/html/exec.htm new file mode 100644 index 0000000..756d987 --- /dev/null +++ b/contrib/ntp/html/exec.htm @@ -0,0 +1,292 @@ +<html><head><title> +Executive Summary - Computer Network Time Synchronization +</title></head><body><H3> +Executive Summary - Computer Network Time Synchronization +</h3> + +<img align=left src=pic/alice12.gif> +from <i>Alice's Adventures in Wonderland</i>, by Lewis Carroll, +illustrations by Sir John Tenniel + +<p>The executive is the one on the left. + +<br clear=left><hr> + +<h4>Introduction</h4> + +<p>The standard timescale used by most nations of the world is Universal +Coordinated Time (UTC), which is based on the Earth's rotation about its +axis, and the Gregorian Calendar, which is based on the Earth's rotation +about the Sun. The UTC timescale is disciplined with respect to +International Atomic Time (TAI) by inserting leap seconds at intervals +of about 18 months. UTC time is disseminated by various means, including +radio and satellite navigation systems, telephone modems and portable +clocks. + +<p>Special purpose receivers are available for many time-dissemination +services, including the Global Position System (GPS) and other services +operated by various national governments. For reasons of cost and +convenience, it is not possible to equip every computer with one of +these receivers. However, it is possible to equip some number of +computers acting as primary time servers to synchronize a much larger +number of secondary servers and clients connected by a common network. +In order to do this, a distributed network clock synchronization +protocol is required which can read a server clock, transmit the reading +to one or more clients and adjust each client clock as required. +Protocols that do this include the Network Time Protocol (NTP), Digital +Time Synchronization Protocol (DTSS) and others found in the literature +(See "Further Reading" at the end of this article.) + +<h4>Protocol Design Issues</h4> + +<p>The synchronization protocol determines the time offset of the server +clock relative to the client clock. The various synchronization +protocols in use today provide different means to do this, but they all +follow the same general model. On request, the server sends a message +including its current clock value or <i>timestamp</i> and the client +records its own timestamp upon arrival of the message. For the best +accuracy, the client needs to measure the server-client propagation +delay to determine its clock offset relative to the server. Since it is +not possible to determine the one-way delays, unless the actual clock +offset is known, the protocol measures the total roundtrip delay and +assumes the propagation times are statistically equal in each direction. +In general, this is a useful approximation; however, in the Internet of +today, network paths and the associated delays can differ significantly +due to the individual service providers. + +<p>The community served by the synchronization protocol can be very +large. For instance, the NTP community in the Internet of 1998 includes +over 230 primary time servers, synchronized by radio, satellite and +modem, and well over 100,000 secondary servers and clients. In addition, +there are many thousands of private communities in large government, +corporate and institution networks. Each community is organized as a +tree graph or <i>subnet</i>, with the primary servers at the root and +secondary servers and clients at increasing hop count, or stratum level, +in corporate, department and desktop networks. It is usually necessary +at each stratum level to employ redundant servers and diverse network +paths in order to protect against broken software, hardware and network +links. +<p>Synchronization protocols work in one or more association modes, +depending on the protocol design. Client/server mode, also called +master/slave mode, is supported in both DTSS and NTP. In this mode, a +client synchronizes to a stateless server as in the conventional RPC +model. NTP also supports symmetric mode, which allows either of two peer +servers to synchronize to the other, in order to provide mutual backup. +DTSS and NTP support a broadcast mode which allows many clients to +synchronize to one or a few servers, reducing network traffic when large +numbers of clients are involved. In NTP, IP multicast can be used when +the subnet spans multiple networks. + +<p>Configuration management can be a serious problem in large subnets. +Various schemes which index public databases and network directory +services are used in DTSS and NTP to discover servers. Both protocols +use broadcast modes to support large client populations; but, since +listen-only clients cannot calibrate the delay, accuracy can suffer. In +NTP, clients determine the delay at the time a server is first +discovered by polling the server in client/server mode and then +reverting to listen-only mode. In addition, NTP clients can broadcast a +special "manycast" message to solicit responses from nearby servers and +continue in client/server mode with the respondents. + +<h4>Computer Clock Modelling and Error Analysis</h4> + +Most computers include a quartz resonator-stabilized oscillator and +hardware counter that interrupts the processor at intervals of a few +milliseconds. At each interrupt, a quantity called <i>tick</i> is added +to a system variable representing the clock time. The clock can be read +by system and application programs and set on occasion to an external +reference. Once set, the clock readings increment at a nominal rate, +depending on the value of <i>tick</i>. Typical Unix system kernels +provide a programmable mechanism to increase or decrease the value of +<i>tick</i> by a small, fixed amount in order to amortize a given time +adjustment smoothly over multiple <i>tick</i> intervals. + +<p>Clock errors are due to variations in network delay and latencies in +computer hardware and software (jitter), as well as clock oscillator +instability (wander). The time of a client relative to its server can be +expressed + +<p><center><i>T</i>(<i>t</i>) = <i>T</i>(<i>t</i><sub>0</sub>) + +<i>R</i>(<i>t - t</i><sub>0</sub>) + 1/2 <i>D</i>(<i>t - +T</i><sub>0</sub>)<sup>2</sup>,</center> + +<p>where <i>t</i> is the current time, <i>T</i> is the time offset at +the last measurement update <i>t</i><sub>0</sub>, <i>R</i> is the +frequency offset and <i>D</i> is the drift due to resonator ageing. All +three terms include systematic offsets that can be corrected and random +variations that cannot. Some protocols, including DTSS, estimate only +the first term in this expression, while others, including NTP, estimate +the first two terms. Errors due to the third term, while important to +model resonator aging in precision applications, are neglected, since +they are usually dominated by errors in the first two terms. + +<p>The synchronization protocol estimates <i>T</i>(<i>t</i><sub>0</sub>) +(and <i>R</i>(<i>t</i><sub>0</sub>), where relevant) at regular +intervals <font face="symbol">t</font> and adjusts the clock to minimize +<i>T</i>(<i>t</i>) in future. In common cases, <i>R</i> can have +systematic offsets of several hundred parts-per-million (PPM) with +random variations of several PPM due to ambient temperature changes. If +not corrected, the resulting errors can accumulate to seconds per day. +In order that these errors do not exceed a nominal specification, the +protocol must periodically re-estimate <i>T</i> and <i>R</i> and +compensate for variations by adjusting the clock at regular intervals. +As a practical matter, for nominal accuracies of tens of milliseconds, +this requires clients to exchange messages with servers at intervals in +the order of tens of minutes. + +<p>Analysis of quartz-resonator stabilized oscillators show that errors +are a function of the averaging time, which in turn depends on the +interval between corrections. At correction intervals less than a few +hundred seconds, errors are dominated by jitter, while, at intervals +greater than this, errors are dominated by wander. As explained later, +the characteristics of each regime determine the algorithm used to +discipline the clock. These errors accumulate at each stratum level from +the root to the leaves of the subnet tree. It is possible to quantify +these errors by statistical means, as in NTP. This allows real-time +applications to adjust audio or video playout delay, for example. +However, the required statistics may be different for various classes of +applications. Some applications need absolute error bounds guaranteed +never to exceeded, as provided by the following correctness principles. + +<h4>Correctness Principles</h4> + +<p>Applications requiring reliable time synchronization such as air +traffic control must have confidence that the local clock is correct +within some bound relative to a given timescale such as UTC. There is a +considerable body of literature that studies these issues with respect +to various failure models such as fail-stop and Byzantine disagreement. +While these models inspire much confidence in a theoretical setting, +most require multiple message rounds for each measurement and would be +impractical in a large computer network such as the Internet. However, +it can be shown that the worst-case error in reading a remote server +clock cannot exceed one-half the roundtrip delay measured by the client. +This is a valuable insight, since it permits strong statements about the +correctness of the timekeeping system. + +<p>In the Probabilistic Clock Synchronization (PCS) scheme devised by +Cristian, a maximum error tolerance is established in advance and time +value samples associated with roundtrip delays that exceed twice this +value are discarded. By the above argument, the remaining samples must +represent time values within the specified tolerance. As the tolerance +is decreased, more samples fail the test until a point where no samples +survive. The tolerance can be adjusted for the best compromise between +the highest accuracy consistent with acceptable sample survival rate. + +<p>In a scheme devised by Marzullo and exploited in NTP and DTSS, the +worst-case error determined for each server determines a correctness +interval. If each of a number of servers are in fact synchronized to a +common timescale, the actual time must be contained in the intersection +of their correctness intervals. If some intervals do not intersect, then +the clique containing the maximum number of intersections is assumed +correct <i>truechimers</i> and the others assumed incorrect +<i>false<i>tick</i>ers</i>. Only the truechimers are used to adjust the +system +clock. + +<h4>Data Grooming Algorithms</h4> + +By its very nature, clock synchronization is a continuous process, +resulting in a sequence of measurements with each of possibly several +servers and resulting in a clock adjustment. In some protocols, crafted +algorithms are used to improve the time and frequency estimates and +refine the clock adjustment. Algorithms described in the literature are +based on trimmed-mean and median filter methods. The clock filter +algorithm used in NTP is based on the above observation that the +correctness interval depends on the roundtrip delay. The algorithm +accumulates offset/delay samples in a window of several samples and +selects the offset sample associated with the minimum delay. In general, +larger window sizes provide better estimates; however, stability +considerations limit the window size to about eight. +<p>The same principle could be used when selecting the best subset of +servers and combining their offsets to determine the clock adjustment. +However, different servers often show different systematic offsets, so +the best statistic for the central tendency of the server population may +not be obvious. Various kinds of clustering algorithms have been found +useful for this purpose. The one used in NTP sorts the offsets by a +quality metric, then calculates the variance of all servers relative to +each server separately. The algorithm repeatedly discards the outlyer +with the largest variance until further discards will not improve the +residual variance or until a minimum number of servers remain. The final +clock adjustment is computed as a weighted average of the survivors. + +<p>At the heart of the synchronization protocol is the algorithm used to +adjust the system clock in accordance with the final adjustment +determined by the above algorithms. This is called the clock discipline +algorithm or simply the discipline. Such algorithms can be classed +according to whether they minimize the time offset or frequency offset +or both. For instance, the discipline used in DTSS minimizes only the +time offset, while the one used in NTP minimizes both time and frequency +offsets. While the DTSS algorithm cannot remove residual errors due to +systematic frequency errors, the NTP algorithm is more complicated and +less forgiving of design and implementation mistakes. + +<p>All clock disciplines function as a feedback loop, with measured +offsets used to adjust the clock oscillator phase and frequency to match +the external synchronization source. The behavior of feedback loops is +well understood and modelled by mathematical analysis. The significant +design parameter is the time constant, or responsiveness to external or +internal variations in time or frequency. Optimum selection of time +constant depends on the interval between update messages. In general, +the longer these intervals, the larger the time constant and vice versa. +In practice and with typical network configurations the optimal poll +intervals vary between one and twenty minutes for network paths to some +thousands of minutes for modem paths. + +<h4>Further Reading</h4> + +<ol> + +<p><li>Cristian, F. Probabilistic clock synchronization. In Distributed +Computing 3, Springer Verlag, 1989, 146-158.</li> + +<p><li>Digital Time Service Functional Specification Version T.1.0.5. +DigitalEquipment Corporation, 1989.</li> + +<p><li>Gusella, R., and S. Zatti. TEMPO - A network time controller for +a distributed Berkeley UNIX system. IEEE Distributed Processing +Technical Committee Newsletter 6, NoSI-2 (June 1984), 7-15. Also in: +Proc. Summer 1984 USENIX (Salt Lake City, June 1984).</li> + +<p><li>Kopetz, H., and W. Ochsenreiter. Clock synchronization in +distributed real-time systems. IEEE Trans. Computers C-36, 8 (August +1987), 933-939.</li> + +<p><li>Lamport, L., and P.M. Melliar-Smith. Synchronizing clocks in the +presence of faults. JACM 32, 1 (January 1985), 52-78.</li> + +<p><li>Marzullo, K., and S. Owicki. Maintaining the time in a +distributed system. ACM Operating Systems Review 19, 3 (July 1985), 44- +54.</li> + +<p><li>Mills, D.L. Internet time synchronization: the Network Time +Protocol. IEEE Trans. Communications COM-39, 10 (October 1991), 1482- +1493. Also in: Yang, Z., and T.A. Marsland (Eds.). Global States and +Time in Distributed Systems, IEEE Press, Los Alamitos, CA, 91-102.</li> +<p><li>Mills, D.L. Modelling and analysis of computer network clocks. +Electrical Engineering Department Report 92-5-2, University of Delaware, +May 1992, 29 pp.</li> + +<p><li>NIST Time and Frequency Dissemination Services. NBS Special +Publication432 (Revised 1990), National Institute of Science and +Technology, U.S. Department of Commerce, 1990.</li> + +<p><li>Schneider, F.B. A paradigm for reliable clock synchronization. +Department of Computer Science Technical Report TR 86-735, Cornell +University, February 1986.</li> + +<p><li>Srikanth, T.K., and S. Toueg. Optimal clock synchronization. JACM +34, 3 (July 1987), 626-645.</li> + +<p><li>Stein, S.R. Frequency and time - their measurement and +characterization (Chapter 12). In: E.A. Gerber and A. Ballato (Eds.). +Precision Frequency Control, Vol. 2, Academic Press, New York 1985, 191- +232, 399-416. Also in: Sullivan, D.B., D.W. Allan, D.A. Howe and F.L. +Walls (Eds.). Characterization of Clocks and Oscillators. National +Institute of Standards and Technology Technical Note 1337, U.S. +Government Printing Office (January, 1990), TN61-TN119.</li> + +</ol> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/extern.htm b/contrib/ntp/html/extern.htm new file mode 100644 index 0000000..d44d243 --- /dev/null +++ b/contrib/ntp/html/extern.htm @@ -0,0 +1,40 @@ +<HTML><HEAD><TITLE> +External Clock Discipline and the Local Clock Driver +</TITLE></HEAD><BODY><H3> +External Clock Discipline and the Local Clock Driver +</H3><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 Lockclock algorithm used with NIST Automated Computer Time Service (ACTS) modem synchronized time. + +<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 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>Control and monitoring functions for the external clock and driver are implemented using the Local Clock (type 1) driver 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, Digital Unix, 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. 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>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>ntp__enable. set/reset by enable command. enables ntp clock discipline + +<p>ntp_control. set during initial configuration if kernel support is available + +kern_enable +Set/reset by enable commandexit + +If this 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 ntp_adjtime(). If this switch is 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. + +pps_update +set in the protocol routine if the prefer peer has survived and has offset less than 128 ms; otherwise set to zero. + +pps_control +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>The ntp_enable and kern_enable 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 pps_update switch is set by the protocol module when it believes the PPS provider source is legitimate and operating within nominals. The ntp_control switch is set during configuration by interrogating the kernel. If both the kern_enable and ntp_control siwitches are set, the daemon disciplines the clock via the kernel and the internal daemon discipline is disabled. + +<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 ntp_adjtime() 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 + + +d PLL/ + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href="mailto:mills@udel.edu"> David L. Mills <mills@udel.edu></a> +</address></body></html> diff --git a/contrib/ntp/html/gadget.htm b/contrib/ntp/html/gadget.htm new file mode 100644 index 0000000..80274535 --- /dev/null +++ b/contrib/ntp/html/gadget.htm @@ -0,0 +1,111 @@ +<html><head><title> +Gadget Box PPS Level Converter and CHU Modem +</title></head><body><h3> +Gadget Box PPS Level Converter and CHU Modem +</h3> + +<img align=left src=pic/gadget.jpg>A Gadget Box built by Chuck Hanavin + +<br clear=left><hr> + +<p><h4>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 as the distribution <a href= +"http://www.eecis.udel.edu/~mills/ntp/ntp">gadget.tar.Z</a>, or by +anonymous FTP from ftp.udel.edu in the <TT>pub/ntp</TT> directory. + +<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 <code>tty_clk</code> and <code>chu_tty</code> line disciplines in +the ntp3 distribution. + +<p>This archive contains complete construction details for the gadget +box, including schematic, parts list and artwork for a two-sided, +printed-circuit board. All files are in PostScript, with the exception +of this file and an information file, which are in ASCII. The artwork is +in the 1:1 scale and is suitable for direct printing on photographic +resist for each side of the board. While a plated-through-holes process +is most convenient, it is possible to bridge the two sides using +soldered wires where necessary. + +<p><h4>Circuit Description</h4> + +<p>Following is a brief functional description of the device. See the +schematic diagram gadget.s01 for reference. The audio output of a +shortwave radio tuned to CHU at 3330, 7335 or 14670 kHz is connected to +J2. A level of at least 30 mV peak-peak is required, such as provided by +the recorder output on many receivers. The input level is adjusted by +potentiometer R8 so that the timecode modulation broadcast at 31-39 +seconds past the minute reliably lights green LED1, but the signals +broadcast during other seconds of the minute do not. + +<p>Opamp U4A provides low-impedance drive for the bridged-tee bandpass +filter U4B. The filter has a bandpass of about 600 Hz at the 6-dB points +and a center frequency of about 2150 Hz. It is designed to avoid +aliasing effects with receivers of relatively wide bandpass +characteristics. The modem itself is implemented by U2 and its +associated circuitry. Resistors R4 and R1 are a 40-dB pad which matches +the filter output to the modem input. U2 is a TTL/EIA level converter +with integral power supply for bipolar signals. The modem output is +available at pin 3 (receive data) of DB25 connector J1. + +<p>The TTL PPS signal is connected via J3 to a retriggerable one-shot +U3A, which generates a TTL pulse of width determined by potentiometer +R7. The pulse width is determined by the bit rate of the attached serial +port. In the common case the width is one bit-time, such as 26 us for +38.4 kbps, for example. This appears to the port as a single start bit +of zero followed by eight bits of ones and a stop bit of one. The second +one-shot U3B generates a 200-ms pulse suitable for driving the amber +LED3 as a visual monitor. The output of U3A is converted to EIA levels +by U1 and appears at pin 12 (secondary receive data) of J1. + +<p>If only the PPS circuit is required, U2 and U4 can be deleted and the +gadget box powered from the EIA modem-control signal at pin 20 (terminal +ready) of J1, assuming this signal is placed in the on (positive +voltage) condition by the computer program. J1 is wired to keep most +finicky UARTs and terminal-driver programs happy. If the CHU circuit is +required, an external 12-volt AC transformer or 9-12-volt DC supply +connected to J4 is required. Red LED2 indicates power is supplied to the +box. + +<p>Files + +<p>Following is a list of files included in this archive. All files are +in PostScript, except the <code>README</code> and +<code>gadget.lst</code> files, which are in ASCII. The files +<code>gadget.s01, gadget.s02</code> and <code>gadget.lst</code> were +generated using the Schema schematic-capture program from Omation. The +printed-circuit files <code>*.lpr</code> were generated using Schema- +PCB, also from Omation. + +<p>Files + +<p><code>README</code> - helpful information +<br><code>gadget.s01</code> - circuit schematic +<br><code>gadget.s02</code> - minibox assembly drawing +<br><code>gadget.lst</code> - net list, pin list, parts list, etc. +<br><code>gen0102.lpr</code> - pcb x-ray diagram +<br><code>art01.lpr</code> - pcb artword side 1 +<br><code>art02.lpr</code> - pcb artwork side 2 +<br><code>adt0127.lpr</code> - pcb assembly drawing +<br><code>dd0124.lpr</code> - pcb drill drawing +<br><code>sm0228.lpr</code> - pcb solder mask (side 2) +<br><code>sst0126.lpr</code> - pcb silkscreen mask (side 1) + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/hints.htm b/contrib/ntp/html/hints.htm new file mode 100644 index 0000000..066b4db --- /dev/null +++ b/contrib/ntp/html/hints.htm @@ -0,0 +1,26 @@ +<html><head><title> +Hints and Kinks +</title></head><body><h3> +Hints and Kinks +</h3><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>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. Bash <a href=http:hints>here</a> for a directory listing. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/hints/a-ux b/contrib/ntp/html/hints/a-ux new file mode 100644 index 0000000..f8c26d2 --- /dev/null +++ b/contrib/ntp/html/hints/a-ux @@ -0,0 +1,195 @@ +------------- +INTRODUCTION: +------------- +Last revision: 06-Jul-1994 + +Included in this distribution of XNTP V3 is a configuration file suitable +for use under Apple's A/UX Version 3.x.x There is also one for A/UX 2.0.1 +but it has not been fully tested. To make the executables follow the steps +outlined below. + +*** NOTE: You must have gcc installed to successfully compile the current +distribution; the native cc supplied with A/UX will NOT correctly compile +this source. See the FAQ in comp.unix.aux for places to obtain gcc from +and how to install it. + +---------------------- +MAKING XNTPD FOR A/UX: +---------------------- + +First, you need to create the makefiles (after you've downloaded the +source, of course): + + % make clean + % make refconf + +After that, you should edit Config.local to make sure that BINDIR is +correct for where you wish the programs to be "installed". The default +(and what I use) is /usr/local/etc. Make sure that DEFS_LOCAL and +CLOCKDEFS are commented out! Presently, only the LOCAL_CLOCK/REFCLOCK +clock is used and supported. + + +After this is done (you should be told that your system is A/UX 3), make +'xntpd' (the options to 'gcc' are held in compilers/aux3.gcc): + + % make + +I do not normally use the `make install' option and so have not verified its +compatibility with A/UX. Rather, I pull out each of the executables and +place them in the locally appropriate locations. + +--------------- +STARTING XNTPD: +--------------- + +At this point you need to set things up so that 'xntpd' is started upon +boot-up. You can do this in 1 of 2 ways: either add entries in /etc/inittab +or, more ideally, create and use an /etc/rc.local file. Since rc.local is +what I recommend, here's how you do it: + +By default, A/UX doesn't have rc.local, so you'll need to add the following to +/etc/inittab: + + net6:2:wait:/etc/syslogd # set to "wait" to run a syslog daemon ++ jmj0:2:wait:/etc/rc.local 1>/dev/syscon 2>&1 # Local stuff + dbg2::wait:/etc/telinit v # turn off init's verbose mode + +Now, the look of a sample /etc/rc.local is as follows: + + #!/bin/sh + : + : rc.local + : + # @(#)Copyright Apple Computer 1987 Version 1.17 of rc.sh on 91/11/08 15:56:21 (ATT 1.12) + + + # Push line discipline/set the device so it will print + /etc/line_sane 1 + echo " " + echo "Entering rc.local..." + + set `/bin/who -r` + if [ "$7" = 2 ] + then + /bin/echo " now setting the time..." + /usr/local/etc/ntpdate -s -b <host.domain> + sleep 5 + # + # start up 'xntpd' if we want + # + if [ -f /etc/ntp.conf ] + then + /bin/echo " setting tick and tickadj..." + /usr/local/etc/tickadj -t 16672 -a 54 + sleep 5 + /bin/echo " starting xntpd..." + /usr/local/etc/xntpd <&- > /dev/null 2>&1 + sleep 5 + fi + # + fi + + echo "Leaving rc.local..." + +There are a few things to notice about the above: + + o When run, 'ntpdate' forces your clock to the time returned by the + host(s) specified by <host.domain> (you'll need to replace this + be the IP address(es) of your timehosts. This is good since it gets + things close to start off with. You can use more than one time + server. + + o 'tickadj' is also called. This does two things: changes the + default value of 'tick' (which the the amount of time, in ms, that + is added to the clock every 1/60 seconds) and changes the value + of 'tickadj' which the the amount that is added or subtracted + from 'tickadj' when adjtime() is called. + + Now Mac clocks are pretty bad and tend to be slow. Sooo, instead of + having A/UX add the default of 16666ms every 1/60th of a second, you + may want it to add more (or less) so that it keeps better time. The + above value works for me but your "best" value may be different and + will likely require some fooling around to find the best value. As a + general rule of thumb, if you see 'xntpd' make a lot of negative clock + adjustments, then your clock is fast and you'll need to _decrease_ + the value of 'tick'. If your adjustments are positive, then you need + to increase 'tick'. To make a guess on how fast/slow your clock is, + use 'ntpdate' to sync your clock. Now watch 'xntpd' and see how it + operates. If, for example, it resets your clock by 1 second every 30 + minutes, then your clock is (1/(30*60)) is about 0.056% off and you'll + need to adjust 'tick' by 16666*0.00056 or about 9 (i.e. 'tick' should + be ~16675 if slow or ~16657 if fast) + + A/UX's default value of 'tickadj' is 1666 which is too big for + 'xntpd'... so it also needs to be adjusted. I like using larger + values then the recommended value of 9 for 'tickadj' (although not + anything near as big as 1666) since this allows for quick slews + when adjusting the clock. Even with semi-large values of 'tickadj' + (~200), getting 5ms (1/200 s) accuracy is easy. + + +Finally, before A/UX and 'xntpd' will work happily together, you need to +patch the kernel. This is due to the fact that A/UX attempts to keep the +UNIX-software clock and the Mac-hardware clock in sync. Neither the h/w or +the s/w clock are too accurate. Also, 'xntpd' will be attempting to adjust +the software clock as well, so having A/UX muck around with it is asking +for headaches. What you therefore need to do is tell the kernel _not_ to +sync the s/w clock with the h/w one. This is done using 'adb'. The +following is a shell script that will do the patch for you: + + #! /bin/sh + adb -w /unix <<! + init_time_fix_timeout?4i + init_time_fix_timeout?w 0x4e75 + init_time_fix_timeout?4i + $q + ! + +This must be done _every_ time you create a new kernel (via newconfig or +newunix) or else 'xntpd' will go crazy. + +-------- +HISTORY: +-------- + +John Dundas was the original porter of 'xntpd' and a lot of the additions +and A/UX-ports are from him. I got involved when I wanted to run 'xntpd' +on jagubox. It was also around this time that the base-patchlevel of +'xntpd' changed relatively (the so-called "jones" version). Since then, +I've been maintaining 'xntpd' for A/UX for the xntp development team + +The original kernel patch (which patched 'time_fix_timeout') was from +Richard Todd. I suggest patching 'init_time_fix_timeout' which prevents +'time_fix_timeout' from even being called. + +---------------- +TECHNICAL NOTES: +---------------- + + o As configured (see machines/aux3), 'xntpd' will log messages via syslogd + using the LOC_LOCAL1 facility. I would suggest the following in + /etc/syslog.conf: + + local1.notice /usr/adm/ntpd-syslog + + o As mentioned above, the clocks on A/UX and Macs are kinda bad. Not + only that, but logging in and out of the MacOS mode as well as + extensive floppy use causes A/UX to drop and lose clock interupts + (these are sent every 1/60th of a second). So, if you do these + activities a lot, you find out that you lose about 300ms of time + (i.e., you become 300ms slow). 'xntpd' default way of handling this + is to called 'settimeofday()' and step the clock to the correct + time. I prefer having 'xntpd' slew the clock back into line by + making gradual adjustments to the clock over a coupla minutes + or so. It's for this reason that SLEWALWAYS is defined in + include/ntp_machine.h for SYS_AUX3. It's also for this reason than + I like larger values of 'tickadj'. + +Good luck! If you have problems under A/UX feel free to contact me (e-mail +is preferred). +-- + Jim Jagielski | "That is no ordinary rabbit... 'tis the + jim@jagubox.gsfc.nasa.gov | most foul, cruel and bad-tempered + NASA/GSFC, Code 734.4 | rodent you ever set eyes on" + Greenbelt, MD 20771 | Tim the Enchanter diff --git a/contrib/ntp/html/hints/aix b/contrib/ntp/html/hints/aix new file mode 100644 index 0000000..e53beff --- /dev/null +++ b/contrib/ntp/html/hints/aix @@ -0,0 +1,76 @@ +Problem with recent ANSI compilers + +On some systems, including AIX, the compiler quits on the ntp_refclock.c +file when processing the refclock_report() routine. The problem, which +is eithre a feature or a bug, has to do with an unwanted promotion of +the u_char argument to an int and a failure of the compiler to recognize +the preceding prototype. A workaround is to use ANSI syntax to delare +the arguments. Since ANSI compilers are not universally available, this +syntax can't be used in the stock distribution. + +(Message # 60: 2884 bytes, New) +Date: Sat, 19 Aug 1995 13:20:50 -0400 +From: "R. Bernstein" <rocky@panix.com> +Newsgroups: comp.protocols.time.ntp +to: mills@udel.edu +return-receipt-to: rocky@panix.com +Subject: time and AIX 3.2.5 raw tty bug + +This posting isn't strictly about NTP, any program that may stop the +clock or set the clock backwards is subject to the AIX 3.2.5 bug. + +On AIX 3.2.5, there is a bug in the tty driver for a raw device which +may crash the box under certain conditions: basically a read() on a +raw tty in effect, a character was read but not as many as specified +by VMIN when a read timeout occurred. VTIME specifies the timeout. See +the AIX manual page on termios.h or that include file. for Information +on VMIN (or MIN) VTIME (or TIME). + +A remedy other than to not use raw tty's is to apply patch U435110. + +Details of the problem report follow. + +> ABSTRACT: +> IX43779: TRAP IN PSX_TIMEO +> +> ORIGINATING DETAILS: +> Stacktrace shows: +> IAR: 01460214 posixdd:psx_timeo + 8bf4: ti 4,r12,0x0 +> *LR: 014601a0 posixdd:psx_timeo + 8b80 +> 00212c60: 014604f4 posixdd:psx_timer + 8ed4 +> 00212cc0: 0144b74c ttydd:tty_do_offlevel + 4284 +> 00212d20: 000216fc .i_offlevel + 8c +> 00212d70: 00021d78 .i_softint + c8 +> 00001004: 00008714 .finish_interrupt + 80 +> +> RESPONDER SUMMARY: +> AIX asserted in psx_timeo(). Reason for the assert was that +> the current time was behind psx_ctime. Since this state +> can occur when the current time is changed after a character +> is received but before the VTIME interbyte timer pops, we +> should not assert on this. +> +> RESPONDER CONCLUSION: +> Removed the requirement that current time > psx_ctime by +> adding a new L_ntimersub macro that is used instead of the +> ntimersub macro in time.h. Also added a test for (current +> time - psx_ctime) being negative, in that case we do not +> adjust the new timeout. +> +> Reported to Correct a PTF in Error: NO +> Reported as a Highly pervasive problem: NO +> +> PE Apar?: NoPE +> Hiper Apar?: NoHiper +> Status: CLOSED PER +> Component Name: AIX V3 FOR RS/6 +> Version: 320 +> Component ID: 575603001 +> Submitted: 94/05/03 +> Closed: 94/05/05 +> ChangeTeam: TX2527 +> +> APAR FIXED BY: U431696 U432151 U432844 U432870 U432979 +> U433049 U433081 U433459 U433876 U433906 U434598 U434453 +> U434672 U434737 U435110 + diff --git a/contrib/ntp/html/hints/bsdi b/contrib/ntp/html/hints/bsdi new file mode 100644 index 0000000..3b8bc38 --- /dev/null +++ b/contrib/ntp/html/hints/bsdi @@ -0,0 +1,65 @@ +hints/bsdi + +Author: Bdale Garbee, bdale@gag.com +Last revision: 27Oct94 (Paul Vixie) + +Included in this distribution of XNTP is a configuration file suitable +for use with BSDI's BSD/OS 1.1 (formerly BSD/386 1.1). On this system, +the "cc" command is GCC 1.4x rather than PCC or GCC 2.x. It is imperative +that "cc" be used since it predefines the symbol __bsdi__; if you want to +use another compiler you will need to add -D__bsdi__ to catch the various +#ifdef's required for this system. + +The Kinemetrics/Truetime GPS-TM/TMD driver is known to work on this system. +The GPS-805 and GOES should also work fine. Hell, they should all work fine +but it's hard to test very many locally. + +Due to BNR2's strict interpretation of POSIX and XNTP's use of SIGIO, BSD/OS +can only handle one refclock per daemon. We're working this out with the +system architects. + +The config file is machine/bsdi, and the following steps should be all that +are required to install and use the bits. + +Note that you will need GNU sed; the version supplied with BSD/OS 1.1 loops +endlessly during "make refconf". Likewise you should get GNU make, which +the instructions below assume that you have put in /usr/local/bin/gnumake. + +To build the software: + + rm -f Config.local + gnumake refconf + gnumake MAKE=gnumake + +To install the software: + + gnumake install + + This will place all of the executables in /usr/local/etc. The config + file is expected to be /usr/local/etc/xntp.conf and the key file for + the optional authentication is /etc/ntp.keys. + + Craft a config file and a key file, and put them in the right places. + There is information on how to do this elsewhere in the documentation, + the only thing I'll mention is that I put the drift file in + /var/log/ntp.drift, and the authdelay on my 486DX/50 system is + 0.000064. Your mileage will vary, learn to use the authspeed tools + if you're going to authenticate. + + In the file /etc/rc.local, make sure that the invocation of ntpd is + commented out, and add an invocation of xntpd. Here's what I'm using: + + echo -n 'starting local daemons:' + + if [ -f /etc/ntp.keys -a -f /usr/local/etc/xntp.conf ]; then + echo -n ' xntpd'; /usr/local/etc/xntpd + fi + + #XXX# echo -n ' ntpd'; /usr/libexec/ntpd -t + +At this point, you should be good to go. Try running /usr/local/etc/xntpd and +using ntpq or xntpdc to see if things are working, then pay attention the next +time you reboot to make sure that xntpd is being invoked, and use ntpq or +xntpdc again to make sure all is well. + +Enjoy! diff --git a/contrib/ntp/html/hints/changes b/contrib/ntp/html/hints/changes new file mode 100644 index 0000000..177e562 --- /dev/null +++ b/contrib/ntp/html/hints/changes @@ -0,0 +1,13 @@ +Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de> (xntpd/refclock_parse.c): + - Added support to supply power from RS232 with CLOCK_RAWDCF. + Known to work with Linux 1.2. + - Made Linux ignore parity errors with CLOCK_RAWDCF. + +Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de> (parse/util/dcfd.c): + - Removed conflicting prototype for Linux (sscanf) + - Corrected spelling error + - Made Linux ignore parity errors. + - Added support to supply power from RS232 with CLOCK_RAWDCF. + +Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de> (parse/util/testdcf.c): + - Made Linux ignore parity errors. diff --git a/contrib/ntp/html/hints/decosf1 b/contrib/ntp/html/hints/decosf1 new file mode 100644 index 0000000..bc4ce0b --- /dev/null +++ b/contrib/ntp/html/hints/decosf1 @@ -0,0 +1,40 @@ +Some major changes were necessary to make xntp v3 run on the DEC Alpha +hardware running DEC OSF/1. All "long" and "u_long" declarations and +casts in the code were changed to "LONG" and "U_LONG" and a new header +file (include/ntp_types.h) was added. The new header file defines +LONG as int and U_LONG as u_int for the Alpha hardware and as long +and u_long for anything else. A couple of #ifs where changed in +ntpq and xntpdc to get the result of a signal defined correctly. The +Config.decosf1 file built the programs here with no problems. + +I don't have a radio clock here, so none of that code has been tested. +I have run xntpd, xntpdc, xntpres, ntpq, ntpdate, and tickadj under +DEC OSF/1 v1.2-2 (BL10). + +Mike Iglesias Internet: iglesias@draco.acs.uci.edu +University of California, Irvine BITNET: iglesias@uci +Office of Academic Computing uucp: ...!ucbvax!ucivax!iglesias +Distributed Computing Support phone: (714) 856-6926 + +Support for NTP Version 2 is included with the current OSF/1 release. If +you are upgrading to NTP Version 3 with this distribution, you should not +use the xntpd or ntpq programs that come with the OSF/1 release. The +older programs should be replaced by the newer programs of the same name, +either in situ or via a link to a tranquil spot like /usr/local/bin. The +make install script in the this distribution don't work due to a silly +install program incompatibility, so you will need to copy the programs by +hand. + +Don't use the setup utility to install or configure the xntpd installation, +as it will cheerfully clobber your painstakingly crafted ntp.conf program. +However, assuming you put this file in /etc/ntp.conf, you can use the +/sbin/init.d/xntpd script to start and stop the daemon. + +This distribution compiles with nominal mumur with the stock cc compiler +that comes with OSF/1. + +Dave Mills +Electrical Engineering Department +Unibergisty of Delabunch +mills@udel.edu + diff --git a/contrib/ntp/html/hints/decosf2 b/contrib/ntp/html/hints/decosf2 new file mode 100644 index 0000000..e4a8828 --- /dev/null +++ b/contrib/ntp/html/hints/decosf2 @@ -0,0 +1,54 @@ +Problems with DEC OSF/1 V2.0 + +Compilation using gcc fails with ntp_config.c. The problem is an apparent +error in the /usr/include/sys/procset.h and /usr/include/sys/wait.h +include files. + +cowbird:/usr/include/sys# diff -c wait.h.orig wait.h +*** wait.h.orig Tue Feb 22 02:41:38 1994 +--- wait.h Thu Aug 25 14:52:57 1994 +*************** +*** 298,304 **** + #else + + _BEGIN_CPLUSPLUS +! extern int waitid(idtype_t, id_t, siginfo_t *, int); + _END_CPLUSPLUS + #endif /* _NO_PROTO */ + +--- 298,304 ---- + #else + + _BEGIN_CPLUSPLUS +! extern int waitid(idtype_t, pid_t, siginfo_t *, int); + _END_CPLUSPLUS + #endif /* _NO_PROTO */ + +cowbird:/usr/include/sys# diff -c procset.h.orig procset.h +*** procset.h.orig Tue Feb 22 02:41:44 1994 +--- procset.h Thu Aug 25 14:43:52 1994 +*************** +*** 86,95 **** + */ + + idtype_t p_lidtype; /* The id type for the left set. */ +! id_t p_lid; /* The id for the left set. */ + + idtype_t p_ridtype; /* The id type of for right set. */ +! id_t p_rid; /* The id of the right set. */ + } procset_t; + + +--- 86,95 ---- + */ + + idtype_t p_lidtype; /* The id type for the left set. */ +! pid_t p_lid; /* The id for the left set. */ + + idtype_t p_ridtype; /* The id type of for right set. */ +! pid_t p_rid; /* The id of the right set. */ + } procset_t; + +Also, if using gcc from the freeware disk, either replace syscall.h +in the directory /usr/local/lib/gcc-lib/alpha-dec-osf1/2.3.3/include +or replace with a link to /usr/include/sys/syscall.h. diff --git a/contrib/ntp/html/hints/hpux b/contrib/ntp/html/hints/hpux new file mode 100644 index 0000000..1640d05 --- /dev/null +++ b/contrib/ntp/html/hints/hpux @@ -0,0 +1,158 @@ +Last update: Sun Mar 13 15:05:31 PST 1994 + +This file hopefully describes the whatever and however of how to get xntp +running on hpux 7.0 and later s300. s400, s700, and s800. + +First off, all the standard disclaimers hold here ... HP doesn't have anthing +to do with this stuff. I fool with it in my spare time because we use it and +because I like to. We just happen to have a lot of HP machines around here :-) +Xntpd has been in use here for several years and has a fair amount of mileage +on various HP platforms within the company. I can't really guarantee bug fixes +but I'd certainly like to hear about bugs and I won't hestitate to look at +any fixes sent to me. + +Now lets talk OS. If you don't have 7.0 or later, pretty much hang it up now. +This stuff has run here on pretty much everything from 8.0 upward on s300, +s700, and s800. It is known to run on 7.0 s300/s400 but all reports are +from the field and not my personal experience. + +If you are lucky enough to have a s300 or s400 with 9.03, then you no longer +have to worry about adjtimed as HP-UX now has adjtime(2). The rest of you +will have to wait on 10.0 which will have adjtime(2) and a supported though +a bit older version of xntpd. + +Next, let me explain a bit about how this stuff works on HP-UX's that do not +have adjtime(2). The directory adjtime contains libadjtime.a and the adjtimed +daemon. Instead of the adjtime(2) system call, we use a library routine to +talk to adjtimed thru message queues. Adjtimed munges into /dev/kmem and +causes the clock to skew properly as needed. PLEASE NOTE that the adjtime +code provided here is NOT a general replacement for adjtime(2) ... use of +this adjtime(3)/adjtimed(8) other than with xntpd may yield very odd results. + +What to do to get this stuff running ? + + * If you are running an OS less than 10.0 or do not have a s300/s400 + with 9.03 or better + -> cd machines + -> vi hpux + -> (change -DSYS_HPUX=? to match whatever you are running [7,8,9]) + -> cd .. + + * Say "make makeconfig" + + * Say "make", sit back for a few minutes. + + * cd authstuff + * Say "./authcert < certdata" and check the output. Every line should + end with "OK" ... if not, we got trouble. + * Now try "./authspeed auth.samplekeys". What we want to + remember here is the "authentication delay in CPU time" + * cd .. + + * Say "make install" + + * I'd suggest reading the xntp docs about now :-) ... seriously !! + + * One thing I have added to this version of xntpd is a way to select + config files if you are sharing /usr/local thru NFS or whatever. + If the file /usr/local/etc/xntp.conf happens to be a directory, the + files in that directory are searched until a match is found. The + rules for a match are: + + 1. Our hostname + 2. default.<machine id> (as in default.375 or default.850) + 3. default + + * Ok, make sure adjtimed is running (just start it up for now with + "/usr/local/etc/adjtimed"). Using -z as an option will get you + a usage message. + + * Now start up xntpd and watch it work. + + * Make sure that adjtimed gets started at boot right before xntpd. + We do this in /etc/netbsdsrc. They must both run as root !! + +Possible problems ? + + * On some 320's and 835's we have had to run adjtimed with "-p 45" or + so to get rid of syslog messages about "last adjust did not finish". + + * At 9.0, there is a problem with DIAGMON (patch available from the + response center) which causes it to delete the message queue that + adjtimed/xntpd use to communicate. (see next note for result) + + * Xntpd has been known to get really ticked off when adjtime() fails + which is usually only while running the emulation code on HP-UX. + When it gets mad, it usually jumps the clock into never never land. + Possible reasons for this are adjtimed being killed or just never + started or adjtimed being completely swapped out on a really busy + machine (newer adjtimed try to lock themselves in memory to prevent + this one). + +Anything else ... just drop me a line at ken@sdd.hp.com + +Received: from louie.udel.edu by huey.udel.edu id aa14418; 15 Jun 95 9:19 EDT +Received: from host5.colby.edu (host-05.colby.edu) by host-04.colby.edu with ESMTP (1.37.109.15/Colby 1.1) + id AA165442355; Thu, 15 Jun 1995 09:19:16 -0400 +Received: by host5.colby.edu (1.37.109.15/Colby 1.1) + id AA056252339; Thu, 15 Jun 1995 09:18:59 -0400 +Date: Thu, 15 Jun 1995 09:18:59 -0400 (EDT) +From: "Jeff A. Earickson" <jaearick@colby.edu> +To: Mills@huey.udel.edu +Subject: More minor bugs in xntp3.4s +In-Reply-To: <9506150022.aa12727@huey.udel.edu> +Message-Id: <Pine.HPP.3.91.950615083549.4557A-100000@host5.colby.edu> +Mime-Version: 1.0 +Content-Type: TEXT/PLAIN; charset=US-ASCII + +Dave, + After reading the hpux hints file, I realized I didn't install or +start adjtimed. In the course of doing this, I discovered that: + +--> $(TOP) is not defined in adjtime/Makefile, so "make install" can't + find the install.sh script. + +--> "make install" from the main Makefile never goes into the adjtime + directory, so I added the following two lines into the install + target of the main Makefile: + + @echo installing from adjtime + @cd adjtime && $(MAKE) $(MFLAGS) MFLAGS="$(MFLAGS)" MAKE="$(MAKE)" install + +This twiddle may not be right for all systems, but it got adjtimed +installed for me. + + You might also want to add to the hpux hints file that one way to +fire things up at boot time is to add the following lines to the localrc +function of /etc/rc: + + #---daemons for Network Time Protocol (version 3.4s) + #---note that adjtimed is only needed for HP-UX 9.X, not 10.0 + #---adjtimed must be running or xntpd won't work right... + if [ -x /usr/local/bin/adjtimed ]; then + /usr/local/bin/adjtimed -r & echo -n ' adjtimed' + if [ -x /usr/local/bin/xntpd ]; then + /usr/local/bin/xntpd & echo -n ' xntpd' + fi + fi + +I discovered that the "-r" option of adjtimed is needed to clear out any +trash from a previous execution of it. Otherwise adjtimed quietly dies +and leaves xntpd in the lurch... + +Thanks for the help. + +** Jeff A. Earickson, Ph.D PHONE: 207-872-3659 +** Senior UNIX Sysadmin, Information Technology EMAIL: jaearick@colby.edu +** Colby College, 4214 Mayflower Hill, FAX: 207-872-3555 +** Waterville ME, 04901-8842 + +On Thu, 15 Jun 1995 Mills@huey.udel.edu wrote: + +> Jeff, +> +> Read the hpux file in the hints directory. +> +> Dave +> + diff --git a/contrib/ntp/html/hints/linux b/contrib/ntp/html/hints/linux new file mode 100644 index 0000000..b06a36a --- /dev/null +++ b/contrib/ntp/html/hints/linux @@ -0,0 +1,5 @@ +The kernel PLL interface is broken, I know. +Update RSN. + + Torsten + (duwe@informatik.uni-erlangen.de) diff --git a/contrib/ntp/html/hints/notes-xntp-v3 b/contrib/ntp/html/hints/notes-xntp-v3 new file mode 100644 index 0000000..ba027f2 --- /dev/null +++ b/contrib/ntp/html/hints/notes-xntp-v3 @@ -0,0 +1,119 @@ +Notes for NTP Version 3 + +This version operates in much the same manner as Version 2 with the +following changes and additions: + +1. The protocol machinery operates in conformance with the RFC1305 NTP + Version 3 specification. The most visible characteristic of this + version is that the poll intervals for all polls, even selected + ones, is significantly increased. This is especially desirable when + serving a large client population. This implementation supports + previous versions as non-configured peers; for version-2 configured + peers a "version 2" keyword should be included on the "peer" line. + +2. The configuration file has a new keyword: statfile <file>, where + <file> is the name of a statistics file." When present, each clock + update generates an entry of the form: + + <day> <sec>.<frac> <addr> <status> <offset> <delay> <disp> + + where <day> is the modified Julian day, <sec>.<frac> is the time of + day, <addr> is the peer address and <status> is the peer status. + The <offset>, <delay> and <disp> are the measured offset, delay and + dispersion, respectively, of the peer clock relative to the local + clock. About once per day the current file is closed and a new one + created with names <file>.<gen>, where <gen> starts at one and + increments for each new generation. + +3. A number of additional platforms are supported. See ./Config file + for details. + +4. A driver for the TrueTime 468DC GOES Synchronized Clock is + included. This driver (refclock_goes.c) should also work for other + TrueTime radio clocks, since all use the same format. + +5. A replacement driver for the Spectracom 8170 WWVB Synchronized + Clock is included. This driver (refclock_wwvb.c) (a) does not + require a 1-pulse-per-second signal, (b) supports both format 0 + (original 8170) and format 2 (Netclock/2 and upgraded 8170), (c) + can be connected to more than one computer and (d) automatically + compensates for all serial baud rates. + +6. A driver for the German time/frequency station DCF77 is included. + This requires a special STREAMS module. + +7. In Version 2 special line-discipline modules were required for the + CHU and WWVB drivers. This code continues to work in Version 3, + although it is no longer needed for the WWVB driver. However, this + code does not work under STREAMS, as used in SunOS 4.1.1. + Equivalent STREAMS modules are supplied with Version 3. + +8. Support for an external 1-pulse-per-second (pps) signal is + provided. The signal is connected to a serial port (see + xntpd/ntp_loopfilter.c for details). When present the leading edge + of the pulse establishes the on-time epoch within an interval + established by the selected radio clock or other NTP time server. + Use of the pps is indicated when the tattletale displayed by ntpq + changes from "*" to "o". + +9. The clock-selection and poll-update procedures have been modified + slightly in order to achieve better performance on high speed LANs + with compromise in performance on typical WANs. + +10. In order to comply with U.S. Commerce Department regulations, the DES + encryption routine lib/authdes.c cannot be exported. For exportable + versions of this distribution a DES-encrypted version of this routine + lib/authdes.c.des is included along with an unencrypted version + lib/authdes.c.export, which allows normal operation, but without the + NTP authentication feature. Further information is available in the + lib/authdes.c.export file. + +11. As an alternative to the DES-based authentication mechanism, an + implementation of the RSA Message Digest 5 algorithm is provided. + (see applicable copyright information in the library files). + +12. A driver for the Magnavox MX4200 GPS clock. + +13. A STREAMS module which captures carrier-detect data-lead transitions to + connect a precision source of 1-pps, yet avoid the ugly overhead in the + usual STREAMS processing. See the ppsclock subdirectory. + +14. Support for the Apple A/UX operating system and enhanced support for the + Hewlet-Packard HP/UX operating system. See the various README and Config + files for further information. + +See the COPYRIGHT file for authors and copyright information. Note that some +modules in this distribution contain copyright information that supersedes +the copyright information in that file. + +If I missed something or neglected to give due credit, please advise. + +David L. Mills +University of Delaware +31 May 1992, amended 23 July 1992, 25 October 1992 + +Bugs and notes + +A bug in the original tty_clk_STREAMS.c module has been fixed. + +The poll-interval randomization feature of poll_update (in +xntpd/ntp_proto.c) has been extended to apply when the poll interval is +increased, as well as reduced. This spreads the update messages in time +and helps avoid unpleasant bursts of messages. + +In the clock_select algorithm the peers selected for combining are +limited to those survivors at the lowest stratum, not the entire list. +This helps avoid whiplash when large numbers of peers are at the same +stratum. + +The number formerly displayed by ntpq as "compliance" is now the time +constant of integration. + +The DNS resolver xntpd/ntp_intres.c is now integrated into xntpd, making +configuration of multiple hosts easier. + +System and peer event are now written to the system log at priority +LOG_INFO. + +The leap-second code was fixed to avoid broadcasting leap warnings on +all except the last day of June and December. diff --git a/contrib/ntp/html/hints/parse b/contrib/ntp/html/hints/parse new file mode 100644 index 0000000..d252351 --- /dev/null +++ b/contrib/ntp/html/hints/parse @@ -0,0 +1,105 @@ +Compilation: + Usual thing: rm -f Config.local ; make for vanilla + make refconf for reference clock (e. g. DCF77) + +Directory contents: + + hints/PARSE - this file + + xntpd/refclock_parse.c + - reference clock support for DCF77/GPS in xntp + parse/parse.c + - Reference clock data parser framework + parse/parse_conf.c + - parser configuration (clock types) + parse/clk_meinberg.c + - Meinberg clock formats (DCF U/A 31, PZF 535, GPS166) + parse/clk_schmid.c + - Schmid receiver (DCF77) + parse/clk_rawdcf.c + - 100/200ms pulses via 50 Baud line (DCF77) + parse/clk_dcf7000.c + - ELV DCF7000 (DCF77) + parse/clk_trimble.c + - Trimble SV6 GPS receiver + + If you want to add new clock types please check + 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. + + parse/Makefile.kernel + - *SIMPLE* makefile to build a loadable STREAMS + module for SunOS 4.x / SunOS 5.x systems + + parse/parsestreams.c + - SUN Streams module (loadable) for radio clocks + This streams module is designed for SunOS 4.1.X. + + parse/parsesolaris.c + - SUN Streams module (loadable) for radio clocks. + This streams module is designed for SunOS 5.x + Beware this is still new - so it might crash + your machine (we have seen it working, though). + + parse/parsetest.c + - simple test program for STREAMS module. Its so simple, + that it doesn't even set TTY-modes, thus they got to + be correct on startup - works for Meinberg receivers + + parse/testdcf.c + - test program for raw DCF77 (100/200ms pulses) + receivers + + include/parse.h - interface to "parse" module and more + include/parse_conf.h + - interface to "parse" configuration + + include/sys/parsestreams.h + - STREAMS specific definitions + + scripts/support + - scripts (perl & sh) for statistics and rc startup + the startup scripts are used in Erlangen for + starting the daemon on a variety of Suns and HPs + and for Reference Clock startup on Suns + These scripts may or may not be helpful to you. + +Supported clocks: + Meinberg DCF U/A 31 + Meinberg PZF535/TCXO (Software revision PZFUERL 4.6) + Meinberg PZF535/OCXO (Software revision PZFUERL 4.6) + Meinberg GPS166 (Software version for Uni-Erlangen) + ELV DCF7000 (not recommended - casual/emergency use only) + Conrad DCF77 receiver (email: time@informatik.uni-erlangen.de) + + level converter + TimeBrick (email: time@informatik.uni-erlangen.de) + Schmid Receiver Kit + Trimble SV6 GPS receiver + +Addresses: + Meinberg Funkuhren + Auf der Landwehr 22 + 31812 Bad Pyrmont + Germany + Tel.: 05281/20 18 + FAX: 05281/60 81 80 + + ELV Kundenservice + Postfach 1000 + 26787 Leer + Germany + Tel.: 0491/60 08 88 + + Walter Schmidt + Eichwisrain 14 + 8634 Hombrechtikon + Switzerland + +If you have problems mail to: + + time@informatik.uni-erlangen.de + +We'll help (conditions permitting) + diff --git a/contrib/ntp/html/hints/refclocks b/contrib/ntp/html/hints/refclocks new file mode 100644 index 0000000..17e7643 --- /dev/null +++ b/contrib/ntp/html/hints/refclocks @@ -0,0 +1,35 @@ +This is a short overview for the reference clocks currently supported +by xntp V3. (Ultimate wisdom can be obtained from xntpd/refclock_*.c +this file was derived from that information - unfortunately some comments +in the files tend to get stale - so use with caution) + +Refclock address Type +127.127.0.x no clock (fails to configure) +127.127.1.x local clock - use local clock as reference +127.127.2.x no clock (fails to configure) +127.127.3.x PSTI 1010/1020 WWV Clock +127.127.4.x SPECTRACOM WWVB receiver 8170 and Netclock/2 +127.127.5.x Kinimetric Truetime 468-DC GOES receiver +127.127.6.x IRIG audio decode (Sun & modified BSD audio driver) +127.127.7.x CHU Timecode (via normal receiver & Bell 103 modem) +127.127.8.x PARSE (generic driver for a bunch of DCF/GPS clocks + can be extended for other clocks too) + 8.0-3 Meinberg PZF535/TCXO + 8.4-7 Meinberg PZF535/OCXO + 8.8-11 Meinberg DCF U/A 31 + 8.12-15 ELV DCF7000 + 8.16-19 Walter Schmid DCF receiver (Kit) + 8.20-23 Conrad DCF77 receiver module + level converter (Kit) + 8.24-27 TimeBrick (limited availability ask + time@informatik.uni-erlangen.de) + 8.28-31 Meinberg GPS166 + 8.32-35 Trimble SV6 GPS receiver +127.127.9.x MX4200 GPS receiver +127.127.10.x Austron 2201A GPS Timing Receiver +127.127.11.x Kinemetrics Truetime OM-DC OMEGA Receiver +127.127.12.x KSI/Odetecs TPRO-S IRIG-B / TPRO-SAT GPS +127.127.13.x Leitch: CSD 5300 Master Clock System Driver +127.127.14.x MSFEES +127/127.15.x TrueTime GPS/TM-TMD +127.127.16.x Bancomm GPS/IRIG Ticktock +127.127.17.x Datum Programmable Time System diff --git a/contrib/ntp/html/hints/rs6000 b/contrib/ntp/html/hints/rs6000 new file mode 100644 index 0000000..8561ac2 --- /dev/null +++ b/contrib/ntp/html/hints/rs6000 @@ -0,0 +1,56 @@ +15.7.1993 +xntp3 compiles now again on AIX. I have disabled prototyping and added +the switch -D_NO_PROTO which disables prototyping in the system include +files. + +Matthias Ernst maer@nmr.lpc.ethz.ch +-------------------------------------------------------------------------------- +Xntp version 3 now support the cc compiler for AIX. +The Config.aix will now use cc by default. You can still compile xntp +with the bsd compiler by changing "COMP= cc" to "COMP= bsdcc" and +and removing the "-DSTUPID_SIGNAL" option from the "DEFS" option. + +xntp and tickadj was also modified so that the value of tickadj is read +form the kernel and can be set by tickadj. For now I would not set +tickadj below 40 us. + +Bill Jones +jones@chpc.utexas.edu +------------------------------------------------------------------------------- + +This is a modified version of xntp version 3 for the RS6000. It works for +AIX 3.2 and these are the same changes as have been applied tothe version 2 +implementation of xntp. It works fine for us but I have not tested all of +the features, especially the local clock support for the RS6000 is not tested +at all. + +Matthias Ernst, ETH-Zuerich, Switzerland - maer@nmr.lpc.ethz.ch + +-------------------------------------------------------------------------------- + +Here the original README.rs6000 for the version 2 implementation: + +A hacked version of xntp for the IBM RS/6000 under AIX 3.1 can be found +in xntp.rs6000.tar.Z. [ if still available at all - Frank Kardel 93/12/3 ] + +This will not work on older versions of AIX due to a kernel bug; to find +out whether you have the kernel bug, compile and run testrs6000.c (see +comments in the code for instructions). + +xntp and testrs6000 require "bsdcc" to compile. This is simply another +entry point into the xlc compiler with various options set for BSD +compatibility. If your system does not have bsdcc, do the following: + +link /bin/bsdcc to /bin/xlc + +put the following into /etc/xlc.cfg: + +* BSD compatibility +bsdcc: use = DEFLT + crt = /lib/crt0.o + mcrt = /lib/mcrt0.o + gcrt = /lib/gcrt0.o + libraries = -lbsd, -lc + proflibs = -L/lib/profiled,-L/usr/lib/profiled + options = -H512,-T512, -qlanglvl=extended, -qnoro, -D_BSD, -D_NONSTD_TYPES, -D_NO_PROTO, -tp,-B/lib/ + diff --git a/contrib/ntp/html/hints/sco.htm b/contrib/ntp/html/hints/sco.htm new file mode 100644 index 0000000..2273faa --- /dev/null +++ b/contrib/ntp/html/hints/sco.htm @@ -0,0 +1,39 @@ +<HTML> +<HEAD> + <TITLE>SCO Unix hints</TITLE> +</HEAD> +<BODY> + <H1>SCO Unix hints</H1> + + <H2>Older SCO Unix versions</H2> + <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>. + + <H2>Compiling NTP</H2> + <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. + + <H2>Running NTP</H2> + <P> + Run "tickadj -As" after every reboot to set the variables + "clock_drift" and "track_rtc" to the right values. + <P> + Run "ntpd" with a high negative nice-value, i.e. + "nice --19 ntpd" for best results. + + <H2>More information</H2> + <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> + <A HREF="mailto:kees@echelon.nl">Kees Hendrikse</A>, January 1999 +</BODY> +</HTML> diff --git a/contrib/ntp/html/hints/sgi b/contrib/ntp/html/hints/sgi new file mode 100644 index 0000000..5e4f7de --- /dev/null +++ b/contrib/ntp/html/hints/sgi @@ -0,0 +1,74 @@ +adjtime, tick and tickadj: +-------------------------- + +The SGI value for HZ is 100 under Irix 4, with the system clock running +in nominal mode (ftimer off), so the value for tick is 10000 usec. +Tickadj is a bit more tricky because of the behaviour of adjtime(), +which seems to try to perform the correction over 100-200 seconds, with +a rate limit of 0.04 secs/sec for large corrections. Corrections of +less than 0.017 seconds generally complete in less than a second, +however. + +Some measured rates are as follows: + + Delta Rate (sec/sec) + + > 1 0.04 + 0.75 0.04 + 0.6 0.004 + 0.5 0.004 + 0.4 0.0026 + 0.3 0.0026 + 0.2 0.0013 + 0.1 0.0015 + 0.05 0.0015 + 0.02 0.0003 + 0.01 0.015 +Strange. Anyway, since adjtime will complete adjustments of less than +17msec in less than a second, whether the fast clock is on or off, I +have used a value of 150usec/tick for the tickadj value. + +Fast clock: +----------- + +I get smoother timekeeping if I turn on the fast clock, thereby making +the clock tick at 1kHz rather than 100Hz. With the fast clock off, I +see a sawtooth clock offset with an amplitude of 5msec. With it on, +the amplitude drops to 0.5msec (surprise!). This may be a consequence +of having a local reference clock which spits out the time at exactly +one-second intervals - I am probably seeing sampling aliasing between +that and the machine clock. This may all be irrelevant for machines +without a local reference clock. Fiddling with the fast clock doesn't +seem to compromise the above choices for tick and tickadj. + +I use the "ftimer" program to switch the fast clock on when the system +goes into multiuser mode, but you can set the "fastclock" flag in +/usr/sysgen/master.d/kernel to have it on by default. See ftimer(1). + +timetrim: +--------- + +Irix has a kernel variable called timetrim which adjusts the system +time increment, effectively trimming the clock frequency. Xntpd could +use this rather than adjtime() to do it's frequency trimming, but I +haven't the time to explore this. There is a utility program, +"timetrim", in the util directory which allows manipulation of the +timetrim value in both SGI and xntpd native units. You can fiddle with +default timetrim value in /usr/sysgen/master.d/kernel, but I think +that's ugly. I just use xntpd to figure out the right value for +timetrim for a particular CPU and then set it using "timetrim" when +going to multiuser mode. + +Serial I/O latency: +------------------- + +If you use a local clock on an RS-232 line, look into the kernel +configuration stuff with regard to improving the input latency (check +out /usr/sysgen/master.d/[sduart|cdsio]). I have a Kinemetrics OM-DC +hooked onto /dev/ttyd2 (the second CPU board RS-232 port) on an SGI +Crimson, and setting the duart_rsrv_duration flag to 0 improves things +a bit. + + +12 Jan 93 +Steve Clift, CSIRO Marine Labs, Hobart, Australia (clift@ml.csiro.au) diff --git a/contrib/ntp/html/hints/solaris.html b/contrib/ntp/html/hints/solaris.html new file mode 100644 index 0000000..8595fbf --- /dev/null +++ b/contrib/ntp/html/hints/solaris.html @@ -0,0 +1,139 @@ +<HTML> +<HEAD> +<TITLE>Solaris hints and kinks</TITLE> +</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> +Proper operation of ntp under Solaris requires 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.htm#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/hints/solaris.xtra.4023118 b/contrib/ntp/html/hints/solaris.xtra.4023118 new file mode 100644 index 0000000..84c5d15 --- /dev/null +++ b/contrib/ntp/html/hints/solaris.xtra.4023118 @@ -0,0 +1,36 @@ + Bug Id: 4023118 + Category: kernel + Subcategory: other + State: integrated + Synopsis: sun4u doesn't keep accurate time + Description: + +[ bmc, 12/20/96 ] + +The clock on a sun4u drifts unacceptably. On a typical 143 mHz Ultra, +the clock took 1.0001350 seconds to count 1 second. While this may seem +trivial, it adds up quickly. In this case, the TOD chip will have to +pull the clock forward by 2 seconds every 4 hours and 7 minutes. +This drift rate is so high, that the clock is close to being too broken +for NTP to guarantee correctness (in order for NTP's mechanism to work, +it must be assured that the local clock drifts no more than 20 ms in 64 +seconds; this particular 143 mHz Ultra will drift by nearly 9 ms in that +period). This problem has been reproduced on virtually all sun4u +classes. + +The fundamental problem lies in the kernel's perception of ticks per +second. The PROM is responsible for determining this figure exactly, +and the kernel extracts it into the variable cpu_tick_freq. On sun4u's, +this number is disconcertingly round: 143000000, 167000000, 248000000, +etc. Indeed, a simple experiment revealed that these numbers were +quite far from the actual ticks per second. Typical was the 143 mHz +Ultra which was discovered to tick around 142,980,806 (+/- 10) times +per second. + + Work around: + + Integrated in releases: s297_27 + Duplicate of: + Patch id: + See also: + Summary: diff --git a/contrib/ntp/html/hints/solaris.xtra.4095849 b/contrib/ntp/html/hints/solaris.xtra.4095849 new file mode 100644 index 0000000..8d3ce80 --- /dev/null +++ b/contrib/ntp/html/hints/solaris.xtra.4095849 @@ -0,0 +1,74 @@ + Bug Id: 4095849 + Category: kernel + Subcategory: syscall + State: evaluated + Synopsis: time_constant value >6 with PLL in use leads to integer divide + zero trap panic + Description: +If the time_constant parameter is 7 or higher, and the phase-lock looping model +is in use, the system will take a "integer divide zero trap" panic in +the clock routine as soon as the time_offset becomes non-zero. + +time_constant defaults to 0. The only place it is set is in the ntp_adjtime +system call, from the 'constant' element of the timex structure argument. + + Work around: +Never set the constant element of the timex structure passed to ntp_adjtime to +a value larger than 6. + +satish.mynam@Eng 1998-04-30 +1. Use Sun's version of NTP software instead of PD version. This problem +is not seen with Sun's NTP version (which is mostly eqivalent to PD NTP 3.4 +plus some Sun's local functionality futures). + +2. Workaround for the public domain NTP version ONLY: + ===================================================== +The workaround for public domain NTP version is to disable the +KERNEL_PLL from the NTP code. This way ntp_Adjtime() system call is +totally bypassed without sacrificing any of the functionality of the +NTP. The only hit you might see is the way kernel precision timminig +is done without the PLL algorithm in the kernel. + + The easiest way to disable ntp_adjtime option is(without changing + any makefiles or other config files) to disable the KERNEL_PLL + value in the ./config.h file. + +After doing a ./configure for probing for all the necessary tools(compilers, +os version, libraries), please comment out KERNEL_PLL macro in +the ./config.h file. This will disable the KERNEL_PLL part of the source +code and the newly obtained xntpd is just similar to the old one but it +does not use ntp_adjtime() system call. This prevents it from panic'ng +the kernel. + +/*#define KERNEL_PLL 1*/ + +I complied a new xntpd binary this way and it does nothave any ntp_adjtime() +related stuff. + +Default: +======= +/net/divya/export/home/mynam/public_domain/ntp/xntp3-5.92/xntpd>strings +xntpd | +grep ntp_adjtime +354:adj_frequency: ntp_adjtime failed: %m +357:loop_config: ntp_adjtime() failed: %m +435:get_kernel_info: ntp_adjtime() failed: %m + +With KERNEL_PLL disabled in config.h file +-======================= + +/net/divya/export/home/mynam/public_domain/ntp/xntp3-5.92/xntpd>strings +xntpd.nopll | grep ntp_adjtime + + Integrated in releases: + Duplicate of: + Patch id: + See also: 4133517 + Summary: +If the time_constant parameter is 7 or higher, and the phase-lock looping model +is in use, the system will take a "integer divide zero trap" panic in +the clock routine as soon as the time_offset becomes non-zero. + +time_constant defaults to 0. The only place it is set is in the ntp_adjtime +system call, from the 'constant' element of the timex structure argument. +---------------------------------------------------------------------------- diff --git a/contrib/ntp/html/hints/solaris.xtra.S99ntpd b/contrib/ntp/html/hints/solaris.xtra.S99ntpd new file mode 100644 index 0000000..33662ba --- /dev/null +++ b/contrib/ntp/html/hints/solaris.xtra.S99ntpd @@ -0,0 +1,20 @@ +#!/bin/sh +if [ $1 = "start" ]; then + if [ -x /usr/local/bin/xntpd ]; then + echo "Starting NTP daemon, takes about 1 minute... " + # The following line is unnecessary if you turn off + # dosynctodr in /etc/system. + /usr/local/bin/tickadj -s + /usr/local/bin/ntpdate -v server1 server2 + sleep 5 + /usr/local/bin/xntpd + fi +else + if [ $1 = "stop" ]; then + pid=`/usr/bin/ps -e | /usr/bin/grep xntpd | /usr/bin/sed -e 's/^ *//' -e 's/ .*//'` + if [ "${pid}" != "" ]; then + echo "Stopping Network Time Protocol daemon " + /usr/bin/kill ${pid} + fi + fi +fi diff --git a/contrib/ntp/html/hints/solaris.xtra.patchfreq b/contrib/ntp/html/hints/solaris.xtra.patchfreq new file mode 100644 index 0000000..9600881 --- /dev/null +++ b/contrib/ntp/html/hints/solaris.xtra.patchfreq @@ -0,0 +1,85 @@ +#!/bin/ksh + +# +# File: patchfreq +# Author: Bryan Cantrill (bmc@eng.sun.com), Solaris Performance +# Modified: Sat Apr 26 04:00:59 PDT 1997 +# +# This is a little script to patch a 5.5 or 5.5.1 kernel to get around +# the cpu_tick_freq inaccuracy. Before running this script, one must +# know the true frequency of one's CPU; this can be derived by NTP, +# or by observing the clock relative to the time-of-day chip over a +# long period of time (the TOD will pull system time when it drifts +# by more than two seconds). +# +# Patching a kernel can render a machine unbootable; do not run this +# script unless you are prepared to accept that possibility. It +# is advisable to have a backout path (e.g. net booting, an alternate +# boot disk, an installation CD) should your machine fail to boot. +# +# This is not a product of Sun Microsystems, and is provided "as is", +# without warranty of any kind expressed or implied including, but not +# limited to, the suitability of this script for any purpose. +# + +if [ $# -eq 0 ]; then + echo "Usage: $0 cpu_tick_freq [ alternate_kernel ]" + exit 1 +fi + +cpu_tick_freq=$1 +kernel=/platform/sun4u/kernel/unix + +if [ $# -eq 2 ]; then + kernel=$2 +fi + +if [ ! -w $kernel ]; then + echo "$0: Cannot open $kernel for writing." + exit 1 +fi + +arch=`echo utsname+404?s | adb $kernel | cut -d: -f2` + +if [ ! $arch = "sun4u" ]; then + echo "Patch only applies to sun4u" + exit 1 +fi + +rel=`echo utsname+202?s | adb $kernel | cut -d: -f2` + +if [ ! $rel = "5.5" ] && [ ! $rel = "5.5.1" ]; then + echo "Patch only applies to 5.5 or 5.5.1..." + exit 1 +fi + +nop="1000000" # nop +store_mask="ffffe000" # mask out low 13 bits +store="da256000" # st %o5, [%l5 + offset] + +instr=`echo setcpudelay+34?X | adb $kernel | cut -d: -f 2 | nawk '{ print $1 }'` + +if [ $instr = $nop ]; then + echo "Instruction already patched..." +else + let masked="(16#$store_mask & 16#$instr) - 16#$store" + if [ $masked -ne 0 ]; then + echo "Couldn't find instruction to patch; aborting." + exit 1 + fi + + if ! echo setcpudelay+34?W $nop | adb -w $kernel 1> /dev/null + then + echo "adb returned an unexpected error; aborting." + fi +fi + +echo "Patching cpu_tick_freq to $cpu_tick_freq..." + +if ! echo cpu_tick_freq?W 0t$cpu_tick_freq | adb -w $kernel 1> /dev/null; then + echo "adb returned an unexpected error; aborting." + exit 1 +fi + +echo "$kernel successfully patched." +exit 0 diff --git a/contrib/ntp/html/hints/sun4 b/contrib/ntp/html/hints/sun4 new file mode 100644 index 0000000..424fa18 --- /dev/null +++ b/contrib/ntp/html/hints/sun4 @@ -0,0 +1,15 @@ +Notes on CPU clock oscillator tolerance with SunOS 4.1.1 and 4.1.3 + +A bug in SunOS 4.1.1 results in the kernel time losing 1 microsecond +per tick of the system clock. The bug was fixed (bugid 1094383) for +SunOS 4.1.1 and corrected in SunOS 4.1.3. The easiest way to fix this +is to replace the 4.1.1 binary clock.o with the corresponding 4.1.3 +binary. Without this change it is necessary to use the tickadj program +included in this distribution with the -t 9999 option. + +The tickadj option will work in all cases except when the kernel has +been modified to correct the CPU clock oscillator frequency using a +1-pps signal from a precision source. The bugfix must be installed for +this wrinkle to work properly. + +Dave Mills (mills@udel.edu) diff --git a/contrib/ntp/html/hints/svr4-dell b/contrib/ntp/html/hints/svr4-dell new file mode 100644 index 0000000..2c92f8a --- /dev/null +++ b/contrib/ntp/html/hints/svr4-dell @@ -0,0 +1,8 @@ +Notes on the DELL SVR4. + +You should use -DSETTIMEOFDAY_BROKEN. + +Philip.Gladstone@mail.citicorp.com + +(XXX But there is no checking for SETTIMEOFDAY_BROKEN in the code) + diff --git a/contrib/ntp/html/hints/svr4_package b/contrib/ntp/html/hints/svr4_package new file mode 100644 index 0000000..b9f5ca3 --- /dev/null +++ b/contrib/ntp/html/hints/svr4_package @@ -0,0 +1,33 @@ +Date: Wed, 12 Apr 1995 12:42:03 +0100 +Message-ID: <513.797686923@concurrent.co.uk> +From: Andy Chittenden <asc@concurrent.co.uk> + +Dave + +Here is a uuencoded, compressed tar file. The only file I've +changed is Makefile - I've included the full file rather than diffs. +There are some new files as well: + + xntp shell script that starts up ntp during boot up + (the packaging stuff creates links to it so it comes + up at run level 2). As with all svr4 start/stop + scripts, it takes one parameter which is either + start or stop. It assumes that ntp.conf is in + /etc/inet/ntp.conf (where it should be on svr4 + machines). + prototype describes the file contents of the package. + You might like to review its contents to + see whether you want to include any other + files or remove some. NB I've made the man + pages go into 1m as they should on svr4. + preinstall runs before installation takes place. It + ensures that ntp is down if it is up before + installing a replacement package + postinstall starts up ntp after package installation. + preremove brings down ntp before removing the package. + +You create a package using "make package". This creates a file +called xntp.pkg. To install this package, you use +"pkgadd -d `pwd`/xntp.pkg xntp". This will start up ntp if +/etc/inet/ntp.conf exists. If you don't want the package anymore, use +"pkgrm xntp". I have tested this on Solaris 2.4. diff --git a/contrib/ntp/html/hints/todo b/contrib/ntp/html/hints/todo new file mode 100644 index 0000000..e0e5ffa --- /dev/null +++ b/contrib/ntp/html/hints/todo @@ -0,0 +1,4 @@ +Ulrich Windl <Ulrich.Windl@rz.uni-regensburg.de>: + Any change in a source file in the lib directory causes all files to + be recompiled (because the objects are removed). Add a better rule for + make to update the library. Maybe just remove "-rm -f $?". diff --git a/contrib/ntp/html/hints/vxworks.html b/contrib/ntp/html/hints/vxworks.html new file mode 100644 index 0000000..4df83c5 --- /dev/null +++ b/contrib/ntp/html/hints/vxworks.html @@ -0,0 +1,18 @@ +<HTML> +<HEAD> + <TITLE>vxWorks Port of NTP</TITLE> +</HEAD> +<BODY LINK="#00008B" VLINK="#8B0000"> + +<H1>VxWorks port of NTP </H1> + +<P>Please look at the <A HREF="../vxworks.htm">Vxworks file</A> in the html directory.
+ +<P>Casey Crellin</A> <BR>
+<A HREF="mailto:casey@csc.co.za">casey@csc.co.za</A> </P>
+ +<P><BR> +</P> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/hints/winnt b/contrib/ntp/html/hints/winnt new file mode 100644 index 0000000..6fd7c84 --- /dev/null +++ b/contrib/ntp/html/hints/winnt @@ -0,0 +1,207 @@ +------------- +INTRODUCTION: +------------- +Last revision 27 July 1999 Version 4.0.95. + +This version compiles under WINNT with Visual C 6.0. + +Greg Brackley and Sven Dietrich + +Significant changes: +-Visual Studio v6.0 support +-Winsock 2.0 support +-Use of I/O completion ports for sockets and comm port I/O +-Removed the use of multimedia timers (from ntpd, others need removing) +-Use of waitable timers (with user mode APC) and performance counters to fake getting a better time +-Trimble Palisade NTP Reference Clock support +-General cleanup, prototyping of functions +-Moved receiver buffer code to a separate module (removed unused members from the recvbuff struct) +-Moved io signal code to a separate module + +Compiling Instructions: +1. Requires Perl to be installed, and the Perl environment variable to be set correctly +2. Open the .\ports\winnt\ntp.dsw +3. Batch build of all debug projects compile + + +Last revision: 20-Oct-1996 + +This version corrects problems with building the XNTP +version 3.5-86 distribution under Windows NT. + +The following files were modified: + blddbg.bat + bldrel.bat + include\ntp_machine.h + xntpd\ntp_unixclock.c + xntpd\ntp_refclock.c + scripts\wininstall\build.bat + scripts\wininstall\setup.rul + scripts\wininstall\readme.nt + scripts\wininstall\distrib\ntpog.wri + html\hints\winnt (this file) + +In order to build the entire Windows NT distribution you +need to modify the file scripts\wininstall\build.bat +with the installation directory of the InstallShield +software. Then, simply type "bldrel" for non-debug +or "blddbg" for debug executables. + + + +Greg Schueman + <schueman@acm.org> + + +Last revision: 07-May-1996 + +This set of changes fixes all known bugs, and it includes +several major enhancements. + +Many changes have been made both to the build environment as +well as the code. There is no longer an ntp.mak file, instead +there is a buildntall.bat file that will build the entire +release in one shot. The batch file requires Perl. Perl +is easily available from the NT Resource Kit or on the Net. + +The multiple interface support was adapted from Larry Kahn's +work on the BIND NT port. I have not been able to test it +adequately as I only have NT servers with one network +interfaces on which to test. + +Enhancements: +* Event Logging now works correctly. +* Version numbers now work (requires Perl during build) +* Support for multiple network interface cards (untested) +* NTP.CONF now default, but supports ntp.ini if not found +* Installation procedure automated. +* All paths now allow environment variables such as %windir% + +Bug fixes: +* INSTSRV replaced, works correctly +* Cleaned up many warnings +* Corrected use of an uninitialized variable in XNTPD +* Fixed ntpdate -b option +* Fixed ntpdate to accept names as well as IP addresses + (Winsock WSAStartup was called after a gethostbyname()) +* Fixed problem with "longjmp" in xntpdc/ntpdc.c that + caused a software exception on doing a Control-C in xntpdc. + A Cntrl-C now terminates the program. + +See below for more detail: + + Note: SIGINT is not supported for any Win32 application including + Windows NT and Windows 95. When a CTRL+C interrupt occurs, Win32 + operating systems generate a new thread to specifically handle that + interrupt. This can cause a single-thread application such as UNIX, + to become multithreaded, resulting in unexpected behavior. + + +Possible enhancements and things left to do: +* Reference clock drivers for NT (at least Local Clock support) +* Control Panel Applet +* InstallShield based installation, like NT BIND has +* Integration with NT Performance Monitor +* SNMP integration +* Fully test multiple interface support + + +Known problems: +* bug in ntptrace - if no Stratum 1 servers are available, + such as on an IntraNet, the application crashes. + + + + +Last revision: 12-Apr-1995 + + +This NTPv3 distribution includes a sample configuration file and the project +makefiles for WindowsNT 3.5 platform using Microsoft Visual C++ 2.0 compiler. +Also included is a small routine to install the NTP daemon as a "service" +on a WindowsNT box. Besides xntpd, the utilities that have been ported are +ntpdate and xntpdc. The port to WindowsNT 3.5 has been tested using a Bancomm +TimeServe2000 GPS receiver clock that acts as a strata 1 NTP server with no +authentication (it has not been tested with any refclock drivers compiled in). +Following are the known flaws in this port: +1) currently, I do not know of a way in NT to get information about multiple + network interface cards. The current port uses just one socket bound to + INADDR_ANY address. Therefore when dealing with a multihomed NT time server, + clients should point to the default address on the server (otherwise the + reply is not guaranteed to come from the same interface to which the + request was sent). Working with Microsoft to get this resolved. +2) There is some problem with "longjmp" in xntpdc/ntpdc.c that causes a + software exception on doing a Control-C in xntpdc. Be patient! +3) The error messages logged by xntpd currently contain only the numerical + error code. Corresponding error message string has to be looked up in + "Books Online" on Visual C++ 2.0 under the topic "Numerical List of Error + Codes". + + +---------------------------------------------------- +MAKING XNTPD FOR WindowsNT 3.5 using Visual C++ 2.0: +---------------------------------------------------- + +Separate projects are needed for xntpd, ntpdate, xntpdc, and the library +containing routines used by them. + +1) First build the static library composed of routines in the lib + subdirectory of the distribution. Load the project by opening the + corresponding makefile libntp.mak (in the lib subdirectory of the + distribution) by choosing the Open option in the File menu. This should + display a list of files contained in this project. Then choose the + "Rebuild All" option from the Project menu in order to compile the + routines into a library. The libntp.lib static library is created in + the lib/WinDebug directory + + You can now choose to build xntpd, ntpdate, and xntpdc in any order. + +2) To build xntpd, load the project by opening the corresponding makefile + xntpd.mak (in the xntpd subdirectory of the distribution), and rebuild + all files. The xntpd.exe executable is created in the xntpd/WinDebug + directory. + +3) repeat the above step for ntpdate and xntpdc + + +------------------------------------------------- +INSTALLING XNTPD AS A SERVICE UNDER WindowsNT 3.5 +------------------------------------------------- + +At this point you need to install 'xntpd' as a service. First modify the +sample configuration file conf/config.winnt35 in the distribution to +suit your needs. Then install it as "%SystemRoot%\NTP.INI" (%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", +NTP.INI is the suggested name for the "ntp.conf" file in Windows environment). +The instsrv.c program in the util subdirectory of the distribution can +be used to install 'xntpd' as a service and start automatically at boot +time. Compile instsrv.c, and enter form the command prompt + "instsrv.exe NetWorkTimeProtocol <pathname_for_xntd.exe>" +Clicking on the "Services" icon in the "Control Panel" ("Main" group +in the "Program Manager") 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. View the event log by +clicking on the "Event Viewer" icon in the "Administrative Tools" group +of the "Program Manager", there should be several successful startup +messages from NTP. NTP will keep running and restart automatically when +the machine is rebooted. + +You can change the start mode (automatic/manual) and other startup +parameters correponding to the NTP service (eg. location of conf file) +also in the "Services" dialog box if you wish. + +There is no clean way to run 'ntpdate' before starting 'xntpd' at boot +time, unlike the Unix environment. 'xntpd' will step the clock upto +a 1000 seconds. While there is no reason that the system clock should +be that much off during bootup if 'xntpd' was running before bootup, +you may want to increase the CLOCK_WAYTOOBIG parameter in include/ntp.h +from 1000 to, say, MAXINT. + +You can also use instsrv.c to delete the NTP service + "instsrv.exe NetworkTimeProtocol remove" + + +Viraj Bais +<vbais@mailman1.intel.com> diff --git a/contrib/ntp/html/howto.htm b/contrib/ntp/html/howto.htm new file mode 100644 index 0000000..7d03df9 --- /dev/null +++ b/contrib/ntp/html/howto.htm @@ -0,0 +1,315 @@ +<html><head><title> +How to Write a Reference Clock Driver +</title></head><body><h3> +How to Write a Reference Clock Driver +</h3><hr> + +<h4>Description</h4> + +<p>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 local 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>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 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>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> are called to +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>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 +millisecond/microsecond decoded from the ASCII timecode. Additional +information includes the receive timestamp, exception report, 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. + +<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> and <tt>ppsclock</tt> STREAMS modules and +<tt>ppsapi</tt> PPS interface described in the <a href="ldisc.htm">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>ppsclock</tt> module is an interface for the +PPS signal provided by some radios. 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 = "gadget.htm"> Gadget Box PPS Level +Converter and CHU Modem</a> page. + +<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.htm"> 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="config.htm"> Configuration Options </a> page. + +<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>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>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>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). + +<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. + +<h4>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. + +<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. + +<p><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. + +<p><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. + +<p><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. + +<p><dt><tt>./acconfig.h</tt> +<dd>This is a configuration file used by the autoconfigure scheme. Add +two lines in the form: + +<p><pre> + /* Define if we have a FOO clock */ + #undef FOO +</pre> + +<p>where FOO is the define used to cause the driver to be included in +the distribution. + +<p><dt><tt>./configure.in</tt> +<dd>This is a configuration file used by the autoconfigure scheme. Add +lines similar to the following: + +<p><pre> + AC_MSG_CHECKING(FOO clock_description) + AC_ARG_ENABLE(FOO, [ --enable-FOO clock_description], + [ntp_ok=$enableval], [ntp_ok=$ntp_eac]) + if test "$ntp_ok" = "yes"; then + ntp_refclock=yes + AC_DEFINE(FOO) + fi + AC_MSG_RESULT($ntp_ok) +</pre> + +<p>(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.) + +<p><dt><tt>./ntpd/Makefile.am</tt> +<dd><p>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. + +<p>Patches to <tt>automake-1.0</tt> are required for the +autoconfigure scripts to work properly. The file <tt>automake- +1.0.patches</tt> can be used for this purpose. + +<p><dt><tt>./ntpd/Makefile.am</tt> +<dd>Do the following sequence of commands: + +<p><pre> + automake + autoconf + autoheader + configure +</pre> + +<p>or simply run <tt>make</tt>, which will do this command sequence +automatically. + +</dl> + +<p><h4>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. +<p><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. + +<p><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. + +<p><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. + +<p>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. + +<p><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. + +<p><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. + +<p><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. + +<p><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. + +<p><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. + +<p><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><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/htmlprimer.htm b/contrib/ntp/html/htmlprimer.htm new file mode 100644 index 0000000..898a583 --- /dev/null +++ b/contrib/ntp/html/htmlprimer.htm @@ -0,0 +1,1198 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Draft//EN"> +<HTML> +<HEAD> +<TITLE>A Beginner's Guide to HTML</TITLE> +</HEAD> + +<BODY> +<H1>A Beginner's Guide to HTML</H1> + +<P> +This is a primer for producing documents in HTML, the markup language +used by the World Wide Web. + +<UL> +<LI><A HREF="#A1.1">Acronym Expansion</A> +<LI><A HREF="#A1.2">What This Primer Doesn't Cover</A> +<LI><A HREF="#A1.3">Creating HTML Documents</A> + <UL> + <LI><A HREF="#A1.3.1">The Minimal HTML Document</A> + <LI><A HREF="#A1.3.2">Basic Markup Tags</A> + <UL> + <LI><A HREF="#A1.3.2.1">Titles</A> + <LI><A HREF="#A1.3.2.2">Headings</A> + <LI><A HREF="#A1.3.2.3">Paragraphs</A> + </UL> + <LI><A HREF="#A1.3.3">Linking to Other Documents</A> + <UL> + <LI><A HREF="#A1.3.3.1">Relative Links Versus Absolute Pathnames</A> + <LI><A HREF="#A1.3.3.2">Uniform Resource Locator</A> + <LI><A HREF="#A1.3.3.3">Anchors to Specific Sections in Other Documents</A> + <LI><A HREF="#A1.3.3.4">Anchors to Specific Sections Within + the Current Document</A> + </UL> + </UL> +<LI><A HREF="#A1.4">Additional Markup Tags</A> + <UL> + <LI><A HREF="#A1.4.1">Lists</A> + <UL> + <LI><A HREF="#A1.4.1.1">Unnumbered Lists</A> + <LI><A HREF="#A1.4.1.2">Numbered Lists</A> + <LI><A HREF="#A1.4.1.3">Definition Lists</A> + <LI><A HREF="#A1.4.1.4">Nested Lists</A> + </UL> + <LI><A HREF="#A1.4.2">Preformatted Text</A> + <LI><A HREF="#A1.4.3">Extended Quotes</A> + <LI><A HREF="#A1.4.4">Addresses</A> + </UL> + +<LI><A HREF="#A1.5">Character Formatting</A> + <UL> + <LI><A HREF="#A1.5.1">Physical Versus Logical: + Use Logical Tags When Possible</A> + <UL> + <LI><A HREF="#A1.5.1.1">Logical Styles</A> + <LI><A HREF="#A1.5.1.2">Physical Styles</A> + </UL> + <LI><A HREF="#A1.5.2">Using Character Tags</A> + <LI><A HREF="#A1.5.3">Special Characters</A> + <UL> + <LI><A HREF="#A1.5.3.1">Escape Sequences</A> + <LI><A HREF="#A1.5.3.2">Forced Line Breaks</A> + <LI><A HREF="#A1.5.3.3">Horizontal Rules</A> + </UL> + </UL> +<LI><A HREF="#A1.6">In-line Images</A> + <UL> + <LI><A HREF="#A1.6.1">Alternate Text for Viewers + That Can't Display Images</A> + </UL> +<LI><A HREF="#A1.7">External Images, Sounds, and Animations</A> +<LI><A HREF="#A1.8">Troubleshooting</A> + <UL> + <LI><A HREF="#A1.8.1">Avoid Overlapping Tags</A> + <LI><A HREF="#A1.8.2">Embed Anchors and Character Tags, + But Not Anything Else</A> + <LI><A HREF="#A1.8.3">Check Your Links</A> + </UL> +<LI><A HREF="#A1.9">A Longer Example</A> +<LI><A HREF="#A1.10">For More Information</A> + <UL> + <LI><A HREF="#A1.10.1">Fill-out Forms</A> + <LI><A HREF="#A1.10.2">Style Guides</A> + <LI><A HREF="#A1.10.3">Other Introductory Documents</A> + <LI><A HREF="#A1.10.4">Additional References</A> + </UL> +</UL> + +<H2><A NAME = "A1.1">Acronym Expansion</A></H2> +<DL COMPACT> +<DT><I>WWW</I> +<DD>World Wide Web (or Web, for short). +<DT><I>SGML</I> +<DD>Standard Generalized Markup Language -- this is a standard for + describing markup languages. +<DT><CITE>DTD</CITE> +<DD>Document Type Definition -- this is a specific markup language, + written using SGML. +<DT><CITE>HTML</CITE> +<DD>HyperText Markup Language -- HTML is a SGML DTD. In practical + terms, HTML is a collection of styles (indicated by markup tags) + that define the various components of a World Wide Web document. +HTML was invented by Tim Berners-Lee while at CERN. He is now director +of the W3 Consortium. +</DL> + +<H2><A NAME = "A1.2">What This Primer Doesn't Cover</A></H2> +<P> +This primer assumes that you have: + +<UL> +<LI>at least a passing knowledge of how to use NCSA Mosaic or some + other Web browser +<LI>a general understanding of how Web servers and client browsers + work +<LI>access to a Web server for which you would like to produce HTML + documents, or that you wish to produce HTML documents for personal + use +</UL> + +<H2><A NAME = "A1.3">Creating HTML Documents</A></H2> +<P> +HTML documents are in plain (also known as ASCII) text format and can +be created using any text editor (e.g., Emacs or vi on UNIX machines). +A couple of Web browsers (tkWWW for X Window System machines and CERN's +Web browser for NeXT computers) include rudimentary HTML editors in +a WYSIWYG environment. There are also some WYSIWIG editors available +now (e.g. HotMetal for Sun Sparcstations, HTML Edit for Macintoshes). +You may wish to try one of them first before delving into the details +of HTML. +<BLOCKQUOTE> + <I>You can preview a document in progress with NCSA Mosaic (and + some </I><I>other Web browsers). Open it with the </I><B>Open Local + </B><I>command under the </I><B>File</B><I> menu. </I> + + <P> + <I>After you edit the source HTML file, save the changes. Return + to NCSA </I><I>Mosaic and </I><B>Reload</B><I> the document. The + changes are reflected in the on-</I><I>screen display.</I> + +</BLOCKQUOTE> + +<H3><A NAME = "A1.3.1">The Minimal HTML Document</A></H3> +<P> +Here is a bare-bones example of HTML: + +<PRE> + <TITLE>The simplest HTML example</TITLE> + <H1>This is a level-one heading</H1> + Welcome to the world of HTML. + This is one paragraph.<P> + And this is a second.<P> +</PRE> + +<A HREF=MinimalHTML.html>Click here</A> to see the formatted version +of the example. + +<P> +HTML uses markup tags to tell the Web browser how to display the text. +The above example uses: + +<UL> +<LI>the <SAMP><TITLE></SAMP> tag (and corresponding <SAMP></TITLE></SAMP> + tag), which specifies the title of the document +<LI>the <SAMP><H1></SAMP> header tag (and corresponding <SAMP></H1></SAMP>) +<LI>the <SAMP><P></SAMP> paragraph-separator tag +</UL> + +<P> +HTML tags consist of a left angle bracket (<SAMP><</SAMP>), (a ``less +than'' symbol to mathematicians), followed by name of the tag and closed +by a right angular bracket (<SAMP>></SAMP>). Tags are usually paired, +e.g. <SAMP><H1></SAMP> and <SAMP></H1></SAMP>. The ending +tag looks just like the starting tag except a slash (/) precedes the +text within the brackets. In the example, <SAMP><H1></SAMP> tells +the Web browser to start formatting a level-one heading; <SAMP></H1></SAMP> +tells the browser that the heading is complete. + +<P> +The primary exception to the pairing rule is the <SAMP><P></SAMP> +tag. There is no such thing as <SAMP></P></SAMP>. + +<P> +<STRONG>NOTE:</STRONG><I> HTML is not case sensitive. </I><SAMP><title></SAMP><I> +is equivalent to </I><SAMP><TITLE></SAMP><I> or </I><SAMP><TiTlE></SAMP><I>. +</I> + +<P> +Not all tags are supported by all World Wide Web browsers. If a browser +does not support a tag, it just ignores it. + +<H3><A NAME = "A1.3.2">Basic Markup Tags</A></H3> +<H4><A NAME = "A1.3.2.1">Title</A></H4> +<P> +Every HTML document should have a title. A title is generally displayed +separately from the document and is used primarily for document identification +in other contexts (e.g., a WAIS search). Choose about half a dozen +words that describe the document's purpose. +<BLOCKQUOTE> + <I>In the X Window System and Microsoft Windows versions of NCSA + </I><I>Mosaic, the </I><B>Document Title</B><I> field is at the + top of the screen just below the </I><I>pulldown menus. In NCSA + Mosaic for Macintosh, text tagged as </I><SAMP><TITLE></SAMP> + <I>appears as the window title.</I> + +</BLOCKQUOTE> + +<H4><A NAME = "A1.3.2.2">Headings</A></H4> +<P> +HTML has six levels of headings, numbered 1 through 6, with 1 being +the most prominent. Headings are displayed in larger and/or bolder +fonts than normal body text. The first heading in each document should +be tagged <SAMP><H1></SAMP>. The syntax of the heading tag is: + +<P> +<SAMP><H</SAMP><VAR>y</VAR><SAMP>></SAMP><VAR>Text of heading</VAR><SAMP> +</H</SAMP><VAR>y</VAR><SAMP> ></SAMP> + +<P> +where <VAR>y</VAR> is a number between 1 and 6 specifying the level +of the heading. + +<P> +For example, the coding for the ``Headings'' section heading above +is + +<PRE> + <H3>Headings</H3> +</PRE> + +<H5><A NAME = "A1.3.2.2.1">Title versus first heading</A></H5> +<P> +In many documents, the first heading is identical to the title. For +multipart documents, the text of the first heading should be suitable +for a reader who is already browsing related information (e.g., a chapter +title), while the title tag should identify the document in a wider +context (e.g., include both the book title and the chapter title, although +this can sometimes become overly long). + +<H4><A NAME = "A1.3.2.3">Paragraphs</A></H4> +<P> +Unlike documents in most word processors, carriage returns in HTML +files aren't significant. Word wrapping can occur at any point in your +source file, and multiple spaces are collapsed into a single space. +(There are couple of exceptions; space following a <SAMP><P></SAMP> +or <SAMP><H</SAMP><VAR>y</VAR><SAMP>></SAMP> tag, for example, +is ignored.) Notice that in the bare-bones example, the first paragraph +is coded as + +<PRE> + Welcome to HTML. + This is the first paragraph. <P> +</PRE> + +<P> +In the source file, there is a line break between the sentences. A +Web browser ignores this line break and starts a new paragraph only +when it reaches a <SAMP><P></SAMP> tag. + +<P> +<STRONG>Important:</STRONG> You must separate paragraphs with <SAMP><P></SAMP>. +The browser ignores any indentations or blank lines in the source text. +HTML relies almost entirely on the tags for formatting instructions, +and without the <SAMP><P></SAMP> tags, the document becomes one +large paragraph. (The exception is text tagged as ``preformatted,'' +which is explained below.) For instance, the following would produce +identical output as the first bare-bones HTML example: + +<PRE> + <TITLE>The simplest HTML example</TITLE><H1>This is a level + one heading</H1>Welcome to the world of HTML. This is one + paragraph.<P>And this is a second.<P> +</PRE> + +<P> +However, to preserve readability in HTML files, headings should be +on separate lines, and paragraphs should be separated by blank lines +(in addition to the <SAMP><P></SAMP> tags). +<BLOCKQUOTE> + <I>NCSA Mosaic handles <P> by ending the current paragraph + and insert</I><I>ing a blank line. </I> + +</BLOCKQUOTE> + +<P> +In HTML+, a successor to HTML currently in development, <SAMP><P></SAMP> +becomes a ``container'' of text, just as the text of a level-one heading +is ``contained'' within<SAMP><H1> ... </SAMP><SAMP></H1></SAMP>: + +<PRE> + <P> + This is a paragraph in HTML+. + </P> +</PRE> + +<P> +The difference is that the <SAMP></P></SAMP> closing tag can +always be omitted. (That is, if a browser sees a <SAMP><P></SAMP>, +it knows that there must be an implied <SAMP></P></SAMP> to end +the previous paragraph.) In other words, in HTML+, <SAMP><P></SAMP> +is a beginning-of-paragraph marker. + +<P> +The advantage of this change is that you will be able to specify formatting +options for a paragraph. For example, in HTML+, you will be able to +center a paragraph by coding + +<PRE> + <SAMP><P ALIGN=CENTER></SAMP> + This is a centered paragraph. This is HTML+, so you can't do it yet. +</PRE> + +<P> +This change won't effect any documents you write now, and they will +continue to look just the same with HTML+ browsers. + +<H3><A NAME = "A1.3.3">Linking to Other Documents</A></H3> +<P> +The chief power of HTML comes from its ability to link regions of text +(and also images) to another document. The browser highlights these +regions (usually with color and/or underlines) to indicate that they +are hypertext links (often shortened to <DFN>hyperlinks</DFN> or simply +<DFN>links</DFN>). + +<P> +HTML's single hypertext-related tag is <SAMP><A></SAMP>, which +stands for <DFN>anchor</DFN>. To include an anchor in your document: + +<OL> +<LI>Start the anchor with <SAMP><A</SAMP> . (There's a space after + the <CODE>A</CODE>.) +<LI>Specify the document that's being pointed to by entering the parameter + <SAMP>HREF="</SAMP><VAR>filename</VAR><SAMP>"</SAMP> + followed by a closing right angle bracket: <SAMP>></SAMP> +<LI>Enter the text that will serve as the hypertext link in the current + document. +<LI>Enter the ending anchor tag: <SAMP></A></SAMP>. +</OL> + +<P> +Here is an sample hypertext reference: + +<PRE> + <A HREF="MaineStats.html">Maine</A> +</PRE> + +<P> +This entry makes the word ``Maine'' the hyperlink to the document <SAMP>MaineStats.html</SAMP>, +which is in the same directory as the first document. You can link +to documents in other directories by specifying the <DFN>relative path</DFN> +from the current document to the linked document. For example, a link +to a file <SAMP>NJStats.html</SAMP> located in the subdirectory <SAMP>AtlanticStates</SAMP> +would be: + +<PRE> + <A HREF="AtlanticStates/NJStats.html">New Jersey</A> +</PRE> + +<P> +These are called <VAR>relative links</VAR>. You can also use the absolute +pathname of the file if you wish. Pathnames use the standard UNIX syntax. + +<H4><A NAME = "A1.3.3.1">Relative Links Versus Absolute Pathnames</A></H4> +<P> +In general, you should use relative links, because + +<OL> +<LI>You have less to type. +<LI>It's easier to move a group of documents to another location, because + the relative path names will still be valid. +</OL> + +<P> +However, use absolute pathnames when linking to documents that are +not directly related. For example, consider a group of documents that +comprise a user manual. Links within this group should be relative +links. Links to other documents (perhaps a reference to related software) +should use full path names. This way, if you move the user manual to +a different directory, none of the links would have to be updated. + +<H4><A NAME = "A1.3.3.2">Uniform Resource Locator</A></H4> +<P> +The World Wide Web uses Uniform Resource Locators (URLs) to specify +the location of files on other servers. A URL includes the type of +resource being accessed (e.g., gopher, WAIS), the address of the server, +and the location of the file. The syntax is: + +<P> +<VAR>scheme</VAR><SAMP>://</SAMP><VAR>host.domain</VAR><SAMP>[:</SAMP><VAR>port</VAR><SAMP>]/</SAMP><VAR>path</VAR><SAMP>/</SAMP><VAR>filename</VAR> + +<P> +where <VAR>scheme</VAR> is one of + +<DL COMPACT> +<DT><SAMP>file</SAMP> +<DD> +<DT> +<DD>a file on your local system, or a file on an anonymous FTP server + +<DT><SAMP>http</SAMP> +<DD>a file on a World Wide Web server +<DT><SAMP>gopher</SAMP> +<DD>a file on a Gopher server +<DT><SAMP>WAIS</SAMP> +<DD>a file on a WAIS server +<DT><SAMP>news</SAMP> +<DD>an Usenet newsgroup +<DT><SAMP>telnet</SAMP> +<DD>a connection to a Telnet-based service +</DL> + +<P> +The <VAR>port</VAR> number can generally be omitted. (That means unless +someone tells you otherwise, leave it out.) + +<P> +For example, to include a link to this primer in your document, you +would use + +<PRE> + <A HREF = "http://www.ncsa.uiuc.edu/General/Internet/WWW/HTMLPrimer.html"> + NCSA's Beginner's Guide to HTML</A> +</PRE> + +<P> +This would make the text ``NCSA's Beginner's Guide to HTML'' a hyperlink +to this document. + +<P> +For more information on URLs, look at + +<UL> +<LI><A HREF = "http://www.w3.org/hypertext/WWW/Addressing/Addressing.html"> + <CITE>WWW Names and Addresses, URIs, URLs, URNs</CITE></A>, written + by people at CERN +<LI><A HREF = "http://www.ncsa.uiuc.edu/demoweb/url-primer.html"> + <CITE>A Beginner's Guide to URLs</CITE></A>, located on the NCSA Mosaic + <B>Help</B> menu +</UL> + +<H4><A NAME = "A1.3.3.3">Links to Specific Sections in Other Documents</A></H4> +<P> +Anchors can also be used to move to a particular section in a document. +Suppose you wish to set a link from document A and a specific section +in document B. (Call this file <SAMP>documentB.html</SAMP>.) First +you need to set up a <DFN>named anchor</DFN> in document B. For example, +to set up an anchor named ``Jabberwocky'' to document B, enter + +<PRE> + Here's <A NAME = "Jabberwocky">some text</a> +</PRE> + +<P> +Now when you create the link in document A, include not only the filename, +but also the named anchor, separated by a hash mark (#). + +<PRE> + This is my <A HREF = "documentB.html#Jabberwocky">link</A> to document B. +</PRE> + +<P> +Now clicking on the word ``link'' in document A sends the reader directly +to the words ``some text'' in document B. + +<H4><A NAME = "A1.3.3.4">Links to Specific Sections Within the Current Document</A></H4> +<P> +The technique is exactly the same except the filename is omitted. + +<P> +For example, to link to the Jabberwocky anchor from within the same +file (Document B), use + +<PRE> + This is <A HREF = "#Jabberwocky">Jabberwocky link</A> from within Document B. +</PRE> + +<H2><A NAME = "A1.4">Additional Markup Tags</A></H2> +<P> +The preceding is sufficient to produce simple HTML documents. For more +complex documents, HTML has tags for several types of lists, preformatted +sections, extended quotations, character formatting, and other items. + +<H3><A NAME = "A1.4.1">Lists</A></H3> +<P> +HTML supports unnumbered, numbered, and definition lists. + +<H4><A NAME = "A1.4.1.1">Unnumbered Lists</A></H4> +<P> +To make an unnumbered list, + +<OL> +<LI>Start with an opening list <SAMP><UL></SAMP> tag. +<LI>Enter the <SAMP><LI></SAMP> tag followed by the individual + item. (No closing <SAMP></LI></SAMP> tag is needed.) +<LI>End with a closing list <SAMP></UL></SAMP> tag. +</OL> + +<P> +Below an example two-item list: + +<PRE> + <UL> + <LI> apples + <LI> bananas + </UL> +</PRE> + +<P> +The output is: + +<UL> +<LI>apples +<LI>bananas +</UL> + +<P> +The <SAMP><LI></SAMP> items can contain multiple paragraphs. +Just separate the paragraphs with the <SAMP><P></SAMP> paragraph +tags. + +<H4><A NAME = "A1.4.1.2">Numbered Lists</A></H4> +<P> +A numbered list (also called an ordered list, from which the tag name +derives) is identical to an unnumbered list, except it uses <SAMP><OL></SAMP> +instead of <SAMP><UL></SAMP>. The items are tagged using the +same <SAMP><LI></SAMP> tag. The following HTML code + +<PRE> + <OL> + <LI> oranges + <LI> peaches + <LI> grapes + </OL> +</PRE> + +<P> +produces this formatted output: + +<OL> +<LI>oranges +<LI>peaches +<LI>grapes +</OL> + +<H4><A NAME = "A1.4.1.3">Definition Lists </A></H4> +<P> +A definition list usually consists of alternating a term (abbreviated +as <SAMP>DT</SAMP>) and a definition (abbreviated as <SAMP>DD</SAMP>). +Web browsers generally format the definition on a new line. + +<P> +The following is an example of a definition list: + +<PRE> + <DL> + <DT> NCSA + <DD> NCSA, the National Center for Supercomputing Applications, + is located on the campus of the University of Illinois + at Urbana-Champaign. NCSA is one of the participants in the + National MetaCenter for Computational Science and Engineering. + <DT> Cornell Theory Center + <DD> CTC is located on the campus of Cornell University in Ithaca, + New York. CTC is another participant in the National MetaCenter + for Computational Science and Engineering. + </DL> +</PRE> + +<P> +The output looks like: + +<DL COMPACT> +<DT>NCSA +<DD>NCSA, the National Center for Supercomputing Applications, is located + on the campus of the University of Illinois at Urbana-Champaign. + NCSA is one of the participants in the National MetaCenter for + Computational Science and Engineering. +<DT>Cornell Theory Center +<DD>CTC is located on the campus of Cornell University in Ithaca, New + York. CTC is another participant in the National MetaCenter for + Computational Science and Engineering. +</DL> + +<P> +The <SAMP><DT></SAMP> and<SAMP> <DD></SAMP> entries can +contain multiple paragraphs (separated by <SAMP><P></SAMP> paragraph +tags), lists, or other definition information. + +<H4><A NAME = "A1.4.1.4">Nested Lists</A></H4> +<P> +Lists can be arbitrarily nested, although in practice you probably +should limit the nesting to three levels. You can also have a number +of paragraphs, each containing a nested list, in a single list item. + +<P> + An example nested list: + +<PRE> + <UL> + <LI> A few New England states: + <UL> + <LI> Vermont + <LI> New Hampshire + </UL> + <LI> One Midwestern state: + <UL> + <LI> Michigan + </UL> + </UL> +</PRE> + +<P> +The nested list is displayed as + +<UL> +<LI>A few New England states: + <UL> + <LI>Vermont + <LI>New Hampshire + </UL> +<LI>One Midwestern state: + <UL> + <LI>Michigan + </UL> +</UL> + +<H3><A NAME = "A1.4.2">Preformatted Text</A></H3> +<P> +Use the<SAMP> <PRE></SAMP> tag (which stands for ``preformatted'') +to generate text in a fixed-width font and cause spaces, new lines, +and tabs to be significant. (That is, multiple spaces are displayed +as multiple spaces, and lines break in the same locations as in the +source HTML file.) This is useful for program listings. For example, +the following lines + +<PRE> + <PRE> + #!/bin/csh + cd $SCR + cfs get mysrc.f:mycfsdir/mysrc.f + cfs get myinfile:mycfsdir/myinfile + fc -02 -o mya.out mysrc.f + mya.out + cfs save myoutfile:mycfsdir/myoutfile + rm * + </PRE> +</PRE> + +<P> +display as + +<PRE> + #!/bin/csh + cd $SCR + cfs get mysrc.f:mycfsdir/mysrc.f + cfs get myinfile:mycfsdir/myinfile + fc -02 -o mya.out mysrc.f + mya.out + cfs save myoutfile:mycfsdir/myoutfile + rm * +</PRE> + +<P> +Hyperlinks can be used within <SAMP><PRE></SAMP> sections. You +should avoid using other HTML tags within <SAMP><PRE></SAMP> +sections, however. + +<P> +Note that because <, >, and & have special meaning in HTML, +you have to use their escape sequences (<SAMP>&lt;</SAMP>, <SAMP>&gt;</SAMP>, +and <SAMP>&amp;</SAMP>, respectively) to enter these characters. +See the section <A HREF = "#A1.5.3"> +Special Characters</A> for more information. + +<H3><A NAME = "A1.4.3">Extended Quotations</A></H3> +<P> +Use the <SAMP><BLOCKQUOTE></SAMP> tag to include quotations in +a separate block on the screen. Most browsers generally indent to separate +it from surrounding text. + +<P> +An example: + +<PRE> + <BLOCKQUOTE> + I still have a dream. It is a dream deeply rooted in the + American dream. <P> + I have a dream that one day this nation will rise up and + live out the true meaning of its creed. We hold these truths + to be self-evident that all men are created equal. <P> + </BLOCKQUOTE> +</PRE> + +<P> +The result is: +<BLOCKQUOTE> + I still have a dream. It is a dream deeply rooted in the American + dream. + + <P> + I have a dream that one day this nation will rise up and live out + the true meaning of its creed. We hold these truths to be self-evident + that all men are created equal. + +</BLOCKQUOTE> + +<H3><A NAME = "A1.4.4">Addresses</A></H3> +<P> +The <SAMP><ADDRESS></SAMP> tag is generally used to specify the +author of a document and a means of contacting the author (e.g., an +email address). This is usually the last item in a file. + +<P> +For example, the last line of the online version of this guide is + +<PRE> + <ADDRESS> + A Beginner's Guide to HTML / NCSA / pubs@ncsa.uiuc.edu + </ADDRESS> +</PRE> + +<P> +The result is +<ADDRESS>A Beginner's Guide to HTML / NCSA / pubs@ncsa.uiuc.edu </ADDRESS> + +<P> +<STRONG>NOTE:</STRONG> <SAMP><ADDRESS></SAMP> is <EM>not</EM> +used for postal addresses. See ``Forced Line Breaks'' on page 10 to +see how to format postal addresses. + +<H2><A NAME = "A1.5">Character Formatting</A></H2> +<P> +You can code individual words or sentences with special styles. There +are two types of styles: logical and physical. <DFN>Logical styles</DFN> +tag text according to its meaning, while <DFN>physical styles</DFN> +specify the specific appearance of a section. For example, in the preceding +sentence, the words ``logical styles'' was tagged as a ``definition.'' +The same effect (formatting those words in italics), could have been +achieved via a different tag that specifies merely ``put these words +in italics.'' + +<H3><A NAME = "A1.5.1">Physical Versus Logical: Use Logical Styles When Possible</A></H3> +<P> +If physical and logical styles produce the same result on the screen, +why are there both? We devolve, for a couple of paragraphs, into the +philosophy of SGML, which can be summed in a Zen-like mantra: ``Trust +your browser.'' + +<P> +In the ideal SGML universe, content is divorced from presentation. +Thus, SGML tags a level-one heading as a level-one heading, but does +not specify that the level-one heading should be, for instance, 24-point +bold Times centered on the top of a page. The advantage of this approach +(it's similar in concept to style sheets in many word processors) is +that if you decide to change level-one headings to be 20-point left-justified +Helvetica, all you have to do is change the definition of the level-one +heading in the presentation device (i.e., your World Wide Web browser). + +<P> +The other advantage of logical tags is that they help enforce consistency +in your documents. It's easier to tag something as <SAMP><H1></SAMP> +than to remember that level-one headings are 24-point bold Times or +whatever. The same is true for character styles. For example, consider +the <SAMP><STRONG></SAMP> tag. Most browsers render it in bold +text. However, it is possible that a reader would prefer that these +sections be displayed in red instead. Logical styles offer this flexibility. + +<H4><A NAME = "A1.5.1.1">Logical Styles</A></H4> +<DL COMPACT> +<DT><SAMP><DFN></SAMP> +<DD>for a word being defined. Typically displayed in italics. (<DFN>NCSA + </DFN><DFN>Mosaic</DFN> is a World Wide Web browser.) +<DT><SAMP><EM></SAMP> +<DD>for emphasis. Typically displayed in italics. (<EM>Watch out for + pick</EM><EM>pockets</EM>.) +<DT><SAMP><CITE></SAMP> +<DD>for titles of books, films, etc. Typically displayed in italics. + (<CITE>A </CITE><CITE>Beginner's Guide to HTML</CITE>) +<DT><SAMP><CODE></SAMP> +<DD>for snippets of computer code. Displayed in a fixed-width font. + (The <SAMP><stdio.h></SAMP> header file) +<DT> <SAMP><KBD></SAMP> +<DD>for user keyboard entry. Should be displayed in a bold fixed-width + font, but many browsers render it in the plain fixed-width font. + (Enter <KBD>passwd</KBD> to change your password.) +<DT><SAMP><SAMP></SAMP> +<DD>for computer status messages. Displayed in a fixed-width font. + (<SAMP>Segmentation fault: Core dumped.</SAMP>) +<DT><SAMP><STRONG></SAMP> +<DD>for strong emphasis. Typically displayed in bold. (<STRONG>Important</STRONG>) + +<DT><SAMP><VAR></SAMP> +<DD>for a ``metasyntactic'' variable, where the user is to replace + the variable with a specific instance. Typically displayed in italics. + (<KBD>rm</KBD> <VAR>filename</VAR> deletes the file.) +</DL> + +<H4><A NAME = "A1.5.1.2">Physical Styles</A></H4> +<DL COMPACT> +<DT><SAMP><B></SAMP> +<DD>bold text +<DT><SAMP><I></SAMP> +<DD>italic text +<DT><SAMP><TT></SAMP> +<DD>typewriter text, e.g. fixed-width font. +</DL> + +<H3><A NAME = "A1.5.2">Using Character Tags</A></H3> +<P> +To apply a character style, + +<OL> +<LI>Start with <SAMP><</SAMP><VAR>tag</VAR><SAMP>></SAMP>, where<SAMP> + </SAMP><VAR>tag</VAR> is the desired character formatting tag, + to indicate the beginning of the tagged text. +<LI>Enter the tagged text. +<LI>End the passage with <SAMP></</SAMP><VAR>tag</VAR><SAMP>></SAMP>. +</OL> + +<H3><A NAME = "A1.5.3">Special Characters</A></H3> +<H4><A NAME = "A1.5.3.1">Escape Sequences</A></H4> +<P> +Four characters of the ASCII character set -- the left angle bracket +(<), the right angle bracket (>), the ampersand (&) and the +double quote (") -- have special meaning within HTML and therefore +cannot be used ``as is'' in text. (The angle brackets are used to indicate +the beginning and end of HTML tags, and the ampersand is used to indicate +the beginning of an escape sequence.) + +<P> +To use one of these characters in an HTML document, you must enter +its <DFN>escape </DFN><DFN>sequence</DFN> instead: + +<DL COMPACT> +<DT><SAMP>&lt;</SAMP> +<DD>the escape sequence for < +<DT><SAMP>&gt;</SAMP> +<DD>the escape sequence for > +<DT><SAMP>&amp;</SAMP> +<DD>the escape sequence for & +<DT><SAMP>&quot;</SAMP> +<DD>the escape sequence for " +</DL> + +<P> +Additional escape sequences support accented characters. For example: + +<DL COMPACT> +<DT><SAMP>&ouml;</SAMP> +<DD>the escape sequence for a lowercase o with an umlaut: ö + +<DT><SAMP>&ntilde;</SAMP> +<DD>the escape sequence for a lowercase n with an tilde: ñ +<DT><SAMP>&Egrave;</SAMP> +<DD>the escape sequence for an uppercase E with a grave accent: È + +</DL> + +<P> +<A HREF = "http://www.w3.org/hypertext/WWW/MarkUp/ISOlat1.html"> A full +list of supported characters</A> is available. + +<P> +<STRONG>NOTE:</STRONG> Unlike the rest of HTML, the escape sequences +are case sensitive. You cannot, for instance, use &LT; instead +of &lt;. + +<H4><A NAME = "A1.5.3.2">Forced Line Breaks</A></H4> +<P> +The <SAMP><BR></SAMP> tag forces a line break with no extra space +between lines. (By contrast, most browsers format the <SAMP><P></SAMP> +paragraph tag with an additional blank line to more clearly indicate +the beginning the new paragraph.) + +<P> +One use of <SAMP><BR></SAMP> is in formatting addresses: + +<PRE> + National Center for Supercomputing Applications<BR> + 605 East Springfield Avenue<BR> + Champaign, Illinois 61820-5518<BR> +</PRE> + +<H4><A NAME = "A1.5.3.3">Horizontal Rules</A></H4> +<P> +The <SAMP><HR> tag </SAMP>produces a horizontal line the width +of the browser window. + +<H2><A NAME = "A1.6">In-line Images</A></H2> +<P> +Most Web browsers can display in-line images (that is, images next +to text) that are in X Bitmap (XBM) or GIF format. Each image takes +time to process and slows down the initial display of the document, +so generally you should not include too many or overly large images. + +<P> +To include an in-line image, use + +<PRE> + <IMG SRC=<VAR>image_URL</VAR>> +</PRE> + +<P> +where <VAR>image_URL</VAR> is the URL of the image file. The syntax +for <SAMP>IMG SRC </SAMP>URLs is identical to that used in an anchor +<SAMP>HREF</SAMP>. If the image file is a GIF file, then the filename +part of <VAR>image_URL </VAR><STRONG>must</STRONG> end with <SAMP>.gif</SAMP>. +Filenames of X Bitmap images must end with <SAMP>.xbm</SAMP>. + +<P> +<IMG SRC = "Graphics/RandomPic.gif" ALT = "">By default the bottom +of an image is aligned with the text as shown in this paragraph. + +<P> +<IMG SRC = "Graphics/RandomPic.gif" ALT = "" ALIGN = TOP> +Add the <SAMP>ALIGN=TOP</SAMP> +option if you want the browser to align adjacent text with the top +of the image as shown in this paragraph. The full in-line image tag +with the top alignment is: + +<PRE> + <IMG ALIGN=top SRC=<VAR>image_URL</VAR>> +</PRE> + +<P> +<IMG SRC = "Graphics/RandomPic.gif" ALT = "" ALIGN = MIDDLE> +<SAMP>ALIGN=MIDDLE</SAMP> +aligns the text with the center of the image. + +<H3><A NAME = "A1.6.1">Alternate Text for Browsers That Can't Display Images</A></H3> +<P> +Some World Wide Web browsers, primarily those that run on VT100 terminals, +cannot display images. The <SAMP>ALT</SAMP> option allows you to specify +text to be displayed when an image cannot be. For example: + +<PRE> + <IMG SRC = "UpArrow.gif" ALT = "Up"> +</PRE> + +<P> +where <SAMP>UpArrow.gif </SAMP>is the picture of an upward pointing +arrow. With NCSA Mosaic and other graphics-capable viewers, the user +sees the up arrow graphic. With a VT100 browser, such as lynx, the +user sees the word ``Up.'' + +<H2><A NAME = "A1.7">External Images, Sounds, and Animations</A></H2> +<P> +You may want to have an image open as a separate document when a user +activates a link on either a word or a smaller, in-line version of +the image included in your document. This is considered an external +image and is useful if you do not wish to slow down the loading of +the main document with large in-line images. + +<P> +To include a reference to an external image, use + +<PRE> + <A HREF = <VAR>image_URL</VAR>>link anchor</A> +</PRE> + +<P> +Use the same syntax is for links to external animations and sounds. +The only difference is the file extension of the linked file. For example, + +<P> +<SAMP><A HREF = "QuickTimeMovie.mov">link anchor</A></SAMP> + +<P> +specifies a link to a QuickTime movie. Some common file types and their +extensions are: + +<DL COMPACT> +<DT><STRONG>File Type</STRONG> +<DD><STRONG>Extension</STRONG> +<DT>Plain text +<DD><SAMP>.txt</SAMP> +<DT>HTML document +<DD><SAMP>.html</SAMP> +<DT>GIF image +<DD><SAMP>.gif</SAMP> +<DT>TIFF image +<DD><SAMP>.tiff</SAMP> +<DT>XBM bitmap image +<DD><SAMP>.xbm</SAMP> +<DT>JPEG image +<DD><SAMP>.jpg</SAMP> or <SAMP>.jpeg</SAMP> +<DT>PostScript file +<DD><SAMP>.ps</SAMP> +<DT>AIFF sound +<DD><SAMP>.aiff</SAMP> +<DT>AU sound +<DD><SAMP>.au</SAMP> +<DT>QuickTime movie +<DD><SAMP>.mov</SAMP> +<DT>MPEG movie +<DD><SAMP>.mpeg</SAMP> or <SAMP>.mpg</SAMP> +</DL> + +<P> +Make sure your intended audience has the necessary viewers. Most UNIX +workstations, for instance, cannot view QuickTime movies. + +<H2><A NAME = "A1.8">Troubleshooting</A></H2> +<H3><A NAME = "A1.8.1">Avoid Overlapping Tags</A></H3> +<P> +Consider this snippet of HTML: + +<PRE> + <B>This is an example of <DFN>overlapping</B> HTML tags.</DFN> +</PRE> + +<P> +The word ``overlapping'' is contained within both the <SAMP><B></SAMP> +and <SAMP><DFN></SAMP> tags. How does the browser format it? +You won't know until you look, and different browsers will likely react +differently. In general, avoid overlapping tags. + +<H3><A NAME = "A1.8.2">Embed Anchors and Character Tags, But Nothing Else</A></H3> +<P> +It is acceptable to embed anchors within another HTML element: + +<PRE> + <H1><A HREF = "Destination.html">My heading</A></H1> +</PRE> + +<P> +<EM>Do not</EM> embed a heading or another HTML element within an anchor: + +<PRE> + <A HREF = "Destination.html"> + <H1>My heading</H1> + </A> +</PRE> + +<P> +Although most browsers currently handle this example, it is forbidden +by the official HTML and HTML+ specifications, and will not work with +future browsers. + +<P> +Character tags modify the appearance of other tags: + +<PRE> + <UL><LI><B>A bold list item</B> + <UL> + <LI><I>An italic list item</I> + </UL> +</PRE> + +<P> +However, avoid embedding other types of HTML element tags. For example, +it is tempting to embed a heading within a list, in order to make the +font size larger: + +<PRE> + <UL><LI><H1>A large heading</H1> + <UL> + <LI><H2>Something slightly smaller</H2> + </UL> +</PRE> + +<P> +Although some browsers, such as NCSA Mosaic for the X Window System, +format this construct quite nicely, it is unpredictable (because it +is undefined) what other browsers will do. For compatibility with all +browsers, avoid these kinds of constructs. + +<P> +What's the difference between embedding a <SAMP><B></SAMP> within +a <SAMP><LI></SAMP> tag as opposed to embedding a <SAMP><H1></SAMP> +within a <SAMP><LI></SAMP>? This is again a question of SGML. +The semantic meaning of <SAMP><H1></SAMP> is that it's the main +heading of a document and that it should be followed by the content +of the document.Thus it doesn't make sense to find a <SAMP><H1></SAMP> +within a list. + +<P> +Character formatting tags also are generally not additive. You might +expect that + +<PRE> + <B><I>some text</I></B> +</PRE> + +<P> +would produce bold-italic text. On some browsers it does; other browsers +interpret only the innermost tag (here, the italics). + +<H3><A NAME = "A1.8.3">Check Your Links</A></H3> +<P> +When an <SAMP><IMG></SAMP> tag points at an image that does not +exist, a dummy image is substituted. When this happens, make sure that +the referenced image does in fact exist, that the hyperlink has the +correct information in the URL, and that the file permission is set +appropriately (world-readable). + +<H2><A NAME = "A1.9">A Longer Example</A></H2> +<P> +Here is a longer example of an HTML document: + +<PRE> + <HEAD> + <TITLE>A Longer Example</TITLE> + </HEAD> + <BODY> + <H1>A Longer Example</H1> + This is a simple HTML document. This is the first + paragraph. <P> + This is the second paragraph, which shows special effects. This is a + word in <I>italics</I>. This is a word in <B>bold</B>. + Here is an in-lined GIF image: <IMG SRC = "myimage.gif">. + <P> + This is the third paragraph, which demonstrates links. Here is + a hypertext link from the word <A HREF = "subdir/myfile.html">foo</A> + to a document called "subdir/myfile.html". (If you + try to follow this link, you will get an error screen.) <P> + <H2>A second-level header</H2> + Here is a section of text that should display as a + fixed-width font: <P> + <PRE> + On the stiff twig up there + Hunches a wet black rook + Arranging and rearranging its feathers in the rain ... + </PRE> + This is a unordered list with two items: <P> + <UL> + <LI> cranberries + <LI> blueberries + </UL> + This is the end of my example document. <P> + <ADDRESS>Me (me@mycomputer.univ.edu)</ADDRESS> + </BODY> +</PRE> + +<A HREF=LongerExample.html>Click here</A> to see the formatted version. + +<P> +In addition to tags already discussed, this example also uses the <SAMP><HEAD> +... </HEAD> </SAMP>and <SAMP><BODY> ... </BODY></SAMP> +tags, which separate the document into introductory information about +the document and the main text of the document. These tags don't change +the appearance of the formatted document at all, but are useful for +several purposes (for example, NCSA Mosaic for Macintosh 2.0, for example, +allows you to browse just the header portion of document before deciding +whether to download the rest), and it is recommended that you use these +tags. + +<H2><A NAME = "A1.10">For More Information</A></H2> +<P> +This guide is only an introduction to HTML and not a comprehensive +reference. Below are additional sources of information. + +<H3><A NAME = "A1.10.1">Fill-out Forms</A></H3> +<P> +One major feature not discussed here is fill-out forms, which allows +users to return information to the World Wide Web server. For information +on fill-out forms, look at this +<A HREF = "/SDG/Software/Mosaic/Docs/fill-out-forms/overview.html"> Fill-out +Forms Overview</A> + +<H3><A NAME = "A1.10.2">Style Guides</A></H3> +<P> +The following offer advice on how to write ``good'' HTML: + +<UL> +<LI><A HREF = "http://www.willamette.edu/html-composition/strict-html.html"> + <CITE>Composing Good HTML</CITE></A> +<LI> +<A HREF = "http://www.w3.org/hypertext/WWW/Provider/Style/Introduction.html"> + CERN's style guide for online hypertext</A> +</UL> + +<H3><A NAME = "A1.10.3">Other Introductory Documents</A></H3> +These cover similar information as this guide: +<UL> +<LI><A HREF = "http://www.ucc.ie/info/net/htmldoc.html"> + <CITE>How to Write HTML Files</CITE></A> +<LI><A HREF = "http://melmac.corp.harris.com/about_html.html"> + <CITE>Introduction to HTML</CITE></A> +</UL> + +<H3><A NAME = "A1.10.4">Additional References</A></H3> +<UL> +<LI><A HREF = "http://kuhttp.cc.ukans.edu/lynx_help/HTML_quick.html"> + <CITE>The HTML Quick Reference Guide</CITE></A>, + which provides a comprehensive listing of HTML codes +<LI><A HREF = "http://www.w3.org/hypertext/WWW/MarkUp/MarkUp.html"> + The official HTML specification</A> +<LI><A HREF = "http://www.w3.org/hypertext/WWW/MarkUp/SGML.html">A + description of SGML</A>, the Standard Generalized Markup Language +<LI><A HREF += "http://www.ietf.cnri.reston.va.us/html.charters/html-charter.html"> +<cite>The HTML Working Group of the IETF</cite></A>. +</UL> +<HR> +<ADDRESS> +National Center for Supercomputing Applications / pubs@ncsa.uiuc.edu +</ADDRESS> +</BODY> + diff --git a/contrib/ntp/html/index.htm b/contrib/ntp/html/index.htm new file mode 100644 index 0000000..a676c87 --- /dev/null +++ b/contrib/ntp/html/index.htm @@ -0,0 +1,201 @@ +<HTML><HEAD><TITLE> +The Network Time Protocol (NTP) Distribution +</TITLE></HEAD><BODY><H3> +The Network Time Protocol (NTP) Distribution +</H3> + +<IMG align=left SRC=pic/barnstable.gif>From <i>pogo</i>, Walt Kelly + +<p>Pleased to meet you. +<BR clear=left><HR> + +<H4>Introduction</H4> + +Note: The software contained in this distribution is available without +charge under the conditions set forth in the <A +HREF=copyright.htm>Copyright Notice</A>. + +<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 client +accuracies typically within a millisecond on LANs and up to a few tens +of milliseconds on WANs relative to a primary server synchronized 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. Some configurations include cryptographic +authentication to prevent accidental or malicious protocol attacks. + +<P>Background information on computer network time synchronization can +be found on the <A HREF=exec.htm>Executive Summary - Computer Network +Time Synchronization</A> page. Discussion on protocol conformance issues +and interoperability with previous NTP versions can be found in the <A +HREF=biblio.htm>Protocol Conformance Statement</A> page. Discussion on +year-2000 issues can be found in the <A HREF=y2k.htm>Year 2000 +Conformance Statement page</A>. Background information, bibliography and +briefing slides suitable for presentations can be found in the <A +HREF=http://www.eecis.udel.edu/~mills/ntp.htm> Network Time +Synchronization Project</A> page. + +<H4>Building and Installing NTP</H4> + +The <A HREF=build.htm>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 +in the <A HREF=config.htm>Configuration Options </A>and <A +HREF=release.htm>Release Notes </A>pages. + +<P>Bringing up a NTP primary server requires a radio or satellite +receiver or modem. The distribution includes hardware drivers for over +two dozen radio clocks and modem services. A list of the particular +receivers and modem drivers supported in the distribution is given in +the <A HREF=refclock.htm>Reference Clock Drivers </A>page. For most +popular workstations marketed by Digital, Sun 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. + +<H4>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=quick.htm>Quick Start</a> page may be useful to get a +simple workstation on the air with an existing server. + +<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.htm>Notes on +Configuring NTP and Setting up a NTP Subnet </A>page. However, in many +common cases involving simple network topologies and workstations, the +file data can be specified entirely on the command line. + +<P>The most important factor in providing accurate, reliable time is the +selection of modes and servers to be used in the configuration file. NTP +support for one or more computers is normally engineered as part of the +existing NTP synchronization subnet. The existing NTP 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>The NTP subnet in early 1998 includes 70 public primary (stratum 1) +servers synchronized directly to UTC by radio, satellite or modem and +located in every continent of the globe, except Antarctica (soon). +Normally, client workstations and servers with a relatively small number +of clients do not synchronize to primary servers. There are 106 public +secondary (stratum 2) servers synchronized to the primary servers and +providing synchronization to a total in excess of 100,000 clients and +servers in the Internet. The current lists are maintained in the <A +HREF=http://www.eecis.udel.edu/~mills/ntp/index.htm>Information on Time +and Frequency Services</A> page, which is updated frequently. There are +numerous private primary and secondary servers not normally available to +the public as well. You are strongly discouraged from using these +servers, since they sometimes hide in little ghettos behind dinky links +to the outside world and your traffic can bring up expensive ISDN lines, +causing much grief and frustration. + +<H4>Resolving Problems</H4> + +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 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.htm>NTP Debugging Techniques </A>and <A +HREF=hints.htm>Hints and Kinks </A>pages contain useful information +for identifying problems and devising solutions. + +<P>Users are requested to report bugs, offer suggestions and contribute +additions to this distribution. The <A HREF=patches.htm>Patching +Procedures </A>page suggests procedures which greatly simplify +distribution updates, while the <A HREF=porting.htm>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=refclock.htm>Reference Clock Drivers </A>page. Further +information on NTP in the Internet can be found in the <A +HREF=http://www.eecis.udel.edu/~ntp>NTP +web page</A>. + +<H4>Program Manual Pages</H4> + +<ul> + +<li><A HREF=ntpd.htm><TT>ntpd</TT> - Network Time Protocol (NTP) +daemon</A></LI> +<LI><A HREF=ntpq.htm><TT>ntpq</TT> - standard NTP query +program</A></LI> +<LI><A HREF=ntpdc.htm><TT>ntpdc</TT> - special NTP query +program</A></LI> +<LI><A HREF=ntpdate.htm><TT>ntpdate</TT> - set the date and time via +NTP</A></LI> +<LI><A HREF=ntptrace.htm><TT>ntptrace</TT> - trace a chain of NTP +servers back to the primary source</A></LI> +<LI><A HREF=tickadj.htm><TT>tickadj</TT> - set time-related kernel +variables</A></LI> +<LI><A HREF=ntptime.htm><TT>ntptime</TT> - read kernel time +variables</A></LI> + +</ul> + +<H4>Supporting Documentation</H4> + +<ul> + +<LI<A HREF=ntp.htm>NTP Reference Library</A></LI> +<LI><A HREF=copyright.htm>Copyright Notice</A></LI> +<LI><A HREF=exec.htm>Executive Summary - Computer Network Time +Synchronization</A></LI> +<LI><A HREF=biblio.htm>Protocol Conformance Statement</A></LI> +<LI><A HREF=y2k.htm>Year 2000 Conformance Statement</A></LI> +<LI><A HREF=notes.htm>Notes on Configuring NTP and Setting up a NTP +Subnet</A></LI> +<LI><A HREF=release.htm>NTP Version 4 Release Notes</A></LI> +<LI><A HREF=build.htm>Building and Installing the +Distribution</A></LI> +<LI><A HREF=config.htm>Configuration Options</A></LI> +<LI><A HREF=debug.htm>NTP Debugging Techniques</A></LI> +<LI><A HREF=refclock.htm>Reference Clock Drivers</A></LI> +<LI><A HREF=patches.htm>Patching Procedures</A></LI> +<LI><A HREF=hints.htm>Hints and Kinks</A></LI> +<LI><A HREF=porting.htm>Porting Hints</A></LI> + +</ul> + +<H4>Application Notes</H4> + +<ul> + +<LI><A HREF=prefer.htm>Mitigation Rules and the <TT>prefer</TT> +Keyword</A></LI> +<LI><A HREF=assoc.htm>Association Management</A></LI> +<LI><A HREF=pps.htm>Pulse-per-second (PPS) Signal Interfacing</A></LI> +<LI><A HREF=gadget.htm>Gadget Box PPS Level Converter and CHU +Modem</A></LI> +<LI><A HREF=measure.htm>Time and Time Interval Measurement with +Application to Computer and Network Performance Evaluation</A></LI> +<LI><A HREF=kern.htm>A Kernel Model for Precision Timekeeping</A></LI> +<LI><A HREF=kernpps.htm>A Kernel Programming Interface for Precision +Time Signals</A></LI> + +</ul> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/kern.htm b/contrib/ntp/html/kern.htm new file mode 100644 index 0000000..b1ee383 --- /dev/null +++ b/contrib/ntp/html/kern.htm @@ -0,0 +1,51 @@ +<HTML><HEAD><TITLE> +A Kernel Model for Precision Timekeeping +</TITLE></HEAD><BODY><H3> +A Kernel Model for Precision Timekeeping +</H3><HR> + +<P>The technical memorandum: <I>A Kernel Model for Precision +Timekeeping</I><A +HREF="http://www.eecis.udel.edu/~mills/database/memos/memo96b.ps"> +(PostScript) </A>describes an engineering model which implements 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 hybrid loop provides automatic +time and frequency steering with update intervals from a few seconds to +over one day. + +<P>The hybrid PLL/FLL has been implemented in the Unix kernels for +several workstations, including those made by Sun Microsystems, Digital +and Hewlett Packard. Currently, the modifications are in licensed +kernels for Digital Unix 4.0 and Sun Solaris 2.6. Since these specific +implementations involve modifications to licensed code, they cannot be +provided directly. Inquiries should be directed to the manufacturer's +representatives. In addition to the licensed kernels, the hybrid PLL/FLL +has been implemented in the nonlicensed kernels for Linux and FreeBSD. +The engineering model for these implementations, including a simulator +with code segments almost identical to the implementations, but not +involving licensed code, is available via the web at <A +HREF="http://www.eecis.udel.edu/~mills/ntp/ntp">kernel.tar.Z</A> or by +anonymous FTP from ftp.udel.edu in the <TT>pub/ntp</TT> directory. + +<P>The model changes the way the system clock is adjusted in time and +frequency, as well as provides mechanisms to discipline its time and +frequency to an external precision timing source, such as a pulse-per- +second (PPS) signal. The model incorporates a generic system-call +interface for use with the Network Time Protocol (NTP) or similar time +synchronization protocol. The NTP software daemons for Version 3 +<TT>xntpd</TT> and Version 4 <TT>ntpd</TT> operate with this model +to provide synchronization limited in principle only by the accuracy and +stability of the external timing source. There are two new system calls +defined in the model, <TT>ntp_gettime()</TT>, which returns a structure +including the current time, estimated error and maximum error, and +<TT>ntp_adjtime()</TT>, which provides a means to adjust kernel +variables, including the current time and frequency offsets. Further +information on the calling sequences and variable definitions are in the +<TT>/usr/include/sys/timex.h</TT> file. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/kernpps.htm b/contrib/ntp/html/kernpps.htm new file mode 100644 index 0000000..fe003f7 --- /dev/null +++ b/contrib/ntp/html/kernpps.htm @@ -0,0 +1,26 @@ +<html><head><title> +A Kernel Programming Interface for Precision Time Signals +Network Performance Evaluation +</title></head><body><h3> +A Kernel Programming Interface for Precision Time Signals +</h3><hr> + +<p>The technical memorandum: <cite>A Kernel Programming Interface for +Precision Time Signals</cite><a +href="http://www.eecis.udel.edu/~mills/database/memos/memo96c.ps"> +(PostScript) </a> describes a proposed programming interface for +external precision time signals, such as the pulse-per-second (PPS) +signal generated by some radio clocks and cesium oscillators. + +<p>The memorandum argues for a generic capability in the ubiquitous Unix +kernel, which could be used for a wide variety of measurement +applications, including network time synchronization and experiments +involving performance measurement and evaluation of computer networks +and transmission systems. 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. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/ldisc.htm b/contrib/ntp/html/ldisc.htm new file mode 100644 index 0000000..5dd7326 --- /dev/null +++ b/contrib/ntp/html/ldisc.htm @@ -0,0 +1,161 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> +<html><head><title> +Line Disciplines and Streams Modules +</title></head><body><h3> +Line Disciplines and Streams Modules +</h3><hr> + +<p><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 +timing jitter contributed by the serial port hardware and software +driver can accumulate to several milliseconds on a typical Unix +workstation. In order to reduce these errors, a set of special line +disciplines and stream modules can be configured in the Unix kernel. +These routines intercept special characters or signals provided by the +radio or modem clock and save a local timestamp for later processing. + +<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 +<code>ntpd</code>. The streams modules can be pushed and popped from +the streams stack using conventional System V streams program +primitives. Note that not all Unix kernels support line disciplines and +of those that do, not all support System V streams. The disciplines here +are known to work correctly with SunOS 4.x kernels, but have not been +tested for other kernels. + +<p>There are two line disciplines and a special streams module included +in the distribution. Support for each in <code>ntpd</code> is enabled +by adding flags to the <code>DEFS_LOCAL</code> line of the +<code>ntpd</code> configuration file <code>./Config.local</code>. This +can be done automatically by the autoconfiguration build procedures, or +can be inserted/deleted after the process has completed. + +<dl> + +<dt><code>tty_clk</code> +<dd>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 <code>timeval</code> format. Both +<code>select()</code> and <code>SIGIO</code> are supported by the +routine. The <code>-DTTYCLK</code> flag is used to compile support for +this discipline in <code>ntpd</code>. This flag is automatically +included if the <code>clkdefs.h</code> file is found in the +<code>/usr/include/sys</code> directory, or it can be added (or deleted) +manually. This module must be configured in the kernel during the kernel +build process, as described in the <code>README</code> file in the +<code>./kernel</code> directory. + +<p><dt><code>tty_chu</code> +<dd>This routine is a special purpose line discipline for receiving a +special timecode broadcast by Canadian time and frequency standard +station CHU. The radio signal is first demodulated by the 300-baud modem +included in the gadget box, then processed by the discipline and finally +processed by the CHU modem driver (type 7) described in the <a href = +"refclock.htm"> Reference Clock Drivers </a> page. This discipline +should be used in raw mode. The <code>-DCHUCLK</code> flag is used to +compile support for this discipline in <code>ntpd</code>. This flag is +automatically included if the <code>chudefs.h</code> file is found in +the <code>/usr/include/sys</code> directory, or it can be added (or +deleted) manually. This module must be configured in the kernel during +the kernel build process, as described in the <code>README</code> file +in the <code>./kernel</code> directory. +<p><dt><code>ppsclock</code> +<dd>This routine is a special purpose streams module which monitors the +state of the data carrier detect (DCD) modem interface signal. It is +normally used in connection with a pulse-per-second (PPS) signal +generated by some radio clocks, which requires a hardware level +converter/pulse generator, such as described in the <a href = +"gadget.htm"> Gadget Box PPS Level Converter and CHU Modem </a> page. +For each positive-going edge of the DCD signal, the +<code>ppsclock</code> module captures a timestamp in Unix +<code>timeval</code> format for later retrieval using a special +<code>ioctl()</code> system call. The <code>-DPPS</code> flag is used to +compile support for this module in <code>ntpd</code>. This flag is +automatically included if the <code>ppsclock.h</code> file is found in +the <code>/sys/sys</code> directory, or it can be added (or deleted) +manually. This module must also be configured in the kernel during the +kernel build process, as described in the <code>README</code> file in +the <code>./kernel</code> directory. + +</dl> + +<p>There are two versions of both the <code>tty_clk</code> and +<code>chu_clk</code> programs. The <code>tty_clk.c</code> and +<code>chu_clk.c</code> are designed for use with older BSD systems and +are compiled in the kernel. The <code>tty_clk_STREAMS.c</code> and +<code>chu_clk_STREAMS.c</code> are designed for use with System V +streams, in which case they 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 or both of these line +disciplines is in the <code>README</code> file in the +<code>./kernel</code> directory. + +<p><h4>How to Use the <code>tty_clk</code> Line Discipline</h4> + +<p>The tty_clk line discipline defines a new <code>ioctl()</code>, +<code>CLK_SETSTR</code>, which takes a pointer to a string of no more +than 32 characters. Until the first <code>CLK_SETSTR</code> is +performed, the discipline will simply pass through characters. Once it +is passed a string by <code>CLK_SETSTR</code>, any character in that +string will be immediately followed by a timestamp in Unix +<code>timeval</code> format. You can change the string whenever you want +by doing another <code>CLK_SETSTR</code>. 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 <code>CLK_SETSTR</code> +turns off timestamping. Passing <code>NULL</code> will produce undefined +results. + +<p><h4>How to Use the <code>tty_chu</code> Line Discipline</h4> + +<p>The tty_chu line discipline translates data received from the CHU +modem and returns <code>chucode</code> structures, as defined in +chudefs.h, and expected by the Scratchbuilt CHU Receiver reference clock +driver. Depending on the settings of <code>PEDANTIC</code> and +<code>ANAL_RETENTIVE</code> used when compiling the kernel, some +checking of the data may or may not be necessary. + +<p><h4>How to Use the <code>ppsclock</code> Stream Module</h4> + +<p>The ppsclock streams module implements an <code>ioctl() +CIOGETEV</code>, which takes a pointer to the structure + +<pre> +struct ppsclockev { + struct timeval tv; + u_int serial; +}; +</pre> + +<p>The ppsclock module is pushed on the streams stack of the serial port +connected to the PPS signal. The port must be configured for local +operation, rather than remote (modem) operation. At each positive-going +edge of the DCD signal, the routine latches the current local timestamp +and increments a counter. At each <code>CIOGETEV ioctl()</code> call, +the current values of the timestamp and counter are returned in the +<code>ppsclockev</code> structure. + +<p><h4>TIOCDCDTIMESTAMP timestamping</h4> + +<p>On FreeBSD 2.2 and later systems the TIOCDCDTIMESTAMP ioctl is used +to read the timestamp when the DCD serial go active. To use this the +PPS signal must be tied to the serial port DCD signal through the +appropriate level converters and pulse stretch circuitry if necessary. +This enhances the accuracy of the driver to a few microseconds. Using +FreeBSD 2.2 the measured delay between activation of the PPS signal and +the time the timestamp is made on a 66MHz 486DX2 is 19us and on a +100MHz Pentium is 6us. The driver does NOT compensate for this. + +<p>The TIOCDCDTIMESTAMP timestamping ioctl() is used automatically +on FreeBSD systems if available. It is integrated into the +refclock_gtlin() function so any driver using it will benefit from +the enhanced accuracy. + +<hr><address>David L. Mills (mills@udel.edu)</address></body></html> diff --git a/contrib/ntp/html/measure.htm b/contrib/ntp/html/measure.htm new file mode 100644 index 0000000..a06261d --- /dev/null +++ b/contrib/ntp/html/measure.htm @@ -0,0 +1,50 @@ +<html><head><title> +Time and Time Interval Measurement with Application to Computer and +Network Performance Evaluation +</title></head><body><h3> +Time and Time Interval Measurement with Application to Computer and +Network Performance Evaluation +</h3><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/~mills/database/memos/memo96a.ps"> +(PostScript) </a> describes a number of techniques for conducting +experiments typical of computer network and transmission systems +engineering. + +<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>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>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. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/miscopt.htm b/contrib/ntp/html/miscopt.htm new file mode 100644 index 0000000..af5ee3c --- /dev/null +++ b/contrib/ntp/html/miscopt.htm @@ -0,0 +1,162 @@ +<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>Miscellaneous Options +</TITLE> +</HEAD> +<BODY> + +<H3> +Miscellaneous Options</H3> + +<HR> +<DL> +<DT> +<TT>broadcastdelay <I>seconds</I></TT></DT> + +<DD> +The broadcast and multicast modes require a special calibration to determine +the network delay between the local and remote servers. Ordinarily, this +is done automatically by the initial protocol exchanges between the local +and remote servers. 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.</DD> + +<DD> + </DD> + +<DT> +<TT>trap <I>host_address</I> [port <I>port_number</I>] [interface <I>interface_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> + +<DD> + </DD> + +<DT> +<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> + +<DD> + </DD> + +<DT> +<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.</DD> + +<DD> + </DD> + +<DT> +<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. By +default, all output is turned on. 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>peer</TT>, +<TT>sys</TT> and <TT>sync</TT>). Within these classes four types of messages +can be controlled.</DD> + +<DD> +Informational messages (<TT>info</TT>) control configuration information. +Event messages (<TT>events</TT>) control logging of events (reachability, +synchronization, alarm conditions). Statistical output is controlled with +the <TT>statistics</TT> keyword. The final message group is the status +messages. This describes mainly the synchronizations status. Configuration +keywords are formed by concatenating the message class with the event class. +The <TT>allprefix</TT> 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.</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> +</DL> + +<H4> +Variables</H4> +Most variables used by the NTP protocol can be examined with the <TT>ntpdc</TT> +(mode 7 messages) and the <TT>ntpq</TT> (mode 6 messages). Currently, very +few variables can be modified via mode 6 messages. These variables are +either created with the <TT>setvar</TT> directive or the leap warning bits. +The leap warning bits can be set in the <TT>leapwarning</TT> variable up +to one month ahead. Both the <TT>leapwarning</TT> and <TT>leapindication</TT> +variables have a slightly different encoding than the usual leap bits interpretation: +<DL> +<DT> +<TT>00</TT></DT> + +<DD> +The daemon passes the leap bits of its synchronization source (usual mode +of operation).</DD> + +<DT> +<TT>01/10</TT></DT> + +<DD> +A leap second is added/deleted (operator forced leap second).</DD> + +<DT> +<TT>11</TT></DT> + +<DD> +Leap information from the synchronizations source is ignored (thus <TT>LEAP_NOWARNING</TT> +is passed on).</DD> +</DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/monopt.htm b/contrib/ntp/html/monopt.htm new file mode 100644 index 0000000..fc6ba84 --- /dev/null +++ b/contrib/ntp/html/monopt.htm @@ -0,0 +1,370 @@ +<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>Monitoring Options +</TITLE> +</HEAD> +<BODY> + +<H3> +Monitoring Options</H3> + +<HR> +<H4> +Monitoring Support</H4> +<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 ./scripts directory of this +distribution. Using these facilities and Unix <TT>cron</TT> jobs, the data +can be automatically summarized and archived for retrospective analysis. +<H4> +Monitoring Commands</H4> + +<DL> +<DT> +<TT>statistics <I>name</I> [...]</TT></DT> + +<DD> +Enables writing of statistics records. Currently, four kinds of <I><TT>name</TT></I> +statistics are supported.</DD> + +<DD> + </DD> + +<DL> +<DT> +<TT>loopstats</TT></DT> + +<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> + +<PRE>50935 75440.031 0.000006019 13.778190 0.000351733 0.013380 6</PRE> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>peerstats</TT></DT> + +<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>:</DD> + +<PRE>48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142</PRE> + +<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 A of the NTP specification RFC +1305. The final three fields show the offset, delay and RMS jitter, all +in seconds.</DD> + +<DD> + </DD> + +<DT> +<TT>clockstats</TT></DT> + +<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> + +<PRE>49213 525.624 127.127.4.1 93 226 00:08:29.606 D</PRE> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>rawstats</TT></DT> + +<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>:</DD> + +<DD> + </DD> + +<DD> +<TT>50928 2132.543 128.4.1.1 128.4.1.20 3102453281.584327000 3102453281.58622800031 +02453332.540806000 3102453332.541458000</TT></DD> + +<DD> +<TT> </TT></DD> + +<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 or clock +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.</DD> +</DL> + +<DD> + </DD> + +<DT> +<TT>statsdir <I>directory_path</I></TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>filegen <I>name</I> [file <I>filename</I>] [type <I>typename</I>] [link +| nolink] [enable | disable]</TT></DT> + +<DT> +<TT> </TT></DT> + +<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> + +<DD> + </DD> + +<DD> +Note that this command can be sent from the <TT>ntpdc</TT> program running +at a remote location.</DD> + +<DD> + </DD> + +<DL> +<DT> +<I><TT>name</TT></I></DT> + +<DD> +This is the type of the statistics records, as shown in the <TT>statististics</TT> +command.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>file <I>filename</I></TT></DD> + +<DL> +<DD> +This is the file name for the statistics records. Filenames of set members +are built from three elements:</DD> + +<DD> + </DD> + +<DL> +<DT> +prefix</DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<I><TT>filename</TT></I></DT> + +<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>.</DD> + +<DD> + </DD> + +<DT> +suffix</DT> + +<DD> +This part is reflects individual elements of a file set. It is generated +according to the type of a file set.</DD> +</DL> + +<DD> + </DD> +</DL> + +<DD> +<TT>type <I>typename</I></TT></DD> + +<DL> +<DD> +A file generation set is characterized by its type. The following types +are supported:</DD> + +<DD> + </DD> + +<DL> +<DT> +<TT>none</TT></DT> + +<DD> +The file set is actually a single plain file.</DD> + +<DD> + </DD> + +<DT> +<TT>pid</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>day</TT></DT> + +<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>.</DD> + +<DD> + </DD> + +<DT> +<TT>week</TT></DT> + +<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>.</DD> + +<DD> + </DD> + +<DT> +<TT>month</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>year</TT></DT> + +<DD> +One generation file element is generated per year. The filename suffix +consists of a dot and a 4 digit year number.</DD> + +<DD> + </DD> + +<DT> +<TT>age</TT></DT> + +<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>enabl</TT>; output is prevented by specifying <TT>disable</TT>.</DD> + +<DD> + </DD> +</DL> +</DL> + +<DD> +<TT>link | nolink</TT></DD> + +<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.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>enable | disable</TT></DD> + +<DL> +<DD> +Enables or disables the recording function.</DD> +</DL> +</DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/mx4200data.htm b/contrib/ntp/html/mx4200data.htm new file mode 100644 index 0000000..2123607 --- /dev/null +++ b/contrib/ntp/html/mx4200data.htm @@ -0,0 +1,445 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<HTML> +<HEAD> +<TITLE>MX4200 Receiver Data Format</TITLE> +<BODY> +<h1>MX4200 Receiver Data Format</h1> + +<hr> +<h2>Table of Contents</h2> + +<ul> + <li><a href="#control">Control Port Sentences</a></li> + <li><a href="#input">Control Port Input Sentences</a> + <ul> + <li> <a href="#input_000">$PMVXG,000</a> Initialization/Mode Control - Part A</li> + <li> <a href="#input_001">$PMVXG,001</a> Initialization/Mode Control - Part B</li> + <li> <a href="#input_007">$PMVXG,007</a> Control Port Configuration</li> + <li> <a href="#input_023">$PMVXG,023</a> Time Recovery Configuration</li> + <li> <a href="#input_gpq">$CDGPQ,YYY</a> Query From a Remote Device / Request to Output a Sentence</li> + </ul> + <li><a href="#output">Control Port Output Sentences</a> + <ul> + <li> <a href="#output_000">$PMVXG,000</a> Receiver Status + <li> <a href="#output_021">$PMVXG,021</a> Position, Height, Velocity + <li> <a href="#output_022">$PMVXG,022</a> DOPs + <li> <a href="#output_030">$PMVXG,030</a> Software Configuration + <li> <a href="#output_101">$PMVXG,101</a> Control Sentence Accept/Reject + <li> <a href="#output_523">$PMVXG,523</a> Time Recovery Configuration + <li> <a href="#output_830">$PMVXG,830</a> Time Recovery Results + </ul> +</ul> + +<hr> + +<h2><a name="control">Control Port Sentences</a></h2> + +<p>The Control (CDU) Port is used to initialize, monitor, and control +the receiver. The structure of the control port sentences is based on +the <cite>NMEA-0183</cite> Standard for Interfacing Marine Electronics +Navigation Devices (version 1.5). For more details, please refer to +the <cite>NMEA-0183</cite> Specification available from the <a +href="http://www.nmea.org/"> National Marine Electronics +Association</a>.</p> + +<p>Reserved characters are used to indicate the beginning and the end +of records in the data stream, and to delimit data fields within a +sentence. Only printable ASCII characters (Hex 20 through 7F) may be +used in a sentence. <a href="#table_2">Table 2</a> lists the reserved +characters and defines their usage. <a href="#table_1">Table 1</a> +illustrates the general Magnavox proprietary NMEA sentence format. +</p> + +<h4><a name="table_1">Table 1. Magnavox Proprietary NMEA Sentence +Format</a></h4> + +<p> +<code> +$PMVXG,XXX,...................*CK +</code> + +<p> + +<table border> + <tr> <th>Character <th>Meaning + <tr> <td><code>$</code> <td>Sentence Start Character + <tr> <td><code>P</code> <td>Special ID (P = Proprietary) + <tr> <td><code>MVX</code> <td>Originator ID (MVX = Magnavox) + <tr> <td><code>G</code> <td>Interface ID (G = GPS) + <tr> <td><code>XXX</code> <td>Sentence Type + <tr> <td><code>...</code> <td>Data + <tr> <td><code>*</code> <td>Optional Checksum Field Delimiter + <tr> <td><code>CK</code> <td>Optional Checksum +</table> + +<h4><a name="table_2">Table 2. NMEA Sentence Reserved Characters</a></h4> + +<table border> + <tr> <th>Character <th>Hex Value <th>Usage + <tr> <td><code>$</code> <td>24 <td>Start of Sentence Identifier + <tr> <td><code>{cr}{lf}</code> <td>0D 0A <td>End of Sentence Identifier + <tr> <td><code>,</code> <td>2C <td>Sentence Delimiter + <tr> <td><code>*</code> <td>2A <td>Optional Checksum Field Delimiter +</table> + +<p>Following the start character <code>$</code>, are five characters +which constitute the block label of the sentence. For Magnavox +proprietary sentences, this label is always <code>PMVXG</code>. The +next field after the block label is the sentence type, consisting of +three decimal digits.</p> + +<p>The data, delimited by commas, follows the sentence type. Note that +the receiver uses a free-format parsing algorithm, so you need not send +the exact number of characters shown in the examples. You will need to +use the commas to determine how many bytes of data need to be +retrieved.</p> + +<p>The notation <code>CK</code> shown in <a href="#table_1">Table 1</a> +symbolically indicates the optional checksum in the examples. The +checksum is computed by exclusive-ORing all of the bytes between the +<code>$</code> and the <code>*</code> characters. The <code>$</code> , +<code>*</code> and the checksum are not included in the checksum +computation.</p> + +<p>Checksums are optional for Control Port input sentences, but are +highly recommended to limit the effects of communication errors. +Magnavox receivers always generate checksums for Control Port output +sentences.</p> + +<p>ASCII data characters are transmitted in the following format:</p> + +<table border> + <tr> <td> Data Bits <td>8 (msb always 0) + <tr> <td> Parity <td>None + <tr> <td> Stop Bits <td>1 +</table> + +<p>NULL fields are fields which do not contain any data. They would +appear as two commas together in the sentence format, except for the +final field. Some Magnavox proprietary sentences require that the +format contain NULL fields. mandatory NULL fields are identified by an +'*' next to the respective field.</p> + +<hr> + +<h2><a name="input">Control Port Input Sentences</a></h2> +These are the subset of the MX4200 control port input sentences sent by +the NTP driver to the GPS receiver. + +<hr> + +<h3><a name="input_000">$PMVXG,000</a></h3> +<h4>Initialization/Mode Control - Part A</h4> +Initializes the time, position and antenna height of the MX4200. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Default <th>Range + <tr> <td>1 <td>Day <td> <td>Int <td> <td>1-31 + <tr> <td>2 <td>Month <td> <td>Int <td> <td>1-12 + <tr> <td>3 <td>Year <td> <td>Int <td> <td>1991-9999 + <tr> <td>4 <td>GMT Time <td>HHMMSS <td>Int <td> <td>000000-235959 + <tr> <td>5 <td>WGS-84 Latitude <td>DDMM.MMMM<td>Float<td>0.0 <td>0 - 8959.9999 + <tr> <td>6 <td>North/South Indicator <td> <td>Char <td>N <td>N,S + <tr> <td>7 <td>WGS-84 Longitude <td>DDDMM.MMMM<td>Float<td>0.0 <td>0 - 17959.9999 + <tr> <td>8 <td>East/West Indicator <td> <td>Char <td>E <td>E,W + <tr> <td>9 <td>Altitude (height above Mean Sea Level) in meters (WGS-84) <td>Meters<td>Float<td>0.0<td>+/-99999.0 + <tr> <td>10 <td>Not Used <td> <td> <td> <td> +</table> +Example:<br> +<code>$PMVXG,000,,,,,,,,,,*48</code><br> +<code>$PMVXG,000,,,,,5128.4651,N,00020.0715,W,58.04,*4F</code> + +<hr> + +<h3><a name="input_001">$PMVXG,001</a></h3> +<h4>Initialization/Mode Control - Part B</h4> +Specifies various navigation parameters: Altitude aiding, acceleration +DOP limits, and satellite elevation limits. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Default <th>Range + <tr> <td>*1 <td>Constrain Altitude <td> <td>Int <td>1 <td>0=3D Only<br>1=Auto<br>2=2D Only + <tr> <td>2 <td>Not Used <td> <td> <td> <td> + <tr> <td>*3 <td>Horizontal Acceleration Factor<td>m/sec^2 <td>Float <td>1.0 <td>0.5-10.0 + <tr> <td>*4 <td>Not Used <td> <td> <td> <td> + <tr> <td>*5 <td>VDOP Limit <td> <td>Int <td>10 <td>1-9999 + <tr> <td>*6 <td>HDOP Limit <td> <td>Int <td>10 <td>1-9999 + <tr> <td>7 <td>Elevation Limit <td>Deg <td>Int <td>5 <td>0-90 + <tr> <td>8 <td>Time Output Mode <td> <td>Char <td>U <td>U=UTC<br>L=Local Time + <tr> <td>9 <td>Local Time Offset <td>HHMM <td>Int <td>0 <td>+/- 0-2359 +</table> +Example:<br> +<code>$PMVXG,001,3,,0.1,0.1,10,10,5,U,0*06</code> + +<hr> + + +<h3><a name="input_007">$PMVXG,007</a></h3> +<h4>Control Port Output Configuration</h4> +This message enables or disables output of the specified sentence and +defines the output rate. The user sends this message for each sentence +that the receiver is to output. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Default <th>Range + <tr> <td>1 <td>Control Port Output Block Label<td> <td>Char <td> <td> + <tr> <td>2 <td>Clear Current Output List<td> <td>Int <td> <td>0=No<br>1=Yes + <tr> <td>3 <td>Add/Delete Sentence from List<td> <td>Int <td> <td>1=Append<br>2=Delete + <tr> <td>4 <td>Not Used <td> <td> <td> <td> + <tr> <td>5 <td>Sentence Output Rate <td>Sec <td>Int <td> <td>1-9999 + <tr> <td>6 <td># digits of Precision for CGA and GLL sentences<td> <td>Int <td>2 <td>2-4 + <tr> <td>7 <td>Not Used <td> <td> <td> <td> + <tr> <td>8 <td>Not Used <td> <td> <td> <td> +</table> +Example:<br> +<code>$PMVXG,007,022,0,1,,1,,,*4F</code> + +<hr> + + +<h3><a name="input_023">$PMVXG,023</a></h3> +<h4>Time Recovery Configuration</h4> +This message is used to enable/disable the time recovery feature of the +receiver. The time synchronization for the 1PPS output is specified in +addition to a user time bias and an error tolerance for a valid pulse. +This record is accepted in units configured for time recovery. If the +back panel contains a 1PPS outlet, the receiver is a time recovery +unit. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Default <th>Range + <tr> <td>*1 <td>Time Recovery Mode <td> <td>Char <td>D <td>D=Dynamic<br>S=Static<br>K=Known Position<br>N=No Time Recovery + <tr> <td>2 <td>Time Synchronization <td> <td>Char <td>G <td>U=UTC<br>G=GPS + <tr> <td>3 <td>Time Mark Mode <td> <td>Char <td>A <td>A=Always<br>V=Valid Pulses Only + <tr> <td>4 <td>Maximum Time Error <td>Nsec <td>Int <td>100 <td>50-1000 + <tr> <td>5 <td>User Time Bias <td>Nsec <td>Int <td>0 <td>+/- 99999 + <tr> <td>6 <td>ASCII Time Message Control<td> <td>Int <td>0 <td>0=No Output<br>1=830 to Control Port<br>2=830 to Equipment Port + <tr> <td>7 <td>Known Pos PRN <td> <td>Int <td>0 <td>1-32<br>0=Track All Sats +</table> +Example:<br> +<code>$PMVXG,023,S,U,A,500,0,1,*16</code> + +<hr> + + +<h3><a name="input_gpq">$CDGPQ,YYY</a></h3> +<h4>Query From a Remote Device / Request to Output a Sentence</h4> +Enables the controller to request a one-time transmission of a specific +block label. To output messages at a periodic rate, refer to input +sentence <a href="#input_007">$PMVXG,007</a>. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Default <th>Range + <tr> <td>1:CD <td>ID of Remote Device <td> <td>Char <td> <td>(See <cite>NMEA-0183</cite>) + <tr> <td>2:GP <td>GPS <td> <td>Char <td> <td>(See <cite>NMEA-0183</cite>) + <tr> <td>3:Q <td>Query <td> <td>Char <td> <td>(See <cite>NMEA-0183</cite>) + <tr> <td>4:YYY <td>Label of Desired Sentence<td> <td>Char <td> <td>Any Valid NMEA or Magnavox Sentence Type +</table> +Example:<br> +<code>$CDGPQ,030*5E</code> + + + +<hr> +<h2><a name="output">Control Port Output Sentences</a></h2> +These are the subset of the MX4200 control port output sentences +recognized by the NTP driver. + +<hr> + +<h3><a name="output_000">$PMVXG,000</a></h3> +<h4>Receiver Status</h4> +Returns the current status of the receiver including the operating +mode, number of satellites visible, and the number of satellites being +tracked. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>Current Receiver Status <td> <td>Char <td>ACQ=Reacquisition<br>ALT=Constellation Selection<br>IAC=Initial Acquisition<br>IDL=Idle, No Satellites<br>NAV=Navigating<br>STS=Search The Sky<br>TRK=Tracking + <tr> <td>2 <td>Number of Satellites that should be Visible <td> <td>Int <td>0-12 + <tr> <td>3 <td>Number of Satellites being Tracked <td> <td>Int <td>0-12 + <tr> <td>4 <td>Time since Last Navigation <td>HHMM <td>Int <td>0-2359 + <tr> <td>5 <td>Initialization Status <td> <td>Int <td>0=Waiting for Initialization<br>1=Initialization Complete +</table> +Example:<br> +<code>$PMVXG,000,TRK,3,3,0122,1*19</code> + +<hr> + +<h3><a name="output_021">$PMVXG,021</a></h3> +<h4>Position, Height, Velocity</h4> +This sentence gives the receiver position, height, navigation mode and +velocity north/east. <em>This sentence is intended for post analysis +applications.</em> + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>UTC Measurement Time <td>Seconds into the week<td>Float<td>0-604800.00 + <tr> <td>2 <td>WGS-84 Latitude <td>DDMM.MMMM<td>Float <td>0-89.9999 + <tr> <td>3 <td>North/South Indicator <td> <td>Char <td>N, S + <tr> <td>4 <td>WGS-84 Longitude <td>DDDMM.MMMM <td>Float <td>0-179.9999 + <tr> <td>5 <td>East/West Indicator <td> <td>Char <td>E, W + <tr> <td>6 <td>Altitude (MSL) <td>Meters <td>Float <td> + <tr> <td>7 <td>Geoidal Height <td>Meters <td>Float <td> + <tr> <td>8 <td>Velocity East <td>M/Sec <td>Float <td> + <tr> <td>9 <td>Velocity North <td>M/Sec <td>Float <td> + <tr> <td>10 <td>Navigation Mode <td> <td>Int <td><em>Navigating</em><br> + 1=Position From a Remote Device<br> + 2=2D<br> + 3=3D<br> + 4=2D differential<br> + 5=3D differential<br> + <em>Not Navigating</em><br> + 51=Too Few Satellites<br> + 52=DOPs too large<br> + 53=Position STD too large<br> + 54=Velocity STD too large<br> + 55=Too many iterations for velocity<br> + 56=Too many iterations for position<br> + 57=3 Sat Startup failed +</table> +Example:<br> +<code>$PMVXG,021,142244.00,5128.4744,N,00020.0593,W,00054.4,0047.4,0000.1,-000.2,03*66</code> + +<hr> + +<h3><a name="output_022">$PMVXG,022</a></h3> +<h4>DOPs</h4> +This sentence reports the DOP (Dilution Of Precision) values actually +used in the measurement processing corresponding to the satellites +listed. The satellites are listed in receiver channel order. Fields +11-16 are output only on 12-channel receivers. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>UTC Measurement Time <td>Seconds into the week<td>Float<td>0-604800.00 + <tr> <td>2 <td>East DOP (EDOP) <td> <td>Float <td> + <tr> <td>3 <td>North DOP (NDOP) <td> <td>Float <td> + <tr> <td>4 <td>Vertical DOP (VDOP) <td> <td>Float <td> + <tr> <td>5 <td>PRN on Channel #1 <td> <td>Int <td>1-32 + <tr> <td>6 <td>PRN on Channel #2 <td> <td>Int <td>1-32 + <tr> <td>7 <td>PRN on Channel #3 <td> <td>Int <td>1-32 + <tr> <td>8 <td>PRN on Channel #4 <td> <td>Int <td>1-32 + <tr> <td>9 <td>PRN on Channel #5 <td> <td>Int <td>1-32 + <tr> <td>10 <td>PRN on Channel #6 <td> <td>Int <td>1-32 + <tr> <td>11 <td>PRN on Channel #7 <td> <td>Int <td>1-32 + <tr> <td>12 <td>PRN on Channel #8 <td> <td>Int <td>1-32 + <tr> <td>13 <td>PRN on Channel #9 <td> <td>Int <td>1-32 + <tr> <td>14 <td>PRN on Channel #10 <td> <td>Int <td>1-32 + <tr> <td>15 <td>PRN on Channel #11 <td> <td>Int <td>1-32 + <tr> <td>16 <td>PRN on Channel #12 <td> <td>Int <td>1-32 +</table> +Example:<br> +<code>$PMVXG,022,142243.00,00.7,00.8,01.9,27,26,10,09,13,23*77</code> + +<hr> + +<h3><a name="output_030">$PMVXG,030</a></h3> +<h4>Software Configuration</h4> +This sentence contains the navigation processor and baseband firmware +version numbers. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>Nav Processor Version Number <td> <td>Char <td> + <tr> <td>2 <td>Baseband Firmware Version Number <td> <td>Char <td> +</table> +Example:<br> +<code>$PMVXG,030,DA35,015</code> + +<hr> + +<h3><a name="output_101">$PMVXG,101</a></h3> +<h4>Control Sentence Accept/Reject</h4> +This sentence is returned (on the Control Port) for every +<strong>$PMVXG</strong> and <strong>$XXGPQ</strong> sentence that is +received. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>Sentence ID <td> <td>Char <td> + <tr> <td>2 <td>Accept/Reject Status <td> <td>Int <td>0=Sentence Accepted<br> + 1=Bad Checksum<br> + 2=Illegal Value<br> + 3=Unrecognized ID<br> + 4=Wrong # of fields<br> + 5=Required Data Field Missing<br> + 6=Requested Sentence Unavailable + <tr> <td>3 <td>Bad Field Index <td> <td>Int <td> + <tr> <td>4 <td>Requested Sentence ID (If field #1 = GPQ) <td> <td>Char <td> +</table> +Example:<br> +<code>$PMVXG,101,GPQ,0,,030*0D</code> + +<hr> + +<h3><a name="output_523">$PMVXG,523</a></h3> +<h4>Time Recovery Configuration</h4> +This sentence contains the configuration of the time recovery function +of the receiver. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>Time Recovery Mode <td> <td>Char <td>D=Dynamic<br>S=Static<br>K=Known Position<br>N=No Time Recovery + <tr> <td>2 <td>Time Synchronization <td> <td>Char <td>U=UTC Time<br>G=GPS Time + <tr> <td>3 <td>Time Mark Mode <td> <td>Char <td>A=Always Output Time Pulse<br>V=Only when Valid + <tr> <td>4 <td>Maximum Time Error for which a time mark will be considered valid <td>Nsec <td>Int <td> + <tr> <td>5 <td>User Time Bias <td>Nsec <td>Int <td> + <tr> <td>6 <td>Time Message Control <td> <td>Int <td>0=No Message<br>1=830 to Control Port<br>2=830 to Equipment Port + <tr> <td>7 <td>Not Used <td> <td> <td> +</table> +Example:<br> +<code>$PMVXG,523,S,U,A,0500,000000,1,0*23</code> + +<hr> + +<h3><a name="output_830">$PMVXG,830</a></h3> +<h4>Time Recovery Results</h4> +This sentence is output approximately 1 second preceding the 1PPS +output. It indicates the exact time of the next pulse, whether or not +the time mark will be valid (based on operator-specified error +tolerance), the time to which the pulse is synchronized, the receiver +operating mode, and the time error of the <strong>last</strong> 1PPS +output. The leap second flag (Field #11) is not output by older +receivers. + +<p> +<table border> + <tr> <th>Field <th>Description <th>Units <th>Format <th>Range + <tr> <td>1 <td>Time Mark Valid <td> <td>Char <td>T=Valid<br>F=Not Valid + <tr> <td>2 <td>Year <td> <td>Int <td>1993- + <tr> <td>3 <td>Month <td> <td>Int <td>1-12 + <tr> <td>4 <td>Day <td>Nsec <td>Int <td>1-31 + <tr> <td>5 <td>Time <td>HH:MM:SS<td>Int <td>00:00:00-23:59:59 + <tr> <td>6 <td>Time Synchronization <td> <td>Char <td>U=UTC<br>G=GPS + <tr> <td>7 <td>Operating Mode <td> <td>Char <td>D=Dynamic<br>S=Static<br>K=Known Position + <tr> <td>8 <td>Oscillator Offset - estimate of oscillator frequency error <td>PPB <td>Int <td> + <tr> <td>9 <td>Time Mark Error of last pulse <td>Nsec <td>Int <td> + <tr> <td>10 <td>User Time Bias <td>Nsec <td>Int <td> + <tr> <td>11 <td>Leap Second Flag - indicates that a leap second will occur. + This value is usually zero except during the week + prior to a leap second occurence, when this value + will be set to +/-1. A value of +1 indicates + that GPS time will be 1 second further ahead of + UTC time. + <td> <td>Int <td>-1,0,1 +</table> +Example:<br> +<code>$PMVXG,830,T,1998,10,12,15:30:46,U,S,000298,00003,000000,01*02</code> + +<hr> + + +</BODY> +</HTML> diff --git a/contrib/ntp/html/notes.htm b/contrib/ntp/html/notes.htm new file mode 100644 index 0000000..6b20cbc --- /dev/null +++ b/contrib/ntp/html/notes.htm @@ -0,0 +1,1544 @@ +<HTML><HEAD><TITLE> +Notes on Configuring NTP and Setting up a NTP Subnet</H3> +</TITLE></HEAD><BODY><H3> +Notes on Configuring NTP and Setting up a NTP Subnet</H3> +</H3> + +<img align=left src=pic/tonea.gif> +From NBS Special Publication 432 (out of print) +<br clear=left> + +<H4>Introduction</H4> + +This document is a collection of notes concerning the use of ntpd and +relatedprograms, 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><TT>ntpd</TT> includes a complete implementation of the NTP Version +3 specification, as defined in: + +<ul> + +<p><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/~mills/database/rfc/rfc1305/rfc1305a.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305a.pdf> +PDF</a>, Body: <a +href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.pdf> +PDF</a>, Appendices: <a +href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.ps> +PostScript</a> | <a +href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.pdf> +PDF</a> + +</ul> +Additional features have are described for <A HREF="release.htm">NTP +Version 4</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>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/~mills/database/rfc2030.txt"> +(ASCII)</A>. + +<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>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="biblio.htm">Further Information and Bibliography</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>The NTP Version 4 distribution includes, in addition to the daemon +itself (<TT><A HREF="ntpd.htm">ntpd</A></TT>), several utility programs, +including two remote-monitoring programs (<A HREF="ntpq.htm"> +<TT>ntpq</TT></A>, <TT><A HREF="ntpdc.htm">ntpdc</A></TT>), a remote +clock-setting program similar to the Unix rdate program +(<TT>ntpdate</TT>), a traceback utility u seful 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>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. + +<H4>How NTP Works</H4> + +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>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>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>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>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>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>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>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. +<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.htm">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/~ntp">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.htm">ntptrace</A></TT> +and <TT><A HREF="ntpdc.htm">ntpdc</A></TT> programs. + +<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>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>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>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>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>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>When planning your network you might, beyond this, keep in mind a few +generic don'ts, in particular: +<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> + +<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> +<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.</LI> +</UL> +There are many useful exceptions to these rules. When in doubt, however, +follow them. +<H4> +Configuring Your Server or Client</H4> +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): +<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>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>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>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>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. + +<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 int he NetInfo directory +<TT>/locations/ntp</TT> for property/value pairs which are equivalent +the the lines in the configuration file described above. Each +configuration keyword may have a coresponding 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>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. + +<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 +feaures documented in the <A HREF="release.htm">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>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 +<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 pollers 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: +<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.htm"><TT>ntpd</TT> +</A>page. + +<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: +<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. +<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.htm">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: +<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 overriden by +the <TT>authdelay </TT>line, which is used as a correction for the +transmit +timestamp. This can be computed for your CPU by the <A +HREF="authspeed.htm"><TT>authspeed</TT> +</A>program included in the distribution. The usage is illustrated by +the +following: +<PRE> # for DES keys + + authspeed -n 30000 auth.samplekeys + # for MD5 keys + + authspeed -mn 30000 auth.samplekeys</PRE> +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: +<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 +cruptography and avoids the key file entirely. While this feature is not +completely finished yet, details can be found in the <A +HREF="release.htm">Release +Notes</A> page. +<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><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. +<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: +<PRE> +Value Action + + +00 &nbs +p; The daemon passes the leap bits of its + + +synchronisation source (usual mode of operation) + + 01/10 A leap +second is added/deleted + + +11 &nbs +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. +<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>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. +<H4> +<A NAME="frequency_tolerance">Dealing with Frequency Tolerance +Violations</A> + (<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>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 accurace of the time +service. + +<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>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>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: +<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. +<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.htm">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: +<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. +<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: +<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.htm">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>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>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.htm">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="gadget.htm">Gadget +Box PPS Level Converter and CHU Modem </A>document 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>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. +<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><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/ntpd.htm b/contrib/ntp/html/ntpd.htm new file mode 100644 index 0000000..a90dfcb --- /dev/null +++ b/contrib/ntp/html/ntpd.htm @@ -0,0 +1,183 @@ +<HTML><HEAD><TITLE> +<TT>ntpd</TT> - Network Time Protocol (NTP) daemon +</TITLE></HEAD><BODY><H3> +<TT>ntpd</TT> - Network Time Protocol (NTP) daemon +</H3><HR> + +<H4>Synopsis</H4> + +<TT>ntpd [ -aAbdm ] [ -c <I>conffile</I> ] [ -f <I>driftfile</I> ] [ -k +<I>keyfile</I> ] [ -l <I>logfile</I> ] [ -p <I>pidfile</I> ] [ -r +<I>broadcastdelay</I> ] [ -s <I>statsdir</I> ] [ -t <I>key</I> ] [ -v +<I>variable</I> ] [ -V +<I>variable</I> ]</TT> + +<H4>Description</H4> + +<TT>ntpd</TT> is an operating system daemon which sets and maintains the +system time-of-day in synchronism with Internet standard time servers. +<TT>ntpd</TT> 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 unltimate precision, +about 232 picoseconds. While the ultimate precision, is not achievable +with ordinary workstations and networks of today, it may be required +with future nanosecond CPU clocks and gigabit LANs. + +<P>The daemon can operate in any of several modes, including symmetric +active/passive, client/server broadcast/multicast and manycast. 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>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 appropriate when the +local host is to be configured as a broadcast/multicast client or +manycast client, with all peers being determined by listening to +broadcasts at run time. + +<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>Various internal <TT>ntpd</TT> variables can be displayed and +configuration options altered while the daemon is running using the +<TT><A HREF="ntpq.htm">ntpq</A></TT> and <TT><A +HREF="ntpdc.htm">ntpdc</A></TT> utility programs. + +<P>When <TT>ntpd</TT> starts it looks at the value of <TT>umask</TT>, +and if it's zero <TT>ntpd</TT> will set the <TT>umask</TT> to +<TT>022</TT>. + +<H4>Command Line Options</H4> + +<DL> + +<DT><TT>-a</TT></DT> +<DD>Enable authentication mode (default).</DD> + +<DT><TT>-A</TT></DT> +<DD>Disable authentication mode.</DD> + +<DT><TT>-b</TT></DT> +<DD>Synchronize using NTP broadcast messages.</DD> + +<DT><TT>-c <I>conffile</I></TT></DT> +<DD>Specify the name and path of the configuration file.</DD> + +<DT><TT>-d</TT></DT> +<DD>Specify debugging mode. This flag may occur multiple times, with +each occurrence indicating greater detail of display.</DD> + +<DT><TT>-D <I>level</I></TT></DT> +<DD>Specify debugging level directly.</DD> + +<DT><TT>-f <I>driftfile</I></TT></DT> +<DD>Specify the name and path of the drift file.</DD> + +<DT><TT>-g</TT></DT> +<DD>Normally, the daemon exits if the offset exceeds a 1000-s sanity +limit. This option overrides this limit and allows the time to be set to +any value without restriction.</DD> + +<DT><TT>-k <I>keyfile</I></TT></DT> +<DD>Specify the name and path of the file containing the NTP +authentication keys.</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 facility.</DD> + +<DT><TT>-m</TT></DT> +<DD>Synchronize using NTP multicast messages on the IP multicast group +address 224.0.1.1 (requires multicast kernel).</DD> + +<DT><TT>-p <I>pidfile</I></TT></DT> +<DD>Specify the name and path to record the daemon's process ID.</DD> + +<DT><TT>-P</TT></DT> +<DD>Override the priority limit set by the operating system. Not +recommended for sissies.</DD> + +<DT><TT>-r <I>broadcastdelay</I></TT></DT> +<DD>Specify the default propagation delay from the broadcast/multicast +server and this computer. 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.</DD> + +<DT><TT>-t <I>key</I></TT></DT> +<DD>Add a key number to the trusted key list.</DD> + +<DT><TT>-v <I>variable</I></TT></DT> +<DT><TT>-V <I>variable</I></TT></DT> +<DD>Add a system variable listed by default.</DD> + +<DT><TT>-x</TT></DT> +<DD>Ordinarily, if the time is to be adjusted more than 128 ms, it is +stepped, not gradually slewed. This option forces the time to be slewed +in all cases. Note: Since the slew rate is limited to 0.5 ms/s, each +second of adjustment requires an amortization interval of 2000 s. Thus, +an adjustment of many seconds can take hours or days to amortize.</DD> + +</DL> + +<H4>The Configuration File</H4> + +The <TT>ntpd</TT> configuration file is read at initial startup in order +to specify the synchronization sources, modes and other related +information. Usually, it 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. 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>See the following pages for configuration and control options. While +there is a rich set of options available, the only required option is +one or more <TT>server, peer,</TT> <TT>broadcast</TT> or +<TT>manycastclient </TT>commands described in the Configuration Options +page. The <A HREF="notes.htm">Notes on Configuring NTP and Setting up a +NTP Subnet </A>page contains an extended discussion of these options. + +<P><A HREF="confopt.htm">Configuration Options</A> +<BR><A HREF="authopt.htm">Authentication Options</A> +<BR><A HREF="monopt.htm">Monitoring Options</A> +<BR><A HREF="accopt.htm">Access Control Options</A> +<BR><A HREF="clockopt.htm">Reference Clock Options</A> +<BR><A HREF="miscopt.htm">Miscellaneous Options</A> + +<H4>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 + +<H4>Bugs</H4> + +<TT>ntpd</TT> has gotten rather fat. While not huge, it has gotten +larger than might be desireable for an elevated-priority daemon running +on a workstation, particularly since many of the fancy features which +consume the space were designed more with a busy primary server, rather +than a high stratum workstation, in mind. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/ntpdate.htm b/contrib/ntp/html/ntpdate.htm new file mode 100644 index 0000000..a7f532f --- /dev/null +++ b/contrib/ntp/html/ntpdate.htm @@ -0,0 +1,185 @@ +<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>ntpdate - set the date and time via NTP +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>ntpdate</TT> - set the date and time via NTP</H3> + +<HR> +<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>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><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>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>. + +<H4> +Command Line Options</H4> + +<DL> +<DT> +<TT>-a <I>key</I></TT></DT> + +<DD> +Enable the authentication function and specify the key identifier to be +used for authentication as the argument <I>key</I><TT>ntpdate</TT>. The +keys and key identifiers must match in both the client and server key files. +The default is to disable the authentication function.</DD> + +<DT> +<TT>-B</TT></DT> + +<DD> +Force the time to always be slewed using the adjtime() system call, even +if the measured offset is greater than +-128 ms. The default is to step +the time using settimeofday() if the offset is greater than +-128 ms. Note +that, if the offset is much greater than +-128 ms in this case, that it +can take a long time (hours) to slew the clock to the correct value. During +this time. the host should not be used to synchronize clients.</DD> + +<DT> +<TT>-b</TT></DT> + +<DD> +Force the time to be stepped using the settimeofday() system call, rather +than slewed (default) using the adjtime() system call. This option should +be used when called from a startup file at boot time.</DD> + +<DT> +<TT>-d</TT></DT> + +<DD> +Enable the debugging mode, in which <TT>ntpdate</TT> will go through all +the steps, but not adjust the local clock. Information useful for general +debugging will also be printed.</DD> + +<DT> +<TT>-e <I>authdelay</I></TT></DT> + +<DD> +Specify the processing delay to perform an authentication function as the +value <I>authdelay</I>, in seconds and fraction (see <TT>ntpd</TT> for +details). This number is usually small enough to be negligible for most +purposes, though specifying a value may improve timekeeping on very slow +CPU's.</DD> + +<DT> +<TT>-k <I>keyfile</I></TT></DT> + +<DD> +Specify the path for the authentication key file as the string <I>keyfile</I>. +The default is <TT>/etc/ntp.keys</TT>. This file should be in the format +described in <TT>ntpd</TT>.</DD> + +<DT> +<TT>-o <I>version</I></TT></DT> + +<DD> +Specify the NTP version for outgoint packets as the integer <I>version</I>, +which can be 1 or 2. The default is 3. This allows <TT>ntpdate</TT> to +be used with older NTP versions.</DD> + +<DT> +<TT>-p <I>samples</I></TT></DT> + +<DD> +Specify the number of samples to be acquired from each server as the integer +<I>samples</I>, with values from 1 to 8 inclusive. The default is 4.</DD> + +<DT> +<I><TT>-q</TT></I></DT> + +<DD> +Query only - don't set the clock.</DD> + +<DT> +<TT>-s</TT></DT> + +<DD> +Divert logging output from the standard output (default) to the system +<TT>syslog</TT> facility. This is designed primarily for convenience of +<TT>cron</TT> scripts.</DD> + +<DT> +<TT>-t <I>timeout</I></TT></DT> + +<DD> +Specify the maximum time waiting for a server response as the value <I>timeout</I>, +in seconds and fraction. The value is is rounded to a multiple of 0.2 seconds. +The default is 1 second, a value suitable for polling across a LAN.</DD> + +<DT> +<TT>-u</TT></DT> + +<DD> +Direct <TT>ntpdate</TT> to use an unprivileged port or outgoing packets. +This is most useful when behind a firewall that blocks incoming traffic +to privileged ports, and you want to synchronise with hosts beyond the +firewall. Note that the <TT>-d</TT> option always uses unprivileged ports.</DD> + +<DT> +<TT>-<I>v</I></TT></DT> + +<DD> +Be verbose. This option will cause <TT>ntpdate</TT>'s version identification +string to be logged.</DD> +</DL> + +<H4> +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> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/ntpdc.htm b/contrib/ntp/html/ntpdc.htm new file mode 100644 index 0000000..52d1fdf --- /dev/null +++ b/contrib/ntp/html/ntpdc.htm @@ -0,0 +1,620 @@ +<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>ntpdc - special NTP query program +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>ntpdc</TT> - special NTP query program</H3> + +<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 start up using ntpd's configuration file may also be specified +at run time using <TT>ntpdc</TT>. + +<P>If one or more request options is 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><TT>ntpdc</TT> uses NTP mode 7 packets to communicate with the NTP server, +and hence can be used to query any compatable 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>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. +<H4> +Command Line Options</H4> +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. +<DL> +<DT> +<TT>-c <I>command</I></TT></DT> + +<DD> +The following argument is interpreted as an interactive format command +and is added to the list of commands to be executed on the specified host(s). +Multiple -c options may be given.</DD> + +<DT> +<TT>-i</TT></DT> + +<DD> +Force <TT>ntpdc</TT> to operate in interactive mode. Prompts will be written +to the standard output and commands read from the standard input.</DD> + +<DT> +<TT>-l</TT></DT> + +<DD> +Obtain a list of peers which are known to the server(s). This switch is +equivalent to <TT>-c listpeers</TT>.</DD> + +<DT> +<TT>-n</TT></DT> + +<DD> +Output all host addresses in dotted-quad numeric format rather than converting +to the canonical host names.</DD> + +<DT> +<TT>-p</TT></DT> + +<DD> +Print a list of the peers known to the server as well as a summary of their +state. This is equivalent to <TT>-c peers</TT>.</DD> + +<DT> +<TT>-s</TT></DT> + +<DD> +Print a list of the peers known to the server as well as a summary of their +state, but in a slightly different format than the -p switch. This is equivalent +to <TT>-c dmpeers</TT>.</DD> +</DL> + +<H4> +Interactive Commands</H4> +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>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. +<DL> +<DT> +<TT>? [ <I>command_keyword</I> ]</TT></DT> + +<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 funcation 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. This must correspond to a key number the server +has been configured to use for this purpose.</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>millseconds</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> +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. +<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 synchonization 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. In addition, +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 synchonizing to.</DD> + + +<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. +<DT> +<TT>dmpeers</TT></DT> + +<DD> +A slightly different peer summary list. Identical to the output of the +<TT>peers</TT> command, except for the character in the leftmost column. +Characters only appear beside peers which were included in the final stage +of the clock selection algorithm. A <TT>.</TT> indicates that this peer +was cast off in the falseticker detection, while a <TT>+</TT> indicates +that the peer made it through. A <TT>*</TT> denotes the peer the server +is currently synchronizing with.</DD> + +<DT> +<TT>showpeer <I>peer_address</I> [...]</TT></DT> + +<DD> +Shows a detailed display of the current peer variables for one or more +peers. Most of these values are described in the NTP Version 2 specification.</DD> + +<DT> +<TT>pstats <I>peer_address</I> [...]</TT></DT> + +<DD> +Show per-peer statistic counters associated with the specified peer(s).</DD> + +<DT> +<TT>clockinfo <I>clock_peer_address</I> [...]</TT></DT> + +<DD> +Obtain and print information concerning a peer clock. The values obtained +provide information on the setting of fudge factors and other clock performance +information.</DD> + +<DT> +<TT>kerninfo</TT></DT> + +<DD> +Obtain and print kernel phase-lock loop operating parameters. This information +is available only if the kernel has been specially modified for a precision +timekeeping function.</DD> + +<DT> +<TT>loopinfo [ oneline | multiline ]</TT></DT> + +<DD> +Print the values of selected loop filter variables. The loop filter is +the part of NTP which deals with adjusting the local system clock. The +<TT>offset</TT> is the last offset given to the loop filter by the packet +processing code. The <TT>frequency</TT> is the frequency error of the local +clock in parts-per-million (ppm). The <TT>time_const</TT> controls the +stiffness of the phase-lock loop and thus the speed at which it can adapt +to oscillator drift. The <TT>watchdog timer</TT> value is the number of +seconds which have elapsed since the last sample offset was given to the +loop filter. The <TT>oneline</TT> and <TT>multiline</TT> options specify +the format in which this information is to be printed, with <TT>multiline</TT> +as the default.</DD> + +<DT> +<TT>sysinfo</TT></DT> + +<DD> +Print a variety of system state variables, i.e., state related to the local +server. All except the last four lines are described in the NTP Version +3 specification, RFC-1305.</DD> + +<DL> +<DD> +The <TT>system flags</TT> show various system flags, some of which can +be set and cleared by the <TT>enable</TT> and <TT>disable</TT> configuration +commands, respectively. These are the <TT>auth</TT>, <TT>bclient</TT>, +<TT>monitor</TT>, <TT>pll</TT>, <TT>pps</TT> and <TT>stats</TT> flags. +See the <TT>ntpd</TT> documentation for the meaning of these flags. There +are two additional flags which are read only, the <TT>kernel_pll</TT> and +<TT>kernel_pps</TT>. These flags indicate the synchronization status when +the precision time kernel modifications are in use. The <TT>kernel_pll</TT> +indicates that the local clock is being disciplined by the kernel, while +the kernel_pps indicates the kernel discipline is provided by the PPS signal.</DD> + +<DD> +The <TT>stability</TT> is the residual frequency error remaining after +the system frequency correction is applied and is intended for maintenance +and debugging. In most architectures, this value will initially decrease +from as high as 500 ppm to a nominal value in the range .01 to 0.1 ppm. +If it remains high for some time after starting the daemon, something may +be wrong with the local clock, or the value of the kernel variable <TT>tick</TT> +may be incorrect.</DD> + +<DD> +The <TT>broadcastdelay</TT> shows the default broadcast delay, as set by +the <TT>broadcastdelay</TT> configuration command.</DD> + +<DD> +The <TT>authdelay</TT> shows the default authentication delay, as set by +the <TT>authdelay</TT> configuration command.</DD> +</DL> + +<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>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.</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> +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 xtnpdc. 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>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>The following commands all make authenticated requests. +<DL> +<DT> +<TT>addpeer <I>peer_address</I> [ <I>keyid</I> ] [ <I>version</I> ] [ <I>prefer</I> +]</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 optional <TT>keyid</TT> +is a nonzero integer, 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. The <TT>version#</TT> +can be 1, 2 or 3 and defaults to 3. 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.</DD> + +<DT> +<TT>addserver <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 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 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 [ <I>flag</I> ] [ ... ]</TT></DT> + +<BR><TT>disable [ <I>flag</I> ] [ ... ]</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>. Following is a description +of the flags. Note that only the <TT>auth</TT>, <TT>bclient</TT>, <TT>monitor</TT>, +<TT>pll</TT>, <TT>pps</TT> and <TT>stats</TT> flags can be set by <TT>ntpdc</TT>; +the <TT>pll_kernel</TT> and <TT>pps_kernel</TT> flags are read-only.</DD> + +<DL> +<DT> +<TT>auth</TT></DT> + +<DD> +Enables the server to synchronize with unconfigured peers only if the peer +has been correctly authenticated using a trusted key and key identifier. +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>monitor</TT></DT> + +<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.</DD> + +<DT> +<TT>pll</TT></DT> + +<DD> +Enables the server to adjust its local clock by means of NTP. If disabled, +the local clock free-runs at its intrinsic time and frequency offset. This +flag is useful in case the local clock is controlled by some other device +or protocol and NTP is used only to provide synchronization to other clients. +In this case, the local clock driver is used. See the <A HREF="refclock.htm">Reference +Clock Drivers </A>page for further information. The default for this flag +is enable.</DD> + +<DT> +<TT>pps</TT></DT> + +<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.htm">A +Kernel Model for Precision Timekeeping </A>page for further information. +The default for this flag is disable.</DD> + +<DT> +<TT>stats</TT></DT> + +<DD> +Enables the statistics facility. See the <A HREF="monopt.htm">Monitoring +Options </A>page for further information. The default for this flag is +enable.</DD> + +<DT> +<TT>pll_kernel</TT></DT> + +<DD> +When the precision time kernel modifications are installed, this indicates +the kernel controls the clock discipline; otherwise, the daemon controls +the clock discipline.</DD> + +<DT> +<TT>pps_kernel</TT></DT> + +<DD> +When the precision time kernel modifications are installed and a pulse-per-second +(PPS) signal is available, this indicates the PPS signal controls the clock +discipline; otherwise, the daemon or kernel controls the clock discipline, +as indicated by the <TT>pll_kernel</TT> flag.</DD> +</DL> + +<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>trustkey <I>keyid</I> [...]</TT></DT> + +<DT> +<TT>untrustkey <I>keyid</I> [...]</TT></DT> + +<DD> +These commands operate in the same way as the <TT>trustedkey</TT> and <TT>untrustkey</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> +<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. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/ntpq.htm b/contrib/ntp/html/ntpq.htm new file mode 100644 index 0000000..9308867 --- /dev/null +++ b/contrib/ntp/html/ntpq.htm @@ -0,0 +1,747 @@ +<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>ntpq - standard NTP query program +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>pq</TT> - standard NTP query program</H3> + +<HR> +<H4> +Synopsis</H4> +<TT>ntpq [-inp] [-c <I>command</I>] [<I>host</I>] [...]</TT> +<H4> +Description</H4> +<TT>ntpq</TT> is used to query NTP servers which implement the recommended +NTP mode 6 control message format about current state and to request changes +in that state. The program may 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. +<TT>ntpq</TT> can also obtain and print a list of peers in a common format +by sending multiple queries to the server. + +<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><TT>ntpq</TT> uses NTP mode 6 packets to communicate with the NTP server, +and hence can be used to query any compatable 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>Command line options are described following. Specifying a command line +option other than -i or -n 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. +<DL> +<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 -c options may be given.</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> +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 "<", 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. +<DL> +<DT> +<TT>? [<I>command_keyword</I>]</TT></DT> + +<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 funcation and usage information about the +command. This command is probably a better source of information about +<TT>ntpq</TT> than this manual page.</DD> + +<DD> + </DD> + +<DT> +<TT>addvars <I>variable_name</I> [ = <I>value</I>] [...]</TT></DT> + +<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 readlist and writelist commands described below. The addvars 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 rmvars command can be used to remove individual +variables from the list, while the clearlist command removes all variables +from the list.</DD> + +<DD> + </DD> + +<DT> +<TT>authenticate yes | no</TT></DT> + +<DD> +Normally <TT>ntpq</TT> does not authenticate requests unless they are write +requests. The command authenticate yes causes <TT>ntpq</TT> to send authentication +with all requests it makes. Authenticated requests causes some servers +to handle requests slightly differently, and can occasionally melt the +CPU in fuzzballs if you turn authentication on before doing a peer display.</DD> + +<DD> + </DD> + +<DT> +<TT>cooked</TT></DT> + +<DD> +Causes output from query commands to be <TT>"cooked"</TT>. Variables which +are recognized by the server will have their values reformatted for human +consumption. Variables which <TT>ntpq</TT> thinks should have a decodeable +value but didn't are marked with a trailing <TT>"?"</TT>.</DD> + +<DD> + </DD> + +<DT> +<TT>debug more | less | off</TT></DT> + +<DD> +Turns internal query program debugging on and off.</DD> + +<DD> + </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> + +<DD> + </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> + +<DD> + </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> + +<DD> + </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. This must correspond to a key number the server +has been configured to use for this purpose.</DD> + +<DD> + </DD> + +<DT> +<TT>ntpversion 1 | 2 | 3 | 4</TT></DT> + +<DD> +Sets the NTP version number which <TT>ntpq</TT> claims in packets. Defaults +to 3, Note that mode 6 control messages (and modes, for that matter) didn't +exist in NTP version 1. There appear to be no servers left which demand +version 1.</DD> + +<DD> + </DD> + +<DT> +<TT>quit</TT></DT> + +<DD> +Exit <TT>ntpq</TT>.</DD> + +<DD> + </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> + +<DD> + </DD> + +<DT> +<TT>raw</TT></DT> + +<DD> +Causes all output from query commands is printed as received from the remote +server. The only formating/intepretation done on the data is to transform +nonascii data into a printable (but barely understandable) form.</DD> + +<DD> + </DD> + +<DT> +<TT>timeout <I>millseconds</I></TT></DT> + +<DD> +Specify a timeout period for responses to server queries. The default is +about 5000 milliseconds. Note that since <TT>ntpq</TT> retries each query +once after a timeout, the total waiting time for a timeout will be twice +the timeout value set.</DD> +</DL> + +<H4> +Control Message Commands</H4> +Each peer known to an NTP server has a 16 bit integer association identifier +assigned to it. 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>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. +<DL> +<DT> +<TT>associations</TT></DT> + +<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 +and index may be used as an alternative.</DD> + +<DD> + </DD> + +<DT> +<TT>clockvar [<I>assocID</I>] [<I>variable_name</I> [ = <I>value</I> [...] +] [...]</TT></DT> + +<DT> +<TT>cv [<I>assocID</I>] [<I>variable_name</I> [ = <I>value</I> [...] ] +[...]</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>lassocations</TT></DT> + +<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>.</DD> + +<DD> + </DD> + +<DT> +<TT>lpassociations</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>lpeers</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>mreadlist <I>assocID</I> <I>assocID</I></TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>mreadvar <I>assocID</I> <I>assocID</I> [ <I>variable_name</I> [ = <I>value</I> +[ ... ]</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>opeers</TT></DT> + +<DD> +An old form of the <TT>peers</TT> command with the reference ID replaced +by the local interface address.</DD> + +<DD> + </DD> + +<DT> +<TT>passociations</TT></DT> + +<DD> +Prints 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.</DD> + +<DD> + </DD> + +<DT> +<TT>peers</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DD> +The character in the left margin indicates the fate of this peer in the +clock selection process. Folowing is a list of these characters, the pidgeon +used in the <TT>rv</TT> command, and a short explanation of the condition +revealed.</DD> + +<DD> + </DD> + +<DD> +<TT>space reject</TT></DD> + +<DL> +<DD> +The peer is discarded as unreachable, synchronized to this server (synch +loop) or outrageous synchronization distance.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>x falsetick</TT></DD> + +<DL> +<DD> +The peer is discarded by the intersection algorithm as a falseticker.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>. excess</TT></DD> + +<DL> +<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.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>- outlyer</TT></DD> + +<DL> +<DD> +The peer is discarded by the clustering algorithm as an outlyer.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>+ candidat</TT></DD> + +<DL> +<DD> +The peer is a survivor and a candidate for the combining algorithm.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT># selected</TT></DD> + +<DL> +<DD> +The peer is a survivor, but not among the first six peers sorted by synchronization +distance. If the assocation is ephemeral, it may be demobilized to conserve +resources.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>* sys.peer</TT></DD> + +<DL> +<DD> +The peer has been declared the system peer and lends its variables to the +system variables.</DD> +</DL> + +<DD> +<TT> </TT></DD> + +<DD> +<TT>o pps.peer</TT></DD> + +<DL> +<DD> +The peer has been declared the system peer and lends its variables to the +system 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.</DD> + +<DD> + </DD> +</DL> + +<DD> +The <TT>flash</TT> variable is not defined in the NTP specification, but +is included as a valuable debugging aid. It displays the results of the +packet sanity checks defined in the NTP specification <TT>TEST1</TT> through +<TT>TEST9</TT>. The bits for each test read in increasing sequency from +the least significant bit and are defined as follows.</DD> + +<DD> + </DD> + +<DD> +The following <TT>TEST1</TT> through <TT>TEST4</TT> enumerate procedure +errors. The packet timestamps may or may not be believed, but the remaining +header data are ignored.</DD> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST1</TT></DD> + +<DL> +<DD> +Duplicate packet. A copy from somewhere.</DD> +</DL> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST2</TT></DD> + +<DL> +<DD> +Bogus packet. It is not a reply to a message previously sent. This can +happen when the NTP daemon is restarted and before a peer notices.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST3</TT></DD> + +<DL> +<DD> +Unsynchronized. One or more timestamp fields are missing. This normally +happens when the first packet from a peer is received.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST4</TT></DD> + +<DL> +<DD> +Either peer delay or peer dispersion is greater than one second. Ya gotta +be kidding.</DD> + +<DD> + </DD> +</DL> + +<DD> +The following <TT>TEST5</TT> through <TT>TEST10</TT> ennumerate errors +in the packet header. The packet is discarded without inspecting its contents.</DD> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST5</TT></DD> + +<DL> +<DD> +Cryptographic authentication fails. See the <A HREF="authopt.htm">Authentication +Options</A> page.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST6</TT></DD> + +<DL> +<DD> +Peer is unsynchronized. Wind up its clock first.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST7</TT></DD> + +<DL> +<DD> +Peer stratum is greater than 15. The peer is probably unsynchronized.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST8</TT></DD> + +<DL> +<DD> +Either root delay or root dispersion is greater than one second. Too far +from home.</DD> +</DL> + +<DL> +<DD> + </DD> +</DL> + +<DD> +<TT>TEST9</TT></DD> + +<DL> +<DD> +Peer cryptographic authentication fails. Either the key identifier or key +is wrong or somebody trashed our packet.</DD> + +<DD> + </DD> +</DL> + +<DD> +<TT>TEST10</TT></DD> + +<DL> +<DD> +Access is denied. See the <A HREF="accopt.htm">Access Control Options</A> +page.</DD> + +<DD> + </DD> +</DL> + +<DT> +<TT>pstatus <I>assocID</I></TT></DT> + +<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 hexidecimal and in pidgeon English.</DD> + +<DD> + </DD> + +<DT> +<TT>readlist [ <I>assocID</I> ]</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>readvar <I>assocID</I> <I>variable_name</I> [ = <I>value</I> ] [ ... +]</TT></DT> + +<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.</DD> + +<DD> + </DD> + +<DT> +<TT>writevar <I>assocID</I> <I>variable_name</I> [ = <I>value</I> [ ... +]</TT></DT> + +<DD> +Like the readvar request, except the specified variables are written instead +of read.</DD> + +<DD> + </DD> + +<DT> +<TT>writelist [ <I>assocID</I> ]</TT></DT> + +<DD> +Like the readlist request, except the internal list variables are written +instead of read.</DD> +</DL> + +<H4> +Bugs</H4> +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. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/ntptime.htm b/contrib/ntp/html/ntptime.htm new file mode 100644 index 0000000..3cc4544 --- /dev/null +++ b/contrib/ntp/html/ntptime.htm @@ -0,0 +1,96 @@ +<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>ntptime - read kernel time variables +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>ntptime</TT> - read kernel time variables</H3> + +<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> +This program is useful only with special kernels described in the <A HREF="kern.htm">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. +<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 times in Unix timeval format. Default is NTP format.</DD> + +<DT> +<TT>-l</TT></DT> + +<DD> +Specify the leap bits as a code from 0 to 3.</DD> + +<DT> +<TT>-m <I>max_error</I></TT></DT> + +<DD> +Display help information.</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-4.</DD> +</DL> + +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/ntptrace.htm b/contrib/ntp/html/ntptrace.htm new file mode 100644 index 0000000..675c347 --- /dev/null +++ b/contrib/ntp/html/ntptrace.htm @@ -0,0 +1,82 @@ +<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>ntptrace - trace a chain of NTP servers back to the primary +source +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>ntptrace</TT> - trace a chain of NTP servers back to the primary source</H3> + +<HR> +<H4> +Synopsis</H4> +<TT>ntptrace [ -vdn ] [ -r <I>retries</I> ] [ -t <I>timeout</I> ] [ <I>server</I> +]</TT> +<H4> +Description</H4> +<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>: +<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> +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. +<H4> +Options</H4> + +<DL> +<DT> +<TT>-d</TT></DT> + +<DD> +Turns on some debugging output.</DD> + +<DT> +<TT>-n</TT></DT> + +<DD> +Turns off the printing of host names; instead, host IP addresses are given. +This may be useful if a nameserver is down.</DD> + +<DT> +<TT>-r <I>retries</I></TT></DT> + +<DD> +Sets the number of retransmission attempts for each host (default = 5).</DD> + +<DT> +<TT>-t <I>timeout</I></TT></DT> + +<DD> +Sets the retransmission timeout (in seconds) (default = 2).</DD> + +<DT> +<TT>-v</TT></DT> + +<DD> +Prints verbose information about the NTP servers.</DD> +</DL> + +<H4> +Bugs</H4> +This program makes no attempt to improve accuracy by doing multiple samples. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/parsedata.htm b/contrib/ntp/html/parsedata.htm new file mode 100644 index 0000000..a756079 --- /dev/null +++ b/contrib/ntp/html/parsedata.htm @@ -0,0 +1,407 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> +<TITLE>NTP PARSE clock data formats</TITLE> +<h1>NTP PARSE clock data formats</h1> + +<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). + +<hr> +<h2>Meinberg clocks</h2> +<pre> +Meinberg: start=<STX>, end=<ETX>, sync on start + pattern="\2D: . . ;T: ;U: . . ; \3" + pattern="\2 . . ; ; : : ; \3" + pattern="\2 . . ; ; : : ; : ; ; . . " +</pre> + <p> + Meinberg is a german manufacturer of time code receivers. Those clocks + have a pretty common output format in the stock version. In order to + support NTP Meinberg was so kind to produce some special versions of + the firmware for the use with NTP. So, if you are going to use a + Meinberg clock please ask whether there is a special Uni Erlangen + version. + You can reach <A HREF="http://www.meinberg.de/">Meinberg</A> via the Web. + Information can also be ordered via eMail from <A HREF="mailto: info@meinberg.de">info@meinberg.de</A> + + <p> + General characteristics: + <br> + Meinberg clocks primarily output pulse per second and a describing + ASCII string. This string can be produced in two modes. either upon + the reception of a question mark or every second. NTP uses the latter + mechanism. The DCF77 variants have a pretty good relationship between + RS232 time code and the PPS signal while the GPS receiver has no fixed + timeing between the datagram and the pulse (you need to use PPS with + GPS!) on DCF77 you might get away without the PPS signal. + <pre> + The preferred tty setting for Meinberg is: + CFLAG (B9600|CS7|PARENB|CREAD|HUPCL) + IFLAG (IGNBRK|IGNPAR|ISTRIP) + OFLAG 0 + LFLAG 0 + </pre> + <pre> + The tty setting for Meinberg GPS 166/167 receivers is: + CFLAG (B19200|CS8|PARENB|CREAD|HUPCL) + IFLAG (IGNBRK|IGNPAR|ISTRIP) + OFLAG 0 + LFLAG 0 + </pre> + + <p> + The clock is run at datagram once per second. + Stock dataformat is: + <pre> + <STX>D:<dd>.<mm>.<yy>;T:<w>;U:<hh>:<mm>:<ss>;<S><F><D><A><ETX> +pos: 0 00 00 0 00 0 11 111 1 111 12 2 22 2 22 2 2 2 3 3 3 + 1 23 45 6 78 9 01 234 5 678 90 1 23 4 56 7 8 9 0 1 2 + +<STX> = '\002' ASCII start of text +<ETX> = '\003' ASCII end of text +<dd>,<mm>,<yy> = day, month, year(2 digits!!) +<w> = day of week (sunday= 0) +<hh>,<mm>,<ss> = hour, minute, second +<S> = '#' if never synced since powerup else ' ' for DCF U/A 31 + '#' if not PZF sychronisation available else ' ' for PZF 535 +<F> = '*' if time comes from internal quartz else ' ' +<D> = 'S' if daylight saving time is active else ' ' +<D> = 'U' if UTC time code is deliverd else ' ' +<A> = '!' during the hour preceeding an daylight saving time + start/end change +<A> = 'A' if a leap second is announced +</pre> + + <pre> + <STX><dd>.<mm>.<yy>; <w>; <hh>:<mm>:<ss>; <U><S><F><D><A><L><R><ETX> + pos: 0 00 0 00 0 00 11 1 11 11 1 11 2 22 22 2 2 2 2 2 3 3 3 + 1 23 4 56 7 89 01 2 34 56 7 89 0 12 34 5 6 7 8 9 0 1 2 + <STX> = '\002' ASCII start of text + <ETX> = '\003' ASCII end of text + <dd>,<mm>,<yy> = day, month, year(2 digits!!) + <w> = day of week (sunday= 0) + <hh>,<mm>,<ss> = hour, minute, second + <U> = 'U' UTC time display + <S> = '#' if never synced since powerup else ' ' for DCF U/A 31 + '#' if not PZF sychronisation available else ' ' for PZF 535 + <F> = '*' if time comes from internal quartz else ' ' + <D> = 'S' if daylight saving time is active else ' ' + <A> = '!' during the hour preceeding an daylight saving time + start/end change + <L> = 'A' LEAP second announcement + <R> = 'R' alternate antenna +</pre> +<p>Meinberg GPS166 receiver +<br> + You must get the Uni-Erlangen firmware for the GPS receiver support + to work to full satisfaction ! +<pre> + <STX><dd>.<mm>.<yy>; <w>; <hh>:<mm>:<ss>; <+/-><00:00>; <U><S><F><D><A><L><R><L>; <position...><ETX> + * + 000000000111111111122222222223333333333444444444455555555556666666 + 123456789012345678901234567890123456789012345678901234567890123456 + \x0209.07.93; 5; 08:48:26; +00:00; ; 49.5736N 11.0280E 373m\x03 + * + + <STX> = '\002' ASCII start of text + <ETX> = '\003' ASCII end of text + <dd>,<mm>,<yy> = day, month, year(2 digits!!) + <w> = day of week (sunday= 0) + <hh>,<mm>,<ss> = hour, minute, second + <+/->,<00:00> = offset to UTC + <S> = '#' if never synced since powerup else ' ' for DCF U/A 31 + '#' if not PZF sychronisation available else ' ' for PZF 535 + <U> = 'U' UTC time display + <F> = '*' if time comes from internal quartz else ' ' + <D> = 'S' if daylight saving time is active else ' ' + <A> = '!' during the hour preceeding an daylight saving time + start/end change + <L> = 'A' LEAP second announcement + <R> = 'R' alternate antenna (reminiscent of PZF535) usually ' ' + <L> = 'L' on 23:59:60 +</pre> + +<p>For the Meinberg parse look into clock_meinberg.c + +<br> +<h2>Raw DCF77 Data via serial line</h2> +<p>RAWDCF: end=TIMEOUT>1.5s, sync each char (any char),generate psuedo time + codes, fixed format +<p> + direct DCF77 code input + + <p>In Europe it is relatively easy/cheap the receive the german time code + transmitter DCF77. The simplest version to process its signal is to + feed the 100/200ms pulse of the demodulated AM signal via a level + converter to an RS232 port at 50Baud. parse/clk_rawdcf.c holds all + necessary decoding logic for the time code which is transmitted each + minute for one minute. A bit of the time code is sent once a second. + +<pre> + The preferred tty setting is: + CFLAG (B50|CS8|CREAD|CLOCAL) + IFLAG 0 + OFLAG 0 + LFLAG 0 +</pre> + +<h2>DCF77 raw time code</h2> + + +<p>From "Zur Zeit", Physikalisch-Technische Bundesanstalt (PTB), Braunschweig +und Berlin, März 1989 +<br> +<pre> + Timecode transmission: + + AM: + + time marks are send every second except for the second before the + next minute mark + time marks consist of a reduction of transmitter power to 25% + of the nominal level + the falling edge is the time indication (on time) + time marks of a 100ms duration constitute a logical 0 + time marks of a 200ms duration constitute a logical 1 + + FM: + + see the spec. (basically a (non-)inverted psuedo random phase shift) + + Encoding: + + Second Contents + 0 - 10 AM: free, FM: 0 + 11 - 14 free + 15 R - alternate antenna + 16 A1 - expect zone change (1 hour before) + 17 - 18 Z1,Z2 - time zone + 0 0 illegal + 0 1 MEZ (MET) + 1 0 MESZ (MED, MET DST) + 1 1 illegal + 19 A2 - expect leap insertion/deletion (1 hour before) + 20 S - start of time code (1) + 21 - 24 M1 - BCD (lsb first) Minutes + 25 - 27 M10 - BCD (lsb first) 10 Minutes + 28 P1 - Minute Parity (even) + 29 - 32 H1 - BCD (lsb first) Hours + 33 - 34 H10 - BCD (lsb first) 10 Hours + 35 P2 - Hour Parity (even) + 36 - 39 D1 - BCD (lsb first) Days + 40 - 41 D10 - BCD (lsb first) 10 Days + 42 - 44 DW - BCD (lsb first) day of week (1: Monday -> 7: Sunday) + 45 - 49 MO - BCD (lsb first) Month + 50 MO0 - 10 Months + 51 - 53 Y1 - BCD (lsb first) Years + 54 - 57 Y10 - BCD (lsb first) 10 Years + 58 P3 - Date Parity (even) + 59 - usually missing (minute indication), except for leap insertion +</pre> + +<hr> +<h2>Schmid clock</h2> + +<p> + Schmid clock: needs poll, binary input, end='\xFC', sync start + + <p> + The Schmid clock is a DCF77 receiver that sends a binary + time code at the reception of a flag byte. The contents + if the flag byte determined the time code format. The + binary time code is delimited by the byte 0xFC. +<PRE> + TTY setup is: + CFLAG (B1200|CS8|CREAD|CLOCAL) + IFLAG 0 + OFLAG 0 + LFLAG 0 + +</PRE> + + +<p> The command to Schmid's DCF77 clock is a single byte; each bit + allows the user to select some part of the time string, as follows (the + output for the lsb is sent first). + +<pre> + Bit 0: time in MEZ, 4 bytes *binary, not BCD*; hh.mm.ss.tenths + Bit 1: date 3 bytes *binary, not BCD: dd.mm.yy + Bit 2: week day, 1 byte (unused here) + Bit 3: time zone, 1 byte, 0=MET, 1=MEST. (unused here) + Bit 4: clock status, 1 byte, 0=time invalid, + 1=time from crystal backup, + 3=time from DCF77 + Bit 5: transmitter status, 1 byte, + bit 0: backup antenna + bit 1: time zone change within 1h + bit 3,2: TZ 01=MEST, 10=MET + bit 4: leap second will be + added within one hour + bits 5-7: Zero + Bit 6: time in backup mode, units of 5 minutes (unused here) +</pre> + +<hr> +<h2>Trimble SV6 ASCII time code (TAIP)</h2> + +<p> + Trimble SV6: needs poll, ascii timecode, start='>', end='<', + query='>QTM<', eol='<' + +<p> Trimble SV6 is a GPS receiver with PPS output. It needs to be polled. + It also need a special tty mode setup (EOL='<'). +<pre> + TTY setup is: + CFLAG (B4800|CS8|CREAD) + IFLAG (BRKINT|IGNPAR|ISTRIP|ICRNL|IXON) + OFLAG (OPOST|ONLCR) + LFLAG (ICANON|ECHOK) + + Special flags are: + PARSE_F_PPSPPS - use CIOGETEV for PPS time stamping + PARSE_F_PPSONSECOND - the time code is not related to + the PPS pulse (so use the time code + only for the second epoch) + + Timecode + 0000000000111111111122222222223333333 / char + 0123456789012345678901234567890123456 \ posn + >RTMhhmmssdddDDMMYYYYoodnnvrrrrr;*xx< Actual + ----33445566600112222BB7__-_____--99- Parse + >RTM 1 ;* < Check +</pre> + +<hr> +<h2>ELV DCF7000</h2> +<p> + ELV DCF7000: end='\r', pattern=" - - - - - - - \r" +<p> + The ELV DCF7000 is a cheap DCF77 receiver sending each second + a time code (though not very precise!) delimited by '`r' +<pre> + Timecode + YY-MM-DD-HH-MM-SS-FF\r + + FF&0x1 - DST + FF&0x2 - DST switch warning + FF&0x4 - unsynchronised +</pre> +<hr> +<h2>HOPF 6021 und Kompatible</h2> + +<p> + HOPF Funkuhr 6021 mit serieller Schnittstelle + Created by F.Schnekenbuehl <frank@comsys.dofn.de> from clk_rcc8000.c + Nortel DASA Network Systems GmbH, Department: ND250 + A Joint venture of Daimler-Benz Aerospace and Nortel. + +<pre> + hopf Funkuhr 6021 + used with 9600,8N1, + UTC via serial line + "Sekundenvorlauf" ON + ETX zum Sekundenvorlauf ON + dataformat 6021 + output time and date + transmit with control characters + transmit evry second + + Type 6021 Serial Output format + + 000000000011111111 / char + 012345678901234567 \ position + sABHHMMSSDDMMYYnre Actual + C4110046231195 Parse + s enr Check + + s = STX (0x02), e = ETX (0x03) + n = NL (0x0A), r = CR (0x0D) + + A B - Status and weekday + + A - Status + + 8 4 2 1 + x x x 0 - no announcement + x x x 1 - Summertime - wintertime - summertime announcement + x x 0 x - Wintertime + x x 1 x - Summertime + 0 0 x x - Time/Date invalid + 0 1 x x - Internal clock used + 1 0 x x - Radio clock + 1 1 x x - Radio clock highprecision + + B - 8 4 2 1 + 0 x x x - MESZ/MEZ + 1 x x x - UTC + x 0 0 1 - Monday + x 0 1 0 - Tuesday + x 0 1 1 - Wednesday + x 1 0 0 - Thursday + x 1 0 1 - Friday + x 1 1 0 - Saturday + x 1 1 1 - Sunday +</pre> +<hr> +<h2>Diem Computime Clock</h2> + +<p> + The Computime receiver sends a datagram in the following format every minute +<pre> + Timestamp T:YY:MM:MD:WD:HH:MM:SSCRLF + Pos 0123456789012345678901 2 3 + 0000000000111111111122 2 2 + Parse T: : : : : : : \r\n + + T Startcharacter "T" specifies start of the timestamp + YY Year MM Month 1-12 + MD Day of the month + WD Day of week + HH Hour + MM Minute + SS Second + CR Carriage return + LF Linefeed +</pre> +<hr> +<h2>WHARTON 400A Series Clock with a 404.2 Serial interface</h2> + +<p> + The WHARTON 400A Series clock is able to send date/time serial messages + in 7 output formats. We use format 1 here because it is the shortest. + We set up the clock to send a datagram every second. + For use with this driver, the WHARTON 400A Series clock must be set-up + as follows : +<pre> + Programmable Selected + Option No Option + BST or CET display 3 9 or 11 + No external controller 7 0 + Serial Output Format 1 9 1 + Baud rate 9600 bps 10 96 + Bit length 8 bits 11 8 + Parity even 12 E +</pre> + WHARTON 400A Series output format 1 is as follows : +<pre> + Timestamp STXssmmhhDDMMYYSETX + Pos 0 12345678901234 + 0 00000000011111 + + STX start transmission (ASCII 0x02) + ETX end transmission (ASCII 0x03) + ss Second expressed in reversed decimal (units then tens) + mm Minute expressed in reversed decimal + hh Hour expressed in reversed decimal + DD Day of month expressed in reversed decimal + MM Month expressed in reversed decimal (January is 1) + YY Year (without century) expressed in reversed decimal + S Status byte : 0x30 + + bit 0 0 = MSF source 1 = DCF source + bit 1 0 = Winter time 1 = Summer time + bit 2 0 = not synchronised 1 = synchronised + bit 3 0 = no early warning 1 = early warning +</pre> diff --git a/contrib/ntp/html/parsenew.htm b/contrib/ntp/html/parsenew.htm new file mode 100644 index 0000000..0ef60bc --- /dev/null +++ b/contrib/ntp/html/parsenew.htm @@ -0,0 +1,237 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> +<TITLE>Making PARSE Clocks</TITLE> +<h1>How to build new PARSE clocks</h1> + +<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>Prerequisites: +<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) +</ul> + + +<p>What to do: + + +<p>Make a conversion module (libparse/clk_*.c) + +<ol> +<li>What ist the time code format ? +<ul> +<li> find year, month, day, hour, minute, second, status (synchronised or +not), possibly time zone information (you need to give the offset to UTC) +You will have to convert the data from a string into a struct clocktime: +<pre> + struct clocktime /* clock time broken up from time code */ + { + long day; + long month; + long year; + long hour; + long minute; + long second; + long usecond; + long utcoffset; /* in seconds */ + time_t utcoffset; /* true utc time instead of date/time */ + long flags; /* current clock status */ + }; +</pre> + +<p>Conversion is usually simple and straight forward. For the flags following +values can be OR'ed together: +<PRE> + PARSEB_ANNOUNCE switch time zone warning (informational only) + PARSEB_POWERUP no synchronisation - clock confused (must set then) + PARSEB_NOSYNC timecode currently not confirmed (must set then) + usually on reception error when there is still a + chance the the generated time is still ok. + + PARSEB_DST DST in effect (informational only) + PARSEB_UTC timecode contains UTC time (informational only) + PARSEB_LEAPADD LEAP addition warning (prior to leap happening - must set when imminent) + also used for time code that do not encode the + direction (as this is currently the default). + PARSEB_LEAPDEL LEAP deletion warning (prior to leap happening - must set when imminent) + PARSEB_ALTERNATE backup transmitter (informational only) + PARSEB_POSITION geographic position available (informational only) + PARSEB_LEAPSECOND actual leap second (this time code is the leap + second - informational only) +</PRE> + +<p>These are feature flags denoting items that are supported by the clock: + <PRE> + PARSEB_S_LEAP supports LEAP - might set PARSEB_LEAP + PARSEB_S_ANTENNA supports ANTENNA - might set PARSEB_ALTERNATE + PARSEB_S_PPS supports PPS time stamping + PARSEB_S_POSITION supports position information (GPS) + </PRE> + + <p>If the utctime field is non zero this value will be take as + time code value. This allows for conversion routines that + already have the utc time value. The utctime field gives the seconds + since Jan 1st 1970, 0:00:00. The useconds field gives the respective + usec value. The fields for date and time (down to second resolution) + will be ignored. + + + <p>Conversion is done in the cvt_* routine in parse/clk_*.c files. look in + them for examples. The basic structure is: + +<PRE> + struct clockformat <yourclock>_format = { + lots of fields for you to fill out (see below) + }; + + static cvt_<yourclock>() + ... + { + if (<I do not recognize my time code>) { + return CVT_NONE; + } else { + if (<conversion into clockformat is ok>) { + <set all necessary flags>; + return CVT_OK; + } else { + return CVT_FAIL|CVT_BADFMT; + } + } +</PRE> + + +<p>The struct clockformat is the interface to the rest of the parse + driver - it holds all information necessary for finding the + clock message and doing the appropriate time stamping. + +<PRE> +struct clockformat +{ + u_long (*input)(); + /* input routine - your routine - cvt_<yourclock> */ + u_long (*convert)(); + /* conversion routine - your routine - cvt_<yourclock> */ + /* routine for handling RS232 sync events (time stamps) - usually sync_simple */ + u_long (*syncpps)(); + /* PPS input routine - usually pps_one */ + void *data; + /* local parameters - any parameters/data/configuration info your conversion + routine might need */ + char *name; + /* clock format name - Name of the time code */ + unsigned short length; + /* maximum length of data packet for your clock format */ + u_long flags; + /* information for the parser what to look for */ +}; +</PRE> + + +<p>The above should have given you some hints on how to build a clk_*.c + file with the time code conversion. See the examples and pick a clock + closest to yours and tweak the code to match your clock. + + + <p>In order to make your clk_*.c file usable a reference to the clockformat + structure must be put into parse_conf.c. +</ul> +<li>TTY setup and initialisation/configuration will be done in +ntpd/refclock_parse.c. +<ul> +<li>Find out the exact tty settings for your clock (baud rate, parity, +stop bits, character size, ...) and note them in terms of +termio*.h c_cflag macros. +<li>in ntpd/refclock_parse.c fill out a new the struct clockinfo element +(that allocates a new "IP" address - see comments) +(see all the other clocks for example) +<PRE> + struct clockinfo + { + u_long cl_flags; /* operation flags (io modes) */ + PARSE_F_PPSPPS use loopfilter PPS code (CIOGETEV) + PARSE_F_PPSONSECOND PPS pulses are on second + usually flags stay 0 as they are used only for special setups + + void (*cl_poll)(); /* active poll routine */ + The routine to call when the clock needs data sent to it in order to + get a time code from the clock (e.g. Trimble clock) + + int (*cl_init)(); /* active poll init routine */ + The routine to call for very special initializations. + + void (*cl_event)(); /* special event handling (e.g. reset clock) */ + What to do, when an event happens - used to re-initialize clocks on timeout. + + void (*cl_end)(); /* active poll end routine */ + The routine to call to undo any special initialisation (free memory/timers) + + void *cl_data; /* local data area for "poll" mechanism */ + local data for polling routines + + u_fp cl_rootdelay; /* rootdelay */ + NTP rootdelay estimate (usually 0) + + u_long cl_basedelay; /* current offset - unsigned l_fp + fractional part (fraction) by + which the RS232 time code is + delayed from the actual time. */ + + u_long cl_ppsdelay; /* current PPS offset - unsigned l_fp fractional + time (fraction) by which the PPS time stamp is delayed (usually 0) + part */ + + char *cl_id; /* ID code (usually "DCF") */ + Refclock id - (max 4 chars) + + char *cl_description; /* device name */ + Name of this device. + + char *cl_format; /* fixed format */ + If the data format cann not ne detected automatically this is the name + as in clk_*.c clockformat. + + u_char cl_type; /* clock type (ntp control) */ + Type if clock as in clock status word (ntp control messages) - usually 0 + + u_long cl_maxunsync; /* time to trust oscillator after loosing synch + */ + seconds a clock can be trusted after loosing synchronisation. + + u_long cl_speed; /* terminal input & output baudrate */ + u_long cl_cflag; /* terminal io flags */ + u_long cl_iflag; /* terminal io flags */ + u_long cl_oflag; /* terminal io flags */ + u_long cl_lflag; /* terminal io flags */ + termio*.h tty modes. + + u_long cl_samples; /* samples for median filter */ + u_long cl_keep; /* samples for median filter to keep */ + median filter parameters - smoothing and rejection of bad samples + } clockinfo[] = { + ...,<other clocks>,... + { < your parameters> }, + }; + +</PRE> +</ul> +</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>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>For questions: <a href="mailto: kardel@acm.org">kardel@acm.org</a>. + +<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). +<hr><p> +<a href="http://www4.informatik.uni-erlangen.de/~kardel">Frank Kardel</a> diff --git a/contrib/ntp/html/patches.htm b/contrib/ntp/html/patches.htm new file mode 100644 index 0000000..154d4b8 --- /dev/null +++ b/contrib/ntp/html/patches.htm @@ -0,0 +1,70 @@ +<html><head><title> +Patching Procedures +</title></head><body><h3> +Patching Procedures +</h3> + +<IMG align=left SRC=pic/rabbit.gif>From <i>pogo</i>, Walt Kelly +<br clear=left><hr> + +<p>A distribution so widely used as this one eventually develops +numerous barnacles as the result of <a href=porting.htm>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. + +<ol> + +<p><li>Please submit patches to <a href=mailto:mills@udel.edu>David L. +Mills <mills@udel.edu></a> in the form of either unified-diffs +(<tt>diff -u</tt>) or context-diffs (<tt>diff -c</tt>).</li> + +<p><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> + +<p><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</li> + +<p><tt>patch -p <your_patch></tt></li> + +<p><li>Please avoid patching the RCS subdirectories; better yet, clean +them out before submitting patches.</li> + +<p><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 zip or the stock Unix compress utility.</li> + +<p><li>Don't forget the documentation that may be affected by the patch. +Send us patches for the <tt>./html</tt> files as well. See the <a +href=htmlprimer.htm>A Beginner's Guide to HTML</a> page for a +tutorial.</li> + +<p><li>We would be glad to include your name, electric address and +descriptive phrase in the <a href=copyright.htm>Copyright</a> page, +if you wish.</li> + +</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 occured 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>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>The best way to see what's changed between two distributions is to +run a <tt>diff</tt> against them. +<p>Thanks for your contribution and happy chime. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/porting.htm b/contrib/ntp/html/porting.htm new file mode 100644 index 0000000..d541d4e --- /dev/null +++ b/contrib/ntp/html/porting.htm @@ -0,0 +1,78 @@ +<html><head><title> +Porting Hints +</title></head><body><h3> +Porting Hints +</h3><hr> + +<p>NOTE: The following procedures have been replaced by GNU automake and +autoconfigure. This page is to be updated in the next release. + +<p>Porting to a new machine or operating system ordinarily requires +updating the <code>./machines</code> directory and the +<code>./compilers</code> directories in order to define the build +environment and autoconfigure means. You will probably have to modify +the <code>ntp_machines.h</code> file and <code>"l_stdlib.h"</code> files +as well. The two most famous trouble spots are the I/O code in +<code>./ntpd/ntp_io.c</code> and the clock adjustment code in +<code>./ntpd/ntp_unixclock.c</code>. + +<p>These are the rules so that older bsd systems and the POSIX standard +system can coexist together. + +<ol> + +<li>If you use <code>select</code> then include +<code>"ntp_select.h"</code>. <code>select</code> 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 +<code>"ntp_select.h"</code>. + +<p><li>Always use POSIX definition of strings. Include +<code>"ntp_string.h"</code> instead of <code><string.h></code>. + +<p><li>Always include <code>"ntp_malloc.h"</code> if you use +<code>malloc</code>. + +<p><li>Always include <code>"ntp_io.h"</code> instead of +<code><sys/file.h></code> or <code><fnctl.h></code> to get +<code>O_*</code> flags. + +<p><li>Always include <code>"ntp_if.h"</code> instead of +<code><net/if.h></code>. + +<p><li>Always include <code>"ntp_stdlib.h"</code> instead of +<code><stdlib.h></code>. + +<p><li>Define any special defines needed for a system in +<code>./include/ntp_machine.h</code> based on system identifier. This +file is included by the <code>"ntp_types.h"</code> file and should +always be placed first after the <code><></code> defines. + +<p><li>Define any special library prototypes left over from the system +library and include files in the <code>"l_stdlib.h"</code> file. This +file is included by the <code>"ntp_stdlib.h"</code> file and should +ordinarily be placed last in the includes list. + +<p><li>Don't define a include file by the same name as a system include +file. + +</ol> + +<p><code>"l_stdlib.h"</code> can contain any extra definitions that are +needed so that <code>gcc</code> 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>See <code>include/ntp_machines.h</code> for the various compile time +options. + +<p>When you are satisfied the port works and that other ports are not +adversely affected, please send <a href="patches.htm">patches</a> for +the system files you have changed, as well as any documentation that +should be updated, including the advice herein. + +<p>Good luck. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/pps.htm b/contrib/ntp/html/pps.htm new file mode 100644 index 0000000..a002c1f --- /dev/null +++ b/contrib/ntp/html/pps.htm @@ -0,0 +1,83 @@ +<HTML><HEAD><TITLE> +Pulse-per-second (PPS) Signal Interfacing +</TITLE></HEAD><BODY><H3> +Pulse-per-second (PPS) Signal Interfacing +</H3><HR> + +<P>Some radio clocks and related timekeeping gear have a pulse-per- +second (PPS) signal that can be used to discipline the local clock +oscillator to a high degree of precision, typically to the order less +than 20 <FONT FACE=Symbol>m</FONT>s in time and 0.01 PPM in frequency. +The PPS signal can be connected in either of two ways: via the data +leads of a serial port or via the modem control leads. Either way +requires conversion of the PPS signal, usually at TTL levels, to RS232 +levels, which can be done using a circuit such as described in the <A +HREF=gadget.htm>Gadget Box PPS Level Converter and CHU Modem</A> page. + +<P>The data leads interface requires regenerating the PPS pulse and +converting to RS232 signal levels, so that the pulse looks like a +legitimate ASCII character to a serial port. The <TT>tty_clk</TT> line +discipline/streams module inserts a timestamp following this character +in the input data stream. The <A HREF=driver22.htm>PPS Clock +Discipline</A> driver uses this timestamp to determine the time of +arrival of the PPS pulse to within 26 us at 38.4 kbps while eliminating +error due to operating system queues and service times. + +<P>The modem control leads interface requires converting to RS232 levels +and connecting to the data carrier detect (DCD) lead of a serial port. +The <TT>ppsclock</TT> and <TT>ppsapi</TT> streams modules capture a +timestamp upon transition of the DCD signal. Note that the +<TT>ppsclock</TT> module functionality has been subsumed by the new +<TT>ppsapi</TT> interface specification, which is supported by the NTP +daemon. As the latter is expected to become an IETF cross-platform +standard, it should be used in new configurations. The PPS Clock +Discipline driver reads the latest timestamp with a designated system +call or interface routine to determine the time of arrival of the PPS +pulse to within a few microseconds. Alternatively, if provisions have +been made in the kernel for PPS signals, the signal is captured directly +by the kernel serial driver without using the PPS driver. + +<P>The <TT>tty_clk</TT> module is included in the NTP software +distribution, while the <A +HREF=http://www.eecis.udel.edu/~mills/ntp/ntp/ppsclock.tar.Z><TT> +ppsclock</TT></A> module can be obtained via the web at that link or by +anonymous FTP from ftp.udel.edu in the <TT>pub/ntp</TT> directory. Both +the <TT>tty_clk</TT> and <TT>ppsclock</TT> modules are described in the +<A HREF=ldisc.htm>Line Disciplines and Streams Drivers</A> page. +Directions for building the modules themselves are in the +<TT>./kernel</TT> directory. Directions on how to configure +<TT>ntpd</TT> to operate with these modules is described in <A +HREF=build.htm>Building and Installing the Distribution </A>page. + +<P>The PPS driver is operates in conjunction with another reference +clock driver that produces the PPS pulse, as described in the <A +HREF=prefer.htm>Mitigation Rules and the <TT>prefer</TT> Keyword +</A>page. One of the drivers described in the <A +HREF=refclock.htm>Reference Clock Drivers</A> page furnishes +the coarse timecode used to disambiguate the seconds numbering of the +PPS pulse itself. The NTP daemon mitigates between the radio clock +driver and <TT>PPS</TT> 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>For the utmost time quality, some Unix system kernels support a PPS +signal directly, as described in the <A HREF=kern.htm>A Kernel Model +for Precision Timekeeping </A>page. Specifically, the ppsclock module +can be used to interface the PPS signal directly to the kernel for use +as discipline sources for both time and frequency. These sources can be +separately enabled and monitored using the <TT>ntp_adjtime()</TT> system +call described in that page and the <TT>/usr/include/sys/timex.h</TT> +header file. The presence of these kernel provisions is automatically +detected and supporting code compiled. + +<P>In some configurations may have multiple radio clocks, each with PPS +outputs, as well as a kernel provisions for the PPS signal. In order to +provide the highest degree of redundancy and survivability, the kernel +PPS discipline, <TT>tty_clk</TT> module, <TT>ppsclock</TT> module and +kernel modifications may all be in use at the same time, each backing up +the other. The sometimes complicated mitigation rules are described in +the Mitigation Rules and the <TT>prefer</TT> Keyword page. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/prefer.htm b/contrib/ntp/html/prefer.htm new file mode 100644 index 0000000..edb5152 --- /dev/null +++ b/contrib/ntp/html/prefer.htm @@ -0,0 +1,332 @@ +<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>Mitigation Rules and the ``prefer'' Keyword +</TITLE> +</HEAD> +<BODY> + +<H3> +Mitigation Rules and the <TT>prefer</TT> Keyword</H3> + +<HR> +<H4> +Introduction</H4> +The mechanics of the NTP algorithms which select the best data sample from +each available peer and the best subset of the peer population have been +finely crafted to resist network jitter, faults in the network or peer +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. + +<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 peers in addition to one or more radio +or modem clocks operating as local peers. In these configurations the suite +of algorithms used in NTP to refine the data from each peer separately +and to select and weight the data from a number of peers are used with +the entire ensemble of remote peers and local peers. 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>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 peers and reference clock drivers specified in the configuration +file. +<H4> +The <TT>prefer</TT> Peer</H4> +The mitigation rules are designed to provide an intelligent selection between +various peers of substantially the same statistical quality. They is designed +to provide the best quality time without compromising the normal operation +of the NTP algorithms. The mitigation scheme in its present form is not +an integral component of the NTP Version 3 specification RFC- 1305. but +is to be included in the version 4 specification when it is published. +The scheme is 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 peer or server, but is most commonly used with a radio clock. +While the scheme does 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>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 the specification, is not important here, other than +to point out 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. + +<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 right there. The prefer +peer can still be discarded by the sanity checks and intersection algorithms, +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>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. +<H4> +Peer Classification</H4> +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 and local peers as a function of configuration +declarations and reference clock driver type: +<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> + +<BR> +<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 peer or reference clock driver, which provides the seconds +numbering. The PPS peer is active only under conditions explained below.</LI> + +<BR> +<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> + +<BR> +<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> + +<BR> +<LI> +Where support is available, the PPS signal may be processed directly by +the kernel, as described in the <A HREF="kern.htm">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.</LI> +</OL> +Reference clock drivers operate in the manner described in the <A HREF="refclock.htm">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>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 the remote or local peers. 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 both +remote or local peers together with a modem peer are operated in the same +configuration, what can happen is that first the clock selection algorithm +can select one or more remote/local peers 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>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.htm">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. +<H4> +Mitigation Rules</H4> +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 operation, +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>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>The mitigation rules establish the choice of <I>system peer</I>, which +determine the stratum, reference identifier and several other system variables +which are visible to clients of the local server. In addition, they establish +which source or combination of sources control the local clock. +<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> + +<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> + +<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> + +<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> + +<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.</LI> +</OL> + +<H4> +Using the Pulse-per-Second (PPS) Signal</H4> +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 at best and a few milliseconds +in typical cases. However, some radios produce a PPS signal which can be +used to improve the accuracy with typical workstation servers to the order +of a few tens of microseconds. The details of how this can be accomplished +are discussed in the <A HREF="pps.htm">Pulse-per-second (PPS) Signal Interfacing</A> +page. The following paragraphs discuss how the PPS signal is affected by +the mitigation rules. + +<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>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="driver22.htm">PPS +Clock Discipline</A> page, the other using PPS signal support in the kernel, +as described in the <A HREF="kern.htm">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>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>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>In order to operate, the kernel support must be enabled by the <TT>enable +pll </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 in 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. +<HR> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/quick.htm b/contrib/ntp/html/quick.htm new file mode 100644 index 0000000..5ce0099 --- /dev/null +++ b/contrib/ntp/html/quick.htm @@ -0,0 +1,99 @@ +<HTML><HEAD><TITLE> +Quick Start +</TITLE></HEAD><BODY><H3> +Quick Start +</H3> + +<img align=left src=pic/panda.gif>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/~mills/database/papers/fuzz.ps">Fuzzball +</A>. As it happened, this was also the first Internet multimedia +presentation and the first to use NTP in regular operation. The image +was widely copied and used for testing purpose throughout much of the +1980s. +<br clear=left> + +<H4>Introduction</H4> + +<p>This page describes what to expect when the NTP daemon <tt>ntpd</tt> +is started for the first time. The discussion presumes the programs in +this distribution have been compiled and installed as described in the +<a href=build.htm>Building and Installing the Distribution</a> page. + +<p>When the daemon is started, whether for the first or subsequent +times, a number of roundtrip samples are required to accumulate reliable +measurements of network path delay and clock offset relative to the +server. Normally, this takes about four minutes, after which the local +clock is synchronized to the server. The daemon behavior at startup +depends on whether a drift file <tt>ntp.drift</tt> exists. This file +contains the latest estimate of local clock frequency error. When the +daemon is started for the first time, it is created after about one hour +of operation and updated once each hour after that. When the daemon is +started and the file does not exist, the daemon 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 daemon enters +normal mode, where the time and frequency are continuously tracked +relative to the server. + +<p>As a practical matter, once the local clock has been set, it very +rarely strays more than 128 ms relative to the server, even under +extreme cases of network path congestion and jitter. Sometimes, in +particular when the daemon is first started, the relative clock offset +exceeds 128 ms. In such cases the normal behavior of the daemon is to +set the clock directly, rather than rely on gradual corrections. This +may 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 that starts the daemon, the clock will never be +stepped and only slew corrections will be used. + +<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 2000 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>There may be an occasional outlyer, where an individual measurement +exceeds 128 ms. When the frequency of occurrence of these outlyers is +low, the measurement is discarded and operation continues with the next +one. However, if the outlyers persist for an interval longer than about +15 minutes, the next value is believed and the clock stepped or slewed +as determined by the <tt>-x</tt> option. The usual reason for this +behavior is when a leap second has occurred, but the reference clock +receiver has not synchronized to it. When leap second support is +implemented in the kernel, the kernel implements it as directed by the +NTP daemon. If this happens and the reference clock source +resynchronizes correctly within 15 minutes, the transient misbehavior of +the source is transparent. + +<p>It has been observed that, as the result of extreme network +congestion, the roundtrip delays can exceed three seconds and the +synchronization distance, which is equal to one-half the roundtrip delay +plus the error budget terms, can become very large. When the +synchronization distance exceeds one second, the offset measurement is +discarded. If this condition persists for several poll intervals, the +server may be declared unreachable. Sometimes the large jitter results +in large frequency errors which result in straying outside the +acceptable offset range and an eventual step or slew time correction. If +following such a correction the frequency error is so large that the +first sample is outside the acceptable range, the daemon 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 burst mode when configuring the server. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> + diff --git a/contrib/ntp/html/rdebug.htm b/contrib/ntp/html/rdebug.htm new file mode 100644 index 0000000..472b09f --- /dev/null +++ b/contrib/ntp/html/rdebug.htm @@ -0,0 +1,67 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> +<html><head><title> +Debugging Hints for Reference Clock Drivers +</title></head><body><h3> +Debugging Hints for Reference Clock Drivers +</h3><hr> + +<p>The <a href = "ntpq.htm"> <code>ntpq</code></a> and <a href = +"ntpdc.htm"> <code>ntpdc</code> </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 command-line switches described in the <a href = +"ntpd.htm"> <code>ntpd</code> </a> page. The first thing to look for +are error messages on the system log. If none occur, the daemon has +started, opened the devices specified and waiting for peers and radios +to come up. + +<p>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>If RS232 messages are getting to and from the clock, the variables of +interest can be inspected using the <code>ntpq</code> program and +various commands described on the documentation page. First, use the +<code>pe</code> and <code>as</code> commands to display billboards +showing the peer configuration and association IDs for all peers, +including the radio clock peers. The assigned clock address should +appear in the <code>pe</code> billboard and the association ID for it at +the same relative line position in the <code>as</code> billboard. If +things are operating correctly, after a minute or two samples should +show up in the <code>pe</code> display line for the clock. + +<p>Additional information is available with the <code>rv</code> and +<code>clockvar</code> commands, which take as argument the association +ID shown in the <code>as</code> billboard. The <code>rv</code> command +with no argument shows the system variables, while the <code>rv</code> +command with association ID argument shows the peer variables for the +clock, as well as any other peers of interest. The <code>clockvar</code> +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 <code>fudge</code> parameters is included. + +<p>The <code>ntpdc</code> utility program can be used for detailed +inspection of the clock driver status. The most useful are the +<code>clockstat</code> and <code>clkbug</code> 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. + +<p>Most drivers write a message to the <code>clockstats</code> 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 +<code>filegen</code> facility described in the <code>ntpd</code> 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 <code>./scripts/stats</code> +directory can be run from a <code>cron</code> job to collect and +summarize these data on a daily or weekly basis. The summary files have +proven invaluable to detect infrequent misbehavior due to clock +implementation bugs in some radios. +<hr><address>David L. Mills (mills@udel.edu)</address></body></html> diff --git a/contrib/ntp/html/refclock.htm b/contrib/ntp/html/refclock.htm new file mode 100644 index 0000000..5747e3f --- /dev/null +++ b/contrib/ntp/html/refclock.htm @@ -0,0 +1,126 @@ +<HTML><HEAD><TITLE> +Reference Clock Drivers +</TITLE></HEAD><BODY><H3> +Reference Clock Drivers +</H3> + +<IMG ALIGN=LEFT SRC=pic/tardisa.gif>From top: + +<UL> + +<LI>Austron 2100A GPS Receiver with LORAN-C assist</LI> +<LI>Austron 2000 LORAN-C Receiver></LI> +<LI>Spectracom 8170 WWVB Receiver</LI> +<LI>Hewlett Packard 5061A Cesium Beam Standard</LI> + +</UL> + +<br clear=left> +The Tardis +<hr> + +<H4>Reference Clock Drivers</H4> + +Support for most of the commonly available radio and modem 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.htm><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>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>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 speed, and features (line disciplines, etc.). +For those drivers without specific documentation, please contact the +author listed in the <A HREF=copyright.htm>copyright page</A>. + +<P><A HREF=driver1.htm>Type 1</A> Undisciplined Local Clock +(<TT>LOCAL</TT>) +<BR><A HREF=driver2.htm>Type 2</A> Trak 8820 GPS Receiver +(<TT>GPS_TRAK</TT>) +<BR><A HREF=driver3.htm>Type 3</A> PSTI/Traconex 1020 WWV/WWVH +Receiver +(<TT>WWV_PST</TT>) +<BR><A HREF=driver4.htm>Type 4</A> Spectracom 8170 and Netclock/2 WWVB +Receivers (<TT>WWVB_SPEC</TT>) +<BR><A HREF=driver5.htm>Type 5</A> TrueTime GPS/GOES/OMEGA Receivers +(<TT>TRUETIME</TT>) +<BR><A HREF=driver6.htm>Type 6</A> IRIG Audio Decoder +(<TT>IRIG_AUDIO</TT>) +<BR><A HREF=driver7.htm>Type 7</A> CHU Audio/Modem Decoder +(<TT>CHU</TT>) +<BR><A HREF=driver8.htm>Type 8</A> Generic Reference Driver +(<TT>PARSE</TT>) +<BR><A HREF=driver9.htm>Type 9</A> Magnavox MX4200 GPS Receiver +(<TT>GPS_MX4200</TT>) +<BR><A HREF=driver10.htm>Type 10</A> Austron 2200A/2201A GPS Receivers +(<TT>GPS_AS2201</TT>) +<BR><A HREF=driver11.htm>Type 11</A> Arbiter 1088A/B GPS Receiver +(<TT>GPS_ARBITER</TT>) +<BR><A HREF=driver12.htm>Type 12</A> KSI/Odetics TPRO/S IRIG Interface +(<TT>IRIG_TPRO</TT>) +<BR>Type 13 Leitch CSD 5300 Master Clock Controller +(<TT>ATOM_LEITCH</TT>) +<BR>Type 14 EES M201 MSF Receiver (<TT>MSF_EES</TT>) +<BR><A HREF=driver5.htm>Type 15</A> * TrueTime generic receivers +<BR>Type 16 Bancomm GPS/IRIG Receiver (<TT>GPS_BANCOMM</TT>) +<BR>Type 17 Datum Precision Time System (<TT>GPS_DATUM</TT>) +<BR><A HREF=driver18.htm>Type 18</A> NIST Modem Time Service +(<TT>ACTS_NIST</TT>) +<BR><A HREF=driver19.htm>Type 19</A> Heath WWV/WWVH Receiver +(<TT>WWV_HEATH</TT>) +<BR><A HREF=driver20.htm>Type 20</A> Generic NMEA GPS Receiver +(<TT>NMEA</TT>) +<BR>Type 21 TrueTime GPS-VME Interface (<TT>GPS_VME</TT>) +<BR><A HREF=driver22.htm>Type 22</A> PPS Clock Discipline +(<TT>PPS</TT>) +<BR><A HREF=driver23.htm>Type 23</A> PTB Modem Time Service +(<TT>ACTS_PTB</TT>) +<BR><A HREF=driver24.htm>Type 24</A> USNO Modem Time Service +(<TT>ACTS_USNO</TT>) +<BR><A HREF=driver5.htm>Type 25</A> * TrueTime generic receivers +<BR><A HREF=driver26.htm>Type 26</A> Hewlett Packard 58503A GPS +Receiver +(<TT>GPS_HP</TT>) +<BR><A HREF=driver27.htm>Type 27</A> Arcron MSF Receiver +(<TT>MSF_ARCRON</TT>) +<BR><A HREF=driver28.htm>Type 28</A> Shared memory driver +(<TT>SHM</TT>) +<BR><A HREF=driver29.htm>Type 29</A> Trimble Navigation Palisade GPS (<TT>GPS_PALISADE</TT>) +<BR><A HREF=driver30.htm>Type 30 Motorola UT Oncore GPS +(<TT>GPS_ONCORE</TT>) +<BR>Type 31 Rockwell Jupiter GPS (<TT>GPS_JUPITER</TT>) +<BR><A HREF=driver34.htm>Type 34</A> Ultralink WWVB receivers + +<P>* All TrueTime receivers are now supported by one driver, type 5. +Types +15 and 25 will be retained only for a limited time and may be reassigned +in future. + +<P>Additional Information + +<P><A HREF=prefer.htm>Mitigation Rules and the <TT>prefer</TT> +Keyword</A> +<BR><A HREF=rdebug.htm>Debugging Hints for Reference Clock Drivers</A> +<BR><A HREF=ldisc.htm>Line Disciplines and Streams Drivers</A> +<BR><A HREF=pps.htm>Pulse-per-second (PPS) Signal Interfacing</A> +<BR><A HREF=howto.htm>How To Write a Reference Clock Driver</A> +<BR><A HREF=index.htm>The Network Time Protocol (NTP) +Distribution </A> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/release.htm b/contrib/ntp/html/release.htm new file mode 100644 index 0000000..8b29cb9 --- /dev/null +++ b/contrib/ntp/html/release.htm @@ -0,0 +1,199 @@ +<HTML><HEAD><TITLE> +NTP Version 4 Release Notes +</TITLE></HEAD><BODY><H3> +NTP Version 4 Release Notes +</H3> + +<IMG align=left SRC=pic/hornraba.gif> <i>Alice's Adventures in +Wonderland</i>, by Lewis Carroll, illustrations by Sir John Tenniel +<BR clear=left><HR> + +<H4>NTP Version 4 Release Notes</H4> + +This release of the NTP Version 4 (NTPv4) daemon for Unix incorporates +new features and refinements to the NTP Version 3 (NTPv3) algorithms. +However, it continues the tradition of retaining backwards compatibility +with older versions. 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 implemented in the current NTPv3. The primary +purpose of this release is to verify the remaining new code compiles and +runs in the various architectures, operating systems and hardware +complement that can't be verified here. Of particular interest are +Windows NT, VMS and various reference clock drivers. As always, +corrections and bugfixes are warmly received, especially in the form of +context diffs. + +<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 + +<OL> + +<P><LI>Most of the extensive calculations are now done using 64-bit +floating-point 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 it. 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 double. The differences are ordinarily quite small +so can be expressed without loss of accuracy in double format.</LI> + +<P><LI>The clock discipline algorithm has been redesigned to improve +accuracy, reduce the impact of network jitter and allow an increase in +poll intervals to well over one day with only moderate sacrifice in +accuracy. The NTPv4 design allows servers to increase the poll intervals +even when synchronized directly to the peer. 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.</LI> + +<P><LI>A <A HREF=assoc.htm>burst-mode</A> feature is available which +results in good accuracy with intermittent connections typical of PPP +and ISDN services. When enabled, at each poll interval the server sends +eight messages over the next 30-s interval and processes them in a +batch. Outlyers due to initial dial-up delays, etc., are avoided and the +server synchronizes with its peer generally within 30 s.</LI> + +<P><LI>In addition to the NTPv3 authentication scheme, which uses +private-key cryptography, a new NTPv4 <A HREF=authopt.htm>autokey +</A>authentication scheme is available. Autokey uses public-key +technology and avoids the need to distribute keys by separate means. The +design is such that full accuracy is available without degradation due +to processing demands of the public-key routines. It can be used in any +of the NTP association modes, but is most useful in broadcast/multicast +modes.</LI> + +<P><LI>NTPv4 includes two new association modes which in most +applications can avoid per-host configuration altogether. Both of these +are based on multicast technology. They provide for automatic discovery +and configuration of servers and clients. In <A HREF=assoc.htm>multicast +</A>mode, a server sends a message at fixed intervals using specified +multicast addresses, while clients listen on these addresses. Upon +receiving the message, a client exchanges several messages with the +server in order to calibrate the multicast propagation delay between the +client and server. In <A HREF=assoc.htm>manycast </A>mode, a client +sends a message 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 in ordinary +client/server operation with them. The manycast scheme can provide +somewhat better accuracy than the multicast scheme at the price of +additional network overhead.</LI> + +<P><LI>The reference clock driver interface is smaller, more rational +and moreaccurate. 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 this interface, but some, including the +PARSE subinterface, have yet to be overhauled. New drivers have been +added for several GPS receivers now on the market. Drivers for the +Canadian standard time and frequency station CHU and for audio IRIG +signals have been updated and capabilites added to allow direct +connection of these signals to the Sun audio port +<TT>/dev/audio</TT>.</LI> + +<P><LI>In all except a very few cases, all timing intervals are +randomized, so that the tendency for NTPv3 to bunch messages, especially +with a large number of configured associations, is minimized.</LI> + +<P><LI>In NTPv3 a large number of weeds and useless code had grown over +the years since the original NTPv1 code was implemented almost ten 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> + +<P><LI>The entire distribution has been converted to <TT>gnu +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.</LI> +</OL> + +<H4>Nasty Surprises</H4> + +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: + +<OL> + +<P><LI>As required by Defense Trade Regulations (DTR), the cryptographic +routines supporting the Data Encryption Standard (DES) has been removed +from the export version of the distribtution. These routines are readily +available in most countries from RSA Laboratories. Directions for their +use are in the <A HREF=build.htm>Building and Installing the +Distribution</A> page.</LI> + +<P><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. Developers should +note the NTP authentication routines use the interface defined in the +<TT>rsaref2.0</TT> package available from RSA laboratories.</LI> + +<P><LI>The enable and disable commands have a few changes in their +arguments see the <TT>ntpd</TT> <A HREF=confopt.htm>Configuration +Options</A> page for details.</LI> + +<P><LI>The scheme for enabling the <TT>ppsclock</TT> line +discipline/streams module has changed. Formerly, it was enabled by +setting f<TT>udge flag3</TT> for the serial port connected to the PPS +signal. Now, there is an explicit command <TT>pps</TT> used to designate +the device name. See the <A HREF=clockopt.htm>Reference Clock +Options</A> page for details.</LI> + +<P><LI>While in fact not a new problem, some obscure option combinations +require the <TT>server</TT> and <TT>peer</TT> commands to follow the +others; in particular, the <TT>enable</TT> and <TT>pps</TT> commands +should preceed these commands.</LI> + +</OL> + +<H4>Caveats</H4> + +This release has been compiled and tested on several systems, including +SunOS 4.1.3, Solaris 2.5.1 and 2.6, Alpha 4.0, Ultrix 4.4, Linux, +FreeBSD and HP-UX 10.02. It has not been compiled for Windows NT or VMS. +We are relying on the NTP volunteer brigade to do that. Known problems +are summarized below: + +<OL> + +<P><LI>To work properly in all cases, the <TT>enable</TT> and +<TT>pps</TT> commands, if used, should appear before the <TT>server</TT> +and <TT>fudge</TT> commands in the configuration file.</LI> + +<P><LI>The precision time kernel modifications now in stock Solaris 2.6 +have bugs. The 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> + +<P><LI>On Alpha 4.0 with reference clocks configured, debugging with the +<TT>-d</TT> options doesn't work.</LI> + +<P><LI>The autokey function requires an NTP header extensions field, +which is documented in an internet draft and implemented in this +release. This field holds the public-key signature and certificate; +however, the detailed format for these data have not yet been +determined. It is expected this will happen in the near future and that +implementation of the required algorithms will quickly follow using +available cryptographic algorithms.</LI> + +<P><LI>The manycast function still needs some work. Ideally, the +existing I/O routines would be enhanced to include the capability to +determine the source address on every multicast packet sent, so that the +autokey function could reliably construct the correct cryptosum. +Meanwhile, the utility of manycast in conjunction with autokey is +limited to clients with only a single network +interface.</LI> + +<P><LI>The HTML documentation has been partially updated. However, most +of the NTPv3 documentation continues to apply to NTPv4. Until the 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.</LI> + +</OL> + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> diff --git a/contrib/ntp/html/tickadj.htm b/contrib/ntp/html/tickadj.htm new file mode 100644 index 0000000..7d3a863 --- /dev/null +++ b/contrib/ntp/html/tickadj.htm @@ -0,0 +1,103 @@ +<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>tickadj - set time-related kernel variables +</TITLE> +</HEAD> +<BODY> + +<H3> +<TT>tickadj</TT> - set time-related kernel variables</H3> + +<HR> +<H4> +Synopsis</H4> +<TT>tickadj [ -Aqs ] [ -a <I>tickadj</I> ] [ -t <I>tick</I> ]</TT> +<H4> +Description</H4> +The <TT>tickadj</TT> program reads, and optionally modifies, several timekeeping-related +variables in the running kernel, via <TT>/dev/kmem</TT>. The particular +variables it is concerned with are <TT>tick</TT>, which is the number of +microseconds added to the system time during 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>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>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. +<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</TT></I> +specified.</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 SunOS4.</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> + +<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> +<ADDRESS> +David L. Mills (mills@udel.edu)</ADDRESS> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/vxworks.htm b/contrib/ntp/html/vxworks.htm new file mode 100644 index 0000000..b6fae80 --- /dev/null +++ b/contrib/ntp/html/vxworks.htm @@ -0,0 +1,153 @@ +<HTML> +<HEAD> + <TITLE>vxWorks Port of NTP</TITLE> +</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> + +<LI>Little endianess is set if the target is of type iX86. </LI> + +<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> + +<LI>clock_settime() is defined to be used for setting the clock. </LI> + +<LI>The Linking flags have -r added to allow for relinking into the vxWorks +kernel </LI> +</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> + +<LI>POSIX timers have been added. </LI> + +<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.</LI> +</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</A> <BR> +<A HREF="mailto:casey@csc.co.za">casey@csc.co.za</A> </P> + +<P><BR> +</P> + +</BODY> +</HTML> diff --git a/contrib/ntp/html/y2k.htm b/contrib/ntp/html/y2k.htm new file mode 100644 index 0000000..3609ee3 --- /dev/null +++ b/contrib/ntp/html/y2k.htm @@ -0,0 +1,141 @@ +<html><head<title> +Network Time Protocol Year 2000 Conformance Statement +</title></head><body><h3> +Network Time Protocol Year 2000 Conformance Statement +</h3> + +<img align=left src=pic/alice15.gif> +from <i>Alice's Adventures in Wonderland</i>, by Lewis Carroll, +illustrations by Sir John Tenniel + +<p>The Mad Hatter and the March Hare are discussing whether the Teapot +serial number should have two or four digits. + +<br clear=left><hr> + +<h4>Introduction</h4> + +By the year 2000, the Network Time Protocol (NTP) will have been in +use for over two decades and remain the longest running, continuously +operating application protocol in the Internet. There is some concern, +especially in government and financial institutions, that NTP might +cause Internet applications to misbehave in terrible ways on the epoch +of the next century. This document presents an analysis of the various +hazards that might result in incorrect time values upon this epoch. It +concludes that incorrect time values due to the NTP timescale, protocol +design and reference implementation are highly unlikely. However, it is +possible that external reference time sources used by NTP could +misbehave and cause NTP servers to distribute incorrect time values to +significant portions of the Internet. Note that, while this document +addresses the issues specifically with respect to Unix systems, the +issues are equally applicable to Windows and VMS systems. + +<h4>The NTP Timescale</h4> + +It will be helpful in understanding the issues raised in this document +to consider the concept of a universal timescale. The conventional civil +timescale used in most parts of the world is based on Universal +Coordinated Time (UTC sic), formerly known as Greenwich Mean Time (GMT). +UTC is based on International Atomic Time (TAI sic), which is derived +from hundreds of cesium clocks in the national standards laboratories of +many countries. Deviations of UTC from TAI are implemented in the form +of leap seconds, which occur on average every eighteen months. For +almost every computer application today, UTC represents the universal +timescale extending into the indefinite past and indefinite future. We +know of course that the UTC timescale did not exist prior to 1972, the +Gregorian calendar did not exist prior to 1582, the Julian calendar did +not exist prior to 54 BC and we cannot predict exactly when the next +leap second will occur. Nevertheless, most folks would prefer that, even +if we can't get future seconds numbering right beyond the next leap +second, at least we can get the days numbering right until the end of +reason. + +<p>The universal timescale can be implemented using a binary counter of +indefinite width and with the unit seconds bit placed somewhere in the +middle. The counter is synchronized to UTC such that it runs at the same +rate and the units increment coincides with the UTC seconds tick. The +NTP timescale is constructed from 64 bits of this counter, of which 32 +bits number the seconds and 32 bits represent the fraction. With this +design, the counter runs in 136-year cycles, called eras, the latest of +which began with a counter value of zero at 0h 1 January 1900. The +design assumption is that further low order bits, if required, are +provided by local interpolation, while further high order bits, when +required, are provided by external means. The important point to be made +here is that the high order bits must ultimately be provided by +astronomers and disseminated to the population by international means. +Ultimately, should a need exist to align a particular NTP era to the +current calendar, the operating system in which NTP is embedded must +provide the necessary high order bits, most conveniently from the file +system or flash memory. + +<h4>The Year 2000 Era</h4> + +With respect to the year 2000 issue, the most important thing to observe +about the NTP timescale is that it knows nothing about days, years or +centuries, only the seconds since the beginning of the latest era, the +current one of which began on 1 January 1900. On 1 January 1970 when +Unix life began, the NTP timescale showed 2,208,988,800 and on 1 January +1972 when UTC life began, it showed 2,272,060,800. On the last second of +year 1999, the NTP timescale will show 3,155,672,599 and one second +later on the first second of the next century will show 3,155,672,600. +Other than this observation, the NTP timescale has no knowledge of or +provision for any of these eclectic seconds. + +<p>The NTP timescale is almost never used directly by system or +application programs. The generic Unix kernel keeps time in seconds and +microseconds (or nanoseconds) to provide both time of day and interval +timer functions. In order to synchronize the Unix clock, NTP must +convert to and from its representation and Unix representation. Unix +kernels implement the time of day function using two 32-bit counters, +one representing the seconds since Unix life began and the other the +microseconds or nanoseconds of the second. In principle, the seconds +counter will wrap around in 136-year eras, the next of which will begin +in 2106. How the particular Unix semantics interprets the counter values +is of concern, but is beyond the scope of discussion here. + +<p>While incorrect time values due to the NTP timescale and protocol +design or reference implementation upon the epoch of the next century +are highly unlikely, hazards remain due to incorrect software external +to NTP. These hazards include the Unix kernel and library routines which +convert Unix time to and from conventional civil time in seconds, +minutes, hours, days and years. Although NTP uses these routines to +format monitoring data displays, they are not used to read or set the +NTP clock. They may in fact cause problems with certain application +programs, but this is not an issue which concerns NTP correctness. + +<p>While it is extremely unlikely that NTP will produce incorrect time +values upon the epoch, it is possible that some external source to which +NTP synchronizes may produce a discontinuity which could then induce a +NTP discontinuity. The NTP primary (stratum 1) time servers, which are +the ultimate time references for the entire NTP population, obtain time +from various sources, including radio and satellite receivers and +telephone modems. Not all sources provide year information and not all +of these provide time in four-digit form. In point of fact, the NTP +reference implementation does not use the year information, even if +available. Instead, the year information is provided from the file +system, which itself depends on the Unix clock. + +<p>The NTP protocol specification requires the apparent NTP time derived +from external servers to be compared to the file system time before the +clock is set. If the discrepancy is over 1000 seconds, an error alarm is +raised requiring manual intervention. This makes it very unlikely that +even a clique of seriously corrupted NTP servers will result in +incorrect time values. In the case of embedded computers with no file +system, the design assumption is that the current era be established +from flash memory or a clock chip previously set by manual means. + +<p>It is essential that any clock synchronization protocol, including +NTP, include provisions for multiple-server redundancy and multiple- +route diversity. Past experience has demonstrated the wisdom of this +approach, which protects clients against hardware and software faults, +as well as incorrectly operating reference sources and sometimes even +buggy software. For the most reliable service, we recommend multiple +reference sources for primary servers, including a backup radio or +satellite receiver or telephone modem. We also recommend that primary +servers run NTP with other primary servers to provide additional +redundancy and mutual backup should the reference sources themselves +fail or operate incorrectly. + +<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a +href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a> +</address></a></body></html> |
