From f99c80852b62c80e457eeb4364485a9cc4e0051a Mon Sep 17 00:00:00 2001
From: BJ Dweck <bjdweck@gmail.com>
Date: Tue, 6 Oct 2020 15:14:57 +0200
Subject: [PATCH] Updated/Added README.md files

---
 README.md         | 41 +++++++++++++++++++++++++++++++++++++++++
 example/README.md | 45 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 86 insertions(+)
 create mode 100755 example/README.md

diff --git a/README.md b/README.md
index 00d5398..fb5a0dd 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,42 @@
 # TORch: Illuminating the Path to your Node
+
+TORch is a solution for creating an SSH-via-Tor backdoor on a remote device as a means of fallback remote management and initial headless device configuration.
+
+## Description
+
+Since Tor traffic easily crosses NAT boundries, this is a nice solution for 
+* fallback connection to remote devices located on other LANs in the event that the network configuration on the remote side changes and the primary connection / VPN fails
+* the initial discovery and connection to a headless device like a Raspberry Pi on a local network which is configured via DHCP
+
+A TORch solution consists of 3 processes:
+* `torch-agent` - Installed on remote machine; responsible for creating Tor hidden service and broadcasting the onion hostname an MQTT broker
+* MQTT broker - Any MQTT broker, reachable via IPv4 or Tor, through TLS or insecure communications
+* `torch-subscriber` - Listens for and handles onion hostname publications
+
+## Installation of TORch Agent (Ubuntu)
+
+Copy the files to the target device
+* `install-ubuntu2004.sh`
+* `torch-agent.py`
+* `torch.conf`
+* `torch.service`
+
+Run the installation script:
+```bash
+vagrant@ubuntu2004:~$ ./install-ubuntu2004.sh
+```
+
+This will create a local user `torch` and install the TORch agent as a Systemd service named `torch`
+
+## Configuration
+
+The TORch agent will look for a `torch.conf` configuration in the configuration directory.
+
+The configuation directory can be specified by
+* The `TORCH_CONFIG_DIR` environment variable
+* Using the `--config-dir` commandline option
+* Default: `/etc/torch`
+
+A fully configured example can be found [here](example/README.md)
+
+See the sample [`torch.conf`](torch.conf) file for additional configuration options and details
\ No newline at end of file
diff --git a/example/README.md b/example/README.md
new file mode 100755
index 0000000..44b269f
--- /dev/null
+++ b/example/README.md
@@ -0,0 +1,45 @@
+# TORch Agent Example
+
+The example creates a Vagrant machine configured with TORch Agent
+
+## Instructions to Run
+
+### Install dependencies
+
+* `docker`
+* `mosquitto_sub`
+    * `apt install mosquitto-clients`
+
+### Run the Broker
+
+Add the following line to your `/etc/hosts` file:
+
+```
+127.0.0.1    mqtt.example.com
+```
+
+Run the broker in a terminal window:
+
+```bash
+cd example
+./run-broker.sh
+```
+
+### Run the Subscriber
+
+In a separate terminal window, run the subscriber:
+
+```bash
+cd example
+./run-subscriber.sh
+```
+
+### Run TORch Agent in Vagrant
+
+Run the Vagrant box in a third terminal window:
+
+```bash
+vagrant up
+```
+
+You should see that the broker received a connection from the Vagrant box at boot up and the subscriber received the onion hostname.  You can use a local `tor` proxy to connect to the vagrant box using SSH and the onion hostname.
\ No newline at end of file