Changeset View
Standalone View
sbin/ping/ping.8
Show All 22 Lines | |||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||
.\" | .\" | ||||
.\" @(#)ping.8 8.2 (Berkeley) 12/11/93 | .\" @(#)ping.8 8.2 (Berkeley) 12/11/93 | ||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||
.\" | .\" | ||||
.Dd August 22, 2019 | .Dd August 23, 2019 | ||||
.Dt PING 8 | .Dt PING 8 | ||||
.Os | .Os | ||||
.Sh NAME | .Sh NAME | ||||
.Nm ping | .Nm ping | ||||
.Nd send | .Nd send | ||||
.Tn ICMP ECHO_REQUEST | .Tn ICMP | ||||
or | |||||
.Tn ICMPv6 ECHO_REQUEST | |||||
packets to network hosts | packets to network hosts | ||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||
.Nm | .Nm | ||||
.Op Fl AaDdfHnoQqRrv | .Op Fl 4AaDdfHnoQqRrv | ||||
.Op Fl c Ar count | .Op Fl c Ar count | ||||
.Op Fl G Ar sweepmaxsize | .Op Fl G Ar sweepmaxsize | ||||
.Op Fl g Ar sweepminsize | .Op Fl g Ar sweepminsize | ||||
.Op Fl h Ar sweepincrsize | .Op Fl h Ar sweepincrsize | ||||
.Op Fl i Ar wait | .Op Fl i Ar wait | ||||
.Op Fl l Ar preload | .Op Fl l Ar preload | ||||
.Op Fl M Cm mask | time | .Op Fl M Cm mask | time | ||||
.Op Fl m Ar ttl | .Op Fl m Ar ttl | ||||
.Op Fl P Ar policy | .Op Fl P Ar policy | ||||
.Op Fl p Ar pattern | .Op Fl p Ar pattern | ||||
.Op Fl S Ar src_addr | .Op Fl S Ar src_addr | ||||
.Op Fl s Ar packetsize | .Op Fl s Ar packetsize | ||||
.Op Fl t Ar timeout | .Op Fl t Ar timeout | ||||
.Op Fl W Ar waittime | .Op Fl W Ar waittime | ||||
.Op Fl z Ar tos | .Op Fl z Ar tos | ||||
.Ar host | .Ar IPv4-host | ||||
.Nm | .Nm | ||||
.Op Fl AaDdfHLnoQqRrv | .Op Fl 4AaDdfHLnoQqRrv | ||||
.Op Fl c Ar count | .Op Fl c Ar count | ||||
.Op Fl I Ar iface | .Op Fl I Ar iface | ||||
asomers: It's dumb to call this argument `iface` when it must be an address. What's the difference… | |||||
jansucanUnsubmitted Done Inline ActionsWell, ping6's -I is less equal to ping's I than it should be. For ping6, argument to the -I is an interface name which is converted to an interface index by if_nametoindex and saved to "struct in6_pktinfo.ipi6_ifindex" or "struct sockaddr_in6.sin6_scope_id". An argument to the -S is resolved by cap_getaddrinfo and causes bind to be called. I lack some knowledge to tell how redundant those two options are. I will try to work on it. jansucan: Well, ping6's `-I` is less equal to ping's `I` than it should be.
For ping6, argument to the `… | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsDon't worry about it for now; the problem predates you and it's not really related to this review. asomers: Don't worry about it for now; the problem predates you and it's not really related to this… | |||||
.Op Fl i Ar wait | .Op Fl i Ar wait | ||||
.Op Fl l Ar preload | .Op Fl l Ar preload | ||||
.Op Fl M Cm mask | time | .Op Fl M Cm mask | time | ||||
.Op Fl m Ar ttl | .Op Fl m Ar ttl | ||||
.Op Fl P Ar policy | .Op Fl P Ar policy | ||||
.Op Fl p Ar pattern | .Op Fl p Ar pattern | ||||
.Op Fl S Ar src_addr | .Op Fl S Ar src_addr | ||||
.Op Fl s Ar packetsize | .Op Fl s Ar packetsize | ||||
.Op Fl T Ar ttl | .Op Fl T Ar ttl | ||||
.Op Fl t Ar timeout | .Op Fl t Ar timeout | ||||
.Op Fl W Ar waittime | .Op Fl W Ar waittime | ||||
.Op Fl z Ar tos | .Op Fl z Ar tos | ||||
.Ar mcast-group | .Ar IPv4-mcast-group | ||||
.Nm | |||||
.Op Fl 6aAdDEfHnNoOquvyYZ | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsWhen sorting alphabetically, BIG letters like A come before small ones like a. asomers: When sorting alphabetically, BIG letters like A come before small ones like a. | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Op Fl b Ar bufsiz | |||||
.Op Fl c Ar count | |||||
.Op Fl e Ar gateway | |||||
.Op Fl I Ar interface | |||||
.Op Fl i Ar wait | |||||
.Op Fl k Ar addrtype | |||||
.Op Fl l Ar preload | |||||
.Op Fl m Ar hoplimit | |||||
.Op Fl P Ar policy | |||||
.Op Fl p Ar pattern | |||||
.Op Fl S Ar sourceaddr | |||||
.Op Fl s Ar packetsize | |||||
.Op Fl t Ar timeout | |||||
.Op Fl W Ar waittime | |||||
.Op Ar IPv6-hops ... | |||||
.Ar IPv6-host | |||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||
The | The | ||||
.Nm | .Nm | ||||
utility uses the | utility invoked with an IPv4 target | ||||
.Ns ( Ar IPv4-host No or Ar IPv4-mcast-group Ns ) | |||||
uses the | |||||
.Tn ICMP | .Tn ICMP | ||||
.No protocol Ap s mandatory | .No protocol Ap s mandatory | ||||
.Tn ECHO_REQUEST | .Tn ECHO_REQUEST | ||||
datagram to elicit an | datagram to elicit an | ||||
.Tn ICMP ECHO_RESPONSE | .Tn ICMP ECHO_RESPONSE | ||||
from a host or gateway. | from a host or gateway. | ||||
.Tn ECHO_REQUEST | .Tn ECHO_REQUEST | ||||
datagrams | datagrams | ||||
.Pq Dq pings | .Pq Dq pings | ||||
have an IP and | have an IP and | ||||
.Tn ICMP | .Tn ICMP | ||||
header, followed by a | header, followed by a | ||||
.Dq struct timeval | .Dq struct timeval | ||||
and then an arbitrary number of | and then an arbitrary number of | ||||
.Dq pad | .Dq pad | ||||
bytes used to fill out the packet. | bytes used to fill out the packet. | ||||
The options are as follows: | .Pp | ||||
When invoked with IPv6 target | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsNeeds an article here: "an IPv6 target". asomers: Needs an article here: "an IPv6 target". | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Ns ( Ar IPv6-host Ns ) Ns , | |||||
it uses the | |||||
.Tn ICMPv6 | |||||
protocol's mandatory | |||||
.Tn ICMP6_ECHO_REQUEST | |||||
datagram to elicit an | |||||
.Tn ICMP6_ECHO_REPLY | |||||
.Ns . | |||||
.Tn ICMP6_ECHO_REQUEST | |||||
datagrams have an IPv6 header and | |||||
.Tn ICMPv6 | |||||
header formatted as documented in RFC 2463. | |||||
.Pp | |||||
When invoked with target of unknown IP version, the version to which | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsInstead of "target of unknown IP version", couldn't you simply say "hostname"? asomers: Instead of "target of unknown IP version", couldn't you simply say "hostname"? | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
the target is resolved first is used. In that case, the options and | |||||
arguments used must be valid for the specific IP version, otherwise | |||||
.Nm | |||||
exits with an error. If the target is resolved to both IPv4 and IPv6, | |||||
specific IP version can be requested by | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsNeed another article: "the specific IP version". asomers: Need another article: "the specific IP version". | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Fl 4 | |||||
or | |||||
.Fl 6 | |||||
options, respectively. | |||||
.Ss Options common to both IPv4 and IPv6 targets | |||||
.Bl -tag -width indent | .Bl -tag -width indent | ||||
.It Fl A | .It Fl A | ||||
Audible. | Audible. | ||||
Output a bell | Output a bell | ||||
.Tn ( ASCII | .Tn ( ASCII | ||||
0x07) | 0x07) | ||||
character when no packet is received before the next packet | character when no packet is received before the next packet | ||||
is transmitted. | is transmitted. | ||||
To cater for round-trip times that are longer than the interval | To cater for round-trip times that are longer than the interval | ||||
between transmissions, further missing packets cause a bell only | between transmissions, further missing packets cause a bell only | ||||
if the maximum number of unreceived packets has increased. | if the maximum number of unreceived packets has increased. | ||||
.It Fl a | .It Fl a | ||||
Audible. | Audible. | ||||
Include a bell | Include a bell | ||||
.Tn ( ASCII | .Tn ( ASCII | ||||
0x07) | 0x07) | ||||
character in the output when any packet is received. | character in the output when any packet is received. | ||||
This option is ignored | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsWas this line simply an error in the old version? asomers: Was this line simply an error in the old version? | |||||
jansucanUnsubmitted Done Inline ActionsYes. More precisely, the bell is included only for a non-flood ping. Should I try to mention this in the manual page? jansucan: Yes. More precisely, the bell is included only for a non-flood ping. Should I try to mention… | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsProbably not necessary. I doubt anybody will be disappointed when they don't hear a bell 1000 times per second when they try to flood ping. asomers: Probably not necessary. I doubt anybody will be disappointed when they don't hear a bell 1000… | |||||
if other format options are present. | |||||
.It Fl c Ar count | .It Fl c Ar count | ||||
Stop after sending | Stop after sending | ||||
(and receiving) | (and receiving) | ||||
.Ar count | .Ar count | ||||
.Tn ECHO_RESPONSE | .Tn ECHO_RESPONSE | ||||
packets. | packets. | ||||
If this option is not specified, | If this option is not specified, | ||||
.Nm | .Nm | ||||
will operate until interrupted. | will operate until interrupted. | ||||
If this option is specified in conjunction with ping sweeps, | .Pp | ||||
For IPv4 target, if this option is specified in conjunction with ping sweeps, | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsNeed another article: "an IPv4 target". asomers: Need another article: "an IPv4 target". | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
each sweep will consist of | each sweep will consist of | ||||
.Ar count | .Ar count | ||||
packets. | packets. | ||||
.It Fl D | .It Fl D | ||||
Set the Don't Fragment bit. | Disable fragmentation. | ||||
.It Fl d | .It Fl d | ||||
Set the | Set the | ||||
.Dv SO_DEBUG | .Dv SO_DEBUG | ||||
option on the socket being used. | option on the socket being used. | ||||
.It Fl f | .It Fl f | ||||
Flood ping. | Flood ping. | ||||
Outputs packets as fast as they come back or one hundred times per second, | Outputs packets as fast as they come back or one hundred times per second, | ||||
whichever is more. | whichever is more. | ||||
For every | For every | ||||
.Tn ECHO_REQUEST | .Tn ECHO_REQUEST | ||||
sent a period | sent a period | ||||
.Dq .\& | .Dq .\& | ||||
is printed, while for every | is printed, while for every | ||||
.Tn ECHO_REPLY | .Tn ECHO_REPLY | ||||
received a backspace is printed. | received a backspace is printed. | ||||
This provides a rapid display of how many packets are being dropped. | This provides a rapid display of how many packets are being dropped. | ||||
Only the super-user may use this option. | Only the super-user may use this option. | ||||
.Bf -emphasis | .Bf -emphasis | ||||
This can be very hard on a network and should be used with caution. | This can be very hard on a network and should be used with caution. | ||||
.Ef | .Ef | ||||
.It Fl G Ar sweepmaxsize | |||||
Specify the maximum size of | |||||
.Tn ICMP | |||||
payload when sending sweeping pings. | |||||
This option is required for ping sweeps. | |||||
.It Fl g Ar sweepminsize | |||||
Specify the size of | |||||
.Tn ICMP | |||||
payload to start with when sending sweeping pings. | |||||
The default value is 0. | |||||
.It Fl H | .It Fl H | ||||
Hostname output. | Hostname output. | ||||
Try to do a reverse DNS lookup when displaying addresses. | Try to do a reverse DNS lookup when displaying addresses. | ||||
This is the opposite of the | This is the opposite of the | ||||
.Fl n | .Fl n , | ||||
asomersAuthorUnsubmitted Not Done Inline ActionsDitch the comma. asomers: Ditch the comma. | |||||
jansucanUnsubmitted Done Inline ActionsDone. jansucan: Done. | |||||
option. | option. | ||||
.It Fl h Ar sweepincrsize | |||||
Specify the number of bytes to increment the size of | |||||
.Tn ICMP | |||||
payload after | |||||
each sweep when sending sweeping pings. | |||||
The default value is 1. | |||||
.It Fl I Ar iface | .It Fl I Ar iface | ||||
Source multicast packets with the given interface address. | For IPv4 target, | ||||
asomersAuthorUnsubmitted Not Done Inline Actions"an IPv4 target" asomers: "an IPv4 target" | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
This flag only applies if the ping destination is a multicast address. | .Ar iface | ||||
is an IP address indentifying an interface from which the packets will | |||||
be sent. This flag applies only if the ping target is a multicast | |||||
address. | |||||
.Pp | |||||
For IPv6 target, | |||||
asomersAuthorUnsubmitted Not Done Inline Actions"an IPv6 target" asomers: "an IPv6 target" | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Ar iface | |||||
is a name of an interface (e.g. `em0') from which the packets will be | |||||
sent. This flag applies if the ping target is a multicast address, or | |||||
link-local/site-local unicast address. | |||||
.It Fl i Ar wait | .It Fl i Ar wait | ||||
Wait | Wait | ||||
.Ar wait | .Ar wait | ||||
seconds | seconds | ||||
.Em between sending each packet . | .Em between sending each packet . | ||||
The default is to wait for one second between each packet. | The default is to wait for one second between each packet. | ||||
The wait time may be fractional, but only the super-user may specify | The wait time may be fractional, but only the super-user may specify | ||||
values less than 1 second. | values less than 1 second. | ||||
This option is incompatible with the | This option is incompatible with the | ||||
.Fl f | .Fl f | ||||
option. | option. | ||||
.It Fl L | |||||
Suppress loopback of multicast packets. | |||||
This flag only applies if the ping destination is a multicast address. | |||||
.It Fl l Ar preload | .It Fl l Ar preload | ||||
If | If | ||||
.Ar preload | .Ar preload | ||||
is specified, | is specified, | ||||
.Nm | .Nm | ||||
sends that many packets as fast as possible before falling into its normal | sends that many packets as fast as possible before falling into its normal | ||||
mode of behavior. | mode of behavior. | ||||
Only the super-user may use this option. | Only the super-user may use this option. | ||||
.It Fl M Cm mask | time | |||||
Use | |||||
.Dv ICMP_MASKREQ | |||||
or | |||||
.Dv ICMP_TSTAMP | |||||
instead of | |||||
.Dv ICMP_ECHO . | |||||
For | |||||
.Cm mask , | |||||
print the netmask of the remote machine. | |||||
Set the | |||||
.Va net.inet.icmp.maskrepl | |||||
MIB variable to enable | |||||
.Dv ICMP_MASKREPLY | |||||
and | |||||
.Va net.inet.icmp.maskfake | |||||
if you want to override the netmask in the response. | |||||
For | |||||
.Cm time , | |||||
print the origination, reception and transmission timestamps. | |||||
Set the | |||||
.Va net.inet.icmp.tstamprepl | |||||
MIB variable to enable or disable | |||||
.Dv ICMP_TSTAMPREPLY . | |||||
.It Fl m Ar ttl | .It Fl m Ar ttl | ||||
Set the IP Time To Live for outgoing packets. | For IPv4 target, set the IP Time To Live for outgoing packets. | ||||
asomersAuthorUnsubmitted Not Done Inline Actions"an IPv4 target" asomers: "an IPv4 target" | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
If not specified, the kernel uses the value of the | If not specified, the kernel uses the value of the | ||||
.Va net.inet.ip.ttl | .Va net.inet.ip.ttl | ||||
MIB variable. | MIB variable. | ||||
.Pp | |||||
For IPv6 target, set the IPv6 hoplimit. | |||||
asomersAuthorUnsubmitted Not Done Inline Actions"an IPv6 target". Is the default hard-coded or defined by the net.inet6.ip6.hlim sysctl? asomers: "an IPv6 target". Is the default hard-coded or defined by the `net.inet6.ip6.hlim` sysctl? | |||||
jansucanUnsubmitted Done Inline ActionsThe article has been added. jansucan: The article has been added. | |||||
jansucanUnsubmitted Done Inline Actions
It's not hard-coded, but there is no explicit getting of net.inet6.ip6.hlim value either. If the -m is not used, ping6 doesn't set hoplimit on the socket and the system probably uses net.inet6.ip6.hlim. I can try to find out if that's really true. jansucan: > Is the default hard-coded or defined by the net.inet6.ip6.hlim sysctl?
It's not hard-coded… | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsDon't worry about it. It isn't ping.8's job to document the kernel. asomers: Don't worry about it. It isn't ping.8's job to document the kernel. | |||||
.It Fl n | .It Fl n | ||||
Numeric output only. | Numeric output only. | ||||
No attempt will be made to lookup symbolic names for host addresses. | No attempt will be made to lookup symbolic names for host addresses. | ||||
This is the opposite of | This is the opposite of | ||||
.Fl H , | .Fl H , | ||||
and it is the default behavior. | and it is the default behavior. | ||||
.It Fl o | .It Fl o | ||||
Exit successfully after receiving one reply packet. | Exit successfully after receiving one reply packet. | ||||
.It Fl P Ar policy | .It Fl P Ar policy | ||||
.Ar policy | .Ar policy | ||||
specifies IPsec policy for the ping session. | specifies IPsec policy for the ping session. | ||||
For details please refer to | For details please refer to | ||||
.Xr ipsec 4 | .Xr ipsec 4 | ||||
and | and | ||||
.Xr ipsec_set_policy 3 . | .Xr ipsec_set_policy 3 . | ||||
.It Fl p Ar pattern | .It Fl p Ar pattern | ||||
You may specify up to 16 | You may specify up to 16 | ||||
.Dq pad | .Dq pad | ||||
bytes to fill out the packet you send. | bytes to fill out the packet you send. | ||||
This is useful for diagnosing data-dependent problems in a network. | This is useful for diagnosing data-dependent problems in a network. | ||||
For example, | For example, | ||||
.Dq Li \-p ff | .Dq Li \-p ff | ||||
will cause the sent packet to be filled with all | will cause the sent packet to be filled with all | ||||
ones. | ones. | ||||
.It Fl q | |||||
Quiet output. | |||||
Nothing is displayed except the summary lines at startup time and | |||||
when finished. | |||||
.It Fl S Ar src_addr | |||||
Use the following IP address as the source address in outgoing packets. | |||||
On hosts with more than one IP address, this option can be used to | |||||
force the source address to be something other than the IP address | |||||
of the interface the probe packet is sent on. | |||||
.Pp | |||||
For IPv4, if the IP address is not one of this machine's interface | |||||
addresses, an error is returned and nothing is sent. | |||||
.Pp | |||||
For IPv6, the source address must be one of the unicast addresses of | |||||
the sending node, and must be numeric. | |||||
.It Fl s Ar packetsize | |||||
Specify the number of data bytes to be sent. | |||||
The default is 56, which translates into 64 | |||||
.Tn ICMP | |||||
data bytes when combined | |||||
with the 8 bytes of | |||||
.Tn ICMP | |||||
header data. | |||||
.Pp | |||||
For IPv4, only the super-user may specify values more than default. | |||||
This option cannot be used with ping sweeps. | |||||
.Pp | |||||
For IPv6, you may need to specify | |||||
.Fl b | |||||
as well to extend socket buffer size. | |||||
.It Fl t Ar timeout | |||||
Specify a timeout, in seconds, before ping exits regardless of how | |||||
many packets have been received. | |||||
.It Fl v | |||||
Verbose output. | |||||
.Tn ICMP | |||||
packets other than | |||||
.Tn ECHO_RESPONSE | |||||
that are received are listed. | |||||
.It Fl W Ar waittime | |||||
Time in milliseconds to wait for a reply for each packet sent. | |||||
If a reply arrives later, the packet is not printed as replied, but | |||||
considered as replied when calculating statistics. | |||||
.El | |||||
.Ss Options only for IPv4 target | |||||
asomersAuthorUnsubmitted Not Done Inline Actionss/target/targets/ asomers: s/target/targets/ | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Bl -tag -width indent | |||||
.It Fl 4 | |||||
Use IPv4 in case that the target is is resolved to both IPv4 and IPv6. | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsI would simply say "Use IPv4 regardless of how the target is resolved" asomers: I would simply say "Use IPv4 regardless of how the target is resolved" | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.It Fl G Ar sweepmaxsize | |||||
Specify the maximum size of | |||||
.Tn ICMP | |||||
payload when sending sweeping pings. | |||||
This option is required for ping sweeps. | |||||
.It Fl g Ar sweepminsize | |||||
Specify the size of | |||||
.Tn ICMP | |||||
payload to start with when sending sweeping pings. | |||||
The default value is 0. | |||||
.It Fl h Ar sweepincrsize | |||||
Specify the number of bytes to increment the size of | |||||
.Tn ICMP | |||||
payload after | |||||
each sweep when sending sweeping pings. | |||||
The default value is 1. | |||||
.It Fl L | |||||
Suppress loopback of multicast packets. | |||||
This flag only applies if the ping destination is a multicast address. | |||||
.It Fl M Cm mask | time | |||||
Use | |||||
.Dv ICMP_MASKREQ | |||||
or | |||||
.Dv ICMP_TSTAMP | |||||
instead of | |||||
.Dv ICMP_ECHO . | |||||
For | |||||
.Cm mask , | |||||
print the netmask of the remote machine. | |||||
Set the | |||||
.Va net.inet.icmp.maskrepl | |||||
MIB variable to enable | |||||
.Dv ICMP_MASKREPLY | |||||
and | |||||
.Va net.inet.icmp.maskfake | |||||
if you want to override the netmask in the response. | |||||
For | |||||
.Cm time , | |||||
print the origination, reception and transmission timestamps. | |||||
Set the | |||||
.Va net.inet.icmp.tstamprepl | |||||
MIB variable to enable or disable | |||||
.Dv ICMP_TSTAMPREPLY . | |||||
.It Fl Q | .It Fl Q | ||||
Somewhat quiet output. | Somewhat quiet output. | ||||
.No Don Ap t | .No Don Ap t | ||||
display ICMP error messages that are in response to our query messages. | display ICMP error messages that are in response to our query messages. | ||||
Originally, the | Originally, the | ||||
.Fl v | .Fl v | ||||
flag was required to display such errors, but | flag was required to display such errors, but | ||||
.Fl v | .Fl v | ||||
displays all ICMP error messages. | displays all ICMP error messages. | ||||
On a busy machine, this output can be overbearing. | On a busy machine, this output can be overbearing. | ||||
Without the | Without the | ||||
.Fl Q | .Fl Q | ||||
flag, | flag, | ||||
.Nm | .Nm | ||||
prints out any ICMP error messages caused by its own ECHO_REQUEST | prints out any ICMP error messages caused by its own ECHO_REQUEST | ||||
messages. | messages. | ||||
.It Fl q | |||||
Quiet output. | |||||
Nothing is displayed except the summary lines at startup time and | |||||
when finished. | |||||
.It Fl R | .It Fl R | ||||
Record route. | Record route. | ||||
Includes the | Includes the | ||||
.Tn RECORD_ROUTE | .Tn RECORD_ROUTE | ||||
option in the | option in the | ||||
.Tn ECHO_REQUEST | .Tn ECHO_REQUEST | ||||
packet and displays | packet and displays | ||||
the route buffer on returned packets. | the route buffer on returned packets. | ||||
Show All 11 Lines | |||||
.It Fl r | .It Fl r | ||||
Bypass the normal routing tables and send directly to a host on an attached | Bypass the normal routing tables and send directly to a host on an attached | ||||
network. | network. | ||||
If the host is not on a directly-attached network, an error is returned. | If the host is not on a directly-attached network, an error is returned. | ||||
This option can be used to ping a local host through an interface | This option can be used to ping a local host through an interface | ||||
that has no route through it | that has no route through it | ||||
(e.g., after the interface was dropped by | (e.g., after the interface was dropped by | ||||
.Xr routed 8 ) . | .Xr routed 8 ) . | ||||
.It Fl S Ar src_addr | |||||
Use the following IP address as the source address in outgoing packets. | |||||
On hosts with more than one IP address, this option can be used to | |||||
force the source address to be something other than the IP address | |||||
of the interface the probe packet is sent on. | |||||
If the IP address | |||||
is not one of this machine's interface addresses, an error is | |||||
returned and nothing is sent. | |||||
.It Fl s Ar packetsize | |||||
Specify the number of data bytes to be sent. | |||||
The default is 56, which translates into 64 | |||||
.Tn ICMP | |||||
data bytes when combined | |||||
with the 8 bytes of | |||||
.Tn ICMP | |||||
header data. | |||||
Only the super-user may specify values more than default. | |||||
This option cannot be used with ping sweeps. | |||||
.It Fl T Ar ttl | .It Fl T Ar ttl | ||||
Set the IP Time To Live for multicasted packets. | Set the IP Time To Live for multicasted packets. | ||||
This flag only applies if the ping destination is a multicast address. | This flag only applies if the ping destination is a multicast address. | ||||
.It Fl t Ar timeout | |||||
Specify a timeout, in seconds, before ping exits regardless of how | |||||
many packets have been received. | |||||
.It Fl v | |||||
Verbose output. | |||||
.Tn ICMP | |||||
packets other than | |||||
.Tn ECHO_RESPONSE | |||||
that are received are listed. | |||||
.It Fl W Ar waittime | |||||
Time in milliseconds to wait for a reply for each packet sent. | |||||
If a reply arrives later, the packet is not printed as replied, but | |||||
considered as replied when calculating statistics. | |||||
.It Fl z Ar tos | .It Fl z Ar tos | ||||
Use the specified type of service. | Use the specified type of service. | ||||
.It Ar IPv4-host | |||||
IPv4 address of the final destination node. | |||||
asomersAuthorUnsubmitted Not Done Inline Actions"hostname or IPv4 address" asomers: "hostname or IPv4 address" | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.It Ar IPv4-mcast-group | |||||
IPv4 multicast address of the final destination nodes. | |||||
.El | .El | ||||
.Ss Options only for IPv6 target | |||||
asomersAuthorUnsubmitted Not Done Inline Actionss/target/targets/ asomers: s/target/targets/ | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Bl -tag -width indent | |||||
.It Fl 6 | |||||
Use IPv6 in case that the target is is resolved to both IPv4 and IPv6. | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsAs above, I would say "Use IPv6 regardless of how the target is resolved" asomers: As above, I would say "Use IPv6 regardless of how the target is resolved" | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.It Fl b Ar bufsiz | |||||
Set socket buffer size. | |||||
.It Fl e Ar gateway | |||||
Specifies to use | |||||
.Ar gateway | |||||
as the next hop to the destination. | |||||
The gateway must be a neighbor of the sending node. | |||||
.It Fl k Ar addrtype | |||||
Generate ICMPv6 Node Information Node Addresses query, rather than echo-request. | |||||
.Ar addrtype | |||||
must be a string constructed of the following characters. | |||||
.Bl -tag -width Ds -compact | |||||
.It Ic a | |||||
requests unicast addresses from all of the responder's interfaces. | |||||
If the character is omitted, | |||||
only those addresses which belong to the interface which has the | |||||
responder's address are requests. | |||||
.It Ic c | |||||
requests responder's IPv4-compatible and IPv4-mapped addresses. | |||||
.It Ic g | |||||
requests responder's global-scope addresses. | |||||
.It Ic s | |||||
requests responder's site-local addresses. | |||||
.It Ic l | |||||
requests responder's link-local addresses. | |||||
.It Ic A | |||||
requests responder's anycast addresses. | |||||
Without this character, the responder will return unicast addresses only. | |||||
With this character, the responder will return anycast addresses only. | |||||
Note that the specification does not specify how to get responder's | |||||
anycast addresses. | |||||
This is an experimental option. | |||||
.El | |||||
.It Fl N | |||||
Probe node information multicast group address | |||||
.Pq Li ff02::2:ffxx:xxxx . | |||||
.Ar host | |||||
must be string hostname of the target | |||||
(must not be a numeric IPv6 address). | |||||
Node information multicast group will be computed based on given | |||||
.Ar host , | |||||
and will be used as the final destination. | |||||
Since node information multicast group is a link-local multicast group, | |||||
outgoing interface needs to be specified by | |||||
.Fl I | |||||
option. | |||||
.Pp | .Pp | ||||
When specified twice, the address | |||||
.Pq Li ff02::2:xxxx:xxxx | |||||
is used instead. | |||||
The former is in RFC 4620, the latter is in an old Internet Draft | |||||
draft-ietf-ipngwg-icmp-name-lookup. | |||||
Note that KAME-derived implementations including | |||||
.Fx | |||||
use the latter. | |||||
.It Fl O | |||||
Generate ICMPv6 Node Information supported query types query, | |||||
rather than echo-request. | |||||
.Fl s | |||||
has no effect if | |||||
.Fl O | |||||
is specified. | |||||
.It Fl u | |||||
By default, | |||||
.Nm | |||||
asks the kernel to fragment packets to fit into the minimum IPv6 MTU. | |||||
The | |||||
.Fl u | |||||
option | |||||
will suppress the behavior in the following two levels: | |||||
when the option is specified once, the behavior will be disabled for | |||||
unicast packets. | |||||
When the option is more than once, it will be disabled for both | |||||
unicast and multicast packets. | |||||
.It Fl y | |||||
Generate ICMPv6 Node Information DNS Name query, rather than echo-request. | |||||
.Fl s | |||||
has no effect if | |||||
.Fl y | |||||
is specified. | |||||
.It Fl Y | |||||
Same as | |||||
.Fl y , | |||||
but with old packet format based on 03 draft. | |||||
This option is present for backward compatibility. | |||||
.Fl s | |||||
has no effect if | |||||
.Fl y | |||||
is specified. | |||||
.It Ar IPv6-hops | |||||
IPv6 addresses for intermediate nodes, | |||||
which will be put into type 0 routing header. | |||||
.It Ar IPv6-host | |||||
IPv6 address of the final destination node. | |||||
.El | |||||
.Ss Experimental options only for IPv6 target | |||||
.Bl -tag -width indent | |||||
.It Fl E | |||||
Enables transport-mode IPsec encapsulated security payload. | |||||
.It Fl Z | |||||
Enables transport-mode IPsec authentication header. | |||||
.El | |||||
.Pp | |||||
When using | When using | ||||
.Nm | .Nm | ||||
for fault isolation, it should first be run on the local host, to verify | for fault isolation, it should first be run on the local host, to verify | ||||
that the local network interface is up and running. | that the local network interface is up and running. | ||||
Then, hosts and gateways further and further away should be | Then, hosts and gateways further and further away should be | ||||
.Dq pinged . | .Dq pinged . | ||||
Round-trip times and packet loss statistics are computed. | Round-trip times and packet loss statistics are computed. | ||||
If duplicate packets are received, they are not included in the packet | If duplicate packets are received, they are not included in the packet | ||||
Show All 11 Lines | |||||
.Nm | .Nm | ||||
receives a | receives a | ||||
.Dv SIGINFO | .Dv SIGINFO | ||||
(see the | (see the | ||||
.Cm status | .Cm status | ||||
argument for | argument for | ||||
.Xr stty 1 ) | .Xr stty 1 ) | ||||
signal, the current number of packets sent and received, and the | signal, the current number of packets sent and received, and the | ||||
minimum, mean, and maximum of the round-trip times will be written to | minimum, mean, maximum, and standard deviation of the round-trip times | ||||
the standard error output. | will be written to the standard output. | ||||
.Pp | .Pp | ||||
This program is intended for use in network testing, measurement and | This program is intended for use in network testing, measurement and | ||||
management. | management. | ||||
Because of the load it can impose on the network, it is unwise to use | Because of the load it can impose on the network, it is unwise to use | ||||
.Nm | .Nm | ||||
during normal operations or from automated scripts. | during normal operations or from automated scripts. | ||||
.Sh ICMP PACKET DETAILS | .Sh ICMP PACKET DETAILS | ||||
An IP header without options is 20 bytes. | An IP header without options is 20 bytes. | ||||
▲ Show 20 Lines • Show All 64 Lines • ▼ Show 20 Lines | |||||
cannot | cannot | ||||
be sent across your network or that takes much longer to transfer than | be sent across your network or that takes much longer to transfer than | ||||
other similar length files. | other similar length files. | ||||
You can then examine this file for repeated patterns that you can test | You can then examine this file for repeated patterns that you can test | ||||
using the | using the | ||||
.Fl p | .Fl p | ||||
option of | option of | ||||
.Nm . | .Nm . | ||||
.Sh TTL DETAILS | .Sh IPv4 TTL DETAILS | ||||
The | The | ||||
.Tn TTL | .Tn TTL | ||||
value of an IP packet represents the maximum number of IP routers | value of an IP packet represents the maximum number of IP routers | ||||
that the packet can go through before being thrown away. | that the packet can go through before being thrown away. | ||||
In current practice you can expect each router in the Internet to decrement | In current practice you can expect each router in the Internet to decrement | ||||
the | the | ||||
.Tn TTL | .Tn TTL | ||||
field by exactly one. | field by exactly one. | ||||
▲ Show 20 Lines • Show All 73 Lines • ▼ Show 20 Lines | |||||
.Bl -tag -width indent | .Bl -tag -width indent | ||||
.It 0 | .It 0 | ||||
At least one response was heard from the specified | At least one response was heard from the specified | ||||
.Ar host . | .Ar host . | ||||
.It 2 | .It 2 | ||||
The transmission was successful but no responses were received. | The transmission was successful but no responses were received. | ||||
.It any other value | .It any other value | ||||
An error occurred. | An error occurred. | ||||
These values are defined in | |||||
.In sysexits.h . | |||||
.El | .El | ||||
.Sh EXAMPLES | |||||
The following will send ICMPv6 echo request to | |||||
.Li dst.foo.com . | |||||
.Bd -literal -offset indent | |||||
ping -6 -n dst.foo.com | |||||
.Ed | |||||
.Pp | |||||
The following will probe hostnames for all nodes on the network link attached to | |||||
.Li wi0 | |||||
interface. | |||||
The address | |||||
.Li ff02::1 | |||||
is named the link-local all-node multicast address, and the packet would | |||||
reach every node on the network link. | |||||
.Bd -literal -offset indent | |||||
ping -6 -y ff02::1%wi0 | |||||
.Ed | |||||
.Pp | |||||
The following will probe addresses assigned to the destination node, | |||||
.Li dst.foo.com . | |||||
.Bd -literal -offset indent | |||||
ping -6 -k agl dst.foo.com | |||||
.Ed | |||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||
.Xr netstat 1 , | .Xr netstat 1 , | ||||
.Xr icmp 4 , | .Xr icmp 4 , | ||||
.Xr icmp6 4 , | |||||
.Xr inet6 4 , | |||||
.Xr ip6 4 , | |||||
.Xr ifconfig 8 , | .Xr ifconfig 8 , | ||||
.Xr routed 8 , | .Xr routed 8 , | ||||
.Xr traceroute 8 | .Xr traceroute 8 | ||||
.Xr traceroute6 8 | |||||
.Rs | |||||
.%A A. Conta | |||||
.%A S. Deering | |||||
.%T "Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification" | |||||
.%N RFC 2463 | |||||
.%D December 1998 | |||||
.Re | |||||
.Rs | |||||
.%A Matt Crawford | |||||
.%T "IPv6 Node Information Queries" | |||||
.%N draft-ietf-ipngwg-icmp-name-lookups-09.txt | |||||
.%D May 2002 | |||||
.%O work in progress material | |||||
.Re | |||||
.Sh HISTORY | .Sh HISTORY | ||||
The | The | ||||
.Nm | .Nm | ||||
utility appeared in | utility appeared in | ||||
.Bx 4.3 . | .Bx 4.3 . | ||||
The | |||||
.Nm ping6 | |||||
utility with IPv6 support first appeared in the WIDE Hydrangea IPv6 | |||||
protocol stack kit. It was merged to | |||||
asomersAuthorUnsubmitted Not Done Inline ActionsLet's keep things in chronological order. Can you move the GSoC 2019 sentence to below "FreeBSD 4.0"? asomers: Let's keep things in chronological order. Can you move the GSoC 2019 sentence to below… | |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Nm | |||||
in Google Summer of Code 2019. | |||||
.Pp | |||||
IPv6 and IPsec support based on the KAME Project | |||||
.Pq Pa http://www.kame.net/ | |||||
stack was initially integrated into | |||||
.Fx 4.0 . | |||||
.Sh AUTHORS | .Sh AUTHORS | ||||
The original | The original | ||||
.Nm | .Nm | ||||
utility was written by | utility was written by | ||||
.An Mike Muuss | .An Mike Muuss | ||||
while at the US Army Ballistics | while at the US Army Ballistics | ||||
Research Laboratory. | Research Laboratory. | ||||
.Sh BUGS | .Sh BUGS | ||||
Many Hosts and Gateways ignore the | Many Hosts and Gateways ignore the | ||||
asomersAuthorUnsubmitted Not Done Inline ActionsI would say "ignore the IPv4 RECORD_ROUTE option" asomers: I would say "ignore the IPv4 RECORD_ROUTE option"
| |||||
jansucanUnsubmitted Done Inline ActionsFixed. jansucan: Fixed. | |||||
.Tn RECORD_ROUTE | .Tn RECORD_ROUTE | ||||
option. | option in IPv4. | ||||
.Pp | .Pp | ||||
The maximum IP header length is too small for options like | The maximum IP header length is too small for options like | ||||
.Tn RECORD_ROUTE | .Tn RECORD_ROUTE | ||||
to be completely useful. | to be completely useful. | ||||
.No There Ap s | .No There Ap s | ||||
not much that can be done about this, however. | not much that can be done about this, however. | ||||
.Pp | .Pp | ||||
Flood pinging is not recommended in general, and flood pinging the | Flood pinging is not recommended in general, and flood pinging the | ||||
broadcast address should only be done under very controlled conditions. | broadcast address should only be done under very controlled conditions. | ||||
.Pp | .Pp | ||||
The | The | ||||
.Fl v | .Fl v | ||||
option is not worth much on busy hosts. | option is not worth much on busy hosts. |
It's dumb to call this argument iface when it must be an address. What's the difference between -I and -S anyway?