path: root/usr.sbin/mtrace/mtrace.8

.\"	$OpenBSD: mtrace.8,v 1.15 2007/05/31 19:20:26 jmc Exp $
.\"	$NetBSD: mtrace.8,v 1.4 1995/12/10 10:57:11 mycroft Exp $
.\"
.\" Copyright (c) 1993, 1998-2001.
.\" The University of Southern California/Information Sciences Institute.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" Other copyrights might apply to parts of this software and are so
.\" noted when applicable.
.\"
.\" This manual page (but not the software) was derived from the
.\" manual page for the traceroute program which bears the following
.\" copyright notice:
.\"
.\" Copyright (c) 1988 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" Van Jacobson.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 31 2007 $
.Dt MTRACE 8
.Os
.Sh NAME
.Nm mtrace
.Nd print multicast path from a source to a receiver
.Sh SYNOPSIS
.Nm mtrace
.Op Fl lMnpsv
.Op Fl g Ar gateway
.Op Fl i Ar if_addr
.Op Fl m Ar max_hops
.Op Fl q Ar nqueries
.Op Fl r Ar host
.Op Fl S Ar stat_int
.Op Fl t Ar ttl
.Op Fl w Ar waittime
.Ar source
.Op Ar receiver
.Op Ar group
.Sh DESCRIPTION
Assessing problems in the distribution of IP multicast traffic
can be difficult.
.Nm
utilizes a tracing feature implemented in multicast routers
.Pf ( Nm 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
.Ar receiver
to the
.Ar source ,
collecting hop addresses, packet counts, and routing error conditions
along the path, and then the response is returned to the requestor.
.Pp
The only required parameter is the
.Ar source
host name or address.
The default
.Ar receiver
is the host running mtrace, and the default
.Ar 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 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
.Ar receiver
is a unicast address and the
.Ar group
is a multicast address.
.Pp
The options are as follows:
.Bl -tag -width addr_xy
.It Fl g Ar gateway
Send the trace query via unicast directly to the multicast router
.Ar gateway
rather than multicasting the query.
This must be the last-hop router on the path from the intended
.Ar source
to the
.Ar receiver .
.Em NOTE: Read the BUGS section below.
.It Fl i Ar if_addr
Use
.Ar if_addr
as the local interface address (on a multi-homed host) for sending the
trace query and as the default for the
.Ar receiver
and the response destination.
.It Fl l
Loop indefinitely printing packet rate and loss statistics for the
multicast path every 10 seconds (see
.Fl S Ar stat_int ) .
.It Fl M
Always send the response using multicast rather than attempting
unicast first.
.It Fl m Ar max_hops
Set to
the maximum number of hops that will be traced from the
.Ar receiver
back toward the
.Ar source .
The default is 32 hops (infinity for the DVMRP routing protocol).
.It Fl n
Print hop addresses numerically rather than symbolically and numerically
(saves a nameserver address-to-name lookup for each router found on the
path).
.It Fl p
Listen passively for multicast responses from traces initiated by others.
This works best when run on a multicast router.
.It Fl q Ar nqueries
Set the maximum number of query attempts for any hop to
.Ar nqueries .
The default is 3.
.It Fl r Ar host
Send the trace response to
.Ar host
rather than to the host on which
.Nm
is being run, or to a multicast address other than the one registered
for this purpose (224.0.1.32).
.It Fl S Ar stat_int
Change the interval between statistics gathering traces to
.Ar stat_int
seconds (default 10 seconds).
.It Fl s
Print a short form output including only the multicast path and not
the packet rate and loss statistics.
.It Fl t Ar ttl
Set the
.Ar 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.
.It Fl v
Verbose mode; show hop times on the initial trace and statistics display.
.It Fl w Ar waittime
Set the time to wait for a trace response to
.Ar waittime
seconds (default 3 seconds).
.El
.Ss How \&It Works
The technique used by the
.Nm traceroute
tool to trace unicast network paths will not work for IP multicast
because ICMP responses are specifically 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 accumulated while the number of packets
sent is minimized.
.Pp
Since multicast uses
reverse path forwarding, the trace is run backwards from the
.Ar receiver
to the
.Ar source .
A trace query packet is sent to the last
hop multicast router (the leaf router for the desired
.Ar 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
.Ar 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.
.Pp
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.
.Pp
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
.Ar 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.
.Ss 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
.Ae source
to the
.Ar receiver .
If the
.Ar 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
.Ar group
address since the last hop router will be a member of that group if
the
.Ar receiver
is.
Therefore it is necessary to specify a
.Ar group
that the intended
.Ar receiver
is joined.
This multicast is sent with a default ttl of 64, which may not be sufficient
for all cases (changed with the
.Fl t
option).
If the last hop router is known, it may also be addressed directly
using the
.Fl g
option).
Alternatively, if it is desired to trace a group that the
.Ar receiver
has not joined, but it is known that the last-hop router is a
member of another group, the
.Fl g
option may also be used to specify a different multicast address for the
trace query.
.Pp
When tracing from a multihomed host or router, the default
.Ar receiver
address may not be the desired interface for the path from the
.Ar source .
In that case, the desired interface should be specified explicitly as
the
.Ar receiver .
.Ss Directing the Response
By default,
.Nm
first attempts to trace the full reverse path, unless the number of
hops to trace is explicitly set with the
.Fl m
option.
If there is no response within a 3 second timeout interval
(changed with the
.Fl m
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
.Fl q
option).
The first half of the attempts (default is one) are made with
the unicast address of the host running
.Nm
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
.Ar 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
.Fl t
option and/or the initial unicast attempts can be forced to use
multicast instead with the
.Fl m
option.
For each attempt, if no response is received within the timeout,
a "*" is printed.
After the specified number of attempts have failed,
.Nm
will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
request (as used by the
.Nm mrinfo
program) to see what kind of router it is.
.Sh EXAMPLES
The output of
.Nm
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
.Ae source
to the
.Ae 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 previous 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.
A sample use and output might be:
.Bd -literal
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
.Ed
.Pp
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 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 traffic forwarded
from the specified
.Ar source
to the specified
.Ar group .
.Pp
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
.Fl 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
.Fl s .
option is set.
.Bd -literal
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
.Ed
.Pp
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 seconds.
There are two sources of larger errors,
both of which show up as negative losses:
.Bl -bullet -offset abcd
.It
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.
.It
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.
.El
.Pp
Note that these negative losses may mask positive losses.
.Pp
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 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.
.Pp
A second example shows a trace to a
.Ar receiver
that is not local; the query is sent to the last-hop router with the
.Fl 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
.Nm mrouted
that did not implement the multicast traceroute function, so
.Nm
switched to hop-by-hop mode.
The "Route pruned" error code indicates that traffic for group 224.2.143.24
would not be forwarded.
.Bd -literal
oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \e
                           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
.Ed
.Sh SEE ALSO
.Xr map-mbone 8 ,
.Xr mrinfo 8 ,
.Xr mrouted 8 ,
.Xr traceroute 8
.Sh AUTHORS
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
.Nm mrouted
by Ajit Thyagarajan and Bill Fenner.
The option syntax and the output format of
.Nm
are modeled after the unicast
.Nm traceroute
program written by Van Jacobson.
.Sh BUGS
Versions 3.3 and 3.5 of
.Nm mrouted
will crash if a trace query is received via a
unicast packet and
.Nm mrouted
has no route for the
.Ar source
address.
Therefore, do not use the
.Fl g
option unless the target
.Nm mrouted
has been verified to be 3.4 or newer than 3.5.