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
44 .Op Fl .\& Ns Ar chars
47 .Op Fl G Ar sweepmaxsize
48 .Op Fl g Ar sweepminsize
49 .Op Fl h Ar sweepincrsize
52 .Op Fl M Cm mask | time
57 .Op Fl s Ar packetsize
63 .Op Fl 4AaDdfHLnoQqRrv
64 .Op Fl .\& Ns Ar chars
70 .Op Fl M Cm mask | time
75 .Op Fl s Ar packetsize
82 .Op Fl 6AaDdEfHNnOoquvYyZ
83 .Op Fl .\& Ns Ar chars
94 .Op Fl S Ar sourceaddr
95 .Op Fl s Ar packetsize
103 utility invoked with an IPv4 target
104 .Ns ( Ar IPv4-host No or Ar IPv4-mcast-group Ns )
107 .No protocol Ap s mandatory
109 datagram to elicit an
110 .Tn ICMP ECHO_RESPONSE
111 from a host or gateway.
117 header, followed by a
119 and then an arbitrary number of
121 bytes used to fill out the packet.
123 When invoked with an IPv6 target
124 .Ns ( Ar IPv6-host Ns ) Ns ,
128 .Tn ICMP6_ECHO_REQUEST
129 datagram to elicit an
132 .Tn ICMP6_ECHO_REQUEST
133 datagrams have an IPv6 header and
135 header formatted as documented in RFC 2463.
137 When invoked with a hostname, the version to which the target is resolved first is used.
138 In that case, the options and arguments used must be valid for the specific IP version, otherwise
141 If the target is resolved to both IPv4 and IPv6, the specific IP version can be requested by
145 options, respectively.
146 For backwards-compatibility, ICMPv6 can also be selected by invoking the binary
149 .Ss Options common to both IPv4 and IPv6 targets
150 .Bl -tag -width indent
151 .It Fl .\& Ns Ar chars
152 By default, for every
156 is printed, while for every
158 received, a backspace is printed.
159 This option takes an optional string argument listing characters
160 that will be printed one by one in the provided order
161 instead of the default period.
164 .Bd -literal -offset indent
165 ping -.0123456789 freebsd.org
172 character when no packet is received before the next packet
174 To cater for round-trip times that are longer than the interval
175 between transmissions, further missing packets cause a bell only
176 if the maximum number of unreceived packets has increased.
182 character in the output when any packet is received.
184 Add an 802.1p Ethernet Priority Code Point when sending a packet.
185 0..7 uses that specific PCP, -1 uses the interface default PCP (or none).
192 If this option is not specified,
194 will operate until interrupted.
196 For an IPv4 target, if this option is specified in conjunction with ping sweeps,
197 each sweep will consist of
201 Disable fragmentation.
205 option on the socket being used.
208 Outputs packets as fast as they come back or one hundred times per second,
212 to print a period for every
214 sent and a backspace for every
217 This provides a rapid display of how many packets are being dropped.
218 Only the super-user may use this option.
220 This can be very hard on a network and should be used with caution.
224 Try to do a reverse DNS lookup when displaying addresses.
225 This is the opposite of the
231 is an IP address indentifying an interface from which the packets will be sent.
232 This flag applies only if the ping target is a multicast address.
236 is a name of an interface (e.g. `em0') from which the packets will be sent.
237 This flag applies if the ping target is a multicast address, or link-local/site-local
243 .Em between sending each packet .
244 The default is to wait for one second between each packet.
245 The wait time may be fractional, but only the super-user may specify
246 values less than 1 second.
247 This option is incompatible with the
255 sends that many packets as fast as possible before falling into its normal
257 Only the super-user may use this option.
259 For an IPv4 target, set the IP Time To Live for outgoing packets.
260 If not specified, the kernel uses the value of the
264 For an IPv6 target, set the IPv6 hoplimit.
267 No attempt will be made to lookup symbolic names for host addresses.
268 This is the opposite of
270 and it is the default behavior.
272 Exit successfully after receiving one reply packet.
275 specifies IPsec policy for the ping session.
276 For details please refer to
279 .Xr ipsec_set_policy 3 .
281 You may specify up to 16
283 bytes to fill out the packet you send.
284 This is useful for diagnosing data-dependent problems in a network.
287 will cause the sent packet to be filled with all
291 Nothing is displayed except the summary lines at startup time and
294 Use the following IP address as the source address in outgoing packets.
295 On hosts with more than one IP address, this option can be used to
296 force the source address to be something other than the IP address
297 of the interface the probe packet is sent on.
299 For IPv4, if the IP address is not one of this machine's interface
300 addresses, an error is returned and nothing is sent.
302 For IPv6, the source address must be one of the unicast addresses of
303 the sending node, and must be numeric.
304 .It Fl s Ar packetsize
305 Specify the number of data bytes to be sent.
306 The default is 56, which translates into 64
308 data bytes when combined
313 For IPv4, only the super-user may specify values more than default.
314 This option cannot be used with ping sweeps.
316 For IPv6, you may need to specify
318 as well to extend socket buffer size.
320 Specify a timeout, in seconds, before ping exits regardless of how
321 many packets have been received.
327 that are received are listed.
329 Time in milliseconds to wait for a reply for each packet sent.
330 If a reply arrives later, the packet is not printed as replied, but
331 considered as replied when calculating statistics.
333 .Ss Options only for IPv4 targets
334 .Bl -tag -width indent
336 Use IPv4 regardless of how the target is resolved.
337 .It Fl G Ar sweepmaxsize
338 Specify the maximum size of
340 payload when sending sweeping pings.
341 This option is required for ping sweeps.
342 .It Fl g Ar sweepminsize
345 payload to start with when sending sweeping pings.
346 The default value is 0.
347 .It Fl h Ar sweepincrsize
348 Specify the number of bytes to increment the size of
351 each sweep when sending sweeping pings.
352 The default value is 1.
354 Suppress loopback of multicast packets.
355 This flag only applies if the ping destination is a multicast address.
356 .It Fl M Cm mask | time
365 print the netmask of the remote machine.
367 .Va net.inet.icmp.maskrepl
368 MIB variable to enable
371 .Va net.inet.icmp.maskfake
372 if you want to override the netmask in the response.
375 print the origination, reception and transmission timestamps.
377 .Va net.inet.icmp.tstamprepl
378 MIB variable to enable or disable
379 .Dv ICMP_TSTAMPREPLY .
381 Somewhat quiet output.
383 display ICMP error messages that are in response to our query messages.
386 flag was required to display such errors, but
388 displays all ICMP error messages.
389 On a busy machine, this output can be overbearing.
394 prints out any ICMP error messages caused by its own ECHO_REQUEST
403 the route buffer on returned packets.
404 Note that the IP header is only large enough for nine such routes;
407 command is usually better at determining the route packets take to a
408 particular destination.
409 If more routes come back than should, such as due to an illegal spoofed
410 packet, ping will print the route list and then truncate it at the correct
412 Many hosts ignore or discard the
416 Bypass the normal routing tables and send directly to a host on an attached
418 If the host is not on a directly-attached network, an error is returned.
419 This option can be used to ping a local host through an interface
420 that has no route through it
421 (e.g., after the interface was dropped by
424 Set the IP Time To Live for multicasted packets.
425 This flag only applies if the ping destination is a multicast address.
427 Use the specified type of service.
429 hostname or IPv4 address of the final destination node.
430 .It Ar IPv4-mcast-group
431 IPv4 multicast address of the final destination nodes.
433 .Ss Options only for IPv6 targets
434 .Bl -tag -width indent
436 Use IPv6 regardless of how the target is resolved.
438 Set socket buffer size.
442 as the next hop to the destination.
443 The gateway must be a neighbor of the sending node.
445 Generate ICMPv6 Node Information Node Addresses query, rather than echo-request.
447 must be a string constructed of the following characters.
448 .Bl -tag -width Ds -compact
450 requests unicast addresses from all of the responder's interfaces.
451 If the character is omitted,
452 only those addresses which belong to the interface which has the
453 responder's address are requests.
455 requests responder's IPv4-compatible and IPv4-mapped addresses.
457 requests responder's global-scope addresses.
459 requests responder's site-local addresses.
461 requests responder's link-local addresses.
463 requests responder's anycast addresses.
464 Without this character, the responder will return unicast addresses only.
465 With this character, the responder will return anycast addresses only.
466 Note that the specification does not specify how to get responder's
468 This is an experimental option.
471 Probe node information multicast group address
472 .Pq Li ff02::2:ffxx:xxxx .
474 must be string hostname of the target
475 (must not be a numeric IPv6 address).
476 Node information multicast group will be computed based on given
478 and will be used as the final destination.
479 Since node information multicast group is a link-local multicast group,
480 outgoing interface needs to be specified by
484 When specified twice, the address
485 .Pq Li ff02::2:xxxx:xxxx
487 The former is in RFC 4620, the latter is in an old Internet Draft
488 draft-ietf-ipngwg-icmp-name-lookup.
489 Note that KAME-derived implementations including
493 Generate ICMPv6 Node Information supported query types query,
494 rather than echo-request.
502 asks the kernel to fragment packets to fit into the minimum IPv6 MTU.
506 will suppress the behavior in the following two levels:
507 when the option is specified once, the behavior will be disabled for
509 When the option is more than once, it will be disabled for both
510 unicast and multicast packets.
514 but with old packet format based on 03 draft.
515 This option is present for backward compatibility.
521 Generate ICMPv6 Node Information DNS Name query, rather than echo-request.
527 IPv6 addresses for intermediate nodes,
528 which will be put into type 0 routing header.
530 IPv6 address of the final destination node.
532 .Ss Experimental options only for IPv6 target
533 .Bl -tag -width indent
535 Enables transport-mode IPsec encapsulated security payload.
537 Enables transport-mode IPsec authentication header.
542 for fault isolation, it should first be run on the local host, to verify
543 that the local network interface is up and running.
544 Then, hosts and gateways further and further away should be
546 Round-trip times and packet loss statistics are computed.
547 If duplicate packets are received, they are not included in the packet
548 loss calculation, although the round trip time of these packets is used
549 in calculating the round-trip time statistics.
550 When the specified number of packets have been sent
552 or if the program is terminated with a
554 a brief summary is displayed, showing the number of packets sent and
555 received, and the minimum, mean, maximum, and standard deviation of
556 the round-trip times.
566 signal, the current number of packets sent and received, and the
567 minimum, mean, maximum, and standard deviation of the round-trip times
568 will be written to the standard output.
570 This program is intended for use in network testing, measurement and
572 Because of the load it can impose on the network, it is unwise to use
574 during normal operations or from automated scripts.
575 .Sh ICMP PACKET DETAILS
576 An IP header without options is 20 bytes.
580 packet contains an additional 8 bytes worth of
582 header followed by an arbitrary amount of data.
585 is given, this indicated the size of this extra piece of data
587 Thus the amount of data received inside of an IP packet of type
590 will always be 8 bytes more than the requested data space
595 If the data space is at least eight bytes large,
597 uses the first eight bytes of this space to include a timestamp which
598 it uses in the computation of round trip times.
599 If less than eight bytes of pad are specified, no round trip times are
601 .Sh DUPLICATE AND DAMAGED PACKETS
604 utility will report duplicate and damaged packets.
605 Duplicate packets should never occur when pinging a unicast address,
606 and seem to be caused by
607 inappropriate link-level retransmissions.
608 Duplicates may occur in many situations and are rarely
610 a good sign, although the presence of low levels of duplicates may not
611 always be cause for alarm.
612 Duplicates are expected when pinging a broadcast or multicast address,
613 since they are not really duplicates but replies from different hosts
616 Damaged packets are obviously serious cause for alarm and often
617 indicate broken hardware somewhere in the
619 packet's path (in the network or in the hosts).
620 .Sh TRYING DIFFERENT DATA PATTERNS
623 layer should never treat packets differently depending on the data
624 contained in the data portion.
625 Unfortunately, data-dependent problems have been known to sneak into
626 networks and remain undetected for long periods of time.
627 In many cases the particular pattern that will have problems is something
628 that does not have sufficient
630 such as all ones or all zeros, or a pattern right at the edge, such as
633 necessarily enough to specify a data pattern of all zeros (for example)
634 on the command line because the pattern that is of interest is
635 at the data link level, and the relationship between what you type and
636 what the controllers transmit can be complicated.
638 This means that if you have a data-dependent problem you will probably
639 have to do a lot of testing to find it.
640 If you are lucky, you may manage to find a file that either
642 be sent across your network or that takes much longer to transfer than
643 other similar length files.
644 You can then examine this file for repeated patterns that you can test
652 value of an IP packet represents the maximum number of IP routers
653 that the packet can go through before being thrown away.
654 In current practice you can expect each router in the Internet to decrement
657 field by exactly one.
661 specification recommends setting the
665 packets to 64, but many systems use smaller values
671 The maximum possible value of this field is 255, and most
677 .Tn ICMP ECHO_REQUEST
679 This is why you will find you can
681 some hosts, but not reach them with
688 prints the ttl value from the packet it receives.
689 When a remote system receives a ping packet, it can do one of three things
692 field in its response:
695 Not change it; this is what
697 systems did before the
702 value in the received packet will be 255 minus the
703 number of routers in the round-trip path.
705 Set it to 255; this is what current
710 value in the received packet will be 255 minus the
711 number of routers in the path
719 Set it to some other value.
720 Some machines use the same value for
722 packets that they use for
724 packets, for example either 30 or 60.
725 Others may use completely wild values.
730 utility exits with one of the following values:
731 .Bl -tag -width indent
733 At least one response was heard from the specified
736 The transmission was successful but no responses were received.
741 The following will send ICMPv6 echo request to
743 .Bd -literal -offset indent
744 ping -6 -n dst.foo.com
747 The following will probe hostnames for all nodes on the network link attached to
752 is named the link-local all-node multicast address, and the packet would
753 reach every node on the network link.
754 .Bd -literal -offset indent
755 ping -6 -y ff02::1%wi0
758 The following will probe addresses assigned to the destination node,
760 .Bd -literal -offset indent
761 ping -6 -k agl dst.foo.com
776 .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
782 .%T "IPv6 Node Information Queries"
783 .%N draft-ietf-ipngwg-icmp-name-lookups-09.txt
785 .%O work in progress material
794 utility with IPv6 support first appeared in the WIDE Hydrangea IPv6
797 IPv6 and IPsec support based on the KAME Project
798 .Pq Pa https://www.kame.net/
799 stack was initially integrated into
804 utility was merged to
806 in Google Summer of Code 2019.
810 utility was written by
812 while at the US Army Ballistics
815 Many Hosts and Gateways ignore the IPv4
819 The maximum IP header length is too small for options like
821 to be completely useful.
823 not much that can be done about this, however.
825 Flood pinging is not recommended in general, and flood pinging the
826 broadcast address should only be done under very controlled conditions.
830 option is not worth much on busy hosts.
projects / FreeBSD / FreeBSD.git / blob