1 .\" Copyright (c) 2002-2013 Apple Inc. All rights reserved.
3 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 .\" This file contains Original Code and/or Modifications of Original Code
6 .\" as defined in and that are subject to the Apple Public Source License
7 .\" Version 2.0 (the 'License'). You may not use this file except in
8 .\" compliance with the License. The rights granted to you under the License
9 .\" may not be used to create, or enable the creation or redistribution of,
10 .\" unlawful or unlicensed copies of an Apple operating system, or to
11 .\" circumvent, violate, or enable the circumvention or violation of, any
12 .\" terms of an Apple operating system software license agreement.
14 .\" Please obtain a copy of the License at
15 .\" http://www.opensource.apple.com/apsl/ and read it before using this file.
17 .\" The Original Code and all software distributed under the License are
18 .\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
19 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
20 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
21 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
22 .\" Please see the License for the specific language governing rights and
23 .\" limitations under the License.
25 .\" @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
28 .\" All rights reserved.
30 .\" Redistribution and use in source and binary forms, with or without
31 .\" modification, are permitted provided that the following conditions
33 .\" 1. Redistributions of source code must retain the above copyright
34 .\" notice, this list of conditions and the following disclaimer.
35 .\" 2. Redistributions in binary form must reproduce the above copyright
36 .\" notice, this list of conditions and the following disclaimer in the
37 .\" documentation and/or other materials provided with the distribution.
38 .\" 3. Neither the name of the project nor the names of its contributors
39 .\" may be used to endorse or promote products derived from this software
40 .\" without specific prior written permission.
42 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
43 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
44 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
45 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
46 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
47 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
48 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
49 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
50 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
51 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
61 .Tn ICMPv6 ECHO_REQUEST
62 packets to network hosts
65 .\" without ipsec, or new ipsec
68 .\" .Op Fl ADdEfmnNqRtvwW
104 .Op Fl S Ar sourceaddr
107 .Op Fl s Ar packetsize
124 .Tn ICMP6_ECHO_REQUEST
125 datagram to elicit an
127 from a host or gateway.
128 .Tn ICMP6_ECHO_REQUEST
129 datagrams (``pings'') have an IPv6 header,
132 header formatted as documented in RFC2463.
133 The options are as follows:
137 .\" Enables transport-mode IPsec authentication header
140 Generate ICMPv6 Node Information Node Addresses query, rather than echo-request.
142 must be a string constructed of the following characters.
143 .Bl -tag -width Ds -compact
145 requests unicast addresses from all of the responder's interfaces.
146 If the character is omitted,
147 only those addresses which belong to the interface which has the
148 responder's address are requests.
150 requests responder's IPv4-compatible and IPv4-mapped addresses.
152 requests responder's global-scope addresses.
154 requests responder's site-local addresses.
156 requests responder's link-local addresses.
158 requests responder's anycast addresses.
159 Without this character, the responder will return unicast addresses only.
160 With this character, the responder will return anycast addresses only.
161 Note that the specification does not specify how to get responder's
163 This is an experimental option.
166 Set socket buffer size.
168 Bind the socket to interface
172 Prohibit the socket from using the cellular network interface.
180 Disable IPv6 fragmentation.
184 option on the socket being used.
186 .\" Enables transport-mode IPsec encapsulated security payload
190 Outputs packets as fast as they come back or one hundred times per second,
196 is printed, while for every
198 received a backspace is printed.
199 This provides a rapid display of how many packets are being dropped.
200 Only the super-user may use this option.
202 This can be very hard on a network and should be used with caution.
207 as the next hop to the destination.
208 The gateway must be a neighbor of the sending node.
210 Specifies to try reverse-lookup of IPv6 addresses.
213 utility does not try reverse-lookup unless the option is specified.
215 Set the IPv6 hoplimit.
216 .It Fl I Ar interface
217 Source packets with the given interface address.
218 This flag applies if the ping destination is a multicast address,
219 or link-local/site-local unicast address.
224 .Em between sending each packet .
225 The default is to wait for one second between each packet.
226 The wait time may be fractional, but only the super-user may specify
227 values less than 0.1 second.
228 This option is incompatible with the
236 sends that many packets as fast as possible before falling into its normal
238 Only the super-user may use this option.
242 asks the kernel to fragment packets to fit into the minimum IPv6 MTU.
246 will suppress the behavior in the following two levels:
247 when the option is specified once, the behavior will be disabled for
249 When the option is more than once, it will be disabled for both
250 unicast and multicast packets.
253 No attempt will be made to lookup symbolic names from addresses in the reply.
255 Probe node information multicast group
256 .Pq Li ff02::2:xxxx:xxxx .
258 must be string hostname of the target
259 (must not be a numeric IPv6 address).
260 Node information multicast group will be computed based on given
262 and will be used as the final destination.
263 Since node information multicast group is a link-local multicast group,
264 outgoing interface needs to be specified by
268 Exit successfully after receiving one reply packet.
270 You may specify up to 16
272 bytes to fill out the packet you send.
273 This is useful for diagnosing data-dependent problems in a network.
276 will cause the sent packet to be filled with all
281 specifies IPsec policy to be used for the probe.
284 Nothing is displayed except the summary lines at startup time and
291 character in the output when any packet is received.
297 character when no packet is received before the next packet
299 To cater for round-trip times that are longer than the interval
300 between transmissions, further missing packets cause a bell only
301 if the maximum number of unreceived packets has increased.
302 .It Fl S Ar sourceaddr
303 Specifies the source address of request packets.
304 The source address must be one of the unicast addresses of the sending node,
306 .It Fl s Ar packetsize
307 Specifies the number of data bytes to be sent.
308 The default is 56, which translates into 64
310 data bytes when combined
314 You may need to specify
316 as well to extend socket buffer size.
318 Generate ICMPv6 Node Information supported query types query,
319 rather than echo-request.
329 that are received are listed.
331 Generate ICMPv6 Node Information DNS Name query, rather than echo-request.
339 but with old packet format based on 03 draft.
340 This option is present for backward compatibility.
346 Use the specified traffic class.
348 IPv6 addresses for intermediate nodes,
349 which will be put into type 0 routing header.
351 IPv6 address of the final destination node.
356 for fault isolation, it should first be run on the local host, to verify
357 that the local network interface is up and running.
358 Then, hosts and gateways further and further away should be
360 Round-trip times and packet loss statistics are computed.
361 If duplicate packets are received, they are not included in the packet
362 loss calculation, although the round trip time of these packets is used
363 in calculating the round-trip time statistics.
364 When the specified number of packets have been sent
366 or if the program is terminated with a
368 a brief summary is displayed, showing the number of packets sent and
369 received, and the minimum, mean, maximum, and standard deviation of
370 the round-trip times.
380 signal, the current number of packets sent and received, and the
381 minimum, mean, maximum, and standard deviation of the round-trip times
382 will be written to the standard output in the same format as the
383 standard completion message.
385 This program is intended for use in network testing, measurement and
387 Because of the load it can impose on the network, it is unwise to use
389 during normal operations or from automated scripts.
390 .\" .Sh ICMP PACKET DETAILS
391 .\" An IP header without options is 20 bytes.
395 .\" packet contains an additional 8 bytes worth of
397 .\" header followed by an arbitrary amount of data.
400 .\" is given, this indicated the size of this extra piece of data
401 .\" (the default is 56).
402 .\" Thus the amount of data received inside of an IP packet of type
405 .\" will always be 8 bytes more than the requested data space
410 .\" If the data space is at least eight bytes large,
412 .\" uses the first eight bytes of this space to include a timestamp which
413 .\" it uses in the computation of round trip times.
414 .\" If less than eight bytes of pad are specified, no round trip times are
416 .Sh DUPLICATE AND DAMAGED PACKETS
419 utility will report duplicate and damaged packets.
420 Duplicate packets should never occur when pinging a unicast address,
421 and seem to be caused by
422 inappropriate link-level retransmissions.
423 Duplicates may occur in many situations and are rarely
425 a good sign, although the presence of low levels of duplicates may not
426 always be cause for alarm.
427 Duplicates are expected when pinging a broadcast or multicast address,
428 since they are not really duplicates but replies from different hosts
431 Damaged packets are obviously serious cause for alarm and often
432 indicate broken hardware somewhere in the
435 (in the network or in the hosts).
436 .Sh TRYING DIFFERENT DATA PATTERNS
439 layer should never treat packets differently depending on the data
440 contained in the data portion.
441 Unfortunately, data-dependent problems have been known to sneak into
442 networks and remain undetected for long periods of time.
443 In many cases the particular pattern that will have problems is something
444 that does not have sufficient
446 such as all ones or all zeros, or a pattern right at the edge, such as
449 necessarily enough to specify a data pattern of all zeros (for example)
450 on the command line because the pattern that is of interest is
451 at the data link level, and the relationship between what you type and
452 what the controllers transmit can be complicated.
454 This means that if you have a data-dependent problem you will probably
455 have to do a lot of testing to find it.
456 If you are lucky, you may manage to find a file that either
458 be sent across your network or that takes much longer to transfer than
459 other similar length files.
460 You can then examine this file for repeated patterns that you can test
468 utility returns 0 on success (the host is alive),
469 2 if the transmission was successful but no responses were received,
470 any other non-zero value if the arguments are incorrect or
471 another error has occurred.
477 would work; the following will send ICMPv6 echo request to
479 .Bd -literal -offset indent
483 The following will probe hostnames for all nodes on the network link attached to
488 is named the link-local all-node multicast address, and the packet would
489 reach every node on the network link.
490 .Bd -literal -offset indent
494 The following will probe addresses assigned to the destination node,
496 .Bd -literal -offset indent
497 ping6 -a agl dst.foo.com
512 .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
518 .%T "IPv6 Node Information Queries"
519 .%N draft-ietf-ipngwg-icmp-name-lookups-09.txt
521 .%O work in progress material
530 utility with IPv6 support first appeared in the WIDE Hydrangea IPv6
533 IPv6 and IPsec support based on the KAME Project
534 .Pq Pa http://www.kame.net/
535 stack was initially integrated into
541 is intentionally separate from
544 There have been many discussions on why we separate
548 Some people argued that it would be more convenient to uniform the
549 ping command for both IPv4 and IPv6.
550 The followings are an answer to the request.
552 From a developer's point of view:
553 since the underling raw sockets API is totally different between IPv4
554 and IPv6, we would end up having two types of code base.
555 There would actually be less benefit to uniform the two commands
556 into a single command from the developer's standpoint.
558 From an operator's point of view: unlike ordinary network applications
559 like remote login tools, we are usually aware of address family when using
560 network management tools.
561 We do not just want to know the reachability to the host, but want to know the
562 reachability to the host via a particular network protocol such as
564 Thus, even if we had a unified
566 command for both IPv4 and IPv6, we would usually type a
570 option (or something like those) to specify the particular address family.
571 This essentially means that we have two different commands.
projects / apple / network_cmds.git / blob