Connecting via SSH (Linux/macOS)

SSH (Secure Shell) is the standard way to securely connect to remote servers on Linux and macOS. This guide will walk you through connecting to the HLRS training cluster using the provided SSH key.

Step 1: Store Your SSH Key

Save your SSH key file:
sca50xxx
to your system. SSH keys are typically stored in the ~/.ssh/ directory. If this directory doesn't exist, create it first.

Step 2: Restrict Permissions

For security reasons, SSH requires that you be the only user with read and write access to the SSH key. You can restrict the permissions of the SSH key file by opening a terminal window and running the following command:
chmod 600 ~/.ssh/sca50xxx

Step 3: Connect to the Server

The username on the cluster is identical to the name of your SSH Key file and also has the form sca50xxx. You can use that to connect to the cluster with the following command:
ssh -D 8080 -Xi ~/.ssh/sca50xxx sca50xxx@training.hlrs.de

The -D option enables port forwarding on port 8080, which is needed for running a Jupyter-Notebook on the cluster.
The -X option allows you to open graphical applications over SSH.
The -i option allows you to choose a specific identity file (SSH key) for authentication.

If you connect to a server for the first time, you will get this message:

The authenticity of host 'training.hlrs.de (141.58.0.221)' can't be established.
ED25519 key fingerprint is SHA256:19E0sAY21G6+o4nEkaqYv6qFSgOzMdf3uEzh2mBZKhI.
This key is not known by any other names.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Enter yes to continue. The fingerprint will be saved to your ~/.ssh/known_hosts file and will let you identify the server in the future.

You should now see the following command line prompt:

students cl7fr1 1$

which means you are logged in and can run commands on the Training Cluster. Type exit to disconnect from the server when you are finished.

Step 4: Configure SSH

You can simplify future connections by adding a configuration block to your ~/.ssh/config file. If this file does not exist, create it with exactly this name (no file extension), for example by typing nano ~/.ssh/config in a terminal. Add the following block, save with Ctrl+O, Enter and exit with Ctrl+X. Replace the placeholders with your actual values:

Host <alias>
    Hostname training.hlrs.de
    Port 22
    User sca50xxx
    IdentityFile ~/.ssh/sca50xxx
    IdentitiesOnly yes
    PreferredAuthentications publickey,keyboard-interactive
    ServerAliveInterval 60
    ServerAliveCountMax 5
    ForwardX11 yes
    DynamicForward 8080

SSH options explained: ▶

IdentitiesOnly yes
only use the specified key; do not try other keys loaded in the agent. This helps prevent failed login attempts that could get your IP address blocked by the server.
PreferredAuthentications publickey,keyboard-interactive
try key-based login first, fall back to OTP/challenge-response. Plain password auth is not supported by HLRS and is skipped. This helps prevent failed login attempts that could get your IP address blocked by the server.
ServerAliveInterval 60
send a keepalive packet every 60 seconds to prevent idle disconnects.
ServerAliveCountMax 5
drop the connection after 5 missed keepalive responses (approx. 5 minutes).
ForwardX11 yes
allow graphical programs running on the cluster to open windows on your local machine (see the X-forwarding section of this guide).
DynamicForward 8080
open a local SOCKS proxy on port 8080, needed by courses that use port forwarding (see the port forwarding section of this guide).

After adding this block, you can connect to the cluster using the following simple command:
ssh <alias>
If you land on the cluster, everything works. Type exit to return to your local terminal.

We recommend naming this alias after a short version of your course, for example CFD for Computational Fluid Dynamics. If you attend multiple courses, make sure each alias is unique.

Step 5: Copying data to and from the cluster

All methods in this step use the same SSH connection,
<alias> , you already set up in Step 4.

Most Linux file managers can also browse the cluster like a local folder. Enter sftp://<alias>/zhome/training/sca50xxx/ in the address bar. In GNOME Files, click Other Locations in the sidebar, and copy files by drag and drop.
With scp you can copy files between your computer and the training cluster from the command line.
Important: run all commands in this section in a terminal on your own computer. Do not run them in a terminal that is already connected to the cluster.

Upload a single file to your home directory

scp local_file.txt <alias>:

Upload a whole directory to a remote path

scp -r local_dir <alias>:/path/to/remote/dir/

Download a file to the current local directory

scp <alias>:/path/to/remote/file.txt .

The colon separates the host alias from the path on the cluster. A colon with nothing after it means your home directory on the cluster.

Submit jobs on the cluster

After successfully connecting to the cluster, you can start submitting compute jobs. To see how, follow the guide:
Getting started on a compute cluster