README.win32

   1 $Id: README.win32,v 1.70 2004/04/18 10:16:19 obiot Exp $
   2
   3 Installing Ethereal, Tethereal, and Editcap on Win32
   4 ====================================================
   5 These are the instructions for installing Ethereal
   6 from the installation executable that is provided on
   7 the Ethereal website at:
   8
   9 http://www.ethereal.com/distribution/win32
  10
  11 and any of its mirrors.
  12
  13 The installation package allows you to install:
  14
  15         o Ethereal - the GUI version
  16         o Tethereal - the console, line-mode version
  17         o Editcap - a console, line-mode utility to convert
  18           capture files from one format to another.
  19           (The same functions are available in Ethereal)
  20         o Text2Pcap - a console, line-mode utility to generate
  21           a capture file from an ASCII hexdump of packets
  22         o Mergecap - a console, line-mode utility to merge two
  23           capture files into one
  24
  25 Additionally, the installation package contains a "plugins"
  26 option, which installs some additional dissector plugins
  27 for use with Ethereal and Tethereal.
  28
  29 All binaries in Ethereal package are now built with debugging
  30 information embedded. If you are experiencing a crash when running
  31 Ethereal or other binaries, Dr. Watson or your debugger
  32 can use the information embedded in the binary to provide useful
  33 information to the Ethereal developers that will help them pinpoint
  34 the problem.
  35
  36 In the past, two versions of Ethereal binaries were published -- a
  37 version that could capture packets and a version which could not.
  38 The latter is useful if you're only reading files produced by
  39 another product (e.g., a sniffer, firewall, or intrustion detection system)
  40 and did not wish to install WinPcap, the library Ethereal uses
  41 to capture packets on Win32 platforms.
  42
  43 As of WinPcap 2.1, all the WinPcap libraries have been released as DLLs.
  44 This means that Ethereal can detect the presence of WinPcap at run time,
  45 which means that only one version of the Ethereal binaries needs to be
  46 shipped.
  47
  48 If you don't want to capture packets, just install the Ethereal
  49 package. If you do want to capture packets, install Ethereal *and*
  50 install the latest non-beta version of WinPcap, available from:
  51
  52         http://winpcap.polito.it/
  53
  54 and mirrored at
  55
  56         http://winpcap.mirror.ethereal.com/
  57
  58 and
  59
  60         http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/
  61
  62 If you already have an earlier version of WinPcap installed, you need to
  63 un-install it and install the latest version.  If the older version is
  64 WinPcap 2.0 or 2.02, and you have other applications that use the older
  65 version , you will have to decide which applications to keep, since
  66 WinPcap 2.0/2.02 and later versions cannot be installed on the same
  67 system at the same time.
  68
  69 If Ethereal is not capturing packets and you have WinPcap installed, you
  70 can test your WinPcap installation by installing WinDump (tcpdump for
  71 Windows) ported by the same folks who make WinPcap.  It's at:
  72
  73         http://windump.polito.it/
  74
  75 and mirrored at
  76
  77         http://windump.mirror.ethereal.com/
  78
  79 and
  80
  81         http://www.mirrors.wiretapped.net/security/packet-capture/windump/
  82
  83 They also make Analyzer, a GUI sniffer for Win32:
  84
  85         http://analyzer.polito.it/
  86
  87 The rest of this documentation is only interesting if
  88 you want to compile Ethereal yourself.
  89
  90
  91 Compiling the Ethereal distribution from source
  92 ===============================================
  93
  94 Compilers
  95 ---------
  96 MS Visual C++ Version 6
  97 This is the common compiler used for building Ethereal on win32.
  98
  99 MS Visual C++ Version 7 / VC.NET
 100 Currently unsupported for two reasons:
 101 -the licence agreement does NOT allow you to compile GPL code.
 102 -there are serious problems in using DLL's compiled with MS VC6.
 103
 104 Cygwin GCC
 105 Ethereal can entirely be built with cygwin GCC. However the built binaries will
 106 only run in a cygwin environment, so they are not standalone Win32 applications.
 107 It is however not excluded that native Win32 code can be compiled on cygwin GCC
 108 but you then have to use -mms-bitfields as a strict minimum and probably
 109 -mno-cygwin or a similar compiler flag too.
 110 See section below for instructions.
 111
 112
 113 Automated library download
 114 --------------------------
 115 Before using the automated download, be sure to edit the config.nmake file
 116 to suit your needs. Especially have a look at the ETHEREAL_LIBS setting.
 117 However, the defaults should be working well for a first start.
 118
 119 If you've installed Microsoft Visual C++ (MSVC), you can run:
 120
 121 nmake -f makefile.nmake setup
 122
 123 This will first check the availability of all required tools and then uses
 124 the tool wget to download each package file (together around 30MB!) from the
 125 server location at:
 126
 127 http://www.ethereal.com/distribution/win32/development/
 128
 129 and unpack it in the $ETHEREAL_LIBS directory.
 130
 131 If you have problems downloading the files, you might be connected to the
 132 internet through a proxy/firewall. In this case see the wget documentation
 133 to configure wget accordingly.
 134
 135
 136 Required libraries
 137 ------------------
 138 If the automated library download finished sucessfully, you should have all
 139 libraries on your machine at the right places. So you don't have to read this,
 140 unless you are interested which libraries are used.
 141
 142 You'll need the development packages for GLIB, GTK+, iconv, gettext,
 143 WinPcap, Net-SNMP, and optionally ADNS, PCRE and zlib. The development
 144 packages contain header files and stub libraries to link against.
 145
 146 PRECOMPILED VERSIONS OF ALL OF THESE PACKAGES ARE AVAILABLE AT:
 147
 148         http://www.ethereal.com/distribution/win32/development/
 149
 150
 151 The GLIB, GTK+, iconv, gettext packages for win32 can be found at the home
 152 page for the GTK+ for Win32 project:
 153
 154         http://www.gimp.org/~tml/gimp/win32 or the mirror
 155         http://www.iki.fi/tml/gimp/win32/
 156
 157 The Net-SNMP package for win32 is available at its homepage:
 158
 159         http://
 160
 161 The WinPcap package is available at its homepage:
 162
 163         http://winpcap.polito.it/ or the mirror
 164         http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
 165
 166 The optional ADNS package for win32 is available at its homepage:
 167
 168         http://adns.jgaa.com/
 169
 170 The optional PCRE package (Perl Compatible Regular Expressions) for win32 is
 171 available at its homepage:
 172
 173         http://gnuwin32.sourceforge.net/packages/pcre.htm
 174
 175 The optional zlib package for win32 is available at its homepage:
 176
 177         http://www.gzip.org/zlib/
 178
 179
 180 By default, the build process looks for these packages in
 181 C:\ethereal-win32-libs.  You can place them in a different directory, but
 182 you must update the ETHEREAL_LIBS variable in config.nmake accordingly.
 183
 184 The following lists the packages needed to compile Ethereal and the default
 185 locations where to unpack them, when the above method isn't used.
 186
 187     Package                               Default Location
 188     -------                               ----------------
 189     glib-2.2.3-20040116.zip               C:\ethereal-win32-libs\glib
 190     glib-dev-2.2.3-20040116.zip           C:\ethereal-win32-libs\glib
 191     gtk+-1.3.0-20030717.zip               C:\ethereal-win32-libs\gtk+
 192     gtk+-dev-1.3.0-20030115.zip           C:\ethereal-win32-libs\gtk+
 193     libiconv-1.9.1.bin.woe32.zip          C:\ethereal-win32-libs\libiconv-1.9.1.bin.woe32
 194     gettext-runtime-0.13.1.zip            C:\ethereal-win32-libs\gettext-runtime-0.13.1
 195     net-snmp-5.1.zip                      C:\ethereal-win32-libs
 196     wpdpack_3_0.zip                       C:\ethereal-win32-libs
 197
 198 and optional:
 199
 200     adns-1.0-win32-03.zip                 C:\ethereal-win32-libs
 201     pcre-4.4.zip                          C:\ethereal-win32-libs
 202     zlib121-dll.zip                       C:\ethereal-win32-libs\zlib121-dll
 203
 204 (to use the default locations, the directories in question should be
 205 created, and each zip file should be unpacked into the corresponding
 206 directory).  If you only want to change the C:\ethereal-win32-libs
 207 part, you just change the setting of ETHEREAL_LIBS in config.nmake; if
 208 you want to change subdirectories, you'll have to change the individual
 209 item for a package.  (Note that some zip files create the subdirectory -
 210 those zip files just have C:\ethereal-win32-libs in the list above - so
 211 if you don't want the package to be in that subdirectory, you'd have to
 212 rename the directory.)
 213
 214 The gettext runtime package provides intl.dll, which is needed by
 215 GLib 2.2.3.
 216
 217
 218 Compiling the Ethereal distribution using GTK+2
 219 -----------------------------------------------
 220
 221 The more recent version 2 of the GTK+ can be used to compile
 222 Ethereal with, but is still considered beta.
 223
 224 GTK+2 will look better in various ways, especially for WIN32 users.
 225
 226 You can get the required libraries from:
 227
 228 http://www.ethereal.com/distribution/win32/development/gtk2
 229
 230 or (like the GTK+1 libraries from the GTK+ for Win32 project):
 231
 232 http://www.gimp.org/~tml/gimp/win32/downloads.html
 233
 234 If you want to try a build with GTK+2.x these Extra libraries are needed
 235
 236     Package                               Default Location
 237     -------                               ----------------
 238     gtk+-2.2.4-20040124.zip               C:\ethereal-win32-libs\gtk2
 239     gtk+-dev-2.2.4-20040124.zip           C:\ethereal-win32-libs\gtk2
 240     pango-1.2.5-20040124.zip              C:\ethereal-win32-libs\gtk2
 241     pango-dev-1.2.5-20040124.zip          C:\ethereal-win32-libs\gtk2
 242     atk-1.4.0.zip                         C:\ethereal-win32-libs\gtk2
 243     atk-dev-1.4.0.zip                     C:\ethereal-win32-libs\gtk2
 244
 245 and optional:
 246
 247     gtk-wimp-0.5.3-bin.zip                C:\ethereal-win32-libs\gtk-wimp
 248
 249 Be sure to set GTK2_DIR in config.nmake correct, to be able to compile.
 250
 251 Running your freshly compiled Ethereal
 252 --------------------------------------
 253
 254 Make sure the glib and gtk DLL's are in your path or you use a directory
 255 where all required DLL's and the exe files reside.- i.e., that your
 256 path includes the directory (folder) or directories (folders) in which
 257 those DLLs are found - when you run Ethereal.
 258
 259 Note the wiretap*.dll must be in your path as well and if wiretap is changed
 260 be sure to put the new one in your path.
 261
 262 Plugins (gryphon.dll and mgcp.dll) can go in:
 263         <Ethereal installation directory>\plugins\<version>
 264
 265 Where <version> is the version number, without brackets.  For example,
 266 if you have Ethereal 0.9.8 installed in the default location, plugins
 267 will reside in C:\Program Files\Ethereal\plugins\0.9.8
 268
 269 Yes, the location of plugins needs to be more flexible.
 270
 271 Instructions for MS Visual C++
 272 ----------------------------
 273 Modify the config.nmake file in the top directory of the Ethereal source
 274 tree to work for your local configuration; if you don't have Python,
 275 comment out the line that defines PYTHON, otherwise set it to refer to
 276 the pathname of your Python interpreter executable.  You should not have
 277 to modify any other Makefile.
 278
 279 Note that perl is needed to build the documentation, the lines in config.nmake
 280
 281 POD2MAN=$(SH) pod2man
 282 POD2HTML=$(SH) pod2html
 283
 284 requires Cygwin bash and perl to work.
 285
 286 Many of the file and directory names used in the build process go past
 287 the old 8.3 naming limitations.  As a result, at least on Windows NT 4.0,
 288 Windows 2000, Windows XP, and Windows .NET Server, you should use the
 289 newer "cmd.exe" command interpreter instead of the old "command.com",
 290 as the "command.com" on Windows 2000, at least, can't handle non-8.3
 291 directory names.  (It may be that the "command.com" in Windows 95, Windows
 292 98, and Windows Me, as it's the only command interpreter in those systems,
 293 can handle those directories.  If not, it may not be possible to build
 294 Ethereal from the command line on those versions of Windows.)
 295
 296 Be sure that your command-line environment is set up to compile
 297 and link with MSVC++. When installing MSVC++, you can have your
 298 system's environment set up to always allow compiling from the
 299 command line, or you can invoke the vcvars32.bat script, which can
 300 usually be found in the "VC98\Bin" subdirectory of the directory in
 301 which Visual Studio was installed.
 302
 303 The first time you build Ethereal, run the script "cleanbld.bat" in the
 304 top-level Ethereal source directory to make sure that the "config.h"
 305 files will be reconstructed from the "config.h.win32" files.  (If, for
 306 example, you have "config.h" files left over from a Unix build, a
 307 Windows build will fail.)
 308
 309 In the ethereal directory, type "nmake -f makefile.nmake". It will
 310 recurse into the subdirectories as appropriate.
 311
 312 Some generated source is created by traditionally "Unix-ish" tools.
 313
 314 If you are building from an official distribution, these files are
 315 already generated, although they were generated on a Unix-compatible
 316 system.  In most cases, the generated files can be used when building on
 317 Windows, but the files listed below as being generated by Flex can be
 318 used when building on Windows only when generated by a Windows version
 319 of Flex, so you will need a Windows version of Flex to do a Windows
 320 build.  Those generated files are removed by the "cleanbld.bat" script,
 321 to make sure that versions left over from a Unix build aren't used.
 322
 323 If you are building from a modified version of an official distribution,
 324 and you modified any of the source files listed below, you will need the
 325 tool(s) that generate output from those source files.
 326
 327 If building from a CVS image, you'll need all the tools to generate C
 328 source.
 329
 330 The "special" files and their requisite tools are:
 331
 332 Source                          Output                  Tool
 333 ------                          ------                  ----
 334 config.h.win32                  config.h                sed
 335 epan/config.h.win32             epan/config.h           sed
 336 image/ethereal.rc.in            image/ethereal.rc       sed
 337 image/tethereal.rc.in           image/tethereal.rc      sed
 338 image/editcap.rc.in             image/editcap.rc        sed
 339 image/mergecap.rc.in            image/mergecap.rc       sed
 340 image/text2pcap.rc.in           image/text2pcap.rc      sed
 341 wiretap/config.h.win32          wiretap/config.h        sed
 342 epan/dfilter/dfilter-scanner.l  epan/dfilter/*.c        Flex
 343 text2pcap-scanner.l             *.c                     Flex
 344 wiretap/ascend-scanner.l        *.c                     Flex
 345 wiretap/ascend-grammar.y        *.c,*.h                 Bison/Yacc
 346 ncp2222.py                      packet-ncp2222.c        Python
 347
 348 make-reg-dotc, packet*.c        register.c              Bash + grep + sed
 349 or
 350 make-reg-dotc.py, packet*.c     register.c              Python
 351
 352 make-tapreg-dotc, tap-*.c       tethereal-tap-register.c
 353                                                         Bash + grep + sed
 354 make-tapreg-dotc, tap files     gtk/ethereal-tap-register.c
 355     in the gtk subdirectory                             Bash + grep + sed
 356
 357 The Makefile.nmake supplied with the Ethereal distribution will, if
 358 PYTHON is defined in config.nmake, attempt to make register.c with
 359 Python, since it is much much much faster than the shell version.  The
 360 reason it is faster is because the shell version launches multiple
 361 processes (grep, sed) for each source file, multiple times.  The Python
 362 script is one process.  This matters a lot on Win32.
 363
 364 If you have a Unix system handy, you can first build on Unix to create
 365 most of the source files that these tools make, then run the build on
 366 Windows.  That will avoid the need for these tools on your Windows
 367 computer.  This won't work for the files in the "image" directory,
 368 however, as those aren't built on Unix - they're only for Windows
 369 builds.  It also won't work for the "config.h" files; whilst those are
 370 built for Unix, they're specific to the platform on which you're
 371 building, and the "config.h" files constructed for a Unix build will not
 372 work with a Windows build.  In addition, it won't work for the files
 373 generated by Flex, as, for a Windows build, those have to be generated
 374 by a Windows version of Flex.
 375
 376 Most of those tools are available for Win32 systems as part of the
 377 Cygwin package:
 378
 379         http://sources.redhat.com/cygwin/
 380
 381 After installing them, you will probably have to modify the config.nmake
 382 file to specify where the Cygwin binaries are installed.
 383
 384 Python for Win32 is available from:
 385
 386         http://www.python.org/
 387
 388
 389 Build an (NSIS based) installer
 390 -------------------------------
 391
 392 If you want to build your own installer, you need to get NSIS from:
 393
 394 http://nsis.sourceforge.net/home/
 395
 396 After installing it, you will probably have to modify the config.nmake
 397 file to specify where the NSIS binaries are installed and wether to use the modern UI or not.
 398 You will need NSIS version 2 or higher, to build an installer with the modern user interface,
 399 and for a much smaller installer (using the lzma compression).
 400
 401 In the ethereal directory, type "nmake -f makefile.nmake packaging" to build the installer.
 402 Please be patient while the compression is done, it will take some time even on fast machines.
 403
 404 You will hopefully now see something like ethereal-setup-0.10.2.exe in the dir packaging/nsis.
 405
 406
 407 Installing GTK-Wimp
 408 -------------------
 409
 410 GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines,
 411 especially with the new "coloured" WinXP theme. It will only take effect
 412 together with the GTK2 version of Ethereal.
 413
 414 No changes to the Ethereal sources are needed, GTK-Wimp simply changes the
 415 way GTK2 displays the widgets (by changing the GTK2 default theme).
 416
 417 GTK-Wimp might already be installed. In this case, the files mentioned below
 418 are already existing at the appropriate places.
 419
 420 If GTK-Wimp isn't installed, you can install it yourself:
 421
 422 1. Go to http://gtk-wimp.sourceforge.net/
 423 2. Download the ZIP archive containing the library and the theme
 424 3. Locate the installation directory of Ethereal (C:\Program Files\Ethereal)
 425 4. Create a subdirectory 'share\themes\Default\gtk-2.0'
 426 5. Drop the file 'gtkrc' in 'share\themes\Default\gtk-2.0'
 427 6. Create a subdirectory named 'lib\gtk-2.0\2.2.0\engines'
 428 7. Drop the 'libwimp.dll' library in 'lib\gtk-2.0\2.2.0\engines'
 429
 430 When you're finished, you should have:
 431
 432 C:\Program Files\Ethereal\lib\gtk-2.0\2.2.0\engines\libwimp.dll
 433 C:\Program Files\Ethereal\share\themes\Default\gtk-2.0\gtkrc
 434
 435 After (re-)starting Ethereal, you should now see it's widgets in the modern
 436 WinXP style on your screen.
 437
 438
 439 Instructions for Cygwin
 440 -----------------------
 441
 442 It is possible to build Ethereal under Cygwin using their version
 443 of XFree86. References:
 444  - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
 445  - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
 446
 447 To get it running, execute the following steps:
 448
 449 1. Install the required cygwin packages (compiler, scripting, X, zlib)
 450    with the CygWin setup.exe tool (http://www.cygwin.com/).
 451    You need the base Xfree86 support plus the X headers package in order
 452    to be able to compile the gtk+ package.
 453
 454 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
 455
 456 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
 457    http://homepage.ntlworld.com/steven.obrien2/
 458
 459  + glib-1.2.10
 460    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
 461           /libs/patches/glib-1.2.10-cygwin.patch
 462
 463  + gtk+-1.2.10
 464    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
 465           /libs/patches/gtk+-1.2.10-cygwin.patch
 466
 467 4. Compile and install both packages after patching (see instructions
 468    at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
 469
 470    Set the path:
 471
 472      $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
 473
 474    For glib-1.2.10:
 475
 476      $ cd glib-1.2.10
 477      $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
 478      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
 479      $ make
 480      $ make check
 481      $ make install
 482
 483    For gtk+-1.2.10:
 484
 485      $ cd gtk+-1.2.10
 486      $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
 487      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
 488      $ make
 489      $ make check
 490      $ make install
 491
 492 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
 493    removing "ethclist.c" from the dependencies.
 494
 495    This patch is required since the private GTK+ clist widget
 496    (was required for earlier versions of GTK+ but prevents Ethereal
 497    from running with cygwin).
 498
 499 6. Configure and make Ethereal:
 500
 501    Set the path (if this has not yet been done earlier)
 502
 503      $ PATH=/opt/gnome/bin:$PATH
 504
 505      $ ./autogen.sh
 506      $ ./configure --config-cache --without-pcap
 507      $ make
 508
 509 7. Start X
 510
 511      $ sh /usr/X11R6/bin/startxwin.sh
 512
 513     Or you can start it from C:\cygwin\usr\X11R6\bin\startxwin.bat
 514
 515 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
 516
 517      $ <ethereal-src>/ethereal
 518
 519     And voila! Behold the mighty sniffer in all its glory!
 520
 521     Note that the plugin dissectors must be installed (make install) if you
 522     want to use them. Note also that running "make install" produces lots of
 523     output to the console; this is normal.
 524
 525 Note: Compiling Ethereal under cygwin takes a lot of time, because the
 526 generation of 'register.c' takes ages. If you only edit one dissector and
 527 you know what you're doing, it is acceptable to uncomment the generation
 528 of the file 'register.c' in Makefile. Look for the 'register.c' target:
 529
 530     register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
 531         @echo Making register.c
 532         # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
 533         @echo Skipping generation of register.c
 534
 535 Of course, you need to generate the 'register.c' file at least once.
 536
 537 Note: You can also capture packets on a cygwin built Ethereal. You then have
 538 to unpack the WinPCap development package, install the files in lib/ and
 539 include/ in say /usr/lib and /usr/include (they must be in the search path of
 540 the compiler and linker, otherwise you have to specify the configure option
 541 --with-pcap=/location/to/pcap so the packet capture functionality can be used.
 542 In order to run Ethereal, you have to add the .dll files in a directory in the
 543 PATH (e.g., /bin).
 544 Should you want packet capturing enabled in the cygwin build, then you have to
 545 remove --without-pcap from step 6.