PROXY protocol Wrapper
by Novogodnich
PROXY protocol Wrapper lets a Minecraft server read real client addresses from HAProxy PROXY protocol v2 headers sent by a proxy in front of it.
What it does
Behind a reverse proxy, load balancer or CDN, the server normally sees the proxy's address instead of the player's. The mod injects custom handlers into the Netty pipeline during the handshake, so the real player IP is forwarded and used by the server. Bans, whitelists and logs then record the actual client address rather than 127.0.0.1 or the proxy's own IP. The mod works with HAProxy, Velocity, cloud mitigation providers and DDoS protection layers that send PROXY protocol v2.
Setup needs two parts. The upstream proxy or load balancer has to have PROXY protocol v2 enabled on the Minecraft backend port, for example through a send-proxy-v2 option in its HAProxy configuration. The server side only needs this Fabric mod, which is server-side only, so players join without installing anything. Files are published for Fabric only, for the 1.21.11 and 26.3 game versions, with 1.1 for 26.3 as the latest build, released 2026-10-13. The code is under the GNU General Public License v3.0 or later, so the project is open source.
Key features
Accurate IP forwarding
Real client addresses replace the proxy's address for connections that arrive with a PROXY protocol v2 header.
Dynamic pipeline handling
Handlers are added to the channel pipeline during the handshake phase, so no manual Netty changes are needed.
Native Netty integration
The required HAProxy codecs are shaded into the mod, and pipeline race conditions that cause NoSuchElementException are fixed.
Ban and whitelist support
Logs, bans and whitelist checks use the restored player IP, instead of the proxy address shared by all connections.
Compatibility
Latest build for each game version and loader.
Only full game releases are shown. This mod publishes no snapshot builds.
How it compares
HAProxyCompat is also a server-side Fabric mod for the same purpose, with Fabric and NeoForge files for 1.21 – 26.3 under the GNU General Public License v3.0 or later, and it is open source. NG HaProxy Support is a Forge-only server-side option for 1.20.1, released under the MIT License, and it is not open source. IP Whitelist (Fabric) is server-side only and open source under the GNU General Public License v3.0 only, with files for 1.21.10 – 1.21.11, but it does not forward IPs through PROXY protocol v2.
| Mod | Loaders | Game versions | Environment | Updated |
|---|---|---|---|---|
| PROXY protocol Wrapper | Fabric | 1.21.11 – 26.3 | Server-side only | 2026-10-13 |
| HAProxyCompat | Fabric and NeoForge | 1.21 – 26.3 | Server-side only | 2026-09-24 |
| NG HaProxy Support | Forge | 1.20.1 | Server-side only | 2026-03-15 |
| IP Whitelist (Fabric) | Fabric | 1.21.10 – 1.21.11 | Server-side only | 2026-01-29 |
Questions
Does PROXY protocol Wrapper need to be installed on player clients?
Which game versions does PROXY protocol Wrapper support?
What must be configured on the proxy side?
In the catalog
PROXY protocol Wrapper is one of 8,499 Technology mods on ModsFinder, and one of 4,201 Technology mods for Fabric. 8,071 mods support Minecraft 26.3.
Similar mods
What the author says
A lightweight Fabric server-side mod that adds native support for the HAProxy PROXY protocol v2. It injects custom handlers into the Netty pipeline to accurately forward real player IPs behind reverse proxies, CDNs, or DDoS protection layers (like HAProxy, Velocity, or cloud mitigation providers).
Official listing
- Modrinth page
- modrinth.com/mod/fabric-proxy-wrapper
- Owner
- Novogodnich
- Published
- 2026-07-08
- Updated on Modrinth
- 2026-10-13
- Facts verified
- 2026-10-15