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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
       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 ]

DESCRIPTION
       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
       0.0.0.0,	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.

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

       -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 (224.0.1.32).

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

USAGE
   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	 all-routers.mcast.net
       (224.0.0.2)  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,	mtrace.mcast.net (224.0.1.32) 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.

EXAMPLES
       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:

       oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu 224.2.0.3
       Mtrace from 18.26.0.170 to 128.9.160.100	via group 224.2.0.3
       Querying	full reverse path...
	 0  oak.isi.edu	(128.9.160.100)
	-1  cub.isi.edu	(128.9.160.153)	 DVMRP	thresh^	1  3 ms
	-2  la.dart.net	(140.173.128.1)	 DVMRP	thresh^	1  14 ms
	-3  dc.dart.net	(140.173.64.1)	DVMRP  thresh^ 1  50 ms
	-4  bbn.dart.net (140.173.32.1)	 DVMRP	thresh^	1  63 ms
	-5  mit.dart.net (140.173.48.2)	 DVMRP	thresh^	1  71 ms
	-6  caraway.lcs.mit.edu	(18.26.0.170)
       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
       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,
       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
       18.26.0.170    128.9.160.100    Packet	 18.26.0.170 To	224.2.0.3
	    |	    __/	rtt  125 ms	Rate	 Lost/Sent = Pct  Rate
	    v	   /	hop   65 ms    -------	 ---------------------
       18.26.0.144
       140.173.48.2   mit.dart.net
	    |	  ^	ttl    1	 0 pps	    0/2	 = --%	0 pps
	    v	  |	hop    8 ms	 0 pps	    0/18 =  0%	0 pps
       140.173.48.1
       140.173.32.1   bbn.dart.net
	    |	  ^	ttl    2	 0 pps	    0/2	 = --%	0 pps
	    v	  |	hop   12 ms	 0 pps	    0/18 =  0%	0 pps
       140.173.32.2
       140.173.64.1   dc.dart.net
	    |	  ^	ttl    3	27 pps	    0/2	 = --%	0 pps
	    v	  |	hop   34 ms	26 pps	    0/18 =  0%	0 pps
       140.173.64.2
       140.173.128.1  la.dart.net
	    |	  ^	ttl    4	83 pps	    0/2	 = --%	0 pps
	    v	  |	hop   11 ms	79 pps	    0/18 =  0%	0 pps
       140.173.128.2
       128.9.160.153  cub.isi.edu
	    |	   \__	ttl    5	83 pps	    ?/2		0 pps
	    v	      \	hop   -8 ms	79 pps	    ?/18	0 pps
       128.9.160.100  128.9.160.100
	 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:

	      	 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.
	      	 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 224.2.143.24 would	not be forwarded.

       oak.isi.edu 108#	mtrace -g 140.173.48.2 204.62.246.73 \
				  butter.lcs.mit.edu 224.2.143.24
       Mtrace from 204.62.246.73 to 18.26.0.151	via group 224.2.143.24
       Querying	full reverse path... * switching to hop-by-hop:
	 0  butter.lcs.mit.edu (18.26.0.151)
	-1  jam.lcs.mit.edu (18.26.0.144)  DVMRP  thresh^ 1  33	ms  Output pruned
	-2  bbn.dart.net (140.173.48.1)	 DVMRP	thresh^	1  36 ms
	-3  dc.dart.net	(140.173.32.2)	DVMRP  thresh^ 1  44 ms
	-4  darpa.dart.net (140.173.240.2)  DVMRP  thresh^ 16  47 ms
	-5  * *	* noc.hpc.org (192.187.8.2) [mrouted 2.2] didn't respond
       Round trip time 95 ms

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

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

BUGS
       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:
<https://man.freebsd.org/cgi/man.cgi?query=mtrace&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>

home | help