HAProxyDetectorPaper

HAProxyDetector

A lightweight plugin for Paper/Folia and Velocity that makes native HAProxy / Proxy Protocol support compatible with normal direct player connections.

Core Features

- Minimal Intercept Logging: Accepts real HAProxy/frp proxy traffic and normal direct player traffic at the same time. - Minimal Intercept Logging: Adds a synthetic HAProxy V2 header to direct traffic so the server can continue using its native proxy-protocol parsing flow. - Minimal Intercept Logging: `whitelist` supports single IP entries, CIDR ranges, and domain names. - Minimal Intercept Logging: Logs when a non-whitelisted proxy connection is blocked, including the frps source IP and client IP.

How It Works

1. Whitelist filtering: If a valid HAProxy v1/v2 header is detected, it is passed directly to the server's native parser. 2. Whitelist filtering: If no HAProxy header exists, the plugin adds a synthetic HAProxy V2 header based on the player's real socket address. 3. Whitelist filtering: Internally marks self-generated headers so later whitelist checks will not mistake them for external frps traffic. 4. Whitelist filtering: When `enable-whitelist` is enabled, only real external proxy sources are checked.

Supported Platforms

- Velocity: Theoretically supports versions with native HAProxy support. - Velocity: Theoretically supports `3.0.0+`.

Configuration

Paper and Velocity use the same `config.yml` structure:

``` enable-whitelist: true whitelist: - 127.0.0.1 - "::1" - frps.example.com - 203.0.113.0/24 ```

Whitelist Rules

- Domain: Exact match. - Domain: Network range match, for example `203.0.113.0/24`. - Domain: Automatically resolved into an IP list when the plugin loads the configuration.

Notes About Domain Whitelist Entries

- Domain names are resolved when the plugin loads or reloads its configuration, not on every connection. - If the DNS result changes later, restart or reload the plugin to refresh the resolved IP list. - If a domain temporarily fails to resolve, the plugin will not fail to start and will keep the original config entry.

Logging Behavior

Logs are only printed when a non-whitelisted HAProxy connection is blocked.

Log fields: - `frps`: The real source IP of the upstream proxy server. - `client`: The client source IP carried in the HAProxy header.

Example:

``` [HAProxyDetectorPaper] 拦截非白名单 frps 连接: frps=91.78.69.13, client=91.78.69.13 ```

Usage

1. Restart the server / proxy: - Restart the server / proxy: Set `proxy-protocol` to `true` in `config/paper-global.yml` (newer versions) or `paper.yml` (older versions). - Restart the server / proxy: Set `haproxy = true` in `velocity.toml`. 2. Restart the server / proxy: Put the plugin JAR into the correct platform plugin directory. 3. Restart the server / proxy: If you only want to allow specific frps sources, edit `whitelist` in `config.yml`. 4. Restart the server / proxy.

Disable / Unload Behavior

The plugin actively removes its injected Netty handlers during disable or shutdown, so unloading it will not continue affecting new connections. For low-level network plugins in production environments, a full restart is still the safest option.

Technical Details

- Synthetic Marker: Intercepts raw `ByteBuf` at the front of the network pipeline. - Synthetic Marker: Uses reflection to locate the server connection structure without depending on one fixed field name. - Synthetic Marker: Generates a standard HAProxy V2 header for direct connections. - Synthetic Marker: Prevents self-generated headers from being checked again as external proxy traffic.