1.\" $OpenBSD: mtrace.8,v 1.12 2003/07/14 13:32:11 jmc Exp $ 2.\" $NetBSD: mtrace.8,v 1.4 1995/12/10 10:57:11 mycroft Exp $ 3.\" 4.\" Copyright (c) 1993, 1998-2001. 5.\" The University of Southern California/Information Sciences Institute. 6.\" All rights reserved. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. Neither the name of the project nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" Other copyrights might apply to parts of this software and are so 33.\" noted when applicable. 34.\" 35.\" This manual page (but not the software) was derived from the 36.\" manual page for the traceroute program which bears the following 37.\" copyright notice: 38.\" 39.\" Copyright (c) 1988 The Regents of the University of California. 40.\" All rights reserved. 41.\" 42.\" This code is derived from software contributed to Berkeley by 43.\" Van Jacobson. 44.\" 45.\" Redistribution and use in source and binary forms, with or without 46.\" modification, are permitted provided that the following conditions 47.\" are met: 48.\" 1. Redistributions of source code must retain the above copyright 49.\" notice, this list of conditions and the following disclaimer. 50.\" 2. Redistributions in binary form must reproduce the above copyright 51.\" notice, this list of conditions and the following disclaimer in the 52.\" documentation and/or other materials provided with the distribution. 53.\" 3. Neither the name of the University nor the names of its contributors 54.\" may be used to endorse or promote products derived from this software 55.\" without specific prior written permission. 56.\" 57.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 58.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 59.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 60.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 61.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 62.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 63.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 65.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 66.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 67.\" SUCH DAMAGE. 68.\" 69.Dd May 8, 1995 70.Dt MTRACE 8 71.Os 72.Sh NAME 73.Nm mtrace 74.Nd print multicast path from a source to a receiver 75.Sh SYNOPSIS 76.Nm mtrace 77.Bk -words 78.Op Fl g Ar gateway 79.Op Fl i Ar if_addr 80.Op Fl l 81.Op Fl M 82.Op Fl m Ar max_hops 83.Op Fl n 84.Op Fl p 85.Op Fl q Ar nqueries 86.Op Fl r Ar resp_dest 87.Op Fl s 88.Op Fl S Ar stat_int 89.Op Fl t Ar ttl 90.Op Fl v 91.Op Fl w Ar waittime 92.Ar source 93.Op Ar receiver 94.Op Ar group 95.Ek 96.Sh DESCRIPTION 97Assessing problems in the distribution of IP multicast traffic 98can be difficult. 99.Nm 100utilizes a tracing feature implemented in multicast routers 101.Pf ( Nm mrouted 102version 3.3 and later) that is 103accessed via an extension to the IGMP protocol. 104A trace query is passed hop-by-hop along the reverse path from the 105.Ar receiver 106to the 107.Ar source , 108collecting hop addresses, packet counts, and routing error conditions 109along the path, and then the response is returned to the requestor. 110.Pp 111The only required parameter is the 112.Ar source 113host name or address. 114The default 115.Ar receiver 116is the host running mtrace, and the default 117.Ar group 118is "MBone Audio" (224.2.0.1), which is sufficient if packet loss 119statistics for a particular multicast group are not needed. 120These two optional parameters may be specified to test the path to some other 121receiver in a particular group, subject to some constraints as 122detailed below. 123The two parameters can be distinguished because the 124.Ar receiver 125is a unicast address and the 126.Ar group 127is a multicast address. 128.Pp 129The options are as follows: 130.Bl -tag -width addr_xy 131.It Fl g Ar gwy 132Send the trace query via unicast directly to the multicast router 133.Ar gwy 134rather than multicasting the query. 135This must be the last-hop router on the path from the intended 136.Ar source 137to the 138.Ar receiver . 139.Em NOTE: Read the BUGS section below. 140.It Fl i Ar addr 141Use 142.Ar addr 143as the local interface address (on a multi-homed host) for sending the 144trace query and as the default for the 145.Ar receiver 146and the response destination. 147.It Fl l 148Loop indefinitely printing packet rate and loss statistics for the 149multicast path every 10 seconds (see 150.Fl S Ar stat_int ) . 151.It Fl M 152Always send the response using multicast rather than attempting 153unicast first. 154.It Fl m Ar n 155Set to 156.Ar n 157the maximum number of hops that will be traced from the 158.Ar receiver 159back toward the 160.Ar source . 161The default is 32 hops (infinity for the DVMRP routing protocol). 162.It Fl n 163Print hop addresses numerically rather than symbolically and numerically 164(saves a nameserver address-to-name lookup for each router found on the 165path). 166.It Fl q Ar n 167Set the maximum number of query attempts for any hop to 168.Ar n . 169The default is 3. 170.It Fl p 171Listen passively for multicast responses from traces initiated by others. 172This works best when run on a multicast router. 173.It Fl r Ar host 174Send the trace response to 175.Ar host 176rather than to the host on which 177.Nm 178is being run, or to a multicast address other than the one registered 179for this purpose (224.0.1.32). 180.It Fl s 181Print a short form output including only the multicast path and not 182the packet rate and loss statistics. 183.It Fl S Ar n 184Change the interval between statistics gathering traces to 185.Ar n 186seconds (default 10 seconds). 187.It Fl t Ar ttl 188Set the 189.Ar ttl 190(time-to-live, or number of hops) for multicast trace queries and 191responses. 192The default is 64, except for local queries to the 193"all routers" multicast group which use ttl 1. 194.It Fl v 195Verbose mode; show hop times on the initial trace and statistics display. 196.It Fl w Ar n 197Set the time to wait for a trace response to 198.Ar n 199seconds (default 3 seconds). 200.El 201.Ss How \&It Works 202The technique used by the 203.Nm traceroute 204tool to trace unicast network paths will not work for IP multicast 205because ICMP responses are specifically forbidden for multicast traffic. 206Instead, a tracing feature has been built into the multicast routers. 207This technique has the advantage that additional information about 208packet rates and losses can be accumulated while the number of packets 209sent is minimized. 210.Pp 211Since multicast uses 212reverse path forwarding, the trace is run backwards from the 213.Ar receiver 214to the 215.Ar source . 216A trace query packet is sent to the last 217hop multicast router (the leaf router for the desired 218.Ar receiver 219address). 220The last hop router builds a trace response packet, fills in 221a report for its hop, and forwards the trace packet using unicast to 222the router it believes is the previous hop for packets originating 223from the specified 224.Ar source . 225Each router along the path adds its report and forwards the packet. 226When the trace response packet reaches the first hop router (the router 227that is directly connected to the source's net), that router sends the 228completed response to the response destination address specified in 229the trace query. 230.Pp 231If some multicast router along the path does not implement the 232multicast traceroute feature or if there is some outage, then no 233response will be returned. 234To solve this problem, the trace query includes a maximum hop count field 235to limit the number of hops traced before the response is returned. 236That allows a partial path to be traced. 237.Pp 238The reports inserted by each router contain not only the address of 239the hop, but also the ttl required to forward and some flags to indicate 240routing errors, plus counts of the total number of packets on the 241incoming and outgoing interfaces and those forwarded for the specified 242.Ar group . 243Taking differences in these counts for two traces separated in time 244and comparing the output packet counts from one hop with the input 245packet counts of the next hop allows the calculation of packet rate 246and packet loss statistics for each hop to isolate congestion 247problems. 248.Ss Finding the Last-Hop Router 249The trace query must be sent to the multicast router which is the 250last hop on the path from the 251.Ae source 252to the 253.Ar receiver . 254If the 255.Ar receiver 256is on the local subnet (as determined using the subnet 257mask), then the default method is to multicast the trace query to 258all-routers.mcast.net (224.0.0.2) with a ttl of 1. 259Otherwise, the trace query is multicast to the 260.Ar group 261address since the last hop router will be a member of that group if 262the 263.Ar receiver 264is. 265Therefore it is necessary to specify a 266.Ar group 267that the intended 268.Ar receiver 269is joined. 270This multicast is sent with a default ttl of 64, which may not be sufficient 271for all cases (changed with the 272.Fl t 273option). 274If the last hop router is known, it may also be addressed directly 275using the 276.Fl g 277option). 278Alternatively, if it is desired to trace a group that the 279.Ar receiver 280has not joined, but it is known that the last-hop router is a 281member of another group, the 282.Fl g 283option may also be used to specify a different multicast address for the 284trace query. 285.Pp 286When tracing from a multihomed host or router, the default 287.Ar receiver 288address may not be the desired interface for the path from the 289.Ar source . 290In that case, the desired interface should be specified explicitly as 291the 292.Ar receiver . 293.Ss Directing the Response 294By default, 295.Nm 296first attempts to trace the full reverse path, unless the number of 297hops to trace is explicitly set with the 298.Fl m 299option. 300If there is no response within a 3 second timeout interval 301(changed with the 302.Fl m 303option), a "*" is printed and the probing switches to hop-by-hop mode. 304Trace queries are issued starting with a maximum hop count of one and 305increasing by one until the full path is traced or no response is 306received. 307At each hop, multiple probes are sent (default is three, changed with 308.Fl q 309option). 310The first half of the attempts (default is one) are made with 311the unicast address of the host running 312.Nm 313as the destination for the response. 314Since the unicast route may be blocked, the remainder of attempts request 315that the response be multicast to mtrace.mcast.net (224.0.1.32) with the 316ttl set to 32 more than what's needed to pass the thresholds seen so far 317along the path to the 318.Ar receiver . 319For the last quarter of the attempts (default is 320one), the ttl is increased by another 32 each time up to a maximum of 192. 321Alternatively, the ttl may be set explicitly with the 322.Fl t 323option and/or the initial unicast attempts can be forced to use 324multicast instead with the 325.Fl m 326option. 327For each attempt, if no response is received within the timeout, 328a "*" is printed. 329After the specified number of attempts have failed, 330.Nm 331will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2 332request (as used by the 333.Nm mrinfo 334program) to see what kind of router it is. 335.Sh EXAMPLES 336The output of 337.Nm 338is in two sections. 339The first section is a short listing of the hops in the order they are 340queried, that is, in the reverse of the order from the 341.Ae source 342to the 343.Ae receiver . 344For each hop, a line is printed showing the hop number (counted 345negatively to indicate that this is the reverse path); the multicast 346routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to 347forward data (to the previous hop in the listing as indicated by the 348up-arrow character); and the cumulative delay for the query to reach 349that hop (valid only if the clocks are synchronized). 350This first section ends with a line showing the round-trip time which measures 351the interval from when the query is issued until the response is 352received, both derived from the local system clock. 353A sample use and output might be: 354.Bd -literal 355oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu 224.2.0.3 356Mtrace from 18.26.0.170 to 128.9.160.100 via group 224.2.0.3 357Querying full reverse path... 358 0 oak.isi.edu (128.9.160.100) 359 -1 cub.isi.edu (128.9.160.153) DVMRP thresh^ 1 3 ms 360 -2 la.dart.net (140.173.128.1) DVMRP thresh^ 1 14 ms 361 -3 dc.dart.net (140.173.64.1) DVMRP thresh^ 1 50 ms 362 -4 bbn.dart.net (140.173.32.1) DVMRP thresh^ 1 63 ms 363 -5 mit.dart.net (140.173.48.2) DVMRP thresh^ 1 71 ms 364 -6 caraway.lcs.mit.edu (18.26.0.170) 365Round trip time 124 ms 366.Ed 367.Pp 368The second section provides a pictorial view of the path in the 369forward direction with data flow indicated by arrows pointing downward 370and the query path indicated by arrows pointing upward. 371For each hop, both the entry and exit addresses of the router are shown if 372different, along with the initial ttl required on the packet in order 373to be forwarded at this hop and the propagation delay across the hop 374assuming that the routers at both ends have synchronized clocks. 375The right half of this section is composed of several columns of 376statistics in two groups. 377Within each group, the columns are the number of packets lost, the number 378of packets sent, the percentage lost, and the average packet rate at each hop. 379These statistics are calculated from differences between traces and from 380hop to hop as explained above. 381The first group shows the statistics for all traffic flowing out the interface 382at one hop and in the interface at the next hop. 383The second group shows the statistics only for traffic forwarded 384from the specified 385.Ar source 386to the specified 387.Ar group . 388.Pp 389These statistics are shown on one or two lines for each hop. 390Without any options, this second section of the output is printed only once, 391approximately 10 seconds after the initial trace. 392One line is shown for each hop showing the statistics over that 10-second 393period. 394If the 395.Fl l 396option is given, the second section is repeated every 10 seconds and 397two lines are shown for each hop. 398The first line shows the statistics for the last 10 seconds, and the second 399line shows the cumulative statistics over the period since the initial trace, 400which is 101 seconds in the example below. 401The second section of the output is omitted if the 402.Fl s . 403option is set. 404.Bd -literal 405Waiting to accumulate statistics... Results after 101 seconds: 406 407 Source Response Dest Packet Statistics For Only For Traffic 40818.26.0.170 128.9.160.100 All Multicast Traffic From 18.26.0.170 409 | __/ rtt 125 ms Lost/Sent = Pct Rate To 224.2.0.3 410 v / hop 65 ms --------------------- ------------------ 41118.26.0.144 412140.173.48.2 mit.dart.net 413 | ^ ttl 1 0/6 = --% 0 pps 0/2 = --% 0 pps 414 v | hop 8 ms 1/52 = 2% 0 pps 0/18 = 0% 0 pps 415140.173.48.1 416140.173.32.1 bbn.dart.net 417 | ^ ttl 2 0/6 = --% 0 pps 0/2 = --% 0 pps 418 v | hop 12 ms 1/52 = 2% 0 pps 0/18 = 0% 0 pps 419140.173.32.2 420140.173.64.1 dc.dart.net 421 | ^ ttl 3 0/271 = 0% 27 pps 0/2 = --% 0 pps 422 v | hop 34 ms -1/2652 = 0% 26 pps 0/18 = 0% 0 pps 423140.173.64.2 424140.173.128.1 la.dart.net 425 | ^ ttl 4 -2/831 = 0% 83 pps 0/2 = --% 0 pps 426 v | hop 11 ms -3/8072 = 0% 79 pps 0/18 = 0% 0 pps 427140.173.128.2 428128.9.160.153 cub.isi.edu 429 | \\__ ttl 5 833 83 pps 2 0 pps 430 v \\ hop -8 ms 8075 79 pps 18 0 pps 431128.9.160.100 128.9.160.100 432 Receiver Query Source 433.Ed 434.Pp 435Because the packet counts may be changing as the trace query is 436propagating, there may be small errors (off by 1 or 2) in these 437statistics. 438However, those errors should not accumulate, so the cumulative statistics 439line should increase in accuracy as a new trace is run every 10 seconds. 440There are two sources of larger errors, 441both of which show up as negative losses: 442.Bl -bullet -offset abcd 443.It 444If the input to a node is from a multi-access network with more than 445one other node attached, then the input count will be (close to) the 446sum of the output counts from all the attached nodes, but the output 447count from the previous hop on the traced path will be only part of 448that. 449Hence the output count minus the input count will be negative. 450.It 451In release 3.3 of the DVMRP multicast forwarding software for SunOS 452and other systems, a multicast packet generated on a router will be 453counted as having come in an interface even though it did not. 454This creates the negative loss that can be seen in the example above. 455.El 456.Pp 457Note that these negative losses may mask positive losses. 458.Pp 459In the example, there is also one negative hop time. 460This simply indicates a lack of synchronization between the system clocks 461across that hop. 462This example also illustrates how the percentage loss is 463shown as two dashes when the number of packets sent is less than 10 464because the percentage would not be statistically valid. 465.Pp 466A second example shows a trace to a 467.Ar receiver 468that is not local; the query is sent to the last-hop router with the 469.Fl g 470option. 471In this example, the trace of the full reverse path resulted 472in no response because there was a node running an old version of 473.Nm mrouted 474that did not implement the multicast traceroute function, so 475.Nm 476switched to hop-by-hop mode. 477The "Route pruned" error code indicates that traffic for group 224.2.143.24 478would not be forwarded. 479.Bd -literal 480oak.isi.edu 108# mtrace -g 140.173.48.2 204.62.246.73 \e 481 butter.lcs.mit.edu 224.2.143.24 482Mtrace from 204.62.246.73 to 18.26.0.151 via group 224.2.143.24 483Querying full reverse path... * switching to hop-by-hop: 484 0 butter.lcs.mit.edu (18.26.0.151) 485 -1 jam.lcs.mit.edu (18.26.0.144) DVMRP thresh^ 1 33 ms Route pruned 486 -2 bbn.dart.net (140.173.48.1) DVMRP thresh^ 1 36 ms 487 -3 dc.dart.net (140.173.32.2) DVMRP thresh^ 1 44 ms 488 -4 darpa.dart.net (140.173.240.2) DVMRP thresh^ 16 47 ms 489 -5 * * * noc.hpc.org (192.187.8.2) [mrouted 2.2] didn't respond 490Round trip time 95 ms 491.Ed 492.Sh SEE ALSO 493.Xr map-mbone 8 , 494.Xr mrinfo 8 , 495.Xr mrouted 8 , 496.Xr traceroute 8 497.Sh AUTHORS 498Implemented by Steve Casner based on an initial prototype written by 499Ajit Thyagarajan. 500The multicast traceroute mechanism was designed by 501Van Jacobson with help from Steve Casner, Steve Deering, Dino 502Farinacci, and Deb Agrawal; it was implemented in 503.Nm mrouted 504by Ajit Thyagarajan and Bill Fenner. 505The option syntax and the output format of 506.Nm 507are modeled after the unicast 508.Nm traceroute 509program written by Van Jacobson. 510.Sh BUGS 511Versions 3.3 and 3.5 of 512.Nm mrouted 513will crash if a trace query is received via a 514unicast packet and 515.Nm mrouted 516has no route for the 517.Ar source 518address. 519Therefore, do not use the 520.Fl g 521option unless the target 522.Nm mrouted 523has been verified to be 3.4 or newer than 3.5. 524