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