sbin/ping/ping.8

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