ntpmon - real-time NTP status monitor

ntpmon [-dhnuV] [-D lvl] [-l logfile] [host]

This program is a real-time status monitor for NTP. It presents the same information as the peers, mrulist, rv, and cv commands of ntpq(1), but using a split-window display that also includes a status summary bar, and updates at intervals guaranteed to show status changes almost as soon as they occur.

(Specifically, the display begins updating once per second and adjusts itself to poll at twice the frequency of the shortest polling interval reported in the last peers response.)

The status bar includes the version string of the server being watched, the (local) time at which it was last updated, and the current query interval in parens following the date.

There is a detail-display mode that dumps full information about a single selected peer in a tabular format that makes it relatively easy to see changing values. However, note that a default-sized terminal emulator window (usually 25 lines) doesn’t have enough room for the clock variables portion. The only fix for this is to resize your terminal.

^C cleanly terminates the program. Any keystroke will trigger a poll and update. A few single-keystroke commands are also interpreted as commands.

If no hostname is specified on the command line, localhost is monitored.

Here’s a breakdown of the peers display in the top window:

The t column has strange encodings due to historical use by old code. If you are looking at an old server, you might also see: s: symmetric (peer), server, B: broadcast server,

The tally code is one of the following:

And the MRU list in the bottom window:

The refid field is as described under "Event Messages and Status Words" in the NTP documentation on the Web.

When run in a terminal that does not allow UTF-8 ntpmon will downgrade its unit display to a non-unicode version. ntpmon has to interact with the curses and locale libraries, which prevents it from forcing the use of UTF-8.

When querying a version of ntpd older than NTPsec 0.9.6, ntpmon will appear to hang when monitoring hosts with extremely long MRU lists - in particular, public pool hosts. Correct behavior requires a Mode 6 protocol extension not yet present in those versions.

Even with this extension, monitoring a sufficiently high-traffic server sometimes fails.

When using the -u option, very old xterms may fail to render μ correctly. If this happens, be sure your xterm is started with the -u8 option, or the utf8 resource', and that your console font contains the UTF-8 μ character. Also confirm your LANG environment variable is set to a UTF-8 language, like this: "export LANG=en_US.utf8".

Timestamp interpretation in this program is likely to fail in flaky ways if the local system clock has not already been approximately synchronized to UTC. Querying a server based in a different NTP era than the current one is especially likely to fail.

This program will behave in apparently buggy and only semi-predictable ways when fetching MRU lists from any server with sufficiently high traffic.

The problem is fundamental. The Mode 6 protocol can’t ship (and your client cannot accept) MRU records as fast as the daemon accepts incoming traffic. Under these circumstances, the daemon will repeatedly fail to ship an entire report, leading to long hangs as your client repeatedly re-sends the request. Eventually the Mode 6 client library will throw an error indicating that a maximum number of restarts has been exceeded.

To avoid this problem, avoid monitoring over links that don’t have enough capacity to handle the monitored server’s entire NTP load.

The Mode 6 protocol used by ntpmon to communicate with ntpd(8) is described here.