| 1 | .\" Copyright (c) 1985 The Regents of the University of California. |
| 2 | .\" All rights reserved. |
| 3 | .\" |
| 4 | .\" %sccs.include.redist.man% |
| 5 | .\" |
| 6 | .\" @(#)ping.8 6.6 (Berkeley) %G% |
| 7 | .\" |
| 8 | .TH PING 8 "" |
| 9 | .UC 6 |
| 10 | .SH NAME |
| 11 | ping \- send ICMP ECHO_REQUEST packets to network hosts |
| 12 | .SH SYNOPSIS |
| 13 | .B ping |
| 14 | [ |
| 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] |
| 27 | .SH DESCRIPTION |
| 28 | .I Ping |
| 29 | uses the |
| 30 | ICMP protocol's mandatory ECHO_REQUEST datagram to elicit an |
| 31 | ICMP ECHO_RESPONSE from a host or gateway. |
| 32 | ECHO_REQUEST datagrams (``pings'') have an IP and ICMP header, |
| 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: |
| 38 | Other options are: |
| 39 | .TP |
| 40 | .I "-c count" |
| 41 | Stop after sending (and receiving) |
| 42 | .I count |
| 43 | ECHO_RESPONSE packets. |
| 44 | .TP |
| 45 | .I -d |
| 46 | Set the SO_DEBUG option on the socket being used. |
| 47 | .TP |
| 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. |
| 54 | This provides a rapid display of how many packets are being dropped. |
| 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." |
| 57 | .TP |
| 58 | .I "-i wait" |
| 59 | Wait |
| 60 | .I wait seconds between sending each packet. |
| 61 | The default is to wait for one second between each packet. |
| 62 | This option is incompatible with the |
| 63 | .I -f |
| 64 | option. |
| 65 | .TP |
| 66 | .I -l preload |
| 67 | If |
| 68 | .I preload |
| 69 | is specified, |
| 70 | .I ping |
| 71 | sends that many packets as fast as possible before falling into its normal |
| 72 | mode of behavior. |
| 73 | .TP |
| 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. |
| 80 | This is useful for diagnosing data-dependent problems in a network. |
| 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)). |
| 103 | .TP |
| 104 | .I "-s packetsize" |
| 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. |
| 108 | .TP |
| 109 | .I -v |
| 110 | Verbose output. |
| 111 | ICMP packets other than ECHO_RESPONSE that are received are listed. |
| 112 | .PP |
| 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''. |
| 118 | Round-trip times and packet loss statistics are computed. |
| 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. |
| 124 | .PP |
| 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 |
| 128 | .I ping |
| 129 | during normal operations or from automated scripts. |
| 130 | .SH ICMP PACKET DETAILS |
| 131 | An IP header without options is 20 bytes. |
| 132 | An ICMP ECHO_REQUEST packet contains an additional 8 bytes worth |
| 133 | of ICMP header followed by an arbitrary amount of data. |
| 134 | When a |
| 135 | .I packetsize |
| 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). |
| 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. |
| 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. |
| 151 | Duplicate packets should never occur, and seem to be caused by |
| 152 | inappropriate link-level retransmissions. |
| 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. |
| 156 | .PP |
| 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. |
| 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 |
| 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. |
| 169 | It isn't necessarily enough to specify a data pattern of all zeros (for |
| 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. |
| 173 | .PP |
| 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. |
| 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. |
| 181 | .SH TTL DETAILS |
| 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. |
| 184 | In current practice you can expect each router in the Internet to decrement |
| 185 | the TTL field by exactly one. |
| 186 | .PP |
| 187 | The TCP/IP specification states that the TTL field for TCP packets should |
| 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. |
| 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 . |
| 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 |
| 203 | -- |
| 204 | Not change it; this is what Berkeley Unix systems did before the 4.3BSD-tahoe |
| 205 | release. |
| 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 |
| 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 | -- |
| 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 |
| 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. |
| 231 | .PP |
| 232 | Flood pinging is not recommended in general, and flood pinging the |
| 233 | broadcast address should only be done under very controlled conditions. |
| 234 | .SH SEE ALSO |
| 235 | netstat(1), ifconfig(8), routed(8) |