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.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)ping.8 8.2 (Berkeley) 12/11/93 29.\" $FreeBSD: src/sbin/ping/ping.8,v 1.54 2006/04/05 12:30:42 glebius Exp $ 30.\" $DragonFly: src/sbin/ping/ping.8,v 1.5 2007/05/29 10:21:41 hasso Exp $ 31.\" 32.Dd April 4, 2006 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 AaDdfnoQqRrv 43.Op Fl c Ar count 44.Op Fl G Ar sweepmaxsize 45.Op Fl g Ar sweepminsize 46.Op Fl h Ar sweepincrsize 47.Op Fl i Ar wait 48.Op Fl l Ar preload 49.Op Fl M Cm mask | time 50.Op Fl m Ar ttl 51.Op Fl P Ar policy 52.Op Fl p Ar pattern 53.Op Fl S Ar src_addr 54.Op Fl s Ar packetsize 55.Op Fl t Ar timeout 56.Op Fl W Ar waittime 57.Op Fl z Ar tos 58.Ar host 59.Nm 60.Op Fl AaDdfLnoQqRrv 61.Op Fl c Ar count 62.Op Fl I Ar iface 63.Op Fl i Ar wait 64.Op Fl l Ar preload 65.Op Fl M Cm mask | time 66.Op Fl m Ar ttl 67.Op Fl P Ar policy 68.Op Fl p Ar pattern 69.Op Fl S Ar src_addr 70.Op Fl s Ar packetsize 71.Op Fl T Ar ttl 72.Op Fl t Ar timeout 73.Op Fl W Ar waittime 74.Op Fl z Ar tos 75.Ar mcast-group 76.Sh DESCRIPTION 77The 78.Nm 79utility uses the 80.Tn ICMP 81.No protocol Ap s mandatory 82.Tn ECHO_REQUEST 83datagram to elicit an 84.Tn ICMP ECHO_RESPONSE 85from a host or gateway. 86.Tn ECHO_REQUEST 87datagrams 88.Pq Dq pings 89have an IP and 90.Tn ICMP 91header, followed by a 92.Dq struct timeval 93and then an arbitrary number of 94.Dq pad 95bytes used to fill out the packet. 96The options are as follows: 97.Bl -tag -width indent 98.It Fl A 99Audible. 100Output a bell 101.Tn ( ASCII 1020x07) 103character when no packet is received before the next packet 104is transmitted. 105To cater for round-trip times that are longer than the interval 106between transmissions, further missing packets cause a bell only 107if the maximum number of unreceived packets has increased. 108.It Fl a 109Audible. 110Include a bell 111.Tn ( ASCII 1120x07) 113character in the output when any packet is received. 114This option is ignored 115if other format options are present. 116.It Fl c Ar count 117Stop after sending 118(and receiving) 119.Ar count 120.Tn ECHO_RESPONSE 121packets. 122If this option is not specified, 123.Nm 124will operate until interrupted. 125If this option is specified in conjunction with ping sweeps, 126each sweep will consist of 127.Ar count 128packets. 129.It Fl D 130Set the Don't Fragment bit. 131.It Fl d 132Set the 133.Dv SO_DEBUG 134option on the socket being used. 135.It Fl f 136Flood ping. 137Outputs packets as fast as they come back or one hundred times per second, 138whichever is more. 139For every 140.Tn ECHO_REQUEST 141sent a period 142.Dq .\& 143is printed, while for every 144.Tn ECHO_REPLY 145received a backspace is printed. 146This provides a rapid display of how many packets are being dropped. 147Only the super-user may use this option. 148.Bf -emphasis 149This can be very hard on a network and should be used with caution. 150.Ef 151.It Fl G Ar sweepmaxsize 152Specify the maximum size of 153.Tn ICMP 154payload when sending sweeping pings. 155This option is required for ping sweeps. 156.It Fl g Ar sweepminsize 157Specify the size of 158.Tn ICMP 159payload to start with when sending sweeping pings. 160The default value is 0. 161.It Fl h Ar sweepincrsize 162Specify the number of bytes to increment the size of 163.Tn ICMP 164payload after 165each sweep when sending sweeping pings. 166The default value is 1. 167.It Fl I Ar iface 168Source multicast packets with the given interface address. 169This flag only applies if the ping destination is a multicast address. 170.It Fl i Ar wait 171Wait 172.Ar wait 173seconds 174.Em between sending each packet . 175The default is to wait for one second between each packet. 176The wait time may be fractional, but only the super-user may specify 177values less than 1 second. 178This option is incompatible with the 179.Fl f 180option. 181.It Fl L 182Suppress loopback of multicast packets. 183This flag only applies if the ping destination is a multicast address. 184.It Fl l Ar preload 185If 186.Ar preload 187is specified, 188.Nm 189sends that many packets as fast as possible before falling into its normal 190mode of behavior. 191Only the super-user may use this option. 192.It Fl M Cm mask | time 193Use 194.Dv ICMP_MASKREQ 195or 196.Dv ICMP_TSTAMP 197instead of 198.Dv ICMP_ECHO . 199For 200.Cm mask , 201print the netmask of the remote machine. 202Set the 203.Va net.inet.icmp.maskrepl 204MIB variable to enable 205.Dv ICMP_MASKREPLY . 206For 207.Cm time , 208print the origination, reception and transmission timestamps. 209.It Fl m Ar ttl 210Set the IP Time To Live for outgoing packets. 211If not specified, the kernel uses the value of the 212.Va net.inet.ip.ttl 213MIB variable. 214.It Fl n 215Numeric output only. 216No attempt will be made to lookup symbolic names for host addresses. 217.It Fl o 218Exit successfully after receiving one reply packet. 219.It Fl P Ar policy 220.Ar policy 221specifies IPsec policy for the ping session. 222For details please refer to 223.Xr ipsec 4 224and 225.Xr ipsec_set_policy 3 . 226.It Fl p Ar pattern 227You may specify up to 16 228.Dq pad 229bytes to fill out the packet you send. 230This is useful for diagnosing data-dependent problems in a network. 231For example, 232.Dq Li \-p ff 233will cause the sent packet to be filled with all 234ones. 235.It Fl Q 236Somewhat quiet output. 237.No Don Ap t 238display ICMP error messages that are in response to our query messages. 239Originally, the 240.Fl v 241flag was required to display such errors, but 242.Fl v 243displays all ICMP error messages. 244On a busy machine, this output can be overbearing. 245Without the 246.Fl Q 247flag, 248.Nm 249prints out any ICMP error messages caused by its own ECHO_REQUEST 250messages. 251.It Fl q 252Quiet output. 253Nothing is displayed except the summary lines at startup time and 254when finished. 255.It Fl R 256Record route. 257Includes the 258.Tn RECORD_ROUTE 259option in the 260.Tn ECHO_REQUEST 261packet and displays 262the route buffer on returned packets. 263Note that the IP header is only large enough for nine such routes; 264the 265.Xr traceroute 8 266command is usually better at determining the route packets take to a 267particular destination. 268If more routes come back than should, such as due to an illegal spoofed 269packet, ping will print the route list and then truncate it at the correct 270spot. 271Many hosts ignore or discard the 272.Tn RECORD_ROUTE 273option. 274.It Fl r 275Bypass the normal routing tables and send directly to a host on an attached 276network. 277If the host is not on a directly-attached network, an error is returned. 278This option can be used to ping a local host through an interface 279that has no route through it 280(e.g., after the interface was dropped by 281.Xr routed 8 ) . 282.It Fl S Ar src_addr 283Use the following IP address as the source address in outgoing packets. 284On hosts with more than one IP address, this option can be used to 285force the source address to be something other than the IP address 286of the interface the probe packet is sent on. 287If the IP address 288is not one of this machine's interface addresses, an error is 289returned and nothing is sent. 290.It Fl s Ar packetsize 291Specify the number of data bytes to be sent. 292The default is 56, which translates into 64 293.Tn ICMP 294data bytes when combined 295with the 8 bytes of 296.Tn ICMP 297header data. 298Only the super-user may specify values more than default. 299This option cannot be used with ping sweeps. 300.It Fl T Ar ttl 301Set the IP Time To Live for multicasted packets. 302This flag only applies if the ping destination is a multicast address. 303.It Fl t Ar timeout 304Specify a timeout, in seconds, before ping exits regardless of how 305many packets have been received. 306.It Fl v 307Verbose output. 308.Tn ICMP 309packets other than 310.Tn ECHO_RESPONSE 311that are received are listed. 312.It Fl W Ar waittime 313Time in milliseconds to wait for a reply for each packet sent. 314If a reply arrives later, the packet is not printed as replied, but 315considered as replied when calculating statistics. 316.It Fl z Ar tos 317Use the specified type of service. 318.El 319.Pp 320When using 321.Nm 322for fault isolation, it should first be run on the local host, to verify 323that the local network interface is up and running. 324Then, hosts and gateways further and further away should be 325.Dq pinged . 326Round-trip times and packet loss statistics are computed. 327If duplicate packets are received, they are not included in the packet 328loss calculation, although the round trip time of these packets is used 329in calculating the round-trip time statistics. 330When the specified number of packets have been sent 331(and received) 332or if the program is terminated with a 333.Dv SIGINT , 334a brief summary is displayed, showing the number of packets sent and 335received, and the minimum, mean, maximum, and standard deviation of 336the round-trip times. 337.Pp 338If 339.Nm 340receives a 341.Dv SIGINFO 342(see the 343.Cm status 344argument for 345.Xr stty 1 ) 346signal, the current number of packets sent and received, and the 347minimum, mean, and maximum of the round-trip times will be written to 348the standard error output. 349.Pp 350This program is intended for use in network testing, measurement and 351management. 352Because of the load it can impose on the network, it is unwise to use 353.Nm 354during normal operations or from automated scripts. 355.Sh ICMP PACKET DETAILS 356An IP header without options is 20 bytes. 357An 358.Tn ICMP 359.Tn ECHO_REQUEST 360packet contains an additional 8 bytes worth of 361.Tn ICMP 362header followed by an arbitrary amount of data. 363When a 364.Ar packetsize 365is given, this indicated the size of this extra piece of data 366(the default is 56). 367Thus the amount of data received inside of an IP packet of type 368.Tn ICMP 369.Tn ECHO_REPLY 370will always be 8 bytes more than the requested data space 371(the 372.Tn ICMP 373header). 374.Pp 375If the data space is at least eight bytes large, 376.Nm 377uses the first eight bytes of this space to include a timestamp which 378it uses in the computation of round trip times. 379If less than eight bytes of pad are specified, no round trip times are 380given. 381.Sh DUPLICATE AND DAMAGED PACKETS 382The 383.Nm 384utility will report duplicate and damaged packets. 385Duplicate packets should never occur when pinging a unicast address, 386and seem to be caused by 387inappropriate link-level retransmissions. 388Duplicates may occur in many situations and are rarely 389(if ever) 390a good sign, although the presence of low levels of duplicates may not 391always be cause for alarm. 392Duplicates are expected when pinging a broadcast or multicast address, 393since they are not really duplicates but replies from different hosts 394to the same request. 395.Pp 396Damaged packets are obviously serious cause for alarm and often 397indicate broken hardware somewhere in the 398.Nm 399packet's path (in the network or in the hosts). 400.Sh TRYING DIFFERENT DATA PATTERNS 401The 402(inter)network 403layer should never treat packets differently depending on the data 404contained in the data portion. 405Unfortunately, data-dependent problems have been known to sneak into 406networks and remain undetected for long periods of time. 407In many cases the particular pattern that will have problems is something 408that does not have sufficient 409.Dq transitions , 410such as all ones or all zeros, or a pattern right at the edge, such as 411almost all zeros. 412It is not 413necessarily enough to specify a data pattern of all zeros (for example) 414on the command line because the pattern that is of interest is 415at the data link level, and the relationship between what you type and 416what the controllers transmit can be complicated. 417.Pp 418This means that if you have a data-dependent problem you will probably 419have to do a lot of testing to find it. 420If you are lucky, you may manage to find a file that either 421cannot 422be sent across your network or that takes much longer to transfer than 423other similar length files. 424You can then examine this file for repeated patterns that you can test 425using the 426.Fl p 427option of 428.Nm . 429.Sh TTL DETAILS 430The 431.Tn TTL 432value of an IP packet represents the maximum number of IP routers 433that the packet can go through before being thrown away. 434In current practice you can expect each router in the Internet to decrement 435the 436.Tn TTL 437field by exactly one. 438.Pp 439The 440.Tn TCP/IP 441specification recommends setting the 442.Tn TTL 443field for 444.Tn IP 445packets to 64, but many systems use smaller values 446.No ( Bx 4.3 447uses 30, 448.Bx 4.2 449used 15). 450.Pp 451The maximum possible value of this field is 255, and most 452.Ux 453systems set 454the 455.Tn TTL 456field of 457.Tn ICMP ECHO_REQUEST 458packets to 255. 459This is why you will find you can 460.Dq ping 461some hosts, but not reach them with 462.Xr telnet 1 463or 464.Xr ftp 1 . 465.Pp 466In normal operation 467.Nm 468prints the ttl value from the packet it receives. 469When a remote system receives a ping packet, it can do one of three things 470with the 471.Tn TTL 472field in its response: 473.Bl -bullet 474.It 475Not change it; this is what 476.Bx 477systems did before the 478.Bx 4.3 tahoe 479release. 480In this case the 481.Tn TTL 482value in the received packet will be 255 minus the 483number of routers in the round-trip path. 484.It 485Set it to 255; this is what current 486.Bx 487systems do. 488In this case the 489.Tn TTL 490value in the received packet will be 255 minus the 491number of routers in the path 492.Em from 493the remote system 494.Em to 495the 496.Nm Ns Em ing 497host. 498.It 499Set it to some other value. 500Some machines use the same value for 501.Tn ICMP 502packets that they use for 503.Tn TCP 504packets, for example either 30 or 60. 505Others may use completely wild values. 506.El 507.Sh DIAGNOSTICS 508The 509.Nm 510utility returns an exit status of zero if at least one response was 511heard from the specified 512.Ar host ; 513a status of two if the transmission was successful but no responses 514were received; or another value 515(from 516.In sysexits.h ) 517if an error occurred. 518.Sh SEE ALSO 519.Xr netstat 1 , 520.Xr ifconfig 8 , 521.Xr routed 8 , 522.Xr traceroute 8 523.Sh HISTORY 524The 525.Nm 526utility appeared in 527.Bx 4.3 . 528.Sh AUTHORS 529The original 530.Nm 531utility was written by 532.An Mike Muuss 533while at the US Army Ballistics 534Research Laboratory. 535.Sh BUGS 536Many Hosts and Gateways ignore the 537.Tn RECORD_ROUTE 538option. 539.Pp 540The maximum IP header length is too small for options like 541.Tn RECORD_ROUTE 542to be completely useful. 543.No There Ap s 544not much that can be done about this, however. 545.Pp 546Flood pinging is not recommended in general, and flood pinging the 547broadcast address should only be done under very controlled conditions. 548.Pp 549The 550.Fl v 551option is not worth much on busy hosts. 552