forked from osmocom/wireshark
561 lines
19 KiB
Plaintext
561 lines
19 KiB
Plaintext
// WSDG Chapter Introduction
|
||
|
||
[[ChapterIntroduction]]
|
||
|
||
== Introduction
|
||
|
||
[[ChIntroIntro]]
|
||
|
||
=== Introduction
|
||
|
||
This chapter will provide you with information about Wireshark
|
||
development in general.
|
||
|
||
[[ChIntroWhatIs]]
|
||
|
||
=== 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
|
||
link:{wireshark-users-guide-url}[Wireshark User’s Guide],
|
||
which will provide a lot of general information about it.
|
||
|
||
[[ChIntroPlatforms]]
|
||
|
||
=== Supported Platforms
|
||
|
||
Wireshark currently runs on most UNIX platforms and various Windows
|
||
platforms. It requires Qt, 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 Qt GUI library) which are available for many 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 mailto:{wireshark-dev-list-email}[].
|
||
|
||
Binary packages are available for the following platforms along with many
|
||
others:
|
||
|
||
==== Unix
|
||
|
||
* Apple macOS
|
||
|
||
* FreeBSD
|
||
|
||
* HP-UX
|
||
|
||
* IBM AIX
|
||
|
||
* NetBSD
|
||
|
||
* OpenBSD
|
||
|
||
* Oracle Solaris
|
||
|
||
==== Linux
|
||
|
||
* Debian GNU/Linux
|
||
|
||
* Ubuntu
|
||
|
||
* Gentoo Linux
|
||
|
||
* IBM S/390 Linux (Red Hat)
|
||
|
||
* Mandrake Linux
|
||
|
||
* PLD Linux
|
||
|
||
* Red Hat Linux
|
||
|
||
* Rock Linux
|
||
|
||
* Slackware Linux
|
||
|
||
* Suse Linux
|
||
|
||
==== Microsoft Windows
|
||
|
||
Wireshark supports Windows natively via the
|
||
https://en.wikipedia.org/wiki/Windows_API[Windows API]. Note that in
|
||
this documentation and elsewhere we tend to use the terms
|
||
“Win32”, “Win”, and “Windows” interchangeably to refer to the
|
||
Windows API. Wireshark runs on and can be compiled on the following
|
||
platforms:
|
||
|
||
* Windows 10 / Windows Server 2016
|
||
|
||
* Windows 8.1 / Windows Server 2012 R2
|
||
|
||
* Windows 8 / Windows Server 2012
|
||
|
||
* Windows 7 / Windows Server 2008 R2
|
||
|
||
Development on Windows Vista, Server 2008, and older versions may be possible but
|
||
is not supported.
|
||
|
||
[[ChIntroDevelopment]]
|
||
|
||
=== Development and maintenance of Wireshark
|
||
|
||
Wireshark was initially developed by Gerald Combs. Ongoing development
|
||
and maintenance of Wireshark is handled by the Wireshark core developers,
|
||
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 and other improvements 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 {wireshark-authors-url} 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
|
||
activities. 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 <<ChIntroMailingLists>> about the different
|
||
Wireshark mailing lists available.
|
||
|
||
==== Programming languages used
|
||
|
||
Most of Wireshark is implemented in plain ANSI C. A notable exception is
|
||
the code in _ui/qt_, which is written in {cpp}.
|
||
|
||
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 build 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 build and 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.
|
||
|
||
==== Open Source Software
|
||
|
||
Wireshark is an open source software (OSS) project, and is released under
|
||
the link:{gplv2-url}[GNU General Public License] (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 community.
|
||
|
||
|
||
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 you and other people.
|
||
|
||
* The developers of Wireshark might improve your changes even more, as there’s
|
||
always room for improvement. 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 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 packages for some platforms are all
|
||
available on the download page of the Wireshark website:
|
||
{wireshark-download-url}.
|
||
|
||
|
||
[[ChIntroReleases]]
|
||
|
||
=== Releases and distributions
|
||
|
||
The officially released files can be found at {wireshark-download-url}.
|
||
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.
|
||
|
||
[[ChIntroReleaseBinary]]
|
||
|
||
==== 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:
|
||
|
||
* Windows (.exe file). The typical Windows end user is used to getting
|
||
a setup.exe file which will install all the required things for him.
|
||
|
||
* Win32 PAF (.paf.exe file). Another Windows end user method is to get a
|
||
portable application file which will install all the required things for him.
|
||
|
||
* 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 RPM Package Manager (RPM) based system
|
||
obtains an .rpm file from which the package manager checks the dependencies
|
||
and installs the software.
|
||
|
||
* macOS (.dmg file). The typical macOS end user is used to getting a .dmg file
|
||
which will install all the required things for him.
|
||
|
||
* 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
|
||
<<ChSrcBinary>>.
|
||
|
||
[[ChIntroReleaseSource]]
|
||
|
||
==== 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 GIT sources. For details about the different ways to get the
|
||
Wireshark source code see <<ChSrcObtain>>.
|
||
|
||
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.
|
||
|
||
[[ChIntroAutomated]]
|
||
|
||
=== 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.
|
||
|
||
==== 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:
|
||
https://buildbot.wireshark.org/wireshark-master/[] 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: https://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.
|
||
|
||
==== What does the Buildbot do?
|
||
|
||
The Buildbot will do the following (to a different degree on the different
|
||
platforms):
|
||
|
||
* Check out from the source repository
|
||
|
||
* Build
|
||
|
||
* Create binary packages and installers
|
||
|
||
* Create source packages and run distribution checks
|
||
|
||
* 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 8.1 x86 (Win32, little endian, Visual Studio 2013)
|
||
|
||
* Windows Server 2012 R2 x86-64 (Win64, little endian, Visual Studio 2013)
|
||
|
||
* Ubuntu x86-64 (Linux, little endian, gcc, Clang)
|
||
|
||
* macOS x86-64 (BSD, little endian, Clang)
|
||
|
||
and two buildslaves that run static code analysis to help spot coding issues:
|
||
|
||
* Visual Studio Code Analysis (Win64, little endian, VS 2013)
|
||
|
||
* Clang Code Analysis (Linux, little endian, Clang)
|
||
|
||
Each platform is represented at the status page by a single column, the
|
||
most recent entries are at the top.
|
||
|
||
[[ChIntroHelp]]
|
||
|
||
|
||
=== 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).
|
||
|
||
[[ChIntroHomepage]]
|
||
|
||
==== Website
|
||
|
||
You will find lots of useful information on the Wireshark homepage at
|
||
{wireshark-main-url}.
|
||
|
||
[[ChIntroWiki]]
|
||
|
||
==== Wiki
|
||
|
||
The Wireshark Wiki at {wireshark-wiki-url} 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.
|
||
|
||
[[ChIntroFAQ]]
|
||
|
||
|
||
==== FAQ
|
||
|
||
The "Frequently Asked Questions" will list often asked questions and
|
||
the corresponding answers.
|
||
|
||
Before sending any mail to the mailing lists below, be sure to read the
|
||
FAQ, as it will often answer any questions 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:
|
||
{wireshark-faq-url}. You might prefer this online version as it’s
|
||
typically more up to date and the HTML format is easier to use.
|
||
|
||
[[ChIntroOtherSources]]
|
||
|
||
==== 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
|
||
|
||
[NOTE]
|
||
.Read the README
|
||
====
|
||
_README.developer_ is packed full with all kinds of details relevant
|
||
to the developer of Wireshark source code. Its companion file
|
||
_README.dissector_ advises you around common
|
||
pitfalls, shows you basic layout of dissector code, shows details of the
|
||
APIs available to the dissector developer, etc.
|
||
====
|
||
|
||
* The Wireshark source code
|
||
|
||
* Tool documentation of the various tools used
|
||
(e.g. manpages of sed, gcc, etc.)
|
||
|
||
* The different mailing lists. See <<ChIntroMailingLists>>
|
||
|
||
[[ChIntroMailingLists]]
|
||
|
||
==== Mailing Lists
|
||
|
||
There are several mailing lists available on specific Wireshark topics:
|
||
|
||
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 building 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. Every time 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 <<ChIntroBugDatabase>>.
|
||
|
||
wireshark-commits:: This list is for Wireshark developers. Every time a change to the GIT
|
||
repository is checked in, a mail to this mailing list is generated.
|
||
If you want to be notified about all the changes to the GIT
|
||
repository, join this list. Details about the GIT repository can be
|
||
found in <<ChSrcGitRepository>>.
|
||
|
||
You can subscribe to each of these lists from the Wireshark web site:
|
||
{wireshark-mailing-lists-url}. From there, you can choose which mailing
|
||
list you want to subscribe to by clicking on the
|
||
Subscribe/Unsubscribe/Options button under the title of the relevant
|
||
list. The links to the archives are included on that page as well.
|
||
|
||
[TIP]
|
||
.The archives are searchable
|
||
====
|
||
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.
|
||
====
|
||
|
||
[[ChIntroBugDatabase]]
|
||
|
||
==== Bug database (Bugzilla)
|
||
|
||
The Wireshark community collects bug reports in a Bugzilla database at
|
||
{wireshark-bugs-url}. This database is filled with manually filed bug
|
||
reports, usually after some discussion on wireshark-dev, and automatic
|
||
bug reports from the Buildbot tools.
|
||
|
||
[[ChIntroQA]]
|
||
|
||
==== Q&A Site
|
||
|
||
The Wireshark Q&A site at {wireshark-qa-url} offers a resource where
|
||
questions and answers come together. You have the option to search what
|
||
questions were asked before and what answers were given by people who
|
||
knew about the issue. Answers are graded, so you can pick out the best
|
||
ones easily. If your issue isn't discussed before you can post one
|
||
yourself.
|
||
|
||
[[ChIntroReportProblems]]
|
||
|
||
==== Reporting Problems
|
||
|
||
[NOTE]
|
||
.Test with the latest version
|
||
====
|
||
Before reporting any problems, please make sure you have installed the
|
||
latest version of Wireshark. Reports on older maintenance releases are
|
||
usually met with an upgrade request.
|
||
====
|
||
|
||
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:
|
||
|
||
. The version number of Wireshark and the dependent libraries linked with
|
||
it, e.g. Qt, GTK+, etc. You can obtain this with the command
|
||
`wireshark -v`.
|
||
|
||
. Information about the platform you run Wireshark on.
|
||
|
||
. A detailed description of your problem.
|
||
|
||
. If you get an error/warning message, copy the text of that message (and
|
||
also a few lines before 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.
|
||
|
||
[NOTE]
|
||
.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.
|
||
====
|
||
|
||
[WARNING]
|
||
.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. Visibility of such files can be limited to certain
|
||
groups in the Bugzilla database though.
|
||
====
|
||
|
||
==== 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
|
||
<<ChIntroReportProblems>>).
|
||
|
||
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]
|
||
.Using GDB
|
||
====
|
||
Type the characters in the first line verbatim. Those are
|
||
back-tics there.
|
||
|
||
`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.
|
||
|
||
If you do not have `gdb` available, you
|
||
will have to check out your operating system’s debugger.
|
||
====
|
||
|
||
You should mail the traceback to mailto:{wireshark-dev-list-email}[] or attach it
|
||
to your bug report.
|
||
|
||
==== Reporting Crashes on Windows platforms
|
||
|
||
You can download Windows debugging symbol files (.pdb) from the following locations:
|
||
|
||
* 32-bit Windows: https://www.wireshark.org/download/win32/all-versions/
|
||
|
||
* 64-bit Windows: https://www.wireshark.org/download/win64/all-versions/
|
||
|
||
Files are named "Wireshark-pdb-win__bits__-_x_._y_._z_.zip" to match their
|
||
corresponding "Wireshark-win__bits__-_x_._y_._z_.exe" installer packages.
|
||
|
||
// XXX Show how to use the Visual Studio debugger
|
||
|
||
// End of WSDG Chapter Introduction
|