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


>>-TRACERTE----------------------------------------------------->

>--+-?---------------------------------------------+-----------><
   '-host_name--+------------+--+----------------+-'   
                '-packetSize-'  '-(--| Options |-'     

Options

   .------------------------.   
   V                        |   
|----+--------------------+-+-----------------------------------|
     +-Addrtype--+-ipv4-+-+     
     |           '-ipv6-' |     
     +-DEBUG--------------+     
     +-Intf --interface---+     
     +-Limdisp------------+     
     |      .-30--.       |     
     +-MAX--+-----+-------+     
     |      '-hop-'       |     
     +-NOName-------------+     
     +-NORoute------------+     
     |       .-33434-.    |     
     +-PORT--+-------+----+     
     |       '-num---'    |     
     +-Srcip --srcAddr----+     
     +-TCP --tcpname------+     
     |      .-0---.       |     
     +-Tos--+-----+-------+     
     |      '-tos-'       |     
     |      .-3--------.  |     
     +-TRY--+----------+--+     
     |      '-attempts-'  |     
     +-Verbose------------+     
     |       .-5-------.  |     
     '-WAIT--+---------+--'     
             '-seconds-'

Note: The minimum abbreviation for each parameter is shown as uppercase letters in the syntax diagram above.

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

The Traceroute command displays one line of output for every TTL or hop limit value for which it sent a UDP probe packet. The format of the output is as follows:

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. Flag Indicates * No datagram was received before your request timed out. The hop might not respond with ICMP or, the NETACCESS configuration might prohibit the response packets from being received by the command because of the security product user ID associated with the user who invoked the command. A Administratively prohibited (IPv6 only). B Destination is beyond scope of source address (IPv6 only). C Precedence cutoff in effect (IPv4 only). D Destination Host unknown (IPv4 only). F The packet needs to be fragmented. H The destination host is unreachable. N The destination network is unreachable (IPv4 only). P The destination protocol is unreachable (IPv4 only). Q The destination host is reachable, but cannot accept the packet because the queue is full (IPv4 only). R No route to destination (IPv6 only). S The route supplied for the message was incorrect (IPv4 only). T Network unreachable for TOS or host unreachable for TOS (IPv4 only). U Address is unreachable (IPv6 only). V Host precedence violation (IPv4 only). X Communication administratively prohibited by filtering (IPv4 only). Firewall configuration is the most common reason for this code being returned to Traceroute. num Unknown ICMP Unreachable code (IPv4 only).

For a list of the ICMP types associated with the preceding Flags, see ICMP/ICMPv6 types and codes.

Examples

Note: In these examples, an asterisk (*) represents a lost packet.

The second hop in this example does not send TTL-exceeded messages.

tracerte cyst.watson.ibm.com                         
CS V2R1: 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 V2R1: 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 V2R1: 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 V2R1: 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 V2R1: 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 V2R1: 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 V2R1: 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.

Restrictions:

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.