Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

ntpq


NAME
     ntpq - standard Network Time Protocol query program

SYNOPSIS
     /usr/sbin/ntpq [-inp] [-c command] [host] [...]

DESCRIPTION
     ntpq queries NTP servers which implement the recommended NTP
     mode  6  control message format, about current state. It can
     also request changes in that state. The program can  be  run
     in  interactive  mode; or it can be controlled using command
     line arguments. Requests to read and write  arbitrary  vari-
     ables  can  be assembled, with raw and pretty-printed output
     options  available.  By  sending  multiple  queries  to  the
     server,  ntpq can also obtain and print a list of peers in a
     common format.

     If one or more request options are included on  the  command
     line, ntpq sends each of the requests to NTP servers running
     on each of the hosts given as  command  line  arguments.  By
     default,  ntpq sends its requests to localhost, if hosts are
     not included on the command line. If no request options  are
     given,  ntpq  attempts  to  read  commands from the standard
     input and execute them on the  NTP  server  running  on  the
     first  host  given on the command line. Again, ntpq defaults
     to localhost if no other host is specified.

     ntpq uses NTP mode 6 packets  to  communicate  with  an  NTP
     server.  Thus, it can be used to query any compatible server
     on the network that permits queries. Since NTP is a UDP pro-
     tocol, this communication will be somewhat unreliable, espe-
     cially over large  distances.  ntpq  makes  one  attempt  to
     retransmit  requests; requests timeout if the remote host is
     not heard from within a suitable period.

OPTIONS
     Command line options are described below. Specifying a  com-
     mand  line  option  other than -i or -n causes the specified
     query (queries) to be sent,  immediately  to  the  indicated
     host(s). Otherwise, ntpq attempts to read interactive format
     commands from standard input.

     -c       Interpret the next argument as an interactive  for-
              mat  command  and add it to the list of commands to
              be executed on the specified host(s).  Multiple  -c
              options may be given.



     -i       Operate in interactive mode; write prompts to stan-
              dard output and read commands from standard input.

     -n       Output all host addresses  in  dotted-quad  numeric
              format  rather  than  converting  them to 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 the peers  interactive  command.  See
              USAGE below.




USAGE
     Interactive format commands consist of a keyword followed by
     up  to  four  arguments.  Only enough characters of the full
     keyword to uniquely identify the command need be typed. Nor-
     mally,  the  output of a command is sent to standard output;
     but this output may be written to a file by appending a `>',
     followed by a file name, to the command line.

  Interactive Commands
     A  number  of  interactive  format  commands  are   executed
     entirely  within the ntpq program itself. They do not result
     in NTP mode 6 requests being sent to a server. If no request
     options  are  included on the command line, and if the stan-
     dard input is a terminal device, ntpq prompts for these com-
     mands. The interactive commands are described below:

     ? [command_keyword]

         A `?' by itself prints a list of all  the  command  key-
         words  known to the current version of ntpq.  A `?' fol-
         lowed by a command keyword  prints  function  and  usage
         information about the command.



     timeoutmilliseconds

         Specifies a time out  period  for  responses  to  server
         queries.   The default is about 5000 milliseconds. Since
         ntpq retries each query once after a time out, the total
         waiting  time for a time out is twice the time out value
         that is set.



     delaymilliseconds

         Specifies a time interval  to  be  added  to  timestamps
         included  in requests which require authentication. This
         command is used to enable (unreliable)  server  reconfi-
         guration  over  long  delay  network  paths  or  between
         machines whose clocks are unsynchronized. Currently, the
         server  does  not  require  time stamps in authenticated
         requests. Thus, this command may be obsolete.



     hosthostname

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



     keyid #

         Specify of a key number to be used to authenticate  con-
         figuration  requests.  This  number must correspond to a
         key number the server has been  configured  to  use  for
         this purpose.



     passwd

         Allow the user to specify  a  password  at  the  command
         line.  This  will  be used to authenticate configuration
         requests. If an authenticating key  has  been  specified
         (see keyid above), this password must correspond to this
         key. ntpq does not echo the password as it is typed.



     hostnames yes|no

         If "yes" is specified, host names are printed in  infor-
         mation displays. If "no" is given, numeric addresses are
         printed instead. The default is  "yes"  unless  modified
         using the command line -n switch.



     raw

         Print all output from query commands exactly  as  it  is
         received    from    the   remote   server.    The   only
         formatting/filtering done on the data  is  to  transform
         non- ASCII data into printable form.

     cooked

         Causes output from query commands to  be  "cooked".  The
         values  of variables recognized by the server are refor-
         matted, so that they can be more easily read.  Variables
         which  ntpq thinks should have a decodable value, but do
         not, are marked with a trailing `?'.



     ntpversion[ 1|2|3 ]

         Sets the NTP version number which ntpq claims in packets
         (defaults  is 3). Note that mode 6 control messages (and
         modes, for that matter) did not exist in NTP version  1.
         There  appear to be no servers left which demand version
         1.



     authenticate[ yes|no ]

         The command authenticate  yes  instructs  ntpq  to  send
         authentication with all requests it makes. Normally ntpq
         does not authenticate requests  unless  they  are  write
         requests.  Authenticated  requests cause some servers to
         handle requests slightly differently, and can  occasion-
         ally  cause a slowed response if you turn authentication
         on   before    doing    a    peer    display.    addvars
         variable_name[=value]  [  ,...  ] rmvars variable_name [
         ,... ] clearvars

         The data carried by NTP mode 6 messages  consists  of  a
         list of items of the form


         variable_name=value


         where the "=value" is ignored, and can  be  omitted,  in
         requests to the server to read variables. ntpq maintains
         an internal list in which data to be included in control
         messages  can  be  assembled,  and  sent. This is accom-
         plished  with  the  readlist  and   writelist   commands
         described  below.   The addvars command 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  it  should  not  contain  white
         space.  The rmvars command can be used to remove indivi-
         dual variables from  the  list;  the  clearlist  command
         removes all variables from the list.

     debug[ more|less|off ]

         Turns internal query program debugging on and off.



     quit

         Exit ntpq.




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

     Control message commands send one or more NTP  mode  6  mes-
     sages  to  the  server,  and  cause  the data returned to be
     printed in some format. Most commands currently  implemented
     send  a  single  message  and  expect a single response. The
     current exceptions are the peers mreadlist and mreadvar com-
     mands.  The  peers  command  sends a preprogrammed series of
     messages to obtain the data  it  needs.  The  mreadlist  and
     mreadvar commands, iterate over a range of associations.

     Control message commands are described below:

     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 that numbers the associations from 1,
         for internal use. The second column contains the  actual
         association  identifier  returned  by the server and the
         third the status word for the peer. This is followed  by
         a  number  of  columns  containing data decoded from the
         status word. Note that the data returned by the associa-
         tions command is cached internally in ntpq. The index is
         then of use when dealing with "dumb" servers  which  use
         association  identifiers  that  are  hard  for humans to
         type. For any subsequent commands which require an asso-
         ciation identifier as an argument, the identifier can be
         specified by using the form, &index. Here index is taken
         from the previous list.

     lassociations

         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.  Such  associations
         are  normally omitted from the display when the associa-
         tions command is used, but are included in the output of
         lassociations.



     passociations

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



     lpassociations

         Print data for all associations,  including  out-of-spec
         client  associations, from the internally cached list of
         associations. This command differs from
          passociations only  when  dealing  with  servers  which
         retain
          state for out-of-spec client associations.



     pstatusassocID

         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 pigeon English.



     readvar [ assoc] [ 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.



     rv [ assocID] [ variable_name[=value][ ,... ]]

         An easy-to-type short form for the readvar command.



     writevar assocID variable_name=value [ ,... ]

         Like the readvar request, except the specified variables
         are written instead of read.



     readlist [ 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 display.



     rl [ assocID]

         An easy-to-type short form of the readlist command.



     writelist [ assocID]

         Like the readlist  request,  except  the  internal  list
         variables are written instead of read.



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



     mrv assocID assocID [ variable_name[=value] [ ,... ]]

         An easy-to-type short form of the mreadvar command.



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



     mrlassocID assocID

         An easy-to-type short form of the mreadlist command.



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

         Requests that a list of the server's clock variables  be
         sent. Servers which have a radio clock or other external
         synchronization respond positively to this. If the asso-
         ciation identifier is omitted or zero the request is for
         the variables of the "system clock". This  request  gen-
         erally  gets a positive response from all servers with a
         clock. Some servers may  treat  clocks  as  pseudo-peers
         and,  hence,  can possibly have more than one clock con-
         nected at  once.  For  these  servers,  referencing  the
         appropriate peer association ID shows the variables of a
         particular clock. Omitting the variable list causes  the
         server to return a default variable display.



     cv [ assocID] [ variable_name[=value][ ,... ]]

         An easy-to-type short form of the clockvar command.



     peers

         Obtains a list of in-spec peers  of  the  server,  along
         with a summary of each peer's state. Summary information
         includes:


           o
              The address of the remote peer

           o  The reference ID (0.0.0.0 if the ref ID is unknown)

           o  The stratum of the remote peer

           o  The type of the peer (local, unicast, multicast  or
              broadcast) when the last packet was received

           o  The polling interval in seconds

           o  The reachability register, in octal

           o  The current estimated delay offset  and  dispersion
              of the peer, all in milliseconds.

         The character in the left margin indicates the  fate  of
         this  peer  in  the  clock  selection process. The codes
         mean:


         SPACE           Discarded due  to  high  stratum  and/or
                         failed sanity checks.




         x               Designated falsticker by  the  intersec-
                         tion algorithm.



         .               Culled from the  end  of  the  candidate
                         list.



         -               Discarded by the clustering algorithm.



         +               Included in the final selection set.



         #               Selected for synchronization;  but  dis-
                         tance exceeds maximum.



         *               Selected for synchronization.

         o               Selected for synchronization, pps signal
                         in use.



         Since the peers command depends on the ability to  parse
         the values in the responses it gets, it may fail to work
         from time to time with servers which poorly control  the
         data formats.

         The contents of the host field may be given  in  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).  On "host-
         names no" only IP-addresses will be displayed.


     lpeers

         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  inadequate
         servers.



     opeers

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




ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWntpu                    |
    |_____________________________|_____________________________|


SEE ALSO
     attributes(5)

BUGS
     The peers command is non-atomic. It may occasionally  result
     in spurious error messages about invalid associations occur-
     ring and terminating the command.
     The timeout value is a fixed constant. As a result, it often
     waits  a long time to timeout, since the fixed value assumes
     sort of a worst case.  The program should improve  the  time
     out  estimate  as it sends queries to a particular host; but
     it does not.










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments