Hooks

A hook is the location in the kernel a chain is attached to. It’s defined once and for all when the chain is created. The hook options tell bpfilter how to attach the chain: to which interface, which cgroup, or with which Netfilter priorities.

Supported hooks

The following hooks are supported:

  • BF_HOOK_XDP: XDP hook.

  • BF_HOOK_TC_INGRESS: ingress TC hook.

  • BF_HOOK_NF_PRE_ROUTING: similar to nftables and iptables prerouting hook.

  • BF_HOOK_NF_LOCAL_IN: similar to nftables and iptables input hook.

  • BF_HOOK_CGROUP_SKB_INGRESS: ingress cgroup_skb hook.

  • BF_HOOK_CGROUP_SKB_EGRESS: egress cgroup_skb hook.

  • BF_HOOK_NF_FORWARD: similar to nftables and iptables forward hook.

  • BF_HOOK_NF_LOCAL_OUT: similar to nftables and iptables output hook.

  • BF_HOOK_NF_POST_ROUTING: similar to nftables and iptables postrouting hook.

  • BF_HOOK_TC_EGRESS: egress TC hook.

  • BF_HOOK_CGROUP_SOCK_ADDR_CONNECT4: cgroup hook for IPv4 connect() syscalls.

  • BF_HOOK_CGROUP_SOCK_ADDR_CONNECT6: cgroup hook for IPv6 connect() syscalls.

  • BF_HOOK_CGROUP_SOCK_ADDR_SENDMSG4: cgroup hook for IPv4 UDP sendmsg() syscalls.

  • BF_HOOK_CGROUP_SOCK_ADDR_SENDMSG6: cgroup hook for IPv6 UDP sendmsg() syscalls.

Note

BF_HOOK_CGROUP_SOCK_ADDR_* hooks operate on socket metadata rather than packet data. Supported matchers: meta.l3_proto, meta.l4_proto, meta.probability, meta.dport, meta.pid, ip4.daddr, ip4.dnet, ip4.proto, ip6.daddr, ip6.dnet, udp.dport. Connect hooks additionally support tcp.dport. Sendmsg hooks additionally support ip4.saddr, ip4.snet, ip6.saddr, and ip6.snet. Sets are supported with the same per-component restrictions: each set key component must be a matcher supported by the chain’s hook. meta.dport is supported in sets, while meta.sport is unavailable on these hooks.

Hook options

$OPTIONS are hook-specific comma separated key value pairs. A given hook option can only be specified once:

Option

Required by

Supported by

Notes

ifindex=$IFINDEX

BF_HOOK_XDP, BF_HOOK_TC_INGRESS, BF_HOOK_TC_EGRESS

N/A

Interface index to attach the program to.

cgpath=$CGROUP_PATH

BF_HOOK_CGROUP_SKB_*, BF_HOOK_CGROUP_SOCK_ADDR_*

N/A

Path to the cgroup to attach to.

family=$FAMILY

N/A

N/A

Deprecated, bpfilter will automatically attach Netfilter chains to both IPv4 and IPv6 families.

priorities=$INT1-$INT2

BF_HOOK_NF_*

N/A

INT1 and INT2 are different non-zero integers. Priority values to use when attaching the chain. Two values are required to ensure atomic update of the chain.

Example

chain xdp_filter BF_HOOK_XDP{ifindex=2} ACCEPT
chain local_input BF_HOOK_NF_LOCAL_IN{priorities=101-102} ACCEPT
chain workload_egress BF_HOOK_CGROUP_SKB_EGRESS{cgpath=/sys/fs/cgroup/my.slice} ACCEPT

If your chain was loaded without hook options, you can provide them to bfcli chain attach using --option, for example --option ifindex=2.

See Where filtering happens to understand which packets each hook will see, and bfcli commands and global options for the commands used to load and attach a chain.