mtrace.8

mtrace源码

.\" 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.
.\"
.\"	mtrace.8,v 5.2 1998/12/04 04:48:16 fenner Exp
.\"
.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 \-e
.I extrahops
] [
.B \-g
.I gateway
] [
.B \-i
.I if_addr
] [
.B \-l
] [
.B \-M
] [
.B \-m
.I max_hops
] [
.B \-n
] [
.B \-O
] [
.B \-p
] [
.B \-P
] [
.B \-q
.I nqueries
] [
.B \-r
.I resp_dest
] [
.B \-s
] [
.B \-S
.I stat_int
] [
.B \-t
.I ttl
] [
.B \-T
] [
.B \-U
] [
.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 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 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
.I receiver
is a unicast address and the
.I group
is a multicast address.
If the
.B \-g
flag is specified, the source address defaults to the host running
mtrace, and the receiver defaults to the router being addressed with
the
.B \-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 -i option must be used to set the local address.
.SH OPTIONS
.TP 8 8
.BI \-e\  extrahops
Try tracing
.I extrahops
hops past a non-responding router.
.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 request the response using multicast rather than attempting
unicast for the last half of the tries.
.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 \-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.
.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
.B \-P
Loop indefinitely collecting the path every 10 seconds (see
.B \-S
.IR stat_int )
and printing it when it changes.  Do not print any statistics.
.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 127, except for local queries to the "all
routers" multicast group which use ttl 1.
.TP 8 8
.B \-T
"Tunnel statistics" mode; show loss rates for overall traffic.
These statistics can be extremely misleading.
.TP 8 8
.B \-U
Always request the response using unicast rather than attempting
multicast first.
.TP 8 8
.B \-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.
.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