Skip to content

Setting up SSH key-based access to Apocrita

SSH keys allow secure, password-less access to remote systems such as Apocrita. They are very easy to set up and provide a greater level of security than using a password, while being convenient too.

Generating an SSH key pair provides you with a public and a private key which are two files containing long character strings. You can place the public key on any server, and then unlock it by connecting to it from the computer that has the private key on it. If the two keys match up then you are given access to the remote system. Although it is possible to create a key pair without a passphrase you must protect the private key with a passphrase, so that it cannot be used by someone who gains access to your private key file.

Never share your private key

Your private key is the part of the key pair that identifies you as yourself. Even a passphrase protected private key should not be shared with anyone or stored in a public area (including on a remote server).

If you do not use the default location for keys please ensure that your key is saved somewhere that is protected under your user account on that machine.

Protecting your account on Apocrita and other services

Although SSH keys are convenient and reasonably secure, there are risks associated with them. Our usage policy requires that you protect the key you use to access Apocrita with a passphrase, but there are additional steps that you can take to make the use of SSH keys even more secure.

We recommend that you never store a private key file on a multi-user machine. This includes on Apocrita itself, since only the public part of the key is needed to be stored on a server to gain access using the private key stored on your machine.

In particular, if you need to use SSH to access services from the Apocrita login nodes, such as compute nodes to check on the status of one of your running jobs or GitHub, we recommend that you use SSH agent forwarding instead of a private key. Please see the examples below using ssh-add.

Equally, you can use SSH agent forwarding if you need to transfer data between Apocrita and other remote servers. This should allow you to avoid storing your Apocrita private key remotely, or your other remote server key on Apocrita.

If you use SSH keys to access several different services such as other QMUL machines, the Tier 2 services, GitHub or the QMUL-hosted GitHub Enterprise servers, you should use different key pairs for each service.

In summary,

  • Protect your private key with a passphrase.
  • Use a different key for each service.
  • Don't share your private key with someone.
  • Don't store your private key on remote servers, or a machine you do not own.
  • SSH agent forwarding allows you to use your private key on a remote server without the key leaving your machine.

Creating an SSH key for accessing Apocrita

Operating System Variations

The following commands will work on Linux and recent versions of macOS. Windows users may follow these instructions within the MobaXterm application. The native Windows command prompt also supports ssh and ssh-keygen commands but not the ssh-copy-id utility.

Open a terminal and execute the ssh-keygen command as shown below (the example below assumes the key will be saved to /home/USERNAME/.ssh/id_rsa):

# Generate public/private key pair (with a 4096-bit RSA key length for Apocrita)
$ ssh-keygen -b 4096 -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/USERNAME/.ssh/id_rsa): [enter full path here]
Enter passphrase (empty for no passphrase): [enter your passphrase]
Enter same passphrase again: [enter same passphrase]
Your identification has been saved in /home/USERNAME/.ssh/id_rsa.
Your public key has been saved in /home/USERNAME/.ssh/id_rsa.pub.

# Now you need to submit your public key (id_rsa.pub) and after confirmation
# you can login with your private key, replacing USERNAME with your
# Apocrita user name
$ ssh -i ~/.ssh/id_rsa USERNAME@login.hpc.qmul.ac.uk

Once created, submit your public key via this form which will be sent to ITS Research. After your key has been verified and copied into place, you will receive a confirmation email. At this point you will be able to log into Apocrita using one of the methods described here.

Please also see our step-by-step video tutorials for Linux / MacOS and Windows machines, which demonstrate the process of creating SSH keys, and logging in to the QMUL Apocrita HPC cluster.

If you prefer a written tutorial, you can follow our blog post, which explains the same process in detail.

SSH key passphrase

ITS Research will be unable to recover/reset your SSH key passphrase. If a private key becomes unusable due to a lost passphrase, please delete and re-create a new SSH key pair then submit the new public key using this form

Setting up SSH keys on different machines

To access Apocrita from an alternative machine (i.e. a new laptop), please follow these instructions.

Additional SSH keys on the same machine

To create additional SSH keys on the same machine that your initial SSH key was created, you may generate a new key pair and use the ssh-copy-id utility (Linux / MacOS only) to install new keys on Apocrita without uploading your public SSH key using our form. For further assistance, please contact us.

Maintaining your authorized_keys file on Apocrita

The authorized_keys file in the $HOME/.ssh folder on Apocrita contains a list of the public keys that will allow a user to authenticate into their account, by providing the corresponding private key. Lines starting with # and empty lines are ignored.

Any old, revoked or lost keys must be manually removed from this file by the user to maintain security of the system. ITS Research reserve the right to disable or remove any old or duplicate public SSH keys.