NG Proxy Support

Adds HAProxy PROXY protocol support to your Minecraft Forge server.

See real player IP addresses when your server is behind a proxy like Velocity, TCPShield, FRP, Nginx, or any other HAProxy-compatible reverse proxy.

Features

HAProxy PROXY Protocol v1/v2 — Full support for both protocol versions
Real IP Resolution — Players connecting through a proxy will show their real IP in server logs, bans, and plugins
Hybrid Mode — Supports both proxied and direct connections simultaneously
Fail-Closed Security — Connections from unknown IPs are automatically rejected, preventing proxy bypass attacks
CIDR Notation — Whitelist entire subnets (e.g. 192.168.0.0/16)
TCPShield Integration — Automatically fetch and whitelist TCPShield server IPs
Hot-Reload Config — Reload configuration without restarting the server
Status Command — View current configuration and connection stats in-game
Connection Logging — Log real player IPs and proxy IPs to a dedicated log file

Commands

Command	Permission	Description
`/proxyprotocol reload`	OP Level 4	Reload config without restart
`/proxyprotocol status`	OP Level 4	View current config and active rules

Configuration

Config file: config/proxy_protocol_support.json

{
  "enableProxyProtocol": true,
  "proxyServerIPs": ["127.0.0.1"],
  "directAccessIPs": ["127.0.0.1", "192.168.0.0/16"],
  "whitelistTCPShieldServers": false,
  "logConnections": true
}

Option	Description
`enableProxyProtocol`	Enable/disable the mod entirely
`proxyServerIPs`	IPs of your proxy servers (Velocity, HAProxy, etc.) — PROXY headers will only be accepted from these IPs
`directAccessIPs`	IPs allowed to connect directly without PROXY headers
`whitelistTCPShieldServers`	Auto-fetch TCPShield IPs and add them to proxy whitelist
`logConnections`	Log real IP and proxy IP to `logs/proxy_connections.log`

How It Works

Player → Proxy (Velocity/HAProxy/FRP) → Forge Server (with NG Proxy Support)
                                          ↓
                                   Reads PROXY header
                                   Extracts real IP
                                   Sets player address

Your proxy sends a PROXY protocol header with the real client IP
NG Proxy Support intercepts incoming connections and reads the header
The player's address is set to their real IP instead of the proxy IP
All server logs, ban systems, and plugins see the correct IP

Security Model

NG Proxy Support uses a fail-closed model:

✅ Connections from proxyServerIPs → PROXY header is read, real IP is extracted
✅ Connections from directAccessIPs → Allowed without PROXY header
❌ Connections from any other IP → Automatically rejected

This prevents players from bypassing your proxy to connect directly and spoof their IP.

Setup Guide

With Velocity

Install NG Proxy Support on your Forge server
Enable PROXY protocol in Velocity's velocity.toml:

   [advanced]
   haproxy-protocol = true

Add your Velocity server IP to proxyServerIPs in the mod config
Restart both servers

With HAProxy / Nginx / FRP

Configure your reverse proxy to send PROXY protocol headers
Add the proxy IP to proxyServerIPs
Restart the Forge server

Requirements

Minecraft 1.20.1
Forge 47.x
Java 17+
Server-side only (no client mod needed)

NG HaProxy Support