ntpq(1M)
NAME
ntpq - standard Network Time Protocol query program
SYNOPSIS
/usr/sbin/ntpq [-inp] [-c command] [host] [...]
DESCRIPTION
ntpq queries NTP servers which implement the recommended
NTP mode 6 control message format, about current state. It
can also request changes in that state. The program can be
run in interactive mode; or it can be controlled using com-
mand line arguments. Requests to read and write arbitrary
variables can be assembled, with raw and pretty-printed out-
put options available. By sending multiple queries to the
server, ntpq can also obtain and print a list of peers in a
common format.
If one or more request options are included on the command
line, ntpq sends each of the requests to NTP servers run-
ning on each of the hosts given as command line arguments.
By default, ntpq sends its requests to localhost, if hosts
are not included on the command line. If no request options
are given, ntpq attempts to read commands from the standard
input and execute them on the NTP server running on the
first host given on the command line. Again, ntpq defaults
to localhost if no other host is specified.
ntpq uses NTP mode 6 packets to communicate with an NTP
server. Thus, it can be used to query any compatible server
on the network that permits queries. Since NTP is a UDP
protocol, this communication will be somewhat unreliable,
especially over large distances. ntpq makes one attempt to
retransmit requests; requests timeout if the remote host is
not heard from within a suitable period.
OPTIONS
Command line options are described below. Specifying a com-
mand line option other than -i or -n causes the specified
query (queries) to be sent, immediately to the indicated
host(s). Otherwise, ntpq attempts to read interactive format
commands from standard input.
-c Interpret the next argument as an interactive
format command and add it to the list of commands
to be executed on the specified host(s). Multiple
-c options may be given.
-i Operate in interactive mode; write prompts to
standard output and read commands from standard
input.
-n Output all host addresses in dotted-quad numeric
format rather than converting them to canonical
host names.
-p Print 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. See
USAGE below.
USAGE
Interactive format commands consist of a keyword followed by
up to four arguments. Only enough characters of the full
keyword to uniquely identify the command need be typed. Nor-
mally, the output of a command is sent to standard output;
but this output may be written to a file by appending a `>',
followed by a file name, to the command line.
Interactive Commands
A number of interactive format commands are executed
entirely within the ntpq program itself. They do not result
in NTP mode 6 requests being sent to a server. If no
request options are included on the command line, and if
the standard input is a terminal device, ntpq prompts for
these commands. The interactive commands are described
below:
? [ command_keyword ]
A `?' by itself prints a list of all the command
keywords known to the current version of ntpq. A
`?' followed by a command keyword prints function
and usage information about the command.
timeout milliseconds
Specifies a time out period for responses to
server queries. The default is about 5000 mil-
liseconds. Since ntpq retries each query once
after a time out, the total waiting time for a
time out is twice the time out value that is set.
delay milliseconds
Specifies a time interval to be added to times-
tamps included in requests which require authen-
tication. This command is used to enable
(unreliable) server reconfiguration over long
delay network paths or between machines whose
clocks are unsynchronized. Currently, the server
does not require time stamps in authenticated
requests. Thus, this command may be obsolete.
host hostname
Set the name of the host to which future queries
are to be sent. Hostname may be either a host
name or a numeric address.
keyid #
Specify of a key number to be used to authenti-
cate configuration requests. This number must
correspond to a key number the server has been
configured to use for this purpose.
passwd
Prompts the user to type in a password which will
be used to authenticate configuration requests.
If an authenticating key has been specified (see
keyid above), this password must correspond to
this key. ntpq does not echo the password as it
is typed.
hostnames yes|no
If "yes" is specified, host names are printed in
information displays. If "no" is given, numeric
addresses are printed instead. The default is
"yes" unless modified using the command line -n
switch.
raw Print all output from query commands exactly as
it is received from the remote server. The only
formatting/filtering done on the data is to
transform non- ASCII data into printable form.
cooked
Causes output from query commands to be "cooked".
The values of variables recognized by the server
are reformatted, so that they can be more easily
read. Variables which ntpq thinks should have a
decodable value, but do not, are marked with a
trailing `?'.
ntpversion [ 1|2|3 ]
Sets the NTP version number which ntpq claims in
packets (defaults is 3). Note that mode 6 control
messages (and modes, for that matter) did not
exist in NTP version 1. There appear to be no
servers left which demand version 1.
authenticate [ yes|no ]
The command authenticate yes instructs ntpq to
send authentication with all requests it makes.
Normally ntpq does not authenticate requests
unless they are write requests. Authenticated
requests cause some servers to handle requests
slightly differently, and can occasionally cause
a slowed response if you turn authentication on
before doing a peer display. 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. ntpq maintains an internal list
in which data to be included in control mes-
sages can be assembled, and sent. This is
accomplished with the readlist and writelist
commands described below. The addvars com-
mand 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 it should not con-
tain white space. The rmvars command can be
used to remove individual variables from the
list; the clearlist command removes all
variables from the list.
debug [ more|less|off ]
Turns internal query program debugging on
and off.
quit Exit ntpq.
Control Message Commands
Each peer known to an NTP server has a 16 bit integer asso-
ciation identifier assigned to it. NTP control messages
which carry peer variables must identify the peer that the
values correspond to, by including its association ID. An
association ID of 0 is special. It indicates the variables
are system variables, whose names are drawn from a separate
name space.
Control message commands send one or more NTP mode 6 mes-
sages 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 mreadlist and mreadvar
commands. The peers command sends a preprogrammed series of
messages to obtain the data it needs. The mreadlist and
mreadvar commands, iterate over a range of associations.
Control message commands are described below:
associations
Obtains and prints a list of association identif-
iers 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 that
numbers the associations from 1, for internal
use. The second column contains the actual asso-
ciation identifier returned by the server and the
third the status word for the peer. This is fol-
lowed by a number of columns containing data
decoded from the status word. Note that the data
returned by the associations command is cached
internally in ntpq. The index is then of use when
dealing with "dumb" servers which use association
identifiers that are hard for humans to type. For
any subsequent commands which require an associa-
tion identifier as an argument, the identifier
can be specified by using the form, &index. Here
index is taken from the previous list.
lassociations
Obtains and prints a list of association identif-
iers and peer statuses for all associations for
which the server is maintaining
state. This command differs from the associa-
tions 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.
passociations
Prints association data concerning in-spec peers
from the internally cached list of associations.
This command performs identically to the associa-
tions command except that it displays the inter-
nally stored data rather than making a new query.
lpassociations
Print data for all associations, including out-
of-spec client associations, from the internally
cached list of associations. This command differs
from passociations only when dealing with
servers which retain state for out-of-spec
client associations.
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
that the status word from the header is displayed
preceding the variables, both in hexadecimal and
in pigeon English.
readvar [ assoc ] [ variable_name[=value] [ ,... ]]
Requests that the values of the specified vari-
ables 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 vari-
ables 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.
rv [ assocID ] [ variable_name[=value] [ ,... ]]
An easy-to-type short form for the readvar com-
mand.
writevar assocID variable_name=value [ ,... ]
Like the readvar request, except the specified
variables are written instead of read.
readlist [ assocID ]
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.
rl [ assocID ]
An easy-to-type short form of the readlist com-
mand.
writelist [ assocID ]
Like the readlist request, except the internal
list variables are written instead of read.
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 association
list cached by the most recent associations com-
mand.
mrv assocID assocID [ variable_name[=value] [ ,... ]]
An easy-to-type short form of the mreadvar com-
mand.
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 associa-
tion list cached by the most recent associations
command.
mrl assocID assocID
An easy-to-type short form of the mreadlist com-
mand.
clockvar [ assocID ] [ variable_name[=value] [ ,... ]]
Requests that a list of the server's clock vari-
ables be sent. Servers which have a radio clock
or other external synchronization respond posi-
tively to this. If the association identifier is
omitted or zero the request is for the variables
of the "system clock". This request generally
gets a positive response from all servers with a
clock. Some servers may treat clocks as pseudo-
peers and, hence, can possibly have more than one
clock connected at once. For these servers,
referencing the appropriate peer association ID
shows the variables of a particular clock. Omit-
ting the variable list causes the server to
return a default variable display.
cv [ assocID ] [ variable_name[=value] [ ,... ]]
An easy-to-type short form of the clockvar com-
mand.
peers Obtains a list of in-spec peers of the server,
along with a summary of each peer's state. Sum-
mary information includes:
o The address of the remote peer
o The reference ID (0.0.0.0 if the ref ID is
unknown)
o The stratum of the remote peer
o The type of the peer (local, unicast, mul-
ticast or broadcast) when the last packet
was received
o The polling interval in seconds
o The reachability register, in octal
o The current 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
mean:
SPACE
Discarded due to high stratum and/or failed san-
ity checks.
x Designated falsticker by the intersection algo-
rithm.
. Culled from the end of the candidate list.
- Discarded by the clustering algorithm.
+ Included in the final selection set.
# Selected for synchronization; but distance
exceeds maximum.
* Selected for synchronization.
o 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 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 given in one of
four forms. It may be a host name, an IP address, a
reference clock implementation name with its parameter
or, REFCLK(implementation number, parameter). On "host-
names no" only IP-addresses will be displayed.
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 from inade-
quate servers.
opeers
An old form of the peers command with the reference
ID replaced by the local interface address.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWntpu |
|_____________________________|_____________________________|
SEE ALSO
attributes(5)
BUGS
The peers command is non-atomic. It may occasionally result
in spurious error messages about invalid associations occur-
ring and terminating the command.
The timeout value is a fixed constant. As a result, it often
waits a long time to timeout, since the fixed value assumes
sort of a worst case. The program should improve the time
out estimate as it sends queries to a particular host; but
it does not.
Man(1) output converted with
man2html