embedaddon/mrouted/mtrace.8 - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / mrouted / mtrace.8
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Feb 21 23:10:48 2012 UTC (12 years, 3 months ago) by misho
Branches: mrouted, MAIN
CVS tags: v3_9_6p0, v3_9_6, v3_9_5, HEAD

mrouted

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