Commit | Line | Data |
---|---|---|
8cd61d7d KB |
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 | .\" |
d7ff4848 | 7 | .\" %sccs.include.redist.man% |
7d897888 | 8 | .\" |
2e55f625 | 9 | .\" @(#)traceroute.8 8.2 (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. | |
2e55f625 | 99 | .ne 1i |
b42074ab | 100 | .It Fl t Ar tos |
7d897888 | 101 | Set the |
b42074ab CL |
102 | .Em type-of-service |
103 | in probe packets to the following value (default zero). The value must be | |
7d897888 KB |
104 | a decimal integer in the range 0 to 255. This option can be used to |
105 | see if different types-of-service result in different paths. (If you | |
b42074ab CL |
106 | are not running a |
107 | .Bx 4.3 tahoe | |
108 | or later system, this may be academic since the normal network | |
109 | services like telnet and ftp don't let you control the | |
110 | .Dv TOS ) . | |
111 | Not all values of | |
112 | .Dv TOS | |
113 | are legal or | |
7d897888 | 114 | meaningful \- see the IP spec for definitions. Useful values are |
b42074ab CL |
115 | probably |
116 | .Ql \-t 16 | |
117 | (low delay) and | |
118 | .Ql \-t 8 | |
119 | (high throughput). | |
120 | .It Fl v | |
121 | Verbose output. Received | |
122 | .Tn ICMP | |
123 | packets other than | |
124 | .Dv TIME_EXCEEDED | |
125 | and | |
126 | .Dv UNREACHABLE Ns s | |
127 | are listed. | |
128 | .It Fl w | |
7d897888 KB |
129 | Set the time (in seconds) to wait for a response to a probe (default 3 |
130 | sec.). | |
b42074ab CL |
131 | .El |
132 | .Pp | |
7d897888 | 133 | This program attempts to trace the route an IP packet would follow to some |
b42074ab CL |
134 | internet host by launching |
135 | .Tn UDP | |
136 | probe | |
7d897888 | 137 | packets with a small ttl (time to live) then listening for an |
b42074ab CL |
138 | .Tn ICMP |
139 | "time exceeded" reply from a gateway. We start our probes | |
140 | with a ttl of one and increase by one until we get an | |
141 | .Tn ICMP | |
142 | "port unreachable" | |
143 | (which means we got to "host") or hit a max (which | |
144 | defaults to 30 hops & can be changed with the | |
145 | .Fl m | |
146 | flag). Three | |
147 | probes (changed with | |
148 | .Fl q | |
149 | flag) are sent at each ttl setting and a | |
7d897888 KB |
150 | line is printed showing the ttl, address of the gateway and |
151 | round trip time of each probe. If the probe answers come from | |
152 | different gateways, the address of each responding system will | |
153 | be printed. If there is no response within a 3 sec. timeout | |
b42074ab CL |
154 | interval (changed with the |
155 | .Fl w | |
156 | flag), a "*" is printed for that | |
7d897888 | 157 | probe. |
b42074ab | 158 | .Pp |
7d897888 | 159 | We don't want the destination |
b42074ab CL |
160 | host to process the |
161 | .Tn UDP | |
162 | probe packets so the destination port is set to an | |
7d897888 | 163 | unlikely value (if some clod on the destination is using that |
b42074ab CL |
164 | value, it can be changed with the |
165 | .Fl p | |
166 | flag). | |
167 | .Pp | |
7d897888 | 168 | A sample use and output might be: |
b42074ab | 169 | .Bd -literal |
7d897888 KB |
170 | [yak 71]% traceroute nis.nsf.net. |
171 | traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 56 byte packet | |
b42074ab CL |
172 | 1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms |
173 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms | |
174 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms | |
175 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms | |
176 | 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms | |
177 | 6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms | |
178 | 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms | |
179 | 8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms | |
180 | 9 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms | |
7d897888 KB |
181 | 10 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms |
182 | 11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms | |
7d897888 | 183 | |
b42074ab | 184 | .Ed |
7d897888 KB |
185 | Note that lines 2 & 3 are the same. This is due to a buggy |
186 | kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards | |
187 | packets with a zero ttl (a bug in the distributed version | |
b42074ab CL |
188 | of 4.3 |
189 | .Tn BSD ) . | |
190 | Note that you have to guess what path | |
191 | the packets are taking cross-country since the | |
192 | .Tn NSFNet | |
193 | (129.140) | |
194 | doesn't supply address-to-name translations for its | |
195 | .Tn NSS Ns es . | |
196 | .Pp | |
7d897888 | 197 | A more interesting example is: |
b42074ab | 198 | .Bd -literal |
7d897888 KB |
199 | [yak 72]% traceroute allspice.lcs.mit.edu. |
200 | traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max | |
b42074ab CL |
201 | 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms |
202 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms | |
203 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms | |
204 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms | |
205 | 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms | |
206 | 6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms | |
207 | 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms | |
208 | 8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms | |
209 | 9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms | |
7d897888 KB |
210 | 10 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms |
211 | 11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms | |
212 | 12 * * * | |
213 | 13 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms | |
214 | 14 * * * | |
215 | 15 * * * | |
216 | 16 * * * | |
217 | 17 * * * | |
218 | 18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms | |
7d897888 | 219 | |
b42074ab | 220 | .Ed |
7d897888 | 221 | Note that the gateways 12, 14, 15, 16 & 17 hops away |
b42074ab CL |
222 | either don't send |
223 | .Tn ICMP | |
224 | "time exceeded" messages or send them | |
7d897888 | 225 | with a ttl too small to reach us. 14 \- 17 are running the |
b42074ab CL |
226 | .Tn MIT |
227 | C Gateway code that doesn't send "time exceeded"s. God | |
7d897888 | 228 | only knows what's going on with 12. |
b42074ab | 229 | .Pp |
7d897888 | 230 | The silent gateway 12 in the above may be the result of a bug in |
b42074ab CL |
231 | the 4.[23] |
232 | .Tn BSD | |
233 | network code (and its derivatives): 4.x (x <= 3) | |
7d897888 KB |
234 | sends an unreachable message using whatever ttl remains in the |
235 | original datagram. Since, for gateways, the remaining ttl is | |
b42074ab CL |
236 | zero, the |
237 | .Tn ICMP | |
238 | "time exceeded" is guaranteed to not make it back | |
7d897888 KB |
239 | to us. The behavior of this bug is slightly more interesting |
240 | when it appears on the destination system: | |
b42074ab CL |
241 | .Bd -literal |
242 | 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms | |
243 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms | |
244 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms | |
245 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms | |
246 | 5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms | |
247 | 6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms | |
248 | 7 * * * | |
249 | 8 * * * | |
250 | 9 * * * | |
7d897888 KB |
251 | 10 * * * |
252 | 11 * * * | |
253 | 12 * * * | |
254 | 13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! | |
7d897888 | 255 | |
b42074ab | 256 | .Ed |
7d897888 KB |
257 | Notice that there are 12 "gateways" (13 is the final |
258 | destination) and exactly the last half of them are "missing". | |
259 | What's really happening is that rip (a Sun-3 running Sun OS3.5) | |
260 | is using the ttl from our arriving datagram as the ttl in its | |
b42074ab CL |
261 | .Tn ICMP |
262 | reply. So, the reply will time out on the return path | |
263 | (with no notice sent to anyone since | |
264 | .Tn ICMP's | |
265 | aren't sent for | |
266 | .Tn ICMP's ) | |
267 | until we probe with a ttl that's at least twice the path | |
7d897888 KB |
268 | length. I.e., rip is really only 7 hops away. A reply that |
269 | returns with a ttl of 1 is a clue this problem exists. | |
b42074ab CL |
270 | .Nm Traceroute |
271 | prints a "!" after the time if the ttl is <= 1. | |
272 | Since vendors ship a lot of obsolete | |
273 | .Pf ( Tn DEC Ns \'s | |
274 | Ultrix, Sun 3.x) or | |
275 | non-standard | |
276 | .Pq Tn HPUX | |
277 | software, expect to see this problem | |
7d897888 KB |
278 | frequently and/or take care picking the target host of your |
279 | probes. | |
7d897888 | 280 | Other possible annotations after the time are |
b42074ab CL |
281 | .Sy !H , |
282 | .Sy !N , | |
283 | .Sy !P | |
7d897888 | 284 | (got a host, network or protocol unreachable, respectively), |
b42074ab | 285 | .Sy !S |
7d897888 | 286 | or |
b42074ab | 287 | .Sy !F |
7d897888 KB |
288 | (source route failed or fragmentation needed \- neither of these should |
289 | ever occur and the associated gateway is busted if you see one). If | |
b42074ab CL |
290 | almost all the probes result in some kind of unreachable, |
291 | .Nm traceroute | |
7d897888 | 292 | will give up and exit. |
b42074ab | 293 | .Pp |
7d897888 KB |
294 | This program is intended for use in network testing, measurement |
295 | and management. | |
296 | It should be used primarily for manual fault isolation. | |
297 | Because of the load it could impose on the network, it is unwise to use | |
b42074ab | 298 | .Nm traceroute |
7d897888 | 299 | during normal operations or from automated scripts. |
b42074ab | 300 | .Sh AUTHOR |
7d897888 KB |
301 | Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged |
302 | by a cast of thousands with particularly cogent suggestions or fixes from | |
303 | C. Philip Wood, Tim Seaver and Ken Adelman. | |
b42074ab CL |
304 | .Sh SEE ALSO |
305 | .Xr netstat 1 , | |
306 | .Xr ping 8 | |
307 | .Sh HISTORY | |
308 | The | |
309 | .Nm | |
310 | command | |
311 | .Bt |