|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|
PCAP-FILTER(7) Miscellaneous Information Manual PCAP-FILTER(7)
pcap-filter - packet filter syntax
pcap_compile(3PCAP) 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(3PCAP), pcap_dispatch(3PCAP), pcap_next(3PCAP), or
pcap_next_ex(3PCAP).
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'.
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 address or a name. If it is
a name with multiple IPv4/IPv6 addresses, each address will
be checked for a match.
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 /etc/ethers or a
numerical MAC address of the form "xx:xx:xx:xx:xx:xx",
"xx.xx.xx.xx.xx.xx", "xx-xx-xx-xx-xx-xx", "xxxx.xxxx.xxxx"
or "xxxxxxxxxxxx", where each "x" is a hex digit (0-9, a-f,
or A-F).
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. May be
qualified with a specific protocol (arp, ip, rarp). For
example,
ip gateway host
is equivalent to
ether host ethernameaddr 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 a name from the networks database
(/etc/networks, etc.) or a network number.
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 must be written out fully; the 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.
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. For the latter zero
compression notation (::) is valid, but IPv4-mapped
notation (x:x:x:x:x:x:d.d.d.d) is not. 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. 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. 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, and macOS), 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 recognised 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 and macOS,
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. (See `ip proto' above for the meaning of
protocol.) Note that the IPv6 variant of ICMP uses a
different protocol number, named ipv6-icmp in AIX, FreeBSD,
illumos, Haiku, GNU/Hurd, Linux, macOS, NetBSD, OpenBSD,
Solaris and Windows. 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, arp, atalk, decnet,
ip, ip6, ipx, iso, lat, loopback, mopdl, moprc, netbeui,
rarp, sca or stp. Note these identifiers (except loopback)
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 etype.
In the case of Ethernet, the filter checks the Ethernet
type 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 etype 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 etype in
either an Ethernet frame or an 802.2 SNAP frame with
an OUI of 0x000000;
ipx the filter checks for the IPX etype in an Ethernet
frame, the IPX DSAP in the LLC header, the
802.3-with-no-LLC-header encapsulation of IPX, and
the IPX etype 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. Namely,
lat is Local Area Transport (LAT), mopdl is DNA Dump/Load
(MOP), moprc is DNA Remote Console (MOP) and sca is System
Communication Architecture (SCA).
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
Packet was received by the host performing the capture
rather than being sent by that host. This is only
supported for certain link-layer types, such as SLIP and
the ``cooked'' Linux capture mode used for the ``any''
device and for some other device types.
outbound
Packet was sent by the host performing the capture rather
than being received by that host. This is only supported
for certain link-layer types, such as SLIP and the
``cooked'' Linux capture mode used for the ``any'' device
and for some other device types.
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
(Ethernet type 0x8863).
pppoes [session_id]
True if the packet is a PPP-over-Ethernet Session packet
(Ethernet type 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 arcnetaddr
True, only for DLT_ARCNET or DLT_ARCNET_LINUX, if the
source or the destination ARCnet address of the packet is
arcnetaddr. May be qualified with a different direction
(src, dst, src and dst), in which case the host keyword is
optional.
arcnetaddr 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.
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 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 operator,
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.
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 operator, indicated by the keyword len, gives the
length of the packet.
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 tcp, udp and other upper-layer protocol types only apply
to IPv4, not IPv6 (this will be fixed in the 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 frag zero 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.
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.
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)
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 often can be used as an ID in
primitives that take a protocol name argument; in all cases except
loopback the protocol name is also a keyword. If the keyword is
an alias, the "see" column refers to the main keyword. The "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 "PDA" column tells whether
the keyword can be used in a packet data accessor. The "pqual"
column tells whether the keyword can be used as a case of the
proto qualifier kind. If the name can be used as an ID for the
proto case of the type qualifier kind, the "tqual ID" column shows
the valid context(s).
┌──────────┬──────┬──────┬─────┬───────┬──────────────────────┐
│ name │ see │ abbr │ PDA │ pqual │ tqual ID │
├──────────┼──────┼──────┼─────┼───────┼──────────────────────┤
│ 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 │ │
│ 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 │ │ │ │ │
│ 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 │ │ │ │ │
└──────────┴──────┴──────┴─────┴───────┴──────────────────────┘
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
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.
pcap(3PCAP)
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.
This page is part of the libpcap (packet capture library) project.
Information about the project can be found at
⟨http://www.tcpdump.org/⟩. If you have a bug report for this
manual page, see ⟨http://www.tcpdump.org/#patches⟩. This page was
obtained from the project's upstream Git repository
⟨https://github.com/the-tcpdump-group/libpcap.git⟩ on 2025-08-11.
(At that time, the date of the most recent commit that was found
in the repository was 2025-08-10.) If you discover any rendering
problems in this HTML version of the page, or you believe there is
a better or more up-to-date source for the page, or you have
corrections or improvements to the information in this COLOPHON
(which is not part of the original manual page), send a mail to
man-pages@man7.org
7 April 2025 PCAP-FILTER(7)
Pages that refer to this page: pcap(3pcap), pcap_compile(3pcap), cbpf-savefile(5), netsniff-ng(8)
|
HTML rendering created 2025-09-06 by Michael Kerrisk, author of The Linux Programming Interface. For details of in-depth Linux/UNIX system programming training courses that I teach, look here. Hosting by jambit GmbH. |
|