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

FreeBSD Manual Pages


home | help
MTRACE(8)               FreeBSD 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.  The mtrace utility 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 parameters 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.

     The following options are available:

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

     -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 attempt-
             ing 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 (infin-
             ity 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 sta-

     -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 sec-
             onds (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 attempting
             multicast first.

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

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

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

     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 for-
     wards 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 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 incom-
     ing 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

   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 standard multicast address, ( with the ttl set to 32 more than what is
     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 instead
     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 num-
     ber 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.  The mtrace utility will try to query
     three (changed with the -e option) hops past a non-responding router, in
     the hopes that even though it is not 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 previ-
     ous 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 system
     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

     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 contains the aver-
     age packet rate for all traffic at each hop.  The remaining 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 cal-
     culated 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 sec-
     ond group shows the statistics only for traffic forwarded from the speci-
     fied source to the specified group.  The first group of statistics may be
     expanded to include loss rates using the -T option.  However, these num-
     bers 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, approxi-
     mately 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 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 propagat-
     ing, there may be small errors (off by 1 or 2) in these statistics.  How-
     ever, those errors should not accumulate, so the cumulative statistics
     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

     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 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 example, 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 implement the mul-
     ticast 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

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

     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.

     Statistics collection in passive mode does not always produce the same
     output as when actively collecting data.

FreeBSD 6.2                       May 8, 1995                      FreeBSD 6.2


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

home | help