ntpq(1M) ntpq(1M)
NAME
ntpq - standard Network Time Protocol query program
SYNOPSIS
ntpq [-dinp] [-c command] [host] [...]
DESCRIPTION
The ntpq command is used to query NTP servers which implement
the recommended NTP mode 6 control message format about
current state and to request changes in that state.
USAGE
ntpq may be run either in interactive mode or controlled using
command line arguments. Requests to read and write arbitrary
variables can be assembled, with raw and pretty-printed output
options being available. ntpq can also obtain and print a
list of peers in a common format by sending multiple queries
to the server.
If one or more request options is included on the command line
when ntpq is executed, each of the requests will be sent to
the NTP servers running on each of the hosts given as command
line arguments, or on localhost by default. If no request
options are given, ntpq will attempt to read commands from the
standard input and execute these on the NTP server running on
the first host given on the command line, again defaulting to
localhost when no other host is specified. ntpq will prompt
for commands if the standard input is a terminal device.
ntpq uses NTP mode 6 packets to communicate with the NTP
server, and hence can be used to query any compatable server
on the network which permits it. Note that, since NTP is a
UDP protocol this communication will be somewhat unreliable,
especially over large distances in terms of network topology.
ntpq makes one attempt to retransmit requests, and will time
requests out if the remote host is not heard from within a
suitable time out time.
Options
Specifying a command line option other than -i or -n will
cause the specified query (queries) to be sent to the
indicated host(s) immediately. Otherwise, ntpq will attempt
to read interactive format commands from the standard input.
Copyright 1994 Novell, Inc. Page 1
ntpq(1M) ntpq(1M)
-c The following argument is interpreted as an
interactive format command and is added to the list of
commands to be executed on the specified host(s).
Multiple -c options may be given.
-d Enable debugging, setting the debug level to level 1.
-i Force ntpq to operate in interactive mode. Prompts
will be 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
the peers interactive command.
Internal Commands
Interactive format commands consist of a keyword followed by
zero to four arguments. Only enough characters of the full
keyword to uniquely identify the command need be typed. The
output of a command is normally sent to the standard output,
but optionally the output of individual commands may be sent
to a file by appending a ``>'', followed by a file name, to
the command line.
A number of interactive format commands are executed entirely
within the ntpq program itself and do not result in NTP mode 6
requests being sent to a server. These are described
following.
? [command_keyword]
A ? by itself will print a list of all the command
keywords known to this incarnation of ntpq. A ?
followed by a command keyword will print funcation and
usage information about the command. This command is
probably a better source of information about ntpq than
this manual page.
timeout millseconds
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 will be twice
Copyright 1994 Novell, Inc. Page 2
ntpq(1M) ntpq(1M)
the time out value set.
delay milliseconds
Specify a time interval to be added to timestamps
included in requests which require authentication. This
is used to enable (unreliable) server reconfiguration
over long delay network paths or between machines whose
clocks are unsynchronized. Actually the server does not
now require time stamps in authenticated requests, so
this command may be obsolete.
host hostname
Set the host to which future queries will be sent.
hostname may be either a host name or a numeric address.
poll [#] [verbose]
Poll the current server in client mode. The first
argument is the number of times to poll (default is 1).
The second argument may be given to obtain a more
detailed output of the results. This command is
currently just wishful thinking.
keyid #
This command allows the specification of 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.
passwd
This command prompts you to type in a password (which
will not be echoed) which will be used to authenticate
configuration requests. The password must correspond to
the key configured for use by the NTP server for this
purpose if such requests are to be successful.
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 Causes all output from query commands is printed as
received from the remote server. The only
formatting/interpretation done on the data is to
transform nonascii data into a printable (but barely
understandable) form.
Copyright 1994 Novell, Inc. Page 3
ntpq(1M) ntpq(1M)
cooked
Causes output from query commands to be ``cooked''.
Variables which are recognized by the server will have
their values reformatted for human consumption.
Variables which ntpq thinks should have a decodeable
value but didn't are marked with a trailing ``?''.
ntpversion 1 | 2
Sets the NTP version number which ntpq claims in
packets. Defaults to 2 since mode 6 control messages
(and modes, for that matter) didn't exist in NTP version
1. There appear to be no servers left which demand
version 1.
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 causes some servers to handle
requests slightly differently, and can occasionally
cause problems with fuzzball servers if you turn
authentication on before doing a peer display.
clearvars
addvars variable_name [=value] [,...] rmvars variable_name [,...]
The data carried by NTP mode 6 messages consists of a
list of items of the form variable_name=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 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 not
contain white space. The rmvars command can be used to
remove individual variables from the list, while the
clearlist command removes all variables from the list.
debug more|less|no
Turns internal query program debugging on and off.
Copyright 1994 Novell, Inc. Page 4
ntpq(1M) ntpq(1M)
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 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.
Control message commands result in one or more NTP mode 6
messages being sent 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 command, which
will send a preprogrammed series of messages to obtain the
data it needs, and the mreadlist and mreadvar commands, which
will iterate over a range of associations.
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 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 then of use
when dealing with stupid servers which use association
identifiers which are hard for humans to type, in that
for any subsequent commands which require an association
identifier as an argument, the form &index may be used
as an alternative.
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 (that is,
fuzzballs). Such associations are normally omitted from
the display when the associations command is used, but
are included in the output of lassociations.
Copyright 1994 Novell, Inc. Page 5
ntpq(1M) ntpq(1M)
passociations
Prints 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.
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 fuzzballs.
pstatus assoc_id
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 pidgeon English.
readvar [assoc_id] [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 [assoc_id] [variable_name[=value] [,...]]
An easy-to-type short form for the readvar command.
writevar assoc_id variable_name=value [,...]
Like the readvar request, except the specified variables
are written instead of read.
readlist [assoc_id]
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 given as zero, 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.
Copyright 1994 Novell, Inc. Page 6
ntpq(1M) ntpq(1M)
rl [assoc_id]
An easy-to-type short form of the readlist command.
writelist [assoc_id]
Like the readlist request, except the internal list
variables are written instead of read.
mreadvar assoc_id assoc_id [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 assoc_id assoc_id [variable_name[=value] [,...]]
An easy-to-type short form of the mreadvar command.
mreadlist assoc_id assoc_id
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.
mrl assoc_id assoc_id
An easy-to-type short form of the mreadlist command.
clockvar [assoc_id] [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 will 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 will show the variables of a
particular clock. Omitting the variable list will cause
the server to return a default variable display.
cv [assoc_id] [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 reference ID is unknown),
Copyright 1994 Novell, Inc. Page 7
ntpq(1M) ntpq(1M)
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 ``.'' indicates that this
peer was cast off in the falseticker detection, while a
``+'' indicates that the peer made it through. A ``*''
denotes the peer the server is currently synchronizing
with. 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 which
poorly control the data formats.
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 fuzzball
servers.
opeers
An old form of the peers command with the reference ID
replaced by the local interface address.
REFERENCES
ntpdate(1M), xntpd(1M), xntpdc(1M)
Copyright 1994 Novell, Inc. Page 8