# 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).