path: root/docbook/wsug_src/WSUG_chapter_build_install.xml

<!-- WSUG Chapter BuildInstall -->
<!-- $Id$ -->

<chapter id="ChapterBuildInstall">
  <title>Building and Installing Wireshark</title>
  <section id="ChBuildInstallIntro">
    <title>Introduction</title>
    <para>
      As with all things, there must be a beginning, and so it is with 
      Wireshark. To use Wireshark, you must:
      <itemizedlist>
	<listitem>
	  <para>
	    Obtain a binary package for your operating system, or
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Obtain the source and build Wireshark for your operating system.
	  </para>
	</listitem>
      </itemizedlist>
    </para>
    <para>
      Currently, only two or three Linux distributions ship Wireshark, and 
      they are commonly shipping an out-of-date version.  No other versions 
      of UNIX ship Wireshark so far, and Microsoft does not ship it with any 
      version of Windows.  For that reason, you will need to know where to 
      get the latest version of Wireshark and how to install it.
    </para>
    <para>
      This chapter shows you how to obtain source and binary packages, 
      and how to build Wireshark from source, should you choose to do so.
    </para>
    <para>
      The following are the general steps you would use:
      <orderedlist>
	<listitem>
	  <para>
	    Download the relevant package for your needs, e.g. source or 
	    binary distribution.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Build the source into a binary, if you have downloaded the 
	    source.
	  </para>
	  <para>
	    This may involve building and/or installing other necessary packages.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Install the binaries into their final destinations.
	  </para>
	</listitem>
      </orderedlist>
    </para>
  </section>
  
  <section id="ChBuildInstallDistro">
    <title>Obtaining the source and binary distributions</title>
    <para>
      You can obtain both source and binary distributions from the Wireshark 
      web site: <ulink url="&WiresharkWebSite;">&WiresharkWebSite;</ulink>. 
      Simply select the download link, and then select either the source 
      package or binary package of your choice from the mirror site closest 
      to you.
    </para>
    <note>
      <title>Download all required files!</title>
      <para>
	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 -->
      </para>
    </note>
    <para>
      Once you have downloaded the relevant files, you can go on to the 
      next step.
    </para>
    <note>
      <title>Note!</title>
      <para>
	While you will find a number of binary packages available on the 
	Wireshark web site, you might not find one for your platform, and 
	they often tend to be several versions behind the current released 
	version, as they are contributed by people who have the platforms 
	they are built for.
      </para>
      <para>
	For this reason, you might want to pull down the source distribution 
	and build it, as the process is relatively simple.
      </para>
    </note>
  </section>
  
  <section id="ChBuildInstallBeforeBuild">
    <title>Before you build <application>Wireshark</application> under UNIX</title>
    <para>
      Before you build Wireshark from sources, or install a binary package, 
      you must ensure that you have the following other packages installed:
      <itemizedlist>
	<listitem>
	  <para>GTK+, The GIMP Tool Kit.</para>
	  <para>
	    You will also need Glib.  Both can be obtained from 
	    <ulink url="http://www.gtk.org">www.gtk.org</ulink>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    libpcap, the packet capture software that Wireshark uses.
	  </para>
	  <para>
	    You can obtain libpcap from 
	    <ulink url="http://www.tcpdump.org">www.tcpdump.org</ulink>
	  </para>
	</listitem>
      </itemizedlist>
      Depending on your system, you may be able to install these from 
      binaries, e.g. RPMs, or you may need to obtain them in source code 
      form and build them.
    </para>
    <para>
      If you have downloaded the source for GTK+, the instructions shown 
      in <xref linkend="Ch02Ex1"/> may provide some help in building it:
	<example id="Ch02Ex1">
	  <title>Building GTK+ from source</title>
	  <programlisting>
gzip -dc gtk+-1.2.10.tar.gz | tar xvf -
&lt;much output removed>
cd gtk+-1.2.10
./configure
&lt;much output removed>
make
&lt;much output removed>
make install
&lt;much output removed>
	  </programlisting>
	</example>
	<note>
	  <title>Note!</title>
	  <para>
	    You may need to change the version number of gtk+ in 
	    <xref linkend="Ch02Ex1"/> to match the version of GTK+ you have 
	      downloaded. The directory you change to will change if the 
	      version of GTK+ changes, and in all cases, 
	      <command>tar xvf -</command> will show you the name of the 
	      directory you should change to.
	  </para>
	</note>
	<note>
	  <title>Note!</title>
	  <para>
	    If you use Linux, or have GNU <command>tar</command> installed, 
	    you can use <command>tar zxvf gtk+-1.2.10.tar.gz</command>. It 
	    is also possible to use <command>gunzip -c</command> or 
	    <command>gzcat</command> rather than <command>gzip -dc</command> 
	    on many UNIX systems.
	  </para>
	</note>
	<note>
	  <title>Note!</title>
	  <para>
	    If you downloaded gtk+ or any other tar file using Windows, 
	    you may find your file called gtk+-1_2_8_tar.gz.
	  </para>
	</note>
    </para>
    <para>
      You should consult the GTK+ web site if any errors occur in carrying 
      out the instructions in <xref linkend="Ch02Ex1"/>.
    </para>
    <para>
      If you have downloaded the source to libpcap, the general instructions 
      shown in <xref linkend="Ch2Ex2"/>  will assist in building it. Also, 
	if your operating system does not support <command>tcpdump</command>, 
	you might also want to download it from the 
	<ulink url="http://www.tcpdump.org">tcpdump</ulink> web site and 
	install it.
	<example id="Ch2Ex2">
	  <title>Building and installing libpcap</title>
	  <programlisting>
gzip -dc libpcap-0.8.3.tar.Z | tar xvf -
&lt;much output removed>
cd libpcap_0_8_3
./configure
&lt;much output removed>
make
&lt;much output removed>
make install
&lt;much output removed>
make install-incl
&lt;much output removed>
	    </programlisting>
	</example>
    </para>
    <note>
      <title>Note!</title>
      <para>
	The directory you should change to will depend on the version of 
	libpcap you have downloaded.  In all cases, 
	<command>tar xvf -</command> will show you the name of the 
	directory that has been unpacked.
      </para>
    </note>
    <para>
      When installing the include files, you might get the error shown 
      in <xref linkend="Ch02Ex3"/> when you submit the command 
	<command>make install-incl</command>.
	<example id="Ch02Ex3">
	  <title>Errors while installing the libpcap include files</title>
	  <programlisting>
/usr/local/include/pcap.h
/usr/bin/install -c -m 444 -o bin -g bin ./pcap-namedb.h \
/usr/local/include/pcap-namedb.h
/usr/bin/install -c -m 444 -o bin -g bin ./net/bpf.h \
/usr/local/include/net/bpf.h
/usr/bin/install: cannot create regular file \
`/usr/local/include/net/bpf.h': No such file or directory
make: *** [install-incl] Error 1
	  </programlisting>
	</example>
	If you do, simply create the missing directory with the following 
	command:
	<programlisting>
mkdir /usr/local/include/net
	</programlisting>
	and rerun the command <command>make install-incl</command>.
    </para>
    <para>
      Under RedHat 6.x and beyond (and distributions based on it, like 
      Mandrake) you can simply install each of the packages you need from 
      RPMs. Most Linux systems will install GTK+ and GLib in anycase, 
      however, you will probably need to install the devel versions of 
      each of these packages. The commands shown in <xref linkend="Ch02Ex4"/> 
	will install all the needed RPMs if they are not already installed.
	<example id="Ch02Ex4">
	  <title>
	    Installing required RPMs under RedHat Linux 6.2 and beyond
	  </title>
	  <programlisting>
cd /mnt/cdrom/RedHat/RPMS
rpm -ivh glib-1.2.6-3.i386.rpm
rpm -ivh glib-devel-1.2.6-3.i386.rpm
rpm -ivh gtk+-1.2.6-7.i386.rpm
rpm -ivh gtk+-devel-1.2.6-7.i386.rpm
rpm -ivh libpcap-0.4-19.i386.rpm
	  </programlisting>
	</example>
    </para>
    <note>
      <para>
	If you are using a version of RedHat later than 6.2, the required 
	RPMs have most likely changed. Simply use the correct RPMs from your 
	distribution.
      </para>
    </note>
    <para> 
      Under Debian you can install Wireshark using apt-get.  apt-get will
      handle any dependency issues for you. <xref linkend="Ch02Ex5"/> shows 
	how to do this.
	<example id="Ch02Ex5">
	  <title>Installing debs under Debian</title>
	  <programlisting>
apt-get install ethereal
	  </programlisting>
	</example>
    </para>
  </section>
  
  <section id="ChBuildInstallUnixBuild">
    <title>Building Wireshark from source under UNIX</title>
    <para>
      Use the following general steps if you are building Wireshark from 
      source under a UNIX operating system:
      <orderedlist>
	<listitem>
	  <para>
	    Unpack the source from its <command>gzip</command>'d 
	    <command>tar</command> file. If you are using Linux, or your 
	    version of UNIX uses GNU <command>tar</command>, you can use the 
	    following command:
	    <programlisting>
tar zxvf ethereal-&WiresharkCurrentVersion;-tar.gz
	    </programlisting>
	  </para>
	  <para>
	    For other versions of UNIX, You will want to use the following 
	    commands:
	    <programlisting>
gzip -d ethereal-&WiresharkCurrentVersion;-tar.gz
tar xvf ethereal-&WiresharkCurrentVersion;-tar
	    </programlisting>
	    <note>
	      <title>Note!</title>
	      <para>
		The pipeline 
		<command>
		  gzip -dc ethereal-&WiresharkCurrentVersion;-tar.gz | tar xvf -
		</command> will work here as well.
	      </para>
	    </note>
	    <note>
	      <title>Note!</title>
	      <para>
		If you have downloaded the Wireshark tarball under Windows, 
		you may find that your browser has created a file with 
		underscores rather than periods in its file name.
	      </para>
	    </note>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Change directory to the Wireshark source directory.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Configure your source so it will build correctly for your 
	    version of UNIX.  You can do this with the following command:
	    <programlisting>
./configure
	    </programlisting>
	  </para>
	  <para>
	    If this step fails, you will have to rectify the problems and 
	    rerun <command>configure</command>.  Troubleshooting hints are 
	    provided in <xref linkend="ChBuildInstallUnixTrouble"/>.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Build the sources into a binary, with the <command>make</command> 
	    command.  For example:
	    <programlisting>
make
	    </programlisting>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Install the software in its final destination, using the command:
	    <programlisting>
make install
	    </programlisting>
	  </para>
	</listitem>
      </orderedlist>
    </para>
    <para>
      Once you have installed Wireshark with <command>make install</command> 
      above, you should be able to run it by entering 
      <command>ethereal</command>.
    </para>
  </section>
  
  <section id="ChBuildInstallUnixInstallBins">
    <title>Installing the binaries under UNIX</title>
    <para>
      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 <command>smit</command> to 
      install the Wireshark binary package, while under Tru64 UNIX 
      (formerly Digital UNIX) you would use <command>setld</command>.
    </para>
  
  <section>
    <title>Installing from rpm's under RedHat and alike</title>
    <para>
      Use the following command to install the Wireshark RPM that you have 
      downloaded from the Wireshark web site:
      <programlisting>
rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm
      </programlisting>
      If the above step fails because of missing dependencies, install the 
      dependencies first, and then retry the step above.  See 
      <xref linkend="Ch02Ex4"/> for information on what RPMs you will need 
	to have installed.
    </para>
  </section>

  <section> 
    <title>Installing from deb's under Debian</title>
    <para> 
      Use the following command to install Wireshark under Debian:
      <programlisting>
apt-get install ethereal
      </programlisting>
      apt-get should take care of all of the dependency issues for you.
    </para>
  </section>
  </section>
  
  <section id="ChBuildInstallUnixTrouble">
    <title>Troubleshooting during the install on Unix</title>
    <para>
      A number of errors can occur during the installation process.  
      Some hints on solving these are provided here.
    </para>
    <para>
      If the <command>configure</command> stage fails, you will need to find 
      out why. You can check the file <filename>config.log</filename> in the 
      source directory to find out what failed. The last few lines of this 
      file should help in determining the problem.
    </para>
    <para>
      The standard problems are that you do not have GTK+ on your system, 
      or you do not have a recent enough version of GTK+. The 
      <command>configure</command> will also fail if you do not have libpcap 
      (at least the required include files) on your system.
    </para>
    <para>
      Another common problem is for the final compile and link stage to 
      terminate with a complaint of: <errorname>Output too long.</errorname>  
      This is likely to be caused by an antiquated <command>sed</command> 
      (such as the one shipped with Solaris).  Since <command>sed</command> is 
      used by the <command>libtool</command> script to construct the final 
      link command, this leads to mysterious problems.  This can be 
      resolved by downloading a recent version of sed from 
      <ulink url="http://directory.fsf.org/GNU/sed.html"/>.
    </para>
    <para>
      If you cannot determine what the problems are, send mail to the 
      <command>ethereal-dev</command> mailing list explaining your problem, 
      and including the output from <filename>config.log</filename> and 
      anything else you think is relevant, like a trace of the 
      <command>make</command> stage.
    </para>
  </section>
  
  <section id="ChBuildInstallWinBuild">
    <title>Building from source under Windows</title>
    <para>
	  It is recommended to use the binary installer for Windows, 
	  until you want to start developing Wireshark on the Windows platform.
    </para>
    <para>
	  For further information how to build Wireshark for Windows from the 
	  sources, have a look at the Development Wiki:
	  <ulink url="http://wiki.ethereal.com/Development">http://wiki.ethereal.com/Development</ulink>
	  for the latest available development documentation.
    </para>
  </section>
  
  <section id="ChBuildInstallWinInstall">
    <title>Installing Wireshark under Windows</title>
    <para>
      In this section we explore installing Wireshark under Windows from the 
      binary packages.  
	</para>
  <section id="ChBuildInstallWireshark">
    <title>Install Wireshark</title>
	<para>
		You may acquire a binary installer of Wireshark named something like: 
		<filename>ethereal-setup-x.y.z.exe</filename>.
	</para>
	<para>
	    Simply download the Wireshark installer from:
	    <ulink url="&WiresharkBinariesPage;">&WiresharkBinariesPage;</ulink> 
		and execute it.
	</para>
	<note><title>Note!</title>
	<para>
	<command>Since Wireshark Version 0.10.12, the WinPcap installer has become 
	part of the main Wireshark installer, so you don't need to download and 
	install two separate packages any longer!</command>
    </para>
	</note>
  <section id="ChBuildInstallWiresharkCommandLine">
    <title>Command line options</title>
    <para>
	You can simply start the Wireshark installer without any command line 
	parameters, it will show you the usual interactive installer.
    </para>
    <para>
	There are some command line parameters available:
    </para>
	<itemizedlist>
	<listitem>
		<para>
		<command>/NCRC</command> disables the CRC check
		</para>
	</listitem>
	<listitem>
		<para>
		<command>/S</command> runs the installer or uninstaller silently with 
		default values. Please note: The silent installer won't install WinPCap!
		</para>
	</listitem>
	<listitem>
		<para>
		<command>/desktopicon</command> installation of the desktop icon, 
		<command>=yes</command> - force installation, <command>=no</command> - 
		don't install, otherwise use defaults / user settings.
		This option is available since 0.10.13 an can be useful for a silent 
		installer. 
		</para>
	</listitem>
	<listitem>
		<para>
		<command>/quicklaunchicon</command> installation of the quick launch icon, 
		<command>=yes</command> - force installation, <command>=no</command> - 
		don't install, otherwise use defaults / user settings.
		This option is available since 0.10.13 an can be useful for a silent 
		installer. 
		</para>
	</listitem>
	<listitem>
		<para>
		<command>/D</command> 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.
		</para>
	</listitem>
	</itemizedlist>
	<para> Example:
    <programlisting>
ethereal-setup-0.10.13.exe /NCRC /S /desktopicon=yes /quicklaunchicon=no /D=C:\Program Files\Foo
	</programlisting>
	</para>
  </section>
  <section id="ChBuildInstallComponents">
    <title>Components</title>
    <para>
	Beside the usual installer options like where to install the program, 
	there are several optional components.
    </para>
    <tip><title>Tip!</title>
	<para>
	If you are unsure which settings to select, just keep the default settings.
    </para>
	</tip>
    <para>
	The Components
	(both Wireshark GTK1 and 2 cannot be installed at the same time):
	<itemizedlist>
	<listitem><para>
	<command>Etheral GTK1</command> - Wireshark is a GUI network protocol 
	analyzer.
	</para></listitem>
	<listitem><para>
	<command>Etheral GTK2</command> - Wireshark is a GUI network protocol 
	analyzer (using the modern GTK2 GUI toolkit, recommended).
	</para></listitem>
	<listitem><para>
	<command>GTK-Wimp</command> - GTKWimp is the GTK2 windows impersonator 
	(native Win32 look and feel, recommended).
	</para></listitem>
	<listitem><para>
	<command>TShark</command> - TShark is a command-line based network 
	protocol analyzer.
	</para></listitem>
	</itemizedlist>
	The dissection extensions for Wireshark and TShark:
	<itemizedlist>
	<listitem><para>
	<command>Dissector Plugins</command> - Plugins with some extended dissections.
	</para></listitem>
	<listitem><para>
	<command>Tree Statistics Plugins</command> - Plugins with some extended statistics.
	</para></listitem>
	<listitem><para>
	<command>Mate - Meta Analysis and Tracing Engine</command> - user 
	configurable extension(s) of the display filter engine, see 
	<ulink url="http://wiki.ethereal.com/Mate">http://wiki.ethereal.com/Mate</ulink>
	for details.
	</para></listitem>
	<listitem><para>
	<command>SNMP MIBs</command> - SNMP MIBs for a more detailed SNMP 
	dissection.
	</para></listitem>
	</itemizedlist>
	The Tools:
	<itemizedlist>
	<listitem><para>
	<command>Editcap</command> - Editcap is a program that reads a capture 
	file and writes some or all of the packets into another capture file.
	</para></listitem>
	<listitem><para>
	<command>Text2Pcap</command> - Text2pcap is a program that reads in an 
	ASCII hex dump and writes the data into a libpcap-style capture file.
	</para></listitem>
	<listitem><para>
	<command>Mergecap</command> - Mergecap is a program that combines multiple 
	saved capture files into a single output file.
	</para></listitem>
	<listitem><para>
	<command>Capinfos</command> - Capinfos is a program that provides 
	information on capture files.
	</para></listitem>
	</itemizedlist>
	The Additional Tasks:
	<itemizedlist>
	<listitem><para>
	<command>Start Menu Shortcuts</command> - add some start menu shortcuts.
	</para></listitem>
	<listitem><para>
	<command>Desktop Icon</command> - add an Wireshark icon to the desktop.
	</para></listitem>
	<listitem><para>
	<command>Quick Launch Icon</command> - add an Wireshark icon to the 
	Explorer quick launch toolbar.
	</para></listitem>
	<listitem><para>
	<command>Associate file extensions to Wireshark</command> - Associate 
	standard network trace files to Wireshark.
	</para></listitem>
	</itemizedlist>
    </para>
  </section>
  </section>
  <section id="ChBuildInstallWinPcap">
    <title>Install WinPcap</title>
    <note><title>Note!</title>
	<para>
	<command>As mentioned above, the Wireshark installer 
	(since version 0.10.12) takes care of the installation of WinPcap, 
	so usually you don't have to worry about WinPcap at all!</command> 
    </para>
	</note>
    <para>
	If you do not have WinPcap installed you will be able to open saved 
	capture files, but you will not be able to capture live network traffic.
    </para>
    <para>
	While running, the Wireshark installer detects which WinPcap version is 
	currently installed and will install WinPcap, if none or an older version is 
	detected. 
    </para>
	<para>
	More WinPcap info:
	<itemizedlist>
	<listitem><para>
	Wireshark related:
	<ulink url="http://wiki.ethereal.com/WinPcap">http://wiki.ethereal.com/WinPcap</ulink>
	</para></listitem>
	<listitem><para>
	General WinPcap info: 
	<ulink url="&WinPcapWebsite;">&WinPcapWebsite;</ulink>
	</para></listitem>
	</itemizedlist>
	</para>
  	<section id="ChBuildInstallWinPcapManually">
    <title>Manual WinPcap Installation</title>
    <para>
	The following is only necessary if you want to 
	try a different version than the one included in the Wireshark installer, 
	e.g. because a new WinPcap (beta) version was released.
    </para>
    <para>
	Additional WinPcap versions (including newer alpha or beta releases)
	can be downloaded from the following locations:
	<itemizedlist>
	<listitem><para>
    The main WinPcap site: 
	<ulink url="&WinPcapWebsite;">&WinPcapWebsite;</ulink>
	</para></listitem>
	<listitem><para>
    The ethereal.com mirror:
	<ulink url="http://winpcap.mirror.ethereal.com">
	http://winpcap.mirror.ethereal.com</ulink>
	</para></listitem>
	<listitem><para>
    The Wiretapped.net mirror:
	<ulink url="http://www.mirrors.wiretapped.net/security/packet-capture/winpcap">
	http://www.mirrors.wiretapped.net/security/packet-capture/winpcap</ulink>
	</para></listitem>
	</itemizedlist>
    </para>
    <para>
	At the download page you will find a single installer exe called something 
	like "auto-installer", which can be installed under various Windows 
	systems, including 9x/Me/NT4.0/2000/XP.
	</para>
	</section>
  </section>
  
  <section id="ChBuildInstallWinWiresharkUpdate">
    <title>Update Wireshark</title>
	<para>
	From time to time you may want to update your installed Wireshark to a more
	recent version. If you join Wireshark's announce mailing list, you will be 
	informed about new Wireshark versions, see <xref 
	linkend="ChIntroMailingLists"/> for details how to subscribe to this list.
    </para>
    <para>
	New versions of Wireshark usually become available every 4-8 weeks.
	Updating Wireshark is done the same way as installing it, you simply 
	download and start the installer exe. A reboot is usually not required and
	all your personal settings remain unchanged.
    </para>
  </section>
  
  <section id="ChBuildInstallWinPcapUpdate">
    <title>Update WinPcap</title>
    <para>
	New versions of WinPcap are less frequently available, maybe only once in a 
	year. You will find WinPcap update instructions where you can download new 
	WinPcap versions. Usually you have to reboot the machine after installing 
	a new WinPcap version.
    </para>
	<warning><title>Warning!</title>
	<para>
	If you have an older version of WinPcap installed, you must un-install it 
	before installing the current version. Recent versions of the WinPcap 
	installer will take care of this.
	</para>
	</warning>
  </section>
  
  <section id="ChBuildInstallWinUninstall">
    <title>Uninstall Wireshark</title>
    <para>
	You can uninstall Wireshark the usual way, using the "Add or Remove 
	Programs" option inside the Control Panel. Select the "Wireshark" entry to 
	start the uninstallation procedure.
    </para>
    <para>
	The Wireshark uninstaller will provide several options which things to be 
	uninstalled, the default is to remove the core components but keep the personal 
	settings, WinPcap and alike.
    </para>
    <para>
	WinPcap won't be uninstalled by default, as other programs than Wireshark 
	may use it as well.
    </para>
  </section>
  
  <section id="ChBuildInstallWinPcapUninstall">
    <title>Uninstall WinPcap</title>
    <para>
	You can uninstall WinPcap independantly of Wireshark, using the "WinPcap" 
	entry in the "Add or Remove Programs" of the Control Panel.
    </para>
	<note><title>Note!</title>
    <para>
	After uninstallation of WinPcap you can't capture anything with Wireshark.
    </para>
	</note>
    <para>
	It might be a good idea to reboot Windows afterwards.
    </para>
  </section>
  </section>
  
</chapter>
<!-- End of WSUG Chapter 2 -->