1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
|
<!-- 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 will
be referred as Win32, Win or Windows might 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 an setup
.exe file, which will install all the required things for him.
</para>
</listitem>
<listitem>
<para>
Debian (.deb file)
</para>
</listitem>
<listitem>
<para>
RedHat (.rpm file)
</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="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-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="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, be sure they don't contain
any sensitive or confidential information like passwords or such.
</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.
</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 -->
|