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:
9 http://www.ethereal.com/distribution/win32
11 and any of its mirrors.
13 The installation package allows you to install:
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
25 Additionally, the installation package contains a "plugins"
26 option, which installs some additional dissector plugins
27 for use with Ethereal and Tethereal.
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
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.
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
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:
52 http://winpcap.polito.it/
56 http://winpcap.mirror.ethereal.com/
60 http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/
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.
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:
73 http://windump.polito.it/
77 http://windump.mirror.ethereal.com/
81 http://www.mirrors.wiretapped.net/security/packet-capture/windump/
83 They also make Analyzer, a GUI sniffer for Win32:
85 http://analyzer.polito.it/
87 The rest of this documentation is only interesting if
88 you want to compile Ethereal yourself.
91 Compiling the Ethereal distribution from source
92 ===============================================
96 You can find a comprehensive guide how to develop Ethereal in the
97 Developer's Guide, which you can find (and much more info) at:
99 http://wiki.ethereal.com/Development
101 The guide contains detailed information how to setup the development
102 environment and it's usage.
106 MS Visual C++ Version 6
107 This is the common compiler used for building Ethereal on win32.
109 MS Visual C++ Version 7 / VC.NET
110 Currently unsupported for two reasons:
111 -the licence agreement does NOT allow you to compile GPL code.
112 -there are serious problems in using DLL's compiled with MS VC6.
113 See section "Problems with MS Visual C++ Version 7 / VC.NET" below.
116 Ethereal can entirely be built with cygwin GCC. However the built binaries will
117 only run in a cygwin environment, so they are not standalone Win32 applications.
118 It is however not excluded that native Win32 code can be compiled on cygwin GCC
119 but you then have to use -mms-bitfields as a strict minimum and probably
120 -mno-cygwin or a similar compiler flag too.
121 See section below for instructions.
124 Automated library download
125 --------------------------
126 Before using the automated download, be sure to edit the config.nmake file
127 to suit your needs. Especially have a look at the ETHEREAL_LIBS setting.
128 However, the defaults should be working well for a first start.
130 If you've installed Microsoft Visual C++ (MSVC), you can run:
132 nmake -f makefile.nmake setup
134 This will first check the availability of all required tools and then uses
135 the tool wget to download each package file (together around 30MB!) from the
138 http://anonsvn.ethereal.com/ethereal-win32-libs/trunk/packages/
140 and unpack it in the $ETHEREAL_LIBS directory.
142 If you have problems downloading the files, you might be connected to the
143 internet through a proxy/firewall. In this case see the wget documentation
144 to configure wget accordingly.
149 If the automated library download finished sucessfully, you should have all
150 libraries on your machine at the right places. So you don't have to read this,
151 unless you are interested which libraries are used.
153 You'll need the development packages for GLIB, GTK+, iconv, gettext,
154 WinPcap, Net-SNMP, and optionally ADNS, PCRE and zlib. The development
155 packages contain header files and stub libraries to link against.
157 PRECOMPILED VERSIONS OF ALL OF THESE PACKAGES ARE AVAILABLE AT:
159 http://anonsvn.ethereal.com/ethereal-win32-libs/trunk/packages/
162 The GLIB, GTK+, iconv, gettext packages for win32 can be found at the home
163 page for the GTK+ for Win32 project:
165 http://www.gimp.org/~tml/gimp/win32 or the mirror
166 http://www.iki.fi/tml/gimp/win32/
168 The Net-SNMP package for win32 is available at its homepage:
172 The WinPcap package is available at its homepage:
174 http://winpcap.polito.it/ or the mirror
175 http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
177 The optional ADNS package for win32 is available at its homepage:
179 http://adns.jgaa.com/
181 The optional PCRE package (Perl Compatible Regular Expressions) for win32 is
182 available at its homepage:
184 http://gnuwin32.sourceforge.net/packages/pcre.htm
186 The optional zlib package for win32 is available at its homepage:
188 http://www.gzip.org/zlib/
191 By default, the build process looks for these packages in
192 C:\ethereal-win32-libs. You can place them in a different directory, but
193 you must update the ETHEREAL_LIBS variable in config.nmake accordingly.
195 The following lists the packages needed to compile Ethereal and the default
196 locations where to unpack them, when the above method isn't used.
198 Package Default Location
199 ------- ----------------
200 glib-2.2.3-20040116.zip C:\ethereal-win32-libs\glib
201 glib-dev-2.2.3-20040116.zip C:\ethereal-win32-libs\glib
202 gtk+-1.3.0-20030717.zip C:\ethereal-win32-libs\gtk+
203 gtk+-dev-1.3.0-20030115.zip C:\ethereal-win32-libs\gtk+
204 libiconv-1.9.1.bin.woe32.zip C:\ethereal-win32-libs\libiconv-1.9.1.bin.woe32
205 gettext-runtime-0.13.1.zip C:\ethereal-win32-libs\gettext-runtime-0.13.1
206 net-snmp-5.1.zip C:\ethereal-win32-libs
207 wpdpack_3_0.zip C:\ethereal-win32-libs
211 adns-1.0-win32-03.zip C:\ethereal-win32-libs
212 pcre-4.4.zip C:\ethereal-win32-libs
213 zlib122-dll.zip C:\ethereal-win32-libs\zlib122-dll
215 (to use the default locations, the directories in question should be
216 created, and each zip file should be unpacked into the corresponding
217 directory). If you only want to change the C:\ethereal-win32-libs
218 part, you just change the setting of ETHEREAL_LIBS in config.nmake; if
219 you want to change subdirectories, you'll have to change the individual
220 item for a package. (Note that some zip files create the subdirectory -
221 those zip files just have C:\ethereal-win32-libs in the list above - so
222 if you don't want the package to be in that subdirectory, you'd have to
223 rename the directory.)
225 The gettext runtime package provides intl.dll, which is needed by
229 Compiling the Ethereal distribution using GTK+2
230 -----------------------------------------------
232 The more recent version 2 of the GTK+ can be used to compile
233 Ethereal with, but is still considered beta.
235 GTK+2 will look better in various ways, especially for WIN32 users.
237 You can get the required libraries from:
239 http://www.ethereal.com/distribution/win32/development/gtk2
241 or (like the GTK+1 libraries from the GTK+ for Win32 project):
243 http://www.gimp.org/~tml/gimp/win32/downloads.html
245 If you want to try a build with GTK+2.x these Extra libraries are needed
247 Package Default Location
248 ------- ----------------
249 gtk+-2.2.4-20040124.zip C:\ethereal-win32-libs\gtk2
250 gtk+-dev-2.2.4-20040124.zip C:\ethereal-win32-libs\gtk2
251 pango-1.2.5-20040124.zip C:\ethereal-win32-libs\gtk2
252 pango-dev-1.2.5-20040124.zip C:\ethereal-win32-libs\gtk2
253 atk-1.4.0.zip C:\ethereal-win32-libs\gtk2
254 atk-dev-1.4.0.zip C:\ethereal-win32-libs\gtk2
258 gtk-wimp-0.5.3-bin.zip C:\ethereal-win32-libs\gtk-wimp
260 Be sure to set GTK2_DIR in config.nmake correct, to be able to compile.
262 Running your freshly compiled Ethereal
263 --------------------------------------
265 Make sure the glib and gtk DLL's are in your path or you use a directory
266 where all required DLL's and the exe files reside.- i.e., that your
267 path includes the directory (folder) or directories (folders) in which
268 those DLLs are found - when you run Ethereal.
270 Note the wiretap*.dll must be in your path as well and if wiretap is changed
271 be sure to put the new one in your path.
273 Plugins (gryphon.dll and mgcp.dll) can go in:
274 <Ethereal installation directory>\plugins\<version>
276 Where <version> is the version number, without brackets. For example,
277 if you have Ethereal 0.9.8 installed in the default location, plugins
278 will reside in C:\Program Files\Ethereal\plugins\0.9.8
280 Yes, the location of plugins needs to be more flexible.
282 Instructions for MS Visual C++
283 ----------------------------
284 Modify the config.nmake file in the top directory of the Ethereal source
285 tree to work for your local configuration; if you don't have Python,
286 comment out the line that defines PYTHON, otherwise set it to refer to
287 the pathname of your Python interpreter executable. You should not have
288 to modify any other Makefile.
290 Note that perl is needed to build the documentation, the lines in config.nmake
292 POD2MAN=$(SH) pod2man
293 POD2HTML=$(SH) pod2html
295 requires Cygwin bash and perl to work.
297 Many of the file and directory names used in the build process go past
298 the old 8.3 naming limitations. As a result, at least on Windows NT 4.0,
299 Windows 2000, Windows XP, and Windows .NET Server, you should use the
300 newer "cmd.exe" command interpreter instead of the old "command.com",
301 as the "command.com" on Windows 2000, at least, can't handle non-8.3
302 directory names. (It may be that the "command.com" in Windows 95, Windows
303 98, and Windows Me, as it's the only command interpreter in those systems,
304 can handle those directories. If not, it may not be possible to build
305 Ethereal from the command line on those versions of Windows.)
307 Be sure that your command-line environment is set up to compile
308 and link with MSVC++. When installing MSVC++, you can have your
309 system's environment set up to always allow compiling from the
310 command line, or you can invoke the vcvars32.bat script, which can
311 usually be found in the "VC98\Bin" subdirectory of the directory in
312 which Visual Studio was installed.
314 The first time you build Ethereal, run the script "cleanbld.bat" in the
315 top-level Ethereal source directory to make sure that the "config.h"
316 files will be reconstructed from the "config.h.win32" files. (If, for
317 example, you have "config.h" files left over from a Unix build, a
318 Windows build will fail.)
320 In the ethereal directory, type "nmake -f makefile.nmake". It will
321 recurse into the subdirectories as appropriate.
323 Some generated source is created by traditionally "Unix-ish" tools.
325 If you are building from an official distribution, these files are
326 already generated, although they were generated on a Unix-compatible
327 system. In most cases, the generated files can be used when building on
328 Windows, but the files listed below as being generated by Flex can be
329 used when building on Windows only when generated by a Windows version
330 of Flex, so you will need a Windows version of Flex to do a Windows
331 build. Those generated files are removed by the "cleanbld.bat" script,
332 to make sure that versions left over from a Unix build aren't used.
334 If you are building from a modified version of an official distribution,
335 and you modified any of the source files listed below, you will need the
336 tool(s) that generate output from those source files.
338 If building from a CVS image, you'll need all the tools to generate C
341 The "special" files and their requisite tools are:
345 config.h.win32 config.h sed
346 epan/config.h.win32 epan/config.h sed
347 image/ethereal.rc.in image/ethereal.rc sed
348 image/tethereal.rc.in image/tethereal.rc sed
349 image/editcap.rc.in image/editcap.rc sed
350 image/mergecap.rc.in image/mergecap.rc sed
351 image/text2pcap.rc.in image/text2pcap.rc sed
352 wiretap/config.h.win32 wiretap/config.h sed
353 epan/dfilter/dfilter-scanner.l epan/dfilter/*.c Flex
354 text2pcap-scanner.l *.c Flex
355 wiretap/ascend-scanner.l *.c Flex
356 wiretap/ascend-grammar.y *.c,*.h Bison/Yacc
357 ncp2222.py packet-ncp2222.c Python
359 make-reg-dotc, packet*.c register.c Bash + grep + sed
361 make-reg-dotc.py, packet*.c register.c Python
363 make-tapreg-dotc, tap-*.c tethereal-tap-register.c
365 make-tapreg-dotc, tap files gtk/ethereal-tap-register.c
366 in the gtk subdirectory Bash + grep + sed
368 The Makefile.nmake supplied with the Ethereal distribution will, if
369 PYTHON is defined in config.nmake, attempt to make register.c with
370 Python, since it is much much much faster than the shell version. The
371 reason it is faster is because the shell version launches multiple
372 processes (grep, sed) for each source file, multiple times. The Python
373 script is one process. This matters a lot on Win32.
375 If you have a Unix system handy, you can first build on Unix to create
376 most of the source files that these tools make, then run the build on
377 Windows. That will avoid the need for these tools on your Windows
378 computer. This won't work for the files in the "image" directory,
379 however, as those aren't built on Unix - they're only for Windows
380 builds. It also won't work for the "config.h" files; whilst those are
381 built for Unix, they're specific to the platform on which you're
382 building, and the "config.h" files constructed for a Unix build will not
383 work with a Windows build. In addition, it won't work for the files
384 generated by Flex, as, for a Windows build, those have to be generated
385 by a Windows version of Flex.
387 Most of those tools are available for Win32 systems as part of the
390 http://www.cygwin.com/
392 After installing them, you will probably have to modify the config.nmake
393 file to specify where the Cygwin binaries are installed.
394 Note that installing cygwin with the "Default Text File Type" set to DOS
395 may break the compilation because all the required tools may not be found.
396 Set this parameter to UNIX instead.
398 Python for Win32 is available from:
400 http://www.python.org/
403 Build an (NSIS based) installer
404 -------------------------------
406 If you want to build your own installer, you need to get NSIS from:
408 http://nsis.sourceforge.net/home/
410 After installing it, you will probably have to modify the config.nmake
411 file to specify where the NSIS binaries are installed and wether to use the modern UI or not.
412 You will need NSIS version 2 or higher, to build an installer with the modern user interface,
413 and for a much smaller installer (using the lzma compression).
415 In the ethereal directory, type "nmake -f makefile.nmake packaging" to build the installer.
416 Please be patient while the compression is done, it will take some time even on fast machines.
418 You will hopefully now see something like ethereal-setup-0.10.2.exe in the dir packaging/nsis.
424 GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines,
425 especially with the new "coloured" WinXP theme. It will only take effect
426 together with the GTK2 version of Ethereal.
428 No changes to the Ethereal sources are needed, GTK-Wimp simply changes the
429 way GTK2 displays the widgets (by changing the GTK2 default theme).
431 GTK-Wimp might already be installed. In this case, the files mentioned below
432 are already existing at the appropriate places.
434 If GTK-Wimp isn't installed, you can install it yourself:
436 1. Go to http://gtk-wimp.sourceforge.net/
437 2. Download the ZIP archive containing the library and the theme
438 3. Locate the installation directory of Ethereal (C:\Program Files\Ethereal)
439 4. Create a subdirectory 'share\themes\Default\gtk-2.0'
440 5. Drop the file 'gtkrc' in 'share\themes\Default\gtk-2.0'
441 6. Create a subdirectory named 'lib\gtk-2.0\2.2.0\engines'
442 7. Drop the 'libwimp.dll' library in 'lib\gtk-2.0\2.2.0\engines'
444 When you're finished, you should have:
446 C:\Program Files\Ethereal\lib\gtk-2.0\2.2.0\engines\libwimp.dll
447 C:\Program Files\Ethereal\share\themes\Default\gtk-2.0\gtkrc
449 After (re-)starting Ethereal, you should now see it's widgets in the modern
450 WinXP style on your screen.
453 Problems with MS Visual C++ Version 7 / VC.NET
454 ----------------------------------------------
456 Beside licensing problems with these compilers, there are known problems
457 with DLL's. If Ethereal is compiled with MSVC Version 7, there are
458 conflicts in the MSVCRT DLL's, The MSVCRT.DLL includes the standard
459 ANSI-C functions like fopen, malloc, etc.. MSVCRT.DLL is shipped with
460 the MSVC 6 compiler versions, and dynamically linked to prebuild DLL's
461 like the one's for gtk, glib and such. The MSVC 7 compiler now uses and
462 ships MSVCRT71.DLL with it, which is incompatible with MSVCRT.DLL. So
463 when using the MSVC 7 compiler, some parts of the Ethereal code uses
464 MSVCRT71.DLL, and some others (indirectly from e.g. the gtk DLL) will
465 use MSVCRT.DLL. This will result in incorrect file handles and such.
467 The same problem seems to apply on all MSVC compilers after version 6, like the
468 "Microsoft Visual C++ Toolkit 2003".
471 Instructions for Cygwin
472 -----------------------
474 It is possible to build Ethereal under Cygwin using their version
475 of XFree86. References:
476 - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
477 - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
479 To get it running, execute the following steps:
481 1. Install the required cygwin packages (compiler, scripting, X, zlib)
482 with the CygWin setup.exe tool (http://www.cygwin.com/).
483 You need the base Xfree86 support plus the X headers package in order
484 to be able to compile the gtk+ package.
486 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
488 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
489 http://homepage.ntlworld.com/steven.obrien2/
492 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
493 /libs/patches/glib-1.2.10-cygwin.patch
496 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
497 /libs/patches/gtk+-1.2.10-cygwin.patch
499 4. Compile and install both packages after patching (see instructions
500 at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
504 $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
509 $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
510 $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
518 $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
519 $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
524 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
525 removing "ethclist.c" from the dependencies.
527 This patch is required since the private GTK+ clist widget
528 (was required for earlier versions of GTK+ but prevents Ethereal
529 from running with cygwin).
531 6. Configure and make Ethereal:
533 Set the path (if this has not yet been done earlier)
535 $ PATH=/opt/gnome/bin:$PATH
538 $ ./configure --config-cache --without-pcap
543 $ sh /usr/X11R6/bin/startxwin.sh
545 Or you can start it from C:\cygwin\usr\X11R6\bin\startxwin.bat
547 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
549 $ <ethereal-src>/ethereal
551 And voila! Behold the mighty sniffer in all its glory!
553 Note that the plugin dissectors must be installed (make install) if you
554 want to use them. Note also that running "make install" produces lots of
555 output to the console; this is normal.
557 Note: Compiling Ethereal under cygwin takes a lot of time, because the
558 generation of 'register.c' takes ages. If you only edit one dissector and
559 you know what you're doing, it is acceptable to uncomment the generation
560 of the file 'register.c' in Makefile. Look for the 'register.c' target:
562 register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
563 @echo Making register.c
564 # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
565 @echo Skipping generation of register.c
567 Of course, you need to generate the 'register.c' file at least once.
569 Note: You can also capture packets on a cygwin built Ethereal. You then have
570 to unpack the WinPCap development package, install the files in lib/ and
571 include/ in say /usr/lib and /usr/include (they must be in the search path of
572 the compiler and linker, otherwise you have to specify the configure option
573 --with-pcap=/location/to/pcap so the packet capture functionality can be used.
574 In order to run Ethereal, you have to add the .dll files in a directory in the
576 Should you want packet capturing enabled in the cygwin build, then you have to
577 remove --without-pcap from step 6.