WIP: Roihu migration guide

csc-overrides/assets/snippets/graphical-connection.md

@@ -0,0 +1,4 @@
+!!! info "Note"
+    For performance reasons, we generally recommend using the
+    [HPC web interfaces](/computing/webinterface/index.md) to run applications which
+    require displaying graphics.

csc-overrides/assets/snippets/ssh-agent-forwarding.md

@@ -0,0 +1,4 @@
+!!! warning "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.

csc-overrides/assets/snippets/ssh-ca.md

@@ -0,0 +1,8 @@
+!!! warning "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](/computing/connecting/ssh-keys.md#signing-public-key).

csc-overrides/assets/snippets/using-ssh-keys.md

@@ -0,0 +1,8 @@
+!!! info "Using SSH keys"
+    See the page on [setting up SSH keys](/computing/connecting/ssh-keys.md)
+    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**.

docs/computing/connecting/index.md

@@ -1,6 +1,6 @@
 # Connecting to CSC supercomputers
 
---8<-- "auth-update-ssh.md"
+--8<-- "ssh-ca.md"
 
 There are two main ways of connecting to CSC supercomputers.
 
@@ -22,8 +22,7 @@ For instructions on connecting to the LUMI supercomputer, please see the
 ## Using the web interface
 
 The [web interface](../webinterface/index.md) is a good platform
-for using graphical applications on the Puhti and Mahti supercomputers.
-It hosts
+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.
@@ -34,15 +33,36 @@ 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 Puhti and Mahti web interfaces](../webinterface/connecting.md).
+[connecting to HPC web interfaces](../webinterface/connecting.md).
 
 ## Using an SSH client
 
-Logging in to Puhti and Mahti using an SSH client requires that you have
-[set up SSH keys](ssh-keys.md) and
-[added your public key to MyCSC](ssh-keys.md#adding-public-key-in-mycsc).
-Traditional password-based authentication and public keys stored in your
-personal `~/.ssh/authorized_keys` file will **not** work.
+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. [signed your public key](ssh-keys.md#signing-public-key) to obtain a
+   time-based SSH certificate.
+    * Step 3. is only required when connecting to Roihu and must be
+      repeated every 24 hours.
+
+```mermaid
+flowchart LR
+    A(**Before first connection:**
+      <a href='ssh-keys/'>Set up SSH keys</a>)
+    A --> B{Connecting
+            to Roihu?}
+    B -->|yes| C(**Once every 24 hours:**
+                 <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
@@ -54,12 +74,13 @@ over SSH, there are 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 and added your public key to MyCSC, use a
-command like below to connect over SSH:
+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" or "mahti"
+# <host> with "puhti", "mahti", "roihu-cpu" or "roihu-gpu"
 
 ssh <username>@<host>.csc.fi
 ```
@@ -106,6 +127,22 @@ should again verify the new key against fingerprints provided by CSC.
     | WC9Lb5tmKDzUJqsQjaZLvp9T7LTs3aMUYSIy2OCdtgg | ssh_host_ecdsa_key.pub (ECDSA)     |
     | tE+1jA4Et1enbbat1V3dMRWlLtJgA8t7ZrkyIkU4ooo | ssh_host_ed25519_key.pub (ED25519) |
     | 0CxM3ECpD2LhAnMfHnm3YaXresvHrhW4cevvcPb+HNw | ssh_host_rsa_key.pub (RSA)         |
+=== "Roihu (pilot phase)"
+    | SHA256 checksum                             | Key                                |
+    |---------------------------------------------|------------------------------------|
+    | NnNuy5xLxXDhDyBTVCtRbGNSMmTTKdnH6dlomerCg14 | ssh_host_ecdsa_key.pub (ECDSA)     |
+    | mAkMF6xpb4wc1eq+vPc4q4mo7YvcL4GHxe8XauPqGas | ssh_host_ed25519_key.pub (ED25519) |
+    | IHUo4GZOYH8V9qlcv155iP3w/83SdlS6E2jOb/z01hE | ssh_host_rsa_key.pub (RSA)         |
+=== "Roihu (general availability)"
+    | 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)         |
+
+!!! info "Note"
+    For security reasons, Roihu host keys will be changed after the pilot
+    phase.
 
 ### Graphical connection
 
@@ -125,17 +162,17 @@ 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. 'puhti-login11.csc.fi'
+ssh <username>@<host>-login<id>.csc.fi  # e.g. 'roihu-gpu-login1.csc.fi'
 ```
 
 The available login nodes are:
 
-| Puhti | Mahti |
-|-|-|
-| `puhti-login11` | `mahti-login11` |
-| `puhti-login12` | `mahti-login12` |
-| `puhti-login14` | `mahti-login14` |
-| `puhti-login15` | `mahti-login15` |
+| 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
@@ -164,19 +201,15 @@ supercomputers in an [SSH config file](https://www.ssh.com/academy/ssh/config)
 (e.g. `~/.ssh/config`).
 
 ```bash
-Host <host>  # e.g. "puhti"
+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:
 
 ```bash
 ssh <host>
 ```
-
-#### Remote development
-
-Some editors like Visual Studio Code and Notepad++ can be used to
-[work on files remotely](../../support/tutorials/remote-dev.md)
-using an appropriate plugin. **However, this is not recommended.**

docs/computing/connecting/ssh-keys.md

@@ -1,10 +1,11 @@
 # Setting up SSH keys
 
---8<-- "auth-update-ssh.md"
+--8<-- "ssh-ca.md"
 
 [SSH keys](https://www.ssh.com/academy/ssh-keys) provide more convenient and
-secure authentication. Setting them up is a two-step process, and is required
-to be able to connect to CSC supercomputers using an SSH client.
+secure authentication. SSH keys are required to be able to connect to CSC
+supercomputers using an SSH client. Connecting to Roihu requires also that you
+sign your public key in order to obtain a time-based SSH certificate.
 
 1. [Generate SSH keys on your local workstation](#generating-ssh-keys).
     - SSH keys are always generated in pairs consisting of one _public key_ and
@@ -16,6 +17,12 @@ to be able to connect to CSC supercomputers using an SSH client.
       the _public key_ to MyCSC. **Do not copy the private key.** Note that
       copying the public key directly to CSC supercomputers using tools such as
       `ssh-copy-id` will not work.
+3. [Sign the public key in MyCSC and download SSH certificate](#signing-public-key) (**required for Roihu only**).
+    - To connect to Roihu, sign your public key in MyCSC to generate a
+      time-based SSH certificate that is used for authentication. SSH
+      certificates have a finite lifetime of 24 hours, which significantly
+      improves the security of the system. After the SSH certificate expires, a
+      new one must be generated by signing the public key in MyCSC again.
 
 For more information about SSH keys, see:
 
@@ -103,7 +110,143 @@ cat /var/lib/acco/sshkeys/${USER}/${USER}.pub
 If you have added multiple keys to MyCSC, they should all be visible in the
 same `${USER}.pub` file.
 
+## Signing public key
+
+!!! info "The following is a requirement for connecting to Roihu only"
+
+To connect to Roihu using SSH, you must sign your public key to get a so called
+**SSH certificate**. SSH certificates significantly improve the security of the
+system by introducing an additional authentication factor for SSH logins.
+
+**SSH certficates are valid for 24 hours at a time**. Once your certificate
+expires, a new one must be signed following either of the processes below.
+
+### Option 1: Certificate helper tool
+
+The certificate helper is a Python tool developed by CSC to simplify the
+process of signing and downloading SSH certificates. A detailed documentation
+of the tool is available in the [source repository](https://github.com/CSCfi/).
+The following instructions illustrate only basic usage.
+
+1. Ensure that you have Python installed on your computer.
+    - Instructions are available in the
+      [Python Beginners Guide](https://wiki.python.org/moin/BeginnersGuide/Download).
+      Contact your local IT-support if you need assistance.
+    - If Python for some reason cannot be installed on your computer, fall
+      back to [Option 2](#option-2-mycsc) instead.
+2. [Download the certificate helper tool here](https://github.com/CSCfi/).
+3. Run the tool:
+
+    === "Linux & macOS"
+
+        1. Open terminal and execute:
+
+            ```bash
+            # Replace <username> with your CSC user name and
+            # <path-to-public-key> with the path to your SSH public key
+
+            python3 csc-cert.py -u <username> <path-to-public-key>
+            ```
+
+        2. If you have an earlier certificate which is still valid, the tool
+            exits.
+        3. If signing is needed, a login URL is displayed. Follow the link and
+            authenticate.
+        4. Copy the 6-digit code displayed into your terminal and enter your
+           SSH key passphrase.
+            - The signed certificate is automatically downloaded and added to
+              your SSH agent. The signed certificate is saved as
+              `<key>-cert.pub` (e.g., `~/.ssh/id_ed25519-cert.pub`).
+        5. Each SSH certificate is valid for 24 hours. The expiration time can
+           be checked by running the tool again.
+
+    === "Windows"
+
+        1. Optional, but helpful:
+            [Install WinSCP](https://winscp.net/eng/docs/installation) and
+            [start the Pageant authentication agent](https://the.earth.li/~sgtatham/putty/0.83/htmldoc/Chapter9.html#pageant)
+            that comes bundled with PuTTY to automatically add SSH key and
+            certificate to SSH agent.
+        2. Open PowerShell and execute:
+
+            ```bash
+            # Replace <username> with your CSC user name and
+            # <path-to-public-key> with the path to your SSH public key
+
+            python3 csc-cert.py -u <username> <path-to-public-key>
+            ```
+
+            !!! info "Note"
+                PowerShell is just needed to run the certificate
+                helper script. You can still connect to Roihu using your
+                [favorite SSH client](ssh-windows.md#basic-usage).
+
+        3.  If you have an earlier certificate which is still valid, the tool
+            exits.
+        4.  If signing is needed, a login URL is displayed. Follow the link and
+            authenticate.
+        5. Copy the displayed 6-digit code into PowerShell and enter your SSH
+           key passphrase.
+            - The signed certificate is automatically downloaded and added to
+              your SSH agent (if you have WinSCP installed and Pageant
+              running). The signed certificate is saved as `<key>-cert.pub`
+              (e.g., `C:\Users\<username>\.ssh\id_ed25519-cert.pub`).
+        6. Each SSH certificate is valid for 24 hours. The expiration time can
+           be checked by running the tool again.
+
+---
+
+### Option 2: MyCSC
+
+1. Log in to MyCSC with your CSC or Haka/Virtu credentials.
+2. Select _Profile_ from the left-hand navigation or the dropdown menu in the
+   top-right corner.
+3. Locate _SSH PUBLIC KEYS_ section and click the three vertical dots next to
+   the public key you want to sign.
+4. Click _Sign SSH key_. As a security measure, you are asked to log in again.
+
+    ![Sign SSH key](https://a3s.fi/docs-files/sign-ssh-key.png 'Sign SSH key')
+
+5. Download the certificate by clicking the three vertical dots next to your
+   public key and selecting _Download SSH certificate_.
+
+    !!! info "Where to store the SSH certificate?"
+        We **strongly** advice saving the certificate in the default folder for
+        SSH-related files (e.g. `~/.ssh`). Specifically, storing the
+        certificate in the same directory as your SSH private key **and**
+        naming it as `<key>-cert.pub` will simplify connecting, working with
+        SSH agent, etc.
+
+        For example, if you've stored your SSH private key in
+        `~/.ssh/id_ed25519`, please save your SSH certificate as
+        `~/.ssh/id_ed25519-cert.pub`
+
+    ![Download SSH certificate](https://a3s.fi/docs-files/download-ssh-cert.png 'Download SSH certificate')
+
+6. Each SSH certificate is valid for 24 hours. The expiration time can be
+   checked as follows:
+
+    === "Terminal (Linux, macOS, PowerShell, MobaXterm)"
+
+        1. Open a terminal client.
+        2. Run command:
+
+            ```bash
+            ssh-keygen -L -f <path-to-certificate> | grep "Valid"
+            ```
+
+    === "GUI (PuTTY, MobaXterm)"
+
+        3. Open PuTTYgen / MobaKeyGen.
+        4. Load your private key: _File_ :material-arrow-right: _Load private key_.
+        5. Add a certificate to the key: _Key_ :material-arrow-right: _Add certificate to key_.
+        6. Select _Certificate info_ to see the validity period among other info.
+
+    ---
+
 ## More information
 
 - [Tutorial on setting up SSH keys at CSC](https://csc-training.github.io/csc-env-eff/hands-on/connecting/ssh-keys.html)
 - [Troubleshooting issues with SSH keys](../../support/faq/ssh-keys-not-working.md)
+- [Connecting to CSC supercomputers with SSH on Linux and macOS](ssh-unix.md)
+- [Connecting to CSC supercomputers with SSH on Windows](ssh-windows.md)