1ntpdc(8)                         User Commands                        ntpdc(8)
2
3
4

NAME

6       ntpdc - vendor-specific NTPD control program
7

SYNOPSIS

9       ntpdc [-flags] [-flag [value]] [--option-name[[=| ]value]] [ host ...]
10
11

DESCRIPTION

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
16       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

OPTIONS

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
30              Force DNS resolution of following host names on the command line
31              to the IPv4 namespace.
32
33       -6, --ipv6
34              Force  IPv6 DNS name resolution.  This option must not appear in
35              combination with any of the following options: ipv4.
36
37              Force DNS resolution of following host names on the command line
38              to the IPv6 namespace.
39
40       -c cmd, --command=cmd
41              run  a  command  and  exit.  This option may appear an unlimited
42              number of times.
43
44              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
48       -d, --debug-level
49              Increase debug verbosity  level.   This  option  may  appear  an
50              unlimited number of times.
51
52
53       -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
58
59       -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
64              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
68       -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
72              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
76       -n, --numeric
77              numeric host addresses.
78
79              Output all host addresses in dotted-quad numeric  format  rather
80              than converting to the canonical host names.
81
82       -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
86              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
90       -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
94              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
98       -?, --help
99              Display usage information and exit.
100
101       -!, --more-help
102              Pass the extended usage information through a pager.
103
104       -> [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
109       -< 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
114       --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

OPTION PRESETS

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

USAGE

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
140       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
148       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
155       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
163   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
171       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
175       ? command_keyword
176
177       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
184       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
192       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
196       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
202       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
208       quit   Exit ntpdc.
209
210       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
216       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
222   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
227       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
234       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
243              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
252              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
257       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
266       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
271       pstats peer_address [...]
272              Show per-peer statistic counters associated with  the  specified
273              peer(s).
274
275       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
280       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
285       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
299       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
304              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
316              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
325              The  ‘broadcastdelay’  shows the default broadcast delay, as set
326              by the broadcastdelay configuration command.
327
328              The ‘authdelay’ shows the default authentication delay,  as  set
329              by the authdelay configuration command.
330
331       sysstats
332              Print statistics counters maintained in the protocol module.
333
334       memstats
335              Print statistics counters related to memory allocation code.
336
337       iostats
338              Print statistics counters maintained in the input-output module.
339
340       timerstats
341              Print  statistics  counters  maintained in the timer/event queue
342              support code.
343
344       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
349       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
354       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
359   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
372       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
388       The following commands all make authenticated requests.
389
390       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
405       addserver peer_address [keyid] [version] [prefer]
406              Identical to the addpeer command, except that the operating mode
407              is client.
408
409       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
417       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
424       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
428       enable  [auth  |  bclient  | calibrate | kernel | monitor | ntp | pps |
429       stats]
430
431       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
436              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
441              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
447              calibrate
448                     Enables the calibrate feature for reference clocks.   The
449                     default for this flag is disable.
450
451              kernel Enables  the  kernel  time discipline, if available.  The
452                     default for this flag is enable if support is  available,
453                     otherwise disable.
454
455              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
460              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
464              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
471              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
475       restrict address mask flag [...]
476              This command operates in the same way as the restrict configura‐
477              tion file commands of ntpd(8).
478
479       unrestrict address mask flag [...]
480              Unrestrict the matching entry from the restrict list.
481
482       delrestrict address mask [ntpport]
483              Delete the matching entry from the restrict list.
484
485       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
492       trustedkey keyid [...]
493
494       untrustedkey keyid [...]
495              These  commands  operate  in  the same way as the trustedkey and
496              untrustedkey configuration file commands of ntpd(8).
497
498       authinfo
499              Returns  information  concerning  the   authentication   module,
500              including  known  keys and counts of encryptions and decryptions
501              which have been done.
502
503       traps  Display the traps set in the server.  See the source listing for
504              further information.
505
506       addtrap address [port] [interface]
507              Set  a  trap  for asynchronous messages.  See the source listing
508              for further information.
509
510       clrtrap address [port] [interface]
511              Clear a trap for asynchronous messages.  See the source  listing
512              for further information.
513
514       reset  Clear  the statistics counters in various modules of the server.
515              See the source listing for further information.
516

ENVIRONMENT

518       See OPTION PRESETS for configuration environment variables.
519

FILES

521       See OPTION PRESETS for configuration files.
522

EXIT STATUS

524       One of the following exit values will be returned:
525
526       0  (EXIT_SUCCESS)
527              Successful program execution.
528
529       1  (EXIT_FAILURE)
530              The operation failed or the command syntax was not valid.
531
532       66  (EX_NOINPUT)
533              A specified configuration file could not be loaded.
534
535       70  (EX_SOFTWARE)
536              libopts had an internal operational error.  Please report it  to
537              autogen-users@lists.sourceforge.net.  Thank you.
538

SEE ALSO

540       ntp.conf(5), ntpd(8) David L. Mills, Network Time Protocol (Version 3),
541       RFC1305
542

AUTHORS

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

BUGS

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
558       Please report bugs to http://bugs.ntp.org .
559
560       Please send bug reports to: http://bugs.ntp.org, bugs@ntp.org
561

NOTES

563       This manual page was AutoGen-erated from the ntpdc option definitions.
564
565
566
5674.2.8p13                          20 Feb 2019                         ntpdc(8)
Impressum