man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2014

ntpdc (1m)


ntpdc - Network Time Protocol special query program


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


SunOS 5.11                                                      1

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 indi-
     cated host(s) immediately. Otherwise, ntpdc will attempt  to
     read interactive format commands 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 exe-
          cuted on the specified 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 standard 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
          converting to the canonical host names.

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

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

     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 interactive mode or controlled using com-
     mand line arguments. Extensive state and statistics informa-
     tion  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

SunOS 5.11                Last change:                          1

System Administration Commands                          ntpdc(1M)

     specified at run time using ntpdc.  If one or  more  request
     options  are included on the command line when ntpdc is exe-
     cuted, each of the requests will be sent to the NTP  servers
     running  on  each  of  the hosts given as command line argu-
     ments, 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 device.

     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 topol-
     ogy. 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 imple-
     mentation  of  the  ntpd  daemon and can be expected to work
     only with this and maybe some previous versions of the  dae-
     mon.  Requests  from a remote ntpdc program 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  resolu-
     tion 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 key-
          words  known  to this incarnation of ntpq. A ? followed
          by a command keyword  will  print  function  and  usage
          information about the command. This command is probably

SunOS 5.11                Last change:                          2

System Administration Commands                          ntpdc(1M)

          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. Actually 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

     hostnames [ yes | no ]
          If yes is specified, host names are printed in informa-
          tion displays. If no is  specified,  numeric  addresses
          are  printed  instead. The default is yes, unless modi-
          fied 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 subse-
          quent addpeer/addserver/broadcast
           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.

          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

SunOS 5.11                Last change:                          3

System Administration Commands                          ntpdc(1M)

          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 time-
          out, 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  candi-

          Obtains  a  list of peers for which the server is main-
          taining state, along with a summary of that state. Sum-
          mary  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 seconds,
          the reachability register, in octal,  and  the  current
          estimated 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 - indicates symmetric passive, a  =
          means the remote server is being polled in client mode,
          a ^ indicates that the server is broadcasting  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 reference clock implementation name
          with its  parameter  or  REFCLK(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 charac-
          ter in the  leftmost  column.  Characters  only  appear
          beside  peers which were included in the final stage of

SunOS 5.11                Last change:                          4

System Administration Commands                          ntpdc(1M)

          the clock selection algorithm. A . indicates 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 peer(s).

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

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

     loopinfo [ oneline | multiline ]
          Print the values of selected loop filter variables. The
          loop filter is the part of NTP which deals with adjust-
          ing the local system clock. The offset is the last off-
          set given to the loop filter by the  packet  processing
          code. The frequency is the frequency error of the local
          clock in parts-per-million (ppm). The  time_const  con-
          trols 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  indi-
          cate the synchronization status when the precision time

SunOS 5.11                Last change:                          5

System Administration Commands                          ntpdc(1M)

          kernel modifications are in use. The  kernel_pll  indi-
          cates  that the local clock is being disciplined by the
          kernel, while the kernel_pps indicates the kernel  dis-
          cipline  is  provided by the PPS signal.  The stability
          is the residual frequency  error  remaining  after  the
          system  frequency 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 dae-
          mon, something may be wrong with the  local  clock,  or
          the value of the kernel variable tick may be incorrect.
          The broadcastdelay shows the default  broadcast  delay,
          as  set  by  the  broadcastdelay configuration command.
          The authdelay shows the default  authentication  delay,
          as set by the authdelay configuration command.

          Print  statistics  counters  maintained in the protocol

          Print statistics counters  maintained  in  the  control

          Print  statistics counters related to memory allocation

          Print statistics counters maintained in the  input-out-
          put 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 network communication.

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

SunOS 5.11                Last change:                          6

System Administration Commands                          ntpdc(1M)

     monlist [ version ]
          Obtain and print traffic  counts  collected  and  main-
          tained  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 disabled by the server by not configur-
     ing 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

     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 configuration 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 recon-
     figuration facility should  provide  an  adequate  level  of

     The following commands all make authenticated requests.

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

SunOS 5.11                Last change:                          7

System Administration Commands                          ntpdc(1M)

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

          Add a configured peer association at the given  address
          and  operating  in  symmetric active mode. Note that an
          existing association with the same peer may be  deleted
          when  this  command  is executed, or may simply be con-
          verted to conform to the new configuration,  as  appro-
          priate.  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 lit-
          erals  prefer, iburst, burst, minpoll  N, keyid N, ver-
          sion  N, or maxpoll  N (where N is  a  numeric  value),
          and have the action as specified in the peer configura-
          tion file command of ntpd.   See  the   server  options
          page    at  file:///usr/share/doc/ntp/confopt.html  for
          further  information.   Each  flag  (or  its   absence)
          replaces the previous setting. The prefer keyword indi-
          cates a preferred peer (and thus will be used primarily
          for  clock  synchronisation if possible). The preferred
          peer also determines the validity of the PPS  signal  -
          if  the  preferred peer is suitable for synchronisation
          so is the PPS signal.  The dynamic keyword allows asso-
          ciation  configuration  even  when  no suitable network
          interface is found at configuration time.  The  dynamic
          interface  update mechanism may complete the configura-
          tion when new interfaces appear (e.g.  WLAN/PPP  inter-
          faces)  at a later time and thus render the association

     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 oper-
          ating mode is client.

     addrefclock clock_address [  mode [ prefer | burst | minpoll
          | 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.

SunOS 5.11                Last change:                          8

System Administration Commands                          ntpdc(1M)

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

     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 association to be deleted.  When  appro-
          priate,  however,  the  association  may  persist in an
          unconfigured mode if the remote peer is willing to con-
          tinue 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

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

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

     restrict address mask flag [ flag ]
          This  command  operates in the same way as the restrict
          configuration 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 [...]

SunOS 5.11                Last change:                          9

System Administration Commands                          ntpdc(1M)

     untrustedkey keyid [...]

     controlkey keyid [...]

     requestkey keyid [...]
          These commands operate in the same way  as  the  corre-
          sponding configuration 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  mod-
          ule, including known keys and counts of encryptions and
          decryptions which have been done.

          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.

          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 configura-
     tion 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 letters.  For example, to set the --com-
     mand option, you would  set  the  NTPDC_COMMAND  environment
     variable.   The  users home directory and the current direc-
     tory are searched for a file named .ntprc.

     See  attributes(5)  for  descriptions   of   the   following

SunOS 5.11                Last change:                         10

System Administration Commands                          ntpdc(1M)

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

     This   software   was   built   from   source  available  at   The   original
     community    source    was   downloaded   from    http://ar-

     Further information about this software can be found on  the
     open source community website at

SunOS 5.11                Last change:                         11