Updates for the endpoint talkers thing
[obnox/wireshark/wip.git] / README.win32
1 $Id: README.win32,v 1.48 2003/08/24 23:25:40 gerald 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 and any of its mirrors.
8
9 The installation package allows you to install:
10
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
20
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.
24
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 
30 the problem. 
31
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.
38
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
42 shipped.
43
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:
47
48         http://winpcap.polito.it/
49
50 and mirrored at
51
52         http://winpcap.mirror.ethereal.com/
53
54 and
55
56         http://www.mirrors.wiretapped.net/security/packet-capture/winpcap/
57
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.
64
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:
68
69         http://windump.polito.it/
70
71 and mirrored at
72
73         http://windump.mirror.ethereal.com/
74
75 and
76
77         http://www.mirrors.wiretapped.net/security/packet-capture/windump/
78
79 They also make Analyzer, a GUI sniffer for Win32:
80
81         http://analyzer.polito.it/
82
83 The rest of this documentation is only interesting if
84 you want to compile Ethereal yourself.
85
86
87 Running Ethereal, Tethereal, and Editcap on Win32
88 =================================================
89 You need the glib and gtk libraries for running Ethereal. 
90
91 These packages for win32 can be found at:
92
93         http://www.ethereal.com/distribution/win32
94
95 and at the home page for the GTK+ for Win32 project:
96
97         http://www.gimp.org/~tml/gimp/win32
98
99 or
100         http://www.iki.fi/tml/gimp/win32/
101
102 (the mirror nearer to you may be faster).
103
104 Plugins (gryphon.dll and mgcp.dll) can go in:
105         <Ethereal installation directory>\plugins\<version>
106
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
110
111 Yes, the location of plugins needs to be more flexible.
112
113 Make sure the glib and gtk DLL's are in your path - i.e., that your path
114 includes the directory (folder) or directories (folders) in which those
115 DLLs are found - when you run Ethereal.  This includes gtk-*.dll,
116 glib-*.dll, gmodule-*.dll, gdk-*.dll, gnu-intl.dll, and iconv-*.dll.
117 As of the 20000805 GTK+/GLIB distribution, gthread-*.dll is no longer needed.
118
119 The Win32 Binary distribution, available from
120
121         http://www.ethereal.com/distribution/win32
122
123 used different version of the GTK+/GLIB libraries at different points
124 in time:
125
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
132
133
134 Capturing Packets
135 -----------------
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
139 WinPcap home page:
140
141         http://winpcap.polito.it/
142
143 or the mirror site at
144
145         http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
146
147 Compiling the Ethereal distribution from source
148 ===============================================
149
150 You'll need the development packages for GLIB, GTK+, iconv, intl,
151 WinPcap, zlib, Net-SNMP, and ADNS.  The GLIB, GTK+, and WinPcap packages
152 are available from the respctive home pages for each project (the same
153 URLs as listed above). The development packages contain header files and
154 stub libaries to link against.  Precompiled versions of these packages
155 are available at
156
157         http://www.ethereal.com/distribution/win32/development/
158
159 The ADNS package is also available at its homepage:
160
161         http://adns.jgaa.com/
162
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:
167
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     libintl-0.10.40-tml-20020904.zip    C:\ethereal-win32-libs\gtk+
177     net-snmp-5.0.6.zip                  C:\ethereal-win32-libs
178     zlib-114-dev.zip                    C:\ethereal-win32-libs
179
180
181 Instructions for MS Visual C++
182 ----------------------------
183 Modify the config.nmake file in the top directory of the Ethereal source
184 tree to work for your local configuration; if you don't have Python,
185 comment out the line that defines PYTHON, otherwise set it to refer to
186 the pathname of your Python interpreter executable.  You should not have
187 to modify any other Makefile.
188
189 Many of the file and directory names used in the build process go past
190 the old 8.3 naming limitations.  As a result, at least on Windows NT 4.0,
191 Windows 2000, Windows XP, and Windows .NET Server, you should use the
192 newer "cmd.exe" command interpreter instead of the old "command.com",
193 as the "command.com" on Windows 2000, at least, can't handle non-8.3
194 directory names.  (It may be that the "command.com" in Windows 95, Windows
195 98, and Windows Me, as it's the only command interpreter in those systems,
196 can handle those directories.  If not, it may not be possible to build
197 Ethereal from the command line on those versions of Windows.)
198
199 Be sure that your command-line environment is set up to compile
200 and link with MSVC++. When installing MSVC++, you can have your
201 system's environment set up to always allow compiling from the
202 command line, or you can invoke the vcvars32.bat script, which can
203 usually be found in the "VC98\Bin" subdirectory of the directory in
204 which Visual Studio was installed.
205
206 The first time you build Ethereal, run the script "cleanbld.bat" in the
207 top-level Ethereal source directory to make sure that the "config.h"
208 files will be reconstructed from the "config.h.win32" files.  (If, for
209 example, you have "config.h" files left over from a Unix build, a
210 Windows build will fail.)
211
212 In the ethereal directory, type "nmake -f makefile.nmake". It will
213 recurse into the subdirectories as appropriate.
214
215 Some generated source is created by traditionally "Unix-ish" tools.
216
217 If you are building from an official distribution, these files are
218 already generated, although they were generated on a Unix-compatible
219 system.  In most cases, the generated files can be used when building on
220 Windows, but the files listed below as being generated by Flex can be
221 used when building on Windows only when generated by a Windows version
222 of Flex, so you will need a Windows version of Flex to do a Windows
223 build.  Those generated files are removed by the "cleanbld.bat" script,
224 to make sure that versions left over from a Unix build aren't used.
225
226 If you are building from a modified version of an official distribution,
227 and you modified any of the source files listed below, you will need the
228 tool(s) that generate output from those source files.
229
230 If building from a CVS image, you'll need all the tools to generate C
231 source.
232
233 The "special" files and their requisite tools are:
234
235 Source                          Output                  Tool
236 ------                          ------                  ----
237 config.h.win32                  config.h                sed
238 epan/config.h.win32             epan/config.h           sed
239 image/ethereal.rc.in            image/ethereal.rc       sed
240 image/tethereal.rc.in           image/tethereal.rc      sed
241 image/editcap.rc.in             image/editcap.rc        sed
242 image/mergecap.rc.in            image/mergecap.rc       sed
243 image/text2pcap.rc.in           image/text2pcap.rc      sed
244 packaging/nsis/ethereal.nsi.in  packaging/ethereal.nsi  sed
245 wiretap/config.h.win32          wiretap/config.h        sed
246 epan/dfilter/dfilter-scanner.l  epan/dfilter/*.c        Flex
247 text2pcap-scanner.l             *.c                     Flex
248 wiretap/ascend-scanner.l        *.c                     Flex
249 wiretap/ascend-grammar.y        *.c,*.h                 Bison/Yacc
250 ncp2222.py                      packet-ncp2222.c        Python
251
252 make-reg-dotc, packet*.c        register.c              Bash + grep + sed
253 or
254 make-reg-dotc.py, packet*.c     register.c              Python
255
256 make-tapreg-dotc, tap-*.c       tethereal-tap-register.c
257                                                         Bash + grep + sed
258
259 The Makefile.nmake supplied with the Ethereal distribution will, if
260 PYTHON is defined in config.nmake, attempt to make register.c with
261 Python, since it is much much much faster than the shell version.  The
262 reason it is faster is because the shell version launches multiple
263 processes (grep, sed) for each source file, multiple times.  The Python
264 script is one process.  This matters a lot on Win32.
265
266 If you have a Unix system handy, you can first build on Unix to create
267 most of the source files that these tools make, then run the build on
268 Windows.  That will avoid the need for these tools on your Windows
269 computer.  This won't work for the files in the "image" directory,
270 however, as those aren't built on Unix - they're only for Windows
271 builds.  It also won't work for the "config.h" files; whilst those are
272 built for Unix, they're specific to the platform on which you're
273 building, and the "config.h" files constructed for a Unix build will not
274 work with a Windows build.  In addition, it won't work for the files
275 generated by Flex, as, for a Windows build, those have to be generated
276 by a Windows version of Flex.
277
278 Most of those tools are available for Win32 systems as part of the
279 Cygwin package:
280
281         http://sources.redhat.com/cygwin/
282
283 After installing them, you will probably have to modify the config.nmake
284 file to specify where the Cygwin binaries are installed.
285
286 Python for Win32 is available from
287
288         http://www.python.org/
289
290
291 Instructions for Cygwin
292 -----------------------
293
294 It is possible to build Ethereal under Cygwin using their version
295 of XFree86. References:
296  - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
297  - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
298  
299 To get it running, execute the following steps:
300
301 1. Install the required cygwin packages (compiler, scripting, X, zlib)
302    with the CygWin setup.exe tool (http://www.cygwin.com/).
303    You need the base Xfree86 support plus the X headers package in order
304    to be able to compile the gtk+ package.
305
306 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
307
308 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
309    http://homepage.ntlworld.com/steven.obrien2/
310
311  + glib-1.2.10
312    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
313           /libs/patches/glib-1.2.10-cygwin.patch
314
315  + gtk+-1.2.10
316    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
317           /libs/patches/gtk+-1.2.10-cygwin.patch
318
319 4. Compile and install both packages after patching (see instructions
320    at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
321
322    Set the path:
323
324      $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
325
326    For glib-1.2.10:
327    
328      $ cd glib-1.2.10
329      $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
330      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
331      $ make
332      $ make check
333      $ make install
334
335    For gtk+-1.2.10:
336
337      $ cd gtk+-1.2.10
338      $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
339      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
340      $ make
341      $ make check
342      $ make install
343
344 5. Patch Makefile.am in <ethereal-src>/gtk/Makefile.am by
345    removing "gtkclist.c" from the dependencies.
346
347    This patch is required since the private GTK+ clist widget
348    (was required for earlier versions of GTK+ but prevents Ethereal
349    from running with cygwin).
350
351 6. Configure and make Ethereal:
352
353    Set the path (if this has not yet been done earlier)
354
355      $ PATH=/opt/gnome/bin:$PATH
356
357      $ ./autogen.sh --without-pcap --without-plugins
358      $ ./configure --without-pcap --without-plugins
359      $ make
360
361    This make will eventually stop, but it is required as e.g., the
362    GTK binaries are built then.
363
364      $ make ethereal.exe
365
366 7. Start X
367
368      $ sh /usr/X11R6/bin/startxwin.sh
369
370    For non-US keyboard layouts, use (replace 'be' with your layout):
371
372      $ setxkbmap.exe -layout be
373
374 8. Run ethereal (add /opt/gnome/bin to $PATH if this is not yet done)
375
376      $ <ethereal-src>/ethereal
377
378    And voila! Behold the mighty sniffer in all its glory!
379
380 Something is wrong with the makefile that gets generated, so it doesn't work
381 just running make.
382 I am not curious enough to look at why 'make' doesnt work; 'make ethereal.exe'
383 works well enough for me.
384
385 Note: Compiling Ethereal under cygwin takes a lot of time, because the
386 generation of 'register.c' takes ages. If you only edit one dissector and
387 you know what you're doing, it is acceptable to uncomment the generation
388 of the file 'register.c' in Makefile. Look for the 'register.c' target:
389
390     register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
391         @echo Making register.c
392         # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
393         @echo Skipping generation of register.c
394
395 Of course, you need to generate the 'register.c' file at least once.