HAProxyCompat

# HAProxyCompat **Stop seeing `127.0.0.1`. See who's actually connecting.** When your Minecraft server sits behind a reverse proxy like FRP, nginx, HAProxy, or Traefik, every player looks like they're connecting from the proxy. Bans, logs, and IP tools all see the proxy's address instead of the real one. HAProxyCompat fixes that. It reads the PROXY protocol header (v1 and v2) that your proxy sends, pulls out the real client IP, and hands it to Minecraft as if the player connected directly. The result: real IPs in your logs, working IP bans, and accurate geolocation. No client mod, no extra setup for players. > **Heads up:** this is often not optional. Once your proxy starts sending PROXY headers, a vanilla > server has no idea what those extra bytes are and chokes on them, so players can't connect and the > server just looks offline in the client. Installing HAProxyCompat is what makes the connection work > at all. The real-IP part is the bonus. - **For:** NeoForge and Fabric dedicated servers. Pick the jar that matches your loader and MC version. - **Needs:** Nothing else. The one Netty piece Minecraft doesn't ship is tucked inside the jar for you, so it stays a single drop-in file. ## Quick start 1. Drop the right jar into your server's `mods/` folder. 2. Tell your proxy to send the PROXY header (see (#point-your-proxy-at-it)). 3. If your proxy runs on a different machine, add its IP to `trusted_proxies` (see below). 4. Start the server. Done. Out of the box it works for a proxy running on the same machine as the server. That's the only case that needs zero config. ## Configure it **NeoForge** — settings live in `config/haproxycompat-common.toml`. Edit them while the server is running and they apply instantly, no restart needed. **Fabric** — settings live in `config/haproxycompat.json`. Restart required for changes to take effect. ```toml # NeoForge (haproxycompat-common.toml) enabled = true require_proxy_protocol = true trusted_proxies = log_connections = false kick_message = "This server requires a proxy connection." ``` ```json // Fabric (haproxycompat.json) { "enabled": true, "requireProxyProtocol": true, "trustedProxies": , "logConnections": false, "kickMessage": "This server requires a proxy connection." } ``` ### Settings - **enabled** — master on/off switch. - **require\_proxy\_protocol** — `true`: only allow connections with a valid PROXY header from a trusted proxy. Use when the Minecraft port is reachable only through your proxy. `false`: also allow plain direct connections through untouched. - **trusted\_proxies** — IP addresses / CIDR ranges that may send PROXY headers. Only these are believed; anyone else sending a PROXY header is dropped. Add your proxy's address here. - **log\_connections** — print one line per connection decision. Great for debugging, noisy once working. - **kick\_message** — message shown in the disconnect screen when a client connects directly and `require_proxy_protocol` is true. Without this, clients would hang until a read timeout fires. ### Why `trusted_proxies` matters The PROXY header is just text the connecting side sends. Anyone who can reach your server port directly could send a fake one and claim to be any IP they like, which would let them dodge bans or frame someone else. To stop that, HAProxyCompat only believes the header when it comes from an address you've listed in `trusted_proxies`. Everyone else is ignored or dropped. Two simple rules: 1. **Add your proxy's real address.** The default list only trusts the local machine. If your proxy lives on another host or subnet, its headers get rejected until you add its IP or CIDR here. 2. **Lock the door behind the proxy.** Firewall the Minecraft port so only your proxy can reach it. That way a forged header can never arrive in the first place. If the list is empty, nobody is trusted and no real IPs get applied. The server logs a warning at startup so you're not left guessing. ## Point your proxy at it HAProxyCompat only listens. Your proxy still has to be told to **send** the header: - **HAProxy:** add `send-proxy` (v1) or `send-proxy-v2` to the `server` line. - **nginx (stream):** set `proxy_protocol on;` in the `server` block. - **FRP:** set `transport.proxyProtocolVersion = "v2"` on the proxied service. - **Traefik:** enable `proxyProtocol` on the TCP service's server. ## Under the hood Every new connection first meets a small gatekeeper (`ProxyProtocolDetector`) that sits at the very front of the network pipeline. It peeks at the opening bytes to see if a PROXY header is there, and checks whether the connection came from a trusted proxy. Then it decides what to do: | From a trusted proxy? | Has a PROXY header? | What happens | |---|---|---| | Yes | Yes | Decode the header and apply the real client IP | | Yes | No | Drop it (or let it through, if `re