ВЕРСИИ (6)

## 🆕 What's New in 1.5.0: Reliability & Security Fixes A maintenance release from a systematic audit, plus one addition to keep pace with an ngrok change: - **Added: ngrok tunnels can now use a reserved/static domain.** ngrok moved domain selection to their own dashboard ("Choose your URL") — pick one there, drop it into the new `hostname` field, and it's passed along with `--url`. Leave it blank for a random domain each start, same as before. - **Fixed: editing a tunnel could silently wipe its saved authtoken/cfToken.** The edit form correctly never sends secrets back to the browser, but saving an unrelated change (like toggling auto-start) was overwriting the stored token with blank — breaking the tunnel on its next start. Blank secret fields on save now keep the existing value; only an actual new value overwrites it. - **Fixed: a tunnel name containing an apostrophe broke every action button on that tunnel's card.** Start/Stop/Restart/Delete/Copy buttons are now correctly escaped for names, URLs, and IDs containing `'`, `"`, or `\`. - **Fixed: renaming a tunnel to an existing tunnel's name silently orphaned the old one.** The old tunnel's process kept running with nothing left tracking it, and it disappeared from `config.yml` entirely. Renaming to a name already in use is now rejected instead. - **Fixed: clicking Stop immediately after Start could leave an untracked tunnel process running,** and later resurrect it as "running" in the dashboard even though you'd explicitly stopped it. A start/stop race no longer lets a launch that lost the race adopt its process. - **Fixed: playit.gg's "Try Again" button could hand back a dead claim session** for up to ~11 minutes after a rejected or cancelled link attempt, instead of issuing a fresh code. - **Fixed: an unsanitized tunnel name could write ngrok's per-tunnel config file outside the intended directory.** Tunnel names are now restricted to letters, numbers, `_`, and `-`. - **Fixed: editing any tunnel could silently wipe a saved ngrok reserved domain back to blank,** since the persistence path rebuilt every tunnel's entry from scratch on every save. - **Fixed: a malformed dashboard API request could return an empty, unexplained server error** with nothing in the log. Bad requests now get a clear JSON error and the real cause is logged server-side. - **Improved: error logging** for playit/ngrok/cloudflared download and connection failures now always includes the exception type (and throw site when there's no message), instead of sometimes printing a bare "null".

## 🆕 What's New in 1.4.0: playit.gg Support **A static address, right protocol per tunnel.** playit.gg is the pick for Bedrock/Geyser — TCP for Java Edition, UDP for Bedrock (Bedrock/RakNet is UDP-only), both with an address that survives restarts. Neither ngrok's free tier nor cloudflared quick tunnels can do that, and the official playit.gg plugin doesn't support UDP either. Combined TCP+UDP and TCP-only custom tunnels are also available (require playit premium); UDP-only and the two Minecraft presets work on the free tier. **No token to paste.** Link an account from the dashboard's Settings tab — click **Link**, open the generated claim link, approve it in your browser, and the dashboard flips to linked automatically. **One shared agent.** playit's model is one agent per machine (accounts have a limited agent quota), so TunnelMC runs a single `playitd` process shared by every playit tunnel you add. Every claim provisions a fresh agent identity — there's no API to target an existing one — so Unlink deletes this server's tunnels from your playit.gg account before clearing the secret, and a re-link recreates them fresh with new addresses. That keeps tunnels from piling up on your account; the one thing that still needs manual cleanup is the old agent record itself at playit.gg/account/agents, since playit has no API to delete an agent at all. **Clean up leftovers without leaving the dashboard.** A "Check for Other Tunnels" button in Settings finds any tunnel on your playit agent that TunnelMC isn't tracking and lets you delete it in place. Deleting a tunnel from the Tunnels tab deletes it on playit's side too. **macOS:** playit.gg publishes no official Mac binary. The dashboard offers a TunnelMC-compiled build (SHA-256 verified) or self-build instructions — ngrok and cloudflared are unaffected and work normally on macOS.

## 🆕 What's New in 1.3.0 ### Java 25 & Build Modernization - **Upgraded to Java 25** — compiled with Java 25 bytecode for the latest JVM performance and language features. - **Gradle 9.5.1** — build system upgraded from Gradle 8.x to 9.5.1 for native Java 25 support. - **Virtual thread executor** — the dashboard HTTP server now uses `newVirtualThreadPerTaskExecutor()` for non-blocking I/O scaling on Java 25. - **`plugin.yml` api-version** updated from `1.13` to `1.21` to match the target platform and suppress Paper deprecation warnings. ### Security Hardening - **CSRF protection** — all mutating API endpoints now require an `X-TM-Request` header. - **Brute-force login protection** — lockout after 5 failed attempts with 500ms delay per failure. - **Timing-safe password comparison** — login now uses `MessageDigest.isEqual()` to prevent timing attacks. - **CSP headers** — Content-Security-Policy added to all dashboard responses to mitigate XSS risks. - **Session sweep** — expired sessions and stale lockout entries are automatically cleaned up hourly. ### Stability - **`volatile` singleton** — static plugin instance is now `volatile` and nulled on disable to prevent classloader leaks during reloads. - **Config bounds checking** — all numeric config getters now clamp to valid ranges via `Math.max`. - **Default password warning** — a prominent console warning at startup if the dashboard password is still `"changeme"`. ### Compatibility - **Minecraft 1.21.x – 26.2.x** — compiled against Paper 1.21.1 API, which is forward-compatible with all Paper versions through 26.2.x. Existing configs remain fully compatible — no config changes required.

## 🆕 What's New in 1.2.0 ### Cloudflared Support Every tunnel now has its own `provider` field. Choose `ngrok` or `cloudflared` per tunnel, or mix them in the same config. **Cloudflared quick tunnels** — zero account setup, random `*.trycloudflare.com` URL, HTTP only. Great for dashboards and web services. **Cloudflared named tunnels** — paste a Cloudflare Zero Trust token and your custom hostname. Persistent URL, any protocol you've configured in Cloudflare. ### Multiple ngrok Accounts Each ngrok tunnel now has its own `authtoken` field (required for ngrok v3). Authtokens are passed as a CLI flag instead of writing to the global ngrok config, so you can run tunnels from completely different ngrok accounts at the same time. ### Per-Tunnel Region Each ngrok tunnel can set its own `region`, overriding the global default. ### Web Dashboard A full browser-based management dashboard on port `8090` (local only). From it you can: - View all tunnels — status, URL, uptime, restarts - Start / stop / restart tunnels individually - **Create, edit, and delete tunnels live** — no server restart needed - Download ngrok and cloudflared binaries with one click - Edit all global settings ### Auto-Expose on First Run If no tunnels are configured, TunnelMC automatically downloads cloudflared and creates a quick tunnel to the dashboard on first startup so you can access it from anywhere right away. ### Per-Tunnel Auto-Start Each tunnel has its own `auto-start` field. Set it to `true` to start a tunnel on server boot even when global auto-start is off. The default `dashboard` tunnel ships with `auto-start: true`.

## 🆕 What's new in 1.1.0 ### Auto-Restart & Crash Loop Protection Tunnels now restart automatically if the ngrok process exits unexpectedly. Crash loop protection kicks in if a tunnel fails too many times within a configurable time window, stopping the retry cycle to prevent runaway restarts. Both the restart delay and failure threshold are fully configurable. ### Health Checks TunnelMC now periodically verifies each tunnel is still alive by querying ngrok's local API. If a tunnel silently dies without crashing, the health check catches it and triggers an automatic restart. The check interval is configurable, or can be disabled entirely. ### `/tunnel download` Command You can now trigger the ngrok binary download manually at any time from in-game or console with `/tunnel download`. Useful if the initial download failed or you want to re-fetch the binary without restarting your server. ### NodeRunner & PyRunner Integration If [NodeRunner](https://modrinth.com/plugin/noderunner) or [PyRunner](https://modrinth.com/plugin/pyrunner) is installed and one of your configured tunnel ports matches their dashboard port, TunnelMC will print a helpful suggestion in console. This is purely informational — these bot runners are never auto-started by TunnelMC. --- ### Config changes Four new options have been added to `config.yml`: ```yaml auto-restart: true restart-delay-seconds: 10 max-restarts: 5 crash-window-seconds: 60 health-check-interval-seconds: 30 integrations: noderunner-suggestion: true pyrunner-suggestion: true ``` Existing configs remain fully compatible — all new keys will use their defaults if not present.

# TunnelMC 🌐 > **Expose any port on your Minecraft server to the internet via ngrok tunnels — no extra port allocations needed.** TunnelMC is a Bukkit/Spigot/Paper plugin that automatically downloads and manages ngrok as a child process, creates tunnels for any local port, and broadcasts the public URL to console and online OPs the moment the tunnel is ready. Perfect for exposing web dashboards (like [NodeRunner](https://modrinth.com/plugin/noderunner)'s WebUI) when you don't have a spare port allocation on shared or Pterodactyl hosting. --- ## ✨ Features ### ⚡ Zero-Touch ngrok Setup No ngrok installed? No problem. TunnelMC automatically detects your OS and CPU architecture and downloads the correct ngrok v3 binary on first launch. Downloaded once, cached forever. ### 🔌 HTTP & TCP Protocol Support Use `http` protocol for web dashboards and APIs — gets you a public `https://` URL instantly. Use `tcp` for game servers, SSH, databases, or any other TCP traffic — gets you a `tcp://` address. Note: UDP is not supported by ngrok. ### 🔀 Multiple Tunnels Define as many tunnels as you need in config, each with its own name, port, and protocol. Each tunnel runs as an independent ngrok process. ### 🔔 Instant URL Broadcast The public ngrok URL is printed to console and sent to all online OPs the moment the tunnel comes online — no need to dig through logs. ### 🎮 Full In-Game Control Start, stop, restart, and check tunnel status from in-game or the console via `/tunnel`. Tab completion included. ### 🐋 Pterodactyl Compatible Fully tested on Pterodactyl panels. No extra port allocation needed — that's the whole point. If your host throttles the ngrok download, TunnelMC will warn you after 30 seconds with manual install instructions. ### ⚙️ Auto-Start Optionally start all tunnels automatically on server boot with a configurable startup delay. --- ## 📥 Installation 1. Drop `TunnelMC.jar` into your `plugins/` folder 2. Start the server once to generate the config 3. Sign up free at [ngrok.com](https://ngrok.com) and copy your authtoken from the [dashboard](https://dashboard.ngrok.com/get-started/your-authtoken) 4. Paste your authtoken into `plugins/TunnelMC/config.yml` 5. Restart or run `/tunnel start` --- ## ⚙️ Configuration ```yaml authtoken: "your-ngrok-token-here" auto-start: true startup-delay-seconds: 0 region: "us" # us, eu, ap, au, sa, jp, in notify-ops: true tunnels: - name: "dashboard" port: 8080 protocol: "http" # https:// URL - name: "gameserver" port: 25565 protocol: "tcp" # tcp:// URL ``` --- ## 🎮 Commands & Permissions **Permission:** `tunnelmc.admin` *(default: OP)* | Command | Description | | :--- | :--- | | `/tunnel start [name]` | Start all or a specific tunnel | | `/tunnel stop [name]` | Stop all or a specific tunnel | | `/tunnel restart [name]` | Restart all or a specific tunnel | | `/tunnel url [name]` | Show public URL(s) | | `/tunnel status` | Show status of all tunnels | | `/tunnel reload` | Reload config and restart tunnels | --- ## ⚠️ ngrok Free Plan Limitations - **1 tunnel at a time** — Free accounts cannot run multiple simultaneous tunnels. Multiple tunnels require a paid ngrok plan. - **Random URLs** — Free accounts get a new random URL on every restart. Paid plans support fixed custom domains. - **Bandwidth limits** — Free accounts have monthly bandwidth limits. See [ngrok's pricing](https://ngrok.com/pricing). - **UDP not supported** — ngrok only supports TCP-based protocols. --- ## 🐋 Pterodactyl Notes No extra port allocation needed — TunnelMC handles that. However, some hosts throttle downloads from `bin.equinox.io`. If that happens, TunnelMC warns you after 30 seconds and you can install ngrok manually instead: 1. Download ngrok from [ngrok.com/download](https://ngrok.com/download) on your PC — pick **Linux → 64-bit** 2. Extract the archive — you get a single file called `ngrok` 3. Upload it to `plugins/TunnelMC/ngrok/ngrok` via the file manager (the second `ngrok` is the file name itself) 4. Restart — TunnelMC detects it automatically and skips the download --- ## 📊 Compatibility | | | | :--- | :--- | | **Platforms** | Bukkit, Spigot, Paper, Purpur | | **Minecraft** | 1.13+ | | **Java** | 11+ (21 recommended) | | **OS** | Linux, macOS, Windows | | **Architectures** | x64, ARM64 | | **Hosting** | Self-hosted, Pterodactyl, any VPS | > **⚠️ Java Version Note:** Although the plugin API is compatible with 1.13+, the JAR is compiled with Java 21 which means your server must be running **Java 21 or higher** regardless of Minecraft version. Older Minecraft versions (1.13–1.16) typically run on Java 8 or 11 and will fail to load this plugin with an `UnsupportedClassVersionError`. In practice, **Java 21 + Paper 1.21.x** is the recommended and fully tested setup. --- ## 🔗 Related **[NodeRunner](https://modrinth.com/plugin/noderunner)** — Run a Node.js Discord bot directly inside your Minecraft server. TunnelMC pairs perfectly with NodeRunner to expose its web dashboard without needing an extra port. --- ## 📄 License **All Rights Reserved** — This plugin and its source code are proprietary. You may not copy, redistribute, modify, or decompile this software without explicit written permission from the author. --- *Developed by [Spider](https://github.com/Spider2742)*