Sweep-fix man page section order to match mdoc(7), part 5/5.
[dragonfly.git] / usr.sbin / mrouted / mtrace.8
1 .\" Copyright (c) 1995 by the University of Southern California
2 .\" All rights reserved.
3 .\"
4 .\" Permission to use, copy, modify, and distribute this software and its
5 .\" documentation in source and binary forms for non-commercial purposes
6 .\" and without fee is hereby granted, provided that the above copyright
7 .\" notice appear in all copies and that both the copyright notice and
8 .\" this permission notice appear in supporting documentation, and that
9 .\" any documentation, advertising materials, and other materials related
10 .\" to such distribution and use acknowledge that the software was
11 .\" developed by the University of Southern California, Information
12 .\" Sciences Institute.  The name of the University may not be used to
13 .\" endorse or promote products derived from this software without
14 .\" specific prior written permission.
15 .\"
16 .\" THE UNIVERSITY OF SOUTHERN CALIFORNIA makes no representations about
17 .\" the suitability of this software for any purpose.  THIS SOFTWARE IS
21 .\"
22 .\" Other copyrights might apply to parts of this software and are so
23 .\" noted when applicable.
24 .\"
25 .\" This manual page (but not the software) was derived from the
26 .\" manual page for the traceroute program which bears the following
27 .\" copyright notice:
28 .\"
29 .\" Copyright (c) 1988 The Regents of the University of California.
30 .\" All rights reserved.
31 .\"
32 .\" $FreeBSD: src/usr.sbin/mrouted/mtrace.8,v 2003/03/11 22:31:29 trhodes Exp $
33 .\" $DragonFly: src/usr.sbin/mrouted/mtrace.8,v 1.3 2006/02/17 19:40:18 swildner Exp $
34 .\"
35 .Dd May 8, 1995
36 .Dt MTRACE 8
37 .Os
38 .Sh NAME
39 .Nm mtrace
40 .Nd print multicast path from a source to a receiver
42 .Nm
43 .Op Fl e Ar extrahops
44 .Op Fl g Ar gateway
45 .Op Fl i Ar if_addr
46 .Op Fl l
47 .Op Fl M
48 .Op Fl m Ar max_hops
49 .Op Fl n
50 .Op Fl O
51 .Op Fl p
52 .Op Fl P
53 .Op Fl q Ar nqueries
54 .Op Fl r Ar resp_dest
55 .Op Fl s
56 .Op Fl S Ar stat_int
57 .Op Fl t Ar ttl
58 .Op Fl T
59 .Op Fl U
60 .Op Fl v
61 .Op Fl w Ar waittime
62 .Ar source
63 .Op Ar receiver
64 .Op Ar group
66 Assessing problems in the distribution of IP multicast traffic
67 can be difficult.
68 The
69 .Nm
70 utility utilizes a tracing feature implemented in multicast routers that is
71 accessed via an extension to the IGMP protocol.  A trace query is
72 passed hop-by-hop along the reverse path from the
73 .Ar receiver
74 to the
75 .Ar source ,
76 collecting hop addresses, packet counts, and routing error conditions
77 along the path, and then the response is returned to the requestor.
78 .Pp
79 The only required parameter is the
80 .Ar source
81 host name or address.  The default
82 .Ar receiver
83 is the host running mtrace, and the default
84 .Ar group
85 is, which is sufficient if packet loss
86 statistics for a particular multicast group are not needed.  These two
87 optional parameters may be specified to test the path to some other
88 receiver in a particular group, subject to some constraints as
89 detailed below.  The two parameters can be distinguished because the
90 .Ar receiver
91 is a unicast address and the
92 .Ar group
93 is a multicast address.
94 If the
95 .Fl g
96 flag is specified, the source address defaults to the host running
97 .Nm ,
98 and the receiver defaults to the router being addressed with
99 the
100 .Fl g
101 flag.  In this case, there are no required parameters.
102 .Pp
103 NOTE: For Solaris 2.4/2.5, if the multicast interface is not the default
104 interface, the
105 .Fl i
106 option must be used to set the local address.
107 .Pp
108 The following options are available:
109 .Bl -tag -width indent
110 .It Fl e Ar extrahops
111 Try tracing
112 .Ar extrahops
113 hops past a non-responding router.
114 .It Fl g Ar gwy
115 Send the trace query via unicast directly to the multicast router
116 .Ar gwy
117 rather than multicasting the query.
118 This must be the last-hop router on the path from the intended
119 .Ar source
120 to the
121 .Ar receiver .
122 .Pp
123 .Em CAUTION ! !
124 Versions 3.3 and 3.5 of
125 .Nm mrouted
126 will crash if a trace query is received via a
127 unicast packet and
128 .Nm mrouted
129 has no route for the
130 .Ar source
131 address.  Therefore, do not use the
132 .Fl g
133 option unless the target
134 .Nm mrouted
135 has been verified to be 3.4 or newer than 3.5.
136 .It Fl i Ar addr
137 Use
138 .Ar addr
139 as the local interface address (on a multi-homed host) for sending the
140 trace query and as the default for the
141 .Ar receiver
142 and the response destination.
143 .It Fl l
144 Loop indefinitely printing packet rate and loss statistics for the
145 multicast path every 10 seconds (see
146 .Fl S Ar stat_int ) .
147 .It Fl M
148 Always request the response using multicast rather than attempting
149 unicast for the last half of the tries.
150 .It Fl m Ar n
151 Set to
152 .Ar n
153 the maximum number of hops that will be traced from the
154 .Ar receiver
155 back toward the
156 .Ar source .
157 The default is 32 hops (infinity for the DVMRP routing protocol).
158 .It Fl n
159 Print hop addresses numerically rather than symbolically and numerically
160 (saves a nameserver address-to-name lookup for each router found on the
161 path).
162 .It Fl q Ar n
163 Set the maximum number of query attempts for any hop to
164 .Ar n .
165 The default is 3.
166 .It Fl O
167 Do not use the Router-Alert IP option on those requests which need it.
168 Some versions of Cisco's IOS cannot handle
169 multicast traceroutes with IP options, so it may be necessary to use the
170 .Fl O
171 flag if the last-hop router is a Cisco.
172 .It Fl p
173 Listen passively for multicast responses from traces initiated by
174 others.  This works best when run on a multicast router.
175 .It Fl P
176 Loop indefinitely collecting the path every 10 seconds (see
177 .Fl S Ar stat_int )
178 and printing it when it changes.  Do not print any statistics.
179 .It Fl r Ar host
180 Send the trace response to
181 .Ar host
182 rather than to the host on which
183 .Nm
184 is being run, or to a multicast address other than the one registered
185 for this purpose (
186 .It Fl s
187 Print a short form output including only the multicast path and not
188 the packet rate and loss statistics.
189 .It Fl S Ar n
190 Change the interval between statistics gathering traces to
191 .Ar n
192 seconds (default 10 seconds).
193 .It Fl t Ar ttl
194 Set the
195 .Ar ttl
196 (time-to-live, or number of hops) for multicast trace queries and
197 responses.  The default is 127, except for local queries to the "all
198 routers" multicast group which use ttl 1.
199 .It Fl T
200 "Tunnel statistics" mode; show loss rates for overall traffic.
201 These statistics can be extremely misleading.
202 .It Fl U
203 Always request the response using unicast rather than attempting
204 multicast first.
205 .It Fl v
206 Verbose mode; show hop times on the initial trace and statistics display.
207 Also show the route that was used to forward the initial trace.
208 .It Fl w Ar n
209 Set the time to wait for a trace response to
210 .Ar n
211 seconds (default 3 seconds).
212 .El
213 .Sh USAGE
214 .Ss "How It Works"
215 The technique used by the
216 .Nm traceroute
217 utility to trace unicast network paths will not work for IP multicast
218 because ICMP responses are specifically forbidden for multicast traffic.
219 Instead, a tracing feature has been built into the multicast routers.
220 This technique has the advantage that additional information about
221 packet rates and losses can be accumulated while the number of packets
222 sent is minimized.
223 .Pp
224 Since multicast uses
225 reverse path forwarding, the trace is run backwards from the
226 .Ar receiver
227 to the
228 .Ar source .
229 A trace query packet is sent to the last
230 hop multicast router (the leaf router for the desired
231 .Ar receiver
232 address).  The last hop router builds a trace response packet, fills in
233 a report for its hop, and forwards the trace packet using unicast to
234 the router it believes is the previous hop for packets originating
235 from the specified
236 .Ar source .
237 Each router along the path adds its report and forwards the packet.
238 When the trace response packet reaches the first hop router (the router
239 that is directly connected to the source's net), that router sends the
240 completed response to the response destination address specified in
241 the trace query.
242 .Pp
243 If some multicast router along the path does not implement the
244 multicast traceroute feature or if there is some outage, then no
245 response will be returned.  To solve this problem, the trace query
246 includes a maximum hop count field to limit the number of hops traced
247 before the response is returned.  That allows a partial path to be
248 traced.
249 .Pp
250 The reports inserted by each router contain not only the address of
251 the hop, but also the ttl required to forward and some flags to indicate
252 routing errors, plus counts of the total number of packets on the
253 incoming and outgoing interfaces and those forwarded for the specified
254 .Ar group .
255 Taking differences in these counts for two traces separated in time
256 and comparing the output packet counts from one hop with the input
257 packet counts of the next hop allows the calculation of packet rate
258 and packet loss statistics for each hop to isolate congestion
259 problems.
260 .Ss Finding the Last-Hop Router
261 The trace query must be sent to the multicast router which is the
262 last hop on the path from the
263 .Ar source
264 to the
265 .Ar receiver .
266 If the receiver is on the local subnet (as determined using the subnet
267 mask), then the default method is to multicast the trace query to
268 all-routers.mcast.net ( with a ttl of 1.  Otherwise, the
269 trace query is multicast to the
270 .Ar group
271 address since the last hop router will be a member of that group if
272 the receiver is.  Therefore it is necessary to specify a group that
273 the intended receiver has joined.  This multicast is sent with a
274 default ttl of 127, which may not be sufficient for all cases (changed
275 with the
276 .Fl t
277 option).
278 If the last hop router is known, it may also be addressed directly
279 using the
280 .Fl g
281 option).  Alternatively, if it is desired to trace a group that the
282 receiver has not joined, but it is known that the last-hop router is a
283 member of another group, the
284 .Fl g
285 option may also be used to specify a different multicast address for the
286 trace query.
287 .Pp
288 When tracing from a multihomed host or router, the default receiver
289 address may not be the desired interface for the path from the source.
290 In that case, the desired interface should be specified explicitly as
291 the
292 .Ar receiver .
293 .Ss Directing the Response
294 By default,
295 .Nm
296 first attempts to trace the full reverse path, unless the number of
297 hops to trace is explicitly set with the
298 .Fl m
299 option.  If there is no response within a 3 second timeout interval
300 (changed with the
301 .Fl w
302 option), a "*" is printed and the probing switches to hop-by-hop mode.
303 Trace queries are issued starting with a maximum hop count of one and
304 increasing by one until the full path is traced or no response is
305 received.  At each hop, multiple probes are sent (default is three,
306 changed with
307 .Fl q
308 option).  The first half of the attempts (default is two) are made with
309 the reply address set to standard multicast address, mtrace.mcast.net
310 ( with the ttl set to 32 more than what's needed to pass the
311 thresholds seen so far along the path to the receiver.  For each
312 additional attempt, the ttl is increased by another 32 each time up to
313 a maximum of 192.  Since the desired router may not be able to send a
314 multicast reply, the remainder of the attempts request that the
315 response be sent via unicast to the host running
316 .Nm .
317 Alternatively, the multicast ttl may be set explicitly with the
318 .Fl t
319 option, the initial multicast attempts can be forced to use unicast
320 instead with the
321 .Fl U
322 option, the final unicast attempts can be forced to use multicast
323 instead with the
324 .Fl M
325 option, or if you specify
326 .Fl UM ,
327 .Nm
328 will first attempt using unicast and then multicast.  For each attempt,
329 if no response is received within the timeout, a "*" is printed.  After
330 the specified number of attempts have failed,
331 .Nm
332 will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2
333 request (as used by the
334 .Nm mrinfo
335 program) to see what kind of router it is.
336 The
337 .Nm
338 utility will try to query three (changed with the
339 .Fl e
340 option) hops past a non-responding router, in the hopes that even
341 though it isn't capable of sending a response, it might be capable of
342 forwarding the request on.
344 The output of
345 .Nm
346 is in two sections.  The first section is a short listing of the hops
347 in the order they are queried, that is, in the reverse of the order
348 from the
349 .Ar source
350 to the
351 .Ar receiver .
352 For each hop, a line is printed showing the hop number (counted
353 negatively to indicate that this is the reverse path); the multicast
354 routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to
355 forward data (to the previous hop in the listing as indicated by the
356 up-arrow character); and the cumulative delay for the query to reach
357 that hop (valid only if the clocks are synchronized).  This first
358 section ends with a line showing the round-trip time which measures
359 the interval from when the query is issued until the response is
360 received, both derived from the local system clock, and the total
361 ttl required for a packet to travel along this path.  A sample use and
362 output might be:
363 .Pp
364 .Bd -literal
365 oak.isi.edu 80# mtrace -l caraway.lcs.mit.edu
366 Mtrace from to via group
367 Querying full reverse path...
368   0  oak.isi.edu (
369  -1  cub.isi.edu (  DVMRP  thresh^ 1  3 ms
370  -2  la.dart.net (  DVMRP  thresh^ 1  14 ms
371  -3  dc.dart.net (  DVMRP  thresh^ 1  50 ms
372  -4  bbn.dart.net (  DVMRP  thresh^ 1  63 ms
373  -5  mit.dart.net (  DVMRP  thresh^ 1  71 ms
374  -6  caraway.lcs.mit.edu (
375 Round trip time 124 ms; total ttl of 6 required.
376 .Ed
377 .Pp
378 If a hop reports that it is using the default route to forward packets,
379 the word
380 .Em [default]
381 is printed after that hop.  If the
382 .Fl v
383 flag is supplied, the route being used to forward packets is printed
384 in the form
385 .Em [18.26.0/24] .
386 .Pp
387 The second section provides a pictorial view of the path in the
388 forward direction with data flow indicated by arrows pointing downward
389 and the query path indicated by arrows pointing upward.  For each hop,
390 both the entry and exit addresses of the router are shown if
391 different, along with the initial ttl required on the packet in order
392 to be forwarded at this hop and the propagation delay across the hop
393 assuming that the routers at both ends have synchronized clocks.
394 The right half of this section is composed of two sets of statistics.
395 The first column contains the average packet rate for all traffic at
396 each hop.
397 The remaining columns are the
398 number of packets lost, the number of packets sent, the percentage
399 lost, and the average packet rate at each hop.  These statistics are
400 calculated from differences between traces and from hop to hop as
401 explained above.  The first group shows the statistics for all traffic
402 flowing out the interface at one hop and in the interface at the next
403 hop.  The second group shows the statistics only for traffic forwarded
404 from the specified
405 .Ar source
406 to the specified
407 .Ar group .
408 The first group of statistics may be expanded to include loss rates
409 using the
410 .Fl T
411 option.  However, these numbers can be extremely misleading and require
412 detailed knowledge of the routers involved to be interpreted properly.
413 .Pp
414 These statistics are shown on one or two lines for each hop.  Without
415 any options, this second section of the output is printed only once,
416 approximately 10 seconds after the initial trace.  One line is shown
417 for each hop showing the statistics over that 10-second period.  If
418 the
419 .Fl l
420 option is given, the second section is repeated every 10 seconds and
421 two lines are shown for each hop.  The first line shows the statistics
422 for the last 10 seconds, and the second line shows the cumulative
423 statistics over the period since the initial trace, which is 101
424 seconds in the example below.  The second section of the output is
425 omitted if the
426 .Fl s
427 option is set or if no multicast group is specified.
428 .Pp
429 .Bd -literal
430 Waiting to accumulate statistics... Results after 101 seconds:
432   Source       Response Dest    Overall   Packet Statistics For Traffic From
433    Packet To
434      |       __/ rtt  125 ms     Rate     Lost/Sent = Pct  Rate
435      v      /    hop   65 ms    -------   ---------------------
437   mit.dart.net
438      |     ^     ttl    1         0 pps      0/2  = --%  0 pps
439      v     |     hop    8 ms      0 pps      0/18 =  0%  0 pps
441   bbn.dart.net
442      |     ^     ttl    2         0 pps      0/2  = --%  0 pps
443      v     |     hop   12 ms      0 pps      0/18 =  0%  0 pps
445   dc.dart.net
446      |     ^     ttl    3        27 pps      0/2  = --%  0 pps
447      v     |     hop   34 ms     26 pps      0/18 =  0%  0 pps
449  la.dart.net
450      |     ^     ttl    4        83 pps      0/2  = --%  0 pps
451      v     |     hop   11 ms     79 pps      0/18 =  0%  0 pps
453  cub.isi.edu
454      |      \\__  ttl    5        83 pps      ?/2         0 pps
455      v         \\ hop   -8 ms     79 pps      ?/18        0 pps
457   Receiver     Query Source
458 .Ed
459 .Pp
460 Because the packet counts may be changing as the trace query is
461 propagating, there may be small errors (off by 1 or 2) in these
462 statistics.  However, those errors should not accumulate, so the
463 cumulative statistics line should increase in accuracy as a new trace
464 is run every 10 seconds.  There are two sources of larger errors, both
465 of which show up as negative losses:
466 .Pp
467 If the input to a node is from a multi-access network with more than
468 one other node attached, then the input count will be (close to) the
469 sum of the output counts from all the attached nodes, but the output
470 count from the previous hop on the traced path will be only part of
471 that.  Hence the output count minus the input count will be negative.
472 .Pp
473 In release 3.3 of the DVMRP multicast forwarding software for SunOS
474 and other systems, a multicast packet generated on a router will be
475 counted as having come in an interface even though it did not.  This
476 creates the negative loss that can be seen in the example above.
477 .Pp
478 Note that these negative losses may mask positive losses.
479 .Pp
480 In the example, there is also one negative hop time.  This simply
481 indicates a lack of synchronization between the system clocks across
482 that hop.  This example also illustrates how the percentage loss is
483 shown as two dashes when the number of packets sent is less than 10
484 because the percentage would not be statistically valid.
485 .Pp
486 A second example shows a trace to a receiver that is not local; the
487 query is sent to the last-hop router with the
488 .Fl g
489 option.  In this example, the trace of the full reverse path resulted
490 in no response because there was a node running an old version of
491 .Nm mrouted
492 that did not implement the multicast traceroute function, so
493 .Nm
494 switched to hop-by-hop mode.  The
495 .Dq Output pruned
496 error code
497 indicates that traffic for group would not be forwarded.
498 .Pp
499 .Bd -literal
500 oak.isi.edu 108# mtrace -g \\
501                            butter.lcs.mit.edu
502 Mtrace from to via group
503 Querying full reverse path... * switching to hop-by-hop:
504   0  butter.lcs.mit.edu (
505  -1  jam.lcs.mit.edu (  DVMRP  thresh^ 1  33 ms  Output pruned
506  -2  bbn.dart.net (  DVMRP  thresh^ 1  36 ms
507  -3  dc.dart.net (  DVMRP  thresh^ 1  44 ms
508  -4  darpa.dart.net (  DVMRP  thresh^ 16  47 ms
509  -5  * * * noc.hpc.org ( [mrouted 2.2] didn't respond
510 Round trip time 95 ms
511 .Ed
512 .Sh SEE ALSO
513 .Xr map-mbone 8 ,
514 .Xr mrinfo 8 ,
515 .Xr mrouted 8 ,
516 .Xr traceroute 8
518 .An -nosplit
519 Implemented by
520 .An Steve Casner
521 based on an initial prototype written by
522 .An Ajit Thyagarajan .
523 The multicast traceroute mechanism was designed by
524 .An Van Jacobson
525 with help from
526 .An Steve Casner ,
527 .An Steve Deering ,
528 .An Dino Farinacci ,
529 and
530 .An Deb Agrawal ;
531 it was implemented in
532 .Nm mrouted
533 by
534 .An Ajit Thyagarajan
535 and
536 .An Bill Fenner .
537 The option syntax and the output format of
538 .Nm
539 are modeled after the unicast
540 .Nm traceroute
541 program written by
542 .An Van Jacobson .
543 .Sh BUGS
544 Statistics collection in passive mode doesn't always produce the same output
545 as when actively collecting data.