glfs/networking/netutils/wireshark.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY wireshark-download-http "https://www.wireshark.org/download/src/all-versions/wireshark-&wireshark-version;.tar.bz2">
  <!ENTITY wireshark-download-ftp  " ">
  <!ENTITY wireshark-md5sum        "a4d880554c7f925dafef60fa313b580d">
  <!ENTITY wireshark-size          "31 MB">
  <!ENTITY wireshark-buildsize     "1.6 GB (with default GUI front-ends, and SBC codec)">
  <!ENTITY wireshark-time          "3.5 SBU (with parallelism=4 and default GUI front-ends)">
]>

<sect1 id="wireshark" xreflabel="Wireshark-&wireshark-version;">
  <?dbhtml filename="wireshark.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Wireshark-&wireshark-version;</title>

  <indexterm zone="wireshark">
    <primary sortas="a-Wireshark">Wireshark</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Wireshark</title>

    <para>
      The <application>Wireshark</application> package contains a network
      protocol analyzer, also known as a <quote>sniffer</quote>. This is useful
      for analyzing data captured <quote>off the wire</quote> from a live
      network connection, or data read from a capture file.
    </para>

    <para>
      <application>Wireshark</application> provides both a graphical and a
      TTY-mode front-end for examining captured network packets from over 500
      protocols, as well as the capability to read capture files from many
      other popular network analyzers.
    </para>

    &lfs80_checked;
    &gcc7_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&wireshark-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&wireshark-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &wireshark-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &wireshark-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &wireshark-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &wireshark-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Optional patch:
          <ulink url=
              "&patch-root;/wireshark-&wireshark-version;-lua_5_3_1-1.patch"/>
          (allows building the LUA bindings if <xref linkend="lua"/> is
          installed and LUA is not disabled by passing <option>--without-lua
          </option> to <command>configure</command>)
        </para>
      </listitem>
      <listitem>
        <para>
          Additional Documentation:
          <ulink url="https://www.wireshark.org/download/docs/"/>
          (contains links to several different docs in a variety of formats)
         </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Wireshark dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="glib2"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="gtk3"/> (for the <application>Gtk+3</application> GUI),
      <xref linkend="libpcap"/> (required to capture data), and
      <xref linkend="qt5"/> (for the <application>Qt5</application> GUI)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="c-ares"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="libgcrypt"/>,
      <xref linkend="libnl"/>,
      <xref linkend="lua"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="openssl"/>,
      <xref linkend="sbc"/>,
      <ulink url="http://www.gnu.org/software/adns/adns.html">adns</ulink>,
      <ulink url="http://www.ibr.cs.tu-bs.de/projects/libsmi/">libsmi</ulink>,
      <ulink url="http://www.maxmind.com/app/c">GeoIP</ulink>, and
      <ulink url="http://www.portaudio.com/">PortAudio</ulink>
      (for GTK+ RTP player)
    </para>

    <bridgehead renderas="sect4">Optional (for GUI front-ends)
    </bridgehead>
    <para role="optional">
      <xref linkend="gtk2"/>
    </para>

    <note>
      <para>
        The <application>GTK+</application> GUI needs one of <xref linkend=
        "gtk2"/> or <xref linkend="gtk3"/>. If both are installed, GTK+3
        is used by default.
      </para>

      <para>
        The <application>Qt</application> GUI needs <xref linkend="qt5"/>. 
      </para>

      <para>
        Both GTK+ and Qt GUI front-ends are built, as recommended by the
        upstream developers.  If you want to override the defaults, some
        configure switches have to be set (see <quote>Command
        Explanations</quote>).
      </para>
    </note>

    <para condition="html" role="usernotes">
      User Notes: <ulink url="&blfs-wiki;/wireshark"/>
    </para>

  </sect2>

  <sect2 role="kernel" id="wireshark-kernel">
    <title>Kernel Configuration</title>

    <para>
      The kernel must have the Packet protocol enabled for <application>
      Wireshark</application> to capture live packets from the network:
    </para>

<screen><literal>[*] Networking support ---&gt;          [CONFIG_NET]
      Networking options ---&gt;
        &lt;*/M&gt; Packet socket          [CONFIG_PACKET]</literal></screen>

    <para>
      If built as a module, the name is <filename>af_packet.ko</filename>.
    </para>

    <indexterm zone="wireshark wireshark-kernel">
      <primary sortas="d-Capturing-network-packets">
        Capturing network packets
      </primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Wireshark</title>

    <para>
      <application>Wireshark</application> is a very large and complex
      application. These instructions provide additional security measures to
      ensure that only trusted users are allowed to view network traffic. First,
      set up a system group for wireshark.  As the <systemitem
      class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>groupadd -g 62 wireshark</userinput></screen>

    <para>
      Continue to install <application>Wireshark</application> by running
      the following commands:
    </para>

<screen><userinput>patch -Np1 -i ../wireshark-&wireshark-version;-lua_5_3_1-1.patch  &amp;&amp;

./configure --prefix=/usr --sysconfdir=/etc &amp;&amp;
make</userinput></screen>

    <para>
      This package does not come with a test suite.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make install &amp;&amp;

install -v -m755 -d /usr/share/doc/wireshark-&wireshark-version; &amp;&amp;
install -v -m644    README{,.linux} doc/README.* doc/*.{pod,txt} \
                    /usr/share/doc/wireshark-&wireshark-version; &amp;&amp;

pushd /usr/share/doc/wireshark-&wireshark-version; &amp;&amp;
   for FILENAME in ../../wireshark/*.html; do
      ln -s -v -f $FILENAME .
   done &amp;&amp;
popd
unset FILENAME</userinput></screen>

    <para>
      If you downloaded any of the documentation files from the page
      listed in the 'Additional Downloads', install them by issuing the
      following commands as the <systemitem class="username">root</systemitem>
      user:
    </para>

<screen role="root"><userinput>install -v -m644 <replaceable>&lt;Downloaded_Files&gt;</replaceable> \
                 /usr/share/doc/wireshark-&wireshark-version;</userinput></screen>

    <para>
      Now, set ownership and permissions of sensitive applications to only
      allow authorized users.  As the <systemitem class="username">root
      </systemitem> user:
    </para>

<screen role="root"><userinput>chown -v root:wireshark /usr/bin/{tshark,dumpcap} &amp;&amp;
chmod -v 6550 /usr/bin/{tshark,dumpcap}</userinput></screen>

    <para>
      Finally, add any users to the wireshark group (as <systemitem class=
      "username">root</systemitem> user):
    </para>

<screen role="root"><userinput>usermod -a -G wireshark &lt;username&gt;</userinput></screen>

    <para>
      If you are installing wireshark for the first time, it will be necessary
      to leave the session and login again, thus you will now have wireshark
      between your groups, otherwise, it will not run properly.
    </para>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <option>--with-gtk2=[yes/no]</option>: For the Gtk+2 GUI. If both Gtk+2
      and 3 are installed, default is no. Notice that the GUI for only one Gtk+
      version (either 2 or 3) can be built.
    </para>

    <para>
      <option>--with-gtk3=[yes/no]</option>: For the Gtk+3 GUI. If both Gtk+2
      and 3 are installed, default is yes.
    </para>

    <para>
      <option>--with-qt=[yes/no/4/5]</option>: For the Qt GUI. Default is yes.
    </para>

    <para>
      <option>--disable-wireshark</option>: Use this switch if you
      have <application>GTK+</application> installed but do not want to build
      any of the GUIs.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Wireshark</title>

    <sect3 id="wireshark-config">
      <title>Config Files</title>

      <para><filename>/etc/wireshark.conf</filename> and
      <filename>~/.config/wireshark/*</filename> (unless there is already
      <filename>~/.wireshark/*</filename> in the system)</para>

      <indexterm zone="wireshark wireshark-config">
        <primary sortas="e-AA.wireshark-star">~/.wireshark/*</primary>
      </indexterm>

      <indexterm zone="wireshark wireshark-config">
        <primary sortas="e-etc-wireshark.conf">/etc/wireshark.conf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>Though the default configuration parameters are very sane, reference
      the configuration section of the <ulink
      url="http://www.wireshark.org/docs/wsug_html/">Wireshark User's
      Guide</ulink> for configuration information. Most of
      <application>Wireshark</application>'s configuration can be accomplished
      using the menu options of the <command>wireshark</command> graphical
      interfaces.</para>

      <note>
        <para>If you want to look at packets, make sure you don't filter them
        out with <xref linkend="iptables"/>. If you want to exclude certain
        classes of packets, it is more efficient to do it with
        <application>iptables</application> than it is with
        <application>Wireshark</application>.</para>
      </note>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          capinfos, captype, dftest, dumpcap, editcap, idl2wrs,
          mergecap, randpkt, rawshark, reordercap, text2pcap, tshark, wireshark,
          and wireshark-gtk
        </seg>
        <seg>
          libwireshark.so, libwiretap.so, libwscodecs.so (optional),
          libwsutil.so, and numerous modules under /usr/lib/wireshark/plugins
        </seg>
        <seg>
          /usr/{lib,share}/wireshark and
          /usr/share/doc/wireshark-&wireshark-version;
         </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="capinfos">
        <term><command>capinfos</command></term>
        <listitem>
          <para>reads a saved capture file and returns any or all of several
          statistics about that file. It is able to detect and read any capture
          supported by the <application>Wireshark</application> package.</para>
          <indexterm zone="wireshark capinfos">
            <primary sortas="b-capinfos">capinfos</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="captype">
        <term><command>captype</command></term>
        <listitem>
          <para>prints the file types of capture files.</para>
          <indexterm zone="wireshark captype">
            <primary sortas="b-captype">captype</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dftest">
        <term><command>dftest</command></term>
        <listitem>
          <para>is a display-filter-compiler test program.</para>
          <indexterm zone="wireshark dftest">
            <primary sortas="b-dftest">dftest</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="dumpcap">
        <term><command>dumpcap</command></term>
        <listitem>
          <para>is a network traffic dump tool. It lets you capture packet data
          from a live network and write the packets to a file.</para>
          <indexterm zone="wireshark dumpcap">
            <primary sortas="b-dumpcap">dumpcap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="editcap">
        <term><command>editcap</command></term>
        <listitem>
          <para>edits and/or translates the format of capture files. It knows
          how to read <application>libpcap</application> capture files,
          including those of <command>tcpdump</command>,
          <application>Wireshark</application> and other tools that write
          captures in that format.</para>
          <indexterm zone="wireshark editcap">
            <primary sortas="b-editcap">editcap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mergecap">
        <term><command>mergecap</command></term>
        <listitem>
          <para>combines multiple saved capture files into a single output
          file.</para>
          <indexterm zone="wireshark mergecap">
            <primary sortas="b-mergecap">mergecap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="randpkt">
        <term><command>randpkt</command></term>
        <listitem>
          <para>creates random-packet capture files.</para>
          <indexterm zone="wireshark randpkt">
            <primary sortas="b-randpkt">randpkt</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="rawshark">
        <term><command>rawshark</command></term>
        <listitem>
          <para>dump and analyze raw libpcap data.</para>
          <indexterm zone="wireshark rawshark">
            <primary sortas="b-rawshark">rawshark</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="reordercap">
        <term><command>reordercap</command></term>
        <listitem>
          <para>reorder timestamps of input file frames into output file.</para>
          <indexterm zone="wireshark reordercap">
            <primary sortas="b-reordercap">reordercap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="text2pcap">
        <term><command>text2pcap</command></term>
        <listitem>
          <para>reads in an ASCII hex dump and writes the
          data described into a <application>libpcap</application>-style
          capture file.</para>
          <indexterm zone="wireshark text2pcap">
            <primary sortas="b-text2pcap">text2pcap</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tshark">
        <term><command>tshark</command></term>
        <listitem>
          <para>is a TTY-mode network protocol analyzer. It lets you capture
          packet data from a live network or read packets from a
          previously saved capture file.</para>
          <indexterm zone="wireshark tshark">
            <primary sortas="b-tshark">tshark</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="wireshark-prog">
        <term><command>wireshark</command></term>
        <listitem>
          <para>
            is the Qt GUI network protocol analyzer. It lets you interactively
            browse packet data from a live network or from a previously saved
            capture file.
          </para>
          <indexterm zone="wireshark wireshark-prog">
            <primary sortas="b-wireshark">wireshark</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="wireshark-gtk-prog">
        <term><command>wireshark-gtk</command></term>
        <listitem>
          <para>
            is the Gtk+ GUI network protocol analyzer. It lets you interactively
            browse packet data from a live network or from a previously saved
            capture file.
          </para>
          <indexterm zone="wireshark wireshark-gtk-prog">
            <primary sortas="b-wireshark-gtk">wireshark-gtk</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libwireshark">
        <term><filename class='libraryfile'>libwireshark.so</filename></term>
        <listitem>
          <para>contains functions used by the
          <application>Wireshark</application> programs to perform filtering and
          packet capturing.</para>
          <indexterm zone="wireshark libwireshark">
            <primary sortas="c-libwireshark">libwireshark.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libwiretap">
        <term><filename class='libraryfile'>libwiretap.so</filename></term>
        <listitem>
          <para>is a library being developed as a future replacement for
          <filename class='libraryfile'>libpcap</filename>, the current
          standard Unix library for packet capturing. For more information,
          see the <filename>README</filename> file in the source
          <filename class='directory'>wiretap</filename> directory.</para>
          <indexterm zone="wireshark libwiretap">
            <primary sortas="c-libwiretap">libwiretap.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>