git: 5eb1aebf8d80 - main - traceroute: Lint manuals
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Sat, 03 Feb 2024 04:08:07 UTC
The branch main has been updated by imp:
URL: https://cgit.FreeBSD.org/src/commit/?id=5eb1aebf8d80ccdd34f5680618c3c958af5606cb
commit 5eb1aebf8d80ccdd34f5680618c3c958af5606cb
Author: Jose Luis Duran <jlduran@gmail.com>
AuthorDate: 2023-11-17 16:41:24 +0000
Commit: Warner Losh <imp@FreeBSD.org>
CommitDate: 2024-02-03 03:14:09 +0000
traceroute: Lint manuals
Fix a number of warning mandoc -Tlint and igor turned up. No changes
intended.
Reviewed by: imp
Pull Request: https://github.com/freebsd/freebsd-src/pull/901
---
contrib/traceroute/traceroute.8 | 279 ++++++++++++++++++-------------------
usr.sbin/traceroute6/traceroute6.8 | 46 +++---
2 files changed, 160 insertions(+), 165 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.
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