diff --git a/contrib/traceroute/traceroute.8 b/contrib/traceroute/traceroute.8 index 1ba11b75e37d..203b743fb408 100644 --- a/contrib/traceroute/traceroute.8 +++ b/contrib/traceroute/traceroute.8 @@ -15,7 +15,7 @@ .\" .\" $Id: traceroute.8,v 1.19 2000/09/21 08:44:19 leres Exp $ .\" -.Dd October 25, 2023 +.Dd November 17, 2023 .Dt TRACEROUTE 8 .Os .Sh NAME @@ -42,39 +42,34 @@ .Op Ar packetlen .Ek .Sh DESCRIPTION -The Internet is a large and complex aggregation of -network hardware, connected together by gateways. -Tracking the route one's packets follow (or finding the miscreant -gateway that's discarding your packets) can be difficult. +The Internet is a large and complex aggregation of network hardware, connected +together by gateways. +Tracking the route one's packets follow (or finding the miscreant gateway +that's discarding your packets) can be difficult. .Nm -utilizes the IP protocol `time to live' field and attempts to elicit an -ICMP TIME_EXCEEDED response from each gateway along the path to some -host. +utilizes the IP protocol `time to live' field and attempts to elicit an ICMP +TIME_EXCEEDED response from each gateway along the path to some host. .Pp The only mandatory parameter is the destination host name or IP number. -The default probe datagram length is 40 bytes, but this may be increased -by specifying a packet length (in bytes) after the destination host -name. +The default probe datagram length is 40 bytes, but this may be increased by +specifying a packet length (in bytes) after the destination host name. .Pp Other options are: .Bl -tag -width Ds .It Fl a Turn on AS# lookups for each hop encountered. .It Fl A Ar as_server -Turn on AS# lookups and use the given server instead of the -default. +Turn on AS# lookups and use the given server instead of the default. .It Fl d Enable socket level debugging. .It Fl D -When an ICMP response to our probe datagram is received, -print the differences between the transmitted packet and -the packet quoted by the ICMP response. +When an ICMP response to our probe datagram is received, print the differences +between the transmitted packet and the packet quoted by the ICMP response. A key showing the location of fields within the transmitted packet is printed, -followed by the original packet in hex, -followed by the quoted packet in hex. +followed by the original packet in hex, followed by the quoted packet in hex. Bytes that are unchanged in the quoted packet are shown as underscores. -Note, -the IP checksum and the TTL of the quoted packet are not expected to match. +Note, the IP checksum and the TTL of the quoted packet are not expected to +match. By default, only one probe per hop is sent with this option. .It Fl e Firewall evasion mode. @@ -103,30 +98,30 @@ Set the "don't fragment" bit. .It Fl g Ar gateway Specify a loose source route gateway (8 maximum). .It Fl i Ar iface -Specify a network interface to obtain the source IP address for -outgoing probe packets. This is normally only useful on a multi-homed -host. (See the +Specify a network interface to obtain the source IP address for outgoing probe +packets. +This is normally only useful on a multi-homed host. +(See the .Fl s -flag for another way to do this.) +flag for another way to do this). .It Fl I -Use ICMP ECHO instead of UDP datagrams. (A synonym for "-P icmp"). +Use ICMP ECHO instead of UDP datagrams. +(A synonym for "-P icmp"). .It Fl m Ar max_ttl -Set the max time-to-live (max number of hops) used in outgoing probe -packets. The default is the value of the +Set the max time-to-live (max number of hops) used in outgoing probe packets. +The default is the value of the .Va net.inet.ip.ttl .Xr sysctl 8 -(the same default used for TCP -connections). +(the same default used for TCP connections). .It Fl M Ar first_ttl Set the initial time-to-live value used in outgoing probe packets. The default is 1, i.e., start with the first hop. .It Fl n Print hop addresses numerically rather than symbolically and numerically -(saves a nameserver address-to-name lookup for each gateway found on the -path). +(saves a nameserver address-to-name lookup for each gateway found on the path). .It Fl p Ar port -Protocol specific. For UDP, UDP-Lite, TCP and SCTP, sets -the base +Protocol specific. +For UDP, UDP-Lite, TCP and SCTP, sets the base .Ar port number used in probes (default is 33434). Traceroute hopes that nothing is listening on UDP ports (or UDP-Lite ports @@ -136,106 +131,106 @@ and supported by the peer) .Em port + 1 to .Em port + (max_ttl - first_ttl + 1) * nprobes -at the destination host (so an ICMP PORT_UNREACHABLE message will -be returned to terminate the route tracing). If something is -listening on a port in the default range, this option can be used -to pick an unused port range. +at the destination host (so an ICMP PORT_UNREACHABLE message will be returned +to terminate the route tracing). +If something is listening on a port in the default range, this option can be +used to pick an unused port range. .It Fl P Ar proto -Send packets of specified IP protocol. The currently supported protocols -are: UDP, UDP-Lite, TCP, SCTP, GRE and ICMP. Other protocols may also be -specified (either by name or by number), though +Send packets of specified IP protocol. +The currently supported protocols +are: UDP, UDP-Lite, TCP, SCTP, GRE and ICMP. +Other protocols may also be specified (either by name or by number), though .Nm -does not implement any special knowledge of their packet formats. This -option is useful for determining which router along a path may be -blocking packets based on IP protocol number. But see BUGS below. +does not implement any special knowledge of their packet formats. +This option is useful for determining which router along a path may be blocking +packets based on IP protocol number. +But see BUGS below. .It Fl q Ar nprobes -Set the number of probes per hop (default is 3, -unless +Set the number of probes per hop (default is 3, unless .Fl D is specified, when it is 1). .It Fl r Bypass the normal routing tables and send directly to a host on an attached network. -If the host is not on a directly-attached network, -an error is returned. -This option can be used to ping a local host through an interface -that has no route through it (e.g., after the interface was dropped by +If the host is not on a directly-attached network, an error is returned. +This option can be used to ping a local host through an interface that has no +route through it (e.g., after the interface was dropped by .Xr routed 8 . .It Fl s Ar src_addr -Use the following IP address (which usually is given as an IP number, not -a hostname) as the source address in outgoing probe packets. On -multi-homed hosts (those with more than one IP -address), this option can be used to -force the source address to be something other than the IP address -of the interface the probe packet is sent on. If the IP address -is not one of this machine's interface addresses, an error is -returned and nothing is sent. (See the +Use the following IP address (which usually is given as an IP number, not a +hostname) as the source address in outgoing probe packets. +On multi-homed hosts (those with more than one IP address), this option can be +used to force the source address to be something other than the IP address of +the interface the probe packet is sent on. +If the IP address is not one of this machine's interface addresses, an error is +returned and nothing is sent. +(See the .Fl i -flag for another way to do this.) +flag for another way to do this). .It Fl S Print a summary of how many probes were not answered for each hop. .It Fl t Ar tos Set the .Em type-of-service -in probe packets to the following value (default zero). The value must be -a decimal integer in the range 0 to 255. This option can be used to -see if different types-of-service result in different paths. The upper six -bits are the Differentiated Services Codepoint (RFC4594). The lower two -bits are the Explicit Congestion Notification field (RFC3168). +in probe packets to the following value (default zero). +The value must be a decimal integer in the range 0 to 255. +This option can be used to see if different types-of-service result in +different paths. +The upper six bits are the Differentiated Services Codepoint (RFC4594). +The lower two bits are the Explicit Congestion Notification field (RFC3168). .It Fl v -Verbose output. Received ICMP packets other than +Verbose output. +Received ICMP packets other than .Dv TIME_EXCEEDED and .Dv UNREACHABLE Ns s are listed. .It Fl w Ar waittime -Set the time (in seconds) to wait for a response to a probe (default 5 -sec.). +Set the time (in seconds) to wait for a response to a probe (default 5 sec.). .It Fl x -Toggle ip checksums. Normally, this prevents traceroute from calculating -ip checksums. In some cases, the operating system can overwrite parts of -the outgoing packet but not recalculate the checksum (so in some cases -the default is to not calculate checksums and using +Toggle ip checksums. +Normally, this prevents traceroute from calculating ip checksums. +In some cases, the operating system can overwrite parts of the outgoing packet +but not recalculate the checksum (so in some cases the default is to not +calculate checksums and using .Fl x -causes them to be calculated). Note that checksums are usually required -for the last hop when using ICMP ECHO probes +causes them to be calculated). +Note that checksums are usually required for the last hop when using ICMP ECHO +probes .Pq Fl I . So they are always calculated when using ICMP. .It Fl z Ar pausemsecs Set the time (in milliseconds) to pause between probes (default 0). -Some systems such as Solaris and routers such as Ciscos rate limit -icmp messages. A good value to use with this this is 500 (e.g. 1/2 second). +Some systems such as Solaris and routers such as Ciscos rate limit ICMP +messages. +A good value to use with this is 500 (e.g., 1/2 second). .El .Pp This program attempts to trace the route an IP packet would follow to some -internet host by launching UDP probe -packets with a small ttl (time to live) then listening for an -ICMP "time exceeded" reply from a gateway. We start our probes -with a ttl of one and increase by one until we get an ICMP "port -unreachable" (which means we got to "host") or hit a max (which -defaults to the amount of hops specified by the +internet host by launching UDP probe packets with a small TTL (time to live) +then listening for an ICMP "time exceeded" reply from a gateway. +We start our probes with a TTL of one and increase by one until we get an ICMP +"port unreachable" (which means we got to "host") or hit a max (which defaults +to the amount of hops specified by the .Va net.inet.ip.ttl .Xr sysctl 8 and can be changed with the .Fl m -flag). Three -probes (change with +flag). +Three probes (change with .Fl q -flag) are sent at each ttl setting and a -line is printed showing the ttl, address of the gateway and -round trip time of each probe. If the probe answers come from -different gateways, the address of each responding system will -be printed. If there is no response within a 5 sec. timeout -interval (changed with the +flag) are sent at each TTL setting and a line is printed showing the TTL, +address of the gateway and round trip time of each probe. +If the probe answers come from different gateways, the address of each +responding system will be printed. +If there is no response within a 5 sec. timeout interval (changed with the .Fl w -flag), a "*" is printed for that -probe. +flag), a "*" is printed for that probe. .Pp -We don't want the destination -host to process the UDP probe packets so the destination port is set to an -unlikely value (if some clod on the destination is using that -value, it can be changed with the +We don't want the destination host to process the UDP probe packets so the +destination port is set to an unlikely value (if some clod on the destination +is using that value, it can be changed with the .Fl p flag). .Pp @@ -256,12 +251,13 @@ traceroute to nis.nsf.net (35.1.1.48), 64 hops max, 40 byte packets 11 nic.merit.edu (35.1.1.48) 239 ms 239 ms 239 ms .Ed .Pp -Note that lines 2 & 3 are the same. This is due to a buggy -kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- that forwards -packets with a zero ttl (a bug in the distributed version -of 4.3BSD). Note that you have to guess what path -the packets are taking cross-country since the NSFNet (129.140) -doesn't supply address-to-name translations for its NSSes. +Note that lines 2 & 3 are the same. +This is due to a buggy kernel on the 2nd hop system \- lilac-dmc.Berkeley.EDU \- +that forwards packets with a zero TTL (a bug in the distributed version of +4.3BSD). +Note that you have to guess what path the packets are taking cross-country +since the NSFNet (129.140) doesn't supply address-to-name translations for its +NSSes. .Pp A more interesting example is: .Bd -literal -offset 4n @@ -287,19 +283,18 @@ traceroute to allspice.lcs.mit.edu (18.26.0.115), 64 hops max, 40 byte packets 18 ALLSPICE.LCS.MIT.EDU (18.26.0.115) 339 ms 279 ms 279 ms .Ed .Pp -Note that the gateways 12, 14, 15, 16 & 17 hops away -either don't send ICMP "time exceeded" messages or send them -with a ttl too small to reach us. 14 \- 17 are running the -MIT C Gateway code that doesn't send "time exceeded"s. God -only knows what's going on with 12. +Note that the gateways 12, 14, 15, 16 & 17 hops away either don't send ICMP +"time exceeded" messages or send them with a TTL too small to reach us. +14 \- 17 are running the MIT C Gateway code that doesn't send "time exceeded"s. +God only knows what's going on with 12. .Pp -The silent gateway 12 in the above may be the result of a bug in -the 4.[23]BSD network code (and its derivatives): 4.x (x <= 3) -sends an unreachable message using whatever ttl remains in the -original datagram. Since, for gateways, the remaining ttl is -zero, the ICMP "time exceeded" is guaranteed to not make it back -to us. The behavior of this bug is slightly more interesting -when it appears on the destination system: +The silent gateway 12 in the above may be the result of a bug in the 4.[23]BSD +network code (and its derivatives): 4.x (x <= 3) sends an unreachable message +using whatever TTL remains in the original datagram. +Since, for gateways, the remaining TTL is zero, the ICMP "time exceeded" is +guaranteed to not make it back to us. +The behavior of this bug is slightly more interesting when it appears on the +destination system: .Bd -literal -offset 4n 1 helios.ee.lbl.gov (128.3.112.1) 0 ms 0 ms 0 ms 2 lilac-dmc.Berkeley.EDU (128.32.216.1) 39 ms 19 ms 39 ms @@ -316,24 +311,24 @@ when it appears on the destination system: 13 rip.Berkeley.EDU (128.32.131.22) 59 ms ! 39 ms ! 39 ms ! .Ed .Pp -Notice that there are 12 "gateways" (13 is the final -destination) and exactly the last half of them are "missing". -What's really happening is that rip (a Sun-3 running Sun OS3.5) -is using the ttl from our arriving datagram as the ttl in its -ICMP reply. So, the reply will time out on the return path -(with no notice sent to anyone since ICMP's aren't sent for -ICMP's) until we probe with a ttl that's at least twice the path -length. I.e., rip is really only 7 hops away. A reply that -returns with a ttl of 1 is a clue this problem exists. -Traceroute prints a "!" after the time if the ttl is <= 1. +Notice that there are 12 "gateways" (13 is the final destination) and exactly +the last half of them are "missing". +What's really happening is that rip (a Sun-3 running Sun OS3.5) is using the +TTL from our arriving datagram as the TTL in its ICMP reply. +So, the reply will time out on the return path (with no notice sent to anyone +since ICMP's aren't sent for ICMP's) until we probe with a TTL that's at least +twice the path length. +I.e., rip is really only 7 hops away. +A reply that returns with a TTL of 1 is a clue this problem exists. +.Nm +prints a "!" after the time if the TTL is <= 1. Since vendors ship a lot of obsolete -.Pf ( Tn DEC Ns \'s +.Pf ( DEC Ns \'s Ultrix, Sun 3.x) or non-standard -.Pq Tn HP-UX -software, expect to see this problem -frequently and/or take care picking the target host of your -probes. +.Pq HP-UX +software, expect to see this problem frequently and/or take care picking the +target host of your probes. .Pp Other possible annotations after the time are: .Bl -hang -offset indent -width 12n @@ -377,8 +372,8 @@ If almost all the probes result in some kind of unreachable, .Nm will give up and exit. .Pp -This program is intended for use in network testing, measurement -and management. +This program is intended for use in network testing, measurement and +management. It should be used primarily for manual fault isolation. Because of the load it could impose on the network, it is unwise to use .Nm @@ -386,21 +381,23 @@ during normal operations or from automated scripts. .Sh SEE ALSO .Xr netstat 1 , .Xr ping 8 , -.Xr traceroute6 8 . +.Xr traceroute6 8 .Sh AUTHORS -Implemented by Van Jacobson from a suggestion by Steve Deering. Debugged -by a cast of thousands with particularly cogent suggestions or fixes from -C. Philip Wood, Tim Seaver and Ken Adelman. +Implemented by +.An Van Jacobson +from a suggestion by Steve Deering. +Debugged by a cast of thousands with particularly cogent suggestions or fixes +from C. Philip Wood, Tim Seaver and Ken Adelman. .Sh BUGS When using protocols other than UDP, functionality is reduced. -In particular, the last packet will often appear to be lost, because -even though it reaches the destination host, there's no way to know -that because no ICMP message is sent back. +In particular, the last packet will often appear to be lost, because even +though it reaches the destination host, there's no way to know that because no +ICMP message is sent back. In the TCP case, .Nm -should listen for a RST from the destination host (or an intermediate -router that's filtering packets), but this is not implemented yet. +should listen for a RST from the destination host (or an intermediate router +that's filtering packets), but this is not implemented yet. .Pp -The AS number capability reports information that may sometimes be -inaccurate due to discrepancies between the contents of the -routing database server and the current state of the Internet. +The AS number capability reports information that may sometimes be inaccurate +due to discrepancies between the contents of the routing database server and +the current state of the Internet. diff --git a/usr.sbin/traceroute6/traceroute6.8 b/usr.sbin/traceroute6/traceroute6.8 index 5abd4ba01c5b..f185b8087411 100644 --- a/usr.sbin/traceroute6/traceroute6.8 +++ b/usr.sbin/traceroute6/traceroute6.8 @@ -75,16 +75,14 @@ .Sh DESCRIPTION The .Nm -utility -uses the IPv6 protocol hop limit field to elicit an ICMPv6 TIME_EXCEEDED -response from each gateway along the path to some host. +utility uses the IPv6 protocol hop limit field to elicit an ICMPv6 +TIME_EXCEEDED response from each gateway along the path to some host. .Pp The only mandatory parameter is the destination host name or IPv6 address. -The default probe datagram carries 20 bytes of payload, -in addition to the IPv6 header. -The size of the payload can be specified by giving a length -(in bytes) -after the destination host name. +The default probe datagram carries 20 bytes of payload, in addition to the IPv6 +header. +The size of the payload can be specified by giving a length (in bytes) after +the destination host name. .Pp Other options are: .Bl -tag -width Ds @@ -130,8 +128,8 @@ The default is the value of the .It Fl n Do not resolve numeric address to hostname. .It Fl N -Use a packet with no upper layer header for the probes, -instead of UDP datagrams. +Use a packet with no upper layer header for the probes, instead of UDP +datagrams. .It Fl p Ar port Set SCTP/TCP/UDP port number to .Ar port . @@ -139,16 +137,15 @@ Set SCTP/TCP/UDP port number to Set the number of probe per hop count to .Ar probes . .It Fl r -Bypass the normal routing tables and send directly to a host -on an attached network. +Bypass the normal routing tables and send directly to a host on an attached +network. If the host is not on a directly-connected network, an error is returned. This option corresponds to the .Dv SO_DONTROUTE -socket option; -it can be used to ping a local host through an interface -that has no route through it -(e.g., after the interface was dropped by a routing daemon). +socket option; it can be used to ping a local host through an interface that +has no route through it (e.g., after the interface was dropped by a routing +daemon). .It Fl s Ar src .Ar Src specifies the source IPv6 address to be used. @@ -178,10 +175,11 @@ Be verbose. Specify the delay time between probes. .El .Pp -This program prints the route to the given destination and the round-trip -time to each gateway, in the same manner as traceroute. +This program prints the route to the given destination and the round-trip time +to each gateway, in the same manner as traceroute. .Pp -Here is a list of possible annotations after the round-trip time for each gateway: +Here is a list of possible annotations after the round-trip time for each +gateway: .Bl -hang -offset indent .It !N Destination Unreachable - No Route to Host. @@ -195,11 +193,11 @@ Destination Unreachable - Address Unreachable. Parameter Problem - Unrecognized Next Header Type. .It !\& This is printed if the hop limit is <= 1 on a port unreachable message. -This means that the packet got to the destination, -but that the reply had a hop limit that was just large enough to -allow it to get back to the source of the traceroute6. -This was more interesting in the IPv4 case, -where some IP stack bugs could be identified by this behaviour. +This means that the packet got to the destination, but that the reply had a hop +limit that was just large enough to allow it to get back to the source of the +traceroute6. +This was more interesting in the IPv4 case, where some IP stack bugs could be +identified by this behaviour. .El .\" .Sh EXIT STATUS