README.win32

   1 $Id$
   2
   3 Installing Wireshark, TShark, and Editcap on Win32
   4 ==================================================
   5 These are the instructions for installing Wireshark
   6 from the installation executable that is provided on
   7 the Wireshark website at:
   8
   9 http://www.wireshark.org/download/win32
  10
  11 and any of its mirrors.
  12
  13 The installer will take care of most situations, so just keep the
  14 default settings and start Wireshark after the installation finished.
  15
  16 For detailed descriptions how to install and use Wireshark and the
  17 related command line tools, see the Wireshark User's Guide at:
  18
  19 http://www.wireshark.org/docs/
  20
  21
  22 Troubleshooting
  23 ===============
  24
  25 If Wireshark is not capturing packets and you have WinPcap installed, you
  26 can test your WinPcap installation by installing WinDump (tcpdump for
  27 Windows) ported by the same folks who make WinPcap.  It's at:
  28
  29         http://windump.polito.it/
  30
  31 and mirrored at
  32
  33         http://windump.mirror.ethereal.com/
  34
  35 and
  36
  37         http://www.mirrors.wiretapped.net/security/packet-capture/windump/
  38
  39 They also make Analyzer, a GUI sniffer for Win32:
  40
  41         http://analyzer.polito.it/
  42
  43
  44 The rest of this documentation is only interesting if
  45 you want to compile Wireshark yourself.
  46
  47
  48 Compiling the Wireshark distribution from source
  49 ================================================
  50
  51 Developer's Guide
  52 -----------------
  53 You can find a comprehensive guide how to develop Wireshark in the
  54 Developer's Guide, which you can find (and much more info) at:
  55
  56 http://wiki.wireshark.org/Development
  57
  58 The guide contains detailed information how to setup the development
  59 environment and it's usage.
  60
  61 Compilers
  62 ---------
  63 MS Visual C++ Version 6
  64 This is the recommended compiler used for building Wireshark on win32.
  65
  66 If you've downloaded an Wireshark source tarball and unpacked it, then,
  67 before you do any build, you must do
  68
  69         nmake -f makefile.nmake distclean
  70
  71 to get rid of files included in the source distribution that are built
  72 for UN*X (so that the source distribution can be compiled on UN*X
  73 without requiring tools such as Flex) and that won't compile on Windows
  74 as generated.
  75
  76 You must also do that if you've built for UN*X in the same directory
  77 tree, regardless of whether you are building from a source tarball or
  78 from the Subversion tree.
  79
  80 You do not have to do this if you're directly building from the
  81 Subversion tree, as long as you haven't done a UN*X build in the same
  82 directory.
  83
  84 MS Visual C++ Version 7 / VC.NET / 2003 / 2005
  85 Currently unsupported for two reasons:
  86 -there are serious problems in using DLL's compiled with MS VC6.
  87 See section "Problems with MS Visual C++ Version 7 / VC.NET" below.
  88
  89 Cygwin GCC
  90 Wireshark can entirely be built with cygwin GCC. But please remember that MSVC6
  91 is the recommended way - using GCC might be quite difficult and the built
  92 binaries will only run in a cygwin environment using an X server, so they are
  93 not standalone Win32 applications.
  94 It is however not excluded that native Win32 code can be compiled on cygwin GCC
  95 but you then have to use -mms-bitfields as a strict minimum and probably
  96 -mno-cygwin or a similar compiler flag too.
  97 See the "Instructions for Cygwin" section below for detailed instructions.
  98
  99
 100 Automated library download
 101 --------------------------
 102 Before using the automated download, be sure to edit the config.nmake file
 103 to suit your needs. Especially have a look at the WIRESHARK_LIBS setting.
 104 However, the defaults should be working well for a first start.
 105
 106 If you've installed Microsoft Visual C++ (MSVC), you can run:
 107
 108 nmake -f makefile.nmake setup
 109
 110 This will first check the availability of all required tools and then uses
 111 the tool wget to download each package file (together around 30MB!) from the
 112 server location at:
 113
 114         http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/
 115
 116 and unpack it in the $WIRESHARK_LIBS directory.
 117
 118 If you have problems downloading the files, you might be connected to the
 119 internet through a proxy/firewall. In this case see the wget documentation
 120 to configure wget accordingly.
 121
 122
 123 Required libraries
 124 ------------------
 125 If the automated library download finished sucessfully, you should have all
 126 libraries on your machine at the right places. So you don't have to read this
 127 section, unless you are interested which libraries are used.
 128
 129 You'll need the development packages for GLIB, GTK+, iconv, gettext,
 130 WinPcap, Net-SNMP, and optionally ADNS, PCRE and zlib. The development
 131 packages contain header files and stub libraries to link against.
 132
 133 PRECOMPILED VERSIONS OF ALL OF THESE PACKAGES ARE AVAILABLE AT:
 134
 135         http://anonsvn.wireshark.org/wireshark-win32-libs/trunk/packages/
 136
 137
 138 The GLIB, GTK+, iconv, gettext packages for win32 can be found at the home
 139 page for the GTK+ for Win32 project:
 140
 141         http://www.gimp.org/~tml/gimp/win32 or the mirror
 142         http://www.iki.fi/tml/gimp/win32/
 143
 144 The Net-SNMP package for win32 is available at its homepage:
 145
 146         http://
 147
 148 The WinPcap package is available at its homepage:
 149
 150         http://winpcap.polito.it/ or the mirror
 151         http://www.wiretapped.net/security/packet-capture/winpcap/default.htm
 152
 153 The optional ADNS package for win32 is available at its homepage:
 154
 155         http://adns.jgaa.com/
 156
 157 The optional PCRE package (Perl Compatible Regular Expressions) for win32 is
 158 available at its homepage:
 159
 160         http://gnuwin32.sourceforge.net/packages/pcre.htm
 161
 162 The optional zlib package for win32 is available at its homepage:
 163
 164         http://www.gzip.org/zlib/
 165
 166
 167 By default, the build process looks for these packages in
 168 C:\wireshark-win32-libs.  You can place them in a different directory, but
 169 you must update the WIRESHARK_LIBS variable in config.nmake accordingly.
 170
 171 The following lists the packages needed to compile Wireshark and the default
 172 locations where to unpack them, when the above method isn't used.
 173
 174     Package                               Default Location
 175     -------                               ----------------
 176     glib-2.4.7.zip                        C:\wireshark-win32-libs\glib
 177     glib-dev-2.4.7.zip                    C:\wireshark-win32-libs\glib
 178     gtk+-1.3.0-20030717.zip               C:\wireshark-win32-libs\gtk+
 179     gtk+-dev-1.3.0-20030115.zip           C:\wireshark-win32-libs\gtk+
 180     libiconv-1.9.1.bin.woe32.zip          C:\wireshark-win32-libs\libiconv-1.9.1.bin.woe32
 181     gettext-runtime-0.13.1.zip            C:\wireshark-win32-libs\gettext-runtime-0.13.1
 182     net-snmp-5.2.1.2.zip                  C:\wireshark-win32-libs
 183     wpdpack_3_0.zip                       C:\wireshark-win32-libs
 184
 185 and optional:
 186
 187     adns-1.0-win32-04.zip                 C:\wireshark-win32-libs
 188     pcre-4.4.zip                          C:\wireshark-win32-libs
 189     zlib123-dll.zip                       C:\wireshark-win32-libs\zlib123-dll
 190
 191 (to use the default locations, the directories in question should be
 192 created, and each zip file should be unpacked into the corresponding
 193 directory).  If you only want to change the C:\wireshark-win32-libs
 194 part, you just change the setting of WIRESHARK_LIBS in config.nmake; if
 195 you want to change subdirectories, you'll have to change the individual
 196 item for a package.  (Note that some zip files create the subdirectory -
 197 those zip files just have C:\wireshark-win32-libs in the list above - so
 198 if you don't want the package to be in that subdirectory, you'd have to
 199 rename the directory.)
 200
 201 The gettext runtime package provides intl.dll, which is needed by
 202 GLib 2.4.7.
 203
 204
 205 Compiling the Wireshark distribution using GTK+2
 206 ------------------------------------------------
 207
 208 The more recent version 2 of the GTK+ can be used to compile
 209 Wireshark with, but is still considered beta.
 210
 211 GTK+2 will look better in various ways, especially for WIN32 users.
 212
 213 You can get the required libraries from:
 214
 215 http://www.wireshark.org/distribution/win32/development/gtk2
 216
 217 or (like the GTK+1 libraries from the GTK+ for Win32 project):
 218
 219 http://www.gimp.org/~tml/gimp/win32/downloads.html
 220
 221 If you want to try a build with GTK+2.x these Extra libraries are needed
 222
 223     Package                               Default Location
 224     -------                               ----------------
 225     gtk+-2.4.14.zip                       C:\wireshark-win32-libs\gtk2
 226     gtk+-dev-2.4.14.zip                   C:\wireshark-win32-libs\gtk2
 227     pango-1.4.1.zip                       C:\wireshark-win32-libs\gtk2
 228     pango-dev-1.4.1.zip                   C:\wireshark-win32-libs\gtk2
 229     atk-1.6.0.zip                         C:\wireshark-win32-libs\gtk2
 230     atk-dev-1.6.0.zip                     C:\wireshark-win32-libs\gtk2
 231
 232 and optional:
 233
 234     gtk-wimp-0.7.0-bin.zip                C:\wireshark-win32-libs\gtk-wimp
 235
 236 Be sure to set GTK2_DIR in config.nmake correct, to be able to compile.
 237
 238 Running your freshly compiled Wireshark
 239 --------------------------------------
 240
 241 Make sure the glib and gtk DLL's are in your path or you use a directory
 242 where all required DLL's and the exe files reside.- i.e., that your
 243 path includes the directory (folder) or directories (folders) in which
 244 those DLLs are found - when you run Wireshark.
 245
 246 Note the wiretap*.dll must be in your path as well and if wiretap is changed
 247 be sure to put the new one in your path.
 248
 249 Plugins (gryphon.dll and mgcp.dll) can go in:
 250         <Wireshark installation directory>\plugins\<version>
 251
 252 Where <version> is the version number, without brackets.  For example,
 253 if you have Wireshark 0.99.1 installed in the default location, plugins
 254 will reside in C:\Program Files\Wireshark\plugins\0.99.1
 255
 256 Yes, the location of plugins needs to be more flexible.
 257
 258 Instructions for MS Visual C++
 259 ----------------------------
 260 Modify the config.nmake file in the top directory of the Wireshark source
 261 tree to work for your local configuration; if you don't have Python,
 262 comment out the line that defines PYTHON, otherwise set it to refer to
 263 the pathname of your Python interpreter executable.  You should not have
 264 to modify any other Makefile.
 265
 266 Note that perl is needed to build the documentation, the lines in config.nmake
 267
 268 POD2MAN=$(SH) pod2man
 269 POD2HTML=$(SH) pod2html
 270
 271 requires Cygwin bash and perl to work.
 272
 273 Many of the file and directory names used in the build process go past
 274 the old 8.3 naming limitations.  As a result, at least on Windows NT 4.0,
 275 Windows 2000, Windows XP, and Windows .NET Server, you should use the
 276 newer "cmd.exe" command interpreter instead of the old "command.com",
 277 as the "command.com" on Windows 2000, at least, can't handle non-8.3
 278 directory names.  (It may be that the "command.com" in Windows 95, Windows
 279 98, and Windows Me, as it's the only command interpreter in those systems,
 280 can handle those directories.  If not, it may not be possible to build
 281 Wireshark from the command line on those versions of Windows.)
 282
 283 Be sure that your command-line environment is set up to compile
 284 and link with MSVC++. When installing MSVC++, you can have your
 285 system's environment set up to always allow compiling from the
 286 command line, or you can invoke the vcvars32.bat script, which can
 287 usually be found in the "VC98\Bin" subdirectory of the directory in
 288 which Visual Studio was installed.
 289
 290 The first time you build Wireshark, run "nmake -f makefile.nmake distclean"
 291 in the top-level Wireshark source directory to make sure that the "config.h"
 292 files will be reconstructed from the "config.h.win32" files.  (If, for
 293 example, you have "config.h" files left over from a Unix build, a
 294 Windows build will fail.)
 295
 296 In the wireshark directory, type "nmake -f makefile.nmake". It will
 297 recurse into the subdirectories as appropriate.
 298
 299 Some generated source is created by traditionally "Unix-ish" tools.
 300
 301 If you are building from an official distribution, these files are
 302 already generated, although they were generated on a Unix-compatible
 303 system.  In most cases, the generated files can be used when building on
 304 Windows, but the files listed below as being generated by Flex can be
 305 used when building on Windows only when generated by a Windows version
 306 of Flex, so you will need a Windows version of Flex to do a Windows
 307 build.  Those generated files are removed by
 308 "nmake -f makefile.nmake distclean", to make sure that versions left over
 309 from a Unix build aren't used.
 310
 311 If you are building from a modified version of an official distribution,
 312 and you modified any of the source files listed below, you will need the
 313 tool(s) that generate output from those source files.
 314
 315 If building from a CVS image, you'll need all the tools to generate C
 316 source.
 317
 318 The "special" files and their requisite tools are:
 319
 320 Source                          Output                  Tool
 321 ------                          ------                  ----
 322 config.h.win32                  config.h                sed
 323 epan/config.h.win32             epan/config.h           sed
 324 image/wireshark.rc.in           image/wireshark.rc      sed
 325 image/tshark.rc.in              image/tshark.rc         sed
 326 image/editcap.rc.in             image/editcap.rc        sed
 327 image/mergecap.rc.in            image/mergecap.rc       sed
 328 image/text2pcap.rc.in           image/text2pcap.rc      sed
 329 wiretap/config.h.win32          wiretap/config.h        sed
 330 epan/dfilter/dfilter-scanner.l  epan/dfilter/*.c        Flex
 331 text2pcap-scanner.l             *.c                     Flex
 332 wiretap/ascend-scanner.l        *.c                     Flex
 333 wiretap/ascend-grammar.y        *.c,*.h                 Bison/Yacc
 334 ncp2222.py                      packet-ncp2222.c        Python
 335
 336 make-reg-dotc, packet*.c        register.c              Bash + grep + sed
 337 or
 338 make-reg-dotc.py, packet*.c     register.c              Python
 339
 340 make-tapreg-dotc, tap-*.c       tshark-tap-register.c
 341                                                         Bash + grep + sed
 342 make-tapreg-dotc, tap files     gtk/wireshark-tap-register.c
 343     in the gtk subdirectory                             Bash + grep + sed
 344
 345 The Makefile.nmake supplied with the Wireshark distribution will, if
 346 PYTHON is defined in config.nmake, attempt to make register.c with
 347 Python, since it is much much much faster than the shell version.  The
 348 reason it is faster is because the shell version launches multiple
 349 processes (grep, sed) for each source file, multiple times.  The Python
 350 script is one process.  This matters a lot on Win32.
 351
 352 If you have a Unix system handy, you can first build on Unix to create
 353 most of the source files that these tools make, then run the build on
 354 Windows.  That will avoid the need for these tools on your Windows
 355 computer.  This won't work for the files in the "image" directory,
 356 however, as those aren't built on Unix - they're only for Windows
 357 builds.  It also won't work for the "config.h" files; whilst those are
 358 built for Unix, they're specific to the platform on which you're
 359 building, and the "config.h" files constructed for a Unix build will not
 360 work with a Windows build.  In addition, it won't work for the files
 361 generated by Flex, as, for a Windows build, those have to be generated
 362 by a Windows version of Flex.
 363
 364 Most of those tools are available for Win32 systems as part of the
 365 Cygwin package:
 366
 367         http://www.cygwin.com/
 368
 369 After installing them, you will probably have to modify the config.nmake
 370 file to specify where the Cygwin binaries are installed.
 371 Note that installing cygwin with the "Default Text File Type" set to DOS
 372 may break the compilation because all the required tools may not be found.
 373 Set this parameter to UNIX instead.
 374
 375 Python for Win32 is available from:
 376
 377         http://www.python.org/
 378
 379
 380 Build an (NSIS based) installer
 381 -------------------------------
 382
 383 If you want to build your own installer, you need to get NSIS from:
 384
 385 http://nsis.sourceforge.net/home/
 386
 387 After installing it, you will probably have to modify the config.nmake
 388 file to specify where the NSIS binaries are installed and wether to use the modern UI or not.
 389 You will need NSIS version 2 or higher, to build an installer with the modern user interface,
 390 and for a much smaller installer (using the lzma compression).
 391
 392 In the wireshark directory, type "nmake -f makefile.nmake packaging" to build the installer.
 393 Please be patient while the compression is done, it will take some time even on fast machines.
 394
 395 You will hopefully now see something like wireshark-setup-0.10.12.exe in the dir packaging/nsis.
 396
 397
 398 Installing GTK-Wimp
 399 -------------------
 400
 401 GTK-Wimp can be used to get a native Look-and-Feel on WinXP machines,
 402 especially with the new "coloured" WinXP theme. It will only take effect
 403 together with the GTK2 version of Wireshark.
 404
 405 No changes to the Wireshark sources are needed, GTK-Wimp simply changes the
 406 way GTK2 displays the widgets (by changing the GTK2 default theme).
 407
 408 GTK-Wimp will be automatically installed if you use the official Wireshark Setup.
 409 In this case, the files mentioned below are already existing at the appropriate
 410 places.
 411
 412 If GTK-Wimp wasn't installed, you can install it yourself (however, this
 413 method is error prone and therefore no longer recommended):
 414
 415 1. Go to http://gtk-wimp.sourceforge.net/
 416 2. Download the ZIP archive containing the library and the theme
 417 3. Locate the installation directory of Wireshark (C:\Program Files\Wireshark)
 418 4. Create a subdirectory 'share\themes\Default\gtk-2.0'
 419 5. Drop the file 'gtkrc' in 'share\themes\Default\gtk-2.0'
 420 6. Create a subdirectory named 'lib\gtk-2.0\2.4.0\engines'
 421 7. Drop the 'libwimp.dll' library in 'lib\gtk-2.0\2.4.0\engines'
 422
 423 When you're finished, you should have:
 424
 425 C:\Program Files\Wireshark\lib\gtk-2.0\2.4.0\engines\libwimp.dll
 426 C:\Program Files\Wireshark\share\themes\Default\gtk-2.0\gtkrc
 427
 428 After (re-)starting Wireshark, you should now see it's widgets in the modern
 429 WinXP style on your screen.
 430
 431
 432 Problems with MS Visual C++ Version 7 / VC.NET
 433 ----------------------------------------------
 434
 435 There are known problems with DLL's.
 436 If Wireshark is compiled with MSVC Version 7, there are
 437 conflicts in the MSVCRT DLL's, The MSVCRT.DLL includes the standard
 438 ANSI-C functions like fopen, malloc, etc..  MSVCRT.DLL is shipped with
 439 the MSVC 6 compiler versions, and dynamically linked to prebuild DLL's
 440 like the one's for gtk, glib and such.  The MSVC 7 compiler now uses and
 441 ships MSVCRT71.DLL with it, which is incompatible with MSVCRT.DLL.  So
 442 when using the MSVC 7 compiler, some parts of the Wireshark code uses
 443 MSVCRT71.DLL, and some others (indirectly from e.g. the gtk DLL) will
 444 use MSVCRT.DLL.  This will result in incorrect file handles and such.
 445
 446 The same problem seems to apply on all MSVC compilers after version 6, like the
 447 "Microsoft Visual C++ Toolkit 2003".
 448
 449
 450 Instructions for Cygwin
 451 -----------------------
 452
 453 It is possible to build Wireshark under Cygwin using their version
 454 of XFree86. References:
 455  - http://www.ethereal.com/lists/ethereal-dev/200205/msg00107.html
 456  - http://www.ethereal.com/lists/ethereal-dev/200302/msg00026.html
 457
 458 To get it running, execute the following steps:
 459
 460 1. Install the required cygwin packages (compiler, scripting, X, zlib)
 461    with the CygWin setup.exe tool (http://www.cygwin.com/).
 462    You need the base Xfree86 support plus the X headers package in order
 463    to be able to compile the gtk+ package.
 464
 465 2. Download glib-1.2.10 and gtk+-1.2.10 from a mirror of www.gnome.org.
 466
 467 3. Retrieve the patches for glib-1.2.10 and gtk+-1.2.10 from
 468    http://homepage.ntlworld.com/steven.obrien2/
 469
 470  + glib-1.2.10
 471    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
 472           /libs/patches/glib-1.2.10-cygwin.patch
 473
 474  + gtk+-1.2.10
 475    http://homepage.ntlworld.com/steven.obrien2/ (URL cont'd on next line)
 476           /libs/patches/gtk+-1.2.10-cygwin.patch
 477
 478 4. Compile and install both packages after patching (see instructions
 479    at the bottom of http://homepage.ntlworld.com/steven.obrien2/):
 480
 481    Set the path:
 482
 483      $ PATH=/opt/gnome/bin:/usr/X11R6/bin:$PATH
 484
 485    For glib-1.2.10:
 486
 487      $ cd glib-1.2.10
 488      $ patch -p1 < /path/to/glib-1.2.10-cygwin.patch
 489      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome --with-threads=posix
 490      $ make
 491      $ make check
 492      $ make install
 493
 494    For gtk+-1.2.10:
 495
 496      $ cd gtk+-1.2.10
 497      $ patch -p1 < /path/to/gtk+-1.2.10-cygwin.patch
 498      $ CFLAGS=-O2 ./configure --prefix=/opt/gnome
 499      $ make
 500      $ make check
 501      $ make install
 502
 503 5. Patch Makefile.am in <wireshark-src>/gtk/Makefile.am by
 504    removing "ethclist.c" from the dependencies.
 505
 506    This patch is required since the private GTK+ clist widget
 507    (was required for earlier versions of GTK+ but prevents Wireshark
 508    from running with cygwin).
 509
 510 6. Configure and make Wireshark:
 511
 512    Set the path (if this has not yet been done earlier)
 513
 514      $ PATH=/opt/gnome/bin:$PATH
 515
 516      $ ./autogen.sh
 517      $ ./configure --config-cache --without-pcap
 518      $ make
 519
 520 7. Start X
 521
 522      $ sh /usr/X11R6/bin/startxwin.sh
 523
 524     Or you can start it from C:\cygwin\usr\X11R6\bin\startxwin.bat
 525
 526 8. Run wireshark (add /opt/gnome/bin to $PATH if this is not yet done)
 527
 528      $ <wireshark-src>/wireshark
 529
 530     And voila! Behold the mighty sniffer in all its glory!
 531
 532     Note that the plugin dissectors must be installed (make install) if you
 533     want to use them. Note also that running "make install" produces lots of
 534     output to the console; this is normal.
 535
 536 Note: Compiling Wireshark under cygwin takes a lot of time, because the
 537 generation of 'register.c' takes ages. If you only edit one dissector and
 538 you know what you're doing, it is acceptable to uncomment the generation
 539 of the file 'register.c' in Makefile. Look for the 'register.c' target:
 540
 541     register.c: $(DISSECTOR_SRC) $(srcdir)/make-reg-dotc
 542         @echo Making register.c
 543         # @$(srcdir)/make-reg-dotc register.c $(srcdir) $(DISSECTOR_SRC)
 544         @echo Skipping generation of register.c
 545
 546 Of course, you need to generate the 'register.c' file at least once.
 547
 548 Note: You can also capture packets on a cygwin built Wireshark. You then have
 549 to unpack the WinPCap development package, install the files in lib/ and
 550 include/ in say /usr/lib and /usr/include (they must be in the search path of
 551 the compiler and linker, otherwise you have to specify the configure option
 552 --with-pcap=/location/to/pcap so the packet capture functionality can be used.
 553 In order to run Wireshark, you have to add the .dll files in a directory in the
 554 PATH (e.g., /bin).
 555 Should you want packet capturing enabled in the cygwin build, then you have to
 556 remove --without-pcap from step 6.