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