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