README.win32

   1 $Id: README.win32,v 1.63 2004/02/22 16:28:47 ulfl 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 Running Ethereal, Tethereal, and Editcap on Win32
  92 =================================================
  93 You need the glib and gtk libraries for running Ethereal.
  94
  95 These packages for win32 can be found at:
  96
  97         http://www.ethereal.com/distribution/win32
  98
  99 and at the home page for the GTK+ for Win32 project:
 100
 101         http://www.gimp.org/~tml/gimp/win32
 102
 103 or
 104         http://www.iki.fi/tml/gimp/win32/
 105
 106 (the mirror nearer to you may be faster).
 107
 108 Plugins (gryphon.dll and mgcp.dll) can go in:
 109         <Ethereal installation directory>\plugins\<version>
 110
 111 Where <version> is the version number, without brackets.  For example,
 112 if you have Ethereal 0.9.8 installed in the default location, plugins
 113 will reside in C:\Program Files\Ethereal\plugins\0.9.8
 114
 115 Yes, the location of plugins needs to be more flexible.
 116
 117 Make sure the glib and gtk DLL's are in your path - i.e., that your
 118 path includes the directory (folder) or directories (folders) in which
 119 those DLLs are found - when you run Ethereal.  This includes gtk-*.dll,
 120 glib-*.dll, gmodule-*.dll, gdk-*.dll, intl.dll, and iconv-*.dll.  As of
 121 the 20000805 GTK+/GLIB distribution, gthread-*.dll is no longer needed.
 122
 123 Note the wiretap*.dll must be in your path as well and if wiretap is changed
 124 be shure to put the new one in your path.
 125
 126 The Win32 Binary distribution, available from
 127
 128         http://www.ethereal.com/distribution/win32
 129
 130 used different version of the GTK+/GLIB libraries at different points
 131 in time:
 132
 133 Ethereal Version                GTK+/GLIB version
 134 ----------------                -----------------
 135 0.8.16 and after                20001226
 136 0.8.11 - 0.8.15                 20000805
 137 0.8.9 - 0.8.10                  20000416
 138 0.8.8 and before                19990828
 139
 140
 141 Capturing Packets
 142 -----------------
 143 In order to capture with Win32, you need to install the NDIS
 144 packet capture driver for your particular Win32 OS; drivers for Windows
 145 9x, Windows NT 4.0, Windows 2000 and Windows XP can be downloaded from the
 146 WinPcap home page:
 147
 148         http://winpcap.polito.it/
 149
 150 or the mirror site at
 151
 152         http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
 153
 154 Compiling the Ethereal distribution from source
 155 ===============================================
 156
 157 You'll need the development packages for GLIB, GTK+, iconv, gettext,
 158 WinPcap, zlib, Net-SNMP, ADNS, and PCRE.  The GLIB, GTK+, and WinPcap
 159 packages are available from the respective home pages for each project
 160 (the same URLs as listed above). The development packages contain header
 161 files and stub libraries to link against.  Precompiled versions of all
 162 of these packages are available at
 163
 164         http://www.ethereal.com/distribution/win32/development/
 165
 166 The ADNS package is also available at its homepage:
 167
 168         http://adns.jgaa.com/
 169
 170 By default, the build process looks for these packages in
 171 C:\ethereal-win32-libs.  You can place them in a different directory, but
 172 you must update config.nmake accordingly.  The default location for each
 173 package is as follows:
 174
 175     Package                               Default Location
 176     -------                               ----------------
 177     adns-1.0-win32-01.zip                 C:\ethereal-win32-libs
 178     glib-2.2.3-20040116.zip               C:\ethereal-win32-libs\glib
 179     glib-dev-2.2.3-20040116.zip           C:\ethereal-win32-libs\glib
 180     gtk+-1.3.0-20030717.zip               C:\ethereal-win32-libs\gtk+
 181     gtk+-dev-1.3.0-20030115.zip           C:\ethereal-win32-libs\gtk+
 182     libiconv-1.9.1.bin.woe32.zip          C:\ethereal-win32-libs\libiconv-1.9.1.bin.woe32
 183     gettext-runtime-0.13.1.zip            C:\ethereal-win32-libs\gettext-runtime-0.13.1
 184     net-snmp-5.1.zip                      C:\ethereal-win32-libs
 185     pcre-4.4.zip                          C:\ethereal-win32-libs
 186     wpdpack_3_0.zip                       C:\ethereal-win32-libs
 187     zlib121-dll.zip                       C:\ethereal-win32-libs\zlib121-dll
 188
 189 (to use the default locations, the directories in question should be
 190 created, and each zip file should be unpacked into the corresponding
 191 directory).  If you only want to change the C:\ethereal-win32-libs
 192 part, you just change the setting of ETHEREAL_LIBS in config.nmake; if
 193 you want to change subdirectories, you'll have to change the individual
 194 item for a package.  (Note that some zip files create the subdirectory -
 195 those zip files just have C:\ethereal-win32-libs in the list above - so
 196 if you don't want the package to be in that subdirectory, you'd have to
 197 rename the directory.)
 198
 199 The gettext runtime package provides intl.dll, which is needed by
 200 GLib 2.2.3.
 201
 202
 203 Compiling the Ethereal distribution using GTK+2
 204 ===============================================
 205
 206 The more recent version 2 of the GTK+ can be used to compile
 207 Ethereal with, but is still considered experimental.
 208
 209 GTK+2 will look better and nicer in some ways, especially for WIN32 users.
 210
 211 You can get the required libraries from:
 212
 213 http://www.gimp.org/~tml/gimp/win32/downloads.html
 214
 215 If you want to try a build with GTK+2.x these Extra libraries are needed
 216
 217     Package                               Default Location
 218     -------                               ----------------
 219     gtk+-2.2.4-20040124.zip               C:\ethereal-win32-libs\gtk2
 220     gtk+-dev-2.2.4-20040124.zip           C:\ethereal-win32-libs\gtk2
 221     pango-1.2.5-20040124.zip              C:\ethereal-win32-libs\gtk2
 222     pango-dev-1.2.5-20040124.zip          C:\ethereal-win32-libs\gtk2
 223     atk-1.4.0.zip                         C:\ethereal-win32-libs\gtk2
 224     atk-dev-1.4.0.zip                     C:\ethereal-win32-libs\gtk2
 225
 226 Be sure to set GTK2_DIR in config.nmake correct, to be able to compile.
 227
 228 Instructions for MS Visual C++
 229 ----------------------------
 230 Modify the config.nmake file in the top directory of the Ethereal source
 231 tree to work for your local configuration; if you don't have Python,
 232 comment out the line that defines PYTHON, otherwise set it to refer to
 233 the pathname of your Python interpreter executable.  You should not have
 234 to modify any other Makefile.
 235
 236 Note that perl is needed to build the documentation, the lines in config.nmake
 237
 238 POD2MAN=$(SH) pod2man
 239 POD2HTML=$(SH) pod2html
 240
 241 requires Cygwin bash and perl to work.
 242
 243 Many of the file and directory names used in the build process go past
 244 the old 8.3 naming limitations.  As a result, at least on Windows NT 4.0,
 245 Windows 2000, Windows XP, and Windows .NET Server, you should use the
 246 newer "cmd.exe" command interpreter instead of the old "command.com",
 247 as the "command.com" on Windows 2000, at least, can't handle non-8.3
 248 directory names.  (It may be that the "command.com" in Windows 95, Windows
 249 98, and Windows Me, as it's the only command interpreter in those systems,
 250 can handle those directories.  If not, it may not be possible to build
 251 Ethereal from the command line on those versions of Windows.)
 252
 253 Be sure that your command-line environment is set up to compile
 254 and link with MSVC++. When installing MSVC++, you can have your
 255 system's environment set up to always allow compiling from the
 256 command line, or you can invoke the vcvars32.bat script, which can
 257 usually be found in the "VC98\Bin" subdirectory of the directory in
 258 which Visual Studio was installed.
 259
 260 The first time you build Ethereal, run the script "cleanbld.bat" in the
 261 top-level Ethereal source directory to make sure that the "config.h"
 262 files will be reconstructed from the "config.h.win32" files.  (If, for
 263 example, you have "config.h" files left over from a Unix build, a
 264 Windows build will fail.)
 265
 266 In the ethereal directory, type "nmake -f makefile.nmake". It will
 267 recurse into the subdirectories as appropriate.
 268
 269 Some generated source is created by traditionally "Unix-ish" tools.
 270
 271 If you are building from an official distribution, these files are
 272 already generated, although they were generated on a Unix-compatible
 273 system.  In most cases, the generated files can be used when building on
 274 Windows, but the files listed below as being generated by Flex can be
 275 used when building on Windows only when generated by a Windows version
 276 of Flex, so you will need a Windows version of Flex to do a Windows
 277 build.  Those generated files are removed by the "cleanbld.bat" script,
 278 to make sure that versions left over from a Unix build aren't used.
 279
 280 If you are building from a modified version of an official distribution,
 281 and you modified any of the source files listed below, you will need the
 282 tool(s) that generate output from those source files.
 283
 284 If building from a CVS image, you'll need all the tools to generate C
 285 source.
 286
 287 The "special" files and their requisite tools are:
 288
 289 Source                          Output                  Tool
 290 ------                          ------                  ----
 291 config.h.win32                  config.h                sed
 292 epan/config.h.win32             epan/config.h           sed
 293 image/ethereal.rc.in            image/ethereal.rc       sed
 294 image/tethereal.rc.in           image/tethereal.rc      sed
 295 image/editcap.rc.in             image/editcap.rc        sed
 296 image/mergecap.rc.in            image/mergecap.rc       sed
 297 image/text2pcap.rc.in           image/text2pcap.rc      sed
 298 wiretap/config.h.win32          wiretap/config.h        sed
 299 epan/dfilter/dfilter-scanner.l  epan/dfilter/*.c        Flex
 300 text2pcap-scanner.l             *.c                     Flex
 301 wiretap/ascend-scanner.l        *.c                     Flex
 302 wiretap/ascend-grammar.y        *.c,*.h                 Bison/Yacc
 303 ncp2222.py                      packet-ncp2222.c        Python
 304
 305 make-reg-dotc, packet*.c        register.c              Bash + grep + sed
 306 or
 307 make-reg-dotc.py, packet*.c     register.c              Python
 308
 309 make-tapreg-dotc, tap-*.c       tethereal-tap-register.c
 310                                                         Bash + grep + sed
 311 make-tapreg-dotc, tap files     gtk/ethereal-tap-register.c
 312     in the gtk subdirectory                             Bash + grep + sed
 313
 314 The Makefile.nmake supplied with the Ethereal distribution will, if
 315 PYTHON is defined in config.nmake, attempt to make register.c with
 316 Python, since it is much much much faster than the shell version.  The
 317 reason it is faster is because the shell version launches multiple
 318 processes (grep, sed) for each source file, multiple times.  The Python
 319 script is one process.  This matters a lot on Win32.
 320
 321 If you have a Unix system handy, you can first build on Unix to create
 322 most of the source files that these tools make, then run the build on
 323 Windows.  That will avoid the need for these tools on your Windows
 324 computer.  This won't work for the files in the "image" directory,
 325 however, as those aren't built on Unix - they're only for Windows
 326 builds.  It also won't work for the "config.h" files; whilst those are
 327 built for Unix, they're specific to the platform on which you're
 328 building, and the "config.h" files constructed for a Unix build will not
 329 work with a Windows build.  In addition, it won't work for the files
 330 generated by Flex, as, for a Windows build, those have to be generated
 331 by a Windows version of Flex.
 332
 333 Most of those tools are available for Win32 systems as part of the
 334 Cygwin package:
 335
 336         http://sources.redhat.com/cygwin/
 337
 338 After installing them, you will probably have to modify the config.nmake
 339 file to specify where the Cygwin binaries are installed.
 340
 341 Python for Win32 is available from
 342
 343         http://www.python.org/
 344
 345
 346 If you want to build an installer you need to get NSIS from:
 347
 348 http://nsis.sourceforge.net/home/
 349
 350 After installing it, you will probably have to modify the config.nmake
 351 file to specify where the binaries are installed and wether to use the modern UI or not.
 352 You will need NSIS version 2 or higher, to build an installer with the modern user interface,
 353 and for a much smaller installer (using the lzma compression).
 354
 355 In the ethereal directory, type "nmake -f makefile.nmake packaging" to build the installer.
 356
 357
 358 Instructions for Cygwin
 359 -----------------------
 360
 361 It is possible to build Ethereal under Cygwin using their version
 362 of XFree86. References:
 363  - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
 364  - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
 365
 366 To get it running, execute the following steps:
 367
 368 1. Install the required cygwin packages (compiler, scripting, X, zlib)
 369    with the CygWin setup.exe tool (http://www.cygwin.com/).
 370    You need the base Xfree86 support plus the X headers package in order
 371    to be able to compile the gtk+ package.
 372
 373 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
 374
 375 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
 376    http://homepage.ntlworld.com/steven.obrien2/
 377
 378  + glib-1.2.10
 379    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
 380           /libs/patches/glib-1.2.10-cygwin.patch
 381
 382  + gtk+-1.2.10
 383    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
 384           /libs/patches/gtk+-1.2.10-cygwin.patch
 385
 386 4. Compile and install both packages after patching (see instructions
 387    at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
 388
 389    Set the path:
 390
 391      $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
 392
 393    For glib-1.2.10:
 394
 395      $ cd glib-1.2.10
 396      $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
 397      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
 398      $ make
 399      $ make check
 400      $ make install
 401
 402    For gtk+-1.2.10:
 403
 404      $ cd gtk+-1.2.10
 405      $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
 406      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
 407      $ make
 408      $ make check
 409      $ make install
 410
 411 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
 412    removing "ethclist.c" from the dependencies.
 413
 414    This patch is required since the private GTK+ clist widget
 415    (was required for earlier versions of GTK+ but prevents Ethereal
 416    from running with cygwin).
 417
 418 6. Configure and make Ethereal:
 419
 420    Set the path (if this has not yet been done earlier)
 421
 422      $ PATH=/opt/gnome/bin:$PATH
 423
 424      $ ./autogen.sh --without-pcap --without-plugins
 425      $ ./configure --without-pcap --without-plugins
 426      $ make
 427
 428    This make will eventually stop, but it is required as e.g., the
 429    GTK binaries are built then.
 430
 431      $ make ethereal.exe
 432
 433 7. Start X
 434
 435      $ sh /usr/X11R6/bin/startxwin.sh
 436
 437    For non-US keyboard layouts, use (replace 'be' with your layout):
 438
 439      $ setxkbmap.exe -layout be
 440
 441 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
 442
 443      $ <ethereal-src>/ethereal
 444
 445    And voila! Behold the mighty sniffer in all its glory!
 446
 447 Something is wrong with the makefile that gets generated, so it doesn't work
 448 just running make.
 449 I am not curious enough to look at why 'make' doesnt work; 'make ethereal.exe'
 450 works well enough for me.
 451
 452 Note: Compiling Ethereal under cygwin takes a lot of time, because the
 453 generation of 'register.c' takes ages. If you only edit one dissector and
 454 you know what you're doing, it is acceptable to uncomment the generation
 455 of the file 'register.c' in Makefile. Look for the 'register.c' target:
 456
 457     register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
 458         @echo Making register.c
 459         # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
 460         @echo Skipping generation of register.c
 461
 462 Of course, you need to generate the 'register.c' file at least once.