diff options
Diffstat (limited to 'usr.sbin/mrouted/mtrace.8')
| -rw-r--r-- | usr.sbin/mrouted/mtrace.8 | 591 |
1 files changed, 0 insertions, 591 deletions
diff --git a/usr.sbin/mrouted/mtrace.8 b/usr.sbin/mrouted/mtrace.8 deleted file mode 100644 index 820fde13ec30f..0000000000000 --- a/usr.sbin/mrouted/mtrace.8 +++ /dev/null @@ -1,591 +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. -.\" -.\" mtrace.8,v 5.2 1998/12/04 04:48:16 fenner Exp -.\" -.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 \-e -.I extrahops -] [ -.B \-g -.I gateway -] [ -.B \-i -.I if_addr -] [ -.B \-l -] [ -.B \-M -] [ -.B \-m -.I max_hops -] [ -.B \-n -] [ -.B \-O -] [ -.B \-p -] [ -.B \-P -] [ -.B \-q -.I nqueries -] [ -.B \-r -.I resp_dest -] [ -.B \-s -] [ -.B \-S -.I stat_int -] [ -.B \-t -.I ttl -] [ -.B \-T -] [ -.B \-U -] [ -.B \-v -] [ -.B \-w -.I waittime -] -.I source -[ -.I receiver -] [ -.I group -] -.SH DESCRIPTION -Assessing problems in the distribution of IP multicast traffic -can be difficult. -.B mtrace -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 -.I receiver -to the -.IR 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 -.I source -host name or address. The default -.I receiver -is the host running mtrace, and the default -.I 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 -.I receiver -is a unicast address and the -.I group -is a multicast address. -If the -.B \-g -flag is specified, the source address defaults to the host running -mtrace, and the receiver defaults to the router being addressed with -the -.B \-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 -i option must be used to set the local address. -.SH OPTIONS -.TP 8 8 -.BI \-e\ extrahops -Try tracing -.I extrahops -hops past a non-responding router. -.TP 8 8 -.BI \-g\ gwy -Send the trace query via unicast directly to the multicast router -.I gwy -rather than multicasting the query. -This must be the last-hop router on the path from the intended -.I 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 -Use -.I addr -as the local interface address (on a multi-homed host) for sending the -trace query and as the default for the -.I receiver -and the response destination. -.TP 8 8 -.B \-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 -Always request the response using multicast rather than attempting -unicast for the last half of the tries. -.TP 8 8 -.BI \-m\ n -Set to -.I n -the maximum number of hops that will be traced from the -.I receiver -back toward the -.IR source . -The default is 32 hops (infinity for the DVMRP routing protocol). -.TP 8 8 -.B \-n -Print hop addresses numerically rather than symbolically and numerically -(saves a nameserver address-to-name lookup for each router found on the -path). -.TP 8 8 -.BI \-q\ n -Set the maximum number of query attempts for any hop to -.IR n . -The default is 3. -.TP 8 8 -.B \-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 --O flag if the last-hop router is a Cisco. -.TP 8 8 -.B \-p -Listen passively for multicast responses from traces initiated by -others. This works best when run on a multicast router. -.TP 8 8 -.B \-P -Loop indefinitely collecting the path every 10 seconds (see -.B \-S -.IR stat_int ) -and printing it when it changes. Do not print any statistics. -.TP 8 8 -.BI \-r\ host -Send the trace response to -.I host -rather than to the host on which -.B mtrace -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 -Print a short form output including only the multicast path and not -the packet rate and loss statistics. -.TP 8 8 -.BI \-S\ n -Change the interval between statistics gathering traces to -.I n -seconds (default 10 seconds). -.TP 8 8 -.BI \-t\ ttl -Set the -.I 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. -.TP 8 8 -.B \-T -"Tunnel statistics" mode; show loss rates for overall traffic. -These statistics can be extremely misleading. -.TP 8 8 -.B \-U -Always request the response using unicast rather than attempting -multicast first. -.TP 8 8 -.B \-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. -.TP 8 8 -.BI \-w\ n -Set the time to wait for a trace response to -.I n -seconds (default 3 seconds). -.SH USAGE -.SS How It Works -The technique used by the -.B 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 -.I receiver -to the -.IR source . -A trace query packet is sent to the last -hop multicast router (the leaf router for the desired -.I 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 . -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 -.IR 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 -.I source -to the -.IR 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 -.I 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 -.B \-t -option). -If the last hop router is known, it may also be addressed directly -using the -.B \-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 -.B \-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 -.IR receiver . -.SS Directing the Response -By default, -.B mtrace -first attempts to trace the full reverse path, unless the number of -hops to trace is explicitly set with the -.B \-m -option. If there is no response within a 3 second timeout interval -(changed with the -.B \-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 -.B \-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's 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 -.B mtrace . -Alternatively, the multicast ttl may be set explicitly with the -.B \-t -option, the initial multicast attempts can be forced to use unicast -instead with the -.B \-U -option, the final unicast attempts can be forced to use multicast -isntead with the -.B \-M -option, or if you specify -.B \-UM -.B mtrace -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, -.B mtrace -will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2 -request (as used by the -.B mrinfo -program) to see what kind of router it is. -.B mtrace -will try to query three (changed with the -.B \-e -option) hops past a non-responding router, in the hopes that even -though it isn't capable of sending a response, it might be capable of -forwarding the request on. -.SH EXAMPLES -The output of -.B 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 -to the -.IR 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 -.nf -.ft C -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. -.fi -.PP -If a hop reports that it is using the default route to forward packets, -the word -.B [default] -is printed after that hop. If the -.B \-v -flag is supplied, the route being used to forward packets is printed -in the form -.B [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 -.I source -to the specified -.IR group . -The first group of statistics may be expanded to include loss rates -using the -.B \-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 -.B \-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 -option is set or if no multicast group is specified. -.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 -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 -.fi -.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 -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 -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 -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 -.B \-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 -that did not implement the multicast traceroute function, so -.B mtrace -switched to hop-by-hop mode. The \*(lqOutput pruned\*(rq error code -indicates that traffic for group 224.2.143.24 would not be forwarded. -.PP -.nf -.ft C -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 -.fi -.SH AUTHOR -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 -by Ajit Thyagarajan and Bill Fenner. The option syntax and the output -format of -.B mtrace -are modeled after the unicast -.B traceroute -program written by Van Jacobson. -.SH SEE ALSO -.BR mrouted (8) , -.BR mrinfo (8) , -.BR map-mbone (8) , -.BR traceroute (8) -.SH BUGS -.PP -Statistics collection in passive mode doesn't always produce the same output -as when actively collecting data. |