1 files changed, 67 insertions, 0 deletions
diff --git a/contrib/ntp/html/rdebug.htm b/contrib/ntp/html/rdebug.htm
new file mode 100644
index 0000000..472b09f
--- /dev/null
+++ b/contrib/ntp/html/rdebug.htm
@@ -0,0 +1,67 @@
+<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
+<html><head><title>
+Debugging Hints for Reference Clock Drivers
+</title></head><body><h3>
+Debugging Hints for Reference Clock Drivers
+</h3><hr>
+
+<p>The <a href = "ntpq.htm"> <code>ntpq</code></a> and <a href =
+"ntpdc.htm"> <code>ntpdc</code> </a>utility programs can be used to
+debug reference clocks, either on the server itself or from another
+machine elsewhere in the network. The server is compiled, installed and
+started using the command-line switches described in the <a href =
+"ntpd.htm"> <code>ntpd</code> </a> page. The first thing to look for
+are error messages on the system log. If none occur, the daemon has
+started, opened the devices specified and waiting for peers and radios
+to come up.
+
+<p>The next step is to be sure the RS232 messages, if used, are getting
+to and from the clock. The most reliable way to do this is with an RS232
+tester and to look for data flashes as the driver polls the clock and/or
+as data arrive from the clock. Our experience is that the overwhelming
+fraction of problems occurring during installation are due to problems
+such as miswired connectors or improperly configured device links at
+this stage.
+
+<p>If RS232 messages are getting to and from the clock, the variables of
+interest can be inspected using the <code>ntpq</code> program and
+various commands described on the documentation page. First, use the
+<code>pe</code> and <code>as</code> commands to display billboards
+showing the peer configuration and association IDs for all peers,
+including the radio clock peers. The assigned clock address should
+appear in the <code>pe</code> billboard and the association ID for it at
+the same relative line position in the <code>as</code> billboard. If
+things are operating correctly, after a minute or two samples should
+show up in the <code>pe</code> display line for the clock.
+
+<p>Additional information is available with the <code>rv</code> and
+<code>clockvar</code> commands, which take as argument the association
+ID shown in the <code>as</code> billboard. The <code>rv</code> command
+with no argument shows the system variables, while the <code>rv</code>
+command with association ID argument shows the peer variables for the
+clock, as well as any other peers of interest. The <code>clockvar</code>
+command with argument shows the peer variables specific to reference
+clock peers, including the clock status, device name, last received
+timecode (if relevant), and various event counters. In addition, a
+subset of the <code>fudge</code> parameters is included.
+
+<p>The <code>ntpdc</code> utility program can be used for detailed
+inspection of the clock driver status. The most useful are the
+<code>clockstat</code> and <code>clkbug</code> commands described in the
+document page. While these commands permit getting quite personal with
+the particular driver involved, their use is seldom necessary, unless an
+implementation bug shows up.
+
+<p>Most drivers write a message to the <code>clockstats</code> file as
+each timecode or surrogate is received from the radio clock. By
+convention, this is the last ASCII timecode (or ASCII gloss of a binary-
+coded one) received from the radio clock. This file is managed by the
+<code>filegen</code> facility described in the <code>ntpd</code> page
+and requires specific commands in the configuration file. This forms a
+highly useful record to discover anomalies during regular operation of
+the clock. The scripts included in the <code>./scripts/stats</code>
+directory can be run from a <code>cron</code> job to collect and
+summarize these data on a daily or weekly basis. The summary files have
+proven invaluable to detect infrequent misbehavior due to clock
+implementation bugs in some radios.
+<hr><address>David L. Mills (mills@udel.edu)</address></body></html>