unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



ntpq(8)								      ntpq(8)



NAME

  ntpq - Network Time Protocol (NTP) monitor program for xntpd

SYNOPSIS

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

OPTIONS

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

  -n  Outputs all host addresses in dotted-decimal notation rather than	con-
      verting to the canonical host names.

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

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

  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 dae-
  mons,	and therefore can be used to query any compatible daemon on the	net-
  work that permits it.	 Note: Since NTP uses the UDP protocol,	this communi-
  cation will be somewhat unreliable, especially over large network topolo-
  gies.	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

  Interactive Commands


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

  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:

  ? [command_keyword]
      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.

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

  authenticate yes|no
      Normally ntpq does not authenticate requests unless they are write
      requests.	 The authenticate yes command causes ntpq to send authentica-
      tion 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.

  cooked
      Reformats	variables that are recognized by the server. Variables that
      ntpq does	not recognize are marked with a	trailing ?.

  debug	more|less|off
      Adjusts level of ntpq debugging. The default is off.

  delay	milliseconds
      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.

  help
      Same as ?.

  host [hostname]
      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.

  hostnames yes|no
      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.

  keyid	#
      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.

  keytype md5|des
      Setsthe authentication key to either md5 or des.	Only md5 is supported
      in this implementation.

  ntpversion 1|2|3
      Sets the NTP version number that ntpq claims in packets.	Default	is 3.
      Mode 6 control messages (and modes, for that matter) did not exist in
      NTP version 1.

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

  poll [#] [verbose]
      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.

  quit
      Exits ntpq.

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

  timeout milliseconds
      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


  Each peer known to an	NTP server has a 16-bit	integer	association identif-
  ier 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	for-
  mat.	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.

  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.

  cl  An easy-to-type short form of the	clocklist command.

  clocklist [assocID]
      Reads the	clock variables	included in the	variable list.

  clockvar [assocID] [variable_name[=value] [,...]]
      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	con-
      nected 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.

  cv [assocID] [variable_name[=value] [,...]]
      An easy-to-type short form of the	clockvar command.

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

  lopeers
      Obtains and prints a list	of all peers and clients having	the destina-
      tion address.

  lpassociations
      Prints data for all associations,	including out-of-spec client associa-
      tions, from the internally cached	list of	associations.

  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.

  mreadlist 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 asso-
      ciation list cached by the most recent associations command.

  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 asso-
      ciation list cached by the most recent associations command.

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

  mrv assocID assocID [variable_name[=value] [,...]]
      An easy-to-type short form of the	mreadvar command.

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

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

  peers
      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 (0.0.0.0 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:

      <&lt;sp>&gt;
	  Indicates the	peer was discarded due to high stratum or failed san-
	  ity checks, or both.

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

      o	  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 parame-
      ter, or REFCLK(implementation number, parameter).	On hostnames no	only,
      IP-addresses will	be displayed.

  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: The	status word from the header is displayed preceding the vari-
      ables, both in hexadecimal and in	English.

  readlist [assocID]
      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.

  readvar [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; other-
      wise, 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.

  rl [assocID]
      An easy-to-type short form of the	readlist command.

  rv [assocID] [variable_name[=value] [,...]]
      An easy-to-type short form for the readvar command.

  showvars
      Prints the variables on the variable list.

  version
      Prints the ntpq version number.

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

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

ERRORS

    +  ***Can't	find host hostname

       Explanation:

       The hostname is not in the local	/etc/host file.

    +  hostname: timed out, nothing received ***Request	timed out

       Explanation:

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

NOTES

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






FILES

  /usr/bin/ntpq
      Specifies	the command path


SEE ALSO

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

  Files: ntp.conf(4)