1.\" $OpenBSD: traceroute.8,v 1.75 2022/12/23 07:16:55 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 $Mdocdate: December 23 2022 $ 37.Dt TRACEROUTE 8 38.Os 39.Sh NAME 40.Nm traceroute , 41.Nm traceroute6 42.Nd print the route packets take to network host 43.Sh SYNOPSIS 44.Nm traceroute\ \& 45.Op Fl ADdIlnSvx 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 proto 50.Op Fl p Ar port 51.Op Fl q Ar nqueries 52.Op Fl s Ar sourceaddr 53.Op Fl t Ar toskeyword 54.Op Fl V Ar rtable 55.Op Fl w Ar waittime 56.Ar host 57.Op Ar datalen 58.Nm traceroute6 59.Op Fl ADdIlnSv 60.Op Fl f Ar first_hop 61.Op Fl m Ar max_hop 62.Op Fl p Ar port 63.Op Fl q Ar nqueries 64.Op Fl s Ar sourceaddr 65.Op Fl t Ar toskeyword 66.Op Fl V Ar rtable 67.Op Fl w Ar waittime 68.Ar host 69.Op Ar datalen 70.Sh DESCRIPTION 71The Internet is a large and complex aggregation of 72network hardware, connected together by gateways. 73Tracking the route packets follow (or finding the miscreant 74gateway that's discarding packets) can be difficult. 75.Nm 76and 77.Nm traceroute6 78attempt to elicit 79.Dv TIME_EXCEEDED 80responses from each gateway along the path to 81.Ar host , 82in order to determine their route. 83.Nm 84is used for IPv4 networks and 85.Nm traceroute6 86for IPv6. 87.Pp 88The options are as follows: 89.Bl -tag -width Ds 90.It Fl A 91Look up the AS number for each hop address. 92Uses the DNS service described at 93.Lk https://www.team-cymru.com/IP-ASN-mapping.html#dns 94.It Fl D 95Dump the packet data to standard error before transmitting it. 96.It Fl d 97Turn on socket-level debugging. 98.It Fl f Ar first_ttl 99Set the first TTL or hop limit used in outgoing probe packets. 100The effect is that the first first_ttl \- 1 hosts will be skipped 101in the output of 102.Nm traceroute . 103The default is 1 (skip no hosts). 104.It Fl g Ar gateway_addr 105Add 106.Ar gateway_addr 107to the list of addresses in the IP Loose Source Record Route (LSRR) 108option. 109If no gateways are specified, the LSRR option is omitted. 110This option is not available for IPv6. 111.It Fl I 112Use ICMP or ICMP6 ECHO instead of UDP datagrams. 113.It Fl l 114Display the TTL or hop limit value of the returned packet. 115This is useful for checking for asymmetric routing. 116.It Fl m Ar max_ttl 117Set the maximum TTL or hop limit. 118The default is the value of the system's 119.Va net.inet.ip.ttl 120or 121.Va net.inet6.ip6.hlim 122.Xr sysctl 8 123variable, which defaults to 64. 124.It Fl n 125Print hop addresses numerically rather than symbolically and numerically 126(saves a nameserver address-to-name lookup for each gateway found on the 127path). 128.It Fl P Ar proto 129Change the protocol being used from UDP 130to a numeric protocol or a name as specified in 131.Pa /etc/protocols . 132This will not work reliably for most protocols. 133If set to 1 (ICMP), then 134ICMP Echo Request messages will be used (same as 135.Xr ping 8 ) . 136This option is not available for IPv6. 137.It Fl p Ar port 138Set the base UDP 139.Ar port 140number used in probes. 141The default is 33434. 142.Nm 143hopes that nothing is listening on UDP ports 144.Ar base 145to 146.Ar base Ns + Ns Ar nhops Ns * Ns Ar nqueries Ns -1 147at the destination host (so an ICMP 148.Dv PORT_UNREACHABLE 149message will 150be returned to terminate the route tracing). 151If something is 152listening on a port in the default range, this option can be used 153to pick an unused port range. 154.It Fl q Ar nqueries 155Set the number of probes per TTL to 156.Ar nqueries . 157The default is three probes. 158.It Fl S 159Print how many probes were not answered for each hop. 160.It Fl s Ar sourceaddr 161Set the source address to transmit from, which is useful on machines 162with multiple interfaces. 163.It Fl t Ar toskeyword 164Set the type-of-service (TOS) in probe packets. 165The value may be one of 166.Cm critical , 167.Cm inetcontrol , 168.Cm lowdelay , 169.Cm netcontrol , 170.Cm throughput , 171.Cm reliability , 172or one of the DiffServ Code Points: 173.Cm ef , 174.Cm af11 ... af43 , 175.Cm cs0 ... cs7 ; 176or a number in either hex or decimal. 177The default is zero. 178This option can be used to 179see if different types-of-service result in different paths. 180If this option is used, changes to the type-of-service in the 181returned packets are displayed. 182Not all values of TOS are legal or meaningful \- 183see the IP spec for definitions. 184Useful values are probably 185.Cm lowdelay 186and 187.Cm throughput . 188.It Fl V Ar rtable 189Set the routing table to be used. 190.It Fl v 191Verbose output. 192Received ICMP packets other than 193.Dv TIME_EXCEEDED 194and 195.Dv UNREACHABLE Ns s 196are listed. 197.It Fl w Ar waittime 198Set the time, in seconds, to wait for a response to a probe. 199The default is 3. 200.It Fl x 201Print the ICMP extended headers if available. 202This option is not available for IPv6. 203.It Ar host 204The destination host, 205specified as a host name or numeric IP address. 206.It Ar datalen 207The probe datagram length. 208The default is 40 bytes for IPv4 UDP 209and 60 bytes for ICMP, IPv6 UDP and ICMP6. 210.El 211.Pp 212The program attempts to trace the route an IP packet would follow to a 213host by launching UDP probe packets with a small TTL or hop limit, 214then listening for an ICMP "time exceeded" reply from a gateway. 215It starts using probes with a TTL/hop limit of one 216and increases by one until it gets an ICMP "port unreachable" 217(which means it reached the host) or hits a maximum limit 218(which defaults to 64, but can be changed using the 219.Fl m 220option). 221Three probes (the exact number can be changed using the 222.Fl q 223option) are sent and a line is printed 224showing the TTL or hop limit, address of the gateway, 225and round trip time of each probe. 226If the probe answers come from different gateways, 227the address of each responding system will be printed. 228If there is no response within a 3 second timeout 229interval (which can be changed using the 230.Fl w 231option), a "*" is printed for that 232probe. 233If the host cannot be reached, 234.Nm 235skips printing lines consisting only of * until the maximum TTL/hop limit is 236reached. 237.Pp 238We don't want the destination 239host to process the UDP 240probe packets so the destination port is set to an 241unlikely value (if some clod on the destination is using that 242value, it can be changed using the 243.Fl p 244option). 245.Pp 246A sample use and output might be: 247.Bd -literal -offset indent 248$ traceroute nis.nsf.net. 249traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 56 byte packet 2501 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 2512 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2523 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 2534 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 2545 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 2556 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 2567 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms 2578 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 2589 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms 25910 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms 26011 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 261.Ed 262.Pp 263Note that lines 2 & 3 are the same. 264This is due to a buggy 265kernel on the 2nd hop system \- lbl-csam.arpa \- that forwards 266packets with a zero TTL (a bug in the distributed version of 267.Bx 4.3 ) . 268Note that you have to guess what path 269the packets are taking cross-country since the NSFNET (129.140) 270doesn't supply address-to-name translations for its NSSes. 271.Pp 272A more interesting example is: 273.Bd -literal -offset indent 274$ traceroute allspice.lcs.mit.edu. 275traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max 2761 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 2772 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 2783 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 2794 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 2805 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 2816 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 2827 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms 2838 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 2849 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms 28510 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms 28611 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 28712 * * * 28813 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms 28914 * * * 29015 * * * 29116 * * * 29217 * * * 29318 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 294.Ed 295.Pp 296Note that the gateways 12, 14, 15, 16 & 17 hops away 297either don't send ICMP "time exceeded" messages or send them 298with a TTL too small to reach us. 29914 \- 17 are running the MIT 300C Gateway code that doesn't send "time exceeded"s. 301God only knows what's going on with 12. 302.Pp 303The silent gateway 12 in the above may be the result of a bug in 304the 4.[23] 305.Bx 306network code (and its derivatives): 4.x (x <= 3) 307sends an unreachable message using whatever TTL remains in the 308original datagram. 309Since, for gateways, the remaining TTL is zero, the ICMP 310"time exceeded" is guaranteed to not make it back to us. 311The behavior of this bug is slightly more interesting 312when it appears on the destination system: 313.Bd -literal -offset indent 3141 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 3152 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 3163 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 3174 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 3185 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 3196 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 3207 * * * 3218 * * * 3229 * * * 32310 * * * 32411 * * * 32512 * * * 32613 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! 327.Ed 328.Pp 329Notice that there are 12 "gateways" (13 is the final 330destination) and exactly the last half of them are "missing". 331What's really happening is that rip (a Sun-3 running Sun OS3.5) 332is using the TTL from our arriving datagram as the TTL in its 333ICMP reply. 334So, the reply will time out on the return path 335(with no notice sent to anyone since ICMPs aren't sent for ICMPs) 336until we probe with a TTL that's at least twice the path 337length. 338That is, rip is really only 7 hops away. 339A reply that returns with a TTL of 1 is a clue this problem exists. 340.Nm 341prints a "!" after the time if the TTL is <= 1. 342Since vendors ship a lot of obsolete (DEC's Ultrix, Sun 3.x) or 343non-standard (HP-UX) software, expect to see this problem 344frequently and/or take care picking the target host of your 345probes. 346.Pp 347Other possible annotations after the time are 348.Sy !H , 349.Sy !N , 350.Sy !P 351(got a host, network or protocol unreachable, respectively), 352.Sy !A , 353.Sy !C 354(access to the network or host, respectively, is prohibited), 355.Sy !X 356(communication administratively prohibited by filtering), 357.Sy !S 358or 359.Sy !F 360(source route failed or fragmentation needed \- neither of these should 361ever occur and the associated gateway is busted if you see one), 362.Sy !U 363(destination network or host unknown), 364.Sy !T 365(destination network or host unreachable for TOS), 366.Sy !<code> 367(other ICMP unreachable code). 368.Sy TOS=xxx! 369(TOS bit in returned packet differs from last hop). 370If almost all the probes result in some kind of unreachable, 371.Nm 372will give up and exit. 373.Pp 374.Dl $ traceroute -g 10.3.0.5 128.182.0.0 375.Pp 376will show the path from the Cambridge Mailbridge to PSC, while 377.Pp 378.Dl $ traceroute -g 192.5.146.4 -g 10.3.0.5 35.0.0.0 379.Pp 380will show the path from the Cambridge Mailbridge to Merit, using PSC to 381reach the Mailbridge. 382.Pp 383This program is intended for use in network testing, measurement 384and management. 385It should be used primarily for manual fault isolation. 386Because of the load it could impose on the network, it is unwise to use 387.Nm 388during normal operations or from automated scripts. 389.Sh SEE ALSO 390.Xr ping 8 , 391.Xr route 8 392.Sh HISTORY 393The very first 394.Nm 395(never released) used ICMP ECHO_REQUEST 396datagrams as probe packets. 397During the first night of testing it was 398discovered that more than half the router vendors of the time would 399not return an ICMP TIME_EXCEEDED for an ECHO_REQUEST. 400.Nm 401was then changed to use UDP probe packets. 402Most modern TCP/IP implementations will now generate an ICMP error 403message to ICMP query messages, and the option to use ECHO_REQUEST probes 404was re-implemented. 405.Pp 406The 407.Nm 408command first appeared in 409.Bx 4.3 Reno . 410The 411.Nm traceroute6 412command first appeared in the WIDE Hydrangea IPv6 protocol stack kit. 413.Sh AUTHORS 414.An -nosplit 415Implemented by 416.An Van Jacobson 417from a suggestion by 418.An Steve Deering . 419Debugged 420by a cast of thousands with particularly cogent suggestions or fixes from 421.An C. Philip Wood , 422.An Tim Seaver , 423and 424.An Ken Adelman . 425