1.\" $NetBSD: ping.8,v 1.41 2002/10/26 12:06:04 jdolecek 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 deadline 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 deadline 239Specifies a timeout, in seconds, before ping exits regardless of 240how many packets have been sent or received. 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. 258The summary information can be displayed while 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. 271On a trusted system with IP 272Security Options enabled, if the network idiom is not MONO, 273.Nm 274also prints a second line containing the hexadecimal representation 275of the IP security option in the ECHO_RESPONSE. 276If the 277.Fl c 278count option is given, only that number of requests is sent. 279No output is produced if there is no response. 280Round-trip times and packet loss statistics are computed. 281If duplicate packets are received, 282they are not included in the packet loss calculation, 283although the round trip time of these packets is used in calculating 284the minimum/average/maximum round-trip time numbers. 285When the specified number of packets have been sent (and received) or if 286the program is terminated with an interrupt (SIGINT), a brief 287summary is displayed. 288When not using the 289.Fl f 290(flood) option, the first interrupt, usually generated by control-C or DEL, 291causes 292.Nm 293to wait for its outstanding requests to return. 294It will wait no longer than the longest round trip time 295encountered by previous, successful pings. 296The second interrupt stops ping immediately. 297.Pp 298This program is intended for use in network testing, measurement and 299management. 300Because of the load it can impose on the network, it is unwise to use 301.Nm 302during normal operations or from automated scripts. 303.Sh ICMP PACKET DETAILS 304An IP header without options is 20 bytes. 305An 306.Tn ICMP 307.Tn ECHO_REQUEST 308packet contains an additional 8 bytes worth of 309.Tn ICMP 310header followed by an arbitrary amount of data. 311When a 312.Ar packetsize 313is given, this indicated the size of this extra piece of data (the 314default is 56). 315Thus the amount of data received inside of an IP packet of type 316.Tn ICMP 317.Tn ECHO_REPLY 318will always be 8 bytes more than the requested data space (the 319.Tn ICMP 320header). 321.Pp 322If the data space is at least eight bytes large, 323.Nm 324uses the first eight bytes of this space to include a timestamp to compute 325round trip times. 326If less than eight bytes of pad are specified, 327no round trip times are given. 328.Sh DUPLICATE AND DAMAGED PACKETS 329.Nm 330will report duplicate and damaged packets. 331Duplicate packets should never occur, and seem to be caused by 332inappropriate link-level retransmissions. 333Duplicates may occur in many situations and are rarely (if ever) a 334good sign, although the presence of low levels of duplicates may not 335always be cause for alarm. 336.Pp 337Damaged packets are obviously serious cause for alarm and often 338indicate broken hardware somewhere in the 339.Nm 340packet's path (in the network or in the hosts). 341.Sh TRYING DIFFERENT DATA PATTERNS 342The (inter)network layer should never treat packets differently depending 343on the data contained in the data portion. 344Unfortunately, data-dependent problems have been known to sneak into 345networks and remain undetected for long periods of time. 346In many cases the particular pattern that will have problems is something 347that doesn't have sufficient ``transitions'', such as all ones or all 348zeros, or a pattern right at the edge, such as almost all zeros. 349It isn't necessarily enough to specify a data pattern of all zeros (for 350example) on the command line because the pattern that is of interest is 351at the data link level, and the relationship between what you type and 352what the controllers transmit can be complicated. 353.Pp 354This means that if you have a data-dependent problem you will probably 355have to do a lot of testing to find it. 356If you are lucky, you may manage to find a file that either can't be sent 357across your network or that takes much longer to transfer than other 358similar length files. 359You can then examine this file for repeated patterns that you can test 360using the 361.Fl p 362option of 363.Nm "" . 364.Sh TTL DETAILS 365The 366.Tn TTL 367value of an IP packet represents the maximum number of IP routers 368that the packet can go through before being thrown away. 369In current practice you can expect each router in the Internet to decrement 370the 371.Tn TTL 372field by exactly one. 373.Pp 374The 375.Tn TCP/IP 376specification states that the 377.Tn TTL 378field for 379.Tn TCP 380packets should 381be set to 60, but many systems use smaller values 382.Po 383.Bx 4.3 384uses 30, 385.Bx 4.2 386used 15 387.Pc . 388.Pp 389The maximum possible value of this field is 255, and most 390.Ux 391systems set the 392.Tn TTL 393field of 394.Tn ICMP ECHO_REQUEST 395packets to 255. 396This is why you will find you can ``ping'' some hosts, but not reach them 397with 398.Xr telnet 1 399or 400.Xr ftp 1 . 401.Pp 402In normal operation ping prints the ttl value from the packet it receives. 403When a remote system receives a ping packet, it can do one of three things 404with the 405.Tn TTL 406field in its response: 407.Bl -bullet 408.It 409Not change it; this is what Berkeley 410.Ux 411systems did before the 412.Bx 4.3 tahoe 413release. 414In this case the 415.Tn TTL 416value in the received packet will be 255 minus the 417number of routers in the round-trip path. 418.It 419Set it to 255; this is what current Berkeley 420.Ux 421systems do. 422In this case the 423.Tn TTL 424value in the received packet will be 255 minus the 425number of routers in the path 426.Em from 427the remote system 428.Em to 429the 430.Nm "" Ns Em ing 431host. 432.It 433Set it to some other value. 434Some machines use the same value for 435.Tn ICMP 436packets that they use for 437.Tn TCP 438packets, for example either 30 or 60. 439Others may use completely wild values. 440.El 441.Sh EXIT STATUS 442.Nm 443returns 0 on success (the host is alive), 444and non-zero if the arguments are incorrect or the host is not responding. 445.Sh SEE ALSO 446.Xr netstat 1 , 447.Xr icmp 4 , 448.Xr inet 4 , 449.Xr ip 4 , 450.Xr ifconfig 8 , 451.Xr routed 8 , 452.Xr spray 8 , 453.Xr traceroute 8 454.Sh HISTORY 455The 456.Nm 457command appeared in 458.Bx 4.3 . 459IPsec support was added by WIDE/KAME project. 460.Sh BUGS 461Flood pinging is not recommended in general, and flood pinging a broadcast 462or multicast address should only be done under very controlled conditions. 463.Pp 464The 465.Nm 466program has evolved differently under different operating systems, 467and in some cases the same flag performs a different function 468under different operating systems. 469The 470.Fl t 471flag conflicts with 472.Fx . 473The 474.Fl a , c , i , I , 475.Fl l , p , P , s , 476and 477.Fl t 478flags conflict with 479.Sy Solaris . 480.Pp 481Some hosts and gateways ignore the 482.Tn RECORD_ROUTE 483option. 484.Pp 485The maximum IP header length is too small for options like 486.Tn RECORD_ROUTE 487to 488be completely useful. 489There's not much that that can be done about this, however. 490