293 useradd/del/mod should be ZFS-aware

[illumos-gate.git] / usr / src / man / man1m / ping.1m

'\" te
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 1989 AT&T
.\" Copyright 2015, Joyent, Inc.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH PING 1M "May 21, 2015"
.SH NAME
ping \- send ICMP (ICMP6) ECHO_REQUEST packets to network hosts
.SH SYNOPSIS
.LP
.nf
\fB/usr/sbin/ping\fR \fIhost\fR [\fItimeout\fR]
.fi

.LP
.nf
\fB/usr/sbin/ping\fR \fB-s\fR [\fB-l\fR | \fB-U\fR] [\fB-abdDLnrRv\fR] [\fB-A\fR \fIaddr_family\fR]
     [\fB-c\fR \fItraffic_class\fR] [\fB-g\fR \fIgateway\fR [\fB-g\fR \fIgateway\fR...]]
     [\fB-N\fR \fInext_hop_router\fR] [\fB-F\fR \fIflow_label\fR] [\fB-I\fR \fIinterval\fR]
     [\fB-i\fR \fIinterface\fR] [\fB-P\fR \fItos\fR] [\fB-p\fR \fIport\fR] [\fB-t\fR \fIttl\fR] \fIhost\fR
     [\fIdata_size\fR] [\fInpackets\fR]
.fi

.SH DESCRIPTION
.LP
The utility \fBping\fR utilizes the \fBICMP\fR (\fBICMP6\fR in IPv6) protocol's
\fBECHO_REQUEST\fR datagram to elicit an \fBICMP\fR (\fBICMP6\fR)
\fBECHO_RESPONSE\fR from the specified \fIhost\fR or network \fIgateway\fR. If
\fIhost\fR responds, \fBping\fR will print:
.sp
.in +2
.nf
\fIhost\fR is alive
.fi
.in -2
.sp

.sp
.LP
on the standard output and exit. Otherwise, after \fItimeout\fR seconds, it
will write:
.sp
.in +2
.nf
no answer from \fIhost\fR
.fi
.in -2
.sp

.sp
.LP
The default value of \fItimeout\fR is \fB20\fR seconds.
.sp
.LP
When you specify the s flag, sends one datagram per second (adjust with
\fB-I\fR) and prints one line of output for every \fBECHO_RESPONSE\fR that it
receives. \fBping\fR produces no output if there is no response. In this second
form, \fBping\fR computes round trip times and packet loss statistics; it
displays a summary of this information upon termination or timeout. The default
\fIdata_size\fR is \fB56\fR bytes, or you can specify a size with the
\fIdata_size\fR command-line argument. If you specify the optional
\fInpackets\fR, \fBping\fR sends \fBping\fR requests until it either sends
\fInpackets\fR requests or receives \fInpackets\fR replies.
.sp
.LP
When using \fBping\fR for fault isolation, first \fBping\fR the local host to
verify that the local network interface is running.
.SH OPTIONS
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-A\fR\ \fIaddr_family\fR\fR
.ad
.RS 24n
Specify the address family of the target host. \fIaddr_family\fR can be either
\fBinet\fR or \fBinet6\fR. Address family determines which protocol to use. For
an argument of \fBinet\fR, IPv4 is used. For \fBinet6\fR, IPv6 is used.
.sp
By default, if the name of a host is provided, not the literal \fBIP\fR
address, and a valid IPv6 address exists in the name service database,
\fBping\fR will use this address. Otherwise, if the name service database
contains an IPv4 address, it will try the IPv4 address.
.sp
Specify the address family \fBinet\fR or \fBinet6\fR to override the default
behavior. If the argument specified is \fBinet\fR, \fBping\fR will use the IPv4
address associated with the host name. If none exists, \fBping\fR will state
that the host is unknown and exit. It does not try to determine if an IPv6
address exists in the name service database.
.sp
If the specified argument is \fBinet6\fR, \fBping\fR uses the IPv6 address that
is associated with the host name. If none exists, \fBping\fR states that the
host is unknown and exits.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 24n
Don't allow probe packets to be fragmented. If the packet size exceeds the MTU
of a gateway it passes through, the gateway will reject it.
.RE
 
.sp
.ne 2
.na
\fB\fB-F\fR\ \fIflow_label\fR\fR
.ad
.RS 24n
Specify the flow label of probe packets. The value must be an integer in the
range from 0 to 1048575. This option is valid only on IPv6.
.RE

.sp
.ne 2
.na
\fB\fB-I\fR \fIinterval\fR\fR
.ad
.RS 24n
Turn on the statistics mode and specify the interval between successive
transmissions. The default is one second. See the discussion of the \fB-s\fR
option. The minimum interval is 0.01 seconds. It is an error to specify
a smaller interval.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 24n
Turn off loopback of multicast packets. Normally, members are in the host group
on the outgoing interface, a copy of the multicast packets will be delivered to
the local machine.
.RE

.sp
.ne 2
.na
\fB\fB-N\fR \fInext_hop_router\fR\fR
.ad
.RS 24n
Specify a next-hop router so that the probe packet goes through the specified
router along its path to the target host. This option essentially bypasses the
system routing table and leaves the probe packet header unmodified. Only one
next-hop router can be specified.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\ \fItos\fR\fR
.ad
.RS 24n
Set the type of service (\fItos\fR) in probe packets to the specified value.
The default is zero. The value must be an integer in the range from 0 to 255.
Gateways also in the path can route the probe packet differently, depending
upon the value of \fItos\fR that is set in the probe packet. This option is
valid only on IPv4.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 24n
Record route. Sets the IPv4 record route option, which stores the route of the
packet inside the IPv4 header. The contents of the record route are only
printed if the \fB-v\fR and \fB-s\fR options are given. They are only set on
return packets if the target host preserves the record route option across
echos, or the \fB-l\fR option is given. This option is valid only on IPv4.
.RE

.sp
.ne 2
.na
\fB\fB-U\fR\fR
.ad
.RS 24n
Send \fBUDP\fR packets instead of \fBICMP\fR (\fBICMP6\fR) packets. \fBping\fR
sends \fBUDP\fR packets to consecutive ports expecting to receive back
\fBICMP\fR (\fBICMP6\fR) \fBPORT_UNREACHABLE\fR from the target host.
.RE

.sp
.ne 2
.na
\fB\fB-a\fR\fR
.ad
.RS 24n
\fBping\fR all addresses, both IPv4 and IPv6, of the multihomed destination.
The output appears as if \fBping\fR has been run once for each \fBIP\fR address
of the destination. If this option is used together with \fB-A\fR, \fBping\fR
probes only the addresses that are of the specified address family. When used
with the \fB-s\fR option and \fInpackets\fR is not specified, \fBping\fR
continuously probes the destination addresses in a round robin fashion. If
\fInpackets\fR is specified, \fBping\fR sends \fInpackets\fR number of probes
to each \fBIP\fR address of the destination and then exits.
.RE

.sp
.ne 2
.na
\fB\fB-b\fR\fR
.ad
.RS 24n
Bypass the global IPsec policy and send and receive packets in the clear for
this connection only. This option can be used to troubleshoot network
connectivity independent of IPsec. Because this option bypasses system-wide
policy for this connection, it can only be used by superuser or a user granted
the sys_net_config privilege.
.RE

.sp
.ne 2
.na
\fB\fB-c\fR\ \fItraffic_class\fR\fR
.ad
.RS 24n
Specify the traffic class of probe packets. The value must be an integer in the
range from 0 to 255. Gateways along the path can route the probe packet
differently, depending upon the value of \fItraffic_class\fR set in the probe
packet. This option is valid only on IPv6.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 24n
Set the \fBSO_DEBUG\fR socket option.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\ \fIgateway\fR\fR
.ad
.RS 24n
Specify a loose source route gateway so that the probe packet goes through the
specified host along the path to the target host. The maximum number of
gateways is 8 for IPv4 and 127 for IPv6. Note that some factors such as the
link \fBMTU\fR can further limit the number of gateways for IPv6.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR \fIinterface_address\fR\fR
.ad
.RS 24n
Specify the outgoing interface address to use for multicast packets for IPv4
and both multicast and unicast packets for IPv6. The default interface address
for multicast packets is determined from the (unicast) routing tables.
\fIinterface_address\fR can be a literal \fBIP\fR address, for example,
\fB10.123.100.99\fR, or an interface name, for example, \fBeri0\fR, or an
interface index, for example \fB2\fR.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 24n
Use to send the probe packet to the given host and back again using loose
source routing. Usually specified with the \fB-R\fR option. If any gateways are
specified using \fB-g\fR, they are visited twice, both to and from the
destination. This option is ignored if the \fB-U\fR option is used.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 24n
Show network addresses as numbers. \fBping\fR normally does a reverse name
lookup on the IP addresses it extracts from the packets received. The \fB-n\fR
option blocks the reverse lookup, so \fBping\fR prints IP addresses instead of
host names.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\ \fIport\fR\fR
.ad
.RS 24n
Set the base \fBUDP\fR \fIport\fR number used in probes. This option is used
with the \fB-U\fR option. The default base \fIport\fR number is 33434. The
\fBping\fR utility starts setting the destination port number of \fBUDP\fR
packets to this base and increments it by one at each probe.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 24n
Bypass the normal routing tables and send directly to a host on an attached
network. If the host is not on a directly attached network, an error is
returned. This option can be used to \fBping\fR a local host through an
interface that has been dropped by the router daemon. See \fBin.routed\fR(1M).
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 24n
Send one datagram per second and collect statistics.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\ \fIttl\fR\fR
.ad
.RS 24n
Specify the IPv4 time to live, or IPv6 hop limit, for unicast and multicast
packets. The default time to live (hop limit) for unicast packets can be set
with the \fBndd\fR module, \fB/dev/icmp\fR, using the \fBicmp_ipv4_ttl\fR
variable for IPv4 and the \fBicmp_ipv6_hoplimit\fR variable for IPv6. The
default time to live (hop limit) for multicast is one hop. See \fBEXAMPLES\fR.
For further information, see\fBndd\fR(1M).
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 24n
Verbose output. List any \fBICMP\fR (\fBICMP6\fR) packets, other than replies
from the target host.
.RE

.SH OPERANDS
.ne 2
.na
\fB\fIhost\fR\fR
.ad
.RS 8n
The network host
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBping\fR With IPv6
.sp
.LP
This example shows \fBping\fR sending probe packets to all the IPv6 addresses
of the host \fBxyz\fR, one at a time. It sends an \fBICMP6\fR
\fBECHO_REQUEST\fR every second until the user interrupts it.

.sp
.in +2
.nf
istanbul% \fBping -s -A inet6 -a xyz\fR
PING xyz: 56 data bytes
64 bytes from xyz (4::114:a00:20ff:ab3d:83ed): icmp_seq=0. time=0.479 ms
64 bytes from xyz (fec0::114:a00:20ff:ab3d:83ed): icmp_seq=1. time=0.843 ms
64 bytes from xyz (4::114:a00:20ff:ab3d:83ed): icmp_seq=2. time=0.516 ms
64 bytes from xyz (fec0::114:a00:20ff:ab3d:83ed): icmp_seq=3. time=4.943 ms
64 bytes from xyz (4::114:a00:20ff:ab3d:83ed): icmp_seq=4. time=0.485 ms
64 bytes from xyz (fec0::114:a00:20ff:ab3d:83ed): icmp_seq=5. time=2.201 ms
^C
----xyz PING Statistics----
6 packets transmitted, 6 packets received, 0% packet loss
round-trip (ms)  min/avg/stddev = 0.479/1.583/4.943/1.823
.fi
.in -2
.sp

.LP
\fBExample 2 \fRUsing \fBndd\fR to Set the \fBicmp_ipv6_hoplimit\fR
.sp
.LP
This example shows the \fBndd\fR module, \fB/dev/icmp\fR, used to set the
\fBicmp_ipv6_hoplimit\fR.

.sp
.in +2
.nf
# ndd -set /dev/icmp icmp_ipv6_hoplimit 100
.fi
.in -2
.sp

.SH EXIT STATUS
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 12n
Successful operation; the machine is alive.
.RE

.sp
.ne 2
.na
\fBnon-zero\fR
.ad
.RS 12n
An error has occurred. Either a malformed argument has been specified, or the
machine was not alive.
.RE

.SH SEE ALSO
.LP
\fBifconfig\fR(1M), \fBin.routed\fR(1M), \fBndd\fR(1M), \fBnetstat\fR(1M),
\fBrpcinfo\fR(1M), \fBtraceroute\fR(1M), \fBattributes\fR(5), \fBicmp\fR(7P),
\fBicmp6\fR(7P)

.SH DIAGNOSTICS
.ne 2
.na
\fB\fBping: warning: ICMP responses received, but name service lookups
are taking a while. Use ping -n to disable name service lookups.\fB\fB
.ad
.sp .6
.RS 4n
When the
.B -n
flag is not specified,
.B ping
tries to lookup the name corresponding to the IP address that it
received via name services. If name services are unavailable, it may
take time before the system properly times out the name service lookups.
As a result, it may appear that no ICMP replies are being received when
they in fact are. This diagnostic indicates that this has occurred and
indicates that there are valid responses and that using the
.B -n
flag will stop this from occurring.
.RE

.sp
.ne 2
.na
\fB\fBping: warning: timing accuracy diminished -- setsockopt
SO_TIMESTAMP failed\fR\fR
.ad
.sp .6
.RS 4n
By default, the system attempts to use the
.B SO_TIMESTAMP
socket option to allow for more accurate time stamps that reflect when
the ICMP echo replies were received by the system as opposed to when
they were received by the
.B ping
command. These differences may occur because an operator stopped the
process or because
.B ping
was blocked up behind a name service look up. When this diagnostic is
emitted, the
.B ping
command will continue to function, but it will be doing the time
stamping itself, which may cause the timing intervals reported to be
longer than they actually are.
.RE