| blob | 9a3fd273cfeee2ed5a0cff99fa791c9f906f594d |
1 .\" $NetBSD: ping.8,v 1.46 2006/03/21 09:54:12 pavel Exp $
2 .\"
3 .\" Copyright (c) 1985, 1991, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)ping.8 8.2 (Berkeley) 12/11/93
31 .\"
32 .Dd March 21, 2006
33 .Dt PING 8
34 .Os
35 .Sh NAME
36 .Nm ping
37 .Nd send
38 .Tn ICMP ECHO_REQUEST
39 packets to network hosts
40 .Sh SYNOPSIS
41 .Nm
42 .Bk -words
43 .Op Fl adDfLnoPqQrRv
44 .Ek
45 .Bk -words
46 .Op Fl c Ar count
47 .Ek
48 .Bk -words
49 .Op Fl E Ar policy
50 .Ek
51 .Bk -words
52 .Op Fl g Ar gateway
53 .Ek
54 .Bk -words
55 .Op Fl h Ar host
56 .Ek
57 .Bk -words
58 .Op Fl i Ar interval
59 .Ek
60 .Bk -words
61 .Op Fl I Ar srcaddr
62 .Ek
63 .Bk -words
64 .Op Fl l Ar preload
65 .Ek
66 .Bk -words
67 .Op Fl p Ar pattern
68 .Ek
69 .Bk -words
70 .Op Fl s Ar packetsize
71 .Ek
72 .Bk -words
73 .Op Fl t Ar tos
74 .Ek
75 .Bk -words
76 .Op Fl T Ar ttl
77 .Ek
78 .Bk -words
79 .Op Fl w Ar deadline
80 .Ek
81 .Ar host
82 .Sh DESCRIPTION
83 .Nm
84 uses the
85 .Tn ICMP
86 protocol's mandatory
87 .Tn ECHO_REQUEST
88 datagram to elicit an
89 .Tn ICMP ECHO_RESPONSE
90 from a host or gateway.
91 .Tn ECHO_REQUEST
92 datagrams (``pings'') have an IP and
93 .Tn ICMP
94 header,
95 followed by a
96 .Dq struct timeval
97 and then an arbitrary number of ``pad'' bytes used to fill out the
98 packet.
99 The options are as follows:
100 .Bl -tag -width Ds
101 .It Fl a
102 Emit an audible beep (by sending an ascii BEL character to the
103 standard error output) after each non-duplicate response is received.
104 This is disabled for flood pings as it would probably cause temporary
105 insanity.
106 .It Fl c Ar count
107 Stop after sending (and waiting the specified delay to receive)
108 .Ar count
109 .Tn ECHO_RESPONSE
110 packets.
111 .It Fl d
112 Set the
113 .Dv SO_DEBUG
114 option on the socket being used.
115 .It Fl D
116 Set the
117 .Dv Don't Fragment
118 bit in the IP header.
119 This can be used to determine the path MTU.
120 .It Fl E Ar policy
121 Use IPsec policy specification string
122 .Ar policy
123 for packets.
124 For the format of specification string, please refer
125 .Xr ipsec_set_policy 3 .
126 Please note that this option is same as
127 .Fl P
128 in KAME/FreeBSD and KAME/BSDI
129 (as
130 .Fl P
131 was already occupied in
132 .Nx ) .
133 .It Fl f
134 Flood ping.
135 Outputs packets as fast as they come back or one hundred times per second,
136 whichever is more.
137 For every
138 .Tn ECHO_REQUEST
139 sent a period ``.'' is printed, while for every
140 .Tn ECHO_REPLY
141 received a backspace is printed.
142 This provides a rapid display of how many packets are being dropped.
143 Only the super-user may use this option.
144 .Bf -emphasis
145 This can be very hard on a network and should be used with caution.
146 .Ef
147 .It Fl g Ar gateway
148 Use Loose Source Routing to send the ECHO_REQUEST packets via
149 .Ar gateway .
150 .It Fl i Ar interval
151 Wait
152 .Ar interval
153 seconds
154 .Em between sending each packet .
155 The default is to wait for one second between each packet,
156 except when the -f option is used the wait interval is 0.01 seconds.
157 .It Fl I Ar srcaddr
158 Set the source IP address to
159 .Ar srcaddr
160 which can be a hostname or an IP number.
161 For multicast datagrams, it also specifies the outgoing interface.
162 .It Fl h Ar host
163 is an alternate way of specifying the target host instead of as the
164 last argument.
165 .It Fl l Ar preload
166 If
167 .Ar preload
168 is specified,
169 .Nm
170 sends that many packets as fast as possible before falling into its normal
171 mode of behavior.
172 Only the super-user may use this option.
173 .It Fl L
174 Disable loopback when sending to multicast destinations,
175 so the transmitting host doesn't see the ICMP requests.
176 .It Fl n
177 Numeric output only.
178 No attempt will be made to look up symbolic names for host addresses.
179 .It Fl o
180 Exit successfully after receiving one reply packet.
181 .It Fl p Ar pattern
182 You may specify up to 16 ``pad'' bytes to fill out the packet you send.
183 This is useful for diagnosing data-dependent problems in a network.
184 For example,
185 .Dq Li \-p ff
186 will cause the sent packet to be filled with all
187 ones.
188 .It Fl P
189 Use a pseudo-random sequence for the data instead of the default,
190 fixed sequence of incrementing 8-bit integers.
191 This is useful to foil compression on PPP and other links.
192 .It Fl q
193 Quiet output.
194 Nothing is displayed except the summary lines at startup time and
195 when finished.
196 .It Fl Q
197 Do not display responses such as Network Unreachable ICMP messages
198 concerning the ECHO_REQUESTs sent.
199 .It Fl r
200 Bypass the normal routing tables and send directly to a host on an attached
201 network.
202 If the host is not on a directly-attached network, an error is returned.
203 This option can be used to ping a local host through an interface
204 that has no route through it (e.g., after the interface was dropped by
205 .Xr routed 8 ) .
206 .It Fl R
207 Record Route.
208 Includes the
209 .Tn RECORD_ROUTE
210 option in the
211 .Tn ECHO_REQUEST
212 packet and displays the route buffer on returned packets.
213 This should show the path to the target host and back, which is
214 especially useful in the case of asymmetric routing.
215 Note that the IP header is only large enough for nine such addresses,
216 and only seven when using the
217 .Fl g
218 option.
219 This is why it was necessary to invent
220 .Xr traceroute 8 .
221 Many hosts ignore or discard this option.
222 .It Fl s Ar packetsize
223 Specifies the number of data bytes to be sent.
224 The default is 56, which translates into 64
225 .Tn ICMP
226 data bytes when combined
227 with the 8 bytes of
228 .Tn ICMP
229 header data.
230 The maximum allowed value is 65467 bytes.
231 .It Fl T Ar ttl
232 Use the specified time-to-live.
233 .It Fl t Ar tos
234 Use the specified hexadecimal type of service.
235 .It Fl v
236 Verbose output.
237 .Tn ICMP
238 packets other than
239 .Tn ECHO_RESPONSE
240 that are received are listed.
241 .It Fl w Ar deadline
242 Specifies a timeout, in seconds, before ping exits regardless of
243 how many packets have been sent or received.
244 .El
245 .Pp
246 When using
247 .Nm
248 for fault isolation, it should first be run on the local host, to verify
249 that the local network interface is up and running.
250 Then, hosts and gateways further and further away should be ``pinged''.
251 .Pp
252 Round-trip times and packet loss statistics are computed.
253 If duplicate packets are received, they are not included in the packet
254 loss calculation, although the round trip time of these packets is used
255 in calculating the minimum/average/maximum round-trip time numbers.
256 .Pp
257 When the specified number of packets have been sent (and received) or
258 if the program is terminated with a
259 .Dv SIGINT ,
260 a brief summary is displayed.
261 The summary information can be displayed while
262 .Nm
263 is running by sending it a
264 .Dv SIGINFO
265 signal (see the
266 .Dq status
267 argument for
268 .Xr stty 1
269 for more information).
270 .Pp
271 .Nm
272 continually sends one datagram per second, and prints one line of
273 output for every ECHO_RESPONSE returned.
274 On a trusted system with IP
275 Security Options enabled, if the network idiom is not MONO,
276 .Nm
277 also prints a second line containing the hexadecimal representation
278 of the IP security option in the ECHO_RESPONSE.
279 If the
280 .Fl c
281 count option is given, only that number of requests is sent.
282 No output is produced if there is no response.
283 Round-trip times and packet loss statistics are computed.
284 If duplicate packets are received,
285 they are not included in the packet loss calculation,
286 although the round trip time of these packets is used in calculating
287 the minimum/average/maximum round-trip time numbers.
288 When the specified number of packets have been sent (and received) or if
289 the program is terminated with an interrupt (SIGINT), a brief
290 summary is displayed.
291 When not using the
292 .Fl f
293 (flood) option, the first interrupt, usually generated by control-C or DEL,
294 causes
295 .Nm
296 to wait for its outstanding requests to return.
297 It will wait no longer than the longest round trip time
298 encountered by previous, successful pings.
299 The second interrupt stops ping immediately.
300 .Pp
301 This program is intended for use in network testing, measurement and
302 management.
303 Because of the load it can impose on the network, it is unwise to use
304 .Nm
305 during normal operations or from automated scripts.
306 .Sh ICMP PACKET DETAILS
307 An IP header without options is 20 bytes.
308 An
309 .Tn ICMP
310 .Tn ECHO_REQUEST
311 packet contains an additional 8 bytes worth of
312 .Tn ICMP
313 header followed by an arbitrary amount of data.
314 When a
315 .Ar packetsize
316 is given, this indicated the size of this extra piece of data (the
317 default is 56).
318 Thus the amount of data received inside of an IP packet of type
319 .Tn ICMP
320 .Tn ECHO_REPLY
321 will always be 8 bytes more than the requested data space (the
322 .Tn ICMP
323 header).
324 .Pp
325 If the data space is at least eight bytes large,
326 .Nm
327 uses the first eight bytes of this space to include a timestamp to compute
328 round trip times.
329 If less than eight bytes of pad are specified,
330 no round trip times are given.
331 .Sh DUPLICATE AND DAMAGED PACKETS
332 .Nm
333 will report duplicate and damaged packets.
334 Duplicate packets should never occur, and seem to be caused by
335 inappropriate link-level retransmissions.
336 Duplicates may occur in many situations and are rarely (if ever) a
337 good sign, although the presence of low levels of duplicates may not
338 always be cause for alarm.
339 .Pp
340 Damaged packets are obviously serious cause for alarm and often
341 indicate broken hardware somewhere in the
342 .Nm
343 packet's path (in the network or in the hosts).
344 .Sh TRYING DIFFERENT DATA PATTERNS
345 The (inter)network layer should never treat packets differently depending
346 on the data contained in the data portion.
347 Unfortunately, data-dependent problems have been known to sneak into
348 networks and remain undetected for long periods of time.
349 In many cases the particular pattern that will have problems is something
350 that doesn't have sufficient ``transitions'', such as all ones or all
351 zeros, or a pattern right at the edge, such as almost all zeros.
352 It isn't necessarily enough to specify a data pattern of all zeros (for
353 example) on the command line because the pattern that is of interest is
354 at the data link level, and the relationship between what you type and
355 what the controllers transmit can be complicated.
356 .Pp
357 This means that if you have a data-dependent problem you will probably
358 have to do a lot of testing to find it.
359 If you are lucky, you may manage to find a file that either can't be sent
360 across your network or that takes much longer to transfer than other
361 similar length files.
362 You can then examine this file for repeated patterns that you can test
363 using the
364 .Fl p
365 option of
366 .Nm .
367 .Sh TTL DETAILS
368 The
369 .Tn TTL
370 value of an IP packet represents the maximum number of IP routers
371 that the packet can go through before being thrown away.
372 In current practice you can expect each router in the Internet to decrement
373 the
374 .Tn TTL
375 field by exactly one.
376 .Pp
377 The
378 .Tn TCP/IP
379 specification states that the
380 .Tn TTL
381 field for
382 .Tn TCP
383 packets should
384 be set to 60, but many systems use smaller values
385 .Po
386 .Bx 4.3
387 uses 30,
388 .Bx 4.2
389 used 15
390 .Pc .
391 .Pp
392 The maximum possible value of this field is 255, and most
393 .Ux
394 systems set the
395 .Tn TTL
396 field of
397 .Tn ICMP ECHO_REQUEST
398 packets to 255.
399 This is why you will find you can ``ping'' some hosts, but not reach them
400 with
401 .Xr telnet 1
402 or
403 .Xr ftp 1 .
404 .Pp
405 In normal operation ping prints the ttl value from the packet it receives.
406 When a remote system receives a ping packet, it can do one of three things
407 with the
408 .Tn TTL
409 field in its response:
410 .Bl -bullet
411 .It
412 Not change it; this is what Berkeley
413 .Ux
414 systems did before the
415 .Bx 4.3 tahoe
416 release.
417 In this case the
418 .Tn TTL
419 value in the received packet will be 255 minus the
420 number of routers in the round-trip path.
421 .It
422 Set it to 255; this is what current Berkeley
423 .Ux
424 systems do.
425 In this case the
426 .Tn TTL
427 value in the received packet will be 255 minus the
428 number of routers in the path
429 .Em from
430 the remote system
431 .Em to
432 the
433 .Nm Ns Em ing
434 host.
435 .It
436 Set it to some other value.
437 Some machines use the same value for
438 .Tn ICMP
439 packets that they use for
440 .Tn TCP
441 packets, for example either 30 or 60.
442 Others may use completely wild values.
443 .El
444 .Sh EXIT STATUS
445 .Nm
446 returns 0 on success (the host is alive),
447 and non-zero if the arguments are incorrect or the host is not responding.
448 .Sh SEE ALSO
449 .Xr netstat 1 ,
450 .Xr icmp 4 ,
451 .Xr inet 4 ,
452 .Xr ip 4 ,
453 .Xr ifconfig 8 ,
454 .Xr routed 8 ,
455 .Xr spray 8 ,
456 .Xr traceroute 8
457 .Sh HISTORY
458 The
459 .Nm
460 command appeared in
461 .Bx 4.3 .
462 IPsec support was added by WIDE/KAME project.
463 .Sh BUGS
464 Flood pinging is not recommended in general, and flood pinging a broadcast
465 or multicast address should only be done under very controlled conditions.
466 .Pp
467 The
468 .Nm
469 program has evolved differently under different operating systems,
470 and in some cases the same flag performs a different function
471 under different operating systems.
472 The
473 .Fl t
474 flag conflicts with
475 .Fx .
476 The
477 .Fl a , c , i , I ,
478 .Fl l , p , P , s ,
479 and
480 .Fl t
481 flags conflict with
482 .Sy Solaris .
483 .Pp
484 Some hosts and gateways ignore the
485 .Tn RECORD_ROUTE
486 option.
487 .Pp
488 The maximum IP header length is too small for options like
489 .Tn RECORD_ROUTE
490 to
491 be completely useful.
492 There's not much that that can be done about this, however.