xref: /openbsd-src/sbin/ping/ping.8 (revision f2da64fbbbf1b03f09f390ab01267c93dfd77c4c)
1.\"	$OpenBSD: ping.8,v 1.57 2016/09/20 12:32:35 jmc Exp $
2.\"	$NetBSD: ping.8,v 1.10 1995/12/31 04:55:35 ghudson Exp $
3.\"
4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. Neither the name of the project nor the names of its contributors
16.\"    may be used to endorse or promote products derived from this software
17.\"    without specific prior written permission.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29.\" SUCH DAMAGE.
30.\"
31.\" Copyright (c) 1985, 1991, 1993
32.\"	The Regents of the University of California.  All rights reserved.
33.\"
34.\" Redistribution and use in source and binary forms, with or without
35.\" modification, are permitted provided that the following conditions
36.\" are met:
37.\" 1. Redistributions of source code must retain the above copyright
38.\"    notice, this list of conditions and the following disclaimer.
39.\" 2. Redistributions in binary form must reproduce the above copyright
40.\"    notice, this list of conditions and the following disclaimer in the
41.\"    documentation and/or other materials provided with the distribution.
42.\" 3. Neither the name of the University nor the names of its contributors
43.\"    may be used to endorse or promote products derived from this software
44.\"    without specific prior written permission.
45.\"
46.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
47.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
48.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
49.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
50.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
51.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
52.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
54.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
56.\" SUCH DAMAGE.
57.\"
58.\"     @(#)ping.8	8.2 (Berkeley) 12/11/93
59.\"
60.Dd $Mdocdate: September 20 2016 $
61.Dt PING 8
62.Os
63.Sh NAME
64.Nm ping ,
65.Nm ping6
66.Nd send ICMP ECHO_REQUEST packets to network hosts
67.Sh SYNOPSIS
68.Nm ping
69.Op Fl DdEefHLnqRv
70.Op Fl c Ar count
71.Op Fl I Ar ifaddr
72.Op Fl i Ar wait
73.Op Fl l Ar preload
74.Op Fl p Ar pattern
75.Op Fl s Ar packetsize
76.Op Fl T Ar toskeyword
77.Op Fl t Ar ttl
78.Op Fl V Ar rtable
79.Op Fl w Ar maxwait
80.Ar host
81.Nm ping6
82.Op Fl dEefHLmnqv
83.Op Fl c Ar count
84.Op Fl h Ar hoplimit
85.Op Fl I Ar sourceaddr
86.Op Fl i Ar wait
87.Op Fl l Ar preload
88.Op Fl p Ar pattern
89.Op Fl s Ar packetsize
90.Op Fl V Ar rtable
91.Op Fl w Ar maxwait
92.Ar host
93.Sh DESCRIPTION
94.Nm
95uses the ICMP protocol's mandatory
96.Dv ECHO_REQUEST
97datagram to elicit an ICMP
98.Dv ECHO_REPLY
99from a host or gateway.
100These datagrams
101.Pq pings
102have an IP and ICMP header,
103followed by a
104.Qq struct timeval
105and then an arbitrary number of pad bytes used to fill out the packet.
106.Pp
107The options are as follows:
108.Bl -tag -width Ds
109.It Fl c Ar count
110Stop sending after
111.Ar count
112.Dv ECHO_REQUEST
113packets have been sent.
114If
115.Ar count
116is 0, send an unlimited number of packets.
117.It Fl D
118.Pq IPv4 only
119Set the
120.Dv Don't Fragment
121bit.
122.It Fl d
123Set the
124.Dv SO_DEBUG
125option on the socket being used.
126This option has no effect on
127.Ox .
128.It Fl E
129Emit an audible beep (by sending an ASCII BEL character to the
130standard error output) when no packet is received before the next
131packet is transmitted.
132To cater for round-trip times that are longer than the interval between
133transmissions, further missing packets cause a bell only if the maximum
134number of unreceived packets has increased.
135This option is disabled for flood pings.
136.It Fl e
137Emit an audible beep (by sending an ASCII BEL character to the
138standard error output) after each non-duplicate response is received.
139This option is disabled for flood pings.
140.It Fl f
141Flood ping.
142Outputs packets as fast as they come back or one hundred times per second,
143whichever is more.
144For every
145.Dv ECHO_REQUEST
146sent, a period
147.Sq \&.
148is printed, while for every
149.Dv ECHO_REPLY
150received a backspace is printed.
151This provides a rapid display of how many packets are being dropped.
152Only the superuser may use this option.
153.Bf -emphasis
154This can be very hard on a network and should be used with caution.
155.Ef
156.It Fl H
157Try reverse lookups for addresses.
158.It Fl h Ar hoplimit
159.Pq IPv6 only
160Set the hoplimit.
161.It Fl I Ar ifaddr
162Specify the interface address to transmit from
163on machines with multiple interfaces.
164For unicast and multicast pings.
165.It Fl i Ar wait
166Wait
167.Ar wait
168seconds between sending each packet.
169The default is to wait for one second between each packet.
170The wait time may be fractional, but only the superuser may specify
171a value less than one second.
172This option is incompatible with the
173.Fl f
174option.
175.It Fl L
176Disable the loopback, so the transmitting host doesn't see the ICMP
177requests.
178For multicast pings.
179.It Fl l Ar preload
180Send
181.Ar preload
182packets as fast as possible before reverting to normal behavior.
183Only root may set a preload value.
184.It Fl m
185.Pq IPv6 only
186Do not fragment unicast packets to fit the minimum IPv6 MTU.
187If specified twice,
188do this for multicast packets as well.
189.It Fl n
190Numeric output only.
191No attempt will be made to look up symbolic names from addresses in the reply.
192.It Fl p Ar pattern
193Specify up to 16 pad bytes to fill out the packet sent.
194This is useful for diagnosing data-dependent problems in a network.
195For example,
196.Qq -p ff
197causes the sent packet to be filled with all ones.
198.It Fl q
199Quiet output.
200Nothing is displayed except the summary lines at startup time and
201when finished.
202.It Fl R
203.Pq IPv4 only
204Record route.
205Includes the
206.Dv RECORD_ROUTE
207option in the
208.Dv ECHO_REQUEST
209packet and displays
210the route buffer on returned packets.
211Note that the IP header is only large enough for nine such routes.
212If more routes come back than should, such as due to an illegal spoofed
213packet,
214.Nm
215will print the route list and then truncate it at the correct spot.
216Many hosts ignore or discard this option.
217.It Fl s Ar packetsize
218Specify the number of data bytes to be sent.
219The default is 56,
220which translates into 64 ICMP data bytes
221when combined with the 8 bytes of ICMP header data.
222The maximum packet size is 65467 for IPv4 and 65527 for IPv6.
223.It Fl T Ar toskeyword
224.Pq IPv4 only
225Change the TOS value.
226.Ar toskeyword
227may be one of
228.Cm critical ,
229.Cm inetcontrol ,
230.Cm lowdelay ,
231.Cm netcontrol ,
232.Cm throughput ,
233.Cm reliability ,
234or one of the DiffServ Code Points:
235.Cm ef ,
236.Cm af11 ... af43 ,
237.Cm cs0 ... cs7 ;
238or a number in either hex or decimal.
239.It Fl t Ar ttl
240.Pq IPv4 only
241Use the specified time-to-live.
242.It Fl V Ar rtable
243Set the routing table to be used for outgoing packets.
244.It Fl v
245Verbose output.
246ICMP packets other than
247.Dv ECHO_REPLY
248that are received are listed.
249.It Fl w Ar maxwait
250Specify the maximum number of seconds to wait for responses
251after the last request has been sent.
252The default is 10.
253.El
254.Pp
255When using
256.Nm
257for fault isolation, it should first be run on the local host to verify
258that the local network interface is up and running.
259Then, hosts and gateways further and further away should be
260.Dq pinged .
261.Pp
262Round trip times and packet loss statistics are computed.
263If duplicate packets are received, they are not included in the packet
264loss calculation, although the round trip time of these packets is used
265in calculating the minimum/average/maximum round trip time numbers and
266the standard deviation.
267.Pp
268When the specified number of packets have been
269sent (and received), or if the program is terminated with a
270.Dv SIGINT ,
271a brief summary is displayed.
272The summary information can also be displayed while
273.Nm
274is running by sending it a
275.Dv SIGINFO
276signal (see the
277.Cm status
278argument of
279.Xr stty 1
280for more information).
281.Pp
282This program is intended for use in network testing, measurement and
283management.
284Because of the load it can impose on the network, it is unwise to use
285.Nm
286during normal operations or from automated scripts.
287.Sh ICMP PACKET DETAILS
288An IP header without options is 20 bytes.
289An ICMP
290.Dv ECHO_REQUEST
291packet contains an additional 8 bytes worth of
292ICMP header followed by an arbitrary amount of data.
293When a
294.Ar packetsize
295is given, this indicates the size of this extra piece of data (the
296default is 56).
297Thus the amount of data received inside of an IP packet of type ICMP
298.Dv ECHO_REPLY
299will always be 8 bytes more than the requested data space
300(the ICMP header).
301.Pp
302If the data space is at least eight bytes large,
303.Nm
304uses the first eight bytes of this space to include a timestamp which
305it uses in the computation of round trip times.
306If less than eight bytes of pad are specified, no round trip times are
307given.
308.Sh DUPLICATE AND DAMAGED PACKETS
309.Nm
310will report duplicate and damaged packets.
311Duplicate packets should never occur, and seem to be caused by
312inappropriate link-level retransmissions.
313Duplicates may occur in many situations and are rarely (if ever) a
314good sign, although the presence of low levels of duplicates may not
315always be cause for alarm.
316.Pp
317Damaged packets are obviously serious cause for alarm and often
318indicate broken hardware somewhere in the
319.Nm
320packet's path (in the network or in the hosts).
321.Sh TRYING DIFFERENT DATA PATTERNS
322The (inter)network layer should never treat packets differently depending
323on the data contained in the data portion.
324Unfortunately, data-dependent problems have been known to sneak into
325networks and remain undetected for long periods of time.
326In many cases the particular pattern that will have problems is something
327that doesn't have sufficient
328.Dq transitions ,
329such as all ones or all
330zeros, or a pattern right at the edge, such as almost all zeros.
331It isn't necessarily enough to specify a data pattern of all zeros (for
332example) on the command line because the pattern that is of interest is
333at the data link level, and the relationship between what you type and
334what the controllers transmit can be complicated.
335.Pp
336This means that if you have a data-dependent problem you will probably
337have to do a lot of testing to find it.
338If you are lucky, you may manage to find a file that either can't be sent
339across your network or that takes much longer to transfer than other
340similar length files.
341You can then examine this file for repeated patterns that you can test
342using the
343.Fl p
344option of
345.Nm ping .
346.Sh TTL DETAILS
347The TTL value of an IP packet represents the maximum number of IP routers
348that the packet can go through before being thrown away.
349In current practice you can expect each router in the Internet to decrement
350the TTL field by exactly one.
351.Pp
352The TCP/IP specification states that the TTL field
353for TCP packets should be set to 60,
354but many systems use smaller values
355.Po
356.Bx 4.3
357uses 30,
358.Bx 4.2
359used 15
360.Pc .
361.Pp
362The maximum possible value of this field is 255, and most
363.Ux
364systems set the TTL field of ICMP
365.Dv ECHO_REQUEST
366packets to 255.
367This is why you will find you can
368.Dq ping
369some hosts, but not reach them
370with
371.Xr telnet 1
372or
373.Xr ftp 1 .
374.Pp
375In normal operation,
376.Nm
377prints the TTL value from the packet it receives.
378When a remote system receives a ping packet, it can do one of three things
379with the TTL field in its response:
380.Bl -bullet
381.It
382Not change it; this is what Berkeley
383.Ux
384systems did before the
385.Bx 4.3 Tahoe
386release.
387In this case the TTL value in the received packet will be
388255 minus the number of routers in the round trip path.
389.It
390Set it to 255; this is what current Berkeley
391.Ux
392systems do.
393In this case the TTL value in the received packet will be
394255 minus the number of routers in the path from the remote system
395to the pinging host.
396.It
397Set it to some other value.
398Some machines use the same value for ICMP packets
399that they use for TCP packets, for example either 30 or 60.
400Others may use completely wild values.
401.El
402.Sh EXIT STATUS
403.Nm
404exits 0 if at least one reply is received,
405and >0 if no reply is received or an error occurred.
406.Sh SEE ALSO
407.Xr netstat 1 ,
408.Xr ifconfig 8
409.Sh HISTORY
410The
411.Nm
412command appeared in
413.Bx 4.3 .
414The
415.Nm ping6
416command was originally a separate program
417and first appeared in the WIDE Hydrangea IPv6 protocol stack kit.
418.Sh BUGS
419Many hosts and gateways ignore the
420.Dv RECORD_ROUTE
421option.
422.Pp
423The maximum IP header length is too small for options like
424.Dv RECORD_ROUTE
425to
426be completely useful.
427There's not much that can be done about this, however.
428.Pp
429Flood pinging is not recommended in general, and flood pinging the
430broadcast address should only be done under very controlled conditions.
431