docs: review the Readme so it can be read easily

Author: fhuitelec

README.md

@@ -14,7 +14,7 @@ You can:
 
 This Github action is rather young and it might not be as stable and battle-tested as you need: use it at your own risk.
 
-## Usage
+## Usage examples
 
 ### Basic usage
 
@@ -54,58 +54,57 @@ steps:
       echo "...multiple commands"
 ```
 
-### SSH config<a name="ssh-config"></a>
-
-You can specify a `ssh_config` input with a compliant SSH config ([`man ssh_config`](https://linux.die.net/man/5/ssh_config)) which will be dumped as is in `~/.ssh/config`.
-
-Among other things, this will allow you to use a bastion or jump hosts or change the behaviour of the knock sequence.
-
-In such case, beware:
-- the `user` input is ignored, specify the `User` in `ssh_config`
-- the `port` input is ignored, specify the `Port` in `ssh_config` if it's not standard
-- the `knock_sequence` input is ignored, specify a `ProxyCommand` in `ssh_config` if you need it
-  + Example: `ProxyCommand /bin/sh -c 'until nc -zv %h %p -w 1 2>&1 ; do knock %h 111 222 333 ; done; exec nc %h %p'`
-- do not declare the `IdentityFile` as its location is hard-coded (`~/.ssh/id_rsa`)
+## Inputs
 
-### Port
+| Parameter                           | Required                                  | Description                                                          |
+|-------------------------------------|-------------------------------------------|----------------------------------------------------------------------|
+| [`hosts`](#hosts)                   | Yes                                       | Remote host(s) to connect to                                         |
+| `commands`                          | Yes                                       | One or multiple commands to run on the remote host(s)                |
+| `user`                              | [Sometimes](#ssh-config--optional-inputs) | Remote user to connect with                                          |
+| `port`                              | [Sometimes](#ssh-config--optional-inputs) | Remote port to connect to (_default: `22`_)                          |
+| [`private_key`](#private-key)       | [Sometimes](#password-or-private-key)     | Private SSH key to connect with                                      |
+| `password`                          | [Sometimes](password-or-private-key)      | Password to connect with                                             |
+| [`known_hosts`](#known-hosts)       | No                                        | Known hosts keys that SSH can rely on to connect to the remote hosts |
+| [`knock_sequence`](#knock-sequence) | No                                        | Knock sequence performed onto remote host(s) before connecting to it |
+| [`ssh_config`](#ssh-config)         | No                                        | SSH config to use to connect to remote host(s)                       |
 
-If your port is not standard (`22`), you can specify it through the `port` input.
+## Outputs
 
-Note it is ignored if you declare an `ssh_config` input.
+_No output is generated._
 
-### Authentication
+## Configuration
 
-#### Private SSH key<a name="private-key"></a>
+### Hosts<a name="hosts"></a>
 
-To authenticate yourself, you can use a private SSH key with the `private_key` input.
+Specify the remote host(s) - [they all must share the same authentication](#one-auth-for-all-hosts) - to run the `commands` on via the `hosts` input.
 
-The script dumps the SSH private key to `~/.ssh/id_rsa`.
+### Private SSH key<a name="private-key"></a>
 
-Note if you both `password` and `private_key`, `password` will be ignored.
+To authenticate yourself, you can use a private SSH key with the `private_key` input [**using a PEM format**](#not-a-valid-rsa-private-key). The script will dump the SSH private key to `~/.ssh/id_rsa`.
 
-Beware you need to use a PEM-formatted SSH key because `paramiko`, one of the library behind this action, does not support the newest key formats [[reference](https://github.com/paramiko/paramiko/issues/340#issuecomment-492448662)].
+Note if you both `password` and `private_key`, `password` will be ignored.<a name="password-or-private-key"></a>
 
-#### Password
+### Known hosts<a name="known-hosts"></a>
 
-To authenticate yourself, you can use a `password`.
+You can specify explicit one or multiple known hosts keys using the `known_host` input.
 
-The script passes the password to the SSH CLI through `sshpass`
+When not specifying `known_hosts`, the option `StrictHostKeyChecking=no` is added in the `ssh_config`: in such cases, you are exposing yourself to security risks! ⚠️
 
-#### Known hosts
+### Knock sequence<a name="knock-sequence"></a>
 
-You can specify explicit one or multiple (for jump host for example) known hosts keys using the `known_host` input.
+If your remote host needs a knocking sequence (see [`man knock`](https://linux.die.net/man/1/knock)), you can specify the sequence through the `knock_sequence` input.
 
-If you do not specify the `known_hosts` input, the option `StrictHostKeyChecking=no` will be put in the SSH config file.
+For example, with a `knock_sequence` of `111 222 333`, the action will create an SSH config with a `ProxyCommand` that will knock the `host` until it is reachable or will fail after 10 attemps.
 
-⚠️ Be aware that by not specifying `known_hosts`, you would be exposing yourself to security risks.
+You can change this behaviour by specifying your own SSH config (see the [**SSH config**](#ssh-config) section).
 
-#### Knock sequence
+### SSH config<a name="ssh-config"></a>
 
-If your remote host needs a knocking sequence (see [`man knock`](https://linux.die.net/man/1/knock)), you can specify the sequence through the `knock_sequence` input.
+To have complete control over the connection behaviour, you can specify a `ssh_config` input with a compliant SSH config ([`man ssh_config`](https://linux.die.net/man/5/ssh_config)) which will be dumped as is in `~/.ssh/config`.
 
-For example, with a `knock_sequence` of `111 222 333`, the action will create an SSH config with a `ProxyCommand` that will knock the `host` until it is reachable or will fail after 10 attemps.
+Beware, the `user`, `port` & `knock_sequence` inputs will be ignored, specify them explicitely in your `ssh_config`. Also note that you cannot declare the `IdentityFile` as its location is hard-coded (`~/.ssh/id_rsa`).<a name="ssh-config--optional-inputs"></a>
 
-You can change this behaviour by specifying your own SSH config (see the [**SSH config**](#ssh-config) section).
+## Limitations
 
 ### Use environment variables
 
@@ -128,29 +127,16 @@ steps:
       # [...]
 ```
 
-## Configuration
+### One authentication for every hosts<a name="one-auth-for-all-hosts"></a>
 
-See [`action.yaml`](./action.yaml).
+You cannot have multiple SSH keys or passwords for all the `hosts`: they must share the same authentication method **AND** the same credential (i.e. same `password` or same `private_key`).
 
 ## Troubleshooting
 
-### "Not a valid RSA private key file"
+### "Not a valid RSA private key file"<a name="not-a-valid-rsa-private-key"></a>
 
-See the [**Private SSH key**](#private-key) section, you need to use a PEM-formatted SSH key:
+You need to use a PEM-formatted SSH private key because `paramiko`, one of the library behind this action, does not support the newest key formats [[reference](https://github.com/paramiko/paramiko/issues/340#issuecomment-492448662)]:
 
 ```shell
 ssh-keygen -t rsa -b 4096 -C "[email protected]" -m PEM
 ```
-
-## Todo
-
-- Add pipenv integration in Dockerfile
-- Add Contributing guidelines
-- Add better disclaimer and manage expectation
-- Add more dependencies/implementation details
-- Add changelog
-- Add release(s)
-- Document Docker repo 
-- Publish to marketplace
-- Tests
-- CI

TODO.md

@@ -0,0 +1,14 @@
+# Todo
+
+_Todo list to reach a stable 1.0.0 version_
+
+- Add pipenv integration in Dockerfile
+- Add Contributing guidelines
+- Add better disclaimer and manage expectation
+- Add more dependencies/implementation details
+- Add changelog
+- Add release(s)
+- Document Docker repo
+- Publish to marketplace
+- Tests
+- CI

action.yml

@@ -7,10 +7,10 @@ inputs:
     description: Remote host(s) to connect to
     required: true
   commands:
-    description: One or multiple commands to run on the remote hosts
+    description: One or multiple commands to run on the remote host(s)
     required: true
   user:
-    description: Remot user to connect with
+    description: Remote user to connect with
     required: true
   port:
     description: Remote port to connect to
@@ -23,13 +23,13 @@ inputs:
     description: Password to connect with
     required: false
   known_hosts:
-    description: Known hosts keys that SSH can rely on to connect to the remote host
+    description: Known hosts keys that SSH can rely on to connect to the remote host(s)
     required: false
   knock_sequence:
     description: Knock sequence performed onto the remote host before connecting to it
     required: false
   ssh_config:
-    description: SSH config to use to connect to the remote host
+    description: SSH config to use to connect to the remote host(s)
     required: false
 
 outputs: {}