astraceroute.8

   1 .\" netsniff-ng - the packet sniffing beast
   2 .\" Copyright 2013 Daniel Borkmann.
   3 .\" Subject to the GPL, version 2.
   4
   5 .TH ASTRACEROUTE 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
   6 .SH NAME
   7 astraceroute \- autonomous system trace route utility
   8
   9 .SH SYNOPSIS
  10
  11 \fB astraceroute\fR [\fIoptions\fR]
  12
  13 .SH DESCRIPTION
  14 astraceroute is a small utility to retrieve path information in a traceroute
  15 like way, but with additional geographical location information. It tracks the
  16 route of a packet from the local host to the remote host by sucessively
  17 increasing the IP's TTL field in the hope, that the intermediate node sends a
  18 ICMP TIME_EXCEEDED notification back to us.
  19
  20 astraceroute supports IPv4 and IPv6 queries and will display country and city
  21 information if available as well as the AS number the hop belongs to and its
  22 ISP name. astraceroute also displays timing information and reverse DNS data.
  23
  24 Due to astraceroute's configurability it is also possible to gather some more
  25 useful information about the hop regarding what it passes through and what not.
  26 I.e. astraceroute also allows some clear text strings for probing some DPIs or
  27 ``great firewalls'' that would filter out blacklisted critical keywords. This
  28 tool might be a good start for further in-depth analysis of such systems.
  29
  30 .SH OPTIONS
  31
  32 .SS -H <host>, --host <host>
  33 Hostname, IPv4 or IPv6 address of the remote host where the AS route should
  34 be traced to. In case of an IPv6 address or host, also option ``-6'' must be
  35 used. IPv4 is the default.
  36
  37 .SS -p <port>, --port <port>
  38 TCP port for the remote host to use. If not otherwise specified, the default
  39 port to be used is 80.
  40
  41 .SS -i <device>, -d <device>, --dev <device>
  42 Networking device to start the trace route from, e.g. eth0, wlan0.
  43
  44 .SS -f <ttl>, --init-ttl <ttl>
  45 Initial TTL value to be used. This option might be useful if you are not
  46 interested in the first n hops, but only follow-up ones. The default
  47 initial TTL value is 1.
  48
  49 .SS -m <ttl>, --max-ttl <ttl>
  50 Maximum TTL value to be used. If not otherwise specified, the maximum
  51 TTL value is 30. Thus, after this has been reached astraceroute exits
  52 itself.
  53
  54 .SS -q <num>, --num-probes <num>
  55 Specifies the number of queries to be done on a particular hop. The
  56 default is 2 query requests.
  57
  58 .SS -x <sec>, --timeout <sec>
  59 Tells astraceroute the probe response timeout in seconds, in other words
  60 the maximum time astraceroute must wait for an ICMP response from the current
  61 hop. The default is 3 seconds.
  62
  63 .SS -X <string>, --payload <string>
  64 Places an ASCII cleartext into the packet payload. In case the cleartext
  65 contains whitespaces, it must be put into quotes, f.e. "censer me".
  66
  67 .SS -l <len>, --totlen <len>
  68 Specifies the total length of the packet. Payload that does not have a
  69 cleartext string in it is padded with random garbage.
  70
  71 .SS -4, --ipv4
  72 Use IPv4 only requests. This is the default.
  73
  74 .SS -6, --ipv6
  75 Use IPv6 only requests. This must be used when passing an IPv6 host as an
  76 argument.
  77
  78 .SS -n, --numeric
  79 Tells astraceroute to not perform reverse DNS lookup for hop replies. The
  80 reverse option is ``-N''.
  81
  82 .SS -u, --update
  83 The built-in geo-database update mechanism will be invoked to get Maxmind's
  84 latest version. To configure search locations for databases, the file
  85 /etc/netsniff-ng/geoip.conf contains possible addresses. Thus, to save bandwidth
  86 or for mirroring Maxmind's databases (to bypass their traffic limit policy),
  87 different hosts or IP addresses can be placed into geoip.conf, separated by
  88 a newline.
  89
  90 .SS -L, --latitude
  91 Also show latitude and longtitude of hops.
  92
  93 .SS -N, --dns
  94 Tells astraceroute to perform reverse DNS lookup for hop replies. The
  95 reverse option is ``-n''.
  96
  97 .SS -S, --syn
  98 Use TCP's SYN flag for the request.
  99
 100 .SS -A, --ack
 101 Use TCP's ACK flag for the request.
 102
 103 .SS -F, --fin
 104 Use TCP's FIN flag for the request.
 105
 106 .SS -P, --psh
 107 Use TCP's PSH flag for the request.
 108
 109 .SS -U, --urg
 110 Use TCP's URG flag for the request.
 111
 112 .SS -R, --rst
 113 Use TCP's RST flag for the request.
 114
 115 .SS -E, --ecn-syn
 116 Use TCP's ECN flag for the request.
 117
 118 .SS -t <tos>, --tos <tos>
 119 Explicitly specify IP's TOS.
 120
 121 .SS -G, --nofrag
 122 Set the IP's no fragmentation flag.
 123
 124 .SS -Z, --show-packet
 125 Show and dissect the returned packet.
 126
 127 .SS -v, --version
 128 Show versioning information.
 129
 130 .SS -h, --help
 131 Show user help.
 132
 133 .SH USAGE EXAMPLE
 134
 135 .SS astraceroute -i eth0 -N -S -H netsniff-ng.org
 136 This sends out a TCP SYN probe via the ``eth0'' networking device to the
 137 remote IPv4 host netsniff-ng.org. This request is most likely to pass. Also,
 138 tell astraceroute to perform reverse DNS lookups for each hop.
 139
 140 .SS astraceroute -6 -i eth0 -S -E -N -H www.6bone.net
 141 In this example, a TCP SYN/ECN probe for the IPv6 host www.6bone.net is being
 142 performed. Also in this case, the ``eth0'' device is being used and hops are
 143 being reserve DNS'ed.
 144
 145 .SS astraceroute -i eth0 -N -F -H netsniff-ng.org
 146 Here, we send out a TCP FIN probe to the remote host netsniff-ng.org. Again,
 147 on each hop a reverse DNS lookup is being done and the queries are transmitted
 148 from ``eth0''. IPv4 is used.
 149
 150 .SS astraceroute -i eth0 -N -FPU -H netsniff-ng.org
 151 As in most other examples, we perform a trace route to IPv4 host netsniff-ng.org
 152 and do a TCP Xmas probe this time.
 153
 154 .SS astraceroute -i eth0 -N -H netsniff-ng.org -X "censor-me" -Z
 155 In this example, we have a Null probe to the remote host netsniff-ng.org, port
 156 80 (default) and this time, we append the cleartext string "censor-me" into the
 157 packet payload to test if a firewall/DPI will let this string pass. Such a trace
 158 could be done once without and once with a blacklisted string to gather possible
 159 information about censorhsip.
 160
 161 .SH NOTE
 162 If a TCP-based probe will fail after a number of retries, astraceroute will
 163 automatically fall back to ICMP-based probes to pass through firewalls resp.
 164 routers.
 165
 166 To gather more information about astraceroute's displayed AS numbers, see f.e.
 167 http://bgp.he.net/AS<number>.
 168
 169 .SH BUGS
 170 The geographical locations are estimated with the help of Maxmind's GeoIP
 171 database and can or cannot deviate from the actual real physical location.
 172 What one can do to decrease a possible error rate is to update the database
 173 regularly e.g. with astraceroute's --update option.
 174
 175 At some point in time, we need a similar approach to gather more reliable path
 176 information such as in paris-traceroute.
 177
 178 Due to the generic nature of astraceroute it currently does only have a built-in
 179 mechanism to stop the trace after a static number of hops, since the configurable
 180 TCP flags can have anything included. It is possible to decrease this number of
 181 course. In future, if a SYN probe is sent out, there should be a listener thus
 182 we can stop the trace if we detect a handshake in progress.
 183
 184 .SH LEGAL
 185 astraceroute is licensed under the GNU GPL version 2.0.
 186
 187 .SH HISTORY
 188 .B astraceroute
 189 was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
 190 is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
 191 Borkmann <dborkma@tik.ee.ethz.ch>.
 192
 193 .SH SEE ALSO
 194 .BR netsniff-ng (8),
 195 .BR trafgen (8),
 196 .BR mausezahn (8),
 197 .BR ifpps (8),
 198 .BR bpfc (8),
 199 .BR flowtop (8),
 200 .BR curvetun (8)
 201
 202 .SH AUTHOR
 203 Manpage was written by Daniel Borkmann.