glfs/networking/netutils/wireshark.xml

<?xml version="1.0" encoding="UTF-8"?>
<!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        "3012a4f3afc2b131f54d5e98351daf72">
  <!ENTITY wireshark-size          "43 MB">
  <!ENTITY wireshark-buildsize     "740 MB (with all optional dependencies available in the BLFS book; 167 MB installed)">
  <!ENTITY wireshark-time          "2.7 SBU (with parallelism=4 and all optional dependencies available in the BLFS book)">
]>

<!-- Gentle reminder: many Wireshark releases contain vulnerability fixes,
 we have not always been aware of these. At https://www.wireshark.org/security/
 there is a list of advisories and the version in which they were fixed.

 If you click on an advisory, after the bug number in the References:
 there may be a CVE number, although perhaps those get added some time after
 the release.  Perhaps as a general rule treat ALL their advisories for crashes
 etc as worthy of a security fix. -->

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


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

    &lfs120_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>
          Required patch to build with Python-3.12:
          <ulink url="&patch-root;/wireshark-&wireshark-version;-py_3.12_fix-1.patch"/>
        </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="cmake"/>,
      <xref linkend="c-ares"/>,
      <xref linkend="glib2"/>,
      <xref linkend="libgcrypt"/>, and
      <xref linkend="qt6"/>
    </para>

    <note>
      <para>
        <xref linkend="qt6"/> is not strictly required, since it can be
        replaced with <application>Qt5</application>. See <quote>Command
        explanations</quote> below.
      </para>
    </note>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="libpcap"/> (required to capture data)
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="asciidoctor"/>,
      <xref linkend="brotli"/>,
      <xref linkend="doxygen"/>,
      <xref linkend="git"/>,
      <xref linkend="gnutls"/>,
      <xref linkend="libnl"/>,
      <xref linkend="libxslt"/>,
      <xref linkend="libxml2"/>,
      <xref linkend="lua52"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="nghttp2"/>,
      (<xref linkend="qt5"/> or
      <xref role="nodep" linkend="qt5-components"/> with qtmultimedia)
      (required if <xref role="nodep" linkend="qt6"/> is not installed),
      <xref linkend="sbc"/>,
      <xref linkend="speex"/>,
      <ulink url="https://www.linphone.org/technical-corner/bcg729">BCG729</ulink>,
      <ulink url="https://github.com/TimothyGu/libilbc">libilbc</ulink>,
      <ulink url="https://www.ibr.cs.tu-bs.de/projects/libsmi/">libsmi</ulink>,
      <ulink url="https://lz4.github.io/lz4/">lz4</ulink>,
      <ulink url="https://www.libssh.org/">libssh</ulink>,
      <ulink url="https://github.com/maxmind/libmaxminddb">MaxMindDB</ulink>,
      <ulink url="https://www.winimage.com/zLibDll/minizip.html">Minizip</ulink>,
      <ulink url="https://google.github.io/snappy/">Snappy</ulink>, and
      <ulink url="https://github.com/freeswitch/spandsp">Spandsp</ulink>
    </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>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="wireshark-kernel.xml"/>

    <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>mkdir build &amp;&amp;
cd    build &amp;&amp;

cmake -DCMAKE_INSTALL_PREFIX=/usr \
      -DCMAKE_BUILD_TYPE=Release  \
      -DCMAKE_INSTALL_DOCDIR=/usr/share/doc/wireshark-&wireshark-version; \
      -G Ninja \
      .. &amp;&amp;
ninja</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>ninja install &amp;&amp;

install -v -m755 -d /usr/share/doc/wireshark-&wireshark-version; &amp;&amp;
install -v -m644    ../README.linux ../doc/README.* ../doc/randpkt.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"
        remap="doc"><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 <replaceable>&lt;username&gt;</replaceable></userinput></screen>

    <para>
      If you are installing wireshark for the first time, it will be necessary
      to logout of your session and login again. This will put wireshark in your
      groups, because otherwise Wireshark will not function properly.
    </para>

  </sect2>

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

      <para>
        <option>-DUSE_qt6=OFF</option>: Use this switch if
        <xref linkend="qt6"/> is not available. You'll need
        <xref linkend="qt5"/> or at least <xref linkend="qt5-components"/>
        with qtmultimedia in this case.
      </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=
        "https://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, dumpcap, editcap, idl2wrs,
          mergecap, randpkt, rawshark, reordercap, sharkd,
          text2pcap, tshark, and wireshark
        </seg>
        <seg>
          libwireshark.so, libwiretap.so,
          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="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>
            dumps and analyzes 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>
            reorders timestamps of input file frames into an 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>
<!-- seems to have disappeared
      <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>