The z/OS UNIX traceroute command: Debug network problems
This command is useful for debugging various network problems. This command sends UDP requests with varying TTL (time to live) or hop limit values and then waits for the routers between the local and remote hosts to send time-exceeded messages.
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. The -A option can be used to determine whether the command requests only IPv4 or only IPv6 IP addresses from the resolver. If the -A option is not specified, the -i and -s options can also be used to determine whether the command requests only IPv4 or only IPv6 IP addresses from the resolver. If neither the -A, -i, or -s options are specified, then the command does not request a specific type of IP address from the resolver, so both 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). An example follows that uses 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 more than one TCP/IP stack, you must specify the -a 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 -i 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 -i 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.
- -A
- 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 -A 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.
- -a tcpname
- Specifies the name 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
S member.identifiermethod of starting TCP/IP is used, the value specified for identifier must be used as the tcpname value.When the -a 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.
- -d
- Specifies that extra messages and other debugging information are to be displayed.
- -i interface
- Specifies the local interface over which the packets is sent.
The interface is either a maximum 16-byte name from a LINK or INTERFACE
profile statement, or it is the IP address of the 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 -A option is not specified, the address type of the -i value is used to determine whether the host name is resolved to an IPv4 or IPv6 IP address.
When this parameter is specified, the command establishes affinity to either the default TCP/IP stack or the stack specified on the -a parameter. The specified interface must be defined to the stack to which the 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 -s 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 statement 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.
- -l
- Displays the time-to-live or hop limit value from each received packet. This value can be used to help detect asymmetric routing.
- -m hop
- Specifies the maximum time to live or hop limit. The range for valid values is 1 - 255. The default is 30.
- -n
- 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.
- -p num
- Specifies the starting destination port number. This parameter
does not affect the value of the source port number used. The range
of valid values is 2048 - 60 000. The default is 33 434.
For example, in the default case, the destination port number in the first outbound probe packet is the default port value of 33 434 plus 1, or 33 435. The destination port number is incremented by 1 for each subsequent outbound probe packet.
- -q attempts
- Specifies the number of times that a probe is sent with the same time-to-live/hop limit value. This number reflects the total probe transmission (success or failure) per time-to-live/hop limit increment. The range is 1 - 20. The default is 3.
- -r
- 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.
- -s scrAddr
- Specifies the source IP address. You must specify this address
as an IP number 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 -A option is not specified, the address type of the -s 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.
- -t 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.
- -v
- 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.
- -w 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| 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. |
| ! | 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. |
| NUM | The elapsed time between when the probe packet was sent out and when the ICMP response to that probe packet was received. |
| 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:
In these examples, an asterisk (*) represents a lost packet.
- The second hop in this example does not send TTL-exceeded messages.
traceroute cyst.watson.ibm.com CS V2R4: Traceroute to CYST.WATSON.IBM.COM (9.2.91.34) Enter ESC character plus C or c to interrupt 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).
traceroute 129.35.130.09 CS V2R4: Traceroute to 129.35.130.09 (129.35.130.9) Enter ESC character plus C or c to interrupt 1 9.67.22.2 (9.67.22.2) 61 ms 62 ms 56 ms 2 * * * 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.
traceroute 129.45.45.45 CS V2R4: Traceroute to 129.45.45.45 (129.45.45.45) Enter ESC character plus C or c to interrupt 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 - z/OS UNIX traceroute 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.
traceroute EVANS CS V2R4: Traceroute to EVANS (129.45.45.45) Enter ESC character plus C or c to interrupt 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.
traceroute linuxipv62.tcp CS V2R4: Traceroute to linuxipv62.tcp.raleigh.ibm.com at IPv6 address: 2001:0DB8::1:9:67:114:44 Enter ESC character plus C or c to interrupt 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.
traceroute fe80::12:1:2%mpc6221 CS V2R4: Traceroute to fe80::12:1:2 at IPv6 address: fe80::12:1:2 Enter ESC character plus C or c to interrupt 1 fe80::12:1:2%MPC6221 (fe80::12:1:2) 1 ms 2 ms 1 ms - Using an unknown IPv6 IP address results in a flag indicating
that there is no route to the destination.
traceroute 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 Enter ESC character plus C or c to interrupt 1 2001:0DB8::206:2aff:fe66:c800 (2001:0DB8::206:2aff:fe66:c800) 3 ms !R * 2 ms !R
Usage:
- The range of port numbers the traceroute command uses is normally not valid but can be changed if the target host is using nonstandard UDP port.
- To interrupt traceroute command processing, enter the ESC character plus the letter C or c. For example, if the ESC character for the UNIX shell is $, enter $c or $C.
- 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.