pcap-filter(7) Miscellaneous Information Manual pcap-filter(7)
NAME
pcap-filter - packet filter syntax
DESCRIPTION
pcap_compile(3) is used to compile a string into a filter program.
The resulting filter program can then be applied to some stream of
packets to determine which packets will be supplied to
pcap_loop(3), pcap_dispatch(3), pcap_next(3), or
pcap_next_ex(3).
The filter expression consists of one or more primitives. Primitives
usually consist of an id (a name, a number or something slightly more
complex, such as a CIDR prefix) preceded by one or more qualifiers.
There are three different kinds of qualifier:
proto proto qualifiers restrict the match to a particular protocol.
(This should not be confused with the proto type qualifier
below.) Possible protocols are: ether, link, wlan, ip, ip6,
arp, tcp, udp, sctp, iso, isis, rarp, decnet, fddi, tr, ppp and
slip. E.g., `ether src foo', `arp net 128.3', `tcp port 21',
`ip proto ospf', `ether proto 0x88CC', `udp portrange
7000-7009', `wlan addr2 0:2:3:4:5:6'. If there is no proto
qualifier, all protocols consistent with the type are assumed.
E.g., `src foo' means `(ip6 or ip or arp or rarp) src foo',
`proto tcp' means `(ip6 or ip) proto tcp' `net bar' means `(ip6
or ip or arp or rarp) net bar' and `port 53' means `(tcp or udp
or sctp) port 53' (note that these examples use invalid syntax
to illustrate the principle).
dir dir qualifiers specify a particular transfer direction to and/or
from id. Possible directions are src, dst, src or dst, src and
dst, ra, ta, addr1, addr2, addr3, and addr4. E.g., `src foo',
`dst net 128.3', `src or dst port ftp-data'. If there is no dir
qualifier, `src or dst' is assumed. The ra, ta, addr1, addr2,
addr3, and addr4 qualifiers are only valid for IEEE 802.11
Wireless LAN link layers.
type type qualifiers say what kind of thing the id name or number
refers to. Possible types are host, net, proto, port,
portrange, protochain and gateway. E.g., `host foo', `net
128.3', `port 20', `portrange 6000-6008', `proto 17'. If there
is no type qualifier, host is assumed.
In primitives that follow this pattern each qualifier kind may be
present at most once, and if more than one kind is present, any proto
qualifier must be the first qualifier and any type qualifier must be
the last qualifier, for example, `tcp dst port 80'. Also not all
combinations of these qualifier kinds are valid syntax. Some make no
sense in network protocols space, for example: ether port (Ethernet
header has no ports), tcp net (TCP header does not have layer 3
fields), dst proto (in a protocol header the same protocol applies to
both the source and the destination), and so on. Some other
combinations are not valid syntax because they are not implemented,
even though hypothetically could make sense, for example: iso net, aarp
host and so on.
[fddi is actually an alias for ether; the parser treats them
identically as meaning ``the data link level used on the specified
network interface''. FDDI headers contain Ethernet-like source and
destination addresses, and often contain Ethernet-like packet types, so
you can filter on these FDDI fields just as with the analogous Ethernet
fields. FDDI headers also contain other fields, but you cannot name
them explicitly in a filter expression. Similarly, tr and wlan are
aliases for ether; the statements about FDDI headers also apply to
Token Ring and 802.11 wireless LAN headers. The same stands for the
link, ppp and slip keywords.]
For IEEE 802.11 headers, the destination address is the DA field and
the source address is the SA field. For both ARP and RARP headers, the
destination address is the TPA (Target Protocol Address) field and the
source address is the SPA (Sender Protocol Address) field.
In addition to the above, there are some special `primitive' keywords
that don't follow the pattern (for example: broadcast, multicast,
inbound, outbound, ifindex, llc, vlan, mpls, less, greater), packet
data accessors and relations of two arithmetic expressions. All of
these are described below.
More complex filter expressions are built up by using the words and, or
and not (or equivalently: `&&', `||' and `!' respectively) to combine
primitives. E.g., `host foo and not port ftp and not port ftp-data'.
To save typing, identical qualifier lists can be omitted. E.g., `tcp
dst port ftp or ftp-data or domain' is exactly the same as `tcp dst
port ftp or tcp dst port ftp-data or tcp dst port domain'.
PRIMITIVES
host hostnameaddr
True if the source or the destination ARP/IPv4/IPv6/RARP address
of the packet is hostnameaddr. May be qualified with a specific
protocol (arp, ip, ip6, rarp) and/or a different direction (src,
dst, src and dst), in the latter case the host keyword is
optional. For example,
ip src hostnameaddr
for Ethernet-like link-layer types is equivalent to
ether proto \ip and ip src host hostnameaddr
hostnameaddr may be either an IPv4 host number or an IPv6 host
number or a name.
An IPv4 host number can be written as a dotted quad (e.g.,
192.168.10.20), dotted triple (e.g., 192.168.10 means the same
as 192.168.10.0/24, so it is really a network match), dotted
pair (e.g., 192.168 means 192.168.0.0/16, so it is really a
network match as well), or single number (e.g., [decimal]
168496141, [octal] 01202606015 and [hexadecimal] 0x0a0b0c0d all
mean 10.11.12.13).
An IPv6 host number can be written as a complete 128-bit address
(x:x:x:x:x:x:x:x) or using the zero compression (x::x) or the
IPv4-mapped (x:x:x:x:x:x:d.d.d.d) notations as discussed in
inet_pton(3). In this primitive this version of libpcap
tolerates an optional "/128" after an IPv6 host number, this
behaviour is an implementation quirk and it may be removed in
future.
A host name must resolve using getaddrinfo(3), which typically
means DNS or hosts(5), to at least one IPv4 address for `arp
host', `ip host' and `rarp host', at least one IPv6 address for
`ip6 host', and at least one IPv4/IPv6 address for `host'. If
the name resolves to more than one address, this primitive
evaluates to true as soon as one of the addresses matches the
packet.
When not qualified with a protocol, this primitive implies all
protocols that make sense for the address families of the
specified/resolved addresses. When qualified with a protocol,
this primitive ignores the address family that does not make
sense for the protocol. For example, for a name that resolves
only to an IPv6 address `arp host' returns an error, but `host'
is valid and means IPv6, for a name that resolves only to an
IPv4 address `ip6 host' returns an error, but `host' is valid
and means ARP/IPv4/RARP, for a name that resolves to both IPv4
and IPv6 addresses `ip host' ignores the IPv6 addresses and `ip6
host' ignores the IPv4 addresses, and so on.
ether host ethernameaddr
True if the source or the destination Ethernet/802.11/IPFC/ATM
LANE/FDDI/Token Ring address of the packet is ethernameaddr.
May be qualified with a different direction (src, dst, src and
dst), in which case the host keyword is optional.
ethernameaddr may be either a name from ethers(5) or a numerical
MAC-48 address. In the latter case a valid format is one of
"xx:xx:xx:xx:xx:xx", "xx.xx.xx.xx.xx.xx" or "xx-xx-xx-xx-xx-xx",
where every "xx" is a hexadecimal digit (0-9, a-f, or A-F) or a
two-digit hexadecimal number -- for example, "aa:00:04:00:1d:04"
means the same as "AA-0-4-0-1D-4". Another valid format is one
of "xxxx.xxxx.xxxx" or "xxxxxxxxxxxx", where each "x" is a
hexadecimal digit -- for example, "aa0004001d04".
gateway host
True if the packet used host as a gateway. I.e., the source or
the destination Ethernet-like address is host but neither the
source nor the destination ARP/IPv4/RARP address is host. This
primitive is valid only for the same link-layer types as the
ether host primitive above, also it cannot be applied to packets
encapsulated in MPLS, VXLAN or Geneve. May be qualified with a
specific protocol (arp, ip, rarp). For example,
ip gateway host
is equivalent to
ether host ethernameaddr and ip and not ip host hostnameaddr
which can be used with either names or numbers for hostnameaddr
and ethernameaddr.
Host must be a name and must be found both by the machine's
host-name-to-IP-address resolution mechanisms (host name file,
DNS, NIS, etc.) and by the machine's host-name-to-Ethernet-
address resolution mechanism (/etc/ethers, etc.).
net netnameaddr
True if the source or the destination ARP/IPv4/IPv6/RARP address
of the packet belongs to the specified network. May be
qualified with a specific protocol (arp, ip, ip6, rarp) and/or a
different direction (src, dst, src and dst), in the latter case
the net keyword remains mandatory. netnameaddr may be either an
IPv4 network number or an IPv6 network number or an IPv4 network
name.
An IPv4 network number can be written as a dotted quad (e.g.,
192.168.1.0), dotted triple (e.g., 192.168.1), dotted pair (e.g,
172.16), or single number (e.g., 10); the netmask is
255.255.255.255 (/32) for a dotted quad (which means that it's
really a host match), 255.255.255.0 (/24) for a dotted triple,
255.255.0.0 (/16) for a dotted pair, or 255.0.0.0 (/8) for a
single number.
An IPv6 network number is an IPv6 address as discussed for the
host primitive above; the implicit netmask is
ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff (/128), so in this
primitive IPv6 "network" matches are really always host matches.
For an actual IPv6 network match see the `net netaddr/len'
primitive below.
An IPv4 network name is a name from the networks database
(traditionally networks(5), in OpenBSD hosts(5), also possibly
NIS, LDAP, etc.). Some operating systems do not implement a
networks database, in those that do the implemented behaviour
varies. For example, POSIX does not specify a format of
networks(5), so the line somenet 192.168 therein can translate
to either 192.168.0.0/32 or 192.168.0.0/16 depending on the
implementation. In this sense, the only reliable address
notation to be used with an IPv4 network name would be a dotted
quad (/32), in which case it would be simpler just to use a host
match with a hostname, as well as DNS. For these reasons IPv4
network names should not be used in portable applications and
this form of ID may be removed from this primitive in future.
net netaddr mask netmask
True if the source or the destination ARP/IPv4/RARP address of
the packet belongs to netaddr with the specified netmask. May
be qualified with a specific protocol (arp, ip, rarp) and/or a
different direction (src, dst, src and dst), in the latter case
the net keyword remains mandatory. In this implementation this
primitive does not support IPv6 networks.
Both netaddr and netmask use the IPv4 network number notation
described above, except the "single number" form is not valid in
this primitive. For example,
net 192.168 mask 255.255
is equivalent to
net 192.168.0.0 mask 255.255.0.0
The netmask can represent any 32-bit value, which is why the
`net netaddr/len' primitive below is usually a better fit for
use cases that require the value to be strictly one of the 33
CIDR masks (from /0 to /32).
net netaddr/len
True if the source or the destination ARP/IPv4/IPv6/RARP address
of the packet belongs to netaddr where the bit-length of the
network mask equals len (in other words, the address belongs to
the specified CIDR prefix). May be qualified with a specific
protocol (arp, ip, ip6, rarp) and/or a different direction (src,
dst, src and dst), in the latter case the net keyword is
optional.
For IPv4, len is an integer between 0 and 32 (both inclusive)
and netaddr is the same as the above. For IPv6, len is an
integer between 0 and 128 (both inclusive) and netaddr is an
IPv6 address as discussed for the host primitive above. For
both IPv4 and IPv6 the maximum value of len is equivalent to a
host match and the 0 value (which implies an all-zeroes value of
netaddr) matches any address. In the latter case this primitive
reduces to matching the specified (or implied) protocols only.
port portnamenum
True if the source or the destination TCP/UDP/SCTP port of an
IPv4/IPv6 packet is portnamenum. For IPv4 this also implies
that the packet is the first fragment or is not fragmented; for
IPv6 this also implies that the packet does not use any
extension (e.g. Routing, Fragment, Destination Options) headers.
May be qualified with a specific layer 4 protocol (tcp, udp,
sctp) or a different direction (src, dst, src and dst), in the
latter case the port keyword remains mandatory. Cannot be
qualified with a specific layer 3 protocol (IPv4/IPv6) in the
same primitive, but can be trivially combined with other
primitives to achieve the required effect, for example:
ip and tcp dst port 80
The portnamenum can be a number or a name used in /etc/services
(see services(5)). If a name is used, both the port number and
protocol are checked. If a number or ambiguous name is used,
only the port number is checked (e.g., `dst port 513' will print
both tcp/login traffic and udp/who traffic, and `port domain'
will print both tcp/domain and udp/domain traffic).
portrange portnamenum1-portnamenum2
This is a more generic form of the above: true if the port
number in the packet is between portnamenum1 and portnamenum2
(both inclusive), everything else holds the same meaning. In
this predicate portnamenum1 and portnamenum2 can be specified in
either order. If the two values are equal, this primitive has
the same effect as the port primitive above.
less length
True if the packet has a length less than or equal to length.
This is equivalent to:
len <= length
greater length
True if the packet has a length greater than or equal to length.
This is equivalent to:
len >= length
ip proto protocol
True if the packet is an IPv4 packet of protocol type protocol.
For this primitive it does not matter whether the IPv4 packet is
fragmented or not. Protocol can be a number or one of the names
recognized by getprotobyname(3), for example: ah, esp, eigrp
(only in Linux with glibc, FreeBSD, NetBSD, DragonFly BSD,
MidnightBSD, macOS, and QNX), icmp, igmp, igrp (only in Haiku
and OpenBSD), pim, sctp, tcp, udp or vrrp. Note that most of
these example identifiers are also keywords and must be escaped
via backslash (\). Note that this primitive does not chase the
protocol header chain.
Typically getprotobyname(3) parses the /etc/protocols file to
translate protocol names to numbers, and the getent protocols
command lists the protocols recognized by the function. This is
not entirely so in AIX (which does not have the command), Haiku
(which has the file at /system/data/network/protocols and does
not have the command), on Linux with musl libc (which hard-codes
the list of protocols) and on hosts that use a network database
to resolve protocol names to numbers (see nsswitch.conf(5)). If
a protocol name fails to translate to a number, this version of
libpcap will treat the filter expression as invalid.
carp, vrrp
Abbreviations for:
ip proto 112
icmp Abbreviation for:
ip proto 1
igmp Abbreviation for:
ip proto 2
igrp Abbreviation for:
ip proto igrpval
where igrpval is 88 on DragonFly BSD, FreeBSD, macOS,
MidnightBSD, and QNX, and 9 on all other OSes. This
abbreviation should not be used in portable applications and may
be removed in future.
ip6 proto protocol
True if the packet is an IPv6 packet of protocol type protocol.
Besides IPv6 packets that have protocol in the Next Header field
of the basic header, this also matches IPv6 packets that have 44
in the Next Header field of the basic header and protocol in the
Next Header field of the immediately following Fragment
extension header. (See `ip proto' above for the meaning of
protocol.) Note that the IPv6 variant of ICMP uses a different
protocol number, named ipv6-icmp. Note that this primitive does
not chase the protocol header chain.
icmp6 Abbreviation for:
ip6 proto 58
proto protocol
True if the packet is an IPv4 or IPv6 packet of protocol type
protocol. (See `ip proto' above for the meaning of protocol.)
Note that this primitive does not chase the protocol header
chain.
ah, esp, pim, sctp, tcp, udp
Abbreviations for:
proto \protocol
where protocol is one of the above protocols.
ip6 protochain protocol
True if the packet is IPv6 packet, and contains protocol header
with type protocol in its protocol header chain. (See `ip
proto' above for the meaning of protocol.) For example,
ip6 protochain 6
matches any IPv6 packet with TCP protocol header in the protocol
header chain. The packet may contain, for example,
authentication header, routing header, or hop-by-hop option
header, between IPv6 header and TCP header. The BPF code
emitted by this primitive is complex and cannot be optimized by
the BPF optimizer code, and is not supported by filter engines
in the kernel, so this can be somewhat slow, and may cause more
packets to be dropped.
ip protochain protocol
Equivalent to ip6 protochain protocol, but this is for IPv4.
(See `ip proto' above for the meaning of protocol.)
protochain protocol
True if the packet is an IPv4 or IPv6 packet of protocol type
protocol. (See `ip proto' above for the meaning of protocol.)
Note that this primitive chases the protocol header chain.
ether broadcast
True if the destination Ethernet/802.11/IPFC/ARCnet/ATM
LANE/FDDI/Token Ring address of the packet is the broadcast
address (e.g. FF:FF:FF:FF:FF:FF for Ethernet). The ether
keyword is optional.
ip broadcast
True if the packet is an IPv4 packet with the host part of the
destination address being either all-ones or all-zeroes. This
primitive requires to specify the netmask, which cannot be done
in the filter expression; the only way to specify a netmask is
via the netmask argument of the pcap_compile() function. If a
netmask has not been specified, an attempt to compile a filter
expression with this primitive will return an error.
Note that this primitive ignores the network part of the
destination address, thus it can match more packets than
expected, especially if the interface has multiple IPv4
addresses with different netmasks. For example, if the
interface has addresses 10.1.2.100/29 and 192.168.202.200/24
configured and the netmask argument corresponds to the first
address, its value will be 0xFFFFFFF8 and the host mask value
will be 0x00000007. This will match the expected two addresses
in the first prefix (10.1.2.96 and 10.1.2.103), as well as 64
addresses in the second prefix (192.168.202.0, 192.168.202.7,
192.168.202.8, 192.168.202.15, 192.168.202.16 and so on), as
well as any other IPv4 address with the lowest 3 bits being all-
ones or all-zeroes (for example: 10.73.74.151, 192.168.50.63,
172.19.0.128) -- in other words, 25% of the complete IPv4
address space. This is why in use cases that require more
precision it would be better to match the required address(es)
explicitly, for example:
ip dst host 10.1.2.96 or 10.1.2.103
ether multicast
True if the destination Ethernet/802.11/IPFC/ARCnet/ATM
LANE/FDDI/Token Ring address of the packet is a multicast
address (e.g. ether[0] & 1 != 0 for Ethernet). The ether
keyword is optional.
ip multicast
True if the packet is an IPv4 multicast packet.
ip6 multicast
True if the packet is an IPv6 multicast packet.
ether proto protocol
True if the packet is of ether type protocol. Protocol can be a
number or one of the names:
aarp AppleTalk ARP Protocol
arp ARP
atalk AppleTalk
decnet DECNet
ip IPv4
ip6 IPv6
ipx Novell IPX
iso OSI protocols
lat DEC Local Area Transport (LAT)
lldp Link-Layer Discovery Protocol
loopback
Loopback frames (DIX Ethernet Configuration Test
Protocol)
mopdl DEC DNA Dump/Load (MOP),
moprc DEC DNA Remote Console (MOP)
netbeui
NetBIOS Frame Protocol
rarp Reverse ARP
sca DEC System Communication Architecture (SCA)
slow IEEE Slow Protocols, such as LACP, OAM and OSSP
stp IEEE Spanning Tree Protocol
Note these identifiers (except lldp, loopback and slow) are also
keywords and must be escaped via backslash (\).
[In the case of FDDI (e.g., `fddi proto \arp'), Token Ring
(e.g., `tr proto \arp'), and IEEE 802.11 wireless LANs (e.g.,
`wlan proto \arp'), for most of those protocols, the protocol
identification comes from the 802.2 Logical Link Control (LLC)
header, which is usually layered on top of the FDDI, Token Ring,
or 802.11 header.
When filtering for most protocol identifiers on FDDI, Token
Ring, or 802.11, the filter checks only the protocol ID field of
an LLC header in so-called SNAP format with an Organizational
Unit Identifier (OUI) of 0x000000, for encapsulated Ethernet; it
doesn't check whether the packet is in SNAP format with an OUI
of 0x000000. The exceptions are:
iso the filter checks the DSAP (Destination Service Access
Point) and SSAP (Source Service Access Point) fields of
the LLC header;
stp and netbeui
the filter checks the DSAP of the LLC header;
atalk the filter checks for a SNAP-format packet with an OUI of
0x080007 and the AppleTalk EtherType.
In the case of Ethernet, the filter checks the EtherType field
for most of those protocols. The exceptions are:
iso, stp, and netbeui
the filter checks for an 802.3 frame and then checks the
LLC header as it does for FDDI, Token Ring, and 802.11;
atalk the filter checks both for the AppleTalk EtherType in an
Ethernet frame and for a SNAP-format packet as it does
for FDDI, Token Ring, and 802.11;
aarp the filter checks for the AppleTalk ARP EtherType in
either an Ethernet frame or an 802.2 SNAP frame with an
OUI of 0x000000;
ipx the filter checks for the IPX EtherType in an Ethernet
frame, the IPX DSAP in the LLC header, the 802.3-with-no-
LLC-header encapsulation of IPX, and the IPX EtherType in
a SNAP frame.
ip, ip6, arp, rarp, atalk, aarp, decnet, iso, stp, ipx, netbeui
Abbreviations for:
ether proto \protocol
where protocol is one of the above protocols.
lat, mopdl, moprc, sca
Abbreviations for:
ether proto \protocol
where protocol is one of the above protocols, all of which
originated at DEC, but are not the same as DECnet.
decnet host decnetaddr
True if the source or the destination DECnet address of the
packet is decnetaddr. May be qualified with a different
direction (src, dst, src and dst), in which case the host
keyword is optional.
decnetaddr is an address of the form AREANUMBER.NODENUMBER,
where the area number can be between 0 and 63 (both inclusive)
and the node number can be between 0 and 1023 (both inclusive)
and both numbers always use decimal base. For example:
decnet src 10.123
llc True if the packet has an 802.2 LLC header. This includes:
Ethernet packets with a length field rather than a type field
that aren't raw NetWare-over-802.3 packets;
IEEE 802.11 data packets;
Token Ring packets (no check is done for LLC frames);
FDDI packets (no check is done for LLC frames);
LLC-encapsulated ATM packets, for SunATM on Solaris.
llc type
True if the packet has an 802.2 LLC header and has the specified
type. type can be one of:
i Information (I) PDUs
s Supervisory (S) PDUs
u Unnumbered (U) PDUs
rr Receiver Ready (RR) S PDUs
rnr Receiver Not Ready (RNR) S PDUs
rej Reject (REJ) S PDUs
ui Unnumbered Information (UI) U PDUs
ua Unnumbered Acknowledgment (UA) U PDUs
disc Disconnect (DISC) U PDUs
dm Disconnected Mode (DM) U PDUs
sabme Set Asynchronous Balanced Mode Extended (SABME) U PDUs
test Test (TEST) U PDUs
xid Exchange Identification (XID) U PDUs
frmr Frame Reject (FRMR) U PDUs
inbound
True if the packet was received by the host performing the
capture rather than sent by that host. This primitive is
supported for certain link-layer types only, namely, DLT_SLIP,
DLT_IPNET, DLT_LINUX_SLL, DLT_LINUX_SLL2, DLT_PFLOG,
DLT_PPP_PPPD, a number of Juniper Networks private types and
some types of Linux DSA tag. For reference, the ``any'' pseudo-
interface uses DLT_LINUX_SLL or DLT_LINUX_SLL2 on Linux, and
DLT_IPNET on Solaris.
outbound
Same as the above, but for the opposite direction (from the
capturing host to the network).
ifindex interface_index
True if the packet was logged via the specified interface
(applies only to packets logged by the Linux "any" cooked v2
interface).
ifname interface
True, for DLT_PFLOG only, if the packet was logged as coming
from the specified interface.
on interface
Synonymous with the ifname primitive.
rnr num
True, for DLT_PFLOG only, if the packet was logged as matching
the specified PF rule number.
rulenum num
Synonymous with the rnr primitive.
reason code
True, for DLT_PFLOG only, if the packet was logged with the
specified PF reason code. Valid codes are: match, bad-offset,
fragment, short, normalize, memory, bad-timestamp, congestion,
ip-option, proto-cksum, state-mismatch, state-insert,
state-limit, src-limit, synproxy, map-failed (on FreeBSD only),
state-locked (on NetBSD only), translate (on OpenBSD only),
no-route (on OpenBSD only) and dummynet (on macOS only).
rset name
True, for DLT_PFLOG only, if the packet was logged as matching
the specified PF ruleset name of an anchored ruleset.
ruleset name
Synonymous with the rset primitive.
srnr num
True, for DLT_PFLOG only, if the packet was logged as matching
the specified PF rule number of an anchored ruleset.
subrulenum num
Synonymous with the srnr primitive.
action act
True, for DLT_PFLOG only, if PF took the specified action when
the packet was logged. Valid actions are: pass (or accept),
block (or drop) and, with later versions of pf(4), scrub,
noscrub, nat, nonat, binat, nobinat, rdr, nordr, synproxy-drop,
defer (on FreeBSD and OpenBSD only), match (on OpenBSD only),
divert (on OpenBSD only), rt (on OpenBSD only), afrt (on OpenBSD
only), dummynet (on macOS only), nodummynet (on macOS only),
nat64 (on macOS only) and nonat64 (on macOS only).
wlan ra ehost
True if the IEEE 802.11 RA is ehost. The RA field is used in
all frames except for management frames.
wlan ta ehost
True if the IEEE 802.11 TA is ehost. The TA field is used in
all frames except for management frames and CTS (Clear To Send)
and ACK (Acknowledgment) control frames.
wlan addr1 ehost
True if the first IEEE 802.11 address is ehost.
wlan addr2 ehost
True if the second IEEE 802.11 address, if present, is ehost.
The second address field is used in all frames except for CTS
(Clear To Send) and ACK (Acknowledgment) control frames.
wlan addr3 ehost
True if the third IEEE 802.11 address, if present, is ehost.
The third address field is used in management and data frames,
but not in control frames.
wlan addr4 ehost
True if the fourth IEEE 802.11 address, if present, is ehost.
The fourth address field is only used for WDS (Wireless
Distribution System) frames.
wlan type wlan_type
True if the IEEE 802.11 frame type matches the specified
wlan_type. Valid wlan_types are: mgt, ctl and data. The wlan
keyword is optional.
wlan type wlan_type subtype wlan_subtype
True if the IEEE 802.11 frame type matches the specified
wlan_type and frame subtype matches the specified wlan_subtype.
The wlan keyword is optional.
If the specified wlan_type is mgt, then valid wlan_subtypes are:
assoc-req, assoc-resp, reassoc-req, reassoc-resp, probe-req,
probe-resp, beacon, atim, disassoc, auth and deauth.
If the specified wlan_type is ctl, then valid wlan_subtypes are:
bar, ba, ps-poll, rts, cts, ack, cf-end and cf-end-ack.
If the specified wlan_type is data, then valid wlan_subtypes
are: data, data-cf-ack, data-cf-poll, data-cf-ack-poll, null,
cf-ack, cf-poll, cf-ack-poll, qos-data, qos-data-cf-ack,
qos-data-cf-poll, qos-data-cf-ack-poll, qos, qos-cf-poll and
qos-cf-ack-poll.
wlan subtype wlan_subtype
True if the IEEE 802.11 frame subtype matches the specified
wlan_subtype and frame has the type to which the specified
wlan_subtype belongs. The wlan keyword is optional.
wlan dir direction
True if the IEEE 802.11 frame direction matches the specified
direction. Valid directions are: nods, tods, fromds, dstods, or
a numeric value. The wlan keyword is optional.
vlan [vlan_id]
True if the packet is an IEEE 802.1Q VLAN packet. If the
optional vlan_id is specified, only true if the packet has the
specified vlan_id. Note that the first vlan keyword encountered
in an expression changes the decoding offsets for the remainder
of the expression on the assumption that the packet is a VLAN
packet. The `vlan [vlan_id]` keyword may be used more than
once, to filter on VLAN hierarchies. Each use of that keyword
increments the filter offsets by 4.
For example:
vlan 100 && vlan 200
filters on VLAN 200 encapsulated within VLAN 100, and
vlan && vlan 300 && ip
filters IPv4 protocol encapsulated in VLAN 300 encapsulated
within any higher order VLAN.
mpls [label_num]
True if the packet is an MPLS packet. If the optional label_num
is specified, only true if the packet has the specified
label_num. Note that the first mpls keyword encountered in an
expression changes the decoding offsets for the remainder of the
expression on the assumption that the packet is a MPLS-
encapsulated IP packet. The `mpls [label_num]` keyword may be
used more than once, to filter on MPLS hierarchies. Each use of
that keyword increments the filter offsets by 4.
For example:
mpls 100000 && mpls 1024
filters packets with an outer label of 100000 and an inner label
of 1024, and
mpls && mpls 1024 && host 192.9.200.1
filters packets to or from 192.9.200.1 with an inner label of
1024 and any outer label.
pppoed True if the packet is a PPP-over-Ethernet Discovery packet
(EtherType 0x8863).
pppoes [session_id]
True if the packet is a PPP-over-Ethernet Session packet
(EtherType 0x8864). If the optional session_id is specified,
only true if the packet has the specified session_id. Note that
the first pppoes keyword encountered in an expression changes
the decoding offsets for the remainder of the expression on the
assumption that the packet is a PPPoE session packet.
For example:
pppoes 0x27 && ip
filters IPv4 protocol encapsulated in PPPoE session id 0x27.
geneve [vni]
True if the packet is a Geneve packet (UDP port 6081). If the
optional vni is specified, only true if the packet has the
specified vni. Note that when the geneve keyword is encountered
in an expression, it changes the decoding offsets for the
remainder of the expression on the assumption that the packet is
a Geneve packet.
For example:
geneve 0xb && ip
filters IPv4 protocol encapsulated in Geneve with VNI 0xb. This
will match both IPv4 directly encapsulated in Geneve as well as
IPv4 contained inside an Ethernet frame.
vxlan [vni]
True if the packet is a VXLAN packet (UDP port 4789). If the
optional vni is specified, only true if the packet has the
specified vni. Note that when the vxlan keyword is encountered
in an expression, it changes the decoding offsets for the
remainder of the expression on the assumption that the packet is
a VXLAN packet.
For example:
vxlan 0x7 && ip6
filters IPv6 protocol encapsulated in VXLAN with VNI 0x7.
iso proto protocol
True if the packet is an OSI packet of protocol type protocol.
Protocol can be a number or one of the names clnp, esis, or
isis.
clnp, esis, isis
Abbreviations for:
iso proto \protocol
where protocol is one of the above protocols. Also in this
context es-is is an alias for esis and is-is is an alias for
isis.
isis proto protocol
True if the packet is an IS-IS packet of protocol type protocol,
which can be a number only.
l1, l2, iih, lsp, snp, csnp, psnp
Abbreviations for IS-IS PDU types.
atmfield relop val
True if the packet is an ATM packet, for SunATM on Solaris, and
the relation holds. atmfield is one of {vpi, vci}; relop is one
of {>, <, >=, <=, =, ==, !=} (where = means the same as ==); val
is an integer. vpi and vci stand for the virtual path
identifier (VPI) and the virtual channel identifier (VCI) fields
respectively.
atmfield val
Abbreviation for
atmfield == val
in the expression above.
atmfield (val1 or ... or valN)
Abbreviation for
(atmfield == val1 or ... or atmfield == valN)
in the expression above.
lane True if the packet is an ATM packet, for SunATM on Solaris, and
is an ATM LANE packet. Note that the first lane keyword
encountered in an expression changes the tests done in the
remainder of the expression on the assumption that the packet is
either a LANE emulated Ethernet packet or a LANE LE Control
packet. If lane isn't specified, the tests are done under the
assumption that the packet is an LLC-encapsulated packet.
Also the first lane keyword enables primitives that do not apply
to ATM in general, such as link host and link multicast.
oamf4sc
True if the packet is an ATM packet, for SunATM on Solaris, and
is a segment OAM F4 flow cell (VPI=0 & VCI=3).
oamf4ec
True if the packet is an ATM packet, for SunATM on Solaris, and
is an end-to-end OAM F4 flow cell (VPI=0 & VCI=4).
oamf4 True if the packet is an ATM packet, for SunATM on Solaris, and
is a segment or end-to-end OAM F4 flow cell (VPI=0 & (VCI=3 |
VCI=4)).
oam True if the packet is an ATM packet, for SunATM on Solaris, and
is a segment or end-to-end OAM F4 flow cell (VPI=0 & (VCI=3 |
VCI=4)).
metac True if the packet is an ATM packet, for SunATM on Solaris, and
is on a meta signaling circuit (VPI=0 & VCI=1).
bcc True if the packet is an ATM packet, for SunATM on Solaris, and
is on a broadcast signaling circuit (VPI=0 & VCI=2).
sc True if the packet is an ATM packet, for SunATM on Solaris, and
is on a signaling circuit (VPI=0 & VCI=5).
ilmic True if the packet is an ATM packet, for SunATM on Solaris, and
is on an ILMI circuit (VPI=0 & VCI=16).
connectmsg
True if the packet is an ATM packet, for SunATM on Solaris, and
is on a signaling circuit and is a Q.2931 Setup, Call
Proceeding, Connect, Connect Ack, Release, or Release Done
message.
metaconnect
True if the packet is an ATM packet, for SunATM on Solaris, and
is on a meta signaling circuit and is a Q.2931 Setup, Call
Proceeding, Connect, Release, or Release Done message.
fisu True if the packet is a Fill-In Signal Unit (FISU) MTP2 packet.
lssu True if the packet is a Link Status Signal Unit (LSSU) MTP2
packet.
msu True if the packet is a Message Signal Unit (MSU) MTP2 packet.
mtpfield relop val
True if the relation holds. mtpfield is one of {sio, dpc, opc,
sls}; relop is one of {>, <, >=, <=, =, ==, !=} (where = means
the same as ==); val is an integer. sio stands for the Service
Information Octet (SIO) field of the MTP2 MSU header. dpc, opc
and sls stand for the Destination Point Code (DPC), Originating
Point Code (OPC) and Signalling Link Selection (SLS) fields
respectively of the MTP3 standard routing label.
mtpfield val
Abbreviation for
mtpfield == val
in the expression above.
mtpfield (val1 or ... or valN)
Abbreviation for
(mtpfield == val1 or ... or mtpfield == valN)
in the expression above.
hfisu, hlssu, hmsu, hsio, hdpc, hopc, hsls
Same as fisu, lssu, msu, sio, dpc, opc and sls respectively, but
only if the MTP2 link uses the extended sequence numbers
encoding specified for high speed signalling links (HSL) in ITU-
T Recommendation Q.703 Annex A.
link host mac8addr
True if the source or the destination ARCnet node ID (for
DLT_ARCNET and DLT_ARCNET_LINUX only) or MS/TP station address
(for DLT_BACNET_MS_TP only) is mac8addr. May be qualified with
a different direction (src, dst, src and dst), in which case the
host keyword is optional.
mac8addr is a string of the form $xx or $x, where "x" is a
hexadecimal digit. For example:
link host $2b
Also in ARCnet context broadcast and multicast are equivalent to
link dst $0, and in MS/TP context broadcast is equivalent to
link dst $ff.
Note that this address syntax clashes with the parameter
expansion syntax in POSIX-compatible shells and elsewhere, so
depending on the use case the filter string may require the use
of single quotes or a backslash.
byte idx op val
True if the value of the link layer byte number idx satisfies a
condition with regard to val, which can be a number only. The
condition is one of: "equals to" (if op is =), "less than" (if
op is <), "greater than" (if op is >), "the result of bitwise
AND is not zero" (if op is &), "the result of bitwise OR is not
zero" (if op is |).
The arithmetic expressions and packet data accessors below
implement all of these and many other things much better, so
this primitive will be removed in a future release and should
not be used in applications that require forward compatibility.
ARITHMETIC EXPRESSIONS
Arithmetic expressions are the operands of a relational operator in a
relation of the following form:
expr1 relop expr2
This evaluates to true if and only if the relation holds. relop (the
relational operator) is one of {>, <, >=, <=, =, ==, !=} (where = means
the same as ==). Each of expr1 and expr2 is an arithmetic expression
composed of integer constants (expressed in standard C syntax), the
common arithmetic and bitwise binary operations {+, -, *, /, %, &, |,
^, <<, >>}, a length accessor, and packet data accessors. All
arithmetic expressions regardless of the complexity and composition
resolve to an integer value. Note that all comparisons are unsigned,
so that, for example, both 0x80000000 and 0xffffffff are > 0.
Note that 32-bit octal integer constants in the [010000000000 ..
037777777777] interval, which includes 75% of all 32-bit integers, are
interpreted as MAC-48 addresses when prepended with a single zero
(e.g., 012345670123 means 01:23:45:67:01:23). To disambiguate the
expression, prepend such an octal number with more zeroes
(0012345670123) or represent the same value using a decimal
(1402433619) or hexadecimal (0x53977053) number.
The % and ^ operators are currently only supported for filtering in the
kernel on particular operating systems (for example: FreeBSD, Linux
with 3.7 and later kernels, NetBSD); on all other systems (for example:
AIX, Hurd, illumos, Solaris, OpenBSD), if those operators are used,
filtering will be done in user mode, which will increase the overhead
of capturing packets and may cause more packets to be dropped.
The length accessor, indicated by the keywords len or length, gives the
length of the packet.
PACKET DATA ACCESSORS
To use the packet data in an arithmetic expression, use the following
syntax:
proto [ expr : size ]
Proto is one of arp, atalk, carp, decnet, ether, fddi, icmp, icmp6,
igmp, igrp, ip, ip6, lat, link, mopdl, moprc, pim, ppp, radio, rarp,
sca, sctp, slip, tcp, tr, udp, vrrp or wlan, and indicates the protocol
layer for the index operation. (ether, fddi, link, ppp, slip, tr and
wlan all refer to the link layer, radio refers to the "radio header"
added to some 802.11 captures.)
Note that in the current implementation of packet data accessors the
tcp, udp, icmp, igmp, pim, vrrp, carp, sctp and igrp above do not match
IPv6 packets (this may be fixed for some of these protocols in future),
also the icmp6 above implies that the IPv6 packet does not have any
extension (e.g. Fragment) headers, also the igrp above uses an OS-
specific protocol number (as discussed for the igrp abbreviation
earlier) and therefore should not be used in portable applications and
may be removed in future.
The byte offset, relative to the indicated protocol layer, is given by
expr, which can be an integer constant or any other valid arithmetic
expression. Size is optional and indicates the number of bytes in the
field of interest; it can be either one, two, or four, and defaults to
one; also it must be one of these valid integer constants only and
cannot be a more complex expression.
For example, `ether[0] & 1 != 0' catches all multicast traffic. The
expression `ip[0] & 0xf != 5' catches all IPv4 packets with options.
The expression `ip[6:2] & 0x1fff = 0' catches only unfragmented IPv4
datagrams and the first fragment of fragmented IPv4 datagrams. This
check is implicitly applied to the tcp, udp, icmp, sctp, igmp, pim,
igrp, vrrp and carp index operations. For instance, tcp[0] always
means the first byte of the TCP header, and never means the first byte
of an intervening fragment.
NAMED VALUES
Some offsets and field values may be expressed as names rather than as
numeric values. The following protocol header field offsets are
available: icmptype (ICMP type field), icmp6type (ICMPv6 type field),
icmpcode (ICMP code field), icmp6code (ICMPv6 code field) and tcpflags
(TCP flags field).
The following ICMP type field values are available: icmp-echoreply,
icmp-unreach, icmp-sourcequench, icmp-redirect, icmp-echo,
icmp-routeradvert, icmp-routersolicit, icmp-timxceed, icmp-paramprob,
icmp-tstamp, icmp-tstampreply, icmp-ireq, icmp-ireqreply, icmp-maskreq,
icmp-maskreply.
The following ICMPv6 type field values are available:
icmp6-destinationunreach, icmp6-packettoobig, icmp6-timeexceeded,
icmp6-parameterproblem, icmp6-echo, icmp6-echoreply,
icmp6-multicastlistenerquery, icmp6-multicastlistenerreportv1,
icmp6-multicastlistenerdone, icmp6-routersolicit, icmp6-routeradvert,
icmp6-neighborsolicit, icmp6-neighboradvert, icmp6-redirect,
icmp6-routerrenum, icmp6-nodeinformationquery,
icmp6-nodeinformationresponse, icmp6-ineighbordiscoverysolicit,
icmp6-ineighbordiscoveryadvert, icmp6-multicastlistenerreportv2,
icmp6-homeagentdiscoveryrequest, icmp6-homeagentdiscoveryreply,
icmp6-mobileprefixsolicit, icmp6-mobileprefixadvert,
icmp6-certpathsolicit, icmp6-certpathadvert,
icmp6-multicastrouteradvert, icmp6-multicastroutersolicit,
icmp6-multicastrouterterm.
The following TCP flags field values are available: tcp-fin, tcp-syn,
tcp-rst, tcp-push, tcp-ack, tcp-urg, tcp-ece, tcp-cwr.
COMPOUND EXPRESSIONS
Primitives and relations may be combined using:
Parentheses.
Negation (`!' or `not').
Concatenation (`&&' or `and').
Alternation (`||' or `or').
Negation has the highest precedence. Alternation and concatenation
have equal precedence and associate left to right.
For primitives, if an identifier is given without a keyword, the most
recent keyword is assumed. For example,
not host vs and ace
is short for
not host vs and host ace
which should not be confused with
not (host vs and host ace)
PROTOCOL NAMES IN VARIOUS CONTEXTS
The table below shows which protocol names can be used in which
contexts of the currently implemented syntax. The "name" column
contains a protocol name, which can be used as a keyword and/or as an
ID for the proto case of the type qualifier kind.
For keywords: if the keyword is an alias, the "K/see" column refers to
the main keyword; the "K/abbr" column tells whether the keyword can be
used as an abbreviation (that is, if the keyword is the only contents
of a primitive, it means a more complex expression); the "K/PDA" column
tells whether the keyword can be used in a packet data accessor; the
"K/pqual" column tells whether the keyword can be used as a case of the
proto qualifier kind.
For IDs: the "ID/tqual" column shows the valid context(s).
+---------+-------+--------+-------+---------+----------------------+
|name | K/see | K/abbr | K/PDA | K/pqual | ID/tqual |
+---------+-------+--------+-------+---------+----------------------+
|aarp | | yes | no | no | link proto \aarp |
|ah | | yes | no | no | [ip|ip6] proto \ah |
|arp | | yes | yes | yes | link proto \arp |
|atalk | | yes | yes | no | link proto \atalk |
|carp | | yes | yes | no | ip proto \carp |
|clnp | | yes | no | no | iso proto \clnp |
|csnp | | yes | no | no | |
|decnet | | yes | yes | yes | link proto \decnet |
|esis | | yes | no | no | iso proto \esis |
|es-is | esis | | | | |
|esp | | yes | no | no | [ip|ip6] proto \esp |
|ether | link | | | | |
|fddi | link | | | | |
|icmp | | yes | yes | no | ip proto \icmp |
|icmp6 | | yes | yes | no | |
|igmp | | yes | yes | no | ip proto \igmp |
|igrp | | yes | yes | no | ip proto \igrp |
|iih | | yes | no | no | |
|ip | | yes | yes | yes | link proto \ip |
|ip6 | | yes | yes | yes | link proto \ip6 |
|ipx | | yes | no | no | link proto \ipx |
|isis | | yes | no | yes | iso proto \isis |
|is-is | isis | | | | |
|iso | | yes | no | yes | link proto \iso |
|l1 | | yes | no | no | |
|l2 | | yes | no | no | |
|lat | | yes | yes | no | link proto \lat |
|link | | no | yes | yes | |
|lldp | | | | | link proto lldp |
|loopback | | | | | link proto loopback |
|lsp | | yes | no | no | |
|mopdl | | yes | yes | no | link proto \mopdl |
|moprc | | yes | yes | no | link proto \moprc |
|netbeui | | yes | no | no | link proto \netbeui |
|pim | | yes | yes | no | [ip|ip6] proto \pim |
|ppp | link | | | | |
|psnp | | yes | no | no | |
|radio | | no | yes | no | |
|rarp | | yes | yes | yes | link proto \rarp |
|sca | | yes | yes | no | link proto \sca |
|sctp | | yes | yes | yes | [ip|ip6] proto \sctp |
|slip | link | | | | |
|slow | | | | | link proto slow |
|snp | | yes | no | no | |
|stp | | yes | no | no | link proto \stp |
|tcp | | yes | yes | yes | [ip|ip6] proto \tcp |
|tr | link | | | | |
|udp | | yes | yes | yes | [ip|ip6] proto \udp |
|vrrp | | yes | yes | no | ip proto \vrrp |
|wlan | link | | | | |
+---------+-------+--------+-------+---------+----------------------+
EXAMPLES
To select all packets arriving at or departing from `sundown':
host sundown
To select traffic between `helios' and either `hot' or `ace':
host helios and (hot or ace)
To select all IPv4 packets between `ace' and any host except `helios':
ip host ace and not helios
To select all traffic between local hosts and hosts at Berkeley:
net ucb-ether
To select all FTP traffic through Internet gateway `snup':
gateway snup and (port ftp or ftp-data)
To select IPv4 traffic neither sourced from nor destined for local
hosts (if you gateway to one other net, this stuff should never make it
onto your local net).
ip and not net localnet
To select the start and end packets (the SYN and FIN packets) of each
TCP conversation that involves a non-local host.
tcp[tcpflags] & (tcp-syn|tcp-fin) != 0 and not src and dst net localnet
To select the TCP packets with flags RST and ACK both set. (i.e.
select only the RST and ACK flags in the flags field, and if the result
is "RST and ACK both set", match)
tcp[tcpflags] & (tcp-rst|tcp-ack) == (tcp-rst|tcp-ack)
To select all IPv4 HTTP packets to and from port 80, i.e. print only
packets that contain data, not, for example, SYN and FIN packets and
ACK-only packets. (IPv6 is left as an exercise for the reader.)
tcp port 80 and (((ip[2:2] - ((ip[0]&0xf)<<2)) - ((tcp[12]&0xf0)>>2)) != 0)
To select IPv4 packets longer than 576 bytes sent through gateway
`snup':
gateway snup and ip[2:2] > 576
To select IPv4 broadcast or multicast packets that were not sent via
Ethernet broadcast or multicast:
ether[0] & 1 = 0 and ip[16] >= 224
To select all ICMP packets that are not echo requests/replies (i.e.,
not ping packets):
icmp[icmptype] != icmp-echo and icmp[icmptype] != icmp-echoreply
icmp6[icmp6type] != icmp6-echo and icmp6[icmp6type] != icmp6-echoreply
BACKWARD COMPATIBILITY
The carp keyword became available in libpcap 1.2.1.
The hfisu, hlssu, hmsu, hsio, hopc, hdpc and hsls keywords became
available in libpcap 1.5.3.
The modulo (%) and bitwise XOR (^) binary operators became available in
libpcap 1.6.2.
The geneve keyword became available in libpcap 1.8.0.
The ICMPv6 type code names, as well as the tcp-ece and tcp-cwr TCP flag
names became available in libpcap 1.9.0.
The ifindex keyword became available in libpcap 1.10.0.
The vxlan keyword became available in libpcap 1.11.0.
The lldp and slow protocols became available for "ether proto" in
libpcap 1.11.0.
Before libpcap 1.11.0 the gateway primitive had a different definition,
which did not produce the expected results, also its support was
conditional and since libpcap 1.0.0 was disabled by default.
SEE ALSO
pcap(3)
BUGS
To report a security issue please send an e-mail to
security@tcpdump.org.
To report bugs and other problems, contribute patches, request a
feature, provide generic feedback etc please see the file
CONTRIBUTING.md in the libpcap source tree root.
Filter expressions on fields other than those in Token Ring headers
will not correctly handle source-routed Token Ring packets.
Filter expressions on fields other than those in 802.11 headers will
not correctly handle 802.11 data packets with both To DS and From DS
set.
`ip6 proto' should chase header chain, but at this moment it does not.
`ip6 protochain' is supplied for this behavior. For example, to match
IPv6 fragments: `ip6 protochain 44'
Arithmetic expression against transport layer headers, like tcp[0],
does not work against IPv6 packets. It only looks at IPv4 packets.
The sio and hsio keywords do not test whether the packet is an MSU
packet. The dpc, opc, sls, hdpc, hopc and hsls keywords do not test
whether the packet is an MTP3 packet.
For ARP and RARP the current implementation assumes IPv4 over Ethernet
and may incorrectly match packets that have a different combination of
protocol and hardware.
12 September 2026 pcap-filter(7)
libpcap 1.11.0 - Generated Tue Sep 15 09:41:12 CDT 2026