From a84937198ba1c0ea5313aebd6d9cecc23f298af3 Mon Sep 17 00:00:00 2001 From: Gerald Combs Date: Mon, 18 Aug 2014 09:31:26 -0700 Subject: [PATCH] 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 --- docbook/README.txt | 40 +- docbook/asciidoc.conf | 3 + docbook/ws.css | 4 - .../wsug_src/WSUG_chapter_capture.asciidoc | 936 ++++++++++ docbook/wsug_src/WSUG_chapter_capture.xml | 1575 ----------------- 5 files changed, 973 insertions(+), 1585 deletions(-) create mode 100644 docbook/wsug_src/WSUG_chapter_capture.asciidoc delete mode 100644 docbook/wsug_src/WSUG_chapter_capture.xml diff --git a/docbook/README.txt b/docbook/README.txt index 2404e72866..7b56f62dd1 100644 --- a/docbook/README.txt +++ b/docbook/README.txt @@ -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/ - diff --git a/docbook/asciidoc.conf b/docbook/asciidoc.conf index 54563b2186..29b22c440e 100644 --- a/docbook/asciidoc.conf +++ b/docbook/asciidoc.conf @@ -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 diff --git a/docbook/ws.css b/docbook/ws.css index a83d020a1a..a5d11422c3 100644 --- a/docbook/ws.css +++ b/docbook/ws.css @@ -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 { diff --git a/docbook/wsug_src/WSUG_chapter_capture.asciidoc b/docbook/wsug_src/WSUG_chapter_capture.asciidoc new file mode 100644 index 0000000000..e2b4ed1a9a --- /dev/null +++ b/docbook/wsug_src/WSUG_chapter_capture.asciidoc @@ -0,0 +1,936 @@ +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ + +[[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 + <>. + +* Save packets in multiple files while doing a long term capture, optionally + rotating through a fixed number of files (a ``ringbuffer''). See + <>. + +* 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 + <> or <> 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 <>. + +[[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 +<> or <>. + +// 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 <>. +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 <>. + +_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 +<>. + +_Details (Microsoft Windows only)_:: +Open a dialog with detailed information about the interface. See +<>. + +_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]] +.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 <> 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 <>. 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 <> + +_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 <>. + +[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 <> +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 <>. + +_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 <> 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 <> 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 <>. + +_Enable network name resolution_:: +This option allows you to control whether or not Wireshark translates network +addresses into names. See <>. + +_Enable transport name resolution_:: +This option allows you to control whether or not Wireshark translates transport +addresses into protocols. See <>. + +==== 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 <>. + +[[ChCapEditInterfaceSettingsSection]] + +=== The ``Edit Interface Settings'' dialog box + +If you double-click on an interface in <> 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 <> + +_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 <> + +_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 <>. 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 <> + +_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]] + +=== 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 <> 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 <> gives +you this option. It pops up the dialog shown in +<>. + +[[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 <>. 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 +<>. + +[[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 <>. + +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]] +.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 <>, 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. + +++++++++++++++++++++++++++++++++++++++ + +++++++++++++++++++++++++++++++++++++++ diff --git a/docbook/wsug_src/WSUG_chapter_capture.xml b/docbook/wsug_src/WSUG_chapter_capture.xml deleted file mode 100644 index 2a92f58361..0000000000 --- a/docbook/wsug_src/WSUG_chapter_capture.xml +++ /dev/null @@ -1,1575 +0,0 @@ - - - - Capturing Live Network Data -
- 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 (Ethernet, Token Ring, - ATM, ...). - - - Stop the capture on different triggers like: amount of captured data, - captured time, captured number of packets. - - - Simultaneously show decoded packets while Wireshark keeps on capturing. - - - Filter packets, reducing the amount of data to be captured, see . - - - 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 . - - - Simultaneous capturing from multiple network interfaces. - - - The capture engine still lacks the following features: - - - Stop capturing (or doing some other action), depending on the captured - data. - - - -
- -
Prerequisites - - Setting up Wireshark to capture packets for the first time can be tricky. - - Tip! - A comprehensive guide "How To setup a Capture" is available at: - &WiresharkWikiPage;/CaptureSetup. - - - Here are some common pitfalls: - - - - You need to have root / Administrator 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. - - - - - ... and a lot more!. - - - - - - If you have any problems setting up your capture environment, you should - have a look at the guide mentioned above. - -
- -
Start Capturing - - One of the following methods can be used to start capturing packets with - Wireshark: - - - - You can get an overview of the available local interfaces using the - " - Capture Interfaces" dialog box, see - or - . You can start a - capture from this dialog box, using (one of) the "Capture" button(s). - - - - - You can start capturing using the - " - Capture Options" dialog box, see - . - - - - - If you have selected the right capture options before, you can - immediately start a capture using the - " - Capture Start" menu / toolbar item. The capture - process will start immediately. - - - - - If you already know the name of the capture interface, you can start - Wireshark from the command line and use the following: - -wireshark -i eth0 -k - - This will start Wireshark capturing on interface eth0, more details - can be found at: . - - - - -
- -
- The "Capture Interfaces" dialog box - - When you select "Interfaces..." from the Capture menu, Wireshark pops - up the "Capture Interfaces" dialog box as shown in - or - . - 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. - - - Not all available interfaces may be displayed! - - This dialog box will only show the local interfaces Wireshark knows - of. It will not show interfaces marked as hidden in . - 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. - - - - - As it is possible to simultaneously capture packets from multiple interfaces, - the toggle buttons can be used to select one or more interfaces. - -
- The "Capture Interfaces" dialog box on Microsoft Windows - -
-
- The "Capture Interfaces" dialog box on Unix/Linux - -
- - Device (Unix/Linux only) - - - The interface device name. - - - - Description - - - The interface description provided by the operating system, or the - user defined comment added in . - - - - 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 - . - - - - Details (Microsoft Windows only) - - - Open a dialog with detailed information about the interface, see - . - - - - Help - - - Show this help page. - - - - Close - - - Close this dialog box. - - - - -
- -
- The "Capture Options" dialog box - - 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 - . - -
- The "Capture Options" dialog box - -
- 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 - 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 - . It defaults to empty, or - no filter. - - - 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 - - - - - 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 "Compile selected BPFs" button leads you to - . - - 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 sysfsutils - sysfsutils. - - - - - - - Manage Interfaces - - - - The "Manage Interfaces" button leads you to - 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 . - - - 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 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 - 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 - 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 - . - - - - - Enable network name resolution - - - This option allows you to control whether or not - Wireshark translates network addresses into names, see - . - - - - - Enable transport name resolution - - - This option allows you to control whether or not - Wireshark translates transport addresses into protocols, see - . - - - - -
-
Buttons - - Once you have set the values you desire and have selected the - options you need, simply click on Start to commence the - capture, or 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 - . - -
-
- -
- The "Edit Interface Settings" dialog box - - If you double-click on an interface in - the following dialog box pops up. - -
- The "Edit Interface Settings" dialog box - -
- - 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 you need this, just keep - the default. For a detailed description, see - - - - - 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 - - - - - - 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. - - - - Note - - Even in promiscuous mode you still won't necessarily see all packets - on your LAN segment, see for - some more explanations. - - - - - 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 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 - . It defaults to empty, or - no filter. - - - 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 - - - - - 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. - - - - -
- -
- The "Compile Results" dialog box - - This figure shows the compile results of the selected interfaces. - -
- The "Compile Results" dialog box - -
- - 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. - -
- -
- 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. - -
- The "Add New Interfaces" dialog box - -
-
- Add or remove pipes -
- The "Add New Interfaces - Pipes" dialog box - -
- 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. - - - To remove a pipe from the list of interfaces it first has to be selected. Then - click the "Delete" button. - -
-
- Add or hide local interfaces -
- The "Add New Interfaces - Local Interfaces" dialog box - -
- - 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 "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. - -
-
- Add or hide remote interfaces -
- The "Add New Interfaces - Remote Interfaces" dialog box - -
- - 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 "Delete" button. - - - For a detailed description, see - -
-
- -
- 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. - - 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 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 - , and select "Add". - -
Remote Capture Interfaces -
- The "Remote Capture Interfaces" dialog box - -
- - You have to set the following parameter 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 Remote Settings button in - gives you this option. - It pops up the dialog shown in - . - -
- The "Remote Capture Settings" dialog box - -
- - 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. - - - - -
-
- -
- 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 - . This dialog shows various - characteristics and statistics for the selected interface. - - Microsoft Windows only - This dialog is only available on Microsoft Windows - -
- The "Interface Details" dialog box - -
-
- -
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 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. - - - Note! - - 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. - - - Tip! - - Information about the folders used for the capture file(s), can be found - in . - - - - Capture file mode selected by capture options - - - - - - - - "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 the - 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 to 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, keeping the latest captured data. - - - - -
- -
Link-layer header type - - 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: - - - 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". - - - 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". - - - 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". - - - 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". - -
- -
Filtering while capturing - - 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. - - - Tip! - - You will find a lot of Capture Filter examples at &WiresharkWikiCaptureFiltersPage;. - - - - You enter the capture filter into the Filter field of the Wireshark - Capture Options dialog box, as shown in - . The following is an outline - of the syntax of the tcpdump capture filter language. - See the expression option at the tcpdump manual page for details: - . - - - 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 . - - - - 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 - , and shows how to capture all - telnet traffic except that 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 tcpdump man page at - for more details. - - - - - -
- 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. - -
-
- -
While a Capture is running ... - - While a capture is running, the following dialog box is shown: -
- The "Capture Info" dialog box - -
- 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. - - -
Stop the running capture - - A running capture session will be stopped in one of the following ways: - - - Using the - " - Stop" button from the Capture Info dialog box - . - - Note! - - The Capture Info dialog box might be hidden, if the option "Hide capture - info dialog" is used. - - - - - Using the menu item - "Capture/ - Stop". - - - - Using the toolbar item - " - Stop". - - - - Pressing the accelerator keys: Ctrl+E. - - - - The capture will be automatically stopped, if one of the - Stop Conditions is exceeded, e.g. the maximum amount - of data was captured. - - - - -
-
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 item - "Capture/ - Restart". - - - - Using the toolbar item - " - Restart". - - - - -
-
- - - - -