unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-2.0)
Page:
Section:
Apropos / Subsearch:
optional field

MTRACE(8)                   System Manager's Manual                  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 uses a  tracing  feature  implemented  in  multicast
       routers  (mrouted version 3.3 and later) that is accessed via an exten-
       sion 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 statis-
       tics 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.

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

       -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 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  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  statis-
               tics 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 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 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 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 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.  Alternatively, the ttl may be set explicitly with  the
       -t option and/or the initial unicast attempts can be forced to use mul-
       ticast 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 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.  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

       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 several columns of  statistics  in  two  groups.
       Within each group, the columns are the number of packets lost, the num-
       ber 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  statis-
       tics only for traffic forwarded from the specified source to the speci-
       fied group.

       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.

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



4.3 Berkeley Distribution         May 8, 1995                        MTRACE(8)