Usage

Note

bpfilter is not (yet) packaged for any distribution. If you want to try it, you will have to build it from sources. See Build from sources.

bpfilter is composed of two main parts that work together: the front-ends are used by the users to define the filtering rules and send them to the daemon that performs the heavy lifting of generating the BPF bytecode.

Before anything, you will have to run the daemon on your system, see The daemon for more details.

Once the daemon is running, you need to choose which front-end’s CLI to use:

  • bfcli: bpfilter-specific CLI, developed as part of the project. bfcli supports new bpfilter features before other CLIs as it’s used for development. It allows for a more flexible rule definition: you can use a combination of filters and hooks that might not be possible with other CLIs. However, it doesn’t support nftables or iptables rules format.

  • nftables: requires a custom version of the nft binary with bpfilter support (see below), and support for new bpfilter features is usually a bit delayed.

  • iptables: similar to nftables, however iptables has been deprecated globally in favor of nftables.

Example Usage

Note

This is only to be used as an example and a more interactive test to familiarize you with bpfilter, more in-depth information can be found throughout the documentation.

Initialize bpfilter daemon

Note

From here on we assume all commands are being run from your local bpfilter source directory following cmake -B build

> sudo ./build/output/bpfilter --transient --verbose=debug --no-iptables

Load bfcli filter(s)

While the bpfilter daemon runs, now we will open up a separate window to use bfcli

Note

bfcli is just one of the ways you can communicate with the bpfilter daemon along with iptables and nftables

> sudo ./build/output/bfcli --str "chain BF_HOOK_NF_LOCAL_IN policy ACCEPT rule ip4.saddr eq 192.168.1.1 ACCEPT"

The command above will send a request to the bpfilter daemon to create a chain and attach it to the BF_HOOK_NF_LOCAL_IN hook, located after the packet has been routed in the kernel network stack. A single rule is defined, which will accept the packet if its source IPv4 address is 192.168.1.1. If the rule doesn’t match the packet, the chain’s policy is applied and the packet is accepted. In its current shape, the chain will always accept incoming packets.

You can check by running:

> ping 192.168.1.1
... [pinging] ...
--- 192.168.1.1 ping statistics ---
4 packets transmitted, 4 packets received, 0.0% packet loss

Note

If you run into errors here there may be problems with your system worth diagnosing before continuing

Now let’s try changing the filter from 192.168.1.1 ACCEPT to DROP. If we work through it logically, now bpfilter should in general accept incoming traffic from the BF_HOOK_NF_LOCAL_IN hook location, but now if it detects the IP address to be 192.168.1.1 then it should drop the packets. So now when we ping 192.168.1.1 we should not recieve its subsequent response.

sudo ./build/output/bfcli --str "chain BF_HOOK_NF_LOCAL_IN policy ACCEPT rule ip4.saddr eq 192.168.1.1 DROP"

You should now observe a change in the behavior of ping.

> ping 192.168.1.1
... [attempting to ping] ...
--- 192.168.1.1 ping statistics ---
4 packets transmitted, 0 packets received, 100.0% packet loss

Congratulations you have now officially used bpfilter to systematically filter out packets from 192.168.1.1. For documentation for more complex filtering options please check under the DEVELOPERS section and good luck!