6.4. Building Display Filter Expressions (2024)

The simplest display filter is one that displays a single protocol.To only display packets containing a particular protocol, type the protocolinto Wireshark’s display filter toolbar. For example, to onlydisplay TCP packets, type tcp into Wireshark’s display filter toolbar.Similarly, to only displaypackets containing a particular field, type the fieldinto Wireshark’s display filter toolbar. For example, to only displayHTTP requests, type http.request into Wireshark’s display filter toolbar.

You can filter on any protocol that Wireshark supports. You canalso filter on any field that a dissector adds to the tree view, if the dissectorhas added an abbreviation for that field. A full list of the available protocolsand fields is available through the menu itemView → Internals → Supported Protocols.

You can build display filters that compare values using a number of differentcomparison operators. For example, to only display packets to orfrom the IP address 192.168.0.1, use ip.addr==192.168.0.1.

A complete list of available comparison operators is shown in Table6.6, “Display Filter comparison operators”.

	Tip
	English and C-like operators are interchangeable and can be mixed within a filter string.

	Note
	The meaning of != (all not equal) was changed in Wireshark 3.6.Before it used to mean "any not equal".

All protocol fields have a type. Section6.4.2.1, “Display Filter Field Types” provides a listof the types with examples of how to use them in display filters.

udp contains 81:60:03

sip.To contains "a1762"

http.host matches "acme\\.(org|com|net)"

tcp.flags & 0x02

6.4.2.3.Possible Pitfalls Using Regular Expressions

String literals containing regular expressions are parsed twice. Once by Wireshark’s displayfilter engine and again by the PCRE2 library. It’s important to keep this in mind when usingthe "matches" operator with regex escape sequences and special characters.

For example, the filter expression frame matches "AB\x43" uses the string "ABC" as inputpattern to PCRE. However, the expression frame matches "AB\\x43" uses the string "AB\x43"as the pattern. In this case both expressions give the same result because Wireshark and PCREboth support the same byte escape sequence (0x43 is the ASCII hex code for C).

An example where this fails badly is foo matches "bar\x28". Because 0x28 is the ASCIIcode for ( the pattern input to PCRE is "bar(". This regular expression is syntacticallyinvalid (missing closing parenthesis). To match a literal parenthesis in a display filter regularexpression it must be escaped (twice) with backslashes.

	Tip
	Using raw strings avoids most problem with the "matches" operator and double escape requirements.

You can combine filter expressions in Wireshark using the logical operators shown in Table6.7, “Display Filter Logical Operations”

Wireshark allows you to select a subsequence of byte arrays (includingprotocols) or text strings in rather elaborate ways. After a label you canplace a pair of brackets [] containing a comma separated list of rangespecifiers.

eth.src[0:3] == 00:00:83

The example above uses the n:m format to specify a single range. In this case nis the beginning offset and m is the length of the range being specified.

eth.src[1-2] == 00:83

The example above uses the n-m format to specify a single range. In this case nis the beginning offset and m is the ending offset.

eth.src[:4] == 00:00:83:00

The example above uses the :m format, which takes everything from the beginningof a sequence to offset m. It is equivalent to 0:m

eth.src[4:] == 20:20

The example above uses the n: format, which takes everything from offset n tothe end of the sequence.

eth.src[2] == 83

The example above uses the n format to specify a single range. In this case theelement in the sequence at offset n is selected. This is equivalent to n:1.

eth.src[0:3,1-2,:4,4:,2] ==00:00:83:00:83:00:00:83:00:20:20:83

Wireshark allows you to string together single ranges in a comma separated listto form compound ranges as shown above.

You can use the slice operator on a protocol name, too, to slice thebytes associated with that protocol. The frame protocol can be useful,encompassing all the captured data (not including secondary data sourceslike decrypted data.)

Offsets can be negative, indicating an offset from the end of a field.

frame[-4:4] == 0.1.2.3frame[-4:] == 0.1.2.3

The two examples above both check the last four bytes of a frame.

Slices of string fields yield strings, and are indexed on codepointboundaries after conversation of the string to UTF-8, not bytes.

http.content_type[0:4] == "text"smpp.message_text[:10] == "Абвгдеёжзи"

The second example above will match regardless of whether the originalstring was in Windows-1251, UTF-8, or UTF-16, so long as the convertedstring starts with those ten characters.

Byte slices can be directly compared to strings; this converts thestring to the corresponding UTF-8 byte sequence. To compare stringslices with byte sequences, use the @ operator, below.

A field can be restricted to a certain layer in the protocol stack using thelayer operator (#), followed by a decimal number:

ip.addr#2 == 192.168.30.40

matches only the inner (second) layer in the packet.Layers use simple stacking semantics and protocol layers are counted sequentially starting from 1.For example, in a packet that contains two IPv4 headers, the outer (first) source address can be matched with "ip.src#1" and the inner (second) source address can be matched with "ip.src#2".

For more complicated ranges the same syntax used with slices is valid:

tcp.port#[2-4]

means layers number 2, 3 or 4 inclusive. The hash symbol is required todistinguish a layer range from a slice.

By prefixing the field name with an at sign (@) the comparison is done againstthe raw packet data for the field.

A character string must be decoded from a source encoding during dissection.If there are decoding errors the resulting string will usually containreplacement characters:

browser.comment == "string is ����"

The at operator allows testing the raw undecoded data:

@browser.comment == 73:74:72:69:6e:67:20:69:73:20:aa:aa:aa:aa

The syntactical rules for a bytes field type apply to the second example.

Note

When a bytes field is compared with a literal string, it is comparedwith the UTF-8 representation of that string. The at operator comparesa string field with the actual byte representation in the original encoding,which may not be UTF-8. As an example, SMPP has a bytes field, smpp.message, and a stringfield, smpp.message_text, that refer to the same data. If thefirst four characters of the message is the string "Text" in the UTF-16encoding, the following filters all match. smpp.message[:8] == 00:54:00:65:00:73:00:74smpp.message[:8] == "\x00T\x00e\x00s\x00t"smpp.message_text[:4] == "Test"smpp.message_text[:4] == "\x54\x65\x73\x74"@smpp.message_text[:8] == 00:54:00:65:00:73:00:[email protected]_text[:8] == "\x00T\x00e\x00s\x00t" The following filters do NOT match. @smpp.message_text[:4] == "\x00T\x00e\x00s\x00t"smpp.message[:4] == "Test"smpp.message[:8] == "Test"@smpp.message_text[:4] == "Test"@smpp.message_text[:8] == "Test" The first filter above does not match because of operator precedenceleft-to-right; [emailprotected]_text is converted to bytes before theslice operator is applied, so the length of the necessary slice is 8.The other filters do not match because the literal string "Test" isalways converted to its 4 octet UTF-8 representation when comparingagainst bytes, and it does not match the UTF-16 representation ofthe field bytes.

Wireshark allows you to test a field for membership in a set of values orfields. After the field name, use the in operator followed by the set itemssurrounded by braces {}. For example, to display packets with a TCP source ordestination port of 80, 443, or 8080, you can use tcp.port in {80, 443, 8080}.Set elements must be separated by commas.The set of values can also contain ranges: tcp.port in {443,4430..4434}.

Note

The display filter tcp.port in {80, 443, 8080} is equivalent to tcp.port == 80 || tcp.port == 443 || tcp.port == 8080 However, the display filter tcp.port in {443, 4430..4434} is not equivalent to tcp.port == 443 || (tcp.port >= 4430 && tcp.port <= 4434) This is because comparison operators are satisfied when any fieldmatches the filter, so a packet with a source port of 56789 anddestination port of port 80 would also match the second filtersince 56789 >= 4430 && 80 <= 4434 is true. In contrast, themembership operator tests a single field against the range condition.

Sets are not just limited to numbers, other types can be used as well:

http.request.method in {"HEAD", "GET"}ip.addr in {10.0.0.5 .. 10.0.0.9, 192.168.1.1..192.168.1.9}frame.time_delta in {10 .. 10.5}

You can perform the arithmetic operations on numeric fields shown in Table6.8, “Display Filter Arithmetic Operations”

An unfortunate quirk in the filter syntax is that the subtractionoperator must be preceded by a space character, so "A-B" must bewritten as "A -B" or "A - B".

Arithmetic expressions can be grouped using curly braces.

For example, frames where capture length resulted in truncated TCP options:

frame.cap_len < { 14 + ip.hdr_len + tcp.hdr_len }

The display filter language has a number of functions to convert fields, seeTable6.9, “Display Filter Functions”.

The upper and lower functions can used to force case-insensitive matches:lower(http.server) contains "apache".

To find HTTP requests with long request URIs: len(http.request.uri) > 100.Note that the len function yields the string length in bytes rather than(multi-byte) characters.

Usually an IP frame has only two addresses (source and destination), but in caseof ICMP errors or tunneling, a single packet might contain even more addresses.These packets can be found with count(ip.addr) > 2.

The string function converts a field value to a string, suitable for use with operatorslike "matches" or "contains". Integer fields are converted to their decimal representation.It can be used with IP/Ethernet addresses (as well as others), but not with string orbyte fields.

For example, to match odd frame numbers:

string(frame.number) matches "[13579]$"

To match IP addresses ending in 255 in a block of subnets (172.16 to 172.31):

string(ip.dst) matches r"^172\.(1[6-9]|2[0-9]|3[0-1])\.[0-9]{1,3}\.255"

The vals function converts an integer or boolean field value to a stringusing the field’s associated value string, if it has one.

The functions max() and min() take any number of arguments of the same typeand returns the largest/smallest respectively of the set.

max(tcp.srcport, tcp.dstport) <= 1024

An expression of the form ${some.proto.field} is called a field reference.Its value is read from the corresponding field in the currently selectedfield in the GUI. This is a powerful way to build dynamic filters, suchas frames since the last five minutes to the selected frame:

frame.time_relative >= ${frame.time_relative} - 300

or all HTTP packets whose +ip.dst value equals the "A" record ofthe DNS response in the current frame:

http && ip.dst eq ${dns.a}

The notation of field references is similar to that of macros but they aresyntactically distinct. Field references, like other complex filters, makeexcellent use cases for macros,saved filters, andfilter buttons

As protocols evolve they sometimes change names or are superseded bynewer standards. For example, DHCP extends and has largely replacedBOOTP and TLS has replaced SSL. If a protocol dissector originally usedthe older names and fields for a protocol the Wireshark development teammight update it to use the newer names and fields. In such cases theywill add an alias from the old protocol name to the new one in order tomake the transition easier.

For example, the DHCP dissector was originally developed for the BOOTPprotocol but as of Wireshark 3.0 all of the “bootp” display filterfields have been renamed to their “dhcp” equivalents. You can still usethe old filter names for the time being, e.g., “bootp.type” is equivalentto “dhcp.type” but Wireshark will show the warning “"bootp" is deprecated”when you use it. Support for the deprecated fields may be removed in the future.

In some particular cases relational expressions (equal, less than, etc.)can be ambiguous. The filter name of a protocol or protocol field can containany letter and digit in any order, possibly separated by dots. That can beindistinguishable from a literal value (usually numerical values in hexadecimal).For example the semantic value of fc can be the protocol Fibre Channel or thenumber 0xFC in hexadecimal because the 0x prefix is optional for hexadecimal numbers.

Any value that matches a registered protocol or protocol field filter name isinterpreted semantically as such. If it doesn’t match a protocol name the normalrules for parsing literal values apply.

So in the case of 'fc' the lexical token is interpreted as "Fibre Channel" andnot 0xFC. In the case of 'fd' it would be interpreted as 0xFD because it is awell-formed hexadecimal literal value (according to the rules of display filterlanguage syntax) and there is no protocol registered with the filter name 'fd'.

How ambiguous values are interpreted may change in the future. To avoid thisproblem and resolve the ambiguity there is additional syntax available.Values prefixed with a dot are always treated as a protocol name. Thedot stands for the root of the protocol namespace and is optional). Valuesprefixed with a colon are always interpreted as a byte array.

frame[10:] contains .fc or frame[10] == :fc

If you are writing a script, or you think your expression may not be giving theexpected results because of the syntactical ambiguity of some filter expressionit is advisable to use the explicit syntax to indicate the correct meaning forthat expression.