Research IT

Setup SSH tunnel using a Jump Host

Table of Contents

Summary

The following are instructions for setting up a basic SSH tunnel to a compute node in the Nova cluster, using nova.its.iastate.edu as a jump host.  The instructions are primarily targeted at users who do not use Microsoft Visual Studio Code and/or do not have access to the VS Code remote tunnel extension, but they should work with any IDE that supports SSH, including Microsoft Visual Studio Code.

I. Preparation

  1. Open or create the SSH configuration file on your local machine.
  • For Linux and macOS users, the file is located at ~/.ssh/config. If it’s not there, then create a file with that name.
  • For Windows users, the file is located at C:\Users\<username>\.ssh\config. <username> is your local account name, which may or may not be the same as your NetID.  If the file is not present, then create a file with that name.
  1. Add the following text to the config file.  On the User line, make sure to replace <Net-ID> with your actual ISU Net-ID.
Host nova-ssh-tunnel
    HostName localhost
    User <Net-ID>
    Port 2222

Host nova.its.iastate.edu
    ServerAliveInterval 300

Once the config file is setup correctly, this step will not need to be repeated.

II. Allocate a session on a compute node

This can be done using either the command line on Nova, or using the 'VS Code Tunnel' app on Nova OnDemand.  The latter method is used solely to get a session on a compute node, the Microsoft Tunnel information is not used.  Examples of both methods are shown below.

A. Nova command line

  1. Connect to the VPN if not on the campus network.

  2. Using a terminal on macOS or Linux, Powershell on Windows, connect to Nova.

    ssh <netid>@nova.its.iastate.edu

  3. Use the salloc command to allocate a session on a compute node.  Requested resources can be adjusted as necessary. 

    salloc --nodes=1 --ntasks=16 --mem=32G --time 04:00:00

  4. Once on the compute node, make note of the host name (nova22-45 in the screenshot) as it will be used later in the process.  The host name will be shown in the prompt.

    Using Nova CLI to request a compute node.

  5. Proceed to Step III.

B) Nova OnDemand

  1. Connect to the VPN if not on the campus network.
  2. Using a browser, navigate to: https://nova-ondemand.its.iastate.edu

  3. Click on "Interactive Apps" in the top menu, select "VS Code Tunnel"

    Select VS Code Tunnel option.

  4. On the "VS Code Tunnel" page, the defaults should be adequate, but you can make changes based on your requirements.  Be sure to populate the "Working Directory" field with the correct value, then click "Launch". 

    VS Code Tunnel page.

  5. The next page is similar to the ones shown below (screenshots are cropped to show only the relevant information). The job will start out "Queued", but after a short pause it should transition to "Running".  Once the job is running, make note of the host name as it will be used later (nova18-wide-1 in the screenshot).  The Microsoft Tunnel information (not shown below) is not used and can be ignored.

    Queue VS Code Tunnel job.

VS Code Tunnel running

III. Start the SSH tunnel on your local computer

  1. Connect to the VPN if not on campus network.
  2. Open a new terminal on macOS or Linux, Powershell on Windows.

  3. Enter the following command, substituting your NetID and the host name of the compute node to which you were assigned. You will be prompted once for your verification code and twice for your ISU password, the first for nova.its.iastate.edu and the second for the compute node.

    ssh -J <netid>@nova.its.iastate.edu -L 2222:localhost:22 <your_netid>@<compute_node>

    To avoid being prompted to add the host key the first time you connect to a compute node, you can append the below option to the above command.

    -o StrictHostKeyChecking=accept-new

    Example output from the tunnel command.

IV.  Connect your IDE to the tunnel

  1. Using the method supported by your IDE, connect it to the Nova compute node by giving it the name of the tunnel you used in the ssh config file.
nova-ssh-tunnel

It may prompt you once for your ISU password, to authenticate with the compute node.  

 

At this point, you should be able to begin your work.  The IDE you use may have additional requirements that must be met before it can be used.  Please check the documentation for the IDE.

V. Once you've completed your work, close the IDE's remote connection

  1. Using the instructions provided by the IDE documentation, close the remote connection.

VI. Cancel your compute node allocation

A. Nova command line

  1. You should still be logged into the compute node (Step III a), so you can just type 'exit' twice to close your connections to the compute node and the login node (nova.its.iastate.edu).  This will also terminate the SSH tunnel.

B. Nova OnDemand

If you still have the OnDemand Interactive Sessions page open, just click the "Cancel" button for the Running job. Otherwise:

  1. Connect to the VPN, if not on the campus network.
  2. Using a browser, navigate to: https://nova-ondemand.its.iastate.edu
  3. Click on "My Interactive Sessions" in the top menu.

  4. Then click "Cancel" to cancel the Running job.  This will also terminate the SSH tunnel.

    Cancel VS Code Tunnel job.

  5. (Optional) Delete the job from the Interactive Session page by clicking the "Delete" button after the job has transitioned to "Completed" status.

    Delete VS Code tunnel job.