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 server, 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 initial 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.

# You can now login with your private key, replacing USERNAME with your
# Apocrita user name
$ ssh USERNAME@login.hpc.qmul.ac.uk

To copy your initial key to Apocrita you must request it to be uploaded by us. This can be done via this form. Once the 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.

Creating and using additional keys and agent forwarding

In this example, we use ssh-keygen to create a public/private key-pair, copy it to Apocrita with ssh-copy-id and then use ssh-add to add the identity to an SSH agent. You will need the ssh-askpass program to be installed to allow confirmation of the SSH agent forwarding.

Providing your initial public key

If you don't have an existing public key stored on Apocrita, you can provide one using this form. An active QMUL IT Services account is required to use this form.

In the instructions below, we are using the ~ shortcut for the home directory, but you can equally use the $HOME variable instead.

Open a terminal:

# Generate public/private key-pair (with a 4096-bit RSA key length for Apocrita)
# storing the private key in ~/.ssh/id_rsa_apocrita - the public key is
# automatically named ~/.ssh/id_rsa_apocrita.pub
ssh-keygen -b 4096 -t rsa -f ~/.ssh/id_rsa_apocrita

# Copy public key to Apocrita, replacing USERNAME with your Apocrita user name
ssh-copy-id -i ~/.ssh/id_rsa_apocrita USERNAME@login.hpc.qmul.ac.uk

# Add the Apocrita private key identity to your SSH agent, requesting
# confirmation before using the key
ssh-add -c ~/.ssh/id_rsa_apocrita

# Connect to Apocrita, enabling SSH agent forwarding, providing your password
ssh -A USERNAME@login.hpc.qmul.ac.uk
[confirm to the SSH agent that this was your login request]

Maintaining your authorized_keys file

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

The ssh-copy-id command will automatically add your public key to the authorized_keys file and is the recommended approach for adding keys. However, any old, revoked or lost keys must be manually removed from this file by the user to maintain security of the system.