Proxy Protocol Support

Running a Minecraft server behind a proxy like HAProxy or TCPShield offers excellent DDoS protection and hides your server's true IP address. However, a common frustration is that all player connections appear to come from the proxy itself, making moderation, logging, and IP-based tools useless. Proxy Protocol Support solves this problem elegantly by enabling your server to read the real player IP from the PROXY protocol header.

What Is Proxy Protocol Support for Minecraft?

Proxy Protocol Support is a lightweight, server-side mod designed for Fabric and Quilt loaders. It implements the HAProxy PROXY protocol, allowing your Minecraft server to accept connections from trusted proxies while still seeing the original player IP addresses. This means you can use powerful external proxy services without losing visibility into who is actually connecting. The mod works seamlessly with Minecraft versions 1.14 through 1.21.10, and likely future releases as well.

Key Features

• Real IP Transparency – Logs, bans, and plugins see the player's actual IP, not the proxy's.
• Hybrid Mode – Accept both proxied connections and direct connections simultaneously, perfect for admins who need local access.
• Secure Default-Deny – Only whitelisted proxy IPs and direct-access IPs are allowed; all others are rejected.
• TCPShield Integration – Automatically fetch and whitelist TCPShield's proxy IPs with a simple config toggle.
• Lightweight and Server-Side Only – No client installation required, minimal performance impact.

How to Install Proxy Protocol Support

Installing this mod is straightforward, but because it is server-side only, you do not need to place it in your client's mods folder. Follow these steps to get started:

1. Ensure your server runs Fabric or Quilt (the mod supports both loaders).
2. Download Proxy Protocol Support from a trusted mod repository. The file will be a .jar.
3. Place the downloaded .jar file into your server's mods folder.
4. Restart the server. The mod will generate a default configuration file at config/proxy_protocol_support.json.
5. Edit the configuration to match your proxy setup (see below).

If you manage multiple servers or modpacks, the foxygame.net launcher simplifies the process by offering one-click installation of Proxy Protocol Support directly into your server's mod list, along with automatic updates to keep the mod current without manual file handling.

Configuration Guide

All settings are stored in config/proxy_protocol_support.json. Open this file with a text editor and adjust the following options:

enableProxyProtocol

Set to true to activate the mod. Default is true.

proxyServerIPs

A list of IP addresses that are your trusted proxy servers. Connections from these IPs must include a valid PROXY protocol header. For example, if your proxy runs on the same machine, use ["127.0.0.1"]. If you use a remote VPS, enter its public IP.

directAccessIPs

A list of IPs or CIDR ranges that are allowed to connect directly without a PROXY header. This is ideal for admins, local network players, or server management tools. Default includes ["127.0.0.1", "192.168.0.0/16"].

whitelistTCPShieldServers

When set to true, the mod automatically fetches the official TCPShield proxy IP list and adds them to the trusted proxy list. This keeps your configuration up-to-date without manual intervention.

Example Scenarios

Here are a few common setups to illustrate how flexible Proxy Protocol Support can be:

Local Proxy with Direct LAN Access

Your server and proxy (e.g., frp) run on the same machine. You want players to connect via the proxy, but you also want to join directly from your PC on the local network (IP 192.168.1.100).

• proxyServerIPs: ["127.0.0.1"]
• directAccessIPs: ["127.0.0.1", "192.168.1.100"]

Remote VPS Proxy with Home Network Access

Your server is at home, and you use a VPS with IP 203.0.113.10 as the proxy. You want your entire home network (192.168.0.0/24) to connect directly.

• proxyServerIPs: ["203.0.113.10"]
• directAccessIPs: ["127.0.0.1", "192.168.0.0/24"]

Maximum Security – Proxy Only

You want to allow connections exclusively through your trusted proxies, blocking all direct access.

• proxyServerIPs: ["1.2.3.4", "5.6.7.8"]
• directAccessIPs: [] (leave empty)

Why Proxy Protocol Support Is Essential for Modern Servers

Without the PROXY protocol, your server logs and anti-cheat plugins see only the proxy's IP address. This makes it impossible to ban specific players by IP, track suspicious activity, or use geolocation features. Proxy Protocol Support for Minecraft restores full visibility, giving you the security benefits of a proxy without sacrificing server management capabilities. The mod's hybrid mode is particularly powerful, allowing you to maintain a secure perimeter while still offering direct access to trusted users. Whether you are running a small community server or a large network, this mod ensures your IP-based tools work exactly as intended.

Compatibility and Loaders

Proxy Protocol Support is built for the Fabric and Quilt mod loaders and is compatible with Minecraft versions 1.14 through 1.21.10. It is a server-side only mod, so players do not need to install anything. The mod is regularly updated to support new Minecraft releases, and the developer tests against the latest stable versions. If you are using a proxy service like TCPShield, the automatic whitelist feature keeps your configuration current without any manual work.

Getting Started

To download Proxy Protocol Support, visit your preferred mod platform and grab the latest .jar file. After installation, spend a few minutes tailoring the configuration to your network setup. The default settings are secure, but customizing the IP lists ensures only authorized connections reach your server. With real IP visibility restored, you can finally use all your favorite server tools without compromise.