Monitor the NTP daemon and determine its performance
ntpq [-46dinp] [-c command] [host] [...]
- Force DNS resolution of hosts to the IP4 namespace.
- Force DNS resolution of hosts to the IP6 namespace.
- -c command
- Execute the given command on the
specified hosts. You can use multiple -c options.
- Turn on the debugging mode.
- Force ntpq to operate in interactive mode.
Prompts are written to the standard output and commands are read from the
- Print all host addresses in dotted-quad numeric format rather than
converting them to the canonical host names.
- Print a list of peers known to the server, and
a summary of their state. This is equivalent to the
peers interactive command.
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.
||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.
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]
- Print a list of all the command keywords for
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] [...]
rmvars variable_name [...]
- 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.
- 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
- 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.
- 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.
- Exit the ntpq utility.
- 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.
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.
- 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
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 [...]] [...]
cv [assocID] [variable_name [ =
- 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.
- 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
retain state for out-of-spec client associations. Such
associations are normally omitted from the display when the
command is used, but are included in the output of lassociations.
- Print data for all associations, including out-of-spec client
associations, from the internally cached list of associations. This
command differs from passociations.
- 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
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[ ... ]
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.
- An old form of the peers command with the reference identifier
replaced by the local interface address.
- 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.
- 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
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]
- 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] [...]
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
- writelist [assocID]
- Write the internal list of variables. Behave like the
readlist request command.
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
- 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
- - outlyer
- Discarded by the clustering algorithm as an outlyer.
- # candidat
- A survivor, and a candidate for the combining algorithm.
- 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.
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:
- Software version and generation time.
- Processor and kernel identification string.
- Operating system version and release identifier.
- State of the clock discipline state machine. The values are
described in the architecture briefing on the NTP project page linked
- Internal integer used to identify the association currently
designated as the system peer.
- Estimated time error of the system clock measured as an exponential
average of RMS time differences.
- 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.
- 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:
- Autokey enabled
- NIST leapseconds file loaded
- PC identity scheme
- IFF identity scheme
- GQ identity scheme.
- Host name as returned by gethostname().
- NTP filestamp of the host key file.
- 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:
- Has been signed by the server.
- Is trusted.
- Is private.
- Contains errors and shouldn't be trusted.
- NTP filestamp of the NIST leapseconds file.
- NTP timestamp when the host public cryptographic values are
refreshed and signed.
- Host digest/signature scheme name from the OpenSSL library.
- TAI-UTC offset in seconds obtained from the NIST leapseconds table.
The status, srcadr, srcport,
dstadr, dstport, leap, stratum,
precision, rootdelay, rootdispersion,
readh, hmode, pmode, hpoll,
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 code for the most recent packet received. The encoding and
meaning of these codes is given below.
- Estimated time error of the peer clock measured as an exponential
average of RMS time differences.
- 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:
- Current flag bits. This word is the server host status word with
additional bits used by the Autokey state machine.
- Server host name.
- Initial key used by the key list generator in the Autokey protocol.
- Initial index used by the key list generator in the Autokey protocol.
- Server message digest/signature scheme name from the OpenSSL
- NTP timestamp when the last Autokey key list was generated and
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.
- 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
- 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
- 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.
- 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
- 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.
The peers command is nonatomic and may occasionally result
in spurious error messages about invalid associations. Also,
you wait a long time for timeouts, because
the timeout time is a fixed constant, and it assumes the
worst-case scenario. In addition, the program doesn't estimate timeout as
it sends queries to a particular host.