| 1 | .\" Copyright (c) 1989, 1995, 1996 |
| 2 | .\" The Regents of the University of California. All rights reserved. |
| 3 | .\" |
| 4 | .\" Redistribution and use in source and binary forms are permitted |
| 5 | .\" provided that the above copyright notice and this paragraph are |
| 6 | .\" duplicated in all such forms and that any documentation, |
| 7 | .\" advertising materials, and other materials related to such |
| 8 | .\" distribution and use acknowledge that the software was developed |
| 9 | .\" by the University of California, Berkeley. The name of the |
| 10 | .\" University may not be used to endorse or promote products derived |
| 11 | .\" from this software without specific prior written permission. |
| 12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR |
| 13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED |
| 14 | .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. |
| 15 | .\" |
| 16 | .\" $Header: traceroute.8,v 1.7 96/09/27 20:02:41 leres Exp $ |
| 17 | .\" $FreeBSD: src/contrib/traceroute/traceroute.8,v 1.6.2.2 2002/11/27 17:05:29 fenner Exp $ |
| 18 | .\" $DragonFly: src/contrib/traceroute/Attic/traceroute.8,v 1.2 2003/06/17 04:24:07 dillon Exp $ |
| 19 | .\" |
| 20 | .TH TRACEROUTE 8 "27 September 1996" |
| 21 | .UC 6 |
| 22 | .SH NAME |
| 23 | traceroute \- print the route packets take to network host |
| 24 | .SH SYNOPSIS |
| 25 | .. while ((op = getopt(argc, argv, "dnrvg:M:m:P:p:q:s:t:w:")) != EOF) |
| 26 | .na |
| 27 | .B traceroute |
| 28 | [ |
| 29 | .B \-Sdnrv |
| 30 | ] [ |
| 31 | .B \-g |
| 32 | .I gw_host |
| 33 | ] [ |
| 34 | .B \-M |
| 35 | .I min_ttl |
| 36 | ] |
| 37 | .br |
| 38 | .ti +8 |
| 39 | [ |
| 40 | .B \-m |
| 41 | .I max_ttl |
| 42 | ] [ |
| 43 | .B \-P |
| 44 | .I proto |
| 45 | ] [ |
| 46 | .B \-p |
| 47 | .I port |
| 48 | ] |
| 49 | .br |
| 50 | .ti +8 |
| 51 | [ |
| 52 | .B \-q |
| 53 | .I nqueries |
| 54 | ] [ |
| 55 | .B \-s |
| 56 | .I src_addr |
| 57 | ] [ |
| 58 | .B \-t |
| 59 | .I tos |
| 60 | ] |
| 61 | .br |
| 62 | .ti +8 |
| 63 | [ |
| 64 | .B \-w |
| 65 | .I waittime |
| 66 | ] |
| 67 | .I host |
| 68 | [ |
| 69 | .I packetlen |
| 70 | ] |
| 71 | .ad |
| 72 | .SH DESCRIPTION |
| 73 | The Internet is a large and complex aggregation of |
| 74 | network hardware, connected together by gateways. |
| 75 | Tracking the route one's packets follow (or finding the miscreant |
| 76 | gateway that's discarding your packets) can be difficult. |
| 77 | .I Traceroute |
| 78 | utilizes the IP protocol `time to live' field and attempts to elicit an |
| 79 | ICMP TIME_EXCEEDED response from each gateway along the path to some |
| 80 | host. |
| 81 | .PP |
| 82 | The only mandatory parameter is the destination host name or IP number. |
| 83 | The default probe datagram length is 40 bytes, but this may be increased |
| 84 | by specifying a packet length (in bytes) after the destination host |
| 85 | name. |
| 86 | .PP |
| 87 | Other options are: |
| 88 | .TP |
| 89 | .B \-S |
| 90 | Print a summary of how many probes were not answered for each hop. |
| 91 | .TP |
| 92 | .B \-g |
| 93 | Specify a loose source route gateway (8 maximum). |
| 94 | .TP |
| 95 | .B \-M |
| 96 | Set the initial time-to-live value used in outgoing probe packets. |
| 97 | The default is 1, i.e., start with the first hop. |
| 98 | .TP |
| 99 | .B \-m |
| 100 | Set the max time-to-live (max number of hops) used in outgoing probe |
| 101 | packets. The default is |
| 102 | .I net.inet.ip.ttl |
| 103 | hops (the same default used for TCP |
| 104 | connections). |
| 105 | .TP |
| 106 | .B \-n |
| 107 | Print hop addresses numerically rather than symbolically and numerically |
| 108 | (saves a nameserver address-to-name lookup for each gateway found on the |
| 109 | path). |
| 110 | .TP |
| 111 | .B \-P |
| 112 | Send packets of specified IP protocol. The currently supported protocols |
| 113 | are: UDP, TCP, GRE and ICMP. Other protocols may also be specified (either by |
| 114 | name or by number), though |
| 115 | .I traceroute |
| 116 | does not implement any special knowledge of their packet formats. This |
| 117 | option is useful for determining which router along a path may be |
| 118 | blocking packets based on IP protocol number. But see BUGS below. |
| 119 | .TP |
| 120 | .B \-p |
| 121 | Protocol specific. For UDP and TCP, sets |
| 122 | the base port number used in probes (default is 33434). |
| 123 | Traceroute hopes that nothing is listening on UDP ports |
| 124 | .I base |
| 125 | to |
| 126 | .I base + nhops - 1 |
| 127 | at the destination host (so an ICMP PORT_UNREACHABLE message will |
| 128 | be returned to terminate the route tracing). If something is |
| 129 | listening on a port in the default range, this option can be used |
| 130 | to pick an unused port range. |
| 131 | .TP |
| 132 | .B \-q |
| 133 | Set the number of probes per hop (default is 3). |
| 134 | .TP |
| 135 | .B \-r |
| 136 | Bypass the normal routing tables and send directly to a host on an attached |
| 137 | network. |
| 138 | If the host is not on a directly-attached network, |
| 139 | an error is returned. |
| 140 | This option can be used to ping a local host through an interface |
| 141 | that has no route through it (e.g., after the interface was dropped by |
| 142 | .IR routed (8C)). |
| 143 | .TP |
| 144 | .B \-s |
| 145 | Use the following IP address (which must be given as an IP number, not |
| 146 | a hostname) as the source address in outgoing probe packets. On |
| 147 | hosts with more than one IP address, this option can be used to |
| 148 | force the source address to be something other than the IP address |
| 149 | of the interface the probe packet is sent on. If the IP address |
| 150 | is not one of this machine's interface addresses, an error is |
| 151 | returned and nothing is sent. |
| 152 | .TP |
| 153 | .B \-t |
| 154 | Set the |
| 155 | .I type-of-service |
| 156 | in probe packets to the following value (default zero). The value must be |
| 157 | a decimal integer in the range 0 to 255. This option can be used to |
| 158 | see if different types-of-service result in different paths. (If you |
| 159 | are not running 4.4bsd, this may be academic since the normal network |
| 160 | services like telnet and ftp don't let you control the TOS). |
| 161 | Not all values of TOS are legal or |
| 162 | meaningful \- see the IP spec for definitions. Useful values are |
| 163 | probably `-t 16' (low delay) and `-t 8' (high throughput). |
| 164 | .TP |
| 165 | .B \-v |
| 166 | Verbose output. Received ICMP packets other than TIME_EXCEEDED and |
| 167 | UNREACHABLEs are listed. |
| 168 | .TP |
| 169 | .B \-w |
| 170 | Set the time (in seconds) to wait for a response to a probe (default 5 |
| 171 | sec.). |
| 172 | .PP |
| 173 | This program attempts to trace the route an IP packet would follow to some |
| 174 | internet host by launching UDP probe |
| 175 | packets with a small ttl (time to live) then listening for an |
| 176 | ICMP "time exceeded" reply from a gateway. We start our probes |
| 177 | with a ttl of one and increase by one until we get an ICMP "port |
| 178 | unreachable" (which means we got to "host") or hit a max (which |
| 179 | defaults to |
| 180 | .I net.inet.ip.ttl |
| 181 | hops & can be changed with the \-m flag). Three |
| 182 | probes (change with \-q flag) are sent at each ttl setting and a |
| 183 | line is printed showing the ttl, address of the gateway and |
| 184 | round trip time of each probe. If the probe answers come from |
| 185 | different gateways, the address of each responding system will |
| 186 | be printed. If there is no response within a 5 sec. timeout |
| 187 | interval (changed with the \-w flag), a "*" is printed for that |
| 188 | probe. |
| 189 | .PP |
| 190 | We don't want the destination |
| 191 | host to process the UDP probe packets so the destination port is set to an |
| 192 | unlikely value (if some clod on the destination is using that |
| 193 | value, it can be changed with the \-p flag). |
| 194 | .PP |
| 195 | A sample use and output might be: |
| 196 | |
| 197 | .RS |
| 198 | .nf |
| 199 | [yak 71]% traceroute nis.nsf.net. |
| 200 | traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 38 byte packet |
| 201 | 1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms |
| 202 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms |
| 203 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms |
| 204 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms |
| 205 | 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms |
| 206 | 6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms |
| 207 | 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms |
| 208 | 8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms |
| 209 | 9 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms |
| 210 | 10 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms |
| 211 | 11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms |
| 212 | .fi |
| 213 | .RE |
| 214 | |
| 215 | Note that lines 2 & 3 are the same. This is due to a buggy |
| 216 | kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards |
| 217 | packets with a zero ttl (a bug in the distributed version |
| 218 | of 4.3BSD). Note that you have to guess what path |
| 219 | the packets are taking cross-country since the NSFNet (129.140) |
| 220 | doesn't supply address-to-name translations for its NSSes. |
| 221 | .PP |
| 222 | A more interesting example is: |
| 223 | |
| 224 | .RS |
| 225 | .nf |
| 226 | [yak 72]% traceroute allspice.lcs.mit.edu. |
| 227 | traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max |
| 228 | 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms |
| 229 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms |
| 230 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms |
| 231 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms |
| 232 | 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms |
| 233 | 6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms |
| 234 | 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms |
| 235 | 8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms |
| 236 | 9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms |
| 237 | 10 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms |
| 238 | 11 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms |
| 239 | 12 * * * |
| 240 | 13 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms |
| 241 | 14 * * * |
| 242 | 15 * * * |
| 243 | 16 * * * |
| 244 | 17 * * * |
| 245 | 18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms |
| 246 | .fi |
| 247 | .RE |
| 248 | |
| 249 | Note that the gateways 12, 14, 15, 16 & 17 hops away |
| 250 | either don't send ICMP "time exceeded" messages or send them |
| 251 | with a ttl too small to reach us. 14 \- 17 are running the |
| 252 | MIT 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]BSD network code (and its derivatives): 4.x (x <= 3) |
| 257 | sends an unreachable message using whatever ttl remains in the |
| 258 | original datagram. Since, for gateways, the remaining ttl is |
| 259 | zero, the ICMP "time exceeded" is guaranteed to not make it back |
| 260 | to us. The behavior of this bug is slightly more interesting |
| 261 | when it appears on the destination system: |
| 262 | |
| 263 | .RS |
| 264 | .nf |
| 265 | 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms |
| 266 | 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms |
| 267 | 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms |
| 268 | 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms |
| 269 | 5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms |
| 270 | 6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms |
| 271 | 7 * * * |
| 272 | 8 * * * |
| 273 | 9 * * * |
| 274 | 10 * * * |
| 275 | 11 * * * |
| 276 | 12 * * * |
| 277 | 13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! |
| 278 | .fi |
| 279 | .RE |
| 280 | |
| 281 | Notice that there are 12 "gateways" (13 is the final |
| 282 | destination) and exactly the last half of them are "missing". |
| 283 | What's really happening is that rip (a Sun-3 running Sun OS3.5) |
| 284 | is using the ttl from our arriving datagram as the ttl in its |
| 285 | ICMP reply. So, the reply will time out on the return path |
| 286 | (with no notice sent to anyone since ICMP's aren't sent for |
| 287 | ICMP's) until we probe with a ttl that's at least twice the path |
| 288 | length. I.e., rip is really only 7 hops away. A reply that |
| 289 | returns with a ttl of 1 is a clue this problem exists. |
| 290 | Traceroute prints a "!" after the time if the ttl is <= 1. |
| 291 | Since vendors ship a lot of obsolete (DEC's Ultrix, Sun 3.x) or |
| 292 | non-standard (HPUX) software, expect to see this problem |
| 293 | frequently and/or take care picking the target host of your |
| 294 | probes. |
| 295 | |
| 296 | Other possible annotations after the time are |
| 297 | .BR !H , |
| 298 | .BR !N , |
| 299 | or |
| 300 | .B !P |
| 301 | (got a host, network or protocol unreachable, respectively), |
| 302 | .B !S |
| 303 | or |
| 304 | .B !F |
| 305 | (source route failed or fragmentation needed \- neither of these should |
| 306 | ever occur and the associated gateway is busted if you see one), |
| 307 | .B !X |
| 308 | (communication administratively prohibited), or |
| 309 | .B !<N> |
| 310 | (ICMP unreachable code N). |
| 311 | If almost all the probes result in some kind of unreachable, traceroute |
| 312 | will give up and exit. |
| 313 | .PP |
| 314 | This program is intended for use in network testing, measurement |
| 315 | and management. |
| 316 | It should be used primarily for manual fault isolation. |
| 317 | Because of the load it could impose on the network, it is unwise to use |
| 318 | .I traceroute |
| 319 | during normal operations or from automated scripts. |
| 320 | .SH SEE ALSO |
| 321 | netstat(1), ping(8) |
| 322 | .SH AUTHOR |
| 323 | Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged |
| 324 | by a cast of thousands with particularly cogent suggestions or fixes from |
| 325 | C. Philip Wood, Tim Seaver and Ken Adelman. |
| 326 | .LP |
| 327 | The current version is available via anonymous ftp: |
| 328 | .LP |
| 329 | .RS |
| 330 | .I ftp://ftp.ee.lbl.gov/traceroute.tar.Z |
| 331 | .RE |
| 332 | .SH BUGS |
| 333 | When using protocols other than UDP, functionality is reduced. |
| 334 | In particular, the last packet will often appear to be lost, because |
| 335 | even though it reaches the destination host, there's no way to know |
| 336 | that because no ICMP message is sent back. |
| 337 | In the TCP case, |
| 338 | .I traceroute |
| 339 | should listen for a RST from the destination host (or an intermediate |
| 340 | router that's filtering packets), but this is not implemented yet. |
| 341 | .PP |
| 342 | Please send bug reports to traceroute@ee.lbl.gov. |