freebsd-skq/contrib/ntp/html/driver1.htm
1999-12-09 13:01:21 +00:00

158 lines
5.8 KiB
HTML

<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<META NAME="GENERATOR" CONTENT="Mozilla/4.01 [en] (Win95; I) [Netscape]">
<TITLE>Undisciplined Local Clock
</TITLE>
</HEAD>
<BODY>
<H3>
Undisciplined Local Clock</H3>
<HR>
<H4>
Synopsis</H4>
Address: 127.127.1.<I>u</I>
<BR>Reference ID: <TT>LCL</TT>
<BR>Driver ID: <TT>LOCAL</TT>
<H4>
Description</H4>
This driver is intended for use in an isolated network where no external
source of synchronization such as a radio clock or modem is available.
It allows a designated time server to act as a primary server to provide
synchronization to other clients on the network. Pick a machine that has
a good clock oscillator (Digital machines are good, Sun machines are not)
and configure it with this driver. Set the clock using the best means available,
like eyeball-and-wristwatch. Then, point all the other machines at this
one or use broadcast (not multicast) mode to distribute time.
<P>Another application for this driver is if a particular server clock
is to be used as the clock of last resort when all other normal synchronization
sources have gone away. This is especially useful if that server has an
ovenized oscillator. For this you would configure this driver at a stratum
greater than any other likely sources of time (say 3 or 4) to prevent the
server taking over when legitimate sources are still available.
<P>A third application for this driver is when an external discipline source
is available, such as the NIST <TT>lockclock</TT> program, which synchronizes
the local clock via a telephone modem and the NIST Automated Computer Time
Service (ACTS), or the Digital Time Synchronization Service (DTSS), which
runs on DCE machines. In this case the stratum should be set at zero, indicating
a bona fide stratum-1 source. In the case of DTSS, the local clock can
have a rather large jitter, depending on the interval between corrections
and the intrinsic frequency error of the clock oscillator. In extreme cases,
this can cause clients to exceed the 128-ms slew window and drop off the
NTP subnet.
<P>In the case where a NTP time server is synchronized to some device or
protocol that is not external to the NTP daemon itself, some means should
be provided to pass such things as error and health values to the NTP daemon
for dissemination to its clients. If this is not done, there is a very
real danger that the device or protocol could fail and with no means to
tell NTP clients of the mishap. When ordinary Unix system calls like <TT>adjtime()</TT>
are used to discipline the kernel clock, there is no obvious way this can
be done without modifying the code for each case. However, when a modified
kernel with the <TT>ntp_adjtime()</TT> system call&nbsp; is available,
that routine can be used for the same purpose as the <TT>adjtime()</TT>
routine and in addition provided with the estimated error, maximum error,
and leap-indicator values. This is the preferred way to synchronize the
kernel clock and pass information to the NTP clients.
<P>In the default mode the behavior of the clock selection algorithm is
modified when this driver is in use. The algorithm is designed so that
this driver will never be selected unless no other discipline source is
available. This can be overridden with the <TT>prefer</TT> keyword of the
<TT>server</TT> configuration command, in which case only this driver will
be selected for synchronization and all other discipline sources will be
ignored. This behavior is intended for use when an external discipline
source controls the system clock. See the <A HREF="prefer.htm">Mitigation
Rules and the <TT>prefer</TT> Keyword </A>page for a detailed description
of the exact behavior.
<P>The stratum for this driver is set at 3 by default, but can be changed
by the <TT>fudge</TT> configuration command and/or the <TT>ntpdc</TT> utility.
The reference ID is <TT>LCL</TT> by default, but can be changed using the
same mechanisms. <B>*NEVER*</B> configure this driver to operate at a stratum
which might possibly disrupt a client with access to a bona fide primary
server, unless the local clock oscillator is reliably disciplined by another
source. <B>*NEVER NEVER*</B> configure a server which might devolve to
an undisciplined local clock to use multicast mode.
<P>This driver provides a mechanism to trim the local clock in both time
and frequency, as well as a way to manipulate the leap bits. The <TT>fudge
time1</TT> parameter adjusts the time (in seconds) and the <TT>fudge time2</TT>
parameter adjusts the frequency (in parts per million). Both parameters
are additive and operate only once; that is, each command (as from <TT>ntpdc</TT>)
adds signed increments in time or frequency to the nominal local clock
time and frequency.
<H4>
Monitor Data</H4>
No <TT>filegen clockstats</TT> monitor data are produced by this driver.
<H4>
Fudge Factors</H4>
<DL>
<DT>
<TT>time1 <I>time</I></TT></DT>
<DD>
Specifies the time offset calibration factor, in seconds and fraction,
with default 0.0.</DD>
<DT>
<TT>time2 <I>time</I></TT></DT>
<DD>
Specifies the frequency offset calibration factor, in parts per million,
with default 0.0.</DD>
<DT>
<TT>stratum <I>number</I></TT></DT>
<DD>
Specifies the driver stratum, in decimal from 0 to 15, with default 3.</DD>
<DT>
<TT>refid <I>string</I></TT></DT>
<DD>
Specifies the driver reference identifier, an ASCII string from one to
four characters, with default <TT>LCL</TT>.</DD>
<DT>
<TT>flag1 0 | 1</TT></DT>
<DD>
Not used by this driver.</DD>
<DT>
<TT>flag2 0 | 1</TT></DT>
<DD>
Not used by this driver.</DD>
<DT>
<TT>flag3 0 | 1</TT></DT>
<DD>
Not used by this driver.</DD>
<DT>
<TT>flag4 0 | 1</TT></DT>
<DD>
Not used by this driver.</DD>
<P>Additional Information
<P><A HREF="refclock.htm">Reference Clock Drivers</A></DL>
<HR>
<ADDRESS>
David L. Mills (mills@udel.edu)</ADDRESS>
</BODY>
</HTML>