1WIRESHARK-FILTER(4)                                        WIRESHARK-FILTER(4)
2
3
4

NAME

6       wireshark-filter - Wireshark display filter syntax and reference
7

SYNOPSIS

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

DESCRIPTION

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

FILTER SYNTAX

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       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
41   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
49   Comparison operators
50       The comparison operators can be expressed either through English-like
51       abbreviations or through C-like symbols:
52
53           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
60       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
68           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
73       The operators "any" or "all" can be used with any comparison operator
74       to make the test match any or all fields:
75
76           all tcp.port > 1024
77
78           any ip.addr != 1.1.1.1
79
80       The "any" and "all" modifiers take precedence over comparison operators
81       such as "===" and "any_eq".
82
83   Search and match operators
84       Additional operators exist expressed only in English, not C-like
85       syntax:
86
87           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
91       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
97       For example, to search for a given HTTP URL in a capture, the following
98       filter can be used:
99
100           http contains "https://www.wireshark.org"
101
102       The "contains" operator cannot be used on atomic fields, such as
103       numbers or IP addresses.
104
105       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
113           wsp.header.user_agent matches "cldc"
114
115       This would match "cldc", "CLDC", "cLdC" or any other combination of
116       upper and lower case letters.
117
118       You can force case sensitivity using
119
120           wsp.header.user_agent matches "(?-i)cldc"
121
122       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
128   Functions
129       The filter language has the following functions:
130
131           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
140       upper() and lower() are useful for performing case-insensitive string
141       comparisons. For example:
142
143           upper(ncp.nds_stream_name) contains "MACRO"
144           lower(mount.dump.hostname) == "angel"
145
146       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
151           string(frame.number) matches "[13579]$"
152
153       gives you all the odd packets.
154
155       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
159   Protocol field types
160       Each protocol field is typed. The types are:
161
162           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
187       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
191           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
199       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
206           tr.sr == 1
207           tr.sr == True
208           tr.sr == TRUE
209
210       Non source-routed packets can be found with:
211
212           tr.sr == 0
213           tr.sr == False
214           tr.sr == FALSE
215
216       Ethernet addresses and byte arrays are represented by hex digits. The
217       hex digits may be separated by colons, periods, or hyphens:
218
219           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
224       IPv4 addresses can be represented in either dotted decimal notation or
225       by using the hostname:
226
227           ip.src == 192.168.1.1
228           ip.dst eq www.mit.edu
229
230       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
235       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
239           ip.addr == 129.111.0.0/16
240
241       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
247           ip.addr eq sneezy/24
248
249       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
253       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
256           (dhcp.id == 0xfe089c15) || (ip.id == 0x0373)
257
258       Strings are enclosed in double quotes:
259
260           http.request.method == "POST"
261
262       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
265           browser.comment == "An embedded \" double-quote"
266
267       Use of hexadecimal to look for "HEAD":
268
269           http.request.method == "\x48EAD"
270
271       Use of octal to look for "HEAD":
272
273           http.request.method == "\110EAD"
274
275       This means that you must escape backslashes with backslashes inside
276       double quotes.
277
278           smb.path contains "\\\\SERVER\\SHARE"
279
280       looks for \\SERVER\SHARE in "smb.path". This may be more conveniently
281       written as
282
283           smb.path contains r"\\SERVER\SHARE"
284
285       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
290       The following table lists all escape sequences supported with strings
291       and character constants:
292
293           \'          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
308       Date and time values can be given in ISO 8601 format or using a legacy
309       month-year-time format:
310
311           "2020-07-04T12:34:56"
312           "Sep 26, 2004 23:18:04.954975"
313
314       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
320   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
325           eth.src[0:3] == 00:00:83
326
327       Another example is:
328
329           http.content_type[0:4] == "text"
330
331       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
335           token[0:5] ne 0.0.0.1.1
336           llc[0] eq aa
337           frame[100-199] contains "wireshark"
338
339       The following syntax governs slices:
340
341           [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
347       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
352           frame[-4:4] == 0.1.2.3
353
354       or
355
356           frame[-4:] == 0.1.2.3
357
358       A slice can always be compared against either a string or a byte
359       sequence.
360
361       Slices can be combined. You can concatenate them using the comma
362       operator:
363
364           ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b
365
366       This concatenates offset 1, offsets 3-5, and offset 9 to the end of the
367       ftp data.
368
369   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
373           ip.addr#2 == 192.168.30.40
374
375       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
382       For more complicated ranges the same syntax used with slices is valid:
383
384           tcp.port#[2-4]
385
386       means layers number 2, 3 or 4 inclusive. The hash symbol is required to
387       distinguish a layer range from a slice.
388
389   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
394           tcp.port in {80,443,8080}
395
396       as opposed to the more verbose:
397
398           tcp.port == 80 or tcp.port == 443 or tcp.port == 8080
399
400       To find HTTP requests using the HEAD or GET methods:
401
402           http.request.method in {"HEAD", "GET"}
403
404       The set of values can also contain ranges:
405
406           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
410   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
415       So, for instance, the following filters are equivalent:
416
417           tcp.payload contains "GET"
418           tcp.payload contains 47.45.54
419
420       As noted above, a slice can also be compared in either way:
421
422           frame[60:2] gt 50.51
423           frame[60:2] gt "PQ"
424
425       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
432       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
440           frame[4] == 0xff
441           frame[1:4] contains 0x02
442
443   Bitwise operators
444       It is also possible to define tests with bitwise operations. Currently
445       the following bitwise operator is supported:
446
447           bitwise_and, &        Bitwise AND
448
449       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
453       When testing for TCP SYN packets, you can write:
454
455           tcp.flags & 0x02
456
457       That expression will match all packets that contain a "tcp.flags" field
458       with the 0x02 bit, i.e. the SYN bit, set.
459
460       To match locally administered unicast ethernet addresses you can use:
461
462           eth.addr[0] & 0x0f == 2
463
464       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
467           ip[42:2] & 40:ff
468
469   Arithmetic operators
470       Arithmetic expressions are supported with the usual operators:
471
472           +   Addition
473           -   Subtraction
474           *   Multiplication
475           /   Division
476           %   Modulo (integer remainder)
477
478       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
481           udp.dstport >= udp.srcport + 1
482
483       It is possible to group arithmetic expressions using curly brackets
484       (parenthesis will not work for this):
485
486           tcp.dstport >= 4 * {tcp.srcport + 3}
487
488       Do not confuse this usage of curly brackets with set membership.
489
490       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
494   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
501           frame.time_relative >= ${frame.time_relative} - 300
502
503       Field references share a similar notation to macros but are distinct
504       syntactical elements in the filter language.
505
506   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
512           not, ! Logical NOT   (right-associative)
513           and, &&   Logical AND   (left-associative)
514           or,  ||   Logical OR    (left-associative)
515
516       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
520           (A and B) or (not C) or (D and (not E)) or F
521
522       It’s usually better to be explicit about grouping using parenthesis.
523       The following are all valid display filter expressions:
524
525           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
530       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
541       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
546           ip.dst ne 224.1.2.3
547
548       may be too restrictive. This is the same as writing:
549
550           ip.dst and ip.dst ne 224.1.2.3
551
552       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
557           not ip.dst or ip.dst ne 224.1.2.3
558           not ip.dst eq 224.1.2.3
559
560       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

FILTER FIELD REFERENCE

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
569       •   The online Display Filter Reference:
570           https://www.wireshark.org/docs/dfref/
571
572View:Internals:Supported Protocols in Wireshark
573
574       •   tshark -G fields on the command line
575
576       •   The Wireshark wiki:
577           https://gitlab.com/wireshark/wireshark/-/wikis/DisplayFilters
578

NOTES

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
584       Regular expressions in the "matches" operator are provided by the PCRE2
585       library. See https://www.pcre.org/ for more information.
586
587       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
593       Display Filters are also described in the User’s Guide:
594       https://www.wireshark.org/docs/wsug_html_chunked/ChWorkBuildDisplayFilterSection.html
595

SEE ALSO

597       wireshark(1), tshark(1), editcap(1), pcap(3), pcap-filter(7) or
598       tcpdump(8) if it doesn’t exist.
599

AUTHORS

601       See the list of authors in the Wireshark man page for a list of authors
602       of that code.
603
604
605
606                                  2023-08-31               WIRESHARK-FILTER(4)
Impressum