TRCTCPRTE (Trace TCP/IP Route)

TRCTCPRTE Command syntax diagram

 

Purpose

The Trace TCP/IP Route (TRCTCPRTE) command, also known as TRACEROUTE, traces the route of IP packets to a user-specified destination system. The route can involve many different systems along the way. Each system along the route is referred to as a hop. You can trace all hops along the route or specify the starting and ending hops to be traced.

The route is traced by sending packets (called probes) to the destination system. Each probe contains an upper limit on the number of systems the probe can pass through.

Note: In IP Version 6, 'Time To Live' (TTL) is called the 'hop limit'.

A route is traced by successively incrementing the TTL (or hop limit) of the probe packets by one. The trace ends when either a probe response is received from the destination system or when the probe Time To Live value equals the maximum allowed.

Responses from the probe packets are sent as messages to the job log or as queue entries to a user-specified data queue.

 

Required Parameters

RMTSYS

Specifies the remote system name (255 characters) or IP address of the destination system.

Either a valid IP Version 4 or IP Version 6 address will be accepted.

remote-system: Specify the remote system name or address.

 

Optional Parameters

RANGE

Specifies the range of hop systems from which probe responses are expected. Each probe specifies a Time To Live (or hop limit) integer value. This Time To Live (TTL) value is the maximum number of hops the probe can traverse. For example, a probe packet with a TTL of 3 can pass through at most 3 hop systems before the hop system discards the probe and sends information back to the system from which the probe originated.

Element 1 specifies the first TTL value sent in probe packets. Element 2 specifies the last TTL value sent in probe packets. Trace information is generated from each hop system which discards a probe packet because the TTL value in the probe is reached or when the destination system is reached.

Element 1: Starting Probe TTL

(hop limit)

1: The default starting hop is 1.

starting-hop: Specify the first hop limit TTL number used for probe packets. Valid values range from 1 to 255.

Element 2: Ending Probe TTL

(hop limit)

30: The default ending hop is 30.

ending-hop: Specify the maximum number of hops a probe can traverse to reach the destination system. Valid values range from 1 to 255.

PROBES

Specifies the number of probe packets sent to each hop system for each probe TTL

(hop limit)

value in the range specified by the RANGE parameter.

3: The default number of probes is three.

number-of-probes: Specify the number of probes to send. Valid values range from 1 to 64.

WAITTIME

Specifies the maximum time, in seconds, to wait for a response from a hop system to each probe.

3: The default is to wait up to 3 seconds for a response.

response-waittime: Specify the maximum time in seconds to wait for a response. Valid values range from 1 to 120.

PKTLEN

Specifies the total length, in bytes, of the IP packet sent for each probe.

40: The default probe packet length.

packet-length: Specify the probe IP packet length, in bytes. Valid values range from 40 to 65535.

OUTPUT

Specifies where the results obtained from sending the probe packets is sent. Information is sent for each hop until the destination system is reached, including hop count, average round-trip time, IP address of the hop and host name of the hop.

*MSG: Results are output as messages sent to the job log of the job in which the command is issued.

*VERBOSE: Results are output as messages sent to the job log of the job in which the command is issued. All responses received are displayed. Results are not limited to ICMP TIME_EXCEEDED and PORT_UNREACHABLE responses.

*DTAQ: Results from probes are placed on the data queue specified by the DTAQ parameter.

DTAQ

Specifies the name and library of the data queue on which entries are placed. When a data queue is specified, messages are not sent to the job log unless an error occurs.

Each queue entry contains the response to a probe if one was received or indicates that no probe response was received. The specified data queue must have a queue entry length of at least 32 characters and must exist when the command is issued.

data-queue-name: Specify the name of the data queue.

The name of the data queue can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

ADRVERFMT

Specifies which IP address version protocol (IP Version 4 or IP Version 6) is used to resolve host names specified by RMTSYS.

*CALC: The address family will be 'calculated' (determined) based on the address entered by the RMTSYS parameter. TRCTCPRTE (TRACEROUTE) will first use IP Version 4 host name resolution in determining the IP address. If that fails, IP Version 6 host name resolution will then be used in order to resolve the IP address.

*IP4: Explicitly use the IP Version 4 protocol addressing method.

*IP6: Explicitly use the IP Version 6 protocol addressing method.

LCLINTNETA

Specifies how the source IP address in the probe packet is chosen.

*ANY: The source IP address in the probe packets is chosen by the system. The system may use any active local interface which can reach the remote system.

source-IP-address: The local interface to use as the source IP address.

RMTPORT

Specifies the base UDP port number used in probes.

33434: The default base UDP port number.

base-remote-port: Specify the base UDP port number used in probes. Valid values range from 1 to 65535.

NAMELOOKUP

Specifies whether IP addresses will be resolved to the host name.

*YES: The address will be resolved to the host name.

*NO: The address will not be resolved to the host name.

PROBEPCL

Specifies the protocol used when sending probe packets.

*ICMP: The probes sent to the destination system are ICMP (Internet Control Message Protocol) Echo Request packets.

*UDP:The probes sent to the destination system are UDP (User Datagram Protocol) packets.

FRAGMENT

Specifies how the setting of the "Do Not Fragment" option in the IP header of the probe packet is determined.

*TCPA: The iSeries system sets the option based on the setting of the IP Path MTU Discovery TCP/IP attribute.

Note:

Use the Change TCP/IP Attributes (CHGTCPA) command to change the value of this attribute.

*NO: The "Do Not Fragment" option is always not set in probe packets.

*YES: The "Do Not Fragment" option is always set in probe packets.

Examples for TRCTCPRTE

Example 1: Trace Entire Route

TRCTCPRTE RMTSYS('130.14.3.5')

This command traces the entire route between the local iSeries system and the destination system whose IP address is '130.14.3.5'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP Echo Request packet. Results received are sent as messages to the job log.

Example 2: Trace Partial Route

TRCTCPRTE RMTSYS('AAA.BBBB.COM')
  RANGE(3 7) PROBES(5) PROBEPCL(*UDP)
  OUTPUT(*DTAQ) DTAQ(MYLIB/MYDATAQ)

This command traces the route between the local iSeries system and the destination system whose host name is 'AAA.BBBB.COM'. Five probe packets will be sent for the starting range value of 3. Each probe will be a UDP packet inside an IP packet that is 40 bytes long. Each of these 5 probes will specify a TTL of 3. If system AAA.BBB.COM can be reached by passing through at most 2 hop systems then the trace will terminate at this point.

If system AAA.BBB.COM is futher than 2 hops, another set of 5 probe packets will be sent to the destination AAA.BBB.COM. Each of these 5 probes will specify a TTL of 4. This is repeated until either system AAA.BBB.COM responds to a probe or 5 probes with a TTL of 7, the ending range value, are sent. Any results received are placed as queue entries on data queue MYDATAQ in library MYLIB.

Example 3: Trace Route with an IP Version 6 address

TRCTCPRTE RMTSYS('1:2:3:4:5:6:7:8')

This command traces the entire route between the local iSeries system and the destination system whose IP address is '1:2:3:4:5:6:7:8'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP6 Echo Request packet. Results received are sent as messages to the job log.

Note: A colon (':') found in RMTSYS signifies an IP Version 6 address and will cause an ICMP6 echo request packet to be generated.

Example 4: Trace Route with an IP Version 6 host name

TRCTCPRTE RMTSYS('IP6HOST')

This command traces the entire route between the local iSeries system and the destination system whose host name is 'IP6HOST'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP6 Echo Request packet. Results received are sent as messages to the job log.

The default "Address version format" is *CALC. Host name resolution may return multiple IP addresses for a given host name. But, in the case (*CALC), the first IP address (IP Version 4 or IP Version 6) resolved will be the address used when attempting to trace the route.

Example 5: Trace Route with an IP Version 6 host name and explicitly use IP Version 6 host name resolution

TRCTCPRTE RMTSYS('IP6HOST') ADRVERFMT(*IP6)

This command traces the entire route between the local iSeries system and the destination system whose host name is 'IP6HOST'. Three probe packets will be sent to each hop system. Each IP probe packet will be 40 bytes long and will contain an ICMP6 Echo Request packet. Results received are sent as messages to the job log.

This example differs from example 4 in that only a valid IP version 6 resolved address, for IP6HOST, will be used when attempting to trace the route.

Error messages for TRCTCPRTE

*ESCAPE Messages

TCP3250

DTAQ parameter value required with OUTPUT(*DTAQ).

TCP3251

DTAQ parameter not valid when OUTPUT(*MSG) specified.

TCP3252

Starting range value greater than range limit.