1 .\" Copyright (c) 1995 by the University of Southern California
2 .\" All rights reserved.
4 .\" Permission to use, copy, modify, and distribute this software and its
5 .\" documentation in source and binary forms for non-commercial purposes
6 .\" and without fee is hereby granted, provided that the above copyright
7 .\" notice appear in all copies and that both the copyright notice and
8 .\" this permission notice appear in supporting documentation, and that
9 .\" any documentation, advertising materials, and other materials related
10 .\" to such distribution and use acknowledge that the software was
11 .\" developed by the University of Southern California, Information
12 .\" Sciences Institute. The name of the University may not be used to
13 .\" endorse or promote products derived from this software without
14 .\" specific prior written permission.
16 .\" THE UNIVERSITY OF SOUTHERN CALIFORNIA makes no representations about
17 .\" the suitability of this software for any purpose. THIS SOFTWARE IS
18 .\" PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
19 .\" INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
20 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
22 .\" Other copyrights might apply to parts of this software and are so
23 .\" noted when applicable.
25 .\" This manual page (but not the software) was derived from the
26 .\" manual page for the traceroute program which bears the following
29 .\" Copyright (c) 1988 The Regents of the University of California.
30 .\" All rights reserved.
32 .\" $FreeBSD: src/usr.sbin/mrouted/mtrace.8,v 1.12.2.6 2003/03/11 22:31:29 trhodes Exp $
39 .Nd print multicast path from a source to a receiver
65 Assessing problems in the distribution of IP multicast traffic
69 utility utilizes a tracing feature implemented in multicast routers that is
70 accessed via an extension to the IGMP protocol. A trace query is
71 passed hop-by-hop along the reverse path from the
75 collecting hop addresses, packet counts, and routing error conditions
76 along the path, and then the response is returned to the requestor.
78 The only required parameter is the
80 host name or address. The default
82 is the host running mtrace, and the default
84 is 0.0.0.0, which is sufficient if packet loss
85 statistics for a particular multicast group are not needed. These two
86 optional parameters may be specified to test the path to some other
87 receiver in a particular group, subject to some constraints as
88 detailed below. The two parameters can be distinguished because the
90 is a unicast address and the
92 is a multicast address.
95 flag is specified, the source address defaults to the host running
97 and the receiver defaults to the router being addressed with
100 flag. In this case, there are no required parameters.
102 NOTE: For Solaris 2.4/2.5, if the multicast interface is not the default
105 option must be used to set the local address.
107 The following options are available:
108 .Bl -tag -width indent
109 .It Fl e Ar extrahops
112 hops past a non-responding router.
114 Send the trace query via unicast directly to the multicast router
116 rather than multicasting the query.
117 This must be the last-hop router on the path from the intended
123 Versions 3.3 and 3.5 of
125 will crash if a trace query is received via a
130 address. Therefore, do not use the
132 option unless the target
134 has been verified to be 3.4 or newer than 3.5.
138 as the local interface address (on a multi-homed host) for sending the
139 trace query and as the default for the
141 and the response destination.
143 Loop indefinitely printing packet rate and loss statistics for the
144 multicast path every 10 seconds (see
145 .Fl S Ar stat_int ) .
147 Always request the response using multicast rather than attempting
148 unicast for the last half of the tries.
152 the maximum number of hops that will be traced from the
156 The default is 32 hops (infinity for the DVMRP routing protocol).
158 Print hop addresses numerically rather than symbolically and numerically
159 (saves a nameserver address-to-name lookup for each router found on the
162 Set the maximum number of query attempts for any hop to
166 Do not use the Router-Alert IP option on those requests which need it.
167 Some versions of Cisco's IOS cannot handle
168 multicast traceroutes with IP options, so it may be necessary to use the
170 flag if the last-hop router is a Cisco.
172 Listen passively for multicast responses from traces initiated by
173 others. This works best when run on a multicast router.
175 Loop indefinitely collecting the path every 10 seconds (see
177 and printing it when it changes. Do not print any statistics.
179 Send the trace response to
181 rather than to the host on which
183 is being run, or to a multicast address other than the one registered
184 for this purpose (224.0.1.32).
186 Print a short form output including only the multicast path and not
187 the packet rate and loss statistics.
189 Change the interval between statistics gathering traces to
191 seconds (default 10 seconds).
195 (time-to-live, or number of hops) for multicast trace queries and
196 responses. The default is 127, except for local queries to the "all
197 routers" multicast group which use ttl 1.
199 "Tunnel statistics" mode; show loss rates for overall traffic.
200 These statistics can be extremely misleading.
202 Always request the response using unicast rather than attempting
205 Verbose mode; show hop times on the initial trace and statistics display.
206 Also show the route that was used to forward the initial trace.
208 Set the time to wait for a trace response to
210 seconds (default 3 seconds).
214 The technique used by the
216 utility to trace unicast network paths will not work for IP multicast
217 because ICMP responses are specifically forbidden for multicast traffic.
218 Instead, a tracing feature has been built into the multicast routers.
219 This technique has the advantage that additional information about
220 packet rates and losses can be accumulated while the number of packets
224 reverse path forwarding, the trace is run backwards from the
228 A trace query packet is sent to the last
229 hop multicast router (the leaf router for the desired
231 address). The last hop router builds a trace response packet, fills in
232 a report for its hop, and forwards the trace packet using unicast to
233 the router it believes is the previous hop for packets originating
236 Each router along the path adds its report and forwards the packet.
237 When the trace response packet reaches the first hop router (the router
238 that is directly connected to the source's net), that router sends the
239 completed response to the response destination address specified in
242 If some multicast router along the path does not implement the
243 multicast traceroute feature or if there is some outage, then no
244 response will be returned. To solve this problem, the trace query
245 includes a maximum hop count field to limit the number of hops traced
246 before the response is returned. That allows a partial path to be
249 The reports inserted by each router contain not only the address of
250 the hop, but also the ttl required to forward and some flags to indicate
251 routing errors, plus counts of the total number of packets on the
252 incoming and outgoing interfaces and those forwarded for the specified
254 Taking differences in these counts for two traces separated in time
255 and comparing the output packet counts from one hop with the input
256 packet counts of the next hop allows the calculation of packet rate
257 and packet loss statistics for each hop to isolate congestion
259 .Ss Finding the Last-Hop Router
260 The trace query must be sent to the multicast router which is the
261 last hop on the path from the
265 If the receiver is on the local subnet (as determined using the subnet
266 mask), then the default method is to multicast the trace query to
267 all-routers.mcast.net (224.0.0.2) with a ttl of 1. Otherwise, the
268 trace query is multicast to the
270 address since the last hop router will be a member of that group if
271 the receiver is. Therefore it is necessary to specify a group that
272 the intended receiver has joined. This multicast is sent with a
273 default ttl of 127, which may not be sufficient for all cases (changed
277 If the last hop router is known, it may also be addressed directly
280 option). Alternatively, if it is desired to trace a group that the
281 receiver has not joined, but it is known that the last-hop router is a
282 member of another group, the
284 option may also be used to specify a different multicast address for the
287 When tracing from a multihomed host or router, the default receiver
288 address may not be the desired interface for the path from the source.
289 In that case, the desired interface should be specified explicitly as
292 .Ss Directing the Response
295 first attempts to trace the full reverse path, unless the number of
296 hops to trace is explicitly set with the
298 option. If there is no response within a 3 second timeout interval
301 option), a "*" is printed and the probing switches to hop-by-hop mode.
302 Trace queries are issued starting with a maximum hop count of one and
303 increasing by one until the full path is traced or no response is
304 received. At each hop, multiple probes are sent (default is three,
307 option). The first half of the attempts (default is two) are made with
308 the reply address set to standard multicast address, mtrace.mcast.net
309 (224.0.1.32) with the ttl set to 32 more than what's needed to pass the
310 thresholds seen so far along the path to the receiver. For each
311 additional attempt, the ttl is increased by another 32 each time up to
312 a maximum of 192. Since the desired router may not be able to send a
313 multicast reply, the remainder of the attempts request that the
314 response be sent via unicast to the host running
316 Alternatively, the multicast ttl may be set explicitly with the
318 option, the initial multicast attempts can be forced to use unicast
321 option, the final unicast attempts can be forced to use multicast
324 option, or if you specify
327 will first attempt using unicast and then multicast. For each attempt,
328 if no response is received within the timeout, a "*" is printed. After
329 the specified number of attempts have failed,
331 will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
332 request (as used by the
334 program) to see what kind of router it is.
337 utility will try to query three (changed with the
339 option) hops past a non-responding router, in the hopes that even
340 though it isn't capable of sending a response, it might be capable of
341 forwarding the request on.
345 is in two sections. The first section is a short listing of the hops
346 in the order they are queried, that is, in the reverse of the order
351 For each hop, a line is printed showing the hop number (counted
352 negatively to indicate that this is the reverse path); the multicast
353 routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to
354 forward data (to the previous hop in the listing as indicated by the
355 up-arrow character); and the cumulative delay for the query to reach
356 that hop (valid only if the clocks are synchronized). This first
357 section ends with a line showing the round-trip time which measures
358 the interval from when the query is issued until the response is
359 received, both derived from the local system clock, and the total
360 ttl required for a packet to travel along this path. A sample use and
364 oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu 224.2.0.3
365 Mtrace from 18.26.0.170 to 128.9.160.100 via group 224.2.0.3
366 Querying full reverse path...
367 0 oak.isi.edu (128.9.160.100)
368 -1 cub.isi.edu (128.9.160.153) DVMRP thresh^ 1 3 ms
369 -2 la.dart.net (140.173.128.1) DVMRP thresh^ 1 14 ms
370 -3 dc.dart.net (140.173.64.1) DVMRP thresh^ 1 50 ms
371 -4 bbn.dart.net (140.173.32.1) DVMRP thresh^ 1 63 ms
372 -5 mit.dart.net (140.173.48.2) DVMRP thresh^ 1 71 ms
373 -6 caraway.lcs.mit.edu (18.26.0.170)
374 Round trip time 124 ms; total ttl of 6 required.
377 If a hop reports that it is using the default route to forward packets,
380 is printed after that hop. If the
382 flag is supplied, the route being used to forward packets is printed
386 The second section provides a pictorial view of the path in the
387 forward direction with data flow indicated by arrows pointing downward
388 and the query path indicated by arrows pointing upward. For each hop,
389 both the entry and exit addresses of the router are shown if
390 different, along with the initial ttl required on the packet in order
391 to be forwarded at this hop and the propagation delay across the hop
392 assuming that the routers at both ends have synchronized clocks.
393 The right half of this section is composed of two sets of statistics.
394 The first column contains the average packet rate for all traffic at
396 The remaining columns are the
397 number of packets lost, the number of packets sent, the percentage
398 lost, and the average packet rate at each hop. These statistics are
399 calculated from differences between traces and from hop to hop as
400 explained above. The first group shows the statistics for all traffic
401 flowing out the interface at one hop and in the interface at the next
402 hop. The second group shows the statistics only for traffic forwarded
407 The first group of statistics may be expanded to include loss rates
410 option. However, these numbers can be extremely misleading and require
411 detailed knowledge of the routers involved to be interpreted properly.
413 These statistics are shown on one or two lines for each hop. Without
414 any options, this second section of the output is printed only once,
415 approximately 10 seconds after the initial trace. One line is shown
416 for each hop showing the statistics over that 10-second period. If
419 option is given, the second section is repeated every 10 seconds and
420 two lines are shown for each hop. The first line shows the statistics
421 for the last 10 seconds, and the second line shows the cumulative
422 statistics over the period since the initial trace, which is 101
423 seconds in the example below. The second section of the output is
426 option is set or if no multicast group is specified.
429 Waiting to accumulate statistics... Results after 101 seconds:
431 Source Response Dest Overall Packet Statistics For Traffic From
432 18.26.0.170 128.9.160.100 Packet 18.26.0.170 To 224.2.0.3
433 | __/ rtt 125 ms Rate Lost/Sent = Pct Rate
434 v / hop 65 ms ------- ---------------------
436 140.173.48.2 mit.dart.net
437 | ^ ttl 1 0 pps 0/2 = --% 0 pps
438 v | hop 8 ms 0 pps 0/18 = 0% 0 pps
440 140.173.32.1 bbn.dart.net
441 | ^ ttl 2 0 pps 0/2 = --% 0 pps
442 v | hop 12 ms 0 pps 0/18 = 0% 0 pps
444 140.173.64.1 dc.dart.net
445 | ^ ttl 3 27 pps 0/2 = --% 0 pps
446 v | hop 34 ms 26 pps 0/18 = 0% 0 pps
448 140.173.128.1 la.dart.net
449 | ^ ttl 4 83 pps 0/2 = --% 0 pps
450 v | hop 11 ms 79 pps 0/18 = 0% 0 pps
452 128.9.160.153 cub.isi.edu
453 | \\__ ttl 5 83 pps ?/2 0 pps
454 v \\ hop -8 ms 79 pps ?/18 0 pps
455 128.9.160.100 128.9.160.100
456 Receiver Query Source
459 Because the packet counts may be changing as the trace query is
460 propagating, there may be small errors (off by 1 or 2) in these
461 statistics. However, those errors should not accumulate, so the
462 cumulative statistics line should increase in accuracy as a new trace
463 is run every 10 seconds. There are two sources of larger errors, both
464 of which show up as negative losses:
466 If the input to a node is from a multi-access network with more than
467 one other node attached, then the input count will be (close to) the
468 sum of the output counts from all the attached nodes, but the output
469 count from the previous hop on the traced path will be only part of
470 that. Hence the output count minus the input count will be negative.
472 In release 3.3 of the DVMRP multicast forwarding software for SunOS
473 and other systems, a multicast packet generated on a router will be
474 counted as having come in an interface even though it did not. This
475 creates the negative loss that can be seen in the example above.
477 Note that these negative losses may mask positive losses.
479 In the example, there is also one negative hop time. This simply
480 indicates a lack of synchronization between the system clocks across
481 that hop. This example also illustrates how the percentage loss is
482 shown as two dashes when the number of packets sent is less than 10
483 because the percentage would not be statistically valid.
485 A second example shows a trace to a receiver that is not local; the
486 query is sent to the last-hop router with the
488 option. In this example, the trace of the full reverse path resulted
489 in no response because there was a node running an old version of
491 that did not implement the multicast traceroute function, so
493 switched to hop-by-hop mode. The
496 indicates that traffic for group 224.2.143.24 would not be forwarded.
499 oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \\
500 butter.lcs.mit.edu 224.2.143.24
501 Mtrace from 204.62.246.73 to 18.26.0.151 via group 224.2.143.24
502 Querying full reverse path... * switching to hop-by-hop:
503 0 butter.lcs.mit.edu (18.26.0.151)
504 -1 jam.lcs.mit.edu (18.26.0.144) DVMRP thresh^ 1 33 ms Output pruned
505 -2 bbn.dart.net (140.173.48.1) DVMRP thresh^ 1 36 ms
506 -3 dc.dart.net (140.173.32.2) DVMRP thresh^ 1 44 ms
507 -4 darpa.dart.net (140.173.240.2) DVMRP thresh^ 16 47 ms
508 -5 * * * noc.hpc.org (192.187.8.2) [mrouted 2.2] didn't respond
509 Round trip time 95 ms
515 based on an initial prototype written by
516 .An Ajit Thyagarajan .
517 The multicast traceroute mechanism was designed by
525 it was implemented in
531 The option syntax and the output format of
533 are modeled after the unicast
543 Statistics collection in passive mode doesn't always produce the same output
544 as when actively collecting data.