4. Logging in

Please make sure you have enabled your DUO device using UCI’s Duo infrastructure

To connect to an HPC3 login node use:

server name:

hpc3.rcic.uci.edu

login name:

your UCINetID

password:

your password associated with your UCINetID

The following login methods are available, most common listed first:

4.1. Using ssh

SSH is the only way to directly log in to HPC3 for interactive use and we require multi-factor authentication for all password-based logins.

We describe two main methods below.

4.1.1. Method I: Password authentication

Password authentication with automated DUO push on your phone is the most common method for authentication. It requires your phone to have internet access to receive the push notification from DUO and to send your approval/denial back to DUO’s servers.

You access HPC3 via your favorite SSH (SCP, SFTP) client from your laptop and then respond to the DUO app on your phone. HPC3 prompts you for a password and requests to use DUO authentication. The DUO push happens on your phone (or your other DUO-enabled device).

Step by Step

  • You must either be on the campus network or connected to the UCI campus VPN.

  • To use ssh, you need to use one of Terminal applications and depending on a user laptop they are listed in Your laptop applications.

  1. Run ssh command

    Your login name can be specified as ether user@hostname or given with the -l option, for example a user with UCINetID panteater can use one of the following:

    ssh panteater@hpc3.rcic.uci.edu
ssh hpc3.rcic.uci.edu -l panteater

    When prompted for a password please enter password followed by Return key. Note, password will not be visible when typed:

    Password:

  2. Respond to multi-factor authentication prompts

    Next, you will be prompted to enter a code (backup or generated by your DUO device) or request a push to your enrolled DUO-enabled device. A prompt looks similar to:

    Duo two-factor login for panteater

Enter a passcode or select one of the following options:

 1. Duo Push to XXX-XXX-1234

Passcode or option (1-1):

    Type desired option (in this example 1).

    Passcode or option (1-1): 1

  3. Use DUO on your phone

    Now use the DUO app on your phone and respond to the received DUO notification. Press Approve on your DUO app when prompted. If the DUO authentication is successful you will see on your laptop:

    Success. Logging you in...
Last login:  ....

After a successful login you will see a screen similar to the following:

+-----------------------------------------+
|  _             _             _ _ ____   |
| | | ___   __ _(_)_ __       (_) | ___|  |
| | |/ _ \ / _` | | '_ \ _____| | |___ \  |
| | | (_) | (_| | | | | |_____| | |___) | |
| |_|\___/ \__, |_|_| |_|     |_|_|____/  |
|          |___/                          |
+-----------------------------------------+
 Distro:  Rocky 8.7 Green Obsidian
 Virtual: NO

 CPUs:    40
 RAM:     191.8GB
 BUILT:   2022-08-30 14:02

 ACCEPTABLE USE: https://rcic.uci.edu/documents/RCIC-Acceptable-Use-Policy.pdf

[user@login-x:~]$

4.1.2. Method II: Key-based authentication

Please read the Guide to Generating SSH Keys before you begin.

If you choose to use key-based authentication for your login, you have additional responsibilities:

Attention

  • Every user-generated ssh key MUST have a non-empty passphrase. It is a requirement per our Acceptable use policy

  • NEVER add a different user’s ssh public into your authorized_keys file. This is a violation of account sharing.

  • Generate a different private key and password for each device you plan to use for accessing HPC3. For example, if you two different laptops, generate a private key for each laptop.

  • Treat all of your ssh private keys with care. If you are on a shared system (e.g. a lab workstation), make sure that file permissions are set such you (and only you) can read and unlock the key with its passphrase.

  • If you don’t want to keep re-entering your passphrase, you should learn how to manage your ssh keys with the help of ssh agents. This provides a convenience of a “passwordless” ssh key, but has all the security of a password-protected key.

See Tutorials for more SSH links.

Step by Step

  1. Generate your ssh keys

    This step is done once. Depending on your laptop, use the following guides:

    macOS:

    Generate SSH keys on macOS

    Linux:

    Generate SSH keys on Linux

    Windows (PuTTY):

    Generate SSH keys on Windows with PuttyGen

    Windows (Powershell):

    Generate SSH keys on Windows in Powershell

    Once you generate your SSH keys and copy the public key to HPC3:

    • your laptop or workstation from which you are initiating ssh will have a passphrase protected ssh private key and a corresponding public key.

    • your public ssh key is added on HPC3 to your $HOME/.ssh/authorized_keys file.

  2. Use ssh command to login

    Once your keys are setup simply use ssh commands. For example a user with UCINetID panteater can use one of the following commands and provide your ssh passphrase when prompted:

    ssh panteater@hpc3.rcic.uci.edu
ssh hpc3.rcic.uci.edu -l panteater

    The above commands assume using default ssh keys (usually ~/.ssh/id_rsa, .ssh/id_dsa, ~/.ssh/id_ecdsa, ~/.ssh/id_ed25519, and ~/.ssh/identity).

    If your ssh keys have non-default names and you do not have mapping in your ~/.ssh/config file, or if your ssh client does not use this file (FileZilla), then you need to specify ssh key via -i flag:

    ssh -i ~/.ssh/key-to-hpc3 panteater@hpc3.rcic.uci.edu
ssh -i ~/.ssh/key-to-hpc3 hpc3.rcic.uci.edu -l panteater

4.1.3. Ssh and Xforward

If you want X-windows graphics to be forwarded through your ssh connection, then you should use the -X option in your ssh command, for example one of the following:

ssh -X panteater@hpc3.rcic.uci.edu
ssh -X hpc3.rcic.uci.edu -l panteater

Once logged in chck if your enviornment variabl DISPLAY is set:

[user@login-x:~]$ echo $DISPLAY
DISPLAY=localhost:27.0

If the Xforward is enabled in your ssh connection the DISPLAY will be set to a similar string, otherwise the output will be empty (no Xforward).

Note

Mac users must have XQuartz (standard application) installed in order to use XForwarding.

4.2. Using FileZilla and DUO

If you use FileZilla (Windows users) for files transfer you will need to change your login type to interactive in FileZilla Site Manger settings. For exact instructions please see Filezilla Site Manger

site manager settings

Fig. 4.1 Set login type

FileZilla with SSH keys

Sometimes it is more convenient to use SSH keys based authentication (in place of DUO). There are three mechanisms for use of the FileZilla client with SSH-2 keys.

Once you generated your ssh keys see the detailed instructions for the FileZilla SSH key based authentication mechanisms to setup your FileZilla client.

4.3. Using MobaXterm and DUO

Make sure that in your MobaXterm SSH tab -> Advanced ssh settings your Remote Environment is set to Interactive shell:

advanced ssh settings

Fig. 4.2 Advancesd ssh settings

Attention

Do NOT enable Remote monitoring! See MobaXterm monitoring for more info.

4.4. Using VSCode

We do not allow running VSCode on login nodes because vscode usage can result in login nodes becoming unusable by all.

However, many users desire to use VSCode, so RCIC supports the following method so that you can run the VSCode server on compute nodes as a Slurm job and connect to it from your laptop.

VSCode’s remote server support requires ssh. To make things work smoothly, you must set up ssh key-based authentication from your laptop to HPC3.

Attention

Any running VSCode server instances will be removed from login nodes without a notice.
The method provided in this guide is the only way to run VSCode on HPC3.

There are two major parts to running the VSCode server on a compute node and connecting to it from your laptop:

Part 1:

You need to submit a Slurm job specific to VSCode. This starts, on the assigned compute node, a user-specific sshd that is only available to that user.

Part 2:

You need to configure your laptop VSCode client to communicate with this job’s sshd. Once set up properly, VSCode’s remote server development option performs all the work.

Please follow the instruction steps below to setup your VSCode connection on compute nodes.

  1. Use ssh to connect to a cluster, see Method II: Key-based authentication to setup key-based authentication to HPC3. Critical: the ssh-key you setup must be protected with a password.

  2. Submit a batch job to set up a user-level sshd daemon on compute node which is needed for starting VSCode server.

    [user@login-x:~]$ sbatch /opt/rcic/scripts/vscode-sshd.sh
Submitted batch job 21877983

    Slurm returns a job ID (in this example 21877983). Wait for the batch job to start running, the status in squeue output must be R:

    [user@login-x:~]$ squeue -j 21877983
JOBID     PARTITION     NAME       USER   ACCOUNT ST   TIME  CPUS NODE NODELIST(REASON)
21877983   standard vscode-s  panteater panteater  R   0:04     1    1 hpc3-22-09

    Note

    If you need additional resources, you can add the request when you run sbatch. For example, if you require 4 cpus instead of the default: sbatch –cpus-per-task=4 /opt/rcic/scripts/vscode-sshd.sh

  3. Once the job starts running check its output file vscode-sshd-<jobID>.out in the directory where you submitted the job. There will be lines that look similar to:

    Host hpc3-*
  HostName hpc3-22-09
  Port 6666
  ProxyJump panteater@hpc3.rcic.uci.edu
  User panteater
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no

    Note, HostName will show a compute node name and the Port will show a port number. You will need to use them in the next steps.

  4. This step needs to be done once and it will be used for all future invocations of VSCode on HPC3.

    On your laptop in your $HOME there is a directory .ssh which was created when you enabled your ssh keys. Using a text editor, create a file .ssh/config with the following content:

    Host hpc3-*
  HostName %h
  Port XXXX
  ProxyJump UCINetID@hpc3.rcic.uci.edu
  User UCINetID
  UserKnownHostsFile /dev/null
  StrictHostKeyChecking no
    Replace UCINetID with yours, and XXXX with the Port number from vscode-sshd-<jobID>.out.
    Do not change any other other lines!

    If you already have .ssh/config file, simply add the content to it.

    Note

    Each time you start a new vscode-ssh.sh job, the Port number may change. This happens because the the :tt:vscode-sshd.sh` looks for the first available network port within a pre-defined range on the specific compute node assigned to your job. Since that choice is dynamic, it can change for each new vscode-sshd.sh job. Simply edit your local .ssh/config to update the port to the port of your currently-running vscode job that you started in Step 3.

  5. On your laptop start your VSCode application.

    Note, images below show VSCode application for macOS, the Windows version may look slightly different but the concept is the same.

    5.1 Click on the open remote window icon and choose Connect to Host… from the menu

    VSCode connect

    Fig. 4.3 Connect to host

    5.2 Choose + Add new SSH Host… from the menu:

    VSCode connect add ssh host

    Fig. 4.4 Add new ssh host

    5.3 In the Enter SSH Connection Command box, enter the compute node name from
    the output file of your submitted batch job, then press Enter or Escape key:
    VSCode connect to host

    Fig. 4.5 Enter SSH Connection command

    5.4 In the Select SSH configuration file to update menu choose your
    local .ssh/config (use local file from your user area on your laptop):
    VSCode connect to host

    Fig. 4.6 Enter SSH configuration file to update

    5.5 When the window updates press Connect button:

    VSCode connect to host

    Fig. 4.7 Presss connect

    5.6 In a new window you will be asked to provide your ssh passphrase
    (two times), type it where indicated by your Application:
    VSCode setup

    Fig. 4.8 Provide ssh credentials

    Once the authentication is successful you will see the changes on the lower portion of the window, they indicate that the connection is getting established and the server is getting setup (shown with blue outline above). It may take a few minutes for the VSCode to setup the server.

    5.7 Once done, you will see the open remote window icon showing compute node name (in blue
    outline). This means your connection is redy and you can proceed with your work as usual:
    VSCode setup

    Fig. 4.9 Connection is ready

  6. Shutting down your remote VSCode server

    Attention

    The remote start of VSCode leaves the server running long after you have finished your work and closed your remote connection. You need to shutdown your server properly.

    Shutting down your remote server is a simple 2-step process:

    Step 1 on your laptop:

    in VSCode application choose File > Close Remote Connection and follow your application prompts to disconnect from the host.

    Step 2 on login node:

    cancel your VSCode job (by your jobID):

    [user@login-x:~]$ scancel 23383635

    If you don’t cancel your job it will continue consuming your lab or your personal Slurm allocation balance.

  7. Reconnecting to an already running VScode Server

    If you have not shutdown the server in Step 6 above, you simply re-open the connection as you did in Step 5. Please remember, you Slurm job continues to charge your account as long as it consumes resources.