ethereal-filter - Ethereal filter syntax and reference
ethereal [other options] [ -R ``filter expression'' ]
tethereal [other options] [ -R ``filter expression'' ]
Ethereal and Tethereal share a powerful filter engine that helps remove the noise from a packet trace and lets you see only the packets that interest you. If a packet meets the requirements expressed in your filter, then it is displayed in the list of packets. Display filters let you compare the fields within a protocol against a specific value, compare fields against fields, and check the existence of specified fields or protocols.
Filters are also used by other features such as statistics generation and packet list colorization (the latter is only available to Ethereal). This manual page describes their syntax and provides a comprehensive reference of filter fields.
The simplest filter allows you to check for the existence of a protocol or field. If you want to see all packets which contain the IPX protocol, the filter would be ``ipx'' (without the quotation marks). To see all packets that contain a Token-Ring RIF field, use ``tr.rif''.
Think of a protocol or field in a filter as implicitly having the ``exists'' operator.
Note: all protocol and field names that are available in Ethereal and Tethereal filters are listed in the FILTER PROTOCOL REFERENCE (see below).
Fields can also be compared against values. The comparison operators can be expressed either through C-like symbols or through English-like abbreviations:
eq, == Equal
ne, != Not Equal
gt, > Greater Than
lt, < Less Than
ge, >= Greater than or Equal to
le, <= Less than or Equal to
Additional operators exist expressed only in English, not punctuation:
contains Does the protocol, field or slice contain a value
matches Does the text string match the given Perl regular expression
The ``contains'' operator allows a filter to search for a sequence of characters or bytes. For example, to search for a given HTTP URL in a capture, the following filter can be used:
http contains "http://www.ethereal.com";
The ``contains'' operator cannot be used on atomic fields, such as numbers or IP addresses.
The ``matches'' operator allows a filter to apply to a specified Perl-compatible regular expression (PCRE). The ``matches'' operator is only implemented for protocols and for protocol fields with a text string representation. For example, to search for a given WAP WSP User-Agent, you can write:
wsp.user_agent matches "(?i)cldc"
This example shows an interesting PCRE feature: pattern match options have to
be specified with the (?option) construct. For instance, (?i) performs
a case-insensitive pattern match. More information on PCRE can be found in the
pcrepattern(3) man page (Perl Regular Expressions are explained in
http://www.perldoc.com/perl5.8.0/pod/perlre.html).
Note: the ``matches'' operator is only available if Ethereal or Tethereal have been compiled with the PCRE library. This can be checked by running:
ethereal -v
tethereal -v
or selecting the ``About Ethereal'' item from the ``Help'' menu in Ethereal.
Each protocol field is typed. The types are:
Unsigned integer (8-bit, 16-bit, 24-bit, or 32-bit)
Signed integer (8-bit, 16-bit, 24-bit, or 32-bit)
Boolean
Ethernet address (6 bytes)
Byte array
IPv4 address
IPv6 address
IPX network number
Text string
Double-precision floating point number
An integer may be expressed in decimal, octal, or hexadecimal notation. The following three display filters are equivalent:
frame.pkt_len > 10
frame.pkt_len > 012
frame.pkt_len > 0xa
Boolean values are either true or false. In a display filter expression testing the value of a Boolean field, ``true'' is expressed as 1 or any other non-zero value, and ``false'' is expressed as zero. For example, a token-ring packet's source route field is Boolean. To find any source-routed packets, a display filter would be:
tr.sr == 1
Non source-routed packets can be found with:
tr.sr == 0
Ethernet addresses and byte arrays are represented by hex digits. The hex digits may be separated by colons, periods, or hyphens:
eth.dst eq ff:ff:ff:ff:ff:ff
aim.data == 0.1.0.d
fddi.src == aa-aa-aa-aa-aa-aa
echo.data == 7a
IPv4 addresses can be represented in either dotted decimal notation or by using the hostname:
ip.dst eq www.mit.edu
ip.src == 192.168.1.1
IPv4 addresses can be compared with the same logical relations as numbers: eq, ne, gt, ge, lt, and le. The IPv4 address is stored in host order, so you do not have to worry about the endianness of an IPv4 address when using it in a display filter.
Classless InterDomain Routing (CIDR) notation can be used to test if an IPv4 address is in a certain subnet. For example, this display filter will find all packets in the 129.111 Class-B network:
ip.addr == 129.111.0.0/16
Remember, the number after the slash represents the number of bits used to represent the network. CIDR notation can also be used with hostnames, as in this example of finding IP addresses on the same Class C network as 'sneezy':
ip.addr eq sneezy/24
The CIDR notation can only be used on IP addresses or hostnames, not in variable names. So, a display filter like ``ip.src/24 == ip.dst/24'' is not valid (yet).
IPX networks are represented by unsigned 32-bit integers. Most likely you will be using hexadecimal when testing IPX network values:
ipx.src.net == 0xc0a82c00
Strings are enclosed in double quotes:
http.request.method == "POST"
Inside double quotes, you may use a backslash to embed a double quote or an arbitrary byte represented in either octal or hexadecimal.
browser.comment == "An embedded \" double-quote"
Use of hexadecimal to look for ``HEAD'':
http.request.method == "\x48EAD"
Use of octal to look for ``HEAD'':
http.request.method == "\110EAD"
This means that you must escape backslashes with backslashes inside double quotes.
smb.path contains "\\\\SERVER\\SHARE"
looks for \\SERVER\SHARE in ``smb.path''.
You can take a slice of a field if the field is a text string or a byte array. For example, you can filter on the vendor portion of an ethernet address (the first three bytes) like this:
eth.src[0:3] == 00:00:83
Another example is:
http.content_type[0:4] == "text"
You can use the slice operator on a protocol name, too. The ``frame'' protocol can be useful, encompassing all the data captured by Ethereal or Tethereal.
token[0:5] ne 0.0.0.1.1
llc[0] eq aa
frame[100-199] contains "ethereal"
The following syntax governs slices:
[i:j] i = start_offset, j = length
[i-j] i = start_offset, j = end_offset, inclusive.
[i] i = start_offset, length = 1
[:j] start_offset = 0, length = j
[i:] start_offset = i, end_offset = end_of_field
Offsets can be negative, in which case they indicate the offset from the end of the field. The last byte of the field is at offset -1, the last but one byte is at offset -2, and so on. Here's how to check the last four bytes of a frame:
frame[-4:4] == 0.1.2.3
or
frame[-4:] == 0.1.2.3
You can concatenate slices using the comma operator:
ftp[1,3-5,9:] == 01:03:04:05:09:0a:0b
This concatenates offset 1, offsets 3-5, and offset 9 to the end of the ftp data.
If a field is a text string or a byte array, it can be expressed in whichever way is most convenient.
So, for instance, the following filters are equivalent:
http.request.method == "GET"
http.request.method == 47.45.54
A range can also be expressed in either way:
frame[60:2] gt 50.51
frame[60:2] gt "PQ"
It is also possible to define tests with bit field operations. Currently the following bit field operation is supported:
bitwise_and, & Bitwise AND
The bitwise AND operation allows testing to see if one or more bits are set. Bitwise AND operates on integer protocol fields and slices.
When testing for TCP SYN packets, you can write:
tcp.flags & 0x02
Similarly, filtering for all WSP GET and extended GET methods is achieved with:
wsp.pdu_type & 0x40
When using slices, the bit mask must be specified as a byte string, and it must have the same number of bytes as the slice itself, as in:
ip[42:2] & 40:ff
Tests can be combined using logical expressions. These too are expressable in C-like syntax or with English-like abbreviations:
and, && Logical AND
or, || Logical OR
not, ! Logical NOT
Expressions can be grouped by parentheses as well. The following are all valid display filter expressions:
tcp.port == 80 and ip.src == 192.168.2.1
not llc
http and frame[100-199] contains "ethereal"
(ipx.src.net == 0xbad && ipx.src.node == 0.0.0.0.0.1) || ip
Remember that whenever a protocol or field name occurs in an expression, the ``exists'' operator is implicitly called. The ``exists'' operator has the highest priority. This means that the first filter expression must be read as ``show me the packets for which tcp.port exists and equals 80, and ip.src exists and equals 192.168.2.1''. The second filter expression means ``show me the packets where not (llc exists)'', or in other words ``where llc does not exist'' and hence will match all packets that do not contain the llc protocol. The third filter expression includes the constraint that offset 199 in the frame exists, in other words the length of the frame is at least 200.
A special caveat must be given regarding fields that occur more than once per packet. ``ip.addr'' occurs twice per IP packet, once for the source address, and once for the destination address. Likewise, ``tr.rif.ring'' fields can occur more than once per packet. The following two expressions are not equivalent:
ip.addr ne 192.168.4.1
not ip.addr eq 192.168.4.1
The first filter says ``show me packets where an ip.addr exists that does not equal 192.168.4.1''. That is, as long as one ip.addr in the packet does not equal 192.168.4.1, the packet passes the display filter. The other ip.addr could equal 192.168.4.1 and the packet would still be displayed. The second filter says ``don't show me any packets that have an ip.addr field equal to 192.168.4.1''. If one ip.addr is 192.168.4.1, the packet does not pass. If neither ip.addr field is 192.168.4.1, then the packet is displayed.
It is easy to think of the 'ne' and 'eq' operators as having an implict ``exists'' modifier when dealing with multiply-recurring fields. ``ip.addr ne 192.168.4.1'' can be thought of as ``there exists an ip.addr that does not equal 192.168.4.1''. ``not ip.addr eq 192.168.4.1'' can be thought of as ``there does not exist an ip.addr equal to 192.168.4.1''.
Be careful with multiply-recurring fields; they can be confusing.
Care must also be taken when using the display filter to remove noise from the packet trace. If, for example, you want to filter out all IP multicast packets to address 224.1.2.3, then using:
ip.dst ne 224.1.2.3
may be too restrictive. Filtering with ``ip.dst'' selects only those IP packets that satisfy the rule. Any other packets, including all non-IP packets, will not be displayed. To display the non-IP packets as well, you can use one of the following two expressions:
not ip or ip.dst ne 224.1.2.3
not ip.addr eq 224.1.2.3
The first filter uses ``not ip'' to include all non-IP packets and then lets ``ip.dst ne 224.1.2.3'' filter out the unwanted IP packets. The second filter has already been explained above where filtering with multiply occuring fields was discussed.
Each entry below provides an abbreviated protocol or field name. Every one of these fields can be used in a display filter. The type of the field is also given.
xnsllc.type Type
Unsigned 16-bit integer
a11.ackstat Reply Status
Unsigned 8-bit integer
A11 Registration Ack Status.
a11.auth.auth Authenticator
Byte array
Authenticator.
a11.auth.spi SPI
Unsigned 32-bit integer
Authentication Header Security Parameter Index.
a11.b Broadcast Datagrams
Boolean
Broadcast Datagrams requested
a11.coa Care of Address
IPv4 address
Care of Address.
a11.code Reply Code
Unsigned 8-bit integer
A11 Registration Reply code.
a11.d Co-lcated Care-of Address
Boolean
MN using Co-located Care-of address
a11.ext.apptype Application Type
Unsigned 8-bit integer
Application Type.
a11.ext.auth.subtype Gen Auth Ext SubType
Unsigned 8-bit integer
Mobile IP Auth Extension Sub Type.
a11.ext.canid CANID
Byte array
CANID
a11.ext.code Reply Code
Unsigned 8-bit integer
PDSN Code.
a11.ext.dormant All Dormant Indicator
Unsigned 16-bit integer
All Dormant Indicator.
a11.ext.key Key
Unsigned 32-bit integer
Session Key.
a11.ext.len Extension Length
Unsigned 16-bit integer
Mobile IP Extension Length.
a11.ext.mnsrid MNSR-ID
Unsigned 16-bit integer
MNSR-ID
a11.ext.msid MSID(BCD)
Byte array
MSID(BCD).
a11.ext.msid_len MSID Length
Unsigned 8-bit integer
MSID Length.
a11.ext.msid_type MSID Type
Unsigned 16-bit integer
MSID Type.
a11.ext.panid PANID
Byte array
PANID
a11.ext.ppaddr Anchor P-P Address
IPv4 address
Anchor P-P Address.
a11.ext.ptype Protocol Type
Unsigned 16-bit integer
Protocol Type.
a11.ext.sidver Session ID Version
Unsigned 8-bit integer
Session ID Version
a11.ext.srvopt Service Option
Unsigned 16-bit integer
Service Option.
a11.ext.type Extension Type
Unsigned 8-bit integer
Mobile IP Extension Type.
a11.ext.vid Vendor ID
Unsigned 32-bit integer
Vendor ID.
a11.extension Extension
Byte array
Extension
a11.flags Flags
Unsigned 8-bit integer
a11.g GRE
Boolean
MN wants GRE encapsulation
a11.haaddr Home Agent
IPv4 address
Home agent IP Address.
a11.homeaddr Home Address
IPv4 address
Mobile Node's home address.
a11.ident Identification
Byte array
MN Identification.
a11.life Lifetime
Unsigned 16-bit integer
A11 Registration Lifetime.
a11.m Minimal Encapsulation
Boolean
MN wants Minimal encapsulation
a11.nai NAI
String
NAI
a11.s Simultaneous Bindings
Boolean
Simultaneous Bindings Allowed
a11.t Reverse Tunneling
Boolean
Reverse tunneling requested
a11.type Message Type
Unsigned 8-bit integer
A11 Message type.
a11.v Van Jacobson
Boolean
Van Jacobson
vlan.cfi CFI
Unsigned 16-bit integer
CFI
vlan.etype Type
Unsigned 16-bit integer
Type
vlan.id ID
Unsigned 16-bit integer
ID
vlan.len Length
Unsigned 16-bit integer
Length
vlan.priority Priority
Unsigned 16-bit integer
Priority
vlan.trailer Trailer
Byte array
VLAN Trailer
eapol.keydes.data WPA Key
Byte array
WPA Key Data
eapol.keydes.datalen WPA Key Length
Unsigned 16-bit integer
WPA Key Data Length
eapol.keydes.id WPA Key ID
Byte array
WPA Key ID(RSN Reserved)
eapol.keydes.index.indexnum Index Number
Unsigned 8-bit integer
Key Index number
eapol.keydes.index.keytype Key Type
Boolean
Key Type (unicast/broadcast)
eapol.keydes.key Key
Byte array
Key
eapol.keydes.key_info Key Information
Unsigned 16-bit integer
WPA key info
eapol.keydes.key_info.encr_key_data Encrypted Key Data flag
Boolean
Encrypted Key Data flag
eapol.keydes.key_info.error Error flag
Boolean
Error flag
eapol.keydes.key_info.install Install flag
Boolean
Install flag
eapol.keydes.key_info.key_ack Key Ack flag
Boolean
Key Ack flag
eapol.keydes.key_info.key_index Key Index
Unsigned 16-bit integer
Key Index (0-3) (RSN: Reserved)
eapol.keydes.key_info.key_mic Key MIC flag
Boolean
Key MIC flag
eapol.keydes.key_info.key_type Key Type
Boolean
Key Type (Pairwise or Group)
eapol.keydes.key_info.keydes_ver Key Descriptor Version
Unsigned 16-bit integer
Key Descriptor Version Type
eapol.keydes.key_info.request Request flag
Boolean
Request flag
eapol.keydes.key_info.secure Secure flag
Boolean
Secure flag
eapol.keydes.key_iv Key IV
Byte array
Key Initialization Vector
eapol.keydes.key_signature Key Signature
Byte array
Key Signature
eapol.keydes.keylen Key Length
Unsigned 16-bit integer
Key Length
eapol.keydes.mic WPA Key MIC
Byte array
WPA Key Message Integrity Check
eapol.keydes.nonce Nonce
Byte array
WPA Key Nonce
eapol.keydes.replay_counter Replay Counter
Unsigned 64-bit integer
Replay Counter
eapol.keydes.rsc WPA Key RSC
Byte array
WPA Key Receive Sequence Counter
eapol.keydes.type Descriptor Type
Unsigned 8-bit integer
Key Descriptor Type
eapol.len Length
Unsigned 16-bit integer
Length
eapol.type Type
Unsigned 8-bit integer
eapol.version Version
Unsigned 8-bit integer
alcap.aal2_path_id AAL2 path identifier
Unsigned 32-bit integer
alcap.channel_id Channel identifier (CID)
Unsigned 32-bit integer
alcap.dsai Destination signalling association identifier
Unsigned 32-bit integer
alcap.len Length
Unsigned 8-bit integer
alcap.msg_type Message Type
Unsigned 8-bit integer
alcap.none Subtree
No value
alcap.nsap_address NSAP address
Byte array
alcap.organizational_unique_id Organizational unique identifier (OUI)
Unsigned 24-bit integer
alcap.osai Originating signalling association identifier
Unsigned 32-bit integer
alcap.param_id Parameter identifier
Unsigned 8-bit integer
alcap.served_user_gen_ref Served user generated reference
Unsigned 32-bit integer
rep_proc.opnum Operation
Unsigned 16-bit integer
Operation
admin.confirm_status Confirmation status
Unsigned 16-bit integer
aim.acctinfo.code Account Information Request Code
Unsigned 16-bit integer
aim.acctinfo.permissions Account Permissions
Unsigned 16-bit integer
aim.client_verification.hash Client Verification MD5 Hash
Byte array
aim.client_verification.length Client Verification Request Length
Unsigned 32-bit integer
aim.client_verification.offset Client Verification Request Offset
Unsigned 32-bit integer
aim.evil.new_warn_level New warning level
Unsigned 16-bit integer
aim.ext_status.data Extended Status Data
Byte array
aim.ext_status.flags Extended Status Flags
Unsigned 8-bit integer
aim.ext_status.length Extended Status Length
Unsigned 8-bit integer
aim.ext_status.type Extended Status Type
Unsigned 16-bit integer
aim.idle_time Idle time (seconds)
Unsigned 32-bit integer
aim.migrate.numfams Number of families to migrate
Unsigned 16-bit integer
aim.privilege_flags Privilege flags
Unsigned 32-bit integer
aim.privilege_flags.allow_idle Allow other users to see idle time
Boolean
aim.privilege_flags.allow_member Allow other users to see how long account has been a member
Boolean
aim.ratechange.msg Rate Change Message
Unsigned 16-bit integer
aim.rateinfo.class.alertlevel Alert Level
Unsigned 32-bit integer
aim.rateinfo.class.clearlevel Clear Level
Unsigned 32-bit integer
aim.rateinfo.class.currentlevel Current Level
Unsigned 32-bit integer
aim.rateinfo.class.curstate Current State
Unsigned 8-bit integer
aim.rateinfo.class.disconnectlevel Disconnect Level
Unsigned 32-bit integer
aim.rateinfo.class.id Class ID
Unsigned 16-bit integer
aim.rateinfo.class.lasttime Last Time
Unsigned 32-bit integer
aim.rateinfo.class.limitlevel Limit Level
Unsigned 32-bit integer
aim.rateinfo.class.maxlevel Max Level
Unsigned 32-bit integer
aim.rateinfo.class.numpairs Number of Family/Subtype pairs
Unsigned 16-bit integer
aim.rateinfo.class.window_size Window Size
Unsigned 32-bit integer
aim.rateinfo.numclasses Number of Rateinfo Classes
Unsigned 16-bit integer
aim.rateinfoack.class Acknowledged Rate Class
Unsigned 16-bit integer
aim.selfinfo.warn_level Warning level
Unsigned 16-bit integer
generic.motd.motdtype MOTD Type
Unsigned 16-bit integer
generic.servicereq.service Requested Service
Unsigned 16-bit integer
aim_icq.chunk_size Data chunk size
Unsigned 16-bit integer
aim_icq.offline_msgs.dropped_flag Dropped messages flag
Unsigned 8-bit integer
aim_icq.owner_uid Owner UID
Unsigned 32-bit integer
aim_icq.request_seq_number Request Sequence Number
Unsigned 16-bit integer
aim_icq.request_type Request Type
Unsigned 16-bit integer
aim_icq.subtype Meta Request Subtype
Unsigned 16-bit integer
aim.snac.location.request_user_info.infotype Infotype
Unsigned 16-bit integer
aim.evil.warn_level Old warning level
Unsigned 16-bit integer
aim.evilreq.origin Send Evil Bit As
Unsigned 16-bit integer
aim.icbm.channel Channel to setup
Unsigned 16-bit integer
aim.icbm.flags Message Flags
Unsigned 32-bit integer
aim.icbm.max_receiver_warnlevel max receiver warn level
Unsigned 16-bit integer
aim.icbm.max_sender_warn-level Max sender warn level
Unsigned 16-bit integer
aim.icbm.max_snac Max SNAC Size
Unsigned 16-bit integer
aim.icbm.min_msg_interval Minimum message interval (seconds)
Unsigned 16-bit integer
aim.icbm.unknown Unknown parameter
Unsigned 16-bit integer
aim.messaging.channelid Message Channel ID
Unsigned 16-bit integer
aim.messaging.icbmcookie ICBM Cookie
Byte array
aim.notification.channel Notification Channel
Unsigned 16-bit integer
aim.notification.cookie Notification Cookie
Byte array
aim.notification.type Notification Type
Unsigned 16-bit integer
aim.rendezvous.msg_type Message Type
Unsigned 16-bit integer
aim.bos.userclass User class
Unsigned 32-bit integer
aim.fnac.ssi.bid SSI Buddy ID
Unsigned 16-bit integer
aim.fnac.ssi.buddyname Buddy Name
String
aim.fnac.ssi.buddyname_len SSI Buddy Name length
Unsigned 16-bit integer
aim.fnac.ssi.data SSI Buddy Data
Unsigned 16-bit integer
aim.fnac.ssi.gid SSI Buddy Group ID
Unsigned 16-bit integer
aim.fnac.ssi.last_change_time SSI Last Change Time
Unsigned 32-bit integer
aim.fnac.ssi.numitems SSI Object count
Unsigned 16-bit integer
aim.fnac.ssi.tlvlen SSI TLV Len
Unsigned 16-bit integer
aim.fnac.ssi.type SSI Buddy type
Unsigned 16-bit integer
aim.fnac.ssi.version SSI Version
Unsigned 8-bit integer
aim.sst.icon Icon
Byte array
aim.sst.icon_size Icon Size
Unsigned 16-bit integer
aim.sst.md5 MD5 Hash
Byte array
aim.sst.md5.size MD5 Hash Size
Unsigned 8-bit integer
aim.sst.ref_num Reference Number
Unsigned 16-bit integer
aim.sst.unknown Unknown Data
Byte array
aim.userlookup.email Email address looked for
String
Email address
ansi_a.bsmap_msgtype BSMAP Message Type
Unsigned 8-bit integer
ansi_a.cell_ci Cell CI
Unsigned 16-bit integer
ansi_a.cell_lac Cell LAC
Unsigned 16-bit integer
ansi_a.cell_mscid Cell MSCID
Unsigned 24-bit integer
ansi_a.cld_party_ascii_num Called Party ASCII Number
String
ansi_a.cld_party_bcd_num Called Party BCD Number
String
ansi_a.clg_party_ascii_num Calling Party ASCII Number
String
ansi_a.clg_party_bcd_num Calling Party BCD Number
String
ansi_a.dtap_msgtype DTAP Message Type
Unsigned 8-bit integer
ansi_a.elem_id Element ID
Unsigned 8-bit integer
ansi_a.esn ESN
Unsigned 32-bit integer
ansi_a.imsi IMSI
String
ansi_a.len Length
Unsigned 8-bit integer
ansi_a.min MIN
String
ansi_a.none Sub tree
No value
ansi_a.pdsn_ip_addr PDSN IP Address
IPv4 address
IP Address