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