The TSO PING command: Send an echo request

The TSO PING command sends an echo request to a foreign node (remote host) to determine whether the node is accessible.

When a response to a Ping command is received, the elapsed time is displayed. The time does not include the time spent communicating between the user and the TCP/IP address space.

For information about the remote Ping function, which enables a user at one host to determine the response time between two remote hosts using SNMP, see Managing TCP/IP network resources with SNMP.

Format


>>-PING--+- host_name--+---------------+-+---------------------><
         |             '-(--| Option |-' |   
         +- Help-------------------------+   
         '- ?----------------------------'   

Option

   .--------------------------.   
   V                          |   
|----+----------------------+-+---------------------------------|
     +-Addrtype--+-ipv4-+---+     
     |           '-ipv6-'   |     
     |        .-1----.      |     
     +-Count--+------+------+     
     |        '-echo-'      |     
     +-Intf-- interface-----+     
     |         .-256---.    |     
     +-Length--+-------+----+     
     |         '-bytes-'    |     
     +-NOName---------------+     
     +-PMTU--+-yes----+-----+     
     |       '-ignore-'     |     
     +-Srcip-- srcip--------+     
     +-TCP-- tcpname--------+     
     |          .-10------. |     
     +-Timeout--+---------+-+     
     |          '-seconds-' |     
     '-Verbose--------------'

Note: The minimum abbreviation for each parameter is shown in uppercase letters.

Parameters

host_name

Specifies the host to which you want to send the echo request. 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. The command uses the first IP address that is returned by the resolver. The ADDRTYPE option can be used to determine whether the command requests only IPv4 or only IPv6 IP addresses from the resolver. If the ADDRTYPE option is not specified, 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 ADDRTYPE, INTF, or SRCIP are not 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). The examples that follow include 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 that is 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.

Addrtype ipv4 | ipv6

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.

Count echo

Sets the number of echo requests that are sent to the host. If you do not specify the Count parameter, the default value 1 is used, unless the Verbose parameter is specified. When the Verbose parameter is specified but the Count parameter is not specified, the default value is 3.

If echo is not specified, an error occurs. The echo value must be in the range 0 - 2³¹ minus 1, which is 2147483647. If echo is 0, the Ping command sends echo requests continually. To stop the Ping command, press PA1.

Restriction: If you specify the Verbose parameter, you cannot specify the value 0 for the Count parameter.

Intf interface

Specifies the local interface, interface, over which the packets are sent. The interface is either a name with a maximum of 16 bytes 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 interface value is used to determine whether the host name is resolved to an IPv4 or IPv6 IP address.

When this parameter is specified, Ping establishes affinity to either the default TCP/IP stack or the stack specified on the TCP parameter. The specified interface must be defined to the stack to which Ping 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 MULTIPATH or 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.

Length bytes

Sets the number of data bytes for the echo request. If a bytes value is not specified, an error occurs. If you do not specify the Length parameter, the default value 256 is used. The number of bytes must be in the range 8 - 65 487. A minimum of 8 data bytes is needed for a time stamp value, which the Ping command uses to correlate echo requests to echo replies.

For IPv4 destinations, the total length of the outbound echo request packet includes the length of an IPv4 IP header (20 bytes), the length of an ICMP header (8 bytes), and the data length specified by the Length parameter. Depending on your TCP/IP stack configuration, the TCP/IP stack might add additional IP header options to the IP header created by the Ping command before the echo request packet is sent.

For IPv6 destinations, the total length of the outbound echo request packet includes the length of an IPv6 IP header (40 bytes), the length of an ICMPv6 header (8 bytes), and the data length specified by the Length parameter. Depending on your TCP/IP stack configuration, the TCP/IP stack might add additional IPv6 extension headers to the packet that is created by the Ping command, before the echo request packet is sent.

NOName

Specifies that the Ping command should not resolve IP addresses to host names for ICMP/ICMPv6 messages received because of path MTU problems. This parameter is in effect only if the PTMU parameter was also specified; otherwise it is ignored. Specifying this parameter results in the Ping command displaying only the IP address of the host where fragmentation is needed. For example:

    Ping #n needs fragmentation at: ipaddress

PMTU yes | ignore

This parameter can be used for diagnosing path maximum transmission unit (MTU) problems in the network. It prevents the outbound echo request packets from being fragmented and specifies what kind of path MTU discovery support should be used with the Ping command. For IPv4, path MTU discovery support is enabled by specifying the PATHMTUDISCOVERY parameter on the IPCONFIG profile statement. For IPv6, path MTU discovery support is enabled by default. The values for this option are not case sensitive.

If the echo request packets need to be fragmented at the local host or in the network, the Ping command displays the host name and IP address of the host where fragmentation is required.

yes

Specifies that the outbound echo request packets are not fragmented at the local host or in the network and that the MTU value, determined by path MTU discovery for the destination, is used.

If path MTU discovery is enabled and has already determined an MTU value for the destination, and the length of the Ping echo request packet is larger than this MTU size, then the local TCP/IP stack does not send out the packet. In this case, The Ping command displays one of the local stack's IP addresses as the host address where fragmentation is needed, and the next-hop MTU value displayed by the Ping command is the current path MTU value to the destination. For Ping commands to IPv4 destinations, the Ping command processing itself does not cause path MTU discovery support to be triggered for the destination. For IPv4, only TCP processing causes path MTU discovery support to be triggered.
If path MTU discovery is not enabled or has not already determined a path MTU value for the destination, and the Ping echo request packet exceeds the configured route MTU selected for this packet, then the local TCP/IP stack does not send out the packet. In this case, the Ping command displays one of the local stack's IP addresses as the address of the host where fragmentation is needed, and the next-hop MTU value displayed by the Ping command is that of the route selected for the Ping packet.
If the Ping request fails because the echo request packet requires fragmentation at some point in the network, the Ping command displays the IP address where fragmentation is required and displays the next-hop MTU value, if it was provided.

ignore

Specifies that the outbound echo request packets are not fragmented at the local host or in the network, and that any MTU values determined by path MTU discovery for the destination, are ignored.

If path MTU discovery determines an MTU value for the destination, and the length of the Ping echo request packet is larger than this MTU size, specifying the value ignore causes the TCP/IP stack to ignore the path MTU value and attempt to send out the packet. As long as the echo request packet length does not exceed the configured route MTU that is selected for this packet, you can use the ignore value to determine where in the network the original MTU problem occurred. In this case, the Ping command displays the IP address where fragmentation needs to occur and displays the path MTU value, if it was provided.
If the Ping echo request packet exceeds the configured route MTU selected for this packet, then the local TCP/IP stack does not send out the packet. In this case, the Ping command displays one of the local stack's IP addresses as the address of the host where fragmentation is needed and the next-hop MTU value displayed by the Ping command is that of the route selected for the Ping packet.

If the Ping command receives an ICMP/ICMPv6 error message indicating that an echo request packet requires fragmentation, the Ping command displays the following output based on this message:

    Ping #n needs fragmentation at: host_name (ipaddress)

If the host name resolution fails, the Ping command displays the following output:

    Ping #n needs fragmentation at: ipaddress (ipaddress)

You can use the NOName parameter to request that the Ping command display only the host IP address, without resolving it to a host name.

If the host returned the next-hop MTU size in the ICMP/ICMPv6 message, then this MTU size is also displayed:

    Next-hop MTU size is nnnnn

If the MTU size is not displayed, you can use the Length parameter to vary the size of the echo request packet, to determine the MTU of the network.

MULTIPATH PERPACKET considerations: When the MULTIPATH PERPACKET parameter is in effect and equal-cost routes are configured to the Ping destination host, the smallest MTU value of all the equal-cost routes is used as the largest packet size that can be sent, even if some of the equal-cost routes could support a larger packet size.

Srcip srcip

Specifies the source IP address, srcip. 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 is resolved to an IPv4 or IPv6 IP address.

Restriction: You cannot specify scope information for the source IP address.

TCP tcpname

Specifies the name of the TCP/IP stack that is to be used.

The tcpname is an 8-byte procedure name that is used to start the TCP/IP stack. When the S 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.

Timeout seconds

Sets the number of seconds that the Ping command waits for a response. If you do not specify the Timeout parameter, the default of 10 seconds is used. If a seconds value is not specified, an error occurs. The number of seconds must be in the range 1 - 100.

Verbose

Provides additional details about the received echo replies and a statistics summary.

If you do not specify the Verbose and Count parameters, then the default count of echo requests is 1. If you specify the Verbose parameter without the Count parameter, then the default value is 3. If you specify both the Verbose and Count parameters, then the number of echo requests is the value that is specified in the Count parameter.

Restriction: If you specify the value 0 for the Count parameter, you cannot specify the Verbose parameter.

See the examples that follow for the format of the Ping output when the Verbose parameter is specified. See the response descriptions that follow for the explanation of the fields that are used in the verbose information.

Help or question mark (?)

Provides help information about the Ping command. You cannot place the HELP parameter on the Ping command line with other parameters.

Usage

To stop or interrupt the Ping command, press the PA1 or ATTN key.
You can place more than one parameter on the Ping command line; however, the HELP parameter is an exception and cannot be placed on the Ping command line with other parameters.
To authorize the Ping command to use RAW sockets, add the command name, PING, 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. If Ping is not authorized to use RAW sockets, Ping will fail with message EZZ3115I Unable to open RAW socket: EDC5139I Operation not permitted. For other authorization considerations, see MVS-related considerations information in the z/OS Communications Server: IP Configuration Guide.

Restrictions:

Ping commands to a remote host might fail if there is a firewall between the two systems, even if the host is reachable using other commands.
Ping commands to a remote host might be unable to detect path MTU information if there is an IPSec tunnel at any point between the two systems, even if the host is reachable using other commands. For more information about Ping PMTU interactions with IPSec tunnels, see Resolving TSO PING and z/OS UNIX ping command problems.

Examples

IPv4

ping mvs098
CS V2R1: Pinging host MVS098 (9.67.113.11)
Ping #1 response took 0.002 seconds.

IPv6

ping linuxipv62.tcp
CS V2R1: Pinging host LINUXIPV62.TCP.raleigh.ibm.com
at IPv6 address 2001:0db8::1:9:67:114:44
Ping #1 response took 0.002 seconds.

IPv4 with the value ignore specified for the PMTU parameter and fragmentation needed out in the network. The hosts in this IPv4 network do not provide a next-hop MTU value when sending the ICMP error message. This example represents a network where there are multiple network paths to the destination.
```
ping hosta (count 4 pmtu ignore length 2500
CS V2R1: Pinging host hosta.test.ibm.com (9.56.99.99)   
Ping #1 needs fragmentation at:hoste.test.ibm.com 9.56.22.22
Ping #2 response took 0.002 seconds.
Ping #3 response took 0.001 seconds.
Ping #4 needs fragmentation at: hoste.test.ibm.com 9.56.22.22
```

IPv4 with the value ignore specified for the PMTU parameter, the NOName parameter specified, and fragmentation needed out in the network. The hosts in this IPv4 network do not provide a next-hop MTU value when sending the ICMP error message.

ping hosta (count 4 pmtu ignore noname length 2500
CS V2R1: Pinging host hosta.test.ibm.com (9.56.99.99)
Ping #1 needs fragmentation at: (9.56.22.22)
Ping #2 response took 0.002 seconds.
Ping #3 response took 0.001 seconds.
Ping #4 needs fragmentation at: (9.56.33.33)

IPv4 with the Verbose parameter specified.

ping hosta (verbose
CS V2R1: Pinging host hosta.test.ibm.com (9.56.99.99) 
with 256 bytes of ICMP data
Ping #1 from 9.56.99.99: bytes=264 seq=1 ttl=51 time=1.08 ms
Ping #2 from 9.56.99.99: bytes=264 seq=2 ttl=51 time=1.35 ms
Ping #3 from 9.56.99.99: bytes=264 seq=3 ttl=51 time=1.58 ms

Ping statistics for hosta.test.ibm.com (9.56.99.99)
  Packets: Sent=3, Received=3, Lost=0 (0% loss)
  Approximate round trip times in milliseconds:
  Minimum=1.08 ms, Maximum=1.58 ms, Average=1.34 ms, StdDev=0.26 ms

IPv4 with the parameters Verbose, Length, and PMTU specified with the value ignore but with the Ping failures (timeout and fragmentation needed errors)

ping hosta (verbose length 2500 PMTU ignore 
CS V2R1: Pinging host hosta.test.ibm.com (9.56.99.99)
with 2500 bytes of ICMP data 
Ping #1 needs fragmentation at: hoste.test.ibm.com (9.56.22.22)
Ping #2 timed out
Ping #3 timed out

Ping statistics for hosta.test.ibm.com (9.56.99.99) 
  Packets: Sent=3, Received=0, Lost=3 (100% loss)

IPv6 with the value ignore specified for the PMTU parameter, the NOName parameter specified, and fragmentation needed out in the network.

ping hostipv6 (count 4 pmtu ignore noname length 3000
CS V2R1: Pinging host hostipv6.raleigh.ibm.com 
at IPv6 address 50c9:c2d4:0:5:9:6b00:111a:1
Ping #1 needs fragmentation at: 50c9:c2d4:0:3:9:6b00:111a:250e
  Next-hop MTU size is 1500
Ping #2 response took 0.002 seconds.
Ping #3 response took 0.001 seconds.
Ping #4 needs fragmentation at: 50c9:c2d4:0:3:9:6b00:111a:250e
  Next-hop MTU size is 1500

IPv6 with the value yes specified for the PMTU parameter. Fragmentation needed, first out in the network, and then at the local TCP/IP stack because of Path MTU Discovery.

ping hostipv6 (count 4 pmtu yes length 3000
CS V2R1: Pinging host hostipv6.raleigh.ibm.com 
at IPv6 address 50c9:c2d4:0:5:9:6b00:111a:1
Ping #1 needs fragmentation at: hoste.test.ibm.com (50c9:c2d4:0:3:9:6b00:111a:250e)
  Next-hop MTU size is 1500
Ping #2 needs fragmentation at: local.host (50c9:c2d4:0:6:1:6b00:111a:0001)
  Next-hop MTU size is 1500
Ping #3 needs fragmentation at: local.host (50c9:c2d4:0:6:1:6b00:111a:0001)
  Next-hop MTU size is 1500 
Ping #4 needs fragmentation at: local.host (50c9:c2d4:0:6:1:6b00:111a:0001) 
  Next-hop MTU size is 1500

IPv6 with the Count, Length, and Verbose parameters specified.

ping hostipv6 (count 5 length 8944 verbose 
CS V2R1: Pinging host hostipv6.raleigh.ibm.com 
at IPv6 address 50c9:c2d4:0:5:9:6b00:111a:1
with 8944 bytes of ICMP data
Ping #1 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=1 hoplim=51 time=1.71 ms 
Ping #2 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=2 hoplim=51 time=1.52 ms
Ping #3 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=3 hoplim=51 time=1.78 ms
Ping #4 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=4 hoplim=51 time=1.88 ms
Ping #5 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=5 hoplim=51 time=2.25 ms

Ping statistics for hostipv6.raleigh.ibm.com 
at IPv6 address 50c9:c2d4:0:5:9:6b00:111a:1
  Packets: Sent=5, Received=5, Lost=0 (0% loss)
  Approximate round trip times in milliseconds:
  Minimum=1.52 ms, Maximum=2.25 ms, Average=1.83 ms, StdDev=0.24 ms

IPv6 with the Count, Length, and Verbose parameters specified, but with mixed Ping results (success and failure).

ping hostipv6 (count 5 length 8944 verbose 
CS V2R1: Pinging host hostipv6.raleigh.ibm.com 
at IPv6 address 50c9:c2d4:0:5:9:6b00:111a:1
with 8944 bytes of ICMP data
Ping #1 timed out
Ping #2 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=2 hoplim=51 time=1.51 ms
Ping #3 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=3 hoplim=51 time=1.68 ms
Ping #4 timed out 
Ping #5 from 50c9:c2d4:0:5:9:6b00:111a:1: bytes=8952 seq=5 hoplim=51 time=1.64 ms

Ping statistics for hostipv6.raleigh.ibm.com 
at IPv6 address 50c9:c2d4:0:5:9:6b00:111a:1
  Packets: Sent=5, Received=3, Lost=2 (40% loss)
  Approximate round trip times in milliseconds:
  Minimum=1.51 ms, Maximum=1.68 ms, Average=1.61 ms, StdDev=0.10 ms

IPv6 link-local with scope information.

ping fe80::12:1:2%mpc6221            
CS V2R1: Pinging host FE80::12:1:2%MPC6221          
at IPv6 address fe80::12:1:2                        
Ping #1 response took 0.028 seconds.

Response description:

The Ping command displays one response output line for every echo request packet that is sent. The default response output line displays the number of elapsed seconds for the echo reply that was received and the number of bytes that were sent for the data portion of the echo request packet.

When the Verbose parameter is specified, the following information is displayed:

Echo reply details

Ping #n from address: Echo reply process counter and IP address of the echo reply sender.
bytes=nn: The number of bytes for the ICMP packet (ICMP header and data portions) from the echo reply.
seq=nn: ICMP sequence number of the echo reply.
ttl=nn (for IPv4): Time-to-live value for the echo reply.
hoplim=nn (for IPv6): Hop limit value for the echo reply.
time=nn ms: Round-trip time (RTT), in milliseconds.

Ping statistics summary

Sent

Total number of echo request packets sent.

Received

Total number of echo reply packets received.

Lost (n% loss)

Total number of lost echo packets (echo reply packets that were not received) and the percentage of packets that were lost.

Approximate round trip times (RTT) in milliseconds

Minimum: Minimum RTT value of Ping requests that were sent.
Maximum: Maximum RTT value of Ping requests that were sent.
Average: Average RTT value of Ping requests that were sent.
StdDev: Standard deviation of all RTT values of Ping requests that were sent.