// 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. * Simultaneously capture from multiple network interfaces. * 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 <>. 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 {wireshark-wiki-url}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 <>. * You can select an interface in the <>, then select menu:Capture[Start] or click the first toolbar button. * You can get more detailed information about available interfaces using <> (menu:Capture[Options...]). * 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” Section Of The Welcome Screen When you open Wireshark without starting a capture or opening a capture file it will display the “Welcome Screen,” which lists any recently opened capture files and available capture interfaces. Network activity for each interface will be shown in a sparkline next to the interface name. It is possible to select more than one interface and capture from them simultaneously. [#ChCapCaptureInterfacesMainWin32] .Capture interfaces on Microsoft Windows image::images/ws-capture-interfaces-main-win32.png[{screenshot-attrs}] [#ChCapCaptureInterfacesMainMacos] .Capture interfaces on macOS image::images/ws-capture-interfaces-main-macos.png[{screenshot-attrs}] Some interfaces allow or require configuration prior to capture. This will be indicated by a configuration icon (image:images/toolbar/x-capture-options.png[height=16,width=16]) to the left of the interface name. Clicking on the icon will show the configuration dialog for that interface. Hovering over an interface will show any associated IPv4 and IPv6 addresses and its capture filter. Wireshark isn't limited to just network interfaces -- on most systems you can also capture USB, Bluetooth, and other types of packets. Note also that an interface might be hidden if it’s inaccessible to Wireshark or if it has been hidden as described in <>. [#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 <>. If you are unsure which options to choose in this dialog box, leaving the defaults settings as they are should work well in many cases. [#ChCapCaptureOptionsDialog] .The “Capture Options” input tab image::images/ws-capture-options.png[{screenshot-attrs}] The “Input” tab contains the “Interface” table, which shows the following columns: Interface:: The interface name. + Some interfaces allow or require configuration prior to capture. This will be indicated by a configuration icon (image:images/toolbar/x-capture-options.png[height=16,width=16]) to the left of the interface name. Clicking on the icon will show the configuration dialog for that interface. Traffic:: A sparkline showing network activity over time. Link-layer Header:: The type of packet captured by this interface. In some cases it is possible to change this. See <> for more details. Promiscuous:: Lets you put this interface in promiscuous mode while capturing. Note that another application might override this setting. Snaplen:: The snapshot length, or the number of bytes to capture for each packet. You can set an explicit length if needed, e.g., for performance or privacy reasons. Buffer:: The size of the kernel buffer that is reserved for capturing packets. You can increase or decrease this as needed, but the default is usually sufficient. Monitor Mode:: Lets you capture full, raw 802.11 headers. Support depends on the interface type, hardware, driver, and OS. Note that enabling this might disconnect you from your wireless network. Capture Filter:: The capture filter applied to this interface. You can edit the filter by double-clicking on it. See <> for more details about capture filters. Hovering over an interface or expanding it will show any associated IPv4 and IPv6 addresses. If “Enable promiscuous mode on all interfaces” is enabled, the individual promiscuous mode settings above will be overridden. “Capture filter for selected interfaces” can be used to set a filter for more than one interface at the same time. btn:[Manage Interfaces] opens the <> where pipes can be defined, local interfaces scanned or hidden, or remote interfaces added. btn:[Compile Selected BPFs] opens <>, which shows you the compiled bytecode for your capture filter. This can help to better understand the capture filter you created. [TIP] .Linux power user tip ==== The execution of BPFs can be sped up on Linux by turning on BPF Just In Time compilation 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-main-url}[sysfsutils]. ==== .The “Capture Options” output tab image::images/ws-capture-options-output.png[{screenshot-attrs}] The “Output” tab shows the following information: Capture to a permanent file:: File::: This field allows you to specify the file name that will be used for the capture file. It is left blank by default. If 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. Output format::: Allows you to set the format of the capture file. pcapng is the default and is more flexible than pcap. pcapng might be required, e.g., if more than one interface is chosen for capturing. See {wireshark-wiki-url}Development/PcapNg for more details on pcapng. Create a new file automatically...:: Sets the conditions for switching a new capture file. A new capture file can be created based on the following conditions: * The number of packets in the capture file. * The size of the capture file. * The duration of the capture file. * The wall clock time. Use a ring buffer with:: Multiple files only. Form a ring buffer of the capture files with the given number of files. More details about capture files can be found in <>. .The “Capture Options” options tab image::images/ws-capture-options-options.png[{screenshot-attrs}] The “Options” tab shows the following information: Display Options:: Update list of packets in real-time::: Updates the packet list pane in real time during capture. If you do not enable this, Wireshark will 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. Automatically scroll during live capture::: Scroll the packet list pane as new packets come in, so you are always looking at the most recent packet. Automatic scrolling is temporarily disabled when manually scrolling upwards or performing a <> so that the selected packet can be examined. It will resume upon manually scrolling to the end of the packet list. If you do not specify this Wireshark adds new packets to the packet list but does not scroll the packet list pane. This option has no effect if “Update list of packets in real-time” is disabled. Show capture information during capture::: If this option is enabled, the capture information dialog described in <> will be shown while packets are captured. Name Resolution:: Resolve MAC addresses::: Translate MAC addresses into names. Resolve network names::: Translate network addresses into names. Resolve transport names::: Translate transport names (port numbers). See <> for more details on each of these options. Stop capture automatically after...:: Capturing can be stopped based on the following conditions: * The number of packets in the capture file. * The number of capture files. * The capture file size. * The capture file duration. You can double click on an interface row in the “Input“ tab or click btn:[Start] from any tab to commence the capture. You can click btn:[Cancel] to apply your changes and close the dialog. [#ChCapManageInterfacesSection] === The “Manage Interfaces” Dialog Box [#ChCapManageInterfacesDialog] .The “Manage Interfaces” dialog box image::images/ws-manage-interfaces.png[{screenshot-attrs}] The “Manage Interfaces” dialog box initially shows the “Local Interfaces” tab, which lets you manage the following: Show:: Whether or not to show or hide this interface in the welcome screen and the “Capture Options” dialog. Friendly Name:: A name for the interface that is human readable. Interface Name:: The device name of the interface. Comment:: Can be used to add a descriptive comment for the interface. // [[ChCapManageInterfacesPipesDialog]] // .The “Pipes” tab // image::images/ws-capture-options-manage-interfaces-pipes.png[{screenshot-attrs}] The “Pipes” tab lets you capture from a named pipe. To successfully add a pipe, its associated named pipe must have already been created. Click btn:[{plus}] and type the name of the pipe including its path. Alternatively, btn:[Browse] can be used to locate the pipe. To remove a pipe from the list of interfaces, select it and press btn:[-]. // [[ChCapManageInterfacesDialog]] // === 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 // image::images/ws-capture-options-manage-interfaces.png[{screenshot-attrs}] // ==== Add or hide local interfaces // [[ChCapManageInterfacesLocalDialog]] // .The “Add New Interfaces - Local Interfaces” dialog box // image::images/ws-capture-options-manage-interfaces-local.png[{screenshot-attrs}] // 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 btn:[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::images/ws-capture-options-manage-interfaces-remote.png[{screenshot-attrs}] On Microsoft Windows, the “Remote Interfaces” tab lets you capture from an interface on a different machine. The Remote Packet Capture Protocol service must first be running on the target platform before Wireshark can connect to it. On Linux or Unix you can capture (and do so more securely) through an SSH tunnel. To add a new remote capture interface, click btn:[{plus}] and specify the following: Host:: 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 blank 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. This is exactly as secure as it appears, i.e., it is not secure at all. Password authentication:: Lets you specify the username and password required to connect to the Remote Packet Capture Protocol service. Each interface can optionally be hidden. In contrast to the local interfaces, they are not saved in the `preferences` file. [NOTE] ==== Make sure you have outside access to port 2002 on the target platform. This is the default port used by the Remote Packet Capture Protocol service. ==== To remove a host including all its interfaces from the list, select it and click the btn:[-] button. // To access the Remote Capture Interfaces dialog use the “Remote Interfaces” tab of the “Manage Interfaces” dialog. See <> and select btn:[Add]. // [[ChCapInterfaceRemoteDialog]] // .The “Remote Capture Interfaces” dialog box // image::images/ws-capture-options-manage-interfaces-remote-plus.png[{screenshot-attrs}] // ==== Remote Capture Settings // The remote capture can be further fine tuned to match your situation. The // btn:[Remote Interfaces] button in <> gives // you this option. It pops up the dialog shown in // <>. // [[ChCapInterfaceRemoteSettingsDialog]] // .The “Remote Capture Settings” dialog box // image::images/ws-capture-options-remote-settings.png[{screenshot-attrs}] // 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 than 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 a 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::images/ws-capture-interface-details.png[{screenshot-attrs}] [#ChCapCompiledFilterOutputSection] === The “Compiled Filter Output” Dialog Box This figure shows the results of compiling the BPF filter for the selected interfaces. [#ChCapCompiledFilterOutputDialog] .The “Compiled Filter Output” dialog box image::images/ws-capture-options-compile-selected-bpfs.png[{medium-screenshot-attrs}] In the list on the left the interface names are listed. The results of compiling a filter for the selected interface are shown on the right. [#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 a capture file. By default, Wireshark saves packets to a temporary file. You can also tell Wireshark to save to a specific (“permanent”) file and switch to a different file after a given time has elapsed or a given number of packets have been captured. These options are controlled in the “Capture Options” dialog's “Output” tab. [#ChCapCaptureOptionsOutputDialog] .Capture output options image::images/ws-capture-options-output.png[{screenshot-attrs}] [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 the “Multiple files” option 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",cols="2,2,2,3,5"] |=== |File Name|“Create a new file...”|“Use a ring buffer...”|Mode|Resulting filename(s) used |-|-|-|Single temporary file|wireshark_XXXXXX.pcap[ng] ( is the "friendly name" of the capture interface if available and the system name if not, when capturing on a single interface, and "N_interfaces" where N is the number of interfaces, when capturing on multiple interfaces; XXXXXX is a unique 6 character alphanumeric sequence.) |foo.cap|-|-|Single named file|foo.cap |foo.cap|x|-|Multiple files, continuous|foo_00001_20240714110102.cap, foo_00002_20240714110318.cap, ... |foo.cap|x|x|Multiple files, ring buffer|foo_00001_20240714110102.cap, foo_00002_20240714110318.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. Choose this mode if you want to place the new capture file in a specific folder. 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 exceptions 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 supports limiting the packet capture to packets that match a _capture filter_. Wireshark capture filters are written in libpcap filter language. Below is a brief overview of the libpcap filter language's syntax. Complete documentation can be found at the link:{pcap-filter-man-page-url}[pcap-filter man page]. You can find many Capture Filter examples at {wireshark-wiki-url}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 ==== ---- 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 ==== ---- 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 _:: 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 :: 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 :: 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 [{mask }|{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 :: 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 :: 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 :: 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. relop :: 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 {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):: `SSH_CLIENT` (ssh):: `REMOTEHOST` (tcsh, others?):: `DISPLAY` (x11):: [remote name]: `SESSIONNAME` (terminal server):: On Windows it asks the operating system if it’s running in a Remote Desktop Services environment. [#ChCapRunningSection] === While a Capture is running ... You might see the following dialog box while a capture is running: [#ChCapCaptureInfoDialog] .The “Capture Information” dialog box image::images/ws-capture-info.png[{small-screenshot-attrs}] This dialog box shows a list of protocols and their activity over time. It can be enabled via the “capture.show_info” setting in the “Advanced” preferences. [#ChCapStopSection] ==== Stop the running capture A running capture session will be stopped in one of the following ways: . The btn:[Stop Capture] button in the “Capture Information” dialog box. . The menu:Capture[Stop] menu item. . The btn:[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 btn:[Restart] toolbar button. // End of WSUG Chapter Capture