NAME
xntpd - Network Time Protocol daemon
SYNOPSIS
xntpd [ -abdm ] [ -c conffile ] [ -e authdelay ] [ -f
driftfile ] [ -k keyfile ] [ -l logfile ] [ -p pidfile ] [
-r broadcastdelay ] [ -s statsdir ] [ -t trustedkey ] [ -v
variable ] [ -V variable ]
DESCRIPTION
xntpd is a daemon which sets and maintains a Unix system
time-of-day in agreement with Internet standard time
servers. xntpd is a complete implementation of the Network
Time Protocol (NTP) version 3 standard, as defined by RFC
1305, but also retains compatability with version 1 and 2
servers as defined by RFC 1059 and RFC 1119, respectively.
xntpd does all computations in fixed point arithmetic and
requires no floating point code. The computations done in
the protocol and clock adjustment code are carried out with
high precision and with attention to the details which might
introduce systematic bias into the computations, to try to
maintain an accuracy suitable for synchronizing with even
the most precise external time source.
Ordinarily, xntpd reads its configuration from a
configuration file at startup time. The default
configuration file name is /etc/ntp.conf, although this may
be overridden from the command line. It is also possible to
specify a working, although limited, 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 or multicast
client, with all peers being determined by listening to
broadcasts at run time. Various internal xntpd variables can
be displayed and configuration options altered while the
daemon is running through use of the ntpq(8) and xntpdc(8)
programs.
The daemon can operate in any of several modes, including
symmetric active/passive, client/server and
broadcast/multicast. A broadcast/multicast client can
automatically discover remote servers, compute one-way delay
correction factors and comfigure itself automatically. This
makes it possible to deploy a fleet of workstations without
specifying a configuration file or configuration details
specific to its environment.
The following command line arguments are understood by xntpd
(see the configuration file description for a more complete
functional description):
-a run in "authenticate" mode
-b listen for broadcast NTP and sync to this if
available
-c specify an alternate configuration file
-d specify debugging mode. This flag may occur multiple
times, with each occurance indicating greater detail
of display.
-e specify the time (in seconds) it takes to compute
the NTP encryption field on this computer
-f driftfile
specify the location of the drift file
-k specify the location of the file which contains the
NTP authentication keys
-l logfile
specify a log file instead of logging to syslog
-m listen for multicast messages and synchronize to
them if available (requires multicast kernel)
-p specify the name of the file to record the daemon's
process id
-r ordinarily, the daemon automatically compensates for
the network delay between the broadcast/multicast
server and the client; if the calibration procedure
fails, use the specified the default delay (in
seconds)
-s specify the directory to be used for creating
statistics files
-t trustedkey
add a key number to the trusted key list
-v add a system variable
-V add a system variable listed by default
CONFIGURATION OPTIONS
xntpd 's configuration file format is similar to other Unix
configuration files. Comments begin with a "#" character
and extend to the end of the line. Blank lines are ignored.
Configuration commands consist of an initial keyword
followed by a list of arguments, some of which may be
optional, separated by whitespace. These commands may not be
continued over multiple lines. Arguments may be host names,
host addresses written in numeric, dotted-quad form,
integers, floating point numbers (when specifying times in
seconds) and text strings. Optional arguments are delimited
by "[]" in the following descriptions, while alternatives
are separated by "|".
peer host_address [ key # ] [ version # ] [ prefer ]
server host_address [ key # ] [ version # ] [ prefer ] [
mode # ]
broadcast host_address [ key # ] [ version # ] [ ttl # ]
These three commands specify various time servers to be used
and/or time services to be provided. The peer command
specifies that the local server is to operate in "symmetric
active" mode with the remote server host_address named in
the command. In this mode the local server can be
synchronized to the remote server and, in addition, the
remote server can be synchronized by the local server. This
is useful in a network of servers where, depending on
various failure scenarios, either the local or remote server
host may be the better source of time. The server command
specifies that the local server is to operate in "client"
mode with the remote server named in the command. In this
mode the local server can be synchronized to the remote
server, but the remote server can never be synchronized to
the local server. The broadcast command specifies that the
local server is to operate in "broadcast" mode where the
local server sends periodic broadcast messages to a client
population at the broadcast/multicast address named in the
command. Ordinarily, this specification applies only to the
local server operating as a transmitter; for operation as a
broadcast client, see the broadcastclient or multicastclient
commands elsewhere in this document. In this mode the
host_address is usually the broadcast address on [one of]
the local network[s] or a multicast address assigned to NTP.
The Numbers Czar has assigned the address 224.0.1.1 to NTP;
this is presently the only number that should be used. Note
that the use of multicast features requires a multicast
kernel, which is not yet ubiquitous in vendor products.
The 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 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 prefer option marks the host as a
preferred host. All other things being equal, this host will
be chosen for synchronization among a set of correctly
operating hosts. The ttl option is used only with the
broadcast mode. It specifies the time-to- live (TTL) to use
on multicast packets. Selection of the proper value, which
defaults to 127, is something of a black art and must be
coordinated with the network admistrator(s).
broadcastclient
This directs the local server to listen for broadcast
messages on the local network, in order to discover other
servers on the same subnet. Upon hearing a broadcast
message for the first time, the local server measures the
nominal network delay using a brief client/server exchange
with the remote server, then enters the "broadcastclient"
mode, in which it listens for and synchronizes to succeeding
broadcast messages. Note that, in order to avoid accidental
or malicious disruption in this mode, both the local and
remote servers must operate using authentication and the
same trusted key and key identifier.
multicastclient [ IP address ... ]
This command is used in the same way as the broadcastclient
command, but operates using IP multicasting. Support for
this function requires a multicast kernel and the use of
authentication. If one or more IP addresses are given, the
server joins the respective multicast group(s). If none are
given, the IP address assigned to NTP (224.0.1.1) is
assumed.
driftfile filename
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 rename(3) to replace the old version. This
implies that 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.
enable auth|bclient|pll|monitor|stats [ ... ]
Provides a way to enable various server options. Flags not
mentioned are unaffected. The "auth" flag causes the server
to synchronize with unconfigured peers only if the peer has
been correctly authenticated using a trusted key and key
identifier. The default for this flag is disable (off). The
"bclient" flag causes the server to listen for a message
from a broadcast or multicast server, following which an
association is automatically instantiated for that server.
The default for this flag is disable (off). The "pll" flag
enables the server to adjust its local clock, with default
enable (on). If not set, the local clock free-runs at its
intrinsic time and frequency offset. This flag is useful in
case the local clock is controlled by some other device or
protocol and NTP is used only to provide synchronization to
other clients. The "monitor" flag enables the monitoring
facility (see elsewhere), with default enable (on). The
"stats" flag enables statistics facility filegen (see
description elsewhere.), with default enable (on).
disable auth|bclient|pll|monitor|stats [ ... ]
Provides a way to disable various server options. Flags not
mentioned are unaffected. The flags presently available are
described under the enable command.
AUTHENTICATION OPTIONS
keys filename
This command specifies the name of a file which contains the
encryption keys and key identifiers used by xntpd when
operating in authenticated mode. The format of this file is
described later in this document.
trustedkey # [ # ... ]
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.
requestkey #
This command specifies the key identifier to use with the
xntpdc(8) program, which is useful to diagnose and repair
problems that affect xntpd(8) operation. The operation of
the xntpdc program are specific to this particular
implementation of xntpd and can be expected to work only
with this and previous versions of the daemon. Requests
from a remote xntpdc program which affect the state of the
local server must be authenticated, which requires bot the
remote program and local server share a common key and key
identifier. The argument to this command is a 32 bit
unsigned integer. If no requestkey command is included in
the configuration file, or if the keys don't match, such
requests will be ignored.
controlkey #
This command specifies the key identifier to use with the
ntpq(8) program, which is useful to diagnose and repair
problems that affect xntpd(8) operation. The operation of
the ntpq program and xntpd conform to those specified in RFC
1305. Requests from a remote ntpq program which affect the
state of the local server must be authenticated, which
requires bot the remote program and local server share a
common key and key identifier. The argument to this command
is a 32 bit unsigned integer. If no requestkey command is
included in the configuration file, or if the keys don't
match, such requests will be ignored.
authdelay seconds
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 authspeed
program included with the distribution.
ACCESS CONTROL OPTIONS
restrict address [ mask numeric_mask ] [ flag ] [ ... ]
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 "mask" argument defaults to 255.255.255.255,
meaning that the "address" 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
"address" is normally given in dotted-quad format, the text
string "default", with no mask option, may be used to
indicate the default entry.
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:
ignore Ignore all packets from hosts which match this
entry. If this flag is specified neither queries
nor time server polls will be responded to.
noquery Ignore all NTP mode 6 and 7 packets (i.e.
information queries and configuration requests)
from the source. Time service is not affected.
nomodify 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.
notrap 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.
lowpriotrap
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.
noserve Ignore NTP packets whose mode is other than 6 or
7. In effect, time service is denied, though
queries may still be permitted.
nopeer Provide stateless time service to polling hosts,
but do not allocate peer memory resources to these
hosts even if they otherwise might be considered
useful as future synchronization partners.
notrust Treat these hosts normally in other respects, but
never use them as synchronization sources.
limited These hosts are subject to limitation of number of
clients from the same net. Net in this context
refers to the IP notion of net (class A, class B,
class C, etc.). Only the first "client_limit"
hosts that have shown up at the server and that
have been active during the last
"client_limit_period" seconds are accepted.
Requests from other clients from the same net are
rejected. Only time request packets are taken into
account. "Private", "control", and "broadcast"
packets are not subject to client limitation and
therefore are not contributing to client count.
History of clients is kept using the monitoring
capability of xntpd . Thus, monitoring is active
as long as there is a restriction entry with the
"limited" flag. The default value for
"client_limit" is 3. The default value for
"client_limit_period" is 3600 seconds.
ntpport 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 "ntpport" and non-"ntpport"
may be specified. The "ntpport" is considered more
specific and is sorted later in the list.
Default restriction list entries, with the flags "ignore,
ntpport", 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).
The restriction facility was added to allow the current
access policies of the time servers running on the NSFnet
backbone to be implemented with 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.
clientlimit limit
Sets "client_limit" to "limit", allows configuration of
client limitation policy. This variable defines the number
of clients from the same network that are allowed to use the
server.
clientperiod period
Sets "client_limit_period", allows configuration of client
limitation policy. This variable specifies the number of
seconds after which a client is considered inactive and thus
no longer is counted for client limit restriction.
MONITORING OPTIONS
statsdir /directory path/
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 filegen statement below).
statistics name...
Enables writing of statistics records. Currently, three
kinds of statistics are supported.
loopstats 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 "loopstats":
48773 10847.650 0.0001307 17.3478 2
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.
peerstats 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 "peerstats":
48773 10847.650 127.127.4.1 9714 -0.001605 0.00000
0.00142
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.
clockstats
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 "clockstats":
49213 525.624 127.127.4.1 93 226 00:08:29.606 D
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.
Statistic files are managed using file generation sets (see
filegen below). The information obtained by enabling
statistics recording allows analysis of temporal properties
of a xntpd server. It is usually only useful to primary
servers or maybe main campus servers.
filegen name [ file filename ] [ type typename ] [ flag
flagval ] [ link ] [ enable ]
Configures setting of generation file set 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 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
xntpd . (Most important: they can be removed to free space
for new data produced.) Filenames of set members are built
from three elements.
prefix This is a constant filename path. It is not
subject to modifications via the 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 statsdir
statement explained above.
filename This string is directly concatenated to the prefix
mentioned above (no intervening '/' (slash)). This
can be modified using the "file" argument to the
"filegen" statement. No ".." elements are allowed
in this component to prevent filenames referring
to parts outside the filesystem hierarchy denoted
by "prefix".
suffix This part is reflects individual elements of a
file set. It is generated according to the type of
a file set as explained below.
A file generation set is characterized by its type. The
following types are supported:
none The file set is actually a single plain file.
pid One element of file set is used per incarnation of
a 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 xntpd server
incarnations. The set member filename is built by
appending a dot ('.') to concatentated "prefix"
and "filename" strings, and appending the decimal
representation of the process id of the xntpd
server process.
day One file generation set element is created per
day. The term day is based on UTC. A day is
defined as the period between 00:00 and 24:00 UTC.
The file set member suffix consists of a dot "."
and a day specification in the form <YYYYMMDD>.
YYYY is a 4 digit year number (e.g. 1992). MM is
a two digit month number. DD is a two digit day
number. Thus, all information written at December
10th, 1992 would end up in a file named
"<prefix><filename>.19921210".
week Any file set member contains data related to a
certain week of a year. The term week is definied
by computing "day of year" 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 "W", and a two digit week number. For
example, information from Jamuary, 10th 1992 would
end up in a file with suffix ".1992W1".
month 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.
year One generation file elment is generated per year.
The filename suffix consists of a dot and a 4
digit year number.
age 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 "a", 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.
Information is only written to a file generation set when
this set is "enabled". Output is prevented by specifying
"disabled".
It is convenient to be able to access the current element of
a file generation set by a fixed name. This feature is
enabled by specifying "link" and disabled using "nolink". If
"link" 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
"C", and the pid of the 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.
MISCELLANEOUS OPTIONS
precision #
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.
broadcastdelay seconds
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.
trap host_address [ port port_number ] [ interface
interface_addess ]
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.
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.
setvar variable [default]
This command adds an additional system variable. These
variables can be used to distribute additional information
such as the access policy. If the variable of the from
<name>=<value> is followed by the default keyword the
variable will be listed as part of the default system
variables ( ntpq rv command). These additional variables
serve informational purposes only. They are not related to
the protocol other that they can be listed. The known
protocol variables will always overide any variables defined
via the setvar mechanism.
There are three special variables that contain the names of
all variable of the same group. The sys_var_list holds the
names of all system variables. The peer_var_list holds the
names of all peer variables and the clock_var_list hold the
names of the reference clock variables.
monitor yes|no authenticate yes|no
These commands have been superseded by the enable and
disable commands. They are listed here for historical
purposes.
AUTHENTICATION KEY FILE FORMAT
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 xntpd using the DES or MD5
algorithms to compute a digital signature, or message-
digest. The specification allows any one of possibly 4
billion keys, numbered with 32 bit key identifiers, to be
used to authenticate an association. The servers involved in
an association must agree on the key and key identifier used
to authenticate their data, though they must each learn the
key and key identifer independently. In the case of DES, the
keys are 56 bits long with, depending on type, a parity
check on each byte. In the case of MD5, the keys are 64 bits
(8 bytes). xntpd reads its keys from a file specified using
the -k command line option or the 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.
The key file uses the same comment conventions as the
configuration file. Key entries use a fixed format of the
form
keyno type key
where "keyno" is a positive integer, "type" is a single
character which defines the format the key is given in, and
"key" is the key itself.
The key may be given in one of three different formats,
controlled by the "type" character. The three key types, and
corresponding formats, are listed following.
S The "key" 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 0101010101010101 .
N The "key" 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 8080808080808080
A The "key" 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.
M The "key" 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.
One of the keys may be chosen, by way of the configuration
file requestkey statement, to authenticate run time
configuration requests made using the 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.
PRIMARY CLOCK SUPPORT
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.
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.
For the purposes of configuration, 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 127.127.t.u where t is an integer
denoting the clock type and u indicates the type-specific
unit number. Reference clocks are configured using a server
statement in the configuration file where the host_address
is the clock address. The key, version and ttl options are
not used for reference clock support. Some reference clocks
require a mode option to further specify their operation.
The permissable values for reference clock types, units and
any applicable modes are documented in README.refclock in
the source directory. The prefer option can be useful to
persuade the server to cherish a reference clock with
somewhat more enthusiasm than other reference clocks or
peers, if this is advisable. Clock addresses may generally
be used anywhere in the configuration file a normal IP
address can be used, for example, in restrict statements,
although such use would normally be considered strange.
Reference clock support provides the fudge command, which
can be used to configure reference clocks in special ways.
Following is the generic format that applies to this command
fudge 127.127.t.u [ time1 secs ] [ time2 secs ] [ stratum
int ] [ refid int ] [ flag1 0|1 ] [ flag2 0|1 ] [ flag3 0|1
] [ flag4 0|1 ]
The time1 and time2 options are specified in fixed point
seconds and used in some clock drivers as calibration
constants. By convention, and unless indicated otherwise,
time1 is used as a calibration constant to adjust the
nominal time offset of a particular clock to agree with an
external standard, such as a precision PPS signal. The
specified offset is in addition to the propagation delay
provided by other means, such as internal DIPswitches. The
stratum option is a number in the range zero to 15 and is
used to assign a nonstandard operating stratum to the clock.
The refid option is an ASCII string in the range one to four
characters and is used to assign a nonstandard reference
identifier to the clock. Finally, the four binary flags
flag1, flag2, flag3 and flag4 are used for customizing the
clock driver. The interpretation of these values, and
whether they are used at all, is a function of the needs of
the particular clock driver. However, by convention, and
unless indicated otherwise, flag3 is used to attach the
ppsclock streams module to the configured driver, while
flag4 is used to enable recording verbose monitoring data to
the clockstats file configured with the filegen command.
Further information on the ppsclock streams module is in the
README file in the ./kernel directory in the current xntp3
program distribution. Further information on this feature is
available in the
Ordinarily, the stratum of a reference clock is by default
zero. Since the xntpd daemon adds one to the stratum of each
peer, a primary server ordinarily displays stratum one. In
order to provide engineered backups, it is often useful to
specify the reference clock stratum as greater than zero.
The stratum option is used for this purpose. Also, in cases
involving both a reference clock and a 1-pps discipline
signal, it is useful to specify the reference clock
identifier as other than the default, depending on the
driver. The refid option is used for this purpose. Except
where noted, these options apply to all clock drivers.
xntpd on Unix machines currently supports several different
types of clock hardware plus a special pseudo-clock used for
backup or when no other clock source is available. In the
case of most of the clock drivers, support for a 1-pps
precision timing signal is available as described in the
README file in the ./doc directory of the xntp3 progam
distribution. The clock drivers, and the addresses used to
configure them, are described in the README.refclocks in the
doc directory of the current program distribution.
VARIABLES
Most variables used by the NTP protocol can be examined with
the xntpdc (mode 7 messages) and the ntpq (mode 6 messages).
Currently very few variables can be modified via mode 6
messages. These variables are either created with the setvar
directive or the leap warning variables. The leap warning
bits that can be set in the leapwarning variable (up to one
month ahead). Both, the leapwarning and in the
leapindication variable, have a slightly different encoding
than the usual leap bits interpretation:
00 The daemon passes the leap bits of its
synchronisation source (usual mode of operation).
01/10 A leap second is added/deleted (operator forced leap
second).
11 Leap information from the sychronisation source is
ignored (thus LEAP_NOWARNING is passed on).
FILES
/etc/ntp.conf the default name of the configuration
file
/etc/ntp.drift the conventional name of the drift file
/etc/ntp.keys the conventional name of the key file
SEE ALSO
xntpdc(8), ntpq(8), ntpdate(8) (xntp
source)/doc/README.refclock
HISTORY
Written by Dennis Ferguson at the University of Toronto.
Text amended by David Mills at the University of Delaware.
BUGS
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.