How XDP filtering works
How OpenShield-XDP drops attack traffic at the NIC driver hook: the packet path, baseline spike detection, the eBPF maps, and why false positives stay low.
Last updated
On this page
OpenShield-XDP drops attack traffic inside your server's network card path, before the kernel spends any real work on it. This page walks the packet path, how detection fires, and why legitimate traffic rarely gets caught.
The path of a packet
Without OpenShield, every arriving packet travels the full Linux network stack: the kernel allocates a socket buffer, parses headers, runs netfilter, and only then can anything drop it. A flood large enough to exhaust that pipeline takes the whole server down with it.
With OpenShield, an eBPF program attaches to the XDP hook in the NIC driver — the earliest
point a packet can be handled. Verdicts happen there, and attack packets are dropped
(XDP_DROP) before a socket buffer is ever allocated. That is why mitigation runs at line
rate with sub-millisecond overhead.
NIC
│
▼
XDP hook (eBPF program — earliest point in the stack)
│─ source on whitelist map ─────────────► pass
│─ source on ban map ───────────────────► XDP_DROP
│─ attack active and packet offending ──► XDP_DROP
│
▼ pass
kernel network stack ──► socket buffer ──► your application
The console reports which mode the program runs in (system.xdp_mode — native driver or
generic fallback) and which interface it guards (system.interface).
How detection fires
The agent continuously learns a traffic baseline (attack.baseline_pps). When the current
packet rate (attack.current_pps) exceeds baseline × a spike factor
(attack.spike_factor), the agent flips into mitigation (attack.state) and starts
dropping offending packets. The threshold it crossed is reported as
attack.spike_pps_threshold.
During mitigation, offending sources are banned with an expiry (bans.active_count,
bans.recent), and brand-new sources can be refused outright
(attack.new_sources_blocked).
Where the state lives
All state sits in eBPF maps; the metrics payload reports entry counts per map.
| Map | Holds |
|---|---|
config | The active mitigation settings |
whitelist | Sources that always pass |
ip_stats | Per-source packet counters |
ban | Banned sources and their expiry |
global_stats | Global packet and drop counters |
baseline | The learned traffic baseline |
events | The recent event ring buffer |
Why false positives stay low
Two mechanisms protect real users. The whitelist map is checked first, so sources you trust always pass. And on game profiles, per-player buckets track each source against its own budget, so one busy player doesn't look like a flood. Tune this per workload — see Tuning profiles.