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
       receiver	to the source, collecting hop addresses,  packet  counts,  and
       routing	error  conditions  along  the  path,  and then the response is
       returned	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
       default 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
	       attempting 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
       incoming	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
       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
       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
       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 receiver.

   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 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	 (default is two) are made with	the reply address set to stan-
       dard 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  request 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 instead 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 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
       reverse 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
		 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.
	      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