Annotation of embedaddon/mrouted/mtrace.8, revision 1.1.1.1
1.1 misho 1: .\" $OpenBSD: mtrace.8,v 1.16 2010/03/26 19:30:40 jmc Exp $
2: .\" $NetBSD: mtrace.8,v 1.4 1995/12/10 10:57:11 mycroft Exp $
3: .\"
4: .\" Copyright (c) 1993, 1998-2001.
5: .\" The University of Southern California/Information Sciences Institute.
6: .\" All rights reserved.
7: .\"
8: .\" Redistribution and use in source and binary forms, with or without
9: .\" modification, are permitted provided that the following conditions
10: .\" are met:
11: .\" 1. Redistributions of source code must retain the above copyright
12: .\" notice, this list of conditions and the following disclaimer.
13: .\" 2. Redistributions in binary form must reproduce the above copyright
14: .\" notice, this list of conditions and the following disclaimer in the
15: .\" documentation and/or other materials provided with the distribution.
16: .\" 3. Neither the name of the project nor the names of its contributors
17: .\" may be used to endorse or promote products derived from this software
18: .\" without specific prior written permission.
19: .\"
20: .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30: .\" SUCH DAMAGE.
31: .\"
32: .\" Other copyrights might apply to parts of this software and are so
33: .\" noted when applicable.
34: .\"
35: .\" This manual page (but not the software) was derived from the
36: .\" manual page for the traceroute program which bears the following
37: .\" copyright notice:
38: .\"
39: .\" Copyright (c) 1988 The Regents of the University of California.
40: .\" All rights reserved.
41: .\"
42: .\" This code is derived from software contributed to Berkeley by
43: .\" Van Jacobson.
44: .\"
45: .\" Redistribution and use in source and binary forms, with or without
46: .\" modification, are permitted provided that the following conditions
47: .\" are met:
48: .\" 1. Redistributions of source code must retain the above copyright
49: .\" notice, this list of conditions and the following disclaimer.
50: .\" 2. Redistributions in binary form must reproduce the above copyright
51: .\" notice, this list of conditions and the following disclaimer in the
52: .\" documentation and/or other materials provided with the distribution.
53: .\" 3. Neither the name of the University nor the names of its contributors
54: .\" may be used to endorse or promote products derived from this software
55: .\" without specific prior written permission.
56: .\"
57: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
58: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
59: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
60: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
61: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
62: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
63: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
65: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
66: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
67: .\" SUCH DAMAGE.
68: .\"
69: .Dd $Mdocdate: March 26 2010 $
70: .Dt MTRACE 8 SMM
71: .Os
72: .Sh NAME
73: .Nm mtrace
74: .Nd print multicast path from a source to a receiver
75: .Sh SYNOPSIS
76: .Nm mtrace
77: .Op Fl lMnpsv
78: .Op Fl g Ar gateway
79: .Op Fl i Ar if_addr
80: .Op Fl m Ar max_hops
81: .Op Fl q Ar nqueries
82: .Op Fl r Ar host
83: .Op Fl S Ar stat_int
84: .Op Fl t Ar ttl
85: .Op Fl w Ar waittime
86: .Ar source
87: .Op Ar receiver
88: .Op Ar group
89: .Sh DESCRIPTION
90: Assessing problems in the distribution of IP multicast traffic
91: can be difficult.
92: .Nm
93: utilizes a tracing feature implemented in multicast routers
94: .Pf ( Nm mrouted
95: version 3.3 and later) that is
96: accessed via an extension to the IGMP protocol.
97: A trace query is passed hop-by-hop along the reverse path from the
98: .Ar receiver
99: to the
100: .Ar source ,
101: collecting hop addresses, packet counts, and routing error conditions
102: along the path, and then the response is returned to the requestor.
103: .Pp
104: The only required parameter is the
105: .Ar source
106: host name or address.
107: The default
108: .Ar receiver
109: is the host running mtrace, and the default
110: .Ar group
111: is "MBone Audio" (224.2.0.1), which is sufficient if packet loss
112: statistics for a particular multicast group are not needed.
113: These two optional parameters may be specified to test the path to some other
114: receiver in a particular group, subject to some constraints as
115: detailed below.
116: The two parameters can be distinguished because the
117: .Ar receiver
118: is a unicast address and the
119: .Ar group
120: is a multicast address.
121: .Pp
122: The options are as follows:
123: .Bl -tag -width addr_xy
124: .It Fl g Ar gateway
125: Send the trace query via unicast directly to the multicast router
126: .Ar gateway
127: rather than multicasting the query.
128: This must be the last-hop router on the path from the intended
129: .Ar source
130: to the
131: .Ar receiver .
132: .Em NOTE: Read the BUGS section below.
133: .It Fl i Ar if_addr
134: Use
135: .Ar if_addr
136: as the local interface address (on a multi-homed host) for sending the
137: trace query and as the default for the
138: .Ar receiver
139: and the response destination.
140: .It Fl l
141: Loop indefinitely printing packet rate and loss statistics for the
142: multicast path every 10 seconds (see
143: .Fl S Ar stat_int ) .
144: .It Fl M
145: Always send the response using multicast rather than attempting
146: unicast first.
147: .It Fl m Ar max_hops
148: Set to
149: the maximum number of hops that will be traced from the
150: .Ar receiver
151: back toward the
152: .Ar source .
153: The default is 32 hops (infinity for the DVMRP routing protocol).
154: .It Fl n
155: Print hop addresses numerically rather than symbolically and numerically
156: (saves a nameserver address-to-name lookup for each router found on the
157: path).
158: .It Fl p
159: Listen passively for multicast responses from traces initiated by others.
160: This works best when run on a multicast router.
161: .It Fl q Ar nqueries
162: Set the maximum number of query attempts for any hop to
163: .Ar nqueries .
164: The default is 3.
165: .It Fl r Ar host
166: Send the trace response to
167: .Ar host
168: rather than to the host on which
169: .Nm
170: is being run, or to a multicast address other than the one registered
171: for this purpose (224.0.1.32).
172: .It Fl S Ar stat_int
173: Change the interval between statistics gathering traces to
174: .Ar stat_int
175: seconds (default 10 seconds).
176: .It Fl s
177: Print a short form output including only the multicast path and not
178: the packet rate and loss statistics.
179: .It Fl t Ar ttl
180: Set the
181: .Ar ttl
182: (time-to-live, or number of hops) for multicast trace queries and
183: responses.
184: The default is 64, except for local queries to the
185: "all routers" multicast group which use ttl 1.
186: .It Fl v
187: Verbose mode; show hop times on the initial trace and statistics display.
188: .It Fl w Ar waittime
189: Set the time to wait for a trace response to
190: .Ar waittime
191: seconds (default 3 seconds).
192: .El
193: .Ss How \&It Works
194: The technique used by the
195: .Nm traceroute
196: tool to trace unicast network paths will not work for IP multicast
197: because ICMP responses are specifically forbidden for multicast traffic.
198: Instead, a tracing feature has been built into the multicast routers.
199: This technique has the advantage that additional information about
200: packet rates and losses can be accumulated while the number of packets
201: sent is minimized.
202: .Pp
203: Since multicast uses
204: reverse path forwarding, the trace is run backwards from the
205: .Ar receiver
206: to the
207: .Ar source .
208: A trace query packet is sent to the last
209: hop multicast router (the leaf router for the desired
210: .Ar receiver
211: address).
212: The last hop router builds a trace response packet, fills in
213: a report for its hop, and forwards the trace packet using unicast to
214: the router it believes is the previous hop for packets originating
215: from the specified
216: .Ar source .
217: Each router along the path adds its report and forwards the packet.
218: When the trace response packet reaches the first hop router (the router
219: that is directly connected to the source's net), that router sends the
220: completed response to the response destination address specified in
221: the trace query.
222: .Pp
223: If some multicast router along the path does not implement the
224: multicast traceroute feature or if there is some outage, then no
225: response will be returned.
226: To solve this problem, the trace query includes a maximum hop count field
227: to limit the number of hops traced before the response is returned.
228: That allows a partial path to be traced.
229: .Pp
230: The reports inserted by each router contain not only the address of
231: the hop, but also the ttl required to forward and some flags to indicate
232: routing errors, plus counts of the total number of packets on the
233: incoming and outgoing interfaces and those forwarded for the specified
234: .Ar group .
235: Taking differences in these counts for two traces separated in time
236: and comparing the output packet counts from one hop with the input
237: packet counts of the next hop allows the calculation of packet rate
238: and packet loss statistics for each hop to isolate congestion
239: problems.
240: .Ss Finding the Last-Hop Router
241: The trace query must be sent to the multicast router which is the
242: last hop on the path from the
243: .Ae source
244: to the
245: .Ar receiver .
246: If the
247: .Ar receiver
248: is on the local subnet (as determined using the subnet
249: mask), then the default method is to multicast the trace query to
250: all-routers.mcast.net (224.0.0.2) with a ttl of 1.
251: Otherwise, the trace query is multicast to the
252: .Ar group
253: address since the last hop router will be a member of that group if
254: the
255: .Ar receiver
256: is.
257: Therefore it is necessary to specify a
258: .Ar group
259: that the intended
260: .Ar receiver
261: is joined.
262: This multicast is sent with a default ttl of 64, which may not be sufficient
263: for all cases (changed with the
264: .Fl t
265: option).
266: If the last hop router is known, it may also be addressed directly
267: using the
268: .Fl g
269: option).
270: Alternatively, if it is desired to trace a group that the
271: .Ar receiver
272: has not joined, but it is known that the last-hop router is a
273: member of another group, the
274: .Fl g
275: option may also be used to specify a different multicast address for the
276: trace query.
277: .Pp
278: When tracing from a multihomed host or router, the default
279: .Ar receiver
280: address may not be the desired interface for the path from the
281: .Ar source .
282: In that case, the desired interface should be specified explicitly as
283: the
284: .Ar receiver .
285: .Ss Directing the Response
286: By default,
287: .Nm
288: first attempts to trace the full reverse path, unless the number of
289: hops to trace is explicitly set with the
290: .Fl m
291: option.
292: If there is no response within a 3 second timeout interval
293: (changed with the
294: .Fl m
295: option), a "*" is printed and the probing switches to hop-by-hop mode.
296: Trace queries are issued starting with a maximum hop count of one and
297: increasing by one until the full path is traced or no response is
298: received.
299: At each hop, multiple probes are sent (default is three, changed with
300: .Fl q
301: option).
302: The first half of the attempts (default is one) are made with
303: the unicast address of the host running
304: .Nm
305: as the destination for the response.
306: Since the unicast route may be blocked, the remainder of attempts request
307: that the response be multicast to mtrace.mcast.net (224.0.1.32) with the
308: ttl set to 32 more than what's needed to pass the thresholds seen so far
309: along the path to the
310: .Ar receiver .
311: For the last quarter of the attempts (default is
312: one), the ttl is increased by another 32 each time up to a maximum of 192.
313: Alternatively, the ttl may be set explicitly with the
314: .Fl t
315: option and/or the initial unicast attempts can be forced to use
316: multicast instead with the
317: .Fl m
318: option.
319: For each attempt, if no response is received within the timeout,
320: a "*" is printed.
321: After the specified number of attempts have failed,
322: .Nm
323: will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
324: request (as used by the
325: .Nm mrinfo
326: program) to see what kind of router it is.
327: .Sh EXAMPLES
328: The output of
329: .Nm
330: is in two sections.
331: The first section is a short listing of the hops in the order they are
332: queried, that is, in the reverse of the order from the
333: .Ae source
334: to the
335: .Ae receiver .
336: For each hop, a line is printed showing the hop number (counted
337: negatively to indicate that this is the reverse path); the multicast
338: routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to
339: forward data (to the previous hop in the listing as indicated by the
340: up-arrow character); and the cumulative delay for the query to reach
341: that hop (valid only if the clocks are synchronized).
342: This first section ends with a line showing the round-trip time which measures
343: the interval from when the query is issued until the response is
344: received, both derived from the local system clock.
345: A sample use and output might be:
346: .Bd -literal
347: oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu 224.2.0.3
348: Mtrace from 18.26.0.170 to 128.9.160.100 via group 224.2.0.3
349: Querying full reverse path...
350: 0 oak.isi.edu (128.9.160.100)
351: -1 cub.isi.edu (128.9.160.153) DVMRP thresh^ 1 3 ms
352: -2 la.dart.net (140.173.128.1) DVMRP thresh^ 1 14 ms
353: -3 dc.dart.net (140.173.64.1) DVMRP thresh^ 1 50 ms
354: -4 bbn.dart.net (140.173.32.1) DVMRP thresh^ 1 63 ms
355: -5 mit.dart.net (140.173.48.2) DVMRP thresh^ 1 71 ms
356: -6 caraway.lcs.mit.edu (18.26.0.170)
357: Round trip time 124 ms
358: .Ed
359: .Pp
360: The second section provides a pictorial view of the path in the
361: forward direction with data flow indicated by arrows pointing downward
362: and the query path indicated by arrows pointing upward.
363: For each hop, both the entry and exit addresses of the router are shown if
364: different, along with the initial ttl required on the packet in order
365: to be forwarded at this hop and the propagation delay across the hop
366: assuming that the routers at both ends have synchronized clocks.
367: The right half of this section is composed of several columns of
368: statistics in two groups.
369: Within each group, the columns are the number of packets lost, the number
370: of packets sent, the percentage lost, and the average packet rate at each hop.
371: These statistics are calculated from differences between traces and from
372: hop to hop as explained above.
373: The first group shows the statistics for all traffic flowing out the interface
374: at one hop and in the interface at the next hop.
375: The second group shows the statistics only for traffic forwarded
376: from the specified
377: .Ar source
378: to the specified
379: .Ar group .
380: .Pp
381: These statistics are shown on one or two lines for each hop.
382: Without any options, this second section of the output is printed only once,
383: approximately 10 seconds after the initial trace.
384: One line is shown for each hop showing the statistics over that 10-second
385: period.
386: If the
387: .Fl l
388: option is given, the second section is repeated every 10 seconds and
389: two lines are shown for each hop.
390: The first line shows the statistics for the last 10 seconds, and the second
391: line shows the cumulative statistics over the period since the initial trace,
392: which is 101 seconds in the example below.
393: The second section of the output is omitted if the
394: .Fl s .
395: option is set.
396: .Bd -literal
397: Waiting to accumulate statistics... Results after 101 seconds:
398:
399: Source Response Dest Packet Statistics For Only For Traffic
400: 18.26.0.170 128.9.160.100 All Multicast Traffic From 18.26.0.170
401: | __/ rtt 125 ms Lost/Sent = Pct Rate To 224.2.0.3
402: v / hop 65 ms --------------------- ------------------
403: 18.26.0.144
404: 140.173.48.2 mit.dart.net
405: | ^ ttl 1 0/6 = --% 0 pps 0/2 = --% 0 pps
406: v | hop 8 ms 1/52 = 2% 0 pps 0/18 = 0% 0 pps
407: 140.173.48.1
408: 140.173.32.1 bbn.dart.net
409: | ^ ttl 2 0/6 = --% 0 pps 0/2 = --% 0 pps
410: v | hop 12 ms 1/52 = 2% 0 pps 0/18 = 0% 0 pps
411: 140.173.32.2
412: 140.173.64.1 dc.dart.net
413: | ^ ttl 3 0/271 = 0% 27 pps 0/2 = --% 0 pps
414: v | hop 34 ms -1/2652 = 0% 26 pps 0/18 = 0% 0 pps
415: 140.173.64.2
416: 140.173.128.1 la.dart.net
417: | ^ ttl 4 -2/831 = 0% 83 pps 0/2 = --% 0 pps
418: v | hop 11 ms -3/8072 = 0% 79 pps 0/18 = 0% 0 pps
419: 140.173.128.2
420: 128.9.160.153 cub.isi.edu
421: | \e__ ttl 5 833 83 pps 2 0 pps
422: v \e hop -8 ms 8075 79 pps 18 0 pps
423: 128.9.160.100 128.9.160.100
424: Receiver Query Source
425: .Ed
426: .Pp
427: Because the packet counts may be changing as the trace query is
428: propagating, there may be small errors (off by 1 or 2) in these
429: statistics.
430: However, those errors should not accumulate, so the cumulative statistics
431: line should increase in accuracy as a new trace is run every 10 seconds.
432: There are two sources of larger errors,
433: both of which show up as negative losses:
434: .Bl -bullet -offset abcd
435: .It
436: If the input to a node is from a multi-access network with more than
437: one other node attached, then the input count will be (close to) the
438: sum of the output counts from all the attached nodes, but the output
439: count from the previous hop on the traced path will be only part of
440: that.
441: Hence the output count minus the input count will be negative.
442: .It
443: In release 3.3 of the DVMRP multicast forwarding software for SunOS
444: and other systems, a multicast packet generated on a router will be
445: counted as having come in an interface even though it did not.
446: This creates the negative loss that can be seen in the example above.
447: .El
448: .Pp
449: Note that these negative losses may mask positive losses.
450: .Pp
451: In the example, there is also one negative hop time.
452: This simply indicates a lack of synchronization between the system clocks
453: across that hop.
454: This example also illustrates how the percentage loss is
455: shown as two dashes when the number of packets sent is less than 10
456: because the percentage would not be statistically valid.
457: .Pp
458: A second example shows a trace to a
459: .Ar receiver
460: that is not local; the query is sent to the last-hop router with the
461: .Fl g
462: option.
463: In this example, the trace of the full reverse path resulted
464: in no response because there was a node running an old version of
465: .Nm mrouted
466: that did not implement the multicast traceroute function, so
467: .Nm
468: switched to hop-by-hop mode.
469: The "Route pruned" error code indicates that traffic for group 224.2.143.24
470: would not be forwarded.
471: .Bd -literal
472: oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \e
473: butter.lcs.mit.edu 224.2.143.24
474: Mtrace from 204.62.246.73 to 18.26.0.151 via group 224.2.143.24
475: Querying full reverse path... * switching to hop-by-hop:
476: 0 butter.lcs.mit.edu (18.26.0.151)
477: -1 jam.lcs.mit.edu (18.26.0.144) DVMRP thresh^ 1 33 ms Route pruned
478: -2 bbn.dart.net (140.173.48.1) DVMRP thresh^ 1 36 ms
479: -3 dc.dart.net (140.173.32.2) DVMRP thresh^ 1 44 ms
480: -4 darpa.dart.net (140.173.240.2) DVMRP thresh^ 16 47 ms
481: -5 * * * noc.hpc.org (192.187.8.2) [mrouted 2.2] didn't respond
482: Round trip time 95 ms
483: .Ed
484: .Sh SEE ALSO
485: .Xr map-mbone 8 ,
486: .Xr mrinfo 8 ,
487: .Xr mrouted 8 ,
488: .Xr traceroute 8
489: .Sh AUTHORS
490: Implemented by Steve Casner based on an initial prototype written by
491: Ajit Thyagarajan.
492: The multicast traceroute mechanism was designed by
493: Van Jacobson with help from Steve Casner, Steve Deering, Dino
494: Farinacci, and Deb Agrawal; it was implemented in
495: .Nm mrouted
496: by Ajit Thyagarajan and Bill Fenner.
497: The option syntax and the output format of
498: .Nm
499: are modeled after the unicast
500: .Nm traceroute
501: program written by Van Jacobson.
502: .Sh BUGS
503: Versions 3.3 and 3.5 of
504: .Nm mrouted
505: will crash if a trace query is received via a
506: unicast packet and
507: .Nm mrouted
508: has no route for the
509: .Ar source
510: address.
511: Therefore, do not use the
512: .Fl g
513: option unless the target
514: .Nm mrouted
515: has been verified to be 3.4 or newer than 3.5.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to mtrace.8 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / mrouted