mdoc-ify. Add $OpenBSD$

1 files changed, 178 insertions, 221 deletions

diff --git a/usr.sbin/mtrace/mtrace.8 b/usr.sbin/mtrace/mtrace.8
index 3c882306730..3dc93de2178 100644
--- a/usr.sbin/mtrace/mtrace.8
+++ b/usr.sbin/mtrace/mtrace.8
@@ -1,3 +1,4 @@
+.\"	$OpenBSD: mtrace.8,v 1.5 2001/05/22 11:15:30 ho Exp $
 .\"	$NetBSD: mtrace.8,v 1.4 1995/12/10 10:57:11 mycroft Exp $
 .\"
 .\" Copyright (c) 1995 by the University of Southern California
@@ -31,313 +32,271 @@
 .\" Copyright (c) 1988 The Regents of the University of California.
 .\" All rights reserved.
 .\"
-.TH MTRACE 8 "May 8, 1995"
-.UC 6
-.SH NAME
-mtrace \- print multicast path from a source to a receiver
-.SH SYNOPSIS
-.B mtrace
-[
-.B \-g
-.I gateway
-] [
-.B \-i
-.I if_addr
-] [
-.B \-l
-] [
-.B \-M
-] [
-.B \-m
-.I max_hops
-] [
-.B \-n
-] [
-.B \-p
-] [
-.B \-q
-.I nqueries
-] [
-.B \-r
-.I resp_dest
-] [
-.B \-s
-] [
-.B \-S
-.I stat_int
-] [
-.B \-t
-.I ttl
-] [
-.B \-v
-] [
-.B \-w
-.I waittime
-]
-.I source
-[
-.I receiver
-] [
-.I group
-]
-.SH DESCRIPTION
+.Dd May 8, 1995
+.Dt mtrace 8
+.Os
+.Sh NAME
+.Nm mtrace
+.Nd print multicast path from a source to a receiver
+.Sh SYNOPSIS
+.Nm mtrace
+.Op Fl g Ar gateway
+.Op Fl i Ar if_addr
+.Op Fl l
+.Op Fl M
+.Op Fl m Ar max_hops
+.Op Fl n
+.Op Fl p
+.Op Fl q Ar nqueries
+.Op Fl r Ar resp_dest
+.Op Fl s
+.Op Fl S Ar stat_int
+.Op Fl t Ar ttl
+.Op Fl v
+.Op Fl w Ar waittime
+.Ar source
+.Op Ar receiver
+.Op Ar group
+.Sh DESCRIPTION
 Assessing problems in the distribution of IP multicast traffic
 can be difficult.
-.B mtrace
+.Nm
 utilizes a tracing feature implemented in multicast routers
-.RB ( mrouted
+.Nm ( mrouted
 version 3.3 and later) that is
 accessed via an extension to the IGMP protocol.  A trace query is
 passed hop-by-hop along the reverse path from the
-.I receiver
+.Ar receiver
 to the
-.IR source ,
+.Ar source ,
 collecting hop addresses, packet counts, and routing error conditions
 along the path, and then the response is returned to the requestor.
-.PP
+.Pp
 The only required parameter is the
-.I source
+.Ar source
 host name or address.  The default
-.I receiver
+.Ar receiver
 is the host running mtrace, and the default
-.I group
+.Ar group
 is "MBone Audio" (224.2.0.1), which is sufficient if packet loss
 statistics for a particular multicast group are not needed.  These two
 optional parameters may be specified to test the path to some other
 receiver in a particular group, subject to some constraints as
 detailed below.  The two parameters can be distinguished because the
-.I receiver
+.Ar receiver
 is a unicast address and the
-.I group
+.Ar group
 is a multicast address.
-.PP
-NOTE: For Solaris 2.4/2.5, if the multicast interface is not the default
-interface, the -i option must be used to set the local address.
-.SH OPTIONS
-.TP 8 8
-.BI \-g\  gwy
+.Pp
+The options are as follows:
+.Pp
+.Bl -tag -width addr_xy
+.It Fl g Ar gwy
 Send the trace query via unicast directly to the multicast router
-.I gwy
+.Ar gwy
 rather than multicasting the query.
 This must be the last-hop router on the path from the intended
-.I source
+.Ar source
 to the
-.IR receiver .
-.RS 8
-.TP 12 12
-.I CAUTION!!
-Versions 3.3 and 3.5 of
-.B mrouted
-will crash if a trace query is received via a
-unicast packet and
-.B mrouted
-has no route for the
-.I source
-address.  Therefore, do not use the
-.B \-g
-option unless the target
-.B mrouted
-has been verified to be 3.4 or newer than 3.5.
-.RE
-.TP 8 8
-.BI \-i\  addr
+.Ar receiver .
+.Em NOTE: Read the BUGS section below.
+.It Fl i Ar addr
 Use
-.I addr
+.Ar addr
 as the local interface address (on a multi-homed host) for sending the
 trace query and as the default for the
-.I receiver
+.Ar receiver
 and the response destination.
-.TP 8 8
-.B \-l
+.It Fl l
 Loop indefinitely printing packet rate and loss statistics for the
 multicast path every 10 seconds (see
-.B \-S
-.IR stat_int ).
-.TP 8 8
-.B \-M
+.Fl S Ar stat_int Ns ).
+.It Fl M
 Always send the response using multicast rather than attempting
 unicast first.
-.TP 8 8
-.BI \-m\  n
+.It Fl m Ar n
 Set to
-.I n
+.Ar n
 the maximum number of hops that will be traced from the
-.I receiver
+.Ar receiver
 back toward the
-.IR source .
+.Ar source .
 The default is 32 hops (infinity for the DVMRP routing protocol).
-.TP 8 8
-.B \-n
+.It Fl n
 Print hop addresses numerically rather than symbolically and numerically
-(saves a nameserver address-to-name lookup for each router found on the
+(saves a nameserver address-to-name lo okup for each router found on the
 path).
-.TP 8 8
-.BI \-q\  n
+.It Fl q Ar n
 Set the maximum number of query attempts for any hop to
-.IR n .
+.Ar n .
 The default is 3.
-.TP 8 8
-.B \-p
+.It Fl p
 Listen passively for multicast responses from traces initiated by
 others.  This works best when run on a multicast router.
-.TP 8 8
-.BI \-r\  host
+.It Fl r Ar host
 Send the trace response to
-.I host
+.Ar host
 rather than to the host on which
-.B mtrace
+.Nm
 is being run, or to a multicast address other than the one registered
 for this purpose (224.0.1.32).
-.TP 8 8
-.B \-s
+.It Fl s
 Print a short form output including only the multicast path and not
 the packet rate and loss statistics.
-.TP 8 8
-.BI \-S\  n
+.It Fl S Ar n
 Change the interval between statistics gathering traces to
-.I n
+.Ar n
 seconds (default 10 seconds).
-.TP 8 8
-.BI \-t\  ttl
+.It Fl t Ar ttl
 Set the
-.I ttl
+.Ar ttl
 (time-to-live, or number of hops) for multicast trace queries and
-responses.  The default is 64, except for local queries to the "all
-routers" multicast group which use ttl 1.
-.TP 8 8
-.B \-v
+responses.  The default is 64, except for local queries to the 
+"all routers" multicast group which use ttl 1.
+.It Fl v
 Verbose mode; show hop times on the initial trace and statistics display.
-.TP 8 8
-.BI \-w\  n
+.It Fl w Ar n
 Set the time to wait for a trace response to
-.I n
+.Ar n
 seconds (default 3 seconds).
-.SH USAGE
-.SS How It Works
+.El
+.Ss How It Works
 The technique used by the
-.B traceroute
+.Nm traceroute
 tool to trace unicast network paths will not work for IP multicast
 because ICMP responses are specifically forbidden for multicast traffic.
 Instead, a tracing feature has been built into the multicast routers.
 This technique has the advantage that additional information about
 packet rates and losses can be accumulated while the number of packets
 sent is minimized.
-.PP
+.Pp
 Since multicast uses
 reverse path forwarding, the trace is run backwards from the
-.I receiver
+.Ar receiver
 to the
-.IR source .
+.Ar source .
 A trace query packet is sent to the last
 hop multicast router (the leaf router for the desired
-.I receiver
+.Ar receiver
 address).  The last hop router builds a trace response packet, fills in
 a report for its hop, and forwards the trace packet using unicast to
 the router it believes is the previous hop for packets originating
 from the specified
-.IR source .
+.Ar source .
 Each router along the path adds its report and forwards the packet.
 When the trace response packet reaches the first hop router (the router
 that is directly connected to the source's net), that router sends the
 completed response to the response destination address specified in
 the trace query.
-.PP
+.Pp
 If some multicast router along the path does not implement the
 multicast traceroute feature or if there is some outage, then no
 response will be returned.  To solve this problem, the trace query
 includes a maximum hop count field to limit the number of hops traced
 before the response is returned.  That allows a partial path to be
 traced.
-.PP
+.Pp
 The reports inserted by each router contain not only the address of
 the hop, but also the ttl required to forward and some flags to indicate
 routing errors, plus counts of the total number of packets on the
 incoming and outgoing interfaces and those forwarded for the specified
-.IR group .
+.Ar group .
 Taking differences in these counts for two traces separated in time
 and comparing the output packet counts from one hop with the input
 packet counts of the next hop allows the calculation of packet rate
 and packet loss statistics for each hop to isolate congestion
 problems.
-.SS Finding the Last-Hop Router
+.Ss Finding the Last-Hop Router
 The trace query must be sent to the multicast router which is the
 last hop on the path from the
-.I source
+.Ae source
 to the
-.IR receiver .
-If the receiver is on the local subnet (as determined using the subnet
+.Ar receiver .
+If the 
+.Ar receiver
+is on the local subnet (as determined using the subnet
 mask), then the default method is to multicast the trace query to
 all-routers.mcast.net (224.0.0.2) with a ttl of 1.  Otherwise, the
 trace query is multicast to the
-.I group
+.Ar group
 address since the last hop router will be a member of that group if
-the receiver is.  Therefore it is necessary to specify a group that
-the intended receiver has joined.  This multicast is sent with a
+the 
+.Ar receiver 
+is.  Therefore it is necessary to specify a 
+.Ar group 
+that the intended 
+.Ar receiver 
+is joined.  This multicast is sent with a
 default ttl of 64, which may not be sufficient for all cases (changed
 with the
-.B \-t
+.Fl t
 option).
 If the last hop router is known, it may also be addressed directly
 using the
-.B \-g
+.Fl g
 option).  Alternatively, if it is desired to trace a group that the
-receiver has not joined, but it is known that the last-hop router is a
+.Ar receiver
+has not joined, but it is known that the last-hop router is a
 member of another group, the
-.B \-g
+.Fl g
 option may also be used to specify a different multicast address for the
 trace query.
-.PP
-When tracing from a multihomed host or router, the default receiver
-address may not be the desired interface for the path from the source.
+.Pp
+When tracing from a multihomed host or router, the default 
+.Ar receiver
+address may not be the desired interface for the path from the 
+.Ar source .
 In that case, the desired interface should be specified explicitly as
 the
-.IR receiver .
-.SS Directing the Response
+.Ar receiver .
+.Ss Directing the Response
 By default,
-.B mtrace
+.Nm
 first attempts to trace the full reverse path, unless the number of
 hops to trace is explicitly set with the
-.B \-m
+.Fl m
 option.  If there is no response within a 3 second timeout interval
 (changed with the
-.B \-w
+.Fl m
 option), a "*" is printed and the probing switches to hop-by-hop mode.
 Trace queries are issued starting with a maximum hop count of one and
 increasing by one until the full path is traced or no response is
 received.  At each hop, multiple probes are sent (default is three,
 changed with
-.B \-q
+.Fl q
 option).  The first half of the attempts (default is one) are made with
 the unicast address of the host running
-.B mtrace
+.Nm
 as the destination for the response.  Since the unicast route may be
 blocked, the remainder of attempts request that the response be
 multicast to mtrace.mcast.net (224.0.1.32) with the ttl set to 32 more
 than what's needed to pass the thresholds seen so far along the path
-to the receiver.  For the last quarter of the attempts (default is
+to the 
+.Ar receiver .
+For the last quarter of the attempts (default is
 one), the ttl is increased by another 32 each time up to a maximum of
 192.  Alternatively, the ttl may be set explicitly with the
-.B \-t
+.Fl t
 option and/or the initial unicast attempts can be forced to use
 multicast instead with the
-.B \-M
+.Fl m
 option.  For each attempt, if no response is received within the
 timeout, a "*" is printed.  After the specified number of attempts
 have failed,
-.B mtrace
+.Nm
 will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
 request (as used by the
-.B mrinfo
+.Nm mrinfo
 program) to see what kind of router it is.
-.SH EXAMPLES
+.Sh EXAMPLES
 The output of
-.B mtrace
+.Nm mtrace
 is in two sections.  The first section is a short listing of the hops
 in the order they are queried, that is, in the reverse of the order
 from the
-.I source
+.Ae source
 to the
-.IR receiver .
+.Ae receiver .
 For each hop, a line is printed showing the hop number (counted
 negatively to indicate that this is the reverse path); the multicast
 routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to
@@ -349,8 +308,7 @@ the interval from when the query is issued until the response is
 received, both derived from the local system clock.  A sample use and
 output might be:
 .PP
-.nf
-.ft C
+.Bd -literal
 oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu 224.2.0.3
 Mtrace from 18.26.0.170 to 128.9.160.100 via group 224.2.0.3
 Querying full reverse path...
@@ -362,8 +320,8 @@ Querying full reverse path...
  -5  mit.dart.net (140.173.48.2)  DVMRP  thresh^ 1  71 ms
  -6  caraway.lcs.mit.edu (18.26.0.170)
 Round trip time 124 ms
-.fi
-.PP
+.Ed
+.Pp
 The second section provides a pictorial view of the path in the
 forward direction with data flow indicated by arrows pointing downward
 and the query path indicated by arrows pointing upward.  For each hop,
@@ -380,35 +338,26 @@ explained above.  The first group shows the statistics for all traffic
 flowing out the interface at one hop and in the interface at the next
 hop.  The second group shows the statistics only for traffic forwarded
 from the specified
-.I source
+.Ar source
 to the specified
-.IR group .
-.PP
+.Ar group .
+.Pp
 These statistics are shown on one or two lines for each hop.  Without
 any options, this second section of the output is printed only once,
 approximately 10 seconds after the initial trace.  One line is shown
 for each hop showing the statistics over that 10-second period.  If
 the
-.B \-l
+.Fl l
 option is given, the second section is repeated every 10 seconds and
 two lines are shown for each hop.  The first line shows the statistics
 for the last 10 seconds, and the second line shows the cumulative
 statistics over the period since the initial trace, which is 101
 seconds in the example below.  The second section of the output is
 omitted if the
-.B \-s
+.Fl s.
 option is set.
-.ie t \{\
-.ft C
-.  ie \w'i'<>\w'm' \{\" looks like this is not proper Courier font
-(If this example is not properly columned with a fixed-width font, get
-.B groff
-and try again.)
-.  \}
-.\}
-.PP
-.ft C
-.nf
+.Pp
+.Bd -literal
 Waiting to accumulate statistics... Results after 101 seconds:
 
   Source       Response Dest  Packet Statistics For  Only For Traffic
@@ -437,54 +386,49 @@ Waiting to accumulate statistics... Results after 101 seconds:
      v         \\ hop   -8 ms     8075        79 pps     18        0 pps
 128.9.160.100  128.9.160.100
   Receiver     Query Source
-.fi
-.PP
+.Ed
+.Pp
 Because the packet counts may be changing as the trace query is
 propagating, there may be small errors (off by 1 or 2) in these
 statistics.  However, those errors should not accumulate, so the
 cumulative statistics line should increase in accuracy as a new trace
 is run every 10 seconds.  There are two sources of larger errors, both
 of which show up as negative losses:
-.LP
-.RS
-.PD 0
-.TP 3
-\(bu
+.Bl -bullet -offset abcd
+.It
 If the input to a node is from a multi-access network with more than
 one other node attached, then the input count will be (close to) the
 sum of the output counts from all the attached nodes, but the output
 count from the previous hop on the traced path will be only part of
 that.  Hence the output count minus the input count will be negative.
-.TP 3
-\(bu
+.It
 In release 3.3 of the DVMRP multicast forwarding software for SunOS
 and other systems, a multicast packet generated on a router will be
 counted as having come in an interface even though it did not.  This
 creates the negative loss that can be seen in the example above.
-.PD
-.RE
-.LP
+.El
+.Pp
 Note that these negative losses may mask positive losses.
-.PP
+.Pp
 In the example, there is also one negative hop time.  This simply
 indicates a lack of synchronization between the system clocks across
 that hop.  This example also illustrates how the percentage loss is
 shown as two dashes when the number of packets sent is less than 10
 because the percentage would not be statistically valid.
-.PP
-A second example shows a trace to a receiver that is not local; the
-query is sent to the last-hop router with the
-.B \-g
+.Pp
+A second example shows a trace to a 
+.Ar receiver
+that is not local; the query is sent to the last-hop router with the
+.Fl g
 option.  In this example, the trace of the full reverse path resulted
 in no response because there was a node running an old version of
-.B mrouted
+.Nm mrouted
 that did not implement the multicast traceroute function, so
-.B mtrace
-switched to hop-by-hop mode.  The \*(lqRoute pruned\*(rq error code
+.Nm
+switched to hop-by-hop mode.  The "Route pruned" error code
 indicates that traffic for group 224.2.143.24 would not be forwarded.
-.PP
-.nf
-.ft C
+.Pp
+.Bd -literal
 oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \\
                            butter.lcs.mit.edu 224.2.143.24
 Mtrace from 204.62.246.73 to 18.26.0.151 via group 224.2.143.24
@@ -496,21 +440,34 @@ Querying full reverse path... * switching to hop-by-hop:
  -4  darpa.dart.net (140.173.240.2)  DVMRP  thresh^ 16  47 ms
  -5  * * * noc.hpc.org (192.187.8.2) [mrouted 2.2] didn't respond
 Round trip time 95 ms
-.fi
-.SH AUTHOR
+.Ed
+.Sh SEE ALSO
+.Xr mrouted 8 ,
+.Xr mrinfo 8 ,
+.Xr map-mbone 8 ,
+.Xr traceroute 8
+.Sh BUGS
+Versions 3.3 and 3.5 of
+.Nm mrouted
+will crash if a trace query is received via a
+unicast packet and
+.Nm mrouted
+has no route for the
+.Ar source
+address.  Therefore, do not use the
+.Fl g
+option unless the target
+.Nm mrouted
+has been verified to be 3.4 or newer than 3.5.
+.Sh AUTHORS
 Implemented by Steve Casner based on an initial prototype written by
 Ajit Thyagarajan.  The multicast traceroute mechanism was designed by
 Van Jacobson with help from Steve Casner, Steve Deering, Dino
 Farinacci, and Deb Agrawal; it was implemented in
-.B mrouted
+.Nm mrouted
 by Ajit Thyagarajan and Bill Fenner.  The option syntax and the output
 format of
-.B mtrace
+.Nm
 are modeled after the unicast
-.B traceroute
+.Nm traceroute
 program written by Van Jacobson.
-.SH SEE ALSO
-.BR mrouted (8) ,
-.BR mrinfo (8) ,
-.BR map-mbone (8) ,
-.BR traceroute (8)