Added SSH Keys DOCS

_data/sidebars/merlin6_sidebar.yml

@@ -39,6 +39,8 @@ entries:
       url: /merlin6/archive.html
     - title: Remote Desktop Access
       url: /merlin6/nomachine.html
+    - title: Configuring SSH Keys
+      url: /merlin6/ssh-keys.html
   - title: Job Submission
     folderitems:
     - title: Using PModules

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

@@ -0,0 +1,111 @@
+---
+title: Configuring SSH Keys in Merlin
+
+#tags:
+keywords: Linux, connecting, client, configuration, SSH, Keys, SSH-Keys, RSA
+last_updated: 15 Jul 2020
+summary: "This document describes how to deploy SSH Keys in Merlin."
+sidebar: merlin6_sidebar
+permalink: /merlin6/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 add a password***. Never leave an empty password.
+   * 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
+   ```
+
+## 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.
+
+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:
+
+1. Check whether the authentication agent has already the key added:
+   ```bash
+   ssh-add -l | grep "/psi/home/$(whoami)/.ssh"
+   ```
+2. If no key is return 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:
+   ```bash
+   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.
+
+### 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 merlin-l-001
+   ```
+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 merlin-l-002
+   ```
+
+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
+```

pages/merlin6/05 Software Support/ansys-fluent.md

@@ -99,7 +99,16 @@ Otherwise, one must use the Slurm batch system using allocations:
 Please refer to the documentation **[Running Interactive Jobs](/merlin6/interactive-jobs.html)** for firther information about different ways for running interactive
 jobs in the Merlin6 cluster.
 
-### Considerations
+### Requirements
+
+#### SSH Keys
+
+Running Fluent interactively requires the use of SSH Keys. This is the way of communication between the GUI and the different nodes. For doing that, one must have
+a **passphrase protected** SSH Key. If the user does not have SSH Keys yet (simply run **`ls $HOME/.ssh/`** to check whether **`id_rsa`** files exist or not). For 
+deploying SSH Keys for running Fluent interactively, one should follow this documentation: **[Configuring SSH Keys](/merlin6/ssh-keys.html)**
+
+
+#### List of hosts
 
 For running Fluent using Slurm computing nodes, one needs to get the list of the reserved nodes. For getting that list, once you have the allocation, one can run
 the following command: