1WIRESHARK-FILTER(4) WIRESHARK-FILTER(4)
2
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 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 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 Whenever a protocol or field appears as the argument of a function in a
38 filter, an exists operator for that protocol or field implicitly
39 appears.
40 Values and operators
42 Each field has a value, and that value can be used in operations with
43 comparable values (which may be literals, other fields, or function
44 results). The value of a field is not necessarily what appears in the
45 Wireshark display or TShark output. For example, a protocol is
46 semantically equivalent to the sequence of bytes that it spans, not its
47 displayed text in the protocol tree.
48 Comparison operators
50 The comparison operators can be expressed either through English-like
51 abbreviations or through C-like symbols:
52 eq, == Equal
54 ne, != Not Equal
55 gt, > Greater Than
56 lt, < Less Than
57 ge, >= Greater than or Equal to
58 le, <= Less than or Equal to
59 The ordering depends on the value type in the usual way (e.g.,
61 lexicographic for strings and arithmetic for integers.) A field may
62 appear more than once in a given frame. In that case equality can be
63 strict (all fields must match the condition) or not (any field must
64 match the condition). The inequality is the logical negation of
65 equality. The following table contains all equality operators, their
66 aliases and meaning:
67 eq, any_eq, == Any field must be equal
69 ne, all_ne, != All fields must be not equal
70 all_eq, === All fields must be equal
71 any_ne, !== Any fields must be not equal
72 The operators "any" or "all" can be used with any comparison operator
74 to make the test match any or all fields:
75 all tcp.port > 1024
77 any ip.addr != 1.1.1.1
79 The "any" and "all" modifiers take precedence over comparison operators
81 such as "===" and "any_eq".
82 Search and match operators
84 Additional operators exist expressed only in English, not C-like
85 syntax:
86 contains Does the protocol, field or slice contain a value
88 matches, ~ Does the string match the given case-insensitive
89 Perl-compatible regular expression
90 The "contains" operator allows a filter to search for a sequence of
92 characters, expressed as a string, or bytes, expressed as a byte array.
93 The type of the left hand side of the "contains" operator must be
94 comparable to that of the right hand side after any implicit or
95 explicit conversions.
96 For example, to search for a given HTTP URL in a capture, the following
98 filter can be used:
99 http contains "https://www.wireshark.org"
101 The "contains" operator cannot be used on atomic fields, such as
103 numbers or IP addresses.
104 The "matches" or "~" operator allows a filter to apply to a specified
106 Perl-compatible regular expression (PCRE2). The regular expression must
107 be a double quoted string. The left hand side of the "matches" operator
108 must be a string, which can be a non-stringlike field implicitly or
109 explicitly converted to a string. Matches are case-insensitive by
110 default. For example, to search for a given WAP WSP User-Agent, you can
111 write:
112 wsp.header.user_agent matches "cldc"
114 This would match "cldc", "CLDC", "cLdC" or any other combination of
116 upper and lower case letters.
117 You can force case sensitivity using
119 wsp.header.user_agent matches "(?-i)cldc"
121 This is an example of PCRE2’s (?option) construct. (?-i) performs a
123 case-sensitive pattern match but other options can be specified as
124 well. More information can be found in the
125 pcre2pattern(3)|https://www.pcre.org/current/doc/html/pcre2pattern.html
126 man page.
127 Functions
129 The filter language has the following functions:
130 upper(string-field) - converts a string field to uppercase
132 lower(string-field) - converts a string field to lowercase
133 len(field) - returns the byte length of a string or bytes field
134 count(field) - returns the number of field occurrences in a frame
135 string(field) - converts a non-string field to string
136 max(f1,...,fn) - return the maximum value
137 min(f1,...,fn) - return the minimum value
138 abs(field) - return the absolute value of numeric fields
139 upper() and lower() are useful for performing case-insensitive string
141 comparisons. For example:
142 upper(ncp.nds_stream_name) contains "MACRO"
144 lower(mount.dump.hostname) == "angel"
145 string() converts a field value to a string, suitable for use with
147 operators like "matches" or "contains". Integer fields are converted to
148 their decimal representation. It can be used with IP/Ethernet addresses
149 (as well as others), but not with string or byte fields. For example:
150 string(frame.number) matches "[13579]$"
152 gives you all the odd packets.
154 max() and min() take any number of arguments and returns one value,
156 respectively the largest/smallest. The arguments must all have the same
157 type.
158 Protocol field types
160 Each protocol field is typed. The types are:
161 ASN.1 object identifier, plain or relative
163 AX.25 address
164 Boolean
165 Byte sequence
166 Character string
167 Character, 1 byte
168 Date and time
169 Ethernet or other MAC address
170 EUI64 address
171 Fibre Channel WWN
172 Floating point, single or double precision
173 Frame number
174 Globally Unique Identifier
175 IEEE-11073 floating point, 16 or 32 bits
176 IPv4 address
177 IPv6 address
178 IPX network number
179 Label
180 OSI System-ID
181 Protocol
182 Signed integer, 1, 2, 3, 4, or 8 bytes
183 Time offset
184 Unsigned integer, 1, 2, 3, 4, or 8 bytes
185 VINES address
186 An integer may be expressed in decimal, octal, hexadecimal or binary
188 notation, or as a C-style character constant. The following seven
189 display filters are equivalent:
190 frame.len > 10
192 frame.len > 012
193 frame.len > 0xa
194 frame.len > 0b1010
195 frame.len > '\n'
196 frame.len > '\x0a'
197 frame.len > '\012'
198 Boolean values are either true or false. In a display filter expression
200 testing the value of a Boolean field, true is expressed as the word
201 "True" or "TRUE" (without quotes) or any non-zero number. False is
202 expressed as "False" or "FALSE" or the number zero. For example, a
203 token-ring packet’s source route field is Boolean. To find any
204 source-routed packets, a display filter would be any of the following:
205 tr.sr == 1
207 tr.sr == True
208 tr.sr == TRUE
209 Non source-routed packets can be found with:
211 tr.sr == 0
213 tr.sr == False
214 tr.sr == FALSE
215 Ethernet addresses and byte arrays are represented by hex digits. The
217 hex digits may be separated by colons, periods, or hyphens:
218 eth.dst eq ff:ff:ff:ff:ff:ff
220 aim.data == 0.1.0.d
221 fddi.src == aa-aa-aa-aa-aa-aa
222 echo.data == 7a
223 IPv4 addresses can be represented in either dotted decimal notation or
225 by using the hostname:
226 ip.src == 192.168.1.1
228 ip.dst eq www.mit.edu
229 IPv4 addresses can be compared with the same logical relations as
231 numbers: eq, ne, gt, ge, lt, and le. The IPv4 address is stored in host
232 order, so you do not have to worry about the endianness of an IPv4
233 address when using it in a display filter.
234 Classless Inter-Domain Routing (CIDR) notation can be used to test if
236 an IPv4 address is in a certain subnet. For example, this display
237 filter will find all packets in the 129.111 network:
238 ip.addr == 129.111.0.0/16
240 Remember, the number after the slash represents the number of bits used
242 to represent the network. CIDR notation can also be used with
243 hostnames, as in this example of finding IP addresses on the same
244 network as 'sneezy' (requires that 'sneezy' resolve to an IP address
245 for filter to be valid):
246 ip.addr eq sneezy/24
248 The CIDR notation can only be used on IP addresses or hostnames, not in
250 variable names. So, a display filter like "ip.src/24 == ip.dst/24" is
251 not valid (yet).
252 Transaction and other IDs are often represented by unsigned 16 or 32
254 bit integers and formatted as a hexadecimal string with "0x" prefix:
255 (dhcp.id == 0xfe089c15) || (ip.id == 0x0373)
257 Strings are enclosed in double quotes:
259 http.request.method == "POST"
261 Inside double quotes, you may use a backslash to embed a double quote
263 or an arbitrary byte represented in either octal or hexadecimal.
264 browser.comment == "An embedded \" double-quote"
266 Use of hexadecimal to look for "HEAD":
268 http.request.method == "\x48EAD"
270 Use of octal to look for "HEAD":
272 http.request.method == "\110EAD"
274 This means that you must escape backslashes with backslashes inside
276 double quotes.
277 smb.path contains "\\\\SERVER\\SHARE"
279 looks for \\SERVER\SHARE in "smb.path". This may be more conveniently
281 written as
282 smb.path contains r"\\SERVER\SHARE"
284 String literals prefixed with 'r' are called "raw strings". Such
286 strings treat backslash as a literal character. Double quotes may still
287 be escaped with backslash but note that backslashes are always
288 preserved in the result.
289 The following table lists all escape sequences supported with strings
291 and character constants:
292 \' single quote
294 \" double quote
295 \\ backslash
296 \a audible bell
297 \b backspace
298 \f form feed
299 \n line feed
300 \r carriage return
301 \t horizontal tab
302 \v vertical tab
303 \NNN arbitrary octal value
304 \xNN arbitrary hexadecimal value
305 \uNNNN Unicode codepoint U+NNNN
306 \UNNNNNNNN Unicode codepoint U+NNNNNNNN
307 Date and time values can be given in ISO 8601 format or using a legacy
309 month-year-time format:
310 "2020-07-04T12:34:56"
312 "Sep 26, 2004 23:18:04.954975"
313 The 'T' separator in ISO 8601 can be omitted. ISO 8601 supports
315 timezone designators as UTC or an offset from UTC. Legacy formats can
316 append the value "UTC" at the end to specify time in Coordinated
317 Universal Time. Otherwise date and time values are interpreted as local
318 time.
319 The slice operator
321 You can take a slice of a field if the field is a text string or a byte
322 array. For example, you can filter on the vendor portion of an ethernet
323 address (the first three bytes) like this:
324 eth.src[0:3] == 00:00:83
326 Another example is:
328 http.content_type[0:4] == "text"
330 You can use the slice operator on a protocol name, too. The "frame"
332 protocol can be useful, encompassing all the data captured by Wireshark
333 or TShark.
334 token[0:5] ne 0.0.0.1.1
336 llc[0] eq aa
337 frame[100-199] contains "wireshark"
338 The following syntax governs slices:
340 [i:j] i = start_offset, j = length
342 [i-j] i = start_offset, j = end_offset, inclusive.
343 [i] i = start_offset, length = 1
344 [:j] start_offset = 0, length = j
345 [i:] start_offset = i, end_offset = end_of_field
346 Offsets can be negative, in which case they indicate the offset from
348 the end of the field. The last byte of the field is at offset -1, the
349 last but one byte is at offset -2, and so on. Here’s how to check the
350 last four bytes of a frame:
351 frame[-4:4] == 0.1.2.3
353 or
355 frame[-4:] == 0.1.2.3
357 A slice can always be compared against either a string or a byte
359 sequence.
360 Slices can be combined. You can concatenate them using the comma
362 operator:
363 ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b
365 This concatenates offset 1, offsets 3-5, and offset 9 to the end of the
367 ftp data.
368 The layer operator
370 A field can be restricted to a certain layer in the protocol stack
371 using the layer operator (#), followed by a decimal number:
372 ip.addr#2 == 192.168.30.40
374 matches only the inner (second) layer in the packet. Layers use simple
376 stacking semantics and protocol layers are counted sequentially
377 starting from 1. For example, in a packet that contains two IPv4
378 headers, the outer (first) source address can be matched with
379 "ip.src#1" and the inner (second) source address can be matched with
380 "ip.src#2".
381 For more complicated ranges the same syntax used with slices is valid:
383 tcp.port#[2-4]
385 means layers number 2, 3 or 4 inclusive. The hash symbol is required to
387 distinguish a layer range from a slice.
388 The membership operator
390 A field may be checked for matches against a set of values simply with
391 the membership operator. For instance, you may find traffic on common
392 HTTP/HTTPS ports with the following filter:
393 tcp.port in {80,443,8080}
395 as opposed to the more verbose:
397 tcp.port == 80 or tcp.port == 443 or tcp.port == 8080
399 To find HTTP requests using the HEAD or GET methods:
401 http.request.method in {"HEAD", "GET"}
403 The set of values can also contain ranges:
405 tcp.port in {443, 4430..4434}
407 ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9}
408 frame.time_delta in {10 .. 10.5}
409 Implicit type conversions
411 Fields which are sequences of bytes, including protocols, are
412 implicitly converted to strings for comparisons against (double quoted)
413 literal strings and raw strings.
414 So, for instance, the following filters are equivalent:
416 tcp.payload contains "GET"
418 tcp.payload contains 47.45.54
419 As noted above, a slice can also be compared in either way:
421 frame[60:2] gt 50.51
423 frame[60:2] gt "PQ"
424 The inverse does not occur; stringlike fields are not implicitly
426 converted to byte arrays. (Some operators allow stringlike fields to be
427 compared with unquoted literals, which are then treated as strings;
428 this is deprecated in general and specifically disallowed by the
429 "matches" operator. Literal strings should be double quoted for
430 clarity.)
431 A hex integer that is 0xff or less (which means it fits inside one
433 byte) can be implicitly converted to a byte string. This is not allowed
434 for hex integers greater than one byte, because then one would need to
435 specify the endianness of the multi-byte integer. Also, this is not
436 allowed for decimal or octal numbers, since they would be confused with
437 the hex numbers that make up byte string literals. Nevertheless,
438 single-byte hex integers can be convenient:
439 frame[4] == 0xff
441 frame[1:4] contains 0x02
442 Bitwise operators
444 It is also possible to define tests with bitwise operations. Currently
445 the following bitwise operator is supported:
446 bitwise_and, & Bitwise AND
448 The bitwise AND operation allows masking bits and testing to see if one
450 or more bits are set. Bitwise AND operates on integer protocol fields
451 and slices.
452 When testing for TCP SYN packets, you can write:
454 tcp.flags & 0x02
456 That expression will match all packets that contain a "tcp.flags" field
458 with the 0x02 bit, i.e. the SYN bit, set.
459 To match locally administered unicast ethernet addresses you can use:
461 eth.addr[0] & 0x0f == 2
463 When using slices, the bit mask must be specified as a byte string, and
465 it must have the same number of bytes as the slice itself, as in:
466 ip[42:2] & 40:ff
468 Arithmetic operators
470 Arithmetic expressions are supported with the usual operators:
471 + Addition
473 - Subtraction
474 * Multiplication
475 / Division
476 % Modulo (integer remainder)
477 For example it is possible to filter for UDP destination ports greater
479 or equal by one to the source port with the expression:
480 udp.dstport >= udp.srcport + 1
482 It is possible to group arithmetic expressions using curly brackets
484 (parenthesis will not work for this):
485 tcp.dstport >= 4 * {tcp.srcport + 3}
487 Do not confuse this usage of curly brackets with set membership.
489 An unfortunate quirk in the filter syntax is that the subtraction
491 operator must be preceded by a space character, so "A-B" must be
492 written as "A -B" or "A - B".
493 Protocol field references
495 A variable using a sigil with the form ${some.proto.field} is called a
496 field reference. A field reference is a field value read from the
497 currently selected frame in the GUI. This is useful to build dynamic
498 filters such as, frames since the last five minutes to the selected
499 frame:
500 frame.time_relative >= ${frame.time_relative} - 300
502 Field references share a similar notation to macros but are distinct
504 syntactical elements in the filter language.
505 Logical expressions
507 Tests can be combined using logical expressions. These too are
508 expressible in C-like syntax or with English-like abbreviations. The
509 following table lists the logical operators from highest to lowest
510 precedence:
511 not, ! Logical NOT (right-associative)
513 and, && Logical AND (left-associative)
514 or, || Logical OR (left-associative)
515 The evaluation is always performed left to right. Expressions can be
517 grouped by parentheses as well. The expression "A and B or not C or D
518 and not E or F" is read:
519 (A and B) or (not C) or (D and (not E)) or F
521 It’s usually better to be explicit about grouping using parenthesis.
523 The following are all valid display filter expressions:
524 tcp.port == 80 and ip.src == 192.168.2.1
526 not llc
527 http and frame[100-199] contains "wireshark"
528 (ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip
529 Remember that whenever a protocol or field name occurs in an
531 expression, the "exists" operator is implicitly called. The "exists"
532 operator has the highest priority. This means that the first filter
533 expression must be read as "show me the packets for which tcp.port
534 exists and equals 80, and ip.src exists and equals 192.168.2.1". The
535 second filter expression means "show me the packets where not exists
536 llc", or in other words "where llc does not exist" and hence will match
537 all packets that do not contain the llc protocol. The third filter
538 expression includes the constraint that offset 199 in the frame exists,
539 in other words the length of the frame is at least 200.
540 Each comparison has an implicit exists test for any field value. Care
542 must be taken when using the display filter to remove noise from the
543 packet trace. If, for example, you want to filter out all IP multicast
544 packets to address 224.1.2.3, then using:
545 ip.dst ne 224.1.2.3
547 may be too restrictive. This is the same as writing:
549 ip.dst and ip.dst ne 224.1.2.3
551 The filter selects only frames that have the "ip.dst" field. Any other
553 frames, including all non-IP packets, will not be displayed. To display
554 the non-IP packets as well, you can use one of the following two
555 expressions:
556 not ip.dst or ip.dst ne 224.1.2.3
558 not ip.dst eq 224.1.2.3
559 The first filter uses "not ip.dst" to include all non-IP packets and
561 then lets "ip.dst ne 224.1.2.3" filter out the unwanted IP packets. The
562 second filter also negates the implicit existance test and so is a
563 shorter way to write the first.
564
566 The entire list of display filters is too large to list here. You can
567 can find references and examples at the following locations:
568 • The online Display Filter Reference:
570 https://www.wireshark.org/docs/dfref/
571 • View:Internals:Supported Protocols in Wireshark
573 • tshark -G fields on the command line
575 • The Wireshark wiki:
577 https://gitlab.com/wireshark/wireshark/-/wikis/DisplayFilters
578
580 The wireshark-filter(4) manpage is part of the Wireshark distribution.
581 The latest version of Wireshark can be found at
582 https://www.wireshark.org.
583 Regular expressions in the "matches" operator are provided by the PCRE2
585 library. See https://www.pcre.org/ for more information.
586 This manpage does not describe the capture filter syntax, which is
588 different. See the manual page of pcap-filter(7) or, if that doesn’t
589 exist, tcpdump(8), or, if that doesn’t exist,
590 https://gitlab.com/wireshark/wireshark/-/wikis/CaptureFilters for a
591 description of capture filters.
592 Display Filters are also described in the User’s Guide:
594 https://www.wireshark.org/docs/wsug_html_chunked/ChWorkBuildDisplayFilterSection.html
595
597 wireshark(1), tshark(1), editcap(1), pcap(3), pcap-filter(7) or
598 tcpdump(8) if it doesn’t exist.
599
601 See the list of authors in the Wireshark man page for a list of authors
602 of that code.
603 2022-12-08 WIRESHARK-FILTER(4)