Commit | Line | Data |
---|---|---|
ad787160 C |
1 | .\" Copyright (c) 1990, 1991, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
7d897888 | 3 | .\" |
d7ff4848 KB |
4 | .\" This code is derived from software contributed to Berkeley by |
5 | .\" Van Jacobson. | |
7d897888 | 6 | .\" |
ad787160 C |
7 | .\" Redistribution and use in source and binary forms, with or without |
8 | .\" modification, are permitted provided that the following conditions | |
9 | .\" are met: | |
10 | .\" 1. Redistributions of source code must retain the above copyright | |
11 | .\" notice, this list of conditions and the following disclaimer. | |
12 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
13 | .\" notice, this list of conditions and the following disclaimer in the | |
14 | .\" documentation and/or other materials provided with the distribution. | |
15 | .\" 3. All advertising materials mentioning features or use of this software | |
16 | .\" must display the following acknowledgement: | |
17 | .\" This product includes software developed by the University of | |
18 | .\" California, Berkeley and its contributors. | |
19 | .\" 4. Neither the name of the University nor the names of its contributors | |
20 | .\" may be used to endorse or promote products derived from this software | |
21 | .\" without specific prior written permission. | |
7d897888 | 22 | .\" |
ad787160 C |
23 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
24 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
25 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
26 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
27 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
28 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
29 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
30 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
31 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
32 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
33 | .\" SUCH DAMAGE. | |
d7ff4848 | 34 | .\" |
ad787160 C |
35 | .\" @(#)traceroute.8 8.1 (Berkeley) 6/6/93 |
36 | .\" | |
37 | .Dd June 6, 1993 | |
b42074ab CL |
38 | .Dt TRACEROUTE 8 |
39 | .Os BSD 4.3 | |
40 | .Sh NAME | |
41 | .Nm traceroute | |
42 | .Nd print the route packets take to network host | |
43 | .Sh SYNOPSIS | |
44 | .Nm traceroute | |
45 | .Op Fl m Ar max_ttl | |
46 | .Op Fl n | |
47 | .Op Fl p Ar port | |
48 | .Op Fl q Ar nqueries | |
49 | .Op Fl r | |
50 | .Bk -words | |
51 | .Op Fl s Ar src_addr | |
52 | .Ek | |
53 | .Op Fl t Ar tos | |
54 | .Op Fl w Ar waittime | |
55 | .Ar host | |
56 | .Op Ar packetsize | |
57 | .Sh DESCRIPTION | |
7d897888 KB |
58 | The Internet is a large and complex aggregation of |
59 | network hardware, connected together by gateways. | |
60 | Tracking the route one's packets follow (or finding the miscreant | |
61 | gateway that's discarding your packets) can be difficult. | |
b42074ab | 62 | .Nm Traceroute |
7d897888 | 63 | utilizes the IP protocol `time to live' field and attempts to elicit an |
b42074ab CL |
64 | .Tn ICMP |
65 | .Dv TIME_EXCEEDED | |
66 | response from each gateway along the path to some | |
7d897888 | 67 | host. |
b42074ab | 68 | .Pp |
7d897888 KB |
69 | The only mandatory parameter is the destination host name or IP number. |
70 | The default probe datagram length is 38 bytes, but this may be increased | |
71 | by specifying a packet size (in bytes) after the destination host | |
72 | name. | |
b42074ab | 73 | .Pp |
7d897888 | 74 | Other options are: |
b42074ab CL |
75 | .Bl -tag -width Ds |
76 | .It Fl m Ar max_ttl | |
7d897888 | 77 | Set the max time-to-live (max number of hops) used in outgoing probe |
b42074ab CL |
78 | packets. The default is 30 hops (the same default used for |
79 | .Tn TCP | |
7d897888 | 80 | connections). |
b42074ab | 81 | .It Fl n |
7d897888 KB |
82 | Print hop addresses numerically rather than symbolically and numerically |
83 | (saves a nameserver address-to-name lookup for each gateway found on the | |
84 | path). | |
b42074ab CL |
85 | .It Fl p Ar port |
86 | Set the base | |
87 | .Tn UDP | |
88 | .Ar port | |
89 | number used in probes (default is 33434). | |
90 | .Nm Traceroute | |
91 | hopes that nothing is listening on | |
92 | .Tn UDP | |
93 | ports | |
94 | .Em base | |
7d897888 | 95 | to |
b42074ab CL |
96 | .Em base+nhops-1 |
97 | at the destination host (so an | |
98 | .Tn ICMP | |
99 | .Dv PORT_UNREACHABLE | |
100 | message will | |
7d897888 KB |
101 | be returned to terminate the route tracing). If something is |
102 | listening on a port in the default range, this option can be used | |
103 | to pick an unused port range. | |
b42074ab CL |
104 | .It Fl q Ar nqueries |
105 | Set the number of probes per ``ttl'' to | |
106 | .Ar nqueries | |
107 | (default is three probes). | |
108 | .It Fl r | |
7d897888 KB |
109 | Bypass the normal routing tables and send directly to a host on an attached |
110 | network. | |
111 | If the host is not on a directly-attached network, | |
112 | an error is returned. | |
113 | This option can be used to ping a local host through an interface | |
114 | that has no route through it (e.g., after the interface was dropped by | |
b42074ab CL |
115 | .Xr routed 8 ) . |
116 | .It Fl s Ar src_addr | |
117 | Use the following IP address | |
118 | (which must be given as an IP number, not | |
7d897888 KB |
119 | a hostname) as the source address in outgoing probe packets. On |
120 | hosts with more than one IP address, this option can be used to | |
121 | force the source address to be something other than the IP address | |
122 | of the interface the probe packet is sent on. If the IP address | |
123 | is not one of this machine's interface addresses, an error is | |
124 | returned and nothing is sent. | |
b42074ab | 125 | .It Fl t Ar tos |
7d897888 | 126 | Set the |
b42074ab CL |
127 | .Em type-of-service |
128 | in probe packets to the following value (default zero). The value must be | |
7d897888 KB |
129 | a decimal integer in the range 0 to 255. This option can be used to |
130 | see if different types-of-service result in different paths. (If you | |
b42074ab CL |
131 | are not running a |
132 | .Bx 4.3 tahoe | |
133 | or later system, this may be academic since the normal network | |
134 | services like telnet and ftp don't let you control the | |
135 | .Dv TOS ) . | |
136 | Not all values of | |
137 | .Dv TOS | |
138 | are legal or | |
7d897888 | 139 | meaningful \- see the IP spec for definitions. Useful values are |
b42074ab CL |
140 | probably |
141 | .Ql \-t 16 | |
142 | (low delay) and | |
143 | .Ql \-t 8 | |
144 | (high throughput). | |
145 | .It Fl v | |
146 | Verbose output. Received | |
147 | .Tn ICMP | |
148 | packets other than | |
149 | .Dv TIME_EXCEEDED | |
150 | and | |
151 | .Dv UNREACHABLE Ns s | |
152 | are listed. | |
153 | .It Fl w | |
7d897888 KB |
154 | Set the time (in seconds) to wait for a response to a probe (default 3 |
155 | sec.). | |
b42074ab CL |
156 | .El |
157 | .Pp | |
7d897888 | 158 | This program attempts to trace the route an IP packet would follow to some |
b42074ab CL |
159 | internet host by launching |
160 | .Tn UDP | |
161 | probe | |
7d897888 | 162 | packets with a small ttl (time to live) then listening for an |
b42074ab CL |
163 | .Tn ICMP |
164 | "time exceeded" reply from a gateway. We start our probes | |
165 | with a ttl of one and increase by one until we get an | |
166 | .Tn ICMP | |
167 | "port unreachable" | |
168 | (which means we got to "host") or hit a max (which | |
169 | defaults to 30 hops & can be changed with the | |
170 | .Fl m | |
171 | flag). Three | |
172 | probes (changed with | |
173 | .Fl q | |
174 | flag) are sent at each ttl setting and a | |
7d897888 KB |
175 | line is printed showing the ttl, address of the gateway and |
176 | round trip time of each probe. If the probe answers come from | |
177 | different gateways, the address of each responding system will | |
178 | be printed. If there is no response within a 3 sec. timeout | |
b42074ab CL |
179 | interval (changed with the |
180 | .Fl w | |
181 | flag), a "*" is printed for that | |
7d897888 | 182 | probe. |
b42074ab | 183 | .Pp |
7d897888 | 184 | We don't want the destination |
b42074ab CL |
185 | host to process the |
186 | .Tn UDP | |
187 | probe packets so the destination port is set to an | |
7d897888 | 188 | unlikely value (if some clod on the destination is using that |
b42074ab CL |
189 | value, it can be changed with the |
190 | .Fl p | |
191 | flag). | |
192 | .Pp | |
7d897888 | 193 | A sample use and output might be: |
b42074ab | 194 | .Bd -literal |
7d897888 KB |
195 | [yak 71]% traceroute nis.nsf.net. |
196 | traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 56 byte packet | |
b42074ab CL |
197 | 1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms |
198 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms | |
199 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms | |
200 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms | |
201 | 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms | |
202 | 6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms | |
203 | 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms | |
204 | 8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms | |
205 | 9 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms | |
7d897888 KB |
206 | 10 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms |
207 | 11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms | |
7d897888 | 208 | |
b42074ab | 209 | .Ed |
7d897888 KB |
210 | Note that lines 2 & 3 are the same. This is due to a buggy |
211 | kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards | |
212 | packets with a zero ttl (a bug in the distributed version | |
b42074ab CL |
213 | of 4.3 |
214 | .Tn BSD ) . | |
215 | Note that you have to guess what path | |
216 | the packets are taking cross-country since the | |
217 | .Tn NSFNet | |
218 | (129.140) | |
219 | doesn't supply address-to-name translations for its | |
220 | .Tn NSS Ns es . | |
221 | .Pp | |
7d897888 | 222 | A more interesting example is: |
b42074ab | 223 | .Bd -literal |
7d897888 KB |
224 | [yak 72]% traceroute allspice.lcs.mit.edu. |
225 | traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max | |
b42074ab CL |
226 | 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms |
227 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms | |
228 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms | |
229 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms | |
230 | 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms | |
231 | 6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms | |
232 | 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms | |
233 | 8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms | |
234 | 9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms | |
7d897888 KB |
235 | 10 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms |
236 | 11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms | |
237 | 12 * * * | |
238 | 13 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms | |
239 | 14 * * * | |
240 | 15 * * * | |
241 | 16 * * * | |
242 | 17 * * * | |
243 | 18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms | |
7d897888 | 244 | |
b42074ab | 245 | .Ed |
7d897888 | 246 | Note that the gateways 12, 14, 15, 16 & 17 hops away |
b42074ab CL |
247 | either don't send |
248 | .Tn ICMP | |
249 | "time exceeded" messages or send them | |
7d897888 | 250 | with a ttl too small to reach us. 14 \- 17 are running the |
b42074ab CL |
251 | .Tn MIT |
252 | C Gateway code that doesn't send "time exceeded"s. God | |
7d897888 | 253 | only knows what's going on with 12. |
b42074ab | 254 | .Pp |
7d897888 | 255 | The silent gateway 12 in the above may be the result of a bug in |
b42074ab CL |
256 | the 4.[23] |
257 | .Tn BSD | |
258 | network code (and its derivatives): 4.x (x <= 3) | |
7d897888 KB |
259 | sends an unreachable message using whatever ttl remains in the |
260 | original datagram. Since, for gateways, the remaining ttl is | |
b42074ab CL |
261 | zero, the |
262 | .Tn ICMP | |
263 | "time exceeded" is guaranteed to not make it back | |
7d897888 KB |
264 | to us. The behavior of this bug is slightly more interesting |
265 | when it appears on the destination system: | |
b42074ab CL |
266 | .Bd -literal |
267 | 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms | |
268 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms | |
269 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms | |
270 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms | |
271 | 5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms | |
272 | 6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms | |
273 | 7 * * * | |
274 | 8 * * * | |
275 | 9 * * * | |
7d897888 KB |
276 | 10 * * * |
277 | 11 * * * | |
278 | 12 * * * | |
279 | 13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! | |
7d897888 | 280 | |
b42074ab | 281 | .Ed |
7d897888 KB |
282 | Notice that there are 12 "gateways" (13 is the final |
283 | destination) and exactly the last half of them are "missing". | |
284 | What's really happening is that rip (a Sun-3 running Sun OS3.5) | |
285 | is using the ttl from our arriving datagram as the ttl in its | |
b42074ab CL |
286 | .Tn ICMP |
287 | reply. So, the reply will time out on the return path | |
288 | (with no notice sent to anyone since | |
289 | .Tn ICMP's | |
290 | aren't sent for | |
291 | .Tn ICMP's ) | |
292 | until we probe with a ttl that's at least twice the path | |
7d897888 KB |
293 | length. I.e., rip is really only 7 hops away. A reply that |
294 | returns with a ttl of 1 is a clue this problem exists. | |
b42074ab CL |
295 | .Nm Traceroute |
296 | prints a "!" after the time if the ttl is <= 1. | |
297 | Since vendors ship a lot of obsolete | |
298 | .Pf ( Tn DEC Ns \'s | |
299 | Ultrix, Sun 3.x) or | |
300 | non-standard | |
301 | .Pq Tn HPUX | |
302 | software, expect to see this problem | |
7d897888 KB |
303 | frequently and/or take care picking the target host of your |
304 | probes. | |
7d897888 | 305 | Other possible annotations after the time are |
b42074ab CL |
306 | .Sy !H , |
307 | .Sy !N , | |
308 | .Sy !P | |
7d897888 | 309 | (got a host, network or protocol unreachable, respectively), |
b42074ab | 310 | .Sy !S |
7d897888 | 311 | or |
b42074ab | 312 | .Sy !F |
7d897888 KB |
313 | (source route failed or fragmentation needed \- neither of these should |
314 | ever occur and the associated gateway is busted if you see one). If | |
b42074ab CL |
315 | almost all the probes result in some kind of unreachable, |
316 | .Nm traceroute | |
7d897888 | 317 | will give up and exit. |
b42074ab | 318 | .Pp |
7d897888 KB |
319 | This program is intended for use in network testing, measurement |
320 | and management. | |
321 | It should be used primarily for manual fault isolation. | |
322 | Because of the load it could impose on the network, it is unwise to use | |
b42074ab | 323 | .Nm traceroute |
7d897888 | 324 | during normal operations or from automated scripts. |
b42074ab | 325 | .Sh AUTHOR |
7d897888 KB |
326 | Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged |
327 | by a cast of thousands with particularly cogent suggestions or fixes from | |
328 | C. Philip Wood, Tim Seaver and Ken Adelman. | |
b42074ab CL |
329 | .Sh SEE ALSO |
330 | .Xr netstat 1 , | |
331 | .Xr ping 8 | |
332 | .Sh HISTORY | |
333 | The | |
334 | .Nm | |
335 | command | |
336 | .Bt |