517 lines
18 KiB
Groff
517 lines
18 KiB
Groff
.\" $NetBSD: mtrace.8,v 1.6 2002/01/19 11:44:57 wiz Exp $
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.TH MTRACE 8 "May 8, 1995"
|
|
.UC 6
|
|
.SH NAME
|
|
mtrace \- print multicast path from a source to a receiver
|
|
.SH SYNOPSIS
|
|
.B mtrace
|
|
[
|
|
.B \-g
|
|
.I gateway
|
|
] [
|
|
.B \-i
|
|
.I if_addr
|
|
] [
|
|
.B \-l
|
|
] [
|
|
.B \-M
|
|
] [
|
|
.B \-m
|
|
.I max_hops
|
|
] [
|
|
.B \-n
|
|
] [
|
|
.B \-p
|
|
] [
|
|
.B \-q
|
|
.I nqueries
|
|
] [
|
|
.B \-r
|
|
.I resp_dest
|
|
] [
|
|
.B \-s
|
|
] [
|
|
.B \-S
|
|
.I stat_int
|
|
] [
|
|
.B \-t
|
|
.I ttl
|
|
] [
|
|
.B \-v
|
|
] [
|
|
.B \-w
|
|
.I waittime
|
|
]
|
|
.I source
|
|
[
|
|
.I receiver
|
|
] [
|
|
.I group
|
|
]
|
|
.SH DESCRIPTION
|
|
Assessing problems in the distribution of IP multicast traffic
|
|
can be difficult.
|
|
.B mtrace
|
|
utilizes a tracing feature implemented in multicast routers
|
|
.RB ( 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
|
|
.I receiver
|
|
to the
|
|
.IR 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
|
|
.I source
|
|
host name or address. The default
|
|
.I receiver
|
|
is the host running mtrace, and the default
|
|
.I 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
|
|
.I receiver
|
|
is a unicast address and the
|
|
.I group
|
|
is a multicast address.
|
|
.PP
|
|
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.
|
|
.SH OPTIONS
|
|
.TP 8 8
|
|
.BI \-g\ gwy
|
|
Send the trace query via unicast directly to the multicast router
|
|
.I gwy
|
|
rather than multicasting the query.
|
|
This must be the last-hop router on the path from the intended
|
|
.I source
|
|
to the
|
|
.IR receiver .
|
|
.RS 8
|
|
.TP 12 12
|
|
.I CAUTION!!
|
|
Versions 3.3 and 3.5 of
|
|
.B mrouted
|
|
will crash if a trace query is received via a
|
|
unicast packet and
|
|
.B mrouted
|
|
has no route for the
|
|
.I source
|
|
address. Therefore, do not use the
|
|
.B \-g
|
|
option unless the target
|
|
.B mrouted
|
|
has been verified to be 3.4 or newer than 3.5.
|
|
.RE
|
|
.TP 8 8
|
|
.BI \-i\ addr
|
|
Use
|
|
.I addr
|
|
as the local interface address (on a multi-homed host) for sending the
|
|
trace query and as the default for the
|
|
.I receiver
|
|
and the response destination.
|
|
.TP 8 8
|
|
.B \-l
|
|
Loop indefinitely printing packet rate and loss statistics for the
|
|
multicast path every 10 seconds (see
|
|
.B \-S
|
|
.IR stat_int ).
|
|
.TP 8 8
|
|
.B \-M
|
|
Always send the response using multicast rather than attempting
|
|
unicast first.
|
|
.TP 8 8
|
|
.BI \-m\ n
|
|
Set to
|
|
.I n
|
|
the maximum number of hops that will be traced from the
|
|
.I receiver
|
|
back toward the
|
|
.IR source .
|
|
The default is 32 hops (infinity for the DVMRP routing protocol).
|
|
.TP 8 8
|
|
.B \-n
|
|
Print hop addresses numerically rather than symbolically and numerically
|
|
(saves a nameserver address-to-name lookup for each router found on the
|
|
path).
|
|
.TP 8 8
|
|
.BI \-q\ n
|
|
Set the maximum number of query attempts for any hop to
|
|
.IR n .
|
|
The default is 3.
|
|
.TP 8 8
|
|
.B \-p
|
|
Listen passively for multicast responses from traces initiated by
|
|
others. This works best when run on a multicast router.
|
|
.TP 8 8
|
|
.BI \-r\ host
|
|
Send the trace response to
|
|
.I host
|
|
rather than to the host on which
|
|
.B mtrace
|
|
is being run, or to a multicast address other than the one registered
|
|
for this purpose (224.0.1.32).
|
|
.TP 8 8
|
|
.B \-s
|
|
Print a short form output including only the multicast path and not
|
|
the packet rate and loss statistics.
|
|
.TP 8 8
|
|
.BI \-S\ n
|
|
Change the interval between statistics gathering traces to
|
|
.I n
|
|
seconds (default 10 seconds).
|
|
.TP 8 8
|
|
.BI \-t\ ttl
|
|
Set the
|
|
.I 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.
|
|
.TP 8 8
|
|
.B \-v
|
|
Verbose mode; show hop times on the initial trace and statistics display.
|
|
.TP 8 8
|
|
.BI \-w\ n
|
|
Set the time to wait for a trace response to
|
|
.I n
|
|
seconds (default 3 seconds).
|
|
.SH USAGE
|
|
.SS How It Works
|
|
The technique used by the
|
|
.B 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
|
|
.I receiver
|
|
to the
|
|
.IR source .
|
|
A trace query packet is sent to the last
|
|
hop multicast router (the leaf router for the desired
|
|
.I 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
|
|
.IR 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
|
|
.IR 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
|
|
.I source
|
|
to the
|
|
.IR 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
|
|
.I 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
|
|
.B \-t
|
|
option).
|
|
If the last hop router is known, it may also be addressed directly
|
|
using the
|
|
.B \-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
|
|
.B \-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
|
|
.IR receiver .
|
|
.SS Directing the Response
|
|
By default,
|
|
.B mtrace
|
|
first attempts to trace the full reverse path, unless the number of
|
|
hops to trace is explicitly set with the
|
|
.B \-m
|
|
option. If there is no response within a 3 second timeout interval
|
|
(changed with the
|
|
.B \-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
|
|
.B \-q
|
|
option). The first half of the attempts (default is one) are made with
|
|
the unicast address of the host running
|
|
.B 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
|
|
.B \-t
|
|
option and/or the initial unicast attempts can be forced to use
|
|
multicast instead with the
|
|
.B \-M
|
|
option. For each attempt, if no response is received within the
|
|
timeout, a "*" is printed. After the specified number of attempts
|
|
have failed,
|
|
.B mtrace
|
|
will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
|
|
request (as used by the
|
|
.B mrinfo
|
|
program) to see what kind of router it is.
|
|
.SH EXAMPLES
|
|
The output of
|
|
.B 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
|
|
.I source
|
|
to the
|
|
.IR 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:
|
|
.PP
|
|
.nf
|
|
.ft C
|
|
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
|
|
.fi
|
|
.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
|
|
.I source
|
|
to the specified
|
|
.IR 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
|
|
.B \-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
|
|
.B \-s
|
|
option is set.
|
|
.ie t \{\
|
|
.ft C
|
|
. ie \w'i'<>\w'm' \{\" looks like this is not proper Courier font
|
|
(If this example is not properly columned with a fixed-width font, get
|
|
.B groff
|
|
and try again.)
|
|
. \}
|
|
.\}
|
|
.PP
|
|
.ft C
|
|
.nf
|
|
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
|
|
.fi
|
|
.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:
|
|
.LP
|
|
.RS
|
|
.PD 0
|
|
.TP 3
|
|
\(bu
|
|
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.
|
|
.TP 3
|
|
\(bu
|
|
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.
|
|
.PD
|
|
.RE
|
|
.LP
|
|
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
|
|
.B \-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
|
|
.B mrouted
|
|
that did not implement the multicast traceroute function, so
|
|
.B mtrace
|
|
switched to hop-by-hop mode. The \*(lqRoute pruned\*(rq error code
|
|
indicates that traffic for group 224.2.143.24 would not be forwarded.
|
|
.PP
|
|
.nf
|
|
.ft C
|
|
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
|
|
.fi
|
|
.SH 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
|
|
.B mrouted
|
|
by Ajit Thyagarajan and Bill Fenner. The option syntax and the output
|
|
format of
|
|
.B mtrace
|
|
are modeled after the unicast
|
|
.B traceroute
|
|
program written by Van Jacobson.
|
|
.SH SEE ALSO
|
|
.BR mrouted (8) ,
|
|
.BR mrinfo (8) ,
|
|
.BR map-mbone (8) ,
|
|
.BR traceroute (8)
|