Further cleanup of Wireshark User Guide
[obnox/wireshark/wip.git] / docbook / wsug_src / WSUG_chapter_capture.xml
1 <!-- WSUG Chapter Capture -->
2 <!-- $Id$ -->
3
4 <chapter id="ChapterCapture">
5   <title>Capturing Live Network Data</title>
6   
7   <section id="ChCapIntroduction">
8         <title>Introduction</title>
9         <para>
10         Capturing live network data is one of the major features of Wireshark.
11         </para>
12         <para>
13         The Wireshark capture engine provides the following features:
14         </para>
15         <para>
16         <itemizedlist>
17         <listitem><para>
18         Capture from different kinds of network hardware (Ethernet, Token Ring, 
19         ATM, ...).
20         </para></listitem>
21         <listitem><para>
22         Stop the capture on different triggers like: amount of captured data, 
23         captured time, captured number of packets.
24         </para></listitem>
25         <listitem><para>
26         Simultaneously show decoded packets while keep on capturing.
27         </para></listitem>
28         <listitem><para>
29         Filter packets, reducing the amount of data to be captured, see <xref 
30         linkend="ChCapCaptureFilterSection"/>.
31         </para></listitem>
32         <listitem><para>
33         Capturing into multiple files while doing a long term capture, and in 
34         addition the option to form a ringbuffer of these files, keeping only 
35         the last x files, useful for a "very long term" capture, see <xref 
36         linkend="ChCapCaptureFiles"/>.
37         </para></listitem>
38         </itemizedlist>
39         The capture engine still lacks the following features:
40         <itemizedlist>
41         <listitem><para>
42         Simultaneous capturing from multiple network interfaces (however, you 
43         can start multiple instances of Wireshark and merge capture files later).
44         </para></listitem>
45         <listitem><para>
46         Stop capturing (or doing some other action), depending on the captured 
47         data.
48         </para></listitem>
49         </itemizedlist>
50         </para>
51   </section>
52
53   <section id="ChCapPrerequisitesSection"><title>Prerequisites</title>
54     <para>
55         Setting up Wireshark to capture packets for the first time can be tricky. 
56         </para>
57         <tip><title>Tip!</title><para>
58         A comprehensive guide "How To setup a Capture" is available at:
59         <ulink url="&WiresharkWikiPage;/CaptureSetup">&WiresharkWikiPage;/CaptureSetup</ulink>.
60         </para></tip>
61         <para>
62         Here are some common pitfalls:
63       <itemizedlist>
64         <listitem>
65           <para>
66                 You need to have root / Administrator privileges to start a live 
67                 capture.
68           </para>
69         </listitem>
70         <listitem>
71           <para>
72                 You need to choose the right network interface to capture packet data 
73                 from.
74           </para>
75         </listitem>
76         <listitem>
77           <para>
78                 You need to capture at the right place in the network to see the 
79                 traffic you want to see.
80           </para>
81         </listitem>
82         <listitem>
83           <para>
84                 ... and a lot more!.
85           </para>
86         </listitem>
87       </itemizedlist>
88         </para>
89         <para>
90         If you have any problems setting up your capture environment, you should 
91         have a look at the guide mentioned above.
92         </para>
93   </section>
94
95   <section id="ChCapCapturingSection"><title>Start Capturing</title>
96     <para>
97       One of the following methods can be used to start capturing packets with 
98           Wireshark:
99       <itemizedlist>
100         <listitem>
101           <para>
102             You can get an overview of the available local interfaces using the 
103                 "<inlinegraphic entityref="WiresharkToolbarCaptureInterfaces" format="PNG"/>
104                 Capture Interfaces" dialog box, see 
105                 <xref linkend="ChCapCaptureInterfacesDialog"/>. You can start a 
106                 capture from this dialog box, using (one of) the "Capture" button(s).
107           </para>
108         </listitem>
109         <listitem>
110           <para>
111             You can start capturing using the 
112                 "<inlinegraphic entityref="WiresharkToolbarCaptureOptions" format="PNG"/>
113                 Capture Options" dialog box, see 
114                 <xref linkend="ChCapCaptureOptionsDialog"/>.
115           </para>
116         </listitem>
117         <listitem>
118           <para>
119             If you have selected the right capture options before, you can 
120                 immediately start a capture using the 
121                 "<inlinegraphic entityref="WiresharkToolbarCaptureStart" format="PNG"/>
122                 Capture Start" menu / toolbar item. The capture
123                 process will start immediately.
124           </para>
125         </listitem>
126         <listitem>
127           <para>
128             If you already know the name of the capture interface, you can start 
129                 Wireshark from the command line and use the following:
130             <programlisting>
131 wireshark -i eth0 -k
132             </programlisting>
133                 This will start Wireshark capturing on interface eth0, more details 
134                 can be found at: <xref linkend="ChCustCommandLine"/>.
135           </para>
136         </listitem>
137       </itemizedlist>
138     </para>
139     </section>
140
141   <section id="ChCapInterfaceSection">
142         <title>The "Capture Interfaces" dialog box</title>
143         <para>
144         When you select "Interfaces..." from the Capture menu, Wireshark pops 
145         up the "Capture Interfaces" dialog box as shown in 
146         <xref linkend="ChCapCaptureInterfacesDialog"/>.
147         <warning><title>Warning!</title>
148         <para>
149         As the "Capture Interfaces" dialog is showing live captured data, it is 
150         consuming a lot of system ressources. Close this dialog as soon as 
151         possible to prevent excessive system load.
152         </para>
153         </warning>
154         <note><title>Note!</title>
155         <para>
156         This dialog box will only show the local interfaces Wireshark knows 
157         of. As Wireshark might not be able to detect all local interfaces, and it 
158         cannot detect the remote interfaces available, there could be more capture 
159         interfaces available than listed.
160         </para>
161         </note>
162         <figure id="ChCapCaptureInterfacesDialog">
163         <title>The "Capture Interfaces" dialog box</title>
164         <graphic entityref="WiresharkCaptureInterfacesDialog" format="PNG"/>
165         </figure>
166         <variablelist>
167           <varlistentry><term><command>Description</command></term>
168             <listitem>
169               <para>
170                   The interface description provided by the operating system.
171               </para>
172             </listitem>
173           </varlistentry>
174           <varlistentry><term><command>IP</command></term>
175             <listitem>
176               <para>
177                   The first IP address Wireshark could resolve from this interface. 
178                   If no address could be resolved (e.g. no DHCP server available), 
179                   "unknown" will be displayed. If more than one IP address could be 
180                   resolved, only the first is shown (unpredictable which one in that 
181                   case).
182               </para>
183             </listitem>
184           </varlistentry>
185           <varlistentry><term><command>Packets</command></term>
186             <listitem>
187               <para>
188                   The number of packets captured from this interface, since this 
189                   dialog was opened. Will be greyed out, if no packet was captured 
190                   in the last second.
191               </para>
192             </listitem>
193           </varlistentry>
194           <varlistentry><term><command>Packets/s</command></term>
195             <listitem>
196               <para>
197                   Number of packets captured in the last second. Will be greyed out, 
198                   if no packet was captured in the last second.
199               </para>
200             </listitem>
201           </varlistentry>
202           <varlistentry><term><command>Stop</command></term>
203             <listitem>
204               <para>
205                   Stop a currently running capture.
206               </para>
207             </listitem>
208           </varlistentry>
209           <varlistentry><term><command>Capture</command></term>
210             <listitem>
211               <para>
212                   Start a capture on this interface immediately, using the settings 
213                   from the last capture.
214               </para>
215             </listitem>
216           </varlistentry>
217           <varlistentry><term><command>Prepare</command></term>
218             <listitem>
219               <para>
220                   Open the Capture Options dialog with this interface selected, see 
221                   <xref linkend="ChCapCaptureOptions"/>.
222               </para>
223             </listitem>
224           </varlistentry>
225           <varlistentry><term><command>Close</command></term>
226             <listitem>
227               <para>
228                   Close this dialog box.
229               </para>
230             </listitem>
231           </varlistentry>
232         </variablelist>
233         </para>
234   </section>
235   
236     <section id="ChCapCaptureOptions">
237       <title>The "Capture Options" dialog box</title>
238       <para>
239         When you select Start... from the Capture menu (or use the corresponding 
240         item in the "Main" toolbar), Wireshark pops 
241         up the "Capture Options" dialog box as shown in 
242         <xref linkend="ChCapCaptureOptionsDialog"/>.
243       </para>
244       <figure id="ChCapCaptureOptionsDialog">
245         <title>The "Capture Options" dialog box</title>
246         <graphic entityref="WiresharkCaptureOptionsDialog" format="JPG"/>
247       </figure>
248         <tip><title>Tip!</title>
249         <para>
250         If you are unsure which options to choose in this dialog box, just try 
251         keeping the defaults as this should work well in many cases.
252         </para>
253         </tip>
254         <para>
255         You can set the following fields in this dialog box:
256         </para>
257         <section><title>Capture frame</title>
258         <variablelist>
259           <varlistentry><term><command>Interface</command></term>
260             <listitem>
261               <para>
262                 This field specifies the interface you want to capture on. 
263                 You can only capture on one interface, and you can only 
264                 capture on interfaces that Wireshark has found on the 
265                 system. It is a drop-down list, so simply click on the 
266                 button on the right hand side and select the interface you 
267                 want. It defaults to the first non-loopback interface that 
268                 supports capturing, and if there are none, the first 
269                 loopback interface. On some systems, loopback interfaces 
270                 cannot be used for capturing (loopback interfaces are not available 
271                 on Windows platforms).
272               </para>
273               <para>
274                 This field performs the same function as the 
275                 <command>-i &lt;interface></command> command line option.
276               </para>
277             </listitem>
278           </varlistentry>
279           <varlistentry><term><command>IP address</command></term>
280             <listitem>
281               <para>
282                   The IP address(es) of the selected interface. If no address could 
283                   be resolved from the system, "unknown" will be shown.
284               </para>
285             </listitem>
286           </varlistentry>
287           <varlistentry><term><command>Link-layer header type</command></term>
288             <listitem>
289               <para>
290                   Unless you are in the rare situation that you need this, just keep 
291                   the default. For a detailed description, see 
292                   <xref linkend="ChCapLinkLayerHeader"/>
293               </para>
294             </listitem>
295           </varlistentry>
296           <varlistentry><term><command>Buffer size: n megabyte(s)</command></term>
297             <listitem>
298               <para>
299                   Enter the buffer size to be used while capturing. This is the size 
300                   of the kernel buffer which will keep the captured packets, until 
301                   they are written to disk. If you encounter packet drops, try 
302                   increasing this value.
303               </para>
304               <note>
305                   <title>Note</title>
306                   <para>This option is only available on Windows platforms.</para>
307               </note>
308             </listitem>
309           </varlistentry>
310           <varlistentry>
311             <term>
312               <command>Capture packets in promiscuous mode</command>
313             </term>
314             <listitem>
315               <para>
316                 This checkbox allows you to specify that Wireshark 
317                 should put the interface in promiscuous mode when capturing. 
318                 If you do not specify this, Wireshark will only capture the 
319                 packets going to or from your computer (not 
320                 all packets on your LAN segment).
321               </para>
322               <note>
323                 <title>Note</title>
324                 <para>
325                   If some other process has put the interface in 
326                   promiscuous mode you may be capturing in promiscuous 
327                   mode even if you turn off this option
328                 </para>
329               </note>
330               <note>
331                 <title>Note</title>
332                 <para>
333                 Even in promiscuous mode you still won't necessarily see all packets 
334                 on your LAN segment, see <ulink url="&WiresharkFAQPromiscPage;"/> for 
335                 some more explanations.
336                 </para>
337               </note>
338             </listitem>
339           </varlistentry>
340           <varlistentry><term><command>Limit each packet to n bytes</command></term>
341             <listitem>
342               <para>
343                 This field allows you to specify the maximum amount of 
344                 data that will be captured for each packet, and is 
345                 sometimes referred to as the <command>snaplen</command>. If disabled, 
346                 the default is 65535, which will be sufficient for most 
347                 protocols. Some rules of thumb:
348               </para>
349                 <itemizedlist>
350             <listitem>
351               <para>
352                         If you are unsure, just keep the default value.
353               </para>
354             </listitem>
355             <listitem>
356               <para>
357                         If you don't need all of the data in a packet - for example, if you
358                         only need the link-layer, IP, and TCP headers - you might want to
359                         choose a small snapshot length, as less CPU time is required for
360                         copying packets, less buffer space is required for packets, and thus
361                         perhaps fewer packets will be dropped if traffic is very heavy.
362               </para>
363             </listitem>
364             <listitem>
365               <para>
366                         If you don't capture all of the data in a packet, you might find that
367                         the packet data you want is in the part that's dropped, or that
368                         reassembly isn't possible as the data required for reassembly is
369                         missing.
370               </para>
371             </listitem>
372                 </itemizedlist>
373             </listitem>
374           </varlistentry>
375           <varlistentry><term><command>Capture Filter</command></term>
376             <listitem>
377               <para>
378                 This field allows you to specify a capture filter. 
379                 Capture filters are discussed in more details in 
380                 <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or 
381                   no filter.
382               </para>
383               <para>
384                 You can also click on the button labelled Capture Filter, and Wireshark 
385                 will bring up the Capture Filters dialog box and allow you to create 
386                 and/or select a filter.  Please see 
387                 <xref linkend="ChWorkDefineFilterSection"/>
388               </para>
389             </listitem>
390           </varlistentry>
391         </variablelist>
392         </section>
393         <section><title>Capture File(s) frame</title>
394         <para>
395         An explanation about capture file usage can be found in <xref 
396         linkend="ChCapCaptureFiles"/>.
397         </para>
398         <variablelist>    
399           <varlistentry><term><command>File</command></term>
400             <listitem>
401               <para>
402                         This field allows you to specify the file name that will be 
403                         used for the capture file. This field is left blank by default.
404                         If the field is left blank, the capture data will be stored in a 
405                         temporary file, see <xref linkend="ChCapCaptureFiles"/> for 
406                         details.
407               </para>
408               <para>
409                         You can also click on the button to the right of this field to 
410                         browse through the filesystem.
411               </para>
412             </listitem>
413           </varlistentry>
414           <varlistentry><term><command>Use multiple files</command></term>
415             <listitem>
416               <para>
417                         Instead of using a single file, Wireshark will automatically switch 
418                         to a new one, if a specific trigger condition is reached.
419               </para>
420             </listitem>
421           </varlistentry>
422           <varlistentry><term><command>Next file every n megabyte(s)</command></term>
423             <listitem>
424               <para>
425                         Multiple files only: Switch to the next file after the given 
426                         number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been
427                         captured. 
428               </para>
429             </listitem>
430           </varlistentry>
431           <varlistentry><term><command>Next file every n minute(s)</command></term>
432             <listitem>
433               <para>
434                         Multiple files only: Switch to the next file after the given 
435                         number of second(s)/minutes(s)/hours(s)/days(s) have elapsed.
436               </para>
437             </listitem>
438           </varlistentry>
439           <varlistentry><term><command>Ring buffer with n files</command></term>
440             <listitem>
441               <para>
442                         Multiple files only: Form a ring buffer of the capture files, with 
443                         the given number of files.
444               </para>
445             </listitem>
446           </varlistentry>
447           <varlistentry><term><command>Stop capture after n file(s)</command></term>
448             <listitem>
449               <para>
450                         Multiple files only: Stop capturing after switching to the next 
451                         file the given number of times.
452               </para>
453             </listitem>
454           </varlistentry>
455         </variablelist>
456         </section>
457         <section><title>Stop Capture... frame</title>
458         <variablelist>    
459           <varlistentry><term><command>... after n packet(s)</command></term>
460             <listitem>
461               <para>
462                         Stop capturing after the given number of packets have been
463                         captured.
464               </para>
465             </listitem>
466           </varlistentry>
467           <varlistentry><term><command>... after n megabytes(s)</command></term>
468             <listitem>
469               <para>
470                         Stop capturing after the given number of 
471                         byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured.
472                         This option is greyed out, if "Use multiple files" is selected.
473               </para>
474             </listitem>
475           </varlistentry>
476           <varlistentry><term><command>... after n minute(s)</command></term>
477             <listitem>
478               <para>
479                         Stop capturing after the given number of 
480                         second(s)/minutes(s)/hours(s)/days(s) have elapsed.
481               </para>
482             </listitem>
483           </varlistentry>
484         </variablelist>
485         </section>
486         <section><title>Display Options frame</title>
487         <variablelist>    
488           <varlistentry>
489             <term>
490               <command>Update list of packets in real time</command>
491             </term>
492             <listitem>
493               <para>
494                 This option allows you to specify that Wireshark 
495                 should update the packet list pane in real time. If you 
496                 do not specify this, Wireshark does not display any 
497                 packets until you stop the capture. When you check this,
498                 Wireshark captures in a separate process 
499                 and feeds the captures to the display process.
500               </para>
501             </listitem>
502           </varlistentry>
503           <varlistentry>
504             <term>
505               <command>Automatic scrolling in live capture</command>
506             </term>
507             <listitem>
508               <para>
509                 This option allows you to specify that Wireshark 
510                 should scroll the packet list pane as new packets come 
511                 in, so you are always looking at the last packet.  If you 
512                 do not specify this, Wireshark simply adds new packets onto 
513                 the end of the list, but does not scroll the packet list 
514                 pane. This option is greyed out if 
515                 "Update list of packets in real time" is disabled.
516               </para>
517             </listitem>
518           </varlistentry>
519           <varlistentry>
520             <term>
521               <command>Hide capture info dialog</command>
522             </term>
523             <listitem>
524               <para>
525                 If this option is checked, the following capture info dialog will be 
526                 hidden.
527               </para>
528             </listitem>
529           </varlistentry>
530         </variablelist>
531         </section>
532         <section><title>Name Resolution frame</title>
533         <variablelist>    
534           <varlistentry>
535             <term><command>Enable MAC name resolution</command></term>
536             <listitem>
537               <para>
538                 This option allows you to control whether or not 
539                 Wireshark translates MAC addresses into names, see 
540                 <xref linkend="ChAdvNameResolutionSection"/>.
541               </para>
542             </listitem>
543           </varlistentry>
544           <varlistentry>
545             <term><command>Enable network name resolution</command></term>
546             <listitem>
547               <para>
548                 This option allows you to control whether or not 
549                 Wireshark translates network addresses into names, see
550                 <xref linkend="ChAdvNameResolutionSection"/>.
551               </para>  
552             </listitem>
553           </varlistentry>
554           <varlistentry>
555             <term><command>Enable transport name resolution</command></term>
556             <listitem>
557               <para>
558                 This option allows you to control whether or not 
559                 Wireshark translates transport addresses into protocols, see
560                 <xref linkend="ChAdvNameResolutionSection"/>.
561               </para>
562             </listitem>
563           </varlistentry>
564         </variablelist>
565         </section>
566         <section><title>Buttons</title>
567       <para>
568         Once you have set the values you desire and have selected the 
569         options you need, simply click on <command>OK</command> to commence the 
570         capture, or <command>Cancel</command> to cancel the capture.
571       </para>
572       <para>
573         If you start a capture, Wireshark allows you to stop capturing when 
574         you have enough packets captured, for details see
575                 <xref linkend="ChCapRunningSection"/>.
576       </para>
577     </section>
578     </section>
579         
580     <section id="ChCapCaptureFiles"><title>Capture files and file modes</title>
581         <para>
582         While capturing, the underlying libpcap capturing engine will grab the 
583         packets from the network card and keep the packet data in a (relatively) 
584         small kernel buffer. This data is read by Wireshark and saved into 
585         the capture file(s) the user specified.
586         </para>
587
588         <para>
589         Different modes of operation are available when saving this packet data to 
590         the capture file(s).
591         </para>
592         
593         <tip><title>Tip!</title>
594         <para>
595         Working with large files (several 100 MB's) can be quite slow. If you plan 
596         to do a long term capture or capturing from a high traffic network, think 
597         about using one of the "Multiple files" options. This  will spread the 
598         captured packets over several smaller files which can be much more 
599         pleasant to work with.
600         </para>
601         </tip>
602         <note><title>Note!</title>
603         <para>
604         Using Multiple files may cut context related information.
605         Wireshark keeps context information of the loaded packet data, so it can 
606         report context related problems (like a stream error) and keeps information
607         about context related protocols (e.g. where data is exchanged at the 
608         establishing phase and only referred to in later packets). 
609         As it keeps this information only for the loaded file, using one of 
610         the multiple file modes may cut these contexts. If the establishing phase 
611         is saved in one file and the things you would like to see is in another, 
612         you might not see some of the valuable context related information.
613         </para>
614         </note>
615         <tip><title>Tip!</title>
616         <para>
617         Information about the folders used for the capture file(s), can be found 
618         in <xref linkend="AppFiles"/>. 
619         </para>
620         </tip>
621         
622     <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title>
623       <tgroup cols="5">
624         <colspec colnum="1" colwidth="72pt"/>
625           <colspec colnum="2" colwidth="80pt"/>
626           <colspec colnum="3" colwidth="80pt"/>
627           <colspec colnum="4" colwidth="80pt"/>
628             <thead>
629               <row>
630                 <entry>"File" option</entry>
631                 <entry>"Use multiple files" option</entry>
632                 <entry>"Ring buffer with n files" option</entry>
633                 <entry>Mode</entry>
634                 <entry>Resulting filename(s) used</entry>
635               </row>
636             </thead>
637             <tbody>
638               <row>
639                 <entry>-</entry>
640                 <entry>-</entry>
641                 <entry>-</entry>
642                 <entry><command>Single temporary file</command></entry>
643                 <entry>etherXXXXXX (where XXXXXX is a unique number)</entry>
644               </row>
645               <row>
646                 <entry>foo.cap</entry>
647                 <entry>-</entry>
648                 <entry>-</entry>
649                 <entry><command>Single named file</command></entry>
650                 <entry>foo.cap</entry>
651               </row>
652               <row>
653                 <entry>foo.cap</entry>
654                 <entry>x</entry>
655                 <entry>-</entry>
656                 <entry><command>Multiple files, continuous</command></entry>
657                 <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
658               </row>
659               <row>
660                 <entry>foo.cap</entry>
661                 <entry>x</entry>
662                 <entry>x</entry>
663                 <entry><command>Multiple files, ring buffer</command></entry>
664                 <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
665               </row>
666             </tbody>
667       </tgroup>
668     </table>
669         <variablelist>
670           <varlistentry>
671             <term><command>Single temporary file</command></term>
672             <listitem>
673         <para>
674         A temporary file will be created and used (this is the default). After the 
675         capturing is stopped, this file can be saved later under a user specified 
676         name.
677         </para>
678             </listitem>
679           </varlistentry>
680           <varlistentry>
681             <term><command>Single named file</command></term>
682             <listitem>
683         <para>
684         A single capture file will be used. If you want to place the new capture 
685         file to a specific folder, choose this mode.
686         </para>
687             </listitem>
688           </varlistentry>
689           <varlistentry>
690             <term><command>Multiple files, continuous</command></term>
691             <listitem>
692         <para>
693         Like the "Single named file" mode, but a new file is created and used, 
694         after reaching one of the multiple file switch conditions (one of the 
695         "Next file every ..." values).
696         </para>
697             </listitem>
698           </varlistentry>
699           <varlistentry>
700             <term><command>Multiple files, ring buffer</command></term>
701             <listitem>
702         <para>
703         Much like "Multiple files continuous", reaching one of the multiple files 
704         switch conditions (one of the "Next file every ..." values) will switch 
705         to the next file. This will be a newly created file if value of "Ring 
706         buffer with n files" is not reached, otherwise it will replace the oldest 
707         of the formerly used files (thus forming a "ring").
708         </para>
709         <para>
710         This mode will limit the maximum disk usage, even for an unlimited amount of 
711         capture input data, keeping the latest captured data.
712         </para>
713             </listitem>
714           </varlistentry>
715         </variablelist>
716         </section>
717
718   <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title>
719         <para>
720         In the usual case, you won't have to choose this link-layer header type. 
721         The following paragraphs describe the exceptional cases, where
722         selecting this type is possible, so you will have a guide what to do:
723         </para>
724     <para>
725     If you are capturing on an 802.11 device on some versions of BSD, this 
726         might offer a choice of "Ethernet" or "802.11".  "Ethernet" will cause 
727         the captured packets to have fake Ethernet headers; "802.11" will cause 
728         them to have IEEE 802.11 headers.  Unless the capture needs to be read by 
729         an application that doesn't support 802.11 headers, you should select 
730         "802.11".
731         </para>
732         <para>
733     If you are capturing on an Endace DAG card connected to a synchronous 
734         serial line, this might offer a choice of "PPP over serial" or 
735         "Cisco HDLC"; if the protocol on the serial line is PPP, select 
736         "PPP over serial", and if the protocol on the serial line is Cisco HDLC, 
737         select "Cisco HDLC".
738         </para>
739         <para>
740     If you are capturing on an Endace DAG card connected to an ATM network, 
741         this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM".  
742         If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if 
743         the capture needs to be read by an application that doesn't support SunATM 
744         headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM".
745         </para>
746         <para>
747     If you are capturing on an Ethernet device, this might offer a choice of 
748         "Ethernet" or "DOCSIS".  If you are capturing traffic from a Cisco Cable 
749         Modem Termination System that is putting DOCSIS traffic onto the Ethernet 
750         to be captured, select "DOCSIS", otherwise select "Ethernet".
751     </para>
752   </section>
753
754   <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title>
755     <para>
756       Wireshark uses the libpcap filter language for capture filters. 
757       This is explained in the tcpdump man page, which can be hard to 
758           understand, so it's explained here to some extent.
759     </para>
760     <tip>
761       <title>Tip!</title>
762       <para>
763           You will find a lot of Capture Filter examples at <ulink 
764           url="&WiresharkWikiCaptureFiltersPage;">&WiresharkWikiCaptureFiltersPage;</ulink>.
765       </para>
766     </tip>
767     <para>
768       You enter the capture filter into the Filter field of the Wireshark 
769       Capture Options dialog box, as shown in 
770       <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline 
771           of the syntax of the <command>tcpdump</command> capture filter language. 
772           See the expression option at the tcpdump manual page for details:
773           <ulink url="&TcpdumpManpage;"/>.
774     </para>
775     <para>
776       A capture filter takes the form of a series of primitive expressions 
777       connected by conjunctions (<command>and/or</command>) and optionally 
778       preceded by <command>not</command>:
779       <programlisting>
780 [not] <command>primitive</command> [and|or [not] <command>primitive</command> ...]
781       </programlisting>
782       An example is shown in <xref linkend="ChCapExFilt1"/>.
783
784       <example id="ChCapExFilt1">
785         <title>
786           A capture filter for telnet than captures traffic to and from a 
787           particular host
788         </title>
789         <programlisting>
790 tcp port 23 and host 10.0.0.5
791         </programlisting>
792       </example>
793       This example captures telnet traffic to and from the host 
794       10.0.0.5, and shows how to use two primitives and the 
795       <command>and</command> conjunction.  Another example is shown in 
796       <xref linkend="ChCapExFilt2"/>, and shows how to capture all 
797         telnet traffic except that from 10.0.0.5.
798         <example id="ChCapExFilt2">
799           <title>
800             Capturing all telnet traffic not from 10.0.0.5</title>
801           <programlisting>
802 tcp port 23 and not host 10.0.0.5
803           </programlisting>
804         </example>
805       </para>
806
807       <para>
808           XXX - add examples to the following list.
809       </para>
810       <para>
811       A primitive is simply one of the following:
812       <variablelist>
813         <varlistentry>
814           <term><command>[src|dst] host &lt;host></command></term>
815           <listitem>
816             <para>
817               This primitive allows you to filter on a host IP 
818               address or name. You can optionally precede the 
819               primitive with the keyword <command>src|dst</command> 
820               to specify that you are only interested in source or 
821               destination addresses. If these are not present, 
822               packets where the specified address appears as either 
823               the source or the destination address will be selected.
824             </para>
825           </listitem>
826         </varlistentry>
827         <varlistentry>
828           <term>
829             <command>ether [src|dst] host &lt;ehost></command>
830           </term>
831           <listitem>
832             <para>
833               This primitive allows you to filter on Ethernet host 
834               addresses. You can optionally include the keyword 
835               <command>src|dst</command> between the keywords 
836               <command>ether</command> and <command>host</command> 
837               to specify that you are only interested in source 
838               or destination addresses.  If these are not present, 
839               packets where the specified address appears in either 
840               the source or destination address will be selected.
841             </para>
842           </listitem>
843         </varlistentry>
844         <varlistentry>
845           <term><command>gateway host &lt;host></command></term>
846           <listitem>
847             <para>
848               This primitive allows you to filter on packets that 
849               used <command>host</command> as a gateway. That is, where 
850               the Ethernet source or destination was 
851               <command>host</command> but neither the source nor 
852               destination IP address was <command>host</command>.
853             </para>
854           </listitem>
855         </varlistentry>
856         <varlistentry>
857           <term>
858             <command>
859               [src|dst] net &lt;net> [{mask &lt;mask>}|{len &lt;len>}]
860             </command>
861           </term>
862           <listitem>
863             <para>
864               This primitive allows you to filter on network numbers. 
865               You can optionally precede this primitive with the 
866               keyword <command>src|dst</command> to specify that you 
867               are only interested in a source or destination network. 
868               If neither of these are present, packets will be 
869               selected that have the specified network in either the
870               source or destination address.  In addition, you can 
871               specify either the netmask or the CIDR prefix for the 
872               network if they are different from your own. 
873             </para>
874           </listitem>
875         </varlistentry>
876         <varlistentry>
877           <term>
878             <command>[tcp|udp] [src|dst] port &lt;port></command>
879           </term>
880           <listitem>
881             <para>
882               This primitive allows you to filter on TCP and UDP port 
883               numbers. You can optionally precede this primitive with 
884               the keywords <command>src|dst</command> and 
885               <command>tcp|udp</command> which allow you to specify 
886               that you are only interested in source or destination 
887               ports and TCP or UDP packets respectively.  The 
888               keywords <command>tcp|udp</command> must appear before 
889               <command>src|dst</command>.
890             </para>
891             <para>
892               If these are not specified, packets will be selected 
893               for both the TCP and UDP protocols and when the 
894               specified address appears in either the source or 
895               destination port field.
896             </para>
897           </listitem>
898         </varlistentry>
899         <varlistentry>
900           <term><command>less|greater &lt;length></command></term>
901           <listitem>
902             <para>
903               This primitive allows you to filter on packets whose 
904               length was less than or equal to the specified length, 
905               or greater than or equal to the specified length, 
906               respectively.
907             </para>
908           </listitem>
909         </varlistentry>
910         <varlistentry>
911           <term><command>ip|ether proto &lt;protocol></command></term>
912           <listitem>
913             <para>
914               This primitive allows you to filter on the specified 
915               protocol at either the Ethernet layer or the IP layer.
916             </para>
917           </listitem>
918         </varlistentry>
919         <varlistentry>
920           <term><command>ether|ip broadcast|multicast</command></term>
921           <listitem>
922             <para>
923               This primitive allows you to filter on either 
924               Ethernet or IP broadcasts or multicasts.
925             </para>
926           </listitem>
927         </varlistentry>
928         <varlistentry>
929           <term><command>&lt;expr> relop &lt;expr></command></term>
930           <listitem>
931             <para>
932               This primitive allows you to create complex filter 
933               expressions that select bytes or ranges of bytes in 
934               packets.  Please see the tcpdump man page at
935                   <ulink url="&TcpdumpManpage;"/> for more details.
936             </para>
937           </listitem>
938         </varlistentry>
939       </variablelist>
940     </para>
941   </section>
942
943   <section id="ChCapRunningSection"><title>While a Capture is running ...</title>
944     <para>
945         While a capture is running, the following dialog box is shown:
946       <figure id="ChCapCaptureInfoDialog">
947         <title>The "Capture Info" dialog box</title>
948         <graphic entityref="WiresharkCaptureInfoDialog" format="JPG"/>
949       </figure>
950         This dialog box will inform you about the number of captured packets and 
951         the time since the capture was started. The selection which protocols
952         are counted cannot be changed.
953         </para>
954           <tip><title>Tip!</title>
955           <para>
956           This Capture Info dialog box can be hidden, using the "Hide capture info 
957           dialog" option in the Capture Options dialog box.
958           </para>
959           </tip>
960         <section id="ChCapStopSection"><title>Stop the running capture</title>
961     <para>
962       A running capture session will be stopped in one of the following ways:
963       <orderedlist>
964         <listitem>
965           <para>Using the 
966           "<inlinegraphic entityref="WiresharkToolbarStop" format="PNG"/>
967           Stop" button from the <command>Capture Info dialog box
968           </command>.
969           </para>
970           <note><title>Note!</title>
971           <para>
972           The Capture Info dialog box might be hidden, if the option "Hide capture 
973           info dialog" is used.
974           </para>
975           </note>
976         </listitem>
977         <listitem>
978           <para>Using the <command>menu item</command>
979           "Capture/<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
980           Stop". 
981           </para>
982         </listitem>
983         <listitem>
984           <para>Using the <command>toolbar item</command>
985           "<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
986           Stop". 
987           </para>
988         </listitem>
989         <listitem>
990           <para>Pressing the accelerator keys: <command>Ctrl+E</command>. 
991           </para>
992         </listitem>
993         <listitem>
994           <para>The capture will be automatically stopped, if one of the 
995           <command>Stop Conditions</command> is exceeded, e.g. the maximum amount 
996           of data was captured.
997           </para>
998         </listitem>
999       </orderedlist>
1000     </para>
1001     </section>
1002         <section id="ChCapRestartSection"><title>Restart a running capture</title>
1003     <para>
1004       A running capture session can be restarted with the same capture options 
1005           than the last time, this will remove all packets previously captured.
1006           This can be useful, if some uninteresting packets are captured and 
1007           there's no need to keep them.
1008     </para>
1009     <para>        
1010           Restart is a convenience function and 
1011           equivalent to a capture stop following by an immediate capture start. 
1012           A restart can be triggered in one of the following ways:
1013       <orderedlist>
1014         <listitem>
1015           <para>Using the <command>menu item</command>
1016           "Capture/<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
1017           Restart". 
1018           </para>
1019         </listitem>
1020         <listitem>
1021           <para>Using the <command>toolbar item</command> 
1022           "<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
1023           Restart". 
1024           </para>
1025         </listitem>
1026       </orderedlist>
1027     </para>
1028     </section>
1029     </section>
1030
1031 </chapter>
1032 <!-- End of WSUG Chapter Capture -->
1033