Remove mrouted from -CURRENT.

Discussed with:	fenner, net@

1 files changed, 0 insertions, 589 deletions

diff --git a/usr.sbin/mrouted/mtrace.8 b/usr.sbin/mrouted/mtrace.8
deleted file mode 100644
index cd8d67d..0000000
--- a/usr.sbin/mrouted/mtrace.8
+++ /dev/null
@@ -1,589 +0,0 @@
-.\" Copyright (c) 1995 by the University of Southern California
-.\" All rights reserved.
-.\"
-.\" Permission to use, copy, modify, and distribute this software and its
-.\" documentation in source and binary forms for non-commercial purposes
-.\" and without fee is hereby granted, provided that the above copyright
-.\" notice appear in all copies and that both the copyright notice and
-.\" this permission notice appear in supporting documentation, and that
-.\" any documentation, advertising materials, and other materials related
-.\" to such distribution and use acknowledge that the software was
-.\" developed by the University of Southern California, Information
-.\" Sciences Institute.  The name of the University may not be used to
-.\" endorse or promote products derived from this software without
-.\" specific prior written permission.
-.\"
-.\" THE UNIVERSITY OF SOUTHERN CALIFORNIA makes no representations about
-.\" the suitability of this software for any purpose.  THIS SOFTWARE IS
-.\" PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
-.\" INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
-.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-.\"
-.\" 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.
-.\"
-.\" $FreeBSD$
-.\"
-.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
-.Op Fl e Ar extrahops
-.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 O
-.Op Fl p
-.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 T
-.Op Fl U
-.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.
-The
-.Nm
-utility utilizes a tracing feature implemented in multicast routers 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 0.0.0.0, 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.
-If the
-.Fl g
-flag is specified, the source address defaults to the host running
-.Nm ,
-and the receiver defaults to the router being addressed with
-the
-.Fl g
-flag.
-In this case, there are no required parameters.
-.Pp
-NOTE: For Solaris 2.4/2.5, if the multicast interface is not the default
-interface, the
-.Fl i
-option must be used to set the local address.
-.Pp
-The following options are available:
-.Bl -tag -width indent
-.It Fl e Ar extrahops
-Try tracing
-.Ar extrahops
-hops past a non-responding router.
-.It Fl g Ar gwy
-Send the trace query via unicast directly to the multicast router
-.Ar gwy
-rather than multicasting the query.
-This must be the last-hop router on the path from the intended
-.Ar source
-to the
-.Ar receiver .
-.Pp
-.Em CAUTION ! !
-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.
-.It Fl i Ar addr
-Use
-.Ar 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 request the response using multicast rather than attempting
-unicast for the last half of the tries.
-.It Fl m Ar n
-Set to
-.Ar n
-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 q Ar n
-Set the maximum number of query attempts for any hop to
-.Ar n .
-The default is 3.
-.It Fl O
-Do not use the Router-Alert IP option on those requests which need it.
-Some versions of Cisco's IOS cannot handle
-multicast traceroutes with IP options, so it may be necessary to use the
-.Fl O
-flag if the last-hop router is a Cisco.
-.It Fl p
-Listen passively for multicast responses from traces initiated by
-others.
-This works best when run on a multicast router.
-.It Fl P
-Loop indefinitely collecting the path every 10 seconds (see
-.Fl S Ar stat_int )
-and printing it when it changes.
-Do not print any statistics.
-.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
-Print a short form output including only the multicast path and not
-the packet rate and loss statistics.
-.It Fl S Ar n
-Change the interval between statistics gathering traces to
-.Ar n
-seconds (default 10 seconds).
-.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 127, except for local queries to the "all
-routers" multicast group which use ttl 1.
-.It Fl T
-"Tunnel statistics" mode; show loss rates for overall traffic.
-These statistics can be extremely misleading.
-.It Fl U
-Always request the response using unicast rather than attempting
-multicast first.
-.It Fl v
-Verbose mode; show hop times on the initial trace and statistics display.
-Also show the route that was used to forward the initial trace.
-.It Fl w Ar n
-Set the time to wait for a trace response to
-.Ar n
-seconds (default 3 seconds).
-.El
-.Sh USAGE
-.Ss "How It Works"
-The technique used by the
-.Nm traceroute
-utility 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 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 receiver is.
-Therefore it is necessary to specify a group that
-the intended receiver has joined.
-This multicast is sent with a
-default ttl of 127, 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
-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 receiver
-address may not be the desired interface for the path from the 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 w
-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 two) are made with
-the reply address set to standard multicast address, mtrace.mcast.net
-(224.0.1.32) with the ttl set to 32 more than what is needed to pass the
-thresholds seen so far along the path to the receiver.
-For each
-additional attempt, the ttl is increased by another 32 each time up to
-a maximum of 192.
-Since the desired router may not be able to send a
-multicast reply, the remainder of the attempts request that the
-response be sent via unicast to the host running
-.Nm .
-Alternatively, the multicast ttl may be set explicitly with the
-.Fl t
-option, the initial multicast attempts can be forced to use unicast
-instead with the
-.Fl U
-option, the final unicast attempts can be forced to use multicast
-instead with the
-.Fl M
-option, or if you specify
-.Fl UM ,
-.Nm
-will first attempt using unicast and then multicast.
-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.
-The
-.Nm
-utility will try to query three (changed with the
-.Fl e
-option) hops past a non-responding router, in the hopes that even
-though it is not capable of sending a response, it might be capable of
-forwarding the request on.
-.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, and the total
-ttl required for a packet to travel along this path.
-A sample use and
-output might be:
-.Pp
-.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; total ttl of 6 required.
-.Ed
-.Pp
-If a hop reports that it is using the default route to forward packets,
-the word
-.Em [default]
-is printed after that hop.
-If the
-.Fl v
-flag is supplied, the route being used to forward packets is printed
-in the form
-.Em [18.26.0/24] .
-.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 two sets of statistics.
-The first column contains the average packet rate for all traffic at
-each hop.
-The remaining 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 .
-The first group of statistics may be expanded to include loss rates
-using the
-.Fl T
-option.
-However, these numbers can be extremely misleading and require
-detailed knowledge of the routers involved to be interpreted properly.
-.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 or if no multicast group is specified.
-.Pp
-.Bd -literal
-Waiting to accumulate statistics... Results after 101 seconds:
-
-  Source       Response Dest    Overall   Packet Statistics For Traffic From
-18.26.0.170    128.9.160.100    Packet    18.26.0.170 To 224.2.0.3
-     |       __/ rtt  125 ms     Rate     Lost/Sent = Pct  Rate
-     v      /    hop   65 ms    -------   ---------------------
-18.26.0.144
-140.173.48.2   mit.dart.net
-     |     ^     ttl    1         0 pps      0/2  = --%  0 pps
-     v     |     hop    8 ms      0 pps      0/18 =  0%  0 pps
-140.173.48.1
-140.173.32.1   bbn.dart.net
-     |     ^     ttl    2         0 pps      0/2  = --%  0 pps
-     v     |     hop   12 ms      0 pps      0/18 =  0%  0 pps
-140.173.32.2
-140.173.64.1   dc.dart.net
-     |     ^     ttl    3        27 pps      0/2  = --%  0 pps
-     v     |     hop   34 ms     26 pps      0/18 =  0%  0 pps
-140.173.64.2
-140.173.128.1  la.dart.net
-     |     ^     ttl    4        83 pps      0/2  = --%  0 pps
-     v     |     hop   11 ms     79 pps      0/18 =  0%  0 pps
-140.173.128.2
-128.9.160.153  cub.isi.edu
-     |      \\__  ttl    5        83 pps      ?/2         0 pps
-     v         \\ hop   -8 ms     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:
-.Pp
-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.
-.Pp
-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.
-.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 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
-.Dq Output pruned
-error code
-indicates that traffic for group 224.2.143.24 would not be forwarded.
-.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
-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  Output 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
-.Nm traceroute
-program written by
-.An Van Jacobson .
-.Sh BUGS
-Statistics collection in passive mode does not always produce the same output
-as when actively collecting data.