SSH client on macOS and Linux

SSH certificates are required to connect to Roihu over SSH

To connect to Roihu, users must sign their public key in MyCSC to obtain a time-based SSH certificate. Each certificate is valid for 24 hours, and once it expires, a new one must be generated by signing the public key again.

Read the detailed instructions on signing your public key.

On Unix-based systems like macOS and Linux, it is recommended to connect to CSC supercomputers using the pre-installed terminal program. The OpenSSH client typically comes pre-installed on macOS and Linux systems.

Generating SSH keys

Using SSH keys

See the page on setting up SSH keys for general information about using SSH keys and certificates for authentication. Please note that it is mandatory to add your public key to MyCSC – copying it directly to a CSC supercomputer does not work!

Supported key types are Ed25519 and RSA 4096 through 16384. We strongly recommend Ed25519.

Connecting to CSC supercomputers using an SSH client requires setting up SSH keys. On macOS and Linux, you can use the ssh-keygen command-line utility for generating SSH keys:

ssh-keygen -a 100 -t ed25519

If you have not set up SSH keys before, feel free to accept the default name and location by pressing ENTER (recommended). However, if using the default file name would overwrite an existing key, you will receive a warning that looks like this:

/home/<username>/.ssh/id_ed25519 already exists.
Overwrite (y/n)?

Generally, you do not want to overwrite existing keys, so enter n, run ssh-keygen again and enter a different file name when prompted. See also the section on SSH key files with non-default name or location.

Next, you will be asked for a passphrase. Please choose a secure passphrase. It should be at least 8 characters long and contain numbers, letters and special characters. Never leave the passphrase empty when generating an SSH key pair!

After you have generated an SSH key pair, you need to add the public key to the MyCSC portal. Read the instructions here. To connect to Roihu, you must also sign your public key to obtain a time-based SSH certificate which is required for authentication.

You may also wish to configure authentication agent to make using SSH keys more convenient.

Basic usage

After setting up SSH keys, adding your public key to MyCSC, and downloading an SSH certificate (required for Roihu only), you can create a remote SSH connection by opening the terminal and running:

# Replace <username> with the name of your CSC user account and
# <host> with "puhti", "mahti", "roihu-cpu" or "roihu-gpu"

ssh <username>@<host>.csc.fi

This assumes that the SSH keys (and certificate for Roihu) are saved in a standard location using standard naming:

Private key: ~/.ssh/id_<algorithm>
Public key: ~/.ssh/id_<algorithm>.pub
Certificate: ~/.ssh/id_<algorithm>-cert.pub

where <algorithm> is either ed25519 or rsa.

SSH key or certificate file with non-default name or location

If you have stored your SSH key and/or certificate file with a non-default name or in a non-default location, you must tell the ssh command where to look for these files. Use option -i as follows:

# Replace <username> with the name of your CSC user account,
# <host> with "puhti", "mahti", "roihu-cpu" or "roihu-gpu",
# <path-to-private-key> with the path to your SSH private key and
# <path-to-certificate> with the path to your SSH certificate file (Roihu only)

ssh <username>@<host>.csc.fi -i <path-to-private-key> -i <path-to-certificate>

Alternatively, you may specify the key location in the ~/.ssh/config file:

Host <host>
  HostName <host>.csc.fi
  User <csc-username>
  IdentityFile <path-to-private-key>
  CertificateFile <path-to-certificate>

The ~/.ssh/config file above would allow you to log in to <host> simply using:

ssh <host>

Graphical connection

Note

For performance reasons, we generally recommend using the HPC web interfaces to run applications which require displaying graphics.

Displaying graphics, such as GUIs and plots, over an SSH connection requires a window system. Linux systems have a server program for the X window system (X11) installed by default. On macOS you need to install one separately, for example XQuartz.

To enable displaying graphics over SSH, use the -X (X11 forwarding) or -Y (trusted X11 forwarding) option when launching the SSH client:

ssh -X <username>@<host>.csc.fi

For more information about the X11 forwarding options, run man ssh in the terminal.

Authentication agent

To avoid having to type your passphrase every time you connect to a CSC supercomputer, the ssh-agent utility can hold your SSH keys and certificates in memory. The program's behavior depends on your system:

On Linux systems, ssh-agent is typically configured and run automatically at login and requires no additional actions on your part.
On macOS systems, you should add the following lines to the ~/.ssh/config file (create the file if it does not exist):
```
Host <host>.csc.fi
    UseKeychain no
    AddKeysToAgent yes
```
Assuming your SSH private key and certificate (required for Roihu only) are stored in ~/.ssh/id_ed25519 and ~/.ssh/id_ed25519-cert.pub, add them to the authentication agent by running:
```
$ ssh-add ~/.ssh/id_ed25519
Enter passphrase for ~/.ssh/id_ed25519: # enter key passphrase here
Identity added: ~/.ssh/id_ed25519
Certificate added: ~/.ssh/id_ed25519-cert.pub
```
This step is done automatically if you use the CSC certificate helper tool to sign and download your SSH certificate!

Important note if you're not using the certificate helper tool

Users downloading SSH certificates manually from MyCSC must store it in the same directory as the SSH private key and name it as <private-key-name>-cert.pub to be able to add it to SSH agent with ssh-add command. If successful, ssh-add outputs:

Certificate added: ~/.ssh/id_ed25519-cert.pub

If the certificate is stored and/or named in any other way, it cannot be added to the authentication agent because OpenSSH uses hard-coded naming conventions.

If you intend to connect to Roihu via a jump host (e.g. when transferring data from another CSC server to Roihu), also the SSH certificate must be added to the SSH agent so that it can be properly forwarded.
Alternatively, you may connect to Roihu and pull data from servers that do not require a SSH certificate (e.g. Puhti or Mahti). In this case it is enough to forward only your SSH keys.
Read more about SSH agent forwarding below.

SSH agent forwarding

Note

You should only forward your SSH agent to remote servers that you trust and only when you really need it. Forwarding your SSH agent by default to any server you connect to is considered insecure.

Agent forwarding is a useful mechanism where the SSH client is configured to allow an SSH server to use your local ssh-agent on the server as if it was local there. This means in practice that you can, for example, connect directly between CSC supercomputers using the SSH keys and certificates you have on your local machine, i.e. you do not need to create a new set of SSH keys on CSC supercomputers.

Agent forwarding is also very handy if you need to copy data directly between CSC supercomputers, or, for example, push to a private Git repository from CSC supercomputers.

To enable agent forwarding, include the -A flag to your ssh command:

ssh -A <username>@<host>.csc.fi

Once connected, you may verify that SSH agent forwarding worked by running:

$ ssh-add -l

If you see the fingerprint(s) of your SSH key(s) and certificate(s) listed, agent forwarding is working. Associated SSH keys and certificates in the authentication agent have the same fingerprints and are annotated with <ALGORITHM> and <ALGORITHM>-CERT, respectively. For example:

256 SHA256:ZXG7TvhDAWOv8VveFAlt/UYarsO9Nx5md4owX+FE5/M optional_comment (ED25519)
256 SHA256:ZXG7TvhDAWOv8VveFAlt/UYarsO9Nx5md4owX+FE5/M optional_comment (ED25519-CERT)

Configuring SSH client

You can save yourself some time by adding host-specific options for CSC supercomputers in an SSH config file (e.g. ~/.ssh/config).

Host <host>  # e.g. "roihu-cpu"
    HostName <host>.csc.fi
    User <csc-username>
    IdentityFile <path-to-private-key>
    CertificateFile <path-to-certificate>  # Required for Roihu only

Now you can connect to the host simply by running:

ssh <host>