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