docs: Added All OpenBSD Manuals

1 files changed, 528 insertions, 0 deletions

diff --git a/static/openbsd/man8/mtrace.8 b/static/openbsd/man8/mtrace.8
new file mode 100644
index 00000000..9ba0b666
--- /dev/null
+++ b/static/openbsd/man8/mtrace.8
@@ -0,0 +1,528 @@
+.\"	$OpenBSD: mtrace.8,v 1.18 2014/09/08 01:27:55 schwarze Exp $
+.\"	$NetBSD: mtrace.8,v 1.4 1995/12/10 10:57:11 mycroft Exp $
+.\"
+.\" Copyright (c) 1993, 1998-2001.
+.\" The University of Southern California/Information Sciences Institute.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the project nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.\" Other copyrights might apply to parts of this software and are so
+.\" noted when applicable.
+.\"
+.\" This manual page (but not the software) was derived from the
+.\" manual page for the traceroute program which bears the following
+.\" copyright notice:
+.\"
+.\" Copyright (c) 1988 The Regents of the University of California.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" Van Jacobson.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: September 8 2014 $
+.Dt MTRACE 8
+.Os
+.Sh NAME
+.Nm mtrace
+.Nd print multicast path from a source to a receiver
+.Sh SYNOPSIS
+.Nm mtrace
+.Op Fl lMnpsv
+.Op Fl g Ar gateway
+.Op Fl i Ar if_addr
+.Op Fl m Ar max_hops
+.Op Fl q Ar nqueries
+.Op Fl r Ar host
+.Op Fl S Ar stat_int
+.Op Fl t Ar ttl
+.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.
+.Nm
+utilizes a tracing feature implemented in multicast routers
+.Pf ( 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
+.Ar receiver
+to the
+.Ar source ,
+collecting hop addresses, packet counts, and routing error conditions
+along the path, and then the response is returned to the requestor.
+.Pp
+The only required parameter is the
+.Ar source
+host name or address.
+The default
+.Ar receiver
+is the host running mtrace, and the default
+.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
+.Ar receiver
+is a unicast address and the
+.Ar group
+is a multicast address.
+.Pp
+The options are as follows:
+.Bl -tag -width addr_xy
+.It Fl g Ar gateway
+Send the trace query via unicast directly to the multicast router
+.Ar gateway
+rather than multicasting the query.
+This must be the last-hop router on the path from the intended
+.Ar source
+to the
+.Ar receiver .
+.Em NOTE: Read the BUGS section below.
+.It Fl i Ar if_addr
+Use
+.Ar if_addr
+as the local interface address (on a multi-homed host) for sending the
+trace query and as the default for the
+.Ar receiver
+and the response destination.
+.It Fl l
+Loop indefinitely printing packet rate and loss statistics for the
+multicast path every 10 seconds (see
+.Fl S Ar stat_int ) .
+.It Fl M
+Always send the response using multicast rather than attempting
+unicast first.
+.It Fl m Ar max_hops
+Set to
+the maximum number of hops that will be traced from the
+.Ar receiver
+back toward the
+.Ar source .
+The default is 32 hops (infinity for the DVMRP routing protocol).
+.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
+path).
+.It Fl p
+Listen passively for multicast responses from traces initiated by others.
+This works best when run on a multicast router.
+.It Fl q Ar nqueries
+Set the maximum number of query attempts for any hop to
+.Ar nqueries .
+The default is 3.
+.It Fl r Ar host
+Send the trace response to
+.Ar host
+rather than to the host on which
+.Nm
+is being run, or to a multicast address other than the one registered
+for this purpose (224.0.1.32).
+.It Fl S Ar stat_int
+Change the interval between statistics gathering traces to
+.Ar stat_int
+seconds (default 10 seconds).
+.It Fl s
+Print a short form output including only the multicast path and not
+the packet rate and loss statistics.
+.It Fl t Ar ttl
+Set the
+.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.
+.It Fl v
+Verbose mode; show hop times on the initial trace and statistics display.
+.It Fl w Ar waittime
+Set the time to wait for a trace response to
+.Ar waittime
+seconds (default 3 seconds).
+.El
+.Ss How \&It Works
+The technique used by the
+.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
+Since multicast uses
+reverse path forwarding, the trace is run backwards from the
+.Ar receiver
+to the
+.Ar source .
+A trace query packet is sent to the last
+hop multicast router (the leaf router for the desired
+.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
+.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
+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
+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
+.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
+The trace query must be sent to the multicast router which is the
+last hop on the path from the
+.Ar source
+to the
+.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
+.Ar group
+address since the last hop router will be a member of that group if
+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
+.Fl t
+option).
+If the last hop router is known, it may also be addressed directly
+using the
+.Fl g
+option).
+Alternatively, if it is desired to trace a group that the
+.Ar receiver
+has not joined, but it is known that the last-hop router is a
+member of another group, the
+.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
+.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
+.Ar receiver .
+.Ss Directing the Response
+By default,
+.Nm
+first attempts to trace the full reverse path, unless the number of
+hops to trace is explicitly set with the
+.Fl m
+option.
+If there is no response within a 3 second timeout interval
+(changed with the
+.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
+.Fl q
+option).
+The first half of the attempts (default is one) are made with
+the unicast address of the host running
+.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
+.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
+.Fl t
+option and/or the initial unicast attempts can be forced to use
+multicast instead with the
+.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,
+.Nm
+will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
+request (as used by the
+.Nm mrinfo
+program) to see what kind of router it is.
+.Sh EXAMPLES
+The output of
+.Nm
+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
+.Ar source
+to the
+.Ar 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
+forward data (to the previous hop in the listing as indicated by the
+up-arrow character); and the cumulative delay for the query to reach
+that hop (valid only if the clocks are synchronized).
+This first section ends with a line showing the round-trip time which measures
+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:
+.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...
+  0  oak.isi.edu (128.9.160.100)
+ -1  cub.isi.edu (128.9.160.153)  DVMRP  thresh^ 1  3 ms
+ -2  la.dart.net (140.173.128.1)  DVMRP  thresh^ 1  14 ms
+ -3  dc.dart.net (140.173.64.1)  DVMRP  thresh^ 1  50 ms
+ -4  bbn.dart.net (140.173.32.1)  DVMRP  thresh^ 1  63 ms
+ -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
+.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, both the entry and exit addresses of the router are shown if
+different, along with the initial ttl required on the packet in order
+to be forwarded at this hop and the propagation delay across the hop
+assuming that the routers at both ends have synchronized clocks.
+The right half of this section is composed of several columns of
+statistics in two groups.
+Within each group, the columns are the number of packets lost, the number
+of packets sent, the percentage lost, and the average packet rate at each hop.
+These statistics are calculated from differences between traces and from
+hop to hop as 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
+.Ar source
+to the specified
+.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
+.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
+.Fl s .
+option is set.
+.Bd -literal
+Waiting to accumulate statistics... Results after 101 seconds:
+
+  Source       Response Dest  Packet Statistics For  Only For Traffic
+18.26.0.170    128.9.160.100  All Multicast Traffic  From 18.26.0.170
+     |       __/ rtt  125 ms  Lost/Sent = Pct  Rate    To 224.2.0.3
+     v      /    hop   65 ms  ---------------------  ------------------
+18.26.0.144
+140.173.48.2   mit.dart.net
+     |     ^     ttl    1      0/6    = --%   0 pps   0/2  = --%  0 pps
+     v     |     hop    8 ms   1/52   =  2%   0 pps   0/18 =  0%  0 pps
+140.173.48.1
+140.173.32.1   bbn.dart.net
+     |     ^     ttl    2      0/6    = --%   0 pps   0/2  = --%  0 pps
+     v     |     hop   12 ms   1/52   =  2%   0 pps   0/18 =  0%  0 pps
+140.173.32.2
+140.173.64.1   dc.dart.net
+     |     ^     ttl    3      0/271  =  0%  27 pps   0/2  = --%  0 pps
+     v     |     hop   34 ms  -1/2652 =  0%  26 pps   0/18 =  0%  0 pps
+140.173.64.2
+140.173.128.1  la.dart.net
+     |     ^     ttl    4     -2/831  =  0%  83 pps   0/2  = --%  0 pps
+     v     |     hop   11 ms  -3/8072 =  0%  79 pps   0/18 =  0%  0 pps
+140.173.128.2
+128.9.160.153  cub.isi.edu
+     |      \e__  ttl    5        833         83 pps     2         0 pps
+     v         \e hop   -8 ms     8075        79 pps     18        0 pps
+128.9.160.100  128.9.160.100
+  Receiver     Query Source
+.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:
+.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.
+.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.
+.El
+.Pp
+Note that these negative losses may mask positive losses.
+.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
+.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
+.Nm mrouted
+that did not implement the multicast traceroute function, so
+.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.
+.Bd -literal
+oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \e
+                           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
+Querying full reverse path... * switching to hop-by-hop:
+  0  butter.lcs.mit.edu (18.26.0.151)
+ -1  jam.lcs.mit.edu (18.26.0.144)  DVMRP  thresh^ 1  33 ms  Route pruned
+ -2  bbn.dart.net (140.173.48.1)  DVMRP  thresh^ 1  36 ms
+ -3  dc.dart.net (140.173.32.2)  DVMRP  thresh^ 1  44 ms
+ -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
+.Ed
+.Sh SEE ALSO
+.Xr map-mbone 8 ,
+.Xr mrinfo 8 ,
+.Xr mrouted 8 ,
+.Xr traceroute 8
+.Sh AUTHORS
+.An -nosplit
+Implemented by
+.An Steve Casner
+based on an initial prototype written by
+.An Ajit Thyagarajan .
+The multicast traceroute mechanism was designed by
+.An Van Jacobson
+with help from
+.An Steve Casner ,
+.An Steve Deering ,
+.An Dino Farinacci ,
+and
+.An Deb Agrawal ;
+it was implemented in
+.Nm mrouted
+by
+.An Ajit Thyagarajan
+and
+.An Bill Fenner .
+The option syntax and the output format of
+.Nm
+are modeled after the unicast
+.Xr traceroute 8
+program written by
+.An Van Jacobson .
+.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.