# Connecting to CSC supercomputers

--8<-- "ssh-ca.md"

There are two main ways of connecting to CSC supercomputers.

1. The traditional way to connect to a supercomputer is
   [using an SSH client](#using-an-ssh-client).
2. We also offer a [web interface](#using-the-web-interface) to our systems,
   which enables running both graphical applications and command-line shells.

Additionally, we also offer a [RESTful HTTP API](#using-the-firecrest-hpc-api) based on [FirecREST v2](https://eth-cscs.github.io/firecrest-v2/), which is the primary interface for [machine-to-machine robot account](../../accounts/how-to-create-new-user-account.md#getting-a-machine-to-machine-robot-account) usage.

For instructions on connecting to the LUMI supercomputer, please see the
[Get Started page in the LUMI user guide](https://docs.lumi-supercomputer.eu/firststeps/getstarted/).

!!! note "Login node usage policy"
    When you connect to a supercomputer using an SSH client or the
    [*Login node shell*](../webinterface/shell.md) app, you are directed to a
    login node. Login nodes are **not meant for long or heavy processing**.
    The accepted uses for login nodes are defined in our
    [login node usage policy](../usage-policy.md#login-nodes).

## Using the web interface

The [web interface](../webinterface/index.md) is a good platform
for using graphical applications on CSC supercomputers. It hosts
[interactive applications for select programs](../webinterface/apps.md)
like Jupyter and RStudio, and for other GUI programs you can use the
[remote desktop](../webinterface/desktop.md) interface.

It is also possible to [open a shell program](../webinterface/shell.md) on a
login node or compute node. The compute node shell is persistent, meaning it
will keep running even if you close your browser or lose your internet
connection. The shell applications are especially convenient for users whose
workstation has a Windows operating system, since Windows does not
typically come with a pre-installed SSH client. See the instructions for
[connecting to HPC web interfaces](../webinterface/connecting.md).

## Using the FirecREST HPC API

The [FirecREST HPC API](../firecrest/index.md) provides a standardized RESTful interface for accessing computing resources from web-based software. It offers APIs for managing jobs through Slurm scheduler, performing file system operations over personal and project data, and for transferring large amounts of data to or from the system.

## Using an SSH client

Logging in to CSC supercomputers using an SSH client requires that you have

1. [set up SSH keys](ssh-keys.md),
2. [added your public key to MyCSC](ssh-keys.md#adding-public-key-in-mycsc),
   and
3. Only in Roihu: [sign your public key](ssh-keys.md#signing-public-key) to obtain a
   time-based SSH certificate, must be repeated every 24 hours.

```mermaid
flowchart LR
    A(<b>Before first connection:</b>
      <a href='ssh-keys/'>Set up SSH keys</a>)
    A --> B{Connecting
            to Roihu?}
    B -->|yes| C(<b>Once every 24 hours:</b>
                 <a href='ssh-keys/#signing-public-key'>Get a new SSH certificate</a>)
    C --> D(<a href='ssh-unix/'>SSH with Linux/macOS</a>
            or
            <a href='ssh-windows/'>SSH with Windows</a>)
    B -->|no| D
```

Please note that traditional password-based authentication and public keys
stored in your personal `~/.ssh/authorized_keys` file will **not** work.

Unix-based systems like macOS and Linux typically come with a pre-installed
terminal program called simply *Terminal*. The instructions for using an
[SSH client on macOS and Linux](ssh-unix.md) show how to connect to a CSC
supercomputer using the terminal program.

Windows comes with the `Command Prompt` terminal program that typically has the OpenSSH
ssh client installed. This client works in a similar fashion to the ssh clients on Linux and MacOS. 
In addition to this client, Windows has multiple programs that can be used for this.
The instructions for using an [SSH client on Windows](ssh-windows.md) lists a few popular options.

Once you have set up SSH keys, added your public key to MyCSC, and signed it to
generate an SSH certificate (only required for Roihu), use a command like below
to connect over SSH:

```bash
# 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
```

!!! note
    It might take up to one hour for your new key to become active on Puhti or Mahti after adding
    it to MyCSC. Roihu has no such delay since it is based on SSH certificates.

Once the SSH connection to the supercomputer is open, you can interact with it
by issuing Linux commands using the Bash shell program. An introduction to
working on the Linux command-line can be found in our
[Linux basics tutorial for CSC](../../support/tutorials/env-guide/index.md).
You can have several connections to CSC supercomputers open at the same time.

### First connection

When connecting to a given supercomputer for the first time, the SSH client
may notify you that the host is unknown, and ask you to confirm the connection.
With the OpenSSH client, the message looks like this:

```text
The authenticity of host 'puhti.csc.fi' can't be established.
ECDSA key fingerprint is SHA256:kk0Tar9opQ+6Gq0GWJdWVVvFEMeI6kW1DW1VOYveT5c.
Are you sure you want to continue connecting (yes/no/[fingerprint])?
```

In order to continue, you should confirm that the displayed key fingerprint is
found in the [table below](#host-key-fingerprints), and then enter `yes`. You
will not be asked again unless the server key changes, in which case you
should again verify the new key against fingerprints provided by CSC.

#### Host key fingerprints

=== "Roihu"
    | SHA256 checksum                             | Key                                |
    |---------------------------------------------|------------------------------------|
    | h3YVzmNucpxTXcxag8D2TaC21jH8/6LGNNCCOgRDaTU | ssh_host_ecdsa_key.pub (ECDSA)     |
    | YNdesHbXhxN0hKD4mWvYGQONebjRqY+CGXDqPiZyByQ | ssh_host_ed25519_key.pub (ED25519) |
    | cXJ5h3Z9fgu0wVpC2kDIpjdsrFsJF/bfyWegQXsfQpU | ssh_host_rsa_key.pub (RSA)         |

=== "Puhti"
    | SHA256 checksum                             | Key                                |
    |---------------------------------------------|------------------------------------|
    | kk0Tar9opQ+6Gq0GWJdWVVvFEMeI6kW1DW1VOYveT5c | ssh_host_ecdsa_key.pub (ECDSA)     |
    | Q2lpykI43ffs4PrRODZ/qncjUo3eyrRHc5T9yjJEwWY | ssh_host_ed25519_key.pub (ED25519) |
    | WH1Ag2OQtMPZb+hj3YeH9uVMMetXpCvyNUbsdk0Qcpk | ssh_host_rsa_key.pub (RSA)         |

=== "Mahti"
    | SHA256 checksum                             | Key                                |
    |---------------------------------------------|------------------------------------|
    | WC9Lb5tmKDzUJqsQjaZLvp9T7LTs3aMUYSIy2OCdtgg | ssh_host_ecdsa_key.pub (ECDSA)     |
    | tE+1jA4Et1enbbat1V3dMRWlLtJgA8t7ZrkyIkU4ooo | ssh_host_ed25519_key.pub (ED25519) |
    | 0CxM3ECpD2LhAnMfHnm3YaXresvHrhW4cevvcPb+HNw | ssh_host_rsa_key.pub (RSA)         |

### Graphical connection

We recommend using the web interfaces for running applications with graphical
user interfaces. Alternatively, graphics can also be displayed over an SSH
connection using X11 forwarding. See the operating system-specific instructions:

* [X11 forwarding on Linux and macOS](ssh-unix.md#graphical-connection)
* [X11 forwarding on Windows](ssh-windows.md#graphical-connection)

### Advanced usage

#### Connecting to a specific node

When you connect to a supercomputer, you are automatically directed to one of
the login nodes on the system. However, you can also use your SSH client to
connect to a specific login node:

```bash
ssh <username>@<host>-login<id>.csc.fi  # e.g. 'roihu-gpu-login1.csc.fi'
```

The available login nodes are:

| Puhti | Mahti | Roihu CPU | Roihu GPU |
|-|-|-|-|
| `puhti-login11` | `mahti-login11` | `roihu-cpu-login1` | `roihu-gpu-login1` |
| `puhti-login12` | `mahti-login12` | `roihu-cpu-login2` | `roihu-gpu-login2` |
| `puhti-login14` | `mahti-login14` | `roihu-cpu-login3` |                    |
| `puhti-login15` | `mahti-login15` | `roihu-cpu-login4` |                    |

This also applies to compute nodes, although just the ones where you have a
job running. Use the `squeue` command to see which node(s) your job is on, and
then connect to a node using `ssh`.

!!! warning "Direct SSH connection into compute nodes on Roihu has not yet been configured"
     A direct SSH connection into compute nodes on Roihu is not yet configured.
     For connecting onto compute nodes where you have a job running, use Slurm's overlap feature:

     ```text
     srun --jobid=<jobid> --overlap --pty bash
     ```

     Or for targeting a specific node in a multi-node run:
     ```text
     srun --jobid=<jobid> --overlap --nodelist=rcXXXX --pty bash
     ```

     Replace `<jobid>` and `rcXXXX` in the above with your job ID in Slurm and the specific node
     you want to connect into.


```bash
# The nodes hosting the job are
# displayed in the "NODELIST(REASON)" column.

[username@puhti-login11 ~]$ squeue --me
             JOBID PARTITION     NAME     USER ST       TIME  NODES NODELIST(REASON)
          12345678      test     test username  R       0:01      1 r07c01
[username@puhti-login11 ~]$ ssh r07c01
[username@r07c01 ~]$ hostname
r07c01.bullx
```

If you try to connect to a node where you have no active jobs, you will
receive the following error message: `Access denied by pam_slurm_adopt: you
have no active jobs on this node`.