mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-24 11:29:10 +00:00
1548 lines
69 KiB
HTML
1548 lines
69 KiB
HTML
<HTML><HEAD><TITLE>
|
|
Notes on Configuring NTP and Setting up a NTP Subnet</H3>
|
|
</TITLE></HEAD><BODY><H3>
|
|
Notes on Configuring NTP and Setting up a NTP Subnet</H3>
|
|
</H3>
|
|
|
|
<img align=left src=pic/tonea.gif>
|
|
From NBS Special Publication 432 (out of print)
|
|
<br clear=left>
|
|
|
|
<H4>Introduction</H4>
|
|
|
|
This document is a collection of notes concerning the use of ntpd and
|
|
relatedprograms, and on coping with the Network Time Protocol (NTP) in
|
|
general. It is a major rewrite and update of an earlier document written
|
|
by Dennis Ferguson of the University of Toronto and includes many
|
|
changes and additions resulting from the NTP Version 3 specification and
|
|
new Version 4 implementation features. It supersedes earlier documents,
|
|
which should no longer be used
|
|
for new configurations.
|
|
|
|
<P><TT>ntpd</TT> includes a complete implementation of the NTP Version
|
|
3 specification, as defined in:
|
|
|
|
<ul>
|
|
|
|
<p><li>Mills, D.L. Network Time Protocol (Version 3) specification,
|
|
implementation and analysis. Network Working Group Report RFC-1305,
|
|
University of Delaware, March 1992, 113 pp. Abstract: <a
|
|
href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305a.ps>
|
|
PostScript</a> | <a
|
|
href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305a.pdf>
|
|
PDF</a>, Body: <a
|
|
href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.ps>
|
|
PostScript</a> | <a
|
|
href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.pdf>
|
|
PDF</a>, Appendices: <a
|
|
href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.ps>
|
|
PostScript</a> | <a
|
|
href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.pdf>
|
|
PDF</a>
|
|
|
|
</ul>
|
|
Additional features have are described for <A HREF="release.htm">NTP
|
|
Version 4</A>. It also retains compatibility with both NTP Version 2, as
|
|
defined in RFC-1119, and NTP Version 1, as defined in RFC-1059, although
|
|
this compatibility is sometimes strained and only semiautomatic. In
|
|
order to support in principle the ultimate precision of about 232
|
|
picoseconds in the NTP specification, <TT>ntpd</TT> uses NTP timestamp
|
|
format for external communication and double precision floating point
|
|
arithmetic internally. <TT>ntpd</TT> fully implements NTP Versions 2 and
|
|
3 authentication and in addition Version 4 autokey. It supports the NTP
|
|
mode-6 control message facility along with a private mode-7 control-
|
|
message facility used to remotely reconfigure the system and monitor a
|
|
considerable amount of internal detail. As extensions to the
|
|
specification, a flexible address-and-mask restriction facility has been
|
|
included.
|
|
|
|
<P>The code is biased towards the needs of a busy time server with
|
|
numerous, often hundreds, of clients and other servers. Tables are
|
|
hashed to allow efficient handling of many associations, though at the
|
|
expense of additional overhead when the number of associations is small.
|
|
Many fancy features have been included to permit efficient management
|
|
and monitoring of a busy primary server, features which are probably
|
|
excess baggage for a high stratum client. In such cases, a stripped-down
|
|
version of the protocol, the Simple Network Time Protocol (SNTP) can be
|
|
used. SNTP and NTP servers and clients can interwork in most situations,
|
|
as described in: Mills, D.L. Simple Network Time Protocol (SNTP).
|
|
Network Working Group Report RFC-2030, University of Delaware, October
|
|
1996, 14 pp. <A
|
|
HREF="http://www.eecis.udel.edu/~mills/database/rfc2030.txt">
|
|
(ASCII)</A>.
|
|
|
|
<P>The code was written with near demonic attention to details which can
|
|
affect precision and as a consequence should be able to make good use of
|
|
high performance, special purpose hardware such as precision oscillators
|
|
and radio clocks. The present code supports a number of radio clocks,
|
|
including those for the WWV, CHU, WWVB, MSF, DCF77, GOES and GPS radio
|
|
and satellite time services and USNO, ACTS and PTB modem time services.
|
|
It also supports the IRIG-B and IRIG-E signal format connected via an
|
|
audio codec. The server methodically avoids the use of Unix-specific
|
|
library routines where possible by implementing local versions, in order
|
|
to aid in porting the code to perverse Unix and non-Unix platforms.
|
|
|
|
<P>While this implementation conforms in most respects to the NTP
|
|
Version 3 specification RFC-1305, a number of improvements have been
|
|
made which are described in the conformance statement in the <A
|
|
HREF="biblio.htm">Further Information and Bibliography</A> page. It has
|
|
been specifically tuned to achieve the highest accuracy possible on
|
|
whatever hardware and operating-system platform is available. In
|
|
general, its precision and stability are limited only by the
|
|
characteristics of the onboard clock source used by the hardware
|
|
and operating system, usually an uncompensated crystal oscillator. On
|
|
modern RISC-based processors connected directly to radio clocks via
|
|
serial-asynchronous interfaces, the accuracy is usually limited by the
|
|
radio clock and interface to the order of a millisecond or less. The
|
|
code includes special features to support a pulse-per-second (PPS)
|
|
signal and/or an IRIG-B signal generated by some radio clocks. When used
|
|
in conjunction with a suitable hardware level converter, the accuracy
|
|
can be improved to a few tens of microseconds.
|
|
Further improvement is possible using an outboard, stabilized frequency
|
|
source, in which the accuracy and stability are limited only by the
|
|
characteristics
|
|
of that source.
|
|
|
|
<P>The NTP Version 4 distribution includes, in addition to the daemon
|
|
itself (<TT><A HREF="ntpd.htm">ntpd</A></TT>), several utility programs,
|
|
including two remote-monitoring programs (<A HREF="ntpq.htm">
|
|
<TT>ntpq</TT></A>, <TT><A HREF="ntpdc.htm">ntpdc</A></TT>), a remote
|
|
clock-setting program similar to the Unix rdate program
|
|
(<TT>ntpdate</TT>), a traceback utility u seful to discover suitable
|
|
synchronization sources (<TT>ntptrace</TT>), and various programs used
|
|
to configure the local platform and calibrate the intrinsic errors. NTP
|
|
has been ported to a large number of platforms, including most RISC and
|
|
CISC workstations and mainframes manufactured today. Example
|
|
configuration files for many models of these machines are included
|
|
in the distribution. While in most cases the standard version of the
|
|
implementation runs with no hardware or operating system modifications,
|
|
not all features of the distribution are available on all platforms. For
|
|
instance, a special feature allowing Sun workstations to achieve
|
|
accuracies in the order of 100 microseconds requires some minor changes
|
|
and additions to the kernel and input/output support.
|
|
|
|
<P>There are, however, several drawbacks to all of this. <TT>ntpd</TT>
|
|
is quite fat. This is rotten if your intended platform for the daemon is
|
|
memory limited. <TT>ntpd</TT> uses <TT>SIGIO</TT> for all input, a
|
|
facility which appears to not enjoy universal support and whose use
|
|
seems to exercise the parts of your vendors' kernels which are most
|
|
likely to have been done poorly. The code is unforgiving in the face of
|
|
kernel problems which affect performance, and generally requires that
|
|
you repair the problems in order to achieve acceptable performance. The
|
|
code has a distinctly experimental flavour and contains features which
|
|
could charitably be termed failed
|
|
experiments, but which have not been completely hacked out. Much was
|
|
learned from the addition of support for a variety of radio clocks,
|
|
with the result that some radio clock drivers could use some rewriting.
|
|
|
|
<H4>How NTP Works</H4>
|
|
|
|
The approach used by NTP to achieve reliable time synchronization from
|
|
a set of possibly unreliable remote time servers is somewhat different
|
|
than other protocols. In particular, NTP does not attempt to synchronize
|
|
clocks to each other. Rather, each server attempts to synchronize to
|
|
Universal
|
|
Coordinated Time (UTC) using the best available source and available
|
|
transmission
|
|
paths to that source. This is a fine point which is worth understanding.
|
|
A group of NTP-synchronized clocks may be close to each other in time,
|
|
but this is not a consequence of the clocks in the group having
|
|
synchronized
|
|
to each other, but rather because each clock has synchronized closely to
|
|
UTC via the best source it has access to. As such, trying to synchronize
|
|
a set of clocks to a set of servers whose time is not in mutual
|
|
agreement
|
|
may not result in any sort of useful synchronization of the clocks, even
|
|
if you don't care about UTC. However, in networks isolated from UTC
|
|
sources,
|
|
provisions can made to nominate one of them as a phantom UTC source.
|
|
|
|
<P>NTP operates on the premise that there is one true standard time, and
|
|
that if several servers which claim synchronization to standard time
|
|
disagree
|
|
about what that time is, then one or more of them must be broken. There
|
|
is no attempt to resolve differences more gracefully since the premise
|
|
is that substantial differences cannot exist. In essence, NTP expects
|
|
that
|
|
the time being distributed from the root of the synchronization subnet
|
|
will be derived from some external source of UTC (e.g., a radio clock).
|
|
This makes it somewhat inconvenient (though by no means impossible) to
|
|
synchronize hosts together without a reliable source of UTC to
|
|
synchronize
|
|
them to. If your network is isolated and you cannot access other
|
|
people's
|
|
servers across the Internet, a radio clock may make a good investment.
|
|
|
|
<P>Time is distributed through a hierarchy of NTP servers, with each
|
|
server
|
|
adopting a <I>stratum</I> which indicates how far away from an external
|
|
source of UTC it is operating at. Stratum-1 servers, which are at the
|
|
top
|
|
of the pile (or bottom, depending on your point of view), have access to
|
|
some external time source, usually a radio clock synchronized to time
|
|
signal
|
|
broadcasts from radio stations which explicitly provide a standard time
|
|
service. A stratum-2 server is one which is currently obtaining time
|
|
from
|
|
a stratum-1 server, a stratum-3 server gets its time from a stratum-2
|
|
server,
|
|
and so on. To avoid long lived synchronization loops the number of
|
|
strata
|
|
is limited to 15.
|
|
|
|
<P>Each client in the synchronization subnet (which may also be a server
|
|
for other, higher stratum clients) chooses exactly one of the available
|
|
servers to synchronize to, usually from among the lowest stratum servers
|
|
it has access to. This is, however, not always an optimal configuration,
|
|
for indeed NTP operates under another premise as well, that each
|
|
server's
|
|
time should be viewed with a certain amount of distrust. NTP really
|
|
prefers
|
|
to have access to several sources of lower stratum time (at least three)
|
|
since it can then apply an agreement algorithm to detect insanity on the
|
|
part of any one of these. Normally, when all servers are in agreement,
|
|
NTP will choose the best of these, where "best" is defined in terms of
|
|
lowest stratum, closest (in terms of network delay) and claimed
|
|
precision,
|
|
along with several other considerations. The implication is that, while
|
|
one should aim to provide each client with three or more sources of
|
|
lower
|
|
stratum time, several of these will only be providing backup service and
|
|
may be of lesser quality in terms of network delay and stratum (i.e., a
|
|
same-stratum peer which receives time from lower stratum sources the
|
|
local
|
|
server doesn't access directly can also provide good backup service).
|
|
|
|
<P>Finally, there is the issue of association modes. There are a number
|
|
of modes in which NTP servers can associate with each other, with the
|
|
mode
|
|
of each server in the pair indicating the behaviour the other server can
|
|
expect from it. In particular, when configuring a server to obtain time
|
|
from other servers, there is a choice of two modes which may be used.
|
|
Configuring
|
|
an association in symmetric-active mode (usually indicated by a
|
|
<TT>peer</TT>
|
|
declaration in the configuration file) indicates to the remote server
|
|
that
|
|
one wishes to obtain time from the remote server and that one is also
|
|
willing
|
|
to supply time to the remote server if need be. This mode is appropriate
|
|
in configurations involving a number of redundant time servers
|
|
interconnected
|
|
via diverse network paths, which is presently the case for most stratum-
|
|
1
|
|
and stratum-2 servers on the Internet today. Configuring an association
|
|
in client mode (usually indicated by a <TT>server</TT> declaration in
|
|
the
|
|
configuration file) indicates that one wishes to obtain time from the
|
|
remote
|
|
server, but that one is not willing to provide time to the remote
|
|
server.
|
|
This mode is appropriate for file-server and workstation clients that do
|
|
not provide synchronization to other local clients. Client mode is also
|
|
useful for boot-date-setting programs and the like, which really have no
|
|
time to provide and which don't retain state about associations over the
|
|
longer term.
|
|
|
|
<P>Where the requirements in accuracy and reliability are modest,
|
|
clients
|
|
can be configured to use broadcast and/or multicast modes. These modes
|
|
are not normally utilized by servers with dependent clients. The
|
|
advantage
|
|
of these modes is that clients do not need to be configured for a
|
|
specific
|
|
server, so that all clients operating can use the same configuration
|
|
file.
|
|
Broadcast mode requires a broadcast server on the same subnet, while
|
|
multicast
|
|
mode requires support for IP multicast on the client machine, as well as
|
|
connectivity via the MBONE to a multicast server. Since broadcast
|
|
messages
|
|
are not propagated by routers, only those broadcast servers on the same
|
|
subnet will be used. There is at present no way to select which of
|
|
possibly
|
|
many multicast servers will be used, since all operate on the same group
|
|
address.
|
|
|
|
<P>Where the maximum accuracy and reliability provided by NTP are
|
|
needed,
|
|
clients and servers operate in either client/server or symmetric modes.
|
|
Symmetric modes are most often used between two or more servers
|
|
operating
|
|
as a mutually redundant group. In these modes, the servers in the group
|
|
members arrange the synchronization paths for maximum performance,
|
|
depending
|
|
on network jitter and propagation delay. If one or more of the group
|
|
members
|
|
fail, the remaining members automatically reconfigure as required.
|
|
Dependent
|
|
clients and servers normally operate in client/server mode, in which a
|
|
client or dependent server can be synchronized to a group member, but no
|
|
group member can synchronize to the client or dependent server. This
|
|
provides
|
|
protection against malfunctions or protocol attacks.
|
|
|
|
<P>Servers that provide synchronization to a sizeable population of
|
|
clients
|
|
normally operate as a group of three or more mutually redundant servers,
|
|
each operating with three or more stratum-one or stratum-two servers in
|
|
client-server modes, as well as all other members of the group in
|
|
symmetric
|
|
modes. This provides protection against malfunctions in which one or
|
|
more
|
|
servers fail to operate or provide incorrect time. The NTP algorithms
|
|
have
|
|
been specifically engineered to resist attacks where some fraction of
|
|
the
|
|
configured synchronization sources accidently or purposely provide
|
|
incorrect
|
|
time. In these cases a special voting procedure is used to identify
|
|
spurious
|
|
sources and discard their data.
|
|
<H4>
|
|
Configuring Your Subnet</H4>
|
|
At startup time the <TT>ntpd</TT> daemon running on a host reads the
|
|
initial
|
|
configuration information from a file, usually <TT>/etc/ntp.conf</TT>,
|
|
unless a different name has been specified at compile time. Putting
|
|
something
|
|
in this file which will enable the host to obtain time from somewhere
|
|
else
|
|
is usually the first big hurdle after installation of the software
|
|
itself,
|
|
which is described in the <A HREF="build.htm">Building and Installing
|
|
the
|
|
Distribution</A> page. At its simplest, what you need to do in the
|
|
configuration
|
|
file is declare the servers that the daemon should poll for time
|
|
synchronization.
|
|
In principle, no such list is needed if some other time server operating
|
|
in broadcast/multicast mode is available, which requires the client to
|
|
operate in a broadcastclient mode.
|
|
|
|
<P>In the case of a workstation operating in an enterprise network for
|
|
a public or private organization, there is often an administrative
|
|
department
|
|
that coordinates network services, including NTP. Where available, the
|
|
addresses of appropriate servers can be provided by that department.
|
|
However,
|
|
if this infrastructure is not available, it is necessary to explore some
|
|
portion of the existing NTP subnet now running in the Internet. There
|
|
are
|
|
at present many thousands of time servers running NTP in the Internet,
|
|
a significant number of which are willing to provide a public time-
|
|
synchronization
|
|
service. Some of these are listed in the list of public time servers,
|
|
which
|
|
can be accessed via the <A HREF="http://www.eecis.udel.edu/~ntp">NTP web
|
|
page</A>. These data are updated on a regular basis using information
|
|
provided
|
|
voluntarily by various site administrators. There are other ways to
|
|
explore
|
|
the nearby subnet using the <TT><A HREF="ntptrace.htm">ntptrace</A></TT>
|
|
and <TT><A HREF="ntpdc.htm">ntpdc</A></TT> programs.
|
|
|
|
<P>It is vital to carefully consider the issues of robustness and
|
|
reliability
|
|
when selecting the sources of synchronization. Normally, not less than
|
|
three sources should be available, preferably selected to avoid common
|
|
points of failure. It is usually better to choose sources which are
|
|
likely
|
|
to be "close" to you in terms of network topology, though you shouldn't
|
|
worry overly about this if you are unable to determine who is close and
|
|
who isn't. Normally, it is much more serious when a server becomes
|
|
faulty
|
|
and delivers incorrect time than when it simply stops operating, since
|
|
an NTP-synchronized host normally can coast for hours or even days
|
|
without
|
|
its clock accumulating serious error approaching a second, for instance.
|
|
Selecting at least three sources from different operating
|
|
administrations,
|
|
where possible, is the minimum recommended, although a lesser number
|
|
could
|
|
provide acceptable service with a degraded degree of robustness.
|
|
|
|
<P>Normally, it is not considered good practice for a single workstation
|
|
to request synchronization from a primary (stratum-1) time server. At
|
|
present,
|
|
these servers provide synchronization for hundreds of clients in many
|
|
cases
|
|
and could, along with the network access paths, become seriously
|
|
overloaded
|
|
if large numbers of workstation clients requested synchronization
|
|
directly.
|
|
Therefore, workstations located in sparsely populated administrative
|
|
domains
|
|
with no local synchronization infrastructure should request
|
|
synchronization
|
|
from nearby stratum-2 servers instead. In most cases the keepers of
|
|
those
|
|
servers in the lists of public servers provide unrestricted access
|
|
without
|
|
prior permission; however, in all cases it is considered polite to
|
|
notify
|
|
the administrator listed in the file upon commencement of regular
|
|
service.
|
|
In all cases the access mode and notification requirements listed in the
|
|
file must be respected. Under no conditions should servers not in these
|
|
lists be used without prior permission, as to do so can create severe
|
|
problems
|
|
in the local infrastructure, especially in cases of dial-up access to
|
|
the
|
|
Internet.
|
|
|
|
<P>In the case of a gateway or file server providing service to a
|
|
significant
|
|
number of workstations or file servers in an enterprise network it is
|
|
even
|
|
more important to provide multiple, redundant sources of synchronization
|
|
and multiple, diversity-routed, network access paths. The preferred
|
|
configuration
|
|
is at least three administratively coordinated time servers providing
|
|
service
|
|
throughout the administrative domain including campus networks and
|
|
subnetworks.
|
|
Each of these should obtain service from at least two different outside
|
|
sources of synchronization, preferably via different gateways and access
|
|
paths. These sources should all operate at the same stratum level, which
|
|
is one less than the stratum level to be used by the local time servers
|
|
themselves. In addition, each of these time servers should peer with all
|
|
of the other time servers in the local administrative domain at the
|
|
stratum
|
|
level used by the local time servers, as well as at least one
|
|
(different)
|
|
outside source at this level. This configuration results in the use of
|
|
six outside sources at a lower stratum level (toward the primary source
|
|
of synchronization, usually a radio clock), plus three outside sources
|
|
at the same stratum level, for a total of nine outside sources of
|
|
synchronization.
|
|
While this may seem excessive, the actual load on network resources is
|
|
minimal, since the interval between polling messages exchanged between
|
|
peers usually ratchets back to no more than one message every 17
|
|
minutes.
|
|
|
|
<P>The stratum level to be used by the local time servers is an
|
|
engineering
|
|
choice. As a matter of policy, and in order to reduce the load on the
|
|
primary
|
|
servers, it is desirable to use the highest stratum consistent with
|
|
reliable,
|
|
accurate time synchronization throughout the administrative domain. In
|
|
the case of enterprise networks serving hundreds or thousands of client
|
|
file servers and workstations, conventional practice is to obtain
|
|
service
|
|
from stratum-1 primary servers listed for public access. When choosing
|
|
sources away from the primary sources, the particular synchronization
|
|
path
|
|
in use at any time can be verified using the <TT>ntptrace</TT> program
|
|
included in this distribution. It is important to avoid loops and
|
|
possible
|
|
common points of failure when selecting these sources. Note that, while
|
|
NTP detects and rejects loops involving neighboring servers, it does not
|
|
detect loops involving intervening servers. In the unlikely case that
|
|
all
|
|
primary sources of synchronization are lost throughout the subnet, the
|
|
remaining servers on that subnet can form temporary loops and, if the
|
|
loss
|
|
continues for an interval of many hours, the servers will drop off the
|
|
subnet and free-run with respect to their internal (disciplined) timing
|
|
sources. After some period with no outside timing source (currently one
|
|
day), a host will declare itself unsynchronized and provide this
|
|
information
|
|
to local application programs.
|
|
|
|
<P>In many cases the purchase of one or more radio clocks is justified,
|
|
in which cases good engineering practice is to use the configurations
|
|
described
|
|
above anyway and connect the radio clock to one of the local servers.
|
|
This
|
|
server is then encouraged to participate in a special primary-server
|
|
subnetwork
|
|
in which each radio-equipped server peers with several other similarly
|
|
equipped servers. In this way the radio-equipped server may provide
|
|
synchronization,
|
|
as well as receive synchronization, should the local or remote radio
|
|
clock(s)
|
|
fail or become faulty. <TT>ntpd</TT> treats attached radio clock(s) in
|
|
the same way as other servers and applies the same criteria and
|
|
algorithms
|
|
to the time indications, so can detect when the radio fails or becomes
|
|
faulty and switch to alternate sources of synchronization. It is
|
|
strongly
|
|
advised, and in practice for most primary servers today, to employ the
|
|
authentication or access-control features of the NTP specification in
|
|
order
|
|
to protect against hostile intruders and possible destabilization of the
|
|
time service. Using this or similar strategies, the remaining hosts in
|
|
the same administrative domain can be synchronized to the three (or
|
|
more)
|
|
selected time servers. Assuming these servers are synchronized directly
|
|
to stratum-1 sources and operate normally as stratum-2, the next level
|
|
away from the primary source of synchronization, for instance various
|
|
campus
|
|
file servers, will operate at stratum 3 and dependent workstations at
|
|
stratum
|
|
4. Engineered correctly, such a subnet will survive all but the most
|
|
exotic
|
|
failures or even hostile penetrations of the various, distributed
|
|
timekeeping
|
|
resources.
|
|
<P>The above arrangement should provide very good, robust time service
|
|
with a minimum of traffic to distant servers and with manageable loads
|
|
on the local servers. While it is theoretically possible to extend the
|
|
synchronization subnet to even higher strata, this is seldom justified
|
|
and can make the maintenance of configuration files unmanageable.
|
|
Serving
|
|
time to a higher stratum peer is very inexpensive in terms of the load
|
|
on the lower stratum server if the latter is located on the same
|
|
concatenated
|
|
LAN. When justified by the accuracy expectations, NTP can be operated in
|
|
broadcast and multicast modes, so that clients need only listen for
|
|
periodic
|
|
broadcasts and do not need to send anything.
|
|
|
|
<P>When planning your network you might, beyond this, keep in mind a few
|
|
generic don'ts, in particular:
|
|
<UL>
|
|
<LI>
|
|
Don't synchronize a local time server to another peer at the same
|
|
stratum,
|
|
unless the latter is receiving time from lower stratum sources the
|
|
former
|
|
doesn't talk to directly. This minimizes the occurrence of common points
|
|
of failure, but does not eliminate them in cases where the usual chain
|
|
of associations to the primary sources of synchronization are disrupted
|
|
due to failures.</LI>
|
|
|
|
<BR>
|
|
<LI>
|
|
Don't configure peer associations with higher stratum servers. Let the
|
|
higher strata configure lower stratum servers, but not the reverse. This
|
|
greatly simplifies configuration file maintenance, since there is
|
|
usually
|
|
much greater configuration churn in the high stratum clients such as
|
|
personal
|
|
workstations.</LI>
|
|
<BR>
|
|
<LI>
|
|
Don't synchronize more than one time server in a particular
|
|
administrative
|
|
domain to the same time server outside that domain. Such a practice
|
|
invites
|
|
common points of failure, as well as raises the possibility of massive
|
|
abuse, should the configuration file be automatically distributed do a
|
|
large number of clients.</LI>
|
|
</UL>
|
|
There are many useful exceptions to these rules. When in doubt, however,
|
|
follow them.
|
|
<H4>
|
|
Configuring Your Server or Client</H4>
|
|
As mentioned previously, the configuration file is usually called
|
|
/etc/ntp.conf.
|
|
This is an ASCII file conforming to the usual comment and whitespace
|
|
conventions.
|
|
A working configuration file might look like (in this and other
|
|
examples,
|
|
do not copy this directly):
|
|
<PRE> # peer configuration for host whimsy
|
|
# (expected to operate at stratum 2)
|
|
|
|
server rackety.udel.edu
|
|
server umd1.umd.edu
|
|
server lilben.tn.cornell.edu
|
|
|
|
driftfile /etc/ntp.drift</PRE>
|
|
(Note the use of host names, although host addresses in dotted-quad
|
|
notation
|
|
can also be used. It is always preferable to use names rather than
|
|
addresses,
|
|
since over time the addresses can change, while the names seldom
|
|
change.)
|
|
|
|
<P>This particular host is expected to operate as a client at stratum 2
|
|
by virtue of the <TT>server</TT> keyword and the fact that two of the
|
|
three
|
|
servers declared (the first two) have radio clocks and usually run at
|
|
stratum
|
|
1. The third server in the list has no radio clock, but is known to
|
|
maintain
|
|
associations with a number of stratum 1 peers and usually operates at
|
|
stratum
|
|
2. Of particular importance with the last host is that it maintains
|
|
associations
|
|
with peers besides the two stratum 1 peers mentioned. This can be
|
|
verified
|
|
using the <TT>ntpq</TT> program mentioned above. When configured using
|
|
the <TT>server</TT> keyword, this host can receive synchronization from
|
|
any of the listed servers, but can never provide synchronization to
|
|
them.
|
|
|
|
<P>Unless restricted using facilities described later, this host can
|
|
provide
|
|
synchronization to dependent clients, which do not have to be listed in
|
|
the configuration file. Associations maintained for these clients are
|
|
transitory
|
|
and result in no persistent state in the host. These clients are
|
|
normally
|
|
not visible using the <TT>ntpq</TT> program included in the
|
|
distribution;
|
|
however, <TT>ntpd</TT> includes a monitoring feature (described later)
|
|
which caches a minimal amount of client information useful for debugging
|
|
administrative purposes.
|
|
|
|
<P>A time server expected to both receive synchronization from another
|
|
server, as well as to provide synchronization to it, is declared using
|
|
the <TT>peer</TT> keyword instead of the <TT>server</TT> keyword. In all
|
|
other aspects the server operates the same in either mode and can
|
|
provide
|
|
synchronization to dependent clients or other peers. If a local source
|
|
of UTC time is available, it is considered good engineering practice to
|
|
declare time servers outside the administrative domain as <TT>peer</TT>
|
|
and those inside as <TT>server</TT> in order to provide redundancy in
|
|
the
|
|
global Internet, while minimizing the possibility of instability within
|
|
the domain itself. A time server in one domain can in principle heal
|
|
another
|
|
domain temporarily isolated from all other sources of synchronization.
|
|
However, it is probably unwise for a casual workstation to bridge
|
|
fragments
|
|
of the local domain which have become temporarily isolated.
|
|
|
|
<P>Note the inclusion of a <TT>driftfile</TT> declaration. One of the
|
|
things
|
|
the NTP daemon does when it is first started is to compute the error in
|
|
the intrinsic frequency of the clock on the computer it is running on.
|
|
It usually takes about a day or so after the daemon is started to
|
|
compute
|
|
a good estimate of this (and it needs a good estimate to synchronize
|
|
closely
|
|
to its server). Once the initial value is computed, it will change only
|
|
by relatively small amounts during the course of continued operation.
|
|
The
|
|
<TT>driftfile</TT> declaration indicates to the daemon the name of a
|
|
file
|
|
where it may store the current value of the frequency error so that, if
|
|
the daemon is stopped and restarted, it can reinitialize itself to the
|
|
previous estimate and avoid the day's worth of time it will take to
|
|
recompute
|
|
the frequency estimate. Since this is a desirable feature, a
|
|
<TT>driftfile</TT>
|
|
declaration should always be included in the configuration file.
|
|
|
|
<P>An implication in the above is that, should <TT>ntpd</TT> be stopped
|
|
for some reason, the local platform time will diverge from UTC by an
|
|
amount
|
|
that depends on the intrinsic error of the clock oscillator and the time
|
|
since last synchronized. In view of the length of time necessary to
|
|
refine
|
|
the frequency estimate, every effort should be made to operate the
|
|
daemon
|
|
on a continuous basis and minimize the intervals when for some reason it
|
|
is not running.
|
|
|
|
<H4>
|
|
Configuring NTP with NetInfo</H4>
|
|
If NetInfo support is compiled into NTP, you can opt to configure ntp
|
|
in your NetInfo domain. NTP will look int he NetInfo directory
|
|
<TT>/locations/ntp</TT> for property/value pairs which are equivalent
|
|
the the lines in the configuration file described above. Each
|
|
configuration keyword may have a coresponding property in NetInfo.
|
|
Each value for a given property is treated as arguments to that property,
|
|
similar to a line in the configuration file.
|
|
|
|
<P>For example, the configuration shown in the configuration file above
|
|
can be duplicated in NetInfo by adding a property "<TT>server</TT>" with
|
|
values "<TT>rackety.udel.edu</TT>", "<TT>umd1.umd.edu</TT>", and
|
|
"<TT>lilben.tn.cornell.edu</TT>"; and a property "<TT>driftfile</TT>"
|
|
with the single value "<TT>/etc/ntp.drift</TT>".
|
|
|
|
<P>Values may contain multiple tokens similar to the arguments available
|
|
in the configuration file. For example, to use <TT>mimsy.mil</TT> as an
|
|
NTP version 1 time server, you would add a value "<TT>mimsy.mil version
|
|
1</TT>" to the "<TT>server</TT>" property.
|
|
|
|
<H4>
|
|
Ntp4 Versus Previous Versions</H4>
|
|
There are several items of note when dealing with a mixture of
|
|
<TT>ntp4</TT>
|
|
and previous distributions of NTP Version 2 (<TT>ntpd</TT>) and NTP
|
|
Version
|
|
1 (<TT>ntp3.4</TT>). The <TT>ntp4</TT> implementation conforms to the
|
|
NTP
|
|
Version 3 specification RFC-1305 and, in addition, contains additional
|
|
feaures documented in the <A HREF="release.htm">Release Notes</A> page.
|
|
As such, by default when no additional information is available
|
|
concerning
|
|
the preferences of the peer, <TT>ntpd</TT> claims to be version 4 in the
|
|
packets that it sends from configured associations. The <TT>version
|
|
</TT>subcommand
|
|
of the <TT>server</TT>, <TT>peer</TT>, <TT>broadcast </TT>and
|
|
<TT>manycastclient
|
|
</TT>command can be used to change the default. In unconfigured
|
|
(ephemeral)
|
|
associaitons, the daemon always replies in the same version as the
|
|
request.
|
|
|
|
<P>An NTP implementation conforming to a previous version specification
|
|
ordinarily discards packets from a later version. However, in most
|
|
respects
|
|
documented in RFC-1305, The version 2 implementation is compatible with
|
|
the version 3 algorithms and protocol. The version 1 implementation
|
|
contains
|
|
most of the version 2 algorithms, but without important features for
|
|
clock
|
|
selection and robustness. Nevertheless, in most respects the NTP
|
|
versions
|
|
are backwards compatible. The sticky part here is that, when a previous
|
|
version implementation receives a packet claiming to be from a version
|
|
4 server, it discards it without further processing. Hence there is a
|
|
danger
|
|
that in some situations synchronization with previous versions will
|
|
fail.
|
|
|
|
<P>The trouble occurs when an previous version is to be included in an
|
|
<TT>ntpd</TT> configuration file. With no further indication,
|
|
<TT>ntpd</TT>
|
|
will send packets claiming to be version 4 when it polls. To get around
|
|
this, <TT>ntpd</TT> allows a qualifier to be added to configuration
|
|
entries
|
|
to indicate which version to use when polling. Hence the entries
|
|
<PRE> # specify NTP version 1
|
|
|
|
server mimsy.mil version
|
|
1 # server running ntpd version 1
|
|
server apple.com version
|
|
2 # server running ntpd version 2</PRE>
|
|
will cause version 1 packets to be sent to the host mimsy.mil and
|
|
version
|
|
2 packets to be sent to apple.com. If you are testing <TT>ntpd</TT>
|
|
against
|
|
previous version servers you will need to be careful about this. Note
|
|
that,
|
|
as indicated in the RFC-1305 specification, there is no longer support
|
|
for the original NTP specification, once called NTP Version 0.
|
|
<H4>
|
|
Traffic Monitoring</H4>
|
|
<TT>ntpd</TT> handles peers whose stratum is higher than the stratum of
|
|
the local server and polls using client mode by a fast path which
|
|
minimizes
|
|
the work done in responding to their polls, and normally retains no
|
|
memory
|
|
of these pollers. Sometimes, however, it is interesting to be able to
|
|
determine
|
|
who is polling the server, and how often, as well as who has been
|
|
sending
|
|
other types of queries to the server.
|
|
|
|
<P>To allow this, <TT>ntpd</TT> implements a traffic monitoring facility
|
|
which records the source address and a minimal amount of other
|
|
information
|
|
from each packet which is received by the server. This feature is
|
|
normally
|
|
enabled, but can be disabled if desired using the configuration file
|
|
entry:
|
|
<PRE> # disable monitoring feature
|
|
disable monitor</PRE>
|
|
The recorded information can be displayed using the <TT>ntpdc</TT> query
|
|
program, described briefly below.
|
|
<H4>
|
|
Address-and-Mask Restrictions</H4>
|
|
The address-and-mask configuration facility supported by <TT>ntpd</TT>
|
|
is quite flexible and general, but is not an integral part of the NTP
|
|
Version
|
|
3 specification. The major drawback is that, while the internal
|
|
implementation
|
|
is very nice, the user interface is not. For this reason it is probably
|
|
worth doing an example here. Briefly, the facility works as follows.
|
|
There
|
|
is an internal list, each entry of which holds an address, a mask and a
|
|
set of flags. On receipt of a packet, the source address of the packet
|
|
is compared to each entry in the list, with a match being posted when
|
|
the
|
|
following is true:
|
|
<PRE> (source_addr & mask) == (address &
|
|
mask)</PRE>
|
|
A particular source address may match several list entries. In this case
|
|
the entry with the most one bits in the mask is chosen. The flags
|
|
associated
|
|
with this entry are used to control the access.
|
|
|
|
<P>In the current implementation the flags always add restrictions. In
|
|
effect, an entry with no flags set leaves matching hosts unrestricted.
|
|
An entry can be added to the internal list using a <TT>restrict</TT>
|
|
declaration.
|
|
The flags associated with the entry are specified textually. For
|
|
example,
|
|
the <TT>notrust</TT> flag indicates that hosts matching this entry,
|
|
while
|
|
treated normally in other respects, shouldn't be trusted to provide
|
|
synchronization
|
|
even if otherwise so enabled. The <TT>nomodify</TT> flag indicates that
|
|
hosts matching this entry should not be allowed to do run-time
|
|
configuration.
|
|
There are many more flags, see the <A HREF="ntpd.htm"><TT>ntpd</TT>
|
|
</A>page.
|
|
|
|
<P>Now the example. Suppose you are running the server on a host whose
|
|
address is 128.100.100.7. You would like to ensure that run time
|
|
reconfiguration
|
|
requests can only be made from the local host and that the server only
|
|
ever synchronizes to one of a pair of off-campus servers or, failing
|
|
that,
|
|
a time source on net 128.100. The following entries in the configuration
|
|
file would implement this policy:
|
|
<PRE> # by default, don't trust and don't allow
|
|
modifications
|
|
|
|
restrict default notrust nomodify
|
|
|
|
# these guys are trusted for time, but no
|
|
modifications allowed
|
|
|
|
restrict 128.100.0.0 mask 255.255.0.0 nomodify
|
|
restrict 128.8.10.1 nomodify
|
|
restrict 192.35.82.50 nomodify
|
|
|
|
# the local addresses are unrestricted
|
|
|
|
restrict 128.100.100.7
|
|
restrict 127.0.0.1</PRE>
|
|
The first entry is the default entry, which all hosts match and hence
|
|
which
|
|
provides the default set of flags. The next three entries indicate that
|
|
matching hosts will only have the <TT>nomodify</TT> flag set and hence
|
|
will be trusted for time. If the mask isn't specified in the
|
|
<TT>restrict</TT>
|
|
keyword, it defaults to 255.255.255.255. Note that the address
|
|
128.100.100.7
|
|
matches three entries in the table, the default entry (mask 0.0.0.0),
|
|
the
|
|
entry for net 128.100 (mask 255.255.0.0) and the entry for the host
|
|
itself
|
|
(mask 255.255.255.255). As expected, the flags for the host are derived
|
|
from the last entry since the mask has the most bits set.
|
|
|
|
<P>The only other thing worth mentioning is that the <TT>restrict</TT>
|
|
declarations apply to packets from all hosts, including those that are
|
|
configured elsewhere in the configuration file and even including your
|
|
clock pseudopeer(s), if any. Hence, if you specify a default set of
|
|
restrictions
|
|
which you don't wish to be applied to your configured peers, you must
|
|
remove
|
|
those restrictions for the configured peers with additional
|
|
<TT>restrict</TT>
|
|
declarations mentioning each peer separately.
|
|
<H4>
|
|
Authentication</H4>
|
|
<TT>ntpd</TT> supports the optional authentication procedure specified
|
|
in the NTP Version 2 and 3 specifications. Briefly, when an association
|
|
runs in authenticated mode, each packet transmitted has appended to it
|
|
a 32-bit key ID and a 64/128-bit cryptographic checksum of the packet
|
|
contents
|
|
computed using either the Data Encryption Standard (DES) or Message
|
|
Digest
|
|
(MD5) algorithms. Note that, while either of these algorithms provide
|
|
sufficient
|
|
protection from message- modification attacks, distribution of the
|
|
former
|
|
algorithm implementation is restricted to the U.S. and Canada, while the
|
|
latter presently is free from such restrictions. For this reason, the
|
|
DES
|
|
algorithm is not included in the current distribution. Directions for
|
|
obtaining
|
|
it in other countries is in the <A HREF="build.htm">Building and
|
|
Installing
|
|
the Distribution</A> page. With either algorithm the receiving peer
|
|
recomputes
|
|
the checksum and compares it with the one included in the packet. For
|
|
this
|
|
to work, the peers must share at least one encryption key and,
|
|
furthermore,
|
|
must associate the shared key with the same key ID.
|
|
|
|
<P>This facility requires some minor modifications to the basic packet
|
|
processing procedures, as required by the specification. These
|
|
modifications
|
|
are enabled by the <TT>enable auth</TT> configuration declaration, which
|
|
is currently the default. In authenticated mode, peers which send
|
|
unauthenticated
|
|
packets, peers which send authenticated packets which the local server
|
|
is unable to decrypt and peers which send authenticated packets
|
|
encrypted
|
|
using a key we don't trust are all marked untrustworthy and unsuitable
|
|
for synchronization. Note that, while the server may know many keys
|
|
(identified
|
|
by many key IDs), it is possible to declare only a subset of these as
|
|
trusted.
|
|
This allows the server to share keys with a client which requires
|
|
authenticated
|
|
time and which trusts the server, but which is not trusted by the
|
|
server.
|
|
Also, some additional configuration language is required to specify the
|
|
key ID to be used to authenticate each configured peer association.
|
|
Hence,
|
|
for a server running in authenticated mode, the configuration file might
|
|
look similar to the following:
|
|
<PRE> # peer configuration for 128.100.100.7
|
|
# (expected to operate at stratum 2)
|
|
# fully authenticated this time
|
|
|
|
peer 128.100.49.105 key 22 #
|
|
suzuki.ccie.utoronto.ca
|
|
peer 128.8.10.1 key 4 #
|
|
umd1.umd.edu
|
|
peer 192.35.82.50 key 6 #
|
|
lilben.tn.cornell.edu
|
|
|
|
keys /usr/local/etc/ntp.keys # path for
|
|
key file
|
|
trustedkey 1 2 14 15 #
|
|
define trusted keys
|
|
requestkey
|
|
15 #
|
|
key (7) for accessing server variables
|
|
controlkey
|
|
15 #
|
|
key (6) for accessing server variables
|
|
|
|
authdelay
|
|
0.000094 # authentication delay
|
|
(Sun4c/50 IPX)</PRE>
|
|
There are a couple of previously unmentioned things in here. The
|
|
<TT>keys
|
|
</TT>line specifies the path to the keys file (see below and the
|
|
<TT>ntpd</TT>
|
|
document page for details of the file format). The <TT>trustedkey</TT>
|
|
declaration identifies those keys that are known to be uncompromised;
|
|
the
|
|
remainder presumably represent the expired or possibly compromised keys.
|
|
Both sets of keys must be declared by key identifier in the
|
|
<TT>ntp.keys</TT>
|
|
file described below. This provides a way to retire old keys while
|
|
minimizing
|
|
the frequency of delicate key-distribution procedures. The
|
|
<TT>requestkey</TT>
|
|
line establishes the key to be used for mode-6 control messages as
|
|
specified
|
|
in RFC-1305 and used by the <TT>ntpq</TT> utility program, while the
|
|
<TT>controlkey
|
|
</TT>line establishes the key to be used for mode-7 private control
|
|
messages
|
|
used by the <TT>ntpdc</TT> utility program. These keys are used to
|
|
prevent
|
|
unauthorized modification of daemon variables.
|
|
|
|
<P>Ordinarily, the authentication delay; that is, the processing time
|
|
taken
|
|
between the freezing of a transmit timestamp and the actual transmission
|
|
of the packet when authentication is enabled (i.e. more or less the time
|
|
it takes for the DES or MD5 routine to encrypt a single block) is
|
|
computed
|
|
automatically by the daemon. If necessary, the delay can be overriden by
|
|
the <TT>authdelay </TT>line, which is used as a correction for the
|
|
transmit
|
|
timestamp. This can be computed for your CPU by the <A
|
|
HREF="authspeed.htm"><TT>authspeed</TT>
|
|
</A>program included in the distribution. The usage is illustrated by
|
|
the
|
|
following:
|
|
<PRE> # for DES keys
|
|
|
|
authspeed -n 30000 auth.samplekeys
|
|
# for MD5 keys
|
|
|
|
authspeed -mn 30000 auth.samplekeys</PRE>
|
|
Additional utility programs included in the <TT>./authstuff</TT>
|
|
directory
|
|
can be used to generate random keys, certify implementation correctness
|
|
and display sample keys. As a general rule, keys should be chosen
|
|
randomly,
|
|
except possibly the request and control keys, which must be entered by
|
|
the user as a password.
|
|
|
|
<P>The <TT>ntp.keys</TT> file contains the list of keys and associated
|
|
key IDs the server knows about (for obvious reasons this file is better
|
|
left unreadable by anyone except root). The contents of this file might
|
|
look like:
|
|
<PRE> # ntp keys file (ntp.keys)
|
|
1 N
|
|
29233E0461ECD6AE # des key in NTP format
|
|
2 M
|
|
RIrop8KPPvQvYotM # md5 key as an ASCII random string
|
|
14 M
|
|
sundial  
|
|
; # md5 key as an ASCII string
|
|
15 A
|
|
sundial  
|
|
; # des key as an ASCII string
|
|
|
|
# the following 3 keys are identical
|
|
|
|
10 A SeCReT
|
|
10 N
|
|
d3e54352e5548080
|
|
10 S
|
|
a7cb86a4cba80101</PRE>
|
|
In the keys file the first token on each line indicates the key ID, the
|
|
second token the format of the key and the third the key itself. There
|
|
are four key formats. An <TT>A</TT> indicates a DES key written as a 1-
|
|
to-8
|
|
character string in 7-bit ASCII representation, with each character
|
|
standing
|
|
for a key octet (like a Unix password). An <TT>S</TT> indicates a DES
|
|
key
|
|
written as a hex number in the DES standard format, with the low order
|
|
bit (LSB) of each octet being the (odd) parity bit. An <TT>N</TT>
|
|
indicates
|
|
a DES key again written as a hex number, but in NTP standard format with
|
|
the high order bit of each octet being the (odd) parity bit (confusing
|
|
enough?). An <TT>M</TT> indicates an MD5 key written as a 1-to-31
|
|
character
|
|
ASCII string in the <TT>A</TT> format. Note that, because of the simple
|
|
tokenizing routine, the characters <TT>' ', '#', '\t', '\n'</TT> and
|
|
<TT>'\0'</TT>
|
|
can't be used in either a DES or MD5 ASCII key. Everything else is fair
|
|
game, though. Key 0 (zero) is used for special purposes and should not
|
|
appear in this file.
|
|
|
|
<P>The big trouble with the authentication facility is the keys file. It
|
|
is a maintenance headache and a security problem. This should be fixed
|
|
some day. Presumably, this whole bag of worms goes away if/when a
|
|
generic
|
|
security regime for the Internet is established. An alternative with NTP
|
|
Version 4 is the autokey feature, which uses random session keys and
|
|
public-key
|
|
cruptography and avoids the key file entirely. While this feature is not
|
|
completely finished yet, details can be found in the <A
|
|
HREF="release.htm">Release
|
|
Notes</A> page.
|
|
<H4>
|
|
Query Programs</H4>
|
|
Three utility query programs are included with the distribution,
|
|
<TT>ntpq</TT>,
|
|
<TT>ntptrace</TT> and <TT>ntpdc</TT>. <TT>ntpq</TT> is a handy program
|
|
which sends queries and receives responses using NTP standard mode-6
|
|
control
|
|
messages. Since it uses the standard control protocol specified in RFC-
|
|
1305,
|
|
it may be used with NTP Version 2 and Version 3 implementations for both
|
|
Unix and Fuzzball, but not Version 1 implementations. It is most useful
|
|
to query remote NTP implementations to assess timekeeping accuracy and
|
|
expose bugs in configuration or operation.
|
|
|
|
<P><TT>ntptrace</TT> can be used to display the current synchronization
|
|
path from a selected host through possibly intervening servers to the
|
|
primary
|
|
source of synchronization, usually a radio clock. It works with both
|
|
version
|
|
2 and version 3 servers, but not version 1.
|
|
|
|
<P><TT>ntpdc</TT> is a horrid program which uses NTP private mode-7
|
|
control
|
|
messages to query local or remote servers. The format and contents of
|
|
these
|
|
messages are specific to this version of <TT>ntpd</TT> and some older
|
|
versions.
|
|
The program does allow inspection of a wide variety of internal counters
|
|
and other state data, and hence does make a pretty good debugging tool,
|
|
even if it is frustrating to use. The other thing of note about
|
|
<TT>ntpdc</TT>
|
|
is that it provides a user interface to the run time reconfiguration
|
|
facility.
|
|
See the respective document pages for details on the use of these
|
|
programs.
|
|
<H4>
|
|
Run-Time Reconfiguration</H4>
|
|
<TT>ntpd</TT> was written specifically to allow its configuration to be
|
|
fully modifiable at run time. Indeed, the only way to configure the
|
|
server
|
|
is at run time. The configuration file is read only after the rest of
|
|
the
|
|
server has been initialized into a running default-configured state.
|
|
This
|
|
facility was included not so much for the benefit of Unix, where it is
|
|
handy but not strictly essential, but rather for dedicated platforms
|
|
where
|
|
the feature is more important for maintenance. Nevertheless, run time
|
|
configuration
|
|
works very nicely for Unix servers as well.
|
|
|
|
<P>Nearly all of the things it is possible to configure in the
|
|
configuration
|
|
file may be altered via NTP mode-7 messages using the <TT>ntpdc</TT>
|
|
program.
|
|
Mode-6 messages may also provide some limited configuration
|
|
functionality
|
|
(though the only thing you can currently do with mode-6 messages is set
|
|
the leap-second warning bits) and the <TT>ntpq</TT> program provides
|
|
generic
|
|
support for the latter. The leap bits that can be set in the
|
|
<TT>leap_warning</TT>
|
|
variable (up to one month ahead) and in the <TT>leap_indication</TT>
|
|
variable
|
|
have a slightly different encoding than the usual interpretation:
|
|
<PRE>
|
|
Value Action
|
|
|
|
|
|
00 &nbs
|
|
p; The daemon passes the leap bits of its
|
|
|
|
|
|
synchronisation source (usual mode of operation)
|
|
|
|
01/10 A leap
|
|
second is added/deleted
|
|
|
|
|
|
11 &nbs
|
|
p; Leap information from the synchronization source
|
|
|
|
is
|
|
ignored (thus LEAP_NOWARNING is passed on)</PRE>
|
|
Mode-6 and mode-7 messages which would modify the configuration of the
|
|
server are required to be authenticated using standard NTP
|
|
authentication.
|
|
To enable the facilities one must, in addition to specifying the
|
|
location
|
|
of a keys file, indicate in the configuration file the key IDs to be
|
|
used
|
|
for authenticating reconfiguration commands. Hence the following
|
|
fragment
|
|
might be added to a configuration file to enable the mode-6 (ntpq) and
|
|
mode-7 (ntpdc) facilities in the daemon:
|
|
<PRE> # specify mode-6 and mode-7 trusted keys
|
|
|
|
requestkey 65535 # for mode-7
|
|
requests
|
|
controlkey 65534 # for mode-6
|
|
requests</PRE>
|
|
If the <TT>requestkey</TT> and/or the <TT>controlkey</TT> configuration
|
|
declarations are omitted from the configuration file, the corresponding
|
|
run-time reconfiguration facility is disabled.
|
|
|
|
<P>The query programs require the user to specify a key ID and a key to
|
|
use for authenticating requests to be sent. The key ID provided should
|
|
be the same as the one mentioned in the configuration file, while the
|
|
key
|
|
should match that corresponding to the key ID in the keys file. As the
|
|
query programs prompt for the key as a password, it is useful to make
|
|
the
|
|
request and control authentication keys typeable (in ASCII format) from
|
|
the keyboard.
|
|
<H4>
|
|
Name Resolution</H4>
|
|
<TT>ntpd</TT> includes the capability to specify host names requiring
|
|
resolution
|
|
in <TT>peer</TT> and <TT>server</TT> declarations in the configuration
|
|
file. However, in some outposts of the Internet, name resolution is
|
|
unreliable
|
|
and the interface to the Unix resolver routines is synchronous. The
|
|
hangups
|
|
and delays resulting from name-resolver clanking can be unacceptable
|
|
once
|
|
the NTP server is running (and remember it is up and running before the
|
|
configuration file is read). However, it is advantageous to resolve time
|
|
server names, since their addresses are occasionally changed.
|
|
|
|
<P>In order to prevent configuration delays due to the name resolver,
|
|
the
|
|
daemon runs the name resolution process in parallel with the main daemon
|
|
code. When the daemon comes across a <TT>peer</TT> or <TT>server</TT>
|
|
entry
|
|
with a non-numeric host address, it records the relevant information in
|
|
a temporary file and continues on. When the end of the configuration
|
|
file
|
|
has been reached and one or more entries requiring name resolution have
|
|
been found, the server runs the name resolver from the temporary file.
|
|
The server then continues on normally but with the offending
|
|
peers/servers
|
|
omitted from its configuration.
|
|
|
|
<P>As each name is resolved, it configures the associated entry into the
|
|
server using the same mode-7 run time reconfiguration facility that
|
|
<TT>ntpdc</TT>
|
|
uses. If temporary resolver failures occur, the resolver will
|
|
periodically
|
|
retry the requests until a definite response is received. The program
|
|
will
|
|
continue to run until all entries have been resolved.
|
|
<H4>
|
|
<A NAME="frequency_tolerance">Dealing with Frequency Tolerance
|
|
Violations</A>
|
|
(<TT>tickadj</TT> and Friends)</H4>
|
|
The NTP Version 3 specification RFC-1305 calls for a maximum oscillator
|
|
frequency tolerance of +-100 parts-per-million (PPM), which is
|
|
representative
|
|
of those components suitable for use in relatively inexpensive
|
|
workstation
|
|
platforms. For those platforms meeting this tolerance, NTP will
|
|
automatically
|
|
compensate for the frequency errors of the individual oscillator and no
|
|
further adjustments are required, either to the configuration file or to
|
|
various kernel variables. For the NTP Version 4 release, this tolerance
|
|
has been increased to +-500 PPM.
|
|
|
|
<P>However, in the case of certain notorious platforms, in particular
|
|
Sun
|
|
4.1.1 systems, the performance can be improved by adjusting the values
|
|
of certain kernel variables; in particular, <TT>tick</TT> and
|
|
<TT>tickadj</TT>.
|
|
The variable <TT>tick</TT> is the increment in microseconds added to the
|
|
system time on each interval- timer interrupt, while the variable
|
|
<TT>tickadj</TT>
|
|
is used by the time adjustment code as a slew rate, in microseconds per
|
|
tick. When the time is being adjusted via a call to the system routine
|
|
<TT>adjtime()</TT>, the kernel increases or reduces tick by
|
|
<TT>tickadj</TT>
|
|
microseconds per tick until the specified adjustment has been completed.
|
|
Unfortunately, in most Unix implementations the tick increment must be
|
|
either zero or plus/minus exactly <TT>tickadj</TT> microseconds, meaning
|
|
that adjustments are truncated to be an integral multiple of
|
|
<TT>tickadj</TT>
|
|
(this latter behaviour is a misfeature, and is the only reason the
|
|
<TT>tickadj</TT>
|
|
code needs to concern itself with the internal implementation of
|
|
<TT>tickadj</TT>
|
|
at all). In addition, the stock Unix implementation considers it an
|
|
error
|
|
to request another adjustment before a prior one has completed.
|
|
<P>Thus, to make very sure it avoids problems related to the roundoff,
|
|
the <TT>tickadj </TT>program can be used to adjust the values of
|
|
<TT>tick</TT>
|
|
and <TT>tickadj</TT>. This ensures that all adjustments given to
|
|
<TT>adjtime()</TT>
|
|
are an even multiple of <TT>tickadj</TT> microseconds and computes the
|
|
largest adjustment that can be completed in the adjustment interval
|
|
(using
|
|
both the value of <TT>tick</TT> and the value of <TT>tickadj</TT>) so it
|
|
can avoid exceeding this limit. It is important to note that not all
|
|
systems
|
|
will allow inspection or modification of kernel variables other than at
|
|
system build time. It is also important to know that, with the current
|
|
NTP tolerances, it is rarely necessary to make these changes, but in
|
|
many
|
|
cases they will substantially improve the general accurace of the time
|
|
service.
|
|
|
|
<P>Unfortunately, the value of <TT>tickadj</TT> set by default is almost
|
|
always too large for <TT>ntpd</TT>. NTP operates by continuously making
|
|
small adjustments to the clock, usually at one-second intervals. If
|
|
<TT>tickadj</TT>
|
|
is set too large, the adjustments will disappear in the roundoff; while,
|
|
if <TT>tickadj</TT> is too small, NTP will have difficulty if it needs
|
|
to make an occasional large adjustment. While the daemon itself will
|
|
read
|
|
the kernel's values of these variables, it will not change the values,
|
|
even if they are unsuitable. You must do this yourself before the daemon
|
|
is started using the <TT>tickadj</TT> program included in the
|
|
<TT>./util</TT>
|
|
directory of the distribution. Note that the latter program will also
|
|
compute
|
|
an optimal value of <TT>tickadj</TT> for NTP use based on the kernel's
|
|
value of <TT>tick</TT>.
|
|
|
|
<P>The <TT>tickadj</TT> program can reset several other kernel variables
|
|
if asked. It can change the value of <TT>tick</TT> if asked. This is
|
|
handy to compensate for kernel bugs which cause the clock to run with a
|
|
very large frequency error, as with SunOS 4.1.1 systems. It can also be
|
|
used to set the value of the kernel <TT>dosynctodr</TT> variable to
|
|
zero. This variable controls whether to synchronize the system clock to
|
|
the time-of-day clock, something you really don't want to be happen
|
|
when <TT>ntpd</TT> is trying to keep it under control. In some systems,
|
|
such as recent Sun Solaris kernels, the <TT>dosynctodr </TT>variable is
|
|
the only one that can be changed by the <TT>tickadj </TT>program. In
|
|
this and other modern kernels, it is not necessary to change the other
|
|
variables in any case.
|
|
|
|
<P>
|
|
We have a report that says starting with Solaris 2.6 we should
|
|
leave <I>dosynctodr</I> alone.
|
|
<A HREF="solaris-dosynctodr.html">Here is the report</A>.
|
|
|
|
<P>In order to maintain reasonable correctness bounds, as well as
|
|
reasonably
|
|
good accuracy with acceptable polling intervals, <TT>ntpd</TT> will
|
|
complain
|
|
if the frequency error is greater than 500 PPM. For machines with a
|
|
value
|
|
of <TT>tick</TT> in the 10-ms range, a change of one in the value of
|
|
<TT>tick</TT>
|
|
will change the frequency by about 100 PPM. In order to determine the
|
|
value
|
|
of <TT>tick</TT> for a particular CPU, disconnect the machine from all
|
|
sources of time (<TT>dosynctodr</TT> = 0) and record its actual time
|
|
compared
|
|
to an outside source (eyeball-and-wristwatch will do) over a day or
|
|
more.
|
|
Multiply the time change over the day by 0.116 and add or subtract the
|
|
result to tick, depending on whether the CPU is fast or slow. An example
|
|
call to <TT>tickadj</TT> useful on SunOS 4.1.1 is:
|
|
<PRE> <TT>tickadj</TT> -t 9999 -a 5 -s</PRE>
|
|
which sets tick 100 PPM fast, <TT>tickadj</TT> to 5 microseconds and
|
|
turns
|
|
off the clock/calendar chip fiddle. This line can be added to the
|
|
<TT>rc.local</TT>
|
|
configuration file to automatically set the kernel variables at boot
|
|
time.
|
|
|
|
<P>All this stuff about diddling kernel variables so the NTP daemon will
|
|
work is really silly. If vendors would ship machines with clocks that
|
|
kept
|
|
reasonable time and would make their <TT>adjtime()</TT> system call
|
|
apply
|
|
the slew it is given exactly, independent of the value of
|
|
<TT>tickadj</TT>,
|
|
all this could go away. This is in fact the case on many current Unix
|
|
systems.
|
|
<H4>
|
|
Tuning Your Subnet</H4>
|
|
There are several parameters available for tuning the NTP subnet for
|
|
maximum
|
|
accuracy and minimum jitter. One of these is the <TT>prefer</TT>
|
|
configuration
|
|
declaration described in <A HREF="prefer.htm">Mitigation Rules and the
|
|
<TT>prefer</TT> Keyword </A>documentation page. When more than one
|
|
eligible
|
|
server exists, the NTP clock-selection and combining algorithms act to
|
|
winnow out all except the "best" set of servers using several criteria
|
|
based on differences between the readings of different servers and
|
|
between
|
|
successive readings of the same server. The result is usually a set of
|
|
surviving servers that are apparently statistically equivalent in
|
|
accuracy,
|
|
jitter and stability. The population of survivors remaining in this set
|
|
depends on the individual server characteristics measured during the
|
|
selection
|
|
process and may vary from time to time as the result of normal
|
|
statistical
|
|
variations. In LANs with high speed RISC-based time servers, the
|
|
population
|
|
can become somewhat unstable, with individual servers popping in and out
|
|
of the surviving population, generally resulting in a regime called
|
|
<I>clockhopping</I>.
|
|
|
|
<P>When only the smallest residual jitter can be tolerated, it may be
|
|
convenient
|
|
to elect one of the servers at each stratum level as the preferred one
|
|
using the keyword <TT>prefer</TT> on the configuration declaration for
|
|
the selected server:
|
|
<PRE> # preferred server declaration
|
|
|
|
peer rackety.udel.edu prefer
|
|
# preferred server</PRE>
|
|
The preferred server will always be included in the surviving
|
|
population,
|
|
regardless of its characteristics and as long as it survives preliminary
|
|
sanity checks and validation procedures.
|
|
|
|
<P>The most useful application of the <TT>prefer</TT> keyword is in high
|
|
speed LANs equipped with precision radio clocks, such as a GPS receiver.
|
|
In order to insure robustness, the hosts need to include outside peers
|
|
as well as the GPS-equipped server; however, as long as that server is
|
|
running, the synchronization preference should be that server. The
|
|
keyword
|
|
should normally be used in all cases in order to prefer an attached
|
|
radio
|
|
clock. It is probably inadvisable to use this keyword for peers outside
|
|
the LAN, since it interferes with the carefully crafted judgement of the
|
|
selection and combining algorithms.
|
|
<H4>
|
|
Provisions for Leap Seconds and Accuracy Metrics</H4>
|
|
<TT>ntpd</TT> understands leap seconds and will attempt to take
|
|
appropriate
|
|
action when one occurs. In principle, every host running ntpd will
|
|
insert
|
|
a leap second in the local timescale in precise synchronization with
|
|
UTC.
|
|
This requires that the leap-warning bits be activated some time prior to
|
|
the occurrence of a leap second at the primary (stratum 1) servers.
|
|
Subsequently,
|
|
these bits are propagated throughout the subnet depending on these
|
|
servers
|
|
by the NTP protocol itself and automatically implemented by
|
|
<TT>ntpd</TT>
|
|
and the time- conversion routines of each host. The implementation is
|
|
independent
|
|
of the idiosyncrasies of the particular radio clock, which vary widely
|
|
among the various devices, as long as the idiosyncratic behavior does
|
|
not
|
|
last for more than about 20 minutes following the leap. Provisions are
|
|
included to modify the behavior in cases where this cannot be
|
|
guaranteed.
|
|
While provisions for leap seconds have been carefully crafted so that
|
|
correct
|
|
timekeeping immediately before, during and after the occurrence of a
|
|
leap
|
|
second is scrupulously correct, stock Unix systems are mostly inept in
|
|
responding to the available information. This caveat goes also for the
|
|
maximum-error and statistical-error bounds carefully calculated for all
|
|
clients and servers, which could be very useful for application programs
|
|
needing to calibrate the delays and offsets to achieve a near-
|
|
simultaneous
|
|
commit procedure, for example. While this information is maintained in
|
|
the <TT>ntpd</TT> data structures, there is at present no way for
|
|
application
|
|
programs to access it. This may be a topic for further development.
|
|
<H4>
|
|
Clock Support Overview</H4>
|
|
<TT>ntpd</TT> was designed to support radio (and other external) clocks
|
|
and does some parts of this function with utmost care. Clocks are
|
|
treated
|
|
by the protocol as ordinary NTP peers, even to the point of referring to
|
|
them with an (invalid) IP host address. Clock addresses are of the form
|
|
127.127.<I>t.u</I>, where <I>t</I> specifies the particular type of
|
|
clock
|
|
(i.e., refers to a particular clock driver) and <I>u</I> is a unit
|
|
number
|
|
whose interpretation is clock-driver dependent. This is analogous to the
|
|
use of major and minor device numbers by Unix and permits multiple
|
|
instantiations
|
|
of clocks of the same type on the same server, should such magnificent
|
|
redundancy be required.
|
|
|
|
<P>Because clocks look much like peers, both configuration file syntax
|
|
and run time reconfiguration commands can be used to control clocks in
|
|
the same way as ordinary peers. Clocks are configured via
|
|
<TT>server</TT>
|
|
declarations in the configuration file, can be started and stopped using
|
|
ntpdc and are subject to address-and-mask restrictions much like a
|
|
normal
|
|
peer, should this stretch of imagination ever be useful. As a concession
|
|
to the need to sometimes transmit additional information to clock
|
|
drivers,
|
|
an additional configuration file is available: the <TT>fudge</TT>
|
|
statement.
|
|
This enables one to specify the values of two time quantities, two
|
|
integral
|
|
values and two flags, the use of which is dependent on the particular
|
|
clock
|
|
driver. For example, to configure a PST radio clock which can be
|
|
accessed
|
|
through the serial device <TT>/dev/pst1</TT>, with propagation delays to
|
|
WWV and WWVH of 7.5 and 26.5 milliseconds, respectively, on a machine
|
|
with
|
|
an imprecise system clock and with the driver set to disbelieve the
|
|
radio
|
|
clock once it has gone 30 minutes without an update, one might use the
|
|
following configuration file entries:
|
|
<PRE> # radio clock fudge fiddles
|
|
server 127.127.3.1
|
|
fudge 127.127.3.1 time1 0.0075 time2 0.0265
|
|
fudge 127.127.3.1 value2 30 flag1 1</PRE>
|
|
Additional information on the interpretation of these data with respect
|
|
to various radio clock drivers is given in the <A
|
|
HREF="refclock.htm">Reference
|
|
Clock Drivers </A>document page and in the individual driver documents
|
|
accessible via that page.
|
|
<H4>
|
|
Towards the Ultimate Tick</H4>
|
|
This section considers issues in providing precision time
|
|
synchronization
|
|
in NTP subnets which need the highest quality time available in the
|
|
present
|
|
technology. These issues are important in subnets supporting real-time
|
|
services such as distributed multimedia conferencing and wide-area
|
|
experiment
|
|
control and monitoring.
|
|
|
|
<P>In the Internet of today synchronization paths often span continents
|
|
and oceans with moderate to high variations in delay due to traffic
|
|
spasms.
|
|
NTP is specifically designed to minimize timekeeping jitter due to delay
|
|
variations using intricately crafted filtering and selection algorithms;
|
|
however, in cases where these variations are as much as a second or
|
|
more,
|
|
the residual jitter following these algorithms may still be excessive.
|
|
Sometimes, as in the case of some isolated NTP subnets where a local
|
|
source
|
|
of precision time is available, such as a PPS signal produced by a
|
|
calibrated
|
|
cesium clock, it is possible to remove the jitter and retime the local
|
|
clock oscillator of the NTP server. This has turned out to be a useful
|
|
feature to improve the synchronization quality of time distributed in
|
|
remote
|
|
places where radio clocks are not available. In these cases special
|
|
features
|
|
of the distribution are used together with the PPS signal to provide a
|
|
jitter-free timing signal, while NTP itself is used to provide the
|
|
coarse
|
|
timing and resolve the seconds numbering.
|
|
|
|
<P>Most available radio clocks can provide time to an accuracy in the
|
|
order
|
|
of milliseconds, depending on propagation conditions, local noise levels
|
|
and so forth. However, as a practical matter, all clocks can
|
|
occasionally
|
|
display errors significantly exceeding nominal specifications. Usually,
|
|
the algorithms used by NTP for ordinary network peers, as well as radio
|
|
clock peers will detect and discard these errors as discrepancies
|
|
between
|
|
the disciplined local clock oscillator and the decoded time message
|
|
produced
|
|
by the radio clock. Some radio clocks can produce a special PPS signal
|
|
which can be interfaced to the server platform in a number of ways and
|
|
used to substantially improve the (disciplined) clock oscillator jitter
|
|
and wander characteristics by at least an order of magnitude. Using
|
|
these
|
|
features it is possible to achieve accuracies in the order of a few tens
|
|
of microseconds with a fast RISC- based platform.
|
|
|
|
<P>There are three ways to implement PPS support, depending on the radio
|
|
clock model, platform model and serial line interface. These are
|
|
described
|
|
in detail in the application notes mentioned in the <A
|
|
HREF="index.htm">The
|
|
Network Time Protocol (NTP) Distribution </A>document page. Each of
|
|
these
|
|
requires circuitry to convert the TTL signal produced by most clocks to
|
|
the EIA levels used by most serial interfaces. The <A
|
|
HREF="gadget.htm">Gadget
|
|
Box PPS Level Converter and CHU Modem </A>document page describes a
|
|
device
|
|
designed to do this. Besides being useful for this purpose, this device
|
|
includes an inexpensive modem designed for use with the Canadian CHU
|
|
time/frequency
|
|
radio station.
|
|
|
|
<P>In order to select the appropriate implementation, it is important to
|
|
understand the underlying PPS mechanism used by ntpd. The PPS support
|
|
depends
|
|
on a continuous source of PPS pulses used to calculate an offset within
|
|
+-500 milliseconds relative to the local clock. The serial timecode
|
|
produced
|
|
by the radio or the time determined by NTP in absence of the radio is
|
|
used
|
|
to adjust the local clock within +-128 milliseconds of the actual time.
|
|
As long as the local clock is within this interval the PPS support is
|
|
used
|
|
to discipline the local clock and the timecode used only to verify that
|
|
the local clock is in fact within the interval. Outside this interval
|
|
the
|
|
PPS support is disabled and the timecode used directly to control the
|
|
local
|
|
clock.
|
|
<H4>
|
|
Parting Shots</H4>
|
|
There are several undocumented programs which can be useful in unusual
|
|
cases. They can be found in the <TT>./clockstuff</TT> and
|
|
<TT>./authstuff</TT>
|
|
directories of the distribution. One of these is the <TT>propdelay</TT>
|
|
program, which can compute high frequency radio propagation delays
|
|
between
|
|
any two points whose latitude and longitude are known. The program
|
|
understands
|
|
something about the phenomena which allow high frequency radio
|
|
propagation
|
|
to occur, and will generally provide a better estimate than a
|
|
calculation
|
|
based on the great circle distance. Other programs of interest include
|
|
<TT>clktest</TT>, which allows one to exercise the generic clock line
|
|
discipline,
|
|
and <TT>chutest</TT>, which runs the basic reduction algorithms used by
|
|
the daemon on data received from a serial port.
|
|
|
|
<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
|
|
href=mailto:mills@udel.edu> David L. Mills <mills@udel.edu></a>
|
|
</address></a></body></html>
|