forked from osmocom/wireshark
1576 lines
59 KiB
XML
1576 lines
59 KiB
XML
<!-- WSUG Chapter Capture -->
|
|
|
|
<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 Wireshark.
|
|
</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 Wireshark keeps 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>
|
|
<listitem><para>
|
|
Simultaneous capturing from multiple network interfaces.
|
|
</para></listitem>
|
|
</itemizedlist>
|
|
The capture engine still lacks the following features:
|
|
<itemizedlist>
|
|
<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 Wireshark 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="&WiresharkWikiPage;/CaptureSetup">&WiresharkWikiPage;/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
|
|
Wireshark:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
You can get an overview of the available local interfaces using the
|
|
"<inlinegraphic entityref="WiresharkToolbarCaptureInterfaces" format="PNG"/>
|
|
Capture Interfaces" dialog box, see
|
|
<xref linkend="ChCapCaptureInterfacesDialogWin32"/> or
|
|
<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="WiresharkToolbarCaptureOptions" 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="WiresharkToolbarCaptureStart" 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
|
|
Wireshark from the command line and use the following:
|
|
<programlisting>
|
|
wireshark -i eth0 -k
|
|
</programlisting>
|
|
This will start Wireshark 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, Wireshark pops
|
|
up the "Capture Interfaces" dialog box as shown in
|
|
<xref linkend="ChCapCaptureInterfacesDialogWin32"/> or
|
|
<xref linkend="ChCapCaptureInterfacesDialog"/>.
|
|
<warning><title>This dialog consumes lots of system resources!</title>
|
|
<para>
|
|
As the "Capture Interfaces" dialog is showing live captured data, it is
|
|
consuming a lot of system resources. Close this dialog as soon as
|
|
possible to prevent excessive system load.
|
|
</para>
|
|
</warning>
|
|
<note><title>Not all available interfaces may be displayed!</title>
|
|
<para>
|
|
This dialog box will only show the local interfaces Wireshark knows
|
|
of. It will not show interfaces marked as hidden in <xref linkend="ChCustInterfaceOptionsSection"/>.
|
|
As Wireshark 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>
|
|
</para>
|
|
<para>
|
|
As it is possible to simultaneously capture packets from multiple interfaces,
|
|
the toggle buttons can be used to select one or more interfaces.
|
|
</para>
|
|
<figure id="ChCapCaptureInterfacesDialogWin32">
|
|
<title>The "Capture Interfaces" dialog box on Microsoft Windows</title>
|
|
<graphic entityref="WiresharkCaptureInterfacesDialogWin32" format="PNG"/>
|
|
</figure>
|
|
<figure id="ChCapCaptureInterfacesDialog">
|
|
<title>The "Capture Interfaces" dialog box on Unix/Linux</title>
|
|
<graphic entityref="WiresharkCaptureInterfacesDialog" format="PNG"/>
|
|
</figure>
|
|
<variablelist>
|
|
<varlistentry><term><command>Device (Unix/Linux only)</command></term>
|
|
<listitem>
|
|
<para>
|
|
The interface device name.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Description</command></term>
|
|
<listitem>
|
|
<para>
|
|
The interface description provided by the operating system, or the
|
|
user defined comment added in <xref linkend="ChCustInterfaceOptionsSection"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>IP</command></term>
|
|
<listitem>
|
|
<para>
|
|
The first IP address Wireshark could find for this interface.
|
|
You can click on the address to cycle through other addresses
|
|
assigned to it, if available.
|
|
If no address could be found "none" will be displayed.
|
|
</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>Start</command></term>
|
|
<listitem>
|
|
<para>
|
|
Start a capture on all selected interfaces immediately, using the settings
|
|
from the last capture or the default settings, if no options have been
|
|
set.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Options</command></term>
|
|
<listitem>
|
|
<para>
|
|
Open the Capture Options dialog with the marked interfaces selected, see
|
|
<xref linkend="ChCapCaptureOptions"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Details (Microsoft Windows only)</command></term>
|
|
<listitem>
|
|
<para>
|
|
Open a dialog with detailed information about the interface, see
|
|
<xref linkend="ChCapInterfaceDetailsSection"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Help</command></term>
|
|
<listitem>
|
|
<para>
|
|
Show this help page.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Close</command></term>
|
|
<listitem>
|
|
<para>
|
|
Close this dialog box.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="ChCapCaptureOptions">
|
|
<title>The "Capture Options" dialog box</title>
|
|
<para>
|
|
When you select Options... from the Capture menu (or use the corresponding
|
|
item in the "Main" toolbar), Wireshark 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="WiresharkCaptureOptionsDialog"/>
|
|
</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>
|
|
<section><title>Capture frame</title>
|
|
<para>
|
|
The table shows the settings for all available interfaces:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
The name of the interface and its IP addresses. If no address could
|
|
be resolved from the system, "none" will be shown.
|
|
</para>
|
|
<note>
|
|
<title>Note</title>
|
|
<para>loopback interfaces are not available on Windows platforms.</para>
|
|
</note>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The link-layer header type.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The information whether promicuous mode is enabled or disabled.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The maximum amount of data that will be captured for each packet.
|
|
The default value is set to the 65535 bytes.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The size of the kernel buffer that is reserved to keep the captured packets.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The information whether packets will be captured in monitor mode (Unix/Linux only).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The chosen capture filter.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
By marking the
|
|
checkboxes in the first column the interfaces are selected to be
|
|
captured from. By double-clicking on an interface the "Edit Interface Settings"
|
|
dialog box as shown in
|
|
<xref linkend="ChCapEditInterfacesSettingsDialog"/> will be opened.
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
<command>Capture on all interfaces</command>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
As Wireshark can capture on multiple interfaces, it is possible to choose to capture on all available interfaces.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>Capture all packets in promiscuous mode</command>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This checkbox allows you to specify that Wireshark
|
|
should put all interfaces in promiscuous mode when capturing.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Capture Filter</command></term>
|
|
<listitem>
|
|
<para>
|
|
This field allows you to specify a capture filter for all interfaces
|
|
that are currently selected. Once a filter has been entered in this field,
|
|
the newly selected interfaces will inherit the 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 labeled "Capture Filter", and Wireshark
|
|
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>
|
|
<varlistentry><term><command>Compile selected BPFs</command></term>
|
|
<listitem>
|
|
<para>
|
|
This button allows you to compile the capture filter into BPF code and
|
|
pop up a window showing you the resulting pseudo code. This can help in
|
|
understanding the working of the capture filter you created.
|
|
The "Compile selected BPFs" button leads you to
|
|
<xref linkend="ChCapCompileSelectedBpfsDialog"/>.
|
|
</para>
|
|
<tip><title>Tip!</title>
|
|
<para>
|
|
The execution of BPFs can be sped up on Linux by turning on BPF JIT by
|
|
executing <programlisting>echo 1 >/proc/sys/net/core/bpf_jit_enable</programlisting>
|
|
if it is not enabled already. To make the change persistent you can use sysfsutils
|
|
<ulink url="&SysFsUtils;">sysfsutils</ulink>.
|
|
</para>
|
|
</tip>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>Manage Interfaces</command>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The "Manage Interfaces" button leads you to
|
|
<xref linkend="ChCapManageInterfacesDialog"/> where pipes can be defined,
|
|
local interfaces scanned or hidden, or remote interfaces added (Windows only).
|
|
</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, Wireshark will automatically switch
|
|
to a new one, if a specific trigger condition is reached.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>Use pcap-ng format</command>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This checkbox allows you to specify that Wireshark saves the captured
|
|
packets in pcap-ng format. This next generation capture file format is
|
|
currently in development. If more than one interface is chosen for
|
|
capturing, this checkbox is set by default. See
|
|
<ulink url="&WiresharkWikiPcapNgPage;"/> for more details on pcap-ng.
|
|
</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 Wireshark
|
|
should update the packet list pane in real time. If you
|
|
do not specify this, Wireshark does not display any
|
|
packets until you stop the capture. When you check this,
|
|
Wireshark 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 Wireshark
|
|
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, Wireshark 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 capture info dialog described in
|
|
<xref linkend="ChCapRunningSection"/> 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
|
|
Wireshark 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
|
|
Wireshark 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
|
|
Wireshark 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>Start</command> to commence the
|
|
capture, or <command>Cancel</command> to cancel the capture.
|
|
</para>
|
|
<para>
|
|
If you start a capture, Wireshark allows you to stop capturing when
|
|
you have enough packets captured, for details see
|
|
<xref linkend="ChCapRunningSection"/>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="ChCapEditInterfaceSettingsSection">
|
|
<title>The "Edit Interface Settings" dialog box</title>
|
|
<para>
|
|
If you double-click on an interface in <xref linkend="ChCapCaptureOptionsDialog"/>
|
|
the following dialog box pops up.
|
|
</para>
|
|
<figure id="ChCapEditInterfacesSettingsDialog">
|
|
<title>The "Edit Interface Settings" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureEditInterfacesSettingsDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
You can set the following fields in this dialog box:
|
|
</para>
|
|
<variablelist>
|
|
<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, "none" 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>Wireless settings (Windows only)</command></term>
|
|
<listitem>
|
|
<para>
|
|
Here you can set the settings for wireless capture using the AirPCap adapter.
|
|
For a detailed description, see the AirPCap Users Guide.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Remote settings (Windows only)</command></term>
|
|
<listitem>
|
|
<para>
|
|
Here you can set the settings for remote capture.
|
|
For a detailed description, see <xref linkend="ChCapInterfaceRemoteSection"/>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>Capture packets in promiscuous mode</command>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This checkbox allows you to specify that Wireshark
|
|
should put the interface in promiscuous mode when capturing.
|
|
If you do not specify this, Wireshark 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="&WiresharkFAQPromiscPage;"/> 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 value is set to the maximum 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>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>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>
|
|
<command>Capture packets in monitor mode (Unix/Linux only)</command>
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This checkbox allows you to setup the Wireless interface to capture
|
|
all traffic it can receive, not just the traffic on the BSS to which
|
|
it is associated, which can happen even when you set promiscuous mode.
|
|
Also it might be necessary to turn this option on in order to see
|
|
IEEE 802.11 headers and/or radio information from the captured frames.
|
|
</para>
|
|
<note>
|
|
<title>Note</title>
|
|
<para>
|
|
In monitor mode the adapter might disassociate itself from the network
|
|
it was associated to.
|
|
</para>
|
|
</note>
|
|
</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 labeled "Capture Filter", and Wireshark
|
|
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>
|
|
<varlistentry><term><command>Compile BPF</command></term>
|
|
<listitem>
|
|
<para>
|
|
This button allows you to compile the capture filter into BPF code and
|
|
pop up a window showing you the resulting pseudo code. This can help in
|
|
understanding the working of the capture filter you created.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="ChCapCompileSelectedBpfsSection">
|
|
<title>The "Compile Results" dialog box</title>
|
|
<para>
|
|
This figure shows the compile results of the selected interfaces.
|
|
</para>
|
|
<figure id="ChCapCompileSelectedBpfsDialog">
|
|
<title>The "Compile Results" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureCompileSelectedBPFsDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
In the left window the interface names are listed. A green bullet indicates a successful
|
|
compilation, a red bullet a failure. The results of an individual interface are shown
|
|
in the right window, when it is selected.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="ChCapManageInterfacesSection">
|
|
<title>The "Add New Interfaces" dialog box</title>
|
|
<para>
|
|
As a central point to manage interfaces this dialog box consists of three tabs
|
|
to add or remove interfaces.
|
|
</para>
|
|
<figure id="ChCapManageInterfacesDialog">
|
|
<title>The "Add New Interfaces" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureManageInterfacesDialog" format="PNG"/>
|
|
</figure>
|
|
<section>
|
|
<title>Add or remove pipes</title>
|
|
<figure id="ChCapManageInterfacesPipesDialog">
|
|
<title>The "Add New Interfaces - Pipes" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureManageInterfacesPipesDialog" format="PNG"/>
|
|
</figure>
|
|
<para>To successfully add a pipe, this pipe must have already been created.
|
|
Click the "New" button and type the name of the pipe including its path.
|
|
Alternatively, the "Browse" button can be used to locate the pipe.
|
|
With the "Save" button the pipe is added to the list of available interfaces.
|
|
Afterwards, other pipes can be added.
|
|
</para>
|
|
<para>
|
|
To remove a pipe from the list of interfaces it first has to be selected. Then
|
|
click the "Delete" button.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Add or hide local interfaces</title>
|
|
<figure id="ChCapManageInterfacesLocalDialog">
|
|
<title>The "Add New Interfaces - Local Interfaces" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureManageInterfacesLocalDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
The tab "Local Interfaces" contains a list of available local interfaces, including
|
|
the hidden ones, which are not shown in the other lists.
|
|
</para>
|
|
<para>
|
|
If a new local interface is added, for example, a wireless interface has been
|
|
activated, it is not automatically added to the list to prevent the constant scanning
|
|
for a change in the list of available interfaces. To renew the list a rescan can be done.
|
|
</para>
|
|
<para>
|
|
One way to hide an interface is to change the preferences. If the "Hide" checkbox
|
|
is activated and the "Apply" button clicked, the interface will not be seen in the
|
|
lists of the "Capture Options" or "Capture Interfaces" dialog box any more. The changes
|
|
are also saved in the "Preferences" file.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Add or hide remote interfaces</title>
|
|
<figure id="ChCapManageInterfacesRemoteDialog">
|
|
<title>The "Add New Interfaces - Remote Interfaces" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureManageInterfacesRemoteDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
In this tab interfaces on remote hosts can be added. One or more of these
|
|
interfaces can be hidden. In contrast to the local interfaces they are not
|
|
saved in the "Preferences" file.
|
|
</para>
|
|
<para>
|
|
To remove a host including all its interfaces from the list, it has to be
|
|
selected. Then click the "Delete" button.
|
|
</para>
|
|
<para>
|
|
For a detailed description, see <xref linkend="ChCapInterfaceRemoteSection"/>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="ChCapInterfaceRemoteSection">
|
|
<title>The "Remote Capture Interfaces" dialog box</title>
|
|
<para>
|
|
Besides doing capture on local interfaces Wireshark is capable of
|
|
reaching out across the network to a so called capture daemon or service
|
|
processes to receive captured data from.
|
|
</para>
|
|
<note><title>Microsoft Windows only</title>
|
|
<para>
|
|
This dialog and capability is only available on Microsoft Windows. On
|
|
Linux/Unix you can achieve the same effect (securely) through an SSH
|
|
tunnel.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
The Remote Packet Capture Protocol service must first be running on the
|
|
target platform before Wireshark can connect to it. The easiest way is
|
|
to install WinPcap from <ulink url="&WinPcapDownloadWebsite;"/> on the
|
|
target. Once installation is completed go to the Services control panel,
|
|
find the Remote Packet Capture Protocol service and start it.
|
|
</para>
|
|
<note><title>Note</title>
|
|
<para>
|
|
Make sure you have outside access to port 2002 on the target platform.
|
|
This is the port where the Remote Packet Capture Protocol service can
|
|
be reached, by default.
|
|
</para>
|
|
</note>
|
|
<para>
|
|
To access the Remote Capture Interfaces dialog use the
|
|
"Add New Interfaces - Remote" dialog, see
|
|
<xref linkend="ChCapManageInterfacesRemoteDialog"/>, and select "Add".
|
|
</para>
|
|
<section><title>Remote Capture Interfaces</title>
|
|
<figure id="ChCapInterfaceRemoteDialog">
|
|
<title>The "Remote Capture Interfaces" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureOptionsRemoteInterfacesDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
You have to set the following parameter in this dialog:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry><term><command>Host</command></term>
|
|
<listitem>
|
|
<para>
|
|
Enter the IP address or host name of the target platform where the
|
|
Remote Packet Capture Protocol service is listening. The drop down list
|
|
contains the hosts that have previously been successfully contacted.
|
|
The list can be emptied by choosing "Clear list" from the drop down list.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Port</command></term>
|
|
<listitem>
|
|
<para>
|
|
Set the port number where the Remote Packet Capture Protocol service
|
|
is listening on. Leave open to use the default port (2002).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Null authentication</command></term>
|
|
<listitem>
|
|
<para>
|
|
Select this if you don't need authentication to take place for a
|
|
remote capture to be started. This depends on the target platform.
|
|
Configuring the target platform like this makes it insecure.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Password authentication</command></term>
|
|
<listitem>
|
|
<para>
|
|
This is the normal way of connecting to a target platform. Set the
|
|
credentials needed to connect to the Remote Packet Capture Protocol
|
|
service.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
<!-- <section><title>Remote Capture</title>
|
|
<para>
|
|
When the connection to the Remote Packet Capture Protocol service is
|
|
successfully established the "Capture Options" dialog looks like this,
|
|
see <xref linkend="ChCapInterfaceRemoteCapDialog"/>.
|
|
</para>
|
|
<figure id="ChCapInterfaceRemoteCapDialog">
|
|
<title>The "Remote Capture" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureOptionsRemoteCaptureDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
The Interface dropdown list now shows the IP address or host name of the
|
|
Remote Packet Capture Protocol service and the other field shows the
|
|
interfaces on the remote target. After selecting the desired interface
|
|
just click <command>Start</command> to start the remote capture.
|
|
</para>
|
|
</section> -->
|
|
<section><title>Remote Capture Settings</title>
|
|
<para>
|
|
The remote capture can be further fine tuned to match your situation.
|
|
The <command>Remote Settings</command> button in
|
|
<xref linkend="ChCapEditInterfacesSettingsDialog"/> gives you this option.
|
|
It pops up the dialog shown in
|
|
<xref linkend="ChCapInterfaceRemoteSettingsDialog"/>.
|
|
</para>
|
|
<figure id="ChCapInterfaceRemoteSettingsDialog">
|
|
<title>The "Remote Capture Settings" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureOptionsRemoteSettingsDialog" format="PNG"/>
|
|
</figure>
|
|
<para>
|
|
You can set the following parameters in this dialog:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry><term><command>Do not capture own RPCAP traffic</command></term>
|
|
<listitem>
|
|
<para>
|
|
This option sets a capture filter so that the traffic flowing back
|
|
from the Remote Packet Capture Protocol service to Wireshark isn't
|
|
captured as well and also send back. The recursion in this saturates
|
|
the link with duplicate traffic.
|
|
</para>
|
|
<para>
|
|
You only should switch this off when capturing on an interface other
|
|
then the interface connecting back to Wireshark.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Use UDP for data transfer</command></term>
|
|
<listitem>
|
|
<para>
|
|
Remote capture control and data flows over a TCP connection. This
|
|
option allows you to choose an UDP stream for data transfer.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Sampling option None</command></term>
|
|
<listitem>
|
|
<para>
|
|
This option instructs the Remote Packet Capture Protocol service to
|
|
send back all captured packets which have passed the capture filter.
|
|
This is usually not a problem on a remote capture session with
|
|
sufficient bandwidth.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Sampling option 1 of x packets</command></term>
|
|
<listitem>
|
|
<para>
|
|
This option limits the Remote Packet Capture Protocol service to send
|
|
only a sub sampling of the captured data, in terms of number of
|
|
packets. This allows capture over a narrow band remote capture
|
|
session of a higher bandwidth interface.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry><term><command>Sampling option 1 every x milliseconds</command></term>
|
|
<listitem>
|
|
<para>
|
|
This option limits the Remote Packet Capture Protocol service to send
|
|
only a sub sampling of the captured data, in terms of time. This
|
|
allows capture over a narrow band capture session of a higher
|
|
bandwidth interface.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="ChCapInterfaceDetailsSection">
|
|
<title>The "Interface Details" dialog box</title>
|
|
<para>
|
|
When you select Details from the Capture Interface menu, Wireshark pops
|
|
up the "Interface Details" dialog box as shown in
|
|
<xref linkend="ChCapInterfaceDetailsDialog"/>. This dialog shows various
|
|
characteristics and statistics for the selected interface.
|
|
</para>
|
|
<note><title>Microsoft Windows only</title>
|
|
<para>This dialog is only available on Microsoft Windows</para>
|
|
</note>
|
|
<figure id="ChCapInterfaceDetailsDialog">
|
|
<title>The "Interface Details" dialog box</title>
|
|
<graphic entityref="WiresharkCaptureInterfaceDetailsDialog" format="JPG"/>
|
|
</figure>
|
|
</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.
|
|
Wireshark 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>wiresharkXXXXXX (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_20100205110102.cap, foo_00002_20100205110318.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_20100205110102.cap, foo_00002_20100205110318.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 of 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>
|
|
Wireshark 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="&WiresharkWikiCaptureFiltersPage;">&WiresharkWikiCaptureFiltersPage;</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 that 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 src 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 <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 <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 <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 <net> [{mask <mask>}|{len <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 <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 <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 <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><expr> relop <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 id="ChCapCaptureAutoFilterSection">
|
|
<title>Automatic Remote Traffic Filtering</title>
|
|
<para>
|
|
If Wireshark is running remotely (using e.g. SSH, an exported X11 window,
|
|
a terminal server, ...), the remote content has to be transported over
|
|
the network, adding a lot of (usually unimportant) packets to the actually
|
|
interesting traffic.
|
|
</para>
|
|
<para>
|
|
To avoid this, Wireshark tries to figure out if it's remotely connected
|
|
(by looking at some specific environment variables) and automatically
|
|
creates a capture filter that matches aspects of the connection.
|
|
</para>
|
|
<para>
|
|
The following environment variables are analyzed:
|
|
</para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><command>SSH_CONNECTION</command> (ssh)</term>
|
|
<listitem>
|
|
<para>
|
|
<remote IP> <remote port> <local IP> <local port>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>SSH_CLIENT</command> (ssh)</term>
|
|
<listitem>
|
|
<para>
|
|
<remote IP> <remote port> <local port>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>REMOTEHOST</command> (tcsh, others?)</term>
|
|
<listitem>
|
|
<para>
|
|
<remote name>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><command>DISPLAY</command> (x11)</term>
|
|
<listitem>
|
|
<para>
|
|
[remote name]:<display num>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><command>SESSIONNAME</command> (terminal server)</term>
|
|
<listitem>
|
|
<para>
|
|
<remote name>
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
On Windows it asks the operating system if it's running in a Remote Desktop Services
|
|
environment.
|
|
</para>
|
|
</section>
|
|
</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="WiresharkCaptureInfoDialog" 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 of 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="WiresharkToolbarCaptureStop" 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="WiresharkToolbarCaptureStop" format="PNG"/>
|
|
Stop".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Using the <command>toolbar item</command>
|
|
"<inlinegraphic entityref="WiresharkToolbarCaptureStop" 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
|
|
as 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="WiresharkToolbarCaptureRestart" format="PNG"/>
|
|
Restart".
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Using the <command>toolbar item</command>
|
|
"<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
|
|
Restart".
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
</chapter>
|
|
<!-- End of WSUG Chapter Capture -->
|
|
|
|
|