EUG -> WSUG

svn path=/trunk/; revision=18256

1 files changed, 1033 insertions, 0 deletions

diff --git a/docbook/wsug_src/WSUG_chapter_capture.xml b/docbook/wsug_src/WSUG_chapter_capture.xml
new file mode 100644
index 0000000000..23a00c13a7
--- /dev/null
+++ b/docbook/wsug_src/WSUG_chapter_capture.xml
@@ -0,0 +1,1033 @@
+<!-- WSUG Chapter Capture -->
+<!-- $Id$ -->
+
+<chapter id="ChapterCapture">
+  <title>Capturing Live Network Data</title>
+  
+  <section id="ChCapIntroduction">
+	<title>Introduction</title>
+	<para>
+	Capturing live network data is one of the major features of Ethereal.
+	</para>
+	<para>
+	The Wireshark capture engine provides the following features:
+	</para>
+	<para>
+	<itemizedlist>
+	<listitem><para>
+	Capture from different kinds of network hardware (Ethernet, Token Ring, 
+	ATM, ...).
+	</para></listitem>
+	<listitem><para>
+	Stop the capture on different triggers like: amount of captured data, 
+	captured time, captured number of packets.
+	</para></listitem>
+	<listitem><para>
+	Simultaneously show decoded packets while keep on capturing.
+	</para></listitem>
+	<listitem><para>
+	Filter packets, reducing the amount of data to be captured, see <xref 
+	linkend="ChCapCaptureFilterSection"/>.
+	</para></listitem>
+	<listitem><para>
+	Capturing into multiple files while doing a long term capture, and in 
+	addition the option to form a ringbuffer of these files, keeping only 
+	the last x files, useful for a "very long term" capture, see <xref 
+	linkend="ChCapCaptureFiles"/>.
+	</para></listitem>
+	</itemizedlist>
+	The capture engine still lacks the following features:
+	<itemizedlist>
+	<listitem><para>
+	Simultaneous capturing from multiple network interfaces (however, you 
+	can start multiple instances of Ethereal and merge capture files later).
+	</para></listitem>
+	<listitem><para>
+	Stop capturing (or doing some other action), depending on the captured 
+	data.
+	</para></listitem>
+	</itemizedlist>
+	</para>
+  </section>
+
+  <section id="ChCapPrerequisitesSection"><title>Prerequisites</title>
+    <para>
+	Setting up Ethereal to capture packets for the first time can be tricky. 
+	</para>
+	<tip><title>Tip!</title><para>
+	A comprehensive guide "How To setup a Capture" is available at:
+	<ulink url="http://wiki.ethereal.com/CaptureSetup">http://wiki.ethereal.com/CaptureSetup</ulink>.
+	</para></tip>
+	<para>
+	Here are some common pitfalls:
+      <itemizedlist>
+	<listitem>
+	  <para>
+		You need to have root / Administrator privileges to start a live 
+		capture.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+		You need to choose the right network interface to capture packet data 
+		from.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+		You need to capture at the right place in the network to see the 
+		traffic you want to see.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+		... and a lot more!.
+	  </para>
+	</listitem>
+      </itemizedlist>
+	</para>
+	<para>
+	If you have any problems setting up your capture environment, you should 
+	have a look at the guide mentioned above.
+	</para>
+  </section>
+
+  <section id="ChCapCapturingSection"><title>Start Capturing</title>
+    <para>
+      One of the following methods can be used to start capturing packets with 
+	  Ethereal:
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    You can get an overview of the available local interfaces using the 
+		"<inlinegraphic entityref="EtherealToolbarCaptureInterfaces" format="PNG"/>
+		Capture Interfaces" dialog box, see 
+		<xref linkend="ChCapCaptureInterfacesDialog"/>. You can start a 
+		capture from this dialog box, using (one of) the "Capture" button(s).
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    You can start capturing using the 
+		"<inlinegraphic entityref="EtherealToolbarCaptureOptions" format="PNG"/>
+		Capture Options" dialog box, see 
+		<xref linkend="ChCapCaptureOptionsDialog"/>.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    If you have selected the right capture options before, you can 
+		immediately start a capture using the 
+		"<inlinegraphic entityref="EtherealToolbarCaptureStart" format="PNG"/>
+		Capture Start" menu / toolbar item. The capture
+		process will start immediately.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    If you already know the name of the capture interface, you can start 
+		Ethereal from the command line and use the following:
+	    <programlisting>
+ethereal -i eth0 -k
+	    </programlisting>
+		This will start Ethereal capturing on interface eth0, more details 
+		can be found at: <xref linkend="ChCustCommandLine"/>.
+	  </para>
+	</listitem>
+      </itemizedlist>
+    </para>
+    </section>
+
+  <section id="ChCapInterfaceSection">
+	<title>The "Capture Interfaces" dialog box</title>
+	<para>
+	When you select "Interfaces..." from the Capture menu, Ethereal pops 
+	up the "Capture Interfaces" dialog box as shown in 
+	<xref linkend="ChCapCaptureInterfacesDialog"/>.
+	<warning><title>Warning!</title>
+	<para>
+	As the "Capture Interfaces" dialog is showing live captured data, it is 
+	consuming a lot of system ressources. Close this dialog as soon as 
+	possible to prevent excessive system load.
+	</para>
+	</warning>
+	<note><title>Note!</title>
+	<para>
+	This dialog box will only show the local interfaces Ethereal knows 
+	of. As Ethereal might not be able to detect all local interfaces, and it 
+	cannot detect the remote interfaces available, there could be more capture 
+	interfaces available than listed.
+	</para>
+	</note>
+	<figure id="ChCapCaptureInterfacesDialog">
+	<title>The "Capture Interfaces" dialog box</title>
+	<graphic entityref="EtherealCaptureInterfacesDialog" format="PNG"/>
+	</figure>
+	<variablelist>
+	  <varlistentry><term><command>Description</command></term>
+	    <listitem>
+	      <para>
+		  The interface description provided by the operating system.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>IP</command></term>
+	    <listitem>
+	      <para>
+		  The first IP address Ethereal could resolve from this interface. 
+		  If no address could be resolved (e.g. no DHCP server available), 
+		  "unknown" will be displayed. If more than one IP address could be 
+		  resolved, only the first is shown (unpredictable which one in that 
+		  case).
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Packets</command></term>
+	    <listitem>
+	      <para>
+		  The number of packets captured from this interface, since this 
+		  dialog was opened. Will be greyed out, if no packet was captured 
+		  in the last second.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Packets/s</command></term>
+	    <listitem>
+	      <para>
+		  Number of packets captured in the last second. Will be greyed out, 
+		  if no packet was captured in the last second.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Stop</command></term>
+	    <listitem>
+	      <para>
+		  Stop a currently running capture.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Capture</command></term>
+	    <listitem>
+	      <para>
+		  Start a capture on this interface immediately, using the settings 
+		  from the last capture.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Prepare</command></term>
+	    <listitem>
+	      <para>
+		  Open the Capture Options dialog with this interface selected, see 
+		  <xref linkend="ChCapCaptureOptions"/>.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Close</command></term>
+	    <listitem>
+	      <para>
+		  Close this dialog box.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</para>
+  </section>
+  
+    <section id="ChCapCaptureOptions">
+      <title>The "Capture Options" dialog box</title>
+      <para>
+	When you select Start... from the Capture menu (or use the corresponding 
+	item in the "Main" toolbar), Ethereal pops 
+	up the "Capture Options" dialog box as shown in 
+	<xref linkend="ChCapCaptureOptionsDialog"/>.
+      </para>
+      <figure id="ChCapCaptureOptionsDialog">
+	<title>The "Capture Options" dialog box</title>
+	<graphic entityref="EtherealCaptureOptionsDialog" format="JPG"/>
+      </figure>
+	<tip><title>Tip!</title>
+	<para>
+	If you are unsure which options to choose in this dialog box, just try 
+	keeping the defaults as this should work well in many cases.
+	</para>
+	</tip>
+	<para>
+	You can set the following fields in this dialog box:
+	</para>
+	<section><title>Capture frame</title>
+	<variablelist>
+	  <varlistentry><term><command>Interface</command></term>
+	    <listitem>
+	      <para>
+		This field specifies the interface you want to capture on. 
+		You can only capture on one interface, and you can only 
+		capture on interfaces that Ethereal has found on the 
+		system. It is a drop-down list, so simply click on the 
+		button on the right hand side and select the interface you 
+		want. It defaults to the first non-loopback interface that 
+		supports capturing, and if there are none, the first 
+		loopback interface. On some systems, loopback interfaces 
+		cannot be used for capturing (loopback interfaces are not available 
+		on Windows platforms).
+	      </para>
+	      <para>
+		This field performs the same function as the 
+		<command>-i &lt;interface></command> command line option.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>IP address</command></term>
+	    <listitem>
+	      <para>
+		  The IP address(es) of the selected interface. If no address could 
+		  be resolved from the system, "unknown" will be shown.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Link-layer header type</command></term>
+	    <listitem>
+	      <para>
+		  Unless you are in the rare situation that you need this, just keep 
+		  the default. For a detailed description, see 
+		  <xref linkend="ChCapLinkLayerHeader"/>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Buffer size: n megabyte(s)</command></term>
+	    <listitem>
+	      <para>
+		  Enter the buffer size to be used while capturing. This is the size 
+		  of the kernel buffer which will keep the captured packets, until 
+		  they are written to disk. If you encounter packet drops, try 
+		  increasing this value.
+	      </para>
+	      <note>
+		  <title>Note</title>
+		  <para>This option is only available on Windows platforms.</para>
+	      </note>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>
+	      <command>Capture packets in promiscuous mode</command>
+	    </term>
+	    <listitem>
+	      <para>
+		This checkbox allows you to specify that Ethereal 
+		should put the interface in promiscuous mode when capturing. 
+		If you do not specify this, Ethereal will only capture the 
+		packets going to or from your computer (not 
+		all packets on your LAN segment).
+	      </para>
+	      <note>
+		<title>Note</title>
+		<para>
+		  If some other process has put the interface in 
+		  promiscuous mode you may be capturing in promiscuous 
+		  mode even if you turn off this option
+		</para>
+	      </note>
+	      <note>
+		<title>Note</title>
+		<para>
+		Even in promiscuous mode you still won't necessarily see all packets 
+		on your LAN segment, see <ulink url="&EtherealFAQPromiscPage;"/> for 
+		some more explanations.
+		</para>
+	      </note>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Limit each packet to n bytes</command></term>
+	    <listitem>
+	      <para>
+		This field allows you to specify the maximum amount of 
+		data that will be captured for each packet, and is 
+		sometimes referred to as the <command>snaplen</command>. If disabled, 
+		the default is 65535, which will be sufficient for most 
+		protocols. Some rules of thumb:
+	      </para>
+		<itemizedlist>
+	    <listitem>
+	      <para>
+			If you are unsure, just keep the default value.
+	      </para>
+	    </listitem>
+	    <listitem>
+	      <para>
+			If you don't need all of the data in a packet - for example, if you
+			only need the link-layer, IP, and TCP headers - you might want to
+			choose a small snapshot length, as less CPU time is required for
+			copying packets, less buffer space is required for packets, and thus
+			perhaps fewer packets will be dropped if traffic is very heavy.
+	      </para>
+	    </listitem>
+	    <listitem>
+	      <para>
+			If you don't capture all of the data in a packet, you might find that
+			the packet data you want is in the part that's dropped, or that
+			reassembly isn't possible as the data required for reassembly is
+			missing.
+	      </para>
+	    </listitem>
+		</itemizedlist>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Capture Filter</command></term>
+	    <listitem>
+	      <para>
+		This field allows you to specify a capture filter. 
+		Capture filters are discussed in more details in 
+		<xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or 
+		  no filter.
+	      </para>
+	      <para>
+		You can also click on the button labelled Capture Filter, and Ethereal 
+		will bring up the Capture Filters dialog box and allow you to create 
+		and/or select a filter.  Please see 
+		<xref linkend="ChWorkDefineFilterSection"/>
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</section>
+	<section><title>Capture File(s) frame</title>
+	<para>
+	An explanation about capture file usage can be found in <xref 
+	linkend="ChCapCaptureFiles"/>.
+	</para>
+	<variablelist>	  
+	  <varlistentry><term><command>File</command></term>
+	    <listitem>
+	      <para>
+			This field allows you to specify the file name that will be 
+			used for the capture file. This field is left blank by default.
+			If the field is left blank, the capture data will be stored in a 
+			temporary file, see <xref linkend="ChCapCaptureFiles"/> for 
+			details.
+	      </para>
+	      <para>
+			You can also click on the button to the right of this field to 
+			browse through the filesystem.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Use multiple files</command></term>
+	    <listitem>
+	      <para>
+			Instead of using a single file, Ethereal will automatically switch 
+			to a new one, if a specific trigger condition is reached.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Next file every n megabyte(s)</command></term>
+	    <listitem>
+	      <para>
+			Multiple files only: Switch to the next file after the given 
+			number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been
+			captured. 
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Next file every n minute(s)</command></term>
+	    <listitem>
+	      <para>
+			Multiple files only: Switch to the next file after the given 
+			number of second(s)/minutes(s)/hours(s)/days(s) have elapsed.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Ring buffer with n files</command></term>
+	    <listitem>
+	      <para>
+			Multiple files only: Form a ring buffer of the capture files, with 
+			the given number of files.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>Stop capture after n file(s)</command></term>
+	    <listitem>
+	      <para>
+			Multiple files only: Stop capturing after switching to the next 
+			file the given number of times.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</section>
+	<section><title>Stop Capture... frame</title>
+	<variablelist>	  
+	  <varlistentry><term><command>... after n packet(s)</command></term>
+	    <listitem>
+	      <para>
+			Stop capturing after the given number of packets have been
+			captured.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>... after n megabytes(s)</command></term>
+	    <listitem>
+	      <para>
+			Stop capturing after the given number of 
+			byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured.
+			This option is greyed out, if "Use multiple files" is selected.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry><term><command>... after n minute(s)</command></term>
+	    <listitem>
+	      <para>
+			Stop capturing after the given number of 
+			second(s)/minutes(s)/hours(s)/days(s) have elapsed.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</section>
+	<section><title>Display Options frame</title>
+	<variablelist>	  
+	  <varlistentry>
+	    <term>
+	      <command>Update list of packets in real time</command>
+	    </term>
+	    <listitem>
+	      <para>
+		This option allows you to specify that Ethereal 
+		should update the packet list pane in real time. If you 
+		do not specify this, Ethereal does not display any 
+		packets until you stop the capture. When you check this,
+		Ethereal captures in a separate process 
+		and feeds the captures to the display process.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>
+	      <command>Automatic scrolling in live capture</command>
+	    </term>
+	    <listitem>
+	      <para>
+		This option allows you to specify that Ethereal 
+		should scroll the packet list pane as new packets come 
+		in, so you are always looking at the last packet.  If you 
+		do not specify this, Ethereal simply adds new packets onto 
+		the end of the list, but does not scroll the packet list 
+		pane. This option is greyed out if 
+		"Update list of packets in real time" is disabled.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term>
+	      <command>Hide capture info dialog</command>
+	    </term>
+	    <listitem>
+	      <para>
+		If this option is checked, the following capture info dialog will be 
+		hidden.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</section>
+	<section><title>Name Resolution frame</title>
+	<variablelist>	  
+	  <varlistentry>
+	    <term><command>Enable MAC name resolution</command></term>
+	    <listitem>
+	      <para>
+		This option allows you to control whether or not 
+		Ethereal translates MAC addresses into names, see 
+		<xref linkend="ChAdvNameResolutionSection"/>.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><command>Enable network name resolution</command></term>
+	    <listitem>
+	      <para>
+		This option allows you to control whether or not 
+		Ethereal translates network addresses into names, see
+		<xref linkend="ChAdvNameResolutionSection"/>.
+	      </para>  
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><command>Enable transport name resolution</command></term>
+	    <listitem>
+	      <para>
+		This option allows you to control whether or not 
+		Ethereal translates transport addresses into protocols, see
+		<xref linkend="ChAdvNameResolutionSection"/>.
+	      </para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</section>
+	<section><title>Buttons</title>
+      <para>
+	Once you have set the values you desire and have selected the 
+	options you need, simply click on <command>OK</command> to commence the 
+	capture, or <command>Cancel</command> to cancel the capture.
+      </para>
+      <para>
+	If you start a capture, Ethereal allows you to stop capturing when 
+	you have enough packets captured, for details see
+		<xref linkend="ChCapRunningSection"/>.
+      </para>
+    </section>
+    </section>
+	
+    <section id="ChCapCaptureFiles"><title>Capture files and file modes</title>
+	<para>
+	While capturing, the underlying libpcap capturing engine will grab the 
+	packets from the network card and keep the packet data in a (relatively) 
+	small kernel buffer. This data is read by Wireshark and saved into 
+	the capture file(s) the user specified.
+	</para>
+
+	<para>
+	Different modes of operation are available when saving this packet data to 
+	the capture file(s).
+	</para>
+	
+	<tip><title>Tip!</title>
+	<para>
+	Working with large files (several 100 MB's) can be quite slow. If you plan 
+	to do a long term capture or capturing from a high traffic network, think 
+	about using one of the "Multiple files" options. This  will spread the 
+	captured packets over several smaller files which can be much more 
+	pleasant to work with.
+	</para>
+	</tip>
+	<note><title>Note!</title>
+	<para>
+	Using Multiple files may cut context related information.
+	Ethereal keeps context information of the loaded packet data, so it can 
+	report context related problems (like a stream error) and keeps information
+	about context related protocols (e.g. where data is exchanged at the 
+	establishing phase and only referred to in later packets). 
+	As it keeps this information only for the loaded file, using one of 
+	the multiple file modes may cut these contexts. If the establishing phase 
+	is saved in one file and the things you would like to see is in another, 
+	you might not see some of the valuable context related information.
+	</para>
+	</note>
+	<tip><title>Tip!</title>
+	<para>
+	Information about the folders used for the capture file(s), can be found 
+	in <xref linkend="AppFiles"/>. 
+	</para>
+	</tip>
+	
+    <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title>
+      <tgroup cols="5">
+	<colspec colnum="1" colwidth="72pt"/>
+	  <colspec colnum="2" colwidth="80pt"/>
+	  <colspec colnum="3" colwidth="80pt"/>
+	  <colspec colnum="4" colwidth="80pt"/>
+	    <thead>
+	      <row>
+		<entry>"File" option</entry>
+		<entry>"Use multiple files" option</entry>
+		<entry>"Ring buffer with n files" option</entry>
+		<entry>Mode</entry>
+		<entry>Resulting filename(s) used</entry>
+	      </row>
+	    </thead>
+	    <tbody>
+	      <row>
+		<entry>-</entry>
+		<entry>-</entry>
+		<entry>-</entry>
+		<entry><command>Single temporary file</command></entry>
+		<entry>etherXXXXXX (where XXXXXX is a unique number)</entry>
+	      </row>
+	      <row>
+		<entry>foo.cap</entry>
+		<entry>-</entry>
+		<entry>-</entry>
+		<entry><command>Single named file</command></entry>
+		<entry>foo.cap</entry>
+	      </row>
+	      <row>
+		<entry>foo.cap</entry>
+		<entry>x</entry>
+		<entry>-</entry>
+		<entry><command>Multiple files, continuous</command></entry>
+		<entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
+	      </row>
+	      <row>
+		<entry>foo.cap</entry>
+		<entry>x</entry>
+		<entry>x</entry>
+		<entry><command>Multiple files, ring buffer</command></entry>
+		<entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
+	      </row>
+	    </tbody>
+      </tgroup>
+    </table>
+	<variablelist>
+	  <varlistentry>
+	    <term><command>Single temporary file</command></term>
+	    <listitem>
+	<para>
+	A temporary file will be created and used (this is the default). After the 
+	capturing is stopped, this file can be saved later under a user specified 
+	name.
+	</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><command>Single named file</command></term>
+	    <listitem>
+	<para>
+	A single capture file will be used. If you want to place the new capture 
+	file to a specific folder, choose this mode.
+	</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><command>Multiple files, continuous</command></term>
+	    <listitem>
+	<para>
+	Like the "Single named file" mode, but a new file is created and used, 
+	after reaching one of the multiple file switch conditions (one of the 
+	"Next file every ..." values).
+	</para>
+	    </listitem>
+	  </varlistentry>
+	  <varlistentry>
+	    <term><command>Multiple files, ring buffer</command></term>
+	    <listitem>
+	<para>
+	Much like "Multiple files continuous", reaching one of the multiple files 
+	switch conditions (one of the "Next file every ..." values) will switch 
+	to the next file. This will be a newly created file if value of "Ring 
+	buffer with n files" is not reached, otherwise it will replace the oldest 
+	of the formerly used files (thus forming a "ring").
+	</para>
+	<para>
+	This mode will limit the maximum disk usage, even for an unlimited amount of 
+	capture input data, keeping the latest captured data.
+	</para>
+	    </listitem>
+	  </varlistentry>
+	</variablelist>
+	</section>
+
+  <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title>
+	<para>
+	In the usual case, you won't have to choose this link-layer header type. 
+	The following paragraphs describe the exceptional cases, where
+	selecting this type is possible, so you will have a guide what to do:
+	</para>
+    <para>
+    If you are capturing on an 802.11 device on some versions of BSD, this 
+	might offer a choice of "Ethernet" or "802.11".  "Ethernet" will cause 
+	the captured packets to have fake Ethernet headers; "802.11" will cause 
+	them to have IEEE 802.11 headers.  Unless the capture needs to be read by 
+	an application that doesn't support 802.11 headers, you should select 
+	"802.11".
+	</para>
+	<para>
+    If you are capturing on an Endace DAG card connected to a synchronous 
+	serial line, this might offer a choice of "PPP over serial" or 
+	"Cisco HDLC"; if the protocol on the serial line is PPP, select 
+	"PPP over serial", and if the protocol on the serial line is Cisco HDLC, 
+	select "Cisco HDLC".
+	</para>
+	<para>
+    If you are capturing on an Endace DAG card connected to an ATM network, 
+	this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM".  
+	If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if 
+	the capture needs to be read by an application that doesn't support SunATM 
+	headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM".
+	</para>
+	<para>
+    If you are capturing on an Ethernet device, this might offer a choice of 
+	"Ethernet" or "DOCSIS".  If you are capturing traffic from a Cisco Cable 
+	Modem Termination System that is putting DOCSIS traffic onto the Ethernet 
+	to be captured, select "DOCSIS", otherwise select "Ethernet".
+    </para>
+  </section>
+
+  <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title>
+    <para>
+      Ethereal uses the libpcap filter language for capture filters. 
+      This is explained in the tcpdump man page, which can be hard to 
+	  understand, so it's explained here to some extent.
+    </para>
+    <tip>
+      <title>Tip!</title>
+      <para>
+	  You will find a lot of Capture Filter examples at <ulink 
+	  url="&EtherealWikiCaptureFiltersPage;">&EtherealWikiCaptureFiltersPage;</ulink>.
+      </para>
+    </tip>
+    <para>
+      You enter the capture filter into the Filter field of the Wireshark 
+      Capture Options dialog box, as shown in 
+      <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline 
+	  of the syntax of the <command>tcpdump</command> capture filter language. 
+	  See the expression option at the tcpdump manual page for details:
+	  <ulink url="&TcpdumpManpage;"/>.
+    </para>
+    <para>
+      A capture filter takes the form of a series of primitive expressions 
+      connected by conjunctions (<command>and/or</command>) and optionally 
+      preceded by <command>not</command>:
+      <programlisting>
+[not] <command>primitive</command> [and|or [not] <command>primitive</command> ...]
+      </programlisting>
+      An example is shown in <xref linkend="ChCapExFilt1"/>.
+
+      <example id="ChCapExFilt1">
+	<title>
+	  A capture filter for telnet than captures traffic to and from a 
+	  particular host
+	</title>
+	<programlisting>
+tcp port 23 and host 10.0.0.5
+	</programlisting>
+      </example>
+      This example captures telnet traffic to and from the host 
+      10.0.0.5, and shows how to use two primitives and the 
+      <command>and</command> conjunction.  Another example is shown in 
+      <xref linkend="ChCapExFilt2"/>, and shows how to capture all 
+	telnet traffic except that from 10.0.0.5.
+	<example id="ChCapExFilt2">
+	  <title>
+	    Capturing all telnet traffic not from 10.0.0.5</title>
+	  <programlisting>
+tcp port 23 and not host 10.0.0.5
+	  </programlisting>
+	</example>
+      </para>
+
+      <para>
+	  XXX - add examples to the following list.
+      </para>
+      <para>
+      A primitive is simply one of the following:
+      <variablelist>
+	<varlistentry>
+	  <term><command>[src|dst] host &lt;host></command></term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on a host IP 
+	      address or name. You can optionally precede the 
+	      primitive with the keyword <command>src|dst</command> 
+	      to specify that you are only interested in source or 
+	      destination addresses. If these are not present, 
+	      packets where the specified address appears as either 
+	      the source or the destination address will be selected.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <command>ether [src|dst] host &lt;ehost></command>
+	  </term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on Ethernet host 
+	      addresses. You can optionally include the keyword 
+	      <command>src|dst</command> between the keywords 
+	      <command>ether</command> and <command>host</command> 
+	      to specify that you are only interested in source 
+	      or destination addresses.  If these are not present, 
+	      packets where the specified address appears in either 
+	      the source or destination address will be selected.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><command>gateway host &lt;host></command></term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on packets that 
+	      used <command>host</command> as a gateway. That is, where 
+	      the Ethernet source or destination was 
+	      <command>host</command> but neither the source nor 
+	      destination IP address was <command>host</command>.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <command>
+	      [src|dst] net &lt;net> [{mask &lt;mask>}|{len &lt;len>}]
+	    </command>
+	  </term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on network numbers. 
+	      You can optionally precede this primitive with the 
+	      keyword <command>src|dst</command> to specify that you 
+	      are only interested in a source or destination network. 
+	      If neither of these are present, packets will be 
+	      selected that have the specified network in either the
+	      source or destination address.  In addition, you can 
+	      specify either the netmask or the CIDR prefix for the 
+	      network if they are different from your own. 
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>
+	    <command>[tcp|udp] [src|dst] port &lt;port></command>
+	  </term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on TCP and UDP port 
+	      numbers. You can optionally precede this primitive with 
+	      the keywords <command>src|dst</command> and 
+	      <command>tcp|udp</command> which allow you to specify 
+	      that you are only interested in source or destination 
+	      ports and TCP or UDP packets respectively.  The 
+	      keywords <command>tcp|udp</command> must appear before 
+	      <command>src|dst</command>.
+	    </para>
+	    <para>
+	      If these are not specified, packets will be selected 
+	      for both the TCP and UDP protocols and when the 
+	      specified address appears in either the source or 
+	      destination port field.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><command>less|greater &lt;length></command></term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on packets whose 
+	      length was less than or equal to the specified length, 
+	      or greater than or equal to the specified length, 
+	      respectively.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><command>ip|ether proto &lt;protocol></command></term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on the specified 
+	      protocol at either the Ethernet layer or the IP layer.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><command>ether|ip broadcast|multicast</command></term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to filter on either 
+	      Ethernet or IP broadcasts or multicasts.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term><command>&lt;expr> relop &lt;expr></command></term>
+	  <listitem>
+	    <para>
+	      This primitive allows you to create complex filter 
+	      expressions that select bytes or ranges of bytes in 
+	      packets.  Please see the tcpdump man page at
+		  <ulink url="&TcpdumpManpage;"/> for more details.
+	    </para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </para>
+  </section>
+
+  <section id="ChCapRunningSection"><title>While a Capture is running ...</title>
+    <para>
+	While a capture is running, the following dialog box is shown:
+      <figure id="ChCapCaptureInfoDialog">
+	<title>The "Capture Info" dialog box</title>
+	<graphic entityref="EtherealCaptureInfoDialog" format="JPG"/>
+      </figure>
+	This dialog box will inform you about the number of captured packets and 
+	the time since the capture was started. The selection which protocols
+	are counted cannot be changed.
+	</para>
+	  <tip><title>Tip!</title>
+	  <para>
+	  This Capture Info dialog box can be hidden, using the "Hide capture info 
+	  dialog" option in the Capture Options dialog box.
+	  </para>
+	  </tip>
+	<section id="ChCapStopSection"><title>Stop the running capture</title>
+    <para>
+      A running capture session will be stopped in one of the following ways:
+      <orderedlist>
+	<listitem>
+	  <para>Using the 
+	  "<inlinegraphic entityref="EtherealToolbarStop" format="PNG"/>
+	  Stop" button from the <command>Capture Info dialog box
+	  </command>.
+	  </para>
+	  <note><title>Note!</title>
+	  <para>
+	  The Capture Info dialog box might be hidden, if the option "Hide capture 
+	  info dialog" is used.
+	  </para>
+	  </note>
+	</listitem>
+	<listitem>
+	  <para>Using the <command>menu item</command>
+	  "Capture/<inlinegraphic entityref="EtherealToolbarCaptureStop" format="PNG"/>
+	  Stop". 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Using the <command>toolbar item</command>
+	  "<inlinegraphic entityref="EtherealToolbarCaptureStop" format="PNG"/>
+	  Stop". 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Pressing the accelerator keys: <command>Ctrl+E</command>. 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>The capture will be automatically stopped, if one of the 
+	  <command>Stop Conditions</command> is exceeded, e.g. the maximum amount 
+	  of data was captured.
+	  </para>
+	</listitem>
+      </orderedlist>
+    </para>
+    </section>
+	<section id="ChCapRestartSection"><title>Restart a running capture</title>
+    <para>
+      A running capture session can be restarted with the same capture options 
+	  than the last time, this will remove all packets previously captured.
+	  This can be useful, if some uninteresting packets are captured and 
+	  there's no need to keep them.
+    </para>
+    <para>	  
+	  Restart is a convenience function and 
+	  equivalent to a capture stop following by an immediate capture start. 
+	  A restart can be triggered in one of the following ways:
+      <orderedlist>
+	<listitem>
+	  <para>Using the <command>menu item</command>
+	  "Capture/<inlinegraphic entityref="EtherealToolbarCaptureRestart" format="PNG"/>
+	  Restart". 
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>Using the <command>toolbar item</command> 
+	  "<inlinegraphic entityref="EtherealToolbarCaptureRestart" format="PNG"/>
+	  Restart". 
+	  </para>
+	</listitem>
+      </orderedlist>
+    </para>
+    </section>
+    </section>
+
+</chapter>
+<!-- End of WSUG Chapter Capture -->
+