forked from osmocom/wireshark
WSUG: Convert the "Capturing" chapter to AsciiDoc.
Leave most of the content intact for now. Add a section on markup conventions to README.txt. Remove the .mediaobject border. Change-Id: I06cfd482a4c8ea63c90b9f59fcdf2afaf636a4a2 Reviewed-on: https://code.wireshark.org/review/3821 Reviewed-by: Gerald Combs <gerald@wireshark.org>
This commit is contained in:
parent
d3728738dd
commit
a84937198b
|
@ -94,11 +94,40 @@ rename it to jimi-1.0.jar.
|
|||
|
||||
AsciiDoc
|
||||
--------
|
||||
Text documentation format and conversion suite:
|
||||
http://asciidoc.org/. AsciiDoc can use either w3m (default) or Lynx
|
||||
for plain text output. We use AsciiDoc for the Developer's Guide and
|
||||
for the release notes; Lynx as well is used for the official plaintext
|
||||
release announcments.
|
||||
Text documentation format and conversion suite: http://asciidoc.org/. AsciiDoc
|
||||
can use either w3m (default) or Lynx for plain text output. We use AsciiDoc for
|
||||
the Developer's Guide, User's Guide, and for the release notes. Lynx is used to
|
||||
render the official plaintext release announcments.
|
||||
|
||||
The AsciiDoc files have been converted from DocBook. In a lot of cases the
|
||||
markup is wrong, inconsistent, or both. Use the following markup conventions
|
||||
for any new or revised text:
|
||||
|
||||
- Window and dialog box names should be in ``curly quotes''.
|
||||
|
||||
- Use Asciidoctor compatibility macros for buttons, keys, and menus:
|
||||
|
||||
The button:[Start] button
|
||||
Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
|
||||
Select menu:File[Open] from the main menu.
|
||||
|
||||
This ensures that UI elemnents are shown consistently and lets us apply styles
|
||||
to each type of element.
|
||||
|
||||
- Command line examples should reflect the OS:
|
||||
|
||||
----
|
||||
$ echo Linux and UNIX
|
||||
----
|
||||
|
||||
----
|
||||
C:\> echo Windows
|
||||
----
|
||||
|
||||
Admonitions ([NOTE], [TIP], and [WARNING]) can be used to highlight important
|
||||
information. Keep in mind that they interrupt the flow of text by design. Too
|
||||
many (especially in a row) are distracting and annoying.
|
||||
|
||||
|
||||
Lynx
|
||||
----
|
||||
|
@ -305,4 +334,3 @@ http://www.codeproject.com/KB/winhelp/docbook_howto.aspx
|
|||
FO Parameter Reference
|
||||
by Norman Walsh
|
||||
http://docbook.sourceforge.net/release/xsl/current/doc/fo/
|
||||
|
||||
|
|
|
@ -27,10 +27,13 @@ wireshark-wiki-site:\[\]=http://wiki.wireshark.org/
|
|||
|
||||
tcpdump-web-site:\[\]=http://www.tcpdump.org/
|
||||
tcpdump-man-page-url:\[\]=http://www.tcpdump.org/manpages/tcpdump.1.html
|
||||
pcap-filter-man-page-url:\[\]=http://www.tcpdump.org/manpages/pcap-filter.7.html
|
||||
|
||||
winpcap-web-site:\[\]=http://www.winpcap.org/
|
||||
winpcap-download-page:\[\]=http://www.winpcap.org/install/
|
||||
|
||||
sysfs-web-site:\[\]=http://linux-diag.sourceforge.net/Sysfsutils.html
|
||||
|
||||
# Make a document attribute after we fully convert to AsciiDoc
|
||||
wsdg-author-email:\[\]=ulf.lamping[AT]web.de
|
||||
|
||||
|
|
|
@ -276,10 +276,6 @@ div.table thead > tr > th, div.informaltable thead > tr > th {
|
|||
vertical-align: bottom;
|
||||
}
|
||||
|
||||
div.mediaobject img {
|
||||
border: 1px solid silver;
|
||||
margin-bottom: 0.8em;
|
||||
}
|
||||
div.figure p.title,
|
||||
div.table p.title
|
||||
{
|
||||
|
|
|
@ -0,0 +1,936 @@
|
|||
++++++++++++++++++++++++++++++++++++++
|
||||
<!-- WSUG Chapter Capture -->
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
|
||||
[[ChapterCapture]]
|
||||
|
||||
== Capturing Live Network Data
|
||||
|
||||
[[ChCapIntroduction]]
|
||||
|
||||
=== Introduction
|
||||
|
||||
Capturing live network data is one of the major features of Wireshark.
|
||||
|
||||
The Wireshark capture engine provides the following features:
|
||||
|
||||
* Capture from different kinds of network hardware such as Ethernet or 802.11.
|
||||
|
||||
* Stop the capture on different triggers such as the amount of captured data,
|
||||
elapsed time, or the number of packets.
|
||||
|
||||
* Simultaneously show decoded packets while Wireshark is capturing.
|
||||
|
||||
* Filter packets, reducing the amount of data to be captured. See
|
||||
<<ChCapCaptureFilterSection>>.
|
||||
|
||||
* Save packets in multiple files while doing a long term capture, optionally
|
||||
rotating through a fixed number of files (a ``ringbuffer''). See
|
||||
<<ChCapCaptureFiles>>.
|
||||
|
||||
* Simultaneously capture from multiple network interfaces.
|
||||
|
||||
The capture engine still lacks the following features:
|
||||
|
||||
* Stop capturing (or perform some other action) depending on the captured data.
|
||||
|
||||
[[ChCapPrerequisitesSection]]
|
||||
|
||||
=== Prerequisites
|
||||
|
||||
Setting up Wireshark to capture packets for the first time can be tricky. A
|
||||
comprehensive guide ``How To setup a Capture'' is available at
|
||||
link:wireshark-wiki-site:[]CaptureSetup[wireshark-wiki-site:[]CaptureSetup].
|
||||
|
||||
Here are some common pitfalls:
|
||||
|
||||
* You may need special privileges to start a live capture.
|
||||
|
||||
* You need to choose the right network interface to capture packet data from.
|
||||
|
||||
* You need to capture at the right place in the network to see the traffic you
|
||||
want to see.
|
||||
|
||||
If you have any problems setting up your capture environment you should have a
|
||||
look at the guide mentioned above.
|
||||
|
||||
[[ChCapCapturingSection]]
|
||||
|
||||
=== Start Capturing
|
||||
|
||||
The following methods can be used to start capturing packets with Wireshark:
|
||||
|
||||
* You can double-click on an interface in the main window.
|
||||
|
||||
* You can get an overview of the available interfaces using the ``Capture
|
||||
Interfaces'' dialog box (menu:Capture[Options...]). See
|
||||
<<ChCapCaptureInterfacesDialogWin32>> or <<ChCapCaptureInterfacesDialog>> for
|
||||
more information. You can start a capture from this dialog box using the
|
||||
button:[Start] button.
|
||||
|
||||
* You can immediately start a capture using your current settings by selecting
|
||||
menu:Capture[Start] or by cliking the first toolbar button.
|
||||
|
||||
* If you already know the name of the capture interface you can start Wireshark
|
||||
from the command line:
|
||||
--
|
||||
----
|
||||
$ wireshark -i eth0 -k
|
||||
----
|
||||
--
|
||||
This will start Wireshark capturing on interface eth0. More details can be found
|
||||
at <<ChCustCommandLine>>.
|
||||
|
||||
[[ChCapInterfaceSection]]
|
||||
|
||||
=== The ``Capture Interfaces'' dialog box
|
||||
|
||||
When you select menu:Capture[Options...] from the main menu Wireshark pops up
|
||||
the ``Capture Interfaces'' dialog box as shown in
|
||||
<<ChCapCaptureInterfacesDialogWin32>> or <<ChCapCaptureInterfacesDialog>>.
|
||||
|
||||
// XXX Not sure this is the case any more
|
||||
//[WARNING]
|
||||
//.This dialog consumes lots of system resources
|
||||
//====
|
||||
//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.
|
||||
//====
|
||||
|
||||
[NOTE]
|
||||
.Both you and your OS can hide interfaces
|
||||
====
|
||||
This dialog box will only show the local interfaces Wireshark can access. It
|
||||
will also hide interfaces marked as hidden in <<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.
|
||||
====
|
||||
|
||||
It is possible to select more than one interface and capture from them
|
||||
simultaneously.
|
||||
|
||||
[[ChCapCaptureInterfacesDialogWin32]]
|
||||
|
||||
.The ``Capture Interfaces'' dialog box on Microsoft Windows
|
||||
image::wsug_graphics/ws-capture-interfaces-win32.png[]
|
||||
|
||||
[[ChCapCaptureInterfacesDialog]]
|
||||
|
||||
.The ``Capture Interfaces'' dialog box on Unix/Linux
|
||||
image::wsug_graphics/ws-capture-interfaces.png[]
|
||||
|
||||
_Device (Unix/Linux only)_::
|
||||
The interface device name.
|
||||
|
||||
_Description_::
|
||||
The interface description provided by the operating system, or the user defined
|
||||
comment added in <<ChCustInterfaceOptionsSection>>.
|
||||
|
||||
_IP_::
|
||||
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.
|
||||
|
||||
|
||||
_Packets_::
|
||||
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.
|
||||
|
||||
_Packets/s_::
|
||||
Number of packets captured in the last second. Will be greyed out, if no packet
|
||||
was captured in the last second.
|
||||
|
||||
_Stop_::
|
||||
Stop a currently running capture.
|
||||
|
||||
_Start_::
|
||||
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.
|
||||
|
||||
_Options_::
|
||||
Open the Capture Options dialog with the marked interfaces selected. See
|
||||
<<ChCapCaptureOptions>>.
|
||||
|
||||
_Details (Microsoft Windows only)_::
|
||||
Open a dialog with detailed information about the interface. See
|
||||
<<ChCapInterfaceDetailsSection>>.
|
||||
|
||||
_Help_::
|
||||
Show this help page.
|
||||
|
||||
_Close_::
|
||||
Close this dialog box.
|
||||
|
||||
[[ChCapCaptureOptions]]
|
||||
|
||||
=== The ``Capture Options'' dialog box
|
||||
|
||||
When you select menu:Capture[Options...] (or use the corresponding item in the
|
||||
main toolbar), Wireshark pops up the ``Capture Options'' dialog box as shown in
|
||||
<<ChCapCaptureOptionsDialog>>.
|
||||
|
||||
[[ChCapCaptureOptionsDialog]]
|
||||
.The ``Capture Options'' dialog box
|
||||
image::wsug_graphics/ws-capture-options.png[]
|
||||
|
||||
[TIP]
|
||||
====
|
||||
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.
|
||||
====
|
||||
|
||||
==== Capture frame
|
||||
|
||||
The table shows the settings for all available interfaces:
|
||||
|
||||
* The name of the interface and its IP addresses. If no address could be
|
||||
resolved from the system, ``none'' will be shown.
|
||||
--
|
||||
[NOTE]
|
||||
====
|
||||
Loopback interfaces are not available on Windows platforms.
|
||||
====
|
||||
--
|
||||
|
||||
* The link-layer header type.
|
||||
|
||||
* The information whether promicuous mode is enabled or disabled.
|
||||
|
||||
* The maximum amount of data that will be captured for each packet. The default
|
||||
value is set to the 65535 bytes.
|
||||
|
||||
* The size of the kernel buffer that is reserved to keep the captured packets.
|
||||
|
||||
* The information whether packets will be captured in monitor mode (Unix/Linux
|
||||
only).
|
||||
|
||||
* The chosen capture filter.
|
||||
|
||||
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 <<ChCapEditInterfacesSettingsDialog>> will be opened.
|
||||
|
||||
_Capture on all interfaces_::
|
||||
As Wireshark can capture on multiple interfaces it is possible to choose to
|
||||
capture on all available interfaces.
|
||||
|
||||
_Capture all packets in promiscuous mode_::
|
||||
This checkbox allows you to specify that Wireshark should put all interfaces in
|
||||
promiscuous mode when capturing.
|
||||
|
||||
_Capture Filter_::
|
||||
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 <<ChCapCaptureFilterSection>>. It defaults to empty, or no
|
||||
filter.
|
||||
+
|
||||
You can also click on the button:[Capture Filter] button and Wireshark will
|
||||
bring up the Capture Filters dialog box and allow you to create and/or select a
|
||||
filter. Please see <<ChWorkDefineFilterSection>>
|
||||
|
||||
_Compile selected BPFs_::
|
||||
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 button:[Compile Selected BPFs] button
|
||||
leads you to <<ChCapCompileSelectedBpfsDialog>>.
|
||||
|
||||
[TIP]
|
||||
Linux power user tip
|
||||
====
|
||||
The execution of BPFs can be sped up on Linux by turning on BPF JIT by executing
|
||||
|
||||
----
|
||||
$ echo 1 >/proc/sys/net/core/bpf_jit_enable
|
||||
----
|
||||
|
||||
if it is not enabled already. To make the change persistent you can use
|
||||
link:sysfs-web-site:[][sysfsutils].
|
||||
====
|
||||
|
||||
_Manage Interfaces_::
|
||||
The button:[Manage Interfaces] button opens the <<ChCapManageInterfacesDialog>>
|
||||
where pipes can be defined, local interfaces scanned or hidden, or remote
|
||||
interfaces added (Windows only).
|
||||
|
||||
==== Capture File(s) frame
|
||||
|
||||
An explanation about capture file usage can be found in <<ChCapCaptureFiles>>.
|
||||
|
||||
_File_::
|
||||
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 <<ChCapCaptureFiles>> for
|
||||
details.
|
||||
+
|
||||
You can also click on the button to the right of this field to browse through
|
||||
the filesystem.
|
||||
|
||||
_Use multiple files_::
|
||||
Instead of using a single file Wireshark will automatically switch to a new
|
||||
one if a specific trigger condition is reached.
|
||||
|
||||
_Use pcap-ng format_::
|
||||
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 link:wireshark-wiki-site:[]Development/PcapNg[wireshark-wiki-site:[]Development/PcapNg] for more details on
|
||||
pcap-ng.
|
||||
|
||||
_Next file every n megabyte(s)_::
|
||||
Multiple files only. Switch to the next file after the given number of
|
||||
byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured.
|
||||
|
||||
_Next file every n minute(s)_::
|
||||
Multiple files only: Switch to the next file after the given number of
|
||||
second(s)/minutes(s)/hours(s)/days(s) have elapsed.
|
||||
|
||||
_Ring buffer with n files_::
|
||||
Multiple files only: Form a ring buffer of the capture files with the given
|
||||
number of files.
|
||||
|
||||
_Stop capture after n file(s)_::
|
||||
Multiple files only: Stop capturing after switching to the next file the given
|
||||
number of times.
|
||||
|
||||
==== Stop Capture... frame
|
||||
|
||||
_... after n packet(s)_::
|
||||
Stop capturing after the given number of packets have been captured.
|
||||
|
||||
_... after n megabytes(s)_::
|
||||
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.
|
||||
|
||||
_... after n minute(s)_::
|
||||
Stop capturing after the given number of second(s)/minutes(s)/hours(s)/days(s)
|
||||
have elapsed.
|
||||
|
||||
==== Display Options frame
|
||||
|
||||
_Update list of packets in real time_::
|
||||
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.
|
||||
|
||||
_Automatic scrolling in live capture_::
|
||||
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.
|
||||
|
||||
_Hide capture info dialog_::
|
||||
If this option is checked, the capture info dialog described in <<ChCapRunningSection>> will be hidden.
|
||||
|
||||
==== Name Resolution frame
|
||||
|
||||
_Enable MAC name resolution_::
|
||||
This option allows you to control whether or not Wireshark translates MAC
|
||||
addresses into names. See <<ChAdvNameResolutionSection>>.
|
||||
|
||||
_Enable network name resolution_::
|
||||
This option allows you to control whether or not Wireshark translates network
|
||||
addresses into names. See <<ChAdvNameResolutionSection>>.
|
||||
|
||||
_Enable transport name resolution_::
|
||||
This option allows you to control whether or not Wireshark translates transport
|
||||
addresses into protocols. See <<ChAdvNameResolutionSection>>.
|
||||
|
||||
==== Buttons
|
||||
|
||||
Once you have set the values you desire and have selected the options you need,
|
||||
simply click on button:[Start] to commence the capture or button:[Cancel] to
|
||||
cancel the capture.
|
||||
|
||||
If you start a capture, Wireshark allows you to stop capturing when you have
|
||||
enough packets captured, for details see <<ChCapRunningSection>>.
|
||||
|
||||
[[ChCapEditInterfaceSettingsSection]]
|
||||
|
||||
=== The ``Edit Interface Settings'' dialog box
|
||||
|
||||
If you double-click on an interface in <<ChCapCaptureOptionsDialog>> the following dialog box pops up.
|
||||
|
||||
[[ChCapEditInterfacesSettingsDialog]]
|
||||
.The ``Edit Interface Settings'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-settings.png[]
|
||||
|
||||
You can set the following fields in this dialog box:
|
||||
|
||||
_IP address_::
|
||||
The IP address(es) of the selected interface. If no address could be resolved
|
||||
from the system ``none'' will be shown.
|
||||
|
||||
_Link-layer header type_::
|
||||
Unless you are in the rare situation that requires this keep the default setting.
|
||||
For a detailed description. See <<ChCapLinkLayerHeader>>
|
||||
|
||||
_Wireless settings (Windows only)_::
|
||||
Here you can set the settings for wireless capture using the AirPCap adapter.
|
||||
For a detailed description see the AirPCap Users Guide.
|
||||
|
||||
_Remote settings (Windows only)_::
|
||||
Here you can set the settings for remote capture. For a detailed description
|
||||
see <<ChCapInterfaceRemoteSection>>
|
||||
|
||||
_Capture packets in promiscuous mode_::
|
||||
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).
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
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.
|
||||
|
||||
Even in promiscuous mode you still won't necessarily see all packets on your LAN
|
||||
segment. See link:wireshark-faq-url:[]#promiscsniff[the Wireshark FAQ] for more information.
|
||||
====
|
||||
|
||||
_Limit each packet to n bytes_::
|
||||
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 _snaplen_. If
|
||||
disabled the value is set to the maximum 65535 which will be sufficient for
|
||||
most protocols. Some rules of thumb:
|
||||
|
||||
* If you are unsure just keep the default value.
|
||||
|
||||
* If you don't need or don't want 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.
|
||||
|
||||
* 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.
|
||||
|
||||
_Buffer size: n megabyte(s)_::
|
||||
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.
|
||||
|
||||
_Capture packets in monitor mode (Unix/Linux only)_::
|
||||
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.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
In monitor mode the adapter might disassociate itself from the network it was
|
||||
associated to.
|
||||
====
|
||||
|
||||
_Capture Filter_::
|
||||
This field allows you to specify a capture filter. Capture filters are discussed
|
||||
in more details in <<ChCapCaptureFilterSection>>. It defaults to empty, or no
|
||||
filter.
|
||||
+
|
||||
You can also click on the button:[Capture Filter] button and Wireshark will
|
||||
bring up the ``Capture Filters'' dialog box and allow you to create and/or
|
||||
select a filter. Please see <<ChWorkDefineFilterSection>>
|
||||
|
||||
_Compile BPF_::
|
||||
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.
|
||||
|
||||
[[ChCapCompileSelectedBpfsSection]]
|
||||
|
||||
=== The ``Compile Results'' dialog box
|
||||
|
||||
This figure shows the compile results of the selected interfaces.
|
||||
|
||||
[[ChCapCompileSelectedBpfsDialog]]
|
||||
.The ``Compile Results'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-compile-selected-bpfs.png[]
|
||||
|
||||
In the left window the interface names are listed. The results of an individual
|
||||
interface are shown in the right window when it is selected.
|
||||
|
||||
[[ChCapManageInterfacesSection]]
|
||||
|
||||
=== The ``Add New Interfaces'' dialog box
|
||||
|
||||
As a central point to manage interfaces this dialog box consists of three tabs
|
||||
to add or remove interfaces.
|
||||
|
||||
[[ChCapManageInterfacesDialog]]
|
||||
.The ``Add New Interfaces'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-manage-interfaces.png[]
|
||||
|
||||
==== Add or remove pipes
|
||||
|
||||
[[ChCapManageInterfacesPipesDialog]]
|
||||
.The ``Add New Interfaces - Pipes'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-manage-interfaces-pipes.png[]
|
||||
|
||||
To successfully add a pipe, this pipe must have already been created. Click the
|
||||
button:[New] button and type the name of the pipe including its path.
|
||||
Alternatively, the button:[Browse] button can be used to locate the pipe. With
|
||||
the button:[Save] button the pipe is added to the list of available interfaces.
|
||||
Afterwards, other pipes can be added.
|
||||
|
||||
To remove a pipe from the list of interfaces it first has to be selected. Then
|
||||
click the button:[Delete] button.
|
||||
|
||||
==== Add or hide local interfaces
|
||||
|
||||
[[ChCapManageInterfacesLocalDialog]]
|
||||
.The ``Add New Interfaces - Local Interfaces'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-manage-interfaces-local.png[]
|
||||
|
||||
The tab ``Local Interfaces'' contains a list of available local interfaces,
|
||||
including the hidden ones, which are not shown in the other lists.
|
||||
|
||||
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.
|
||||
|
||||
One way to hide an interface is to change the preferences. If the ``Hide''
|
||||
checkbox is activated and the button:[Apply] button clicked, the interface will
|
||||
not be seen in the lists of the ``Capture Interfaces'' dialog box any more. The
|
||||
changes are also saved in the `preferences` file.
|
||||
|
||||
==== Add or hide remote interfaces
|
||||
|
||||
[[ChCapManageInterfacesRemoteDialog]]
|
||||
.The ``Add New Interfaces - Remote Interfaces'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-manage-interfaces-remote.png[]
|
||||
|
||||
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.
|
||||
|
||||
To remove a host including all its interfaces from the list, it has to be
|
||||
selected. Then click the button:[Delete] button.
|
||||
|
||||
For a detailed description see <<ChCapInterfaceRemoteSection>>
|
||||
|
||||
[[ChCapInterfaceRemoteSection]]
|
||||
|
||||
=== The ``Remote Capture Interfaces'' dialog box
|
||||
|
||||
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.
|
||||
|
||||
[NOTE]
|
||||
.Microsoft Windows only
|
||||
====
|
||||
This dialog and capability is only available on Microsoft Windows. On Linux/Unix
|
||||
you can achieve the same effect (securely) through an SSH tunnel.
|
||||
====
|
||||
|
||||
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 link:winpcap-download-page:[][winpcap-download-page:[]] on the target. Once
|
||||
installation is completed go to the Services control panel, find the Remote
|
||||
Packet Capture Protocol service and start it.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
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.
|
||||
====
|
||||
|
||||
To access the Remote Capture Interfaces dialog use the ``Add New Interfaces -
|
||||
Remote'' dialog. See <<ChCapManageInterfacesRemoteDialog>> and select button:[Add].
|
||||
|
||||
==== Remote Capture Interfaces
|
||||
|
||||
[[ChCapInterfaceRemoteDialog]]
|
||||
.The ``Remote Capture Interfaces'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-manage-interfaces-remote-plus.png[]
|
||||
|
||||
You have to set the following parameters in this dialog:
|
||||
|
||||
_Host_::
|
||||
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.
|
||||
|
||||
_Port_::
|
||||
Set the port number where the Remote Packet Capture Protocol service is
|
||||
listening on. Leave open to use the default port (2002).
|
||||
|
||||
_Null authentication_::
|
||||
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.
|
||||
|
||||
_Password authentication_::
|
||||
This is the normal way of connecting to a target platform. Set the credentials
|
||||
needed to connect to the Remote Packet Capture Protocol service.
|
||||
|
||||
==== Remote Capture Settings
|
||||
|
||||
The remote capture can be further fine tuned to match your situation. The
|
||||
button:[Remote Settings] button in <<ChCapEditInterfacesSettingsDialog>> gives
|
||||
you this option. It pops up the dialog shown in
|
||||
<<ChCapInterfaceRemoteSettingsDialog>>.
|
||||
|
||||
[[ChCapInterfaceRemoteSettingsDialog]]
|
||||
.The ``Remote Capture Settings'' dialog box
|
||||
image::wsug_graphics/ws-capture-options-remote-settings.png[]
|
||||
|
||||
You can set the following parameters in this dialog:
|
||||
|
||||
_Do not capture own RPCAP traffic_::
|
||||
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.
|
||||
+
|
||||
You only should switch this off when capturing on an interface other then the
|
||||
interface connecting back to Wireshark.
|
||||
|
||||
_Use UDP for data transfer_::
|
||||
Remote capture control and data flows over a TCP connection. This option allows
|
||||
you to choose an UDP stream for data transfer.
|
||||
|
||||
_Sampling option None_::
|
||||
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.
|
||||
|
||||
_Sampling option 1 of x packets_::
|
||||
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.
|
||||
|
||||
|
||||
_Sampling option 1 every x milliseconds_::
|
||||
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.
|
||||
|
||||
[[ChCapInterfaceDetailsSection]]
|
||||
|
||||
=== The ``Interface Details'' dialog box
|
||||
|
||||
When you select Details from the Capture Interface menu, Wireshark pops up the
|
||||
``Interface Details'' dialog box as shown in <<ChCapInterfaceDetailsDialog>>. This
|
||||
dialog shows various characteristics and statistics for the selected interface.
|
||||
|
||||
[NOTE]
|
||||
.Microsoft Windows only
|
||||
====
|
||||
This dialog is only available on Microsoft Windows
|
||||
====
|
||||
|
||||
[[ChCapInterfaceDetailsDialog]]
|
||||
.The ``Interface Details'' dialog box
|
||||
image::wsug_graphics/ws-capture-interface-details.png[]
|
||||
|
||||
[[ChCapCaptureFiles]]
|
||||
|
||||
=== Capture files and file modes
|
||||
|
||||
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.
|
||||
|
||||
Different modes of operation are available when saving this packet data to the
|
||||
capture file(s).
|
||||
|
||||
[TIP]
|
||||
====
|
||||
Working with large files (several hundred MB) 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.
|
||||
====
|
||||
|
||||
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.
|
||||
|
||||
Information about the folders used for capture files can be found in
|
||||
<<AppFiles>>.
|
||||
|
||||
[[ChCapTabCaptureFiles]]
|
||||
.Capture file mode selected by capture options
|
||||
[options="header"]
|
||||
|===============
|
||||
|``File'' option|``Use multiple files'' option|``Ring buffer with n files'' option|Mode|Resulting filename(s) used
|
||||
|-|-|-|_Single temporary file_|wiresharkXXXXXX (where XXXXXX is a unique number)
|
||||
|foo.cap|-|-|_Single named file_|foo.cap
|
||||
|foo.cap|x|-|_Multiple files, continuous_|foo_00001_20100205110102.cap, foo_00002_20100205110318.cap, ...
|
||||
|foo.cap|x|x|_Multiple files, ring buffer_|foo_00001_20100205110102.cap, foo_00002_20100205110318.cap, ...
|
||||
|===============
|
||||
|
||||
_Single temporary file_::
|
||||
A temporary file will be created and used (this is the default). After capturing
|
||||
is stopped this file can be saved later under a user specified name.
|
||||
|
||||
_Single named file_::
|
||||
A single capture file will be used. If you want to place the new capture file in
|
||||
a specific folder choose this mode.
|
||||
|
||||
_Multiple files, continuous_::
|
||||
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).
|
||||
|
||||
_Multiple files, ring buffer_::
|
||||
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'').
|
||||
+
|
||||
This mode will limit the maximum disk usage, even for an unlimited amount of
|
||||
capture input data, only keeping the latest captured data.
|
||||
|
||||
[[ChCapLinkLayerHeader]]
|
||||
|
||||
=== Link-layer header type
|
||||
|
||||
In most cases you won't have to modify link-layer header type. Some exceaptions
|
||||
are as follows:
|
||||
|
||||
If you are capturing on an Ethernet device you might be offered 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''.
|
||||
|
||||
If you are capturing on an 802.11 device on some versions of BSD you might be
|
||||
offered a choice of ``Ethernet'' or ``802.11''. ``Ethernet'' will cause the
|
||||
captured packets to have fake (``cooked'') Ethernet headers. ``802.11'' will
|
||||
cause them to have full 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''.
|
||||
|
||||
If you are capturing on an Endace DAG card connected to a synchronous serial
|
||||
line you might be offered 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''.
|
||||
|
||||
If you are capturing on an Endace DAG card connected to an ATM network you might
|
||||
be offered 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''.
|
||||
|
||||
[[ChCapCaptureFilterSection]]
|
||||
|
||||
=== Filtering while capturing
|
||||
|
||||
Wireshark uses the libpcap filter language for capture filters. A brief overview
|
||||
of the syntax follows. Complete documentation can be found in the
|
||||
link:pcap-filter-man-page-url:[][pcap-filter man page]. You can find a lot of
|
||||
Capture Filter examples at
|
||||
link:wireshark-wiki-site:[]CaptureFilters[wireshark-wiki-site:[]CaptureFilters].
|
||||
|
||||
You enter the capture filter into the ``Filter'' field of the Wireshark
|
||||
``Capture Options'' dialog box, as shown in <<ChCapCaptureOptionsDialog>>.
|
||||
|
||||
A capture filter takes the form of a series of primitive expressions connected
|
||||
by conjunctions (__and/or__) and optionally preceded by __not__:
|
||||
|
||||
----
|
||||
[not] primitive [and|or [not] primitive ...]
|
||||
----
|
||||
|
||||
An example is shown in <<ChCapExFilt1>>.
|
||||
|
||||
[[ChCapExFilt1]]
|
||||
.A capture filter for telnet that captures traffic to and from a particular host
|
||||
====
|
||||
A capture filter for telnet that captures traffic to and from a particular host
|
||||
|
||||
----
|
||||
tcp port 23 and host 10.0.0.5
|
||||
----
|
||||
====
|
||||
|
||||
This example captures telnet traffic to and from the host 10.0.0.5, and shows
|
||||
how to use two primitives and the __and__ conjunction. Another example is shown
|
||||
in <<ChCapExFilt2>>, and shows how to capture all telnet traffic except that
|
||||
from 10.0.0.5.
|
||||
|
||||
[[ChCapExFilt2]]
|
||||
.Capturing all telnet traffic not from 10.0.0.5
|
||||
====
|
||||
Capturing all telnet traffic not from 10.0.0.5
|
||||
|
||||
----
|
||||
tcp port 23 and not src host 10.0.0.5
|
||||
----
|
||||
====
|
||||
|
||||
// XXX - add examples to the following list.
|
||||
|
||||
A primitive is simply one of the following: _[src|dst] host <host>_::
|
||||
This primitive allows you to filter on a host IP address or name. You can
|
||||
optionally precede the primitive with the keyword _src|dst_ 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.
|
||||
|
||||
_ether [src|dst] host <ehost>_::
|
||||
This primitive allows you to filter on Ethernet host addresses. You can
|
||||
optionally include the keyword _src|dst_ between the keywords _ether_ and _host_
|
||||
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.
|
||||
|
||||
_gateway host <host>_::
|
||||
This primitive allows you to filter on packets that used _host_ as a gateway.
|
||||
That is, where the Ethernet source or destination was _host_ but neither the
|
||||
source nor destination IP address was _host_.
|
||||
|
||||
_[src|dst] net <net> [{mask <mask>}|{len <len>}]_::
|
||||
This primitive allows you to filter on network numbers. You can optionally
|
||||
precede this primitive with the keyword _src|dst_ 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.
|
||||
|
||||
|
||||
_[tcp|udp] [src|dst] port <port>_::
|
||||
This primitive allows you to filter on TCP and UDP port numbers. You can
|
||||
optionally precede this primitive with the keywords _src|dst_ and _tcp|udp_
|
||||
which allow you to specify that you are only interested in source or destination
|
||||
ports and TCP or UDP packets respectively. The keywords _tcp|udp_ must appear
|
||||
before _src|dst_.
|
||||
+
|
||||
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.
|
||||
|
||||
_less|greater <length>_::
|
||||
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.
|
||||
|
||||
_ip|ether proto <protocol>_::
|
||||
This primitive allows you to filter on the specified protocol at either the
|
||||
Ethernet layer or the IP layer.
|
||||
|
||||
_ether|ip broadcast|multicast_::
|
||||
This primitive allows you to filter on either Ethernet or IP broadcasts or
|
||||
multicasts.
|
||||
|
||||
_<expr> relop <expr>_::
|
||||
This primitive allows you to create complex filter expressions that select bytes
|
||||
or ranges of bytes in packets. Please see the pcap-filter man page at
|
||||
link:pcap-filter-man-page-url:[][pcap-filter-man-page-url:[]] for more details.
|
||||
|
||||
|
||||
[[ChCapCaptureAutoFilterSection]]
|
||||
|
||||
==== Automatic Remote Traffic Filtering
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
The following environment variables are analyzed:
|
||||
|
||||
_$$SSH_CONNECTION$$_ (ssh)::
|
||||
<remote IP> <remote port> <local IP> <local port>
|
||||
|
||||
|
||||
_$$SSH_CLIENT$$_ (ssh)::
|
||||
<remote IP> <remote port> <local port>
|
||||
|
||||
|
||||
_REMOTEHOST_ (tcsh, others?)::
|
||||
<remote name>
|
||||
|
||||
_DISPLAY_ (x11)::
|
||||
[remote name]:<display num>
|
||||
|
||||
|
||||
_SESSIONNAME_ (terminal server)::
|
||||
<remote name>
|
||||
|
||||
On Windows it asks the operating system if it's running in a Remote Desktop Services environment.
|
||||
|
||||
[[ChCapRunningSection]]
|
||||
|
||||
=== While a Capture is running ...
|
||||
|
||||
While a capture is running, the following dialog box is shown:
|
||||
|
||||
[[ChCapCaptureInfoDialog]]
|
||||
.The ``Capture Info'' dialog box
|
||||
image::wsug_graphics/ws-capture-info.png[]
|
||||
|
||||
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.
|
||||
|
||||
[TIP]
|
||||
====
|
||||
This ``Capture Info'' dialog box can be hidden using the ``Hide capture info
|
||||
dialog'' option in the Capture Options dialog box.
|
||||
====
|
||||
|
||||
[[ChCapStopSection]]
|
||||
|
||||
==== Stop the running capture
|
||||
|
||||
A running capture session will be stopped in one of the following ways:
|
||||
|
||||
. Using the button:[Stop[ button from the ``Capture Info'' dialog box.
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
The ``Capture Info'' dialog box might be hidden if the ``Hide capture info
|
||||
dialog'' option is used.
|
||||
====
|
||||
|
||||
. Using the menu:Capture[Stop] menu item.
|
||||
|
||||
. Using the button:[Stop] toolbar button.
|
||||
|
||||
. Pressing kbd:[Ctrl+E].
|
||||
|
||||
. The capture will be automatically stopped if one of the _Stop Conditions_ is
|
||||
met, e.g. the maximum amount of data was captured.
|
||||
|
||||
[[ChCapRestartSection]]
|
||||
|
||||
==== Restart a running capture
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
|
||||
. Using the menu:Capture[Restart] menu item.
|
||||
|
||||
. Using the button:[Restart] toolbar button.
|
||||
|
||||
++++++++++++++++++++++++++++++++++++++
|
||||
<!-- End of WSUG Chapter Capture -->
|
||||
++++++++++++++++++++++++++++++++++++++
|
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue