wireshark/docbook/wsug_src/WSUG_chapter_build_install.adoc

// 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 provide 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 general steps are the following:

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

. For source distributions, compile the source into a binary.
  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 {wireshark-main-url}[main page] or the download page at {wireshark-download-url}.
Select the package most appropriate for your system.

//
// Windows
//

[#ChBuildInstallWinInstall]

=== Installing Wireshark under Windows

The official Windows packages can be downloaded from the Wireshark {wireshark-main-url}[main page] or the {wireshark-download-url}[download page].
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 Npcap which is required for packet capture.
Windows packages automatically update.
See <<ChBuildInstallUpdatingWireshark>> for details.

Simply download the Wireshark installer from {wireshark-download-url} and execute it.
Official packages are signed by *Sysdig, Inc.*.
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 &amp; Extensions* - Extras for the Wireshark and TShark dissection engines

  - *Codec Plugins* - Additional codec support.

  - *Configuration Profiles* - Additional configuration profiles.

  - *Dissector Plugins* - Additional protocol dissectors.

  - *File Type Plugins - capture file support* - Extend wiretap support for capture file types. (e.g. usbdump)

  - *Mate - Meta Analysis and Tracing Engine* - User configurable extension(s)
    of the display filter engine, see <<ChMate>> for details.

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

  - *TRANSUM - performance analysis* - Plugin to calculate Response Time Element (RTE) statistics.

  - *Tree Statistics Plugin* - Extended statistics. (see stats_tree in WSDG; Packet Lengths in WSUG)

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

  - *Capinfos* - Print information about capture files.

  - *Captype* - Print the type(format) of capture files.

  - *DFTest* - Show display filter byte-code, for debugging dfilter routines.

  - *Editcap* - Copy packets to a new file, optionally trimming packets, omitting them,
  or saving to a different format.

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

  - *MMDBResolve* - MaxMind Database resolution tool - read IPv4 and IPv6 addresses and
  print their IP geolocation information.

  - *Randpkt* - Create a pcap trace file full of random packets. (randpkt produces very bad packets)

  - *Rawshark* - Dump and analyze raw pcap data.

  - *Reordercap* - Copy packets to a new file, sorted by time.

  - *Text2Pcap* - Generate a capture file from an ASCII hexdump of packets.

* *External Capture (extcap)* - External Capture Interfaces

  - *Androiddump* - Provide capture interfaces from Android devices.

  - *Etwdump* - Provide an interface to read Event Tracing for Windows (ETW) event trace (ETL).

  - *Randpktdump* - Provide an interface to the random packet generator. (see also randpkt)

  - *Sshdump, Ciscodump, and Wifidump* - Provide remote capture through SSH. (tcpdump, Cisco EPC, wifi)

  - *UDPdump* - Provide capture interface to receive UDP packets streamed from network devices.

* *Documentation* - Local installation of the User’s Guide and FAQ. 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

* *Wireshark Start Menu Item* - Add a shortcut to the start menu.

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

* *Associate trace file extensions with 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.

[#ChBuildInstallNpcap]

==== Installing Npcap

The Wireshark installer contains the latest Npcap installer.

If you don’t have Npcap 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 Npcap will be installed. If you don’t wish to do this or if
you wish to reinstall Npcap you can check the _Install Npcap_ box as needed.

For more information about Npcap see {npcap-main-url} and
{wireshark-wiki-url}Npcap.


[#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 Npcap.

* `/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.

* `/EXTRACOMPONENTS` comma separated list of optional components to install.
The following extcap binaries are supported.


** `androiddump` - Provide interfaces to capture from Android devices

** `ciscodump` - Provide interfaces to capture from a remote Cisco router through SSH

** `randpktdump` - Provide an interface to generate random captures using randpkt

** `sshdump` - Provide interfaces to capture from a remote host through SSH using a remote capture binary

** `udpdump` - Provide a UDP receiver that gets packets from network devices

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

> Wireshark-win64-3.3.0.exe /S /EXTRACOMPONENTS=sshdump,udpdump
----

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

[#ChBuildInstallNpcapManually]

==== Manual Npcap Installation

As mentioned above, the Wireshark installer also installs Npcap.
If you prefer to install Npcap manually or want to use a different version than the
one included in the Wireshark installer, you can download Npcap from
the main Npcap site at {npcap-main-url}.

[#ChBuildInstallNpcapUpdate]

==== Update Npcap

Wireshark updates may also include a new version of Npcap.
Manual Npcap updates instructions can be found on the Npcap web
site at {npcap-main-url}. You may have to reboot your machine after installing
a new Npcap 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 Npcap.
Npcap is kept in case other programs need it.

[#ChBuildInstallNpcapUninstall]

==== Uninstall Npcap

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

[#ChBuildInstallWinBuild]

=== Building from source under Windows

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

For further information how to obtain sources and build Wireshark for Windows
from the sources see the Developer’s Guide at:

* {wireshark-developers-guide-url}ChSrcObtain

* {wireshark-developers-guide-url}ChSetupWindows

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

//
// macOS
//

[#ChBuildInstallOSXInstall]

=== Installing Wireshark under macOS

The official macOS packages can be downloaded from the Wireshark {wireshark-main-url}[main page] or the {wireshark-download-url}[download page].
Packages are distributed as disk images (.dmg) containing the application bundle.
Package names contain the platform and version.
To install Wireshark simply open the disk image and drag _Wireshark_ to your _/Applications_ folder.
macOS packages automatically update.
See <<ChBuildInstallUpdatingWireshark>> for details.

In order to capture packets, you must install the “ChmodBPF” launch daemon.
You can do so by opening the _Install ChmodBPF.pkg_ file in the Wireshark .dmg or from Wireshark itself by opening menu:Wireshark[About Wireshark] selecting the “Folders” tab, and double-clicking “macOS Extras”.

The installer package includes Wireshark along with ChmodBPF and system path packages.
See the included _Read me first.html_ file for more details.

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

----
apt install wireshark
----

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

[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 {wireshark-code-file-url}packaging/debian/README.Debian
(file:///usr/share/doc/wireshark-common/README.Debian.gz[/usr/share/doc/wireshark-common/README.Debian.gz])
====

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

[#ChBuildInstallUnixBuild]

=== Building from source under UNIX or Linux

We recommended using the binary installer for your platform unless you
want to start developing Wireshark.

Building Wireshark requires the proper build environment including a
compiler and many supporting libraries. For more information, see the Developer’s Guide at:

* {wireshark-developers-guide-url}ChSrcObtain

* {wireshark-developers-guide-url}ChapterSetup#ChSetupUNIX

[#ChBuildInstallUpdatingWireshark]

=== Updating Wireshark

By default, Wireshark on Windows and macOS 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 subscribe to the _wireshark-announce_ mailing list to be notified of new versions.
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 run the installer on Windows, or download and drag the application on macOS.
A reboot is usually not required and all your personal settings will remain unchanged.

We offer two update channels, _Stable_ and _Development_.
The Stable channel is the default, and only installs packages from stable (even-numbered) release branches.
The Development channel installs development and release candidate packages when they are available, and stable releases otherwise.
To configure your release channel, go to menu:Preferences[Advanced] and search for “update.channel”.
See <<ChCustPreferencesSection>> for details.

// End of WSUG ChapterBuildInstall