diff options
Diffstat (limited to 'usr.sbin/mrouted/mtrace.8')
| -rw-r--r-- | usr.sbin/mrouted/mtrace.8 | 499 |
1 files changed, 499 insertions, 0 deletions
diff --git a/usr.sbin/mrouted/mtrace.8 b/usr.sbin/mrouted/mtrace.8 new file mode 100644 index 000000000000..bfc6dd54135c --- /dev/null +++ b/usr.sbin/mrouted/mtrace.8 @@ -0,0 +1,499 @@ +.\" 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. +.\" +.\" $Id: mtrace.8,v 3.5 1995/05/09 01:23:58 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 \-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 +.I src_addr +] [ +.B \-t +.I ttl +] [ +.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 +.RB ( 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 +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 "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 +is a unicast address and the +.I group +is a multicast address. +.SH OPTIONS +.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!! +Version 3.3 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 newer than 3.3. +.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. +.TP 8 8 +.B \-M +Always send the response using multicast rather than attempting +unicast first. +.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 \-p +Listen passively for multicast responses from traces initiated by +others (not implemented yet). +.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 \-t\ ttl +Set the +.I 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 +.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 64, 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 one) are made with +the unicast address of the host running +.B mtrace +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 +one), the ttl is increased by another 32 each time up to a maximum of +192. Alternatively, the ttl may be set explicity with the +.B \-t +option and/or the initial unicast attempts can be forced to use +multicast instead with the +.B \-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 +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. +.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. 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 +.fi +.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 +.I source +to the specified +.IR 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 +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. +.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 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 + | \\__ ttl 5 833 83 pps 2 0 pps + v \\ hop -8 ms 8075 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 \*(lqRoute 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 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 +.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) |