1ntpdc(8) User Commands ntpdc(8)
2
6 ntpdc - vendor-specific NTPD control program
7
9 ntpdc [-flags] [-flag [value]] [--option-name[[=| ]value]] [ host ...]
10
13 ntpdc is deprecated. Please use ntpq(8) instead - it can do everything
14 ntpdc used to do, and it does so using a much more sane interface.
15 ntpdc is a utility program used to query ntpd(8) about its current
17 state and to request changes in that state. It uses NTP mode 7 control
18 message formats described in the source code. The program may be run
19 either in interactive mode or controlled using command line arguments.
20 Extensive state and statistics information is available through the
21 ntpdc interface. In addition, nearly all the configuration options
22 which can be specified at startup using ntpd's configuration file may
23 also be specified at run time using ntpdc.
24
26 -4, --ipv4
27 Force IPv4 DNS name resolution. This option must not appear in
28 combination with any of the following options: ipv6.
29 Force DNS resolution of following host names on the command line
31 to the IPv4 namespace.
32 -6, --ipv6
34 Force IPv6 DNS name resolution. This option must not appear in
35 combination with any of the following options: ipv4.
36 Force DNS resolution of following host names on the command line
38 to the IPv6 namespace.
39 -c cmd, --command=cmd
41 run a command and exit. This option may appear an unlimited
42 number of times.
43 The following argument is interpreted as an interactive format
45 command and is added to the list of commands to be executed on
46 the specified host(s).
47 -d, --debug-level
49 Increase debug verbosity level. This option may appear an
50 unlimited number of times.
51 -D number, --set-debug-level=number
54 Set the debug verbosity level. This option may appear an unlim‐
55 ited number of times. This option takes an integer number as
56 its argument.
57 -i, --interactive
60 Force ntpq to operate in interactive mode. This option must not
61 appear in combination with any of the following options: com‐
62 mand, listpeers, peers, showpeers.
63 Force ntpq to operate in interactive mode. Prompts will be
65 written to the standard output and commands read from the stan‐
66 dard input.
67 -l, --listpeers
69 Print a list of the peers. This option must not appear in com‐
70 bination with any of the following options: command.
71 Print a list of the peers known to the server as well as a sum‐
73 mary of their state. This is equivalent to the 'listpeers'
74 interactive command.
75 -n, --numeric
77 numeric host addresses.
78 Output all host addresses in dotted-quad numeric format rather
80 than converting to the canonical host names.
81 -p, --peers
83 Print a list of the peers. This option must not appear in com‐
84 bination with any of the following options: command.
85 Print a list of the peers known to the server as well as a sum‐
87 mary of their state. This is equivalent to the 'peers' interac‐
88 tive command.
89 -s, --showpeers
91 Show a list of the peers. This option must not appear in combi‐
92 nation with any of the following options: command.
93 Print a list of the peers known to the server as well as a sum‐
95 mary of their state. This is equivalent to the 'dmpeers' inter‐
96 active command.
97 -?, --help
99 Display usage information and exit.
100 -!, --more-help
102 Pass the extended usage information through a pager.
103 -> [cfgfile], --save-opts [=cfgfile]
105 Save the option state to cfgfile. The default is the last con‐
106 figuration file listed in the OPTION PRESETS section, below.
107 The command will exit after updating the config file.
108 -< cfgfile, --load-opts=cfgfile, --no-load-opts
110 Load options from cfgfile. The no-load-opts form will disable
111 the loading of earlier config/rc/ini files. --no-load-opts is
112 handled early, out of order.
113 --version [{v|c|n}]
115 Output version of program and exit. The default mode is `v', a
116 simple version. The `c' mode will print copyright information
117 and `n' will print the full copyright notice.
118
120 Any option that is not marked as not presettable may be preset by load‐
121 ing values from configuration ("RC" or ".INI") file(s) and values from
122 environment variables named:
123 NTPDC_<option-name> or NTPDC
124 The environmental presets take precedence (are processed later than)
125 the configuration files. The homerc files are "$HOME", and ".". If
126 any of these are directories, then the file .ntprc is searched for
127 within those directories.
128
130 If one or more request options are included on the command line when
131 ntpdc is executed, each of the requests will be sent to the NTP servers
132 running on each of the hosts given as command line arguments, or on
133 localhost by default. If no request options are given, ntpdc will
134 attempt to read commands from the standard input and execute these on
135 the NTP server running on the first host given on the command line,
136 again defaulting to localhost when no other host is specified. The
137 ntpdc utility will prompt for commands if the standard input is a ter‐
138 minal device.
139 The ntpdc utility uses NTP mode 7 packets to communicate with the NTP
141 server, and hence can be used to query any compatible server on the
142 network which permits it. Note that since NTP is a UDP protocol this
143 communication will be somewhat unreliable, especially over large dis‐
144 tances in terms of network topology. The ntpdc utility makes no
145 attempt to retransmit requests, and will time requests out if the
146 remote host is not heard from within a suitable timeout time.
147 The operation of ntpdc are specific to the particular implementation of
149 the ntpd(8) daemon and can be expected to work only with this and maybe
150 some previous versions of the daemon. Requests from a remote ntpdc
151 utility which affect the state of the local server must be authenti‐
152 cated, which requires both the remote program and local server share a
153 common key and key identifier.
154 Note that in contexts where a host name is expected, a -4 qualifier
156 preceding the host name forces DNS resolution to the IPv4 namespace,
157 while a -6 qualifier forces DNS resolution to the IPv6 namespace.
158 Specifying a command line option other than -i or -n will cause the
159 specified query (queries) to be sent to the indicated host(s) immedi‐
160 ately. Otherwise, ntpdc will attempt to read interactive format com‐
161 mands from the standard input.
162 Interactive Commands
164 Interactive format commands consist of a keyword followed by zero to
165 four arguments. Only enough characters of the full keyword to uniquely
166 identify the command need be typed. The output of a command is nor‐
167 mally sent to the standard output, but optionally the output of indi‐
168 vidual commands may be sent to a file by appending a ‘>’, followed by a
169 file name, to the command line.
170 A number of interactive format commands are executed entirely within
172 the ntpdc utility itself and do not result in NTP mode 7 requests being
173 sent to a server. These are described following.
174 ? command_keyword
176 help command_keyword
178 A ‘?’ will print a list of all the command keywords known to
179 this incarnation of ntpdc. A ‘?’ followed by a command keyword
180 will print function and usage information about the command.
181 This command is probably a better source of information about
182 ntpq(8) than this manual page.
183 delay milliseconds
185 Specify a time interval to be added to timestamps included in
186 requests which require authentication. This is used to enable
187 (unreliable) server reconfiguration over long delay network
188 paths or between machines whose clocks are unsynchronized.
189 Actually the server does not now require timestamps in authenti‐
190 cated requests, so this command may be obsolete.
191 host hostname
193 Set the host to which future queries will be sent. Hostname may
194 be either a host name or a numeric address.
195 hostnames [yes | no]
197 If yes is specified, host names are printed in information dis‐
198 plays. If no is specified, numeric addresses are printed
199 instead. The default is yes, unless modified using the command
200 line -n switch.
201 keyid keyid
203 This command allows the specification of a key number to be used
204 to authenticate configuration requests. This must correspond to
205 a key number the server has been configured to use for this pur‐
206 pose.
207 quit Exit ntpdc.
209 passwd This command prompts you to type in a password (which will not
211 be echoed) which will be used to authenticate configuration
212 requests. The password must correspond to the key configured
213 for use by the NTP server for this purpose if such requests are
214 to be successful.
215 timeout milliseconds
217 Specify a timeout period for responses to server queries. The
218 default is about 8000 milliseconds. Note that since ntpdc
219 retries each query once after a timeout, the total waiting time
220 for a timeout will be twice the timeout value set.
221 Control Message Commands
223 Query commands result in NTP mode 7 packets containing requests for
224 information being sent to the server. These are read-only commands in
225 that they make no modification of the server configuration state.
226 listpeers
228 Obtains and prints a brief list of the peers for which the
229 server is maintaining state. These should include all config‐
230 ured peer associations as well as those peers whose stratum is
231 such that they are considered by the server to be possible
232 future synchronization candidates.
233 peers Obtains a list of peers for which the server is maintaining
235 state, along with a summary of that state. Summary information
236 includes the address of the remote peer, the local interface
237 address (0.0.0.0 if a local address has yet to be determined),
238 the stratum of the remote peer (a stratum of 16 indicates the
239 remote peer is unsynchronized), the polling interval, in sec‐
240 onds, the reachability register, in octal, and the current esti‐
241 mated delay, offset and dispersion of the peer, all in seconds.
242 The character in the left margin indicates the mode this peer
244 entry is operating in. A ‘+’ denotes symmetric active, a ‘-’
245 indicates symmetric passive, a ‘=’ means the remote server is
246 being polled in client mode, a ‘^’ indicates that the server is
247 broadcasting to this address, a ‘~’ denotes that the remote peer
248 is sending broadcasts and a ‘~’ denotes that the remote peer is
249 sending broadcasts and a ‘*’ marks the peer the server is cur‐
250 rently synchronizing to.
251 The contents of the host field may be one of four forms. It may
253 be a host name, an IP address, a reference clock implementation
254 name with its parameter or REFCLK() On hostnames no only IP-
255 addresses will be displayed.
256 dmpeers
258 A slightly different peer summary list. Identical to the output
259 of the peers command, except for the character in the leftmost
260 column. Characters only appear beside peers which were included
261 in the final stage of the clock selection algorithm. A ‘.’
262 indicates that this peer was cast off in the falseticker detec‐
263 tion, while a ‘+’ indicates that the peer made it through. A
264 ‘*’ denotes the peer the server is currently synchronizing with.
265 showpeer peer_address [...]
267 Shows a detailed display of the current peer variables for one
268 or more peers. Most of these values are described in the NTP
269 Version 2 specification.
270 pstats peer_address [...]
272 Show per-peer statistic counters associated with the specified
273 peer(s).
274 clockstat clock_peer_address [...]
276 Obtain and print information concerning a peer clock. The val‐
277 ues obtained provide information on the setting of fudge factors
278 and other clock performance information.
279 kerninfo
281 Obtain and print kernel phase-lock loop operating parameters.
282 This information is available only if the kernel has been spe‐
283 cially modified for a precision timekeeping function.
284 loopinfo [oneline | multiline]
286 Print the values of selected loop filter variables. The loop
287 filter is the part of NTP which deals with adjusting the local
288 system clock. The ‘offset’ is the last offset given to the loop
289 filter by the packet processing code. The ‘frequency’ is the
290 frequency error of the local clock in parts-per-million (ppm).
291 The ‘time_const’ controls the stiffness of the phase-lock loop
292 and thus the speed at which it can adapt to oscillator drift.
293 The ‘watchdog timer’ value is the number of seconds which have
294 elapsed since the last sample offset was given to the loop fil‐
295 ter. The oneline and multiline options specify the format in
296 which this information is to be printed, with multiline as the
297 default.
298 sysinfo
300 Print a variety of system state variables, i.e., state related
301 to the local server. All except the last four lines are
302 described in the NTP Version 3 specification, RFC-1305.
303 The ‘system flags’ show various system flags, some of which can
305 be set and cleared by the enable and disable configuration com‐
306 mands, respectively. These are the auth, bclient, monitor, pll,
307 pps and stats flags. See the ntpd(8) documentation for the
308 meaning of these flags. There are two additional flags which
309 are read only, the kernel_pll and kernel_pps. These flags indi‐
310 cate the synchronization status when the precision time kernel
311 modifications are in use. The ‘kernel_pll’ indicates that the
312 local clock is being disciplined by the kernel, while the ‘ker‐
313 nel_pps’ indicates the kernel discipline is provided by the PPS
314 signal.
315 The ‘stability’ is the residual frequency error remaining after
317 the system frequency correction is applied and is intended for
318 maintenance and debugging. In most architectures, this value
319 will initially decrease from as high as 500 ppm to a nominal
320 value in the range .01 to 0.1 ppm. If it remains high for some
321 time after starting the daemon, something may be wrong with the
322 local clock, or the value of the kernel variable kern.clock‐
323 rate.tick may be incorrect.
324 The ‘broadcastdelay’ shows the default broadcast delay, as set
326 by the broadcastdelay configuration command.
327 The ‘authdelay’ shows the default authentication delay, as set
329 by the authdelay configuration command.
330 sysstats
332 Print statistics counters maintained in the protocol module.
333 memstats
335 Print statistics counters related to memory allocation code.
336 iostats
338 Print statistics counters maintained in the input-output module.
339 timerstats
341 Print statistics counters maintained in the timer/event queue
342 support code.
343 reslist
345 Obtain and print the server's restriction list. This list is
346 (usually) printed in sorted order and may help to understand how
347 the restrictions are applied.
348 monlist [version]
350 Obtain and print traffic counts collected and maintained by the
351 monitor facility. The version number should not normally need
352 to be specified.
353 clkbug clock_peer_address [...]
355 Obtain debugging information for a reference clock driver. This
356 information is provided only by some clock drivers and is mostly
357 undecodable without a copy of the driver source in hand.
358 Runtime Configuration Requests
360 All requests which cause state changes in the server are authenticated
361 by the server using a configured NTP key (the facility can also be dis‐
362 abled by the server by not configuring a key). The key number and the
363 corresponding key must also be made known to ntpdc. This can be done
364 using the keyid and passwd commands, the latter of which will prompt at
365 the terminal for a password to use as the encryption key. You will
366 also be prompted automatically for both the key number and password the
367 first time a command which would result in an authenticated request to
368 the server is given. Authentication not only provides verification
369 that the requester has permission to make such changes, but also gives
370 an extra degree of protection again transmission errors.
371 Authenticated requests always include a timestamp in the packet data,
373 which is included in the computation of the authentication code. This
374 timestamp is compared by the server to its receive time stamp. If they
375 differ by more than a small amount the request is rejected. This is
376 done for two reasons. First, it makes simple replay attacks on the
377 server, by someone who might be able to overhear traffic on your LAN,
378 much more difficult. Second, it makes it more difficult to request
379 configuration changes to your server from topologically remote hosts.
380 While the reconfiguration facility will work well with a server on the
381 local host, and may work adequately between time-synchronized hosts on
382 the same LAN, it will work very poorly for more distant hosts. As
383 such, if reasonable passwords are chosen, care is taken in the distri‐
384 bution and protection of keys and appropriate source address restric‐
385 tions are applied, the run time reconfiguration facility should provide
386 an adequate level of security.
387 The following commands all make authenticated requests.
389 addpeer peer_address [keyid] [version] [prefer]
391 Add a configured peer association at the given address and oper‐
392 ating in symmetric active mode. Note that an existing associa‐
393 tion with the same peer may be deleted when this command is exe‐
394 cuted, or may simply be converted to conform to the new configu‐
395 ration, as appropriate. If the optional keyid is a nonzero
396 integer, all outgoing packets to the remote server will have an
397 authentication field attached encrypted with this key. If the
398 value is 0 (or not given) no authentication will be done. The
399 version can be 1, 2 or 3 and defaults to 3. The prefer keyword
400 indicates a preferred peer (and thus will be used primarily for
401 clock synchronisation if possible). The preferred peer also
402 determines the validity of the PPS signal - if the preferred
403 peer is suitable for synchronisation so is the PPS signal.
404 addserver peer_address [keyid] [version] [prefer]
406 Identical to the addpeer command, except that the operating mode
407 is client.
408 broadcast peer_address [keyid] [version] [prefer]
410 Identical to the addpeer command, except that the operating mode
411 is broadcast. In this case a valid key identifier and key are
412 required. The peer_address parameter can be the broadcast
413 address of the local network or a multicast group address
414 assigned to NTP. If a multicast address, a multicast-capable
415 kernel is required.
416 unconfig peer_address [...]
418 This command causes the configured bit to be removed from the
419 specified peer(s). In many cases this will cause the peer asso‐
420 ciation to be deleted. When appropriate, however, the associa‐
421 tion may persist in an unconfigured mode if the remote peer is
422 willing to continue on in this fashion.
423 fudge peer_address [time1] [time2] [stratum] [refid]
425 This command provides a way to set certain data for a reference
426 clock. See the source listing for further information.
427 enable [auth | bclient | calibrate | kernel | monitor | ntp | pps |
429 stats]
430 disable [auth | bclient | calibrate | kernel | monitor | ntp | pps |
432 stats]
433 These commands operate in the same way as the enable and disable
434 configuration file commands of ntpd(8).
435 auth Enables the server to synchronize with unconfigured peers
437 only if the peer has been correctly authenticated using
438 either public key or private key cryptography. The
439 default for this flag is enable.
440 bclient
442 Enables the server to listen for a message from a broad‐
443 cast or multicast server, as in the multicastclient com‐
444 mand with default address. The default for this flag is
445 disable.
446 calibrate
448 Enables the calibrate feature for reference clocks. The
449 default for this flag is disable.
450 kernel Enables the kernel time discipline, if available. The
452 default for this flag is enable if support is available,
453 otherwise disable.
454 monitor
456 Enables the monitoring facility. See the documentation
457 here about the monlist command or further information.
458 The default for this flag is enable.
459 ntp Enables time and frequency discipline. In effect, this
461 switch opens and closes the feedback loop, which is use‐
462 ful for testing. The default for this flag is enable.
463 pps Enables the pulse-per-second (PPS) signal when frequency
465 and time is disciplined by the precision time kernel mod‐
466 ifications. See the "A Kernel Model for Precision Time‐
467 keeping" (available as part of the HTML documentation
468 provided in /usr/share/doc/ntp) page for further informa‐
469 tion. The default for this flag is disable.
470 stats Enables the statistics facility. See the Monitoring
472 Options section of ntp.conf(5) for further information.
473 The default for this flag is disable.
474 restrict address mask flag [...]
476 This command operates in the same way as the restrict configura‐
477 tion file commands of ntpd(8).
478 unrestrict address mask flag [...]
480 Unrestrict the matching entry from the restrict list.
481 delrestrict address mask [ntpport]
483 Delete the matching entry from the restrict list.
484 readkeys
486 Causes the current set of authentication keys to be purged and a
487 new set to be obtained by rereading the keys file (which must
488 have been specified in the ntpd(8) configuration file). This
489 allows encryption keys to be changed without restarting the
490 server.
491 trustedkey keyid [...]
493 untrustedkey keyid [...]
495 These commands operate in the same way as the trustedkey and
496 untrustedkey configuration file commands of ntpd(8).
497 authinfo
499 Returns information concerning the authentication module,
500 including known keys and counts of encryptions and decryptions
501 which have been done.
502 traps Display the traps set in the server. See the source listing for
504 further information.
505 addtrap address [port] [interface]
507 Set a trap for asynchronous messages. See the source listing
508 for further information.
509 clrtrap address [port] [interface]
511 Clear a trap for asynchronous messages. See the source listing
512 for further information.
513 reset Clear the statistics counters in various modules of the server.
515 See the source listing for further information.
516
518 See OPTION PRESETS for configuration environment variables.
519
521 See OPTION PRESETS for configuration files.
522
524 One of the following exit values will be returned:
525 0 (EXIT_SUCCESS)
527 Successful program execution.
528 1 (EXIT_FAILURE)
530 The operation failed or the command syntax was not valid.
531 66 (EX_NOINPUT)
533 A specified configuration file could not be loaded.
534 70 (EX_SOFTWARE)
536 libopts had an internal operational error. Please report it to
537 autogen-users@lists.sourceforge.net. Thank you.
538
540 ntp.conf(5), ntpd(8) David L. Mills, Network Time Protocol (Version 3),
541 RFC1305
542
544 The formatting directives in this document came from FreeBSD.
545
547 Copyright (C) 1992-2017 The University of Delaware and Network Time
548 Foundation all rights reserved. This program is released under the
549 terms of the NTP license, <http://ntp.org/license>.
550
552 The ntpdc utility is a crude hack. Much of the information it shows is
553 deadly boring and could only be loved by its implementer. The program
554 was designed so that new (and temporary) features were easy to hack in,
555 at great expense to the program's ease of use. Despite this, the pro‐
556 gram is occasionally useful.
557 Please report bugs to http://bugs.ntp.org .
559 Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
561
563 This manual page was AutoGen-erated from the ntpdc option definitions.
5644.2.8p13 20 Feb 2019 ntpdc(8)