diff --git a/docs/configuring_tor.md b/docs/configuring_tor.md index d4395fb1..eebef286 100644 --- a/docs/configuring_tor.md +++ b/docs/configuring_tor.md @@ -1,24 +1,29 @@ # Table of Contents -1. [Overview](#Overview) -2. [Outbound Connections Only](#outbound-connections-only) +1. [Overview](#overview) +2. [Getting Started](#getting-started) 3. [Tor Stream Isolation](#tor-stream-isolation) +4. [Listening for Inbound Connections](#listening-for-inbound-connections) + 1. [v2 Onion Services](#v2-onion-services) + 2. [v3 Onion Services](#v3-onion-services) -## 1. Overview +## Overview -`lnd` currently has _partial_ support for using Lightning over +`lnd` currently has complete support for using Lightning over [Tor](https://www.torproject.org/). Usage of Lightning over Tor is valuable as routing nodes no longer need to potentially expose their location via their advertised IP address. Additionally, leaf nodes can also protect their location -by using Tor for anonymous networking to establish connections. +by using Tor for anonymous networking to establish connections. -At the time of the writing of this documentation, `lnd` only supports usage of -Tor for establishing _outbound_ connections. In the near future, support for -full [Onion Service](https://www.torproject.org/docs/onion-services.html.en) -usage will be added as well. Support for both `v2` and `v3` onion services are -planned. With widespread usage of Onion Services within the network, concerns -about the difficulty of proper NAT traversal are alleviated, as usage of Onion -Services allows nodes to accept inbound connections even if they're behind a -NAT. +With widespread usage of Onion Services within the network, concerns about the +difficulty of proper NAT traversal are alleviated, as usage of Onion Services +allows nodes to accept inbound connections even if they're behind a NAT. + +At the time of writing this documentation, `lnd` supports both types of onion +services: v2 and v3. However, only v2 onion services can automatically be +created and set up by `lnd` until Tor Control support for v3 onion services is +implemented in the stable release of the Tor daemon. v3 onion services can be +used as long as they are set up manually. We'll cover the steps on how to do +these things below. Before following the remainder of this documentation, you should ensure that you already have Tor installed locally. Official instructions to install the @@ -26,29 +31,19 @@ latest release of Tor can be found [here](https://www.torproject.org/docs/tor-doc-unix.html.en). **NOTE**: This documentation covers how to ensure that `lnd`'s _Lightning -protocol traffic_ is tunnled over Tor. Users will need to take care that if -they're running using a Bitcoin full-node, then that is also configured to -proxy all trafic over Tor. If using the `neutrino` backend for `lnd`, then it -will automatically also default to Tor usage if active within `lnd`. +protocol traffic_ is tunneled over Tor. Users must ensure that when also running +a Bitcoin full-node, that it is also proxying all traffic over Tor. If using the +`neutrino` backend for `lnd`, then it will automatically also default to Tor +usage if active within `lnd`. - -## 2. Outbound Connections Only - -Currenty, `lnd` only supports purely _outbound_ Tor usage. In this mode, `lnd` -_won't_ listen at all, and will only be able to establish outbound connections. -_All_ protocol traffic will be tunneled over Tor. Additionally, we'll also -force any DNS requests over Tor such that we don't leak our IP address to the -clear net. - -The remainder of this tutorial assumes one already has the `tor` daemon -installed locally. +## Getting Started First, you'll want to run `tor` locally before starting up `lnd`. Depending on how you installed Tor, you'll find the configuration file at `/usr/local/etc/tor/torrc`. Here's an example configuration file that we'll be using for the remainder of the tutorial: ``` -SOCKSPort 9050 # Default: Bind to localhost:9050 for local connections. +SOCKSPort 9050 Log notice stdout ControlPort 9051 CookieAuthentication 1 @@ -84,28 +79,49 @@ At this point, we can now start `lnd` with the relevant arguments: Tor: - --tor.socks= The port that Tor's exposed SOCKS5 proxy is listening on. Using Tor allows outbound-only connections (listening will be disabled) -- NOTE port must be between 1024 and 65535 - --tor.dns= The DNS server as IP:PORT that Tor will use for SRV queries - NOTE must have TCP resolution enabled + --tor.active Allow outbound and inbound connections to be routed through Tor + --tor.socks= The port that Tor's exposed SOCKS5 proxy is listening on -- NOTE port must be between 1024 and 65535 (default: 9050) + --tor.dns= The DNS server as IP:PORT that Tor will use for SRV queries - NOTE must have TCP resolution enabled (default: soa.nodes.lightning.directory:53) + --tor.streamisolation Enable Tor stream isolation by randomizing user credentials for each connection. + --tor.controlport= The port that Tor is listening on for Tor control connections -- NOTE port must be between 1024 and 65535 (default: 9051) + --tor.v2 Automatically set up a v2 onion service to listen for inbound connections + --tor.v3 Use a v3 onion service to listen for inbound connections + --tor.privatekeypath= The path to the private key of the onion service being created (default: /Users/user/Library/Application Support/Lnd/onion_private_key) ``` -The `--tor.socks` argument should point to the interface that the `Tor` daemon -is listening on to proxy connections. The `--tor.dns` flag is required in order -to be able to properly automatically bootstrap a set of peer connections. The -`tor` daemon doesn't currently support proxying `SRV` queries over Tor. So -instead, we need to connect directly to the authoritative DNS server over TCP, -in order query for `SRV` records that we can use to bootstrap our connections. -As of the time this documentation was written, for Bitcoin's Testnet, clients -should point to `nodes.lightning.directory`. +There are a couple things here, so let's dissect them. The `--tor.active` flag +allows `lnd` to route all outbound and inbound connections through Tor. -Finally, we'll start `lnd` with the proper arguments: -``` -⛰ ./lnd --tor.socks=9050 --tor.dns=nodes.lightning.directory +Outbound connections are possible with the use of the `--tor.socks` and +`--tor.dns` arguments. The `--tor.socks` argument should point to the interface +that the `Tor` daemon is listening on to proxy connections. The `--tor.dns` flag +is required in order to be able to properly automatically bootstrap a set of +peer connections. The `tor` daemon doesn't currently support proxying `SRV` +queries over Tor. So instead, we need to connect directly to the authoritative +DNS server over TCP, in order query for `SRV` records that we can use to +bootstrap our connections. + +Inbound connections are possible due to `lnd` automatically creating a v2 onion +service. A path to save the onion service's private key can be specified with +the `--tor.privatekeypath` flag. A v3 onion service can also be used, but it +must be created manually. We'll expand on how this works in [Listening for +Inbound Connections](#listening-for-inbound-connections). + +Most of these arguments have defaults, so as long as they apply to you, routing +all outbound and inbound connections through Tor can simply be done with: +```shell +⛰ ./lnd --tor.active --tor.v2 ``` -With the above arguments, `lnd` will proxy _all_ network traffic over Tor! +Outbound support only can also be used with: +```shell +⛰ ./lnd --tor.active +``` +This will allow you to make all outgoing connections over Tor, but still allow +regular (clearnet) incoming connections. -## 3. Tor Stream Isolation +## Tor Stream Isolation Our support for Tor also has an additional privacy enhancing modified: stream isolation. Usage of this mode means that Tor will always use _new circuit_ for @@ -116,5 +132,56 @@ circuit. Activating stream isolation is very straightforward, we only require the specification of an additional argument: ``` -⛰ ./lnd --tor.socks=9050 --tor.dns=nodes.lightning.directory --tor.streamisolation +⛰ ./lnd --tor.active --tor.streamisolation ``` + +## Listening for Inbound Connections + +In order to listen for inbound connections through Tor, an onion service must be +created. There are two types of onion services: v2 and v3. + +### v2 Onion Services + +v2 onion services can be created automatically by `lnd` and are currently the +default. To do so, run `lnd` with the following arguments: +``` +⛰ ./lnd --tor.active --tor.v2 +``` + +This will automatically create a hidden service for your node to use to listen +for inbound connections and advertise itself to the network. The onion service's +private key is saved to a file named `onion_private_key` in `lnd`'s base +directory. This will allow `lnd` to recreate the same hidden service upon +restart. If you wish to generate a new onion service, you can simply delete this +file. The path to this private key file can also be modified with the +`--tor.privatekeypath` argument. + +### v3 Onion Services + +v3 onion services are the latest generation of onion services and they provide a +number of advantages over the legacy v2 onion services. To learn more about +these benefits, see [Intro to Next Gen Onion Services](https://trac.torproject.org/projects/tor/wiki/doc/NextGenOnions). + +Unfortunately, at the time of writing this, v3 onion service support is still +at an alpha level in the Tor daemon, so we're unable to automatically set them +up within `lnd` unlike with v2 onion services. However, they can still be run +manually! To do so, append the following lines to the torrc sample from above: +``` +HiddenServiceDir PATH_TO_HIDDEN_SERVICE +HiddenServiceVersion 3 +HiddenServicePort PORT_ONION_SERVICE_LISTENS_ON ADDRESS_LND_LISTENS_ON +``` + +If needed, instructions on how to set up a v3 onion service manually can be +found [here](https://trac.torproject.org/projects/tor/wiki/doc/NextGenOnions#Howtosetupyourownprop224service). + +Once the v3 onion service is set up, `lnd` is able to use it to listen for +inbound connections. You'll also need the onion service's hostname in order to +advertise your node to the network. To do so, run `lnd` with the following +arguments: +``` +⛰ ./lnd --tor.active --tor.v3 --externalip=ONION_SERVICE_HOSTNAME +``` + +Once v3 onion service support is stable, `lnd` will be updated to also +automatically set up v3 onion services.