ROADMAP FOR LINKTEST

The overly convoluted flow of control looks like:

The Web:
	<user> ->
Boss:
	-> www/linktest.php3 -> weblinktest -> linktest_control ->
Ops:
	-> linktest.proxy -> run_linktest.pl
Nodes:
	-> linktest -> elab_linktest.pl -> linktest.pl

Description of files...

Name:
	linktest.c.in, linktest.h.in
Description:
	A daemon that waits for LINKTEST events.
Where it runs:
	On nodes only. Invoked at boot time by rc.linktest
	(tmcd/common/rc.linktest) so that it is running before
	any events arrive.  Runs in the current directory.
What it does:
	After receiving the START event, forks linktest.pl
	to conduct tests. Waits for linktest.pl to exit or
	for a KILL event.
Who it should run as:
	experiment swapper

Name:
	elab_linktest.pl.in
Description:
	A wrapper which interfaces with Emulab config variables and passes
        them on as parameters to linktest.pl
Where it runs:
	On nodes only.  Runs in the current directory.
What it does:
	Invokes linktest.pl with Emulab-specific arguments.
Who it should run as:
	Invoked by linktest; therefore experiment swapper.

Name:
	linktest.pl
Description:
	A test suite for Emulab experiments.
Where it runs:
	On nodes only.  Runs in the current directory.
What it does:
	Parses the experiment link maps (ltmap, ltpmap)
	to reconstruct the topology and then conducts
	various tests for connectivity and link attributes.
	If errors are found, it saves them to a directory
	under tbdata for the experiment. It sends LOG and
	REPORT events to report on its progress and ultimately,
	a COMPLETE event when all tests are completed.
Who it should run as:
	Invoked by elab_linktest.pl; therefore experiment swapper.

Name:
	run_linktest.pl.in
Description:
	A script to run Linktest and report results.
Where it runs:
	Nodes or ops.
What it does:
	Wrapper for starting linktest remotely.  Sends initial START
	command and waits for report and status events.
	If errors were found, exit code is 1, else 0.
	Prints out contents of error files saved by Linktest.
	This script could be used by boss to run linktest when
	starting up the experiment.
	Important usage note: -q to skip the (time-consuming)
	bandwidth test.
Who it should run as:
	Experimenter either manually or as invoked indirectly from
	boss at swapin or during explicit web-page invocation.

Name:
	ltevent.c
Description:
	A program to either send an event or wait for an event.
Where it runs:
	On nodes by linktest.pl.in to inject events.
	On nodes or ops by run_linktest.pl.in to inject or extract
	events to/from linktest on the nodes.
What it does:
	Accepts command line arguments to either send or wait for
	an event.
Who it should run as:
	Experiment swapper when invoked by linktest.pl;
	experimenter when invoked by run_linktest.pl

Name:
	linktest.proxy.in
Description:
	A shim run on ops to run run_linktest.pl as the correct user.
Where it runs:
	On ops, invoked via ssh from boss as root.
What it does:
	Runs run_linktest.pl on ops as correct user with the correct groups.
Who it should run as:
	Root, changes to correct user.

Name:
	linktest_control.in
Description:
	A setuid-root wrapper script run on boss to communicate between
	web pages on boss and run_linktest (via linktest.proxy) on ops.
Where it runs:
	On boss.
What it does:
	Primary action script for running linktest from the web/DB server.
	Performs authentication and invokes run_linktest.pl on ops.
Who it should run as:
	Anyone, typically the non-privileged web user.

Name:
	weblinktest.in
Description:
	Yet another wrapper script, called by PHP code to invoke
	linktest_control on boss.
Where it runs:
	On boss.
What it does:
	Adds another layer of indirection for no apparent reason.
Who it should run as:
	Web user.
