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.Dd June 26, 2020 37.Dt TRACEROUTE 8 38.Os 39.Sh NAME 40.Nm traceroute 41.Nd print the route packets take to network host 42.Sh SYNOPSIS 43.Nm 44.Bk -words 45.Op Fl cdDIlMnrSv 46.Op Fl f Ar first_ttl 47.Op Fl g Ar gateway_addr 48.Op Fl m Ar max_ttl 49.Op Fl p Ar port 50.Op Fl P Ar proto 51.Op Fl q Ar nqueries 52.Op Fl s Ar src_addr 53.Op Fl t Ar tos 54.Op Fl w Ar waittime 55.Ar host 56.Op Ar packetsize 57.Ek 58.Sh DESCRIPTION 59The Internet is a large and complex aggregation of 60network hardware, connected together by gateways. 61Tracking the route one's packets follow (or finding the miscreant 62gateway that's discarding your packets) can be difficult. 63.Nm 64utilizes the IP protocol `time to live' field and attempts to elicit an 65.Tn ICMP 66.Dv TIME_EXCEEDED 67response from each gateway along the path to some 68host. 69.Pp 70The only mandatory parameter is the destination host name or IP number. 71The default probe datagram length is 38 bytes, but this may be increased 72by specifying a packet size (in bytes) after the destination host 73name. 74.Pp 75The options are as follows: 76.Bl -tag -width Ds 77.It Fl c 78Do not increment the destination port number in successive UDP packets. 79Rather, all UDP packets will have the same destination port, as set via the 80.Fl p 81flag (or 33434 if none is specified). 82.It Fl d 83Turn on socket-level debugging. 84.It Fl D 85Dump the packet data to standard error before transmitting it. 86.It Fl f Ar first_ttl 87Set the first time-to-live used in outgoing probe packets. The effect is that 88the first first_ttl - 1 hosts will be skipped in the output of 89.Nm . 90The default value is 1 (skip no hosts). 91.It Fl g Ar gateway_addr 92Add 93.Ar gateway_addr 94to the list of addresses in the IP Loose Source Record Route (LSRR) 95option. 96If no gateways are specified, the LSRR option is omitted. 97.It Fl I 98Equivalent to 99.Fl P 1001. 101Used for compatibility with other OSes. 102.It Fl l 103Display the ttl value of the returned packet. 104This is useful for checking for asymmetric routing. 105.It Fl m Ar max_ttl 106Set the max time-to-live (max number of hops) used in outgoing probe 107packets. 108The default is the value of the system's 109.Va net.inet.ip.ttl 110MIB variable, which defaults to 64. 111.It Fl M 112If found, show the MPLS Label and the Experimental (EXP) bit for the hop. 113.It Fl n 114Print hop addresses numerically rather than symbolically and numerically 115(saves a nameserver address-to-name lookup for each gateway found on the 116path). 117.It Fl p Ar port 118Set the base 119.Tn UDP 120.Ar port 121number used in probes (default is 33434). 122.Nm 123hopes that nothing is listening on 124.Tn UDP 125ports 126.Em base 127to 128.Em base+nhops*nqueries-1 129at the destination host (so an 130.Tn ICMP 131.Dv PORT_UNREACHABLE 132message will 133be returned to terminate the route tracing). 134If something is 135listening on a port in the default range, this option can be used 136to pick an unused port range. 137.It Fl P Ar proto 138Change the protocol being used from 139.Tn UDP 140to a numeric protocol or a name as specified in 141.Pa /etc/protocols . 142This will not work reliably for most protocols. 143If set to 1 (ICMP), then 144ICMP Echo Request messages will be used (same as 145.Xr ping 8 ) . 146.It Fl q Ar nqueries 147Set the number of probes per ``ttl'' to 148.Ar nqueries 149(default is three probes). 150.It Fl r 151Bypass the normal routing tables and send directly to a host on an attached 152network. 153If the host is not on a directly attached network, 154an error is returned. 155This option can be used to ping a local host through an interface 156that has no route through it (e.g., after the interface was dropped by 157.Xr routed 8 ) . 158.It Fl s Ar src_addr 159Use the following IP address 160(which must be given as an IP number, not 161a hostname) as the source address in outgoing probe packets. 162On hosts with more than one IP address, this option can be used to 163force the source address to be something other than the IP address 164of the interface the probe packet is sent on. 165If the IP address 166is not one of this machine's interface addresses and the user is 167not the superuser, an error is returned and nothing is sent. 168.It Fl S 169Print how many probes were not answered for each hop. 170.It Fl t Ar tos 171Set the 172.Em type-of-service 173in probe packets to the following value (default zero). 174The value must be a decimal integer in the range 0 to 255. 175This option can be used to 176see if different types-of-service result in different paths. 177(If you are not running a 178.Bx 4.3 tahoe 179or later system, this may be academic since the normal network 180services like telnet and ftp don't let you control the 181.Dv TOS ) . 182Not all values of 183.Dv TOS 184are legal or 185meaningful \- see the IP spec for definitions. 186Useful values are probably 187.Ql -t 16 188(low delay) and 189.Ql -t 8 190(high throughput). 191.It Fl v 192Verbose output. 193Received 194.Tn ICMP 195packets other than 196.Dv TIME_EXCEEDED 197and 198.Dv UNREACHABLE Ns s 199are listed. 200.It Fl w Ar waittime 201Set the time (in seconds) to wait for a response to a probe (default 3). 202.El 203.Pp 204This program attempts to trace the route an IP packet would follow to some 205internet host by launching 206.Tn UDP 207probe 208packets with a small ttl (time to live) then listening for an 209.Tn ICMP 210"time exceeded" reply from a gateway. 211We start out probes with a ttl of one and increase by one until we get an 212.Tn ICMP 213"port unreachable" 214(which means we got to "host") or hit a max (which 215defaults to 64 hops and can be changed with the 216.Fl m 217flag). 218Three probes (changed with 219.Fl q 220flag) are sent at each ttl setting and a 221line is printed showing the ttl, address of the gateway and 222round trip time of each probe. 223If the probe answers come from 224different gateways, the address of each responding system will 225be printed. 226If there is no response within a 5 sec. timeout 227interval (changed with the 228.Fl w 229flag), a "*" is printed for that 230probe. 231.Pp 232We don't want the destination 233host to process the 234.Tn UDP 235probe packets so the destination port is set to an 236unlikely value (if some clod on the destination is using that 237value, it can be changed with the 238.Fl p 239flag). 240.Pp 241A sample use and output might be: 242.Bd -literal -offset indent 243$ traceroute nis.nsf.net. 244traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 56 byte packet 2451 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 2462 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2473 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2484 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 2495 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 2506 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 2517 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms 2528 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 2539 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms 25410 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms 25511 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 256.Ed 257.Pp 258Note that lines 2 & 3 are the same. 259This is due to a buggy 260kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- that forwards 261packets with a zero ttl (a bug in the distributed version 262of 4.3 263.Tn BSD ) . 264Note that you have to guess what path 265the packets are taking cross-country since the 266.Tn NSFNET 267(129.140) 268doesn't supply address-to-name translations for its 269.Tn NSS Ns es . 270.Pp 271A more interesting example is: 272.Bd -literal -offset indent 273$ traceroute allspice.lcs.mit.edu. 274traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max 2751 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 2762 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 2773 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 2784 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 2795 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 2806 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 2817 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms 2828 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 2839 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms 28410 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms 28511 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 28612 * * * 28713 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms 28814 * * * 28915 * * * 29016 * * * 29117 * * * 29218 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 293.Ed 294.Pp 295Note that the gateways 12, 14, 15, 16 & 17 hops away 296either don't send 297.Tn ICMP 298"time exceeded" messages or send them 299with a ttl too small to reach us. 30014 \- 17 are running the 301.Tn MIT 302C Gateway code that doesn't send "time exceeded"s. 303God only knows what's going on with 12. 304.Pp 305The silent gateway 12 in the above may be the result of a bug in 306the 4.[23] 307.Tn BSD 308network code (and its derivatives): 4.x (x \(<= 3) 309sends an unreachable message using whatever ttl remains in the 310original datagram. 311Since, for gateways, the remaining ttl is zero, the 312.Tn ICMP 313"time exceeded" is guaranteed to not make it back to us. 314The behavior of this bug is slightly more interesting 315when it appears on the destination system: 316.Bd -literal -offset indent 3171 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 3182 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 3193 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 3204 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 3215 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 3226 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 3237 * * * 3248 * * * 3259 * * * 32610 * * * 32711 * * * 32812 * * * 32913 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! 330.Ed 331.Pp 332Notice that there are 12 "gateways" (13 is the final 333destination) and exactly the last half of them are "missing". 334What's really happening is that rip (a Sun-3 running Sun OS3.5) 335is using the ttl from our arriving datagram as the ttl in its 336.Tn ICMP 337reply. 338So, the reply will time out on the return path 339(with no notice sent to anyone since 340.Tn ICMP's 341aren't sent for 342.Tn ICMP's ) 343until we probe with a ttl that's at least twice the path 344length. 345i.e., rip is really only 7 hops away. 346A reply that returns with a ttl of 1 is a clue this problem exists. 347.Nm 348prints a "!" after the time if the ttl is \(<= 1. 349Since vendors ship a lot of obsolete 350.Pf ( Tn DEC Ns \'s 351Ultrix, Sun 3.x) or 352non-standard 353.Pq Tn HP-UX 354software, expect to see this problem 355frequently and/or take care picking the target host of your 356probes. 357.Pp 358Other possible annotations after the time are 359.Sy !H , 360.Sy !N , 361.Sy !P 362(got a host, network or protocol unreachable, respectively), 363.Sy !A , 364.Sy !C 365(access to the network or host, respectively, is prohibited), 366.Sy !X 367(communication administratively prohibited by filtering), 368.Sy !S 369or 370.Sy !F 371(source route failed or fragmentation needed \- neither of these should 372ever occur and the associated gateway is busted if you see one), 373.Sy !U 374(destination network or host unknown), 375.Sy !T 376(destination network or host unreachable for TOS), 377.Sy !<code> 378(other ICMP unreachable code). 379If almost all the probes result in some kind of unreachable, 380.Nm 381will give up and exit. 382.Pp 383.Dl $ traceroute -g 10.3.0.5 128.182.0.0 384.Pp 385will show the path from the Cambridge Mailbridge to PSC, while 386.Pp 387.Dl $ traceroute -g 192.5.146.4 -g 10.3.0.5 35.0.0.0 388.Pp 389will show the path from the Cambridge Mailbridge to Merit, using PSC to 390reach the Mailbridge. 391.Pp 392This program is intended for use in network testing, measurement 393and management. 394It should be used primarily for manual fault isolation. 395Because of the load it could impose on the network, it is unwise to use 396.Nm 397during normal operations or from automated scripts. 398.Sh SEE ALSO 399.Xr netstat 1 , 400.Xr ping 8 , 401.Xr ping6 8 , 402.Xr traceroute6 8 403.Sh HISTORY 404The very first 405.Nm 406(never released) used ICMP ECHO_REQUEST 407datagrams as probe packets. During the first night of testing it was 408discovered that more than half the router vendors of the time would 409not return an ICMP TIME_EXCEEDED for an ECHO_REQUEST. 410.Nm 411was then changed to use UDP probe packets. 412Most modern TCP/IP implementations will now generate an ICMP error 413message to ICMP query messages, and the option to use ECHO_REQUEST probes 414was re-implemented. 415.Pp 416The 417.Nm 418command first appeared in 419.Bx 4.4 . 420.Sh AUTHORS 421.An -nosplit 422Implemented by 423.An Van Jacobson 424from a suggestion by 425.An Steve Deering . 426Debugged 427by a cast of thousands with particularly cogent suggestions or fixes from 428.An C. Philip Wood , 429.An Tim Seaver 430and 431.An Ken Adelman . 432