Additional security policy measures in force
Please note that we are currently applying a policy of requiring your user account password in addition to your password-protected SSH key to login to Apocrita.
Once you have an account, you can log into the cluster from any network (internal to QMUL, over eduroam, or from other sites over the internet) using a secure shell (SSH).
Never share your private key or password with anyone
Your private key / password identifies you as yourself, anyone with either of these can access the cluster using your account.
SSH access via the Terminal¶
To login into Apocrita using your password and SSH key, use one of the following methods (valid for all Linux, macOS and Windows 10+ systems).
Firstly, open a local terminal or the Windows Command Prompt.
- On Linux systems, this will usually be an application called "Terminal".
- On macOS systems, go to
- On Windows 10+, type cmd (short for command) into the search box, and press Enter. You may need to firstly enable the OpenSSH client if SSH commands do not work by default.
Then connect using one of the above methods, further described below. In all
USERNAME with your Apocrita username and
/path/to/privatekey with the real path to your generated private key. If you
have not already generated a key pair, see the
instructions to generate a SSH key pair.
Your password will not be displayed
Linux does not display feedback as passwords are typed.
SSH connection with a specific key¶
Run the following command to SSH into Apocrita specifying a private key.
ssh -i /path/to/privatekey USERNAME@login.hpc.qmul.ac.uk
- On Linux the key path defaults to
- On macOS the key defaults to
- On Windows 10+ the key defaults to
USER is the username on your local machine.
Add the key to your SSH agent¶
Run the following commands to add the private key to your SSH agent and log in to Apocrita.
ssh-add /path/to/privatekey ssh USERNAME@login.hpc.qmul.ac.uk
By using the SSH agent, you will not be prompted for the key passphrase every time you use the key once the key has been added to the agent. A key will remain in the agent until either removed, the agent is restarted or your machine is rebooted.
The SSH agent might be disabled by default on Windows 10+, to enable this, open the Services window, right click on the OpenSSH Authentication Agent entry and press Start. If this option is not available, click Properties and change the Startup Type to "Automatic", then start the service.
Create an SSH configuration file¶
.ssh directory, create a file called
config and include
Host apocrita Hostname login.hpc.qmul.ac.uk User USERNAME IdentityFile /path/to/privatekey
Now you can SSH to Apocrita using the following command:
As you have stored your username, remote hostname and private key information inside the SSH user configuration file, you do not need to specify these on the command line.
Please also see our step-by-step video tutorial which demonstrates the process of creating SSH keys, and logging in to the QMUL Apocrita HPC cluster for Linux / MacOS users.
Windows Subsystem for Linux (WSL)¶
You can install WSL on Windows by opening a Windows Terminal or Powershell window as an administrator and issuing:
This command will enable the required optional components, download the latest Linux kernel, set WSL 2 as your default, and install a Linux distribution for you (Ubuntu by default).
You can check which version of WSL is installed using:
wsl -l -v
which will output something like:
NAME STATE VERSION * Ubuntu Stopped 2
To start using WSL, simply open a Windows Terminal or Powershell window and issue:
More in-depth installation documentation is available from Microsoft.
WSL contains a full Linux environment, so the majority of any documentation written for Linux should apply and things like X forwarding should work, after starting WSL.
SSH keys under WSL¶
For creating a new SSH key inside WSL, please follow the instructions for Linux that you will find here.
If you have created SSH keys on Windows using the Windows terminal, they will
be stored in
c:\Users\<username>\.ssh. However, you can't use SSH keys stored
in this directory directly from WSL as the permissions aren't strict enough and
you will receive an error message:
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ @ WARNING: UNPROTECTED PRIVATE KEY FILE! @ @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ Permissions 0755 for '/home/user/.ssh/id_rsa' are too open. It is required that your private key files are NOT accessible by others. This private key will be ignored. Load key "/home/user/.ssh/id_rsa": bad permissions firstname.lastname@example.org: Permission denied (publickey).
Instead, you will need to copy your keys into the WSL environment - run the following from within WSL:
cp -r /mnt/c/Users/<username>/.ssh/* ~/.ssh
and then set the correct permissions:
chmod -R 600 ~/.ssh/*
SSH key permissions
All files in
~/.ssh need to have
0600 permissions, so repeat the
process above if you copy any new/additional keys or config files into it.
For further information, please see here.
MobaXterm setup instructions (Windows only)¶
MobaXterm is only supported on Windows operating systems
If you are using Linux or macOS, please see the SSH access via the Terminal instructions above.
Users may find WSL a better option than MobaXterm, as it is supported directly by Microsoft and part of Windows. The instructions below are for legacy users or those that prefer to use MobaXterm.
If you require a graphical SFTP connection and X Windows support, then you can use MobaXterm. The following instructions explain how to create a session to log into Apocrita.
- Open MobaXterm.
- Click on the Session tab above the Quick connect textbox. This will bring up a new window.
- Click SSH (first option) to display the SSH settings.
- Enter login.hpc.qmul.ac.uk in the Remote host box.
- Check the Specify username box and enter your Apocrita username into the textbox.
- Click the Advanced SSH settings tab to display further options.
- Check the Use private key box, click the page icon at the right of the textbox and browse to your private key.
- Click OK to save your session. This will also attempt a connection to Apocrita.
When logging in, you should be asked for your SSH key passphrase, then your Apocrita password. You may click Yes when prompted to save your Apocrita password securely so you do not need to type this every time you login.
Please also see our step-by-step video tutorial which demonstrates the process of creating SSH keys, and logging in to the QMUL Apocrita HPC cluster for Windows users.
Changing your password¶
Once you have an account, you should be able to change your Apocrita password using the ITS Research Password Manager. Please make sure that you read the recommendations carefully. This site is protected behind the QMUL idcheck service therefore, only users with valid QMUL IT Services accounts will be able to use this process.
The password change will affect access to the following ITS Research services:
- Apocrita HPC cluster
- GitHub Enterprise (research version)
- Stats page
- Redmine ticketing system web interface
- Learning site
You can also add a new SSH public key when you cannot access Apocrita by using this form.
For changing your college password please use central IT Services PRM utility.
If you cannot remember your password please contact us requesting a one-time unlocking code.
One-time unlocking code
If you were given a one-time unlocking code, please enter it into the
One-time unlocking code field leaving the
The X windows system allows forwarding of graphical applications running on cluster nodes to the user's desktop. This allows programs like MATLAB to be run on the cluster using the GUI. Due to the overhead of running and GUI and the need for a constant connection this is discouraged but may be required by certain applications.
Initial setup varies based on the user's operating system.
Linux and macOS X Windows¶
macOS users need to download XQuartz
macOS requires the installation of XQuartz to allow X Windows software to be used.
-X to the SSH command line will enable X forwarding:
ssh -X -i /path/to/privatekey USERNAME@login.hpc.qmul.ac.uk
If you experience issues with drawing the GUI or receive errors it may be worth
-Y instead of
-X which will enable X forwarding without the X11
ssh -Y -i /path/to/privatekey USERNAME@login.hpc.qmul.ac.uk
The SSH configuration file also supports enabling X forwarding for all
connections so you do not need to pass the
-Y options. To enable this
ForwardX11 yes to the
apocrita section in your configuration file. For
Host apocrita Hostname login.hpc.qmul.ac.uk User USERNAME IdentityFile /path/to/privatekey ForwardX11 yes
Windows X Windows¶
MobaXterm has X windows built in and forwarded by default so no additional user steps are required.
WSL also supports X forwarding by following the steps for Linux above.
If you are using the Windows Command Prompt (Windows 10+), you will need to download and run an X server application (such as Xming) to launch X windows. However, this isn't a recommended method - it is better to use MobaXterm or WSL. Please contact us if you need assistance setting up this type of connection.