Minecraft-XDP-eBPF: Fast Kernel L7 DDoS Defense for Java Servers

Running a public Minecraft server means dealing with rogue ping spams, fake handshake floods, and bot armies designed to stall your main tick loop. Minecraft-XDP-eBPF solves this by inspecting and filtering malicious game packets directly inside the Linux kernel before they ever reach your Java runtime.

What Layer 7 Floods Do to Your Game Server

Most network firewalls operate purely on IP addresses and basic port rules. They can stop massive generic UDP or raw TCP packet floods, but they stumble the moment an attacker sends traffic that mimics real players.

When someone hits your port with thousands of crafted handshake packets, status requests, or invalid VarInt payloads, Netty has to parse all of it. Your server burns valuable CPU cycles decoding bad packets, allocating memory buffers, and tearing down invalid sockets. TPS plummets, players begin lagging out, and your server console fills with connection timeout spam.

And that's why normal software firewalls fall short here.

If you've ever checked our Minecraft Server List to see massive networks like Donutsmp handling tens of thousands of simultaneous users, you know that keeping latency crisp under pressure is vital. Standard Java-level mitigation simply can't keep up once bad connections overwhelm the socket backlog.

How eBPF and XDP Handle Packet Filtering

The Outfluencer/Minecraft-XDP-eBPF project takes a fundamentally different route by using eXpress Data Path (XDP) and extended Berkeley Packet Filter (eBPF). Instead of waiting for packets to travel through the Linux network stack and into userspace Java applications, XDP attaches directly to the network interface driver level.

The core filter logic is written in C and compiled to eBPF bytecode. When a packet arrives on your network card, the kernel executes this sandboxed bytecode in a fraction of a microsecond. If the packet fails validation, the filter issues an XDP_DROP action. The malicious packet is wiped from memory before your operating system allocates socket buffers, saving virtually all CPU overhead.

To control this filter, the project couples the C eBPF program with a high-performance loader written in Rust. All active rate-limiting windows and verified connection states stay managed directly in-kernel via bpf_timer routines, meaning packet tracking doesn't depend on slow userspace roundtrips.

Key Defense Features

This repository (currently sitting at 217 stars on GitHub) delivers specialized defenses targeted specifically at Minecraft Java Edition protocol quirks across versions 1.8 through 26.3.

• Deep Protocol Inspection: The eBPF program verifies VarInt encoding, handshake structures, status queries, ping requests, and login packets. Packets carrying malformed lengths or illegal protocol states get discarded on the spot.
• Driver-Level Dropping: By dropping bad packets with zero-copy efficiency at the driver stage, your server preserves network bandwidth and system RAM.
• Configurable SYN Throttling: Built-in rate limiting restricts how many SYN packets a single source IP can initiate in a rolling window. By default, it permits 10 SYNs per 3 seconds per IP address.
• Prometheus Metrics Export: You can expose real-time packet processing counts and drop statistics straight to Prometheus to monitor attack activity in Grafana dashboards.

It acts like a bouncer standing outside your building rather than inside your lobby.

System Prerequisites and Compatibility

Because this project depends on modern Linux kernel capabilities like bpf_timer, you need a host running Linux kernel 5.15 or newer. The filter specifically protects IPv4 traffic and targets the standard Minecraft port 25565 by default (though port ranges are configurable).

Before compiling from source or running the binary, make sure your Linux system has the necessary build dependencies and a recent Clang/LLVM toolchain (CI builds test with LLVM 21):

sudo apt update
sudo apt install -y gcc-multilib wget gnupg software-properties-common git libbpf-dev

If you're building the project yourself, fetch the current LLVM toolchain installer:

wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 21 all

Installation and Running the Filter

You've two choices for getting started: pulling prebuilt binaries directly from GitHub releases or compiling the repository using Rust and Clang.

Method A: Using Precompiled Releases

The easiest route is downloading the compiled binary and eBPF object file directly from the GitHub releases page (such as release v3.0.7):

1. Grab xdp-loader and minecraft_filter.o from the official release assets.
2. Place both files in the same directory on your dedicated Linux server.
3. Make the loader executable: chmod +x xdp-loader

Method B: Building From Source

If you prefer building the source yourself using the stable Rust toolchain:

git clone https://github.com/Outfluencer/Minecraft-XDP-eBPF.git
cd Minecraft-XDP-eBPF
./build.sh

The build script compiles both the eBPF C program and the Rust loader. You can find the resulting binary located at target/release/xdp-loader.

If you want to verify that the protocol parser works properly on your environment, run the integrated test suite:

cargo test

This runs Rust unit tests and executes native C test suites with AddressSanitizer and UndefinedBehaviorSanitizer to ensure packet parsing memory safety.

Attaching the Firewall to Your Network Interface

To run the firewall, execute the loader with root privileges and pass your network interface name (such as eth0 or ens3):

sudo ./target/release/xdp-loader eth0

Keep in mind that the loader runs as a persistent userspace process. If you close or kill the loader process, the firewall unloads and removes the XDP filter from your interface.

Configuring Ports, Throttles, and Metrics

When you start the loader for the first time, it automatically generates a default config.toml configuration file in the working directory. You can also supply a custom configuration path using the --config <path> argument.

Inside config.toml, the [filter] section lets you customize your port ranges and rate limits:

[filter]
start_port = 25565
end_port = 25565
hit_count = 10
hit_count_reset_secs = 3

If you run multiple game instances or custom backend proxies, match your port range here. If you need help structuring your ports or server files, our Server Properties Generator makes configuring vanilla and modified server settings straightforward.

To turn on the Prometheus metrics collector, configure the [metrics] table:

[metrics]
enabled = true
addr = "127.0.0.1:1999"

Once enabled, you can scrape live filter metrics directly at http://127.0.0.1:1999/metrics.

Common Pitfalls and Operational Gotchas

While XDP filtering offers incredible speed, there are specific quirks every server administrator should understand before deploying it into production.

First, verify your network interface driver support. Most modern virtual machines and bare-metal enterprise network cards (like Intel igb/ixgbe or Mellanox) support native driver-level XDP. If your driver doesn't support native XDP, the kernel falls back to generic XDP mode. Generic mode still protects your Java application, but it processes packets slightly later in the kernel stack.

Second, remember that this filter covers IPv4 traffic on specified TCP port ranges. So it isn't a replacement for global BGP-level volumetric mitigation if an attacker floods your uplink with 50 Gbps of raw UDP traffic. What it excels at is stopping protocol-level CPU exhaustion attacks that bypass standard firewalls.

Third, keep your SYN throttle settings reasonable. Setting hit_count too low might temporarily throttle players who disconnect and reconnect rapidly due to flaky home Wi-Fi connections.

How to Safely Unload and Revert

Stopping the protection is simple. Here's the thing, because the loader manages attachment state, sending an interrupt signal (such as pressing Ctrl + C in your terminal or sending SIGINT/SIGTERM via systemd) will cleanly detach the XDP program from your network interface.

No kernel modifications persist after stopping the loader, returning your Linux network stack to its normal default packet routing immediately.