Debugging Hints for Reference Clock Drivers

The ntpq and xntpdc 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 xntpd 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.

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.

If RS232 messages are getting to and from the clock, the variables of interest can be inspected using the ntpq program and various commands described on the documentation page. First, use the pe and as 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 pe billboard and the association ID for it at the same relative line position in the as billboard. If things are operating correctly, after a minute or two samples should show up in the pe display line for the clock.

Additional information is available with the rv and clockvar commands, which take as argument the association ID shown in the as billboard. The rv command with no argument shows the system variables, while the rv command with association ID argument shows the peer variables for the clock, as well as any other peers of interest. The clockvar 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 fudge parameters is included.

The xntpdc utility program can be used for detailed inspection of the clock driver status. The most useful are the clockstat and 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.

Most drivers write a message to the clockstats 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 filegen facility described in the xntpd 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 ./scripts/stats directory can be run from a cron 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.