Pin Minecraft 26.3 and add safe Orion managed deployment support
This commit is contained in:
Aryan Singh committed
1 parent
dff2b5a9c4
commit
008120dbad
40 files changed
+1877
-490
No files matched your search
+8
-77
@@ -1,84 +1,15 @@
|
||||
# TCPShield (DDoS protection + real player IPs)
|
||||
# TCPShield on Orion
|
||||
|
||||
[TCPShield](https://tcpshield.com) sits in front of the server: players connect to
|
||||
your TCPShield domain, and your real server IP stays hidden and DDoS-protected.
|
||||
The catch: without extra setup, every connection appears to come from TCPShield's
|
||||
proxies, so the Security page, IP bans, and connection logs are useless.
|
||||
Use the maintained runbook in `homelab-infra/stacks/minecraft/TCPSHIELD.md` for the exact OPNsense and host firewall steps.
|
||||
|
||||
TCPShield's own RealIP plugin is Bukkit/Bungee/Velocity-only — it does not exist
|
||||
for Fabric. The working path for this stack is **PROXY protocol v2** plus the
|
||||
**Proxy Protocol Support** Fabric mod.
|
||||
Traffic flows: player → TCPShield → OPNsense source-restricted TCP 25565 DNAT → Orion Velocity → private Fabric backend. Enable PROXY protocol in TCPShield and `haproxy-protocol = true` in Velocity. Velocity then uses modern forwarding, with the same secret as `FABRIC_PROXY_SECRET` in FabricProxy-Lite.
|
||||
|
||||
## Setup
|
||||
The reviewed deployment pins Minecraft 26.3 and Velocity 4.2.0 build 30. The direct Fabric `proxy-protocol-support` mod did not advertise 26.3 support at review time, so it is not used. The old `config/patches` files are legacy and are no longer mounted by the standalone Compose file. Do not combine that legacy direct-server guide with the Velocity deployment.
|
||||
|
||||
1. **TCPShield panel** → your backend → enable **Proxy Protocol**.
|
||||
2. **Mods page** → Recommended → add **Proxy Protocol Support** → Apply
|
||||
(or append `proxy-protocol-support` to `MODRINTH_PROJECTS` in `.env` and
|
||||
`docker compose up -d mc`).
|
||||
3. Nothing else — the mod's configuration is **enforced automatically on every
|
||||
boot** by `config/patches/patch-set.json` (see below). Restart once after
|
||||
installing so the patch applies:
|
||||
OPNsense must preserve the TCPShield source address and permit only the official IPv4 ranges from https://tcpshield.com/v4/. Host DOCKER-USER rules enforce the same restriction before trusted-LAN exceptions. Do not add game port 25565 to unrestricted public ports. Do not expose the backend, RCON, panel or a map port.
|
||||
|
||||
```bash
|
||||
docker compose restart mc
|
||||
```
|
||||
The public Minecraft hostname is a DNS-only CNAME to the hostname assigned by TCPShield. An ordinary Cloudflare orange-cloud HTTP proxy is not a Minecraft proxy. Use the public protected hostname even from home; direct LAN joins intentionally fail on the protected proxy port.
|
||||
|
||||
## Verifying it works
|
||||
Verify an external join, real player IP, EasyAuth registration, whitelist/UUID continuity and direct-origin rejection before inviting players. Configure TCPShield for the exact protected hostname and backend; account/plan controls and any account-specific verification steps must be completed in its dashboard.
|
||||
|
||||
Watch the startup log (`docker compose logs -f mc`). You must see all three:
|
||||
|
||||
```
|
||||
Proxy Protocol Support is enabled!
|
||||
TCPShield integration enabled! Fetching official IPs...
|
||||
Successfully added 2 TCPShield IPs to the trusted proxy list.
|
||||
```
|
||||
|
||||
Then join through your TCPShield domain — the console shows your **real IP**, and
|
||||
`docker compose ps` shows `mc` **healthy**.
|
||||
|
||||
## How the config is managed (don't hand-edit!)
|
||||
|
||||
The mod rewrites `config/proxy_protocol_support.json` at every startup, which
|
||||
silently clobbers hand edits. Instead, the server image applies
|
||||
`config/patches/patch-set.json` from this repo **before every server start**,
|
||||
enforcing:
|
||||
|
||||
| Setting | Value | Why |
|
||||
|---|---|---|
|
||||
| `enableProxyProtocol` | `true` | decode PROXY protocol headers |
|
||||
| `whitelistTCPShieldServers` | `true` | auto-fetch TCPShield's proxy IP ranges — no hardcoding, survives their infra changes |
|
||||
| `proxyServerIPs` | `127.0.0.1` | (TCPShield's ranges are added automatically at runtime) |
|
||||
| `directAccessIPs` | localhost (`127.0.0.1`, `::1`) + private ranges (`10/8`, `172.16/12`, `192.168/16`) | container healthcheck + LAN/panel access |
|
||||
|
||||
To change a value, edit the patch file in the repo and `docker compose up -d mc`.
|
||||
|
||||
**First-boot note:** on a brand-new install the mod's config file doesn't exist
|
||||
yet when patches run, so the very first boot uses mod defaults; every boot after
|
||||
that is patched. One `docker compose restart mc` after first install settles it.
|
||||
|
||||
## Security model
|
||||
|
||||
PROXY protocol headers carry no signature, so anyone who finds your raw server IP
|
||||
could spoof client IPs — the mod prevents this with default-deny:
|
||||
|
||||
- PROXY headers are only accepted from **TCPShield's published ranges** (auto-fetched)
|
||||
- Direct, header-less connections are only accepted from **localhost + LAN**
|
||||
- Everything else → `REJECTED unauthorized direct connection` in the log
|
||||
|
||||
So occasional `REJECTED` lines from random public IPs are the wall working —
|
||||
that's scanner bots hitting your raw IP and bouncing. A `REJECTED ... /0:0:0:0:0:0:0:1`
|
||||
(IPv6 localhost) every few seconds means the container healthcheck is being
|
||||
blocked — that's exactly what the `::1` entry in the patch prevents; if you see
|
||||
it, the patch didn't apply (check `docker compose logs mc | head -50`).
|
||||
|
||||
For belt-and-braces, also enable TCPShield's Advanced Firewall (panel → Network →
|
||||
Firewall), and consider host-firewalling port 25565 to TCPShield's ranges
|
||||
(`curl tcpshield.com/v4`) once everything works.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Friends must connect via the TCPShield domain** — direct-IP connections from
|
||||
outside your LAN are rejected by design once this is active.
|
||||
- If real players start bouncing with `REJECTED`, TCPShield may have changed
|
||||
their IP ranges *and* the auto-fetch failed at boot — restart the server so it
|
||||
re-fetches.
|
||||
Sources: [TCPShield documentation](https://docs.tcpshield.com/), [Velocity forwarding](https://docs.papermc.io/velocity/player-information-forwarding/), [OPNsense NAT](https://docs.opnsense.org/manual/nat.html).
|
||||
Reference in new issue
Block a user