Suricata Performance: Resolving eBPF Bypass Failure via Manual Kernel Filter Compilation

Enabling eBPF (Extended Berkeley Packet Filter) bypass is the ultimate step in Suricata performance tuning. It allows the kernel to filter known-safe traffic (e.g., TLS data) before the packets reach the resource-intensive Userspace engine. However, this functionality often fails to work out-of-the-box.

I found a bug report confirming that the pre-compiled .bpf files shipped in my distribution were incompatible with the current libbpf library (version > 1.0). Without a successful .bpf load, the kernel bypass mechanism is completely inactive.

Part I: Diagnosis of the Bypass Failure

To confirm the failure, I checked Suricata’s internal statistics via suricatasc. The initial output confirmed that the eBPF bypass was not occurring, despite the configuration being set in suricata.yaml.

Initial Failure Metrics

The metrics show zero packets being bypassed (ipv4_success: 0):

>>> ebpf-bypassed-stat
Success:
{
    "ens3": {
        "ipv4_fail": 0,
        "ipv4_maps_count": 0,
        "ipv4_success": 0,
        "ipv6_fail": 0,
        "ipv6_maps_count": 0,
        "ipv6_success": 0
    },
    "ens5": {
        "ipv4_fail": 0,
        "ipv4_maps_count": 78,
        "ipv4_success": 0,
        "ipv6_fail": 0,
        "ipv6_maps_count": 0,
        "ipv6_success": 0
    }
}

The simple interface status confirmed the failure, but also revealed an underlying issue with checksums that requires further attention:

>>> iface-stat ens3
Success:
{
    "bypassed": 0,
    "drop": 0,
    "invalid-checksums": 11510,
    "pkts": 21704175
}

The attempt to load the default .bpf file resulted in a fatal error:

 Error: ebpf: Unable to load eBPF objects in '/usr/lib/suricata/ebpf/bypass_filter.bpf': Operation not supported

Part II: Manual Kernel Filter Compilation

The solution is to manually compile the .bpf files from the Suricata source code, linking them against the host system’s current libbpf library. This resolves the version incompatibility.

The Compilation Process

I grab the Suricata source code and configure the build process specifically to include eBPF support:

# Install dependencies as explained in Suricata installation documentation
./scripts/bundle.sh
./autogen.sh
./configure --enable-ebpf-build

# Change into the eBPF directory and compile the kernel filters
cd ebpf
make

Deployment

The newly compiled files are copied to the correct path, replacing the broken distribution files.

cp *.bpf /usr/lib/suricata/ebpf/

Once the corrected filter is loaded, the logs show success:

 Info: ebpf: Successfully loaded eBPF file '/usr/lib/suricata/ebpf/bypass_filter.bpf' on 'ens3'
 Info: ebpf: Successfully loaded eBPF file '/usr/lib/suricata/ebpf/bypass_filter.bpf' on 'ens5'

Part III: Verification

The successful loading of the eBPF filter confirms that Suricata is now utilizing the kernel to filter traffic before passing it to the Userspace engine, resulting in significant CPU savings.

Final Success Metrics (Post-Compilation)

The metrics now show thousands of successful bypasses, validating the fix:

>>> ebpf-bypassed-stat
Success:
{
    "ens3": {
        "ipv4_fail": 0,
        "ipv4_maps_count": 32,
        "ipv4_success": 32292,
        "ipv6_fail": 0,
        "ipv6_maps_count": 0,
        "ipv6_success": 0
    },
    "ens5": {
        "ipv4_fail": 0,
        "ipv4_maps_count": 78,
        "ipv4_success": 32290,
        "ipv6_fail": 0,
        "ipv6_maps_count": 0,
        "ipv6_success": 0
    }
}

The interface statistics now display the successfully bypassed packets:

>>> iface-stat ens5
Success:
{
    "bypassed": 807883,
    "drop": 0,
    "invalid-checksums": 0,
    "pkts": 316991330
}

Note: The original log showed a high count of invalid-checksums. This is a separate, critical issue (often related to offloading) that needs to be addressed, but the eBPF bypass functionality itself is now working.

Sources / See Also

Suricata Documentation. Working with eBPF and XDP. https://docs.suricata.io/en/latest/install/ebpf-xdp.html
Suricata Documentation. Suricata 7 Changelog (Note new policy behavior). https://suricata.io/changelog/
Suricata Documentation. FAQ: Traffic gets blocked after upgrading to Suricata 7. https://suricata-update.readthedocs.io/en/latest/faq.html#my-traffic-gets-blocked-after-upgrading-to-suricata-7
Libvirt Documentation. VirtIO Device Configuration (Driver Offload Parameters). https://libvirt.org/formatdomain.html#elementsNICS
GitHub Repository libbpf. eBPF library source and version compatibility issues. https://github.com/libbpf/libbpf
Linux Networking. Understanding the eBPF framework and its application in networking. https://www.kernel.org/doc/html/latest/networking/filter.html