<p style="text-align: center"><b><font size=5 color=blueyellow>Login to Leonardo Booster Cluster</font></b></p>

**Contribution**: <a><img src="https://img.shields.io/badge/ENCCS-blue?style=plastic"/></a>

**Categories**: <a><img src="https://img.shields.io/badge/Blogpost-996300?style=plastic"/></a> <a><img src="https://img.shields.io/badge/CINECA-green?style=plastic"/></a> <a><img src="https://img.shields.io/badge/Leonardo Booster-3232ff?style=plastic"/></a> <a><img src="https://img.shields.io/badge/UserDB portal-aqua?style=plastic"/></a> <a><img src="https://img.shields.io/badge/2FA/OPT-red?style=plastic"/></a> <a><img src="https://img.shields.io/badge/smallstep-gold?style=plastic"/></a>

**Contents of this document and quicklinks**：
[TOC]

---

## 1. Registration at the CINECA UserDB portal

In order to have access on Leonardo, it is necessary to complete the registration procedure on [CINECA UserDB portal](https://userdb.hpc.cineca.it)
- Click on the "Create a New User" button and filling in the required fields
- Uploading an ID card (**passport for non-Italian**) in the Documents for HPC tab, complete the information about your Institution and check your Personal Data.
- Your CINECA ID looks like **YOUR.NAME_xxxxx [uid: xxxxx]**, in which **xxxxx** is a 5-digit string consising of numbers.

## 2. Association your account with an active project

Send your ID account at CINECA to the project leader and ask for the access to an existing project.

## 3. Request to access to an CINECA HPC cluster

- Once your username has been associated with an active account, you can request access to an CINECA HPC clusters.
- Make sure following info are **OK**, see the figure below.
- Personal data
- Institution
- HPC DOCs
- Authorization
- Clicking the button **Submit** on your HPC Access page.
- **Wait for several hours .....**
- Once approved your request, you will receive two emails
- one email with the **username**
- another with the link to a page showing how to
- configure the **two-factor authentication (2FA)**
- configure the **OTP**
- an exmaple of this email is shown below
> **OBS**: The link for the configuration of 2FA has a duration of only 24 hours. After its expiration you need to write to [e-mail] to get a new valid link.

---

## 4. Configuration of 2FA and OTP

Two-factor authentication (2FA) refers to an authentication method in which a user is granted access to the CINECA HPC systems only after successfully presenting two pieces of evidence (or factors).

Verifying your identity, using an independent second factor, prevents other users from logging in with your identity, even if they have the password.

Therefore, the two-factor authentication (2FA) adds a further level of security to the authentication for access to services based on the Identity Provider.

The detailed procedures for the configuration of **2FA** and **OTP** are available [HERE](https://wiki.u-gov.it/confluence/display/SCAIUS/How+to+activate+the+2FA+and+configure+the+OTP).

The last step, once you have successfully inserted the 6-digit code from **FreeOPT/Goolge Authentiator**, you will get the **Recovery codes** (shown below). Please save these codes somewhere by downloading, printing or copying in a text file.


---

## 5. Install and configuration of the **smallstep** client

Once the 2FA will be enabled as the only method to authenticate on CINECA clusters, you will need to install and configure on your PC a program that allows you to authenticate via 2FA and to download locally the temporary certificate. The CINECA recommends the **smallstep** client.

Detailed descriptions are available [HERE](https://wiki.u-gov.it/confluence/display/SCAIUS/How+to+install+the+smallstep+client).
- [Setup client step-cli: Linux and Mac users](https://wiki.u-gov.it/confluence/display/SCAIUS/Setup+client+step-cli%3A+Linux+and+Mac+users)
- [Setup client step-cli: Windows users](https://wiki.u-gov.it/confluence/display/SCAIUS/Setup+client+step-cli%3A+Windows+users)
- **IMPORTANT**: users with Ubuntu operating systems (but may happen also for other Linux distributions) should not run the command "sudo apt install step" because this will install a different software that will give errors when following the below instructions.

Below are commands for Linux and Mac users.
- Run the command below in your local shell:

    $ step ca bootstrap --ca-url=https://sshproxy.hpc.cineca.it --fingerprint 2ae1543202304d3f434bdc1a2c92eff2cd2b02110206ef06317e70c1c1735ecd 

- you can get similar output as follows:

    The root certificate has been saved in <path-to>/.step/certs/root_ca.crt.

    The authority configuration has been saved in <path-to>/.step/config/defaults.json.

- Run the command below to activate the ssh-agent

    $ eval $(ssh-agent)

- Run the command below to obtain the certificate

    $ step ssh login 'USER@EMAIL' --provisioner cineca-hpc

- This command will report an output on the shell as follows:
- This also leads to a webpage on your default web browser.
- You should input your cluster credentials (username and password) and then click the button **Sign in**
- The keycloak page will ask for the OTP code generated by the FreeOTP/Google Authenticator
- Once authenticated, you will see a **Success** message on your browser.
- <font color=red>**IMPORTANT**</font>: The the temporary certificate is valid for 12 hours. If you reboot your computer, the certificate is lost and you need to download a new one launching again the **step ssh login ...** command.
- Run the command at the terminal

    $ ssh [e-mail]

- if everything work well, you can come to the leonardo cluster.

---

## 6. Managing password, 2FA and OTP

More details about change the password, recover one-time password generator, as well as renew the recovery codes are available [HERE](https://wiki.u-gov.it/confluence/display/SCAIUS/Managing+password%2C+2FA+and+OTP).

---

## 7. Solution to error message **WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!**

During the 12-hour window, the temporary certificate generated at **Step 5** works if you do not reboot your computer.
- If you reboot your computer, you need to download a new one launching again the **step ssh login ...** command
- If you log out the cluster, and want to login again to the LB cluster, you might got an error message like `WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!`
- If this happens, you can find the `known_hosts` file at the ~/.ssh directory.
- In this file, you will see three lines containing `cineca` related information.
- <font color=red>**Delete these three lines**</font> and save the file before you exit.
- Run the command `ssh [e-mail]`, you can relogin to the LB cluster.

---

## 8. Login nodes on LB cluster

Leonardo have 4 login node as shown below, you can use `login.leonardo.cineca.it` for login and you will "randomly" choose one of login node.

| Column 1 | hostname |
| :------: | :------: |
| login | login.leonardo.cineca.it |
| login1 | login01-ext.leonardo.cineca.it |
| login2 | login02-ext.leonardo.cineca.it |
| login5 | login05-ext.leonardo.cineca.it |
| login7 | login07-ext.leonardo.cineca.it |

If you want to login to LB cluster from a specific login node each time, you can setup a configure file at` ~/.ssh/config` (for mac computer)

Host Leonardo7
  HostName login07-ext.leonardo.cineca.it
  StrictHostKeyChecking no
  UserKnownHostsFile /dev/null
  User your_user_name_on_Leonardo
  ControlMaster auto
  ControlPath ~/.ssh/cm-%r@%h:%p
  ControlPersist 2h

- remember to change **your_user_name_on_Leonardo** above
- `UserKnownHostsFile /dev/null` will avoid the error
- after this setup, you can just type `ssh Leonardo7` at the terminal for your login to the LB cluster.

:::danger
:::