*****************************
For updated information, see:
  http://www-rp.lip6.fr/~latapy/Radar/
**************************************

-------
Outline
-------

tracetree measures an ego-centered view of the IP topology
around the machine running it, in a traceroute-like manner
but by probing backwards towards a set of destination in a
way that produces a tree (to avoid redundancy and reduce
network load).

It was developped for research purposes only, and may cause
severe network trouble; read below.

It was developped for Linux; porting it to other platforms
may require some work.

We provide below the basics for running it and understanding
its parameters; for more details, see the code.

-----------
Quick start
-----------

1. Compile tracetree: ./make.sh
2. Create a file named 'data' and containing a few IP
   addresses (one per line)
3. Run: ./tracetree

You may redirect the outputs to a file, in particular the
standard error:
./tracetree 2> err

--------------------
Input and parameters
--------------------

Usage:
 ./tracetree [input_file [output_file [ttl0]]]

 - input_file: a text file giving on each line a
   destination IP address, with possibly its
   estimated distance (separated by a space);
   default: "data";
 - output_file: the file where raw data is written
   (see below); default: "rawdata";
 - ttl0: the default (if unspecified in the input_file)
   estimated distance; default: 10.

WARNING: input_file is changed by tracetree; see below.

Some parameters are #defined in the source code:
tracetree.c:
 - TIMEOUT: delay (in miliseconds) after which the answer to
   a probe is no longer expected; default: 2000;
 - MAX_TTL: new estimated (and maximal) value of the distance
   to a destination when it was underestimated; default 30;
 - TTL_DEFAULT: the default estimated distance to use if none
   was provided in input_file and ttl0 was unspecified;
   default: 10;
 - IS_TRACEROUTE: forces traceroute-like behaviour if set
   to 1;
 - SEND_ALL_STRATEGY, READ_ALL_STRATEGY, and
   SEND_ALL_READ_ALL_STRATEGY change the packet sending and
   reading strategy; see source code.
network.h:
 - MSG: data part of probe packets. We recommend you change
   it to your e-mail address for contact purposes in case of
   problem.

------
Output
------

The standard output is a series of triples (each on a line)
of the form 'x y z' meaning that the IP address 'x' was seen
at TTL 'y' on a path towards 'z'. If we reached a timeout
then 'x' is a star '*'.

The output is a tree if one considers each pair (x,y) (with
the notations above) as a node, and considers that the father
of this node is (x,y-1).

Various informations are displayed on the standard error,
documented in the source code.

In addition, the program writes raw information, i.e. the IP
packets sent and received, as well as the time at which this
occurred, in a file named 'raw'; this may be useful to obtain
more information than provided by standard output/error (like
RTT for instance), without launching new measurements.

Finally, the file 'data' used as input is replaced by a new
file with the same format in which each distance is updated
according to what was observed during this run of
tracetree.

--------------------------
Known problems/limitations
--------------------------

. if ICMP packets are filtered on your network, then you
  will obtain trivial outputs (basically, only stars '*');
  this is normal (run the program elsewhere).

. tracetree implements no control on the sending rate of
  packets, which may be a problem in some cases; use it
  carefully;

. if the program encounters a problem and stops, it will
  most probably erase the 'data' file;

. current version uses ICMP ECHO probe packets only;

. it does not make DNS queries, and thus IP addresses must
  be provided as destinations (not machine names);

. although it has been massively tested with success on
  various Linux machines, it has not been tested on other
  platforms, and making it portable would need some work;

. this program was written with some specific uses in mind
  and for research purposes; you should not run it if you do
  not understand how it works; if it is not used properly,
  it may cause serious damages and disturbances, not only
  on the machine running it but also on the destinations and
  on the networks; it is provided 'as-is', with no warranty
  of any kind. Please be careful when you use it.