first stab at mkdocs migration
refactor CSCS and Meg content add merlin6 quick start update merlin6 nomachine docs give the userdoc its own color scheme we use the Materials default one refactored slurm general docs merlin6 add merlin6 JB docs add software support m6 docs add all files to nav vibed changes #1 add missing pages further vibing #2 vibe #3 further fixes
This commit is contained in:
184
docs/merlin7/02-How-To-Use-Merlin/ssh-keys.md
Normal file
184
docs/merlin7/02-How-To-Use-Merlin/ssh-keys.md
Normal file
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: Configuring SSH Keys in Merlin
|
||||
|
||||
#tags:
|
||||
keywords: linux, connecting, client, configuration, SSH, Keys, SSH-Keys, RSA, authorization, authentication
|
||||
last_updated: 15 Jul 2020
|
||||
summary: "This document describes how to deploy SSH Keys in Merlin."
|
||||
sidebar: merlin7_sidebar
|
||||
permalink: /merlin7/ssh-keys.html
|
||||
---
|
||||
|
||||
Merlin users sometimes will need to access the different Merlin services without being constantly requested by a password.
|
||||
One can achieve that with Kerberos authentication, however in some cases some software would require the setup of SSH Keys.
|
||||
One example is ANSYS Fluent, which, when used interactively, the way of communication between the GUI and the different nodes
|
||||
is through the SSH protocol, and the use of SSH Keys is enforced.
|
||||
|
||||
## Setting up SSH Keys on Merlin
|
||||
|
||||
For security reason, users **must always protect SSH Keys with a passphrase**.
|
||||
|
||||
User can check whether a SSH key already exists. These would be placed in the **~/.ssh/** directory. `RSA` encryption
|
||||
is usually the default one, and files in there would be **`id_rsa`** (private key) and **`id_rsa.pub`** (public key).
|
||||
|
||||
```bash
|
||||
ls ~/.ssh/id*
|
||||
```
|
||||
|
||||
For creating **SSH RSA Keys**, one should:
|
||||
|
||||
1. Run `ssh-keygen`, a password will be requested twice. You **must remember** this password for the future.
|
||||
* Due to security reasons, ***always try protecting it with a password***. There is only one exception, when running ANSYS software, which in general should not use password to simplify the way of running the software in Slurm.
|
||||
* This will generate a private key **id_rsa**, and a public key **id_rsa.pub** in your **~/.ssh** directory.
|
||||
2. Add your public key to the **`authorized_keys`** file, and ensure proper permissions for that file, as follows:
|
||||
|
||||
```bash
|
||||
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
|
||||
chmod 0600 ~/.ssh/authorized_keys
|
||||
```
|
||||
|
||||
3. Configure the SSH client in order to force the usage of the **psi.ch** domain for trusting keys:
|
||||
|
||||
```bash
|
||||
echo "CanonicalizeHostname yes" >> ~/.ssh/config
|
||||
```
|
||||
|
||||
4. Configure further SSH options as follows:
|
||||
|
||||
```bash
|
||||
echo "AddKeysToAgent yes" >> ~/.ssh/config
|
||||
echo "ForwardAgent yes" >> ~/.ssh/config
|
||||
```
|
||||
|
||||
Other options may be added.
|
||||
|
||||
5. Check that your SSH config file contains at least the lines mentioned in steps 3 and 4:
|
||||
|
||||
```console
|
||||
# cat ~/.ssh/config
|
||||
CanonicalizeHostname yes
|
||||
AddKeysToAgent yes
|
||||
ForwardAgent yes
|
||||
```
|
||||
|
||||
## Using the SSH Keys
|
||||
|
||||
### Using Authentication Agent in SSH session
|
||||
|
||||
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:
|
||||
|
||||
```ssh_config
|
||||
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 login001.merlin7.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 "/data/user/$(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
|
||||
ssh-add -l | grep "/data/user/$(whoami)/.ssh"
|
||||
```
|
||||
2. 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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### Testing SSH Keys
|
||||
|
||||
Once SSH Key is created, for testing that the SSH Key is valid, one can do the following:
|
||||
|
||||
1. Create a **new** SSH session in one of the login nodes:
|
||||
|
||||
```bash
|
||||
ssh login001
|
||||
```
|
||||
|
||||
2. In the login node session, destroy any existing Kerberos ticket or active SSH Key:
|
||||
|
||||
```bash
|
||||
kdestroy
|
||||
ssh-add -D
|
||||
```
|
||||
|
||||
3. Add the new private key identity to the authentication agent. You will be requested by the passphrase.
|
||||
|
||||
```bash
|
||||
ssh-add
|
||||
```
|
||||
|
||||
4. Check that your key is active by the SSH agent:
|
||||
|
||||
```bash
|
||||
ssh-add -l
|
||||
```
|
||||
|
||||
4. SSH to the second login node. No password should be requested:
|
||||
|
||||
```bash
|
||||
ssh -vvv login002
|
||||
```
|
||||
|
||||
If the last step succeeds, then means that your SSH Key is properly setup.
|
||||
Reference in New Issue
Block a user