ntpq4 Daemon

Purpose

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

Syntax

ntpq [-4 -6 -d -i -n -p] [-c command] [host] [...]

Description

The ntpq program is used to monitor the NTP daemon, the ntpd operations, and determine performance. It uses the standard NTP version 3 mode 6 control message formats defined by RFC 1305. The same formats are used in NTP version 4.

The program can be run either in interactive or controlled mode using command line arguments. The raw and printed output options enables you to assemble the requests to read and write arbitrary variables. The ntpq program can also obtain and print a list of peers in a common format by sending multiple queries to the server.

If one or more request options are included in the command line when the ntpq program is executed, each request will be sent to the NTP servers running on the hosts given by the command line arguments, or on localhost by default. If no request options are given, the ntpq utility will attempt to read commands from the standard input and execute them on the NTP server running on the first host given by the command line, again defaulting to localhost when no other host is specified. The ntpq utility will prompt 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 which permits it.

In the instance where a host name is expected, and when you add a -4 qualifier preceding the host name, the utility forces the DNS resolution to the IP version 4 namespace. Similarly, and a -6 qualifier forces DNS resolution to the IP version 6 namespace.

Specifying a command line option other than -i or -n will cause the specified query or queries to be sent to the indicated host or hosts immediately. Otherwise, the ntpq utility will attempt to read interactive format commands from the standard input.

Flags

Item	Description
-4	Forces DNS resolution of the host names on the command line to the IP version 4 namespace.
-6	Forces DNS resolution of the host names on the command line to the IP version 6 namespace.
-c	The following argument is interpreted as an interactive format command and is added to the list of commands to be executed on the specified host or hosts. Multiples of the -c options might be added.
-d	Enables the debugging mode.
-i	Forces the ntpq utility to operate in interactive mode. The results will be written to the standard output and the commands are read from the standard input.
-n	Outputs all host addresses in dotted-quad numeric format rather than converting to the canonical host names.
-p	Prints a list of peers known to the server as well as a summary of their state. This is equivalent to the peers interactive command.

Parameters

Item	Description
Host...	Specifies the hosts.

Exit Status

This command returns the following exit values:

0: Successful completion.
> 0: An error occurred.

Security

Access Control : You must have root authority to run this command.

Auditing Events : N/A

Examples

To start the Network Time Protocol query program in interactive mode, enter:
ntpq -i
To print a list of peers known to the server and the summary of their state, enter:
ntpq -p

Output similar to the following is displayed:

     remote           refid             st  t   when poll reach   delay        offset    jitter

===============================================================================================

ausgsa.austin.ibm.com 9.41.253.167     2 u   19      64  377      285.962   -8.792   2.989

ntpq Internal Commands

Interactive Format Commands

Interactive format commands consist of a keyword followed by a maximum of 4 arguments. You must type only the required number of characters of the keyword to uniquely identify the command. The output of a command is normally sent to the standard output. You can also opt to send the output of individual commands by appending a greater than symbol (>), followed by a file name, to the command line. A number of interactive format commands are executed entirely within the ntpq program and do not send the NTP mode 6 requests to a server.

Item	Description
? [ command_keyword ] or help [ command_keyword ]	A question mark (?) by itself will print a list of all the command keywords known to this incarnation of ntpq. A question mark (?) followed by a command keyword will print function and the use of the command.
addvars variable_name [ = value] [...] or rmvars variable_name [...] or clearvars	The data carried by the NTP mode 6 messages consists of a list of items of the form variable_name = value, where the equals symbol (=) value is ignored, and can be omitted, in requests to the server to read variables. The ntpq program maintains an internal list in which data to be included in control messages can be assembled, and sent using the readlist and writelist commands described below. The addvars command allows variables and their optional values to be added to the list. If more than one variable is to be added, the list must be separated by using commas, and must not contain any white space. The rmvars command can be used to remove individual variables from the list, while the clearlist command removes all variables from the list.
cooked	Causes the output from query commands to be cooked, so that variables which are recognized by the ntpq command will have their values reformatted for human consumption. The ntpq program marks the variables with a trailing question mark symbol (?) when the variable value cannot be decoded.
debug more \| less \| no	Adjusts the level of ntpq debugging. The default is debug no.
delay milliseconds	Specifies a time interval to be added to timestamps included in requests which require authentication. This is used to enable server reconfiguration over long delay network paths or between machines whose clocks are not synchronized.
host hostname	Sets the host to which future queries will be sent. Hostname may be either a host name or a numeric address.
hostnames [yes \| no]	If yes is specified, host names are printed in the information display. If no is specified, numeric addresses are printed. The default is yes, unless modified using the command line -n switch.
keyid keyid	Specifies the key number to be used to authenticate configuration requests. This must correspond to a key number the server has been configured to use for this purpose.
ntpversion 1 \| 2 \| 3 \| 4	Sets the NTP version number which ntpq claims in packets. The default is 2. The mode 6 control messages did not exist in NTP version 1.
passwd	Prompts for a password that will not be echoed, and which will be used to authenticate configuration requests. The password must correspond to the key configured for NTP server for this purpose.
quit	Exits ntpq.
raw	Prints the output of query commands received from the remote server. The only formatting done on the data is transforming non-ASCII data to a printable form.
timeout millseconds	Specifies a timeout period for responses to server queries. The default is 5000 milliseconds. Since ntpq retries each query once after a timeout, the total waiting time for a timeout will be twice the timeout value set.

Control Message Commands

Each association known to an NTP server has a 16 bit integer association identifier. The NTP control messages that carry peer variables must identify the corresponding peer values, which are its association ID. An association ID 0 indicates that the variables are system variables, and their names are drawn from a separate name space.

Control message commands result in one or more NTP mode 6 messages being sent to the server, and cause the data returned to be printed in a format. Most commands currently implemented send a single message and expect a single response. The current exceptions is the peers command, which will send a pre-programmed series of messages to obtain the data it needs, and the mreadlist and mreadvar commands, which will 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 columns. The first column indicates the index numbering of associations from 1. The second column specifies the actual association identifier returned by the server, and the third column indicates the status word for the peer. This is followed by a number of columns containing data decoded from the status word. See the peers command for a decode of the condition field. Note: The data returned by the associations command is cached internally in ntpq. The index in the form &index is used when dealing with servers that use association identifiers wherein the subsequent commands require an association identifier as an argument.
clockvar [assocID] [variable_name [ = value [...]] [...] cv [assocID] [variable_name [ = value [...] ][...]	Requests the server to send a list of the server's clock variables. Servers, which have a radio clock or other external synchronization will respond positively to this. If the association identifier is omitted or is a zero, you are requesting for the system clock variables and will get a positive response from all servers with a clock. If the server treats clocks as pseudo-peers, and hence can possibly have more than one clock connected at once, referencing the appropriate peer association ID will show the variables of a particular clock. Omitting the variable list will cause the server to return a default variable display.
lassociations	Obtains and prints a list of association identifiers and peer statuses for all associations for which the server is maintaining state. This command differs from the associations command only for servers which retain state for out-of-spec client associations (i.e., fuzzballs). Such associations are normally omitted from the display when the associations command is used, but are included in the output of lassociations.
lpassociations	Prints data for all associations, including out-of-spec client associations, from the internally cached list of associations. This command differs from passociations only when dealing with fuzzballs.
lpeers	Similar to R peers, except that a summary of states of all associations that the server is maintaining are printed. This can produce a much longer list of peers from fuzzball servers.
mreadlist assocID assocID mrl assocID assocID	Similar to the readlist command, except that the query is done for a range of (nonzero) association IDs. 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[ ... ]	Similar to the readvar command, except that the query is done for a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent associations command.
opeers	An old form of peers command with the reference ID replaced by the local interface address.
passociations	Displays association data concerning in-spec peers from the internally cached list of associations. This command performs identically to the associations except that it displays the internally stored data rather than making a new query.
peers	Obtains a current list peers of the server, along with a summary of each peer's state. Summary information includes the address of the remote peer, the reference ID (0.0.0.0 if this is unknown), the stratum of the remote peer, the type of the peer (local, unicast, multicast or broadcast), when the last packet was received, the polling interval, in seconds, the reachability register, in octal, and the current estimated delay, offset and dispersion of the peer, all in milliseconds.
pstatus assocID	Sends a read status request to the server for the given association. The names and values of the peer variables returned will be printed. Note that the status word from the header is displayed preceding the variables, both in hexadecimal and in pidgeon English.
readlist [ assocID ] rl [ assocID ]	Requests that the values of the variables in the internal variable list be returned by the server. If the association ID is omitted or is 0 the variables are assumed to be system variables. Otherwise they are treated as peer variables. If the internal variable list is empty a request is sent without data, which should induce the remote server to return a default display.
readvar assocID variable_name [ = value ] [ ...] rv assocID [ variable_name [ = value ] [...]	Requests that the values of the specified variables be returned by the server by sending a read variables request. If the association ID is omitted or is given as zero the variables are system variables, otherwise they are peer variables and the values returned will be those of the corresponding peer. Omitting the variable list will send a request with no data which should induce the server to return a default display. The encoding and meaning of the variables derived from NTPv3 is given in RFC-1305; the encoding and meaning of the additional NTPv4 variables are given later in this page.
writevar assocID variable_name [ = value [ ...]	Similar to the readvar request, except that the specified variables are written.
writelist [ assocID ]	Similar to the readlist request, except that the internal list of variables are written.

Files

Item	Description
`/usr/sbin/ntp4/ntpq4`	Contains the ntpq command. The default symbolic link to NTP version 4 binary from the `/usr/sbin` directory. `/usr/sbin/ntpq --> /usr/sbin/ntp3/ntpq`