1ntpdc(8) System Manager's Manual ntpdc(8)
2
6 ntpdc - special NTP query program
7
10 ntpdc [ -46dilnps ] [ -c command ] [ host ] [ ... ]
11
14 ntpdc is used to query the ntpd daemon about its current state and to
15 request changes in that state. The program may be run either in inter‐
16 active mode or controlled using command line arguments. Extensive state
17 and statistics information is available through the ntpdc interface. In
18 addition, nearly all the configuration options which can be specified
19 at startup using ntpd's configuration file may also be specified at run
20 time using ntpdc.
21 If one or more request options are included on the command line when
23 ntpdc is executed, each of the requests will be sent to the NTP servers
24 running on each of the hosts given as command line arguments, or on
25 localhost by default. If no request options are given, ntpdc will
26 attempt to read commands from the standard input and execute these on
27 the NTP server running on the first host given on the command line,
28 again defaulting to localhost when no other host is specified. ntpdc
29 will prompt for commands if the standard input is a terminal device.
30 ntpdc uses NTP mode 7 packets to communicate with the NTP server, and
32 hence can be used to query any compatible server on the network which
33 permits it. Note that since NTP is a UDP protocol this communication
34 will be somewhat unreliable, especially over large distances in terms
35 of network topology. ntpdc makes no attempt to retransmit requests, and
36 will time requests out if the remote host is not heard from within a
37 suitable timeout time.
38 The operation of ntpdc are specific to the particular implementation of
40 the ntpd daemon and can be expected to work only with this and maybe
41 some previous versions of the daemon. Requests from a remote ntpdc pro‐
42 gram which affect the state of the local server must be authenticated,
43 which requires both the remote program and local server share a common
44 key and key identifier.
45 Note that in contexts where a host name is expected, a -4 qualifier
47 preceding the host name forces DNS resolution to the IPv4 namespace,
48 while a -6 qualifier forces DNS resolution to the IPv6 namespace.
49
52 Specifying a command line option other than -i or -n will cause the
53 specified query (queries) to be sent to the indicated host(s) immedi‐
54 ately. Otherwise, ntpdc will attempt to read interactive format com‐
55 mands from the standard input.
56 -4 Force DNS resolution of following host names on the command
59 line to the IPv4 namespace.
60 -6 Force DNS resolution of following host names on the command
62 line to the IPv6 namespace.
63 -c command
65 The following argument is interpreted as an interactive format
66 command and is added to the list of commands to be executed on
67 the specified host(s). Multiple -c options may be given.
68 -d Turn on debugging mode.
70 -i Force ntpdc to operate in interactive mode. Prompts will be
72 written to the standard output and commands read from the stan‐
73 dard input.
74 -l Obtain a list of peers which are known to the server(s). This
76 switch is equivalent to -c listpeers.
77 -n Output all host addresses in dotted-quad numeric format rather
79 than converting to the canonical host names.
80 -p Print a list of the peers known to the server as well as a sum‐
82 mary of their state. This is equivalent to -c peers.
83 -s Print a list of the peers known to the server as well as a sum‐
85 mary of their state, but in a slightly different format than
86 the -p switch. This is equivalent to -c dmpeers.
87
90 Interactive format commands consist of a keyword followed by zero to
91 four arguments. Only enough characters of the full keyword to uniquely
92 identify the command need be typed. The output of a command is normally
93 sent to the standard output, but optionally the output of individual
94 commands may be sent to a file by appending a <, followed by a file
95 name, to the command line.
96 A number of interactive format commands are executed entirely within
98 the ntpdc program itself and do not result in NTP mode 7 requests being
99 sent to a server. These are described following.
100 ? [ command_keyword ]
103 help [ command_keyword ]
105 A ? by itself will print a list of all the command keywords
106 known to this incarnation of ntpq. A ? followed by a command
107 keyword will print function and usage information about the
108 command. This command is probably a better source of informa‐
109 tion about ntpq than this manual page.
110 delay milliseconds
112 Specify a time interval to be added to timestamps included in
113 requests which require authentication. This is used to enable
114 (unreliable) server reconfiguration over long delay network
115 paths or between machines whose clocks are unsynchronized.
116 Actually the server does not now require timestamps in authen‐
117 ticated requests, so this command may be obsolete.
118 host hostname
120 Set the host to which future queries will be sent. Hostname may
121 be either a host name or a numeric address.
122 hostnames [ yes | no ]
124 If yes is specified, host names are printed in information dis‐
125 plays. If no is specified, numeric addresses are printed
126 instead. The default is yes, unless modified using the command
127 line -n switch.
128 keyid keyid
130 This command allows the specification of a key number to be
131 used to authenticate configuration requests from ntpdc to the
132 host(s). This must correspond to a key number which the
133 host/server has been configured to use for this purpose (server
134 options: trustedkey, and requestkey). If authentication is not
135 enabled on the host(s) for ntpdc commands, the command "keyid
136 0" should be given; otherwise the keyid of the next subsequent
137 addpeer/addserver/broadcast command will be used.
138 quit Exit ntpdc.
140 passwd This command prompts you to type in a password (which will not
142 be echoed) which will be used to authenticate configuration
143 requests. The password must correspond to the key configured
144 for use by the NTP server for this purpose if such requests are
145 to be successful.
146 timeout milliseconds
148 Specify a timeout period for responses to server queries. The
149 default is about 8000 milliseconds. Note that since ntpdc
150 retries each query once after a timeout, the total waiting time
151 for a timeout will be twice the timeout value set.
152
155 Query commands result in NTP mode 7 packets containing requests for
156 information being sent to the server. These are read-only commands in
157 that they make no modification of the server configuration state.
158 listpeers
161 Obtains and prints a brief list of the peers for which the
162 server is maintaining state. These should include all config‐
163 ured peer associations as well as those peers whose stratum is
164 such that they are considered by the server to be possible
165 future synchronization candidates.
166 peers Obtains a list of peers for which the server is maintaining
168 state, along with a summary of that state. Summary information
169 includes the address of the remote peer, the local interface
170 address (0.0.0.0 if a local address has yet to be determined),
171 the stratum of the remote peer (a stratum of 16 indicates the
172 remote peer is unsynchronized), the polling interval, in sec‐
173 onds, the reachability register, in octal, and the current
174 estimated delay, offset and dispersion of the peer, all in sec‐
175 onds. The character in the left margin indicates the mode this
176 peer entry is operating in. A + denotes symmetric active, a -
177 indicates symmetric passive, a = means the remote server is
178 being polled in client mode, a ^ indicates that the server is
179 broadcasting to this address, a ~ denotes that the remote peer
180 is sending broadcasts and a * marks the peer the server is cur‐
181 rently synchronizing to.
182 The contents of the host field may be one of four forms. It may
184 be a host name, an IP address, a reference clock implementation
185 name with its parameter or REFCLK(implementation number, param‐
186 eter). On hostnames no only IP-addresses will be displayed.
187 dmpeers A slightly different peer summary list. Identical to the output
190 of the peers command, except for the character in the leftmost
191 column. Characters only appear beside peers which were included
192 in the final stage of the clock selection algorithm. A . indi‐
193 cates that this peer was cast off in the falseticker detection,
194 while a + indicates that the peer made it through. A * denotes
195 the peer the server is currently synchronizing with.
196 showpeer peer_address [...]
198 Shows a detailed display of the current peer variables for one
199 or more peers. Most of these values are described in the NTP
200 Version 2 specification.
201 pstats peer_address [...]
203 Show per-peer statistic counters associated with the specified
204 peer(s).
205 clockinfo clock_peer_address [...]
207 Obtain and print information concerning a peer clock. The val‐
208 ues obtained provide information on the setting of fudge fac‐
209 tors and other clock performance information.
210 kerninfo
212 Obtain and print kernel phase-lock loop operating parameters.
213 This information is available only if the kernel has been spe‐
214 cially modified for a precision timekeeping function.
215 loopinfo [ oneline | multiline ]
217 Print the values of selected loop filter variables. The loop
218 filter is the part of NTP which deals with adjusting the local
219 system clock. The offset is the last offset given to the loop
220 filter by the packet processing code. The frequency is the fre‐
221 quency error of the local clock in parts-per-million (ppm). The
222 time_const controls the stiffness of the phase-lock loop and
223 thus the speed at which it can adapt to oscillator drift. The
224 watchdog timer value is the number of seconds which have
225 elapsed since the last sample offset was given to the loop fil‐
226 ter. The oneline and multiline options specify the format in
227 which this information is to be printed, with multiline as the
228 default.
229 sysinfo Print a variety of system state variables, i.e., state related
231 to the local server. All except the last four lines are
232 described in the NTP Version 3 specification, RFC-1305. The
233 system flags show various system flags, some of which can be
234 set and cleared by the enable and disable configuration com‐
235 mands, respectively. These are the auth, bclient, monitor, pll,
236 pps and stats flags. See the ntpd documentation for the meaning
237 of these flags. There are two additional flags which are read
238 only, the kernel_pll and kernel_pps. These flags indicate the
239 synchronization status when the precision time kernel modifica‐
240 tions are in use. The kernel_pll indicates that the local clock
241 is being disciplined by the kernel, while the kernel_pps indi‐
242 cates the kernel discipline is provided by the PPS signal.
243 The stability is the residual frequency error remaining after
245 the system frequency correction is applied and is intended for
246 maintenance and debugging. In most architectures, this value
247 will initially decrease from as high as 500 ppm to a nominal
248 value in the range .01 to 0.1 ppm. If it remains high for some
249 time after starting the daemon, something may be wrong with the
250 local clock, or the value of the kernel variable tick may be
251 incorrect.
252 The broadcastdelay shows the default broadcast delay, as set by
254 the broadcastdelay configuration command.
255 The authdelay shows the default authentication delay, as set by
257 the authdelay configuration command.
258 sysstats
261 Print statistics counters maintained in the protocol module.
262 memstats
264 Print statistics counters related to memory allocation code.
265 iostats Print statistics counters maintained in the input-output mod‐
267 ule.
268 timerstats
270 Print statistics counters maintained in the timer/event queue
271 support code.
272 reslist Obtain and print the server's restriction list. This list is
274 (usually) printed in sorted order and may help to understand
275 how the restrictions are applied.
276 ifstats List interface statistics for interfaces used by ntpd for net‐
278 work communication.
279 ifreload
281 Force rescan of current system interfaces. Outputs interface
282 statistics for interfaces that could possibly change. Marks
283 unchanged interfaces with ., added interfaces with + and
284 deleted interfaces with -.
285 monlist [ version ]
287 Obtain and print traffic counts collected and maintained by the
288 monitor facility. The version number should not normally need
289 to be specified.
290 clkbug clock_peer_address [...]
292 Obtain debugging information for a reference clock driver. This
293 information is provided only by some clock drivers and is
294 mostly undecodable without a copy of the driver source in hand.
295
298 All requests which cause state changes in the server are authenticated
299 by the server using a configured NTP key (the facility can also be dis‐
300 abled by the server by not configuring a key). The key number and the
301 corresponding key must also be made known to ntpdc. This can be done
302 using the keyid and passwd commands, the latter of which will prompt at
303 the terminal for a password to use as the encryption key. You will also
304 be prompted automatically for both the key number and password the
305 first time a command which would result in an authenticated request to
306 the server is given. Authentication not only provides verification that
307 the requester has permission to make such changes, but also gives an
308 extra degree of protection again transmission errors.
309 Authenticated requests always include a timestamp in the packet data,
311 which is included in the computation of the authentication code. This
312 timestamp is compared by the server to its receive time stamp. If they
313 differ by more than a small amount the request is rejected. This is
314 done for two reasons. First, it makes simple replay attacks on the
315 server, by someone who might be able to overhear traffic on your LAN,
316 much more difficult. Second, it makes it more difficult to request con‐
317 figuration changes to your server from topologically remote hosts.
318 While the reconfiguration facility will work well with a server on the
319 local host, and may work adequately between time-synchronized hosts on
320 the same LAN, it will work very poorly for more distant hosts. As such,
321 if reasonable passwords are chosen, care is taken in the distribution
322 and protection of keys and appropriate source address restrictions are
323 applied, the run time reconfiguration facility should provide an ade‐
324 quate level of security.
325 The following commands all make authenticated requests.
327 addpeer peer_address [ keyid ] [ version ] [ minpoll# | prefer | iburst
330 | burst | minpoll N | maxpoll N [ dynamic ] [...] ]
331 addpeer peer_address [ prefer | iburst | burst | minpoll N | maxpoll N
333 | keyidN | version N [...] ]
334 Add a configured peer association at the given address and
335 operating in symmetric active mode. Note that an existing asso‐
336 ciation with the same peer may be deleted when this command is
337 executed, or may simply be converted to conform to the new con‐
338 figuration, as appropriate. If the keyid is nonzero, all outgo‐
339 ing packets to the remote server will have an authentication
340 field attached encrypted with this key. If the value is 0 (or
341 not given) no authentication will be done. If ntpdc's key num‐
342 ber has not yet been set (e.g., by the keyid command), it will
343 be set to this value. The version# can be 1 through 4 and
344 defaults to 3. The remaining options are either a numeric value
345 for minpoll or literals prefer, iburst, burst, minpoll N, keyid
346 N, version N, or maxpoll N (where N is a numeric value), and
347 have the action as specified in the peer configuration file
348 command of ntpd. See the Server Options page for further infor‐
349 mation. Each flag (or its absence) replaces the previous set‐
350 ting. The prefer keyword indicates a preferred peer (and thus
351 will be used primarily for clock synchronization if possible).
352 The preferred peer also determines the validity of the PPS sig‐
353 nal - if the preferred peer is suitable for synchronization so
354 is the PPS signal. The dynamic keyword allows association con‐
355 figuration even when no suitable network interface is found at
356 configuration time. The dynamic interface update mechanism may
357 complete the configuration when new interfaces appear (e.g.
358 WLAN/PPP interfaces) at a later time and thus render the asso‐
359 ciation operable.
360 addserver peer_address [ keyid ] [ version ] [ minpoll# | prefer |
362 iburst | burst | minpoll N | maxpoll N [...] ]
363 addserver peer_address [ prefer | iburst | burst | minpoll N | maxpoll
365 N | keyidN | version N [...] [ dynamic ] ]
366 Identical to the addpeer command, except that the operating
367 mode is client.
368 broadcast peer_address [ keyid ] [ version ] [ prefer ]
370 Identical to the addpeer command, except that the operating
371 mode is broadcast. In this case a valid non-zero key identifier
372 and key are required. The peer_address parameter can be the
373 broadcast address of the local network or a multicast group
374 address assigned to NTP. If a multicast address, a multicast-
375 capable kernel is required.
376 unconfig peer_address [...]
378 This command causes the configured bit to be removed from the
379 specified peer(s). In many cases this will cause the peer asso‐
380 ciation to be deleted. When appropriate, however, the associa‐
381 tion may persist in an unconfigured mode if the remote peer is
382 willing to continue on in this fashion.
383 fudge peer_address [ time1 ] [ time2 ] [ stratum ] [ refid ]
385 This command provides a way to set certain data for a reference
386 clock. See the source listing for further information.
387 enable [ auth | bclient | calibrate | kernel | monitor | ntp | pps |
389 stats]
390 disable [ auth | bclient | calibrate | kernel | monitor | ntp | pps |
392 stats]
393 These commands operate in the same way as the enable and dis‐
394 able configuration file commands of ntpd. See the Miscellaneous
395 Options page for further information.
396 restrict address mask flag [ flag ]
398 This command operates in the same way as the restrict configu‐
399 ration file commands of ntpd.
400 unrestrict address mask flag [ flag ]
402 Unrestrict the matching entry from the restrict list.
403 delrestrict address mask [ ntpport ]
405 Delete the matching entry from the restrict list.
406 readkeys
408 Causes the current set of authentication keys to be purged and
409 a new set to be obtained by rereading the keys file (which must
410 have been specified in the ntpd configuration file). This
411 allows encryption keys to be changed without restarting the
412 server.
413 trustedkey keyid [...]
415 untrustedkey keyid [...]
417 These commands operate in the same way as the trustedkey and
418 untrustedkey configuration file commands of ntpd.
419 authinfo
421 Returns information concerning the authentication module,
422 including known keys and counts of encryptions and decryptions
423 which have been done.
424 traps Display the traps set in the server. See the source listing for
426 further information.
427 addtrap [ address ] [ port ] [ interface ]
429 Set a trap for asynchronous messages. See the source listing
430 for further information.
431 clrtrap [ address ] [ port ] [ interface]
433 Clear a trap for asynchronous messages. See the source listing
434 for further information.
435 reset Clear the statistics counters in various modules of the server.
437 See the source listing for further information.
438
441 ntpdc is a crude hack. Much of the information it shows is deadly bor‐
442 ing and could only be loved by its implementer. The program was
443 designed so that new (and temporary) features were easy to hack in, at
444 great expense to the program's ease of use. Despite this, the program
445 is occasionally useful.
446
449 ntpd(8)
450 Primary source of documentation: /usr/share/doc/ntp-*
452 This file was automatically generated from HTML source.
454 ntpdc(8)