createDist v0.1
---------------

Table of Contents:
I. 	Possible Input and Output
II. 	How it Works
III. 	Commandline Options


This program is used to count packet sizes, calculate 
distributions from the results of the counters and produce 
input for the enhanced Linux Kernel Packet Generator (see
http://www.net.in.tum.de/~schneifa/proj.html#lkpg for details). 

In addition I used this application for some measurements where I needed
additional load per packet. This was resulting in the two options -c and
-z.

For installation instructions, please refer to the file INSTALL. If you
experience any problems please send me an email: fabian_at_net.in.tum.de
(substitute "_at_" through "@").



I. 	Possible Input and Output
---------------------------------

The following types of input and output are designated:

sizes:	This is simply a file containing numbers which tell the packet
	size. Those number can occur arbitrarily often in the file, and it
	can be of any length. This could be the input from some sort of 
	network data analysis tool like e.g. ipsumdump or tcpdump. 

dist:	Such a distribution consists of lines like: 
	<pkt_size> <#incidences>. You can derive this one simply from the
	sizes by counting the occurences of the packet sizes.

procfs:	This format can directly feeded to the enhanced version of the
	Linux Kernel Packet Generator.

The following additional input formats are possible:

trace:	The input is now a trace file in pcap format. The size of every 
	packet in the stream will be counted. 

live:	This means a capturing session is established (root priviledges are
	needed for this one), and the packet sizes of the online captured
	packets are counted.

The Input and Output type is defined by the -I and -O options. With
sizes as well as dist as input it is possible to supply multiple files
concatenated together as input.



II. 	How it Works
--------------------

Depending on how your chosen input different actions have to be performed.
Thus the mission is to obtain the distribution as explained for dist. From
that point the distribution can displayed, or transformed to the output
needed by the enhanced Linux Kernel Packet Generator. If the requested 
output type is sizes, then this program produces packet sizes according to
the distribution and acts like the generator. For reading the packet sizes
it is either necessary to read in a text or pcap trace file and count the
packet sizes or the network layer has to be accessed using the libpcap. 
For both pcap based cases---reading trace file and live capturing---the
callback function simply discards all non-IP packets or counts the length
of the IP packet.  



III. 	Commandline Options
---------------------------

GENERAL options:
    -v		verbose output
		Print status information, progress information, warning
		output, packet counters, pcap version information and 
		statistics to standard error.
    
    -z [int]	do additonal compress [level] on any packet
		This is not useful at the moment, because the compression
		initialisation is done for every packet, thus resulting in
		an useless waste of resources.
		
    -c [int]	do additonal copy operations [amount] on any packet 
		You can add very fine-grained per packet load with this on
    
    -h		show help

    -n int	number of pkt_sizes to generate (default: 10000000)
		This applies only if sizes is chosen as output type.


INPUT/OUTPUT options:
    -i file	specify input file
		Instead of reading from standard in read from the specified
		file
    
    -o file	specify output file 
		Instead of writing to standard out write the output to the 
		specified file
    
    -I dist|procfs|sizes|trace|live 
		specify input type (default: dist)
    
    -O dist|procfs|sizes
		specify output type (default: procfs)
    
    -fs char	specify field seperator character (default: space)
		Applies to type dist only
    
    -if string	specify capturing interface
		This in necessary when doing live capturing.
    
    -sl int	specify capturing snaplength
		See man pcap for details on this on.
    
    -f string	specify capturing filter
		See man tcpdump for the filter description language.
    
    -s 		surround procfs output by pgset()'s
		Useful when using the output with the skript supplyied in 
		pktgen.txt from the Linux Kernel Packet Generator.

DISTRIBUTION options: 
(read section I. How it works from http://www.net.informatik.tu-muenchen.de/
~schneifa/sources/pktgen-lkpg-dist-0.1-howto.txt as prerequisite)

    -max int	specify max_pkt_size (default: 1500)
		Sets the maximum regarded packet size.
    
    -prec int	specify precision/resolution of arrays for procfs 
		(default: 1000)
		The size of the arrays used for generating the different 
		packet sizes is set.
    
    -hwidth int width of histo bucket (default: 20)
		Width of the bins	
    
    -outlb double    
		when over percentage -> pkt_size is an outlier (default: 0.0020)


Happy distribution building

02.10.2005 Fabian Schneider