Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
MTRACE(8)		  BSD System Manager's Manual		     MTRACE(8)

     mtrace -- print multicast path from a source to a receiver

     mtrace [-e	extrahops] [-g gateway]	[-i if_addr] [-l] [-M] [-m max_hops]
	    [-n] [-O] [-p] [-P]	[-q nqueries] [-r resp_dest] [-s]
	    [-S	stat_int] [-t ttl] [-T]	[-U] [-v] [-w waittime]	source
	    [receiver] [group]

     Assessing problems	in the distribution of IP multicast traffic can	be
     difficult.	 The mtrace 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
     receiver to the source, collecting	hop addresses, packet counts, and
     routing error conditions along the	path, and then the response is re-
     turned to the requestor.

     The only required parameter is the	source host name or address.  The de-
     fault receiver is the host	running	mtrace,	and the	default	group is, 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 receiver	is a unicast address and the group is
     a multicast address.  If the -g flag is specified,	the source address de-
     faults to the host	running	mtrace,	and the	receiver defaults to the
     router being addressed with the -g	flag.  In this case, there are no re-
     quired parameters.

     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.

     The following options are available:

     -e	extrahops
	     Try tracing extrahops hops	past a non-responding router.

     -g	gwy  Send the trace query via unicast directly to the multicast	router
	     gwy rather	than multicasting the query.  This must	be the last-
	     hop router	on the path from the intended source to	the receiver.

	     CAUTION!!	Versions 3.3 and 3.5 of	mrouted	will crash if a	trace
	     query is received via a unicast packet and	mrouted	has no route
	     for the source address.  Therefore, do not	use the	-g option un-
	     less the target mrouted has been verified to be 3.4 or newer than

     -i	addr
	     Use addr as the local interface address (on a multi-homed host)
	     for sending the trace query and as	the default for	the receiver
	     and the response destination.

     -l	     Loop indefinitely printing	packet rate and	loss statistics	for
	     the multicast path	every 10 seconds (see -S stat_int).

     -M	     Always request the	response using multicast rather	than attempt-
	     ing unicast for the last half of the tries.

     -m	n    Set to n the maximum number of hops that will be traced from the
	     receiver back toward the source.  The default is 32 hops (infin-
	     ity for the DVMRP routing protocol).

     -n	     Print hop addresses numerically rather than symbolically and nu-
	     merically (saves a	nameserver address-to-name lookup for each
	     router found on the path).

     -q	n    Set the maximum number of query attempts for any hop to n.	 The
	     default is	3.

     -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.

     -p	     Listen passively for multicast responses from traces initiated by
	     others.  This works best when run on a multicast router.

     -P	     Loop indefinitely collecting the path every 10 seconds (see -S
	     stat_int) and printing it when it changes.	 Do not	print any sta-

     -r	host
	     Send the trace response to	host rather than to the	host on	which
	     mtrace is being run, or to	a multicast address other than the one
	     registered	for this purpose (

     -s	     Print a short form	output including only the multicast path and
	     not the packet rate and loss statistics.

     -S	n    Change the	interval between statistics gathering traces to	n sec-
	     onds (default 10 seconds).

     -t	ttl  Set the 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.

     -T	     "Tunnel statistics" mode; show loss rates for overall traffic.
	     These statistics can be extremely misleading.

     -U	     Always request the	response using unicast rather than attempting
	     multicast first.

     -v	     Verbose mode; show	hop times on the initial trace and statistics
	     display.  Also show the route that	was used to forward the	ini-
	     tial trace.

     -w	n    Set the time to wait for a	trace response to n seconds (default 3

   How It Works
     The technique used	by the traceroute utility to trace unicast network
     paths will	not work for IP	multicast because ICMP responses are specifi-
     cally 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 accumu-
     lated while the number of packets sent is minimized.

     Since multicast uses reverse path forwarding, the trace is	run backwards
     from the receiver to the source.  A trace query packet is sent to the
     last hop multicast	router (the leaf router	for the	desired	receiver ad-
     dress).  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 source.	Each router along the path adds	its report and for-
     wards 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.

     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 re-
     turned.  That allows a partial path to be traced.

     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 incom-
     ing and outgoing interfaces and those forwarded for the specified 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.

   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 source to	the 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
     ( with a	ttl of 1.  Otherwise, the trace	query is multicast to
     the 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 de-
     fault ttl of 127, which may not be	sufficient for all cases (changed with
     the -t option).  If the last hop router is	known, it may also be ad-
     dressed directly using the	-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 -g option may also
     be	used to	specify	a different multicast address for the trace query.

     When tracing from a multihomed host or router, the	default	receiver ad-
     dress may not be the desired interface for	the path from the source.  In
     that case,	the desired interface should be	specified explicitly as	the

   Directing the Response
     By	default, mtrace	first attempts to trace	the full reverse path, unless
     the number	of hops	to trace is explicitly set with	the -m option.	If
     there is no response within a 3 second timeout interval (changed with the
     -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 in-
     creasing 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 -q
     option).  The first half of the attempts (default is two) are made	with
     the reply address set to standard multicast address,
     ( 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 addi-
     tional attempt, the ttl is	increased by another 32	each time up to	a max-
     imum of 192.  Since the desired router may	not be able to send a multi-
     cast reply, the remainder of the attempts request that the	response be
     sent via unicast to the host running mtrace.  Alternatively, the multi-
     cast ttl may be set explicitly with the -t	option,	the initial multicast
     attempts can be forced to use unicast instead with	the -U option, the fi-
     nal unicast attempts can be forced	to use multicast instead with the -M
     option, or	if you specify -UM, 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, mtrace will try to query the next hop	router with a
     DVMRP_ASK_NEIGHBORS2 request (as used by the mrinfo program) to see what
     kind of router it is.  The	mtrace utility will try	to query three
     (changed with the -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.

     The output	of 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	re-
     verse of the order	from the source	to the 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 cumula-
     tive 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: 80# mtrace -l
     Mtrace from to via group
     Querying full reverse path...
       0 (
      -1 (  DVMRP  thresh^ 1	 3 ms
      -2 (  DVMRP  thresh^ 1	 14 ms
      -3 (  DVMRP  thresh^ 1	50 ms
      -4 (  DVMRP  thresh^ 1	 63 ms
      -5 (  DVMRP  thresh^ 1	 71 ms
      -6 (
     Round trip	time 124 ms; total ttl of 6 required.

     If	a hop reports that it is using the default route to forward packets,
     the word [default]	is printed after that hop.  If the -v flag is sup-
     plied, the	route being used to forward packets is printed in the form

     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	aver-
     age 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 cal-
     culated 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 sec-
     ond group shows the statistics only for traffic forwarded from the	speci-
     fied source to the	specified group.  The first group of statistics	may be
     expanded to include loss rates using the -T option.  However, these num-
     bers can be extremely misleading and require detailed knowledge of	the
     routers involved to be interpreted	properly.

     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, approxi-
     mately 10 seconds after the initial trace.	 One line is shown for each
     hop showing the statistics	over that 10-second period.  If	the -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 be-
     low.  The second section of the output is omitted if the -s option	is set
     or	if no multicast	group is specified.

     Waiting to	accumulate statistics... Results after 101 seconds:

       Source	    Response Dest    Overall   Packet Statistics For Traffic From    Packet To
	  |	  __/ rtt  125 ms     Rate     Lost/Sent = Pct	Rate
	  v	 /    hop   65 ms    -------   ---------------------
	  |	^     ttl    1	       0 pps	  0/2  = --%  0	pps
	  v	|     hop    8 ms      0 pps	  0/18 =  0%  0	pps
	  |	^     ttl    2	       0 pps	  0/2  = --%  0	pps
	  v	|     hop   12 ms      0 pps	  0/18 =  0%  0	pps
	  |	^     ttl    3	      27 pps	  0/2  = --%  0	pps
	  v	|     hop   34 ms     26 pps	  0/18 =  0%  0	pps
	  |	^     ttl    4	      83 pps	  0/2  = --%  0	pps
	  v	|     hop   11 ms     79 pps	  0/18 =  0%  0	pps
	  |	 \__  ttl    5	      83 pps	  ?/2	      0	pps
	  v	    \ hop   -8 ms     79 pps	  ?/18	      0	pps
       Receiver	    Query Source

     Because the packet	counts may be changing as the trace query is propagat-
     ing, there	may be small errors (off by 1 or 2) in these statistics.  How-
     ever, 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

     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.

     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.

     Note that these negative losses may mask positive losses.

     In	the example, there is also one negative	hop time.  This	simply indi-
     cates 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.

     A second example shows a trace to a receiver that is not local; the query
     is	sent to	the last-hop router with the -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 mrouted that did not implement the mul-
     ticast traceroute function, so mtrace switched to hop-by-hop mode.	 The
     "Output pruned" error code	indicates that traffic for group
     would not be forwarded. 108# mtrace -g \
     Mtrace from to via group
     Querying full reverse path... * switching to hop-by-hop:
       0 (
      -1 (	 DVMRP	thresh^	1  33 ms  Output pruned
      -2 (  DVMRP  thresh^ 1	 36 ms
      -3 (  DVMRP  thresh^ 1	44 ms
      -4 (  DVMRP	 thresh^ 16  47	ms
      -5  * * * ( [mrouted 2.2]	didn't respond
     Round trip	time 95	ms

     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	mrouted	by Ajit	Thyagarajan and	Bill
     Fenner.  The option syntax	and the	output format of mtrace	are modeled
     after the unicast traceroute program written by Van Jacobson.

     map-mbone(8), mrinfo(8), mrouted(8), traceroute(8)

     Statistics	collection in passive mode doesn't always produce the same
     output as when actively collecting	data.

BSD				  May 8, 1995				   BSD


Want to link to this manual page? Use this URL:

home | help