			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

    NOTE: 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"

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:]

    1090621158.764064 81.161.208.1 500 60 0

    00   0.991   128.2.223.254   2990   2990 . GIGROUTER.NET.CS.CMU.EDU
    01   1.231      128.2.0.12   3869   2990 . CORE0-VL1000.GW.CMU.NET
    02   2.134    128.2.33.225    125   2990 . HYPER-VL501.GW.CMU.NET
    03   1.348  192.88.115.181   3494   3491 . bar-cmu-ge-4-0-0-0.psc.net
    04   1.472    192.88.115.5   3491   3491 . minime-ge-0-1-0-0.psc.net
    05   1.475  199.239.216.13   3744   3624 . pos4-1-1-0.a01.pitbpa05.us.ra.verio.net
    06   1.587  129.250.24.142   3624   3624 . ge-0-3-0-4.r01.pitbpa05.us.bb.verio.net
    07  13.333   129.250.5.123   3740   3624 . p16-1-1-2.r21.nycmny01.us.bb.verio.net
    08  13.326    129.250.3.49   3492   3493 . p16-7-0-0.r04.nycmny01.us.bb.verio.net
    09  13.320 209.244.160.149   3493   3493 . so-10-1.core2.NewYork1.Level3.net
    10  13.432   64.159.17.129   3625   3625 . ae-0-55.bbr1.NewYork1.Level3.net
    11  84.263    4.68.128.105   3742   3625 . as-0-0.mp2.London1.Level3.net
    12  93.623  212.187.128.29   2748   2872 3 so-3-0-0.mp2.Frankfurt1.Level3.net
    13  93.744  195.122.136.83   2872   2872 . ge-11-1.ipcolo1.Frankfurt1.Level3.net
    14 139.711     62.67.32.66    125   2872 . 62.67.32.66
    15 129.839   194.12.224.10   8494   2872 . 194.12.224.10
    16 152.446  194.12.224.226    123   2872 . rvn4fa0-0-6.lirex.net
    17 143.946    194.12.255.2   9248   9248 2 lirex-m-net.lirex.net
    18 144.691 193.110.223.249  49721  49721 1 fw-e0.mnet.bg
    conf = 0.814 0.689 0.262

    rtt = 151.534 ( 81.161.208.1 ) 20

    [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:   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: 1.00 10 10  48675 18 193.110.223.249
    sum: 0.70 10 07   7124 15 194.12.224.10
    sum: 0.60 10 06   5553  1 128.2.0.12

    info 1090621916.349008 81.161.208.1 500 60 0

    1996  1996        2.452 128.2.223.254        0 128.2.223.254
    7486  6989  [3]   0.962 128.2.0.12           0 128.2.0.12
    6989  6989        1.704 128.2.33.225         0 128.2.33.225
    7481  7481        0.956 192.88.115.181       0 192.88.115.181
    7496  7481        1.185 192.88.115.5         0 192.88.115.5
    3623  3623        1.304 199.239.216.13       0 199.239.216.13
    3369  3623        1.556 129.250.24.142       0 129.250.24.142
    3858  3623       13.179 129.250.5.123        0 129.250.5.123
    3482  3482       13.173 129.250.3.49         0 129.250.3.49
    3234  3482       13.166 209.244.160.149      0 209.244.160.149
    3746  3618       13.524 64.159.17.129        0 64.159.17.129
    3618  3618       84.229 4.68.128.105         0 4.68.128.105
    3240  3240       93.722 212.187.128.29       0 212.187.128.29
    2614  2614       93.720 195.122.136.83       0 195.122.136.83
    873   2614      139.180 62.67.32.66          0 62.67.32.66
    8743  8743  [2] 128.665 194.12.224.10        0 194.12.224.10
    9618  9618      141.903 194.12.224.226       0 194.12.224.226
    11370 11370     140.775 194.12.255.2         0 194.12.255.2
    52342 52342 (1) 142.269 193.110.223.249      0 193.110.223.249
    conf = 0.783 0.701 0.714

    rtt = 151.767 ( 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
 ****************************************************************************/
