panel — open-source game server manager (public release)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-14 19:19:43 -07:00
commit 5232609719
2160 changed files with 300415 additions and 0 deletions
@@ -0,0 +1,105 @@
+# Networking for normal humans
+
+You run panel at home, your friends want to join your server, and you
+have a consumer router. This page is for you.
+
+## The 60-second version
+
+1. panel gives every instance its **host ports** at create time (see
+   [what the panel auto-allocates](#what-the-panel-auto-allocates)).
+   The dashboard's instance card / Ports panel shows the exact numbers.
+2. Log in to your router and **forward those ports** (right protocol —
+   most games are UDP) to the LAN IP of the **agent box** running that
+   instance.
+3. Give your friends `your-public-ip:game-port`.
+
+You do **not** need to forward the panel's own ports (8080/8443) for
+people to *play* — only to administer the panel from outside.
+
+## What the panel auto-allocates
+
+At instance create time the controller assigns each declared port a
+**host port** from the agent's configured port window — default
+**7000–9999** (`controller/cmd/controller/portalloc.go`). You can set a
+per-agent window in the agent edit modal (e.g. box A gets 7000–7999,
+box B gets 8000–8999). The allocator:
+
+- reserves ports of **stopped** instances too (they come back),
+- probes live sockets so it won't hand out a port some other process holds,
+- honors manual overrides from the Ports UI when they fit the window,
+- errors when the window is exhausted (widen it or delete instances).
+
+So the *actual* host port is usually **not** the game's default port —
+always read it off the dashboard. Ports marked `internal` in the module
+manifest (RCON, admin APIs) are **never** exposed on the host and never
+need forwarding.
+
+## Per-game port table
+
+Defaults from each `modules/<id>/module.yaml` (`ports:`). "Forward"
+means players/queries need it; internal ports are panel-only.
+
+| Game | Port (default) | Proto | Forward? | Notes |
+|---|---|---|---|---|
+| 7 Days to Die | 26900, 26901, 26902 | udp | yes (all 3, contiguous) | 8080/tcp web dashboard optional; telnet 8081 internal |
+| ARK: Survival Ascended | 7777, 7778 game + 27015 query | udp | yes | RCON 27020/tcp internal |
+| Barotrauma | 27015 game + 27016 query | udp | yes | |
+| Conan Exiles | 7777 game + 7778 pinger + 27015 query | udp | yes | RCON 25575/tcp internal |
+| Core Keeper | 27015 | udp | yes | |
+| DayZ | 2302 game/query | udp | yes | 2303/2304 optional; BE RCON 2305 internal |
+| Dragonwilds | 7777 | udp | yes | |
+| Empyrion | 30000–30003 (game, query, client, EAC) | udp | yes (all 4) | CSW 30004 internal; EAH API 30007/tcp only if you use EAH |
+| Enshrouded | 15637 | udp | yes | |
+| Factorio | 34197 | udp | yes | RCON 27015/tcp internal |
+| Minecraft Bedrock | 19132 (+19133 IPv6) | udp | yes | |
+| Minecraft Java | 25565 | tcp | yes | RCON 25575 internal |
+| Palworld | 8211 game + 27015 query | udp | yes | RCON 25575/tcp internal |
+| Project Zomboid | 16261, 16262 | udp | yes (both) | RCON 27015/tcp internal |
+| Rust | 28015 | udp | yes | RCON 28016 internal; Rust+ 28082/tcp optional |
+| Satisfactory | 7777/udp game + 8888/tcp reliable | both | yes (both) | |
+| Sons of the Forest | 8766 game + 27016 query | udp | yes | |
+| Soulmask | 8777 game + 27015 query | udp | yes | admin 8888/tcp internal |
+| Terraria | 7777 | tcp | yes | |
+| V Rising | 9876 game + 9877 query | udp | yes | |
+| Valheim | 2456, 2457, 2458 | udp | yes (all 3, contiguous) | |
+| Vein | 7777 game + 27015 query | udp | yes | RCON 7878/udp internal |
+| Windrose | 7777 | udp | yes | |
+
+Remember: these are the *container defaults* — forward the **host ports
+the panel actually assigned** (dashboard → instance → Ports).
+
+## Forwarding ports on a generic router
+
+Every router is different; the shape is always:
+
+1. Browse to your router's admin page — usually `http://192.168.1.1` or
+   `http://192.168.0.1` (it's the "Default Gateway" in
+   `ipconfig` / `ip route`).
+2. Find **Port Forwarding** — sometimes under "NAT", "Virtual Server",
+   "Gaming", or "Advanced".
+3. Add a rule per port (or range): external port = internal port =
+   the host port panel assigned; protocol per the table above; internal
+   IP = the LAN address of the **agent** box.
+4. Give the agent box a **static LAN IP** (DHCP reservation) so the rule
+   doesn't break after a reboot.
+5. Test from *outside* your network (phone on cellular). Sites like
+   canyouseeme.org only test TCP — most game ports are UDP, so the real
+   test is a friend joining.
+
+If you're behind **CGNAT** (ISP gives you a shared public IP — common on
+cellular/fiber ISPs), port forwarding can't work; use a VPN/tunnel
+(WireGuard on a cheap VPS, playit.gg, Tailscale Funnel, etc.) or ask
+your ISP for a public IP.
+
+## What about `opnfwd`?
+
+You may notice an "OPNsense auto-forward" card in the admin settings and
+`opnfwd_*` code in the tree. That is **maintainer-specific automation**
+for a home lab running an OPNsense firewall: when enabled, the panel
+calls the OPNsense API to create port forwards automatically on instance
+create/delete.
+
+It is **off by default** (`panel_settings.opnfwd_enabled` must be
+explicitly set to `true`) and is irrelevant to normal users — if you
+don't run OPNsense, ignore it entirely and forward ports on your router
+as described above.