xref: /freebsd/sbin/ping/ping.8 (revision 7f3dea244c40159a41ab22da77a434d7c5b5e85a)
1.\" Copyright (c) 1985, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
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. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)ping.8	8.2 (Berkeley) 12/11/93
33.\" $FreeBSD$
34.\"
35.Dd March 1, 1997
36.Dt PING 8
37.Os BSD 4.3
38.Sh NAME
39.Nm ping
40.Nd send
41.Tn ICMP ECHO_REQUEST
42packets to network hosts
43.Sh SYNOPSIS
44.Nm ping
45.Op Fl QRadfnqrv
46.Op Fl c Ar count
47.Op Fl i Ar wait
48.Op Fl l Ar preload
49.Op Fl p Ar pattern
50.Op Fl s Ar packetsize
51.Op Fl S Ar src_addr
52.Bo
53.Ar host |
54.Op Fl L
55.Op Fl I Ar interface
56.Op Fl T Ar ttl
57.Ar mcast-group
58.Bc
59.Sh DESCRIPTION
60.Nm Ping
61uses the
62.Tn ICMP
63.No protocol Ap s mandatory
64.Tn ECHO_REQUEST
65datagram to elicit an
66.Tn ICMP ECHO_RESPONSE
67from a host or gateway.
68.Tn ECHO_REQUEST
69datagrams
70.Pq Dq pings
71have an IP and
72.Tn ICMP
73header, followed by a
74.Dq struct timeval
75and then an arbitrary number of
76.Dq pad
77bytes used to fill out the packet.  The options are as follows:
78.Bl -tag -width indent
79.It Fl a
80Audible. Include a bell
81.Pq ASCII 0x07
82character in the output when any packet is received. This option is ignored
83if other format options are present.
84.It Fl c Ar count
85Stop after sending
86.Pq and receiving
87.Ar count
88.Tn ECHO_RESPONSE
89packets.
90If this option is not specified,
91.Nm
92will operate until interrupted.
93.It Fl d
94Set the
95.Dv SO_DEBUG
96option on the socket being used.
97.It Fl f
98Flood ping.
99Outputs packets as fast as they come back or one hundred times per second,
100whichever is more.
101For every
102.Tn ECHO_REQUEST
103sent a period
104.Dq \&.
105is printed, while for every
106.Tn ECHO_REPLY
107received a backspace is printed.
108This provides a rapid display of how many packets are being dropped.
109Only the super-user may use this option.
110.Bf -emphasis
111This can be very hard on a network and should be used with caution.
112.Ef
113.It Fl i Ar wait
114Wait
115.Ar wait
116seconds
117.Em between sending each packet .
118The default is to wait for one second between each packet.
119The wait time may be fractional, but only the super-user may specify
120values less then 1 second.
121This option is incompatible with the
122.Fl f
123option.
124.It Fl I Ar interface
125Source multicast packets with the given interface address.
126This flag only applies if the ping destination is a multicast address.
127.It Fl l Ar preload
128If
129.Ar preload
130is specified,
131.Nm
132sends that many packets as fast as possible before falling into its normal
133mode of behavior.
134Only the super-user may use this option.
135.It Fl L
136Suppress loopback of multicast packets.
137This flag only applies if the ping destination is a multicast address.
138.It Fl n
139Numeric output only.
140No attempt will be made to lookup symbolic names for host addresses.
141.It Fl p Ar pattern
142You may specify up to 16
143.Dq pad
144bytes to fill out the packet you send.
145This is useful for diagnosing data-dependent problems in a network.
146For example,
147.Dq Li \-p ff
148will cause the sent packet to be filled with all
149ones.
150.It Fl Q
151Somewhat quiet output.
152.No Don Ap t
153display ICMP error messages that are in response to our query messages.
154Originally, the
155.Fl v
156flag was required to display such errors, but
157.Fl v
158displays all ICMP error messages.  On a busy machine, this output can
159be overbearing.  Without the
160.Fl Q
161flag,
162.Nm
163prints out any ICMP error messages caused by its own ECHO_REQUEST
164messages.
165.It Fl q
166Quiet output.
167Nothing is displayed except the summary lines at startup time and
168when finished.
169.It Fl R
170Record route.
171Includes the
172.Tn RECORD_ROUTE
173option in the
174.Tn ECHO_REQUEST
175packet and displays
176the route buffer on returned packets.
177Note that the IP header is only large enough for nine such routes;
178the
179.Xr traceroute 8
180command is usually better at determining the route packets take to a
181particular destination.
182If more routes come back than should, such as due to an illegal spoofed
183packet, ping will print the route list and then truncate it at the correct
184spot.
185Many hosts ignore or discard the
186.Tn RECORD_ROUTE
187option.
188.It Fl r
189Bypass the normal routing tables and send directly to a host on an attached
190network.
191If the host is not on a directly-attached network, an error is returned.
192This option can be used to ping a local host through an interface
193that has no route through it
194.Po
195e.g., after the interface was dropped by
196.Xr routed 8
197.Pc .
198.It Fl s Ar packetsize
199Specify the number of data bytes to be sent.
200The default is 56, which translates into 64
201.Tn ICMP
202data bytes when combined
203with the 8 bytes of
204.Tn ICMP
205header data.
206Only the super-user may use this option.
207.It Fl S Ar src_addr
208Use the following IP address as the source address in outgoing packets.
209On hosts with more than one IP address, this option can be used to
210force the source address to be something other than the IP address
211of the interface the probe packet is sent on.  If the IP address
212is not one of this machine's interface addresses, an error is
213returned and nothing is sent.
214.It Fl T Ar ttl
215Set the IP Time To Live for multicasted packets.
216This flag only applies if the ping destination is a multicast address.
217.It Fl v
218Verbose output.
219.Tn ICMP
220packets other than
221.Tn ECHO_RESPONSE
222that are received are listed.
223.El
224.Pp
225When using
226.Nm
227for fault isolation, it should first be run on the local host, to verify
228that the local network interface is up and running.
229Then, hosts and gateways further and further away should be
230.Dq pinged .
231Round-trip times and packet loss statistics are computed.
232If duplicate packets are received, they are not included in the packet
233loss calculation, although the round trip time of these packets is used
234in calculating the round-trip time statistics.
235When the specified number of packets have been sent
236.Pq and received
237or if the program is terminated with a
238.Dv SIGINT ,
239a brief summary is displayed, showing the number of packets sent and
240received, and the minimum, maximum, mean, and standard deviation of
241the round-trip times.
242.Pp
243This program is intended for use in network testing, measurement and
244management.
245Because of the load it can impose on the network, it is unwise to use
246.Nm
247during normal operations or from automated scripts.
248.Sh ICMP PACKET DETAILS
249An IP header without options is 20 bytes.
250An
251.Tn ICMP
252.Tn ECHO_REQUEST
253packet contains an additional 8 bytes worth of
254.Tn ICMP
255header followed by an arbitrary amount of data.
256When a
257.Ar packetsize
258is given, this indicated the size of this extra piece of data
259.Pq the default is 56 .
260Thus the amount of data received inside of an IP packet of type
261.Tn ICMP
262.Tn ECHO_REPLY
263will always be 8 bytes more than the requested data space
264.Pq the Tn ICMP header .
265.Pp
266If the data space is at least eight bytes large,
267.Nm
268uses the first eight bytes of this space to include a timestamp which
269it uses in the computation of round trip times.
270If less than eight bytes of pad are specified, no round trip times are
271given.
272.Sh DUPLICATE AND DAMAGED PACKETS
273.Nm Ping
274will report duplicate and damaged packets.
275Duplicate packets should never occur when pinging a unicast address,
276and seem to be caused by
277inappropriate link-level retransmissions.
278Duplicates may occur in many situations and are rarely
279.Pq if ever
280a good sign, although the presence of low levels of duplicates may not
281always be cause for alarm.
282Duplicates are expected when pinging a broadcast or multicast address,
283since they are not really duplicates but replies from different hosts
284to the same request.
285.Pp
286Damaged packets are obviously serious cause for alarm and often
287indicate broken hardware somewhere in the
288.Nm
289packet's path (in the network or in the hosts).
290.Sh TRYING DIFFERENT DATA PATTERNS
291The
292(inter)network
293layer should never treat packets differently depending on the data
294contained in the data portion.
295Unfortunately, data-dependent problems have been known to sneak into
296networks and remain undetected for long periods of time.
297In many cases the particular pattern that will have problems is something
298that does not have sufficient
299.Dq transitions ,
300such as all ones or all zeros, or a pattern right at the edge, such as
301almost all zeros.
302It is not
303necessarily enough to specify a data pattern of all zeros (for example)
304on the command line because the pattern that is of interest is
305at the data link level, and the relationship between what you type and
306what the controllers transmit can be complicated.
307.Pp
308This means that if you have a data-dependent problem you will probably
309have to do a lot of testing to find it.
310If you are lucky, you may manage to find a file that either
311cannot
312be sent across your network or that takes much longer to transfer than
313other similar length files.
314You can then examine this file for repeated patterns that you can test
315using the
316.Fl p
317option of
318.Nm Ns .
319.Sh TTL DETAILS
320The
321.Tn TTL
322value of an IP packet represents the maximum number of IP routers
323that the packet can go through before being thrown away.
324In current practice you can expect each router in the Internet to decrement
325the
326.Tn TTL
327field by exactly one.
328.Pp
329The
330.Tn TCP/IP
331specification states that the
332.Tn TTL
333field for
334.Tn TCP
335packets should be set to 60, but many systems use smaller values
336.Po
337.Bx 4.3
338uses 30,
339.Bx 4.2
340used 15
341.Pc .
342.Pp
343The maximum possible value of this field is 255, and most
344.Ux
345systems set
346the
347.Tn TTL
348field of
349.Tn ICMP ECHO_REQUEST
350packets to 255.
351This is why you will find you can
352.Dq ping
353some hosts, but not reach them with
354.Xr telnet 1
355or
356.Xr ftp 1 .
357.Pp
358In normal operation
359.Nm
360prints the ttl value from the packet it receives.
361When a remote system receives a ping packet, it can do one of three things
362with the
363.Tn TTL
364field in its response:
365.Bl -bullet
366.It
367Not change it; this is what
368.Bx
369systems did before the
370.Bx 4.3 tahoe
371release.
372In this case the
373.Tn TTL
374value in the received packet will be 255 minus the
375number of routers in the round-trip path.
376.It
377Set it to 255; this is what current
378.Bx
379systems do.
380In this case the
381.Tn TTL
382value in the received packet will be 255 minus the
383number of routers in the path
384.Em from
385the remote system
386.Em to
387the
388.Nm Ns Em ing
389host.
390.It
391Set it to some other value.
392Some machines use the same value for
393.Tn ICMP
394packets that they use for
395.Tn TCP
396packets, for example either 30 or 60.
397Others may use completely wild values.
398.El
399.Sh RETURN VALUES
400The
401.Nm
402command returns an exit status of zero if at least one response was
403heard from the specified
404.Ar host ;
405a status of two if the transmission was successful but no responses
406were received; or another value
407.Pq from Aq Pa sysexits.h
408if an error occurred.
409.Sh SEE ALSO
410.Xr netstat 1 ,
411.Xr ifconfig 8 ,
412.Xr routed 8 ,
413.Xr traceroute 8
414.Sh HISTORY
415The
416.Nm
417command appeared in
418.Bx 4.3 .
419.Sh AUTHORS
420The original
421.Nm
422command was written by
423.An Mike Muuss
424while at the US Army Ballistics
425Research Laboratory.
426.Sh BUGS
427Many Hosts and Gateways ignore the
428.Tn RECORD_ROUTE
429option.
430.Pp
431The maximum IP header length is too small for options like
432.Tn RECORD_ROUTE
433to be completely useful.
434.No There Ap s
435not much that can be done about this, however.
436.Pp
437Flood pinging is not recommended in general, and flood pinging the
438broadcast address should only be done under very controlled conditions.
439.Pp
440The
441.Fl v
442option is not worth much on busy hosts.
443