diff options
| author | roberto <roberto@FreeBSD.org> | 2001-08-29 14:35:15 +0000 |
|---|---|---|
| committer | roberto <roberto@FreeBSD.org> | 2001-08-29 14:35:15 +0000 |
| commit | 40b8e415eb0f835a9dd7a473ddf134ec67877fd7 (patch) | |
| tree | 3cfb63f1a112ee17469b17fc1593a88d004ddda6 /contrib/ntp/html | |
| parent | a5a8dc6136fcee95f261a31609a25669038c3861 (diff) | |
| download | FreeBSD-src-40b8e415eb0f835a9dd7a473ddf134ec67877fd7.zip FreeBSD-src-40b8e415eb0f835a9dd7a473ddf134ec67877fd7.tar.gz | |
Virgin import of ntpd 4.1.0
Diffstat (limited to 'contrib/ntp/html')
59 files changed, 9864 insertions, 8143 deletions
diff --git a/contrib/ntp/html/Oncore-SHMEM.htm b/contrib/ntp/html/Oncore-SHMEM.htm new file mode 100644 index 0000000..3148f6a --- /dev/null +++ b/contrib/ntp/html/Oncore-SHMEM.htm @@ -0,0 +1,257 @@ +<HTML> +<HEAD> + <TITLE> ONCORE - SHMEM </TITLE> +</HEAD> +<BODY> +<H3> +Motorola ONCORE - The Shared Memory Interface +</H3> +<HR> + +<H4> +Introduction +</H4> + +<P> +In NMEA mode, the Oncore GPS receiver provides the user with the same information as +other GPS receivers. +In BINARY mode, it can provide a lot of additional information. +<P> +In particular, you can ask for satellite positions, satellite health, signal levels, +the ephemeris and the almanac, and you can set many operational parameters. +In the case of the VP, +you can get the pseudorange corrections necessary to act as a DGPS base station, and you can see +the raw satellite data messages themselves. +<P> +When using the Oncore GPS receiver with NTP, this additional information is usually +not available since the receiver is only talking to the oncore driver in NTPD. +To make this information available for use in other programs, +(say graphic displays of satellites positions, plots of SA, etc.), a shared memory interface +(SHMEM) has been added to the refclock_oncore driver on those operating systems that support +shared memory. +<P> +To make use of this information you will need an Oncore Reference Manual for the +Oncore GPS receiver that you have. The Manual for the VP only exists as a paper +document, the UT manuals are available as a pdf document online. +<P> +This interface was written by Poul-Henning Kamp (phk@FreeBSD.org), and modified by +Reg Clemens (reg@dwf.com). +The interface is known to work in FreeBSD, Linux, and Solaris. +<H4> +Activating the Interface +</H4> +Although the Shared Memory Interface will be compiled into the Oncore driver +on those systems where Shared Memory is supported, to activate this interface you must +include a <B>STATUS</B> line in the <tt>/etc/ntp.oncore</tt> data file that looks like +<PRE> + STATUS < file_name > +</PRE> +Thus a line like +<PRE> + STATUS /var/adm/ntpstats/ONCORE +</PRE> +would be acceptable. +This file name will be used to access the Shared Memory. +<P> +In addition, one the two keywords <B>Posn2D</B> and <B>Posn3D</B> can be added to +see @@Ea records containing the 2D or 3D position of the station (see below). +Thus to activate the interface, and see 3D positions, something like +<PRE> + STATUS /var/adm/ntpstats/ONCORE + Posn3D +</PRE> +would be required. +<H4> +Storage of Messages in Shared Memory +</H4> +With the shared memory interface, the oncore driver (refclock_oncore) allocates space +for all of the messages that it is configured to receive, and then puts each message +in the appropriate slot in shared memory as it arrives from the receiver. +Since there is no easy way for a client program to know when the shared memory has +been updated, +a sequence number is associated with each message, and is incremented when a new message +arrives. +With the sequence number it is easy to check through the shared memory segment for messages that +have changed. +<P> +The Oncore binary messages are kept in their full length, as described in the Reference +manual, that is everything from the @@ prefix thru the <checksum><CR><LF>. +<P> +The data starts at location ONE of SHMEM (NOT location ZERO). +<P> +The messages are stacked in a series of variable length structures, that look like +<PRE> + struct message { + u_int length; + u_char sequence; + u_char message[length]; + } +</PRE> +<P> +if something like that were legal. +That is, there are two bytes (caution, these may NOT be aligned with word boundaries, so +the field needs to be treated as a pair of u_char), that contains the length of the next +message. +This is followed by a u_char sequence number, that is incremented whenever a new message of +this type is received. +This is followed by 'length' characters of the actual message. +<P> +The next structure starts immediately following the last char of the previous message (no alignment). +Thus, each structure starts a distance of 'length+3' from the previous structure. +<P> +Following the last structure, is a u_int containing a zero length to indicate the end +of the data. +<P> +The messages are recognized by reading the headers in the data itself, viz @@Ea or whatever. +<P> +There are two special cases. +<P> +(1) The almanac takes a total of 34 submessages all starting with @@Cb. <br> +35 slots are allocated in shared memory. +Each @@Cb message is initially placed in the first of these locations, +and then later it is moved to the appropriate location for that submessage. +The submessages can be distinguished by the first two characters following the @@Cb header, +and new data is received only when the almanac changes. +<P> +(2) The @@Ea message contains the calculated location of the antenna, and is received +once per second. +However, when in timekeeping mode, the receiver is normally put in 0D mode, with the +position fixed, to get better accuracy. +In 0D mode no position is calculated. +<P> +When the SHMEM option is active, +and if one of <B>Posn2D</B> or <B>Posn3D</B> is specified, +one @@Ea record is hijacked each 15s, and the receiver +is put back in 2D/3D mode so the the current location can be determined (for position determination, or for +tracking SA). +The timekeeping code is careful NOT to use the time associated with this (less accurate) 2D/3D tick +in its timekeeping functions. +<P> +Following the initial @@Ea message are 3 additional slots for a total of four. +As with the almanac, the first gets filled each time a new record becomes available, +later in the code, the message is distributed to the appropriate slot. +The additional slots are for messages containing 0D, 2D and 3D positions. +These messages can be distinguished by different bit patterns in the last data byte of the record. +<H4> +Opening the Shared Memory File +</H4> +The shared memory segment is accessed through a file name given on a <B>ACCESS</B> card in the +<tt>/etc/ntp.oncore</tt> input file. +The following code could be used to open the Shared Memory Segment: + +<PRE> + char *Buf, *file; + int size, fd; + struct stat statbuf; + + file = "/var/adm/ntpstats/ONCORE"; /* the file name on my ACCESS card */ + if ((fd=open(file, O_RDONLY)) < 0) { + fprintf(stderr, "Cant open %s\n", file); + exit(1); + } + + if (stat(file, &statbuf) < 0) { + fprintf(stderr, "Cant stat %s\n", file); + exit(1); + } + + size = statbuf.st_size; + if ((Buf=mmap(0, size, PROT_READ, MAP_SHARED, fd, (off_t) 0)) < 0) { + fprintf(stderr, "MMAP failed\n"); + exit(1); + } +</PRE> + +<H4> +Accessing the data +</H4> +The following code shows how to get to the individual records. + +<PRE> + void oncore_msg_Ea(), oncore_msg_As(), oncore_msg_Bb(); + + struct Msg { + char c[5]; + unsigned int seq; + void (*go_to)(uchar *); + }; + + struct Msg Hdr[] = { {"@@Bb", 0, &oncore_msg_Bb}, + {"@@Ea", 0, &oncore_msg_Ea}, + {"@@As", 0, &oncore_msg_As}}; + + void + read_data() + { + int i, j, k, n, iseq, jseq; + uchar *cp, *cp1; + + + for(cp=Buf+1; (n = 256*(*cp) + *(cp+1)) != 0; cp+=(n+3)) { + for (k=0; k < sizeof(Hdr)/sizeof(Hdr[0]); k++) { + if (!strncmp(cp+3, Hdr[k].c, 4)) { /* am I interested? */ + iseq = *(cp+2); + jseq = Hdr[k].seq; + Hdr[k].seq = iseq; + if (iseq > jseq) { /* has it changed? */ + /* verify checksum */ + j = 0; + cp1 = cp+3; /* points to start of oncore response */ + for (i=2; i < n-3; i++) + j ^= cp1[i]; + if (j == cp1[n-3]) { /* good checksum */ + Hdr[k].go_to(cp1); + } else { + fprintf(stderr, "Bad Checksum for %s\n", Hdr[k].c); + break; + } + } + } + } + if (!strncmp(cp+3, "@@Ea", 4)) + cp += 3*(n+3); + if (!strncmp(cp+3, "@@Cb", 4)) + cp += 34*(n+3); + } + } + + oncore_msg_Bb(uchar *buf) + { + /* process Bb messages */ + } + + oncore_msg_Ea(uchar *buf) + { + /* process Ea messages */ + } + + oncore_msg_As(uchar *buf) + { + /* process As messages */ + } +</PRE> + +The structure Hdr contains the Identifying string for each of the messages that +we want to examine, and the name of a program to call when a new message of that +type is arrives. +The loop can be run every few seconds to check for new data. +<H4> +Examples +</H4> +There are two complete examples available. +The first plots satellite positions and the station position as affected by SA, and +keeps track of the mean station position, so you can run it for periods of days +to get a better station position. +The second shows the effective horizon by watching satellite tracks. +The examples will be found in the GNU-zipped tar file +<A HREF=ftp://ftp.udel.edu/pub/ntp/software/OncorePlot.tar.gz> +ftp://ftp.udel.edu/pub/ntp/software/OncorePlot.tar.gz</A>. +<P> +Try the new interface, enjoy. +<HR> +<ADDRESS> +Reg.Clemens (reg@dwf.com), +Poul-Henning Kamp (phk@FreeBSD.org) +<ADDRESS> +</BODY> +</HTML> diff --git a/contrib/ntp/html/accopt.htm b/contrib/ntp/html/accopt.htm index d64a0d1..b0f5a9d 100644 --- a/contrib/ntp/html/accopt.htm +++ b/contrib/ntp/html/accopt.htm @@ -1,219 +1,210 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Access Control Options</title> +</head> +<body> +<h3>Access Control Options</h3> + +<img align="left" src="pic/pogo6.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>The skunk watches for intruders and sprays.<br clear="left"> +</p> + +<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.</p> + +<h4>The Kiss-of-Death Packet</h4> + +<p>Ordinarily, packets denied service are simply dropped with no +further action except incrementing statistics counters. Sometimes a +more proactive response is needed, such as a server message that +explicitly requests the client to stop sending and leave a message +for the system operator. A special packet format has been created +for this purpose called the kiss-of-death packet. If the <tt> +kod</tt> flag is set and either service is denied or the client +limit is exceeded, the server it returns the packet and sets the +leap bits unsynchronized, stratum zero and the ASCII string "DENY" +in the reference source identifier field. If the <tt>kod</tt> flag +is not set, the server simply drops the packet.</p> + +<p>A client or peer receiving a kiss-of-death packet performs a set +of sanity checks to minimize security exposure. If this is the +first packet received from the server, the client assumes an access +denied condition at the server. It updates the stratum and +reference identifier peer variables and sets the access denied +(test 4) bit in the peer flash variable. If this bit is set, the +client sends no packets to the server. If this is not the first +packet, the client assumes a client limit condition at the server, +but does not update the peer variables. In either case, a message +is sent to the system log.</p> + +<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> +<dl> +<dt><tt>kod</tt></dt> + +<dd>If access is denied, send a kiss-of-death packet.</dd> + +<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> + +<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> + +<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> + +<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> + +<dt><tt>lowpriotrap</tt></dt> + +<dd>Declare traps set by matching hosts to be low priority. The +number of traps a server can maintain is limited (the current limit +is 3). Traps are usually assigned on a first come, first served +basis, with later trap requestors being denied service. This flag +modifies the assignment algorithm by allowing low priority traps to +be overridden by later requests for normal priority traps.</dd> + +<dt><tt>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> + +<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> + +<dt><tt>notrust</tt></dt> + +<dd>Treat these hosts normally in other respects, but never use +them as synchronization sources.</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> + +<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> + +<dt><tt>version</tt></dt> + +<dd>Ignore these hosts if not the current NTP version.</dd> +</dl> +</dd> + +<dd>Default restriction list entries, with the flags <tt>ignore, +interface, ntpport</tt>, for each of the local host's interface +addresses are inserted into the table at startup to prevent the +server from attempting to synchronize to its own time. A default +entry is also always present, though if it is otherwise +unconfigured; no flags are associated with the default entry (i.e., +everything besides your own NTP server is unrestricted).</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> + +<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> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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 index 69cb7bc..a56d122 100644 --- a/contrib/ntp/html/assoc.htm +++ b/contrib/ntp/html/assoc.htm @@ -1,170 +1,89 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html><title> +Association Management +</title></head><body><h3> +Association Management +</h3> + +<img align=left src=pic/alice51.gif alt="gif"><a href=http://www.eecis.udel.edu/~mills/pictures.htm> +from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>Make sure who your friends are. +<br clear=left><hr> + +<h4>Association Modes</h4> + +<p>NTP Version 4 (NTPv4) incorporates new features and refinements to the NTP Version 3 (NTPv3) algorithms; however, it continues the tradition of backwards compatibility with older versions. A number of new operating modes for automatic server discovery and improved accuracy in occasionally connected networks are provided. Following is an overview of the new features; additional information is available on the <a href=confopt.htm>Configuration Options</a> and <a href=authopt.htm>Authentication Options</a> pages and in the papers, reports, memoranda and briefings at <a href=http://www.ntp.org>www.ntp.org</a>. + +<p>There are two types of associations: persistent associations, which result from configuration file commands, and ephemeral associations, which result from protocol operations described below. A persistent association is never demobilized, although it may become dormant when the associated server becomes unreachable. An ephemeral association is mobilized when a message arrives from a server; for instance, a symmetric passive association is mobilized upon arrival of a symmetric active message. A broadcast client association is mobilized upon arrival of a broadcast server message, while a manycast client association is mobilized upon arrival of a manycast server message. + +<p>Ordinarily, successful mobilization of an ephemeral association requires the server to be cryptographically authenticated to the dependent client. This can be done using either symmetric-key or public-key cryptography, as described in the <a href=authopt.htm>Authentication Options</a> page. The cryptographic means insure an unbroken chain of trust between the dependent client and the primary servers at the root of the synchronization subnet. We call this chain the provenance of the client and define new vocabulary as to proventicate a client or provide proventic credentials. Once mobilized, ephemeral associations are demobilized when either (a) the server becomes unreachable or (b) the server refreshes the key media without notifying the client. + +<p>There are three principal modes of operation: client/server, symmetric active/passive and broadcast. In addition, there are two modes using IP Multicast support: multicast and manycast. These modes are selected based on the scope of service, intended flow of time and proventic values and means of configuration. Following is a summary of the operations in each mode. + +<h4>Client/Server Mode</h4> + +<p>Client/server mode is probably the most common configuration in the Internet today. It operates in the classic remote-procedure-call (RPC) paradigm with stateless servers. In this mode a client sends a request to the server and expects a reply at some future time. In some contexts this would be described as a "pull" operation, in that the client pulls the time and proventic values from the server. A client is configured in client mode using the <tt>server</tt> (sic) command and specifying the server DNS name or address; the server requires no prior configuration. The original NTPv3 authentication scheme is applicable in this mode, as well as the new NTPv4 Autokey proventication scheme. In addition, two burst modes described below can be used in appropriate cases. + +<h4>Symmetric Active/Passive Mode</h4> + +<p>Symmetric active/passive mode is intended for configurations were a clique of low-stratum peers operate as mutual backups for each other. Each peer operates with one or more primary reference sources, such as a radio clock, or a subset of secondary servers known to be reliable and proventicated. Should one of the peers lose all reference sources or simply cease operation, the other peers will automatically reconfigure so that time and proventication values can flow from the surviving peers to all the others in the clique. In some contexts this would be described as a "push-pull" operation, in that the peer either pulls or pushes the time and proventic values depending on the particular configuration. + +<p>Symmetric peers operate with their sources in some NTP mode and with each other in symmetric mode. A peer is configured in symmetric active mode using the <tt>peer</tt> command and specifying the other peer DNS name or address. The other peer can also be configured in symmetric active mode in a similar way. However, if the other peer is not specifically configured in this way, a symmetric passive association is mobilized upon arrival of a symmetric active message. Since an intruder can impersonate a symmetric active peer and inject false time values, symmetric mode should always be cryptographically validated. The original NTPv3 authentication scheme is applicable in this mode, as well as the new NTPv4 Autokey proventication scheme. + +<h4>Broadcast Mode</h4> + +<p>Broadcast mode is intended for configurations involving one or a few servers and a possibly very large client population. A broadcast server is configured using the <tt>broadcast</tt> command and a local subnet address. A broadcast client is configured using the <tt>broadcastclient</tt> command, in which case it responds to broadcast messages received on any interface. Since an intruder can impersonate a broadcast server and inject false time values, this mode should always be cryptographically validated. The original NTPv3 authentication scheme is applicable in this mode, as well as the new NTPv4 Autokey proventication scheme. + +<p>The server generates broadcast messages continuously at intervals specified by the <tt>minpoll</tt> keyword and with a time-to-live span specified by the <tt>ttl</tt> keyword. A NTPv4 broadcast client responds to the first proventicated message received by waiting an interval randomized over the <tt>minpoll</tt> interval, in order to avoid implosion at the server. Then, the client polls the server in burst mode in order to reliably set the host clock and validate the source. This normally results in a volley of eight client/server cycles over a 30-s interval during which both the synchronization and cryptographic protocols run concurrently. When the next broadcast message is received after the volley, the client computes the offset between the apparent broadcast time and the (unicast) client time. This offset is used to compensate for the propagation time between the broadcast server and client. Once the offset is computed, the server continues as before and the client sends no further messages. + +<h4>IP Multicast Support</h4> + +<p>Broadcast mode in both NTPv3 and NTPv4 is limited to directly connected subnets such as Ethernets which support broadcast technology. Ordinarily, this technology does not operate beyond the first hop router or gateway. Where service is intended beyond the local subnet, IP multicasting can be used where supported by the operating system and the routers support the Internet Group Management Protocol (IGMP). Most current kernels and available routers do support IP multicast technology, although service providers are sometimes reluctant to deploy it. + +<p>A general discussion of IP multicast technology is beyond the scope here. In simple terms a host or router sending to a IP multicast group (class D) address expects all hosts or routers listening on this address to receive the message. There is no intrinsic limit on the number of senders or receivers and senders can be receivers and vice versa. The IANA has assigned multicast group address 224.0.1.1 to NTP, but this address should be used only where the multicast span can be reliably constrained to protect neighbor networks. In general, administratively scoped group addresses should be used, as described in RFC-2365, or GLOP group addresses, as described in RFC-2770. + +<h4>Multicasting</h4> + +<p>IP multicasting can be used to extend the scope of a timekeeping subnet in two ways: multicasting and manycasting. A multicast client is configured using the <tt>broadcast</tt> command, but with a multicast group (class D) address instead of a local subnet broadcast address. However, there is a subtle difference between broadcasting and multicasting. Broadcasting is specific to each interface and local subnet address. If more than one interface is attached to a machine, a separate <tt>broadcast</tt> command applies to each one separately. This provides a way to limit exposure in a firewall, for example. + +<p>IP multicasting is a different paradigm. A multicast message has the same format as a broadcast message and is configured with the same <tt>broadcast</tt> command, but with a multicast group address instead of a local subnet address. By design, multicast messages travel from the sender via a shortest-path or shared tree to the receivers, which may require these messages emit from one or all interfaces, but carry a common source address. However, it is possible to configure multiple multicast group addresses using multiple <tt>broadcast</tt> commands. Other than these particulars, multicast messages are processed just like broadcast messages. Note that the calibration feature in broadcast mode is extremely important, since IP multicast messages can travel far different paths through the IP routing fabric than ordinary IP unicast messages. + +<h4>Manycasting</h4> + +<p>Manycasting is a automatic discovery and configuration paradigm new to NTPv4. It is intended as a means for a multicast client to troll the nearby network neighborhood to find cooperating manycast servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. The intended result is that each manycast client mobilizes client associations with the "best" three of the available manycast servers, yet automatically reconfigures to sustain this number of servers should one or another fail. + +<p>Note that the manycasting paradigm does not coincide with the anycasting paradigm described in RFC-1546, which is designed to find a single server from a clique of servers providing the same service. The manycasting paradigm is designed to find a plurality of redundant servers, in this case willing NTP servers. + +<p>A persistent manycast client association is configured using the <tt>server</tt> command, but with a multicast (class D) group address instead of an ordinary IP (class A, B, C) address. It sends client mode messages to this address at the maximum feasible poll interval and minimum feasible time-to-live hops, depending on how many servers have already been found. There can be as many manycast client associations as different group addresss, each one serving as a template for a future ephemeral client/server mode association. + +<p>Manycast servers configured with the <tt>manycastserver</tt> command listen on the specified group address for manycast client messages. Note the distinction between manycast client, which is configured with a <tt>server</tt> command, and manycast server, which is configured with a <tt>manycastserver</tt> command. If a manycast server is in range of the current time-to-live and is itself synchronized to a valid source and operating at a stratum level equal to or lower than the manycast client, it replies to the manycast client message with an ordinary server mode message. + +<p>The manycast client receiving this message mobilizes an ephemeral client association as in ordinary client/server mode according to the matching manycast client template. Then, the client polls the server at its unicast address in burst mode in order to reliably set the host clock and validate the source. This normally results in a volley of eight client/server cycles over a 30-s interval during which both the synchronization and cryptographic protocols run concurrently. Following the volley, the client runs the NTP intersection and clustering algorithms, which act to discard all but the best three associations. The surviving associations then continue in ordinary client/server mode. + +<p>The manycast client polling program is designed to reduce as much as possible the volume of messages and the effects of implosion due to near-simultaneous arrival of manycast server messages. The program uses a poll interval eight times the system poll interval, which starts out at the <tt>minpoll</tt> value and under normal circumstances increases gradually to the <tt>maxpolll</tt> value. Initially, the time-to-live is set at one hop. At each retransmission the time-to-live is incremented by one until at least three manycast servers are found. Further retransmissions use the same time-to-live value. + +<p>If less than three servers are found when the time-to-live has reached the maximum specified by the <tt>ttl</tt> keyword, the poll interval is doubled. For each transmission after that, the poll interval is doubled again until reaching the maximum of eight times the value specified by the <tt>maxpoll</tt> keyword. Further transmissions use the same poll interval and time-to-live values. + +<p>The above scenario happens for each manycast client message, which repeats at the designated poll interval. However, once the ephemeral client association is mobilized, subsequent manycast server replies are discarded, since they will fail the message digest test. If during a poll interval the number of client associations falls below three, all manycast client prototype associations are reset to the initial poll interval and time-to-live values and operation resumes from the beginning. It is important in manycast mode to avoid frequent manycast client messages, since each one requires all manycast servers in range to respond. The result could well be an implosion, either minor or major, depending on the number of servers in range. The recommended value for <tt>maxpoll</tt> is 12 (4,096 s) and for <tt>ttl</tt> is 7. + +<p>It is possible and frequently useful to configure a host as both a manycast client and manycast server. A number of hosts configured this way and sharing a common group address will automatically organize themselves in an optimum configuration based on the smallest synchronization distance computed by the NTP mitigation algorithms. For example, consider an NTP subnet of two primary servers and maybe a dozen dependent clients. All servers and clients are configured as both multicast client and multicast server with multicast group address 239.1.1.1. In addition, the primary servers are configured for a primary reference source such as a GPS receiver. + +Once operations have stabilized in this scenario, the primary servers will affiliate with the primary reference source and each other, since they both operate at the same stratum (1), but not with any client, since clients operate at a higher stratum. The clients will find both primary servers and in addition, one of their own at the minimum synchronization distance. If one of the primary servers loses its GPS receiver, it will continue to operate as a client and other clients will time out the corresponding association and re-associate accordingly. + +<h4>Burst Modes</h4> + +<p>There are two burst modes that can be enabled in client/server mode using the <tt>iburst</tt> and <tt>burst</tt> keywords. In either mode a single poll initiates a burst of eight client messages at intervals randomized over the range 1-4 s. However, the interval between the first and second messages is increased to about 16 s in order for a dialup modem to complete a call, if necessary. Received server messages update the NTPv4 clock filter, which selects the best (most accurate) time values. When the last client message in the burst is sent, the next received server message updates the system variables and sets the system clock in the usual manner, as if only a single client/server cycle had occurred. The result is not only a rapid and reliable setting of the system clock, but a considerable reduction in network jitter. + +<p>The <tt>iburst</tt> keyword can be configured for cases where it is important to set the clock quickly when an association is first mobilized or first becomes reachable or when the network attachment requires an initial calling or training procedure. The burst is initiated only when the server first becomes reachable and results in good accuracy with intermittent connections typical of PPP and ISDN services. Outlyers due to initial dial-up delays, etc., are avoided and the client sets the clock within 30 s after the first message. + +<p>The <tt>burst</tt> keyword can be configured in cases of excessive network jitter or when the network attachment requires an initial calling or training procedure. The burst is initiated at each poll interval when the server is reachable. The burst does produce additional network overhead and can cause trouble if used indiscriminately. It should only be used where the poll interval is expected to settle to values at or above 1024 s. + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/audio.htm b/contrib/ntp/html/audio.htm index 5df5570..b345bc7 100644 --- a/contrib/ntp/html/audio.htm +++ b/contrib/ntp/html/audio.htm @@ -1,153 +1,187 @@ -<html><head><title> -Reference Clock Audio Drivers -</title></head><body><h3> -Reference Clock Audio Drivers -</h3><hr> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Reference Clock Audio Drivers</title> +</head> +<body> +<h3>Reference Clock Audio Drivers</h3> +<img align="left" src="pic/radio2.jpg" alt="gif"> + +<p>Make a little noise here.<br clear="left"> +</p> + +<hr> <p>There are some applications in which the computer time can be disciplined to an audio signal, rather than a serial timecode and -communications port or special purpose bus peripheral. This is useful in -such cases where the audio signal is sent over a telephone circuit, for -example, or received directly from a shortwave receiver. In such cases -the audio signal can be connected via an ordinary sound card or -baseboard audio codec. The suite of NTP reference clock drivers -currently includes three drivers suitable for these applications. They -include a driver for the Inter Range Instrumentation Group (IRIG) -signals produced by most radio clocks and timing devices, another for -the Canadian time/frequency radio station CHU and a third for the NIST +communications port or special purpose bus peripheral. This is +useful in such cases where the audio signal is sent over a +telephone circuit, for example, or received directly from a +shortwave receiver. In such cases the audio signal can be connected +via an ordinary sound card or baseboard audio codec. The suite of +NTP reference clock drivers currently includes three drivers +suitable for these applications. They include a driver for the +Inter Range Instrumentation Group (IRIG) signals produced by most +radio clocks and timing devices, another for the Canadian +time/frequency radio station CHU and a third for the NIST time/frequency radio stations WWV and WWVH. The radio drivers are -designed to work with ordinary inexpensive shortwave radios and may be -one of the least expensive ways to build a good primary time server. +designed to work with ordinary inexpensive shortwave radios and may +be one of the least expensive ways to build a good primary time +server.</p> <p>All three drivers make ample use of sophisticated digital signal -processing algorithms designed to efficiently extract timing signals -from noise and interference. The radio station drivers in particular -implement optimum linear demodulation and decoding techniques, including -maximum likelihood and soft-decision methods. The documentation page for -each driver contains an in-depth discussion on the algorithms and -performance expectations. In some cases the algorithms are further -analyzed, modelled and evaluated in a technical report. +processing algorithms designed to efficiently extract timing +signals from noise and interference. The radio station drivers in +particular implement optimum linear demodulation and decoding +techniques, including maximum likelihood and soft-decision methods. +The documentation page for each driver contains an in-depth +discussion on the algorithms and performance expectations. In some +cases the algorithms are further analyzed, modelled and evaluated +in a technical report.</p> <p>Currently, the audio drivers are compatible with Sun operating systems, including Solaris and SunOS, and the native audio codec -interface supported by these systems. In fact, the interface is quite -generic and support for other systems, in particular the various Unix -generics, should not be difficult. Volunteers are solicited. - -<p>The audio drivers include a number of common features designed to -groom input signals, suppress spikes and normalize signal levels. An -automatic gain control (AGC) feature provides protection against -overdriven or underdriven input signals. It is designed to maintain -adequate demodulator signal amplitude while avoiding occasional noise -spikes. In order to assure reliable operation, the signal level must be -in the range where the audio gain control is effective. In general, this -means the input signal level must be such as to cause the AGC to set the -gain somewhere in the middle of the range from 0 to 255, as indicated in -the timecode displayed by the <tt>ntpq</tt> program. +interface supported by these systems. In fact, the interface is +quite generic and support for other systems, in particular the +various Unix generics, should not be difficult. Volunteers are +solicited.</p> + +<p>The audio drivers include a number of common features designed +to groom input signals, suppress spikes and normalize signal +levels. An automatic gain control (AGC) feature provides protection +against overdriven or underdriven input signals. It is designed to +maintain adequate demodulator signal amplitude while avoiding +occasional noise spikes. In order to assure reliable operation, the +signal level must be in the range where the audio gain control is +effective. In general, this means the input signal level must be +such as to cause the AGC to set the gain somewhere in the middle of +the range from 0 to 255, as indicated in the timecode displayed by +the <tt>ntpq</tt> program.</p> <p>The drivers operate by disciplining a logical clock based on the codec sample clock to the audio signal as received. This is done by -stuffing or slipping samples as required to maintain exact frequency to -the order of 0.1 PPM. In order for the driver to reliably lock on the -audio signal, the sample clock frequency tolerance must be less than 250 -PPM (.025 percent) for the IRIG driver and half that for the radio -drivers. The largest error observed so far is about 60 PPM, but it is -possible some sound cards or codecs may exceed that value. +stuffing or slipping samples as required to maintain exact +frequency to the order of 0.1 PPM. In order for the driver to +reliably lock on the audio signal, the sample clock frequency +tolerance must be less than 250 PPM (.025 percent) for the IRIG +driver and half that for the radio drivers. The largest error +observed so far is about 60 PPM, but it is possible some sound +cards or codecs may exceed that value.</p> <p>The drivers include provisions to select the input port and to monitor the input signal. The <tt>fudge flag 2</tt> selects the -microphone port if set to zero or the line-in port if set to one. It -does not seem useful to specify the compact disc player port. The -<tt>fudge flag 3</tt> enables the input signal monitor using the -previously selected output port and output gain. Both of these flags can -be set in the configuration file or remotely using the <tt>ntpdc</tt> -utility program. - -<H4>Shortwave Radio Drivers</H4> - -<p>The WWV/H and CHU audio drivers require an external shortwave radio -with the radio output - speaker or headphone jack - connected to either -the microphone or line-in port on the computer. There is some degree of -art in setting up the radio and antenna and getting the setup to work. -While the drivers are highly sophisticated and efficient in extracting -timing signals from noise and interference, it always helps to have as -clear a signal as possible. - -<p>The most important factor affecting the radio signal is the antenna. -It need not be long - even 15 feet is enough if it is located outside of -a metal frame building, preferably on the roof, and away from metallic -objects. An ordinary CB whip mounted on a PVC pipe and wooden X-frame on -the roof should work well with most portable radios, as they are -optimized for small antennas. +microphone port if set to zero or the line-in port if set to one. +It does not seem useful to specify the compact disc player port. +The <tt>fudge flag 3</tt> enables the input signal monitor using +the previously selected output port and output gain. Both of these +flags can be set in the configuration file or remotely using the +<tt>ntpdc</tt> utility program.</p> + +<h4>Shortwave Radio Drivers</h4> + +<p>The WWV/H and CHU audio drivers require an external shortwave +radio with the radio output - speaker or headphone jack - connected +to either the microphone or line-in port on the computer. There is +some degree of art in setting up the radio and antenna and getting +the setup to work. While the drivers are highly sophisticated and +efficient in extracting timing signals from noise and interference, +it always helps to have as clear a signal as possible.</p> + +<p>The most important factor affecting the radio signal is the +antenna. It need not be long - even 15 feet is enough if it is +located outside of a metal frame building, preferably on the roof, +and away from metallic objects. An ordinary CB whip mounted on a +PVC pipe and wooden X-frame on the roof should work well with most +portable radios, as they are optimized for small antennas.</p> <p>The radio need not be located near the computer; in fact, it generally works better if the radio is outside the near field of computers and other electromagnetic noisemakers. It can be in the -elevator penthouse connected by house wiring, which can also be used to -power the radio. A couple of center-tapped audio transformers will -minimize noise pickup and provide phantom power to the radio with return -via the AC neutral wire. +elevator penthouse connected by house wiring, which can also be +used to power the radio. A couple of center-tapped audio +transformers will minimize noise pickup and provide phantom power +to the radio with return via the AC neutral wire.</p> <p>The WWV/H and CHU transmitters operate on several frequencies simultaneously, so that in most parts of North America at least one -frequency supports propagation to the receiver location at any given -hour. While both drivers support the ICOM CI-V radio interface and can tune the radio automatically, computer-tunable radios are expensive and probably not cost effective compared to a GPS receiver. So, the radio frequency must usually be fixed and chosen by compromise. +frequency supports propagation to the receiver location at any +given hour. While both drivers support the ICOM CI-V radio +interface and can tune the radio automatically, computer-tunable +radios are expensive and probably not cost effective compared to a +GPS receiver. So, the radio frequency must usually be fixed and +chosen by compromise.</p> -<p>Shortwave (3-30 MHz) radio propagation phenomena are well known to -shortwave enthusiasts. The phenomena generally obey the following rules: +<p>Shortwave (3-30 MHz) radio propagation phenomena are well known +to shortwave enthusiasts. The phenomena generally obey the +following rules:</p> <ul> +<li>The optimum frequency is higher in daytime than nighttime, +stays high longer on summer days and low longer on winter +nights.</li> -<p><li>The optimum frequency is higher in daytime than nighttime, stays -high longer on summer days and low longer on winter nights. - -<p><li>Transitions between daytime and nightime conditions generally -occur somewhat after sunrise and sunset at the midpoint of the path from -transmitter to receiver. - -<p><li>Ambient noise (static) on the lower frequencies follows the -thunderstorm season, so is higher on summer afternoons and evenings. +<li>Transitions between daytime and nightime conditions generally +occur somewhat after sunrise and sunset at the midpoint of the path +from transmitter to receiver.</li> -<p><li>The lower frequency bands are best for shorter distances, while -the higher bands are best for longer distances. +<li>Ambient noise (static) on the lower frequencies follows the +thunderstorm season, so is higher on summer afternoons and +evenings.</li> -<p><li>The optimum frequencies are higher at the peak of the 11-year -sunspot cycle and lower at the trough. The current sunspot cycle should -peak in the first couple of years beginning the century. +<li>The lower frequency bands are best for shorter distances, while +the higher bands are best for longer distances.</li> +<li>The optimum frequencies are higher at the peak of the 11-year +sunspot cycle and lower at the trough. The current sunspot cycle +should peak in the first couple of years beginning the +century.</li> </ul> -The best way to choose a frequency is to listen at various times over -the day and determine the best highest (daytime) and lowest (nighttime) -frequencies. Then, assuming one is available, choose the highest -frequency between these frequencies. This strategy assumes that the high -frequency is more problematic than the low, that the low frequency -probably comes with severe multipath and static, and insures that -probably twice a day the chosen frequency will work. For instance, on -the east coast the best compromise CHU frequency is probably 7335 kHz -and the best WWV frequency is probably 15 MHz. +The best way to choose a frequency is to listen at various times +over the day and determine the best highest (daytime) and lowest +(nighttime) frequencies. Then, assuming one is available, choose +the highest frequency between these frequencies. This strategy +assumes that the high frequency is more problematic than the low, +that the low frequency probably comes with severe multipath and +static, and insures that probably twice a day the chosen frequency +will work. For instance, on the east coast the best compromise CHU +frequency is probably 7335 kHz and the best WWV frequency is +probably 15 MHz. <h4>Debugging Aids</h4> -<p>The audio drivers include extensive debugging support to help hook up -the audio signals and monitor the driver operations. The documentation -page for each driver describes the various messages that can be produced -either in real-time or written to the <tt>clockstats</tt> file for -later analysis. Of particular help in verifying signal connections and -compatibility is a provision to monitor the signal via headphones or -speaker. - - -<p>The drivers write a synthesized timecode to the <tt>clockstats</tt> -file each time the clock is set or verified and at other times if verbose monitoring is enabled. The format includes several fixed-length fields defining the Gregorian time to the millisecond, together with additional variable-length fields specific to each driver. The data include the intervals since the clock was last set or verified, the audio gain and various state variables and counters specific to each driver. - -<H4>Additional Information</H4> - -<A HREF="refclock.htm">Reference Clock Drivers</A> -<br><A HREF="driver7.htm">Radio CHU Audio Demodulator/Decoder</A> -<br><A HREF="driver36.htm">Radio WWV/H Audio Demodulator/Decoder</A> -<br><A HREF="driver6.htm">IRIG Audio Decoder</A> +<p>The audio drivers include extensive debugging support to help +hook up the audio signals and monitor the driver operations. The +documentation page for each driver describes the various messages +that can be produced either in real-time or written to the <tt> +clockstats</tt> file for later analysis. Of particular help in +verifying signal connections and compatibility is a provision to +monitor the signal via headphones or speaker.</p> + +<p>The drivers write a synthesized timecode to the <tt> +clockstats</tt> file each time the clock is set or verified and at +other times if verbose monitoring is enabled. The format includes +several fixed-length fields defining the Gregorian time to the +millisecond, together with additional variable-length fields +specific to each driver. The data include the intervals since the +clock was last set or verified, the audio gain and various state +variables and counters specific to each driver.</p> + +<h4>Additional Information</h4> + +<a href="refclock.htm">Reference Clock Drivers</a> <br> +<a href="driver7.htm">Radio CHU Audio Demodulator/Decoder</a> <br> +<a href="driver36.htm">Radio WWV/H Audio Demodulator/Decoder</a> +<br> +<a href="driver6.htm">IRIG Audio Decoder</a> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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/authopt.htm b/contrib/ntp/html/authopt.htm index 506d4f3..29df75d 100644 --- a/contrib/ntp/html/authopt.htm +++ b/contrib/ntp/html/authopt.htm @@ -1,281 +1,415 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Authentication Options</title> +</head> +<body> +<h3>Authentication Options</h3> + +<img align="left" src="pic/alice44.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>Our resident cryptographer; now you see him, now you don't.<br +clear="left"> +</p> + +<hr> +<h4>Authentication Support</h4> + +<p>Authentication support allows the NTP client to verify that the +server is in fact known and trusted and not an intruder intending +accidentally or on purpose to masquerade as that server. The NTPv3 +specification RFC-1305 defines an scheme which provides +cryptographic authentication of received NTP packets. Originally, +this was done using the Data Encryption Standard (DES) algorithm +operating in Cipher Block Chaining (CBC) mode, commonly called +DES-CBC. Subsequently, this was augmented by the RSA Message Digest +5 (MD5) algorithm using a private key, commonly called keyed-MD5. +Either algorithm computes a message digest, or one-way hash, which +can be used to verify the server has the correct private key and +key identifier.</p> + +<p>NTPv4 retains the NTPv3 schemes, properly described as +symmetric-key cryptography and, in addition, provides a new Autokey +scheme based on public-key cryptography. Public-key cryptography is +generally considered more secure than symmetric-key cryptography, +since the security is based on a private value which is generated +by each server and never revealed. With Autokey all key +distribution and management functions involve only public values, +which considerably simplifies key distribution and storage.</p> + +<p>Authentication is 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. The authentication +options described below specify the suite of keys, select the key +for each configured association and manage the configuration +operations.</p> + +<p>The <tt>auth</tt> flag controls whether new associations or +remote configuration commands require cryptographic authentication. +This flag can be set or reset by the <tt>enable</tt> and <tt> +disable</tt> configuration commands and also by remote +configuration commands sent by a <tt>ntpdc</tt> program running in +another machine. If this flag is enabled, which is the default +case, new broadcast client and symmetric passive associations and +remote configuration commands must be cryptographically +authenticated using either symmetric-key or public-key schemes. 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 timekeeping.</p> + +<p>In networks with firewalls and large numbers of broadcast +clients it may be acceptable to disable authentication, since that +avoids key distribution and simplifies network maintenance. +However, when the configuration file contains host names, or when a +server or client is configured remotely, host names are resolved +using the DNS and a separate name resolution process. In order to +protect against bogus name server messages, name resolution +messages are authenticated using an internally generated key which +is normally invisible to the user. However, if cryptographic +support is disabled, 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 enabling the flag for +name resolution and disabled it once the name resolution process is +complete.</p> + +<p>An attractive alternative where multicast support is available +is manycast mode, in which clients periodically troll for servers. +Cryptographic authentication in this mode uses public-key schemes +as described below. The principle advantage of this manycast mode +is that potential servers need not be configured in advance, since +the client finds them during regular operation, and the +configuration files for all clients can be identical.</p> + +<p>In addition to the default symmetric-key cryptographic support, +support for public-key cryptography is available if the requisite +<tt>rsaref20</tt> software distribution has been installed before +building the distribution. Public-key cryptography provides secure +authentication of servers without compromising accuracy and +stability. The security model and protocol schemes for both +symmetric-key and public-key cryptography are described below.</p> + +<h4>Symmetric-Key Scheme</h4> + +The original RFC-1305 specification allows any one of possibly +65,534 keys, each distinguished by a 32-bit key identifier, to +authenticate an association. The servers and clients involved must +agree on the key and key identifier to authenticate their messages. +Keys and related information are specified in a key file, usually +called <tt>ntp.keys</tt>, 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 keys 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 +specified int he <tt>keys</tt> command and installs the keys in the +key cache. However, the keys must be activated with the <tt> +trusted</tt> command before use. This allows, for instance, the +installation of possibly several batches of keys and then +activating or deactivating each batch remotely using <tt> +ntpdc</tt>. This also provides a revocation capability that can be +used if a key becomes compromised. The <tt>requestkey</tt> command +selects the key used as the password for the <tt>ntpdc</tt> +utility, while the <tt>controlkey</tt> command selects the key used +as the password for the <tt>ntpq</tt> utility.</p> + +<h4>Public-Key Scheme</h4> + +The original NTPv3 authentication scheme described in RFC-1305 +continues to be supported; however, in NTPv4 an additional +authentication scheme called Autokey is available. It uses MD5 +message digest, RSA public-key signature and Diffie-Hellman key +agreement algorithms available from several sources, but not +included in the NTPv4 software distribution. In order to be +effective, the <tt>rsaref20</tt> package must be installed as +described in the <tt>README.rsa</tt> file. Once installed, the +configure and build process automatically detects it and compiles +the routines required. The Autokey scheme has several modes of +operation corresponding to the various NTP modes supported. RSA +signatures with timestamps are used in all modes to verify the +source of cryptographic values. All modes use a special cookie +which can be computed independently by the client and server. In +symmetric modes the cookie is constructed using the Diffie-Hellman +key agreement algorithm. In other modes the cookie is constructed +from the IP addresses and a private value known only to the server. +All modes use in addition a variant of the S-KEY scheme, in which a +pseudo-random key list is generated and used in reverse order. +These schemes are described along with an executive summary, +current status, briefing slides and reading list, on the <a href= +"http://www.eecis.udel.edu/~mills/autokey.htm">Autonomous +Authentication</a> page. + +<p>The cryptographic values used by the Autokey scheme are +incorporated as a set of files generated by the <a href= +"genkeys.htm"><tt>ntp-genkeys</tt></a> program, including the +symmetric private keys, public/private key pair, and the agreement +parameters. See the <tt>ntp-genkeys</tt> page for a description of +the formats of these files. They contain cryptographic values +generated by the algorithms of the <tt>rsaref20</tt> package and +are in printable ASCII format. All file names include the +timestamp, in NTP seconds, following the default names given below. +Since the file data are derived from random values seeded by the +system clock and the file name includes the timestamp, every +generation produces a different file and different file name.</p> + +<p>The <tt>ntp.keys</tt> file contains the DES/MD5 private keys. It +must be distributed by secure means to other servers and clients +sharing the same security compartment and made visible only to +root. While this file is not used with the Autokey scheme, it is +needed to authenticate some remote configuration commands used by +the <a href="ntpdc.htm"><tt>ntpq</tt></a> and <a href="ntpq.htm"> +<tt>ntpdc</tt></a> utilities. The <tt>ntpkey</tt> file contains the +RSA private key. It is useful only to the machine that generated it +and never shared with any other daemon or application program, so +must be made visible only to root.</p> + +<p>The <tt>ntp_dh</tt> file contains the agreement parameters, +which are used only in symmetric (active and passive) modes. It is +necessary that both peers beginning a symmetric-mode association +share the same parameters, but it does not matter which <tt> +ntp_dh</tt> file generates them. If one of the peers contains the +parameters, the other peer obtains them using the Autokey protocol. +If both peers contain the parameters, the most recent copy is used +by both peers. If a peer does not have the parameters, they will be +requested by all associations, either configured or not; but, none +of the associations can proceed until one of them has received the +parameters. Once loaded, the parameters can be provided on request +to other clients and servers. The <tt>ntp_dh</tt> file can be also +be distributed using insecure means, since the data are public +values.</p> + +<p>The <tt>ntpkey_<i>host</i></tt> file contains the RSA public +key, where <tt><i>host</i></tt> is the name of the host. Each host +must have its own <tt>ntpkey_<i>host</i></tt> file, which is +normally provided to other hosts using the Autokey protocol Each +<tt>server</tt> or <tt>peer</tt> association requires the public +key associated with the particular server or peer to be loaded +either directly from a local file or indirectly from the server +using the Autokey protocol. These files can be widely distributed +and stored using insecure means, since the data are public +values.</p> + +<p>The optional <tt>ntpkey_certif_<i>host</i></tt> file contains +the PKI certificate for the host. This provides a binding between +the host hame and RSA public key. In the current implementation the +certificate is obtained by a client, if present, but the contents +are ignored.</p> + +<p>Due to the widespread use of interface-specific naming, the host +names used in configured and mobilized associations are determined +by the Unix <tt>gethostname()</tt> library routine. Both the <tt> +ntp-genkeys</tt> program and the Autokey protocol derive the name +of the public key file using the name returned by this routine. +While every server and client is required to load their own public +and private keys, the public keys for each client or peer +association can be obtained from the server or peer using the +Autokey protocol. Note however, that at the current stage of +development the authenticity of the server or peer and the +cryptographic binding of the server name, address and public key is +not yet established by a certificate authority or web of trust.</p> + +<h4>Leapseconds Table</h4> + +<p>The NIST provides a table showing the epoch for all historic +occasions of leap second insertion since 1972. The leapsecond table +shows each epoch of insertion along with the offset of +International Atomic Time (TAI) with respect to Coordinated +Universtal Time (UTC), as disseminated by NTP. The table can be +obtained directly from NIST national time servers using <tt> +ftp</tt> as the ASCII file <tt>pub/leap-seconds</tt>.</p> + +<p>While not strictly a security function, the Autokey scheme +provides means to securely retrieve the leapsecond table from a +server or peer. Servers load the leapsecond table directly from the +file specified in the <tt>crypto</tt> command, while clients can +load the table indirectly from the servers using the Autokey +protocol. Once loaded, the table can be provided on request to +other clients and servers.</p> + +<h4>Key Management</h4> + +<p>All key files are installed by default in <tt> +/usr/local/etc</tt>, which is normally in a shared filesystem in +NFS-mounted networks and avoids installing them in each machine +separately. The default can be overridden by the <tt>keysdir</tt> +configuration command. However, this is not a good place to install +the private key file, since each machine needs its own file. A +suitable place to install it is in <tt>/etc</tt>, which is normally +not in a shared filesystem.</p> + +<p>The recommended practice is to keep the timestamp extensions +when installing a file and to install a link from the default name +(without the timestamp extension) to the actual file. This allows +new file generations to be activated simply by changing the link. +However, <tt>ntpd</tt> parses the link name when present to extract +the extension value and sends it along with the public key and host +name when requested. This allows clients to verify that the file +and generation time are always current. However, the actual +location of each file can be overridden by the <tt>crypto</tt> +configuration command.</p> + +<p>All cryptographic keys and related parameters should be +regenerated on a periodic and automatic basis, like once per month. +The <tt>ntp-genkeys</tt> program uses the same timestamp extension +for all files generated at one time, so each generation is distinct +and can be readily recognized in monitoring data. While a +public/private key pair must be generated by every server and +client, the public keys and agreement parameters do not need to be +explicitly copied to all machines in the same security compartment, +since they can be obtained automatically using the Autokey +protocol. However, it is necessary that all primary servers have +the same agreement parameter file. The recommended way to do this +is for one of the primary servers to generate that file and then +copy it to the other primary servers in the same compartment using +the Unix <tt>rdist</tt> command. Future versions of the Autokey +protocol are to contain provisions for an agreement protocol to do +this automatically.</p> + +<p>Servers and clients can make a new generation in the following +way. All machines have loaded the old generation at startup and are +operating normally. At designated intervals, each machine generates +a new public/private key pair and makes links from the default file +names to the new file names. The <tt>ntpd</tt> is then restarted +and loads the new generation, with result clients no longer can +authenticate correctly. The Autokey protocol is designed so that +after a few minutes the clients time out and restart the protocol +from the beginning, with result the new generation is loaded and +operation continues as before. A similar procedure can be used for +the agreement parameter file, but in this case precautions must be +take to be sure that all machines with this file have the same +copy.</p> + +<h4>Authentication Commands</h4> + +<dl> +<dt><tt>autokey [<i>logsec</i>]</tt></dt> + +<dd>Specifies the interval between regenerations of the session key +list used with the Autokey protocol. Note that the size of the key +list for each association depends on this interval and the current +poll interval. The default value is 12 (4096 s or about 1.1 hours). +For poll intervals above the specified interval, a session key list +with a single entry will be regenerated for every message +sent.</dd> + +<dt><tt>controlkey <i>key</i></tt></dt> + +<dd>Specifies the key identifier to use with the <a href= +"ntpq.htm"><tt>ntpq</tt></a> utility, which uses the standard +protocol defined in RFC-1305. The <tt><i>key</i></tt> argument is +the key identifier for a trusted key, where the value can be in the +range 1 to 65534, inclusive.</dd> + +<dt><tt>crypto [flags <i>flags</i>] [privatekey <i>file</i>] +[publickey <i>file</i>] [dhparms <i>file</i>] [leap <i> +file</i>]</tt></dt> + +<dd>This command requires the NTP daemon build process be +configured with the RSA library. This command activates public-key +cryptography and loads the required RSA private and public key +files and the optional Diffie-Hellman agreement parameter file, if +present. If one or more files are left unspecified, the default +names are used as described below. Following are the +subcommands:</dd> + +<dd> +<dl> +<dt><tt>privatekey <i>file</i></tt></dt> + +<dd>Specifies the location of the RSA private key file, which +otherwise defaults to <tt>/usr/local/etc/ntpkey</tt>.</dd> + +<dt><tt>publickey <i>file</i></tt></dt> + +<dd>Specifies the location of the RSA public key file, which +otherwise defaults to <tt>/usr/local/etc/ntpkey_<i>host</i></tt>., +where <i>host</i> is the name of the generating machine.</dd> + +<dt><tt>dhparms <i>file</i></tt></dt> + +<dd>Specifies the location of the Diffie-Hellman parameters file, +which otherwise defaults to <tt>/usr/local/etc/ntpkey_dh</tt>.</dd> + +<dt><tt>leap <i>file</i></tt></dt> + +<dd>Specifies the location of the leapsecond table file, which +otherwise defaults to <tt>/usr/local/etc/ntpkey_leap</tt>.</dd> +</dl> +</dd> + +<dt><tt>keys <i>keyfile</i></tt></dt> + +<dd>Specifies the location of the DES/MD5 private key file +containing the keys and key identifiers used by <tt>ntpd</tt>, <tt> +ntpq</tt> and <tt>ntpdc</tt> when operating in symmetric-key +mode.</dd> + +<dt><tt>keysdir <i>path</i></tt></dt> + +<dd>This command requires the NTP daemon build process be +configured with the RSA library. It specifies the default directory +path for the private key file, agreement parameters file and one or +more public key files. The default when this command does not +appear in the configuration file is <tt>/usr/local/etc/</tt>.</dd> + +<dt><tt>requestkey <i>key</i></tt></dt> + +<dd>Specifies the key identifier to use with the <a href= +"ntpdc.htm"><tt>ntpdc</tt></a> utility program, which uses a +proprietary protocol specific to this implementation of <tt> +ntpd</tt>. The <tt><i>key</i></tt> argument is a key identifier for +the trusted key, where the value can be in the range 1 to 65534, +inclusive.</dd> + +<dt><tt>revoke [<i>logsec</i>]</tt></dt> + +<dd>Specifies the interval between re-randomization of certain +cryptographic values used by the Autokey scheme, as a power of 2 in +seconds. These values need to be updated frequently in order to +deflect brute-force attacks on the algorithms of the scheme; +however, updating some values is a relatively expensive operation. +The default interval is 16 (65,536 s or about 18 hours). For poll +intervals above the specified interval, the values will be updated +for every message sent.</dd> + +<dt><tt>trustedkey <i>key</i> [...]</tt></dt> + +<dd>Specifies the key identifiers which are trusted for the +purposes of authenticating peers with symmetric-key cryptography, +as well as keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> +programs. The authentication procedures require that both the local +and remote servers share the same key and key identifier for this +purpose, although different keys can be used with different +servers. The <tt><i>key</i></tt> arguments are 32-bit unsigned +integers with values from 1 to 65,534.</dd> +</dl> + +<h4>Files</h4> + +<tt>ntp.keys</tt> private MD5 keys <br> +<tt>ntpkey</tt> RSA private key <br> +<tt>ntpkey_<i>host</i></tt> RSA public key <br> +<tt>ntp_dh</tt> Diffie-Hellman agreement parameters + +<h4>Bugs</h4> + +The <tt>ntpkey_<i>host</i></tt> files are really digital +certificates. These should be obtained via secure directory +services when they become universally available. + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/biblio.htm b/contrib/ntp/html/biblio.htm index 3396481..7f621d3 100644 --- a/contrib/ntp/html/biblio.htm +++ b/contrib/ntp/html/biblio.htm @@ -3,257 +3,104 @@ 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 + +<img align=left src=pic/flatheads.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>From <i>The +Wizard of Oz</i>, L. Frank Baum</a> <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 +<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. 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>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 the <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 software distribution. 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. A historical perspective is available in + +<ul> + +<p><li>Mills, D.L. A brief history of NTP time: confessions of an Internet timekeeper. Submitted for publication; please do not cite or redistribute. <a href=database/papers/history.ps>PostScript</a> | <a href=http://www.eecis.udel.edu/~mills/database/papers/history.pdf>PDF</a> + +</ul> + +<p>The NTP architecture, protocol and algorithm models are described in + +<ul> + +<p><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> + +<p>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. 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> + +<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> + +<p>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 + +<p>Mills, D.L., and P.-H. Kamp. The nanokernel. <i>Proc. Precision Time and Time Interval (PTTI) Applications and Planning Meeting</i> (Reston VA, November 2000). Paper: <a href=http://www.eecis.udel.edu/~mills/database/papers/nano/nano2.ps>PostScript</a> | <a href=http://www.eecis.udel.edu/~mills/database/papers/nano/nano2.pdf>PDF</a>, Slides: <a href=database/brief/nano/nano.htm>HTML</a> | <a href=http://www.eecis.udel.edu/~mills/database/brief/nano/nano.ps>PostScript</a> | <a href=http://www.eecis.udel.edu/~mills/database/brief/nano/nano.ppt>PowerPoint</a> + +<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 the <a href=assoc.htm>Association Management</a> page and in + +<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. 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>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><li>Simple Network Monitoring Protocol (SNMP) monitoring tools, as described in</li> + +<p>Sethi, A.S., H. Gao, and D.L. Mills. Management of the Network Time Protocol (NTP) with SNMP. Computer and Information Sciences Report 98-09, University of Delaware, November 1998, 32 pp. <a href=http://www.eecis.udel.edu/~mills/database/reports/ntp-mib-tr.ps>PostScript</a> | <a href=database/reports/ntp-mib-tr.pdf>PDF</a> + +<p><li>Engineered refinements to radio clock drivers and interface code, as described in in the <a href=pps.htm>Pulse-per-second (PPS) Signal Interfacing</a> page and</li> + +<p>Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl. Pulse-per-second API for Unix-like operating systems, version 1. Request for Comments RFC-2783, Internet Engineering Task Force, March 2000, 31 pp. <a href=http://www.eecis.udel.edu/~mills/database/rfc/rfc2783.txt>ASCII</a> + +<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 the <a href=authopt.htm>Authentication Options</a> page and in</li> + +<p>Mills, D.L. Public-Key cryptography for the Network Time Protocol. Internet Draft draft-ietf-stime-ntpauth-00.txt, University of Delaware, June 2000, 36 pp. <a href=http://www.eecis.udel.edu/~mills/database/memos/draft-ietf-stime-ntpauth-00.txt>ASCII</a> + +<p>Mills, D.L. Public key cryptography for the Network Time Protocol. Electrical Engineering Report 00-5-1, University of Delaware, May 2000. 23 pp. Abstract: <a href=http://www.eecis.udel.edu/~mills/database/reports/pkey/pkeya.ps>PostScript</a> | <a href=database/reports/pkey/pkeya.pdf>PDF</a>, Body: <a href=http://www.eecis.udel.edu/~mills/database/reports/pkey/pkeyb.ps>PostScript</a> | <a href=http://www.eecis.udel.edu/~mills/database/reports/pkey/pkeyb.pdf>PDF</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> +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>Support for International Atomic Time (TAI), as described in</li> + +<p>Levine, J., and D. Mills. Using the Network Time Protocol to transmit International Atomic Time (TAI). <i>Proc. Precision Time and Time Interval (PTTI) Applications and Planning Meeting</i> (Reston VA, November 2000). Paper: <a href=http://www.eecis.udel.edu/~mills/database/papers/tai.ps>PostScript</a> | <a href=http://www.eecis.udel.edu/~mills/database/papers/tai.pdf>PDF</a> + +<p><li>Performance surveys for NTP Version 4 can be found in</li> + +<p>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> + +<p>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> + +</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 index 44b0391..5981de3 100644 --- a/contrib/ntp/html/build.htm +++ b/contrib/ntp/html/build.htm @@ -1,186 +1,239 @@ -<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 +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Building and Installing the Distribution</title> +</head> +<body> +<h3>Building and Installing the Distribution</h3> + +<img align="left" src="pic/beaver.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>For putting out compiler fires.<br clear="left"> +</p> + +<hr> +<h4>Building and Installing the Distribution</h4> + +<p>As a practical matter, every computer architecture and operating +system version seems to be different than any other. The device +drivers may be different, the input/output system may be +idiosyncratic and the libraries may have different semantics. It is +not possible in a software distribution such as this one to support +every individual 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> + +<p>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> + +<p>The NTP authentication routines conform to the interface used by +RSA Laboratories in the <tt>rsaref20.zip</tt> package, which was +formerly downloadable from <tt>ftp.rsa.com</tt> or via the web at +<tt>www.rsa.com</tt>, but this may no longer be the case. Outside +the US 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 routines in either package with +the NTP build procedures is to uncompress and extract the <tt> +rsaref20</tt> files in a top level directory with that name. Then +install a link to that directory from <tt>rsaref2</tt> in the top +level directory of the distribution. Use <tt>rsaeuro1</tt> instead +for that distribution. These steps must be completed +before the configuration process described below.</p> + +<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. + +<p>The first thing to do is uncompress the distribution and extract +the source tree. Use the <tt>./configure</tt> command to perform an +automatic configuration procedure. This command inspects the +hardware and software environment and tests for the presence of +system header files and the contents of these files to determine if +certain features are present. When one or more of these features +are present, the code is compiled to use them; if not, no special +code is compiled. However, even if the code is compiled to use +these features, the code does a special test at run time to see if +one or more are actually present and avoids using them if not +present. In such cases a warning message is sent to the system log, +but the daemon should still work properly.</p> + +<p>The default build normally includes the debugging code, which +can be useful in diagnosing problems found in initial test, and all +reference clock drivers known to work with each machine and operating system. Unless memory space is at a premium, this is a sensible strategy and 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, +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> + +<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.</p> + +<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> -See <tt><a href="hints/winnt.htm">hints/winnt.htm</a> </tt>for directions -to compile the sources and install the executables. - -<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> +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.</p> + +<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 in the destination directory. This +includes the following programs: + +<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> +</ul> + +<p>If the precision time kernel modifications are present, the +following program is installed:</p> + +<ul> +<li><a href="ntptime.htm"><tt>ntptime</tt> - read kernel time +variables</a></li> +</ul> + +<p>If the public key authentication functions are present, the +following program is installed:</p> + +<ul> +<li><a href="genkeys.htm"><tt>ntp-genkeys</tt> - generate public +and private keys</a></li> +</ul> + +<p>In some systems that include the capability to edit kernel +variables, the following program is installed:</p> + +<ul> +<li><a href="tickadj.htm"><tt>tickadj</tt> - set time-related +kernel variables</a></li> +</ul> + +<h4>Configuration</h4> + +<p>You are now ready to configure the daemon and start it. You will +need to create a NTP configuration file <tt>ntp.conf</tt> and +possibly a cryptographic key file <tt>ntp.keys</tt>. Newbies should +see the <a href="quick.htm">Quick Start</a> page for orientation. +Seasoned veterans can start with the <a href="ntpd.htm"><tt> +ntpd</tt> - Network Time Protocol (NTP) daemon</a> page and move on +to the specific configuration option pages from there. A tutorial +on NTP subnet design and configuration options is in the <a href= +"notes.htm">Notes on Configuring NTP and Setting up a NTP +Subnet</a> page.</p> + +<h4>If You Have Problems</h4> + +<p>If you have problems peculiar to the particular hardware and +software environment (e.g. operating system-specific issues), +browse the <a href="hints.htm">Hints and Kinks</a> page. For other +problems a tutorial on debugging technique is in the <a href= +"debug.htm">NTP Debugging Technique</a> page. As always, the first +line of general assistance is the <a href="http://www.ntp.org">NTP +web site www.ntp.org</a> and the FAQ resident there. Requests for +assistance of a general nature and of interest to other timekeepers +should be sent to the NTP newsgroup. Bug reports of a specific +nature should be sent to <a href="mailto:bugs@mail.ntp.org"> +<bugs@mail.ntp.org></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 +bugs@mail.ntp.org.</p> + +<p>Please include the version of the source distribution (e.g., +ntp-4.0.70a) in your bug report, as well as billboards from the +relevant utility programs and debug trace, if available. Please +include the output of <tt>config.guess</tt> in your bug report. It +will look something like:</p> + +<p><tt>pdp11-dec-fuzzos3.4</tt></p> + +<p>Additional <tt>make</tt> commands</p> + +<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> + +See <tt><a href="hints/winnt.htm">hints/winnt.htm</a></tt> for +directions to compile the sources and install the executables. + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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 index b128b42..18773f0 100644 --- a/contrib/ntp/html/clockopt.htm +++ b/contrib/ntp/html/clockopt.htm @@ -1,193 +1,76 @@ -<HTML><HEAD><TITLE> +<html><head><title> Reference Clock Options -</TITLE></HEAD><BODY><H3> +</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> +</h3> + +<img align=left src=pic/boom4.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>Pogo</i>, Walt Kelly</a> + +<p>See the radios, all in a row. +<br clear=left><hr> + +<h4>Reference Clock Support</h4> + +The NTP Version 4 daemon supports some three dozen different radio, satellite and modem reference clocks plus a special pseudo-clock used for backup or when no other clock source is available. Detailed descriptions of individual device drivers and options can be found in the <a HREF="refclock.htm">Reference Clock Drivers </a>page. Additional information can be found in the pages linked there, including the <a HREF="rdebug.htm">Debugging Hints for Reference Clock Drivers</a> and <a HREF="howto.htm">How To Write a Reference Clock Driver</a> pages. In addition, 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 +<p>A reference clock will generally (though not always) be a radio timecode receiver which is synchronized to a source of standard time such as the services offered by the NRC in Canada and NIST and USNO in the US. The interface between the computer and the timecode receiver is device dependent, but is usually a serial port. A device driver specific to each reference clock must be selected and compiled in the distribution; however, most common radio, satellite and modem clocks are included by default. Note that an attempt to configure a reference clock when the driver has not been compiled or the hardware port has not been appropriately configured results in a scalding remark to the system log file, but is otherwise non hazardous. + +<p>For the purposes of configuration, <tt>ntpd</tt> treats reference clocks in a manner analogous to normal NTP peers as much as possible. Reference clocks are identified by a syntactically correct but invalid IP address, in order to distinguish them from normal NTP peers. Reference clock addresses are of the form <tt>127.127.<i>t.u</i></tt>, where <i><tt>t</tt></i> is an integer denoting the clock type and <i><tt>u</tt></i> indicates the unit number in the range 0-3. While it may seem overkill, it is in fact sometimes useful to configure multiple reference clocks of the same type, in which case the unit numbers must be unique. + +<p>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 <tt>fudge</tt> command is used to provide additional information for individual clock drivers and normally follows immediately after the <tt>server</tt> command. The <i><tt>address</tt></i> argument specifies the clock address. The <tt>refid</tt> and <tt>stratum</tt> options control can be used to override the defaults for the device. There are two optional device-dependent time offsets and four flags that can be included in the <tt>fudge</tt> command as well. + +<p>The stratum number of a reference clock is by default zero. Since the <tt>ntpd</tt> daemon adds one to the stratum of each peer, a primary server ordinarily displays an external stratum of one. In order to provide engineered backups, it is often useful to specify the reference clock stratum as greater than zero. The <tt>stratum</tt> option is used for this purpose. Also, in cases involving both a reference clock and a pulse-per-second (PPS) discipline signal, it is useful to specify the reference clock identifier as other than the default, depending on the driver. The <tt>refid</tt> option is used for this purpose. Except where noted, these options apply to all clock drivers. + +<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> +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 or operating system latencies, different cable lengths or receiver internal delay. The specified offset is in addition to the propagation delay provided by other means, such as internal DIPswitches. Where a calibration for an individual system and driver is available, an approximate correction is noted in the driver documentation pages.</dd> + +<p><dd>Note: in order to facilitate calibration when more than one radio clock or PPS signal is supported, a special calibration feature is available. It takes the form of an argument to the <tt>enable</tt> command described in the <a href=miscopt.htm>Miscellaneous Options</a> page and operates as described in the <a href=refclock.hrm>Reference Clock Drivers</a> page.</dd> + +<dt><tt>time2 <i>secs</i></tt></dt> +<dd>Specifies a fixed-point decimal number in seconds, which is interpreted in a driver-dependent way. See the descriptions of specific drivers in the <a HREF="refclock.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. Further information on the <tt>filegen</tt> command can be found in the <a HREF="monopt.htm">Monitoring Options </a>page.</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 index f8606f2..2fafb0c 100644 --- a/contrib/ntp/html/config.htm +++ b/contrib/ntp/html/config.htm @@ -1,11 +1,15 @@ -<HTML><HEAD><TITLE> +<html><head><title> Configuration Options -</TITLE></HEAD><BODY><H3> +</title></head><body><h3> Configuration Options -</H3> +</h3> -<IMG align=left SRC="pic/pogo3a.gif">From <i>pogo</i>, Walt Kelly -<BR clear=left><HR> +<img align=left src=pic/pogo3a.gif><a +href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>Pogo</i>, +Walt Kelly</a> + +<p>Gnu autoconfigure tools are in the backpack. +<br clear=left><hr> <H4>Basic Configuration Options - the <TT>configure</TT> utility</H4> @@ -18,273 +22,166 @@ 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: +options, as of the 4.0.99m version: <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 - - +Configuration: +<PRE> + --cache-file=FILE cache test results in FILE + --help print this message + --no-create do not create output files + --quiet, --silent do not print `checking...' messages + --version print the version of autoconf that created configure -Directory and file names +</PRE> - --prefix=PREFIX install -architecture-independent files in - - -PREFIX [/usr/local] - --exec-prefix=EPREFIX install architecture-dependent files -in EPREFIX - - +Directory and file names: + +<PRE> + --prefix=PREFIX install architecture-independent files in PREFIX +[/usr/local] + --exec-prefix=EPREFIX install architecture-dependent files in EPREFIX [same as prefix] - -- -bindir=DIR -user executables in DIR [EPREFIX/bin] - -- -sbindir=DIR system -admin executables in DIR [EPREFIX/sbin] - --libexecdir=DIR program -executables in DIR [EPREFIX/libexec] - -- -datadir=DIR read- -only architecture-independent data in DIR - - + --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 - - + --sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc] - --sharedstatedir=DIR modifiable architecture- -independent data in DIR - - + --sharedstatedir=DIR modifiable architecture-independent data in DIR [PREFIX/com] - --localstatedir=DIR modifiable single-machine -data in DIR - - + --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 - - + --libdir=DIR object code libraries in DIR [EPREFIX/lib] + --includedir=DIR C header files in DIR [PREFIX/include] + --oldincludedir=DIR C header files for non-gcc in DIR [/usr/include] + --infodir=DIR info documentation in DIR [PREFIX/info] + --mandir=DIR man documentation in DIR [PREFIX/man] + --srcdir=DIR find the sources in DIR [configure dir or ..] + --x-includes=DIR X include files are in DIR + --x-libraries=DIR X library files are in DIR + --program-prefix=PREFIX prepend PREFIX to installed program names -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 - - + --program-suffix=SUFFIX append SUFFIX to installed program +names + --program-transform-name=PROGRAM run sed PROGRAM on installed program +names +</PRE> + +Host type: + +<PRE> + --build=BUILD configure for building on BUILD [BUILD=HOST] + --host=HOST configure for HOST [guessed] + --target=TARGET configure for TARGET [TARGET=HOST] +</PRE> + +Optional packages: + +<PRE> + --with-PACKAGE[=ARG] use PACKAGE [ARG=yes] + --without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no) + + openssl-libdir=DIR OpenSSL object code libraries in DIR [/usr/lib +/usr/local/lib /usr/local/ssl/lib] + openssl-incdir=DIR OpenSSL header files in DIR [/usr/include +/usr/local/include /usr/local/ssl/include] + crypto=autokey Use autokey cryptography + crypto=rsaref Use the RSAREF library + electricfence Compile with ElectricFence malloc debugger +</PRE> + +Optional features: + +<PRE> + --disable-FEATURE do not include FEATURE (same as +--enable-FEATURE=no) + --enable-FEATURE[=ARG] include FEATURE [ARG=yes] + + accurate-adjtime The adjtime() call is accurate + debugging Include debugging code [enable] + des Include support for DES keys [enable] + dst-minutes=VALUE Minutes per DST adjustment [60] + gdt-surveying Include GDT survey code [disable] + hourly-todr-sync If we should sync TODR hourly + kernel-fll-bug If we should avoid a (Solaris) kernel FLL bug + kmem Read /dev/kmem for 'tick' and/or 'tickadj' + md5 Include support for MD5 keys [enable] + ntpdate-step If ntpdate should step the time + slew-always Always slew the time + step-slew Step and slew the time + tick=VALUE Force a value for 'tick' + tickadj=VALUE Force a value for 'tickadj' + udp-wildcard Use UDP wildcard delivery +</PRE> + +Radio clocks (these are ordinarily enabled, if supported by the +machine and operating system): + +<PRE> + all-clocks Include drivers for all suitable non-PARSE +clocks [enable] + ACTS NIST dialup clock + ARBITER Arbiter 1088A/B GPS receiver + ARCRON_MSF Arcron MSF receiver + AS2201 Austron 2200A or 2201A GPS receiver + ATOM ATOM PPS interface + AUDIO-CHU CHU audio decoder + BANCOMM Datum/Bancomm BC635/VME interface + (requires an explicit --enable-BANCOMM request) + CHRONOLOG Chrono-log K-series WWVB receiver + CHU CHU modem decoder + DATUM Datum Programmable Time System + DUMBCLOCK Dumb generic hh:mm:ss local clock + FG Forum Graphic GPS + GPSVME TrueTime GPS receiver with VME interface + (requires an explicit --enable-GPSVME request) + HEATH HeathKit GC-1000 Most Accurate Clock + HOPFPCI HOPF 6039 PCI board + HOPFSERIAL HOPF serial clock device + HPGPS HP 58503A GPS Time & Frequency receiver + IRIG IRIG (Audio) Clock + JUPITER Rockwell Jupiter GPS receiver + LEITCH Leitch CSD 5300 Master Clock System Driver + LOCAL-CLOCK Local clock driver + MSFEES EES M201 MSF receiver + MX4200 Magnavox MX4200 GPS receiver + NMEA NMEA GPS receiver + ONCORE Motorola VP/UT Oncore GPS receiver + PALISADE Palisade clock + PCF Conrad parallel port radio clock + PST PST/Traconex 1020 WWV/H receiver + PTBACTS PTB dialup clock support + SHM Clock attached through shared memory + (requires an explicit --enable-SHM request) + SPECTRACOM Spectracom 8170/Netclock/2 WWVB receiver + TRAK TRAK 8810 GPS station clock + TPRO KSI/Odetics TPRO/S IRIG Interface + TRUETIME Kinemetrics/TrueTime (generic) receiver + ULINK Ultralink WWVB receiver + USNO US Naval Observatory dialup clock + WWV WWV audio receiver +</PRE> + +PARSE Clocks: + +<PRE> + parse-clocks Include drivers for all suitable PARSE 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> + COMPUTIME Diem Computime Radio Clock + DCF7000 ELV/DCF7000 Clock + HOPF6021 HOPF 6021 Radio Clock support + MEINBERG Meinberg clocks + RAWDCF DCF77 raw time code + RCC8000 RCC 8000 Radio Clock support + SCHMID SCHMID DCF77 clock support + TRIMTAIP Trimble GPS/TAIP Protocol + TRIMTSIP Trimble GPS/TSIP Protocol + VARITEXT VARITEXT clock + WHARTON Wharton 400A Series clock +</PRE> <hr><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> diff --git a/contrib/ntp/html/confopt.htm b/contrib/ntp/html/confopt.htm index 68ddf7f..8f911ef 100644 --- a/contrib/ntp/html/confopt.htm +++ b/contrib/ntp/html/confopt.htm @@ -1,330 +1,257 @@ -<html><head><title> -Configuration Options -</title></head><body><h3> -Configuration Options -</h3><hr> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Configuration Options</title> +</head> +<body> +<h3>Configuration Options</h3> +<img align="left" src="pic/boom3a.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>The chicken is getting configuration advice.<br clear="left"> +</p> + +<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> +NTPv4. These commands have the same basic functions as in NTPv3 and +in some cases new functions and new arguments. There are two +classes of commands, configuration commands that configure a +persistent association with a remote server or peer or reference +clock, and auxilliary commands that specify environmental variables +that control various related operations.</p> + +<h4>Configuration Commands</h4> + +<p>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 +only those options applicable to each command are listed below. Use +of options not listed may not be caught as an error, but may result +in some weird and even destructive behavior.</p> + +<dl> +<dt><tt>server <i>address</i> [key <i>key</i> | autokey] [burst] +[iburst] [version <i>version</i>] [prefer] [minpoll <i>minpoll</i>] +[maxpoll <i>maxpoll</i>]</tt></dt> + +<dt><tt>peer <i>address</i> [key <i>key</i> | autokey] [version <i> +version</i>] [prefer] [minpoll <i>minpoll</i>] [maxpoll <i> +maxpoll</i>]</tt></dt> + +<dt><tt>broadcast <i>address</i> [key <i>key</i> | autokey] +[version <i>version</i>] [minpoll <i>minpoll</i>] [ttl <i> +ttl</i>]</tt></dt> + +<dt><tt>manycastclient <i>address</i> [key <i>key</i> | autokey] +[version <i>version</i>] [minpoll <i>minpoll</i> [maxpoll <i> +maxpoll</i>] [ttl <i>ttl</i>]</tt></dt> + +<dd>These four commands specify the time server name or address to +be used and the mode in which to operate. The <i>address</i> can be +either a DNS name or a IP address in dotted-quad notation. +Additional information on association behavior can be found in the +<a href="assoc.htm">Association Management</a> page. + +<dl> +<dt><tt>server</tt></dt> + +<dd>For type s and r addresses, this command mobilizes a persistent +client mode association with the specified remote server or local +radio clock. In this mode the local clock can synchronized to the +remote server, but the remote server can never be synchronized to +the local clock. This command should NOT be used for type <tt> +b</tt> or <tt>m</tt> addresses.</dd> + +<dt><tt>peer</tt></dt> + +<dd>For type s addresses (only), this command mobilizes a +persistent symmetric-active mode association with the specified +remote peer. In this mode the local clock can be synchronized to +the remote peer or the remote peer can be synchronized to the local +clock. This is useful in a network of servers where, depending on +various failure scenarios, either the local or remote peer may be +the better source of time. This command should NOT be used for type +<tt>b</tt>, <tt>m</tt> or <tt>r</tt> addresses.</dd> + +<dt><tt>broadcast</tt></dt> + +<dd>For type <tt>b</tt> and <tt>m</tt> addresses (only), this +command mobilizes a persistent broadcast mode association. Multiple +commands can be used to specify multiple local broadcast interfaces +(subnets) and/or multiple multicast groups. Note that local +broadcast messages go only to the interface associated with the +subnet specified, but multicast messages go to all interfaces.</dd> + +<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> + +<dt><tt>manycastclient</tt></dt> + +<dd>For type <tt>m</tt> addresses (only), this command 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>The <tt>manycast</tt> command specifies that the local server +is to operate in client mode with the remote servers that are +discovered as the result of broadcast/multicast messages. The +client broadcasts a request message to the group address associated +with the specified <i><tt>address</tt></i> and specifically enabled +servers respond to these messages. The client selects the servers +providing the best time and continues as with the <tt>server</tt> +command. The remaining servers are discarded as if never +heard.</dd> + +<dt>Options</dt> + +<dt><tt>autokey</tt></dt> + +<dd>All packets sent to and received from the server or peer are to +include authentication fields encrypted using the autokey scheme +described in the <a href="authopt.htm">Authentication Options</a> +page.</dd> + +<dt><tt>burst</tt></dt> + +<dd>when the server is reachable and at each poll interval, send a +burst of eight packets instead of the usual one packet. The spacing +between the first and the second packets is about 16s to allow a +modem call to complete, while the spacing between the remaining +packets is about 2s. This is designed to improve timekeeping +quality with the <tt>server</tt> command and <tt>s</tt> +addresses.</dd> + +<dt><tt>iburst</tt></dt> + +<dd>When the server is unreachable and at each poll interval, send +a burst of eight packets instead of the usual one. As long as the +server is unreachable, the spacing between packets is about 16s to +allow a modem call to complete. Once the server is reachable, the +spacing between packets is about 2s. This is designed to speed the +initial synchronization acquisition with the <tt>server</tt> +command and <tt>s</tt> addresses and when <tt>ntpd</tt> is started +with the <tt>-q</tt> option.</dd> + +<dt><tt>key</tt> <i><tt>key</tt></i></dt> + +<dd>All packets sent to and received from the server or peer are to +include authentication fields encrypted using the specified <i> +key</i> identifier with values from 1 to 65534, inclusive. The +default is to include no encryption field.</dd> + +<dt><tt>minpoll <i>minpoll</i></tt><br> +<tt>maxpoll <i>maxpoll</i></tt></dt> + +<dd>These options specify the minimum and maximum poll intervals +for NTP messages, in seconds to the power of two. The maximum poll +interval defaults to 10 (1,024 s), but can be increased by the <tt> +maxpoll</tt> option to an upper limit of 17 (36.4 h). The minimum +poll interval defaults to 6 (64 s), but can be decreased by the +<tt>minpoll</tt> option to a lower limit of 4 (16 s).</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> + +<dt><tt>ttl <i>ttl</i></tt></dt> + +<dd>This option is used only with broadcast server and manycast +client modes. It specifies the time-to-live <i><tt>ttl</tt></i> to +use on broadcast server and multicast server and the maximum <i> +<tt>ttl</tt></i> for the expanding ring search with manycast client +packets. Selection of the proper value, which defaults to 127, is +something of a black art and should be coordinated with the network +administrator.</dd> + +<dt><tt>version <i>version</i></tt></dt> + +<dd>Specifies the version number to be used for outgoing NTP +packets. Versions 1-4 are the choices, with version 4 the +default.</dd> +</dl> +</dd> +</dl> + +<h4>Auxilliary Commands</h4> <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> +<dt><tt>broadcastclient</tt></dt> + +<dd>This command enables reception of broadcast server messages to +any local interface (type b) address. Upon receiving a message for +the first time, the broadcast client measures the nominal server +propagation delay using a brief client/server exchange with the +server, then enters the broadcast client mode, in which it +synchronizes to succeeding broadcast messages. Note that, in order +to avoid accidental or malicious disruption in this mode, both the +server and client should operate using symmetric-key or public-key +authentication as described in the <a href="authopt.htm"> +Authentication Options</a> page.</dd> + +<dt><tt>manycastserver <i>address</i> [...]</tt></dt> + +<dd>This command enables reception of manycast client 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. Note that, in order to avoid +accidental or malicious disruption in this mode, both the server +and client should operate using symmetric-key or public-key +authentication as described in the <a href="authopt.htm"> +Authentication Options</a> page.</dd> + +<dt><tt>multicastclient [<i>address</i>] [...]</tt></dt> + +<dd>This command enables reception of multicast server messages to +the multicast group address(es) (type m) specified. Upon receiving +a message for the first time, the multicast client measures the +nominal server propagation delay using a brief client/server +exchange with the server, then enters the broadcast client mode, in +which it synchronizes to succeeding multicast messages. Note that, +in order to avoid accidental or malicious disruption in this mode, +both the server and client should operate using symmetric-key or +public-key authentication as described in the <a href= +"authopt.htm">Authentication Options</a> page.</dd> </dl> +<h4>Bugs</h4> + +<p>The syntax checking is not picky; some combinations of +ridiculous and even hilarious options and modes may not be +detected.</p> + <hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> -<address> - David L. Mills (mills@udel.edu) -</address> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> </body> </html> + diff --git a/contrib/ntp/html/copyright.htm b/contrib/ntp/html/copyright.htm index 527b5d0..2f052a7 100644 --- a/contrib/ntp/html/copyright.htm +++ b/contrib/ntp/html/copyright.htm @@ -1,202 +1,142 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> <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 +<img align=left 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. +<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-2000 * - * * - * 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: +<pre> +*********************************************************************** +* * +* Copyright (c) David L. Mills 1992-2001 * +* * +* 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: altmeier@atlsoft.de">Bernd Altmeier <altmeier@atlsoft.de></a> hopf Elektronik serial line and PCI-bus devices</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> +<kirkwood@striderfm.intel.com></a> port to WindowsNT 3.5</li> -<LI><A HREF="mailto: michael.barone@lmco.com">Michael Barone -<michael,barone@lmco.com></a> GPSVME fixes</LI> +<li><A HREF="mailto: michael.barone@lmco.com">Michael Barone <michael,barone@lmco.com></a> GPSVME fixes</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: karl@owl.HQ.ileaf.com">Karl Berry <karl@owl.HQ.ileaf.com></a> syslog to file option</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: 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: 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: Marc.Brett@westgeo.com">Marc Brett <Marc.Brett@westgeo.com></a> Magnavox GPS clock driver</li> -<LI><A HREF="mailto: clift@ml.csiro.au">Steve Clift -<clift@ml.csiro.au></a> OMEGA clock driver</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:casey@csc.co.za">Casey Crellin -<casey@csc.co.za></a> vxWorks (Tornado) port and help with target -configuration</LI> +<li><A HREF="mailto: reg@dwf.com">Reg Clemens <reg@dwf.com></a> Oncore driver (Current maintainer)</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: clift@ml.csiro.au">Steve Clift <clift@ml.csiro.au></a> OMEGA clock driver</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: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: 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: 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: dundas@salt.jpl.nasa.gov">John A. Dundas III <dundas@salt.jpl.nasa.gov></a> Apple A/UX port</li> -<LI><A HREF="mailto: glenn@herald.usask.ca">Glenn Hollinger -<glenn@herald.usask.ca></a> GOES clock driver</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: iglesias@uci.edu">Mike Iglesias -<iglesias@uci.edu></a> DEC Alpha 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: jagubox.gsfc.nasa.gov">Jim Jagielski -<jim@jagubox.gsfc.nasa.gov></a> A/UX port</LI> +<li><A HREF="mailto: glenn@herald.usask.ca">Glenn Hollinger <glenn@herald.usask.ca></a> GOES clock driver</li> -<LI><A HREF="mailto: jbj@chatham.usdesign.com">Jeff Johnson -<jbj@chatham.usdesign.com></a> massive prototyping overhaul</LI> +<li><A HREF="mailto: iglesias@uci.edu">Mike Iglesias <iglesias@uci.edu></a> DEC Alpha port</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: jagubox.gsfc.nasa.gov">Jim Jagielski <jim@jagubox.gsfc.nasa.gov></a> A/UX port</li> -<LI><A HREF="mailto:Hans.Lambermont@nl.origin-it.com">Hans Lambermont -<Hans.Lambermont@nl.origin-it.com></A> or <A -HREF="mailto:H.Lambermont@chello.nl"><H.Lambermont@chello.nl></A> -ntpsweep</LI> +<li><A HREF="mailto: jbj@chatham.usdesign.com">Jeff Johnson <jbj@chatham.usdesign.com></a> massive prototyping overhaul</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:Hans.Lambermont@nl.origin-it.com">Hans Lambermont <Hans.Lambermont@nl.origin-it.com></A> or <A +HREF="mailto:H.Lambermont@chello.nl"><H.Lambermont@chello.nl></A> ntpsweep</li> -<LI><A HREF="mailto: dkatz@cisco.com">Dave Katz -<dkatz@cisco.com></a> RS/6000 AIX port</LI> +<li><A HREF="mailto: phk@FreeBSD.ORG">Poul-Henning Kamp <phk@FreeBSD.ORG></a> Oncore driver (Original author)</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="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: lindholm@ucs.ubc.ca">George Lindholm -<lindholm@ucs.ubc.ca></a> SunOS 5.1 port</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: louie@ni.umd.edu">Louis A. Mamakos -<louie@ni.umd.edu></a> MD5-based authentication</LI> +<li><A HREF="mailto: dkatz@cisco.com">Dave Katz <dkatz@cisco.com></a> RS/6000 AIX port</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: leres@ee.lbl.gov">Craig Leres +<leres@ee.lbl.gov></a> 4.4BSD port, ppsclock, Magnavox GPS clock driver</li> -<LI><A HREF="mailto: mills@udel.edu">David L. Mills -<mills@udel.edu></a> Version 4 foundation: clock discipline, -authentication, precision kernel; clock drivers: Spectracom, Austron, -Arbiter, Heath, ATOM, ACTS, KSI/Odetics; audio clock drivers: CHU, -WWV/H, IRIG</LI> +<li><A HREF="mailto: lindholm@ucs.ubc.ca">George Lindholm <lindholm@ucs.ubc.ca></a> SunOS 5.1 port</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: louie@ni.umd.edu">Louis A. Mamakos <louie@ni.umd.edu></a> MD5-based authentication</li> -<LI><A HREF="mailto: mogul@pa.dec.com">Jeffrey Mogul -<mogul@pa.dec.com></a> ntptrace utility</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: tmoore@fievel.daytonoh.ncr.com">Tom Moore -<tmoore@fievel.daytonoh.ncr.com></a> i386 svr4 port</LI> +<li><A HREF="mailto: mills@udel.edu">David L. Mills <mills@udel.edu></a> Version 4 foundation: clock discipline, authentication, precision kernel; clock drivers: Spectracom, Austron, Arbiter, Heath, ATOM, ACTS, KSI/Odetics; audio clock drivers: CHU, WWV/H, IRIG</li> -<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: moeller@gwdgv1.dnet.gwdg.de">Wolfgang Moeller <moeller@gwdgv1.dnet.gwdg.de></a> VMS 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: mogul@pa.dec.com">Jeffrey Mogul <mogul@pa.dec.com></a> ntptrace utility</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: tmoore@fievel.daytonoh.ncr.com">Tom Moore <tmoore@fievel.daytonoh.ncr.com></a> i386 svr4 port</li> -<LI><A HREF="mailto: wsanchez@apple.com">Wilfredo Sánchez -<wsanchez@apple.com></A> added support for NetInfo</LI> +<li><A HREF="mailto: kamal@whence.com">Kamal A Mostafa <kamal@whence.com></a> SCO OpenServer port</li> -<LI><A HREF="mailto: mrapple@quack.kfu.com">Nick Sayer -<mrapple@quack.kfu.com></a> SunOS streams modules</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: jack@innovativeinternet.com">Jack Sasportas -<jack@innovativeinternet.com></A> Saved a Lot of space on the -stuff in the html/pic/ subdirectory</LI> +<li><A HREF="mailto: 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: schnitz@unipress.com">Ray Schnitzler -<schnitz@unipress.com></a> Unixware1 port</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: shields@tembel.org">Michael Shields -<shields@tembel.org></a> USNO clock driver</LI> +<li><A HREF="mailto: wsanchez@apple.com">Wilfredo Sánchez <wsanchez@apple.com></A> added support for NetInfo</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: mrapple@quack.kfu.com">Nick Sayer <mrapple@quack.kfu.com></a> SunOS streams modules</li> -<LI><A HREF="mailto: harlan@pfcs.com">Harlan Stenn -<harlan@pfcs.com></a> GNU automake/autoconfigure makeover, various -other bits (see the ChangeLog)</LI> +<li><A HREF="mailto: jack@innovativeinternet.com">Jack Sasportas <jack@innovativeinternet.com></A> Saved a Lot of space on the stuff in the html/pic/ subdirectory</li> -<LI><A HREF="mailto: ken@sdd.hp.com">Kenneth Stone -<ken@sdd.hp.com></a> HP-UX port</LI> +<li><A HREF="mailto: schnitz@unipress.com">Ray Schnitzler <schnitz@unipress.com></a> Unixware1 port</li> -<LI><A HREF="mailto: ajit@ee.udel.edu">Ajit Thyagarajan -<ajit@ee.udel.edu></a>IP multicast/anycast support</LI> +<li><A HREF="mailto: shields@tembel.org">Michael Shields <shields@tembel.org></a> USNO clock driver</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: pebbles.jpl.nasa.gov">Jeff Steinman <jss@pebbles.jpl.nasa.gov></a> Datum PTS 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: harlan@pfcs.com">Harlan Stenn <harlan@pfcs.com></a> GNU automake/autoconfigure makeover, various other bits (see the ChangeLog)</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: ken@sdd.hp.com">Kenneth Stone <ken@sdd.hp.com></a> HP-UX port</li> -</OL> +<li><A HREF="mailto: ajit@ee.udel.edu">Ajit Thyagarajan <ajit@ee.udel.edu></a>IP multicast/anycast support</li> -<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> +<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> + +</ol> + +<hr> +<a href=index.htm><img align=left src=pic/home.gif alt="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/debug.htm b/contrib/ntp/html/debug.htm index bf16049..564bb18 100644 --- a/contrib/ntp/html/debug.htm +++ b/contrib/ntp/html/debug.htm @@ -1,288 +1,477 @@ -<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 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>NTP Debugging Techniques</title> +</head> +<body> +<h3>NTP Debugging Techniques</h3> + +<img align="left" src="pic/pogo.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>We make house calls and bring our own bugs.<br clear="left"> +</p> + +<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 and receiving messages, as specified in the +configuration file.</p> + +<h4>Initial Startup</h4> + +<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 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 reconfigure and enable or disable some functions while +the daemon is running.</p> + +<p>In extreme cases with elusive bugs, the daemon can operate in +two modes, depending on the presence of the <tt>-d</tt> +command-line debug switch. If not present, the daemon detaches from +the controlling terminal and proceeds autonomously. If one or more +<tt>-d</tt> switches are present, the daemon does not detach and +generates special output useful for debugging. In general, +interpretation of this output requires reference to the sources. +However, a single <tt>-d</tt> does produce only mildly cryptic +output and can be very useful in finding problems with +configuration and network troubles. With a little experience, the +volume of output can be reduced by piping the output to <tt> +grep</tt> and specifying the keyword of the trace you want to +see.</p> + +<p>Some problems are immediately apparent when the daemon first +starts running. The most common of these are the lack of a UDP port +for NTP (123) in the Unix <tt>/etc/services</tt> file (or +equivalent in some systems). 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 exists and that the address responds to the Unix +<tt>ping</tt> command.</p> + +<p>When first started, the daemon normally polls the servers listed +in the configuration file at 64-s intervals. In order to allow a sufficient number of samples for the NTP algorithms to reliably -discriminate between 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 +discriminate between correctly operating servers and possible +intruders, at least four valid messages from the majority of +servers and peers listed in the configuration file is required +before the daemon can set the local clock. However, if the +difference between the client time and server time is greater than +the panic threshold, which defaults to 1000 s, the daemon will send +a message to the system log and shut down without setting the +clock. It is necessary to set the local clock to within the panic +threshold first, either manually by eyeball and wristwatch and the +Unix <tt>date</tt> command, or by the <tt>ntpdate</tt> or <tt>ntpd +-q</tt> commands. The panic threshold can be changed by the <tt> +tinker panic</tt> command discribed on the <a href="miscopt.htm"> +Miscellaneous Options</a> page. The panic threshold can be disabled +entirely by the <tt>-g</tt> command line option described on the <a +href="ntpd.htm">ntpd - Network Time Protocol (NTP) daemon</a> +page.</p> + +<p>If the difference between local time and server time is less +than the panic threshold but greater than the step threshold, which +defaults to 125 ms, the daemon will perform a step adjustment; +otherwise, it will gradually slew the clock to the nominal time. +The step threshold can be changed by the <tt>tinker step</tt> +command discribed on the <a href="miscopt.htm">Miscellaneous +Options</a> page. The step threshold can be disabled entirely by +the <tt>-x</tt> command line option described on the <a href= +"ntpd.htm">ntpd - Network Time Protocol (NTP) daemon</a> page. In +this case the clock will never be stepped; however, users should +understand the implications for doing this in a distributed data +network where all processing must be tightly synchronized. See the +<a href="leap.htm">NTP Timescale and Leap Seconds</a> page for +further information. If a step adjustment is made, the clock +discipline algorithm will start all over again, requiring another +round of at least four messages as before. This is necessary so +that all servers and peers operate on the same set of time +values.</p> + +<p>The clock discipline algorithm is designed to avoid large noise +spikes that might occur on a congested network or access line. If +an offset sample exceeds the step threshold, it is ignored and a +timer started. If a later sample is below the step threshold, the +counter is reset. However, if the counter is greater than the +stepout interval, which defaults to 900 s, the next sample will +step or slew the time as directed. The stepout threshold can be +changed by the <tt>tinker stepout</tt> command discribed on the <a +href="miscopt.htm">Miscellaneous Options</a> page.</p> + +<p>If, as discussed later on this page, for some reason the +hardware clock oscillator frequency error is very large, the time +errors upon first startup of the daemon may increase over time +until exceeding the step threshold, which requires another step +correction. However, due to provisions that reduce vulnerability to +noise spikes, the second correction will not be done until after +the stepout threshold. When the frequency error is very large, it +may take a number of cycles like this until converging on the +nominal frequency correction. After this, the correction is written +to the <tt>ntp.drift</tt> file, which is read upon subsequent +restarts, so the herky-jerky cycles should not recur.</p> + +<h4>Verifying Correct Operation</h4> + +<p>After starting the daemon, run the <tt>ntpq</tt> program using +the <tt>-n</tt> switch, which will avoid possible distractions due +to name resolution problems. Use the <tt>pe</tt> command to display +a billboard showing the status of configured peers and possibly +other clients poking the daemon. After operating for a few minutes, +the display should be something like:</p> + +<pre> +ntpq> pe + remote refid st t when poll reach delay offset jitter +===================================================================== +-isipc6.cairn.ne .GPS1. 1 u 18 64 377 65.592 -5.891 0.044 ++saicpc-isiepc2. pogo.udel.edu 2 u 241 128 370 10.477 -0.117 0.067 ++uclpc.cairn.net pogo.udel.edu 2 u 37 64 177 212.111 -0.551 0.187 +*pogo.udel.edu .GPS1. 1 u 95 128 377 0.607 0.123 0.027 +</pre> + +<p>The host names or addresses shown in the <tt>remote</tt> column +correspond to the server and peer entries listed in the +configuration file; however, the DNS names might not agree if the +names listed are not the canonical DNS names. The <tt>refid</tt> +column shows the current source of synchronization, while the <tt> +st</tt> column reveals the stratum, <tt>t</tt> the type (<tt>u</tt> += unicast, <tt>m</tt> = multicast, <tt>l</tt> = local, <tt>-</tt> = +don't know), and <tt>poll</tt> the poll interval in seconds. The +<tt>when</tt> column shows the time since the peer was last heard +in seconds, while the <tt>reach</tt> column shows the status of the +reachability register (see RFC-1305) in octal. The remaining +entries show the latest delay, offset and jitter in milliseconds. +Note that in NTP Version 4 what used to be the <tt>dispersion</tt> +column has been replaced by the <tt>jitter</tt> column.</p> + +<p>The tattletale symbol at the left margin displays the synchronization status of each peer. The currently selected peer is -marked <TT>*</TT>, while additional peers designated acceptable for -synchronization, 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> +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 the weighted +average computation to set the local clock; the data produced by +peers marked with other symbols are discarded. See the <tt> +ntpq</tt> page for the meaning of these symbols.</p> + +<p>Additional details for each peer separately can be determined by +the following procedure. First, use the <tt>as</tt> command to +display an index of association identifiers, such as</p> + +<pre> +ntpq> as +ind assID status conf reach auth condition last_event cnt +=========================================================== + 1 50252 f314 yes yes ok outlyer reachable 1 + 2 50253 f414 yes yes ok candidat reachable 1 + 3 50254 f414 yes yes ok candidat reachable 1 + 4 50255 f614 yes yes ok sys.peer reachable 1 +</pre> + +<p>Each line in this billboard is associated with the corresponding +line in the <tt>pe</tt> billboard above. The <tt>assID</tt> shows +the unique identifier for each mobilized association, while the +<tt>status</tt> column shows the peer status word in hex, as +defined in the NTP specification. Next, use the <tt>rv</tt> command +and the respective <tt>assID</tt> identifier to display a detailed +synopsis for the selected peer, such as</p> + +<pre> +ntpq> rv 50253 +status=f414 reach, conf, auth, sel_candidat, 1 event, event_reach, +srcadr=saicpc-isiepc2.cairn.net, srcport=123, dstadr=140.173.1.46, +dstport=123, keyid=3816249004, stratum=2, precision=-27, +rootdelay=10.925, rootdispersion=12.848, refid=pogo.udel.edu, +reftime=bd11b225.133e1437 Sat, Jul 8 2000 13:59:01.075, delay=10.550, +offset=-1.357, jitter=0.074, dispersion=1.444, reach=377, valid=7, +hmode=1, pmode=1, hpoll=6, ppoll=7, leap=00, flash=00 ok, +org=bd11b23c.01385836 Sat, Jul 8 2000 13:59:24.004, +rec=bd11b23c.02dc8fb8 Sat, Jul 8 2000 13:59:24.011, +xmt=bd11b21a.ac34c1a8 Sat, Jul 8 2000 13:58:50.672, +filtdelay= 10.45 10.50 10.63 10.40 10.48 10.43 10.49 11.26, +filtoffset= -1.18 -1.26 -1.26 -1.35 -1.35 -1.42 -1.54 -1.81, +filtdisp= 0.51 1.47 2.46 3.45 4.40 5.34 6.33 7.28, +hostname="miro.time.saic.com", publickey=3171359012, pcookie=0x6629adb2, +hcookie=0x61f99cdb, initsequence=61, initkey=0x287b649c, +timestamp=3172053041 +</pre> + +<p>A detailed explanation of the fields in this billboard are +beyond the scope of this discussion; however, most variables +defined in the NTP Version 3 specification RFC-1305 are available +along with others defined for NTP Version 4. This particular +example was chosen to illustrate probably the most complex +configuration involving symmetric modes and public-key +cryptography. As the result of debugging experience, the names and +values of these variables may change from time to time. An +explanation of the current set is on the <tt>ntpq</tt> page.</p> + +<p>A useful indicator of miscellaneous problems is the <tt> +flash</tt> value, which reveals the state of the various sanity +tests on incoming packets. There are currently eleven bits, one for +each test, numbered from the right, which is for test 1. If the +test fails, the corresponding bit is set to one and zero otherwise. +If any bit is set following each processing step, the packet is +discarded. The meaning of each test is described on the <tt> +ntpq</tt> page.</p> + +<p>The three lines identified as <tt>filtdelay</tt>, <tt> +filtoffset</tt> and <tt>filtdisp</tt> reveal the roundtrip delay, +clock offset and dispersion for each of the last eight measurement +rounds, all in milliseconds. Note that the dispersion, which is an +estimate of the error, increases as the age of the sample +increases. From these data, it is usually possible to determine the +incidence of severe packet loss, network congestion, and unstable +local clock oscillators. There are no hard and fast rules here, +since every case is unique; however, if one or more of the rounds +show large values or change radically from one round to another, +the network is probably congested or lossy.</p> + +<p>Once the daemon has set the local clock, it will continuously +track the discrepancy between local time and NTP time and adjust +the local clock accordingly. There are two components of this +adjustment, time and frequency. These adjustments are automatically +determined by the clock discipline algorithm, which functions as a +hybrid phase/frequency feedback loop. The behavior of this +algorithm is carefully controlled to minimize residual errors due +to network jitter and frequency variations of the local clock +hardware oscillator that normally occur in practice. However, when +started for the first time, the algorithm may take some time to +converge on the intrinsic frequency error of the host machine.</p> + +<p>The state of the local clock itself can be determined using the +<tt>rv</tt> command (without the argument), such as</p> + +<pre> +ntpq> rv +status=0644 leap_none, sync_ntp, 4 events, event_peer/strat_chg, +version="ntpd 4.0.99j4-r Fri Jul 7 23:38:17 GMT 2000 (1)", +processor="i386", system="FreeBSD3.4-RELEASE", leap=00, stratum=2, +precision=-27, rootdelay=0.552, rootdispersion=12.532, peer=50255, +refid=pogo.udel.edu, +reftime=bd11b220.ac89f40a Sat, Jul 8 2000 13:58:56.673, poll=6, +clock=bd11b225.ee201472 Sat, Jul 8 2000 13:59:01.930, state=4, +phase=0.179, frequency=44.298, jitter=0.022, stability=0.001, +hostname="barnstable.udel.edu", publickey=3171372095, params=3171372095, +refresh=3172016539 +</pre> + +<p>An explanation about most of these variables is in the RFC-1305 +specification. The most useful ones include <tt>clock</tt>, which +shows when the clock was last adjusted, and <tt>reftime</tt>, which +shows when the server clock of <tt>refid</tt> was last adjusted. +The <tt>version</tt>, <tt>processor</tt> and <tt>system</tt> values +are very helpful when included in bug reports. The mean millisecond +time offset (<tt>phase</tt>) and deviation (<tt>jitter</tt>) +monitor the clock quality, while the mean PPM frequency offset +(<tt>frequency</tt>) and deviation (<tt>stability</tt>) monitor the +clock stability and serve as a useful diagnostic tool. It has been +the experience of NTP operators over the years that these data +represent useful environment and hardware alarms. If the +motherboard fan freezes up or some hardware bit sticks, the system +clock is usually the first to notice it.</p> + +<p>Among the new variables added for NTP Version 4 are the <tt> +hostname</tt>, <tt>publickey</tt>, <tt>params</tt> and <tt> +refresh</tt>, which are used for the Autokey public-key +cryptography described on the <a href="authopt.htm">Authentication +Options</a> page. The values show the filestamps, in NTP seconds, +that the associated values were created. These are useful in +diagnosing problems with cryptographic key consistency and ordering +principles.</p> + +<p>When nothing seems to happen in the <tt>pe</tt> billboard after +some minutes, there may be a network problem. One common network +problem is an access controlled router on the path to the selected +peer or an access controlled server using methods described on the +<a href="accopt.htm">Access Control Options</a> page. Another +common problem is that the server is down or running in +unsynchronized mode due to a local problem. Use the <tt>ntpq</tt> +program to spy on the server variables in the same way you can spy +on your own.</p> + +<p>Normally, the daemon will adjust the local clock in small steps +in such a way that system and user programs are unaware of its +operation. The adjustment process operates continuously as long as +the apparent clock error exceeds the step threshold for a period +longer than the stepout threshold, which for most Internet paths is +a very rare event. If the event is simply an outlyer due to an +occasional network delay spike, the correction is simply discarded; +however, if the apparent time error persists for longer than the +stepout threshold of about 17 minutes, the local clock is stepped +or slewed to the new value as directed. This behavior is designed +to resist errors due to severely congested network paths, as well +as errors due to confused radio clocks upon the epoch of a leap +second.</p> + +<h4>Special Problems</h4> + +<p>The frequency tolerance of computer clock oscillators can vary +widely, which can put a strain on the daemon's ability to +compensate for the intrinsic frequency error. While the daemon can +handle frequency errors up to 500 parts-per-million (PPM), or 43 +seconds per day, values much above 100 PPM reduce the headroom and +increase the time to learn the particular value and record it in +the <tt>ntp.drift</tt> file. In extreme cases before the particular +oscillator frequency error has been determined, the residual system +time offsets can sweep from one extreme to the other of the 128-ms +tracking window only for the behavior to repeat at 900-s intervals +until the measurements have converged.</p> + +<p>In order to determine if excessive frequency error is a problem, +observe the nominal <tt>filtoffset</tt> values for a number of +rounds and divide by the poll interval. If the result is something +approaching 500 PPM, there is a good chance that NTP will not work +properly until the frequency error is reduced by some means. A +common cause is the hardware time-of-year (TOY) clock chip, which +must be disabled when NTP disciplines the software clock. For some +systems this can be done using the <tt><a href="tickadj.htm"> +tickadj</a></tt> utility and the <tt>-s</tt> command line argument. +For other systems this can be done using a command in the system +startup file.</p> + +<p>If the TOY chip is not the cause, the problem may be that the +hardware clock frequency may simply be too slow or two fast. In +some systems this might require tweaking a trimmer capacitor on the +motherboard. For other systems the clock frequency can be adjusted +in increments of 100 PPM using the <tt>tickadj</tt> utility and the +<tt>-t</tt> command line argument. Note that the <tt>tickadj</tt> +alters certain kernel variables and, while the utility attempts to +figure out an acceptable way to do this, there are many cases where +<tt>tickadj</tt> is incompatible with a running kernel.</p> + +<p>Provisions are included in <tt>ntpd</tt> for access controls +which deflect unwanted traffic from selected hosts or networks. The +controls described on the <a href="accopt.htm">Access Control +Options</a> include detailed packet filter operations based on +source address and address mask. Normally, filtered packets are +dropped without notice other than to increment tally counters. +However, the server can configure to generate what is called a +kiss-of-death (KOD) packet and send to the client. In case of +outright access denied, the KOD is the response to the first client +packet. In this case the client association is permanently disabled +and the access denied bit (test 4) is set in the flash peer +variable mentioned above and a message is sent to the system +log.</p> + +<p>The access control provisions include a limit on the packet rate +from a host or network. If an incoming packet exceeds the limit, it +is dropped and a KOD sent to the source. If this occurs after the +client association has synchronized, the association is not +disabled, but a message is sent to the system log. See the <a href= +"accopt.htm">Access Control Options</a> page for further +informatin.</p> + +<p>In some reported scenarios an access line may show low to +moderate network delays during some period of the day and moderate +to high delays during other periods. Often the delay on one +direction of transmission dominates, which can result in large time +offset errors, sometimes in the range up to a few seconds. It is +not usually convenient to run <tt>ntpd</tt> throughout the day in +such scenarios, since this could result in several time steps, +especially if the condition persists for greater than the stepout +threshold.</p> + +<p>The recommended approach in such scenarios is first to calibrate +the local clock frequency error by running <tt>ntpd</tt> in +continuous mode during the quiet interval and let it write the +frequency to the <tt>ntp.drift</tt> file. Then, run <tt>ntpd +-q</tt> from a cron job each day at some time in the quiet +interval. In systems with the nanokernel or microkernel performance +enhancements, including Solaris, Tru64, Linux and FreeBSD, the +kernel continuously disciplines the frequency so that the residual +correction produced by <tt>ntpd</tt> is usually less than a few +milliseconds.</p> + +<h4>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> +<li style="list-style: none"></li> + +<li>Verify the <tt>/etc/services</tt> file host machine is +configured to accept UDP packets on the NTP port 123. NTP is +specifically designed to use UDP and does not respond to TCP.</li> + +<li style="list-style: none"></li> + +<li>Check the system log for <tt>ntpd</tt> messages about +configuration errors, name-lookup failures or initialization +problems.</li> + +<li style="list-style: none"></li> + +<li>Verify using <tt>ping</tt> or other utility that packets +actually do make the round trip between the client and server. +Verify using <tt>nslookup</tt> or other utility that the DNS server +names do exist and resolve to valid Internet addresses.</li> + +<li>Using the <tt>ntpdc</tt> program, verify that the packets +received and packets sent counters are incrementing. If the sent +counter does not increment and the configuration file includes +configured servers, something may be wrong in the host network or +interface configuration. If this counter does increment, but the +received counter does not increment, something may be wrong in the +network or the server NTP daemon may not be running or the server +itself may be down or not responding.</li> + +<li style="list-style: none"></li> + +<li>If both the sent and received counters do increment, but the +<tt>reach</tt> values in the <tt>pe</tt> billboard with <tt> +ntpq</tt> continues to show zero, received packets are probably +being discarded for some reason. If this is the case, the cause +should be evident from the <tt>flash</tt> variable as discussed +above and on the <tt>ntpq</tt> page.</li> + +<li style="list-style: none"></li> + +<li>If the <tt>reach</tt> values in the <tt>pe</tt> billboard show +the servers are alive and responding, note the tattletale symbols +at the left margin, which indicate the status of each server +resulting from the various grooming and mitigation algorithms. The +interpretation of these symbols is discussed on the <tt>ntpq</tt> +page. After a few minutes of operation, one or another of the +reachable server candidates should show a * tattletale symbol. If +this doesn't happen, the intersection algorithm, which classifies +the servers as truechimers or falsetickers, may be unable to find a +majority of truechimers among the server population.</li> + +<li style="list-style: none"></li> + +<li>If all else fails, see the FAQ and/or the discussion and +briefings at <a href="http://www.eecis.udel.edu/~mills/ntp.htm"> +Network Time Synchronization Project.</a></li> +</ol> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/driver1.htm b/contrib/ntp/html/driver1.htm index 1f88e7d..b70010f 100644 --- a/contrib/ntp/html/driver1.htm +++ b/contrib/ntp/html/driver1.htm @@ -1,157 +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> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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> + +<p>This driver is intended for use in an isolated network where no +external source of synchronization such as a radio clock or modem +is available. It allows a designated time server to act as a +primary server to provide synchronization to other clients on the +network. Pick a machine that has a good clock oscillator (Digital +machines are good, Sun machines are not) and configure it with this +driver. Set the clock using the best means available, like +eyeball-and-wristwatch. Then, point all the other machines at this +one or use broadcast (not multicast) mode to distribute time.</p> + +<p>Another application for this driver is if a particular server +clock is to be used as the clock of last resort when all other +normal synchronization sources have gone away. This is especially +useful if that server has an ovenized oscillator. For this you +would configure this driver at a stratum greater than any other +likely sources of time (say 3 or 4) to prevent the server taking +over when legitimate sources are still available.</p> + +<p>A third application for this driver is when an external +discipline source is available, such as the NIST <tt>lockclock</tt> +program, which synchronizes the local clock via a telephone modem +and the NIST Automated Computer Time Service (ACTS), or the Digital +Time Synchronization Service (DTSS), which runs on DCE machines. In +this case the stratum should be set at zero, indicating a bona fide +stratum-1 source. In the case of DTSS, the local clock can have a +rather large jitter, depending on the interval between corrections +and the intrinsic frequency error of the clock oscillator. In +extreme cases, this can cause clients to exceed the 128-ms slew +window and drop off the NTP subnet.</p> + +<p>In the case where a NTP time server is synchronized to some +device or protocol that is not external to the NTP daemon itself, +some means should be provided to pass such things as error and +health values to the NTP daemon for dissemination to its clients. +If this is not done, there is a very real danger that the device or +protocol could fail and with no means to tell NTP clients of the +mishap. When ordinary Unix system calls like <tt>adjtime()</tt> are +used to discipline the kernel clock, there is no obvious way this +can be done without modifying the code for each case. However, when +a modified kernel with the <tt>ntp_adjtime()</tt> system call +is available, that routine can be used for the same purpose as the +<tt>adjtime()</tt> routine and in addition provided with the +estimated error, maximum error, and leap-indicator values. This is +the preferred way to synchronize the kernel clock and pass +information to the NTP clients.</p> + +<p>In the default mode the behavior of the clock selection +algorithm is modified when this driver is in use. The algorithm is +designed so that this driver will never be selected unless no other +discipline source is available. This can be overridden with the +<tt>prefer</tt> keyword of the <tt>server</tt> configuration +command, in which case only this driver will be selected for +synchronization and all other discipline sources will be ignored. +This behavior is intended for use when an external discipline +source controls the system clock. See the <a href="prefer.htm"> +Mitigation Rules and the <tt>prefer</tt> Keyword</a> page for a +detailed description of the exact behavior.</p> + +<p>The stratum for this driver is set at 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> + +<p>This driver provides a mechanism to trim the local clock in both +time and frequency, as well as a way to manipulate the leap bits. +The <tt>fudge time1</tt> parameter adjusts the time (in seconds) +and the <tt>fudge time2</tt> parameter adjusts the frequency (in +parts per million). Both parameters are additive and operate only +once; that is, each command (as from <tt>ntpdc</tt>) adds signed +increments in time or frequency to the nominal local clock time and +frequency.</p> + +<h4>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> +</dl> + +<p>Additional Information</p> + +<p><a href="refclock.htm">Reference Clock Drivers</a></p> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/driver20.htm b/contrib/ntp/html/driver20.htm index e6a4bd2..6d1126b 100644 --- a/contrib/ntp/html/driver20.htm +++ b/contrib/ntp/html/driver20.htm @@ -1,39 +1,46 @@ -<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> +<!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.76 [en] (X11; U; Linux 2.2.16-22 i586) [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 by default. Alternately the <tt>$GPGGA</tt> or <tt>$GPGLL +</tt>may +be selected. +<br>The driver expects 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 +<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) +<p>If the Operating System supports the PPSAPI, RFC-2783, it will be used. +<br> +<p>The various GPS sentences that this driver recognises look like this: +<br>(others quietly ignored) +<pre><tt>$GPRMC,POS_UTC,POS_STAT,LAT,LAT_REF,LON,LON_REF,SPD,HDG,DATE,MAG_VAR,MAG_REF*CC<cr><lf> +$GPGLL,LAT,LAT_REF,LONG,LONG_REF,POS_UTC,POS_STAT*CC<cr><lf> +$GPGGA,POS_UTC,LAT,LAT_REF,LONG,LONG_REF,FIX_MODE,SAT_USED,HDOP,ALT,ALT_UNIT,GEO,G_UNIT,D_AGE,D_REF*CC<cr><lf> + + POS_UTC - UTC of position. Hours, minutes and seconds [fraction (opt.)]. (hhmmss[.fff]) POS_STAT - Position status. (A = Data valid, V = Data invalid) LAT - Latitude (llll.ll) LAT_REF - Latitude direction. (N = North, S = South) @@ -44,88 +51,111 @@ of the serial interface and operating system. DATE - Date (ddmmyy) MAG_VAR - Magnetic variation (degrees) (x.x) MAG_REF - Magnetic variation (E = East, W = West) + FIX_MODE - Position Fix Mode ( 0 = Invalid, >0 = Valid) + SAT_USED - Number Satellites used in solution + HDOP - Horizontal Dilution of Precision + ALT - Antenna Altitude + ALT_UNIT - Altitude Units (Metres/Feet) + GEO - Geoid/Elipsoid separation + G_UNIT - Geoid units (M/F) + D_AGE - Age of last DGPS Fix + D_REF - Reference ID of DGPS station CC - Checksum (optional) - <cr><lf> - Sentence terminator.</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> + <cr><lf> - Sentence terminator.</tt></pre> +Alternate GPS sentences (other than <tt>$GPRMC</tt> - the default) may +be enabled by setting the relevent bits of 'mode' in the server configuration +line +<br> * server 127.127.20.x mode X +<br> bit 0 - enables RMC ( value = +1) +<br> bit 1 - enables GGA ( value = +2) +<br> bit 2 - enables GLL +( value = 4) +<br>multiple sentences may be selected +<br> +<p>The driver will send a <tt>$PMOTG,RMC,0000*1D<cr><lf></tt> message +each time a <tt>$GPRMC</tt> string is needed. This is not needed on most +GPS receivers because they automatically send the <tt>$GPRMC</tt> string +every second and will only work on GPS receivers that understand the <tt>$PMOTG</tt> string. Others will just ignore it. -<H4> -Setting up the Garmin GPS-25XL</H4> +<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> +<pre>"$PGRMO,,2<cr><lf>"</pre> Now switch only $GPRMC on by sending it the following string. -<PRE>"$PGRMO,GPRMC,1<cr><lf>"</PRE> +<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> +<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> +<h4> +Monitor Data</h4> +The GPS sentence(s) that is used is written to the clockstats file. +<h4> +Fudge Factors</h4> -<DL> -<DT> -<TT>time1 <I>time</I></TT></DT> +<dl> +<dt> +<tt>time1 <i>time</i></tt></dt> -<DD> +<dd> Specifies the time offset calibration factor, in seconds and fraction, -with default 0.0.</DD> +with default 0.0.</dd> -<DT> -<TT>time2 <I>time</I></TT></DT> +<dt> +<tt>time2 <i>time</i></tt></dt> -<DD> -Not used by this driver.</DD> +<dd> +Not used by this driver.</dd> -<DT> -<TT>stratum <I>number</I></TT></DT> +<dt> +<tt>stratum <i>number</i></tt></dt> -<DD> -Specifies the driver stratum, in decimal from 0 to 15, with default 0.</DD> +<dd> +Specifies the driver stratum, in decimal from 0 to 15, with default 0.</dd> -<DT> -<TT>refid <I>string</I></TT></DT> +<dt> +<tt>refid <i>string</i></tt></dt> -<DD> +<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> +four characters, with default <tt>GPS</tt>.</dd> -<DT> -<TT>flag2 0 | 1</TT></DT> +<dt> +<tt>flag1 0 | 1</tt></dt> -<DD> -Not used by this driver.</DD> +<dd> +Not used by this driver.</dd> -<DT> -<TT>flag3 0 | 1</TT></DT> +<dt> +<tt>flag2 0 | 1</tt></dt> -<DD> -Not used by this driver.</DD> +<dd> +Specifies the PPS signal on-time edge: 0 for assert (default), 1 for clear.</dd> -<DT> -<TT>flag4 0 | 1</TT></DT> +<dt> +<tt>flag3 0 | 1</tt></dt> -<DD> -Not used by this driver.</DD> +<dd> +Controls the kernel PPS discipline: 0 for disable (default), 1 for enable.</dd> +<dt> +<tt>flag4 0 | 1</tt></dt> -<P>Additional Information +<dd> +Not used by this driver.</dd> -<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL> +<br> +<p> +<br> +<br> +<p>Additional Information +<p><a href="refclock.htm">Reference Clock Drivers</a></dl> -<HR> -<ADDRESS> -David L. Mills (mills@udel.edu)</ADDRESS> +<hr> +<address> +David L. Mills (mills@udel.edu)</address> -</BODY> -</HTML> +</body> +</html> diff --git a/contrib/ntp/html/driver22.htm b/contrib/ntp/html/driver22.htm index 313d2b8..a293cbc 100644 --- a/contrib/ntp/html/driver22.htm +++ b/contrib/ntp/html/driver22.htm @@ -1,129 +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>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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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 or Parallel Port: <tt>/dev/pps<i>u</i></tt> <br> +Requires: PPSAPI interface + +<p>Note: This driver supersedes an older one of the same name. The +older driver operated with several somewhat archaic signal +interface devices, required intricate configuration and was poorly +documented. This driver operates only with the PPSAPI interface +proposed as an IETF standard. Note also that the <tt>pps</tt> +configuration command has been obsoleted by this driver.</p> + +<h4>Description</h4> + +<p>This driver furnishes an interface for the pulse-per-second +(PPS) produced by a cesium clock, radio clock or related equipment. +It can be used to augment the serial timecode generated by a GPS +receiver, for example. It can be used to remove accumulated jitter +and re-time a secondary server when synchronized to a primary +server over a congested, wide-area network and before +redistributing the time to local clients. The driver includes +extensive signal sanity checks and grooming algorithms. A range +gate and frequency discriminator reject noise and signals with +incorrect frequency. A multiple-stage median filter rejects jitter +due to hardware interrupt and operating system latencies. A +trimmed-mean algorithm determines the best time samples. With +typical workstations and processing loads, the incidental jitter +can be reduced to less than a microsecond.</p> + +<p>While this driver can discipline the time and frequency relative +to the PPS source, it cannot number the seconds. For this purpose a +auxiliary source is required, ordinarily a radio clock operated as +a primary reference (stratum 1) source; however, another NTP time +server can be used as well. For this purpose, the auxiliary source +is marked as the prefer peer, as described in the <a href= +"prefer.htm">Mitigation Rules and the <tt>prefer</tt> Keyword</a> +page.</p> + +<p>The driver requires the PPSAPI interface<sup>1</sup>, which is a +proposed IETF standard. The interface consists of the <tt> +timepps.h</tt> header file and associated kernel support. Support +for this interface is included in current versions of FreeBSD and +Linux and proprietary versions for Digital/Compaq Tru64 (Alpha), +Sun Solaris and Sun SunOS. See the <a href="pps.htm"> +Pulse-per-second (PPS) Signal Interfacing</a> page for further +information.</p> + +<p>The PPS source can be connected via a serial or parallel port, +depending on the hardware and operating system. The port can be +dedicated to the PPS source or shared with another device. A radio +clock is usually connected via a serial port and the PPS source +connected via a level converter to the data carrier detect (DCD) +pin (DB-9 pin 1, DB-25 pin 8) of the same connector. In some +systems where a parallel port and driver are available, the PPS +signal can be connected directly to the ACK pin (pin 10) of the +connector. Whether the PPS signal is connected via a dedicated port +or shared with another device, the driver opens the device <tt> +/dev/pps%d</tt>, where <tt>%d</tt> is the unit number. As with +other drivers, links can be used to redirect the logical name to +the actual physical device.</p> + +<p>The driver normally operates like any other driver and uses the +same mitigation algorithms and PLL/FLL clock discipline +incorporated in the daemon. If kernel PLL/FLL support is available, +the kernel PLL/FLL clock discipline is used instead. The default +behavior is not to use the kernel PPS clock discipline, even if +present. This driver incorporates a good deal of signal processing +to reduce jitter using the median filter and trimmed average +algorithms in the driver interface. As the result, performance with +minpoll and maxpoll configured at the minimum 4 (16s) is generally +better than the kernel PPS clock discipline. However, fudge flag 3 +can be used to enable this discipline if necessary.</p> + +<p>Note that the PPS source is considered reachable only if the +auxiliary source is the prefer peer, is reachable and is selected +to discipline the system clock. The stratum assigned to the PPS +source is automatically determined. If the auxiliary source is +unreachable or inoperative, the stratum is set to 16; otherwise it +is set to match the stratum of the auxiliary source. Since the +stratum is determined dynamically, it is not possible to assign +another stratum using the <tt>fudge</tt> command as in other +drivers.</p> + +<h4>Fudge Factors</h4> + +<dl> +<dt><tt>time1 <i>time</i></tt></dt> + +<dd>Specifies the time offset calibration factor, in seconds and +fraction, with default 0.0.dd></dd> + +<dt><tt>time2 <i>time</i></tt></dt> + +<dd>Not used by this driver.</dd> + +<dt><tt>stratum <i>number</i></tt></dt> + +<dd>Specifies the driver stratum, in decimal from 0 to 15, with +default 0.</dd> + +<dt><tt>refid <i>string</i></tt></dt> + +<dd>Specifies the driver reference identifier, an ASCII string from +one to four characters, with default <tt>PPS</tt>.</dd> + +<dt><tt>flag1 0 | 1</tt></dt> + +<dd>Not used by this driver.</dd> + +<dt><tt>flag2 0 | 1</tt></dt> + +<dd>Specifies the PPS signal on-time edge: 0 for assert (default), +1 for clear.</dd> + +<dt><tt>flag3 0 | 1</tt></dt> + +<dd>Controls the kernel PPS discipline: 0 for disable (default), 1 +for enable.</dd> + +<dt><tt>flag4 0 | 1</tt></dt> + +<dd>Not used by this driver.</dd> +</dl> + +<p>Additional Information</p> + +<p><a href="refclock.htm">Reference Clock Drivers</a></p> + +<p>Reference</p> + +<ol> +<li>Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl. +Pulse-per-second API for Unix-like operating systems, version 1. +Request for Comments RFC-2783, Internet Engineering Task Force, +March 2000, 31 pp.</li> +</ol> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -</BODY> -</HTML> diff --git a/contrib/ntp/html/driver23.htm b/contrib/ntp/html/driver23.htm index 6633999..8d6fc9d 100644 --- a/contrib/ntp/html/driver23.htm +++ b/contrib/ntp/html/driver23.htm @@ -1,87 +1,178 @@ <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> + <META NAME="GENERATOR" CONTENT="Adobe PageMill 3.0 per Windows"> + <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> + <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> +<H3>PTB Modem Time Service and other European Laboratories Time +Services</H3> + +<HR ALIGN=LEFT> + +<H4>Synopsis</H4> + +<P>Address: 127.127.23.<I>u</I> <BR> +Reference ID: <TT>PTB</TT> <BR> +Driver ID: <TT>ACTS_PTB</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</P> + +<H4>Description</H4> + +<P>This driver supports the PTB Automated Computer Time Service +(ACTS) and it is a modified version of the NIST ACTS driver so +see it for more informations..</P> + +<P>It periodically dials a prespecified telephone number, receives +the PTB 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> + +<P>The only change between this driver and the NIST one is the +data format. Infact PTB data format is the following:</P> + +<P><FONT SIZE="-1" FACE="Courier New">Data format<BR> +0000000000111111111122222222223333333333444444444455555555556666666666777777777 + 7<BR> +0123456789012345678901234567890123456789012345678901234567890123456789012345678 + 9<BR> +1995-01-23 20:58:51 MEZ 10402303260219950123195849740+40000500 + *<BR> +A B C D EF G H IJ K L M N O P Q R S T U V W +XY Z<CR><LF><BR> +A year<BR> +B month<BR> +C day<BR> +D hour<BR> +E : normally<BR> +A for DST to ST switch first hour<BR> +B for DST to ST switch second hour if not marked in H<BR> +F minute<BR> +G second<BR> +H timezone<BR> +I day of week<BR> +J week of year<BR> +K day of year<BR> +L month for next ST/DST changes<BR> +M day<BR> +N hour<BR> +O UTC year<BR> +P UTC month<BR> +Q UTC day<BR> +R UTC hour<BR> +S UTC minute<BR> +T modified julian day (MJD)<BR> +U DUT1<BR> +V direction and month if leap second<BR> +W signal delay (assumed/measured)<BR> +X sequence number for additional text line in Y<BR> +Y additional text<BR> +Z on time marker (* - assumed delay / # measured delay)<BR> + <CR>!<LF> ! is second change !<BR> +</FONT><BR> +This format is an ITU-R Recommendation (ITU-R TF583.4) and is now available from the primary +timing centres of the following countries: +Austria, Belgium, Germany, Italy, The Netherlands, Poland, Portugal, Romania, Spain, Sweden, +Switzerland, Turkey, United Kingdom. +Some examples are: +</P> + +<UL> + <LI>In Germany by Physikalisch-Technische Bundesanstalt (PTB)'s + timecode service. Phone number: +49 5 31 51 20 38. +</UL> + +<BLOCKQUOTE> + <P>For more detail, see <A HREF="http://www.ptb.de/english/org/4/43/433/disse.htm">http://www.ptb.de/english/org/4/43/433/disse.htm</A></P> +</BLOCKQUOTE> + +<UL> + <LI>In the UK by National Physical Laboratory (NPL)'s TRUETIME + service. Phone number: 0891 516 333 +</UL> + +<BLOCKQUOTE> + <P>For more detail, see <A HREF="http://www.npl.co.uk/npl/ctm/truetime.html">http://www.npl.co.uk/npl/ctm/truetime.html</A></P> +</BLOCKQUOTE> + +<UL> + <LI>In Italy by Istituto Elettrotecnico Nazionale "Galileo + Ferrais" (IEN)'s CTD service. Phone number: 166 11 46 + 15 +</UL> + +<BLOCKQUOTE> + <P>For more detail, see <A HREF="http://www.ien.it/tf/time/Pagina42.html">http://www.ien.it/tf/time/Pagina42.html</A></P> +</BLOCKQUOTE> + +<UL> + <LI>In Switzerland by Swiss Federal Office of Metrology 's timecode + service. Phone number: 031 323 32 25 +</UL> + +<BLOCKQUOTE> + <P>For more detail, see <A HREF="http://www.ofmet.admin.ch/de/labors/4/Zeitvert.html%20">http://www.ofmet.admin.ch/de/labors/4/Zeitvert.html + </A></P> +</BLOCKQUOTE> + +<UL> + <LI>In Sweden by SP Swedish National Testing and Research Institute + 's timecode service. Phone number: +46 33 415783 +</UL> + +<BLOCKQUOTE> + <P>For more detail, see <A HREF="http://www.sp.se/pne/ElectricalMetrology/ElMeteng/frameset.htm">http://www.sp.se/pne/ElectricalMetrology/ElMeteng/frameset.htm</A><BR> +<BR> + </P> +</BLOCKQUOTE> + +<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>time1 <I>time</I></TT> + <DD>Specifies the time offset calibration factor, in seconds + and fraction, with default 0.0. + <DT><TT>time2 <I>time</I></TT> + <DD>Not used by this driver. + <DT><TT>stratum <I>number</I></TT> + <DD>Specifies the driver stratum, in decimal from 0 to 15, with + default 0. + <DT><TT>refid <I>string</I></TT> + <DD>Specifies the driver reference identifier, an ASCII string + from one to four characters, with default PTB. + <DT><TT>flag1 0 | 1</TT> + <DD>Not used by this driver. + <DT><TT>flag2 0 | 1</TT> + <DD>Not used by this driver. + <DT><TT>flag3 0 | 1</TT> + <DD>Not used by this driver. + <DT><TT>flag4 0 | 1</TT> + <DD>Not used by this driver. +</DL> -<DT> -<TT>flag2 0 | 1</TT></DT> +<P>Additional Information</P> -<DD> -Not used by this driver.</DD> +<P>A keyword in the ntp.conf file permits a direct connection +to a serial port of source of time like IEN CTD signal. It is +sufficient to use the string DIRECT in place of the phone number.</P> -<DT> -<TT>flag3 0 | 1</TT></DT> +<P>Example:</P> -<DD> -Not used by this driver.</DD> +<P><FONT FACE="Courier New">server 127.127.23.1</FONT></P> -<DT> -<TT>flag4 0 | 1</TT></DT> +<P><FONT FACE="Courier New">phone DIRECT</FONT></P> -<DD> -Not used by this drivert.</DD> -</DL> -Additional Information +<P><A HREF="refclock.htm">Reference Clock Drivers</A> <HR ALIGN=LEFT></P> -<P><A HREF="refclock.htm">Reference Clock Drivers</A> -<HR> -<ADDRESS> -David L. Mills (mills@udel.edu)</ADDRESS> +<ADDRESS>by Marco Mascarello (masca@tf.ien.it) for David L. Mills +(mills@udel.edu)</ADDRESS> </BODY> </HTML> + diff --git a/contrib/ntp/html/driver30.htm b/contrib/ntp/html/driver30.htm index fab604b..d2ec9dd 100644 --- a/contrib/ntp/html/driver30.htm +++ b/contrib/ntp/html/driver30.htm @@ -17,31 +17,31 @@ Motorola Oncore GPS receiver</H3> <H4> Synopsis</H4> -Address: 127.127.30.0<BR> +Address: 127.127.30.<i>u</i><BR> Reference ID: <TT>GPS</TT><BR> Driver ID: ONCORE<BR> -Serial Port: <TT>/dev/oncore.serial.0</TT>; 9600 baud, 8-bits, +Serial Port: <TT>/dev/oncore.serial.</TT><i>u</i>; 9600 baud, 8-bits, no parity.<BR> -PPS Port: <TT>/dev/oncore.pps.0</TT>; <TT>PPS_CAPTUREASSERT</TT> -required, <TT>PPS_OFFSETASSERT</TT> supported. +PPS Port: <TT>/dev/oncore.pps.</TT><i>u</i>; <TT>PPS_CAPTUREASSERT</TT> +required, <TT>PPS_OFFSETASSERT</TT> supported.<BR> +Configuration File: <TT>/etc/ntp.oncore<TT><i>u</i> or, +<TT>/etc/ntp.oncore.<TT><i>u</i>, or <TT>/etc/ntp.oncore<TT>. <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 three most interesting versions of the Oncore are the "VP", -the "UT+", -and the "Remote" which is a prepackaged "UT+". -The "VP" is no longer available. - -<P>The evaluation kit +This driver supports most models of the +<A HREF="http://www.mot.com/AECS/PNSB/products">Motorola Oncore GPS receivers</A> +(Basic, PVT6, VP, UT, UT+, GT, GT+, SL, M12), +as long as they support the <I>Motorola Binary Protocol</I>. + +<P>The three most interesting versions of the Oncore are the VP, +the UT+, and the "Remote" which is a prepackaged UT+. +The VP is no longer available. +The Motorola evaluation kit can also be recommended, it interfaces to a PC straightaway, using the serial (DCD) or parallel port for PPS input and packs the receiver in a nice and sturdy box. Two less expensive interface kits are available from -<A HREF="http://www.tapr.org">TAPR </A>. +<A HREF="http://www.tapr.org">TAPR</A>. <BR> <CENTER><TABLE NOSAVE > @@ -74,17 +74,27 @@ 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 VP/UT models. +If you do not have the PPS signal available, then you should probably be using +the NMEA driver rather than the Oncore driver. <P>The driver will use the "position hold" mode with user provided coordinates, the receivers built-in site-survey, -or a similar algorithm implemented in this driver. +or a similar algorithm implemented in this driver to determine the antenna position. <H4> Monitor Data</H4> -The driver is quite chatty on stdout if ntpd is run with -debugging. -A manual will be required though. -Additional information is written to the clockstats file, if configured. +The driver always puts a lot of useful information on the clockstats file, +and when run with debugging can be quite chatty on stdout. +When first starting to use the driver you should definitely review the information +written to the clockstats file to verify that the driver is running correctly. +<P> +In addition, on platforms supporting Shared Memory, all of the messages +received from the Oncore receiver are made available in shared memory for +use by other programs. +See the <A HREF=Oncore-SHMEM.htm> Oncore-SHMEM </A> manual page for +information on how to use this option. +For either debugging or using the SHMEM option, an Oncore Reference Manual +for the specific receiver in use will be required. <H4> Fudge Factors</H4> @@ -141,8 +151,9 @@ Not used by this driver.</DD> Not used by this driver.</DD> </DL> <B>Additional Information</B> -<P>The driver has been tested on FreeBSD, Linux and SunOS. - +<P>The driver was initially developed on FreeBSD, and has since been tested +on Linux, SunOS and Solaris. +<P><B>Configuration</B> <P>There is a driver specific configuration file <TT>/etc/ntp.oncore</TT> that contains information on the startup mode, the location of the GPS receiver, an offset of the PPS signal from zero, and the cable delay. @@ -165,11 +176,11 @@ 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 +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> +timekeeping under FreeBSD</A>. <HR> <ADDRESS> Poul-Henning Kamp (phk@FreeBSD.org), diff --git a/contrib/ntp/html/driver34.htm b/contrib/ntp/html/driver34.htm index e9dcdbc..c114c72 100644 --- a/contrib/ntp/html/driver34.htm +++ b/contrib/ntp/html/driver34.htm @@ -1,7 +1,7 @@ <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso8859-1"> -<title>Dumb Clock</title> +<title>Ultralink Clock</title> </head> <body> @@ -10,18 +10,19 @@ <hr> <h4>Synopsis</h4> Address: 127.127.34.<i>u</i><br> -Reference ID: <TT>ULINK</TT><br> +Reference ID: <TT>WWVB</TT><br> Driver ID: <tt>ULINK</tt><br> -Serial Port: <tt>/dev/ulink<i>u</i></tt>; 9600 bps, 8-bits, +Serial Port: <tt>/dev/wwvb<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). +This driver supports the Ultralink Model 320 RS-232 powered WWVB receiver. PDF specs available on <a href="http://www.ulio.com">www.ulio.com</a>. +This driver also supports the Model 330,331,332 decoders in both polled or continous time code mode. Leap second and quality are supported. <P>Most of this code is originally from refclock_wwvb.c with thanks. Any mistakes are mine. Any improvements are welcome. - +<hr> <pre> - The timecode format is: + The Model 320 timecode format is: <cr><lf>SQRYYYYDDD+HH:MM:SS.mmLT<cr> @@ -40,14 +41,55 @@ This driver supports the Ultralink Model 320 RS-232 powered WWVB receiver. PDF 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. + Note that this driver does not do anything with the T flag. - The M320 also has a 'U' command which returns UT1 correction information. It - is not used in this driver. + The M320 also has a 'U' command which returns UT1 correction information. + It is not used in this driver. +</pre> +<hr> +<pre> + The Model 33x timecode format is: + + S9+D 00 YYYY+DDDUTCS HH:MM:SSl+5 + + Where: + + S = sync indicator S insync N not in sync + the sync flag is WWVB decoder sync + nothing to do with time being correct + 9+ = signal level 0 thru 9+ If over 9 indicated as 9+ + D = data bit ( fun to watch but useless ;-) + space + 00 = hours since last GOOD WWVB frame sync + space + YYYY = current year + + = leap year indicator + DDD = day of year + UTC = timezone (always UTC) + S = daylight savings indicator + space + HH = hours + : = This is the REAL in sync indicator (: = insync) + MM = minutes + : = : = in sync ? = NOT in sync + SS = seconds + L = leap second flag + +5 = UT1 correction (sign + digit )) + + This driver ignores UT1 correction,DST indicator,Leap year + and signal level. + +</pre> +<hr> +<pre> + +Fudge factors + flag1 polling enable (1=poll 0=no poll) + </pre> <hr> - <address><a href="mailto:dstrout@linuxfoundary.com">root</a></address> + <address><a href="mailto:dstrout@linuxfoundary.com">mail</a></address> <!-- hhmts start --> Last modified: Tue Sep 14 05:53:08 EDT 1999 <!-- hhmts end --> diff --git a/contrib/ntp/html/driver35.htm b/contrib/ntp/html/driver35.htm index d3b77e0..0e6aebf 100644 --- a/contrib/ntp/html/driver35.htm +++ b/contrib/ntp/html/driver35.htm @@ -1,4 +1,4 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> <html> <head> <title>Conrad parallel port radio clock</title> @@ -13,32 +13,30 @@ <p>Address: 127.127.35.<i>u</i><br> Reference ID: <tt>PCF</tt><br> Driver ID: <tt>PCF</tt><br> -Parallel Port: <tt>/dev/pcfclock<i>u</i></tt> +Parallel Port: <tt>/dev/pcfclocks/<i>u</i></tt> or <tt>/dev/pcfclock<i>u</i></tt> </p> <h4>Description</h4> -<p>This driver supports the parallel port radio clocks sold by <a -href="http://www.conrad-electronic.com/">Conrad Electronic</a> under -order numbers 967602 and 642002. The battery-powered radio clock is -put between a parallel port and your printer. It receives the legal -German time, which is either CET or CEST, from the DCF77 transmitter -and uses it to set internal quartz clock. The DCF77 transmitter is -located near to Frankfurt/Main and covers a radius of more than 1500 -kilometers. - -<p>The driver requires that the pcfclock device driver be installed. -A device driver for Linux 2.2 is available at -<a href="http://home.pages.de/~voegele/pcf.html">the pcfclock driver -page</a>. +<p>This driver supports the parallel port radio clock sold by +<a href="http://www.conrad-electronic.com/">Conrad Electronic</a> under +order numbers 967602 and 642002. This clock is put between a parallel +port and your printer. It receives the legal German time, which is +either CET or CEST, from the DCF77 transmitter and uses it to set its +internal quartz clock. The DCF77 transmitter is located near to +Frankfurt/Main and covers a radius of more than 1500 kilometers. + +<p>The pcfclock device driver is required in order to use this +reference clock driver. Currently device drivers for +<a href="http://home.pages.de/~voegele/pcf.html">Linux</a> and +<a href="http://schumann.cx/pcfclock/">FreeBSD</a> are available.</p> + +<p>This driver uses C library functions to convert the received +timecode to UTC and thus requires that the local timezone be CET or +CEST. If your server is not located in Central Europe you have to set +the environment variable TZ to CET before starting <tt>ntpd</tt>. </p> -<p>The driver uses C library functions to convert the received -timecode to UTC and therefore requires that the local timezone be -CET/CEST. If your server is not located in Central Europe, you have -to set the environment variable TZ to CET before <tt>ntpd</tt> is -started.</p> - <h4>Monitor Data</h4> <p>Each timecode is written to the <tt>clockstats</tt> file in the format @@ -49,7 +47,7 @@ started.</p> <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> +with default 0.1725.</dd> <dt><tt>time2 <i>time</i></tt></dt> <dd>Not used by this driver.</dd> @@ -66,7 +64,8 @@ four characters, with default <tt>PCF</tt>.</dd> <dd>Not used by this driver.</dd> <dt><tt>flag2 0 | 1</tt></dt> -<dd>Not used by this driver.</dd> +<dd>If set to 1, the radio clock's synchronisation status bit is +ignored, ie the timecode is used without a check.</dd> <dt><tt>flag3 0 | 1</tt></dt> <dd>Not used by this driver.</dd> @@ -76,7 +75,6 @@ four characters, with default <tt>PCF</tt>.</dd> </dl> <hr> -<address>Andreas Voegele (andreas.voegele@gmx.de)</address> - +<address>Andreas Voegele <voegelas@users.sourceforge.net></address> </body> </html> diff --git a/contrib/ntp/html/driver36.htm b/contrib/ntp/html/driver36.htm index 6f70dcc..2c74646 100644 --- a/contrib/ntp/html/driver36.htm +++ b/contrib/ntp/html/driver36.htm @@ -1,581 +1,634 @@ -<html><head><title> -Radio WWV/H Audio Demodulator/Decoder -</title></head><body><h3> -Radio WWV/H Audio Demodulator/Decoder -</h3><hr> - +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Radio WWV/H Audio Demodulator/Decoder</title> +</head> +<body> +<h3>Radio WWV/H Audio Demodulator/Decoder</h3> + +<hr> <h4>Synopsis</h4> -Address: 127.127.36.<I>u</I> -<br>Reference ID: <tt>WWV</tt> or <tt>WWVH</tt> -<br>Driver ID: <tt>WWV_AUDIO</tt> -<br>Autotune Port: <tt>/dev/icom</tt>; 9600 baud, 8-bits, no parity -<br>Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt> +Address: 127.127.36.<i>u</i> <br> +Reference ID: <tt>WWV</tt> or <tt>WWVH</tt> <br> +Driver ID: <tt>WWV_AUDIO</tt> <br> +Autotune Port: <tt>/dev/icom</tt>; 1200/9600 baud, 8-bits, no +parity <br> +Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt> <h4>Description</h4> This driver synchronizes the computer time using data encoded in -shortwave radio transmissions from NIST time/frequency stations WWV in -Ft. Collins, CO, and WWVH in Kauai, HI. Transmissions are made +shortwave radio transmissions from NIST time/frequency stations WWV +in Ft. Collins, CO, and WWVH in Kauai, HI. Transmissions are made continuously on 2.5, 5, 10, 15 and 20 MHz. An ordinary shortwave -receiver can be tuned manually to one of these frequencies or, in the -case of ICOM receivers, the receiver can be tuned automatically by the -driver as propagation conditions change throughout the day and night. -The performance of this driver when tracking one of the stations is -ordinarily better than 1 ms in time with frequency drift less than 0.5 -PPM when not tracking either station. +receiver can be tuned manually to one of these frequencies or, in +the case of ICOM receivers, the receiver can be tuned automatically +by the driver as propagation conditions change throughout the day +and night. The performance of this driver when tracking one of the +stations is ordinarily better than 1 ms in time with frequency +drift less than 0.5 PPM when not tracking either station. <p>The demodulation and decoding algorithms used by this driver are -based on a machine language program developed for the TAPR DSP93 DSP -unit, which uses the TI 320C25 DSP chip. The analysis, design and -performance of the program running on this unit is described in: Mills, -D.L. A precision radio clock for WWV transmissions. Electrical -Engineering Report 97-8-1, University of Delaware, August 1997, 25 pp. -Available from <a href=http://www.eecis.udel.edu/~mills/reports.htm> -www.eecis.udel.edu/~mills/reports.htm</a>. For use in this driver, the -original program was rebuilt in the C language and adapted to the NTP -driver interface. The algorithms have been modified somewhat to improve -performance under weak signal conditions and to provide an automatic -station identification feature. - -<p>This driver incorporates several features in common with other audio -drivers such as described in the <a href=driver7.htm>Radio CHU Audio -Demodulator/Decoder</a> and the <a href=driver6.htm>IRIG Audio -Decoder</a> pages. They include automatic gain control (AGC), selectable -audio codec port and signal monitoring capabilities. For a discussion of -these common features, as well as a guide to hookup, debugging and -monitoring, see the <a href=audio.htm>Reference Clock Audio Drivers</a> -page. - -<p>The WWV signal format is described in NIST Special Publication 432 -(Revised 1990). It consists of three elements, a 5-ms, 1000-Hz pulse, -which occurs at the beginning of each second, a 800-ms, 1000-Hz pulse, -which occurs at the beginning of each minute, and a pulse-width -modulated 100-Hz subcarrier for the data bits, one bit per second. The -WWVH format is identical, except that the 1000-Hz pulses are sent at -1200 Hz. Each minute encodes nine BCD digits for the time of century -plus seven bits for the daylight savings time (DST) indicator, leap -warning indicator and DUT1 correction. +based on a machine language program developed for the TAPR DSP93 +DSP unit, which uses the TI 320C25 DSP chip. The analysis, design +and performance of the program running on this unit is described +in: Mills, D.L. A precision radio clock for WWV transmissions. +Electrical Engineering Report 97-8-1, University of Delaware, +August 1997, 25 pp. Available from <a href= +"http://www.eecis.udel.edu/~mills/reports.htm"> +www.eecis.udel.edu/~mills/reports.htm</a>. For use in this driver, +the original program was rebuilt in the C language and adapted to +the NTP driver interface. The algorithms have been modified +somewhat to improve performance under weak signal conditions and to +provide an automatic station identification feature.</p> + +<p>This driver incorporates several features in common with other +audio drivers such as described in the <a href="driver7.htm">Radio +CHU Audio Demodulator/Decoder</a> and the <a href="driver6.htm"> +IRIG Audio Decoder</a> pages. They include automatic gain control +(AGC), selectable audio codec port and signal monitoring +capabilities. For a discussion of these common features, as well as +a guide to hookup, debugging and monitoring, see the <a href= +"audio.htm">Reference Clock Audio Drivers</a> page.</p> + +<p>The WWV signal format is described in NIST Special Publication +432 (Revised 1990). It consists of three elements, a 5-ms, 1000-Hz +pulse, which occurs at the beginning of each second, a 800-ms, +1000-Hz pulse, which occurs at the beginning of each minute, and a +pulse-width modulated 100-Hz subcarrier for the data bits, one bit +per second. The WWVH format is identical, except that the 1000-Hz +pulses are sent at 1200 Hz. Each minute encodes nine BCD digits for +the time of century plus seven bits for the daylight savings time +(DST) indicator, leap warning indicator and DUT1 correction.</p> <h4>Program Architecture</h4> -<p>As in the original program, the clock discipline is modelled as a -Markov process, with probabilistic state transitions corresponding to a -conventional clock and the probabilities of received decimal digits. The -result is a performance level which results in very high accuracy and -reliability, even under conditions when the minute beep of the signal, -normally its most prominent feature, can barely be detected by ear with -a shortwave receiver. - -<p>The analog audio signal from the shortwave radio is sampled at 8000 -Hz and converted to digital representation. The 1000/1200-Hz pulses and -100-Hz subcarrier are first separated using two IIR filters, a 600-Hz -bandpass filter centered on 1100 Hz and a 150-Hz lowpass filter. The -minute sync pulse is extracted using a 800-ms synchronous matched filter -and pulse grooming logic which discriminates between WWV and WWVH -signals and noise. The second sync pulse is extracted using a 5-ms FIR -matched filter and 8000-stage comb filter. - -<p>The phase of the 100-Hz subcarrier relative to the second sync pulse -is fixed at the transmitter; however, the audio highpass filter in most -radios affects the phase response at 100 Hz in unpredictable ways. The -driver adjusts for each radio using two 170-ms synchronous matched -filters. The I (in-phase) filter is used to demodulate the subcarrier -envelope, while the Q (quadrature-phase) filter is used in a tracking -loop to discipline the codec sample clock and thus the demodulator -phase. +<p>As in the original program, the clock discipline is modelled as +a Markov process, with probabilistic state transitions +corresponding to a conventional clock and the probabilities of +received decimal digits. The result is a performance level which +results in very high accuracy and reliability, even under +conditions when the minute beep of the signal, normally its most +prominent feature, can barely be detected by ear with a shortwave +receiver.</p> + +<p>The analog audio signal from the shortwave radio is sampled at +8000 Hz and converted to digital representation. The 1000/1200-Hz +pulses and 100-Hz subcarrier are first separated using two IIR +filters, a 600-Hz bandpass filter centered on 1100 Hz and a 150-Hz +lowpass filter. The minute sync pulse is extracted using a 800-ms +synchronous matched filter and pulse grooming logic which +discriminates between WWV and WWVH signals and noise. The second +sync pulse is extracted using a 5-ms FIR matched filter and +8000-stage comb filter.</p> + +<p>The phase of the 100-Hz subcarrier relative to the second sync +pulse is fixed at the transmitter; however, the audio highpass +filter in most radios affects the phase response at 100 Hz in +unpredictable ways. The driver adjusts for each radio using two +170-ms synchronous matched filters. The I (in-phase) filter is used +to demodulate the subcarrier envelope, while the Q +(quadrature-phase) filter is used in a tracking loop to discipline +the codec sample clock and thus the demodulator phase.</p> <p>The data bit probabilities are determined from the subcarrier envelope using a threshold-corrected slicer. The averaged envelope -amplitude 30 ms from the beginning of the second establishes the minimum -(noise floor) value, while the amplitude 200 ms from the beginning -establishes the maximum (signal peak) value. The slice level is midway -between these two values. The negative-going envelope transition at the -slice level establishes the length of the data pulse, which in turn -establish probabilities for binary zero (P0) or binary one (P1). The -values are established by linear interpolation between the pulse lengths -for P0 (300 ms) and P1 (500 ms) so that the sum is equal to one. If the -driver has not synchronized to the minute pulse, or if the data bit -amplitude, signal/noise ratio (SNR) or length are below thresholds, the -bit is considered invalid and all three probabilities are set to zero. - -<p>The difference between the P1 and P0 probabilities, or likelihood, -for each data bit is exponentially averaged in a set of 60 accumulators, -one for each second, to determine the semi-static miscellaneous bits, -such as DST indicator, leap second warning and DUT1 correction. In this -design, an average value larger than a positive threshold is interpreted -as a hit on one and a value smaller than a negative threshold as a hit -on zero. Values between the two thresholds, which can occur due to -signal fades or loss of signal, are interpreted as a miss, and result in -no change of indication. - -<p>The BCD digit in each digit position of the timecode is represented -as four data bits, all of which must be valid for the digit itself to be -considered valid. If so, the bits are correlated with the bits -corresponding to each of the valid decimal digits in this position. If -the digit is invalid, the correlated value for all digits in this -position is assumed zero. In either case, the values for all digits are -exponentially averaged in a likelihood vector associated with this -position. The digit associated with the maximum over all of the averaged -values then becomes the maximum likelihood selection for this position -and the ratio of the maximum over the next lower value becomes the -likelihood ratio. - -<p>The decoding matrix contains nine row vectors, one for each digit -position. Each row vector includes the maximum likelihood digit, -likelihood vector and other related data. The maximum likelihood digit -for each of the nine digit positions becomes the maximum likelihood time -of the century. A built-in transition function implements a conventional -clock with decimal digits that count the minutes, hours, days and years, -as corrected for leap seconds and leap years. The counting operation -also rotates the likelihood vector corresponding to each digit as it -advances. Thus, once the clock is set, each clock digit should -correspond to the maximum likelihood digit as transmitted. - -<p>Each row of the decoding matrix also includes a compare counter and -the difference (modulo the radix) between the current clock digit and -most recently determined maximum likelihood digit. If a digit likelihood -exceeds the decision level and the difference is constant for a number -of successive minutes in any row, the maximum likelihood digit replaces -the clock digit in that row. When this condition is true for all rows -and the second epoch has been reliably determined, the clock is set (or -verified if it has already been set) and delivers correct time to the -integral second. The fraction within the second is derived from the -logical master clock, which runs at 8000 Hz and drives all system timing -functions. - -<p>The logical master clock is derived from the audio codec clock. Its -frequency is disciplined by a frequency-lock loop (FLL) which operates -independently of the data recovery functions. At averaging intervals -determined by the measured jitter, the frequency error is calculated as -the difference between the most recent and the current second epoch -divided by the interval. The sample clock frequency is then corrected by -this amount using an exponential average. When first started, the -frequency averaging interval is eight seconds, in order to compensate -for intrinsic codec clock frequency offsets up to 125 PPM. Under most -conditions, the averaging interval doubles in stages from the initial -value to over 1000 seconds, which results in an ultimate frequency -precision of 0.125 PPM, or about 11 ms/day. +amplitude 30 ms from the beginning of the second establishes the +minimum (noise floor) value, while the amplitude 200 ms from the +beginning establishes the maximum (signal peak) value. The slice +level is midway between these two values. The negative-going +envelope transition at the slice level establishes the length of +the data pulse, which in turn establish probabilities for binary +zero (P0) or binary one (P1). The values are established by linear +interpolation between the pulse lengths for P0 (300 ms) and P1 (500 +ms) so that the sum is equal to one. If the driver has not +synchronized to the minute pulse, or if the data bit amplitude, +signal/noise ratio (SNR) or length are below thresholds, the bit is +considered invalid and all three probabilities are set to zero.</p> + +<p>The difference between the P1 and P0 probabilities, or +likelihood, for each data bit is exponentially averaged in a set of +60 accumulators, one for each second, to determine the semi-static +miscellaneous bits, such as DST indicator, leap second warning and +DUT1 correction. In this design, an average value larger than a +positive threshold is interpreted as a hit on one and a value +smaller than a negative threshold as a hit on zero. Values between +the two thresholds, which can occur due to signal fades or loss of +signal, are interpreted as a miss, and result in no change of +indication.</p> + +<p>The BCD digit in each digit position of the timecode is +represented as four data bits, all of which must be valid for the +digit itself to be considered valid. If so, the bits are correlated +with the bits corresponding to each of the valid decimal digits in +this position. If the digit is invalid, the correlated value for +all digits in this position is assumed zero. In either case, the +values for all digits are exponentially averaged in a likelihood +vector associated with this position. The digit associated with the +maximum over all of the averaged values then becomes the maximum +likelihood selection for this position and the ratio of the maximum +over the next lower value becomes the likelihood ratio.</p> + +<p>The decoding matrix contains nine row vectors, one for each +digit position. Each row vector includes the maximum likelihood +digit, likelihood vector and other related data. The maximum +likelihood digit for each of the nine digit positions becomes the +maximum likelihood time of the century. A built-in transition +function implements a conventional clock with decimal digits that +count the minutes, hours, days and years, as corrected for leap +seconds and leap years. The counting operation also rotates the +likelihood vector corresponding to each digit as it advances. Thus, +once the clock is set, each clock digit should correspond to the +maximum likelihood digit as transmitted.</p> + +<p>Each row of the decoding matrix also includes a compare counter +and the difference (modulo the radix) between the current clock +digit and most recently determined maximum likelihood digit. If a +digit likelihood exceeds the decision level and the difference is +constant for a number of successive minutes in any row, the maximum +likelihood digit replaces the clock digit in that row. When this +condition is true for all rows and the second epoch has been +reliably determined, the clock is set (or verified if it has +already been set) and delivers correct time to the integral second. +The fraction within the second is derived from the logical master +clock, which runs at 8000 Hz and drives all system timing +functions.</p> + +<p>The logical master clock is derived from the audio codec clock. +Its frequency is disciplined by a frequency-lock loop (FLL) which +operates independently of the data recovery functions. At averaging +intervals determined by the measured jitter, the frequency error is +calculated as the difference between the most recent and the +current second epoch divided by the interval. The sample clock +frequency is then corrected by this amount using an exponential +average. When first started, the frequency averaging interval is +eight seconds, in order to compensate for intrinsic codec clock +frequency offsets up to 125 PPM. Under most conditions, the +averaging interval doubles in stages from the initial value to over +1000 seconds, which results in an ultimate frequency precision of +0.125 PPM, or about 11 ms/day.</p> <p>It is important that the logical clock frequency is stable and -accurately determined, since in most applications the shortwave radio -will be tuned to a fixed frequency where WWV or WWVH signals are not -available throughout the day. In addition, in some parts of the US, -especially on the west coast, signals from either or both WWV and WWVH -may be available at different times or even at the same time. Since the -propagation times from either station are almost always different, each -station must be reliably identified before attempting to set the clock. - -<p>Station identification uses the 800-ms minute pulse transmitted by -each station. In the acquisition phase the entire minute is searched -using both the WWV and WWVH using matched filters and a pulse gate -discriminator similar to that found in radar acquisition and tracking -receivers. The peak amplitude found determines a range gate and window -where the next pulse is expected to be found. The minute is scanned -again to verify the peak is indeed in the window and with acceptable -amplitude, SNR and jitter. At this point the receiver begins to track -the second sync pulse and operate as above until the clock is set. - -<p>Once the minute is synchronized, the range gate is fixed and only -energy within the window is considered for the minute sync pulse. A -compare counter increments by one if the minute pulse has acceptable -amplitude, SNR and jitter and decrements otherwise. This is used as a -quality indicator and reported in the timecode and also for the autotune -function described below. +accurately determined, since in most applications the shortwave +radio will be tuned to a fixed frequency where WWV or WWVH signals +are not available throughout the day. In addition, in some parts of +the US, especially on the west coast, signals from either or both +WWV and WWVH may be available at different times or even at the +same time. Since the propagation times from either station are +almost always different, each station must be reliably identified +before attempting to set the clock.</p> + +<p>Station identification uses the 800-ms minute pulse transmitted +by each station. In the acquisition phase the entire minute is +searched using both the WWV and WWVH using matched filters and a +pulse gate discriminator similar to that found in radar acquisition +and tracking receivers. The peak amplitude found determines a range +gate and window where the next pulse is expected to be found. The +minute is scanned again to verify the peak is indeed in the window +and with acceptable amplitude, SNR and jitter. At this point the +receiver begins to track the second sync pulse and operate as above +until the clock is set.</p> + +<p>Once the minute is synchronized, the range gate is fixed and +only energy within the window is considered for the minute sync +pulse. A compare counter increments by one if the minute pulse has +acceptable amplitude, SNR and jitter and decrements otherwise. This +is used as a quality indicator and reported in the timecode and +also for the autotune function described below.</p> <h4>Performance</h4> -<p>It is the intent of the design that the accuracy and stability of the -indicated time be limited only by the characteristics of the propagation -medium. Conventional wisdom is that synchronization via the HF medium is -good only to a millisecond under the best propagation conditions. The -performance of the NTP daemon disciplined by the driver is clearly -better than this, even under marginal conditions. Ordinarily, with -marginal to good signals and a frequency averaging interval of 1024 s, -the frequency is stabilized within 0.1 PPM and the time within 125 <font -face=Symbol>m</font>s. The frequency stability characteristic is highly -important, since the clock may have to free-run for several hours before -reacquiring the WWV/H signal. - -<p>The expected accuracy over a typical day was determined using the -DSP93 and an oscilloscope and cesium oscillator calibrated with a GPS -receiver. With marginal signals and allowing 15 minutes for initial -synchronization and frequency compensation, the time accuracy determined -from the WWV/H second sync pulse was reliably within 125 <font -face=Symbol>m</font>s. In the particular DSP-93 used for program -development, the uncorrected CPU clock frequency offset was -45.8±0.1 PPM. Over the first hour after initial synchronization, -the clock frequency drifted about 1 PPM as the frequency averaging -interval increased to the maximum 1024 s. Once reaching the maximum, the -frequency wandered over the day up to 1 PPM, but it is not clear whether -this is due to the stability of the DSP-93 clock oscillator or the -changing height of the ionosphere. Once the frequency had stabilized and -after loss of the WWV/H signal, the frequency drift was less than 0.5 -PPM, which is equivalent to 1.8 ms/h or 43 ms/d. This resulted in a step -phase correction up to several milliseconds when the signal returned. - -<p>The measured propagation delay from the WWV transmitter at Boulder, -CO, to the receiver at Newark, DE, is 23.5±0.1 ms. This is -measured to the peak of the pulse after the second sync comb filter and -includes components due to the ionospheric propagation delay, nominally -8.9 ms, communications receiver delay and program delay. The propagation -delay can be expected to change about 0.2 ms over the day, as the result -of changing ionosphere height. The DSP93 program delay was measured at -5.5 ms, most of which is due to the 400-Hz bandpass filter and 5-ms -matched filter. Similar delays can be expected of this driver. +<p>It is the intent of the design that the accuracy and stability +of the indicated time be limited only by the characteristics of the +propagation medium. Conventional wisdom is that synchronization via +the HF medium is good only to a millisecond under the best +propagation conditions. The performance of the NTP daemon +disciplined by the driver is clearly better than this, even under +marginal conditions. Ordinarily, with marginal to good signals and +a frequency averaging interval of 1024 s, the frequency is +stabilized within 0.1 PPM and the time within 125 <font face= +"Symbol">m</font>s. The frequency stability characteristic is +highly important, since the clock may have to free-run for several +hours before reacquiring the WWV/H signal.</p> + +<p>The expected accuracy over a typical day was determined using +the DSP93 and an oscilloscope and cesium oscillator calibrated with +a GPS receiver. With marginal signals and allowing 15 minutes for +initial synchronization and frequency compensation, the time +accuracy determined from the WWV/H second sync pulse was reliably +within 125 <font face="Symbol">m</font>s. In the particular DSP-93 +used for program development, the uncorrected CPU clock frequency +offset was 45.8±0.1 PPM. Over the first hour after initial +synchronization, the clock frequency drifted about 1 PPM as the +frequency averaging interval increased to the maximum 1024 s. Once +reaching the maximum, the frequency wandered over the day up to 1 +PPM, but it is not clear whether this is due to the stability of +the DSP-93 clock oscillator or the changing height of the +ionosphere. Once the frequency had stabilized and after loss of the +WWV/H signal, the frequency drift was less than 0.5 PPM, which is +equivalent to 1.8 ms/h or 43 ms/d. This resulted in a step phase +correction up to several milliseconds when the signal returned.</p> + +<p>The measured propagation delay from the WWV transmitter at +Boulder, CO, to the receiver at Newark, DE, is 23.5±0.1 ms. +This is measured to the peak of the pulse after the second sync +comb filter and includes components due to the ionospheric +propagation delay, nominally 8.9 ms, communications receiver delay +and program delay. The propagation delay can be expected to change +about 0.2 ms over the day, as the result of changing ionosphere +height. The DSP93 program delay was measured at 5.5 ms, most of +which is due to the 400-Hz bandpass filter and 5-ms matched filter. +Similar delays can be expected of this driver.</p> <h4>Program Operation</h4> -The driver begins operation immediately upon startup. It first searches -for one or both of the stations WWV and WWVH and attempts to acquire -minute sync. This may take some fits and starts, as the driver expects -to see three consecutive minutes with good signals and low jitter. If -the autotune function is active, the driver will rotate over all five -frequencies and both WWV and WWVH stations until three good minutes are -found. - -<p>The driver then acquires second sync, which can take up to several -minutes, depending on signal quality. At the same time the driver -accumulates likelihood values for each of the nine digits of the clock, -plus the seven miscellaneous bits included in the WWV/H transmission -format. The minute units digit is decoded first and, when five -repetitions have compared correctly, the remaining eight digits are -decoded. When five repetitions of all nine digits have decoded -correctly, which normally takes 15 minutes with good signals and up to -an hour when buried in noise, and the second sync alarm has not been -raised for two minutes, the clock is set (or verified) and is selectable -to discipline the system clock. - -<p>As long as the clock is set or verified, the system clock offsets are -provided once each second to the reference clock interface, where they -are saved in a buffer. At the end of each minute, the buffer samples are -groomed by the median filter and trimmed-mean averaging functions. Using -these functions, the system clock can in principle be disciplined to a -much finer resolution than the 125-<font face=Symbol>m</font>s sample -interval would suggest, although the ultimate accuracy is probably -limited by propagation delay variations as the ionspheric height varies -throughout the day and night. - -<p>As long as signals are available, the clock frequency is disciplined -for use during times when the signals are unavailable. The algorithm -refines the frequency offset using increasingly longer averaging -intervals to 1024 s, where the precision is about 0.1 PPM. With good -signals, it takes well over two hours to reach this degree of precision; -however, it can take many more hours than this in case of marginal -signals. Once reaching the limit, the algorithm will follow frequency -variations due to temperature fluctuations and ionospheric height -variations. - -<p>It may happen as the hours progress around the clock that WWV and -WWVH signals may appear alone, together or not at all. When the driver -is first started, the NTP reference identifier appears as <tt>NONE</tt>. -When the driver has acquired one or both stations and mitigated which -one is best, it sets the station identifier in the timecode as described -below. In addition, the NTP reference identifier is set to the station -callsign. If the propagation delays has been properly set with the -<tt>fudge time1</tt> (WWV) and <tt>fudge time2</tt> (WWVH) commands in -the configuration file, handover from one station to the other will be -seamless. +The driver begins operation immediately upon startup. It first +searches for one or both of the stations WWV and WWVH and attempts +to acquire minute sync. This may take some fits and starts, as the +driver expects to see three consecutive minutes with good signals +and low jitter. If the autotune function is active, the driver will +rotate over all five frequencies and both WWV and WWVH stations +until three good minutes are found. + +<p>The driver then acquires second sync, which can take up to +several minutes, depending on signal quality. At the same time the +driver accumulates likelihood values for each of the nine digits of +the clock, plus the seven miscellaneous bits included in the WWV/H +transmission format. The minute units digit is decoded first and, +when five repetitions have compared correctly, the remaining eight +digits are decoded. When five repetitions of all nine digits have +decoded correctly, which normally takes 15 minutes with good +signals and up to an hour when buried in noise, and the second sync +alarm has not been raised for two minutes, the clock is set (or +verified) and is selectable to discipline the system clock.</p> + +<p>As long as the clock is set or verified, the system clock +offsets are provided once each second to the reference clock +interface, where they are saved in a buffer. At the end of each +minute, the buffer samples are groomed by the median filter and +trimmed-mean averaging functions. Using these functions, the system +clock can in principle be disciplined to a much finer resolution +than the 125-<font face="Symbol">m</font>s sample interval would +suggest, although the ultimate accuracy is probably limited by +propagation delay variations as the ionspheric height varies +throughout the day and night.</p> + +<p>As long as signals are available, the clock frequency is +disciplined for use during times when the signals are unavailable. +The algorithm refines the frequency offset using increasingly +longer averaging intervals to 1024 s, where the precision is about +0.1 PPM. With good signals, it takes well over two hours to reach +this degree of precision; however, it can take many more hours than +this in case of marginal signals. Once reaching the limit, the +algorithm will follow frequency variations due to temperature +fluctuations and ionospheric height variations.</p> + +<p>It may happen as the hours progress around the clock that WWV +and WWVH signals may appear alone, together or not at all. When the +driver is first started, the NTP reference identifier appears as +<tt>NONE</tt>. When the driver has acquired one or both stations +and mitigated which one is best, it sets the station identifier in +the timecode as described below. In addition, the NTP reference +identifier is set to the station callsign. If the propagation +delays has been properly set with the <tt>fudge time1</tt> (WWV) +and <tt>fudge time2</tt> (WWVH) commands in the configuration file, +handover from one station to the other will be seamless.</p> <p>Once the clock has been set for the first time, it will appear -reachable and selectable to discipline the system clock, even if the -broadcast signal fades to obscurity. A consequence of this design is -that, once the clock is set, the time and frequency are disciplined only -by the second sync pulse and the clock digits themselves are driven by -the clock state machine and ordinarily never changed. However, as long -as the clock is set correctly, it will continue to read correctly after -a period of signal loss, as long as it does not drift more than 500 ms -from the correct time. Assuming the clock frequency can be disciplined -within 1 PPM, the clock could coast without signals for some 5.8 days -without exceeding that limit. If for some reason this did happen, the -clock would be in the wrong second and would never resynchronize. To -protect against this most unlikely situation, if after four days with no -signals, the clock is considered unset and resumes the synchronization -procedure from the beginning. - -<p>To work well, the driver needs a communications receiver with good -audio response at 100 Hz. Most shortwave and communications receivers -roll off the audio response below 250 Hz, so this can be a problem, -especially with receivers using DSP technology, since DSP filters can -have very fast rolloff outside the passband. Some DSP transceivers, in -particular the ICOM 775, have a programmable low frequency cutoff which -can be set as low as 80 Hz. However, this particular radio has a strong -low frequency buzz at about 10 Hz which appears in the audio output and -can affect data recovery under marginal conditions. Although not tested, -it would seem very likely that a cheap shortwave receiver could function -just as well as an expensive communications receiver. +reachable and selectable to discipline the system clock, even if +the broadcast signal fades to obscurity. A consequence of this +design is that, once the clock is set, the time and frequency are +disciplined only by the second sync pulse and the clock digits +themselves are driven by the clock state machine and ordinarily +never changed. However, as long as the clock is set correctly, it +will continue to read correctly after a period of signal loss, as +long as it does not drift more than 500 ms from the correct time. +Assuming the clock frequency can be disciplined within 1 PPM, the +clock could coast without signals for some 5.8 days without +exceeding that limit. If for some reason this did happen, the clock +would be in the wrong second and would never resynchronize. To +protect against this most unlikely situation, if after four days +with no signals, the clock is considered unset and resumes the +synchronization procedure from the beginning.</p> + +<p>To work well, the driver needs a communications receiver with +good audio response at 100 Hz. Most shortwave and communications +receivers roll off the audio response below 250 Hz, so this can be +a problem, especially with receivers using DSP technology, since +DSP filters can have very fast rolloff outside the passband. Some +DSP transceivers, in particular the ICOM 775, have a programmable +low frequency cutoff which can be set as low as 80 Hz. However, +this particular radio has a strong low frequency buzz at about 10 +Hz which appears in the audio output and can affect data recovery +under marginal conditions. Although not tested, it would seem very +likely that a cheap shortwave receiver could function just as well +as an expensive communications receiver.</p> <h4>Autotune</h4> -<p>The driver includes provisions to automatically tune the radio in -response to changing radio propagation conditions throughout the day and -night. The radio interface is compatible with the ICOM CI-V standard, -which is a bidirectional serial bus operating at TTL levels. The bus can -be connected to a serial port using a level converter such as the CT-17. -The serial port speed is presently compiled in the program, but can be -changed in the driver source file. - -<p>Each ICOM radio is assigned a unique 8-bit ID select code, usually -expressed in hex format. To activate the CI-V interface, the -<tt>mode</tt> keyword of the <tt>server</tt> configuration command -specifies a nonzero select code in decimal format. A table of ID select -codes for the known ICOM radios is given below. A missing <tt>mode</tt> -keyword or a zero argument leaves the interface disabled. The driver -will attempt to open the device <tt>/dev/icom</tt> and, if successful -will activate the autotune function and tune the radio to each operating -frequency in turn while attempting to acquire minute sync from either -WWV or WWVH. However, the driver is liberal in what it assumes of the -configuration. If the <tt>/dev/icom</tt> link is not present or the open -fails or the CI-V bus or radio is inoperative, the driver quietly gives -up with no harm done. - -<p>Once acquiring minute sync, the driver operates as described above to -set the clock. However, during seconds 59, 0 and 1 of each minute it -tunes the radio to one of the five broadcast frequencies to measure the -sync pulse and data pulse amplitudes and SNR and update the compare -counter. Each of the five frequencies are probed in a five-minute -rotation to build a database of current propagation conditions for all -signals that can be heard at the time. At the end of each rotation, a -mitigation procedure scans the database and retunes the radio to the -best frequency and station found. For this to work well, the radio -should be set for a fast AGC recovery time. This is most important while -tracking a strong signal, which is normally the case, and then probing -another frequency, which may have much weaker signals. - -<p>Reception conditions for each frequency and station are evaluated -according to a metric which considers the minute sync pulse amplitude, -SNR and jitter, as well as, the data pulse amplitude and SNR. The minute -pulse is evaluated at second 0, while the data pulses are evaluated at -seconds 59 and 1. The results are summarized in a scoreboard of three -bits +<p>The driver includes provisions to automatically tune the radio +in response to changing radio propagation conditions throughout the +day and night. The radio interface is compatible with the ICOM CI-V +standard, which is a bidirectional serial bus operating at TTL +levels. The bus can be connected to a serial port using a level +converter such as the CT-17. The serial port speed is presently +compiled in the program, but can be changed in the driver source +file.</p> + +<p>Each ICOM radio is assigned a unique 8-bit ID select code, +usually expressed in hex format. To activate the CI-V interface, +the <tt>mode</tt> keyword of the <tt>server</tt> configuration +command specifies a nonzero select code in decimal format. A table +of ID select codes for the known ICOM radios is given below. Since +all ICOM select codes are less than 128, the high order bit of the +code is used by the driver to specify the baud rate. If this bit is +not set, the rate is 9600 bps for the newer radios; if set, the +rate is 1200 bps for the older radios. A missing <tt>mode</tt> +keyword or a zero argument leaves the interface disabled.</p> + +<p>If specified, the driver will attempt to open the device <tt> +/dev/icom</tt> and, if successful will activate the autotune +function and tune the radio to each operating frequency in turn +while attempting to acquire minute sync from either WWV or WWVH. +However, the driver is liberal in what it assumes of the +configuration. If the <tt>/dev/icom</tt> link is not present or the +open fails or the CI-V bus or radio is inoperative, the driver +quietly gives up with no harm done.</p> + +<p>Once acquiring minute sync, the driver operates as described +above to set the clock. However, during seconds 59, 0 and 1 of each +minute it tunes the radio to one of the five broadcast frequencies +to measure the sync pulse and data pulse amplitudes and SNR and +update the compare counter. Each of the five frequencies are probed +in a five-minute rotation to build a database of current +propagation conditions for all signals that can be heard at the +time. At the end of each rotation, a mitigation procedure scans the +database and retunes the radio to the best frequency and station +found. For this to work well, the radio should be set for a fast +AGC recovery time. This is most important while tracking a strong +signal, which is normally the case, and then probing another +frequency, which may have much weaker signals.</p> + +<p>Reception conditions for each frequency and station are +evaluated according to a metric which considers the minute sync +pulse amplitude, SNR and jitter, as well as, the data pulse +amplitude and SNR. The minute pulse is evaluated at second 0, while +the data pulses are evaluated at seconds 59 and 1. The results are +summarized in a scoreboard of three bits</p> <dl> +<dt><tt>0x0001</tt></dt> -<p><dt><tt>0x0001</tt> -<dd>Jitter exceeded. The difference in epoches between the last minute -sync pulse and the current one exceeds 50 ms (400 samples).</dd> +<dd>Jitter exceeded. The difference in epoches between the last +minute sync pulse and the current one exceeds 50 ms (400 +samples).</dd> -<dt><tt>0x0002</tt> -<dd>Minute pulse error. For the minute sync pulse in second 0, either -the amplitude or SNR is below threshold (2000 and 20 dB, -respectively).</dd> +<dt><tt>0x0002</tt></dt> -<dt><tt>0x0004</tt> -<dd>Minute pulse error. For both of the data pulses in seocnds 59 and 1, -either the amplitude or SNR is below threshold (1000 and 10 dB, +<dd>Minute pulse error. For the minute sync pulse in second 0, +either the amplitude or SNR is below threshold (2000 and 20 dB, respectively).</dd> +<dt><tt>0x0004</tt></dt> + +<dd>Minute pulse error. For both of the data pulses in seocnds 59 +and 1, either the amplitude or SNR is below threshold (1000 and 10 +dB, respectively).</dd> </dl> <p>If none of the scoreboard bits are set, the compare counter is -increased by one to a maximum of six. If any bits are set, the counter -is decreased by one to a minimum of zero. At the end of each minute, the -frequency and station with the maximum compare count is chosen, with -ties going to the highest frequency. +increased by one to a maximum of six. If any bits are set, the +counter is decreased by one to a minimum of zero. At the end of +each minute, the frequency and station with the maximum compare +count is chosen, with ties going to the highest frequency.</p> <h4>Diagnostics</h4> -<p>The autotune process produces diagnostic information along with the -timecode. This is very useful for evaluating the performance of the -algorithm, as well as radio propagation conditions in general. The -message is produced once each minute for each frequency in turn after -minute sync has been acquired. +<p>The autotune process produces diagnostic information along with +the timecode. This is very useful for evaluating the performance of +the algorithm, as well as radio propagation conditions in general. +The message is produced once each minute for each frequency in turn +after minute sync has been acquired.</p> -<p><tt>wwv5 port agc wwv wwvh</tt> +<p><tt>wwv5 port agc wwv wwvh</tt></p> -<p>where <tt>port</tt> and <tt>agc</tt> are the audio port and gain, -respectively, for this frequency and <tt>wwv</tt> and <tt>wwvh</tt> are -two sets of fields, one each for WWV and WWVH. Each of the two fields -has the format +<p>where <tt>port</tt> and <tt>agc</tt> are the audio port and +gain, respectively, for this frequency and <tt>wwv</tt> and <tt> +wwvh</tt> are two sets of fields, one each for WWV and WWVH. Each +of the two fields has the format</p> -<p><tt>ident score comp sync/snr/jitr</tt> +<p><tt>ident score comp sync/snr/jitr</tt></p> <p>where <tt>ident</tt>encodes the station (<tt>C</tt> for WWV, -<tt>H</tt> for WWVH) and frequency (2, 5, 10, 15 and 20), <tt>score</tt> -is the scoreboard described above, <tt>comp</tt> is the compare counter, -<tt>sync</tt> is the minute sync pulse amplitude, <tt>snr</tt> the SNR -of the pulse and <tt>jitr</tt> is the sample difference between the -current epoch and the last epoch. An example is: +<tt>H</tt> for WWVH) and frequency (2, 5, 10, 15 and 20), <tt> +score</tt> is the scoreboard described above, <tt>comp</tt> is the +compare counter, <tt>sync</tt> is the minute sync pulse amplitude, +<tt>snr</tt> the SNR of the pulse and <tt>jitr</tt> is the sample +difference between the current epoch and the last epoch. An example +is:</p> -<p><tt>wwv5 2 111 C20 0100 6 8348/30.0/-3 H20 0203 0 22/-12.4/8846</tt> +<p><tt>wwv5 2 111 C20 0100 6 8348/30.0/-3 H20 0203 0 +22/-12.4/8846</tt></p> <p>Here the radio is tuned to 20 MHz and the line-in port AGC is -currently 111 at that frequency. The message contains a report for WWV -(<tt>C20</tt>) and WWVH (<tt>H20</tt>). The WWV report scoreboard is -0100 and the compare count is 6, which suggests very good reception -conditions, and the minute sync amplitude and SNR are well above -thresholds (2000 and 20 dB, respectively). Probably the most sensitive -indicator of reception quality is the jitter, -3 samples, which is well -below threshold (50 ms or 400 samples). While the message shows solid -reception conditions from WWV, this is not the case for WWVH. Both the -minute sync amplitude and SNR are below thresholds and the jitter is -above threshold. - -<p>A sequence of five messages, one for each minute, might appear as -follows: - -<p><pre>wwv5 2 95 C2 0107 0 164/7.2/8100 H2 0207 0 80/-5.5/7754 +currently 111 at that frequency. The message contains a report for +WWV (<tt>C20</tt>) and WWVH (<tt>H20</tt>). The WWV report +scoreboard is 0100 and the compare count is 6, which suggests very +good reception conditions, and the minute sync amplitude and SNR +are well above thresholds (2000 and 20 dB, respectively). Probably +the most sensitive indicator of reception quality is the jitter, -3 +samples, which is well below threshold (50 ms or 400 samples). +While the message shows solid reception conditions from WWV, this +is not the case for WWVH. Both the minute sync amplitude and SNR +are below thresholds and the jitter is above threshold.</p> + +<p>A sequence of five messages, one for each minute, might appear +as follows:</p> + +<pre> +wwv5 2 95 C2 0107 0 164/7.2/8100 H2 0207 0 80/-5.5/7754 wwv5 2 99 C5 0104 0 3995/21.8/395 H5 0207 0 27/-9.3/18826 wwv5 2 239 C10 0105 0 9994/30.0/2663 H10 0207 0 54/-16.1/-529 wwv5 2 155 C15 0103 3 3300/17.8/-1962 H15 0203 0 236/17.0/4873 -wwv5 2 111 C20 0100 6 8348/30.0/-3 H20 0203 0 22/-12.4/8846</pre> +wwv5 2 111 C20 0100 6 8348/30.0/-3 H20 0203 0 22/-12.4/8846 +</pre> -<p>Clearly, the only frequencies that are available are 15 MHz and 20 -MHz and propagation may be failing for 15 MHz. However, minute sync -pulses are being heard on 5 and 10 MHz, even though the data pulses are -not. This is typical of late afternoon when the maximum usable frequency -(MUF) is falling and the ionospheric loss at the lower frequencies is -beginning to decrease. +<p>Clearly, the only frequencies that are available are 15 MHz and +20 MHz and propagation may be failing for 15 MHz. However, minute +sync pulses are being heard on 5 and 10 MHz, even though the data +pulses are not. This is typical of late afternoon when the maximum +usable frequency (MUF) is falling and the ionospheric loss at the +lower frequencies is beginning to decrease.</p> <h4>Debugging Aids</h4> <p>The most convenient way to track the driver status is using the -<tt>ntpq</tt> program and the <tt>clockvar</tt> command. This displays -the last determined timecode and related status and error counters, even -when the driver is not discipline the system clock. If the debugging -trace feature (<tt>-d</tt> on the <tt>ntpd</tt> command line)is enabled, -the driver produces detailed status messages as it operates. If the -<tt>fudge flag 4</tt> is set, these messages are written to the -<tt>clockstats</tt> file. All messages produced by this driver have the -prefix <tt>chu</tt> for convenient filtering with the Unix <tt>grep</tt> -command. +<tt>ntpq</tt> program and the <tt>clockvar</tt> command. This +displays the last determined timecode and related status and error +counters, even when the driver is not discipline the system clock. +If the debugging trace feature (<tt>-d</tt> on the <tt>ntpd</tt> +command line)is enabled, the driver produces detailed status +messages as it operates. If the <tt>fudge flag 4</tt> is set, these +messages are written to the <tt>clockstats</tt> file. All messages +produced by this driver have the prefix <tt>chu</tt> for convenient +filtering with the Unix <tt>grep</tt> command.</p> <p>In the following descriptions the units of amplitude, phase, probability and likelihood are normalized to the range 0-6000 for -convenience. In addition, the signal/noise ratio (SNR) and likelihood -ratio are measured in decibels and the words with bit fields are in -hex. Most messages begin with a leader in the following format: +convenience. In addition, the signal/noise ratio (SNR) and +likelihood ratio are measured in decibels and the words with bit +fields are in hex. Most messages begin with a leader in the +following format:</p> -<p><tt>wwvn ss stat sigl</tt> +<p><tt>wwvn ss stat sigl</tt></p> -<p>where <tt>wwvn</tt> is the message code, <tt>ss</tt> the second of -minute, <tt>stat</tt> the driver status word and <tt>sigl</tt> the -second sync pulse amplitude. A full explanation of the status bits is -contained in the driver source listing; however, the following are the -most useful for debugging. +<p>where <tt>wwvn</tt> is the message code, <tt>ss</tt> the second +of minute, <tt>stat</tt> the driver status word and <tt>sigl</tt> +the second sync pulse amplitude. A full explanation of the status +bits is contained in the driver source listing; however, the +following are the most useful for debugging.</p> <dl> +<dt><tt>0x0001</tt></dt> -<p><dt><tt>0x0001</tt> <dd>Minute sync. Set when the decoder has identified a station and acquired the minute sync pulse.</dd> -<p><dt><tt>0x0002</tt> -<dd>Second sync. Set when the decoder has acquired the second sync pulse -and within 125 <font face=Symbol>m</font>s of the correct phase.</dd> -<p><dt><tt>0x0004</tt> -<dd>Minute unit sync. Set when the decoder has reliably determined the -unit digit of the minute.</dd> +<dt><tt>0x0002</tt></dt> + +<dd>Second sync. Set when the decoder has acquired the second sync +pulse and within 125 <font face="Symbol">m</font>s of the correct +phase.</dd> -<p><dt><tt>0x0008</tt> -<dd>Clock set. Set when the decoder has reliably determined all nine -digits of the timecode and is selectable to discipline the system -clock.</dd> +<dt><tt>0x0004</tt></dt> +<dd>Minute unit sync. Set when the decoder has reliably determined +the unit digit of the minute.</dd> + +<dt><tt>0x0008</tt></dt> + +<dd>Clock set. Set when the decoder has reliably determined all +nine digits of the timecode and is selectable to discipline the +system clock.</dd> </dl> -<p>With debugging enabled the driver produces messages in the following -formats: +<p>With debugging enabled the driver produces messages in the +following formats:</p> -<p>Format <tt>wwv8</tt> messages are produced once per minute by the WWV -and WWVH station processes before minute sync has been acquired. They -show the progress of identifying and tracking the minute pulse of each -station. +<p>Format <tt>wwv8</tt> messages are produced once per minute by +the WWV and WWVH station processes before minute sync has been +acquired. They show the progress of identifying and tracking the +minute pulse of each station.</p> -<p><tt>wwv8 port agc ident comp ampl snr epoch jitr offs</tt> +<p><tt>wwv8 port agc ident comp ampl snr epoch jitr offs</tt></p> -<p>where <tt>port</tt> and <tt>agc</tt> are the audio port and gain, -respectively. The <tt>ident</tt>encodes the station (<tt>C</tt> for WWV, -<tt>H</tt> for WWVH) and frequency (2, 5, 10, 15 and 20). For the -encoded frequency, <tt>comp</tt> is the compare counter, <tt>ampl</tt> -the pulse amplitude, <tt>snr</tt> the SNR, <tt>epoch</tt> the sample -number of the minute pulse in the minute, <tt>jitr</tt> the change since -the last <tt>epoch</tt> and <tt>offs</tt> the minute pulse offset -relative to the second pulse. An example is: +<p>where <tt>port</tt> and <tt>agc</tt> are the audio port and +gain, respectively. The <tt>ident</tt>encodes the station +(<tt>C</tt> for WWV, <tt>H</tt> for WWVH) and frequency (2, 5, 10, +15 and 20). For the encoded frequency, <tt>comp</tt> is the compare +counter, <tt>ampl</tt> the pulse amplitude, <tt>snr</tt> the SNR, +<tt>epoch</tt> the sample number of the minute pulse in the minute, +<tt>jitr</tt> the change since the last <tt>epoch</tt> and <tt> +offs</tt> the minute pulse offset relative to the second pulse. An +example is:</p> -<p><tt> wwv8 2 127 C15 2 9247 30.0 18843 -1 1</tt> -<br><tt>wwv8 2 127 H15 0 134 -2.9 19016 193 174</tt> +<p><tt>wwv8 2 127 C15 2 9247 30.0 18843 -1 1</tt><br> +<tt>wwv8 2 127 H15 0 134 -2.9 19016 193 174</tt></p> <p>Here the radio is tuned to 15 MHz and the line-in port AGC is -currently 127 at that frequency. The driver has not yet acquired minute -sync, WWV has been heard for at least two minutes, and WWVH is in the -noise. The WWV minute pulse amplitude and SNR are well above the -threshold (2000 and 6 dB, respectively) and the minute epoch has been -determined -1 sample relative to the last one and 1 sample relative to -the second sync pulse. The compare counter has incrmented to two; when -it gets to three, minute sync has been acquired. +currently 127 at that frequency. The driver has not yet acquired +minute sync, WWV has been heard for at least two minutes, and WWVH +is in the noise. The WWV minute pulse amplitude and SNR are well +above the threshold (2000 and 6 dB, respectively) and the minute +epoch has been determined -1 sample relative to the last one and 1 +sample relative to the second sync pulse. The compare counter has +incrmented to two; when it gets to three, minute sync has been +acquired.</p> + +<p>Format <tt>wwv3</tt> messages are produced after minute sync has +been acquired and until the seconds unit digit is determined. They +show the results of decoding each bit of the transmitted +timecode.</p> + +<p><tt>wwv3 ss stat sigl ampl phas snr prob like</tt></p> -<p>Format <tt>wwv3</tt> messages are produced after minute sync has been -acquired and until the seconds unit digit is determined. They show the -results of decoding each bit of the transmitted timecode. +<p>where <tt>ss</tt>, <tt>stat</tt> and <tt>sigl</tt> are as above, +<tt>ampl</tt> is the subcarrier amplitude, <tt>phas</tt> the +subcarrier phase, <tt>snr</tt> the subcarrier SNR, <tt>prob</tt> +the bit probability and <tt>like</tt> the bit likelihood. An +example is:</p> -<p><tt>wwv3 ss stat sigl ampl phas snr prob like</tt> +<p><tt>wwv3 28 0123 4122 4286 0 24.8 -5545 -1735</tt></p> -<p>where <tt>ss</tt>, <tt>stat</tt> and <tt>sigl</tt> are as above, -<tt>ampl</tt> is the subcarrier amplitude, <tt>phas</tt> the subcarrier -phase, <tt>snr</tt> the subcarrier SNR, <tt>prob</tt> the bit -probability and <tt>like</tt> the bit likelihood. An example is: - -<p><tt>wwv3 28 0123 4122 4286 0 24.8 -5545 -1735</tt> - -<p>Here the driver has acquired minute and second sync, but has not yet -determined the seconds unit digit. However, it has just decoded bit 28 -of the minute. The results show the second sync pulse amplitude well -over the threshold (500), subcarrier amplitude well above the threshold -(1000), good subcarrier tracking phase and SNR well above the threshold -(10 dB). The bit is almost certainly a zero and the likelihood of a zero -in this second is very high. -<p>Format <tt>wwv4</tt> messages are produced for each of the nine BCD -timecode digits until the clock has been set or verified. They show the -results of decoding each digit of the transmitted timecode. -<p><tt>wwv4 ss stat sigl radx ckdig mldig diff cnt like snr</tt> +<p>Here the driver has acquired minute and second sync, but has not +yet determined the seconds unit digit. However, it has just decoded +bit 28 of the minute. The results show the second sync pulse +amplitude well over the threshold (500), subcarrier amplitude well +above the threshold (1000), good subcarrier tracking phase and SNR +well above the threshold (10 dB). The bit is almost certainly a +zero and the likelihood of a zero in this second is very high.</p> + +<p>Format <tt>wwv4</tt> messages are produced for each of the nine +BCD timecode digits until the clock has been set or verified. They +show the results of decoding each digit of the transmitted +timecode.</p> + +<p><tt>wwv4 ss stat sigl radx ckdig mldig diff cnt like +snr</tt></p> <p>where <tt>ss</tt>, <tt>stat</tt> and <tt>sigl</tt> are as above, <tt>radx</tt> is the digit radix (3, 4, 6, 10), <tt>ckdig</tt> the current clock digit, <tt>mldig</tt> the maximum likelihood digit, -<tt>diff</tt> the difference between these two digits modulo the radix, -<tt>cnt</tt> the compare counter, <tt>like</tt> the digit likelihood and -<tt>snr</tt> the likelihood ratio. An example is: +<tt>diff</tt> the difference between these two digits modulo the +radix, <tt>cnt</tt> the compare counter, <tt>like</tt> the digit +likelihood and <tt>snr</tt> the likelihood ratio. An example +is:</p> -<p><tt>wwv4 8 010f 5772 10 9 9 0 6 4615 6.1</tt> +<p><tt>wwv4 8 010f 5772 10 9 9 0 6 4615 6.1</tt></p> -<p>Here the driver has previousl set or verified the clock. It has just -decoded the digit preceding second 8 of the minute. The digit radix is -10, the current clock and maximum likelihood digits are both 9, the -likelihood is well above the threshold (1000) and the likelihood -function well above threshold (3.0 dB). Short of a hugely unlikely -probability conspiracy, the clock digit is most certainly a 9. +<p>Here the driver has previousl set or verified the clock. It has +just decoded the digit preceding second 8 of the minute. The digit +radix is 10, the current clock and maximum likelihood digits are +both 9, the likelihood is well above the threshold (1000) and the +likelihood function well above threshold (3.0 dB). Short of a +hugely unlikely probability conspiracy, the clock digit is most +certainly a 9.</p> -<p>Format <tt>wwv2</tt> messages are produced at each master oscillator -frequency update, which starts at 8 s, but eventually climbs to 1024 s. -They show the progress of the algorithm as it refines the frequency -measurement to a precision of 0.1 PPM. +<p>Format <tt>wwv2</tt> messages are produced at each master +oscillator frequency update, which starts at 8 s, but eventually +climbs to 1024 s. They show the progress of the algorithm as it +refines the frequency measurement to a precision of 0.1 PPM.</p> -<p><tt>wwv2 ss stat sigl avint avcnt avinc jitr delt freq</tt> +<p><tt>wwv2 ss stat sigl avint avcnt avinc jitr delt freq</tt></p> <p>where <tt>ss</tt>, <tt>stat</tt> and <tt>sigl</tt> are as above, -<tt>avint</tt> is the averaging interval, <tt>avcnt</tt> the averaging -interval counter, <tt>avinc</tt> the interval increment, <tt>jitr</tt> -the sample change between the beginning and end of the interval, -<tt>delt</tt> the computed frequency change and <tt>freq</tt> the -current frequency (PPM). An example is: +<tt>avint</tt> is the averaging interval, <tt>avcnt</tt> the +averaging interval counter, <tt>avinc</tt> the interval increment, +<tt>jitr</tt> the sample change between the beginning and end of +the interval, <tt>delt</tt> the computed frequency change and <tt> +freq</tt> the current frequency (PPM). An example is:</p> -<p><tt>wwv2 22 030f 5795 256 256 4 0 0.0 66.7</tt> +<p><tt>wwv2 22 030f 5795 256 256 4 0 0.0 66.7</tt></p> <p>Here the driver has acquired minute and second sync and set the -clock. The averaging interval has increased to 256 s on the way to 1024 -s, has stayed at that interval for 4 averaging intervals, has measured -no change in frequency and the current frequency is 66.7 PPM. +clock. The averaging interval has increased to 256 s on the way to +1024 s, has stayed at that interval for 4 averaging intervals, has +measured no change in frequency and the current frequency is 66.7 +PPM.</p> <p>If the CI-V interface for ICOM radios is active, a debug level -greater than 1 will produce a trace of the CI-V command and response -messages. Interpretation of these messages requires knowledge of the -CI-V protocol, which is beyond the scope of this document. +greater than 1 will produce a trace of the CI-V command and +response messages. Interpretation of these messages requires +knowledge of the CI-V protocol, which is beyond the scope of this +document.</p> <h4>Monitor Data</h4> -When enabled by the <tt>filegen</tt> facility, every received timecode -is written to the <tt>clockstats</tt> file in the following format: +When enabled by the <tt>filegen</tt> facility, every received +timecode is written to the <tt>clockstats</tt> file in the +following format: <pre> sq yy ddd hh:mm:ss.fff ld du lset agc stn rfrq errs freq cons @@ -599,130 +652,151 @@ is written to the <tt>clockstats</tt> file in the following format: avgt averaging time </pre> -The fields beginning with <tt>year</tt> and extending through -<tt>dut</tt> are decoded from the received data and are in fixed-length +The fields beginning with <tt>year</tt> and extending through <tt> +dut</tt> are decoded from the received data and are in fixed-length format. The <tt>agc</tt> and <tt>lset</tt> fields, as well as the -following driver-dependent fields, are in variable-length format. +following driver-dependent fields, are in variable-length format. <dl> +<dt><tt>s</tt></dt> + +<dd>The sync indicator is initially <tt>?</tt> before the clock is +set, but turns to space when all nine digits of the timecode are +correctly set.</dd> -<dt><tt>s</tt> -<dd>The sync indicator is initially <tt>?</tt> before the clock is set, -but turns to space when all nine digits of the timecode are correctly -set.</dd> +<dt><tt>q</tt></dt> + +<dd>The quality character is a four-bit hexadecimal code showing +which alarms have been raised. Each bit is associated with a +specific alarm condition according to the following: -<dt><tt>q</tt> -<dd>The quality character is a four-bit hexadecimal code showing which -alarms have been raised. Each bit is associated with a specific alarm -condition according to the following: <dl> +<dt><tt>0x8</tt></dt> + +<dd>Sync alarm. The decoder may not be in correct second or minute +phase relative to the transmitter.</dd> -<dt><tt>0x8</tt> -<dd>Sync alarm. The decoder may not be in correct second or minute phase -relative to the transmitter.</dd> +<dt><tt>0x4</tt></dt> -<dt><tt>0x4</tt> <dd>Error alarm. More than 30 data bit errors occurred in the last minute.</dd> -<dt><tt>0x2</tt> -<dd>Symbol alarm. The probability of correct decoding for a digit or -miscellaneous bit has fallen below the threshold.</dd> +<dt><tt>0x2</tt></dt> -<dt><tt>0x1</tt> -<dd>Decoding alarm. A maximum likelihood digit fails to agree with the -current associated clock digit.</dd> +<dd>Symbol alarm. The probability of correct decoding for a digit +or miscellaneous bit has fallen below the threshold.</dd> +<dt><tt>0x1</tt></dt> + +<dd>Decoding alarm. A maximum likelihood digit fails to agree with +the current associated clock digit.</dd> </dl> -It is important to note that one or more of the above alarms does not -necessarily indicate a clock error, but only that the decoder has -detected a condition that may in future result in an error. +It is important to note that one or more of the above alarms does +not necessarily indicate a clock error, but only that the decoder +has detected a condition that may in future result in an +error.</dd> + +<dt><tt>yyyy ddd hh:mm:ss.fff</tt></dt> -<dt><tt>yyyy ddd hh:mm:ss.fff</tt></tt> -<dd>The timecode format itself is self explanatory. Since the driver -latches the on-time epoch directly from the second sync pulse, the -fraction <tt>fff</tt>is always zero. Although the transmitted timecode -includes only the year of century, the Gregorian year is augmented 2000 -if the indicated year is less than 72 and 1900 otherwise.</dd> +<dd>The timecode format itself is self explanatory. Since the +driver latches the on-time epoch directly from the second sync +pulse, the fraction <tt>fff</tt>is always zero. Although the +transmitted timecode includes only the year of century, the +Gregorian year is augmented 2000 if the indicated year is less than +72 and 1900 otherwise.</dd> -<dt><tt>l</tt> -<dd>The leap second warning is normally space, but changes to <tt>L</tt> -if a leap second is to occur at the end of the month of June or -December.</dd> +<dt><tt>l</tt></dt> + +<dd>The leap second warning is normally space, but changes to <tt> +L</tt> if a leap second is to occur at the end of the month of June +or December.</dd> + +<dt><tt>d</tt></dt> -<dt><tt>d</tt> <dd>The DST state is <tt>S</tt> or <tt>D</tt> when standard time or -daylight time is in effect, respectively. The state is <tt>I</tt> or -<tt>O</tt> when daylight time is about to go into effect or out of -effect, respectively.</dd> -<dt><tt>dut</tt> -<dd>The DUT sign and magnitude shows the current UT1 offset relative to -the displayed UTC time, in deciseconds.</dd> - -<dt><tt>lset</tt> -<dd>Before the clock is set, the interval since last set is the number -of minutes since the driver was started; after the clock is set, this -is number of minutes since the time was last verified relative to the -broadcast signal.</dd> - -<dt><tt>agc</tt> -<dd>The audio gain shows the current codec gain setting in the range 0 -to 255. Ordinarily, the receiver audio gain control or IRIG level -control should be set for a value midway in this range. - -<dt><tt>ident</tt> +daylight time is in effect, respectively. The state is <tt>I</tt> +or <tt>O</tt> when daylight time is about to go into effect or out +of effect, respectively.</dd> + +<dt><tt>dut</tt></dt> + +<dd>The DUT sign and magnitude shows the current UT1 offset +relative to the displayed UTC time, in deciseconds.</dd> + +<dt><tt>lset</tt></dt> + +<dd>Before the clock is set, the interval since last set is the +number of minutes since the driver was started; after the clock is +set, this is number of minutes since the time was last verified +relative to the broadcast signal.</dd> + +<dt><tt>agc</tt></dt> + +<dd>The audio gain shows the current codec gain setting in the +range 0 to 255. Ordinarily, the receiver audio gain control or IRIG +level control should be set for a value midway in this range.</dd> + +<dt><tt>ident</tt></dt> + <dd>The station identifier shows the station, <tt>C</tt> for WWV or -<tt>H</tt> for WWVH, and frequency being tracked. If neither station is -heard on any frequency, the station identifier shows <tt>X</tt>.</dd> - -<dt><tt>comp</tt> -<dd>The minute sync compare counter is useful to determine the quality -of the minute sync signal and can range from 0 (no signal) to 5 -(best).</dd> - -<dt><tt>errs</tt> -<dd>The bit error counter is useful to determine the quality of the data -signal received in the most recent minute. It is normal to drop a couple -of data bits under good signal conditions and increasing numbers as -conditions worsen. While the decoder performs moderately well even with -half the bits are in error in any minute, usually by that point the sync -signals are lost and the decoder reverts to free-run anyway.</dd> - -<dt><tt>freq</tt> -<dd>The frequency offset is the current estimate of the codec frequency -offset to within 0.1 PPM. This may wander a bit over the day due to -local temperature fluctuations and propagation conditions.</dd> - -<dt><tt>avgt</tt> +<tt>H</tt> for WWVH, and frequency being tracked. If neither +station is heard on any frequency, the station identifier shows +<tt>X</tt>.</dd> + +<dt><tt>comp</tt></dt> + +<dd>The minute sync compare counter is useful to determine the +quality of the minute sync signal and can range from 0 (no signal) +to 5 (best).</dd> + +<dt><tt>errs</tt></dt> + +<dd>The bit error counter is useful to determine the quality of the +data signal received in the most recent minute. It is normal to +drop a couple of data bits under good signal conditions and +increasing numbers as conditions worsen. While the decoder performs +moderately well even with half the bits are in error in any minute, +usually by that point the sync signals are lost and the decoder +reverts to free-run anyway.</dd> + +<dt><tt>freq</tt></dt> + +<dd>The frequency offset is the current estimate of the codec +frequency offset to within 0.1 PPM. This may wander a bit over the +day due to local temperature fluctuations and propagation +conditions.</dd> + +<dt><tt>avgt</tt></dt> + <dd>The averaging time is the interval between frequency updates in powers of two to a maximum of 1024 s. Attainment of the maximum -indicates the driver is operating at the best possible resolution in -time and frequency.</dd> - +indicates the driver is operating at the best possible resolution +in time and frequency.</dd> </dl> -<p>An example timecode is: +<p>An example timecode is:</p> -<p><tt> 0 2000 006 22:36:00.000 S +3 1 115 C20 6 5 66.4 1024</tt> +<p><tt>0 2000 006 22:36:00.000 S +3 1 115 C20 6 5 66.4 +1024</tt></p> -<p>Here the clock has been set and no alarms are raised. The year, day -and time are displayed along with no leap warning, standard time and DUT -+0.3 s. The clock was set on the last minute, the AGC is safely in the -middle ot the range 0-255, and the receiver is tracking WWV on 20 MHz. -Excellent reeiving conditions prevail, as indicated by the compare count -6 and 5 bit errors during the last minute. The current frequency is 66.4 -PPM and the averaging interval is 1024 s, indicating the maximum -precision available. +<p>Here the clock has been set and no alarms are raised. The year, +day and time are displayed along with no leap warning, standard +time and DUT +0.3 s. The clock was set on the last minute, the AGC +is safely in the middle ot the range 0-255, and the receiver is +tracking WWV on 20 MHz. Excellent reeiving conditions prevail, as +indicated by the compare count 6 and 5 bit errors during the last +minute. The current frequency is 66.4 PPM and the averaging +interval is 1024 s, indicating the maximum precision available.</p> <h4>Modes</h4> <p>The <tt>mode</tt> keyword of the <tt>server</tt> configuration -command specifies the ICOM ID select code. A missing or zero argument -disables the CI-V interface. Following are the ID select codes for the -known radios. -<p><table cols=6 width=100%> +command specifies the ICOM ID select code. A missing or zero +argument disables the CI-V interface. Following are the ID select +codes for the known radios.</p> +<table cols="6" width="100%"> <tr> <td>Radio</td> <td>Hex</td> @@ -758,6 +832,7 @@ known radios. <td>0x1A</td> <td>26</td> </tr> + <tr> <td>IC751</td> <td>0x1c</td> @@ -766,6 +841,7 @@ known radios. <td>0x34</td> <td>52</td> </tr> + <tr> <td>IC761</td> <td>0x1e</td> @@ -792,48 +868,63 @@ known radios. <td>0x2a</td> <td>42</td> </tr> - </table> <h4>Fudge Factors</h4> <dl> +<dt><tt>time1 <i>time</i></tt></dt> -<dt><tt>time1 <I>time</I></tt></dt> -<dd>Specifies the propagation delay for WWV (40:40:49.0N 105:02:27.0W), -in seconds and fraction, with default 0.0.dd> +<dd>Specifies the propagation delay for WWV (40:40:49.0N +105:02:27.0W), in seconds and fraction, with default 0.0.</dd> -<dt><tt>time2 <I>time</I></tt></dt> -<dd>Specifies the propagation delay for WWVH (21:59:26.0N 159:46:00.0W), -in seconds and fraction, with default 0.0. -</dd> +<dt><tt>time2 <i>time</i></tt></dt> -<dt><tt>stratum <I>number</I></tt></dt> -<dd>Specifies the driver stratum, in decimal from 0 to 15, with default -0.</dd> +<dd>Specifies the propagation delay for WWVH (21:59:26.0N +159:46:00.0W), in seconds and fraction, with default 0.0.</dd> + +<dt><tt>stratum <i>number</i></tt></dt> + +<dd>Specifies the driver stratum, in decimal from 0 to 15, with +default 0.</dd> + +<dt><tt>refid <i>string</i></tt></dt> + +<dd>Ordinarily, this field specifies the driver reference +identifier; however, the driver sets the reference identifier +automatically as described above.</dd> -<dt><tt>refid <I>string</I></tt></dt> -<dd>Ordinarily, this field specifies the driver reference identifier; -however, the driver sets the reference identifier automatically as -described above. <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> + +<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> + +<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> + <h4>Additional Information</h4> -<A HREF="refclock.htm">Reference Clock Drivers</A> -<br><A HREF="audio.htm">Reference Clock Audio 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></a></body></html> +<a href="refclock.htm">Reference Clock Drivers</a> <br> +<a href="audio.htm">Reference Clock Audio Drivers</a> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/driver38.htm b/contrib/ntp/html/driver38.htm new file mode 100644 index 0000000..4ae1c78 --- /dev/null +++ b/contrib/ntp/html/driver38.htm @@ -0,0 +1,191 @@ +<!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>hopf clock drivers by ATLSoft</title> +</head> +<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<h1> +<font face="Arial"><i><blink><font size="5">hopf</font></blink></i><font size="+2"> +</font><font size="3">Serial Line Receivers (6021 and kompatible)</font></font></h1> +<hr> + +<h2> +<font size=+1>Synopsis</font></h2> + +<table border="0" cellpadding cellspacing width="100%"> + <tr> + <td> + +<table border="0" cellpadding="3" bgcolor="#C0C0C0"> +<tr> +<td height="21"> +<div align=right><tt>Address: </tt></div> +</td> + +<td><b>127.127.38.<i>X</i></b></td> +</tr> + +<tr> +<td height="1"> +<div align=right><tt>Reference ID: </tt></div> +</td> + +<td height="1"><a NAME="REFID"></a><b>.hopf. </b>(default)<b>, GPS, DCF</b></td> +</tr> + +<tr> +<td height="21"> +<div align=right><tt>Driver ID: </tt></div> +</td> + +<td height="21"><b>HOPF_S</b></td> +</tr> + +<tr> +<td height="16"> +<div align=right><tt>Serial Port: </tt></div> +</td> + +<td height="16"><b>/dev/hopfclock<i>X</i></b></td> +</tr> + +<tr> +<td height="23"> +<div align=right><tt><font size=+1>Serial I/O</font>: </tt></div> +</td> + +<td height="23"><b>9600 baud, 8-bits, 1-stop, no parity</b></td> +</tr> +</table> + + </td> + <td align="center"><img border="0" src="pic/fg6021.gif" width="238" height="207"></td> + </tr> +</table> + +<hr> + +<h2> +<font size=+1>Description</font></h2> +The <b>refclock_hopf_serial</b> driver supports <a href="http://www.hopf.com">hopf +electronic receivers</a> with serial Interface kompatibel 6021. +<br>Additional software and information about the software drivers is available +from: <a href="http://www.ATLSoft.de/ntp">http://www.ATLSoft.de/ntp</a>. +<br>Latest NTP driver source, executables and documentation is maintained +at: <a href="http://www.ATLSoft.de/ntp">http://www.ATLSoft.de/ntp</a> +<hr> +<h2> +<font size=+1>Operating System Compatibility</font></h2> +<p align="left"> +The hopf clock driver has been tested on the following software and hardware +platforms: +<br> <table bgcolor="#C0C0C0"> +<tr> +<td VALIGN=CENTER WIDTH="23%" nowrap> + <p align="left"><b>Platform</b></p> +</td> + +<td VALIGN=CENTER nowrap> + <p align="left"><b>Operating System</b></p> +</td> + +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="23%" nowrap> + <p align="left">i386 (PC) </p> +</td> + +<td VALIGN=CENTER nowrap> + <p align="left">Linux</p> +</td> + +</tr> + +<tr> +<td nowrap> + <p align="left">i386 (PC) </p> + </td> + +<td nowrap> + <p align="left">Windows NT</p> + </td> + +</tr> + +<tr> +<td nowrap> + <p align="left">i386 (PC) </p> +</td> + +<center> + +<td nowrap>Windows 2000</td> + +</tr> + +</table></center> + +<hr> + +<h2> +<font size=+1>O/S Serial Port Configuration</font></h2> +The driver attempts to open the device <b><tt><a href="#REFID">/dev/hopfclock<i>X</i></a></tt></b> +where <i><b>X</b></i> 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/hopfclock0</tt></blockquote> +Windows NT does not support symbolic links to device files. <br> +<b> COMx</b>: +is used by the driver, based on the refclock unit number, where <b> unit 1</b> +corresponds to <b> COM1</b>: and <b> unit 3</b> corresponds to <b>COM3</b>: +<br> +<hr> + +<h2> +<font size=+1>Fudge Factors</font></h2> + +<dl> +<dt> +<b> +<a NAME="time1"></a><tt><font size=+1><a href="#Configuration">time1 <i>time</i></a></font></tt></b></dt> + +<dd> +Specifies the time offset calibration factor, in seconds and fraction, +with default 0.0. Should be set to +20 milliseconds to correct serial line and operating system delays incurred +in capturing time stamps from the synchronous packets.</dd> + +<dt> +<tt><font size=+1><a href="#REFID"><b>refid <i>string</i></b></a></font></tt></dt> + +<dd> +Specifies the driver reference identifier, <b>GPS </b><i>or</i> <b> DCF</b>.</dd> + +<dt> +<tt><font size=+1><b>flag1 0 +| 1</b></font></tt></dt> + +<dd> +When set to 1, driver sync's even if only crystal driven.</dd> +</dl> + +<hr> + +<h2> +<a NAME="DataFormat"></a><font size=+1>Data Format</font></h2> +<p>as specified in clock manual under pt. <u>[ <span lang="EN-GB" style="font-size:10.0pt;font-family: +Arial;mso-fareast-font-family:"Times New Roman";mso-bidi-font-family:"Times New Roman"; +mso-ansi-language:EN-GB;mso-fareast-language:DE;mso-bidi-language:AR-SA"><b>Data +String for NTP</b> ( <b><i>Network Time Protocol </i></b>) </span>]</u></p> +<hr> +<h3>Questions or Comments:</h3> +<p><a href="mailto:altmeier@atlsoft.de">Bernd Altmeier</a><a href="http://www.ATLSoft.de"><br> +Ing.-B’ro f’r Software www.ATLSoft.de</a><p>(last updated 02/28/2001) +<br> +</body> +</html> diff --git a/contrib/ntp/html/driver39.htm b/contrib/ntp/html/driver39.htm new file mode 100644 index 0000000..86b0f60 --- /dev/null +++ b/contrib/ntp/html/driver39.htm @@ -0,0 +1,162 @@ +<!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>hopf clock drivers by ATLSoft</title> +</head> +<body text="#000000" bgcolor="#FFFFFF" link="#0000FF" vlink="#800080" alink="#FF0000"> + +<h1> +<font face="Arial"><i><blink><font size="5">hopf</font></blink></i><font size="+2"> +</font><font size="3">PCI-Bus Receiver (6039 GPS/DCF77)</font></font></h1> +<hr> + +<div align="center"> + <center> + <table border="0" cellpadding="0" cellspacing="0" width="100%"> + <tr> + <td width="50%"> + <h2> +<font size=+1>Synopsis</font></h2> + +<table border="0" cellpadding="3" bgcolor="#C0C0C0"> +<tr> +<td height="21"> +<div align=right><tt>Address: </tt></div> +</td> + +<td height="21"><b>127.127.39.<i>X</i></b></td> +</tr> + +<tr> +<td height="21"> +<div align=right><tt>Reference ID: </tt></div> +</td> + +<td height="21"><a NAME="REFID"></a><b>.hopf. </b>(default)<b>, GPS, DCF</b></td> +</tr> + +<tr> +<td height="21"> +<div align=right><tt>Driver ID: </tt></div> +</td> + +<td height="21"><b>HOPF_P</b></td> +</tr> + +</table> + + </td> + <td valign="middle" align="center"><font face="Arial"><i><blink><font size="5"><img border="0" src="pic/fg6039.jpg" width="141" height="140"></font></blink></i></font></td> + </tr> + </table> + </center> +</div> + +<hr> + +<h2> +<font size=+1>Description</font></h2> +The <b>refclock_hopf_pci </b>driver supports the <a href="http://www.hopf.com">hopf</a> +PCI-bus interface 6039 GPS/DCF77. +<br>Additional software and information about the software drivers maybe available +from: <a href="http://www.ATLSoft.de/ntp">http://www.ATLSoft.de/ntp</a>. +<br>Latest NTP driver source, executables and documentation is maintained +at: <a href="http://www.ATLSoft.de/ntp">http://www.ATLSoft.de/ntp</a> +<hr> +<h2> +<font size=+1>Operating System Compatibility</font></h2> +<p align="left"> +The hopf clock driver has been tested on the following software and hardware +platforms: +<br> <table bgcolor="#C0C0C0"> +<tr> +<td VALIGN=CENTER WIDTH="23%" nowrap> + <p align="left"><b>Platform</b></p> +</td> + +<td VALIGN=CENTER nowrap> + <p align="left"><b>Operating System</b></p> +</td> + +</tr> + +<tr> +<td VALIGN=CENTER WIDTH="23%" nowrap> + <p align="left">i386 (PC) </p> +</td> + +<td VALIGN=CENTER nowrap> + <p align="left">Linux</p> +</td> + +</tr> + +<tr> +<td nowrap> + <p align="left">i386 (PC) </p> + </td> + +<td nowrap> + <p align="left">Windows NT</p> + </td> + +</tr> + +<tr> +<td nowrap> + <p align="left">i386 (PC) </p> +</td> + +<center> + +<td nowrap>Windows 2000</td> + +</tr> + +</table></center> + +<hr> + +<h2> +<font size=+1>O/S System Configuration</font></h2> + +<p> +<b>UNIX</b></p> +The driver attempts to open the device <b><tt><a href="#REFID">/dev/hopf6039</a></tt></b> +. The device entry will be made by the installation process of the kernel module +for the PCI-bus board. The driver sources belongs to the delivery equipment of +the PCI-board. +<p><b>Windows NT/2000</b> +<p> +The driver attempts to open the device by calling the function "OpenHopfDevice()". +This function will be installed by the Device Driver for the PCI-bus board. The +driver belongs to the delivery equipment of the PCI-board.</p> +<hr> + +<h2> +<font size=+1>Fudge Factors</font></h2> + +<dl> + +<dt> +<tt><font size=+1><a href="#REFID"><b>refid <i>string</i></b></a></font></tt></dt> + +<dd> +Specifies the driver reference identifier, <b>GPS </b><i>or</i> <b> DCF</b>.</dd> + +<dt> +<tt><font size=+1><b>flag1 0 +| 1</b></font></tt></dt> + +<dd> +When set to 1, driver sync's even if only crystal driven.</dd> +</dl> + +<hr> +<h3>Questions or Comments:</h3> +<p><a href="mailto:altmeier@atlsoft.de">Bernd Altmeier</a><a href="http://www.ATLSoft.de"><br> +Ing.-B’ro f’r Software www.ATLSoft.de</a><p>(last updated 03/02/2001) +<br> +</body> +</html> diff --git a/contrib/ntp/html/driver6.htm b/contrib/ntp/html/driver6.htm index 9fac978..501f697 100644 --- a/contrib/ntp/html/driver6.htm +++ b/contrib/ntp/html/driver6.htm @@ -1,242 +1,271 @@ -<html><head><title> -IRIG Audio Decoder -</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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>IRIG Audio Decoder</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.</p> + +<h4>Description</h4> This driver supports the Inter-Range Instrumentation Group (IRIG) -standard time distribution signal using the audio codec native to some -workstations. This signal is generated by several radio clocks, -including those made by Arbiter, Austron, Bancomm, Odetics, Spectracom -and TrueTime, among others, although it is often an add-on option. The -signal is connected via an optional attenuator box and cable to either -the microphone or line-in port. The driver receives, demodulates and -decodes the IRIG-B and IRIG-E signal formats using internal filters -designed to reduce the effects of noise and interference. - -<p>This driver incorporates several features in common with other audio -drivers such as described in the <a href=driver7.htm>Radio CHU Audio -Demodulator/Decoder</a> and the <a href=driver36.htm>Radio WWV/H Audio -Demodulator/Decoder</a> pages. They include automatic gain control -(AGC), selectable audio codec port and signal monitoring capabilities. -For a discussion of these common features, as well as a guide to hookup, -debugging and monitoring, see the <a href=audio.htm>Reference Clock -Audio Drivers</a> page. - -<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. +standard time distribution signal using the audio codec native to +some workstations. This signal is generated by several radio +clocks, including those made by Arbiter, Austron, Bancomm, Odetics, +Spectracom and TrueTime, among others, although it is often an +add-on option. The signal is connected via an optional attenuator +box and cable to either the microphone or line-in port. The driver +receives, demodulates and decodes the IRIG-B and IRIG-E signal +formats using internal filters designed to reduce the effects of +noise and interference. + +<p>This driver incorporates several features in common with other +audio drivers such as described in the <a href="driver7.htm">Radio +CHU Audio Demodulator/Decoder</a> and the <a href="driver36.htm"> +Radio WWV/H Audio Demodulator/Decoder</a> pages. They include +automatic gain control (AGC), selectable audio codec port and +signal monitoring capabilities. For a discussion of these common +features, as well as a guide to hookup, debugging and monitoring, +see the <a href="audio.htm">Reference Clock Audio Drivers</a> +page.</p> + +<p>The IRIG signal format uses an amplitude-modulated carrier with +pulse-width modulated data bits. For IRIG-B, the carrier frequency +is 1000 Hz and bit rate 100 b/s; for IRIG-E, the carrier frequenchy +is 100 Hz and bit rate 10 b/s. While IRIG-B provides the best +accuracy, generally within a few tens of microseconds relative to +IRIG time, it can also generate a significant load on the processor +with older workstations. Generally, the accuracy with IRIG-E is +about ten times worse than IRIG-B, but the processor load is ten +times less.</p> + +<p>The program processes 8000-Hz 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> + +<p>Infinite impulse response (IIR) filters are used with both +IRIG-B and IRIG-E formats. An 800-Hz highpass filter is used for +IRIG-B and a 130-Hz lowpass filter for IRIG-E. These are intended +for use with noisy signals, such as might be received over a +telephone line or radio circuit, or when interfering signals may be +present in the audio passband. The driver determines which IRIG +format is in use by sampling the amplitude of each filter output +and selecting the one with maximum signal. An automatic gain +control feature provides protection against overdriven or +underdriven input signal amplitudes. It is designed to maintain +adequate demodulator signal amplitude while avoiding occasional +noise spikes. In order to assure reliable capture, the decompanded +input signal amplitude must be greater than 100 units and the codec +sample frequency error less than 250 PPM (.025 percent).</p> + +<p>The program performs a number of error checks to protect against +overdriven or underdriven input signal levels, incorrect signal +format or improper hardware configuration. 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. +measurement, the data are rejected.</p> -<OL> +<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> -<LI>The peak carrier amplitude is less than 100 units. This usually -means dead IRIG signal source, broken cable or wrong input port.</LI> +<li>The frequency error is greater than ±250 PPM (.025 +percent). This usually means broken codec hardware or wrong codec +configuration.</li> -<LI>The frequency error is greater than ±250 PPM (.025 percent). -This usually means broken codec hardware or wrong codec -configuration.</LI> +<li>The modulation index is less than 0.5. This usually means +overdriven IRIG signal or wrong IRIG format.</li> -<LI>The modulation index is less than 0.5. This usually means overdriven -IRIG signal or wrong IRIG format.</LI> +<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> -<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> +<li>A data decoding error has occured. This usually means wrong +IRIG signal format.</li> -<LI>A data decoding error has occured. This usually means wrong IRIG -signal format.</LI> +<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> -<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> +<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> -<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> +Note that additional checks are done elsewhere in the reference +clock interface routines. -</OL> +<p>Unlike other drivers, which can have multiple instantiations, +this one supports only one. It does not seem likely that more than +one audio codec would be useful in a single machine. More than one +would probably chew up too much CPU time anyway.</p> -Note that additional checks are done elsewhere in the reference clock -interface routines. +<h4>IRIG-B Timecode Format</h4> -<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. +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. -<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 +<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: +digits. The driver will automatically reject the data and declare +itself unsynchronized in this case. Some devices, in particular +Spectracom radio/satellite clocks, provide additional year and +status indication in the format:</p> -<PRE> Element CF Function +<pre> + Element CF Function ------------------------------------- 55 6 time sync status 60-63 10-13 BCD year units 65-68 15-18 BCD year tens -</PRE> +</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 <font +face="symbol">m</font>s 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.</p> + +<h4>Monitor Data</h4> + +The timecode format used for debugging and data recording includes +data helpful in diagnosing problems with the IRIG signal and codec +connections. With debugging enabled (-d on the ntpd command line), +the driver produces one line for each timecode in the following +format: -Other devices set these elements to zero. +<p><tt>00 1 98 23 19:26:52 721 143 0.694 47 20 0.083 66.5 +3094572411.00027</tt></p> -<H4>Performance</H4> +<p>The first field containes the error flags in hex, where the hex +bits are interpreted as below. This is followed by the IRIG status +indicator, year of century, day of year and time of day. The status +indicator and year are not produced by some IRIG devices. Following +these fields are the 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.</p> -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. +<h4>Fudge Factors</h4> -<P>The accuracy of the system clock synchronized to the IRIG-B source -with this driver and the <TT>ntpd</TT> daemon is 10-20 <font -face=symbol>m</font>s with a Sun UltraSPARC II 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. +<dl> +<dt><tt>time1 <i>time</i></tt></dt> -<H4>Monitor Data</H4> +<dd>Specifies the time offset calibration factor, in seconds and +fraction, with default 0.0.</dd> -The timecode format used for debugging and data recording includes data -helpful in diagnosing problems with the IRIG signal and codec -connections. With debugging enabled (-d on the ntpd command line), the -driver produces one line for each timecode in the following format: +<dt><tt>time2 <i>time</i></tt></dt> -<p><tt>00 1 98 23 19:26:52 721 143 0.694 47 20 0.083 66.5 -3094572411.00027</tt> +<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> -<p>The first field containes the error flags in hex, where the hex bits -are interpreted as below. This is followed by the IRIG status indicator, -year of century, day of year and time of day. The status indicator and -year are not produced by some IRIG devices. Following these fields are -the 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. +<dd>Specifies the driver reference identifier, an ASCII string from +one to four characters, with default <tt>IRIG</tt>.</dd> -<H4>Fudge Factors</H4> +<dt><tt>flag1 0 | 1</tt></dt> -<DL> +<dd>Not used by this driver.</dd> -<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>flag2 0 | 1</tt></dt> -<DT><TT>time2 <I>time</I></TT></DT> -<DD>Not used by this driver.</DD> +<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>stratum <I>number</I></TT></DT> -<DD>Specifies the driver stratum, in decimal from 0 to 15, with default -0.</DD> +<dt><tt>flag3 0 | 1</tt></dt> -<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> +<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>flag1 0 | 1</TT></DT> -<DD>Not used by this driver.</DD> +<dt><tt>flag4 0 | 1</tt></dt> -<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> +<dd>Enable verbose <tt>clockstats</tt> recording if set.</dd> +</dl> -<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> +<h4>Additional Information</h4> -<DT><TT>flag4 0 | 1</TT></DT> -<DD>Enable verbose <TT>clockstats</TT> recording if set.</DD> -</DL> +<a href="refclock.htm">Reference Clock Drivers</a> <br> +<a href="audio.htm">Reference Clock Audio Drivers</a> -<H4>Additional Information</H4> +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> -<A HREF="refclock.htm">Reference Clock Drivers</A> -<br><A HREF="audio.htm">Reference Clock Audio Drivers</A> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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/driver7.htm b/contrib/ntp/html/driver7.htm index 5995072..029ac04 100644 --- a/contrib/ntp/html/driver7.htm +++ b/contrib/ntp/html/driver7.htm @@ -1,362 +1,397 @@ -<html><head><title> -Radio CHU Audio Demodulator/Decoder -</title></head><body><h3> -Radio CHU Audio Demodulator/Decoder -</h3><hr> - +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Radio CHU Audio Demodulator/Decoder</title> +</head> +<body> +<h3>Radio CHU Audio Demodulator/Decoder</h3> + +<hr> <h4>Synopsis</h4> -Address: 127.127.7.<I>u</I> -<br>Reference ID: <tt>CHU</tt> -<br>Driver ID: <tt>CHU</tt> -<br>Modem Port: <tt>/dev/chu<I>u</I></tt>; 300 baud, 8-bits, no parity -<br>Autotune Port: <tt>/dev/icom</tt>; 9600 baud, 8-bits, no parity -<br>Audio Device: <tt>/dev/audio</tt> and <tt>/dev/audioctl</tt> +Address: 127.127.7.<i>u</i> <br> +Reference ID: <tt>CHU</tt> <br> +Driver ID: <tt>CHU</tt> <br> +Modem Port: <tt>/dev/chu<i>u</i></tt>; 300 baud, 8-bits, no parity +<br> +Autotune Port: <tt>/dev/icom</tt>; 1200/9600 baud, 8-bits, no +parity <br> +Audio Device: <tt>/dev/chu_audio</tt> and <tt>/dev/audioctl</tt> <h4>Description</h4> -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 as -propagation conditions change throughout the day and night. The -performance of this driver when tracking the station is ordinarily -better than 1 ms in time with frequency drift less than 0.5 PPM when not -tracking the station. - -<p>While there are currently no known commercial CHU receivers, a simple -but effective receiver/demodulator can be constructed from an ordinary -shortwave receiver and Bell 103 compatible, 300-b/s modem or modem chip, -as described in the <a href=pps.htm>Pulse-per-second (PPS) Signal -Interfacing</a> page. The driver can be compiled to use a 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 interface. 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 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>This driver incorporates several features in common with other audio -drivers such as described in the <a href=driver36.htm>Radio WWV/H Audio -Demodulator/Decoder</a> and the <a href=driver6.htm>IRIG Audio -Decoder</a> pages. They include automatic gain control (AGC), selectable -audio codec port and signal monitoring capabilities. For a discussion of -these common features, as well as a guide to hookup, debugging and -monitoring, see the <a href=audio.htm>Reference Clock Audio Drivers</a> -page. +<p>This driver synchronizes the computer time using data encoded in +radio transmissions from Canadian time/frequency station CHU in +Ottawa, Ontario. It replaces an earlier one, built by Dennis +Ferguson in 1988, which required a special line discipline to +preprocessed the signal. The new driver includes more powerful +algorithms implemented directly in the driver and requires no +preprocessing.</p> + +<p>CHU transmissions are made continuously on 3330 kHz, 7335 kHz +and 14670 kHz in upper sideband, compatible AM mode. An ordinary +shortwave receiver can be tuned manually to one of these +frequencies or, in the case of ICOM receivers, the receiver can be +tuned automatically as propagation conditions change throughout the +day and night. The performance of this driver when tracking the +station is ordinarily better than 1 ms in time with frequency drift +less than 0.5 PPM when not tracking the station.</p> + +<p>While there are currently no known commercial CHU receivers, a +simple but effective receiver/demodulator can be constructed from +an ordinary shortwave receiver and Bell 103 compatible, 300-b/s +modem or modem chip, as described in the <a href="gadget.htm"> +Gadget Box PPS Level Converter and CHU Modem</a> page. The driver +can use the modem to receive the radio signal and demodulate the +data or, if available, the driver can use the audio codec of the +Sun workstation or another with compatible audio interface. In the +latter case, the driver implements the modem using DSP routines, so +the radio can be connected directly to either the microphone on +line input port.</p> + +<p>This driver incorporates several features in common with other +audio drivers such as described in the <a href="driver36.htm">Radio +WWV/H Audio Demodulator/Decoder</a> and the <a href="driver6.htm"> +IRIG Audio Decoder</a> pages. They include automatic gain control +(AGC), selectable audio codec port and signal monitoring +capabilities. For a discussion of these common features, as well as +a guide to hookup, debugging and monitoring, see the <a href= +"audio.htm">Reference Clock Audio Drivers</a> page.</p> <p>Ordinarily, the driver poll interval is set to 14 (about 4.5 h), -although this can be changed with configuration commands. As long as the -clock is set or verified at least once during this interval, the NTP -algorithms will consider the source reachable and selectable to -discipline the system clock. However, if this does not happen for eight -poll intervals, the algorithms will consider the source unreachable and -some other source will be chosen (if available) to discipline the system -clock. - -<p>The decoding algorithms take advantage of all the redundancy -available in each broadcast message or burst. In each burst described in -the next section, every character is sent twice and, in the case of -format A bursts, the burst is sent eight times every minute. In the case -of format B bursts, which are sent once each minute, the burst is -considered correct only if every character matches its repetition in the -burst. In the case of format A messages, a majority decoder requires at -least six repetitions for each digit in the timecode and more than -half of the repetitions decode to the same digit. Every character in -every burst provides an independent timestamp upon arrival with a -potential total of over 60 timestamps for each minute. - -<p>A timecode in the format described below is assembled when all bursts -have been received in the minute. The timecode is considered valid and -the clock set when at least one valid format B burst has been decoded -and the above requirements are met. The <tt>yyyy</tt> year field in the -timecode indicates whether a valid format B burst has been received. -Upon startup, this field is initialized at zero; when a valid format B -burst is received, it will be set to the correct Gregorian year. The -<tt>q</tt> quality character field in the timecode indicates whether a -valid timecode has been determined. If any of the high order three bits -of this character are set, the timecode is invalid. +although this can be changed with configuration commands. As long +as the clock is set or verified at least once during this interval, +the NTP algorithms will consider the source reachable and +selectable to discipline the system clock. However, if this does +not happen for eight poll intervals, the algorithms will consider +the source unreachable and some other source will be chosen (if +available) to discipline the system clock.</p> + +<p>The decoding algorithms process the data using +maximum-likelihood techniques which exploit the considerable degree +of redundancy available in each broadcast message or burst. As +described below, every character is sent twice and, in the case of +format A bursts, the burst is sent eight times every minute. In the +case of format B bursts, which are sent once each minute, the burst +is considered correct only if every character matches its +repetition in the burst. In the case of format A messages, a +majority decoder requires at least six repetitions for each digit +in the timecode and more than half of the repetitions decode to the +same digit. Every character in every burst provides an independent +timestamp upon arrival with a potential total of over 60 timestamps +for each minute.</p> + +<p>A timecode in the format described below is assembled when all +bursts have been received in the minute. The timecode is considered +valid and the clock set when at least one valid format B burst has +been decoded and the above requirements are met. The <tt>yyyy</tt> +year field in the timecode indicates whether a valid format B burst +has been received. Upon startup, this field is initialized at zero; +when a valid format B burst is received, it is set to the current +Gregorian year. The <tt>q</tt> quality character field in the +timecode indicates whether a valid timecode has been determined. If +any of the high order three bits of this character are set, the +timecode is invalid.</p> <p>Once the clock has been set for the first time, it will appear -reachable and selectable to discipline the system clock, even if the -broadcast signal is lost. Since the signals are almost always available -during some period of the day and the NTP clock discipline algorithms -are designed to work well even in this case, it is unlikely that the -system clock could drift more than a few tens of milliseconds during -periods of signal loss. To protect against this most unlikely situation, -if after four days with no signals, the clock is considered unset and -resumes the synchronization procedure from the beginning. - -<p>The last three fields in the timecode are useful in assessing the -quality of the radio channel during the most recent minute bursts were -received. The <tt>bcnt</tt> field shows the number of format A bursts in -the range 1-8. The <tt>dist</tt> field shows the majority decoder -distance, or the minimum number of sample repetitions for each digit of -the timecode in the range 0-16. The <tt>tsmp</tt> field shows the number -of timestamps determined in the range 0-60. For a valid timecode, -<tt>bcnt</tt> must be at least 3, <tt>dist</tt> must be greater than -<tt>bcnt</tt> and <tt>tsmp</tt> must be at least 20. +reachable and selectable to discipline the system clock, even if +the broadcast signal is lost. Since the signals are almost always +available during some period of the day and the NTP clock +discipline algorithms are designed to work well even in this case, +it is unlikely that the system clock could drift more than a few +tens of milliseconds during periods of signal loss. To protect +against this most unlikely situation, if after four days with no +signals, the clock is considered unset and resumes the +synchronization procedure from the beginning.</p> + +<p>The last three fields in the timecode are useful in assessing +the quality of the radio channel during the most recent minute +bursts were received. The <tt>bcnt</tt> field shows the number of +format A bursts in the range 1-8. The <tt>dist</tt> field shows the +majority decoder distance, or the minimum number of sample +repetitions for each digit of the timecode in the range 0-16. The +<tt>tsmp</tt> field shows the number of timestamps determined in +the range 0-60. For a valid timecode, <tt>bcnt</tt> must be at +least 3, <tt>dist</tt> must be greater than <tt>bcnt</tt> and <tt> +tsmp</tt> must be at least 20.</p> <h4>Program Operation</h4> <p>The program consists of four major parts: the DSP modem, maximum -likelihood UART, burst assembler and majority decoder. The DSP modem -demodulates Bell 103 modem answer-frequency signals; that is, frequency- -shift keyed (FSK) tones of 2225 Hz (mark) and 2025 Hz (space). This is -done using a 4th-order IIR filter and limiter/discriminator with 500-Hz -bandpass centered on 2125 Hz and followed by a FIR raised-cosine lowpass -filter optimized for the 300-b/s data rate. Alternately, the driver can -be compiled to delete the modem and input 300 b/s data directly from an -external modem via a serial port. +likelihood UART, burst assembler and majority decoder. The DSP +modem demodulates Bell 103 modem answer-frequency signals; that is, +frequency-shift keyed (FSK) tones of 2225 Hz (mark) and 2025 Hz +(space). This is done using a 4th-order IIR filter and +limiter/discriminator with 500-Hz bandpass centered on 2125 Hz and +followed by a FIR raised-cosine lowpass filter optimized for the +300-b/s data rate. Alternately, the driver can be compiled to +delete the modem and input 300 b/s data directly from an external +modem via a serial port.</p> <p>The maximum likelihood UART is implemented using a set of eight -11-stage shift registers, one for each of eight phases of the 300-b/s -bit clock. At each phase a new baseband signal value from the DSP modem -is shifted into the corresponding register and the maximum and minimum -over all 11 samples computed. This establishes a slice level midway -between the maximum and minimum over all stages. For each stage, a -signal level above this level is a mark (1) and below is a space (0). A -quality metric is calculated for each register with respect to the slice -level and the a-priori signal consisting of a mark bit (previous stop -bit), space (start) bit, eight arbitrary information bits and the first -of the two mark (stop) bits. -<p>The shift registers are processed in round-robin order as each modem -value arrives until one of them shows a valid framing pattern consisting -of a mark bit, space bit, eight arbitrary data bits and a mark bit. When -found, the data bits from the register with the best metric is chosen as -the maximum likelihood character and the UART begins to process the next -character. +11-stage shift registers, one for each of eight phases of the +300-b/s bit clock. At each phase a new baseband signal value from +the DSP modem is shifted into the corresponding register and the +maximum and minimum over all 11 samples computed. This establishes +a slice level midway between the maximum and minimum over all +stages. For each stage, a signal level above this level is a mark +(1) and below is a space (0). A quality metric is calculated for +each register with respect to the slice level and the a-priori +signal consisting of a mark bit (previous stop bit), space (start) +bit, eight arbitrary information bits and the first of the two mark +(stop) bits.</p> + +<p>The shift registers are processed in round-robin order as each +modem value arrives until one of them shows a valid framing pattern +consisting of a mark bit, space bit, eight arbitrary data bits and +a mark bit. When found, the data bits from the register with the +best metric is chosen as the maximum likelihood character and the +UART begins to process the next character.</p> <p>The burst assembler processes characters either from the maximum -likelihood UART or directly from the serial port as configured. A burst -begins when a character is received and is processed after a timeout -interval when no characters are received. If the interval between -characters is greater than two characters, but less than the timeout -interval, the burst is rejected as a runt and a new burst begun. As each -character is received, a timestamp is captured and saved for later -processing. +likelihood UART or directly from the serial port as configured. A +burst begins when a character is received and is processed after a +timeout interval when no characters are received. If the interval +between characters is greater than two characters, but less than +the timeout interval, the burst is rejected as a runt and a new +burst begun. As each character is received, a timestamp is captured +and saved for later processing.</p> <p>A valid burst consists of ten characters in two replicated five-character blocks. A format B block contains the year and other -information in ten hexadecimal digits. A format A block contains the -timecode in ten decimal digits, the first of which is a framing code -(6). The burst assembler must deal with cases where the first character -of a format A burst is lost or is noise. This is done using the framing -code to correct the phase, either one character early or one character -late. - -<p>The burst distance is incremented by one for each bit in the first -block that matches the corresponding bit in the second block and -decremented by one otherwise. In a format B burst the second block is -bit-inverted relative to the first, so a perfect burst of five 8-bit -characters has distance -40. In a format A block the two blocks are -identical, so a perfect burst has distance +40. Format B bursts must be -perfect to be acceptable; however, format A bursts, which are further -processed by the majority decoder, are acceptable if the distance is at -least 28. - -<p>Each minute of transmission includes eight format A bursts containing -two timecodes for each second from 31 through 39. The majority decoder -uses a decoding matrix of ten rows, one for each digit position in the -timecode, and 16 columns, one for each 4-bit code combination that might -be decoded at that position. In order to use the character timestamps, -it is necessary to reliably determine the second number of each burst. -In a valid burst, the last digit of the two timecodes in the block must -match and the value must be in the range 2-9 and greater than in the -previous burst. - -<p>As each hex digit of a valid burst is processed, the value at the row -corresponding to the digit position in the timecode and column -corresponding to the code found at that position is incremented. At the -end of each minute of transmission, each row of the decoding matrix -encodes the number of occurrences of each code found at the -corresponding position of the timecode. However, the first digit -(framing code) is always 6, the ninth (second tens) is always 3 and the -last (second units) changes for each burst, so are not used. - -<p>The maximum over all occurrences at each timecode digit position is -the distance for that position and the corresponding code is the maximum -likelihood candidate. If the distance is zero, the decoder assumes a -miss; if the distance is not more than half the total number of -occurrences, the decoder assumes a soft error; if two different codes -with the same distance are found, the decoder assumes a hard error. In -all these cases the decoder encodes a non-decimal character which will -later cause a format error when the timecode is reformatted. The -decoding distance is defined as the minimum distance over the first nine -digits; the tenth digit varies over the seconds and is uncounted. +information in ten hexadecimal digits. A format A block contains +the timecode in ten decimal digits, the first of which is a framing +code (6). The burst assembler must deal with cases where the first +character of a format A burst is lost or is noise. This is done +using the framing code to correct the phase, either one character +early or one character late.</p> + +<p>The burst distance is incremented by one for each bit in the +first block that matches the corresponding bit in the second block +and decremented by one otherwise. In a format B burst the second +block is bit-inverted relative to the first, so a perfect burst of +five 8-bit characters has distance -40. In a format A block the two +blocks are identical, so a perfect burst has distance +40. Format B +bursts must be perfect to be acceptable; however, format A bursts, +which are further processed by the majority decoder, are acceptable +if the distance is at least 28.</p> + +<p>Each minute of transmission includes eight format A bursts +containing two timecodes for each second from 31 through 39. The +majority decoder uses a decoding matrix of ten rows, one for each +digit position in the timecode, and 16 columns, one for each 4-bit +code combination that might be decoded at that position. In order +to use the character timestamps, it is necessary to reliably +determine the second number of each burst. In a valid burst, the +last digit of the two timecodes in the block must match and the +value must be in the range 2-9 and greater than in the previous +burst.</p> + +<p>As each hex digit of a valid burst is processed, the value at +the row corresponding to the digit position in the timecode and +column corresponding to the code found at that position is +incremented. At the end of each minute of transmission, each row of +the decoding matrix encodes the number of occurrences of each code +found at the corresponding position of the timecode. However, the +first digit (framing code) is always 6, the ninth (second tens) is +always 3 and the last (second units) changes for each burst, so are +not used.</p> + +<p>The maximum over all occurrences at each timecode digit position +is the distance for that position and the corresponding code is the +maximum likelihood candidate. If the distance is zero, the decoder +assumes a miss; if the distance is not more than half the total +number of occurrences, the decoder assumes a soft error; if two +different codes with the same distance are found, the decoder +assumes a hard error. In all these cases the decoder encodes a +non-decimal character which will later cause a format error when +the timecode is reformatted. The decoding distance is defined as +the minimum distance over the first nine digits; the tenth digit +varies over the seconds and is uncounted.</p> <p>The result of the majority decoder is a nine-digit timecode representing the maximum likelihood candidate for the transmitted -timecode in that minute. Note that the second and fraction within the -minute are always zero and that the actual reference point to calculate -timestamp offsets is backdated to the first second of the minute. At -this point the timecode block is reformatted and the year, days, hours -and minutes extracted along with other information from the format B -burst, including DST state, DUT1 correction and leap warning. The -reformatting operation checks the timecode for invalid code combinations -that might have been left by the majority decoder and rejects the entire -timecode if found. +timecode in that minute. Note that the second and fraction within +the minute are always zero and that the actual reference point to +calculate timestamp offsets is backdated to the first second of the +minute. At this point the timecode block is reformatted and the +year, days, hours and minutes extracted along with other +information from the format B burst, including DST state, DUT1 +correction and leap warning. The reformatting operation checks the +timecode for invalid code combinations that might have been left by +the majority decoder and rejects the entire timecode if found.</p> <p>If the timecode is valid, it is passed to the reference clock -interface along with the backdated timestamp offsets accumulated over -the minute. A perfect set of nine bursts could generate as many as 90 -timestamps, but the maximum the interface can handle is 60. These are -processed by the interface using a median filter and trimmed-mean -average, so the resulting system clock correction is usually much better -than would otherwise be the case with radio noise, UART jitter and -occasional burst errors. +interface along with the backdated timestamp offsets accumulated +over the minute. A perfect set of nine bursts could generate as +many as 90 timestamps, but the maximum the interface can handle is +60. These are processed by the interface using a median filter and +trimmed-mean average, so the resulting system clock correction is +usually much better than would otherwise be the case with radio +noise, UART jitter and occasional burst errors.</p> <h4>Autotune</h4> -<p>The driver includes provisions to automatically tune the radio in -response to changing radio propagation conditions throughout the day and -night. The radio interface is compatible with the ICOM CI-V standard, -which is a bidirectional serial bus operating at TTL levels. The bus can -be connected to a standard serial port using a level converter such as -the CT-17. The serial port speed is presently compiled in the program, -but can be changed in the <tt>icom.h</tt> header file. - -<p>Each ICOM radio is assigned a unique 8-bit ID select code, usually -expressed in hex format. To activate the CI-V interface, the -<tt>mode</tt> keyword of the <tt>server</tt> configuration command -specifies a nonzero select code in decimal format. A table of ID select -codes for the known ICOM radios is given below. A missing <tt>mode</tt> -keyword or a zero argument leaves the interface disabled. The driver -will attempt to open the device <tt>/dev/icom</tt> and, if successful -will tune the radio to 3.330 MHz. If after five minutes at this -frequency not more than two format A bursts have been received for any -minute, the driver will tune to 7.335 MHz, then to 14.670 MHz, then -return to 3.330 MHz and continue in this cycle. - -<p>The driver is liberal in what it assumes of the configuration. If the -<tt>/dev/icom</tt> link is not present or the open fails or the CI-V bus -or radio is inoperative, the driver quietly gives up with no harm done. +<p>The driver includes provisions to automatically tune the radio +in response to changing radio propagation conditions throughout the +day and night. The radio interface is compatible with the ICOM CI-V +standard, which is a bidirectional serial bus operating at TTL +levels. The bus can be connected to a standard serial port using a +level converter such as the CT-17. The serial port speed is +presently compiled in the program, but can be changed in the <tt> +icom.h</tt> header file.</p> + +<p>Each ICOM radio is assigned a unique 8-bit ID select code, +usually expressed in hex format. To activate the CI-V interface, +the <tt>mode</tt> keyword of the <tt>server</tt> configuration +command specifies a nonzero select code in decimal format. A table +of ID select codes for the known ICOM radios is given below. Since +all ICOM select codes are less than 128, the high order bit of the +code is used by the driver to specify the baud rate. If this bit is +not set, the rate is 9600 bps for the newer radios; if set, the +rate is 1200 bps for the older radios. A missing <tt>mode</tt> +keyword or a zero argument leaves the interface disabled.</p> + +<p>If specified, the driver will attempt to open the device <tt> +/dev/icom</tt> and, if successful will tune the radio to 3.330 MHz. +If after five minutes at this frequency not more than two format A +bursts have been received for any minute, the driver will tune to +7.335 MHz, then to 14.670 MHz, then return to 3.330 MHz and +continue in this cycle. However, the driver is liberal in what it +assumes of the configuration. If the <tt>/dev/icom</tt> link is not +present or the open fails or the CI-V bus or radio is inoperative, +the driver quietly gives up with no harm done.</p> <h4>Radio Broadcast Format</h4> -<p>The CHU time broadcast includes an audio signal compatible with the -Bell 103 modem standard (mark = 2225 Hz, space = 2025 Hz). It consist of -nine, ten-character bursts transmitted at 300 b/s and beginning each -second from second 31 to second 39 of the minute. Each character -consists of eight data bits plus one start bit and two stop bits to -encode two hex digits. The burst data consist of five characters (ten -hex digits) followed by a repeat of these characters. In format A, the -characters are repeated in the same polarity; in format B, the -characters are repeated in the opposite polarity. - -<p>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>), minute (<tt>mm</tt>) and -second (<tt>ss</tt>). Since format A bursts are sent during the -third decade of seconds the tens digit of <tt>ss</tt> is always 3. The -driver uses this to determine correct burst synchronization. These -digits are then repeated with the same polarity. -<p>Format B bursts are sent at second 31 of the minute in hex digits - -<p><tt>xdyyyyttaaxdyyyyttaa</tt> +<p>The CHU time broadcast includes an audio signal compatible with +the Bell 103 modem standard (mark = 2225 Hz, space = 2025 Hz). It +consist of nine, ten-character bursts transmitted at 300 b/s and +beginning each second from second 31 to second 39 of the minute. +Each character consists of eight data bits plus one start bit and +two stop bits to encode two hex digits. The burst data consist of +five characters (ten hex digits) followed by a repeat of these +characters. In format A, the characters are repeated in the same +polarity; in format B, the characters are repeated in the opposite +polarity.</p> + +<p>Format A bursts are sent at seconds 32 through 39 of the minute +in hex digits</p> + +<p><tt>6dddhhmmss6dddhhmmss</tt></p> + +<p>The first ten digits encode a frame marker (<tt>6</tt>) followed +by the day (<tt>ddd</tt>), hour (<tt>hh</tt>), minute (<tt>mm</tt>) +and second (<tt>ss</tt>). Since format A bursts are sent during the +third decade of seconds the tens digit of <tt>ss</tt> is always 3. +The driver uses this to determine correct burst synchronization. +These digits are then repeated with the same polarity.</p> + +<p>Format B bursts are sent at second 31 of the minute in hex +digits</p> + +<p><tt>xdyyyyttaaxdyyyyttaa</tt></p> <p>The first ten digits encode a code (<tt>x</tt> described below) followed by the DUT1 (<tt>d</tt> in deciseconds), Gregorian year -(<tt>yyyy</tt>), difference TAI - UTC (<tt>tt</tt>) and daylight time -indicator (<tt>aa</tt>) peculiar to Canada. These digits are then -repeated with inverted polarity. +(<tt>yyyy</tt>), difference TAI - UTC (<tt>tt</tt>) and daylight +time indicator (<tt>aa</tt>) peculiar to Canada. These digits are +then repeated with inverted polarity.</p> -<p>The <tt>x</tt> is coded +<p>The <tt>x</tt> is coded</p> <dl> +<dt><tt>1</tt></dt> -<dt><tt>1</tt> -<dd>Sign of DUT (0 = +)/dd> +<dd>Sign of DUT (0 = +)/dd></dd> + +<dt><tt>2</tt></dt> -<dt><tt>2</tt> <dd>Leap second warning. One second will be added.</dd> -<dt><tt>4</tt> +<dt><tt>4</tt></dt> + <dd>Leap second warning. One second will be subtracted. This is not likely to happen in our universe.</dd> -<dt><tt>8</tt> -<dd>Even parity bit for this nibble.</dd> +<dt><tt>8</tt></dt> +<dd>Even parity bit for this nibble.</dd> </dl> <p>By design, the last stop bit of the last character in the burst coincides with 0.5 second. Since characters have 11 bits and are transmitted at 300 b/s, the last stop bit of the first character -coincides with 0.5 - 10 * 11/300 = 0.133 second. Depending on the UART, -character interrupts can vary somewhere between the beginning of bit 9 -and end of bit 11. These eccentricities can be corrected along with the -radio propagation delay using the <tt>fudge time1</tt> variable. +coincides with 0.5 - 10 * 11/300 = 0.133 second. Depending on the +UART, character interrupts can vary somewhere between the beginning +of bit 9 and end of bit 11. These eccentricities can be corrected +along with the radio propagation delay using the <tt>fudge +time1</tt> variable.</p> <h4>Debugging Aids</h4> <p>The most convenient way to track the program status is using the -<tt>ntpq</tt> program and the <tt>clockvar</tt> command. This displays -the last determined timecode and related status and error counters, even -when the program is not discipline the system clock. If the debugging -trace feature (<tt>-d</tt> on the <tt>ntpd</tt> command line)is enabled, -the program produces detailed status messages as it operates. If the -<tt>fudge flag 4</tt> is set, these messages are written to the -<tt>clockstats</tt> file. All messages produced by this driver have the -prefix <tt>chu</tt> for convenient filtering with the Unix <tt>grep</tt> -command. - -<p>With debugging enabled the driver produces messages in the following -formats: - -<p>A format <tt>chuA</tt> message is produced for each format A burst -received in seconds 32 through 39 of the minute: - -<p><tt>chuA 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>A format <tt>chuB</tt> message is produced for each format B burst -received in second 31 of the minute: - -<p><tt>chuB 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. +<tt>ntpq</tt> program and the <tt>clockvar</tt> command. This +displays the last determined timecode and related status and error +counters, even when the program is not discipline the system clock. +If the debugging trace feature (<tt>-d</tt> on the <tt>ntpd</tt> +command line)is enabled, the program produces detailed status +messages as it operates. If the <tt>fudge flag 4</tt> is set, these +messages are written to the <tt>clockstats</tt> file. All messages +produced by this driver have the prefix <tt>chu</tt> for convenient +filtering with the Unix <tt>grep</tt> command.</p> + +<p>With debugging enabled the driver produces messages in the +following formats:</p> + +<p>A format <tt>chuA</tt> message is produced for each format A +burst received in seconds 32 through 39 of the minute:</p> + +<p><tt>chuA n b s code</tt></p> + +<p>where <tt>n</tt> is the number of characters in the burst +(0-11), <tt>b</tt> the burst distance (0-40), <tt>s</tt> the +synchronization distance (0-40) and <tt>code</tt> the burst +characters as received. Note that the hex digits in each character +are reversed and the last ten digits inverted, so the burst</p> + +<p><tt>11 40 1091891300ef6e76ecff</tt></p> + +<p>is interpreted as containing 11 characters with burst distance +40. The nibble-swapped timecode shows DUT1 +0.1 second, year 1998 +and TAI -UTC 31 seconds.</p> + +<p>A format <tt>chuB</tt> message is produced for each format B +burst received in second 31 of the minute:</p> + +<p><tt>chuB n b f s m code</tt></p> + +<p>where <tt>n</tt> is the number of characters in the burst +(0-11), <tt>b</tt> the burst distance (0-40), <tt>f</tt> the field +alignment (-1, 0, 1), <tt>s</tt>the synchronization distance +(0-16), <tt>m</tt>the burst number (2-9) and <tt>code</tt> the +burst characters as received. Note that the hex digits in each +character are reversed, so the burst</p> + +<p><tt>10 38 0 16 9 06851292930685129293</tt></p> + +<p>is interpreted as containing 11 characters with burst distance +38, field alignment 0, synchronization distance 16 and burst number +9. The nibble-swapped timecode shows day 58, hour 21, minute 29 and +second 39.</p> <p>If the CI-V interface for ICOM radios is active, a debug level -greater than 1 will produce a trace of the CI-V command and response -messages. Interpretation of these messages requires knowledge of the -CI-V protocol, which is beyond the scope of this document. +greater than 1 will produce a trace of the CI-V command and +response messages. Interpretation of these messages requires +knowledge of the CI-V protocol, which is beyond the scope of this +document.</p> <h4>Monitor Data</h4> -When enabled by the <tt>filegen</tt> facility, every received timecode -is written to the <tt>clockstats</tt> file in the following format: +When enabled by the <tt>filegen</tt> facility, every received +timecode is written to the <tt>clockstats</tt> file in the +following format: <pre> sq yy ddd hh:mm:ss.fff ld dut lset agc rfrq bcnt dist tsmp @@ -380,84 +415,103 @@ is written to the <tt>clockstats</tt> file in the following format: tsmp timestamps captured </pre> -The fields beginning with <tt>year</tt> and extending through -<tt>dut</tt> are decoded from the received data and are in fixed-length +The fields beginning with <tt>year</tt> and extending through <tt> +dut</tt> are decoded from the received data and are in fixed-length format. The <tt>agc</tt> and <tt>lset</tt> fields, as well as the -following driver-dependent fields, are in variable-length format. +following driver-dependent fields, are in variable-length format. <dl> +<dt><tt>s</tt></dt> -<dt><tt>s</tt> -<dd>The sync indicator is initially <tt>?</tt> before the clock is set, -but turns to space when the clock is correctly set.</dd> +<dd>The sync indicator is initially <tt>?</tt> before the clock is +set, but turns to space when the clock is correctly set.</dd> -<dt><tt>q</tt> -<dd>The quality character is a four-bit hexadecimal code showing which -alarms have been raised during the most recent minute. Each bit is -associated with a specific alarm condition according to the following: +<dt><tt>q</tt></dt> + +<dd>The quality character is a four-bit hexadecimal code showing +which alarms have been raised during the most recent minute. Each +bit is associated with a specific alarm condition according to the +following: <dl> -<dt><tt>8</tt> -<dd>Decoder alarm. A majority of repetitions for at least one digit of -the timecode fails to agree. -</dd> +<dt><tt>8</tt></dt> + +<dd>Decoder alarm. A majority of repetitions for at least one digit +of the timecode fails to agree.</dd> -<dt><tt>4</tt> -<dd>Timestamp alarm. Fewer than 20 timestamps have been determined.</dd> +<dt><tt>4</tt></dt> + +<dd>Timestamp alarm. Fewer than 20 timestamps have been +determined.</dd> + +<dt><tt>2</tt></dt> -<dt><tt>2</tt> <dd>Format alarm. The majority timecode contains invalid bit combinations.</dd> -<dt><tt>1</tt> +<dt><tt>1</tt></dt> + <dd>Frame alarm. A framing or format error occurred on at least one burst during the minute.</dd> - </dl> -It is important to note that one or more of the above alarms does not -necessarily indicate a clock error, but only that the decoder has -detected a condition that may in future result in an error. +It is important to note that one or more of the above alarms does +not necessarily indicate a clock error, but only that the decoder +has detected a condition that may in future result in an +error.</dd> + +<dt><tt>yyyy ddd hh:mm:ss.fff</tt></dt> -<dt><tt>yyyy ddd hh:mm:ss.fff</tt></tt> <dd>The timecode format itself is self explanatory. Note that the -Gregorian year is decoded directly from the transmitted timecode.</dd> -<dt><tt>l</tt> -<dd>The leap second warning is normally space, but changes to <tt>L</tt> -if a leap second is to occur at the end of the month of June or -December.</dd> - -<dt><tt>d</tt> -<dd>The DST code for Canada encodes the state for all provinces.</dd> - -<dt><tt>dut</tt> -<dd>The DUT sign and magnitude shows the current UT1 offset relative to -the displayed UTC time, in deciseconds.</dd> - -<dt><tt>lset</tt> -<dd>Before the clock is set, the interval since last set is the number -of minutes since the program was started; after the clock is set, this -is number of minutes since the time was last verified relative to the -broadcast signal.</dd> - -<dt><tt>agc</tt> -<dd>The audio gain shows the current codec gain setting in the range 0 -to 255. Ordinarily, the receiver audio gain control or IRIG level -control should be set for a value midway in this range. - -<dt><tt>rfrq</tt> -<dd>The current radio frequency, if the CI-V interface is active, or 'X' -if not.</dd> - -<dt><tt>bcnt</tt> -<dd>The number of format A bursts received during the most recent minute -bursts were received.</dd> - -<dt><tt>dist</tt> +Gregorian year is decoded directly from the transmitted +timecode.</dd> + +<dt><tt>l</tt></dt> + +<dd>The leap second warning is normally space, but changes to <tt> +L</tt> if a leap second is to occur at the end of the month of June +or December.</dd> + +<dt><tt>d</tt></dt> + +<dd>The DST code for Canada encodes the state for all +provinces.</dd> + +<dt><tt>dut</tt></dt> + +<dd>The DUT sign and magnitude shows the current UT1 offset +relative to the displayed UTC time, in deciseconds.</dd> + +<dt><tt>lset</tt></dt> + +<dd>Before the clock is set, the interval since last set is the +number of minutes since the program was started; after the clock is +set, this is number of minutes since the time was last verified +relative to the broadcast signal.</dd> + +<dt><tt>agc</tt></dt> + +<dd>The audio gain shows the current codec gain setting in the +range 0 to 255. Ordinarily, the receiver audio gain control or IRIG +level control should be set for a value midway in this range.</dd> + +<dt><tt>rfrq</tt></dt> + +<dd>The current radio frequency, if the CI-V interface is active, +or 'X' if not.</dd> + +<dt><tt>bcnt</tt></dt> + +<dd>The number of format A bursts received during the most recent +minute bursts were received.</dd> + +<dt><tt>dist</tt></dt> + <dd>The minimum decoding distance determined during the most recent minute bursts were received.</dd> -<dt><tt>tsmp</tt> +<dt><tt>tsmp</tt></dt> + <dd>The number of timestamps determined during the most recent minute bursts were received.</dd> </dl> @@ -465,12 +519,11 @@ minute bursts were received.</dd> <h4>Modes</h4> <p>The <tt>mode</tt> keyword of the <tt>server</tt> configuration -command specifies the ICOM ID select code. A missing or zero argument -disables the CI-V interface. Following are the ID select codes for the -known radios. - -<p><table cols=6 width=100%> +command specifies the ICOM ID select code. A missing or zero +argument disables the CI-V interface. Following are the ID select +codes for the known radios.</p> +<table cols="6" width="100%"> <tr> <td>Radio</td> <td>Hex</td> @@ -542,50 +595,63 @@ known radios. <td>0x2a</td> <td>42</td> </tr> - </table> <h4>Fudge Factors</h4> <dl> +<dt><tt>time1 <i>time</i></tt></dt> + +<dd>Specifies the propagation delay for CHU (45:18N 75:45N), in +seconds and fraction, with default 0.0.</dd> -<dt><tt>time1 <I>time</I></tt></dt> -<dd>Specifies the propagation delay for CHU (45:18N 75:45N), in seconds -and fraction, with default 0.0.</dd> +<dt><tt>time2 <i>time</i></tt></dt> -<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>stratum <i>number</i></tt></dt> -<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> +<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> + +<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> +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> +<dd>Enable verbose <tt>clockstats</tt> recording if set.</dd> </dl> <h4>Additional Information</h4> -<A HREF="refclock.htm">Reference Clock Drivers</A> -<br><A HREF="audio.htm">Reference Clock Audio 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></a></body></html> +<a href="refclock.htm">Reference Clock Drivers</a> <br> +<a href="audio.htm">Reference Clock Audio Drivers</a> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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 index 8a11a02..def05f8 100644 --- a/contrib/ntp/html/driver9.htm +++ b/contrib/ntp/html/driver9.htm @@ -2,24 +2,21 @@ <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> + <TITLE>Magnavox MX4200 GPS Receiver</TITLE> </HEAD> <BODY> -<H3> -Magnavox MX4200 GPS Receiver</H3> +<H3>Magnavox MX4200 GPS Receiver</H3> <HR> -<H4> -Synopsis</H4> +<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> + +<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 @@ -32,8 +29,9 @@ Interfacing</A> page. 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/"><IMG align=left HEIGHT=143 WIDTH=180 +SRC="pic/9400n.jpg" ALT="Leica MX9400N Navigator"></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 @@ -44,32 +42,30 @@ Leica MX9400N Navigator. <P> -<H4> -Operating Modes</H4> +<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. +3D Nav" mode, where latitude, longitude, elevation and time are +calculated for a fixed station. An average position is calculated from +this data. After 24 hours, the receiver is placed into a "Known +Position" mode, initialized with the calculated position, and then +solves only for time. <P>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> + +<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> +<H4>Fudge Factors</H4> <DL> <DT> diff --git a/contrib/ntp/html/exec.htm b/contrib/ntp/html/exec.htm index 756d987..464b3af 100644 --- a/contrib/ntp/html/exec.htm +++ b/contrib/ntp/html/exec.htm @@ -1,292 +1,393 @@ -<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> - +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" &lt;html> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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" alt="gif"><a href= +"pictures.htm">from <i>Alice's Adventures in Wonderland</i>, Lewis +Carroll</a> + +<p>The executive is the one on the left.<br clear="left"> +</p> + +<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.) +<p>The standard timescale used by most nations of the world is +Coordinated UniversalTime (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> + +<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.)</p> <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 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> <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. +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> + <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. +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> + +<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.</p> + +<h4>Security Issues</h4> + +<p>A reliable network time service requires provisions to prevent +accidental or malicious attacks on the servers and clients in the +network. Reliability requires that clients can determine that +received messages are authentic; that is, were actually sent by the +intended server and not manufactured or modified by an intruder. +Ubiquity requires that any client can verify the authenticity of +any server using only public information. This is especially +important in such ubiquitous network services as directory +services, cryptographic key management and time +synchronization.</p> + +<p>NTP includes provisions to cryptographically authenticate +individual servers using symmetric-key cryptography in which +clients authenticate servers using shared secret keys. However, the +secret keys must be distributed in advance using secure means +beyond the scope of the protocol. This can be awkward and fragile +with a large population of potential clients, possibly intruding +hackers.</p> + +<p>Modern public-key cryptography provides means to reliably bind +the server identification credentials and related public values +using public directory services. However, these means carry a high +computing cost, especially when large numbers of time-critical +clients are involved as often the case with NTP servers. In +addition, there are problems unique to NTP in the interaction +between the authentication and synchronization functions, since +each requires the other for success.</p> + +<p>The recent NTP Version 4 includes a revised security model and +authentication scheme supporting both symmetric and public-key +cryptography. The public-key variant is specially crafted to reduce +the risk of intrusion, minimize the consumption of processor +resources and minimize the vulnerability to hacker attack.</p> <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. +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> + +<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> + +<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.</p> <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. +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> + +<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> + +<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> +falsetickers</i>. Only the truechimers are used to adjust the +system clock.</p> <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. +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> + +<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> <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. +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.</p> <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 +<li> +<p>Cristian, F. Probabilistic clock synchronization. In Distributed +Computing 3, Springer Verlag, 1989, 146-158.</p> +</li> + +<li> +<p>Digital Time Service Functional Specification Version T.1.0.5. +DigitalEquipment Corporation, 1989.</p> +</li> + +<li> +<p>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 +Technical Committee Newsletter 6, NoSI-2 (June 1984), 7-15. Also +in: Proc. Summer 1984 USENIX (Salt Lake City, June 1984).</p> +</li> + +<li> +<p>Kopetz, H., and W. Ochsenreiter. Clock synchronization in +distributed real-time systems. IEEE Trans. Computers C-36, 8 +(August 1987), 933-939.</p> +</li> + +<li> +<p>Lamport, L., and P.M. Melliar-Smith. Synchronizing clocks in the +presence of faults. JACM 32, 1 (January 1985), 52-78.</p> +</li> + +<li> +<p>Marzullo, K., and S. Owicki. Maintaining the time in a +distributed system. ACM Operating Systems Review 19, 3 (July 1985), +44-54.</p> +</li> + +<li> +<p>Mills, D.L. Adaptive hybrid clock discipline algorithm for the +Network Time Protocol. <i>IEEE/ACM Trans. Networking 6, 5</i> +(October 1998), 505-514.</p> +</li> + +<li> +<p>Mills, D.L. Improved algorithms for synchronizing computer +network clocks. <i>IEEE/ACM Trans. Networks 3, 3</i> (June 1995), +245-254.</p> +</li> + +<li> +<p>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.</p> +</li> + +<li> +<p>Mills, D.L. Modelling and analysis of computer network clocks. +Electrical Engineering Department Report 92-5-2, University of +Delaware, May 1992, 29 pp.</p> +</li> + +<li> +<p>NIST Time and Frequency Dissemination Services. NBS Special Publication432 (Revised 1990), National Institute of Science and -Technology, U.S. Department of Commerce, 1990.</li> +Technology, U.S. Department of Commerce, 1990.</p> +</li> -<p><li>Schneider, F.B. A paradigm for reliable clock synchronization. +<li> +<p>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> +University, February 1986.</p> +</li> + +<li> +<p>Srikanth, T.K., and S. Toueg. Optimal clock synchronization. +JACM 34, 3 (July 1987), 626-645.</p> +</li> + +<li> +<p>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.</p> +</li> +</ol> -<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> +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"home"></a> -</ol> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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 index d44d243..01c0149 100644 --- a/contrib/ntp/html/extern.htm +++ b/contrib/ntp/html/extern.htm @@ -1,40 +1,108 @@ -<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> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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> + +<p>When external clocks are used in conjunction with NTP service, +some way needs to be provided for the external clock driver and NTP +daemon <tt>ntpd</tt> to communicate and determine which discipline +is in control. This is necessary in order to provide backup, for +instance if the external clock or protocol were to fail and +synchronization service fall back to other means, such as a local +reference clock or another NTP server. In addition, when the +external clock and driver are in control, some means needs to be +provided for the clock driver to pass on status information and +error statistics to the NTP daemon.</p> + +<p>Control and monitoring functions for the external clock and +driver are implemented using the <a href="driver1.htm">Local Clock +(type 1) driver</a> and the <tt>ntp_adjtime()</tt> system call. +This system call is implemented by special kernel provisions +included in the kernel of several operating systems, including +Solaris, Tru64, FreeBSD and Linux, and possibly others. When the +external clock is disabled or not implemented, the system call is +used to pass time and frequency information, as well as error +statistics, to the kernel. Besides disciplining the system time, +the same interface can be used by other applications to determine +the operating parameters of the discipline.</p> + +<p>When the external clock is enabled, <tt>ntpd</tt> does not +discipline the system clock, nor does it maintain the error +statistics. In this case, the external clock and driver do this +using mechanisms unknown to <tt>ntpd</tt>; however, in this case +the kernel state variables are retrieved at 64-s intervals by the +Local Clock driver and used by the clock selection and mitigation +algorithms to determine the system variables presented to other NTP +clients and peers. In this way, downstream clients and servers in +the NTP subnet can make an intelligent choice when more than one +server is available.</p> + +<p>In order to implement a reliable mitigation between ordinary NTP +sources and the external clock source, a protocol is necessary +between the local clock driver and the external clock driver. This +is implemented using Boolean variables and certain bits in the +kernel clock status word. The Boolean variables include the +following:</p> + +<p>ntp__enable. set/reset by enable command. enables ntp clock +discipline</p> + +<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> + +<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> + +<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.</p> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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 index 80274535..6bf64fc 100644 --- a/contrib/ntp/html/gadget.htm +++ b/contrib/ntp/html/gadget.htm @@ -8,104 +8,41 @@ Gadget Box PPS Level Converter and CHU Modem <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. +<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 <a href=driver7.htm>Radio CHU Audio Demodulator/Decoder</a> driver. + +<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. + +<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>Following is a list of files included in this archive. All files are in PostScript, except the <tt>README</tt> and <tt>gadget.lst</tt> files, which are in ASCII. The files <tt>gadget.s01, gadget.s02</tt> and <tt>gadget.lst</tt> were generated using the Schema schematic-capture program from Omation. The printed-circuit files <tt>*.lpr</tt> 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> +<p><tt>README</tt> - helpful information +<br><tt>gadget.s01</tt> - circuit schematic +<br><tt>gadget.s02</tt> - minibox assembly drawing +<br><tt>gadget.lst</tt> - net list, pin list, parts list, etc. +<br><tt>gen0102.lpr</tt> - pcb x-ray diagram +<br><tt>art01.lpr</tt> - pcb artword side 1 +<br><tt>art02.lpr</tt> - pcb artwork side 2 +<br><tt>adt0127.lpr</tt> - pcb assembly drawing +<br><tt>dd0124.lpr</tt> - pcb drill drawing +<br><tt>sm0228.lpr</tt> - pcb solder mask (side 2) +<br><tt>sst0126.lpr</tt> - 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/genkeys.htm b/contrib/ntp/html/genkeys.htm new file mode 100644 index 0000000..33e99ef --- /dev/null +++ b/contrib/ntp/html/genkeys.htm @@ -0,0 +1,181 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>ntp-genkeys - generate public and private keys</title> +</head> +<body> +<h3><tt>ntp-genkeys</tt> - generate public and private keys</h3> + +<img align="left" src="pic/alice23.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>Alice holds the key.<br clear="left"> +</p> + +<hr> +<h4>Synopsis</h4> + +<tt>ntp-genkeys</tt> + +<h4>Description</h4> + +<p>This program generates random keys used by either or both the +NTPv3/NTPv4 symmetric key or the NTPv4 public key (Autokey) +cryptographic authentication schemes. By default the program +generates the <tt>ntp.keys</tt> file containing 16 random symmetric +keys. In addition, if the <tt>rsaref20</tt> package is configured +for the software build, the program generates cryptographic values +used by the Autokey scheme. These values are incorporated as a set +of three files, <tt>ntpkey</tt> containing the RSA private key, +<tt>ntpkey_<i>host</i></tt> containing the RSA public key, where +<tt><i>host</i></tt> is the DNS name of the generating machine, and +<tt>ntpkey_dh</tt> containing the parameters for the Diffie-Hellman +key-agreement algorithm. All files and are in printable ASCII +format. A timestamp in NTP seconds is appended to each. Since the +algorithms are seeded by the system clock, each run of this program +produces a different file and file name.</p> + +<p>The <tt>ntp.keys</tt> file contains 16 MD5 keys. Each key +consists of 16 characters randomized over the ASCII 95-character +printing subset. The file is read by the daemon at the location +specified by the <tt>keys</tt> configuration file command and made +visible only to root. An additional key consisting of a easily +remembered password should be added by hand for use with the <tt> +ntpq</tt> and <tt>ntpdc</tt> programs. The file must be distributed +by secure means to other servers and clients sharing the same +security compartment. While the key identifiers for MD5 and DES +keys must be in the range 1-65534, inclusive, the <tt> +ntp-genkeys</tt> program uses only the identifiers from 1 to 16. +The key identifier for each association is specified as the key +argument in the <tt>server</tt> or peer configuration file +command.</p> + +<p>The <tt>ntpkey</tt> file contains the RSA private key. It is +read by the daemon at the location specified by the <tt> +privatekey</tt> argument of the <tt>crypto</tt> configuration file +command and made visible only to root. This file is useful only to +the machine that generated it and never shared with any other +daemon or application program.</p> + +<p>The <tt>ntpkey_<i>host</i></tt> file contains the RSA public +key, where <tt><i>host</i></tt> is the DNS name of the host that +generated it. The file is read by the daemon at the location +specified by the <tt>publickey</tt> argument to the <tt>server</tt> +or <tt>peer</tt> configuration file command. This file can be +widely distributed and stored without using secure means, since the +data are public values.</p> + +<p>The <tt>ntp_dh</tt> file contains two Diffie-Hellman parameters: +the prime modulus and the generator. The file is read by the daemon +at the location specified by the <tt>dhparams</tt> argument of the +<tt>crypto</tt> configuration file command. The file can be +distributed by insecure means to other servers and clients sharing +the same key agreement compartment, since the data are public +values.</p> + +<p>The file formats begin with two lines, the first containing the +generating system DNS name and the second the datestamp. Lines +beginning with <tt>#</tt> are considered comments and ignored by +the daemon. In the <tt>ntp.keys</tt> file, the next 16 lines +contain the MD5 keys in order. If necessary, this file can be +further customized by an ordinary text editor. The format is +described in the following section. In the <tt>ntpkey</tt> and <tt> +ntpkey_<i>host</i></tt> files, the next line contains the modulus +length in bits followed by the key as a PEM encoded string. In the +<tt>ntpkey_dh</tt> file, the next line contains the prime length in +bytes followed by the prime as a PEM encoded string, and the next +and final line contains the generator length in bytes followed by +the generator as a PEM encoded string.</p> + +<p>Note: See the file <tt>./source/rsaref.h</tt> in the <tt> +rsaref20</tt> package for explanation of return values, if +necessary.</p> + +<h4>Symmetric 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> + +<p><i><tt>keyno type key</tt></i></p> + +<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> + +<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.</p> + +<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> + +<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> + +<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> + +<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> + +<p>Note that the keys used by the <tt>ntpq</tt> and <tt>ntpdc</tt> +programs are checked against passwords requested by the programs +and entered by hand, so it is generally appropriate to specify +these keys in ASCII format.</p> + +<h4>Files</h4> + +The RSA Laboratories package <tt>rsaref20</tt> of cryptographic +routines is necessary in order to build and use this program. + +<h4>Bugs</h4> + +It can take quite a while to generate the RSA public/private key +pair and Diffie-Hellman parameters, from a few seconds on a modern +workstation to several minutes on older machines. + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/hints.htm b/contrib/ntp/html/hints.htm index 066b4db..fcb533b 100644 --- a/contrib/ntp/html/hints.htm +++ b/contrib/ntp/html/hints.htm @@ -2,7 +2,13 @@ Hints and Kinks </title></head><body><h3> Hints and Kinks -</h3><hr> +</h3> + +<img align=left src=pic/alice35.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm> +from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>Mother in law has all the answers. +<br clear=left><hr> <p>This is an index for a set of troubleshooting notes contained in individual text files in the <tt>./hints</tt> directory. They were @@ -19,7 +25,7 @@ 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. +advise. See the <a href=http:hints>directory listing</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> diff --git a/contrib/ntp/html/hints/freebsd b/contrib/ntp/html/hints/freebsd new file mode 100644 index 0000000..ef84732 --- /dev/null +++ b/contrib/ntp/html/hints/freebsd @@ -0,0 +1,15 @@ +If you are compiling under FreeBSD and see messages in the syslogs that +indicate that the ntpd process is trying to use unavailable sched_ +calls, it means you are running a kernel that does not have the POSIX +scheduling calls enabled. + +You have two choices: + +- Ignore the messages + +- Generate a new kernel, where the kernel configuration file contains + the lines: + + options "P1003_1B" + options "_KPOSIX_PRIORITY_SCHEDULING" + options "_KPOSIX_VERSION=199309L" diff --git a/contrib/ntp/html/hints/vxworks.htm b/contrib/ntp/html/hints/vxworks.htm new file mode 100644 index 0000000..b6fae80 --- /dev/null +++ b/contrib/ntp/html/hints/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/hints/winnt.htm b/contrib/ntp/html/hints/winnt.htm index 06c0e41..2b675ed 100644 --- a/contrib/ntp/html/hints/winnt.htm +++ b/contrib/ntp/html/hints/winnt.htm @@ -1,5 +1,8 @@ +<!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.7 [en] (WinNT; I) [Netscape]"> <title>NTP on Windows NT</title> </head> <body> @@ -8,10 +11,22 @@ NTP 4.x for Windows NT</h1> <h2> +Do not try to compile NTP-4.0.99i under WINNT, it will not work. +Fixed NTP-4.0.99i; look for next release to be functional. +Sven - May 11 2000 +</h2> + +<h2> +Download NTP-4.0.99g for the last stable WINNT port. +I am working on adapting the major changes starting with 99i +and getting things running again. Sven - April 25 2000 +</h2> + +<h2> Introduction</h2> The NTP 4 distribution runs as service on (i386) Windows NT 4.0 and Windows -2000. The binaries now work on all dual processor systems (mostly Dell) -that have been tested. This port has not been tested on the Alpha platform. +2000. The binaries work on dual processor systems. This port has not been +tested on the Alpha platform. <p>Refer to System Requirements and Instructions for how to compile the program. <h2> @@ -72,9 +87,6 @@ Compiling Requirements</h2> <tt>Microsoft Visual C++ 6.0</tt></li> <li> -<tt>Perl5 </tt><a href="http://www.perl.org">http://www.perl.org</a></li> - -<li> Some version of the archiving program <tt>ZIP</tt>.</li> </ul> @@ -83,10 +95,6 @@ Compiling Instructions</h2> <ol> <li> -Install Perl and set the PERL environment variable to your Perl directory -(e.g. C:\PERL)</li> - -<li> Unpack the NTP-4.x.tar.gz</li> <li> @@ -144,9 +152,9 @@ is no reason that the system clock should be that much off during bootup if 'ntpd' was running before, you may wish to override this default and/or pass other command line directives. <p>Use the registry editor to edit the value for the ntpd executable under -LocalMachine\System\CurrentControlSet\Services\NetworkTimeProtocol. -<p>Add the -g option behind "%INSTALLDIR>\ntpd". This will force NTP to -accept large time errors (including 1.1.1980 00:00) +LocalMachine\System\CurrentControlSet\Services\NTP. +<p>Add the -g option to the ImagePath key, behind "%INSTALLDIR>\ntpd.exe". +This will force NTP to accept large time errors (including 1.1.1980 00:00) <h2> Bug Reports</h2> Send bug reports to <a href="news://comp.protocols.time.ntp">news://comp.protocols.time.ntp</a> @@ -155,6 +163,17 @@ and Sven_Dietrich@Trimble.COM Change Log</h2> <h3> +Last revision 16 February 1999 Version 4.0.99e.</h3> +<b>by Sven Dietrich (sven_dietrich@trimble.com)</b> +<p><b>Significant Changes:</b> +<ul> +<li> +Perl 5 is no longer needed to compile NTP. The configuration script which +creates version.c with the current date and time was modified by Frederick +Czajka [w2k@austin.rr.com] so that Perl is no longer required.</li> +</ul> + +<h3> Last revision 15 November 1999 Version 4.0.98f.</h3> <b>by Sven Dietrich (sven_dietrich@trimble.com)</b> <p><b>Significant Changes:</b> diff --git a/contrib/ntp/html/howto.htm b/contrib/ntp/html/howto.htm index 7d03df9..6e08242 100644 --- a/contrib/ntp/html/howto.htm +++ b/contrib/ntp/html/howto.htm @@ -2,7 +2,12 @@ How to Write a Reference Clock Driver </title></head><body><h3> How to Write a Reference Clock Driver -</h3><hr> +</h3> + +<img align=left src=pic/pogo4.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>Pogo</i>, Walt Kelly</a> + +<p>You need a little magic. +<br clear=left><hr> <h4>Description</h4> diff --git a/contrib/ntp/html/index.htm b/contrib/ntp/html/index.htm index c5cca91..680cec8 100644 --- a/contrib/ntp/html/index.htm +++ b/contrib/ntp/html/index.htm @@ -1,201 +1,261 @@ -<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 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm"><i>P.T. Bridgeport +Bear</i>; from <i>Pogo</i>, Walt Kelly</a> + +<p>Pleased to meet you.<br clear="left"> +</p> + +<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 +accuracies typically within a millisecond on LANs and up to a few +tens of milliseconds on WANs relative to Coordinated Universal Time +(UTC) via a Global Positioning Service (GPS) receiver, for example. +Typical NTP configurations utilize multiple redundant servers and +diverse network paths in order to achieve high accuracy and +reliability. Some configurations include cryptographic +authentication to prevent accidental or malicious protocol attacks +and some provide automatic server discovery using IP multicast.</p> + +<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 how NTP reckons the time can be +found in the <a href="leap.htm">NTP Timescale and Leap Seconds</a> +page. 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. Additional information can be +found at the NTP web site <a href="http://www.ntp.org"> +www.ntp.org</a>. Please send bug reports to <a href= +"mailto:bugs@mail.ntp.org"><bugs@mail.ntp.org></a>.</p> + +<h4>Building and Installing NTP</h4> + +NTP supports Unix and Windows (NT4 and 2000) systems. 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. Note that support for strong cryptography requires +cryptographic libraries not included in this distribution. + +<p>Bringing up a NTP primary server requires a radio or satellite +receiver or modem. It is also possible to configure a machine on an +isolated network with the local clock driver and have other +machines synchronize to it. The distribution includes hardware +drivers for the local clock and over three dozen radio clocks and +modem services. A list of supported drivers is given in the <a +href="refclock.htm">Reference Clock Drivers</a> page. For most +popular workstations marketed by Digital/Compaq, 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.</p> + +<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> + +<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 configuration data can be +specified entirely on the command line for the <a href="ntpd.htm"> +<tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a>.</p> + +<p>The most important factor in providing accurate, reliable time +is the selection of modes and servers to be used in the +configuration file. A discussion on the available modes is on the +<a href="assoc.htm">Association Management</a> page. 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> + +<p>The NTP subnet in late 2000 includes over a hundred public +primary (stratum 1) servers synchronized directly to UTC by radio, +satellite or modem and located in every continent of the globe, +including Antarctica. Normally, client workstations and servers +with a relatively small number of clients do not synchronize to +primary servers. There are over a hundred 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.</p> + +<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> +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>.</p> + +<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=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> +<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> + +<li><a href="genkeys.htm"><tt>ntp-genkeys</tt> - generate public +and private keys</a></li> </ul> -<H4>Supporting Documentation</H4> +<h4>Supporting Documentation</h4> <ul> +<li><a href="http://www.eecis.udel.edu/~mills/ntp.htm">NTP Project +and 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="leap.htm">NTP Timescale and Leap Seconds</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=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> +<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> +<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=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> +<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">Kernel Model for Precision +Timekeeping</a></li> + +<li><a href="kernpps.htm">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> +<hr> +<center><img src="pic/pogo1a.gif" alt="gif"></center> + +<br> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/kern.htm b/contrib/ntp/html/kern.htm index b1ee383..4139fb2 100644 --- a/contrib/ntp/html/kern.htm +++ b/contrib/ntp/html/kern.htm @@ -1,51 +1,122 @@ -<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 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Kernel Model for Precision Timekeeping</title> +</head> +<body> +<h3>Kernel Model for Precision Timekeeping</h3> + +<hr> +<img align="left" src="pic/alice61.gif" alt="gif"> <a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>Exploding kernel<br clear="left"> +</p> + +<hr> +<p>The technical report [2], which is a major revision and update +of an earlier report [3], describes an engineering model for a +precision time-of-day function for a generic operating system. The +model is based on the principles of disciplined oscillators using +phase-lock loops (PLL) and frequency-lock loops (FLL) often found +in the engineering literature. The model uses a hybrid PLL/FLL +discipline algorithm implemented in the kernel. The hybrid loop +provides automatic time and frequency steering with update +intervals from a few seconds to over one day.</p> + +<p>The hybrid PLL/FLL has been implemented in the Unix kernels for +several operating systems, including FreeBSD and Linux and those +made by Sun Microsystems, Digital/Compaq and Hewlett Packard. The +modifications are currently included in the licensed kernels for +Digital Unix 4.0 (aka Tru64) and Sun Solaris 2.8. Since the +modifications involve proprietary kernel interface code, they +cannot be provided for other licensed kernels directly. Inquiries +should be directed to the manufacturer's representatives. The +software and documentation, including a simulator with code +segments almost identical to the implementations, but not involving +licensed code, is called <tt>nanokernel.tar.gz</tt> and available +via the web at <a href="http://www.ntp.org">www.ntp.org</a> or by +anonymous FTP from ftp.udel.edu in the <tt>pub/ntp/software</tt> +directory.</p> + +<p>Recently [1], the model has been re-implemented to support a +nanosecond system clock. The <tt>/usr/include/sys/timex.h</tt> +header file defines the applications programming interface (API) +routines and data structures. Implementations are available for +Linux, FreeBSD, SunOS and Tru64; however, only the Linux and +FreeBSD implementations, which are included in recent system +versions, are directly available. The software and documentation, +including a simulator with code segments almost identical to the +implementations, but not involving licensed code, is called <tt> +nanokernel.tar.gz</tt> and available via the web at <a href= +"http://www.ntp.org">www.ntp.org</a> or by anonymous FTP from +ftp.udel.edu in the <tt>pub/ntp/software</tt> directory.</p> + +<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 +described in the <a href="pps.htm">Pulse-per-second (PPS) Signal +Interfacing</a> page. The model incorporates a generic system call +interface for use with the NTP or similar time synchronization +protocol. The NTP software daemons for Version 3 <tt>xntpd</tt> and +Version 4 <tt>ntpd</tt> use this API 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 +<tt>timex.h</tt>, <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> +<tt>ntp_adjtime()</tt>, which provides a means to adjust kernel +variables, including the current time and frequency offsets.</p> + +<p>These kernel modifications are normally used in conjunction with +a kernel hardware interface such as described in the <a href= +"kernpps.htm">Kernel Programming Interface for Precision Time +Signals</a> page.</p> + +<h4>References</h4> + +<ol> + +<li><p>Mills, D.L., and P.-H. Kamp. The nanokernel. <i>Proc. Precision +Time and Time Interval (PTTI) Applications and Planning Meeting</i> +(Reston VA, November 2000). Paper: <a href= +"database/papers/nano/nano2.ps">PostScript</a> | <a href= +"http://www.eecis.udel.edu/~mills/database/papers/nano/nano2.pdf"> +PDF</a>, Slides: <a href= +"http://www.eecis.udel.edu/~mills/database/brief/nano/nano.htm"> +HTML</a> | <a href= +"http://www.eecis.udel.edu/~mills/database/brief/nano/nano.ps"> +PostScript</a> | <a href= +"http://www.eecis.udel.edu/~mills/database/brief/nano/nano.pdf"> +PDF</a> | <a href= +"http://www.eecis.udel.edu/~mills/database/brief/nano/nano.ppt"> +PowerPoint</a></p></li> + +<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="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></p></li> + +<li><p>Mills, D.L. A kernel model for precision timekeeping. Network +Working Group Report RFC-1589, University of Delaware, March 1994. +31 pp. <a href= +"http://www.eecis.udel.edu/~mills/database/rfc/rfc1589.txt"> +ASCII</a></p></li> +</ol> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/kernpps.htm b/contrib/ntp/html/kernpps.htm index fe003f7..d9c9643 100644 --- a/contrib/ntp/html/kernpps.htm +++ b/contrib/ntp/html/kernpps.htm @@ -1,25 +1,23 @@ <html><head><title> -A Kernel Programming Interface for Precision Time Signals +Kernel Programming Interface for Precision Time Signals Network Performance Evaluation </title></head><body><h3> -A Kernel Programming Interface for Precision Time Signals +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. +<p>The technical report [1] describes a proposed application programming interface (API) for external precision time signals, such as the pulse-per-second (PPS) signal generated by some radio clocks and cesium oscillators. The report 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. + +<p>Support for this API has been implemented in the NTP Version 4 software distribution. The <tt>/usr/include/sys/timepps.h</tt> header file defines the API interface routines and data structures. The API obsoletes previous APIs based on the <tt>tty_clock</tt> and <tt>ppsclock</tt> line disciplines and streams modules, which are no longer supported. The API used by the <a href=driver22.htm>PPS Clock Discipline</a> driver (type 22) to support PPS signals via either a serial port or parallel port, depending on the operating system. The API is supported in stock FreeBSD from 3.4 and with the addition of the <tt>PPSkit</tt> kernel software in Linux. Limited support for Solaris from 2.8 is available using the <tt>timepps.h.solaris</tt> header file included in this distribution. Copy this file to <tt>/usr/include/sys</tt> before configuring the distributution. + +<p>The API is normally used in conjunction with the precision time kernel modifications described in the <a href=kern.htm>Kernel Model for Precision Timekeeping</a> page. + +<h4>Reference</h4> + +<ol> + +<p><li>Mogul, J., D. Mills, J. Brittenson, J. Stone and U. Windl. Pulse-per-second API for Unix-like operating systems, version 1. Request for Comments RFC-2783, Internet Engineering Task Force, March 2000, 31 pp. <a href=http://www.eecis.udel.edu/~mills/database/rfc/rfc2783.txt>ASCII</a> + +</ol> <hr><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> diff --git a/contrib/ntp/html/ldisc.htm b/contrib/ntp/html/ldisc.htm index 5dd7326..e6a026a 100644 --- a/contrib/ntp/html/ldisc.htm +++ b/contrib/ntp/html/ldisc.htm @@ -1,4 +1,3 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> <html><head><title> Line Disciplines and Streams Modules </title></head><body><h3> @@ -7,125 +6,66 @@ Line Disciplines and Streams Modules <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. +<p>Most radio and modem clocks used for a primary (stratum-1) NTP server utilize serial ports operating at speeds of 9600 baud or greater. The intrinsic delay and jitter contributed by the serial port hardware and software driver can accumulate up to a millisecond in newer Unix systems and tens of milliseconds in older ones. In order to reduce the effects of delay and jitter, a set of special line disciplines, stream modules and operating system calls (ioctls) can be configured in some Unix kernels. These routines intercept special characters or signals provided by the radio or modem clock and save a timestamp for later processing. + +<p>The routines provide two important functions. Some insert a timestamp in the receive data stream upon occurance of a designated character or characters at the serial interface. This can be used to timestamp an on-time character produced by a radio clock, for example. Other routines support an application program interface for pulse-per-second (PPS) signals generated by some radio clocks and laboratory instruments. These routines are normally accessed through the PPSAPI application program interface described below. + +<p>The routines can be compiled in the kernel in older BSD-derived systems, or installed as System V streams modules and either compiled in the kernel or dynamically loaded when required. In either case, they require minor changes in some kernel files and in the NTP daemon <tt>ntpd</tt>. The streams modules can be pushed and popped from the streams stack using conventional System V streams program primitives. Note that some Unix kernels do not support line disciplines and some do not support System V streams. The routines described here are known to work correctly with the Unix kernels called out in the descriptions, but have not been tested for other kernels. + +<h4>PPSAPI Application Program Interface</h4> + +<p>Pulse-per-second (PPS) signals are normally processed as described in the <a href=pps.htm>Pulse-per-second (PPS) Signal Interfacing</a> page. The <a href=driver22.htm>PPS Clock Discipline</a> driver uses the PPSAPI application program interface to capture PPS signal transitions used to fine-tune the system clock. This interface, defined in RFC-2783, is the only PPS interface supported in NTP. While older PPS interfaces based on the ioctls described below continue to be supported, they are used only in the special header file <t>/usr/include/sys/timepps.h</tt>, which implements the PPSAPI specific to each archeticture and operating system. + +<p>It is the intent of the evolving design to remove all PPS support from the various clock drivers and utilize only the PPS driver for PPS support. This allows the required sanity checks and signal grooming to be provided and maintained in one place and avoids cluttering up the drivers with duplicate functionality. Since the PPS signal samples are processed by the entire suite of NTP grooming, selection and clustering algorithms, noisy PPS signals and signals outside specific time and frequency tolerances are excluded. + +<p>The PPSAPI interface provides the following functions: <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. +<dt><tt>time_pps_create</tt> +<dd>Creates a PPS interface instance and returns a handle to it.</dd> + +<dt><tt>time_pps_destroy</tt> +<dd>Destroys a PPS interface and returns the resources used.</dd> + +<dt><tt>time_pps_setparams</tt> +<dd>Sets the parameters associated with a PPS interface instance, including offsets to be automatically added to captured timestamps.</dd> + +<dt><tt>time_pps_getparams</tt> +<dd>Returns the parameters associated with a PPS interface instance.</dd> + +<dt><tt>time_pps_getcap</tt> +<dd>Returns the capabilities of the current interface and kernel implementation.</dd> + +<dt><tt>time_pps_fetch</tt> +<dd>Returns the current timestamps associated with a PPS interface instance in either nanoseconds and nanoseconds (Unix <tt>timespec</tt>) or seconds and fraction (NTP) format.</dd> + +<dt><tt>time_pps_kcbind</tt> +<dd>If kernel PPS processing is supported, this binds the support to the associated PPS interface instance.</dd> </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 +<p>The entire PPS interface functionality is currently provided by inline code in the <tt>timepps.h</tt> header files implemented for SunOS, Solaris, FreeBSD, Linux and Tru64. While not all implementations support the full PPSAPI specification, they do support all the functions required for the PPS driver. The FreeBSD, Linux and Solaris implementations can be used with the stock kernels provided with those systems; however, the Tru64 and SunOS kernels require additional functions not provided in the stock kernels. Solaris users are cautioned that these ioctls function improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. + +<h4><tt>tty_clk</tt> Line Discipline/Streams Module</h4> + +<p>This routine intercepts characters received from the serial port and passes unchanged all except a set of designated characters to the generic serial port discipline. For each of the exception characters, the character is inserted in the receiver buffer followed by a local timestamp in Unix <tt>timeval</tt> format. Both <tt>select()</tt> and <tt>SIGIO</tt> are supported by the routine. Support for this routine is automatically detected during the NTP build process and interface code compiled as necessary. + +<p>There are two versions of the <tt>tty_clk</tt> routine. The <tt>tty_clk.c</tt> line discipline is designed for older BSD systems and is compiled in the kernel. The <tt>tty_clk_STREAMS.c</tt> is designed for System V streams, in which case it can be either compiled in the kernel or dynamically loaded. Since these programs are small, unobtrusive, and do nothing unless specifically enabled by an application program, it probably doesn't matter which version is chosen. Instructions on how to configure and build a kernel supporting either of these routines is in the <tt>README</tt> file in the <tt>./kernel</tt> directory. + +<p>The <tt>tty_clk</tt> routine defines a new ioctl <tt>CLK_SETSTR</tt>, which takes a pointer to a string of no more than 32 characters. Until the first <tt>CLK_SETSTR</tt> is performed, the routine will simply pass through characters. Once it is passed a string by <tt>CLK_SETSTR</tt>, any character in that string will be immediately followed by a timestamp in Unix <tt>timeval</tt> format. You can change the string whenever you want by doing another <tt>CLK_SETSTR</tt>. The character must be an exact, 8 bit match. The character '\000' cannot, be used, as it is the string terminator. Passing an empty string to <tt>CLK_SETSTR</tt> turns off timestamping. Passing <tt>NULL</tt> may produce surprising results. + +<p><h4><tt>TIOCDCDTIMESTAMP</tt> ioctl in FreeBSD</h4> + +<p>This ioctl is included in FreeBSD 2.2 and later. It causes a timestamp to be inserted in the serial port receive data stream when the data carrier detect (DCD) signal is asserted. This is useful for those radio clocks that indicate the on-time epoch by means of a modem control signal. It is not recommended that this be used for PPS timestamps, as this function is available using the PPS application program interface included in FreeBSD 3.4 and later. + +<p>The <tt>TIOCDCDTIMESTAMP</tt> ioctl() is detected and compiled automatically on FreeBSD systems if available. With FreeBSD 2.2 the measured delay between activation of the DCD signal and the time the timestamp is captured on a 66MHz 486DX2 is 19 <font face=Symbol>m</font>s and on a 100MHz Pentium is 6 <font face=Symbol>m</font>s. + +<h4><tt>ppsclock</tt>Streams Module</h4> + +<p>This routine is a streams module which causes a timestamp to be captured when the DCD signal is asserted. It is normally used in connection with a PPS signal generated by some radio clocks. However, it is normally used only by the PPSAPI interface and should be avoided in other contexts. Instructions on how to configure and build a kernel supporting either of these routines is in the <tt>README</tt> file in the <tt>./kernel</tt> directory. + +<p>The ppsclock streams module implements the <tt>CIOGETEV</tt> ioctl, which takes a pointer to the structure <pre> struct ppsclockev { @@ -134,28 +74,16 @@ struct ppsclockev { }; </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> +<p>The <tt>ppsclock</tt> module is pushed on the streams stack of the serial port connected to the DCD line. At each positive-going edge of the PPS signal, the routine latches the current local timestamp and increments a counter. At each <tt>CIOGETEV</tt> ioctl call, the current values of the timestamp and counter are returned in the <tt>ppsclockev</tt> structure. + +<p><h4><tt>TIOCSPPS</tt> and <tt>TIOCGETPPSEV</tt> ioctls in Solaris</h4> + +<p>These ioctls are included in Solaris 2.4 and later. They implement the same function as the <tt>ppsclock</tt> streams module, but are implemented as integrated system calls independent of the streams facility. They are normally used in connection with a pulse-per-second (PPS) signal generated by some radio clocks. However, these ioctls are normally used only by the PPSAPI interface and should be avoided in other contexts. See the Sun documentation for the calling sequence and return values. + +<p>Users are cautioned that these ioctls function improperly in Solaris versions prior to 2.8 with patch Generic_108528-02. + +<h4><tt>tty_chu</tt> Line Discipline/Streams Module (depredated)</h4> + +<p>This routine is a special purpose line discipline for receiving a special timecode broadcast by Canadian time and frequency standard station CHU. It has been removed from the distribution since its function has been replaced by the <a href=driver7.htm>Radio CHU Audio Demodulator/Decoder (type 7)</a> clock driver. + +<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/leap.htm b/contrib/ntp/html/leap.htm new file mode 100644 index 0000000..97bf8d4 --- /dev/null +++ b/contrib/ntp/html/leap.htm @@ -0,0 +1,250 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>NTP Timescale and Leap Seconds</title> +</head> +<body> +<h3>NTP Timescale and Leap Seconds</h3> + +<img align="left" src="pic/alice15.gif" alt="gif"><a href= +"pictures.htm">from <i>Alice's Adventures in Wonderland</i>, Lewis +Carroll</a> + +<p>The Mad Hatter and the March Hare are discussing whether the +Teapot serial number should have two or four digits.<br clear= +"left"> +</p> + +<hr> +<h4>Introduction</h4> + +<p>In the year 2001 the Network Time Protocol (NTP) has been in use +for over two decades and remains the longest running, continuously +operating application protocol in the Internet. There was some +concern, especially in government and financial institutions, that +NTP might cause Internet applications to misbehave in terrible ways +on the epoch of the new century, but this didn't happen. However, +how NTP reckons the time is important when considering the +relationship between NTP time and conventional civil time.</p> + +<p>This document presents an analysis of the NTP timescale, in +particular the metrication relative to the conventional civil +timescale and when the NTP timescale rolls over in 2036. These +issues are also important with respect to the Unix timescale, but +that rollover will not happen until 2038. This document does not +establish a standard, nor does it present specific algorithms which +metricate the NTP timescale with respect to other timescales.</p> + +<h4>The NTP Timescale</h4> + +<p>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 Coordinated Universal 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.</p> + +<p>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> + +<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 (also the rate of TAI) 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 +next era will begin when the seconds counter rolls over sometime in +2036. 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.</p> + +<p>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.</p> + +<p>With respect to the recent 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 current era 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 the year 1999, the NTP +timescale showed 3,155,673,599 and one second later on the first +second of the next century showed 3,155,673,600. Other than this +observation, the NTP timescale has no knowledge of or provision for +any of these eclectic seconds.</p> + +<h4>Conversion to Other Timescales</h4> + +<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 NTP representation and Unix +representation. Unix kernels implement the time of day function +using two 32-bit counters, one representing the signed seconds +since Unix life began and the other the microseconds or nanoseconds +of the second. In principle, the seconds counter will change sign +in 2038. How the particular Unix semantics interprets the counter +values is of concern, but is beyond the scope of discussion +here.</p> + +<p>While incorrect NTP time values are unlikely in a properly +configured subnet using strong cryptography, redundant sources and +diverse network paths, hazards remain due to incorrect software +external to NTP. These include the Unix kernel and library routines +which convert NTP time to and from Unix time and 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> + +<p>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> + +<p>Most computers include a time-of-year (TOY) clock chip which +maintains the time when the power is off. When the operating system +is booted, the system clock is set from the chip. As the chip does +not record the year, this value is determined from the datestamp on +a system configuration file. For this to be correct, the filestamp must by updated at least once each year. The NTP protocol specification +requires the apparent NTP time derived from external servers to be +compared to the 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 +grossly incorrect time values. When the system clock is synchronized to +NTP, the TOY chip is corrected to system time on a regular +basis.</p> + +<h4>Timescale Resolution and the Tick Interval</h4> + +<p>Modern computer clocks use a hardware counter to generate processor interrupts at tick intervals in the order of a few milliseconds. At each tick the processor increments the software system clock by the number of microseconds or nanoseconds in the tick. The software resolution of the system clock is defined as the tick interval. Most modern processors implement some kind of high resolution hardware counter that can be used to interpolate the interval between the most recent tick and the actual clock reading. The hardware resolution of the system clock is defined as the time between increments of this counter. However, the actual reading latency due to the kernel interface and interpolation code can range from a few tens of microseconds in older processors to under a microsecond in modern processors.</p> + +<p>System clock correctness principles require that clock readings must be always monotonically increasing, so that no two clock readings will be the same. As long as the reading latency exceeds the hardware resolution, this behavior is guaranteed. With reading latencies dropping below the microsecond in modern processors, the system clock in modern operating systems runs in nanoseconds, rather than the microseconds used in the original Unix kernel. With processor speeds exceeding 1 GHz, this assumption may be in jeopardy. + +<h4>Leap Seconds</h4> + +<p>The International Earth Rotation Service (IERS) uses +astronomical observations provided by USNO and other observatories +to determine UTC, which is syntonic (identical frequency) with TAI +but offset by a integral number of seconds. Starting from apparent +mean solar time as observed, the UT0 timescale is determined using +corrections for Earth orbit and inclination (the Equation of Time, +as used by sundials), the UT1 (navigator's) timescale by adding +corrections for polar migration and the UT2 timescale by adding +corrections for known periodicity variations. UTC is based on UT1, +which is presently fast relative to TAI by a fraction of a second +per year. Since the UTC timescale runs at the TAI rate, when the +magnitude of the UT1 correction approaches 0.5 second, a leap +second is inserted or deleted in the UTC timescale on the last day +of June or December.</p> + +<p>For the most precise coordination and timestamping of events +since 1972, it is necessary to know when leap seconds are +implemented in UTC and how the seconds are numbered. The insertion +of leap seconds into UTC is currently the responsibility of the +IERS, which is located at the Paris Observatory. As specified in +CCIR Report 517, a leap second is inserted following second +23:59:59 on the last day of June or December and becomes second +23:59:60 of that day. A leap second would be deleted by omitting +second 23:59:59 on one of these days, although this has never +happened. A table of historic leap seconds and the NTP time when +each occurred is available via FTP from any NIST NTP server.</p> + +<p>The UTC timescale thus ticks in standard (atomic) seconds and +was set to an initial offset of 10 seconds relative to TAI at 0h +MJD 41,318.0 according to the Julian calendar or 0h on 1 January +1972 according to the Gregorian calendar. This established the +first tick of the UTC era and its reckoning with these calendars. +Subsequently, the UTC timescale has marched backward relative to +the TAI timescale exactly one second on scheduled occasions +recorded in the institutional memory of our civilization. Note in +passing that leap second adjustments affect the number of seconds +per day and thus the number of seconds per year. Apparently, should +we choose to worry about it, the UTC clock, Gregorian calendar and +various cosmic oscillators will inexorably drift apart with time +until rationalized by some future papal bull.</p> + +<h4>Reckoning with NTP and UTC Leap seconds</h4> + +<p>The NTP timescale is based on the UTC timescale, but not +necessarily always coincident with it. At the first tick of the UTC +Era, which began at 0h on 1 January 1972 (MJD 41,318.0) the NTP +clock read 2,272,060,800, representing the number of standard +seconds since the beginning of the NTP era at 0h on 1 January 1900 +(MJD 15,021.0) according to the Gregorian calendar. The insertion +of leap seconds in UTC and subsequently into NTP does not affect +the UTC or NTP oscillator frequency, only the conversion between +NTP network time and UTC civil time. However, since the only +institutional memory available to NTP are the UTC broadcast +services, the NTP timescale is in effect reset to UTC as each +broadcast timecode is received. Thus, when a leap second is +inserted in UTC and subsequently in NTP, knowledge of all previous +leap seconds is lost.</p> + +<p>Another way to describe this is to say there are as many NTP +timescales as historic leap seconds. In effect, a new timescale is +established after each new leap second. Thus, all previous leap +seconds, not to mention the apparent origin of the timescale +itself, lurch forward one second as each new timescale is +established. If a clock synchronized to NTP in early 2001 was used +to establish the UTC epoch of an event that occurred in early 1972 +without correction, the event would appear 22 seconds late. +However, NTP primary time servers resolve the epoch using the +broadcast timecode, so that the NTP clock is set to the broadcast +value on the current timescale. As a result, for the most precise +determination of epoch relative to the historic Gregorian calendar +and UTC timescale, the user must subtract from the apparent NTP +epoch the offsets derived from the NIST table. This is a feature of +almost all present day time distribution mechanisms.</p> + +<p>The obvious question raised by this scenario is what happens +during the leap second when NTP time stops and the clock remains +unchanged. If the precision time kernel modifications have been +implemented, the kernel includes a state machine that implements +the actions required by the scenario. At the exact instant of the +leap, the logical clock is stepped backward one second. However, +the routine that actually reads the clock is constrained never to +step backwards, unless the step is significantly larger than one +second, which might occur due to explicit operator direction.</p> + +<p>In this design time stands still during the leap second, but is correct commencing with the next second. Since clock readings must be positive monotonic, the apparent time will increase by one nanosecond for each reading. At the end of the second the apparent time may be ahead of the actual time depending on how many times the clocks was read during the second. Eventually, the actual time will catch up with the apparent time and operation continues normally.</p> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/measure.htm b/contrib/ntp/html/measure.htm index a06261d..11035d0 100644 --- a/contrib/ntp/html/measure.htm +++ b/contrib/ntp/html/measure.htm @@ -6,45 +6,12 @@ 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>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>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>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. +<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> +<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 index af5ee3c..348bc3e 100644 --- a/contrib/ntp/html/miscopt.htm +++ b/contrib/ntp/html/miscopt.htm @@ -1,162 +1,279 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Miscellaneous Options</title> +</head> +<body> +<h3>Miscellaneous Options</h3> + +<img align="left" src="pic/boom3.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>We have three, now looking for more.<br clear="left"> +</p> + +<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 client and server. In some cases, +the calibration procedure may fail due to network or server access +controls, for example. This command specifies the default delay to +be used under these circumstances. Typically (for Ethernet), a +number between 0.003 and 0.007 seconds is appropriate. The default +when this command is not used is 0.004 seconds.</dd> + +<dt><tt>driftfile <i>driftfile</i></tt></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. + +<p>The file format consists of a single line containing a single +floating point number, which records the frequency offset measured +in parts-per-million (PPM). The file is updated by first writing +the current drift value into a temporary file and then renaming +this file to replace the old version. This implies that <tt> +ntpd</tt> must have write permission for the directory the drift +file is located in, and that file system links, symbolic or +otherwise, should be avoided.</p> +</dd> + +<dt><tt>enable [auth | bclient | calibrate | kernel | monitor | ntp +| stats]</tt><br> +<tt>disable [auth | bclient | calibrate | kernel | monitor | ntp | +stats</tt></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> +<dl> +<dt><tt>bclient</tt></dt> + +<dd>When enabled, this is identical to the <tt>broadcastclient</tt> +command. The default for this flag is <tt>disable</tt>.</dd> + +<dt><tt>calibrate</tt></dt> + +<dd>Enables the calibration facility, which automatically adjusts +the <tt>time1</tt> values for each clock driver to display the same +offset as the currently selected source or kernel discipline +signal. See the <a href="refclock.htm">Reference Clock Drivers</a> +for further information. The default for this flag is <tt> +disable</tt>.</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. The default for this flag is +<tt>enable</tt>.</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 <tt>enable</tt>.</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 <tt>enable</tt>.</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 <tt>enable</tt>.</dd> +</dl> +</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>clock</tt>, <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>all</tt> prefix can be used instead of a +message class. A message class may also be followed by the <tt> +all</tt> keyword to enable/disable all messages of the respective +message class.</dd> + +<dd>Thus, a minimal log configuration could look like this: + +<p><tt>logconfig=syncstatus +sysevents</tt></p> + +<p>This would just list the synchronizations state of <tt>ntpd</tt> +and the major system events. For a simple reference server, the +following minimum message configuration could be useful:</p> + +<p><tt>logconfig=syncall +clockall</tt></p> + +<p>This configuration will list all clock information and +synchronization information. All other events and messages about +peers, system events and so on is suppressed.</p> +</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> + +<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> + +<dt><tt>tinker [ step <i>step</i> | panic <i>panic</i> | dispersion +<i>dispersion</i> | stepout <i>stepout</i> | minpoll <i>minpoll</i> +]</tt></dt> + +<dd>This command can be used to alter several system variables in +very exceptional circumstances. It should occur in the +configuration file before any other configuration options. The +default values of these variables have been carefully optimized for +a wide range of network speeds and reliability expectations. In +general, they interact in intricate ways that are hard to predict +and some combinations can result in some very nasty behavior. Very +rarely is it necessary to change the default values; but, some +folks can't resist twisting the knobs anyway and this command is +for them. Emphasis added: twisters are on their own and can expect +no help from the support group. + +<p>All arguments are in floating point seconds or seconds per +second. The <tt>minpoll</tt> argument is an integer in seconds to +the power of two. The variables operate as follows:</p> +</dd> + +<dd> +<dl> +<dt><tt>step <i>step</i></tt></dt> + +<dd>The argument becomes the new value for the step threshold, +normally 0.128 s. If set to zero, step adjustments will never +occur. In general, if the intent is only to avoid step adjustments, +the step threshold should be left alone and the <tt>-x</tt> command +line option be used instead.</dd> + +<dt><tt>panic <i>panic</i></tt></dt> + +<dd>The argument becomes the new value for the panic threshold, +normally 1000 s. If set to zero, the panic sanity check is disabled +and a clock offset of any value will be accepted.</dd> + +<dt><tt>dispersion <i>dispersion</i></tt></dt> + +<dd>The argument becomes the new value for the dispersion increase +rate, normally .000015.</dd> + +<dt><tt>stepout <i>stepout</i></tt></dt> + +<dd>The argument becomes the new value for the watchdog timeout, +normally 900 s.</dd> + +<dt><tt>minpoll <i>minpoll</i></tt></dt> + +<dd>The argument becomes the new value for the minimum poll +interval used when configuring multicast client, manycast client +and , symmetric passive mode association. The value defaults to 6 +(64 s) and has a lower limit of 4 (16 s).</dd> + +<dt><tt>allan <i>allan</i></tt></dt> + +<dd>The argument becomes the new value for the minimum Allan +intercept, which is a parameter of the PLL/FLL clock discipline +algorithm. The value defaults to 1024 s, which is also the lower +limit.</dd> + +<dt><tt>huffpuff <i>huffpuff</i></tt></dt> + +<dd>The argument becomes the new value for the experimental +huff-n'-puff filter span, which determines the most recent interval +the algorithm will search for a minimum delay. The lower limit is +900 s (15 m), but a more reasonable value is 7200 (2 hours). There +is no default, since the filter is not enabled unless this command +is given.</dd> +</dl> +</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. + +<p>The trap receiver will generally log event messages and other +information from the server in a log file. While such monitor +programs may also request their own trap dynamically, configuring a +trap receiver will ensure that no messages are lost when the server +is started.</p> +</dd> +</dl> + +<h4>Files</h4> + +<tt>ntp.drift</tt> frequency compensation (PPM) + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/monopt.htm b/contrib/ntp/html/monopt.htm index 267bbcc..4ec8c23 100644 --- a/contrib/ntp/html/monopt.htm +++ b/contrib/ntp/html/monopt.htm @@ -2,7 +2,12 @@ Monitoring Options </title></head><body><h3> Monitoring Options -</h3><hr> +</h3> + +<img align=left src=pic/pogo8.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>Pogo</i>, Walt Kelly</a> + +<p>The pig watches the logs. +<br clear=left><hr> <h4>Monitoring Support</h4> @@ -117,7 +122,7 @@ running at a remote location.</dd> <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> +<tt>statistics</tt> command.</dd> </dl> diff --git a/contrib/ntp/html/mx4200data.htm b/contrib/ntp/html/mx4200data.htm index 2123607..bca0474 100644 --- a/contrib/ntp/html/mx4200data.htm +++ b/contrib/ntp/html/mx4200data.htm @@ -1,7 +1,8 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN"> +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN"> <HTML> <HEAD> -<TITLE>MX4200 Receiver Data Format</TITLE> + <TITLE>MX4200 Receiver Data Format</TITLE> +</HEAD> <BODY> <h1>MX4200 Receiver Data Format</h1> @@ -10,23 +11,23 @@ <ul> <li><a href="#control">Control Port Sentences</a></li> - <li><a href="#input">Control Port Input Sentences</a> + <li><a href="#input">Control Port Input Sentences</a></li> <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> + <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> + <li><a href="#output">Control Port Output Sentences</a></li> <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 + <li><a href="#output_000">$PMVXG,000</a> Receiver Status</li> + <li><a href="#output_021">$PMVXG,021</a> Position, Height, Velocity</li> + <li><a href="#output_022">$PMVXG,022</a> DOPs</li> + <li><a href="#output_030">$PMVXG,030</a> Software Configuration</li> + <li><a href="#output_101">$PMVXG,101</a> Control Sentence Accept/Reject</li> + <li><a href="#output_523">$PMVXG,523</a> Time Recovery Configuration</li> + <li><a href="#output_830">$PMVXG,830</a> Time Recovery Results</li> </ul> </ul> @@ -38,8 +39,8 @@ 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 +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 @@ -50,10 +51,7 @@ 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> +<h4><a name="table_1">Table 1. Magnavox Proprietary NMEA Sentence Format</a></h4> <code> $PMVXG,XXX,...................*CK </code> @@ -135,16 +133,16 @@ 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>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>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>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> + <tr> <td>10 <td>Not Used <td>  <td>  <td>  <td>  </table> Example:<br> <code>$PMVXG,000,,,,,,,,,,*48</code><br> @@ -160,14 +158,14 @@ 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>*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>*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>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> @@ -185,14 +183,14 @@ 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> + <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> @@ -212,13 +210,13 @@ 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>*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 + <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> @@ -235,10 +233,10 @@ 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 + <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> @@ -261,11 +259,11 @@ 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>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 + <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> @@ -283,14 +281,14 @@ applications.</em> <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>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> + <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> @@ -321,21 +319,21 @@ listed. The satellites are listed in receiver channel order. Fields <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 + <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> @@ -350,8 +348,8 @@ 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> + <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> @@ -367,16 +365,16 @@ 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> + <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> + <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> @@ -391,13 +389,13 @@ 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> + <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> @@ -417,23 +415,23 @@ 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>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>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 + <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> diff --git a/contrib/ntp/html/notes.htm b/contrib/ntp/html/notes.htm index e9f648c..c3f1ee0 100644 --- a/contrib/ntp/html/notes.htm +++ b/contrib/ntp/html/notes.htm @@ -724,7 +724,7 @@ 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 +the local server and polls using client mode by a fast path which minimizes the work done in responding to their polls, and normally retains no memory diff --git a/contrib/ntp/html/ntpd.htm b/contrib/ntp/html/ntpd.htm index 0ba0ac7..62aa26a 100644 --- a/contrib/ntp/html/ntpd.htm +++ b/contrib/ntp/html/ntpd.htm @@ -1,183 +1,457 @@ -<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> ] [ -g -] [ -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> ] [ -x ]</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 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>ntpd - Network Time Protocol (NTP) daemon</title> +</head> +<body> +<h3><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</h3> + +<img align="left" src="pic/alice47.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>The mushroom knows all the command line options.<br clear= +"left"> +</p> + +<hr> +<h4>Synopsis</h4> + +<tt>ntpd [ -aAbdgLmNPqx ] [ -c <i>conffile</i> ] [ -f <i> +driftfile</i> ] [ -g ] [ -k <i>keyfile</i> ] [ -l <i>logfile</i> ] +[ -N high ] [ -p <i>pidfile</i> ] [ -r <i>broadcastdelay</i> ] [ -s +<i>statsdir</i> ] [ -t <i>key</i> ] [ -v <i>variable</i> ] [ -V <i> +variable</i> ] [ -x ]</tt> + +<h4>Description</h4> + +The <tt>ntpd</tt> program is an operating system daemon which sets +and maintains the system time of day in synchronism with Internet +standard time servers. It is a complete implementation of the +Network Time Protocol (NTP) version 4, but also retains +compatibility with version 3, as defined by RFC-1305, and version 1 +and 2, as defined by RFC-1059 and RFC-1119, respectively. <tt> +ntpd</tt> does most computations in 64-bit floating point +arithmetic and does relatively clumsy 64-bit fixed point operations +only when necessary to preserve the ultimate precision, about 232 +picoseconds. While the ultimate precision, is not achievable with +ordinary workstations and networks of today, it may be required +with future gigahertz CPU clocks and gigabit LANs. + +<h4>How NTP Operates</h4> + +<p>The <tt>ntpd</tt> program operates by exchanging messages with +one or more configured servers at designated poll intervals. When +started, whether for the first or subsequent times, the program +requires several exahanges from the majority of these servers so +the signal processing and mitigation algorithms can accumulate and +groom the data and set the clock. In order to protect the network +from bursts, the initial poll interval for each server is delayed +an interval randomized over 0-16s. At the default initial poll +interval of 64s, several minutes can elapse before the clock is +set. The initial delay to set the clock can be reduced using the +<tt>iburst</tt> keyword with the <tt>server</tt> configuration +command, as described on the <a href="confopt.htm">Configuration +Options</a> page.</p> + +<p>Most operating systems and hardware of today incorporate a +time-of-year (TOY) chip to maintain the time during periods when +the power is off. When the machine is booted, the chip is used to +initialize the operating system time. After the machine has +synchronized to a NTP server, the operating system corrects the +chip from time to time. In case there is no TOY chip or for some +reason its time is more than 1000s from the server time, <tt> +ntpd</tt> assumes something must be terribly wrong and the only +reliable action is for the operator to intervene and set the clock +by hand. This causes <tt>ntpd</tt> to exit with a panic message to +the system log. The <tt>-g</tt> option overrides this check and the +clock will be set to the server time regardless of the chip time. +However, and to protect against broken hardware, such as when the +CMOS battery fails or the clock counter becomes defective, once the +clock has been set, an error greater than 1000s will cause <tt> +ntpd</tt> to exit anyway.</p> + +<p>Under ordinariy conditions, <tt>ntpd</tt> adjusts the clock in +small steps so that the timescale is effectively continuous and +without discontinuities. Under conditions of extreme network +congestion, the roundtrip delay jitter can exceed three seconds and +the synchronization distance, which is equal to one-half the +roundtrip delay plus error budget terms, can become very large. The +<tt>ntpd</tt> algorithms discard sample offsets exceeding 128 ms, +unless the interval during which no sample offset is less than 128 +ms exceeds 900s. The first sample after that, no matter what the +offset, steps the clock to the indicated time. In practice this +reduces the false alarm rate where the clock is stepped in error to +a vanishingly low incidence.</p> + +<p>As the result of this behavior, once the clock has been set, it +very rarely strays more than 128 ms, even under extreme cases of +network path congestion and jitter. Sometimes, in particular when +<tt>ntpd</tt> is first started, the error might exceed 128 ms. This +may on occasion cause the clock to be set backwards if the local +clock time is more than 128 s in the future relative to the server. +In some applications, this behavior may be unacceptable. If the +<tt>-x</tt> option is included on the command line, the clock will +never be stepped and only slew corrections will be used.</p> + +<p>The issues should be carefully explored before deciding to use +the <tt>-x</tt> option. The maximum slew rate possible is limited +to 500 parts-per-million (PPM) as a consequence of the correctness +principles on which the NTP protocol and algorithm design are +based. As a result, the local clock can take a long time to +converge to an acceptable offset, about 2,000 s for each second the +clock is outside the acceptable range. During this interval the +local clock will not be consistent with any other network clock and +the system cannot be used for distributed applications that require +correctly synchronized network time.</p> + +<p>In spite of the above precautions, sometimes when large +frequency errors are present the resulting time offsets stray +outside the 128-ms range and an eventual step or slew time +correction is required. If following such a correction the +frequency error is so large that the first sample is outside the +acceptable range, <tt>ntpd</tt> enters the same state as when the +<tt>ntp.drift</tt> file is not present. The intent of this behavior +is to quickly correct the frequency and restore operation to the +normal tracking mode. In the most extreme cases +(<tt>time.ien.it</tt> comes to mind), there may be occasional +step/slew corrections and subsequent frequency corrections. It +helps in these cases to use the <tt>burst</tt> keyword when +configuring the server.</p> + +<h4>Frequency Discipline</h4> + +<p>The <tt>ntpd</tt> behavior at startup depends on whether the +frequency file, usually <tt>ntp.drift</tt>, exists. This file +contains the latest estimate of clock frequency error. When the +<tt>ntpd</tt> is started and the file does not exist, the <tt> +ntpd</tt> enters a special mode designed to quickly adapt to the +particular system clock oscillator time and frequency error. This +takes approximately 15 minutes, after which the time and frequency +are set to nominal values and the <tt>ntpd</tt> enters normal mode, +where the time and frequency are continuously tracked relative to +the server. After one hour the frequency file is created and the +current frequency offset written to it. When the <tt>ntpd</tt> is +started and the file does exist, the <tt>ntpd</tt> frequency is +initialized from the file and enters normal mode immediately. After +that the current frequency offset is written to the file at hourly +intervals.</p> + +<h4>Operating Modes</h4> + +<p><tt>ntpd</tt> can operate in any of several modes, including +symmetric active/passive, client/server broadcast/multicast and +manycast, as described in the <a href="assoc.htm">Association +Management</a> page. It normally operates continuously while +monitoring for small changes in frequency and trimming the clock +for the ultimate precision. However, it can operate in a one-time +mode where the time is set from an external server and frequency is +set from a previously recorded frequency file. A broadcast/multicast or manycast client can discover remote servers, -compute server-client propagation delay correction factors and configure -itself automatically. This makes it possible to deploy a fleet of -workstations without specifying configuration details specific to the -local environment. +compute server-client propagation delay correction factors and +configure itself automatically. This makes it possible to deploy a +fleet of workstations without specifying configuration details +specific to the local environment.</p> + +<p>By default, <tt>ntpd</tt> runs in continuous mode where each of +possibly several external servers is polled at intervals determined +by an intricate state machine. The state machine measures the +incidental roundtrip delay jitter and oscillator frequency wander +and determines the best poll interval using a heuristic algorithm. +Ordinarily, and in most operating environments, the state machine +will start with 64s intervals and eventually increase in steps to +1024s. A small amount of random variation is introduced in order to +avoid bunching at the servers. In addition, should a server become +unreachable for some time, the poll interval is increased in steps +to 1024s in order to reduce network overhead.</p> + +<p>In some cases it may not be practical for <tt>ntpd</tt> to run +continuously. A common workaround has been to run the <tt> +ntpdate</tt> program from a <tt>cron</tt> job at designated times. +However, this program does not have the crafted signal processing, +error checking and mitigation algorithms of <tt>ntpd</tt>. The <tt> +-q</tt> option is intended for this purpose. Setting this option +will cause <tt>ntpd</tt> to exit just after setting the clock for +the first time. The procedure for initially setting the clock is +the same as in continuous mode; most applications will probably +want to specify the <tt>iburst</tt> keyword with the <tt> +server</tt> configuration command. With this keyword a volley of +messages are exchanged to groom the data and the clock is set in +about a minute. If nothing is heard after a couple of minutes, the +daemon times out and exits. After a suitable period of mourning, +the <tt>ntpdate</tt> program may be retired.</p> + +<p>When kernel support is available to discipline the clock +frequency, which is the case for stock Solaris, Tru64, Linux and +FreeBSD, a useful feature is available to discipline the clock +frequency. First, <tt>ntpd</tt> is run in continuous mode with +selected servers in order to measure and record the intrinsic clock +frequency offset in the frequency file. It may take some hours for +the frequency and offset to settle down. Then the <tt>ntpd</tt> is +stopped and run in one-time mode as required. At each startup, the +frequency is read from the file and initializes the kernel +frequency.</p> + +<h4>Poll Interval Control</h4> + +<p>This version of NTP includes an intricate state machine to +reduce the network load while maintaining a quality of +synchronization consistent with the observed jitter and wander. +There are a number of ways to tailor the operation in order enhance +accuracy by reducing the interval or to reduce network overhead by +increasing it. However, the user is advised to carefully consider +the consequenses of changing the poll adjustment range from the +default minimum of 64 s to the default maximum of 1,024 s. The +default minimum can be changed with the <tt>tinker minpoll</tt> +command to a value not less than 16 s. This value is used for all +configured associations, unless overriden by the <tt>minpoll</tt> +option on the configuration command. Note that most device drivers +will not operate properly if the poll interval is less than 64 s +and that the broadcast server and manycast client associations will +also use the default, unless overriden.</p> + +<p>In some cases involving dial up or toll services, it may be +useful to increase the minimum interval to a few tens of minutes +and maximum interval to a day or so. Under normal operation +conditions, once the clock discipline loop has stabilized the +interval will be increased in steps from the minumum to the +maximum. However, this assumes the intrinsic clock frequency error +is small enough for the discipline loop correct it. The capture +range of the loop is 500 PPM at an interval of 64s decreasing by a +factor of two for each doubling of interval. At a minimum of 1,024 +s, for example, the capture range is only 31 PPM. If the intrinsic +error is greater than this, the drift file <tt>ntp.drift</tt> will +have to be specially tailored to reduce the residual error below +this limit. Once this is done, the drift file is automatically +updated once per hour and is available to initialize the frequency +on subsequent daemon restarts.</p> + +<h4>The huff-n'-puff filter</h4> + +<p>In scenarios where a considerable amount of data are to be +downloaded or uploaded over telephone modems, timekeeping quality +can be seriously degraded. This occurs because the differential +delays on the two directions of transmission can be quite large. In +many cases the apparent time errors are so large as to exceed the +step threshold and a step correction can occur during and after the +data transfer is in progress.</p> + +<p>The huff-n'-puff filter is designed to correct the apparent time +offset in these cases. It depends on knowledge of the propagation +delay when no other traffic is present. In common scenarios this +occurs during other than work hours. The filter maintains a shift +register that remembers the minimum delay over the most recent +interval measured usually in hours. Under conditions of severe +delay, the filter corrects the apparent offset using the sign of +the offset and the difference between the apparent delay and +minimum delay. The name of the filter reflects the negative (huff) +and positive (puff) correction, which depends on the sign of the +offset.</p> + +<p>The filter is activated by the <tt>tinker</tt> command and <tt> +huffpuff</tt> keyword, as described in the <a href="miscopt.htm"> +Miscellaneous Options</a> page.</p> + +<h4>Notes</h4> + +<p>If NetInfo support is built into <tt>ntpd</tt>, then <tt> +ntpd</tt> will attempt to read its configuration from the NetInfo +if the default ntp.conf file cannot be read and no file is +specified by the <tt>-c</tt> option.</p> + +<p>Various internal <tt>ntpd</tt> variables can be displayed and +configuration options altered while the <tt>ntpd</tt> is running +using the <tt><a href="ntpq.htm">ntpq</a></tt> and <tt><a href= +"ntpdc.htm">ntpdc</a></tt> utility programs.</p> + +<p>When <tt>ntpd</tt> starts it looks at the value of <tt> +umask</tt>, and if zero <tt>ntpd</tt> will set the <tt>umask</tt> +to <tt>022</tt>.</p> + +<h4>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. (Disable +netinfo?)</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, <tt>ntpd</tt> exits if the offset exceeds the sanity +limit, which is 1000 s by default. If the sanity limit is set to +zero, no sanity checking is performed and any offset is acceptable. +This option overrides the limit and allows the time to be set to +any value without restriction; however, this can happen only once. +After that, <tt>ntpd</tt> will exit if the limit is exceeded. This +option can be used with the <tt>-q</tt> option.</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>-L</tt></dt> + +<dd>Listen to virtual IPs.</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>-n</tt></dt> + +<dd>Don't fork.</dd> + +<dt><tt>-N <i>priority</i></tt></dt> + +<dd>To the extent permitted by the operating system, run the <tt> +ntpd</tt> at a high priority.</dd> + +<dt><tt>-p <i>pidfile</i></tt></dt> + +<dd>Specify the name and path to record the <tt>ntpd</tt>'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>-q</tt></dt> + +<dd>Exit the <tt>ntpd</tt> just after the first time the clock is +set. This behavior mimics that of the <tt>ntpdate</tt> program, +which is to be retired. The <tt>-g</tt> and <tt>-x</tt> options can +be used with this option.</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>Normally, the time is slewed if the offset is less than the +step threshold, which is 128 ms by default, and stepped if above +the threshold. This option forces the time to be slewed in all +cases. If the step threshold is set to zero, all offsets are +stepped, regardless of value and regardless of the <tt>-x</tt> +option. In general, this is not a good idea, as it bypasses the +clock state machine which is designed to cope with large time and +frequency errors 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. This option can be used with the <tt>-q</tt> option.</dd> +</dl> + +<h4>The Configuration File</h4> + +<p>Ordinarily, <tt>ntpd</tt> reads the <tt>ntp.conf</tt> +configuration file at startup time in order to determine the +synchronization sources and operating modes. It is also possible to +specify a working, although limited, configuration entirely on the +command line, obviating the need for a configuration file. This may +be particularly useful when the local host is to be configured as a +broadcast/multicast client, with all peers being determined by +listening to broadcasts at run time.</p> + +<p>Usually, the configuration file is installed in the <tt> +/etc</tt> directory, but could be installed elsewhere (see the <tt> +-c <i>conffile</i></tt> command line option). The file format is +similar to other Unix configuration files - comments begin with a +<tt>#</tt> character and extend to the end of the line; blank lines +are ignored.</p> + +<p>Configuration commands consist of an initial keyword followed by +a list of arguments, some of which may be optional, separated by +whitespace. Commands may not be continued over multiple lines. +Arguments may be host names, host addresses written in numeric, +dotted-quad form, integers, floating point numbers (when specifying +times in seconds) and text strings. Optional arguments are +delimited by <tt>[ ]</tt> in the following descriptions, while +alternatives are separated by <tt>|</tt>. The notation <tt>[ ... +]</tt> means an optional, indefinite repetition of the last item +before the <tt>[ ... ]</tt>.</p> + +<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></p> + +<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 desirable for an elevated-priority <tt> +ntpd</tt> 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" alt= +"gif"></a> + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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; however, this can happen only once. After -that, the daemon will exit of the limit is exceeded. - -<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 index a7f532f..c2d32bb 100644 --- a/contrib/ntp/html/ntpdate.htm +++ b/contrib/ntp/html/ntpdate.htm @@ -1,185 +1,186 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>ntpdate - set the date and time via NTP</title> +</head> +<body> +<h3><tt>ntpdate</tt> - set the date and time via NTP</h3> + +<img align="left" src="pic/rabbit.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>I told you it was eyeball and wristwatch.<br clear="left"> +</p> + +<hr> +<p>Disclaimer: The functionality of this program is now available +in the <tt>ntpd</tt> program. See the <tt>-q</tt> command line +option in the <a href="ntpd.htm"><tt>ntpd</tt> - Network Time +Protocol (NTP) daemon</a> page. After a suitable period of +mourning, the <tt>ntpdate</tt> program is to be retired from this +distribution</p> + +<h4>Synopsis</h4> + +<tt>ntpdate [ -bBdoqsuv ] [ -a <i>key</i> ] [ -e <i>authdelay</i> ] +[ -k <i>keyfile</i> ] [ -o <i>version</i> ] [ -p <i>samples</i> ] [ +-t <i>timeout</i> ] <i>server</i> [ ... ]</tt> + +<h4>Description</h4> + +<tt>ntpdate</tt> sets the local date and time by polling the +Network Time Protocol (NTP) server(s) given as the <i>server</i> +arguments to determine the correct time. It must be run as root on +the local host. A number of samples are obtained from each of the +servers specified and a subset of the NTP clock filter and +selection algorithms are applied to select the best of these. Note +that the accuracy and reliability of <tt>ntpdate</tt> depends on +the number of servers, the number of polls each time it is run and +the interval between runs. + +<p><tt>ntpdate</tt> can be run manually as necessary to set the +host clock, or it can be run from the host startup script to set +the clock at boot time. This is useful in some cases to set the +clock initially before starting the NTP daemon <tt>ntpd</tt>. It is +also possible to run <tt>ntpdate</tt> from a <tt>cron</tt> script. +However, it is important to note that <tt>ntpdate</tt> with +contrived <tt>cron</tt> scripts is no substitute for the NTP +daemon, which uses sophisticated algorithms to maximize accuracy +and reliability while minimizing resource use. Finally, since <tt> +ntpdate</tt> does not discipline the host clock frequency as does +<tt>ntpd</tt>, the accuracy using <tt>ntpdate</tt> is limited.</p> + +<p>Time adjustments are made by <tt>ntpdate</tt> in one of two +ways. If <tt>ntpdate</tt> determines the clock is in error more +than 0.5 second it will simply step the time by calling the system +<tt>settimeofday()</tt> routine. If the error is less than 0.5 +seconds, it will slew the time by calling the system <tt> +adjtime()</tt> routine. The latter technique is less disruptive and +more accurate when the error is small, and works quite well when +<tt>ntpdate</tt> is run by <tt>cron</tt> every hour or two.</p> + +<p><tt>ntpdate</tt> will decline to set the date if an NTP server +daemon (e.g., <tt>ntpd</tt>) is running on the same host. When +running <tt>ntpdate</tt> on a regular basis from <tt>cron</tt> as +an alternative to running a daemon, doing so once every hour or two +will result in precise enough timekeeping to avoid stepping the +clock.</p> + +<p>If NetInfo support is compiled into <tt>ntpdate</tt>, then the +<tt>server</tt> argument is optional if <tt>ntpdate</tt> can find a +time server in the NetInfo configuration for <tt>ntpd</tt>.</p> + +<h4>Command Line Options</h4> + +<dl> +<dt><tt>-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> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/ntpdc.htm b/contrib/ntp/html/ntpdc.htm index 52d1fdf..ffb2cc0 100644 --- a/contrib/ntp/html/ntpdc.htm +++ b/contrib/ntp/html/ntpdc.htm @@ -1,620 +1,573 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>ntpdc - special NTP query program</title> +</head> +<body> +<h3><tt>ntpdc</tt> - special NTP query program</h3> + +<img align="left" src="pic/alice31.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>This program is a big puppy.<br clear="left"> +</p> + +<hr> +<h4>Synopsis</h4> + +<tt>ntpdc [ -ilnps ] [ -c <i>command</i> ] [ <i>host</i> ] [ ... +]</tt> + +<h4>Description</h4> + +<tt>ntpdc</tt> is used to query the <tt>ntpd</tt> daemon about its +current state and to request changes in that state. The program may +be run either in interactive mode or controlled using command line +arguments. Extensive state and statistics information is available +through the <tt>ntpdc</tt> interface. In addition, nearly all the +configuration options which can be specified at startup using +ntpd's configuration file may also be specified at run time using +<tt>ntpdc</tt>. + +<p>If one or more request options are included on the command line +when <tt>ntpdc</tt> is executed, each of the requests will be sent +to the NTP servers running on each of the hosts given as command +line arguments, or on localhost by default. If no request options +are given, <tt>ntpdc</tt> will attempt to read commands from the +standard input and execute these on the NTP server running on the +first host given on the command line, again defaulting to localhost +when no other host is specified. <tt>ntpdc</tt> will prompt for +commands if the standard input is a terminal device.</p> + +<p><tt>ntpdc</tt> uses NTP mode 7 packets to communicate with the +NTP server, and hence can be used to query any 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> + +<p>The operation of <tt>ntpdc</tt> are specific to the particular +implementation of the <tt>ntpd</tt> daemon and can be expected to +work only with this and maybe some previous versions of the daemon. +Requests from a remote <tt>ntpdc</tt> program which affect the +state of the local server must be authenticated, which requires +both the remote program and local server share a common key and key +identifier.</p> + +<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> -<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>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.</p> + +<dl> +<dt><tt>? [ <i>command_keyword</i> ]</tt><br> +<tt>help [ <i>command_keyword</i> ]</tt></dt> + +<dd>A <tt>?</tt> by itself will print a list of all the command +keywords known to this incarnation of <tt>ntpq</tt>. A <tt>?</tt> +followed by a command keyword will print 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> -<DD> -Clear a trap for asynchronous messages. See the source listing for further -information.</DD> +<dt><tt>hostnames [ yes | no ]</tt></dt> -<DT> -<TT>reset</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> -Clear the statistics counters in various modules of the server. See the -source listing for further information.</DD> -</DL> +<dt><tt>keyid <i>keyid</i></tt></dt> -<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> +<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. + +<p>The character in the left margin indicates the mode this peer +entry is operating in. A <tt>+</tt> denotes symmetric active, a +<tt>-</tt> indicates symmetric passive, a <tt>=</tt> means the +remote server is being polled in client mode, a <tt>^</tt> +indicates that the server is broadcasting to this address, a <tt> +~</tt> denotes that the remote peer is sending broadcasts and a +<tt>*</tt> marks the peer the server is currently synchonizing +to.</p> + +<p>The contents of the host field may be one of four forms. It may +be a host name, an IP address, a reference clock implementation +name with its parameter or <tt>REFCLK(<i>implementation number</i>, +<i>parameter</i>)</tt>. On <tt>hostnames no</tt> only IP-addresses +will be displayed.</p> +</dd> + +<dt><tt>dmpeers</tt></dt> + +<dd>A slightly different peer summary list. Identical to the output +of the <tt>peers</tt> command, except for the character in the +leftmost column. Characters only appear beside peers which were +included in the final stage of the clock selection algorithm. A +<tt>.</tt> indicates that this peer was cast off in the falseticker +detection, while a <tt>+</tt> indicates that the peer made it +through. A <tt>*</tt> denotes the peer the server is currently +synchronizing with.</dd> + +<dt><tt>showpeer <i>peer_address</i> [...]</tt></dt> + +<dd>Shows a detailed display of the current peer variables for one +or more peers. Most of these values are described in the NTP +Version 2 specification.</dd> + +<dt><tt>pstats <i>peer_address</i> [...]</tt></dt> + +<dd>Show per-peer statistic counters associated with the specified +peer(s).</dd> + +<dt><tt>clockinfo <i>clock_peer_address</i> [...]</tt></dt> + +<dd>Obtain and print information concerning a peer clock. The +values obtained provide information on the setting of fudge factors +and other clock performance information.</dd> + +<dt><tt>kerninfo</tt></dt> + +<dd>Obtain and print kernel phase-lock loop operating parameters. +This information is available only if the kernel has been specially +modified for a precision timekeeping function.</dd> + +<dt><tt>loopinfo [ oneline | multiline ]</tt></dt> + +<dd>Print the values of selected loop filter variables. The loop +filter is the part of NTP which deals with adjusting the local +system clock. The <tt>offset</tt> is the last offset given to the +loop filter by the packet processing code. The <tt>frequency</tt> +is the frequency error of the local clock in parts-per-million +(ppm). The <tt>time_const</tt> controls the stiffness of the +phase-lock loop and thus the speed at which it can adapt to +oscillator drift. The <tt>watchdog timer</tt> value is the number +of seconds which have elapsed since the last sample offset was +given to the loop filter. The <tt>oneline</tt> and <tt> +multiline</tt> options specify the format in which this information +is to be printed, with <tt>multiline</tt> as the default.</dd> + +<dt><tt>sysinfo</tt></dt> + +<dd>Print a variety of system state variables, i.e., state related +to the local server. All except the last four lines are described +in the NTP Version 3 specification, RFC-1305. + +<p>The <tt>system flags</tt> show various system flags, some of +which can be set and cleared by the <tt>enable</tt> and <tt> +disable</tt> configuration commands, respectively. These are the +<tt>auth</tt>, <tt>bclient</tt>, <tt>monitor</tt>, <tt>pll</tt>, +<tt>pps</tt> and <tt>stats</tt> flags. See the <tt>ntpd</tt> +documentation for the meaning of these flags. There are two +additional flags which are read only, the <tt>kernel_pll</tt> and +<tt>kernel_pps</tt>. These flags indicate the synchronization +status when the precision time kernel modifications are in use. The +<tt>kernel_pll</tt> indicates that the local clock is being +disciplined by the kernel, while the kernel_pps indicates the +kernel discipline is provided by the PPS signal.</p> + +<p>The <tt>stability</tt> is the residual frequency error remaining +afterthe system frequency correction is applied and is intended for +maintenance and debugging. In most architectures, this value will +initially decrease from as high as 500 ppm to a nominal value in +the range .01 to 0.1 ppm. If it remains high for some time after +starting the daemon, something may be wrong with the local clock, +or the value of the kernel variable <tt>tick</tt> may be +incorrect.</p> + +<p>The <tt>broadcastdelay</tt> shows the default broadcast delay, +as set by the <tt>broadcastdelay</tt> configuration command.</p> + +<p>The <tt>authdelay</tt> shows the default authentication delay, +as set by the <tt>authdelay</tt> configuration command.</p> +</dd> + +<dt><tt>sysstats</tt></dt> + +<dd>Print statistics counters maintained in the protocol +module.</dd> + +<dt><tt>memstats</tt></dt> + +<dd>Print statistics counters related to memory allocation +code.</dd> + +<dt><tt>iostats</tt></dt> + +<dd>Print statistics counters maintained in the input-output +module.</dd> + +<dt><tt>timerstats</tt></dt> + +<dd>Print statistics counters maintained in the timer/event queue +support code.</dd> + +<dt><tt>reslist</tt></dt> + +<dd>Obtain and print the server's restriction list. This list is +(usually) printed in sorted order and may help to understand how +the restrictions are applied.</dd> + +<dt><tt>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> + +<p>The following commands all make authenticated requests.</p> + +<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><br> +<tt>disable [ <i>flag</i> ] [ ... ]</tt></dt> + +<dd>These commands operate in the same way as the <tt>enable</tt> +and <tt>disable</tt> configuration file commands of <tt>ntpd</tt>. +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> + +<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> +</dd> + +<dt><tt>restrict <i>address mask flag</i> [ <i>flag</i> ]</tt></dt> + +<dd>This command operates in the same way as the <tt>restrict</tt> +configuration file commands of <tt>ntpd</tt>.</dd> + +<dt><tt>unrestrict <i>address mask flag</i> [ <i>flag</i> +]</tt></dt> + +<dd>Unrestrict the matching entry from the restrict list.</dd> + +<dt><tt>delrestrict <i>address mask [ ntpport ]</i></tt></dt> + +<dd>Delete the matching entry from the restrict list.</dd> + +<dt><tt>readkeys</tt></dt> + +<dd>Causes the current set of authentication keys to be purged and +a new set to be obtained by rereading the keys file (which must +have been specified in the <tt>ntpd</tt> configuration file). This +allows encryption keys to be changed without restarting the +server.</dd> + +<dt><tt>trustedkey <i>keyid</i> [...]</tt></dt> + +<dt><tt>untrustedkey <i>keyid</i> [...]</tt></dt> + +<dd>These commands operate in the same way as the <tt> +trustedkey</tt> and <tt>untrustedkey</tt> configuration file +commands of <tt>ntpd</tt>.</dd> + +<dt><tt>authinfo</tt></dt> + +<dd>Returns information concerning the authentication module, +including known keys and counts of encryptions and decryptions +which have been done.</dd> + +<dt><tt>traps</tt></dt> + +<dd>Display the traps set in the server. See the source listing for +further information.</dd> + +<dt><tt>addtrap [ <i>address</i> [ <i>port</i> ] [ <i>interface</i> +]</tt></dt> + +<dd>Set a trap for asynchronous messages. See the source listing +for further information.</dd> + +<dt><tt>clrtrap [ <i>address</i> [ <i>port</i> ] [ <i> +interface</i>]</tt></dt> + +<dd>Clear a trap for asynchronous messages. See the source listing +for further information.</dd> + +<dt><tt>reset</tt></dt> + +<dd>Clear the statistics counters in various modules of the server. +See the source listing for further information.</dd> +</dl> + +<h4>Bugs</h4> + +<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> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -</BODY> -</HTML> diff --git a/contrib/ntp/html/ntpq.htm b/contrib/ntp/html/ntpq.htm index 9308867..908eb5e 100644 --- a/contrib/ntp/html/ntpq.htm +++ b/contrib/ntp/html/ntpq.htm @@ -1,747 +1,658 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>ntpq - standard NTP query program</title> +</head> +<body> +<h3><tt>ntpq</tt> - standard NTP query program</h3> + +<img align="left" src="pic/bustardfly.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> + +<p>A typical NTP monitoring packet.<br clear="left"> +</p> + +<hr> +<h4>Synopsis</h4> + +<tt>ntpq [-inp] [-c <i>command</i>] [<i>host</i>] [...]</tt> + +<h4>Description</h4> + +The <tt>ntpq</tt> utility program 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> + +<p><tt>ntpq</tt> uses NTP mode 6 packets to communicate with the +NTP server, and hence can be used to query any compatible server on +the network which permits it. Note that since NTP is a UDP protocol +this communication will be somewhat unreliable, especially over +large distances in terms of network topology. <tt>ntpq</tt> makes +one attempt to retransmit requests, and will time requests out if +the remote host is not heard from within a suitable timeout +time.</p> + +<p>For examples and usage, see the <a href="debug.htm">NTP +Debugging Techniques</a> page.</p> + +<p>Command line options are described following. Specifying a +command line option other than <tt>-i</tt> or <tt>-n</tt> will +cause the specified query (queries) to be sent to the indicated +host(s) immediately. Otherwise, <tt>ntpq</tt> will attempt to read +interactive format commands from the standard input.</p> + +<dl> +<dt><tt>-c</tt></dt> + +<dd>The following argument is interpreted as an interactive format +command and is added to the list of commands to be executed on the +specified host(s). Multiple <tt>-c</tt> options may be given.</dd> + +<dt><tt>-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 +<tt><</tt>, followed by a file name, to the command line. A +number of interactive format commands are executed entirely within +the <tt>ntpq</tt> program itself and do not result in NTP mode 6 +requests being sent to a server. These are described following. + +<dl> +<dt><tt>? [<i>command_keyword</i>]</tt><br> +<tt>helpl [<i>command_keyword</i>]</tt></dt> + +<dd>A <tt>?</tt> by itself will print a list of all the command +keywords known to this incarnation of <tt>ntpq</tt>. A <tt>?</tt> +followed by a command keyword will print function and usage +information about the command. This command is probably a better +source of information about <tt>ntpq</tt> than this manual +page.</dd> + +<dt><tt>addvars <i>variable_name</i> [ = <i>value</i>] +[...]</tt><br> +<tt>rmvars <i>variable_name</i> [...]</tt><br> +<tt>clearvars</tt></dt> + +<dd>The data carried by NTP mode 6 messages consists of a list of +items of the form <tt><i>variable_name</i> = <i>value</i></tt>, +where the <tt>= <i>value</i></tt> is ignored, and can be omitted, +in requests to the server to read variables. <tt>ntpq</tt> +maintains an internal list in which data to be included in control +messages can be assembled, and sent using the <tt>readlist</tt> and +<tt>writelist</tt> commands described below. The <tt>addvars</tt> +command allows variables and their optional values to be added to +the list. If more than one variable is to be added, the list should +be comma-separated and not contain white space. The <tt>rmvars</tt> +command can be used to remove individual variables from the list, +while the <tt>clearlist</tt> command removes all variables from the +list.</dd> + +<dt><tt>authenticate yes | no</tt></dt> + +<dd>Normally <tt>ntpq</tt> does not authenticate requests unless +they are write requests. The command <tt>authenticate yes</tt> +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 <tt> +peer</tt> display. [I didn't know that - Ed.]</dd> + +<dt><tt>cooked</tt></dt> + +<dd>Causes output from query commands to be "cooked", so that +variables which are recognized by <tt>ntpq</tt> will have their +values reformatted for human consumption. Variables which <tt> +ntpq</tt> thinks should have a decodable value but didn't are +marked with a trailing <tt>?</tt>.</dd> + +<dt><tt>debug more | less | off</tt></dt> + +<dd>Turns internal query program debugging on and off.</dd> + +<dt><tt>delay <i>milliseconds</i></tt></dt> + +<dd>Specify a time interval to be added to timestamps included in +requests which require authentication. This is used to enable +(unreliable) server reconfiguration over long delay network paths +or between machines whose clocks are unsynchronized. Actually the +server does not now require timestamps in authenticated requests, +so this command may be obsolete.</dd> + +<dt><tt>host <i>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>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> + +<dt><tt>quit</tt></dt> + +<dd>Exit <tt>ntpq</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>raw</tt></dt> + +<dd>Causes all output from query commands is printed as received +from the remote server. The only formating/interpretation done on +the data is to transform nonascii data into a printable (but barely +understandable) form.</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.</p> + +<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> + +<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> - -<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> +<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> -<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> +<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> + +<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> + +<dt><tt>mreadlist <i>assocID</i> <i>assocID</i></tt><br> +<tt>mrl <i>assocID</i> <i>assocID</i></tt></dt> + +<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> + +<dt><tt>mreadvar <i>assocID</i> <i>assocID</i> [ <i> +variable_name</i> [ = <i>value</i>[ ... ]</tt><br> +<tt>mrv <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ = +<i>value</i>[ ... ]</tt></dt> + +<dd>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> + +<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> + +<dt><tt>passociations</tt></dt> + +<dd>Displays association data concerning in-spec peers from the +internally cached list of associations. This command performs +identically to the <tt>associations</tt> except that it displays +the internally stored data rather than making a new query.</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>The character in the left margin indicates the fate of this +peer in the clock selection process. Following is a list of these +characters, the pigeon used in the <tt>rv</tt> command, and a short +explanation of the condition revealed.</dd> + +<dd> +<dl> +<dt><tt>space reject</tt></dt> + +<dd>The peer is discarded as unreachable, synchronized to this +server (synch loop) or outrageous synchronization distance.</dd> + +<dt><tt>x falsetick</tt></dt> + +<dd>The peer is discarded by the intersection algorithm as a +falseticker.</dd> + +<dt><tt>. excess</tt></dt> + +<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> + +<dt><tt>- outlyer</tt></dt> + +<dd>The peer is discarded by the clustering algorithm as an +outlyer.</dd> + +<dt><tt>+ candidat</tt></dt> + +<dd>The peer is a survivor and a candidate for the combining +algorithm.</dd> + +<dt><tt># selected</tt></dt> + +<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> + +<dt><tt>* sys.peer</tt></dt> + +<dd>The peer has been declared the system peer and lends its +variables to the system variables.</dd> + +<dt><tt>o pps.peer</tt></dt> + +<dd>The peer has been declared the system peer and lends its +variables to thesystem variables. However, the actual system +synchronization is derived from a pulse-per-second (PPS) signal, +either indirectly via the PPS reference clock driver or directly +via kernel interface.</dd> +</dl> +</dd> + +<dd>The <tt>flash</tt> variable is a valuable debugging aid. It +displays the results of the original sanity checks defined in the +NTP specification RFC-1305 and additional ones added in NTP Version +4. There are eleven tests called <tt>TEST1</tt> through <tt> +TEST11</tt>. The tests are performed in a certain order designed to +gain maximum diagnostic information while protecting against +accidental or malicious errors. The <tt>flash</tt> variable is +first initialized to zero. If after each set of tests one or more +bits are set, the packet is discarded. + +<p>Tests <tt>TEST4</tt> and <tt>TEST5</tt> check the access +permissions and cryptographic message digest. If any bits are set +after that, the packet is discarded. Tests <tt>TEST10</tt> and <tt> +TEST11</tt> check the authentication state using Autokey public-key +cryptography, as described in the <a href="authopt.htm"> +Authentication Options</a> page. If any bits are set and the +association has previously been marked reachable, the packet is +discarded; otherwise, the originate and receive timestamps are +saved, as required by the NTP protocol, and processing +continues.</p> + +<p>Tests <tt>TEST1</tt> through <tt>TEST3</tt> check the packet +timestamps from which the offset and delay are calculated. If any +bits are set, the packet is discarded; otherwise, the packet header +variables are saved. Tests <tt>TEST6</tt> through <tt>TEST8</tt> +check the health of the server. If any bits are set, the packet is +discarded; otherwise, the offset and delay relative to the server +are calculated and saved. Test <tt>TEST9</tt> checks the health of +the association itself. If any bits are set, the packet is +discarded; otherwise, the saved variables are passed to the clock +filter and mitigation algorithms.</p> + +<p>The <tt>flash</tt> bits for each test read in increasing order +from the least significant bit are defined as follows.</p> +</dd> + +<dd> +<dl> +<dt><tt>TEST1</tt></dt> + +<dd>Duplicate packet. The packet is at best a casual retransmission +and at worst a malicious replay.</dd> + +<dt><tt>TEST2</tt></dt> + +<dd>Bogus packet. The packet is not a reply to a message previously +sent. This can happen when the NTP daemon is restarted and before +somebody else notices.</dd> + +<dt><tt>TEST3</tt></dt> + +<dd>Unsynchronized. One or more timestamp fields are invalid. This +normally happens when the first packet from a peer is +received.</dd> + +<dt><tt>TEST4</tt></dt> + +<dd>Access is denied. See the <a href="accopt.htm">Access Control +Options</a> page.</dd> + +<dt><tt>TEST5</tt></dt> + +<dd>Cryptographic authentication fails. See the <a href= +"authopt.htm">Authentication Options</a> page.</dd> + +<dt><tt>TEST6</tt></dt> + +<dd>The server is unsynchronized. Wind up its clock first.</dd> + +<dt><tt>TEST7</tt></dt> + +<dd>The server stratum is at the maximum than 15. It is probably +unsynchronized and its clock needs to be wound up.</dd> + +<dt><tt>TEST8</tt></dt> + +<dd>Either the root delay or dispersion is greater than one second, +which is highly unlikely unless the peer is synchronized to +Mars.</dd> + +<dt><tt>TEST9</tt></dt> + +<dd>Either the peer delay or dispersion is greater than one second, +which is higly unlikely unless the peer is on Mars.</dd> + +<dt><tt>TEST10</tt></dt> + +<dd>The autokey protocol has detected an authentication failure. +See the <a href="authopt.htm">Authentication Options</a> page.</dd> + +<dt><tt>TEST11</tt></dt> + +<dd>The autokey protocol has not verified the server or peer is +authentic and has valid public key credentials. See the <a href= +"authopt.htm">Authentication Options</a> page.</dd> + +<dt>Additional system variables used by the NTP Version 4 Autokey +support include the following:</dt> + +<dd> +<dl> +<dt><tt>certificate <i>filestamp</i></tt></dt> + +<dd>Shows the NTP seconds when the certificate file was +created.</dd> + +<dt><tt>hostname <i>host</i></tt></dt> + +<dd>Shows the name of the host as returned by the Unix <tt> +gethostname()</tt> library function.</dd> + +<dt><tt>flags <i>hex</i></tt></dt> + +<dd>Shows the current flag bits, where the <tt><i>hex</i></tt> bits +are interpreted as follows:</dd> + +<dd> +<dl> +<dt><tt>0x01</tt></dt> + +<dd>autokey enabled</dd> + +<dt><tt>0x02</tt></dt> + +<dd>RSA public/private key files present</dd> + +<dt><tt>0x04</tt></dt> + +<dd>PKI certificate file present</dd> + +<dt><tt>0x08</tt></dt> + +<dd>Diffie-Hellman parameters file present</dd> + +<dt><tt>0x10</tt></dt> + +<dd>NIST leapseconds table file present</dd> +</dl> +</dd> + +<dt><tt>leapseconds <i>filestamp</i></tt></dt> + +<dd>Shows the NTP seconds when the NIST leapseconds table file was +created.</dd> + +<dt><tt>params <i>filestamp</i></tt></dt> + +<dd>Shows the NTP seconds when the Diffie-Hellman agreement +parameter file was created.</dd> + +<dt><tt>publickey <i>filestamp</i></tt></dt> + +<dd>Shows the NTP seconds when the RSA public/private key files +were created.</dd> + +<dt><tt>refresh <i>timestamp</i></tt></dt> + +<dd>Shows the NTP seconds when the public cryptographic values were +refreshed and signed.</dd> + +<dt><tt>tai <i>offset</i></tt></dt> + +<dd>Shows the TAI-UTC offset in seconds obtained from the NIST +leapseconds table.</dd> +</dl> +</dd> + +<dt>Additional peer variables used by the NTP Version 4 Autokey +support include the following:</dt> + +<dd> +<dl> +<dt><tt>certificate <i>filestamp</i></tt></dt> + +<dd>Shows the NTP seconds when the certificate file was +created.</dd> + +<dt><tt>flags <i>hex</i></tt></dt> + +<dd>Shows the current flag bits, where the <i>hex</i> bits are +interpreted as in the system variable of the same name. The bits +are set in the first autokey message received from the server and +then reset as the associated data are obtained from the server and +stored.</dd> + +<dt><tt>hcookie <i>hex</i></tt></dt> + +<dd>Shows the host cookie used in the key agreement algorithm.</dd> + +<dt><tt>initkey <i>key</i></tt></dt> + +<dd>Shows the initial key used by the key list generator in the +autokey protocol.</dd> + +<dt><tt>initsequence <i>index</i></tt></dt> + +<dd>Shows the initial index used by the key list generator in the +autokey protocol.</dd> + +<dt><tt>pcookie <i>hex</i></tt></dt> + +<dd>Specifies the peer cookie used in the key agreement +algorithm.</dd> + +<dt><tt>timestamp <i>time</i></tt></dt> + +<dd>Shows the NTP seconds when the last autokey key list was +generated and signed.</dd> +</dl> +</dd> +</dl> +</dd> + +<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> + +<dt><tt>readlist [ <i>assocID</i> ]</tt><br> +<tt>rl [ <i>assocID</i> ]</tt></dt> + +<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> + +<dt><tt>readvar <i>assocID</i> <i>variable_name</i> [ = <i> +value</i> ] [ ...]</tt><br> +<tt>rv <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i> ] [ +...]</tt></dt> + +<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> + +<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> + +<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> + +<p>The peers command is non-atomic and may occasionally result in +spurious error messages about invalid associations occurring and +terminating the command. The timeout time is a fixed constant, +which means you wait a long time for timeouts since it assumes sort +of a worst case. The program should improve the timeout estimate as +it sends queries to a particular host, but doesn't.</p> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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 index 3cc4544..c192c13 100644 --- a/contrib/ntp/html/ntptime.htm +++ b/contrib/ntp/html/ntptime.htm @@ -1,96 +1,80 @@ -<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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>ntptime - read kernel time variables</title> +</head> +<body> +<h3><tt>ntptime</tt> - read kernel time variables</h3> -<H3> -<TT>ntptime</TT> - read kernel time variables</H3> +<img align="left" src="pic/pogo5.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Pogo</i>, +Walt Kelly</a> -<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> +<p>The turtle is been swimming in the kernel.<br clear="left"> +</p> -<DL> -<DT> -<TT>-c</TT></DT> +<hr> +<h4>Synopsis</h4> -<DD> -Display the execution time of <TT>ntptime</TT> itself.</DD> +<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> -<DT> -<TT>-e <I>est_error</I></TT></DT> +<h4>Description</h4> -<DD> -Specify estimated error, in microseconds.</DD> +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. -<DT> -<TT>-f <I>frequency</I></TT></DT> +<h4>Options</h4> -<DD> -Specify frequency offset, in parts per million.</DD> +<dl> +<dt><tt>-c</tt></dt> -<DT> -<TT>-h</TT></DT> +<dd>Display the execution time of <tt>ntptime</tt> itself.</dd> -<DD> -Display times in Unix timeval format. Default is NTP format.</DD> +<dt><tt>-e <i>est_error</i></tt></dt> -<DT> -<TT>-l</TT></DT> +<dd>Specify estimated error, in microseconds.</dd> -<DD> -Specify the leap bits as a code from 0 to 3.</DD> +<dt><tt>-f <i>frequency</i></tt></dt> -<DT> -<TT>-m <I>max_error</I></TT></DT> +<dd>Specify frequency offset, in parts per million.</dd> -<DD> -Display help information.</DD> +<dt><tt>-h</tt></dt> -<DT> -<TT>-o <I>offset</I></TT></DT> +<dd>Display help information.</dd> -<DD> -Specify clock offset, in microseconds.</DD> +<dt><tt>-m <i>max_error</i></tt></dt> -<DT> -<TT>-r</TT></DT> +<dd>Specify max possible errors, in microseconds.</dd> -<DD> -Display Unix and NTP times in raw format.</DD> +<dt><tt>-o <i>offset</i></tt></dt> -<DT> -<TT>-s <I>status</I></TT></DT> +<dd>Specify clock offset, in microseconds.</dd> -<DD> -Specify clock status. Better know what you are doing.</DD> +<dt><tt>-r</tt></dt> -<DT> -<TT>-t <I>time_constant</I></TT></DT> +<dd>Display Unix and NTP times in raw format.</dd> -<DD> -Specify time constant, an integer in the range 0-4.</DD> -</DL> +<dt><tt>-s <i>status</i></tt></dt> -<HR> -<ADDRESS> -David L. Mills (mills@udel.edu)</ADDRESS> +<dd>Specify clock status. Better know what you are doing.</dd> + +<dt><tt>-t <i>time_constant</i></tt></dt> + +<dd>Specify time constant, an integer in the range 0-10.</dd> +</dl> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -</BODY> -</HTML> diff --git a/contrib/ntp/html/ntptrace.htm b/contrib/ntp/html/ntptrace.htm index 675c347..28313a5 100644 --- a/contrib/ntp/html/ntptrace.htm +++ b/contrib/ntp/html/ntptrace.htm @@ -1,82 +1,91 @@ -<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 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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> + +<img align="left" src="pic/alice13.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>The rabbit knows the way back.<br clear="left"> +</p> + +<hr> +<h4>Synopsis</h4> + +<tt>ntptrace [ -vdn ] [ -r <i>retries</i> ] [ -t <i>timeout</i> ] [ +<i>server</i> ]</tt> + +<h4>Description</h4> + +<p><tt>ntptrace</tt> determines where a given Network Time Protocol +(NTP) server gets its time from, and follows the chain of NTP +servers back to their master time source. If given no arguments, it +starts with <tt>localhost</tt>. Here is an example of the output +from <tt>ntptrace</tt>:</p> + +<pre> +% 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> +'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> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/patches.htm b/contrib/ntp/html/patches.htm index 154d4b8..ed4c8dd 100644 --- a/contrib/ntp/html/patches.htm +++ b/contrib/ntp/html/patches.htm @@ -4,67 +4,39 @@ Patching Procedures Patching Procedures </h3> -<IMG align=left SRC=pic/rabbit.gif>From <i>pogo</i>, Walt Kelly +<img align=left src=pic/alice38.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm> +from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>The Mad Hatter needs patches. <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. +<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 submit patches to <a href=mailto:bugs@mail.ntp.org>Bugs <bugs@mail.ntp.org></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 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><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>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>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 <tt>compress</tt> 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>Don't forget the documentation that may be affected by the patch. Send us patches for the <tt>./htm</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> +<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>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> +<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 index d541d4e..4015d61 100644 --- a/contrib/ntp/html/porting.htm +++ b/contrib/ntp/html/porting.htm @@ -2,7 +2,13 @@ Porting Hints </title></head><body><h3> Porting Hints -</h3><hr> +</h3> + +<img align=left src=pic/wingdorothy.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>The +Wizard of Oz</i>, L. Frank Baum</a> + +<p>Porting Dorothy in Oz. +<br clear=left><hr> <p>NOTE: The following procedures have been replaced by GNU automake and autoconfigure. This page is to be updated in the next release. diff --git a/contrib/ntp/html/pps.htm b/contrib/ntp/html/pps.htm index 97850d7..a20dd4d 100644 --- a/contrib/ntp/html/pps.htm +++ b/contrib/ntp/html/pps.htm @@ -1,84 +1,106 @@ -<html><head><title> -Pulse-per-second (PPS) Signal Interfacing -</title></head><body><h3> -Pulse-per-second (PPS) Signal Interfacing -</h3><hr> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Pulse-per-second (PPS) Signal Interfacing</title> +</head> +<body> +<h3>Pulse-per-second (PPS) Signal Interfacing</h3> -<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. +<img align="left" src="pic/alice32.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> -<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>Alice is trying to find the PPS signal connector.<br clear= +"left"> +</p> -<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. +<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 10 <font face="Symbol">m</font>s in time and +0.01 parts-per-million (PPM) in frequency. The PPS signal can be +connected in either of two ways: via the data carrier detector +(DCD) pin of a serial port or via the acknowledge (ACK) pin of a +parallel port, depending on the hardware and operating system. +Connection via a serial port may require signal conversion and +regeneration 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. Note that NTP no longer supports +connection via the data leads of a serial port.</p> -<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>Both the serial and parallel port connection require operating +system support, which is available in only a few operating systems, +including Linux, FreeBSD and latest Solaris beginning with 2.7. +Support on an experimental basis is available for several older +systems, including SunOS, Digital Ultrix and HP-UX, and in current +Digital Tru64 (Alpha). The PPS application program interface +defined in RFC-2783 (PPSAPI) is the only interface currently +supported. Older PPS interfaces based on the <tt>ppsclock</tt> and +<tt>tty_clk</tt> streams modules are no longer supported. As the +PPSAPI is expected to become an IETF cross-platform standard, it +should be used by new applications.</p> -<P>The 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>The PPSAPI inerface requires a <tt> +/usr/include/sys/ppstime.h</tt> header file. This file is included +in Linux and FreeBSD distributions, but not in other distributions +or standard workstation products at this time. Header files for +other systems, including Solaris, can be found in the <tt> +nanokernel.tar.gz</tt> distribution, which can be found via the +Collaboration Resources link at www.ntp.org. The top level +directory contains a number of subdirectories for each +architecture, including Solaris. The <tt>ppstime.h</tt> file for +each architecture can be found in the subdirectory of the same +name.</p> -<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 the preferred mode of operation, PPS signals are processed by +the <a href="driver22.htm">PPS Clock Discipline</a> driver and +other clock drivers which might be involved need not know or care +about them. In some cases where there is no other driver, time +might be obtained from remote NTP servers via the network and local +PPS signals, for instance from a calibrated cesium oscillator, used +to stabilize the frequency and remove network jitter. Note that the +<tt>pps</tt> configuration command has been obsoleted by this +driver.</p> -<P>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. +<p>The PPS driver operates in conjunction with a preferred peer, 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 or another +NTP server furnishes the coarse timing and disambiguates the +seconds numbering of the PPS signal itself. The NTP daemon +mitigates between the clock driver or NTP server and the PPS driver +as described in that page in order to provide the most accurate +time, while respecting the various types of equipment failures that +could happen.</p> + +<p>Some Unix system kernels support a PPS signal directly, as +described in the <a href="kern.htm">A Kernel Model for Precision +Timekeeping</a> page. Specifically, the PPS driver can be used to +direct the PPS signal to the kernel for use as a discipline source +for both time and frequency. The presence of the kernel support is +automatically detected during the NTP build process and supporting +code automatically compiled. Note that the PPS driver does not +normally enable the PPS kernel code, since performance is generally +better without it. However, this code can be enabled by a driver +fudge flag if necessary.</p> + +<p>Some configurations may include multiple radio clocks with +individual PPS outputs. In some PPSAPI designs multiple PPS signals +can be connected to multiple instances of the PPS driver. In such +cases the NTP mitigation and grooming algorithms operate with all +the radio timecodes and PPS signals to develop the highest degree +of redundancy and survivability.</p> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a><br> +<br> + + +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<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 index edb5152..57a047a 100644 --- a/contrib/ntp/html/prefer.htm +++ b/contrib/ntp/html/prefer.htm @@ -1,332 +1,93 @@ -<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> +<html><head><title> +Mitigation Rules and the <tt>prefer</tt> Keyword +</title></head><body><h3> +Mitigation Rules and the <tt>prefer</tt> Keyword +</h3> + +<img align=left src=pic/alice11.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm> +from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>Listen carefully to what I say; it is very complicated. +<br clear=left><hr> + +<h4>Introduction</h4> + +The mechanics of the NTP algorithms which select the best data sample from each available server and the best subset of the server population have been finely crafted to resist network jitter, faults in the network or server operations, and to deliver the best possible accuracy. Most of the time these algorithms do a good job without requiring explicit manual tailoring of the configuration file. However, there are times when the accuracy can be improved by some careful tailoring. The following sections explain how to do this using explicit configuration items and special signals, when available, that are generated by some radio clocks and laboratory instruments. + +<p>In order to provide robust backup sources, primary (stratum-1) servers are usually operated in a diversity configuration, in which the server operates with a number of remote servers in addition to one or more radio or modem clocks. In these configurations the suite of algorithms used in NTP to refine the data from each peer separately and to select and combine the data from a number of servers and clocks. As the result of these algorithms, a set of <i>survivors</i> are identified which can presumably provide the most reliable and accurate time. Ordinarily, the individual clock offsets of the survivors are combined on a weighted average basis to produce an offset used to control the system clock. + +<p>However, because of small but significant systematic time offsets between the survivors, it is in general not possible to achieve the lowest jitter and highest stability in these configurations. This happens because the selection algorithm tends to <i>clockhop</i> between survivors of substantially the same quality, but showing small systematic offsets between them. In addition, there are a number of configurations involving pulse-per-second (PPS) signals, modem backup services and other special cases, so that a set of mitigation rules becomes necessary to select a single peer from among the survivors. These rules are based on a set of special characteristics of the various remote servers and reference clock drivers specified in the configuration file. + +<h4>The <tt>prefer</tt> Peer</h4> + +The mitigation rules are designed to provide an intelligent selection between various sources of substantially the same statistical quality without compromising the normal operation of the NTP algorithms. While they have been implemented in NTP Version 4 and will be incorporated in the NTP Version 4 specification when published, they are not in the NTP Version 3 specification RFC-1305. The rules are based on the concept of <i>prefer peer</i>, which is specified by including the <tt>prefer</tt> keyword with the associated <tt>server</tt> or <tt>peer</tt> command in the configuration file. This keyword can be used with any server or peer, but is most commonly used with a radio clock. While the rules do not forbid it, it does not seem useful to designate more than one peer as preferred, since the additional complexities to mitigate among them do not seem justified from on-air experience. + +<p>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 RFC-1305, is beyond the scope of discussion here. It operates in rounds, where a survivor, presumably the worst of the lot, is discarded in each round until one of several termination conditions is met. An example terminating condition is when the number of survivors is about to be reduced below three. + +<p>In the prefer scheme the clustering algorithm is modified so that the prefer peer is never discarded; on the contrary, its potential removal becomes a termination condition. If the original algorithm were about to toss out the prefer peer, the algorithm terminates immediately. The prefer peer can still be discarded by the sanity checks and intersection 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 serves and local radio clocks as a function of configuration declarations and 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> + +<li>When a PPS signal is connected via the PPS Clock Discipline driver (type 22), this is called the <i>PPS peer</i>. This driver provides precision clock corrections only within one second, so is always operated in conjunction with another server or radio clock driver, which provides the seconds numbering. The PPS peer is active only under conditions explained below.</li> + +<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> + +<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> + +<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> + +<p>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 a remote server or local radio clock. In order to provide the best stability, the operation of the clock discipline algorithm changes gradually from a phase-lock mode at the shorter update intervals to a frequency-lock mode at the longer update intervals. If remote servers or local radio clocks together with a modem peer operate in the same client, the following things can happen. + +<p>First the clock selection algorithm can select one or more remote servers or radio clocks and the clock discipline algorithm will optimize for the shorter update intervals. Then, the selection algorithm can select the modem peer, which requires a much different optimization. The intent in the design is to allow the modem peer to control the system clock either when no other source is available or, if the modem peer happens to be marked as prefer, then it always controls the clock, as long as it passes the sanity checks and intersection algorithm. There still is room for suboptimal operation in this scheme, since a noise spike can still cause a clockhop either way. Nevertheless, the optimization function is slow to adapt, so that a clockhop or two does not cause much harm. + +<p>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>PPS support requires the PPS driver (type 22) and PPSAPI interface described in the <a href=pps.htm>Pulse-per-second (PPS) Signal Interfacing></a> page. In order to operate, the prefer peer must be designated and the kernel support enabled by the <tt>enable pps</tt> command in the configuration file and the signal must be present and within nominal jitter and wander error tolerances. In the NTP daemon, the PPS discipline is active only when the prefer peer is among the survivors of the clustering algorithm, and its absolute offset is within 128 ms, as determined by the PPS driver. Under these conditions the kernel disregards updates produced by the NTP daemon and uses its internal PPS source instead. The kernel maintains a watchdog timer for the PPS signal; if the signal has not been heard or is out of tolerance for more than some interval, currently two minutes, the kernel discipline is declared inoperable and operation continues as if it were not present. + +<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/quick.htm b/contrib/ntp/html/quick.htm index 5ce0099..4eecf82 100644 --- a/contrib/ntp/html/quick.htm +++ b/contrib/ntp/html/quick.htm @@ -1,99 +1,100 @@ -<HTML><HEAD><TITLE> -Quick Start -</TITLE></HEAD><BODY><H3> -Quick Start -</H3> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Quick Start</title> +</head> +<body> +<h3>Quick Start</h3> -<img align=left src=pic/panda.gif>FAX test image for SATNET (1979). +<img align="left" src="pic/panda.gif" alt="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> +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"> +</p> -<H4>Introduction</H4> +<hr> +<p>For the rank amateur the sheer volume of the documentation +collection must be intimidating. However, it doesn't take much to +fly the <tt>ntpd</tt> daemon with a simple configuration where a +workstation needs to synchronize to some server elsewhere in the +Internet. The first thing that needs to be done is to build the +distribution for the particular workstation and install in the +usual place. The <a href="build.htm">Building and Installing the +Distribution</a> page describes how to do this.</p> -<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>While it is possible that certain configurations do not need a +configuration file, most do require one. Strictly speaking, the +file need only contain one line specifying a remote server, for +instance</p> -<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><tt>server foo.bar.com</tt></p> -<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>Choosing an appropriate remote server is somewhat of a black +art, but a suboptimal choice is seldom a problem. Links to public +time servers operated by National Institutes of Science and +Technology (NIST), US Naval Observatory (USNO), Canadian Metrology +Centre (CMC) and many others are given in the home page of this +document collection. The lists are sorted by country and, in the +case of the US, by state. Usually, the best choice is the nearest +in geographical terms, but the terms of engagement specified in +each list entry should be carefully respected.</p> -<p>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>During operation <tt>ntpd</tt> measures and corrects for +incidental clock frequency error and writes the current value to a +file if enabled. If the <tt>ntpd</tt> is stopped and restarted, it +initializes the frequency from this file. In this way the +potentially lengthy interval to relearn the frequency error is +avoided. Thus, for most applications an additional line should be +added to the file of the form</p> -<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><tt>driftfile /etc/ntp.drift</tt></p> -<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. +<p>That's all there is to it, unless some problem in network +connectivity or local operating system configuration occurs. The +most common problem is some firewall between the workstation and +server. System administrators should understand NTP uses UDP port +123 as both the source and destination port and that NTP does not +involve any operating system interaction other than to set the +system clock. While almost all modern Unix systems have included +NTP and UDP port 123 defined in the services file, this should be +checked if <tt>ntpd</tt> fails to come up at all.</p> -<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> +<p>The best way to confirm NTP is working is using the <a href= +"ntpq.htm"><tt>ntpq</tt></a> utility, although the <a href= +"ntpdc.htm"><tt>ntpdc</tt></a> utility may be useful in extreme +cases. See the documentation pages for further information. In the +most extreme cases the <tt>-d</tt> option on the <tt>ntpd</tt> +command line results in a blow-by-blow trace of the daemon +operations. While the trace output can be cryptic, to say the +least, it gives a general idea of what the program is doing and, in +particular, details the arriving and departing packets and detected +errors, if present.</p> + +<p>Sometimes the <tt>ntpd</tt>. behavior may seem to violate the +Principle of Least Astonishment, but there are good reasons for +this. See the <a href="ntpd.htm">Network Time Protocol (NTP) +daemon</a> page for revealing insights. See this page and its +dependencies for additional configuration and control options. The +<a href="notes.htm">Notes on Configuring NTP and Setting up a NTP +Subnet</a> page contains an extended discussion of these +options.</p> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/rdebug.htm b/contrib/ntp/html/rdebug.htm index 472b09f..bc998ca 100644 --- a/contrib/ntp/html/rdebug.htm +++ b/contrib/ntp/html/rdebug.htm @@ -1,67 +1,25 @@ -<!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> +</h3> -<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. +<img align=left src=pic/oz2.gif><a href=http://www.eecis.udel.edu/~mills/pictures.htm>from <i>The +Wizard of Oz</i>, L. Frank Baum</a> -<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>Call the girls and the'll sweep your bugs. +<br clear=left><hr> -<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>The <a href=ntpq.htm><tt>ntpq</tt></a> and <a href=ntpdc.htm><tt>ntpdc</tt></a> utility programs can be used to debug reference clocks, either on the server itself or from another machine elsewhere in the network. The server is compiled, installed and started using the configuration file described in the <a href=ntpd.htm><tt>ntpd</tt></a> page and its dependencies. If the clock appears in the <tt>ntpq</tt> utility and <tt>pe</tt> command, no errors have occured and the daemon has started, opened the devices specified and waiting for peers and radios to come up. If not, the first thing to look for are error messages on the system log. These are usually due to improper configuration, missing links or multiple instances of the daemon. -<p>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>It normally takes a minute or so for evidence to appear that the clock is running and the driver is operating correctly. The first indication is a nonzero value in the <tt>reach</tt> column in the <tt>pe</tt> billboard. If nothing appears after a few minutes, the next step is to be sure the RS232 messages, if used, are getting to and from the clock. The most reliable way to do this is with an RS232 tester and to look for data flashes as the driver polls the clock and/or as data arrive from the clock. Our experience is that the overwhelming fraction of problems occurring during installation are due to problems such as miswired connectors or improperly configured device links at this stage. -<p>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>If RS232 messages are getting to and from the clock, the variables of interest can be inspected using the <tt>ntpq</tt> program and various commands described on the documentation page. First, use the <tt>pe</tt> and <tt>as</tt> commands to display billboards showing the peer configuration and association IDs for all peers, including the radio clock. The assigned clock address should appear in the <tt>pe</tt> billboard and the association ID for it at the same relative line position in the <tt>as</tt> billboard. -<p>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> +<p>Additional information is available with the <tt>rv</tt> and <tt>clockvar</tt> commands, which take as argument the association ID shown in the <tt>as</tt> billboard. The <tt>rv</tt> command with no argument shows the system variables, while the <tt>rv</tt> command with association ID argument shows the peer variables for the clock, as well as other peers of interest. The <tt>clockvar</tt> command with argument shows the peer variables specific to reference clock peers, including the clock status, device name, last received timecode (if relevant), and various event counters. In addition, a subset of the <tt>fudge</tt> parameters is included. The poll and error counters in the <tt>clockvar</tt> billboard are useful debugging aids. The <tt>poll</tt> counts the poll messages sent to the clock, while the <tt>noreply</tt>, <tt>badformat</tt> and <tt>baddate</tt> count various errors. Check the timecode to be sure it matches what the driver expects. This may require consulting the clock hardware reference manual, which is probably pretty dusty at this stage. + +<p>The <tt>ntpdc</tt> utility program can be used for detailed inspection of the clock driver status. The most useful are the <tt>clockstat</tt> and <tt>clkbug</tt> commands described in the document page. While these commands permit getting quite personal with the particular driver involved, their use is seldom necessary, unless an implementation bug shows up. If all else fails, turn on the debugging trace using two <tt>-d</tt> flags in the <tt>ntpd</tt> startup command line. Most drivers will dump status at every received message in this case. While the displayed trace can be intimidating, this provides the most detailed and revealing indicator of how the driver and clock are performing and where bugs might lurk. + +<p>Most drivers write a message to the <tt>clockstats</tt> file as each timecode or surrogate is received from the radio clock. By convention, this is the last ASCII timecode (or ASCII gloss of a binary-coded one) received from the radio clock. This file is managed by the <tt>filegen</tt> facility described in the <tt>ntpd</tt> page and requires specific commands in the configuration file. This forms a highly useful record to discover anomalies during regular operation of the clock. The scripts included in the <tt>./scripts/stats</tt> directory can be run from a <tt>cron</tt> job to collect and summarize these data on a daily or weekly basis. The summary files have proven inspirational to detect infrequent misbehavior due to clock implementation bugs in some radios. + +<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/refclock.htm b/contrib/ntp/html/refclock.htm index 80c62a2..4b2611d 100644 --- a/contrib/ntp/html/refclock.htm +++ b/contrib/ntp/html/refclock.htm @@ -1,157 +1,250 @@ -<html><head><title> -Reference Clock Drivers -</title></head><body><h3> -Reference Clock Drivers -</H3> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Reference Clock Drivers</title> +</head> +<body> +<h3>Reference Clock Drivers</h3> -<IMG ALIGN=LEFT SRC=pic/tardisa.gif>From top: +<img align="left" src="pic/stack1a.jpg" alt="gif">Master Time +Facility at the <a href="http://www.eecis.udel.edu/~mills/lab.htm"> +UDel Internet Research Laboratory</a>: <br clear="left"> +<hr> +<p>Support for most of the commonly available radio and modem +reference clocks is included in the default configuration of the +NTP daemon for Unix <tt>ntpd</tt>. Individual clocks can be +activated by configuration file commands, specifically the <tt> +server</tt> and <tt>fudge</tt> commands described in the <a href= +"ntpd.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> + +<p>Many radio reference clocks can be set to display local time as +adjusted for timezone and daylight saving mode. For use with NTP +the clock must be set for Coordinated Universal Time (UTC) only. +Ordinarily, these adjustments are performed by the kernel, so the +fact that the clock runs on UTC will be transparent to the +user.</p> + +<p>Radio and modem clocks by convention have addresses in the form +127.127.<i>t.u</i>, where <i>t</i> is the clock type and <i>u</i> +is a unit number in the range 0-3 used to distinguish multiple +instances of clocks of the same type. Most of these clocks require +support in the form of a serial port or special bus peripheral, but +some can work directly from the audio codec found in some +workstations. The particular device is normally specified by adding +a soft link <tt>/dev/device<i>u</i></tt> to the particular hardware +device involved, where <i><tt>u</tt></i> correspond to the unit +number above.</p> + +<p>Most clock drivers communicate with the reference clock using a +serial port, usually at 9600 bps. There are several application +program interfaces (API) used in the various Unix and NT systems, +most of which can be detected at configuration time. Thus, it is +important that the NTP daemon and utilities be compiled on the +target system or clone. In some cases special features are +available, such as timestamping in the kernel or pulse-per-second +(PPS) interface. In most cases these features can be detected at +configuration time as well; however, the kernel may have to be +recompiled in order for them to work.</p> + +<p>The audio drivers are a special case. These include support for +the NIST time/frequency stations WWV and WWVH, the Canadian +time/frequency station CHU and generic IRIG signals. Currently, +support for the Solaris and SunOS audio API is included in the +distribution. It is left to the volunteer corps to extend this +support to other systems. Further information on hookup, debugging +and monitoring is given in the <a href="audio.htm">Audio +Drivers</a> page.</p> + +<p>The local clock driver is also a special case. A server +configured with this driver can operate as a primary server to +synchronize other clients when no other external synchronization +sources are available. If the server is connected directly or +indirectly to the public Internet, there is some danger that it can +adversely affect the operation of unrelated clients. Carefully read +the <a href="driver1.htm">Undisciplined Local Clock</a> page and +respect the stratum limit.</p> + +<p>The local clock driver also supports an external synchronization +source such as a high resolution counter disciplined by a GPS +receiver, for example. Further information is on the <a href= +"extern.htm">External Clock Discipline and the Local Clock +Driver</a> page.</p> + +<h4>Driver Calibration</h4> + +<p>Some drivers depending on longwave and shortwave radio services +need to know the radio propagation time from the transmitter to the +receiver, which can amount to some tens of milliseconds. This must +be calculated for each specific receiver location and requires the +geographic coordinates of both the transmitter and receiver. The +transmitter coordinates for various radio services are given in the +<a href="qth.htm">Stations, Frequencies and Geographic +Coordinates</a> page. Receiver coordinates can be obtained or +estimated from various sources. The actual calculations are beyond +the scope of this document.</p> -<UL> +<p>When more than one clock driver is supported, it is often the +case that each shows small systematic offset differences relative +to the rest. To reduce the effects of jitter when switching from +one driver to the another, it is useful to calibrate the drivers to +a common ensemble offset. The <tt>enable calibrate</tt> +configuration command in the <a href="miscopt.htm">Miscellaneous +Options</a> page is useful for this purpose. The calibration +function can also be enabled and disabled using the <tt>ntpdc</tt> +program utility.</p> -<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> +<p>Most clock drivers use the <tt>time1</tt> value specified in the +<tt>fudge</tt> configuration command to provide the calibration +correction when this cannot be provided by the clock or interface. +When the calibration function is enabled, the <tt>time1</tt> value +is automatically adjusted to match the offset of the remote server +or local clock driver selected for synchronization. Ordinarily, the +NTP selection algorithm chooses the best from among all sources, +usually the best radio clock determined on the basis of stratum, +synchronization distance and jitter. The calibration function +adjusts the <tt>time1</tt> values for all clock drivers except this +source so that their indicated offsets tend to zero. If the +selected source is the kernel PPS discipline, the <tt>fudge +time1</tt> values for all clock drivers are adjusted.</p> -</UL> +<p>The adjustment function is an exponential average designed to +improve accuracy, so the function takes some time to converge. The +recommended procedure is to enable the function, let it run for an +hour or so, then edit the configuration file using the <tt> +time1</tt> values displayed by the <tt>ntpq</tt> utility and <tt> +clockvar</tt> command. Finally, disable the calibration function to +avoid possible future disruptions due to misbehaving clocks or +drivers.</p> + +<h4>Performance Enhancements</h4> + +<p>In general, performance can be improved, especially when more +than one clock driver is supported, to use the prefer peer function +described in the <a href="prefer.htm">Mitigation Rules and the <tt> +prefer</tt> Keyword</a> page. The prefer peer is ordinarily +designated the remote peer or local clock driver which provides the +best quality time. All other things equal, only the prefer peer +source is used to discipline the system clock and jitter-producing +"clockhopping" between sources is avoided. This is valuable when +more than one clock driver is present and especially valuable when +the PPS clock driver (type 22) is used. Support for PPS signals is +summarized in the <a href="pps.htm">Pulse-per-second (PPS) Signal +Interfacing</a> page.</p> + +<p>Where the highest performance is required, generally better than +one millisecond, additional hardware and/or software functions may +be required. Kernel modifications for precision time are described +in the <a href="kern.htm">A Kernel Model for Precision +Timekeeping</a> page. Special line discipline and streams modules +for use in capturing precision timestamps are described in the <a +href="ldisc.htm">Line Disciplines and Streams Drivers</a> page.</p> + +<h4>Comprehensive List of Clock Drivers</h4> + +<p>Following is a list showing the type and title of each driver +currently implemented. The compile-time identifier for each is +shown in parentheses. Click on a selected type for specific +description and configuration documentation, including the clock +address, reference ID, driver ID, device name and serial line +speed, and features (line disciplines, etc.). For those drivers +without specific documentation, please contact the author listed in +the <a href="copyright.htm">Copyright Notice</a> page.</p> + +<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 WWVB and GPS 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> Radio CHU Audio +Demodulator/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> +<a href="driver16">Type 16</a> 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</a> Motorola UT Oncore GPS +(<tt>GPS_ONCORE</tt>)<br> +Type 31 Rockwell Jupiter GPS (<tt>GPS_JUPITER</tt>)<br> +<a href="driver32.htm">Type 32</a> Chrono-log K-series WWVB +receiver <a href="driver33.htm">Type 33</a> Dumb Clock <a href= +"driver34.htm">Type 34</a> Ultralink WWVB Receivers<br> +<a href="driver35.htm">Type 35</a> Conrad Parallel Port Radio Clock +(<tt>PCF</tt>)<br> +<a href="driver36.htm">Type 36</a> Radio WWV/H Audio +Demodulator/Decoder(<tt>WWV</tt>)<br> +<a href="driver37.htm">Type 37</a> Forum Graphic GPS Dating station +(<tt>FG</tt>)<br> +<a href="driver38.htm">Type 38</a> hopf GPS/DCF77 6021/komp for +Serial Line (<tt>HOPF_S</tt>)<br> +<a href="driver39.htm">Type 39</a> hopf GPS/DCF77 6039 for PCI-Bus +(<tt>HOPF_P</tt>)</p> + +<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> + +<p>Additional Information</p> + +<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="kern.htm">A Kernel Model for Precision Timekeeping</a><br> +<a href="ldisc.htm">Line Disciplines and Streams Drivers</a><br> +<a href="audio.htm">Reference Clock Audio 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></p> -<br clear=left> -The Tardis <hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> -Support for most of the commonly available radio and modem reference -clocks is included in the default configuration of the NTP daemon for -Unix <TT>ntpd</TT>. Individual clocks can be activated by configuration -file commands, specifically the <TT>server</TT> and <TT>fudge</TT> -commands described in the <A HREF=ntpd.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. +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> -<p>Most clock drivers communicate with the reference clock using a -serial port, usually at 9600 bps. There are several application program -interfaces (API) used in the various Unix and NT systems, most of which -can be detected at configuration time. Thus, it is important that the -NTP daemon and utilities be compiled on the target system or clone. In -some cases special features are available, such as timestamping in the -kernel or pulse-per-second (PPS) interface. In most cases these features -can be detected at configuration time as well; however, the kernel may -have to be recompiled in order for them to work. - -<p>The audio drivers are a special case. These include support for the -NIST time/frequency stations WWV and WWVH, the Canadian time/frequency -station CHU and generic IRIG signals. Currently, support for the Solaris -and SunOS audio API is included in the distribution. It is left to the -volunteer corps to extend this support to other systems. Further -information on hookup, debugging and monitoring is given in the <a -href=audio.htm>Audio Drivers</a> page. - -<p>Some drivers depending on longwave and shortwave radio services need -to know the radio propagation time from the transmitter to the receiver, -which can amount to some tens of milliseconds. This must be calculated -for each specific receiver location and requires the geographic -coordinates of both the transmitter and receiver. The transmitter -coordinates for various radio services are given in the <a -href=qth.htm>Stations, Frequencies and Geographic Coordinates</a> page. -Receiver coordinates can be obtained or estimated from various sources. -The actual calculations are beyond the scope of this document. - -<P>Following is a list showing the type and title of each driver -currently implemented. The compile-time identifier for each is shown in -parentheses. Click on a selected type for specific description and -configuration documentation, including the clock address, reference ID, -driver ID, device name and serial line speed, and features (line -disciplines, etc.). For those drivers without specific documentation, -please contact the author listed in the <A HREF=copyright.htm>Copyright -Notice</A> page. - -<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 WWVB and GPS 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> Radio CHU Audio Demodulator/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</A> 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 -<BR><A HREF=driver35.htm>Type 35</A> Conrad Parallel Port Radio Clock -(<TT>PCF</TT>) -<BR><A HREF=driver36.htm>Type 36</A> Radio WWV/H Audio -Demodulator/Decoder(<TT>WWV</TT>) -<BR><A HREF=driver37.htm>Type 37</A> Forum Graphic GPS Dating station -(<TT>FG</TT>) - -<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=audio.htm>Reference Clock Audio 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 index 8b29cb9..9dcef7c 100644 --- a/contrib/ntp/html/release.htm +++ b/contrib/ntp/html/release.htm @@ -1,199 +1,290 @@ -<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 +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>NTP Version 4 Release Notes</title> +</head> +<body> +<h3>NTP Version 4 Release Notes</h3> + +<img align="left" src="pic/hornraba.gif" alt="gif"><a href= +"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's +Adventures in Wonderland</i>, Lewis Carroll</a> + +<p>The rabbit toots to make sure you read this.<br clear="left"> +</p> + +<hr> +<p>This document was last updated 4 May 2001</p> + +<h4>NTP Version 4 Release Notes</h4> + +<p>This release of the NTP Version 4 (NTPv4) daemon for Unix, VMS +and Windows (NT4 and 2000) incorporates new features and +refinements to the NTP Version 3 (NTPv3) algorithms. However, it +continues the tradition of retaining backwards compatibility with +older versions, except for symmetric mode in NTPv1. Client/server +mode continues to be supported in NTPv1. The NTPv4 version has been +under development for quite a while and isn't finished yet. In +fact, quite a number of NTPv4 features have already been +retrofitted in the current NTPv3, although this version is not +actively maintained by the NTPv4 developer's group.</p> + +<p>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 2000, VMS and various reference +clock drivers. As always, corrections and bugfixes are warmly +received, especially in the form of context diffs.</p> + +<p>This note summarizes the differences between this software +release of NTPv4, called ntp-4.x.x, and the previous NTPv3 version, +called xntp3-5.x.x. Additional information on protocol +compatibility details is in the <a href="biblio.htm">Protocol +Conformance Statement</a> page.</p> + +<ol> +<li> +<p>Most calculations are now done using 64-bit floating double +format, rather than 64-bit fixed point format. The motivation for +this is to reduce size, improve speed and avoid messy bounds +checking. Workstations of today are much faster than when the +original NTP version was designed in the early 1980s, and it is +rare to find a processor architecture that does not support +floating double. The fixed point format is still used with raw +timestamps, in order to retain the full precision of about 212 +picoseconds. However, the algorithms which process raw timestamps +all produce fixed point differences before converting to floating +double. The differences are ordinarily quite small so can be +expressed without loss of accuracy in this format.</p> +</li> + +<li> +<p>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.</p> +</li> + +<li> +<p>This release includes support for the <a href= +"http://www.eecis.udel.edu/~mills/resource.htm"><i> +nanokernel</i></a> precision time kernel support, which is now in +stock Linux and FreeBSD kernels. If a precision time source such as +a GPS timing receiver or cesium clock is available, kernel +timekeeping can be improved to the order less than one microsecond. +The older precision time kernel for the Alpha continues to be +supported.</p> +</li> + +<li> +<p>This release includes support for Autokey public-key +cryptography, which is the preferred scheme for authenticating +servers to clients. It uses NTP header extensions fields documented +in: Mills, D.L. Public-Key cryptography for the Network Time +Protocol. Internet Draft draft-ietf-stime-ntpauth-00.txt, +University of Delaware, June 2000, 36 pp. <a href= +"http://www.eecis.udel.edu/~mills/database/memos/draft-ietf-stime-ntpauth-00.txt"> +ASCII</a> and implemented in this release. The design provides for +orderly key refreshment and does not require public keys and +related media to be copied from one machine to another. Specific +information about Autokey cryptography is contained in the <a href= +"authopt.htm">Authentication Options</a> page and links from +there.</p> +</li> + +<li> +<p>NTPv4 includes two new association modes which in most +applications can avoid per-host configuration altogether. Both of +these are based on IP multicast technology and Autokey +cryptography. They provide for automatic discovery and +configuration of servers and clients without identifying servers or +clients in advance. In multicast mode a server sends a message at +fixed intervals using specified multicast group addresses, while +clients listen on these addresses. 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 manycast mode a client sends a message to a specified +multicast group address and expects one or more servers to reply. +Using engineered algorithms, the client selects an appropriate +subset of servers from the messages received and continues in +ordinary client/server operation. 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, +additional network overhead. See the <a href="assoc.htm"> +Association Management</a> page for further information.</p> +</li> + +<li> +<p>There are two burst mode features available where special +conditions apply. One of these is enabled by the <tt>iburst</tt> +keyword in the <tt>server</tt> configuration command. It is +intended for cases where it is important to set the clock quickly +when an association is first mobilized. The other is enabled by the +<tt>burst</tt> keyword in the <tt>server</tt> configuration +command. It is intended for cases where the network attachment +requires an initial calling or training procedure. See the <a href= +"assoc.htm">Association Management</a> page for further +information.</p> +</li> + +<li> +<p>The reference clock driver interface is smaller, more rational +and more accurate. Support for pulse-per-second (PPS) signals has +been extended to all drivers as an intrinsic function. Most of the +drivers in NTPv3 have been converted to 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 +for a total of 39 drivers. Drivers for the Canadian standard time +and frequency station CHU, the US standard time and frequency +stations WWV/H and for IRIG signals have been updated and +capabilities added to allow direct connection of these signals to +the Sun audio port <tt>/dev/audio</tt>.</p> +</li> + +<li> +<p>In all except a very few cases, all timing intervals are +randomized, so that the tendency for NTPv3 to self-synchronize and +bunch messages, especially with a large number of configured +associations, is minimized.</p> +</li> + +<li> +<p>In NTPv3 a large number of weeds and useless code had grown over +the years since the original NTPv1 code was implemented almost +twenty years ago. Using a powerful weedwacker, much of the +shrubbery has been removed, with effect a substantial reduction in +size of almost 40 percent.</p> +</li> + +<li> +<p>The entire distribution has been converted to gnu <tt> +automake</tt>, which should greatly ease the task of porting to new +and different programming environments, as well as reduce the +incidence of bugs due to improper handling of idiosyncratic kernel +functions.</p> +</li> +</ol> + +<h4>Nasty Surprises</h4> + +<p>There are a few things different about this release that have +changed since the latest NTP Version 3 release. Following are a few +things to worry about:</p> + +<ol> +<li> +<p>As required by Defense Trade Regulations (DTR), the +cryptographic routines supporting the Data Encryption Standard +(DES) have been removed from the base distribution. 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.</p> +</li> + +<li> +<p>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> +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.</p> +</li> + +<li> +<p>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. Note that the <tt>authenticate</tt> +command has been removed.</p> +</li> + +<li> +<p>The <tt>ppsclock</tt> line discipline/streams module is no +longer supported. This function is now handled by the <a href= +"driver22.htm">PPS Clock Discipline</a> driver, which uses the new +PPSAPI application program interface proposed by the IETF. Note +that the <tt>pps</tt> configuration file command has been obsoleted +by the driver. See the <a href="pps.htm">Pulse-per-second (PPS) +Signal Interfacing</a> page for further information.</p> +</li> + +<li> +<p>Several new options have been added for the <tt>ntpd</tt> +command line. For the inveterate knob twiddlers several of the more +important performance variables can be changed to fit actual or +perceived special conditions. It is possible to operate the daemon +in a one-time mode similar to <tt>ntpdate</tt>, which program is +headed for retirement. See the <a href="ntpd.htm"><tt>ntpd</tt> - +Network Time Protocol (NTP) daemon</a> page for the new +features.</p> +</li> + +<li> +<p>To help reduce the level of spurious network traffic due to +obsolete configuration files, a special control message called the +kiss-of-death packet has been implemented. If enabled and a packet +is denied service or exceeds the client limie, a compliant server +will send this message to the client. A compliant client will cease +further transmission and send a message to the system log. See the +<a href="accopt.htm">Authentication Options</a> page for further +information.</p> +</li> + +<li> +<p>An experimental filter algorithm called huff-n'-puff has been +implemented to reduce errors under conditions of severe assymetric +delays characteristic of <tt>ppp</tt> connections with telephone +modems and downloading or uploading considerable traffic. See the +<a href="ntpd.htm">ntpd - Network Time Protocol (NTP) daemon</a> +page for further information.</p> +</li> +</ol> + +<h4>Caveats</h4> + +<p>This release has been compiled and tested on several systems, +including SunOS 4.1.3, Solaris 2.5.1-2.8, Alpha 4.0, Ultrix 4.4, +Linux, FreeBSD and HP-UX 10.02. It has been compiled and tested on +Windows NT, but not yet on any other Windows version or for VMS. We +are relying on the NTP volunteer corps to do that. Known problems +are summarized below:</p> + +<ol> +<li> +<p>The latest NTPv4 <tt>ntpdc</tt> does not work with previous +versions of <tt>ntpd</tt> and previous versions of <tt>ntpdc</tt> +do not work with latest <tt>ntpd</tt>. This situation is +regrettable and may be fixed in future; however, it is necessary in +order for the autokey function to retrieve canonical names and +certificates from directory services such as Secure DNS.</p> +</li> + +<li> +<p>The precision time support in stock Solaris 2.6 has bugs that +were fixed in 2.7. A patch is available that fixes the 2.6 bugs. +The 2.6 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>.</p> +</li> + +<li> +<p>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.</p> +</li> +</ol> + +<hr> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"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/tickadj.htm b/contrib/ntp/html/tickadj.htm index 7dc11c0..3d9745e 100644 --- a/contrib/ntp/html/tickadj.htm +++ b/contrib/ntp/html/tickadj.htm @@ -1,107 +1,105 @@ -<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>We have a report that says starting with Solaris 2.6 we should -leave <I>dosynctodr</I> alone. -<A HREF="solaris-dosynctodr.html">Here is the report</A>. - -<P>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> +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"> +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<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 in some +machines, 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>Note that this program does NOT work in some kernels, in +particular Solaris 2.6 or later. See the <a href= +"solaris-dosynctodr.html">report</a>.</p> + +<p>By default, with no arguments, <tt>tickadj</tt> reads the +variables of interest in the kernel and displays them. At the same +time, it determines an "optimal" value for the value of the <tt> +tickadj</tt> variable if the intent is to run the <tt>ntpd</tt> +Network Time Protocol (NTP) daemon, and prints this as well. Since +the operation of <tt>tickadj</tt> when reading the kernel mimics +the operation of similar parts of the <tt>ntpd</tt> program fairly +closely, this can be useful when debugging problems with <tt> +ntpd</tt>.</p> + +<p>Note that <tt>tickadj</tt> should be run with some caution when +being used for the first time on different types of machines. The +operations which <tt>tickadj</tt> tries to perform are not +guaranteed to work on all Unix machines and may in rare cases cause +the kernel to crash.</p> + +<h4>Command Line Options</h4> + +<dl> +<dt><tt>-a <i>tickadj</i></tt></dt> + +<dd>Set the kernel variable <tt>tickadj</tt> to the value <i><tt> +tickadj</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> +/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> +<a href="index.htm"><img align="left" src="pic/home.gif" alt= +"gif"></a> +<address><a href="mailto:mills@udel.edu">David L. Mills +<mills@udel.edu></a></address> +</body> +</html> + |
