The lightning network functions in rapid growing speed as infrastructure for payments across the globe between merchants, creators, consumers, institutions and investors alike. Hence the key pillars of sustained growth are their nodes, by providing reliable, liquid, discoverable, trustless and fast connection points between those parties. For fast communication establishing clearnet connections between nodes is inevitable.
The effort of creating a valuable "clearnet over VPN" node - which we laid out here and here - is quite high and intense because it touches several disciplines not every node runner is comfortable with. Required knowledge of the command line, firewall handling, network details, trust in and choosing of a suitable VPN provider that offers all the features we need and cares about privacy and security and, of course, the configuration of the lightning node itself makes it easy to just "leave it as is". Therefore we came to the conclusion that this process has to be simplified a lot. In the last few weeks we put together all the pieces that we think provide the best of both worlds to make it as easy as possible to go hybrid.
Although thinking this is a suitable way of providing a "hybrid service", we want to emphasize to carefully read through the guide below, make an educated decision by yourself if you want to go clearnet over VPN.
- Prelude and Objective
- Preconditions
- How this works
- Install
- Enabling hybrid mode
- Renew Subscription
- Uninstall
- Deep Dive
- Further Help
-
RaspiBlitz (LND / CLN) v1.8.0
-
Umbrel-OS (LND) 0.5+ recommended
-
Umbrel-OS (CLN not yet recommended or be tech-savvy)
-
myNode (LND) v0.2.x
-
RaspiBolt (LND / CLN)
-
For bare metal systems please check the following requirements:
- OS: Debian-/Ubuntu-based (apt-get required)
- Linux kernel version: 5.10.102+ (
uname -r
) - nftables version: 0.9.6+ (
nft -v
orapt search nftables | grep "^nftables"
) - LND running as systemd service:
/etc/systemd/system/lnd.service
or - CLN running as systemd service:
/etc/systemd/system/lightningd.service
- run
sudo bash check.sh
from/scripts/
directory to compare your system to TunnelSats' requirements
-
LND latest (minimal requirement
0.14.2-beta
) -
CLN latest
-
only one lightning implementation per system is supported (configured to port 9735)
-
edit your lightning configuration file (
lnd.conf
/config
) -
ability to spend some sats (the hardest part)
In order to understand the provided scripts and steps we gonna take a deep dive into our service. It is split into three parts:
-
Renting a VPN server and obtaining a corresponding WireGuard config file from tunnelsats.com,
-
installing required software and components to make VPN connection and Tor splitting work and
-
setting up the node for hybrid mode by editing the lightning configuration file as described below.
WireGuard is a fast, lightweight and secure VPN software. We offer a few WireGuard servers and quantum-safe VPN tunnels in various countries to choose from.
-
Go to tunnelsats.com, select a country of your choice (preferably close to your real location for faster connection speed) and choose how long you want to use the service (1 to 12 months).
-
Pay the lightning invoice.
-
Copy, download or send the wireguard configuration (file:
tunnelsatsv2.conf
- please do NOT rename this file) to your local computer and transfer it to your node. -
Backup
tunnelsatsv2.conf
to a safe place (to prevent deletion on updates, for example on RaspiBlitz create a new directory called/tunnelsats/
and save the config file in there:/mnt/hdd/app-data/tunnelsats/
) -
Download the setup script onto your node.
Download setup script:
$ wget -O setupv2.sh https://github.com/blckbx/tunnelsats/raw/main/scripts/setupv2.sh
Copy your WireGuard config file (tunnelsatsv2.conf
) to the same directory where setupv2.sh
is located. If you need to transfer it to your node, use scp
like so:
$ scp tunnelsatsv2.conf <user>@<ip/hostname>:/<path-to-home-dir>
e.g. for Umbrel: scp tunnelsatsv2.conf [email protected]:/home/umbrel/
Make sure that both files (tunnelsatsv2.conf and setupv2.sh) are located in the same directory. Then start it:
$ sudo bash setupv2.sh
If everything went fine, your selected VPN's credentials and further instructions are shown to adjust the lightning configuration file. Copy to file or write them down for later use (e.g. LND config):
#########################################
[Application Options]
listen=0.0.0.0:9735
externalhosts={vpnDNS}:{vpnPort}
[Tor]
tor.streamisolation=false
tor.skip-proxy-for-clearnet-targets=true
#########################################
Before applying any changes to your config files, please always create a backup! For example:
$ cp /path/to/lnd.conf /path/to/lnd.conf.backup
Running LND only requires a few parameters to be checked and set to activate hybrid mode. Locate lnd.conf
depending on your node setup. See the FAQ for some default path examples. Please edit the file and put the settings shown below into their corresponding sections. If any of these settings are already present, comment them out and add the new ones below. We need to add or modify the following settings:
[Application Options]
listen=0.0.0.0:9735
externalhosts={vpnDNS}:{vpnPort} #these infos are provided at the end of the setupv2.sh script
[Tor]
# set streamisolation to 'false' if currently set 'true'. if not set at all, just leave it out
tor.streamisolation=false
tor.skip-proxy-for-clearnet-targets=true
With CLN it's a bit trickier. Most node setups like Umbrel, RaspiBolt, RaspiBlitz etc. default CLN's daemon port to 9736
. So in order to route CLN clearnet over VPN, we need to change CLN's default port to 9735
. Locate data directory of your CLN installation. By default CLN's configuration is stored in a file named config
. Edit the file and look out for network settings section.
# Tor
addr=statictor:127.0.0.1:9051/torport=9735
proxy=127.0.0.1:9050
always-use-proxy=false
# Clearnet
bind-addr=0.0.0.0:9735
announce-addr={vpnDNS}:{vpnPort}
# Tor
addr=statictor:127.0.0.1:9051/torport=9736
proxy=127.0.0.1:9050
bind-addr=127.0.0.1:9736
always-use-proxy=false
# Clearnet
bind-addr=0.0.0.0:9735
announce-addr={vpnDNS}:{vpnPort}
On docker-based systems this might look very different. The following shows how to enable hybrid on Umbrel v0.5+:
- Apps installed: Bitcoin, CLN (LND may NOT be installed at the same time)
- Working Directory:
~/umbrel/app-data/core-lightning/
- File to look for:
export.sh
- Changes to be made:
export.sh: change port number from 9736 to 9735
export APP_CORE_LIGHTNING_DAEMON_PORT="9736"
change to
export APP_CORE_LIGHTNING_DAEMON_PORT="9735"
export.sh
is getting reset. So this change has to be done after every update procedure of CLN!
Additionally we create a persistent CLN config file (if not already provided. Umbrel 0.5+ does not initially.):
$ nano ~/umbrel/app-data/core-lightning/data/lightningd/bitcoin/config
and enter the following settings:
bind-addr=10.9.9.9:9735
always-use-proxy=false
announce-addr={vpnDNS}:{vpnPort}
Renewal of existing subscriptions has been reworked. Now it is possible to prolong your subscription by extending the current fixed term. Here is how it works:
- go to tunnelsats.com and select "Renew Subscription" on the navigation bar
- enter the WireGuard public key - find the key either
- commented out in your
tunnelsatsv2.conf
, look for#myPubKey
line (new subscriptions only) or - in your wireguard connection details extracted by running
sudo wg show | grep "public key"
- commented out in your
- click "Query Key Info" to fetch your current valid date
- select the desired term extension of your choice (it is appended to the current expiry)
- click "Update Subscription" and pay the lightning invoice
To restore all applied changes made to your node setup, download and run the uninstallv2 script. Furthermore remove entries from configuration files.
$ wget -O uninstallv2.sh https://github.com/blckbx/tunnelsats/raw/main/scripts/uninstallv2.sh
$ sudo bash uninstallv2.sh
Restore your configuration from with the backup file you (hopefully) created on setting up hybrid mode. The uninstall script will take care of the most important part to prevent real IP leaks by disabling/removing hybrid settings in respective configuration files.
What is the setupv2.sh
script doing in detail?
-
Checking if required components are already installed and if not, installing them. These are:
cgroup-tools
(for split-tunneling Tor),nftables
(VPN rules) andwireguard
(VPN software). -
Checking if
tunnelsatsv2.conf
exists in current directory (must be the same directory where setupv2 script is located). -
Setting up "split-tunneling" to exclude Tor traffic from VPN usage.
-
Enabling and starting required systemd services ([email protected], splitting.service) or network container for docker-based solutions.
-
Adding client-side nftables ruleset enabling kill-switching and preventing DNS leakage.
Please review the FAQ for further help. If you need help setting up hybrid mode over VPN or just want to have a chat with us, join our Tunnel⚡Sats Telegram group.
This service is brought to you by @ziggie1984 (Ziggie), @TrezorHannes (Hakuna) and @blckbx (osito).
Special thanks to @LightRider5 (lnvpn.net) for providing this amazing frontend framework and for help and support.