Skip to content

Releases: CyberSphinxxx/TunnelKeeper

Release list

v2.0.0 - Modern Dynamic Tunnel & DNS Gateway

v2.0.0 - Modern Dynamic Tunnel & DNS Gateway Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 07 Sep 20:36
v2.0.0
aac711d

Overview

TunnelKeeper v2.0.0 is a major milestone release that transforms the project from a set of command-line scripts into an automated, production-grade Minecraft tunneling gateway with a modern graphical dashboard, automated Windows installers, multi-provider DNS support, and a fully de-personalized architecture.

This release introduces native Windows WPF GUI integration, system tray minimization, dual DNS provider support (Hostinger and Cloudflare), strict configuration enforcement, zero-downtime hot-swap automation, and automated GitHub Actions CI/CD workflows for building Windows installers and release bundles.

What Is New in v2.0.0

1. Modern Native Windows WPF Dashboard

  • Dedicated Graphical Interface: Run TunnelKeeper.exe for a full-featured, dark-themed dashboard built entirely on native Windows WPF with no external dependencies (no Electron, Python, or Node.js required).
  • Zero-Console Flash: Compiled using a custom C# win32 application wrapper to guarantee zero console popups or terminal flashes on launch.
  • Interactive Settings Tab: Configure DNS provider tokens, domain names, SRV records, local Minecraft port, hot-swap intervals, DNS TTL, and log retention directly within the interface without manually editing files.
  • Password Masking & Visibility Toggle: Mask and reveal Hostinger or Cloudflare API tokens securely.
  • Public Address Display & 1-Click Copy: View your player-facing address (e.g. play.yourdomain.com or root domain) and copy it directly to your clipboard with a single click.
  • Live Log Viewer: Real-time embedded log streaming with auto-scroll toggles, buffer clearing, and direct shortcuts to open the active log file or logs folder.
  • System Tray Integration: Minimize TunnelKeeper to the Windows notification tray next to the taskbar clock with a right-click context menu (Open, Start, Stop, Exit) to maintain 24/7 server uptime without taskbar clutter.

2. Multi-Provider DNS Dispatcher (Hostinger & Cloudflare)

  • Cloudflare API Integration: Full support for Cloudflare DNS via scoped API tokens (Zone.DNS permissions), including automatic zone ID discovery, SRV record lookup, priority/weight configuration, and atomic DNS updates.
  • Hostinger API Integration: Native support for Hostinger REST API SRV record management with automatic target host formatting and verification.
  • Dynamic Provider Switching: Seamlessly toggle between Hostinger and Cloudflare via radio buttons in the GUI or via the DnsProvider setting in .env.
  • Sensitive Credential Redaction: All logs and console outputs automatically redact Hostinger and Cloudflare tokens to prevent accidental exposure.

3. Complete De-Personalization & Configuration Enforcement

  • Generic Configuration Architecture: All personal domains, ports, and prefixes (therealneighbors.online, port 25566, TRN_) have been completely removed from public repository files.
  • Pre-Flight Validation Engine: Both the GUI and the background autostart daemon enforce that users specify their own registered domain name before launching. Placeholder domains (example.com, yourdomain.com) and invalid ports or intervals are rejected with clear, descriptive guidance.
  • Seven Configurable Parameters: Full support and validation for:
    • RootDomain: Your registered domain zone.
    • SrvRecordName: The SRV record label (e.g. _minecraft._tcp.play or _minecraft._tcp).
    • LocalPort: Local Minecraft server port (standard Java default 25565).
    • Priority: SRV record priority (0 - 65535, default: 0).
    • Weight: SRV record weight for balancing (0 - 65535, default: 5).
    • TTL: DNS record Time-To-Live in seconds (default: 60).
    • HotSwapMinute: Elapsed minutes before pre-starting a replacement tunnel (default: 55).
  • Dynamic Player Address Helper: Automatically determines whether players connect to play.yourdomain.com, a custom subdomain, or the root domain based on the configured SRV label.

4. Process Lifecycle & System Safety Guard

  • Windows Named Mutex (Global\TunnelKeeper_Gateway): Guarantees that only a single instance of the gateway daemon can execute at any time. Handles process crashes and abandoned mutexes cleanly.
  • Windows Task Scheduler Coexistence: If launched while the background Task Scheduler task is active, TunnelKeeper detects the running service, displays an informational status card, and exits cleanly without throwing errors.
  • Interactive Takeover (-Force): Passing -Force automatically stops background scheduled tasks, terminates orphan Pinggy SSH processes, and runs the daemon interactively in the current console.
  • Orphan Process Cleanup: Automatically cleans up lingering child SSH tunnels if the terminal or GUI is closed abruptly.

5. Automated Windows Installers & CI/CD

  • Inno Setup Wizard (TunnelKeeper-Setup.exe): Single executable installer that installs TunnelKeeper to %LOCALAPPDATA%\TunnelKeeper, creates Desktop and Start Menu shortcuts, and provides clean Windows uninstallation.
  • 1-Line PowerShell Web Installer (install.ps1): Quick-install command (irm https://raw.githubusercontent.com/CyberSphinxxx/TunnelKeeper/main/install.ps1 | iex) that downloads, compiles, and configures the app automatically.
  • GitHub Actions Release Workflow: Automated CI/CD pipeline (.github/workflows/release.yml) that triggers on tag push or manual dispatch to compile TunnelKeeper.exe, generate TunnelKeeper-Setup.exe, create a portable zip bundle, generate SHA-256 checksums, and publish release assets automatically.
  • Continuous Integration Workflow: .github/workflows/ci.yml validates PowerShell syntax and C# compilation on every pull request and push to the main branch.

Installation Options

Option A: Windows Setup Wizard (Recommended)

  1. Download TunnelKeeper-Setup.exe from the Assets section below.
  2. Run the installer and follow the setup prompts.
  3. Launch TunnelKeeper from your Desktop or Start Menu.

Option B: 1-Line PowerShell Web Installer

Run the following command in PowerShell:

irm https://raw.githubusercontent.com/CyberSphinxxx/TunnelKeeper/main/install.ps1 | iex

Option C: Portable Zip Bundle

  1. Download TunnelKeeper-v2.0.0-Portable.zip from the Assets section below.
  2. Extract the archive to your preferred folder.
  3. Double-click TunnelKeeper.exe to launch.

Configuration Reference

Copy .env.example to .env or configure these settings directly in the TunnelKeeper GUI Settings tab:

Parameter Default Description
DnsProvider Hostinger DNS provider: Hostinger or Cloudflare
HostingerToken (empty) Hostinger API token with DNS write permissions
CloudflareApiToken (empty) Cloudflare API token with Zone.DNS permissions
CloudflareZoneId (auto) Optional Cloudflare Zone ID; auto-discovered if omitted
RootDomain (Required) Your registered domain zone (e.g. yourdomain.com)
SrvRecordName _minecraft._tcp.play SRV record label within your DNS zone
LocalPort 25565 Local Minecraft server port (Java standard: 25565)
Priority 0 SRV record priority (0 - 65535, default: 0)
Weight 5 SRV record weight (0 - 65535, default: 5)
TTL 60 DNS TTL in seconds for fast propagation
HotSwapMinute 55 Minutes elapsed before starting a replacement tunnel
LogRetentionDays 14 Days of rotated log files to retain before cleanup

Screenshots

image image image

Detailed Commit History

  • 9a8b3db: chore: update .gitignore to ignore .env and release artifacts
  • 2ec8ba0: feat(config): add .env.example configuration template with DNS and port settings
  • fdde30b: refactor(core): de-personalize tunnel daemon, add strict pre-flight validation and dynamic SRV mapping
  • 7f5da8d: feat(assets): add TunnelKeeper application icon
  • 5f914c7: feat(build): add native C# compiler script to generate TunnelKeeper.exe
  • 6360d02: feat(bin): add precompiled native Windows launcher TunnelKeeper.exe
  • 4a43637: feat(launcher): add silent VBScript background launcher
  • 24b600b: feat(launcher): add quick-start batch launcher
  • 6ddf99f: feat(gui): add native WPF dark-theme dashboard with settings and live logs
  • f134ae4: feat(installer): add Inno Setup wizard configuration script
  • 00e0c99: feat(install): add 1-line PowerShell web installer and uninstaller
  • 3f3a3e5: ci: add GitHub Actions workflow for syntax and build validation
  • 6a09d71: ci: add GitHub Actions release workflow for automated installer compilation
  • b13a114: docs: update README with installation options, GUI documentation, and generic examples

Full Changelog: v1.0.0...v2.0.0

Assets 6
Loading

v1.0.0 - Initial Release

v1.0.0 - Initial Release

Choose a tag to compare

View all tags
@CyberSphinxxx CyberSphinxxx released this 07 Sep 18:23
v1.0.0
40a3259

TunnelKeeper v1.0.0 is an automated PowerShell networking and dynamic DNS engine designed to expose a self-hosted Minecraft Java Edition server through free ephemeral TCP tunnels while maintaining continuous domain availability.

This release resolves systemic TCP connection timeout issues previously encountered with third-party proxy relays (playit.gg / SquidServers) by migrating Java traffic to an orchestrated Pinggy SSH tunnel pipeline. It introduces a hot-swap architecture to eliminate downtime caused by free-tier tunnel expirations, automates Hostinger DNS SRV record management via REST API, and hardens Windows process execution against terminal freezes and duplicate processes.

What is in the v1.0.0

Zero-Downtime Tunnel Hot-Swapping

Free-tier Pinggy tunnels terminate after approximately 60 minutes. Gateway v3 eliminates service interruptions through an overlapping lifecycle manager:

  • Pre-emptive Instantiation: At the 55-minute runtime mark ($HotSwapMinute = 55), the script provisions a second Pinggy tunnel in the background while the current tunnel remains operational.
  • Seamless Cutover: The script updates Hostinger SRV records to target the new host and port immediately upon address acquisition.
  • Graceful Deprecation: The preceding tunnel remains active in memory to handle trailing connections until remote termination by Pinggy, backed by a 10-minute force-cleanup fallback.

Hostinger DNS API Integration

The engine directly controls the authoritative DNS zone for my therealneighbors.online you can modify to make it yours ofcourse:

  • Atomic Deletion and Provisioning: Dispatches authenticated DELETE requests to purge stale _minecraft._tcp.play records before executing a PUT transaction, preventing duplicate SRV records.
  • Low-TTL Configuration: Standardizes the SRV record TTL to 60 seconds, ensuring fast client propagation across public resolver caches following each cycle.
  • Exponential Backoff and Retries: Implements an automated 3-attempt retry loop with 5-second backoff intervals for failed DNS updates, complemented by a persistent 30-second background retry loop if endpoints change while DNS is unresponsive.

Process Stability and Windows Hardening

  • Global Mutex Protection: Integrates a named kernel object (Global\TRN_MinecraftGateway) to block concurrent script executions, preventing API rate-limiting and tunnel conflicts.
  • Console QuickEdit Bypass: Injects Win32 API calls via Add-Type (kernel32.dll) to disable Windows Terminal/PowerShell QuickEdit mode on startup, preventing accidental console pauses caused by mouse clicks.
  • Automated SSH Authentication Bypass: Implements a localized .cmd stub via SSH_ASKPASS and streams blank inputs directly to the SSH standard input handle to bypass interactive prompts non-interactively.
  • 75-Minute Watchdog: Features a hard ceiling termination safeguard that force-kills un-recycled SSH instances running past 75 minutes to reset the cycle cleanly.

Logging and Telemetry

  • Automated Rotation: Writes structured, timestamped output to daily log files located at %USERPROFILE%\TRN_Gateway_Logs\gateway_YYYY-MM-DD.log.
  • Real-Time Terminal Telemetry: Outputs cycle iteration counts, active session duration, assigned public sockets, and DNS sync statuses to the console.

Technical Specifications

Architecture Map

+-------------------------------------------------------------+
| Local Host Environment (Windows 10/11)                      |
|                                                             |
|  +--------------------------+                               |
|  | Minecraft Server (Paper) |                               |
|  | Listening on :25566      |                               |
|  +------------^-------------+                               |
|               | localhost                                   |
|  +------------+-------------------------------------------+ |
|  | TRN Gateway v3 (PowerShell Orchestrator)               | |
|  |                                                        | |
|  |  [Active Tunnel Worker]                                | |
|  |   └─> ssh -p 443 -R0:localhost:25566 tcp@a.pinggy.io   | |
|  |                                                        | |
|  |  [Hot-Swap Worker (T+55m)]                             | |
|  |   └─> ssh -p 443 -R0:localhost:25566 tcp@a.pinggy.io   | |
|  +------------|-------------------------------------------+ |
+---------------|---------------------------------------------+
                |
                | Parses assigned dynamic socket (e.g., tcp://a.pinggy.io:XXXXX)
                v
+-------------------------------------------------------------+
| Hostinger API Endpoint                                      |
| DELETE /api/dns/v1/zones/therealneighbors.online            |
| PUT    /api/dns/v1/zones/therealneighbors.online            |
|                                                             |
| Payload:                                                    |
| Name:    _minecraft._tcp.play                               |
| Type:    SRV                                                |
| TTL:     60                                                 |
| Content: 0 5 <TunnelPort> <TunnelHost>.                     |
+-------------------------------------------------------------+
                |
                v
+-------------------------------------------------------------+
| Client Resolution Flow                                      |
| Player joins: play.therealneighbors.online                  |
| Resolves SRV -> <Dynamic Host Pinggy>:<Dynamic Port>        |
+-------------------------------------------------------------+

Configuration Variables

Variable Default Value Description
$RootDomain therealneighbors.online Hostinger DNS zone identifier
$SrvRecordName _minecraft._tcp.play Subdomain structure for Minecraft SRV records
$LocalPort 25566 Target server port forwarded by Pinggy
$Priority 0 SRV priority weight
$Weight 5 SRV load distribution weight
$TTL 60 Time-To-Live in seconds for DNS records
$HotSwapMinute 55 Elapsed minutes before initiating replacement tunnel

Infrastructure Topology

Java Edition Path

  • Connect Address: play.therealneighbors.online
  • Port Entry Required: No (SRV record routes directly to Pinggy dynamic port)
  • Underlying Protocol: TCP
  • Ingress Flow: Client -> Hostinger SRV Resolution -> Pinggy Relay -> Local OpenSSH Reverse Port Forward (localhost:25566)

Bedrock Edition Path

  • Connect Address: bedrock.therealneighbors.online
  • Port Entry Required: 50909
  • Underlying Protocol: UDP
  • Ingress Flow: Client -> Hostinger A Record (147.185.221.31) -> playit.gg UDP Relay -> Local Port Forward (Unchanged)

System Requirements

  • Operating System: Windows 10 or Windows 11
  • Execution Environment: Windows PowerShell 5.1 or PowerShell 7+
  • Dependencies: Native Windows OpenSSH Client (ssh.exe accessible in $env:PATH)
  • Network Access: Outbound TCP port 443 open to a.pinggy.io
  • Authentication: Hostinger API token stored in local .env with DNS Zone management scope

Installation and Deployment

  1. Repository Layout: Ensure the script and environment files reside in the deployment directory:

    TheRealNeighborsMinecraftSetup/
├── .env
├── .gitignore
├── minecraft-tunnel-autostart.ps1
└── README.md

  2. Secret Configuration: Create .env in the working directory:

    HostingerToken=YOUR_HOSTINGER_API_TOKEN_HERE

  3. Execution Policy: Ensure the executing user account permits local script execution:

    Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

  4. Manual Invocation:

    .\minecraft-tunnel-autostart.ps1

  5. Automated Boot Task (Windows Task Scheduler):

    • Action: Start a program
    • Program/script: powershell.exe
    • Arguments: -ExecutionPolicy Bypass -WindowStyle Hidden -File "C:\Path\To\TheRealNeighborsMinecraftSetup\minecraft-tunnel-autostart.ps1"
    • Run with highest privileges enabled.

Full Changelog: https://github.com/CyberSphinxxx/TunnelKeeper/commits/v1.0.0

Loading