660 lines
19 KiB
Groff
660 lines
19 KiB
Groff
''' $Header
|
|
'''
|
|
.de Sh
|
|
.br
|
|
.ne 5
|
|
.PP
|
|
\fB\\$1\fR
|
|
.PP
|
|
..
|
|
.de Sp
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Ip
|
|
.br
|
|
.ie \\n.$>=3 .ne \\$3
|
|
.el .ne 3
|
|
.IP "\\$1" \\$2
|
|
..
|
|
'''
|
|
''' Set up \*(-- to give an unbreakable dash;
|
|
''' string Tr holds user defined translation string.
|
|
''' Bell System Logo is used as a dummy character.
|
|
'''
|
|
.tr \(bs-|\(bv\*(Tr
|
|
.ie n \{\
|
|
.ds -- \(bs-
|
|
.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
|
|
.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
|
|
.ds L" ""
|
|
.ds R" ""
|
|
.ds L' '
|
|
.ds R' '
|
|
'br\}
|
|
.el\{\
|
|
.ds -- \(em\|
|
|
.tr \*(Tr
|
|
.ds L" ``
|
|
.ds R" ''
|
|
.ds L' `
|
|
.ds R' '
|
|
'br\}
|
|
.TH XNTPDC 8 LOCAL
|
|
.SH NAME
|
|
xntpdc - query/control program for the Network Time Protocol daemon
|
|
.SH SYNOPSIS
|
|
.B xntpdc
|
|
[
|
|
.B -ilnps
|
|
] [
|
|
.B -c
|
|
.I command
|
|
] [
|
|
.I host
|
|
] [
|
|
.I ...
|
|
]
|
|
.SH DESCRIPTION
|
|
.I Xntpdc
|
|
is used to query the
|
|
.IR 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
|
|
.I xntpdc
|
|
interface. In addition, nearly all the configuration options which can
|
|
be specified at start up using
|
|
.IR xntpd 's
|
|
configuration file may also be specified at run time using
|
|
.IR xntpdc .
|
|
.PP
|
|
If one or more request options is included on the command line when
|
|
.I 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
|
|
.I localhost
|
|
by default. If no request options are given,
|
|
.I 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
|
|
.I localhost
|
|
when no other host is specified.
|
|
.I Xntpdc
|
|
will prompt for commands if the standard input is a terminal device.
|
|
.PP
|
|
.I 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.
|
|
.I 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.
|
|
.PP
|
|
Command line options are described following. Specifying a command
|
|
line option other than
|
|
.B -i
|
|
or
|
|
.B -n
|
|
will cause the specified query (queries) to be sent to the indicated
|
|
host(s) immediately. Otherwise,
|
|
.I xntpdc
|
|
will attempt to read interactive format commands from the standard input.
|
|
.Ip -c 8
|
|
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
|
|
.B -c
|
|
options may be given.
|
|
.Ip -i 8
|
|
Force
|
|
.I xntpdc
|
|
to operate in interactive mode. Prompts will be written to the
|
|
standard output and commands read from the standard input.
|
|
.Ip -l 8
|
|
Obtain a list of peers which are known to the server(s). This switch
|
|
is equivalent to \*(L"-c listpeers\*(R".
|
|
.Ip -n 8
|
|
Output all host addresses in dotted\-quad numeric format rather than
|
|
converting to the canonical host names.
|
|
.Ip -p 8
|
|
Print a list of the peers known to the server as well as a summary
|
|
of their state. This is equivalent to \*(L"-c peers\*(R".
|
|
.Ip -s 8
|
|
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
|
|
.B -p
|
|
switch. This is equivalent to \*(L"-c dmpeers\*(R".
|
|
.SH INTERNAL COMMANDS
|
|
.PP
|
|
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 \*(L">\*(R",
|
|
followed by a file name, to the command line.
|
|
.PP
|
|
A number of interactive format commands are executed entirely within the
|
|
.I xntpdc
|
|
program itself and do not result in NTP mode 7 requests being sent
|
|
to a server. These are described following.
|
|
.PP
|
|
.B ?
|
|
[
|
|
.I command_keyword
|
|
}
|
|
.PP
|
|
A \*(L"?\*(R" by itself will print a list of all the command keywords
|
|
known to this incarnation of
|
|
.IR xntpdc .
|
|
A \*(L"?\*(R" followed by a command keyword will print funcation and
|
|
usage information about the command. This command is probably a better
|
|
source of information about
|
|
.I xntpdc
|
|
than this manual page.
|
|
.PP
|
|
.B help
|
|
[
|
|
.I command_keyword
|
|
]
|
|
.PP
|
|
A synonym for the
|
|
.B ?
|
|
command.
|
|
.PP
|
|
.B timeout
|
|
.I millseconds
|
|
.PP
|
|
Specify a time out period for responses to server queries. The default
|
|
is about 8000 milliseconds.
|
|
.PP
|
|
.B delay
|
|
.I milliseconds
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B host
|
|
.I hostname
|
|
.PP
|
|
Set the host to which future queries will be sent.
|
|
.I Hostname
|
|
may be either a host name or a numeric
|
|
address.
|
|
.PP
|
|
.B poll
|
|
[
|
|
.I #
|
|
] [
|
|
.B verbose
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B keyid
|
|
.I #
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B passwd
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B "hostnames yes|no"
|
|
.PP
|
|
If \*(L"yes\*(R" is specified, host names are printed in information
|
|
displays. If \*(L"no\*(R" is given, numeric addresses are printed
|
|
instead. The default is \*(L"yes\*(R" unless modified using the command
|
|
line
|
|
.B -n
|
|
switch.
|
|
.PP
|
|
.B quit
|
|
.PP
|
|
Exit
|
|
.IR xntpdc .
|
|
.SH QUERY COMMANDS
|
|
.PP
|
|
Query commands result in NTP mode 7 packets containing requests for
|
|
information being sent to the server. These are \*(L"read\-only\*(R"
|
|
commands in that they make no modification of the server configuration
|
|
state.
|
|
.PP
|
|
.B listpeers
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B peers
|
|
.PP
|
|
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
|
|
\*(L"+\*(R" denotes symmetric active, a \*(L"-\*(R" indicates symmetric
|
|
passive, a \*(L"=\*(R" means the remote server is being polled in
|
|
client mode, a \*(L"^\*(R" indicates that the server is broadcasting
|
|
to this address, a \*(L"~\*(R" denotes that the remote peer is sending
|
|
broadcasts and a \*(L"*\*(R" marks the peer the server is currently
|
|
synchonizing to.
|
|
.PP
|
|
The contents of the host field may be one of four forms. It may be a host name,
|
|
an IP address, a reference clock implementation name with its parameter or
|
|
\*(L"REFCLK(<implementation number>, <parameter>)\*(R". On \*(L"hostnames no\*(R"
|
|
only IP\-addresses will be displayed.
|
|
.PP
|
|
.B dmpeers
|
|
.PP
|
|
A slightly different peer summary list. Identical to the output of the
|
|
.B 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 \*(L".\*(R" indicates that this
|
|
peer was cast off in the falseticker detection, while a \*(L"+\*(R"
|
|
indicates that the peer made it through. A \*(L"*\*(R" denotes the
|
|
peer the server is currently synchronizing with.
|
|
.PP
|
|
.B showpeer
|
|
.I peer_address
|
|
[
|
|
.I addr2
|
|
] [
|
|
.I addr3
|
|
] [
|
|
.I addr4
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B pstats
|
|
.I peer_address
|
|
[
|
|
.I addr2
|
|
] [
|
|
.I addr3
|
|
] [
|
|
.I addr4
|
|
]
|
|
.PP
|
|
Show per\-peer statistic counters associated with the specified peer(s).
|
|
.PP
|
|
.B loopinfo
|
|
[
|
|
.B oneline|multiline
|
|
]
|
|
.PP
|
|
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
|
|
\*(L"offset\*(R" is the last offset given to the loop filter by the
|
|
packet processing code. The \*(L"frequency\*(R" 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 \*(L"compliance\*(R" is actually
|
|
a long term average offset and is used by NTP to control the gain of
|
|
the loop filter. The \*(L"timer\*(R" value is the number of seconds
|
|
which have elapsed since a new sample offset was given to the loop
|
|
filter. The \*(L"oneline\*(R" and \*(L"multiline\*(R" options specify
|
|
the format in which this information is to be printed. \*(L"multiline\*(R"
|
|
is the default.
|
|
.PP
|
|
.B sysinfo
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B sysstats
|
|
.PP
|
|
Print a number of stat counters maintained in the protocol module.
|
|
.PP
|
|
.B memstats
|
|
.PP
|
|
Print a number of counters related to the peer memory allocation
|
|
code.
|
|
.PP
|
|
.B iostats
|
|
.PP
|
|
Print counters maintained in the input\-output module.
|
|
.PP
|
|
.B timerstats
|
|
.PP
|
|
Print counters maintained in the timer/event queue support code.
|
|
.PP
|
|
.B reslist
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B monlist
|
|
.PP
|
|
Obtain and print traffic counts collected and maintained by the
|
|
monitor facility.
|
|
.PP
|
|
.B clockinfo
|
|
.I clock_peer_address
|
|
[
|
|
.I addr2
|
|
] [
|
|
.I addr3
|
|
] [
|
|
.I addr4
|
|
]
|
|
.PP
|
|
Obtain and print information concerning a peer clock. The values
|
|
obtained provide information on the setting of fudge factors and
|
|
other clock performance information.
|
|
.PP
|
|
.B clkbug
|
|
.I clock_peer_address
|
|
[
|
|
.I addr2
|
|
] [
|
|
.I addr3
|
|
] [
|
|
.I addr4
|
|
]
|
|
.PP
|
|
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.
|
|
.SH RUNTIME CONFIGURATION REQUESTS
|
|
.PP
|
|
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
|
|
.IR xtnpdc .
|
|
This can be done using the
|
|
.B keyid
|
|
and
|
|
.B 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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The following commands all make authenticated requests.
|
|
.PP
|
|
.B addpeer
|
|
.I peer_address
|
|
[
|
|
.I keyid
|
|
] [
|
|
.I version#
|
|
] [
|
|
.B minpoll|prefer
|
|
]
|
|
.PP
|
|
Add a configured, symmetric active peer association with a peer at the
|
|
given address. If the optional \*(L"keyid\*(R" 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
|
|
\*(L"version#\*(R" can be 1 or 2, and defaults to 2. If \*(L"minpoll\*(R"
|
|
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. The prefer keyword indicates
|
|
a preferred peer (and thus will be used primarily for clock synchronisation
|
|
if possible). The preferred peer also determines the validity of the PPS
|
|
signal - if the preferred peer is suitable for synchronisation so is the
|
|
PPS signal.
|
|
.PP
|
|
.B addserver
|
|
.I peer_address
|
|
[
|
|
.I keyid
|
|
] [
|
|
.I version#
|
|
] [
|
|
.B minpoll|prefer
|
|
]
|
|
.PP
|
|
Identical to the
|
|
.B addpeer
|
|
command except that polling is done in client mode rather than
|
|
symmetric active mode.
|
|
.PP
|
|
.B broadcast
|
|
.I peer_address
|
|
[
|
|
.I keyid
|
|
] [
|
|
.I version#
|
|
] [
|
|
.B minpoll
|
|
]
|
|
.PP
|
|
Identical to the
|
|
.B addpeer
|
|
command except that packets are instead sent in broadcast mode. The
|
|
\*(L"peer_address\*(R" parameter will generally be a broadcast address
|
|
on one of your local networks.
|
|
.PP
|
|
.B unconfig
|
|
.I peer_address
|
|
[
|
|
.I addr2
|
|
] [
|
|
.I addr3
|
|
] [
|
|
.I addr4
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B set bclient|auth
|
|
[
|
|
.I ...
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B clear bclient|auth
|
|
[
|
|
.I ...
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B restrict
|
|
.I address
|
|
.I mask
|
|
.I flag
|
|
[
|
|
.I flag
|
|
]
|
|
.PP
|
|
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:
|
|
.Ip ignore 10
|
|
Ignore all packets from hosts which match this entry. If this flag
|
|
is specified neither queries nor time server polls will be responded
|
|
to.
|
|
.Ip noquery 10
|
|
Ignore all NTP mode 7 packets (i.e. information queries and configuration
|
|
requests) from the source. Time service is not affected.
|
|
.Ip nomodify 10
|
|
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.
|
|
.Ip noserve 10
|
|
Ignore NTP packets whose mode is other than 7. In effect, time service is
|
|
denied, though queries may still be permitted.
|
|
.Ip nopeer 10
|
|
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.
|
|
.Ip notrust 10
|
|
Treat these hosts normally in other respects, but never use them as
|
|
synchronization sources.
|
|
.Ip ntpport 10
|
|
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
|
|
\*(L"ntpport\*(R" and non\-\*(L"ntpport\*(R" may be specified. The
|
|
\*(L"ntpport\*(R" is considered more specific and is sorted later in the
|
|
list.
|
|
.PP
|
|
.B unrestrict
|
|
.I address
|
|
.I mask
|
|
.I flag
|
|
[
|
|
.I flag
|
|
]
|
|
.PP
|
|
Remove the specified flag(s) from the restrict list entry indicated
|
|
by the
|
|
.I address
|
|
and
|
|
.I mask
|
|
arguments.
|
|
.PP
|
|
.B delrestrict
|
|
.I address
|
|
.I mask
|
|
[
|
|
.B ntpport
|
|
]
|
|
.PP
|
|
Delete the matching entry from the restrict list.
|
|
.PP
|
|
.B "monitor yes|no"
|
|
.PP
|
|
Enable or disable the monitoring facility. Note that a
|
|
.B "monitor no"
|
|
command followed by a
|
|
.B "monitor yes"
|
|
command is a good way of resetting the packet counts.
|
|
.PP
|
|
.B readkeys
|
|
.PP
|
|
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
|
|
.I xntpd
|
|
configuration file). This allows encryption keys to be changed without
|
|
restarting the server.
|
|
.PP
|
|
.B trustkey
|
|
.I keyid
|
|
[
|
|
.I keyid
|
|
] [
|
|
.I keyid
|
|
] [
|
|
.I keyid
|
|
]
|
|
.PP
|
|
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.
|
|
.PP
|
|
.B untrustkey
|
|
.I keyid
|
|
[
|
|
.I keyid
|
|
] [
|
|
.I keyid
|
|
] [
|
|
.I keyid
|
|
]
|
|
.PP
|
|
Removes one or more keys from the trusted key list.
|
|
.PP
|
|
.B authinfo
|
|
.PP
|
|
Returns information concerning the authentication module, including
|
|
known keys and counts of encryptions and decryptions which have been
|
|
done.
|
|
.PP
|
|
.B setprecision
|
|
.I precision_value
|
|
.PP
|
|
Sets the precision which the server advertises to the specified value. This
|
|
should be a negative integer in the range -4 through -20.
|
|
.PP
|
|
.B setselect
|
|
.I algorithm_number
|
|
.PP
|
|
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.
|
|
.SH SEE ALSO
|
|
.PP
|
|
.IR xntpd (8)
|
|
.SH HISTORY
|
|
.PP
|
|
Written by Dennis Ferguson at the University of Toronto.
|
|
.SH BUGS
|
|
.PP
|
|
.I 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.
|