From fdcd803e082d3103c2ea88d6b70563588a5023a7 Mon Sep 17 00:00:00 2001 From: ginsbach Date: Fri, 4 Aug 2017 02:08:21 +0000 Subject: [PATCH] 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. --- usr.sbin/traceroute6/traceroute6.8 | 84 ++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 9 deletions(-) diff --git a/usr.sbin/traceroute6/traceroute6.8 b/usr.sbin/traceroute6/traceroute6.8 index fce4b26d3ef1..335e073ffdd4 100644 --- a/usr.sbin/traceroute6/traceroute6.8 +++ b/usr.sbin/traceroute6/traceroute6.8 @@ -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 @@ is not specified, and only numeric addresses if .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 @@ through an interface that has no route through it (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