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         Wireshark 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 Wireshark) 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       Wireshark 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 Wireshark 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         Maintained:
 236         <itemizedlist>
 237         <listitem><para>Windows Server 2003 / XP / 2000 / NT 4.0</para></listitem>
 238         <listitem><para>Windows Me / 98</para></listitem>
 239         </itemizedlist>
 240     </para>
 241     <para>
 242         Unsupported/Unmaintained (because lack of required libraries):
 243         <itemizedlist>
 244         <listitem><para>Windows CE</para></listitem>
 245         <listitem><para>Windows NT / XP Embedded</para></listitem>
 246         <listitem><para>Windows 95 is no longer actively maintained by WinPcap,
 247         but still may work perfectly</para></listitem>
 248         </itemizedlist>
 249     </para>
 250     <para>
 251         No experiences (fresh versions):
 252         <itemizedlist>
 253         <listitem><para>Windows XP 64-bit Edition</para></listitem>
 254         <listitem><para>Windows Vista (aka Longhorn)</para></listitem>
 255         </itemizedlist>
 256         Please provide your experiences about these fresh versions to:
 257         <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>.
 258     </para>
 259         </section>
 260
 261   </section>
 262
 263   <section id="ChIntroDownload">
 264     <title>Where to get Ethereal?</title>
 265     <para>
 266       You can get the latest copy of the program from the Ethereal website:
 267       <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.  The
 268       website allows you to choose from among several mirrors for
 269       downloading.
 270     </para>
 271     <para>
 272         A new Ethereal version will typically become available every 4-8 weeks.
 273     </para>
 274     <para>
 275         If you want to be notified about new Ethereal releases, you should
 276         subscribe to the ethereal-announce mailing list. You will find more
 277         details in <xref linkend="ChIntroMailingLists"/>.
 278     </para>
 279   </section>
 280
 281   <section id="ChIntroPronounce">
 282     <title>A rose by any other name</title>
 283     <para>
 284       William Shakespeare wrote:
 285       <emphasis>
 286         &quot;A rose by any other name would smell as sweet.&quot;
 287       </emphasis>
 288       And so it is with Ethereal, as there appears to be two different
 289       ways that people pronounce the name.
 290     </para>
 291     <para>
 292       Some people pronounce it ether-real, while others pronounce it
 293       e-the-real, as in ghostly, insubstantial, etc.
 294     </para>
 295     <para>
 296       You are welcome to call it what you like, as long as you find it
 297       useful. The FAQ gives the official pronunciation as "e-the-real".
 298     </para>
 299   </section>
 300
 301   <section id="ChIntroHistory">
 302     <title>A brief history of Ethereal</title>
 303     <para>
 304       In late 1997, Gerald Combs needed a tool for tracking down
 305       networking problems and wanted to learn more about networking, so
 306       he started writing Ethereal as a way to solve both problems.
 307     </para>
 308     <para>
 309       Ethereal was initially released, after several pauses in development,
 310       in July 1998 as version 0.2.0.  Within days, patches, bug reports,
 311       and words of encouragement started arriving, so Ethereal was on its
 312       way to success.
 313     </para>
 314     <para>
 315       Not long after that Gilbert Ramirez saw its potential and contributed
 316       a low-level dissector to it.
 317     </para>
 318     <para>
 319       In October, 1998, Guy Harris of Network Appliance was looking for
 320           something better than tcpview, so he started applying patches and
 321           contributing dissectors to Ethereal.
 322     </para>
 323     <para>
 324       In late 1998, Richard Sharpe, who was giving TCP/IP courses, saw its
 325       potential on such courses, and started looking at it to see if it
 326       supported the protocols he needed. While it didn't at that point,
 327       new protocols could be easily added.  So he started contributing
 328       dissectors and contributing patches.
 329     </para>
 330     <para>
 331       The list of people who have contributed to Ethereal has become very long
 332           since then, and almost all of them started with a protocol that they
 333           needed that Ethereal did not already handle. So they copied an existing
 334           dissector and contributed the code back to the team.
 335     </para>
 336   </section>
 337
 338   <section id="ChIntroMaintenance">
 339     <title>
 340       Development and maintenance of <application>Ethereal</application>
 341     </title>
 342     <para>
 343       Ethereal was initially developed by Gerald Combs. Ongoing development
 344       and maintenance of Wireshark is handled by the Ethereal team, a loose
 345       group of individuals who fix bugs and provide new functionality.
 346     </para>
 347     <para>
 348       There have also been a large number of people who have contributed
 349       protocol dissectors to Ethereal, and it is expected that this will
 350       continue.  You can find a list of the people who have contributed
 351       code to Ethereal by checking the about dialog box of Ethereal, or at
 352           the <ulink url="&EtherealAuthorsPage;">authors</ulink> page on the
 353       Ethereal web site.
 354     </para>
 355     <para>
 356       Wireshark is an open source software project, and is released under
 357       the <ulink url="&GPLWebsite;">GNU General Public Licence</ulink> (GPL).
 358           All source code is freely available under the GPL.  You are welcome to
 359       modify Ethereal to suit your own needs, and it would be appreciated
 360       if you contribute your improvements back to the Ethereal team.
 361     </para>
 362     <para>
 363       You gain three benefits by contributing your improvements back to the
 364       community:
 365       <itemizedlist>
 366         <listitem>
 367           <para>
 368             Other people who find your contributions useful will appreciate
 369             them, and you will know that you have helped people in the
 370             same way that the developers of Ethereal have helped people.
 371           </para>
 372         </listitem>
 373         <listitem>
 374           <para>
 375             The developers of Ethereal might improve your changes even more,
 376                 as there's always room for improvements. Or they may implement some
 377                 advanced things on top of your code, which can be useful for yourself
 378                 too.
 379           </para>
 380         </listitem>
 381         <listitem>
 382           <para>
 383             The maintainers and developers of Ethereal will maintain your
 384             code as well, fixing it when API changes or other changes are
 385             made, and generally keeping it in tune with what is happening
 386             with Ethereal. So if Wireshark is updated (which is done often),
 387                 you can get a new Ethereal version from the website and your changes
 388                 will already be included without any effort for you.
 389           </para>
 390         </listitem>
 391       </itemizedlist>
 392     </para>
 393     <para>
 394       The Wireshark source code and binary kits for some platforms are all
 395       available on the download page of the Ethereal website:
 396       <ulink url="&EtherealDownloadPage;">&EtherealDownloadPage;</ulink>.
 397     </para>
 398   </section>
 399
 400   <section id="ChIntroHelp">
 401     <title>Reporting problems and getting help</title>
 402         <para>
 403       If you have problems, or need help with Ethereal, there are several
 404       places that may be of interest to you (well, beside this guide of
 405           course).
 406         </para>
 407
 408         <section id="ChIntroHomepage"><title>Website</title>
 409     <para>
 410         You will find lot's of useful information on the Ethereal homepage at
 411         <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.
 412         </para>
 413         </section>
 414
 415         <section id="ChIntroWiki"><title>Wiki</title>
 416     <para>
 417         The Wireshark Wiki at <ulink
 418         url="&EtherealWikiPage;">&EtherealWikiPage;</ulink> provides a wide range
 419         of information related to Ethereal and packet capturing in general.
 420         You will find a lot of information not part of this user's guide. For
 421         example, there is an explanation how to capture on a switched network,
 422         an ongoing effort to build a protocol reference and a lot more.
 423         </para>
 424         <para>
 425         And best of all, if you would like to contribute your knowledge on a
 426         specific topic (maybe a network protocol you know well), you can edit the
 427         wiki pages by simply using your webbrowser.
 428         </para>
 429         </section>
 430
 431         <section id="ChIntroFAQ"><title>FAQ</title>
 432     <para>
 433         The "Frequently Asked Questions" will list often asked questions and
 434         the corresponding answers.
 435         <note><title>Read the FAQ!</title>
 436         <para>
 437         Before sending any mail to the mailing lists below, be sure to read the
 438         FAQ, as it will often answer the question(s) you might have. This will save
 439         yourself and others a lot of time (keep in mind that a lot of people are
 440         subscribed to the mailing lists).
 441     </para>
 442     </note>
 443         You will find the FAQ inside Ethereal by clicking the menu item
 444         Help/Contents and selecting the FAQ page in the upcoming dialog.
 445     </para>
 446     <para>
 447         An online version is available at the ethereal website:
 448         <ulink url="&EtherealFAQPage;">&EtherealFAQPage;</ulink>. You might
 449         prefer this online version, as it's typically more up to date and the HTML
 450         format is easier to use.
 451     </para>
 452         </section>
 453
 454         <section id="ChIntroMailingLists"><title>Mailing Lists</title>
 455     <para>
 456       There are several mailing lists of specific Ethereal topics available:
 457       <variablelist>
 458         <varlistentry><term><command>ethereal-announce</command></term>
 459           <listitem>
 460             <para>
 461               This mailing list will inform you about new program
 462                   releases, which usually appear about every 4-8 weeks.
 463             </para>
 464           </listitem>
 465         </varlistentry>
 466         <varlistentry><term><command>ethereal-users</command></term>
 467           <listitem>
 468             <para>
 469               This list is for users of Ethereal.  People post
 470               questions about building and using Ethereal, others (hopefully)
 471                   provide answers.
 472             </para>
 473           </listitem>
 474         </varlistentry>
 475         <varlistentry><term><command>ethereal-dev</command></term>
 476           <listitem>
 477             <para>
 478               This list is for Wireshark developers. If you want to start
 479               developing a protocol dissector, join this list.
 480             </para>
 481           </listitem>
 482         </varlistentry>
 483       </variablelist>
 484       You can subscribe to each of these lists from the Ethereal web site:
 485       <ulink url="&EtherealWebSite;">&EtherealWebSite;</ulink>.  Simply
 486       select the <command>mailing lists</command> link on the left hand
 487       side of the site. The lists are archived at the Ethereal web site
 488       as well.
 489         <tip><title>Tip!</title>
 490         <para>
 491         You can search in the list archives to see if someone asked the same
 492         question some time before and maybe already got an answer. That way you
 493         don't have to wait until someone answers your question.
 494         </para>
 495         </tip>
 496     </para>
 497         </section>
 498
 499         <section><title>Reporting Problems</title>
 500         <note><title>Note!</title>
 501         <para>
 502         Before reporting any problems, please make sure you have installed the
 503         latest version of Ethereal.
 504         </para>
 505         </note>
 506     <para>
 507       When reporting problems with Ethereal, it is helpful if you supply the
 508       following information:
 509       <orderedlist>
 510         <listitem>
 511           <para>
 512             The version number of Ethereal and the dependent libraries linked with
 513                 it, eg GTK+, etc. You can obtain this with the command
 514             <command>ethereal -v</command>.
 515           </para>
 516         </listitem>
 517         <listitem>
 518           <para>
 519             Information about the platform you run Ethereal on.
 520           </para>
 521         </listitem>
 522         <listitem>
 523           <para>
 524             A detailed description of your problem.
 525           </para>
 526         </listitem>
 527         <listitem>
 528           <para>
 529                 If you get an error/warning message, copy the text of that message
 530                 (and also a few lines before and after it, if there are some), so
 531                 others may find the place where things go wrong. Please don't
 532                 give something like: "I get a warning while doing x" as this won't
 533                 give a good idea where to look at.
 534           </para>
 535         </listitem>
 536       </orderedlist>
 537     </para>
 538         <note><title>Don't send large files!</title>
 539         <para>
 540         Do not send large files (>100KB) to the mailing lists, just place a note
 541         that further data is available on request. Large files will only annoy a
 542         lot of people on the list who are not interested in your specific problem.
 543         If required, you will be asked for further data by the persons who really
 544         can help you.
 545         </para>
 546         </note>
 547         <warning><title>Don't send confidential information!</title>
 548         <para>
 549         If you send captured data to the mailing lists, be sure they don't contain
 550         any sensitive or confidential information like passwords or such.
 551         </para>
 552         </warning>
 553   </section>
 554
 555         <section><title>Reporting Crashes on UNIX/Linux platforms</title>
 556     <para>
 557       When reporting crashes with Ethereal, it is helpful if you supply the
 558       traceback information (besides the information mentioned in "Reporting
 559           Problems").
 560     </para>
 561           <para>
 562             You can obtain this traceback information with the following commands:
 563             <programlisting>
 564 <![CDATA[
 565 $ gdb `whereis ethereal | cut -f2 -d: | cut -d' ' -f2` core >& bt.txt
 566 backtrace
 567 ^D
 568 $
 569 ]]>
 570                 </programlisting>
 571             <note>
 572               <para>
 573                 Type the characters in the first line verbatim! Those are
 574                 back-tics there!
 575               </para>
 576             </note>
 577             <note>
 578               <para>
 579                 backtrace is a <command>gdb</command> command. You should
 580                 enter it verbatim after the first line shown above, but it will not be
 581                 echoed. The ^D
 582                 (Control-D, that is, press the Control key and the D key
 583                 together) will cause <command>gdb</command> to exit. This will
 584                 leave you with a file called
 585                 <filename>bt.txt</filename> in the current directory.
 586                 Include the file with your bug report.
 587               </para>
 588             </note>
 589             <note>
 590               <para>
 591                 If you do not have <command>gdb</command> available, you
 592                 will have to check out your operating system's debugger.
 593               </para>
 594             </note>
 595           </para>
 596           <para>
 597             You should mail the traceback to the
 598                 <ulink url="mailto:&EtherealDevMailList;">&EtherealDevMailList;</ulink>
 599             mailing list.
 600           </para>
 601   </section>
 602
 603         <section><title>Reporting Crashes on Windows platforms</title>
 604     <para>
 605         The Windows distributions don't contain the symbol files (.pdb), because
 606         they are very large. For this reason it's not possible to create
 607         a meaningful backtrace file from it. You should report your crash just
 608         like other problems, using the mechanism described above.
 609     </para>
 610   </section>
 611   </section>
 612
 613 </chapter>
 614 <!-- End of EUG Chapter 1 -->