1ntpdc(8)                    System Manager's Manual                   ntpdc(8)
2
3
4

NAME

6       ntpdc - special NTP query program
7
8

SYNOPSIS

10       ntpdc [ -46dilnps ] [ -c command ] [ host ] [ ... ]
11
12

DESCRIPTION

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
22       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
31       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
39       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
46       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
50

COMMAND LINE OPTIONS

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
57
58       -4      Force DNS resolution of following host  names  on  the  command
59               line to the IPv4 namespace.
60
61       -6      Force  DNS  resolution  of  following host names on the command
62               line to the IPv6 namespace.
63
64       -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
69       -d      Turn on debugging mode.
70
71       -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
75       -l      Obtain a list of peers which are known to the  server(s).  This
76               switch is equivalent to -c listpeers.
77
78       -n      Output  all host addresses in dotted-quad numeric format rather
79               than converting to the canonical host names.
80
81       -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
84       -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
88

INTERACTIVE COMMANDS

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
97       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
101
102       ? [ command_keyword ]
103
104       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
111       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
119       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
123       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
129       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
139       quit    Exit ntpdc.
140
141       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
147       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
153

CONTROL MESSAGE COMMANDS

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
159
160       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
167       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
183               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
188
189       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
197       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
202       pstats peer_address [...]
203               Show per-peer statistic counters associated with the  specified
204               peer(s).
205
206       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
211       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
216       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
230       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
244               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
253               The broadcastdelay shows the default broadcast delay, as set by
254               the broadcastdelay configuration command.
255
256               The authdelay shows the default authentication delay, as set by
257               the authdelay configuration command.
258
259
260       sysstats
261               Print statistics counters maintained in the protocol module.
262
263       memstats
264               Print statistics counters related to memory allocation code.
265
266       iostats Print  statistics  counters maintained in the input-output mod‐
267               ule.
268
269       timerstats
270               Print statistics counters maintained in the  timer/event  queue
271               support code.
272
273       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
277       ifstats List  interface statistics for interfaces used by ntpd for net‐
278               work communication.
279
280       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
286       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
291       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
296

RUNTIME CONFIGURATION REQUESTS

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
310       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
326       The following commands all make authenticated requests.
327
328
329       addpeer peer_address [ keyid ] [ version ] [ minpoll# | prefer | iburst
330       | burst | minpoll N | maxpoll N [ dynamic ] [...] ]
331
332       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
361       addserver peer_address [ keyid ] [ version ]  [  minpoll#  |  prefer  |
362       iburst | burst | minpoll N | maxpoll N [...] ]
363
364       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
369       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
377       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
384       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
388       enable  [  auth  | bclient | calibrate | kernel | monitor | ntp | pps |
389       stats]
390
391       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
397       restrict address mask flag [ flag ]
398               This  command operates in the same way as the restrict configu‐
399               ration file commands of ntpd.
400
401       unrestrict address mask flag [ flag ]
402               Unrestrict the matching entry from the restrict list.
403
404       delrestrict address mask [ ntpport ]
405               Delete the matching entry from the restrict list.
406
407       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
414       trustedkey keyid [...]
415
416       untrustedkey keyid [...]
417               These commands operate in the same way as  the  trustedkey  and
418               untrustedkey configuration file commands of ntpd.
419
420       authinfo
421               Returns   information  concerning  the  authentication  module,
422               including known keys and counts of encryptions and  decryptions
423               which have been done.
424
425       traps   Display the traps set in the server. See the source listing for
426               further information.
427
428       addtrap [ address ] [ port ] [ interface ]
429               Set a trap for asynchronous messages. See  the  source  listing
430               for further information.
431
432       clrtrap [ address ] [ port ] [ interface]
433               Clear  a trap for asynchronous messages. See the source listing
434               for further information.
435
436       reset   Clear the statistics counters in various modules of the server.
437               See the source listing for further information.
438
439

BUGS

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
447

SEE ALSO

449       ntpd(8)
450
451       Primary source of documentation: /usr/share/doc/ntp-*
452
453       This file was automatically generated from HTML source.
454
455
456
457
458                                                                      ntpdc(8)
Impressum