ntpq - Network Time Protocol (NTP) monitor program for
xntpd
/usr/bin/ntpq [-inp] [-c command] [host1 host2...]
Forces ntpq to operate in interactive mode. Prompts are
written to the standard output and commands read from the
standard input. This is the default. Outputs all host
addresses in dotted-decimal notation rather than converting
to the canonical host names. Prints 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.
Interprets command as an interactive format command
and adds it to the list of commands to be executed on the
specified host(s). Multiple -c options may be given.
Specifying the -c or -p options sends the specified query
(queries) to the indicated host(s) immediately; localhost
is the default. Otherwise, ntpq attempts to read interactive
format commands from the standard input.
The ntpq program is used to monitor NTP hosts running
xntpd. The program may be run either in interactive mode
or controlled using command line arguments. Requests to
read arbitrary variables can be assembled, with raw and
formatted output options available. The ntpq program 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 xntpd daemons running on each of the hosts
given as command line arguments, or on localhost by
default. If no request options are given, ntpq attempts
to read commands from the standard input and execute these
on the first host given on the command line, defaulting to
localhost when no other host is specified. The ntpq program
will prompt for commands if the standard input is a
terminal device.
The ntpq program uses NTP mode 6 packets to communicate
with the xntpd daemons, and therefore can be used to query
any compatible daemon on the network that permits it.
Note: Since NTP uses the UDP protocol, this communication
will be somewhat unreliable, especially over large network
topologies. The ntpq program makes one attempt to retransmit
requests, and will time out if the remote host is not
heard from within a suitable time.
Interactive Commands [Toc] [Back]
Interactive format commands consist of a keyword followed
by zero or more 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 > (redirect
metacharacter), 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 daemon. These commands
are as follows: A ? by itself prints a list of all
the command keywords known to this version of ntpq. A ?
followed by a command keyword prints function and usage
information about the command. 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. The ntpq
program maintains an internal list in which data to
be included in control messages can be assembled,
and sent using the readlist and writelist commands.
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 separated by commas 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. Normally
ntpq does not authenticate requests unless they are
write requests. The authenticate yes command
causes ntpq to send authentication with all
requests it makes. Authenticated requests cause
some servers to handle requests slightly differently.
To prevent any mishap, do a peer display
before turning on authentication. Reformats variables
that are recognized by the server. Variables
that ntpq does not recognize are marked with a
trailing ?. Adjusts level of ntpq debugging. The
default is off. Specifies a time interval to be
added to timestamps 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. Actually the server does not now
require time stamps in authenticated requests, so
this command may be obsolete. Same as ?. Sets the
host to which future queries will be sent; hostname
may be either a host name or a Internet address. If
hostname is not specified, the current host is
used. If yes is specified, prints host names in
information displays. If no is specified, prints
Internet addresses instead. The default is yes
unless modified using the command line -n option.
Specifies 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. Setsthe authentication key to
either md5 or des. Only md5 is supported in this
implementation. Sets the NTP version number that
ntpq claims in packets. To display the NTP version
that ntpq currently claims, execute ntpversion with
no arguments. Although most servers run version 3
or better, ntpq claims version 2 by default for
backwards compatibility. (Note that Mode 6 control
messages, and modes, for that matter, did not exist
in NTP version 1.) Prompts you to type in a password
(which will not be echoed) that is 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. Polls the current server in
client mode. The first argument is the number of
times to poll (default is 1) while the second argument
may be given to obtain a more detailed output
of the results. Exits ntpq. Prints all output
from query commands as received from the remote
server. The only data formatting performed is to
translate nonascii data into a printable form.
Specifies a timeout period for responses to server
queries. The default is about 5000 milliseconds.
Since ntpq retries each query once after a timeout,
the total waiting time for a timeout will be twice
the timeout value.
Control Message Commands [Toc] [Back]
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.
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.
Obtains and prints a list of association identifiers
and peer status 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 is 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: The
data returned by the associations command is cached internally
in ntpq. The index is then used when dealing with
servers that use association identifiers. For any subsequent
commands which require an association identifier as
an argument, the form &index may be used as an alternative.
An easy-to-type short form of the clocklist command.
Reads the clock variables included in the variable
list. Requests that the server send a list of the clock
variables. Servers that 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 system clock variables and will generally
get a positive response from all servers with a
clock. If the server treats clocks as pseudo-peers, and
can possibly have more than one clock connected at once,
referencing the appropriate peer association ID will show
the variables of a particular clock. If you omit the
variable list, the server returns a default variable display.
An easy-to-type short form of the clockvar command.
Obtains and prints a list of association identifiers and
peer status 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.
Obtains and prints a list of all peers and
clients having the destination address. Prints data for
all associations, including out-of-spec client associations,
from the internally cached list of associations.
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. 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. 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. An easy-to-type
short form of the mreadlist command. An easy-to-type
short form of the mreadvar command. An old form of the
peers command with the reference ID replaced by the local
interface address. 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. 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 refID 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 milliseconds.
The character in the left margin indicates the fate
of this peer in the clock selection process. The
codes are as follows: Indicates the peer was discarded
due to high stratum or failed sanity checks,
or both. Indicates the peer was designated falseticker
by the intersection algorithm. Indicates
that this peer was culled from the end of the candidate
list. Indicates that the peer was discarded
by the clustering algorithm. Indicates that the
peer was included in the final selection set.
Indicates the peer was selected for synchronization,
but distance exceeds the maximum. Indicates
the peer was selected for synchronization. Indicates
the peer was 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 might
fail to work with servers that poorly control the
data formats.
The contents of the host field may be one of four
forms: a host name, an IP address, a reference
clock implementation name with its parameter, or
REFCLK(implementation number, parameter). On hostnames
no only, IP-addresses will be displayed.
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: The
status word from the header is displayed preceding
the variables, both in hexadecimal and in English.
Requests that the server return the values of the
variables in the internal variable list. 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; the remote server should return a default
display. 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 are those of the corresponding
peer. If the variable list is empty, a
request is sent without data; the remote server
should return a default display. An easy-to-type
short form of the readlist command. An
easy-to-type short form for the readvar command.
Prints the variables on the variable list. Prints
the ntpq version number. Like the readlist
request, except the internal list variables are
written instead of read. Like the readvar request,
except the specified variables are written instead
of read.
***Can't find host hostname
Explanation:
The hostname is not in the local /etc/host file.
hostname: timed out, nothing received ***Request
timed out
Explanation:
Check that xntpd is running on the remote host
being queried.
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.
Specifies the command path
Commands: ntpdate(8), xntpd(8), xntpdc(8)
Files: ntp.conf(4)
ntpq(8)
[ Back ] |
