1.\" $NetBSD: ping.8,v 1.50 2011/09/10 20:47:33 wiz Exp $ 2.\" 3.\" Copyright (c) 1985, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)ping.8 8.2 (Berkeley) 12/11/93 31.\" 32.Dd September 10, 2011 33.Dt PING 8 34.Os 35.Sh NAME 36.Nm ping 37.Nd send 38.Tn ICMP ECHO_REQUEST 39packets to network hosts 40.Sh SYNOPSIS 41.Nm 42.Op Fl aCDdfLnoPQqRrv 43.Op Fl c Ar count 44.Op Fl E Ar policy 45.Op Fl g Ar gateway 46.Op Fl h Ar host 47.Op Fl I Ar srcaddr 48.Op Fl i Ar interval 49.Op Fl l Ar preload 50.Op Fl p Ar pattern 51.Op Fl s Ar packetsize 52.Op Fl T Ar ttl 53.Op Fl t Ar tos 54.Op Fl w Ar deadline 55.Ar host 56.Sh DESCRIPTION 57.Nm 58uses the 59.Tn ICMP 60protocol's mandatory 61.Tn ECHO_REQUEST 62datagram to elicit an 63.Tn ICMP ECHO_RESPONSE 64from a host or gateway. 65.Tn ECHO_REQUEST 66datagrams (``pings'') have an IP and 67.Tn ICMP 68header, 69followed by a 70.Dq struct timespec 71and then an arbitrary number of ``pad'' bytes used to fill out the 72packet. 73The options are as follows: 74.Bl -tag -width Ds 75.It Fl a 76Emit an audible beep (by sending an ascii BEL character to the 77standard error output) after each non-duplicate response is received. 78This is disabled for flood pings as it would probably cause temporary 79insanity. 80.It Fl C 81Send timestamps in compat format; two 32 bit words in little endian format, 82the first one representing seconds, and the second one representing 83microseconds. 84.It Fl c Ar count 85Stop after sending (and waiting the specified delay to receive) 86.Ar count 87.Tn ECHO_RESPONSE 88packets. 89.It Fl D 90Set the 91.Dv Don't Fragment 92bit in the IP header. 93This can be used to determine the path MTU. 94.It Fl d 95Set the 96.Dv SO_DEBUG 97option on the socket being used. 98.It Fl E Ar policy 99Use IPsec policy specification string 100.Ar policy 101for packets. 102For the format of specification string, please refer 103.Xr ipsec_set_policy 3 . 104Please note that this option is same as 105.Fl P 106in KAME/FreeBSD and KAME/BSDI 107(as 108.Fl P 109was already occupied in 110.Nx ) . 111.It Fl f 112Flood ping. 113Outputs packets as fast as they come back or one hundred times per second, 114whichever is more. 115For every 116.Tn ECHO_REQUEST 117sent a period ``.'' is printed, while for every 118.Tn ECHO_REPLY 119received a backspace is printed. 120This provides a rapid display of how many packets are being dropped. 121Only the super-user may use this option. 122.Bf -emphasis 123This can be very hard on a network and should be used with caution. 124.Ef 125.It Fl g Ar gateway 126Use Loose Source Routing to send the ECHO_REQUEST packets via 127.Ar gateway . 128.It Fl h Ar host 129is an alternate way of specifying the target host instead of as the 130last argument. 131.It Fl I Ar srcaddr 132Set the source IP address to 133.Ar srcaddr 134which can be a hostname or an IP number. 135For multicast datagrams, it also specifies the outgoing interface. 136.It Fl i Ar interval 137Wait 138.Ar interval 139seconds 140.Em between sending each packet . 141The default is to wait for one second between each packet, 142except when the -f option is used the wait interval is 0.01 seconds. 143.It Fl L 144Disable loopback when sending to multicast destinations, 145so the transmitting host doesn't see the ICMP requests. 146.It Fl l Ar preload 147If 148.Ar preload 149is specified, 150.Nm 151sends that many packets as fast as possible before falling into its normal 152mode of behavior. 153Only the super-user may use this option. 154.It Fl n 155Numeric output only. 156No attempt will be made to look up symbolic names for host addresses. 157.It Fl o 158Exit successfully after receiving one reply packet. 159.It Fl P 160Use a pseudo-random sequence for the data instead of the default, 161fixed sequence of incrementing 8-bit integers. 162This is useful to foil compression on PPP and other links. 163.It Fl p Ar pattern 164You may specify up to 16 ``pad'' bytes to fill out the packet you send. 165This is useful for diagnosing data-dependent problems in a network. 166For example, 167.Dq Li \-p ff 168will cause the sent packet to be filled with all 169ones. 170.It Fl Q 171Do not display responses such as Network Unreachable ICMP messages 172concerning the ECHO_REQUESTs sent. 173.It Fl q 174Quiet output. 175Nothing is displayed except the summary lines at startup time and 176when finished. 177.It Fl R 178Record Route. 179Includes the 180.Tn RECORD_ROUTE 181option in the 182.Tn ECHO_REQUEST 183packet and displays the route buffer on returned packets. 184This should show the path to the target host and back, which is 185especially useful in the case of asymmetric routing. 186Note that the IP header is only large enough for nine such addresses, 187and only seven when using the 188.Fl g 189option. 190This is why it was necessary to invent 191.Xr traceroute 8 . 192Many hosts ignore or discard this option. 193.It Fl r 194Bypass the normal routing tables and send directly to a host on an attached 195network. 196If the host is not on a directly-attached network, an error is returned. 197This option can be used to ping a local host through an interface 198that has no route through it (e.g., after the interface was dropped by 199.Xr routed 8 ) . 200.It Fl s Ar packetsize 201Specifies the number of data bytes to be sent. 202The default is 56, which translates into 64 203.Tn ICMP 204data bytes when combined 205with the 8 bytes of 206.Tn ICMP 207header data. 208The maximum allowed value is 65467 bytes. 209.It Fl T Ar ttl 210Use the specified time-to-live. 211.It Fl t Ar tos 212Use the specified hexadecimal type of service. 213.It Fl v 214Verbose output. 215.Tn ICMP 216packets other than 217.Tn ECHO_RESPONSE 218that are received are listed. 219.It Fl w Ar deadline 220Specifies a timeout, in seconds, before ping exits regardless of 221how many packets have been sent or received. 222.El 223.Pp 224When using 225.Nm 226for fault isolation, it should first be run on the local host, to verify 227that the local network interface is up and running. 228Then, hosts and gateways further and further away should be ``pinged''. 229.Pp 230Round-trip times and packet loss statistics are computed. 231If duplicate packets are received, they are not included in the packet 232loss calculation, although the round trip time of these packets is used 233in calculating the minimum/average/maximum round-trip time numbers. 234.Pp 235When the specified number of packets have been sent (and received) or 236if the program is terminated with a 237.Dv SIGINT , 238a brief summary is displayed. 239The summary information can be displayed while 240.Nm 241is running by sending it a 242.Dv SIGINFO 243signal (see the 244.Dq status 245argument for 246.Xr stty 1 247for more information). 248.Pp 249.Nm 250continually sends one datagram per second, and prints one line of 251output for every ECHO_RESPONSE returned. 252On a trusted system with IP 253Security Options enabled, if the network idiom is not MONO, 254.Nm 255also prints a second line containing the hexadecimal representation 256of the IP security option in the ECHO_RESPONSE. 257If the 258.Fl c 259count option is given, only that number of requests is sent. 260No output is produced if there is no response. 261Round-trip times and packet loss statistics are computed. 262If duplicate packets are received, 263they are not included in the packet loss calculation, 264although the round trip time of these packets is used in calculating 265the minimum/average/maximum round-trip time numbers. 266When the specified number of packets have been sent (and received) or if 267the program is terminated with an interrupt (SIGINT), a brief 268summary is displayed. 269When not using the 270.Fl f 271(flood) option, the first interrupt, usually generated by control-C or DEL, 272causes 273.Nm 274to wait for its outstanding requests to return. 275It will wait no longer than the longest round trip time 276encountered by previous, successful pings. 277The second interrupt stops ping immediately. 278.Pp 279This program is intended for use in network testing, measurement and 280management. 281Because of the load it can impose on the network, it is unwise to use 282.Nm 283during normal operations or from automated scripts. 284.Sh ICMP PACKET DETAILS 285An IP header without options is 20 bytes. 286An 287.Tn ICMP 288.Tn ECHO_REQUEST 289packet contains an additional 8 bytes worth of 290.Tn ICMP 291header followed by an arbitrary amount of data. 292When a 293.Ar packetsize 294is given, this indicated the size of this extra piece of data (the 295default is 56). 296Thus the amount of data received inside of an IP packet of type 297.Tn ICMP 298.Tn ECHO_REPLY 299will always be 8 bytes more than the requested data space (the 300.Tn ICMP 301header). 302.Pp 303If the data space is at least 304.Dv sizeof(struct timespec) 305(16) large, 306.Nm 307uses the first 308.Dv sizeof(struct timespec) 309bytes to include a timestamp to compute round trip times. 310Otherwise if the data space is at least eight bytes large (or the 311.Fl C 312flag is specified), 313.Nm 314uses the first eight bytes of this space to include a timestamp to compute 315round trip times. 316If there are not enough bytes of pad no round trip times are given. 317.Sh DUPLICATE AND DAMAGED PACKETS 318.Nm 319will report duplicate and damaged packets. 320Duplicate packets should never occur, and seem to be caused by 321inappropriate link-level retransmissions. 322Duplicates may occur in many situations and are rarely (if ever) a 323good sign, although the presence of low levels of duplicates may not 324always be cause for alarm. 325.Pp 326Damaged packets are obviously serious cause for alarm and often 327indicate broken hardware somewhere in the 328.Nm 329packet's path (in the network or in the hosts). 330.Sh TRYING DIFFERENT DATA PATTERNS 331The (inter)network layer should never treat packets differently depending 332on the data contained in the data portion. 333Unfortunately, data-dependent problems have been known to sneak into 334networks and remain undetected for long periods of time. 335In many cases the particular pattern that will have problems is something 336that doesn't have sufficient ``transitions'', such as all ones or all 337zeros, or a pattern right at the edge, such as almost all zeros. 338It isn't necessarily enough to specify a data pattern of all zeros (for 339example) on the command line because the pattern that is of interest is 340at the data link level, and the relationship between what you type and 341what the controllers transmit can be complicated. 342.Pp 343This means that if you have a data-dependent problem you will probably 344have to do a lot of testing to find it. 345If you are lucky, you may manage to find a file that either can't be sent 346across your network or that takes much longer to transfer than other 347similar length files. 348You can then examine this file for repeated patterns that you can test 349using the 350.Fl p 351option of 352.Nm . 353.Sh TTL DETAILS 354The 355.Tn TTL 356value of an IP packet represents the maximum number of IP routers 357that the packet can go through before being thrown away. 358In current practice you can expect each router in the Internet to decrement 359the 360.Tn TTL 361field by exactly one. 362.Pp 363The 364.Tn TCP/IP 365specification states that the 366.Tn TTL 367field for 368.Tn TCP 369packets should 370be set to 60, but many systems use smaller values 371.Po 372.Bx 4.3 373uses 30, 374.Bx 4.2 375used 15 376.Pc . 377.Pp 378The maximum possible value of this field is 255, and most 379.Ux 380systems set the 381.Tn TTL 382field of 383.Tn ICMP ECHO_REQUEST 384packets to 255. 385This is why you will find you can ``ping'' some hosts, but not reach them 386with 387.Xr telnet 1 388or 389.Xr ftp 1 . 390.Pp 391In normal operation ping prints the ttl value from the packet it receives. 392When a remote system receives a ping packet, it can do one of three things 393with the 394.Tn TTL 395field in its response: 396.Bl -bullet 397.It 398Not change it; this is what Berkeley 399.Ux 400systems did before the 401.Bx 4.3 tahoe 402release. 403In this case the 404.Tn TTL 405value in the received packet will be 255 minus the 406number of routers in the round-trip path. 407.It 408Set it to 255; this is what current Berkeley 409.Ux 410systems do. 411In this case the 412.Tn TTL 413value in the received packet will be 255 minus the 414number of routers in the path 415.Em from 416the remote system 417.Em to 418the 419.Nm Ns Em ing 420host. 421.It 422Set it to some other value. 423Some machines use the same value for 424.Tn ICMP 425packets that they use for 426.Tn TCP 427packets, for example either 30 or 60. 428Others may use completely wild values. 429.El 430.Sh EXIT STATUS 431.Nm 432returns 0 on success (the host is alive), 433and non-zero if the arguments are incorrect or the host is not responding. 434.Sh SEE ALSO 435.Xr netstat 1 , 436.Xr icmp 4 , 437.Xr inet 4 , 438.Xr ip 4 , 439.Xr ifconfig 8 , 440.Xr routed 8 , 441.Xr spray 8 , 442.Xr traceroute 8 443.Sh HISTORY 444The 445.Nm 446command appeared in 447.Bx 4.3 . 448IPsec support was added by WIDE/KAME project. 449.Sh BUGS 450Flood pinging is not recommended in general, and flood pinging a broadcast 451or multicast address should only be done under very controlled conditions. 452.Pp 453The 454.Nm 455program has evolved differently under different operating systems, 456and in some cases the same flag performs a different function 457under different operating systems. 458The 459.Fl t 460flag conflicts with 461.Fx . 462The 463.Fl a , c , I , i , 464.Fl l , P , p , s , 465and 466.Fl t 467flags conflict with 468.Sy Solaris . 469.Pp 470Some hosts and gateways ignore the 471.Tn RECORD_ROUTE 472option. 473.Pp 474The maximum IP header length is too small for options like 475.Tn RECORD_ROUTE 476to 477be completely useful. 478There's not much that that can be done about this, however. 479