Merge #19961: doc: tor.md updates

a34eceb4cc054b4233e7321de927e8a7a2146301 doc: update -externalip documentation in tor.md (Jon Atack)
dc8a591222f249da81c7eef8aa5961f8d7dd1e23 doc: add tor.md section on how to get tor info via bitcoind (Jon Atack)
e1765d8b04fe1fb775f3750e0fa59f13a58eb176 doc: update tor.md address examples from onion v2 to v3 (Jon Atack)

Pull request description:

  It looks like `doc/tor.md` could use some updates and improvements, not only for Tor v3, but also for setting multiple addresses with `-externalip` (see the conversation from http://www.erisian.com.au/bitcoin-core-dev/log-2020-09-16.html#l-39), how to see information about your Tor config via Bitcoin Core, and other improvements.

  Closes #19924.

ACKs for top commit:
  laanwj:
    ACK a34eceb4cc054b4233e7321de927e8a7a2146301

Tree-SHA512: 3197cdca1188dbd645c8f9e6ed7c023da5ad9bcf246a6bcbfbe6078f40c01c563032b4906736cde253a2daf71aaed28a659121628891a5d0bf6e89f821a17a28

1 files changed, 21 insertions, 6 deletions

diff --git a/doc/tor.md b/doc/tor.md
index 692041ccea..86e5d9ddf3 100644
--- a/doc/tor.md
+++ b/doc/tor.md
@@ -5,6 +5,16 @@ It is possible to run Bitcoin Core as a Tor onion service, and connect to such s
 The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly
 configure Tor.
 
+## How to see information about your Tor configuration via Bitcoin Core
+
+There are several ways to see your local onion address in Bitcoin Core:
+- in the debug log (grep for "tor:" or "AddLocal")
+- in the output of RPC `getnetworkinfo` in the "localaddresses" section
+- in the output of the CLI `-netinfo` peer connections dashboard
+
+You may set the `-debug=tor` config logging option to have additional
+information in the debug log about your Tor configuration.
+
 
 ## 1. Run Bitcoin Core behind a Tor proxy
 
@@ -51,14 +61,19 @@ The directory can be different of course, but virtual port numbers should be equ
 your bitcoind's P2P listen port (8333 by default), and target addresses and ports
 should be equal to binding address and port for inbound Tor connections (127.0.0.1:8334 by default).
 
-	-externalip=X   You can tell bitcoin about its publicly reachable address using
-	                this option, and this can be a .onion address. Given the above
-	                configuration, you can find your .onion address in
+	-externalip=X   You can tell bitcoin about its publicly reachable addresses using
+	                this option, and this can be an onion address. Given the above
+	                configuration, you can find your onion address in
 	                /var/lib/tor/bitcoin-service/hostname. For connections
 	                coming from unroutable addresses (such as 127.0.0.1, where the
-	                Tor proxy typically runs), .onion addresses are given
+	                Tor proxy typically runs), onion addresses are given
 	                preference for your node to advertise itself with.
 
+	                You can set multiple local addresses with -externalip. The
+	                one that will be rumoured to a particular peer is the most
+	                compatible one and also using heuristics, e.g. the address
+	                with the most incoming connections, etc.
+
 	-listen         You'll need to enable listening for incoming connections, as this
 	                is off by default behind a proxy.
 
@@ -71,7 +86,7 @@ should be equal to binding address and port for inbound Tor connections (127.0.0
 
 In a typical situation, where you're only reachable via Tor, this should suffice:
 
-	./bitcoind -proxy=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -listen
+	./bitcoind -proxy=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -listen
 
 (obviously, replace the .onion address with your own). It should be noted that you still
 listen on all devices and another node could establish a clearnet connection, when knowing
@@ -89,7 +104,7 @@ and open port 8333 on your firewall (or use -upnp).
 If you only want to use Tor to reach .onion addresses, but not use it as a proxy
 for normal IPv4/IPv6 communication, use:
 
-	./bitcoind -onion=127.0.0.1:9050 -externalip=57qr3yd1nyntf5k.onion -discover
+	./bitcoind -onion=127.0.0.1:9050 -externalip=7zvj7a2imdgkdbg4f2dryd5rgtrn7upivr5eeij4cicjh65pooxeshid.onion -discover
 
 ## 3. Automatically create a Bitcoin Core onion service