aboutsummaryrefslogtreecommitdiffstats
path: root/docbook/wsug_src/WSUG_chapter_capture.adoc
blob: 3eba2ea6341b4b2495e492b6498dfc2fd144bdb6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
// 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
  <<ChCapCaptureFilterSection>>.

* Save packets in multiple files while doing a long term capture, optionally
  rotating through a fixed number of files (a “ringbuffer”). See
  <<ChCapCaptureFiles>>.

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 <<ChCapInterfaceSection,welcome screen>>.

* You can select an interface in the <<ChCapInterfaceSection,welcome screen>>, then select menu:Capture[Start] or click the first toolbar button.

* You can get more detailed information about available interfaces using <<ChCapCaptureOptions>> (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 <<ChCustCommandLine>>.

[[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::wsug_graphics/ws-capture-interfaces-main-win32.png[{screenshot-attrs}]

[[ChCapCaptureInterfacesMainMacos]]

.Capture interfaces on macOS
image::wsug_graphics/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:wsug_graphics/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 <<ChManageInterfacesSection>>.

[[ChCapCaptureOptions]]

=== The “Capture Options” Dialog Box

When you select menu:Capture[Options...] (or use the corresponding item in the
main toolbar), Wireshark pops up the “Capture Options” dialog box as shown in
<<ChCapCaptureOptionsDialog>>.
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::wsug_graphics/ws-capture-options.png[{screenshot-attrs}]

The “Input” tab contains the the “Interface” table, which shows the following columns:

Interface::
The interface name.

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 <<ChCapLinkLayerHeader>> 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 <<ChCapCaptureFilterSection>> 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 <<ChCapManageInterfacesDialog>> where pipes can be defined, local interfaces scanned or hidden, or remote interfaces added.

btn:[Compile Selected BPFs] opens <<ChCapCompiledFilterOutputDialog>>, 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::wsug_graphics/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 <<ChCapCaptureFiles>> 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 <<ChCapCaptureFiles>>.

.The “Capture Options” options tab
image::wsug_graphics/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.
If you do not specify this Wireshark adds new packets to the packet list but does not scroll the packet list pane.
This option is greyed out 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  <<ChCapRunningSection>> 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 <<ChAdvNameResolutionSection>> 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 click btn:[Start] from any tab to commence the capture or btn:[Cancel] to apply your changes and close the dialog.

[[ChManageInterfacesSection]]

=== The “Manage Interfaces” Dialog Box

[[ChCapManageInterfacesDialog]]
.The “Manage Interfaces” dialog box
image::wsug_graphics/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::wsug_graphics/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::wsug_graphics/ws-capture-options-manage-interfaces.png[{screenshot-attrs}]

// ==== Add or hide local interfaces

// [[ChCapManageInterfacesLocalDialog]]
// .The “Add New Interfaces - Local Interfaces” dialog box
// image::wsug_graphics/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::wsug_graphics/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.
The easiest way is to install Npcap from {npcap-download-url} on the target.
Once installation is completed go to the Services control panel, find the Remote Packet Capture Protocol service and start it.

On Linux or Unix you can capture (and do so more securely) through an SSH tunnel.

To add a new remore 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 <<ChCapManageInterfacesRemoteDialog>> and select btn:[Add].

// [[ChCapInterfaceRemoteDialog]]
// .The “Remote Capture Interfaces” dialog box
// image::wsug_graphics/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 <<ChCapManageInterfacesDialog>> gives
// you this option. It pops up the dialog shown in
// <<ChCapInterfaceRemoteSettingsDialog>>.

// [[ChCapInterfaceRemoteSettingsDialog]]
// .The “Remote Capture Settings” dialog box
// image::wsug_graphics/ws-capture-options-remote-settings.png[{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 an UDP stream for data transfer.

// _Sampling option None_::
// This option instructs the Remote Packet Capture Protocol service to send back
// all captured packets which have passed the capture filter. This is usually not a
// problem on a remote capture session with sufficient bandwidth.

// _Sampling option 1 of x packets_::
// This option limits the Remote Packet Capture Protocol service to send only a sub
// sampling of the captured data, in terms of number of packets. This allows
// capture over a narrow band remote capture session of a higher bandwidth
// interface.


// _Sampling option 1 every x milliseconds_::
// This option limits the Remote Packet Capture Protocol service to send only a sub
// sampling of the captured data in terms of time. This allows capture over a
// narrow band capture session of a higher bandwidth interface.

// [[ChCapInterfaceDetailsSection]]

// === The “Interface Details” dialog box

// When you select Details from the Capture Interface menu, Wireshark pops up the
// “Interface Details” dialog box as shown in <<ChCapInterfaceDetailsDialog>>. This
// dialog shows various characteristics and statistics for the selected interface.

// [NOTE]
// .Microsoft Windows only
// ====
// This dialog is only available on Microsoft Windows
// ====

// [[ChCapInterfaceDetailsDialog]]
// .The “Interface Details” dialog box
// image::wsug_graphics/ws-capture-interface-details.png[{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::wsug_graphics/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 “Output” tab in
the “Capture Options” dialog.

[[ChCapCaptureOptionsOutputDialog]]
.Capture output options
image::wsug_graphics/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
<<AppFiles>>.

[[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|wiresharkXXXXXX (where XXXXXX is a unique number)
|foo.cap|-|-|Single named file|foo.cap
|foo.cap|x|-|Multiple files, continuous|foo_00001_20190714110102.cap, foo_00002_20190714110318.cap, ...
|foo.cap|x|x|Multiple files, ring buffer|foo_00001_20190714110102.cap, foo_00002_20190714110318.cap, ...
|===

Single temporary file::
A temporary file will be created and used (this is the default).
After capturing is stopped this file can be saved later under a user specified name.

Single named file::
A single capture file will be used.
If you want to place the new capture file in a specific folder choose this mode.

Multiple files, continuous::
Like the “Single named file” mode, but a new file is created and used after reaching one of the multiple file switch conditions (one of the “Next file every...” values).

Multiple files, ring buffer::
Much like “Multiple files continuous”, reaching one of the multiple files switch
conditions (one of the “Next file every ...” values) will switch to the next
file. This will be a newly created file if value of “Ring buffer with n files”
is not reached, otherwise it will replace the oldest of the formerly used files
(thus forming a “ring”).
+
This mode will limit the maximum disk usage, even for an unlimited amount of
capture input data, only keeping the latest captured data.

[[ChCapLinkLayerHeader]]

=== Link-layer header type

In most cases you won’t have to modify link-layer header type. Some 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 <<ChCapCaptureOptionsDialog>>.

A capture filter takes the form of a series of primitive expressions connected
by conjunctions (__and/or__) and optionally preceded by __not__:

----
[not] primitive [and|or [not] primitive ...]
----

An example is shown in <<ChCapExFilt1>>.

[[ChCapExFilt1]]
.A capture filter for telnet that captures traffic to and from a particular host
====
A capture filter for telnet that captures traffic to and from a particular host

----
tcp port 23 and host 10.0.0.5
----
====

This example captures telnet traffic to and from the host 10.0.0.5, and shows
how to use two primitives and the __and__ conjunction. Another example is shown
in <<ChCapExFilt2>>, and shows how to capture all telnet traffic except that
from 10.0.0.5.

[[ChCapExFilt2]]
.Capturing all telnet traffic not from 10.0.0.5
====
Capturing all telnet traffic not from 10.0.0.5

----
tcp port 23 and not src host 10.0.0.5
----
====

// XXX - add examples to the following list.

A primitive is simply one of the following: _[src|dst] host <host>_::
This primitive allows you to filter on a host IP address or name. You can
optionally precede the primitive with the keyword _src|dst_ to specify that you
are only interested in source or destination addresses. If these are not
present, packets where the specified address appears as either the source or the
destination address will be selected.

ether [src|dst] host <ehost>::
This primitive allows you to filter on Ethernet host addresses. You can
optionally include the keyword _src|dst_ between the keywords _ether_ and _host_
to specify that you are only interested in source or destination addresses. If
these are not present, packets where the specified address appears in either the
source or destination address will be selected.

gateway host <host>::
This primitive allows you to filter on packets that used _host_ as a gateway.
That is, where the Ethernet source or destination was _host_ but neither the
source nor destination IP address was _host_.

[src|dst] net <net> [{mask <mask>}|{len <len>}]::
This primitive allows you to filter on network numbers. You can optionally
precede this primitive with the keyword _src|dst_ to specify that you are only
interested in a source or destination network. If neither of these are present,
packets will be selected that have the specified network in either the source or
destination address. In addition, you can specify either the netmask or the CIDR
prefix for the network if they are different from your own.


[tcp|udp] [src|dst] port <port>::
This primitive allows you to filter on TCP and UDP port numbers. You can
optionally precede this primitive with the keywords _src|dst_ and _tcp|udp_
which allow you to specify that you are only interested in source or destination
ports and TCP or UDP packets respectively. The keywords _tcp|udp_ must appear
before _src|dst_.
+
If these are not specified, packets will be selected for both the TCP and UDP
protocols and when the specified address appears in either the source or
destination port field.

less|greater <length>::
This primitive allows you to filter on packets whose length was less than or
equal to the specified length, or greater than or equal to the specified length,
respectively.

ip|ether proto <protocol>::
This primitive allows you to filter on the specified protocol at either the
Ethernet layer or the IP layer.

ether|ip broadcast|multicast::
This primitive allows you to filter on either Ethernet or IP broadcasts or
multicasts.

<expr> relop <expr>::
This primitive allows you to create complex filter expressions that select bytes or ranges of bytes in packets.
Please see the pcap-filter man page at {pcap-filter-man-page-url} for more details.


[[ChCapCaptureAutoFilterSection]]

==== Automatic Remote Traffic Filtering

If Wireshark is running remotely (using e.g. SSH, an exported X11 window, a
terminal server, ...), the remote content has to be transported over the
network, adding a lot of (usually unimportant) packets to the actually
interesting traffic.

To avoid this, Wireshark tries to figure out if it’s remotely connected (by
looking at some specific environment variables) and automatically creates a
capture filter that matches aspects of the connection.

The following environment variables are analyzed:

`SSH_CONNECTION` (ssh)::
<remote IP> <remote port> <local IP> <local port>


`SSH_CLIENT` (ssh)::
<remote IP> <remote port> <local port>


`REMOTEHOST` (tcsh, others?)::
<remote name>

`DISPLAY` (x11)::
[remote name]:<display num>


`SESSIONNAME` (terminal server)::
<remote name>

On Windows it asks the operating system if it’s running in a Remote Desktop Services environment.

[[ChCapRunningSection]]

=== While a Capture is running ...

You might see the following dialog box while a capture is running:

[[ChCapCaptureInfoDialog]]
.The “Capture Information” dialog box
image::wsug_graphics/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