Set up SSH for the SWC HPC cluster#

This guide explains how to connect to the SWC’s HPC cluster via SSH.

Warning

Some links within this document point to the SWC internal wiki, which is only accessible from within the SWC network. We recommend opening these links in a new tab.

Interpreting code blocks

Shell commands will be shown in code blocks like this (with the $ sign indicating the shell prompt):

$ echo "Hello world!"

Similarly, Python code blocks will appear with the >>> sign indicating the Python interpreter prompt:

>>> print("Hello world!")

The expected outputs of both Shell and Python commands will be shown without any prompt:

Hello world!

Abbreviations#

Acronym

Meaning

SWC

Sainsbury Wellcome Centre

HPC

High Performance Computing

SLURM

Simple Linux Utility for Resource Management

SSH

Secure (Socket) Shell protocol

IDE

Integrated Development Environment

GUI

Graphical User Interface

Prerequisites#

  • You have an SWC account and know your username and password.

  • You have read the SWC wiki’s section on High Performance Computing (HPC), especially the Logging into the Cluster page.

  • You know the basics of using the command line, i.e. using the terminal to navigate the file system and run commands.

  • You have an SSH client installed on your computer. This is usually pre-installed on Linux and macOS. SSH is also available on Windows (since Windows 10), however some steps will differ. If you are a Windows user, read the note below before proceeding.

Note for Windows users

You have two options on how to proceed:

  1. Install Git Bash, which emulates a Linux terminal on Windows and includes tools that are not available on Windows by default, such as nano, and ssh-copy-id. This is the recommended option, as it will allow you to follow along with all commands in this guide, as they are presented. Just assume that all commands are run in Git Bash.

  2. If you are using Windows 10 or newer, you can follow this guide (except for the section on SSH keys) using native Windows functionalities as described here.

    To Log into the cluster, you can use the same commands as in the guide below, but typed in the Windows cmd:

    cmd#
    ssh <SWC-USERNAME>@ssh.swc.ucl.ac.uk
    ssh hpc-gw1
    

    The SSH config file section can be followed using the file browser and Notepad, instead of the terminal and nano. Create the .ssh folder in you home directory, i.e. C:\Users\<USERNAME>\.ssh, if it does not already exist (don’t forget the . at the start of .ssh).

    You may create and edit the config file with Notepad but beware that the file must not have an extension. To create a file without an extension in Windows, you need to make the file extensions visible (click ‘View’ in the file browser and check the box ‘File name extensions’). The config file contents should be the same as in the guide below.

    In day-to-day use, you can use the ssh swc-gateway and ssh swc-bastion commands natively in Windows cmd, provided that you have defined those aliases in your config file, as this guide describes.

Log into the cluster#

Run the following commands on the terminal, typing your <SWC-PASSWORD> both times when prompted (your password will not be displayed on the screen):

$ ssh <SWC-USERNAME>@ssh.swc.ucl.ac.uk
$ ssh hpc-gw1

You have now successfully logged into the cluster 🎉. You may stop reading here, but…

Note

If you want to learn more about why we had to SSH twice, read the next section.

If you want to make you life easier, you can set yourself up with an SSH config file and some SSH keys. Trust us, it’s worth the effort. For example, one benefit is that you will be able to use Visual Studio Code on your PC/laptop to edit files on the cluster (see the last section).

Why do we SSH twice?#

We first need to distinguish the different types of nodes on the SWC HPC system:

  • the bastion node (or “jump host”) - ssh.swc.ucl.ac.uk. This serves as a single entry point to the cluster from external networks. By funneling all external SSH connections through this node, it’s easier to monitor, log, and control access, reducing the attack surface. The bastion node has very little processing power. It can be used to submit and monitor SLURM jobs, but it shouldn’t be used for anything else.

  • the gateway node - hpc-gw1. This is a more powerful machine and can be used for light processing, such as editing your scripts, creating and copying files etc. However don’t use it for anything computationally intensive, since this node’s resources are shared across all users.

  • the compute nodes - enc1-node10, gpu-sr670-21, etc. These are the machinces that actually run the jobs we submit, either interactively via srun or via batch scripts submitted with sbatch.

Your home directory, as well as the locations where filesystems like ceph are mounted, are shared across all of the nodes.

The first ssh command - ssh <SWC-USERNAME>@ssh.swc.ucl.ac.uk only takes you to the bastion node. A second command - ssh hpc-gw1 - is needed to reach the gateway node.

Similarly, if you are on the gateway node, typing logout once will only get you one layer outo the bastion node. You need to type logout again to exit the bastion node and return to your local machine.

The compute nodes should only be accessed via the SLURM srun or sbatch commands. This can be done from either the bastion or the gateway nodes. If you are running an interactive job on one of the compute nodes, you can terminate it by typing exit. This will return you to the node from which you entered.

SSH config file#

If you find yourself typing the above commands over and over again, you can make your life easier by editing the SSH config file. This is a text file that lives in your home directory and contains a list of aliases for SSH connections.

On your local PC/Laptop, navigate to the .ssh folder in your user’s home ~ directory:

$ cd ~/.ssh

List the files in this directory:

$ ls -1
authorized_keys
config
known_hosts

Some of these files may not exist yet. Next we will open the config file using the terminal text editor nano:

$ nano config

If the file doesn’t exist yet, it will be created. Add the following lines to the file:

config#
# Specify our intermediate jump host, aka the bastion node
Host swc-bastion
    HostName ssh.swc.ucl.ac.uk
    User <SWC-USERNAME>

# Specify how to get to the gateway node by jumping through the bastion node
# The gateway hostname is specified as the jump-host would see it
Host swc-gateway
    HostName hpc-gw1
    User <SWC-USERNAME>
    ProxyJump swc-bastion

Save the file by pressing Ctrl+O, then Enter. Exit the nano editor by pressing Ctrl+X.

From now on, you can directly SSH into the gateway node by typing:

$ ssh swc-gateway

You can also use the same syntax to SSH into the bastion node:

$ ssh swc-bastion

In both cases, typing the logout command once will return you to your local machine.

SSH keys#

If you are bored of typing your password every time you SSH into the cluster, you can set up authentication via SSH keys. You will have to do some work upfront, but it will save you tons of time in the long run. Plus, it’s more secure.

How does SSH key authentication work?

You generate a pair of keys locally - a public and a private one - and then copy the public key to the remote machine. When you try to SSH into the remote machine, the SSH client on your local machine will use the private key to generate a signature, which the SSH server on the remote machine will verify using the public key. If the signature is valid, you will be granted access.

There are several cryptographic algorithms that can be used to generate the keys. They can be selected using the -t argument of the ssh-keygen command. In the following example, we use ed25519, as it strikes a good balance between security and speed for most use cases.

To generate a pair of SSH keys, run the following command on your local machine:

$ ssh-keygen -t ed25519

You will be prompted to enter a file path for the key. You may accept the default - ~/.ssh/id_ed25519 - or choose another path/name.

Next, you will be prompted to enter a passphrase. This is an extra layer of security, but you can leave it blank if you want.

There are now two new files in the .ssh directory:

$ cd ~/.ssh
$ ls -1
authorized_keys
config
id_ed25519
id_ed25519.pub
known_hosts

The id_ed25519 file is your private key and it should never be shared with anyone.

The id_ed25519.pub file is your public key.

Warning

In most cases, you don’t need to explicitly specify the location of the private key in your ~/.ssh/config file because SSH will automatically look for the default key names (like id_rsa, id_ed25519, etc.) in the ~/.ssh directory.

However, if you’re using a non-default name or location for your private key, or if you have multiple keys and want to specify which one to use for a particular host, then you can add the IdentityFile directive in your ~/.ssh/config to point to the private key.

For example, if you have a private key with a custom name <MY-SPECIAL-KEY> in the ~/.ssh directory, you can add the following lines to your ~/.ssh/config file:

config#
# Specify our intermediate jump host, aka the bastion node
Host swc-bastion
    HostName ssh.swc.ucl.ac.uk
    User <SWC-USERNAME>
    IdentityFile ~/.ssh/<MY-SPECIAL-KEY>

# Specify how to get to the gateway node by jumping through the bastion node
# The gateway hostname is specified as the jump-host would see it
Host swc-gateway
    HostName hpc-gw1
    User <SWC-USERNAME>
    ProxyJump swc-bastion
    IdentityFile ~/.ssh/<MY-SPECIAL-KEY>

Next, let’s copy the public key you just generated to the remote machines.

$ ssh-copy-id -i id_ed25519.pub swc-gateway
Explain the above command

The ssh-copy-id command uses the configuration we previously set up in the config file to figure out how to reach the remote machine.

It copies the specified public key to your home directory on the target machine (in this case swc-gateway) and adds it to the .ssh/authorized_keys file there.

Since your SWC home directory is shared across all HPC nodes, the public key will be available on all of them. That’s why you only need to run the above command once, with either swc-bastion or swc-gateway as the target.

🎉 Congrats! You can now directly SSH into the gateway node without typing your password:

$ ssh swc-gateway

In case you want to SSH into the bastion node, you can do so by typing:

$ ssh swc-bastion

Remote development#

One benefit of setting your SSH config and SSH keys is that you can now easily use Visual Studio Code to edit files on remote machines. This is especially useful for editing scripts on the gateway node that you want to run on the compute nodes of the cluster.

To do this, you need to install the Remote - SSH extension in VS Code. Then, when you click on the “Open a Remote Window” button in the bottom left corner of the VS Code window, you will see a list of the SSH hosts you have configured in your ~/.ssh/config file. You can then select the host you want to connect to - e.g. swc-gateway - and VS Code will open a new window with a terminal connected to that host. You can then use the VS Code GUI to navigate the file system and edit files on the remote machine.

Other IDEs like PyCharm also offer similar functionality.