ntpq Daemon for NTPv4

Purpose

Starts the standard Network Time Protocol (NTP) query program.

Syntax

ntpq [ -inp] [ -c command ] [ host ] [...]

Description

Use the ntpq command to monitor the operations of the NTP daemon and determine performance. The ntpq command uses the standard NTP mode 6 control message formats that are defined in Appendix B of the NTP version 3 (NTPv3) specification RFC1305. The NTP version v4 (NTPv4) uses the NTP mode 6 control message format. The description on the ntpq command page is for the NTPv4 variables.

The ntpq command can run either in interactive mode or it can be controlled by using command-line arguments. The ntpq command can assemble requests to read and write arbitrary variables with options for raw and printed output. Additionally, the ntpq command can display a list of peers in a common format by sending multiple queries to the server.

If one or more request options are included when the ntpq command is run, each of the requests is sent to the NTP servers that run on each of the hosts that are specified. If you do not provide any request options, the ntpq command attempts to read commands from the standard input and runs them on the NTP server running on the first specified host.. The ntpq command sends the requests to the NTP server that runs on the local host when no other host is specified. The ntpq command prompts for commands if the standard input is a terminal device.

The ntpq command communicates with the NTP server by using NTP mode 6 packets, which allows to query any compatible server on the network. The NTP operates over UDP, which makes communication unreliable, particularly over long network distances. When the ntpq command attempts to send a request, if no response is received from the remote NTP server within a specified timeout period, it considers the request as timed out.

For more information about NTP debugging techniques, see the NTP Debugging Techniques page.

Flags

A command-line option other than the -i or -n parameter causes the specified query or queries to be sent immediately to the indicated one or more than one host. Otherwise, the ntpq command attempts to read interactive format commands from the standard input.

Table 1. Flags
Item	Description
-4	Forces DNS resolution of hostnames to the Internet Protocol version 4 (IPv4) namespace.
-6	Forces DNS resolution of hostnames to the IP version 6 (IPv6) namespace.
-c `command`	The `command` argument is interpreted as an interactive format command and is added to the list of commands to be run on the specified one or more hosts. You can run multiple -c options.
-d	Enables debugging mode.
-i	Forces the ntpq command to operate in interactive mode. Prompts are written to the standard output and commands are read from the standard input.
-n	Outputs all host addresses in dotted-quad numeric format rather than converting them to the canonical hostnames.
-p	Prints a list of the peers that are known to the server and a summary of their state. This option is equivalent to the -c `peers` option.

ntpq Internal Commands

Interactive commands

Interactive format commands consist of a keyword followed by zero to four arguments. Type only enough characters from the entire keyword to identify the command uniquely. The output of a command is normally sent to the standard output. However, the output of the individual commands can be sent to a file by appending an opening angle bracket (<), followed by a file name, to the command.

The ntpq program executes various interactive commands internally, without sending NTP mode 6 requests to a server. The following list describes the interactive commands.

Table 2. Interactive Commands
Item	Description
? [ `command_keyword` ] or help [ `command_keyword` ]	A question mark (?) prints a list of all the command keywords that are known to the ntpq command. A question mark (?) followed by a command keyword prints the function and use of the command.
addvars `variable_name` [ = `value`] […] rmvars `variable_name` […] clearvars	The NTP mode 6 messages carry data that consists of a list of items in the form `variable_name = value`. In the requests to the server to read variables, the `value` is ignored and can be omitted. The ntpq command maintains an internal list where it assembles data to be included in control messages. It then sends this data by using the readlist and writelist commands. The addvars command allows you to add variables and their optional values to the list. If you need to add more than one variable, the list must be comma-separated and must not contain whitespace. You can use the rmvars command to remove individual variables from the list, and the clearlist command to remove all the variables from the list.
cooked	Cooks the output from query commands, reformatting the values of variables recognized by the ntpq command for human consumption. The ntpq command marks variables that must have a value that can be decoded with a trailing question mark (?).
debug more \| less \| off	Enables or disables the debugging of internal query program.
delay `milliseconds`	Specifies a time interval to be added to timestamps included in the requests that require authentication. This option is used to enable (unreliable) server reconfiguration over long-delay network paths or between machines whose clocks are not synchronized.
host `hostname`	Sets the host to which future queries are sent. The `hostname` specified can be either a hostname or a numeric address.
hostnames [ yes \| no ]	Lists the hostnames or the numeric addresses of the hosts. The hostname command can take the following values: yes: The hostnames are printed. This option is the default value unless it is modified by using the -n option. no: The numeric addresses of the hosts are printed.
keyid `keyid`	Specifies the key ID that is used to authenticate configuration requests. This option must correspond to a key number that the server is configured to use for authentication purposes.
ntpversion 1 \| 2 \| 3 \| 4	Sets the NTP version number to which the ntpq command claims in packets. The default value is 2. Note: The NTP mode 6 control messages do not exist in NTPv1 (NTPv1).
passwd	Prompts to type in a password, which is used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server.
quit	Exits the ntpq command.
raw	Ensures that all the output from query commands is printed as received from the remote server. The only formatting or interpretation that is done on the data is to transform non-ASCII data into a printable form.
timeout `milliseconds`	Specifies a timeout period for responses to the server queries. The default timeout period is 8000 milliseconds. Note: The total waiting time for a timeout is twice the timeout value set as the ntpq command retries each query once after a timeout.

Control message commands

Each peer that is known to an NTP server has a 16-bit integer association identifier that is assigned to it. NTP control messages that carry peer variables must include the association ID of the peer to identify the corresponding peer. An association ID of 0 is special and indicates that the variables are system variables whose names are drawn from a separate namespace.

The control message commands send one or more NTP mode 6 messages to the server and displays the returned data in the same format. Most commands currently send a single message and expect a single response. The exceptions include the peers command, which sends a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which iterate over a range of associations.

Table 3. Control message commands
Item	Description
associations	Prints a list of association identifiers and peer status for in-spec peers of the server that are queried. The list is printed in the following columns: The first column contains the index number that numbers the associations from 1 for internal use. The second column contains the actual association identifier that is returned by the server. The third column contains the status word for the peer. The remaining columns contain data that is decoded from the status word. Note: The data that is returned by the associations command is cached internally in the ntpq query program. When dealing with servers that use difficult association identifiers, use the index as an argument, in the form `&index`, as an alternative to the association identifier.
clockvar [ `assocID` ] [ `variable_name` [ = `Value` […]] […] or cv [ `assocID` ] [ `variable_name` [ = `Value` […]] […]	Sends a request for a list of the server clock variables. Servers with a radio clock or other external synchronization respond positively. If you omit the association identifier or set it to zero, the request targets the system clock variables. In general, you receive a positive response from all the servers with a clock. If the server treats clocks as pseudo-peers, which allows more than one clock to be connected at once, referencing the appropriate peer association ID shows the variables of a specific clock. Omitting the variable list can cause the server to return a default variable display.
lassociations	Displays a list of association identifiers and peer status for each association that the server maintains. This command differs from the associations command only for the servers that retains state for out-of-spec client associations. Such associations are omitted from the display when using the associations command, but they are included in the output of lassociations command.
lpassociations	Displays data for all associations, including out-of-spec client associations, from the internally cached list of associations. The lpassociations command differs from passociations only when dealing with servers with Fuzzball Operating Systems (OS).
lpeers	Displays a summary of all the associations that the server maintains. This command is similar to the peers command. The lpeers command produces a longer list of peers, as the output includes peers from servers with Fuzzball OS.
mreadlist `assocID` `assocID` or mrl `assocID` `assocID`	Displays the values of the specified peer variables for each server in the range of given nonzero association IDs. The association list that is cached by the most recent associations command determines the range. This command is similar to the readlist command.
mreadvar `assocID` `assocID` [ `variable_name` [ = `value`[… ] or mrv `assocID` `assocID` [ `variable_name` [ = `value`[… ]	Displays the values of the specified peer variables in the internal variable list for each server in the range of given nonzero association IDs. The association list that is cached by the most recent associations command determines the range. This command is similar to the readvar command.
opeers	An old form of the peers command, which replaces the reference ID with the local interface address.
passociations	Displays association data that concerns in-spec peers from the internally cached list of associations. The passociations command works like the associations command except that it displays the internally stored data rather than making a new query.
peers	Displays a list of in-spec peers of the server and a summary of the state of each peer. The summary information includes the following data: Address of the remote peer. The reference ID. A reference ID value of `0.0.0.0` is displayed for an unknown reference ID. Stratum of the remote peer. A stratum value of 16 indicates that the remote peer is not synchronized. The type of peer (local, unicast, multicast, or broadcast). The time the last packet was received. Polling interval, in seconds. Reachability register, in octal. Current estimated delay, offset, and dispersion of the peer, all in seconds. The character at the left margin of each line shows the synchronization status of the association and serves as a valuable diagnostic tool.
pstatus `assocID`	Displays the names and values of the peer variables of the server with the specified association ID by sending a read status request. The output displays the header that precedes the variables, both in hexadecimal and in English.
readlist [ `assocID` ] or rl [ `assocID` ]	Displays the values of the peer variables in the internal variable list of the server with the specified association ID. To request the system variables, leave the `assocID` blank or type `0`. If the internal variable list is empty, the server returns a default variable display.
readvar `assocID` `variable_name` [ = `value` ] […] or rv `assocID` [ `variable_name` [ = `value` ] […]	Displays the values of the specified variables of the server with the specified association ID by sending a read variables request. To request the system variables, leave `assocID` blank or type `0`. Omitting the variable list causes the server to return a default variable display. The encoding and meaning of the variables that are derived from NTPv3 is given in RFC-1305.
writevar `assocID` `variable_name` [ = `value` […]	Writes the values of the specified peer variables to the server with the specified association ID by sending a write variables request. This option is similar to the readvar command.
writelist [ `assocID` ]	Writes the values of the peer variables in the internal variable list of the server with the specified association ID. This option is similar to the readlist command.

Parameters

Table 4. Parameters
Item	Description
`Host` ...	Specifies the hosts.

Exit Status

The ntpq command returns the following exit values:

Table 5. Exit status
Item	Description
0	Successful completion.
>0	An error occurred.

Security

Access Control: You must be a part of the system group to run this command.
Auditing Events: N/A
RBAC users: Attention RBAC users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations that are associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To start the NTP query program in interactive mode, enter the following command:
```
ntpq -i
```
To add a time interval of 1000 milliseconds to timestamps, enter the following command:
```
ntpq -c "delay 1000"
```

Files

/usr/sbin/ntp4/ntpq4: Contains the ntpq command.
/usr/sbin/ntpq-->/usr/sbin/ntp4/ntpq4: The default symbolic link to the NTPv4 binary file from the /usr/sbin directory.