| 1 | .\" Copyright (c) 1990, 1991 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" This code is derived from software contributed to Berkeley by |
| 5 | .\" Van Jacobson. |
| 6 | .\" |
| 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. |
| 22 | .\" |
| 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. |
| 34 | .\" |
| 35 | .\" @(#)traceroute.8 5.4 (Berkeley) 3/16/91 |
| 36 | .\" |
| 37 | .Dd March 16, 1991 |
| 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 |
| 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. |
| 62 | .Nm Traceroute |
| 63 | utilizes the IP protocol `time to live' field and attempts to elicit an |
| 64 | .Tn ICMP |
| 65 | .Dv TIME_EXCEEDED |
| 66 | response from each gateway along the path to some |
| 67 | host. |
| 68 | .Pp |
| 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. |
| 73 | .Pp |
| 74 | Other options are: |
| 75 | .Bl -tag -width Ds |
| 76 | .It Fl m Ar max_ttl |
| 77 | Set the max time-to-live (max number of hops) used in outgoing probe |
| 78 | packets. The default is 30 hops (the same default used for |
| 79 | .Tn TCP |
| 80 | connections). |
| 81 | .It Fl n |
| 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). |
| 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 |
| 95 | to |
| 96 | .Em base+nhops-1 |
| 97 | at the destination host (so an |
| 98 | .Tn ICMP |
| 99 | .Dv PORT_UNREACHABLE |
| 100 | message will |
| 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. |
| 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 |
| 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 |
| 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 |
| 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. |
| 125 | .It Fl t Ar tos |
| 126 | Set the |
| 127 | .Em type-of-service |
| 128 | in probe packets to the following value (default zero). The value must be |
| 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 |
| 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 |
| 139 | meaningful \- see the IP spec for definitions. Useful values are |
| 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 |
| 154 | Set the time (in seconds) to wait for a response to a probe (default 3 |
| 155 | sec.). |
| 156 | .El |
| 157 | .Pp |
| 158 | This program attempts to trace the route an IP packet would follow to some |
| 159 | internet host by launching |
| 160 | .Tn UDP |
| 161 | probe |
| 162 | packets with a small ttl (time to live) then listening for an |
| 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 |
| 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 |
| 179 | interval (changed with the |
| 180 | .Fl w |
| 181 | flag), a "*" is printed for that |
| 182 | probe. |
| 183 | .Pp |
| 184 | We don't want the destination |
| 185 | host to process the |
| 186 | .Tn UDP |
| 187 | probe packets so the destination port is set to an |
| 188 | unlikely value (if some clod on the destination is using that |
| 189 | value, it can be changed with the |
| 190 | .Fl p |
| 191 | flag). |
| 192 | .Pp |
| 193 | A sample use and output might be: |
| 194 | .Bd -literal |
| 195 | [yak 71]% traceroute nis.nsf.net. |
| 196 | traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 56 byte packet |
| 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 |
| 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 |
| 208 | |
| 209 | .Ed |
| 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 |
| 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 |
| 222 | A more interesting example is: |
| 223 | .Bd -literal |
| 224 | [yak 72]% traceroute allspice.lcs.mit.edu. |
| 225 | traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max |
| 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 |
| 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 |
| 244 | |
| 245 | .Ed |
| 246 | Note that the gateways 12, 14, 15, 16 & 17 hops away |
| 247 | either don't send |
| 248 | .Tn ICMP |
| 249 | "time exceeded" messages or send them |
| 250 | with a ttl too small to reach us. 14 \- 17 are running the |
| 251 | .Tn MIT |
| 252 | C Gateway code that doesn't send "time exceeded"s. God |
| 253 | only knows what's going on with 12. |
| 254 | .Pp |
| 255 | The silent gateway 12 in the above may be the result of a bug in |
| 256 | the 4.[23] |
| 257 | .Tn BSD |
| 258 | network code (and its derivatives): 4.x (x <= 3) |
| 259 | sends an unreachable message using whatever ttl remains in the |
| 260 | original datagram. Since, for gateways, the remaining ttl is |
| 261 | zero, the |
| 262 | .Tn ICMP |
| 263 | "time exceeded" is guaranteed to not make it back |
| 264 | to us. The behavior of this bug is slightly more interesting |
| 265 | when it appears on the destination system: |
| 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 * * * |
| 276 | 10 * * * |
| 277 | 11 * * * |
| 278 | 12 * * * |
| 279 | 13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! |
| 280 | |
| 281 | .Ed |
| 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 |
| 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 |
| 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. |
| 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 |
| 303 | frequently and/or take care picking the target host of your |
| 304 | probes. |
| 305 | Other possible annotations after the time are |
| 306 | .Sy !H , |
| 307 | .Sy !N , |
| 308 | .Sy !P |
| 309 | (got a host, network or protocol unreachable, respectively), |
| 310 | .Sy !S |
| 311 | or |
| 312 | .Sy !F |
| 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 |
| 315 | almost all the probes result in some kind of unreachable, |
| 316 | .Nm traceroute |
| 317 | will give up and exit. |
| 318 | .Pp |
| 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 |
| 323 | .Nm traceroute |
| 324 | during normal operations or from automated scripts. |
| 325 | .Sh AUTHOR |
| 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. |
| 329 | .Sh SEE ALSO |
| 330 | .Xr netstat 1 , |
| 331 | .Xr ping 8 |
| 332 | .Sh HISTORY |
| 333 | The |
| 334 | .Nm |
| 335 | command |
| 336 | .Bt |