						March 15, 1995

VERSION:	0.92	(first BETA release)

Changes since 0.91

  Minor nits; no major complaints were received.
  Tested on SGI/irix5.3/sgi-cc

Changes since 0.90 (first ALPHA release):

  This package now uses autoconf 2.1.
  ansi-C is sufficent; gcc is not required
  compiles on SGI machines under irix5.2 and native cc

  Run-time configuration of analysis parameters is supported.  See
  pd_config.c for 'documentation'.  CONFIG-badclock is an example file
  for use with machines with system clocks that lose/gain time a lot.
  It should be copied to m/foo/CONFIG before running crunch-data.-

This is the file README from time-surveying-src.tgz.  A copy of my
doctoral thesis is available as time-surveying-doc.tar.  There is no
documentation at the moment besides this file.

THIS IS A BETA RELEASE.

This program analyzes log messages from a modified NTP daemon.  It
produces files for a plotting program that allow the user to view
synchronization behavior.

To use the time-surveying package, you must do several things:

1.  Obtain and install the following programs: perl, gzip, xplot.  If
you have gcc the program will use inline functions and probably be
faster.

perl, gzip and gcc are available from the FSF.

xplot is available as thyme.lcs.mit.edu:pub/xplot-0.79.tar.gz

2.  Get xntp3.4h or later.  Compile with GDT_SURVEYING defined in
Config.local.  A patch to define this is included as PATCH-config.local.

To compile xntp3
  untar xntp3.4h or later version

  make Config.local
  patch < PATCH-config.local
  make

NTP will now produce lines like the following:

  Sep 28 15:18:32 marengo xntpd[8219]: observation: time 2989768712 128.4.1.2 off 0.007471 delay 0.043777 error 0.000977 rsadj -0.356126

3.  Arrange to capture log messages from the ntp daemon, with a line
like in syslog.conf:
daemon.debug					/var/adm/ntp-messages
If you defined LOG_NTP=LOG_LOCAL2, then this should be local2.debug
Arrange to rotate the ntp logs (I recommend daily).

4.  Unpack this distribution in the directory "~/time-surveying".  If
you put it someplace else edit the file sub-rsadj.pl.

Build the 'pd' program (cd to ~/time-surveying/src and run
configure and then make).

This has worked on
	SUN	sparc-sunos4.1.2-gcc
	SUN	sparc-sunos4.1.4-gcc
	SGI	mips-irix5.2-cc
	SGI	mips-irix5.3-cc
	DEC	mips-ultrix42-gcc

If it doesn't compile under your system, please find out why and send
me a fix, or a bug report if you can't fix it.  I won't accept
machine-specific fixes that don't use the autoconf mechanism.
Previous versions of this have run under i386-NetBSD-gcc; this should too.

A directory will automatically be made for each host you monitor:
	~/time-surveying/m/$hostname

Customize get-data if necessary, to obtain the logs.
It looks in /usr/adm for 'ntp-messages'.
Improvements (such as reading how to deal with each host out of a
configuration file) are welcome; please mail them to gtroxel@bbn.com.

Run
	get-data hostname

~/time-surveying/m/hostname should now have D.941020.gz or something
like that.

Run
	prep-data hostname
Now detailed.hostname, hourly.hostname, and stray.hostname should
appear in m/hostname

Then prep-data will automatically run

	crunch-data hostname

Now
	LOG, PARAM-*, and xplot.* should appear

Run
	doxp hostname

You should get some xplot windows, with various graphs.
A short explanation of the graphs:
frequency: ntp's frequency estimates, and those produced by pd
rsadjresid_integrated: view of the value of the system clock with
	respect to the 'hindsight' view of time
poffset_integrated: view of the remote clock (NTP means NTP's system
	offset) with respec to the hindsight view of time
poffset_piecewise: as above, but with multiple hindsight views
aoffset: actual offsets recorded by NTP
clock: index of current sys.peer (see LOG for values)
	
The colors indicate whether a data point was kept throughout the
analysis or marked 'invalid' for some reason:
	white	kept
	green	high delay
	red	high-variance group of points
	blue	high variance with respect to small group
	yellow	high variance with respect to large group

You should add the X resource
	xplot*geometry: =1148x896+0+0
 or something similar to make it take up the whole screen; it sizes
subwindows automatically from the geometry specification.  If you use
titlebars, you will probably want to turn them off at least for xplot.

To see the data from hostname to ip address w.x.y.z:
	doxp hostname raw.w.x.y.z

To control the pd program, make a file CLOCK_CONFIG in a host's
directory.
The flags field is 1 to be included in the integrated calculation, and
2 to suppress writing data.  Offset is a systematic offset to be
removed before processing.
#ip addr	flags	offset
18.26.0.128	1
128.4.1.2	1
130.43.2.2	1	-15.2

Example data is in time-surveying/m/aardvark.  You should be able to
run prep-data and crunch-data and produce output files (LOG, PARAM*,
xplot*).

To get estimates of systematic offsets among remote clocks, examine the
output file PARAM-integrated.  The following output indicates that
130.43.2.2 has an offset of roughly -15.5 ms relative to 128.4.1.2,
and that the rms error of the samples with respect to the estimate was
approximately 1 ms for each clock.

aging 0.000000 ppm/day freq 14.621288 14.621288 ppm
Run 0	23.156765 s
[      128.4.1.2] # 0 offset   3.720 ms rms error 1.019 ms weight 9.841e-01
[     130.43.2.2] # 1 offset -11.804 ms rms error 0.965 ms weight 7.754e-01


5. Openloop control

To use this feature, you need to apply the patch in
PATCH_3.4h_OPENLOOP to xntp3.4h (or future versions).  Both xntpd and
xntpdc are affected by this patch, so you must compile everything
after the patch is installed.  This patch may not work on all
architectures.  Bug reports/fixes are welcome.
The file PATCH_3.4m should be applied to xntp3.4m or later.

pd will calculate the oscillator frequency and phase, and produce a
command (in PARAM-integrated) that can be conveyed to a running daemon
to allow it to coast on the estimates, such as the following line.
	openloop 1 2991557305 1.331826 8.013895 0.000000
You will need to have a controlkey set up, and then run xntpdc and
give it the openloop command.

pd has an option (p) to 'predict' rather than 'analyze'.  This changes
the behavior subtly; the focus is on producing estimates that are
useful for predicting the future rather than analyzing the past.

pd has an option to do simulation of schemes to control the local
clock by computing estimates and conveying them to the daemon
periodically, as well as other options.

To understand the available options, see main() in src/pd.c.

I am happy to accept bug reports and patches via email, but I
cannot provide support.  I hope to write documentation at some point,
but I'm not sure when that will be.

	Greg Troxel
	<gdt@bbn.com>

