This guide describes the nftables-based firewall integration of BitNinja, including system requirements, limitations, verification steps, and useful troubleshooting commands.

1. Overview#

BitNinja integrates with nftables and uses eBPF maps to manage IP reputation and blocking rules. Instead of legacy iptables/ipset handling, rules are inserted directly into nftables and enforced via BPF-backed maps.

2. Limitations#

⚠️ Kernel Requirement

  • Kernel version 5.14 or newer is required.
  • There is an internal compatibility check that prevents usage on kernels below 5.14.
  • Earlier kernel versions are not supported.

You can verify your kernel version with:

uname -r

3. Supported Operating Systems#

The nftables integration is supported on:

  • Ubuntu 22.04+
  • Debian 12+
  • AlmaLinux 9+
  • Rocky Linux 9+

Earlier releases are not supported due to kernel and nftables limitations.

4. Required Tools#

The following tools must be installed:

  • bpftool
  • jq

Verify Installation:
Check that both tools are installed and available:

bpftool --version
jq --version

If either command fails, install the missing package using your distribution’s package manager.

In case you run into the following error on Ubuntu 22.04:
Command 'bpftool' not found, but can be installed with:

You can fix it by installing:
apt-get install linux-tools-5.15.0-25-generic

5. nftables Integration#

BitNinja inserts its rules directly into nftables.

Verify Ruleset:
To check whether BitNinja rules are loaded:

nft list ruleset

You should see the following table:

table ip bitninja { //BitNinja rules within// }

This table must:

  • Exist
  • Be populated with chains, sets, and rules

If the table does not exist, BitNinja nftables integration is not active or failed to initialize.

6. Checking IP Presence in Maps#

BitNinja uses BPF maps stored under /sys/fs/bpf/ to manage IP data.
Check if an IP Exists in Any Map

/var/lib/bitninja/policier/bitninja-policier check --elem 1.2.3.4

This command verifies whether the specified IP address is present in any BitNinja-managed map.

Check Including Ranges:
To also verify if the IP is part of a stored range:

/var/lib/bitninja/policier/bitninja-policier check --elem 1.2.3.4 --show-range

The --show-range flag will display matching CIDR ranges if applicable.

7. Inspecting BPF Map Directory#

BitNinja stores its eBPF maps in:

ls -la /sys/fs/bpf/

This directory should contain the pinned BPF maps used by the policier component.

If the directory is empty or missing expected entries:

  • Ensure the kernel supports eBPF
  • Verify BitNinja services are running
  • Confirm required tools are installed

8. Summary Checklist#

Before troubleshooting, confirm:

  • ✅ Kernel version ≥ 5.14
  • ✅ Supported OS version
  • ✅ bpftool installed
  • ✅ jq installed
  • ✅ table ip bitninja {} exists in nftables
  • ✅ BPF maps visible under /sys/fs/bpf/
  • ✅ IP lookup works via bitninja-policier check

If all of the above conditions are met, BitNinja’s nftables-based protection layer should be operating correctly.