PROXY protocol v2 Wrapper
Running a Minecraft server behind a reverse proxy, CDN, or DDoS mitigation layer is standard practice these days. The problem is that once traffic passes through that layer, your server sees the proxy's IP address instead of the actual player's. Every log entry shows 127.0.0.1, every ban hits the wrong address, and your whitelist becomes a guessing game. The PROXY protocol v2 Wrapper is a lightweight Fabric server-side mod built to fix exactly that.
What the PROXY protocol v2 Wrapper Does
At its core, this mod adds native support for the HAProxy PROXY protocol v2 on a Fabric server. Instead of relying on external plugins or fragile workarounds, it injects custom handlers directly into the Netty pipeline during the handshake phase. When a connection arrives carrying the PROXY v2 header, the wrapper reads it, extracts the real client address, and hands that information to the rest of the server stack before normal Minecraft traffic is processed.
The result is simple but transformative: your server logs, ban system, and whitelist all operate on genuine player IPs again. No more 127.0.0.1 entries cluttering your console, and no more accidentally banning your own proxy node.
Native Netty Integration
Because the mod works at the pipeline level, it dynamically updates the channel during the handshake rather than patching higher-level code. This keeps it fast and unobtrusive. The required Netty HAProxy codecs are safely shaded into the jar, so you will not run into dependency conflicts with other mods that bundle their own Netty versions.
Production-Ready Reliability
Early implementations of PROXY protocol support often suffered from pipeline race conditions, throwing NoSuchElementException errors under load. This wrapper addresses those issues directly, making it stable enough for busy public servers where connection spikes are routine. If you have been burned by half-finished proxy fixes before, this one is built with real-world deployment in mind.
Supported Versions and Loader
The mod targets modern Fabric environments. You will need Fabric Loader 0.18.4 or newer and Fabric API 0.159.1+26.3 or above. Supported Minecraft versions are 1.21.11 and 26.3. If you run an older server, check back for updates, as the mod tracks current Fabric releases closely.
For server owners who prefer a frictionless setup, the foxygame.net launcher bundles PROXY protocol v2 Wrapper in its add-on catalog, so you can add it to a compatible Fabric instance without manually hunting down matching builds. The launcher also handles version compatibility checks, which saves time when you are spinning up a fresh proxy-backed server.
How to Install the PROXY protocol v2 Wrapper
Installation is straightforward and takes only a few minutes. Before you begin, make sure your upstream proxy or load balancer is configured to send PROXY protocol v2 headers to the Minecraft backend port. In HAProxy, for example, that means adding send-proxy-v2 to the backend server line.
- Download PROXY protocol v2 Wrapper for Minecraft from the official project page and confirm the file matches your server version.
- Stop your Fabric server completely before making changes.
- Drop the compiled .jar file into your server's mods/ directory.
- Verify that Fabric API is present in the same folder at the required version.
- Start the server and connect through your proxy to confirm real IPs appear in the logs.
If players still show up as the proxy address after installation, double-check that PROXY v2 is enabled on the correct backend port and that no other layer is stripping the header. The mod only reads what the proxy sends, so a misconfigured upstream will still produce loopback addresses.
When Should You Use It?
This mod is essential if you run HAProxy, Velocity with PROXY protocol enabled, or any cloud mitigation provider that forwards connections with PROXY v2 headers. It is equally useful for networks using TCPShield-style DDoS protection, where accurate IP data is critical for moderation. Vanilla-facing servers without a proxy do not need it, and installing it there will not change behavior.
Final Thoughts
Accurate player IPs are not a luxury for a serious Minecraft server; they are a baseline requirement for moderation, security, and fair play. The PROXY protocol v2 Wrapper delivers that with minimal overhead and a clean Fabric-native implementation. Whether you are running a small community server behind HAProxy or a large network with layered mitigation, this add-on restores the visibility you need. Grab it, follow the install steps above, and your logs will finally tell the truth about who is connecting.