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.

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 - 2³¹ 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:

• 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.

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

• 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.