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