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