initial commitHEADmain

1 files changed, 88 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..78e4f60
--- /dev/null
+++ b/README.md
@@ -0,0 +1,88 @@
+# Ansible relayed domain setup role
+
+Role to setup a SSH tunnel to relay a domain to an arbitrary port of hosts
+behind a NAT or without a public IP address.
+
+This role requires both used hosts to be configurable via ansible.
+SSH allows to seamlessly forward traffic between ports.
+This means that connections to a port on the SSH client machine are forwarded
+to a port of the SSH server machine.
+Contrary to the `relayed_ssh` role we use a port forward from the `relay_host`
+to the `relayed_host` in order to use the uberspace reverse proxy mechanisms.
+
+This role sets up a [uberspace web backend](https://manual.uberspace.de/web-backends/)
+for the relayed domain redirecting the incoming traffic to the forwarded local
+port and therefore through the SSH tunnel to the `relayed_host`.
+
+In the following we use the term `relay_host` to specify the machine where the
+relayed domain points to.
+The `relayed_host` is the machine which serves something on the relayed port.
+
+The setup looks roughly like this:
+
+```
+SSH tunnel initialization from relayed_host to relay_host
+
++------------+                                 +----------------+
+| relay_host |-------------------------------->|22 relayed_host |
++------------+   connects to and establishes   +----------------+
+                 the tunnel between 
+                 relay_host:relay_port and 
+                 relayed_host:relayed_port
+
+The uberspace relay_host uses a reverse proxy to forward traffic from the relayed
+domain to relay_host:relay_port and thus to relayed_host:relayed_port.
+
+Connection from the world to relayed_host
+
++--------+                    +------------+                                   +--------------+
+| Client |------------------->| relay_host |---------------------------------->| relayed_host |
++--------+   connects to via  +------------+  nginx forwards the connection    +--------------+
+             domain                           through the tunnel to the relayed_port
+```
+
+For password-less SSH port-forwarding from the `relay_host` to the `relayed_host`
+a relay SSH key pair is used.
+The private key must be kept secretly (e.g., in your password manager.
+The access is setup using the `ssh_relay_access` role.
+
+## Variables
+
+* `domain`: The relayed domain
+* `relay_host`: The host where the relayed domain points to
+* `relay_port`: The local port on the `relay_host` used by the uberspace backend
+* `relay_ssh_key_name`: The name of the private key of the relay SSH key pair
+* `relayed_port [80]`: The port on the `relayed_host` where the traffic finally arrives
+* `relayed_host_ssh_port [22]`: The port to connect to in order to establish a SSH connection
+
+## Requirements
+
+* The private key for the relay host must be accessable: `~/.ssh/{{ relay_ssh_key_name }}`
+* Both host must be configurable with ansible
+* The relay hosts must be a uberspace
+* Port on the `relay_host` - To forward the port through the `relay_host` a
+  available and open port on the `relay_host` must be available
+* Domain - The domain to relay must point to the `relay_host`
+
+If `relay_host` is an uberspace, [ports](https://manual.uberspace.de/basics-ports/)
+can be opened using: `uberspace port add`
+
+## Example Playbook
+
+```yml
+---
+- hosts: host-pattern
+  roles:
+    - relayed_domain
+      domain: example.domain.tld
+      relay_host: ssh_relay.example.tld
+      relay_port: <port>
+      # Default relayed port is the http port 80
+      # relayed_port: port
+```
+
+## LICENSE
+
+
+This ansible role is licensed under the term of the GPLv3.
+For further information see the `COPYING` file or [https://www.gnu.org/licenses/gpl-3.0.en.html](https://www.gnu.org/licenses/gpl-3.0.en.html).