forked from osmocom/wireshark
591 lines
21 KiB
XML
591 lines
21 KiB
XML
<!-- EDG Chapter Introduction -->
|
|
<!-- $Id$ -->
|
|
|
|
<chapter id="ChapterIntroduction">
|
|
<title>Introduction</title>
|
|
|
|
<section id="ChIntroIntro">
|
|
<title>Introduction</title>
|
|
<para>
|
|
This chapter will provide you with information about Ethereal
|
|
development in general.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroWhatIs">
|
|
<title>What is <application>Ethereal?</application></title>
|
|
<para>
|
|
Well, if you want to start Ethereal development, you might already
|
|
know what Ethereal is doing. If not, please have a look at the
|
|
<ulink url="&EtherealUsersGuidePage;">Ethereal User's Guide</ulink>,
|
|
which will provide a lot of general information about it.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="ChIntroPlatforms">
|
|
<title>Platforms Ethereal runs on</title>
|
|
<para>
|
|
Ethereal currently runs on most UNIX platforms and various Windows
|
|
platforms. It requires GTK+, GLib, libpcap and some other libraries in
|
|
order to run.
|
|
</para>
|
|
<para>
|
|
As Ethereal is developed in a platform independant way and uses libraries
|
|
which are available for a lot of different platforms (such as the GTK+
|
|
GUI library), it's available on a such a wide variety of platforms.
|
|
</para>
|
|
<para>
|
|
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 <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
|
|
</para>
|
|
<para>
|
|
Binary packages are available for at least the following platforms:
|
|
</para>
|
|
|
|
<section><title>Unix</title>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem><para>Apple Mac OS X</para></listitem>
|
|
<listitem><para>BeOS</para></listitem>
|
|
<listitem><para>FreeBSD</para></listitem>
|
|
<listitem><para>HP-UX</para></listitem>
|
|
<listitem><para>IBM AIX</para></listitem>
|
|
<listitem><para>NetBSD</para></listitem>
|
|
<listitem><para>OpenBSD</para></listitem>
|
|
<listitem><para>SCO UnixWare/OpenUnix</para></listitem>
|
|
<listitem><para>SGI Irix</para></listitem>
|
|
<listitem><para>Sun Solaris/Intel</para></listitem>
|
|
<listitem><para>Sun Solaris/Sparc</para></listitem>
|
|
<listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section><title>Linux</title>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem><para>Debian GNU/Linux</para></listitem>
|
|
<listitem><para>Gentoo Linux</para></listitem>
|
|
<listitem><para>IBM S/390 Linux (Red Hat)</para></listitem>
|
|
<listitem><para>Mandrake Linux</para></listitem>
|
|
<listitem><para>PLD Linux</para></listitem>
|
|
<listitem><para>Red Hat Linux</para></listitem>
|
|
<listitem><para>Rock Linux</para></listitem>
|
|
<listitem><para>Slackware Linux</para></listitem>
|
|
<listitem><para>Suse Linux</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section><title>Microsoft Windows</title>
|
|
<para>
|
|
Thanks to the Win32 API, development on all Windows platforms will be
|
|
done in a very similar way. However some differences between the platforms
|
|
are existing (especially between the NT and 95 based platforms), the
|
|
differences will be notified where appropriate. All Windows platforms
|
|
referred to as Win32, Win or Windows may be used with the same meaning.
|
|
As Windows CE differs a lot compared to the other Windows platforms
|
|
mentioned, Ethereal will not run on Windows CE and there are no plans to
|
|
support it.
|
|
<itemizedlist>
|
|
<listitem><para>Windows Me / 98 / 95</para></listitem>
|
|
<listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="ChIntroDevelopment">
|
|
<title>
|
|
Development and maintenance of <application>Ethereal</application>
|
|
</title>
|
|
<para>
|
|
Ethereal was initially developed by Gerald Combs. Ongoing development
|
|
and maintenance of Ethereal is handled by the Ethereal team, a loose
|
|
group of individuals who fix bugs and provide new functionality.
|
|
</para>
|
|
<para>
|
|
There have also been a large number of people who have contributed
|
|
protocol dissectors to Ethereal, and it is expected that this will
|
|
continue. You can find a list of the people who have contributed
|
|
code to Ethereal by checking the about dialog box of Ethereal, or have
|
|
a look at the <ulink url="&EtherealAuthorsPage;"/> page on the Ethereal
|
|
web site.
|
|
</para>
|
|
<para>
|
|
The
|
|
communication between the developers is usually done trough the developer
|
|
mailing list, which can be joined by anyone interested in the development
|
|
process. At the time writing of this document, more than 500 persons are
|
|
subscribed to this mailing list!
|
|
</para>
|
|
<para>
|
|
It is strongly recommended to join the developer mailing list, if you
|
|
are going to do any Ethereal development. See
|
|
<xref linkend="ChIntroMailingLists"/> about the different Ethereal
|
|
mailing lists available.
|
|
</para>
|
|
|
|
<section><title>Programming language(s) used</title>
|
|
<para>
|
|
Almost any part of Ethereal is implemented in plain ANSI C.
|
|
</para>
|
|
<para>
|
|
The typical task for a new Ethereal 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 Ethereal development in almost any case.
|
|
</para>
|
|
<para>
|
|
So unless you are going to change the development process of Ethereal
|
|
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 Ethereal build
|
|
process).
|
|
</para>
|
|
<para>
|
|
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 and in the case Ethereal
|
|
should be installed from the released source packages. If Ethereal is
|
|
installed from a binary package, none of these helper tools are needed on
|
|
the target system.
|
|
</para>
|
|
</section>
|
|
|
|
|
|
<section><title>Open Source Software</title>
|
|
<para>
|
|
Ethereal is an open source software project, and is released under
|
|
the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
|
|
You can freely use Ethereal 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 Ethereal, either as plugins, or built
|
|
into the source, and they often do!
|
|
</para>
|
|
<para>
|
|
You are welcome to
|
|
modify Ethereal to suit your own needs, and it would be appreciated
|
|
if you contribute your improvements back to the Ethereal team.
|
|
</para>
|
|
<para>
|
|
You gain three benefits by contributing your improvements back to the
|
|
community:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
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 Ethereal have helped people.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The developers of Ethereal 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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The maintainers and developers of Ethereal 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 Ethereal. So if Ethereal is updated (which is done often),
|
|
you can get a new Ethereal version from the website and your changes
|
|
will already be included without any effort for you.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>
|
|
The Ethereal source code and binary kits for some platforms are all
|
|
available on the download page of the Ethereal website:
|
|
<ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="ChIntroReleases">
|
|
<title>Releases and distributions</title>
|
|
<para>
|
|
The officially released files can be found at: <ulink
|
|
url="&EtherealDownloadPage;"/>. A new Ethereal version is released, after
|
|
significant changes compared to the last release were completed or a
|
|
serious security issue was encountered. The typical release schedule is
|
|
about every 4-8 weeks (although this may vary).
|
|
</para>
|
|
<para>
|
|
There are two kinds of distributions: binary and source, both have their
|
|
advantages and disadvantages.
|
|
</para>
|
|
|
|
<section id="ChIntroReleaseBinary">
|
|
<title>Binary distributions</title>
|
|
<para>
|
|
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:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
Win32 (.exe file). The typical Windows end user is used to get a setup.exe
|
|
file, which will install all the required things for him.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Debian (.deb file). A user of a Debian Package Manager (DPKG) based system
|
|
is used to get a .deb file from which the package manager checks the
|
|
dependancies and installs the software.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
RedHat (.rpm file). A user of a RedHat Package Manager (RPM) based system
|
|
is used to get a .rpm file from which the package manager checks the
|
|
dependancies and installs the software.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Solaris. A Solaris user is used to get a file from which the package manager
|
|
(PKG) checks the dependancies and installs the software.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
However, if you want to start developing with Ethereal, the binary
|
|
distributions won't be much helpful, as you need the source files, of
|
|
course.
|
|
</para>
|
|
<para>
|
|
For details about how to build these binary distributions yourself,
|
|
e.g. if you need a distribution for a special audience, see
|
|
<xref linkend="ChSrcBinary"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroReleaseSource">
|
|
<title>Source code distributions</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<para>
|
|
You should use the released sources if you want to build Ethereal from
|
|
source on your platform for productive use. However, if you going to
|
|
develop changes to the Ethereal sources, it might be better to use the
|
|
latest SVN sources. For details about the different ways to get the
|
|
Ethereal source code see <xref linkend="ChSrcObtain"/>.
|
|
</para>
|
|
<para>
|
|
Before building Ethereal 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.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="ChIntroHelp">
|
|
<title>Reporting problems and getting help</title>
|
|
<para>
|
|
If you have problems, or need help with Ethereal, there are several
|
|
places that may be of interest to you (well, beside this guide of
|
|
course).
|
|
</para>
|
|
|
|
<section id="ChIntroHomepage"><title>Website</title>
|
|
<para>
|
|
You will find lot's of useful information on the Ethereal homepage at
|
|
<ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroWiki"><title>Wiki</title>
|
|
<para>
|
|
The Ethereal Wiki at <ulink
|
|
url="&EtherealWikiSite;">&EtherealWikiSite;</ulink> provides a wide range
|
|
of information related to Ethereal 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroFAQ"><title>FAQ</title>
|
|
<para>
|
|
The "Frequently Asked Questions" will list often asked questions and
|
|
the corresponding answers.
|
|
<note><title>Read the FAQ!</title>
|
|
<para>
|
|
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).
|
|
</para>
|
|
</note>
|
|
You will find the FAQ inside Ethereal by clicking the menu item
|
|
Help/Contents and selecting the FAQ page in the upcoming dialog.
|
|
</para>
|
|
<para>
|
|
An online version is available at the ethereal website:
|
|
<ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
|
|
prefer this online version, as it's typically more up to date and the HTML
|
|
format is easier to use.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroMailingLists"><title>Mailing Lists</title>
|
|
<para>
|
|
There are several mailing lists of specific Ethereal topics available:
|
|
<variablelist>
|
|
<varlistentry><term><command>ethereal-announce</command></term>
|
|
<listitem>
|
|
<para>
|
|
This mailing list will inform you about new program
|
|
releases, which usually appear about every 4-8 weeks.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>ethereal-users</command></term>
|
|
<listitem>
|
|
<para>
|
|
This list is for users of Ethereal. People post
|
|
questions about building and using Ethereal, others (hopefully)
|
|
provide answers.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>ethereal-dev</command></term>
|
|
<listitem>
|
|
<para>
|
|
This list is for Ethereal developers. People post questions about
|
|
the development of Ethereal, others (hopefully) provide answers.
|
|
If you want to start developing a protocol dissector, join this list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>ethereal-bugs</command></term>
|
|
<listitem>
|
|
<para>
|
|
This list is for Ethereal 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 <xref linkend="ChIntroBugDatabase"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>ethereal-cvs</command></term>
|
|
<listitem>
|
|
<para>
|
|
This list is for Ethereal 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 <xref linkend="ChSrcSVNServer"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
You can subscribe to each of these lists from the Ethereal web site:
|
|
<ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>. Simply
|
|
select the <command>mailing lists</command> link on the left hand
|
|
side of the site. The lists are archived at the Ethereal web site
|
|
as well.
|
|
<tip><title>Tip!</title>
|
|
<para>
|
|
You can search in the list archives to see if someone asked the same
|
|
question some time before and maybe already got an answer. That way you
|
|
don't have to wait until someone answers your question.
|
|
</para>
|
|
</tip>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroBugDatabase"><title>Bug database</title>
|
|
<para>
|
|
The Etereal community started collecting bug reports in a Bugzilla database at
|
|
<ulink url="&EtherealBugsSite;">&EtherealBugsSite;</ulink>.
|
|
This database is filled with manually filed bug reports, usually after some
|
|
discussion on ethereal-dev, and bug reports from the QA build tooling.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChIntroReportProblems"><title>Reporting Problems</title>
|
|
<note><title>Note!</title>
|
|
<para>
|
|
Before reporting any problems, please make sure you have installed the
|
|
latest version of Ethereal.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
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 uses a lot of different
|
|
platforms to compile/run Ethereal on.
|
|
</para>
|
|
<para>
|
|
When reporting problems with Ethereal, it is helpful if you supply the
|
|
following information:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
The version number of Ethereal and the dependent libraries linked with
|
|
it, eg GTK+, etc. You can obtain this with the command
|
|
<command>ethereal -v</command>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Information about the platform you run Ethereal on.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
A detailed description of your problem.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
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 comiling x"
|
|
as this won't give any direction to look at.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
<note><title>Don't send large files!</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
<note><title>Don't send confidential information!</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section><title>Reporting Crashes on UNIX/Linux platforms</title>
|
|
<para>
|
|
When reporting crashes with Ethereal, it is helpful if you supply the
|
|
traceback information (besides the information mentioned in
|
|
<xref linkend="ChIntroReportProblems"/>).
|
|
</para>
|
|
<para>
|
|
You can obtain this traceback information with the following commands:
|
|
<programlisting>
|
|
<![CDATA[
|
|
$ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
|
|
backtrace
|
|
^D
|
|
$
|
|
]]>
|
|
</programlisting>
|
|
<note>
|
|
<para>
|
|
Type the characters in the first line verbatim! Those are
|
|
back-tics there!
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
backtrace is a <command>gdb</command> 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 <command>gdb</command> to exit. This will
|
|
leave you with a file called
|
|
<filename>bt.txt</filename> in the current directory.
|
|
Include the file with your bug report.
|
|
</para>
|
|
</note>
|
|
<note>
|
|
<para>
|
|
If you do not have <command>gdb</command> available, you
|
|
will have to check out your operating system's debugger.
|
|
</para>
|
|
</note>
|
|
</para>
|
|
<para>
|
|
You should mail the traceback to the
|
|
<ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
|
|
mailing list, or append it to your bug report.
|
|
</para>
|
|
</section>
|
|
|
|
<section><title>Reporting Crashes on Windows platforms</title>
|
|
<para>
|
|
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
|
|
<xref linkend="ChIntroReportProblems"/>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="ChIntroOtherSources"><title>Other sources of developer information
|
|
</title>
|
|
<para>
|
|
If you don't find the information you need inside this book, there are
|
|
various other sources of information:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
have a look at the Ethereal source code
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
there are various documentation files on different topics inside the
|
|
source code, see all the README.xxx files
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
tool documentation of the various tools used
|
|
(e.g. manpages of sed, gcc, ...)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
the different mailing lists <xref linkend="ChIntroMailingLists"/>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
...
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
</chapter>
|
|
<!-- End of EUG Chapter 1 -->
|