+* Documentation updates from Dave Mills.
(4.2.7p48) 2010/09/12 Released by Harlan Stenn <stenn@ntp.org>
* Documentation updates from Dave Mills.
(4.2.7p47) 2010/09/11 Released by Harlan Stenn <stenn@ntp.org>
<img src="pic/alice51.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>Make sure who your friends are.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->09-Sep-2010 20:30<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 3:04<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<h4 id="modes">Association Modes</h4>
<p>This page describes the various modes of operation provided in NTPv4. There are three types of associations in NTP: <em>persistent</em>, <em>preemptable</em> and <em>ephemeral</em>. Persistent associations are mobilized by a configuration command and never demobilized. Preemptable associations, which are new to NTPv4, are mobilized by a configuration command which includes the <tt>preempt</tt> option and are demobilized by a "better" server or by timeout, but only if the number of survivors exceeds the threshold set by the <tt>tos maxclock</tt> command. Ephemeral associations are mobilized upon arrival of designated NTP packets and demobilized by timeout.</p>
<p>Ordinarily, successful mobilization of ephemeral associations requires the server to be cryptographically authenticated to the client. This can be done using either symmetric key or Autokey public key cryptography, as described in the <a href="authopt.html">Authentication Options</a> page.</p>
-<p>There are three principal modes of operation in NTP: client/server, symmetric active/passive and broadcast/multicast. There are three automatic server discovery schemes in NTP: broadcast/multicast, manycast and pool described on the <a href="manyopt.html">Automatic Server Discovery Schemes</a> page. In addition, the orphan mode and burst options described on this page can be used in appropriate cases.</p>
+<p>There are three principal modes of operation in NTP: client/server, symmetric active/passive and broadcast/multicast. There are three automatic server discovery schemes in NTP: broadcast/multicast, manycast and pool described on the <a href="discover.html">Automatic Server Discovery Schemes</a> page. In addition, the orphan mode and burst options described on this page can be used in appropriate cases.</p>
<p>Following is a summary of the operations in each mode. Note that reference to option applies to the commands described on the <a href="confopt.html">Configuration Options</a> page. See that page for applicability and defaults.</p>
<h4 id="client">Client/Server Mode</h4>
<p>Client/server mode is the most common configuration in the Internet today. It operates in the classic remote-procedure-call (RPC) paradigm with stateless servers and stateful clients. In this mode a host sends a client (mode 3) request to the specified server and expects a server (mode 4) reply at some future time. In some contexts this would be described as a "pull" operation, in that the host pulls the time and related values from the server.</p>
<p>A peer is configured in symmetric active mode using the <tt>peer</tt> command and specifying the other peer DNS name or IPv4 or IPv6 address. The <tt>burst</tt> and <tt>iburst</tt> options should not be used in symmetric modes, as this can upset the intended symmetry of the protocol and result in spurious duplicate or dropped messages.</p>
<p>As symmetric modes are most often used as root servers for moderate to large subnets where rapid response is required, it is generally best to set the minimum and maximum poll intervals of each root server to the same value using the <tt>minpoll</tt> and <tt>maxpoll</tt> options.</p>
<h4 id="broad">Broadcast/Multicast Modes</h4>
-<p>NTP broadcast and multicast modes are intended for configurations involving one or a few servers and a possibly very large client population. Broadcast mode can be used with Ethernet, FDDI and WiFi spans interconnected by hubs or switches. Ordinarily, broadcast packets do not extend beyond a level-3 router. Where service is intended beyond a level-3 router, multicast mode can be used. Additional information is on the <a href="manyopt.html">Automatic NTP Configuration Options</a> page.</p>
+<p>NTP broadcast and multicast modes are intended for configurations involving one or a few servers and a possibly very large client population. Broadcast mode can be used with Ethernet, FDDI and WiFi spans interconnected by hubs or switches. Ordinarily, broadcast packets do not extend beyond a level-3 router. Where service is intended beyond a level-3 router, multicast mode can be used. Additional information is on the <a href="discover.html">Automatic NTP Configuration Options</a> page.</p>
<p>A server is configured to send broadcast or multicast messages using the <tt>broadcast</tt> command and specifying the subnet address for broadcast or the multicast group address for multicast. A broadcast client is enabled using the <tt>broadcastclient</tt> command, while a multicasst client is enabled using the <tt>multicstclient</tt> command and specifiying the multicast group address. Multiple commands of either type can be used. However, the association is not mobilized until the first broadcast or multicast message is actuayl received.</p>
<h4 id="many">Manycast and Pool Modes</h4>
<p>Manycast and pool modes are automatic discovery and configuration paradigms new to NTPv4. They are intended as a means for a client to troll the nearby network neighborhood to find cooperating willing servers, validate them using cryptographic means and evaluate their time values with respect to other servers that might be lurking in the vicinity. The intended result is that each client mobilizes ephemeral client associations with some number of the "best" of the nearby servers, yet automatically reconfigures to sustain this number of servers should one or another fail. Additional information is on the <a href="discover.html">Automatic Server Discovery Schemes</a> page.</p>
-<h4 id="poll2">Poll Interval Control</h4>
+<h4 id="poll">Poll Interval Control</h4>
<p>NTP uses an intricate heuristic algorithm to automatically control the poll interval for maximum accuracy consistent with minimum network overhead. The algorithm measures the incidental offset and jitter to determine the best poll interval. When <tt>ntpd</tt> starts, the interval is the default minimum 64 s. Under normal conditions when the clock discipline has stabilized, the interval increases in steps to the default maximum 1024 s. In addition, should a server become unreachable after some time, the interval increases in steps to the maximum in order to reduce network overhead.</p>
<p>The default poll interval range is suitable for most conditions, but can be changed using options on the <a href="confopt.html">Server Options</a> and <a href="miscopt.html">Miscellaneous Options</a> pages. However, when using maximum intervals much larger than the default, the residual clock frequency error must be small enough for the discipline loop to capture and correct. The capture range is 500 PPM with a 64-s interval decreasing by a factor of two for each interval doubling. At a 36-hr interval, for example, the capture range is only 0.24 PPM.</p>
<p>In the NTPv4 specificationn and reference implementation, the poll interval is expressed in log<sub>2</sub> units, properly called the poll exponent. It is constrained by the lower limit <tt>minpoll</tt> and upper limit <tt>maxpoll</tt> options of the <tt>server</tt> command. The limits default to 6 (64 s) and 10 (1024 s), respectively, which are appropriate for the vast majority of cases. The default limits can be changed with these options to a minimum set by the <tt>average</tt> option of the <tt>discard</tt> command (see below) to a maximum of 17 (36 h).</p>
<li>With symmetric modes the most stable behavior results when both peers are configured in symmetric active mode with matching poll intervals of 6 (64 s).</li>
<li>The poll interval should not be modified for reference clocks, with the single exception the ACTS telephone modem driver. In this case the recommended minimum and maximum intervals are 12 (1.1 h) and 17 (36 h), respectively.</li>
</ul>
-<h4 id="burst2">Burst Options</h4>
+<h4 id="burst">Burst Options</h4>
<p>Occasionally it is necessary to send packets at intervals less than the poll interval. For instance, with the <tt>burst</tt> and <tt>iburst</tt> options of the <tt>server</tt> command, the poll algorithm sends a burst of several packets at 2-s intervals. The <tt>ntpd</tt> poll algorithm avoids sending needless packets if the server is not responding. The client begins a burst with a single packet. When the first packet is received from the server, the client continues with the remaining packets in the burst. If the first packet is not received within 64 s, it will be sent again for two additional retries before beginning backoff. The result is to minimize network load if the server is not responding.</p>
<p>For the <tt>iburst</tt> option the number of packets in the burst is six, which is the number normally needed to synchronize the clock; for the <tt>burst</tt> option, the number of packets in the burst is determined by the difference between the poll interval and the minimum poll interval set by the <tt>minpoll</tt> option of the <a href="confopt.html#server"><tt>server</tt></a> command. For instance, with a poll exponent of 6 (64 s), only a single packet is sent for every poll, while the full number of eight packets is sent at poll intervals of 9 (512 s) or more.</p>
<p>There are two burst options where a single poll event triggers a burst of eight packets at 2-s intervals instead of the normal one packet. They should be used only with the <tt>server</tt> and <tt>pool</tt> commands, but not with reference clock drivers nor symmetric peers. The <tt>burst</tt> option sends a burst when the server is reachable, while the <tt>iburst</tt> option sends a burst when the server is unreachable. Each mode is independently of the other and both can be used at the same time. In either mode the client sends one packet, waits for the reply, then sends the remaining packets in the burst. This may be useful to allow a modem to complete a call.</p>
<img src="pic/alice44.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>Our resident cryptographer; now you see him, now you don't.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->11-Sep-2010 15:56<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 3:08<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<p>Unless noted otherwise, further information about these commands is on the <a href="authentic.html">Authentication Support</a> page.</p>
<dl>
<dt id=automax><tt>automax [<i>logsec</i>]</tt></dt>
- <dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent. See the <a href="autokeyk.html">Autokey Public Key Authentication</a> page for further information.</dd>
+ <dd>Specifies the interval between regenerations of the session key list used with the Autokey protocol, as a power of 2 in seconds. Note that the size of the key list for each association depends on this interval and the current poll interval. The default interval is 12 (about 1.1 h). For poll intervals above the specified interval, a session key list with a single entry will be regenerated for every message sent. See the <a href="autokey.html">Autokey Public Key Authentication</a> page for further information.</dd>
<dt id="controlkey"><tt>controlkey <i>keyid</i></tt></dt>
<dd>Specifies the key ID to use with the <a
href="ntpq.html"><tt>ntpq</tt></a> utility, which uses the
are left unspecified, the default names are used as described below. Unless
the complete path and name of the file are specified, the location of a file
is relative to the keys directory specified in the <tt>keysdir</tt> configuration
- command or default <tt>/usr/local/etc</tt>. See the <a href="autokeyk.html">Autokey Public Key Authentication</a> page for further information. Following are the options.</dd>
+ command or default <tt>/usr/local/etc</tt>. See the <a href="autokey.html">Autokey Public Key Authentication</a> page for further information. Following are the options.</dd>
<dd>
<dl>
<dt><tt>digest</tt> <tt>MD2</tt> | <tt>MD4</tt> | <tt>MD5</tt> | <tt>MDC2</tt> | <tt>RIPEMD160</tt> | <tt>SHA</tt> | <tt>SHA1</tt></dt>
<body>
<h3>Autokey Public-Key Authentication</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->11-Sep-2010 19:19<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 3:22<!-- #EndDate -->
UTC</p>
<hr>
<h4>Table of Contents</h4>
<ul>
- <li class="inline"><a href="#auth">Introduction</a></li>
+ <li class="inline"><a href="#intro">Introduction</a></li>
<li class="inline"><a href="#group">NTP Secure Groups</a></li>
<li class="inline"><a href="#ident">Identity Schemes and Cryptotypes</a></li>
<li class="inline"><a href="#cfg">Configuration</a></li>
<li class="inline"><a href="#exam">Examples</a></li>
</ul>
<hr>
-<h4 id="pub">Introduction</h4>
+<h4 id="intro">Introduction</h4>
<p>This distribution includes support for the Autokey public key algorithms and protocol specified in RFC-5906 "Network Time Protocol Version 4: Autokey Specification". This support is available only if the OpenSSL library has been installed and the <tt>--enable-autokey</tt> option is used when the distribution is built. Public key cryptography is generally more secure than symmetric key cryptography, since the security is based on private and public values which are generated by each participant and where the private value is never revealed. Autokey uses X.509 public certificates, which can be produced by commercial services, utility programs in the OpenSSL software library or the <a href="keygen.html"><tt>ntp-keygen</tt></a> utility program in the NTP software distribution.</p>
<p> The Autokey Version 2 protocol described on the <a href="http://www.eecis.udel.edu/%7emills/proto.html">Autokey Protocol</a> page verifies packet integrity using MD5 message digests and verifies the source using digital signatures and any of several digest/signature schemes. Optional identity schemes described on the <a href="http://www.eecis.udel.edu/~mills/ident.html">Autokey Identity Schemes</a> page are based on cryptographic challenge/response exchanges. These schemes provide strong security against replay with or without message modification, spoofing, masquerade and most forms of clogging attacks. These schemes are described along with an executive summary, current status, briefing slides and reading list on the <a href="http://www.eecis.udel.edu/~mills/autokey.html">Autonomous Authentication</a> page.</p>
<p>Autokey authenticates individual packets using cookies bound to the IP source and destination addresses. The cookies must have the same addresses at both the server and client. For this reason operation with network address translation schemes is not possible. This reflects the intended robust security model where government and corporate NTP servers are operated outside firewall perimeters.</p>
Walt Kelly</a>
<p>The chicken is getting configuration advice.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->10-Sep-2010 0:29<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 4:07<!-- #EndDate -->
</p>
<br clear="left">
<h4>Related Links</h4>
<dd>For type s addresses (only) this command mobilizes a pool client mode association
for the DNS name specified. The DNS name must resolve to one or more IPv4 or
IPv6 addresses. The pool automatic server discovery scheme is described on the
- <a href="manyopt.html#pool">Automatic Server Discovery</a> page.
+ <a href="discover.html#pool">Automatic Server Discovery</a> page.
<a href="http://www.pool.ntp.org/">www.pool.ntp.org</a> describes a compatible pool
of public NTP servers.</dd>
- <dt><tt>unpeer</tt></dt>
+ <dt><tt>unpeer</tt></dt>
<dd>This command removes a previously configured association. An address or association ID can
be used to identify the association. Either an IP address or DNS name can be used. This
command is most useful when supplied via <tt><a href="ntpq.html">ntpq</a></tt> runtime
<p><img src="pic/alice23.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a></p>
<p>Alice holds the key.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->03-Sep-2010 23:20<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 3:36<!-- #EndDate -->
</p>
<br clear="left">
<h4>Related Links</h4>
[ -m <i>modulus</i> ] [ -p <i>passwd2</i> ] [ -q <i>passwd1</i> ] [ -S
[ RSA | DSA ] ] [ -s <i>host</i> ] [ -V <i>nkeys</i> ]</tt></p>
<h4 id="descrip">Description</h4>
-<p>This program generates cryptographic data files used by the NTPv4 authentication
- and identity schemes. It can generate message digest keys used in symmetric
- key cryptography and, if the OpenSSL software library has been installed,
- it can generate host keys, sign keys, certificates and identity keys used
- by the Autokey public key cryptography. The message digest keys file is generated
- in a format compatible with NTPv3. All other files are in PEM-encoded printable
- ASCII format so they can be embedded as MIME attachments in mail to other
- sites.</p>
+<p>This program generates cryptographic data files used by the NTPv4 authentication and identity schemes. It can generate message digest keys used in symmetric key cryptography and, if the OpenSSL software library has been installed, it can generate host keys, sign keys, certificates and identity keys used by the Autokey public key cryptography. The message digest keys file is generated in a format compatible with NTPv3. All other files are in PEM-encoded printable ASCII format so they can be embedded as MIME attachments in mail to other sites.</p>
<p>When used to generate message digest keys, the program produces a file containing
- ten pseudo-random printable ASCII strings suitable for the MD5 message digest
- algorithm included in the distribution. If the OpenSSL library is installed,
- it produces an additional ten hex-encoded random bit strings suitable for
- the SHA1 and other message digest algorithms. Printable ASCII keys can have
- length from one to 20 characters, inclusive. Bit string keys have length
- 20 octets (40 hex characters). All keys are 160 bits in length.</p>
+ ten pseudo-random printable ASCII strings suitable for the MD5 message digest algorithm included in the distribution. If the OpenSSL library is installed, it produces an additional ten hex-encoded random bit strings suitable for the SHA1 and other message digest algorithms. Printable ASCII keys can have length from one to 20 characters, inclusive. Bit string keys have length 20 octets (40 hex characters). All keys are 160 bits in length.</p>
<p> The file can be edited later with
purpose-chosen passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> programs.
- Each line of the file contains three fields, first an integer between 1 and
- 65534, inclusive, representing the key identifier used in the <tt>server</tt> and <tt>peer</tt> configuration
- commands. Next is the key type for the message digest algorithm,
- which in the absence of the OpenSSL library should be the string <tt>MD5</tt> to
- designate the MD5 message digest algorithm.
- If the OpenSSL library is installed, the key type can be any message digest
- algorithm supported by that library. However, if compatibility with FIPS
- 140-2 is required, the key type must be either <tt>SHA</tt> or <tt>SHA1</tt>.Finally
- is the key itself as a printable ASCII string excluding the space and # characters.
- If not greater than 20 characters in length, the string is the key itself;
- otherwise, it is interpreted as a hex-encoded bit string. As is
- custom, # and the remaining characters on the line are ignored. Later, this
- file can be edited to include the passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> utilities.
- If this is the only need, run <tt>ntp-keygen</tt> with the <tt>-M</tt> option
- and disregard the remainder of this page. </p>
+ Each line of the file contains three fields, first an integer between 1 and 65534, inclusive, representing the key identifier used in the <tt>server</tt> and <tt>peer</tt> configuration commands. Next is the key type for the message digest algorithm, which in the absence of the OpenSSL library should be the string <tt>MD5</tt> to designate the MD5 message digest algorithm. If the OpenSSL library is installed, the key type can be any message digest algorithm supported by that library. However, if compatibility with FIPS 140-2 is required, the key type must be either <tt>SHA</tt> or <tt>SHA1</tt>.Finally is the key itself as a printable ASCII string excluding the space and # characters. If not greater than 20 characters in length, the string is the key itself; otherwise, it is interpreted as a hex-encoded bit string. As is custom, # and the remaining characters on the line are ignored. Later, this file can be edited to include the passwords for the <tt>ntpq</tt> and <tt>ntpdc</tt> utilities. If this is the only need, run <tt>ntp-keygen</tt> with the <tt>-M</tt> option and disregard the remainder of this page. </p>
<p>The remaining generated files are compatible with other OpenSSL applications and other Public Key Infrastructure (PKI) resources. Certificates generated by this program should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identity keys are probably not compatible with anything other than Autokey.</p>
<p>Most files used by this program are encrypted using a private password. The <tt>-p</tt> option specifies the password for local files and the <tt>-q</tt> option the password for files sent to remote sites. If no local password is specified, the host name returned by the Unix <tt>gethostname()</tt> function, normally the DNS name of the host, is used. If no remote password is specified, the local password is used.</p>
<p>The <tt>pw</tt> option of the <tt>crypto</tt> configuration command specifies the read password for previously encrypted files. This must match the local password used by this program. If not specified, the host name is used. Thus, if files are generated by this program without password, they can be read back by <tt>ntpd</tt> without password, but only on the same host.</p>
-<p>All files and links are usually installed in the directory <tt>/usr/local/etc</tt>,
- which is normally in a shared filesystem in NFS-mounted networks and cannot
- be changed by shared clients. The location of the keys directory can be changed
- by the <tt>keysdir</tt> configuration command in such cases. Normally, encrypted
- files for each host are generated by that host and used only by that host,
- although exceptions exist as noted later on this page.</p>
+<p>All files and links are usually installed in the directory <tt>/usr/local/etc</tt>, which is normally in a shared filesystem in NFS-mounted networks and cannot be changed by shared clients. The location of the keys directory can be changed by the <tt>keysdir</tt> configuration command in such cases. Normally, encrypted files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page.</p>
<p>This program directs commentary and error messages to the standard error stream <tt>stderr</tt> and remote files to the standard output stream <tt>stdout</tt> where they can be piped to other applications or redirected to a file. The names used for generated files and links all begin with the string <tt>ntpkey</tt> and include the file type, generating host and filestamp, as described in the <a href="#fmt">Cryptographic Data Files</a> section below</p>
<h4 id="run">Running the Program</h4>
<p>To test and gain experience with Autokey concepts, log in as root and change to the keys directory, usually <tt>/usr/local/etc</tt>. When run for the first time, or if all files with names beginning <tt>ntpkey</tt> have been removed, use the <tt>ntp-keygen </tt>command without arguments to generate a default RSA host key and matching RSA-MD5 certificate with expiration date one year hence. If run again, the program uses the existing keys and parameters and generates only a new certificate with new expiration date one year hence; however, the certificate is not generated if the <tt>-e</tt> or <tt>-q</tt> options are present.</p>
<p>As described on the <a href="authopt.html">Authentication Options</a> page, an NTP secure group consists of one or more low-stratum THs as the root from which all other group hosts derive synchronization directly or indirectly. For authentication purposes all hosts in a group must have the same group name specified by the <tt>-i</tt> option and matching the <tt>ident</tt> option of the <tt>crypto</tt> configuration command. The group name is used in the subject and issuer fields of trusted, self-signed certificates and when constructing the file names for identity keys. All hosts must have different host names, either the default host name or as specified by the <tt>-s</tt> option and matching the <tt>host</tt> option of the <tt>crypto</tt> configuration command. Most installations need not specify the <tt>-i</tt> option nor the <tt>host</tt> option. Host names are used in the subject and issuer fields of self-signed, nontrusted certificates and when constructing the file names for host and sign keys and certificates. Host and group names are used only for authentication purposes and have nothing to do with DNS names.</p>
<h4 id="ident">Identity Schemes</h4>
<p>As described on the <a href="authopt.html">Authentication Options</a> page, there are five identity schemes, three of which - IFF, GQ and MV - require identity keys specific to each scheme. There are two types of files for each scheme, an encrypted keys file and a nonencrypted parameters file, which usually contains a subset of the keys file. In general, NTP secondary servers operating as certificate signing authorities (CSA) use the keys file and clients use the parameters file. Both files are generated by the TA operating as a certificate authority (CA) on behalf of all servers and clients in the group.</p>
-<p>The parameters files are public; they can be stored in a public place and
- sent in the clear. The keys files are encrypted with the local password. To
- retrieve the keys file, a host can send a mail request to the TA including its
- local password. The TA encrypts the keys file with this password and returns
- it as an attachment. The attachment is then copied intact to the keys directory
- with name given in the first line of the file, but all in lower case and with
- the filestamp deleted. Alternatively, the parameters file can be retrieved from
+<p>The parameters files are public; they can be stored in a public place and sent in the clear. The keys files are encrypted with the local password. To retrieve the keys file, a host can send a mail request to the TA including its local password. The TA encrypts the keys file with this password and returns it as an attachment. The attachment is then copied intact to the keys directory with name given in the first line of the file, but all in lower case and with the filestamp deleted. Alternatively, the parameters file can be retrieved from
a secure web site.</p>
<p>For example, the TA generates default host key, IFF keys and trusted certificate using the command</p>
<p><tt>ntp-keygen -p <i>local_passwd</i> -T -I -i<i>group_name</i></tt></p>
-<p>Each group host generates default host keys and nontrusted certificate use
- the same command line but omitting the <tt>-i</tt> option. Once these media
- have been generated, the TA can then generate the public parameters using the
- command</p>
+<p>Each group host generates default host keys and nontrusted certificate use the same command line but omitting the <tt>-i</tt> option. Once these media have been generated, the TA can then generate the public parameters using the command</p>
<p><tt>ntp-keygen -p local_passwd -e ><i>parameters_file</i></tt></p>
<p>where the <tt>-e</tt> option redirects the unencrypted parameters to the standard output stream for a mail application or stored locally for later distribution. In a similar fashion the <tt>-q</tt> option redirects the encrypted server keys to the standard output stream.</p>
<h4 id="cmd">Command Line Options</h4>
<dl>
<dt><tt>-c [ RSA-MD2 | RSA-MD5 | RSA-SHA | RSA-SHA1 | RSA-MDC2 | RSA-RIPEMD160 | DSA-SHA | DSA-SHA1 ]</tt></dt>
- <dd>Select certificate and message digest/signature encryption scheme. Note that
- RSA schemes must be used with a RSA sign key and DSA schemes must be used
- with a DSA sign key. The default without this option is <tt>RSA-MD5</tt>. If
- compatibility with FIPS 140-2 is required, either the <tt>DSA-SHA</tt> or <tt>DSA-SHA1</tt> scheme
- must be used.</dd>
+ <dd>Select certificate and message digest/signature encryption scheme. Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is <tt>RSA-MD5</tt>. If compatibility with FIPS 140-2 is required, either the <tt>DSA-SHA</tt> or <tt>DSA-SHA1</tt> scheme must be used.</dd>
<dt><tt>-d</tt></dt>
<dd>Enable debugging. This option displays the cryptographic data produced for eye-friendly billboards.</dd>
<dt><tt>-e</tt></dt>
<dd>Extract the IFF or GQ public parameters from the <tt>IFFkey</tt> or <tt>GQkey</tt> keys file previously specified. Send the unencrypted data to the standard output stream <tt>stdout</tt>. While the IFF parameters do not reveal the private group key, the GQ parameters should be used with caution, as they include the group key. Use the <tt>-q</tt> option with password instead. Note: a new certificate is not generated when this option is present. This allows multiple commands with this option but without disturbing existing media.</dd>
<dt><tt>-G</tt></dt>
- <dd>Generate a new encrypted GQ key file and link for the Guillou-Quisquater
- (GQ) identity scheme.</dd>
+ <dd>Generate a new encrypted GQ key file and link for the Guillou-Quisquater (GQ) identity scheme.</dd>
<dt><tt>-H</tt></dt>
- <dd>Generate a new encrypted RSA public/private host key file and link<tt></tt>.
- Note that if the sign key is the same as the host key, generating a new host
- key invalidates all certificates signed with the old host key.</dd>
+ <dd>Generate a new encrypted RSA public/private host key file and link. Note that if the sign key is the same as the host key, generating a new host key invalidates all certificates signed with the old host key.</dd>
<dt><tt>-i <i>group</i></tt></dt>
<dd>Set the group name to <tt><i>group</i></tt>. This is used in the identity file names. It must match the group name specified in the <tt>ident</tt> option of the <tt>crypto</tt> configuration command.</dd>
<dt><tt>-I</tt></dt>
<h4 id="rand">Random Seed File</h4>
<p>All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the OpenSSL library routines. If a site supports <tt>ssh</tt>, it is very likely that means to do this are already available. The entropy seed used by the OpenSSL library is contained in a file, usually called <tt>.rnd</tt>, which must be available when starting the <tt>ntp-keygen</tt> program or <tt>ntpd</tt> daemon.</p>
<p>The OpenSSL library looks for the file using the path specified by the <tt>RANDFILE</tt> environment variable in the user home directory, whether root or some other user. If the <tt>RANDFILE</tt> environment variable is not present, the library looks for the <tt>.rnd</tt> file in the user home directory. Since both the <tt>ntp-keygen</tt> program and <tt>ntpd</tt> daemon must run as root, the logical place to put this file is in <tt>/.rnd</tt> or <tt>/root/.rnd</tt>. If the file is not available or cannot be written, the program exits with a message to the system log.</p>
-<h4 id="priv">Cryptographic Data Files</h4>
+<h4 id="fmt">Cryptographic Data Files</h4>
<p>File and link names are in the form <tt>ntpkey_<i>key</i>_<i>name</i>.<i>fstamp</i></tt>, where <tt><i>key</i></tt> is the key or parameter type, <tt><i>name</i></tt> is the host or group name and <tt><i>fstamp</i></tt> is the filestamp (NTP seconds) when the file was created). By convention, key fields in generated file names include both upper and lower case alphanumeric characters, while key fields in generated link names include only lower case characters. The filestamp is not used in generated link names.</p>
<p>The key type is a string defining the cryptographic function. Key types include public/private keys <tt>host</tt> and <tt>sign</tt>, certificate <tt>cert</tt> and several challenge/response key types. By convention, files used for challenges have a <tt>par</tt> subtype, as in the IFF challenge <tt>IFFpar</tt>, while files for responses have a <tt>key</tt> subtype, as in the GQ response <tt>GQkey</tt>.</p>
<p>All files begin with two nonencrypted lines. The first line contains the file name in the format <tt>ntpkey_<i>key</i>_<i>host</i>.<i>fstamp</i></tt>. The second line contains the datestamp in conventional Unix <tt>date</tt> format. Lines beginning with <tt>#</tt> are ignored.</p>
<img src="pic/boom3.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
<p>We have three, now looking for more.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->06-Sep-2010 18:31<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->13-Sep-2010 3:59<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<dt><tt>freq <i>freq</i></tt></dt>
<dd>Specifies the frequency offset in parts-per-million (PPM) with default the value in the frequency file.</dd>
<dt><tt>huffpuff <i>huffpuff</i></tt></dt>
- <dd>Sp edifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 m), but a more reasonable value is 7200 (2 hours).</dd>
+ <dd>Sp edifies the huff-n'-puff filter span, which determines the most recent interval the algorithm will search for a minimum delay. The lower limit is 900 s (15 min), but a more reasonable value is 7200 (2 hours).See the <a href=="huffpuff.html">Huff-n'-Puff Filter</a> page for further information.</dd>
<dt><tt>panic <i>panic</i></tt></dt>
<dd>Sp edifies the panic threshold in seconds with default 1000 s. If set to zero, the panic sanity check is disabled and a clock offset of any value will be accepted.</dd>
<dt><tt>step <i>step</i></tt></dt>
- <dd>Sp edifies the step threshold in seconds. The default without this command
- is 0.128 s. If set to zero, step adjustments will never
- occur. Note: The kernel time discipline is disabled if
- the step threshold is set to zero or greater than 0.5
+ <dd>Sp edifies the step threshold in seconds. The default without this command is 0.128 s. If set to zero, step adjustments will never occur. Note: The kernel time discipline is disabled if the step threshold is set to zero or greater than 0.5
s.</dd>
<dt><tt>stepout <i>stepout</i></tt></dt>
- <dd>Specifies the stepout threshold in seconds. The default without this
- command is 900 s. If set to zero, popcorn spikes will
- not be suppressed.</dd>
+ <dd>Specifies the stepout threshold in seconds. The default without this command is 900 s. If set to zero, popcorn spikes will not be suppressed.</dd>
</dl>
</dd>
<dt id="tos"><tt>tos [ beacon <i>beacon</i> | ceiling <i>ceiling</i> | cohort {0 | 1} | floor <i>floor</i> | maxclock <i>maxclock </i>| maxdist <i>maxdist</i> | minclock <i>minclock</i> | mindist <i>mindist </i>| minsane <i>minsane</i> | orphan <i>stratum</i> | orphanwait <em>delay</em> ]</tt></dt>
<dd>
<dl>
<dt><tt>beacon <i>beacon</i></tt></dt>
- <dd>The manycast server sends packets at intervals of 64 s if less than <tt>maxclock</tt> servers are available. Otherwise, it sends packets at the <i><tt>beacon</tt></i> interval in seconds. The default is 3600 s. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dd>The manycast server sends packets at intervals of 64 s if less than <tt>maxclock</tt> servers are available. Otherwise, it sends packets at the <i><tt>beacon</tt></i> interval in seconds. The default is 3600 s. See the <a href="discover.html">Automatic Server Discovery</a> page for further details.</dd>
<dt><tt>ceiling <i>ceiling</i></tt></dt>
- <dd>Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dd>Specify the maximum stratum (exclusive) for acceptable server packets. The default is 16. See the <a href="discover.html">Automatic Server Discovery</a> page for further details.</dd>
<dt><tt>cohort { 0 | 1 }</tt></dt>
- <dd>Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dd>Specify whether (1) or whether not (0) a server packet will be accepted for the same stratum as the client. The default is 0. See the <a href="discover.html">Automatic Server Discovery</a> page for further details.</dd>
<dt><tt>floor <i>floor</i></tt></dt>
- <dd>Specify the minimum stratum (inclusive) for acceptable server packets. The default is 1. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dd>Specify the minimum stratum (inclusive) for acceptable server packets. The default is 1. See the <a href="discover.html">Automatic Server Discovery</a> page for further details.</dd>
<dt><tt>maxclock <i>maxclock</i></tt></dt>
- <dd>Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the <a href="manyopt.html">Automatic Server Discovery</a> page for further details.</dd>
+ <dd>Specify the maximum number of servers retained by the server discovery schemes. The default is 10. See the <a href="discover.html">Automatic Server Discovery</a> page for further details.</dd>
<dt><tt>maxdist <i>maxdistance</i></tt></dt>
<dd>Specify the synchronization distance threshold used by the clock selection algorithm. The default is 1.5 s. This determines both the minimum number of packets to set the system clock and the maximum roundtrip delay. It can be decreased to improve reliability or increased to synchronize clocks on the Moon or planets.</dd>
<dt><tt>minclock <i>minclock</i></tt></dt>
<img src="pic/pogo7.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/~mills/pictures.html">from <i>Pogo</i>, Walt Kelly</a>
<p>Racoon is shooting configuration bugs.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->04-Sep-2010 1:13<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 3:45<!-- #EndDate -->
UTC</p>
<br clear="left">
<hr>
<li>Functions that have a <tt>create_</tt> prefix. These functions are used to build a node of the AST.</li>
<li>Functions that have a <tt>config_</tt> prefix. These functions are used to traverse the AST and configure NTP according to the nodes present on the tree.</li>
</ol>
-<h4>Guidelines for Adding Configuration Commands</h4>
+<h4 id="guidelines">Guidelines for Adding Configuration Commands</h4>
<p>The following steps may be used to add a new configuration command to the NTP reference implementation:</p>
<ol>
<li>Write phrase-structure grammar rules for the syntax of the new command. Add these rules to the rules section of the <b>ntp_config.y</b> file. </li>
<ul>
<li class="inline"><a href="#synop">Synopsis</a></li>
<li class="inline"><a href="#descr">Description</a></li>
- <li class="inline"><a href="#info">Additional Information</a></li>
<li class="inline"><a href="#cmd">Command Line Options</a></li>
<li class="inline"><a href="#cfg">The Configuration File</a></li>
<li class="inline"><a href="#files">Files</a></li>
<img src="pic/alice32.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>Alice is trying to find the PPS signal connector.</p>
<p>Last update:
- <!-- #BeginDate format:En2m -->09-Sep-2010 18:15<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 4:09<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<p><img src="pic/gadget.jpg" alt="gif"></p>
<p>A Gadget Box built by Chuck Hanavin</p>
</div>
+<h4 id="gadget">Gadget Box</h4>
<p>The gadget box shown above is assembled in a 5"x3"x2" aluminum minibox containing the the circuitry, serial connector and optional 12-V power connector. A complete set of schematics, PCB artwork, drill templates can be obtained via the web from ftp.udel.edu as <a href="ftp://ftp.udel.edu/pub/ntp/hardware/gadget.tar.Z">gadget.tar.Z</a>.</p>
<p> The gadget box includes two subcircuits. One of these converts a TTL positive edge into a fixed-width pulse at EIA levels and is for use with a timecode receiver or precision oscillator with a TTL PPS output. The other converts the timecode modulation broadcast by Canadian time/frequency standard station CHU into a 300-bps serial character stream at EIA levels and is for use with the <a href="drivers/driver7.html">Radio CHU Audio Demodulator/Decoder</a> driver.</p>
<h4 id="opsys">Operating System Support</h4>
<p>Both the serial and parallel port connection require operating system support, which is available in a few operating systems, including FreeBSD, Linux (with PPSkit patch) and Solaris. Support on an experimental basis is available for several other systems, including SunOS and HP/Compaq/Digital Tru64. The kernel interface described on the <a href="kernpps.html">PPSAPI Interface for Precision Time Signals</a> page is the only interface currently supported. Older PPS interfaces based on the <tt>ppsclock</tt> and <tt>tty_clk</tt> streams modules are no longer supported. The interface consists of the <tt>ppstime.h</tt> header file which is specific to each system. It is included automatically when the distribution is built.</p>
<h4>PPS Driver</h4>
<p>PPS support requires is built into some drivers, in particular the WWVB and NMEA drivers, and may be added to other drivers in future. Alternatively, the PPS driver described on the <a href="drivers/driver22.html">Type 22 PPS Clock Discipline</a> page can be used. It operates in conjunction with another source that provides seconds numbering. The selected source is designate a prefer peer, as using the <tt>prefer</tt> option, as described on the <a href="prefer.html">Mitigation Rules and the <tt>prefer</tt> Keyword</a> page. The prefer peer is ordinarily the radio clock that provides the PPS signal, but in principle another radio clock or even a remote Internet server could be designated preferred Note that the <tt>pps</tt> configuration command has been obsoleted by this driver.</p>
-<h4 id="pps">Using the Pulse-per-Second (PPS) Signal</h4>
+<h4 id="use">Using the Pulse-per-Second (PPS) Signal</h4>
<p>The PPS signal can be used in either of two ways, one using the NTP grooming and mitigation algorithms and the other using the kernel PPS signal support described in the <a href="kern.html">Kernel Model for Precision Timekeeping</a> page. The presence of kernel support is automatically detected during the NTP build process and supporting code automatically compiled. In either case, the PPS signal must be present and within nominal jitter and wander tolerances. In addition, the prefer peer must be a truechimer; that is, survive the sanity checks and intersection algorithm. Finally, the offset of the system clock relative to the prefer peer must be within ±0.5 s. The kernel maintains a watchdog timer for the PPS signal; if the signal has not been heard or is out of tolerance for more than some interval, currently two minutes, the kernel discipline is disabled and operation continues as if it were not present. </p>
<p> An option flag in the driver determines whether the NTP algorithms or kernel support is enabled (if available). For historical reasons, the NTP algorithms are selected by by default, since performance is generally better using older, slower systems. However, performance is generally better with kernl support using newer, faster systems.</p>
<hr>
</head>
<body>
<p>Last update:
- <!-- #BeginDate format:En2m -->04-Sep-2010 17:16<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 3:54<!-- #EndDate -->
UTC</p>
<h3>Quick Start</h3>
<img src="pic/panda.gif" alt="gif" align="left">FAX test image for SATNET (1979).
<p>The baby panda was scanned at University College London and used as a FAX test image for a demonstration of the DARPA Atlantic SATNET Program and the first transatlantic Internet connection in 1978. The computing system used for that demonstration was called the <a href="http://www.eecis.udel.edu/%7emills/database/papers/fuzz.ps">Fuzzball</a>. As it happened, this was also the first Internet multimedia presentation and the first to use a predecessor of NTP in regular operation. The image was widely copied and used for testing purpose throughout much of the 1980s.</p>
<p>Last update:
- <!-- #BeginDate format:En1m -->4-sep-10 17:16<!-- #EndDate -->
+ <!-- #BeginDate format:En1m -->12-sep-10 3:54<!-- #EndDate -->
UTC</p>
<h4>Related Links</h4>
<script type="text/javascript" language="javascript" src="scripts/install.txt"></script>
<p><tt>server foo.bar.com</tt></p>
<p>Choosing an appropriate remote server is somewhat of a black art, but a
suboptimal choice is seldom a problem. The simplest is to use the
- Server Pool Scheme on the <a href="manyopt.html">Automatic Server Discovery</a> page. There
+ Server Pool Scheme on the <a href="discover.html">Automatic Server Discovery</a> page. There
are about two dozen public time servers operated by the <a href="http://tf.nist.gov/tf-cgi/servers.cgi">National
Institutes of Science and Technology (NIST)</a>, <a href="http://tycho.usno.navy.mil/ntp.html">US
Naval Observatory (USNO)</a>, <a href="http://inms-ienm.nrc-cnrc.gc.ca/time_services/network_time_protocol_e.html"> Canadian
<h4>Table of Contents</h4>
<ul>
<li class="inline"><a href="#intro">Introduction</a></li>
- <li class="inline"><a href="#poll">Poll Rate Control</a></li>
- <li class="inline"><a href="#burst">Burst Control</a></li>
<li class="inline"><a href="#guard">Guard Time</a></li>
<li class="inline"><a href="#mah">Average Headway Time</a></li>
<li class="inline"><a href="#kiss">The Kiss-o'-Death Packet</a></li>
<img src="pic/hornraba.gif" alt="gif" align="left"><a href="http://www.eecis.udel.edu/%7emills/pictures.html">from <i>Alice's Adventures in Wonderland</i>, Lewis Carroll</a>
<p>The rabbit toots to make sure you read this.</p>
<p>Last update:
- <!-- #BeginDate format:En1m -->9-sep-10 18:25<!-- #EndDate -->
+ <!-- #BeginDate format:En1m -->12-sep-10 4:14<!-- #EndDate -->
UTC</p>
<br clear="left">
<h4>Related Links</h4>
<li>A new feature called orphan mode provides an automatic, subnet-wide synchronization feature with multiple sources. It provides relable backup in isolated networks or in pr when Internet sources have become unavaillable. See the <a href="orphan.html">Orphan Mode</a> page for further information.</li>
<li>This release includes comprehensive packet rate management tools to help reduce the level of spurious network traffic and protect the busiest servers from overload. There is support for the optional Kiss-o'- Death (KoD) packet intended to slow down an abusive client. See the <a href="rate.html">Rate Management and the Kiss-o'-Death Packet</a> page for further information.</li>
<li>There are two new burst mode features available where special conditions apply. One of these is enabled by the <tt>iburst</tt> keyword in the <tt>server</tt> configuration command. It is intended for cases where it is important to set the clock quickly when an association is first mobilized. The other is enabled by the <tt>burst</tt> keyword in the <tt>server</tt> configuration command. It is intended for cases where the network attachment requires an initial calling or training procedure. See the <a href="assoc.html">Association Management</a> page for further information.</li>
- <li>The OpenSSL cryptographic library has replaced the library formerly available from RSA Laboratories. All cryptographic routines except a version of the MD5 message digest routine have been removed from the base distribution. All 128- and 160- bit message digests routines are now supported for both symmetric key and public key cryptosystems. See the <a href="authentic">Authetication Support</a> pagefor further information and the <a href="authopt.html">Authentication Options</a> page for a list of supported digest algorithms.</li>
+ <li>The OpenSSL cryptographic library has replaced the library formerly available from RSA Laboratories. All cryptographic routines except a version of the MD5 message digest routine have been removed from the base distribution. All 128- and 160- bit message digests routines are now supported for both symmetric key and public key cryptosystems. See the <a href="authentic
.html">Authetication Support</a> pagefor further information and the <a href="authopt.html">Authentication Options</a> page for a list of supported digest algorithms.</li>
<li>This release includes support for Autokey public-key cryptography for authenticating public servers to clients, as described in RFC 5906. This support requires the --enabld-autokey option when building the distribution. Additional information about Autokey is on the <a href="autokey.html">Autokey Publid Key Authentication</a> page and links from there.</li>
<li>The NTP descrete even simulator has been substantially upgraded, now including scenarios with multiple servers and time-sensitive scripts. This allows the NTP algorithms to be tested in an embedded environment with systematic and pseudo-random network delay and oscillator wander distributions. This has been used to verify correct operation under conditions of extreme error and misconfiguration. See the <a href="ntpdsim.html"><tt>ntpdsim</tt> - Network Time Protocol (NTP) simulator</a> page. A technical description and performance analysis is given in the white papers at the <a href="http://www.eecis.udel.edu/~mills/ntp.html">NTP Project Page</a>.</li>
- <li>NTPv4 includes three new server discovery schemes, which in most applications can avoid per-host configuration altogether. Two of these are based on IP multicast technology, while the remaining one is based on crafted DNS lookups. See the <a href="manyopt.html">Automatic NTP Configuration Schemes</a> page for further information.</li>
+ <li>NTPv4 includes three new server discovery schemes, which in most applications can avoid per-host configuration altogether. Two of these are based on IP multicast technology, while the remaining one is based on crafted DNS lookups. See the <a href="discover.html">Automatic NTP Configuration Schemes</a> page for further information.</li>
<li>The status display and event report monitoring functions have been considerably expanded, including new statistics files and event reporting to files and the system log. See the <a href="decode.html">Event Messages and Status Words</a> page for further information.</li>
<li>Several new options have been added for the <tt>ntpd</tt> command line. For the inveterate knob twiddlers several of the more important performance variables can be changed to fit actual or perceived special conditions. In particular, the <tt>tinker</tt> and <tt>tos</tt> commands can be used to adjust thresholds, throw switches and change limits.</li>
<li>The <tt>ntpd</tt> daemon can be operated in a one-time mode similar to <tt>ntpdate</tt>, which program is headed for retirement. See the <a href="ntpd.html"><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</a> page for the new features.</li>
<body>
<h3>How NTP Works</h3>
<p>Last update:
- <!-- #BeginDate format:En2m -->11-Sep-2010 17:51<!-- #EndDate -->
+ <!-- #BeginDate format:En2m -->12-Sep-2010 21:04<!-- #EndDate -->
UTC</p>
<h4>Table of Contents</h4>
<ul>
<li class="inline"><a href="#ntp">NTP Daemon Architecture and Basic Operation</a></li>
<li class="inline"><a href="#stats">How Statistics are Determined</a></li>
<li class="inline"><a href="#clock">Clock Discipline Algorithm</a></li>
+ <li class="inline"><a href="#state">Clock State Machine</a></li>
</ul>
<hr>
<h4 id="intro">Introduction</h4>
<p> The optimum time constant, and thus the poll interval, depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. With a compromise Allan intercept of 2000 s, the optimum poll interval is about 64 s, which corresponds to a poll exponent of 6.</p>
<p> The poll interval is managed by a heuristic algorithm developed over several years of experimentation. It depends on an exponentially weighted average of clock offset differences, called the clock jitter, and a jiggle counter, which is initially set to zero. When a clock update is received and the offset exceeds the clock jitter by a factor of 4, the jiggle counter is increased by the poll exponent; otherwise, it is decreased by twice the poll exponent. If the jiggle counter is greater than an arbitrary threshold of 30, the poll exponent. if jiggle counter exceed an arbitrary threshold of 30, it is reset to zero and the poll exponent increased by 1. If the jiggle counter is less than -30, it is set to zero and the poll exponent decreased by 1. In effect, the algorithm has a relatively slow reaction to good news, but a relatively fast reaction to bad news.</p>
<p>The optimum time constant, and thus the poll exponent, depends on the network time jitter and the clock oscillator frequency wander. Errors due to jitter decrease as the time constant increases, while errors due to wander decrease as the time constant decreases. The two error characteristics intersect at a point called the Allan intercept, which represents the ideal time constant. With a compromise Allan intercept of 2000 s, the optimum poll interval is about 64 s, which corresponds to a poll exponent of 6.</p>
-<p>Additional information about the clock discipline behavior is on the <a href="clock.html">Clock State Machine</a> page. </p>
+<h4 id="state">Clock State Machine</h4>
+<p>In the NTPv4 specification and reference implementation a state machine is used to manage the system clock under exceptional conditions, as when the daemon is first started or when encountering severe network congesiton, for example. The state machine uses three thresolds: panic, step and stepout, and a watchdog timer. The thresholds default to 1000 s, 128 ms and 900 s, respectively, but can be changed by command options.</p>
+<p>Most compters today incorporate a time-of-year (TOY) chip to maintain the time when the power is off. When the machine is restarted, the chip is used to initialize the operating system time. In case there is no TOY chip or the TOY time is different from NTP time by more than the panic threshold, the daemon <tt></tt> assumes something must be terribly wrong, so exits with a message to the system operator to set the time manually. With the <tt>-g</tt> option, the daemon will set the clock to NTP time the first time, but exit if the offset exceed the any time after that.</p>
+<p>Under ordinary conditions, the clock discipline slews the clock so that the time is effectively continuous and never runs backwards. If due to extreme network congestion, or an offset spike exceeds the step threshold, by default 128 ms, the spike is discarded. However, if offsets greater than the step threshold persist for more than the <i>stepout threshold</i>, by default 900 s, the system clock is stepped to the correct value. In practice the need for a step has been extremely rare and almost always the result of a hardware failure. Both the step threshold and stepout threshold can be set as options to the tinker command.</p>
+<p>Historically, the most important appliccation of the step function was when a leap second was inserted in the Coordinated Univesal Time (UTC) timescale and kernel precision time support was not available. Further details are on the <a href="leap.html">Leap Second Processing</a> page.</p>
+<p>In some applications the clock can never be set backward, even it accidentlly set forward a week by some other means. There are several ways to alter the daemon behavior to insure time is always monotone-increasing. If the step threhold is set to zero, there will never be a step. With the <tt>-x</tt> command line option the daemon will set will set the step threshold to 600 s, which is about the limit of eyeball and wristwatch. However, in any of these cases, the precision time kernel support is disabled, as it cannot handle offsets greater than ±0.5 s.</p>
+<p>The issues should be carefully considered before using these options. The slew rate is fixed at 500 parts-per-million (PPM) by the Unix kernel. As a result, the clock can take 33 minutes to amortize each second the clock is outside the acceptable range. During this interval the clock will not be consistent with any other network clock and the system cannot be used for distributed applications that require correctly synchronized network time.</p>
+<p>The frequency file, usually called <tt>ntp.drift</tt>, contains the latest estimate of clock frequency. If this file does not exist when the daemon is started, the clock state machine enters a special mode designed to measure the particular frequency directly. The measurement takes an interval equal to the stepout threshold, after which the frequency is set and the daemon esumes normal mode where the time and frequency are continuously adjusted. The frequency file is updated at intervals of an hour or more depending on the measured clock stability.</p>
<hr>
<p>
<script type="text/javascript" language="javascript" src="scripts/footer.txt"></script>
projects / thirdparty / ntp.git / commitdiff
