Documentation

Setup Guide

Comprehensive documentation for setting up, configuring, and optimizing your TunnelSats VPN connection.

TunnelSats: Hybrid Lightning Node Setup

Overview

TunnelSats simplifies running a hybrid Lightning node by routing clearnet traffic through a VPN while maintaining Tor connectivity. This guide helps you configure your node for optimal reliability, liquidity, and discoverability.

Key Benefits:

  • Clearnet connectivity for faster routing
  • Privacy-preserving VPN tunneling
  • Tor fallback for additional privacy
  • Simplified setup process

Important: Review this entire guide before proceeding. Understand the implications of exposing clearnet connections before enabling hybrid mode.

Prerequisites

Supported Node Platforms

  • RaspiBlitz (LND/CLN) v1.8.0+
  • Umbrel (LND) v0.5+ on Raspberry Pi
  • myNode (LND) v0.2.x
  • RaspiBolt (LND/CLN)
  • Bare Metal Systems meeting these requirements:
    • Debian/Ubuntu-based OS (apt-get required)
    • Linux kernel 5.10.102+ (check: uname -r)
    • nftables 0.9.6+ (check: nft -v)
    • LND/CLN running as systemd service

Software Requirements

  • LND 0.14.2-beta minimum (latest recommended)
  • CLN latest version
  • Only one Lightning implementation per system (port 9735)
  • Ability to edit configuration files
  • Small amount of sats for subscription payment

System Check: Run sudo bash tunnelsats.sh check to verify compatibility.

How It Works

TunnelSats operates in three stages:

  1. VPN Subscription – Rent a WireGuard server from tunnelsats.com and obtain your configuration file
  2. Software Installation – Install WireGuard, nftables, and split-tunneling components
  3. Node Configuration – Update your Lightning node settings for hybrid mode

TunnelSats Banner

Installation

Step 1: Subscribe to TunnelSats

  1. Visit tunnelsats.com
  2. Select a server location (choose one close to your physical location for best performance)
  3. Choose subscription duration (1-12 months)
  4. Pay the Lightning invoice
  5. Download the tunnelsats_<server>.conf file (e.g., tunnelsats_us3.conf)

Critical: Back up your configuration file to a safe location (e.g., /mnt/hdd/app-data/tunnelsats/ on RaspiBlitz).

Step 2: Install TunnelSats Software

Download the unified setup script and its checksum:

bash
wget -O tunnelsats.sh https://raw.githubusercontent.com/Tunnelsats/tunnelsats/9833b9ee28877a7597f5737327c6ec38da916bfe/scripts/tunnelsats.sh && wget -O tunnelsats.sh.sha256 https://raw.githubusercontent.com/Tunnelsats/tunnelsats/9833b9ee28877a7597f5737327c6ec38da916bfe/scripts/tunnelsats.sh.sha256
# Checksum (SHA256): 3f396e96b11e763e5b4c41d3b940ddb9914a747c348fb0533ed7db6fc6e8e258

Verification: Always verify the integrity of executed scripts. Run the following to compare the script against its checksum file:

bash
sed 's|scripts/||' tunnelsats.sh.sha256 > tunnelsats.sh.sha256.local && sha256sum -c --ignore-missing tunnelsats.sh.sha256.local && rm tunnelsats.sh.sha256.local

Note: This command corrects the path in the checksum file and then verifies the script integrity.

Transfer your WireGuard configuration to your node (if not already there):

bash
scp tunnelsats_us3.conf <user>@<hostname>:/<home-directory>

Example for Umbrel:

bash
scp tunnelsats_us3.conf [email protected]:/home/umbrel/

Ensure both files (tunnelsats_us3.conf and tunnelsats.sh) are in the same directory, then run the installer:

bash
sudo bash tunnelsats.sh install

Upon successful completion, the script displays your VPN credentials and configuration parameters. Save these values – you'll need them to configure your Lightning node.

Configuration

Before proceeding: Back up your configuration file!

bash
cp /path/to/lnd.conf /path/to/lnd.conf.backup

Choose your Lightning implementation below:

Verification

Once you've completed the configuration, verify that your connection is working by running:

sh
sudo bash tunnelsats.sh status

This acts as a "Headless Status Page" for your node, checking VPN connectivity, Tor status, and Public IP visibility.

Subscription Renewal

Extend your subscription without reconfiguration:

  1. Visit tunnelsats.com → Renew Subscription
  2. Enter your WireGuard public key (found in tunnelsats_*.conf as # myPubKey).
  3. Click Query Key Info to view your current expiry date
  4. Select extension duration (appends to current expiry)
  5. Click Update Subscription and pay the invoice

Alternately, you can manage your subscription directly in My Dashboard.

In either case, your existing configuration remains valid – no changes needed.

Uninstallation

To remove TunnelSats and restore your original configuration:

bash
sudo bash tunnelsats.sh uninstall

Restore your Lightning configuration from the backup you created earlier. The uninstall script removes hybrid mode settings to prevent IP leakage.

Technical Details

What does tunnelsats.sh do?

This unified script manages the entire lifecycle of the TunnelSats connection:

  1. Install: Installs components (wireguard, cgroup-tools, nftables), configures split-tunneling, and creates systemd services.
  2. Status: Provides a comprehensive health check of the connection.
  3. Uninstall: Cleanly removes all components and restores network settings.
  4. Restart: Restarts the TunnelSats service. (Warning: Stops and restarts your lightning services to avoid IP leakage)
  5. Pre-Check: Checks if your node is compatible with TunnelSats.

Support