1 Copyright 2000, International Business Machines Corporation and others.
4 This software has been released under the terms of the IBM Public
5 License. For details, see the LICENSE file in the top-level source
6 directory or online at http://www.openafs.org/dl/license10.html
8 README for UNIX NTP release $Date$ $Revision$
12 NTP (Network Time Protocol) Daemons
14 There are three programs in the NTP distribution:
15 ntp - simple query program used for single
18 ntpd - A daemon that sets up peers and responds
19 to queries. Ntpd does the clock trimming.
21 ntpdc - program to query an ntpd. It was useful in
22 checking the filters and cleaning the windows
26 1) Add an entry to /etc/services to define the ntp port.
28 ntp 123/udp # network time protocol (exp)
30 2) Make a /etc/ntp.conf with the clocks you want to track.
31 Please refer to the RFC's in the man directory, the man
32 pages, and the clock.txt file to assist you in selecting
33 clocks to peer with. The supplied ntp.conf is only a
34 sample, and is not suitable for use.
37 3) Change the Makefile definitions to suit your environment.
40 6) adb or remake kernel and change "tickadj"
41 Recommended values for tickadj on various machines:
48 This step is optional; new algorithms will allow you to
49 get by (with reduced accuracy) with the system supplied
50 value of tickadj. For better preformence, you should
51 change the value of tickadj. This can be done by making
52 a new kernel or by compiling ntpd with SETTICKADJ defined,
53 and having ntpd set it to the value you specify. This is
56 7) Fire up ntpd in /etc/rc.local
60 Yet another preprocessor define for broken unsigned long to double
61 conversions. Define GENERIC_UNS_BUG, and the unsigned long is shifted
62 right one bit and cast to an int before conversion to a double. This
63 seems to work much better.
65 Preliminary support for NeXT systems. Be sure to define both
66 GENERIC_UNS_BUG and SUN_FLT_BUG. The default value of tickadj in the
67 kernel is too large so you'll have to adjust it by using the
68 -t option and compiling with SETTICKADJ. I don't think you can use
69 gdb on the running /dev/mem image. NOTE: don't even think of trying
70 to run this on the 0.8 release of the system software. You will
71 utterly and absolutely hang you system. Current testing is being
72 done on the 0.9 release. So far, there seems to be some weirdness in
73 the kernel which is attempting to sync to the clock to the internal
74 clock chip every so ofter. So while it compiles and runs, it really
75 doesn't work very well on the NeXT machine.
77 Integration of the reference clock code
78 has been done. To configure a reference clock, check the
82 The changes to the ntp_proto.c module for clockhopper suppression have
83 been tweaked once more, ever so slightly to conform with the 21 April
84 1989 draft of the NTP spec. We won't switch peers if the current
85 peer makes it into the final selection list, unless the first peer on
86 the selection list is of a higher stratum than the current peer.
88 The ntpd.c/hourly() function now saves the value of the drift
89 compensation register to a file (/etc/ntp.drift by default). In fact,
90 the last 5 hourly samples are written to the file, as well as how
91 many hours the ntpd process has been running. Ntpd will also attempt
92 to intialize the value of the drift compensation register from this
93 file when it is started up. The hourly stats: log message has been
94 augmented to log additional information.
97 Changes to the ntp_proto.c module to supress peer switching when the
98 dispersion between the newly selected peer and the currently selected
99 peer is "small." A new configuration option, NOSWAP, has been added
100 for use on Ultrix systems which can lock the ntpd process in memory;
101 very desirable for diskless workstations. peer.reach is now not
102 cleared in the clear() procedure. The stat.pl perl script can now
103 handle syslog records which span a month boundary correctly. We're
104 getting real close to a "blessed" version now.
107 A few fixes, clean up of unused #defines in ntp.h. The receive()
108 procedure is now table driven per the 26 March 1989 draft of the
109 spec. If no terrible errors or bugs are found, this version
110 will probably be packaged as a "blessed" working version before
111 the next stage of major hacking.
114 A bunch of minor fixes here an there. The RCS header is being
115 updated so that patches that are generated will apply; apparently
116 the new version of RCS puts the Locked: status in the Header
118 Minor fiddles to ntpd/ntpdc to eliminate some byte-sex dependencies.
119 Changs to ntp_proto.c to fix an mis-interpretation in the packet
122 The ntp program now uses connected UDP sockets to pick up ICMP
125 ntpdc will now select a value of tickadj if you don't specify one.
128 Another sort-of-working ntpd. There might still be something weird
129 with the logical clock code; seems to be a little weird. Would
130 really like your comments on this version.
132 Note that the a version that supports the Precision Time WWV clock
133 can be had via anonymous FTP from BITSY.MIT.EDU. The version there
134 might lag the University of Maryland version.
137 A snapshot of a more-or-less working ntpd. There's been a few more
138 bug fixes and changes due to the NTP spec being revised. A few more
139 changes have been made to the latest NTP spec (11 March 1989 version)
140 which have not yet been applied.
142 A few problems areas: I currently observe some peer flapping between
143 two clock which are both of very good quality (UMD1.UMD.EDU and
144 TRUECHIMER.CSO.UIUC.EDU). Not quite sure why this is happening yet
145 or if it is really a problem.
147 There are quite a few "Dropping peer <foo>" messages in the syslog.
148 Most of these are due to lower statum "transient" clocks peering with
149 the local daemon. Need to find a way to supress the messages in
150 the transmit procedure when we've got no intention of keeping a
151 peer structure around for them.
153 There are changes in the works to improve the reliability of the
154 ntpdc program. The ntpd hooks are there now, and some work remains
155 in the ntpdc program.
159 *** THIS IS A TEST RELEASE ***
161 This version contain most of the new algorithms from the 6 March 1989
162 draft of the NTP specification. It still operates, however, as
163 Version 1, and does not support the authentication feature.
165 The stratum 1 WWV clock code from Doug Kingston has not been tested or
166 changed for this release. I would really like someone to change the
167 interface to have the clock appear as just another peer.
169 Quite a bit if clean-up and cosmetic changes were made in almost all
170 of the modules. Note that the ntest program which tests certain
171 arithmetic operations on you machine is automatically run by the
172 Makefile. If it fail *for any reason*, stop right there and find
173 out why. Until ntest works correctly, don't even bother with the
174 rest of the code. Note that at least Ultrix has problems, and there
175 is a define option in the makefile to accomodate the broken Ultrix
176 pcc compiler. Recent version of GNU CC are known to work correctly
177 on a VAX platform, and is in fact used for development. It is not
178 necessary to use the GNU C compiler on you machine, however.
180 The logical clock code in ntp_adjust.c has been changed to be more
181 self-contained and independent from NTP proper. It has the tickadj
182 round-off residual accumulating code, and attempts to implemenet the
183 newest version of the NTP logical clock code. A large change here is
184 that once an clock update has been passed to the logical clock, it will
185 ignore further updated for 1<<CLOCK_UPDATE seconds. Note that the
186 units for tick_adj have changed in this version. Eventually, a
187 normalized version of this value will be written to a file for use
188 on subsequent invocations.
190 There has been no work in the area of supporting broadcast NTP. A
191 bunch of bug fixes have been made to the ntp_proto.c module, including
192 a significant one in the code which selects the clock; the dispersion
193 computed before was incorrect and resulted in poor clock choices. This
194 is probably the cause of having long "strings" of peers rather then
195 all syncing to one clock.
197 The ntpd will now actually delete peer entries when the hosts "go
198 away." This will hopefully save some memory. The peer list is now
199 doublely linked, so deletions can happen very efficiently.
201 There is still a weirdness in there when interoperating with very old
202 broken versions of ntpd. It manifests itself with peers being expunged
203 and them coming back.
205 Please beat on this version and let me know what bugs you find. I
206 want to make another release, this one "blessed" until the Version 2
211 *** THIS IS A TEST RELEASE ***
212 There have been a bunch of bug fixes, and an attemtp to unify the
213 the debug output and logging. There is still a problem with the
214 verbose version of ntpdc; the offset values are clearly bogus.
216 Danger: don't attempt to run ntpd on a NeXT machine. It provokes
217 a bug in the OS which hangs the machine quite absolutely.
219 There is some support for a statrum 1 clock in some code provided by
220 Doug Kingston (dpk@morgan.com). I'm not really sure that its the
221 ``right'' way to do it; I'd rather have the clock appear just like
222 another peer, and have it selected as a reference, just like you'd
223 select any other clock. In fact, by doing it that way with some other
224 support, you could even have a seperate process take care of reading
225 the clock, and talking to the main process with some UNIX domain
229 *** THIS IS A TEST RELEASE ***
230 Really. We have tested this code on a VAX platform, but not much of
231 anything else. I would like to hear back about any bugs, but you
232 should not treat this as a 'release' version.
234 Very large number of changes and updates. Files have been reorganized
235 with ntpd.c containing intialization and other very UNIX specific code,
236 while the new file ntp_proto.c contains the bulk of the NTP code.
237 This version of the UNIX NTP daemon was re-written and updated to
238 conform with the revised NTP specification.
240 For all of the mucking about with tickadj, you can now define
241 SETTICKADJ in the Makefile, and specify the value of tickadj in
242 /etc/ntp.conf. The ntpd will attempt to update `tickadj' using
245 If possible, ntpd will attempt to discover the value of your kernel's
246 `hz' variable, and set the value of `precison' automagically. If
247 `precision' is specified in /etc/ntp.conf, it will override any
250 Only hosts which are configured or mentioned in /etc/ntp.conf on a
251 `peer', `server' or `passive' statement are elligable to be
252 synchronized to. This solves the "ganging-up" problem, but is sorta
255 The `peer' statement in /etc/ntp.conf works just as before; it sends
256 packets with MODE=SYMMETRIC-ACTIVE to the remote host. The remote host
257 might synchronize to you if appropriate. If reachability is lost,
258 polling will continue.
260 The new `server' statement in /etc/ntp.conf causes packets of MODE=
261 CLIENT to be sent to the specified host. The remote host will *not*
262 synchronize to you under any circumstances. If reachability is lost,
263 polling will continue.
265 The new `passive' statement in /etc/ntp.conf causes packets of
266 MODE=SYMMETRIC-PASSIVE to be sent to the remote host *when the local
267 host is polled*. If reachability is lost, then polling will cease
268 until the remote host begins to the local host again.
270 Note conditional compilation define in the makefile for
271 VAX_COMPILER_FLT_BUG for old 4.2 and Ultrix 2.0/2.2/3.0 pcc compilers.
272 There is a bug in the code generated to convert an unsigned long to a
273 double. Previously, this code was always present, but it is now
274 #ifdef'd. The 4.3BSD-tahoe and GNU CC (1.30 and 1.31 at least) are
275 known to work correctly. If you don't know if your compiler
276 performs this conversion correctly, try making and running the
277 `ntest' program, and see if test3 passes or not.
279 The format of the data sent between ntpd and the ntpdc programs has
280 changed yet again. It is likely to change again before the final
281 release of this version.
284 Added and updated manual entries contributed by Glenn Trewitt.
285 (trewitt@miasma.stanford.edu)
287 Reorder peer list so configuted hosts are always first. This
288 REALLY helps the faleticker code.
290 Changed ntpdc to have a larger RECV socket buffer. This fixes
291 the "only see 20 peers" problem. This is a side affect of using
292 UDP for the status return.
295 Support for hosts with multiple interfaces. Minor updates to
296 the ntpdc program; note that the format of the messages between
297 the ntpd and ntpdc programs is different in this version than the
298 last. You should update both ntpd and ntpdc at the same time.
300 New file ``ntp_sock.c''. Tested with Ultrix 2.4 field test, and
301 4.3 BSD tahoe release. Debug level can be adjusted by sending
302 SIGUSR1 to increase and SIGUSR2 to zero the debug level.
305 Changed peer structure alloactor to stop allocating a perm
306 structure for non-peer relationships. This make the ntpdc
307 output a lot more understandable.
308 Installed faletick code.
309 Installed work around to bug in Ultrix C compiler.
310 The compiler has troubles converting unsigned longs to floats.
311 This caused a lot of off by 2 second problems.
313 The world is ALL different now. The NTP protocols have had
314 some major structural work. This is the first rev that
315 attempts to meet NTP version 1 compliance. There are a couple
316 of loose ends (faltickers code and clock slew rate) that
317 are not finished, but should be RSN. This release is to
318 bridge the compatability with the old clock system.
321 ntpsubs.c had a MAJOR bug in the tstamp routine. Accuracy
322 should be much better now.
324 The ntp.conf file is much simpler. List your precision
325 and peers, the rest is automagic.
327 The ntp/udp service mapping is now consitent. No more hard
330 The math routines are more robust. They now handle signed
331 conversion of longs and shorts.
333 The control structure of ntpd is radically different. A peer
334 relation is NOT setup for clocks at a higher stratum. This
335 reduces table clutter, but you lose the history of those
339 Removed the median filter and replaced it with a minimum
340 filter. Experimentation by Dave Mills suggests this is
341 a better way to track network clocks. Changed status field based
345 Only believe samples were the round trip delay is positive.
346 I recommend HIGHLY that you change tickadj in /sys/conf/param.c
347 to equal 1 instead of 40. This reduces the granularity of
348 clock slewing from 4ms/sec to .1ms/sec. This should suffice
349 if your clock is less that 4.3 minutes per month. If this is
350 the case get a new clock, increase the value, or live with
351 periodic clock jumps due to setimeofday(). The basic problem is
352 that adjtime() slews only with "tickadj" granularity. That's
353 argueably broken, but needs kernel mods to fix it.
356 Added some of the changes from Greg Fowler and Ken Stone
357 of HP labs. This adds "hpux" compatability. Ken and Greg
358 also tighten up the "bestclock" determination so you
359 don't end up tracking yourself. (thanks again)
361 The Precision field in now correct, precision is the power
362 of 2 indication of internal clock tics. (ex. 60-HZ = -6)
363 This is a constant for the machine and should be set in the
367 Massive cleanup in the daemon code. There was a BIG problem
368 with "bestclock" peer calculation. A clock of a lower type would
369 be tracked if the delay to that clock was lower than the delay
370 to the higher precision clock. The peers listed in the ntp.conf
371 files are marked as PERM. This causes a ntp gram to go to these
372 guys regardless of any recv activity. This eliminates the problem
373 of a peer being down and not talking ot him when he comes back
374 up because the activity indicator went to zero. Using PERM
375 entries creates a fixed overhead, use it with caution.
376 There is the beginning of a second order filter that can be used
377 to adjust the kernel tick rate. More on that when it's done.
378 The data structures have changed for queries. Querying old
379 clocks will cause problems. Note - the NTP protocol has NOT
380 changed, only the query hack. The SET_THRESHOLD has been changed
381 to be more reasonable with the max slew rate of 4.3BSD. This
382 will be relaxed when the second order stuff is working.
386 All of the internal math is now done with doubles. This removes
387 a lot of the hair and cost. On vaxen the double yields 54(5) bits of
388 accuracy. The NTP timestamps are 64 bits. Converting to doubles
389 will cause the loss of some bits on ost machines. This is not bad
390 since most machines don't have clocks that could track even the lower
391 16 bits of the NTP timestamps.
393 NTP makes three choices on changing the local clock.
394 1) If the local clock apperars to be off by more than
395 WAYTOOBIG (1000.0) seconds, it refuses to do anything
397 2) If the local clock is off less than WAYTOOBIG but more
398 than SET_THRESHOLD (2.0) a settimeofday will be done.
399 3) If the clock is off less than SET_THRESHOLD an adjustime
402 Ntpd clears out the samples after every clock adjustment.
403 This helped to prevent the filter from overshouting based on old
405 ===========================================================================
406 Still cooking on the stove are:
408 modify adjtime - it won't allow small adjustments.
409 I may punt and put in a new adjtime that handles
410 the second order stuff.
412 making it handle broadcasted time like timed