facebook / bpfilter

BPF-based packet filtering framework

An eBPF-based packet filtering framework.

bpfilter is an eBPF-based packet filtering framework designed to translate filtering rules into BPF programs. It comprises three main components:

1. A daemon that runs on the host, translating filtering rules into BPF programs.
2. A lightweight library to facilitate communication with the daemon.
3. A dedicated command line interface to define the filtering rules.

A typical usage workflow would be to start the bpfilter daemon, then define the filtering rules using bfcli (part of the bpfilter project), nftables or iptables. The bpfilter daemon will be responsible for translating the filtering rules into custom BPF programs, and loading them on the system.

Detailed information can be found in the documentation.

Quick start guide

1. Install dependencies

   # To build bpfilter
   sudo dnf install -y \
       bison \
       bpftool \
       clang \
       clang-tools-extra \
       cmake \
       flex \
       jq \
       libcmocka-devel \
       doxygen \
       git \
       lcov \
       libasan \
       libbpf-devel \
       libnl3-devel \
       libubsan \
       python3-breathe \
       python3-furo \
       python3-linuxdoc \
       python3-sphinx \
       pkgconf
   
   # To build nftables and iptables
   sudo dnf install \
       autoconf \
       automake \
       bison \
       flex \
       gmp-devel \
       libedit-devel \
       libmnl-devel \
       libnftnl-devel \
       libtool

2. Build bpfilter

   cmake -S $SOURCES_DIR -B $BUILD_DIR
   make -C $BUILD_DIR
   make -C $BUILD_DIR test

3. Build custom versions of nftables and iptables (optional)

   make -C $BUILD_DIR nftables iptables

4. Start the bpfilter daemon

   sudo $BUILD_DIR/src/bpfilter

5. Configure the filtering rules

   • For bfcli:

     $BUILD_DIR/output/bin/bfcli --file $RULESET

   • For nftables:

     sudo $BUILD_DIR/tools/install/sbin/nft --bpf ...

   • For iptables:

     sudo $BUILD_DIR/tools/install/sbin/iptables --bpf ...

License

bpfilter is licensed under GPLv2. You can find the licensing details in the COPYING file.

Acknowledgements

bpfilter was initially developed by Dmitrii Banshchikov as a Linux kernel usermode helper.

For further information and updates, visit the bpfilter documentation.

bpfilter's Issues

Compiled bpfilter doesn't load: No such file or directory

Hello @qdeslandes,

I have just compiled the bpfilter module on both the linux-6.1.14 branch and the bpf-next branch, both times I get the following output in dmesg:

[    4.619942] bpfilter: Loaded bpfilter_umh pid 971
[    4.622811] bpfilter: generate forward packet assessment
[    4.622823] bpfilter: generate forward packet assessment
[    4.625250] bpfilter: failed to create TC hook: No such file or directory
[    4.625348] bpfilter: failed to load chain INPUT in table filter: processed 73 insns (limit 1000000) max_states_per_insn 0 total_states 4 peak_states 4 mark_read 3
[    4.625455] bpfilter: failed to install new table 'filter': No such file or directory
[    4.625578] bpfilter: failed to created filter table: No such file or directory
[    4.625807] bpfilter: read fail 0

Would you happen to know if I did something wrong?

Thanks a lot,
Mr. Hax

Cannot restart bpfilter daemon after a first stop

Hello,
I'm working on an Ubuntu 24.04 server, compilation is OK, the first launch of bpfilter is successful:

user@ubuntu-2404-32go:~$ sudo bpfilter_build/src/bpfilter
[sudo] password for user: 
info   : failed test access to context file: /run/bpfilter/data.bin: No such file or directory
info   : generating BF_FLAVOR_NF program for BF_FRONT_IPT::BF_HOOK_IPT_LOCAL_IN::ens18
info   : generating BF_FLAVOR_NF program for BF_FRONT_IPT::BF_HOOK_IPT_FORWARD::ens18
info   : generating BF_FLAVOR_NF program for BF_FRONT_IPT::BF_HOOK_IPT_LOCAL_OUT::ens18
info   : waiting for requests...

but when exiting with Ctrl+C and relaunching bpfilter it does not work

user@ubuntu-2404-32go:~$ sudo bpfilter_build/src/bpfilter
[sudo] password for user: 
info   : failed test access to context file: /run/bpfilter/data.bin: No such file or directory
info   : generating BF_FLAVOR_NF program for BF_FRONT_IPT::BF_HOOK_IPT_LOCAL_IN::ens18
info   : generating BF_FLAVOR_NF program for BF_FRONT_IPT::BF_HOOK_IPT_FORWARD::ens18
info   : generating BF_FLAVOR_NF program for BF_FRONT_IPT::BF_HOOK_IPT_LOCAL_OUT::ens18
info   : waiting for requests...


^Cinfo   : received stop signal, exiting...
user@ubuntu-2404-32go:~$ sudo bpfilter_build/src/bpfilter
error  : failed to pin strings map: File exists
error  : failed to initialise messages map: File exists
error  : failed to initialize bpfilter: File exists
user@ubuntu-2404-32go:~$ 

I can make it work by rebooting my VM so I think there should be some files which are not cleaned with a ctrl+c ?

Thank you for your help.

LAB testing

Hi , I install it but when i use iptables with option i have error iptables v1.8.9 (nf_tables): unknown option "--bpf".
How to install it correctly and using it?
i already start it @bpfilter/build/src# ./bpfilter
info : restored new codegen at 0x8006f0
info : restored new codegen at 0x800bb0
info : restored new codegen at 0x801070
info : cache already initialised, skipping initialisation
info : waiting for requests...

Suggestion: update README with what is currently working for iptables/nftables & examples with iptables/nftables

Hello,

Thank you for this project ! I Saw your presentations and I'm interested in this project as this seems to bridge the gap between sysadmins/netadmins (I am) and Software engineers who brings more performance for Linux filtering !

I'm currently trying to reproduce an example with some rules and it's not working and I'm not sure if this is because that is not (yet) implemented or if my build setup is wrong.
Would it be possible to add a section on the README file with what is working and not working for iptables/nftables ?

Also an example of an iptables/nftables rule add/suppression would be greatly appreciated for starters :)

Thank you.

Support IPv6's `nextheader` field

An IPv6 packet's nextheader field can contain one of the following information:

• Layer 4 protocol identifier
• IPv6 extension header identifier

An IPv6 extension header will be located after the IPv6 header. There could be one or more extension header before the layer 4 header.

The current packet preprocessing logic defined by bpfilter always assume nextheadr contains the layer 4 header, meaning IPv6 packets containing extension headers are not properly preprocessed.

Document minimum-known linux kernel version requirement

Potentially pairs with the new README.md note about libbpf 1.0 requirement.
This could also simply be a listing of the the earliest known-working/developer-tested version(s) of the kernel.

As of PR #12 I can't build on my kernel 5.15.x-based system. It seems the bpf_dynptr was introduced to bpf-next in May 2022. Guessing that puts a minimum kernel for dynptr somewhere around 5.18 or 5.19, which is past that of stock Ubuntu, RHEL, and SLE/SUSE releases according to wikipedia. libbpf 1.0.0 was August 22, 2022, so if libbpf and kernel need to move in-step, perhaps the required kernel is 6.0 or newer?

Totally understand if maintainers want to focus on current kernel releases rather than optional configs and work-around for old kernels, but might help avoid further "issue" reports to document a known minimum.

Log packets matching a rule

nftables allows for packets to be logged: if a packet matches the rule's criteria (some of) its content is logged.

The exact implementation is not defined yet, as there are multiple questions that should first be answered:

• Should this be a new verdict? A rule should be able to log a packet and then apply a verdict (accept, drop, ...). If we define a new LOG verdict, it mean we should allow for verdicts to be combined such as LOG | DROP. Otherwise, it could be a rule directive like counter is in bfcli.
• How to actually log the data? bpf_printk() is too slow and not meant for this, BPF perfbuf could be used, but it BPF ringbuf could be better.
• What should be logged? Having the user define specific fields to log would complexify the bytecode: we would have to first check if the field is available in the current packet and then copy only the required data. Another approach could be to copy part of the program's runtime context back to userspace which contains: L3/4 protocol, L2 header, L3 header, L4 header. The user could also request only specific headers.

Collect error metrics

Generated BPF programs call kfuncs and BPF helpers for various purposes, and those call might fail. In this situation, the program will return with a default verdict. There is currently no way to know if such an error occurred during the program's lifetime, except for reading /sys/kernel/debug/tracing/trace_pipe if bpfilter is running in debug mode (--debug).

An error/failure counter would bring more visibility to this situation and help to understand the program's behavior.

error: ‘BPF_NETFILTER’ - build bpfilter in Ubuntu 22 and enable the hadware enablement (HWE) stack.

Hi everyone,

I am trying to build bpfilter in my current infrastructure which uses the Ubuntu 22.04 OS.
I enabled the HWE and upgraded the kernel to version 6.5, but there is an error when I hit make -C $BUILD_DIR for building the bpfilter. Here are some information:

## Upgrade kernal
sudo apt-get install --install-recommends linux-generic-hwe-22.04
root@com-glb-168:~/bpfilter# uname -r
6.5.0-45-generic

## Error log from make output
root@com-glb-168:~/bpfilter# make -C $BUILD_DIR
make: Entering directory '/root/bpfilter'
make[1]: Entering directory '/root/bpfilter'
make[2]: Entering directory '/root/bpfilter'
Consolidate compiler generated dependencies of target bpfilter
make[2]: Leaving directory '/root/bpfilter'
make[2]: Entering directory '/root/bpfilter'
[  1%] Building C object src/CMakeFiles/bpfilter.dir/core/bpf.c.o
/root/bpfilter/src/core/bpf.c: In function ‘bf_bpf_nf_link_create’:
/root/bpfilter/src/core/bpf.c:169:36: error: ‘BPF_NETFILTER’ undeclared (first use in this function); did you mean ‘IP_MSFILTER’?
  169 |     attr.link_create.attach_type = BPF_NETFILTER;
      |                                    ^~~~~~~~~~~~~
      |                                    IP_MSFILTER
/root/bpfilter/src/core/bpf.c:169:36: note: each undeclared identifier is reported only once for each function it appears in
/root/bpfilter/src/core/bpf.c:170:21: error: ‘struct <anonymous>’ has no member named ‘netfilter’
  170 |     attr.link_create.netfilter.pf = NFPROTO_IPV4;
      |                     ^
/root/bpfilter/src/core/bpf.c:171:21: error: ‘struct <anonymous>’ has no member named ‘netfilter’
  171 |     attr.link_create.netfilter.hooknum = bf_hook_to_nf_hook(hook);
      |                     ^
/root/bpfilter/src/core/bpf.c:172:21: error: ‘struct <anonymous>’ has no member named ‘netfilter’
  172 |     attr.link_create.netfilter.priority = priority;
      |                     ^
make[2]: *** [src/CMakeFiles/bpfilter.dir/build.make:104: src/CMakeFiles/bpfilter.dir/core/bpf.c.o] Error 1
make[2]: Leaving directory '/root/bpfilter'
make[1]: *** [CMakeFiles/Makefile2:237: src/CMakeFiles/bpfilter.dir/all] Error 2
make[1]: Leaving directory '/root/bpfilter'
make: *** [Makefile:136: all] Error 2
make: Leaving directory '/root/bpfilter'

I think the error is related to BPF_NETFILTER kernel module, so do I need to do something to enable it?

reserved identifier violation

👀 I would like to point out that identifiers like “_bf_opts_parser” and “_stop_received” do eventually not fit to the expected naming convention of the C language standard.
💭 Would you like to adjust your selection for unique names?

feasible to use bpfilter with uBPF to evaluate/test nftables rulesets in userspace?

i have a dream, where all nftables rules are tested statically before insertion into the kernel.

reading the bpfilter documentation, it seems that the daemon can be used (transparently?) as a backend for nftables userspace tools. did i understand that correctly?

if that's possible, i'd like to pull the generated BPF bytecode from bpfilter and pass it through uBPF in order to perform analysis against simulated packets.

does this seem like something that would work well with bpfilter as currently implemented?

Create a `CONTINUE` verdict

With the existing verdicts, it's not possible to forward a packet to the next rule: it is either accepted or dropped. In both cases, the chain won't process the remaining rules.

A CONTINUE verdict would allow packets to continue going through the filtering rules. Currently, the main interest of such a target would be to count the packets matching specific criteria. For example, this is not currently possible

# Counter the number of IPv6 packets and TCP packets going through the hook
rule
    meta.l3_proto ip6
    counter
    ACCEPT
rule
    meta.l4_proto tcp
    counter
    ACCEPT

IPv6 TCP packets would be counted towards rule #1 counter, as every IPv6 packet would be matched by rule #1 and accepted, stopping the processing. However, with a CONTINUE verdict:

# Counter the number of IPv6 packets and TCP packets going through the hook
rule
    meta.l3_proto ip6
    counter
    CONTINUE
rule
    meta.l4_proto tcp
    counter
    CONTINUE

IPv6 TCP packet would be processed by rule #1 and counted, then processing would continue with rule #2 and they would be counted again.

Provide usage examples in README.md to confirm operation

The original kernel introduction of bpfilter includes a series of usage examples via iptables ping and bpftool. A similar example set of commands (and perhaps expected log output from the bpfilter daemon) would be a huge help in confirming things are hooked in properly after building/loading the binary.