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.\" $FreeBSD$ 34.\" 35.Dd March 1, 1997 36.Dt PING 8 37.Os 38.Sh NAME 39.Nm ping 40.Nd send 41.Tn ICMP ECHO_REQUEST 42packets to network hosts 43.Sh SYNOPSIS 44.Nm 45.Op Fl AQRadfnqrv 46.Op Fl c Ar count 47.Op Fl i Ar wait 48.Op Fl l Ar preload 49.Op Fl m Ar ttl 50.Op Fl p Ar pattern 51.Op Fl P Ar policy 52.Op Fl s Ar packetsize 53.Op Fl S Ar src_addr 54.Op Fl t Ar timeout 55.Bo 56.Ar host | 57.Op Fl L 58.Op Fl I Ar interface 59.Op Fl T Ar ttl 60.Ar mcast-group 61.Bc 62.Sh DESCRIPTION 63.Nm Ping 64uses the 65.Tn ICMP 66.No protocol Ap s mandatory 67.Tn ECHO_REQUEST 68datagram to elicit an 69.Tn ICMP ECHO_RESPONSE 70from a host or gateway. 71.Tn ECHO_REQUEST 72datagrams 73.Pq Dq pings 74have an IP and 75.Tn ICMP 76header, followed by a 77.Dq struct timeval 78and then an arbitrary number of 79.Dq pad 80bytes used to fill out the packet. The options are as follows: 81.Bl -tag -width indent 82.It Fl A 83Audible. 84Include a bell 85.Tn ( ASCII 860x07) 87character in the output when no packet is received before the next packet 88is transmitted. 89.It Fl a 90Audible. 91Include a bell 92.Tn ( ASCII 930x07) 94character in the output when any packet is received. 95This option is ignored 96if other format options are present. 97.It Fl c Ar count 98Stop after sending 99(and receiving) 100.Ar count 101.Tn ECHO_RESPONSE 102packets. 103If this option is not specified, 104.Nm 105will operate until interrupted. 106.It Fl d 107Set the 108.Dv SO_DEBUG 109option on the socket being used. 110.It Fl f 111Flood ping. 112Outputs packets as fast as they come back or one hundred times per second, 113whichever is more. 114For every 115.Tn ECHO_REQUEST 116sent a period 117.Dq .\& 118is printed, while for every 119.Tn ECHO_REPLY 120received a backspace is printed. 121This provides a rapid display of how many packets are being dropped. 122Only the super-user may use this option. 123.Bf -emphasis 124This can be very hard on a network and should be used with caution. 125.Ef 126.It Fl i Ar wait 127Wait 128.Ar wait 129seconds 130.Em between sending each packet . 131The default is to wait for one second between each packet. 132The wait time may be fractional, but only the super-user may specify 133values less then 1 second. 134This option is incompatible with the 135.Fl f 136option. 137.It Fl I Ar interface 138Source multicast packets with the given interface address. 139This flag only applies if the ping destination is a multicast address. 140.It Fl l Ar preload 141If 142.Ar preload 143is specified, 144.Nm 145sends that many packets as fast as possible before falling into its normal 146mode of behavior. 147Only the super-user may use this option. 148.It Fl m Ar ttl 149Set the IP Time To Live for outgoing packets. 150If not specified, the kernel uses the value of the 151.Va net.inet.ip.ttl 152MIB variable. 153.It Fl L 154Suppress loopback of multicast packets. 155This flag only applies if the ping destination is a multicast address. 156.It Fl n 157Numeric output only. 158No attempt will be made to lookup symbolic names for host addresses. 159.It Fl p Ar pattern 160You may specify up to 16 161.Dq pad 162bytes to fill out the packet you send. 163This is useful for diagnosing data-dependent problems in a network. 164For example, 165.Dq Li \-p ff 166will cause the sent packet to be filled with all 167ones. 168.It Fl P Ar policy 169.Ar policy 170specifies IPsec policy for the ping session. 171For details please refer to 172.Xr ipsec 4 173and 174.Xr ipsec_set_policy 3 . 175.It Fl Q 176Somewhat quiet output. 177.No Don Ap t 178display ICMP error messages that are in response to our query messages. 179Originally, the 180.Fl v 181flag was required to display such errors, but 182.Fl v 183displays all ICMP error messages. On a busy machine, this output can 184be overbearing. Without the 185.Fl Q 186flag, 187.Nm 188prints out any ICMP error messages caused by its own ECHO_REQUEST 189messages. 190.It Fl q 191Quiet output. 192Nothing is displayed except the summary lines at startup time and 193when finished. 194.It Fl R 195Record route. 196Includes the 197.Tn RECORD_ROUTE 198option in the 199.Tn ECHO_REQUEST 200packet and displays 201the route buffer on returned packets. 202Note that the IP header is only large enough for nine such routes; 203the 204.Xr traceroute 8 205command is usually better at determining the route packets take to a 206particular destination. 207If more routes come back than should, such as due to an illegal spoofed 208packet, ping will print the route list and then truncate it at the correct 209spot. 210Many hosts ignore or discard the 211.Tn RECORD_ROUTE 212option. 213.It Fl r 214Bypass the normal routing tables and send directly to a host on an attached 215network. 216If the host is not on a directly-attached network, an error is returned. 217This option can be used to ping a local host through an interface 218that has no route through it 219(e.g., after the interface was dropped by 220.Xr routed 8 ) . 221.It Fl s Ar packetsize 222Specify the number of data bytes to be sent. 223The default is 56, which translates into 64 224.Tn ICMP 225data bytes when combined 226with the 8 bytes of 227.Tn ICMP 228header data. 229Only the super-user may use this option. 230.It Fl S Ar src_addr 231Use the following IP address as the source address in outgoing packets. 232On hosts with more than one IP address, this option can be used to 233force the source address to be something other than the IP address 234of the interface the probe packet is sent on. If the IP address 235is not one of this machine's interface addresses, an error is 236returned and nothing is sent. 237.It Fl t Ar timeout 238Specify a timeout, in seconds, before ping exits regardless of how 239many packets have been recieved. 240.It Fl T Ar ttl 241Set the IP Time To Live for multicasted packets. 242This flag only applies if the ping destination is a multicast address. 243.It Fl v 244Verbose output. 245.Tn ICMP 246packets other than 247.Tn ECHO_RESPONSE 248that are received are listed. 249.El 250.Pp 251When using 252.Nm 253for fault isolation, it should first be run on the local host, to verify 254that the local network interface is up and running. 255Then, hosts and gateways further and further away should be 256.Dq pinged . 257Round-trip times and packet loss statistics are computed. 258If duplicate packets are received, they are not included in the packet 259loss calculation, although the round trip time of these packets is used 260in calculating the round-trip time statistics. 261When the specified number of packets have been sent 262(and received) 263or if the program is terminated with a 264.Dv SIGINT , 265a brief summary is displayed, showing the number of packets sent and 266received, and the minimum, maximum, mean, and standard deviation of 267the round-trip times. 268.Pp 269This program is intended for use in network testing, measurement and 270management. 271Because of the load it can impose on the network, it is unwise to use 272.Nm 273during normal operations or from automated scripts. 274.Sh ICMP PACKET DETAILS 275An IP header without options is 20 bytes. 276An 277.Tn ICMP 278.Tn ECHO_REQUEST 279packet contains an additional 8 bytes worth of 280.Tn ICMP 281header followed by an arbitrary amount of data. 282When a 283.Ar packetsize 284is given, this indicated the size of this extra piece of data 285(the default is 56). 286Thus the amount of data received inside of an IP packet of type 287.Tn ICMP 288.Tn ECHO_REPLY 289will always be 8 bytes more than the requested data space 290(the 291.Tn ICMP 292header). 293.Pp 294If the data space is at least eight bytes large, 295.Nm 296uses the first eight bytes of this space to include a timestamp which 297it uses in the computation of round trip times. 298If less than eight bytes of pad are specified, no round trip times are 299given. 300.Sh DUPLICATE AND DAMAGED PACKETS 301.Nm Ping 302will report duplicate and damaged packets. 303Duplicate packets should never occur when pinging a unicast address, 304and seem to be caused by 305inappropriate link-level retransmissions. 306Duplicates may occur in many situations and are rarely 307(if ever) 308a good sign, although the presence of low levels of duplicates may not 309always be cause for alarm. 310Duplicates are expected when pinging a broadcast or multicast address, 311since they are not really duplicates but replies from different hosts 312to the same request. 313.Pp 314Damaged packets are obviously serious cause for alarm and often 315indicate broken hardware somewhere in the 316.Nm 317packet's path (in the network or in the hosts). 318.Sh TRYING DIFFERENT DATA PATTERNS 319The 320(inter)network 321layer should never treat packets differently depending on the data 322contained in the data portion. 323Unfortunately, data-dependent problems have been known to sneak into 324networks and remain undetected for long periods of time. 325In many cases the particular pattern that will have problems is something 326that does not have sufficient 327.Dq transitions , 328such as all ones or all zeros, or a pattern right at the edge, such as 329almost all zeros. 330It is not 331necessarily enough to specify a data pattern of all zeros (for example) 332on the command line because the pattern that is of interest is 333at the data link level, and the relationship between what you type and 334what the controllers transmit can be complicated. 335.Pp 336This means that if you have a data-dependent problem you will probably 337have to do a lot of testing to find it. 338If you are lucky, you may manage to find a file that either 339cannot 340be sent across your network or that takes much longer to transfer than 341other similar length files. 342You can then examine this file for repeated patterns that you can test 343using the 344.Fl p 345option of 346.Nm . 347.Sh TTL DETAILS 348The 349.Tn TTL 350value of an IP packet represents the maximum number of IP routers 351that the packet can go through before being thrown away. 352In current practice you can expect each router in the Internet to decrement 353the 354.Tn TTL 355field by exactly one. 356.Pp 357The 358.Tn TCP/IP 359specification states that the 360.Tn TTL 361field for 362.Tn TCP 363packets should be set to 60, but many systems use smaller values 364.No ( Bx 4.3 365uses 30, 366.Bx 4.2 367used 15). 368.Pp 369The maximum possible value of this field is 255, and most 370.Ux 371systems set 372the 373.Tn TTL 374field of 375.Tn ICMP ECHO_REQUEST 376packets to 255. 377This is why you will find you can 378.Dq ping 379some hosts, but not reach them with 380.Xr telnet 1 381or 382.Xr ftp 1 . 383.Pp 384In normal operation 385.Nm 386prints the ttl value from the packet it receives. 387When a remote system receives a ping packet, it can do one of three things 388with the 389.Tn TTL 390field in its response: 391.Bl -bullet 392.It 393Not change it; this is what 394.Bx 395systems did before the 396.Bx 4.3 tahoe 397release. 398In this case the 399.Tn TTL 400value in the received packet will be 255 minus the 401number of routers in the round-trip path. 402.It 403Set it to 255; this is what current 404.Bx 405systems do. 406In this case the 407.Tn TTL 408value in the received packet will be 255 minus the 409number of routers in the path 410.Em from 411the remote system 412.Em to 413the 414.Nm Ns Em ing 415host. 416.It 417Set it to some other value. 418Some machines use the same value for 419.Tn ICMP 420packets that they use for 421.Tn TCP 422packets, for example either 30 or 60. 423Others may use completely wild values. 424.El 425.Sh RETURN VALUES 426The 427.Nm 428command returns an exit status of zero if at least one response was 429heard from the specified 430.Ar host ; 431a status of two if the transmission was successful but no responses 432were received; or another value 433(from 434.Aq Pa sysexits.h ) 435if an error occurred. 436.Sh SEE ALSO 437.Xr netstat 1 , 438.Xr ifconfig 8 , 439.Xr routed 8 , 440.Xr traceroute 8 441.Sh HISTORY 442The 443.Nm 444command appeared in 445.Bx 4.3 . 446.Sh AUTHORS 447The original 448.Nm 449command was written by 450.An Mike Muuss 451while at the US Army Ballistics 452Research Laboratory. 453.Sh BUGS 454Many Hosts and Gateways ignore the 455.Tn RECORD_ROUTE 456option. 457.Pp 458The maximum IP header length is too small for options like 459.Tn RECORD_ROUTE 460to be completely useful. 461.No There Ap s 462not much that can be done about this, however. 463.Pp 464Flood pinging is not recommended in general, and flood pinging the 465broadcast address should only be done under very controlled conditions. 466.Pp 467The 468.Fl v 469option is not worth much on busy hosts. 470