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  "ftp://ftp.uni-kl.de/pub/wireshark/src/wireshark-&wireshark-version;.tar.bz2">
  <!ENTITY wireshark-md5sum        "c8ae53f648b1dcbf6e74495401a0f1ab">
  <!ENTITY wireshark-size          "28 MB">
  <!ENTITY wireshark-buildsize     "1.6 GB, with the Qt GUI">
  <!ENTITY wireshark-time          "6.2 SBU, with the Qt GUI">
]>

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

    &lfs77_checked; &gcc5_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_0-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"/> (to build the <application>Gtk+3</application>
      GUI) and
      <xref linkend="libpcap"/> (required to capture data)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="gnutls"/>,
      <xref linkend="libgcrypt"/>,
      <xref linkend="lua"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="openssl"/>,
      <ulink url="http://www.gnu.org/software/adns/adns.html">adns</ulink>,
      <ulink url="http://www.maxmind.com/app/c">GeoIP</ulink>, and
      <ulink url="http://www.portaudio.com/download.html">PortAudio</ulink>
    </para>

    <bridgehead renderas="sect4">Optional (to build more GUI front-ends)
    </bridgehead>
    <para role="optional">
      <xref linkend="gtk2"/>,
      <xref linkend="qt4"/>, or
      <xref linkend="qt5"/>
    </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 one of <xref linkend=
        "qt4"/> or <xref linkend="qt5"/>. If both are installed, Qt5
        is used by default.
      </para>

      <para>
        Both GTK+ and Qt GUI can be built at the same time. If you want to
        override the defaults, some configure switches have to be set
        (see <quote>Command Explanations</quote>) or some special instructions
        have to be issued (see below) when both Qt4 and Qt5 are installed and
        you want to use Qt4.  SBU and disk space required are larger for the
        Qt GUI. The instructions below suppose you only want to build the
        GTK+3 GUI.
      </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>
      Optionally, fix the description of the program in the title.
      The first change overwrites the default <quote>SVN Unknown</quote> in
      the title and the second overwrites a utility script that resets the
      version to <quote>unknown</quote>.
    </para>

<screen><userinput>cat > svnversion.h &lt;&lt; "EOF" &amp;&amp;
#define SVNVERSION "BLFS"
#define SVNPATH "source"
EOF

cat > make-version.pl &lt;&lt; "EOF"
<literal>#!/usr/bin/perl</literal>
EOF</userinput></screen>

    <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>
      If you want to build the Qt GUI (see <quote>Command Explanations</quote>),
      for the <application>Qt5</application> GUI, issue:
    </para>

<screen><userinput>source setqt5 &amp;&amp;

sed -e 's/"-fPIE"/""/' \
    -e 's/"-pie"/""/'  \
    -i configure</userinput></screen>

    <para>
      and add <envar>CXXFLAGS="-fPIC"</envar> to the configure line, or, for the <application>Qt4</application> GUI, issue:
    </para>

<screen><userinput>source setqt4 &amp;&amp;
sed -i 's/Qt5 Qt/Qt/' configure</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_0-1.patch  &amp;&amp;

./configure --prefix=/usr     \
            --with-gtk3       \
            --without-qt      \
            --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 -m755 -d /usr/share/pixmaps/wireshark &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 &amp;&amp;
unset FILENAME

install -v -m644 -D wireshark.desktop \
                    /usr/share/applications/wireshark.desktop &amp;&amp;

install -v -m644 -D image/wsicon48.png \
                    /usr/share/pixmaps/wireshark.png &amp;&amp;

install -v -m644    image/*.{png,ico,xpm,bmp} \
                    /usr/share/pixmaps/wireshark</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>

  </sect2>

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

    <para>
      <command>sed -e 's/"-fPIE"/""/' ... configure</command>: This command is
      required for Qt-5.5, because it is necessary to compile with
      <envar>CXXFLAGS="-fPIC"</envar>.
    </para>

    <para>
      <command>sed -i 's/Qt5 Qt/Qt/' ...</command>: This command is required
      because, without it, libraries and includes from
      <application>Qt5</application> are found and used first, if both versions
      are installed, when trying to build with <application>Qt4</application>,
      and <command>make</command> does not complete.
    </para>

    <para>
      <parameter>--with-gtk3</parameter>: By default, the build machinery
      will build a GUI for both Qt and GTK+, if those libraries are found.
      If Qt is installed and you do not want the GUI for it to be built,
      you need to pass <parameter>--without-qt</parameter> to the configure
      script. That overrides the default, so that you must specify
      <parameter>--with-gtk3</parameter>  or <parameter>--with-gtk2</parameter>
      in order to have the GTK+ GUI built.
    </para>

    <para>
      <parameter>--without-qt</parameter>: disables building of the Qt GUI.
    </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>

    <para>
      <option>--with-gtk2</option>: Use this option if you want
      the <application>GTK+2</application> GUI.
      Notice that the GUI for only one GTK+ version (either 2 or 3) can be
      built.
    </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>~/.wireshark/*</filename></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>

    </sect3>

    <sect3>
      <title>Desktop file for the Qt GUI</title>

      <para>If Qt GUI was built and you wish an entry in the desktop menu,
      there are two possibilities (instructions must be run as root).</para>

      <para>If only the Qt GUI was built:</para>

<screen role="root"><userinput>mv -v /usr/share/applications/wireshark.desktop \
      /usr/share/applications/wireshark-qt.desktop</userinput></screen>

      <para>If both, GTK+ and Qt GUIs were built:</para>

<screen role="root"><userinput>cp -v /usr/share/applications/wireshark.desktop \
      /usr/share/applications/wireshark-qt.desktop</userinput></screen>

      <para>Now, fix it for <command>wireshark-qt</command>:</para>

<screen role="root"><userinput>sed -e 's/ireshark/&amp;-qt/' \
    -e 's/^\(Icon=wireshark\)-qt/\1/' \
    -i /usr/share/applications/wireshark-qt.desktop</userinput></screen>

      <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, mergecap, randpkt,
        rawshark, reordercap, text2pcap, tshark,
        wireshark, and optionally wireshark-qt</seg>
        <seg>libfiletap.so, libwireshark.so, libwiretap.so, libwsutil.so, and
        numerous modules under /usr/lib/wireshark/plugins</seg>
        <seg>/usr/lib/wireshark, /usr/share/doc/wireshark-&wireshark-version;,
        /usr/share/pixmaps/wireshark, and /usr/share/wireshark</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 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-prog">
            <primary sortas="b-wireshark">wireshark</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="wireshark-qt-prog">
        <term><command>wireshark-qt</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-qt-prog">
            <primary sortas="b-wireshark-qt">wireshark-qt</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>