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