1# Setting up TOR with c-lightning 2 3To use any Tor features with c-lightning you must have Tor installed and running. 4 5Note that [Tor v2 onion services are deprecated since mid-2020](https://blog.torproject.org/v2-deprecation-timeline) 6and that C-lightning deprecated their support since mid-2021. 7 8You can check your installed Tor version with `tor --version` or `sudo tor --version` 9 10If Tor is not installed you can install it on Debian based Linux systems (Ubuntu, Debian, etc) with the following command: 11 12```bash 13sudo apt install tor 14``` 15then `/etc/init.d/tor start` or `sudo systemctl start tor` depending 16on your system configuration. 17 18Most default setting should be sufficient. 19 20To keep a safe configuration for minimal harassment (See [Tor FAQ]) 21just check that this line is present in the Tor config file `/etc/tor/torrc`: 22 23`ExitPolicy reject *:* # no exits allowed` 24 25This does not affect c-lightning connect, listen, etc.. 26It will only prevent your node from becoming a Tor exit node. 27Only enable this if you are sure about the implications. 28 29If you don't want to create .onion addresses this should be enough. 30 31There are several ways by which a c-lightning node can accept or make connections over Tor. 32 33The node can be reached over Tor by connecting to its .onion address. 34 35To provide the node with a .onion address you can: 36 37* create a **non-persistent** address with an auto service or 38 39* create a **persistent** address with a hidden service. 40 41### Quick Start On Linux 42 43It is easy to create a single persistent Tor address and not announce a public IP. 44This is ideal for most setups where you have an ISP-provided router connecting your 45Internet to your local network and computer, as it does not require a stable 46public IP from your ISP (which might not give one to you for free), nor port 47forwarding (which can be hard to set up for random cheap router models). 48Tor provides NAT-traversal for free, so even if you or your ISP has a complex 49network between you and the Internet, as long as you can use Tor you can 50be connected to. 51 52On most Linux distributions, making a standard installation of `tor` will 53automatically set it up to have a SOCKS5 proxy at port 9050. 54As well, you have to set up the Tor Control Port. 55On most Linux distributions there will be commented-out settings below in the 56`/etc/tor/torrc`: 57 58``` 59ControlPort 9051 60CookieAuthentication 1 61CookieAuthFileGroupReadable 1 62``` 63 64Uncomment those in, then restart `tor` (usually `systemctl restart tor` or 65`sudo systemctl restart tor` on most SystemD-based systems, including recent 66Debian and Ubuntu, or just restart the entire computer if you cannot figure 67it out). 68 69On some systems (such as Arch Linux), you may also need to add the following 70setting: 71 72``` 73DataDirectoryGroupReadable 1 74``` 75 76You also need to make your user a member of the Tor group. 77"Your user" here is whatever user will run `lightningd`. 78On Debian-derived systems, the Tor group will most likely be `debian-tor`. 79You can try listing all groups with the below command, and check for a 80`debian-tor` or `tor` groupname. 81 82``` 83getent group | cut -d: -f1 | sort 84``` 85 86Alternately, you could check the group of the cookie file directly. 87Usually, on most Linux systems, that would be `/run/tor/control.authcookie`: 88 89``` 90stat -c '%G' /run/tor/control.authcookie 91``` 92 93Once you have determined the `${TORGROUP}` and selected the 94`${LIGHTNINGUSER}` that will run `lightningd`, run this as root: 95 96``` 97usermod -a -G ${TORGROUP} ${LIGHTNINGUSER} 98``` 99 100Then restart the computer (logging out and logging in again should also 101work). 102Confirm that `${LIGHTNINGUSER}` is in `${TORGROUP}` by running the 103`groups` command as `${LIGHTNINGUSER}` and checking `${TORGROUP}` is listed. 104 105If the `/run/tor/control.authcookie` exists in your system, then log in as 106the user that will run `lightningd` and check this command: 107 108``` 109cat /run/tor/control.authcookie > /dev/null 110``` 111 112If the above prints nothing and returns, then C-Lightning "should" work 113with your Tor. 114If it prints an error, some configuration problem will likely prevent 115C-Lightning from working with your Tor. 116 117Then make sure these are in your `${LIGHTNING_DIR}/config` or other C-Lightning configuration 118(or prepend `--` to each of them and add them to your `lightningd` invocation 119command line): 120 121``` 122proxy=127.0.0.1:9050 123bind-addr=127.0.0.1:9735 124addr=statictor:127.0.0.1:9051 125always-use-proxy=true 126``` 127 1281. `proxy` informs C-Lightning that you have a SOCKS5 proxy at port 9050. 129 C-Lightning will assume that this is a Tor proxy, port 9050 is the 130 default in most Linux distributions; you can double-check `/etc/tor/torrc` 131 for a `SocksPort` entry to confirm the port number. 1322. `bind-addr` informs C-Lightning to bind itself to port 9735. 133 This is needed for the subsequent `statictor` to work. 134 9735 is the normal Lightning Network port, so this setting may already be present. 135 If you add a second `bind-addr=...` you may get errors, so choose this new one 136 or keep the old one, but don't keep both. 137 This has to appear before any `statictor:` setting. 1383. `addr=statictor:` informs C-Lightning that you want to create a persistent 139 hidden service that is based on your node private key. 140 This informs C-Lightning as well that the Tor Control Port is 9051. 141 You can also use `bind-addr=statictor:` instead to not announce the 142 persistent hidden service, but if anyone wants to make a channel with 143 you, you either have to connect to them, or you have to reveal your 144 address to them explicitly (i.e. autopilots and the like will likely 145 never connect to you). 1464. `always-use-proxy` informs C-Lightning to always use Tor even when 147 connecting to nodes with public IPs. 148 You can set this to `false` or remove it, 149 if you are not privacy-conscious **and** find Tor is too slow for you. 150 151### Tor Browser and Orbot 152 153It is possible to not install Tor on your computer, and rely on just 154Tor Browser. 155Tor Browser will run a built-in Tor instance, but with the proxy at port 1569150 and the control port at 9151 157(the normal Tor has, by default, the proxy at port 9050 and the control 158port at 9051). 159The mobile Orbot uses the same defaults as Tor Browser (9150 and 9151). 160 161You can then use these settings for C-Lightning: 162 163``` 164proxy=127.0.0.1:9150 165bind-addr=127.0.0.1:9735 166addr=statictor:127.0.0.1:9151 167always-use-proxy=true 168``` 169 170You will have to run C-Lightning after launching Tor Browser or Orbot, 171and keep Tor Browser or Orbot open as long as C-Lightning is running, 172but this is a setup which allows others to connect and fund channels 173to you, anywhere (no port forwarding! works wherever Tor works!), and 174you do not have to do anything more complicated than download and 175install Tor Browser. 176This may be useful for operating system distributions that do not have 177Tor in their repositories, assuming we can ever get C-Lightning running 178on those. 179 180### Detailed Discussion 181 182#### Creation of an auto service for non-persistent .onion addresses 183 184To provide the node a non-persistent .onion address it 185is necessary to access the Tor auto service. These types of addresses change 186each time the Tor service is restarted. 187 188*NOTE:If the node is required to be reachable only by **persistent** .onion addresses, this 189part can be skipped and it is necessary to set up a hidden service with the steps 190outlined in the next section.* 191 192To create and use the auto service follow these steps: 193 194Edit the Tor config file `/etc/tor/torrc` 195 196You can configure the service authenticated by cookie or by password: 197 198##### Service authenticated by cookie 199Add the following lines in the `/etc/tor/torrc` file: 200 201```` 202ControlPort 9051 203CookieAuthentication 1 204CookieAuthFileGroupReadable 1 205```` 206 207##### Service authenticated by password 208 209Alternatively, you can set the authentication 210to the service with a password by following these steps: 211 2121. Create a hash of your password with 213``` 214tor --hash-password yourpassword 215``` 216 217This returns a line like 218 219`16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F` 220 2212. put these lines in the `/etc/tor/torrc` file: 222``` 223ControlPort 9051 224HashedControlPassword 16:533E3963988E038560A8C4EE6BBEE8DB106B38F9C8A7F81FE38D2A3B1F 225```` 226 227Save the file and restart the Tor service. In linux: 228 229`/etc/init.d/tor restart` or `sudo systemctl start tor` depending 230on the configuration of your system. 231 232The auto service is used by adding `--addr=autotor:127.0.0.1:9051` if you 233want the address to be public or `--bind-addr=autotor:127.0.0.1:9051` if you 234don't want to publish it. 235 236In the case where the auto service is authenticated through a password, it will 237be necessary to add the option `--tor-service-password=yourpassword` (not the hash). 238 239The created non-persistent .onion address will be shown by the `lightning-cli getinfo` 240command. The other nodes will be able to `connect` to this .onion address through the 2419735 port. 242 243#### Creation of a hidden service for a persistent .onion address 244 245To have a persistent .onion address other nodes can connect to, it 246is necessary to set up a [Tor Hidden Service]. 247 248*NOTE: In the case where only non-persistent addresses are required, 249you don't have to create the hidden service and you can skip this part.* 250 251##### Automatic persistent .onion address 252 253It is possible to generate persistent .onion addresses automatically. 254 255Add the following lines in the `/etc/tor/torrc` file 256(you might already have done this if for example you connected Bitcoin 257over Tor): 258 259```` 260ControlPort 9051 261CookieAuthentication 1 262CookieAuthFileGroupReadable 1 263```` 264 265Then you can use `--addr=statictor:127.0.0.1:9051` instead of 266`--announce-addr=.onionAddressV3`. 267By default V3 onion addresses are generated. 268 269Note that you have to specify a `--bind-addr` first before using 270`--addr=statictor:`. 271Generally `--bind-addr=127.0.0.1:9735` should work fine. 272 273You can also have multiple persistent .onion addresses 274by adding `/torblob=BLOB`, where `BLOB` is 32 to 64 ***random*** 275bytes of text. 276Note that this blob will be used to derive the secret key behind 277the .onion address and you should keep the blob secret otherwise 278anyone who steals it can spoof your .onion address and block 279incoming data to your node via this .onion address. 280You can then specify multiple `statictor:` options with different 281`BLOB`s. 282 283However, even if you have multiple persistent addresses, you can 284only announce up to one onion service (v3). 285This is a limitation of the BOLT spec. 286It is still possible for other nodes to contact you by those 287other hidden services. 288 289Finally, the default external port number for the autogenerated 290persistent .onion address will be 9735, but you can change this by 291adding `/torport=9999` to change the external port for the .onion 292address. 293 294##### Explicit Control 295 296If you want to create a version 3 address, you must also add `HiddenServiceVersion 3` so 297the whole section will be: 298 299```` 300HiddenServiceDir /var/lib/tor/lightningd-service_v3/ 301HiddenServiceVersion 3 302HiddenServicePort 1234 127.0.0.1:9735 303```` 304 305The hidden lightning service will be reachable at port 1234 (global port) 306of the .onion address, which will be created at the restart of the 307Tor service. Both types of addresses can coexist on the same node. 308 309Save the file and restart the Tor service. In linux: 310 311`/etc/init.d/tor restart` or `sudo systemctl start tor` depending 312on the configuration of your system. 313 314You will find the newly created address with: 315``` 316sudo cat /var/lib/tor/lightningd-service_v3/hostname 317``` 318 319Now you are able to create: 320 321* Persistent version 3 hidden services. 322 323Let's see how to use them. 324 325### What do we support 326 327| Case # | IP Number | Hidden service |Incoming / Outgoing Tor | 328| ------- | ------------- | ------------------------- |------------------------- 329| 1 | Public | NO | Outgoing | 330| 6 | Public | v3 | Incoming [1] | 331| 7 | Not Announced | v3 | Incoming | 332| 8 | Public | NO | Outcoing socks5 . | 333 334NOTE: 335 3361. In all the "Incoming" use case, the node can also make "Outgoing" Tor 337connections (connect to a .onion address) by adding the 338`--proxy=127.0.0.1:9050` option. 339 340#### 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. 341 342Without a .onion address, the node won't be reachable through Tor by other 343nodes but it will always be able to `connect` to a Tor enabled node 344(outbound connections), passing the `connect` request through the Tor 345service socks5 proxy. When the Tor service starts it creates a socks5 346proxy which is by default at the address 127.0.0.1:9050. 347 348If the node is started with the option `--proxy=127.0.0.1:9050` the node 349will be always able to connect to nodes with .onion address through the socks5 350proxy. 351 352**You can always add this option, also in the other use cases, to add outgoing 353Tor capabilities.** 354 355If you want to `connect` to nodes ONLY via the Tor proxy, you have to add the 356`--always-use-proxy=true` option. 357 358You can announce your public IP address through the usual method: 359 360``` 361--bind-addr=internalIPAddress:port --announce-addr=externalIpAddress 362``` 363if the node is into an internal network 364``` 365--addr=externalIpAddress 366``` 367if the node is not inside an internal network. 368 369TIP: If you are unsure which of the two is suitable for you, find your internal 370and external address and see if they match. 371 372In linux: 373 374Discover your external IP address with: `curl ipinfo.io/ip` 375 376and your internal IP Address with: `ip route get 1 | awk '{print $NF;exit}'` 377 378If they match you can use the `--addr` command line option. 379 380#### 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. 381 382To have your external IP address and your .onion address announced, you use the 383``` 384--bind-addr=yourInternalIPAddress:port --announce-addr=yourexternalIPAddress:port --announce-addr=your.onionAddress:port` 385``` 386or 387``` 388--bind-addr=yourInternalIPAddress:port --announce-addr=yourexternalIPAddress:port --addr=statictor:127.0.0.1:9051` 389``` 390options. 391 392If you are not inside an internal network you can use 393``` 394--addr=yourIPAddress:port --announce-addr=your.onionAddress:port 395``` 396or 397``` 398--addr=yourIPAddress:port --addr=statictor:127.0.0.1:9051 399``` 400 401your.onionAddress is the one created with the Tor hidden service ([see above](#creation-of-an-hidden-service-for-a-persistent-onion-address)). 402The port is the one indicated as the hidden service port. If the hidden service creation 403line is `HiddenServicePort 1234 127.0.0.1:9735` the .onion address will be reachable at 404the 1234 port (the global port). 405 406For `statictor` the `127.0.0.1` is your computer, and `9051` is the 407Tor Control Port you set up in the `/etc/tor/torrc` file. 408 409It will be possible to connect to this node with: 410``` 411lightning-cli connect nodeID .onionAddress globalPort 412``` 413through Tor where .onion address is in the form `xxxxxxxxxxxxxxxxxxxxxxxxxx.onion`, Or 414``` 415lightning-cli connect nodeID yourexternalIPAddress Port 416``` 417through Clearnet. 418 419#### Case #3 c-lightning has a public IP address and a non-persisten Tor service address 420 421In this case other nodes can connect to you via Clearnet or Tor. 422 423To announce your IP address to the network, you add: 424``` 425--bind-addr=internalAddress:port --announce-addr=yourExternalIPAddress 426``` 427or `--addr=yourExternalIPAddress`if you are NOT on an internal network. 428 429To get your non-persistent Tor address, add 430`--addr=autotor:127.0.0.1:9051` if you want to announce it or 431`--bind-addr=autotor:127.0.0.1:9051` if you don't want to announce it. 432 433If the auto service is protected by password ([see above](#service-authenticated-by-password)) it is necessary to 434specify it with the option `--tor-service-password=yourpassword` (not the hash). 435 436You will obtain the generated non persisten .onion address by reading the results of the 437`lightning-cli getinfo` command. Other nodes will be able to connect to the 438.onion address through the 9735 port. 439 440#### Case #4 c-lightning has no public IP address, but has a fixed Tor hidden service address that is persistent 441 442Other nodes can connect to the announced .onion address created with the 443hidden service ([see above](#creation-of-an-hidden-service-for-a-persistent-onion-address)). 444 445In this case In the `lightningd` command line you will specify: 446``` 447--bind-addr=yourInternalIPAddress:port --announce-addr=your.onionAddress:port 448``` 449or `--addr=your.onionAddress:port` if you are NOT on an internal network. 450 451#### Case #5 c-lightning has no public IP address, and has no fixed Tor hidden service address 452 453In this case it is difficult to track the node. 454You specify just: 455``` 456--bind-addr=yourInternalIPAddress:port --addr=autotor:127.0.0.1:9051 457``` 458In the `lightningd` command line. 459 460Other nodes will not be able to `connect` to you unless you communicate them how to reach you. 461You will find your .onion address with the command `lightning-cli getinfo` and the other nodes will 462be able to connect to it through the 9735 port. 463 464#### Case #6 c-lightning has a public IP address and a fixed Tor v3 hidden service 465 466You will be reachable via Clearnet, via Tor to the .onion if it is communicated to the node that wants to 467connect with our node. 468 469To make your external IP address public you add: 470``` 471--bind-addr=yourInternalAddress:port --announce-addr=yourexternalIPAddress:port`. 472``` 473If the node is not on an internal network the option will be: 474`--addr=yourexternalIPAddress:port`. 475 476Once the .onion addresses have been created with the procedures [oulined above](#creation-of-an-hidden-service-for-a-persistent-onion-address), 477the node is already reachable at the .onion address. 478 479To make your external hidden service public you add: 480``` 481--announce-addr=.onionAddressV3:port 482``` 483to the options to publish your IP number. 484 485#### Case #7 c-lightning has no public IP address, a fixed Tor V3 service address 486 487The Persistent addresses can be created with the steps [outlined above](#creation-of-an-hidden-service-for-a-persistent-onion-address). 488 489To create your non-persistent Tor address, add 490`--addr=autotor:127.0.0.1:9051` if you want to announce it or 491`--bind-addr=autotor:127.0.0.1:9051` if you don't want to announce it. 492 493Also you must specify `--tor-service-password=yourpassword` (not the hash) to access the 494Tor service at 9051 If you have protected them with the password (no additional options if 495they are protected with a cookie file. [See above](#creation-of-an-auto-service-for-non-persistent-onion-addresses)). 496 497To make your external onion service public you add: 498``` 499--bind-addr=yourInternalIPAddress:port --announce-addr=your.onionAddressV3:port 500``` 501#### Case #8 c-lightning has a public IP address and no Tor addresses 502 503The external address is communicated by the 504``` 505--bind-addr=internalIPAddress:port --announce-addr=yourexternalIPAddress:port` 506``` 507or `--addr=yourexternalIPAddress:port` if the node is not inside an internal network. 508 509The node can connect to any V4/6 ip address via a IPV4/6 socks 5 proxy by specifing 510``` 511--proxy=127.0.0.1:9050 --always-use-proxy=true 512``` 513 514## References 515 516[The Tor project](https://www.torproject.org/) 517 518[tor FAQ]: https://www.torproject.org/docs/faq.html.en#WhatIsTor 519 520[Tor Hidden Service]: https://www.torproject.org/docs/onion-services.html.en 521 522[.onion addresses version 3]: https://blog.torproject.org/we-want-you-test-next-gen-onion-services 523