The TSO TRACERTE command: Debug network problems
The TSO TRACERTE command is useful for debugging various network problems. The Tracerte command sends UDP requests with varying TTL (time-to-live) or hop count values and then waits for the routers between the local and remote hosts to send TTL-exceeded messages.
Format:
Parameters:
- ?
- Specifies the command help.
- host_name
- Specifies the destination host. This must be an IP address, or
a host name that can be resolved. IPv4-mapped IPv6 addresses are not
supported.
If the host_name value is specified as a host name (not an IP address), the command invokes the resolver to obtain an IP address for the host_name value. The command uses the first IP address that is returned by the resolver. You can use the ADDRTYPE option to determine whether the command requests only IPv4 or only IPv6 IP addresses from the resolver. If you do not specify the ADDRTYPE option, the INTF and SRCIP options can also be used to determine whether the command requests only IPv4 or only IPv6 IP addresses from the resolver. If neither ADDRTYPE, INTF, or SRCIP are specified, then the command does not request a specific type of IP address from the resolver; IPv4 and IPv6 IP addresses can be returned by the resolver.
When using IPv6 link-local addresses, you can provide scope information with the IP address or host name. To specify scope information, add a percent character (%) after the host_name value, followed by the scope information (usually an interface name). See the examples that follow for an example of using the command with scope information. For a more complete explanation about the use of scope information, see the support for scope information in the z/OS Communications Server: IPv6 Network and Application Design Guide.
Guidelines:- When you are running multiple TCP/IP stacks on the same MVS™ image and the interface name used as the scope information has been defined to multiple TCP/IP stacks, you must specify the TCP parameter to ensure that the correct stack is used to send the command's packets.
- Providing scope information on the host_name option has the same effect as specifying the local interface using the INTF option, although the INTF option covers a wider range of situations (scope information applies only to IPv6 link-local addresses). If both methods of providing scope information are used on the same command, the values provided for scope information on the host_name option and for the INTF interface option must represent the same local interface, otherwise the command fails.
- packetSize
- Optional parameter that can be used to change the size of a probe
packet. The probe size might affect the route of a probe. The value
specified is added to the default probe packet size up to a maximum
of 65 535 bytes.
For IPv4 destinations, the packet size value must be between 1 and 65 495 bytes. The 65 495 value is the maximum IP packet size (65 535) minus the default probe packet size (40). The default probe packet size includes the IP header, UDP header, and default UDP data.
For IPv6 destinations, the packet size value must be between 1 and 65 515 bytes. The 65 515 value is the maximum UDP data size (65 535) minus the default UDP probe packet size (20). The default probe packet size includes the UDP header, and default UDP data. The IPv6 IP header is added later, before the packet is sent and its size is not included in the packetSize value.
If additional IP headers are dynamically added later to the outbound probe packet then the actual size of the packet is increased.
- ADDRTYPE
- Specifies the IP address type that the Resolver returns when resolving
the host name to an IP address. The values for this option are not
case sensitive.
- ipv6
- Specifies that only IPv6 IP addresses are returned from the Resolver when resolving the host name to an IP address.
- ipv4
- Specifies that only IPv4 IP addresses are returned from the Resolver when resolving the host name to an IP address.
If the ADDRTYPE option is not specified, see the description of the host_name parameter for information on how the host_name value is resolved to an IP address.
- DEBUG
- Specifies that extra messages are to be printed.
- INTF interface
- Specifies the local interface, interface, over which the packets are sent. The interface is either a maximum
16-byte name from a LINK or INTERFACE profile statement, or the IP
address of a local interface. IPv4-mapped IPv6 addresses are not
supported. Local VIPA or LOOPBACK interfaces are not valid.
If the destination host is specified as a host name and the ADDRTYPE option is not specified, the address type of the INTF value is used to determine whether the host name is resolved to an IPv4 or IPv6 IP address.
When this parameter is specified, the Traceroute command establishes affinity to either the default TCP/IP stack or to the stack that is specified on the TCP parameter. The specified interface must be defined to the stack to which the Traceroute command establishes affinity. You must also ensure that a route exists to the destination using the specified interface. This can be any kind of route, including a default route. This parameter is independent of the SRCIP parameter used as the source IP address in the outbound packets.Note: As a diagnostics aid in analyzing response times and path availability using a particular route, this parameter routes packets over specified interfaces regardless of the multipath settings in the IPCONFIG/IPCONFIG6 MULTIPATH profile statements by bypassing the outbound path selection algorithm for the packets.Restriction:- You cannot specify scope information for the interface value.
- To specify an OSM interface for the parameter, the user ID must have RACF® authority to use the interface. For more information about OSM interface authorization, see OSM Access Control in z/OS Communications Server: IP Configuration Guide.
- LIMDISP
- Displays the hop limit value from each received packet. This value can be used to help detect asymmetric routing.
- MAX hop
- Specifies the maximum time to live (TTL) or hop limit. The range for valid values is 1 - 255. The default is 30.
- NONAME
- Specifies to print the hop IP address without resolving it to a host name. This address is numeric and saves a name server address-to-name lookup for each gateway on the path.
- NOROUTE
- Sends information directly to a host in an attached network. If the selected route indicates that the host is not in an adjacent network, an error is returned.
- PORT num
- Specifies the source port number and the starting destination
port number. The range for valid values is 2048 - 60 000. The default
is 33 434.
For example, in the default case, the source port number is 33 434. The destination port number in the first outbound probe packet is the default port value of 33 434 plus one, or 33 435. The destination port number is incremented by 1 for each subsequent outbound probe packet.
- SRCIP srcAddr
- Specifies the source IP address, srcAddr. You must specify this as an IP address and not a host name. IPv4-mapped
IPv6 addresses are not supported. On hosts with more than one IP address,
you can set the source address to the IP address for another one of
the stack's interfaces. This can be a VIPA address.
If the destination host is specified as a host name and the ADDRTYPE option is not specified, the address type of the SRCIP value is used to determine whether the host name should be resolved to an IPv4 or IPv6 IP address.
Restriction: You cannot specify scope information for the source IP address.
- TCP tcpname
- Specifies the name, tcpname, of the
TCP/IP stack to be used to send the probe packets. The tcpname is an 8-byte procedure name that is used to
start TCP/IP. When the
member.identifier
method of starting TCP/IP is used, the value specified for identifier must be used as tcpname. When this option is not specified and z/OS® UNIX is configured for CINET, the CINET Prerouter selects the TCP/IP stack to which the request is routed. - TOS tos
- Specifies the Type of Service value (tos) in the probe packets. The range for valid values is 0 - 255. The default is 0. This parameter applies only to IPv4 destinations and is ignored for IPv6 destinations.
- TRY attempts
- Specifies the number of attempts. The range for valid values is 1 - 20. The default is 3.
- VERBOSE
- Specifies that additional information is to be displayed. The information currently displayed is the number of bytes of the ICMP response and the IP address to which the response was sent.
- WAIT seconds
- Specifies how long to wait for a response. The range for valid values is 1 - 255. The default is 5 seconds.
Results:
HOP NAME (IP_ADDRESS) NUM ms !FLAG
The values displayed
are:
Value | Description |
---|---|
HOP | The hop limit value used in the outbound probe packets. |
NAME | If the source IP address in the received Internet Control Message Protocol (ICMP) response can be found in the host site tables, NAME displays the name associated with the source IP address. The host name displayed might include scope information representing the interface over which the ICMP response was received. |
IP_ADDRESS | The source IP address from the received ICMP response. |
NUM | The elapsed time between when the probe packet was sent out and when the ICMP response to that probe packet was received. |
! | An exclamation point without one of the FLAG values below indicates that the received hop limit was less than or equal to 1. Otherwise, an exclamation point is followed by one of the values below. |
FLAG | This is an optional field. It is
present only if one of the following events occurs. Unless otherwise
indicated the flags apply to both IPv4 and IPv6 destinations.
|
Examples:
- The second hop in this example does not send TTL-exceeded messages.
tracerte cyst.watson.ibm.com CS V2R4: Traceroute to CYST.WATSON.IBM.COM (9.2.91.34) 1 9.67.22.2 (9.67.22.2) 67 ms 53 ms 60 ms 2 * * * 3 9.67.1.5 (9.67.1.5) 119 ms 83 ms 65 ms 4 9.3.8.14 (9.3.8.14) 77 ms 80 ms 87 ms 5 9.158.1.1 (9.158.1.1) 94 ms 89 ms 85 ms 6 9.31.3.1 (9.31.3.1) 189 ms 197 ms * 7 * * 9.31.16.2 (9.31.16.2) 954 ms 8 129.34.31.33 (129.34.31.33) 164 ms 181 ms 216 ms 9 9.2.95.1 (9.2.95.1) 198 ms 182 ms 178 ms 10 9.2.91.34 (9.2.91.34) 178 ms 187 ms *
- Sometimes packets are lost (hop 6).
tracerte 129.35.130.09 CS V2R4: Traceroute to 129.35.130.09 (129.35.130.9) 1 9.67.22.2 (9.67.22.2) 61 ms 62 ms 56 ms 2 * * * 3 9.67.1.5 (9.67.1.5) 74 ms 73 ms 80 ms 4 9.3.8.1 (9.3.8.1) 182 ms 200 ms 184 ms 5 129.35.208.2 (129.35.208.2) 170 ms 167 ms 163 ms 6 * 129.35.208.2 (129.35.208.2) 192 ms !H 157 ms !H
- The network was found, but no host was found. The packet could
not route to that network.
tracerte 129.45.45.45 CS V2R4: Traceroute to 129.45.45.45 (129.45.45.45) 1 9.67.22.2 (9.67.22.2) 320 ms 56 ms 71 ms 2 * * * 3 9.67.1.5 (9.67.1.5) 67 ms 64 ms 65 ms 4 9.67.1.5 (9.67.1.5) 171 ms !N 68 ms !N 61 ms !N
- The Traceroute command uses a domain name server along with the
site tables for inverse name resolution. If a host name is found,
it is printed along with its IP address.
tracerte EVANS CS V2R4: Traceroute to EVANS (9.67.30.25) 1 BART (9.67.60.85) 20 ms 56 ms 71 ms 2 BUZZ (9.67.60.84) 55 ms 56 ms 54 ms 3 EVANS (9.67.30.25) 67 ms 64 ms 65 ms
- Successful Traceroute to an IPv6 destination:
tracerte linuxipv62.tcp CS V2R4: Traceroute to LINUXIPV62.TCP.raleigh.ibm.com at IPv6 address: 2001:0DB8::1:9:67:114:44 1 2001:0DB8::206:2aff:fe66:c800 (2001:0DB8::206:2aff:fe66:c800) 2 ms 3 ms * 2 2001:0DB8::1:9:67:114:44 (2001:0DB8::1:9:67:114:44) 2 ms 2 ms 2 ms
- Successful Traceroute to an IPv6 link-local destination:
tracerte fe80::12:1:2%mpc6221 CS V2R4: Traceroute to FE80::12:1:2 at IPv6 address: fe80::12:1:2 1 fe80::12:1:2%MPC6221 (fe80::12:1:2) 62 ms 1 ms 0 ms
- Using an unknown IPv6 IP address results in a flag indicating
that there is no route to the destination.
tracerte 2001:0DB8::1:9:67:114:47 CS V2R4: Traceroute to 2001:0DB8::1:9:67:114:47 at IPv6 address: 2001:0DB8::1:9:67:114:47 1 2001:0DB8::206:2aff:fe66:c800 (2001:0DB8::206:2aff:fe66:c800) 3 ms !R * 2 ms !R
Usage:
- To authorize the TSO Traceroute command to use RAW sockets, add the command name, TRACERTE, to the AUTHCMD NAMES section of the member IKJTSOxx of SYS1.PARMLIB. TSO user IDs with UNIX System Services Superuser authority are able to execute the command even without this SYS1.PARMLIB modification. For other authorization considerations, see MVS-related considerations information in the z/OS Communications Server: IP Configuration Guide.
- The range of port numbers that the Traceroute command uses are typically not valid but you can change the range if the target host is using a nonstandard UDP port.
- To interrupt Traceroute command processing, use the PA1 or ATTN key.
- If IPv4 tunnels exist on the path to the IPv6 destination host, the IPv4 routers in the tunnel are not counted in the hop count. For a more complete description of tunnels, see the z/OS Communications Server: IPv6 Network and Application Design Guide.
- Traceroute commands to a remote host might be unable to detect TTL or hop limit exceeded messages if there is an IPSec tunnel at any point between the two systems, even if the host is reachable using other commands.