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