docbook/eug_src/EUG_chapter_build_install.xml

   1 <!-- EUG Chapter BuildInstall -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterBuildInstall">
   5   <title>Building and Installing Ethereal</title>
   6   <section id="ChBuildInstallIntro">
   7     <title>Introduction</title>
   8     <para>
   9       As with all things, there must be a beginning, and so it is with
  10       Ethereal. To use Ethereal, you must:
  11       <itemizedlist>
  12         <listitem>
  13           <para>
  14             Obtain a binary package for your operating system, or
  15           </para>
  16         </listitem>
  17         <listitem>
  18           <para>
  19             Obtain the source and build Ethereal for your operating system.
  20           </para>
  21         </listitem>
  22       </itemizedlist>
  23     </para>
  24     <para>
  25       Currently, only two or three Linux distributions ship Ethereal, and
  26       they are commonly shipping an out-of-date version.  No other versions
  27       of UNIX ship Ethereal so far, and Microsoft does not ship it with any
  28       version of Windows.  For that reason, you will need to know where to
  29       get the latest version of Ethereal and how to install it.
  30     </para>
  31     <para>
  32       This chapter shows you how to obtain source and binary packages,
  33       and how to build Ethereal from source, should you choose to do so.
  34     </para>
  35     <para>
  36       The following are the general steps you would use:
  37       <orderedlist>
  38         <listitem>
  39           <para>
  40             Download the relevant package for your needs, e.g. source or
  41             binary distribution.
  42           </para>
  43         </listitem>
  44         <listitem>
  45           <para>
  46             Build the source into a binary, if you have downloaded the
  47             source.
  48           </para>
  49           <para>
  50             This may involve building and/or installing other necessary packages.
  51           </para>
  52         </listitem>
  53         <listitem>
  54           <para>
  55             Install the binaries into their final destinations.
  56           </para>
  57         </listitem>
  58       </orderedlist>
  59     </para>
  60   </section>
  61
  62   <section id="ChBuildInstallDistro">
  63     <title>Obtaining the source and binary distributions</title>
  64     <para>
  65       You can obtain both source and binary distributions from the Ethereal
  66       web site: <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
  67       Simply select the download link, and then select either the source
  68       package or binary package of your choice from the mirror site closest
  69       to you.
  70     </para>
  71     <note>
  72       <title>Download all the needed files</title>
  73       <para>
  74         In general, unless you have already downloaded Ethereal
  75         before, you will most likely need to download several source
  76         packages if you are building Ethereal from source.  This is
  77         covered in more detail below. <!-- Make a ref -->
  78       </para>
  79     </note>
  80     <para>
  81       Once you have downloaded the relevant files, you can go on to the
  82       next step.
  83     </para>
  84     <note>
  85       <title>Note!</title>
  86       <para>
  87         While you will find a number of binary packages available on the
  88         Ethereal web site, you might not find one for your platform, and
  89         they often tend to be several versions behind the current released
  90         version, as they are contributed by people who have the platforms
  91         they are built for.
  92       </para>
  93       <para>
  94         For this reason, you might want to pull down the source distribution
  95         and build it, as the process is relatively simple.
  96       </para>
  97     </note>
  98   </section>
  99
 100   <section id="ChBuildInstallBeforeBuild">
 101     <title>Before you build <application>Ethereal</application> under UNIX</title>
 102     <para>
 103       Before you build Ethereal from sources, or install a binary package,
 104       you must ensure that you have the following other packages installed:
 105       <itemizedlist>
 106         <listitem>
 107           <para>GTK+, The GIMP Tool Kit.</para>
 108           <para>
 109             You will also need Glib.  Both can be obtained from
 110             <ulink url="http://www.gtk.org">www.gtk.org</ulink>
 111           </para>
 112         </listitem>
 113         <listitem>
 114           <para>
 115             libpcap, the packet capture software that Ethereal uses.
 116           </para>
 117           <para>
 118             You can obtain libpcap from
 119             <ulink url="http://www.tcpdump.org">www.tcpdump.org</ulink>
 120           </para>
 121         </listitem>
 122       </itemizedlist>
 123       Depending on your system, you may be able to install these from
 124       binaries, e.g. RPMs, or you may need to obtain them in source code
 125       form and build them.
 126     </para>
 127     <para>
 128       If you have downloaded the source for GTK+, the instructions shown
 129       in <xref linkend="Ch02Ex1"/> may provide some help in building it:
 130         <example id="Ch02Ex1">
 131           <title>Building GTK+ from source</title>
 132           <programlisting>
 133 gzip -dc gtk+-1.2.10.tar.gz | tar xvf -
 134 &lt;much output removed>
 135 cd gtk+-1.2.10
 136 ./configure
 137 &lt;much output removed>
 138 make
 139 &lt;much output removed>
 140 make install
 141 &lt;much output removed>
 142           </programlisting>
 143         </example>
 144         <note>
 145           <title>Note!</title>
 146           <para>
 147             You may need to change the version number of gtk+ in
 148             <xref linkend="Ch02Ex1"/> to match the version of GTK+ you have
 149               downloaded. The directory you change to will change if the
 150               version of GTK+ changes, and in all cases,
 151               <command>tar xvf -</command> will show you the name of the
 152               directory you should change to.
 153           </para>
 154         </note>
 155         <note>
 156           <title>Note!</title>
 157           <para>
 158             If you use Linux, or have GNU <command>tar</command> installed,
 159             you can use <command>tar zxvf gtk+-1.2.10.tar.gz</command>. It
 160             is also possible to use <command>gunzip -c</command> or
 161             <command>gzcat</command> rather than <command>gzip -dc</command>
 162             on many UNIX systems.
 163           </para>
 164         </note>
 165         <note>
 166           <title>Note!</title>
 167           <para>
 168             If you downloaded gtk+ or any other tar file using Windows,
 169             you may find your file called gtk+-1_2_8_tar.gz.
 170           </para>
 171         </note>
 172     </para>
 173     <para>
 174       You should consult the GTK+ web site if any errors occur in carrying
 175       out the instructions in <xref linkend="Ch02Ex1"/>.
 176     </para>
 177     <para>
 178       If you have downloaded the source to libpcap, the general instructions
 179       shown in <xref linkend="Ch2Ex2"/>  will assist in building it. Also,
 180         if your operating system does not support <command>tcpdump</command>,
 181         you might also want to download it from the
 182         <ulink url="http://www.tcpdump.org">tcpdump</ulink> web site and
 183         install it.
 184         <example id="Ch2Ex2">
 185           <title>Building and installing libpcap</title>
 186           <programlisting>
 187 gzip -dc libpcap-0.8.3.tar.Z | tar xvf -
 188 &lt;much output removed>
 189 cd libpcap_0_8_3
 190 ./configure
 191 &lt;much output removed>
 192 make
 193 &lt;much output removed>
 194 make install
 195 &lt;much output removed>
 196 make install-incl
 197 &lt;much output removed>
 198             </programlisting>
 199         </example>
 200     </para>
 201     <note>
 202       <title>Note!</title>
 203       <para>
 204         The directory you should change to will depend on the version of
 205         libpcap you have downloaded.  In all cases,
 206         <command>tar xvf -</command> will show you the name of the
 207         directory that has been unpacked.
 208       </para>
 209     </note>
 210     <para>
 211       When installing the include files, you might get the error shown
 212       in <xref linkend="Ch02Ex3"/> when you submit the command
 213         <command>make install-incl</command>.
 214         <example id="Ch02Ex3">
 215           <title>Errors while installing the libpcap include files</title>
 216           <programlisting>
 217 /usr/local/include/pcap.h
 218 /usr/bin/install -c -m 444 -o bin -g bin ./pcap-namedb.h \
 219 /usr/local/include/pcap-namedb.h
 220 /usr/bin/install -c -m 444 -o bin -g bin ./net/bpf.h \
 221 /usr/local/include/net/bpf.h
 222 /usr/bin/install: cannot create regular file \
 223 `/usr/local/include/net/bpf.h': No such file or directory
 224 make: *** [install-incl] Error 1
 225           </programlisting>
 226         </example>
 227         If you do, simply create the missing directory with the following
 228         command:
 229         <programlisting>
 230 mkdir /usr/local/include/net
 231         </programlisting>
 232         and rerun the command <command>make install-incl</command>.
 233     </para>
 234     <para>
 235       Under RedHat 6.x and beyond (and distributions based on it, like
 236       Mandrake) you can simply install each of the packages you need from
 237       RPMs. Most Linux systems will install GTK+ and Glib in anycase,
 238       however, you will probably need to install the devel versions of
 239       each of these packages. The commands shown in <xref linkend="Ch02Ex4"/>
 240         will install all the needed RPMs if they are not already installed.
 241         <example id="Ch02Ex4">
 242           <title>
 243             Installing required RPMs under RedHat Linux 6.2 and beyond
 244           </title>
 245           <programlisting>
 246 cd /mnt/cdrom/RedHat/RPMS
 247 rpm -ivh glib-1.2.6-3.i386.rpm
 248 rpm -ivh glib-devel-1.2.6-3.i386.rpm
 249 rpm -ivh gtk+-1.2.6-7.i386.rpm
 250 rpm -ivh gtk+-devel-1.2.6-7.i386.rpm
 251 rpm -ivh libpcap-0.4-19.i386.rpm
 252           </programlisting>
 253         </example>
 254     </para>
 255     <note>
 256       <para>
 257         If you are using a version of RedHat later than 6.2, the required
 258         RPMs have most likely changed. Simply use the correct RPMs from your
 259         distribution.
 260       </para>
 261     </note>
 262     <para>
 263       Under Debian you can install Ethereal using apt-get.  apt-get will
 264       handle any dependency issues for you. <xref linkend="Ch02Ex5"/> shows
 265         how to do this.
 266         <example id="Ch02Ex5">
 267           <title>Installing debs under Debian</title>
 268           <programlisting>
 269 apt-get install ethereal
 270           </programlisting>
 271         </example>
 272     </para>
 273   </section>
 274
 275   <section id="ChBuildInstallUnixBuild">
 276     <title>Building Ethereal from source under UNIX</title>
 277     <para>
 278       Use the following general steps if you are building Ethereal from
 279       source under a UNIX operating system:
 280       <orderedlist>
 281         <listitem>
 282           <para>
 283             Unpack the source from its <command>gzip</command>'d
 284             <command>tar</command> file. If you are using Linux, or your
 285             version of UNIX uses GNU <command>tar</command>, you can use the
 286             following command:
 287             <programlisting>
 288 tar zxvf ethereal-&EtherealCurrentVersion;-tar.gz
 289             </programlisting>
 290           </para>
 291           <para>
 292             For other versions of UNIX, You will want to use the following
 293             commands:
 294             <programlisting>
 295 gzip -d ethereal-&EtherealCurrentVersion;-tar.gz
 296 tar xvf ethereal-&EtherealCurrentVersion;-tar
 297             </programlisting>
 298             <note>
 299               <title>Note!</title>
 300               <para>
 301                 The pipeline
 302                 <command>
 303                   gzip -dc ethereal-&EtherealCurrentVersion;-tar.gz | tar xvf -
 304                 </command> will work here as well.
 305               </para>
 306             </note>
 307             <note>
 308               <title>Note!</title>
 309               <para>
 310                 If you have downloaded the Ethereal tarball under Windows,
 311                 you may find that your browser has created a file with
 312                 underscores rather than periods in its file name.
 313               </para>
 314             </note>
 315           </para>
 316         </listitem>
 317         <listitem>
 318           <para>
 319             Change directory to the Ethereal source directory.
 320           </para>
 321         </listitem>
 322         <listitem>
 323           <para>
 324             Configure your source so it will build correctly for your
 325             version of UNIX.  You can do this with the following command:
 326             <programlisting>
 327 ./configure
 328             </programlisting>
 329           </para>
 330           <para>
 331             If this step fails, you will have to rectify the problems and
 332             rerun <command>configure</command>.  Troubleshooting hints are
 333             provided in <xref linkend="ChBuildInstallUnixTrouble"/>.
 334           </para>
 335         </listitem>
 336         <listitem>
 337           <para>
 338             Build the sources into a binary, with the <command>make</command>
 339             command.  For example:
 340             <programlisting>
 341 make
 342             </programlisting>
 343           </para>
 344         </listitem>
 345         <listitem>
 346           <para>
 347             Install the software in its final destination, using the command:
 348             <programlisting>
 349 make install
 350             </programlisting>
 351           </para>
 352         </listitem>
 353       </orderedlist>
 354     </para>
 355     <para>
 356       Once you have installed Ethereal with <command>make install</command>
 357       above, you should be able to run it by entering
 358       <command>ethereal</command>.
 359     </para>
 360   </section>
 361
 362   <section id="ChBuildInstallUnixInstallBins">
 363     <title>Installing the binaries under UNIX</title>
 364     <para>
 365       In general, installing the binary under your version of UNIX will be
 366       specific to the installation methods used with your version of UNIX.
 367       For example, under AIX, you would use <command>smit</command> to
 368       install the Ethereal binary package, while under Tru64 UNIX
 369       (formerly Digital UNIX) you would use <command>setld</command>.
 370     </para>
 371
 372   <section>
 373     <title>Installing from rpm's under RedHat and alike</title>
 374     <para>
 375       Use the following command to install the Ethereal RPM that you have
 376       downloaded from the Ethereal web site:
 377       <programlisting>
 378 rpm -ivh ethereal-0.10.5-0.2.2.i386.rpm
 379       </programlisting>
 380       If the above step fails because of missing dependencies, install the
 381       dependencies first, and then retry the step above.  See
 382       <xref linkend="Ch02Ex4"/> for information on what RPMs you will need
 383         to have installed.
 384     </para>
 385   </section>
 386
 387   <section>
 388     <title>Installing from deb's under Debian</title>
 389     <para>
 390       Use the following command to install Ethereal under Debian:
 391       <programlisting>
 392 apt-get install ethereal
 393       </programlisting>
 394       apt-get should take care of all of the dependency issues for you.
 395     </para>
 396   </section>
 397   </section>
 398
 399   <section id="ChBuildInstallUnixTrouble">
 400     <title>Troubleshooting during the install on Unix</title>
 401     <para>
 402       A number of errors can occur during the installation process.
 403       Some hints on solving these are provided here.
 404     </para>
 405     <para>
 406       If the <command>configure</command> stage fails, you will need to find
 407       out why. You can check the file <filename>config.log</filename> in the
 408       source directory to find out what failed. The last few lines of this
 409       file should help in determining the problem.
 410     </para>
 411     <para>
 412       The standard problems are that you do not have GTK+ on your system,
 413       or you do not have a recent enough version of GTK+. The
 414       <command>configure</command> will also fail if you do not have libpcap
 415       (at least the required include files) on your system.
 416     </para>
 417     <para>
 418       Another common problem is for the final compile and link stage to
 419       terminate with a complaint of: <errorname>Output too long.</errorname>
 420       This is likely to be caused by an antiquated <command>sed</command>
 421       (such as the one shipped with Solaris).  Since <command>sed</command> is
 422       used by the <command>libtool</command> script to construct the final
 423       link command, this leads to mysterious problems.  This can be
 424       resolved by downloading a recent version of sed from
 425       <ulink url="http://directory.fsf.org/GNU/sed.html"/>.
 426     </para>
 427     <para>
 428       If you cannot determine what the problems are, send mail to the
 429       <command>ethereal-dev</command> mailing list explaining your problem,
 430       and including the output from <filename>config.log</filename> and
 431       anything else you think is relevant, like a trace of the
 432       <command>make</command> stage.
 433     </para>
 434   </section>
 435
 436   <section id="ChBuildInstallWinBuild">
 437     <title>Building from source under Windows</title>
 438     <para>
 439           It is recommended to use the binary installer for Windows,
 440           until you want to start developing Ethereal on this platform.
 441     </para>
 442     <para>
 443           For further information how to build Ethereal for Windows from the
 444           sources, have a look at the file Readme.win32, which
 445           can be found in the doc directory of the sources.
 446     </para>
 447   </section>
 448
 449   <section id="ChBuildInstallWinInstall">
 450     <title>Installing Ethereal under Windows</title>
 451     <para>
 452       In this section we explore installing Ethereal under Windows from the
 453       binary packages.  You must follow two steps:
 454       <orderedlist>
 455         <listitem>
 456           <para>
 457             <command>Install WinPcap</command>.
 458                 You will find a single installer exe called something
 459                 like "auto-installer", which can be installed under various Windows
 460                 systems, including 9x/Me/NT4.0/2000/XP. This installer is located at:
 461             <ulink url="&WinPcapDownloadWebsite;">&WinPcapDownloadWebsite;</ulink>.
 462             You should download the latest released version (the latest one not
 463                 marked "beta") and execute it.
 464           </para>
 465         </listitem>
 466         <listitem>
 467           <para>
 468             <command>Install Ethereal</command>.
 469                 You may acquire a binary installable of Ethereal at
 470             <ulink url="&EtherealBinariesPage;">&EtherealBinariesPage;</ulink>.
 471             Download the installer and execute it.
 472           </para>
 473         </listitem>
 474       </orderedlist>
 475           Both steps are extremely simply, as you only have to download and
 476           install the two exe files.
 477     </para>
 478   <section id="ChBuildInstallComponents">
 479     <title>Installable Components</title>
 480     <para>
 481         Beside the usual installer options like where to install the program,
 482         there are several optional components (if you are unsure, just keep the
 483         default settings).
 484     </para>
 485     <para>
 486         The programs being installed
 487         (both Ethereal GTK1 and 2 cannot be installed at the same time):
 488         <itemizedlist>
 489         <listitem><para>
 490         <command>Etheral GTK1</command> - Ethereal is a GUI network protocol
 491         analyzer.
 492         </para></listitem>
 493         <listitem><para>
 494         <command>Etheral GTK2</command> - Ethereal is a GUI network protocol
 495         analyzer (using the modern GTK2 GUI toolkit).
 496         </para></listitem>
 497         <listitem><para>
 498         <command>GTK-Wimp</command> - GTKWimp is the GTK2 windows impersonator
 499         (native Win32 look and feel).
 500         </para></listitem>
 501         <listitem><para>
 502         <command>Tethereal</command> - Tethereal is a command-line based network
 503         protocol analyzer.
 504         </para></listitem>
 505         <listitem><para>
 506         <command>Editcap</command> - Editcap is a program that reads a capture
 507         file and writes some or all of the packets into another capture file.
 508         </para></listitem>
 509         <listitem><para>
 510         <command>Text2Pcap</command> - Text2pcap is a program that reads in an
 511         ASCII hex dump and writes the data into a libpcap-style capture file.
 512         </para></listitem>
 513         <listitem><para>
 514         <command>Mergecap</command> - Mergecap is a program that combines multiple
 515         saved capture files into a single output file.
 516         </para></listitem>
 517         <listitem><para>
 518         <command>Capinfo</command> - Capinfo is a program that provides
 519         information on capture files.
 520         </para></listitem>
 521         </itemizedlist>
 522         The dissection extensions for Ethereal and Tethereal:
 523         <itemizedlist>
 524         <listitem><para>
 525         <command>Plugins</command> - Plugins with some extended dissections.
 526         </para></listitem>
 527         <listitem><para>
 528         <command>SNMP MIBs</command> - SNMP MIBs for a more detailed SNMP
 529         dissection.
 530         </para></listitem>
 531         </itemizedlist>
 532         The environment related things:
 533         <itemizedlist>
 534         <listitem><para>
 535         <command>Start Menu Shortcuts</command> - Some start menu shortcuts.
 536         </para></listitem>
 537         <listitem><para>
 538         <command>Desktop Icon</command> - Ethereal desktop icon.
 539         </para></listitem>
 540         <listitem><para>
 541         <command>Associate file extensions to Ethereal</command> - Associate
 542         standard network trace files to Ethereal.
 543         </para></listitem>
 544         </itemizedlist>
 545     </para>
 546   </section>
 547   <section id="ChBuildInstallWinUpdate">
 548     <title>Update</title>
 549         <para>
 550         From time to time you may want to update your installed Ethereal to a more
 551         recent version. If you join Ethereal's announce mailing list, you will be
 552         informed about new Ethereal versions, see <xref
 553         linkend="ChIntroMailingLists"/> for details how to subscribe to this list.
 554       <itemizedlist>
 555         <listitem>
 556     <para>
 557     <command>Update Ethereal</command>.
 558         New versions of Ethereal usually become available every 4-8 weeks.
 559         Updating Ethereal is done the same way as installing it, you simply
 560         download and start the installer exe. A reboot is usually not required and
 561         all your personal settings remain unchanged.
 562     </para>
 563         </listitem>
 564         <listitem>
 565     <para>
 566     <command>Update WinPcap</command>.
 567         New versions of WinPcap are less frequently available, maybe only once a
 568         year. You will find WinPcap update instructions where you can download new
 569         versions. Usually you have to reboot the machine after installing a new
 570         WinPcap version.
 571     </para>
 572         </listitem>
 573       </itemizedlist>
 574         </para>
 575   </section>
 576
 577   <section id="ChBuildInstallWinUninstall">
 578     <title>Uninstall Ethereal</title>
 579     <para>
 580         You can uninstall Ethereal the usual way, using the Software option
 581         inside the Control Panel. You will find two entries, one for Ethereal
 582         itself and one for WinPcap.
 583     </para>
 584   </section>
 585   </section>
 586
 587 </chapter>
 588 <!-- End of EUG Chapter 2 -->