xntpdc(1M) System Administration Commands xntpdc(1M)NAMExntpdc - special NTP query program
SYNOPSISxntpdc [-ilnps] [-c command] [host] [...]
DESCRIPTIONxntpdc queries the xntpd daemon about its current state and requests
changes in that state. You can run xntpdc in interactive mode or in
controlled using command line arguments.
Extensive state and statistics information is available through the
xntpdc interface. In addition, nearly all the configuration options
which can be specified at start up using xntpd's configuration file may
also be specified at run time using xntpdc.
If one or more request options is included on the command line when
xntpdc is executed, each of the requests is sent to the NTP servers
running on each of the hosts given as command line arguments, or on the
local host by default. If no request options are given, xntpdc attempts
to read commands from the standard input and execute these on the NTP
server running on the first host specified on the command line, again
defaulting to the local host when no other host is specified. xntpdc
prompts for commands if the standard input is a terminal device.
xntpdc uses NTP mode 7 packets to communicate with the NTP server, and
can be used to query any compatable server on the network which permits
it. As NTP is a UDP protocol, this communication is somewhat unreli‐
able, especially over large distances. xntpdc does not attempt to re-
transmit requests, and times requests out if the remote host is not
heard from within a suitable timeout time.
The operation of xntpdc is specific to the particular implementation of
the xntpd daemon. You can expect xntpdc to work only with this and
maybe some previous versions of the daemon. Requests from a remote xnt‐
pdc program that affect the state of the local server must be authenti‐
cated. This requires that both the remote program and local server
share a common key and key identifier.
OPTIONSxntpdc reads interactive format commands from the standard input. If
you specify the -c, -l, -p or -s option, the specified queries are sent
to the hosts immediately.
The following command line options are supported:
-c command... Add command to the list of commands to execute
on the specified hosts. command is interpreted
as an interactive format command.
Multiple -c options may be specified.
-i Force xntpdc to operate in interactive mode.
Prompts are written to the standard output.
Commands are read from the standard input.
-l Obtain a list of peers which are known to the
servers.
This option is equivalent to -c listpeers. See
listpeers in Control Message Commands.
-n Output all host addresses in dotted-quad
numeric format rather than converting to the
canonical host names.
-p Print a list of the peers known to the server
as well as a summary of their state.
This option is equivalent to -c peers. See
peers in Control Message Commands.
-s Print a list of the peers known to the server
as well as a summary of their state, but in a
slightly different format than the -p option.
This option is equivalent to -c dmpeers. See
dmpeers in Control Message Commands.
OPERANDS
The following operands are supported:
USAGE
Interactive Commands
The interactive commands consist of a keyword (command_keyword) fol‐
lowed by zero to four arguments. You need to entry only enough charac‐
ters of the command_keyword to uniquely identify it. The output of an
interactive command is sent to the standard output by default. You can
send the output of an interactive command 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 xntpdc program itself and do not result in NTP mode.
The following interactive commands are supported:
? [ command_keyword] Without an argument, print a list of
ntpq command keywords. If command_key‐
word is specified, print function and
usage information about the com‐
mand_keyword.
delay milliseconds Specify a time interval to add to time‐
stamps included in requests which
require authentication.
This enables (unreliable) server recon‐
figuration over long delay network
paths or between machines whose clocks
are unsynchronized. Because the server
no longer requires timestamps in
authenticated requests, this command
may be obsolete.
help [ command_keyword] Without an argument, print a list of
ntpq command keywords. If command_key‐
word is specified, print function and
usage information about the com‐
mand_keyword.
host hostname Set the host (hostname) to which future
queries are sent. Specify hostname as a
host name or a numeric address.
hostnames [ yes | no] Print hostnames or numeric addresses in
information displays.
Specify yes to print host names. Spec‐
ify no to print numeric addresses.
The default is yes, unless the -n com‐
mand line option is specified.
keyid keyid Enable specification of a key number
(keyid) to authenticate configuration
requests. keyid must correspond to a
key number the server has been config‐
ured to use for this purpose.
passwd Allow the user to specify a password at
the command line to authenticate con‐
figuration requests.
The password is not displayed, and must
correspond to the key configured for
use by the NTP server for this purpose.
If the password does not correspond to
the key configured for use by the NTP
server, requests are not successful.
quit Exit xntpdc.
timeout millseconds Specify a timeout period for responses
to server queries.
The default is approximately 8000 mil‐
liseconds. As xntpdc retries each query
once after a timeout, the total waiting
time for a timeout is 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 control message commands
are read-only commands in that they make no modification of the server
configuration state.
The following control message commands are supported:
clkbug
Obtain debugging information for a reference clock driver. This
information is provided only by some clock drivers.
clockinfo clock_peer_address[...]
Obtain and print information concerning a peer clock.
The values obtained provide information on the setting of fudge
factors and other clock performance information.
dmpeers
Obtain a list of peers for which the sserver is maintaining state,
along with a summary of that state.
The peer summary list is identical to the output of the peers com‐
mand, 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 . indicates that this peer was
cast off in the falseticker detection, while a + indicates that the
peer made it through. A * denotes the peer with which the server is
currently synchronizing.
iostats
Print statistics counters maintained in the input-output module.
kerninfo
Obtain and print kernel phase-lock loop operating parameters.
This information is available only if the kernel has been specially
modified for a precision timekeeping function.
listpeers
Obtain and print a brief list of the peers for which the server is
maintaining state.
These 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 synchonization candidates. candidates.
loopinfo [ oneline | multiline ]
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 oneline and multiline options specify the format in which this
information is printed. multiline is the default.
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.
memstats
Print statistics counters related to memory allocation code.
monlist [version]
Obtain and print traffic counts collected and maintained by the
monitor facility. The version number should not normally need to be
specified.
peers
Obtain a list of peers for which the server is maintaining state,
along with a summary of that state.
The following summary information is included:
· Address of the remote peer.
· Local interface address. If a local address has yet to be
determined it is 0.0.0.0.
· Stratum of the remote peer. A stratum of 16 indicates the
remote peer is unsynchronized.
· Polling interval, in seconds.
· Reachability register, in octal.
· Current estimated delay, offset and dispersion of the peer, in
seconds.
· Mode in which the peer entry is operating.
This is represented by the character in the left margin. A +
denotes symmetric active, a - indicates symmetric passive, a =
means the remote server is being polled in client mode, a ^
indicates that the server is broadcasting to this address, a ~
denotes that the remote peer is sending broadcasts and a *
marks the peer the server is currently synchonizing to.
· Host.
This field may contain a host name, an IP address, a reference
clock implementation name with its parameter or REFCLK (imple‐
mentation number, parameter). On hostnames no only IP-
addresses is displayed.
pstats peer_address [...]
Show the per-peer statistic counters associated with the specified
peers.
reslist
Obtain and print the server's restriction list.
Generally, this list is printed in sorted order.
showpeer peer_address [...]
Show 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.
sysinfo
Print a variety of system state variables that are related to the
local server.
The output from sysinfo is described in NTP Version 3 specifica‐
tion, RFC-1305. All except the last four lines are described in the
NTP Version 3 specification, RFC-1305.
The system flags show various system flags, some of which can be
set and cleared by the enable and disable configuration commands,
respectively. These are the auth, bclient, monitor, pll, pps and
stats flags. See the xntpd documentation for the meaning of these
flags. There are two additional flags which are read only, the ker‐
nel_pll and kernel_pps. These flags indicate the synchronization
status when the precision time kernel modifications are in use. The
kernel_pll indicates that the local clock is being disciplined by
the kernel, while the kernel_pps indicates the kernel discipline is
provided by the PPS signal. The stability is the residual frequency
error remaining after the system frequency correction is applied
and is intended for maintenance and debugging. In most architec‐
tures, this value initially decreases from as high as 500 ppm to a
nominal value in the range .01 to 0.1 ppm. If it remains high for
some time after starting the daemon, something may be wrong with
the local clock, or the value of the kernel variable tick may be
incorrect. The broadcastdelay shows the default broadcast delay, as
set by the broadcastdelay configuration command. The authdelay
shows the default authentication delay, as set by the authdelay
configuration command.
sysstats
Print statistics counters maintained in the protocol module.
timerstats
Print statistics counters maintained in the timer/event queue sup‐
port code.
Runtime Configuration Requests
The server authenticates all requests that cause state changes in the
server. The server uses a configured NTP key to accomplish this. This
facility can also be disabled by the server by not configuring a key).
You must make the key number and the corresponding key known to xtnpdc.
Use the keyid or passwd commands to do so.
The passwd command prompts users for a password to use as the encryp‐
tion key. It also prompts automatically for both the key number and
password the first time a command which would result in an authenti‐
cated request to the server is given. Authentication provides verifica‐
tion that the requester has permission to make such changes. It also
gives an extra degree of protection against transmission errors.
Authenticated requests always include a time stamp in the packet data.
The time stamp is included in the computation of the authentication
code. This timestamp is compared by the server to its receive time
stamp. If the time stamps differ by more than a small amount the
request is rejected.
Time stamps are rejected 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 works well with a server on the
local host, and may work adequately between time-synchronized hosts on
the same LAN, it works very poorly for more distant hosts. If reason‐
able passwords are chosen, care is taken in the distribution and pro‐
tection of keys and appropriate source address restrictions are
applied, the run time reconfiguration facility should provide an ade‐
quate level of security.
The following commands make authenticated requests.
addpeer peer_address [ keyid ] [ version ] [ prefer ]
Add a configured peer association at the given address and operat‐
ing in symmetric active mode. 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 keyid is a non-zero integer, all outgoing packets
to the remote server will have an authentication field attached
encrypted with this key. If the keyid is 0 or omitted, no authenti‐
cation is done.
Specify version as 1, 2 or 3. The default is 3.
The prefer keyword indicates a preferred peer. This keyword is used
primarily for clock synchronisation if possible. The preferred
peer also determines the validity of the PPS signal - if the pre‐
ferred peer is suitable for synchronisation so is the PPS signal.
addserver peer_address [ keyid ] [ version ] [ prefer ]
Identical to the addpeer command, except that the operating mode is
client.
addtrap [ address [ port ] [ interface ]
Set a trap for asynchronous messages.
authinfo
Return information concerning the authentication module, including
known keys and counts of encryptions and decryptions which have
been done.
broadcast peer_address [ keyid ] [ version ] [ prefer ]
Identical to the addpeer command, except that the operating mode is
broadcast. In this case a valid key identifier and key are
required. The peer_address parameter can be the broadcast address
of the local network or a multicast group address assigned to NTP.
If a multicast address, a multicast-capable kernel is required.
clrtrap [ address [ port ] [ interface]
Clear a trap for asynchronous messages.
delrestrict address mask [ ntpport ]
Delete the matching entry from the restrict list.
fudge peer_address [ time1 ] [ time2 ] [ stratum ] [ refid ]
Provide a way to set certain data for a reference clock.
readkeys
Cause the current set of authentication keys to be purged and a new
set to be obtained by re-reading the keys file. The keys file must
have been specified in the xntpd configuration file. This enables
encryption keys to be changed without restarting the server.
restrict address mask flag [ flag]
This command operates in the same way as the restrict configuration
file commands of xntpd.
reset
Clear the statistics counters in various modules of the server.
traps
Display the traps set in the server.
trustkey keyid [...]
untrustkey keyid [...]
These commands operate in the same way as the trustedkey and
untrustkey configuration file commands of xntpd.
unconfig peer_address [...]
Cause the configured bit to be removed from the specified peers. In
many cases this causes the peer association to be deleted. When
appropriate, however, the association may persist in an unconfig‐
ured mode if the remote peer is willing to continue on in this
fashion.
unrestrict address mask flag [ flag]
Unrestrict the matching entry from the restrict list.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ATTRIBUTE TYPE │ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWntpu │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOntpdate(1M), ntpq(1M), ntptrace(1M), xntpd(1M), rename(2),
attributes(5)SunOS 5.10 12 July 2004 xntpdc(1M)
