347 lines
16 KiB
HTML
347 lines
16 KiB
HTML
<!-- $NetBSD: ntpq.html,v 1.1 1998/12/30 20:20:36 mcr Exp $ -->
|
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML Strict//EN">
|
|
<html><head><title>
|
|
ntpq - standard NTP query program
|
|
</title></head><body><h3>
|
|
<code>ntpq</code> - standard NTP query program
|
|
</h3><hr>
|
|
|
|
<p><h4>Synopsis</h4>
|
|
|
|
<p><code>ntpq [ -inp ] [ -c <i>command</i> ] [ <i>host</i> ] [ ... ]</code>
|
|
<p><h4>Description</h4>
|
|
|
|
<p><code>ntpq</code> is used to query NTP servers which implement the
|
|
recommended NTP mode 6 control message format about current state and to
|
|
request changes in that state. The program may be run either in
|
|
interactive mode or controlled using command line arguments. Requests to
|
|
read and write arbitrary variables can be assembled, with raw and
|
|
pretty-printed output options being available. <code>ntpq</code> can
|
|
also obtain and print a list of peers in a common format by sending
|
|
multiple queries to the server.
|
|
|
|
<p>If one or more request options is included on the command line when
|
|
<code>ntpq</code> 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 localhost by default. If no request options are given,
|
|
<code>ntpq</code> 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. <code>ntpq</code> will prompt for commands if the standard
|
|
input is a terminal device.
|
|
|
|
<p><code>ntpq</code> uses NTP mode 6 packets to communicate with the NTP
|
|
server, and hence can be used to query any compatable 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 topology. <code>ntpq</code> makes one
|
|
attempt to retransmit requests, and will time requests out if the remote
|
|
host is not heard from within a suitable timeout time.
|
|
|
|
<p>Command line options are described following. Specifying a command
|
|
line option other than -i or -n will cause the specified query (queries)
|
|
to be sent to the indicated host(s) immediately. Otherwise,
|
|
<code>ntpq</code> will attempt to read interactive format commands from
|
|
the standard input.
|
|
|
|
<dl>
|
|
|
|
<dt><code>-c</code>
|
|
<dd>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). Multiple -c options may be given.
|
|
|
|
<p><dt><code>-i</code>
|
|
<dd>Force <code>ntpq</code> to operate in interactive mode. Prompts will
|
|
be written to the standard output and commands read from the standard
|
|
input.
|
|
|
|
<p><dt><code>-n</code>
|
|
<dd>Output all host addresses in dotted-quad numeric format rather than
|
|
converting to the canonical host names.
|
|
|
|
<p><dt><code>-p</code>
|
|
<dd>Print a list of the peers known to the server as well as a summary
|
|
of their state. This is equivalent to the <code>peers</code> interactive
|
|
command.
|
|
|
|
</dl>
|
|
<p><h4>Internal Commands</h4>
|
|
|
|
<p>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 <code>ntpq</code> program itself and do not
|
|
result in NTP mode 6 requests being sent to a server. These are
|
|
described following.
|
|
|
|
<dl>
|
|
|
|
<dt><code>? [ <i>command_keyword</i> ]</code>
|
|
<br><code>helpl [ <i>command_keyword</i> ]</code>
|
|
<dd>A <code>"?"</code> by itself will print a list of all the command
|
|
keywords known to this incarnation of <code>ntpq</code>. A
|
|
<code>"?"</code> followed by a command keyword will print funcation and
|
|
usage information about the command. This command is probably a better
|
|
source of information about <code>ntpq</code> than this manual page.
|
|
|
|
<p><dt><code>addvars <i>variable_name</i> [ = <i>value</i> ] [ ...
|
|
]</code>
|
|
<br><code>rmvars <i>variable_name</i> [ ... ]</code>
|
|
<br><code>clearvars</code>
|
|
<dd>The data carried by NTP mode 6 messages consists of a list of items
|
|
of the form <code><i>variable_name</i> = <i>value</i></code>, where the
|
|
<code>" = <i>value</i>"</code> is ignored, and can be omitted, in
|
|
requests to the server to read variables. <code>ntpq</code> 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 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 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.
|
|
|
|
<p><dt><code>authenticate yes | no</code>
|
|
<dd>Normally <code>ntpq</code> does not authenticate requests unless
|
|
they are write requests. The command authenticate yes causes
|
|
<code>ntpq</code> to send authentication with all requests it makes.
|
|
Authenticated requests causes some servers to handle requests slightly
|
|
differently, and can occasionally melt the CPU in fuzzballs if you turn
|
|
authentication on before doing a peer display.
|
|
|
|
<p><dt><code>cooked</code>
|
|
<dd>Causes output from query commands to be <code>"cooked"</code>.
|
|
Variables which are recognized by the server will have their values
|
|
reformatted for human consumption. Variables which <code>ntpq</code>
|
|
thinks should have a decodeable value but didn't are marked with a
|
|
trailing <code>"?"</code>.
|
|
|
|
<p><dt><code>debug more | less | off</code>
|
|
<dd>Turns internal query program debugging on and off.
|
|
|
|
<p><dt><code>delay <i>milliseconds</i></code>
|
|
<dd>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.
|
|
<p><dt><code>host <i>hostname</i></code>
|
|
<dd>Set the host to which future queries will be sent. Hostname may be
|
|
either a host name or a numeric address.
|
|
|
|
<p><dt><code>hostnames [ yes | no ]</code>
|
|
<dd>If <code>"yes"</code> is specified, host names are printed in
|
|
information displays. If <code>"no"</code> is specified, numeric
|
|
addresses are printed instead. The default is <code>"yes"</code>, unless
|
|
modified using the command line <code>-n</code> switch.
|
|
|
|
<p><dt><code>keyid <i>keyid</i></code>
|
|
<dd>This command allows the specification of 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.
|
|
|
|
<p><dt><code>ntpversion 1 | 2 | 3</code>
|
|
<dd>Sets the NTP version number which <code>ntpq</code> claims in
|
|
packets. Defaults to 3, Note that mode 6 control messages (and modes,
|
|
for that matter) didn't exist in NTP version 1. There appear to be no
|
|
servers left which demand version 1.
|
|
|
|
<p><dt><code>quit</code>
|
|
<dd>Exit <code>ntpq</code>.
|
|
|
|
<p><dt><code>passwd</code>
|
|
<dd>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.
|
|
|
|
<p><dt><code>raw</code>
|
|
<dd>Causes all output from query commands is printed as received from
|
|
the remote server. The only formating/intepretation done on the data is
|
|
to transform nonascii data into a printable (but barely understandable)
|
|
form.
|
|
|
|
<p><dt><code>timeout <i>millseconds</i></code>
|
|
<dd>Specify a timeout period for responses to server queries. The
|
|
default is about 5000 milliseconds. Note that since <code>ntpq</code>
|
|
retries each query once after a timeout, the total waiting time for a
|
|
timeout will be twice the timeout value set.
|
|
|
|
</dl>
|
|
|
|
<p><h4>Control Message Commands</h4>
|
|
|
|
<p>Each peer known to an NTP server has a 16 bit integer association
|
|
identifier assigned to it. 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 variables, whose names are drawn from a separate
|
|
name space.
|
|
|
|
<p>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.
|
|
|
|
<dl>
|
|
|
|
<dt><code>associations</code>
|
|
<dd>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
|
|
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
|
|
<code>"associations"</code> command is cached internally in
|
|
<code>ntpq</code>. The index is then of use when dealing with stupid
|
|
servers which use association identifiers which are hard for humans to
|
|
type, in that for any subsequent commands which require an association
|
|
identifier as an argument, the form &index may be used as an
|
|
alternative.
|
|
|
|
<p><dt><code>clockvar [ <i>assocID</i> ] [ <i>variable_name</i> [ =
|
|
<br><code>cv [ <i>assocID</i> ] [ <i>variable_name</i> [ = <i>value</i>
|
|
[ ... ]</code> ] [ ... ]</code>
|
|
<dd>Requests that a list of the server's clock variables be sent.
|
|
Servers which 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 variables of the <code>"system clock"</code>
|
|
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.
|
|
|
|
<p><dt><code>lassocations</code>
|
|
<dd>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 <code>"associations"</code> 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 <code>"associations"</code> command is used, but are
|
|
included in the output of <code>"lassociations"</code>.
|
|
|
|
<p><dt><code>lpassociations</code>
|
|
<dd>Print data for all associations, including out-of-spec client
|
|
associations, from the internally cached list of associations. This
|
|
command differs from <code>"passociations"</code> only when dealing with
|
|
fuzzballs.
|
|
|
|
<p><dt><code>lpeers</code>
|
|
<dd>Like R 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.
|
|
|
|
<p><dt><code>mreadlist <i>assocID</i> <i>assocID</i></code>
|
|
<br><code>mrl <i>assocID</i> <i>assocID</i></code>
|
|
<dd>Like the <code>readlist</code> 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
|
|
<code>associations</code> command.
|
|
|
|
<p><dt><code>mreadvar <i>assocID</i> <i>assocID</i> [
|
|
<i>variable_name</i> [ = <i>value</i> [ ... ]</code>
|
|
<br><code>mrv <i>assocID</i> <i>assocID</i> [ <i>variable_name</i> [ =
|
|
<i>value</i> [ ... ]</code>
|
|
<dd>Like the <code>readvar</code> 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
|
|
<code>associations</code> command.
|
|
|
|
<p><dt><code>opeers</code>
|
|
<dd>An old form of the <code>peers</code> command with the reference ID
|
|
replaced by the local interface address.
|
|
<p><dt><code>passociations</code>
|
|
<dd>Prints association data concerning in-spec peers from the internally
|
|
cached list of associations. This command performs identically to the
|
|
<code>"associations"</code> except that it displays the internally
|
|
stored data rather than making a new query.
|
|
|
|
<p><dt><code>peers</code>
|
|
<dd>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 type of the peer (local, unicast,
|
|
multicast or broadcast), when the last packet was received, the polling
|
|
interval, in seconds, the reachability register, in octal, and the
|
|
current estimated delay, offset and dispersion of the peer, all in
|
|
seconds.
|
|
|
|
<p><dd>The character in the left margin indicates the fate of this peer
|
|
in the clock selection process. The codes mean: <sp> discarded due
|
|
to high stratum and/or failed sanity checks; <code>"x"</code> designated
|
|
falsticker by the intersection algorithm; <code>"."</code> culled from
|
|
the end of the candidate list; <code>"-"</code> discarded by the
|
|
clustering algorithmi; <code>"+"</code> included in the final selection
|
|
set; <code>"#"</code> selected for synchronizatio;n but distance exceeds
|
|
maximum; <code>"*"</code> selected for synchronization; and
|
|
<code>"o"</code> selected for synchronization, PPS signal in use.
|
|
|
|
<p><dd>Note that 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.
|
|
|
|
<p><dd>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 <code>"REFCLK(<implementation number>,
|
|
<parameter>)"</code>. On <code>"hostnames no"</code> only IP-
|
|
addresses will be displayed.
|
|
|
|
<p><dt><code>pstatus <i>assocID</i></code>
|
|
<dd>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 hexidecimal and in pidgeon English.
|
|
|
|
<p><dt><code>readlist [ <i>assocID</i> ]</code>
|
|
<br><code>rl [ <i>assocID</i> ]</code>
|
|
<dd>Requests that the values of the variables in the internal 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.
|
|
|
|
<p><dt><code>readvar <i>assocID</i> <i>variable_name</i> [ =
|
|
<i>value</i> ] [ ... ]</code>
|
|
<br><code>rv <i>assocID</i> [ <i>variable_name</i> [ = <i>value</i> ] [
|
|
... ]</code>
|
|
<dd>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.
|
|
|
|
<p><dt><code>writevar <i>assocID</i> <i>variable_name</i> [ =
|
|
<i>value</i> [ ... ]</code>
|
|
<dd>Like the readvar request, except the specified variables are written
|
|
instead of read.
|
|
|
|
<p><dt><code>writelist [ <i>assocID</i> ]</code>
|
|
<dd>Like the readlist request, except the internal list variables are
|
|
written instead of read.
|
|
|
|
</dl>
|
|
|
|
<p><h4>Bugs</h4>
|
|
|
|
<p>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 timeouts since it assumes sort of a worst
|
|
case. The program should improve the timeout estimate as it sends
|
|
queries to a particular host, but doesn't.
|
|
|
|
<hr><address>David L. Mills (mills@udel.edu)</address></body></html>
|