From 2f27da272947be6b9f7167e0705f422722545851 Mon Sep 17 00:00:00 2001 From: caubet_m Date: Tue, 18 Aug 2020 11:52:36 +0200 Subject: [PATCH] Updated documentation: ssh-agent and troubleshooting --- .../merlin6/02 accessing-merlin6/ssh-keys.md | 89 +++++++++++++------ 1 file changed, 62 insertions(+), 27 deletions(-) diff --git a/pages/merlin6/02 accessing-merlin6/ssh-keys.md b/pages/merlin6/02 accessing-merlin6/ssh-keys.md index 3f3d86e..34c1d9f 100644 --- a/pages/merlin6/02 accessing-merlin6/ssh-keys.md +++ b/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 -```