githubmirror/iputils

doc/clockdiff.xml
212 строк6 KB
Michael Karr
clockdiff: Document CAP_SYS_NICE requirement
16 июл 2022, 13:18
16 июл 2022, 13:18aa6f42d
<refentry xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="man.clockdiff">

  <refentryinfo>
    <title>clockdiff</title>
    <productname>iputils</productname>
  </refentryinfo>

  <refmeta>
    <refentrytitle>
      <application>clockdiff</application>
    </refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class='manual'>iputils</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>clockdiff</refname>
    <refpurpose>measure clock difference between hosts</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command>clockdiff</command>
      <arg choice="opt" rep="norepeat">
        <option>-o</option>
      </arg>
      <arg choice="opt" rep="norepeat">
        <option>-o1</option>
      </arg>
      <arg choice="opt" rep="norepeat">
        <option>--time-format
        <replaceable>ctime iso</replaceable></option>
      </arg>
      <arg choice="opt" rep="norepeat">
        <option>-V</option>
      </arg>
      <arg choice="req" rep="norepeat">destination</arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsection>
    <info>
      <title>DESCRIPTION</title>
    </info>
    <para>
    <command>clockdiff</command> Measures clock difference between
    us and
    <emphasis remap="I">destination</emphasis> with 1 msec
    resolution using ICMP TIMESTAMP [2] packets or, optionally, IP
    TIMESTAMP option [3] added to ICMP ECHO. [1]</para>
  </refsection>

  <refsection>
    <info>
      <title>OPTIONS</title>
    </info>
    <variablelist remap='TP'>
      <varlistentry>
        <term>
          <option>-o</option>
        </term>
        <listitem>
          <para>Use IP TIMESTAMP with ICMP ECHO instead of ICMP
          TIMESTAMP messages. It is useful with some destinations,
          which do not support ICMP TIMESTAMP (f.e. Solaris
          &lt;2.4).</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-o1</option>
        </term>
        <listitem>
          <para>Slightly different form of
          <option>-o</option>, namely it uses three-term IP
          TIMESTAMP with prespecified hop addresses instead of four
          term one. What flavor works better depends on target
          host. Particularly,
          <option>-o</option> is better for Linux.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-T</option>
        </term>
        <term>
          <option>--time-format <replaceable>ctime iso</replaceable></option>
        </term>
        <listitem>
          <para>Print time stamp in output either ISO-8601 format or
          classical ctime format. The ctime format is default. The ISO
          time stamp includes timezone, and is easier to parse.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-I</option>
        </term>
        <listitem>
          <para>Alias of <option>--time-format <replaceable>iso</replaceable>
          </option> option and argument.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-h</option>
        </term>
        <term>
          <option>--help</option>
        </term>
        <listitem>
          <para>Print help and exit.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>
          <option>-V</option>
        </term>
        <term>
          <option>--version</option>
        </term>
        <listitem>
          <para>Print version and exit.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsection xml:id="warnings">
    <info>
      <title>WARNINGS</title>
    </info>
    <variablelist remap="TP">
      <varlistentry>
        <listitem>
          <para>• Some nodes (Cisco) use non-standard timestamps,
          which is allowed by RFC, but makes timestamps mostly
          useless.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <listitem>
          <para>• Some nodes generate messed timestamps
          (Solaris&gt;2.4), when run
          <command>xntpd</command>. Seems, its IP stack uses a
          corrupted clock source, which is synchronized to
          time-of-day clock periodically and jumps randomly making
          timestamps mostly useless. Good news is that you can use
          NTP in this case, which is even better.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <listitem>
          <para>•
          <command>clockdiff</command> shows difference in time
          modulo 24 days.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsection>

  <refsect1 id='see_also'>
    <title>SEE ALSO</title>
    <para>
    <citerefentry>
      <refentrytitle>ping</refentrytitle>
      <manvolnum>8</manvolnum>
    </citerefentry>,
    <citerefentry>
      <refentrytitle>arping</refentrytitle>
      <manvolnum>8</manvolnum>
    </citerefentry>,
    <citerefentry>
      <refentrytitle>tracepath</refentrytitle>
      <manvolnum>8</manvolnum>
    </citerefentry>.</para>
  </refsect1>

  <refsection xml:id="references">
    <info>
      <title>REFERENCES</title>
    </info>
    <para>[1] ICMP ECHO, RFC0792, page 14.</para>
    <para>[2] ICMP TIMESTAMP, RFC0792, page 16.</para>
    <para>[3] IP TIMESTAMP option, RFC0791, 3.1, page 16.</para>
  </refsection>

  <refsect1 id='author'>
    <title>AUTHOR</title>
    <para>
    <command>clockdiff</command> was compiled by Alexey Kuznetsov
    &lt;kuznet@ms2.inr.ac.ru&gt;. It was based on code borrowed
    from BSD
    <command>timed</command> daemon.</para>
  </refsect1>

  <refsect1 id='security'>
    <title>SECURITY</title>
    <para>
    <command>clockdiff</command> requires CAP_NET_RAW and
    CAP_SYS_NICE capabilities to be executed. It is safe
    to be used as set-uid root.</para>
  </refsect1>

  <refsect1 id='availability'>
    <title>AVAILABILITY</title>
    <para>
    <command>clockdiff</command> is part of
    <emphasis remap='I'>iputils</emphasis> package.</para>
  </refsect1>
</refentry>