[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]
Commands Reference, Volume 4
ntpq Command
Purpose
Starts the standard Network Time Protocol (NTP) query
program. This command only applies to AIX 4.2 or later.
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
-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
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 be part of the system group
to run this command.
Auditing Events: N/A
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.
? [ 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 decodeable 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.
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 (seconds)
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 hexidecimal 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
/usr/sbin/ntpq |
Contains the ntpq command. |
Related Information
Commands: ntpdate, ntptrace, xntpdc
Daemons: xntpd,
[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home |
Legal |
Search ]