mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-22 11:17:19 +00:00
590 lines
20 KiB
Groff
590 lines
20 KiB
Groff
.\" Copyright (c) 1995 by the University of Southern California
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software and its
|
|
.\" documentation in source and binary forms for non-commercial purposes
|
|
.\" and without fee is hereby granted, provided that the above copyright
|
|
.\" notice appear in all copies and that both the copyright notice and
|
|
.\" this permission notice appear in supporting documentation, and that
|
|
.\" any documentation, advertising materials, and other materials related
|
|
.\" to such distribution and use acknowledge that the software was
|
|
.\" developed by the University of Southern California, Information
|
|
.\" Sciences Institute. The name of the University may not be used to
|
|
.\" endorse or promote products derived from this software without
|
|
.\" specific prior written permission.
|
|
.\"
|
|
.\" THE UNIVERSITY OF SOUTHERN CALIFORNIA makes no representations about
|
|
.\" the suitability of this software for any purpose. THIS SOFTWARE IS
|
|
.\" PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
|
|
.\" INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 8, 1995
|
|
.Dt MTRACE 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm mtrace
|
|
.Nd print multicast path from a source to a receiver
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl e Ar extrahops
|
|
.Op Fl g Ar gateway
|
|
.Op Fl i Ar if_addr
|
|
.Op Fl l
|
|
.Op Fl M
|
|
.Op Fl m Ar max_hops
|
|
.Op Fl n
|
|
.Op Fl O
|
|
.Op Fl p
|
|
.Op Fl P
|
|
.Op Fl q Ar nqueries
|
|
.Op Fl r Ar resp_dest
|
|
.Op Fl s
|
|
.Op Fl S Ar stat_int
|
|
.Op Fl t Ar ttl
|
|
.Op Fl T
|
|
.Op Fl U
|
|
.Op Fl v
|
|
.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.
|
|
The
|
|
.Nm
|
|
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
|
|
.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 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 parameters can be distinguished because the
|
|
.Ar receiver
|
|
is a unicast address and the
|
|
.Ar group
|
|
is a multicast address.
|
|
If the
|
|
.Fl g
|
|
flag is specified, the source address defaults to the host running
|
|
.Nm ,
|
|
and the receiver defaults to the router being addressed with
|
|
the
|
|
.Fl g
|
|
flag.
|
|
In this case, there are no required parameters.
|
|
.Pp
|
|
NOTE: For Solaris 2.4/2.5, if the multicast interface is not the default
|
|
interface, the
|
|
.Fl i
|
|
option must be used to set the local address.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width indent
|
|
.It Fl e Ar extrahops
|
|
Try tracing
|
|
.Ar extrahops
|
|
hops past a non-responding router.
|
|
.It Fl g Ar gwy
|
|
Send the trace query via unicast directly to the multicast router
|
|
.Ar gwy
|
|
rather than multicasting the query.
|
|
This must be the last-hop router on the path from the intended
|
|
.Ar source
|
|
to the
|
|
.Ar receiver .
|
|
.Pp
|
|
.Em CAUTION ! !
|
|
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.
|
|
.It Fl i Ar addr
|
|
Use
|
|
.Ar 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 request the response using multicast rather than attempting
|
|
unicast for the last half of the tries.
|
|
.It Fl m Ar n
|
|
Set to
|
|
.Ar n
|
|
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 q Ar n
|
|
Set the maximum number of query attempts for any hop to
|
|
.Ar n .
|
|
The default is 3.
|
|
.It Fl 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
|
|
.Fl O
|
|
flag if the last-hop router is a Cisco.
|
|
.It Fl p
|
|
Listen passively for multicast responses from traces initiated by
|
|
others.
|
|
This works best when run on a multicast router.
|
|
.It Fl P
|
|
Loop indefinitely collecting the path every 10 seconds (see
|
|
.Fl S Ar stat_int )
|
|
and printing it when it changes.
|
|
Do not print any statistics.
|
|
.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
|
|
Print a short form output including only the multicast path and not
|
|
the packet rate and loss statistics.
|
|
.It Fl S Ar n
|
|
Change the interval between statistics gathering traces to
|
|
.Ar n
|
|
seconds (default 10 seconds).
|
|
.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 127, except for local queries to the "all
|
|
routers" multicast group which use ttl 1.
|
|
.It Fl T
|
|
"Tunnel statistics" mode; show loss rates for overall traffic.
|
|
These statistics can be extremely misleading.
|
|
.It Fl U
|
|
Always request the response using unicast rather than attempting
|
|
multicast first.
|
|
.It Fl v
|
|
Verbose mode; show hop times on the initial trace and statistics display.
|
|
Also show the route that was used to forward the initial trace.
|
|
.It Fl w Ar n
|
|
Set the time to wait for a trace response to
|
|
.Ar n
|
|
seconds (default 3 seconds).
|
|
.El
|
|
.Sh USAGE
|
|
.Ss "How It Works"
|
|
The technique used by the
|
|
.Nm traceroute
|
|
utility 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
|
|
.Ar source
|
|
to the
|
|
.Ar 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
|
|
.Ar 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
|
|
.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
|
|
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 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
|
|
.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 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
|
|
.Fl q
|
|
option).
|
|
The first half of the attempts (default 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 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
|
|
.Nm .
|
|
Alternatively, the multicast ttl may be set explicitly with the
|
|
.Fl t
|
|
option, the initial multicast attempts can be forced to use unicast
|
|
instead with the
|
|
.Fl U
|
|
option, the final unicast attempts can be forced to use multicast
|
|
instead with the
|
|
.Fl M
|
|
option, or if you specify
|
|
.Fl UM ,
|
|
.Nm
|
|
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,
|
|
.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.
|
|
The
|
|
.Nm
|
|
utility will try to query three (changed with the
|
|
.Fl 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.
|
|
.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
|
|
.Ar source
|
|
to the
|
|
.Ar 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, and the total
|
|
ttl required for a packet to travel along this path.
|
|
A sample use and
|
|
output might be:
|
|
.Pp
|
|
.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; total ttl of 6 required.
|
|
.Ed
|
|
.Pp
|
|
If a hop reports that it is using the default route to forward packets,
|
|
the word
|
|
.Em [default]
|
|
is printed after that hop.
|
|
If the
|
|
.Fl v
|
|
flag is supplied, the route being used to forward packets is printed
|
|
in the form
|
|
.Em [18.26.0/24] .
|
|
.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 two sets of statistics.
|
|
The first column contains the average 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
|
|
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 .
|
|
The first group of statistics may be expanded to include loss rates
|
|
using the
|
|
.Fl T
|
|
option.
|
|
However, these numbers can be extremely misleading and require
|
|
detailed knowledge of the routers involved to be interpreted properly.
|
|
.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 or if no multicast group is specified.
|
|
.Pp
|
|
.Bd -literal
|
|
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
|
|
.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:
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.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 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
|
|
.Dq Output pruned
|
|
error code
|
|
indicates that traffic for group 224.2.143.24 would not be forwarded.
|
|
.Pp
|
|
.Bd -literal
|
|
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
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr map-mbone 8 ,
|
|
.Xr mrinfo 8 ,
|
|
.Xr mrouted 8 ,
|
|
.Xr traceroute 8
|
|
.Sh AUTHORS
|
|
.An -nosplit
|
|
Implemented by
|
|
.An Steve Casner
|
|
based on an initial prototype written by
|
|
.An Ajit Thyagarajan .
|
|
The multicast traceroute mechanism was designed by
|
|
.An Van Jacobson
|
|
with help from
|
|
.An Steve Casner ,
|
|
.An Steve Deering ,
|
|
.An Dino Farinacci ,
|
|
and
|
|
.An Deb Agrawal ;
|
|
it was implemented in
|
|
.Nm mrouted
|
|
by
|
|
.An Ajit Thyagarajan
|
|
and
|
|
.An Bill Fenner .
|
|
The option syntax and the output format of
|
|
.Nm
|
|
are modeled after the unicast
|
|
.Nm traceroute
|
|
program written by
|
|
.An Van Jacobson .
|
|
.Sh BUGS
|
|
Statistics collection in passive mode does not always produce the same output
|
|
as when actively collecting data.
|