🚑 Node Health & Upkeep

Maintaining a 24/7 VPN connection is essential for Lightning Node operations. This guide provides scripts to automate the monitoring and recovery of your TunnelSats tunnel.

🔍 1. Monitoring Tunnel Health

The most reliable way to check if your VPN is truly "Up" is to verify the WireGuard handshake.

Health Check Script

Save this script as tunnelsats-monitor.sh:

Finding your Interface Name

TunnelSats interface names match your config file. Run wg show | grep interface to confirm yours (usually tunnelsatsv2 or tunnelsats-region).

🛠️ 2. Auto-Healing & IP Migrations

TunnelSats nodes may occasionally migrate IPs for maintenance. If your handshake fails for more than 5 minutes, our internal logic likely updated the DNS.

The "Auto-Sync" Pattern

If your tunnel is down, don't just restart WireGuard. Instead, call the Sync API to get fresh data from the VPN server, or the Status API to check by WireGuard key.

Option A: Sync by Payment Hash (Authenticated)

Force a real-time refresh of subscription data. This verifies your peer is still active on the server.

Option B: Status by WireGuard Key (Unauthenticated)

Check bandwidth and expiry without needing an API key.

📉 3. Bandwidth Auto-Recovery

When your bandwidth exceeds 70% (approaching the 100GB soft cap), the VPN server may throttle or disable your peer. Automate recovery with the bandwidth-reset endpoint.

For the full bandwidth-reset documentation, see ⚡ Bandwidth Top-Up.

📊 4. Checking Server Status

Before you troubleshoot your local node, check if the TunnelSats region is online.

✅ Node Integration Checklist

For developers building integrations for Umbrel, Start9, or RaspiBlitz, follow this checklist to ensure a seamless user experience.

The Provisioning Flow

Server Selection: Use GET /api/public/v1/servers to allow users to pick the region closest to them.

In-App Payment: Display the BOLT11 invoice clearly.

Polling UI: Progress indicator while polling GET /api/public/v1/subscription/{paymentHash}.

Configuration Management

WireGuard Claim: Always offer a way to "Claim" the config again if the initial download fails.

Self-Healing: If wg show indicates no handshake for >3 minutes, automatically call /sync (authenticated) or /status (by key) to verify the server hasn't migrated.

Bandwidth Monitoring: Periodically check /status and warn users when bandwidth_used_gb exceeds 70GB.

Custom Keys

We recommend generating keys on our server (leaving wgPublicKey empty) for the easiest setup. However, for maximum privacy, allow advanced users to provide their own wgPublicKey.

Best Practices for Upkeep

Persist your paymentHash: Store it in a file like /mnt/data/tunnelsats.hash.

Add a Cron Job: Run the health check every 5 minutes: */5 * * * * /path/to/tunnelsats-monitor.sh.

Monitor Latency: If users report high latency, use POST /api/public/v1/ping/test to find a better region.

🔍 1. Monitoring Tunnel Health#

Health Check Script#

🛠️ 2. Auto-Healing & IP Migrations#

The "Auto-Sync" Pattern#

Option A: Sync by Payment Hash (Authenticated)#

Option B: Status by WireGuard Key (Unauthenticated)#

📉 3. Bandwidth Auto-Recovery#

📊 4. Checking Server Status#

✅ Node Integration Checklist#

The Provisioning Flow#

Configuration Management#

Best Practices for Upkeep#

🔍 1. Monitoring Tunnel Health

Health Check Script

🛠️ 2. Auto-Healing & IP Migrations

The "Auto-Sync" Pattern

Option A: Sync by Payment Hash (Authenticated)

Option B: Status by WireGuard Key (Unauthenticated)

📉 3. Bandwidth Auto-Recovery

📊 4. Checking Server Status

✅ Node Integration Checklist

The Provisioning Flow

Configuration Management

Best Practices for Upkeep