1 $Id: README.win32,v 1.54 2003/12/12 16:06:29 gerald 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 and any of its mirrors.
9 The installation package allows you to install:
11 o Ethereal - the GUI version
12 o Tethereal - the console, line-mode version
13 o Editcap - a console, line-mode utility to convert
14 capture files from one format to another.
15 (The same functions are available in Ethereal)
16 o Text2Pcap - a console, line-mode utility to generate
17 a capture file from an ASCII hexdump of packets
18 o Mergecap - a console, line-mode utility to merge two
19 capture files into one
21 Additionally, the installation package contains a "plugins"
22 option, which installs the Gryphon, MGCP and GIOP dissector plugins
23 for use with Ethereal and Tethereal.
25 All binaries in Ethereal package are now built with debugging
26 information embedded. If you are experiencing a crash when running
27 Ethereal or other binaries, Dr. Watson or your debugger
28 can use the information embedded in the binary to provide useful
29 information to the Ethereal developers that will help them pinpoint
32 In the past, two versions of Ethereal binaries were published -- a
33 version that could capture packets and a version which could not.
34 The latter is useful if you're only reading files produced by
35 another product (e.g., a sniffer, firewall, or intrustion detection system)
36 and did not wish to install WinPcap, the library Ethereal uses
37 to capture packets on Win32 platforms.
39 As of WinPcap 2.1, all the WinPcap libraries have been released as DLLs.
40 This means that Ethereal can detect the presence of WinPcap at run time,
41 which means that only one version of the Ethereal binaries needs to be
44 If you don't want to capture packets, just install the Ethereal
45 package. If you do want to capture packets, install Ethereal *and*
46 install the latest non-beta version of WinPcap, available from:
48 http://winpcap.polito.it/
52 http://winpcap.mirror.ethereal.com/
56 http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/
58 If you already have an earlier version of WinPcap installed, you need to
59 un-install it and install the latest version. If the older version is
60 WinPcap 2.0 or 2.02, and you have other applications that use the older
61 version , you will have to decide which applications to keep, since
62 WinPcap 2.0/2.02 and later versions cannot be installed on the same
63 system at the same time.
65 If Ethereal is not capturing packets and you have WinPcap installed, you
66 can test your WinPcap installation by installing WinDump (tcpdump for
67 Windows) ported by the same folks who make WinPcap. It's at:
69 http://windump.polito.it/
73 http://windump.mirror.ethereal.com/
77 http://www.mirrors.wiretapped.net/security/packet-capture/windump/
79 They also make Analyzer, a GUI sniffer for Win32:
81 http://analyzer.polito.it/
83 The rest of this documentation is only interesting if
84 you want to compile Ethereal yourself.
87 Running Ethereal, Tethereal, and Editcap on Win32
88 =================================================
89 You need the glib and gtk libraries for running Ethereal.
91 These packages for win32 can be found at:
93 http://www.ethereal.com/distribution/win32
95 and at the home page for the GTK+ for Win32 project:
97 http://www.gimp.org/~tml/gimp/win32
100 http://www.iki.fi/tml/gimp/win32/
102 (the mirror nearer to you may be faster).
104 Plugins (gryphon.dll and mgcp.dll) can go in:
105 <Ethereal installation directory>\plugins\<version>
107 Where <version> is the version number, without brackets. For example,
108 if you have Ethereal 0.9.8 installed in the default location, plugins
109 will reside in C:\Program Files\Ethereal\plugins\0.9.8
111 Yes, the location of plugins needs to be more flexible.
113 Make sure the glib and gtk DLL's are in your path - i.e., that your
114 path includes the directory (folder) or directories (folders) in which
115 those DLLs are found - when you run Ethereal. This includes gtk-*.dll,
116 glib-*.dll, gmodule-*.dll, gdk-*.dll, intl.dll, and iconv-*.dll. As of
117 the 20000805 GTK+/GLIB distribution, gthread-*.dll is no longer needed.
119 The Win32 Binary distribution, available from
121 http://www.ethereal.com/distribution/win32
123 used different version of the GTK+/GLIB libraries at different points
126 Ethereal Version GTK+/GLIB version
127 ---------------- -----------------
128 0.8.16 and after 20001226
129 0.8.11 - 0.8.15 20000805
130 0.8.9 - 0.8.10 20000416
131 0.8.8 and before 19990828
136 In order to capture with Win32, you need to install the NDIS
137 packet capture driver for your particular Win32 OS; drivers for Windows
138 9x, Windows NT 4.0, and Windows 2000 can be downloaded from the
141 http://winpcap.polito.it/
143 or the mirror site at
145 http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
147 Compiling the Ethereal distribution from source
148 ===============================================
150 You'll need the development packages for GLIB, GTK+, iconv, gettext,
151 WinPcap, zlib, Net-SNMP, ADNS, and PCRE. The GLIB, GTK+, and WinPcap
152 packages are available from the respctive home pages for each project
153 (the same URLs as listed above). The development packages contain header
154 files and stub libaries to link against. Precompiled versions of these
155 packages are available at
157 http://www.ethereal.com/distribution/win32/development/
159 The ADNS package is also available at its homepage:
161 http://adns.jgaa.com/
163 By default, the build process looks for these packages in
164 C:\ethereal-win32-libs. You can place them in a different directory, but
165 you must update config.nmake accordingly. The default location for each
166 package is as follows:
168 Package Default Location
169 ------- ----------------
170 adns-1.0-win32-01.zip C:\ethereal-win32-libs
171 glib-2.2.1.zip C:\ethereal-win32-libs\glib
172 glib-dev-2.2.1.zip C:\ethereal-win32-libs\glib
173 gtk+-1.3.0-20030216.zip C:\ethereal-win32-libs\gtk+
174 gtk+-dev-1.3.0-20030115.zip C:\ethereal-win32-libs\gtk+
175 libiconv-1.9.1.bin.woe32.zip C:\ethereal-win32-libs\gtk+
176 gettext-runtime-0.12.1.bin.woe32.zip [ None ]
177 net-snmp-5.1.zip C:\ethereal-win32-libs
178 pcre-4.4.zip C:\ethereal-win32-libs
179 zlib121-dll.zip C:\ethereal-win32-libs\zlib121-dll
181 The gettext runtime package provides intl.dll, which is needed by
184 Instructions for MS Visual C++
185 ----------------------------
186 Modify the config.nmake file in the top directory of the Ethereal source
187 tree to work for your local configuration; if you don't have Python,
188 comment out the line that defines PYTHON, otherwise set it to refer to
189 the pathname of your Python interpreter executable. You should not have
190 to modify any other Makefile.
192 Many of the file and directory names used in the build process go past
193 the old 8.3 naming limitations. As a result, at least on Windows NT 4.0,
194 Windows 2000, Windows XP, and Windows .NET Server, you should use the
195 newer "cmd.exe" command interpreter instead of the old "command.com",
196 as the "command.com" on Windows 2000, at least, can't handle non-8.3
197 directory names. (It may be that the "command.com" in Windows 95, Windows
198 98, and Windows Me, as it's the only command interpreter in those systems,
199 can handle those directories. If not, it may not be possible to build
200 Ethereal from the command line on those versions of Windows.)
202 Be sure that your command-line environment is set up to compile
203 and link with MSVC++. When installing MSVC++, you can have your
204 system's environment set up to always allow compiling from the
205 command line, or you can invoke the vcvars32.bat script, which can
206 usually be found in the "VC98\Bin" subdirectory of the directory in
207 which Visual Studio was installed.
209 The first time you build Ethereal, run the script "cleanbld.bat" in the
210 top-level Ethereal source directory to make sure that the "config.h"
211 files will be reconstructed from the "config.h.win32" files. (If, for
212 example, you have "config.h" files left over from a Unix build, a
213 Windows build will fail.)
215 In the ethereal directory, type "nmake -f makefile.nmake". It will
216 recurse into the subdirectories as appropriate.
218 Some generated source is created by traditionally "Unix-ish" tools.
220 If you are building from an official distribution, these files are
221 already generated, although they were generated on a Unix-compatible
222 system. In most cases, the generated files can be used when building on
223 Windows, but the files listed below as being generated by Flex can be
224 used when building on Windows only when generated by a Windows version
225 of Flex, so you will need a Windows version of Flex to do a Windows
226 build. Those generated files are removed by the "cleanbld.bat" script,
227 to make sure that versions left over from a Unix build aren't used.
229 If you are building from a modified version of an official distribution,
230 and you modified any of the source files listed below, you will need the
231 tool(s) that generate output from those source files.
233 If building from a CVS image, you'll need all the tools to generate C
236 The "special" files and their requisite tools are:
240 config.h.win32 config.h sed
241 epan/config.h.win32 epan/config.h sed
242 image/ethereal.rc.in image/ethereal.rc sed
243 image/tethereal.rc.in image/tethereal.rc sed
244 image/editcap.rc.in image/editcap.rc sed
245 image/mergecap.rc.in image/mergecap.rc sed
246 image/text2pcap.rc.in image/text2pcap.rc sed
247 packaging/nsis/ethereal.nsi.in packaging/ethereal.nsi sed
248 wiretap/config.h.win32 wiretap/config.h sed
249 epan/dfilter/dfilter-scanner.l epan/dfilter/*.c Flex
250 text2pcap-scanner.l *.c Flex
251 wiretap/ascend-scanner.l *.c Flex
252 wiretap/ascend-grammar.y *.c,*.h Bison/Yacc
253 ncp2222.py packet-ncp2222.c Python
255 make-reg-dotc, packet*.c register.c Bash + grep + sed
257 make-reg-dotc.py, packet*.c register.c Python
259 make-tapreg-dotc, tap-*.c tethereal-tap-register.c
261 make-tapreg-dotc, tap files gtk/ethereal-tap-register.c
262 in the gtk subdirectory Bash + grep + sed
264 The Makefile.nmake supplied with the Ethereal distribution will, if
265 PYTHON is defined in config.nmake, attempt to make register.c with
266 Python, since it is much much much faster than the shell version. The
267 reason it is faster is because the shell version launches multiple
268 processes (grep, sed) for each source file, multiple times. The Python
269 script is one process. This matters a lot on Win32.
271 If you have a Unix system handy, you can first build on Unix to create
272 most of the source files that these tools make, then run the build on
273 Windows. That will avoid the need for these tools on your Windows
274 computer. This won't work for the files in the "image" directory,
275 however, as those aren't built on Unix - they're only for Windows
276 builds. It also won't work for the "config.h" files; whilst those are
277 built for Unix, they're specific to the platform on which you're
278 building, and the "config.h" files constructed for a Unix build will not
279 work with a Windows build. In addition, it won't work for the files
280 generated by Flex, as, for a Windows build, those have to be generated
281 by a Windows version of Flex.
283 Most of those tools are available for Win32 systems as part of the
286 http://sources.redhat.com/cygwin/
288 After installing them, you will probably have to modify the config.nmake
289 file to specify where the Cygwin binaries are installed.
291 Python for Win32 is available from
293 http://www.python.org/
296 Instructions for Cygwin
297 -----------------------
299 It is possible to build Ethereal under Cygwin using their version
300 of XFree86. References:
301 - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
302 - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
304 To get it running, execute the following steps:
306 1. Install the required cygwin packages (compiler, scripting, X, zlib)
307 with the CygWin setup.exe tool (http://www.cygwin.com/).
308 You need the base Xfree86 support plus the X headers package in order
309 to be able to compile the gtk+ package.
311 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
313 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
314 http://homepage.ntlworld.com/steven.obrien2/
317 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
318 /libs/patches/glib-1.2.10-cygwin.patch
321 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
322 /libs/patches/gtk+-1.2.10-cygwin.patch
324 4. Compile and install both packages after patching (see instructions
325 at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
329 $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
334 $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
335 $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
343 $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
344 $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
349 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
350 removing "gtkclist.c" from the dependencies.
352 This patch is required since the private GTK+ clist widget
353 (was required for earlier versions of GTK+ but prevents Ethereal
354 from running with cygwin).
356 6. Configure and make Ethereal:
358 Set the path (if this has not yet been done earlier)
360 $ PATH=/opt/gnome/bin:$PATH
362 $ ./autogen.sh --without-pcap --without-plugins
363 $ ./configure --without-pcap --without-plugins
366 This make will eventually stop, but it is required as e.g., the
367 GTK binaries are built then.
373 $ sh /usr/X11R6/bin/startxwin.sh
375 For non-US keyboard layouts, use (replace 'be' with your layout):
377 $ setxkbmap.exe -layout be
379 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
381 $ <ethereal-src>/ethereal
383 And voila! Behold the mighty sniffer in all its glory!
385 Something is wrong with the makefile that gets generated, so it doesn't work
387 I am not curious enough to look at why 'make' doesnt work; 'make ethereal.exe'
388 works well enough for me.
390 Note: Compiling Ethereal under cygwin takes a lot of time, because the
391 generation of 'register.c' takes ages. If you only edit one dissector and
392 you know what you're doing, it is acceptable to uncomment the generation
393 of the file 'register.c' in Makefile. Look for the 'register.c' target:
395 register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
396 @echo Making register.c
397 # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
398 @echo Skipping generation of register.c
400 Of course, you need to generate the 'register.c' file at least once.