Commit | Line | Data |
---|---|---|
78288025 KB |
1 | .\" Copyright (c) 1985 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms are permitted | |
5 | .\" provided that the above copyright notice and this paragraph are | |
6 | .\" duplicated in all such forms and that any documentation, | |
7 | .\" advertising materials, and other materials related to such | |
8 | .\" distribution and use acknowledge that the software was developed | |
9 | .\" by the University of California, Berkeley. The name of the | |
10 | .\" University may not be used to endorse or promote products derived | |
11 | .\" from this software without specific prior written permission. | |
12 | .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR | |
13 | .\" IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED | |
14 | .\" WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. | |
15 | .\" | |
16 | .\" @(#)ping.8 6.5 (Berkeley) %G% | |
17 | .\" | |
18 | .TH PING 8 "" | |
19 | .UC 6 | |
9aecb40e KM |
20 | .SH NAME |
21 | ping \- send ICMP ECHO_REQUEST packets to network hosts | |
22 | .SH SYNOPSIS | |
78288025 | 23 | .B ping |
9aecb40e | 24 | [ |
63ed9e52 KB |
25 | .B -dfnqrvR |
26 | ][ | |
27 | .B -c | |
28 | count][ | |
29 | .B -i | |
30 | wait][ | |
31 | .B -l | |
32 | preload][ | |
33 | .B -p | |
34 | pattern][ | |
35 | .B -s | |
36 | packetsize] | |
9aecb40e | 37 | .SH DESCRIPTION |
9aecb40e | 38 | .I Ping |
63ed9e52 | 39 | uses the |
d53739b5 MK |
40 | ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an |
41 | ICMP ECHO_RESPONSE from a host or gateway. | |
9aecb40e | 42 | ECHO_REQUEST datagrams (``pings'') have an IP and ICMP header, |
78288025 KB |
43 | followed by a |
44 | .I struct timeval | |
45 | and then an arbitrary number of ``pad'' bytes used to fill out the | |
46 | packet. | |
47 | The options are as follows: | |
d53739b5 MK |
48 | Other options are: |
49 | .TP | |
78288025 KB |
50 | .I "-c count" |
51 | Stop after sending (and receiving) | |
52 | .I count | |
53 | ECHO_RESPONSE packets. | |
54 | .TP | |
55 | .I -d | |
63ed9e52 KB |
56 | Set the SO_DEBUG option on the socket being used. |
57 | .TP | |
78288025 KB |
58 | .I -f |
59 | Flood ping. | |
60 | Outputs packets as fast as they come back or one hundred times per second, | |
61 | whichever is more. | |
62 | For every ECHO_REQUEST sent a period ``.'' is printed, while for ever | |
63 | ECHO_REPLY received a backspace is printed. | |
63ed9e52 | 64 | This provides a rapid display of how many packets are being dropped. |
78288025 KB |
65 | Only the super-user may use this option. |
66 | .I "This can be very hard on a network and should be used with caution." | |
63ed9e52 | 67 | .TP |
78288025 KB |
68 | .I "-i wait" |
69 | Wait | |
70 | .I wait seconds between sending each packet. | |
63ed9e52 | 71 | The default is to wait for one second between each packet. |
78288025 KB |
72 | This option is incompatible with the |
73 | .I -f | |
74 | option. | |
63ed9e52 | 75 | .TP |
78288025 | 76 | .I -l preload |
63ed9e52 KB |
77 | If |
78 | .I preload | |
78288025 | 79 | is specified, |
63ed9e52 | 80 | .I ping |
78288025 KB |
81 | sends that many packets as fast as possible before falling into its normal |
82 | mode of behavior. | |
63ed9e52 | 83 | .TP |
78288025 KB |
84 | .I -n |
85 | Numeric output only. | |
86 | No attempt will be made to lookup symbolic names for host addresses. | |
87 | .TP | |
88 | .I "-p pattern" | |
89 | You may specify up to 16 ``pad'' bytes to fill out the packet you send. | |
63ed9e52 | 90 | This is useful for diagnosing data-dependent problems in a network. |
78288025 KB |
91 | For example, ``-p ff'' will cause the sent packet to be filled with all |
92 | ones. | |
93 | .TP | |
94 | .I -q | |
95 | Quiet output. | |
96 | Nothing is displayed except the summary lines at startup time and | |
97 | when finished. | |
98 | .TP | |
99 | .B -R | |
100 | Record route. | |
101 | Includes the RECORD_ROUTE option in the ECHO_REQUEST packet and displays | |
102 | the route buffer on returned packets. | |
103 | Note that the IP header is only large enough for nine such routes. | |
104 | Many hosts ignore or discard this option. | |
105 | .TP | |
106 | .I -r | |
107 | Bypass the normal routing tables and send directly to a host on an attached | |
108 | network. | |
109 | If the host is not on a directly-attached network, an error is returned. | |
110 | This option can be used to ping a local host through an interface | |
111 | that has no route through it (e.g., after the interface was dropped by | |
112 | .IR routed (8)). | |
63ed9e52 | 113 | .TP |
78288025 | 114 | .I "-s packetsize" |
63ed9e52 KB |
115 | Specifies the number of data bytes to be sent. |
116 | The default is 56, which translates into 64 ICMP data bytes when combined | |
117 | with the 8 bytes of ICMP header data. | |
78288025 KB |
118 | .TP |
119 | .I -v | |
120 | Verbose output. | |
121 | ICMP packets other than ECHO_RESPONSE that are received are listed. | |
9aecb40e | 122 | .PP |
78288025 KB |
123 | When using |
124 | .I ping | |
125 | for fault isolation, it should first be run on the local host, to verify | |
126 | that the local network interface is up and running. | |
127 | Then, hosts and gateways further and further away should be ``pinged''. | |
9aecb40e | 128 | Round-trip times and packet loss statistics are computed. |
78288025 KB |
129 | If duplicate packets are received, they are not included in the packet |
130 | loss calculation, although the round trip time of these packets is used | |
131 | in calculating the minimum/average/maximum round-trip time numbers. | |
132 | When the specified number of packets have been sent (and received) or | |
133 | if the program is terminated with a SIGINT, a brief summary is displayed. | |
d53739b5 | 134 | .PP |
78288025 KB |
135 | This program is intended for use in network testing, measurement and |
136 | management. | |
137 | Because of the load it can impose on the network, it is unwise to use | |
d53739b5 MK |
138 | .I ping |
139 | during normal operations or from automated scripts. | |
78288025 | 140 | .SH ICMP PACKET DETAILS |
63ed9e52 KB |
141 | An IP header without options is 20 bytes. |
142 | An ICMP ECHO_REQUEST packet contains an additional 8 bytes worth | |
78288025 KB |
143 | of ICMP header followed by an arbitrary amount of data. |
144 | When a | |
63ed9e52 | 145 | .I packetsize |
78288025 KB |
146 | is given, this indicated the size of this extra piece of data (the |
147 | default is 56). | |
148 | Thus the amount of data received inside of an IP packet of type ICMP | |
149 | ECHO_REPLY will always be 8 bytes more than the requested data space | |
150 | (the ICMP header). | |
63ed9e52 KB |
151 | .PP |
152 | If the data space is at least eight bytes large, | |
153 | .I ping | |
154 | uses the first eight bytes of this space to include a timestamp which | |
78288025 KB |
155 | it uses in the computation of round trip times. |
156 | If less than eight bytes of pad are specified, no round trip times are | |
157 | given. | |
158 | .SH DUPLICATE AND DAMAGED PACKETS | |
159 | .I Ping | |
160 | will report duplicate and damaged packets. | |
63ed9e52 KB |
161 | Duplicate packets should never occur, and seem to be caused by |
162 | inappropriate link-level retransmissions. | |
78288025 KB |
163 | Duplicates may occur in many situations and are rarely (if ever) a |
164 | good sign, although the presence of low levels of duplicates may not | |
165 | always be cause for alarm. | |
63ed9e52 | 166 | .PP |
78288025 KB |
167 | Damaged packets are obviously serious cause for alarm and often |
168 | indicate broken hardware somewhere in the | |
169 | .I ping | |
170 | packet's path (in the network or in the hosts). | |
171 | .SH TRYING DIFFERENT DATA PATTERNS | |
172 | The (inter)network layer should never treat packets differently depending | |
173 | on the data contained in the data portion. | |
63ed9e52 KB |
174 | Unfortunately, data-dependent problems have been known to sneak into |
175 | networks and remain undetected for long periods of time. | |
176 | In many cases the particular pattern that will have problems is something | |
78288025 KB |
177 | that doesn't have sufficient ``transitions'', such as all ones or all |
178 | zeros, or a pattern right at the edge, such as almost all zeros. | |
63ed9e52 | 179 | It isn't necessarily enough to specify a data pattern of all zeros (for |
78288025 KB |
180 | example) on the command line because the pattern that is of interest is |
181 | at the data link level, and the relationship between what you type and | |
182 | what the controllers transmit can be complicated. | |
63ed9e52 | 183 | .PP |
78288025 KB |
184 | This means that if you have a data-dependent problem you will probably |
185 | have to do a lot of testing to find it. | |
63ed9e52 KB |
186 | If you are lucky, you may manage to find a file that either can't be sent |
187 | across your network or that takes much longer to transfer than other | |
188 | similar length files. | |
189 | You can then examine this file for repeated patterns that you can test | |
190 | using the \fI-p\fR option of \fIping\fR. | |
78288025 | 191 | .SH TTL DETAILS |
63ed9e52 KB |
192 | The TTL value of an IP packet represents the maximum number of IP routers |
193 | that the packet can go through before being thrown away. | |
78288025 KB |
194 | In current practice you can expect each router in the Internet to decrement |
195 | the TTL field by exactly one. | |
63ed9e52 | 196 | .PP |
78288025 | 197 | The TCP/IP specification states that the TTL field for TCP packets should |
63ed9e52 KB |
198 | be set to 60, but many systems use smaller values (4.3 BSD uses 30, 4.2 used |
199 | 15). | |
200 | .PP | |
201 | The maximum possible value of this field is 255, and most Unix systems set | |
202 | the TTL field of ICMP ECHO_REQUEST packets to 255. | |
78288025 KB |
203 | This is why you will find you can ``ping'' some hosts, but not reach them |
204 | with | |
205 | .I telnet | |
206 | or | |
207 | .IR ftp . | |
63ed9e52 KB |
208 | .PP |
209 | In normal operation ping prints the ttl value from the packet it receives. | |
210 | When a remote system receives a ping packet, it can do one of three things | |
211 | with the TTL field in its response: | |
212 | .TP | |
78288025 KB |
213 | -- |
214 | Not change it; this is what Berkeley Unix systems did before the 4.3BSD-tahoe | |
215 | release. | |
63ed9e52 KB |
216 | In this case the TTL value in the received packet will be 255 minus the |
217 | number of routers in the round-trip path. | |
218 | .TP | |
78288025 KB |
219 | -- |
220 | Set it to 255; this is what current Berkeley Unix systems do. | |
221 | In this case the TTL value in the received packet will be 255 minus the | |
222 | number of routers in the path | |
223 | .I from | |
224 | the remote system | |
225 | .I to | |
226 | the | |
227 | .IR ping ing | |
228 | host. | |
229 | .TP | |
230 | -- | |
63ed9e52 KB |
231 | Set it to some other value. |
232 | Some machines use the same value for ICMP packets that they use for | |
233 | TCP packets, for example either 30 or 60. | |
234 | Others may use completely wild values. | |
235 | .SH BUGS | |
236 | Many Hosts and Gateways ignore the RECORD_ROUTE option. | |
237 | .PP | |
78288025 KB |
238 | The maximum IP header length is too small for options like RECORD_ROUTE to |
239 | be completely useful. | |
240 | There's not much that that can be done about this, however. | |
63ed9e52 | 241 | .PP |
78288025 KB |
242 | Flood pinging is not recommended in general, and flood pinging the |
243 | broadcast address should only be done under very controlled conditions. | |
9aecb40e | 244 | .SH SEE ALSO |
78288025 | 245 | netstat(1), ifconfig(8), routed(8) |