[ Previous | Next | Table of Contents | Index | Library Home |
Legal |
Search ]
Commands Reference, Volume 4
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.
| -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.
|
| Host
...
| Specifies the hosts.
|
This command returns the
following exit values:
| 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
- To start the Network
Time Protocol query program in interactive mode, enter:
ntpq -i
- To add a time interval
of 1000 milliseconds to timestamps, enter:
ntpq -c "delay 1000"
The following subcommands can
only be used while running the ntpq query program.
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: Since 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.
|
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
columns. The first column contains the index numbering the associations
from 1 for internal use. The second column contains the actual
association identifier returned by the server. The third column
contains the status word for the peer. The rest of the 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 enter 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:
- address of the remote peer,
- reference ID (0.0.0.0 for an
unknown reference ID),
- the stratum of the remote peer (a stratum of 16
indicates the remote peer is unsynchronized),
- type of the peer (local, unicast, multicast or
broadcast),
- time the last packet was received, the polling
interval (seconds),
- the polling interval (seconds),
- the reachability register (octal), and
- the 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.
Notes:
- 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 enter 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 enter 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.
|
| /usr/sbin/ntpq
| Contains the ntpq command.
|
Commands: ntpdate, ntptrace, xntpdc
Daemons: xntpd,
[ Previous | Next | Table of Contents | Index |
Library Home |
Legal |
Search ]