# Using SSH

Before accessing CSCS clusters using SSH, first ensure that you have [created a user account](<https://docs.cscs.ch/accounts/index.md#getting-and-managing-accounts> "Getting and Managing Accounts") that is part of a project that has access to the cluster, and have [multi factor authentication](<https://docs.cscs.ch/access/mfa/index.md#multi-factor-authentication> "Multi Factor Authentication") configured.

## SSH key management overview

Username+password authentication is not available for SSH access. Instead, you must use SSH keys signed by CSCS. The recommended approach is to generate the SSH key locally and then have it signed by CSCS.

Two methods are available for managing SSH keys:

- **Command-line app** `cscs-key`
- **Web Dashboard** [user-account.cscs.ch](<https://user-account.cscs.ch>)

## Command-line access

The CLI interface to the SSH service is called `cscs-key`, an open source tool developed by CSCS to simplify managing keys.

### Installation

To install `cscs-key`, use Homebrew on macOS or Linux, or download a release binary from the [GitHub releases page](<https://github.com/eth-cscs/cscs-key/releases>) on any platform. For a manual install, unpack the archive and place the binary in a directory on your `PATH` (`$HOME/.local/bin` on macOS/Linux, `$HOME\bin` on Windows). The snippets below set `TAG=v1.1.0` — replace it with the [latest release tag](<https://github.com/eth-cscs/cscs-key/releases>). On Windows, choose the PowerShell tab for the native binary, or the Linux tab when running inside [WSL](<https://learn.microsoft.com/en-us/windows/wsl/install>).

install cscs-key from Homebrew

```console
$ brew install eth-cscs/tap/cscs-key
$ cscs-key --version
cscs-key 1.1.0
```

install cscs-key on Apple Silicon Mac

```console
$ TAG=v1.1.0
$ mkdir -p $HOME/.local/bin
$ cd $HOME/.local/bin
$ curl -LO https://github.com/eth-cscs/cscs-key/releases/download/$TAG/cscs-key-$TAG-aarch64-apple-darwin.tar.gz
$ tar -xzvf cscs-key-$TAG-aarch64-apple-darwin.tar.gz
$ rm cscs-key-$TAG-aarch64-apple-darwin.tar.gz
$ cscs-key --version
cscs-key 1.1.0
```

install cscs-key on x86\_64 Linux

```console
$ TAG=v1.1.0
$ mkdir -p $HOME/.local/bin
$ cd $HOME/.local/bin
$ curl -LO https://github.com/eth-cscs/cscs-key/releases/download/$TAG/cscs-key-$TAG-x86_64-unknown-linux-musl.tar.gz
$ tar -xzvf cscs-key-$TAG-x86_64-unknown-linux-musl.tar.gz
$ rm cscs-key-$TAG-x86_64-unknown-linux-musl.tar.gz
$ cscs-key --version
cscs-key 1.1.0
```

install cscs-key on Windows

```pwsh-session
PS> $TAG = "v1.1.0"
PS> mkdir $HOME\bin -Force
PS> cd $HOME\bin
PS> curl.exe -LO "https://github.com/eth-cscs/cscs-key/releases/download/$TAG/cscs-key-$TAG-x86_64-pc-windows-msvc.zip"
PS> Expand-Archive -Path "cscs-key-$TAG-x86_64-pc-windows-msvc.zip" -DestinationPath .
PS> Remove-Item "cscs-key-$TAG-x86_64-pc-windows-msvc.zip"
PS> cscs-key --version
cscs-key 1.1.0
```

The final `cscs-key --version` step prints the version when the install worked. If it instead reports that `cscs-key` cannot be found, the install directory is not on your shell’s `PATH`. Add it once with the snippet below, then open a new terminal and try again.

> [!NOTE]
>
> **Add the install directory to your `PATH`**
>
> add \~/.local/bin to PATH
>
> ```bash
> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
> ```
>
> add \~/.local/bin to PATH
>
> ```bash
> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
> ```
>
> add $HOME\\bin to PATH for the current user
>
> ```powershell
> $userPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
> [Environment]::SetEnvironmentVariable('PATH', "$userPath;$HOME\bin", 'User')
> ```

You can also build it from source by cloning the git repository and following the instructions in the README.

### Setup SSH keys

First, generate the key pair using [`ssh-keygen`](<https://www.ssh.com/academy/ssh/keygen>).

```bash
ssh-keygen -t ed25519 -f ~/.ssh/cscs-key
```

> [!NOTE]
>
> The key only needs to be generated once, and does not need to be run every time your signed key expires.

And add this key to your [SSH config](<#ref-ssh-config>) or add it to your [SSH agent](<#ref-ssh-agent>).

### Usage

To see all available commands run:

```console
$ cscs-key --help
```

To sign an existing public key:

```console
$ cscs-key sign
```

The default private key is `~/.ssh/cscs-key`. You can specify a different private key using the `-f, --file` option. The default duration of the signed key is 1 day. You can specify a different duration using the `-d, --duration` option. Possible values are `1d` or `1min`.

> [!NOTE]
>
> **generate a new key pair (deprecated)**
>
> > **Warning**
> >
> > Generating the SSH key on the server is deprecated and will be removed in the future.
>
> It is possible to generate the SSH key locally and then sign it using the cscs-key sign command.
>
> ```console
> cscs-key gen
> ```
>
> The default private key is `~/.ssh/cscs-key`. You can specify a different private key using the `-f, --file` option. The default duration of the signed key is 1 day. You can specify a different duration using the `-d, --duration` option. Possible values are `1d` or `1min`.

The `cscs-key` command can be used to summarise the status of all of your signed SSH keys:

```console
$ cscs-key list
╭────────────────────┬──────────┬────────────┬────────────────────────────╮
│ Serial Number      │ Valid    │ Expiration │ Expire Time                │
╞════════════════════╪══════════╪════════════╪════════════════════════════╡
│ 202800351141013664 │ ✅ VALID │ in a day   │ 2026-04-01 16:15:20 +02:00 │
├────────────────────┼──────────┼────────────┼────────────────────────────┤
│ 202344484062892129 │ ✅ VALID │ in a day   │ 2026-04-01 16:09:12 +02:00 │
╰────────────────────┴──────────┴────────────┴────────────────────────────╯
```

The `-a, --all` flag will also include expired and revoked keys in the output of `cscs-key list`.

Keys can be revoked using the serial number, which can be found using the `cscs-key list` command above.

```console
$ cscs-key revoke 202800351141013664
202800351141013664: ✅ Key revoked successfully
```

Use `-a, --all` option to revoke all valid keys.

For more details about any command please refer to help with `-h, --help`.

> [!NOTE]
>
> The app supports three authentication methods:
>
> - **OpenID Connect**: Web browser window opens where user authenticates with the CSCS credentials.
> - **OAuth2 Device Authorization Grant** for remote headless machines, enabled by `--headless` flag.
> - **API keys**: For automation with service accounts. See [Service Accounts](<https://docs.cscs.ch/access/service-accounts/index.md#service-accounts>) for details.

### Shell completion

To enable completion on every shell start, add to your shell config (e.g. `~/.bashrc`):

```bash
source <(cscs-key completion <shell>)
```

Supported shells: `bash`, `zsh`, `fish`, `powershell`, `elvish`.

## Managing SSH keys at user-account.cscs.ch

The centralized key management dashboard at [user-account.cscs.ch](<https://user-account.cscs.ch>) allows you to generate, sign, list, and revoke SSH keys in your browser.

> [!NOTE]
>
> **Info**
>
> The dashboard is an alternative to the `cscs-key` command line tool. If you are comfortable using `cscs-key` we recommend sticking to that interface.

### Sign your existing SSH key

The recommended approach is to upload your existing SSH public key to be signed by CSCS. This avoids transferring private keys over the network and follows security best practices.

1. Access [user-account.cscs.ch](<https://user-account.cscs.ch>) and log in with your CSCS credentials
2. Navigate to **SSH Keys** and select **Sign Key**
3. Paste your SSH public key (e.g., the contents of `~/.ssh/cscs-key.pub`)
4. Click **Sign Key** — CSCS will issue a signed certificate
5. Click **Download certificate** — the browser saves it as `cscs-key-cert.pub` in your downloads folder
6. Move the certificate next to the private key:

   move the certificate

   ```bash
   mv ~/Downloads/cscs-key-cert.pub ~/.ssh/cscs-key-cert.pub
   ```
7. Your original private key remains on your machine

> [!WARNING]
>
> **Name the certificate after the private key**
>
> SSH finds the certificate only if its name is the private key file name followed by `-cert.pub`. The certificate is always downloaded as `cscs-key-cert.pub`, whichever key you sign. For example, if you sign `~/.ssh/id_ed25519.pub`, save the certificate as `~/.ssh/id_ed25519-cert.pub`, and use `~/.ssh/id_ed25519` instead of `~/.ssh/cscs-key` in the examples on this page.

> [!NOTE]
>
> **Advantages**
>
> - Private key never leaves your machine
> - Use your existing SSH key infrastructure
> - Works with any SSH key type (RSA, ED25519, ECDSA)
> - Recommended for security

> [!NOTE]
>
> **Generate a new key pair (deprecated)**
>
> If you don’t have an SSH key, CSCS can generate one for you. This method is currently supported but will be phased out in favor of signing existing keys.
>
> Steps:
>
> 1. Access [user-account.cscs.ch](<https://user-account.cscs.ch>) and log in with your CSCS credentials
> 2. Navigate to **SSH Keys** and select **Generate Key**
> 3. Optionally add a passphrase for additional security
> 4. Click **Generate** — CSCS creates and downloads a new key pair
> 5. Save the private key (`cscs-key`) to `~/.ssh/` with restricted permissions:
>
>    ```bash
>    chmod 0600 ~/.ssh/cscs-key
>    ```
>
> **Note:** This method transfers the private key over HTTPS which should be avoided.

### Key validity and limits

> [!NOTE]
>
> - **Validity**: Keys are valid for 1 day by default
> - **Renewal**: Generate or sign a new key when needed for continued access
> - **Limit**: You can create up to 5 keys per day

## Logging in

To ensure secure access, CSCS requires users to connect through the designated jump host Ela (`ela.cscs.ch`) before accessing any cluster.

Before trying to log into your target cluster, you can first check that your SSH key works with Ela:

```text
ssh -i ~/.ssh/cscs-key ela.cscs.ch
```

The `-i` option takes the private key that you signed, not the certificate.

To log into a target system at CSCS, you need to perform some additional setup to handle SSH key forwarding. There are two alternatives detailed below.

### Adding Ela as a jump host in SSH configuration

This approach configures Ela as a jump host and creates aliases for the systems that you want to access in `~/.ssh/config` on your laptop or PC. The benefit of this approach is that once the `~/.ssh/config` file has been configured, no additional steps are required between creating or signing a new key, and logging in.

Below is an example `~/.ssh/config` file that facilitates directly logging into the Daint, Santis and Clariden clusters using `ela.cscs.ch` as a Jump host:

```text
Host ela
    HostName ela.cscs.ch
    User cscsusername
    IdentityFile ~/.ssh/cscs-key

Host daint
    HostName daint.alps.cscs.ch
    User cscsusername
    ProxyJump ela
    IdentityFile ~/.ssh/cscs-key
    IdentitiesOnly yes

Host santis
    HostName santis.alps.cscs.ch
    ProxyJump ela
    User cscsusername
    IdentityFile ~/.ssh/cscs-key
    IdentitiesOnly yes

Host clariden
    HostName clariden.alps.cscs.ch
    ProxyJump ela
    User cscsusername
    IdentityFile ~/.ssh/cscs-key
    IdentitiesOnly yes

Host eiger
    HostName eiger.alps.cscs.ch
    ProxyJump ela
    User cscsusername
    IdentityFile ~/.ssh/cscs-key
    IdentitiesOnly yes
```

> [!NOTE]
>
> ❗ Replace `cscsusername` with your CSCS username in the file above.

After saving this file, one can directly log into `daint.alps.cscs.ch` from your local system using the alias `daint`:

```text
ssh daint
```

### Using SSH agent

Alternatively, the [SSH authentication agent](<https://www.ssh.com/academy/ssh/add-command>) can be configured to manage the keys.

When using signed keys or newly generated keys, add the private key to the SSH agent:

```text
ssh-add -t 1d ~/.ssh/cscs-key
```

`ssh-add` also adds the certificate `~/.ssh/cscs-key-cert.pub`, if it [has the correct name](<https://docs.cscs.ch/access/ssh/index.md#ref-ssh-cert-name> "Sign your existing SSH key").

> [!WARNING]
>
> **Could not open a connection to your authentication agent**
>
> If you see this error message, the SSH agent is not running. You can start it with the following command:
>
> ```text
> eval $(ssh-agent)
> ```

Once the key has been configured, log into Ela using the `-A` flag, and then jump to the target system:

```bash
# log in to ela.cscs.ch
ssh -A cscsusername@ela.cscs.ch

# then jump to a cluster
ssh daint.cscs.ch
```

## SSH tunnel to a service on Alps compute nodes via Ela

If you have a server listening on a compute node in an Alps cluster and want to reach it from your local computer, you can do the following: allocate a node, start your server bound to `localhost`, open an SSH tunnel that jumps through `ela` to the cluster, then use `http://localhost:PORT` locally. Details on how to achieve this are below.

Before starting, make sure you:

- [Have SSH keys loaded in your agent](<https://docs.cscs.ch/access/ssh/index.md#using-ssh-agent> "Using SSH agent").
- Have your CSCS username handy (replace `MYUSER` below).
- Have your server running on a compute node on Alps. See the [Slurm documentation](<https://docs.cscs.ch/running/slurm/index.md#slurm>) for help on how to allocate a node and start your server on a compute node.
- Know the compute node ID (e.g., `nid006554`) and the port of your running server.

> [!WARNING]
>
> **Fast fixes when starting a server or before tunneling**
>
> - Port already in use locally: pick another PORT (e.g., 6007) in both your server and the tunnel command below.
> - Auth prompts loop: verify your SSH MFA to CSCS and that your SSH agent is correctly set up and loaded with your keys.

> [!TIP]
>
> **Binding to `127.0.0.1` ensures the service is only reachable via your tunnel**

To open the tunnel from your local computer:

```bash
MYUSER=cscsusername     # your username at CSCS
NODE=nid006554          # obtained from salloc or srun
PORT=6006               # example port
CLUSTER=daint           # cluster you want to reach

ssh -N -J ${MYUSER}@ela.cscs.ch,${MYUSER}@${CLUSTER}.alps.cscs.ch -L ${PORT}:localhost:${PORT} ${MYUSER}@${NODE}
```

The command blocks while the tunnel is open (that is expected).

> [!NOTE]
>
> **The first run may ask to trust the node’s host key—type `yes`**

With the service running and the tunnel open, you can now reach your service locally:

- Browser: `http://localhost:PORT`
- Terminal: `curl localhost:PORT`

> [!WARNING]
>
> **Fast fix if the service doesn’t respond locally**
>
> - Service not responding: ensure the server binds to 127.0.0.1 and is running on the compute node; confirm NODE matches your current Slurm allocation.

To clean up afterwards:

- Stop the server (Ctrl-C on the compute node shell).
- End the Slurm allocation:

  ```bash
  scancel $SLURM_JOB_ID
  ```
- Close the tunnel (Ctrl-C in the tunnel terminal).

## Revoking SSH keys

You can revoke SSH keys when they are no longer needed or if compromised.

### Revoke via web dashboard

1. Access [user-account.cscs.ch](<https://user-account.cscs.ch>) and log in
2. Navigate to **SSH Keys** to view your active keys
3. Click the **Revoke** button next to the key you want to revoke
4. Confirm the revocation

### Revoke via CLI

To revoke a key using the command-line interface:

```bash
# Revoke a single key by serial number
cscs-key revoke --serial <serial-number>

# Revoke all active keys
cscs-key revoke-all
```

The revocation takes effect immediately across all CSCS systems.

## Known issues

> [!WARNING]
>
> **too many authentication failures**
>
> You may have too many keys in your SSH agent. Remove the unused keys from the agent or flush them all with the following command:
>
> ```bash
> ssh-add -D
> ```

> [!WARNING]
>
> **Permission denied**
>
> This might indicate that your key has expired or is not valid. Check the validity of your key at [user-account.cscs.ch](<https://user-account.cscs.ch>). If expired, sign or generate a new key.
>
> This error also occurs if the certificate name does not match the private key. In this case, `ssh -v` prints `no such identity` for the private key. Save the certificate as `<private key>-cert.pub`, as described in [Sign your existing SSH key](<https://docs.cscs.ch/access/ssh/index.md#ref-ssh-cert-name>).

> [!WARNING]
>
> **Could not open a connection to your authentication agent**
>
> If you see this error when adding keys to the ssh-agent, please make sure the agent is up, and if not bring up the agent using the following command:
>
> ```bash
> eval $(ssh-agent)
> ```

## Legacy: old SSH key management

> [!WARNING]
>
> **Retired from Q2 2026**
>
> The old SSHService ([sshservice.cscs.ch](<https://sshservice.cscs.ch>)) and the associated command-line script have been retired starting Q2 2026. All users must use the [new key management dashboard](<#ref-ssh-key-management>) or [CLI](<#ref-ssh-cli>).
