source: networking/netutils/wireshark.xml@ 475b404

<?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.xz">
  <!ENTITY wireshark-download-ftp  " ">
  <!ENTITY wireshark-md5sum        "716100be9027e735bba82a40db828abc">
  <!ENTITY wireshark-size          "27 MB">
  <!ENTITY wireshark-buildsize     "2.0 GB (with default GUI front-end, and all optional dependencies available in the BLFS book)">
  <!ENTITY wireshark-time          "4.0 SBU (with parallelism=4, default GUI front-end, and all optional dependencies available in the BLFS book)">
]>

<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>

    &lfs83_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.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"/> and
      <xref linkend="libgcrypt"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <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="gtk3"/> or <xref linkend="gtk2"/> (for the legacy GTK GUI),
      <xref linkend="libnl"/>,
      <xref linkend="lua"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="nghttp2"/>,
      <xref linkend="sbc"/>,
      <ulink url="http://www.ibr.cs.tu-bs.de/projects/libsmi/">libsmi</ulink>,
      <ulink url="http://lz4.github.io/lz4/">lz4</ulink>,
      <ulink url="http://www.maxmind.com/app/c">GeoIP</ulink>,
      <ulink url="https://www.libssh.org/">libssh</ulink>,
      <ulink url="http://www.portaudio.com/">PortAudio</ulink>
      (for GTK+ RTP player),
      <ulink url="http://google.github.io/snappy/">Snappy</ulink>, and
      <ulink url="https://www.soft-switch.org/">Spandsp</ulink>
    </para>

    <note>
      <para>
        The Qt GUI front-end is built by default, if <xref linkend="qt5"/> is
        found. If you want to build the GTK+ GUI front-end, 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.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-gtk=[yes/no/2/3]</option>: For the Gtk+ GUI. Default is no.
      If both Gtk+2 and 3 are installed, and <quote>yes</quote> is selected,
      default is 3. Obviously, <xref linkend="gtk2"/> or <xref linkend="gtk3"/>
      must have been built for this to work.
    </para>

    <para>
      <option>--with-qt=[yes/no/4/5]</option>: For the Qt GUI. Default is yes,
      if <xref linkend="qt5"/> is found on the system.
    </para>

    <para>
      <option>--disable-wireshark</option>: Use this switch if you
      have <application>Qt</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, sharkd,
          text2pcap, tshark, wireshark, and wireshark-gtk (optional)
        </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="idl2wrs">
        <term><command>idl2wrs</command></term>
        <listitem>
          <para>is a program that takes a user specified CORBA IDL file and
          generates <quote>C</quote> source code for a
          <application>Wireshark</application> <quote>plugin</quote>. It relies
          on two Python programs <command>wireshark_be.py</command> and
          <command>wireshark_gen.py</command>, which are not installed
          by default. They have to be copied manually from the <filename
          class="directory">tools</filename> directory to the <filename
          class="directory">$PYTHONPATH/site-packages/</filename> directory.
          </para>
          <indexterm zone="wireshark idl2wrs">
            <primary sortas="b-idl2wrs">idl2wrs</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="sharkd">
        <term><command>sharkd</command></term>
        <listitem>
          <para>is a daemon that listens on UNIX sockets.</para>
          <indexterm zone="wireshark sharkd">
            <primary sortas="b-sharkd">sharkd</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 (optional).
          </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>