1WIRESHARK-FILTER(4) The Wireshark Network Analyzer WIRESHARK-FILTER(4)
2
6 wireshark-filter - Wireshark filter syntax and reference
7
9 wireshark [other options] [ -R "filter expression" ]
10 tshark [other options] [ -R "filter expression" ]
12
14 Wireshark and TShark share a powerful filter engine that helps remove
15 the noise from a packet trace and lets you see only the packets that
16 interest you. If a packet meets the requirements expressed in your
17 filter, then it is displayed in the list of packets. Display filters
18 let you compare the fields within a protocol against a specific value,
19 compare fields against fields, and check the existence of specified
20 fields or protocols.
21 Filters are also used by other features such as statistics generation
23 and packet list colorization (the latter is only available to
24 Wireshark). This manual page describes their syntax. A comprehensive
25 reference of filter fields can be found within Wireshark and in the
26 display filter reference at <http://www.wireshark.org/docs/dfref/>.
27
29 Check whether a field or protocol exists
30 The simplest filter allows you to check for the existence of a protocol
31 or field. If you want to see all packets which contain the IP
32 protocol, the filter would be "ip" (without the quotation marks). To
33 see all packets that contain a Token-Ring RIF field, use "tr.rif".
34 Think of a protocol or field in a filter as implicitly having the
36 "exists" operator.
37 Comparison operators
39 Fields can also be compared against values. The comparison operators
40 can be expressed either through English-like abbreviations or through
41 C-like symbols:
42 eq, == Equal
44 ne, != Not Equal
45 gt, > Greater Than
46 lt, < Less Than
47 ge, >= Greater than or Equal to
48 le, <= Less than or Equal to
49 Search and match operators
51 Additional operators exist expressed only in English, not C-like
52 syntax:
53 contains Does the protocol, field or slice contain a value
55 matches Does the protocol or text string match the given Perl
56 regular expression
57 The "contains" operator allows a filter to search for a sequence of
59 characters, expressed as a string (quoted or unquoted), or bytes,
60 expressed as a byte array. For example, to search for a given HTTP URL
61 in a capture, the following filter can be used:
62 http contains "http://www.wireshark.org"
64 The "contains" operator cannot be used on atomic fields, such as
66 numbers or IP addresses.
67 The "matches" operator allows a filter to apply to a specified Perl-
69 compatible regular expression (PCRE). The "matches" operator is only
70 implemented for protocols and for protocol fields with a text string
71 representation. For example, to search for a given WAP WSP User-Agent,
72 you can write:
73 wsp.user_agent matches "(?i)cldc"
75 This example shows an interesting PCRE feature: pattern match options
77 have to be specified with the (?option) construct. For instance, (?i)
78 performs a case-insensitive pattern match. More information on PCRE can
79 be found in the pcrepattern(3) man page (Perl Regular Expressions are
80 explained in <http://www.perldoc.com/perl5.8.0/pod/perlre.html>).
81 Note: the "matches" operator is only available if Wireshark or TShark
83 have been compiled with the PCRE library. This can be checked by
84 running:
85 wireshark -v
87 tshark -v
88 or selecting the "About Wireshark" item from the "Help" menu in
90 Wireshark.
91 Functions
93 The filter language has the following functions:
94 upper(string-field) - converts a string field to uppercase
96 lower(string-field) - converts a string field to lowercase
97 upper() and lower() are useful for performing case-insensitive string
99 comparisons. For example:
100 upper(ncp.nds_stream_name) contains "MACRO"
102 lower(mount.dump.hostname) == "angel"
103 Protocol field types
105 Each protocol field is typed. The types are:
106 ASN.1 object identifier
108 Boolean
109 Character string
110 Compiled Perl-Compatible Regular Expression (GRegex) object
111 Date and time
112 Ethernet or other MAC address
113 EUI64 address
114 Floating point (double-precision)
115 Floating point (single-precision)
116 Frame number
117 Globally Unique Identifier
118 IPv4 address
119 IPv6 address
120 IPX network number
121 Label
122 Protocol
123 Sequence of bytes
124 Signed integer, 1, 2, 3, 4, or 8 bytes
125 Time offset
126 Unsigned integer, 1, 2, 3, 4, or 8 bytes
127 An integer may be expressed in decimal, octal, or hexadecimal notation.
129 The following three display filters are equivalent:
130 frame.pkt_len > 10
132 frame.pkt_len > 012
133 frame.pkt_len > 0xa
134 Boolean values are either true or false. In a display filter
136 expression testing the value of a Boolean field, "true" is expressed as
137 1 or any other non-zero value, and "false" is expressed as zero. For
138 example, a token-ring packet's source route field is Boolean. To find
139 any source-routed packets, a display filter would be:
140 tr.sr == 1
142 Non source-routed packets can be found with:
144 tr.sr == 0
146 Ethernet addresses and byte arrays are represented by hex digits. The
148 hex digits may be separated by colons, periods, or hyphens:
149 eth.dst eq ff:ff:ff:ff:ff:ff
151 aim.data == 0.1.0.d
152 fddi.src == aa-aa-aa-aa-aa-aa
153 echo.data == 7a
154 IPv4 addresses can be represented in either dotted decimal notation or
156 by using the hostname:
157 ip.dst eq www.mit.edu
159 ip.src == 192.168.1.1
160 IPv4 addresses can be compared with the same logical relations as
162 numbers: eq, ne, gt, ge, lt, and le. The IPv4 address is stored in
163 host order, so you do not have to worry about the endianness of an IPv4
164 address when using it in a display filter.
165 Classless InterDomain Routing (CIDR) notation can be used to test if an
167 IPv4 address is in a certain subnet. For example, this display filter
168 will find all packets in the 129.111 Class-B network:
169 ip.addr == 129.111.0.0/16
171 Remember, the number after the slash represents the number of bits used
173 to represent the network. CIDR notation can also be used with
174 hostnames, as in this example of finding IP addresses on the same Class
175 C network as 'sneezy':
176 ip.addr eq sneezy/24
178 The CIDR notation can only be used on IP addresses or hostnames, not in
180 variable names. So, a display filter like "ip.src/24 == ip.dst/24" is
181 not valid (yet).
182 IPX networks are represented by unsigned 32-bit integers. Most likely
184 you will be using hexadecimal when testing IPX network values:
185 ipx.src.net == 0xc0a82c00
187 Strings are enclosed in double quotes:
189 http.request.method == "POST"
191 Inside double quotes, you may use a backslash to embed a double quote
193 or an arbitrary byte represented in either octal or hexadecimal.
194 browser.comment == "An embedded \" double-quote"
196 Use of hexadecimal to look for "HEAD":
198 http.request.method == "\x48EAD"
200 Use of octal to look for "HEAD":
202 http.request.method == "\110EAD"
204 This means that you must escape backslashes with backslashes inside
206 double quotes.
207 smb.path contains "\\\\SERVER\\SHARE"
209 looks for \\SERVER\SHARE in "smb.path".
211 The slice operator
213 You can take a slice of a field if the field is a text string or a byte
214 array. For example, you can filter on the vendor portion of an
215 ethernet address (the first three bytes) like this:
216 eth.src[0:3] == 00:00:83
218 Another example is:
220 http.content_type[0:4] == "text"
222 You can use the slice operator on a protocol name, too. The "frame"
224 protocol can be useful, encompassing all the data captured by Wireshark
225 or TShark.
226 token[0:5] ne 0.0.0.1.1
228 llc[0] eq aa
229 frame[100-199] contains "wireshark"
230 The following syntax governs slices:
232 [i:j] i = start_offset, j = length
234 [i-j] i = start_offset, j = end_offset, inclusive.
235 [i] i = start_offset, length = 1
236 [:j] start_offset = 0, length = j
237 [i:] start_offset = i, end_offset = end_of_field
238 Offsets can be negative, in which case they indicate the offset from
240 the end of the field. The last byte of the field is at offset -1, the
241 last but one byte is at offset -2, and so on. Here's how to check the
242 last four bytes of a frame:
243 frame[-4:4] == 0.1.2.3
245 or
247 frame[-4:] == 0.1.2.3
249 A slice is alwasy compared against either a string or a byte sequence.
251 As a special case, when the slice is only 1 byte wide, you can compare
252 it against a hex integer that 0xff or less (which means it fits inside
253 one byte). This is not allowed for byte sequences greater than one
254 byte, because then one would need to specify the endianness of the
255 multi-byte integer. Also, this is not allowed for decimal numbers,
256 since they would be confused with hex numbers that are already allowed
257 as byte strings. Neverthelss, single-byte hex integers can be
258 convienent:
259 frame[4] == 0xff
261 Slices can be combined. You can concatenate them using the comma
263 operator:
264 ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b
266 This concatenates offset 1, offsets 3-5, and offset 9 to the end of the
268 ftp data.
269 Type conversions
271 If a field is a text string or a byte array, it can be expressed in
272 whichever way is most convenient.
273 So, for instance, the following filters are equivalent:
275 http.request.method == "GET"
277 http.request.method == 47.45.54
278 A range can also be expressed in either way:
280 frame[60:2] gt 50.51
282 frame[60:2] gt "PQ"
283 Bit field operations
285 It is also possible to define tests with bit field operations.
286 Currently the following bit field operation is supported:
287 bitwise_and, & Bitwise AND
289 The bitwise AND operation allows testing to see if one or more bits are
291 set. Bitwise AND operates on integer protocol fields and slices.
292 When testing for TCP SYN packets, you can write:
294 tcp.flags & 0x02
296 That expression will match all packets that contain a "tcp.flags" field
298 with the 0x02 bit, i.e. the SYN bit, set.
299 Similarly, filtering for all WSP GET and extended GET methods is
301 achieved with:
302 wsp.pdu_type & 0x40
304 When using slices, the bit mask must be specified as a byte string, and
306 it must have the same number of bytes as the slice itself, as in:
307 ip[42:2] & 40:ff
309 Logical expressions
311 Tests can be combined using logical expressions. These too are
312 expressible in C-like syntax or with English-like abbreviations:
313 and, && Logical AND
315 or, || Logical OR
316 not, ! Logical NOT
317 Expressions can be grouped by parentheses as well. The following are
319 all valid display filter expressions:
320 tcp.port == 80 and ip.src == 192.168.2.1
322 not llc
323 http and frame[100-199] contains "wireshark"
324 (ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip
325 Remember that whenever a protocol or field name occurs in an
327 expression, the "exists" operator is implicitly called. The "exists"
328 operator has the highest priority. This means that the first filter
329 expression must be read as "show me the packets for which tcp.port
330 exists and equals 80, and ip.src exists and equals 192.168.2.1". The
331 second filter expression means "show me the packets where not (llc
332 exists)", or in other words "where llc does not exist" and hence will
333 match all packets that do not contain the llc protocol. The third
334 filter expression includes the constraint that offset 199 in the frame
335 exists, in other words the length of the frame is at least 200.
336 A special caveat must be given regarding fields that occur more than
338 once per packet. "ip.addr" occurs twice per IP packet, once for the
339 source address, and once for the destination address. Likewise,
340 "tr.rif.ring" fields can occur more than once per packet. The
341 following two expressions are not equivalent:
342 ip.addr ne 192.168.4.1
344 not ip.addr eq 192.168.4.1
345 The first filter says "show me packets where an ip.addr exists that
347 does not equal 192.168.4.1". That is, as long as one ip.addr in the
348 packet does not equal 192.168.4.1, the packet passes the display
349 filter. The other ip.addr could equal 192.168.4.1 and the packet would
350 still be displayed. The second filter says "don't show me any packets
351 that have an ip.addr field equal to 192.168.4.1". If one ip.addr is
352 192.168.4.1, the packet does not pass. If neither ip.addr field is
353 192.168.4.1, then the packet is displayed.
354 It is easy to think of the 'ne' and 'eq' operators as having an
356 implicit "exists" modifier when dealing with multiply-recurring fields.
357 "ip.addr ne 192.168.4.1" can be thought of as "there exists an ip.addr
358 that does not equal 192.168.4.1". "not ip.addr eq 192.168.4.1" can be
359 thought of as "there does not exist an ip.addr equal to 192.168.4.1".
360 Be careful with multiply-recurring fields; they can be confusing.
362 Care must also be taken when using the display filter to remove noise
364 from the packet trace. If, for example, you want to filter out all IP
365 multicast packets to address 224.1.2.3, then using:
366 ip.dst ne 224.1.2.3
368 may be too restrictive. Filtering with "ip.dst" selects only those IP
370 packets that satisfy the rule. Any other packets, including all non-IP
371 packets, will not be displayed. To display the non-IP packets as well,
372 you can use one of the following two expressions:
373 not ip or ip.dst ne 224.1.2.3
375 not ip.addr eq 224.1.2.3
376 The first filter uses "not ip" to include all non-IP packets and then
378 lets "ip.dst ne 224.1.2.3" filter out the unwanted IP packets. The
379 second filter has already been explained above where filtering with
380 multiply occurring fields was discussed.
381
383 The entire list of display filters is too large to list here. You can
384 can find references and examples at the following locations:
385 · The online Display Filter Reference:
387 <http://www.wireshark.org/docs/dfref/>
388 · Help:Supported Protocols in Wireshark
390 · "tshark -G fields" on the command line
392 · The Wireshark wiki: <http://wiki.wireshark.org/DisplayFilters>
394
396 The wireshark-filters manpage is part of the Wireshark distribution.
397 The latest version of Wireshark can be found at
398 <http://www.wireshark.org>.
399 Regular expressions in the "matches" operator are provided with
401 libpcre, the Perl-Compatible Regular Expressions library: see
402 http://www.pcre.org/.
403 This manpage does not describe the capture filter syntax, which is
405 different. See the manual page of pcap-filter(7) or, if that doesn't
406 exist, tcpdump(8), or, if that doesn't exist,
407 <http://wiki.wireshark.org/CaptureFilters> for a description of capture
408 filters.
409
411 wireshark(1), tshark(1), editcap(1), pcap(3), pcap-filter(7) or
412 tcpdump(8) if it doesn't exist.
413
415 See the list of authors in the Wireshark man page for a list of authors
416 of that code.
4171.8.10 2013-07-23 WIRESHARK-FILTER(4)