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