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

''' $Header
''' 
.de Sh
.br
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp
.if t .sp .5v
.if n .sp
..
.de Ip
.br
.ie \\n.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
.tr \(bs-|\(bv\*(Tr
.ie n \{\
.ds -- \(bs-
.if (\n(.H=4u)&(1m=24u) .ds -- \(bs\h'-12u'\(bs\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(bs\h'-12u'\(bs\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
.ds L' '
.ds R' '
'br\}
.el\{\
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds L' `
.ds R' '
'br\}
.TH XNTPD 8 LOCAL
.SH NAME
xntpd - Network Time Protocol daemon
.SH SYNOPSIS
.B xntpd
[
.B -ab
] [
.B -c 
.I conffile
] [
.B -e
.I authdelay
] [
.B -f
.I driftfile
] [
.B -k
.I keyfile
] [
.B -l
.I loopfile
] [
.B -p
.I pidfile
] [
.B -r
.I broaddelay
] [
.B -s
.I statsdir
] [
.B -t
.I trustedkey
]
.SH DESCRIPTION
.I Xntpd
is a daemon which maintains a Unix system's 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 and 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 is entirely free of
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 integrations,
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 file at startup time.  The default configuration
file is
.I /etc/ntp.conf,
though this may be overridden from the command line.  It is also possible to
specify a working, though limited,
.I xntpd
configuration entirely on the command line, obviating the need for a
configuration file.  This may be particularly appropriate when xntpd is
to be configured as a broadcast 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 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 options
.Ip -e 8
specify the time (in seconds) it takes to compute the NTP encryption field
on this computer
.Ip -f 8
specify the location of the drift file
.Ip -k 8
specify the location of the file which contains the NTP authentication keys
.Ip -p 8
specify the name of the file to record the daemon's process id
.Ip -r 8
specify the default round trip delay (in seconds)
to be used when synchronizing to broadcasts
.Ip -s 8
specify a directory to be used for creating statistics files
.Ip -t 8
add a key number to the trusted key list
.SH "CONFIGURATION FILE OPTIONS"
.IR Xntpd 's
configuration file is relatively free format.  Comments, which may be
freely inserted, begin with a \*(L"#\*(R" character
and extend to the end of the line.  Blank lines are ignored.  Configuration
statements include an initial keyword followed by white space separated
arguments, some of which may be optional.  Configuration statements
may not be continued over multiple lines.  Arguments may be network
numbers (which must be 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 prefer
]
.PP
These three statements specify various time servers to be used and/or
time services to be provided.  The
.B peer
statement specifies that the given host is to be polled in
\*(L"symmetric active\*(R" mode, i.e. that the host is requested to
provide time which you might synchronize to and, in addition, indicates
that you are willing to have to remote host synchronize to your time
if need be.  The
.B server
statement specifies that the given host is to be polled in
\*(L"client\*(R" mode, i.e. that the host is requested to provide
time which you might synchronize with but that you are unwilling to have
the remote host synchronize to your own time.  The
.B broadcast
statement requests your local daemon to transmit broadcast NTP to
the specified address.  The latter is usually the broadcast address
on [one of] your local network[s].
.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.
.PP
.B precision
.I #
.PP
Indicates the precision of local timekeeping.  The value is an integer
which is approximately the base 2 logarithm of the local timekeeping
precision in seconds.  By default this value is set to -6.
.PP
The precision declared by an implementation can affect several aspects
of server operation, and can be used as a tuning parameter for your
synchronization subnet.  It should probably not be changed from the
default value, however, unless there is a good reason to do so.
.PP
.B logfile
.I filename
.PP
Gives the file which is to be used instead of syslog output. This
configuration option is also a compile time option (SYSLOG_FILE).
So in order to be able to use this xntpd must be compiled with
-DSYSLOG_FILE.
.PP
.B driftfile
.I filename
.PP
Specifies the name of the file used to record the \*(L"drift\*(R" (or
frequency error) value
.I xntpd
has computed.  If the file exists on startup, it is read and the value
used to initialize
.IR xntpd 's
internal value of the frequency error.  The file is then updated once
every hour by replacing the old file with a new one containing the
current value of the frequency error.  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 "monitor yes|no"
.PP
Indicates whether the
.I xntpd
traffic monitoring function should be enabled or not.  When enabled,
this causes the origin address of each packet received by the server
to be recorded along with a limited amount of additional information, such
as the mode of the request and whether it originated from an NTP server port
or not.  Traffic monitoring data may be inspected using the
.IR xntpdc (8)
.I monlist
command.  The default is \*(L"no\*(R", i.e. traffic monitoring should not
be done.
.PP
Note that the traffic monitoring facility will increase the CPU used
by
.IR xntpd ,
as well as increasing the daemon's memory utilization by as much as
8.5 kilobytes.  This facility is normally useful for the detection of
peers with malfunctioning software or which are sending bogus data.  It
is primarily intended for very popular servers which exchange time with
large numbers of peers, though it may also be useful for access monitoring
of local servers if you are willing to accept the overhead.
.PP
.B "broadcastclient yes|no"
.PP
This indicates whether the local server should listen for, and attempt to
synchonize to, broadcast NTP.  The default is \*(L"no\*(R".
.PP
.B broadcastdelay
.I seconds
.PP
Specifies the default round trip delay to the host whose broadcasts
are being synchronized to.  The value is specified in seconds and is
typically (for ethernet) a number between 0.007 and 0.015 seconds.  This
initial estimate may be improved by polling each server to determine a
more accurate value.  Defaults to 0.008 seconds.
.PP
.B "authenticate yes|no"
.PP
Indicates whether the local server should operate in authenticate mode
or not.  If \*(L"yes\*(R", only peers which include an authentication field
encrypted with one of our trusted keys (see below) will be considered
as candidates for synchonizing to.  The default is \*(L"no\*(R".
.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.
.PP
.B keys
.I filename
.PP
Specifies the name of a file which contains the encryption keys which
are to be used by
.IR xntpd .
The format of this file is described below.
.PP
.B trustedkey
.I #
[
.I "# ..."
]
.PP
Allows the specification of the encryption key numbers which are trusted
for the purposes of determining peers suitable for time sychonization,
when authentication is enabled.  Only peers using one of these keys for
encryption of the authentication field, and whose authenticity can be
verified by successful decryption, will be considered as synchonization
candidates.  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
.I Xntpd
allows run time reconfiguration to be performed using the
.IR xntpdc (8)
program.  Such requests must be authenticated.  The
.B requestkey
statement allows the specification of a 32 bit unsigned integer
key number to be used for authenticating such requests.  Note that
if no
.B requestkey
statement is included in the configuration file the run time reconfiguration
facility will be disabled.
.PP
.B controlkey
.I #
.PP
Certain changes can be made to the
.I xntpd
server via mode 6 control messages, in particular the setting of
leap second indications in a server with a radio clock.  The
.B controlkey
statement specifies an encription key number to be used for authenticating
such messages.  Omitting this statement will cause control messages
which would change the state of the server to be ignored.
.PP
.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 as a dotted\-quad address, 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 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 trap
.I host_address
[
.B port
.I port_number
] [
.B interface
.I interface_addess
]
.PP
Configures a trap receiver at the given host address and port number, 
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 maxskew
.I seconds
.PP
This command is obsolete and not available in this version of
.I xntpd.
.PP
.B select
.I algorithm_number
.PP
This command is obsolete and not available in this version of
.I xntpd.
.PP
.B resolver
.I /path/xntpres
.PP
Normally, names requiring resolution (rather than numeric addresses)
in the configuration file are resolved by code internal to
.I xntpd;
However, in those cases that require it, the code can be installed
in a standalone program called
.I xntpres.
In these cases the full path to the
.I xntpres
program is given as the argument the command.
As
.I xntpres
makes use of mode 7 runtime reconfiguration, this facility must also be
enabled if the procedure is to exceed (see the
.B requestkey
and
.B keys
statements above).
.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
.IR 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 "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 encryption algorithm.  The specification
allows any one of a possible 4 billion keys, numbered with 32 bit unsigned
integers, to be used to
authenticate an association.  The servers involved in an association
must agree on the value of the key used to authenticate their data, though
they must each learn the key independently.  The keys are standard 56 bit
DES keys.
.PP
Addionally, a new experimental authentication algorithm is available which
uses an MD5 message digest to compute an authenticator.  Currently the length
of the key or password is limited to 8 characters, but this will eventually
be changed to accomodate an effectively unlimited password phrase.
.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
.PP
.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
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 normally
enabled by configuring the clock as a server using a
.B server
statement in the configuration file which references the clock's
address (configuring a reference clock with a
.B peer
statement can also be done, though with some clock drivers this may cause
the clock to be treated somewhat differently and by convention is used
for debugging purposes).  Clock addresses may generally
be used anywhere else in the configuration file a normal IP address
can be used, for example in
.B restrict
statements.
.PP
There is one additional configuration statement which becomes valid
when reference clock support has been compiled in.  Its format is:
.PP
.B fudge
.I 127.127.t.u
[
.B time1
.I secs
] [
.B time2
.I secs
] [
.B value1
.I int
] [
.B value2
.I int
] [
.B flag1
.I 0|1
] [
.B flag2
.I 0|1
]
.PP
There are two times (whose values are specified in fixed point seconds),
two integral values and two binary flags available for customizing
the operation of a clock.  The interpretation of these values, and
whether they are used at all, is a function of the needs of the particular
clock driver.
.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
pps.txt file in the doc directory of the xntp3 distribution. 
The clock drivers, and the addresses used to configure
them, are described following:
.PP
.B 127.127.1.u
\- Local synchronization clock driver
.PP
This driver doesn't support an actual clock, but rather allows the
server to synchronize to its own clock, in essence to free run without
its stratum increasing to infinity.  This can be used to run an
isolated NTP synchronization network where no standard time source is
available, by allowing a free running clock to appear as if it has
external synchronization to other servers.  By running the local clock
at an elevated stratum it can also be used to prevent a server's stratum
from rising above a fixed value, this allowing a synchronization subnet
to synchonize to a single local server for periods when connectivity
to the primary servers is lost.
.PP
The unit number of the clock (the least significant octet in the address)
must lie in the range 0 through 15 inclusive and is used as the stratum
the local clock will run at.  Note that the server, when synchronized
to the local clock, will advertise a stratum one greater than the clock
peer's stratum.  More than one local clock may be configured (indeed all
16 units may be active at once), though this hardly seems useful.
.PP
The local clock driver uses only the fudge time1 parameter.  This parameter
provides read and write access to the local clock drift compensation
register.  This value, which actually provides a fine resolution speed
adjustment for the local clock, is settable but will remain unchanged
from any set value
when the clock is free running without external synchronization.  The
fudge time1 parameter thus provides a way to manually adjust the speed of the
clock to maintain reasonable synchronization with, say, a voice
time announcement.  It is actually more useful to manipulate this value
with the
.IR xntpdc (8)
program.
.PP
.B 127.127.3.u
\- Precision Standard Time/Traconex 1010/1020 WWV/H Receiver
.PP
This driver can be used with a PST/Traconex Time Source 1010 or 1020 WWV/WWVH
Synchronized Clock connected via a serial port.  Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/pst%d (i.e. unit 1, at 127.127.3.1, opens the clock at
/dev/pst1) and that the clock is configured for 9600-baud operation.
.PP
The fudge time1 and time2 parameters are configured directly into the receiver
as nominal propagation delays when synchronized to WWV and WWVH,
respectively; the internal DIPswitches ordinarily used for that purpose
are disabled. The default values are 0.0075 and 0.0265 seconds,
respectively, which are about right for Toronto.  Values for other
locations can be calculated using the
.I propdelay
program in the util directory of the xntp3 distribution or equivalent
means described in the user's manual.
.PP
The fudge value1 parameter can be used to set the stratum at which
the peer operates.  The default is 0, which is correct if you want the
clock to be considered for synchonization whenever it is operating, though
higher values may be assigned if you only want the clock to provide backup
service when all other primary sources have failed.  The value2 parameter
is set to the number of minutes which the daemon will allow the clock to go
without synchronization before it starts disbelieving it.  The default
is 20, which is suitable if you have good quality backup NTP peers.  If
your network is isolated or your network connections are poor it might
be advantageous to increase this value substantially.
.PP
The fudge flag1 can be used to modifiy the averaging algorithm used
to smooth the clock indications. Ordinarily, the algorithm picks the
median of a set of samples, which is appropriate under conditions
of poor to fair radio propagation conditions. If the clock is located
relatively close to the WWV or WWVH transmitters, setting this flag
will cause the algorithm to average the set of samples, which can
reduce the residual jitter and improve accuracy.
.PP
The fudge flag2 can be used to force the driver to send to
the clock the commands required to reprogram the current WWV and WWVH fudge
delays into it.  This is normally done only when the values are to be changed,
such as during inital setup and calibration.  Setting
the (otherwise undocumented) fudge flag3 will cause the driver to reset
the clock.  The latter two flags are generally useful primarily for debugging.
.PP
127.127.4.u
\- Spectracom 8170 and Netclock/2 WWVB Synchronized Clocks
.PP
This driver can be used with a Spectracom 8170 or Netclock/2 WWVB
Synchronized Clock connected via a serial port.  Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/wwvb%d (i.e., unit 1 at 127.127.4.1 opens the clock at
/dev/wwvb1) and that the clock is configured for 9600-baud operation.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system.
The value, which defaults to zero, is in addition to the value
programmed by the propagation switches on the receiver. The
fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
.B 127.127.5.u
\- Kinemetrics/TrueTime Timing Receivers
.PP
This driver can be used with at least two models of Kinemetrics/TrueTime
Timing Receivers, the 468-DC MK III GOES Synchronized Clock and GPS-DC
MK III GPS Synchronized Clock and very likely others in the same model
family that use the same timecode formats. The clocks are connected
via a serial port.  Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/goes%d (i.e., unit 1 at 127.127.5.1 opens the clock at
/dev/goes1) and that the clock is configured for 9600-baud operation.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system in the same
way as described above for the WWVB clock 127.127.4.u.
The fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
.B 127.127.6.0
\- IRIG-B Audio Decoder
.PP
This driver can be used in conjuction with the Inter-Range Instrumentation
Group standard time-distribution signal IRIG-B. This signal is generated
by several radio clocks, including those made by Austron, TrueTime, Odetics
and Spectracom, among others, although it is generally an add-on option.
The signal is connected via an attenuator box and cable to the audio
codec input on a Sun SPARCstation and requires a specially modified
kernel audio driver. Details are in the irig.txt file in the doc
directory of the xntp3 distribution.  As only a single audio codec
is built into a workstation, the driver assumes the device name is /dev/irig.
.PP
Timing jitter using the decoder and a Sun IPC is in the order of a few 
microseconds, although the overal timing accuracy is limited by the
wander of the CPU oscillator used for timing purposes to a few hundred
microseconds.  These figures are comparable with what can be achieved
using the 1-pps signal described in the pps.txt file in the doc 
directory of the xntp3 distribution. 
.PP
.B 127.127.7.u
\- CHU Modem Decoder
.PP
This driver can be used with a shortwave receiver and special modem
circuitry described in the gadget directory of the xntp3 distribution.
It requires the chu-clk line discipline or chu_clk STREAMS module
described in the kernel directory of that distribution. It is connected
via a serial port operating at 300 baud.  Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/chu%d (i.e., unit 1 at 127.127.7.1 opens the clock at
/dev/chu1).
.PP
Unlike the NIST time services, whose timecode requires quite specialized
hardware to interpret, the CHU timecode can be received directly via
a serial port after demodulation.  While there are currently no commercial
CHU receivers, the hardware required to receive the CHU timecode is fairly
simple to build.  While it is possible to configure several CHU units
simultaneously this is not recommended as the character interrupts from all
units will be occuring at the same time and will interfere with each other.
.PP
The fudge time1 parameter is used to specify the propagation delay between
the CHU transmitter at Ottawa, Ontario, and the receiver. The default
value is 0.0025 seconds, which is about right for Toronto.  Values for other
locations can be calculated using the
.I propdelay
program in the util directory of the xntp3 distribution or equivalent
means.
The fudge time2
parameter is used to compensate for inherent latencies in the modem,
serial port hardware and operating system in the same way as described
above for the WWVB clock 127.127.4.u. The default value is
0.0002 seconds, which is about right for typical telephone modem chips.
The fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
The fudge flag1 can be used to modify the averaging algorithm in the
same way as described for that clock.
.PP
.B 127.127.8.u
\- Synchronisation to several receivers (DCF77, GPS)
.PP
The timecode of
the receivers will be sampled via a STREAMS module in the kernel (The STREAMS module
has been designed for use with SUN Systems under SunOS 4.1.x. It can be
linked directly into the kernel or loaded via the loadable driver mechanism)
This STREAMS module can be adepted to be able to convert different time code
formats.
If the daemon is compiled without the STREAM definition synchronisation
will work without the Sun streams module, though accuracy is significantly
degraded.
.br
The actual receiver status is mapped into various synchronisation
states generally used by receivers. The STREAMS module is configured to
interpret the time codes of DCF U/A 31, PZF535, GPS166, Trimble SV6 GPS, ELV DCF7000,
Schmid and low cost receivers (see list below).
.br
The reference clock support in xntp contains the necessary configuration tables
for those receivers. In addition to supporting up to 32 different clock types and
4 devices the generation a a PPS signal is also provided as an configuration
option. The PPS configuration option uses the receiver generated time stamps
for feeding the PPS loopfilter control for much finer clock synchronisation.
.br
CAUTION: The PPS configuration option is different from the hardware PPS signal,
which is also supported (see below), as it controls the way xntpd is synchronised
to the reference clock, while the hardware PPS signal controls the way time
offsets are determined.
.br
The use of the PPS option requires receivers with an accuracy of better than 1ms.
.PP
Fudge factors
.PP
Only two fudge factors are utilized. The
.I time1
fudge factor defines the phase offset of the sychnronisation character to the actual
time.
On the availability of PPS information the
.I time2
fudge factor show the difference betwteen the PPS time stamp and the reception
time stamp of the serial signal. This parameter is read only attempts to
set this parameter will be ignored.
The
.I flag0
enables input filtering. This a median filter with continuous sampling. The
.I flag1
selects averaging of the samples remaining after the filtering. Leap second
handling is controlled with the
.I flag2.
When set a leap second will be deleted on receipt of a leap second indication
from the receiver. Otherwise the leap second will be added (which is the default).
.PP
.I ntpq
timecode variable
.PP
The timecode variable in the ntpq read clock variable command contains several
fields. The first field is the local time in Unix format. The second field is
the offset to UTC (format HHMM). The currently active receiver flags are listed
next. Additional feature flags of the receiver are optionally listed in paranthesis.
The actual time code is enclosed in angle brackets < >. A qualification of the
decoded time code format is following the time code. The last piece of information
is the overall running time and the accumulated times for the clock event states.
.PP
Unit encoding
.PP
The unit field <u> encodes the device, clock type and the PPS generation option.
There are 4 possible devices which are encoded in the lower 2 bits of the <u>
field. The devices are named
.IR /dev/refclock-0
through
.IR /dev/refclock-3 .
Bits 2 thru 6 encode the clock type. The fudge factors
of the clock type are take from a table
.I clockinfo
in refclock_parse.c. The generation of PPS information for disciplining the
local NTP clock is encoded in bit 7 of <u>.
.PP
Currently nine clock types (devices /dev/refclock-0 - /dev/refclock-3) are supported.
.Ip 127.127.8.0-3 16
Meinberg PZF535 receiver (FM demodulation/TCXO / 50us)
.Ip 127.127.8.4-7 16
Meinberg PZF535 receiver (FM demodulation/OCXO / 50us)
.Ip 127.127.8.8-11 16
Meinberg DCF U/A 31 receiver (AM demodulation / 4ms)
.Ip 127.127.8.12-15 16
ELV DCF7000 (sloppy AM demodulation / 50ms)
.Ip 127.127.8.16-19 16
Walter Schmid DCF receiver Kit (AM demodulation / 1ms)
.Ip 127.127.8.20-23 16
RAW DCF77 100/200ms pulses (Conrad DCF77 receiver module / 5ms)
.Ip 127.127.8.24-27 16
RAW DCF77 100/200ms pulses (TimeBrick DCF77 receiver module / 5ms)
.Ip 127.127.8.28-31 16
Meinberg GPS166 receiver (GPS / <<1us)
.Ip 127.127.8.32-35 16
Trimble SV6 GPS receiver (GPS / <<1us)
.PP
The reference clock support carefully monitors the state transitions of
the receiver. All state changes and exceptional events such as loss of time code
transmission are logged via the
.I syslog
facility.
Every hour a summary of the accumulated times for the clock states is
listed via syslog.
.PP
PPS support is only available when the receiver is completely
synchronised. The receiver is believed to deliver correct time for an additional
period of time after losing sychronisation unless a disruption in time code
transmission is detected (possible power loss). The trust period is dependent
on the receiver oscillator and thus a function of clock type. This is one of
the parameters in the
.I clockinfo
field of the reference clock implementation. This parameter cannot be
configured by xntpdc.
.PP
In addition to the PPS loopfilter control a true PPS hardware signal can be applied
on Sun Sparc stations via the CPU serial ports on the CD pin. This signal is
automatically detected and will be used for offset calculation. The input signal
must be the time mark for the following time code. (The edge sensitivity can be
selected - look into the appropriate kernel/parsestreams.c for details).
Meinberg receivers can be connected by feeding the PPS pulse of the receiver via
a 1488 level converter to Pin 8 (CD) of a Sun serial zs\-port.
.PP
There exists a special firmware release for the PZF535 Meinberg receivers.
This release (PZFUERL 4.6 (or higher - The UERL is important)) is absolutely
recommended for XNTP use, as it provides LEAP warning, time code time zone information
and alternate antenna indication. Please check with Meinberg for this
firmware release.
For the Meinberg GPS166 receiver is also a special firmaware release available
(Uni-Erlangen). This release must be used for proper operation.
.PP
The raw DCF77 pulses can be fed via a level converter directly into Pin 3 (Rx)
of the Sun. The telegrams will be decoded an used for synchronisation.
AM DCF77 receivers are running as low as $25. The accuracy is dependent on
the receiver and is somewhere between 2ms (expensive) to 10ms (cheap).
Upon bad signal reception of DCF77 sychronisation will cease as no backup
oscillator is available as usually found in other reference clock receivers.
So it is important to have a good place for the DCF77 antenna. For transmitter
shutdowns you are out of luck unless you have other NTP servers with alternate
time sources available.
.PP
127.127.9.u
\- Magnavox MX4200 Navigation Receiver used as GPS Synchronized Clocks
.PP
This driver can be used with a Magnavox MX4200 Navigation Receiver
adapted to precision timing applications. This requires an interface
box described in the ppsclock directory of the xntp3 distribution.
It is connected via a serial port and requires the ppsclock STREAMS
module described in the same directory.  Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/gps%d (i.e., unit 1 at 127.127.9.1 opens the clock at
/dev/gps1) and that the clock is configured for 9600-baud operation.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system in the
same way described above for the WWVB clock 127.127.4.u.  The
fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
127.127.10.u
\- Austron 2200A/2201A GPS/LORAN Synchronized Clock and Timing Receiver
.PP
This driver can be used with an Austron 2200A/2201A GPS/LORAN Synchronized
Clock and Timing Receiver connected via a serial port.  It supports
several special features of the clock, including the Input Burffer Module,
Output Buffer Module, IRIG-B Interface Module and LORAN Assist Module. It
requires the RS232 Serial Interface module for communication with
the driver. Up to four units (which hardly seems affordable), with unit
numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/gps%d (i.e., unit 1 at 127.127.10.1 opens the clock at
/dev/gps1) and that the clock is configured for 9600-baud operation.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system in the
same way described above for the WWVB clock 127.127.4.u.  The
fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
This receiver is capable of a comprehensive and large volume of
statistics and operational data. The specific data-collection
commands and attributes are embedded in the driver source code;
however, the collection process can be enabled or disabled
using the flag4 flag. If set, collection is enabled; if not,
which is the default, it is disabled. A comprehensive suite of data reduction
and summary scripts is in the ./scripts/stats directory of the xntp
distribution.
.PP
127.127.11.u
\- Kinemetrics/TrueTime OMEGA-DC OMEGA Synchronized Clock
.PP
This driver can be used with a Kinemetrics/TrueTime OMEGA-DC OMEGA
Synchronized Clock connected via a serial port.  This clock is
sufficiently different than other Kinemetrics/TrueTime models
to require a separate driver. Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/omega%d (i.e., unit 1 at 127.127.11.1 opens the clock at
/dev/omega1) and that the clock is configured for 9600-baud operation.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system in the
same way described above for the WWVB clock 127.127.4.u.  The
fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
127.127.12.0
\- KSI/Odeteics TPRO IRIG-B Decoder
.PP
This driver can be used with a KSI/Odeteics TPRO or TPRO-SAT IRIG-B
Decoder, which is a module connected directly to the SBus of a
Sun workstation.  The module works with the IRIG-B signal generated
by several radio clocks, including those made by Austron, TrueTime, Odetics
and Spectracom, among others, although it is generally an add-on option.
In the case of the TPRO-SAT, the module is an integral part of a GPS
receiver, which serves as the primary timing source. 
As only a single module of this type can be
used on a single workstation, only the unit number 0 is acceptable.
The driver assumes the device name is /dev/tpro0.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system in the
same way described above for the WWVB clock 127.127.4.u.  The
fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
127.127.13.u
\- Leitch CSD 500 Controller with HP 5061A Atomic Clock
.PP
This driver can be used with a Leitch CSD 500 Controller
connected to an HP 5061A Atomic Clock or equivalent primary timing source
and connected via a serial port.  Up to
four units, with unit numbers in the range 0 through 3, can be
configured.  The driver assumes the serial port device name is
/dev/leitch%d (i.e., unit 1 at 127.127.13.1 opens the clock at
/dev/leitch1) and that the clock is configured for 300-baud operation.
.PP
The fudge time1 parameter can be used to compensate for inherent
latencies in the serial port hardware and operating system in the
same way described above for the WWVB clock 127.127.4.u.  The
fudge value1 parameter can be used to specify the stratum of the clock
in the same way described above for the WWV/WWVH clock 127.127.3.u.
.PP
127.127.14.u
\- EES M201 MSF receiver
.PP
This driver can be used with an EES M201 MSF receiver connected
to a Sun running SunOS 4.x with the "ppsclock" STREAMS module.
.PP
The fudge time1 and time2 parameters can be used to compensate for
inherent latencies in the serial port hardware and operating system
respectively in the same way described above for the WWVB clock 127.127.4.u.
The bottom 4 bits of fudge value1 parameter can be used to specify
the stratum of the clock in the same way described above for the
WWV/WWVH clock 127.127.3.u.
The fudge value2 parameter can be used to specify the debug mask.
bit 0x1 causes logging of smoothing processing.
bit 0x4 causes the clock buffer to be dumped.
If flag1 is set, then the system clock is assumed to be sloppy
(e.g. Sun4 with 20ms clock), so samples are averaged.
If flag2 is set, then leaphold is set.
If flag3 is set, then the sample information is dumped.
If flag4 is set, then the input data is smoothed, and all data
points are used.
.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.  This will eventually be corrected
either by adopting the
.I ntpd
daemon as an alternative when it becomes able to match
.IR xntpd 's
performance, or if not than by producing a stripped down version of
.I xntpd
specifically for workstation use.