From febe20b6655aba2c443fd5e18f23fbff8a76e1b5 Mon Sep 17 00:00:00 2001
From: emdee <emdee>
Date: Fri, 28 Oct 2022 12:11:25 +0000
Subject: [PATCH] AddingAnOnionService.md

---
 AddingAnOnionService.md | 68 +++++++++++++++++++++++++++++++++++++++--
 1 file changed, 65 insertions(+), 3 deletions(-)

diff --git a/AddingAnOnionService.md b/AddingAnOnionService.md
index c385558..55724e2 100644
--- a/AddingAnOnionService.md
+++ b/AddingAnOnionService.md
@@ -18,8 +18,9 @@ resilient.  I'm assuming the adversaries cannot block .onion addresses
 within Tor, which I think is a valid assumption for now.
 
 There are [simple instructions](https://community.torproject.org/onion-services/setup/)
-to get Tor up and running, and you can test it by setting you browser
-to use the SOCKS proxy on ```127.0.0.1:9050```.
+to get Tor up and running, and it's distributed in all Linux distributions.
+You can test it by setting your browserto use the SOCKS proxy on
+```127.0.0.1:9050```.
 
 Configure your boostrap server with an extra tcp_port that is not
 listed publically in the nodes.json file. We will use 33446 as an example.
@@ -28,7 +29,7 @@ In your ```/etc/tor/torrc``` or equivalent, you need to add 2 sections.
 
 The first is:
 ```
-VirtualAddrNetwork 10.192.0.0/10
+VirtualAddrNetworkV4 10.192.0.0/10
 AutomapHostsOnResolve 1
 AutomapHostsSuffixes .exit,.onion
 ```
@@ -44,13 +45,74 @@ Replace 33446 with your real port number.
 The next time tor starts up, a new directory will be created in
 ```/var/lib/tor/tox-hsv3/``` and it will have a file called
 ```hostname```. Look in the file for the onion address to your site.
+
 Now add the onion address followed by a colon and the port number
 and post it along with your node's public key to the
 [mailinglist](https://lists.tox.chat/pipermail/bootstrap/).
 
+## Using an Onion Bootstrap node
+
+
+To let your client know that you have an onion node it can user,
+you need to add the onion address to your DHTnode.json file.
+But Tox clients don't understand onion addresses and until they do,
+we do the following:
+
+1. Get the IP address your Tor assigns to the onion address
+```
+tor-resolve -4 l2ct3xnuaiwwtoybtn46qp2av4ndxcguwupzyv6xrsmnwi647vvmwtqd.onion
+```
+It will reply with an IPv4 address starting with ```172.```.
+
+You'll need the pubkic key of your BS server.  Take that address and
+add to the DHTnodes.json file in the list of ```nodes```. 
+
+If your nodes file is line one line you can pretty it up with the
+jq utility: ```jq . < DHTnodes.json > Prettynodes.json```.
+
+Put the address in the ```ipv4``` slot and the 
+port in the tcp_ports list and put the onion address as the location.
+```
+{"last_scan": 1665034198,
+  "last_refresh": 1665034201,
+  "nodes": [
+    {
+      "ipv4": "10.192.0.1",
+      "ipv6": "-",
+      "port": "-",
+      "tcp_ports": [
+        33446
+      ],
+      "public_key": "8E7D0B859922EF569298B4D261A8CCB5FEA14FB91ED412A7603A585A25698832",
+      "maintainer": "me",
+      "location": "l2ct3xnuaiwwtoybtn46qp2av4ndxcguwupzyv6xrsmnwi647vvmwtqd.onion:33446",
+      "status_udp": false,
+      "status_tcp": true,
+      "version": "1000002018",
+      "motd": "My Tox Node. ToxId:....",
+      "last_ping": 1665034200
+    },
+```
+
 You can also add this pair to the onions slot in your entry in the
 DHTnodes.json file. If there is not an onions slot, create one.
 
+### Updating
+
+This IP address changes each time Tor restarts, so each time Tor
+restarts the DHTnodes.json file needs updating. You can assign it
+a permanent IP address by using the MapAddress line in the torrc:
+```
+MapAddress l2ct3xnuaiwwtoybtn46qp2av4ndxcguwupzyv6xrsmnwi647vvmwtqd.onion 10.192.0.1
+```
+
+You can use any address in the range defined by
+```
+VirtualAddrNetworkV4 10.192.0.0/10
+```
+
+You can similarly add all the Tox onions you know about in this manner.
+We can work on a script that automates this.
 
 Details:
 * https://git.plastiras.org/emdee/tox_profile/ToxAndTorInChinaAndIran