XDP without the headache: managing 100 rules without reloading the kernel

Managing XDP rules at scale has traditionally posed a critical challenge: each configuration change forced administrators to reload the entire XDP program, introducing downtime windows and race conditions. In 2026, the paradigm has shifted—modern architectures allow you to deploy up to 100 XDP rules (or more) with zero kernel reload, dynamically updating filtering policies through BPF maps while packets flow uninterrupted. This article dissects the technical mechanics, compares traditional versus map-driven approaches, and demonstrates how stateless XDP combined with stateful nftables delivers both performance and operational flexibility for high-throughput environments.

Traditional XDP workflows embed rule logic directly into the eBPF bytecode: each new ACL entry or rate-limit adjustment requires recompiling the C source, verifying the bytecode through the kernel verifier, and attaching the updated program to the network interface. During the brief detach-and-reattach window, packets may bypass filtering or trigger unexpected drops. For production game servers, SaaS APIs, or edge proxies handling millions of packets per second, even a 50-millisecond reload gap translates to thousands of unfiltered packets—an unacceptable risk during active DDoS mitigation.

Why Map-Driven XDP Rules Eliminate Reload Overhead

The core innovation lies in separating policy logic from policy data. A single, persistent XDP program remains attached to the interface indefinitely; it reads filtering instructions from one or more BPF maps updated in real time from user space. The kernel verifier validates the program once at load time, then the same bytecode interprets hundreds of rules stored as key–value pairs in hash maps or arrays.

PAKKT.io exemplifies this architecture: the PAKKT Engine is a monolithic XDP program capable of enforcing up to 256 simultaneous rules per interface. Each rule entry in the pakkt_rules map encodes:

• Port range (start, end) or wildcard for any port.
• Protocol: TCP, UDP, ICMP, or any IP protocol number.
• Action: block (XDP_DROP), rate_limit (stateless token bucket per source IP), or allow_only (whitelist mode).
• Per-port PPS cap and global PPS ceiling to prevent resource exhaustion.
• Packet size constraints (min/max) to drop malformed or oversized datagrams early.

User-space agents (written in Go, Rust, or C) invoke bpf_map_update_elem via libbpf or Cilium's eBPF library to insert, modify, or delete rules without touching the loaded program. The XDP hook sees the changes on the very next packet lookup—no system call latency beyond the map operation itself, typically sub-microsecond on modern CPUs.

Performance Trade-Offs: Hash Maps vs. Arrays

Choosing the right map type affects both throughput and memory footprint:

Map Type	Lookup Complexity	Max Entries	Use Case
BPF_MAP_TYPE_HASH	O(1) average, hash collisions possible	Kernel-limited (often 1M+)	Sparse rule sets, IP blacklists
BPF_MAP_TYPE_ARRAY	O(1) guaranteed, index-based	Pre-allocated, fixed size	Dense rule IDs, ordered evaluation
BPF_MAP_TYPE_LRU_HASH	O(1) with automatic eviction	Fixed, least-recently-used purge	Per-IP rate-limit state

For rule storage, hash maps offer flexibility; for rate-limit counters tracking thousands of source IPs, LRU hashes bound memory while retaining hot entries. The PAKKT Engine combines both: a hash map for rule definitions and an LRU hash for per-IP packet timestamps.

Architectural Blueprint: Single XDP Program, Multi-Rule Engine

A canonical map-driven XDP program follows this control flow:

SEC("xdp")
int pakkt_engine(struct xdp_md *ctx) {
    void *data_end = (void *)(long)ctx->data_end;
    void *data     = (void *)(long)ctx->data;
    struct ethhdr *eth = data;
    if ((void *)(eth + 1) > data_end) return XDP_DROP;

    struct iphdr *ip = (void *)(eth + 1);
    if ((void *)(ip + 1) > data_end || ip->version != 4) return XDP_PASS;

    __u8 proto = ip->protocol;
    __u16 dport = 0;
    if (proto == IPPROTO_TCP || proto == IPPROTO_UDP) {
        struct udphdr *l4 = (void *)ip + (ip->ihl * 4);
        if ((void *)(l4 + 1) > data_end) return XDP_DROP;
        dport = bpf_ntohs(l4->dest);
    }

    // Iterate rules map
    for (__u32 i = 0; i < MAX_RULES; i++) {
        struct rule_entry *rule = bpf_map_lookup_elem(&pakkt_rules, &i);
        if (!rule || !rule->enabled) continue;

        if ((rule->proto == proto || rule->proto == 0) &&
            (dport >= rule->port_start && dport <= rule->port_end)) {
            switch (rule->action) {
                case ACTION_BLOCK:   return XDP_DROP;
                case ACTION_RATE_LIMIT: return check_rate_limit(ip->saddr, rule);
                case ACTION_ALLOW_ONLY: return handle_whitelist(ip->saddr, rule);
            }
        }
    }
    return XDP_PASS;
}

Key observations:

• The loop bound MAX_RULES must be known at compile time for the verifier, but the content of each slot updates dynamically.
• Disabled rules (flag bit) occupy map space but contribute zero runtime cost—early continue skips evaluation.
• Protocol and port wildcards (0 or MAX_U16) match any packet, enabling coarse-grained policies.
• Sub-functions like check_rate_limit read a second map keyed by source IP, enforcing per-IP PPS caps via token buckets or sliding windows.

Dual-Layer Blacklist: XDP Map + nftables Synchronization

While XDP excels at line-rate drops, some scenarios demand stateful inspection—SYN flood mitigation, connection tracking, or per-flow byte limits. PAKKT Integrations orchestrate both layers:

1. XDP BPF map: hash map of blocked IPs (IPv4/IPv6). Lookup overhead ~10 ns, executed before any socket allocation.
2. nftables inet pakkt table: isolated ruleset with ct state, tcp flags, and limit statements. Zero conflict with Docker's nat table, fail2ban's filter table, or iptables-persistent.

When an IP is blacklisted via the PAKKT panel or API, the Go agent performs two atomic operations:

bpf_map_update_elem(blacklist_fd, &ip_key, &dummy_val, BPF_ANY);
system("nft add element inet pakkt blacklist_v4 { 203.0.113.42 }");

Packets from that IP hit XDP_DROP in the NIC driver; any that slip through (e.g., during the microsecond update window) meet the nftables DROP rule in the kernel's netfilter hooks. This redundancy closes race conditions without requiring complex locking.

Operational Workflow: Deploying and Updating 100 XDP Rules

Practical deployment splits into three phases: initial load, runtime updates, and monitoring.

Phase 1: Compile and Attach the XDP Program

# Compile once with Clang + LLVM (requires kernel headers)
clang -O2 -g -target bpf -D__TARGET_ARCH_x86 \
  -I/usr/include/bpf -c pakkt_engine.bpf.c -o pakkt_engine.bpf.o

# Attach to interface (XDP_FLAGS_UPDATE_IF_NOEXIST prevents double-load)
ip link set dev eth0 xdp obj pakkt_engine.bpf.o sec xdp

From this point forward, the XDP program remains resident. Verify attachment:

ip link show eth0 | grep xdp
# Output: prog/xdp id 42 tag a1b2c3d4e5f67890

Phase 2: Populate Rules via BPF Map

Use bpftool for manual insertion or integrate libbpf into your orchestration daemon:

# Example: block TCP port 25565 (Minecraft)
bpftool map update name pakkt_rules key 0 0 0 0 value \
  1 6 25565 25565 1 0 0 0

# Legend: enabled=1, proto=6(TCP), port_start=25565, port_end=25565, action=1(BLOCK)

In production, the PAKKT agent exposes a gRPC or REST endpoint; the panel pushes JSON payloads that the agent translates into bpf_map_update_elem calls. A rule updating 10,000 blacklist IPs completes in under 50 milliseconds on a mid-tier Xeon, with zero packet loss.

Phase 3: Real-Time Metrics and Audit

The XDP program increments per-rule counters (packets matched, packets dropped, bytes processed) in a separate BPF map. A user-space collector polls every 30 seconds and ships metrics to TimescaleDB or Prometheus:

bpftool map dump name rule_stats
# Output:
# key: 00 00 00 00  value: 3f 42 00 00 00 00 00 00  (rule 0: 17215 packets)

The PAKKT Blog documents integration with Grafana for GeoIP heatmaps, top-talker tables, and per-port PPS graphs—all derived from XDP and nftables counters without agent overhead.

Scaling Beyond 100 Rules: Hash Map Sharding and Priority Queues

While 256 rules suffice for most edge cases, environments protecting multi-tenant Kubernetes clusters or carrier-grade NAT gateways may require thousands of policies. Two strategies extend capacity:

1. Multi-Map Sharding

Partition rules by protocol or port range into separate maps. The XDP program checks the TCP map first, then UDP, then ICMP, short-circuiting on the first match. Total lookup cost remains O(log N) with binary search or O(1) with perfect hashing, but each map stays under verifier complexity limits.

2. User-Space Rule Compilation

Generate optimized BPF bytecode snippets for high-priority rules (e.g., emergency blacklists) and use bpf_tail_call to chain into specialized sub-programs. The main XDP program becomes a dispatcher; tail-called programs inherit the packet context and can enforce complex logic without bloating the root function's instruction count.

Both techniques preserve the zero-reload guarantee: maps and tail-call arrays update independently while the dispatcher remains attached.

Complementary Stateful Filtering with nftables

XDP's stateless nature caps its applicability—rate-limiting is per-packet, not per-flow; there is no SYN/ACK validation or connection tracking. The nftables layer fills these gaps:

nft add table inet pakkt
nft add chain inet pakkt input { type filter hook input priority 0\; policy accept\; }

# SYN flood mitigation: max 50 new TCP connections/sec per source
nft add rule inet pakkt input tcp flags syn ct state new \
  meter synflood { ip saddr timeout 10s limit rate 50/second } accept

# Drop invalid TCP flag combinations
nft add rule inet pakkt input tcp flags \& \(fin\|syn\|rst\|psh\|ack\|urg\) == 0x0 drop

# Per-connection byte rate limit (1 Mbps burst)
nft add rule inet pakkt input ct state established \
  limit rate over 1 mbytes/second burst 512 kbytes drop

Because nftables rules execute after XDP (in the kernel's network stack), any packet that XDP allows enters conntrack and the stateful meter logic. Combining both layers yields defense in depth: XDP blocks known-bad IPs and oversized packets at line rate; nftables enforces nuanced policies on the remaining traffic.

Avoiding Configuration Conflicts

Docker, fail2ban, and legacy iptables-persistent manipulate the filter, nat, and mangle tables in the ip (IPv4) or ip6 families. By creating a dedicated inet pakkt table—which applies to both IPv4 and IPv6—you sidestep rule collisions. The PAKKT agent never touches other tables; uninstalling PAKKT is a single nft delete table inet pakkt command.

Observability: Tracing Rule Hits Without Performance Penalty

Debugging which XDP rule matched a specific packet traditionally required recompiling with bpf_printk, a technique that floods the kernel ring buffer and degrades throughput. Modern observability relies on:

• Per-rule counter maps: increment atomically via __sync_fetch_and_add in the XDP program; read from user space without syscall serialization.
• BPF ring buffers (BPF_MAP_TYPE_RINGBUF): submit sampled packet metadata (source IP, port, rule ID, timestamp) to a lock-free circular buffer polled by the agent.
• eBPF tracepoints: attach a secondary BPF program to xdp:xdp_exception or custom USDT probes, capturing drop events with full context.

The PAKKT dashboard aggregates these streams into real-time alerts—"Rule 42 (UDP/19132) dropped 12,000 pps from AS64512"—without the agent ever parsing raw packet payloads or introducing backpressure on the XDP fast path.

Security Considerations: Map Pinning and Privilege Separation

BPF maps persist in the kernel as long as at least one file descriptor references them. Pinning a map to the BPF filesystem (/sys/fs/bpf) lets multiple user-space processes share the same ruleset:

bpftool map pin name pakkt_rules /sys/fs/bpf/pakkt_rules
chmod 600 /sys/fs/bpf/pakkt_rules
chown pakkt-agent:pakkt-agent /sys/fs/bpf/pakkt_rules

Only the agent UID can update the map; monitoring daemons open it read-only. This privilege separation prevents accidental or malicious rule corruption from other services. The PAKKT agent further employs garble obfuscation (Go build-time symbol mangling) and mTLS with certificate pinning, ensuring that only authenticated panel requests trigger map updates.

For high-security environments, enable kernel lockdown mode (lockdown=confidentiality) and sign XDP programs with CONFIG_BPF_JIT_ALWAYS_ON + IMA/EVM to prevent runtime code injection.

Conclusion

Shifting from monolithic, reload-dependent XDP programs to map-driven architectures unlocks true zero-downtime rule management. A single, verifier-approved XDP program interpreting dynamic BPF maps can enforce hundreds of policies—protocol filters, rate limits, blacklists—updated in microseconds without packet loss. Paired with stateful nftables for connection tracking and byte-rate enforcement, this dual-layer approach delivers both line-rate performance and operational flexibility. The elimination of reload overhead transforms DDoS mitigation and access control from a disruptive maintenance task into a continuous, real-time operation.

FAQ

Can I update XDP rules from multiple processes simultaneously without race conditions?

Yes, if each process operates on distinct map keys or uses the BPF_F_LOCK flag (requires kernel 5.1+) for atomic compare-and-swap on individual entries. For coordinated updates across keys, implement user-space locking (e.g., flock on the pinned map path) or funnel all writes through a single orchestration daemon that serializes bpf_map_update_elem calls.

How does map-driven XDP compare to nftables sets for IP blacklists?

XDP hash map lookups occur in the NIC driver before any skb allocation, typically under 10 nanoseconds per packet, whereas nftables sets execute in netfilter hooks after the kernel has begun processing the packet—still fast (sub-microsecond) but with higher baseline overhead. For millions of packets per second, XDP's earlier interception prevents CPU cache pollution and socket memory exhaustion. Use nftables sets for stateful policies (conntrack, rate-limit per flow) that XDP cannot express.

What happens if the XDP program exceeds the verifier's instruction limit when iterating 256 rules?

The verifier enforces a complexity limit (historically 1 million instructions, tunable via BPF_COMPLEXITY_LIMIT_INSNS). If a loop bound of 256 pushes you over, reduce the inline logic per rule iteration: move complex checks into helper functions marked __always_inline selectively, or split the rule set into multiple maps and use tail calls to chain sub-programs. Modern kernels (5.10+) also support bounded loops without unrolling, lowering instruction count significantly.