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