`ntpq`

Monitor the NTP daemon and determine its performance

Syntax:

ntpq [-46dinp] [-c command] [host] [...]

Options:

-4: Force DNS resolution of hosts to the IP4 namespace.
-6: 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.
-d: Turn on the debugging mode.
-i: Force ntpq to operate in interactive mode. Prompts are written to the standard output and commands are read from the standard input.
-n: Print all host addresses in dotted-quad numeric format rather than converting them to the canonical host names.
-p: 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.

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] helpl [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 [...] 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 [...]] [...] 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 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.
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] 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] [...] 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 the readlist 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 should not 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.

Caveats:

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.