XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
NAME
xntpdc | query/control program for the Network Time Protocol daemon
SYNOPSIS
xntpdc [ |ilnps ] [ |c command ] [ host ] [ ... ]
DESCRIPTION
Xntpdc is used to query the xntpd(8) daemon 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.
10/89 Page 1
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
|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.
? [ command_keyword }
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 [ command_keyword ]
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 ]
Page 2 10/89
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
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.
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
10/89 Page 3
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
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.
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 peer_address [ 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 peer_address [ 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
Page 4 10/89
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
Print a number of counters related to the peer memory allocation code.
iostats
Print counters maintained in the input-output module.
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 clock_peer_address [ 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 clock_peer_address [ 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
10/89 Page 5
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
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 reconfiguration facility should provide an adequate level of
security.
The following commands all make authenticated requests.
addpeer peer_address [ 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 peer_address [ keyid ] [ version# ] [ minpoll ]
Identical to the addpeer command except that polling is done in client
mode rather than symmetric active mode.
broadcast peer_address [ 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 peer_address [ 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.
Page 6 10/89
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
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 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 ]
10/89 Page 7
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
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.
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 precision_value
Sets the precision which the server advertises to the specified value.
This should be a negative integer in the range |4 through |20.
setselect algorithm_number
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(8)
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
Page 8 10/89
XNTPDC(8) UNIX System V(LOCAL) XNTPDC(8)
great expense to the program's ease of use. Despite this, the program is
occasionally useful.
10/89 Page 9