eclair/docs/Tor.md

How to Use Tor with Eclair

Installing Tor on your node

Linux:

sudo apt install tor

Mac OS X:

brew install tor

Windows:

Download the "Expert Bundle" from Tor's website and extract it to C:\tor.

Configuring Tor

Linux and Max OS X:

Eclair requires safe cookie authentication as well as SOCKS5 and control connections to be enabled.

Edit Tor configuration file /etc/tor/torrc (Linux) or /usr/local/etc/tor/torrc (Mac OS X).

SOCKSPort 9050
ControlPort 9051
CookieAuthentication 1
ExitPolicy reject *:* # don't change this unless you really know what you are doing

Make sure eclair is allowed to read Tor's cookie file (typically /var/run/tor/control.authcookie).

Windows:

On Windows, it is easier to use the password authentication mechanism.

First pick a password and hash it with this command:

$ cd c:\tor\Tor
$ tor --hash-password this-is-an-example-password-change-it
16:94A50709CAA98333602756426F43E6AC6760B9ADEF217F58219E639E5A

Create a Tor configuration file (C:\tor\Conf\torrc), edit it and replace the value for HashedControlPassword with the result of the command above.

SOCKSPort 9050
ControlPort 9051
HashedControlPassword 16:--REPLACE--THIS--WITH--THE--HASH--OF--YOUR--PASSWORD--
ExitPolicy reject *:* # don't change this unless you really know what you are doing

Start Tor

Linux:

sudo systemctl start tor

Mac OS X:

brew services start tor

Windows:

Open a CMD with administrator access

cd c:\tor\Tor
tor --service install -options -f "c:\tor\Conf\torrc"

Configure Tor hidden service

To create a Tor hidden service endpoint simply set the eclair.tor.enabled parameter in eclair.conf to true.

eclair.tor.enabled = true

Next set the TOR authentication method. The choices are safecookie or password.

eclair.tor.auth = safecookie
# eclair.tor.password = ""      # Needed if you set auth to password

Eclair will automatically set up a hidden service endpoint and add its onion address to the server.public-ips list. You can see what onion address is assigned using eclair-cli:

eclair-cli getinfo

Eclair saves the Tor endpoint's private key in ~/.eclair/tor.dat, so that it can recreate the endpoint address after a restart. If you remove the private key Eclair will regenerate the endpoint address.

There are two possible values for protocol-version:

eclair.tor.protocol-version = "v3"

value	description
v2	set up a Tor hidden service version 2 end point
v3	set up a Tor hidden service version 3 end point (default)

Tor protocol v3 (supported by Tor version 0.3.3.6 and higher) is backwards compatible and supports both v2 and v3 addresses.

For increased privacy do not advertise your IP address in the server.public-ips list, and set your binding IP to localhost:

eclair.server.binding-ip = "127.0.0.1"

By default, the onion address generated by the hidden service will be added to the list of the node's public addresses. If you want to keep it private use this config parameter:

eclair.tor.publish-onion-address = false

You can always see your node's onion address using getinfo CLI command.

Configure SOCKS5 proxy

By default, all incoming connections will be established via Tor network, but all outgoing will be created via the clearnet. To route them through Tor you can use Tor's SOCKS5 proxy. Add this line in your eclair.conf:

eclair.socks5.enabled = true

You can use SOCKS5 proxy only for specific types of addresses. Use eclair.socks5.use-for-ipv4, eclair.socks5.use-for-ipv6 or eclair.socks5.use-for-tor for fine-tuning.

To create a new Tor circuit for every connection, use randomize-credentials parameter:

eclair.socks5.randomize-credentials = true

⚠️ Tor hidden service and SOCKS5 are independent options. You can use just one of them, but if you want to get most privacy features from using Tor, use both.

Note, that bitcoind should be configured to use Tor as well (https://en.bitcoin.it/wiki/Setting_up_a_Tor_hidden_service).

Blockchain watchdogs

Eclair version 0.5.0 introduced blockchain watchdogs, that fetch bitcoin headers from various sources in order to detect whether the node is being eclipsed. Eclair supports four sources at the moment:

• blockchainheaders.net
• blockcypher.com
• blockstream.info
• mempool.space

Once eclair.socks5.enabled is set to true blockchain watchdogs connect to their respective sources over Tor.

The most Tor-friendly sources are blockstream.info and mempool.space since they have native onion endpoints for their APIs.

Tor support for blockchainheaders.net is not implemented (yet), so it gets automatically disabled when eclair.socks5.enabled = true to protect user's privacy.

blockcypher.com can be flaky when used over Tor. It imposes rate limits and sometimes (rather often in fact) requires solving CAPTCHA. If you experience similar troubles with blockcypher.com use this config parameter to disable it:

eclair.blockchain-watchdog.sources = [
  "bitcoinheaders.net",
  "blockstream.info",
  "mempool.space"
]

Also, you can disable Tor for all watchdog sources altogether using:

eclair.socks5.use-for-watchdogs = false