ntpq(1M) System Administration Commands ntpq(1M)NAMEntpq - standard Network Time Protocol query program
SYNOPSIS
/usr/sbin/ntpq [-inp] [-c command] [host] [...]
DESCRIPTIONntpq 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 command line arguments. Requests to read and
write arbitrary variables can be assembled, with raw and pretty-printed
output 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 running 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 per‐
mits 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 command 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 spec‐
ified 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 inter‐
active 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 iden‐
tify the command need be typed. Normally, 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 com‐
mand 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.
timeoutmilliseconds
Specifies a time out period for responses to server queries. The
default is about 5000 milliseconds. 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.
delaymilliseconds
Specifies a time interval to be added to timestamps included in
requests which require authentication. This command is used to
enable (unreliable) server reconfiguration over long delay network
paths or between machines whose clocks are unsynchronized. Cur‐
rently, the server does not require time stamps in authenticated
requests. Thus, this command may be obsolete.
hosthostname
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 authenticate configuration
requests. This number must correspond to a key number the server
has been configured to use for this purpose.
passwd
Allow the user to specify a password at the command line. This will
be used to authenticate configuration requests. If an authenticat‐
ing 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 dis‐
plays. 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 mat‐
ter) 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 messages can be assembled, and
sent. This is accomplished with 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 it should
not contain 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 association 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 messages 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 sin‐
gle response. The current exceptions are the peers mreadlist and mread‐
var commands. The peers command sends a preprogrammed series of mes‐
sages 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 identifiers and peer sta‐
tuses 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 con‐
tains the actual association identifier returned by the server and
the third the status word for the peer. This is followed by a num‐
ber of columns containing data decoded from the status word. Note
that the data returned by the associations command is cached inter‐
nally 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 association
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 identifiers and peer sta‐
tuses 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.
passociations
Prints association data concerning in-spec peers from the inter‐
nally cached list of associations. This command performs identi‐
cally to the associations command except that it displays the
internally stored data rather than making a new query.
lpassociations
Print data for all associations, including out-of-spec client asso‐
ciations, 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.
pstatusassocID
Sends a read status request to the server for the given associa‐
tion. 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 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 vari‐
ables, 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.
rv [ assocID] [ variable_name[=value][ ,... ]]
An easy-to-type short form for the readvar command.
writevar assocID variable_name=value [ ,... ]
Like the readvar request, except the specified variables are writ‐
ten 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 command.
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 command.
mreadlistassocID 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 association list cached by the most recent associations com‐
mand.
mrlassocID assocID
An easy-to-type short form of the mreadlist command.
clockvar [ assocID] [ variable_name[=value][ ,... ]]
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 omit‐
ted 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. Omitting 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 command.
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 ref ID 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
·
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 mean:
SPACE Discarded due to high stratum and/or failed sanity
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 formats.
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 implementa‐
tion name with its parameter or, REFCLK(implementation number,
parameter). On "hostnames 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 inadequate 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 attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWntpu │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOattributes(5)BUGS
The peers command is non-atomic. It may occasionally result in spurious
error messages about invalid associations occurring 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.
SunOS 5.10 12 July 2004 ntpq(1M)
