Research IT

Log in to Nova with SSH

Using SSH to Connect to Nova

While Nova OnDemand provides a convenient way to log in to Nova using a web browser, many users prefer to use a dedicated SSH client, especially when doing a lot of work from the command line.  These instructions will show you how to get set up to login to Nova using SSH instead of your web browser.

Two Options for Authentication 

Nova now supports two authentication methods for SSH, Time-based One Time Passwords (TOTP), and SSH Public Keys:

    1. Time-based One Time Passwords

Time-based One Time Password (TOTP) provides a second factor method for authenticating SSH users on Nova (in addition to the user's ISU password).   With TOTP, you enter a one-time, 6-digit password (aka verification code) generated by an application such as Microsoft Authenticator.  This method has been the standard way to authenticate to SSH for several years.   See How to Set Up Time-based One Time Password authentication for more details.

    2.  SSH Public Keys

SSH Public Key authentication has recently been added to Nova.  Public key authentication does not use TOTP keys.  Instead, you authenticate by providing a passphrase that unlocks an SSH key pair that you create.  Using SSH Public Keys is optional, but some users prefer it to using an Authenticator app.   You must first be connected to the ISU VPN whether you are on or off campus.    See How to Set Up Public Key Authentication for more details.

NOTE:   Even if you are planning to use Public Key authentication for SSH, you must first set up Time-based One Time Password (TOTP) authentication.   It will be used for copying your public key to Nova.

 How to Set Up Time-based One Time Password Authentication

Steps:

  1. Must Be On-Campus or on VPN
  2. Install an Authenticator App
  3. Choose an SSH Client (OpenSSH Preferred)
  4. Login to Open OnDemand to Create Your MFA Key.
  5. Install MFA Key in MS Authenticator
  6. Connect to Nova head node

Must Be On-Campus or on VPN

To connect to Nova you must either be on-campus or connected to the campus VPN (https://vpn.iastate.edu).

Install an Authenticator App

You will need an Authenticator App on your phone (or your desktop) that can be used to generate your time-based verification code that Nova uses for Mutli-Factor Authentication (MFA).  You may already have MS Authenticator installed for other ISU services.  That is recommended.  Google Authenticator also works.

Login to Open OnDemand to Set Up Your MFA Key

In order to connect to Nova via SSH you must have an MFA key for multi-factor authentication.   This is key is created for you automatically the first time you log in to Nova OnDemand.    This will also cause an e-mail to be sent to you with instructions for adding the MFA key to your authenticator app.    

Choose an SSH Client (OpenSSH Preferred)

We strongly recommend using a fairly recent version of OpenSSH.   If you have a Mac or Linux computer, you already have the ssh client from OpenSSH installed.  If you open a Terminal window and type:

$ ssh -V
it should return something like:
OpenSSH_8.7p1, OpenSSL 3.0.7 1 Nov 2022

This shows that this particular ssh program is version 8.7p1 of OpenSSH, which is a fairly recent version.  

If you are using Windows, we recommend installing Windows Subsystem for Linux (WSL) from Microsoft.   WSL provides a familiar Linux experience that can be useful when using Nova. 

Install MFA Key on MS Authenticator

The Nova MFA key for is different from the one used by https://login.iastate.edu .
Follow the steps below to add your Nova key to MS Authenticator (other authenticator apps work similarly):

  1. Open MS Authenticator and click the + upper right
    Add new Item to authenticator with plus
  2. Click Work or school account
    Pick Work or school account
  3. Click "Scan QR code"
    Pick Sign in or Scan QR code
    1. You may be asked to give permission to use the camera so it can scan the QR code, you don't have to allow it, but it is quicker and more accurate to use the QR Code.
    2. Scan the code from the email or enter the seed code manually.
    3. You should now see the 6 digit authentication codes Nova will be asking for.
      Authentication code for Nova

  4. You should now be able to login to nova using Nova MFA code and ISU password. Note that neither your Verification code or password will print out.

    $ ssh your-netid@nova.its.iastate.edu
(your-netid@nova.its.iastate.edu) Verification code:
(your-netid@nova.its.iastate.edu) Password:
Last login: Fri Sep 27 13:19:50 2024 from 129.186.XX.XXX

Connect to Nova head node

From Terminal or console window, use one of the following commands to connect to Nova:

$  ssh <netid>@nova.its.iastate.edu       (The normal Nova head node)

or

$  ssh <netid>@nova-vscode.its.iastate.edu   (Head node for VS-code users)
 

where the <netid> is your ISU NetID.

How to Set Up SSH Public Key Authentication

Steps:

  1. Must Be Connected to VPN
  2. Set Up One-Time Password Authentication First
  3. Choose an SSH Client
  4. Create a Public Key Pair on Your Computer
  5. Add the Public Key to Your Authorized Keys File on Nova
  6. Start SSH Agent
  7. Login to the Actual Head Nodes
  8. Configure SSH Control Master (Optional)

Must Be Connected to VPN 

In order to use this login method, you must be connected to the ISU VPN.  (The ISU VPN adds a layer of verification to your connection that is important for security).

Set Up Time-based One Time Passwords First

You will need to set up TOTP authentication before setting up SSH Public key authentication.  It is needed for transferring your SSH key to Nova.

Choose an SSH Client

We recommend using a relatively current version of OpenSSH to implement Public Key authentication.  If you are using Mac or LInux, you should already have the OpenSSH package installed.   If you are using Windows, we strongly recommend that you install WSL which includes OpenSSH.

Create a Public Key Pair

A public key pair consists of two files:  the private key, and the public key.   You will create the key pair on your computer and then add the public key to the authorized_keys file located in the .ssh folder of your Nova home directory.

Use the  ssh-keygen program to generate a key pair.  An example is shown below.  The -f option sets the base file name of the key pair (The example uses the name nova-pubkey).  The -C option adds a comment to the public key which is really just human readable text to help you identify the key.   The comment is usually is often in a form like <username>@<host>.    

You will be prompted to enter the passphrase for the key.  The passphrase will be used to verify your identify when you use it to log in over SSH.   Note:  Do not use a null (empty) passphrase.  Otherwise, if someone steals your private key file, they could log in as you without providing a passphrase.  A typical ssh-keygen dialog is shown below: 

$ ssh-keygen -f ~/.ssh/nova-pubkey -C "your_netid@nova"   # use your actual netid in place of your_netid
Generating public/private rsa key pair.
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in ~/.ssh/nova-pubkey
Your public key has been saved in ~/.ssh/nova-pubkey.pub
The key fingerprint is:
 (full signature not shown)

 

This will create two files in the your ~/.ssh folder:  nova-pubkey (the private key) and nova-pubkey.pub (the public key).   It is important to keep these files safe.

Add the Public Key to Your Authorized Keys File on Nova

The following command can be used to copy the public key you created above to your ~/.ssh/authorized_keys file on Nova.

$ ssh-copy-id -i nova-pubkey.pub <your_netid>@nova.its.iastate.edu

Enter your ISU Netid in place of <your_netid> above.   Note that for this step, you will be prompted to supply your Time-based One Time Password and ISU password (Since your SSH key is not yet in place on Nova).

Start SSH Agent (Optional)

When you are working from the command line on your own computer, it would be nice to be able to verify your SSH key once per session.  The ssh-agent utility can do that for you.   For example, if you've created an SSH key pair called nova-pubkey in your ~/.ssh directory, you can start a new shell session with ssh-agent and then use ssh-add to select the keys you want to be verified for that session.  A simple example is useful:
 

$ ssh-agent /bin/bash

$ ssh-add ~/.ssh/nova-pubkey
Enter passphrase for ~/.ssh/nova-pubkey:
Identity added: /home/jedicker/.ssh/nova-pubkey (jedicker@nova-ssh)

$ ssh-add -l
3072 SHA256:6OWVp0ikLRbLlsPavECimTsHs6fk8duNGbKmKHvAzFR0 jedicker@nova-ssh (RSA)

The ssh-agent /bin/bash command starts a new bash shell session that can store your SSH verification credentials.  The ssh-add ~/.ssh/nova-pubkey command allows you to cache the verification of an SSH key (called an Identity) so you only have to verify it once per session. This can be a big time saver is you log in multiple times a day.

Login to the Actual Head Node Servers

To log in with SSH keys, we can't log in to nova.its.iastate.edu because nova.its.iastate.edu is not a single server.   We must log in to one of the actual servers:  nova-login-1.its.iastate.edu or nova-login-2.its.iastate.edu.  
So, at this point, we have created our SSH keys, copied to Nova, and verified the key with the passphrase.  Now we can log in to the head nodes like so:

$ ssh nova-login-1.its.iastate.edu

or 

$ ssh nova-login-2.its.iastate.edu
 

Configure the SSH Control Master

The SSH Control Master is a very convenient setting with SSH that allows you to share SSH authentication across multiple SSH sessions.  You authenticate once, and any additional connections from another shell on your computer to the same destination can piggy-back on the previously authenticated connection.  To configure the Control Master settings on your computer, add the following lines to the file ~/.ssh/config :

ControlMaster auto 
ControlPath ~/.ssh/%r@%h:%p
ControlPersist 10h

The settings above tell SSH that the authenticated channel should persist for up to 10 hours on your computer.