Building an eBPF-based Firewall with LPM Trie–Based IP Range Matching

By now, we already know how to capture network traffic using eBPF/XDP, parse it, and even perform some basic IPv6 ICMP rate limiting.

So naturally, you might wonder how different an eBPF-based firewall really is from the rate limiter. After all, instead of rate-limiting packets, we could just block them entirely, right?

Well, not quite.

While our firewall implementation will only focus on filtering packets by client IP (not by ports, protocol, or fingerprinting), one ideally doesn’t want users to specify every single IP rule manually. In many cases, it would be much easier to allow one to whitelist or blacklist entire IP ranges instead.

Nonetheless, a simple IP-based firewall might work fine if you’re only whitelisting a few static addresses. But what if those IPs are dynamic and constantly changing within a certain range or subnet?

But how?

In this tutorial, we’ll learn how to filter network packets using the BPF_MAP_TYPE_LPM_TRIE eBPF map type, which allows one to easily check and enforce whether a certain IP (client machine) belongs to a blacklisted IP range or not.

This playground has a network topology with 4 separate machines on three different networks:

• server in network 172.16.0.10/24
• client in network 10.0.0.10/16
• attacker in network 192.168.178.10/24
• gateway between networks 192.168.178.0/24, 10.0.0.0/16 and 172.16.0.10/24

High-Level Overview

Designing an XDP-based firewall is quite straightforward and follows a similar pattern as packet rate-limiting:

• Keep a blacklist (or whitelist) of rules in an eBPF map (IPs, ports, protocols)
• Capture and parse incoming network packets
• Check the packet header fields against the map entries
• Enforce the firewall rules

But obviously things get more complex when adding features such as filtering a combination of IP, port, and protocol, or introducing mechanisms to detect anomalies in network traffic like TCP/TLS fingeprinting.

But why even XDP? Why not just nftables (or iptables)?

While these numbers speak for themselves, one shouldn’t overstate their impact — most companies don’t really operate at a scale where XDP’s extreme performance truly matters, and netfilter-based firewalls are more than sufficient for their needs.

But when that scale does matter, XDP-based firewalls like Cloudflare’s Magic Firewall can block massive attacks—such as 7.3 terabits-per-second (Tbps) DDoS floods—delivering exceptional value to the organizations that rely on them.

Ideally, we’d address all the different firewall features, but instead, I’ll show you one approach in particular that other eBPF tutorials don't put much focus on — the use of BPF_MAP_TYPE_LPM_TRIE for blacklisting (or whitelisting) IP addresses.

BPF_MAP_TYPE_LPM_TRIE eBPF map

In the case of a firewall, this eBPF map type allows one to determine, through a simple map lookup, whether an IP belongs to any of the specified blacklisted (or whitelisted) IP ranges.

Its key is a bpf_lpm_trie_key struct:

struct bpf_lpm_trie_key {
    __u32   prefixlen;
    __u8    data[];
};

struct bpf_lpm_trie_key {
    __u32   prefixlen = 24;  
    __u8    data[4] = {192, 168, 1, 0};    
};

struct bpf_lpm_trie_key {
    __u32 prefixlen = 32;
    __u8  data[16]  = {
        0x20, 0x01, 0x0d, 0xb8,
        0x00, 0x00, 0x00, 0x00,
        0x00, 0x00, 0x00, 0x00,
        0x00, 0x00, 0x00, 0x00
    };
};

But this is just a rather complex key, whereas the value in this key-value pair can be arbitrary and may be used to enforce different logic in your program (e.g., 1 for allowed, 0 for blocked).

So, what’s so special about this eBPF map?

The cool thing is that this eBPF map internally builds a trie, and key lookups work by walking that trie to perform longest prefix matching.

Here’s an image to illustrate this structure.

In other words, this structure is perfect for firewall application, as the user can simply blacklist (or whitelist) whole IP ranges and this eBPF map will tell us whether the client IP is within a certain IP range (or not), allowing us to filter packets accordingly.

Whether we then block or allow network packets based on a match is entirely up to the eBPF program’s logic.

Without further ado, let’s take a look at how this works in practice.

We define our BPF_MAP_TYPE_LPM_TRIE eBPF map type:

struct {
    __uint(type, BPF_MAP_TYPE_LPM_TRIE);
    __type(key, struct ipv4_lpm_key);
    __type(value, __u32);
    __uint(map_flags, BPF_F_NO_PREALLOC); 
    __uint(max_entries, 65535);
} blocked_ips SEC(".maps");

This eBPF map is then populated from the user space program (lab/main.go), which basically just means converting the IPs provided in the input to the format that this eBPF map expects (prefixlen and data):

var blockedIPs   string
flag.StringVar(&blockedIPs, "blocked-ips", "", "Comma-separated IP/mask (192.168.23.3/32, 228.13.0.0/16)")
...
// Build the keys for the BPF_MAP_TYPE_LPM_TRIE eBPF Map
// e.g. 127.0.0.1/32 -> { Prefixlen: 32, Data: 16777343} 
// Where the:
// - 'Prefixlen' is the prefix length in bits (e.g., /32, /24).
// - 'Data' is the IP converted to the integer
keys, err := buildIPv4LPMKeys(blockedIPs)
if err != nil {
  log.Fatalf("blocked-ips error: %v", err)
}
...
// Add blocked CIDRs/LPM Trie keys into the eBPF map
// Doesn't matter which prefix the captured IP will match (as long as it does match we need to block it)
for _, key := range keys {
  if err := objs.xdpMaps.BlockedIps.Put(&key, uint32(1)); err != nil {
    log.Fatalf("error adding CIDR to allow list: %s", err)
  }
}

In this implementation, the map value actually doesn’t matter (we simply set it to 1); all we care about is whether the IP exists in the blacklist. And if the lookup returns NULL, the client isn’t blocked, so the packet is allowed to pass.

With that covered, you should have a pretty good intuition how can we now fit this into our eBPF firewall implementation.

Implementation Breakdown

The only difference that we have compared to packet rate-limiting program is now to perform a lookup against the BPF_MAP_TYPE_LPM_TRIE eBPF map with the prefix.

...
__u32 src = bpf_ntohl(ip->saddr); 

struct ipv4_lpm_key key = {
  .prefixlen = 32,
  .data = src,
};

int *blocked = bpf_map_lookup_elem(&blocked_ips, &key);
if (blocked && *blocked) {
  return XDP_DROP;
}
...

Here, prefix (/32) is just hardcoded, because a single IP represent "a range with a single IP".

And with this simple trick of using BPF_MAP_TYPE_LPM_TRIE we already created a pretty powerful layer 4 firewall that filters network packets based on the client IP but allowing one to blacklist whole IP ranges.

Let's see it in action.

We could demonstrate this with simple ICMP pings—just like in the ICMPv6 rate-limiting example—but let’s take it one step further.

First, start an HTTP server on the server node (server tab):

python3 -m http.server

Then, from either the attacker or client node (attacker or client tabs), try accessing it:

curl http://172.16.0.10:8000

You’ll notice that both nodes can successfully reach the HTTP server, even though ideally the attacker shouldn’t be able to reach it.

Therefore, let’s build and run our eBPF XDP firewall. Open another server tab, navigate to the /lab directory, and run:

go generate
go build
sudo ./xdp -i eth0 --blocked-ips 192.168.178.10/24 # <- this is the attacker subnet

Now curl the HTTP server again—you’ll see that the attacker is blocked. Success ✅

That said, for pure L4 filtering—IP, ports, protocol, and some advanced matching—eBPF is easily the most performant option. But I believe the transition will still be slow: eBPF expertise is rare, and migration is best done in batches—if you do need it, start by replacing a small subset of features with XDP and then expand as your team’s skills grow.

I will leave it at that - congrats you've came to the end of this tutorial 🎉

In the next tutorial, we take a look at different XDP Load balancing solutions, starting with XDP NAT Load Balancer implementation.