Starts the standard Network Time Protocol (NTP) query program. This command only applies to AIX® 4.2 or later.
ntpq [ -i ] [ -n ] [ -p ] [ -c SubCommand ] [ Host ... ]
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.
| 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. |
| Item | Description |
|---|---|
| Host ... | Specifies the hosts. |
This command returns the following exit values:
| Item | Description |
|---|---|
| 0 | Successful completion. |
| >0 | An error occurred. |
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.
ntpq -intpq -c "delay 1000"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=Valuewhere 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:
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:
The character in the left margin indicates the fate of this peer in the clock selection process:
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. |
| Item | Description |
|---|---|
| /usr/sbin/ntpq | Contains the ntpq command. |