| blob | 7823c823e07d286c54eb153a86c319ad84212600 |
1 <!-- WSUG Chapter Capture -->
2 <!-- $Id$ -->
4 <chapter id="ChapterCapture">
5 <title>Capturing Live Network Data</title>
6 <section id="ChCapIntroduction">
7 <title>Introduction</title>
8 <para>
9 Capturing live network data is one of the major features of Wireshark.
10 </para>
11 <para>
12 The Wireshark capture engine provides the following features:
13 </para>
14 <para>
15 <itemizedlist>
16 <listitem><para>
17 Capture from different kinds of network hardware (Ethernet, Token Ring,
18 ATM, ...).
19 </para></listitem>
20 <listitem><para>
21 Stop the capture on different triggers like: amount of captured data,
22 captured time, captured number of packets.
23 </para></listitem>
24 <listitem><para>
25 Simultaneously show decoded packets while Wireshark keeps on capturing.
26 </para></listitem>
27 <listitem><para>
28 Filter packets, reducing the amount of data to be captured, see <xref
29 linkend="ChCapCaptureFilterSection"/>.
30 </para></listitem>
31 <listitem><para>
32 Capturing into multiple files while doing a long term capture, and in
33 addition the option to form a ringbuffer of these files, keeping only
34 the last x files, useful for a "very long term" capture, see <xref
35 linkend="ChCapCaptureFiles"/>.
36 </para></listitem>
37 <listitem><para>
38 Simultaneous capturing from multiple network interfaces.
39 </para></listitem>
40 </itemizedlist>
41 The capture engine still lacks the following features:
42 <itemizedlist>
43 <listitem><para>
44 Stop capturing (or doing some other action), depending on the captured
45 data.
46 </para></listitem>
47 </itemizedlist>
48 </para>
49 </section>
51 <section id="ChCapPrerequisitesSection"><title>Prerequisites</title>
52 <para>
53 Setting up Wireshark to capture packets for the first time can be tricky.
54 </para>
55 <tip><title>Tip!</title><para>
56 A comprehensive guide "How To setup a Capture" is available at:
57 <ulink url="&WiresharkWikiPage;/CaptureSetup">&WiresharkWikiPage;/CaptureSetup</ulink>.
58 </para></tip>
59 <para>
60 Here are some common pitfalls:
61 <itemizedlist>
62 <listitem>
63 <para>
64 You need to have root / Administrator privileges to start a live
65 capture.
66 </para>
67 </listitem>
68 <listitem>
69 <para>
70 You need to choose the right network interface to capture packet data
71 from.
72 </para>
73 </listitem>
74 <listitem>
75 <para>
76 You need to capture at the right place in the network to see the
77 traffic you want to see.
78 </para>
79 </listitem>
80 <listitem>
81 <para>
82 ... and a lot more!.
83 </para>
84 </listitem>
85 </itemizedlist>
86 </para>
87 <para>
88 If you have any problems setting up your capture environment, you should
89 have a look at the guide mentioned above.
90 </para>
91 </section>
93 <section id="ChCapCapturingSection"><title>Start Capturing</title>
94 <para>
95 One of the following methods can be used to start capturing packets with
96 Wireshark:
97 <itemizedlist>
98 <listitem>
99 <para>
100 You can get an overview of the available local interfaces using the
101 "<inlinegraphic entityref="WiresharkToolbarCaptureInterfaces" format="PNG"/>
102 Capture Interfaces" dialog box, see
103 <xref linkend="ChCapCaptureInterfacesDialogWin32"/> or
104 <xref linkend="ChCapCaptureInterfacesDialog"/>. You can start a
105 capture from this dialog box, using (one of) the "Capture" button(s).
106 </para>
107 </listitem>
108 <listitem>
109 <para>
110 You can start capturing using the
111 "<inlinegraphic entityref="WiresharkToolbarCaptureOptions" format="PNG"/>
112 Capture Options" dialog box, see
113 <xref linkend="ChCapCaptureOptionsDialog"/>.
114 </para>
115 </listitem>
116 <listitem>
117 <para>
118 If you have selected the right capture options before, you can
119 immediately start a capture using the
120 "<inlinegraphic entityref="WiresharkToolbarCaptureStart" format="PNG"/>
121 Capture Start" menu / toolbar item. The capture
122 process will start immediately.
123 </para>
124 </listitem>
125 <listitem>
126 <para>
127 If you already know the name of the capture interface, you can start
128 Wireshark from the command line and use the following:
129 <programlisting>
130 wireshark -i eth0 -k
131 </programlisting>
132 This will start Wireshark capturing on interface eth0, more details
133 can be found at: <xref linkend="ChCustCommandLine"/>.
134 </para>
135 </listitem>
136 </itemizedlist>
137 </para>
138 </section>
140 <section id="ChCapInterfaceSection">
141 <title>The "Capture Interfaces" dialog box</title>
142 <para>
143 When you select "Interfaces..." from the Capture menu, Wireshark pops
144 up the "Capture Interfaces" dialog box as shown in
145 <xref linkend="ChCapCaptureInterfacesDialogWin32"/> or
146 <xref linkend="ChCapCaptureInterfacesDialog"/>.
147 <warning><title>This dialog consumes lots of system resources!</title>
148 <para>
149 As the "Capture Interfaces" dialog is showing live captured data, it is
150 consuming a lot of system resources. Close this dialog as soon as
151 possible to prevent excessive system load.
152 </para>
153 </warning>
154 <note><title>Not all available interfaces may be displayed!</title>
155 <para>
156 This dialog box will only show the local interfaces Wireshark knows
157 of. It will not show interfaces marked as hidden in <xref linkend="ChCustInterfaceOptionsSection"/>.
158 As Wireshark might not be able to detect all local interfaces, and it
159 cannot detect the remote interfaces available, there could be more capture
160 interfaces available than listed.
161 </para>
162 </note>
163 </para>
164 <para>
165 As it is possible to simultaneously capture packets from multiple interfaces,
166 the toggle buttons can be used to select one or more interfaces.
167 </para>
168 <figure id="ChCapCaptureInterfacesDialogWin32">
169 <title>The "Capture Interfaces" dialog box on Microsoft Windows</title>
170 <graphic entityref="WiresharkCaptureInterfacesDialogWin32" format="PNG"/>
171 </figure>
172 <figure id="ChCapCaptureInterfacesDialog">
173 <title>The "Capture Interfaces" dialog box on Unix/Linux</title>
174 <graphic entityref="WiresharkCaptureInterfacesDialog" format="PNG"/>
175 </figure>
176 <variablelist>
177 <varlistentry><term><command>Device (Unix/Linux only)</command></term>
178 <listitem>
179 <para>
180 The interface device name.
181 </para>
182 </listitem>
183 </varlistentry>
184 <varlistentry><term><command>Description</command></term>
185 <listitem>
186 <para>
187 The interface description provided by the operating system, or the
188 user defined comment added in <xref linkend="ChCustInterfaceOptionsSection"/>.
189 </para>
190 </listitem>
191 </varlistentry>
192 <varlistentry><term><command>IP</command></term>
193 <listitem>
194 <para>
195 The first IP address Wireshark could find for this interface.
196 You can click on the address to cycle through other addresses
197 assigned to it, if available.
198 If no address could be found "none" will be displayed.
199 </para>
200 </listitem>
201 </varlistentry>
202 <varlistentry><term><command>Packets</command></term>
203 <listitem>
204 <para>
205 The number of packets captured from this interface, since this
206 dialog was opened. Will be greyed out, if no packet was captured
207 in the last second.
208 </para>
209 </listitem>
210 </varlistentry>
211 <varlistentry><term><command>Packets/s</command></term>
212 <listitem>
213 <para>
214 Number of packets captured in the last second. Will be greyed out,
215 if no packet was captured in the last second.
216 </para>
217 </listitem>
218 </varlistentry>
219 <varlistentry><term><command>Stop</command></term>
220 <listitem>
221 <para>
222 Stop a currently running capture.
223 </para>
224 </listitem>
225 </varlistentry>
226 <varlistentry><term><command>Start</command></term>
227 <listitem>
228 <para>
229 Start a capture on all selected interfaces immediately, using the settings
230 from the last capture or the default settings, if no options have been
231 set.
232 </para>
233 </listitem>
234 </varlistentry>
235 <varlistentry><term><command>Options</command></term>
236 <listitem>
237 <para>
238 Open the Capture Options dialog with the marked interfaces selected, see
239 <xref linkend="ChCapCaptureOptions"/>.
240 </para>
241 </listitem>
242 </varlistentry>
243 <varlistentry><term><command>Details (Microsoft Windows only)</command></term>
244 <listitem>
245 <para>
246 Open a dialog with detailed information about the interface, see
247 <xref linkend="ChCapInterfaceDetailsSection"/>.
248 </para>
249 </listitem>
250 </varlistentry>
251 <varlistentry><term><command>Help</command></term>
252 <listitem>
253 <para>
254 Show this help page.
255 </para>
256 </listitem>
257 </varlistentry>
258 <varlistentry><term><command>Close</command></term>
259 <listitem>
260 <para>
261 Close this dialog box.
262 </para>
263 </listitem>
264 </varlistentry>
265 </variablelist>
266 </section>
268 <section id="ChCapCaptureOptions">
269 <title>The "Capture Options" dialog box</title>
270 <para>
271 When you select Options... from the Capture menu (or use the corresponding
272 item in the "Main" toolbar), Wireshark pops
273 up the "Capture Options" dialog box as shown in
274 <xref linkend="ChCapCaptureOptionsDialog"/>.
275 </para>
276 <figure id="ChCapCaptureOptionsDialog">
277 <title>The "Capture Options" dialog box</title>
278 <graphic entityref="WiresharkCaptureOptionsDialog"/>
279 </figure>
280 <tip><title>Tip!</title>
281 <para>
282 If you are unsure which options to choose in this dialog box, just try
283 keeping the defaults as this should work well in many cases.
284 </para>
285 </tip>
286 <section><title>Capture frame</title>
287 <para>
288 The table shows the settings for all available interfaces:
289 <itemizedlist>
290 <listitem>
291 <para>
292 The name of the interface and its IP addresses. If no address could
293 be resolved from the system, "none" will be shown.
294 </para>
295 <note>
296 <title>Note</title>
297 <para>loopback interfaces are not available on Windows platforms.</para>
298 </note>
299 </listitem>
300 <listitem>
301 <para>
302 The link-layer header type.
303 </para>
304 </listitem>
305 <listitem>
306 <para>
307 The information whether promicuous mode is enabled or disabled.
308 </para>
309 </listitem>
310 <listitem>
311 <para>
312 The maximum amount of data that will be captured for each packet.
313 The default value is set to the 65535 bytes.
314 </para>
315 </listitem>
316 <listitem>
317 <para>
318 The size of the kernel buffer that is reserved to keep the captured packets.
319 </para>
320 </listitem>
321 <listitem>
322 <para>
323 The information whether packets will be captured in monitor mode (Unix/Linux only).
324 </para>
325 </listitem>
326 <listitem>
327 <para>
328 The chosen capture filter.
329 </para>
330 </listitem>
331 </itemizedlist>
332 By marking the
333 checkboxes in the first column the interfaces are selected to be
334 captured from. By double-clicking on an interface the "Edit Interface Settings"
335 dialog box as shown in
336 <xref linkend="ChCapEditInterfacesSettingsDialog"/> will be opened.
337 </para>
338 <variablelist>
339 <varlistentry>
340 <term>
341 <command>Capture on all interfaces</command>
342 </term>
343 <listitem>
344 <para>
345 As Wireshark can capture on multiple interfaces, it is possible to choose to capture on all available interfaces.
346 </para>
347 </listitem>
348 </varlistentry>
349 <varlistentry>
350 <term>
351 <command>Capture all packets in promiscuous mode</command>
352 </term>
353 <listitem>
354 <para>
355 This checkbox allows you to specify that Wireshark
356 should put all interfaces in promiscuous mode when capturing.
357 </para>
358 </listitem>
359 </varlistentry>
360 <varlistentry><term><command>Capture Filter</command></term>
361 <listitem>
362 <para>
363 This field allows you to specify a capture filter for all interfaces
364 that are currently selected. Once a filter has been entered in this field,
365 the newly selected interfaces will inherit the filter.
366 Capture filters are discussed in more details in
367 <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or
368 no filter.
369 </para>
370 <para>
371 You can also click on the button labeled "Capture Filter", and Wireshark
372 will bring up the Capture Filters dialog box and allow you to create
373 and/or select a filter. Please see
374 <xref linkend="ChWorkDefineFilterSection"/>
375 </para>
376 </listitem>
377 </varlistentry>
378 <varlistentry><term><command>Compile selected BPFs</command></term>
379 <listitem>
380 <para>
381 This button allows you to compile the capture filter into BPF code and
382 pop up a window showing you the resulting pseudo code. This can help in
383 understanding the working of the capture filter you created.
384 The "Compile selected BPFs" button leads you to
385 <xref linkend="ChCapCompileSelectedBpfsDialog"/>.
386 </para>
387 <tip><title>Tip!</title>
388 <para>
389 The execution of BPFs can be sped up on Linux by turning on BPF JIT by
390 executing <programlisting>echo 1 >/proc/sys/net/core/bpf_jit_enable</programlisting>
391 if it is not enabled already. To make the change persistent you can use sysfsutils
392 <ulink url="&SysFsUtils;">sysfsutils</ulink>.
393 </para>
394 </tip>
395 </listitem>
396 </varlistentry>
397 <varlistentry>
398 <term>
399 <command>Manage Interfaces</command>
400 </term>
401 <listitem>
402 <para>
403 The "Manage Interfaces" button leads you to
404 <xref linkend="ChCapManageInterfacesDialog"/> where pipes can be defined,
405 local interfaces scanned or hidden, or remote interfaces added (Windows only).
406 </para>
407 </listitem>
408 </varlistentry>
409 </variablelist>
410 </section>
411 <section><title>Capture File(s) frame</title>
412 <para>
413 An explanation about capture file usage can be found in <xref
414 linkend="ChCapCaptureFiles"/>.
415 </para>
416 <variablelist>
417 <varlistentry><term><command>File</command></term>
418 <listitem>
419 <para>
420 This field allows you to specify the file name that will be
421 used for the capture file. This field is left blank by default.
422 If the field is left blank, the capture data will be stored in a
423 temporary file, see <xref linkend="ChCapCaptureFiles"/> for
424 details.
425 </para>
426 <para>
427 You can also click on the button to the right of this field to
428 browse through the filesystem.
429 </para>
430 </listitem>
431 </varlistentry>
432 <varlistentry><term><command>Use multiple files</command></term>
433 <listitem>
434 <para>
435 Instead of using a single file, Wireshark will automatically switch
436 to a new one, if a specific trigger condition is reached.
437 </para>
438 </listitem>
439 </varlistentry>
440 <varlistentry>
441 <term>
442 <command>Use pcap-ng format</command>
443 </term>
444 <listitem>
445 <para>
446 This checkbox allows you to specify that Wireshark saves the captured
447 packets in pcap-ng format. This next generation capture file format is
448 currently in development. If more than one interface is chosen for
449 capturing, this checkbox is set by default. See
450 <ulink url="&WiresharkWikiPcapNgPage;"/> for more details on pcap-ng.
451 </para>
452 </listitem>
453 </varlistentry>
454 <varlistentry><term><command>Next file every n megabyte(s)</command></term>
455 <listitem>
456 <para>
457 Multiple files only: Switch to the next file after the given
458 number of byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been
459 captured.
460 </para>
461 </listitem>
462 </varlistentry>
463 <varlistentry><term><command>Next file every n minute(s)</command></term>
464 <listitem>
465 <para>
466 Multiple files only: Switch to the next file after the given
467 number of second(s)/minutes(s)/hours(s)/days(s) have elapsed.
468 </para>
469 </listitem>
470 </varlistentry>
471 <varlistentry><term><command>Ring buffer with n files</command></term>
472 <listitem>
473 <para>
474 Multiple files only: Form a ring buffer of the capture files, with
475 the given number of files.
476 </para>
477 </listitem>
478 </varlistentry>
479 <varlistentry><term><command>Stop capture after n file(s)</command></term>
480 <listitem>
481 <para>
482 Multiple files only: Stop capturing after switching to the next
483 file the given number of times.
484 </para>
485 </listitem>
486 </varlistentry>
487 </variablelist>
488 </section>
489 <section><title>Stop Capture... frame</title>
490 <variablelist>
491 <varlistentry><term><command>... after n packet(s)</command></term>
492 <listitem>
493 <para>
494 Stop capturing after the given number of packets have been
495 captured.
496 </para>
497 </listitem>
498 </varlistentry>
499 <varlistentry><term><command>... after n megabytes(s)</command></term>
500 <listitem>
501 <para>
502 Stop capturing after the given number of
503 byte(s)/kilobyte(s)/megabyte(s)/gigabyte(s) have been captured.
504 This option is greyed out, if "Use multiple files" is selected.
505 </para>
506 </listitem>
507 </varlistentry>
508 <varlistentry><term><command>... after n minute(s)</command></term>
509 <listitem>
510 <para>
511 Stop capturing after the given number of
512 second(s)/minutes(s)/hours(s)/days(s) have elapsed.
513 </para>
514 </listitem>
515 </varlistentry>
516 </variablelist>
517 </section>
518 <section><title>Display Options frame</title>
519 <variablelist>
520 <varlistentry>
521 <term>
522 <command>Update list of packets in real time</command>
523 </term>
524 <listitem>
525 <para>
526 This option allows you to specify that Wireshark
527 should update the packet list pane in real time. If you
528 do not specify this, Wireshark does not display any
529 packets until you stop the capture. When you check this,
530 Wireshark captures in a separate process
531 and feeds the captures to the display process.
532 </para>
533 </listitem>
534 </varlistentry>
535 <varlistentry>
536 <term>
537 <command>Automatic scrolling in live capture</command>
538 </term>
539 <listitem>
540 <para>
541 This option allows you to specify that Wireshark
542 should scroll the packet list pane as new packets come
543 in, so you are always looking at the last packet. If you
544 do not specify this, Wireshark simply adds new packets onto
545 the end of the list, but does not scroll the packet list
546 pane. This option is greyed out if
547 "Update list of packets in real time" is disabled.
548 </para>
549 </listitem>
550 </varlistentry>
551 <varlistentry>
552 <term>
553 <command>Hide capture info dialog</command>
554 </term>
555 <listitem>
556 <para>
557 If this option is checked, the capture info dialog described in
558 <xref linkend="ChCapRunningSection"/> will be hidden.
559 </para>
560 </listitem>
561 </varlistentry>
562 </variablelist>
563 </section>
564 <section><title>Name Resolution frame</title>
565 <variablelist>
566 <varlistentry>
567 <term><command>Enable MAC name resolution</command></term>
568 <listitem>
569 <para>
570 This option allows you to control whether or not
571 Wireshark translates MAC addresses into names, see
572 <xref linkend="ChAdvNameResolutionSection"/>.
573 </para>
574 </listitem>
575 </varlistentry>
576 <varlistentry>
577 <term><command>Enable network name resolution</command></term>
578 <listitem>
579 <para>
580 This option allows you to control whether or not
581 Wireshark translates network addresses into names, see
582 <xref linkend="ChAdvNameResolutionSection"/>.
583 </para>
584 </listitem>
585 </varlistentry>
586 <varlistentry>
587 <term><command>Enable transport name resolution</command></term>
588 <listitem>
589 <para>
590 This option allows you to control whether or not
591 Wireshark translates transport addresses into protocols, see
592 <xref linkend="ChAdvNameResolutionSection"/>.
593 </para>
594 </listitem>
595 </varlistentry>
596 </variablelist>
597 </section>
598 <section><title>Buttons</title>
599 <para>
600 Once you have set the values you desire and have selected the
601 options you need, simply click on <command>Start</command> to commence the
602 capture, or <command>Cancel</command> to cancel the capture.
603 </para>
604 <para>
605 If you start a capture, Wireshark allows you to stop capturing when
606 you have enough packets captured, for details see
607 <xref linkend="ChCapRunningSection"/>.
608 </para>
609 </section>
610 </section>
612 <section id="ChCapEditInterfaceSettingsSection">
613 <title>The "Edit Interface Settings" dialog box</title>
614 <para>
615 If you double-click on an interface in <xref linkend="ChCapCaptureOptionsDialog"/>
616 the following dialog box pops up.
617 </para>
618 <figure id="ChCapEditInterfacesSettingsDialog">
619 <title>The "Edit Interface Settings" dialog box</title>
620 <graphic entityref="WiresharkCaptureEditInterfacesSettingsDialog" format="PNG"/>
621 </figure>
622 <para>
623 You can set the following fields in this dialog box:
624 </para>
625 <variablelist>
626 <varlistentry><term><command>IP address</command></term>
627 <listitem>
628 <para>
629 The IP address(es) of the selected interface. If no address could
630 be resolved from the system, "none" will be shown.
631 </para>
632 </listitem>
633 </varlistentry>
634 <varlistentry><term><command>Link-layer header type</command></term>
635 <listitem>
636 <para>
637 Unless you are in the rare situation that you need this, just keep
638 the default. For a detailed description, see
639 <xref linkend="ChCapLinkLayerHeader"/>
640 </para>
641 </listitem>
642 </varlistentry>
643 <varlistentry><term><command>Wireless settings (Windows only)</command></term>
644 <listitem>
645 <para>
646 Here you can set the settings for wireless capture using the AirPCap adapter.
647 For a detailed description, see the AirPCap Users Guide.
648 </para>
649 </listitem>
650 </varlistentry>
651 <varlistentry><term><command>Remote settings (Windows only)</command></term>
652 <listitem>
653 <para>
654 Here you can set the settings for remote capture.
655 For a detailed description, see <xref linkend="ChCapInterfaceRemoteSection"/>
656 </para>
657 </listitem>
658 </varlistentry>
659 <varlistentry>
660 <term>
661 <command>Capture packets in promiscuous mode</command>
662 </term>
663 <listitem>
664 <para>
665 This checkbox allows you to specify that Wireshark
666 should put the interface in promiscuous mode when capturing.
667 If you do not specify this, Wireshark will only capture the
668 packets going to or from your computer (not
669 all packets on your LAN segment).
670 </para>
671 <note>
672 <title>Note</title>
673 <para>
674 If some other process has put the interface in
675 promiscuous mode you may be capturing in promiscuous
676 mode even if you turn off this option.
677 </para>
678 </note>
679 <note>
680 <title>Note</title>
681 <para>
682 Even in promiscuous mode you still won't necessarily see all packets
683 on your LAN segment, see <ulink url="&WiresharkFAQPromiscPage;"/> for
684 some more explanations.
685 </para>
686 </note>
687 </listitem>
688 </varlistentry>
689 <varlistentry><term><command>Limit each packet to n bytes</command></term>
690 <listitem>
691 <para>
692 This field allows you to specify the maximum amount of
693 data that will be captured for each packet, and is
694 sometimes referred to as the <command>snaplen</command>. If disabled,
695 the value is set to the maximum 65535, which will be sufficient for most
696 protocols. Some rules of thumb:
697 </para>
698 <itemizedlist>
699 <listitem>
700 <para>
701 If you are unsure, just keep the default value.
702 </para>
703 </listitem>
704 <listitem>
705 <para>
706 If you don't need all of the data in a packet - for example, if you
707 only need the link-layer, IP, and TCP headers - you might want to
708 choose a small snapshot length, as less CPU time is required for
709 copying packets, less buffer space is required for packets, and thus
710 perhaps fewer packets will be dropped if traffic is very heavy.
711 </para>
712 </listitem>
713 <listitem>
714 <para>
715 If you don't capture all of the data in a packet, you might find that
716 the packet data you want is in the part that's dropped, or that
717 reassembly isn't possible as the data required for reassembly is
718 missing.
719 </para>
720 </listitem>
721 </itemizedlist>
722 </listitem>
723 </varlistentry>
724 <varlistentry><term><command>Buffer size: n megabyte(s)</command></term>
725 <listitem>
726 <para>
727 Enter the buffer size to be used while capturing. This is the size
728 of the kernel buffer which will keep the captured packets, until
729 they are written to disk. If you encounter packet drops, try
730 increasing this value.
731 </para>
732 </listitem>
733 </varlistentry>
734 <varlistentry>
735 <term>
736 <command>Capture packets in monitor mode (Unix/Linux only)</command>
737 </term>
738 <listitem>
739 <para>
740 This checkbox allows you to setup the Wireless interface to capture
741 all traffic it can receive, not just the traffic on the BSS to which
742 it is associated, which can happen even when you set promiscuous mode.
743 Also it might be necessary to turn this option on in order to see
744 IEEE 802.11 headers and/or radio information from the captured frames.
745 </para>
746 <note>
747 <title>Note</title>
748 <para>
749 In monitor mode the adapter might disassociate itself from the network
750 it was associated to.
751 </para>
752 </note>
753 </listitem>
754 </varlistentry>
755 <varlistentry><term><command>Capture Filter</command></term>
756 <listitem>
757 <para>
758 This field allows you to specify a capture filter.
759 Capture filters are discussed in more details in
760 <xref linkend="ChCapCaptureFilterSection"/>. It defaults to empty, or
761 no filter.
762 </para>
763 <para>
764 You can also click on the button labeled "Capture Filter", and Wireshark
765 will bring up the Capture Filters dialog box and allow you to create
766 and/or select a filter. Please see
767 <xref linkend="ChWorkDefineFilterSection"/>
768 </para>
769 </listitem>
770 </varlistentry>
771 <varlistentry><term><command>Compile BPF</command></term>
772 <listitem>
773 <para>
774 This button allows you to compile the capture filter into BPF code and
775 pop up a window showing you the resulting pseudo code. This can help in
776 understanding the working of the capture filter you created.
777 </para>
778 </listitem>
779 </varlistentry>
780 </variablelist>
781 </section>
783 <section id="ChCapCompileSelectedBpfsSection">
784 <title>The "Compile Results" dialog box</title>
785 <para>
786 This figure shows the compile results of the selected interfaces.
787 </para>
788 <figure id="ChCapCompileSelectedBpfsDialog">
789 <title>The "Compile Results" dialog box</title>
790 <graphic entityref="WiresharkCaptureCompileSelectedBPFsDialog" format="PNG"/>
791 </figure>
792 <para>
793 In the left window the interface names are listed. A green bullet indicates a successful
794 compilation, a red bullet a failure. The results of an individual interface are shown
795 in the right window, when it is selected.
796 </para>
797 </section>
799 <section id="ChCapManageInterfacesSection">
800 <title>The "Add New Interfaces" dialog box</title>
801 <para>
802 As a central point to manage interfaces this dialog box consists of three tabs
803 to add or remove interfaces.
804 </para>
805 <figure id="ChCapManageInterfacesDialog">
806 <title>The "Add New Interfaces" dialog box</title>
807 <graphic entityref="WiresharkCaptureManageInterfacesDialog" format="PNG"/>
808 </figure>
809 <section>
810 <title>Add or remove pipes</title>
811 <figure id="ChCapManageInterfacesPipesDialog">
812 <title>The "Add New Interfaces - Pipes" dialog box</title>
813 <graphic entityref="WiresharkCaptureManageInterfacesPipesDialog" format="PNG"/>
814 </figure>
815 <para>To successfully add a pipe, this pipe must have already been created.
816 Click the "New" button and type the name of the pipe including its path.
817 Alternatively, the "Browse" button can be used to locate the pipe.
818 With the "Save" button the pipe is added to the list of available interfaces.
819 Afterwards, other pipes can be added.
820 </para>
821 <para>
822 To remove a pipe from the list of interfaces it first has to be selected. Then
823 click the "Delete" button.
824 </para>
825 </section>
826 <section>
827 <title>Add or hide local interfaces</title>
828 <figure id="ChCapManageInterfacesLocalDialog">
829 <title>The "Add New Interfaces - Local Interfaces" dialog box</title>
830 <graphic entityref="WiresharkCaptureManageInterfacesLocalDialog" format="PNG"/>
831 </figure>
832 <para>
833 The tab "Local Interfaces" contains a list of available local interfaces, including
834 the hidden ones, which are not shown in the other lists.
835 </para>
836 <para>
837 If a new local interface is added, for example, a wireless interface has been
838 activated, it is not automatically added to the list to prevent the constant scanning
839 for a change in the list of available interfaces. To renew the list a rescan can be done.
840 </para>
841 <para>
842 One way to hide an interface is to change the preferences. If the "Hide" checkbox
843 is activated and the "Apply" button clicked, the interface will not be seen in the
844 lists of the "Capture Options" or "Capture Interfaces" dialog box any more. The changes
845 are also saved in the "Preferences" file.
846 </para>
847 </section>
848 <section>
849 <title>Add or hide remote interfaces</title>
850 <figure id="ChCapManageInterfacesRemoteDialog">
851 <title>The "Add New Interfaces - Remote Interfaces" dialog box</title>
852 <graphic entityref="WiresharkCaptureManageInterfacesRemoteDialog" format="PNG"/>
853 </figure>
854 <para>
855 In this tab interfaces on remote hosts can be added. One or more of these
856 interfaces can be hidden. In contrast to the local interfaces they are not
857 saved in the "Preferences" file.
858 </para>
859 <para>
860 To remove a host including all its interfaces from the list, it has to be
861 selected. Then click the "Delete" button.
862 </para>
863 <para>
864 For a detailed description, see <xref linkend="ChCapInterfaceRemoteSection"/>
865 </para>
866 </section>
867 </section>
869 <section id="ChCapInterfaceRemoteSection">
870 <title>The "Remote Capture Interfaces" dialog box</title>
871 <para>
872 Besides doing capture on local interfaces Wireshark is capable of
873 reaching out across the network to a so called capture daemon or service
874 processes to receive captured data from.
875 </para>
876 <note><title>Microsoft Windows only</title>
877 <para>
878 This dialog and capability is only available on Microsoft Windows. On
879 Linux/Unix you can achieve the same effect (securely) through an SSH
880 tunnel.
881 </para>
882 </note>
883 <para>
884 The Remote Packet Capture Protocol service must first be running on the
885 target platform before Wireshark can connect to it. The easiest way is
886 to install WinPcap from <ulink url="&WinPcapDownloadWebsite;"/> on the
887 target. Once installation is completed go to the Services control panel,
888 find the Remote Packet Capture Protocol service and start it.
889 </para>
890 <note><title>Note</title>
891 <para>
892 Make sure you have outside access to port 2002 on the target platform.
893 This is the port where the Remote Packet Capture Protocol service can
894 be reached, by default.
895 </para>
896 </note>
897 <para>
898 To access the Remote Capture Interfaces dialog use the
899 "Add New Interfaces - Remote" dialog, see
900 <xref linkend="ChCapManageInterfacesRemoteDialog"/>, and select "Add".
901 </para>
902 <section><title>Remote Capture Interfaces</title>
903 <figure id="ChCapInterfaceRemoteDialog">
904 <title>The "Remote Capture Interfaces" dialog box</title>
905 <graphic entityref="WiresharkCaptureOptionsRemoteInterfacesDialog" format="PNG"/>
906 </figure>
907 <para>
908 You have to set the following parameter in this dialog:
909 </para>
911 <variablelist>
912 <varlistentry><term><command>Host</command></term>
913 <listitem>
914 <para>
915 Enter the IP address or host name of the target platform where the
916 Remote Packet Capture Protocol service is listening. The drop down list
917 contains the hosts that have previously been successfully contacted.
918 The list can be emptied by choosing "Clear list" from the drop down list.
919 </para>
920 </listitem>
921 </varlistentry>
922 <varlistentry><term><command>Port</command></term>
923 <listitem>
924 <para>
925 Set the port number where the Remote Packet Capture Protocol service
926 is listening on. Leave open to use the default port (2002).
927 </para>
928 </listitem>
929 </varlistentry>
930 <varlistentry><term><command>Null authentication</command></term>
931 <listitem>
932 <para>
933 Select this if you don't need authentication to take place for a
934 remote capture to be started. This depends on the target platform.
935 Configuring the target platform like this makes it insecure.
936 </para>
937 </listitem>
938 </varlistentry>
939 <varlistentry><term><command>Password authentication</command></term>
940 <listitem>
941 <para>
942 This is the normal way of connecting to a target platform. Set the
943 credentials needed to connect to the Remote Packet Capture Protocol
944 service.
945 </para>
946 </listitem>
947 </varlistentry>
948 </variablelist>
949 </section>
950 <!-- <section><title>Remote Capture</title>
951 <para>
952 When the connection to the Remote Packet Capture Protocol service is
953 successfully established the "Capture Options" dialog looks like this,
954 see <xref linkend="ChCapInterfaceRemoteCapDialog"/>.
955 </para>
956 <figure id="ChCapInterfaceRemoteCapDialog">
957 <title>The "Remote Capture" dialog box</title>
958 <graphic entityref="WiresharkCaptureOptionsRemoteCaptureDialog" format="PNG"/>
959 </figure>
960 <para>
961 The Interface dropdown list now shows the IP address or host name of the
962 Remote Packet Capture Protocol service and the other field shows the
963 interfaces on the remote target. After selecting the desired interface
964 just click <command>Start</command> to start the remote capture.
965 </para>
966 </section> -->
967 <section><title>Remote Capture Settings</title>
968 <para>
969 The remote capture can be further fine tuned to match your situation.
970 The <command>Remote Settings</command> button in
971 <xref linkend="ChCapEditInterfacesSettingsDialog"/> gives you this option.
972 It pops up the dialog shown in
973 <xref linkend="ChCapInterfaceRemoteSettingsDialog"/>.
974 </para>
975 <figure id="ChCapInterfaceRemoteSettingsDialog">
976 <title>The "Remote Capture Settings" dialog box</title>
977 <graphic entityref="WiresharkCaptureOptionsRemoteSettingsDialog" format="PNG"/>
978 </figure>
979 <para>
980 You can set the following parameters in this dialog:
981 </para>
982 <variablelist>
983 <varlistentry><term><command>Do not capture own RPCAP traffic</command></term>
984 <listitem>
985 <para>
986 This option sets a capture filter so that the traffic flowing back
987 from the Remote Packet Capture Protocol service to Wireshark isn't
988 captured as well and also send back. The recursion in this saturates
989 the link with duplicate traffic.
990 </para>
991 <para>
992 You only should switch this off when capturing on an interface other
993 then the interface connecting back to Wireshark.
994 </para>
995 </listitem>
996 </varlistentry>
997 <varlistentry><term><command>Use UDP for data transfer</command></term>
998 <listitem>
999 <para>
1000 Remote capture control and data flows over a TCP connection. This
1001 option allows you to choose an UDP stream for data transfer.
1002 </para>
1003 </listitem>
1004 </varlistentry>
1005 <varlistentry><term><command>Sampling option None</command></term>
1006 <listitem>
1007 <para>
1008 This option instructs the Remote Packet Capture Protocol service to
1009 send back all captured packets which have passed the capture filter.
1010 This is usually not a problem on a remote capture session with
1011 sufficient bandwidth.
1012 </para>
1013 </listitem>
1014 </varlistentry>
1015 <varlistentry><term><command>Sampling option 1 of x packets</command></term>
1016 <listitem>
1017 <para>
1018 This option limits the Remote Packet Capture Protocol service to send
1019 only a sub sampling of the captured data, in terms of number of
1020 packets. This allows capture over a narrow band remote capture
1021 session of a higher bandwidth interface.
1022 </para>
1023 </listitem>
1024 </varlistentry>
1025 <varlistentry><term><command>Sampling option 1 every x milliseconds</command></term>
1026 <listitem>
1027 <para>
1028 This option limits the Remote Packet Capture Protocol service to send
1029 only a sub sampling of the captured data, in terms of time. This
1030 allows capture over a narrow band capture session of a higher
1031 bandwidth interface.
1032 </para>
1033 </listitem>
1034 </varlistentry>
1035 </variablelist>
1036 </section>
1037 </section>
1039 <section id="ChCapInterfaceDetailsSection">
1040 <title>The "Interface Details" dialog box</title>
1041 <para>
1042 When you select Details from the Capture Interface menu, Wireshark pops
1043 up the "Interface Details" dialog box as shown in
1044 <xref linkend="ChCapInterfaceDetailsDialog"/>. This dialog shows various
1045 characteristics and statistics for the selected interface.
1046 </para>
1047 <note><title>Microsoft Windows only</title>
1048 <para>This dialog is only available on Microsoft Windows</para>
1049 </note>
1050 <figure id="ChCapInterfaceDetailsDialog">
1051 <title>The "Interface Details" dialog box</title>
1052 <graphic entityref="WiresharkCaptureInterfaceDetailsDialog" format="JPG"/>
1053 </figure>
1054 </section>
1056 <section id="ChCapCaptureFiles"><title>Capture files and file modes</title>
1057 <para>
1058 While capturing, the underlying libpcap capturing engine will grab the
1059 packets from the network card and keep the packet data in a (relatively)
1060 small kernel buffer. This data is read by Wireshark and saved into
1061 the capture file(s) the user specified.
1062 </para>
1064 <para>
1065 Different modes of operation are available when saving this packet data to
1066 the capture file(s).
1067 </para>
1069 <tip><title>Tip!</title>
1070 <para>
1071 Working with large files (several 100 MB's) can be quite slow. If you plan
1072 to do a long term capture or capturing from a high traffic network, think
1073 about using one of the "Multiple files" options. This will spread the
1074 captured packets over several smaller files which can be much more
1075 pleasant to work with.
1076 </para>
1077 </tip>
1078 <note><title>Note!</title>
1079 <para>
1080 Using Multiple files may cut context related information.
1081 Wireshark keeps context information of the loaded packet data, so it can
1082 report context related problems (like a stream error) and keeps information
1083 about context related protocols (e.g. where data is exchanged at the
1084 establishing phase and only referred to in later packets).
1085 As it keeps this information only for the loaded file, using one of
1086 the multiple file modes may cut these contexts. If the establishing phase
1087 is saved in one file and the things you would like to see is in another,
1088 you might not see some of the valuable context related information.
1089 </para>
1090 </note>
1091 <tip><title>Tip!</title>
1092 <para>
1093 Information about the folders used for the capture file(s), can be found
1094 in <xref linkend="AppFiles"/>.
1095 </para>
1096 </tip>
1098 <table id="ChCapTabCaptureFiles"><title>Capture file mode selected by capture options</title>
1099 <tgroup cols="5">
1100 <colspec colnum="1" colwidth="72pt"/>
1101 <colspec colnum="2" colwidth="80pt"/>
1102 <colspec colnum="3" colwidth="80pt"/>
1103 <colspec colnum="4" colwidth="80pt"/>
1104 <thead>
1105 <row>
1106 <entry>"File" option</entry>
1107 <entry>"Use multiple files" option</entry>
1108 <entry>"Ring buffer with n files" option</entry>
1109 <entry>Mode</entry>
1110 <entry>Resulting filename(s) used</entry>
1111 </row>
1112 </thead>
1113 <tbody>
1114 <row>
1115 <entry>-</entry>
1116 <entry>-</entry>
1117 <entry>-</entry>
1118 <entry><command>Single temporary file</command></entry>
1119 <entry>wiresharkXXXXXX (where XXXXXX is a unique number)</entry>
1120 </row>
1121 <row>
1122 <entry>foo.cap</entry>
1123 <entry>-</entry>
1124 <entry>-</entry>
1125 <entry><command>Single named file</command></entry>
1126 <entry>foo.cap</entry>
1127 </row>
1128 <row>
1129 <entry>foo.cap</entry>
1130 <entry>x</entry>
1131 <entry>-</entry>
1132 <entry><command>Multiple files, continuous</command></entry>
1133 <entry>foo_00001_20100205110102.cap, foo_00002_20100205110318.cap, ...</entry>
1134 </row>
1135 <row>
1136 <entry>foo.cap</entry>
1137 <entry>x</entry>
1138 <entry>x</entry>
1139 <entry><command>Multiple files, ring buffer</command></entry>
1140 <entry>foo_00001_20100205110102.cap, foo_00002_20100205110318.cap, ...</entry>
1141 </row>
1142 </tbody>
1143 </tgroup>
1144 </table>
1145 <variablelist>
1146 <varlistentry>
1147 <term><command>Single temporary file</command></term>
1148 <listitem>
1149 <para>
1150 A temporary file will be created and used (this is the default). After the
1151 capturing is stopped, this file can be saved later under a user specified
1152 name.
1153 </para>
1154 </listitem>
1155 </varlistentry>
1156 <varlistentry>
1157 <term><command>Single named file</command></term>
1158 <listitem>
1159 <para>
1160 A single capture file will be used. If you want to place the new capture
1161 file to a specific folder, choose this mode.
1162 </para>
1163 </listitem>
1164 </varlistentry>
1165 <varlistentry>
1166 <term><command>Multiple files, continuous</command></term>
1167 <listitem>
1168 <para>
1169 Like the "Single named file" mode, but a new file is created and used,
1170 after reaching one of the multiple file switch conditions (one of the
1171 "Next file every ..." values).
1172 </para>
1173 </listitem>
1174 </varlistentry>
1175 <varlistentry>
1176 <term><command>Multiple files, ring buffer</command></term>
1177 <listitem>
1178 <para>
1179 Much like "Multiple files continuous", reaching one of the multiple files
1180 switch conditions (one of the "Next file every ..." values) will switch
1181 to the next file. This will be a newly created file if value of "Ring
1182 buffer with n files" is not reached, otherwise it will replace the oldest
1183 of the formerly used files (thus forming a "ring").
1184 </para>
1185 <para>
1186 This mode will limit the maximum disk usage, even for an unlimited amount of
1187 capture input data, keeping the latest captured data.
1188 </para>
1189 </listitem>
1190 </varlistentry>
1191 </variablelist>
1192 </section>
1194 <section id="ChCapLinkLayerHeader"><title>Link-layer header type</title>
1195 <para>
1196 In the usual case, you won't have to choose this link-layer header type.
1197 The following paragraphs describe the exceptional cases, where
1198 selecting this type is possible, so you will have a guide of what to do:
1199 </para>
1200 <para>
1201 If you are capturing on an 802.11 device on some versions of BSD, this
1202 might offer a choice of "Ethernet" or "802.11". "Ethernet" will cause
1203 the captured packets to have fake Ethernet headers; "802.11" will cause
1204 them to have IEEE 802.11 headers. Unless the capture needs to be read by
1205 an application that doesn't support 802.11 headers, you should select
1206 "802.11".
1207 </para>
1208 <para>
1209 If you are capturing on an Endace DAG card connected to a synchronous
1210 serial line, this might offer a choice of "PPP over serial" or
1211 "Cisco HDLC"; if the protocol on the serial line is PPP, select
1212 "PPP over serial", and if the protocol on the serial line is Cisco HDLC,
1213 select "Cisco HDLC".
1214 </para>
1215 <para>
1216 If you are capturing on an Endace DAG card connected to an ATM network,
1217 this might offer a choice of "RFC 1483 IP-over-ATM" or "Sun raw ATM".
1218 If the only traffic being captured is RFC 1483 LLC-encapsulated IP, or if
1219 the capture needs to be read by an application that doesn't support SunATM
1220 headers, select "RFC 1483 IP-over-ATM", otherwise select "Sun raw ATM".
1221 </para>
1222 <para>
1223 If you are capturing on an Ethernet device, this might offer a choice of
1224 "Ethernet" or "DOCSIS". If you are capturing traffic from a Cisco Cable
1225 Modem Termination System that is putting DOCSIS traffic onto the Ethernet
1226 to be captured, select "DOCSIS", otherwise select "Ethernet".
1227 </para>
1228 </section>
1230 <section id="ChCapCaptureFilterSection"><title>Filtering while capturing</title>
1231 <para>
1232 Wireshark uses the libpcap filter language for capture filters.
1233 This is explained in the tcpdump man page, which can be hard to
1234 understand, so it's explained here to some extent.
1235 </para>
1236 <tip>
1237 <title>Tip!</title>
1238 <para>
1239 You will find a lot of Capture Filter examples at <ulink
1240 url="&WiresharkWikiCaptureFiltersPage;">&WiresharkWikiCaptureFiltersPage;</ulink>.
1241 </para>
1242 </tip>
1243 <para>
1244 You enter the capture filter into the Filter field of the Wireshark
1245 Capture Options dialog box, as shown in
1246 <xref linkend="ChCapCaptureOptionsDialog"/>. The following is an outline
1247 of the syntax of the <command>tcpdump</command> capture filter language.
1248 See the expression option at the tcpdump manual page for details:
1249 <ulink url="&TcpdumpManpage;"/>.
1250 </para>
1251 <para>
1252 A capture filter takes the form of a series of primitive expressions
1253 connected by conjunctions (<command>and/or</command>) and optionally
1254 preceded by <command>not</command>:
1255 <programlisting>
1256 [not] <command>primitive</command> [and|or [not] <command>primitive</command> ...]
1257 </programlisting>
1258 An example is shown in <xref linkend="ChCapExFilt1"/>.
1260 <example id="ChCapExFilt1">
1261 <title>
1262 A capture filter for telnet that captures traffic to and from a
1263 particular host
1264 </title>
1265 <programlisting>
1266 tcp port 23 and host 10.0.0.5
1267 </programlisting>
1268 </example>
1269 This example captures telnet traffic to and from the host
1270 10.0.0.5, and shows how to use two primitives and the
1271 <command>and</command> conjunction. Another example is shown in
1272 <xref linkend="ChCapExFilt2"/>, and shows how to capture all
1273 telnet traffic except that from 10.0.0.5.
1274 <example id="ChCapExFilt2">
1275 <title>
1276 Capturing all telnet traffic not from 10.0.0.5</title>
1277 <programlisting>
1278 tcp port 23 and not src host 10.0.0.5
1279 </programlisting>
1280 </example>
1281 </para>
1283 <para>
1284 XXX - add examples to the following list.
1285 </para>
1286 <para>
1287 A primitive is simply one of the following:
1288 <variablelist>
1289 <varlistentry>
1290 <term><command>[src|dst] host <host></command></term>
1291 <listitem>
1292 <para>
1293 This primitive allows you to filter on a host IP
1294 address or name. You can optionally precede the
1295 primitive with the keyword <command>src|dst</command>
1296 to specify that you are only interested in source or
1297 destination addresses. If these are not present,
1298 packets where the specified address appears as either
1299 the source or the destination address will be selected.
1300 </para>
1301 </listitem>
1302 </varlistentry>
1303 <varlistentry>
1304 <term>
1305 <command>ether [src|dst] host <ehost></command>
1306 </term>
1307 <listitem>
1308 <para>
1309 This primitive allows you to filter on Ethernet host
1310 addresses. You can optionally include the keyword
1311 <command>src|dst</command> between the keywords
1312 <command>ether</command> and <command>host</command>
1313 to specify that you are only interested in source
1314 or destination addresses. If these are not present,
1315 packets where the specified address appears in either
1316 the source or destination address will be selected.
1317 </para>
1318 </listitem>
1319 </varlistentry>
1320 <varlistentry>
1321 <term><command>gateway host <host></command></term>
1322 <listitem>
1323 <para>
1324 This primitive allows you to filter on packets that
1325 used <command>host</command> as a gateway. That is, where
1326 the Ethernet source or destination was
1327 <command>host</command> but neither the source nor
1328 destination IP address was <command>host</command>.
1329 </para>
1330 </listitem>
1331 </varlistentry>
1332 <varlistentry>
1333 <term>
1334 <command>
1335 [src|dst] net <net> [{mask <mask>}|{len <len>}]
1336 </command>
1337 </term>
1338 <listitem>
1339 <para>
1340 This primitive allows you to filter on network numbers.
1341 You can optionally precede this primitive with the
1342 keyword <command>src|dst</command> to specify that you
1343 are only interested in a source or destination network.
1344 If neither of these are present, packets will be
1345 selected that have the specified network in either the
1346 source or destination address. In addition, you can
1347 specify either the netmask or the CIDR prefix for the
1348 network if they are different from your own.
1349 </para>
1350 </listitem>
1351 </varlistentry>
1352 <varlistentry>
1353 <term>
1354 <command>[tcp|udp] [src|dst] port <port></command>
1355 </term>
1356 <listitem>
1357 <para>
1358 This primitive allows you to filter on TCP and UDP port
1359 numbers. You can optionally precede this primitive with
1360 the keywords <command>src|dst</command> and
1361 <command>tcp|udp</command> which allow you to specify
1362 that you are only interested in source or destination
1363 ports and TCP or UDP packets respectively. The
1364 keywords <command>tcp|udp</command> must appear before
1365 <command>src|dst</command>.
1366 </para>
1367 <para>
1368 If these are not specified, packets will be selected
1369 for both the TCP and UDP protocols and when the
1370 specified address appears in either the source or
1371 destination port field.
1372 </para>
1373 </listitem>
1374 </varlistentry>
1375 <varlistentry>
1376 <term><command>less|greater <length></command></term>
1377 <listitem>
1378 <para>
1379 This primitive allows you to filter on packets whose
1380 length was less than or equal to the specified length,
1381 or greater than or equal to the specified length,
1382 respectively.
1383 </para>
1384 </listitem>
1385 </varlistentry>
1386 <varlistentry>
1387 <term><command>ip|ether proto <protocol></command></term>
1388 <listitem>
1389 <para>
1390 This primitive allows you to filter on the specified
1391 protocol at either the Ethernet layer or the IP layer.
1392 </para>
1393 </listitem>
1394 </varlistentry>
1395 <varlistentry>
1396 <term><command>ether|ip broadcast|multicast</command></term>
1397 <listitem>
1398 <para>
1399 This primitive allows you to filter on either
1400 Ethernet or IP broadcasts or multicasts.
1401 </para>
1402 </listitem>
1403 </varlistentry>
1404 <varlistentry>
1405 <term><command><expr> relop <expr></command></term>
1406 <listitem>
1407 <para>
1408 This primitive allows you to create complex filter
1409 expressions that select bytes or ranges of bytes in
1410 packets. Please see the tcpdump man page at
1411 <ulink url="&TcpdumpManpage;"/> for more details.
1412 </para>
1413 </listitem>
1414 </varlistentry>
1415 </variablelist>
1416 </para>
1417 <section id="ChCapCaptureAutoFilterSection">
1418 <title>Automatic Remote Traffic Filtering</title>
1419 <para>
1420 If Wireshark is running remotely (using e.g. SSH, an exported X11 window,
1421 a terminal server, ...), the remote content has to be transported over
1422 the network, adding a lot of (usually unimportant) packets to the actually
1423 interesting traffic.
1424 </para>
1425 <para>
1426 To avoid this, Wireshark tries to figure out if it's remotely connected
1427 (by looking at some specific environment variables) and automatically
1428 creates a capture filter that matches aspects of the connection.
1429 </para>
1430 <para>
1431 The following environment variables are analyzed:
1432 </para>
1433 <variablelist>
1434 <varlistentry>
1435 <term><command>SSH_CONNECTION</command> (ssh)</term>
1436 <listitem>
1437 <para>
1438 <remote IP> <remote port> <local IP> <local port>
1439 </para>
1440 </listitem>
1441 </varlistentry>
1443 <varlistentry>
1444 <term><command>SSH_CLIENT</command> (ssh)</term>
1445 <listitem>
1446 <para>
1447 <remote IP> <remote port> <local port>
1448 </para>
1449 </listitem>
1450 </varlistentry>
1452 <varlistentry>
1453 <term><command>REMOTEHOST</command> (tcsh, others?)</term>
1454 <listitem>
1455 <para>
1456 <remote name>
1457 </para>
1458 </listitem>
1459 </varlistentry>
1461 <varlistentry>
1462 <term><command>DISPLAY</command> (x11)</term>
1463 <listitem>
1464 <para>
1465 [remote name]:<display num>
1466 </para>
1467 </listitem>
1468 </varlistentry>
1469 <varlistentry>
1470 <term><command>SESSIONNAME</command> (terminal server)</term>
1471 <listitem>
1472 <para>
1473 <remote name>
1474 </para>
1475 </listitem>
1476 </varlistentry>
1477 </variablelist>
1478 <para>
1479 On Windows it asks the operating system if it's running in a Remote Desktop Services
1480 environment.
1481 </para>
1482 </section>
1483 </section>
1485 <section id="ChCapRunningSection"><title>While a Capture is running ...</title>
1486 <para>
1487 While a capture is running, the following dialog box is shown:
1488 <figure id="ChCapCaptureInfoDialog">
1489 <title>The "Capture Info" dialog box</title>
1490 <graphic entityref="WiresharkCaptureInfoDialog" format="JPG"/>
1491 </figure>
1492 This dialog box will inform you about the number of captured packets and
1493 the time since the capture was started. The selection of which protocols
1494 are counted cannot be changed.
1495 </para>
1496 <tip><title>Tip!</title>
1497 <para>
1498 This Capture Info dialog box can be hidden, using the "Hide capture info
1499 dialog" option in the Capture Options dialog box.
1500 </para>
1501 </tip>
1502 <section id="ChCapStopSection"><title>Stop the running capture</title>
1503 <para>
1504 A running capture session will be stopped in one of the following ways:
1505 <orderedlist>
1506 <listitem>
1507 <para>Using the
1508 "<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
1509 Stop" button from the <command>Capture Info dialog box
1510 </command>.
1511 </para>
1512 <note><title>Note!</title>
1513 <para>
1514 The Capture Info dialog box might be hidden, if the option "Hide capture
1515 info dialog" is used.
1516 </para>
1517 </note>
1518 </listitem>
1519 <listitem>
1520 <para>Using the <command>menu item</command>
1521 "Capture/<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
1522 Stop".
1523 </para>
1524 </listitem>
1525 <listitem>
1526 <para>Using the <command>toolbar item</command>
1527 "<inlinegraphic entityref="WiresharkToolbarCaptureStop" format="PNG"/>
1528 Stop".
1529 </para>
1530 </listitem>
1531 <listitem>
1532 <para>Pressing the accelerator keys: <command>Ctrl+E</command>.
1533 </para>
1534 </listitem>
1535 <listitem>
1536 <para>The capture will be automatically stopped, if one of the
1537 <command>Stop Conditions</command> is exceeded, e.g. the maximum amount
1538 of data was captured.
1539 </para>
1540 </listitem>
1541 </orderedlist>
1542 </para>
1543 </section>
1544 <section id="ChCapRestartSection"><title>Restart a running capture</title>
1545 <para>
1546 A running capture session can be restarted with the same capture options
1547 as the last time, this will remove all packets previously captured.
1548 This can be useful, if some uninteresting packets are captured and
1549 there's no need to keep them.
1550 </para>
1551 <para>
1552 Restart is a convenience function and
1553 equivalent to a capture stop following by an immediate capture start.
1554 A restart can be triggered in one of the following ways:
1555 <orderedlist>
1556 <listitem>
1557 <para>Using the <command>menu item</command>
1558 "Capture/<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
1559 Restart".
1560 </para>
1561 </listitem>
1562 <listitem>
1563 <para>Using the <command>toolbar item</command>
1564 "<inlinegraphic entityref="WiresharkToolbarCaptureRestart" format="PNG"/>
1565 Restart".
1566 </para>
1567 </listitem>
1568 </orderedlist>
1569 </para>
1570 </section>
1571 </section>
1573 </chapter>
1574 <!-- End of WSUG Chapter Capture -->