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