852 lines
24 KiB
Groff
852 lines
24 KiB
Groff
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 17, 2006
|
|
.Dt NTPQ 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ntpq
|
|
.Nd standard NTP query program
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl inp
|
|
.Op Fl c Ar command
|
|
.Op Ar host
|
|
.Op Ar ...
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is used to monitor NTP daemon
|
|
.Xr ntpd 8
|
|
operations and determine performance.
|
|
It uses the standard NTP mode 6 control message formats
|
|
defined in Appendix B of the NTPv3 specification RFC1305.
|
|
The same formats are used in NTPv4, although some of the variables
|
|
have changed and new ones added.
|
|
The description on this page is for the NTPv4 variables.
|
|
.Pp
|
|
The program can 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
|
|
.Nm
|
|
can also obtain and print a list of peers in a common format
|
|
by sendingmultiple queries to the server.
|
|
.Pp
|
|
If one or more request options is included on the command line
|
|
when
|
|
.Nm
|
|
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,
|
|
.Nm
|
|
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
|
|
.Nm
|
|
utility will prompt for
|
|
commands if the standard input is a terminal device.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility 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
|
|
.Nm
|
|
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.
|
|
.Pp
|
|
For examples and usage, see the
|
|
.Qq NTP Debugging Techniques
|
|
page
|
|
(available as part of the HTML documentation
|
|
provided in
|
|
.Pa /usr/share/doc/ntp ) .
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl 4
|
|
Force DNS resolution of following host names on the command line to the
|
|
IPv4 namespace.
|
|
.It Fl 6
|
|
Force DNS resolution of following host names on the command line to the
|
|
IPv6 namespace.
|
|
.It Fl c
|
|
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
|
|
.Fl c
|
|
options may be given.
|
|
.It Fl d
|
|
Turn on debugging mode.
|
|
.It Fl i
|
|
Force
|
|
.Nm
|
|
to operate in interactive mode.
|
|
Prompts
|
|
will be written to the standard output and commands read from the
|
|
standard input.
|
|
.It Fl n
|
|
Output all host addresses in dotted-quad numeric format rather
|
|
than converting to the canonical host names.
|
|
.It Fl p
|
|
Print a list of the peers known to the server as well as a
|
|
summary of their state.
|
|
This is equivalent to the
|
|
.Ic peers
|
|
interactive command.
|
|
.El
|
|
.Pp
|
|
Note that in contexts where a host name is expected, a
|
|
.Fl 4
|
|
qualifier preceding the host name forces DNS resolution to the
|
|
IPv4 namespace, while a
|
|
.Fl 6
|
|
qualifier forces DNS resolution to the IPv6 namespace.
|
|
Specifying a
|
|
command line option other than
|
|
.Fl i
|
|
or
|
|
.Fl n
|
|
will
|
|
cause the specified query (queries) to be sent to the indicated
|
|
host(s) immediately.
|
|
Otherwise,
|
|
.Nm
|
|
will attempt to read
|
|
interactive format commands from the standard input.
|
|
.Ss "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.
|
|
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
|
|
.Ql \&> ,
|
|
followed by a file name, to the command line.
|
|
A
|
|
number of interactive format commands are executed entirely within
|
|
the
|
|
.Nm
|
|
utility itself and do not result in NTP mode 6
|
|
requests being sent to a server.
|
|
These are described following.
|
|
.Bl -tag -width indent
|
|
.It Ic \&? Op Ar command_keyword
|
|
.It Ic help Op Ar command_keyword
|
|
A
|
|
.Sq Ic \&?
|
|
by itself will print a list of all the command
|
|
keywords known to this incarnation of
|
|
.Nm .
|
|
A
|
|
.Sq Ic \&?
|
|
followed by a command keyword will print function and usage
|
|
information about the command.
|
|
This command is probably a better
|
|
source of information about
|
|
.Nm
|
|
than this manual
|
|
page.
|
|
.It Xo Ic addvars
|
|
.Ar variable_name Ns Op = Ns Ar value ...
|
|
.Xc
|
|
.It Ic rmvars Ar variable_name ...
|
|
.It Ic clearvars
|
|
The data carried by NTP mode 6 messages consists of a list of
|
|
items of the form
|
|
.Ql variable_name=value ,
|
|
where the
|
|
.Ql =value
|
|
is ignored, and can be omitted,
|
|
in requests to the server to read variables.
|
|
The
|
|
.Nm
|
|
utility maintains an internal list in which data to be included in control
|
|
messages can be assembled, and sent using the
|
|
.Ic readlist
|
|
and
|
|
.Ic writelist
|
|
commands described below.
|
|
The
|
|
.Ic 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
|
|
.Ic rmvars
|
|
command can be used to remove individual variables from the list,
|
|
while the
|
|
.Ic clearlist
|
|
command removes all variables from the
|
|
list.
|
|
.It Ic cooked
|
|
Causes output from query commands to be "cooked", so that
|
|
variables which are recognized by
|
|
.Nm
|
|
will have their
|
|
values reformatted for human consumption.
|
|
Variables which
|
|
.Nm
|
|
thinks should have a decodable value but did not are
|
|
marked with a trailing
|
|
.Ql \&? .
|
|
.It Xo Ic debug
|
|
.Cm more |
|
|
.Cm less |
|
|
.Cm off
|
|
.Xc
|
|
Turns internal query program debugging on and off.
|
|
.It Ic delay Ar 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.
|
|
.It Ic host Ar hostname
|
|
Set the host to which future queries will be sent.
|
|
Hostname may
|
|
be either a host name or a numeric address.
|
|
.It Ic hostnames Cm yes | Cm no
|
|
If
|
|
.Cm yes
|
|
is specified, host names are printed in
|
|
information displays.
|
|
If
|
|
.Cm no
|
|
is specified, numeric
|
|
addresses are printed instead.
|
|
The default is
|
|
.Cm yes ,
|
|
unless
|
|
modified using the command line
|
|
.Fl n
|
|
switch.
|
|
.It Ic keyid Ar keyid
|
|
This command specifies the 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.
|
|
.It Xo Ic ntpversion
|
|
.Cm 1 |
|
|
.Cm 2 |
|
|
.Cm 3 |
|
|
.Cm 4
|
|
.Xc
|
|
Sets the NTP version number which
|
|
.Nm
|
|
claims in
|
|
packets.
|
|
Defaults to 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.
|
|
.It Ic passwd
|
|
This command prompts for a password (which will not be echoed) which will
|
|
be used to authenticate configuration requests.
|
|
The password must
|
|
correspond to the key configured for NTP server for this purpose.
|
|
.It Ic quit
|
|
Exit
|
|
.Nm .
|
|
.It Ic raw
|
|
Causes all output from query commands is printed as received
|
|
from the remote server.
|
|
The only formatting/interpretation done on
|
|
the data is to transform nonascii data into a printable (but barely
|
|
understandable) form.
|
|
.It Ic timeout Ar milliseconds
|
|
Specify a timeout period for responses to server queries.
|
|
The
|
|
default is about 5000 milliseconds.
|
|
Note that since
|
|
.Nm
|
|
retries each query once after a timeout, the total waiting time for
|
|
a timeout will be twice the timeout value set.
|
|
.El
|
|
.Ss Control Message Commands
|
|
Each association known to an NTP server has a 16 bit integer association
|
|
identifier.
|
|
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 peers command, which will send a preprogrammed
|
|
series of messages to obtain the data it needs, and the mreadlist
|
|
and mreadvar commands, which will iterate over a range of
|
|
associations.
|
|
.Bl -tag -width indent
|
|
.It Ic 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 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.
|
|
See the peers command
|
|
for a decode of the
|
|
.Sq condition
|
|
field.
|
|
Note that the data
|
|
returned by the
|
|
.Ic associations
|
|
command is cached internally
|
|
in
|
|
.Nm .
|
|
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 and index may be
|
|
used as an alternative.
|
|
.It Xo Ic clockvar Op Ar assocID
|
|
.Oo
|
|
.Ar variable_name Ns Op = Ns Ar value ...
|
|
.Oc
|
|
.Ar ...
|
|
.Xc
|
|
.It Xo Ic cv Op Ar assocID
|
|
.Oo
|
|
.Ar variable_name Ns Op = Ns Ar value ...
|
|
.Oc
|
|
.Ar ...
|
|
.Xc
|
|
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
|
|
.Sq system clock
|
|
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.
|
|
.It Ic 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
|
|
.Ic associations
|
|
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
|
|
.Ic associations
|
|
command is
|
|
used, but are included in the output of
|
|
.Ic lassociations .
|
|
.It Ic lpassociations
|
|
Print data for all associations, including out-of-spec client
|
|
associations, from the internally cached list of associations.
|
|
This
|
|
command differs from
|
|
.Ic passociations
|
|
only when dealing with
|
|
fuzzballs.
|
|
.It Ic lpeers
|
|
Like R 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.
|
|
.It Ic mreadlist Ar assocID Ar assocID
|
|
.It Ic mrl Ar assocID Ar assocID
|
|
Like the
|
|
.Ic 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
|
|
.Ic associations
|
|
command.
|
|
.It Xo Ic mreadvar Ar assocID Ar assocID
|
|
.Oo
|
|
.Ar variable_name Ns Op = Ns Ar value ...
|
|
.Oc
|
|
.Xc
|
|
.It Xo Ic mrv Ar assocID Ar assocID
|
|
.Oo
|
|
.Ar variable_name Ns Op = Ns Ar value ...
|
|
.Oc
|
|
.Xc
|
|
Like the
|
|
.Ic 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
|
|
.Ic associations
|
|
command.
|
|
.It Ic opeers
|
|
An old form of the
|
|
.Ic peers
|
|
command with the reference ID
|
|
replaced by the local interface address.
|
|
.It Ic passociations
|
|
Displays association data concerning in-spec peers from the
|
|
internally cached list of associations.
|
|
This command performs
|
|
identically to the
|
|
.Ic associations
|
|
except that it displays
|
|
the internally stored data rather than making a new query.
|
|
.It Ic peers
|
|
Obtains a current list 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 this 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 milliseconds.
|
|
The character at the left margin of each line shows the
|
|
synchronization status of the association and is a valuable
|
|
diagnostic tool.
|
|
The encoding and meaning of this character,
|
|
called the tally code, is given later in this page.
|
|
.It Ic pstatus Ar 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
|
|
pidgeon English.
|
|
.It Ic readlist Ar assocID
|
|
.It Ic rl Ar 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.
|
|
.It Xo Ic readvar Ar assocID
|
|
.Ar variable_name Ns Op = Ns Ar value
|
|
.Ar ...
|
|
.Xc
|
|
.It Xo Ic rv Ar assocID
|
|
.Ar variable_name Ns Op = Ns Ar value
|
|
.Ar ...
|
|
.Xc
|
|
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.
|
|
The
|
|
encoding and meaning of the variables derived from NTPv3 is given in
|
|
RFC-1305; the encoding and meaning of the additional NTPv4 variables are
|
|
given later in this page.
|
|
.It Xo Ic writevar Ar assocID
|
|
.Ar variable_name Ns Op = Ns Ar value
|
|
.Ar ...
|
|
.Xc
|
|
Like the readvar request, except the specified variables are
|
|
written instead of read.
|
|
.It Ic writelist Op Ar assocID
|
|
Like the readlist request, except the internal list variables
|
|
are written instead of read.
|
|
.El
|
|
.Ss Tally Codes
|
|
The character in the left margin in the
|
|
.Sq peers
|
|
billboard,
|
|
called the tally code, shows the fate of each association
|
|
in the clock selection process.
|
|
Following is a list of these characters, the pigeon used
|
|
in the
|
|
.Ic rv
|
|
command, and a short explanation of the condition revealed.
|
|
.Bl -tag -width indent
|
|
.It space
|
|
.Pq reject
|
|
The peer is discarded as unreachable, synchronized to this server (synch
|
|
loop) or outrageous synchronization distance.
|
|
.It x
|
|
.Pq falsetick
|
|
The peer is discarded by the intersection algorithm as a falseticker.
|
|
.It \&.
|
|
.Pq excess
|
|
The peer is discarded as not among the first ten peers sorted by
|
|
synchronization distance and so is probably a poor candidate for further
|
|
consideration.
|
|
.It \&-
|
|
.Pq outlyer
|
|
The peer is discarded by the clustering algorithm as an outlyer.
|
|
.It \&+
|
|
.Pq candidat
|
|
The peer is a survivor and a candidate for the combining algorithm.
|
|
.It \&#
|
|
.Pq selected
|
|
The peer is a survivor, but not among the first six peers sorted by
|
|
synchronization distance.
|
|
If the association is ephemeral, it may be
|
|
demobilized to conserve resources.
|
|
.It \&*
|
|
.Pq sys.peer
|
|
The peer has been declared the system peer and lends its variables to the
|
|
system variables.
|
|
.It o
|
|
.Pq pps.peer
|
|
The peer has been 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 kernel interface.
|
|
.El
|
|
.Ss System Variables
|
|
The
|
|
.Cm status ,
|
|
.Cm leap ,
|
|
.Cm stratum ,
|
|
.Cm precision ,
|
|
.Cm rootdelay ,
|
|
.Cm rootdispersion ,
|
|
.Cm refid ,
|
|
.Cm reftime ,
|
|
.Cm poll ,
|
|
.Cm offset ,
|
|
and
|
|
.Cm frequency
|
|
variables are described in RFC-1305
|
|
specification.
|
|
Additional NTPv4 system variables include the following.
|
|
.Bl -tag -width indent
|
|
.It version
|
|
Everything you might need to know about the software version and generation
|
|
time.
|
|
.It processor
|
|
The processor and kernel identification string.
|
|
.It system
|
|
The operating system version and release identifier.
|
|
.It state
|
|
The state of the clock discipline state machine.
|
|
The values are described
|
|
in the architecture briefing on the NTP Project page linked from
|
|
www.ntp.org.
|
|
.It peer
|
|
The internal integer used to identify the association currently designated
|
|
the system peer.
|
|
.It jitter
|
|
The estimated time error of the system clock measured as an exponential
|
|
average of RMS time differences.
|
|
.It stability
|
|
The estimated frequency stability of the system clock measured as an
|
|
exponential average of RMS frequency differences.
|
|
.El
|
|
.Pp
|
|
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 dance:
|
|
.Bl -tag -width indent
|
|
.It flags
|
|
The current flags word bits and message digest algorithm identifier (NID)
|
|
in hex format.
|
|
The high order 16 bits of the four-byte word contain the NID
|
|
from the OpenSSL ligrary, while the low-order bits are interpreted as
|
|
follows:
|
|
.Bl -tag -width indent
|
|
.It 0x01
|
|
autokey enabled
|
|
.It 0x02
|
|
NIST leapseconds file loaded
|
|
.It 0x10
|
|
PC identity scheme
|
|
.It 0x20
|
|
IFF identity scheme
|
|
.It 0x40
|
|
GQ identity scheme
|
|
.El
|
|
.It hostname
|
|
The name of the host as returned by the Unix
|
|
.Fn gethostname
|
|
library
|
|
function.
|
|
.It hostkey
|
|
The NTP filestamp of the host key file.
|
|
.It cert
|
|
A list of certificates held by the host.
|
|
Each entry includes the subject,
|
|
issuer, flags and NTP filestamp in order.
|
|
The bits are interpreted as
|
|
follows:
|
|
.Bl -tag -width indent
|
|
.It 0x01
|
|
certificate has been signed by the server
|
|
.It 0x02
|
|
certificate is trusted
|
|
.It 0x04
|
|
certificate is private
|
|
.It 0x08
|
|
certificate contains errors and should not be trusted
|
|
.El
|
|
.It leapseconds
|
|
The NTP filestamp of the NIST leapseconds file.
|
|
.It refresh
|
|
The NTP timestamp when the host public cryptographic values were refreshed
|
|
and signed.
|
|
.It signature
|
|
The host digest/signature scheme name from the OpenSSL library.
|
|
.It tai
|
|
The TAI-UTC offset in seconds obtained from the NIST leapseconds table.
|
|
.El
|
|
.Ss Peer Variables
|
|
The
|
|
.Cm status ,
|
|
.Cm srcadr ,
|
|
.Cm srcport ,
|
|
.Cm dstadr ,
|
|
.Cm dstport ,
|
|
.Cm leap ,
|
|
.Cm stratum ,
|
|
.Cm precision ,
|
|
.Cm rootdelay ,
|
|
.Cm rootdispersion ,
|
|
.Cm readh ,
|
|
.Cm hmode ,
|
|
.Cm pmode ,
|
|
.Cm hpoll ,
|
|
.Cm ppoll ,
|
|
.Cm offset ,
|
|
.Cm delay ,
|
|
.Cm dspersion ,
|
|
.Cm reftime
|
|
variables are described in the RFC-1305 specification, as
|
|
are the timestamps
|
|
.Cm org ,
|
|
.Cm rec
|
|
and
|
|
.Cm xmt .
|
|
Additional NTPv4 system variables include
|
|
the following.
|
|
.Bl -tag -width indent
|
|
.It flash
|
|
The flash code for the most recent packet received.
|
|
The encoding and
|
|
meaning of these codes is given later in this page.
|
|
.It jitter
|
|
The estimated time error of the peer clock measured as an exponential
|
|
average of RMS time differences.
|
|
.It unreach
|
|
The value of the counter which records the number of poll intervals since
|
|
the last valid packet was received.
|
|
.El
|
|
.Pp
|
|
When the NTPv4 daemon is compiled with the OpenSSL software library, additional
|
|
peer variables are displayed, including the following:
|
|
.Bl -tag -width indent
|
|
.It flags
|
|
The current flag bits.
|
|
This word is the server host status word with
|
|
additional bits used by the Autokey state machine.
|
|
See the source code for
|
|
the bit encoding.
|
|
.It hostname
|
|
The server host name.
|
|
.It initkey Ar key
|
|
The initial key used by the key list generator in the Autokey protocol.
|
|
.It initsequence Ar index
|
|
The initial index used by the key list generator in the Autokey protocol.
|
|
.It signature
|
|
The server message digest/signature scheme name from the OpenSSL software
|
|
library.
|
|
.It timestamp Ar time
|
|
The NTP timestamp when the last Autokey key list was generated and signed.
|
|
.El
|
|
.Ss Flash Codes
|
|
The
|
|
.Cm flash
|
|
code is a valuable debugging aid displayed in the peer variables
|
|
list.
|
|
It shows the results of the original sanity checks defined in the NTP
|
|
specification RFC-1305 and additional ones added in NTPv4.
|
|
There are 12 tests
|
|
designated
|
|
.Sy TEST1
|
|
through
|
|
.Sy TEST12 .
|
|
The tests are performed in a certain order
|
|
designed to gain maximum diagnostic information while protecting against
|
|
accidental or malicious errors.
|
|
The
|
|
.Sy flash
|
|
variable is initialized to zero as
|
|
each packet is received.
|
|
If after each set of tests one or more bits are set,
|
|
the packet is discarded.
|
|
.Pp
|
|
Tests
|
|
.Sy TEST1
|
|
through
|
|
.Sy TEST3
|
|
check the packet timestamps from which the offset and
|
|
delay are calculated.
|
|
If any bits are set, the packet is discarded; otherwise,
|
|
the packet header variables are saved.
|
|
.Sy TEST4
|
|
and
|
|
.Sy TEST5
|
|
are associated with
|
|
access control and cryptographic authentication.
|
|
If any bits are set, the
|
|
packet is discarded immediately with nothing changed.
|
|
.Pp
|
|
Tests
|
|
.Sy TEST6
|
|
through
|
|
.Sy TEST8
|
|
check the health of the server.
|
|
If any bits are set,
|
|
the packet is discarded; otherwise, the offset and delay relative to the server
|
|
are calculated and saved.
|
|
TEST9 checks the health of the association itself.
|
|
If
|
|
any bits are set, the packet is discarded; otherwise, the saved variables are
|
|
passed to the clock filter and mitigation algorithms.
|
|
.Pp
|
|
Tests
|
|
.Sy TEST10
|
|
through
|
|
.Sy TEST12
|
|
check the authentication state using Autokey
|
|
public-key cryptography, as described in the
|
|
.Sx Authentication Options
|
|
section of
|
|
.Xr ntp.conf 5 .
|
|
If
|
|
any bits are set and the association has previously been marked reachable, the
|
|
packet is discarded; otherwise, the originate and receive timestamps are saved,
|
|
as required by the NTP protocol, and processing continues.
|
|
.Pp
|
|
The
|
|
.Cm flash
|
|
bits for each test are defined as follows.
|
|
.Bl -tag -width indent
|
|
.It 0x001
|
|
.Pq TEST1
|
|
Duplicate packet.
|
|
The packet is at best a casual retransmission and at
|
|
worst a malicious replay.
|
|
.It 0x002
|
|
.Pq TEST2
|
|
Bogus packet.
|
|
The packet is not a reply to a message previously sent.
|
|
This
|
|
can happen when the NTP daemon is restarted and before somebody else
|
|
notices.
|
|
.It 0x004
|
|
.Pq TEST3
|
|
Unsynchronized.
|
|
One or more timestamp fields are invalid.
|
|
This normally
|
|
happens when the first packet from a peer is received.
|
|
.It 0x008
|
|
.Pq TEST4
|
|
Access is denied.
|
|
See the
|
|
.Sx Access Control Support
|
|
section of
|
|
.Xr ntp.conf 5 .
|
|
.It 0x010
|
|
.Pq TEST5
|
|
Cryptographic authentication fails.
|
|
See the
|
|
.Sx Authentication Options
|
|
section of
|
|
.Xr ntp.conf 5 .
|
|
.It 0x020
|
|
.Pq TEST6
|
|
The server is unsynchronized.
|
|
Wind up its clock first.
|
|
.It 0x040
|
|
.Pq TEST7
|
|
The server stratum is at the maximum than 15.
|
|
It is probably unsynchronized
|
|
and its clock needs to be wound up.
|
|
.It 0x080
|
|
.Pq TEST8
|
|
Either the root delay or dispersion is greater than one second, which is
|
|
highly unlikely unless the peer is unsynchronized to Mars.
|
|
.It 0x100
|
|
.Pq TEST9
|
|
Either the peer delay or dispersion is greater than one second, which is
|
|
higly unlikely unless the peer is on Mars.
|
|
.It 0x200
|
|
.Pq TEST10
|
|
The autokey protocol has detected an authentication failure.
|
|
See the
|
|
.Sx Authentication Options
|
|
section of
|
|
.Xr ntp.conf 5 .
|
|
.It 0x400
|
|
.Pq TEST11
|
|
The autokey protocol has not verified the server or peer is proventic and
|
|
has valid public key credentials.
|
|
See the
|
|
.Sx Authentication Options
|
|
section of
|
|
.Xr ntp.conf 5 .
|
|
.It 0x800
|
|
.Pq TEST12
|
|
A protocol or configuration error has occurred in the public key algorithms
|
|
or a possible intrusion event has been detected.
|
|
See the
|
|
.Sx Authentication Options
|
|
section of
|
|
.Xr ntp.conf 5 .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr ntp.conf 5 ,
|
|
.Xr ntpd 8 ,
|
|
.Xr ntpdc 8
|
|
.Sh BUGS
|
|
The
|
|
.Ic peers
|
|
command is non-atomic and may occasionally result in
|
|
spurious error messages about invalid associations occurring and
|
|
terminating the command.
|
|
The timeout time is a fixed constant,
|
|
which means you wait a long time for timeouts since it assumes sort
|
|
of a worst case.
|
|
The program should improve the timeout estimate as
|
|
it sends queries to a particular host, but does not.
|