1. What's IGI

IGI means "Initial Gap Increasing", it is a technique to measure available
bandwidth between two network end points. This package includes the normal
version implementation for this technique, root access is not need for this
implementation.

From IGI's implementation, we can also easily get the measurement for another
technique, which is called PTR (Packet Transmission Rate). This implementation
outputs both IGI value and PTR value (refer to section "3. Output" below).

For the details about IGI and PTR, please refer to the "Document" section in
IGI's homepage.


2. How to build and run IGI


(1). Build IGI
   
   	> make

   We have successfully built it on Linux 2.2.20, FreeBSD 4.3, and SunOS 5.5. 
   Comment/Uncomment the "DEFS" and "LIBS" lines in Makefile for different
   platforms.
   
(2). Run IGI

   IGI is executed on two end points of the network, one (igi_client) sends
   probing packets, the other (igi_server) records the time stamps when the 
   probing packet arrive. We call the former one as "src machine", and the 
   latter one as "dst machine".

   Need to emphasize: the probing direction is igi_client -> igi_server, you 
   must set it right to get what you want.

   On dst machine:

	./igi_server [-vdh]

	-v 	verbose mode
	-d 	debug mode (will print more message than verbose mode)
	-h 	Usage message.

   On src machine:

	./igi_client [-n probe_num] [-s packet_size] [-p dst_port]
		     [-m working_mode] [-f trace_file] [-vdh] dst_address

	-n 	set the number of probing packets in each probing phase.
	-s 	set the packet size of the probing packets in byte.
	-p 	indicate the dst machine's listening port. 
		This is optional, because igi_client can itself search for the
		port that the igi_server is using.
	-m 	working_mode (default: sequential):
		o. binary: 	use binary search to locate the turning point.
		o. fast:  	this method tries to achieve the best speed to 
		      	        get the final results.  It does not sleep, and
 		      	        use b_gap to adjust the source gap
		o. sequential: 	this just starts from a very low src gap, 
		      		sequentially increases it, until the src gap 
				is twice of the possible turning gap value.
		o. simple: 	this method simply assump that the turning 
				point is at the bottleneck gap, and just do 
				two probings: 
				1st: get the b_gap 
		      		2nd: probe on b_gap (turing point)
		      		It is not very accurate, but much faster.
	-f 	indicate the trace file name, which will record the packet
		information in way that matlab script can directly work on.
	-v 	verbose mode.
	-d 	debug mode.
	-h 	Usage message.

	"dst_address" can be either IP address or hostname.
	

3. Output

Here is an output example in verbose mode. The [* *] is the explaination for 
the output, hope it does not make it more confusing :).

The debug mode will output more message, and mainly for the purpose of my
debuging (of course). It is not explained here. But if you are really curious,
please forward your questions to hnn@cs.cmu.edu.

*. client side output (verbose mode):

	> ./igi_client -v -m fast gs274.sp.cs.cmu.edu
	src addr: 128.2.198.120
	dst addr: 128.2.191.38
	we get str: READY
	probing_port = 10242
		[* basic probing setup information			*]

	probe_num = 60 packet_size = 500 delay_num = 0 
		[* statistics for single probing phase, "delay_num" is  *]
		[* the loop count used to generate the source gap	*] 
	from dst: data_size = 720 total_count = 60 
		[* some info for the feedback from dst, "data_size" is 	*]
		[* the size of data got from dst, "total_count" is 	*]
		[* number of probing packet the dst receives 		*]	
	avr_src_gap = 0.000020 
	avr_dst_gap = 0.000460 
		[* src_gap and dst_gap for this phase of probing	*]

	probe_num = 60 packet_size = 500 delay_num = 345 
	from dst: data_size = 720 total_count = 60 
	avr_src_gap = 0.000318 
	avr_dst_gap = 0.000510 

	probe_num = 60 packet_size = 500 delay_num = 414 
	from dst: data_size = 720 total_count = 60 
	avr_src_gap = 0.000369 
	avr_dst_gap = 0.000445 
		[* all the above only appear in the verbose/debug mode	*]

	Bottleneck Bandwidth: 8728229.650137 
	Competing  Bandwidth: 240579.350569 
	Packet Transmit Rate: 8984986.477440 
	Available  Bandwidth: 8487650.299567 
		[* THE final measurements, unit: bps (bit/second). 	*]
		[* Bottleneck Bandwidth: the bottleneck link capacity	*]
		[* Competing Bandwidth: the throughput of background   	*]
		[*	traffice					*]	
		[* Packet Transmission Rate: the "PTR" value in the JSAC*]
		[*	paper, the probing rate of the packet train at	*]
		[*	the turning point				*]
		[* Available Bandwidth: bottleneck_bw - competing_bw	*]

	fast probing time : 0.321689
	fast probing count: 3
	ending gaps: [ 0.000369 0.000445 ]
		[* statistics for the whole probing procedure		*]

*. server side output (verbose mode):

	> ./igi_server -v
	server port = 10241 
		[* probing server listening here 			*]
	get new connection 
	src_ip_str = 128.2.198.120 
	dst_ip_str = 128.2.191.38 
	waiting for START msg
	probe_num = 60 
	create a new filter item
	listening port = 10242 
		[* this UDP port number that client is going to send	*]
		[* probing packet to 					*]
	come into get_packets 
	start sending back data
	start sending back data
	start sending back data
		[* except the ip addresses and port numbers, the other 	*]
		[* information is not important unless you want to know *]
		[* how the source code works 				*]


4. Bug report

Please send any bugs to hnn@cs.cmu.edu.

Mon Jul 22 17:11:53 EDT 2002