add initial commitHEADmain

1 files changed, 39 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a03126
--- /dev/null
+++ b/README.md
@@ -0,0 +1,39 @@
+# Ansible setup password-less ssh relay access
+
+Set up password-less access from the `accessing_host!`  to `accessed_host` using
+`accessed_user`.
+The used SSH key must be stored at `~/.ssh/{{ relay_ssh_key_name }}`
+The authorized key is only usable to create port forwards and does not allow
+interactive sessions.
+
+## Variables
+
+**NOTE:** all used variables are prefixed with the role name to prevent scoping issues.
+
+* `ssh_relay_accessing_host [inventory_hostname]`: the host initiating the port forward
+* `ssh_relay_accessed_host`: the server connected to to establish the port forward
+* `ssh_relay_accessed_user`: the user on the server to connect to
+* `relay_ssh_key_name`: The name of the private key of the relay SSH key pair
+
+## Requirements
+
+* The private key for the relay host must be accessable: `~/.ssh/{{ relay_ssh_key_name }}`
+* `relay_host` must be configurable with ansible
+
+## Example Playbook
+
+```yml
+---
+- hosts: host-pattern
+  roles:
+    - ssh_relay_access # use default variable values
+    - role: ssh_relay_access # explicitly pass vales
+      ssh_relay_accessed_host: foo.tld
+      ssh_relay_accessed_user: alice
+      ssh_relay_accessing_host: bar.tld
+```
+
+## 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).