xntpd(1M)xntpd(1M)NAMExntpd - Network Time Protocol daemon
SYNOPSIS
[ ] [ conffile ] [ authdelay ] [ driftfile ]
[ keyfile ] [ logfile ] [ pidfile ] [ broadcastdelay ]
[ ] [ ] [ ] [ ] [ ]
DESCRIPTION
is an operating system daemon which sets and maintains the system
time-of-day in synchronism with Internet standard time servers. is a
complete implementation of the Network Time Protocol (NTP) version 3,
as defined by RFC-1305, but also retains compatibility with version 1
and 2 servers as defined by RFC-1059 and RFC-1119, respectively.
does all computations in 64-bit fixed point arithmetic and requires no
floating point support. While the ultimate precision of this design,
about 232 picoseconds, is not achievable with ordinary workstations and
networks of today, it may be required with future nanosecond CPU clocks
and gigabit LANs.
The daemon can operate in any of several modes, including symmetric
active/passive, client/server and broadcast, as described in RFC-1305.
The daemon can also operate in a multicast mode in which it listens on
a reserved multicast address. A broadcast/multicast client can dis‐
cover remote servers, compute server-client propagation delay correc‐
tion factors and configure itself automatically. This makes it possi‐
ble to deploy a group of workstations without specifying configuration
details specific to the local environment.
Ordinarily, reads the configuration file at startup time in order to
determine the synchronization sources and operating modes. It is also
possible to specify a working, although limited, configuration entirely
on the command line, obviating the need for a configuration file. This
may be particularly appropriate when the local host is to be configured
as a broadcast or multicast client, with all peers being determined by
listening to broadcasts at run time. Various internal variables can be
displayed and configuration options altered while the daemon is running
using the and utility programs.
COMMAND LINE OPTIONS
Enable authentication mode. The default is disable.
Synchronize using NTP broadcast messages.
Specify the name and path of the configuration file.
Specify debugging mode. This flag may occur multiple times, with each
occurrence indicating greater detail of display.
Specify the time (in seconds) it takes to compute the NTP encryption
field on this computer.
Specify the name and path of the drift file.
Specify the name and path of the file containing the NTP authentication
keys.
Specify the name and path of the log file. The default is the system
log facility.
Specify the name and path to record the daemon's process ID.
Specify the default propagation delay from the
server and this computer. This is used only if the
delay cannot be computed automatically by the proto‐
col.
Specify the directory path for files created by the statistics
facility.
Add a key number to the trusted key list.
Add a system variable.
Add a system variable listed by default.
Make all adjustments by SLEW.
THE CONFIGURATION FILE
The configuration file is read at initial startup in order to specify
the synchronization sources, modes and other related information. Usu‐
ally, it is installed in the directory, but could be installed else‐
where (see the command line option).
The 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 key‐
word followed by a list of arguments, some of which may be optional,
separated by white space. 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
The notation means an optional, indefinite repetition of the last item
before the
While there is a rich set of options available, the only required
option is one or more server, peer or broadcast commands described in
the "Configuration Options" section. The examples in may also be help‐
ful.
CONFIGURATION OPTIONS
The configuration commands are as described below:
[ ] [ ] [ ]
[ ] [ ] [ ] [ ]
[ ] [ ] [ ]
The above three commands can be used to specify either the name or
address of the time server and the mode in which the time server should
operate. The address can be either a DNS name or an IP address in dot‐
ted-quad notation.
The command specifies that the local server is to operate in symmetric
active mode with the remote server. 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 may be the better source of time.
The command specifies that the local server is to operate in client
mode with the specified remote server. 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. This is the most common
operating mode (by far).
The 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 specified. Ordi‐
narily, this specification applies only to the local server operating
as a sender; for operation as a broadcast client, see the or commands
below. In this mode, address is usually the broadcast address of (one
of) the local network(s) or a multicast address assigned to NTP. The
address of 224.0.1.1 is assigned to NTP. This is presently the only
address that should be used. Note that the use of multicast features
requires a multicast kernel.
OPTIONS
All packets sent to the address are to include authentication fields
encrypted using the specified key identifier, which is
an unsigned 32 bit integer. The default is to not
include an encryption field.
Specifies the version number to be used for outgoing NTP packets. Ver‐
sions
1, 2, and 3 are the choices, with version 3 the default.
Marks the server as preferred. All other things being equal, this host
will be chosen for synchronization among a set of cor‐
rectly operating hosts.
This option is used only with broadcast mode. It specifies the ttl
(time-to-live) to use on multicast packets. Selection
of the proper value, which defaults to 127, must be
co-ordinated with the network administrator(s).
This command enables reception of broadcast server messages on any
local
interface. Upon receiving a message for the first time,
the broadcast client measures the nominal server propa‐
gation delay using a brief client/server exchange with
the server. Then, the client enters the broadcastclient
mode, in which it listens for and synchronizes to suc‐
ceeding broadcast messages. Note that, in order to
avoid accidental or malicious disruption in this mode,
both the server and client should operate using symmet‐
ric-key or public-key authentication.
This command specifies the name of the file used to record the fre‐
quency
offset of the local clock oscillator. If the file
exists, it is read at startup in order to set the ini‐
tial frequency offset and then updated once per hour
with the current frequency offset computed by the dae‐
mon. 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.
Provides a way to enable or disable various server options.
Flags not
mentioned are unaffected. Note that all of these
flags can be controlled remotely using the util‐
ity program. Each of these flags are described
below.
Enables the server to synchronize with unconfig‐
ured peers only if the
peer has been correctly authenticated
using a trusted key and key identifier.
The default for this flag is disable.
Enables the server to listen for a message from
any
server, as in the multicastclient command
with default address. The default for
this flag is disable.
Enables the monitoring facility. See the
command for further information and xnt‐
pdc(1M).
Enables the server to adjust its local clock,
with default enable. 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 pro‐
vide synchronization to other clients.
In this case, the local clock driver is
used. See the for further information.
Enables the pulse-per-second (PPS) signal when
frequency and time is
disciplined by the precision time kernel
modifications. The default is enable
when these modifications are available
and disable otherwise.
Enables the statistics facility. By default this
option is enabled.
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 imple‐
mented in 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 associa‐
tion. 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.
Additionally, another authentication algorithm is available
which uses an MD5 message digest to compute an authenticator.
The length of the key or password is limited to 8 characters.
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 configura‐
tion 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 four different formats, con‐
trolled by the type character. The four key types, and corre‐
sponding formats, are listed following.
S The key is a 64 bit hexadecimal number in the format speci‐
fied 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 par‐
ity 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 speci‐
fied in the NTP standard. This is the same as the DES for‐
mat 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-32 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.
FILEGEN UTILITY
name [ filename ] [ typename ] [ ] [ ]
This command helps in configuring the generation-file set The
generation-file sets provides a mean for handling files that are
continuously growing during the lifetime of a server. Server
statistics are a typical example for such files. The genera‐
tion-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 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 risk of
disturbing the operation of (Most important: they can be removed
to free space for new data produced.) Filenames of set members
are built from three elements. name is name of the statistic to
be collected. Currently only two kinds of statistics are sup‐
ported: loopstats and peerstats.
Defines a filename string directly concatenated to the prefix
mentioned above (no intervening / (slash)) if prefix
is defined in the statement.
This part 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 typenames are supported:
none The file set is actually a single plain
file.
pid One element of file set is used per incarna‐
tion of a server. This type does not per‐
form any changes to file set members during
runtime, however it provides an easy way of
separating files belonging to different
server incarnations. The set member file‐
name is built by appending a dot . to the
concatenated prefix and filename strings,
and appending the decimal representation of
the process id of the server process. (e.g
<prefix><filename>.<pid> )
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
defined 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 January, 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 run‐
ning at the start of the corresponding 24
hour period.
enabled/disabled
Information is only written to a file generation set
when this set is Output is prevented by specifying The
default is
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 and disabled using
The default is If is specified, a hard link from the cur‐
rent file set element to a file without suffix is cre‐
ated. 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 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.
REFERENCE CLOCK DRIVERS
Individual clocks can be activated by configuration file com‐
mands, specifically the and commands described in the xntpdc(1M)
manual page. The following discussion presents information on
how to select and configure the device drivers in a running UNIX
system.
Radio and modem clocks by convention have addresses in the form
where is the clock type and is a unit number in the range 0-3
used to distinguish multiple instances of clocks of the same
type. Most of these clocks require support in the form of a
serial port or special bus peripheral. The particular device is
normally specified by adding a soft link to the particular hard‐
ware device involved, where u correspond to the unit number
above.
Following is a list showing the type and title of each driver
currently implemented. The compile-time identifier for each is
shown in parentheses.
The following four clock drivers are supported by HP.
Type 1 Local Clock Driver (LOCAL_CLOCK)
Type 4 Spectracom 8170 and Netclock/2 WWVB Receivers (WWVB)
Type 26 Hewlett Packard 58503A GPS Receiver (HPGPS)
Type 29 Trimble Palisade GPS Receiver (PALISADE)
The clock drivers mentioned below are not supported by HP. They
may work, but have not been tested. They are provided for the
convenience of the diverse users.
Type 2 Trak 8820 GPS Receiver (TRAK)
Type 3 PSTI/Traconex 1020 WWV/WWVH Receiver (PST)
Type 5 TrueTime GPS/GOES/OMEGA Receivers (TRUETIME)
Type 8 Generic Reference Driver (PARSE)
Type 10 Austron 2200A/2201A GPS Receivers (AS2201)
Type 11 * TrueTime OMEGA Receiver
Type 15 * TrueTime TM-TMD GPS Receiver
Type 16 Bancomm GPS/IRIG Receiver (HP only) (BANC)
Type 17 Datum Precision Time System (DATUM)
Type 18 NIST Modem Time Service (ACTS)
Type 20 Generic NMEA GPS Receiver (NMEA)
Type 23 PTB Modem Time Service (PTBACTS)
Type 24 USNO Modem Time Service (USNO)
Type 25 * TrueTime generic.
All TrueTime receivers are now supported by one driver, type 5.
Types 11, 15 and 25 will be retained only for a limited time and
may be reassigned in future.
DEBUGGING HINTS FOR REFERENCE CLOCK DRIVERS
The and utility programs can be used to debug reference clocks,
either on the server itself or from another machine elsewhere in
the network. The server is compiled, installed and started
using the command-line switches described in the xntpdc(1M) man‐
ual page.
The first thing to look for are error messages on the system
log. If none occur, the daemon has started, opened the devices
specified and waiting for peers and radios to come up.
The next step is to be sure the RS232 messages, if used, are
getting to and from the clock. The most reliable way to do this
is with an RS232 tester and to look for data flashes as the
driver polls the clock and/or as data arrive from the clock.
Our experience is that many of the problems occurring during
installation are due to problems such as miswired connectors or
improperly configured device links at this stage.
If RS232 messages are getting to and from the clock, variables
can be inspected using the command (see ntpq(1M)). First, use
the and commands to display billboards showing the peer configu‐
ration and association IDs for all peers, including the radio
clock peers. The assigned clock address should appear in the
billboard and the association ID for it at the same relative
line position in the billboard. If things are operating cor‐
rectly, after a minute or two samples should show up in the dis‐
play line for the clock.
Additional information is available with the and commands, which
take as argument the association ID shown in the billboard. The
command with no argument shows the system variables, while the
command with association ID argument shows the peer variables
for the clock, as well as any other peers of interest. The com‐
mand with argument shows the peer variables specific to refer‐
ence clock peers, including the clock status, device name, last
received timecode (if relevant), and various event counters. In
addition, a subset of the fudge parameters is included.
The utility program can be used for detailed inspection of the
clock driver status. The most useful are the file and the com‐
mands in (see xntpdc(1M)).
Most drivers write a message to the clockstats file as each
timecode or surrogate is received from the radio clock. By con‐
vention, this is the last ASCII timecode (or ASCII gloss of a
binary-coded one) received from the radio clock. This file is
managed by the facility described above and requires specific
commands in the configuration file. This forms a highly useful
record to discover anomalies during regular operation of the
clock.
SLEW
is not recommended by HP because it reduces accuracy and stabil‐
ity.
The daemon has three regimes in which it operates:
This is the normal operating regime of
A properly configured hierarchy (with reasonable networking)
can operate for years without ever approaching the 128 mil‐
lisecond upper limit. All time adjustments are small and
smooth (known as SLEWING), and nobody even notices the
adjustments unless they have a cesium clock or a clock and
expensive instrumentation to make sophisticated measurements
(HP/Agilent makes the instruments).
This regime is often encountered at power-on because, those
battery-backed real-time clocks they put in computers are
not too great. Because is quite capable of keeping the off‐
set below one millisecond all the time it is running, many
users want to get into the normal regime quickly when an
offset above 128 millisecond is encountered at startup. So
in this situation will (fairly quickly) make a single STEP
change, and is usually successful in getting the offset well
below 128 millisecond so there will be no more of the dis‐
ruptive STEP changes.
This is so far out of the normal operating range that
decides something is terribly wrong and human intervention
is required. The daemon shuts down.
The catch is that the dispersion on a WAN is frequently much
greater than 128 milliseconds, so you may see (a lot of) the
STEP changes, perhaps as large as 1000 milliseconds (depends on
your network). But there are customer applications that are
quite allergic to the STEP changes, particularly backward steps
(which will happen about half the time). Databases and finan‐
cial transaction systems are examples.
The good news is that can be forced to never make a STEP, but
instead SLEW the clock to drive the offset to zero. This is
accomplished with the option on the command line. This effec‐
tively removes the middle operating regime. You won't get mil‐
lisecond (or microsecond) precision with this method, but you
probably can't get that over a WAN anyway. Sometimes, due to
network congestion, the offset may be higher than 128 ms. In
that case, the algorithm will continue discarding offsets which
are more than 128 ms, until the time interval exceeds 900s.
After 900s, the will again start slewing. However, during this
900s interval, the may appear when the server is queried. It
basically means the underlying network is having some problem.
This mechanism reduces false alarms due to network congestion.
It is important to note that SLEWING is a cover-up for a more
fundamental problem (poor connection to the timesource), and it
does not solve this problem. SLEWING is not recommended by HP
because it causes reduced accuracy and stability, and it leads
to anomalous behavior that can be quite confusing. For example,
you will see messages similar to this in the syslog:
: time reset (step) -411.093665 s
: synchronization lost
: synchronized to 15.13.115.194, stratum=1
: Previous time adjustment incomplete; residual -0.022223 sec
: Previous time adjustment incomplete; residual -0.020624 sec
: Previous time adjustment incomplete; residual -0.020222 sec
: Previous time adjustment incomplete; residual -0.020623 sec
: Previous time adjustment incomplete; residual -0.020623 sec
But this does not mean that your system clock has been stepped.
Only the daemon process has seen a step in its notion of the
current time (and this will be passed on to clients). The sys‐
tem time is being gradually adjusted in a series of maneuvers,
and the rate is quite limited. Be warned that it can take a
long time for the system clock to reach nominal correctness, and
much longer to stabilize. Each cpu model is unique, but the
maximum slew rate is typically about 40 milliseconds per second.
Thus a adjustment of 411 seconds will take over 10,000 seconds
(about 3 hours) to complete. A better approach would be to run
the command once at system startup, and accept the one STEP
change that comes with it. Then start the daemon process and it
will never make a STEP as long as your connection to the time‐
source is good. This method also overcomes the 1000 seconds
problem. The startup script will do this automatically if you
configure the variable in A properly configured hierarchy with
average networking (say 10Base-T) can run for years without ever
making a STEP change.
AUTHOR
was developed by Dennis Ferguson at the University of Toronto.
Text amended by David Mills at the University of Delaware.
FILES
The default configuration file
The default drift file
The default key file
SEE ALSOntpq(1M), ntpdate(1M), xntpdc(1M).
xntpd(1M)
