ntpq(1M) TCP/IP R4.11 ntpq(1M)
NAME
ntpq - query servers using the standard Network Time Protocol
SYNOPSIS
ntpq [ -inp ] [ -c command ] ... [ host ... ]
where:
command An ntpq command (see Commands in Alphabetical Order below)
host The host name of a system to be queried; default = localhost
DESCRIPTION
Ntpq uses NTP mode 6 packets to query NTP servers about current state
and to request changes in that state. You can run the program in
interactive mode or with command-line arguments. ntpq can read and
write arbitrary variables, with output raw or formatted. ntpq can
also print a list of peers in a common format.
If you use the -c or -p option, the specified commands are sent to
the NTP server(s) running on the hosts. If you omit -c and -p, ntpq
reads commands from the standard input and sends these to the NTP
server(s); if the standard input is a terminal device, ntpq prompts
for commands.
Ntpq can communicate with any server on the network that recognizes
NTP mode 6 control message format. Since NTP is a UDP protocol, this
communication is somewhat unreliable, especially over long distances.
ntpq tries once to retransmit requests, and times out if a response
is not received from the remote host within a suitable time (see
timeout under Commands in Alphabetical Order below).
Options
-c Add the specified command to the list of commands to be run
on the host(s).
-i Run ntpq in interactive mode. Prompts are written to the
standard output and commands read from the standard input.
-n Output all host addresses in dotted-quad numeric format
rather than converting to the 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 "-c peers".
Commands by Category
Each ntpq command comprises a keyword followed by zero or more
arguments. You need type only enough characters of the full keyword
to identify the command uniquely. By default, command output is sent
to the standard output; to redirect output to a file, append >
filename to the command.
Internal commands executed entirely within the ntpq program itself
and do not send NTP mode 6 requests to a server. The internal
commands are as follows:
+---------------------------------------------------------------------+
|Category Keyword Description of Task |
|General ? Display a help message |
| debug Turn debugging on or off |
| quit Exit from ntpq |
|I/O cooked Format query information |
| raw Leave query information unformatted |
| ntpversion Specify version of NTP packets |
|Operation host Set name of host to be queried |
| hostnames Set host ID display mode to name or number |
| timeout Specify the time-ovt interlal |
|Security authenticate Authenticate all queries* |
| delay Set delay factor for authentication requests* |
| keyid Specify an authentication key number |
| passwd Prompt for password to authenticate request |
|Variables addvars Set variables and add them to the ntpq list |
| rmvars Remove variables from the ntpq list |
| clearvars Remove all variables from the list |
+---------------------------------------------------------------------+
* On the DG/UX System, this command has no effect.
Control message commands send one or more NTP mode 6 messages to a
server and print the data returned in some format. Most commands
currently implemented send a single message and expect a single
response. The current exceptions are the peers command, which sends
a preprogrammed series of messages to obtain the data it needs, and
the mreadlist and mreadvar commands, which iterate over a range of
associations.
Each peer known to an NTP server has a 16-bit integer association
identifier assigned to it. NTP control messages that carry peer
variables must identify the peer the values correspond 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. The control message commands are as
follows:
+----------------------------------------------------------------------+
|Category Keyword Description of Task |
|Associations associations List in-spec associations |
| lassociations List all associations |
| passociations List associations using internal data |
| lpassociations List all associations using internal data |
| pstatus Display an association's status |
|Peers peers List the server's in-spec peers |
| lpeers List peers and summary information |
| opeers List peers, using local interface address |
|Variables readvar List variables from the server |
| writevar Write variables to the server |
| readlist Read internal variables list |
| writelist Write to internal variables list |
| mreadvar List variables for range of associations |
| mreadlist Read internal variables list for a range |
| clockvar List the server's clock variables |
+----------------------------------------------------------------------+
Commands in Alphabetical Order
In the command descriptions below, the syntax uses square brackets
([]) to delimit optional arguments, a vertical line (|) to separate
alternatives, and an ellipsis (...) to indicate repeatability.
? [ commandkeyword ]
If the argument is omitted, list all the command keywords recognized
by ntpq. If the argument is specified, display task and syntax
information about the command.
addvars variablename[=value] [,...]
The data carried by NTP mode 6 messages consists of a list of items
of the form
variablename=value
where "=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
using the readlist and writelist commands described below. The
addvars command lets you add variables and their optional values to
the list. To add more than one variable, make the list comma-
separated and containing no spaces or tabs.
associations
List 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 numbering the associations from 1 for internal
use, the second 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 associations command is cached
internally in ntpq. The index is useful when dealing with servers
that use association identifiers that are hard for humans to type;
for subsequent commands requiring an association identifier as an
argument, you can use &index as an alternative.
authenticate yes|no
Normally ntpq does not authenticate requests unless they are write
requests. The command authenticate yes causes ntpq to send
authentication with all requests it makes. Authenticated requests
cause some servers to handle requests slightly differently. On the
DG/UX System, this command has no effect.
clearvars
Remove all variables from the list. (See addvars.)
clockvar [ assocID ] [ variablename[=value] [,...] ]
Request that a list of the server's clock variables be sent. Servers
that 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 "system clock" and will
generally get a positive response from all servers with a clock. If
the server treats clocks as pseudo-peers and hence can possibly have
more than one clock connected at once, 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. This command is aliased as cv.
cooked
Cause output from query commands to be "cooked". Variables
recognized by the server have their values reformatted for human
consumption. Variables that ntpq thinks should have a decodable
value but didn't are marked with a trailing "?".
debug more|less|no
Turn internal query program debugging on and off.
delay milliseconds
Specify a time interval to be added to time stamps included in
requests that require authentication. This is used to enable
(unreliable) server reconfiguration over long-delay network paths or
between machines whose clocks are unsynchronized. On the DG/UX
System, this command has no effect.
host hostname
Set the host to which future queries will be sent. Hostname can be
either a host name or a numeric address.
hostnames yes|no
For "yes", display host names. For "no", display numeric addresses.
The default is "yes" unless you specify the -n option to ntpq.
keyid #
Specify 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.
lassociations
List 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 that 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.
lpassociations
Print data for all associations, including out-of-spec client
associations, from the internally cached list of associations.
lpeers
Do like peers, except print a summary of all associations for which
the server is maintaining state.
mreadlist assocID assocID
Do 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.
This command is aliased as mrl.
mreadvar assocID assocID [ variablename[=value] [,...] ]
Do 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.
This command is aliased as mrv.
ntpversion 2|3
Set the NTP version number that ntpq uses in packets. The default is
3.
opeers
Do like peers, except replace the reference ID with the local
interface address. This is an old form of the peers command.
passwd
Prompt for a password (which will not be echoed) used to authenticate
configuration requests. The password must correspond to the key
configured for use by the NTP server for this purpose.
passociations
List association data concerning in-spec peers from the internally
cached list of associations. This command performs identically to
the associations, except that it displays the internally stored data
rather than making a new query.
peers
List 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 reference ID is unknown), the
stratum of the remote peer, the polling interval in seconds, the
reachability register in octal, and the current estimated delay,
offset, and dispersion of the peer, all in seconds. In addition, the
character in the left margin indicates the fate of this peer in the
clock selection algorithm. Characters only appear beside peers which
were included in the final stage of the clock selection algorithm. A
period (.) indicates that this peer was cast off in the falseticker
detection, while a plus (+) indicates that the peer made it through.
A number sign (#) denotes the peer with which the server is currently
synchronizing. Note that 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 that poorly control the data
formats.
pstatus assocID
Send a read status request to the server for the given association.
The names and values of the peer variables returned are printed.
quit
Exit from ntpq.
raw
Cause all output from query commands to be printed as received from
the remote server. The only formatting or interpretation done on the
data is to transform non-textual data into a printable (but barely
understandable) form.
readlist [ assocID ]
Request 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. This command is aliased as rl.
readvar [ assocID ] [ variablename [,...] ]
Send a read variables request to the server to return the values of
the specified variables. 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
corresponding peer. Omitting the variable list sends a request with
no data, which should induce the server to return a default display.
This command is aliased as rv.
rmvars variablename [,...]
Remove individual variables from the list. (See addvars.)
timeout milliseconds
Specify a time-out period for responses to server queries. The
default is about 5000 milliseconds. Note that since ntpq retries
each query once after a time-out, the total waiting time for a time-
out is twice the value you specify.
writelist [ assocID ]
Do like the readlist request, except write instead of read the
internal list variables.
writevar assocID variablename=value [,...]
Do like the readvar request, except write instead of read the
specified variables.
SEE ALSO
ntpdate(1M), xntpdc(1M).
BUGS
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. The
program should improve the time out estimate as it sends queries to a
particular host, but it doesn't.
Licensed material--property of copyright holder(s)