458 lines
20 KiB
HTML
458 lines
20 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<title>ntpd - Network Time Protocol (NTP) daemon</title>
|
|
</head>
|
|
<body>
|
|
<h3><tt>ntpd</tt> - Network Time Protocol (NTP) daemon</h3>
|
|
|
|
<img align="left" src="pic/alice47.gif" alt="gif"><a href=
|
|
"http://www.eecis.udel.edu/~mills/pictures.htm">from <i>Alice's
|
|
Adventures in Wonderland</i>, Lewis Carroll</a>
|
|
|
|
<p>The mushroom knows all the command line options.<br clear=
|
|
"left">
|
|
</p>
|
|
|
|
<hr>
|
|
<h4>Synopsis</h4>
|
|
|
|
<tt>ntpd [ -aAbdgLmNPqx ] [ -c <i>conffile</i> ] [ -f <i>
|
|
driftfile</i> ] [ -g ] [ -k <i>keyfile</i> ] [ -l <i>logfile</i> ]
|
|
[ -N high ] [ -p <i>pidfile</i> ] [ -r <i>broadcastdelay</i> ] [ -s
|
|
<i>statsdir</i> ] [ -t <i>key</i> ] [ -v <i>variable</i> ] [ -V <i>
|
|
variable</i> ] [ -x ]</tt>
|
|
|
|
<h4>Description</h4>
|
|
|
|
The <tt>ntpd</tt> program is an operating system daemon which sets
|
|
and maintains the system time of day in synchronism with Internet
|
|
standard time servers. It is a complete implementation of the
|
|
Network Time Protocol (NTP) version 4, but also retains
|
|
compatibility with version 3, as defined by RFC-1305, and version 1
|
|
and 2, as defined by RFC-1059 and RFC-1119, respectively. <tt>
|
|
ntpd</tt> does most computations in 64-bit floating point
|
|
arithmetic and does relatively clumsy 64-bit fixed point operations
|
|
only when necessary to preserve the ultimate precision, about 232
|
|
picoseconds. While the ultimate precision, is not achievable with
|
|
ordinary workstations and networks of today, it may be required
|
|
with future gigahertz CPU clocks and gigabit LANs.
|
|
|
|
<h4>How NTP Operates</h4>
|
|
|
|
<p>The <tt>ntpd</tt> program operates by exchanging messages with
|
|
one or more configured servers at designated poll intervals. When
|
|
started, whether for the first or subsequent times, the program
|
|
requires several exahanges from the majority of these servers so
|
|
the signal processing and mitigation algorithms can accumulate and
|
|
groom the data and set the clock. In order to protect the network
|
|
from bursts, the initial poll interval for each server is delayed
|
|
an interval randomized over 0-16s. At the default initial poll
|
|
interval of 64s, several minutes can elapse before the clock is
|
|
set. The initial delay to set the clock can be reduced using the
|
|
<tt>iburst</tt> keyword with the <tt>server</tt> configuration
|
|
command, as described on the <a href="confopt.htm">Configuration
|
|
Options</a> page.</p>
|
|
|
|
<p>Most operating systems and hardware of today incorporate a
|
|
time-of-year (TOY) chip to maintain the time during periods when
|
|
the power is off. When the machine is booted, the chip is used to
|
|
initialize the operating system time. After the machine has
|
|
synchronized to a NTP server, the operating system corrects the
|
|
chip from time to time. In case there is no TOY chip or for some
|
|
reason its time is more than 1000s from the server time, <tt>
|
|
ntpd</tt> assumes something must be terribly wrong and the only
|
|
reliable action is for the operator to intervene and set the clock
|
|
by hand. This causes <tt>ntpd</tt> to exit with a panic message to
|
|
the system log. The <tt>-g</tt> option overrides this check and the
|
|
clock will be set to the server time regardless of the chip time.
|
|
However, and to protect against broken hardware, such as when the
|
|
CMOS battery fails or the clock counter becomes defective, once the
|
|
clock has been set, an error greater than 1000s will cause <tt>
|
|
ntpd</tt> to exit anyway.</p>
|
|
|
|
<p>Under ordinariy conditions, <tt>ntpd</tt> adjusts the clock in
|
|
small steps so that the timescale is effectively continuous and
|
|
without discontinuities. Under conditions of extreme network
|
|
congestion, the roundtrip delay jitter can exceed three seconds and
|
|
the synchronization distance, which is equal to one-half the
|
|
roundtrip delay plus error budget terms, can become very large. The
|
|
<tt>ntpd</tt> algorithms discard sample offsets exceeding 128 ms,
|
|
unless the interval during which no sample offset is less than 128
|
|
ms exceeds 900s. The first sample after that, no matter what the
|
|
offset, steps the clock to the indicated time. In practice this
|
|
reduces the false alarm rate where the clock is stepped in error to
|
|
a vanishingly low incidence.</p>
|
|
|
|
<p>As the result of this behavior, once the clock has been set, it
|
|
very rarely strays more than 128 ms, even under extreme cases of
|
|
network path congestion and jitter. Sometimes, in particular when
|
|
<tt>ntpd</tt> is first started, the error might exceed 128 ms. This
|
|
may on occasion cause the clock to be set backwards if the local
|
|
clock time is more than 128 s in the future relative to the server.
|
|
In some applications, this behavior may be unacceptable. If the
|
|
<tt>-x</tt> option is included on the command line, the clock will
|
|
never be stepped and only slew corrections will be used.</p>
|
|
|
|
<p>The issues should be carefully explored before deciding to use
|
|
the <tt>-x</tt> option. The maximum slew rate possible is limited
|
|
to 500 parts-per-million (PPM) as a consequence of the correctness
|
|
principles on which the NTP protocol and algorithm design are
|
|
based. As a result, the local clock can take a long time to
|
|
converge to an acceptable offset, about 2,000 s for each second the
|
|
clock is outside the acceptable range. During this interval the
|
|
local clock will not be consistent with any other network clock and
|
|
the system cannot be used for distributed applications that require
|
|
correctly synchronized network time.</p>
|
|
|
|
<p>In spite of the above precautions, sometimes when large
|
|
frequency errors are present the resulting time offsets stray
|
|
outside the 128-ms range and an eventual step or slew time
|
|
correction is required. If following such a correction the
|
|
frequency error is so large that the first sample is outside the
|
|
acceptable range, <tt>ntpd</tt> enters the same state as when the
|
|
<tt>ntp.drift</tt> file is not present. The intent of this behavior
|
|
is to quickly correct the frequency and restore operation to the
|
|
normal tracking mode. In the most extreme cases
|
|
(<tt>time.ien.it</tt> comes to mind), there may be occasional
|
|
step/slew corrections and subsequent frequency corrections. It
|
|
helps in these cases to use the <tt>burst</tt> keyword when
|
|
configuring the server.</p>
|
|
|
|
<h4>Frequency Discipline</h4>
|
|
|
|
<p>The <tt>ntpd</tt> behavior at startup depends on whether the
|
|
frequency file, usually <tt>ntp.drift</tt>, exists. This file
|
|
contains the latest estimate of clock frequency error. When the
|
|
<tt>ntpd</tt> is started and the file does not exist, the <tt>
|
|
ntpd</tt> enters a special mode designed to quickly adapt to the
|
|
particular system clock oscillator time and frequency error. This
|
|
takes approximately 15 minutes, after which the time and frequency
|
|
are set to nominal values and the <tt>ntpd</tt> enters normal mode,
|
|
where the time and frequency are continuously tracked relative to
|
|
the server. After one hour the frequency file is created and the
|
|
current frequency offset written to it. When the <tt>ntpd</tt> is
|
|
started and the file does exist, the <tt>ntpd</tt> frequency is
|
|
initialized from the file and enters normal mode immediately. After
|
|
that the current frequency offset is written to the file at hourly
|
|
intervals.</p>
|
|
|
|
<h4>Operating Modes</h4>
|
|
|
|
<p><tt>ntpd</tt> can operate in any of several modes, including
|
|
symmetric active/passive, client/server broadcast/multicast and
|
|
manycast, as described in the <a href="assoc.htm">Association
|
|
Management</a> page. It normally operates continuously while
|
|
monitoring for small changes in frequency and trimming the clock
|
|
for the ultimate precision. However, it can operate in a one-time
|
|
mode where the time is set from an external server and frequency is
|
|
set from a previously recorded frequency file. A
|
|
broadcast/multicast or manycast client can discover remote servers,
|
|
compute server-client propagation delay correction factors and
|
|
configure itself automatically. This makes it possible to deploy a
|
|
fleet of workstations without specifying configuration details
|
|
specific to the local environment.</p>
|
|
|
|
<p>By default, <tt>ntpd</tt> runs in continuous mode where each of
|
|
possibly several external servers is polled at intervals determined
|
|
by an intricate state machine. The state machine measures the
|
|
incidental roundtrip delay jitter and oscillator frequency wander
|
|
and determines the best poll interval using a heuristic algorithm.
|
|
Ordinarily, and in most operating environments, the state machine
|
|
will start with 64s intervals and eventually increase in steps to
|
|
1024s. A small amount of random variation is introduced in order to
|
|
avoid bunching at the servers. In addition, should a server become
|
|
unreachable for some time, the poll interval is increased in steps
|
|
to 1024s in order to reduce network overhead.</p>
|
|
|
|
<p>In some cases it may not be practical for <tt>ntpd</tt> to run
|
|
continuously. A common workaround has been to run the <tt>
|
|
ntpdate</tt> program from a <tt>cron</tt> job at designated times.
|
|
However, this program does not have the crafted signal processing,
|
|
error checking and mitigation algorithms of <tt>ntpd</tt>. The <tt>
|
|
-q</tt> option is intended for this purpose. Setting this option
|
|
will cause <tt>ntpd</tt> to exit just after setting the clock for
|
|
the first time. The procedure for initially setting the clock is
|
|
the same as in continuous mode; most applications will probably
|
|
want to specify the <tt>iburst</tt> keyword with the <tt>
|
|
server</tt> configuration command. With this keyword a volley of
|
|
messages are exchanged to groom the data and the clock is set in
|
|
about a minute. If nothing is heard after a couple of minutes, the
|
|
daemon times out and exits. After a suitable period of mourning,
|
|
the <tt>ntpdate</tt> program may be retired.</p>
|
|
|
|
<p>When kernel support is available to discipline the clock
|
|
frequency, which is the case for stock Solaris, Tru64, Linux and
|
|
FreeBSD, a useful feature is available to discipline the clock
|
|
frequency. First, <tt>ntpd</tt> is run in continuous mode with
|
|
selected servers in order to measure and record the intrinsic clock
|
|
frequency offset in the frequency file. It may take some hours for
|
|
the frequency and offset to settle down. Then the <tt>ntpd</tt> is
|
|
stopped and run in one-time mode as required. At each startup, the
|
|
frequency is read from the file and initializes the kernel
|
|
frequency.</p>
|
|
|
|
<h4>Poll Interval Control</h4>
|
|
|
|
<p>This version of NTP includes an intricate state machine to
|
|
reduce the network load while maintaining a quality of
|
|
synchronization consistent with the observed jitter and wander.
|
|
There are a number of ways to tailor the operation in order enhance
|
|
accuracy by reducing the interval or to reduce network overhead by
|
|
increasing it. However, the user is advised to carefully consider
|
|
the consequenses of changing the poll adjustment range from the
|
|
default minimum of 64 s to the default maximum of 1,024 s. The
|
|
default minimum can be changed with the <tt>tinker minpoll</tt>
|
|
command to a value not less than 16 s. This value is used for all
|
|
configured associations, unless overriden by the <tt>minpoll</tt>
|
|
option on the configuration command. Note that most device drivers
|
|
will not operate properly if the poll interval is less than 64 s
|
|
and that the broadcast server and manycast client associations will
|
|
also use the default, unless overriden.</p>
|
|
|
|
<p>In some cases involving dial up or toll services, it may be
|
|
useful to increase the minimum interval to a few tens of minutes
|
|
and maximum interval to a day or so. Under normal operation
|
|
conditions, once the clock discipline loop has stabilized the
|
|
interval will be increased in steps from the minumum to the
|
|
maximum. However, this assumes the intrinsic clock frequency error
|
|
is small enough for the discipline loop correct it. The capture
|
|
range of the loop is 500 PPM at an interval of 64s decreasing by a
|
|
factor of two for each doubling of interval. At a minimum of 1,024
|
|
s, for example, the capture range is only 31 PPM. If the intrinsic
|
|
error is greater than this, the drift file <tt>ntp.drift</tt> will
|
|
have to be specially tailored to reduce the residual error below
|
|
this limit. Once this is done, the drift file is automatically
|
|
updated once per hour and is available to initialize the frequency
|
|
on subsequent daemon restarts.</p>
|
|
|
|
<h4>The huff-n'-puff filter</h4>
|
|
|
|
<p>In scenarios where a considerable amount of data are to be
|
|
downloaded or uploaded over telephone modems, timekeeping quality
|
|
can be seriously degraded. This occurs because the differential
|
|
delays on the two directions of transmission can be quite large. In
|
|
many cases the apparent time errors are so large as to exceed the
|
|
step threshold and a step correction can occur during and after the
|
|
data transfer is in progress.</p>
|
|
|
|
<p>The huff-n'-puff filter is designed to correct the apparent time
|
|
offset in these cases. It depends on knowledge of the propagation
|
|
delay when no other traffic is present. In common scenarios this
|
|
occurs during other than work hours. The filter maintains a shift
|
|
register that remembers the minimum delay over the most recent
|
|
interval measured usually in hours. Under conditions of severe
|
|
delay, the filter corrects the apparent offset using the sign of
|
|
the offset and the difference between the apparent delay and
|
|
minimum delay. The name of the filter reflects the negative (huff)
|
|
and positive (puff) correction, which depends on the sign of the
|
|
offset.</p>
|
|
|
|
<p>The filter is activated by the <tt>tinker</tt> command and <tt>
|
|
huffpuff</tt> keyword, as described in the <a href="miscopt.htm">
|
|
Miscellaneous Options</a> page.</p>
|
|
|
|
<h4>Notes</h4>
|
|
|
|
<p>If NetInfo support is built into <tt>ntpd</tt>, then <tt>
|
|
ntpd</tt> will attempt to read its configuration from the NetInfo
|
|
if the default ntp.conf file cannot be read and no file is
|
|
specified by the <tt>-c</tt> option.</p>
|
|
|
|
<p>Various internal <tt>ntpd</tt> variables can be displayed and
|
|
configuration options altered while the <tt>ntpd</tt> is running
|
|
using the <tt><a href="ntpq.htm">ntpq</a></tt> and <tt><a href=
|
|
"ntpdc.htm">ntpdc</a></tt> utility programs.</p>
|
|
|
|
<p>When <tt>ntpd</tt> starts it looks at the value of <tt>
|
|
umask</tt>, and if zero <tt>ntpd</tt> will set the <tt>umask</tt>
|
|
to <tt>022</tt>.</p>
|
|
|
|
<h4>Command Line Options</h4>
|
|
|
|
<dl>
|
|
<dt><tt>-a</tt></dt>
|
|
|
|
<dd>Enable authentication mode (default).</dd>
|
|
|
|
<dt><tt>-A</tt></dt>
|
|
|
|
<dd>Disable authentication mode.</dd>
|
|
|
|
<dt><tt>-b</tt></dt>
|
|
|
|
<dd>Synchronize using NTP broadcast messages.</dd>
|
|
|
|
<dt><tt>-c <i>conffile</i></tt></dt>
|
|
|
|
<dd>Specify the name and path of the configuration file. (Disable
|
|
netinfo?)</dd>
|
|
|
|
<dt><tt>-d</tt></dt>
|
|
|
|
<dd>Specify debugging mode. This flag may occur multiple times,
|
|
with each occurrence indicating greater detail of display.</dd>
|
|
|
|
<dt><tt>-D <i>level</i></tt></dt>
|
|
|
|
<dd>Specify debugging level directly.</dd>
|
|
|
|
<dt><tt>-f <i>driftfile</i></tt></dt>
|
|
|
|
<dd>Specify the name and path of the drift file.</dd>
|
|
|
|
<dt><tt>-g</tt></dt>
|
|
|
|
<dd>Normally, <tt>ntpd</tt> exits if the offset exceeds the sanity
|
|
limit, which is 1000 s by default. If the sanity limit is set to
|
|
zero, no sanity checking is performed and any offset is acceptable.
|
|
This option overrides the limit and allows the time to be set to
|
|
any value without restriction; however, this can happen only once.
|
|
After that, <tt>ntpd</tt> will exit if the limit is exceeded. This
|
|
option can be used with the <tt>-q</tt> option.</dd>
|
|
|
|
<dt><tt>-k <i>keyfile</i></tt></dt>
|
|
|
|
<dd>Specify the name and path of the file containing the NTP
|
|
authentication keys.</dd>
|
|
|
|
<dt><tt>-l <i>logfile</i></tt></dt>
|
|
|
|
<dd>Specify the name and path of the log file. The default is the
|
|
system log facility.</dd>
|
|
|
|
<dt><tt>-L</tt></dt>
|
|
|
|
<dd>Listen to virtual IPs.</dd>
|
|
|
|
<dt><tt>-m</tt></dt>
|
|
|
|
<dd>Synchronize using NTP multicast messages on the IP multicast
|
|
group address 224.0.1.1 (requires multicast kernel).</dd>
|
|
|
|
<dt><tt>-n</tt></dt>
|
|
|
|
<dd>Don't fork.</dd>
|
|
|
|
<dt><tt>-N <i>priority</i></tt></dt>
|
|
|
|
<dd>To the extent permitted by the operating system, run the <tt>
|
|
ntpd</tt> at a high priority.</dd>
|
|
|
|
<dt><tt>-p <i>pidfile</i></tt></dt>
|
|
|
|
<dd>Specify the name and path to record the <tt>ntpd</tt>'s process
|
|
ID.</dd>
|
|
|
|
<dt><tt>-P</tt></dt>
|
|
|
|
<dd>Override the priority limit set by the operating system. Not
|
|
recommended for sissies.</dd>
|
|
|
|
<dt><tt>-q</tt></dt>
|
|
|
|
<dd>Exit the <tt>ntpd</tt> just after the first time the clock is
|
|
set. This behavior mimics that of the <tt>ntpdate</tt> program,
|
|
which is to be retired. The <tt>-g</tt> and <tt>-x</tt> options can
|
|
be used with this option.</dd>
|
|
|
|
<dt><tt>-r <i>broadcastdelay</i></tt></dt>
|
|
|
|
<dd>Specify the default propagation delay from the
|
|
broadcast/multicast server and this computer. This is necessary
|
|
only if the delay cannot be computed automatically by the
|
|
protocol.</dd>
|
|
|
|
<dt><tt>-s <i>statsdir</i></tt></dt>
|
|
|
|
<dd>Specify the directory path for files created by the statistics
|
|
facility.</dd>
|
|
|
|
<dt><tt>-t <i>key</i></tt></dt>
|
|
|
|
<dd>Add a key number to the trusted key list.</dd>
|
|
|
|
<dt><tt>-v <i>variable</i></tt></dt>
|
|
|
|
<dt><tt>-V <i>variable</i></tt></dt>
|
|
|
|
<dd>Add a system variable listed by default.</dd>
|
|
|
|
<dt><tt>-x</tt></dt>
|
|
|
|
<dd>Normally, the time is slewed if the offset is less than the
|
|
step threshold, which is 128 ms by default, and stepped if above
|
|
the threshold. This option forces the time to be slewed in all
|
|
cases. If the step threshold is set to zero, all offsets are
|
|
stepped, regardless of value and regardless of the <tt>-x</tt>
|
|
option. In general, this is not a good idea, as it bypasses the
|
|
clock state machine which is designed to cope with large time and
|
|
frequency errors Note: Since the slew rate is limited to 0.5 ms/s,
|
|
each second of adjustment requires an amortization interval of 2000
|
|
s. Thus, an adjustment of many seconds can take hours or days to
|
|
amortize. This option can be used with the <tt>-q</tt> option.</dd>
|
|
</dl>
|
|
|
|
<h4>The Configuration File</h4>
|
|
|
|
<p>Ordinarily, <tt>ntpd</tt> reads the <tt>ntp.conf</tt>
|
|
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 useful when the local host is to be configured as a
|
|
broadcast/multicast client, with all peers being determined by
|
|
listening to broadcasts at run time.</p>
|
|
|
|
<p>Usually, the configuration file is installed in the <tt>
|
|
/etc</tt> directory, but could be installed elsewhere (see the <tt>
|
|
-c <i>conffile</i></tt> command line option). The file format is
|
|
similar to other Unix configuration files - comments begin with a
|
|
<tt>#</tt> character and extend to the end of the line; blank lines
|
|
are ignored.</p>
|
|
|
|
<p>Configuration commands consist of an initial keyword followed by
|
|
a list of arguments, some of which may be optional, separated by
|
|
whitespace. 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 <tt>[ ]</tt> in the following descriptions, while
|
|
alternatives are separated by <tt>|</tt>. The notation <tt>[ ...
|
|
]</tt> means an optional, indefinite repetition of the last item
|
|
before the <tt>[ ... ]</tt>.</p>
|
|
|
|
<p><a href="confopt.htm">Configuration Options</a><br>
|
|
<a href="authopt.htm">Authentication Options</a><br>
|
|
<a href="monopt.htm">Monitoring Options</a><br>
|
|
<a href="accopt.htm">Access Control Options</a><br>
|
|
<a href="clockopt.htm">Reference Clock Options</a><br>
|
|
<a href="miscopt.htm">Miscellaneous Options</a></p>
|
|
|
|
<h4>Files</h4>
|
|
|
|
<tt>/etc/ntp.conf</tt> - the default name of the configuration file
|
|
<br>
|
|
<tt>/etc/ntp.drift</tt> - the default name of the drift file <br>
|
|
<tt>/etc/ntp.keys</tt> - the default name of the key file
|
|
|
|
<h4>Bugs</h4>
|
|
|
|
<tt>ntpd</tt> has gotten rather fat. While not huge, it has gotten
|
|
larger than might be desirable for an elevated-priority <tt>
|
|
ntpd</tt> 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.
|
|
|
|
<hr>
|
|
<a href="index.htm"><img align="left" src="pic/home.gif" alt=
|
|
"gif"></a>
|
|
|
|
<address><a href="mailto:mills@udel.edu">David L. Mills
|
|
<mills@udel.edu></a></address>
|
|
</body>
|
|
</html>
|
|
|