Description:
The ntpq utility monitors the ntpd daemon
operations and determines its performance. It uses the standard NTP mode 6 control
message formats defined in Appendix B of the NTPv3 specification
RFC 1305. The same formats are also used for NTPv4
specification, which has more variables, and are discussed here.
You can run this utility either in interactive mode or in command mode.
Command mode is controlled using command-line arguments.
You can use both raw and pretty-printed options when
assembling requests to read or write. You can also obtain and print a list of peers in a
common format by sending multiple queries to the server.
When you run the ntpq utility by including one or more requests
in the command line, each request is sent to the NTP servers running
on each of the hosts. If no request option is given,
ntpq attempts to read commands from the
standard input and execute them on the NTP server running
on the first host, as given on the command line. If no host is mentioned, it
always defaults to localhost. The ntpq
utility prompts for commands if the standard input is a terminal device.
The ntpq utility uses NTP mode 6 packets to
communicate with the NTP server, and hence can be used to
query any compatible server on the network that permits it. However
it is somewhat unreliable, especially over large distances
in a network topology. The ntpq utility makes
only one attempt to retransmit requests, and times out if the remote
host's response isn't received within a suitable timeout time.
Note:
NTP behaves very similar to UDP (User Datagram Protocol).
In contexts where a host name is expected, a -4
qualifier preceding the host name forces DNS resolution
to the IPv4 namespace, while a -6
qualifier forces DNS resolution to the IPv6 namespace.
Specifying a command line option other than -i or -n
causes the specified queries to be sent to the indicated host(s)
immediately. Otherwise, ntpq attempts to read
interactive format commands from the standard input.
Internal commands
The interactive format commands consist of a keyword followed by zero or more arguments. You can type only enough
characters to uniquely identify the command. The output of a command is
normally sent to the standard output, but you can send the output
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 utility:
- ? [command_keyword] or helpl
[command_keyword]
- Print a list of all the command keywords for the ntpq utility.
If you specify a command keyword, the function followed by a
command keyword, the function and the usage information about the command are printed.
- addvars variable_name [ = value] [...] or
rmvars variable_name [...] or
clearvars
- Allow variables and their optional values to be added to the list maintained internally
by ntpq. If more than one variable is to be added,
the list should be comma-separated and shouldn't contain white space.
You can use the rmvars command to remove
individual variables from the list. The clearlist command removes all variables from the list.
- cooked
- Cause the output from query commands to be "cooked," i.e.,
it reformats the values of the variables for useful purposes. The
ntpq utility marks those variables that aren't decodable with a
trailing ?.
- debug more | less | off
- Turn debugging on and off.
- delay milliseconds
- Specify a time interval. This is to be added to timestamps for requests that require authentication.
- host hostname
- Set the host to which to send future queries. The hostname
may be either a host name or a numeric address.
- hostnames [yes | no]
- Print the host names in the information display when yes is specified.
Print the numeric address when no is specified.
The default is yes, unless modified using the command-line -n option.
- keyid keyid
- Specify the key number to use to authenticate configuration requests.
This must correspond to a key number that the server has been configured to.
- ntpversion 1 | 2 | 3 | 4
- Set the NTP version number that the ntpq utility claims in packets.
The default value is 3. Mode 6 control messages (and modes, for that matter) didn't exist in NTP version 1.
- passwd
- Prompt for a password, which isn't echoed, to use to authenticate configuration requests. The password must
correspond to the key configured for NTP server for this purpose.
- quit
- Exit the ntpq utility.
- raw
- Cause all output from query commands to be printed as received from the remote server.
The only formatting/interpretation done on the data is to transform non-ASCII data into a printable
(but barely understandable) form.
- timeout millseconds
- Specify a timeout period for responses to server queries.
The default is about 5000 milliseconds. Since the ntpq utility retries each
query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.
Control message commands
A 16-bit (integer) association identifier is associated with an NTP server.
When NTP control messages are sent, this association identifier is always
included to identify peers. An association identifier of
0 has special meaning; it indicates that 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,
which are sent to the server, and data returned is always printed in some
format. You will find that most commands 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 required data,
and the mreadlist and mreadvar commands,
which iterate over a range of associations.
- associations
- Obtain and print a list of association identifiers and status for in-spec peers of the NTP servers you query.
The list is printed in columns. The first column is an index,
numbering the associations from 1 for internal use, the second column
is the actual association identifier returned by the server, and the third
column is the status word for the peer.
The following columns contain data decoded from the status word.
The data returned by the associations command is cached
internally in the ntpq utility. The index is useful when you deal
with some servers that have association identifiers which are hard for humans to
type. For any subsequent command that requires an association identifier as an argument,
you can use the form and the index as an alternative.
- clockvar [assocID] [variable_name [ =
value [...]] [...] or
cv [assocID] [variable_name [ =
value [...] ][...]
- Request to send a list of the server's clock variables. Servers
that have radio clock or other external synchronization mechanism respond
positively to this. If the association identifier is omitted or zero, the
request for the variables of the system clock gets a positive response
from all servers with a clock. If the server treats
clocks as pseudo-peers, and has more than one clock connected,
referencing the appropriate peer association identifier show the
variables of a particular clock. Omitting the variable list causes
the server to return a default variable display.
- lassociations
- Obtain and print a list of association identifiers and status of the
peers 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. This
command differs from passociations.
- lpeers
- Print a summary of all associations for which the server is maintaining the state.
This produces a much longer list of peers.
- mreadlist assocID assocID or
mrl assocID assocID
- Behave like the readlist command, except the query
is done for each of a range of (nonzero) association identifiers.
This range is determined from the association list cached by the
most recent associations command.
- mreadvar assocID assocID
[variable_name[ = value[ ... ] or
mrv assocID assocID
[ variable_name [= value[ ... ]
- Behave like the readvar command,
except the query is done for each of a range of (nonzero) association identifiers.
This range is determined from the association list cached by the most recent associations command.
- opeers
- An old form of the peers command with the reference identifier
replaced by the local interface address.
- passociations
- Display 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.
- peers
- Obtain a current list of the peers, along with the state summary. Summary information includes the address
of the remote peer, the reference identifier (0.0.0.0
if this is unknown), the stratum of the remote peer, and the type of the
peer (local, unicast, multicast or broadcast). It also includes the polling interval in
seconds, the register in octal, and the current estimated
delay, offset, and dispersion of the peer, all in milliseconds. The
character at the left margin of each line shows the synchronization
status of the association and is a valuable diagnostic tool. The
encoding and meaning of this character, called the tally code, is given later in this page.
- pstatus assocID
- Send a read-status request to the server for the given association.
Print the names and values of the peer variables that are returned. Note
that the status word from the header is displayed preceding the
variables, both in hexadecimal and in pidgin English.
- readlist [assocID] or rl [assocID]
- Request to return the variables in the internal variable
list of the server. When the association identifier is omitted
or 0, the variables are treated either as system variables, or
peer variables. If the internal variable list is empty,
a request is sent without data that induces the remote server to return a default display.
- readvar assocID variable_name [=value] [...] or
rv assocID [variable_name [= value ] [...]
- Request to return the values of the specified variables by sending a
read variables request. If the association identifier is
omitted or 0, the variables are treated either as system variables or
peer variables that are returned of the corresponding peer.
Omitting the variable list sends a
request with no data, which induces the server to return a default
display. The encoding and meaning of the variables derived from NTPv3 are
given in RFC 1305; the encoding and meaning of the additional NTPv4
variables are given later in this page.
- writevar assocID variable_name [=value[ ...]
- Write the specified variables. Behave like the readvar request command.
- writelist [assocID]
- Write the internal list of variables. Behave like thereadlist request command.
Tally codes
The character in the left margin of the peers billboard, called the
tally code, shows the fate of each association in the clock selection
process. Following is a list of these characters, for which the
peer is:
- space reject
- Discarded as unreachable, synchronized to this server (synch loop) or outrageous synchronization distance.
- x falsetick
- Discarded by the intersection algorithm as a falseticker.
- . excess
- Discarded as not among the first ten peers sorted by
synchronization distance, and probably a poor candidate for further consideration.
- - outlyer
- Discarded by the clustering algorithm as an outlyer.
- # candidat
- A survivor, and a candidate for the combining algorithm.
- selected
- A survivor, but not among the first six peers sorted by synchronization distance.
If the association is ephemeral, it may be demobilized to conserve resources.
- * sys.peer
- Declared as the system peer and lends its variables to the system variables.
- o pps.peer
- Declared as the system peer and lends its variables to
the system variables. The actual system synchronization is
derived from a pulse-per-second (PPS) signal, either indirectly via the
PPS reference clock driver or directly via the kernel interface.
System variables
The status, leap, stratum,
precision, rootdelay, rootdispersion,
refid, reftime, poll, offset,
and frequency variables are described in RFC 1305
specification. Additional NTPv4 system variables include:
- version
- Software version and generation time.
- processor
- Processor and kernel identification string.
- system
- Operating system version and release identifier.
- state
- State of the clock discipline state machine. The values are
described in the architecture briefing on the NTP project page linked from www.ntp.org.
- peer
- Internal integer used to identify the association currently designated as the system peer.
- jitter
- Estimated time error of the system clock measured as an exponential average of RMS time differences.
- stability
- Estimated frequency stability of the system clock measured as an exponential average of RMS frequency differences.
Additional system variables are displayed when the NTPv4 daemon is compiled with the OpenSSL software library.
- flags
- Current flags word bits and message digest algorithm identifier
(NID) in hexadecimal format. The high-order 16 bits of the four-byte word
contain the NID from the OpenSSL library, while the low-order bits are interpreted as follows:
- 0x01
- Autokey enabled
- 0x02
- NIST leapseconds file loaded
- 0x10
- PC identity scheme
- 0x20
- IFF identity scheme
- 0x40
- GQ identity scheme.
- hostname
- Host name as returned by gethostname().
- hostkey
- NTP filestamp of the host key file.
- cert
- A list of certificates held by the host. Each entry includes the
subject, issuer, flags and NTP filestamp in order. The bits are
interpreted as follows, where the certificate:
- 0x01
- Has been signed by the server.
- 0x02
- Is trusted.
- 0x04
- Is private.
- 0x08
- Contains errors and shouldn't be trusted.
- leapseconds
- NTP filestamp of the NIST leapseconds file.
- refresh
- NTP timestamp when the host public cryptographic values are refreshed and signed.
- signature
- Host digest/signature scheme name from the OpenSSL library.
- tai
- TAI-UTC offset in seconds obtained from the NIST leapseconds table.
Peer variables
The status, srcadr, srcport,
dstadr, dstport, leap, stratum,
precision, rootdelay, rootdispersion,
readh, hmode, pmode, hpoll,
ppoll, offset,
delay, dspersion, and reftime variables are
described in the RFC 1305 specification, as are the
timestamps org, rec and xmt.
Additional NTPv4 peer variables include:
- flash
- Flash code for the most recent packet received. The encoding and meaning of these codes is given below.
- jitter
- Estimated time error of the peer clock measured as an exponential
average of RMS time differences.
- unreach
- Value of the counter which records the number of poll intervals since the last valid packet was received.
When the NTPv4 daemon is compiled with the OpenSSL software library,
additional peer variables are displayed, as follows:
- flags
- Current flag bits. This word is the server host status word with
additional bits used by the Autokey state machine.
- hostname
- Server host name.
- initkey
- Initial key used by the key list generator in the Autokey protocol.
- initsequence
- Initial index used by the key list generator in the Autokey protocol.
- signature
- Server message digest/signature scheme name from the OpenSSL software library.
- timestamp
- NTP timestamp when the last Autokey key list was generated and signed.
Flash codes
Use the flash code to debug. It is
displayed in the peer variables list and
shows the results of the original sanity checks
defined in the NTP specification RFC 1305 and additional ones added in NTPv4.
There are 12 tests, designated as TEST1 through TEST12, that perform
in a certain order designed to gain maximum diagnostic
information while protecting against accidental or malicious errors. The
flash variable is initialized to zero as each packet is received.
If, after each set of tests, one or more bits are set, the packet is
discarded. Use these tests for the following tasks:
- TEST1 through TEST3
- Check the packet timestamps from which the offset and delay are calculated.
If any bits are set, the packet is discarded; otherwise, the packet header variables are saved.
- TEST4 and TEST5
- Use for access control and cryptographic authentication.
If any bits are set, the packet is discarded immediately and nothing is changed.
- TEST6 through TEST8
- Check the health of the server. If any bits are set, the packet is discarded; otherwise, the offset and delay
relative to the server are calculated and saved.
- TEST9
- Check the health of the association itself.
If any bits are set, the packet is discarded. Otherwise,
the saved variables are passed to the clock filter and mitigation algorithms.
- TEST10 through TEST12
- Check the authentication state using Autokey public-key cryptography.
If any bits are set and the association has previously been marked reachable, the packet is discarded; otherwise,
the originate and receive timestamps are saved, as required by the
NTP protocol, and processing continues.
The flash bits for each test are defined as follows:
- 0x001 TEST1
- Duplicate packet. The packet is at best a casual retransmission and at worst a malicious reply.
- 0x002 TEST2
- Bogus packet. The packet is not a reply to a message previously sent.
This can happen when the NTP daemon is restarted before somebody else notices.
- 0x004 TEST3
- Unsynchronized. One or more timestamp fields are invalid.
This normally happens when the first packet from a peer is received.
- 0x008 TEST4
- Access is denied.
- 0x010 TEST5
- Failure of cryptographic authentication.
- 0x020TEST6
- Server is unsynchronized. Wind up its clock first.
- 0x040 TEST7
- Server stratum is at the maximum of 15. It is probably unsynchronized and its clock needs to be wound up.
- 0x080 TEST8
- Root delay or dispersion is greater than one second, which is
highly unlikely unless the peer is unsynchronized.
- 0x100 TEST9
- Peer delay or dispersion is greater than one second, which is highly unlikely.
- 0x200 TEST10
- Autokey protocol has detected an authentication failure.
- 0x400 TEST11
- Autokey protocol has not verified the server or peer.
- 0x800 TEST12
- A protocol or configuration error has occurred in the public key
algorithms or a possible intrusion event has been detected.