1 <!-- WSUG Chapter Capture -->
4 <chapter id="ChapterCapture">
5 <title>Capturing Live Network Data</title>
7 <section id="ChCapIntroduction">
8 <title>Introduction</title>
10 Capturing live network data is one of the major features of Wireshark.
13 The Wireshark capture engine provides the following features:
18 Capture from different kinds of network hardware (Ethernet, Token Ring,
22 Stop the capture on different triggers like: amount of captured data,
23 captured time, captured number of packets.
26 Simultaneously show decoded packets while keep on capturing.
29 Filter packets, reducing the amount of data to be captured, see <xref
30 linkend="ChCapCaptureFilterSection"/>.
33 Capturing into multiple files while doing a long term capture, and in
34 addition the option to form a ringbuffer of these files, keeping only
35 the last x files, useful for a "very long term" capture, see <xref
36 linkend="ChCapCaptureFiles"/>.
39 The capture engine still lacks the following features:
42 Simultaneous capturing from multiple network interfaces (however, you
43 can start multiple instances of Wireshark and merge capture files later).
46 Stop capturing (or doing some other action), depending on the captured
53 <section id="ChCapPrerequisitesSection"><title>Prerequisites</title>
55 Setting up Wireshark to capture packets for the first time can be tricky.
57 <tip><title>Tip!</title><para>
58 A comprehensive guide "How To setup a Capture" is available at:
59 <ulink url="&WiresharkWikiPage;/CaptureSetup">&WiresharkWikiPage;/CaptureSetup</ulink>.
62 Here are some common pitfalls:
66 You need to have root / Administrator privileges to start a live
72 You need to choose the right network interface to capture packet data
78 You need to capture at the right place in the network to see the
79 traffic you want to see.
90 If you have any problems setting up your capture environment, you should
91 have a look at the guide mentioned above.
95 <section id="ChCapCapturingSection"><title>Start Capturing</title>
97 One of the following methods can be used to start capturing packets with
102 You can get an overview of the available local interfaces using the
103 "<inlinegraphic entityref="WiresharkToolbarCaptureInterfaces" format="PNG"/>
104 Capture Interfaces" dialog box, see
105 <xref linkend="ChCapCaptureInterfacesDialog"/>. You can start a
106 capture from this dialog box, using (one of) the "Capture" button(s).
111 You can start capturing using the
112 "<inlinegraphic entityref="WiresharkToolbarCaptureOptions" format="PNG"/>
113 Capture Options" dialog box, see
114 <xref linkend="ChCapCaptureOptionsDialog"/>.
119 If you have selected the right capture options before, you can
120 immediately start a capture using the
121 "<inlinegraphic entityref="WiresharkToolbarCaptureStart" format="PNG"/>
122 Capture Start" menu / toolbar item. The capture
123 process will start immediately.
128 If you already know the name of the capture interface, you can start
129 Wireshark from the command line and use the following:
133 This will start Wireshark capturing on interface eth0, more details
134 can be found at: <xref linkend="ChCustCommandLine"/>.
141 <section id="ChCapInterfaceSection">
142 <title>The "Capture Interfaces" dialog box</title>
144 When you select "Interfaces..." from the Capture menu, Wireshark pops
145 up the "Capture Interfaces" dialog box as shown in
146 <xref linkend="ChCapCaptureInterfacesDialog"/>.
147 <warning><title>Warning!</title>
149 As the "Capture Interfaces" dialog is showing live captured data, it is
150 consuming a lot of system ressources. Close this dialog as soon as
151 possible to prevent excessive system load.
154 <note><title>Note!</title>
156 This dialog box will only show the local interfaces Wireshark knows
157 of. As Wireshark might not be able to detect all local interfaces, and it
158 cannot detect the remote interfaces available, there could be more capture
159 interfaces available than listed.
162 <figure id="ChCapCaptureInterfacesDialog">
163 <title>The "Capture Interfaces" dialog box</title>
164 <graphic entityref="WiresharkCaptureInterfacesDialog" format="PNG"/>
167 <varlistentry><term><command>Description</command></term>
170 The interface description provided by the operating system.
174 <varlistentry><term><command>IP</command></term>
177 The first IP address Wireshark could resolve from this interface.
178 If no address could be resolved (e.g. no DHCP server available),
179 "unknown" will be displayed. If more than one IP address could be
180 resolved, only the first is shown (unpredictable which one in that
185 <varlistentry><term><command>Packets</command></term>
188 The number of packets captured from this interface, since this
189 dialog was opened. Will be greyed out, if no packet was captured
194 <varlistentry><term><command>Packets/s</command></term>
197 Number of packets captured in the last second. Will be greyed out,
198 if no packet was captured in the last second.
202 <varlistentry><term><command>Stop</command></term>
205 Stop a currently running capture.
209 <varlistentry><term><command>Capture</command></term>
212 Start a capture on this interface immediately, using the settings
213 from the last capture.
217 <varlistentry><term><command>Prepare</command></term>
220 Open the Capture Options dialog with this interface selected, see
221 <xref linkend="ChCapCaptureOptions"/>.
225 <varlistentry><term><command>Close</command></term>
228 Close this dialog box.
236 <section id="ChCapCaptureOptions">
237 <title>The "Capture Options" dialog box</title>
239 When you select Start... from the Capture menu (or use the corresponding
240 item in the "Main" toolbar), Wireshark pops
241 up the "Capture Options" dialog box as shown in
242 <xref linkend="ChCapCaptureOptionsDialog"/>.
244 <figure id="ChCapCaptureOptionsDialog">
245 <title>The "Capture Options" dialog box</title>
246 <graphic entityref="WiresharkCaptureOptionsDialog" format="JPG"/>
248 <tip><title>Tip!</title>
250 If you are unsure which options to choose in this dialog box, just try
251 keeping the defaults as this should work well in many cases.
255 You can set the following fields in this dialog box:
257 <section><title>Capture frame</title>
259 <varlistentry><term><command>Interface</command></term>
262 This field specifies the interface you want to capture on.
263 You can only capture on one interface, and you can only
264 capture on interfaces that Wireshark has found on the
265 system. It is a drop-down list, so simply click on the
266 button on the right hand side and select the interface you
267 want. It defaults to the first non-loopback interface that
268 supports capturing, and if there are none, the first
269 loopback interface. On some systems, loopback interfaces
270 cannot be used for capturing (loopback interfaces are not available
271 on Windows platforms).
274 This field performs the same function as the
275 <command>-i <interface></command> command line option.
279 <varlistentry><term><command>IP address</command></term>
282 The IP address(es) of the selected interface. If no address could
283 be resolved from the system, "unknown" will be shown.
287 <varlistentry><term><command>Link-layer header type</command></term>
290 Unless you are in the rare situation that you need this, just keep
291 the default. For a detailed description, see
292 <xref linkend="ChCapLinkLayerHeader"/>
296 <varlistentry><term><command>Buffer size: n megabyte(s)</command></term>
299 Enter the buffer size to be used while capturing. This is the size
300 of the kernel buffer which will keep the captured packets, until
301 they are written to disk. If you encounter packet drops, try
302 increasing this value.
306 <para>This option is only available on Windows platforms.</para>
312 <command>Capture packets in promiscuous mode</command>
316 This checkbox allows you to specify that Wireshark
317 should put the interface in promiscuous mode when capturing.
318 If you do not specify this, Wireshark will only capture the
319 packets going to or from your computer (not
320 all packets on your LAN segment).
325 If some other process has put the interface in
326 promiscuous mode you may be capturing in promiscuous
327 mode even if you turn off this option
333 Even in promiscuous mode you still won't necessarily see all packets
334 on your LAN segment, see <ulink url="&WiresharkFAQPromiscPage;"/> for
335 some more explanations.
340 <varlistentry><term><command>Limit each packet to n bytes</command></term>
343 This field allows you to specify the maximum amount of
344 data that will be captured for each packet, and is
345 sometimes referred to as the <command>snaplen</command>. If disabled,
346 the default is 65535, which will be sufficient for most
347 protocols. Some rules of thumb:
352 If you are unsure, just keep the default value.
357 If you don't need all of the data in a packet - for example, if you
358 only need the link-layer, IP, and TCP headers - you might want to
359 choose a small snapshot length, as less CPU time is required for
360 copying packets, less buffer space is required for packets, and thus
361 perhaps fewer packets will be dropped if traffic is very heavy.
366 If you don't capture all of the data in a packet, you might find that
367 the packet data you want is in the part that's dropped, or that
368 reassembly isn't possible as the data required for reassembly is
375 <varlistentry><term><command>Capture Filter</command></term>
378 This field allows you to specify a capture filter.
379 Capture filters are discussed in more details in
380 <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or
384 You can also click on the button labelled Capture Filter, and Wireshark
385 will bring up the Capture Filters dialog box and allow you to create
386 and/or select a filter. Please see
387 <xref linkend="ChWorkDefineFilterSection"/>
393 <section><title>Capture File(s) frame</title>
395 An explanation about capture file usage can be found in <xref
396 linkend="ChCapCaptureFiles"/>.
399 <varlistentry><term><command>File</command></term>
402 This field allows you to specify the file name that will be
403 used for the capture file. This field is left blank by default.
404 If the field is left blank, the capture data will be stored in a
405 temporary file, see <xref linkend="ChCapCaptureFiles"/> for
409 You can also click on the button to the right of this field to
410 browse through the filesystem.
414 <varlistentry><term><command>Use multiple files</command></term>
417 Instead of using a single file, Wireshark will automatically switch
418 to a new one, if a specific trigger condition is reached.
422 <varlistentry><term><command>Next file every n megabyte(s)</command></term>
425 Multiple files only: Switch to the next file after the given
426 number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been
431 <varlistentry><term><command>Next file every n minute(s)</command></term>
434 Multiple files only: Switch to the next file after the given
435 number of second(s)/minutes(s)/hours(s)/days(s) have elapsed.
439 <varlistentry><term><command>Ring buffer with n files</command></term>
442 Multiple files only: Form a ring buffer of the capture files, with
443 the given number of files.
447 <varlistentry><term><command>Stop capture after n file(s)</command></term>
450 Multiple files only: Stop capturing after switching to the next
451 file the given number of times.
457 <section><title>Stop Capture... frame</title>
459 <varlistentry><term><command>... after n packet(s)</command></term>
462 Stop capturing after the given number of packets have been
467 <varlistentry><term><command>... after n megabytes(s)</command></term>
470 Stop capturing after the given number of
471 byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured.
472 This option is greyed out, if "Use multiple files" is selected.
476 <varlistentry><term><command>... after n minute(s)</command></term>
479 Stop capturing after the given number of
480 second(s)/minutes(s)/hours(s)/days(s) have elapsed.
486 <section><title>Display Options frame</title>
490 <command>Update list of packets in real time</command>
494 This option allows you to specify that Wireshark
495 should update the packet list pane in real time. If you
496 do not specify this, Wireshark does not display any
497 packets until you stop the capture. When you check this,
498 Wireshark captures in a separate process
499 and feeds the captures to the display process.
505 <command>Automatic scrolling in live capture</command>
509 This option allows you to specify that Wireshark
510 should scroll the packet list pane as new packets come
511 in, so you are always looking at the last packet. If you
512 do not specify this, Wireshark simply adds new packets onto
513 the end of the list, but does not scroll the packet list
514 pane. This option is greyed out if
515 "Update list of packets in real time" is disabled.
521 <command>Hide capture info dialog</command>
525 If this option is checked, the following capture info dialog will be
532 <section><title>Name Resolution frame</title>
535 <term><command>Enable MAC name resolution</command></term>
538 This option allows you to control whether or not
539 Wireshark translates MAC addresses into names, see
540 <xref linkend="ChAdvNameResolutionSection"/>.
545 <term><command>Enable network name resolution</command></term>
548 This option allows you to control whether or not
549 Wireshark translates network addresses into names, see
550 <xref linkend="ChAdvNameResolutionSection"/>.
555 <term><command>Enable transport name resolution</command></term>
558 This option allows you to control whether or not
559 Wireshark translates transport addresses into protocols, see
560 <xref linkend="ChAdvNameResolutionSection"/>.
566 <section><title>Buttons</title>
568 Once you have set the values you desire and have selected the
569 options you need, simply click on <command>OK</command> to commence the
570 capture, or <command>Cancel</command> to cancel the capture.
573 If you start a capture, Wireshark allows you to stop capturing when
574 you have enough packets captured, for details see
575 <xref linkend="ChCapRunningSection"/>.
580 <section id="ChCapCaptureFiles"><title>Capture files and file modes</title>
582 While capturing, the underlying libpcap capturing engine will grab the
583 packets from the network card and keep the packet data in a (relatively)
584 small kernel buffer. This data is read by Wireshark and saved into
585 the capture file(s) the user specified.
589 Different modes of operation are available when saving this packet data to
593 <tip><title>Tip!</title>
595 Working with large files (several 100 MB's) can be quite slow. If you plan
596 to do a long term capture or capturing from a high traffic network, think
597 about using one of the "Multiple files" options. This will spread the
598 captured packets over several smaller files which can be much more
599 pleasant to work with.
602 <note><title>Note!</title>
604 Using Multiple files may cut context related information.
605 Wireshark keeps context information of the loaded packet data, so it can
606 report context related problems (like a stream error) and keeps information
607 about context related protocols (e.g. where data is exchanged at the
608 establishing phase and only referred to in later packets).
609 As it keeps this information only for the loaded file, using one of
610 the multiple file modes may cut these contexts. If the establishing phase
611 is saved in one file and the things you would like to see is in another,
612 you might not see some of the valuable context related information.
615 <tip><title>Tip!</title>
617 Information about the folders used for the capture file(s), can be found
618 in <xref linkend="AppFiles"/>.
622 <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title>
624 <colspec colnum="1" colwidth="72pt"/>
625 <colspec colnum="2" colwidth="80pt"/>
626 <colspec colnum="3" colwidth="80pt"/>
627 <colspec colnum="4" colwidth="80pt"/>
630 <entry>"File" option</entry>
631 <entry>"Use multiple files" option</entry>
632 <entry>"Ring buffer with n files" option</entry>
634 <entry>Resulting filename(s) used</entry>
642 <entry><command>Single temporary file</command></entry>
643 <entry>etherXXXXXX (where XXXXXX is a unique number)</entry>
646 <entry>foo.cap</entry>
649 <entry><command>Single named file</command></entry>
650 <entry>foo.cap</entry>
653 <entry>foo.cap</entry>
656 <entry><command>Multiple files, continuous</command></entry>
657 <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
660 <entry>foo.cap</entry>
663 <entry><command>Multiple files, ring buffer</command></entry>
664 <entry>foo_00001_20040205110102.cap, foo_00002_20040205110102.cap, ...</entry>
671 <term><command>Single temporary file</command></term>
674 A temporary file will be created and used (this is the default). After the
675 capturing is stopped, this file can be saved later under a user specified
681 <term><command>Single named file</command></term>
684 A single capture file will be used. If you want to place the new capture
685 file to a specific folder, choose this mode.
690 <term><command>Multiple files, continuous</command></term>
693 Like the "Single named file" mode, but a new file is created and used,
694 after reaching one of the multiple file switch conditions (one of the
695 "Next file every ..." values).
700 <term><command>Multiple files, ring buffer</command></term>
703 Much like "Multiple files continuous", reaching one of the multiple files
704 switch conditions (one of the "Next file every ..." values) will switch
705 to the next file. This will be a newly created file if value of "Ring
706 buffer with n files" is not reached, otherwise it will replace the oldest
707 of the formerly used files (thus forming a "ring").
710 This mode will limit the maximum disk usage, even for an unlimited amount of
711 capture input data, keeping the latest captured data.
718 <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title>
720 In the usual case, you won't have to choose this link-layer header type.
721 The following paragraphs describe the exceptional cases, where
722 selecting this type is possible, so you will have a guide what to do:
725 If you are capturing on an 802.11 device on some versions of BSD, this
726 might offer a choice of "Ethernet" or "802.11". "Ethernet" will cause
727 the captured packets to have fake Ethernet headers; "802.11" will cause
728 them to have IEEE 802.11 headers. Unless the capture needs to be read by
729 an application that doesn't support 802.11 headers, you should select
733 If you are capturing on an Endace DAG card connected to a synchronous
734 serial line, this might offer a choice of "PPP over serial" or
735 "Cisco HDLC"; if the protocol on the serial line is PPP, select
736 "PPP over serial", and if the protocol on the serial line is Cisco HDLC,
740 If you are capturing on an Endace DAG card connected to an ATM network,
741 this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM".
742 If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if
743 the capture needs to be read by an application that doesn't support SunATM
744 headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM".
747 If you are capturing on an Ethernet device, this might offer a choice of
748 "Ethernet" or "DOCSIS". If you are capturing traffic from a Cisco Cable
749 Modem Termination System that is putting DOCSIS traffic onto the Ethernet
750 to be captured, select "DOCSIS", otherwise select "Ethernet".
754 <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title>
756 Wireshark uses the libpcap filter language for capture filters.
757 This is explained in the tcpdump man page, which can be hard to
758 understand, so it's explained here to some extent.
763 You will find a lot of Capture Filter examples at <ulink
764 url="&WiresharkWikiCaptureFiltersPage;">&WiresharkWikiCaptureFiltersPage;</ulink>.
768 You enter the capture filter into the Filter field of the Wireshark
769 Capture Options dialog box, as shown in
770 <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline
771 of the syntax of the <command>tcpdump</command> capture filter language.
772 See the expression option at the tcpdump manual page for details:
773 <ulink url="&TcpdumpManpage;"/>.
776 A capture filter takes the form of a series of primitive expressions
777 connected by conjunctions (<command>and/or</command>) and optionally
778 preceded by <command>not</command>:
780 [not] <command>primitive</command> [and|or [not] <command>primitive</command> ...]
782 An example is shown in <xref linkend="ChCapExFilt1"/>.
784 <example id="ChCapExFilt1">
786 A capture filter for telnet than captures traffic to and from a
790 tcp port 23 and host 10.0.0.5
793 This example captures telnet traffic to and from the host
794 10.0.0.5, and shows how to use two primitives and the
795 <command>and</command> conjunction. Another example is shown in
796 <xref linkend="ChCapExFilt2"/>, and shows how to capture all
797 telnet traffic except that from 10.0.0.5.
798 <example id="ChCapExFilt2">
800 Capturing all telnet traffic not from 10.0.0.5</title>
802 tcp port 23 and not host 10.0.0.5
808 XXX - add examples to the following list.
811 A primitive is simply one of the following:
814 <term><command>[src|dst] host <host></command></term>
817 This primitive allows you to filter on a host IP
818 address or name. You can optionally precede the
819 primitive with the keyword <command>src|dst</command>
820 to specify that you are only interested in source or
821 destination addresses. If these are not present,
822 packets where the specified address appears as either
823 the source or the destination address will be selected.
829 <command>ether [src|dst] host <ehost></command>
833 This primitive allows you to filter on Ethernet host
834 addresses. You can optionally include the keyword
835 <command>src|dst</command> between the keywords
836 <command>ether</command> and <command>host</command>
837 to specify that you are only interested in source
838 or destination addresses. If these are not present,
839 packets where the specified address appears in either
840 the source or destination address will be selected.
845 <term><command>gateway host <host></command></term>
848 This primitive allows you to filter on packets that
849 used <command>host</command> as a gateway. That is, where
850 the Ethernet source or destination was
851 <command>host</command> but neither the source nor
852 destination IP address was <command>host</command>.
859 [src|dst] net <net> [{mask <mask>}|{len <len>}]
864 This primitive allows you to filter on network numbers.
865 You can optionally precede this primitive with the
866 keyword <command>src|dst</command> to specify that you
867 are only interested in a source or destination network.
868 If neither of these are present, packets will be
869 selected that have the specified network in either the
870 source or destination address. In addition, you can
871 specify either the netmask or the CIDR prefix for the
872 network if they are different from your own.
878 <command>[tcp|udp] [src|dst] port <port></command>
882 This primitive allows you to filter on TCP and UDP port
883 numbers. You can optionally precede this primitive with
884 the keywords <command>src|dst</command> and
885 <command>tcp|udp</command> which allow you to specify
886 that you are only interested in source or destination
887 ports and TCP or UDP packets respectively. The
888 keywords <command>tcp|udp</command> must appear before
889 <command>src|dst</command>.
892 If these are not specified, packets will be selected
893 for both the TCP and UDP protocols and when the
894 specified address appears in either the source or
895 destination port field.
900 <term><command>less|greater <length></command></term>
903 This primitive allows you to filter on packets whose
904 length was less than or equal to the specified length,
905 or greater than or equal to the specified length,
911 <term><command>ip|ether proto <protocol></command></term>
914 This primitive allows you to filter on the specified
915 protocol at either the Ethernet layer or the IP layer.
920 <term><command>ether|ip broadcast|multicast</command></term>
923 This primitive allows you to filter on either
924 Ethernet or IP broadcasts or multicasts.
929 <term><command><expr> relop <expr></command></term>
932 This primitive allows you to create complex filter
933 expressions that select bytes or ranges of bytes in
934 packets. Please see the tcpdump man page at
935 <ulink url="&TcpdumpManpage;"/> for more details.
943 <section id="ChCapRunningSection"><title>While a Capture is running ...</title>
945 While a capture is running, the following dialog box is shown:
946 <figure id="ChCapCaptureInfoDialog">
947 <title>The "Capture Info" dialog box</title>
948 <graphic entityref="WiresharkCaptureInfoDialog" format="JPG"/>
950 This dialog box will inform you about the number of captured packets and
951 the time since the capture was started. The selection which protocols
952 are counted cannot be changed.
954 <tip><title>Tip!</title>
956 This Capture Info dialog box can be hidden, using the "Hide capture info
957 dialog" option in the Capture Options dialog box.
960 <section id="ChCapStopSection"><title>Stop the running capture</title>
962 A running capture session will be stopped in one of the following ways:
966 "<inlinegraphic entityref="WiresharkToolbarStop" format="PNG"/>
967 Stop" button from the <command>Capture Info dialog box
970 <note><title>Note!</title>
972 The Capture Info dialog box might be hidden, if the option "Hide capture
973 info dialog" is used.
978 <para>Using the <command>menu item</command>
979 "Capture/<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
984 <para>Using the <command>toolbar item</command>
985 "<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
990 <para>Pressing the accelerator keys: <command>Ctrl+E</command>.
994 <para>The capture will be automatically stopped, if one of the
995 <command>Stop Conditions</command> is exceeded, e.g. the maximum amount
996 of data was captured.
1002 <section id="ChCapRestartSection"><title>Restart a running capture</title>
1004 A running capture session can be restarted with the same capture options
1005 than the last time, this will remove all packets previously captured.
1006 This can be useful, if some uninteresting packets are captured and
1007 there's no need to keep them.
1010 Restart is a convenience function and
1011 equivalent to a capture stop following by an immediate capture start.
1012 A restart can be triggered in one of the following ways:
1015 <para>Using the <command>menu item</command>
1016 "Capture/<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
1021 <para>Using the <command>toolbar item</command>
1022 "<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
1032 <!-- End of WSUG Chapter Capture -->