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

FreeBSD Manual Pages


home | help
MTRACE(8)		    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.   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 re-
       ceiver 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
       default	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 parame-
       ters 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 defaults to the host running mtrace,  and	 the  receiver
       defaults	to the router being addressed with the -g flag.	 In this case,
       there are no required parameters.

       NOTE: For Solaris 2.4/2.5, if the multicast interface is	 not  the  de-
       fault interface,	the -i option must be used to set the local address.

       -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

	       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 unless the tar-
			   get mrouted has been	verified to be	3.4  or	 newer
			   than	3.5.

       -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  at-
	       tempting	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
	       (infinity for the DVMRP routing protocol).

       -n      Print  hop  addresses  numerically rather than symbolically and
	       numerically (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

       -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
	       seconds (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  attempt-
	       ing multicast first.

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

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

   How It Works
       The technique used by the traceroute  tool  to  trace  unicast  network
       paths will not work for IP multicast because ICMP responses are specif-
       ically forbidden	for multicast traffic.	Instead, a tracing feature has
       been  built  into the multicast routers.	 This technique	has the	advan-
       tage that additional information	about packet rates and losses  can  be
       accumulated while the number of packets sent is minimized.

       Since  multicast	 uses  reverse path forwarding,	the trace is run back-
       wards 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
       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  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.

       If  some	 multicast router along	the path does not implement the	multi-
       cast 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.

       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 in-
       coming 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  de-
       fault  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
       default 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
       addressed directly using	the -g option).	 Alternatively,	if it  is  de-
       sired  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 op-
       tion  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 receiver.

   Directing the Response
       By  default,  mtrace first attempts to trace the	full reverse path, un-
       less 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	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 -q option).  The first half of the attempts (de-
       fault 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 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  re-
       quest  that the response	be sent	via unicast to the host	running	mtrace
       .  Alternatively, the multicast ttl may be set explicitly with  the  -t
       option, the initial multicast attempts can be forced to use unicast in-
       stead with the -U option, the final unicast attempts can	be  forced  to
       use  multicast isntead 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.  mtrace 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 re-
       sponse, 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  pre-
       vious  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 sys-
       tem 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
       [18.26.0/24] .

       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 con-
       tains the average packet	rate for all traffic at	each hop.  The remain-
       ing 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	 traf-
       fic  forwarded  from  the specified source to the specified group.  The
       first group of statistics may be	expanded to include loss  rates	 using
       the  -T option.	However, these numbers can be extremely	misleading and
       require detailed	knowledge of the routers involved  to  be  interpreted

       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
       -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 sta-
       tistics 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 -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	propa-
       gating,	there may be small errors (off by 1 or 2) in these statistics.
       However,	those errors should not	accumulate, so the cumulative  statis-
       tics  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:

	      o	 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 at-
		 tached	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.
	      o	 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 exam-
       ple, 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	imple-
       ment the	multicast 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	 Fari-
       nacci, and Deb Agrawal; it was implemented in mrouted by	Ajit Thyagara-
       jan and Bill Fenner.  The option	syntax and the output format of	mtrace
       are  modeled after the unicast traceroute program written by Van	Jacob-

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

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

4.3 Berkeley Distribution	  May 8, 1995			     MTRACE(8)


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

home | help