1.\" $OpenBSD: traceroute.8,v 1.36 2003/08/27 08:17:33 jmc Exp $ 2.\" $NetBSD: traceroute.8,v 1.6 1995/10/12 03:05:50 mycroft Exp $ 3.\" 4.\" Copyright (c) 1990, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" This code is derived from software contributed to Berkeley by 8.\" Van Jacobson. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)traceroute.8 8.1 (Berkeley) 6/6/93 35.\" 36.\" $DragonFly: src/usr.sbin/traceroute/traceroute.8,v 1.3 2006/02/28 02:25:11 swildner Exp $ 37.Dd June 6, 1993 38.Dt TRACEROUTE 8 39.Os 40.Sh NAME 41.Nm traceroute 42.Nd print the route packets take to network host 43.Sh SYNOPSIS 44.Nm traceroute 45.Bk -words 46.Op Fl cdDIlnrSv 47.Op Fl f Ar first_ttl 48.Op Fl g Ar gateway_addr 49.Op Fl m Ar max_ttl 50.Op Fl p Ar port 51.Op Fl P Ar proto 52.Op Fl q Ar nqueries 53.Op Fl s Ar src_addr 54.Op Fl t Ar tos 55.Op Fl w Ar waittime 56.Ar host 57.Op Ar packetsize 58.Ek 59.Sh DESCRIPTION 60The Internet is a large and complex aggregation of 61network hardware, connected together by gateways. 62Tracking the route one's packets follow (or finding the miscreant 63gateway that's discarding your packets) can be difficult. 64.Nm 65utilizes the IP protocol `time to live' field and attempts to elicit an 66.Tn ICMP 67.Dv TIME_EXCEEDED 68response from each gateway along the path to some 69host. 70.Pp 71The only mandatory parameter is the destination host name or IP number. 72The default probe datagram length is 38 bytes, but this may be increased 73by specifying a packet size (in bytes) after the destination host 74name. 75.Pp 76The options are as follows: 77.Bl -tag -width Ds 78.It Fl c 79Do not increment the destination port number in successive UDP packets. 80Rather, all UDP packets will have the same destination port, as set via the 81.Fl p 82flag (or 33434 if none is specified). 83.It Fl d 84Turn on socket-level debugging. 85.It Fl D 86Dump the packet data to standard error before transmitting it. 87.It Fl f Ar first_ttl 88Set the first time-to-live used in outgoing probe packets. The effect is that 89the first first_ttl - 1 hosts will be skipped in the output of 90.Nm traceroute . 91The default value is 1 (skip no hosts). 92.It Fl g Ar gateway_addr 93Add 94.Ar gateway_addr 95to the list of addresses in the IP Loose Source Record Route (LSRR) 96option. 97If no gateways are specified, the LSRR option is omitted. 98.It Fl I 99Equivalent to 100.Fl P 1011. 102Used for compatibility with other OSes. 103.It Fl l 104Display the ttl value of the returned packet. 105This is useful for checking for asymmetric routing. 106.It Fl m Ar max_ttl 107Set the max time-to-live (max number of hops) used in outgoing probe 108packets. 109The default is the value of the system's 110.Cm net.inet.ip.ttl 111MIB variable, which defaults to 64. 112.It Fl n 113Print hop addresses numerically rather than symbolically and numerically 114(saves a nameserver address-to-name lookup for each gateway found on the 115path). 116.It Fl p Ar port 117Set the base 118.Tn UDP 119.Ar port 120number used in probes (default is 33434). 121.Nm 122hopes that nothing is listening on 123.Tn UDP 124ports 125.Em base 126to 127.Em base+nhops*nqueries-1 128at the destination host (so an 129.Tn ICMP 130.Dv PORT_UNREACHABLE 131message will 132be returned to terminate the route tracing). 133If something is 134listening on a port in the default range, this option can be used 135to pick an unused port range. 136.It Fl P Ar proto 137Change the protocol being used from 138.Tn UDP 139to a numeric protocol or a name as specified in 140.Pa /etc/protocols . 141This will not work reliably for most protocols. 142If set to 1 (ICMP), then 143ICMP Echo Request messages will be used (same as 144.Xr ping 8 ) . 145.It Fl q Ar nqueries 146Set the number of probes per ``ttl'' to 147.Ar nqueries 148(default is three probes). 149.It Fl r 150Bypass the normal routing tables and send directly to a host on an attached 151network. 152If the host is not on a directly attached network, 153an error is returned. 154This option can be used to ping a local host through an interface 155that has no route through it (e.g., after the interface was dropped by 156.Xr routed 8 ) . 157.It Fl s Ar src_addr 158Use the following IP address 159(which must be given as an IP number, not 160a hostname) as the source address in outgoing probe packets. 161On hosts with more than one IP address, this option can be used to 162force the source address to be something other than the IP address 163of the interface the probe packet is sent on. 164If the IP address 165is not one of this machine's interface addresses and the user is 166not the superuser, an error is returned and nothing is sent. 167.It Fl S 168Print how many probes were not answered for each hop. 169.It Fl t Ar tos 170Set the 171.Em type-of-service 172in probe packets to the following value (default zero). 173The value must be a decimal integer in the range 0 to 255. 174This option can be used to 175see if different types-of-service result in different paths. 176(If you are not running a 177.Bx 4.3 tahoe 178or later system, this may be academic since the normal network 179services like telnet and ftp don't let you control the 180.Dv TOS ) . 181Not all values of 182.Dv TOS 183are legal or 184meaningful \- see the IP spec for definitions. 185Useful values are probably 186.Ql -t 16 187(low delay) and 188.Ql -t 8 189(high throughput). 190.It Fl v 191Verbose output. 192Received 193.Tn ICMP 194packets other than 195.Dv TIME_EXCEEDED 196and 197.Dv UNREACHABLE Ns s 198are listed. 199.It Fl w Ar waittime 200Set the time (in seconds) to wait for a response to a probe (default 3). 201.El 202.Pp 203This program attempts to trace the route an IP packet would follow to some 204internet host by launching 205.Tn UDP 206probe 207packets with a small ttl (time to live) then listening for an 208.Tn ICMP 209"time exceeded" reply from a gateway. 210We start out probes with a ttl of one and increase by one until we get an 211.Tn ICMP 212"port unreachable" 213(which means we got to "host") or hit a max (which 214defaults to 64 hops and can be changed with the 215.Fl m 216flag). 217Three probes (changed with 218.Fl q 219flag) are sent at each ttl setting and a 220line is printed showing the ttl, address of the gateway and 221round trip time of each probe. 222If the probe answers come from 223different gateways, the address of each responding system will 224be printed. 225If there is no response within a 5 sec. timeout 226interval (changed with the 227.Fl w 228flag), a "*" is printed for that 229probe. 230.Pp 231We don't want the destination 232host to process the 233.Tn UDP 234probe packets so the destination port is set to an 235unlikely value (if some clod on the destination is using that 236value, it can be changed with the 237.Fl p 238flag). 239.Pp 240A sample use and output might be: 241.Bd -literal -offset indent 242$ traceroute nis.nsf.net. 243traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 56 byte packet 2441 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 2452 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2463 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2474 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 2485 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 2496 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 2507 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms 2518 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 2529 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms 25310 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms 25411 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 255.Ed 256.Pp 257Note that lines 2 & 3 are the same. 258This is due to a buggy 259kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- that forwards 260packets with a zero ttl (a bug in the distributed version 261of 4.3 262.Tn BSD ) . 263Note that you have to guess what path 264the packets are taking cross-country since the 265.Tn NSFNET 266(129.140) 267doesn't supply address-to-name translations for its 268.Tn NSS Ns es . 269.Pp 270A more interesting example is: 271.Bd -literal -offset indent 272$ traceroute allspice.lcs.mit.edu. 273traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max 2741 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 2752 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 2763 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 2774 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 2785 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 2796 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 2807 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms 2818 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 2829 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms 28310 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms 28411 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 28512 * * * 28613 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms 28714 * * * 28815 * * * 28916 * * * 29017 * * * 29118 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 292.Ed 293.Pp 294Note that the gateways 12, 14, 15, 16 & 17 hops away 295either don't send 296.Tn ICMP 297"time exceeded" messages or send them 298with a ttl too small to reach us. 29914 \- 17 are running the 300.Tn MIT 301C Gateway code that doesn't send "time exceeded"s. 302God only knows what's going on with 12. 303.Pp 304The silent gateway 12 in the above may be the result of a bug in 305the 4.[23] 306.Tn BSD 307network code (and its derivatives): 4.x (x \(<= 3) 308sends an unreachable message using whatever ttl remains in the 309original datagram. 310Since, for gateways, the remaining ttl is zero, the 311.Tn ICMP 312"time exceeded" is guaranteed to not make it back to us. 313The behavior of this bug is slightly more interesting 314when it appears on the destination system: 315.Bd -literal -offset indent 3161 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 3172 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 3183 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 3194 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 3205 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 3216 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 3227 * * * 3238 * * * 3249 * * * 32510 * * * 32611 * * * 32712 * * * 32813 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! 329.Ed 330.Pp 331Notice that there are 12 "gateways" (13 is the final 332destination) and exactly the last half of them are "missing". 333What's really happening is that rip (a Sun-3 running Sun OS3.5) 334is using the ttl from our arriving datagram as the ttl in its 335.Tn ICMP 336reply. 337So, the reply will time out on the return path 338(with no notice sent to anyone since 339.Tn ICMP's 340aren't sent for 341.Tn ICMP's ) 342until we probe with a ttl that's at least twice the path 343length. 344i.e., rip is really only 7 hops away. 345A reply that returns with a ttl of 1 is a clue this problem exists. 346.Nm 347prints a "!" after the time if the ttl is \(<= 1. 348Since vendors ship a lot of obsolete 349.Pf ( Tn DEC Ns \'s 350Ultrix, Sun 3.x) or 351non-standard 352.Pq Tn HP-UX 353software, expect to see this problem 354frequently and/or take care picking the target host of your 355probes. 356.Pp 357Other possible annotations after the time are 358.Sy !H , 359.Sy !N , 360.Sy !P 361(got a host, network or protocol unreachable, respectively), 362.Sy !A , 363.Sy !C 364(access to the network or host, respectively, is prohibited), 365.Sy !X 366(communication administratively prohibited by filtering), 367.Sy !S 368or 369.Sy !F 370(source route failed or fragmentation needed \- neither of these should 371ever occur and the associated gateway is busted if you see one), 372.Sy !U 373(destination network or host unknown), 374.Sy !T 375(destination network or host unreachable for TOS), 376.Sy !<code> 377(other ICMP unreachable code). 378If almost all the probes result in some kind of unreachable, 379.Nm 380will give up and exit. 381.Pp 382.Dl $ traceroute -g 10.3.0.5 128.182.0.0 383.Pp 384will show the path from the Cambridge Mailbridge to PSC, while 385.Pp 386.Dl $ traceroute -g 192.5.146.4 -g 10.3.0.5 35.0.0.0 387.Pp 388will show the path from the Cambridge Mailbridge to Merit, using PSC to 389reach the Mailbridge. 390.Pp 391This program is intended for use in network testing, measurement 392and management. 393It should be used primarily for manual fault isolation. 394Because of the load it could impose on the network, it is unwise to use 395.Nm 396during normal operations or from automated scripts. 397.Sh SEE ALSO 398.Xr netstat 1 , 399.Xr ping 8 400.Sh HISTORY 401The very first 402.Nm 403(never released) used ICMP ECHO_REQUEST 404datagrams as probe packets. During the first night of testing it was 405discovered that more than half the router vendors of the time would 406not return an ICMP TIME_EXCEEDED for an ECHO_REQUEST. 407.Nm 408was then changed to use UDP probe packets. 409Most modern TCP/IP implementations will now generate an ICMP error 410message to ICMP query messages, and the option to use ECHO_REQUEST probes 411was re-implemented. 412.Pp 413The 414.Nm 415command first appeared in 416.Bx 4.4 . 417.Sh AUTHORS 418Implemented by Van Jacobson from a suggestion by Steve Deering. 419Debugged 420by a cast of thousands with particularly cogent suggestions or fixes from 421C. Philip Wood, Tim Seaver and Ken Adelman. 422