xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
NAME
xntpdc - query/control program for the Network Time Protocol server
SYNOPSIS
xntpdc [ -ilnps ] [ -c command ] [ host ... ]
DESCRIPTION
Xntpdc is used to query the xntpd(1M) server about its current state
and to request changes in that state. The program may be run either
in interactive mode or 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 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, xntpdc
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. Xntpdc will prompt for commands if the standard input is
a terminal device.
Xntpdc uses NTP mode 7 packets to communicate with the NTP server,
and hence can be used to query any compatable server on the network
which permits it. Note that since NTP is a UDP protocol this
communication will be somewhat unreliable, especially over large
distances in terms of network topology. Xntpdc makes no attempt to
retransmit requests, and will time requests out if the remote host is
not heard from within a suitable time out time.
Command line options are described following. Specifying a command
line option other than -i or -n will cause the specified query
(queries) to be sent to the indicated host(s) immediately.
Otherwise, xntpdc will attempt to read interactive format commands
from the standard input.
-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 -c options may
be given.
-i Force xntpdc to operate in interactive mode. Prompts will be
written to the standard output and commands read from the
standard input.
-l Obtain a list of peers which are known to the server(s).
This switch is equivalent to "-c listpeers".
-n Output all host addresses in dotted-quad numeric format
rather than converting to the canonical host names.
Licensed material--property of copyright holder(s) 1
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
-p Print a list of the peers known to the server as well as a
summary of their state. This is equivalent to "-c peers".
-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 switch. This is equivalent to "-c dmpeers".
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 ">",
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 7 requests
being sent to a server. These are described following.
? [ commandkeyword }
A "?" by itself will print a list of all the command keywords known
to this incarnation of xntpdc. A "?" followed by a command keyword
will print funcation and usage information about the command. This
command is probably a better source of information about xntpdc than
this manual page.
help [ commandkeyword ]
A synonym for the ? command.
timeout millseconds
Specify a time out period for responses to server queries. The
default is about 8000 milliseconds.
delay 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.
host hostname
Set the host to which future queries will be sent. Hostname may be
either a host name or a numeric address.
poll [ # ] [ verbose ]
Poll the current server in client mode. The first argument is the
number of times to poll (default is 1) while the second argument may
be given to obtain a more detailed output of the results. This
command is currently just wishful thinking.
Licensed material--property of copyright holder(s) 2
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
keyid #
This command allows the specification of a key number to be used to
authenticate configuration requests. This must correspond to the key
number the server has been configured to use for this purpose.
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.
hostnames yes|no
If "yes" is specified, host names are printed in information
displays. If "no" is given, numeric addresses are printed instead.
The default is "yes" unless modified using the command line -n
switch.
quit
Exit xntpdc.
Query 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 configuration state.
listpeers
Obtains and prints 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.
peers
Obtains a list of peers for which the server is maintaining 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 register, 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. 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.
Licensed material--property of copyright holder(s) 3
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
dmpeers
A slightly different peer summary list. Identical to the output of
the peers 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 "." indicates that this
peer was cast off in the falseticker detection, while a "+" indicates
that the peer made it through. A "*" denotes the peer the server is
currently synchronizing with.
showpeer peeraddress [ addr2 ] [ addr3 ] [ addr4 ]
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.
pstats peeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Show per-peer statistic counters associated with the specified
peer(s).
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 "offset" is the last offset given to the loop filter by the
packet processing code. The "frequency" is actually the frequency
error, or drift, of your system's clock in the units NTP uses for
internal computations. Dividing this number by 4096 should give you
the actual drift rate. The "compliance" is actually a long term
average offset and is used by NTP to control the gain of the loop
filter. The "timer" value is the number of seconds which have
elapsed since a new sample offset was given to the loop filter. The
"oneline" and "multiline" options specify the format in which this
information is to be printed. "multiline" is the default.
sysinfo
Print a variety of system state variables, i.e. state related to the
local server. Many of these values are described in the NTP Version
2 specification, RFC 1119.
sysstats
Print a number of stat counters maintained in the protocol module.
memstats
Print a number of counters related to the peer memory allocation
code.
iostats
Print counters maintained in the input-output module.
Licensed material--property of copyright holder(s) 4
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
timerstats
Print counters maintained in the timer/event queue support code.
reslist
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.
monlist
Obtain and print traffic counts collected and maintained by the
monitor facility.
clockinfo clockpeeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Obtain and print information concerning a peer clock. The values
obtained provide information on the setting of fudge factors and
other clock performance information.
clkbug clockpeeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Obtain debugging information for a clock peer. This information is
provided only by some clock drivers and is mostly undecodable without
a copy of the driver source in hand.
Runtime Configuration Requests
All requests which cause state changes in the server are
authenticated by the server using a configured NTP key (the facility
can also be disabled by the server by not configuring a key). The
key number and the corresponding key must also be made known to
xtnpdc. 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 encryption 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 again 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
Licensed material--property of copyright holder(s) 5
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
source address restrictions are applied, the run time reconfiguration
facility should provide an adequate level of security.
The following commands all make authenticated requests.
addpeer peeraddress [ keyid ] [ version# ] [ minpoll ]
Add a configured, symmetric active peer association with a peer at
the given address. If the optional "keyid" is a nonzero integer all
outgoing packets to the remote server will have an authentication
field attached encrypted with this key. If the value is 0 (or not
given) no authentication will be done. The "version#" can be 1 or 2,
and defaults to 2. If "minpoll" is specified the polling interval
for the association will remain clamped at the minimum. The latter
option is only useful for testing. 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.
addserver peeraddress [ keyid ] [ version# ] [ minpoll ]
Identical to the addpeer command except that polling is done in
client mode rather than symmetric active mode.
broadcast peeraddress [ keyid ] [ version# ] [ minpoll ]
Identical to the addpeer command except that packets are instead sent
in broadcast mode. The "peer_address" parameter will generally be a
broadcast address on one of your local networks.
unconfig peeraddress [ addr2 ] [ addr3 ] [ addr4 ]
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, however, the
association may persist in an unconfigured mode if the remote peer is
willing to continue on in this fashion.
set bclient|auth [ ... ]
Allows the setting of the broadcast client and/or authenticate system
flags. Setting the former causes the server to listen for broadcast
NTP to to synchronize to broadcasts when appropriate. Setting the
latter flag causes the server to only synchronize with peers which
include an authentication field encrypted with one of the local
server's trusted keys.
clear bclient|auth [ ... ]
Allows the broadcast client and/or authenticate system flags to be
cleared. Clearing the former causes incoming broadcast NTP packets
to be ignored. Clearing the latter allows peers which have not
included an authentication field, or which have included one but have
encrypted it with an untrusted key, to be considered synchronization
Licensed material--property of copyright holder(s) 6
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
candidates.
restrict address mask flag [ flag ]
Causes flag(s) to be added to an existing restrict list entry, or
adds a new entry to the list with the specified flag(s). The
possible choices for the flags arguments are given in the following
list:
ignore Ignore all packets from hosts which match this entry. If
this flag is specified neither queries nor time server
polls will be responded to.
noquery Ignore all NTP mode 7 packets (i.e. information queries and
configuration requests) from the source. Time service is
not affected.
nomodify Ignore all NTP mode 7 packets which attempt to modify the
state of the server (i.e. run time reconfiguration).
Queries which return information are permitted.
noserve Ignore NTP packets whose mode is other than 7. In effect,
time service is denied, though queries may still be
permitted.
nopeer Provide stateless time service to polling hosts, but do not
allocate peer memory resources to these hosts even if they
otherwise might be considered useful as future
synchronization partners.
notrust Treat these hosts normally in other respects, but never use
them as synchronization sources.
ntpport This is actually a match algorithm modifier, rather than a
restriction flag. Its presence causes the restriction
entry to be matched only if the source port in the packet
is the standard NTP UDP port (123). Both "ntpport" and
non-"ntpport" may be specified. The "ntpport" is
considered more specific and is sorted later in the list.
unrestrict address mask flag [ flag ]
Remove the specified flag(s) from the restrict list entry indicated
by the address and mask arguments.
delrestrict address mask [ ntpport ]
Delete the matching entry from the restrict list.
monitor yes|no
Enable or disable the monitoring facility. Note that a monitor no
command followed by a monitor yes command is a good way of resetting
the packet counts.
Licensed material--property of copyright holder(s) 7
xntpdc(1M) TCP/IP 5.4 Rel. 2.01 xntpdc(1M)
readkeys
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 xntpd configuration file). This allows encryption
keys to be changed without restarting the server.
trustkey keyid [ keyid ] [ keyid ] [ keyid ]
Adds one or more keys to the trusted key list. When authentication
is enabled, peers whose time is to be trusted must be authenticated
using a trusted key.
untrustkey keyid [ keyid ] [ keyid ] [ keyid ]
Removes one or more keys from the trusted key list.
authinfo
Returns information concerning the authentication module, including
known keys and counts of encryptions and decryptions which have been
done.
setprecision precisionvalue
Sets the precision which the server advertises to the specified
value. This should be a negative integer in the range -4 through
-20.
setselect algorithmnumber
Sets the selection weight algorithm to that indicated by the
specified number. This should be an integer value between 1 and 5
inclusive. Algorithm 1 is that specified in RFC 1119, the other 4
algorithms are experimental and should be used with caution.
SEE ALSO
xntpd(1M).
HISTORY
Written by Dennis Ferguson at the University of Toronto.
BUGS
Xntpdc is a crude hack. Much of the information it shows is deadly
boring and could only be loved by its implementer. The program was
designed so that new (and temporary) features were easy to hack in,
at great expense to the program's ease of use. Despite this, the
program is occasionally useful.
Licensed material--property of copyright holder(s) 8