doc/wsug_src/wsug_build_install.adoc

   1 // WSUG Chapter BuildInstall
   2
   3 [#ChapterBuildInstall]
   4
   5 == Building and Installing Wireshark
   6
   7 [#ChBuildInstallIntro]
   8
   9 === Introduction
  10
  11 As with all things there must be a beginning and so it is with Wireshark. To
  12 use Wireshark you must first install it. If you are running Windows or macOS
  13 you can download an official release at {wireshark-download-url}, install it,
  14 and skip the rest of this chapter.
  15
  16 If you are running another operating system such as Linux or FreeBSD you might
  17 want to install from source. Several Linux distributions offer Wireshark
  18 packages but they commonly provide out-of-date versions. No other versions of UNIX
  19 ship Wireshark so far. For that reason, you will need to know where to get the
  20 latest version of Wireshark and how to install it.
  21
  22 This chapter shows you how to obtain source and binary packages and how to
  23 build Wireshark from source should you choose to do so.
  24
  25 The general steps are the following:
  26
  27 . Download the relevant package for your needs, e.g., source or binary
  28   distribution.
  29
  30 . For source distributions, compile the source into a binary.
  31   This may involve building and/or installing other necessary packages.
  32
  33 . Install the binaries into their final destinations.
  34
  35 [#ChBuildInstallDistro]
  36
  37 === Obtaining the source and binary distributions
  38
  39 You can obtain both source and binary distributions from the Wireshark {wireshark-main-url}[main page] or the download page at {wireshark-download-url}.
  40 Select the package most appropriate for your system.
  41
  42 //
  43 // Windows
  44 //
  45
  46 [#ChBuildInstallWinInstall]
  47
  48 === Installing Wireshark under Windows
  49
  50 The official Windows packages can be downloaded from the Wireshark {wireshark-main-url}[main page] or the {wireshark-download-url}[download page].
  51 Installer names contain the version and platform.
  52 For example, Wireshark-{wireshark-version}-x64.exe installs Wireshark {wireshark-version} for Windows on 64-bit Intel processors.
  53 The Wireshark installer includes Npcap which is required for packet capture.
  54 Windows packages automatically update.
  55 See <<ChBuildInstallUpdatingWireshark>> for details.
  56
  57 Simply download the Wireshark installer from {wireshark-download-url} and execute it.
  58 Official packages are signed by *Wireshark Foundation*.
  59 You can choose to install several optional components and select the location of the installed package.
  60 The default settings are recommended for most users.
  61
  62 [#ChBuildInstallWinComponents]
  63
  64 ==== Installation Components
  65
  66 On the _Choose Components_ page of the installer you can select from the following:
  67
  68 * *Wireshark* - The network protocol analyzer that we all know and mostly love.
  69
  70 * *TShark* - A command-line network protocol analyzer. If you haven’t tried it
  71   you should.
  72
  73 * *External Capture (extcap)* - External Capture Interfaces
  74
  75   - *Androiddump* - Provide capture interfaces from Android devices.
  76
  77   - *Etwdump* - Provide an interface to read Event Tracing for Windows (ETW) event trace (ETL).
  78
  79   - *Randpktdump* - Provide an interface to the random packet generator. (see also randpkt)
  80
  81   - *Sshdump, Ciscodump, and Wifidump* - Provide remote capture through SSH. (tcpdump, Cisco EPC, wifi)
  82
  83   - *UDPdump* - Provide capture interface to receive UDP packets streamed from network devices.
  84
  85 [#ChBuildInstallWinAdditionalTasks]
  86
  87 ==== Additional Tasks
  88
  89 * *Wireshark Start Menu Item* - Add a shortcut to the start menu.
  90
  91 * *Wireshark Desktop Icon* - Add a Wireshark icon to the desktop.
  92
  93 * *Associate trace file extensions with Wireshark* - Associate standard network trace files to Wireshark.
  94
  95 [#ChBuildInstallWinLocation]
  96
  97 ==== Install Location
  98
  99 By default Wireshark installs into `%ProgramFiles%\Wireshark` on 32-bit Windows
 100 and `%ProgramFiles64%\Wireshark` on 64-bit Windows. This expands to `C:\Program
 101 Files\Wireshark` on most systems.
 102
 103 [#ChBuildInstallNpcap]
 104
 105 ==== Installing Npcap
 106
 107 The Wireshark installer contains the latest Npcap installer.
 108
 109 If you don’t have Npcap installed you won’t be able to capture live network
 110 traffic but you will still be able to open saved capture files. By default the
 111 latest version of Npcap will be installed. If you don’t wish to do this or if
 112 you wish to reinstall Npcap you can check the _Install Npcap_ box as needed.
 113
 114 For more information about Npcap see {npcap-main-url} and
 115 {wireshark-wiki-url}Npcap.
 116
 117
 118 [#ChBuildInstallWinWiresharkCommandLine]
 119
 120 ==== Windows installer command line options
 121
 122 For special cases, there are some command line parameters available:
 123
 124 * `/S` runs the installer or uninstaller silently with default values. The
 125   silent installer *will not* install Npcap.
 126
 127 * `/desktopicon` installation of the desktop icon, `=yes` - force installation,
 128   `=no` - don’t install, otherwise use default settings. This option can be
 129   useful for a silent installer.
 130
 131 * `/D` sets the default installation directory ($INSTDIR), overriding InstallDir
 132   and InstallDirRegKey. It must be the last parameter used in the command line
 133   and must not contain any quotes even if the path contains spaces.
 134
 135 * `/NCRC` disables the CRC check. We recommend against using this flag.
 136
 137 * `/EXTRACOMPONENTS` comma separated list of optional components to install.
 138 The following extcap binaries are supported.
 139
 140
 141 ** `androiddump` - Provide interfaces to capture from Android devices
 142
 143 ** `ciscodump` - Provide interfaces to capture from a remote Cisco router through SSH
 144
 145 ** `randpktdump` - Provide an interface to generate random captures using randpkt
 146
 147 ** `sshdump` - Provide interfaces to capture from a remote host through SSH using a remote capture binary
 148
 149 ** `udpdump` - Provide a UDP receiver that gets packets from network devices
 150
 151 Example:
 152 ----
 153 > Wireshark-4.2.5-x64.exe /NCRC /S /desktopicon=yes /D=C:\Program Files\Foo
 154
 155 > Wireshark-4.2.5-x64.exe /S /EXTRACOMPONENTS=sshdump,udpdump
 156 ----
 157
 158 Running the installer without any parameters shows the normal interactive installer.
 159
 160 [#ChBuildInstallNpcapManually]
 161
 162 ==== Manual Npcap Installation
 163
 164 As mentioned above, the Wireshark installer also installs Npcap.
 165 If you prefer to install Npcap manually or want to use a different version than the
 166 one included in the Wireshark installer, you can download Npcap from
 167 the main Npcap site at {npcap-main-url}.
 168
 169 [#ChBuildInstallNpcapUpdate]
 170
 171 ==== Update Npcap
 172
 173 Wireshark updates may also include a new version of Npcap.
 174 Manual Npcap updates instructions can be found on the Npcap web
 175 site at {npcap-main-url}. You may have to reboot your machine after installing
 176 a new Npcap version.
 177
 178 [#ChBuildInstallWinUninstall]
 179
 180 ==== Uninstall Wireshark
 181
 182 You can uninstall Wireshark using the _Programs and Features_ control panel.
 183 Select the “Wireshark” entry to start the uninstallation procedure.
 184
 185 The Wireshark uninstaller provides several options for removal. The default is
 186 to remove the core components but keep your personal settings and Npcap.
 187 Npcap is kept in case other programs need it.
 188
 189 [#ChBuildInstallNpcapUninstall]
 190
 191 ==== Uninstall Npcap
 192
 193 You can uninstall Npcap independently of Wireshark using the _Npcap_ entry
 194 in the _Programs and Features_ control panel. Remember that if you uninstall
 195 Npcap you won’t be able to capture anything with Wireshark.
 196
 197 [#ChBuildInstallWinBuild]
 198
 199 === Building from source under Windows
 200
 201 We strongly recommended using the binary installer for Windows unless you
 202 want to start developing Wireshark on the Windows platform.
 203
 204 For further information how to obtain sources and build Wireshark for Windows
 205 from the sources see the Developer’s Guide at:
 206
 207 * {wireshark-developers-guide-url}ChSrcObtain
 208
 209 * {wireshark-developers-guide-url}ChSetupWindows
 210
 211 You may also want to have a look at the Development Wiki
 212 ({wireshark-wiki-url}Development) for the latest available development
 213 documentation.
 214
 215 //
 216 // macOS
 217 //
 218
 219 [#ChBuildInstallOSXInstall]
 220
 221 === Installing Wireshark under macOS
 222
 223 The official macOS packages can be downloaded from the Wireshark {wireshark-main-url}[main page] or the {wireshark-download-url}[download page].
 224 They are signed by *Wireshark Foundation*.
 225 Packages are distributed as disk images (.dmg) containing the application bundle.
 226 Package names contain the platform and version.
 227 To install Wireshark simply open the disk image and drag _Wireshark_ to your _/Applications_ folder.
 228 macOS packages automatically update.
 229 See <<ChBuildInstallUpdatingWireshark>> for details.
 230
 231 In order to capture packets, you must install the “ChmodBPF” launch daemon.
 232 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”.
 233
 234 The installer package includes Wireshark along with ChmodBPF and system path packages.
 235 See the included _Read me first.html_ file for more details.
 236
 237 [#ChBuildInstallUnixInstallBins]
 238
 239 === Installing the binaries under UNIX
 240
 241 In general installing the binary under your version of UNIX will be specific to
 242 the installation methods used with your version of UNIX. For example, under AIX,
 243 you would use _smit_ to install the Wireshark binary package, while under Tru64
 244 UNIX (formerly Digital UNIX) you would use _setld_.
 245
 246 ==== Installing from RPMs under Red Hat and alike
 247
 248 Building RPMs from Wireshark’s source code results in several packages (most
 249 distributions follow the same system):
 250
 251 * The `wireshark` package contains the core Wireshark libraries and command-line
 252   tools.
 253
 254 * The `wireshark` or `wireshark-qt` package contains the Qt-based GUI.
 255
 256 Many distributions use `yum` or a similar package management tool to make
 257 installation of software (including its dependencies) easier.  If your
 258 distribution uses `yum`, use the following command to install Wireshark
 259 together with the Qt GUI:
 260
 261 ----
 262 yum install wireshark wireshark-qt
 263 ----
 264
 265 If you’ve built your own RPMs from the Wireshark sources you can install them
 266 by running, for example:
 267
 268 ----
 269 rpm -ivh wireshark-2.0.0-1.x86_64.rpm wireshark-qt-2.0.0-1.x86_64.rpm
 270 ----
 271
 272 If the above command fails because of missing dependencies, install the
 273 dependencies first, and then retry the step above.
 274
 275 ==== Installing from debs under Debian, Ubuntu and other Debian derivatives
 276
 277 If you can just install from the repository then use
 278
 279 ----
 280 apt install wireshark
 281 ----
 282
 283 Apt should take care of all of the dependency issues for you.
 284
 285 [NOTE]
 286 .Capturing requires privileges
 287 ====
 288 By installing Wireshark packages non-root, users won’t gain rights automatically
 289 to capture packets. To allow non-root users to capture packets follow the
 290 procedure described in {wireshark-code-file-url}packaging/debian/README.Debian
 291 (file:///usr/share/doc/wireshark-common/README.Debian.gz[/usr/share/doc/wireshark-common/README.Debian.gz])
 292 ====
 293
 294 ==== Installing from portage under Gentoo Linux
 295
 296 Use the following command to install Wireshark under Gentoo Linux with all of
 297 the extra features:
 298
 299 ----
 300 USE="c-ares ipv6 snmp ssl kerberos threads selinux" emerge wireshark
 301 ----
 302
 303 ==== Installing from packages under FreeBSD
 304
 305 Use the following command to install Wireshark under FreeBSD:
 306
 307 ----
 308 pkg_add -r wireshark
 309 ----
 310
 311 pkg_add should take care of all of the dependency issues for you.
 312
 313 [#ChBuildInstallUnixBuild]
 314
 315 === Building from source under UNIX or Linux
 316
 317 We recommended using the binary installer for your platform unless you
 318 want to start developing Wireshark.
 319
 320 Building Wireshark requires the proper build environment including a
 321 compiler and many supporting libraries. For more information, see the Developer’s Guide at:
 322
 323 * {wireshark-developers-guide-url}ChSrcObtain
 324
 325 * {wireshark-developers-guide-url}ChapterSetup#ChSetupUNIX
 326
 327 [#ChBuildInstallUpdatingWireshark]
 328
 329 === Updating Wireshark
 330
 331 By default, Wireshark on Windows and macOS will check for new versions and notify you when they are available.
 332 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.
 333 See <<ChIntroMailingLists>> for details on subscribing to this list.
 334
 335 New versions of Wireshark are usually released every four to six weeks.
 336 Updating Wireshark is done the same way as installing it.
 337 Simply download and run the installer on Windows, or download and drag the application on macOS.
 338 A reboot is usually not required and all your personal settings will remain unchanged.
 339
 340 We offer two update channels, _Stable_ and _Development_.
 341 The Stable channel is the default, and only installs packages from stable (even-numbered) release branches.
 342 The Development channel installs development and release candidate packages when they are available, and stable releases otherwise.
 343 To configure your release channel, go to menu:Preferences[Advanced] and search for “update.channel”.
 344 See <<ChCustPreferencesSection>> for details.
 345
 346 // End of WSUG ChapterBuildInstall
 347