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