System Administration Commands 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 command
line arguments. Requests to read and write arbitrary vari-
ables 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 permits queries. Since NTP is a UDP pro-
tocol, this communication will be somewhat unreliable, espe-
cially 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 for-
mat 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 stan-
dard 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 stan-
dard input is a terminal device, ntpq prompts for these com-
mands. The interactive commands are described below:
? [command_keyword]
A `?' by itself prints a list of all the command key-
words known to the current version of ntpq. A `?' fol-
lowed 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 reconfi-
guration 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.
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 con-
figuration 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 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 infor-
mation 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 refor-
matted, 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 occasion-
ally 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 accom-
plished 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 indivi-
dual 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 vari-
ables 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 com-
mands. 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 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 that numbers the associations from 1,
for internal use. The second column contains 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 associa-
tions 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 asso-
ciation 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 statuses 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 associa-
tions 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 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 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.
pstatusassocID
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 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.
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 written instead of read.
readlist [ assocID]
Requests that the values of the variables in the inter-
nal 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 command.
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 command.
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 asso-
ciation identifier is omitted or zero the request is for
the variables of the "system clock". This request gen-
erally 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 con-
nected 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:
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, multicast 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 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 intersec-
tion algorithm.
. Culled from the end of the candidate
list.
- Discarded by the clustering algorithm.
+ Included in the final selection set.
# Selected for synchronization; but dis-
tance 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 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 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 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.
|
|
