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 packets to network hosts
43 .Op Fl .\& Ns Ar chars
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
63 .Op Fl .\& Ns Ar chars
69 .Op Fl M Cm mask | time
74 .Op Fl s Ar packetsize
81 .Op Fl 6AaDdEfHNnOoquvYyZ
82 .Op Fl .\& Ns Ar chars
93 .Op Fl S Ar sourceaddr
94 .Op Fl s Ar packetsize
102 utility invoked with an IPv4 target
105 .Ar IPv4-mcast-group )
108 .No protocol Ap s mandatory
110 datagram to elicit an
112 from a host or gateway.
118 header, followed by a
120 and then an arbitrary number of
122 bytes used to fill out the packet.
124 When invoked with an IPv6 target
130 datagram to elicit an
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
139 In that case, the options and arguments used must be valid for the specific IP
143 If the target is resolved to both IPv4 and IPv6, the specific IP version can be
148 options, respectively.
149 For backwards-compatibility, ICMPv6 can also be selected by invoking the binary
152 .Ss Options common to both IPv4 and IPv6 targets
153 .Bl -tag -width indent
154 .It Fl .\& Ns Ar chars
155 By default, for every
159 is printed, while for every
161 received, a backspace is printed.
162 This option takes an optional string argument listing characters
163 that will be printed one by one in the provided order
164 instead of the default period.
167 .Bd -literal -offset indent
168 ping -.0123456789 freebsd.org
175 character when no packet is received before the next packet
177 To cater for round-trip times that are longer than the interval
178 between transmissions, further missing packets cause a bell only
179 if the maximum number of unreceived packets has increased.
185 character in the output when any packet is received.
187 Add an 802.1p Ethernet Priority Code Point when sending a packet.
188 0..7 uses that specific PCP, -1 uses the interface default PCP (or none).
195 If this option is not specified,
197 will operate until interrupted.
199 For an IPv4 target, if this option is specified in conjunction with ping sweeps,
200 each sweep will consist of
204 Disable fragmentation.
208 option on the socket being used.
211 Outputs packets as fast as they come back or one hundred times per second,
215 to print a period for every
217 sent and a backspace for every
220 This provides a rapid display of how many packets are being dropped.
221 Only the super-user may use this option.
223 This can be very hard on a network and should be used with caution.
227 Try to do a reverse DNS lookup when displaying addresses.
228 This is the opposite of the
234 is an IP address indentifying an interface from which the packets will be sent.
235 This flag applies only if the ping target is a multicast address.
239 is a name of an interface (e.g., `em0') from which the packets will be sent.
240 This flag applies if the ping target is a multicast address, or
241 link-local/site-local unicast address.
246 .Em between sending each packet .
247 The default is to wait for one second between each packet.
248 The wait time may be fractional, but only the super-user may specify
249 values less than 1 second.
250 This option is incompatible with the
258 sends that many packets as fast as possible before falling into its normal
260 Only the super-user may use this option.
262 For an IPv4 target, set the IP Time To Live for outgoing packets.
263 If not specified, the kernel uses the value of the
267 For an IPv6 target, set the IPv6 hoplimit.
270 No attempt will be made to lookup symbolic names for host addresses.
271 This is the opposite of
273 and it is the default behavior.
275 Exit successfully after receiving one reply packet.
278 specifies IPsec policy for the ping session.
279 For details please refer to
282 .Xr ipsec_set_policy 3 .
284 You may specify up to 16
286 bytes to fill out the packet you send.
287 This is useful for diagnosing data-dependent problems in a network.
290 will cause the sent packet to be filled with all
294 Nothing is displayed except the summary lines at startup time and
297 Use the following IP address as the source address in outgoing packets.
298 On hosts with more than one IP address, this option can be used to
299 force the source address to be something other than the IP address
300 of the interface the probe packet is sent on.
302 For IPv4, if the IP address is not one of this machine's interface
303 addresses, an error is returned and nothing is sent.
305 For IPv6, the source address must be one of the unicast addresses of
306 the sending node, and must be numeric.
307 .It Fl s Ar packetsize
308 Specify the number of data bytes to be sent.
309 The default is 56, which translates into 64
311 data bytes when combined
316 For IPv4, only the super-user may specify values more than default.
317 This option cannot be used with ping sweeps.
319 For IPv6, you may need to specify
321 as well to extend socket buffer size.
323 Specify a timeout, in seconds, before ping exits regardless of how
324 many packets have been received.
330 that are received are listed.
332 Time in milliseconds to wait for a reply for each packet sent.
333 If a reply arrives later, the packet is not printed as replied, but
334 considered as replied when calculating statistics.
336 .Ss Options only for IPv4 targets
337 .Bl -tag -width indent
339 Use IPv4 regardless of how the target is resolved.
340 .It Fl G Ar sweepmaxsize
341 Specify the maximum size of
343 payload when sending sweeping pings.
344 This option is required for ping sweeps.
345 .It Fl g Ar sweepminsize
348 payload to start with when sending sweeping pings.
349 The default value is 0.
350 .It Fl h Ar sweepincrsize
351 Specify the number of bytes to increment the size of
354 each sweep when sending sweeping pings.
355 The default value is 1.
357 Suppress loopback of multicast packets.
358 This flag only applies if the ping destination is a multicast address.
359 .It Fl M Cm mask | time
368 print the netmask of the remote machine.
370 .Va net.inet.icmp.maskrepl
371 MIB variable to enable
374 .Va net.inet.icmp.maskfake
375 if you want to override the netmask in the response.
378 print the origination, reception and transmission timestamps.
380 .Va net.inet.icmp.tstamprepl
381 MIB variable to enable or disable
382 .Dv ICMP_TSTAMPREPLY .
384 Somewhat quiet output.
386 display ICMP error messages that are in response to our query messages.
389 flag was required to display such errors, but
391 displays all ICMP error messages.
392 On a busy machine, this output can be overbearing.
397 prints out any ICMP error messages caused by its own ECHO_REQUEST
406 the route buffer on returned packets.
407 Note that the IP header is only large enough for nine such routes;
410 command is usually better at determining the route packets take to a
411 particular destination.
412 If more routes come back than should, such as due to an illegal spoofed
413 packet, ping will print the route list and then truncate it at the correct
415 Many hosts ignore or discard the
419 Bypass the normal routing tables and send directly to a host on an attached
421 If the host is not on a directly-attached network, an error is returned.
422 This option can be used to ping a local host through an interface
423 that has no route through it
424 (e.g., after the interface was dropped by
427 Set the IP Time To Live for multicasted packets.
428 This flag only applies if the ping destination is a multicast address.
430 Use the specified type of service.
432 hostname or IPv4 address of the final destination node.
433 .It Ar IPv4-mcast-group
434 IPv4 multicast address of the final destination nodes.
436 .Ss Options only for IPv6 targets
437 .Bl -tag -width indent
439 Use IPv6 regardless of how the target is resolved.
441 Set socket buffer size.
445 as the next hop to the destination.
446 The gateway must be a neighbor of the sending node.
448 Generate ICMPv6 Node Information Node Addresses query, rather than echo-request.
450 must be a string constructed of the following characters.
451 .Bl -tag -width Ds -compact
453 requests unicast addresses from all of the responder's interfaces.
454 If the character is omitted,
455 only those addresses which belong to the interface which has the
456 responder's address are requests.
458 requests responder's IPv4-compatible and IPv4-mapped addresses.
460 requests responder's global-scope addresses.
462 requests responder's site-local addresses.
464 requests responder's link-local addresses.
466 requests responder's anycast addresses.
467 Without this character, the responder will return unicast addresses only.
468 With this character, the responder will return anycast addresses only.
469 Note that the specification does not specify how to get responder's
471 This is an experimental option.
474 Probe node information multicast group address
475 .Pq Li ff02::2:ffxx:xxxx .
477 must be string hostname of the target
478 (must not be a numeric IPv6 address).
479 Node information multicast group will be computed based on given
481 and will be used as the final destination.
482 Since node information multicast group is a link-local multicast group,
483 outgoing interface needs to be specified by
487 When specified twice, the address
488 .Pq Li ff02::2:xxxx:xxxx
490 The former is in RFC 4620, the latter is in an old Internet Draft
491 draft-ietf-ipngwg-icmp-name-lookup.
492 Note that KAME-derived implementations including
496 Generate ICMPv6 Node Information supported query types query,
497 rather than echo-request.
505 asks the kernel to fragment packets to fit into the minimum IPv6 MTU.
509 will suppress the behavior in the following two levels:
510 when the option is specified once, the behavior will be disabled for
512 When the option is more than once, it will be disabled for both
513 unicast and multicast packets.
517 but with old packet format based on 03 draft.
518 This option is present for backward compatibility.
524 Generate ICMPv6 Node Information DNS Name query, rather than echo-request.
530 IPv6 addresses for intermediate nodes,
531 which will be put into type 0 routing header.
533 IPv6 address of the final destination node.
535 .Ss Experimental options only for IPv6 target
536 .Bl -tag -width indent
538 Enables transport-mode IPsec encapsulated security payload.
540 Enables transport-mode IPsec authentication header.
545 for fault isolation, it should first be run on the local host, to verify
546 that the local network interface is up and running.
547 Then, hosts and gateways further and further away should be
549 Round-trip times and packet loss statistics are computed.
550 If duplicate packets are received, they are not included in the packet
551 loss calculation, although the round trip time of these packets is used
552 in calculating the round-trip time statistics.
553 When the specified number of packets have been sent
555 or if the program is terminated with a
557 a brief summary is displayed, showing the number of packets sent and
558 received, and the minimum, mean, maximum, and standard deviation of
559 the round-trip times.
569 signal, the current number of packets sent and received, and the
570 minimum, mean, maximum, and standard deviation of the round-trip times
571 will be written to the standard output.
573 This program is intended for use in network testing, measurement and
575 Because of the load it can impose on the network, it is unwise to use
577 during normal operations or from automated scripts.
578 .Sh ICMP PACKET DETAILS
579 An IP header without options is 20 bytes.
583 packet contains an additional 8 bytes worth of
585 header followed by an arbitrary amount of data.
588 is given, this indicated the size of this extra piece of data
590 Thus the amount of data received inside of an IP packet of type
593 will always be 8 bytes more than the requested data space
598 If the data space is at least eight bytes large,
600 uses the first eight bytes of this space to include a timestamp which
601 it uses in the computation of round trip times.
602 If less than eight bytes of pad are specified, no round trip times are
604 .Sh DUPLICATE AND DAMAGED PACKETS
607 utility will report duplicate and damaged packets.
608 Duplicate packets should never occur when pinging a unicast address,
609 and seem to be caused by
610 inappropriate link-level retransmissions.
611 Duplicates may occur in many situations and are rarely
613 a good sign, although the presence of low levels of duplicates may not
614 always be cause for alarm.
615 Duplicates are expected when pinging a broadcast or multicast address,
616 since they are not really duplicates but replies from different hosts
619 Damaged packets are obviously serious cause for alarm and often
620 indicate broken hardware somewhere in the
622 packet's path (in the network or in the hosts).
623 .Sh TRYING DIFFERENT DATA PATTERNS
626 layer should never treat packets differently depending on the data
627 contained in the data portion.
628 Unfortunately, data-dependent problems have been known to sneak into
629 networks and remain undetected for long periods of time.
630 In many cases the particular pattern that will have problems is something
631 that does not have sufficient
633 such as all ones or all zeros, or a pattern right at the edge, such as
636 necessarily enough to specify a data pattern of all zeros (for example)
637 on the command line because the pattern that is of interest is
638 at the data link level, and the relationship between what you type and
639 what the controllers transmit can be complicated.
641 This means that if you have a data-dependent problem you will probably
642 have to do a lot of testing to find it.
643 If you are lucky, you may manage to find a file that either
645 be sent across your network or that takes much longer to transfer than
646 other similar length files.
647 You can then examine this file for repeated patterns that you can test
655 value of an IP packet represents the maximum number of IP routers
656 that the packet can go through before being thrown away.
657 In current practice you can expect each router in the Internet to decrement
660 field by exactly one.
664 specification recommends setting the
670 The maximum possible value of this field is 255, and some
678 This is why you will find you can
680 some hosts, but not reach them with
687 prints the ttl value from the packet it receives.
688 When a remote system receives a ping packet, it can do one of three things
691 field in its response:
694 Not change it; this is what
696 systems did before the
701 value in the received packet will be 255 minus the
702 number of routers in the round-trip path.
704 Set it to 64; this is what current
709 value in the received packet will be 64 minus the
710 number of routers in the path
718 Set it to some other value.
719 Some machines use the same value for
721 packets that they use for
723 packets, for example either 30 or 60.
724 Others may use completely wild values.
729 utility exits with one of the following values:
730 .Bl -tag -width indent
732 At least one response was heard from the specified
735 The transmission was successful but no responses were received.
740 The following will send ICMPv6 echo request to
741 .Li dst.example.com .
742 .Bd -literal -offset indent
743 ping -6 -n dst.example.com
746 The following will probe hostnames for all nodes on the network link attached to
751 is named the link-local all-node multicast address, and the packet would
752 reach every node on the network link.
753 .Bd -literal -offset indent
754 ping -6 -y ff02::1%wi0
757 The following will probe addresses assigned to the destination node,
758 .Li dst.example.com .
759 .Bd -literal -offset indent
760 ping -6 -k agl dst.example.com
775 .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
781 .%T "IPv6 Node Information Queries"
782 .%N draft-ietf-ipngwg-icmp-name-lookups-09.txt
784 .%O work in progress material
793 utility with IPv6 support first appeared in the WIDE Hydrangea IPv6
796 IPv6 and IPsec support based on the KAME Project
797 .Pq Pa https://www.kame.net/
798 stack was initially integrated into
803 utility was merged to
805 in Google Summer of Code 2019.
809 utility was written by
811 while at the US Army Ballistics
814 Many Hosts and Gateways ignore the IPv4
818 The maximum IP header length is too small for options like
820 to be completely useful.
822 not much that can be done about this, however.
824 Flood pinging is not recommended in general, and flood pinging the
825 broadcast address should only be done under very controlled conditions.
829 option is not worth much on busy hosts.
projects / FreeBSD / FreeBSD.git / blob