Skip to content

v1.0.0 - Initial Release

Choose a tag to compare

View all tags
@CyberSphinxxx CyberSphinxxx released this 07 Sep 18:23
· 23 commits to main since this release
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

Assets 2
Loading