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