ntpq(1M)ntpq(1M)NAMEntpq - standard Network Time Protocol query program
SYNOPSIS
command]... [host]...
DESCRIPTION
is used to query NTP servers, that 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 con‐
trolled mode using command line arguments. Requests to read and write
arbitrary variables can be assembled, with raw and pretty-printed out‐
put options available. 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 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 to local‐
host by default. If no request options are given, attempts 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. prompts for commands if
the standard input is a terminal device.
uses NTP mode 6 packets to communicate with the NTP server, and hence
can be used to query any compatible server on the network which permits
it. Note that since NTP is a UDP protocol this communication is some‐
what unreliable, especially over large distances in terms of network
topology. makes one attempt to retransmit requests, and will time out
if the remote host is not heard from within a suitable timeout time.
Command Line Options
The command line options supported are described below. Specifying a
command line option other than or causes the specified query (queries)
to be sent to the indicated host(s) immediately. Otherwise, attempts
to read interactive format commands from the standard input.
Interactive format command.
The command is added to the list of commands to be executed on
the specified host(s). Multiple options may be given.
Print debugging information.
Force to operate in interactive mode. Prompts are written to the stan‐
dard output and commands read from the standard input.
Output all host addresses in dotted-quad numeric format rather than
converting to the canonical host names.
Print a list of the peers known to the server as well as a summary of
their state. This is equivalent to the interactive command.
Interactive Commands
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 needs to 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, on the command line. A number of interactive format com‐
mands are executed entirely within the program itself and do not result
in NTP mode 6 requests being sent to a server. These are described
below.
A or by itself prints a list of all the command keywords
known to this version of A or 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 is ignored, and can
be omitted in requests to the server to
read variables. maintains an internal
list in which data to be included in
control messages can be assembled, and
sent using the and commands described
below.
This 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-sepa‐
rated and not contain white space.
This command can be used to remove individual
variables from the list.
This command removes all variables from the list.
Normally does not authenticate requests unless
they are write requests. The command
causes 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.
Causes output from query commands to be
Variables which are recognized by the
server have their values reformatted for
human usage.
Turns internal query program debugging on and off.
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.
Set the host to which future queries will be sent.
Hostname may be either a host name or a
numeric address.
If is specified, host names are printed in
information displays. If is specified,
numeric addresses are printed instead.
The default is unless modified using the
command line option.
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.
Sets the NTP version number which
claims in packets. Defaults to 3. Note
that mode 6 control messages (and
modes) did not exist in NTP version 1.
There appears to be no servers left
which demand version 1.
Exit
This command prompts you to type in a password
(which is not
echoed) which will be used to authenti‐
cate configuration requests. The pass‐
word must correspond to the key config‐
ured for use by the server for this pur‐
pose if such requests are to be success‐
ful.
Causes all output from query commands to be
printed as received from the
remote server. The only format‐
ting/interpretation done on the data is
to transform nonascii data into a print‐
able form.
Specify a timeout period for responses to server
queries.
The default is about 5000 milliseconds.
Note that since retries each query once
after a timeout, the total waiting time
for a timeout is twice the timeout value
set.
Control Message Commands
Each peer known to an server has 16 bit integer
association identifier assigned to it. NTP con‐
trol messages which carry peer variables must
identify the peer, the values it corresponds 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 command, which sends a
preprogrammed series of messages to obtain the
data it needs, and the and commands, which iterate
over a range of associations. The supported con‐
trol messages are listed below:
Obtains and prints a list of association identi‐
fiers and peer status
for in-spec peers of the server being
queried. The list is printed in col‐
umns. The first of these columns is an
index numbering the associations from 1
for internal use, the second column is
the actual association identifier
returned by the server and the third
column is 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 command is cached internally in 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 com‐
mands which require an association iden‐
tifier as an argument, the form and
index may be used as an alternative.
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 association identifier is
omitted or zero, the request is
for the variables of the and gen‐
erally gets a positive response
from all servers with a clock.
If the server treats the clocks
as pseudo-peers, then more than
one clock connected at once, ref‐
erencing the appropriate peer
association ID will show the
variables of a particular clock.
Omitting the variable list causes
the server to return a default
variable display.
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
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 command is used,
but are included in the output of
Print data for all associations, including
out-of-spec client
associations, from the internally
cached list of associations.
This command differs from command
only when dealing with fuzzballs.
Similar to
command, 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.
Similar to the
command, except the query
is done for each range of
(nonzero) association IDs.
This range is determined
from the association list
cached by the most recent
associations command.
Similar to the
command, except the
query is done for
each range of
(nonzero) associa‐
tion IDs. This
range is determined
from the associa‐
tion list cached by
the most recent
associations com‐
mand.
An old form of the
command with the
reference ID
replaced by the
local interface
address.
Prints association data con‐
cerning in-spec peers from
the internally
cached list of
associations. This
command performs
identically to the
except that it dis‐
plays the inter‐
nally 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
type of the peer
(local, unicast,
multicast or broad‐
cast), when the
last packet was
received, the
polling interval,
in seconds, the
reachability regis‐
ter, in octal, and
the current esti‐
mated 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
have the following
meaning:
Discarded due to
high stratum and/or
failed sanity
checks.
Designated falset‐
icker by the inter‐
section algorithm.
Culled from the end
of the candidate
list.
Discarded by the
clustering algo‐
rithm.
Included in the
final selection
set.
Selected for syn‐
chronization but
distance exceeds
maximum.
Selected for syn‐
chronization.
selected for syn‐
chronization, PPS
signal in use.
Note that since the 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 for‐
mats. The contents of the
host field may be one of four
forms. It may be a host
name, an IP address, a refer‐
ence clock implementation
name with its parameter or
<implementation number>,
<parameter>). On only
IP-addresses will be dis‐
played.
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 dis‐
played preceding the
variables, both in
hexadecimal and in
English.
Requests that the val‐
ues of the variables
in the internal vari‐
able list
be returned by
the server. If
the association
ID is omitted
or is 0, the
variables are
assumed to be
system vari‐
ables. Other‐
wise 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 dis‐
play.
Requests that
the values of
the specified
variables be
returned by the
server
by send‐
ing a
read
vari‐
ables
request.
If the
associa‐
tion ID
is omit‐
ted or
is given
as zero,
the
vari‐
ables
are sys‐
tem
vari‐
ables.
Other‐
wise
they are
peer
vari‐
ables
and the
values
returned
will be
those of
the cor‐
respond‐
ing
peer.
Omitting
the
variable
list
will
send a
request
with no
data
which
should
induce
the
server
to
return a
default
display.
Similar to the
command,
except
the
speci‐
fied
vari‐
ables
are
written
instead
of read.
Similar to the
command,
except
the
internal
list
vari‐
ables
are
written
instead
of read.
WARNINGS
The command is
non-atomic and
may occasion‐
ally result in
spurious error
messages about
invalid associ‐
ations occur‐
ring and termi‐
nating the com‐
mand. The
timeout time is
a fixed con‐
stant, which
means a long
wait for time‐
outs since it
assumes a worst
case.
FILES
Contains the
encryption keys
used for
authentication.
AUTHOR
was developed
by Dennis Fer‐
guson at the
University of
Toronto.
SEE ALSOntpdate(1M),
xntpd(1M), xnt‐
pdc(1M).
DARPA Internet
Request For
Comments
RFC1035
Assigned Num‐
bers.
ntpq(1M)