1WIRESHARK-FILTER(4) WIRESHARK-FILTER(4)
2
3
4
6 wireshark-filter - Wireshark display filter syntax and reference
7
9 wireshark [other options] [ -Y "display filter expression" |
10 --display-filter "display filter expression" ]
11
12 tshark [other options] [ -Y "display filter expression" |
13 --display-filter "display filter expression" ]
14
16 Wireshark and TShark share a powerful filter engine that helps remove
17 the noise from a packet trace and lets you see only the packets that
18 interest you. If a packet meets the requirements expressed in your
19 filter, then it is displayed in the list of packets. Display filters
20 let you compare the fields within a protocol against a specific value,
21 compare fields against fields, and check the existence of specified
22 fields or protocols.
23
24 Filters are also used by other features such as statistics generation
25 and packet list colorization (the latter is only available to
26 Wireshark). This manual page describes their syntax. A comprehensive
27 reference of filter fields can be found within Wireshark and in the
28 display filter reference at https://www.wireshark.org/docs/dfref/.
29
31 Check whether a field or protocol exists
32 The simplest filter allows you to check for the existence of a protocol
33 or field. If you want to see all packets which contain the IP protocol,
34 the filter would be "ip" (without the quotation marks). To see all
35 packets that contain a Token-Ring RIF field, use "tr.rif".
36
37 Think of a protocol or field in a filter as implicitly having the
38 "exists" operator.
39
40 Comparison operators
41 Fields can also be compared against values. The comparison operators
42 can be expressed either through English-like abbreviations or through
43 C-like symbols:
44
45 eq, == Equal
46 ne, != Not Equal
47 gt, > Greater Than
48 lt, < Less Than
49 ge, >= Greater than or Equal to
50 le, <= Less than or Equal to
51
52 Search and match operators
53 Additional operators exist expressed only in English, not C-like
54 syntax:
55
56 contains Does the protocol, field or slice contain a value
57 matches, ~ Does the protocol or text string match the given
58 case-insensitive Perl-compatible regular expression
59
60 The "contains" operator allows a filter to search for a sequence of
61 characters, expressed as a string (quoted or unquoted), or bytes,
62 expressed as a byte array, or for a single character, expressed as a
63 C-style character constant. For example, to search for a given HTTP URL
64 in a capture, the following filter can be used:
65
66 http contains "https://www.wireshark.org"
67
68 The "contains" operator cannot be used on atomic fields, such as
69 numbers or IP addresses.
70
71 The "matches" or "~" operator allows a filter to apply to a specified
72 Perl-compatible regular expression (PCRE). The "matches" operator is
73 only implemented for protocols and for protocol fields with a text
74 string representation. Matches are case-insensitive by default. For
75 example, to search for a given WAP WSP User-Agent, you can write:
76
77 wsp.header.user_agent matches "cldc"
78
79 This would match "cldc", "CLDC", "cLdC" or any other combination of
80 upper and lower case letters.
81
82 You can force case sensitivity using
83
84 wsp.header.user_agent matches "(?-i)cldc"
85
86 This is an example of PCRE’s (?*option)* construct. (?-i) performs a
87 case-sensitive pattern match but other options can be specified as
88 well. More information can be found in the
89 pcrepattern(3)|https://www.pcre.org/original/doc/html/pcrepattern.html
90 man page.
91
92 Functions
93 The filter language has the following functions:
94
95 upper(string-field) - converts a string field to uppercase
96 lower(string-field) - converts a string field to lowercase
97 len(field) - returns the byte length of a string or bytes field
98 count(field) - returns the number of field occurrences in a frame
99 string(field) - converts a non-string field to string
100
101 upper() and lower() are useful for performing case-insensitive string
102 comparisons. For example:
103
104 upper(ncp.nds_stream_name) contains "MACRO"
105 lower(mount.dump.hostname) == "angel"
106
107 string() converts a field value to a string, suitable for use with
108 operators like "matches" or "contains". Integer fields are converted to
109 their decimal representation. It can be used with IP/Ethernet addresses
110 (as well as others), but not with string or byte fields. For example:
111
112 string(frame.number) matches "[13579]$"
113
114 gives you all the odd packets.
115
116 Protocol field types
117 Each protocol field is typed. The types are:
118
119 ASN.1 object identifier
120 Boolean
121 Character string
122 Compiled Perl-Compatible Regular Expression (GRegex) object
123 Date and time
124 Ethernet or other MAC address
125 EUI64 address
126 Floating point (double-precision)
127 Floating point (single-precision)
128 Frame number
129 Globally Unique Identifier
130 IPv4 address
131 IPv6 address
132 IPX network number
133 Label
134 Protocol
135 Sequence of bytes
136 Signed integer, 1, 2, 3, 4, or 8 bytes
137 Time offset
138 Unsigned integer, 1, 2, 3, 4, or 8 bytes
139 1-byte ASCII character
140
141 An integer may be expressed in decimal, octal, or hexadecimal notation,
142 or as a C-style character constant. The following six display filters
143 are equivalent:
144
145 frame.len > 10
146 frame.len > 012
147 frame.len > 0xa
148 frame.len > '\n'
149 frame.len > '\x0a'
150 frame.len > '\012'
151
152 Boolean values are either true or false. In a display filter expression
153 testing the value of a Boolean field, "true" is expressed as 1 or any
154 other non-zero value, and "false" is expressed as zero. For example, a
155 token-ring packet’s source route field is Boolean. To find any
156 source-routed packets, a display filter would be:
157
158 tr.sr == 1
159
160 Non source-routed packets can be found with:
161
162 tr.sr == 0
163
164 Ethernet addresses and byte arrays are represented by hex digits. The
165 hex digits may be separated by colons, periods, or hyphens:
166
167 eth.dst eq ff:ff:ff:ff:ff:ff
168 aim.data == 0.1.0.d
169 fddi.src == aa-aa-aa-aa-aa-aa
170 echo.data == 7a
171
172 IPv4 addresses can be represented in either dotted decimal notation or
173 by using the hostname:
174
175 ip.src == 192.168.1.1
176 ip.dst eq www.mit.edu
177
178 IPv4 addresses can be compared with the same logical relations as
179 numbers: eq, ne, gt, ge, lt, and le. The IPv4 address is stored in host
180 order, so you do not have to worry about the endianness of an IPv4
181 address when using it in a display filter.
182
183 Classless Inter-Domain Routing (CIDR) notation can be used to test if
184 an IPv4 address is in a certain subnet. For example, this display
185 filter will find all packets in the 129.111 network:
186
187 ip.addr == 129.111.0.0/16
188
189 Remember, the number after the slash represents the number of bits used
190 to represent the network. CIDR notation can also be used with
191 hostnames, as in this example of finding IP addresses on the same
192 network as 'sneezy' (requires that 'sneezy' resolve to an IP address
193 for filter to be valid):
194
195 ip.addr eq sneezy/24
196
197 The CIDR notation can only be used on IP addresses or hostnames, not in
198 variable names. So, a display filter like "ip.src/24 == ip.dst/24" is
199 not valid (yet).
200
201 Transaction and other IDs are often represented by unsigned 16 or 32
202 bit integers and formatted as a hexadecimal string with "0x" prefix:
203
204 (dhcp.id == 0xfe089c15) || (ip.id == 0x0373)
205
206 Strings are enclosed in double quotes:
207
208 http.request.method == "POST"
209
210 Inside double quotes, you may use a backslash to embed a double quote
211 or an arbitrary byte represented in either octal or hexadecimal.
212
213 browser.comment == "An embedded \" double-quote"
214
215 Use of hexadecimal to look for "HEAD":
216
217 http.request.method == "\x48EAD"
218
219 Use of octal to look for "HEAD":
220
221 http.request.method == "\110EAD"
222
223 This means that you must escape backslashes with backslashes inside
224 double quotes.
225
226 smb.path contains "\\\\SERVER\\SHARE"
227
228 looks for \\SERVER\SHARE in "smb.path". This may be more conveniently
229 written as
230
231 smb.path contains r"\\SERVER\SHARE"
232
233 String literals prefixed with 'r' are called "raw strings". Such
234 strings treat backslash as a literal character. Double quotes may still
235 be escaped with backslash but note that backslashes are always
236 preserved in the result.
237
238 The slice operator
239 You can take a slice of a field if the field is a text string or a byte
240 array. For example, you can filter on the vendor portion of an ethernet
241 address (the first three bytes) like this:
242
243 eth.src[0:3] == 00:00:83
244
245 Another example is:
246
247 http.content_type[0:4] == "text"
248
249 You can use the slice operator on a protocol name, too. The "frame"
250 protocol can be useful, encompassing all the data captured by Wireshark
251 or TShark.
252
253 token[0:5] ne 0.0.0.1.1
254 llc[0] eq aa
255 frame[100-199] contains "wireshark"
256
257 The following syntax governs slices:
258
259 [i:j] i = start_offset, j = length
260 [i-j] i = start_offset, j = end_offset, inclusive.
261 [i] i = start_offset, length = 1
262 [:j] start_offset = 0, length = j
263 [i:] start_offset = i, end_offset = end_of_field
264
265 Offsets can be negative, in which case they indicate the offset from
266 the end of the field. The last byte of the field is at offset -1, the
267 last but one byte is at offset -2, and so on. Here’s how to check the
268 last four bytes of a frame:
269
270 frame[-4:4] == 0.1.2.3
271
272 or
273
274 frame[-4:] == 0.1.2.3
275
276 A slice is always compared against either a string or a byte sequence.
277 As a special case, when the slice is only 1 byte wide, you can compare
278 it against a hex integer that is 0xff or less (which means it fits
279 inside one byte). This is not allowed for byte sequences greater than
280 one byte, because then one would need to specify the endianness of the
281 multi-byte integer. Also, this is not allowed for decimal numbers,
282 since they would be confused with hex numbers that are already allowed
283 as byte strings. Nevertheless, single-byte hex integers can be
284 convenient:
285
286 frame[4] == 0xff
287
288 Slices can be combined. You can concatenate them using the comma
289 operator:
290
291 ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b
292
293 This concatenates offset 1, offsets 3-5, and offset 9 to the end of the
294 ftp data.
295
296 The membership operator
297 A field may be checked for matches against a set of values simply with
298 the membership operator. For instance, you may find traffic on common
299 HTTP/HTTPS ports with the following filter:
300
301 tcp.port in {80, 443, 8080}
302
303 as opposed to the more verbose:
304
305 tcp.port == 80 or tcp.port == 443 or tcp.port == 8080
306
307 To find HTTP requests using the HEAD or GET methods:
308
309 http.request.method in {"HEAD", "GET"}
310
311 The set of values can also contain ranges:
312
313 tcp.port in {443, 4430..4434}
314 ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9}
315 frame.time_delta in {10 .. 10.5}
316
317 Type conversions
318 If a field is a text string or a byte array, it can be expressed in
319 whichever way is most convenient.
320
321 So, for instance, the following filters are equivalent:
322
323 http.request.method == "GET"
324 http.request.method == 47.45.54
325
326 A range can also be expressed in either way:
327
328 frame[60:2] gt 50.51
329 frame[60:2] gt "PQ"
330
331 Bit field operations
332 It is also possible to define tests with bit field operations.
333 Currently the following bit field operation is supported:
334
335 bitwise_and, & Bitwise AND
336
337 The bitwise AND operation allows testing to see if one or more bits are
338 set. Bitwise AND operates on integer protocol fields and slices.
339
340 When testing for TCP SYN packets, you can write:
341
342 tcp.flags & 0x02
343
344 That expression will match all packets that contain a "tcp.flags" field
345 with the 0x02 bit, i.e. the SYN bit, set.
346
347 Similarly, filtering for all WSP GET and extended GET methods is
348 achieved with:
349
350 wsp.pdu_type & 0x40
351
352 When using slices, the bit mask must be specified as a byte string, and
353 it must have the same number of bytes as the slice itself, as in:
354
355 ip[42:2] & 40:ff
356
357 Logical expressions
358 Tests can be combined using logical expressions. These too are
359 expressible in C-like syntax or with English-like abbreviations:
360
361 and, && Logical AND
362 or, || Logical OR
363 not, ! Logical NOT
364
365 Expressions can be grouped by parentheses as well. The following are
366 all valid display filter expressions:
367
368 tcp.port == 80 and ip.src == 192.168.2.1
369 not llc
370 http and frame[100-199] contains "wireshark"
371 (ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip
372
373 Remember that whenever a protocol or field name occurs in an
374 expression, the "exists" operator is implicitly called. The "exists"
375 operator has the highest priority. This means that the first filter
376 expression must be read as "show me the packets for which tcp.port
377 exists and equals 80, and ip.src exists and equals 192.168.2.1". The
378 second filter expression means "show me the packets where not exists
379 llc", or in other words "where llc does not exist" and hence will match
380 all packets that do not contain the llc protocol. The third filter
381 expression includes the constraint that offset 199 in the frame exists,
382 in other words the length of the frame is at least 200.
383
384 Each comparison has an implicit exists test for any field value. Care
385 must be taken when using the display filter to remove noise from the
386 packet trace. If, for example, you want to filter out all IP multicast
387 packets to address 224.1.2.3, then using:
388
389 ip.dst ne 224.1.2.3
390
391 may be too restrictive. This is the same as writing:
392
393 ip.dst and ip.dst ne 224.1.2.3
394
395 The filter selects only frames that have the "ip.dst" field. Any other
396 frames, including all non-IP packets, will not be displayed. To display
397 the non-IP packets as well, you can use one of the following two
398 expressions:
399
400 not ip.dst or ip.dst ne 224.1.2.3
401 not ip.dst eq 224.1.2.3
402
403 The first filter uses "not ip.dst" to include all non-IP packets and
404 then lets "ip.dst ne 224.1.2.3" filter out the unwanted IP packets. The
405 second filter also negates the implicit existance test and so is a
406 shorter way to write the first.
407
409 The entire list of display filters is too large to list here. You can
410 can find references and examples at the following locations:
411
412 • The online Display Filter Reference:
413 https://www.wireshark.org/docs/dfref/
414
415 • View:Internals:Supported Protocols in Wireshark
416
417 • tshark -G fields on the command line
418
419 • The Wireshark wiki:
420 https://gitlab.com/wireshark/wireshark/-/wikis/DisplayFilters
421
423 The wireshark-filter(4) manpage is part of the Wireshark distribution.
424 The latest version of Wireshark can be found at
425 https://www.wireshark.org.
426
427 Regular expressions in the "matches" operator are provided by GRegex in
428 GLib. See
429 https://developer-old.gnome.org/glib/stable/glib-regex-syntax.html or
430 https://www.pcre.org/ for more information.
431
432 This manpage does not describe the capture filter syntax, which is
433 different. See the manual page of pcap-filter(7) or, if that doesn’t
434 exist, tcpdump(8), or, if that doesn’t exist,
435 https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters for a
436 description of capture filters.
437
438 Display Filters are also described in the User’s Guide:
439 https://www.wireshark.org/docs/wsug_html_chunked/ChWorkBuildDisplayFilterSection.html
440
442 wireshark(1), tshark(1), editcap(1), pcap(3), pcap-filter(7) or
443 tcpdump(8) if it doesn’t exist.
444
446 See the list of authors in the Wireshark man page for a list of authors
447 of that code.
448
449
450
451 2021-11-25 WIRESHARK-FILTER(4)