1NTPMON(1) NTPsec NTPMON(1)
2
6 ntpmon - real-time NTP status monitor
7
9 ntpmon [-dhnuV] [-D lvl] [-l logfile] [host]
10
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 (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 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 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 ^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 If no hostname is specified on the command line, localhost is
38 monitored.
39 Here’s a breakdown of the peers display in the top window:
41 ┌─────────┬────────────────────────────┐
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 The tally code is one of the following:
96 ┌─────┬───────────────────────────┐
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 And the MRU list in the bottom window:
133 ┌───────────────┬────────────────────────────┐
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 The refid field is as described under "Event Messages and Status Words"
205 in the NTP documentation on the Web.
206
208 a
209 Change peer display to apeers mode, showing association IDs.
210 d
212 Toggle detail mode (some peer will be reverse-video highlighted
213 when on).
214 h
216 Display help screen
217 j
219 Select next peer (in select mode); arrow down also works.
220 k
222 Select previous peer (in select mode); arrow up also works.
223 m
225 Toggle MRUlist-only mode; suppresses peer display when on.
226 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 o
233 Change peer display to opeers mode, showing destination address.
234 p
236 Change peer display to default mode, showing refid.
237 q
239 Cleanly terminate the program.
240 s
242 Toggle display of only reachable hosts (default is all hosts).
243 u
245 Toggle display of units for time values. (default is off)
246 w
248 Toggle wide mode.
249 x
251 Cleanly terminate the program.
252 <space>
254 Rotate through a/n/o/p display modes.
255 +
257 Increase debugging level. Output goes to ntpmon.log
258 -
260 Decrease debugging level.
261 ?
263 Display help screen
264
266 -d
267 Increase output debug message level
268 • may appear multiple times
270 -D
272 Set the output debug message level
273 • may appear multiple times
275 -h
277 Print a usage message.
278 -l
280 Logs debug messages to the provided filename
281 -n
283 Show IP addresses (vs. hostnames)
284 -s, --srcname
286 Show srchost first then names and numbers
287 -S, --srcnumber
289 Show srchost first then numbers
290 -u
292 Show units
293 -V
295 Display version and exit.
296
298 When run in a terminal that does not allow UTF-8 ntpmon will downgrade
299 its unit display to a non-unicode version. ntpmon has to interact with
300 the curses and locale libraries, which prevents it from forcing the use
301 of UTF-8.
302 When querying a version of ntpd older than NTPsec 0.9.6, ntpmon will
304 appear to hang when monitoring hosts with extremely long MRU lists - in
305 particular, public pool hosts. Correct behavior requires a Mode 6
306 protocol extension not yet present in those versions.
307 Even with this extension, monitoring a sufficiently high-traffic server
309 sometimes fails.
310 When using the -u option, very old xterms may fail to render μ
312 correctly. If this happens, be sure your xterm is started with the -u8
313 option, or the utf8 resource', and that your console font contains the
314 UTF-8 &mu character. Also confirm your LANG environment variable is set
315 to a UTF-8 language, like this: "export LANG=en_US.utf8".
316 Timestamp interpretation in this program is likely to fail in flaky
318 ways if the local system clock has not already been approximately
319 synchronized to UTC. Querying a server based in a different NTP era
320 than the current one is especially likely to fail.
321 This program will behave in apparently buggy and only semi-predictable
323 ways when fetching MRU lists from any server with sufficiently high
324 traffic.
325 The problem is fundamental. The Mode 6 protocol can’t ship (and your
327 client cannot accept) MRU records as fast as the daemon accepts
328 incoming traffic. Under these circumstances, the daemon will repeatedly
329 fail to ship an entire report, leading to long hangs as your client
330 repeatedly re-sends the request. Eventually the Mode 6 client library
331 will throw an error indicating that a maximum number of restarts has
332 been exceeded.
333 To avoid this problem, avoid monitoring over links that don’t have
335 enough capacity to handle the monitored server’s entire NTP load.
336
338 Always returns 0.
339NTPsec 2021-02-01 NTPMON(1)