1 $Id: README.win32,v 1.65 2004/02/24 19:42:22 ulfl Exp $
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 Running Ethereal, Tethereal, and Editcap on Win32
92 =================================================
93 You need the glib and gtk libraries for running Ethereal.
95 These packages for win32 can be found at:
97 http://www.ethereal.com/distribution/win32
99 and at the home page for the GTK+ for Win32 project:
101 http://www.gimp.org/~tml/gimp/win32
104 http://www.iki.fi/tml/gimp/win32/
106 (the mirror nearer to you may be faster).
108 Plugins (gryphon.dll and mgcp.dll) can go in:
109 <Ethereal installation directory>\plugins\<version>
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
115 Yes, the location of plugins needs to be more flexible.
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.
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.
126 The Win32 Binary distribution, available from
128 http://www.ethereal.com/distribution/win32
130 used different version of the GTK+/GLIB libraries at different points
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
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
148 http://winpcap.polito.it/
150 or the mirror site at
152 http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
154 Compiling the Ethereal distribution from source
155 ===============================================
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
164 http://www.ethereal.com/distribution/win32/development/
166 The ADNS package is also available at its homepage:
168 http://adns.jgaa.com/
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:
175 Package Default Location
176 ------- ----------------
177 glib-2.2.3-20040116.zip C:\ethereal-win32-libs\glib
178 glib-dev-2.2.3-20040116.zip C:\ethereal-win32-libs\glib
179 gtk+-1.3.0-20030717.zip C:\ethereal-win32-libs\gtk+
180 gtk+-dev-1.3.0-20030115.zip C:\ethereal-win32-libs\gtk+
181 libiconv-1.9.1.bin.woe32.zip C:\ethereal-win32-libs\libiconv-1.9.1.bin.woe32
182 gettext-runtime-0.13.1.zip C:\ethereal-win32-libs\gettext-runtime-0.13.1
183 net-snmp-5.1.zip C:\ethereal-win32-libs
184 wpdpack_3_0.zip C:\ethereal-win32-libs
188 adns-1.0-win32-01.zip C:\ethereal-win32-libs
189 pcre-4.4.zip C:\ethereal-win32-libs
190 zlib121-dll.zip C:\ethereal-win32-libs\zlib121-dll
192 (to use the default locations, the directories in question should be
193 created, and each zip file should be unpacked into the corresponding
194 directory). If you only want to change the C:\ethereal-win32-libs
195 part, you just change the setting of ETHEREAL_LIBS in config.nmake; if
196 you want to change subdirectories, you'll have to change the individual
197 item for a package. (Note that some zip files create the subdirectory -
198 those zip files just have C:\ethereal-win32-libs in the list above - so
199 if you don't want the package to be in that subdirectory, you'd have to
200 rename the directory.)
202 The gettext runtime package provides intl.dll, which is needed by
206 Compiling the Ethereal distribution using GTK+2
207 -----------------------------------------------
209 The more recent version 2 of the GTK+ can be used to compile
210 Ethereal with, but is still considered beta.
212 GTK+2 will look better and nicer in some ways, especially for WIN32 users.
214 You can get the required libraries from:
216 http://www.ethereal.com/distribution/win32/development/gtk2
220 http://www.gimp.org/~tml/gimp/win32/downloads.html
222 If you want to try a build with GTK+2.x these Extra libraries are needed
224 Package Default Location
225 ------- ----------------
226 gtk+-2.2.4-20040124.zip C:\ethereal-win32-libs\gtk2
227 gtk+-dev-2.2.4-20040124.zip C:\ethereal-win32-libs\gtk2
228 pango-1.2.5-20040124.zip C:\ethereal-win32-libs\gtk2
229 pango-dev-1.2.5-20040124.zip C:\ethereal-win32-libs\gtk2
230 atk-1.4.0.zip C:\ethereal-win32-libs\gtk2
231 atk-dev-1.4.0.zip C:\ethereal-win32-libs\gtk2
235 gtk-wimp-0.5.3-bin.zip C:\ethereal-win32-libs\gtk-wimp
237 Be sure to set GTK2_DIR in config.nmake correct, to be able to compile.
239 Instructions for MS Visual C++
240 ----------------------------
241 Modify the config.nmake file in the top directory of the Ethereal source
242 tree to work for your local configuration; if you don't have Python,
243 comment out the line that defines PYTHON, otherwise set it to refer to
244 the pathname of your Python interpreter executable. You should not have
245 to modify any other Makefile.
247 Note that perl is needed to build the documentation, the lines in config.nmake
249 POD2MAN=$(SH) pod2man
250 POD2HTML=$(SH) pod2html
252 requires Cygwin bash and perl to work.
254 Many of the file and directory names used in the build process go past
255 the old 8.3 naming limitations. As a result, at least on Windows NT 4.0,
256 Windows 2000, Windows XP, and Windows .NET Server, you should use the
257 newer "cmd.exe" command interpreter instead of the old "command.com",
258 as the "command.com" on Windows 2000, at least, can't handle non-8.3
259 directory names. (It may be that the "command.com" in Windows 95, Windows
260 98, and Windows Me, as it's the only command interpreter in those systems,
261 can handle those directories. If not, it may not be possible to build
262 Ethereal from the command line on those versions of Windows.)
264 Be sure that your command-line environment is set up to compile
265 and link with MSVC++. When installing MSVC++, you can have your
266 system's environment set up to always allow compiling from the
267 command line, or you can invoke the vcvars32.bat script, which can
268 usually be found in the "VC98\Bin" subdirectory of the directory in
269 which Visual Studio was installed.
271 The first time you build Ethereal, run the script "cleanbld.bat" in the
272 top-level Ethereal source directory to make sure that the "config.h"
273 files will be reconstructed from the "config.h.win32" files. (If, for
274 example, you have "config.h" files left over from a Unix build, a
275 Windows build will fail.)
277 In the ethereal directory, type "nmake -f makefile.nmake". It will
278 recurse into the subdirectories as appropriate.
280 Some generated source is created by traditionally "Unix-ish" tools.
282 If you are building from an official distribution, these files are
283 already generated, although they were generated on a Unix-compatible
284 system. In most cases, the generated files can be used when building on
285 Windows, but the files listed below as being generated by Flex can be
286 used when building on Windows only when generated by a Windows version
287 of Flex, so you will need a Windows version of Flex to do a Windows
288 build. Those generated files are removed by the "cleanbld.bat" script,
289 to make sure that versions left over from a Unix build aren't used.
291 If you are building from a modified version of an official distribution,
292 and you modified any of the source files listed below, you will need the
293 tool(s) that generate output from those source files.
295 If building from a CVS image, you'll need all the tools to generate C
298 The "special" files and their requisite tools are:
302 config.h.win32 config.h sed
303 epan/config.h.win32 epan/config.h sed
304 image/ethereal.rc.in image/ethereal.rc sed
305 image/tethereal.rc.in image/tethereal.rc sed
306 image/editcap.rc.in image/editcap.rc sed
307 image/mergecap.rc.in image/mergecap.rc sed
308 image/text2pcap.rc.in image/text2pcap.rc sed
309 wiretap/config.h.win32 wiretap/config.h sed
310 epan/dfilter/dfilter-scanner.l epan/dfilter/*.c Flex
311 text2pcap-scanner.l *.c Flex
312 wiretap/ascend-scanner.l *.c Flex
313 wiretap/ascend-grammar.y *.c,*.h Bison/Yacc
314 ncp2222.py packet-ncp2222.c Python
316 make-reg-dotc, packet*.c register.c Bash + grep + sed
318 make-reg-dotc.py, packet*.c register.c Python
320 make-tapreg-dotc, tap-*.c tethereal-tap-register.c
322 make-tapreg-dotc, tap files gtk/ethereal-tap-register.c
323 in the gtk subdirectory Bash + grep + sed
325 The Makefile.nmake supplied with the Ethereal distribution will, if
326 PYTHON is defined in config.nmake, attempt to make register.c with
327 Python, since it is much much much faster than the shell version. The
328 reason it is faster is because the shell version launches multiple
329 processes (grep, sed) for each source file, multiple times. The Python
330 script is one process. This matters a lot on Win32.
332 If you have a Unix system handy, you can first build on Unix to create
333 most of the source files that these tools make, then run the build on
334 Windows. That will avoid the need for these tools on your Windows
335 computer. This won't work for the files in the "image" directory,
336 however, as those aren't built on Unix - they're only for Windows
337 builds. It also won't work for the "config.h" files; whilst those are
338 built for Unix, they're specific to the platform on which you're
339 building, and the "config.h" files constructed for a Unix build will not
340 work with a Windows build. In addition, it won't work for the files
341 generated by Flex, as, for a Windows build, those have to be generated
342 by a Windows version of Flex.
344 Most of those tools are available for Win32 systems as part of the
347 http://sources.redhat.com/cygwin/
349 After installing them, you will probably have to modify the config.nmake
350 file to specify where the Cygwin binaries are installed.
352 Python for Win32 is available from:
354 http://www.python.org/
357 Build an (NSIS based) installer
358 -------------------------------
360 If you want to build your own installer, you need to get NSIS from:
362 http://nsis.sourceforge.net/home/
364 After installing it, you will probably have to modify the config.nmake
365 file to specify where the NSIS binaries are installed and wether to use the modern UI or not.
366 You will need NSIS version 2 or higher, to build an installer with the modern user interface,
367 and for a much smaller installer (using the lzma compression).
369 In the ethereal directory, type "nmake -f makefile.nmake packaging" to build the installer.
370 Please be patient while the compression is done, it will take some time even on fast machines.
372 You will hopefully now see something like ethereal-setup-0.10.2.exe in the dir packaging/nsis.
378 GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines,
379 especially with the new "coloured" WinXP theme. It will only take effect
380 together with the GTK2 version of Ethereal.
382 No changes to the Ethereal sources are needed, GTK-Wimp simply changes the
383 way GTK2 displays the widgets (by changing the GTK2 default theme).
385 GTK-Wimp might already be installed. In this case, the files mentioned below
386 are already existing at the appropriate places.
388 If GTK-Wimp isn't installed, you can install it yourself:
390 1. Go to http://gtk-wimp.sourceforge.net/
391 2. Download the ZIP archive containing the library and the theme
392 3. Locate the installation directory of Ethereal (C:\Program Files\Ethereal)
393 4. Create a subdirectory 'share\themes\Default\gtk-2.0'
394 5. Drop the file 'gtkrc' in 'share\themes\Default\gtk-2.0'
395 6. Create a subdirectory named 'lib\gtk-2.0\2.2.0\engines'
396 7. Drop the 'libwimp.dll' library in 'lib\gtk-2.0\2.2.0\engines'
398 When you're finished, you should have:
400 C:\Program Files\Ethereal\lib\gtk-2.0\2.2.0\engines\libwimp.dll
401 C:\Program Files\Ethereal\share\themes\Default\gtk-2.0\gtkrc
403 After (re-)starting Ethereal, you should now see it's widgets in the modern
404 WinXP style on your screen.
407 Instructions for Cygwin
408 -----------------------
410 It is possible to build Ethereal under Cygwin using their version
411 of XFree86. References:
412 - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
413 - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
415 To get it running, execute the following steps:
417 1. Install the required cygwin packages (compiler, scripting, X, zlib)
418 with the CygWin setup.exe tool (http://www.cygwin.com/).
419 You need the base Xfree86 support plus the X headers package in order
420 to be able to compile the gtk+ package.
422 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
424 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
425 http://homepage.ntlworld.com/steven.obrien2/
428 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
429 /libs/patches/glib-1.2.10-cygwin.patch
432 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
433 /libs/patches/gtk+-1.2.10-cygwin.patch
435 4. Compile and install both packages after patching (see instructions
436 at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
440 $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
445 $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
446 $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
454 $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
455 $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
460 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
461 removing "ethclist.c" from the dependencies.
463 This patch is required since the private GTK+ clist widget
464 (was required for earlier versions of GTK+ but prevents Ethereal
465 from running with cygwin).
467 6. Configure and make Ethereal:
469 Set the path (if this has not yet been done earlier)
471 $ PATH=/opt/gnome/bin:$PATH
473 $ ./autogen.sh --without-pcap --without-plugins
474 $ ./configure --without-pcap --without-plugins
477 This make will eventually stop, but it is required as e.g., the
478 GTK binaries are built then.
484 $ sh /usr/X11R6/bin/startxwin.sh
486 For non-US keyboard layouts, use (replace 'be' with your layout):
488 $ setxkbmap.exe -layout be
490 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
492 $ <ethereal-src>/ethereal
494 And voila! Behold the mighty sniffer in all its glory!
496 Something is wrong with the makefile that gets generated, so it doesn't work
498 I am not curious enough to look at why 'make' doesnt work; 'make ethereal.exe'
499 works well enough for me.
501 Note: Compiling Ethereal under cygwin takes a lot of time, because the
502 generation of 'register.c' takes ages. If you only edit one dissector and
503 you know what you're doing, it is acceptable to uncomment the generation
504 of the file 'register.c' in Makefile. Look for the 'register.c' target:
506 register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
507 @echo Making register.c
508 # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
509 @echo Skipping generation of register.c
511 Of course, you need to generate the 'register.c' file at least once.