1106 lines
39 KiB
Groff
1106 lines
39 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.
|
|
''' Greek uppercase omega is used as a dummy character.
|
|
'''
|
|
.tr \(*W-|\(bv\*(Tr
|
|
.ie n \{\
|
|
.ds -- \(*W-
|
|
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\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 XNTPD 8 LOCAL
|
|
.SH NAME
|
|
xntpd - Network Time Protocol daemon
|
|
.SH SYNOPSIS
|
|
.B xntpd
|
|
[
|
|
.B -abdm
|
|
] [
|
|
.B -c
|
|
.I conffile
|
|
] [
|
|
.B -e
|
|
.I authdelay
|
|
] [
|
|
.B -f
|
|
.I driftfile
|
|
] [
|
|
.B -k
|
|
.I keyfile
|
|
] [
|
|
.B -p
|
|
.I pidfile
|
|
] [
|
|
.B -r
|
|
.I broadcastdelay
|
|
] [
|
|
.B -s
|
|
.I statsdir
|
|
] [
|
|
.B -t
|
|
.I trustedkey
|
|
] [
|
|
.B -v
|
|
.I variable
|
|
] [
|
|
.B -V
|
|
.I variable
|
|
]
|
|
.SH DESCRIPTION
|
|
.I xntpd
|
|
is a daemon which sets and maintains a Unix system time\-of\-day in
|
|
agreement with Internet standard time servers.
|
|
.I xntpd
|
|
is a complete implementation of the Network Time Protocol (NTP) version
|
|
3 standard, as defined by RFC 1305, but also retains compatability with
|
|
version 1 and 2 servers as defined by RFC 1059 and RFC 1119,
|
|
respectively.
|
|
.I xntpd
|
|
does all computations in fixed point arithmetic and requires no floating
|
|
point code. The computations done in the protocol and clock adjustment
|
|
code are carried out with high precision and with attention to the
|
|
details which might introduce systematic bias into the computations, to
|
|
try to maintain an accuracy suitable for synchronizing with even the
|
|
most precise external time source.
|
|
.PP
|
|
Ordinarily,
|
|
.I xntpd
|
|
reads its configuration from a configuration file at startup time. The
|
|
default configuration file name is
|
|
.IR /etc/ntp.conf,
|
|
although this may be overridden from the command line. It is also
|
|
possible to specify a working, although limited,
|
|
.I xntpd
|
|
configuration entirely on the command line, obviating the need for a
|
|
configuration file. This may be particularly appropriate when
|
|
.I xntpd
|
|
is to be configured as a broadcast or multicast client, with all peers
|
|
being determined by listening to broadcasts at run time. Various
|
|
internal
|
|
.I xntpd
|
|
variables can be displayed and configuration options altered while the
|
|
daemon is running through use of the
|
|
.IR ntpq (8)
|
|
and
|
|
.IR xntpdc (8)
|
|
programs.
|
|
.PP
|
|
The daemon can operate in any of several modes, including symmetric
|
|
active/passive, client/server and broadcast/multicast. A
|
|
broadcast/multicast client can automatically discover remote servers,
|
|
compute one-way delay correction factors and configure itself
|
|
automatically. This makes it possible to deploy a fleet of workstations
|
|
without specifying a configuration file or configuration details
|
|
specific to its environment.
|
|
.PP
|
|
The following command line arguments are understood by
|
|
.I xntpd
|
|
(see the configuration file description for a more complete functional
|
|
description):
|
|
.Ip -a 8
|
|
run in \*(L"authenticate\*(R" mode
|
|
.Ip -b 8
|
|
listen for broadcast NTP and sync to this if available
|
|
.Ip -c 8
|
|
specify an alternate configuration file
|
|
.Ip -d 8
|
|
specify debugging mode. This flag may occur multiple times, with each
|
|
occurance indicating greater detail of display.
|
|
.Ip -e 8
|
|
specify the time (in seconds) it takes to compute the NTP encryption
|
|
field on this computer
|
|
.Ip -f driftfile 8
|
|
specify the location of the drift file
|
|
.Ip -k 8
|
|
specify the location of the file which contains the NTP authentication
|
|
keys
|
|
.Ip -m 8
|
|
listen for multicast messages and synchronize to them if available
|
|
(requires multicast kernel)
|
|
.Ip -p 8
|
|
specify the name of the file to record the daemon's process id
|
|
.Ip -r 8
|
|
ordinarily, the daemon automatically compensates for the network delay
|
|
between the broadcast/multicast server and the client; if the
|
|
calibration procedure fails, use the specified the default delay (in
|
|
seconds)
|
|
.Ip -s 8
|
|
specify the directory to be used for creating statistics files
|
|
.Ip -t trustedkey 8
|
|
add a key number to the trusted key list
|
|
.Ip -v 8
|
|
add a system variable
|
|
.Ip -V 8
|
|
add a system variable listed by default
|
|
.SH "CONFIGURATION OPTIONS"
|
|
.I xntpd 's
|
|
configuration file format is similar to other Unix configuration files.
|
|
Comments begin with a \*(L"#\*(R" character and extend to the end of the
|
|
line. Blank lines are ignored. Configuration commands consist of an
|
|
initial keyword followed by a list of arguments, some of which may be
|
|
optional, separated by whitespace. These commands may not be continued
|
|
over multiple lines. Arguments may be host names, host addresses written
|
|
in numeric, dotted\-quad form, integers, floating point numbers (when
|
|
specifying times in seconds) and text strings. Optional arguments are
|
|
delimited by \*(L"[]\*(R" in the following descriptions, while
|
|
alternatives are separated by \*(L"|\*(R".
|
|
.PP
|
|
.B peer
|
|
.I host_address
|
|
[
|
|
.B key
|
|
.I #
|
|
] [
|
|
.B version
|
|
.I #
|
|
] [
|
|
.B prefer
|
|
]
|
|
.br
|
|
.B server
|
|
.I host_address
|
|
[
|
|
.B key
|
|
.I #
|
|
] [
|
|
.B version
|
|
.I #
|
|
] [
|
|
.B prefer
|
|
]
|
|
.br
|
|
.B broadcast
|
|
.I host_address
|
|
[
|
|
.B key
|
|
.I #
|
|
] [
|
|
.B version
|
|
.I #
|
|
] [
|
|
.B ttl
|
|
.I #
|
|
]
|
|
.PP
|
|
These three commands specify various time servers to be used and/or time
|
|
services to be provided. The
|
|
.B peer
|
|
command specifies that the local server is to operate in \*(L"symmetric
|
|
active\*(R" mode with the remote server
|
|
.I host_address
|
|
named in the command. In this mode the local server can be synchronized
|
|
to the remote server and, in addition, the remote server can be
|
|
synchronized by the local server. This is useful in a network of servers
|
|
where, depending on various failure scenarios, either the local or
|
|
remote server host may be the better source of time. The
|
|
.B server
|
|
command specifies that the local server is to operate in
|
|
\*(L"client\*(R" mode with the remote server named in the command. In
|
|
this mode the local server can be synchronized to the remote server, but
|
|
the remote server can never be synchronized to the local server. The
|
|
.B broadcast
|
|
command specifies that the local server is to operate in
|
|
\*(L"broadcast\*(R" mode where the local server sends periodic broadcast
|
|
messages to a client population at the broadcast/multicast address named
|
|
in the command. Ordinarily, this specification applies only to the local
|
|
server operating as a transmitter; for operation as a broadcast client,
|
|
see the
|
|
.B broadcastclient
|
|
or
|
|
.B multicastclient
|
|
commands elsewhere in this document. In this mode the
|
|
.I host_address
|
|
is usually the broadcast address on [one of] the local network[s] or a
|
|
multicast address assigned to NTP. The Numbers Czar has assigned the
|
|
address 224.0.1.1 to NTP; this is presently the only number that should
|
|
be used. Note that the use of multicast features requires a multicast
|
|
kernel, which is not yet ubiquitous in vendor products.
|
|
.PP
|
|
The
|
|
.B key
|
|
option, when included, indicates that all packets sent to the address
|
|
are to include authentication fields encrypted using the specified key
|
|
number (the range of which is that of an unsigned 32 bit integer). The
|
|
default is to not include an encryption field. The
|
|
.B version
|
|
option allows one to specify the version number to be used for outgoing
|
|
NTP packets. Versions 1, 2, and 3 are the choices, version 3 is the
|
|
default. The
|
|
.B prefer
|
|
option marks the host as a preferred host. All other things being equal,
|
|
this host will be chosen for synchronization among a set of correctly
|
|
operating hosts. The
|
|
.B ttl
|
|
option is used only with the broadcast mode. It specifies the time-to-
|
|
live (TTL) to use on multicast packets. Selection of the proper value,
|
|
which defaults to 127, is something of a black art and must be
|
|
coordinated with the network admistrator(s).
|
|
.PP
|
|
.B broadcastclient
|
|
.PP
|
|
This directs the local server to listen for broadcast messages on the
|
|
local network, in order to discover other servers on the same subnet.
|
|
Upon hearing a broadcast message for the first time, the local server
|
|
measures the nominal network delay using a brief client/server exchange
|
|
with the remote server, then enters the \*(L"broadcastclient\*(R" mode,
|
|
in which it listens for and synchronizes to succeeding broadcast
|
|
messages. Note that, in order to avoid accidental or malicious
|
|
disruption in this mode, both the local and remote servers must operate
|
|
using authentication and the same trusted key and key identifier.
|
|
.PP
|
|
.B multicastclient
|
|
[
|
|
.I IP address ...
|
|
]
|
|
.PP
|
|
This command is used in the same way as the
|
|
.IR broadcastclient
|
|
command, but operates using IP multicasting. Support for this function
|
|
requires a multicast kernel and the use of authentication. If one or
|
|
more IP addresses are given, the server joins the respective multicast
|
|
group(s). If none are given, the IP address assigned to NTP (224.0.1.1)
|
|
is assumed.
|
|
.PP
|
|
.B driftfile
|
|
.I filename
|
|
.PP
|
|
This command specifies the name of the file used to record the frequency
|
|
offset of the local clock oscillator. If the file exists, it is read at
|
|
startup in order to set the initial frequency offset and then updated
|
|
once per hour with the current offset computed by the daemon. If the
|
|
file does not exist or this command is not given, the initial frequency
|
|
offset is assumed zero. In this case, it may take some hours for the
|
|
frequency to stabilize and the residual timing errors to subside. The
|
|
file contains a single floating point value equal to the offset in
|
|
parts-per-million (ppm). Note that the file is updated by first writing
|
|
the current drift value into a temporary file and then using
|
|
.IR rename (3)
|
|
to replace the old version. This implies that
|
|
.I xntpd
|
|
must have write permission for the directory the drift file is located
|
|
in, and that file system links, symbolic or otherwise, should probably
|
|
be avoided.
|
|
.PP
|
|
.B enable auth|bclient|pll|monitor|stats
|
|
[
|
|
.I ...
|
|
]
|
|
.PP
|
|
Provides a way to enable various server options. Flags not mentioned are
|
|
unaffected. The \*(L"auth\*(R" flag causes the server to synchronize
|
|
with unconfigured peers only if the peer has been correctly
|
|
authenticated using a trusted key and key identifier. The default for
|
|
this flag is disable (off). The \*(L"bclient\*(R" flag causes the server
|
|
to listen for a message from a broadcast or multicast server, following
|
|
which an association is automatically instantiated for that server. The
|
|
default for this flag is disable (off). The \*(L"pll\*(R" flag enables
|
|
the server to adjust its local clock, with default enable (on). If not
|
|
set, the local clock free-runs at its intrinsic time and frequency
|
|
offset. This flag is useful in case the local clock is controlled by
|
|
some other device or protocol and NTP is used only to provide
|
|
synchronization to other clients. The \*(L"monitor\*(R" flag enables the
|
|
monitoring facility (see elsewhere), with default enable (on). The
|
|
\*(L"stats\*(R" flag enables statistics facility filegen (see
|
|
description elsewhere.), with default enable (on).
|
|
.PP
|
|
.B disable auth|bclient|pll|monitor|stats
|
|
[
|
|
.I ...
|
|
]
|
|
.PP
|
|
Provides a way to disable various server options. Flags not mentioned
|
|
are unaffected. The flags presently available are described under the
|
|
enable command.
|
|
|
|
.SH "AUTHENTICATION OPTIONS"
|
|
.PP
|
|
.B keys
|
|
.I filename
|
|
.PP
|
|
This command specifies the name of a file which contains the encryption
|
|
keys and key identifiers used by
|
|
.I xntpd
|
|
when operating in authenticated mode. The format of this file is
|
|
described later in this document.
|
|
.PP
|
|
.B trustedkey
|
|
.I #
|
|
[
|
|
.I "# ..."
|
|
]
|
|
.PP
|
|
This command is used to specify the encryption key identifiers which are
|
|
trusted for the purposes of authenticating peers suitable for
|
|
sychonization. The authentication procedures require that both the local
|
|
and remote servers share the same key and key identifier for this
|
|
purpose, although different keys can be used with different servers. The
|
|
arguments are 32 bit unsigned integers. Note, however, that NTP key 0 is
|
|
fixed and globally known. If meaningful authentication is to be
|
|
performed the 0 key should not be trusted.
|
|
.PP
|
|
.B requestkey
|
|
.I #
|
|
.PP
|
|
This command specifies the key identifier to use with the
|
|
.IR xntpdc (8)
|
|
program, which is useful to diagnose and repair problems that affect
|
|
.IR xntpd (8)
|
|
operation. The operation of the
|
|
.I xntpdc
|
|
program are specific to this particular implementation of xntpd and can
|
|
be expected to work only with this and previous versions of the daemon.
|
|
Requests from a remote xntpdc program which affect the state of the
|
|
local server must be authenticated, which requires bot the remote
|
|
program and local server share a common key and key identifier. The
|
|
argument to this command is a 32 bit unsigned integer. If no
|
|
.B requestkey
|
|
command is included in the configuration file, or if the keys don't
|
|
match, such requests will be ignored.
|
|
.PP
|
|
.B controlkey
|
|
.I #
|
|
.PP
|
|
This command specifies the key identifier to use with the
|
|
.IR ntpq (8)
|
|
program, which is useful to diagnose and repair problems that affect
|
|
.IR xntpd (8)
|
|
operation. The operation of the
|
|
.IR ntpq
|
|
program and
|
|
.I xntpd
|
|
conform to those specified in RFC 1305. Requests from a remote
|
|
.I ntpq
|
|
program which affect the state of the local server must be
|
|
authenticated, which requires bot the remote program and local server
|
|
share a common key and key identifier. The argument to this command is a
|
|
32 bit unsigned integer. If no
|
|
.B requestkey
|
|
command is included in the configuration file, or if the keys don't
|
|
match, such requests will be ignored.
|
|
.PP
|
|
.B authdelay
|
|
.I seconds
|
|
.PP
|
|
Indicates the amount of time it takes to encrypt an NTP authentication
|
|
field on the local computer. This value is used to correct transmit
|
|
timestamps when the authentication is used on outgoing packets. The
|
|
value usually lies somewhere in the range 0.0001 seconds to 0.003
|
|
seconds, though it is very dependent on the CPU speed of the host
|
|
computer. The value is usually computed using the
|
|
.I authspeed
|
|
program included with the distribution.
|
|
.SH "ACCESS CONTROL OPTIONS"
|
|
.B restrict
|
|
.I address
|
|
[
|
|
.B mask
|
|
.I numeric_mask
|
|
] [
|
|
.I flag
|
|
] [
|
|
.I ...
|
|
]
|
|
.PP
|
|
.I xntpd
|
|
implements a general purpose address\-and\-mask based restriction list.
|
|
The list is sorted by address and by mask, and the list is searched in
|
|
this order for matches, with the last match found defining the
|
|
restriction flags associated with the incoming packets. The source
|
|
address of incoming packets is used for the match, with the 32 bit
|
|
address being and'ed with the mask associated with the restriction entry
|
|
and then compared with the entry's address (which has also been and'ed
|
|
with the mask) to look for a match. The \*(L"mask\*(R" argument defaults
|
|
to 255.255.255.255, meaning that the \*(L"address\*(R" is treated as the
|
|
address of an individual host. A default entry (address 0.0.0.0, mask
|
|
0.0.0.0) is always included and, given the sort algorithm, is always the
|
|
first entry in the list. Note that, while \*(L"address\*(R" is normally
|
|
given in dotted\-quad format, the text string \*(L"default\*(R", with no
|
|
mask option, may be used to indicate the default entry.
|
|
.PP
|
|
In the current implementation, flags always restrict access, i.e. an
|
|
entry with no flags indicates that free access to the server is to be
|
|
given. The flags are not orthogonal, in that more restrictive flags will
|
|
often make less restrictive ones redundant. The flags can generally be
|
|
classed into two catagories, those which restrict time service and those
|
|
which restrict informational queries and attempts to do run time
|
|
reconfiguration of the server. One or more of the following flags may be
|
|
specified:
|
|
.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 6 and 7 packets (i.e. information queries and
|
|
configuration requests) from the source. Time service is not affected.
|
|
.Ip nomodify 10
|
|
Ignore all NTP mode 6 and 7 packets which attempt to modify the state of
|
|
the server (i.e. run time reconfiguration). Queries which return
|
|
information are permitted.
|
|
.Ip notrap 10
|
|
Decline to provide mode 6 control message trap service to matching
|
|
hosts. The trap service is a subsystem of the mode 6 control message
|
|
protocol which is intended for use by remote event logging programs.
|
|
.Ip lowpriotrap 10
|
|
Declare traps set by matching hosts to be low priority. The number of
|
|
traps a server can maintain is limited (the current limit is 3). Traps
|
|
are usually assigned on a first come, first served basis, with later
|
|
trap requestors being denied service. This flag modifies the assignment
|
|
algorithm by allowing low priority traps to be overridden by later
|
|
requests for normal priority traps.
|
|
.Ip noserve 10
|
|
Ignore NTP packets whose mode is other than 6 or 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 limited 10
|
|
These hosts are subject to limitation of number of clients from the same
|
|
net. Net in this context refers to the IP notion of net (class A, class
|
|
B, class C, etc.). Only the first \*(L"client_limit\*(R" hosts that have
|
|
shown up at the server and that have been active during the last
|
|
\*(L"client_limit_period\*(R" seconds are accepted. Requests from other
|
|
clients from the same net are rejected. Only time request packets are
|
|
taken into account. \*(L"Private\*(R", \*(L"control\*(R", and
|
|
\*(L"broadcast\*(R" packets are not subject to client limitation and
|
|
therefore are not contributing to client count. History of clients is
|
|
kept using the monitoring capability of
|
|
.I xntpd .
|
|
Thus, monitoring is active as long as there is a restriction entry with
|
|
the \*(L"limited\*(R" flag. The default value for \*(L"client_limit\*(R"
|
|
is 3. The default value for \*(L"client_limit_period\*(R" is 3600
|
|
seconds.
|
|
.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
|
|
Default restriction list entries, with the flags \*(L"ignore,
|
|
ntpport\*(R", for each of the local host's interface addresses are
|
|
inserted into the table at startup to prevent the server from attempting
|
|
to synchronize to its own time. A default entry is also always present,
|
|
though if it is otherwise unconfigured no flags are associated with the
|
|
default entry (i.e. everything besides your own NTP server is
|
|
unrestricted).
|
|
.PP
|
|
The restriction facility was added to allow the current access policies
|
|
of the time servers running on the NSFnet backbone to be implemented
|
|
with
|
|
.I xntpd
|
|
as well. While this facility may be otherwise useful for keeping
|
|
unwanted or broken remote time servers from affecting your own, it
|
|
should not be considered an alternative to the standard NTP
|
|
authentication facility. Source address based restrictions are easily
|
|
circumvented by a determined cracker.
|
|
.PP
|
|
.B clientlimit
|
|
.I limit
|
|
.PP
|
|
Sets \*(L"client_limit\*(R" to \*(L"limit\*(R", allows configuration of
|
|
client limitation policy. This variable defines the number of clients
|
|
from the same network that are allowed to use the server.
|
|
.PP
|
|
.B clientperiod
|
|
.I period
|
|
.PP
|
|
Sets \*(L"client_limit_period\*(R", allows configuration of client
|
|
limitation policy. This variable specifies the number of seconds after
|
|
which a client is considered inactive and thus no longer is counted for
|
|
client limit restriction.
|
|
.SH "MONITORING OPTIONS"
|
|
.PP
|
|
.B statsdir
|
|
.I /directory path/
|
|
.PP
|
|
Indicates the full path of a directory where statistics files should be
|
|
created (see below). This keyword allows the (otherwise constant)
|
|
filegen filename prefix to be modified for file generation sets used for
|
|
handling statistics logs (see
|
|
.B filegen
|
|
statement below).
|
|
.PP
|
|
.B statistics
|
|
.IR name \.\.\.
|
|
.PP
|
|
Enables writing of statistics records. Currently, three kinds of
|
|
statistics are supported.
|
|
.Ip loopstats 10
|
|
enables recording of loop filter statistics information. Each update of
|
|
the local clock outputs a line of the following form to the file
|
|
generation set named \*(L"loopstats\*(R":
|
|
.PP
|
|
.RS 5
|
|
48773 10847.650 0.0001307 17.3478 2
|
|
.RE
|
|
|
|
.RS 10
|
|
The first two fields show the date (Modified Julian Day) and time
|
|
(seconds and fraction past UTC midnight). The next three fields show
|
|
time offset in seconds, frequency offset in parts-per-million and time
|
|
constant of the clock-discipline algorithm at each update of the clock.
|
|
.RE
|
|
.Ip peerstats 10
|
|
enables recording of peer statistics information. This includes
|
|
statistics records of all peers of a NTP server and of the 1-pps signal,
|
|
where present and configured. Each valid update appends a line of the
|
|
following form to the current element of a file generation set named
|
|
\*(L"peerstats\*(R":
|
|
.PP
|
|
.RS 5
|
|
48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142
|
|
.RE
|
|
|
|
.RS 10
|
|
The first two fields show the date (Modified Julian Day) and time
|
|
(seconds and fraction past UTC midnight). The next two fields show the
|
|
peer address in dotted-quad notation and status, respectively. The
|
|
status field is encoded in hex in the format described in Appendix A of
|
|
the NTP specification RFC 1305. The final three fields show the offset,
|
|
delay and dispersion, all in seconds.
|
|
.RE
|
|
.Ip clockstats 10
|
|
enables recording of clock driver statistics information. Each update
|
|
received from a clock driver outputs a line of the following form to the
|
|
file generation set named \*(L"clockstats\*(R":
|
|
.PP
|
|
.RS 5
|
|
49213 525.624 127.127.4.1 93 226 00:08:29.606 D
|
|
.RE
|
|
|
|
.RS 10
|
|
The first two fields show the date (Modified Julian Day) and time
|
|
(seconds and fraction past UTC midnight). The next field shows the clock
|
|
address in dotted-quad notation, The final field shows the last timecode
|
|
received from the clock in decoded ASCII format, where meaningful. In
|
|
some clock drivers a good deal of additional information can be gathered
|
|
and displayed as well. See information specific to each clock for
|
|
further details.
|
|
.RE
|
|
.PP
|
|
Statistic files are managed using file generation sets (see
|
|
.B filegen
|
|
below). The information obtained by enabling statistics recording allows
|
|
analysis of temporal properties of a
|
|
.I xntpd
|
|
server. It is usually only useful to primary servers or maybe main
|
|
campus servers.
|
|
.PP
|
|
.B filegen
|
|
.I name
|
|
[
|
|
.B file
|
|
.I filename
|
|
] [
|
|
.B type
|
|
.I typename
|
|
] [
|
|
.B flag
|
|
.I flagval
|
|
] [
|
|
.BR link \| nolink
|
|
] [
|
|
.BR enable \| disable
|
|
]
|
|
.PP
|
|
Configures setting of generation file set
|
|
.IR name .
|
|
Generation file sets provide a means for handling files that are
|
|
continously growing during the lifetime of a server. Server statistics
|
|
are a typical example for such files. Generation file sets provide
|
|
access to a set of files used to store the actual data. At any time at
|
|
most one element of the set is being written to. The
|
|
.I type
|
|
given specifies when and how data will be directed to a new element of
|
|
the set. This way, information stored in elements of a file set that are
|
|
currently unused are available for administrational operations without
|
|
the risc of desturbing the operation of
|
|
.I xntpd .
|
|
(Most important: they can be removed to free space for new data
|
|
produced.) Filenames of set members are built from three elements.
|
|
.Ip prefix 10
|
|
This is a constant filename path. It is not subject to modifications via
|
|
the
|
|
.B filegen
|
|
statement. It is defined by the server, usually specified as a compile
|
|
time constant. It may, however, be configurable for individual file
|
|
generation sets via other commands. For example, the prefix used with
|
|
"loopstats" and "peerstats" filegens can be configured using the
|
|
.B statsdir
|
|
statement explained above.
|
|
.Ip filename 10
|
|
This string is directly concatenated to the
|
|
.I prefix
|
|
mentioned above (no intervening \*(L'/\*(R' (slash)). This can be
|
|
modified using the \*(L"file\*(R" argument to the \*(L"filegen\*(R"
|
|
statement. No \*(L"..\*(R" elements are allowed in this component to
|
|
prevent filenames referring to parts outside the filesystem hierarchy
|
|
denoted by \*(L"prefix\*(R".
|
|
.Ip suffix 10
|
|
This part is reflects individual elements of a file set. It is generated
|
|
according to the
|
|
.I type
|
|
of a file set as explained below.
|
|
.PP
|
|
A file generation set is characterized by its type. The following types
|
|
are supported:
|
|
.Ip none 10
|
|
The file set is actually a single plain file.
|
|
.Ip pid 10
|
|
One element of file set is used per incarnation of a
|
|
.I xntpd
|
|
server. This type does not perform any changes to file set members
|
|
during runtime, however it provides an easy way of seperating files
|
|
belonging to different
|
|
.I xntpd
|
|
server incarnations. The set member filename is built by appending a dot
|
|
(\*(L'.\*(R') to concatentated \*(L"prefix\*(R" and \*(L"filename\*(R"
|
|
strings, and appending the decimal representation of the process id of
|
|
the
|
|
.I xntpd
|
|
server process.
|
|
.Ip day 10
|
|
One file generation set element is created per day. The term
|
|
.I day
|
|
is based on
|
|
.IR UTC .
|
|
A day is defined as the period between 00:00 and 24:00 UTC. The file set
|
|
member suffix consists of a dot \*(L".\*(R" and a day specification in
|
|
the form
|
|
.RI < YYYYMMDD >.
|
|
.I YYYY
|
|
is a 4 digit year number (e.g. 1992).
|
|
.I MM
|
|
is a two digit month number.
|
|
.I DD
|
|
is a two digit day number. Thus, all information written at December
|
|
10th, 1992 would end up in a file named
|
|
\*(L"<prefix><filename>.19921210\*(R".
|
|
.Ip week 10
|
|
Any file set member contains data related to a certain week of a year.
|
|
The term
|
|
.I week
|
|
is definied by computing \*(L"day of year\*(R" modulo 7. Elements of
|
|
such a file generation set are distinguished by appending the following
|
|
suffix to the file set filename base: A dot, a four digit year number,
|
|
the letter \*(L"W\*(R", and a two digit week number. For example,
|
|
information from Jamuary, 10th 1992 would end up in a file with suffix
|
|
\*(L".1992W1\*(R".
|
|
.Ip month 10
|
|
One generation file set element is generated per month. The file name
|
|
suffix consists of a dot, a four digit year number, and a two digit
|
|
month.
|
|
.Ip year 10
|
|
One generation file elment is generated per year. The filename suffix
|
|
consists of a dot and a 4 digit year number.
|
|
.Ip age 10
|
|
This type of file generation sets changes to a new element of the file
|
|
set every 24 hours of server operation. The filename suffix consists of
|
|
a dot, the letter \*(L"a\*(R", and an eight digit number. This number is
|
|
taken to be the number of seconds the server is running at the start of
|
|
the corresponding 24 hour period.
|
|
.PP
|
|
Information is only written to a file generation set when this set is
|
|
\*(L"enabled\*(R". Output is prevented by specifying \*(L"disabled\*(R".
|
|
.PP
|
|
It is convenient to be able to access the
|
|
.I current
|
|
element of a file generation set by a fixed name. This feature is
|
|
enabled by specifying \*(L"link\*(R" and disabled using
|
|
\*(L"nolink\*(R". If \*(L"link\*(R" is specified, a hard link from the
|
|
current file set element to a file without suffix is created. When there
|
|
is already a file with this name and the number of links of this file is
|
|
one, it is renamed appending a dot, the letter \*(L"C\*(R", and the pid
|
|
of the
|
|
.I xntpd
|
|
server process. When the number of links is greater than one, the file
|
|
is unlinked. This allows the current file to be accessed by a constant
|
|
name.
|
|
.SH "MISCELLANEOUS OPTIONS"
|
|
.PP
|
|
.B precision
|
|
.I #
|
|
.PP
|
|
This command specifies the nominal precision of the local clock. The
|
|
value is an integer approximately equal to the base 2 logarithm of the
|
|
local timekeeping precision in seconds. Normally, the daemon determines
|
|
the precision automatically at startup, so this command is necessary
|
|
only in special cases when the precision cannot be determined
|
|
automatically.
|
|
.PP
|
|
.B broadcastdelay
|
|
.I seconds
|
|
.PP
|
|
The broadcast and multicast modes require a special calibration to
|
|
determine the network delay between the local and remote servers.
|
|
Ordinarily, this is done automatically by the initial protocol exchanges
|
|
between the local and remote servers. In some cases, the calibration
|
|
procedure may fail due to network or server access controls, for
|
|
example. This command specifies the default delay to be used under these
|
|
circumstances. Typically (for Ethernet), a number between 0.003 and
|
|
0.007 seconds is appropriate. The default when this command is not used
|
|
is 0.004 seconds.
|
|
.PP
|
|
.B trap
|
|
.I host_address
|
|
[
|
|
.B port
|
|
.I port_number
|
|
] [
|
|
.B interface
|
|
.I interface_addess
|
|
]
|
|
.PP
|
|
This command configures a trap receiver at the given host address and
|
|
port number for sending messages with the specified local interface
|
|
address. If the port number is unspecified a value of 18447 is used. If
|
|
the interface address is not specified the message is sent with a source
|
|
address which is that of the local interface the message is sent
|
|
through. Note that on a multihomed host the interface used may vary from
|
|
time to time with routing changes.
|
|
.PP
|
|
The trap receiver will generally log event messages and other
|
|
information from the server in a log file. While such monitor programs
|
|
may also request their own trap dynamically, configuring a trap receiver
|
|
will ensure that no messages are lost when the server is started.
|
|
.PP
|
|
.B setvar
|
|
.I variable
|
|
.I [default]
|
|
.PP
|
|
This command adds an additional system variable. These variables can be
|
|
used to distribute additional information such as the access policy. If
|
|
the variable of the from <name>=<value> is followed by the
|
|
.I default
|
|
keyword the variable will be listed as part of the default system
|
|
variables (
|
|
.I ntpq rv
|
|
command). These additional variables serve informational purposes only.
|
|
They are not related to the protocol other that they can be listed. The
|
|
known protocol variables will always overide any variables defined via
|
|
the
|
|
.I setvar
|
|
mechanism.
|
|
.PP
|
|
There are three special variables that contain the names of all variable
|
|
of the same group. The
|
|
.I sys_var_list
|
|
holds the names of all system variables. The
|
|
.I peer_var_list
|
|
holds the names of all peer variables and the
|
|
.I clock_var_list
|
|
hold the names of the reference clock variables.
|
|
.PP
|
|
.B monitor yes|no
|
|
.B authenticate yes|no
|
|
.PP
|
|
These commands have been superseded by the
|
|
.B enable
|
|
and
|
|
.B disable
|
|
commands. They are listed here for historical purposes.
|
|
.SH "AUTHENTICATION KEY FILE FORMAT"
|
|
.PP
|
|
The NTP standard specifies an extension allowing verification of the
|
|
authenticity of received NTP packets, and to provide an indication of
|
|
authenticity in outgoing packets. This is implemented in
|
|
.I xntpd
|
|
using the DES or MD5 algorithms to compute a digital signature, or
|
|
message-digest. The specification allows any one of possibly 4 billion
|
|
keys, numbered with 32 bit key identifiers, to be used to authenticate
|
|
an association. The servers involved in an association must agree on the
|
|
key and key identifier used to authenticate their data, though they must
|
|
each learn the key and key identifer independently. In the case of DES,
|
|
the keys are 56 bits long with, depending on type, a parity check on
|
|
each byte. In the case of MD5, the keys are 64 bits (8 bytes).
|
|
.I xntpd
|
|
reads its keys from a file specified using the
|
|
.B -k
|
|
command line option or the
|
|
.B keys
|
|
statement in the configuration file. While key number 0 is fixed by the
|
|
NTP standard (as 56 zero bits) and may not be changed, one or more of
|
|
the keys numbered 1 through 15 may be arbitrarily set in the keys file.
|
|
.PP
|
|
The key file uses the same comment conventions as the configuration
|
|
file. Key entries use a fixed format of the form
|
|
.Ip "" 5
|
|
.I "keyno type key"
|
|
.PP
|
|
where \*(L"keyno\*(R" is a positive integer, \*(L"type\*(R" is a single
|
|
character which defines the format the key is given in, and
|
|
\*(L"key\*(R" is the key itself.
|
|
.PP
|
|
The key may be given in one of three different formats, controlled by
|
|
the \*(L"type\*(R" character. The three key types, and corresponding
|
|
formats, are listed following.
|
|
.Ip "S" 5
|
|
The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified
|
|
in the DES document, that is the high order 7 bits of each octet are
|
|
used to form the 56 bit key while the low order bit of each octet is
|
|
given a value such that odd parity is maintained for the octet. Leading
|
|
zeroes must be specified (i.e. the key must be exactly 16 hex digits
|
|
long) and odd parity must be maintained. Hence a zero key, in standard
|
|
format, would be given as
|
|
.I 0101010101010101 .
|
|
.Ip "N" 5
|
|
The \*(L"key\*(R" is a 64 bit hexadecimal number in the format specified
|
|
in the NTP standard. This is the same as the DES format except the bits
|
|
in each octet have been rotated one bit right so that the parity bit is
|
|
now the high order bit of the octet. Leading zeroes must be specified
|
|
and odd parity must be maintained. A zero key in NTP format would be
|
|
specified as
|
|
.I 8080808080808080
|
|
.Ip "A" 5
|
|
The \*(L"key\*(R" is a 1\-to\-8 character ASCII string. A key is formed
|
|
from this by using the lower order 7 bits of the ASCII representation of
|
|
each character in the string, with zeroes being added on the right when
|
|
necessary to form a full width 56 bit key, in the same way that
|
|
encryption keys are formed from Unix passwords.
|
|
.Ip "M" 5
|
|
The \*(L"key\*(R" is a 1\-to\-8 character ASCII string, using the MD5
|
|
authentication scheme. Note that both the keys and the authentication
|
|
schemes (DES or MD5) must be identical between a set of peers sharing
|
|
the same key number.
|
|
.PP
|
|
One of the keys may be chosen,
|
|
by way of the configuration file
|
|
.B requestkey
|
|
statement, to authenticate run time configuration requests made using
|
|
the
|
|
.IR xntpdc (8)
|
|
program. The latter program obtains the key from the terminal as a
|
|
password, so it is generally appropriate to specify the key chosen to be
|
|
used for this purpose in ASCII format.
|
|
.SH PRIMARY CLOCK SUPPORT
|
|
.I xntpd
|
|
can be optionally compiled to include support for a number of types of
|
|
reference clocks. A reference clock will generally (though not always)
|
|
be a radio timecode receiver which is synchronized to a source of
|
|
standard time such as the services offered by the NRC in Canada and NIST
|
|
in the U.S. The interface between the computer and the timecode receiver
|
|
is device dependent and will vary, but is often a serial port.
|
|
.PP
|
|
Support for the various reference clock drivers is conditionally
|
|
compiled using the compiler define codes described elsewhere. An attempt
|
|
to configure a reference clock when specific support is not available or
|
|
the hardware port has not been appropriately configured results in a
|
|
scolding remark to the system log file, but is otherwise non hazardous.
|
|
.PP
|
|
For the purposes of configuration,
|
|
.I xntpd
|
|
treats reference clocks in a manner analogous to normal NTP peers as
|
|
much as possible. Reference clocks are referred to by address, much as a
|
|
normal peer is, though an invalid IP address is used to distinguish them
|
|
from normal peers. Reference clock addresses are of the form
|
|
.I 127.127.t.u
|
|
where
|
|
.I t
|
|
is an integer denoting the clock type and
|
|
.I u
|
|
indicates the type\-specific unit number. Reference clocks are
|
|
configured using a
|
|
.B server
|
|
statement in the configuration file where the
|
|
.I host_address
|
|
is the clock address. The
|
|
.I key,
|
|
.I version
|
|
and
|
|
.I ttl
|
|
options are not used for reference clock support; however, the
|
|
.I prefer
|
|
option can be useful to persuade the server to cherish a reference clock
|
|
with somewhat more enthusiasm than other reference clocks or peers, if
|
|
this is advisable. Clock addresses may generally be used anywhere in the
|
|
configuration file a normal IP address can be used, for example, in
|
|
.B restrict
|
|
statements, although such use would normally be considered strange.
|
|
.PP
|
|
Reference clock support provides the
|
|
.B fudge
|
|
command, which can be used to configure reference clocks in special
|
|
ways. Following is the generic format that applies to this command
|
|
.PP
|
|
.B fudge
|
|
.I 127.127.t.u
|
|
[
|
|
.B time1
|
|
.I secs
|
|
] [
|
|
.B time2
|
|
.I secs
|
|
] [
|
|
.B stratum
|
|
.I int
|
|
] [
|
|
.B refid
|
|
.I int
|
|
] [
|
|
.B flag1
|
|
.I 0|1
|
|
] [
|
|
.B flag2
|
|
.I 0|1
|
|
] [
|
|
.B flag3
|
|
.I 0|1
|
|
] [
|
|
.B flag4
|
|
.I 0|1
|
|
]
|
|
.PP
|
|
The
|
|
.I time1
|
|
and
|
|
.B time2
|
|
options are specified in fixed point seconds and used in some clock
|
|
drivers as calibration constants. By convention, and unless indicated
|
|
otherwise,
|
|
.B time1
|
|
is used as a calibration constant to adjust the nominal time offset of a
|
|
particular clock to agree with an external standard, such as a precision
|
|
PPS signal. The specified offset is in addition to the propagation delay
|
|
provided by other means, such as internal DIPswitches. The
|
|
.B stratum
|
|
option is a number in the range zero to 15 and is used to assign a
|
|
nonstandard operating stratum to the clock. The
|
|
.B refid
|
|
option is an ASCII string in the range one to four characters and is
|
|
used to assign a nonstandard reference identifier to the clock. Finally,
|
|
the four binary flags
|
|
.B flag1,
|
|
.B flag2,
|
|
.B flag3
|
|
and
|
|
.B flag4
|
|
are used for customizing the clock driver. The interpretation of these
|
|
values, and whether they are used at all, is a function of the needs of
|
|
the particular clock driver. However, by convention, and unless
|
|
indicated otherwise,
|
|
.B flag3
|
|
is used to attach the ppsclock streams module to the configured driver,
|
|
while
|
|
.B flag4
|
|
is used to enable recording verbose monitoring data to the clockstats
|
|
file configured with the
|
|
.I filegen
|
|
command. Further information on the ppsclock streams module is in the
|
|
README file in the ./kernel directory in the current xntp3 program
|
|
distribution. Further information on this feature is available in the
|
|
./scripts/stats directory in the same distribution.
|
|
.PP
|
|
Ordinarily, the stratum of a reference clock is by default zero. Since
|
|
the
|
|
.I xntpd
|
|
daemon adds one to the stratum of each peer, a primary server ordinarily
|
|
displays stratum one. In order to provide engineered backups, it is
|
|
often useful to specify the reference clock stratum as greater than
|
|
zero. The
|
|
.B stratum
|
|
option is used for this purpose. Also, in cases involving both a
|
|
reference clock and a 1-pps discipline signal, it is useful to specify
|
|
the reference clock identifier as other than the default, depending on
|
|
the driver. The
|
|
.I refid
|
|
option is used for this purpose. Except where noted, these options apply
|
|
to all clock drivers.
|
|
.PP
|
|
.I xntpd
|
|
on Unix machines currently supports several different types of clock
|
|
hardware plus a special pseudo\-clock used for backup or when no other
|
|
clock source is available. In the case of most of the clock drivers,
|
|
support for a 1-pps precision timing signal is available as described in
|
|
the README file in the ./doc directory of the xntp3 progam distribution.
|
|
The clock drivers, and the addresses used to configure them, are
|
|
described in the README.refclocks in the doc directory of the current
|
|
program distribution.
|
|
.PP
|
|
.SH VARIABLES
|
|
Most variables used by the NTP protocol can be examined with the
|
|
.I xntpdc
|
|
(mode 7 messages) and the
|
|
.I ntpq
|
|
(mode 6 messages). Currently very few variables can be modified via mode
|
|
6 messages. These variables are either created with the
|
|
.I setvar
|
|
directive or the leap warning variables. The leap warning bits that can
|
|
be set in the
|
|
.B leapwarning
|
|
variable (up to one month ahead). Both, the
|
|
.B leapwarning and in the
|
|
.B leapindication
|
|
variable, have a slightly different encoding than the usual
|
|
.B leap
|
|
bits interpretation:
|
|
.P
|
|
.Ip 00 8
|
|
The daemon passes the leap bits of its synchronisation source (usual
|
|
mode of operation).
|
|
.Ip 01/10 8
|
|
A leap second is added/deleted (operator forced leap second).
|
|
.Ip 11 8
|
|
Leap information from the sychronisation source is ignored (thus
|
|
LEAP_NOWARNING is passed on).
|
|
.PP
|
|
.SH FILES
|
|
.Ip /etc/ntp.conf 20
|
|
the default name of the configuration file
|
|
.Ip /etc/ntp.drift 20
|
|
the conventional name of the drift file
|
|
.Ip /etc/ntp.keys 20
|
|
the conventional name of the key file
|
|
.SH SEE ALSO
|
|
.PP
|
|
.IR xntpdc (8),
|
|
.IR ntpq (8),
|
|
.IR ntpdate (8)
|
|
.SH HISTORY
|
|
.PP
|
|
Written by Dennis Ferguson at the University of Toronto. Text amended by
|
|
David Mills at the University of Delaware.
|
|
.SH BUGS
|
|
.PP
|
|
.I xntpd
|
|
has gotten rather fat. While not huge, it has gotten larger than might
|
|
be desireable for an elevated\-priority daemon running on a workstation,
|
|
particularly since many of the fancy features which consume the space
|
|
were designed more with a busy primary server, rather than a high
|
|
stratum workstation, in mind.
|