freebsd-skq/usr.sbin/xntpd/doc/xntpd.8

1076 lines
38 KiB
Groff
Raw Normal View History

1998-02-19 08:05:46 +00:00
.\"
.\" $Id$
.\"
.Dd December 21, 1993
.Dt XNTPD 8
.Os
.Sh NAME
.Nm xntpd
.Nd Network Time Protocol daemon
.Sh SYNOPSIS
.Nm xntpd
.Op Fl abdm
.Op Fl c Ar conffile
.Op Fl e Ar authdelay
.Op Fl f Ar driftfile
.Op Fl k Ar keyfile
.Op Fl p Ar pidfile
.Op Fl r Ar broadcastdelay
.Op Fl s Ar statsdir
.Op Fl t Ar trustedkey
.Op Fl v Ar variable
.Op Fl V Ar variable
.Sh DESCRIPTION
.Nm Xntpd
1994-09-29 23:04:24 +00:00
is a daemon which sets and maintains a Unix system time\-of\-day in
agreement with Internet standard time servers.
1998-02-19 08:05:46 +00:00
.Nm Xntpd
1993-12-21 18:36:48 +00:00
is a complete implementation of the Network Time Protocol (NTP) version
1997-09-19 16:04:19 +00:00
3 standard, as defined by RFC 1305, but also retains compatibility with
1994-09-29 23:04:24 +00:00
version 1 and 2 servers as defined by RFC 1059 and RFC 1119,
respectively.
1998-02-19 08:05:46 +00:00
.Nm Xntpd
1994-09-29 23:04:24 +00:00
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
1993-12-21 18:36:48 +00:00
most precise external time source.
1998-02-19 08:05:46 +00:00
.Pp
1993-12-21 18:36:48 +00:00
Ordinarily,
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
reads its configuration from a configuration file at startup time. The
default configuration file name is
1998-02-19 08:05:46 +00:00
.Pa /etc/ntp.conf ,
1994-09-29 23:04:24 +00:00
although this may be overridden from the command line. It is also
possible to specify a working, although limited,
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
configuration entirely on the command line, obviating the need for a
1994-09-29 23:04:24 +00:00
configuration file. This may be particularly appropriate when
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
is to be configured as a broadcast or multicast client, with all peers
being determined by listening to broadcasts at run time. Various
internal
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
variables can be displayed and configuration options altered while the
1993-12-21 18:36:48 +00:00
daemon is running through use of the
1998-02-19 08:05:46 +00:00
.Xr ntpq 8
1993-12-21 18:36:48 +00:00
and
1998-02-19 08:05:46 +00:00
.Xr xntpdc 8
1993-12-21 18:36:48 +00:00
programs.
1998-02-19 08:05:46 +00:00
.Pp
1994-09-29 23:04:24 +00:00
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,
1996-11-03 12:25:21 +00:00
compute one-way delay correction factors and configure itself
1994-09-29 23:04:24 +00:00
automatically. This makes it possible to deploy a fleet of workstations
without specifying a configuration file or configuration details
specific to its environment.
1998-02-19 08:05:46 +00:00
.Pp
1993-12-21 18:36:48 +00:00
The following command line arguments are understood by
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
(see the configuration file description for a more complete functional
description):
1998-02-19 08:05:46 +00:00
.Bl -tag -width indent
.It Fl a
Run in
.Qq "authenticate"
mode.
.It Fl b
Listen for broadcast NTP and sync to this if available.
.It Fl c
Specify an alternate configuration file.
.It Fl d
Specify debugging mode. This flag may occur multiple times, with each
1994-09-29 23:04:24 +00:00
occurance indicating greater detail of display.
1998-02-19 08:05:46 +00:00
.It Fl e
Specify the time (in seconds) it takes to compute the NTP encryption
field on this computer.
.It Fl f Ar driftfile
Specify the location of the drift file.
.It Fl k
Specify the location of the file which contains the NTP authentication
keys.
.It Fl m
Listen for multicast messages and synchronize to them if available
(requires multicast kernel).
.It Fl p
Specify the name of the file to record the daemon's process id.
.It Fl r
Ordinarily, the daemon automatically compensates for the network delay
1994-09-29 23:04:24 +00:00
between the broadcast/multicast server and the client; if the
calibration procedure fails, use the specified the default delay (in
1998-02-19 08:05:46 +00:00
seconds).
.It Fl s
Specify the directory to be used for creating statistics files.
.It Fl t Ar trustedkey
Add a key number to the trusted key list.
.It Fl v
Add a system variable.
.It Fl V
Add a system variable listed by default.
.El
.Sh "CONFIGURATION OPTIONS"
.Nm Xntpd Ns 's
1994-09-29 23:04:24 +00:00
configuration file format is similar to other Unix configuration files.
1998-02-19 08:05:46 +00:00
Comments begin with a
.Qq #
character and extend to the end of the
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
delimited by
.Qq []
in the following descriptions, while
alternatives are separated by
.Qq \&| .
.Pp
.Bl -tag -width indent
.It Xo peer
.Ar host_address
.Op key Ar #
.Op version Ar #
.Op prefer
.Xc
.It Xo server
.Ar host_address
.Op key Ar #
.Op version Ar #
.Op prefer
.Xc
.It Xo broadcast
.Ar host_address
.Op key Ar #
.Op version Ar #
.Op ttl Ar #
.Xc
.Pp
1994-09-29 23:04:24 +00:00
These three commands specify various time servers to be used and/or time
services to be provided. The
1998-02-19 08:05:46 +00:00
.Em peer
command specifies that the local server is to operate in
.Qq symmetric active
mode with the remote server
.Ar host_address
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em server
1994-09-29 23:04:24 +00:00
command specifies that the local server is to operate in
1998-02-19 08:05:46 +00:00
.Qq client
mode with the remote server named in the command. In
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em broadcast
1994-09-29 23:04:24 +00:00
command specifies that the local server is to operate in
1998-02-19 08:05:46 +00:00
.Qq broadcast
mode where the local server sends periodic broadcast
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em broadcastclient
1994-09-29 23:04:24 +00:00
or
1998-02-19 08:05:46 +00:00
.Em multicastclient
1994-09-29 23:04:24 +00:00
commands elsewhere in this document. In this mode the
1998-02-19 08:05:46 +00:00
.Ar host_address
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.Pp
1993-12-21 18:36:48 +00:00
The
1998-02-19 08:05:46 +00:00
.Ar key
1993-12-21 18:36:48 +00:00
option, when included, indicates that all packets sent to the address
are to include authentication fields encrypted using the specified key
1994-09-29 23:04:24 +00:00
number (the range of which is that of an unsigned 32 bit integer). The
default is to not include an encryption field. The
1998-02-19 08:05:46 +00:00
.Ar version
1993-12-21 18:36:48 +00:00
option allows one to specify the version number to be used for outgoing
1994-09-29 23:04:24 +00:00
NTP packets. Versions 1, 2, and 3 are the choices, version 3 is the
default. The
1998-02-19 08:05:46 +00:00
.Ar prefer
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Ar 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,
1994-09-29 23:04:24 +00:00
which defaults to 127, is something of a black art and must be
coordinated with the network admistrator(s).
1998-02-19 08:05:46 +00:00
.It broadcastclient
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
with the remote server, then enters the
.Qq broadcastclient
mode,
1994-09-29 23:04:24 +00:00
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 with the same trusted key and key identifier.
1998-02-19 08:05:46 +00:00
.It multicastclient Op Ar IP address ...
1994-09-29 23:04:24 +00:00
This command is used in the same way as the
1998-02-19 08:05:46 +00:00
.Em broadcastclient
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It driftfile Ar filename
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Xr rename 3
1994-09-29 23:04:24 +00:00
to replace the old version. This implies that
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
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.
1998-02-19 08:05:46 +00:00
.It enable Ar auth|bclient|pll|monitor|stats Op Ar ...
Provide a way to enable various server options. Flags not mentioned are
unaffected. The
.Ar auth
flag causes the server to synchronize
1994-09-29 23:04:24 +00:00
with unconfigured peers only if the peer has been correctly
authenticated using a trusted key and key identifier. The default for
1998-02-19 08:05:46 +00:00
this flag is disable (off). The
.Ar bclient
flag causes the server
1994-09-29 23:04:24 +00:00
to listen for a message from a broadcast or multicast server, following
which an association is automatically instantiated for that server. The
1998-02-19 08:05:46 +00:00
default for this flag is disable (off). The
.Ar pll
flag enables
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
synchronization to other clients. The
.Ar monitor
flag enables the
1994-09-29 23:04:24 +00:00
monitoring facility (see elsewhere), with default enable (on). The
1998-02-19 08:05:46 +00:00
.Ar stats
flag enables statistics facility filegen (see
1994-09-29 23:04:24 +00:00
description elsewhere.), with default enable (on).
1998-02-19 08:05:46 +00:00
.It disable Ar auth|bclient|pll|monitor|stats Op Ar ...
Provide a way to disable various server options. Flags not mentioned
1994-09-29 23:04:24 +00:00
are unaffected. The flags presently available are described under the
enable command.
1998-02-19 08:05:46 +00:00
.El
.Sh "AUTHENTICATION OPTIONS"
.Bl -tag -width indent
.It keys Ar filename
1994-09-29 23:04:24 +00:00
This command specifies the name of a file which contains the encryption
keys and key identifiers used by
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
when operating in authenticated mode. The format of this file is
described later in this document.
1998-02-19 08:05:46 +00:00
.It trustedkey Ar # Op Ar # ...
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It requestkey Ar #
1994-09-29 23:04:24 +00:00
This command specifies the key identifier to use with the
1998-02-19 08:05:46 +00:00
.Xr xntpdc 8
1994-09-29 23:04:24 +00:00
program, which is useful to diagnose and repair problems that affect
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
operation. The operation of the
1998-02-19 08:05:46 +00:00
.Nm xntpdc
program are specific to this particular implementation of
.Nm
and can
1994-09-29 23:04:24 +00:00
be expected to work only with this and previous versions of the daemon.
Requests from a remote
1998-02-19 08:05:46 +00:00
.Nm xntpdc
program which affect the state of the
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em controlkey
1994-09-29 23:04:24 +00:00
command is included in the configuration file, or if the keys don't
match, such requests will be ignored.
1998-02-19 08:05:46 +00:00
.It controlkey Ar #
1994-09-29 23:04:24 +00:00
This command specifies the key identifier to use with the
1998-02-19 08:05:46 +00:00
.Xr ntpq 8
1994-09-29 23:04:24 +00:00
program, which is useful to diagnose and repair problems that affect
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
operation. The operation of the
1998-02-19 08:05:46 +00:00
.Nm ntpq
1994-09-29 23:04:24 +00:00
program and
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
conform to those specified in RFC 1305. Requests from a remote
1998-02-19 08:05:46 +00:00
.Nm ntpq
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em requestkey
1994-09-29 23:04:24 +00:00
command is included in the configuration file, or if the keys don't
match, such requests will be ignored.
1998-02-19 08:05:46 +00:00
.It authdelay Ar seconds
Indicate the amount of time it takes to encrypt an NTP authentication
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em authspeed
1994-09-29 23:04:24 +00:00
program included with the distribution.
1998-02-19 08:05:46 +00:00
.El
.Sh "ACCESS CONTROL OPTIONS"
.Bl -tag -width indent
.It Xo restrict
.Ar address
.Op mask Ar numeric_mask
.Op Ar flag
.Op Ar ...
.Xc
.Nm Xntpd
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
with the mask) to look for a match. The
.Em mask
argument defaults
to 255.255.255.255, meaning that the
.Em address
is treated as the
1994-09-29 23:04:24 +00:00
address of an individual host. A default entry (address 0.0.0.0, mask
1993-12-21 18:36:48 +00:00
0.0.0.0) is always included and, given the sort algorithm, is always the
1998-02-19 08:05:46 +00:00
first entry in the list. Note that, while
.Em address
is normally
given in dotted\-quad format, the text string
.Em default ,
with no
1994-09-29 23:04:24 +00:00
mask option, may be used to indicate the default entry.
1998-02-19 08:05:46 +00:00
.Pp
1994-09-29 23:04:24 +00:00
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:
1998-02-19 08:05:46 +00:00
.Bl -tag -width indent
.It ignore
1994-09-29 23:04:24 +00:00
Ignore all packets from hosts which match this entry. If this flag is
specified neither queries nor time server polls will be responded to.
1998-02-19 08:05:46 +00:00
.It noquery
1994-09-29 23:04:24 +00:00
Ignore all NTP mode 6 and 7 packets (i.e. information queries and
configuration requests) from the source. Time service is not affected.
1998-02-19 08:05:46 +00:00
.It nomodify
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It notrap
1993-12-21 18:36:48 +00:00
Decline to provide mode 6 control message trap service to matching
1994-09-29 23:04:24 +00:00
hosts. The trap service is a subsystem of the mode 6 control message
1993-12-21 18:36:48 +00:00
protocol which is intended for use by remote event logging programs.
1998-02-19 08:05:46 +00:00
.It lowpriotrap
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It noserve
1994-09-29 23:04:24 +00:00
Ignore NTP packets whose mode is other than 6 or 7. In effect, time
service is denied, though queries may still be permitted.
1998-02-19 08:05:46 +00:00
.It nopeer
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It notrust
1993-12-21 18:36:48 +00:00
Treat these hosts normally in other respects, but never use them as
synchronization sources.
1998-02-19 08:05:46 +00:00
.It limited
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
B, class C, etc.). Only the first
.Qq client_limit
hosts that have
1994-09-29 23:04:24 +00:00
shown up at the server and that have been active during the last
1998-02-19 08:05:46 +00:00
.Qq client_limit_period
seconds are accepted. Requests from other
1994-09-29 23:04:24 +00:00
clients from the same net are rejected. Only time request packets are
1998-02-19 08:05:46 +00:00
taken into account.
.Qq Private ,
.Qq control ,
and
.Qq broadcast
packets are not subject to client limitation and
1994-09-29 23:04:24 +00:00
therefore are not contributing to client count. History of clients is
kept using the monitoring capability of
1998-02-19 08:05:46 +00:00
.Nm Ns .
1994-09-29 23:04:24 +00:00
Thus, monitoring is active as long as there is a restriction entry with
1998-02-19 08:05:46 +00:00
the
.Qq limited
flag. The default value for
.Qq client_limit
is 3. The default value for
.Qq client_limit_period
is 3600 seconds.
.It ntpport
1993-12-21 18:36:48 +00:00
This is actually a match algorithm modifier, rather than a restriction
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Qq ntpport
and
.Pf non\- Qq ntpport
may be specified. The
.Qq ntpport
is considered more specific and is sorted later in the
1993-12-21 18:36:48 +00:00
list.
1998-02-19 08:05:46 +00:00
.El
.Pp
Default restriction list entries, with the flags
.Qq ignore ,
.Qq ntpport ,
for each of the local host's interface addresses are
1994-09-29 23:04:24 +00:00
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).
1998-02-19 08:05:46 +00:00
.Pp
1993-12-21 18:36:48 +00:00
The restriction facility was added to allow the current access policies
1994-09-29 23:04:24 +00:00
of the time servers running on the NSFnet backbone to be implemented
with
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It clientlimit Ar limit
Set
.Qq client_limit
to
.Ar limit ,
allow configuration of
1994-09-29 23:04:24 +00:00
client limitation policy. This variable defines the number of clients
from the same network that are allowed to use the server.
1998-02-19 08:05:46 +00:00
.It clientperiod Ar period
Set
.Qq client_limit_period ,
allow configuration of client
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.El
.Sh "MONITORING OPTIONS"
.Bl -tag -width indent
.It statsdir Ar /directory path/
Indicate the full path of a directory where statistics files should be
1994-09-29 23:04:24 +00:00
created (see below). This keyword allows the (otherwise constant)
filegen filename prefix to be modified for file generation sets used for
1993-12-21 18:36:48 +00:00
handling statistics logs (see
1998-02-19 08:05:46 +00:00
.Em filegen
1993-12-21 18:36:48 +00:00
statement below).
1998-02-19 08:05:46 +00:00
.It statistics Ar name Ns ...
Enable writing of statistics records. Currently, three kinds of
statistics are supported:
.Bl -tag -width indent
.It loopstats
Enable recording of loop filter statistics information. Each update of
1994-09-29 23:04:24 +00:00
the local clock outputs a line of the following form to the file
1998-02-19 08:05:46 +00:00
generation set named
.Qq loopstats :
.Dl 48773 10847.650 0.0001307 17.3478 2
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It peerstats
Enable recording of peer statistics information. This includes
1993-12-21 18:36:48 +00:00
statistics records of all peers of a NTP server and of the 1-pps signal,
1994-09-29 23:04:24 +00:00
where present and configured. Each valid update appends a line of the
following form to the current element of a file generation set named
1998-02-19 08:05:46 +00:00
.Qq peerstats :
.Dl 48773 10847.650 127.127.4.1 9714 -0.001605 0.00000 0.00142
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It clockstats
Enable recording of clock driver statistics information. Each update
1993-12-21 18:36:48 +00:00
received from a clock driver outputs a line of the following form to the
1998-02-19 08:05:46 +00:00
file generation set named
.Qq clockstats :
.Dl 49213 525.624 127.127.4.1 93 226 00:08:29.606 D
1994-09-29 23:04:24 +00:00
The first two fields show the date (Modified Julian Day) and time
(seconds and fraction past UTC midnight). The next field shows the clock
1993-12-21 18:36:48 +00:00
address in dotted-quad notation, The final field shows the last timecode
1998-02-19 08:05:46 +00:00
received from the clock in decoded
.Tn ASCII
format, where meaningful. In
1993-12-21 18:36:48 +00:00
some clock drivers a good deal of additional information can be gathered
1994-09-29 23:04:24 +00:00
and displayed as well. See information specific to each clock for
further details.
1998-02-19 08:05:46 +00:00
.El
.Pp
1994-09-29 23:04:24 +00:00
Statistic files are managed using file generation sets (see
1998-02-19 08:05:46 +00:00
.Em filegen
1994-09-29 23:04:24 +00:00
below). The information obtained by enabling statistics recording allows
analysis of temporal properties of a
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
server. It is usually only useful to primary servers or maybe main
campus servers.
1998-02-19 08:05:46 +00:00
.It Xo filegen
.Ar name
.Op file Ar filename
.Op type Ar typename
.Op flag Ar flagval
.Op link | nolink
.Op enable | disable
.Xc
Configure setting of generation file set
.Ar name .
1993-12-21 18:36:48 +00:00
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
1994-09-29 23:04:24 +00:00
most one element of the set is being written to. The
1998-02-19 08:05:46 +00:00
.Em type
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Nm Ns .
1993-12-21 18:36:48 +00:00
(Most important: they can be removed to free space for new data
1998-02-19 08:05:46 +00:00
produced.) Filenames of set members are built from three elements:
.Bl -tag -width indent
.It prefix
1994-09-29 23:04:24 +00:00
This is a constant filename path. It is not subject to modifications via
the
1998-02-19 08:05:46 +00:00
.Em filegen
1993-12-21 18:36:48 +00:00
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
1998-02-19 08:05:46 +00:00
.Qq loopstats
and
.Qq peerstats
filegens can be configured using the
.Em statsdir
1993-12-21 18:36:48 +00:00
statement explained above.
1998-02-19 08:05:46 +00:00
.It filename
1993-12-21 18:36:48 +00:00
This string is directly concatenated to the
1998-02-19 08:05:46 +00:00
.Em prefix
mentioned above (no intervening
.Sq /
(slash)). This can be
modified using the
.Ar file
argument to the
.Em filegen
statement. No
.Qq ..
elements are allowed in this component to
1993-12-21 18:36:48 +00:00
prevent filenames referring to parts outside the filesystem hierarchy
1998-02-19 08:05:46 +00:00
denoted by
.Em prefix .
.It suffix
1993-12-21 18:36:48 +00:00
This part is reflects individual elements of a file set. It is generated
1994-09-29 23:04:24 +00:00
according to the
1998-02-19 08:05:46 +00:00
.Em type
1993-12-21 18:36:48 +00:00
of a file set as explained below.
1998-02-19 08:05:46 +00:00
.El
.Pp
1994-09-29 23:04:24 +00:00
A file generation set is characterized by its type. The following types
are supported:
1998-02-19 08:05:46 +00:00
.Bl -tag -width indent
.It none
1993-12-21 18:36:48 +00:00
The file set is actually a single plain file.
1998-02-19 08:05:46 +00:00
.It pid
1993-12-21 18:36:48 +00:00
One element of file set is used per incarnation of a
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
server. This type does not perform any changes to file set members
during runtime, however it provides an easy way of seperating files
1994-09-29 23:04:24 +00:00
belonging to different
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
server incarnations. The set member filename is built by appending a dot
1998-02-19 08:05:46 +00:00
.Pf ( Sq \&. Ns )
to concatentated
.Em prefix
and
.Em filename
1994-09-29 23:04:24 +00:00
strings, and appending the decimal representation of the process id of
the
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
server process.
1998-02-19 08:05:46 +00:00
.It day
1993-12-21 18:36:48 +00:00
One file generation set element is created per day. The term
1998-02-19 08:05:46 +00:00
.Em day
1994-09-29 23:04:24 +00:00
is based on
1998-02-19 08:05:46 +00:00
.Tn UTC .
A day is defined as the period between 00:00 and 24:00
.Tn UTC .
The file set
member suffix consists of a dot
.Pf ( Qq \&. Ns )
and a day specification in
1994-09-29 23:04:24 +00:00
the form
1998-02-19 08:05:46 +00:00
.Aq YYYYMMDD .
.Em YYYY
1993-12-21 18:36:48 +00:00
is a 4 digit year number (e.g. 1992).
1998-02-19 08:05:46 +00:00
.Em MM
1993-12-21 18:36:48 +00:00
is a two digit month number.
1998-02-19 08:05:46 +00:00
.Em DD
1994-09-29 23:04:24 +00:00
is a two digit day number. Thus, all information written at December
10th, 1992 would end up in a file named
1998-02-19 08:05:46 +00:00
.Qq <prefix><filename>.19921210 .
.It week
1993-12-21 18:36:48 +00:00
Any file set member contains data related to a certain week of a year.
The term
1998-02-19 08:05:46 +00:00
.Em week
is definied by computing
.Qq day of year
modulo 7. Elements of
1994-09-29 23:04:24 +00:00
such a file generation set are distinguished by appending the following
1998-02-19 08:05:46 +00:00
suffix to the file set filename base: a dot, a four digit year number,
the letter
.Qq W ,
and a two digit week number. For example,
1994-09-29 23:04:24 +00:00
information from Jamuary, 10th 1992 would end up in a file with suffix
1998-02-19 08:05:46 +00:00
.Qq .1992W1 .
.It month
1993-12-21 18:36:48 +00:00
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.
1998-02-19 08:05:46 +00:00
.It year
One generation file element is generated per year. The filename suffix
1993-12-21 18:36:48 +00:00
consists of a dot and a 4 digit year number.
1998-02-19 08:05:46 +00:00
.It age
1993-12-21 18:36:48 +00:00
This type of file generation sets changes to a new element of the file
1994-09-29 23:04:24 +00:00
set every 24 hours of server operation. The filename suffix consists of
1998-02-19 08:05:46 +00:00
a dot, the letter
.Qq a ,
and an eight digit number. This number is
1994-09-29 23:04:24 +00:00
taken to be the number of seconds the server is running at the start of
the corresponding 24 hour period.
1998-02-19 08:05:46 +00:00
.El
.Pp
1993-12-21 18:36:48 +00:00
Information is only written to a file generation set when this set is
1998-02-19 08:05:46 +00:00
.Qq enabled .
Output is prevented by specifying
.Qq disabled .
.Pp
1994-09-29 23:04:24 +00:00
It is convenient to be able to access the
1998-02-19 08:05:46 +00:00
.Em current
1993-12-21 18:36:48 +00:00
element of a file generation set by a fixed name. This feature is
1998-02-19 08:05:46 +00:00
enabled by specifying
.Qq link
and disabled using
.Qq nolink .
If
.Qq link
is specified, a hard link from the
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
one, it is renamed appending a dot, the letter
.Qq C ,
and the pid
1994-09-29 23:04:24 +00:00
of the
1998-02-19 08:05:46 +00:00
.Nm
1993-12-21 18:36:48 +00:00
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
1994-09-29 23:04:24 +00:00
name.
1998-02-19 08:05:46 +00:00
.El
.Sh "MISCELLANEOUS OPTIONS"
.Bl -tag -width indent
.It precision Ar #
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It broadcastdelay Ar seconds
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It Xo trap
.Ar host_address
.Op port Ar port_number
.Op interface Ar interface_addess
.Xc
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.Pp
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.It Xo setvar
.Ar variable
.Op Ar default
.Xc
1994-09-29 23:04:24 +00:00
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 form <name>=<value> is followed by the
1998-02-19 08:05:46 +00:00
.Em default
1994-09-29 23:04:24 +00:00
keyword the variable will be listed as part of the default system
1998-02-19 08:05:46 +00:00
variables
.Pf ( Nm ntpq
rv command). These additional variables serve informational purposes only.
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em setvar
1994-09-29 23:04:24 +00:00
mechanism.
1998-02-19 08:05:46 +00:00
.Pp
1994-09-29 23:04:24 +00:00
There are three special variables that contain the names of all variable
of the same group. The
1998-02-19 08:05:46 +00:00
.Em sys_var_list
1994-09-29 23:04:24 +00:00
holds the names of all system variables. The
1998-02-19 08:05:46 +00:00
.Em peer_var_list
1994-09-29 23:04:24 +00:00
holds the names of all peer variables and the
1998-02-19 08:05:46 +00:00
.Em clock_var_list
1994-09-29 23:04:24 +00:00
hold the names of the reference clock variables.
1998-02-19 08:05:46 +00:00
.It monitor Ar yes|no
.It authenticate Ar yes|no
1994-09-29 23:04:24 +00:00
These commands have been superseded by the
1998-02-19 08:05:46 +00:00
.Em enable
1994-09-29 23:04:24 +00:00
and
1998-02-19 08:05:46 +00:00
.Em disable
1994-09-29 23:04:24 +00:00
commands. They are listed here for historical purposes.
1998-02-19 08:05:46 +00:00
.El
.Sh "AUTHENTICATION KEY FILE FORMAT"
The
.Tn NTP
standard specifies an extension allowing verification of the
1994-09-29 23:04:24 +00:00
authenticity of received NTP packets, and to provide an indication of
authenticity in outgoing packets. This is implemented in
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
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).
1998-02-19 08:05:46 +00:00
.Nm Xntpd
1993-12-21 18:36:48 +00:00
reads its keys from a file specified using the
1998-02-19 08:05:46 +00:00
.Fl k
1993-12-21 18:36:48 +00:00
command line option or the
1998-02-19 08:05:46 +00:00
.Em keys
1994-09-29 23:04:24 +00:00
statement in the configuration file. While key number 0 is fixed by the
1998-02-19 08:05:46 +00:00
.Tn NTP
standard (as 56 zero bits) and may not be changed, one or more of
1993-12-21 18:36:48 +00:00
the keys numbered 1 through 15 may be arbitrarily set in the keys file.
1998-02-19 08:05:46 +00:00
.Pp
1993-12-21 18:36:48 +00:00
The key file uses the same comment conventions as the configuration
1998-02-19 08:05:46 +00:00
file. Key entries use a fixed format of the form:
.Pp
.Dl keyno type key
.Pp
where
.Em keyno
is a positive integer,
.Em type
is a single
1994-09-29 23:04:24 +00:00
character which defines the format the key is given in, and
1998-02-19 08:05:46 +00:00
.Em key
is the key itself.
.Pp
1993-12-21 18:36:48 +00:00
The key may be given in one of three different formats, controlled by
1998-02-19 08:05:46 +00:00
the
.Em type
character. The three key types, and corresponding
formats, are listed following:
.Bl -tag -width indent
.It S
The
.Em key
is a 64 bit hexadecimal number in the format specified
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em 0101010101010101 .
.It N
The
.Em key
is a 64 bit hexadecimal number in the format specified
in the
.Tn NTP
standard. This is the same as the DES format except the bits
1993-12-21 18:36:48 +00:00
in each octet have been rotated one bit right so that the parity bit is
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em 8080808080808080 .
.It A
The
.Em key
is a 1\-to\-8 character
.Tn ASCII
string. A key is formed from this by using the lower order 7 bits of the
.Tn ASCII
representation of
1994-09-29 23:04:24 +00:00
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
1993-12-21 18:36:48 +00:00
encryption keys are formed from Unix passwords.
1998-02-19 08:05:46 +00:00
.It M
The
.Em key
is a 1\-to\-8 character
.Tn ASCII
string, using the MD5
1994-09-29 23:04:24 +00:00
authentication scheme. Note that both the keys and the authentication
schemes (DES or MD5) must be identical between a set of peers sharing
1993-12-21 18:36:48 +00:00
the same key number.
1998-02-19 08:05:46 +00:00
.El
.Pp
1993-12-21 18:36:48 +00:00
One of the keys may be chosen,
by way of the configuration file
1998-02-19 08:05:46 +00:00
.Em requestkey
1994-09-29 23:04:24 +00:00
statement, to authenticate run time configuration requests made using
the
1998-02-19 08:05:46 +00:00
.Xr xntpdc 8
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
used for this purpose in
.Tn ASCII
format.
.Sh PRIMARY CLOCK SUPPORT
.Nm Xntpd
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.Pp
1994-09-29 23:04:24 +00:00
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.
1998-02-19 08:05:46 +00:00
.Pp
1993-12-21 18:36:48 +00:00
For the purposes of configuration,
1998-02-19 08:05:46 +00:00
.Nm
treats reference clocks in a manner analogous to normal
.Tn NTP
peers as
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em 127.127.t.u
1993-12-21 18:36:48 +00:00
where
1998-02-19 08:05:46 +00:00
.Em t
1993-12-21 18:36:48 +00:00
is an integer denoting the clock type and
1998-02-19 08:05:46 +00:00
.Em u
1994-09-29 23:04:24 +00:00
indicates the type\-specific unit number. Reference clocks are
configured using a
1998-02-19 08:05:46 +00:00
.Em server
1994-09-29 23:04:24 +00:00
statement in the configuration file where the
1998-02-19 08:05:46 +00:00
.Em host_address
1994-09-29 23:04:24 +00:00
is the clock address. The
1998-02-19 08:05:46 +00:00
.Em key,
.Em version
1994-09-29 23:04:24 +00:00
and
1998-02-19 08:05:46 +00:00
.Em ttl
1994-09-29 23:04:24 +00:00
options are not used for reference clock support; however, the
1998-02-19 08:05:46 +00:00
.Em prefer
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em restrict
1994-09-29 23:04:24 +00:00
statements, although such use would normally be considered strange.
1998-02-19 08:05:46 +00:00
.Pp
1994-09-29 23:04:24 +00:00
Reference clock support provides the
1998-02-19 08:05:46 +00:00
.Em fudge
1994-09-29 23:04:24 +00:00
command, which can be used to configure reference clocks in special
1998-02-19 08:05:46 +00:00
ways. Following is the generic format that applies to this command:
.Pp
fudge
.Ar 127.127.t.u
.Op time1 Ar secs
.Op time2 Ar secs
.Op stratum Ar int
.Op refid Ar int
.Op flag1 Ar 0|1
.Op flag2 Ar 0|1
.Op flag3 Ar 0|1
.Op flag4 Ar 0|1
.Pp
1993-12-21 18:36:48 +00:00
The
1998-02-19 08:05:46 +00:00
.Em time1
1994-09-29 23:04:24 +00:00
and
1998-02-19 08:05:46 +00:00
.Em time2
1994-09-29 23:04:24 +00:00
options are specified in fixed point seconds and used in some clock
drivers as calibration constants. By convention, and unless indicated
otherwise,
1998-02-19 08:05:46 +00:00
.Em time1
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em stratum
1994-09-29 23:04:24 +00:00
option is a number in the range zero to 15 and is used to assign a
nonstandard operating stratum to the clock. The
1998-02-19 08:05:46 +00:00
.Em refid
option is an
.Tn ASCII
string in the range one to four characters and is
1994-09-29 23:04:24 +00:00
used to assign a nonstandard reference identifier to the clock. Finally,
the four binary flags
1998-02-19 08:05:46 +00:00
.Em flag1,
.Em flag2,
.Em flag3
1994-09-29 23:04:24 +00:00
and
1998-02-19 08:05:46 +00:00
.Em flag4
1994-09-29 23:04:24 +00:00
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,
1998-02-19 08:05:46 +00:00
.Em flag3
1994-09-29 23:04:24 +00:00
is used to attach the ppsclock streams module to the configured driver,
while
1998-02-19 08:05:46 +00:00
.Em flag4
1994-09-29 23:04:24 +00:00
is used to enable recording verbose monitoring data to the clockstats
file configured with the
1998-02-19 08:05:46 +00:00
.Em filegen
1994-09-29 23:04:24 +00:00
command. Further information on the ppsclock streams module is in the
1998-02-19 08:05:46 +00:00
.Pa README
file in the
.Pa ./kernel
directory in the current xntp3 program
1994-09-29 23:04:24 +00:00
distribution. Further information on this feature is available in the
1998-02-19 08:05:46 +00:00
.Pa ./scripts/stats
directory in the same distribution.
.Pp
1994-09-29 23:04:24 +00:00
Ordinarily, the stratum of a reference clock is by default zero. Since
the
1998-02-19 08:05:46 +00:00
.Nm
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em stratum
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
.Em refid
1994-09-29 23:04:24 +00:00
option is used for this purpose. Except where noted, these options apply
to all clock drivers.
1998-02-19 08:05:46 +00:00
.Pp
.Nm Xntpd
1994-09-29 23:04:24 +00:00
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
1998-02-19 08:05:46 +00:00
the
.Pa README
file in the
.Pa ./doc
directory of the xntp3 progam distribution.
1994-09-29 23:04:24 +00:00
The clock drivers, and the addresses used to configure them, are
1998-02-19 08:05:46 +00:00
described in the
.Pa README.refclocks
in the
.Pa doc
directory of the current
1994-09-29 23:04:24 +00:00
program distribution.
1998-02-19 08:05:46 +00:00
.Sh VARIABLES
Most variables used by the
.Tn NTP
protocol can be examined with the
.Nm xntpdc
1994-09-29 23:04:24 +00:00
(mode 7 messages) and the
1998-02-19 08:05:46 +00:00
.Nm ntpq
1994-09-29 23:04:24 +00:00
(mode 6 messages). Currently very few variables can be modified via mode
6 messages. These variables are either created with the
1998-02-19 08:05:46 +00:00
.Em setvar
1994-09-29 23:04:24 +00:00
directive or the leap warning variables. The leap warning bits that can
be set in the
1998-02-19 08:05:46 +00:00
.Em leapwarning
1994-04-03 19:50:51 +00:00
variable (up to one month ahead). Both, the
1998-02-19 08:05:46 +00:00
.Em leapwarning
and the
1998-02-19 08:05:46 +00:00
.Em leapindication
1994-04-03 19:50:51 +00:00
variable, have a slightly different encoding than the usual
1998-02-19 08:05:46 +00:00
.Em leap
1994-04-03 19:50:51 +00:00
bits interpretation:
1998-02-19 08:05:46 +00:00
.Bl -tag -width indent
.It 00
1994-09-29 23:04:24 +00:00
The daemon passes the leap bits of its synchronisation source (usual
mode of operation).
1998-02-19 08:05:46 +00:00
.It 01/10
1994-04-03 19:50:51 +00:00
A leap second is added/deleted (operator forced leap second).
1998-02-19 08:05:46 +00:00
.It 11
1994-09-29 23:04:24 +00:00
Leap information from the sychronisation source is ignored (thus
LEAP_NOWARNING is passed on).
1998-02-19 08:05:46 +00:00
.El
.Sh FILES
.Bl -tag -width /etc/ntp.drift -compact
.It /etc/ntp.conf
1993-12-21 18:36:48 +00:00
the default name of the configuration file
1998-02-19 08:05:46 +00:00
.It /etc/ntp.drift
1993-12-21 18:36:48 +00:00
the conventional name of the drift file
1998-02-19 08:05:46 +00:00
.It /etc/ntp.keys
1993-12-21 18:36:48 +00:00
the conventional name of the key file
1998-02-19 08:05:46 +00:00
.El
.Sh SEE ALSO
.Xr ntpdate 8 ,
.Xr ntpq 8 ,
.Xr xntpdc 8
.Sh HISTORY
Written by
.An Dennis Ferguson
at the University of Toronto. Text amended by
.An David Mills
at the University of Delaware.
.Sh BUGS
.Nm Xntpd
1994-09-29 23:04:24 +00:00
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.