*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> ntpq (8)              



NAME    [Toc]    [Back]

       ntpq  -  Network  Time  Protocol (NTP) monitor program for

SYNOPSIS    [Toc]    [Back]

       /usr/bin/ntpq [-inp] [-c command] [host1 host2...]

OPTIONS    [Toc]    [Back]

       Forces ntpq to operate in interactive mode.   Prompts  are
       written  to the standard output and commands read from the
       standard input. This is the  default.   Outputs  all  host
       addresses  in dotted-decimal notation rather than converting
 to the canonical host names.  Prints  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.
  Interprets command as an interactive format command
       and adds it to the list of commands to be executed on  the
       specified host(s).  Multiple -c options may be given.

       Specifying  the -c or -p options sends the specified query
       (queries) to the indicated  host(s) immediately; localhost
       is the default.  Otherwise, ntpq attempts to read interactive
 format commands from the standard input.

DESCRIPTION    [Toc]    [Back]

       The ntpq program is used  to  monitor  NTP  hosts  running
       xntpd.  The  program may be run either in interactive mode
       or controlled using command line arguments.   Requests  to
       read  arbitrary  variables  can be assembled, with raw and
       formatted output options available. The ntpq  program  can
       also  obtain  and print a list of peers in a common format
       by sending multiple queries to the server.

       If one or more request options is included on the  command
       line  when  ntpq is executed, each of the requests will be
       sent to the xntpd daemons running on  each  of  the  hosts
       given  as  command  line  arguments,  or  on  localhost by
       default.  If no request options are given,  ntpq  attempts
       to read commands from the standard input and execute these
       on the first host given on the command line, defaulting to
       localhost  when  no other host is specified. The ntpq program
 will prompt for commands if the standard input  is  a
       terminal device.

       The  ntpq  program  uses NTP mode 6 packets to communicate
       with the xntpd daemons, and therefore can be used to query
       any  compatible  daemon  on  the  network that permits it.
       Note: Since NTP uses the UDP protocol, this  communication
       will be somewhat unreliable, especially over large network
       topologies. The ntpq program makes one attempt to retransmit
  requests, and will time out if the remote host is not
       heard from within a suitable time.

COMMANDS    [Toc]    [Back]

   Interactive Commands    [Toc]    [Back]
       Interactive format commands consist of a keyword  followed
       by  zero or more 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 > (redirect
       metacharacter), followed by a file name,  to  the  command

       A  number  of  interactive  format  commands  are executed
       entirely within the ntpq program itself and do not  result
       in NTP mode 6 requests being sent to a daemon.  These commands
 are as follows: A ?  by itself prints a list of  all
       the  command  keywords  known to this version of ntpq. A ?
       followed by a command keyword prints  function  and  usage
       information  about  the  command.  The data carried by NTP
       mode 6 messages consists of a list of items of the form:


              where the value is ignored, and can be omitted,  in
              requests  to the server to read variables. The ntpq
              program maintains an internal list in which data to
              be  included  in control messages can be assembled,
              and sent using the readlist and writelist commands.
              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 separated by commas and not contain white space.
              The rmvars command can be used to remove individual
              variables from the list, while the  clearlist  command
 removes all variables from the list.  Normally
              ntpq does not authenticate requests unless they are
              write   requests.   The  authenticate  yes  command
              causes  ntpq  to  send  authentication   with   all
              requests  it  makes.   Authenticated requests cause
              some servers to handle  requests  slightly  differently.
  To  prevent  any  mishap, do a peer display
              before turning on authentication.  Reformats  variables
  that are recognized by the server. Variables
              that ntpq does not  recognize  are  marked  with  a
              trailing  ?.   Adjusts level of ntpq debugging. The
              default is off.  Specifies a time  interval  to  be
              added  to  timestamps  included  in  requests  that
              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 time stamps in authenticated  requests,  so
              this command may be obsolete.  Same as ?.  Sets the
              host to which future queries will be sent; hostname
              may be either a host name or a Internet address. If
              hostname is not  specified,  the  current  host  is
              used.   If  yes  is specified, prints host names in
              information displays.  If no is  specified,  prints
              Internet  addresses  instead.   The  default is yes
              unless modified using the command line  -n  option.
              Specifies  a  key number to be used to authenticate
              configuration requests.  This must correspond to  a
              key  number  the  server has been configured to use
              for this purpose.  Setsthe  authentication  key  to
              either  md5  or des.  Only md5 is supported in this
              implementation.  Sets the NTP version  number  that
              ntpq claims in packets.  To display the NTP version
              that ntpq currently claims, execute ntpversion with
              no  arguments.  Although most servers run version 3
              or better, ntpq claims version  2  by  default  for
              backwards  compatibility. (Note that Mode 6 control
              messages, and modes, for that matter, did not exist
              in  NTP version 1.)  Prompts you to type in a password
 (which will not be echoed)  that  is  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.  Polls the current server  in
              client  mode.   The first argument is the number of
              times to poll (default is 1) while the second argument
  may be given to obtain a more detailed output
              of the results.  Exits  ntpq.   Prints  all  output
              from  query  commands  as  received from the remote
              server.  The only data formatting performed  is  to
              translate  nonascii  data  into  a  printable form.
              Specifies a timeout period for responses to  server
              queries.   The  default is about 5000 milliseconds.
              Since ntpq retries each query once after a timeout,
              the  total waiting time for a timeout will be twice
              the timeout value.

   Control Message Commands    [Toc]    [Back]
       Each peer known to an NTP  server  has  a  16-bit  integer
       association  identifier  assigned to it.  NTP control messages
 that 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  variables 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 currently
 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  status  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 is 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: The
       data returned by the associations command is cached internally
  in  ntpq.  The index is then used when dealing with
       servers that use association identifiers. For  any  subsequent
  commands which require an association identifier as
       an argument, the form &index may be used  as  an  alternative.
   An  easy-to-type  short form of the clocklist command.
  Reads the clock variables included in the  variable
       list.   Requests  that the server send a list of the clock
       variables.  Servers that  have  a  radio  clock  or  other
       external  synchronization will respond positively to this.
       If the association identifier  is  omitted  or  zero,  the
       request  is for the system clock variables and will generally
 get a positive  response  from  all  servers  with  a
       clock.   If  the server treats clocks as pseudo-peers, and
       can possibly have more than one clock connected  at  once,
       referencing  the appropriate peer association ID will show
       the variables of a particular  clock.   If  you  omit  the
       variable  list, the server returns a default variable display.
  An easy-to-type short form of the clockvar command.
       Obtains  and  prints a list of association identifiers and
       peer status 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  associations
       command  is used, but are included in the output of lassociations.
  Obtains and prints a  list  of  all  peers  and
       clients  having  the destination address.  Prints data for
       all associations, including  out-of-spec  client  associations,
  from  the  internally cached list of associations.
       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.  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.  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 easy-to-type
       short form of  the  mreadlist  command.   An  easy-to-type
       short  form  of  the mreadvar command.  An old form of the
       peers command with the reference ID replaced by the  local
       interface  address.   Prints  association  data concerning
       in-spec peers from the internally cached list of  associations.
   This command performs identically to the associations
 except that it displays the internally  stored  data
       rather than making a new query.  Obtains a list of in-spec
       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  the  refID  is
       unknown),  the  stratum  of  the  remote peer, the polling
       interval, in seconds, the reachability register, in octal,
       and  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 are as follows: Indicates the peer  was  discarded
 due to high stratum or failed sanity checks,
              or both.  Indicates the peer was designated falseticker
  by  the  intersection  algorithm.  Indicates
              that this peer was culled from the end of the  candidate
 list.  Indicates that the peer was discarded
              by the clustering algorithm.   Indicates  that  the
              peer  was  included  in  the  final  selection set.
              Indicates the peer was  selected  for  synchronization,
  but distance exceeds the maximum.  Indicates
              the peer was selected for  synchronization.   Indicates
  the  peer  was 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 might
              fail to work with servers that poorly  control  the
              data formats.

              The  contents  of the host field may be one of four
              forms: a host name,  an  IP  address,  a  reference
              clock  implementation  name  with its parameter, or
              REFCLK(implementation number, parameter). On  hostnames
  no  only,  IP-addresses  will  be displayed.
              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: The
              status  word from the header is displayed preceding
              the variables, both in hexadecimal and in  English.
              Requests  that  the server return the values of the
              variables in the internal  variable  list.  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;  the  remote  server  should return a default
              display.  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  are those of the corresponding
 peer.  If the variable list  is  empty,  a
              request  is  sent  without  data; the remote server
              should return a default display.   An  easy-to-type
              short   form   of   the   readlist   command.    An
              easy-to-type short form for  the  readvar  command.
              Prints  the variables on the variable list.  Prints
              the  ntpq  version  number.   Like   the   readlist
              request,  except  the  internal  list variables are
              written instead of read.  Like the readvar request,
              except  the specified variables are written instead
              of read.

ERRORS    [Toc]    [Back]

       ***Can't find host hostname


              The hostname is not in the  local  /etc/host  file.
              hostname:  timed  out,  nothing received ***Request
              timed out


              Check that xntpd is  running  on  the  remote  host
              being queried.

NOTES    [Toc]    [Back]

       The  peers  command  is  non-atomic  and  may occasionally
       result in spurious error messages about  invalid  associations
 occurring and terminating the command.

       The timeout time is a fixed constant, which means you wait
       a long time for time outs since it assumes sort of a worst

FILES    [Toc]    [Back]

       Specifies the command path

SEE ALSO    [Toc]    [Back]

       Commands: ntpdate(8), xntpd(8), xntpdc(8)

       Files: ntp.conf(4)

[ Back ]
 Similar pages
Name OS Title
xntpdc Tru64 Monitor and control program for the Network Time Protocol daemon
ntp Tru64 query a clock running a Network Time Protocol daemon, either ntpd or xntpd
ntpq HP-UX standard Network Time Protocol query program
ntpdate Tru64 set the date and time via NTP (Network Time Protocol)
ntptimeset Linux the network time protocol
xntpd Tru64 Network Time Protocol (NTP) daemon
ntpd OpenBSD Network Time Protocol daemon
ntpd FreeBSD Network Time Protocol (NTP) daemon
xntpd HP-UX Network Time Protocol daemon
ntp_intro Tru64 Network Time Protocol (NTP) introductory information
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service