ntpq Command

Purpose

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

Syntax

ntpq [ -i ] [ -n ] [ -p ] [ -c SubCommand ] [ Host ... ]

Description

The ntpq command queries the NTP servers running on the hosts specified which implement the recommended NTP mode 6 control message format about current state and can request changes in that state. It runs either in interactive mode or by using command-line arguments. You can make requests to read and write arbitrary variables, and raw and formatted output options are available. The ntpq command can also obtain and print a list of peers in a common format by sending multiple queries to the server.

If you enter the ntpq command with one or more flags, the NTP servers running on each of the hosts specified (or defaults to local host) receive each request. If you do not enter any flags, the ntpq command tries to read commands from standard input and run them on the NTP server running on the first host specified or on the local host by default. It prompts for subcommands if standard input is the terminal.

The ntpq command uses NTP mode 6 packets to communicate with the NTP server and can query any compatible server on the network which permits it.

The ntpq command makes one attempt to retransmit requests, and will time-out requests if the remote host does not respond within a suitable time.

Specifying a flag other than -i or -n sends the queries to the specified hosts immediately. Otherwise, the ntpq command attempts to read interactive format subcommands from standard input.

Flags

Item	Description
-c SubCommand	Specifies an interactive format command. This flag adds SubCommand to the list of commands to run on the specified hosts. You can enter multiple -c flags.
-i	Specifies interactive mode. Standard output displays prompts and standard input reads commands.
-n	Displays all host addresses in dotted decimal format (x.x.x.x) rather than the canonical host names.
-p	Displays a list of the peers known to the server and a summary of their state. Same as using the peers subcommand.

Parameters

Item	Description
Host ...	Specifies the hosts.

Exit Status

This command returns the following exit values:

Item	Description
0	Successful completion.
>0	An error occurred.

Security

Access Control: You must be part of the system group to run this command.

Auditing Events: N/A

Attention RBAC users and Trusted AIX® 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 associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To start the Network Time Protocol query program in interactive mode, type:
```
ntpq -i
```
To add a time interval of 1000 milliseconds to timestamps, type:
```
ntpq -c "delay 1000"
```

ntpq Internal Subcommands

The following subcommands can only be used while running the ntpq query program.

Interactive Format Subcommands

Interactive format subcommands consist of a keyword followed by zero to four arguments. You only need to type enough characters of the full keyword to uniquely identify the subcommand. The output of a subcommand goes to standard output, but you can redirect the output of individual subcommands to a file by appending a > (greater than sign), followed by a file name, to the command line.

Some interactive format subcommands run entirely within the ntpq query program and do not result in sending NTP mode 6 requests to a server.

The data carried by NTP mode 6 messages consists of a list of items of the form:

Variable=Value

where Value is ignored, and can be omitted, in requests to the server to read variables. The ntpq query program maintains an internal list where data to be included in control messages can be assembled and sent using the readlist and writelist control message subcommands.

Item	Description
? [ SubCommand ]	Displays command usage information. When used without SubCommand, displays a list of all the ntpq command keywords. When used with SubCommand, displays function and usage information about the subcommand.
addvars Variable [ =Value ] [ ,... ]	Specifies the variables and their optional values to be added to the internal data list. If adding more than one variable, the list must be separated by commas and not contain spaces.
authenticate yes \| no	Specifies whether to send authentication with all requests or not. Normally the ntpq query program does not authenticate requests unless they are write requests.
clearvars	Removes all variables from the internal data list.
cooked	Displays all results received from the remote server reformatted. A trailing ? (question mark) marks variables that do not have decodable values.
debug more \| less \| off	Turns the ntpq query program debugging on or off. The more and less options control the verbosity of the output. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
delay MilliSeconds	Specifies the time interval to add to timestamps included in requests which require authentication. This subcommand enables unreliable server reconfiguration over long delay network paths or between machines whose clocks are unsynchronized. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
host HostName	Specifies the host to send queries to. HostName may be either a host name or a numeric address. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
hostnames yes \| no	Specifies whether to output the host name (yes) or the numeric address (no). Defaults to yes unless the -n flag is used. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
keyid Number	Specifies the server key number to use to authenticate configuration requests. If you enter this subcommand without an argument, it prints the current setting for this subcommand.
ntpversion 1 \| 2 \| 3	Specifies the NTP version implementation to use when polling its packets. The default is 3. If you enter this subcommand without an argument, it prints the current setting for this subcommand. Note: Mode 6 control messages and modes did not exist in NTP version 1.
passwd	Prompts you to type in the NTP server authentication password to use to authenticate configuration requests.
quit	Exits the ntpq query program.
raw	Displays all results received from the remote server without formatting. Only transforms non-ascii characters into printable form.
rmvars Variable [ =Value ] [ ,... ]	Specifies the variables and their optional values to be removed from the internal data list. If removing more than one variable, the list must be separated by commas and not contain spaces.
timeout MilliSeconds	Specifies the time-out period for responses to server queries. The default is 5000 milliseconds. If you enter this subcommand without an argument, it prints the current setting for this subcommand. Note: Because ntpq query program retries each query once after a time-out, the total waiting time for a time-out is twice the time-out value set.

Control Message Subcommands

Each peer known to an NTP server has a 16-bit integer association identifier assigned to it. NTP control messages which carry peer variables must identify the peer that 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.

The ntpq control message subcommands result in one or more NTP mode 6 messages sent to the server, and outputs the data returned in some format. Most subcommands currently implemented send a single message and expect a single response. The current exceptions are the peers subcommand, which sends a preprogrammed series of messages to obtain the data it needs, and the mreadlist and mreadvar subcommands, which iterate over a range of associations.

Item	Description
associations	Obtains and prints a list of association identifiers and peer statuses for in-spec peers of the server being queried. The list is printed in the following columns: First column contains the index numbering the associations from 1 for internal use. Second column contains the actual association identifier returned by the server. Third column contains the status word for the peer. Remaining columns contain data decoded from the status word. Note: The data returned by the associations subcommand 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 [ =Value ], ... ] or cv [ AssocID ] [ Variable [ =Value ], ... ]	Displays a list of the server's clock variables. Servers which have a radio clock or other external synchronization respond positively to this. To request the system clock variables, leave AssocID blank or type `0`. 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 shows the variables of a particular clock. Omitting the variable list causes the server to return a default variable display.
lassociations	Displays a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This subcommand differs from the associations subcommand only for servers which retain state for out-of-spec client associations.
lpassociations	Displays data for all associations, including out-of-spec client associations, from the internally cached list of associations.
lpeers	Displays a summary of all associations the server maintains state for Similar to the peers subcommand. This may produce a longer list of peers from out-of-spec client servers.
mreadvar AssocID AssocID [ Variable [ =Value ], ... ] or mrv AssocID AssocID [ Variable [ =Value ], ... ]	Displays the values of the specified peer variables for each server in the range of given nonzero association IDs. The association list cached by the most recent associations command determines the range.
mreadlist AssocID AssocID or mrl AssocID AssocID	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 cached by the most recent associations command determines the range.
opeers	An old form of the peers subcommand. Replaces the reference ID with the local interface address.
passociations	Displays association data concerning in-spec peers from the internally cached list of associations. This subcommand works like the associations subcommand 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 each peer's state. Summary information includes the following: Address of the remote peer Reference ID (0.0.0.0 for an unknown reference ID) Stratum of the remote peer (a stratum of 16 indicates the remote peer is unsynchronized) Type of peer (local, unicast, multicast, or broadcast) Time the last packet was received, the polling interval (seconds) Polling interval (seconds) Reachability register (octal) Current estimated delay, offset and dispersion of the peer (milliseconds) The character in the left margin indicates the fate of this peer in the clock selection process: space Discarded due to high stratum and/or failed sanity checks. x Designated falseticker by the intersection algorithm. . Culled from the end of the candidate list. - Discarded by the clustering algorithm. + Included in the final selection set. # Selected for synchronization but distance exceeds maximum. * Selected for synchronization. o Selected for synchronization, pps signal in use. The contents of the host field may be a host name, an IP address, a reference clock implementation name with its parameter or REFCLK (ImplementationNumber, Parameter). Only IP addresses display when using hostnames no. Note: The peers subcommand depends on the ability to parse the values in the responses it gets. It may fail to work from time to time with servers that poorly control the data formats. The peers subcommand is non-atomic and may occasionally result in spurious error messages about invalid associations occurring and terminating the command.
pstatus AssocID	Displays the names and values of the peer variables of the server with the given association by sending a read status request. The output displays the header preceding 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 given association. To request the system variables, leave AssocID blank or type `0`. If the internal variable list is empty, the server returns a default variable display.
readvar [ AssocID ] [ Variable [ =Value ], ... ] or rv [ AssocID ] [ Variable [ =Value ], ... ]	Displays the values of the specified peer variables of the server with the given association 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.
writevar [ AssocID ] [ Variable [ =Value ], ... ]	Writes the values of the specified peer variables to the server with the given association by sending a write variables request.
writelist [ AssocID ]	Writes the values of the peer variables in the internal variable list of the server with the given association.

Files

Item	Description
/usr/sbin/ntpq	Contains the ntpq command.