423 lines
12 KiB
Groff
423 lines
12 KiB
Groff
.\" $KAME: ping6.8,v 1.22 2000/05/31 17:00:07 itojun Exp $
|
|
.\"
|
|
.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. Neither the name of the project nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd May 17, 1998
|
|
.Dt PING6 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ping6
|
|
.Nd send
|
|
.Tn ICMPv6 ECHO_REQUEST
|
|
packets to network hosts
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.\" without ipsec, or new ipsec
|
|
.Op Fl dfHnNqRvw
|
|
.\" old ipsec
|
|
.\" .Op Fl AdEfnNqRvw
|
|
.Bk -words
|
|
.Op Fl a Ar addrtype
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl b Ar bufsiz
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl c Ar count
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl h Ar hoplimit
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl I Ar interface
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl i Ar wait
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl l Ar preload
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl p Ar pattern
|
|
.Ek
|
|
.Bk -words
|
|
.\" new ipsec
|
|
.Op Fl P Ar policy
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl S Ar sourceaddr
|
|
.Ek
|
|
.Bk -words
|
|
.Op Fl s Ar packetsize
|
|
.Ek
|
|
.Bk -words
|
|
.Op Ar hops...
|
|
.Ek
|
|
.Bk -words
|
|
.Ar host
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
uses the
|
|
.Tn ICMPv6
|
|
protocol's mandatory
|
|
.Tn ICMP6_ECHO_REQUEST
|
|
datagram to elicit an
|
|
.Tn ICMP6_ECHO_REPLY
|
|
from a host or gateway.
|
|
.Tn ICMP6_ECHO_REQUEST
|
|
datagrams (``pings'') have an IPv6 header,
|
|
and
|
|
.Tn ICMPv6
|
|
header formatted as documented in RFC2463.
|
|
The options are as follows:
|
|
.Bl -tag -width Ds
|
|
.\" old ipsec
|
|
.\" .It Fl A
|
|
.\" Enables transport-mode IPsec authentication header
|
|
.\" .Pq experimental .
|
|
.It Fl a Ar addrtype
|
|
Generate ICMPv6 Node Information Node Addresses query, rather than echo-request.
|
|
.Ar addrtype
|
|
must be a string constructed of the following characters.
|
|
.Bl -tag -width Ds -compact
|
|
.It Ic a
|
|
requests all the responder's unicast addresses.
|
|
If the charater is ommited,
|
|
only those addresses which belong to the interface which has the
|
|
responder's address are requests.
|
|
.It Ic c
|
|
requests responder's IPv4-compatible and IPv4-mapped addresses.
|
|
.It Ic g
|
|
requests responder's global-scope addresses.
|
|
.It Ic s
|
|
requests responder's site-local addresses.
|
|
.It Ic l
|
|
requests responder's link-local addresses.
|
|
.It Ic A
|
|
requests responder's anycast addresses.
|
|
Without this character, the responder will return unicast addresses only.
|
|
With this character, the responder will return anycast addresses only.
|
|
Note that the specification does not specify how to get responder's
|
|
anycast addresses.
|
|
This is an experimental option.
|
|
.El
|
|
.It Fl b Ar bufsiz
|
|
Set socket buffer size.
|
|
.It Fl c Ar count
|
|
Stop after sending
|
|
.Pq and receiving
|
|
.Ar count
|
|
.Tn ECHO_RESPONSE
|
|
packets.
|
|
.It Fl d
|
|
Set the
|
|
.Dv SO_DEBUG
|
|
option on the socket being used.
|
|
.\" .It Fl E
|
|
.\" Enables transport-mode IPsec encapsulated security payload
|
|
.\" .Pq experimental .
|
|
.It Fl f
|
|
Flood ping.
|
|
Outputs packets as fast as they come back or one hundred times per second,
|
|
whichever is more.
|
|
For every
|
|
.Tn ECHO_REQUEST
|
|
sent a period
|
|
.Dq \&.
|
|
is printed, while for every
|
|
.Tn ECHO_REPLY
|
|
received a backspace is printed.
|
|
This provides a rapid display of how many packets are being dropped.
|
|
Only the super-user may use this option.
|
|
.Bf -emphasis
|
|
This can be very hard on a network and should be used with caution.
|
|
.Ef
|
|
.It Fl H
|
|
Specifies to try reverse-lookup of IPv6 addresses.
|
|
The
|
|
.Nm
|
|
command does not try reverse-lookup unless the option is specified.
|
|
.It Fl h Ar hoplimit
|
|
Set the IPv6 hoplimit.
|
|
.It Fl I Ar interface
|
|
Source packets with the given interface address.
|
|
This flag applies if the ping destination is a multicast address,
|
|
or link-local/site-local unicast address.
|
|
.It Fl i Ar wait
|
|
Wait
|
|
.Ar wait
|
|
seconds
|
|
.Em between sending each packet .
|
|
The default is to wait for one second between each packet.
|
|
This option is incompatible with the
|
|
.Fl f
|
|
option.
|
|
.It Fl l Ar preload
|
|
If
|
|
.Ar preload
|
|
is specified,
|
|
.Nm ping
|
|
sends that many packets as fast as possible before falling into its normal
|
|
mode of behavior.
|
|
Only the super-user may use this option.
|
|
.It Fl n
|
|
Numeric output only.
|
|
No attempt will be made to lookup symbolic names for host addresses.
|
|
.It Fl N
|
|
Probe node information multicast group
|
|
.Pq Li ff02::2:xxxx:xxxx .
|
|
.Ar host
|
|
must be string hostname of the target
|
|
.Pq must not be a numeric IPv6 address .
|
|
Node information multicast group will be computed based on given
|
|
.Ar host ,
|
|
and will be used as the final destination.
|
|
Since node information multicast group is a link-local multicast group,
|
|
destination link needs to be specified by
|
|
.Fl I
|
|
option.
|
|
.It Fl p Ar pattern
|
|
You may specify up to 16
|
|
.Dq pad
|
|
bytes to fill out the packet you send.
|
|
This is useful for diagnosing data-dependent problems in a network.
|
|
For example,
|
|
.Dq Li \-p ff
|
|
will cause the sent packet to be filled with all
|
|
ones.
|
|
.Fl Q
|
|
flag,
|
|
.Nm
|
|
prints out any ICMP error messages caused by its own ECHO_REQUEST
|
|
messages.
|
|
.\" new ipsec
|
|
.It Fl P Ar policy
|
|
.Ar policy
|
|
specifies IPsec policy to be used for the probe.
|
|
.It Fl q
|
|
Quiet output.
|
|
Nothing is displayed except the summary lines at startup time and
|
|
when finished.
|
|
.It Fl R
|
|
Make the kernel believe that the target
|
|
.Ar host
|
|
.Po
|
|
or the first
|
|
.Ar hop
|
|
if you specify
|
|
.Ar hops
|
|
.Pc
|
|
is reachable, by injecting upper-layer reachability confirmation hint.
|
|
The option is meaningful only if the target
|
|
.Ar host
|
|
.Pq or the first hop
|
|
is a neighbor.
|
|
.It Fl S Ar sourceaddr
|
|
Specifies the source address of request packets.
|
|
The source address must be one of the unicast addresses of the sending node.
|
|
If the outgoing interface is specified by the
|
|
.Fl I
|
|
option as well,
|
|
.Ar sourceaddr
|
|
needs to be an address assigned to the specified interface.
|
|
.It Fl s Ar packetsize
|
|
Specifies the number of data bytes to be sent.
|
|
The default is 56, which translates into 64
|
|
.Tn ICMP
|
|
data bytes when combined
|
|
with the 8 bytes of
|
|
.Tn ICMP
|
|
header data.
|
|
You may need to specify
|
|
.Fl b
|
|
as well to extend socket buffer size.
|
|
.It Fl v
|
|
Verbose output.
|
|
.Tn ICMP
|
|
packets other than
|
|
.Tn ECHO_RESPONSE
|
|
that are received are listed.
|
|
.It Fl w
|
|
Generate ICMPv6 Node Information FQDN query, rather than echo-request.
|
|
.Fl s
|
|
has no effect if
|
|
.Fl w
|
|
is specified.
|
|
.It Fl W
|
|
Same as
|
|
.Fl w ,
|
|
but with old packet format based on 03 draft.
|
|
This option is present for backward compatibility.
|
|
.Fl s
|
|
has no effect if
|
|
.Fl w
|
|
is specified.
|
|
.It Ar hops
|
|
IPv6 addresses for intermediate nodes,
|
|
which will be put into type 0 routing header.
|
|
.It Ar host
|
|
IPv6 adddress of the final destination node.
|
|
.El
|
|
.Pp
|
|
When using
|
|
.Nm
|
|
for fault isolation, it should first be run on the local host, to verify
|
|
that the local network interface is up and running.
|
|
Then, hosts and gateways further and further away should be
|
|
.Dq pinged .
|
|
Round-trip times and packet loss statistics are computed.
|
|
If duplicate packets are received, they are not included in the packet
|
|
loss calculation, although the round trip time of these packets is used
|
|
in calculating the round-trip time statistics.
|
|
When the specified number of packets have been sent
|
|
.Pq and received
|
|
or if the program is terminated with a
|
|
.Dv SIGINT ,
|
|
a brief summary is displayed, showing the number of packets sent and
|
|
received, and the minimum, maximum, mean, and standard deviation of
|
|
the round-trip times.
|
|
.Pp
|
|
This program is intended for use in network testing, measurement and
|
|
management.
|
|
Because of the load it can impose on the network, it is unwise to use
|
|
.Nm
|
|
during normal operations or from automated scripts.
|
|
.\" .Sh ICMP PACKET DETAILS
|
|
.\" An IP header without options is 20 bytes.
|
|
.\" An
|
|
.\" .Tn ICMP
|
|
.\" .Tn ECHO_REQUEST
|
|
.\" packet contains an additional 8 bytes worth of
|
|
.\" .Tn ICMP
|
|
.\" header followed by an arbitrary amount of data.
|
|
.\" When a
|
|
.\" .Ar packetsize
|
|
.\" is given, this indicated the size of this extra piece of data
|
|
.\" .Pq the default is 56 .
|
|
.\" Thus the amount of data received inside of an IP packet of type
|
|
.\" .Tn ICMP
|
|
.\" .Tn ECHO_REPLY
|
|
.\" will always be 8 bytes more than the requested data space
|
|
.\" .Pq the Tn ICMP header .
|
|
.\" .Pp
|
|
.\" If the data space is at least eight bytes large,
|
|
.\" .Nm
|
|
.\" uses the first eight bytes of this space to include a timestamp which
|
|
.\" it uses in the computation of round trip times.
|
|
.\" If less than eight bytes of pad are specified, no round trip times are
|
|
.\" given.
|
|
.Sh DUPLICATE AND DAMAGED PACKETS
|
|
.Nm Ping6
|
|
will report duplicate and damaged packets.
|
|
Duplicate packets should never occur when pinging a unicast address,
|
|
and seem to be caused by
|
|
inappropriate link-level retransmissions.
|
|
Duplicates may occur in many situations and are rarely
|
|
.Pq if ever
|
|
a good sign, although the presence of low levels of duplicates may not
|
|
always be cause for alarm.
|
|
Duplicates are expected when pinging a broadcast or multicast address,
|
|
since they are not really duplicates but replies from different hosts
|
|
to the same request.
|
|
.Pp
|
|
Damaged packets are obviously serious cause for alarm and often
|
|
indicate broken hardware somewhere in the
|
|
.Nm ping
|
|
packet's path
|
|
.Pq in the network or in the hosts .
|
|
.Sh TRYING DIFFERENT DATA PATTERNS
|
|
The
|
|
(inter)network
|
|
layer should never treat packets differently depending on the data
|
|
contained in the data portion.
|
|
Unfortunately, data-dependent problems have been known to sneak into
|
|
networks and remain undetected for long periods of time.
|
|
In many cases the particular pattern that will have problems is something
|
|
that does not have sufficient
|
|
.Dq transitions ,
|
|
such as all ones or all zeros, or a pattern right at the edge, such as
|
|
almost all zeros.
|
|
It is not
|
|
necessarily enough to specify a data pattern of all zeros (for example)
|
|
on the command line because the pattern that is of interest is
|
|
at the data link level, and the relationship between what you type and
|
|
what the controllers transmit can be complicated.
|
|
.Pp
|
|
This means that if you have a data-dependent problem you will probably
|
|
have to do a lot of testing to find it.
|
|
If you are lucky, you may manage to find a file that either
|
|
cannot
|
|
be sent across your network or that takes much longer to transfer than
|
|
other similar length files.
|
|
You can then examine this file for repeated patterns that you can test
|
|
using the
|
|
.Fl p
|
|
option of
|
|
.Nm .
|
|
.Sh RETURN VALUES
|
|
.Nm
|
|
returns 0 on success (the host is alive),
|
|
and non-zero if the arguments are incorrect or the host is not responding.
|
|
.Sh SEE ALSO
|
|
.Xr netstat 1 ,
|
|
.Xr ifconfig 8 ,
|
|
.Xr ping 8 ,
|
|
.Xr routed 8 ,
|
|
.Xr traceroute 8 ,
|
|
.Xr traceroute6 8
|
|
.Rs
|
|
.%A A. Conta
|
|
.%A S. Deering
|
|
.%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
|
|
.%N RFC2463
|
|
.%D December 1998
|
|
.Re
|
|
.Rs
|
|
.%A Matt Crawford
|
|
.%T "IPv6 Node Information Queries"
|
|
.%N draft-ietf-ipngwg-icmp-name-lookups-05.txt
|
|
.%D October 22, 1999
|
|
.%O work in progress material
|
|
.Re
|
|
.Sh HISTORY
|
|
The
|
|
.Nm ping
|
|
command appeared in
|
|
.Bx 4.3 .
|
|
The
|
|
.Nm
|
|
command with IPv6 support first appeared in WIDE Hydrangea IPv6 protocol stack
|
|
kit.
|
|
.Pp
|
|
IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
|
|
was initially integrated into
|
|
.Fx 4.0
|