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