Using the Traceroute MIB

A traceroute test approximates the path packets take from the local host to the remote host.

RFC 2925 is the authoritative description of the Traceroute MIB in detail and provides the ASN.1 MIB definition of the Traceroute MIB. This section provides the following information:

• Starting a Traceroute Test
• Monitoring a Running Traceroute Test
• Monitoring Traceroute Test Completion
• Gathering Traceroute Test Results
• Stopping a Traceroute Test
• Traceroute Variables

Starting a Traceroute Test

Before you start a traceroute test, configure a Traceroute MIB view. This allows SNMP Set requests on tracerouteMIB. To start a test, create a row in traceRouteCtlTable and set traceRouteCtlAdminStatus to enabled. You must specify at least the following before setting traceRouteCtlAdminStatus to enabled:

• traceRouteCtlOwnerIndexSnmpAdminString
• traceRouteCtlTestNameSnmpAdminString
• traceRouteCtlTargetAddressInetAddress
• traceRouteCtlRowStatusRowStatus

For all other values, defaults are chosen unless otherwise specified. traceRouteCtlOwnerIndex and traceRouteCtlTestName are used as the index, so their values are specified as part of the OID. To create a row, set traceRouteCtlRowStatus to createAndWait or createAndGo on a row that does not already exist. A value of active for traceRouteCtlRowStatus indicates that all necessary information has been specified and the test can begin; traceRouteCtlAdminStatus can be set to enabled. An SNMP Set request that sets traceRouteCtlRowStatus to active will fail if the necessary information in the row is not specified or is inconsistent. For information about how to configure a view, see SNMP Remote Operations Overview.

There are two ways to start a traceroute test:

• Using Multiple Set PDUs
• Using a Single Set PDU

Using Multiple Set PDUs

You can use multiple Set request PDUs (multiple PDUs, with one or more varbinds each) and set the following variables in this order to start the test:

• traceRouteCtlRowStatus to createAndWait
• All appropriate test variables
• traceRouteCtlRowStatus to active

  JUNOS Software now verifies that all necessary information to run a test has been specified.

• traceRouteCtlAdminStatus to enabled

Using a Single Set PDU

You can use a single Set request PDU (one PDU, with multiple varbinds) to set the following variables to start the test:

• traceRouteCtlRowStatus to createAndGo
• All appropriate test variables
• traceRouteCtlAdminStatus to enabled

Monitoring a Running Traceroute Test

When traceRouteCtlAdminStatus is successfully set to enabled, the following is done before the acknowledgment of the SNMP Set request is sent back to the client:

• traceRouteResultsEntry is created if it does not already exist.
• traceRouteResultsOperStatus transitions to enabled.

For more information, see the following sections:

• traceRouteResultsTable
• traceRouteProbeResultsTable
• traceRouteHopsTable
• Generating Traps

traceRouteResultsTable

While the test is running, this traceRouteResultsTable keeps track of the status of the test. The value of traceRouteResultsOperStatus is enabled while the test is running and disabled when it has stopped.

The value of traceRouteCtlAdminStatus remains enabled until you set it to disabled. Thus, to get the status of the test, you must examine traceRouteResultsOperStatus.

The traceRouteCtlFrequency variable can be used to schedule many tests for one traceRouteCtlEntry. After a test ends normally (you did not stop the test) and traceRouteCtlFrequency number of seconds has elapsed, the test is started again just as if you had set traceRouteCtlAdminStatus to enabled. If you intervene at any time between repeated tests (you set traceRouteCtlAdminStatus to disabled or traceRouteCtlRowStatus to notInService), the repeat feature is disabled until another test is started and ends normally. A value of 0 for traceRouteCtlFrequency indicates this repeat feature is not active.

traceRouteResultsIpTgtAddr and traceRouteResultsIpTgtAddrType are set to the value of the resolved destination address when the value of traceRouteCtlTargetAddressType is dns. When a test starts successfully and traceRouteResultsOperStatus transitions to enabled:

• traceRouteResultsIpTgtAddr is set to null-string.
• traceRouteResultsIpTgtAddrType is set to unknown.

traceRouteResultsIpTgtAddr and traceRouteResultsIpTgtAddrType are not set until traceRouteCtlTargetAddress can be resolved to a numeric address. To retrieve these values, poll traceRouteResultsIpTgtAddrType for any value other than unknown after successfully setting traceRouteCtlAdminStatus to enabled.

At the start of a test, traceRouteResultsCurHopCount is initialized to traceRouteCtlInitialTtl, and traceRouteResultsCurProbeCount is initialized to 1. Each time a probe result is determined, traceRouteResultsCurProbeCount increases by 1. While the test is running, the value of traceRouteResultsCurProbeCount reflects the current outstanding probe for which results have not yet been determined.

The traceRouteCtlProbesPerHop number of probes is sent for each time-to-live (TTL) value. When the result of the last probe for the current hop is determined, provided that the current hop is not the destination hop, traceRouteResultsCurHopCount increases by 1, and traceRouteResultsCurProbeCount resets to 1.

At the start of a test, if this is the first time this test has been run for this traceRouteCtlEntry, traceRouteResultsTestAttempts and traceRouteResultsTestSuccesses are initialized to 0.

At the end of each test execution, traceRouteResultsOperStatus transitions to disabled, and traceRouteResultsTestAttempts increases by 1. If the test was successful in determining the full path to the target, traceRouteResultsTestSuccesses increases by 1, and traceRouteResultsLastGoodPath is set to the current time.

traceRouteProbeResultsTable

Each entry in traceRouteProbeHistoryTable is indexed by five variables:

• The first two variables, traceRouteCtlOwnerIndex and traceRouteCtlTestName, are the same ones used for traceRouteCtlTable and to identify the test.
• The third variable, traceRouteProbeHistoryIndex, is a counter, starting from 1 and wrapping at FFFFFFFF. The maximum number of entries is limited by traceRouteCtlMaxRows.
• The fourth variable, traceRouteProbeHistoryHopIndex, indicates which hop this probe is for (the actual time-to-live or TTL value). Thus, the first traceRouteCtlProbesPerHop number of entries created when a test starts have a value of traceRouteCtlInitialTtl for traceRouteProbeHistoryHopIndex.
• The fifth variable, traceRouteProbeHistoryProbeIndex, is the probe for the current hop. It ranges from 1 to traceRouteCtlProbesPerHop.

While a test is running, as soon as a probe result is determined, the next probe is sent. A maximum of traceRouteCtlTimeOut seconds elapses before a probe is marked with status requestTimedOut and the next probe is sent. There is never more than one outstanding probe per traceroute test. Any probe result coming back after a probe times out is ignored.

Each probe can:

• Result in a response from a host acknowledging the probe
• Time out with no response from a host acknowledging the probe
• Fail to be sent

Each probe status is recorded in traceRouteProbeHistoryTable with traceRouteProbeHistoryStatus set accordingly.

Probes that result in a response from a host record the following data:

• traceRouteProbeHistoryResponse—Round-trip time (RTT)
• traceRouteProbeHistoryHAddrType—The type of HAddr (next argument)
• traceRouteProbeHistoryHAddr—The address of the hop

All probes, regardless of whether a response for the probe is received, have the following recorded:

• traceRouteProbeHistoryStatus—What happened and why
• traceRouteProbeHistoryLastRC—Return code (RC) value of the ICMP packet
• traceRouteProbeHistoryTime—Timestamp when the probe result was determined

When a probe cannot be sent, traceRouteProbeHistoryResponse is set to 0. When a probe times out, traceRouteProbeHistoryResponse is set to the difference between the time when the probe was discovered to be timed out and the time when the probe was sent.

traceRouteHopsTable

Entries in traceRouteHopsTable are indexed by three variables:

• The first two, traceRouteCtlOwnerIndex and traceRouteCtlTestName, are the same ones used for traceRouteCtlTable and identify the test.
• The third variable, traceRouteHopsHopIndex, indicates the current hop, which starts at 1 (not traceRouteCtlInitialTtl).

When a test starts, all entries in traceRouteHopsTable with the given traceRouteCtlOwnerIndex and traceRouteCtlTestName are deleted. Entries in this table are only created if traceRouteCtlCreateHopsEntries is set to true.

A new traceRouteHopsEntry is created each time the first probe result for a given TTL is determined. The new entry is created whether or not the first probe reaches a host. The value of traceRouteHopsHopIndex is increased by 1 for this new entry.

Note: Any traceRouteHopsEntry can lack a value for traceRouteHopsIpTgtAddress if there are no responses to the probes with the given TTL.

Each time a probe reaches a host, the IP address of that host is available in the probe result. If the value of traceRouteHopsIpTgtAddress of the current traceRouteHopsEntry is not set, then the value of traceRouteHopsIpTgtAddress is set to this IP address. If the value of traceRouteHopsIpTgtAddress of the current traceRouteHopsEntry is the same as the IP address, then the value does not change. If the value of traceRouteHopsIpTgtAddress of the current traceRouteHopsEntry is different from this IP address, indicating a path change, a new traceRouteHopsEntry is created with:

• traceRouteHopsHopIndex variable increased by 1
• traceRouteHopsIpTgtAddress set to the IP address
  Note: A new entry for a test is added to traceRouteHopsTable each time a new TTL value is used or the path changes. Thus, the number of entries for a test may exceed the number of different TTL values used.

When a probe result is determined, the value traceRouteHopsSentProbes of the current traceRouteHopsEntry increases by 1. When a probe result is determined, and the probe reaches a host:

• The value traceRouteHopsProbeResponses of the current traceRouteHopsEntry is increased by 1.
• The following variables are updated:
  • traceRouteResultsMinRtt—Minimum round-trip time
  • traceRouteResultsMaxRtt—Maximum round-trip time
  • traceRouteResultsAverageRtt—Average round-trip time
  • traceRouteResultsRttSumOfSquares—Sum of squares of round-trip times
  • traceRouteResultsLastGoodProbe—Timestamp of the last response
    Note: Only probes that reach a host affect the round-trip time values.

Generating Traps

For any trap to be generated, the appropriate bit of traceRouteCtlTrapGeneration must be set. You must also configure a trap group to receive remote operations. Traps are generated under the following conditions:

• traceRouteHopsIpTgtAddress of the current probe is different from the last probe with the same TTL value (traceRoutePathChange).
• A path to the target could not be determined (traceRouteTestFailed).

A path to the target was determined (traceRouteTestCompleted).

For information about how to configure a trap group to receive remote operations, see Configuring SNMP Trap Groups and SNMP Remote Operations Overview.

Monitoring Traceroute Test Completion

When a test is complete, traceRouteResultsOperStatus transitions from enabled to disabled. This transition occurs in the following situations:

• The test ends successfully. A probe result indicates that the destination has been reached. In this case, the current hop is the last hop. The rest of the probes for this hop are sent. When the last probe result for the current hop is determined, the test ends.
• traceRouteCtlMaxTtl threshold is exceeded. The destination is never reached. The test ends after the number of probes with TTL value equal to traceRouteCtlMaxttl have been sent.
• traceRouteCtlMaxFailures threshold is exceeded. The number of consecutive probes that end with status requestTimedOut exceeds traceRouteCtlMaxFailures.
• You end the test. You set traceRouteCtlAdminStatus to disabled or delete the row by setting traceRouteCtlRowStatus to destroy.
• You misconfigured the traceroute test. A value or variable you specified in traceRouteCtlTable is incorrect and will not allow a single probe to be sent. Because of the nature of the data, this error could not be determined until the test was started; that is, until after traceRouteResultsOperStatus transitioned to enabled. When this occurs, one entry is added to traceRouteProbeHistoryTable with traceRouteProbeHistoryStatus set to the appropriate error code.

If traceRouteCtlTrapGeneration is set properly, either the traceRouteTestFailed or traceRouteTestCompleted trap is generated.

Gathering Traceroute Test Results

You can either poll traceRouteResultsOperStatus to find out when the test is complete or request that a trap be sent when the test is complete. For more information on traceResultsOperStatus, see traceRouteResultsTable. For more information on Traceroute MIB traps, see Generating Traps.

Statistics are calculated on a per-hop basis and then stored in traceRouteHopsTable. They include the following for each hop:

• traceRouteHopsIpTgtAddressType—Address type of host at this hop
• traceRouteHopsIpTgtAddress—Address of host at this hop
• traceRouteHopsMinRtt—Minimum round-trip time
• traceRouteHopsMaxRtt—Maximum round-trip time
• traceRouteHopsAverageRtt—Average round-trip time
• traceRouteHopsRttSumOfSquares—Sum of squares of round-trip times
• traceRouteHopsSentProbes—Number of attempts to send probes
• traceRouteHopsProbeResponses—Number of responses received
• traceRouteHopsLastGoodProbe—Timestamp of last response

You can also consult traceRouteProbeHistoryTable for more detailed information on each probe. The index used for traceRouteProbeHistoryTable starts at 1, goes to 0xFFFFFFFF, and wraps to 1 again.

For example, assume the following:

• traceRouteCtlMaxRows is 10.
• traceRouteCtlProbesPerHop is 5.
• There are eight hops to the target (the target being number eight).
• Each probe sent results in a response from a host (the number of probes sent is not limited by traceRouteCtlMaxFailures).

In this test, 40 probes are sent. At the end of the test, traceRouteProbeHistoryTable would have a history of probes like those in Table 8.

Table 8: traceRouteProbeHistoryTable

HistoryIndex	HistoryHopIndex	HistoryProbeIndex
31	7	1
32	7	2
33	7	3
34	7	4
35	7	5
36	8	1
37	8	2
38	8	3
39	8	4
40	8	5

Stopping a Traceroute Test

To stop an active test, set traceRouteCtlAdminStatus to disabled. To stop a test and remove its traceRouteCtlEntry, traceRouteResultsEntry, traceRouteProbeHistoryEntry, and traceRouteProbeHistoryEntry objects from the MIB, set traceRouteCtlRowStatus to destroy.

Traceroute Variables

This section clarifies the ranges for the following variables that are not explicitly specified in the Traceroute MIB:

• traceRouteCtlMaxRows—The maximum value for traceRouteCtlMaxRows is 2550. This represents the maximum TTL (255) multiplied by the maximum for traceRouteCtlProbesPerHop (10). Therefore, the traceRouteProbeHistoryTable accommodates one complete test at the maximum values for one traceRouteCtlEntry. Usually, the maximum values are not used and the traceRouteProbeHistoryTable is able to accommodate the complete history for many tests for the same traceRouteCtlEntry.
• traceRouteMaxConcurrentRequests—The maximum value is 50. If a test is running, it has one outstanding probe. traceRouteMaxConcurrentRequests represents the maximum number of traceroute tests that have traceRouteResultsOperStatus with a value of enabled. Any attempt to start a test with traceRouteMaxConcurrentRequests tests running will result in the creation of one probe with traceRouteProbeHistoryStatus set to maxConcurrentLimitReached and that test will end immediately.
• traceRouteCtlTable—The maximum number of entries allowed in this table is 100. Any attempt to create a 101st entry will result in a BAD_VALUE message for SNMPv1 and a RESOURCE_UNAVAILABLE message for SNMPv2.