wireshark/docbook/wsug_src/WSUG_chapter_build_install.asciidoc

// WSUG Chapter BuildInstall

[[ChapterBuildInstall]]

== Building and Installing Wireshark

[[ChBuildInstallIntro]]

=== Introduction

As with all things there must be a beginning and so it is with Wireshark. To
use Wireshark you must first install it. If you are running Windows or macOS
you can download an official release at {wireshark-download-url}, install it,
and skip the rest of this chapter.

If you are running another operating system such as Linux or FreeBSD you might
want to install from source. Several Linux distributions offer Wireshark
packages but they commonly ship out-of-date versions. No other versions of UNIX
ship Wireshark so far. For that reason, you will need to know where to get the
latest version of Wireshark and how to install it.

This chapter shows you how to obtain source and binary packages and how to
build Wireshark from source should you choose to do so.

The following are the general steps you would use:

. Download the relevant package for your needs, e.g. source or binary
  distribution.

. Compile the source into a binary if needed.
  This may involve building and/or installing other necessary packages.

. Install the binaries into their final destinations.

[[ChBuildInstallDistro]]

=== Obtaining the source and binary distributions

You can obtain both source and binary distributions from the Wireshark
web site: {wireshark-download-url}. Select the download link and then
select the desired binary or source package.

[NOTE]
.Download all required files
====
If you are building Wireshark from source you will
In general, unless you have already downloaded Wireshark before, you will most
likely need to download several source packages if you are building Wireshark
from source. This is covered in more detail below.

// Make a ref
====

Once you have downloaded the relevant files, you can go on to the next step.

//
// Windows
//

[[ChBuildInstallWinInstall]]

=== Installing Wireshark under Windows

Windows installer names contain the platform and version. For example,
Wireshark-win64-{wireshark-version}.exe installs Wireshark {wireshark-version}
for 64-bit Windows. The Wireshark installer includes WinPcap which is required
for packet capture.

Simply download the Wireshark installer from {wireshark-download-url}
and execute it. Official packages are signed by the *Wireshark
Foundation*. You can choose to install several optional components and
select the location of the installed package. The default settings are
recommended for most users.

[[ChBuildInstallWinComponents]]

==== Installation Components

On the _Choose Components_ page of the installer you can select from the following:

* *Wireshark* - The network protocol analyzer that we all know and mostly love.

* *TShark* - A command-line network protocol analyzer. If you haven’t tried it
  you should.

* *Plugins & Extensions* - Extras for the Wireshark and TShark dissection engines

  - *Dissector Plugins* - Plugins with some extended dissections.

  - *Tree Statistics Plugins* - Extended statistics.

  - *Mate - Meta Analysis and Tracing Engine* - User configurable extension(s) of the display filter engine, see {wireshark-wiki-url}Mate for details.

  - *SNMP MIBs* - SNMP MIBs for a more detailed SNMP dissection.

* *Tools* - Additional command line tools to work with capture files

  - *Editcap* - Reads a capture file and writes some or all of the packets into
    another capture file.

  - *Text2Pcap* - Reads in an ASCII hex dump and writes the data into a
    pcap capture file.

  - *Reordercap* - Reorders a capture file by timestamp.

  - *Mergecap* - Combines multiple saved capture files into a single output file.

  - *Capinfos* - Provides information on capture files.

  - *Rawshark* - Raw packet filter.

* *User’s Guide* - Local installation of the User’s Guide. The Help buttons on
  most dialogs will require an internet connection to show help pages if the
  User’s Guide is not installed locally.

[[ChBuildInstallWinAdditionalTasks]]

==== Additional Tasks

* *Start Menu Shortcuts* - Add some start menu shortcuts.

* *Desktop Icon* - Add a Wireshark icon to the desktop.

* *Quick Launch Icon* - add a Wireshark icon to the Explorer quick launch toolbar.

* *Associate file extensions to Wireshark* - Associate standard network trace files to Wireshark.

[[ChBuildInstallWinLocation]]

==== Install Location

By default Wireshark installs into `%ProgramFiles%\Wireshark` on 32-bit Windows
and `%ProgramFiles64%\Wireshark` on 64-bit Windows. This expands to `C:\Program
Files\Wireshark` on most systems.

[[ChBuildInstallWinPcap]]

==== Installing WinPcap

The Wireshark installer contains the latest WinPcap installer.

If you don’t have WinPcap installed you won’t be able to capture live network
traffic but you will still be able to open saved capture files. By default the
latest version of WinPcap will be installed. If you don’t wish to do this or if
you wish to reinstall WinPcap you can check the _Install WinPcap_ box as needed.

For more information about WinPcap see {winpcap-main-url} and
{wireshark-wiki-url}WinPcap.


[[ChBuildInstallWinWiresharkCommandLine]]

==== Windows installer command line options

For special cases, there are some command line parameters available:

* `/S` runs the installer or uninstaller silently with default values. The
  silent installer *will not* install WinPCap.

* `/desktopicon` installation of the desktop icon, `=yes` - force installation,
  `=no` - don’t install, otherwise use default settings. This option can be
  useful for a silent installer.

* `/quicklaunchicon` installation of the quick launch icon, `=yes` - force
  installation, `=no` - don’t install, otherwise use default settings.

* `/D` sets the default installation directory ($INSTDIR), overriding InstallDir
  and InstallDirRegKey. It must be the last parameter used in the command line
  and must not contain any quotes even if the path contains spaces.

* `/NCRC` disables the CRC check. We recommend against using this flag.

Example:
----
> Wireshark-win64-wireshark-2.0.5.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo
----

Running the installer without any parameters shows the normal interactive installer.

[[ChBuildInstallWinPcapManually]]

==== Manual WinPcap Installation

As mentioned above, the Wireshark installer takes care of installing WinPcap.
The following is only necessary if you want to use a different version than the
one included in the Wireshark installer, e.g. because a new WinPcap version was
released.

Additional WinPcap versions (including newer alpha or beta releases) can
be downloaded from the main WinPcap site at {winpcap-main-url}. The
_Installer for Windows_ supports modern Windows operating systems.

[[ChBuildInstallWinWiresharkUpdate]]

==== Update Wireshark

By default the offical Windows package will check for new versions and notify
you when they are available. If you have the _Check for updates_ preference
disabled or if you run Wireshark in an isolated environment you should subcribe
to the _wireshark-announce_ mailing list. See <<ChIntroMailingLists>> for
details on subscribing to this list.

New versions of Wireshark are usually released every four to six weeks. Updating
Wireshark is done the same way as installing it. Simply download and start the
installer exe. A reboot is usually not required and all your personal settings
remain unchanged.

[[ChBuildInstallWinPcapUpdate]]

==== Update WinPcap

New versions of WinPcap are less frequently available. You will find
WinPcap update instructions the WinPcap web site at {winpcap-main-url}.
You may have to reboot your machine after installing a new WinPcap
version.

[[ChBuildInstallWinUninstall]]

==== Uninstall Wireshark

You can uninstall Wireshark using the _Programs and Features_ control panel.
Select the “Wireshark” entry to start the uninstallation procedure.

The Wireshark uninstaller provides several options for removal. The default is
to remove the core components but keep your personal settings and WinPcap.
WinPcap is left installed by default in case other programs need it.

[[ChBuildInstallWinPcapUninstall]]

==== Uninstall WinPcap

You can uninstall WinPcap independently of Wireshark using the _WinPcap_ entry
in the _Programs and Features_ control panel. Remember that if you uninstall
WinPcap you won’t be able to capture anything with Wireshark.

//
// macOS
//

[[ChBuildInstallOSXInstall]]

=== Installing Wireshark under macOS

The official macOS packages are distributed as disk images (.dmg) containing
the application installer. To install Wireshark simply open the disk image and
run the enclosed installer.

The installer package includes Wireshark, its related command line utilities,
and a launch daemon that adjusts capture permissions at system startup. See the
included _Read me first_ file for more details.

[[ChBuildInstallUnixBuild]]

=== Building Wireshark from source under UNIX

Building Wireshark requires the proper build environment including a
compiler and many supporting libraries. See the Developer’s Guide at
{wireshark-developers-guide-url} for more information.

Use the following general steps to build Wireshark from source under UNIX or Linux:

. Unpack the source from its compressed `tar` file. If you are using Linux or
  your version of UNIX uses GNU `tar` you can use the following command:
+
--
----
$ tar xaf wireshark-2.4.5.tar.xz
----
In other cases you will have to use the following commands:
----
$ xz -d wireshark-2.4.5.tar.xz
$ tar xf wireshark-2.4.5.tar
----
--

. Change directory to the Wireshark source directory.
+
----
$ cd wireshark-2.4.5
----

. Configure your source so it will build correctly for your version of UNIX. You
  can do this with the following command:
+
----
$ ./configure
----
+
If this step fails you will have to rectify the problems and rerun `configure`.
Troubleshooting hints are provided in <<ChBuildInstallUnixTrouble>>.

. Build the sources.
+
----
$ make
----

. Install the software in its final destination.
+
----
$ make install
----

// XXX To do: CMake

Once you have installed Wireshark with _make install_ above, you should be able
to run it by entering `wireshark`.

[[ChBuildInstallUnixInstallBins]]

=== Installing the binaries under UNIX

In general installing the binary under your version of UNIX will be specific to
the installation methods used with your version of UNIX. For example, under AIX,
you would use _smit_ to install the Wireshark binary package, while under Tru64
UNIX (formerly Digital UNIX) you would use _setld_.

==== Installing from RPMs under Red Hat and alike

Building RPMs from Wireshark’s source code results in several packages (most
distributions follow the same system):

* The `wireshark` package contains the core Wireshark libraries and command-line
  tools.

* The `wireshark` or `wireshark-qt` package contains the Qt-based GUI.

Many distributions use `yum` or a similar package management tool to make
installation of software (including its dependencies) easier.  If your
distribution uses `yum`, use the following command to install Wireshark
together with the Qt GUI:

----
yum install wireshark wireshark-qt
----

If you’ve built your own RPMs from the Wireshark sources you can install them
by running, for example:

----
rpm -ivh wireshark-2.0.0-1.x86_64.rpm wireshark-qt-2.0.0-1.x86_64.rpm
----

If the above command fails because of missing dependencies, install the
dependencies first, and then retry the step above.

==== Installing from debs under Debian, Ubuntu and other Debian derivatives

If you can just install from the repository then use

----
$ aptitude install wireshark
----

Aptitude should take care of all of the dependency issues for you.

Use the following command to install downloaded Wireshark debs under Debian:

----
$ dpkg -i wireshark-common_2.0.5.0-1_i386.deb wireshark_wireshark-2.0.5.0-1_i386.deb
----

dpkg doesn’t take care of all dependencies, but reports what’s missing.


[NOTE]
.Capturing requires privileges
====
By installing Wireshark packages non-root users won’t gain rights automatically
to capture packets. To allow non-root users to capture packets follow the
procedure described in
file:///usr/share/doc/wireshark-common/README.Debian[/usr/share/doc/wireshark-common/README.Debian]
====

==== Installing from portage under Gentoo Linux

Use the following command to install Wireshark under Gentoo Linux with all of
the extra features:

----
$ USE="c-ares ipv6 snmp ssl kerberos threads selinux" emerge wireshark
----

==== Installing from packages under FreeBSD

Use the following command to install Wireshark under FreeBSD:

----
$ pkg_add -r wireshark
----

pkg_add should take care of all of the dependency issues for you.

[[ChBuildInstallUnixTrouble]]

=== Troubleshooting during the install on Unix

A number of errors can occur during the installation process. Some hints on
solving these are provided here.

If the `configure` stage fails you will need to find out why. You can check the
file `config.log` in the source directory to find out what failed. The last few
lines of this file should help in determining the problem.

The standard problems are that you do not have a required development package on
your system or that the development package isn’t new enough. Note that
installing a library package isn’t enough. You need to install its development
package as well. `configure` will also fail if you do not have libpcap (at least
the required include files) on your system.

If you cannot determine what the problems are, send an email to the
_wireshark-dev_ mailing list explaining your problem. Include the output from
`config.log` and anything else you think is relevant such as a trace of the
`make` stage.

[[ChBuildInstallWinBuild]]

=== Building from source under Windows

We strongly recommended that you use the binary installer for Windows unless you
want to start developing Wireshark on the Windows platform.

For further information how to build Wireshark for Windows from the sources
see the Developer’s Guide at {wireshark-developers-guide-url}.

You may also want to have a look at the Development Wiki
({wireshark-wiki-url}Development) for the latest available development
documentation.

// End of WSUG Chapter 2