sbin/ping6/ping6.8

   1 .\"     $KAME: ping6.8,v 1.58 2003/06/20 12:00:22 itojun Exp $
   2 .\"
   3 .\" Copyright (C) 1995, 1996, 1997, and 1998 WIDE Project.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the project nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd September 22, 2014
  33 .Dt PING6 8
  34 .Os
  35 .Sh NAME
  36 .Nm ping6
  37 .Nd send
  38 .Tn ICMPv6 ECHO_REQUEST
  39 packets to network hosts
  40 .Sh SYNOPSIS
  41 .Nm
  42 .\" without ipsec, or new ipsec
  43 .Op Fl DdfHmnNoqrRtvwW
  44 .\" old ipsec
  45 .\" .Op Fl ADdEfmnNqRtvwW
  46 .Bk -words
  47 .Op Fl a Ar addrtype
  48 .Ek
  49 .Bk -words
  50 .Op Fl b Ar bufsiz
  51 .Ek
  52 .Bk -words
  53 .Op Fl c Ar count
  54 .Ek
  55 .Bk -words
  56 .Op Fl g Ar gateway
  57 .Ek
  58 .Bk -words
  59 .Op Fl h Ar hoplimit
  60 .Ek
  61 .Bk -words
  62 .Op Fl I Ar interface
  63 .Ek
  64 .Bk -words
  65 .Op Fl i Ar wait
  66 .Ek
  67 .Bk -words
  68 .Op Fl x Ar waittime
  69 .Ek
  70 .Bk -words
  71 .Op Fl X Ar timeout
  72 .Ek
  73 .Bk -words
  74 .Op Fl l Ar preload
  75 .Ek
  76 .Bk -words
  77 .\" new ipsec
  78 .Op Fl P Ar policy
  79 .Ek
  80 .Bk -words
  81 .Op Fl p Ar pattern
  82 .Ek
  83 .Bk -words
  84 .Op Fl S Ar sourceaddr
  85 .Ek
  86 .Bk -words
  87 .Op Fl s Ar packetsize
  88 .Ek
  89 .Bk -words
  90 .Op Ar hops ...
  91 .Ek
  92 .Bk -words
  93 .Ar host
  94 .Ek
  95 .Sh DESCRIPTION
  96 The
  97 .Nm
  98 utility uses the
  99 .Tn ICMPv6
 100 protocol's mandatory
 101 .Tn ICMP6_ECHO_REQUEST
 102 datagram to elicit an
 103 .Tn ICMP6_ECHO_REPLY
 104 from a host or gateway.
 105 .Tn ICMP6_ECHO_REQUEST
 106 datagrams (``pings'') have an IPv6 header,
 107 and
 108 .Tn ICMPv6
 109 header formatted as documented in RFC2463.
 110 The options are as follows:
 111 .Bl -tag -width Ds
 112 .\" old ipsec
 113 .\" .It Fl A
 114 .\" Enables transport-mode IPsec authentication header
 115 .\" (experimental).
 116 .It Fl a Ar addrtype
 117 Generate ICMPv6 Node Information Node Addresses query, rather than echo-request.
 118 .Ar addrtype
 119 must be a string constructed of the following characters.
 120 .Bl -tag -width Ds -compact
 121 .It Ic a
 122 requests unicast addresses from all of the responder's interfaces.
 123 If the character is omitted,
 124 only those addresses which belong to the interface which has the
 125 responder's address are requests.
 126 .It Ic c
 127 requests responder's IPv4-compatible and IPv4-mapped addresses.
 128 .It Ic g
 129 requests responder's global-scope addresses.
 130 .It Ic s
 131 requests responder's site-local addresses.
 132 .It Ic l
 133 requests responder's link-local addresses.
 134 .It Ic A
 135 requests responder's anycast addresses.
 136 Without this character, the responder will return unicast addresses only.
 137 With this character, the responder will return anycast addresses only.
 138 Note that the specification does not specify how to get responder's
 139 anycast addresses.
 140 This is an experimental option.
 141 .El
 142 .It Fl b Ar bufsiz
 143 Set socket buffer size.
 144 .It Fl c Ar count
 145 Stop after sending
 146 (and receiving)
 147 .Ar count
 148 .Tn ECHO_RESPONSE
 149 packets.
 150 .It Fl D
 151 Disable IPv6 fragmentation.
 152 .It Fl d
 153 Set the
 154 .Dv SO_DEBUG
 155 option on the socket being used.
 156 .\" .It Fl E
 157 .\" Enables transport-mode IPsec encapsulated security payload
 158 .\" (experimental).
 159 .It Fl f
 160 Flood ping.
 161 Outputs packets as fast as they come back or one hundred times per second,
 162 whichever is more.
 163 For every
 164 .Tn ECHO_REQUEST
 165 sent a period
 166 .Dq \&.
 167 is printed, while for every
 168 .Tn ECHO_REPLY
 169 received a backspace is printed.
 170 This provides a rapid display of how many packets are being dropped.
 171 Only the super-user may use this option.
 172 .Bf -emphasis
 173 This can be very hard on a network and should be used with caution.
 174 .Ef
 175 .It Fl g Ar gateway
 176 Specifies to use
 177 .Ar gateway
 178 as the next hop to the destination.
 179 The gateway must be a neighbor of the sending node.
 180 .It Fl H
 181 Specifies to try reverse-lookup of IPv6 addresses.
 182 The
 183 .Nm
 184 utility does not try reverse-lookup unless the option is specified.
 185 .It Fl h Ar hoplimit
 186 Set the IPv6 hoplimit.
 187 .It Fl I Ar interface
 188 Source packets with the given interface address.
 189 This flag applies if the ping destination is a multicast address,
 190 or link-local/site-local unicast address.
 191 .It Fl i Ar wait
 192 Wait
 193 .Ar wait
 194 seconds
 195 .Em between sending each packet .
 196 The default is to wait for one second between each packet.
 197 This option is incompatible with the
 198 .Fl f
 199 option.
 200 .It Fl x Ar waittime
 201 Time in milliseconds to wait for a reply for each packet sent.
 202 If a reply arrives later,
 203 the packet is not printed as replied,
 204 but considered as replied when calculating statistics.
 205 .It Fl X Ar timeout
 206 Specify a timeout,
 207 in seconds,
 208 before ping exits regardless of how many packets have been received.
 209 .It Fl l Ar preload
 210 If
 211 .Ar preload
 212 is specified,
 213 .Nm
 214 sends that many packets as fast as possible before falling into its normal
 215 mode of behavior.
 216 Only the super-user may use this option.
 217 .It Fl m
 218 By default,
 219 .Nm
 220 asks the kernel to fragment packets to fit into the minimum IPv6 MTU.
 221 The
 222 .Fl m
 223 option
 224 will suppress the behavior in the following two levels:
 225 when the option is specified once, the behavior will be disabled for
 226 unicast packets.
 227 When the option is more than once, it will be disabled for both
 228 unicast and multicast packets.
 229 .It Fl n
 230 Numeric output only.
 231 No attempt will be made to lookup symbolic names from addresses in the reply.
 232 .It Fl N
 233 Probe node information multicast group address
 234 .Pq Li ff02::2:ffxx:xxxx .
 235 .Ar host
 236 must be string hostname of the target
 237 (must not be a numeric IPv6 address).
 238 Node information multicast group will be computed based on given
 239 .Ar host ,
 240 and will be used as the final destination.
 241 Since node information multicast group is a link-local multicast group,
 242 outgoing interface needs to be specified by
 243 .Fl I
 244 option.
 245 .Pp
 246 When specified twice, the address
 247 .Pq Li ff02::2:xxxx:xxxx
 248 is used instead.
 249 The former is in RFC 4620, the latter is in an old Internet Draft
 250 draft-ietf-ipngwg-icmp-name-lookup.
 251 Note that KAME-derived implementations including
 252 .Fx
 253 use the latter.
 254 .It Fl o
 255 Exit successfully after receiving one reply packet.
 256 .It Fl p Ar pattern
 257 You may specify up to 16
 258 .Dq pad
 259 bytes to fill out the packet you send.
 260 This is useful for diagnosing data-dependent problems in a network.
 261 For example,
 262 .Dq Li \-p ff
 263 will cause the sent packet to be filled with all
 264 ones.
 265 .\" new ipsec
 266 .It Fl P Ar policy
 267 .Ar policy
 268 specifies IPsec policy to be used for the probe.
 269 .It Fl q
 270 Quiet output.
 271 Nothing is displayed except the summary lines at startup time and
 272 when finished.
 273 .It Fl r
 274 Audible.
 275 Include a bell
 276 .Tn ( ASCII
 277 0x07)
 278 character in the output when any packet is received.
 279 .It Fl R
 280 Audible.
 281 Output a bell
 282 .Tn ( ASCII
 283 0x07)
 284 character when no packet is received before the next packet
 285 is transmitted.
 286 To cater for round-trip times that are longer than the interval
 287 between transmissions, further missing packets cause a bell only
 288 if the maximum number of unreceived packets has increased.
 289 .It Fl S Ar sourceaddr
 290 Specifies the source address of request packets.
 291 The source address must be one of the unicast addresses of the sending node,
 292 and must be numeric.
 293 .It Fl s Ar packetsize
 294 Specifies the number of data bytes to be sent.
 295 The default is 56, which translates into 64
 296 .Tn ICMP
 297 data bytes when combined
 298 with the 8 bytes of
 299 .Tn ICMP
 300 header data.
 301 You may need to specify
 302 .Fl b
 303 as well to extend socket buffer size.
 304 .It Fl t
 305 Generate ICMPv6 Node Information supported query types query,
 306 rather than echo-request.
 307 .Fl s
 308 has no effect if
 309 .Fl t
 310 is specified.
 311 .It Fl v
 312 Verbose output.
 313 .Tn ICMP
 314 packets other than
 315 .Tn ECHO_RESPONSE
 316 that are received are listed.
 317 .It Fl w
 318 Generate ICMPv6 Node Information DNS Name query, rather than echo-request.
 319 .Fl s
 320 has no effect if
 321 .Fl w
 322 is specified.
 323 .It Fl W
 324 Same as
 325 .Fl w ,
 326 but with old packet format based on 03 draft.
 327 This option is present for backward compatibility.
 328 .Fl s
 329 has no effect if
 330 .Fl w
 331 is specified.
 332 .It Ar hops
 333 IPv6 addresses for intermediate nodes,
 334 which will be put into type 0 routing header.
 335 .It Ar host
 336 IPv6 address of the final destination node.
 337 .El
 338 .Pp
 339 When using
 340 .Nm
 341 for fault isolation, it should first be run on the local host, to verify
 342 that the local network interface is up and running.
 343 Then, hosts and gateways further and further away should be
 344 .Dq pinged .
 345 Round-trip times and packet loss statistics are computed.
 346 If duplicate packets are received, they are not included in the packet
 347 loss calculation, although the round trip time of these packets is used
 348 in calculating the round-trip time statistics.
 349 When the specified number of packets have been sent
 350 (and received)
 351 or if the program is terminated with a
 352 .Dv SIGINT ,
 353 a brief summary is displayed, showing the number of packets sent and
 354 received, and the minimum, mean, maximum, and standard deviation of
 355 the round-trip times.
 356 .Pp
 357 If
 358 .Nm
 359 receives a
 360 .Dv SIGINFO
 361 (see the
 362 .Cm status
 363 argument for
 364 .Xr stty 1 )
 365 signal, the current number of packets sent and received, and the
 366 minimum, mean, maximum, and standard deviation of the round-trip times
 367 will be written to the standard output in the same format as the
 368 standard completion message.
 369 .Pp
 370 This program is intended for use in network testing, measurement and
 371 management.
 372 Because of the load it can impose on the network, it is unwise to use
 373 .Nm
 374 during normal operations or from automated scripts.
 375 .\" .Sh ICMP PACKET DETAILS
 376 .\" An IP header without options is 20 bytes.
 377 .\" An
 378 .\" .Tn ICMP
 379 .\" .Tn ECHO_REQUEST
 380 .\" packet contains an additional 8 bytes worth of
 381 .\" .Tn ICMP
 382 .\" header followed by an arbitrary amount of data.
 383 .\" When a
 384 .\" .Ar packetsize
 385 .\" is given, this indicated the size of this extra piece of data
 386 .\" (the default is 56).
 387 .\" Thus the amount of data received inside of an IP packet of type
 388 .\" .Tn ICMP
 389 .\" .Tn ECHO_REPLY
 390 .\" will always be 8 bytes more than the requested data space
 391 .\" (the
 392 .\" .Tn ICMP
 393 .\" header).
 394 .\" .Pp
 395 .\" If the data space is at least eight bytes large,
 396 .\" .Nm
 397 .\" uses the first eight bytes of this space to include a timestamp which
 398 .\" it uses in the computation of round trip times.
 399 .\" If less than eight bytes of pad are specified, no round trip times are
 400 .\" given.
 401 .Sh DUPLICATE AND DAMAGED PACKETS
 402 The
 403 .Nm
 404 utility will report duplicate and damaged packets.
 405 Duplicate packets should never occur when pinging a unicast address,
 406 and seem to be caused by
 407 inappropriate link-level retransmissions.
 408 Duplicates may occur in many situations and are rarely
 409 (if ever)
 410 a good sign, although the presence of low levels of duplicates may not
 411 always be cause for alarm.
 412 Duplicates are expected when pinging a broadcast or multicast address,
 413 since they are not really duplicates but replies from different hosts
 414 to the same request.
 415 .Pp
 416 Damaged packets are obviously serious cause for alarm and often
 417 indicate broken hardware somewhere in the
 418 .Nm
 419 packet's path
 420 (in the network or in the hosts).
 421 .Sh TRYING DIFFERENT DATA PATTERNS
 422 The
 423 (inter)network
 424 layer should never treat packets differently depending on the data
 425 contained in the data portion.
 426 Unfortunately, data-dependent problems have been known to sneak into
 427 networks and remain undetected for long periods of time.
 428 In many cases the particular pattern that will have problems is something
 429 that does not have sufficient
 430 .Dq transitions ,
 431 such as all ones or all zeros, or a pattern right at the edge, such as
 432 almost all zeros.
 433 It is not
 434 necessarily enough to specify a data pattern of all zeros (for example)
 435 on the command line because the pattern that is of interest is
 436 at the data link level, and the relationship between what you type and
 437 what the controllers transmit can be complicated.
 438 .Pp
 439 This means that if you have a data-dependent problem you will probably
 440 have to do a lot of testing to find it.
 441 If you are lucky, you may manage to find a file that either
 442 cannot
 443 be sent across your network or that takes much longer to transfer than
 444 other similar length files.
 445 You can then examine this file for repeated patterns that you can test
 446 using the
 447 .Fl p
 448 option of
 449 .Nm .
 450 .Sh EXIT STATUS
 451 The
 452 .Nm
 453 utility returns 0 on success (the host is alive),
 454 2 if the transmission was successful but no responses were received,
 455 any other non-zero value if the arguments are incorrect or
 456 another error has occurred.
 457 .Sh EXAMPLES
 458 Normally,
 459 .Nm
 460 works just like
 461 .Xr ping 8
 462 would work; the following will send ICMPv6 echo request to
 463 .Li dst.foo.com .
 464 .Bd -literal -offset indent
 465 ping6 -n dst.foo.com
 466 .Ed
 467 .Pp
 468 The following will probe hostnames for all nodes on the network link attached to
 469 .Li wi0
 470 interface.
 471 The address
 472 .Li ff02::1
 473 is named the link-local all-node multicast address, and the packet would
 474 reach every node on the network link.
 475 .Bd -literal -offset indent
 476 ping6 -w ff02::1%wi0
 477 .Ed
 478 .Pp
 479 The following will probe addresses assigned to the destination node,
 480 .Li dst.foo.com .
 481 .Bd -literal -offset indent
 482 ping6 -a agl dst.foo.com
 483 .Ed
 484 .Sh SEE ALSO
 485 .Xr netstat 1 ,
 486 .Xr icmp6 4 ,
 487 .Xr inet6 4 ,
 488 .Xr ip6 4 ,
 489 .Xr ifconfig 8 ,
 490 .Xr ping 8 ,
 491 .Xr routed 8 ,
 492 .Xr traceroute 8 ,
 493 .Xr traceroute6 8
 494 .Rs
 495 .%A A. Conta
 496 .%A S. Deering
 497 .%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification"
 498 .%N RFC2463
 499 .%D December 1998
 500 .Re
 501 .Rs
 502 .%A Matt Crawford
 503 .%T "IPv6 Node Information Queries"
 504 .%N draft-ietf-ipngwg-icmp-name-lookups-09.txt
 505 .%D May 2002
 506 .%O work in progress material
 507 .Re
 508 .Sh HISTORY
 509 The
 510 .Xr ping 8
 511 utility appeared in
 512 .Bx 4.3 .
 513 The
 514 .Nm
 515 utility with IPv6 support first appeared in the WIDE Hydrangea IPv6
 516 protocol stack kit.
 517 .Pp
 518 IPv6 and IPsec support based on the KAME Project
 519 .Pq Pa http://www.kame.net/
 520 stack was initially integrated into
 521 .Fx 4.0 .
 522 .Sh BUGS
 523 The
 524 .Nm
 525 utility
 526 is intentionally separate from
 527 .Xr ping 8 .
 528 .Pp
 529 There have been many discussions on why we separate
 530 .Nm
 531 and
 532 .Xr ping 8 .
 533 Some people argued that it would be more convenient to uniform the
 534 ping command for both IPv4 and IPv6.
 535 The followings are an answer to the request.
 536 .Pp
 537 From a developer's point of view:
 538 since the underling raw sockets API is totally different between IPv4
 539 and IPv6, we would end up having two types of code base.
 540 There would actually be less benefit to uniform the two commands
 541 into a single command from the developer's standpoint.
 542 .Pp
 543 From an operator's point of view: unlike ordinary network applications
 544 like remote login tools, we are usually aware of address family when using
 545 network management tools.
 546 We do not just want to know the reachability to the host, but want to know the
 547 reachability to the host via a particular network protocol such as
 548 IPv6.
 549 Thus, even if we had a unified
 550 .Xr ping 8
 551 command for both IPv4 and IPv6, we would usually type a
 552 .Fl 6
 553 or
 554 .Fl 4
 555 option (or something like those) to specify the particular address family.
 556 This essentially means that we have two different commands.