Matchers

Matchers are defined such as:

$TYPE [not] [$OP] $PAYLOAD

With:

• $TYPE: type of the matcher, defines which part of the processed network packet needs to be compared against. All the exact matcher types are defined below.

• not: optional comparison negation. When used, it prefixes an operator, e.g. tcp.sport not eq 80, (ip4.saddr) not in foo, or, with no operator, tcp.sport not 80 (equivalent to tcp.sport not eq 80).

• $OP: comparison operation, not all $TYPE of matchers support all the existing comparison operators:

  • eq: exact equality. This is the default if no $OP is provided.

  • any: match the packet against a set of data defined as the payload. If any of the member of the payload set is found in the packet, the matcher is positive. For example, if you want to match all the packets with the SYN or the ACK flag set: tcp.flags any syn,ack.

  • all: match the packet against a set of data defined as the payload. If all the member of the payload set are found in the packet, the matcher is positive, even if the packet contains more than only the members defined in the payload. For example, to match all the packets containing at least the ACK TCP flag: tcp.flags all ACK.

  • in: matches the packet against a hashed set of reference values. Using the in operator is useful when the packet’s data needs to be compared against a large set of different values. The matcher’s type is then used as the set’s key, and must be enclosed in parentheses: (ip4.saddr) in {192.0.2.1; 192.0.2.2} is valid, ip4.saddr in {...} is not. The tables below describe the payload for a key made of a single matcher. See Sets to combine multiple matchers in a key, to use named sets, and for the list of matchers supported by sets.

  • range: matches in a range of values. Formatted as $START-$END. Both $START and $END are included in the range.

• $PAYLOAD: payload to compare to the processed network packet. The exact payload format depends on $TYPE.

Meta

Matches	Type	Operator	Payload	Notes
Interface	meta.iface	eq	$INTERFACE	For chains attached to an ingress hook, $INTERFACE is the input interface, for chains attached to an egress hook, $INTERFACE is the output interface. $INTERFACE must be an interface name (e.g., “eth0”, “wlan0”) or a decimal interface index (e.g., “1”, “2”).
L3 protocol	meta.l3_proto	eq	$PROTOCOL	$PROTOCOL must be an internet layer protocol name (e.g. “IPv6”, case insensitive), or a valid decimal or hexadecimal IEEE 802 number.
L4 protocol	meta.l4_proto	eq	$PROTOCOL	$PROTOCOL must be a transport layer protocol name (e.g. “ICMP”, case insensitive), or a valid decimal or hexadecimal internet protocol number.
Source port	meta.sport	eq	$PORT	$PORT must be a valid decimal port number.
		in	{$PORT[;...]}
		range	$START-$END	$START and $END are valid port values, as decimal integers.
Destination port	meta.dport	eq	$PORT	$PORT must be a valid decimal port number.
		in	{$PORT[;...]}
		range	$START-$END	$START and $END are valid port values, as decimal integers.
Probability	meta.probability	eq	$PROBABILITY	$PROBABILITY is a floating-point percentage value (i.e., within [0%, 100%], e.g., “50%” or “33.33%”). For BF_HOOK_CGROUP_SOCK_ADDR_* hooks, probability applies per socket operation: each connect() or sendmsg() call is independently accepted or dropped.
Mark	meta.mark	eq	$MARK	$MARK must be a valid decimal or hexadecimal 32-bits value. Incompatible with BF_HOOK_XDP and BF_HOOK_CGROUP_SOCK_ADDR_* hooks.
Flow hash	meta.flow_hash	eq	$HASH	$HASH must be a decimal or hexadecimal 32-bits integer. Only compatible with BF_HOOK_TC_INGRESS and BF_HOOK_TC_EGRESS hooks.
		range	$START-$END	$START and $END must be decimal or hexadecimal 32-bits integers, with $START <= $END. Only compatible with BF_HOOK_TC_INGRESS and BF_HOOK_TC_EGRESS hooks.
Flow probability	meta.flow_probability	eq	$PROBABILITY	$PROBABILITY is a floating-point percentage value (i.e., within [0%, 100%], e.g., “50%” or “33.33%”). Unlike meta.probability which uses per-packet randomness, meta.flow_probability computes a deterministic hash from the packet’s 5-tuple (source/destination IP, source/destination port, protocol) ensuring all packets from the same flow get the same match decision. Only applies to IPv4/IPv6 packets with TCP or UDP on L4; packets with other protocols are skipped. Compatible with BF_HOOK_XDP, BF_HOOK_TC_INGRESS, BF_HOOK_TC_EGRESS, BF_HOOK_CGROUP_SKB_INGRESS, and BF_HOOK_CGROUP_SKB_EGRESS hooks.
Process ID	meta.pid	eq	$PID	$PID must be a decimal process ID (thread group ID), as seen from the initial PID namespace. This is the process ID reported by the log entries of BF_HOOK_CGROUP_SOCK_ADDR_* hooks, not its namespace-local counterpart. Only compatible with BF_HOOK_CGROUP_SOCK_ADDR_* hooks.
		in	{$PID[;...]}

Note

On packet-based hooks, meta.sport and meta.dport are protocol-neutral across TCP and UDP. They do not match packets with other L4 protocols.

IPv4

Matches	Type	Operator	Payload	Notes
Source address	ip4.saddr	eq	$ADDR	$ADDR is an IPv4 address in dotted-decimal format, “ddd.ddd.ddd.ddd”, where ddd is a decimal number of up to three digits in the range 0 to 255. To filter on an IPv4 network (using an IPv4 address and a subnet mask), see ip4.snet or ip4.dnet.
		in	{$ADDR[;...]}
Destination address	ip4.daddr	eq	$ADDR
		in	{$ADDR[;...]}
Source network	ip4.snet	eq	$ADDR/$MASK	$ADDR is an IPv4 network address in dotted-decimal format, "ddd.ddd.ddd.ddd", where ddd is a decimal number of up to three digits in the range 0 to 255, $MASK is a subnet mask in the range 0 to 32.
		in	{$ADDR/$MASK[;...]}
Destination network	ip4.dnet	eq	$ADDR/$MASK
		in	{$ADDR/$MASK[;...]}
Protocol	ip4.proto	eq	$PROTOCOL	$PROTOCOL must be a transport layer protocol name (e.g. “ICMP”, case insensitive), or a valid decimal or hexadecimal internet protocol number.
DSCP	ip4.dscp	eq	$DSCP	$DSCP is a DSCP class name (e.g. “ef”, “cs1”, “af21”, case insensitive) or a numeric value (0-63, decimal or hexadecimal). “be” is accepted as an alias for “cs0”.

IPv6

Matches	Type	Operator	Payload	Notes
Source address	ip6.saddr	eq	$ADDR	$ADDR must be an IPv6 address composed of 8 hexadecimal numbers (abbreviations are supported). To filter on an IPv6 network (using an IPv6 address and a subnet mask), see ip6.snet or ip6.dnet.
		in	{$ADDR[;...]}
Destination address	ip6.daddr	eq	$ADDR
		in	{$ADDR[;...]}
Source network	ip6.snet	eq	$ADDR/$MASK	$ADDR must be an IPv6 address composed of 8 hexadecimal numbers (abbreviations are supported), $MASK is a subnet mask in the range 0 to 128.
		in	{$ADDR/$MASK[;...]}
Destination network	ip6.dnet	eq	$ADDR/$MASK
		in	{$ADDR/$MASK[;...]}
Next header	ip6.nexthdr	eq	$NEXT_HEADER	$NEXT_HEADER is a transport layer protocol name (e.g. “ICMP”, case insensitive), an IPv6 extension header name, or a valid decimal or hexadecimal internet protocol number.
DSCP	ip6.dscp	eq	$DSCP	$DSCP is a DSCP class name (e.g. “ef”, “cs1”, “af21”, case insensitive) or a numeric value (0-63, decimal or hexadecimal). “be” is accepted as an alias for “cs0”.

Tip

The following IPv6 extension header names are recognized by bpfilter: hop, routing, frag, ah, dst, mh.

TCP

Matches	Type	Operator	Payload	Notes
Source port	tcp.sport	eq	$PORT	$PORT must be a valid decimal port number.
		in	{$PORT[;...]}
		range	$START-$END	$START and $END are valid port values, as decimal integers.
Destination port	tcp.dport	eq	$PORT	$PORT must be a valid decimal port number.
		in	{$PORT[;...]}
		range	$START-$END	$START and $END are valid port values, as decimal integers.
Flags	tcp.flags	eq	$FLAG[,...]	$FLAG is a comma-separated list of one or more TCP flags (fin, syn, rst, psh, ack, urg, ece, or cwr). Flags are case-insensitive.
		any
		all

Tip

The tcp.flags operators can be confusing, as they can be used to match all, some, or none of the flags available in the TCP header. This section aims to provide clarity to their exact behavior:

• eq: the TCP header must contain the exact same flags as defined in the rule. The matcher tcp.flags eq syn,ack will match syn,ack, but not syn,ack,fin nor rst.

• any: the TCP header must contain any of the flags defined in the rule. The matcher tcp.flags any syn,ack will match syn, or ack, or syn,ack, but not fin.

• all: the TCP header must contain at least the flags defined in the rule. The matcher tcp.flags all syn,ack will match syn,ack,fin, but not syn, or ack,fin.

Each operator can be negated with not to invert the match:

• not eq: the TCP header must not contain the exact same flags. The matcher tcp.flags not eq syn will match ack, or syn,ack, but not syn alone.

• not any: none of the specified flags may be present. The matcher tcp.flags not any syn,ack will match fin or rst, but not syn, ack, or syn,ack.

• not all: not all of the specified flags are present. The matcher tcp.flags not all syn,ack will match syn or ack alone, but not syn,ack or syn,ack,fin.

UDP

Matches	Type	Operator	Payload	Notes
Source port	udp.sport	eq	$PORT	$PORT must be a valid decimal port number.
		in	{$PORT[;...]}
		range	$START-$END	$START and $END are valid port values, as decimal integers.
Destination port	udp.dport	eq	$PORT	$PORT must be a valid decimal port number.
		in	{$PORT[;...]}
		range	$START-$END	$START and $END are valid port values, as decimal integers.

ICMP

Matches	Type	Operator	Payload	Notes
Type	icmp.type	eq	$TYPE	$TYPE is an ICMP type name (e.g. “echo-reply”, case insensitive), or a decimal or hexadecimal ICMP type value.
Code	icmp.code	eq	$CODE	$CODE is a decimal or hexadecimal ICMP code value.

Tip

The following ICMP type names are recognized by bpfilter: echo-reply, destination-unreachable, source-quench, redirect, echo-request, time-exceeded, parameter-problem, timestamp-request, timestamp-reply, info-request, info-reply, address-mask-request, address-mask-reply, router-advertisement, router-solicitation.

ICMPv6

Matches	Type	Operator	Payload	Notes
Type	icmpv6.type	eq	$TYPE	$TYPE is an ICMPv6 type name (e.g. “echo-reply”, case insensitive), or a decimal or hexadecimal ICMPv6 type value.
Code	icmpv6.code	eq	$CODE	$CODE is a decimal or hexadecimal ICMPv6 code value.

Tip

The following ICMPv6 type names are recognized by bpfilter: destination-unreachable, packet-too-big, time-exceeded, echo-request, echo-reply, mld-listener-query, mld-listener-report, mld-listener-reduction, nd-router-solicit, nd-router-advert, nd-neighbor-solicit, nd-neighbor-advert, parameter-problem, mld2-listener-report.