The z/OS UNIX ping command: Send an echo request

The z/OS® UNIX 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.
Note: ping is a synonym for the oping command in the z/OS UNIX shell. The oping command syntax is the same as that for the ping command.

Format

Read syntax diagramSkip visual syntax diagram ping Option host_name -h -?
Option
Read syntax diagramSkip visual syntax diagram -Aipv4ipv6 -c1echo -i interface -l256bytes -n -Pyesignore -p tcpname -s srcip -t10seconds -v

Parameters

This section describes 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. Use the -A option to specify whether the command requests only IPv4 or only IPv6 IP addresses from the resolver. If you do not specify the -A option, 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 -A, -i, or -s options are specified, the command does not request a specific type of IP address from the resolver and 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 that is used as the scope information has been defined to more than one TCP/IP stack, you must specify the -p 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.
-A 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 -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.

-c echo
Sets the number of echo requests that are sent to the host. If you do not specify the -c parameter, the default value 1 is used unless the -v parameter is specified. When the -v parameter is specified but the -c parameter is not specified, the default value is 3. If an echo value is not specified, an error occurs. The echo value must be in the range 0 - 231 minus 1, which is 2147483647. If echo is 0, the Ping command sends echo requests continually. To stop the Ping command, see Usage.

Restriction: If you specify the -v parameter, you cannot specify the value 0 for the -c parameter.

-h or -question mark (?)
Provides help information about the Ping command. You cannot place the -h or -? parameter on the Ping command line with other parameters.
-i 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 -A 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 -p 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 -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 MULTIPATH or IPCONFIG6 MULTIPATH profile statement, by bypassing the outbound path selection algorithm for the packets.
Restriction:

Restriction:

-l 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 -l 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 Ping 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 -l 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 -l parameter. Depending on your TCP/IP stack configuration, the TCP/IP stack might add additional IPv6 extension headers to the packet created by the Ping command, before the echo request packet is sent.
-n
Specifies that the Ping command should not resolve IP addresses to host names for ICMP/ICMPv6 messages received due to Path MTU problems. This parameter is in effect only if the -P 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
-P 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.
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, are used.
  • If path MTU discovery 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 address of the host 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 active, 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 that is 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 needs to be fragmented at some point in the network, the Ping command displays the IP address where fragmentation needs to occur 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 had determined an MTU value for the destination, and the length of the Ping echo request packet is larger than this MTU size, specifying a value of ignore enables the Ping echo request to be sent out by the local TCP/IP stack, 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. 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 needed to be fragmented, 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 -n parameter to request that the Ping command display only the host name and its IP address of the host, 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, in order to determine the MTU of the network.

MULTIPATH PERPACKET considerations: When the MULTIPATH PERPACKET option 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.

-p tcpname
Specifies the name of the TCP/IP stack to be used.

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

-s 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 -A 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.

-t seconds
Sets the number of seconds that the Ping command waits for a response. If you do not specify the -t parameter, the default of 10 seconds is used. If the seconds value is not specified, an error occurs. The number of seconds specified must be in the range 1 - 100.
-v
Provides additional details about the received echo replies and a statistics summary.

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

Restriction: If you specify the value 0 for the -c parameter, you cannot specify the -v parameter.

See the examples that follow for the format of Ping command output when the -v parameter is specified. See the responses that follow for an explanation of the fields that are used in the verbose information.

Usage

This section describes usage.
  • To stop or interrupt the Ping command, press Ctrl c. The interrupt key can be changed by using the OMVS ESCAPE command in the z/OS UNIX shell, or the stty command for the RAW shell. For more information about OMVS and stty commands,see the z/OS UNIX System Services Command Reference.
  • You can place more than one parameter on the Ping command line; however, the -h and -? parameters are exceptions and cannot be placed on the Ping command line with other parameters.
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 -P interactions with IPSec tunnels, see Resolving TSO PING and z/OS UNIX ping command problems.

Examples

This section describes examples.
  • IPv4
    ping mvs098
    CS V2R4: Pinging host mvs098 (9.67.113.11)  
    Ping #1 response took 0.002 seconds.
  • IPv6
    ping linuxipv62.tcp
    CS V2R4: 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 -P 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 -c 4 -l 2500 -P ignore  hosta             
    CS V2R4: Pinging host hosta.test.ibm.com (9.42.99.99)   
    Ping #1 needs fragmentation at: hoste.test.ibm.com 9.42.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.42.22.22
  • IPv4 with the -v parameter specified.
    ping -v hosta 
    CS V2R4: 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 -v, -l, and -P with value of ignore but with the Ping failures (timeout and fragmentation needed errors)
    ping -v -l 2500 -P ignore hosta 
    CS V2R4: 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 -P parameter and fragmentation needed out in the network.
    ping -c 4 -l 3000 -P ignore -n  hostipv6 
    CS V2R4: 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 -P parameter and the -n parameter specified. Fragmentation needed first out in the network and then at the local TCP/IP stack because of path MTU discovery.
    ping -c 4 -l 3000 -P yes -n  hostipv6
    CS V2R4: 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 -c , -l , and -v parameters specified.
    ping -c 5 -l 8944 -v hostipv6  
    CS V2R4: 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 -c , -l , and -v parameters specified, but with mixed Ping results (success and failure).
    ping -c 5 -l 8944 -v hostipv6 
    CS V2R4: 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=5   1 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=5   1 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 V2R4: Pinging host FE80::12:1:2%MPC6221       
    at IPv6 address fe80::12:1:2                     
    Ping #1 response took 0.001 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 -v parameter is specified, the following information is displayed:
Echo reply details
Ping #n from address
Processing echo reply counter and IP address of the echo reply sender.
bytes=nn
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 not received) and the percentage loss.
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.