BitNinja nftables Compatibility Guide

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.

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.