xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
NAME
xntpdc - query or control the xntpd Network Time Protocol server
SYNOPSIS
xntpdc [ -ilnps ] [ -c command ] ... [ host ... ]
where:
command An xntpdc command (see Commands in Alphabetical Order below)
host The host name of a system to be queried; default = localhost
DESCRIPTION
Xntpdc uses NTP mode 7 packets to query the xntpd(1M) server about
its current state and to request changes in that state. You can run
the program in interactive mode or with command-line arguments.
Extensive state and statistics information is available through the
xntpdc interface. In addition, nearly all the configuration options
that can be specified at start-up using xntpd's configuration file
may also be specified at run-time using xntpdc.
If you use the -c, -l, -p, or -s option, the specified commands are
sent to the NTP server(s) running on the hosts. If you omit these
options, ntpq reads commands from the standard input and sends these
to the NTP server(s); if the standard input is a terminal device,
ntpq prompts for commands.
Xntpdc can communicate with any server on the network that recognizes
NTP mode 7 control message format. Since NTP is a UDP protocol, this
communication is somewhat unreliable, especially over long distances.
Xntpdc makes no attempt to retransmit requests, and times out if a
response is not received from the remote host within a suitable time
(see timeout under Commands in Alphabetical Order below).
Options
-c Add the specified command to the list of commands to be run
on the host(s).
-i Run xntpdc in interactive mode. Prompts are written to the
standard output and commands read from the standard input.
-l Obtain a list of peers that are known to the server(s). This
option is equivalent to "-c listpeers".
-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 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 option. This is equivalent to "-c dmpeers".
Licensed material--property of copyright holder(s) 1
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
Commands by Category
Each xntpdc command comprises a keyword followed by zero or more
arguments. You need type only enough characters of the full keyword
to identify the command uniquely. By default, command output is sent
to the standard output; to redirect output to a file, append >
filename to the command.
Internal commands are executed entirely within the xntpdc program
itself and do not send NTP mode 7 requests to a server. The internal
commands are as follows:
+-----------------------------------------------------------------+
|Category Keyword Description of Task |
|General ? Display a help message |
| quit Exit from xntpdc |
|peration host Set name of host to be queried |
| hostnames Set host ID display mode to name or number |
| timeout Specify the time-out interval |
|Security delay Set delay factor for authentication requests* |
| keyid Specify an authentication key number |
| passwd Prompt for password to authenticate request |
+-----------------------------------------------------------------+
* On the DG/UX System, this command has no effect.
Query commands send a server NTP mode 7 packets containing requests
for information. These are read-only commands; they make no
modification of the server configuration state. The query commands
are as follows:
+----------------------------------------------------------------------+
|Category Keyword Description of Task |
|Clock clockinfo Print information concerning peer clock |
| clkbug Obtain debugging information for clock peer |
|Counters iostats Print counters maintained in I/O module |
| monlist Print traffic counts maintained by monitor |
| memstats Print counters related to memory allocation |
| pstats Show per-peer statistic counters |
| sysstats Print stat counters from protocol module |
| timerstats Print timer/event queue counters |
|General reslist Print server's restriction list |
|Peers listpeers List peers for which server is maintaining state |
| peers List peers plus summary information |
| dmpeers List peers with information in another format |
|Variables loopinfo Print values of loop filter variables |
| showpeer Display peer variables for one or more peers |
| sysinfo Print a variety of system state variables |
+----------------------------------------------------------------------+
Run-time configuration commands cause state changes in a server. All
run-time configuration commands are authenticated by the server using
a configured NTP key. The facility is disabled if no key has been
configured for the server. To make the key number and corresponding
key known to xtnpdc, use the keyid and passwd commands, the latter of
which prompts at the terminal for a password to use as the encryption
Licensed material--property of copyright holder(s) 2
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
key. You will also be prompted automatically for both the key number
and password the first time a command that 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
source address restrictions are applied, the run-time reconfiguration
facility should provide an adequate level of security. The run-time
configuration commands are as follows:
+----------------------------------------------------------------------+
|Category Keyword Description of Task |
|General monitor Turn network monitoring on or off |
| setprecision Set precision that the server advertises |
| setselect Set selection weight algorithm |
|Flags set Set broadcast client and authentication flags |
| clear Unset broadcast client and authentication flags |
|Peers addpeer Add a peer association in symmetric active mode |
| addserver Add client peer association |
| broadcast Add broadcast peer association |
| unconfig Remove the configured bit from peers |
|Security restrict Add flags to restriction list entry |
| unrestrict Delete flags to restriction list entry |
| delrestrict Delete restriction list entry |
| readkeys Reread the keys file* |
| trustkey Add keys to the trusted key list* |
| untrustkey Delete keys from the trusted key list* |
| authinfo Return information concerning authentication* |
+----------------------------------------------------------------------+
* On the DG/UX System, this command has no effect.
Commands in Alphabetical Order
In the command descriptions below, the syntax uses square brackets
([]) to delimit optional arguments, a vertical line (|) to separate
alternatives, an ellipsis (...) to indicate repeatability, and curly
brackets ({}) to group required elements that are repeatable.
? [ commandkeyword ]
If the argument is omitted, list all the command keywords recognized
Licensed material--property of copyright holder(s) 3
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
by xntpdc. If the argument is specified, display task and syntax
information about the command. help is an alias for ?.
addpeer peeraddress [ keyid ] [ version# ] [ minpoll ]
Add a configured, symmetrically 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 is done. The version# can be 1, 2, or 3,
and defaults to 3. If you specify "minpoll", the polling interval
for the association remains clamped at the minimum. The latter
option is useful only 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 ]
Do the same as the addpeer command except that polling is done in
client mode rather than symmetric active mode.
authinfo
Return information concerning the authentication module, including
known keys and counts of encryptions and decryptions that have been
done. On the DG/UX System, this command has no effect.
broadcast peeraddress [ keyid ] [ version# ] [ minpoll ]
Do the same as the addpeer command except that packets are instead
sent in broadcast mode. The peeraddress parameter is generally a
broadcast address on one of your local networks.
clear { bclient|auth } ...
Clear the broadcast client and authenticate system flags. 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.
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.
clockinfo clockpeeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Print information concerning a peer clock. The values obtained
provide information on the setting of fudge factors and other clock
performance information.
Licensed material--property of copyright holder(s) 4
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
delay milliseconds
Specify a time interval to be added to time stamps included in
requests that require authentication. This is used to enable
(unreliable) server reconfiguration over long-delay network paths or
between machines whose clocks are unsynchronized. On the DG/UX
System, this command has no effect.
delrestrict address mask [ ntpport ]
Delete the matching entry from the restriction list.
dmpeers
List peers the same as for the peers command except for the character
in the leftmost column. Characters only appear beside peers that
were included in the final stage of the clock selection algorithm. A
period (.) indicates that this peer was cast off in the falseticker
detection, while a plus (+) indicates that the peer made it through.
An asterisk (*) denotes the peer with which the server is currently
synchronizing.
host hostname
Set the host to which future queries will be sent. Hostname can be
either a host name or a numeric address.
hostnames yes|no
For "yes", display host names. For "no", display numeric addresses.
The default is "yes" unless you specify the -n option to ntpq.
iostats
Print counters maintained in the input-output module.
keyid #
Specify a 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.
listpeers
List briefly 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 synchronization candidates.
loopinfo [ oneline|multiline ]
Print the values of selected loop filter variables. The loop filter
is the part of NTP that deals with adjusting the local system clock.
The "offset" is the last offset given to the loop filter by the
Licensed material--property of copyright holder(s) 5
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
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 that have elapsed
since a new sample offset was given to the loop filter. "oneline"
and "multiline" specify the format in which this information is to be
printed. "multiline" is the default.
memstats
Print a number of counters related to the peer memory allocation
code.
monitor yes|no
Enable or disable the monitoring facility. A monitor no command
followed by a monitor yes command is a good way of resetting the
packet counts.
monlist
Print traffic counts collected and maintained by the monitor
facility.
passwd
Prompt for a password (which will not be echoed) used to authenticate
configuration requests. The password must correspond to the key
configured for use by the NTP server for this purpose.
peers
List 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 plus (+) denotes
symmetric active, a minus (-) indicates symmetric passive, an equals
sign (=) means the remote server is being polled in client mode, a
circumflex (^) indicates that the server is broadcasting to this
address, a tilde (~) denotes that the remote peer is sending
broadcasts and an asterisk (*) marks the peer the server is currently
synchronizing to.
pstats peeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Show per-peer statistic counters associated with the specified
peer(s).
Licensed material--property of copyright holder(s) 6
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
quit
Exit from xntpdc.
readkeys
Cause 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 lets you change
encryption keys without restarting the server. On the DG/UX System,
this command has no effect.
reslist
Print the server's restriction list. This list is (usually) printed
in sorted order and may help to understand how the restrictions are
applied.
restrict address mask flag [ flag ]
Cause flag(s) to be added to an existing restriction list entry, or
add 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 that match this entry.
If you specify this flag, 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 that try to modify the
state of the server (i.e. run-time reconfiguration).
Queries that 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 Modify the match algorithm. Its presence causes the
restriction entry to be matched only if the source port
in the packet is the standard NTP UDP port (123). You
can specify both ntpport and non-ntpport. ntpport is
considered more specific and is sorted later in the
list.
Licensed material--property of copyright holder(s) 7
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
set { bclient|auth } ...
Set the broadcast client and authenticate system flags. Setting the
former causes the server to listen for broadcast NTP to synchronize
to broadcasts when appropriate. Setting the latter causes the server
to synchronize only with peers that include an authentication field
encrypted with one of the local server's trusted keys.
setprecision precisionvalue
Set the precision that the server advertises to the specified value.
This should be a negative integer in the range -4 through -20.
setselect algorithmnumber
Set the selection weight algorithm to that indicated by the specified
number. This should be an integer value from 1 to 5. Algorithm 1 is
that specified in RFC 1305; the other 4 algorithms are experimental
and should be used with caution.
showpeer peeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Show a detailed display of the current peer variables for one or more
peers. Most of these values are described in the NTP Version 3
specification.
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
3 specification, RFC 1305.
sysstats
Print a number of stat counters maintained in the protocol module.
timeout milliseconds
Specify a time-out period for responses to server queries. The
default is about 8000 milliseconds.
timerstats
Print counters maintained in the timer/event queue support code.
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. On the DG/UX System, this command has no
effect.
Licensed material--property of copyright holder(s) 8
xntpdc(1M) TCP/IP 5.4R3.00 xntpdc(1M)
unconfig peeraddress [ addr2 ] [ addr3 ] [ addr4 ]
Cause the configured bit to be removed from the specified peer(s).
In many cases this causes 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.
unrestrict address mask flag [ flag ]
Remove the specified flag(s) from the restriction list entry
indicated by the address and mask arguments.
untrustkey keyid [ keyid ] [ keyid ] [ keyid ]
Remove one or more keys from the trusted key list. On the DG/UX
System, this command has no effect.
SEE ALSO
ntpq(1M), xntpd(1M).
NOTE
The DG/UX System does not support DES authentication.
Licensed material--property of copyright holder(s) 9