1NTPMON(1)                           NTPsec                           NTPMON(1)
2
3
4

NAME

6       ntpmon - real-time NTP status monitor
7

SYNOPSIS

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

DESCRIPTION

12       This program is a real-time status monitor for NTP. It presents the
13       same information as the peers, mrulist, rv, and cv commands of ntpq(1),
14       but using a split-window display that also includes a status summary
15       bar, and updates at intervals guaranteed to show status changes almost
16       as soon as they occur.
17
18       (Specifically, the display begins updating once per second and adjusts
19       itself to poll at twice the frequency of the shortest polling interval
20       reported in the last peers response.)
21
22       The status bar includes the version string of the server being watched,
23       the (local) time at which it was last updated, and the current query
24       interval in parens following the date.
25
26       There is a detail-display mode that dumps full information about a
27       single selected peer in a tabular format that makes it relatively easy
28       to see changing values. However, note that a default-sized terminal
29       emulator window (usually 25 lines) doesn’t have enough room for the
30       clock variables portion. The only fix for this is to resize your
31       terminal.
32
33       ^C cleanly terminates the program. Any keystroke will trigger a poll
34       and update. A few single-keystroke commands are also interpreted as
35       commands.
36
37       If no hostname is specified on the command line, localhost is
38       monitored.
39
40       Here’s a breakdown of the peers display in the top window:
41
42       ┌─────────┬────────────────────────────┐
43       │         │                            │
44       │Variable │ Description                │
45       ├─────────┼────────────────────────────┤
46       │         │                            │
47       │tally    │ single-character code      │
48       │         │ indicating current value   │
49       │         │ of the select field of the │
50       │         │ peer status word           │
51       │         │ <decode.html#peer>         │
52       ├─────────┼────────────────────────────┤
53       │         │                            │
54       │remote   │ host name (or IP number)   │
55       │         │ of peer                    │
56       ├─────────┼────────────────────────────┤
57       │         │                            │
58       │refid    │ association ID or kiss     │
59       │         │ code <decode.html#kiss>    │
60       ├─────────┼────────────────────────────┤
61       │         │                            │
62       │st       │ stratum                    │
63       ├─────────┼────────────────────────────┤
64       │         │                            │
65       │t        │ u: unicast or manycast     │
66       │         │ client, l: local           │
67       │         │ (reference clock), s:      │
68       │         │ symmetric (peer), server,  │
69       │         │ B: broadcast server, 1-8   │
70       │         │ NTS unicast with this      │
71       │         │ number of cookies stored.  │
72       ├─────────┼────────────────────────────┤
73       │         │                            │
74       │when     │ sec/min/hr since last      │
75       │         │ received packet            │
76       ├─────────┼────────────────────────────┤
77       │         │                            │
78       │poll     │ poll interval (log2 s)     │
79       ├─────────┼────────────────────────────┤
80       │         │                            │
81       │reach    │ reach shift register       │
82       │         │ (octal)                    │
83       ├─────────┼────────────────────────────┤
84       │         │                            │
85       │delay    │ roundtrip delay            │
86       ├─────────┼────────────────────────────┤
87       │         │                            │
88       │offset   │ offset of server relative  │
89       │         │ to this host               │
90       ├─────────┼────────────────────────────┤
91       │         │                            │
92       │jitter   │ jitter                     │
93       └─────────┴────────────────────────────┘
94
95       The tally code is one of the following:
96
97       ┌─────┬───────────────────────────┐
98       │     │                           │
99       │Code │ Description               │
100       ├─────┼───────────────────────────┤
101       │     │                           │
102       │     │ discarded as not valid    │
103       ├─────┼───────────────────────────┤
104       │     │                           │
105       │x    │ discarded by intersection │
106       │     │ algorithm                 │
107       ├─────┼───────────────────────────┤
108       │     │                           │
109       │.    │ discarded by table        │
110       │     │ overflow (not used)       │
111       ├─────┼───────────────────────────┤
112       │     │                           │
113       │-    │ discarded by the cluster  │
114       │     │ algorithm                 │
115       ├─────┼───────────────────────────┤
116       │     │                           │
117       │+    │ included by the combine   │
118       │     │ algorithm                 │
119       ├─────┼───────────────────────────┤
120       │     │                           │
121       │#    │ backup (more than tos     │
122       │     │ maxclock sources)         │
123       ├─────┼───────────────────────────┤
124       │     │                           │
125       │*    │ system peer               │
126       ├─────┼───────────────────────────┤
127       │     │                           │
128       │o    │ PPS peer (when the prefer │
129       │     │ peer is valid)            │
130       └─────┴───────────────────────────┘
131
132       And the MRU list in the bottom window:
133
134       ┌───────────────┬────────────────────────────┐
135       │               │                            │
136       │Column         │ Description                │
137       ├───────────────┼────────────────────────────┤
138       │               │                            │
139       │lstint         │ Interval in s between the  │
140       │               │ receipt of the most recent │
141       │               │ packet from this address   │
142       │               │ and the completion of the  │
143       │               │ retrieval of the MRU list  │
144       │               │ by ntpq.                   │
145       ├───────────────┼────────────────────────────┤
146       │               │                            │
147       │avgint         │ Average interval in s      │
148       │               │ between packets from this  │
149       │               │ address.                   │
150       ├───────────────┼────────────────────────────┤
151       │               │                            │
152       │rstr           │ Restriction flags          │
153       │               │ associated with this       │
154       │               │ address. Most are copied   │
155       │               │ unchanged from the         │
156       │               │ matching restrict command, │
157       │               │ however 0x400 (kod) and    │
158       │               │ 0x20 (limited) flags are   │
159       │               │ cleared unless the last    │
160       │               │ packet from this address   │
161       │               │ triggered a rate control   │
162       │               │ response.                  │
163       ├───────────────┼────────────────────────────┤
164       │               │                            │
165       │r              │ Rate control indicator,    │
166       │               │ either a period, L or K    │
167       │               │ for no rate control        │
168       │               │ response, rate limiting by │
169       │               │ discarding, or rate        │
170       │               │ limiting with a KoD        │
171       │               │ response, respectively.    │
172       ├───────────────┼────────────────────────────┤
173       │               │                            │
174       │m              │ Packet mode.               │
175       ├───────────────┼────────────────────────────┤
176       │               │                            │
177       │v              │ Packet version number.     │
178       ├───────────────┼────────────────────────────┤
179       │               │                            │
180       │count          │ Packets received from this │
181       │               │ address.                   │
182       ├───────────────┼────────────────────────────┤
183       │               │                            │
184       │score          │ Packets per second         │
185       │               │ (averaged with exponential │
186       │               │ decay).                    │
187       ├───────────────┼────────────────────────────┤
188       │               │                            │
189       │drop           │ Packets dropped (or KoDed) │
190       │               │ from this address.         │
191       ├───────────────┼────────────────────────────┤
192       │               │                            │
193       │rport          │ Source port of last packet │
194       │               │ from this address.         │
195       ├───────────────┼────────────────────────────┤
196       │               │                            │
197       │remote address │ DNS name, numeric address, │
198       │               │ or address followed by     │
199       │               │ claimed DNS name which     │
200       │               │ could not be verified in   │
201       │               │ parentheses.               │
202       └───────────────┴────────────────────────────┘
203
204       The refid field is as described under "Event Messages and Status Words"
205       in the NTP documentation on the Web.
206

COMMANDS

208       a
209           Change peer display to apeers mode, showing association IDs.
210
211       d
212           Toggle detail mode (some peer will be reverse-video highlighted
213           when on).
214
215       h
216           Display help screen
217
218       j
219           Select next peer (in select mode); arrow down also works.
220
221       k
222           Select previous peer (in select mode); arrow up also works.
223
224       m
225           Toggle MRUlist-only mode; suppresses peer display when on.
226
227       n
228           Toggle display of hostnames vs. IP addresses vs ntpd supplied names
229           plus IP addresses or ntpd supplied names and hostnames (default is
230           hostnames).
231
232       o
233           Change peer display to opeers mode, showing destination address.
234
235       p
236           Change peer display to default mode, showing refid.
237
238       q
239           Cleanly terminate the program.
240
241       r
242           Change to dextral mode, identical to p save that the refid, tally \
243           and remote clock are on the right.
244
245       s
246           Toggle display of only reachable hosts (default is all hosts).
247
248       u
249           Toggle display of units for time values. (default is off)
250
251       w
252           Toggle wide mode.
253
254       x
255           Cleanly terminate the program.
256
257       <space>
258           Rotate through a/n/o/p display modes.
259
260       +
261           Increase debugging level. Output goes to ntpmon.log
262
263       -
264           Decrease debugging level.
265
266       ?
267           Display help screen
268

OPTIONS

270       -d
271           Increase output debug message level
272
273           •   may appear multiple times
274
275       -D
276           Set the output debug message level
277
278           •   may appear multiple times
279
280       -h
281           Print a usage message.
282
283       -l
284           Logs debug messages to the provided filename
285
286       -n
287           Show IP addresses (vs. hostnames)
288
289       -s, --srcname
290           Show srchost first then names and numbers
291
292       -S, --srcnumber
293           Show srchost first then numbers
294
295       -u
296           Show units
297
298       -V
299           Display version and exit.
300

KNOWN BUGS

302       When run in a terminal that does not allow UTF-8 ntpmon will downgrade
303       its unit display to a non-unicode version. ntpmon has to interact with
304       the curses and locale libraries, which prevents it from forcing the use
305       of UTF-8.
306
307       When querying a version of ntpd older than NTPsec 0.9.6, ntpmon will
308       appear to hang when monitoring hosts with extremely long MRU lists - in
309       particular, public pool hosts. Correct behavior requires a Mode 6
310       protocol extension not yet present in those versions.
311
312       Even with this extension, monitoring a sufficiently high-traffic server
313       sometimes fails.
314
315       When using the -u option, very old xterms may fail to render &mu;
316       correctly. If this happens, be sure your xterm is started with the -u8
317       option, or the utf8 resource', and that your console font contains the
318       UTF-8 &mu; character. Also confirm your LANG environment variable is
319       set to a UTF-8 language, like this: "export LANG=en_US.utf8".
320
321       Timestamp interpretation in this program is likely to fail in flaky
322       ways if the local system clock has not already been approximately
323       synchronized to UTC. Querying a server based in a different NTP era
324       than the current one is especially likely to fail.
325
326       This program will behave in apparently buggy and only semi-predictable
327       ways when fetching MRU lists from any server with sufficiently high
328       traffic.
329
330       The problem is fundamental. The Mode 6 protocol can’t ship (and your
331       client cannot accept) MRU records as fast as the daemon accepts
332       incoming traffic. Under these circumstances, the daemon will repeatedly
333       fail to ship an entire report, leading to long hangs as your client
334       repeatedly re-sends the request. Eventually the Mode 6 client library
335       will throw an error indicating that a maximum number of restarts has
336       been exceeded.
337
338       To avoid this problem, avoid monitoring over links that don’t have
339       enough capacity to handle the monitored server’s entire NTP load.
340

EXIT STATUS

342       Always returns 0.
343
344
345
346NTPsec                            2021-07-22                         NTPMON(1)
Impressum