Wireshark 0.99.7 User Guide
Wireshark Developer's Guide
24295 for Wireshark 0.99.7
Ulf Lamping,
Wireshark Developer's Guide:
24295 for Wireshark 0.99.7
by Ulf Lamping
Copyright © 2004-2007 Ulf Lamping
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License,
Version 2 or any later version published by the Free Software Foundation.
All logos and trademarks in this document are property of their respective owner.
Table of Contents
Preface ............................................................................................................. viii
1. Foreword .............................................................................................. viii
2. Who should read this document? ................................................................. ix
3. Acknowledgements .................................................................................... x
4. About this document ................................................................................. xi
5. Where to get the latest copy of this document? .............................................. xii
6. Providing feedback about this document ..................................................... xiii
I. Wireshark Build Environment ............................................................................... 1
1. Introduction .............................................................................................. 2
1.1. Introduction ................................................................................... 2
1.2. What is Wireshark? ......................................................................... 3
1.3. Platforms Wireshark runs on ............................................................. 4
1.3.1. Unix ................................................................................... 4
1.3.2. Linux ................................................................................. 4
1.3.3. Microsoft Windows ............................................................... 5
1.4. Development and maintenance of Wireshark ........................................ 6
1.4.1. Programming language(s) used ................................................ 6
1.4.2. Open Source Software ........................................................... 6
1.5. Releases and distributions ................................................................. 8
1.5.1. Binary distributions ............................................................... 8
1.5.2. Source code distributions ....................................................... 8
1.6. Automated Builds (Buildbot) ............................................................. 9
1.6.1. Advantages .......................................................................... 9
1.6.2. What does the Buildbot do? .................................................... 9
1.7. Reporting problems and getting help ..................................................10
1.7.1. Website .............................................................................10
1.7.2. Wiki ..................................................................................10
1.7.3. FAQ ..................................................................................10
1.7.4. Other sources ......................................................................10
1.7.5. Mailing Lists ......................................................................10
1.7.6. Bug database (Bugzilla) ........................................................11
1.7.7. Reporting Problems ..............................................................11
1.7.8. Reporting Crashes on UNIX/Linux platforms ............................12
1.7.9. Reporting Crashes on Windows platforms ................................12
2. Quick Setup .............................................................................................14
2.1. UNIX: Installation ..........................................................................14
2.2. Win32: Step-by-Step Guide ..............................................................15
2.2.1. Install Microsoft C compiler and Platform SDK .........................15
2.2.2. Install Cygwin .....................................................................15
2.2.3. Install Python ......................................................................16
2.2.4. Install Subversion Client .......................................................16
2.2.5. Install and Prepare Sources ....................................................16
2.2.6. Prepare cmd.exe ..................................................................17
2.2.7. Verify installed tools ............................................................17
2.2.8. Install Libraries ...................................................................18
2.2.9. Distclean Sources ................................................................18
2.2.10. Build Wireshark .................................................................18
2.2.11. Debug Environment Setup (XXX) .........................................19
2.2.12. Optional: Create User's and Developer's Guide ........................19
2.2.13. Optional: Create a Wireshark Installer ....................................19
3. Work with the Wireshark sources .................................................................21
3.1. Introduction ..................................................................................21
3.2. The Wireshark Subversion repository .................................................22
3.2.1. The web interface to the Subversion repository ..........................22
3.3. Obtain the Wireshark sources ...........................................................24
3.3.1. Anonymous Subversion access ...............................................24
3.3.2. Anonymous Subversion web interface .....................................24
iv
Wireshark Developer's Guide
3.3.3. Buildbot Snapshots ..............................................................24
3.3.4. Released sources .................................................................25
3.4. Update the Wireshark sources ...........................................................26
3.4.1. ... with Anonymous Subversion access .....................................26
3.4.2. ... from zip files ...................................................................26
3.5. Build Wireshark .............................................................................27
3.5.1. Unix ..................................................................................27
3.5.2. Win32 native ......................................................................27
3.6. Run generated Wireshark .................................................................29
3.7. Debug your generated Wireshark ......................................................30
3.7.1. Win32 native ......................................................................30
3.8. Make changes to the Wireshark sources ..............................................31
3.9. Contribute your changes ..................................................................32
3.9.1. What is a diff file (a patch)? ...................................................32
3.9.2. Generate a patch ..................................................................33
3.9.3. Some tips for a good patch .....................................................34
3.9.4. Code Requirements ..............................................................34
3.9.5. Sending your patch for inclusion .............................................35
3.10. Apply a patch from someone else ....................................................37
3.10.1. Using patch .......................................................................37
3.10.2. CVS diff (obsolete) ............................................................37
3.11. Add a new file to the Subversion repository .......................................39
3.12. Binary packaging ..........................................................................40
3.12.1. Debian: .deb packages .........................................................40
3.12.2. Red Hat: .rpm packages .......................................................40
3.12.3. Win32: NSIS .exe installer ...................................................40
4. Tool Reference .........................................................................................43
4.1. Introduction ..................................................................................43
4.2. Win32: Cygwin .............................................................................44
4.2.1. Add/Update/Remove Cygwin Packages ...................................44
4.3. GNU compiler toolchain (UNIX or Win32 Cygwin) .............................45
4.3.1. gcc (GNU compiler collection) ...............................................45
4.3.2. gdb (GNU project debugger) ..................................................45
4.3.3. ddd (GNU Data Display Debugger) .........................................45
4.3.4. make (GNU Make) ..............................................................46
4.4. Microsoft compiler toolchain (Win32 native) .......................................47
4.4.1. Toolchain Package Alternatives ..............................................47
4.4.2. Legal issues with MSVC > V6? ..............................................49
4.4.3. cl.exe (C Compiler) ..............................................................50
4.4.4. nmake.exe (Make) ...............................................................51
4.4.5. link.exe (Linker) ..................................................................51
4.4.6. C-Runtime "Redistributable" files ...........................................51
4.4.7. Windows (Platform) SDK .....................................................53
4.4.8. HTML Help ........................................................................53
4.4.9. Debugger ...........................................................................54
4.5. bash .............................................................................................55
4.5.1. UNIX or Win32 Cygwin: GNU bash .......................................55
4.5.2. Win32 native: - ...................................................................55
4.6. python ..........................................................................................56
4.6.1. UNIX or Win32 Cygwin: python ............................................56
4.6.2. Win32 native: python ...........................................................56
4.7. perl ..............................................................................................57
4.7.1. UNIX or Win32 Cygwin: perl ................................................57
4.7.2. Win32 native: perl ...............................................................57
4.8. sed ..............................................................................................58
4.8.1. UNIX or Win32 Cygwin: sed .................................................58
4.8.2. Win32 native: sed ................................................................58
4.9. yacc (bison) ..................................................................................59
4.9.1. UNIX or Win32 Cygwin: bison ..............................................59
4.9.2. Win32 native: bison .............................................................59
4.10. flex ............................................................................................60
4.10.1. UNIX or Win32 Cygwin: flex ..............................................60
4.10.2. Win32 native: flex ..............................................................60
v
Wireshark Developer's Guide
4.11. Subversion (SVN) client (optional) ..................................................61
4.11.1. UNIX or Win32 Cygwin: svn ...............................................61
4.11.2. Win32 native: svn ..............................................................61
4.12. Subversion (SVN) GUI client (optional) ...........................................62
4.12.1. UNIX or Win32 Cygwin: rapidSVN, subcommander ................62
4.12.2. Win32 native: TortoiseSVN .................................................62
4.13. diff (optional) ..............................................................................63
4.13.1. UNIX or Win32 Cygwin: GNU diff .......................................63
4.13.2. Win32 native: diff ..............................................................63
4.14. patch (optional) ............................................................................64
4.14.1. UNIX or Win32 Cygwin: patch ............................................64
4.14.2. Win32 native: patch ............................................................64
4.15. Win32: GNU wget (optional) ..........................................................65
4.16. Win32: GNU unzip (optional) .........................................................66
4.17. Win32: NSIS (optional) .................................................................67
5. Library Reference .....................................................................................69
5.1. Introduction ..................................................................................69
5.2. Binary library formats .....................................................................70
5.2.1. Unix ..................................................................................70
5.2.2. Win32: MSVC ....................................................................70
5.2.3. Win32: cygwin gcc ..............................................................70
5.3. Win32: Automated library download .................................................71
5.3.1. Initial download ..................................................................71
5.3.2. Update of a previous download ..............................................71
5.4. GTK+ / GLib / GDK / Pango / ATK / GNU gettext / GNU libiconv .........73
5.4.1. Unix ..................................................................................73
5.4.2. Win32 MSVC .....................................................................73
5.5. Net-SNMP (optional) ......................................................................74
5.5.1. Unix ..................................................................................74
5.5.2. Win32 MSVC .....................................................................74
5.6. GNU adns (optional) .......................................................................75
5.6.1. Unix ..................................................................................75
5.6.2. Win32 MSVC .....................................................................75
5.7. PCRE (optional) .............................................................................76
5.7.1. Unix ..................................................................................76
5.7.2. Win32 MSVC .....................................................................76
5.8. zlib (optional) ................................................................................77
5.8.1. Unix ..................................................................................77
5.8.2. Win32 MSVC .....................................................................77
5.9. libpcap/WinPcap (optional) ..............................................................78
5.9.1. Unix: libpcap ......................................................................78
5.9.2. Win32 MSVC: WinPcap .......................................................78
5.10. GnuTLS (optional) ........................................................................79
5.10.1. Unix ................................................................................79
5.10.2. Win32 MSVC ...................................................................79
5.11. Gcrypt (optional) ..........................................................................80
5.11.1. Unix ................................................................................80
5.11.2. Win32 MSVC ...................................................................80
5.12. Kerberos (optional) .......................................................................81
5.12.1. Unix ................................................................................81
5.12.2. Win32 MSVC ...................................................................81
5.13. LUA (optional) ............................................................................82
5.13.1. Unix ................................................................................82
5.13.2. Win32 MSVC ...................................................................82
5.14. PortAudio (optional) .....................................................................83
5.14.1. Unix ................................................................................83
5.14.2. Win32 MSVC ...................................................................83
5.15. Win32: GTK WIMP (optional) for GTK 2.x only ...............................84
II. Wireshark Development (incomplete) ..................................................................86
6. How Wireshark Works ..............................................................................87
6.1. Introduction ..................................................................................87
6.2. Overview ......................................................................................88
6.3. Capturing packets ...........................................................................90
vi
Wireshark Developer's Guide
6.4. Capture Files .................................................................................91
6.5. Dissect packets ..............................................................................92
7. Introduction .............................................................................................94
7.1. Source overview ............................................................................94
7.2. Coding styleguides .........................................................................95
7.3. The GLib library ............................................................................96
8. Packet capturing .......................................................................................98
8.1. How to add a new capture type to libpcap ...........................................98
9. Packet dissection ....................................................................................100
9.1. How it works ............................................................................... 100
9.2. Adding a basic dissector ................................................................101
9.2.1. Setting up the dissector ....................................................... 101
9.2.2. Dissecting the details of the protocol ..................................... 103
9.2.3. Improving the dissection information ..................................... 106
9.3. How to handle transformed data ...................................................... 109
9.4. How to reassemble split packets ...................................................... 110
9.4.1. How to reassemble split UDP packets .................................... 110
9.4.2. How to reassemble split TCP Packets .................................... 113
9.5. How to tap protocols ..................................................................... 115
9.6. How to produce protocol stats .........................................................116
9.7. How to use conversations .............................................................. 118
10. User Interface ....................................................................................... 120
10.1. Introduction ............................................................................... 120
10.2. The GTK library ......................................................................... 121
10.2.1. GTK Version 1.x ............................................................. 121
10.2.2. GTK Version 2.x ............................................................. 121
10.2.3. Compatibility between 1.x and 2.x ....................................... 122
10.2.4. GTK resources on the web .................................................122
10.3. GUI Reference documents ............................................................ 124
10.4. Adding/Extending Dialogs ........................................................... 125
10.5. Widget naming ........................................................................... 126
10.6. Common GTK programming pitfalls .............................................. 127
10.6.1. Usage of gtk_widget_show() / gtk_widget_show_all() ............ 127
A. This Document's License (GPL) ........................................................................ 129
vii
Preface
1. Foreword
This book tries to give you a guide to start your own experiments into the wonderful world of Wireshark development.
Developers who are new to Wireshark often have a hard time getting their development environment up and running. This is especially true for Win32 developers, as a lot of the tools and methods
used when building Wireshark are much more common in the UNIX world than on Win32.
The first part of this book will describe how to set up the environment needed to develop Wireshark.
The second part of this book will describe how to change the Wireshark source code.
We hope that you find this book useful, and look forward to your comments.
viii
Preface
2. Who should read this document?
The intended audience of this book is anyone going into the development of Wireshark.
This book is not intended to explain the usage of Wireshark in general. Please refer the Wireshark
User's Guide about Wireshark usage.
By reading this book, you will learn how to develop Wireshark. It will hopefully guide you around
some common problems that frequently appear for new (and sometimes even advanced) developers
of Wireshark.
ix
3. Acknowledgements
The authors would like to thank the whole Wireshark team for their assistance. In particular, the authors would like to thank:
• Gerald Combs, for initiating the Wireshark project.
• Guy Harris, for many helpful hints and his effort in maintaining the various contributions on the
mailing lists.
The authors would also like to thank the following people for their helpful feedback on this document:
• XXX - Please give feedback :-)
And of course a big thank you to the many, many contributors of the Wireshark development community!
Preface
x
Preface
4. About this document
This book was developed by Ulf Lamping.
It is written in DocBook/XML.
You will find some specially marked parts in this book:
This is a warning!
You should pay attention to a warning, as otherwise data loss might occur.
This is a note!
A note will point you to common mistakes and things that might not be obvious.
This is a tip!
Tips will be helpful for your everyday work developing Wireshark.
xi
Preface
5. Where to get the latest copy of this document?
The latest copy of this documentation can always be found at: http://www.wireshark.org/docs/ in
PDF (A4 and US letter), HTML (single and chunked) and CHM format.
xii
Preface
6. Providing feedback about this document
Should you have any feedback about this document, please send it to the authors through wireshark-
dev[AT]wireshark.org.
xiii
Preface
xiv
Part I. Wireshark Build
Environment
Part I. Wireshark Build Environment
The first part describes how to set up the tools, libraries and source needed to generate Wire-
shark, and how to do some typical development tasks.
Part II. Wireshark Development
The second part describes how the Wireshark sources are structured and how to change the sources
(e.g. adding a new dissector).
Chapter 1. Introduction
1.1. Introduction
This chapter will provide you with information about Wireshark development in general.
2
Introduction
1.2. What is Wireshark?
Well, if you want to start Wireshark development, you might already know what Wireshark is doing. If not, please have a look at the Wireshark User's Guide, which will provide a lot of general information about it.
3
Introduction
1.3. Platforms Wireshark runs on
Wireshark currently runs on most UNIX platforms and various Windows platforms. It requires
GTK+, GLib, libpcap and some other libraries in order to run.
As Wireshark is developed in a platform independent way and uses libraries (such as the GTK+
GUI library) which are available for a lot of different platforms, it's thus available on a wide variety
of platforms.
If a binary package is not available for your platform, you should download the source and try to
build it. Please report your experiences to wireshark-dev[AT]wireshark.org.
Binary packages are available for at least the following platforms:
1.3.1. Unix
• Apple Mac OS X
• BeOS
• FreeBSD
• HP-UX
• IBM AIX
• NetBSD
• OpenBSD
• SCO UnixWare/OpenUnix
• SGI Irix
• Sun Solaris/Intel
• Sun Solaris/Sparc
• Tru64 UNIX (formerly Digital UNIX)
1.3.2. Linux
• Debian GNU/Linux
• Gentoo Linux
• IBM S/390 Linux (Red Hat)
• Mandrake Linux
• PLD Linux
• Red Hat Linux
• Rock Linux
• Slackware Linux
4
• Suse Linux
1.3.3. Microsoft Windows
Thanks to the Win32 API, development on all Windows platforms will be done in a very similar
way. All Windows platforms referred to as Win32, Win or Windows may be used with the same
meaning. Older Windows versions are no longer supported by Wireshark. As Windows CE differs a
lot compared to the other Windows platforms mentioned, Wireshark will not run on Windows CE
and there are no plans to support it.
• Windows Server 2003 / XP / 2000
Introduction
5
Introduction
1.4. Development and maintenance of Wireshark
Wireshark was initially developed by Gerald Combs. Ongoing development and maintenance of
Wireshark is handled by the Wireshark team, a loose group of individuals who fix bugs and provide
new functionality.
There have also been a large number of people who have contributed protocol dissectors to Wireshark, and it is expected that this will continue. You can find a list of the people who have contributed code to Wireshark by checking the about dialog box of Wireshark, or have a look at the http://
anonsvn.wireshark.org/wireshark/trunk/AUTHORS page on the Wireshark web site.
The communication between the developers is usually done through the developer mailing list,
which can be joined by anyone interested in the development process. At the time this document
was written, more than 500 persons were subscribed to this mailing list!
It is strongly recommended to join the developer mailing list, if you are going to do any Wireshark
development. See Section 1.7.5, “Mailing Lists” about the different Wireshark mailing lists available.
1.4.1. Programming language(s) used
Almost any part of Wireshark is implemented in plain ANSI C.
The typical task for a new Wireshark developer is to extend an existing, or write a new dissector for
a specific network protocol. As (almost) any dissector is written in plain old ANSI C, a good knowledge about ANSI C will be sufficient for Wireshark development in almost any case.
So unless you are going to change the development process of Wireshark itself, you won't come in
touch with any other programming language than ANSI C (such as perl or python, which are used
only in the Wireshark build process).
Beside the usual tools for developing a program in C (compiler, make, ...), the build process uses
some additional helper tools (Perl, Python, Sed, ...), which are needed for the build process when
Wireshark is to be installed from the released source packages. If Wireshark is installed from a binary package, none of these helper tools are needed on the target system.
1.4.2. Open Source Software
Wireshark is an open source software project, and is released under the GNU General Public Li-
cence (GPL). You can freely use Wireshark on any number of computers you like, without worrying
about license keys or fees or such. In addition, all source code is freely available under the GPL. Because of that, it is very easy for people to add new protocols to Wireshark, either as plugins, or built
into the source, and they often do!
You are welcome to modify Wireshark to suit your own needs, and it would be appreciated if you
contribute your improvements back to the Wireshark team.
You gain three benefits by contributing your improvements back to the community:
• Other people who find your contributions useful will appreciate them, and you will know that
you have helped people in the same way that the developers of Wireshark have helped people.
• The developers of Wireshark might improve your changes even more, as there's always room for
improvements. Or they may implement some advanced things on top of your code, which can be
useful for yourself too.
• The maintainers and developers of Wireshark will maintain your code as well, fixing it when
API changes or other changes are made, and generally keeping it in tune with what is happening
6
Introduction
with Wireshark. So if Wireshark is updated (which is done often), you can get a new Wireshark
version from the website and your changes will already be included without any effort for you.
The Wireshark source code and binary kits for some platforms are all available on the download
page of the Wireshark website: http://www.wireshark.org/download/.
7
Introduction
1.5. Releases and distributions
The officially released files can be found at: http://www.wireshark.org/download/. A new Wireshark
version is released after significant changes compared to the last release are completed or a serious
security issue is encountered. The typical release schedule is about every 4-8 weeks (although this
may vary).
There are two kinds of distributions: binary and source; both have their advantages and disadvantages.
1.5.1. Binary distributions
Binary distributions are usually easy to install (as simply starting the appropriate file is usually the
only thing to do). They are available for the following systems:
• Win32 (.exe file). The typical Windows end user method is used to get a setup.exe file which
will install all the required things for him.
• Win32 U3 (.u3 file). Special distribution for U3 capable USB memory sticks.
• Debian (.deb file). A user of a Debian Package Manager (DPKG) based system obtains a .deb
file from which the package manager checks the dependencies and installs the software.
• Red Hat (.rpm file). A user of a Red Hat Package Manager (RPM) based system obtains an .rpm
file from which the package manager checks the dependencies and installs the software.
• Solaris. A Solaris user obtains a file from which the package manager (PKG) checks the dependencies and installs the software.
However, if you want to start developing with Wireshark, the binary distributions won't be too helpful, as you need the source files, of course.
For details about how to build these binary distributions yourself, e.g. if you need a distribution for a
special audience, see Section 3.12, “Binary packaging”.
1.5.2. Source code distributions
It's still common for UNIX developers to give the end user a source tarball and let the user compile
it on their target machine (configure, make, make install). However, for different UNIX (Linux) distributions it's becoming more common to release binary packages (e.g. .deb or .rpm files) these
days.
You should use the released sources if you want to build Wireshark from source on your platform
for productive use. However, if you going to develop changes to the Wireshark sources, it might be
better to use the latest SVN sources. For details about the different ways to get the Wireshark source
code see Section 3.3, “Obtain the Wireshark sources”.
Before building Wireshark from a source distribution, make sure you have all the tools and libraries
required to build. The following chapters will describe the required tools and libraries in detail.
8
Introduction
1.6. Automated Builds (Buildbot)
The Wireshark Buildbot automatically rebuilds Wireshark on every change of the source code repository and indicates problematic changes. This frees the developers from repeating (and annoying)
work, so time can be spent on more interesting tasks.
1.6.1. Advantages
• Recognizing (cross platform) build problems - early. Compilation problems can be narrowed
down to a few commits, making a fix much easier.
• "Health status" overview of the sources. A quick look at: http://buildbot.wireshark.org/ trunk/
gives a good "feeling" if the sources are currently "well". On the other hand, if all is "red", an
update of a personal source tree might better be done later ...
• "Up to date" binary packages are available. After a change was committed to the repository, a
binary package / installer is usually available within a few hours at: http://www.wireshark.org/
download/automated/. This can be quite helpful, e.g. a bug reporter can easily verify a bugfix by
installing a recent build.
• Automated regression tests. In particular, the fuzz tests often indicate "real life" problems that
are otherwise hard to find.
1.6.2. What does the Buildbot do?
The Buildbot will do the following (to a different degree on the different platforms):
• checkout from the source repository
• build
• create binary package(s) / installer
• create source package (and check completeness)
• run regression tests
Each step is represented at the status page by a rectangle, green if it succeeded or red if it failed.
Most steps provide a link to the corresponding console logfile, to get additional information.
The Buildbot runs on a platform collection that represents the different "platform specialties" quite
well:
• Windows XP x86 (Win32, little endian, MSVC)
• Ubuntu x86 (Linux, little endian, gcc)
• Solaris SPARC (Solaris, big endian, gcc)
• Mac OS-X PPC (BSD, big endian, gcc)
Each platform is represented at the status page by a single column, the most recent entries are at the
top.
9
Introduction
1.7. Reporting problems and getting help
If you have problems, or need help with Wireshark, there are several places that may be of interest
to you (well, beside this guide of course).
1.7.1. Website
You will find lot's of useful information on the Wireshark homepage at http://www.wireshark.org.
1.7.2. Wiki
The Wireshark Wiki at http://wiki.wireshark.org provides a wide range of information related to
Wireshark and packet capturing in general. You will find a lot of information not part of this developer's guide. For example, there is an explanation how to capture on a switched network, an ongoing effort to build a protocol reference and a lot more.
And best of all, if you would like to contribute your knowledge on a specific topic (maybe a network protocol you know well), you can edit the wiki pages by simply using your webbrowser.
1.7.3. FAQ
The "Frequently Asked Questions" will list often asked questions and the corresponding answers.
Read the FAQ!
Before sending any mail to the mailing lists below, be sure to read the FAQ, as it will
often answer the question(s) you might have. This will save yourself and others a lot of
time (keep in mind that a lot of people are subscribed to the mailing lists).
You will find the FAQ inside Wireshark by clicking the menu item Help/Contents and selecting the
FAQ page in the upcoming dialog.
An online version is available at the Wireshark website: http://www.wireshark.org/faq.html. You
might prefer this online version, as it's typically more up to date and the HTML format is easier to
use.
1.7.4. Other sources
If you don't find the information you need inside this book, there are various other sources of information:
• the file doc/README.developer and all the other README.xxx files in the source code these are various documentation files on different topics
• the Wireshark source code
• tool documentation of the various tools used (e.g. manpages of sed, gcc, ...)
• the different mailing lists: see Section 1.7.5, “Mailing Lists”
• ...
1.7.5. Mailing Lists
There are several mailing lists available on specific Wireshark topics:
10
Introduction
wireshark-announce This mailing list will inform you about new program releases, which
usually appear about every 4-8 weeks.
wireshark-users This list is for users of Wireshark. People post questions about build-
ing and using Wireshark, others (hopefully) provide answers.
wireshark-dev This list is for Wireshark developers. People post questions about the
development of Wireshark, others (hopefully) provide answers. If you
want to start developing a protocol dissector, join this list.
wireshark-bugs This list is for Wireshark developers. Everytime a change to the bug
database occurs, a mail to this mailing list is generated. If you want to
be notified about all the changes to the bug database, join this list. Details about the bug database can be found in Section 1.7.6, “Bug data-
base (Bugzilla)”.
wireshark-commits This list is for Wireshark developers. Everytime a change to the SVN
repository is checked in, a mail to this mailing list is generated. If you
want to be notified about all the changes to the SVN repository, join
this list. Details about the SVN repository can be found in Section 3.2,
“The Wireshark Subversion repository”.
You can subscribe to each of these lists from the Wireshark web site: http://www.wireshark.org.
Simply select the mailing lists link on the left hand side of the site. The lists are archived at the
Wireshark web site as well.
Tip!
You can search in the list archives to see if someone previously asked the same question and maybe already got an answer. That way you don't have to wait until someone
answers your question.
1.7.6. Bug database (Bugzilla)
The Wireshark community collects bug reports in a Bugzilla database at http://bugs.wireshark.org.
This database is filled with manually filed bug reports, usually after some discussion on wiresharkdev, and bug reports from the QA build tools.
1.7.7. Reporting Problems
Note!
Before reporting any problems, please make sure you have installed the latest version
of Wireshark.
If you report problems, provide as much information as possible. In general, just think about what
you would need to find that problem, if someone else sends you such a problem report. Also keep in
mind that people compile/run Wireshark on a lot of different platforms.
When reporting problems with Wireshark, it is helpful if you supply the following information:
1. The version number of Wireshark and the dependent libraries linked with it, e.g. GTK+, etc.
You can obtain this with the command wireshark -v.
2. Information about the platform you run Wireshark on.
3. A detailed description of your problem.
4. If you get an error/warning message, copy the text of that message (and also a few lines before
11
Introduction
and after it, if there are some), so others may find the build step where things go wrong. Please
don't give something like: "I get a warning when compiling x" as this won't give any direction
to look at.
Don't send large files!
Do not send large files (>100KB) to the mailing lists, just place a note that further data
is available on request. Large files will only annoy a lot of people on the list who are
not interested in your specific problem. If required, you will be asked for further data
by the persons who really can help you.
Don't send confidential information!
If you send captured data to the mailing lists, or add it to your bug report, be sure it
doesn't contain any sensitive or confidential information, such as passwords.
1.7.8. Reporting Crashes on UNIX/Linux platforms
When reporting crashes with Wireshark, it is helpful if you supply the traceback information
(besides the information mentioned in Section 1.7.7, “Reporting Problems”).
You can obtain this traceback information with the following commands:
$ gdb `whereis wireshark | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
backtrace
^D
$
Note
Type the characters in the first line verbatim! Those are back-tics there!
Note
backtrace is a gdb command. You should enter it verbatim after the first line shown
above, but it will not be echoed. The ^D (Control-D, that is, press the Control key and
the D key together) will cause gdb to exit. This will leave you with a file called
bt.txt in the current directory. Include the file with your bug report.
Note
If you do not have gdb available, you will have to check out your operating system's
debugger.
You should mail the traceback to the wireshark-dev[AT]wireshark.org mailing list, or append it to
your bug report.
1.7.9. Reporting Crashes on Windows platforms
The Windows distributions don't contain the symbol files (.pdb), because they are very large. For
this reason it's not possible to create a meaningful backtrace file from it. You should report your
crash just like other problems, using the mechanism from Section 1.7.7, “Reporting Problems”.
12
Introduction
13
Chapter 2. Quick Setup
2.1. UNIX: Installation
All the tools required are usually installed on a UNIX developer machine.
If a tool is not already installed on your system, you will typically use the installation package from
your distribution (by your favourite package manager: aptitude, yum, synaptics, ...).
If an install package is not available, or you have a reason not to use it (maybe because it's simply
too old), you can install that tool from source code. The following sections will provide you with the
webpage addresses where you can get these sources.
14
Quick Setup
2.2. Win32: Step-by-Step Guide
A quick setup guide for Win32 with recommended configuration.
Warning!
Unless you know exactly what you are doing, you should strictly follow the recommendations!
2.2.1. Install Microsoft C compiler and Platform SDK
You need to install:
1. C compiler: Download(474MB) and install "Visual C++ 2005 Express Edition"
2. Platform SDK : Download(420MB) and install Platform SDK Server 2003 R2
Install MSVC the usual way. Don't forget to install vcvars32.bat or call it manually before building
Wireshark. vcvars32.bat will set some required environment (e.g. the PATH) settings.
Other Microsoft C compiler variants possible!
It's possible to compile Wireshark with a wide range of Microsoft C compiler variants,
for details see Section 4.4, “Microsoft compiler toolchain (Win32 native)”!
Don't use cygwin's gcc!
Using cygwin's gcc is not recommended and will certainly not work (at least without a
lot of advanced tweaking). For further details on this topic, see Section 4.3, “GNU
compiler toolchain (UNIX or Win32 Cygwin)”.
XXX - mention the compiler and PSDK web installers - which significantly reduce download size and find out the required components
XXX - how to get the right PATH settings?
Why this is recommended: While this is a huge download, the 2005 express edition is the only free
(as in beer) version that includes the Visual Studio integrated debugger.
2.2.2. Install Cygwin
Download the cygwin installer and start it.
At the "Select Packages" page, you'll need to select some additional packages, which are not installed by default. Navigate to the required Category/Package row and click on the "Skip" item in
the "New" column so it shows a version number for:
• Archive/unzip
• Devel/bison
• Devel/flex
• Interpreters/perl
15
Quick Setup
• Utils/patch
• Web/wget
After clicking the Next button several times, the setup will then download and install the selected
packages (this may take a while).
Why this is recommended: Cygwin's bash version is required, as no native Win32 version is available. As additional packages can easily be added, the perl and alike packages are also used.
2.2.3. Install Python
Get the python 2.4 installer from: http://python.org/download/and install python into the default location (currently: C:/Python24).
Beware: python 2.5 won't work without modifications.
Why this is recommended: Cygwin's python package doesn't work on some machines, so the Win32
native package is recommended.
2.2.4. Install Subversion Client
Please note that the following is not required to build Wireshark, but can be quite helpful when
working with the sources.
Why this is recommended: updating a personal source tree is significantly easier to do with Subversion than downloading a zip file and merging new sources into a personal source tree "by hand".
2.2.4.1. Subversion
If you want to work with the Wireshark Subversion source repositories (which is highly recommended, see Section 3.3, “Obtain the Wireshark sources”), it's recommended to install Subversion. This
makes the first time setup easy and enables the Wireshark build process to determine your current
source code revision. You can download the setup from http://subversion.tigris.org/and simply install it.
2.2.4.2. TortoiseSVN
If you want to work with the Wireshark Subversion source repositories (which is highly recommended, see Section 3.3, “Obtain the Wireshark sources”), it's recommended to use TortoiseSVN for
your everyday work. You can download the setup from http://tortoisesvn.tigris.org/and simply install it.
2.2.5. Install and Prepare Sources
Tip
It's a good idea to successfully compile and run Wireshark at least once before you
start hacking the Wireshark sources for your own project!
1. Download sources : Download Wireshark sources into: C:\wireshark using TortoiseSVN
a. right click on the C:\ drive in Windows Explorer
b. in the upcoming context menu select "SVN checkout..." and then set:
16
Loading...