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