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