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