Updated documentation: ssh-agent and troubleshooting

pages/merlin6/02 accessing-merlin6/ssh-keys.md

@@ -42,11 +42,42 @@ For creating **SSH RSA Keys**, one should:
 
 ## Using the SSH Keys
 
-By default, when login in the login node through SSH, it will automatically add your SSH Keys to the authentication agent.
-Hence, no actions are needed by the user.
+### Using Authentication Agent in SSH session
 
-However, there are some cases where it might not automatically work. For example, for NoMachine one always need to add 
-the private key identity to the authentication agent. This can be done as follows:
+By default, when accessing the login node via SSH (with `ForwardAgent=yes`), it will automatically add your 
+SSH Keys to the authentication agent. Hence, no actions should not be needed by the user. One can configure
+`ForwardAgent=yes` as follows:
+
+   * **(Recommended)** In your local Linux (workstation, laptop or desktop) add the following line in the 
+   `$HOME/.ssh/config` (or alternatively in `/etc/ssh/ssh_config`) file: 
+   ```
+   ForwardAgent yes
+   ```
+   * Alternatively, on each SSH you can add the option `ForwardAgent=yes` in the SSH command. In example:
+   ```bash
+   ssh -XY -o ForwardAgent=yes merlin-l-001.psi.ch
+   ```
+
+If `ForwardAgent` is not enabled as shown above, one needs to run the authentication agent and then add your key
+to the **ssh-agent**. This must be done once per SSH session, as follows:
+
+   * Run `eval $(ssh-agent -s)` to run the **ssh-agent** in that SSH session
+   * Check whether the authentication agent has your key already added:
+   ```bash
+   ssh-add -l | grep "/psi/home/$(whoami)/.ssh"
+   ```
+   * If no key is returned in the previous step, you have to add the private key identity to the authentication agent. 
+   You will be requested for the **passphrase** of your key, and it can be done by running:
+   ```bash
+   ssh-add
+   ```
+
+### Using Authentication Agent in NoMachine Session
+
+By default, when using a NoMachine session, the `ssh-agent` should be automatically started. Hence, there is no need of
+starting the agent or forwarding it.
+
+However, for NoMachine one always need to add the private key identity to the authentication agent. This can be done as follows:
 
 1. Check whether the authentication agent has already the key added:
    ```bash
@@ -58,8 +89,33 @@ You will be requested for the **passphrase** of your key, and it can be done by
    ssh-add
    ```
 
-When running `ssh-add` is needed (i.e. NoMachine session, or miss-behaving SSH access), you need to run it only once per new session.
-It is, for NoMachine, you just need to run it once, and it would apply to all terminal windows within that NoMachine session.
+You just need to run it once per NoMachine session, and it would apply to all terminal windows within that NoMachine session.
+
+## Troubleshooting
+
+### Errors when running 'ssh-add'
+
+If the error `Could not open a connection to your authentication agent.` appears when running `ssh-add`, it means
+that the authentication agent is not running. Please follow the previous procedures for starting it.
+
+### Adding/Updationg SSH RSA Key password
+
+If an existing SSH Key does not have password, or you want to update an existing password with a new one, you can do it as follows:
+
+```bash
+ssh-keygen -p -f ~/.ssh/id_rsa
+```
+
+### SSH Keys deployed but not working
+
+Please ensure proper permissions of the involved files, as well as any typos in the file names involved:
+
+```bash
+chmod u+rwx,go-rwx,g+s ~/.ssh
+chmod u+rw-x,go-rwx    ~/.ssh/authorized_keys
+chmod u+rw-x,go-rwx    ~/.ssh/id_rsa
+chmod u+rw-x,go+r-wx   ~/.ssh/id_rsa.pub
+```
 
 ### Testing SSH Keys
 
@@ -88,24 +144,3 @@ Once SSH Key is created, for testing that the SSH Key is valid, one can do the f
    ```
 
 If the last step succeeds, then means that your SSH Key is properly setup.
-
-## Troubleshooting
-
-### Add/Update SSH RSA Key password
-
-If an existing SSH Key does not have password, or you want to update an existing password with a new one, you can do it as follows:
-
-```bash
-ssh-keygen -p -f ~/.ssh/id_rsa
-```
-
-### SSH Keys deployed but not working
-
-Please ensure proper permissions of the involved files, as well as any typos in the file names involved:
-
-```bash
-chmod u+rwx,go-rwx,g+s ~/.ssh
-chmod u+rw-x,go-rwx    ~/.ssh/authorized_keys
-chmod u+rw-x,go-rwx    ~/.ssh/id_rsa
-chmod u+rw-x,go+r-wx   ~/.ssh/id_rsa.pub
-```