diff options
Diffstat (limited to 'usr.sbin/mrouted/mtrace.8')
| -rw-r--r-- | usr.sbin/mrouted/mtrace.8 | 135 |
1 files changed, 90 insertions, 45 deletions
diff --git a/usr.sbin/mrouted/mtrace.8 b/usr.sbin/mrouted/mtrace.8 index 44d99d594ce4..6226aa111909 100644 --- a/usr.sbin/mrouted/mtrace.8 +++ b/usr.sbin/mrouted/mtrace.8 @@ -67,7 +67,8 @@ can be difficult. The .Nm utility utilizes a tracing feature implemented in multicast routers that is -accessed via an extension to the IGMP protocol. A trace query is +accessed via an extension to the IGMP protocol. +A trace query is passed hop-by-hop along the reverse path from the .Ar receiver to the @@ -77,15 +78,18 @@ along the path, and then the response is returned to the requestor. .Pp The only required parameter is the .Ar source -host name or address. The default +host name or address. +The default .Ar receiver is the host running mtrace, and the default .Ar group is 0.0.0.0, which is sufficient if packet loss -statistics for a particular multicast group are not needed. These two +statistics for a particular multicast group are not needed. +These two optional parameters may be specified to test the path to some other receiver in a particular group, subject to some constraints as -detailed below. The two parameters can be distinguished because the +detailed below. +The two parameters can be distinguished because the .Ar receiver is a unicast address and the .Ar group @@ -97,7 +101,8 @@ flag is specified, the source address defaults to the host running and the receiver defaults to the router being addressed with the .Fl g -flag. In this case, there are no required parameters. +flag. +In this case, there are no required parameters. .Pp NOTE: For Solaris 2.4/2.5, if the multicast interface is not the default interface, the @@ -127,7 +132,8 @@ unicast packet and .Nm mrouted has no route for the .Ar source -address. Therefore, do not use the +address. +Therefore, do not use the .Fl g option unless the target .Nm mrouted @@ -170,11 +176,13 @@ multicast traceroutes with IP options, so it may be necessary to use the flag if the last-hop router is a Cisco. .It Fl p Listen passively for multicast responses from traces initiated by -others. This works best when run on a multicast router. +others. +This works best when run on a multicast router. .It Fl P Loop indefinitely collecting the path every 10 seconds (see .Fl S Ar stat_int ) -and printing it when it changes. Do not print any statistics. +and printing it when it changes. +Do not print any statistics. .It Fl r Ar host Send the trace response to .Ar host @@ -193,7 +201,8 @@ seconds (default 10 seconds). Set the .Ar ttl (time-to-live, or number of hops) for multicast trace queries and -responses. The default is 127, except for local queries to the "all +responses. +The default is 127, except for local queries to the "all routers" multicast group which use ttl 1. .It Fl T "Tunnel statistics" mode; show loss rates for overall traffic. @@ -228,7 +237,8 @@ to the A trace query packet is sent to the last hop multicast router (the leaf router for the desired .Ar receiver -address). The last hop router builds a trace response packet, fills in +address). +The last hop router builds a trace response packet, fills in a report for its hop, and forwards the trace packet using unicast to the router it believes is the previous hop for packets originating from the specified @@ -241,9 +251,11 @@ the trace query. .Pp If some multicast router along the path does not implement the multicast traceroute feature or if there is some outage, then no -response will be returned. To solve this problem, the trace query +response will be returned. +To solve this problem, the trace query includes a maximum hop count field to limit the number of hops traced -before the response is returned. That allows a partial path to be +before the response is returned. +That allows a partial path to be traced. .Pp The reports inserted by each router contain not only the address of @@ -264,12 +276,15 @@ to the .Ar receiver . If the receiver is on the local subnet (as determined using the subnet mask), then the default method is to multicast the trace query to -all-routers.mcast.net (224.0.0.2) with a ttl of 1. Otherwise, the +all-routers.mcast.net (224.0.0.2) with a ttl of 1. +Otherwise, the trace query is multicast to the .Ar group address since the last hop router will be a member of that group if -the receiver is. Therefore it is necessary to specify a group that -the intended receiver has joined. This multicast is sent with a +the receiver is. +Therefore it is necessary to specify a group that +the intended receiver has joined. +This multicast is sent with a default ttl of 127, which may not be sufficient for all cases (changed with the .Fl t @@ -277,7 +292,8 @@ option). If the last hop router is known, it may also be addressed directly using the .Fl g -option). Alternatively, if it is desired to trace a group that the +option). +Alternatively, if it is desired to trace a group that the receiver has not joined, but it is known that the last-hop router is a member of another group, the .Fl g @@ -295,21 +311,26 @@ By default, first attempts to trace the full reverse path, unless the number of hops to trace is explicitly set with the .Fl m -option. If there is no response within a 3 second timeout interval +option. +If there is no response within a 3 second timeout interval (changed with the .Fl w option), a "*" is printed and the probing switches to hop-by-hop mode. Trace queries are issued starting with a maximum hop count of one and increasing by one until the full path is traced or no response is -received. At each hop, multiple probes are sent (default is three, +received. +At each hop, multiple probes are sent (default is three, changed with .Fl q -option). The first half of the attempts (default is two) are made with +option). +The first half of the attempts (default is two) are made with the reply address set to standard multicast address, mtrace.mcast.net (224.0.1.32) with the ttl set to 32 more than what's needed to pass the -thresholds seen so far along the path to the receiver. For each +thresholds seen so far along the path to the receiver. +For each additional attempt, the ttl is increased by another 32 each time up to -a maximum of 192. Since the desired router may not be able to send a +a maximum of 192. +Since the desired router may not be able to send a multicast reply, the remainder of the attempts request that the response be sent via unicast to the host running .Nm . @@ -324,8 +345,10 @@ instead with the option, or if you specify .Fl UM , .Nm -will first attempt using unicast and then multicast. For each attempt, -if no response is received within the timeout, a "*" is printed. After +will first attempt using unicast and then multicast. +For each attempt, +if no response is received within the timeout, a "*" is printed. +After the specified number of attempts have failed, .Nm will try to query the next hop router with a DVMRP_ASK_NEIGHBORS2 @@ -342,7 +365,8 @@ forwarding the request on. .Sh EXAMPLES The output of .Nm -is in two sections. The first section is a short listing of the hops +is in two sections. +The first section is a short listing of the hops in the order they are queried, that is, in the reverse of the order from the .Ar source @@ -353,11 +377,13 @@ negatively to indicate that this is the reverse path); the multicast routing protocol (DVMRP, MOSPF, PIM, etc.); the threshold required to forward data (to the previous hop in the listing as indicated by the up-arrow character); and the cumulative delay for the query to reach -that hop (valid only if the clocks are synchronized). This first +that hop (valid only if the clocks are synchronized). +This first section ends with a line showing the round-trip time which measures the interval from when the query is issued until the response is received, both derived from the local system clock, and the total -ttl required for a packet to travel along this path. A sample use and +ttl required for a packet to travel along this path. +A sample use and output might be: .Pp .Bd -literal @@ -377,7 +403,8 @@ Round trip time 124 ms; total ttl of 6 required. If a hop reports that it is using the default route to forward packets, the word .Em [default] -is printed after that hop. If the +is printed after that hop. +If the .Fl v flag is supplied, the route being used to forward packets is printed in the form @@ -385,7 +412,8 @@ in the form .Pp The second section provides a pictorial view of the path in the forward direction with data flow indicated by arrows pointing downward -and the query path indicated by arrows pointing upward. For each hop, +and the query path indicated by arrows pointing upward. +For each hop, both the entry and exit addresses of the router are shown if different, along with the initial ttl required on the packet in order to be forwarded at this hop and the propagation delay across the hop @@ -395,11 +423,14 @@ The first column contains the average packet rate for all traffic at each hop. The remaining columns are the number of packets lost, the number of packets sent, the percentage -lost, and the average packet rate at each hop. These statistics are +lost, and the average packet rate at each hop. +These statistics are calculated from differences between traces and from hop to hop as -explained above. The first group shows the statistics for all traffic +explained above. +The first group shows the statistics for all traffic flowing out the interface at one hop and in the interface at the next -hop. The second group shows the statistics only for traffic forwarded +hop. +The second group shows the statistics only for traffic forwarded from the specified .Ar source to the specified @@ -407,20 +438,26 @@ to the specified The first group of statistics may be expanded to include loss rates using the .Fl T -option. However, these numbers can be extremely misleading and require +option. +However, these numbers can be extremely misleading and require detailed knowledge of the routers involved to be interpreted properly. .Pp -These statistics are shown on one or two lines for each hop. Without +These statistics are shown on one or two lines for each hop. +Without any options, this second section of the output is printed only once, -approximately 10 seconds after the initial trace. One line is shown -for each hop showing the statistics over that 10-second period. If +approximately 10 seconds after the initial trace. +One line is shown +for each hop showing the statistics over that 10-second period. +If the .Fl l option is given, the second section is repeated every 10 seconds and -two lines are shown for each hop. The first line shows the statistics +two lines are shown for each hop. +The first line shows the statistics for the last 10 seconds, and the second line shows the cumulative statistics over the period since the initial trace, which is 101 -seconds in the example below. The second section of the output is +seconds in the example below. +The second section of the output is omitted if the .Fl s option is set or if no multicast group is specified. @@ -458,39 +495,47 @@ Waiting to accumulate statistics... Results after 101 seconds: .Pp Because the packet counts may be changing as the trace query is propagating, there may be small errors (off by 1 or 2) in these -statistics. However, those errors should not accumulate, so the +statistics. +However, those errors should not accumulate, so the cumulative statistics line should increase in accuracy as a new trace -is run every 10 seconds. There are two sources of larger errors, both +is run every 10 seconds. +There are two sources of larger errors, both of which show up as negative losses: .Pp If the input to a node is from a multi-access network with more than one other node attached, then the input count will be (close to) the sum of the output counts from all the attached nodes, but the output count from the previous hop on the traced path will be only part of -that. Hence the output count minus the input count will be negative. +that. +Hence the output count minus the input count will be negative. .Pp In release 3.3 of the DVMRP multicast forwarding software for SunOS and other systems, a multicast packet generated on a router will be -counted as having come in an interface even though it did not. This +counted as having come in an interface even though it did not. +This creates the negative loss that can be seen in the example above. .Pp Note that these negative losses may mask positive losses. .Pp -In the example, there is also one negative hop time. This simply +In the example, there is also one negative hop time. +This simply indicates a lack of synchronization between the system clocks across -that hop. This example also illustrates how the percentage loss is +that hop. +This example also illustrates how the percentage loss is shown as two dashes when the number of packets sent is less than 10 because the percentage would not be statistically valid. .Pp A second example shows a trace to a receiver that is not local; the query is sent to the last-hop router with the .Fl g -option. In this example, the trace of the full reverse path resulted +option. +In this example, the trace of the full reverse path resulted in no response because there was a node running an old version of .Nm mrouted that did not implement the multicast traceroute function, so .Nm -switched to hop-by-hop mode. The +switched to hop-by-hop mode. +The .Dq Output pruned error code indicates that traffic for group 224.2.143.24 would not be forwarded. |