xntpdc(1M)xntpdc(1M)NAMExntpdc - special NTP query program
SYNOPSIS
] [ host ]
DESCRIPTION
is used to query the daemon about its current state and to request
changes in that state. The program may be run either in interactive
mode or controlled mode using command line arguments. Extensive state
and statistics information is available through the interface. In addi‐
tion, nearly all the configuration options which can be specified at
start up using configuration file may also be specified at run time
using If one or more request options is included on the command line
when 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, 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. will prompt
for commands if the standard input is a terminal device.
uses NTP mode 7 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 net‐
work topology. makes no attempt to retransmit requests, and will time‐
out requests if the remote host is not heard from within a suitable
timeout time.
The operation of is specific to the particular implementation of the
daemon and can be expected to work only with this and maybe some previ‐
ous versions of the daemon. Requests from a remote program which affect
the state of the local server must be authenticated, which requires
both the remote program and local server to share a common key and key
identifier.
COMMAND LINE OPTIONS
Specifying a command line option other than or will cause the specified
query (or queries) to be sent to the indicated host(s) immediately.
Otherwise, will attempt to read interactive format commands from the
standard input.
The following command is interpreted as an interactive format command
and is added to the list of commands to be executed on
the specified host(s). Multiple commands may be given.
Debugging information is printed.
Force to operate in interactive mode. Prompts will be written
to the standard output and commands read from the stan‐
dard input.
Obtain a list of peers which are known to the server(s). This option is
equivalent to command. See "CONTROL MESSAGE COMMANDS"
below.
Output all host addresses in dotted-quad numeric format
(xxx.xxx.xxx.xxx)
rather than converting to the canonical host names.
Print a list of peers known to the server as well as a summary of
their state. This is equivalent to command. See "CONTROL
MESSAGE COMMANDS" below.
Print a list of peers known to the server as well as a summary of
their state, but in a slightly different format than the
command. This is equivalent to command. See "CONTROL
MESSAGE COMMANDS" below.
INTERACTIVE 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. The output of individual commands may be
redirected or sent to a file by appending a followed by a file name, to
the command line.
A number of interactive format commands are executed entirely within
the program itself and do not result in NTP mode 7 requests being sent
to a server. These commands are described as follows:
A or by itself will print a list of all the
command keywords. A or followed by a com‐
mand keyword (command_keyword) will print
function and usage information about the
command.
Specify a time interval to be added to timestamps included in
requests
which require authentication. This is used
to enable (unreliable) server reconfigura‐
tion over long delay network paths or
between machines whose clocks are unsynchro‐
nized.
Set the host to which future queries will be sent.
The hostname may be either a host name or a
numeric address.
If is specified, host names are printed in
information displays. If is specified,
numeric addresses are printed instead. The
default is unless modified using the command
line command.
This command allows the specification of a key number to be used
to
authenticate configuration requests. The
keyid must correspond to a key number that
the server has been configured to use for
this purpose.
Exit
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.
Specify a timeout period for responses to server queries. The
default
is about 8000 milliseconds. Note that since
retries each query once after a timeout, the
total waiting time for a timeout will be
twice the timeout value set.
CONTROL MESSAGE COMMANDS
Query commands result in NTP mode 7 packets containing requests
for information being sent to the server. These are read-only
commands in that they make no modification of the server config‐
uration state.
Obtains and prints a brief list of the peers for which
the server is
maintaining state. This list should
include all configured peer associations
as well as those peers whose stratum is
such that they are considered by the
server to be possible future synchroniza‐
tion candidates.
Obtains a list of peers for which the server is maintain‐
ing state, along
with a summary of that state. Summary
information includes the address of the
remote peer, the local interface address
(0.0.0.0 if a local address has yet to be
determined), the stratum of the remote
peer (a stratum of 16 indicates the remote
peer is unsynchronized), the polling
interval in seconds, the reachability reg‐
ister in octal, and the current estimated
delay, offset and dispersion of the peer,
all in seconds. In addition, the character
in the left margin indicates the mode this
peer entry is operating in.
indicates symmetric active
indicates symmetric passive
indicates the remote server is being
polled in client mode
indicates the server is broadcasting to
this address
indicates the remote peer is sending
broadcasts
indicates the peer that the server is cur‐
rently synchronizing to.
The contents of the host field may be a host name, an IP
address, a reference clock implementation name with its
parameter or REFCLK (implementation number, parameter).
For only IP addresses will be displayed.
A slightly different peer summary list. The output is
similar to that of the
command, except for the character in the leftmost
column. Characters only appear beside peers which
were included in the final stage of the clock
selection algorithm. A period indicates that this
peer was cast off in the falseticker detection. A
plus indicates that the peer made it through. An
asterisk denotes the peer that the server is cur‐
rently synchronizing with.
Shows a detailed display of the current peer variables
for one or more
peers. Most of these values are described in the
NTP Version 2 specification.
Show per-peer statistic counters associated with the
specified peer(s).
Obtain and print information concerning a peer clock. The
values
obtained provide information on the setting of
fudge factors and other clock performance informa‐
tion.
Obtain and print kernel phase-lock loop operating parame‐
ters. This
information is available only if the kernel has
been specially modified for a precision timekeep‐
ing function.
Print the values of selected loop filter variables. The
loop filter is
the part of NTP which deals with adjusting the
local system clock. The offset is the last offset
given to the loop filter by the packet processing
code. The frequency is the frequency error of the
local clock in parts-per-million (ppm). The
time_const controls the stiffness of the phase-
lock loop and thus the speed at which it can adapt
to oscillator drift. The watchdog timer value is
the number of seconds which have elapsed since the
last sample offset was given to the loop filter.
The and options specify the format in which this
information is to be printed. is the default.
Print a variety of system state variables, i.e., the
state related to the
local server.
The system flags show various system flags, some
of which can be set and cleared by the and config‐
uration commands, respectively. The configurable
flags are the auth, bclient, monitor, pll, pps and
stats flags. Refer to xntpd(1M) for the descrip‐
tion of these flags.
The stability is the residual frequency error
remaining after the system frequency correction is
applied and is intended for maintenance and debug‐
ging. In most architectures, this value will ini‐
tially decrease from as high as 500 ppm to a nomi‐
nal value in the range .01 to 0.1 ppm. If it
remains high for some time after starting the dae‐
mon, something may be wrong with the local clock,
or the value of the kernel variable tick may be
incorrect.
The shows the default broadcast delay, as set by
the configuration command.
The shows the default authentication delay, as set
by the configuration command.
Print statistics counters maintained in the protocol mod‐
ule.
Print statistics counters related to memory allocation
code.
Print statistics counters maintained in the input-output
module.
Print statistics counters maintained in the timer/event
queue support
code.
Obtain and print the server's restriction list. This list
is (usually)
printed in sorted order and may help to understand
how the restrictions are applied.
Obtain and print traffic counts collected and maintained
by the monitor
facility. The version number should not normally
need to be specified.
Obtain debugging information for a reference clock
driver. This
information is provided only by some clock drivers
and is mostly undecodable without a copy of the
driver source.
RUNTIME CONFIGURATION REQUESTS
All requests which cause state changes in the server are authen‐
ticated by the server using a configured NTP key. This facility
is disabled if the NTP key is not configured. The key number and
the corresponding key must also be made known to This can be
done using the keyid and passwd commands, the latter of which
will prompt at the terminal for a password to use as the encryp‐
tion key. You will also be prompted automatically for both the
key number and password the first time a command which would
result in an authenticated request to the server is given.
Authentication not only provides verification that the requester
has permission to make such changes, but also gives an extra
degree of protection against transmission errors.
Authenticated requests always include a timestamp in the packet
data, which is included in the computation of the authentication
code. This timestamp is compared by the server to its receive
time stamp. If they differ by more than a small amount the
request is rejected. This is done for two reasons. First, it
makes simple replay attacks on the server, by someone who might
be able to overhear traffic on your LAN, much more difficult.
Second, it makes it more difficult to request configuration
changes to your server from topologically remote hosts. While
the reconfiguration facility will work well with a server on the
local host, and may work adequately between time-synchronized
hosts on the same LAN, it will work very poorly for more distant
hosts. As such, if reasonable passwords are chosen, care is
taken in the distribution and protection of keys and appropriate
source address restrictions are applied, the run time reconfigu‐
ration facility should provide an adequate level of security.
The following commands all make authenticated requests.
Add a configured peer association at the given address
and operating in
symmetric active mode. Note that an existing
association with the same peer may be deleted
when this command is executed, or may simply be
converted to conform to the new configuration, as
appropriate. If the optional is a nonzero inte‐
ger, all outgoing packets to the remote server
will have an authentication field (encrypted)
attached with this key. If the value is 0 (or not
given) no authentication will be done. The # can
be 1, 2 or 3 and defaults to 3. The keyword indi‐
cates a preferred peer (and thus will be used
primarily for clock synchronization if possible).
The preferred peer also determines the validity
of the PPS signal - if the preferred peer is
suitable for synchronization so is the PPS sig‐
nal.
Identical to the addpeer command, except that the operat‐
ing mode is
client.
Identical to the
command, except that the operating mode is broad‐
cast. In this case a valid key identifier and key
are required. The parameter can be the broadcast
address of the local network or a multicast group
address assigned to NTP. If using a multicast
address, a multicast-capable kernel is required.
This command causes the configured bit to be removed from
the specified
peer(s). In many cases this will cause the peer
association to be deleted. When appropriate, how‐
ever, the association may persist in an unconfig‐
ured mode if the remote peer is willing to con‐
tinue on in this fashion.
This command provides a way to set certain data for a
reference clock. See
the source listing for further information.
These commands operate in the same way as
the
and configuration file commands of
Described below are the flags sup‐
ported.
Enables the server to synchronize
with unconfigured peers only if
the peer has been correctly
authenticated using a
trusted key and key identi‐
fier. The default for this
flag is enable.
Enables the server to listen for a
message from a broadcast
or multicast server, as in
the multicastclient command
with default address. The
default for this flag is
disable.
Enables the monitoring facility.
See the
program and the command for
more information. The
default for this flag is
enable.
Enables the server to adjust its
local clock by means of NTP.
If disabled, the local
clock free-runs at its
intrinsic time and fre‐
quency offset. This flag is
useful in case the local
clock is controlled by some
other device or protocol
and NTP is used only to
provide synchronization to
other clients. In this
case, the local clock
driver is used. The default
for this flag is enable.
Enables the pulse-per-second (PPS)
signal when frequency and time
is disciplined by the pre‐
cision time kernel modifi‐
cations. The default for
this flag is disable.
Enables the statistics facility.
The default for this flag is
enable.
This command operates in the same way as
the
configuration file commands of
Unrestrict the matching entry from the
restrict list.
Delete the matching entry from the restrict
list.
Causes the current set of authentication
keys to be purged and a new set
to be obtained by rereading the
keys file (which must have been
specified in the configuration
file). This allows encryption keys
to be changed without restarting
the server.
These commands operate in the
same way as the
and configuration
file commands of
Returns information concern‐
ing the authentication mod‐
ule, including
known keys and counts
of encryptions and
decryptions which
have been done.
Display the traps set in the
server. See the source list‐
ing for further
information.
Set a trap for asynchronous
messages. See the source
listing for
further information.
Clear a trap for asynchronous
messages. See the source
listing for
further information.
Clear the statistics counters
in various modules of the
server. See the
source listing for
further information.
AUTHOR
was developed by David L. Mills.
SEE ALSOxntpd(1M), ntpdate(1M), ntpq(1M).
xntpdc(1M)
