docbook/eug_src/EUG_chapter_introduction.xml

   1 <!-- EUG Chapter Introduction -->
   2 <!-- $Id$ -->
   3
   4 <chapter id="ChapterIntroduction">
   5   <title>Introduction</title>
   6   <!-- Introduction -->
   7   <section id="ChIntroWhatIs">
   8     <title>What is <application>Ethereal?</application></title>
   9     <para>
  10         Ethereal is a network packet analyzer. A network packet
  11         analyzer will try to capture network packets and tries to display
  12         that packet data as detailed as possible.
  13     </para>
  14     <para>
  15         You could think of a network packet analyzer as a measuring device used to
  16         examine what's going on inside a network cable, just like a voltmeter is
  17         used by an electrician to examine what's going on inside an electric cable
  18         (but at a higher level, of course).
  19     </para>
  20     <para>
  21         In the past, such tools were either very expensive, proprietary, or both.
  22         However, with the advent of Ethereal, all that has changed.
  23     </para>
  24     <para>
  25         <application>Ethereal</application> is perhaps one of the best open
  26         source packet analyzers available today.
  27         </para>
  28
  29   <section id="ChIntroPurposes"><title>Some intended purposes</title>
  30         <para>
  31         Here are some examples people use Ethereal for:
  32       <itemizedlist>
  33         <listitem><para>
  34           network administrators use it to <command>troubleshoot network
  35            problems</command>
  36         </para></listitem>
  37         <listitem><para>
  38           network security engineers use it to <command>examine security
  39           problems</command>
  40         </para></listitem>
  41         <listitem><para>
  42           developers use it to <command>debug protocol implementations</command>
  43         </para></listitem>
  44         <listitem><para>
  45           people use it to <command>learn network protocol</command>
  46           internals
  47         </para></listitem>
  48       </itemizedlist>
  49           Beside these examples, Ethereal can be helpful in many other situations
  50           too.
  51         </para>
  52   </section>
  53
  54   <section id="ChIntroFeatures"><title>Features</title>
  55         <para>
  56         The following are some of the many features Ethereal provides:
  57       <itemizedlist>
  58         <listitem>
  59           <para>Available for <command>UNIX</command> and <command>Windows</command>.</para>
  60         </listitem>
  61         <listitem>
  62           <para>
  63             <command>Capture</command> live packet data from a network interface.
  64           </para>
  65         </listitem>
  66         <listitem>
  67           <para>
  68             Display packets with <command>very detailed protocol information</command>.
  69           </para>
  70         </listitem>
  71         <listitem>
  72           <para>
  73             <command>Open and Save</command> packet data captured.
  74           </para>
  75         </listitem>
  76         <listitem>
  77           <para>
  78             <command>Import and Export</command> packet data from and to a lot of
  79                 other capture programs.
  80           </para>
  81         </listitem>
  82         <listitem>
  83           <para><command>Filter packets</command> on many criteria.</para>
  84         </listitem>
  85         <listitem>
  86           <para><command>Search</command> for packets on many criteria.</para>
  87         </listitem>
  88         <listitem>
  89           <para><command>Colorize</command> packet display based on filters.</para>
  90         </listitem>
  91         <listitem>
  92           <para>Create various <command>statistics</command>.</para>
  93         </listitem>
  94         <listitem>
  95           <para>... and <command>a lot more!</command></para>
  96         </listitem>
  97       </itemizedlist>
  98       However, to really appreciate its power, you have to start using it.
  99     </para>
 100     <para>
 101       <xref linkend="ChIntroFig1"/> shows <application>Ethereal</application>
 102         having captured some packets and waiting for you to examine
 103         them.
 104         <figure id="ChIntroFig1">
 105           <title>
 106             <application>Ethereal</application> captures packets and allows
 107             you to examine their content.
 108           </title>
 109           <graphic entityref="EtherealMain1" format="PNG"/>
 110         </figure>
 111     </para>
 112         </section>
 113
 114         <section>
 115         <title>Live capture from many different network media</title>
 116         <para>
 117           Despite its name, Ethereal can capture traffic from
 118           network media other than Ethernet. Which media types are
 119           supported, depends on many things like the operating system you are
 120           using. An overview of the supported media types can be found at:
 121           <ulink url="&EtherealMediaPage;"/>.
 122         </para>
 123         </section>
 124
 125     <section><title>Import files from many other capture programs</title>
 126         <para>
 127             Ethereal can open packets captured from a large number of
 128                 other capture programs. For a list of input formats see
 129                 <xref linkend="ChIOInputFormatsSection"/>.
 130         </para>
 131     </section>
 132     <section><title>Export files for many other capture programs</title>
 133         <para>
 134             Ethereal can save packets captured in a large number of formats of
 135                 other capture programs. For a list of output formats see
 136                 <xref linkend="ChIOOutputFormatsSection"/>.
 137         </para>
 138     </section>
 139
 140         <section>
 141         <title>Many protocol decoders</title>
 142         <para>
 143       There are protocol decoders (or dissectors, as they are
 144       known in Ethereal) for a great many protocols:
 145           see <xref linkend="AppProtocols"/>.
 146         </para>
 147         </section>
 148
 149         <section><title>Open Source Software</title>
 150     <para>
 151       Ethereal is an open source software project, and is released under
 152       the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
 153           You can freely use Ethereal on any number of computers you like, without
 154           worrying about license keys or fees or such. In addition, all source
 155           code is freely available under the GPL. Because of that, it is very easy
 156           for people to add new protocols to Ethereal, either as plugins, or built
 157           into the source, and they often do!
 158     </para>
 159         </section>
 160
 161     <section id="ChIntroNoFeatures"><title>What Ethereal is not</title>
 162         <para>
 163         Here are some things Ethereal does not provide:
 164       <itemizedlist>
 165         <listitem><para>
 166           Ethereal isn't an intrusion detection system.  It will not warn you when
 167           someone does strange things on your network that he/she isn't allowed to
 168           do. However, if strange things happen, Ethereal might help you figure
 169           out what is really going on.
 170         </para></listitem>
 171         <listitem><para>
 172           Ethereal will not manipulate things on the network, it will only
 173           "measure" things from it. Ethereal doesn't send packets on the network
 174           or do other active things (except for name resolutions, but even
 175           that can be disabled).
 176         </para></listitem>
 177       </itemizedlist>
 178         </para>
 179     </section>
 180   </section>
 181
 182   <section id="ChIntroPlatforms">
 183     <title>Platforms Ethereal runs on</title>
 184     <para>
 185       Ethereal currently runs on most UNIX platforms and various Windows
 186       platforms. It requires GTK+, GLib, libpcap and some other libraries in
 187           order to run.
 188     </para>
 189     <para>
 190       If a binary package is not available for your platform, you should
 191       download the source and try to build it. Please report your experiences
 192           to <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
 193     </para>
 194     <para>
 195       Binary packages are available for at least the following platforms:
 196     </para>
 197
 198         <section><title>Unix</title>
 199         <para>
 200         <itemizedlist>
 201         <listitem><para>Apple Mac OS X</para></listitem>
 202         <listitem><para>BeOS</para></listitem>
 203         <listitem><para>FreeBSD</para></listitem>
 204         <listitem><para>HP-UX</para></listitem>
 205         <listitem><para>IBM AIX</para></listitem>
 206         <listitem><para>NetBSD</para></listitem>
 207         <listitem><para>OpenBSD</para></listitem>
 208         <listitem><para>SCO UnixWare/OpenUnix</para></listitem>
 209         <listitem><para>SGI Irix</para></listitem>
 210         <listitem><para>Sun Solaris/Intel</para></listitem>
 211         <listitem><para>Sun Solaris/Sparc</para></listitem>
 212         <listitem><para>Tru64 UNIX (formerly Digital UNIX)</para></listitem>
 213         </itemizedlist>
 214         </para>
 215         </section>
 216
 217         <section><title>Linux</title>
 218         <para>
 219         <itemizedlist>
 220         <listitem><para>Debian GNU/Linux</para></listitem>
 221         <listitem><para>Gentoo Linux</para></listitem>
 222         <listitem><para>IBM S/390 Linux (Red Hat)</para></listitem>
 223         <listitem><para>Mandrake Linux</para></listitem>
 224         <listitem><para>PLD Linux</para></listitem>
 225         <listitem><para>Red Hat Linux</para></listitem>
 226         <listitem><para>Rock Linux</para></listitem>
 227         <listitem><para>Slackware Linux</para></listitem>
 228         <listitem><para>Suse Linux</para></listitem>
 229         </itemizedlist>
 230         </para>
 231         </section>
 232
 233         <section><title>Microsoft Windows</title>
 234     <para>
 235         <itemizedlist>
 236         <listitem><para>Windows Me / 98 / 95</para></listitem>
 237         <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem>
 238         </itemizedlist>
 239     </para>
 240         </section>
 241
 242   </section>
 243
 244   <section id="ChIntroDownload">
 245     <title>Where to get Ethereal?</title>
 246     <para>
 247       You can get the latest copy of the program from the Ethereal website:
 248       <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.  The
 249       website allows you to choose from among several mirrors for
 250       downloading.
 251     </para>
 252     <para>
 253         A new Ethereal version will typically become available every 4-8 weeks.
 254     </para>
 255     <para>
 256         If you want to be notified about new Ethereal releases, you should
 257         subscribe to the ethereal-announce mailing list. You will find more
 258         details in <xref linkend="ChIntroMailingLists"/>.
 259     </para>
 260   </section>
 261
 262   <section id="ChIntroPronounce">
 263     <title>A rose by any other name</title>
 264     <para>
 265       William Shakespeare wrote:
 266       <emphasis>
 267         &quot;A rose by any other name would smell as sweet.&quot;
 268       </emphasis>
 269       And so it is with Ethereal, as there appears to be two different
 270       ways that people pronounce the name.
 271     </para>
 272     <para>
 273       Some people pronounce it ether-real, while others pronounce it
 274       e-the-real, as in ghostly, insubstantial, etc.
 275     </para>
 276     <para>
 277       You are welcome to call it what you like, as long as you find it
 278       useful. The FAQ gives the official pronunciation as "e-the-real".
 279     </para>
 280   </section>
 281
 282   <section id="ChIntroHistory">
 283     <title>A brief history of Ethereal</title>
 284     <para>
 285       In late 1997, Gerald Combs needed a tool for tracking down
 286       networking problems and wanted to learn more about networking, so
 287       he started writing Ethereal as a way to solve both problems.
 288     </para>
 289     <para>
 290       Ethereal was initially released, after several pauses in development,
 291       in July 1998 as version 0.2.0.  Within days, patches, bug reports,
 292       and words of encouragement started arriving, so Ethereal was on its
 293       way to success.
 294     </para>
 295     <para>
 296       Not long after that Gilbert Ramirez saw its potential and contributed
 297       a low-level dissector to it.
 298     </para>
 299     <para>
 300       In October, 1998, Guy Harris of Network Appliance was looking for
 301           something better than tcpview, so he started applying patches and
 302           contributing dissectors to Ethereal.
 303     </para>
 304     <para>
 305       In late 1998, Richard Sharpe, who was giving TCP/IP courses, saw its
 306       potential on such courses, and started looking at it to see if it
 307       supported the protocols he needed. While it didn't at that point,
 308       new protocols could be easily added.  So he started contributing
 309       dissectors and contributing patches.
 310     </para>
 311     <para>
 312       The list of people who have contributed to Ethereal has become very long
 313           since then, and almost all of them started with a protocol that they
 314           needed that Ethereal did not already handle. So they copied an existing
 315           dissector and contributed the code back to the team.
 316     </para>
 317   </section>
 318
 319   <section id="ChIntroMaintenance">
 320     <title>
 321       Development and maintenance of <application>Ethereal</application>
 322     </title>
 323     <para>
 324       Ethereal was initially developed by Gerald Combs. Ongoing development
 325       and maintenance of Ethereal is handled by the Ethereal team, a loose
 326       group of individuals who fix bugs and provide new functionality.
 327     </para>
 328     <para>
 329       There have also been a large number of people who have contributed
 330       protocol dissectors to Ethereal, and it is expected that this will
 331       continue.  You can find a list of the people who have contributed
 332       code to Ethereal by checking the about dialog box of Ethereal, or at
 333           the <ulink url="&EtherealAuthorsPage;">authors</ulink> page on the
 334       Ethereal web site.
 335     </para>
 336     <para>
 337       Ethereal is an open source software project, and is released under
 338       the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
 339           All source code is freely available under the GPL.  You are welcome to
 340       modify Ethereal to suit your own needs, and it would be appreciated
 341       if you contribute your improvements back to the Ethereal team.
 342     </para>
 343     <para>
 344       You gain three benefits by contributing your improvements back to the
 345       community:
 346       <itemizedlist>
 347         <listitem>
 348           <para>
 349             Other people who find your contributions useful will appreciate
 350             them, and you will know that you have helped people in the
 351             same way that the developers of Ethereal have helped people.
 352           </para>
 353         </listitem>
 354         <listitem>
 355           <para>
 356             The developers of Ethereal might improve your changes even more,
 357                 as there's always room for improvements. Or they may implement some
 358                 advanced things on top of your code, which can be useful for yourself
 359                 too.
 360           </para>
 361         </listitem>
 362         <listitem>
 363           <para>
 364             The maintainers and developers of Ethereal will maintain your
 365             code as well, fixing it when API changes or other changes are
 366             made, and generally keeping it in tune with what is happening
 367             with Ethereal. So if Ethereal is updated (which is done often),
 368                 you can get a new Ethereal version from the website and your changes
 369                 will already be included without any effort for you.
 370           </para>
 371         </listitem>
 372       </itemizedlist>
 373     </para>
 374     <para>
 375       The Ethereal source code and binary kits for some platforms are all
 376       available on the download page of the Ethereal website:
 377       <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.
 378     </para>
 379   </section>
 380
 381   <section id="ChIntroHelp">
 382     <title>Reporting problems and getting help</title>
 383         <para>
 384       If you have problems, or need help with Ethereal, there are several
 385       places that may be of interest to you (well, beside this guide of
 386           course).
 387         </para>
 388
 389         <section id="ChIntroHomepage"><title>Website</title>
 390     <para>
 391         You will find lot's of useful information on the Ethereal homepage at
 392         <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
 393         </para>
 394         </section>
 395
 396         <section id="ChIntroWiki"><title>Wiki</title>
 397     <para>
 398         The Ethereal Wiki at <ulink
 399         url="&EtherealWikiPage;">&EtherealWikiPage;</ulink> provides a wide range
 400         of information related to Ethereal and packet capturing in general.
 401         You will find a lot of information not part of this user's guide. For
 402         example, there is an explanation how to capture on a switched network,
 403         an ongoing effort to build a protocol reference and a lot more.
 404         </para>
 405         <para>
 406         And best of all, if you would like to contribute your knowledge on a
 407         specific topic (maybe a network protocol you know well), you can edit the
 408         wiki pages by simply using your webbrowser.
 409         </para>
 410         </section>
 411
 412         <section id="ChIntroFAQ"><title>FAQ</title>
 413     <para>
 414         The "Frequently Asked Questions" will list often asked questions and
 415         the corresponding answers.
 416         <note><title>Read the FAQ!</title>
 417         <para>
 418         Before sending any mail to the mailing lists below, be sure to read the
 419         FAQ, as it will often answer the question(s) you might have. This will save
 420         yourself and others a lot of time (keep in mind that a lot of people are
 421         subscribed to the mailing lists).
 422     </para>
 423     </note>
 424         You will find the FAQ inside Ethereal by clicking the menu item
 425         Help/Contents and selecting the FAQ page in the upcoming dialog.
 426     </para>
 427     <para>
 428         An online version is available at the ethereal website:
 429         <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
 430         prefer this online version, as it's typically more up to date and the HTML
 431         format is easier to use.
 432     </para>
 433         </section>
 434
 435         <section id="ChIntroMailingLists"><title>Mailing Lists</title>
 436     <para>
 437       There are several mailing lists of specific Ethereal topics available:
 438       <variablelist>
 439         <varlistentry><term><command>ethereal-announce</command></term>
 440           <listitem>
 441             <para>
 442               This mailing list will inform you about new program
 443                   releases, which usually appear about every 4-8 weeks.
 444             </para>
 445           </listitem>
 446         </varlistentry>
 447         <varlistentry><term><command>ethereal-users</command></term>
 448           <listitem>
 449             <para>
 450               This list is for users of Ethereal.  People post
 451               questions about building and using Ethereal, others (hopefully)
 452                   provide answers.
 453             </para>
 454           </listitem>
 455         </varlistentry>
 456         <varlistentry><term><command>ethereal-dev</command></term>
 457           <listitem>
 458             <para>
 459               This list is for Ethereal developers. If you want to start
 460               developing a protocol dissector, join this list.
 461             </para>
 462           </listitem>
 463         </varlistentry>
 464       </variablelist>
 465       You can subscribe to each of these lists from the Ethereal web site:
 466       <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.  Simply
 467       select the <command>mailing lists</command> link on the left hand
 468       side of the site. The lists are archived at the Ethereal web site
 469       as well.
 470         <tip><title>Tip!</title>
 471         <para>
 472         You can search in the list archives to see if someone asked the same
 473         question some time before and maybe already got an answer. That way you
 474         don't have to wait until someone answers your question.
 475         </para>
 476         </tip>
 477     </para>
 478         </section>
 479
 480         <section><title>Reporting Problems</title>
 481         <note><title>Note!</title>
 482         <para>
 483         Before reporting any problems, please make sure you have installed the
 484         latest version of Ethereal.
 485         </para>
 486         </note>
 487     <para>
 488       When reporting problems with Ethereal, it is helpful if you supply the
 489       following information:
 490       <orderedlist>
 491         <listitem>
 492           <para>
 493             The version number of Ethereal and the dependent libraries linked with
 494                 it, eg GTK+, etc. You can obtain this with the command
 495             <command>ethereal -v</command>.
 496           </para>
 497         </listitem>
 498         <listitem>
 499           <para>
 500             Information about the platform you run Ethereal on.
 501           </para>
 502         </listitem>
 503         <listitem>
 504           <para>
 505             A detailed description of your problem.
 506           </para>
 507         </listitem>
 508         <listitem>
 509           <para>
 510                 If you get an error/warning message, copy the text of that message
 511                 (and also a few lines before and after it, if there are some), so
 512                 others may find the place where things go wrong. Please don't
 513                 give something like: "I get a warning while doing x" as this won't
 514                 give a good idea where to look at.
 515           </para>
 516         </listitem>
 517       </orderedlist>
 518     </para>
 519         <note><title>Don't send large files!</title>
 520         <para>
 521         Do not send large files (>100KB) to the mailing lists, just place a note
 522         that further data is available on request. Large files will only annoy a
 523         lot of people on the list who are not interested in your specific problem.
 524         If required, you will be asked for further data by the persons who really
 525         can help you.
 526         </para>
 527         </note>
 528         <warning><title>Don't send confidential information!</title>
 529         <para>
 530         If you send captured data to the mailing lists, be sure they don't contain
 531         any sensitive or confidential information like passwords or such.
 532         </para>
 533         </warning>
 534   </section>
 535
 536         <section><title>Reporting Crashes on UNIX/Linux platforms</title>
 537     <para>
 538       When reporting crashes with Ethereal, it is helpful if you supply the
 539       traceback information (besides the information mentioned in "Reporting
 540           Problems").
 541     </para>
 542           <para>
 543             You can obtain this traceback information with the following commands:
 544             <programlisting>
 545 <![CDATA[
 546 $ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
 547 backtrace
 548 ^D
 549 $
 550 ]]>
 551                 </programlisting>
 552             <note>
 553               <para>
 554                 Type the characters in the first line verbatim! Those are
 555                 back-tics there!
 556               </para>
 557             </note>
 558             <note>
 559               <para>
 560                 backtrace is a <command>gdb</command> command. You should
 561                 enter it verbatim after the first line shown above, but it will not be
 562                 echoed. The ^D
 563                 (Control-D, that is, press the Control key and the D key
 564                 together) will cause <command>gdb</command> to exit. This will
 565                 leave you with a file called
 566                 <filename>bt.txt</filename> in the current directory.
 567                 Include the file with your bug report.
 568               </para>
 569             </note>
 570             <note>
 571               <para>
 572                 If you do not have <command>gdb</command> available, you
 573                 will have to check out your operating system's debugger.
 574               </para>
 575             </note>
 576           </para>
 577           <para>
 578             You should mail the traceback to the
 579                 <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
 580             mailing list.
 581           </para>
 582   </section>
 583
 584         <section><title>Reporting Crashes on Windows platforms</title>
 585     <para>
 586         The Windows distributions don't contain the symbol files (.pdb), because
 587         they are very large. For this reason it's not possible to create
 588         a meaningful backtrace file from it. You should report your crash just
 589         like other problems, using the mechanism described above.
 590     </para>
 591   </section>
 592   </section>
 593
 594 </chapter>
 595 <!-- End of EUG Chapter 1 -->