akovalenko/lnd.xprv
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: update v3 tor docs

Browse Source
This commit is contained in:
Wilmer Paulino 2018-07-06 19:36:07 -07:00
parent 95560238ce
commit 18528e9f3f
No known key found for this signature in database
GPG Key ID: 6DF57B9F9514972F
1 changed files with 32 additions and 61 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

93
docs/configuring_tor.md
View File

@ -15,19 +15,14 @@ advertised IP address. Additionally, leaf nodes can also protect their location
by using Tor for anonymous networking to establish connections.
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.
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.
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
latest release of Tor can be found
Before following the remainder of this documentation, you should ensure that you
already have Tor installed locally. Official instructions to install the 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
@ -80,13 +75,13 @@ At this point, we can now start `lnd` with the relevant arguments:
Tor:
--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.socks= The host:port that Tor's exposed SOCKS5 proxy is listening on (default: localhost:9050)
--tor.dns= The DNS server as host: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.control= The host:port that Tor is listening on for Tor control connections (default: localhost: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)
--tor.v3 Automatically set up a v3 onion service to listen for inbound connections
--tor.privatekeypath= The path to the private key of the onion service being created
```
There are a couple things here, so let's dissect them. The `--tor.active` flag
@ -101,25 +96,27 @@ 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
Inbound connections are possible due to `lnd` automatically creating an 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).
the `--tor.privatekeypath` flag.
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:
all outbound and inbound connections through Tor can simply be done with either
v2 or v3 onion services:
```shell
⛰ ./lnd --tor.active --tor.v2
```
```shell
⛰ ./lnd --tor.active --tor.v3
```
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.
This will allow you to make all outgoing connections over Tor. Listening is
disabled to prevent inadvertent leaks.
## Tor Stream Isolation
@ -138,50 +135,24 @@ specification of an additional argument:
## 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.
created. There are two types of onion services: v2 and v3. 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).
### v2 Onion Services
Both types can be created and used automatically by `lnd`. Specifying which type
should be used can easily be done by either using the `tor.v2` or `tor.v3` flag.
v2 onion services can be created automatically by `lnd` and are currently the
default. To do so, run `lnd` with the following arguments:
For example, v3 onion services can be used with the following flags:
```
⛰ ./lnd --tor.active --tor.v2
⛰ ./lnd --tor.active --tor.v3
```
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
private key is saved to a file named `v2_onion_private_key` or
`v3_onion_private_key` depending on the type of onion service used 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.