Go to main content

man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2017

ntpdc (1m)


ntpdc - Network Time Protocol special query program


/usr/sbin/ntpdc  [-46lpsidnv?!] [-c command] [-D debuglvl] [-< optfile]
[-> optfile]  [host] [...]


System Administration Commands                                       ntpdc(1M)

       ntpdc - Network Time Protocol special query program

       /usr/sbin/ntpdc  [-46lpsidnv?!] [-c command] [-D debuglvl] [-< optfile]
       [-> optfile]  [host] [...]

       Specifying a command line option other than -i or  -n  will  cause  the
       specified  query  (queries) to be sent to the indicated host(s) immedi-
       ately. Otherwise, ntpdc will attempt to read  interactive  format  com-
       mands from the standard input.

       -4     Force DNS resolution of following host names on the command line
              to the IPv4 namespace.

       -6     Force DNS resolution of following host names on the command line
              to the IPv6 namespace.

       -c command
              The  argument  command  is interpreted as an interactive command
              and is added to the list of commands to be executed on the spec-
              ified host(s). Multiple -c options may be given.

       -i     Force  ntpdc  to  operate  in  interactive mode. Prompts will be
              written to the standard output and commands read from the  stan-
              dard input.

       -l     Obtain  a  list  of peers which are known to the server(s). This
              switch is equivalent to -c listpeers.

       -n     Output all host addresses in numeric format rather than convert-
              ing to the canonical host names.

       -p     Print  a list of the peers known to the server as well as a sum-
              mary of their state. This is equivalent to -c peers.

       -s     Print a list of the peers known to the server as well as a  sum-
              mary of their state, but in a slightly different format than the
              -p switch. This is equivalent to -c dmpeers.

       ntpdc is used to query the ntpd daemon about its current state  and  to
       request  changes in that state. The program may be run either in inter-
       active mode or controlled using command line arguments. Extensive state
       and statistics information is available through the ntpdc interface. In
       addition, nearly all the configuration options which can  be  specified
       at startup using ntpd's configuration file may also be specified at run
       time using ntpdc.  If one or more request options are included  on  the
       command  line when ntpdc is executed, each of the requests will be sent
       to the NTP servers running on each of the hosts given as  command  line
       arguments, or on localhost by default. If no request options are given,
       ntpdc will attempt to read commands from the standard input and execute
       these  on the NTP server running on the first host given on the command
       line, again defaulting to localhost when no other  host  is  specified.
       ntpdc  will  prompt  for  commands  if the standard input is a terminal

       ntpdc uses NTP mode 7 packets to communicate with the NTP  server,  and
       hence  can  be used to query any compatible server on the network which
       permits it. Note that since NTP is a UDP  protocol  this  communication
       will  be  somewhat unreliable, especially over large distances in terms
       of network topology. ntpdc makes no attempt to retransmit requests, and
       will  time  requests  out if the remote host is not heard from within a
       suitable timeout time.

       The operation of ntpdc are specific to the particular implementation of
       the  ntpd  daemon  and can be expected to work only with this and maybe
       some previous versions of the daemon. Requests from a remote ntpdc pro-
       gram  which affect the state of the local server must be authenticated,
       which requires both the remote program and local server share a  common
       key and key identifier.

       Note  that  in  contexts  where a host name is expected, a -4 qualifier
       preceding the host name forces DNS resolution to  the  IPv4  namespace,
       while a -6 qualifier forces DNS resolution to the IPv6 namespace.

   Interactive Commands
       Interactive  format  commands  consist of a keyword followed by zero to
       four arguments. Only enough characters of the full keyword to  uniquely
       identify the command need be typed. The output of a command is normally
       sent to the standard output, but optionally the  output  of  individual
       commands  may  be  sent  to a file by appending a >, followed by a file
       name, to the command line.

       A number of interactive format commands are  executed  entirely  within
       the ntpdc program itself and do not result in NTP mode 7 requests being
       sent to a server. These are described following.

       ? [ command_keyword ], help [ command_keyword ]
              A ? by itself will print a list  of  all  the  command  keywords
              known  to  this  incarnation  of ntpq. A ? followed by a command
              keyword will print function and usage information about the com-
              mand.  This  command  is probably a better source of information
              about ntpq than this manual page.

       delay milliseconds
              Specify a time interval to be added to  timestamps  included  in
              requests  which  require  authentication. This is used to enable
              (unreliable) server  reconfiguration  over  long  delay  network
              paths or between machines whose clocks are unsynchronized. Actu-
              ally the server does not now require timestamps in authenticated
              requests, so this command may be obsolete.

       host hostname
              Set  the host to which future queries will be sent. Hostname may
              be either a host name or a numeric address.

       hostnames [ yes | no ]
              If yes is specified, host names are printed in information  dis-
              plays.  If  no  is  specified,  numeric  addresses  are  printed
              instead. The default is yes, unless modified using  the  command
              line -n switch.

       keyid keyid
              This command allows the specification of a key number to be used
              to  authenticate  configuration  requests  from  ntpdc  to   the
              host(s).  This  must  correspond  to  a  key  number  which  the
              host/server has been configured to use for this purpose  (server
              options:  trustedkey, and requestkey).  If authentication is not
              enabled on the host(s) for ntpdc commands, the command "keyid 0"
              should  be  given;  otherwise  the  keyid of the next subsequent
               command will be used.


       exit   Exit ntpdc.

       debug [ no | more | less ]
              With no parameter displays the current ntpdc debug level. The no
              flag  turns  off all debugging, while more and less increase and
              decrease the level respectively.

       passwd This command prompts you to type in a password (which  will  not
              be  echoed)  which  will  be  used to authenticate configuration
              requests. The password must correspond to the key configured for
              use  by  the NTP server for this purpose if such requests are to
              be successful.

       timeout milliseconds
              Specify a timeout period for responses to  server  queries.  The
              default  is  about  8000  milliseconds.  Note  that  since ntpdc
              retries each query once after a timeout, the total waiting  time
              for a timeout will be twice the timeout value set.

              Display the version of the ntpdc command.

   Control Message Commands
       Query  commands  result  in  NTP mode 7 packets containing requests for
       information being sent to the server. These are read-only  commands  in
       that they make no modification of the server configuration state.

              Obtains  and  prints  a  brief  list  of the peers for which the
              server is maintaining state. These should include all configured
              peer  associations  as well as those peers whose stratum is such
              that they are considered by the server  to  be  possible  future
              synchronization candidates.

       peers  Obtains  a  list  of  peers  for which the server is maintaining
              state, along with a summary of that state.  Summary  information
              includes  the  address  of  the remote peer, the local interface
              address ( if a local address has yet to  be  determined),
              the  stratum  of  the remote peer (a stratum of 16 indicates the
              remote peer is unsynchronized), the polling  interval,  in  sec-
              onds, the reachability register, in octal, and the current esti-
              mated delay, offset and dispersion of the peer, all in  seconds.
              The  character  in  the left margin indicates the mode this peer
              entry is operating in. A + denotes symmetric active, a  -  indi-
              cates  symmetric  passive,  a = means the remote server is being
              polled in client mode, a ^ indicates that the server  is  broad-
              casting  to  this  address,  a ~ denotes that the remote peer is
              sending broadcasts and a * marks the peer  the  server  is  cur-
              rently  synchronizing to.  The contents of the host field may be
              one of four forms. It may be a host name, an IP address, a  ref-
              erence  clock  implementation  name  with  its parameter or REF-
              CLK(implementation number, parameter).  If  the  "hostnames  no"
              command has been given only IP-addresses will be displayed.

              A  slightly different peer summary list. Identical to the output
              of the peers command, except for the character in  the  leftmost
              column.  Characters only appear beside peers which were included
              in the final stage of the clock selection algorithm. A  .  indi-
              cates  that this peer was cast off in the falseticker detection,
              while a + indicates that the peer made it through. A  *  denotes
              the peer the server is currently synchronizing with.

       showpeer peer_address [...]
              Shows  a  detailed display of the current peer variables for one
              or more peers. Most of these values are  described  in  the  NTP
              Version 2 specification.

       pstats peer_address [...]
              Show  per-peer  statistic counters associated with the specified

       clockstat clock_peer_address [...]
              Obtain and print information concerning a peer clock. The values
              obtained provide information on the setting of fudge factors and
              other clock performance information.

              Obtain and print kernel phase-lock  loop  operating  parameters.
              This  information is available if the host supports the ntp_adj-
              time system call.

       loopinfo [ oneline | multiline ]
              Print the values of selected loop  filter  variables.  The  loop
              filter  is  the part of NTP which deals with adjusting the local
              system clock. The offset is the last offset given  to  the  loop
              filter  by the packet processing code. The frequency is the fre-
              quency error of the local clock in parts-per-million (ppm).  The
              time_const  controls  the  stiffness  of the phase-lock loop and
              thus the speed at which it can adapt to  oscillator  drift.  The
              watchdog timer value is the number of seconds which have elapsed
              since the last sample offset was given to the loop  filter.  The
              oneline  and  multiline options specify the format in which this
              information is to be printed, with multiline as the default.

              Print a variety of system state variables, i.e.,  state  related
              to  the  local  server.  All  except  the  last  four  lines are
              described in the NTP Version  3  specification,  RFC-1305.   The
              system flags show various system flags, some of which can be set
              and cleared by the enable and  disable  configuration  commands,
              respectively. These are the auth, bclient, monitor, pll, pps and
              stats flags. See the ntpd documentation for the meaning of these
              flags.  There  are two additional flags which are read only, the
              kernel_pll and kernel_pps. These flags indicate the synchroniza-
              tion  status when the precision time kernel modifications are in
              use. The kernel_pll indicates that the local clock is being dis-
              ciplined  by the kernel, while the kernel_pps indicates the ker-
              nel discipline is provided by the PPS signal.  The stability  is
              the  residual  frequency  error  remaining after the system fre-
              quency correction is applied and is intended for maintenance and
              debugging.  In  most  architectures,  this  value will initially
              decrease from as high as 500 ppm to a nominal value in the range
              .01  to 0.1 ppm. If it remains high for some time after starting
              the daemon, something may be wrong with the local clock, or  the
              value  of the kernel variable tick may be incorrect.  The broad-
              castdelay shows the default  broadcast  delay,  as  set  by  the
              broadcastdelay  configuration  command.  The authdelay shows the
              default authentication delay, as set by the authdelay configura-
              tion command.

              Print statistics counters maintained in the protocol module.

              Print statistics counters maintained in the control module.

              Print statistics counters related to memory allocation code.

              Print statistics counters maintained in the input-output module.

              Print  statistics  counters  maintained in the timer/event queue
              support code.

              Obtain and print the server's restriction  list.  This  list  is
              (usually) printed in sorted order and may help to understand how
              the restrictions are applied.

              List interface statistics for interfaces used by ntpd  for  net-
              work communication.

              Force  rescan  of  current  system interfaces. Outputs interface
              statistics for interfaces  that  could  possibly  change.  Marks
              unchanged interfaces with ., added interfaces with + and deleted
              interfaces with -.

       monlist [ version ]
              Obtain and print traffic counts collected and maintained by  the
              monitor facility. The version number should not normally need to
              be specified.

       clkbug clock_peer_address [...]
              Obtain debugging information for a reference clock driver.  This
              information is provided only by some clock drivers and is mostly
              undecodable without a copy of the driver source in hand.

   Runtime Configuration Requests
       All requests which cause state changes in the server are  authenticated
       by the server using a configured NTP key (the facility can also be dis-
       abled by the server by not configuring a key). The key number  and  the
       corresponding  key  must  also be made known to ntpdc. This can be done
       using the keyid and passwd commands, the latter of which will prompt at
       the terminal for a password to use as the encryption key. You will also
       be prompted automatically for both the  key  number  and  password  the
       first  time a command which would result in an authenticated request to
       the server is given. Authentication not only provides verification that
       the  requester  has  permission to make such changes, but also gives an
       extra degree of protection against transmission errors.

       Authenticated requests always include a timestamp in the  packet  data,
       which  is  included in the computation of the authentication code. This
       timestamp is compared by the server to its receive time stamp. If  they
       differ  by  more  than  a small amount the request is rejected. This is
       done for two reasons. First, it makes  simple  replay  attacks  on  the
       server,  by  someone who might be able to overhear traffic on your LAN,
       much more difficult. Second, it makes it more difficult to request con-
       figuration  changes  to  your  server  from topologically remote hosts.
       While the reconfiguration facility will work well with a server on  the
       local  host, and may work adequately between time-synchronized hosts on
       the same LAN, it will work very poorly for more distant hosts. As such,
       if  reasonable  passwords are chosen, care is taken in the distribution
       and protection of keys and appropriate source address restrictions  are
       applied,  the  run time reconfiguration facility should provide an ade-
       quate level of security.

       The following commands all make authenticated requests.

       addpeer peer_address [ keyid ] [ version ]
              [ minpoll# | prefer | iburst  | burst | minpoll N | maxpoll N  [
              dynamic ] [...] ]

       addpeer peer_address [ prefer | iburst | burst | minpoll N
              | maxpoll N | keyid N | version N [...] ]

              Add a configured peer association at the given address and oper-
              ating in symmetric active mode. Note that an  existing  associa-
              tion with the same peer may be deleted when this command is exe-
              cuted, or may simply be converted to conform to the new configu-
              ration,  as  appropriate.  If the keyid is nonzero, all outgoing
              packets to the remote server will have an  authentication  field
              attached  encrypted  with  this  key.  If the value is 0 (or not
              given) no authentication will be done. If ntpdc's key number has
              not yet been set (e.g., by the keyid command), it will be set to
              this value.  The version# can be 1 through 4 and defaults to  3.
              The remaining options are either a numeric value for minpoll# or
              literals prefer, iburst, burst, minpoll  N, keyid N, version  N,
              or  maxpoll  N (where N is a numeric value), and have the action
              as specified in the peer configuration  file  command  of  ntpd.
              See  the  server options page  at file:///usr/share/doc/ntp/con-
              fopt.html for further information.  Each flag (or  its  absence)
              replaces  the  previous  setting. The prefer keyword indicates a
              preferred peer (and thus will be used primarily for  clock  syn-
              chronisation  if  possible).  The preferred peer also determines
              the validity of the PPS signal - if the preferred peer is  suit-
              able for synchronisation so is the PPS signal.  The dynamic key-
              word allows association configuration even when no suitable net-
              work  interface  is  found  at  configuration  time. The dynamic
              interface update mechanism may complete the  configuration  when
              new interfaces appear (e.g. WLAN/PPP interfaces) at a later time
              and thus render the association operable.

       addserver peer_address [ keyid ] [ version ] [minpoll#
              | prefer | iburst  | burst | minpoll N | maxpoll N [...] ]

       addserver peer_address [ prefer | iburst | burst | minpoll N
              | maxpoll N | keyid N | version N [...] [ dynamic ] ]

              Identical to the addpeer command, except that the operating mode
              is client.

       addrefclock clock_address [  mode [ prefer | burst | minpoll N
              | maxpoll N  ...]]

              Identical  to  the addpeer command, except that the address is a
              REFCLOCK  designator  and  it  configures  a  hardware  refclock
              instead of a remote server.

       broadcast peer_address [ keyid ] [ version ] [ prefer ]
              Identical to the addpeer command, except that the operating mode
              is broadcast. In this case a valid non-zero key  identifier  and
              key  are  required. The peer_address parameter can be the broad-
              cast address of the local network or a multicast  group  address
              assigned  to  NTP.  If  a multicast address, a multicast-capable
              kernel is required.

       unconfig peer_address [...]
              This command causes the configured bit to be  removed  from  the
              specified  peer(s). In many cases this will cause the peer asso-
              ciation to be deleted. When appropriate, however,  the  associa-
              tion  may  persist in an unconfigured mode if the remote peer is
              willing to continue on in this fashion.

       fudge peer_address [ time1 ] [ time2 ] [ stratum ] [ refid ]
              This command provides a way to set certain data for a  reference
              clock. See the source listing for further information.

       enable  [  auth  | bclient | calibrate | kernel | monitor | ntp | pps |

       disable [ auth | bclient | calibrate | kernel | monitor | ntp |  pps  |
              These commands operate in the same way as the enable and disable
              configuration file commands  of  ntpd.  See  the  <a  href="mis-
              copt.html">Miscellaneous  Options</a>  page for further informa-

       restrict address mask flag [ flag ]
              This command operates in the same way as the restrict configura-
              tion file commands of ntpd.

       unrestrict address mask flag [ flag ]
              Unrestrict the matching entry from the restrict list.

       delrestrict address mask [ ntpport ]
              Delete the matching entry from the restrict list.

              Causes the current set of authentication keys to be purged and a
              new set to be obtained by rereading the keys  file  (which  must
              have been specified in the ntpd configuration file). This allows
              encryption keys to be changed without restarting the server.

       trustedkey keyid [...]

       untrustedkey keyid [...]

       controlkey keyid [...]

       requestkey keyid [...]
              These commands operate in the same way as the corresponding con-
              figuration file commands of ntpd.

       keytype md5
              This  command specifies the default keytype. Since the only type
              currently support is md5, this is a nop.

              Returns  information  concerning  the   authentication   module,
              including  known  keys and counts of encryptions and decryptions
              which have been done.

       traps  Display the traps set in the server. See the source listing  for
              further information.

       addtrap [ address [ port ] [ interface ]
              Set a trap for asynchronous messages. See the source listing for
              further information.

       clrtrap [ address [ port ] [ interface]
              Clear a trap for asynchronous messages. See the  source  listing
              for further information.

       reset  Clear  the statistics counters in various modules of the server.
              See the source listing for further information.

       preset [peer_address [...]]
              Clear the statistics counters in various modules of  the  server
              with respect to the indicated peers.

       Most options may be preset by loading values from configuration file(s)
       and values from environment variables named:
         NTPDC_<option-name> or NTPDC
       The environmental presets take precedence (are  processed  later  than)
       the  configuration files. The option-name should be in all capital let-
       ters.  For example, to set the --command  option,  you  would  set  the
       NTPDC_COMMAND  environment  variable.  The users home directory and the
       current directory are searched for a file named .ntprc.

       See attributes(5) for descriptions of the following attributes:

       |Availability   | service/network/ntp  |
       |Stability      | Uncommitted obsolete |
       ntpd(1M), ntpq(1M), ntprc(4), attributes(5)

       This    software    was    built    from    source     available     at
       https://java.net/projects/solaris-userland.    The  original  community
       source         was         downloaded         from           http://ar-

       Further information about this software can be found on the open source
       community website at http://www.ntp.org/.