doc/TOR.md: Mention about `statictor`.

Changelog-None

doc/TOR.md

@@ -31,6 +31,97 @@ 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.
+This is ideal for most setups where you have an ISP-provided router connecting your
+Internet to your local network and computer, as it does not require a stable
+public IP from your ISP (which might not give one to you for free), nor port
+forwarding (which can be hard to set up for random cheap router models).
+Tor provides NAT-traversal for free, so even if you or your ISP has a complex
+network between you and the Internet, as long as you can use Tor you can
+be connected to.
+
+On most Linux distributions, making a standard installation of `tor` will
+automatically set it up to have a SOCKS5 proxy at port 9050.
+As well, you have to set up the Tor Control Port.
+On most Linux distributions there will be commented-out settings below in the
+`/etc/tor/torrc`:
+
+```
+ControlPort 9051
+CookieAuthentication 1
+CookieAuthFileGroupReadable 1
+```
+
+Uncomment those in, then restart `tor` (usually `systemctl restart tor`  or
+`sudo systemctl restart tor` on most SystemD-based systems, including recent
+Debian and Ubuntu, or just restart the entire computer if you cannot figure
+it out).
+
+Then add these to your `${LIGHTNING_DIR}/config` or other C-Lightning configuration
+(or prepend `--` to each of them and add them to your `lightningd` invocation
+command line):
+
+```
+proxy=127.0.0.1:9050
+bind-addr=127.0.0.1:9735
+addr=statictor:127.0.0.1:9051
+always-use-proxy=true
+```
+
+1.  `proxy` informs C-Lightning that you have a SOCKS5 proxy at port 9050.
+    C-Lightning will assume that this is a Tor proxy, port 9050 is the
+    default in most Linux distributions; you can double-check `/etc/tor/torrc`
+    for a `SocksPort` entry to confirm the port number.
+2.  `bind-addr` informs C-Lightning to bind itself to port 9735.
+    This is needed for the subsequent `statictor` to work.
+    9735 is the normal Lightning Network port.
+    This has to appear before any `statictor:` setting.
+3.  `addr=statictor:` informs C-Lightning that you want to create a persistent
+    hidden service that is based on your node private key.
+    This informs C-Lightning as well that the Tor Control Port is 9051.
+    You can also use `bind-addr=statictor:` instead to not announce the
+    persistent hidden service, but if anyone wants to make a channel with
+    you, you either have to connect to them, or you have to reveal your
+    address to them explicitly (i.e. autopilots and the like will likely
+    never connect to you).
+4.  `always-use-proxy` informs C-Lightning to always use Tor even when
+    connecting to nodes with public IPs.
+    You can set this to `false` or remove it,
+    if you are not privacy-conscious **and** find Tor is too slow for you.
+
+### Tor Browser and Orbot
+
+It is possible to not install Tor on your computer, and rely on just
+Tor Browser.
+Tor Browser will run a built-in Tor instance, but with the proxy at port
+9150 and the control port at 9151
+(the normal Tor has, by default, the proxy at port 9050 and the control
+port at 9051).
+The mobile Orbot uses the same defaults as Tor Browser (9150 and 9151).
+
+You can then use these settings for C-Lightning:
+
+```
+proxy=127.0.0.1:9150
+bind-addr=127.0.0.1:9735
+addr=statictor:127.0.0.1:9151
+always-use-proxy=true
+```
+
+You will have to run C-Lightning after launching Tor Browser or Orbot,
+and keep Tor Browser or Orbot open as long as C-Lightning is running,
+but this is a setup which allows others to connect and fund channels
+to you, anywhere (no port forwarding! works wherever Tor works!), and
+you do not have to do anything more complicated than download and
+install Tor Browser.
+This may be useful for operating system distributions that do not have
+Tor in their repositories, assuming we can ever get C-Lightning running
+on those.
+
+### Detailed Discussion
+
 #### Creation of an auto service for non-persistent .onion addresses
 
 To provide the node a non-persistent .onion address it
@@ -100,6 +191,52 @@ 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`.
+By default V3 onion addresses are generated.
+
+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.
+
+However, even if you have multiple persistent addresses, you can
+only announce up to one each of a Tor V2 and a Tor V3 address.
+`statictor:` uses Tor V3 addresses by default.
+This is a limitation of the BOLT spec.
+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
+
 Add these lines in the `/etc/tor/torrc` file:
 
 ````
@@ -218,17 +355,29 @@ 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`
 ```
-option.
+or
+```
+--bind-addr=yourInternalIPAddress:port --announce-addr=yourexternalIPAddress:port --addr=statictor:127.0.0.1:9051`
+```
+options.
 
 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
+```
+
 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:
 ```
 lightning-cli connect nodeID .onionAddress globalPort