aljaz/lightning
1
0
Fork 0
mirror of https://github.com/aljazceru/lightning.git synced 2026-01-09 09:04:25 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc/TOR.md: simplify, and don't cover autotor.

Browse Source 
autotor is older, but statictor is better.  Your options are really
"use HiddenServiceDir in torrc" vs "use statictor", with the issue
that statictor requires you to configure Tor for control access by
c-lightning.

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
This commit is contained in:
Rusty Russell
2021-11-10 10:57:41 +10:30
committed by Christian Decker
parent 2a35f33cb0
commit 3dcab9793d
1 changed files with 158 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files

394
doc/TOR.md
View File

@@ -35,6 +35,7 @@ To provide the node with a .onion address you can:
* create a **persistent** address with a hidden service.
### Quick Start On Linux
It is easy to create a single persistent Tor address and not announce a public IP.
@@ -176,117 +177,20 @@ on those.
### Detailed Discussion
#### Creation of an auto service for non-persistent .onion addresses
#### Three Ways to Create .onion Addresses for C-lightning
To provide the node a non-persistent .onion address it
is necessary to access the Tor auto service. These types of addresses change
each time the Tor service is restarted.
You have have Tor create an onion address for you, and tell
c-lightning to use that, or you can have c-lightning tell Tor to
create the same onion address every time it starts up, or you can have
c-lightning tell Tor to create a new onion address every time.
*NOTE:If the node is required to be reachable only by **persistent** .onion addresses, this
part can be skipped and it is necessary to set up a hidden service with the steps
outlined in the next section.*
#### Tor-Created .onion Address
To create and use the auto service follow these steps:
Having Tor create an onion address lets you run other services (e.g.
a web server) at that same address, and you just tell that address to
c-lightning and it doesn't have to talk to the Tor server at all.
Edit the Tor config file `/etc/tor/torrc`
You can configure the service authenticated by cookie or by password:
##### Service authenticated by cookie
Add the following lines in the `/etc/tor/torrc` file:
```
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```
##### Service authenticated by password
Alternatively, you can set the authentication
to the service with a password by following these steps:
1. Create a hash of your password with
```
tor --hash-password yourpassword
```
This returns a line like
`16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F`
2. put these lines in the `/etc/tor/torrc` file:
```
ControlPort 9051
HashedControlPassword 16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F
```
Save the file and restart the Tor service. In linux:
`/etc/init.d/tor restart` or `sudo systemctl start tor` depending
on the configuration of your system.
The auto service is used by adding `--addr=autotor:127.0.0.1:9051` if you
want the address to be public or `--bind-addr=autotor:127.0.0.1:9051` if you
don't want to publish it.
In the case where the auto service is authenticated through a password, it will
be necessary to add the option `--tor-service-password=yourpassword` (not the hash).
The created non-persistent .onion address will be shown by the `lightning-cli getinfo`
command. The other nodes will be able to `connect` to this .onion address through the
9735 port.
#### Creation of a hidden service for a persistent .onion address
To have a persistent .onion address other nodes can connect to, it
is necessary to set up a [Tor Hidden Service].
*NOTE: In the case where only non-persistent addresses are required,
you don't have to create the hidden service and you can skip this part.*
##### Automatic persistent .onion address
It is possible to generate persistent .onion addresses automatically.
Add the following lines in the `/etc/tor/torrc` file
(you might already have done this if for example you connected Bitcoin
over Tor):
```
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```
Then you can use `--addr=statictor:127.0.0.1:9051` instead of
`--announce-addr=.onionAddressV3`.
Note that you have to specify a `--bind-addr` first before using
`--addr=statictor:`.
Generally `--bind-addr=127.0.0.1:9735` should work fine.
You can also have multiple persistent .onion addresses
by adding `/torblob=BLOB`, where `BLOB` is 32 to 64 ***random***
bytes of text.
Note that this blob will be used to derive the secret key behind
the .onion address and you should keep the blob secret otherwise
anyone who steals it can spoof your .onion address and block
incoming data to your node via this .onion address.
You can then specify multiple `statictor:` options with different
`BLOB`s.
It is still possible for other nodes to contact you by those
other hidden services.
Finally, the default external port number for the autogenerated
persistent .onion address will be 9735, but you can change this by
adding `/torport=9999` to change the external port for the .onion
address.
##### Explicit Control
If you want to create your own hidden address, the whole section will be:
Put the following in your `/etc/tor/torrc` file:
```
HiddenServiceDir /var/lib/tor/lightningd-service_v3/
@@ -296,40 +200,114 @@ HiddenServicePort 1234 127.0.0.1:9735
The hidden lightning service will be reachable at port 1234 (global port)
of the .onion address, which will be created at the restart of the
Tor service. Both types of addresses can coexist on the same node.
Tor service. Both types of addresses can coexist on the same node.
Save the file and restart the Tor service. In linux:
`/etc/init.d/tor restart` or `sudo systemctl start tor` depending
on the configuration of your system.
You will find the newly created address with:
You will find the newly created address (myaddress.onion) with:
```
sudo cat /var/lib/tor/lightningd-service_v3/hostname
```
Now you are able to create:
Now you need to tell c-lightning to advertize that onion hostname and
port, by placing `announce-addr=myaddress.onion` in your lightning
config.
* Persistent version 3 hidden services.
#### Letting C-lightning Control Tor
To have c-lightning control your Tor addresses, you have to tell Tor
to accept control commands from c-lightning, either by using a cookie,
or a password.
##### Service authenticated by cookie
This tells Tor to create a cookie file each time: lightningd will have
to be in the same group as tor (e.g. debian-tor): you can look at
`/run/tor/control.authcookie` to check the group name.
Add the following lines in the `/etc/tor/torrc` file:
```
ControlPort 9051
CookieAuthentication 1
CookieAuthFileGroupReadable 1
```
Save the file and restart the Tor service.
##### Service authenticated by password
This tells Tor to allow password access: you also need to tell lightningd
what the password is.
Create a hash of your password with
```
tor --hash-password yourpassword
```
This returns a line like
`16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F`
Put these lines in the `/etc/tor/torrc` file:
```
ControlPort 9051
HashedControlPassword 16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F
```
Save the file and restart the Tor service.
Put `tor-service-password=yourpassword` (not the hash) in your
lightning configuration file.
##### C-Lightning Creating Persistent Hidden Addresses
This is usually better than transient addresses, as nodes won't have
to wait for gossip propagation to find out your new address each time
you restart.
Once you've configured access to Tor as described above, you need
to add *two* lines in your lightningd config file:
1. A local address which lightningd can tell Tor to connect to when
connections come in, e.g. `bind-addr=127.0.0.1:9735`.
2. After that, a `addr=statictor:127.0.0.1:9051` to tell
c-lightning to set up and announce a Tor onion address (and tell
Tor to send connections to our real address, above).
You can use `bind-addr` if you want to set up the onion address and
not announce it to the world for some reason.
You may add more `addr` lines if you want to advertize other
addresses.
There is an older method, called "autotor" instead of "statictor"
which creates a different Tor address on each restart, which is
usually not very helpful; you need to use `lightning-cli getinfo` to
see what address it is currently using, and other peers need to wait
for fresh gossip messages if you announce it, before they can connect.
Let's see how to use them.
### What do we support
| Case # | IP Number | Hidden service |Incoming / Outgoing Tor |
| ------- | ------------- | ------------------------- |-------------------------
| 1 | Public | NO | Outgoing |
| 6 | Public | v3 | Incoming [1] |
| 7 | Not Announced | v3 | Incoming |
| 8 | Public | NO | Outcoing socks5 . |
| 2 | Public | FIXED BY TOR | Incoming [1] |
| 3 | Public | FIXED BY C-LIGHTNING | Incoming [1] |
| 4 | Not Announced | FIXED BY TOR | Incoming [1] |
| 5 | Not Announced | FIXED BY C-LIGHTNING | Incoming [1] |
NOTE:
1. In all the "Incoming" use case, the node can also make "Outgoing" Tor
connections (connect to a .onion address) by adding the
`--proxy=127.0.0.1:9050` option.
connections (connect to a .onion address) by adding the `proxy=127.0.0.1:9050` option.
#### Case #1 c-lightning has a public IP address and no Tor hidden service address, but can connect to an onion address via a Tor socks 5 proxy.
#### Case #1: Public IP address and no Tor address, but can connect to Tor addresses
Without a .onion address, the node won't be reachable through Tor by other
nodes but it will always be able to `connect` to a Tor enabled node
@@ -337,7 +315,7 @@ nodes but it will always be able to `connect` to a Tor enabled node
service socks5 proxy. When the Tor service starts it creates a socks5
proxy which is by default at the address 127.0.0.1:9050.
If the node is started with the option `--proxy=127.0.0.1:9050` the node
If the node is started with the option `proxy=127.0.0.1:9050` the node
will be always able to connect to nodes with .onion address through the socks5
proxy.
@@ -345,18 +323,22 @@ proxy.
Tor capabilities.**
If you want to `connect` to nodes ONLY via the Tor proxy, you have to add the
`--always-use-proxy=true` option.
`always-use-proxy=true` option (though if you only advertize Tor addresses,
we also assume you want to always use the proxy).
You can announce your public IP address through the usual method:
You can announce your public IP address through the usual method: if
your node is in an internal network:
```
--bind-addr=internalIPAddress:port --announce-addr=externalIpAddress
bind-addr=internalIPAddress:port
announce-addr=externalIpAddress
```
if the node is into an internal network
or if it has a public IP address:
```
--addr=externalIpAddress
addr=externalIpAddress
```
if the node is not inside an internal network.
TIP: If you are unsure which of the two is suitable for you, find your internal
and external address and see if they match.
@@ -369,142 +351,82 @@ and your internal IP Address with: `ip route get 1 | awk '{print $NF;exit}'`
If they match you can use the `--addr` command line option.
#### Case #2 c-lightning has a public IP address and a fixed Tor hidden service address that is persistent, so that external users can connect to this node.
#### Case #2: Public IP address, and a fixed Tor address in torrc
To have your external IP address and your .onion address announced, you use the
```
--bind-addr=yourInternalIPAddress:port --announce-addr=yourexternalIPAddress:port --announce-addr=your.onionAddress:port`
```
or
```
--bind-addr=yourInternalIPAddress:port --announce-addr=yourexternalIPAddress:port --addr=statictor:127.0.0.1:9051`
```
options.
Other nodes can connect to you entirely over Tor, and the Tor address
doesn't change every time you restart.
You simply tell c-lightning to advertize both addresses (you can use
`sudo cat /var/lib/tor/lightningd-service_v3/hostname` to get your
Tor-assigned onion address).
If you have an internal IP address:
If you are not inside an internal network you can use
```
--addr=yourIPAddress:port --announce-addr=your.onionAddress:port
```
or
```
--addr=yourIPAddress:port --addr=statictor:127.0.0.1:9051
bind-addr=yourInternalIPAddress:port
announce-addr=yourexternalIPAddress:port
announce-addr=your.onionAddress:port
```
your.onionAddress is the one created with the Tor hidden service ([see above](#creation-of-an-hidden-service-for-a-persistent-onion-address)).
The port is the one indicated as the hidden service port. If the hidden service creation
line is `HiddenServicePort 1234 127.0.0.1:9735` the .onion address will be reachable at
the 1234 port (the global port).
For `statictor` the `127.0.0.1` is your computer, and `9051` is the
Tor Control Port you set up in the `/etc/tor/torrc` file.
It will be possible to connect to this node with:
Or an external address:
```
lightning-cli connect nodeID .onionAddress globalPort
addr=yourIPAddress:port
announce-addr=your.onionAddress:port
```
through Tor where .onion address is in the form `xxxxxxxxxxxxxxxxxxxxxxxxxx.onion`, Or
#### Case #3: Public IP address, and a fixed Tor address set by C-lightning
Other nodes can connect to you entirely over Tor, and the Tor address
doesn't change every time you restart.
See "Letting C-lightning Control Tor" for how to get c-lightning
talking to Tor.
If you have an internal IP address:
```
lightning-cli connect nodeID yourexternalIPAddress Port
bind-addr=yourInternalIPAddress:port
announce-addr=yourexternalIPAddress:port
addr=statictor:127.0.0.1:9051
```
through Clearnet.
#### Case #3 c-lightning has a public IP address and a non-persistent Tor service address
In this case other nodes can connect to you via Clearnet or Tor.
To announce your IP address to the network, you add:
Or an external address:
```
--bind-addr=internalAddress:port --announce-addr=yourExternalIPAddress
addr=yourIPAddress:port
addr=statictor:127.0.0.1:9051
```
or `--addr=yourExternalIPAddress`if you are NOT on an internal network.
To get your non-persistent Tor address, add
`--addr=autotor:127.0.0.1:9051` if you want to announce it or
`--bind-addr=autotor:127.0.0.1:9051` if you don't want to announce it.
#### Case #4: Unannounced IP address, and a fixed Tor address in torrc
If the auto service is protected by password ([see above](#service-authenticated-by-password)) it is necessary to
specify it with the option `--tor-service-password=yourpassword` (not the hash).
Other nodes can only connect to you over Tor.
You will obtain the generated non persisten .onion address by reading the results of the
`lightning-cli getinfo` command. Other nodes will be able to connect to the
.onion address through the 9735 port.
You simply tell c-lightning to advertize the Tor address (you can use
`sudo cat /var/lib/tor/lightningd-service_v3/hostname` to get your
Tor-assigned onion address).
#### Case #4 c-lightning has no public IP address, but has a fixed Tor hidden service address that is persistent
Other nodes can connect to the announced .onion address created with the
hidden service ([see above](#creation-of-an-hidden-service-for-a-persistent-onion-address)).
In this case In the `lightningd` command line you will specify:
```
--bind-addr=yourInternalIPAddress:port --announce-addr=your.onionAddress:port
announce-addr=your.onionAddress:port
proxy=127.0.0.1:9050
always-use-proxy=true
```
or `--addr=your.onionAddress:port` if you are NOT on an internal network.
#### Case #5 c-lightning has no public IP address, and has no fixed Tor hidden service address
#### Case #4: Unannounced IP address, and a fixed Tor address set by C-lightning
Other nodes can only connect to you over Tor.
See "Letting C-lightning Control Tor" for how to get c-lightning
talking to Tor.
In this case it is difficult to track the node.
You specify just:
```
--bind-addr=yourInternalIPAddress:port --addr=autotor:127.0.0.1:9051
```
In the `lightningd` command line.
Other nodes will not be able to `connect` to you unless you communicate them how to reach you.
You will find your .onion address with the command `lightning-cli getinfo` and the other nodes will
be able to connect to it through the 9735 port.
#### Case #6 c-lightning has a public IP address and a fixed Tor hidden service
You will be reachable via Clearnet, via Tor to the .onion if it is communicated to the node that wants to
connect with our node.
To make your external IP address public you add:
```
--bind-addr=yourInternalAddress:port --announce-addr=yourexternalIPAddress:port`.
```
If the node is not on an internal network the option will be:
`--addr=yourexternalIPAddress:port`.
Once the .onion addresses have been created with the procedures [oulined above](#creation-of-an-hidden-service-for-a-persistent-onion-address),
the node is already reachable at the .onion address.
To make your external hidden service public you add:
```
--announce-addr=.onionAddressV3:port
```
to the options to publish your IP number.
#### Case #7 c-lightning has no public IP address, a fixed Tor hidden service
The Persistent addresses can be created with the steps [outlined above](#creation-of-an-hidden-service-for-a-persistent-onion-address).
To create your non-persistent Tor address, add
`--addr=autotor:127.0.0.1:9051` if you want to announce it or
`--bind-addr=autotor:127.0.0.1:9051` if you don't want to announce it.
Also you must specify `--tor-service-password=yourpassword` (not the hash) to access the
Tor service at 9051 If you have protected them with the password (no additional options if
they are protected with a cookie file. [See above](#creation-of-an-auto-service-for-non-persistent-onion-addresses)).
To make your external onion service public you add:
```
--bind-addr=yourInternalIPAddress:port --announce-addr=your.onionAddressV3:port
```
#### Case #8 c-lightning has a public IP address and no Tor addresses
The external address is communicated by the
```
--bind-addr=internalIPAddress:port --announce-addr=yourexternalIPAddress:port`
```
or `--addr=yourexternalIPAddress:port` if the node is not inside an internal network.
The node can connect to any V4/6 ip address via a IPV4/6 socks 5 proxy by specifing
```
--proxy=127.0.0.1:9050 --always-use-proxy=true
addr=statictor:127.0.0.1:9051
proxy=127.0.0.1:9050
always-use-proxy=true
```
## References
The lightningd-config manual page covers the various address cases in detail.
[The Tor project](https://www.torproject.org/)
[tor FAQ]: https://www.torproject.org/docs/faq.html.en#WhatIsTor