.\" 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 NAMEmtrace \- 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 DESCRIPTIONAssessing problems in the distribution of IP multicast trafficcan be difficult..B mtraceutilizes a tracing feature implemented in multicast routers that isaccessed via an extension to the IGMP protocol.  A trace query ispassed hop-by-hop along the reverse path from the.I receiverto the.IR source ,collecting hop addresses, packet counts, and routing error conditionsalong the path, and then the response is returned to the requestor..PPThe only required parameter is the.I sourcehost name or address.  The default.I receiveris the host running mtrace, and the default.I groupis 0.0.0.0, which is sufficient if packet lossstatistics for a particular multicast group are not needed.  These twooptional parameters may be specified to test the path to some otherreceiver in a particular group, subject to some constraints asdetailed below.  The two parameters can be distinguished because the.I receiveris a unicast address and the.I groupis a multicast address.If the.B \-gflag is specified, the source address defaults to the host runningmtrace, and the receiver defaults to the router being addressed withthe.B \-gflag.  In this case, there are no required parameters..PPNOTE: For Solaris 2.4/2.5, if the multicast interface is not the defaultinterface, the -i option must be used to set the local address..SH OPTIONS.TP 8 8.BI \-e\  extrahopsTry tracing.I extrahopshops past a non-responding router..TP 8 8.BI \-g\  gwySend the trace query via unicast directly to the multicast router.I gwyrather than multicasting the query.This must be the last-hop router on the path from the intended.I sourceto the.IR receiver ..RS 8.TP 12 12.I CAUTION!!Versions 3.3 and 3.5 of.B mroutedwill crash if a trace query is received via aunicast packet and.B mroutedhas no route for the.I sourceaddress.  Therefore, do not use the.B \-goption unless the target.B mroutedhas been verified to be 3.4 or newer than 3.5..RE.TP 8 8.BI \-i\  addrUse.I addras the local interface address (on a multi-homed host) for sending thetrace query and as the default for the.I receiverand the response destination..TP 8 8.B \-lLoop indefinitely printing packet rate and loss statistics for themulticast path every 10 seconds (see .B \-S.IR stat_int )..TP 8 8.B \-MAlways request the response using multicast rather than attemptingunicast for the last half of the tries..TP 8 8.BI \-m\  nSet to.I nthe maximum number of hops that will be traced from the.I receiverback toward the.IR source .The default is 32 hops (infinity for the DVMRP routing protocol)..TP 8 8.B \-nPrint hop addresses numerically rather than symbolically and numerically(saves a nameserver address-to-name lookup for each router found on thepath)..TP 8 8.BI \-q\  nSet the maximum number of query attempts for any hop to.IR n .The default is 3..TP 8 8.B \-ODo not use the Router-Alert IP option on those requests which need it.Some versions of Cisco's IOS cannot handlemulticast 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 \-pListen passively for multicast responses from traces initiated byothers.  This works best when run on a multicast router..TP 8 8.B \-PLoop 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\  hostSend the trace response to.I hostrather than to the host on which.B mtraceis being run, or to a multicast address other than the one registeredfor this purpose (224.0.1.32)..TP 8 8.B \-sPrint a short form output including only the multicast path and notthe packet rate and loss statistics..TP 8 8.BI \-S\  nChange the interval between statistics gathering traces to.I nseconds (default 10 seconds)..TP 8 8.BI \-t\  ttlSet the.I ttl(time-to-live, or number of hops) for multicast trace queries andresponses.  The default is 127, except for local queries to the "allrouters" 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 \-UAlways request the response using unicast rather than attemptingmulticast first..TP 8 8.B \-vVerbose 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\  nSet the time to wait for a trace response to.I nseconds (default 3 seconds)..SH USAGE.SS How It WorksThe technique used by the.B traceroutetool to trace unicast network paths will not work for IP multicastbecause 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 aboutpacket rates and losses can be accumulated while the number of packetssent is minimized..PPSince multicast usesreverse path forwarding, the trace is run backwards from the.I receiverto the.IR source .A trace query packet is sent to the lasthop multicast router (the leaf router for the desired.I receiveraddress).  The last hop router builds a trace response packet, fills ina report for its hop, and forwards the trace packet using unicast tothe router it believes is the previous hop for packets originatingfrom 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 routerthat is directly connected to the source's net), that router sends thecompleted response to the response destination address specified inthe trace query..PPIf some multicast router along the path does not implement themulticast traceroute feature or if there is some outage, then noresponse will be returned.  To solve this problem, the trace queryincludes a maximum hop count field to limit the number of hops tracedbefore the response is returned.  That allows a partial path to betraced..PPThe reports inserted by each router contain not only the address ofthe hop, but also the ttl required to forward and some flags to indicaterouting errors, plus counts of the total number of packets on the