source: trunk/third/xntp/html/notes.htm @ 17260

Revision 17260, 68.7 KB checked in by zacheiss, 23 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r17259, which included commits to RCS files with non-trunk default branches.
Line 
1<HTML><HEAD><TITLE>
2Notes on Configuring NTP and Setting up a NTP Subnet</H3>
3</TITLE></HEAD><BODY><H3>
4Notes on Configuring NTP and Setting up a NTP Subnet</H3>
5</H3>
6
7<img align=left src=pic/tonea.gif>
8From NBS Special Publication 432 (out of print)
9<br clear=left>
10
11<H4>Introduction</H4>
12
13This document is a collection of notes concerning the use of ntpd and
14relatedprograms, and on coping with the Network Time Protocol (NTP) in
15general. It is a major rewrite and update of an earlier document written
16by Dennis Ferguson of the University of Toronto and includes many
17changes and additions resulting from the NTP Version 3 specification and
18new Version 4 implementation features. It supersedes earlier documents,
19which should no longer be used
20for new configurations.
21
22<P><TT>ntpd</TT> includes a complete implementation of the NTP Version
233 specification, as defined in:
24
25<ul>
26
27<p><li>Mills, D.L. Network Time Protocol (Version 3) specification,
28implementation and analysis. Network Working Group Report RFC-1305,
29University of Delaware, March 1992, 113 pp. Abstract: <a
30href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305a.ps>
31PostScript</a> | <a
32href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305a.pdf>
33PDF</a>, Body: <a
34href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.ps>
35PostScript</a> | <a
36href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305b.pdf>
37PDF</a>, Appendices: <a
38href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.ps>
39PostScript</a> | <a
40href=http://www.eecis.udel.edu/~mills/database/rfc/rfc1305/rfc1305c.pdf>
41PDF</a>
42
43</ul>
44Additional features have are described for <A HREF="release.htm">NTP
45Version 4</A>. It also retains compatibility with both NTP Version 2, as
46defined in RFC-1119, and NTP Version 1, as defined in RFC-1059, although
47this compatibility is sometimes strained and only semiautomatic. In
48order to support in principle the ultimate precision of about 232
49picoseconds in the NTP specification, <TT>ntpd</TT> uses NTP timestamp
50format for external communication and double precision floating point
51arithmetic internally. <TT>ntpd</TT> fully implements NTP Versions 2 and
523 authentication and in addition Version 4 autokey. It supports the NTP
53mode-6 control message facility along with a private mode-7 control-
54message facility used to remotely reconfigure the system and monitor a
55considerable amount of internal detail. As extensions to the
56specification, a flexible address-and-mask restriction facility has been
57included.
58
59<P>The code is biased towards the needs of a busy time server with
60numerous, often hundreds, of clients and other servers. Tables are
61hashed to allow efficient handling of many associations, though at the
62expense of additional overhead when the number of associations is small.
63Many fancy features have been included to permit efficient management
64and monitoring of a busy primary server, features which are probably
65excess baggage for a high stratum client. In such cases, a stripped-down
66version of the protocol, the Simple Network Time Protocol (SNTP) can be
67used. SNTP and NTP servers and clients can interwork in most situations,
68as described in: Mills, D.L. Simple Network Time Protocol (SNTP).
69Network Working Group Report RFC-2030, University of Delaware, October
701996, 14 pp. <A
71HREF="http://www.eecis.udel.edu/~mills/database/rfc2030.txt">
72(ASCII)</A>.
73
74<P>The code was written with near demonic attention to details which can
75affect precision and as a consequence should be able to make good use of
76high performance, special purpose hardware such as precision oscillators
77and radio clocks. The present code supports a number of radio clocks,
78including those for the WWV, CHU, WWVB, MSF, DCF77, GOES and GPS radio
79and satellite time services and USNO, ACTS and PTB modem time services.
80It also supports the IRIG-B and IRIG-E signal format connected via an
81audio codec. The server methodically avoids the use of Unix-specific
82library routines where possible by implementing local versions, in order
83to aid in porting the code to perverse Unix and non-Unix platforms.
84
85<P>While this implementation conforms in most respects to the NTP
86Version 3 specification RFC-1305, a number of improvements have been
87made which are described in the conformance statement in the <A
88HREF="biblio.htm">Further Information and Bibliography</A> page. It has
89been specifically tuned to achieve the highest accuracy possible on
90whatever hardware and operating-system platform is available. In
91general, its precision and stability are limited only by the
92characteristics of the onboard clock source used by the hardware
93and operating system, usually an uncompensated crystal oscillator. On
94modern RISC-based processors connected directly to radio clocks via
95serial-asynchronous interfaces, the accuracy is usually limited by the
96radio clock and interface to the order of a millisecond or less. The
97code includes special features to support a pulse-per-second (PPS)
98signal and/or an IRIG-B signal generated by some radio clocks. When used
99in conjunction with a suitable hardware level converter, the accuracy
100can be improved to a few tens of microseconds.
101Further improvement is possible using an outboard, stabilized frequency
102source, in which the accuracy and stability are limited only by the
103characteristics
104of that source.
105
106<P>The NTP Version 4 distribution includes, in addition to the daemon
107itself (<TT><A HREF="ntpd.htm">ntpd</A></TT>), several utility programs,
108including two remote-monitoring programs (<A HREF="ntpq.htm">
109<TT>ntpq</TT></A>, <TT><A HREF="ntpdc.htm">ntpdc</A></TT>), a remote
110clock-setting program similar to the Unix rdate program
111(<TT>ntpdate</TT>), a traceback utility u seful to discover suitable
112synchronization sources (<TT>ntptrace</TT>), and various programs used
113to configure the local platform and calibrate the intrinsic errors. NTP
114has been ported to a large number of platforms, including most RISC and
115CISC workstations and mainframes manufactured today. Example
116configuration files for many models of these machines are included
117in the distribution. While in most cases the standard version of the
118implementation runs with no hardware or operating system modifications,
119not all features of the distribution are available on all platforms. For
120instance, a special feature allowing Sun workstations to achieve
121accuracies in the order of 100 microseconds requires some minor changes
122and additions to the kernel and input/output support.
123
124<P>There are, however, several drawbacks to all of this. <TT>ntpd</TT>
125is quite fat. This is rotten if your intended platform for the daemon is
126memory limited. <TT>ntpd</TT> uses <TT>SIGIO</TT> for all input, a
127facility which appears to not enjoy universal support and whose use
128seems to exercise the parts of your vendors' kernels which are most
129likely to have been done poorly. The code is unforgiving in the face of
130kernel problems which affect performance, and generally requires that
131you repair the problems in order to achieve acceptable performance. The
132code has a distinctly experimental flavour and contains features which
133could charitably be termed failed
134experiments, but which have not been completely hacked out. Much was
135learned from the  addition of support for a variety of radio clocks,
136with the result that some radio clock drivers could use some rewriting.
137
138<H4>How NTP Works</H4>
139
140The approach used by NTP to achieve reliable time synchronization from
141a set of possibly unreliable remote time servers is somewhat different
142than other protocols. In particular, NTP does not attempt to synchronize
143clocks to each other. Rather, each server attempts to synchronize to
144Universal
145Coordinated Time (UTC) using the best available source and available
146transmission
147paths to that source. This is a fine point which is worth understanding.
148A group of NTP-synchronized clocks may be close to each other in time,
149but this is not a consequence of the clocks in the group having
150synchronized
151to each other, but rather because each clock has synchronized closely to
152UTC via the best source it has access to. As such, trying to synchronize
153a set of clocks to a set of servers whose time is not in mutual
154agreement
155may not result in any sort of useful synchronization of the clocks, even
156if you don't care about UTC. However, in networks isolated from UTC
157sources,
158provisions can made to nominate one of them as a phantom UTC source.
159
160<P>NTP operates on the premise that there is one true standard time, and
161that if several servers which claim synchronization to standard time
162disagree
163about what that time is, then one or more of them must be broken. There
164is no attempt to resolve differences more gracefully since the premise
165is that substantial differences cannot exist. In essence, NTP expects
166that
167the time being distributed from the root of the synchronization subnet
168will be derived from some external source of UTC (e.g., a radio clock).
169This makes it somewhat inconvenient (though by no means impossible) to
170synchronize hosts together without a reliable source of UTC to
171synchronize
172them to. If your network is isolated and you cannot access other
173people's
174servers across the Internet, a radio clock may make a good investment.
175
176<P>Time is distributed through a hierarchy of NTP servers, with each
177server
178adopting a <I>stratum</I> which indicates how far away from an external
179source of UTC it is operating at. Stratum-1 servers, which are at the
180top
181of the pile (or bottom, depending on your point of view), have access to
182some external time source, usually a radio clock synchronized to time
183signal
184broadcasts from radio stations which explicitly provide a standard time
185service. A stratum-2 server is one which is currently obtaining time
186from
187a stratum-1 server, a stratum-3 server gets its time from a stratum-2
188server,
189and so on. To avoid long lived synchronization loops the number of
190strata
191is limited to 15.
192
193<P>Each client in the synchronization subnet (which may also be a server
194for other, higher stratum clients) chooses exactly one of the available
195servers to synchronize to, usually from among the lowest stratum servers
196it has access to. This is, however, not always an optimal configuration,
197for indeed NTP operates under another premise as well, that each
198server's
199time should be viewed with a certain amount of distrust. NTP really
200prefers
201to have access to several sources of lower stratum time (at least three)
202since it can then apply an agreement algorithm to detect insanity on the
203part of any one of these. Normally, when all servers are in agreement,
204NTP will choose the best of these, where "best" is defined in terms of
205lowest stratum, closest (in terms of network delay) and claimed
206precision,
207along with several other considerations. The implication is that, while
208one should aim to provide each client with three or more sources of
209lower
210stratum time, several of these will only be providing backup service and
211may be of lesser quality in terms of network delay and stratum (i.e., a
212same-stratum peer which receives time from lower stratum sources the
213local
214server doesn't access directly can also provide good backup service).
215
216<P>Finally, there is the issue of association modes. There are a number
217of modes in which NTP servers can associate with each other, with the
218mode
219of each server in the pair indicating the behaviour the other server can
220expect from it. In particular, when configuring a server to obtain time
221from other servers, there is a choice of two modes which may be used.
222Configuring
223an association in symmetric-active mode (usually indicated by a
224<TT>peer</TT>
225declaration in the configuration file) indicates to the remote server
226that
227one wishes to obtain time from the remote server and that one is also
228willing
229to supply time to the remote server if need be. This mode is appropriate
230in configurations involving a number of redundant time servers
231interconnected
232via diverse network paths, which is presently the case for most stratum-
2331
234and stratum-2 servers on the Internet today. Configuring an association
235in client mode (usually indicated by a <TT>server</TT> declaration in
236the
237configuration file) indicates that one wishes to obtain time from the
238remote
239server, but that one is not willing to provide time to the remote
240server.
241This mode is appropriate for file-server and workstation clients that do
242not provide synchronization to other local clients. Client mode is also
243useful for boot-date-setting programs and the like, which really have no
244time to provide and which don't retain state about associations over the
245longer term.
246
247<P>Where the requirements in accuracy and reliability are modest,
248clients
249can be configured to use broadcast and/or multicast modes. These modes
250are not normally utilized by servers with dependent clients. The
251advantage
252of these modes is that clients do not need to be configured for a
253specific
254server, so that all clients operating can use the same configuration
255file.
256Broadcast mode requires a broadcast server on the same subnet, while
257multicast
258mode requires support for IP multicast on the client machine, as well as
259connectivity via the MBONE to a multicast server. Since broadcast
260messages
261are not propagated by routers, only those broadcast servers on the same
262subnet will be used. There is at present no way to select which of
263possibly
264many multicast servers will be used, since all operate on the same group
265address.
266
267<P>Where the maximum accuracy and reliability provided by NTP are
268needed,
269clients and servers operate in either client/server or symmetric modes.
270Symmetric modes are most often used between two or more servers
271operating
272as a mutually redundant group. In these modes, the servers in the group
273members arrange the synchronization paths for maximum performance,
274depending
275on network jitter and propagation delay. If one or more of the group
276members
277fail, the remaining members automatically reconfigure as required.
278Dependent
279clients and servers normally operate in client/server mode, in which a
280client or dependent server can be synchronized to a group member, but no
281group member can synchronize to the client or dependent server. This
282provides
283protection against malfunctions or protocol attacks.
284
285<P>Servers that provide synchronization to a sizeable population of
286clients
287normally operate as a group of three or more mutually redundant servers,
288each operating with three or more stratum-one or stratum-two servers in
289client-server modes, as well as all other members of the group in
290symmetric
291modes. This provides protection against malfunctions in which one or
292more
293servers fail to operate or provide incorrect time. The NTP algorithms
294have
295been specifically engineered to resist attacks where some fraction of
296the
297configured synchronization sources accidently or purposely provide
298incorrect
299time. In these cases a special voting procedure is used to identify
300spurious
301sources and discard their data.
302<H4>
303Configuring Your Subnet</H4>
304At startup time the <TT>ntpd</TT> daemon running on a host reads the
305initial
306configuration information from a file, usually <TT>/etc/ntp.conf</TT>,
307unless a different name has been specified at compile time. Putting
308something
309in this file which will enable the host to obtain time from somewhere
310else
311is usually the first big hurdle after installation of the software
312itself,
313which is described in the <A HREF="build.htm">Building and Installing
314the
315Distribution</A> page. At its simplest, what you need to do in the
316configuration
317file is declare the servers that the daemon should poll for time
318synchronization.
319In principle, no such list is needed if some other time server operating
320in broadcast/multicast mode is available, which requires the client to
321operate in a broadcastclient mode.
322
323<P>In the case of a workstation operating in an enterprise network for
324a public or private organization, there is often an administrative
325department
326that coordinates network services, including NTP. Where available, the
327addresses of appropriate servers can be provided by that department.
328However,
329if this infrastructure is not available, it is necessary to explore some
330portion of the existing NTP subnet now running in the Internet. There
331are
332at present many thousands of time servers running NTP in the Internet,
333a significant number of which are willing to provide a public time-
334synchronization
335service. Some of these are listed in the list of public time servers,
336which
337can be accessed via the <A HREF="http://www.eecis.udel.edu/~ntp">NTP web
338page</A>. These data are updated on a regular basis using information
339provided
340voluntarily by various site administrators. There are other ways to
341explore
342the nearby subnet using the <TT><A HREF="ntptrace.htm">ntptrace</A></TT>
343and <TT><A HREF="ntpdc.htm">ntpdc</A></TT> programs.
344
345<P>It is vital to carefully consider the issues of robustness and
346reliability
347when selecting the sources of synchronization. Normally, not less than
348three sources should be available, preferably selected to avoid common
349points of failure. It is usually better to choose sources which are
350likely
351to be "close" to you in terms of network topology, though you shouldn't
352worry overly about this if you are unable to determine who is close and
353who isn't. Normally, it is much more serious when a server becomes
354faulty
355and delivers incorrect time than when it simply stops operating, since
356an NTP-synchronized host normally can coast for hours or even days
357without
358its clock accumulating serious error approaching a second, for instance.
359Selecting at least three sources from different operating
360administrations,
361where possible, is the minimum recommended, although a lesser number
362could
363provide acceptable service with a degraded degree of robustness.
364
365<P>Normally, it is not considered good practice for a single workstation
366to request synchronization from a primary (stratum-1) time server. At
367present,
368these servers provide synchronization for hundreds of clients in many
369cases
370and could, along with the network access paths, become seriously
371overloaded
372if large numbers of workstation clients requested synchronization
373directly.
374Therefore, workstations located in sparsely populated administrative
375domains
376with no local synchronization infrastructure should request
377synchronization
378from nearby stratum-2 servers instead. In most cases the keepers of
379those
380servers in the lists of public servers provide unrestricted access
381without
382prior permission; however, in all cases it is considered polite to
383notify
384the administrator listed in the file upon commencement of regular
385service.
386In all cases the access mode and notification requirements listed in the
387file must be respected. Under no conditions should servers not in these
388lists be used without prior permission, as to do so can create severe
389problems
390in the local infrastructure, especially in cases of dial-up access to
391the
392Internet.
393
394<P>In the case of a gateway or file server providing service to a
395significant
396number of workstations or file servers in an enterprise network it is
397even
398more important to provide multiple, redundant sources of synchronization
399and multiple, diversity-routed, network access paths. The preferred
400configuration
401is at least three administratively coordinated time servers providing
402service
403throughout the administrative domain including campus networks and
404subnetworks.
405Each of these should obtain service from at least two different outside
406sources of synchronization, preferably via different gateways and access
407paths. These sources should all operate at the same stratum level, which
408is one less than the stratum level to be used by the local time servers
409themselves. In addition, each of these time servers should peer with all
410of the other time servers in the local administrative domain at the
411stratum
412level used by the local time servers, as well as at least one
413(different)
414outside source at this level. This configuration results in the use of
415six outside sources at a lower stratum level (toward the primary source
416of synchronization, usually a radio clock), plus three outside sources
417at the same stratum level, for a total of nine outside sources of
418synchronization.
419While this may seem excessive, the actual load on network resources is
420minimal, since the interval between polling messages exchanged between
421peers usually ratchets back to no more than one message every 17
422minutes.
423
424<P>The stratum level to be used by the local time servers is an
425engineering
426choice. As a matter of policy, and in order to reduce the load on the
427primary
428servers, it is desirable to use the highest stratum consistent with
429reliable,
430accurate time synchronization throughout the administrative domain. In
431the case of enterprise networks serving hundreds or thousands of client
432file servers and workstations, conventional practice is to obtain
433service
434from stratum-1 primary servers listed for public access. When choosing
435sources away from the primary sources, the particular synchronization
436path
437in use at any time can be verified using the <TT>ntptrace</TT> program
438included in this distribution. It is important to avoid loops and
439possible
440common points of failure when selecting these sources. Note that, while
441NTP detects and rejects loops involving neighboring servers, it does not
442detect loops involving intervening servers. In the unlikely case that
443all
444primary sources of synchronization are lost throughout the subnet, the
445remaining servers on that subnet can form temporary loops and, if the
446loss
447continues for an interval of many hours, the servers will drop off the
448subnet and free-run with respect to their internal (disciplined) timing
449sources. After some period with no outside timing source (currently one
450day), a host will declare itself unsynchronized and provide this
451information
452to local application programs.
453
454<P>In many cases the purchase of one or more radio clocks is justified,
455in which cases good engineering practice is to use the configurations
456described
457above anyway and connect the radio clock to one of the local servers.
458This
459server is then encouraged to participate in a special primary-server
460subnetwork
461in which each radio-equipped server peers with several other similarly
462equipped servers. In this way the radio-equipped server may provide
463synchronization,
464as well as receive synchronization, should the local or remote radio
465clock(s)
466fail or become faulty. <TT>ntpd</TT> treats attached radio clock(s) in
467the same way as other servers and applies the same criteria and
468algorithms
469to the time indications, so can detect when the radio fails or becomes
470faulty and switch to alternate sources of synchronization. It is
471strongly
472advised, and in practice for most primary servers today, to employ the
473authentication or access-control features of the NTP specification in
474order
475to protect against hostile intruders and possible destabilization of the
476time service. Using this or similar strategies, the remaining hosts in
477the same administrative domain can be synchronized to the three (or
478more)
479selected time servers. Assuming these servers are synchronized directly
480to stratum-1 sources and operate normally as stratum-2, the next level
481away from the primary source of synchronization, for instance various
482campus
483file servers, will operate at stratum 3 and dependent workstations at
484stratum
4854. Engineered correctly, such a subnet will survive all but the most
486exotic
487failures or even hostile penetrations of the various, distributed
488timekeeping
489resources.
490<P>The above arrangement should provide very good, robust time service
491with a minimum of traffic to distant servers and with manageable loads
492on the local servers. While it is theoretically possible to extend the
493synchronization subnet to even higher strata, this is seldom justified
494and can make the maintenance of configuration files unmanageable.
495Serving
496time to a higher stratum peer is very inexpensive in terms of the load
497on the lower stratum server if the latter is located on the same
498concatenated
499LAN. When justified by the accuracy expectations, NTP can be operated in
500broadcast and multicast modes, so that clients need only listen for
501periodic
502broadcasts and do not need to send anything.
503
504<P>When planning your network you might, beyond this, keep in mind a few
505generic don'ts, in particular:
506<UL>
507<LI>
508Don't synchronize a local time server to another peer at the same
509stratum,
510unless the latter is receiving time from lower stratum sources the
511former
512doesn't talk to directly. This minimizes the occurrence of common points
513of failure, but does not eliminate them in cases where the usual chain
514of associations to the primary sources of synchronization are disrupted
515due to failures.</LI>
516
517<BR>&nbsp;
518<LI>
519Don't configure peer associations with higher stratum servers. Let the
520higher strata configure lower stratum servers, but not the reverse. This
521greatly simplifies configuration file maintenance, since there is
522usually
523much greater configuration churn in the high stratum clients such as
524personal
525workstations.</LI>
526<BR>&nbsp;
527<LI>
528Don't synchronize more than one time server in a particular
529administrative
530domain to the same time server outside that domain. Such a practice
531invites
532common points of failure, as well as raises the possibility of massive
533abuse, should the configuration file be automatically distributed do a
534large number of clients.</LI>
535</UL>
536There are many useful exceptions to these rules. When in doubt, however,
537follow them.
538<H4>
539Configuring Your Server or Client</H4>
540As mentioned previously, the configuration file is usually called
541/etc/ntp.conf.
542This is an ASCII file conforming to the usual comment and whitespace
543conventions.
544A working configuration file might look like (in this and other
545examples,
546do not copy this directly):
547<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # peer configuration for host whimsy
548&nbsp;&nbsp;&nbsp;&nbsp; # (expected to operate at stratum 2)
549
550&nbsp;&nbsp;&nbsp;&nbsp; server rackety.udel.edu
551&nbsp;&nbsp;&nbsp;&nbsp; server umd1.umd.edu
552&nbsp;&nbsp;&nbsp;&nbsp; server lilben.tn.cornell.edu
553
554&nbsp;&nbsp;&nbsp;&nbsp; driftfile /etc/ntp.drift</PRE>
555(Note the use of host names, although host addresses in dotted-quad
556notation
557can also be used. It is always preferable to use names rather than
558addresses,
559since over time the addresses can change, while the names seldom
560change.)
561
562<P>This particular host is expected to operate as a client at stratum 2
563by virtue of the <TT>server</TT> keyword and the fact that two of the
564three
565servers declared (the first two) have radio clocks and usually run at
566stratum
5671. The third server in the list has no radio clock, but is known to
568maintain
569associations with a number of stratum 1 peers and usually operates at
570stratum
5712. Of particular importance with the last host is that it maintains
572associations
573with peers besides the two stratum 1 peers mentioned. This can be
574verified
575using the <TT>ntpq</TT> program mentioned above. When configured using
576the <TT>server</TT> keyword, this host can receive synchronization from
577any of the listed servers, but can never provide synchronization to
578them.
579
580<P>Unless restricted using facilities described later, this host can
581provide
582synchronization to dependent clients, which do not have to be listed in
583the configuration file. Associations maintained for these clients are
584transitory
585and result in no persistent state in the host. These clients are
586normally
587not visible using the <TT>ntpq</TT> program included in the
588distribution;
589however, <TT>ntpd</TT> includes a monitoring feature (described later)
590which caches a minimal amount of client information useful for debugging
591administrative purposes.
592
593<P>A time server expected to both receive synchronization from another
594server, as well as to provide synchronization to it, is declared using
595the <TT>peer</TT> keyword instead of the <TT>server</TT> keyword. In all
596other aspects the server operates the same in either mode and can
597provide
598synchronization to dependent clients or other peers. If a local source
599of UTC time is available, it is considered good engineering practice to
600declare time servers outside the administrative domain as <TT>peer</TT>
601and those inside as <TT>server</TT> in order to provide redundancy in
602the
603global Internet, while minimizing the possibility of instability within
604the domain itself. A time server in one domain can in principle heal
605another
606domain temporarily isolated from all other sources of synchronization.
607However, it is probably unwise for a casual workstation to bridge
608fragments
609of the local domain which have become temporarily isolated.
610
611<P>Note the inclusion of a <TT>driftfile</TT> declaration. One of the
612things
613the NTP daemon does when it is first started is to compute the error in
614the intrinsic frequency of the clock on the computer it is running on.
615It usually takes about a day or so after the daemon is started to
616compute
617a good estimate of this (and it needs a good estimate to synchronize
618closely
619to its server). Once the initial value is computed, it will change only
620by relatively small amounts during the course of continued operation.
621The
622<TT>driftfile</TT> declaration indicates to the daemon the name of a
623file
624where it may store the current value of the frequency error so that, if
625the daemon is stopped and restarted, it can reinitialize itself to the
626previous estimate and avoid the day's worth of time it will take to
627recompute
628the frequency estimate. Since this is a desirable feature, a
629<TT>driftfile</TT>
630declaration should always be included in the configuration file.
631
632<P>An implication in the above is that, should <TT>ntpd</TT> be stopped
633for some reason, the local platform time will diverge from UTC by an
634amount
635that depends on the intrinsic error of the clock oscillator and the time
636since last synchronized. In view of the length of time necessary to
637refine
638the frequency estimate, every effort should be made to operate the
639daemon
640on a continuous basis and minimize the intervals when for some reason it
641is not running.
642
643<H4>
644Configuring NTP with NetInfo</H4>
645If NetInfo support is compiled into NTP, you can opt to configure ntp
646in your NetInfo domain. NTP will look int he NetInfo directory
647<TT>/locations/ntp</TT> for property/value pairs which are equivalent
648the the lines in the configuration file described above. Each
649configuration keyword may have a coresponding property in NetInfo.
650Each value for a given property is treated as arguments to that property,
651similar to a line in the configuration file.
652
653<P>For example, the configuration shown in the configuration file above
654can be duplicated in NetInfo by adding a property "<TT>server</TT>" with
655values "<TT>rackety.udel.edu</TT>", "<TT>umd1.umd.edu</TT>", and
656"<TT>lilben.tn.cornell.edu</TT>"; and a property "<TT>driftfile</TT>"
657with the single value "<TT>/etc/ntp.drift</TT>".
658
659<P>Values may contain multiple tokens similar to the arguments available
660in the configuration file. For example, to use <TT>mimsy.mil</TT> as an
661NTP version 1 time server, you would add a value "<TT>mimsy.mil version
6621</TT>" to the "<TT>server</TT>" property.
663
664<H4>
665Ntp4 Versus Previous Versions</H4>
666There are several items of note when dealing with a mixture of
667<TT>ntp4</TT>
668and previous distributions of NTP Version 2 (<TT>ntpd</TT>) and NTP
669Version
6701 (<TT>ntp3.4</TT>). The <TT>ntp4</TT> implementation conforms to the
671NTP
672Version 3 specification RFC-1305 and, in addition, contains additional
673feaures documented in the <A HREF="release.htm">Release Notes</A> page.
674As such, by default when no additional information is available
675concerning
676the preferences of the peer, <TT>ntpd</TT> claims to be version 4 in the
677packets that it sends from configured associations. The <TT>version
678</TT>subcommand
679of the <TT>server</TT>, <TT>peer</TT>, <TT>broadcast </TT>and
680<TT>manycastclient
681</TT>command can be used to change the default. In unconfigured
682(ephemeral)
683associaitons, the daemon always replies in the same version as the
684request.
685
686<P>An NTP implementation conforming to a previous version specification
687ordinarily discards packets from a later version. However, in most
688respects
689documented in RFC-1305, The version 2 implementation is compatible with
690the version 3 algorithms and protocol. The version 1 implementation
691contains
692most of the version 2 algorithms, but without important features for
693clock
694selection and robustness. Nevertheless, in most respects the NTP
695versions
696are backwards compatible. The sticky part here is that, when a previous
697version implementation receives a packet claiming to be from a version
6984 server, it discards it without further processing. Hence there is a
699danger
700that in some situations synchronization with previous versions will
701fail.
702
703<P>The trouble occurs when an previous version is to be included in an
704<TT>ntpd</TT> configuration file. With no further indication,
705<TT>ntpd</TT>
706will send packets claiming to be version 4 when it polls. To get around
707this, <TT>ntpd</TT> allows a qualifier to be added to configuration
708entries
709to indicate which version to use when polling. Hence the entries
710<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # specify NTP version 1
711
712&nbsp;&nbsp;&nbsp;&nbsp; server mimsy.mil version
7131&nbsp;&nbsp;&nbsp;&nbsp; # server running ntpd version 1
714&nbsp;&nbsp;&nbsp;&nbsp; server apple.com version
7152&nbsp;&nbsp;&nbsp;&nbsp; # server running ntpd version 2</PRE>
716will cause version 1 packets to be sent to the host mimsy.mil and
717version
7182 packets to be sent to apple.com. If you are testing <TT>ntpd</TT>
719against
720previous version servers you will need to be careful about this. Note
721that,
722as indicated in the RFC-1305 specification, there is no longer support
723for the original NTP specification, once called NTP Version 0.
724<H4>
725Traffic Monitoring</H4>
726<TT>ntpd</TT> handles peers whose stratum is higher than the stratum of
727the local server and polls using client mode by a fast path which
728minimizes
729the work done in responding to their polls, and normally retains no
730memory
731of these pollers. Sometimes, however, it is interesting to be able to
732determine
733who is polling the server, and how often, as well as who has been
734sending
735other types of queries to the server.
736
737<P>To allow this, <TT>ntpd</TT> implements a traffic monitoring facility
738which records the source address and a minimal amount of other
739information
740from each packet which is received by the server. This feature is
741normally
742enabled, but can be disabled if desired using the configuration file
743entry:
744<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # disable monitoring feature
745&nbsp;&nbsp;&nbsp;&nbsp; disable monitor</PRE>
746The recorded information can be displayed using the <TT>ntpdc</TT> query
747program, described briefly below.
748<H4>
749Address-and-Mask Restrictions</H4>
750The address-and-mask configuration facility supported by <TT>ntpd</TT>
751is quite flexible and general, but is not an integral part of the NTP
752Version
7533 specification. The major drawback is that, while the internal
754implementation
755is very nice, the user interface is not. For this reason it is probably
756worth doing an example here. Briefly, the facility works as follows.
757There
758is an internal list, each entry of which holds an address, a mask and a
759set of flags. On receipt of a packet, the source address of the packet
760is compared to each entry in the list, with a match being posted when
761the
762following is true:
763<PRE>&nbsp;&nbsp;&nbsp;&nbsp; (source_addr &amp; mask) == (address &amp;
764mask)</PRE>
765A particular source address may match several list entries. In this case
766the entry with the most one bits in the mask is chosen. The flags
767associated
768with this entry are used to control the access.
769
770<P>In the current implementation the flags always add restrictions. In
771effect, an entry with no flags set leaves matching hosts unrestricted.
772An entry can be added to the internal list using a <TT>restrict</TT>
773declaration.
774The flags associated with the entry are specified textually. For
775example,
776the <TT>notrust</TT> flag indicates that hosts matching this entry,
777while
778treated normally in other respects, shouldn't be trusted to provide
779synchronization
780even if otherwise so enabled. The <TT>nomodify</TT> flag indicates that
781hosts matching this entry should not be allowed to do run-time
782configuration.
783There are many more flags, see the <A HREF="ntpd.htm"><TT>ntpd</TT>
784</A>page.
785
786<P>Now the example. Suppose you are running the server on a host whose
787address is 128.100.100.7. You would like to ensure that run time
788reconfiguration
789requests can only be made from the local host and that the server only
790ever synchronizes to one of a pair of off-campus servers or, failing
791that,
792a time source on net 128.100. The following entries in the configuration
793file would implement this policy:
794<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # by default, don't trust and don't allow
795modifications
796
797&nbsp;&nbsp;&nbsp;&nbsp; restrict default notrust nomodify
798
799&nbsp;&nbsp;&nbsp;&nbsp; # these guys are trusted for time, but no
800modifications allowed
801
802&nbsp;&nbsp;&nbsp;&nbsp; restrict 128.100.0.0 mask 255.255.0.0 nomodify
803&nbsp;&nbsp;&nbsp;&nbsp; restrict 128.8.10.1 nomodify
804&nbsp;&nbsp;&nbsp;&nbsp; restrict 192.35.82.50 nomodify
805
806&nbsp;&nbsp;&nbsp;&nbsp; # the local addresses are unrestricted
807
808&nbsp;&nbsp;&nbsp;&nbsp; restrict 128.100.100.7
809&nbsp;&nbsp;&nbsp;&nbsp; restrict 127.0.0.1</PRE>
810The first entry is the default entry, which all hosts match and hence
811which
812provides the default set of flags. The next three entries indicate that
813matching hosts will only have the <TT>nomodify</TT> flag set and hence
814will be trusted for time. If the mask isn't specified in the
815<TT>restrict</TT>
816keyword, it defaults to 255.255.255.255. Note that the address
817128.100.100.7
818matches three entries in the table, the default entry (mask 0.0.0.0),
819the
820entry for net 128.100 (mask 255.255.0.0) and the entry for the host
821itself
822(mask 255.255.255.255). As expected, the flags for the host are derived
823from the last entry since the mask has the most bits set.
824
825<P>The only other thing worth mentioning is that the <TT>restrict</TT>
826declarations apply to packets from all hosts, including those that are
827configured elsewhere in the configuration file and even including your
828clock pseudopeer(s), if any. Hence, if you specify a default set of
829restrictions
830which you don't wish to be applied to your configured peers, you must
831remove
832those restrictions for the configured peers with additional
833<TT>restrict</TT>
834declarations mentioning each peer separately.
835<H4>
836Authentication</H4>
837<TT>ntpd</TT> supports the optional authentication procedure specified
838in the NTP Version 2 and 3 specifications. Briefly, when an association
839runs in authenticated mode, each packet transmitted has appended to it
840a 32-bit key ID and a 64/128-bit cryptographic checksum of the packet
841contents
842computed using either the Data Encryption Standard (DES) or Message
843Digest
844(MD5) algorithms. Note that, while either of these algorithms provide
845sufficient
846protection from message- modification attacks, distribution of the
847former
848algorithm implementation is restricted to the U.S. and Canada, while the
849latter presently is free from such restrictions. For this reason, the
850DES
851algorithm is not included in the current distribution. Directions for
852obtaining
853it in other countries is in the <A HREF="build.htm">Building and
854Installing
855the Distribution</A> page. With either algorithm the receiving peer
856recomputes
857the checksum and compares it with the one included in the packet. For
858this
859to work, the peers must share at least one encryption key and,
860furthermore,
861must associate the shared key with the same key ID.
862
863<P>This facility requires some minor modifications to the basic packet
864processing procedures, as required by the specification. These
865modifications
866are enabled by the <TT>enable auth</TT> configuration declaration, which
867is currently the default. In authenticated mode, peers which send
868unauthenticated
869packets, peers which send authenticated packets which the local server
870is unable to decrypt and peers which send authenticated packets
871encrypted
872using a key we don't trust are all marked untrustworthy and unsuitable
873for synchronization. Note that, while the server may know many keys
874(identified
875by many key IDs), it is possible to declare only a subset of these as
876trusted.
877This allows the server to share keys with a client which requires
878authenticated
879time and which trusts the server, but which is not trusted by the
880server.
881Also, some additional configuration language is required to specify the
882key ID to be used to authenticate each configured peer association.
883Hence,
884for a server running in authenticated mode, the configuration file might
885look similar to the following:
886<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # peer configuration for 128.100.100.7
887&nbsp;&nbsp;&nbsp;&nbsp; # (expected to operate at stratum 2)
888&nbsp;&nbsp;&nbsp;&nbsp; # fully authenticated this time
889
890&nbsp;&nbsp;&nbsp;&nbsp; peer 128.100.49.105 key 22 #
891suzuki.ccie.utoronto.ca
892&nbsp;&nbsp;&nbsp;&nbsp; peer 128.8.10.1 key 4&nbsp;&nbsp;&nbsp; #
893umd1.umd.edu
894&nbsp;&nbsp;&nbsp;&nbsp; peer 192.35.82.50 key 6&nbsp; #
895lilben.tn.cornell.edu
896
897&nbsp;&nbsp;&nbsp;&nbsp; keys /usr/local/etc/ntp.keys&nbsp; # path for
898key file
899&nbsp;&nbsp;&nbsp;&nbsp; trustedkey 1 2 14 15&nbsp;&nbsp;&nbsp;&nbsp; #
900define trusted keys
901&nbsp;&nbsp;&nbsp;&nbsp; requestkey
90215&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; #
903key (7) for accessing server variables
904&nbsp;&nbsp;&nbsp;&nbsp; controlkey
90515&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; #
906key (6) for accessing server variables
907
908&nbsp;&nbsp;&nbsp;&nbsp; authdelay
9090.000094&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; # authentication delay
910(Sun4c/50 IPX)</PRE>
911There are a couple of previously unmentioned things in here. The
912<TT>keys
913</TT>line specifies the path to the keys file (see below and the
914<TT>ntpd</TT>
915document page for details of the file format). The <TT>trustedkey</TT>
916declaration identifies those keys that are known to be uncompromised;
917the
918remainder presumably represent the expired or possibly compromised keys.
919Both sets of keys must be declared by key identifier in the
920<TT>ntp.keys</TT>
921file described below. This provides a way to retire old keys while
922minimizing
923the frequency of delicate key-distribution procedures. The
924<TT>requestkey</TT>
925line establishes the key to be used for mode-6 control messages as
926specified
927in RFC-1305 and used by the <TT>ntpq</TT> utility program, while the
928<TT>controlkey
929</TT>line establishes the key to be used for mode-7 private control
930messages
931used by the <TT>ntpdc</TT> utility program. These keys are used to
932prevent
933unauthorized modification of daemon variables.
934
935<P>Ordinarily, the authentication delay; that is, the processing time
936taken
937between the freezing of a transmit timestamp and the actual transmission
938of the packet when authentication is enabled (i.e. more or less the time
939it takes for the DES or MD5 routine to encrypt a single block) is
940computed
941automatically by the daemon. If necessary, the delay can be overriden by
942the <TT>authdelay </TT>line, which is used as a correction for the
943transmit
944timestamp. This can be computed for your CPU by the <A
945HREF="authspeed.htm"><TT>authspeed</TT>
946</A>program included in the distribution. The usage is illustrated by
947the
948following:
949<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # for DES keys
950
951&nbsp;&nbsp;&nbsp;&nbsp; authspeed -n 30000 auth.samplekeys
952&nbsp;&nbsp;&nbsp;&nbsp; # for MD5 keys
953
954&nbsp;&nbsp;&nbsp;&nbsp; authspeed -mn 30000 auth.samplekeys</PRE>
955Additional utility programs included in the <TT>./authstuff</TT>
956directory
957can be used to generate random keys, certify implementation correctness
958and display sample keys. As a general rule, keys should be chosen
959randomly,
960except possibly the request and control keys, which must be entered by
961the user as a password.
962
963<P>The <TT>ntp.keys</TT> file contains the list of keys and associated
964key IDs the server knows about (for obvious reasons this file is better
965left unreadable by anyone except root). The contents of this file might
966look like:
967<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # ntp keys file (ntp.keys)
968&nbsp;&nbsp;&nbsp;&nbsp; 1&nbsp;&nbsp;&nbsp; N&nbsp;&nbsp;&nbsp;
96929233E0461ECD6AE&nbsp;&nbsp;&nbsp; # des key in NTP format
970&nbsp;&nbsp;&nbsp;&nbsp; 2&nbsp;&nbsp;&nbsp; M&nbsp;&nbsp;&nbsp;
971RIrop8KPPvQvYotM&nbsp;&nbsp;&nbsp; # md5 key as an ASCII random string
972&nbsp;&nbsp;&nbsp;&nbsp; 14&nbsp;&nbsp; M&nbsp;&nbsp;&nbsp;
973sundial&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp
974;&nbsp; # md5 key as an ASCII string
975&nbsp;&nbsp;&nbsp;&nbsp; 15&nbsp;&nbsp; A&nbsp;&nbsp;&nbsp;
976sundial&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp
977;&nbsp; # des key as an ASCII string
978
979&nbsp;&nbsp;&nbsp;&nbsp; # the following 3 keys are identical
980
981&nbsp;&nbsp;&nbsp;&nbsp; 10&nbsp;&nbsp; A&nbsp;&nbsp;&nbsp; SeCReT
982&nbsp;&nbsp;&nbsp;&nbsp; 10&nbsp;&nbsp; N&nbsp;&nbsp;&nbsp;
983d3e54352e5548080
984&nbsp;&nbsp;&nbsp;&nbsp; 10&nbsp;&nbsp; S&nbsp;&nbsp;&nbsp;
985a7cb86a4cba80101</PRE>
986In the keys file the first token on each line indicates the key ID, the
987second token the format of the key and the third the key itself. There
988are four key formats. An <TT>A</TT> indicates a DES key written as a 1-
989to-8
990character string in 7-bit ASCII representation, with each character
991standing
992for a key octet (like a Unix password). An <TT>S</TT> indicates a DES
993key
994written as a hex number in the DES standard format, with the low order
995bit (LSB) of each octet being the (odd) parity bit. An <TT>N</TT>
996indicates
997a DES key again written as a hex number, but in NTP standard format with
998the high order bit of each octet being the (odd) parity bit (confusing
999enough?). An <TT>M</TT> indicates an MD5 key written as a 1-to-31
1000character
1001ASCII string in the <TT>A</TT> format. Note that, because of the simple
1002tokenizing routine, the characters <TT>' ', '#', '\t', '\n'</TT> and
1003<TT>'\0'</TT>
1004can't be used in either a DES or MD5 ASCII key. Everything else is fair
1005game, though. Key 0 (zero) is used for special purposes and should not
1006appear in this file.
1007
1008<P>The big trouble with the authentication facility is the keys file. It
1009is a maintenance headache and a security problem. This should be fixed
1010some day. Presumably, this whole bag of worms goes away if/when a
1011generic
1012security regime for the Internet is established. An alternative with NTP
1013Version 4 is the autokey feature, which uses random session keys and
1014public-key
1015cruptography and avoids the key file entirely. While this feature is not
1016completely finished yet, details can be found in the <A
1017HREF="release.htm">Release
1018Notes</A> page.
1019<H4>
1020Query Programs</H4>
1021Three utility query programs are included with the distribution,
1022<TT>ntpq</TT>,
1023<TT>ntptrace</TT> and <TT>ntpdc</TT>. <TT>ntpq</TT> is a handy program
1024which sends queries and receives responses using NTP standard mode-6
1025control
1026messages. Since it uses the standard control protocol specified in RFC-
10271305,
1028it may be used with NTP Version 2 and Version 3 implementations for both
1029Unix and Fuzzball, but not Version 1 implementations. It is most useful
1030to query remote NTP implementations to assess timekeeping accuracy and
1031expose bugs in configuration or operation.
1032
1033<P><TT>ntptrace</TT> can be used to display the current synchronization
1034path from a selected host through possibly intervening servers to the
1035primary
1036source of synchronization, usually a radio clock. It works with both
1037version
10382 and version 3 servers, but not version 1.
1039
1040<P><TT>ntpdc</TT> is a horrid program which uses NTP private mode-7
1041control
1042messages to query local or remote servers. The format and contents of
1043these
1044messages are specific to this version of <TT>ntpd</TT> and some older
1045versions.
1046The program does allow inspection of a wide variety of internal counters
1047and other state data, and hence does make a pretty good debugging tool,
1048even if it is frustrating to use. The other thing of note about
1049<TT>ntpdc</TT>
1050is that it provides a user interface to the run time reconfiguration
1051facility.
1052See the respective document pages for details on the use of these
1053programs.
1054<H4>
1055Run-Time Reconfiguration</H4>
1056<TT>ntpd</TT> was written specifically to allow its configuration to be
1057fully modifiable at run time. Indeed, the only way to configure the
1058server
1059is at run time. The configuration file is read only after the rest of
1060the
1061server has been initialized into a running default-configured state.
1062This
1063facility was included not so much for the benefit of Unix, where it is
1064handy but not strictly essential, but rather for dedicated platforms
1065where
1066the feature is more important for maintenance. Nevertheless, run time
1067configuration
1068works very nicely for Unix servers as well.
1069
1070<P>Nearly all of the things it is possible to configure in the
1071configuration
1072file may be altered via NTP mode-7 messages using the <TT>ntpdc</TT>
1073program.
1074Mode-6 messages may also provide some limited configuration
1075functionality
1076(though the only thing you can currently do with mode-6 messages is set
1077the leap-second warning bits) and the <TT>ntpq</TT> program provides
1078generic
1079support for the latter. The leap bits that can be set in the
1080<TT>leap_warning</TT>
1081variable (up to one month ahead) and in the <TT>leap_indication</TT>
1082variable
1083have a slightly different encoding than the usual interpretation:
1084<PRE>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1085Value&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; Action
1086
1087&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
108800&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs
1089p; The daemon passes the leap bits of its
1090&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1091&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1092synchronisation source (usual mode of operation)
1093
1094&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 01/10&nbsp;&nbsp; A leap
1095second is added/deleted
1096
1097&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
109811&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbs
1099p; Leap information from the synchronization source
1100&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
1101&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; is
1102ignored (thus LEAP_NOWARNING is passed on)</PRE>
1103Mode-6 and mode-7 messages which would modify the configuration of the
1104server are required to be authenticated using standard NTP
1105authentication.
1106To enable the facilities one must, in addition to specifying the
1107location
1108of a keys file, indicate in the configuration file the key IDs to be
1109used
1110for authenticating reconfiguration commands. Hence the following
1111fragment
1112might be added to a configuration file to enable the mode-6 (ntpq) and
1113mode-7 (ntpdc) facilities in the daemon:
1114<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # specify mode-6 and mode-7 trusted keys
1115
1116&nbsp;&nbsp;&nbsp;&nbsp; requestkey 65535&nbsp;&nbsp;&nbsp; # for mode-7
1117requests
1118&nbsp;&nbsp;&nbsp;&nbsp; controlkey 65534&nbsp;&nbsp;&nbsp; # for mode-6
1119requests</PRE>
1120If the <TT>requestkey</TT> and/or the <TT>controlkey</TT> configuration
1121declarations are omitted from the configuration file, the corresponding
1122run-time reconfiguration facility is disabled.
1123
1124<P>The query programs require the user to specify a key ID and a key to
1125use for authenticating requests to be sent. The key ID provided should
1126be the same as the one mentioned in the configuration file, while the
1127key
1128should match that corresponding to the key ID in the keys file. As the
1129query programs prompt for the key as a password, it is useful to make
1130the
1131request and control authentication keys typeable (in ASCII format) from
1132the keyboard.
1133<H4>
1134Name Resolution</H4>
1135<TT>ntpd</TT> includes the capability to specify host names requiring
1136resolution
1137in <TT>peer</TT> and <TT>server</TT> declarations in the configuration
1138file. However, in some outposts of the Internet, name resolution is
1139unreliable
1140and the interface to the Unix resolver routines is synchronous. The
1141hangups
1142and delays resulting from name-resolver clanking can be unacceptable
1143once
1144the NTP server is running (and remember it is up and running before the
1145configuration file is read). However, it is advantageous to resolve time
1146server names, since their addresses are occasionally changed.
1147
1148<P>In order to prevent configuration delays due to the name resolver,
1149the
1150daemon runs the name resolution process in parallel with the main daemon
1151code. When the daemon comes across a <TT>peer</TT> or <TT>server</TT>
1152entry
1153with a non-numeric host address, it records the relevant information in
1154a temporary file and continues on. When the end of the configuration
1155file
1156has been reached and one or more entries requiring name resolution have
1157been found, the server runs the name resolver from the temporary file.
1158The server then continues on normally but with the offending
1159peers/servers
1160omitted from its configuration.
1161
1162<P>As each name is resolved, it configures the associated entry into the
1163server using the same mode-7 run time reconfiguration facility that
1164<TT>ntpdc</TT>
1165uses. If temporary resolver failures occur, the resolver will
1166periodically
1167retry the requests until a definite response is received. The program
1168will
1169continue to run until all entries have been resolved.
1170<H4>
1171<A NAME="frequency_tolerance">Dealing with Frequency Tolerance
1172Violations</A>
1173  (<TT>tickadj</TT> and Friends)</H4>
1174The NTP Version 3 specification RFC-1305 calls for a maximum oscillator
1175frequency tolerance of +-100 parts-per-million (PPM), which is
1176representative
1177of those components suitable for use in relatively inexpensive
1178workstation
1179platforms. For those platforms meeting this tolerance, NTP will
1180automatically
1181compensate for the frequency errors of the individual oscillator and no
1182further adjustments are required, either to the configuration file or to
1183various kernel variables. For the NTP Version 4 release, this tolerance
1184has been increased to +-500 PPM.
1185
1186<P>However, in the case of certain notorious platforms, in particular
1187Sun
11884.1.1 systems, the performance can be improved by adjusting the values
1189of certain kernel variables; in particular, <TT>tick</TT> and
1190<TT>tickadj</TT>.
1191The variable <TT>tick</TT> is the increment in microseconds added to the
1192system time on each interval- timer interrupt, while the variable
1193<TT>tickadj</TT>
1194is used by the time adjustment code as a slew rate, in microseconds per
1195tick. When the time is being adjusted via a call to the system routine
1196<TT>adjtime()</TT>, the kernel increases or reduces tick by
1197<TT>tickadj</TT>
1198microseconds per tick until the specified adjustment has been completed.
1199Unfortunately, in most Unix implementations the tick increment must be
1200either zero or plus/minus exactly <TT>tickadj</TT> microseconds, meaning
1201that adjustments are truncated to be an integral multiple of
1202<TT>tickadj</TT>
1203(this latter behaviour is a misfeature, and is the only reason the
1204<TT>tickadj</TT>
1205code needs to concern itself with the internal implementation of
1206<TT>tickadj</TT>
1207at all). In addition, the stock Unix implementation considers it an
1208error
1209to request another adjustment before a prior one has completed.
1210<P>Thus, to make very sure it avoids problems related to the roundoff,
1211the <TT>tickadj </TT>program can be used to adjust the values of
1212<TT>tick</TT>
1213and <TT>tickadj</TT>. This ensures that all adjustments given to
1214<TT>adjtime()</TT>
1215are an even multiple of <TT>tickadj</TT> microseconds and computes the
1216largest adjustment that can be completed in the adjustment interval
1217(using
1218both the value of <TT>tick</TT> and the value of <TT>tickadj</TT>) so it
1219can avoid exceeding this limit. It is important to note that not all
1220systems
1221will allow inspection or modification of kernel variables other than at
1222system build time. It is also important to know that, with the current
1223NTP tolerances, it is rarely necessary to make these changes, but in
1224many
1225cases they will substantially improve the general accurace of the time
1226service.
1227
1228<P>Unfortunately, the value of <TT>tickadj</TT> set by default is almost
1229always too large for <TT>ntpd</TT>. NTP operates by continuously making
1230small adjustments to the clock, usually at one-second intervals. If
1231<TT>tickadj</TT>
1232is set too large, the adjustments will disappear in the roundoff; while,
1233if <TT>tickadj</TT> is too small, NTP will have difficulty if it needs
1234to make an occasional large adjustment. While the daemon itself will
1235read
1236the kernel's values of these variables, it will not change the values,
1237even if they are unsuitable. You must do this yourself before the daemon
1238is started using the <TT>tickadj</TT> program included in the
1239<TT>./util</TT>
1240directory of the distribution. Note that the latter program will also
1241compute
1242an optimal value of <TT>tickadj</TT> for NTP use based on the kernel's
1243value of <TT>tick</TT>.
1244
1245<P>The <TT>tickadj</TT> program can reset several other kernel variables
1246if asked. It can change the value of <TT>tick</TT> if asked. This is
1247handy to compensate for kernel bugs which cause the clock to run with a
1248very large frequency error, as with SunOS 4.1.1 systems. It can also be
1249used to set the value of the kernel <TT>dosynctodr</TT> variable to
1250zero.  This variable controls whether to synchronize the system clock to
1251the time-of-day clock, something you really don't want to be happen
1252when <TT>ntpd</TT> is trying to keep it under control. In some systems,
1253such as recent Sun Solaris kernels, the <TT>dosynctodr </TT>variable is
1254the only one that can be changed by the <TT>tickadj </TT>program. In
1255this and other modern kernels, it is not necessary to change the other
1256variables in any case.
1257
1258<P>
1259We have a report that says starting with Solaris 2.6 we should
1260leave <I>dosynctodr</I> alone.
1261<A HREF="solaris-dosynctodr.html">Here is the report</A>.
1262
1263<P>In order to maintain reasonable correctness bounds, as well as
1264reasonably
1265good accuracy with acceptable polling intervals, <TT>ntpd</TT> will
1266complain
1267if the frequency error is greater than 500 PPM. For machines with a
1268value
1269of <TT>tick</TT> in the 10-ms range, a change of one in the value of
1270<TT>tick</TT>
1271will change the frequency by about 100 PPM. In order to determine the
1272value
1273of <TT>tick</TT> for a particular CPU, disconnect the machine from all
1274sources of time (<TT>dosynctodr</TT> = 0) and record its actual time
1275compared
1276to an outside source (eyeball-and-wristwatch will do) over a day or
1277more.
1278Multiply the time change over the day by 0.116 and add or subtract the
1279result to tick, depending on whether the CPU is fast or slow. An example
1280call to <TT>tickadj</TT> useful on SunOS 4.1.1 is:
1281<PRE>&nbsp;&nbsp;&nbsp;&nbsp; <TT>tickadj</TT> -t 9999 -a 5 -s</PRE>
1282which sets tick 100 PPM fast, <TT>tickadj</TT> to 5 microseconds and
1283turns
1284off the clock/calendar chip fiddle. This line can be added to the
1285<TT>rc.local</TT>
1286configuration file to automatically set the kernel variables at boot
1287time.
1288
1289<P>All this stuff about diddling kernel variables so the NTP daemon will
1290work is really silly. If vendors would ship machines with clocks that
1291kept
1292reasonable time and would make their <TT>adjtime()</TT> system call
1293apply
1294the slew it is given exactly, independent of the value of
1295<TT>tickadj</TT>,
1296all this could go away. This is in fact the case on many current Unix
1297systems.
1298<H4>
1299Tuning Your Subnet</H4>
1300There are several parameters available for tuning the NTP subnet for
1301maximum
1302accuracy and minimum jitter. One of these is the <TT>prefer</TT>
1303configuration
1304declaration described in <A HREF="prefer.htm">Mitigation Rules and the
1305<TT>prefer</TT> Keyword </A>documentation page. When more than one
1306eligible
1307server exists, the NTP clock-selection and combining algorithms act to
1308winnow out all except the "best" set of servers using several criteria
1309based on differences between the readings of different servers and
1310between
1311successive readings of the same server. The result is usually a set of
1312surviving servers that are apparently statistically equivalent in
1313accuracy,
1314jitter and stability. The population of survivors remaining in this set
1315depends on the individual server characteristics measured during the
1316selection
1317process and may vary from time to time as the result of normal
1318statistical
1319variations. In LANs with high speed RISC-based time servers, the
1320population
1321can become somewhat unstable, with individual servers popping in and out
1322of the surviving population, generally resulting in a regime called
1323<I>clockhopping</I>.
1324
1325<P>When only the smallest residual jitter can be tolerated, it may be
1326convenient
1327to elect one of the servers at each stratum level as the preferred one
1328using the keyword <TT>prefer</TT> on the configuration declaration for
1329the selected server:
1330<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # preferred server declaration
1331
1332&nbsp;&nbsp;&nbsp;&nbsp; peer rackety.udel.edu prefer&nbsp;&nbsp;&nbsp;
1333# preferred server</PRE>
1334The preferred server will always be included in the surviving
1335population,
1336regardless of its characteristics and as long as it survives preliminary
1337sanity checks and validation procedures.
1338
1339<P>The most useful application of the <TT>prefer</TT> keyword is in high
1340speed LANs equipped with precision radio clocks, such as a GPS receiver.
1341In order to insure robustness, the hosts need to include outside peers
1342as well as the GPS-equipped server; however, as long as that server is
1343running, the synchronization preference should be that server. The
1344keyword
1345should normally be used in all cases in order to prefer an attached
1346radio
1347clock. It is probably inadvisable to use this keyword for peers outside
1348the LAN, since it interferes with the carefully crafted judgement of the
1349selection and combining algorithms.
1350<H4>
1351Provisions for Leap Seconds and Accuracy Metrics</H4>
1352<TT>ntpd</TT> understands leap seconds and will attempt to take
1353appropriate
1354action when one occurs. In principle, every host running ntpd will
1355insert
1356a leap second in the local timescale in precise synchronization with
1357UTC.
1358This requires that the leap-warning bits be activated some time prior to
1359the occurrence of a leap second at the primary (stratum 1) servers.
1360Subsequently,
1361these bits are propagated throughout the subnet depending on these
1362servers
1363by the NTP protocol itself and automatically implemented by
1364<TT>ntpd</TT>
1365and the time- conversion routines of each host. The implementation is
1366independent
1367of the idiosyncrasies of the particular radio clock, which vary widely
1368among the various devices, as long as the idiosyncratic behavior does
1369not
1370last for more than about 20 minutes following the leap. Provisions are
1371included to modify the behavior in cases where this cannot be
1372guaranteed.
1373While provisions for leap seconds have been carefully crafted so that
1374correct
1375timekeeping immediately before, during and after the occurrence of a
1376leap
1377second is scrupulously correct, stock Unix systems are mostly inept in
1378responding to the available information. This caveat goes also for the
1379maximum-error and statistical-error bounds carefully calculated for all
1380clients and servers, which could be very useful for application programs
1381needing to calibrate the delays and offsets to achieve a near-
1382simultaneous
1383commit procedure, for example. While this information is maintained in
1384the <TT>ntpd</TT> data structures, there is at present no way for
1385application
1386programs to access it. This may be a topic for further development.
1387<H4>
1388Clock Support Overview</H4>
1389<TT>ntpd</TT> was designed to support radio (and other external) clocks
1390and does some parts of this function with utmost care. Clocks are
1391treated
1392by the protocol as ordinary NTP peers, even to the point of referring to
1393them with an (invalid) IP host address. Clock addresses are of the form
1394127.127.<I>t.u</I>, where <I>t</I> specifies the particular type of
1395clock
1396(i.e., refers to a particular clock driver) and <I>u</I> is a unit
1397number
1398whose interpretation is clock-driver dependent. This is analogous to the
1399use of major and minor device numbers by Unix and permits multiple
1400instantiations
1401of clocks of the same type on the same server, should such magnificent
1402redundancy be required.
1403
1404<P>Because clocks look much like peers, both configuration file syntax
1405and run time reconfiguration commands can be used to control clocks in
1406the same way as ordinary peers. Clocks are configured via
1407<TT>server</TT>
1408declarations in the configuration file, can be started and stopped using
1409ntpdc and are subject to address-and-mask restrictions much like a
1410normal
1411peer, should this stretch of imagination ever be useful. As a concession
1412to the need to sometimes transmit additional information to clock
1413drivers,
1414an additional configuration file is available: the <TT>fudge</TT>
1415statement.
1416This enables one to specify the values of two time quantities, two
1417integral
1418values and two flags, the use of which is dependent on the particular
1419clock
1420driver. For example, to configure a PST radio clock which can be
1421accessed
1422through the serial device <TT>/dev/pst1</TT>, with propagation delays to
1423WWV and WWVH of 7.5 and 26.5 milliseconds, respectively, on a machine
1424with
1425an imprecise system clock and with the driver set to disbelieve the
1426radio
1427clock once it has gone 30 minutes without an update, one might use the
1428following configuration file entries:
1429<PRE>&nbsp;&nbsp;&nbsp;&nbsp; # radio clock fudge fiddles
1430&nbsp;&nbsp;&nbsp;&nbsp; server 127.127.3.1
1431&nbsp;&nbsp;&nbsp;&nbsp; fudge 127.127.3.1 time1 0.0075 time2 0.0265
1432&nbsp;&nbsp;&nbsp;&nbsp; fudge 127.127.3.1 value2 30 flag1 1</PRE>
1433Additional information on the interpretation of these data with respect
1434to various radio clock drivers is given in the <A
1435HREF="refclock.htm">Reference
1436Clock Drivers </A>document page and in the individual driver documents
1437accessible via that page.
1438<H4>
1439Towards the Ultimate Tick</H4>
1440This section considers issues in providing precision time
1441synchronization
1442in NTP subnets which need the highest quality time available in the
1443present
1444technology. These issues are important in subnets supporting real-time
1445services such as distributed multimedia conferencing and wide-area
1446experiment
1447control and monitoring.
1448
1449<P>In the Internet of today synchronization paths often span continents
1450and oceans with moderate to high variations in delay due to traffic
1451spasms.
1452NTP is specifically designed to minimize timekeeping jitter due to delay
1453variations using intricately crafted filtering and selection algorithms;
1454however, in cases where these variations are as much as a second or
1455more,
1456the residual jitter following these algorithms may still be excessive.
1457Sometimes, as in the case of some isolated NTP subnets where a local
1458source
1459of precision time is available, such as a PPS signal produced by a
1460calibrated
1461cesium clock, it is possible to remove the jitter and retime the local
1462clock oscillator of the NTP server. This has turned out to be a useful
1463feature to improve the synchronization quality of time distributed in
1464remote
1465places where radio clocks are not available. In these cases special
1466features
1467of the distribution are used together with the PPS signal to provide a
1468jitter-free timing signal, while NTP itself is used to provide the
1469coarse
1470timing and resolve the seconds numbering.
1471
1472<P>Most available radio clocks can provide time to an accuracy in the
1473order
1474of milliseconds, depending on propagation conditions, local noise levels
1475and so forth. However, as a practical matter, all clocks can
1476occasionally
1477display errors significantly exceeding nominal specifications. Usually,
1478the algorithms used by NTP for ordinary network peers, as well as radio
1479clock peers will detect and discard these errors as discrepancies
1480between
1481the disciplined local clock oscillator and the decoded time message
1482produced
1483by the radio clock. Some radio clocks can produce a special PPS signal
1484which can be interfaced to the server platform in a number of ways and
1485used to substantially improve the (disciplined) clock oscillator jitter
1486and wander characteristics by at least an order of magnitude. Using
1487these
1488features it is possible to achieve accuracies in the order of a few tens
1489of microseconds with a fast RISC- based platform.
1490
1491<P>There are three ways to implement PPS support, depending on the radio
1492clock model, platform model and serial line interface. These are
1493described
1494in detail in the application notes mentioned in the <A
1495HREF="index.htm">The
1496Network Time Protocol (NTP) Distribution </A>document page. Each of
1497these
1498requires circuitry to convert the TTL signal produced by most clocks to
1499the EIA levels used by most serial interfaces. The <A
1500HREF="gadget.htm">Gadget
1501Box PPS Level Converter and CHU Modem </A>document page describes a
1502device
1503designed to do this. Besides being useful for this purpose, this device
1504includes an inexpensive modem designed for use with the Canadian CHU
1505time/frequency
1506radio station.
1507
1508<P>In order to select the appropriate implementation, it is important to
1509understand the underlying PPS mechanism used by ntpd. The PPS support
1510depends
1511on a continuous source of PPS pulses used to calculate an offset within
1512+-500 milliseconds relative to the local clock. The serial timecode
1513produced
1514by the radio or the time determined by NTP in absence of the radio is
1515used
1516to adjust the local clock within +-128 milliseconds of the actual time.
1517As long as the local clock is within this interval the PPS support is
1518used
1519to discipline the local clock and the timecode used only to verify that
1520the local clock is in fact within the interval. Outside this interval
1521the
1522PPS support is disabled and the timecode used directly to control the
1523local
1524clock.
1525<H4>
1526Parting Shots</H4>
1527There are several undocumented programs which can be useful in unusual
1528cases. They can be found in the <TT>./clockstuff</TT> and
1529<TT>./authstuff</TT>
1530directories of the distribution. One of these is the <TT>propdelay</TT>
1531program, which can compute high frequency radio propagation delays
1532between
1533any two points whose latitude and longitude are known. The program
1534understands
1535something about the phenomena which allow high frequency radio
1536propagation
1537to occur, and will generally provide a better estimate than a
1538calculation
1539based on the great circle distance. Other programs of interest include
1540<TT>clktest</TT>, which allows one to exercise the generic clock line
1541discipline,
1542and <TT>chutest</TT>, which runs the basic reduction algorithms used by
1543the daemon on data received from a serial port.&nbsp;
1544
1545<hr><a href=index.htm><img align=left src=pic/home.gif></a><address><a
1546href=mailto:mills@udel.edu> David L. Mills &lt;mills@udel.edu&gt;</a>
1547</address></a></body></html>
Note: See TracBrowser for help on using the repository browser.