README for UNIX NTP release $Date: 89/05/18 12:43:58 $ $Revision: 3.4.1.6 $



NTP (Network Time Protocol) Daemons

	There are three programs in the NTP distribution:
	ntp	-	simple query program used for single
			sample queries

	ntpd	-	A daemon that sets up peers and responds
			to queries.  Ntpd does the clock trimming.

	ntpdc	-	program to query an ntpd.  It was useful in
			checking the filters and cleaning the windows

Installation:

	1) Add an entry to /etc/services to define the ntp port.

	ntp	123/udp		# network time protocol (exp)

	2) Make a /etc/ntp.conf with the clocks you want to track.
		Please refer to the RFC's in the man directory, the man
		pages, and the clock.txt file to assist you in selecting
		clocks to peer with.  The supplied ntp.conf is only a 
		sample, and is not suitable for use.


	3) Change the Makefile definitions to suit your environment.
	4) make
	5) make install
	6) adb or remake kernel and change "tickadj"
		Recommended values for tickadj on various machines:

		VAX:	5
		Sun3:	10
		Sun4:	5
		NeXT:	7

		This step is optional; new algorithms will allow you to
		get by (with reduced accuracy) with the system supplied
		value of tickadj.  For better preformence, you should
		change the value of tickadj.  This can be done by making
		a new kernel or by compiling ntpd with SETTICKADJ defined,
		and having ntpd set it to the value you specify.  This is
		clearly ugly.

	7) Fire up ntpd in /etc/rc.local

History:
5/17/89
	Yet another preprocessor define for broken unsigned long to double
	conversions.  Define GENERIC_UNS_BUG, and the unsigned long is shifted
	right one bit and cast to an int before conversion to a double.  This
	seems to work much better.

	Preliminary support for NeXT systems.  Be sure to define both
	GENERIC_UNS_BUG and SUN_FLT_BUG.  The default value of tickadj in the
	kernel is too large so you'll have to adjust it by using the
	-t option and compiling with SETTICKADJ.  I don't think you can use
	gdb on the running /dev/mem image.   NOTE: don't even think of trying
	to run this on the 0.8 release of the system software.  You will
	utterly and absolutely hang you system.  Current testing is being 
	done on the 0.9 release.  So far, there seems to be some weirdness in
	the kernel which is attempting to sync to the clock to the internal
	clock chip every so ofter.  So while it compiles and runs, it really
	doesn't work very well on the NeXT machine.

	Integration of the reference clock code from Doug Kingston and Jeff 
	Schiller has been done.  To configure a reference clock, check the
	ntpd manual page.

5/3/89
	The changes to the ntp_proto.c module for clockhopper suppression have
	been tweaked once more, ever so slightly to conform with the 21 April
	1989 draft of the NTP spec.  We won't switch peers if the current 
	peer makes it into the final selection list, unless the first peer on
	the selection list is of a higher stratum than the current peer.

	The ntpd.c/hourly() function now saves the value of the drift
	compensation register to a file (/etc/ntp.drift by default).  In fact,
	the last 5 hourly samples are written to the file, as well as how
	many hours the ntpd process has been running.  Ntpd will also attempt
	to intialize the value of the drift compensation register from this
	file when it is started up.  The hourly stats: log message has been
	augmented to log additional information.

4/8/89
	Changes to the ntp_proto.c module to supress peer switching when the
	dispersion between the newly selected peer and the currently selected
	peer is "small."  A new configuration option, NOSWAP, has been added
	for use on Ultrix systems which can lock the ntpd process in memory;
	very desirable for diskless workstations.  peer.reach is now not
	cleared in the clear() procedure.  The stat.pl perl script can now
	handle syslog records which span a month boundary correctly.  We're
	getting real close to a "blessed" version now.

3/29/89
	A few fixes, clean up of unused #defines in ntp.h.  The receive()
	procedure is now table driven per the 26 March 1989 draft of the
	spec.  If no terrible errors or bugs are found, this version
	will probably be packaged as a "blessed" working version before
	the next stage of major hacking.

3/22/89
	A bunch of minor fixes here an there.  The RCS header is being
	updated so that patches that are generated will apply; apparently
	the new version of RCS puts the Locked: status in the Header

	Minor fiddles to ntpd/ntpdc to eliminate some byte-sex dependencies.
	Changs to ntp_proto.c to fix an mis-interpretation in the packet
	procedure.

	The ntp program now uses connected UDP sockets to pick up ICMP
	generated errors.

	ntpdc will now select a value of tickadj if you don't specify one.

3/17/89
	Another sort-of-working ntpd.  There might still be something weird
	with the logical clock code; seems to be a little weird.  Would
	really like your comments on this version.

	Note that the a version that supports the Precision Time WWV clock
	can be had via anonymous FTP from BITSY.MIT.EDU.  The version there
	might lag the University of Maryland version.

3/12/89
	A snapshot of a more-or-less working ntpd.  There's been a few more
	bug fixes and changes due to the NTP spec being revised.  A few more
	changes have been made to the latest NTP spec (11 March 1989 version)
	which have not yet been applied.

	A few problems areas:  I currently observe some peer flapping between
	two clock which are both of very good quality (UMD1.UMD.EDU and
	TRUECHIMER.CSO.UIUC.EDU).  Not quite sure why this is happening yet
	or if it is really a problem.

	There are quite a few "Dropping peer <foo>" messages in the syslog.
	Most of these are due to lower statum "transient" clocks peering with
	the local daemon.  Need to find a way to supress the messages in
	the transmit procedure when we've got no intention of keeping a
	peer structure around for them.

	There are changes in the works to improve the reliability of the 
	ntpdc program.  The ntpd hooks are there now, and some work remains
	in the ntpdc program.


3/7/89
	*** THIS IS A TEST RELEASE ***

	This version contain most of the new algorithms from the 6 March 1989
	draft of the NTP specification.  It still operates, however, as 
	Version 1, and does not support the authentication feature.

	The stratum 1 WWV clock code from Doug Kingston has not been tested or
	changed for this release.  I would really like someone to change the
	interface to have the clock appear as just another peer.

	Quite a bit if clean-up and cosmetic changes were made in almost all
	of the modules.  Note that the ntest program which tests certain
	arithmetic operations on you machine is automatically run by the
	Makefile.  If it fail *for any reason*, stop right there and find
	out why.  Until ntest works correctly, don't even bother with the
	rest of the code.  Note that at least Ultrix has problems, and there
	is a define option in the makefile to accomodate the broken Ultrix
	pcc compiler.  Recent version of GNU CC are known to work correctly
	on a VAX platform, and is in fact used for development.  It is not
	necessary to use the GNU C compiler on you machine, however.

	The logical clock code in ntp_adjust.c has been changed to be more
	self-contained and independent from NTP proper.  It has the tickadj
	round-off residual accumulating code, and attempts to implemenet the
	newest version of the NTP logical clock code.  A large change here is
	that once an clock update has been passed to the logical clock, it will
	ignore further updated for 1<<CLOCK_UPDATE seconds.  Note that the
	units for tick_adj have changed in this version.  Eventually, a
	normalized version of this value will be written to a file for use
	on subsequent invocations.

	There has been no work in the area of supporting broadcast NTP.  A
	bunch of bug fixes have been made to the ntp_proto.c module, including
	a significant one in the code which selects the clock; the dispersion
	computed before was incorrect and resulted in poor clock choices.  This
	is probably the cause of having long "strings" of peers rather then 
	all syncing to one clock.

	The ntpd will now actually delete peer entries when the hosts "go 
	away."  This will hopefully save some memory.  The peer list is now
	doublely linked, so deletions can happen very efficiently.

	There is still a weirdness in there when interoperating with very old
	broken versions of ntpd.  It manifests itself with peers being expunged
	and them coming back.

	Please beat on this version and let me know what bugs you find.  I
	want to make another release, this one "blessed" until the Version 2
	one is ready.


1/12/89
	*** THIS IS A TEST RELEASE ***
	There have been a bunch of bug fixes, and an attemtp to unify the
	the debug output and logging.  There is still a problem with the
	verbose version of ntpdc; the offset values are clearly bogus.

	Danger: don't attempt to run ntpd on a NeXT machine.  It provokes
	a bug in the OS which hangs the machine quite absolutely.

	There is some support for a statrum 1 clock in some code provided by
	Doug Kingston (dpk@morgan.com).  I'm not really sure that its the
	``right'' way to do it; I'd rather have the clock appear just like
	another peer, and have it selected as a reference, just like you'd
	select any other clock.  In fact, by doing it that way with some other
	support, you could even have a seperate process take care of reading
	the clock, and talking to the main process with some UNIX domain
	sockets... Hmm..

12/8/88
	*** THIS IS A TEST RELEASE ***
	Really.  We have tested this code on a VAX platform, but not much of
	anything else.  I would like to hear back about any bugs, but you 
	should not treat this as a 'release' version.

	Very large number of changes and updates.  Files have been reorganized
	with ntpd.c containing intialization and other very UNIX specific code,
	while the new file ntp_proto.c contains the bulk of the NTP code.
	This version of the UNIX NTP daemon was re-written and updated to
	conform with the revised NTP specification.

	For all of the mucking about with tickadj, you can now define 
	SETTICKADJ in the Makefile, and specify the value of tickadj in 
	/etc/ntp.conf.  The ntpd will attempt to update `tickadj' using 
	/dev/kmem.  Yow!

	If possible, ntpd will attempt to discover the value of your kernel's
	`hz' variable, and set the value of `precison' automagically.  If 
	`precision' is specified in /etc/ntp.conf, it will override any 
	automatic selection.

	Only hosts which are configured or mentioned in /etc/ntp.conf on a
	`peer', `server' or `passive' statement are elligable to be
	synchronized to.  This solves the "ganging-up" problem, but is sorta
	ugly.

	The `peer' statement in /etc/ntp.conf works just as before; it sends
	packets with MODE=SYMMETRIC-ACTIVE to the remote host.  The remote host
	might synchronize to you if appropriate.  If reachability is lost,
	polling will continue.

	The new `server' statement in /etc/ntp.conf causes packets of MODE=
	CLIENT to be sent to the specified host.  The remote host will *not*
	synchronize to you under any circumstances.  If reachability is lost,
	polling will continue.

	The new `passive' statement in /etc/ntp.conf causes packets of
	MODE=SYMMETRIC-PASSIVE to be sent to the remote host *when the local
	host is polled*.  If reachability is lost, then polling will cease
	until the remote host begins to the local host again.

	Note conditional compilation define in the makefile for
	VAX_COMPILER_FLT_BUG for old 4.2 and Ultrix 2.0/2.2/3.0 pcc compilers.
	There is a bug in the code generated to convert an unsigned long to a 
	double.  Previously, this code was always present, but it is now 
	#ifdef'd.  The 4.3BSD-tahoe and GNU CC (1.30 and 1.31 at least) are
	known to work correctly.  If you don't know if your compiler 
	performs this conversion correctly, try making and running the
	`ntest' program, and see if test3 passes or not.

	The format of the data sent between ntpd and the ntpdc programs has
	changed yet again.  It is likely to change again before the final
	release of this version.  

7/30/88
	Added and updated manual entries contributed by Glenn Trewitt.
		(trewitt@miasma.stanford.edu)
7/27/88
	Reorder peer list so configuted hosts are always first.  This
	REALLY helps the faleticker code.

	Changed ntpdc to have a larger RECV socket buffer. This fixes
	the "only see 20 peers" problem. This is a side affect of using
	UDP for the status return.

6/20/88
	Support for hosts with multiple interfaces.  Minor updates to
	the ntpdc program; note that the format of the messages between
	the ntpd and ntpdc programs is different in this version than the
	last.  You should update both ntpd and ntpdc at the same time.

	New file ``ntp_sock.c''.  Tested with Ultrix 2.4 field test, and 
	4.3 BSD tahoe release.  Debug level can be adjusted by sending
	SIGUSR1 to increase and SIGUSR2 to zero the debug level.

5/17/88
	Changed peer structure alloactor to stop allocating a perm
	structure for non-peer relationships. This make the ntpdc
	output a lot more understandable.
	Installed faletick code.
	Installed work around to bug in Ultrix C compiler.
	The compiler has troubles converting unsigned longs to floats.
	This caused a lot of off by 2 second problems.
3/31/88
	The world is ALL different now.  The NTP protocols have had
	some major structural work.  This is the first rev that
	attempts to meet NTP version 1 compliance.  There are a couple
	of loose ends (faltickers code and clock slew rate) that
	are not finished, but should be RSN.  This release is to
	bridge the compatability with the old clock system.

	CHANGES:
	ntpsubs.c had a MAJOR bug in the tstamp routine.  Accuracy
	should be much better now.

	The ntp.conf file is much simpler.  List your precision
	and peers, the rest is automagic.

	The ntp/udp service mapping is now consitent.  No more hard
	coded 123s. 

	The math routines are more robust.  They now handle signed
	conversion of longs and shorts.

	The control structure of ntpd is radically different.  A peer
	relation is NOT setup for clocks at a higher stratum.  This
	reduces table clutter, but you lose the history of those
	requesters.

2/20/88
	Removed the median filter and replaced it with a minimum
	filter.  Experimentation by Dave Mills suggests this is
	a better way to track network clocks.  Changed status field based
	on updated RFC.

12/29/87
	Only believe samples were the round trip delay is positive.
	I recommend HIGHLY that you change tickadj in /sys/conf/param.c
	to equal 1 instead of 40.  This reduces the granularity of
	clock slewing from 4ms/sec to .1ms/sec.  This should suffice
	if your clock is less that 4.3 minutes per month. If this is
	the case get a new clock, increase the value, or live with
	periodic clock jumps due to setimeofday().  The basic problem is
	that adjtime() slews only with "tickadj" granularity.  That's
	argueably broken, but needs kernel mods to fix it.

12/17/87
	Added some of the changes from Greg Fowler and Ken Stone
	of HP labs.  This adds "hpux" compatability.  Ken and Greg
	also tighten up the "bestclock" determination so you
	don't end up tracking yourself. (thanks again)

	The Precision field in now correct, precision is the power
	of 2 indication of internal clock tics.  (ex. 60-HZ = -6)
	This is a constant for the machine and should be set in the
	ntp.conf file.

12/1/87
	Massive cleanup in the daemon code.  There was a BIG problem
	with "bestclock" peer calculation.  A clock of a lower type would
	be tracked if the delay to that clock was lower than the delay
	to the higher precision clock.  The peers listed in the ntp.conf
	files are marked as PERM.  This causes a ntp gram to go to these
	guys regardless of any recv activity. This eliminates the problem
	of a peer being down and not talking ot him when he comes back
	up because the activity indicator went to zero.  Using PERM
	entries creates a fixed overhead, use it with caution.
	There is the beginning of a second order filter that can be used
	to adjust the kernel tick rate.  More on that when it's done.
	The data structures have changed for queries.  Querying old
	clocks will cause problems.  Note - the NTP protocol has NOT
	changed, only the query hack.  The SET_THRESHOLD has been changed
	to be more reasonable with the max slew rate of 4.3BSD.  This
	will be relaxed when the second order stuff is working.

5/29/87

	All of the internal math is now done with doubles.  This removes
a lot of the hair and cost.  On vaxen the double yields 54(5) bits of
accuracy.  The NTP timestamps are 64 bits.  Converting to doubles
will cause the loss of some bits on ost machines.  This is not bad
since most machines don't have clocks that could track even the lower
16 bits of the NTP timestamps.

	NTP makes three choices on changing the local clock.
	1) If the local clock apperars to be off by more than
	WAYTOOBIG (1000.0) seconds, it refuses to do anything
	but fill up you log.
	2) If the local clock is off less than WAYTOOBIG but more
	than SET_THRESHOLD (2.0) a settimeofday will be done.
	3) If the clock is off less than SET_THRESHOLD an adjustime
	is done.

	Ntpd clears out the samples after every clock adjustment.
	This helped to prevent the filter from overshouting based on old
	data.
===========================================================================
Still cooking on the stove are:

	modify adjtime - it won't allow small adjustments.
		I may punt and put in a new adjtime that handles
		the second order stuff.

	making it handle broadcasted time like timed

	man pages

Any suggestions or help are ALWAYS appreciated.

Louis A. Mamakos  (louie@trantor.umd.edu)
mike petry (petry@trantor.umd.edu)
