Access to the Systems

Accessing any section of the Cineca HPC systems requires activating two-factor authentication (2FA) for each user account. This enhanced security measure verifies a user’s identity by requiring a second, independent factor in addition to the account password. Even if the correct account password is used, 2FA ensures that unauthorized access is prevented, significantly improving the system’s overall security.

This access modality operates seamlessly for users, who continue to utilize standard protocols such as the SSH client. Before connecting to the cluster, users must request an SSH certificate from our Identity Provider (IP) via the smallstep client. Upon making the request, a web page will automatically open in the browser, prompting users to authenticate with our IP by entering a one-time password (OTP). Following successful authentication, the server will issue a time-limited certificate valid for 12 hours. This certificate allows users to connect to CINECA systems via SSH client.

Important

For the First-time Access and the activation of 2FA, a user must complete the following steps:

Registration on UserDB.
Correct configuration of 2FA and OTP (How to activate the 2FA and the OTP generator).

Important

If you are a Cloud user only, smallstep installation is not required.
For HPC Resources you must use smallstep client to allow ssh protocol (How to configure smallstep client).

How to activate the 2FA and the OTP generator

Follow the instructions below to activate the 2FA authenticator method and configure the OTP generator.

2FA activation and OTP configuration, step-by-step guide

Step 1 - Activate the 2FA

point the website https://sso.hpc.cineca.it

Sign in using your CINECA cluster username and password (received by email).

At first login, you’ll be prompted to verify your email, change your password, and configure your OTP (One-Time Password).

Important

New users will automatically receive the link. Once it is set up, you’ll use the OTP alongside your password for logging into the cluster.

If it’s your first time logging in and you haven’t received a valid access link, contact superc@cineca.it.

if you already have access to the cluster via username and password but you haven’t yet done your first login on the new sso portal and you haven’t configured the 2FA, you need to write at superc@cineca.it to receive a valid link for the access.

Step 2

After your first login, you will receive an email from CINECA with the subject “CINECA HPC Single Sign-On: Verify Your Email.” This email will be sent to the address you registered with on the UserDB portal.

The email contains a verification link labeled Click on the link to proceed. Once you click it, you will be prompted to define a new password. Please ensure that your chosen password complies with the Policy for HPC password definition.

Step 3
After the definition of a new valid password (that will replace the password used to login to CINECA clusters), you will be asked to configure the 2FA following few simple steps.

Step 4 - OTP Applications

Authentication codes can be generated using either FreeOTP or Google Authenticator, or other compatible apps. If you don’t already have one of these apps, download it onto your smartphone.

Once the app is installed, use it to scan the QR code displayed on the setup page. The OTP will be automatically configured on your authenticator.

As a final step, enter the 6-digit code that appears in the app to verify the correct configuration. If you have multiple OTPs in the app, the correct one will be labeled “CINECA HPC: <your username>”.

After verifying the correct configuration, the following page will display your Recovery codes. Save these codes by downloading, printing, or copying them into a text file.

Warning

Recovery codes are requested to the user in case of problems with your management of the OTP codes (for example, issues with the app or smartphone lost), so saving them somewhere is very important.

Step 5

At this point, your 2FA is active and your OTP configuration is done. In case you are a user of HPC resources (not Cloud), you can follow the guide below to setup the smallstep client for the authentication certificate and to connect to the HPC clusters via ssh protocol.

Important

If you need to regenerate the OTP, please refer to the procedure outlined in the Manage your HPC credentials.

Users that want to get access only to Cloud resources can skip the next steps.

How to configure smallstep client

Once 2FA is enabled as authentication method for CINECA clusters, you will need to install and configure a 2FA-compatible program on your PC, to download the temporary certificate locally. At CINECA, we recommend using the Smallstep client.

Note

smallstep client is not required to access to cloud resources.

To obtain and install the Smallstep executable, visit the Smallstep website and follow the installation instructions for your operating system. Alternatively, you can download the executable directly from the GitHub repository.

After installation, you must configure Smallstep according to your operating system’s requirements. If you encounter any issues or need further assistance, please contact superc@cineca.it.

Windows users have multiple options:

Clients SSH/SFTP under Windows

There are many SSH or SFTP Clients available for Windows, that are of common usage but are not automatically configured for working with the new 2FA system. It is possible to login with them by exploiting the OpenSSH agent forwarding that can be set by taking advantage of another tool installable on Powershell, that is WinSSH-Pageant.

Step 1 - as a prerequisite, complete the configuration for Powershell as explained in the dedicated paragraph above.
Step 2 Download WinSSH-Pegeant
winget install winssh-pageant
after downloading, you should find a new executable in the following path:

C:\Users\$Env:UserName\AppData\Local\Programs\WinSSH-Pageant\winssh-pageant.exe

The variable $Env:UserName will be specific for your personal workstation.
- Create an alias to simplify the execution of winssh-pageant.exe
New-Alias winssh-pageant C:\Users\$Env:UserName\AppData\Local\Programs\WinSSH-Pageant\winssh-pageant.exe
Important

Keep in mind though that Powershell keeps an alias alive only until the shell is closed. An easy permanent solution would be to copy the program winssh-pageant.exe to another folder, for example C:\Users\$Env:UserName\scoop\shims that has been already included permanently in the PATH variable by the previous installation of step and is therefore recognized by Powershell without the need of expliciting the full path.
Step 3
- Launch the WinSSH-pageant with the command: winssh-pageant --sshpipe
- Check if winssh-pageant is active and works properly
  Get-Process | Select-String pageant
  
  You should expect an output like:
  
  System.Diagnostic.Process (winssh-pageant)

Step 4 - Create a new certificate

step ssh login <your-email> --provisioner cineca-hpc

At this point you can connect via SSH/SFTP client by using your preferred client. In the following, we report the proper settings for the most popular clients (Putty, WinSCP, Filezilla, MobaXterm).

Putty:

In the login window, check the category “Connection –> SSH –> Auth” and be sure that the boxes “Attempt authentication using Pageant” and “Allow agent forwarding” are ticked.

WinSCP:

In the login window, from the Advanced settings go to “SSH–> Authentication” and tick the boxes “Attempt authentication using Pageant” and “Allow agent forwarding”. Be sure that the file protocol is set to “SCP”.

Note: It is possible that if you try to edit an already saved site, the ssh-agent won’t be recognized. If this is the case, we recommend to create a new site from scratch and configure it accordingly. The new site can then be saved and will keep working.

Note: In certain cases, we noted that the procedure may not work at first try, and you will get an error at login even if everything is in order. In most cases, a simple reboot of your workstation solves the problem and the issue will not occur again.

FileZilla:

In your site configuration, be sure that the Protocol is set to “SFTP - SSH File Transfer Protocol” and the Logon type is set to “Normal”.

MobaXTerm:

In the upper menu bar with the general options, make sure that in “Settings” → “Configuration” → “SSH” the box “Use external Pageant” is ticked (it should be by default).

After that, opening a simple ssh session should be enough.

Other SSH/SFTP clients don’t seem to be working with this method and are currently not supported by CINECA (for example BitviseSSH), or haven’t been tested yet. We will keep updating the Userguide when other clients will be proven compatible.

How to manage authentication certificates

Managing authentication certificates in HPC environments involves ensuring secure access to resources. Users typically generate certificates via an Identity Provider or a local client, like Smallstep, for secure session authentication.

Key operations include:

Certificate generation: Performed during initial setup or when required by the system.

Re-generating certificates: Necessary if the current certificate expires or becomes invalid. Users typically log in to the portal or use a client tool to request a new certificate.

Certificate renewal: Ensures continued access without disruptions, often automated if supported by the system.

For issues or detailed procedures, users should consult the documentation or contact: superc@cineca.it.

Access via Secure Shell (SSH)

SSH is commonly employed for remote access to a machine, allowing users to execute commands (remote console), run programs, and transfer files securely. On Linux and Mac systems, the SSH client is typically pre-installed. However, on Windows systems, users need to download and install an SSH client. Some popular SSH clients for Windows include Powershell, openSSH, Putty or Tectia. Connection adopting 2FA procedure does not require to provide password.

The access is done via one of the following commands:

$ ssh <username>@login.marconi.cineca.it
$ ssh <username>@login.g100.cineca.it
$ ssh <username>@login.leonardo.cineca.it
$ ssh <username>@login.pitagora.cineca.it

You can use the option -X to enable X11 display forwarding.

Important

After 12 hours, a new certificate must be generated using the smallstep client (How to manage authentication certificates).
You will login to our systems with one of the two shells: bash or tcsh. Contact the HPC support (superc@cineca.it) if you want to change your default login shell.
Login is prevented on systems in which you don’t have a budget account.
We have identified a potential issue for local PC with openssh 8.6 (check with the command ssh -V). The solution can be found here in our FAQ page.

Troubleshooting - WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!

The DNS listed above to access our clusters are aliases pointing at different login nodes. When accessing multiple times on the same cluster, if you end-up on a different login node than the previous session you may get the following error: “WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!” the reason is a possible mismatch between the DNS and the node’s fingerprint saved in your known_hosts file.

To solve this issue, we sugget the following steps.

Linux/MacOS and Windows WSL

Open your terminal, get the 2FA certificate, and run the following command:

ssh-keygen -f ~/.ssh/known_hosts -R <cluster_dns>; for keyal in ssh-rsa ecdsa-sha2-nistp256; do for address in <clustes_explicit_dns>; do ssh-keyscan -t ${keyal} ${address} | sed "s/\b${address}/<cluster_generic_dns>/g" >> ~/.ssh/known_hosts; done; done

where <cluster_dns> is the domain name system of the cluster, and <cluster_generic_dns> is a wildcard pattern derived from the cluster DNS used to generalize host entries in the known_hosts file.

An example for Leonardo cluster:

ssh-keygen -f ~/.ssh/known_hosts -R login.leonardo.cineca.it; for keyal in ssh-rsa ecdsa-sha2-nistp256; do for address in (login01-ext.leonardo.cineca.it login02-ext.leonardo.cineca.it login05-ext.leonardo.cineca.it login07-ext.leonardo.cineca.it); do ssh-keyscan -t  ${keyal} ${address} | sed "s/\b${address}/login*.leonardo.cineca.it/g" >> ~/.ssh/known_hosts; done; done

Note

You can find the previously configured one-line command for each cluster in our FAQ.

To generalize you can use the following:

# Define the main cluster DNS name
cluster_dns=login.leonardo.cineca.it

# Define an array of explicit DNS names for each login node
clustes_explicit_dns=(
   login01-ext.leonardo.cineca.it
   login02-ext.leonardo.cineca.it
   login05-ext.leonardo.cineca.it
   login07-ext.leonardo.cineca.it
)

# Generate a generic DNS pattern by replacing the first '.' with '*.'
# (e.g., "login.leonardo.cineca.it" → "login*.leonardo.cineca.it")
cluster_generic_dns="${cluster_dns/./*.}"

# Remove any existing SSH key entries for the main cluster DNS from known_hosts
if [ -f ~/.ssh/known_hosts ]
then
   ssh-keygen -f ~/.ssh/known_hosts -R ${cluster_dns}
fi

# Loop over the key algorithms to scan (e.g., ssh-rsa, ecdsa-sha2-nistp256)
for keyal in ssh-rsa ecdsa-sha2-nistp256
do
   # Loop over all explicit login node DNS entries
   for address in ${clustes_explicit_dns[@]}
   do
      # Retrieve the SSH public key for the node using ssh-keyscan
      # Replace the explicit node address with the generic pattern in the output
      # Append the result to the known_hosts file
      ssh-keyscan -t ${keyal} ${address} | sed "s/\b${address}/${cluster_generic_dns}/g" >> ~/.ssh/known_hosts
   done
done

Windows Powershell and other SSH clients

Open your Powershell terminal, get the 2FA certificate, and run the following command:

ssh-keygen -f "$HOME\.ssh\known_hosts" -R "<cluster_dns>"; foreach ($keyal in "ssh-rsa", "ecdsa-sha2-nistp256") { foreach ($address in <clusters_explicit_dns>) { ssh-keyscan -t $keyal $address | ForEach-Object { $_ -replace "\b$address\b", "<cluster_generic_dns>" } >> "$HOME\.ssh\known_hosts" } }

where <cluster_dns> is the domain name system of the cluster, and <clustes_explicit_dns> is the list of the explicit DNS of the login nodes.

An example for Leonardo cluster:

ssh-keygen -f "$HOME\.ssh\known_hosts" -R "login.leonardo.cineca.it"; foreach ($keyal in "ssh-rsa", "ecdsa-sha2-nistp256") { foreach ($address in "login01-ext.leonardo.cineca.it", "login02-ext.leonardo.cineca.it", "login05-ext.leonardo.cineca.it", "login07-ext.leonardo.cineca.it") { ssh-keyscan -t $keyal $address | ForEach-Object { $_ -replace "$address", "login*.leonardo.cineca.it" } >> "$HOME\.ssh\known_hosts" } }

Note

You can find the previously configured one-line command for each cluster in our FAQ.

To generalize you can use the following:

# Define the main cluster DNS name
$cluster_dns = "login.leonardo.cineca.it"

# Define an array of explicit DNS names for each login node
$clusters_explicit_dns = @(
   "login01-ext.leonardo.cineca.it",
   "login02-ext.leonardo.cineca.it",
   "login05-ext.leonardo.cineca.it",
   "login07-ext.leonardo.cineca.it"
)

# Generate a generic DNS pattern by replacing the first '.' with '*.'
# (e.g., "login.leonardo.cineca.it" → "login*.leonardo.cineca.it")
$cluster_generic_dns = $cluster_dns -replace '\.', '*.', 1

# Path to known_hosts
$known_hosts_path = "$HOME\.ssh\known_hosts"

# Remove any existing SSH key entries for the main cluster DNS from known_hosts
if (Test-Path $known_hosts_path) {
   ssh-keygen -f $known_hosts_path -R $cluster_dns | Out-Null
}

# Loop over the key algorithms to scan
$keyal_list = @("ssh-rsa", "ecdsa-sha2-nistp256")
foreach ($keyal in $keyal_list) {
   foreach ($address in $clusters_explicit_dns) {
      # Retrieve the SSH public key for the node
      $keyscan_output = ssh-keyscan -t $keyal $address 2>$null

      # Replace the explicit node address with the generic pattern
      $updated_output = $keyscan_output -replace [regex]::Escape($address), $cluster_generic_dns

      # Append the result to the known_hosts file
      Add-Content -Path $known_hosts_path -Value $updated_output
   }
}

Access via Remote Visualization (RCM)

Remote visualization has become popular as an HPC service since it allows to:

visualize the data produced on HPC infrastructure (scientific visualization)
analize and inspect data directy on the HPC infrastructure.
debug and optmization of codes via GUI tools directly on the HPC infrastructure.

All the aforementioned use cases can take advantage of use applications on the server side. The requirements to access to this service are the same for the access to HPC infrastructure. The remote visualization service at Cineca is provided through the Remote Connection Manager (RCM) application. Using this tool you can graphically inspect your data without moving them to your local work station.

Important

It can be used by any user with valid credentials to access CINECA clusters.

Continuous Integration (CI/CD) at CINECA

Continuous Integration, continuous delivery and deployment, also known as CI/CD, is the practice of a constant monitoring of the code development through the activation of an automatic pipeline. Every time a developer applies a change to the code, the automatic pipeline validates it by building the code and running some simple tests (typically unit tests).

CINECA has activated a new service where to run your Continuous Integration (CI/CD) pipelines on CINECA clusters, based on CINECA GitLab service. On Gitlab website there is a detailed documentation about CI/CD. This service is active on Galileo100, and is at the moment in an experimental phase.

Summary

Below we summarize the runners and the tags needed to select the correct one.

Runners	Tags	Notes
2 CPU-only	x86_64,cpu,docker	Up to 24 cpus each. Concurrent execution
2 CPU+GPU	x86_64, docker, nvidia-sm70, nvidia-volta, nvidia-cuda	Each runner has a dedicated GPU. No concurrent execution.

IMPORTANT: If you do not select any tag, the pipeline will never start.

Access via X.509 certificate

An X.509 certificate is issued by a trusted Certificate Authority (CA), which verifies the user’s identity and ensures the certificate is both valid and associated with a real individual. It is used as an authentication mechanism, serving as an alternative to traditional username/password credentials, and helps avoid the need to replicate user accounts across systems. When connecting to a service, the user’s certificate is mapped to a local account, under which all commands and operations are executed.

Important

Access to CINECA clusters no longer requires or supports X.509 certificates for authentication.

However, X.509 certificates may still be necessary for accessing certain external services or resources, such as data repositories, collaboration platforms, or grid computing infrastructures.

The following describes the procedure for obtaining an X.509 certificate and generating a proxy certificate for temporary use.

How to get your X.509 certificate

Users in need of an X.509 certificate can visit the HARICA website. Academic users can select Academic Login and authenticate using their institutional credentials.
In the dashboard’s left-hand menu, click on IGTF Certificate, then select GÉANT Personal Authentication.
Review and accept the terms and conditions, then click Submit Request.

Under Ready Certificates, click Enroll your Certificate. Choose your preferred algorithm (RSA or ECDF), then click Enroll Certificate again. After enrollment, click Download.

A .p12 file (containing your personal certificate and private key) will be downloaded.

How to Use Your X.509 Certificate (Browser and Command Line)

Once you have downloaded your .p12 certificate file, you can either:

Import it into your browser for web-based authentication.
Convert it into PEM format (cert.pem and key.pem) to use it with command-line tools such as grid-proxy-init, voms-proxy-init, or globus-url-copy.