1.\" Copyright (c) 1989, 1995, 1996, 1997, 1999, 2000 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms are permitted 5.\" provided that the above copyright notice and this paragraph are 6.\" duplicated in all such forms and that any documentation, 7.\" advertising materials, and other materials related to such 8.\" distribution and use acknowledge that the software was developed 9.\" by the University of California, Berkeley. The name of the 10.\" University may not be used to endorse or promote products derived 11.\" from this software without specific prior written permission. 12.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR 13.\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED 14.\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. 15.\" 16.\" $Id: traceroute.8,v 1.19 2000/09/21 08:44:19 leres Exp $ 17.\" 18.Dd November 17, 2023 19.Dt TRACEROUTE 8 20.Os 21.Sh NAME 22.Nm traceroute 23.Nd "print the route packets take to network host" 24.Sh SYNOPSIS 25.Nm 26.Bk -words 27.Op Fl adDeEFISnrvx 28.Op Fl A Ar as_server 29.Op Fl f Ar first_ttl 30.Op Fl g Ar gateway 31.Op Fl i Ar iface 32.Op Fl m Ar max_ttl 33.Op Fl M Ar first_ttl 34.Op Fl p Ar port 35.Op Fl P Ar proto 36.Op Fl q Ar nprobes 37.Op Fl s Ar src_addr 38.Op Fl t Ar tos 39.Op Fl w Ar waittime 40.Op Fl z Ar pausemsecs 41.Ar host 42.Op Ar packetlen 43.Ek 44.Sh DESCRIPTION 45The Internet is a large and complex aggregation of network hardware, connected 46together by gateways. 47Tracking the route one's packets follow (or finding the miscreant gateway 48that's discarding your packets) can be difficult. 49.Nm 50utilizes the IP protocol `time to live' field and attempts to elicit an ICMP 51TIME_EXCEEDED response from each gateway along the path to some host. 52.Pp 53The only mandatory parameter is the destination host name or IP number. 54The default probe datagram length is 40 bytes, but this may be increased by 55specifying a packet length (in bytes) after the destination host name. 56.Pp 57Other options are: 58.Bl -tag -width Ds 59.It Fl a 60Turn on AS# lookups for each hop encountered. 61.It Fl A Ar as_server 62Turn on AS# lookups and use the given server instead of the default. 63.It Fl d 64Enable socket level debugging. 65.It Fl D 66When an ICMP response to our probe datagram is received, print the differences 67between the transmitted packet and the packet quoted by the ICMP response. 68A key showing the location of fields within the transmitted packet is printed, 69followed by the original packet in hex, followed by the quoted packet in hex. 70Bytes that are unchanged in the quoted packet are shown as underscores. 71Note, the IP checksum and the TTL of the quoted packet are not expected to 72match. 73By default, only one probe per hop is sent with this option. 74.It Fl e 75Firewall evasion mode. 76Use fixed destination ports for UDP, UDP-Lite, TCP and SCTP probes. 77The destination port does NOT increment with each packet sent. 78.It Fl E 79Detect ECN bleaching. 80Set the 81.Em IPTOS_ECN_ECT1 82Explicit Congestion Notification (ECN) bits 83.Pq Dv 01 , 84and report if the hop has bleached 85.Pq Dv 00 86or mangled 87.Pq Dv 10 88them, or if it is experiencing congestion 89.Pq Dv 11 . 90Otherwise, report that it passed the bits appropriately. 91If 92.Fl t 93is also specified, the corresponding ECN bits will be replaced. 94.It Fl f Ar first_ttl 95Set the initial time-to-live used in the first outgoing probe packet. 96.It Fl F 97Set the "don't fragment" bit. 98.It Fl g Ar gateway 99Specify a loose source route gateway (8 maximum). 100.It Fl i Ar iface 101Specify a network interface to obtain the source IP address for outgoing probe 102packets. 103This is normally only useful on a multi-homed host. 104(See the 105.Fl s 106flag for another way to do this). 107.It Fl I 108Use ICMP ECHO instead of UDP datagrams. 109(A synonym for "-P icmp"). 110.It Fl m Ar max_ttl 111Set the max time-to-live (max number of hops) used in outgoing probe packets. 112The default is the value of the 113.Va net.inet.ip.ttl 114.Xr sysctl 8 115(the same default used for TCP connections). 116.It Fl M Ar first_ttl 117Set the initial time-to-live value used in outgoing probe packets. 118The default is 1, i.e., start with the first hop. 119.It Fl n 120Print hop addresses numerically rather than symbolically and numerically 121(saves a nameserver address-to-name lookup for each gateway found on the path). 122.It Fl p Ar port 123Protocol specific. 124For UDP, UDP-Lite, TCP and SCTP, sets the base 125.Ar port 126number used in probes (default is 33434). 127Traceroute hopes that nothing is listening on UDP ports (or UDP-Lite ports 128if used by 129.Nm 130and supported by the peer) 131.Em port + 1 132to 133.Em port + (max_ttl - first_ttl + 1) * nprobes 134at the destination host (so an ICMP PORT_UNREACHABLE message will be returned 135to terminate the route tracing). 136If something is listening on a port in the default range, this option can be 137used to pick an unused port range. 138.It Fl P Ar proto 139Send packets of specified IP protocol. 140The currently supported protocols 141are: UDP, UDP-Lite, TCP, SCTP, GRE and ICMP. 142Other protocols may also be specified (either by name or by number), though 143.Nm 144does not implement any special knowledge of their packet formats. 145This option is useful for determining which router along a path may be blocking 146packets based on IP protocol number. 147But see BUGS below. 148.It Fl q Ar nprobes 149Set the number of probes per hop (default is 3, unless 150.Fl D 151is specified, 152when it is 1). 153.It Fl r 154Bypass the normal routing tables and send directly to a host on an attached 155network. 156If the host is not on a directly-attached network, an error is returned. 157This option can be used to ping a local host through an interface that has no 158route through it (e.g., after the interface was dropped by 159.Xr routed 8 . 160.It Fl s Ar src_addr 161Use the following IP address (which usually is given as an IP number, not a 162hostname) as the source address in outgoing probe packets. 163On multi-homed hosts (those with more than one IP address), this option can be 164used to force the source address to be something other than the IP address of 165the interface the probe packet is sent on. 166If the IP address is not one of this machine's interface addresses, an error is 167returned and nothing is sent. 168(See the 169.Fl i 170flag for another way to do this). 171.It Fl S 172Print a summary of how many probes were not answered for each hop. 173.It Fl t Ar tos 174Set the 175.Em type-of-service 176in probe packets to the following value (default zero). 177The value must be a decimal integer in the range 0 to 255. 178This option can be used to see if different types-of-service result in 179different paths. 180The upper six bits are the Differentiated Services Codepoint (RFC4594). 181The lower two bits are the Explicit Congestion Notification field (RFC3168). 182.It Fl v 183Verbose output. 184Received ICMP packets other than 185.Dv TIME_EXCEEDED 186and 187.Dv UNREACHABLE Ns s 188are listed. 189.It Fl w Ar waittime 190Set the time (in seconds) to wait for a response to a probe (default 5 sec.). 191.It Fl x 192Toggle ip checksums. 193Normally, this prevents traceroute from calculating ip checksums. 194In some cases, the operating system can overwrite parts of the outgoing packet 195but not recalculate the checksum (so in some cases the default is to not 196calculate checksums and using 197.Fl x 198causes them to be calculated). 199Note that checksums are usually required for the last hop when using ICMP ECHO 200probes 201.Pq Fl I . 202So they are always calculated when using ICMP. 203.It Fl z Ar pausemsecs 204Set the time (in milliseconds) to pause between probes (default 0). 205Some systems such as Solaris and routers such as Ciscos rate limit ICMP 206messages. 207A good value to use with this is 500 (e.g., 1/2 second). 208.El 209.Pp 210This program attempts to trace the route an IP packet would follow to some 211internet host by launching UDP probe packets with a small TTL (time to live) 212then listening for an ICMP "time exceeded" reply from a gateway. 213We start our probes with a TTL of one and increase by one until we get an ICMP 214"port unreachable" (which means we got to "host") or hit a max (which defaults 215to the amount of hops specified by the 216.Va net.inet.ip.ttl 217.Xr sysctl 8 218and can be changed with the 219.Fl m 220flag). 221Three probes (change with 222.Fl q 223flag) are sent at each TTL setting and a line is printed showing the TTL, 224address of the gateway and round trip time of each probe. 225If the probe answers come from different gateways, the address of each 226responding system will be printed. 227If there is no response within a 5 sec. timeout interval (changed with the 228.Fl w 229flag), a "*" is printed for that probe. 230.Pp 231We don't want the destination host to process the UDP probe packets so the 232destination port is set to an unlikely value (if some clod on the destination 233is using that value, it can be changed with the 234.Fl p 235flag). 236.Pp 237A sample use and output might be: 238.Bd -literal -offset 4n 239% traceroute nis.nsf.net. 240traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 40 byte packets 241 1 helios.ee.lbl.gov (128.3.112.1) 19 ms 19 ms 0 ms 242 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 243 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 39 ms 19 ms 244 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 39 ms 245 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 39 ms 39 ms 39 ms 246 6 128.32.197.4 (128.32.197.4) 40 ms 59 ms 59 ms 247 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 59 ms 248 8 129.140.70.13 (129.140.70.13) 99 ms 99 ms 80 ms 249 9 129.140.71.6 (129.140.71.6) 139 ms 239 ms 319 ms 25010 129.140.81.7 (129.140.81.7) 220 ms 199 ms 199 ms 25111 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms 252.Ed 253.Pp 254Note that lines 2 & 3 are the same. 255This is due to a buggy kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- 256that forwards packets with a zero TTL (a bug in the distributed version of 2574.3BSD). 258Note that you have to guess what path the packets are taking cross-country 259since the NSFNet (129.140) doesn't supply address-to-name translations for its 260NSSes. 261.Pp 262A more interesting example is: 263.Bd -literal -offset 4n 264% traceroute allspice.lcs.mit.edu. 265traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max, 40 byte packets 266 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 267 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 19 ms 19 ms 268 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 19 ms 269 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 19 ms 39 ms 39 ms 270 5 ccn-nerif22.Berkeley.EDU (128.32.168.22) 20 ms 39 ms 39 ms 271 6 128.32.197.4 (128.32.197.4) 59 ms 119 ms 39 ms 272 7 131.119.2.5 (131.119.2.5) 59 ms 59 ms 39 ms 273 8 129.140.70.13 (129.140.70.13) 80 ms 79 ms 99 ms 274 9 129.140.71.6 (129.140.71.6) 139 ms 139 ms 159 ms 27510 129.140.81.7 (129.140.81.7) 199 ms 180 ms 300 ms 27611 129.140.72.17 (129.140.72.17) 300 ms 239 ms 239 ms 27712 * * * 27813 128.121.54.72 (128.121.54.72) 259 ms 499 ms 279 ms 27914 * * * 28015 * * * 28116 * * * 28217 * * * 28318 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms 284.Ed 285.Pp 286Note that the gateways 12, 14, 15, 16 & 17 hops away either don't send ICMP 287"time exceeded" messages or send them with a TTL too small to reach us. 28814 \- 17 are running the MIT C Gateway code that doesn't send "time exceeded"s. 289God only knows what's going on with 12. 290.Pp 291The silent gateway 12 in the above may be the result of a bug in the 4.[23]BSD 292network code (and its derivatives): 4.x (x <= 3) sends an unreachable message 293using whatever TTL remains in the original datagram. 294Since, for gateways, the remaining TTL is zero, the ICMP "time exceeded" is 295guaranteed to not make it back to us. 296The behavior of this bug is slightly more interesting when it appears on the 297destination system: 298.Bd -literal -offset 4n 299 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 300 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms 301 3 lilac-dmc.Berkeley.EDU (128.32.216.1) 19 ms 39 ms 19 ms 302 4 ccngw-ner-cc.Berkeley.EDU (128.32.136.23) 39 ms 40 ms 19 ms 303 5 ccn-nerif35.Berkeley.EDU (128.32.168.35) 39 ms 39 ms 39 ms 304 6 csgw.Berkeley.EDU (128.32.133.254) 39 ms 59 ms 39 ms 305 7 * * * 306 8 * * * 307 9 * * * 30810 * * * 30911 * * * 31012 * * * 31113 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! 312.Ed 313.Pp 314Notice that there are 12 "gateways" (13 is the final destination) and exactly 315the last half of them are "missing". 316What's really happening is that rip (a Sun-3 running Sun OS3.5) is using the 317TTL from our arriving datagram as the TTL in its ICMP reply. 318So, the reply will time out on the return path (with no notice sent to anyone 319since ICMP's aren't sent for ICMP's) until we probe with a TTL that's at least 320twice the path length. 321I.e., rip is really only 7 hops away. 322A reply that returns with a TTL of 1 is a clue this problem exists. 323.Nm 324prints a "!" after the time if the TTL is <= 1. 325Since vendors ship a lot of obsolete 326.Pf ( DEC Ns \'s 327Ultrix, Sun 3.x) or 328non-standard 329.Pq HP-UX 330software, expect to see this problem frequently and/or take care picking the 331target host of your probes. 332.Pp 333Other possible annotations after the time are: 334.Bl -hang -offset indent -width 12n 335.It Sy !H 336Host unreachable. 337.It Sy !N 338Network unreachable. 339.It Sy !P 340Protocol unreachable. 341.It Sy !S 342Source route failed. 343.It Sy !F\-<pmtu> 344Fragmentation needed. 345The RFC1191 Path MTU Discovery value is displayed. 346.It Sy !U 347Destination network unknown. 348.It Sy !W 349Destination host unknown. 350.It Sy !I 351Source host is isolated. 352.It Sy !A 353Communication with destination network administratively prohibited. 354.It Sy !Z 355Communication with destination host administratively prohibited. 356.It Sy !Q 357For this ToS the destination network is unreachable. 358.It Sy !T 359For this ToS the destination host is unreachable. 360.It Sy !X 361Communication administratively prohibited. 362.It Sy !V 363Host precedence violation. 364.It Sy !C 365Precedence cutoff in effect. 366.It Sy !<num> 367ICMP unreachable code <num>. 368.El 369.Pp 370These are defined by RFC1812 (which supersedes RFC1716). 371If almost all the probes result in some kind of unreachable, 372.Nm 373will give up and exit. 374.Pp 375This program is intended for use in network testing, measurement and 376management. 377It should be used primarily for manual fault isolation. 378Because of the load it could impose on the network, it is unwise to use 379.Nm 380during normal operations or from automated scripts. 381.Sh SEE ALSO 382.Xr netstat 1 , 383.Xr ping 8 , 384.Xr traceroute6 8 385.Sh AUTHORS 386Implemented by 387.An Van Jacobson 388from a suggestion by Steve Deering. 389Debugged by a cast of thousands with particularly cogent suggestions or fixes 390from C. Philip Wood, Tim Seaver and Ken Adelman. 391.Sh BUGS 392When using protocols other than UDP, functionality is reduced. 393In particular, the last packet will often appear to be lost, because even 394though it reaches the destination host, there's no way to know that because no 395ICMP message is sent back. 396In the TCP case, 397.Nm 398should listen for a RST from the destination host (or an intermediate router 399that's filtering packets), but this is not implemented yet. 400.Pp 401The AS number capability reports information that may sometimes be inaccurate 402due to discrepancies between the contents of the routing database server and 403the current state of the Internet. 404