$Id$ Installing Wireshark, TShark, and Editcap on Win32 ================================================== These are the instructions for installing Wireshark from the installation executable that is provided on the Wireshark website at: http://www.wireshark.org/download/win32 and any of its mirrors. The installer will take care of most situations, so just keep the default settings and start Wireshark after the installation finished. For detailed descriptions how to install and use Wireshark and the related command line tools, see the Wireshark User's Guide at: http://www.wireshark.org/docs/ Troubleshooting =============== If Wireshark is not capturing packets and you have WinPcap installed, you can test your WinPcap installation by installing WinDump (tcpdump for Windows) ported by the same folks who make WinPcap. It's at: http://windump.polito.it/ and mirrored at http://windump.mirror.ethereal.com/ and http://www.mirrors.wiretapped.net/security/packet-capture/windump/ They also make Analyzer, a GUI sniffer for Win32: http://analyzer.polito.it/ The rest of this documentation is only interesting if you want to compile Wireshark yourself. Compiling the Wireshark distribution from source ================================================ Developer's Guide ----------------- You can find a comprehensive guide how to develop Wireshark in the Developer's Guide, which you can find (and much more info) at: http://wiki.wireshark.org/Development The guide contains detailed information how to setup the development environment and it's usage. Compilers --------- MS Visual C++ Version 6 This is the recommended compiler used for building Wireshark on win32. If you've downloaded an Wireshark source tarball and unpacked it, then, before you do any build, you must do nmake -f makefile.nmake distclean to get rid of files included in the source distribution that are built for UN*X (so that the source distribution can be compiled on UN*X without requiring tools such as Flex) and that won't compile on Windows as generated. You must also do that if you've built for UN*X in the same directory tree, regardless of whether you are building from a source tarball or from the Subversion tree. You do not have to do this if you're directly building from the Subversion tree, as long as you haven't done a UN*X build in the same directory. MS Visual C++ Version 7 / VC.NET / 2003 / 2005 Currently unsupported for two reasons: -there are serious problems in using DLL's compiled with MS VC6. See section "Problems with MS Visual C++ Version 7 / VC.NET" below. Cygwin GCC Wireshark can entirely be built with cygwin GCC. But please remember that MSVC6 is the recommended way - using GCC might be quite difficult and the built binaries will only run in a cygwin environment using an X server, so they are not standalone Win32 applications. It is however not excluded that native Win32 code can be compiled on cygwin GCC but you then have to use -mms-bitfields as a strict minimum and probably -mno-cygwin or a similar compiler flag too. See the "Instructions for Cygwin" section below for detailed instructions. Automated library download -------------------------- Before using the automated download, be sure to edit the config.nmake file to suit your needs. Especially have a look at the WIRESHARK_LIBS setting. However, the defaults should be working well for a first start. If you've installed Microsoft Visual C++ (MSVC), you can run: nmake -f makefile.nmake setup This will first check the availability of all required tools and then uses the tool wget to download each package file (together around 30MB!) from the server location at: http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/ and unpack it in the $WIRESHARK_LIBS directory. If you have problems downloading the files, you might be connected to the internet through a proxy/firewall. In this case see the wget documentation to configure wget accordingly. Required libraries ------------------ If the automated library download finished sucessfully, you should have all libraries on your machine at the right places. So you don't have to read this section, unless you are interested which libraries are used. You'll need the development packages for GLIB, GTK+, iconv, gettext, WinPcap, Net-SNMP, and optionally ADNS, PCRE and zlib. The development packages contain header files and stub libraries to link against. PRECOMPILED VERSIONS OF ALL OF THESE PACKAGES ARE AVAILABLE AT: http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/ The GLIB, GTK+, iconv, gettext packages for win32 can be found at the home page for the GTK+ for Win32 project: http://www.gimp.org/~tml/gimp/win32 or the mirror http://www.iki.fi/tml/gimp/win32/ The Net-SNMP package for win32 is available at its homepage: http:// The WinPcap package is available at its homepage: http://winpcap.polito.it/ or the mirror http://www.wiretapped.net/security/packet-capture/winpcap/default.htm The optional ADNS package for win32 is available at its homepage: http://adns.jgaa.com/ The optional PCRE package (Perl Compatible Regular Expressions) for win32 is available at its homepage: http://gnuwin32.sourceforge.net/packages/pcre.htm The optional zlib package for win32 is available at its homepage: http://www.gzip.org/zlib/ By default, the build process looks for these packages in C:\wireshark-win32-libs. You can place them in a different directory, but you must update the WIRESHARK_LIBS variable in config.nmake accordingly. The following lists the packages needed to compile Wireshark and the default locations where to unpack them, when the above method isn't used. Package Default Location ------- ---------------- glib-2.4.7.zip C:\wireshark-win32-libs\glib glib-dev-2.4.7.zip C:\wireshark-win32-libs\glib gtk+-1.3.0-20030717.zip C:\wireshark-win32-libs\gtk+ gtk+-dev-1.3.0-20030115.zip C:\wireshark-win32-libs\gtk+ libiconv-1.9.1.bin.woe32.zip C:\wireshark-win32-libs\libiconv-1.9.1.bin.woe32 gettext-runtime-0.13.1.zip C:\wireshark-win32-libs\gettext-runtime-0.13.1 net-snmp-5.2.1.2.zip C:\wireshark-win32-libs wpdpack_3_0.zip C:\wireshark-win32-libs and optional: adns-1.0-win32-04.zip C:\wireshark-win32-libs pcre-4.4.zip C:\wireshark-win32-libs zlib123-dll.zip C:\wireshark-win32-libs\zlib123-dll (to use the default locations, the directories in question should be created, and each zip file should be unpacked into the corresponding directory). If you only want to change the C:\wireshark-win32-libs part, you just change the setting of WIRESHARK_LIBS in config.nmake; if you want to change subdirectories, you'll have to change the individual item for a package. (Note that some zip files create the subdirectory - those zip files just have C:\wireshark-win32-libs in the list above - so if you don't want the package to be in that subdirectory, you'd have to rename the directory.) The gettext runtime package provides intl.dll, which is needed by GLib 2.4.7. Compiling the Wireshark distribution using GTK+2 ------------------------------------------------ The more recent version 2 of the GTK+ can be used to compile Wireshark with, but is still considered beta. GTK+2 will look better in various ways, especially for WIN32 users. You can get the required libraries from: http://www.wireshark.org/distribution/win32/development/gtk2 or (like the GTK+1 libraries from the GTK+ for Win32 project): http://www.gimp.org/~tml/gimp/win32/downloads.html If you want to try a build with GTK+2.x these Extra libraries are needed Package Default Location ------- ---------------- gtk+-2.4.14.zip C:\wireshark-win32-libs\gtk2 gtk+-dev-2.4.14.zip C:\wireshark-win32-libs\gtk2 pango-1.4.1.zip C:\wireshark-win32-libs\gtk2 pango-dev-1.4.1.zip C:\wireshark-win32-libs\gtk2 atk-1.6.0.zip C:\wireshark-win32-libs\gtk2 atk-dev-1.6.0.zip C:\wireshark-win32-libs\gtk2 and optional: gtk-wimp-0.7.0-bin.zip C:\wireshark-win32-libs\gtk-wimp Be sure to set GTK2_DIR in config.nmake correct, to be able to compile. Running your freshly compiled Wireshark -------------------------------------- Make sure the glib and gtk DLL's are in your path or you use a directory where all required DLL's and the exe files reside.- i.e., that your path includes the directory (folder) or directories (folders) in which those DLLs are found - when you run Wireshark. Note the wiretap*.dll must be in your path as well and if wiretap is changed be sure to put the new one in your path. Plugins (gryphon.dll and mgcp.dll) can go in: \plugins\ Where is the version number, without brackets. For example, if you have Wireshark 0.99.1 installed in the default location, plugins will reside in C:\Program Files\Wireshark\plugins\0.99.1 Yes, the location of plugins needs to be more flexible. Instructions for MS Visual C++ ---------------------------- Modify the config.nmake file in the top directory of the Wireshark source tree to work for your local configuration; if you don't have Python, comment out the line that defines PYTHON, otherwise set it to refer to the pathname of your Python interpreter executable. You should not have to modify any other Makefile. Note that perl is needed to build the documentation, the lines in config.nmake POD2MAN=$(SH) pod2man POD2HTML=$(SH) pod2html requires Cygwin bash and perl to work. Many of the file and directory names used in the build process go past the old 8.3 naming limitations. As a result, at least on Windows NT 4.0, Windows 2000, Windows XP, and Windows .NET Server, you should use the newer "cmd.exe" command interpreter instead of the old "command.com", as the "command.com" on Windows 2000, at least, can't handle non-8.3 directory names. (It may be that the "command.com" in Windows 95, Windows 98, and Windows Me, as it's the only command interpreter in those systems, can handle those directories. If not, it may not be possible to build Wireshark from the command line on those versions of Windows.) Be sure that your command-line environment is set up to compile and link with MSVC++. When installing MSVC++, you can have your system's environment set up to always allow compiling from the command line, or you can invoke the vcvars32.bat script, which can usually be found in the "VC98\Bin" subdirectory of the directory in which Visual Studio was installed. The first time you build Wireshark, run "nmake -f makefile.nmake distclean" in the top-level Wireshark source directory to make sure that the "config.h" files will be reconstructed from the "config.h.win32" files. (If, for example, you have "config.h" files left over from a Unix build, a Windows build will fail.) In the wireshark directory, type "nmake -f makefile.nmake". It will recurse into the subdirectories as appropriate. Some generated source is created by traditionally "Unix-ish" tools. If you are building from an official distribution, these files are already generated, although they were generated on a Unix-compatible system. In most cases, the generated files can be used when building on Windows, but the files listed below as being generated by Flex can be used when building on Windows only when generated by a Windows version of Flex, so you will need a Windows version of Flex to do a Windows build. Those generated files are removed by "nmake -f makefile.nmake distclean", to make sure that versions left over from a Unix build aren't used. If you are building from a modified version of an official distribution, and you modified any of the source files listed below, you will need the tool(s) that generate output from those source files. If building from a CVS image, you'll need all the tools to generate C source. The "special" files and their requisite tools are: Source Output Tool ------ ------ ---- config.h.win32 config.h sed epan/config.h.win32 epan/config.h sed image/wireshark.rc.in image/wireshark.rc sed image/tshark.rc.in image/tshark.rc sed image/editcap.rc.in image/editcap.rc sed image/mergecap.rc.in image/mergecap.rc sed image/text2pcap.rc.in image/text2pcap.rc sed wiretap/config.h.win32 wiretap/config.h sed epan/dfilter/dfilter-scanner.l epan/dfilter/*.c Flex text2pcap-scanner.l *.c Flex wiretap/ascend-scanner.l *.c Flex wiretap/ascend-grammar.y *.c,*.h Bison/Yacc ncp2222.py packet-ncp2222.c Python make-reg-dotc, packet*.c register.c Bash + grep + sed or make-reg-dotc.py, packet*.c register.c Python make-tapreg-dotc, tap-*.c tshark-tap-register.c Bash + grep + sed make-tapreg-dotc, tap files gtk/wireshark-tap-register.c in the gtk subdirectory Bash + grep + sed The Makefile.nmake supplied with the Wireshark distribution will, if PYTHON is defined in config.nmake, attempt to make register.c with Python, since it is much much much faster than the shell version. The reason it is faster is because the shell version launches multiple processes (grep, sed) for each source file, multiple times. The Python script is one process. This matters a lot on Win32. If you have a Unix system handy, you can first build on Unix to create most of the source files that these tools make, then run the build on Windows. That will avoid the need for these tools on your Windows computer. This won't work for the files in the "image" directory, however, as those aren't built on Unix - they're only for Windows builds. It also won't work for the "config.h" files; whilst those are built for Unix, they're specific to the platform on which you're building, and the "config.h" files constructed for a Unix build will not work with a Windows build. In addition, it won't work for the files generated by Flex, as, for a Windows build, those have to be generated by a Windows version of Flex. Most of those tools are available for Win32 systems as part of the Cygwin package: http://www.cygwin.com/ After installing them, you will probably have to modify the config.nmake file to specify where the Cygwin binaries are installed. Note that installing cygwin with the "Default Text File Type" set to DOS may break the compilation because all the required tools may not be found. Set this parameter to UNIX instead. Python for Win32 is available from: http://www.python.org/ Build an (NSIS based) installer ------------------------------- If you want to build your own installer, you need to get NSIS from: http://nsis.sourceforge.net/home/ After installing it, you will probably have to modify the config.nmake file to specify where the NSIS binaries are installed and wether to use the modern UI or not. You will need NSIS version 2 or higher, to build an installer with the modern user interface, and for a much smaller installer (using the lzma compression). In the wireshark directory, type "nmake -f makefile.nmake packaging" to build the installer. Please be patient while the compression is done, it will take some time even on fast machines. You will hopefully now see something like wireshark-setup-0.10.12.exe in the dir packaging/nsis. Installing GTK-Wimp ------------------- GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines, especially with the new "coloured" WinXP theme. It will only take effect together with the GTK2 version of Wireshark. No changes to the Wireshark sources are needed, GTK-Wimp simply changes the way GTK2 displays the widgets (by changing the GTK2 default theme). GTK-Wimp will be automatically installed if you use the official Wireshark Setup. In this case, the files mentioned below are already existing at the appropriate places. If GTK-Wimp wasn't installed, you can install it yourself (however, this method is error prone and therefore no longer recommended): 1. Go to http://gtk-wimp.sourceforge.net/ 2. Download the ZIP archive containing the library and the theme 3. Locate the installation directory of Wireshark (C:\Program Files\Wireshark) 4. Create a subdirectory 'share\themes\Default\gtk-2.0' 5. Drop the file 'gtkrc' in 'share\themes\Default\gtk-2.0' 6. Create a subdirectory named 'lib\gtk-2.0\2.4.0\engines' 7. Drop the 'libwimp.dll' library in 'lib\gtk-2.0\2.4.0\engines' When you're finished, you should have: C:\Program Files\Wireshark\lib\gtk-2.0\2.4.0\engines\libwimp.dll C:\Program Files\Wireshark\share\themes\Default\gtk-2.0\gtkrc After (re-)starting Wireshark, you should now see it's widgets in the modern WinXP style on your screen. Problems with MS Visual C++ Version 7 / VC.NET ---------------------------------------------- There are known problems with DLL's. If Wireshark is compiled with MSVC Version 7, there are conflicts in the MSVCRT DLL's, The MSVCRT.DLL includes the standard ANSI-C functions like fopen, malloc, etc.. MSVCRT.DLL is shipped with the MSVC 6 compiler versions, and dynamically linked to prebuild DLL's like the one's for gtk, glib and such. The MSVC 7 compiler now uses and ships MSVCRT71.DLL with it, which is incompatible with MSVCRT.DLL. So when using the MSVC 7 compiler, some parts of the Wireshark code uses MSVCRT71.DLL, and some others (indirectly from e.g. the gtk DLL) will use MSVCRT.DLL. This will result in incorrect file handles and such. The same problem seems to apply on all MSVC compilers after version 6, like the "Microsoft Visual C++ Toolkit 2003". Instructions for Cygwin ----------------------- It is possible to build Wireshark under Cygwin using their version of XFree86. References: - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html To get it running, execute the following steps: 1. Install the required cygwin packages (compiler, scripting, X, zlib) with the CygWin setup.exe tool (http://www.cygwin.com/). You need the base Xfree86 support plus the X headers package in order to be able to compile the gtk+ package. 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org. 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from http://homepage.ntlworld.com/steven.obrien2/ + glib-1.2.10 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line) /libs/patches/glib-1.2.10-cygwin.patch + gtk+-1.2.10 http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line) /libs/patches/gtk+-1.2.10-cygwin.patch 4. Compile and install both packages after patching (see instructions at the bottom of http://homepage.ntlworld.com/steven.obrien2/): Set the path: $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH For glib-1.2.10: $ cd glib-1.2.10 $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix $ make $ make check $ make install For gtk+-1.2.10: $ cd gtk+-1.2.10 $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch $ CFLAGS=-O2 ./configure --prefix=/opt/gnome $ make $ make check $ make install 5. Patch Makefile.am in /gtk/Makefile.am by removing "ethclist.c" from the dependencies. This patch is required since the private GTK+ clist widget (was required for earlier versions of GTK+ but prevents Wireshark from running with cygwin). 6. Configure and make Wireshark: Set the path (if this has not yet been done earlier) $ PATH=/opt/gnome/bin:$PATH $ ./autogen.sh $ ./configure --config-cache --without-pcap $ make 7. Start X $ sh /usr/X11R6/bin/startxwin.sh Or you can start it from C:\cygwin\usr\X11R6\bin\startxwin.bat 8. Run wireshark (add /opt/gnome/bin to $PATH if this is not yet done) $ /wireshark And voila! Behold the mighty sniffer in all its glory! Note that the plugin dissectors must be installed (make install) if you want to use them. Note also that running "make install" produces lots of output to the console; this is normal. Note: Compiling Wireshark under cygwin takes a lot of time, because the generation of 'register.c' takes ages. If you only edit one dissector and you know what you're doing, it is acceptable to uncomment the generation of the file 'register.c' in Makefile. Look for the 'register.c' target: register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc @echo Making register.c # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC) @echo Skipping generation of register.c Of course, you need to generate the 'register.c' file at least once. Note: You can also capture packets on a cygwin built Wireshark. You then have to unpack the WinPCap development package, install the files in lib/ and include/ in say /usr/lib and /usr/include (they must be in the search path of the compiler and linker, otherwise you have to specify the configure option --with-pcap=/location/to/pcap so the packet capture functionality can be used. In order to run Wireshark, you have to add the .dll files in a directory in the PATH (e.g., /bin). Should you want packet capturing enabled in the cygwin build, then you have to remove --without-pcap from step 6.