+2000-07-14 Harlan Stenn <stenn@whimsy.udel.edu>
+
+ * html/ntpq.htm:
+ * html/index.htm:
+ * html/debug.htm:
+ * html/authopt.htm:
+ Reality check.
+ From Dave Mills
+
2000-07-13 Harlan Stenn <stenn@whimsy.udel.edu>
* Makefile.am (SUBDIRS): Added ElectricFence
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
-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>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.
<h4>Public-Key Scheme</h4>
<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. 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.
+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>The <tt>ntp_dh</tt> file contains the agreement parameters. It is
necessary that all servers and clients of a security compartment share a
single set of parameters, but it does not matter which <tt>ntp_dh</tt>
-file generates them. The servers load the parameters directly from the
-file, while the clients load them indirectly from the servers using the
-autokey protocol. This file can be also be distributed using insecure
-means, since the data are public values.
+file generates them. Servers load the parameters directly from the
+file, while the clients can load them indirectly from the servers using
+the autokey protocol. Note that the parameters will be requested by all
+associations, either configured or not; but, none of the associations
+can proceed until one of them has received them. 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>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 <tt>server</tt>
agreement parameters should be loaded from files, rather than using the
autokey protocol.
+<h4>Leapseconds Table</tt>
+
+<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>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. Note that the table will be
+requested by all associations, either configured or not; but, none of
+the associations can proceed until one of them has received the table.
+Once loaded, the table can be provided on request to other clients and
+servers.
+
<h4>Key Management</h4>
<p>All key files are installed by default in <tt>/usr/local/etc</tt>,
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
key identifier for a trusted key, where the value can be in the range 1
to 65534, inclusive.</dd>
-<dt><tt>crypto [privatekey <i>file</i>] [publickey <i>file</i>] [dhparms
-<i>file</i>] </tt></dt>
+<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
<dl>
+<dt><tt>flags <i>flags</tt></i>
+<dd>Specifies optional flag bits. The only flag bit defined at this time
+is <tt>0x2</tt> which causes the leapsecond file to be fetched from any
+available server or peer.</dd>
+
<dt><tt>privatekey <i>file</tt></i>
<dd>Specifies the location of the RSA private key file, which
otherwise defaults to <tt>/usr/local/etc/ntpkey</tt>.</dd>
<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</tt></i>
+<dd>Specifies the location of the leapsecond table file,
+which otherwise defaults to <tt>/usr/local/etc/ntpkey_leap</tt>.</dd>
+
</dl>
<dt><tt>keys <i>keyfile</i></tt></dt>
and bug, Walt Kelly
<br clear=left><hr>
-<P>Once the NTP software distribution has been compiled and installed
+<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.
+<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>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>
+<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
+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
+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.
+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>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
+<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
+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
+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
+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 UDP port for NTP
+(123) in the Unix <tt>/etc/services</tt> file. Note that NTP does not
+use TCP in any form. Other problems are apparent in the system log file.
+The log file should show the startup banner, some cryptic initialization
+data and the computed precision value. The next most common problem is
incorrect DNS names. Check that each DNS name used in the configuration
-file responds to the Unix <TT>ping</TT> command.
-
-<P>When first started, the daemon normally polls the servers listed in
-the configuration file at 64-second intervals. In order to allow a
-sufficient number of samples for the NTP algorithms to reliably
-discriminate between correctly operating servers and possible intruders,
-at least four valid messages from at least one server is required before
-the daemon can set the local clock. However, if the current local time
-is greater than 1000 seconds in error from the server time, the daemon
-will not set the local clock; instead, it will plant a message in the
-system log and shut down. It is necessary to set the local clock to
-within 1000 seconds first, either by a time-of-year hardware clock, by
-first using the <A HREF="ntpdate.htm"><TT>ntpdate</TT> </A>program or
-manually be eyeball and wristwatch.
-
-<P>After starting the daemon, run the <TT>ntpq</TT> program using the
-<TT>-n</TT> switch, which will avoid possible distractions due to name
-resolution problems. Use the <TT>pe</TT> command to display a billboard
+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-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 the majority of servers and peers listed in the
+configuration file is required before the daemon can set the local
+clock. However, if the current system time is greater than 1000 s in
+error from the server times, 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 s 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>If the initial time error is less than 1000 s but greater than 125
+ms, the daemon will perform a step adjustment; otherwise, it will
+gradually slew the clock to the nominal time. However, if a step
+adjustment, 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>If, as discussed later in this page, for some reason the hardware
+clock oscillator frequency error is relatively large, the time errors
+upon first startup of the daemon may increase over time until exceeding
+125 ms, which requires another step correction. However, due to
+provisions that reduce vulnerability to noise spikes, the second
+correction will not be done until 900 s have elapsed since the last
+adjustment. 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.
+
+<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:
-<PRE>ntpq>pe
-remote refid st t when poll reach delay offset disp
-===================================================================
-+128.4.2.6 132.249.16.1 2 u 131 256 373 9.89 16.28 23.25
-*128.4.1.20 .WWVB. 1 u 137 256 377 280.62 21.74 20.23
--128.8.2.88 128.8.10.1 2 u 49 128 376 294.14 5.94 17.47
-+128.4.2.17 .WWVB. 1 u 173 256 377 279.95 20.56 16.40
-</PRE>
-
-The host addresses shown in the <TT>remote</TT> column should agree with
-the DNS entries in the configuration file, plus any peers not mentioned
-in the file at the same or lower than your stratum that happen to be
-configured to peer with you. Be prepared for surprises in cases where
-the peer has multiple addresses or multiple names. The <TT>refid</TT>
-entry shows the current source of synchronization for each peer, while
-the <TT>st</TT> reveals the stratum, <TT>t</TT> the type (<TT>u</TT> =
-unicast, <TT>m</TT> = multicast, <TT>l</TT> = local, <TT>-</TT> = don't
-know), and <TT>poll</TT> the polling interval in seconds. The
-<TT>when</TT> entry shows the time since the peer was last heard,
-normally in seconds, while the <TT>reach</TT> entry shows the status of
-the reachability register (see RFC-1305) in octal. The remaining entries
-show the latest delay, offset and dispersion computed for the peer in
-milliseconds. Note that in NTP Version 4 the dispersion entry includes
-only the RMS error component; earlier versions included all components.
-
-<P>The tattletale character at the left margin displays the
-synchronization status of each peer. The currently selected peer is
-marked <TT>*</TT>, while additional peers designated acceptable for
-synchronization, but not currently selected, are marked <TT>+</TT>.
-Peers marked <TT>*</TT> and <TT>+</TT> are included in a weighted
-average computation to set the local clock; the data produced by peers
-marked with other symbols are discarded. See the <TT>ntpq</TT>
-documentation for the meaning of these symbols.
-
-<P>Additional details for each peer separately can be determined by the
-following procedure. First, use the <TT>as</TT> command to display an
+<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>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 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>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
+<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>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>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 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
+more of the rounds show large values or change radically from one round
+to another, the network is probably congested or lossy.
+
+<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
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
+<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>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>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>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>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>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>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
<H4>Debugging Checklist</H4>
-If the <TT>ntpq</TT> or <TT>ntpdc</TT> programs do not show that
+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>
+<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>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.
+
+<p><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>
+
+<p><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>
+
+<p><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>
+
+<p><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>
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.
+Synchronization Project</A> page. Additional information can be found at
+the NTP web site <tt>www.ntp.org</tt>. Please send bug reports to <a
+href=mailto:bugs@mail.ntp.org><bugs@mail.ntp.org></a>.
<H4>Building and Installing NTP</H4>
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
<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><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
+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><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>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>For examples and usage, see the <a href=debug.htm>NTP Debugging
+Techniques</a> page.
+
+<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.
<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>
+<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>
+<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>
-
+<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>
+<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.
+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></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>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></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 <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>
+<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>
+<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 decodeable value but didn't are marked with a trailing <tt>?</tt>.</dd>
+<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>
+<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>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>
+<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>
+<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>
+<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>
+<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/intepretation done on the data is to transform nonascii data into a printable (but barely understandable) form.</dd>
+<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>
+<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.
-
+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>
-
-<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>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>
<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>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>
<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>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>
+<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></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>
-
-<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>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></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>
<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>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>
+<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. 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>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>
<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>
+<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>
+<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>
+<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>
+<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>
+<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>
+<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>
+<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>
+<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>
-
-<p><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 original sanity checks defined in the NTP specification RFC-1305 and additional ones added since then. There are eleven tests named <tt>TEST1</tt> through <tt>TEST11</tt>. Tests <tt>TEST1</tt> through <tt>TEST5</tt> represent checks on the basic header data from which the offset and delay are calculated. If any of these tests fail, the packet is discarded without further processing. Tests <tt>TEST6</tt> through <tt>TEST9</tt> represent checks on the remaining header values. Tests <tt>TEST10</tt> and <tt>TEST11</tt> represent checks using public key cryptography. They have meaning only if support for the autokey public key support has been configured in the system. If any of these tests fail, the basic header data are captured, but the packet is then discarded. The bits for each test read in increasing order from the least significant bit are defined as follows.</dd>
-
-<p><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>
+<p><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>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>The <tt>flash</tt> bits for each test read in increasing order from
+the least significant bit are defined as follows.</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>
+<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>
+<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>
+<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>
+<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>
+<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 greater than 15. It is probably unsynchronized and its clock needs to be wound up.</dd>
+<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>
-
+<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>
+<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>
+<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 with public key credentials. See the <A HREF="authopt.htm">Authentication Options</A> page.</dd>
+<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>
</dl>
-<p><dd>Additional system variables not defined in the NTP specification
-RFC-1305 are used by the autokey public key support. They include the following:
+<p><dd>Additional system variables used by the NTP Version 4 Autokey
+support include the following:
<dl>
-<dt><tt>privatekey <i>filename</i></tt>/<dt>
-<dd>Specifies the name of the RSA private key file.</dd>
+<dt><tt>leaptable <i>filestamp</i></tt>/<dt>
+<dd>Shows the NTP seconds when the NIST leapsecond table file was
+created.</dd>
-<dt><tt>publickey <i>filename</i></tt>/<dt>
-<dd>Specifies the name of the RSA public key file.</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>dhparams <i>filename</i></tt>/<dt>
-<dd>Specifies the name of the Diffie-Hellman parameter file.</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>hostname <i>host</i></tt>/<dt>
-<dd>Specifies the name of the host.</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>revoketime <i>host</i></tt>/<dt>
-<dd>Specifies the last time the public and private values used in the agreement algorithm were refreshed.</dd>
+<dt><tt>refresh <i>timestamp</i></tt>/<dt>
+<dd>Shows the NTP seconds when the public cryptographic values were
+refreshed and signed.</dd>
</dl>
-<p><dd>Additional peer variables not defined in the NTP specification
-RFC-1305 are used by the autokey public key support. They include the following:
+<p><dd>Additional peer variables used by the NTP Version 4 Autokey
+support include the following:
<dl>
-<dt><tt>pcookie <i>hex</i></tt>/<dt>
-<dd>Specifies the peer cookie used in the key agreement algorithm.</dd>
-
<dt><tt>hcookie <i>hex</i></tt>/<dt>
-<dd>Specifies the host cookie used in the key agreement algorithm.</dd>
+<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>Specifies the initial index used by the key list generator in the autokey protocol.</dd>
+<dd>Shows the initial index used by the key list generator in the
+autokey protocol.</dd>
-<dt><tt>initkey <i>key</i></tt>/<dt>
-<dd>Specifies the initial key 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>Specifies the NTP time (seconds) when the last autokey message was recieved.</dd>
-
+<dd>Shows the NTP seconds when the last autokey key list was generated
+and signed.</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>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></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>
-
-<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>
-
-<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>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></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>
+
+<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>
+<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
+<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.
+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><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>
projects / thirdparty / ntp.git / commitdiff
