ChorusOS man pages section 1M: System Management Utilities

ntpq(1M)

NAME

ntpq- standard Network Time Protocol query program

SYNOPSIS

ntpq

-inp

-c

command

host

DESCRIPTION

The ntpq program queries NTP servers which implement the recommended NTP mode 6 control message format, about the current state. This program can also request changes in that state. The program can be run in interactive mode, or it can be controlled using command line arguments.

Requests to read and write arbitrary variables can be assembled, with raw and pretty-printed output options available. By sending multiple queries to the server, ntpq can also obtain and print a list of peers in a common format.

If one or more request option is included on the command line when ntpq is executed, ntpq sends each of the requests to the NTP servers running on each host given as a command line argument. By default, ntpq sends its requests to localhost, if hosts are not included on the command line. If no request options are given, ntpq attempts to read commands from the standard input and execute them on the NTP server running on the first host given on the command line. The ntpq program defaults to localhost if no other host is specified. ntpq will prompt for commands if the standard input is a terminal device.

The ntpq program uses NTP mode 6 packets to communicate with an NTP server. This program can be used to query any compatible server on the network that permits such queries. Since NTP is a UDP protocol, this communication will be somewhat unreliable, especially over large distances. ntpq makes one attempt to retransmit requests; requests timeout if the remote host is not respond within a suitable period.

OPTIONS

Command line options are described below. Specifying a command line option other than -i or -n causes the specified query (queries) to be sent, immediately to the indicated host(s). Otherwise, ntpq attempts to read interactive format commands from standard input.

-c: Interpret the next argument as an interactive format command and add it to the list of commands to be executed on the specified host(s). Multiple -c options may be given.
-i: Operate in interactive mode; write prompts to standard output and read commands from standard input.
-n: Output all host addresses in dotted-quad numeric format rather than converting them to canonical host names.
-p: Print a list of the peers known to the server and a summary of their state. This is equivalent to the peers interactive command.

USAGE

Interactive format commands consist of a keyword followed by up to four arguments. Only enough characters of the full keyword to uniquely identify the command need be typed. Normally, the output of a command is sent to standard output; but this output may be written to a file by appending a `>', followed by a file name, to the command line.

Interactive Commands

A number of interactive format commands are executed entirely within the ntpq program itself. These commands do not result in NTP mode 6 requests being sent to a server. The interactive commands are described below:

? [ command_keyword ]
help [ command_keyword ]: A ? by itself prints a list of all the command keywords known to the current version of ntpq. A ? followed by a command keyword prints function and usage information about the command. This command is an alternative source of information about ntpq to this man page.
addvars variable_name [ = value ] [ ... ]
rmvars variable_name [ ... ]
clearvars: The data carried by NTP mode 6 messages consists of a list of items of the form variable_name = value, where the = 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 should be comma-separated and not contain white space. The rmvars command can be used to remove individual variables from the list, while the clearvars command removes all variables from the list.
authenticate yes | no: Without the authenticate yes command, ntpq does not authenticate requests unless they are write requests. The command authenticate yes causes ntpq to send authentication with all requests it makes. Authenticated requests causes some servers to handle requests slightly differently. You can cause an increased response time if you turn authentication on before doing a peer display.
cooked: Causes output from query commands to be "cooked". The values of variables recognized by the server are reformatted, so that the values can be more easily read. Variables which ntpq thinks should have a decodable value, but do not, are marked with a trailing ?.
debug more|less|off: Turns internal query program debugging on and off.
delay milliseconds: Specifies a time interval to be added to timestamps included in requests which require authentication. This command is used to enable (unreliable) server reconfiguration over long delay network paths or between machines whose clocks are not synchronized. Currently, the server does not require time stamps in authenticated requests so you do not have to use this command.
host hostname: Set the name of the host to which future queries are to be sent. Hostname are either a host name or a numeric address.
hostnames [ yes|no ]: If yes is specified, host names are printed in information displays. If no is given, numeric addresses are printed instead. The default is yes unless modified using the command line -n switch.
keyid keyid: Specify a key number to be used to authenticate configuration requests. This number 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 (defaults is 3). Note that mode 6 control messages (and modes, for that matter) did not exist in NTP version 1. There appear to be no servers left which demand version 1.
quit: Exit ntpq.
passwd: Prompts you to type in a password which will be used to authenticate configuration requests. The password must correspond to the key configured for use by the NTP server for this purpose if such requests are to be successful.
raw: Print all output from query commands exactly as it is received from the remote server. The only formatting/filtering done on the data is to transform non- ASCII data into printable form.
timeout milliseconds: Specifies a time out period for responses to server queries. The default is about 5000 milliseconds. Since ntpq retries each query once after a time out, the total waiting time for a time out is twice the time out value that is set.

Control Message Commands

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. It indicates that the variables are system variables whose names are drawn from a separate name space.

Control message commands send one or more NTP mode 6 messages to the server, and cause the data returned to be printed in some format. Most commands currently implemented send a single message and expect a single response. The current exceptions are the peers, mreadlist and mreadvar commands. The peers command sends a preprogrammed series of messages to obtain the data it needs. The mreadlist and mreadvar commands, iterate over a range of associations.

Control message commands are described below:

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 of these is an index that numbers the associations from 1, for internal use. The second column contains the actual association identifier returned by the server and the third the status word for the peer. This is followed by a number of columns containing data decoded from the status word. Note that the data returned by the associations command is cached internally in ntpq. The index is then of use when dealing with "dumb" servers which use association identifiers that are difficult for humans to type. For any subsequent commands which require an association identifier as an argument, the identifier can be specified by using the form, &index. Here index is taken from the previous list.

clockvar [ assocID ] [ variable_name [ =value ] [ ... ] ][ ... ]

Requests that a list of the server's clock variables be sent. Servers which have a radio clock or other external synchronization respond positively to this. If the association identifier is omitted or zero, the request is for the variables of the "system clock". This request generally gets a positive response from all servers with a clock. Some servers may treat clocks as pseudo-peers and, hence, can possibly have more than one clock connected at once. For these servers, 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.

cv [ assocID ] [ variable_name [ = value ] [ ... ] ][ ... ]

An easy-to-type short form of the clockvar command.

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. 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 only when dealing with servers which retain state for out-of-spec client associations.

lpeers

Like peers, except a summary of all associations for which the server is maintaining state is printed. This produce a longer list of peers from inadequate servers.

mreadlist assocID assocID

Like the readlist command except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent associations command.

mrl assocID assocID

An easy-to-type short form of the mreadlist command.

mreadvar assocID assocID [ variable_name [ = value ] [ ... ] ]

Like the readvar command except the query is done for each of a range of (nonzero) association IDs. This range is determined from the association list cached by the most recent associations command.

mrv assocID assocID [ variable_name [ = value ] [ ... ]]

An easy-to-type short form of the mreadvar command.

opeers

An old form of the peers command with the reference ID replaced by the local interface address.

passociations

Prints 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

Obtains a list of in-spec 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 the ref ID 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
The current estimated delay offset and dispersion of the peer, all in milliseconds.

The character in the left margin indicates the fate of this peer in the clock selection process. The codes mean:

space reject: Discarded as being not reachable, in a sync loop (synchronized to the same server), or at too great a synchronization distance.
x falsetick: Designated falseticker by the intersection algorithm.
. excess: Discarded as not among the first ten peers sorted by synchronization distance and so a poor candidate for further consideration.
- outlyer: Discarded by the clustering algorithm as an outlyer.
+ candidat: Included in the final selection set.
# selected: Selected for synchronization, but not among the first six peers sorted by synchronization distance. This peer can me omitted to conserve resources.
* sys.peer: Declared the system peer. Lends its variables to the system variables.
o pps.peer: Declared the system peer and lends its variables to the system variables. However, the actual system synchronization is derived from a pulse-per-second (PPS) signal, either indirectly via the PPS reference clock driver or directly via microkernel interface.

The flash variable is not defined in the NTP specification, but is included as a valuable debugging aid. It displays the results of the packet sanity checks defined in the NTP specification TEST1 through TEST9. The bits for each test read in increasing sequency from the least significant bit and are defined as follows:

The following TEST1 through TEST4 enumerate procedure errors. The packet timestamps may or may not be believed, but the remaining header data are ignored.

TEST1: Duplicate packet.
TEST2: Bogus packet. It is not a reply to a message previously sent. This can happen when the NTP daemon is restarted and before a peer notices.
TEST3: Not synchronized. One or more timestamp fields are missing. This normally happens when the first packet from a peer is received.
TEST4: Either peer delay or peer dispersion is greater than one second.

The following TEST5 through TEST10 enumerate errors in the packet header. The packet is discarded without inspection of its contents.

TEST5: Cryptographic authentication fails.
TEST6: Peer is not synchronized.
TEST7: Peer stratum is greater than 15. The peer is probably not synchronized.
TEST8: Either root delay or root dispersion is greater than one second.
TEST9: Peer cryptographic authentication fails. Either the key identifier or key is wrong or somebody trashed the packet.
TEST10: Access is denied.

Since the peers command depends on the ability to parse the values in the responses it gets, it may fail to work from time to time with servers which poorly control the data formats.

The contents of the host field may be given in one of four forms. It may be a host name, an IP address, a reference clock implementation name with its parameter or, REFCLK(implementation number, parameter). On "hostnames no" only IP-addresses will be displayed.

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 pigeon English.

readlist [ 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.

rl [ assocID ]

An easy-to-type short form of the readlist command.

readvar assoc 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.

rv assocID [ variable_name [ = value ] [ ... ] ]

An easy-to-type short form for the readvar command.

writevar assocID variable_name=value [ ... ]

Like the readvar request, except the specified variables are written instead of read.

writelist [ assocID ]

Like the readlist request, except the internal list variables are written instead of read.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

BUGS

The peers command is non-atomic. It may occasionally result in spurious error messages about invalid associations occurring and terminating the command.

The timeout value is a fixed constant. As a result, it often waits a long time to timeout, since the fixed value assumes a worst case. The program should improve the time out estimate as it sends queries to a particular host; but it does not.

NOTES

The version of NTP incorporated in ChorusOS is ntp-4.0.99i.

ChorusOS 5.0 Last Revised December 2001