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