1 files changed, 138 insertions, 141 deletions

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.