ntpq(1M) ntpq(1M)
NAME
ntpq - command for NTP status queries
SYNOPSIS
ntpq [-inpd] [-c command] [system] [...]
DESCRIPTION
ntpq queries the current status of NTP (Network Time Protocol) servers
for mode 6 control messages and requests status changes. The command
can either be executed in interactive mode or controlled using command
line arguments.
If one or more instructions are specified in the command line, each of
these instructions is transmitted to the NTP servers running on the
individual systems specified in the command line arguments or, by
default, to the local system (localhost). If no instructions are
specified, ntpq tries to read commands from standard input and execute
them on the NTP server running on the first system specified in the
command line or, be default, (if no other system is specified) on the
local system (localhost).
ntpq uses mode 6 NTP packages to communicate with the NTP server and
can therefore be used to query any compatible server in the network.
The command line options are described in the following section. If a
command line option other than -i or -n is specified, the respective
query (queries) are transmitted directly to the system(s) specified.
Otherwise ntpq tries to read commands from standard input interac-
tively.
Page 1 Reliant UNIX 5.44 Printed 11/98
ntpq(1M) ntpq(1M)
OPTIONS
-c The following argument is interpreted as a command and added to
the list of commands to be executed on the specified hosts. The
-c option can be specified more than once.
-i Sets ntpq to interactive mode. Commands are read from standard
input.
-n Outputs all system addresses in dot notation instead of convert-
ing them to system names.
-p Prints a list of partners (NTP partners, systems, and timers)
known to the servers as well as an overview of their status. This
corresponds to the peers interactive command.
-d Activates output of diagnostic tool files.
INTERNAL COMMANDS
Interactive commands consist of a keyword followed by 0 through 4
arguments. Only as many keyword characters as are needed to identify
the command uniquely need to be entered. The output produced by a com-
mand is normally written to standard output, but output from indivi-
dual files can be written to a file by appending > followed by a
filename.
A number of interactive commands are executed within the ntpq command
itself and do not result in mode 6 NTP requests being transmitted to a
server. The commands are described in the following section.
? [keyword]
A single ? outputs a list of all command keywords that are known
to ntpq. A ? followed by a command keyword outputs information on
the function and synopsis of the command.
timeout milliseconds
Specifies a time limit for responses to server queries. The
default value is 5000 milliseconds. Since ntpq repeats each query
once the time limit is exceeded, the total waiting time is twice
as long as the specified time limit value.
host systemname
Specifies the system to which the subsequent queries are trans-
mitted. A system name or numerical address can be specified as
the systemname.
hostnames yes|no
If yes is specified, system names are displayed in ntpq output.
If no is specified, numerical addresses are output instead of the
system name. The default value is yes, provided that it was not
changed in the command line using the -n option.
Page 2 Reliant UNIX 5.44 Printed 11/98
ntpq(1M) ntpq(1M)
raw Displays remote server responses to query commands as they were
received. The only formatting/interpretation carried out on the
data is the conversion of non-ASCII files into a printable for-
mat.
cooked
Edits the responses to query commands. The values of variables
known to the server are reformatted so that they can be under-
stood more easily by the user. Variables that cannot be inter-
preted by ntpq are indicated by a subsequent ?.
ntpversion 1|2|3
Sets the version number that ntpq uses in NTP packages. This is
set to 3 by default. Please note that mode 6 control messages
(and naturally also the corresponding mode) only exist from NTP
version 2 onwards.
addvars variablename[=value] [,...]
rmvars variablename [,...]
clearvars
The data in mode 6 NTP messages consist of a list of elements in
the following format:
variablename=value
where "=value" is ignored in jobs on the server for read vari-
ables. ntpq administers an internal list in which data to be
incorporated in control messages can be compiled and transmitted
using the readlist and writelist commands described below. Vari-
ables and their optional values can be included in the list by
using the addvars command.
If a number of variables are to be incorporated, the entries in
the list must be separated by commas and the list must not con-
tain any blanks or tabs. The rmvars command can be used to remove
individual variables from the list and the clearvars command can
be used to remove all the variables from the list.
debug more|less|off
Activates/deactivates the internal query command debugging func-
tion.
quit Quits ntpq.
COMMANDS FOR CONTROL MESSAGES
Each partner that is known the server is assigned a 16-bit integral
association ID (association identifier). NTP control messages with
partner variables must identify the partner to which the values belong
using the association ID. Here, 0 is a special association ID that
specifies that the variables are system variables and not partner
variables.
Page 3 Reliant UNIX 5.44 Printed 11/98
ntpq(1M) ntpq(1M)
One or more mode 6 NTP messages are transmitted to the server using
commands for control messages and the returned data is output par-
tially formatted. Most commands output a single message and also wait
for a single response. Exceptions are the peers command by means of
which a pre-programmed sequence of messages is transmitted and the
mreadlist and mreadvar commands.
associations
Requests a list of the association IDs and partner statuses for
the partners of the server queried and outputs this list in
columns. The first column contains the associations numbered from
1, the second column contains the actual association IDs returned
by the server, and the third column contains the status word for
the partner. The subsequent columns contain data that was decoded
from the status word. The data returned by the associations com-
mand is buffered internally in ntpq. The index can be useful in
servers that use association IDs that are difficult for the user
to enter. In this case, the index format can be used as an alter-
native for the following commands for which an association ID
must be specified.
pstatus assocID
Transmits a read status request to the server for the specified
association ID. The returned names and values of the parameter
variables are output.
readvar [assocID] [variablename[=value] [,...]]
Transmits a job to the server to read the specified variables. If
an association is not specified, or specified as 0, the variables
are system variables, otherwise they are partner variables and
the values returned belong to the respective partner. If the
variable list is not specified, the server is forced to return a
default list of variables and values.
rv [assocID] [variablename[=value] [,...]]
An abbreviated form of the readvar command.
writevar assocID variablename=value [,...]
Like readvar but the variables specified here are written, not
read.
readlist [assocID]
Transmits a job to the server to read the variables in the inter-
nal variable list. If no association ID is specified, or speci-
fied as 0, it is presumed that the variables are system vari-
ables. Otherwise they are interpreted as partner variables. If
the internal variable list is empty, a request is transmitted
without data which forces the server to return a default list of
variables and values.
rl [assocID]
An abbreviated form of the readlist command.
Page 4 Reliant UNIX 5.44 Printed 11/98
ntpq(1M) ntpq(1M)
writelist [assocID]
Like readlist with the exception that the variables specified
here are written, not read.
mreadvar fromassocID toassocID [variablename[=value] [,...]]
Like readvar with the exception that the queries for each associ-
ation are executed from the specified range (fromassocID
toassocID). This range must be part of the association list that
was buffered by the last associations command executed.
mrv fromassocID toassocID [variablename[=value] [,...]]
An abbreviated form of the mreadvar command.
mreadlist assocID assocID
Like readlist with the exception that the query for each associa-
tion is executed from the specified range (fromassocID
toassocID). This range must be part of the association list that
was buffered by the last associations command executed.
mrl fromassocID toassocID
An abbreviated form of the mreadlist command.
clockvar [assocID] [variablename[=value] [,...]]
Requests a list of server timer variables. Servers on which a
timer is configured react positively to this request. If the
association ID is not specified or specified as 0, the request
applies to the variables of the server's internal NTP system
clock. Otherwise the association ID is interpreted as the partner
association ID of a timer and the accompanying variables are
displayed. If the variable list is not specified, the server
returns a default list of variables and values.
cv [assocID] [variablename[=value] [,...]]
An abbreviated form of the clockvar command.
peers
Requests a list of server partners and an overview of the sta-
tuses of the individual partners. Included in the overview infor-
mation is the address of the remote partner, the reference ID
(0.0.0.0 if the reference ID is unknown), the stratum of the
remote partner, the partner type (local, unicast, or broadcast),
information on when the last package was received, the polling
interval (in seconds), the accessibility register (in octal for-
mat), and the current message propagation delay, deviation, and
dispersion for the partner (all in seconds). The character on the
left-hand side shows the meaning of these partners in the timer
selection process. The codes mean:
<sp> deleted due to a high stratum and/or negative plausibility
checks;
x time is considered incorrect due to the large difference;
Page 5 Reliant UNIX 5.44 Printed 11/98
ntpq(1M) ntpq(1M)
. selected from the end of the candidate list;
- deleted from the cluster algorithms;
+ incorporated into the end selection group;
# selected for synchronization, however the synchronization
distance exceeds the maximum;
* selected for synchronization;
o selected for synchronization, external timer.
A system name, an IP address or the name of a timer can be specified
in the computer field. Only IP addresses are displayed for the
hostnames no command.
SEE ALSO
ntpdate(1M), ntptrace(1M), xntpd(1M).
Page 6 Reliant UNIX 5.44 Printed 11/98