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 58The Internet is a large and complex aggregation of 59network hardware, connected together by gateways. 60Tracking the route one's packets follow (or finding the miscreant 61gateway that's discarding your packets) can be difficult. 62.Nm Traceroute 63utilizes the IP protocol `time to live' field and attempts to elicit an 64.Tn ICMP 65.Dv TIME_EXCEEDED 66response from each gateway along the path to some 67host. 68.Pp 69The only mandatory parameter is the destination host name or IP number. 70The default probe datagram length is 38 bytes, but this may be increased 71by specifying a packet size (in bytes) after the destination host 72name. 73.Pp 74Other options are: 75.Bl -tag -width Ds 76.It Fl m Ar max_ttl 77Set the max time-to-live (max number of hops) used in outgoing probe 78packets. The default is 30 hops (the same default used for 79.Tn TCP 80connections). 81.It Fl n 82Print hop addresses numerically rather than symbolically and numerically 83(saves a nameserver address-to-name lookup for each gateway found on the 84path). 85.It Fl p Ar port 86Set the base 87.Tn UDP 88.Ar port 89number used in probes (default is 33434). 90.Nm Traceroute 91hopes that nothing is listening on 92.Tn UDP 93ports 94.Em base 95to 96.Em base+nhops-1 97at the destination host (so an 98.Tn ICMP 99.Dv PORT_UNREACHABLE 100message will 101be returned to terminate the route tracing). If something is 102listening on a port in the default range, this option can be used 103to pick an unused port range. 104.It Fl q Ar nqueries 105Set the number of probes per ``ttl'' to 106.Ar nqueries 107(default is three probes). 108.It Fl r 109Bypass the normal routing tables and send directly to a host on an attached 110network. 111If the host is not on a directly-attached network, 112an error is returned. 113This option can be used to ping a local host through an interface 114that has no route through it (e.g., after the interface was dropped by 115.Xr routed 8 ) . 116.It Fl s Ar src_addr 117Use the following IP address 118(which must be given as an IP number, not 119a hostname) as the source address in outgoing probe packets. On 120hosts with more than one IP address, this option can be used to 121force the source address to be something other than the IP address 122of the interface the probe packet is sent on. If the IP address 123is not one of this machine's interface addresses, an error is 124returned and nothing is sent. 125.It Fl t Ar tos 126Set the 127.Em type-of-service 128in probe packets to the following value (default zero). The value must be 129a decimal integer in the range 0 to 255. This option can be used to 130see if different types-of-service result in different paths. (If you 131are not running a 132.Bx 4.3 tahoe 133or later system, this may be academic since the normal network 134services like telnet and ftp don't let you control the 135.Dv TOS ) . 136Not all values of 137.Dv TOS 138are legal or 139meaningful \- see the IP spec for definitions. Useful values are 140probably 141.Ql \-t 16 142(low delay) and 143.Ql \-t 8 144(high throughput). 145.It Fl v 146Verbose output. Received 147.Tn ICMP 148packets other than 149.Dv TIME_EXCEEDED 150and 151.Dv UNREACHABLE Ns s 152are listed. 153.It Fl w 154Set the time (in seconds) to wait for a response to a probe (default 3 155sec.). 156.El 157.Pp 158This program attempts to trace the route an IP packet would follow to some 159internet host by launching 160.Tn UDP 161probe 162packets 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 165with 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 169defaults to 30 hops & can be changed with the 170.Fl m 171flag). Three 172probes (changed with 173.Fl q 174flag) are sent at each ttl setting and a 175line is printed showing the ttl, address of the gateway and 176round trip time of each probe. If the probe answers come from 177different gateways, the address of each responding system will 178be printed. If there is no response within a 3 sec. timeout 179interval (changed with the 180.Fl w 181flag), a "*" is printed for that 182probe. 183.Pp 184We don't want the destination 185host to process the 186.Tn UDP 187probe packets so the destination port is set to an 188unlikely value (if some clod on the destination is using that 189value, it can be changed with the 190.Fl p 191flag). 192.Pp 193A sample use and output might be: 194.Bd -literal 195[yak 71]% traceroute nis.nsf.net. 196traceroute to nis.nsf.net (35.1.1.48), 30 hops max, 56 byte packet 1971 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 1982 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 1993 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2004 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 2015 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 2026 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 2037 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms 2048 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 2059 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms 20610 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms 20711 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 208 209.Ed 210Note that lines 2 & 3 are the same. This is due to a buggy 211kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards 212packets with a zero ttl (a bug in the distributed version 213of 4.3 214.Tn BSD ) . 215Note that you have to guess what path 216the packets are taking cross-country since the 217.Tn NSFNet 218(129.140) 219doesn't supply address-to-name translations for its 220.Tn NSS Ns es . 221.Pp 222A more interesting example is: 223.Bd -literal 224[yak 72]% traceroute allspice.lcs.mit.edu. 225traceroute to allspice.lcs.mit.edu (18.26.0.115), 30 hops max 2261 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 2272 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 2283 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 2294 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 2305 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 2316 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 2327 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms 2338 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 2349 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms 23510 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms 23611 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 23712 * * * 23813 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms 23914 * * * 24015 * * * 24116 * * * 24217 * * * 24318 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 244 245.Ed 246Note that the gateways 12, 14, 15, 16 & 17 hops away 247either don't send 248.Tn ICMP 249"time exceeded" messages or send them 250with a ttl too small to reach us. 14 \- 17 are running the 251.Tn MIT 252C Gateway code that doesn't send "time exceeded"s. God 253only knows what's going on with 12. 254.Pp 255The silent gateway 12 in the above may be the result of a bug in 256the 4.[23] 257.Tn BSD 258network code (and its derivatives): 4.x (x <= 3) 259sends an unreachable message using whatever ttl remains in the 260original datagram. Since, for gateways, the remaining ttl is 261zero, the 262.Tn ICMP 263"time exceeded" is guaranteed to not make it back 264to us. The behavior of this bug is slightly more interesting 265when it appears on the destination system: 266.Bd -literal 2671 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 2682 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 2693 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 2704 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 2715 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 2726 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 2737 * * * 2748 * * * 2759 * * * 27610 * * * 27711 * * * 27812 * * * 27913 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! 280 281.Ed 282Notice that there are 12 "gateways" (13 is the final 283destination) and exactly the last half of them are "missing". 284What's really happening is that rip (a Sun-3 running Sun OS3.5) 285is using the ttl from our arriving datagram as the ttl in its 286.Tn ICMP 287reply. So, the reply will time out on the return path 288(with no notice sent to anyone since 289.Tn ICMP's 290aren't sent for 291.Tn ICMP's ) 292until we probe with a ttl that's at least twice the path 293length. I.e., rip is really only 7 hops away. A reply that 294returns with a ttl of 1 is a clue this problem exists. 295.Nm Traceroute 296prints a "!" after the time if the ttl is <= 1. 297Since vendors ship a lot of obsolete 298.Pf ( Tn DEC Ns \'s 299Ultrix, Sun 3.x) or 300non-standard 301.Pq Tn HPUX 302software, expect to see this problem 303frequently and/or take care picking the target host of your 304probes. 305Other 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 311or 312.Sy !F 313(source route failed or fragmentation needed \- neither of these should 314ever occur and the associated gateway is busted if you see one). If 315almost all the probes result in some kind of unreachable, 316.Nm traceroute 317will give up and exit. 318.Pp 319This program is intended for use in network testing, measurement 320and management. 321It should be used primarily for manual fault isolation. 322Because of the load it could impose on the network, it is unwise to use 323.Nm traceroute 324during normal operations or from automated scripts. 325.Sh AUTHOR 326Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged 327by a cast of thousands with particularly cogent suggestions or fixes from 328C. Philip Wood, Tim Seaver and Ken Adelman. 329.Sh SEE ALSO 330.Xr netstat 1 , 331.Xr ping 8 332.Sh HISTORY 333The 334.Nm 335command 336.Bt 337