README - TESTING
================

FILE NAME CONVENTIONS
---------------------

Nprobe on-line will create a directory for each monitoring run named 
"OUTDIR/HOSTNAME.xxxxxxxxxx" where:
	
	OUTDIR is a path specified by the constant OUT_DIR (output.h) or using 
	 the command line option -d<dir>
	HOSTNAME is the name of the monitoring machine
		and
	xxxxxxxxxx is the run commencement time in epoch seconds.

In order to keep log files manageable Nprobe cycles to a new log file as each 
reaches a predetermined size (specified by the constant REPORT_FILE_SZ 
- output.h). Log file names are of the form "CHANNEL.rep.xxxx" where:

	CHANNEL is the channel identifier of the writing Wan process 
		('A', 'B', ...)	
	xxxx is the cycle number

Error packets are dumped in their entirety to files named "CHANNEL.dump.xxxx"
 - rep and dump file cycles are synchronised in order to aid association of 
error packets in dump files and the corresponding rep file cycle. Should the 
dump file size reach REPORT_FILE_SZ (output.h) a file cycle will also be 
triggered.

Owan (the off-line extraction code) takes a tcpdump-format file as its input. 
Log files generated by owan will be placed in the source directory of the processed file - or as specified with -d<dir>.

Error dump files are also in tcpdump format, but written with a non-standard 
interface type of IF_NPROBE. They can in turn be used as input to owan, which 
is useful when polishing code to eliminate data-extraction errors.

Packet records in error dump files have the LLC/MAC header overwritten with an 
error code and some error-specific data - this, together with the non-standard 
interface type means that they can not be read with a standard tcpdump. The 
program tdump (an Nprobe aware version of tcpdump-3.4-5) is provided to allow 
error dumps to be read. An invocation of the form:

		tdump -r CHANNEL.dump.xxxx

will print as tcpdump, but will present error information in lieu of LLC/MAC 
headers. An invocation of the form:

		 tdump -r CHANNEL.dump.xxxx ether[4] = errno

will filter and print only those packets dumped with the specified error (the 
error packet type and frequency contained in a dump log can be ascertained by 
running wread on the corresponding `rep' file, which will report erors as part 
of the log meta-data).

Intermediate and result files generated during analysis have names of the form:
"LOGFILE(s).CL-ARGS.FUNCTION" where:

	LOGFILE is the `rep' file(s) processed
	CL-ARGS records any command-line arguments to the analysis script
		and
	FUNCTION indicates the type of generated file contents

this results in unwieldy file names, but helps keep track of the associations 
between log files, and the analysis, and its parameters, which has been 
carried out.


TESTING BUILDS
--------------

Data-extraction code can be tested by `make owan_test', which will unpack and 
process a small tcpdump file provided. Wread (`rep' file printer) can be 
tested by `make wread_test' - which usefully also serves to ensure that 
data-extraction is generating feasible results).

Data analysis can be tested by `make analysis_test' which should run two 
analysis scripts consecutively on a test log file provided. 

Testing will require your PATH to include the appropriate directoried - see 
docs/README_BUILDING and docs/MAKE_TARGETS for how to set your PATH 
appropriately.

Should you wish to test the build on more comprehensive or larger tcpdump files
or thier derivatives the *_TEST_DATA paths in Makefile.paths can be ammended 
accordingly.

 
 
