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