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
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.
- 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-keygen commands but not the
Open a terminal and execute the
ssh-keygen command as shown below (the
example below assumes the key will be saved to
# 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
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]
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.
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.