xntpd(1M) xntpd(1M)
NAME [Toc] [Back]
xntpd - Network Time Protocol daemon
SYNOPSIS [Toc] [Back]
xntpd [ -abdm ] [ -c conffile ] [ -e authdelay ] [ -f driftfile ]
[ -k keyfile ] [ -l logfile ] [ -p pidfile ] [ -r broadcastdelay ]
[ -s statsdir ] [ -t key ] [ -v variable ] [ -V variable ] [ -x ]
DESCRIPTION [Toc] [Back]
xntpd is an operating system daemon which sets and maintains the
system time-of-day in synchronism with Internet standard time servers.
xntpd 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.
xntpd 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/multicast, as described in
RFC-1305. A broadcast/multicast client can discover remote servers,
compute server-client propagation delay correction factors and
configure itself automatically. This makes it possible to deploy a
group of workstations without specifying configuration details
specific to the local environment.
Ordinarily, xntpd reads the /etc/ntp.conf 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 xntpd variables can be displayed and
configuration options altered while the daemon is running using the
ntpq and xntpdc utility programs.
COMMAND LINE OPTIONS [Toc] [Back]
-a Enable authentication mode. The default is disable.
-b Synchronize using NTP broadcast messages.
-c conffile Specify the name and path of the configuration file.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
-d Specify debugging mode. This flag may occur multiple
times, with each occurrence indicating greater
detail of display.
-e authdelay Specify the time (in seconds) it takes to compute
the NTP encryption field on this computer.
-f driftfile Specify the name and path of the drift file.
-k keyfile Specify the name and path of the file containing the
NTP authentication keys.
-l logfile Specify the name and path of the log file. The
default is the system log facility.
-p pidfile Specify the name and path to record the daemon's
process ID.
-r broadcastdelay Specify the default propagation delay from the
broadcast/multicast server and this computer. This
is used only if the delay cannot be computed
automatically by the protocol.
-s statsdir Specify the directory path for files created by the
statistics facility.
-t key Add a key number to the trusted key list.
-v variable Add a system variable.
-V variable Add a system variable listed by default.
-x Make all adjustments by SLEW.
THE CONFIGURATION FILE [Toc] [Back]
The xntpd configuration file is read at initial startup in order to
specify the synchronization sources, modes and other related
information. Usually, it is installed in the /etc/ntp.conf directory,
but could be installed elsewhere (see the -c conffile 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
keyword 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
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
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
/etc/ntp.conf.example may also be helpful.
CONFIGURATION OPTIONS [Toc] [Back]
The configuration commands are as described below:
peer address [ key key_id ] [ version version_id ] [ prefer ]
server address [ key key_id ] [ version version_id ] [ prefer ]
[ mode mode ]
broadcast address [ key key_id ] [ version version_id ] [ ttl ttl ]
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 dotted-quad notation.
The peer 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 server 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 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
specified. Ordinarily, this specification applies only to the local
server operating as a sender; for operation as a broadcast client, see
the broadcastclient or multicastclient 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 [Toc] [Back]
key key_id 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
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
default is to not include an encryption field.
version version_id
Specifies the version number to be used for outgoing
NTP packets. Versions 1, 2, and 3 are the choices, with
version 3 the default.
prefer Marks the server as preferred. All other things being
equal, this host will be chosen for synchronization
among a set of correctly operating hosts.
ttl ttl 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).
broadcastclient
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 propagation 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 succeeding broadcast
messages. Note that, in order to avoid accidental or
malicious disruption in this mode, both the server and
client should operate using symmetric-key or public-key
authentication.
driftfile driftfile
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 frequency 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.
enable auth|bclient|monitor|pll|pps|stats
disable auth|bclient|monitor|pll|pps|stats
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
xntpdc utility program. Each of these flags are
described below.
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
auth Enables 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.
bclient Enables the server to listen for a message from
a broadcast or multicast server, as in the
multicastclient command with default address.
The default for this flag is disable.
monitor Enables the monitoring facility. See the xntpdc
monlist command for further information
(xntpdc(1M)).
pll 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
provide synchronization to other clients. In
this case, the local clock driver is used. See
the Reference Clock Drivers for further
information.
pps 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.
stats Enables the statistics facility. By default
this option is enabled.
Authentication Key File Format [Toc] [Back]
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 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.
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. 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
Hewlett-Packard Company - 5 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
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 four different formats, controlled by
the type character. The four 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-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 [Toc] [Back]
filegen name [ file filename ] [ type typename ] [ link|nolink ]
[ enable|disable ]
This command helps in configuring the generation-file set name. 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 generation-file
Hewlett-Packard Company - 6 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
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 risk of disturbing 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.
name is name of the statistic to be collected. Currently only two
kinds of statistics are supported: loopstats and peerstats.
file Defines a filename string directly concatenated to the
prefix mentioned above (no intervening / (slash)) if prefix
is defined in the statsdir statement.
type 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 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 separating
files belonging to different xntpd server
incarnations. The set member filename is built by
appending a dot . to the concatenated prefix and
filename strings, and appending the decimal
representation of the process id of the xntpd
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
Hewlett-Packard Company - 7 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
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 running at the start of the
corresponding 24 hour period.
enabled/disabled
Information is only written to a file generation set when
this set is enabled. Output is prevented by specifying
disabled. The default is enabled.
link/nolink
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. The default is link.
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.
REFERENCE CLOCK DRIVERS [Toc] [Back]
Individual clocks can be activated by configuration file commands,
specifically the server and fudge 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
127.127.t.u, where t is the clock type and u 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 /dev/deviceu to the particular
hardware device involved, where u correspond to the unit number above.
Hewlett-Packard Company - 8 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
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 as is, 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 [Toc] [Back]
The ntpq and xntpdc 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) manual 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.
Hewlett-Packard Company - 9 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
If RS232 messages are getting to and from the clock, variables can be
inspected using the ntpq command (see ntpq(1M)). First, use the pe
and as commands to display billboards showing the peer configuration
and association IDs for all peers, including the radio clock peers.
The assigned clock address should appear in the pe billboard and the
association ID for it at the same relative line position in the as
billboard. If things are operating correctly, after a minute or two
samples should show up in the pe display line for the clock.
Additional information is available with the rv and clockvar commands,
which take as argument the association ID shown in the as billboard.
The rv command with no argument shows the system variables, while the
rv command with association ID argument shows the peer variables for
the clock, as well as any other peers of interest. The clockvar
command with argument shows the peer variables specific to reference
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 xntpdc utility program can be used for detailed inspection of the
clock driver status. The most useful are the clockstat file and the
commands in xntpdc (seexntpdc(1M)).
Most drivers write a message to the clockstats file as each timecode
or surrogate is received from the radio clock. By convention, 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 filegen
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 [Toc] [Back]
SLEW is not recommended by HP because it reduces accuracy and
stability.
The NTP daemon has three regimes in which it operates:
offset below 128 milliseconds
This is the normal operating regime of NTP. A properly configured
NTP hierarchy (with reasonable networking) can operate for years
without ever approaching the 128 millisecond upper limit. All time
adjustments are small and smooth (known as SLEWING), and nobody
even notices the SLEW adjustments unless they have a cesium clock
or a GPS clock and expensive instrumentation to make sophisticated
measurements (HP/Agilent makes the instruments).
offset above 128 milliseconds
This regime is often encountered at power-on because, those
battery-backed real-time clocks they put in computers are not too
great. Because NTP is quite capable of keeping the offset below
one millisecond all the time it is running, many users want to get
Hewlett-Packard Company - 10 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
into the normal regime quickly when an offset above 128
millisecond is encountered at startup. So in this situation NTP
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 disruptive STEP changes.
offset above 1000 seconds
This is so far out of the normal operating range that NTP 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 financial transaction systems are examples.
The good news is that NTP can be forced to never make a STEP, but
instead SLEW the clock to drive the offset to zero. This is
accomplished with the -x option on the command line. This effectively
removes the middle operating regime. You won't get millisecond (or
microsecond) precision with this method, but you probably can't get
that over a WAN anyway.
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 NTP daemon process has seen a step in its notion of the current
time (and this will be passed on to clients). The system time is being
gradually adjusted in a series of SLEW maneuvers, and the SLEW 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 SLEW adjustment of 411 seconds will
take over 10,000 seconds (about 3 hours) to complete. A better
approach would be to run the ntpdate command once at system startup,
Hewlett-Packard Company - 11 - HP-UX 11i Version 2: August 2003
xntpd(1M) xntpd(1M)
and accept the one STEP change that comes with it. Then start the NTP
daemon process xntpd and it will never make a STEP as long as your
connection to the timesource is good. This method also overcomes the
1000 seconds problem. The NTP startup script /sbin/rc2.d/S660xntpd
will do this automatically if you configure the NTPDATE_SERVER
variable in /etc/rc.config.d/netdamons. A properly configured NTP
hierarchy with average networking (say 10Base-T) can run for years
without ever making a STEP change.
AUTHOR [Toc] [Back]
xntpd was developed by Dennis Ferguson at the University of Toronto.
Text amended by David Mills at the University of Delaware.
FILES [Toc] [Back]
/etc/ntp.conf The default configuration file
/etc/ntp.drift The default drift file
/etc/ntp.keys The default key file
SEE ALSO [Toc] [Back]
ntpq(1M), ntpdate(1M), xntpdc(1M).
Hewlett-Packard Company - 12 - HP-UX 11i Version 2: August 2003 [ Back ] |
