[src/trunk]: src/usr.sbin/traceroute6 Expand the traceroute6 man page

[ginsbach <ginsbach%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/1515bc03df7d
branches:  trunk
changeset: 825880:1515bc03df7d
user:      ginsbach <ginsbach%NetBSD.org@localhost>
date:      Fri Aug 04 02:08:21 2017 +0000

description:
Expand the traceroute6 man page

- Add a proper description paragraph before launching into describing the
  options.  More closely follow format of the traceroute(8) man page.
- Improve the wording for some option descriptions.
- Add description what what is printed and define what the possible
  annotations mean.

diffstat:

 usr.sbin/traceroute6/traceroute6.8 |  84 +++++++++++++++++++++++++++++++++----
 1 files changed, 75 insertions(+), 9 deletions(-)

diffs (134 lines):

diff -r 67583503d0e0 -r 1515bc03df7d usr.sbin/traceroute6/traceroute6.8
--- a/usr.sbin/traceroute6/traceroute6.8        Fri Aug 04 01:18:39 2017 +0000
+++ b/usr.sbin/traceroute6/traceroute6.8        Fri Aug 04 02:08:21 2017 +0000
@@ -1,4 +1,4 @@
-.\"    $NetBSD: traceroute6.8,v 1.15 2017/07/04 07:13:18 wiz Exp $
+.\"    $NetBSD: traceroute6.8,v 1.16 2017/08/04 02:08:21 ginsbach Exp $
 .\"    $KAME: traceroute6.8,v 1.8 2000/06/12 16:29:18 itojun Exp $
 .\"
 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
@@ -28,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd September 17, 2005
+.Dd January 18, 2007
 .Dt TRACEROUTE6 8
 .Os
 .\"
@@ -51,13 +51,27 @@
 .Op Ar datalen
 .\"
 .Sh DESCRIPTION
+.Nm
+uses the IPv6 protocol hop limit field to elicit an ICMPv6
+.Dv 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 12 bytes of payload,
+in addition to the IPv6 header.
+The size of the payload can be specified by giving a length
+.Po in bytes
+.Pc
+after the destination host name.
+.Pp
+Other options are:
 .Bl -tag -width Ds
 .It Fl A
 Turn on AS# lookups and use the given server instead of the default.
 .It Fl a
 Turn on AS# lookups for each hop encountered.
 .It Fl d
-Debug mode.
+Turn on socket-level debugging.
 .It Fl f Ar firsthop
 Specify how many hops to skip in trace.
 .It Fl g Ar gateway
@@ -78,15 +92,32 @@
 .Fl n
 is specified.
 .It Fl m Ar hoplimit
-Specify maximum hoplimit.
+Specify maximum
+.Ar hoplimit,
+up to 255.
+The default is 30 hops.
 .It Fl n
 Do not resolve numeric address to hostname.
 .It Fl p Ar port
-Set UDP port number to
+Set the base UDP port number use in probes to
 .Ar port .
+The default is 33434.
+.Nm
+hopes that nothing is listening on UDP ports
+.Va base
+to
+.Va base + nhops - 1
+at the destination host (so an ICMPv6
+.Dv 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 q Ar probes
-Set the number of probe per hop count to
+Set the number of probe packets sent per hop count to
 .Ar probes .
+By default,
+.Nm
+sends three probe packets.
 .It Fl r
 Bypass the normal routing tables and send directly to
 a host on an attached network.
@@ -97,12 +128,47 @@
 (e.g., after the interface was dropped by
 .Xr route6d 8 ) .
 .It Fl s Ar src
-.Ar Src
-specifies the source IPv6 address to be used.
+Use the IPv6 address,
+.Ar src ,
+as the source address in outgoing probe packets.
 .It Fl v
 Be verbose.
+Received ICMPv6 packets other than
+.Dv TIME_EXCEEDED
+and
+.Dv UNREACHABLEs
+are listed.
 .It Fl w Ar waittime
-Specify the delay time between probes.
+Use
+.Ar waittime
+as the delay in seconds, between probes.
+The default is 5 seconds.
+.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.
+.Pp
+Here is a list of possible annotations after the
+round-trip time for each gateway:
+.Pp
+.Bl -hang -offset indent
+.It  !N
+Destination Unreachable - No Route to Host.
+.It  !X
+Destination Unreachable - Administratively Prohibited.
+.It  !S
+Destination Unreachable - Not a Neighbour.
+.It  !H
+Destination Unreachable - Address Unreachable.
+.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
+.Nm .
+This was more interesting in the IPv4 case,
+where some IP stack bugs could be identified by this behaviour.
 .El
 .\"
 .Sh EXIT STATUS