docbook/wsug_src/WSUG_chapter_build_install.asciidoc

   1 ++++++++++++++++++++++++++++++++++++++
   2 <!-- WSUG Chapter BuildInstall -->
   3 ++++++++++++++++++++++++++++++++++++++
   4
   5 [[ChapterBuildInstall]]
   6
   7 == Building and Installing Wireshark
   8
   9 [[ChBuildInstallIntro]]
  10
  11 === Introduction
  12
  13 As with all things there must be a beginning and so it is with Wireshark. To
  14 use Wireshark you must first install it. If you are running Windows or OS X
  15 you can download an official release at {wireshark-download-url}, install it,
  16 and skip the rest of this chapter.
  17
  18 If you are running another operating system such as Linux or FreeBSD you might
  19 want to install from source. Several Linux distributions offer Wireshark
  20 packages but they commonly ship out-of-date versions. No other versions of UNIX
  21 ship Wireshark so far. For that reason, you will need to know where to get the
  22 latest version of Wireshark and how to install it.
  23
  24 This chapter shows you how to obtain source and binary packages and how to
  25 build Wireshark from source should you choose to do so.
  26
  27 The following are the general steps you would use:
  28
  29 . Download the relevant package for your needs, e.g. source or binary
  30   distribution.
  31
  32 . Compile the source into a binary if needed.
  33   This may involve building and/or installing other necessary packages.
  34
  35 . Install the binaries into their final destinations.
  36
  37 [[ChBuildInstallDistro]]
  38
  39 === Obtaining the source and binary distributions
  40
  41 You can obtain both source and binary distributions from the Wireshark
  42 web site: {wireshark-download-url}. Select the download link and then
  43 select the desired binary or source package.
  44
  45 [NOTE]
  46 .Download all required files
  47 ====
  48 If you are building Wireshark from source you will
  49 In general, unless you have already downloaded Wireshark before, you will most
  50 likely need to download several source packages if you are building Wireshark
  51 from source. This is covered in more detail below.
  52
  53 ++++++++++++++++++++++++++++++++++++++
  54 <!-- Make a ref -->
  55 ++++++++++++++++++++++++++++++++++++++
  56 ====
  57
  58 Once you have downloaded the relevant files, you can go on to the next step.
  59
  60 //
  61 // Windows
  62 //
  63
  64 [[ChBuildInstallWinInstall]]
  65
  66 === Installing Wireshark under Windows
  67
  68 Windows installer names contain the platform and version. For example,
  69 Wireshark-win64-{wireshark-version}.exe installs Wireshark {wireshark-version}
  70 for 64-bit Windows. The Wireshark installer includes WinPcap which is required
  71 for packet capture.
  72
  73 Simply download the Wireshark installer from {wireshark-download-url}
  74 and execute it. Official packages are signed by the *Wireshark
  75 Foundation*. You can choose to install several optional components and
  76 select the location of the installed package. The default settings are
  77 recommended for most users.
  78
  79 [[ChBuildInstallWinComponents]]
  80
  81 ==== Installation Components
  82
  83 On the _Choose Components_ page of the installer you can select from the following:
  84
  85 * *Wireshark* - The network protocol analyzer that we all know and mostly love.
  86
  87 * *TShark* - A command-line network protocol analyzer. If you haven't tried it
  88   you should.
  89
  90 * *Wireshark 1 Legacy* - The old (GTK+) user interface in case you need it.
  91
  92 * *Plugins &amp; Extensions* - Extras for the Wireshark and TShark dissection engines
  93
  94   - *Dissector Plugins* - Plugins with some extended dissections.
  95
  96   - *Tree Statistics Plugins* - Extended statistics.
  97
  98   - *Mate - Meta Analysis and Tracing Engine* - User configurable extension(s) of the display filter engine, see {wireshark-wiki-url}Mate for details.
  99
 100   - *SNMP MIBs* - SNMP MIBs for a more detailed SNMP dissection.
 101
 102 * *Tools* - Additional command line tools to work with capture files
 103
 104   - *Editcap* - Reads a capture file and writes some or all of the packets into
 105     another capture file.
 106
 107   - *Text2Pcap* - Reads in an ASCII hex dump and writes the data into a
 108     pcap capture file.
 109
 110   - *Reordercap* - Reorders a capture file by timestamp.
 111
 112   - *Mergecap* - Combines multiple saved capture files into a single output file.
 113
 114   - *Capinfos* - Provides information on capture files.
 115
 116   - *Rawshark* - Raw packet filter.
 117
 118 * *User's Guide* - Local installation of the User's Guide. The Help buttons on
 119   most dialogs will require an internet connection to show help pages if the
 120   User's Guide is not installed locally.
 121
 122 [[ChBuildInstallWinAdditionalTasks]]
 123
 124 ==== Additional Tasks
 125
 126 * *Start Menu Shortcuts* - Add some start menu shortcuts.
 127
 128 * *Desktop Icon* - Add a Wireshark icon to the desktop.
 129
 130 * *Quick Launch Icon* - add a Wireshark icon to the Explorer quick launch toolbar.
 131
 132 * *Associate file extensions to Wireshark* - Associate standard network trace files to Wireshark.
 133
 134 [[ChBuildInstallWinLocation]]
 135
 136 ==== Install Location
 137
 138 By default Wireshark installs into `%ProgramFiles%\Wireshark` on 32-bit Windows
 139 and `%ProgramFiles64%\Wireshark` on 64-bit Windows. This expands to `C:\Program
 140 Files\Wireshark` on most systems.
 141
 142 [[ChBuildInstallWinPcap]]
 143
 144 ==== Installing WinPcap
 145
 146 The Wireshark installer contains the latest WinPcap installer.
 147
 148 If you don't have WinPcap installed you won't be able to capture live network
 149 traffic but you will still be able to open saved capture files. By default the
 150 latest version of WinPcap will be installed. If you don't wish to do this or if
 151 you wish to reinstall WinPcap you can check the _Install WinPcap_ box as needed.
 152
 153 For more information about WinPcap see {winpcap-main-url} and
 154 {wireshark-wiki-url}WinPcap.
 155
 156
 157 [[ChBuildInstallWinWiresharkCommandLine]]
 158
 159 ==== Windows installer command line options
 160
 161 For special cases, there are some command line parameters available:
 162
 163 * `/S` runs the installer or uninstaller silently with default values. The
 164   silent installer *will not* install WinPCap.
 165
 166 * `/desktopicon` installation of the desktop icon, `=yes` - force installation,
 167   `=no` - don't install, otherwise use default settings. This option can be
 168   useful for a silent installer.
 169
 170 * `/quicklaunchicon` installation of the quick launch icon, `=yes` - force
 171   installation, `=no` - don't install, otherwise use default settings.
 172
 173 * `/D` sets the default installation directory ($INSTDIR), overriding InstallDir
 174   and InstallDirRegKey. It must be the last parameter used in the command line
 175   and must not contain any quotes even if the path contains spaces.
 176
 177 * `/NCRC` disables the CRC check. We recommend against using this flag.
 178
 179 Example:
 180 ----
 181 > Wireshark-win64-wireshark-2.0.5.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo
 182 ----
 183
 184 Running the installer without any parameters shows the normal interactive installer.
 185
 186 [[ChBuildInstallWinPcapManually]]
 187
 188 ==== Manual WinPcap Installation
 189
 190 As mentioned above, the Wireshark installer takes care of installing WinPcap.
 191 The following is only necessary if you want to use a different version than the
 192 one included in the Wireshark installer, e.g. because a new WinPcap version was
 193 released.
 194
 195 Additional WinPcap versions (including newer alpha or beta releases) can
 196 be downloaded from the main WinPcap site at {winpcap-main-url}. The
 197 _Installer for Windows_ supports modern Windows operating systems.
 198
 199 [[ChBuildInstallWinWiresharkUpdate]]
 200
 201 ==== Update Wireshark
 202
 203 By default the offical Windows package will check for new versions and notify
 204 you when they are available. If you have the _Check for updates_ preference
 205 disabled or if you run Wireshark in an isolated environment you should subcribe
 206 to the _wireshark-announce_ mailing list. See <<ChIntroMailingLists>> for
 207 details on subscribing to this list.
 208
 209 New versions of Wireshark are usually released every four to six weeks. Updating
 210 Wireshark is done the same way as installing it. Simply download and start the
 211 installer exe. A reboot is usually not required and all your personal settings
 212 remain unchanged.
 213
 214 [[ChBuildInstallWinPcapUpdate]]
 215
 216 ==== Update WinPcap
 217
 218 New versions of WinPcap are less frequently available. You will find
 219 WinPcap update instructions the WinPcap web site at {winpcap-main-url}.
 220 You may have to reboot your machine after installing a new WinPcap
 221 version.
 222
 223 [[ChBuildInstallWinUninstall]]
 224
 225 ==== Uninstall Wireshark
 226
 227 You can uninstall Wireshark using the _Programs and Features_ control panel.
 228 Select the "Wireshark" entry to start the uninstallation procedure.
 229
 230 The Wireshark uninstaller provides several options for removal. The default is
 231 to remove the core components but keep your personal settings and WinPcap.
 232 WinPcap is left installed by default in case other programs need it.
 233
 234 [[ChBuildInstallWinPcapUninstall]]
 235
 236 ==== Uninstall WinPcap
 237
 238 You can uninstall WinPcap independently of Wireshark using the _WinPcap_ entry
 239 in the _Programs and Features_ control panel. Remember that if you uninstall
 240 WinPcap you won't be able to capture anything with Wireshark.
 241
 242 //
 243 // OS X
 244 //
 245
 246 [[ChBuildInstallOSXInstall]]
 247
 248 === Installing Wireshark under OS X
 249
 250 The official OS X packages are distributed as disk images (.dmg) containing
 251 the application installer. To install Wireshark simply open the disk image and
 252 run the enclosed installer.
 253
 254 The installer package includes Wireshark, its related command line utilities,
 255 and a launch daemon that adjusts capture permissions at system startup. See the
 256 included _Read me first_ file for more details.
 257
 258 [[ChBuildInstallUnixBuild]]
 259
 260 === Building Wireshark from source under UNIX
 261
 262 Building Wireshark requires the proper build environment including a
 263 compiler and many supporting libraries. See the Developer's Guide at
 264 {wireshark-developers-guide-url} for more information.
 265
 266 Use the following general steps to build Wireshark from source under UNIX or Linux:
 267
 268 . Unpack the source from its compressed `tar` file. If you are using Linux or
 269   your version of UNIX uses GNU `tar` you can use the following command:
 270 +
 271 --
 272 ----
 273 $ tar xaf wireshark-2.4.5.tar.xz
 274 ----
 275 In other cases you will have to use the following commands:
 276 ----
 277 $ xz -d wireshark-2.4.5.tar.xz
 278 $ tar xf wireshark-2.4.5.tar
 279 ----
 280 --
 281
 282 . Change directory to the Wireshark source directory.
 283 +
 284 ----
 285 $ cd wireshark-2.4.5
 286 ----
 287
 288 . Configure your source so it will build correctly for your version of UNIX. You
 289   can do this with the following command:
 290 +
 291 ----
 292 $ ./configure
 293 ----
 294 +
 295 If this step fails you will have to rectify the problems and rerun `configure`.
 296 Troubleshooting hints are provided in <<ChBuildInstallUnixTrouble>>.
 297
 298 . Build the sources.
 299 +
 300 ----
 301 $ make
 302 ----
 303
 304 . Install the software in its final destination.
 305 +
 306 ----
 307 $ make install
 308 ----
 309
 310 // XXX To do: CMake
 311
 312 Once you have installed Wireshark with _make install_ above, you should be able
 313 to run it by entering `wireshark`.
 314
 315 [[ChBuildInstallUnixInstallBins]]
 316
 317 === Installing the binaries under UNIX
 318
 319 In general installing the binary under your version of UNIX will be specific to
 320 the installation methods used with your version of UNIX. For example, under AIX,
 321 you would use _smit_ to install the Wireshark binary package, while under Tru64
 322 UNIX (formerly Digital UNIX) you would use _setld_.
 323
 324 ==== Installing from RPM's under Red Hat and alike
 325
 326 Building RPMs from Wireshark's source code results in several packages (most
 327 distributions follow the same system):
 328
 329 * The `wireshark` package contains the core Wireshark libraries and command-line
 330   tools.
 331
 332 * The `wireshark-qt` package contains the Qt-based GUI.
 333
 334 * The `wireshark-gtk` (formerly `wireshark-gnome`) package contains the legacy
 335 Gtk+ based GUI.
 336
 337 Many distributions use `yum` or a similar package management tool to make
 338 installation of software (including its dependencies) easier.  If your
 339 distribution uses `yum`, use the following command to install Wireshark
 340 together with the Qt GUI:
 341
 342 ----
 343 yum install wireshark wireshark-qt
 344 ----
 345
 346 If you've built your own RPMs from the Wireshark sources you can install them
 347 by running, for example:
 348
 349 ----
 350 rpm -ivh wireshark-2.0.0-1.x86_64.rpm wireshark-qt-2.0.0-1.x86_64.rpm
 351 ----
 352
 353 If the above command fails because of missing dependencies, install the
 354 dependencies first, and then retry the step above.
 355
 356 ==== Installing from deb's under Debian, Ubuntu and other Debian derivatives
 357
 358 If you can just install from the repository then use
 359
 360 ----
 361 $ aptitude install wireshark
 362 ----
 363
 364 Aptitude should take care of all of the dependency issues for you.
 365
 366 Use the following command to install downloaded Wireshark deb's under Debian:
 367
 368 ----
 369 $ dpkg -i wireshark-common_2.0.5.0-1_i386.deb wireshark_wireshark-2.0.5.0-1_i386.deb
 370 ----
 371
 372 dpkg doesn't take care of all dependencies, but reports what's missing.
 373
 374
 375 [NOTE]
 376 .Capturing requires privileges
 377 ====
 378 By installing Wireshark packages non-root users won't gain rights automatically
 379 to capture packets. To allow non-root users to capture packets follow the
 380 procedure described in
 381 file:///usr/share/doc/wireshark-common/README.Debian[/usr/share/doc/wireshark-common/README.Debian]
 382 ====
 383
 384 ==== Installing from portage under Gentoo Linux
 385
 386 Use the following command to install Wireshark under Gentoo Linux with all of
 387 the extra features:
 388
 389 ----
 390 $ USE="c-ares gtk ipv6 portaudio snmp ssl kerberos threads selinux" emerge wireshark
 391 ----
 392
 393 ==== Installing from packages under FreeBSD
 394
 395 Use the following command to install Wireshark under FreeBSD:
 396
 397 ----
 398 $ pkg_add -r wireshark
 399 ----
 400
 401 pkg_add should take care of all of the dependency issues for you.
 402
 403 [[ChBuildInstallUnixTrouble]]
 404
 405 === Troubleshooting during the install on Unix
 406
 407 A number of errors can occur during the installation process. Some hints on
 408 solving these are provided here.
 409
 410 If the `configure` stage fails you will need to find out why. You can check the
 411 file `config.log` in the source directory to find out what failed. The last few
 412 lines of this file should help in determining the problem.
 413
 414 The standard problems are that you do not have a required development package on
 415 your system or that the development package isn't new enough. Note that
 416 installing a library package isn't enough. You need to install its development
 417 package as well. `configure` will also fail if you do not have libpcap (at least
 418 the required include files) on your system.
 419
 420 If you cannot determine what the problems are, send an email to the
 421 _wireshark-dev_ mailing list explaining your problem. Include the output from
 422 `config.log` and anything else you think is relevant such as a trace of the
 423 `make` stage.
 424
 425 [[ChBuildInstallWinBuild]]
 426
 427 === Building from source under Windows
 428
 429 We strongly recommended that you use the binary installer for Windows unless you
 430 want to start developing Wireshark on the Windows platform.
 431
 432 For further information how to build Wireshark for Windows from the sources
 433 see the Developer's Guide at {wireshark-developers-guide-url}.
 434
 435 You may also want to have a look at the Development Wiki
 436 ({wireshark-wiki-url}Development) for the latest available development
 437 documentation.
 438
 439 ++++++++++++++++++++++++++++++++++++++
 440 <!-- End of WSUG Chapter 2 -->
 441 ++++++++++++++++++++++++++++++++++++++
 442