1.\" $OpenBSD: ping.8,v 1.57 2016/09/20 12:32:35 jmc Exp $ 2.\" $NetBSD: ping.8,v 1.10 1995/12/31 04:55:35 ghudson Exp $ 3.\" 4.\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project. 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the project nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" Copyright (c) 1985, 1991, 1993 32.\" The Regents of the University of California. All rights reserved. 33.\" 34.\" Redistribution and use in source and binary forms, with or without 35.\" modification, are permitted provided that the following conditions 36.\" are met: 37.\" 1. Redistributions of source code must retain the above copyright 38.\" notice, this list of conditions and the following disclaimer. 39.\" 2. Redistributions in binary form must reproduce the above copyright 40.\" notice, this list of conditions and the following disclaimer in the 41.\" documentation and/or other materials provided with the distribution. 42.\" 3. Neither the name of the University nor the names of its contributors 43.\" may be used to endorse or promote products derived from this software 44.\" without specific prior written permission. 45.\" 46.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 47.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 48.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 49.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 50.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 51.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 52.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 53.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 54.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 55.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 56.\" SUCH DAMAGE. 57.\" 58.\" @(#)ping.8 8.2 (Berkeley) 12/11/93 59.\" 60.Dd $Mdocdate: September 20 2016 $ 61.Dt PING 8 62.Os 63.Sh NAME 64.Nm ping , 65.Nm ping6 66.Nd send ICMP ECHO_REQUEST packets to network hosts 67.Sh SYNOPSIS 68.Nm ping 69.Op Fl DdEefHLnqRv 70.Op Fl c Ar count 71.Op Fl I Ar ifaddr 72.Op Fl i Ar wait 73.Op Fl l Ar preload 74.Op Fl p Ar pattern 75.Op Fl s Ar packetsize 76.Op Fl T Ar toskeyword 77.Op Fl t Ar ttl 78.Op Fl V Ar rtable 79.Op Fl w Ar maxwait 80.Ar host 81.Nm ping6 82.Op Fl dEefHLmnqv 83.Op Fl c Ar count 84.Op Fl h Ar hoplimit 85.Op Fl I Ar sourceaddr 86.Op Fl i Ar wait 87.Op Fl l Ar preload 88.Op Fl p Ar pattern 89.Op Fl s Ar packetsize 90.Op Fl V Ar rtable 91.Op Fl w Ar maxwait 92.Ar host 93.Sh DESCRIPTION 94.Nm 95uses the ICMP protocol's mandatory 96.Dv ECHO_REQUEST 97datagram to elicit an ICMP 98.Dv ECHO_REPLY 99from a host or gateway. 100These datagrams 101.Pq pings 102have an IP and ICMP header, 103followed by a 104.Qq struct timeval 105and then an arbitrary number of pad bytes used to fill out the packet. 106.Pp 107The options are as follows: 108.Bl -tag -width Ds 109.It Fl c Ar count 110Stop sending after 111.Ar count 112.Dv ECHO_REQUEST 113packets have been sent. 114If 115.Ar count 116is 0, send an unlimited number of packets. 117.It Fl D 118.Pq IPv4 only 119Set the 120.Dv Don't Fragment 121bit. 122.It Fl d 123Set the 124.Dv SO_DEBUG 125option on the socket being used. 126This option has no effect on 127.Ox . 128.It Fl E 129Emit an audible beep (by sending an ASCII BEL character to the 130standard error output) when no packet is received before the next 131packet is transmitted. 132To cater for round-trip times that are longer than the interval between 133transmissions, further missing packets cause a bell only if the maximum 134number of unreceived packets has increased. 135This option is disabled for flood pings. 136.It Fl e 137Emit an audible beep (by sending an ASCII BEL character to the 138standard error output) after each non-duplicate response is received. 139This option is disabled for flood pings. 140.It Fl f 141Flood ping. 142Outputs packets as fast as they come back or one hundred times per second, 143whichever is more. 144For every 145.Dv ECHO_REQUEST 146sent, a period 147.Sq \&. 148is printed, while for every 149.Dv ECHO_REPLY 150received a backspace is printed. 151This provides a rapid display of how many packets are being dropped. 152Only the superuser may use this option. 153.Bf -emphasis 154This can be very hard on a network and should be used with caution. 155.Ef 156.It Fl H 157Try reverse lookups for addresses. 158.It Fl h Ar hoplimit 159.Pq IPv6 only 160Set the hoplimit. 161.It Fl I Ar ifaddr 162Specify the interface address to transmit from 163on machines with multiple interfaces. 164For unicast and multicast pings. 165.It Fl i Ar wait 166Wait 167.Ar wait 168seconds between sending each packet. 169The default is to wait for one second between each packet. 170The wait time may be fractional, but only the superuser may specify 171a value less than one second. 172This option is incompatible with the 173.Fl f 174option. 175.It Fl L 176Disable the loopback, so the transmitting host doesn't see the ICMP 177requests. 178For multicast pings. 179.It Fl l Ar preload 180Send 181.Ar preload 182packets as fast as possible before reverting to normal behavior. 183Only root may set a preload value. 184.It Fl m 185.Pq IPv6 only 186Do not fragment unicast packets to fit the minimum IPv6 MTU. 187If specified twice, 188do this for multicast packets as well. 189.It Fl n 190Numeric output only. 191No attempt will be made to look up symbolic names from addresses in the reply. 192.It Fl p Ar pattern 193Specify up to 16 pad bytes to fill out the packet sent. 194This is useful for diagnosing data-dependent problems in a network. 195For example, 196.Qq -p ff 197causes the sent packet to be filled with all ones. 198.It Fl q 199Quiet output. 200Nothing is displayed except the summary lines at startup time and 201when finished. 202.It Fl R 203.Pq IPv4 only 204Record route. 205Includes the 206.Dv RECORD_ROUTE 207option in the 208.Dv ECHO_REQUEST 209packet and displays 210the route buffer on returned packets. 211Note that the IP header is only large enough for nine such routes. 212If more routes come back than should, such as due to an illegal spoofed 213packet, 214.Nm 215will print the route list and then truncate it at the correct spot. 216Many hosts ignore or discard this option. 217.It Fl s Ar packetsize 218Specify the number of data bytes to be sent. 219The default is 56, 220which translates into 64 ICMP data bytes 221when combined with the 8 bytes of ICMP header data. 222The maximum packet size is 65467 for IPv4 and 65527 for IPv6. 223.It Fl T Ar toskeyword 224.Pq IPv4 only 225Change the TOS value. 226.Ar toskeyword 227may be one of 228.Cm critical , 229.Cm inetcontrol , 230.Cm lowdelay , 231.Cm netcontrol , 232.Cm throughput , 233.Cm reliability , 234or one of the DiffServ Code Points: 235.Cm ef , 236.Cm af11 ... af43 , 237.Cm cs0 ... cs7 ; 238or a number in either hex or decimal. 239.It Fl t Ar ttl 240.Pq IPv4 only 241Use the specified time-to-live. 242.It Fl V Ar rtable 243Set the routing table to be used for outgoing packets. 244.It Fl v 245Verbose output. 246ICMP packets other than 247.Dv ECHO_REPLY 248that are received are listed. 249.It Fl w Ar maxwait 250Specify the maximum number of seconds to wait for responses 251after the last request has been sent. 252The default is 10. 253.El 254.Pp 255When using 256.Nm 257for fault isolation, it should first be run on the local host to verify 258that the local network interface is up and running. 259Then, hosts and gateways further and further away should be 260.Dq pinged . 261.Pp 262Round trip times and packet loss statistics are computed. 263If duplicate packets are received, they are not included in the packet 264loss calculation, although the round trip time of these packets is used 265in calculating the minimum/average/maximum round trip time numbers and 266the standard deviation. 267.Pp 268When the specified number of packets have been 269sent (and received), or if the program is terminated with a 270.Dv SIGINT , 271a brief summary is displayed. 272The summary information can also be displayed while 273.Nm 274is running by sending it a 275.Dv SIGINFO 276signal (see the 277.Cm status 278argument of 279.Xr stty 1 280for more information). 281.Pp 282This program is intended for use in network testing, measurement and 283management. 284Because of the load it can impose on the network, it is unwise to use 285.Nm 286during normal operations or from automated scripts. 287.Sh ICMP PACKET DETAILS 288An IP header without options is 20 bytes. 289An ICMP 290.Dv ECHO_REQUEST 291packet contains an additional 8 bytes worth of 292ICMP header followed by an arbitrary amount of data. 293When a 294.Ar packetsize 295is given, this indicates the size of this extra piece of data (the 296default is 56). 297Thus the amount of data received inside of an IP packet of type ICMP 298.Dv ECHO_REPLY 299will always be 8 bytes more than the requested data space 300(the ICMP header). 301.Pp 302If the data space is at least eight bytes large, 303.Nm 304uses the first eight bytes of this space to include a timestamp which 305it uses in the computation of round trip times. 306If less than eight bytes of pad are specified, no round trip times are 307given. 308.Sh DUPLICATE AND DAMAGED PACKETS 309.Nm 310will report duplicate and damaged packets. 311Duplicate packets should never occur, and seem to be caused by 312inappropriate link-level retransmissions. 313Duplicates may occur in many situations and are rarely (if ever) a 314good sign, although the presence of low levels of duplicates may not 315always be cause for alarm. 316.Pp 317Damaged packets are obviously serious cause for alarm and often 318indicate broken hardware somewhere in the 319.Nm 320packet's path (in the network or in the hosts). 321.Sh TRYING DIFFERENT DATA PATTERNS 322The (inter)network layer should never treat packets differently depending 323on the data contained in the data portion. 324Unfortunately, data-dependent problems have been known to sneak into 325networks and remain undetected for long periods of time. 326In many cases the particular pattern that will have problems is something 327that doesn't have sufficient 328.Dq transitions , 329such as all ones or all 330zeros, or a pattern right at the edge, such as almost all zeros. 331It isn't necessarily enough to specify a data pattern of all zeros (for 332example) on 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 can't be sent 339across your network or that takes much longer to transfer than other 340similar length files. 341You can then examine this file for repeated patterns that you can test 342using the 343.Fl p 344option of 345.Nm ping . 346.Sh TTL DETAILS 347The TTL value of an IP packet represents the maximum number of IP routers 348that the packet can go through before being thrown away. 349In current practice you can expect each router in the Internet to decrement 350the TTL field by exactly one. 351.Pp 352The TCP/IP specification states that the TTL field 353for TCP packets should be set to 60, 354but many systems use smaller values 355.Po 356.Bx 4.3 357uses 30, 358.Bx 4.2 359used 15 360.Pc . 361.Pp 362The maximum possible value of this field is 255, and most 363.Ux 364systems set the TTL field of ICMP 365.Dv ECHO_REQUEST 366packets to 255. 367This is why you will find you can 368.Dq ping 369some hosts, but not reach them 370with 371.Xr telnet 1 372or 373.Xr ftp 1 . 374.Pp 375In normal operation, 376.Nm 377prints the TTL value from the packet it receives. 378When a remote system receives a ping packet, it can do one of three things 379with the TTL field in its response: 380.Bl -bullet 381.It 382Not change it; this is what Berkeley 383.Ux 384systems did before the 385.Bx 4.3 Tahoe 386release. 387In this case the TTL value in the received packet will be 388255 minus the number of routers in the round trip path. 389.It 390Set it to 255; this is what current Berkeley 391.Ux 392systems do. 393In this case the TTL value in the received packet will be 394255 minus the number of routers in the path from the remote system 395to the pinging host. 396.It 397Set it to some other value. 398Some machines use the same value for ICMP packets 399that they use for TCP packets, for example either 30 or 60. 400Others may use completely wild values. 401.El 402.Sh EXIT STATUS 403.Nm 404exits 0 if at least one reply is received, 405and >0 if no reply is received or an error occurred. 406.Sh SEE ALSO 407.Xr netstat 1 , 408.Xr ifconfig 8 409.Sh HISTORY 410The 411.Nm 412command appeared in 413.Bx 4.3 . 414The 415.Nm ping6 416command was originally a separate program 417and first appeared in the WIDE Hydrangea IPv6 protocol stack kit. 418.Sh BUGS 419Many hosts and gateways ignore the 420.Dv RECORD_ROUTE 421option. 422.Pp 423The maximum IP header length is too small for options like 424.Dv RECORD_ROUTE 425to 426be completely useful. 427There's not much that can be done about this, however. 428.Pp 429Flood pinging is not recommended in general, and flood pinging the 430broadcast address should only be done under very controlled conditions. 431