564 lines
16 KiB
Groff
564 lines
16 KiB
Groff
''' $Header
|
|
'''
|
|
.de Sh
|
|
.br
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Ip
|
|
.br
|
|
.ie \\n.$>=3 .ne \\$3
|
|
.el .ne 3
|
|
.IP "\\$1" \\$2
|
|
..
|
|
'''
|
|
''' Set up \*(-- to give an unbreakable dash;
|
|
''' string Tr holds user defined translation string.
|
|
''' Greek uppercase omega is used as a dummy character.
|
|
'''
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ie n \{\
|
|
.ds -- \(*W-
|
|
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
.ds L" ""
|
|
.ds R" ""
|
|
.ds L' '
|
|
.ds R' '
|
|
'br\}
|
|
.el\{\
|
|
.ds -- \(em\|
|
|
.tr \*(Tr
|
|
.ds L" ``
|
|
.ds R" ''
|
|
.ds L' `
|
|
.ds R' '
|
|
'br\}
|
|
.TH NTPQ 8 LOCAL
|
|
.SH NAME
|
|
ntpq - standard Network Time Protocol query program
|
|
.SH SYNOPSIS
|
|
.B ntpq
|
|
[
|
|
.B -inp
|
|
] [
|
|
.B -c
|
|
.I command
|
|
] [
|
|
.I host
|
|
] [
|
|
.I ...
|
|
]
|
|
.SH DESCRIPTION
|
|
.I Ntpq
|
|
is used to query NTP servers which implement the recommended NTP mode 6
|
|
control message format about current state and to request changes in
|
|
that state. The program may be run either in interactive mode or
|
|
controlled using command line arguments. Requests to read and write
|
|
arbitrary variables can be assembled, with raw and pretty\-printed
|
|
output options being available.
|
|
.I Ntpq
|
|
can also obtain and print a list of peers in a common format by sending
|
|
multiple queries to the server.
|
|
.PP
|
|
If one or more request options is included on the command line when
|
|
.I ntpq
|
|
is executed, each of the requests will be sent to the NTP servers
|
|
running on each of the hosts given as command line arguments, or on
|
|
.I localhost
|
|
by default. If no request options are given,
|
|
.I ntpq
|
|
will attempt to read commands from the standard input and execute these
|
|
on the NTP server running on the first host given on the command line,
|
|
again
|
|
defaulting to
|
|
.I localhost
|
|
when no other host is specified.
|
|
.I Ntpq
|
|
will prompt for commands if the standard input is a terminal device.
|
|
.PP
|
|
.I Ntpq
|
|
uses NTP mode 6 packets to communicate with the NTP server, and hence
|
|
can be used to query any compatable server on the network which permits
|
|
it. Note that since NTP is a UDP protocol this communication will be
|
|
somewhat unreliable, especially over large distances in terms of network
|
|
topology.
|
|
.I Ntpq
|
|
makes one attempt to retransmit requests, and will time requests out if
|
|
the remote host is not heard from within a suitable time out time.
|
|
.PP
|
|
Command line options are described following. Specifying a command line
|
|
option other than
|
|
.B -i
|
|
or
|
|
.B -n
|
|
will cause the specified query (queries) to be sent to the indicated
|
|
host(s) immediately. Otherwise,
|
|
.I ntpq
|
|
will attempt to read interactive format commands from the standard
|
|
input.
|
|
.Ip -c 8
|
|
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(s). Multiple
|
|
.B -c
|
|
options may be given.
|
|
.Ip -i 8
|
|
Force
|
|
.I ntpq
|
|
to operate in interactive mode. Prompts will be written to the standard
|
|
output and commands read from the standard input.
|
|
.Ip -n 8
|
|
Output all host addresses in dotted\-quad numeric format rather than
|
|
converting to the canonical host names.
|
|
.Ip -p 8
|
|
Print a list of the peers known to the server as well as a summary of
|
|
their state. This is equivalent to the \*(L"peers\*(R" interactive
|
|
command.
|
|
.SH INTERNAL COMMANDS
|
|
.PP
|
|
Interactive format commands consist of a keyword followed by zero to
|
|
four arguments. Only enough characters of the full keyword to uniquely
|
|
identify the command need be typed. The output of a command is normally
|
|
sent to the standard output, but optionally the output of individual
|
|
commands may be sent to a file by appending a \*(L">\*(R", followed by a
|
|
file name, to the command line.
|
|
.PP
|
|
A number of interactive format commands are executed entirely within the
|
|
.I ntpq
|
|
program itself and do not result in NTP mode 6 requests being sent to a
|
|
server. These are described following.
|
|
.PP
|
|
.B ?
|
|
[
|
|
.I command_keyword
|
|
]
|
|
.PP
|
|
A \*(L"?\*(R" by itself will print a list of all the command keywords
|
|
known to this incarnation of
|
|
.IR ntpq .
|
|
A \*(L"?\*(R" followed by a command keyword will print function and
|
|
usage information about the command. This command is probably a better
|
|
source of information about
|
|
.I ntpq
|
|
than this manual page.
|
|
.PP
|
|
.B timeout
|
|
.I millseconds
|
|
.PP
|
|
Specify a time out period for responses to server queries. The default
|
|
is about 5000 milliseconds. Note that since
|
|
.I ntpq
|
|
retries each query once after a time out the total waiting time for a
|
|
time out will be twice the time out value set.
|
|
.PP
|
|
.B delay
|
|
.I milliseconds
|
|
.PP
|
|
Specify a time interval to be added to timestamps included in requests
|
|
which require authentication. This is used to enable (unreliable) server
|
|
reconfiguration over long delay network paths or between machines whose
|
|
clocks are unsynchronized. Actually the server does not now require time
|
|
stamps in authenticated requests, so this command may be obsolete.
|
|
.PP
|
|
.B host
|
|
.I hostname
|
|
.PP
|
|
Set the host to which future queries will be sent.
|
|
.I Hostname
|
|
may be either a host name or a numeric
|
|
address.
|
|
.PP
|
|
.B poll
|
|
[
|
|
.I #
|
|
] [
|
|
.B verbose
|
|
]
|
|
.PP
|
|
Poll the current server in client mode. The first argument is the number
|
|
of times to poll (default is 1) while the second argument may be given
|
|
to obtain a more detailed output of the results. This command is
|
|
currently just wishful thinking.
|
|
.PP
|
|
.B keyid
|
|
.I #
|
|
.PP
|
|
This command allows the specification of a 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.
|
|
.PP
|
|
.B passwd
|
|
.PP
|
|
This command prompts you to type in a password (which will not be
|
|
echoed) 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.
|
|
.PP
|
|
.B "hostnames yes|no"
|
|
.PP
|
|
If \*(L"yes\*(R" is specified, host names are printed in information
|
|
displays. If \*(L"no\*(R" is given, numeric addresses are printed
|
|
instead. The default is \*(L"yes\*(R" unless modified using the command
|
|
line
|
|
.B -n
|
|
switch.
|
|
.PP
|
|
.B raw
|
|
.PP
|
|
Causes all output from query commands is printed as received from the
|
|
remote server. The only formating/intepretation done on the data is to
|
|
transform nonascii data into a printable (but barely understandable)
|
|
form.
|
|
.PP
|
|
.B cooked
|
|
.PP
|
|
Causes output from query commands to be \*(L"cooked\*(R". Variables
|
|
which are recognized by the server will have their values reformatted
|
|
for human consumption. Variables which
|
|
.I ntpq
|
|
thinks should have a decodeable value but didn't are marked with a
|
|
trailing \*(L"?\*(R".
|
|
.PP
|
|
.B ntpversion
|
|
.B 1|2|3
|
|
.PP
|
|
Sets the NTP version number which
|
|
.I ntpq
|
|
claims in packets. Defaults to 3, Note that mode 6 control messages (and
|
|
modes, for that matter) didn't exist in NTP version 1. There appear to
|
|
be no servers left which demand version 1.
|
|
.PP
|
|
.B authenticate
|
|
.B yes|no
|
|
.PP
|
|
Normally
|
|
.I ntpq
|
|
does not authenticate requests unless they are write requests. The
|
|
command
|
|
.B authenticate yes
|
|
causes
|
|
.I ntpq
|
|
to send authentication with all requests it makes. Authenticated
|
|
requests causes some servers to handle requests slightly differently,
|
|
and can occasionally melt the CPU in fuzzballs if you turn
|
|
authentication on before doing a peer display.
|
|
.PP
|
|
.B addvars
|
|
.IR <variable_name>[=<value>] [,...]
|
|
.B rmvars
|
|
.IR <variable_name> [,...]
|
|
.B clearvars
|
|
.PP
|
|
The data carried by NTP mode 6 messages consists of a list of items of
|
|
the form
|
|
.IP "" 8
|
|
<variable_name>=<value>
|
|
.PP
|
|
where the \*(L"=<value>\*(R" is ignored, and can be omitted, in requests
|
|
to the server to read variables.
|
|
.I Ntpq
|
|
maintains an internal list in which data to be included in control
|
|
messages can be assembled, and sent using the
|
|
.B readlist
|
|
and
|
|
.B writelist
|
|
commands described below. The
|
|
.B 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
|
|
.B rmvars
|
|
command can be used to remove individual variables from the list, while
|
|
the
|
|
.B clearlist
|
|
command removes all variables from the list.
|
|
.PP
|
|
.B debug
|
|
.I more|less|off
|
|
.PP
|
|
Turns internal query program debugging on and off.
|
|
.PP
|
|
.B quit
|
|
.PP
|
|
Exit
|
|
.IR ntpq .
|
|
.SH CONTROL MESSAGE COMMANDS
|
|
.PP
|
|
Each peer known to an NTP server has a 16 bit integer
|
|
.I association
|
|
.I identifier
|
|
assigned to it. NTP control messages which carry peer variables must
|
|
identify the peer 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.
|
|
.PP
|
|
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 some
|
|
format. Most commands currently implemented send a single message and
|
|
expect a single response. The current exceptions are the
|
|
.B peers
|
|
command, which will send a preprogrammed series of messages to obtain
|
|
the data it needs, and the
|
|
.B mreadlist
|
|
and
|
|
.B mreadvar
|
|
commands, which will iterate over a range of associations.
|
|
.PP
|
|
.B associations
|
|
.PP
|
|
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 numbering the associations from
|
|
1 for internal use, the second 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 \*(L"associations\*(R"
|
|
command is cached internally in
|
|
.IR ntpq .
|
|
The index is then of use when dealing with stupid servers which use
|
|
association identifiers which are hard for humans to type, in that for
|
|
any subsequent commands which require an association identifier as an
|
|
argument, the form
|
|
.I &index
|
|
may be used as an alternative.
|
|
.PP
|
|
.B lassocations
|
|
.PP
|
|
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 \*(L"associations\*(R" 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 \*(L"associations\*(R" command is used, but are included in the
|
|
output of \*(L"lassociations\*(R".
|
|
.PP
|
|
.B passociations
|
|
.PP
|
|
Prints association data concerning in\-spec peers from the internally
|
|
cached list of associations. This command performs identically to the
|
|
\*(L"associations\*(R" except that it displays the internally stored
|
|
data rather than making a new query.
|
|
.PP
|
|
.B lpassociations
|
|
.PP
|
|
Print data for all associations, including out\-of\-spec client
|
|
associations, from the internally cached list of associations. This
|
|
command differs from \*(L"passociations\*(R" only when dealing with
|
|
fuzzballs.
|
|
.PP
|
|
.B pstatus
|
|
.I assocID
|
|
.PP
|
|
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 pidgin English.
|
|
.PP
|
|
.B readvar
|
|
[
|
|
.I assocID
|
|
] [
|
|
.IR <variable_name>[=<value>] [,...]
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B rv
|
|
[
|
|
.I assocID
|
|
] [
|
|
.IR <variable_name>[=<value>] [,...]
|
|
]
|
|
.PP
|
|
An easy\-to\-type short form for the
|
|
.B readvar
|
|
command.
|
|
.PP
|
|
.B writevar
|
|
.I assocID
|
|
.IR <variable_name>=<value> [,...]
|
|
.PP
|
|
Like the
|
|
.B readvar
|
|
request, except the specified variables are written instead of read.
|
|
.PP
|
|
.B readlist
|
|
[
|
|
.I assocID
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B rl
|
|
[
|
|
.I assocID
|
|
]
|
|
.PP
|
|
An easy\-to\-type short form of the
|
|
.B readlist
|
|
command.
|
|
.PP
|
|
.B writelist
|
|
[
|
|
.I assocID
|
|
]
|
|
.PP
|
|
Like the
|
|
.B readlist
|
|
request, except the internal list variables are written instead of read.
|
|
.PP
|
|
.B mreadvar
|
|
.I assocID
|
|
.I assocID
|
|
[
|
|
.IR <variable_name>[=<value>] [,...]
|
|
]
|
|
.PP
|
|
Like the
|
|
.B 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
|
|
.B associations
|
|
command.
|
|
.PP
|
|
.B mrv
|
|
.I assocID
|
|
.I assocID
|
|
[
|
|
.IR <variable_name>[=<value>] [,...]
|
|
]
|
|
.PP
|
|
An easy\-to\-type short form of the
|
|
.B mreadvar
|
|
command.
|
|
.PP
|
|
.B mreadlist
|
|
.I assocID
|
|
.I assocID
|
|
.PP
|
|
Like the
|
|
.B 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
|
|
.B associations
|
|
command.
|
|
.PP
|
|
.B mrl
|
|
.I assocID
|
|
.I assocID
|
|
.PP
|
|
An easy\-to\-type short form of the
|
|
.B mreadlist
|
|
command.
|
|
.PP
|
|
.B clockvar
|
|
[
|
|
.I assocID
|
|
]
|
|
[
|
|
.IR <variable_name>[=<value>] [,...]
|
|
]
|
|
.PP
|
|
Requests that a list of the server's clock variables be sent. Servers
|
|
which have a radio clock or other external synchronization will respond
|
|
positively to this. If the association identifier is omitted or zero the
|
|
request is for the variables of the \*(L"system clock\*(R" and will
|
|
generally 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.
|
|
.PP
|
|
.B cv
|
|
[
|
|
.I assocID
|
|
]
|
|
[
|
|
.IR <variable_name>[=<value>] [,...]
|
|
]
|
|
.PP
|
|
An easy\-to\-type short form of the
|
|
.B clockvar
|
|
command.
|
|
.PP
|
|
.B peers
|
|
.PP
|
|
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 refID 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
|
|
seconds.
|
|
.PP
|
|
The character in the left margin indicates the fate of this peer in the
|
|
clock selection process. The codes mean: <sp> discarded due to high
|
|
stratum and/or failed sanity checks; \*(L"x\*(R" designated falsticker
|
|
by the intersection algorithm; \*(L".\*(R" culled from the end of the
|
|
candidate list; \*(L"-\*(R" discarded by the clustering algorithm;
|
|
\*(L"+\*(R" included in the final selection set; \*(L"#\*(R" selected
|
|
for synchronization but distance exceeds maximum; \*(L"*\*(R" selected
|
|
for synchronization; and \*(L"o\*(R" selected for synchronization, pps
|
|
signal in use.
|
|
.PP
|
|
Note that since the
|
|
.B 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.
|
|
.PP
|
|
The contents of the host field may be one of four forms. It may be a
|
|
host name, an IP address, a reference clock implementation name with its
|
|
parameter or \*(L"REFCLK(<implementation number>, <parameter>)\*(R". On
|
|
\*(L"hostnames no\*(R" only IP\-addresses will be displayed.
|
|
.PP
|
|
.B lpeers
|
|
.PP
|
|
Like
|
|
.BR peers ,
|
|
except a summary of all associations for which the server is maintaining
|
|
state is printed. This can produce a much longer list of peers from
|
|
fuzzball servers.
|
|
.PP
|
|
.B opeers
|
|
.PP
|
|
An old form of the \*(L"peers\*(R" command with the reference ID
|
|
replaced by the local interface address.
|
|
.SH HISTORY
|
|
.PP
|
|
Written by Dennis Ferguson at the University of Toronto.
|
|
.SH BUGS
|
|
.PP
|
|
The
|
|
.B peers
|
|
command is non\-atomic and may occasionally result in spurious error
|
|
messages about invalid associations occurring and terminating the
|
|
command.
|
|
.PP
|
|
The timeout time is a fixed constant, which means you wait a long time
|
|
for time outs since it assumes sort of a worst case. The program should
|
|
improve the time out estimate as it sends queries to a particular host,
|
|
but doesn't.
|