man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2014

ntpq (1m)


ntpq - Network Time Protocol query program


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


SunOS 5.11                                                      1

System Administration Commands                           ntpq(1M)

     ntpq - Network Time Protocol query program

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

     The  ntpq utility program is used to monitor NTP daemon ntpd
     operations and determine performance. It uses  the  standard
     NTP  mode 6 control message formats defined in Appendix B of
     the NTPv3 specification RFC1305. The same formats  are  used
     in  NTPv4,  although  some of the variables have changed and
     new ones added. The description on  this  page  is  for  the
     NTPv4 variables.

     The  program  can  be run either in interactive mode or con-
     trolled using command line arguments. Requests to  read  and
     write  arbitrary  variables  can  be assembled, with raw and
     pretty-printed output  options  being  available.  The  ntpq
     utility  can also obtain and print a list of peers in a com-
     mon format by sending multiple queries to the server.

     If one or more request options are included on  the  command
     line  when  ntpq  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 the localhost by default.
     If no request options are given, ntpq 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. ntpq will prompt for  commands  if  the  standard
     input is a terminal device.

     The ntpq utility uses NTP mode 6 packets to communicate with
     the NTP server, and hence can be used to query any  compati-
     ble  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 net-
     work  topology.  The  ntpq  program  makes  one  attempt  to
     retransmit  requests,  and  will  time  requests  out if the
     remote host is not heard  from  within  a  suitable  timeout

     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. On the command line, only  one  of  the  two
     can be given.

     For  examples  of usage of ntpq, see the NTP Debugging Tech-
     niques page at file:///usr/share/doc/ntp/debug.html.

SunOS 5.11                Last change:                          1

System Administration Commands                           ntpq(1M)

     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, ntpq will attempt  to
     read interactive format commands from the standard input.

     -4, --ipv4
          Force  DNS  resolution  of  following host names on the
          command line to the IPv4 namespace. Cannot be used with
          the --ipv6 option.

     -6, --ipv6
          Force  DNS  resolution  of  following host names on the
          command line to the IPv6 namespace. Cannot be used with
          the --ipv4 option.

     -c cmd, --command=cmd
          The following argument is interpreted as an interactive
          format command and is added to the list of commands  to
          be  executed on the specified host(s).  This option may
          appear an unlimited number of  times.  After  all  such
          commands  are  executed  against  all listed hosts, the
          program exits.

     -d, --debug-level
          Increase output debug message level.  This  option  may
          appear an unlimited number of times.

     -D number, --set-debug-level=string
          Set  the  output  debug message level.  This option may
          appear an unlimited number of times, but only the  last
          one will be used.

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

     -i, --interactive
          Force  ntpq  to  operate  in interactive mode.  Prompts
          will be written to the  standard  output  and  commands
          read  from  the  standard  input.  This option must not
          appear in combination  with  either  the  --command  or
          --peers options.

     -n, --numeric
          Output all host addresses in numeric format rather than
          converting to the host names.

     -?, --help
          Display usage information and exit.

SunOS 5.11                Last change:                          2

System Administration Commands                           ntpq(1M)

     -!, --more-help
          Extended usage information passed thru a pager.

     -> rcfile, --save-opts=rcfile
          Save the option state to rcfile.

     -< rcfile, --load-opts=rcfile, --no-load-opts
          Load options from rcfile.  The no-load-opts  form  will
          disable  the  loading  of  earlier RC/INI files.  --no-
          load-opts is handled early, out of order.

     -v, --version
          Output version of program and exit.

     Most options may be preset by loading values from configura-
     tion file(s) and values from environment variables named:
       NTPQ_<option-name> or NTPQ
     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  NTPQ_COMMAND  environment
     variable.   The  users home directory and the current direc-
     tory are searched for a file named .ntprc.

     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.

  Internal Commands
     A number  of  interactive  commands  are  executed  entirely
     within the ntpq utility itself and do not result in requests
     being sent to a server. These commands are as follows:



SunOS 5.11                Last change:                          3

System Administration Commands                           ntpq(1M)

     ? [command_keyword],  help [command_keyword]
          Prints a list of all  the  command  keywords  known  to
          ntpq. Followed by a command keyword will print function
          and usage information about the command.

     addvars variable_name[=value]  ...

     rmvars variable_name ...


          The data carried by NTP mode 6 messages consists  of  a
          list  of  items  of  the  form  variable_name=value. In
          requests to read variable, the =value is  ignored,  and
          can be omitted.  The ntpq utility maintains an internal
          list in which data to be included in  control  messages
          can  be  assembled,  and  sent  using  the readlist and
          writelist commands described below.  The  addvars  com-
          mand  allows  variables and their optional values to be
          added to the list.  If more than one variable is to  be
          added,  the list should be comma-separated and not con-
          tain white space. The showvars command lists  the  cur-
          rent  variable list.  The rmvars command can be used to
          remove individual variables from the  list,  while  the
          clearlist  command removes all variables from the list.

     authenticate [ yes | no ]
          Normally ntpq only  sends  authentication  with   write
          requests.   The command authenticate yes causes ntpq to
          send authentication with all requests  it  makes.   The
          command  authenticate  with  no  keyword causes ntpq to
          display whether or not ntpq is currently authenticating

     :config config_command
          Sends  the entire line after :config to the ntpd daemon
          to be interpreted as a configuration file command. Mul-
          tiple commands may be separated by semi-colons.

     config-from-file config_file
          Sends the entire file config_file to the ntpd daemon to
          be interpreted as configuration file commands.

          Causes output from query commands to  be  "cooked",  so
          that  variables  which are recognized by ntpq will have
          their values reformatted for human consumption.   Vari-
          ables  which  ntpq thinks should have a decodable value
          but didn't are marked with a trailing ?.

     debug [ more | less | off ]

SunOS 5.11                Last change:                          4

System Administration Commands                           ntpq(1M)

          With no argument, displays  the  current  debug  level.
          Otherwise,  the debug level is changed by the indicated

     delay milliseconds
          Specify a time  interval  to  be  added  to  timestamps
          included  in  requests  which  require  authentication.
          This is used to enable (unreliable) server reconfigura-
          tion  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 [ [ -4 | -6 ] hostname ]
          Set the host to which future queries will be sent.  The
          hostname  may  be  either  a  host  name  or  a numeric
          address. With no argument, prints the current host.

     hostnames [ yes | no ]
          If yes is specified, host names are printed in informa-
          tion  displays.   If no is specified, numeric addresses
          are printed instead. With no argument, prints the  cur-
          rent  setting.   The  default  is  yes, unless modified
          using the command line -n switch.

     keyid [ keyid# ]
          This command specifies the key number  to  be  used  to
          authenticate  configuration requests.  This must corre-
          spond to a key number the server has been configured to
          use for this purpose.

     keytype [ md5 ]
          Prints or sets the type of key used for authentication.
          Currently only md5 is accepted.

     ntpversion [ 1 | 2 | 3 | 4 ]
          Sets the NTP version number which ntpq claims in  pack-
          ets.   Defaults to 2. Note that mode 6 control messages
          didn't exist in NTP version 1.  Luckily there appear to
          be  no  servers  left  which demand version 1.  With no
          argument, displays the current NTP version that will be
          used when communicating with servers.

          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.

     quit Exit ntpq .

SunOS 5.11                Last change:                          5

System Administration Commands                           ntpq(1M)

     raw  Causes  all  output  from  query commands is printed as
          received from the  remote  server.   The  only  format-
          ing/interpretation  done  on  the  data is to transform
          nonascii data into a printable (but barely  understand-
          able) form.

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

  Control Message Commands
     Each association known to an NTP server has a 16 bit integer
     association identifier. NTP  control  messages  which  carry
     peer  variables must identify the peer the values correspond
     to by including its association ID. An association ID  of  0
     is  special,  and  indicates  the variables are system vari-
     ables, whose names are drawn from a separate name space.

     Control message commands result in one or more  NTP  mode  6
     messages  being  sent  to  the  server,  and  cause the data
     returned to be printed in some format.  Most  commands  cur-
     rently implemented send a single message and expect a single
     response. The current  exceptions  are  the  peers  command,
     which will send a preprogrammed series of messages to obtain
     the data it needs, and the mreadlist and mreadvar  commands,
     which will iterate over a range of associations.

          Obtains  and  prints  a list of association identifiers
          and peer statuses for in-spec peers of the server being
          queried.  The  list is printed in columns. The first of
          these is an index numbering the associations from 1 for
          internal use, the second the actual association identi-
          fier returned by the server and the  third  the  status
          word for the peer. This is followed by a number of col-
          umns containing data decoded from the status word.  See
          the  peers command for a decode of the condition field.
          The data returned by the associations command is cached
          internally  in  ntpq  and  used in subsequent commands.
          After the first associations command the index  can  be
          used  in place of the association identifier by specif-
          ing the identifier in the form &index.

     clocklist [assocID]

     cl  [assocID]
          Read the values of the clock variables included in  the
          variable list

SunOS 5.11                Last change:                          6

System Administration Commands                           ntpq(1M)

     clockvar [assocID] [variable_name [ = value [...]] [...]

     cv [assocID] [variable_name [ = value [...] ][...]
          Requests that a list of the server's clock variables be
          sent. Servers which have a radio clock or other  exter-
          nal synchronization will respond positively to this. If
          the association  identifier  is  omitted  or  zero  the
          request  is  for  the variables of the system clock and
          will generally get a positive response from all servers
          with  a  clock.  If the server treats clocks as pseudo-
          peers, and hence can possibly have more than one  clock
          connected  at  once,  referencing  the appropriate peer
          association ID will show the variables of a  particular
          clock. Omitting the variable list will cause the server
          to return a default variable display.

          Obtains and prints a list  of  association  identifiers
          and  peer  statuses  for all associations for which the
          server is maintaining state. This command differs  from
          the  associations command only for servers which retain
          state  for  out-of-spec  client   associations   (i.e.,
          fuzzballs). Such associations are normally omitted from
          the display when the associations command is used,  but
          are  included in the output of lassociations. When used
          with the ntpd in this  distribution,  this  command  is
          idenitical to associations.

          Print  data for all associations, including out-of-spec
          client associations, from the internally cached list of

          Same as opeers but from the internally cached data.

          Like  peers,  except  a summary of all associations for
          which the server is maintaining state is printed.  This
          can  produce  a much longer list of peers from fuzzball
          servers, but for most servers this  is  identical  with

     mreadlist assocID assocID

     mrl assocID assocID
          Like the readlist command, except the query is done for
          each of a range  of  (nonzero)  association  IDs.  This
          range is determined from the association list cached by
          the most recent associations command. An  assocIDs  may
          be  either  an  association  identify or the equivilant
          &index form.

SunOS 5.11                Last change:                          7

System Administration Commands                           ntpq(1M)

     mreadvar assocID assocID [ variable_name [ = value[ ... ]

     mrv assocID assocID [ variable_name [ = value[ ... ]
          Like the readvar command, except the query is done  for
          each  of  a  range  of  (nonzero) association IDs. This
          range is determined from the association list cached by
          the most recent associations command.

          An  old form of the peers command with the reference ID
          replaced by the local interface address.

          Displays association data concerning in-spec peers from
          the  internally  cached list of associations. This com-
          mand performs identically to  the  associations  except
          that it displays the internally stored data rather than
          making a new query.

          Obtains a current list peers of the server, along  with
          a  summary  of  each  peer's state. Summary information
          includes the address of the remote peer, the  reference
          ID  (  if  this  is unknown), the stratum of the
          remote peer, the type of the peer (local, unicast, mul-
          ticast   or   broadcast),  when  the  last  packet  was
          received, the polling interval, in seconds, the reacha-
          bility  register,  in  octal, and the current estimated
          delay, offset and dispersion of the peer, all  in  mil-
          liseconds.  The  character  at  the left margin of each
          line shows the synchronization status of  the  associa-
          tion  and  is  a valuable diagnostic tool. The encoding
          and meaning of this character, called the  tally  code,
          is given later in this page.

     pstatus assocID
          Sends a read status request to the server for the given
          association. The names and values of the peer variables
          returned  will  be  printed.  Note that the status word
          from the header is displayed preceding  the  variables,
          both in hexadecimal and in pidgeon English.

     readlist [ assocID ]

     rl [ assocID ]
          Requests that the values of the variables in the inter-
          nal variable list be returned by  the  server.  If  the
          association  ID  is  omitted  or is 0 the variables are
          assumed to be  system  variables.  Otherwise  they  are
          treated  as  peer  variables.  If the internal variable
          list is empty a request is  sent  without  data,  which
          should  induce  the  remote  server to return a default

SunOS 5.11                Last change:                          8

System Administration Commands                           ntpq(1M)


     readvar assocID variable_name [ = value ] [ ...]

     rv assocID [ variable_name [ = value ] [...]
          Requests that the values of the specified variables  be
          returned  by  the  server  by  sending a read variables
          request. If the association ID is omitted or  is  given
          as  zero  the variables are system variables, otherwise
          they are peer variables and the values returned will be
          those  of the corresponding peer. Omitting the variable
          list will send a request  with  no  data  which  should
          induce  the  server  to  return  a default display. The
          encoding and meaning  of  the  variables  derived  from
          NTPv3 is given in RFC-1305; the encoding and meaning of
          the additional NTPv4 variables are given later in  this

     writevar assocID variable_name [ = value [ ...]
          Like  the  readvar  request, except the specified vari-
          ables are written instead of read.

     writelist [ assocID ]
          Like the readlist request,  except  the  internal  list
          variables are written instead of read.

  Tally Codes
     The  character  in  the  left margin in the peers billboard,
     called the tally code, shows the fate of each association in
     the  clock  selection  process. Following is a list of these
     characters, the pidgeon used in the rv command, and a  short
     explanation of the condition revealed.

     space reject
          The  peer  is discarded as unreachable, synchronized to
          this server (synch loop) or outrageous  synchronization

     x falseticker
          The  peer is discarded by the intersection algorithm as
          a falseticker.

     . excess
          The peer is discarded as not among the first ten  peers
          sorted by synchronization distance and so is probably a
          poor candidate for further consideration.

     - outlyer
          The peer is discarded by the clustering algorithm as an

     + candidate

SunOS 5.11                Last change:                          9

System Administration Commands                           ntpq(1M)

          The  peer is a survivor and a candidate for the combin-
          ing algorithm.

     # selected
          The peer is a survivor, but not  among  the  first  six
          peers  sorted by synchronization distance. If the asso-
          ciation is ephemeral, it may be demobilized to conserve

     * sys.peer
          The  peer  has  been declared the system peer and lends
          its variables to the system variables.

     o pps.peer
          The peer has been declared the system  peer  and  lends
          its  variables  to  thesystem  variables.  However, the
          actual system synchronization is derived from a  pulse-
          per-second  (PPS) signal, either indirectly via the PPS
          reference clock driver or directly  via  kernel  inter-

  System Variables
     The status, leap, stratum, precision, rootdelay, rootdisper-
     sion, refid, reftime, poll, offset, and frequency  variables
     are  described  in  RFC-1305 specification. Additional NTPv4
     system variables include the following:

          Everything you might need to know  about  the  software
          version and generation time.

          The processor and kernel identification string.

          The operating system version and release identifier.

          The  state  of  the clock discipline state machine. The
          values are described in the  architecture  briefing  on
          the NTP Project page linked from

     peer The  internal  integer used to identify the association
          currently designated the system peer.

          The estimated time error of the system  clock  measured
          as an exponential average of RMS time differences.

          The  estimated  frequency stability of the system clock
          measured as an exponential  average  of  RMS  frequency

SunOS 5.11                Last change:                         10

System Administration Commands                           ntpq(1M)


     In  addition,  some or all of the following system variables
     related to the crypto authentication are displayed,  depend-
     ing on the state of the particular crypto dance in use:

          The  name  of the host as returned by the Unix gethost-
          name() library function.

          The NTP filestamp of the host key file.

          The current flags word bits and  message  digest  algo-
          rithm identifier (NID) in hex format. The high order 16
          bits of the four-byte word contain  the  NID  from  the
          OpenSSL  ligrary,  while  the low-order bits are inter-
          preted as follows: 0x01: autokey  enabled,  0x02:  NIST
          leapseconds  file  loaded,  0x10:  PC  identity scheme,
          0x20: IFF identity scheme, 0x40: GQ identity scheme.

     cert A list of certificates held by  the  host.  Each  entry
          includes  the  subject, issuer, flags and NTP filestamp
          in order. The bits are interpreted  as  follows:  0x01:
          signed  by  the  server,  0x02: trusted, 0x04: private,
          0x08: contains errors and is not trusted.

          The NTP filestamp of the NIST leapseconds file.

          The NTP timestamp when the  host  public  cryptographic
          values were refreshed and signed.

          The  host digest/signature scheme name from the OpenSSL

     tai  The TAI-UTC offset in seconds obtained  from  the  NIST
          leapseconds table.

  Peer Variables
     The status, srcadr, srcport, dstadr, dstport, leap, stratum,
     precision, rootdelay, rootdispersion, readh,  hmode,  pmode,
     hpoll,  ppoll,  offset,  delay, dspersion, reftime variables
     are described in the  RFC-1305  specification,  as  are  the
     timestamps  org,  rec and xmt. Additional NTPv4 system vari-
     ables include the following.

          The flash code for the most recent packet received. The

SunOS 5.11                Last change:                         11

System Administration Commands                           ntpq(1M)

          encoding  and  meaning of these codes is given later in
          this page.

          The estimated time error of the peer clock measured  as
          an exponential average of RMS time differences.

          The  value  of  the counter which records the number of
          poll  intervals  since  the  last  valid   packet   was

     In  addition,  some  or all of the following  peer variables
     are displayed related to the crypto auithentication:

          The current flag bits. This word  is  the  server  host
          status  word  with  additional bits used by the Autokey
          state machine. See the source code for the  bit  encod-

          The server host name.

     initkey key
          The  initial  key used by the key list generator in the
          Autokey protocol.

     initsequence index
          The initial index used by the key list generator in the
          Autokey protocol.

          The  server  message  digest/signature scheme name from
          the OpenSSL software library.

     timestamp time
          The NTP timestamp when the last Autokey  key  list  was
          generated and signed.

  Flash Codes
     The  flash code is a valuable debugging aid displayed in the
     peer variables list. It shows the results  of  the  original
     sanity  checks defined in the NTP specification RFC-1305 and
     additional ones added in NTPv4. There are  12  tests  desig-
     nated  TEST1  through  TEST12.  The tests are performed in a
     certain order designed to gain maximum  diagnostic  informa-
     tion   while  protecting  against  accidental  or  malicious
     errors. The flash variable is initialized to  zero  as  each
     packet  is  received. If after each set of tests one or more
     bits are set, the packet is discarded.

SunOS 5.11                Last change:                         12

System Administration Commands                           ntpq(1M)

     Tests TEST1 through TEST3 check the packet  timestamps  from
     which  the  offset and delay are calculated. If any bits are
     set, the packet is discarded; otherwise, the  packet  header
     variables  are  saved.  TEST4  and TEST5 are associated with
     access control and cryptographic authentication. If any bits
     are  set,  the  packet is discarded immediately with nothing

     Tests TEST6 through TEST8 check the health of the server. If
     any  bits  are  set, the packet is discarded; otherwise, the
     offset and delay relative to the server are  calculated  and
     saved. TEST9 checks the health of the association itself. If
     any bits are set, the packet is  discarded;  otherwise,  the
     saved  variables  are passed to the clock filter and mitiga-
     tion algorithms.

     Tests TEST10 through TEST12 check the  authentication  state
     using  Autokey  public-key cryptography, as described in the
     Authentication           Options           page           at
     file:///usr/share/doc/ntp/authopt.html.  If any bits are set
     and the association has previously  been  marked  reachable,
     the  packet  is  discarded;  otherwise,  the  originate  and
     receive timestamps are saved, as required by the NTP  proto-
     col, and processing continues.

     The flash bits for each test are defined as follows.

     0x001 TEST1
          Duplicate  packet.  The  packet  is  at  best  a casual
          retransmission and at worst a malicious replay.

     0x002 TEST2
          Bogus packet. The packet is not a reply  to  a  message
          previously sent. This can happen when the NTP daemon is
          restarted and before somebody else notices.

     0x004 TEST3
          Unsynchronized.  One  or  more  timestamp  fields   are
          invalid.  This  normally  happens when the first packet
          from a peer is received.

     0x008 TEST4
          Access is denied. See the Access Control  Options  page
          at file:///usr/share/doc/ntp/accopt.html.

     0x010 TEST5
          Cryptographic authentication fails. See the Authentica-
          tion Options page referenced above.

          The server is unsynchronized. Wind up its clock  first.

SunOS 5.11                Last change:                         13

System Administration Commands                           ntpq(1M)

     0x040 TEST7
          The server stratum is at the maximum of 15. It is prob-
          ably unsynchronized and its clock needs to be wound up.

     0x080 TEST8
          Either the root delay or dispersion is greater than one
          second, which is highly unlikely  unless  the  peer  is
          unsynchronized to Mars.

     0x100 TEST9
          Either the peer delay or dispersion is greater than one
          second, which is higly unlikely unless the peer  is  on

     0x200 TEST10
          The  autokey  protocol  has  detected an authentication
          failure. See the Authentication Options page.

     0x400 TEST11
          The autokey protocol has not  verified  the  server  or
          peer is proventic and has valid public key credentials.
          See the Authentication Options page.

     0x800 TEST12
          A protocol or configuration error has occurred  in  the
          public key algorithms or a possible intrusion event has
          been detected. See the Authentication Options page.

     See  attributes(5)  for  descriptions   of   the   following

     |Availability   | service/network/ntp |
     |Stability      | Uncommitted         |
     The  documentation  available  at /usr/share/doc/ntp is pro-
     vided as is from the NTP distribution and may contain infor-
     mation that is not applicable to the software as provided in
     this partIcular distribution.

     The output of the ntpqP in version 4 differs  from  that  in
     version  3  by  the replacement of the dispersion value with
     the jitter value in the peers output.


SunOS 5.11                Last change:                         14

System Administration Commands                           ntpq(1M)

     ntpd(1M), ntpdc(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:                         15