diff --git a/doc/TOR.md b/doc/TOR.md index 4b87c5c05231..781af0cd70cf 100644 --- a/doc/TOR.md +++ b/doc/TOR.md @@ -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,82 +177,58 @@ on those. ### Detailed Discussion -#### Creation of an auto service for non-persistent .onion addresses - -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. - -*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.* - -To create and use the auto service follow these steps: - -Edit the Tor config file `/etc/tor/torrc` - -You can configure the service authenticated by cookie or by password: +#### Three Ways to Create .onion Addresses for C-lightning -##### Service authenticated by cookie -Add the following lines in the `/etc/tor/torrc` file: +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. -``` -ControlPort 9051 -CookieAuthentication 1 -CookieAuthFileGroupReadable 1 -``` +#### Tor-Created .onion Address -##### Service authenticated by password +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. -Alternatively, you can set the authentication -to the service with a password by following these steps: +Put the following in your `/etc/tor/torrc` file: -1. Create a hash of your password with ``` -tor --hash-password yourpassword +HiddenServiceDir /var/lib/tor/lightningd-service_v3/ +HiddenServiceVersion 3 +HiddenServicePort 1234 127.0.0.1:9735 ``` -This returns a line like - -`16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F` - -2. put these lines in the `/etc/tor/torrc` file: -``` -ControlPort 9051 -HashedControlPassword 16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F -``` +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. 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. +You will find the newly created address (myaddress.onion) with: +``` +sudo cat /var/lib/tor/lightningd-service_v3/hostname +``` -#### Creation of a hidden service for a persistent .onion address +Now you need to tell c-lightning to advertize that onion hostname and +port, by placing `announce-addr=myaddress.onion` in your lightning +config. -To have a persistent .onion address other nodes can connect to, it -is necessary to set up a [Tor Hidden Service]. +#### Letting C-lightning Control Tor -*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.* +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. -##### Automatic persistent .onion address +##### Service authenticated by cookie -It is possible to generate persistent .onion addresses automatically. +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 -(you might already have done this if for example you connected Bitcoin -over Tor): +Add the following lines in the `/etc/tor/torrc` file: ``` ControlPort 9051 @@ -259,77 +236,78 @@ 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. +Save the file and restart the Tor service. -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. +##### Service authenticated by password -It is still possible for other nodes to contact you by those -other hidden services. +This tells Tor to allow password access: you also need to tell lightningd +what the password is. -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. +Create a hash of your password with +``` +tor --hash-password yourpassword +``` -##### Explicit Control +This returns a line like -If you want to create your own hidden address, the whole section will be: +`16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F` +Put these lines in the `/etc/tor/torrc` file: ``` -HiddenServiceDir /var/lib/tor/lightningd-service_v3/ -HiddenServiceVersion 3 -HiddenServicePort 1234 127.0.0.1:9735 +ControlPort 9051 +HashedControlPassword 16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F ``` -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. +Save the file and restart the Tor service. -Save the file and restart the Tor service. In linux: +Put `tor-service-password=yourpassword` (not the hash) in your +lightning configuration file. -`/etc/init.d/tor restart` or `sudo systemctl start tor` depending -on the configuration of your system. +##### C-Lightning Creating Persistent Hidden Addresses -You will find the newly created address with: -``` -sudo cat /var/lib/tor/lightningd-service_v3/hostname -``` +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). -Now you are able to create: +You can use `bind-addr` if you want to set up the onion address and +not announce it to the world for some reason. -* Persistent version 3 hidden services. +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. - -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. +#### Case #2: Public IP address, and a fixed Tor address in torrc -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 -``` +Other nodes can connect to you entirely over Tor, and the Tor address +doesn't change every time you restart. -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). +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). -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. +If you have an internal IP address: -It will be possible to connect to this node with: -``` -lightning-cli connect nodeID .onionAddress globalPort -``` -through Tor where .onion address is in the form `xxxxxxxxxxxxxxxxxxxxxxxxxx.onion`, Or ``` -lightning-cli connect nodeID yourexternalIPAddress Port +bind-addr=yourInternalIPAddress:port +announce-addr=yourexternalIPAddress:port +announce-addr=your.onionAddress:port ``` -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 +announce-addr=your.onionAddress:port ``` -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. -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). +#### Case #3: Public IP address, and a fixed Tor address set by C-lightning -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. +Other nodes can connect to you entirely over Tor, and the Tor address +doesn't change every time you restart. -#### Case #4 c-lightning has no public IP address, but has a fixed Tor hidden service address that is persistent +See "Letting C-lightning Control Tor" for how to get c-lightning +talking to Tor. -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)). +If you have an internal IP address: -In this case In the `lightningd` command line you will specify: ``` ---bind-addr=yourInternalIPAddress:port --announce-addr=your.onionAddress:port +bind-addr=yourInternalIPAddress:port +announce-addr=yourexternalIPAddress:port +addr=statictor:127.0.0.1:9051 ``` -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 -In this case it is difficult to track the node. -You specify just: +Or an external address: ``` ---bind-addr=yourInternalIPAddress:port --addr=autotor:127.0.0.1:9051 +addr=yourIPAddress:port +addr=statictor: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 #4: Unannounced IP address, and a fixed Tor address in torrc -#### Case #6 c-lightning has a public IP address and a fixed Tor hidden service +Other nodes can only connect to you over Tor. -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. +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). -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 +announce-addr=your.onionAddress:port +proxy=127.0.0.1:9050 +always-use-proxy=true ``` -to the options to publish your IP number. -#### Case #7 c-lightning has no public IP address, a fixed Tor hidden service +#### Case #4: Unannounced IP address, and a fixed Tor address set by C-lightning -The Persistent addresses can be created with the steps [outlined above](#creation-of-an-hidden-service-for-a-persistent-onion-address). +Other nodes can only connect to you over Tor. -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. +See "Letting C-lightning Control Tor" for how to get c-lightning +talking to Tor. -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