1 .\" Copyright (c) 1985, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)ping.8 8.2 (Berkeley) 12/11/93
39 .Tn ICMPv6 ECHO_REQUEST
40 packets to network hosts
46 .Op Fl G Ar sweepmaxsize
47 .Op Fl g Ar sweepminsize
48 .Op Fl h Ar sweepincrsize
51 .Op Fl M Cm mask | time
56 .Op Fl s Ar packetsize
62 .Op Fl 4AaDdfHLnoQqRrv
68 .Op Fl M Cm mask | time
73 .Op Fl s Ar packetsize
80 .Op Fl 6AaDdEfHNnOoquvYyZ
91 .Op Fl S Ar sourceaddr
92 .Op Fl s Ar packetsize
100 utility invoked with an IPv4 target
101 .Ns ( Ar IPv4-host No or Ar IPv4-mcast-group Ns )
104 .No protocol Ap s mandatory
106 datagram to elicit an
107 .Tn ICMP ECHO_RESPONSE
108 from a host or gateway.
114 header, followed by a
116 and then an arbitrary number of
118 bytes used to fill out the packet.
120 When invoked with an IPv6 target
121 .Ns ( Ar IPv6-host Ns ) Ns ,
125 .Tn ICMP6_ECHO_REQUEST
126 datagram to elicit an
129 .Tn ICMP6_ECHO_REQUEST
130 datagrams have an IPv6 header and
132 header formatted as documented in RFC 2463.
134 When invoked with a hostname, the version to which the target is
135 resolved first is used. In that case, the options and arguments used
136 must be valid for the specific IP version, otherwise
138 exits with an error. If the target is resolved to both IPv4 and IPv6,
139 the specific IP version can be requested by
143 options, respectively.
144 .Ss Options common to both IPv4 and IPv6 targets
145 .Bl -tag -width indent
151 character when no packet is received before the next packet
153 To cater for round-trip times that are longer than the interval
154 between transmissions, further missing packets cause a bell only
155 if the maximum number of unreceived packets has increased.
161 character in the output when any packet is received.
163 Add an 802.1p Ethernet Priority Code Point when sending a packet.
164 0..7 uses that specific PCP, -1 uses the interface default PCP (or none).
171 If this option is not specified,
173 will operate until interrupted.
175 For an IPv4 target, if this option is specified in conjunction with ping sweeps,
176 each sweep will consist of
180 Disable fragmentation.
184 option on the socket being used.
187 Outputs packets as fast as they come back or one hundred times per second,
193 is printed, while for every
195 received a backspace is printed.
196 This provides a rapid display of how many packets are being dropped.
197 Only the super-user may use this option.
199 This can be very hard on a network and should be used with caution.
203 Try to do a reverse DNS lookup when displaying addresses.
204 This is the opposite of the
210 is an IP address indentifying an interface from which the packets will
211 be sent. This flag applies only if the ping target is a multicast
216 is a name of an interface (e.g. `em0') from which the packets will be
217 sent. This flag applies if the ping target is a multicast address, or
218 link-local/site-local unicast address.
223 .Em between sending each packet .
224 The default is to wait for one second between each packet.
225 The wait time may be fractional, but only the super-user may specify
226 values less than 1 second.
227 This option is incompatible with the
235 sends that many packets as fast as possible before falling into its normal
237 Only the super-user may use this option.
239 For an IPv4 target, set the IP Time To Live for outgoing packets.
240 If not specified, the kernel uses the value of the
244 For an IPv6 target, set the IPv6 hoplimit.
247 No attempt will be made to lookup symbolic names for host addresses.
248 This is the opposite of
250 and it is the default behavior.
252 Exit successfully after receiving one reply packet.
255 specifies IPsec policy for the ping session.
256 For details please refer to
259 .Xr ipsec_set_policy 3 .
261 You may specify up to 16
263 bytes to fill out the packet you send.
264 This is useful for diagnosing data-dependent problems in a network.
267 will cause the sent packet to be filled with all
271 Nothing is displayed except the summary lines at startup time and
274 Use the following IP address as the source address in outgoing packets.
275 On hosts with more than one IP address, this option can be used to
276 force the source address to be something other than the IP address
277 of the interface the probe packet is sent on.
279 For IPv4, if the IP address is not one of this machine's interface
280 addresses, an error is returned and nothing is sent.
282 For IPv6, the source address must be one of the unicast addresses of
283 the sending node, and must be numeric.
284 .It Fl s Ar packetsize
285 Specify the number of data bytes to be sent.
286 The default is 56, which translates into 64
288 data bytes when combined
293 For IPv4, only the super-user may specify values more than default.
294 This option cannot be used with ping sweeps.
296 For IPv6, you may need to specify
298 as well to extend socket buffer size.
300 Specify a timeout, in seconds, before ping exits regardless of how
301 many packets have been received.
307 that are received are listed.
309 Time in milliseconds to wait for a reply for each packet sent.
310 If a reply arrives later, the packet is not printed as replied, but
311 considered as replied when calculating statistics.
313 .Ss Options only for IPv4 targets
314 .Bl -tag -width indent
316 Use IPv4 regardless of how the target is resolved.
317 .It Fl G Ar sweepmaxsize
318 Specify the maximum size of
320 payload when sending sweeping pings.
321 This option is required for ping sweeps.
322 .It Fl g Ar sweepminsize
325 payload to start with when sending sweeping pings.
326 The default value is 0.
327 .It Fl h Ar sweepincrsize
328 Specify the number of bytes to increment the size of
331 each sweep when sending sweeping pings.
332 The default value is 1.
334 Suppress loopback of multicast packets.
335 This flag only applies if the ping destination is a multicast address.
336 .It Fl M Cm mask | time
345 print the netmask of the remote machine.
347 .Va net.inet.icmp.maskrepl
348 MIB variable to enable
351 .Va net.inet.icmp.maskfake
352 if you want to override the netmask in the response.
355 print the origination, reception and transmission timestamps.
357 .Va net.inet.icmp.tstamprepl
358 MIB variable to enable or disable
359 .Dv ICMP_TSTAMPREPLY .
361 Somewhat quiet output.
363 display ICMP error messages that are in response to our query messages.
366 flag was required to display such errors, but
368 displays all ICMP error messages.
369 On a busy machine, this output can be overbearing.
374 prints out any ICMP error messages caused by its own ECHO_REQUEST
383 the route buffer on returned packets.
384 Note that the IP header is only large enough for nine such routes;
387 command is usually better at determining the route packets take to a
388 particular destination.
389 If more routes come back than should, such as due to an illegal spoofed
390 packet, ping will print the route list and then truncate it at the correct
392 Many hosts ignore or discard the
396 Bypass the normal routing tables and send directly to a host on an attached
398 If the host is not on a directly-attached network, an error is returned.
399 This option can be used to ping a local host through an interface
400 that has no route through it
401 (e.g., after the interface was dropped by
404 Set the IP Time To Live for multicasted packets.
405 This flag only applies if the ping destination is a multicast address.
407 Use the specified type of service.
409 hostname or IPv4 address of the final destination node.
410 .It Ar IPv4-mcast-group
411 IPv4 multicast address of the final destination nodes.
413 .Ss Options only for IPv6 targets
414 .Bl -tag -width indent
416 Use IPv6 regardless of how the target is resolved.
418 Set socket buffer size.
422 as the next hop to the destination.
423 The gateway must be a neighbor of the sending node.
425 Generate ICMPv6 Node Information Node Addresses query, rather than echo-request.
427 must be a string constructed of the following characters.
428 .Bl -tag -width Ds -compact
430 requests unicast addresses from all of the responder's interfaces.
431 If the character is omitted,
432 only those addresses which belong to the interface which has the
433 responder's address are requests.
435 requests responder's IPv4-compatible and IPv4-mapped addresses.
437 requests responder's global-scope addresses.
439 requests responder's site-local addresses.
441 requests responder's link-local addresses.
443 requests responder's anycast addresses.
444 Without this character, the responder will return unicast addresses only.
445 With this character, the responder will return anycast addresses only.
446 Note that the specification does not specify how to get responder's
448 This is an experimental option.
451 Probe node information multicast group address
452 .Pq Li ff02::2:ffxx:xxxx .
454 must be string hostname of the target
455 (must not be a numeric IPv6 address).
456 Node information multicast group will be computed based on given
458 and will be used as the final destination.
459 Since node information multicast group is a link-local multicast group,
460 outgoing interface needs to be specified by
464 When specified twice, the address
465 .Pq Li ff02::2:xxxx:xxxx
467 The former is in RFC 4620, the latter is in an old Internet Draft
468 draft-ietf-ipngwg-icmp-name-lookup.
469 Note that KAME-derived implementations including
473 Generate ICMPv6 Node Information supported query types query,
474 rather than echo-request.
482 asks the kernel to fragment packets to fit into the minimum IPv6 MTU.
486 will suppress the behavior in the following two levels:
487 when the option is specified once, the behavior will be disabled for
489 When the option is more than once, it will be disabled for both
490 unicast and multicast packets.
494 but with old packet format based on 03 draft.
495 This option is present for backward compatibility.
501 Generate ICMPv6 Node Information DNS Name query, rather than echo-request.
507 IPv6 addresses for intermediate nodes,
508 which will be put into type 0 routing header.
510 IPv6 address of the final destination node.
512 .Ss Experimental options only for IPv6 target
513 .Bl -tag -width indent
515 Enables transport-mode IPsec encapsulated security payload.
517 Enables transport-mode IPsec authentication header.
522 for fault isolation, it should first be run on the local host, to verify
523 that the local network interface is up and running.
524 Then, hosts and gateways further and further away should be
526 Round-trip times and packet loss statistics are computed.
527 If duplicate packets are received, they are not included in the packet
528 loss calculation, although the round trip time of these packets is used
529 in calculating the round-trip time statistics.
530 When the specified number of packets have been sent
532 or if the program is terminated with a
534 a brief summary is displayed, showing the number of packets sent and
535 received, and the minimum, mean, maximum, and standard deviation of
536 the round-trip times.
546 signal, the current number of packets sent and received, and the
547 minimum, mean, maximum, and standard deviation of the round-trip times
548 will be written to the standard output.
550 This program is intended for use in network testing, measurement and
552 Because of the load it can impose on the network, it is unwise to use
554 during normal operations or from automated scripts.
555 .Sh ICMP PACKET DETAILS
556 An IP header without options is 20 bytes.
560 packet contains an additional 8 bytes worth of
562 header followed by an arbitrary amount of data.
565 is given, this indicated the size of this extra piece of data
567 Thus the amount of data received inside of an IP packet of type
570 will always be 8 bytes more than the requested data space
575 If the data space is at least eight bytes large,
577 uses the first eight bytes of this space to include a timestamp which
578 it uses in the computation of round trip times.
579 If less than eight bytes of pad are specified, no round trip times are
581 .Sh DUPLICATE AND DAMAGED PACKETS
584 utility will report duplicate and damaged packets.
585 Duplicate packets should never occur when pinging a unicast address,
586 and seem to be caused by
587 inappropriate link-level retransmissions.
588 Duplicates may occur in many situations and are rarely
590 a good sign, although the presence of low levels of duplicates may not
591 always be cause for alarm.
592 Duplicates are expected when pinging a broadcast or multicast address,
593 since they are not really duplicates but replies from different hosts
596 Damaged packets are obviously serious cause for alarm and often
597 indicate broken hardware somewhere in the
599 packet's path (in the network or in the hosts).
600 .Sh TRYING DIFFERENT DATA PATTERNS
603 layer should never treat packets differently depending on the data
604 contained in the data portion.
605 Unfortunately, data-dependent problems have been known to sneak into
606 networks and remain undetected for long periods of time.
607 In many cases the particular pattern that will have problems is something
608 that does not have sufficient
610 such as all ones or all zeros, or a pattern right at the edge, such as
613 necessarily enough to specify a data pattern of all zeros (for example)
614 on the command line because the pattern that is of interest is
615 at the data link level, and the relationship between what you type and
616 what the controllers transmit can be complicated.
618 This means that if you have a data-dependent problem you will probably
619 have to do a lot of testing to find it.
620 If you are lucky, you may manage to find a file that either
622 be sent across your network or that takes much longer to transfer than
623 other similar length files.
624 You can then examine this file for repeated patterns that you can test
632 value of an IP packet represents the maximum number of IP routers
633 that the packet can go through before being thrown away.
634 In current practice you can expect each router in the Internet to decrement
637 field by exactly one.
641 specification recommends setting the
645 packets to 64, but many systems use smaller values
651 The maximum possible value of this field is 255, and most
657 .Tn ICMP ECHO_REQUEST
659 This is why you will find you can
661 some hosts, but not reach them with
668 prints the ttl value from the packet it receives.
669 When a remote system receives a ping packet, it can do one of three things
672 field in its response:
675 Not change it; this is what
677 systems did before the
682 value in the received packet will be 255 minus the
683 number of routers in the round-trip path.
685 Set it to 255; this is what current
690 value in the received packet will be 255 minus the
691 number of routers in the path
699 Set it to some other value.
700 Some machines use the same value for
702 packets that they use for
704 packets, for example either 30 or 60.
705 Others may use completely wild values.
710 utility exits with one of the following values:
711 .Bl -tag -width indent
713 At least one response was heard from the specified
716 The transmission was successful but no responses were received.
721 The following will send ICMPv6 echo request to
723 .Bd -literal -offset indent
724 ping -6 -n dst.foo.com
727 The following will probe hostnames for all nodes on the network link attached to
732 is named the link-local all-node multicast address, and the packet would
733 reach every node on the network link.
734 .Bd -literal -offset indent
735 ping -6 -y ff02::1%wi0
738 The following will probe addresses assigned to the destination node,
740 .Bd -literal -offset indent
741 ping -6 -k agl dst.foo.com
756 .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
762 .%T "IPv6 Node Information Queries"
763 .%N draft-ietf-ipngwg-icmp-name-lookups-09.txt
765 .%O work in progress material
774 utility with IPv6 support first appeared in the WIDE Hydrangea IPv6
777 IPv6 and IPsec support based on the KAME Project
778 .Pq Pa http://www.kame.net/
779 stack was initially integrated into
784 utility was merged to
786 in Google Summer of Code 2019.
790 utility was written by
792 while at the US Army Ballistics
795 Many Hosts and Gateways ignore the IPv4
799 The maximum IP header length is too small for options like
801 to be completely useful.
803 not much that can be done about this, however.
805 Flood pinging is not recommended in general, and flood pinging the
806 broadcast address should only be done under very controlled conditions.
810 option is not worth much on busy hosts.
projects / FreeBSD / FreeBSD.git / blob