Documentation
SSH

SSH

SSH stands for Secure Shell. It is a commonly used protocol that allows you to connect to a remote machine and execute commands on it. Learn more about SSH here (opens in a new tab).

⚠️

Before proceeding, make sure that you are a registered user of the WATcloud compute cluster. Not registered? Make a request here).

Quick Start

Here's a tool to help you generate a personalized SSH command. This tool will generate a command that you can copy and paste into your terminal. Note that the commands generated by this tool are only tested on Linux and macOS.

We highly recommend you take a look at the Tips and Tricks section if you are looking to use the cluster regularly. It will save time :).

Command Generator

Choose your preferred machine and entrypoint1 below. Your personalized SSH command will be generated and displayed below.

Machine
Compute Cluster Username
SSH Key Path

Results

Below are options for connecting to delta-ubuntu2. Please choose the option that best fits your use case.

wato-bastion -> Cluster Network -> delta-ubuntu2

  1. Run the following command:

    ssh -v -o ProxyCommand="ssh -W %h:%p -i '__SSH_KEY_PATH__' [email protected]" -i '__SSH_KEY_PATH__' [email protected]

UWaterloo VPN -> University Network -> delta-ubuntu2

  1. Connect to the UWaterloo VPN (opens in a new tab)

  2. Run the following command:

    ssh -v -i '__SSH_KEY_PATH__' [email protected]

UWaterloo Campus -> University Network -> delta-ubuntu2

  1. Connect to the UWaterloo network (e.g. on-campus Ethernet or Eduroam Wi-Fi)

  2. Run the following command:

    ssh -v -i '__SSH_KEY_PATH__' [email protected]

The generated commands do not require setting up ssh agent2 or ssh config3. However, you may soon find that setting them up will make your life easier. If you are interested in learning more about these tools, please check out Tips and Tricks and the official documentation linked in the footnotes.

Syntax

The general syntax for connecting to the cluster is:

SSH_KEY_PATH="<path_to_ssh_key>"
SSH_USERNAME="<username>"
SSH_HOST="<hostname>"
ssh -v -i "$SSH_KEY_PATH" "$SSH_USERNAME@$SSH_HOST"

or if you are using a jump host:

SSH_KEY_PATH="<path_to_ssh_key>"
SSH_USERNAME="<username>"
SSH_HOST="<hostname>"
SSH_JUMP_HOST="<jump_host>"
ssh -v -o ProxyCommand="ssh -W %h:%p -i \"$SSH_KEY_PATH\" \"$SSH_USERNAME@$SSH_JUMP_HOST\"" -i "$SSH_KEY_PATH" "$SSH_USERNAME@$SSH_HOST"

Tips and Tricks

Additional SSH Keys

To use additional SSH keys, you have the following options:

  1. Update your profile to add additional SSH keys.
  2. Manually create ~/.ssh/authorized_keys and place your SSH keys in there.You'll need to make sure that this file is present in all machines that you want to connect to4.

SSH Agent

SSH agent is useful for many reasons, for example:

  1. It removes the need to use the -i flag to specify the path to your SSH key.
  2. It allows you to use SSH agent forwarding (opens in a new tab).

You can use SSH agent as follows:

# Start an SSH agent if it's not already running
[[ -z "$SSH_AUTH_SOCK" ]] && eval "$(ssh-agent -s)"
# Add your SSH key to the agent. Replace ~/.ssh/id_rsa with the path to your SSH key.
ssh-add ~/.ssh/id_rsa
# Connect to the cluster
ssh -v "<ssh_username>@<ssh_host>" # This is the same as ssh -v -i ~/.ssh/id_rsa "<ssh_username>@<ssh_host>" without SSH agent
# or if you are using a jump host
ssh -v -o ProxyCommand="ssh -W %h:%p \"<ssh_username>@<ssh_jump_host>\"" "<ssh_username>@<ssh_host>"

~/.ssh/config

If you find yourself using the same SSH command over and over again, you can use ~/.ssh/config to simplify your life.

For example, if you find yourself using the following command often:

ssh -v -o ProxyCommand="ssh -W %h:%p -i \"<ssh_key_path>\" \"<ssh_username>@<ssh_jump_host>\"" -i "<ssh_key_path>" "<ssh_username>@<ssh_host>"

you can add the following to your ~/.ssh/config:

Host <ssh_jump_host>
    HostName <ssh_jump_host>
    User <ssh_username>
    IdentityFile <ssh_key_path>
 
Host <ssh_host>
    HostName <ssh_host>
    User <ssh_username>
    IdentityFile <ssh_key_path>
    ProxyJump <ssh_jump_host>

and then simply run:

ssh -v <ssh_host>

A real-world example of this is:

Host bastion
    HostName bastion.watonomous.ca
    User alex
    IdentityFile ~/.ssh/id_rsa
 
Host derek3-ubuntu2
    HostName derek3-ubuntu2.cluster.watonomous.ca
    User alex
    IdentityFile ~/.ssh/id_rsa
    ProxyJump bastion
ssh -v derek3-ubuntu2

Footnotes

  1. An entrypoint is a service or location that you connect to or be at when you connect to the cluster. This is necessary because the cluster is behind a firewall and you cannot connect to it directly.

  2. SSH agent (opens in a new tab) is a program that runs in the background and stores your SSH keys. It comes with neat features like SSH agent forwarding (opens in a new tab) that allows you to use your local SSH keys on remote machines.

  3. SSH config (opens in a new tab) is a configuration file that allows you to simplify your SSH commands.

  4. For example, if you use Bastion to connect to the cluster, you'll need to make sure that ~/.ssh/authorized_keys is present on both Bastion and the machine you intend to connect to.