# HAProxyDetector<\/p>\n
A lightweight plugin for Paper\/Folia and Velocity that makes native HAProxy \/ Proxy Protocol support compatible with normal direct player connections.<\/p>\n
## Core Features<\/p>\n
– **Mixed Connection Support**: Accepts real HAProxy\/frp proxy traffic and normal direct player traffic at the same time.
\n– **Native Parser Compatibility**: Adds a synthetic HAProxy V2 header to direct traffic so the server can continue using its native proxy-protocol parsing flow.
\n– **Whitelist Supports Domain \/ IP \/ CIDR**: `whitelist` supports single IP entries, CIDR ranges, and domain names.
\n– **Minimal Intercept Logging**: Logs when a non-whitelisted proxy connection is blocked, including the frps source IP and client IP.<\/p>\n
## How It Works<\/p>\n
1. **Real HAProxy traffic**: If a valid HAProxy v1\/v2 header is detected, it is passed directly to the server’s native parser.
\n2. **Normal direct players**: If no HAProxy header exists, the plugin adds a synthetic HAProxy V2 header based on the player’s real socket address.
\n3. **Synthetic header protection**: Internally marks self-generated headers so later whitelist checks will not mistake them for external frps traffic.
\n4. **Whitelist filtering**: When `enable-whitelist` is enabled, only real external proxy sources are checked.<\/p>\n
## Supported Platforms<\/p>\n
– **Paper \/ Folia**: Theoretically supports versions with native HAProxy support.
\n– **Velocity**: Theoretically supports `3.0.0+`.<\/p>\n
## Configuration<\/p>\n
Paper and Velocity use the same `config.yml` structure:<\/p>\n
“`
\nenable-whitelist: true
\nwhitelist:
\n – 127.0.0.1
\n – “::1”
\n – frps.example.com
\n – 203.0.113.0\/24
\n“`<\/p>\n
### Whitelist Rules<\/p>\n
– **IP**: Exact match.
\n– **CIDR**: Network range match, for example `203.0.113.0\/24`.
\n– **Domain**: Automatically resolved into an IP list when the plugin loads the configuration.<\/p>\n
### Notes About Domain Whitelist Entries<\/p>\n
– Domain names are resolved when the plugin loads or reloads its configuration, not on every connection.
\n– If the DNS result changes later, restart or reload the plugin to refresh the resolved IP list.
\n– If a domain temporarily fails to resolve, the plugin will not fail to start and will keep the original config entry.<\/p>\n
## Logging Behavior<\/p>\n
Logs are only printed when a non-whitelisted HAProxy connection is blocked.<\/p>\n
Log fields:
\n– `frps`: The real source IP of the upstream proxy server.
\n– `client`: The client source IP carried in the HAProxy header.<\/p>\n
Example:<\/p>\n
“`
\n[HAProxyDetectorPaper] \u62e6\u622a\u975e\u767d\u540d\u5355 frps \u8fde\u63a5: frps=91.78.69.13, client=91.78.69.13
\n“`<\/p>\n
## Usage<\/p>\n
1. **Enable native HAProxy support**:
\n – **Paper \/ Folia**: Set `proxy-protocol` to `true` in `config\/paper-global.yml` (newer versions) or `paper.yml` (older versions).
\n – **Velocity**: Set `haproxy = true` in `velocity.toml`.
\n2. **Install the plugin**: Put the plugin JAR into the correct platform plugin directory.
\n3. **Configure the whitelist if needed**: If you only want to allow specific frps sources, edit `whitelist` in `config.yml`.
\n4. **Restart the server \/ proxy**.<\/p>\n
## Disable \/ Unload Behavior<\/p>\n
The plugin actively removes its injected Netty handlers during disable or shutdown, so unloading it will not continue affecting new connections.
\nFor low-level network plugins in production environments, a full restart is still the safest option.<\/p>\n
## Technical Details<\/p>\n
– **Netty ChannelPipeline Injection**: Intercepts raw `ByteBuf` at the front of the network pipeline.
\n– **Feature Detection**: Uses reflection to locate the server connection structure without depending on one fixed field name.
\n– **HAProxy V2 Header Forging**: Generates a standard HAProxy V2 header for direct connections.
\n– **Synthetic Marker**: Prevents self-generated headers from being checked again as external proxy traffic.<\/p>\n","protected":false},"excerpt":{"rendered":"
HAProxyDetector for Paper and Velocity<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"haproxydetectorpaper","_minecraft_project_id":"ajXAHSmP","_minecraft_author":"TendoArisu","_minecraft_license":"MIT","_minecraft_downloads":65,"_minecraft_follows":0,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"haproxydetectorpaper.zip","_minecraft_size_bytes":58308,"_minecraft_version_count":4,"_minecraft_updated_at":"2026-05-15T20:35:16.829975Z","_minecraft_date_created":"2026-02-07T06:45:14.011607Z","_minecraft_date_modified":"2026-04-08T11:53:42.476784Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/haproxydetectorpaper","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-04T13:42:27+00:00","_minecraft_import_hash":"1dba5d5309d741d1e1ad3a448544a0ba","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[125,126,127,128,985],"mod_loader":[131,132,133,986],"minecraft_version":[59,36,60,93,94,101,102,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-79249","mod","type-mod","status-publish","hentry","mod_category-folia","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-velocity","mod_loader-folia","mod_loader-paper","mod_loader-purpur","mod_loader-velocity","minecraft_version-1-20","minecraft_version-1-20-1","minecraft_version-1-20-2","minecraft_version-1-20-3","minecraft_version-1-20-4","minecraft_version-1-20-5","minecraft_version-1-20-6","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n