ntpq(8)ntpq(8)NAMEntpq - Network Time Protocol (NTP) monitor program for xntpd
SYNOPSIS
/usr/bin/ntpq [-inp] [-c command] [host1 host2...]
OPTIONS
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. Other‐
wise, ntpq attempts to read interactive format commands from the stan‐
dard input.
DESCRIPTION
The ntpq program is used to monitor NTP hosts running xntpd. The pro‐
gram 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 dae‐
mons 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
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 nor‐
mally sent to the standard output, but optionally the output of indi‐
vidual 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: 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:
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 com‐
mands. 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 individ‐
ual variables from the list, while the clearlist command removes
all variables from the list. Normally ntpq does not authenti‐
cate 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 authenti‐
cation. 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 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 authenti‐
cate configuration requests. This must correspond to a key num‐
ber 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 ver‐
sion 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
Each peer known to an NTP server has a 16-bit integer association iden‐
tifier assigned to it. NTP control messages that carry peer variables
must identify the peer the values correspond to by including its asso‐
ciation ID. An association ID of 0 is special, and indicates the vari‐
ables 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 iden‐
tifiers. For any subsequent commands which require an association iden‐
tifier 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 sys‐
tem 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 par‐
ticular 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 associa‐
tions are normally omitted from the display when the associations com‐
mand 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 asso‐
ciation 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 associ‐
ations 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 (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 cur‐
rent estimated delay, offset and dispersion of the peer, all in mil‐
liseconds.
The character in the left margin indicates the fate of this peer
in the clock selection process. The codes are as follows: Indi‐
cates the peer was discarded due to high stratum or failed san‐
ity checks, or both. Indicates the peer was designated falset‐
icker 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. Indi‐
cates the peer was selected for synchronization, but distance
exceeds the maximum. Indicates the peer was selected for syn‐
chronization. Indicates the peer was selected for synchroniza‐
tion; pps signal in use.
Since the peers command depends on the ability to parse the val‐
ues 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 spec‐
ified 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 corre‐
sponding 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
***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
Specifies the command path
SEE ALSO
Commands: ntpdate(8), xntpd(8), xntpdc(8)
Files: ntp.conf(4)ntpq(8)