MTRACE(8)                                               MTRACE(8)


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



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

DESCRIPTION
       Assessing problems in the  distribution  of  IP  multicast
       traffic  can be difficult.  mtrace utilizes a tracing fea-
       ture implemented in multicast routers (mrouted version 3.3
       and  later)  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 "MBone Audio" (224.2.0.1),  which
       is  sufficient  if packet loss statistics for a particular
       multicast group are not needed.  These two optional param-
       eters  may  be  specified  to  test the path to some other
       receiver in a  particular  group,  subject  to  some  con-
       straints  as  detailed  below.   The two parameters can be
       distinguished because the receiver is  a  unicast  address
       and the group is a multicast address.

       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.

OPTIONS
       -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.  There-
                           fore, do not use the -g option  unless
                           the  target  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.




                           May 8, 1995                          1





MTRACE(8)                                               MTRACE(8)


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

       -M      Always  send  the  response using multicast rather
               than attempting unicast first.

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

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

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

       -s      Print a short form output including only the  mul-
               ticast  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  64,  except  for local queries to the
               "all routers" multicast group which use ttl 1.

       -v      Verbose mode; show hop times on the initial  trace
               and statistics display.

       -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 specifically forbidden for  multicast  traf-
       fic.   Instead,  a tracing feature has been built into the
       multicast routers.  This technique has the advantage  that



                           May 8, 1995                          2





MTRACE(8)                                               MTRACE(8)


       additional  information  about packet rates and losses can
       be accumulated while the number of packets sent  is  mini-
       mized.

       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 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  multicast traceroute feature or if there is some out-
       age, 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 sepa-
       rated 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 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 64, 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



                           May 8, 1995                          3





MTRACE(8)                                               MTRACE(8)


       that the last-hop router is a member of another group, the
       -g  option  may also be used to specify a different multi-
       cast 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 one) are made with the unicast address of the
       host running mtrace as the destination for  the  response.
       Since  the  unicast route may be blocked, the remainder of
       attempts  request  that  the  response  be  multicast   to
       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 the last quarter of
       the attempts (default is one), the  ttl  is  increased  by
       another  32  each  time  up to a maximum of 192.  Alterna-
       tively, the ttl may be set explicity with  the  -t  option
       and/or  the  initial unicast attempts can be forced to use
       multicast instead with the -M option.  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 pro-
       gram) to see what kind of router it is.

EXAMPLES
       The  output  of mtrace is in two sections.  The first sec-
       tion 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 pro-
       tocol (DVMRP, MOSPF, PIM, etc.); the threshold required to
       forward data (to the previous hop in the listing as  indi-
       cated 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  system  clock.   A
       sample use and output might be:



                           May 8, 1995                          4





MTRACE(8)                                               MTRACE(8)


       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

       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  synchro-
       nized  clocks.  The right half of this section is composed
       of several columns of statistics in  two  groups.   Within
       each  group,  the  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 statis-
       tics 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 traffic forwarded  from  the
       specified source to the specified group.

       These  statistics  are  shown on one or two lines for each
       hop.  Without any options, this second section of the out-
       put  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  statistics  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.

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

         Source       Response Dest  Packet Statistics For  Only For Traffic
       18.26.0.170    128.9.160.100  All Multicast Traffic  From 18.26.0.170
            |       __/ rtt  125 ms  Lost/Sent = Pct  Rate    To 224.2.0.3
            v      /    hop   65 ms  ---------------------  ------------------
       18.26.0.144
       140.173.48.2   mit.dart.net
            |     ^     ttl    1      0/6    = --%   0 pps   0/2  = --%  0 pps



                           May 8, 1995                          5





MTRACE(8)                                               MTRACE(8)


            v     |     hop    8 ms   1/52   =  2%   0 pps   0/18 =  0%  0 pps
       140.173.48.1
       140.173.32.1   bbn.dart.net
            |     ^     ttl    2      0/6    = --%   0 pps   0/2  = --%  0 pps
            v     |     hop   12 ms   1/52   =  2%   0 pps   0/18 =  0%  0 pps
       140.173.32.2
       140.173.64.1   dc.dart.net
            |     ^     ttl    3      0/271  =  0%  27 pps   0/2  = --%  0 pps
            v     |     hop   34 ms  -1/2652 =  0%  26 pps   0/18 =  0%  0 pps
       140.173.64.2
       140.173.128.1  la.dart.net
            |     ^     ttl    4     -2/831  =  0%  83 pps   0/2  = --%  0 pps
            v     |     hop   11 ms  -3/8072 =  0%  79 pps   0/18 =  0%  0 pps
       140.173.128.2
       128.9.160.153  cub.isi.edu
            |      \__  ttl    5        833         83 pps     2         0 pps
            v         \ hop   -8 ms     8075        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 propagating, there may be small errors (off by 1
       or 2) in these statistics.  However, those  errors  should
       not  accumulate,  so the cumulative statistics line should
       increase in accuracy as a new trace is run every  10  sec-
       onds.   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 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  multi-
                 cast  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 indicates a lack  of  synchronization  between  the
       system  clocks  across that hop.  This example also illus-
       trates 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



                           May 8, 1995                          6





MTRACE(8)                                               MTRACE(8)


       -g option.  In this example, the trace of the full reverse
       path resulted in no response because there was a node run-
       ning an old version of mrouted that did not implement  the
       multicast  traceroute function, so mtrace switched to hop-
       by-hop mode.  The "Route 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  Route 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  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.

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


























                           May 8, 1995                          7