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