1222 lines
38 KiB
Plaintext
1222 lines
38 KiB
Plaintext
@node ntpq Invocation
|
|
@section Invoking ntpq
|
|
@pindex ntpq
|
|
@cindex standard NTP query program
|
|
@ignore
|
|
#
|
|
# EDIT THIS FILE WITH CAUTION (invoke-ntpq.texi)
|
|
#
|
|
# It has been AutoGen-ed August 14, 2018 at 08:30:02 AM by AutoGen 5.18.5
|
|
# From the definitions ntpq-opts.def
|
|
# and the template file agtexi-cmd.tpl
|
|
@end ignore
|
|
|
|
|
|
The
|
|
@code{ntpq}
|
|
utility program is used to query NTP servers to monitor NTP operations
|
|
and performance, requesting
|
|
information about current state and/or 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.
|
|
The
|
|
@code{ntpq}
|
|
utility 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 is included on the command line
|
|
when
|
|
@code{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 localhost by default.
|
|
If no request options
|
|
are given,
|
|
@code{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 localhost
|
|
when no other host is specified.
|
|
The
|
|
@code{ntpq}
|
|
utility will prompt for
|
|
commands if the standard input is a terminal device.
|
|
|
|
@code{ntpq}
|
|
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.
|
|
Note that since NTP is a UDP protocol
|
|
this communication will be somewhat unreliable, especially over
|
|
large distances in terms of network topology.
|
|
The
|
|
@code{ntpq}
|
|
utility makes
|
|
one attempt to retransmit requests, and will time requests out if
|
|
the remote host is not heard from within a suitable timeout
|
|
time.
|
|
|
|
Note that in contexts where a host name is expected, a
|
|
@code{-4}
|
|
qualifier preceding the host name forces resolution to the IPv4
|
|
namespace, while a
|
|
@code{-6}
|
|
qualifier forces resolution to the IPv6 namespace.
|
|
For examples and usage, see the
|
|
@quotedblleft{}NTP Debugging Techniques@quotedblright{}
|
|
page.
|
|
|
|
Specifying a
|
|
command line option other than
|
|
@code{-i}
|
|
or
|
|
@code{-n}
|
|
will
|
|
cause the specified query (queries) to be sent to the indicated
|
|
host(s) immediately.
|
|
Otherwise,
|
|
@code{ntpq}
|
|
will attempt to read
|
|
interactive format commands from the standard input.
|
|
|
|
@subsubsection Internal Commands
|
|
|
|
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.
|
|
|
|
A
|
|
number of interactive format commands are executed entirely within
|
|
the
|
|
@code{ntpq}
|
|
utility itself and do not result in NTP
|
|
requests being sent to a server.
|
|
These are described following.
|
|
@table @asis
|
|
@item @code{?} @code{[@kbd{command}]}
|
|
@item @code{help} @code{[@kbd{command}]}
|
|
A
|
|
@quoteleft{}?@quoteright{}
|
|
by itself will print a list of all the commands
|
|
known to
|
|
@code{ntpq}
|
|
A
|
|
@quoteleft{}?@quoteright{}
|
|
followed by a command name will print function and usage
|
|
information about the command.
|
|
@item @code{addvars} @kbd{name}@code{[=@kbd{value}]}@code{[,...]}
|
|
@item @code{rmvars} @kbd{name}@code{[,...]}
|
|
@item @code{clearvars}
|
|
@item @code{showvars}
|
|
The arguments to this command consist of a list of
|
|
items of the form
|
|
@kbd{name}@code{[=@kbd{value}]},
|
|
where the
|
|
.No = Ns Ar value
|
|
is ignored, and can be omitted,
|
|
in requests to the server to read variables.
|
|
The
|
|
@code{ntpq}
|
|
utility maintains an internal list in which data to be included in
|
|
messages can be assembled, and displayed or set using the
|
|
@code{readlist}
|
|
and
|
|
@code{writelist}
|
|
commands described below.
|
|
The
|
|
@code{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
|
|
@code{rmvars}
|
|
command can be used to remove individual variables from the list,
|
|
while the
|
|
@code{clearvars}
|
|
command removes all variables from the
|
|
list.
|
|
The
|
|
@code{showvars}
|
|
command displays the current list of optional variables.
|
|
@item @code{authenticate} @code{[@code{yes}|@code{no}]}
|
|
Normally
|
|
@code{ntpq}
|
|
does not authenticate requests unless
|
|
they are write requests.
|
|
The command
|
|
@code{authenticate} @code{yes}
|
|
causes
|
|
@code{ntpq}
|
|
to send authentication with all requests it
|
|
makes.
|
|
Authenticated requests causes some servers to handle
|
|
requests slightly differently.
|
|
The command
|
|
@code{authenticate}
|
|
causes
|
|
@code{ntpq}
|
|
to display whether or not
|
|
it is currently authenticating requests.
|
|
@item @code{cooked}
|
|
Causes output from query commands to be "cooked", so that
|
|
variables which are recognized by
|
|
@code{ntpq}
|
|
will have their
|
|
values reformatted for human consumption.
|
|
Variables which
|
|
@code{ntpq}
|
|
could not decode completely are
|
|
marked with a trailing
|
|
@quoteleft{}?@quoteright{}.
|
|
@item @code{debug} @code{[@code{more}|@code{less}|@code{off}]}
|
|
With no argument, displays the current debug level.
|
|
Otherwise, the debugging level is changed as indicated.
|
|
@item @code{delay} @code{[@kbd{milliseconds}]}
|
|
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 timestamps in authenticated requests,
|
|
so this command may be obsolete.
|
|
Without any arguments, displays the current delay.
|
|
@item @code{drefid} @code{[@code{hash}|@code{ipv4}]}
|
|
Display refids as IPv4 or hash.
|
|
Without any arguments, displays whether refids are shown as IPv4
|
|
addresses or hashes.
|
|
@item @code{exit}
|
|
Exit
|
|
@code{ntpq}
|
|
@item @code{host} @code{[@kbd{name}]}
|
|
Set the host to which future queries will be sent.
|
|
The
|
|
@kbd{name}
|
|
may be either a host name or a numeric address.
|
|
Without any arguments, displays the current host.
|
|
@item @code{hostnames} @code{[@code{yes}|@code{no}]}
|
|
If
|
|
@code{yes}
|
|
is specified, host names are printed in
|
|
information displays.
|
|
If
|
|
@code{no}
|
|
is specified, numeric
|
|
addresses are printed instead.
|
|
The default is
|
|
@code{yes},
|
|
unless
|
|
modified using the command line
|
|
@code{-n}
|
|
switch.
|
|
Without any arguments, displays whether host names or numeric addresses
|
|
are shown.
|
|
@item @code{keyid} @code{[@kbd{keyid}]}
|
|
This command allows the specification of a key number to be
|
|
used to authenticate configuration requests.
|
|
This must correspond
|
|
to the
|
|
@code{controlkey}
|
|
key number the server has been configured to use for this
|
|
purpose.
|
|
Without any arguments, displays the current
|
|
@kbd{keyid}.
|
|
@item @code{keytype} @code{[@kbd{digest}]}
|
|
Specify the digest algorithm to use for authenticating requests, with default
|
|
@code{MD5}.
|
|
If
|
|
@code{ntpq}
|
|
was built with OpenSSL support, and OpenSSL is installed,
|
|
@kbd{digest}
|
|
can be any message digest algorithm supported by OpenSSL.
|
|
If no argument is given, the current
|
|
@code{keytype} @kbd{digest}
|
|
algorithm used is displayed.
|
|
@item @code{ntpversion} @code{[@code{1}|@code{2}|@code{3}|@code{4}]}
|
|
Sets the NTP version number which
|
|
@code{ntpq}
|
|
claims in
|
|
packets.
|
|
Defaults to 3, and 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.
|
|
With no argument, displays the current NTP version that will be used
|
|
when communicating with servers.
|
|
@item @code{passwd}
|
|
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.
|
|
@item @code{poll} @code{[@kbd{n}]} @code{[@code{verbose}]}
|
|
Poll an NTP server in client mode
|
|
@kbd{n}
|
|
times.
|
|
Poll not implemented yet.
|
|
@item @code{quit}
|
|
Exit
|
|
@code{ntpq}
|
|
@item @code{raw}
|
|
Causes all output from query commands is printed as received
|
|
from the remote server.
|
|
The only formating/interpretation done on
|
|
the data is to transform nonascii data into a printable (but barely
|
|
understandable) form.
|
|
@item @code{timeout} @code{[@kbd{milliseconds}]}
|
|
Specify a timeout period for responses to server queries.
|
|
The
|
|
default is about 5000 milliseconds.
|
|
Without any arguments, displays the current timeout period.
|
|
Note that since
|
|
@code{ntpq}
|
|
retries each query once after a timeout, the total waiting time for
|
|
a timeout will be twice the timeout value set.
|
|
@item @code{version}
|
|
Display the version of the
|
|
@code{ntpq}
|
|
program.
|
|
@end table
|
|
|
|
@subsubsection Control Message Commands
|
|
Association ids are used to identify system, peer and clock variables.
|
|
System variables are assigned an association id of zero and system name
|
|
space, while each association is assigned a nonzero association id and
|
|
peer namespace.
|
|
Most control commands send a single message to the server and expect a
|
|
single response message.
|
|
The exceptions are the
|
|
@code{peers}
|
|
command, which sends a series of messages,
|
|
and the
|
|
@code{mreadlist}
|
|
and
|
|
@code{mreadvar}
|
|
commands, which iterate over a range of associations.
|
|
@table @asis
|
|
@item @code{apeers}
|
|
Display a list of peers in the form:
|
|
@example
|
|
[tally]remote refid assid st t when pool reach delay offset jitter
|
|
@end example
|
|
where the output is just like the
|
|
@code{peers}
|
|
command except that the
|
|
@code{refid}
|
|
is displayed in hex format and the association number is also displayed.
|
|
@item @code{associations}
|
|
Display a list of mobilized associations in the form:
|
|
@example
|
|
ind assid status conf reach auth condition last_event cnt
|
|
@end example
|
|
@table @asis
|
|
@item Sy Variable Ta Sy Description
|
|
@item @code{ind} @code{Ta} @code{index} @code{on} @code{this} @code{list}
|
|
@item @code{assid} @code{Ta} @code{association} @code{id}
|
|
@item @code{status} @code{Ta} @code{peer} @code{status} @code{word}
|
|
@item @code{conf} @code{Ta} @code{yes}: @code{No} @code{persistent,} @code{no}: @code{No} @code{ephemeral}
|
|
@item @code{reach} @code{Ta} @code{yes}: @code{No} @code{reachable,} @code{no}: @code{No} @code{unreachable}
|
|
@item @code{auth} @code{Ta} @code{ok}, @code{yes}, @code{bad} @code{No} @code{and} @code{none}
|
|
@item @code{condition} @code{Ta} @code{selection} @code{status} @code{(see} @code{the} @code{select} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
|
|
@item @code{last_event} @code{Ta} @code{event} @code{report} @code{(see} @code{the} @code{event} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
|
|
@item @code{cnt} @code{Ta} @code{event} @code{count} @code{(see} @code{the} @code{count} @code{No} @code{field} @code{of} @code{the} @code{peer} @code{status} @code{word)}
|
|
@end table
|
|
@item @code{authinfo}
|
|
Display the authentication statistics counters:
|
|
time since reset, stored keys, free keys, key lookups, keys not found,
|
|
uncached keys, expired keys, encryptions, decryptions.
|
|
@item @code{clocklist} @code{[@kbd{associd}]}
|
|
@item @code{cl} @code{[@kbd{associd}]}
|
|
Display all clock variables in the variable list for those associations
|
|
supporting a reference clock.
|
|
@item @code{clockvar} @code{[@kbd{associd}]} @code{[@kbd{name}@code{[=@kbd{value}]}]}@code{[,...]}
|
|
@item @code{cv} @code{[@kbd{associd}]} @code{[@kbd{name}@code{[=@kbd{value}]}]}@code{[,...]}
|
|
Display a list of clock variables for those associations supporting a
|
|
reference clock.
|
|
@item @code{:config} @kbd{configuration command line}
|
|
Send the remainder of the command line, including whitespace, to the
|
|
server as a run-time configuration command in the same format as a line
|
|
in the configuration file.
|
|
This command is experimental until further notice and clarification.
|
|
Authentication is of course required.
|
|
@item @code{config-from-file} @kbd{filename}
|
|
Send each line of
|
|
@kbd{filename}
|
|
to the server as run-time configuration commands in the same format as
|
|
lines in the configuration file.
|
|
This command is experimental until further notice and clarification.
|
|
Authentication is required.
|
|
@item @code{ifstats}
|
|
Display status and statistics counters for each local network interface address:
|
|
interface number, interface name and address or broadcast, drop, flag,
|
|
ttl, mc, received, sent, send failed, peers, uptime.
|
|
Authentication is required.
|
|
@item @code{iostats}
|
|
Display network and reference clock I/O statistics:
|
|
time since reset, receive buffers, free receive buffers, used receive buffers,
|
|
low water refills, dropped packets, ignored packets, received packets,
|
|
packets sent, packet send failures, input wakeups, useful input wakeups.
|
|
@item @code{kerninfo}
|
|
Display kernel loop and PPS statistics:
|
|
associd, status, pll offset, pll frequency, maximum error,
|
|
estimated error, kernel status, pll time constant, precision,
|
|
frequency tolerance, pps frequency, pps stability, pps jitter,
|
|
calibration interval, calibration cycles, jitter exceeded,
|
|
stability exceeded, calibration errors.
|
|
As with other ntpq output, times are in milliseconds; very small values
|
|
may be shown as exponentials.
|
|
The precision value displayed is in milliseconds as well, unlike the
|
|
precision system variable.
|
|
@item @code{lassociations}
|
|
Perform the same function as the associations command, except display
|
|
mobilized and unmobilized associations, including all clients.
|
|
@item @code{lopeers} @code{[@code{-4}|@code{-6}]}
|
|
Display a list of all peers and clients showing
|
|
@code{dstadr}
|
|
(associated with the given IP version).
|
|
@item @code{lpassociations}
|
|
Display the last obtained list of associations, including all clients.
|
|
@item @code{lpeers} @code{[@code{-4}|@code{-6}]}
|
|
Display a list of all peers and clients (associated with the given IP version).
|
|
@item @code{monstats}
|
|
Display monitor facility status, statistics, and limits:
|
|
enabled, addresses, peak addresses, maximum addresses,
|
|
reclaim above count, reclaim older than, kilobytes, maximum kilobytes.
|
|
@item @code{mreadlist} @kbd{associdlo} @kbd{associdhi}
|
|
@item @code{mrl} @kbd{associdlo} @kbd{associdhi}
|
|
Perform the same function as the
|
|
@code{readlist}
|
|
command for a range of association ids.
|
|
@item @code{mreadvar} @kbd{associdlo} @kbd{associdhi} @code{[@kbd{name}]}@code{[,...]}
|
|
This range may be determined from the list displayed by any
|
|
command showing associations.
|
|
@item @code{mrv} @kbd{associdlo} @kbd{associdhi} @code{[@kbd{name}]}@code{[,...]}
|
|
Perform the same function as the
|
|
@code{readvar}
|
|
command for a range of association ids.
|
|
This range may be determined from the list displayed by any
|
|
command showing associations.
|
|
@item @code{mrulist} @code{[@code{limited} | @code{kod} | @code{mincount}=@kbd{count} | @code{laddr}=@kbd{localaddr} | @code{sort}=@code{[-]}@kbd{sortorder} | @code{resany}=@kbd{hexmask} | @code{resall}=@kbd{hexmask}]}
|
|
Display traffic counts of the most recently seen source addresses
|
|
collected and maintained by the monitor facility.
|
|
With the exception of
|
|
@code{sort}=@code{[-]}@kbd{sortorder},
|
|
the options filter the list returned by
|
|
@code{ntpd(8)}.
|
|
The
|
|
@code{limited}
|
|
and
|
|
@code{kod}
|
|
options return only entries representing client addresses from which the
|
|
last packet received triggered either discarding or a KoD response.
|
|
The
|
|
@code{mincount}=@kbd{count}
|
|
option filters entries representing less than
|
|
@kbd{count}
|
|
packets.
|
|
The
|
|
@code{laddr}=@kbd{localaddr}
|
|
option filters entries for packets received on any local address other than
|
|
@kbd{localaddr}.
|
|
@code{resany}=@kbd{hexmask}
|
|
and
|
|
@code{resall}=@kbd{hexmask}
|
|
filter entries containing none or less than all, respectively, of the bits in
|
|
@kbd{hexmask},
|
|
which must begin with
|
|
@code{0x}.
|
|
The
|
|
@kbd{sortorder}
|
|
defaults to
|
|
@code{lstint}
|
|
and may be
|
|
@code{addr},
|
|
@code{avgint},
|
|
@code{count},
|
|
@code{lstint},
|
|
or any of those preceded by
|
|
@quoteleft{}-@quoteright{}
|
|
to reverse the sort order.
|
|
The output columns are:
|
|
@table @asis
|
|
@item Column
|
|
Description
|
|
@item @code{lstint}
|
|
Interval in seconds between the receipt of the most recent packet from
|
|
this address and the completion of the retrieval of the MRU list by
|
|
@code{ntpq}
|
|
@item @code{avgint}
|
|
Average interval in s between packets from this address.
|
|
@item @code{rstr}
|
|
Restriction flags associated with this address.
|
|
Most are copied unchanged from the matching
|
|
@code{restrict}
|
|
command, however 0x400 (kod) and 0x20 (limited) flags are cleared unless
|
|
the last packet from this address triggered a rate control response.
|
|
@item @code{r}
|
|
Rate control indicator, either
|
|
a period,
|
|
@code{L}
|
|
or
|
|
@code{K}
|
|
for no rate control response,
|
|
rate limiting by discarding, or rate limiting with a KoD response, respectively.
|
|
@item @code{m}
|
|
Packet mode.
|
|
@item @code{v}
|
|
Packet version number.
|
|
@item @code{count}
|
|
Packets received from this address.
|
|
@item @code{rport}
|
|
Source port of last packet from this address.
|
|
@item @code{remote} @code{address}
|
|
host or DNS name, numeric address, or address followed by
|
|
claimed DNS name which could not be verified in parentheses.
|
|
@end table
|
|
@item @code{opeers} @code{[@code{-4} | @code{-6}]}
|
|
Obtain and print the old-style list of all peers and clients showing
|
|
@code{dstadr}
|
|
(associated with the given IP version),
|
|
rather than the
|
|
@code{refid}.
|
|
@item @code{passociations}
|
|
Perform the same function as the
|
|
@code{associations}
|
|
command,
|
|
except that it uses previously stored data rather than making a new query.
|
|
@item @code{peers}
|
|
Display a list of peers in the form:
|
|
@example
|
|
[tally]remote refid st t when pool reach delay offset jitter
|
|
@end example
|
|
@table @asis
|
|
@item Variable
|
|
Description
|
|
@item @code{[tally]}
|
|
single-character code indicating current value of the
|
|
@code{select}
|
|
field of the
|
|
.Lk decode.html#peer "peer status word"
|
|
@item @code{remote}
|
|
host name (or IP number) of peer.
|
|
The value displayed will be truncated to 15 characters unless the
|
|
@code{ntpq}
|
|
@code{-w}
|
|
option is given, in which case the full value will be displayed
|
|
on the first line, and if too long,
|
|
the remaining data will be displayed on the next line.
|
|
@item @code{refid}
|
|
source IP address or
|
|
.Lk decode.html#kiss "'kiss code"
|
|
@item @code{st}
|
|
stratum: 0 for local reference clocks, 1 for servers with local
|
|
reference clocks, ..., 16 for unsynchronized server clocks
|
|
@item @code{t}
|
|
@code{u}:
|
|
unicast or manycast client,
|
|
@code{b}:
|
|
broadcast or multicast client,
|
|
@code{p}:
|
|
pool source,
|
|
@code{l}:
|
|
local (reference clock),
|
|
@code{s}:
|
|
symmetric (peer),
|
|
@code{A}:
|
|
manycast server,
|
|
@code{B}:
|
|
broadcast server,
|
|
@code{M}:
|
|
multicast server
|
|
@item @code{when}
|
|
time in seconds, minutes, hours, or days since the last packet
|
|
was received, or
|
|
@quoteleft{}-@quoteright{}
|
|
if a packet has never been received
|
|
@item @code{poll}
|
|
poll interval (s)
|
|
@item @code{reach}
|
|
reach shift register (octal)
|
|
@item @code{delay}
|
|
roundtrip delay
|
|
@item @code{offset}
|
|
offset of server relative to this host
|
|
@item @code{jitter}
|
|
offset RMS error estimate.
|
|
@end table
|
|
@item @code{pstats} @kbd{associd}
|
|
Display the statistics for the peer with the given
|
|
@kbd{associd}:
|
|
associd, status, remote host, local address, time last received,
|
|
time until next send, reachability change, packets sent,
|
|
packets received, bad authentication, bogus origin, duplicate,
|
|
bad dispersion, bad reference time, candidate order.
|
|
@item @code{readlist} @code{[@kbd{associd}]}
|
|
@item @code{rl} @code{[@kbd{associd}]}
|
|
Display all system or peer variables.
|
|
If the
|
|
@kbd{associd}
|
|
is omitted, it is assumed to be zero.
|
|
@item @code{readvar} @code{[@kbd{associd} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}]}
|
|
@item @code{rv} @code{[@kbd{associd} @kbd{name}@code{[=@kbd{value}]} @code{[, ...]}]}
|
|
Display the specified system or peer variables.
|
|
If
|
|
@kbd{associd}
|
|
is zero, the variables are from the
|
|
@ref{System Variables}
|
|
name space, otherwise they are from the
|
|
@ref{Peer Variables}
|
|
name space.
|
|
The
|
|
@kbd{associd}
|
|
is required, as the same name can occur in both spaces.
|
|
If no
|
|
@kbd{name}
|
|
is included, all operative variables in the name space are displayed.
|
|
In this case only, if the
|
|
@kbd{associd}
|
|
is omitted, it is assumed to be zero.
|
|
Multiple names are specified with comma separators and without whitespace.
|
|
Note that time values are represented in milliseconds
|
|
and frequency values in parts-per-million (PPM).
|
|
Some NTP timestamps are represented in the format
|
|
@kbd{YYYY}@kbd{MM} @kbd{DD} @kbd{TTTT},
|
|
where
|
|
@kbd{YYYY}
|
|
is the year,
|
|
@kbd{MM}
|
|
the month of year,
|
|
@kbd{DD}
|
|
the day of month and
|
|
@kbd{TTTT}
|
|
the time of day.
|
|
@item @code{reslist}
|
|
Display the access control (restrict) list for
|
|
@code{ntpq}
|
|
Authentication is required.
|
|
@item @code{saveconfig} @kbd{filename}
|
|
Save the current configuration,
|
|
including any runtime modifications made by
|
|
@code{:config}
|
|
or
|
|
@code{config-from-file},
|
|
to the NTP server host file
|
|
@kbd{filename}.
|
|
This command will be rejected by the server unless
|
|
.Lk miscopt.html#saveconfigdir "saveconfigdir"
|
|
appears in the
|
|
@code{ntpd(8)}
|
|
configuration file.
|
|
@kbd{filename}
|
|
can use
|
|
@code{date(1)}
|
|
format specifiers to substitute the current date and time, for
|
|
example,
|
|
@example
|
|
@code{saveconfig} @file{ntp-%Y%m%d-%H%M%S.conf}.
|
|
@end example
|
|
The filename used is stored in system variable
|
|
@code{savedconfig}.
|
|
Authentication is required.
|
|
@item @code{sysinfo}
|
|
Display system operational summary:
|
|
associd, status, system peer, system peer mode, leap indicator,
|
|
stratum, log2 precision, root delay, root dispersion,
|
|
reference id, reference time, system jitter, clock jitter,
|
|
clock wander, broadcast delay, symm. auth. delay.
|
|
@item @code{sysstats}
|
|
Display system uptime and packet counts maintained in the
|
|
protocol module:
|
|
uptime, sysstats reset, packets received, current version,
|
|
older version, bad length or format, authentication failed,
|
|
declined, restricted, rate limited, KoD responses,
|
|
processed for time.
|
|
@item @code{timerstats}
|
|
Display interval timer counters:
|
|
time since reset, timer overruns, calls to transmit.
|
|
@item @code{writelist} @kbd{associd}
|
|
Set all system or peer variables included in the variable list.
|
|
@item @code{writevar} @kbd{associd} @kbd{name}=@kbd{value} @code{[, ...]}
|
|
Set the specified variables in the variable list.
|
|
If the
|
|
@kbd{associd}
|
|
is zero, the variables are from the
|
|
@ref{System Variables}
|
|
name space, otherwise they are from the
|
|
@ref{Peer Variables}
|
|
name space.
|
|
The
|
|
@kbd{associd}
|
|
is required, as the same name can occur in both spaces.
|
|
Authentication is required.
|
|
@end table
|
|
|
|
@subsubsection Status Words and Kiss Codes
|
|
The current state of the operating program is shown
|
|
in a set of status words
|
|
maintained by the system.
|
|
Status information is also available on a per-association basis.
|
|
These words are displayed by the
|
|
@code{readlist}
|
|
and
|
|
@code{associations}
|
|
commands both in hexadecimal and in decoded short tip strings.
|
|
The codes, tips and short explanations are documented on the
|
|
.Lk decode.html "Event Messages and Status Words"
|
|
page.
|
|
The page also includes a list of system and peer messages,
|
|
the code for the latest of which is included in the status word.
|
|
|
|
Information resulting from protocol machine state transitions
|
|
is displayed using an informal set of ASCII strings called
|
|
.Lk decode.html#kiss "kiss codes" .
|
|
The original purpose was for kiss-o'-death (KoD) packets
|
|
sent by the server to advise the client of an unusual condition.
|
|
They are now displayed, when appropriate,
|
|
in the reference identifier field in various billboards.
|
|
|
|
@subsubsection System Variables
|
|
The following system variables appear in the
|
|
@code{readlist}
|
|
billboard.
|
|
Not all variables are displayed in some configurations.
|
|
|
|
@table @asis
|
|
@item Variable
|
|
Description
|
|
@item @code{status}
|
|
.Lk decode.html#sys "system status word"
|
|
@item @code{version}
|
|
NTP software version and build time
|
|
@item @code{processor}
|
|
hardware platform and version
|
|
@item @code{system}
|
|
operating system and version
|
|
@item @code{leap}
|
|
leap warning indicator (0-3)
|
|
@item @code{stratum}
|
|
stratum (1-15)
|
|
@item @code{precision}
|
|
precision (log2 s)
|
|
@item @code{rootdelay}
|
|
total roundtrip delay to the primary reference clock
|
|
@item @code{rootdisp}
|
|
total dispersion to the primary reference clock
|
|
@item @code{refid}
|
|
reference id or
|
|
.Lk decode.html#kiss "kiss code"
|
|
@item @code{reftime}
|
|
reference time
|
|
@item @code{clock}
|
|
date and time of day
|
|
@item @code{peer}
|
|
system peer association id
|
|
@item @code{tc}
|
|
time constant and poll exponent (log2 s) (3-17)
|
|
@item @code{mintc}
|
|
minimum time constant (log2 s) (3-10)
|
|
@item @code{offset}
|
|
combined offset of server relative to this host
|
|
@item @code{frequency}
|
|
frequency drift (PPM) relative to hardware clock
|
|
@item @code{sys_jitter}
|
|
combined system jitter
|
|
@item @code{clk_wander}
|
|
clock frequency wander (PPM)
|
|
@item @code{clk_jitter}
|
|
clock jitter
|
|
@item @code{tai}
|
|
TAI-UTC offset (s)
|
|
@item @code{leapsec}
|
|
NTP seconds when the next leap second is/was inserted
|
|
@item @code{expire}
|
|
NTP seconds when the NIST leapseconds file expires
|
|
@end table
|
|
The jitter and wander statistics are exponentially-weighted RMS averages.
|
|
The system jitter is defined in the NTPv4 specification;
|
|
the clock jitter statistic is computed by the clock discipline module.
|
|
|
|
When the NTPv4 daemon is compiled with the OpenSSL software library,
|
|
additional system variables are displayed,
|
|
including some or all of the following,
|
|
depending on the particular Autokey dance:
|
|
@table @asis
|
|
@item Variable
|
|
Description
|
|
@item @code{host}
|
|
Autokey host name for this host
|
|
@item @code{ident}
|
|
Autokey group name for this host
|
|
@item @code{flags}
|
|
host flags (see Autokey specification)
|
|
@item @code{digest}
|
|
OpenSSL message digest algorithm
|
|
@item @code{signature}
|
|
OpenSSL digest/signature scheme
|
|
@item @code{update}
|
|
NTP seconds at last signature update
|
|
@item @code{cert}
|
|
certificate subject, issuer and certificate flags
|
|
@item @code{until}
|
|
NTP seconds when the certificate expires
|
|
@end table
|
|
@subsubsection Peer Variables
|
|
The following peer variables appear in the
|
|
@code{readlist}
|
|
billboard for each association.
|
|
Not all variables are displayed in some configurations.
|
|
|
|
@table @asis
|
|
@item Variable
|
|
Description
|
|
@item @code{associd}
|
|
association id
|
|
@item @code{status}
|
|
.Lk decode.html#peer "peer status word"
|
|
@item @code{srcadr}
|
|
source (remote) IP address
|
|
@item @code{srcport}
|
|
source (remote) port
|
|
@item @code{dstadr}
|
|
destination (local) IP address
|
|
@item @code{dstport}
|
|
destination (local) port
|
|
@item @code{leap}
|
|
leap indicator (0-3)
|
|
@item @code{stratum}
|
|
stratum (0-15)
|
|
@item @code{precision}
|
|
precision (log2 s)
|
|
@item @code{rootdelay}
|
|
total roundtrip delay to the primary reference clock
|
|
@item @code{rootdisp}
|
|
total root dispersion to the primary reference clock
|
|
@item @code{refid}
|
|
reference id or
|
|
.Lk decode.html#kiss "kiss code"
|
|
@item @code{reftime}
|
|
reference time
|
|
@item @code{rec}
|
|
last packet received time
|
|
@item @code{reach}
|
|
reach register (octal)
|
|
@item @code{unreach}
|
|
unreach counter
|
|
@item @code{hmode}
|
|
host mode (1-6)
|
|
@item @code{pmode}
|
|
peer mode (1-5)
|
|
@item @code{hpoll}
|
|
host poll exponent (log2 s) (3-17)
|
|
@item @code{ppoll}
|
|
peer poll exponent (log2 s) (3-17)
|
|
@item @code{headway}
|
|
headway (see
|
|
.Lk rate.html "Rate Management and the Kiss-o'-Death Packet" )
|
|
@item @code{flash}
|
|
.Lk decode.html#flash "flash status word"
|
|
@item @code{keyid}
|
|
symmetric key id
|
|
@item @code{offset}
|
|
filter offset
|
|
@item @code{delay}
|
|
filter delay
|
|
@item @code{dispersion}
|
|
filter dispersion
|
|
@item @code{jitter}
|
|
filter jitter
|
|
@item @code{bias}
|
|
unicast/broadcast bias
|
|
@item @code{xleave}
|
|
interleave delay (see
|
|
.Lk xleave.html "NTP Interleaved Modes" )
|
|
@end table
|
|
The
|
|
@code{bias}
|
|
variable is calculated when the first broadcast packet is received
|
|
after the calibration volley.
|
|
It represents the offset of the broadcast subgraph relative to the
|
|
unicast subgraph.
|
|
The
|
|
@code{xleave}
|
|
variable appears only for the interleaved symmetric and interleaved modes.
|
|
It represents the internal queuing, buffering and transmission delays
|
|
for the preceding packet.
|
|
|
|
When the NTPv4 daemon is compiled with the OpenSSL software library,
|
|
additional peer variables are displayed, including the following:
|
|
@table @asis
|
|
@item Variable
|
|
Description
|
|
@item @code{flags}
|
|
peer flags (see Autokey specification)
|
|
@item @code{host}
|
|
Autokey server name
|
|
@item @code{flags}
|
|
peer flags (see Autokey specification)
|
|
@item @code{signature}
|
|
OpenSSL digest/signature scheme
|
|
@item @code{initsequence}
|
|
initial key id
|
|
@item @code{initkey}
|
|
initial key index
|
|
@item @code{timestamp}
|
|
Autokey signature timestamp
|
|
@item @code{ident}
|
|
Autokey group name for this association
|
|
@end table
|
|
|
|
@subsubsection Clock Variables
|
|
The following clock variables appear in the
|
|
@code{clocklist}
|
|
billboard for each association with a reference clock.
|
|
Not all variables are displayed in some configurations.
|
|
@table @asis
|
|
@item Variable
|
|
Description
|
|
@item @code{associd}
|
|
association id
|
|
@item @code{status}
|
|
.Lk decode.html#clock "clock status word"
|
|
@item @code{device}
|
|
device description
|
|
@item @code{timecode}
|
|
ASCII time code string (specific to device)
|
|
@item @code{poll}
|
|
poll messages sent
|
|
@item @code{noreply}
|
|
no reply
|
|
@item @code{badformat}
|
|
bad format
|
|
@item @code{baddata}
|
|
bad date or time
|
|
@item @code{fudgetime1}
|
|
fudge time 1
|
|
@item @code{fudgetime2}
|
|
fudge time 2
|
|
@item @code{stratum}
|
|
driver stratum
|
|
@item @code{refid}
|
|
driver reference id
|
|
@item @code{flags}
|
|
driver flags
|
|
@end table
|
|
|
|
This section was generated by @strong{AutoGen},
|
|
using the @code{agtexi-cmd} template and the option descriptions for the @code{ntpq} program.
|
|
This software is released under the NTP license, <http://ntp.org/license>.
|
|
|
|
@menu
|
|
* ntpq usage:: ntpq help/usage (@option{--help})
|
|
* ntpq ipv4:: ipv4 option (-4)
|
|
* ntpq ipv6:: ipv6 option (-6)
|
|
* ntpq command:: command option (-c)
|
|
* ntpq interactive:: interactive option (-i)
|
|
* ntpq numeric:: numeric option (-n)
|
|
* ntpq old-rv:: old-rv option
|
|
* ntpq peers:: peers option (-p)
|
|
* ntpq refid:: refid option (-r)
|
|
* ntpq wide:: wide option (-w)
|
|
* ntpq config:: presetting/configuring ntpq
|
|
* ntpq exit status:: exit status
|
|
@end menu
|
|
|
|
@node ntpq usage
|
|
@subsection ntpq help/usage (@option{--help})
|
|
@cindex ntpq help
|
|
|
|
This is the automatically generated usage text for ntpq.
|
|
|
|
The text printed is the same whether selected with the @code{help} option
|
|
(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print
|
|
the usage text by passing it through a pager program.
|
|
@code{more-help} is disabled on platforms without a working
|
|
@code{fork(2)} function. The @code{PAGER} environment variable is
|
|
used to select the program, defaulting to @file{more}. Both will exit
|
|
with a status code of 0.
|
|
|
|
@exampleindent 0
|
|
@example
|
|
ntpq - standard NTP query program - Ver. 4.2.8p12
|
|
Usage: ntpq [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... [ host ...]
|
|
Flg Arg Option-Name Description
|
|
-4 no ipv4 Force IPv4 name resolution
|
|
- prohibits the option 'ipv6'
|
|
-6 no ipv6 Force IPv6 name resolution
|
|
- prohibits the option 'ipv4'
|
|
-c Str command run a command and exit
|
|
- may appear multiple times
|
|
-d no debug-level Increase debug verbosity level
|
|
- may appear multiple times
|
|
-D Num set-debug-level Set the debug verbosity level
|
|
- may appear multiple times
|
|
-i no interactive Force ntpq to operate in interactive mode
|
|
- prohibits these options:
|
|
command
|
|
peers
|
|
-n no numeric numeric host addresses
|
|
no old-rv Always output status line with readvar
|
|
-p no peers Print a list of the peers
|
|
- prohibits the option 'interactive'
|
|
-r KWd refid Set default display type for S2+ refids
|
|
-w no wide Display the full 'remote' value
|
|
opt version output version information and exit
|
|
-? no help display extended usage information and exit
|
|
-! no more-help extended usage information passed thru pager
|
|
-> opt save-opts save the option state to a config file
|
|
-< Str load-opts load options from a config file
|
|
- disabled as '--no-load-opts'
|
|
- may appear multiple times
|
|
|
|
Options are specified by doubled hyphens and their name or by a single
|
|
hyphen and the flag character.
|
|
|
|
The following option preset mechanisms are supported:
|
|
- reading file $HOME/.ntprc
|
|
- reading file ./.ntprc
|
|
- examining environment variables named NTPQ_*
|
|
|
|
The valid "refid" option keywords are:
|
|
hash ipv4
|
|
or an integer from 0 through 1
|
|
|
|
Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org>
|
|
@end example
|
|
@exampleindent 4
|
|
|
|
@node ntpq ipv4
|
|
@subsection ipv4 option (-4)
|
|
@cindex ntpq-ipv4
|
|
|
|
This is the ``force ipv4 name resolution'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
must not appear in combination with any of the following options:
|
|
ipv6.
|
|
@end itemize
|
|
|
|
Force resolution of following host names on the command line
|
|
to the IPv4 namespace.
|
|
@node ntpq ipv6
|
|
@subsection ipv6 option (-6)
|
|
@cindex ntpq-ipv6
|
|
|
|
This is the ``force ipv6 name resolution'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
must not appear in combination with any of the following options:
|
|
ipv4.
|
|
@end itemize
|
|
|
|
Force resolution of following host names on the command line
|
|
to the IPv6 namespace.
|
|
@node ntpq command
|
|
@subsection command option (-c)
|
|
@cindex ntpq-command
|
|
|
|
This is the ``run a command and exit'' option.
|
|
This option takes a string argument @file{cmd}.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
may appear an unlimited number of times.
|
|
@end itemize
|
|
|
|
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).
|
|
@node ntpq interactive
|
|
@subsection interactive option (-i)
|
|
@cindex ntpq-interactive
|
|
|
|
This is the ``force ntpq to operate in interactive mode'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
must not appear in combination with any of the following options:
|
|
command, peers.
|
|
@end itemize
|
|
|
|
Force @code{ntpq} to operate in interactive mode.
|
|
Prompts will be written to the standard output and
|
|
commands read from the standard input.
|
|
@node ntpq numeric
|
|
@subsection numeric option (-n)
|
|
@cindex ntpq-numeric
|
|
|
|
This is the ``numeric host addresses'' option.
|
|
Output all host addresses in dotted-quad numeric format rather than
|
|
converting to the canonical host names.
|
|
@node ntpq old-rv
|
|
@subsection old-rv option
|
|
@cindex ntpq-old-rv
|
|
|
|
This is the ``always output status line with readvar'' option.
|
|
By default, @code{ntpq} now suppresses the @code{associd=...}
|
|
line that precedes the output of @code{readvar}
|
|
(alias @code{rv}) when a single variable is requested, such as
|
|
@code{ntpq -c "rv 0 offset"}.
|
|
This option causes @code{ntpq} to include both lines of output
|
|
for a single-variable @code{readvar}.
|
|
Using an environment variable to
|
|
preset this option in a script will enable both older and
|
|
newer @code{ntpq} to behave identically in this regard.
|
|
@node ntpq peers
|
|
@subsection peers option (-p)
|
|
@cindex ntpq-peers
|
|
|
|
This is the ``print a list of the peers'' option.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
must not appear in combination with any of the following options:
|
|
interactive.
|
|
@end itemize
|
|
|
|
Print a list of the peers known to the server as well as a summary
|
|
of their state. This is equivalent to the 'peers' interactive command.
|
|
@node ntpq refid
|
|
@subsection refid option (-r)
|
|
@cindex ntpq-refid
|
|
|
|
This is the ``set default display type for s2+ refids'' option.
|
|
This option takes a keyword argument.
|
|
|
|
@noindent
|
|
This option has some usage constraints. It:
|
|
@itemize @bullet
|
|
@item
|
|
This option takes a keyword as its argument.
|
|
The argument sets an enumeration value that can be tested by comparing the option value macro (OPT_VALUE_REFID).
|
|
The available keywords are:
|
|
@example
|
|
hash ipv4
|
|
@end example
|
|
|
|
or their numeric equivalent.@end itemize
|
|
|
|
Set the default display format for S2+ refids.
|
|
@node ntpq wide
|
|
@subsection wide option (-w)
|
|
@cindex ntpq-wide
|
|
|
|
This is the ``display the full 'remote' value'' option.
|
|
Display the full value of the 'remote' value. If this requires
|
|
more than 15 characters, display the full value, emit a newline,
|
|
and continue the data display properly indented on the next line.
|
|
|
|
|
|
@node ntpq config
|
|
@subsection presetting/configuring ntpq
|
|
|
|
Any option that is not marked as @i{not presettable} may be preset by
|
|
loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTPQ} and @code{NTPQ_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of
|
|
the options listed above in upper case and segmented with underscores.
|
|
The @code{NTPQ} variable will be tokenized and parsed like
|
|
the command line. The remaining variables are tested for existence and their
|
|
values are treated like option arguments.
|
|
|
|
|
|
@noindent
|
|
@code{libopts} will search in 2 places for configuration files:
|
|
@itemize @bullet
|
|
@item
|
|
$HOME
|
|
@item
|
|
$PWD
|
|
@end itemize
|
|
The environment variables @code{HOME}, and @code{PWD}
|
|
are expanded and replaced when @file{ntpq} runs.
|
|
For any of these that are plain files, they are simply processed.
|
|
For any that are directories, then a file named @file{.ntprc} is searched for
|
|
within that directory and processed.
|
|
|
|
Configuration files may be in a wide variety of formats.
|
|
The basic format is an option name followed by a value (argument) on the
|
|
same line. Values may be separated from the option name with a colon,
|
|
equal sign or simply white space. Values may be continued across multiple
|
|
lines by escaping the newline with a backslash.
|
|
|
|
Multiple programs may also share the same initialization file.
|
|
Common options are collected at the top, followed by program specific
|
|
segments. The segments are separated by lines like:
|
|
@example
|
|
[NTPQ]
|
|
@end example
|
|
@noindent
|
|
or by
|
|
@example
|
|
<?program ntpq>
|
|
@end example
|
|
@noindent
|
|
Do not mix these styles within one configuration file.
|
|
|
|
Compound values and carefully constructed string values may also be
|
|
specified using XML syntax:
|
|
@example
|
|
<option-name>
|
|
<sub-opt>...<...>...</sub-opt>
|
|
</option-name>
|
|
@end example
|
|
@noindent
|
|
yielding an @code{option-name.sub-opt} string value of
|
|
@example
|
|
"...<...>..."
|
|
@end example
|
|
@code{AutoOpts} does not track suboptions. You simply note that it is a
|
|
hierarchicly valued option. @code{AutoOpts} does provide a means for searching
|
|
the associated name/value pair list (see: optionFindValue).
|
|
|
|
The command line options relating to configuration and/or usage help are:
|
|
|
|
@subsubheading version (-)
|
|
|
|
Print the program version to standard out, optionally with licensing
|
|
information, then exit 0. The optional argument specifies how much licensing
|
|
detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument.
|
|
Only the first letter of the argument is examined:
|
|
|
|
@table @samp
|
|
@item version
|
|
Only print the version. This is the default.
|
|
@item copyright
|
|
Name the copyright usage licensing terms.
|
|
@item verbose
|
|
Print the full copyright usage licensing terms.
|
|
@end table
|
|
|
|
@node ntpq exit status
|
|
@subsection ntpq exit status
|
|
|
|
One of the following exit values will be returned:
|
|
@table @samp
|
|
@item 0 (EXIT_SUCCESS)
|
|
Successful program execution.
|
|
@item 1 (EXIT_FAILURE)
|
|
The operation failed or the command syntax was not valid.
|
|
@item 66 (EX_NOINPUT)
|
|
A specified configuration file could not be loaded.
|
|
@item 70 (EX_SOFTWARE)
|
|
libopts had an internal operational error. Please report
|
|
it to autogen-users@@lists.sourceforge.net. Thank you.
|
|
@end table
|