			Pathneck (version 1.2)
    	   [the copyright note is at the end of this file]

Quick Start 
===========

	$ make / make sun / make bsd
	[use "make" for Linux & MAC, use "make -f Makefile.sun" for Solaris, 
	 and "make -f Makefile.bsd" for BSD. After this step, you should get 
	 pathneck & get-choke now.]

	$ su
	[change to root]

	# ./setroot.sh 
	[set root id for pathneck, so that a normal user can run it]

	$ exit 
	[go back to normal user]

	$ ./pathneck -o <dst>

Pathneck
========
The output from "pathneck -h" is as the following:

----------------------------------------------------------------------
Pathenck V1.1 Usage: 

    	./pathneck [-e end_pkt_num] [-l udp_pkt_num] [-s pkt_size] 	
		   [-i self_ip] [-y delay_num] [-coptx] [-dvh]		
		   <dst_ip | dst_hostname>				

[probing configuration]
	-e end_pkt_num	number of measurement packets [30]		
	-l udp_pkt_num	number of load packets [60]			
	-s pkt_size	the load packet size in byte [500]		
	-c		use ICMP probing packets, [UDP]			
    	-p 		use the planetlab raw socket interface [0]	
	-y delay_num	specify the src gap within the packet train [0]	
	-i self_ip	sproof the probing pkt source ip [not set]	

[output setting] 
	-x		enable the DNS lookup [0]			
	-o 		enable on-line detection processing [0]		
	-t		dump the packet sending times [0]		
	-d 		debug mode [0]					
	-v 		verbose mode [0]				
	-h 		print this message [0]				
----------------------------------------------------------------------
    Here the "[]" denotes the default setting for the options.

    Pathneck needs root permission to send out raw packets.  setroot.sh 
    (needs root to run) can set the owner id of pathneck with "root", 
    then you will be able to run it with a normal user account

    NOTE1: The "-l" is critical for the tool to work correctly, the value 
    depends on the access link capacity and the probing host CPU speed.  
    Currently, the setup is emphirical. Some typical value:
	o. 100Mbps access link and 400MHz CPU: use the default value
	o. otherwise, eg, 10Mbps access link, or < 400MHz CPU: use "-l 20"

    NOTE2:
    The current version will only detect bottleneck for a path where we can 
    detect at least 4 gap values.

Example
-------

    o. ./pathneck -l 20 -cx yahoo.com
       
       use a 20-packet probing train, probing packets are ICMP ECHO packet,
       and enable hostname lookup

    o. ./pathneck yahoo.com

       the configuration uses the default values: using 500B UDP probing 
       packets, 60-packet probing train, will not do hostname look up.

    o.  $ ./pathneck -xo 81.161.208.1

    [The output is the following:]

    1102870265.142626 81.161.208.1 500 60 0

    00   5.512   128.2.223.254    250   2989 . 959.612 ub GIGROUTER.NET.CS.CMU.EDU
    01   1.518      128.2.0.12   2989   2989 .  80.293 lb CORE0-VL1000.GW.CMU.NET
    02   4.385    128.2.33.225    380   2989 . 629.933 lb HYPER-VL501.GW.CMU.NET
    03   1.630  192.88.115.181   2748   2748 .  87.336 lb bar-cmu-ge-4-0-0-0.psc.net
    04   1.878    192.88.115.5   2742   2748 .  87.526 lb minime-ge-0-1-0-0.3rox.net
    05   1.991  199.239.216.13   2757   2748 .  87.049 lb pos4-1-1-0.a01.pitbpa05.us.ra.verio.net
    06   2.366  129.250.24.142   2379   2748 . 100.845 lb ge-0-3-0-4.r01.pitbpa05.us.bb.verio.net
    07  11.980   129.250.5.123   3125   3125 .  76.778 lb p16-1-1-2.r21.nycmny01.us.bb.verio.net
    08  11.862    129.250.3.49   3237   3125 .  74.121 lb p16-7-0-0.r04.nycmny01.us.bb.verio.net
    09  11.851 209.244.160.149   3118   3125 .  76.948 lb so-10-1.core2.NewYork1.Level3.net
    10  11.716       4.68.97.1   3252   3125 .  73.800 lb ae-1-51.bbr1.NewYork1.Level3.net
    11  81.421    4.68.128.105   2995   3125 .  80.133 lb 4.68.128.105
    12  93.031  212.187.128.29   3249   3125 .  73.849 lb so-3-0-0.mp2.Frankfurt1.Level3.net
    13  93.277  195.122.136.39   3123   3125 .  76.848 lb ge-11-0.ipcolo1.Frankfurt1.Level3.net
    14 135.246     62.67.32.66   8994   8994 2  26.684 ub 62.67.32.66
    15 132.498   194.12.224.10   9489   8994 .  25.292 lb 194.12.224.10
    16 157.113  194.12.224.226   5102   8994 .  47.039 lb rvn4fa0-0-6.lirex.net
    17 148.108    194.12.255.2  14098  14098 3  17.023 ub lirex-m-net.lirex.net
    18 155.665 193.110.223.249  72633  72633 1   3.304 ub fw-e0.mnet.bg
    conf = 0.806 0.653 0.362

    rtt = 167.972 ( 81.161.208.1 )

    [Reading:]
    ----------
    The 1st line: 
    	probing_start_timestamp (local time), dst_ip, load_pkt_size, 
	load_pkt_num, delay_num

    The main body (the 7-column thing):
    1st column:   the index number
    2nd column:   the RTT to that hop
    3rd column:	  hop IP address
    4th column:	  raw gap measurement (in microsecond)
    5th column:	  "smooth"ed gap values (in microsecond), they are also 
    		  the input for the dynamic algo
    6th column:   choke points, "." represents non-choke point, "1", "2",
    		  "3" refers to the choke points (output at most 3), ordered
		  by the confidence value.
    7th column:   bandwidth bound estimation, unit: Mbps
    8th column:   ub->upper bound, lb->lower bound, uk->unknown (see the
	          pathneck paper section 2.3.3 for the detail.)
    9th column:   hop hostname

    The "conf" line:
    	the confidence values for the choke points detected, in the order of
	"1", "2", "3".

    The "rtt" line:
    	the RTT to the destination, dst_ip, and the hop count *from* dst to
	source (i.e., return path, not forward path).

    [Options:]
    ----------
    "$ ./pathneck -o 81.161.208.1" will not output the last column 
    "$ ./pathneck 81.161.208.1" will only output the first 4 columns

Scripts
=======

The script/ directory includes the sCRIPTS THat implements the algorithm used
in SIGCOMM'04 paper. They are mainly useful for large scale measurement:

	$ ./pathneck [-o] yahoo.com (10 times) >> tmp.txt
	$ ./script/get.sh <root_dir> tmp.txt > tmp.sum

	[a complete example script is in script/run.sh. Before using run.sh,
	make sure the "root" variable in this file is set correctly. ]

When doing large scale measurement, "-o" can increase the CPU load of the
probing nodes, and thus is not recommended. The script/get.pl (used by
script/get.sh) has the off-line processing code to run the same dynamic
algorithm to detect choke points.

Example
-------

    $ ./run.sh 81.161.208.1

    [This command will create a 2 files: 81.161.208.1.txt & 81.161.208.1.sum.
     The beginning part of 81.161.208.1.sum looks something like:]

     sum: 0.88 08 07  67161 18 193.110.223.249
     sum: 0.50 08 04   6495 14 62.67.32.66

     info 1102870355.254499 81.161.208.1 500 60 0

     623   3125        5.301 128.2.223.254        0  76.800 ub 128.2.223.254
     3125  3125        1.427 128.2.0.12           0  76.800 lb 128.2.0.12
     1502  3125        3.043 128.2.33.225         0  76.800 lb 128.2.33.225
     3746  3242        0.924 192.88.115.181       0  74.028 lb 192.88.115.181
     3242  3242        1.166 192.88.115.5         0  74.028 lb 192.88.115.5
     3380  3380        1.283 199.239.216.13       0  71.006 lb 199.239.216.13
     3500  3380        1.159 129.250.24.142       0  71.006 lb 129.250.24.142
     3114  3121       11.901 129.250.5.123        0  76.898 lb 129.250.5.123
     3121  3121       11.894 129.250.3.49         0  76.898 lb 129.250.3.49
     3123  3121       11.761 209.244.160.149      0  76.898 lb 209.244.160.149
     3119  3119       11.759 4.68.97.1            0  76.948 lb 4.68.97.1
     2995  3119       81.332 4.68.128.105         0  76.948 lb 4.68.128.105
     3247  3119       92.817 212.187.128.29       0  76.948 lb 212.187.128.29
     3002  3119       93.312 195.122.136.39       0  76.948 lb 195.122.136.39
     3998  3998  [3] 141.280 62.67.32.66          0  60.030 ub 62.67.32.66
     7994  3998      132.906 194.12.224.10        0  60.030 lb 194.12.224.10
     874   874   [2] 165.380 194.12.224.226       0 274.600 uk 194.12.224.226
     372   874       164.132 194.12.255.2         0 274.600 lb 194.12.255.2
     65958 65958 (1) 164.503 193.110.223.249      0   3.639 ub 193.110.223.249
     conf = 0.987 3.574 0.220

     rtt = 184.383 ( 81.161.208.1 )

    ... (followed by 9 more "info ... rtt" probing bodies)

    [Reading:]
    ----------
    The "sum:" lines shows the choke points detected based on the 10 probings,
    ordered by their position on the path. The first line corresponds to the 
    bottleneck.

    The "sum:" line has the following format:

    sum: [d_rate] [#appear] [#detected] [avg_gap] [hop#] [ip]
	
    Here 
    	d_rate 	= #detected/#appear
      	avg_gap is the average gap values measured in the 10 probings
	hop# 	is the position of corresponding router on the path

    NOTE: the summary info are based the "dominant route", i.e., the route
    which appears the most number of times during the 10 probings. If the
    dominant route appear less than 5 times, we do not compute any summary 
    info.

    The following probing bodies is pretty similar with those output from
    pathneck's raw probing, except that the (raw_gap_value, post_processed_gap,
    and the choke point label) is at the first 3 columns.

    [MISC:]
    -------
    o. there is no difference between "[]" & "()"
    o. the different output format between run.sh and pathneck is simply 
       because I run out of time to clean up the script code. Hopefully I can 
       do it in near future.
    o. the RTT measurement doesn't work on planetlab --- haven't figure out 
       the reason for not sending ICMP ECHO packet. Let me know if you know
       what I am doing wrong.

 
Contact
=======

Please send any question, comment, and bug report to 
Ningning Hu (hnn@cs.cmu.edu).


/****************************************************************************
 *  Pathneck: locating network path bottlenecks
 *  Copyright (C) 2004
 *  Ningning Hu and the Carnegie Mellon University
 *
 *  This program is free software; you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation; either version 2 of the License, or
 *  (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License (in the COPYING file) for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ****************************************************************************/
