diff options
Diffstat (limited to 'doc/wsug_src/wsug_build_install.adoc')
| -rw-r--r-- | doc/wsug_src/wsug_build_install.adoc | 350 |
1 files changed, 350 insertions, 0 deletions
diff --git a/doc/wsug_src/wsug_build_install.adoc b/doc/wsug_src/wsug_build_install.adoc new file mode 100644 index 00000000..33035bde --- /dev/null +++ b/doc/wsug_src/wsug_build_install.adoc @@ -0,0 +1,350 @@ +// 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 version and platform. +For example, Wireshark-{wireshark-version}-x64.exe installs Wireshark {wireshark-version} for Windows on 64-bit Intel processors. +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 *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. + +* *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. + +[#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-4.2.5-x64.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo + +> Wireshark-4.2.5-x64.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]. +They are signed by *Wireshark Foundation*. +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 + |