[Scamper-dev] scamper code review

[Matthew Luckie]

usage: scamper [-46l] [-w waitbetween] [-p port]
               [-a attempts] [-h hoplimit] [-t timeout]
               [-o outfile] list

i'm going to try and define `correct behaviour' of scamper based on how it
should work.

scamper sends a UDP probe every 50ms (by default, configurable with
-w) that is designed to solicit either a TTL expired message (from a
router in the path) or a port unreachable message (from the host we are
tracerouting to).  scamper will not send faster than it has been
instructed, so it will not send another probe even if it receives a
response to a `current' probe in under 50ms

scamper is passed the list of addresses to probe, contained in a file, as
a mandatory parameter on the command line.  scamper maintains a linked
list of addresses (in a struct trace) that it is currently tracerouting to
in memory, ordered by when it started to traceroute that address.  each
trace struct has a pair of timestamps in it used to figure out if the last
probe sent has timed-out.  the default timeout is 5 seconds, but
configurable with -t

scamper will try each hop twice before recording a null address in the
path.  this can be configured with -a.  scamper sends each probe for a
path to a unique UDP port, so that it can distinguish the exact hop we are
getting a probe for, and which attempt on the hop we tried.
port    = udp_dport + ((ttl-1) * attempts) + attempt;

scamper will probe the path until
 - it detects a loop (this can be disabled with the -l flag)
 - it gets a port unreachable from the host we are tracerouting to
 - it has tried 32 hops but not got to the destination (configurable with
   -h).
 - it gets an ICMP destination unreachable message from an intermediate
   router that is something like !N / !P / !A / !X etc

there are two output routines provided with scamper.  the traceroute-style
output and a first stab at a binary file format.  both of those are
sufficiently documented.  by default it uses the traceroute-style output,
if you want to use the binary file format, use -o <name of file>

the -4 / -6 flags are there if you know that the list of addresses is of
one type only (IPv6 or IPv4).  it is there so we don't have the
unnecessary overhead of receiving ICMP messages on those sockets if we
don't actually care about.

let me know if there is anything that you'd like documented in greater
detail.

Matthew