Blame doc/ping.xml

Packit Service 6f2e62
Packit Service 6f2e62
Packit Service 6f2e62
                   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
Packit Service 6f2e62
Packit Service 6f2e62
<refentry id='ping8'>
Packit Service 6f2e62
<refmeta>
Packit Service 6f2e62
  <refentrytitle>PING</refentrytitle>
Packit Service 6f2e62
  <manvolnum>8</manvolnum>
Packit Service 6f2e62
  <refmiscinfo class='manual'>iputils</refmiscinfo>
Packit Service 6f2e62
</refmeta>
Packit Service 6f2e62
<refnamediv>
Packit Service 6f2e62
  <refname>ping</refname>
Packit Service 6f2e62
  <refpurpose>send ICMP ECHO_REQUEST to network hosts</refpurpose>
Packit Service 6f2e62
</refnamediv>
Packit Service 6f2e62
Packit Service 6f2e62
<refsynopsisdiv id='synopsis'>
Packit Service 6f2e62
  <cmdsynopsis>
Packit Service 6f2e62
    <command>ping</command>
Packit Service 6f2e62
    <arg choice='opt'>-aAbBdDfhLnOqrRUvV46 </arg>
Packit Service 6f2e62
    <arg choice='opt'>-c <replaceable>count</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-F <replaceable>flowlabel</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-i <replaceable>interval</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-I <replaceable>interface</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-l <replaceable>preload</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-m <replaceable>mark</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-M <replaceable>pmtudisc_option</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-N <replaceable>nodeinfo_option</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-w <replaceable>deadline</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-W <replaceable>timeout</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-p <replaceable>pattern</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-Q <replaceable>tos</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-s <replaceable>packetsize</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-S <replaceable>sndbuf</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'>-t <replaceable>ttl</replaceable></arg>
Packit Service 6f2e62
    <arg choice='opt'><arg choice='plain'>-T <replaceable>timestamp</replaceable></arg><arg choice='plain'><replaceable>option</replaceable></arg></arg>
Packit Service 6f2e62
    <arg choice='opt' rep='repeat'><replaceable>hop</replaceable></arg>
Packit Service 6f2e62
    <arg choice='plain'><replaceable>destination</replaceable></arg>
Packit Service 6f2e62
    <sbr/>
Packit Service 6f2e62
  </cmdsynopsis>
Packit Service 6f2e62
</refsynopsisdiv>
Packit Service 6f2e62
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='description'>
Packit Service 6f2e62
  <title>DESCRIPTION</title>
Packit Service 6f2e62
  <para><command>ping</command> uses the ICMP protocol's mandatory ECHO_REQUEST
Packit Service 6f2e62
datagram to elicit an ICMP ECHO_RESPONSE from a host or gateway.
Packit Service 6f2e62
ECHO_REQUEST datagrams (“pings”) have an IP and ICMP
Packit Service 6f2e62
header, followed by a struct timeval and then an arbitrary
Packit Service 6f2e62
number of “pad” bytes used to fill out the packet.</para>
Packit Service 6f2e62
Packit Service 6f2e62
  <para><command>ping</command> works with both IPv4 and IPv6. Using only one of them
Packit Service 6f2e62
explicitly can be enforced by specifying <option>-4</option> or <option>-6</option>.</para>
Packit Service 6f2e62
Packit Service 6f2e62
  <para><command>ping</command> can also send IPv6 Node Information Queries (RFC4620).
Packit Service 6f2e62
Intermediate <emphasis remap='I'>hop</emphasis>s may not be allowed, because IPv6 source routing was deprecated (RFC5095).</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='options'>
Packit Service 6f2e62
  <title>OPTIONS</title>
Packit Service 6f2e62
<variablelist remap='TP'>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-4</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Use IPv4 only.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-6</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Use IPv6 only.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-a</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Audible ping.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-A</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Adaptive ping. Interpacket interval adapts to round-trip time, so that
Packit Service 6f2e62
effectively not more than one (or more, if preload is set) unanswered probe
Packit Service 6f2e62
is present in the network. Minimal interval is 200msec for not super-user.
Packit Service 6f2e62
On networks with low rtt this mode is essentially equivalent to flood mode.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-b</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Allow pinging a broadcast address.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-B</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Do not allow <command>ping</command> to change source address of probes.
Packit Service 6f2e62
The address is bound to one selected when <command>ping</command> starts.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-c </option><emphasis remap='I'>count</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Stop after sending <emphasis remap='I'>count</emphasis> ECHO_REQUEST
Packit Service 6f2e62
packets. With <emphasis remap='I'>deadline</emphasis> option, <command>ping</command> waits for
Packit Service 6f2e62
<emphasis remap='I'>count</emphasis> ECHO_REPLY packets, until the timeout expires.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-d</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Set the SO_DEBUG option on the socket being used.
Packit Service 6f2e62
Essentially, this socket option is not used by Linux kernel.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-D</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Print timestamp (unix time + microseconds as in gettimeofday) before
Packit Service 6f2e62
each line.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-f</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Flood ping. For every ECHO_REQUEST sent a period “.” is printed,
Packit Service 6f2e62
while for ever ECHO_REPLY received a backspace is printed.
Packit Service 6f2e62
This provides a rapid display of how many packets are being dropped.
Packit Service 6f2e62
If interval is not given, it sets interval to zero and
Packit Service 6f2e62
outputs packets as fast as they come back or one hundred times per second,
Packit Service 6f2e62
whichever is more.
Packit Service 6f2e62
Only the super-user may use this option with zero interval.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-F </option><emphasis remap='I'>flow label</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>IPv6 only.
Packit Service 6f2e62
Allocate and set 20 bit flow label (in hex) on echo request packets.
Packit Service 6f2e62
If value is zero, kernel allocates random flow label.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-h</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Show help.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-i </option><emphasis remap='I'>interval</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Wait <emphasis remap='I'>interval</emphasis> seconds between sending each packet.
Packit Service 6f2e62
The default is to wait for one second between each packet normally,
Packit Service 6f2e62
or not to wait in flood mode. Only super-user may set interval
Packit Service 6f2e62
to values less than 0.2 seconds.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-I </option><emphasis remap='I'>interface</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para><emphasis remap='I'>interface</emphasis> is either an address, or an interface name.
Packit Service 6f2e62
If <emphasis remap='I'>interface</emphasis> is an address, it sets source address
Packit Service 6f2e62
to specified interface address.
Packit Service 6f2e62
If <emphasis remap='I'>interface</emphasis> in an interface name, it sets
Packit Service 6f2e62
source interface to specified interface.
Packit Service 6f2e62
NOTE: For IPv6, when doing ping to a link-local scope
Packit Service 6f2e62
address, link specification (by the '%'-notation in
Packit Service 6f2e62
<emphasis remap='I'>destination</emphasis>, or by this option)
Packit Service 6f2e62
can be used but it is no longer required.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-l </option><emphasis remap='I'>preload</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>If <emphasis remap='I'>preload</emphasis> is specified,
Packit Service 6f2e62
<command>ping</command> sends that many packets not waiting for reply.
Packit Service 6f2e62
Only the super-user may select preload more than 3.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-L</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Suppress loopback of multicast packets.  This flag only applies if the ping
Packit Service 6f2e62
destination is a multicast address.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-m </option><emphasis remap='I'>mark</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>use <emphasis remap='I'>mark</emphasis> to tag the packets going out. This is useful
Packit Service 6f2e62
for variety of reasons within the kernel such as using policy
Packit Service 6f2e62
routing to select specific outbound processing.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-M </option><emphasis remap='I'>pmtudisc_opt</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Select Path MTU Discovery strategy.
Packit Service 6f2e62
<emphasis remap='I'>pmtudisc_option</emphasis> may be either <emphasis remap='I'>do</emphasis>
Packit Service 6f2e62
(prohibit fragmentation, even local one),
Packit Service 6f2e62
<emphasis remap='I'>want</emphasis> (do PMTU discovery, fragment locally when packet size
Packit Service 6f2e62
is large), or <emphasis remap='I'>dont</emphasis> (do not set DF flag).</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-N </option><emphasis remap='I'>nodeinfo_option</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>IPv6 only.
Packit Service 6f2e62
Send ICMPv6 Node Information Queries (RFC4620), instead of Echo Request.
Packit Service 6f2e62
CAP_NET_RAW capability is required.</para>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>help</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>Show help for NI support.</para>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>name</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>Queries for Node Names.</para>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>ipv6</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>Queries for IPv6 Addresses. There are several IPv6 specific flags.</para>
Packit Service 6f2e62
        <variablelist remap='TP'>
Packit Service 6f2e62
          <varlistentry>
Packit Service 6f2e62
          <term><emphasis remap='B'>ipv6-global</emphasis></term>
Packit Service 6f2e62
          <listitem>
Packit Service 6f2e62
<para>Request IPv6 global-scope addresses.</para>
Packit Service 6f2e62
          </listitem>
Packit Service 6f2e62
          </varlistentry>
Packit Service 6f2e62
        </variablelist>
Packit Service 6f2e62
        <variablelist remap='TP'>
Packit Service 6f2e62
          <varlistentry>
Packit Service 6f2e62
          <term><emphasis remap='B'>ipv6-sitelocal</emphasis></term>
Packit Service 6f2e62
          <listitem>
Packit Service 6f2e62
<para>Request IPv6 site-local addresses.</para>
Packit Service 6f2e62
          </listitem>
Packit Service 6f2e62
          </varlistentry>
Packit Service 6f2e62
        </variablelist>
Packit Service 6f2e62
        <variablelist remap='TP'>
Packit Service 6f2e62
          <varlistentry>
Packit Service 6f2e62
          <term><emphasis remap='B'>ipv6-linklocal</emphasis></term>
Packit Service 6f2e62
          <listitem>
Packit Service 6f2e62
<para>Request IPv6 link-local addresses.</para>
Packit Service 6f2e62
          </listitem>
Packit Service 6f2e62
          </varlistentry>
Packit Service 6f2e62
        </variablelist>
Packit Service 6f2e62
        <variablelist remap='TP'>
Packit Service 6f2e62
          <varlistentry>
Packit Service 6f2e62
          <term><emphasis remap='B'>ipv6-all</emphasis></term>
Packit Service 6f2e62
          <listitem>
Packit Service 6f2e62
<para>Request IPv6 addresses on other interfaces.</para>
Packit Service 6f2e62
          </listitem>
Packit Service 6f2e62
          </varlistentry>
Packit Service 6f2e62
        </variablelist>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>ipv4</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>Queries for IPv4 Addresses.  There is one IPv4 specific flag.</para>
Packit Service 6f2e62
        <variablelist remap='TP'>
Packit Service 6f2e62
          <varlistentry>
Packit Service 6f2e62
          <term><emphasis remap='B'>ipv4-all</emphasis></term>
Packit Service 6f2e62
          <listitem>
Packit Service 6f2e62
<para>Request IPv4 addresses on other interfaces.</para>
Packit Service 6f2e62
          </listitem>
Packit Service 6f2e62
          </varlistentry>
Packit Service 6f2e62
        </variablelist>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>subject-ipv6=</emphasis><emphasis remap='I'>ipv6addr</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>IPv6 subject address.</para>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>subject-ipv4=</emphasis><emphasis remap='I'>ipv4addr</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>IPv4 subject address.</para>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>subject-name=</emphasis><emphasis remap='I'>nodename</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>Subject name.  If it contains more than one dot,
Packit Service 6f2e62
fully-qualified domain name is assumed.</para>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
    <variablelist remap='TP'>
Packit Service 6f2e62
      <varlistentry>
Packit Service 6f2e62
      <term><emphasis remap='B'>subject-fqdn=</emphasis><emphasis remap='I'>nodename</emphasis></term>
Packit Service 6f2e62
      <listitem>
Packit Service 6f2e62
<para>Subject name.  Fully-qualified domain name is
Packit Service 6f2e62
always assumed.</para>
Packit Service 6f2e62
      </listitem>
Packit Service 6f2e62
      </varlistentry>
Packit Service 6f2e62
    </variablelist>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-n</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Numeric output only.
Packit Service 6f2e62
No attempt will be made to lookup symbolic names for host addresses.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-O</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Report outstanding ICMP ECHO reply before sending next packet.
Packit Service 6f2e62
This is useful together with the timestamp <option>-D</option> to
Packit Service 6f2e62
log output to a diagnostic file and search for missing answers.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-p </option><emphasis remap='I'>pattern</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>You may specify up to 16 “pad” bytes to fill out the packet you send.
Packit Service 6f2e62
This is useful for diagnosing data-dependent problems in a network.
Packit Service 6f2e62
For example, <option>-p ff</option> will cause the sent packet
Packit Service 6f2e62
to be filled with all ones.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-q</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Quiet output.
Packit Service 6f2e62
Nothing is displayed except the summary lines at startup time and
Packit Service 6f2e62
when finished.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-Q </option><emphasis remap='I'>tos</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Set Quality of Service -related bits in ICMP datagrams.
Packit Service 6f2e62
<emphasis remap='I'>tos</emphasis> can be decimal (<command>ping</command> only) or hex number.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>In RFC2474, these fields are interpreted as 8-bit Differentiated
Packit Service 6f2e62
Services (DS), consisting of: bits 0-1 (2 lowest bits) of separate
Packit Service 6f2e62
data, and bits 2-7 (highest 6 bits) of Differentiated Services
Packit Service 6f2e62
Codepoint (DSCP).  In RFC2481 and RFC3168, bits 0-1 are used for ECN.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>Historically (RFC1349, obsoleted by RFC2474), these were interpreted
Packit Service 6f2e62
as: bit 0 (lowest bit) for reserved (currently being redefined as
Packit Service 6f2e62
congestion control), 1-4 for Type of Service and bits 5-7
Packit Service 6f2e62
(highest bits) for Precedence.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-r</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Bypass the normal routing tables and send directly to a host on an attached
Packit Service 6f2e62
interface.
Packit Service 6f2e62
If the host is not on a directly-attached network, an error is returned.
Packit Service 6f2e62
This option can be used to ping a local host through an interface
Packit Service 6f2e62
that has no route through it provided the option <option>-I</option> is also
Packit Service 6f2e62
used.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-R</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para><command>ping</command> only.
Packit Service 6f2e62
Record route.
Packit Service 6f2e62
Includes the RECORD_ROUTE option in the ECHO_REQUEST
Packit Service 6f2e62
packet and displays the route buffer on returned packets.
Packit Service 6f2e62
Note that the IP header is only large enough for nine such routes.
Packit Service 6f2e62
Many hosts ignore or discard this option.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-s </option><emphasis remap='I'>packetsize</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Specifies the number of data bytes to be sent.
Packit Service 6f2e62
The default is 56, which translates into 64 ICMP
Packit Service 6f2e62
data bytes when combined with the 8 bytes of ICMP header data.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-S </option><emphasis remap='I'>sndbuf</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Set socket sndbuf. If not specified, it is selected to buffer
Packit Service 6f2e62
not more than one packet.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-t </option><emphasis remap='I'>ttl</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para><command>ping</command> only.
Packit Service 6f2e62
Set the IP Time to Live.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-T </option><emphasis remap='I'>timestamp option</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Set special IP timestamp options.
Packit Service 6f2e62
<emphasis remap='I'>timestamp option</emphasis> may be either
Packit Service 6f2e62
<emphasis remap='I'>tsonly</emphasis> (only timestamps),
Packit Service 6f2e62
<emphasis remap='I'>tsandaddr</emphasis> (timestamps and addresses) or
Packit Service 6f2e62
<emphasis remap='I'>tsprespec host1 [host2 [host3 [host4]]]</emphasis>
Packit Service 6f2e62
(timestamp prespecified hops).</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-U</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Print full user-to-user latency (the old behaviour). Normally
Packit Service 6f2e62
<command>ping</command>
Packit Service 6f2e62
prints network round trip time, which can be different
Packit Service 6f2e62
f.e. due to DNS failures.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-v</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Verbose output.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-V</option></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Show version and exit.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-w </option><emphasis remap='I'>deadline</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Specify a timeout, in seconds, before
Packit Service 6f2e62
<command>ping</command>
Packit Service 6f2e62
exits regardless of how many
Packit Service 6f2e62
packets have been sent or received. In this case
Packit Service 6f2e62
<command>ping</command>
Packit Service 6f2e62
does not stop after
Packit Service 6f2e62
<emphasis remap='I'>count</emphasis>
Packit Service 6f2e62
packet are sent, it waits either for
Packit Service 6f2e62
<emphasis remap='I'>deadline</emphasis>
Packit Service 6f2e62
expire or until
Packit Service 6f2e62
<emphasis remap='I'>count</emphasis>
Packit Service 6f2e62
probes are answered or for some error notification from network.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <term><option>-W </option><emphasis remap='I'>timeout</emphasis></term>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>Time to wait for a response, in seconds. The option affects only timeout
Packit Service 6f2e62
in absence of any responses, otherwise <command>ping</command> waits for two RTTs.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
</variablelist>
Packit Service 6f2e62
<para>When using <command>ping</command> for fault isolation, it should first be run
Packit Service 6f2e62
on the local host, to verify that the local network interface is up
Packit Service 6f2e62
and running. Then, hosts and gateways further and further away should be
Packit Service 6f2e62
“pinged”. Round-trip times and packet loss statistics are computed.
Packit Service 6f2e62
If duplicate packets are received, they are not included in the packet
Packit Service 6f2e62
loss calculation, although the round trip time of these packets is used
Packit Service 6f2e62
in calculating the minimum/average/maximum/mdev round-trip time numbers.
Packit Service 6f2e62
</para>
Packit Service 6f2e62
<para>
Packit Service 6f2e62
Median deviation (mdev), essentially an average of how far each ping RTT is from the mean RTT. The higher mdev is, the more variable the RTT is (over time).
Packit Service 6f2e62
Packit Service 6f2e62
With a high RTT variability, you will have speed issues with bulk transfers (they will take longer than is strictly speaking necessary, as the variability will eventually cause the sender to wait for ACKs) and you will have middling to poor VoIP quality.
Packit Service 6f2e62
</para>
Packit Service 6f2e62
<para>
Packit Service 6f2e62
When the specified number of packets have been sent (and received) or
Packit Service 6f2e62
if the program is terminated with a
Packit Service 6f2e62
SIGINT, a brief summary is displayed. Shorter current statistics
Packit Service 6f2e62
can be obtained without termination of process with signal
Packit Service 6f2e62
SIGQUIT.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>If <command>ping</command> does not receive any reply packets at all it will
Packit Service 6f2e62
exit with code 1. If a packet
Packit Service 6f2e62
<emphasis remap='I'>count</emphasis>
Packit Service 6f2e62
and
Packit Service 6f2e62
<emphasis remap='I'>deadline</emphasis>
Packit Service 6f2e62
are both specified, and fewer than
Packit Service 6f2e62
<emphasis remap='I'>count</emphasis>
Packit Service 6f2e62
packets are received by the time the
Packit Service 6f2e62
<emphasis remap='I'>deadline</emphasis>
Packit Service 6f2e62
has arrived, it will also exit with code 1.
Packit Service 6f2e62
On other error it exits with code 2. Otherwise it exits with code 0. This
Packit Service 6f2e62
makes it possible to use the exit code to see if a host is alive or
Packit Service 6f2e62
not.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>This program is intended for use in network testing, measurement and
Packit Service 6f2e62
management.
Packit Service 6f2e62
Because of the load it can impose on the network, it is unwise to use
Packit Service 6f2e62
<command>ping</command> during normal operations or from automated scripts.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='icmp_packet_details'><title>ICMP PACKET DETAILS</title>
Packit Service 6f2e62
<para>An IP header without options is 20 bytes.
Packit Service 6f2e62
An ICMP ECHO_REQUEST packet contains an additional 8 bytes worth
Packit Service 6f2e62
of ICMP header followed by an arbitrary amount of data.
Packit Service 6f2e62
When a <emphasis remap='I'>packetsize</emphasis> is given, this indicated the size of this
Packit Service 6f2e62
extra piece of data (the default is 56). Thus the amount of data received
Packit Service 6f2e62
inside of an IP packet of type ICMP ECHO_REPLY will always be 8 bytes
Packit Service 6f2e62
more than the requested data space (the ICMP header).</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>If the data space is at least of size of struct timeval
Packit Service 6f2e62
<command>ping</command> uses the beginning bytes of this space to include
Packit Service 6f2e62
a timestamp which it uses in the computation of round trip times.
Packit Service 6f2e62
If the data space is shorter, no round trip times are given.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='duplicate_and_damaged_packets'><title>DUPLICATE AND DAMAGED PACKETS</title>
Packit Service 6f2e62
<para><command>ping</command> will report duplicate and damaged packets.
Packit Service 6f2e62
Duplicate packets should never occur, and seem to be caused by
Packit Service 6f2e62
inappropriate link-level retransmissions.
Packit Service 6f2e62
Duplicates may occur in many situations and are rarely (if ever) a
Packit Service 6f2e62
good sign, although the presence of low levels of duplicates may not
Packit Service 6f2e62
always be cause for alarm.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>Damaged packets are obviously serious cause for alarm and often
Packit Service 6f2e62
indicate broken hardware somewhere in the
Packit Service 6f2e62
<command>ping</command> packet's path (in the network or in the hosts).</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='trying_different_data_patterns'>
Packit Service 6f2e62
  <title>TRYING DIFFERENT DATA PATTERNS</title>
Packit Service 6f2e62
<para>The (inter)network layer should never treat packets differently depending
Packit Service 6f2e62
on the data contained in the data portion.
Packit Service 6f2e62
Unfortunately, data-dependent problems have been known to sneak into
Packit Service 6f2e62
networks and remain undetected for long periods of time.
Packit Service 6f2e62
In many cases the particular pattern that will have problems is something
Packit Service 6f2e62
that doesn't have sufficient “transitions”, such as all ones or all
Packit Service 6f2e62
zeros, or a pattern right at the edge, such as almost all zeros.
Packit Service 6f2e62
It isn't necessarily enough to specify a data pattern of all zeros (for
Packit Service 6f2e62
example) on the command line because the pattern that is of interest is
Packit Service 6f2e62
at the data link level, and the relationship between what you type and
Packit Service 6f2e62
what the controllers transmit can be complicated.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>This means that if you have a data-dependent problem you will probably
Packit Service 6f2e62
have to do a lot of testing to find it.
Packit Service 6f2e62
If you are lucky, you may manage to find a file that either can't be sent
Packit Service 6f2e62
across your network or that takes much longer to transfer than other
Packit Service 6f2e62
similar length files.
Packit Service 6f2e62
You can then examine this file for repeated patterns that you can test
Packit Service 6f2e62
using the <option>-p</option> option of <command>ping</command>.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='ttl_details'><title>TTL DETAILS</title>
Packit Service 6f2e62
<para>The TTL value of an IP packet represents the maximum number of IP routers
Packit Service 6f2e62
that the packet can go through before being thrown away.
Packit Service 6f2e62
In current practice you can expect each router in the Internet to decrement
Packit Service 6f2e62
the TTL field by exactly one.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>The TCP/IP specification states that the TTL field for TCP
Packit Service 6f2e62
packets should be set to 60, but many systems use smaller values
Packit Service 6f2e62
(4.3 BSD uses 30, 4.2 used 15).</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>The maximum possible value of this field is 255, and most Unix systems set
Packit Service 6f2e62
the TTL field of ICMP ECHO_REQUEST packets to 255.
Packit Service 6f2e62
This is why you will find you can “ping” some hosts, but not reach them
Packit Service 6f2e62
with
Packit Service 6f2e62
<citerefentry><refentrytitle>telnet</refentrytitle><manvolnum>1</manvolnum></citerefentry>
Packit Service 6f2e62
or
Packit Service 6f2e62
<citerefentry><refentrytitle>ftp</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
Packit Service 6f2e62
Packit Service 6f2e62
<para>In normal operation ping prints the TTL value from the packet it receives.
Packit Service 6f2e62
When a remote system receives a ping packet, it can do one of three things
Packit Service 6f2e62
with the TTL field in its response:</para>
Packit Service 6f2e62
<variablelist remap='TP'>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>• Not change it; this is what Berkeley Unix systems did before the
Packit Service 6f2e62
4.3BSD Tahoe release. In this case the TTL value in the received packet
Packit Service 6f2e62
will be 255 minus the number of routers in the round-trip path.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>• Set it to 255; this is what current Berkeley Unix systems do.
Packit Service 6f2e62
In this case the TTL value in the received packet will be 255 minus the
Packit Service 6f2e62
number of routers in the path <emphasis remap='B'>from</emphasis>
Packit Service 6f2e62
the remote system <emphasis remap='B'>to</emphasis> the <command>ping</command>ing host.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>• Set it to some other value. Some machines use the same value for
Packit Service 6f2e62
ICMP packets that they use for TCP packets, for example either 30 or 60.
Packit Service 6f2e62
Others may use completely wild values.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
</variablelist>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='bugs'><title>BUGS</title>
Packit Service 6f2e62
<variablelist remap='TP'>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>• Many Hosts and Gateways ignore the RECORD_ROUTE option.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>• The maximum IP header length is too small for options like
Packit Service 6f2e62
RECORD_ROUTE to be completely useful.
Packit Service 6f2e62
There's not much that can be done about this, however.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
  <varlistentry>
Packit Service 6f2e62
  <listitem>
Packit Service 6f2e62
<para>• Flood pinging is not recommended in general, and flood pinging the
Packit Service 6f2e62
broadcast address should only be done under very controlled conditions.</para>
Packit Service 6f2e62
  </listitem>
Packit Service 6f2e62
  </varlistentry>
Packit Service 6f2e62
</variablelist>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='see_also'>
Packit Service 6f2e62
  <title>SEE ALSO</title>
Packit Service 6f2e62
  <para><citerefentry><refentrytitle>ip</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
Packit Service 6f2e62
<citerefentry><refentrytitle>ss</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='history'>
Packit Service 6f2e62
  <title>HISTORY</title>
Packit Service 6f2e62
  <para>The <command>ping</command> command appeared in 4.3BSD.</para>
Packit Service 6f2e62
Packit Service 6f2e62
  <para>The version described here is its descendant specific to Linux.</para>
Packit Service 6f2e62
Packit Service 6f2e62
  <para>As of version s20150815, the <emphasis remap='B'>ping6</emphasis> binary doesn't exist anymore.
Packit Service 6f2e62
It has been merged into <command>ping</command>. Creating a symlink named
Packit Service 6f2e62
<emphasis remap='B'>ping6</emphasis> pointing to <command>ping</command> will result in the same
Packit Service 6f2e62
funcionality as before.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='security'>
Packit Service 6f2e62
  <title>SECURITY</title>
Packit Service 6f2e62
<para><command>ping</command> requires CAP_NET_RAW capability
Packit Service 6f2e62
to be executed 1) if the program is used for non-echo queries
Packit Service 6f2e62
(See <option>-N</option> option), or 2) if kernel does not
Packit Service 6f2e62
support non-raw ICMP sockets, or 3) if the user is not allowed
Packit Service 6f2e62
to create an ICMP echo socket.  The program may be used as
Packit Service 6f2e62
set-uid root.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
Packit Service 6f2e62
<refsect1 id='availability'>
Packit Service 6f2e62
  <title>AVAILABILITY</title>
Packit Service 6f2e62
  <para><command>ping</command> is part of <emphasis remap='I'>iputils</emphasis> package.</para>
Packit Service 6f2e62
</refsect1>
Packit Service 6f2e62
</refentry>